# Automation Optimizer > 分析 Issue Flow 某个阶段为何需要多轮人工介入，依据完整 TaskEvent 找出 Agent 首次未完成的真实原因，选择可长期消除原因的改进方式，并生成结构化 Optimization Plan JSON。适用于 triage、plan、build 或 review 阶段 Turns 大于 1 后发起的自动化优化分析。 - Skill: `lianjiatech/automation-optimizer` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add lianjiatech/automation-optimizer` - Raw SKILL.md: https://api.skillmd.com/api/skills/lianjiatech/automation-optimizer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: lianjiatech (https://skillmd.com/u/lianjiatech) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/lianjiatech/automation-optimizer --- # 自动化优化分析 分析 Agent 为什么没有在首次 Task 中完成阶段目标，并设计能够减少同类人工介入的改进。人工评论描述的是这次需要纠正什么，只能作为线索，不能直接改写成根因或长期规则。 从优化 Issue 正文读取来源 Issue、待优化阶段及其 Turns。先读取 [Optimization Plan 产物协议](references/optimization-artifact.md)。本任务只生成分析产物，不实施改进方案。 ## 获取执行上下文 执行一次脚本，获取来源 Issue 整个生命周期的 Task： ```bash node .agentrix/plugins/issue-flow/skills/automation-optimizer/scripts/task-context.cjs \ --issue <来源 Issue 编号> ``` 脚本输出临时索引文件以及 `triage`、`plan`、`build`、`review` 阶段文件。每个阶段文件包含该阶段全部 Task 和全部 `events`。不要筛选事件类型，不要把临时文件放入仓库或提交到 Git。 先读索引和优化 Issue 指定的阶段。只有当前阶段不足以解释问题来源或传播过程时，才读取相关上下游阶段。某阶段没有 Task、事件不完整或来源 Issue 无法确定时，不得猜测根因，应在 Plan 中记录缺失证据及其影响。 ## 分析原则 - 分析“为什么会发生”，不要只总结“哪里做错了”。 - “考虑不完整”“缺少验证”“没有覆盖边界”“理解不足”只是直接原因，不能作为最终根因。 - 不得把后续人工评论改写成祈使句后称为根因或规范。 - 不要用后续评论倒推首次执行时不可能知道的要求。 - 每个原因都必须由 `taskId + sequence`、仓库代码、项目文档或测试事实支撑。 - Task ID、sequence 和事件流水只用于分析取证，不写入最终产物的目标与原因。 - 不强制为每个问题生成规范；先确定原因，再选择最合适的改进去向。 - 优先消除诱发错误的结构，而不是要求 Agent 下次“更仔细”。 ## 分析步骤 ### 1. 定义首次完成标准 根据首次 Task Message、来源 Issue、当时仓库内容和已有项目约定，确定该阶段首次 Task 应完成的产物、操作、验证和结束状态。 ### 2. 还原首次判断 按 `sequence` 还原目标阶段的初始输入、Agent 的理解和操作、工具结果、首次交付、人工纠正及最终结果。对每次人工介入回答： 1. 首次结果与最终正确结果有什么差异？ 2. Agent 在首次交付前作出了什么错误判断或遗漏了什么决策？ 3. Agent 当时看到了哪些证据，为什么会认为原判断足够？ 4. 正确信息当时是否存在于 Issue、代码、测试、项目说明或项目文档中？ 5. 如果信息存在，Agent 是否搜索、读取并正确应用；如果没有，为什么没有找到或为什么选择猜测？ 6. 如果问题可机械验证，现有测试或检查为什么没有暴露它？ 7. 哪个最早的机制能够稳定消除该原因，而不只是提醒以后注意？ 8. 采用该改进后，这次人工介入是否自然不再需要？ ### 3. 检查项目知识与文档 只要问题涉及业务背景、项目约定、已有能力或历史决策，必须检查仓库中的 README、文档目录、ADR、架构说明及相关代码注释，并核对 TaskEvent 中 Agent 是否读取过它们。区分： - 信息不存在； - 信息存在但不完整、错误、过期或互相冲突； - 信息正确但难以发现； - Agent 已读取但理解或应用错误； - Agent 没找到答案后未经确认直接猜测。 不要在已有文档可以补全时重复写项目规范，也不要用项目规范复制业务文档。 ### 4. 按需进行跨阶段分析 如果当前阶段使用了上游产物、人工纠正指向上游遗漏，或多个待优化阶段可能属于同一因果链，再读取相关阶段。分别保留各阶段证据，并确定问题最早产生、传播和暴露的位置。 如果前一阶段已经产生了正确决策，但后续 Task 实际没有收到、收到错误版本或关联到错误 Task，判定为 Issue Flow 上下文传递 Bug，向开发者反馈；不得用项目规范掩盖。若上下文已经正确注入但 Agent 没有使用，再继续分析其执行、提示或信息发现原因。 ## 选择改进去向 根据证据选择一项或多项改进，不得预设所有问题都修改 `.issue-flow/instructions.md`。 ### 项目内改进 - **需求表达或业务决策缺失**：改进 Issue 模板、需求说明或决策记录；不能从事实唯一推导的选择仍由人决定。 - **业务知识缺失**：补充项目业务文档、术语、状态规则或历史决策。 - **已有文档不完整、错误或难发现**：优先修正文档，并改善索引、命名或权威来源说明。 - **可泛化的项目执行方法缺失**：修改 `.issue-flow/instructions.md`，写适用条件、分析方法和完成证据，不写当前任务专属检查清单。 - **稳定行为缺少确定性验证**：补充或修正单元测试、集成测试、类型检查、checker 或 validation。 - **代码结构容易诱发错误**：重构重复判断、隐式副作用、分散复制或多重权威来源，从结构上消除误用。 - **项目工具能力不足**：改进项目内脚本、CLI 或辅助工具，使必要信息可获取、操作可执行、结果可验证。新增可供 Agent 使用的工具时，同时在 `.issue-flow/instructions.md` 中声明其适用场景、调用入口、必要输入、输出和使用边界，确保后续任务能够发现并正确使用；不要在项目说明中复制工具实现细节。 项目级执行规范统一写入 `.issue-flow/instructions.md`。除该文件外，不得生成修改 `.issue-flow/` 下任何文件的方案。若根因属于 `.issue-flow` 体系内的流程、Skill、模板或脚本本身，生成 Issue Flow 开发者反馈，不作为当前项目改进方案。 ### 项目开发者建议 如果改进需要当前项目维护者补齐仓库外或人工管理的前置能力，而 Agent 无法在本次优化中安全实施，例如构建环境、工具链、凭据、组织级基础设施或项目级运行配置，生成 `kind: project-developer-feedback` 的 Proposal： - 明确当前项目开发者需要完成什么，以及完成后 Agent 如何发现和使用该能力； - 不生成 `issue`，页面只展示建议内容和验证方式； - 不提供复制、创建 Issue 或忽略操作，也不阻塞优化流程终态。 只要改动能够由 Agent 在当前仓库中实施，就仍使用 `project-change`，不得用项目开发者建议逃避可执行改进。 ### Issue Flow 开发者反馈 Issue Flow 未传递阶段上下文、关联错误 Task、注入错误版本，或者 `.issue-flow` 体系内的流程、Skill、模板、脚本等存在缺陷时，形成 Issue Flow 开发者反馈。至少记录： - 预期行为与实际行为； - 相关阶段、Task ID 和事件证据； - 缺失或错误的上下文； - 对首次完成的影响； - 可复现条件。 不得把平台缺陷改写成项目长期规则，也不得声称项目改动已经修复底层问题。 Issue Flow 开发者 Bug 反馈必须生成 `kind: issue-flow-feedback` 的 Proposal，Issue 草稿使用 `type::bug` 与 `flow::triage`。 能够通过当前项目的仓库配置、构建入口、运行环境声明或项目维护动作解决的问题，不属于 Issue Flow 开发者反馈；应生成 `project-change` 或 `project-developer-feedback`。只有问题位于 `.issue-flow` 体系内的流程、Skill、模板、脚本等公共能力时，才反馈给 Issue Flow 开发者。 ### 不形成长期改动 - 偶发网络、权限、服务或运行环境失败：记录证据；只有存在稳定恢复模式时才设计重试或可观察性改进。 - 无法自动消除的真实业务选择：说明为什么必须保留人工决策。 - 当前 Issue 的一次性偏好：记录为本次需求，不泛化。 ## 泛化项目规范 只有根因属于可重复出现的项目执行方法缺口时，才写入 `.issue-flow/instructions.md`。规范应描述一类任务的处理方法，而不是复制本次验收项： - 写清适用条件； - 写清分析或执行方法； - 写清可观察的完成证据； - 删除本次类名、接口名、字段名、状态码和具体用例后，仍然清晰、可执行； - 优先修改已有规范，避免重复或冲突。 如果删除任务专属名词后规则失去意义，它仍是本次修复准则，不是可沉淀规范。 ## Optimization Plan 产物只包含 `target` 与 `proposals`。`target.summary` 用一句话简述当前问题；`target.cause` 用 1–3 条短句概括根本原因，不写取证过程。Agent 可在仓库内执行的改动使用 `project-change`；需要当前项目维护者补齐外部能力时使用 `project-developer-feedback`；`.issue-flow` 体系内的公共能力缺陷使用 `issue-flow-feedback`。只有 `project-developer-feedback` 不携带 Issue 合同。多个阶段属于同一因果链时可以合并根因，但不同落点仍拆成独立 Proposal。 Proposal 只保留具体方案和验证方式。证据用于得出结论，不在产物中堆叠执行流水账。 ## 硬性约束 - 不得只根据 Turns 数量推断根因。 - 不得忽略非消息类型的 TaskEvent。 - 不得在没有事件证据时补写执行过程。 - 不得把完整会话、敏感数据或临时上下文文件提交到仓库。 - 不得强制把所有问题转换成 `.issue-flow/instructions.md`。 - 不得用项目规则掩盖 Issue Flow 上下文传递或平台能力 Bug。 - 不得在本分析任务中实施优化改动。