module-deep-research

Files (13)

• SKILL.md
• openai.yaml · agents/
• document-contracts.json · assets/
• recheck.md · assets/prompts/
• task.md · assets/prompts/
• task-types.json · assets/
• business-flow.md · assets/templates/
• constraints-risks.md · assets/templates/
• data-model.md · assets/templates/
• module-overview.md · assets/templates/
• non-flow-feature.md · assets/templates/
• asset-structure.md · references/
• deep_research.py · scripts/

SKILL.md (first lines)

# 模块深度研究

## 1. 边界

- 只读业务代码、测试、配置、文档和 Git 历史。
- 只写 `.sdd/modules/<module>/` 下的认知资产、研究状态和 findings。
- 不修改业务代码，不运行会改变业务数据或外部系统状态的操作。
- 不把文件清单、命名猜测或临时推理写成稳定认知。
- Git 提交、commit message、历史 diff 和旧版本文件只作为调查线索；提交反查形成的稳定结论必须以当前 HEAD 的模块源码为事实来源，测试、配置和说明材料只用于交叉验证。
- 独立运行本 skill，不加载或调用 `aaw-workflow`。

认知资产职责和写入规范见 `<skill-dir>/references/asset-structure.md`。
五类稳定认知文档必须使用 `<skill-dir>/assets/templates/` 中的固定模板。

## 2. 使用 CLI

从仓库根目录执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py <command> ...
```

不得直接编辑 `research-state.json`。任务选择、状态、阻塞问题和完成判定全部以 CLI 返回为准。

### 2.1 初始化或继续

若 `.sdd/modules/<module>/研究过程/research-state.json` 不存在，执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py init --module "<module>" --path "<repo-relative-module-path>" --history-mode full --history-batch-size 20 --json
```

若状态文件已经存在，执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py status --module "<module>" --json
```

CLI 不设置时间预算，也不会因运行时间、已完成工作单元数量、文档数量或阶段成果达到某个值而改变作业生命周期。研究持续到外部阻塞、用户明确要求暂停或 recheck 完成。

`--history-mode full` 扫描所有影响模块路径的可见提交，但初始化时只把它们登记到 `research-state.json` 的提交清单，不立即创建任务。只有用户明确不需要 Git 历史研究时才使用 `--history-mode off`。

`--history-batch-size` 控制常规认知任务收敛后，每批最多实例化多少个 Git 反查任务，默认 `20`，可用范围为 `1..100`。它限制待办规模，不限制最终覆盖的提交总数。

### 2.2 执行循环

先建立以下连续研究契约：

- 用户需要的是经过完整取证、Git 线索反查和最终审查的专家级模块认知资产。
- CLI 返回的任务是长程研究作业中的一个工作单元，不对应一次对话回合，也不构成阶段结果节点。
- 工作单元验收表示成果已写入认知资产和研究状态，继续执行不会丢失已有进展。
- `job.status=active` 时，当前职责是执行响应末尾的 `next_action`；工作单元数量、运行时长和已有成果不改变这个职责。
- CLI 进入 `complete`、`blocked` 或用户明确触发的 `paused` 后，才根据终态的 `next_action` 形成相应回复。

重复执行以下协议：

1. 首次进入、恢复或异常重入时调用 `next --json`。
2. 若返回 `status=task`，只执行返回对象中的 `prompt`，不得自行切换或合并其他任务。
3. 把研究结果写到返回的 `result_file`，把稳定认知增量写入对应认知资产。
4. 执行返回的 `commands.submit`。
5. `submit` 校验失败时按错误修正，不得跳过或直接修改状态。
6. `submit` 成功后会在同一响应中确认当前工作单元并原子续领下一工作单元。按照响应末尾的 `next_action` 立即推进；`action=execute_prompt` 时直接执行同一响应中的 `prompt`，不需要再次调用 `next`。

```text
uv run --no-project <skill-dir>/scripts/deep_research.py next --module "<module>" --json
```

CLI 返回提示词已经包含当前问题、稳定认知资产、已验收认知、优先取证位置、Git 基线、调查方法、完成标准、任务派生规则和结果结构。不要用本文件中的概括替代该提示词。

`submit` 会要求 `acceptance_checks` 逐项引用当前工作单元的 claims，并校验被修改文档的元信息和固定章节。`recheck` 最终提交还会校验全部文档、占位内容、结论状态、原始证据说明和功能索引；校验失败时继续修正文档，不得跳过。

`next` 会在 HEAD 变化时自动刷新提交清单。需要主动强制刷新时执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py history-sync --module "<module>" --force --json
```

CLI 按以下轨道顺序调度，不能用数值优先级跨越轨道：

1. 用户补充问题。
2. 常规认知任务，以及这些任务持续派生出的新认知任务。
3. Git 历史反查任务。
4. 全部任务清空后由 CLI 自动创建并续领的 recheck。

只有第二条轨道达到不再产生新任务的收敛点后，CLI 才会从提交清单按“新提交到旧提交”懒加载一个历史批次。Git 任务发现新的流程、状态、契约、风险或知识缺口并派生常规任务后，下一轮立即切回常规认知轨道；这些新任务再次收敛后才继续历史批次。这样既避免 1000+ 提交淹没队列，也让越新的、通常有效知识密度越高的提交优先被研究。

用户在任何阶段补充模块问题时执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py add-question --module "<module>" --question "<question>" --json
```

可选使用 `--title`、`--priority 1..100` 和重复的 `--evidence-hint`。默认优先级为 `100`。

`add-question` 保留既有文档、任务和 findings。若研究已经 `complete`、`paused` 或 `blocked`，CLI 会重新进入 `research` 并开启新的运行时段；若存在未完成 recheck，则使旧 recheck 失效。新问题处理完后必须重新执行 recheck，才能再次返回 `complete`。

### 2.3 处理作业状态

- `active`：执行响应末尾的 `next_action`。工作单元验收和阶段成果都属于作业内进度。
- `paused`：仅表示用户已经明确要求暂存当前运行。保留当前工作单元，后续使用 `resume` 继续。
- `blocked`：说明 CLI 返回的外部阻塞问题。材料补齐后使用 `resume --reopen-blocked`。
- `complete`：根据完整认知资产形成最终结果；后续仍可使用 `add-question` 重新打开研究。
- `error`：修正命令、结果结构或证据，不绕过 CLI。

`continuation_required=true` 表示作业仍处于 active 生命周期，响应末尾的 `next_action` 是当前唯一调度指令。任务级 `outcome=completed`、一次 `submit` 成功或进入 recheck 只表示工作单元或阶段发生变化。`continuation_required=false` 表示 CLI 已给出终态动作。

`status --json` 的 `current_lane` 表示当前调度轨道；`history` 中的 `queued_commits`、`materialized_commits`、`covered_commits` 和 `blocked_commits` 表示提交清单进度。

恢复命令：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py resume --module "<module>" --json
```

仅当用户明确要求暂停时执行：

```text
uv run --no-project <skill-dir>/scripts/deep_research.py pause --module "<module>" --reason "<reason>" --json
```

From pi-ixel/Awesome-Agent-Workflow, MIT.

More from pi-ixel/Awesome-Agent-Workflow