⚡

代码库文档生成器Skill octocode-documentation-writer

这是一个AI驱动的自动化技能，通过6阶段并行代理管道分析代码库并生成全面的技术文档。它使用AI代理进行代码分析、问题生成、证据研究和文档编写，确保高效、准确且无冲突的文档输出。关键词：AI文档生成、代码分析、自动化文档、并行处理、软件开发工具、智能代理。

AIGC 0 次安装 0 次浏览 更新于 3/9/2026

name: octocode-documentation-writer description: 当用户要求“生成文档”、“为该项目编写文档”、“创建文档”、“编写文档”、“更新文档”、“记录所有API”、“生成入职文档”、“创建开发者文档”或需要全面的代码库文档时，应使用此技能。编排并行AI代理以分析代码并生成文档文件。

仓库文档生成器

生产就绪的6阶段管道，具有智能编排、研究优先验证和无冲突文件所有权。

<what> 此命令在6个阶段中编排专门的AI代理，以分析您的代码仓库并生成全面的文档： </what>

<steps> <phase_1> 发现+分析（第1阶段） 代理：Opus 并行：4个并行代理 内容：分析语言、架构、流程和API 输入：仓库路径 输出：analysis.json </phase_1>

<phase_2> 工程师问题（第2阶段） 代理：Opus 内容：基于分析生成全面问题 输入：analysis.json 输出：questions.json </phase_2>

<phase_3> 研究代理（第3阶段）🆕 代理：Sonnet 并行：动态（基于问题数量） 内容：深度代码取证，以证据回答问题 输入：questions.json 输出：research.json </phase_3>

<phase_4> 编排器（第4阶段） 代理：Opus 内容：按文件目标分组问题，并分配独占文件所有权给编写者 输入：questions.json + research.json 输出：work-assignments.json（基于文件的并行编写者分配） </phase_4>

