octocode-documentation-writer

仓库文档生成器

可用于生产环境的 6 阶段流水线，具备智能编排、研究优先验证和无冲突的文件所有权。

此命令通过 6 个阶段编排专用 AI Agent，分析代码仓库并生成全面的文档： ## 运行时兼容性

• Opus、Sonnet 和 Haiku 等模型标签是角色提示，而非硬性要求。请根据任务将它们映射到可用的最强主机模型。
• Task 表示主机运行时的并行子 Agent 机制。如果主机无法运行真正的并行子 Agent → 那么按顺序执行相同的工作，并保留文件的独占所有权。
• 本文档中的伪代码块是行为模板。请根据当前运行时调整辅助函数名称、文件 API 和重试辅助函数，而不要将它们视为字面 API。
• 会话产物位于 .octocode/documentation/{session-name}/ 下。除非另有说明，下面的短名称（如 analysis.json）均指该会话目录中的文件。

**发现与分析**（阶段 1） Agent 角色：高能力推理模型 并行：4 个并行 Agent 内容：分析语言、架构、流程和 API 输入：仓库路径 输出：`analysis.json`

<phase_2> 工程师问题（阶段 2） Agent 角色：高能力推理模型 内容：根据分析生成全面的问题 输入：analysis.json 输出：questions.json </phase_2>

<phase_3> 研究 Agent（阶段 3）🆕 Agent 角色：快速研究/执行模型 并行：动态调整（基于问题数量） 内容：深入进行代码取证，以证据回答问题 输入：analysis.json + questions.json 输出：research.json </phase_3>

<phase_4> 编排器（阶段 4） Agent 角色：高能力推理模型 内容：按文件目标对问题分组，并为编写人员分配文件的独占所有权 输入：questions.json + research.json 输出：work-assignments.json（基于文件的并行编写任务分配） </phase_4>

