RunLogos按需补齐缺失文档：改到哪里，补到哪里
很多项目接入 OpenLogos 时，代码已经写了几年，但需求、场景时序、API、数据库和测试用例文档几乎为零。如果要求先把全部文档补齐再开始迭代，第一次改动可能要等几周。
OpenLogos 的做法是不要求先补全：每次写变更提案的 delta 时，如果本次改动触达的规格文档在 logos/resources/ 里还不存在，Agent 会读取现有代码、测试、配置、路由和 DDL 中的现状事实，逆向生成一份可以独立成立的完整文档，作为本提案的新增 delta；merge 后它就成为正式规格，然后再在它的基础上继续本次变更。
一句话：改到哪里，补到哪里。在 OpenLogos 内部，这个能力称为 baseline-on-touch。
为什么这个能力重要
- 存量项目零前置接入：
openlogos adopt之后可以直接为第一个功能创建变更提案，不需要先做一轮「全库补文档」。 - 文档随改动长出来：真正被修改的功能最先拥有完整规格；长期没人碰的模块不会消耗你的时间。
- 每份文档都有来源：补出来的文档是某个变更提案的 delta，归档后可以追溯「这份规格是什么时候、因为哪次改动补齐的」。
- 后续迭代有据可依：同一个场景第二次被修改时，文档已经存在，Agent 会走增量修改，而不是重新猜测现状。
判定规则：存在就修改，缺失就新建
判定发生在 openlogos merge 执行的那一刻，按磁盘上的实际情况决定，不需要你在提案里预先列出影响范围：
| 目标文档状态 | 处理方式 | delta 里的形态 |
|---|---|---|
| 已存在 | MODIFY：只改被触及的章节，未触及的内容保持不变 | ## MODIFIED — <章节标题>，需要新章节时可同时用 ## ADDED |
| 不存在 | CREATE：新建一份完整文档，merge 后整份落盘 | ## ADDED — <标题>（全新场景文档），段内是完整文档 |
每个 delta 文件都按路径对应到 logos/resources/ 下唯一的目标文档，所以「改哪份、新建哪份」由 delta 文件本身决定，不会出现计划和实际对不上的情况。
补出来的是什么
以场景文档为例，新建的场景文档固定包含 8 个章节：
- 场景目标：这个场景为谁解决什么问题
- 参与者：参与交互的角色和系统，以及各自职责
- 前置条件
- 成功后置条件
- 时序图：Mermaid
sequenceDiagram，每一步消息都带Step N:编号 - 步骤说明：至少 3 步，与时序图逐一对应
- 异常与边界：输入错误、依赖失败、并发或权限等适用情况
- 追溯：与需求、API、数据库、测试用例的对应关系
场景写清楚之后，Agent 再从时序图判断哪些步骤是 HTTP / RPC / 消息接口、哪些步骤读写数据库，按需补出对应的 API 规格、数据库 Schema 和测试用例（带真实的 UT- / ST- 用例 ID）。
边界：它做什么，不做什么
- 只写能从代码验证的现状事实。代码能说明「系统现在怎么运转」，但说明不了「当初为什么这样设计」。Agent 不会从代码臆造历史背景；需求的 Why 和本次改动的意图，来自你在提案里写的内容。
- 不写骨架。新建的文档必须完整，不允许出现 TODO、占位或「后续补充」。
- 不绕过提案。Agent 不直接写
logos/resources/，补齐的文档一律先进入提案的deltas/，经openlogos merge才成为正式规格；没有活跃提案时，guard 会拦截对正式规格的写入。 - 信息不足时不猜。确实无法从代码判断的产品选择，会在提案阶段列出来交给你决定，而不是编一个答案写进文档。
- verify 不替你判断「该补的是否都补了」。
openlogos verify只检查测试规格里已经声明的用例是否都有执行结果并通过，它不会根据你的业务改动去推算还应该补哪些场景、接口或数据设计。verify 通过不等于本次触达的缺失规格都已补齐——应补的范围和补出来的内容，仍然需要你在审阅提案和 delta 时核对。
OpenLogos 与 RunLogos 各自负责什么
| 环节 | OpenLogos（方法论与 CLI） | RunLogos（桌面工作台） |
|---|---|---|
| 接入存量项目 | openlogos adopt 后建议的下一步直接是 openlogos change <slug>，不强制先建基线 | 接入完成后主按钮就是新建变更，不会先把你带去全库扫描 |
| 写 delta | change-writer Skill 判断目标是否存在；目标缺失时由 scenario-architect Skill 产出完整场景，再派生 API / DB / 测试 | 无人值守驱动在「编写 delta」节点派 Agent 产出；提案阶段流的 Delta 区列出新增文件，点击即可在编辑器中审阅 |
| 合并 | openlogos merge 按磁盘事实判定 MODIFY / CREATE 并原子落盘 | merge 后文档树自动刷新，新文档出现在对应规格目录 |
| 现状证据（可选） | openlogos baseline-seed 可显式预扫全库，只登记模块图和场景候选清单，不是前置条件 | CLI 面板「现状证据（可选）」区显示功能 / 场景清单与「有文档 x/M」；折叠的「可选：全库补写场景文档」里，「让 Agent 补写场景文档」会让 Agent 挑一批还没有文档的场景运行 openlogos change 立案，再由驱动接管提案流程 |
| 验收 | openlogos verify 检查已声明用例的执行结果 | 验收报告面板展示追溯结果 |
上手：在存量项目里用起来
- 接入项目：用 RunLogos 打开现有仓库并完成存量接入（等价于
openlogos adopt），详见 现存项目接入。 - 选一个小功能：挑一个影响范围小、能验收的改动作为第一个试点。
- 创建变更提案：
openlogos change add-export-button
- 写清楚 Why 和验收标准：在
proposal.md里说明为什么要改、改完怎样算对。这部分是 Agent 无法从代码推断的。 - 让 Agent 写 delta：Agent 会读取相关代码。如果这个功能的场景文档还不存在，你会在
deltas/里看到一份标记为「全新场景文档」的完整文档，以及按需派生的 API、数据库和测试用例 delta。 - 审阅补出来的文档：重点看两件事——描述是否符合系统现状；本次触达的场景、接口、数据和测试有没有漏补。不准或漏补，直接修改 delta 或让 Agent 补充。
- 合并规格：确认后执行
openlogos merge add-export-button，新文档落盘为正式规格。 - 实现并验收：按合并后的规格实现代码，运行
openlogos verify。
下次再修改同一个功能时，它的文档已经存在，Agent 会直接走增量修改。
与「全库补写 / 全库扫描」的区别
| 按需补齐（默认） | 全库补写 / 全库扫描（可选） | |
|---|---|---|
| 什么时候发生 | 每次写提案 delta 时，只补本次触达的文档 | 你在 CLI 面板或命令行主动发起 |
| 产出 | 完整的正式规格（场景、API、DB、测试） | 全库扫描只登记模块图和场景候选清单；全库补写会按场景批量立提案，最终仍经提案流程补齐 |
| 是否阻断变更 | 不阻断 | 不阻断，是加速器而不是前置门 |
| 适合 | 绝大多数存量项目的日常迭代 | 想先对全局有一份盘点，或希望集中补齐一批核心场景 |
版本要求
- OpenLogos CLI ≥ 0.15.16（RunLogos 1.0.3 统一的最低版本；当前「merge 时按磁盘事实判定」的规则自 OpenLogos 0.15.0 起生效）
- RunLogos 1.0.3 或更高版本
常见问题
补出来的文档不准怎么办？
在 merge 之前，它只是提案里的一个 delta 文件，可以直接修改，也可以把问题指给 Agent 让它重写。merge 之后发现问题，再用一个新的变更提案修正。
写 delta 阶段会不会顺手改代码？
不会。写 delta 阶段只产出规格文档；代码在规格合并之后、按切片任务才开始实现。
新项目也会触发吗？
会。只要某个 delta 对应的目标文档还不存在，就按「新建完整文档」处理，与项目是新建还是存量接入无关。
我能不能还是先补一轮基线？
可以。如果你希望先把项目背景整体说清楚，可以创建一个专门的提案（例如 add-baseline-docs），或使用 CLI 面板的「可选：全库补写场景文档」。这两种方式都是可选的，不是开始迭代的前置条件。
下一步
→ 现存项目接入