<phase_5> 文档编写者（第5阶段） 代理：Sonnet 并行：1-8个并行代理（基于工作负载动态调整） 内容：综合研究并编写全面文档，具有独占文件所有权 输入：analysis.json + questions.json + research.json + work-assignments.json 输出：documentation/*.md（16个核心文档，5个必需 + 补充文件） </phase_5>

<phase_6> 质量保证验证器（第6阶段） 代理：Sonnet 内容：使用LSP驱动验证验证文档质量 输入：documentation/*.md + analysis.json + questions.json 输出：qa-results.json + QA-SUMMARY.md </phase_6> </steps>

<subagents> 使用spawn explore opus/sonnet/haiku子代理，通过MCP工具探索代码（localSearchCode, lspGotoDefinition, lspCallHierarchy, lspFindReferences） </subagents>

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

⚠️ 关键：并行代理执行

<parallel_execution_critical importance=“maximum”>

停止。请阅读两遍。

1. 规则

您必须在单条消息中使用多个Task工具调用来生成并行代理。

2. 禁止行为

禁止： 顺序调用Task（每次响应一个）。 原因： 顺序调用破坏并行性，使执行速度降低4-8倍。

3. 必需确认

在启动任何并行阶段（1、3、5）之前，您必须验证：

  • [ ] 所有Task调用已准备好在单条响应中
  • [ ] 这些并行代理之间没有依赖关系
  • [ ] 每个代理具有独占范围（无文件冲突）

<correct_pattern title=“✅ 正确：单条响应同时启动所有代理”>

// 在一条助手消息中，包括所有Task工具调用：
Task(description="发现1A-语言", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="发现1B-组件", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="发现1C-依赖", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="发现1D-流程", subagent_type="general-purpose", prompt="...", model="opus")
// ↑ 所有4个同时执行

</correct_pattern>

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

// 不要这样做 - 每个等待前一个完成
消息1：Task(description="发现1A") → 等待结果
消息2：Task(description="发现1B") → 等待结果
消息3：Task(description="发现1C") → 等待结果
消息4：Task(description="发现1D") → 等待结果
// ↑ 速度慢4倍！未实现并行性

</wrong_pattern>

</parallel_execution_critical>

执行流程图

flowchart TB
    Start([/octocode-documentation-writer PATH]) --> Validate[预飞行验证]
    Validate --> Init[初始化工作空间]

    Init --> P1[阶段1：发现+分析]

    subgraph P1_Parallel["🔄 并行运行（4个代理）"]
        P1A[代理1A：<br/>语言和清单]
        P1B[代理1B：<br/>组件]
        P1C[代理1C：<br/>依赖]
        P1D[代理1D：<br/>流程和API]
    end

    P1 --> P1_Parallel
    P1_Parallel --> P1Agg[聚合：<br/>合并为analysis.json]
    P1Agg --> P1Done[✅ analysis.json 已创建]

    P1Done -->|读取analysis.json| P2[阶段2：工程师问题<br/>单个代理 - Opus]
    P2 --> P2Done[✅ questions.json 已创建]

    P2Done -->|读取questions.json| P3[阶段3：研究 🆕<br/>并行代理 - Sonnet]
    
    subgraph P3_Parallel["🔄 并行运行"]
       P3A[研究员1]
       P3B[研究员2]
       P3C[研究员3]
    end
    
    P3 --> P3_Parallel
    P3_Parallel --> P3Agg[聚合：<br/>合并为research.json]
    P3Agg --> P3Done[✅ research.json 已创建<br/>基于证据的答案]

    P3Done -->|读取问题 + 研究| P4[阶段4：编排器<br/>单个代理 - Opus]
    P4 --> P4Group[按文件目标分组问题]
    P4 --> P4Assign[分配文件所有权<br/>给编写者]
    P4Assign --> P4Done[✅ work-assignments.json]

    P4Done --> P5[阶段5：文档编写者]
    P5 --> P5Input[📖 输入：<br/>work-assignments.json<br/>+ research.json]
    P5Input --> P5Dist[每个编写者获得<br/>独占文件所有权]

    subgraph P5_Parallel["🔄 并行运行（1-8个代理）"]
        P5W1[编写者1]
        P5W2[编写者2]
        P5W3[编写者3]
        P5W4[编写者4]
    end

    P5Dist --> P5_Parallel
    P5_Parallel --> P5Verify[验证结构]
    P5Verify --> P5Done[✅ documentation/*.md 已创建]

    P5Done --> P6[阶段6：质量保证验证器<br/>单个代理 - Sonnet]
    P6 --> P6Done[✅ qa-results.json +<br/>QA-SUMMARY.md]

    P6Done --> 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> <phase name=“1-发现” type=“parallel” critical=“true” spawn=“single_message”> <gate> 停止。 验证并行生成要求。 必需： 在一条消息中生成4个代理。 禁止： 顺序Task调用。 </gate> <agent_count>4</agent_count> <description>发现和分析</description> <spawn_instruction>⚠️ 在一条响应中启动所有4个Task调用</spawn_instruction> <rules> <rule>所有4个代理通过单条消息生成同时启动</rule> <rule>等待所有4个完成后聚合</rule> <rule>必须将4个部分JSON聚合为analysis.json</rule> </rules> </phase>

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

<phase name="3-研究" type="parallel" critical="true" spawn="single_message">
    <gate>
    **停止。** 验证并行生成要求。
    **必需：** 在一条消息中生成N个研究员。
    **禁止：** 顺序Task调用。
    </gate>
    <agent_count_logic>
        <case condition="questions &lt; 10">1个代理</case>
        <case condition="questions &gt;= 10">Ceil(问题数 / 15)</case>
    </agent_count_logic>
    <description>证据收集</description>
    <spawn_instruction>⚠️ 在一条响应中启动所有研究员Task调用</spawn_instruction>
    <rules>
        <rule>在生成前将问题分批</rule>
        <rule>所有研究员同时启动</rule>
        <rule>聚合发现为research.json</rule>
    </rules>
</phase>

<phase name="4-编排器" type="single" critical="true" spawn="sequential">
    <agent_count>1</agent_count>
    <description>编排和分配</description>
    <spawn_instruction>单个代理，等待完成</spawn_instruction>
    <rules>
        <rule>分配独占文件所有权给编写者</rule>
        <rule>将研究发现分发给相关编写者</rule>
    </rules>
</phase>

<phase name="5-编写者" type="dynamic_parallel" critical="false" spawn="single_message">
    <gate>
    **停止。** 验证并行生成要求。
    **必需：** 在一条消息中生成所有编写者。
    **禁止：** 顺序Task调用。
    </gate>
    <agent_count_logic>
        <case condition="questions &lt; 20">1个代理</case>
        <case condition="questions 20-99">2-4个代理</case>
        <case condition="questions &gt;= 100">4-8个代理</case>
    </agent_count_logic>
    <spawn_instruction>⚠️ 在一条响应中启动所有编写者Task调用</spawn_instruction>
    <rules>
        <rule>每个编写者拥有独占文件 - 无冲突可能</rule>
        <rule>所有编写者通过单条消息生成同时启动</rule>
        <rule>使用提供的research.json作为主要来源</rule>
    </rules>
</phase>

<phase name="6-质量保证" type="single" critical="false" spawn="sequential">
    <agent_count>1</agent_count>
    <description>质量验证</description>
    <spawn_instruction>单个代理，等待完成</spawn_instruction>
</phase>

</execution_rules>

预飞行检查

<pre_flight_gate> 停止。在继续之前完成这些要求：

必需检查

  1. 验证路径存在
    • 如果 repository_path 缺失 → 那么 错误并退出
  2. 验证目录状态
    • 如果 不是目录 → 那么 错误并退出
  3. 源代码检查
    • 如果 < 3个源文件 → 那么 警告并询问用户（如果没有确认，退出）
  4. 构建目录检查
    • 如果 包含 node_modules 或 dist → 那么 错误并退出
  5. 大小估计
    • 如果 > 200k行代码 → 那么 警告并询问用户（如果没有确认，退出）

在通过检查前禁止：

  • 任何代理生成
  • 工作空间初始化 </pre_flight_gate>

<instruction> 在开始之前，验证仓库路径并检查边缘情况。

  1. 验证路径存在

    • 确保 repository_path 存在。
    • 如果不存在，引发错误：“仓库路径不存在：” + 路径，并退出。

  2. 验证目录状态

    • 确认 repository_path 是目录。
    • 如果不是，引发错误：“路径不是目录：” + 路径，并退出。

  3. 源代码检查

    • 统计以 .ts、.js、.py、.go 或 .rs 结尾的文件。
    • 排除目录：node_modules、.git、dist、build。
    • 如果发现少于3个源文件：
      • 警告：“检测到很少源文件（{count}）。这可能不是代码仓库。”
      • 询问用户：“仍然继续？[y/N]”
      • 如果没有确认，退出。

  4. 构建目录检查

    • 确保路径不包含 node_modules、dist 或 build。
    • 如果包含，引发错误：“仓库路径似乎是构建目录。请指定项目根目录。”并退出。

  5. 大小估计

    • 估计仓库大小。
    • 如果大于200,000行代码：
      • 警告：“检测到大仓库（约{size}行代码）。”
      • 询问用户：“仍然继续？[y/N]”
      • 如果没有确认，退出。 </instruction>

初始化工作空间

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

必需操作

  1. 定义目录 (CONTEXT_DIR, DOC_DIR)
  2. 处理现有状态
    • 如果 state.json 存在 → 那么 提示用户恢复
    • 如果 用户说否 → 那么 重置状态
  3. 创建目录
  4. 初始化新状态（如果不恢复）

禁止：

  • 在状态初始化前启动第1阶段。 </init_gate>

<instruction>

工作空间初始化

在开始管道之前，设置工作环境并处理任何现有状态。

  1. 定义目录

    • 上下文目录 (CONTEXT_DIR)：${REPOSITORY_PATH}/.context
    • 文档目录 (DOC_DIR)：${REPOSITORY_PATH}/documentation

  2. 处理现有状态

    • 检查 ${CONTEXT_DIR}/state.json 是否存在。
    • 如果存在且阶段不是“完成”或“失败”：
      • 提示用户：“发现现有文档生成正在进行（阶段：[PHASE]）。从最后一个检查点恢复？[Y/n]”
      • 如果用户确认（是）：
        • 设置 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。 </instruction>

进度跟踪器

显示实时进度：

📊 文档生成进度 v3.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

仓库：{REPOSITORY_PATH}
模式：{RESUME_MODE ? "恢复" : "新建"}

{if RESUME_MODE}
从恢复：{START_PHASE}
{end}

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

代理管道执行

第1阶段：发现+分析代理

<phase_1_gate> 门：启动第1阶段 必需： 在一条消息中生成4个代理。 禁止： 顺序调用。 </phase_1_gate>

代理规范：references/agent-discovery-analysis.md 任务配置：schemas/discovery-tasks.json

属性 值
并行代理 4（1a-语言，1b-组件，1c-依赖，1d-流程-API）
关键 是
输出 .context/analysis.json

见 references/agent-discovery-analysis.md → 编排器执行逻辑 部分以获取完整实现。

第2阶段：工程师问题代理

代理规范：references/agent-engineer-questions.md

属性 值
代理类型 单个（Opus）
关键 是
输入 .context/analysis.json
输出 .context/questions.json

见 references/agent-engineer-questions.md → 编排器执行逻辑 部分以获取完整实现。

第3阶段：研究代理 🆕

<phase_3_gate> 门：启动第3阶段 必需： 在一条消息中生成N个代理。 禁止： 顺序调用。 </phase_3_gate>

代理规范：references/agent-researcher.md

属性 值
代理类型 并行（Sonnet）
关键 是
输入 .context/questions.json
输出 .context/research.json

见 references/agent-researcher.md → 编排器执行逻辑 部分以获取完整实现。

第4阶段：编排器代理

代理规范：references/agent-orchestrator.md

属性 值
代理类型 单个（Opus）
关键 是
输入 .context/analysis.json、.context/questions.json、.context/research.json
输出 .context/work-assignments.json

见 references/agent-orchestrator.md → 编排器执行逻辑 部分以获取完整实现。

第5阶段：文档编写者

<phase_5_gate> 门：启动第5阶段 必需： 在一条消息中生成所有编写者。 禁止： 顺序调用。 </phase_5_gate>

代理规范：references/agent-documentation-writer.md

属性 值
代理类型 并行（1-8个Sonnet编写者）
主要编写者 编写者1（关键）
非主要 允许部分失败
重试逻辑 每个失败编写者最多2次重试
输入 .context/analysis.json、.context/research.json、.context/work-assignments.json
输出 documentation/*.md（16个核心，5个必需 + 补充）
文件所有权 独占（无冲突）

编写者扩展策略

策略 代理数 使用时机
sequential 1 < 20个问题
parallel-core 2-4 20-99个问题
parallel-all 4-8 >= 100个问题

见 references/agent-documentation-writer.md → 编排器执行逻辑 部分以获取完整实现。

第6阶段：质量保证验证器

代理规范：references/agent-qa-validator.md

属性 值
代理类型 单个（Sonnet）
关键 否（失败产生警告）
输入 .context/analysis.json、.context/questions.json、documentation/*.md
输出 .context/qa-results.json、documentation/QA-SUMMARY.md
分数范围 0-100
质量评级 优秀 (≥90)、良好 (≥75)、一般 (≥60)、需要改进 (<60)

见 references/agent-qa-validator.md → 编排器执行逻辑 部分以获取完整实现。

完成

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

DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
DISPLAY: "✅ 文档完成！"
DISPLAY: ""
DISPLAY: "📁 位置：{DOC_DIR}/"
DISPLAY: "📊 质量保证报告：{DOC_DIR}/QA-SUMMARY.md"
DISPLAY: ""

if (parsed_qa && parsed_qa.overall_score):
  DISPLAY: "质量分数：{parsed_qa.overall_score}/100 ({parsed_qa.quality_rating})"

  if (parsed_qa.overall_score >= 90):
    DISPLAY: "状态：优秀 ✅ - 准备发布"
  else if (parsed_qa.overall_score >= 75):
    DISPLAY: "状态：良好 ✅ - 建议小改进"
  else if (parsed_qa.overall_score >= 60):
    DISPLAY: "状态：一般 -️ - 发布前需解决差距"
  else:
    DISPLAY: "状态：需要改进 -️ - 需要重大改进"

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

DISPLAY: ""
DISPLAY: "📝 文档覆盖："
DISPLAY: "   {parsed_questions.summary.total_questions} 个问题已研究"
DISPLAY: "   {parsed_qa.question_coverage.answered} 个问题已在文档中回答"
DISPLAY: ""
DISPLAY: "查看文档：{DOC_DIR}/index.md"
DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

EXIT code 0

错误恢复

如果任何代理关键失败：

function handle_critical_failure(phase, error):
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  DISPLAY: "❌ 文档生成失败"
  DISPLAY: ""
  DISPLAY: "阶段：{phase}"
  DISPLAY: "错误：{error.message}"
  DISPLAY: ""

  if (error.recoverable):
    DISPLAY: "此错误可恢复。再次运行 /octocode-documentation-writer 以恢复。"
    DISPLAY: "状态保存在：{CONTEXT_DIR}/state.json"
  else:
    DISPLAY: "此错误不可恢复。请检查错误并重试。"
    DISPLAY: "您可能需要解决问题后重试。"

  DISPLAY: ""
  DISPLAY: "日志：{CONTEXT_DIR}/state.json"
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  EXIT code 1

辅助函数

重要：状态同步 仅主编排器进程应更新 state.json。单独的并行代理（发现1A-1D、研究员、编写者）不得直接修改 state.json 以避免竞态条件。并行代理应仅写入其指定的部分结果文件到 partials/<phase>/<task_id>.json。编排器在并行代理完成后聚合这些结果并更新 state.json。

// 注意：此函数应仅由主编排器进程调用，而非并行子代理。并行代理使用 save_partial_result() 代替。
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):
  // 快速估计：统计源文件
  files = count_files(path, ["*.ts", "*.js", "*.py", "*.go", "*.rs", "*.java"], excludeDir=["node_modules", ".git", "dist", "build"])
  // 假设平均约200行代码每文件
  return files * 200

function count_files(path, patterns, excludeDir):
  // 使用 localFindFiles MCP工具 (mcp__octocode__localFindFiles)
  // 返回匹配文件的数量

重试和数据保留逻辑

关键： 永远不丢失部分工作。所有代理支持重试并保留状态。

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 },  // 每个编写者
  qa:                 { max_attempts: 2, backoff_ms: 1000 }
}

// === 所有代理的重试包装器 ===
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} 尝试 ${state.attempts}/${config.max_attempts}`

    try:
      result = agent_fn(options)

      // 成功 - 清除重试状态
      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} 失败：${error.message}`

      if (state.attempts < config.max_attempts):
        DISPLAY: `   在 ${config.backoff_ms}ms 后重试...`
        sleep(config.backoff_ms * state.attempts)  // 指数退避
      else:
        DISPLAY: `❌ ${phase_name} 已尝试所有 ${config.max_attempts} 次`
        return { success: false, error, attempts: state.attempts }

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

// === 并行代理重试（用于发现、研究、编写者） ===
function retry_parallel_agents(phase_name, agent_tasks, options = {}):
  config = RETRY_CONFIG[phase_name]
  results = {}
  failed_tasks = []

  // 第一次尝试 - 并行运行所有
  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 })

  // 单独重试失败任务
  for failed in failed_tasks:
    while (failed.attempts < config.max_attempts):
      failed.attempts++
      DISPLAY: `⟳ 重试 ${phase_name}/${failed.id}（尝试 ${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} 失败：${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} 在 ${config.max_attempts} 次尝试后失败`
      // 加载尝试期间保存的任何部分结果
      results[failed.id] = load_partial_result(phase_name, failed.id) || { success: false, partial: true }

  return results

// === 部分结果保留 ===
// 使用原子写入防止并发访问损坏
function save_partial_result(phase_name, task_id, result):
  partial_dir = CONTEXT_DIR + "/partials/" + phase_name
  mkdir_p(partial_dir)

  target_path = partial_dir + "/" + task_id + ".json"
  temp_path = partial_dir + "/" + task_id + ".json.tmp." + random_uuid()

  // 原子写入：写入临时文件，然后重命名（在POSIX上重命名是原子的）
  Write(temp_path, JSON.stringify(result))
  rename(temp_path, target_path)  // 原子操作

function load_partial_result(phase_name, task_id):
  path = CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json"
  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

// === 重试状态管理 ===
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))

阶段特定重试行为

阶段 重试策略 部分数据保留
发现 单独重试失败子代理（1A-1D） partials/discovery/*.json
问题 重试整个阶段 先前 questions.json 保留直到成功
研究 仅重试失败批次 partials/research/batch-*.json
编排器 重试整个阶段 先前 work-assignments.json 保留
编写者 仅重试失败编写者 partials/writers/writer-*.json + 完成文件
质量保证 重试一次，然后警告 partials/qa/partial-results.json

关键数据保护规则

// 规则1：直到新输出验证前，永远不覆盖成功输出
function safe_write_output(path, content):
  backup_path = path + ".backup"
  if (exists(path)):
    copy(path, backup_path)

  try:
    Write(path, content)
    validate_json(path)  // 确保有效JSON
    delete(backup_path)  // 仅在验证后删除备份
  catch (error):
    // 从备份恢复
    if (exists(backup_path)):
      copy(backup_path, path)
    throw error

// 规则2：即使在失败时也聚合部分结果
// 使用文件锁定防止聚合期间竞态条件
function aggregate_with_partials(phase_name, new_results):
  lock_file = CONTEXT_DIR + "/partials/" + phase_name + "/.aggregate.lock"

  // 在聚合前获取独占锁
  lock_fd = acquire_file_lock(lock_file, timeout_ms=5000)
  if (!lock_fd):
    throw new Error("获取聚合锁失败：" + 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)

// 规则3：恢复感知执行
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 单条消息生成 ⚠️ 关键：单条响应中的多个Task调用 = 真正并行性
3 基于证据 研究代理在编写前用代码跟踪证明答案
4 工程师驱动问题 第2阶段生成全面问题
5 无冲突编写 编排器为每个编写者分配独占文件所有权
6 LSP驱动 使用语义分析进行智能验证
7 状态恢复 如果中断，可从任何阶段恢复
8 统一工具集 所有代理使用octocode本地+LSP工具
9 动态扩展 代理数量基于问题量扩展

</key_features>

<efficiency_summary>

效率最大化

第1阶段：4个代理 × 并行 = 比顺序快约4倍
第3阶段：N个代理 × 并行 = 比顺序快约N倍
第5阶段：M个代理 × 并行 = 比顺序快约M倍

总加速：当遵循 spawn="single_message" 时显著

记住： spawn="single_message" 阶段必须在一条响应中拥有所有Task调用。 </efficiency_summary>