<phase_5> 文档编写人员（阶段 5） Agent 角色：快速写作模型 并行：1-8 个并行 Agent（根据工作量动态调整） 内容：综合研究结果并编写全面的文档，同时确保文件的独占所有权 输入：analysis.json + questions.json + research.json + work-assignments.json 输出：documentation/*.md（16 份核心文档、5 份必需文档，以及由编写人员负责的补充文件；QA-SUMMARY.md 在阶段 6 生成） </phase_5>

<phase_6> QA 验证器（阶段 6） Agent 角色：快速验证模型 内容：使用 LSP 驱动的验证来检查文档质量 输入：documentation/*.md + analysis.json + questions.json + research.json 输出：qa-results.json + QA-SUMMARY.md </phase_6>

使用主机的子 Agent 机制，通过 MCP 工具（`localSearchCode`、`lspGotoDefinition`、`lspCallHierarchy`、`lspFindReferences`）探索代码。请根据能力选择模型级别，而不要使用硬编码的模型名称。

<mcp_discovery> 开始前，检测可用的研究工具。

检查：是否有 octocode-mcp 作为 MCP 服务可用？ 查找 Octocode MCP 工具（例如 localSearchCode、lspGotoDefinition、githubSearchCode、packageSearch）。

如果 Octocode MCP 存在，但本地工具没有返回结果：

建议：“如需研究本地代码库，请在 Octocode MCP 配置中添加 ENABLE_LOCAL=true。”

如果未安装 Octocode MCP：

建议：“安装 Octocode MCP 以进行更深入的研究：

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["-y", "octocode-mcp"],
      "env": {"ENABLE_LOCAL": "true"}
    }
  }
}

然后重启编辑器。”

使用任何可用工具继续操作——不要因配置问题而停下来。 </mcp_discovery>

文档流程： analysis.json → questions.json → research.json → work-assignments.json → 文档（无冲突！）

---

⚠️ 严重警告：并行 Agent 执行

<parallel_execution_critical importance="maximum">

停下。把这段读两遍。

1. 规则

使用宿主支持的最强并行机制。 如果运行时支持并发 Task 调用，优先采用单条消息扇出。

2. 禁止行为

禁止： 宿主实际按顺序执行时，声称任务是并行运行的。 原因： 虚假的并发声明会掩盖运行时限制，也会让故障更难排查。

3. 必需的回退方案

如果运行时无法真正扇出并行任务：

• 按顺序运行相同范围的工作任务
• 保持文件归属互斥
• 保持相同的阶段边界和汇总步骤
• 告知用户执行处于顺序回退模式

4. 必需的确认

在启动任何并行阶段（1、3、5）之前，你必须确认：

• 宿主能够运行所选的扇出模式
• 这些并行 Agent 之间不存在依赖关系
• 每个 Agent 的工作范围互斥（不会发生文件冲突）

<correct_pattern title="✅ 正确：单条回复并发启动所有 Agent">

// In ONE assistant message, include ALL Task tool invocations when the host supports it:
Task(description="Discovery 1A-language", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1B-components", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1C-dependencies", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1D-flows", subagent_type="general-purpose", prompt="...", model="opus")
// ↑ All 4 execute SIMULTANEOUSLY

</correct_pattern>

<wrong_pattern title="❌ 错误：顺序调用会失去并行性">

// DON'T DO THIS when the host supports concurrency - each waits for previous to complete
Message 1: Task(description="Discovery 1A") → wait for result
Message 2: Task(description="Discovery 1B") → wait for result
Message 3: Task(description="Discovery 1C") → wait for result
Message 4: Task(description="Discovery 1D") → wait for result
// ↑ 4x slower! No parallelism achieved

</wrong_pattern>

</parallel_execution_critical>

---

执行流程图

flowchart TB
    Start([/octocode-documentation-writer PATH]) --> Validate[Pre-Flight Validation]
    Validate --> Init[Initialize Workspace]

    Init --> P1[Phase 1: Discovery+Analysis]

    subgraph P1_Parallel["🔄 RUN IN PARALLEL (4 agents)"]
        P1A[Agent 1A:<br/>Language & Manifests]
        P1B[Agent 1B:<br/>Components]
        P1C[Agent 1C:<br/>Dependencies]
        P1D[Agent 1D:<br/>Flows & APIs]
    end

    P1 --> P1_Parallel
    P1_Parallel --> P1Agg[Aggregation:<br/>Merge into analysis.json]
    P1Agg --> P1Done[✅ analysis.json created]

    P1Done -->|Reads analysis.json| P2[Phase 2: Engineer Questions<br/>Single High-Capability Agent]
    P2 --> P2Done[✅ questions.json created]

    P2Done -->|Reads questions.json| P3[Phase 3: Research 🆕<br/>Parallel Research Agents]
    
    subgraph P3_Parallel["🔄 RUN IN PARALLEL"]
       P3A[Researcher 1]
       P3B[Researcher 2]
       P3C[Researcher 3]
    end
    
    P3 --> P3_Parallel
    P3_Parallel --> P3Agg[Aggregation:<br/>Merge into research.json]
    P3Agg --> P3Done[✅ research.json created<br/>Evidence-backed answers]

    P3Done -->|Reads questions + research| P4[Phase 4: Orchestrator<br/>Single High-Capability Agent]
    P4 --> P4Group[Group questions<br/>by file target]
    P4 --> P4Assign[Assign file ownership<br/>to writers]
    P4Assign --> P4Done[✅ work-assignments.json]

    P4Done --> P5[Phase 5: Documentation Writers]
    P5 --> P5Input[📖 Input:<br/>work-assignments.json<br/>+ research.json]
    P5Input --> P5Dist[Each writer gets<br/>exclusive file ownership]

    subgraph P5_Parallel["🔄 RUN IN PARALLEL (1-8 agents)"]
        P5W1[Writer 1]
        P5W2[Writer 2]
        P5W3[Writer 3]
        P5W4[Writer 4]
    end

    P5Dist --> P5_Parallel
    P5_Parallel --> P5Verify[Verify Structure]
    P5Verify --> P5Done[✅ documentation/*.md created]

    P5Done --> P6[Phase 6: QA Validator<br/>Single Validation Agent]
    P6 --> P6Done[✅ qa-results.json +<br/>QA-SUMMARY.md]

    P6Done --> Complete([✅ Documentation Complete])

    style P1_Parallel fill:#e1f5ff
    style P3_Parallel fill:#e1f5ff
    style P5_Parallel fill:#ffe1f5
    style P4 fill:#fff3cd
    style Complete fill:#28a745,color:#fff

并行执行规则

<execution_rules> 停止。 确认并行启动要求。 必需： 有可用宿主并行能力时，必须使用。 回退： 只有宿主无法运行真正的并行工作时，才允许按顺序执行。 <agent_count>4</agent_count> 发现与分析 <spawn_instruction>优先采用单条回复扇出；否则按顺序回退执行，并保持工作范围互斥</spawn_instruction> 宿主支持时，并发运行全部 4 个 Agent；否则按顺序回退执行 汇总前，等待全部 4 个 Agent 完成 必须将 4 份部分 JSON 汇总到 analysis.json

<phase name="2-questions" type="single" critical="true" spawn="sequential">
    <agent_count>1</agent_count>
    <description>生成工程师问题</description>
    <spawn_instruction>使用单个 Agent，等待其完成</spawn_instruction>
</phase>

<phase name="3-research" type="parallel" critical="true" spawn="single_message">
    <gate>
    **停止。** 确认并行启动要求。
    **必需：** 有可用宿主并行能力时，必须使用。
    **回退：** 只有宿主无法运行真正的并行工作时，才允许按顺序执行。
    </gate>
    <agent_count_logic>
        <case condition="questions &lt; 10">1 个 Agent</case>
        <case condition="questions &gt;= 10">Ceil(questions / 15)</case>
    </agent_count_logic>
    <description>收集证据</description>
    <spawn_instruction>优先采用单条回复扇出；否则按顺序回退执行，并保持批次边界</spawn_instruction>
    <rules>
        <rule>启动前先将问题拆分成多个批次</rule>
        <rule>宿主支持时，并发运行所有研究 Agent；否则按顺序回退执行</rule>
        <rule>将研究结果汇总到 research.json</rule>
    </rules>
</phase>

<phase name="4-orchestrator" type="single" critical="true" spawn="sequential">
    <agent_count>1</agent_count>
    <description>协调与分配</description>
    <spawn_instruction>使用单个 Agent，等待其完成</spawn_instruction>
    <rules>
        <rule>为写入者分配互斥的文件归属</rule>
        <rule>将研究结果分发给相关写入者</rule>
    </rules>
</phase>

**停止。** 验证并行启动要求。 **必需：** 如果可用，请使用主机并行处理。 **回退方案：** 仅当主机无法运行真正的并行任务时，才允许顺序执行。 1 个 Agent 2-4 个 Agent 4-8 个 Agent 优先采用单次响应扇出；否则按顺序回退执行，并确保每项工作的归属互不冲突 每位写入者仅负责自己独占的文件——不可能发生冲突 主机支持时，并发运行所有写入者；否则按顺序回退执行 将提供的 research.json 作为主要来源

<phase name="6-qa" type="single" critical="false" spawn="sequential">
    <agent_count>1</agent_count>
    <description>质量验证</description>
    <spawn_instruction>使用单个 Agent，并等待其完成</spawn_instruction>
</phase>

</execution_rules>

预检

<pre_flight_gate> 暂停。继续之前，请完成以下要求：

必需检查

1. 验证路径是否存在
   • 如果缺少 repository_path → 则报错并退出
2. 验证目录状态
   • 如果不是目录 → 则报错并退出
3. 源代码检查
   • 如果少于 3 个源文件 → 则警告并询问用户（若用户不同意则退出）
4. 构建目录检查
   • 如果包含 node_modules 或 dist → 则报错并退出
5. 大小估算
   • 如果超过 200k 行代码 → 则警告并询问用户（若用户不同意则退出）

门禁通过前禁止执行：

• 启动任何 Agent
• 初始化工作区 </pre_flight_gate>

开始之前，请验证仓库路径并检查边缘情况。

1. 验证路径是否存在

   • 确保 repository_path 存在。
   • 如果不存在，则抛出错误："Repository path does not exist: " + path 并退出。

2. 验证目录状态

   • 确认 repository_path 是一个目录。
   • 如果不是，则抛出错误："Path is not a directory: " + path 并退出。

3. 源代码检查

   • 统计以 .ts、.js、.py、.go 或 .rs 结尾的文件。
   • 排除以下目录：node_modules、.git、dist、build。
   • 如果找到的源文件少于 3 个：
     • 警告："Very few source files detected ({count}). This may not be a code repository."
     • 除非调用方明确要求严格验证，否则自动以低置信度模式继续。

4. 构建目录检查

   • 确保该路径不包含 node_modules、dist 或 build。
   • 如果包含，则抛出错误："Repository path appears to be a build directory. Please specify the project root." 并退出。

5. 大小估算

   • 估算仓库大小。
   • 如果超过 200,000 行代码：
     • 警告："Large repository detected (~{size} LOC)."
     • 自动继续，但优先采用保守的探索方式并分批处理。

初始化工作区

<init_gate> 停止。初始化前请验证状态。

必需操作

1. 定义目录（CONTEXT_DIR、DOC_DIR）
   • **必需：**先确定一个稳定的 SESSION_NAME（如有调用方提供的名称则使用；否则使用简短的、基于仓库名称的名称）
2. 处理现有状态
   • 如果非终止阶段存在 state.json → 则自动恢复
   • 如果调用方明确要求重新运行 → 则重置状态
3. 创建目录
4. 初始化新状态（如果未恢复）

禁止：

• 在状态初始化之前开始 Phase 1。 </init_gate>

### 工作区初始化 启动流水线前，请设置工作环境并处理任何现有状态。

1. 定义目录

   • 会话目录（CONTEXT_DIR）：${REPOSITORY_PATH}/.octocode/documentation/${SESSION_NAME}
   • 文档目录（DOC_DIR）：${REPOSITORY_PATH}/documentation

2. 处理现有状态

   • 检查 ${CONTEXT_DIR}/state.json 是否存在。
   • 如果存在且阶段不是“complete”或“failed”：
     • 默认行为：从已保存的检查点恢复。
     • 设置 RESUME_MODE = true
     • 根据已保存的状态设置 START_PHASE。
     • 仅当调用方明确要求重新启动／重新生成时：
       • 警告：“将从头开始重新启动。先前进度将被覆盖。”
       • 设置 RESUME_MODE = false
       • 设置 START_PHASE = "initialized"
   • 如果 state.json 不存在，或上次运行已完成／失败，则从头开始（RESUME_MODE = false）。

3. 创建目录

   • 确保 CONTEXT_DIR 存在（若不存在则创建）。
   • 确保 DOC_DIR 存在（若不存在则创建）。

4. 初始化新状态（若不恢复）

   • 使用 schemas/state-schema.json 中定义的架构创建新的 state.json。

进度跟踪器

实时显示进度：

📊 Documentation Generation Progress v3.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Repository: {REPOSITORY_PATH}
Mode: {RESUME_MODE ? "Resume" : "New"}

{if RESUME_MODE}
Resuming from: {START_PHASE}
{end}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Agent 流水线执行

阶段 1：发现与分析 Agent

<phase_1_gate> GATE：开始阶段 1 必需： 在一条消息中启动 4 个 Agent。 禁止： 顺序调用。 </phase_1_gate>

Agent 规范：references/agent-discovery-analysis.md 任务架构／配置：schemas/discovery-tasks.json

属性	值
并行 Agent	4（1a-language、1b-components、1c-dependencies、1d-flows-apis）
关键	是
输出	.octocode/documentation/{session-name}/analysis.json

完整实现请参阅 references/agent-discovery-analysis.md → Orchestrator Execution Logic 部分。

阶段 2：工程师问题 Agent

Agent 规范：references/agent-engineer-questions.md

属性	值
Agent 类型	单个（高能力推理模型）
关键	是
输入	.octocode/documentation/{session-name}/analysis.json、schemas/documentation-structure.json
输出	.octocode/documentation/{session-name}/questions.json

完整实现请参阅 references/agent-engineer-questions.md → Orchestrator Execution Logic 部分。

阶段 3：研究 Agent 🆕

<phase_3_gate> GATE：开始阶段 3 必需： 在一条消息中启动 N 个 Agent。 禁止： 顺序调用。 </phase_3_gate>

Agent 规范：references/agent-researcher.md

属性	值
Agent 类型	并行（具备研究能力的执行模型）
关键	是
输入	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json
输出	.octocode/documentation/{session-name}/research.json

完整实现请参阅 references/agent-researcher.md → Orchestrator Execution Logic 部分。

阶段 4：编排 Agent

Agent 规范：references/agent-orchestrator.md

属性	值
Agent 类型	单个（高能力推理模型）
关键	是
输入	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、schemas/documentation-structure.json
输出	.octocode/documentation/{session-name}/work-assignments.json

完整实现请参阅 references/agent-orchestrator.md → Orchestrator Execution Logic 部分。

阶段 5：文档撰写者

<phase_5_gate> 门控：启动阶段 5 必需： 在一条消息中启动所有撰写者。 禁止： 按顺序逐个调用。 </phase_5_gate>

Agent 规范：references/agent-documentation-writer.md

属性	值
Agent 类型	并行（1-8 个具备撰写能力的 Agent）
关键撰写者	负责大部分主要核心文件（01-08）的撰写者
非主要撰写者	允许部分失败
重试逻辑	每个失败的撰写者最多重试 2 次
输入	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、.octocode/documentation/{session-name}/work-assignments.json、schemas/documentation-structure.json
输出	documentation/*.md（16 个核心文件、5 个必需文件，以及撰写者负责的补充文件；QA-SUMMARY.md 是阶段 6 的输出）
文件所有权	独占（无冲突）

撰写者扩展策略

策略	Agent 数量	使用时机
sequential	1	少于 25 个问题
parallel-core	2-4	25-49 个问题
parallel-all	4-8	>= 50 个问题

完整实现请参见 references/agent-documentation-writer.md → Orchestrator Execution Logic 部分。

阶段 6：QA 验证器

Agent 规范：references/agent-qa-validator.md

属性	值
Agent 类型	单个（具备验证能力的模型）
关键	否（失败时会产生警告）
输入	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、documentation/*.md、schemas/documentation-structure.json
输出	.octocode/documentation/{session-name}/qa-results.json、documentation/QA-SUMMARY.md
评分范围	0-100
质量评级	excellent（≥90）、good（≥75）、fair（≥60）、needs-improvement（<60）

完整实现请参见 references/agent-qa-validator.md → Orchestrator Execution Logic 部分。

完成

update_state({
  phase: "complete",
  completed_at: new Date().toISOString(),
  current_agent: null
})

DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
DISPLAY: "✅ Documentation Complete!"
DISPLAY: ""
DISPLAY: "📁 Location: {DOC_DIR}/"
DISPLAY: "📊 QA Report: {DOC_DIR}/QA-SUMMARY.md"
DISPLAY: ""

if (parsed_qa && parsed_qa.overall_score):
  DISPLAY: "Quality Score: {parsed_qa.overall_score}/100 ({parsed_qa.quality_rating})"

  if (parsed_qa.overall_score >= 90):
    DISPLAY: "Status: Excellent ✅ - Ready for release"
  else if (parsed_qa.overall_score >= 75):
    DISPLAY: "Status: Good ✅ - Minor improvements recommended"
  else if (parsed_qa.overall_score >= 60):
    DISPLAY: "Status: Fair -️ - Address gaps before release"
  else:
    DISPLAY: "Status: Needs Work -️ - Major improvements required"

  if (parsed_qa.gaps && parsed_qa.gaps.length > 0):
    DISPLAY: ""
    DISPLAY: "Next Steps:"
    for (i = 0; i < Math.min(3, parsed_qa.gaps.length); i++):
      gap = parsed_qa.gaps[i]
      DISPLAY: "  {i+1}. {gap.fix}"

DISPLAY: ""
DISPLAY: "📝 Documentation Coverage:"
DISPLAY: "   {parsed_questions.summary.total_questions} questions researched"
DISPLAY: "   {parsed_qa.question_coverage.answered} questions answered in docs"
DISPLAY: ""
if (exists(DOC_DIR + "/index.md")):
  DISPLAY: "View documentation: {DOC_DIR}/index.md"
else:
  DISPLAY: "View documentation: {DOC_DIR}/01-project-overview.md"
DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

EXIT code 0

错误恢复

如果任何 Agent 发生严重故障：

function handle_critical_failure(phase, error):
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  DISPLAY: "❌ Documentation Generation Failed"
  DISPLAY: ""
  DISPLAY: "Phase: {phase}"
  DISPLAY: "Error: {error.message}"
  DISPLAY: ""

  if (error.recoverable):
    DISPLAY: "This error is recoverable. Run /octocode-documentation-writer again to resume."
    DISPLAY: "State saved in: {CONTEXT_DIR}/state.json"
  else:
    DISPLAY: "This error is not recoverable. Please check the error and try again."
    DISPLAY: "You may need to fix the issue before retrying."

  DISPLAY: ""
  DISPLAY: "Logs: {CONTEXT_DIR}/state.json"
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  EXIT code 1

辅助函数

重要：状态同步 只有主协调器进程可以更新 state.json。各个并行 Agent （Discovery 1A-1D、Researchers、Writers）不得直接修改 state.json，以避免 竞态条件。并行 Agent 只能使用其特定阶段约定的路径， 将结果写入 .octocode/documentation/{session-name}/ 中指定的部分结果文件 （例如 partial-1a-language.json 或 research-results/partial-research-0.json）。协调器会汇总这些结果，并在所有并行 Agent 完成后更新 state.json。

// NOTE: This function should ONLY be called by the main orchestrator process,
// never by parallel sub-agents. Parallel agents use their designated partial-result path instead.
function update_state(updates):
  current_state = Read(CONTEXT_DIR + "/state.json")
  parsed = JSON.parse(current_state)

  for key, value in updates:
    parsed[key] = value

  Write(CONTEXT_DIR + "/state.json", JSON.stringify(parsed, null, 2))

function estimate_repo_size(path):
  // Quick estimate: count source files
  files = count_files(path, ["*.ts", "*.js", "*.py", "*.go", "*.rs", "*.java"], excludeDir=["node_modules", ".git", "dist", "build"])
  // Assume ~200 LOC per file average
  return files * 200

function count_files(path, patterns, excludeDir):
  // Use localFindFiles MCP tool (mcp__octocode__localFindFiles)
  // Return count of matching files

重试与数据保留逻辑

关键： 绝不丢失部分工作。所有 Agent 都支持在保留状态的情况下重试。

const RETRY_CONFIG = {
  discovery_analysis: { max_attempts: 3, backoff_ms: 2000 },
  engineer_questions: { max_attempts: 3, backoff_ms: 2000 },
  research:           { max_attempts: 3, backoff_ms: 3000 },
  orchestrator:       { max_attempts: 3, backoff_ms: 2000 },
  documentation:      { max_attempts: 3, backoff_ms: 5000 },  // per writer
  qa:                 { max_attempts: 2, backoff_ms: 1000 }
}

// === RETRY WRAPPER FOR ALL AGENTS ===
function retry_agent(phase_name, agent_fn, options = {}):
  config = RETRY_CONFIG[phase_name]
  state = get_retry_state(phase_name)

  while (state.attempts < config.max_attempts):
    state.attempts++
    update_retry_state(phase_name, state)

    DISPLAY: `⟳ ${phase_name} attempt ${state.attempts}/${config.max_attempts}`

    try:
      result = agent_fn(options)

      // Success - clear retry state
      clear_retry_state(phase_name)
      return { success: true, result }

    catch (error):
      state.last_error = error.message
      update_retry_state(phase_name, state)

      DISPLAY: `⚠️ ${phase_name} failed: ${error.message}`

      if (state.attempts < config.max_attempts):
        DISPLAY: `   Retrying in ${config.backoff_ms}ms...`
        sleep(config.backoff_ms * state.attempts)  // Exponential backoff
      else:
        DISPLAY: `❌ ${phase_name} exhausted all ${config.max_attempts} attempts`
        return { success: false, error, attempts: state.attempts }

  return { success: false, error: state.last_error, attempts: state.attempts }

// === PARALLEL AGENT RETRY (for Discovery, Research, Writers) ===
function retry_parallel_agents(phase_name, agent_tasks, options = {}):
  config = RETRY_CONFIG[phase_name]
  results = {}
  failed_tasks = []

  // First attempt - run all in parallel
  parallel_results = Task_Parallel(agent_tasks)

  for (task_id, result) in parallel_results:
    if (result.success):
      results[task_id] = result
      save_partial_result(phase_name, task_id, result)
    else:
      failed_tasks.push({ id: task_id, task: agent_tasks[task_id], attempts: 1 })

  // Retry failed tasks individually
  for failed in failed_tasks:
    while (failed.attempts < config.max_attempts):
      failed.attempts++
      DISPLAY: `⟳ Retrying ${phase_name}/${failed.id} (attempt ${failed.attempts}/${config.max_attempts})`

      try:
        result = Task(failed.task)
        if (result.success):
          results[failed.id] = result
          save_partial_result(phase_name, failed.id, result)
          break
      catch (error):
        DISPLAY: `⚠️ ${phase_name}/${failed.id} failed: ${error.message}`
        if (failed.attempts < config.max_attempts):
          sleep(config.backoff_ms * failed.attempts)

    if (failed.attempts >= config.max_attempts && !results[failed.id]):
      DISPLAY: `❌ ${phase_name}/${failed.id} failed after ${config.max_attempts} attempts`
      // Load any partial result saved during attempts
      results[failed.id] = load_partial_result(phase_name, failed.id) || { success: false, partial: true }

  return results

// === PARTIAL RESULT PRESERVATION ===
// Uses atomic writes to prevent corruption from concurrent access
function resolve_partial_result_path(phase_name, task_id):
  if (phase_name == "discovery-analysis"):
    discovery_paths = {
      "agent-1a-language": CONTEXT_DIR + "/partial-1a-language.json",
      "agent-1b-components": CONTEXT_DIR + "/partial-1b-components.json",
      "agent-1c-dependencies": CONTEXT_DIR + "/partial-1c-dependencies.json",
      "agent-1d-flows-apis": CONTEXT_DIR + "/partial-1d-flows-apis.json"
    }
    return discovery_paths[task_id] || (CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json")

  if (phase_name == "research"):
    index = task_id.replace("researcher-", "")
    return CONTEXT_DIR + "/research-results/partial-research-" + index + ".json"

  return CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json"

function save_partial_result(phase_name, task_id, result):
  target_path = resolve_partial_result_path(phase_name, task_id)
  partial_dir = dirname(target_path)
  mkdir_p(partial_dir)
  temp_path = target_path + ".tmp." + random_uuid()

  // Atomic write: write to temp file, then rename (rename is atomic on POSIX)
  Write(temp_path, JSON.stringify(result))
  rename(temp_path, target_path)  // Atomic operation

function load_partial_result(phase_name, task_id):
  path = resolve_partial_result_path(phase_name, task_id)
  if (exists(path)):
    return JSON.parse(Read(path))
  return null

function load_all_partial_results(phase_name):
  partial_dir = CONTEXT_DIR + "/partials/" + phase_name
  if (!exists(partial_dir)):
    return {}
  files = list_files(partial_dir, "*.json")
  results = {}
  for file in files:
    task_id = file.replace(".json", "")
    results[task_id] = JSON.parse(Read(partial_dir + "/" + file))
  return results

// === RETRY STATE MANAGEMENT ===
function get_retry_state(phase_name):
  state = Read(CONTEXT_DIR + "/state.json")
  parsed = JSON.parse(state)
  return parsed.retry_state?.[phase_name] || { attempts: 0 }

function update_retry_state(phase_name, retry_state):
  update_state({
    retry_state: {
      ...current_state.retry_state,
      [phase_name]: retry_state
    }
  })

function clear_retry_state(phase_name):
  state = JSON.parse(Read(CONTEXT_DIR + "/state.json"))
  if (state.retry_state):
    delete state.retry_state[phase_name]
    Write(CONTEXT_DIR + "/state.json", JSON.stringify(state, null, 2))

阶段专属重试行为

阶段	重试策略	保留的部分数据
Discovery	单独重试失败的子 Agent（1A-1D）	partials/discovery/*.json
Questions	重试整个阶段	成功前保留之前的 questions.json
Research	仅重试失败的批次	partials/research/batch-*.json
Orchestrator	重试整个阶段	保留之前的 work-assignments.json
Writers	仅重试失败的撰写者	partials/writers/writer-*.json + 已完成的文件
QA	重试一次，然后发出警告	partials/qa/partial-results.json

关键数据保护规则

// RULE 1: Never overwrite successful output until new output is validated
function safe_write_output(path, content):
  backup_path = path + ".backup"
  if (exists(path)):
    copy(path, backup_path)

  try:
    Write(path, content)
    validate_json(path)  // Ensure valid JSON
    delete(backup_path)  // Only delete backup after validation
  catch (error):
    // Restore from backup
    if (exists(backup_path)):
      copy(backup_path, path)
    throw error

// RULE 2: Aggregate partial results even on failure
// Uses file locking to prevent race conditions during aggregation
function aggregate_with_partials(phase_name, new_results):
  lock_file = CONTEXT_DIR + "/partials/" + phase_name + "/.aggregate.lock"

  // Acquire exclusive lock before aggregation
  lock_fd = acquire_file_lock(lock_file, timeout_ms=5000)
  if (!lock_fd):
    throw new Error("Failed to acquire lock for aggregation: " + phase_name)

  try:
    existing = load_all_partial_results(phase_name)
    merged = { ...existing, ...new_results }
    return merged
  finally:
    release_file_lock(lock_fd)
    delete(lock_file)

// RULE 3: Resume-aware execution
function should_skip_task(phase_name, task_id):
  partial = load_partial_result(phase_name, task_id)
  return partial?.success === true

---

主要功能

<key_features>

#	功能	描述
1	感知宿主的并行执行	在支持真正并行分发的情况下，阶段 1、3、5 会使用并行分发；否则按顺序执行
2	如实处理并发	优先采用并行执行，但此技能绝不会把顺序执行伪称为并发
3	基于证据	研究 Agent 会先通过代码追踪验证答案，再进行撰写
4	由工程师驱动的问题	阶段 2 会生成全面的问题
5	无冲突撰写	编排器会为每位撰写者分配独占的文件所有权
6	由 LSP 提供支持	通过语义分析进行智能验证
7	状态恢复	中断后可从任意阶段恢复
8	统一工具集	所有 Agent 都使用 octocode 本地工具和 LSP 工具
9	动态扩展	Agent 数量会根据问题数量动态调整

</key_features>

<efficiency_summary>

最大化效率

Phase 1: 4 agents × parallel = ~4x faster than sequential
Phase 3: N agents × parallel = ~Nx faster than sequential
Phase 5: M agents × parallel = ~Mx faster than sequential

Total speedup: Significant when host parallelism is available

请记住：使用宿主支持的最强并行分发能力。如果无法实现真正的并行处理，则退回顺序执行，并保持相同的所有权边界。 </efficiency_summary>

---