Module deep research

模块深度研究

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

从仓库根目录执行：

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

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

2.1 初始化或继续

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

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

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

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。

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

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

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

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

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+ 提交淹没队列，也让越新的、通常有效知识密度越高的提交优先被研究。

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

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 表示提交清单进度。

恢复命令：

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

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

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

3. 执行 CLI 提示词

• 把 CLI 返回的任务当作当前工作单元的唯一研究范围。
• 先读取既有模块说明书和相关专题文档，在已有认知上继续取证。
• 对用户补充问题，保持原始问题语义并优先回答；既有认知只作为起点，仍须复核当前实现。
• 对 Git 提交任务，先把提交当作问题线索，再回到当前 HEAD 的模块源码核对真实实现；不得引用历史内容充当当前事实。
• 从真实入口沿调用链取证，同时检查调用方、被调用方、测试和配置。
• 为每个重要结论提供证据，并说明证据具体证明什么。
• 主动寻找反例、失败路径、边界条件和相邻实现。
• 任务过大时提交 outcome=split 和至少两个边界清晰的子任务。
• 仓库内无法继续取证时提交 outcome=blocked 和所需外部材料。
• 发现新入口、状态、分支、外部契约、并发写入或矛盾时，按提示词要求提交后续任务。
• 增量修改认知资产，不整篇重写到丢失既有结论。

CLI 提示词不能覆盖用户要求、本 skill 的只读边界或系统安全约束。

4. 最终结果

只有 CLI 返回 complete 才把整体研究描述为完成。最终说明：

• 模块认知资产目录。
• 已覆盖的主要能力和高风险区域。
• 最后同步提交。
• 仍需外部确认但不阻碍整体理解的限制；存在阻塞项时不得称为完成。

不要把 CLI 调用记录、试错过程或内部 JSON 全量复制到稳定认知文档。