diff --git a/.blueprint/manifest.yaml b/.blueprint/manifest.yaml index 8b09c98..4f17982 100644 --- a/.blueprint/manifest.yaml +++ b/.blueprint/manifest.yaml @@ -528,8 +528,8 @@ modules: - id: intent-catalog name: 意图目录 area: backend - status: planned - progress: 0 + status: in_progress + progress: 15 updated: 2026-10-04 note: "两层模型（人持有的意图目录 .blueprint/catalog.md + 蓝图正文），书装意图、指向事实；卡侧 intent 钉版，agent 编译可判定 /goal，确认卡兼作最小任务简报，回执写进提交。IC1 设计已确认（最小文件优先方案）；IC2–IC4 只新增文档、可与 P8 并行，门控与接线等 P8 收口后做，IC13 按实测数据决定去留。" position: [4000, 950] diff --git a/.blueprint/modules/intent-catalog.md b/.blueprint/modules/intent-catalog.md index b2aad29..7a80251 100644 --- a/.blueprint/modules/intent-catalog.md +++ b/.blueprint/modules/intent-catalog.md @@ -1,6 +1,6 @@ # 意图目录（intent-catalog） -> status: planned | created: 2026-10-04 | 设计：docs/tasks/2026-10-04-intent-catalog-design.md（IC1 ✅，用户 2026-10-04 确认）| 下一步：IC2 +> status: in_progress | created: 2026-10-04 | 设计：docs/tasks/2026-10-04-intent-catalog-design.md（IC1 ✅，用户 2026-10-04 确认）| 指南：docs/ai-context/intent-catalog-guide.md（IC2 ✅）| 下一步：IC3（首批章节由用户定稿） > 来源：2026-10-03～04 与用户讨论（/goal 与 Loop Engineering 操作手册、目录/正文模型、承重墙），以及侦察工作流 wf_6dc3756a-b72 的重叠与冲突扫描。 ## 概述 @@ -103,8 +103,8 @@ agent 开发子项目时躲不掉的现象。每面墙都要回答四个问题 - acceptance: "agent_verify: [读文件] 设计文档含方案选择、设计规格 1–7、13 问化解表、W1–W14 四问表、受影响文件、系统边界变更、风险点、拆解建议、度量与退出、立法草案、没验什么。human_verify: 用户确认设计（含 5 个待拍板问题），确认后模块转 planned 并追加 IC2–IC13。" - notes: 2026-10-04 评审团工作流 wf_60e4c430-bb1 出稿（最小文件优先方案胜出，两位评委 25/30、24/30），设计文档已写，等用户确认。产出 `docs/tasks/<日期>-intent-catalog-design.md`，以 W1–W14 为纲、书模型为体，逐条化解上面的待设计问题，写明收益度量与退出条件；完成后交用户确认，确认后模块转 planned，再用 /splitter 拆成 S/M 卡。 -### 📋 IC2 — 新增 intent-catalog-guide.md：目录语法、修订钉版、goal 编译七步、确认卡与回执、离线检查 -- status: todo +### ✅ IC2 — 新增 intent-catalog-guide.md：目录语法、修订钉版、goal 编译七步、确认卡与回执、离线检查 +- status: done - complexity: S - files: docs/ai-context/intent-catalog-guide.md - depends: IC1 diff --git a/docs/ai-context/intent-catalog-guide.md b/docs/ai-context/intent-catalog-guide.md new file mode 100644 index 0000000..c17beb6 --- /dev/null +++ b/docs/ai-context/intent-catalog-guide.md @@ -0,0 +1,212 @@ +# 意图目录编写与使用指南 + +> 适用对象：所有 agent（Claude Code、Codex、DSH 等）和人。本文件是意图目录语法与 goal 编译流程的**单一来源**。 +> 模块：`.blueprint/modules/intent-catalog.md`。设计依据：`docs/tasks/2026-10-04-intent-catalog-design.md`（临时文件，IC3 后删除）。 +> 试用期（P8 收口前）只用文档和 shell 单行命令；门控脚本 `intent-gate.cjs` 在 Phase 4 落地后替换「离线检查」一节。 + +意图目录 `.blueprint/catalog.md` 是蓝图之上由人持有的一层：每章写一个意图方向、怎么判断做对了、不做什么。任务卡单向挂到章上，agent 据此把意图编译成评估器能判定的 /goal。**书装意图，指向事实**：代码、状态、规格、凭据都不进目录，目录里只放指针。 + +| 角色 | 写什么 | 不写什么 | +|---|---|---| +| 人 | 章的意图、人看、不做；大版本修订；确认小版本、书签切换和 goal 确认卡 | 卡的状态（由 agent 判定）；机器坐标的具体命令 | +| agent | 机器坐标指针、小版本提案、goal 编译、收口回执、卡上的 `- 终验:` 记录 | 章的完成状态（只能推导）；替人改意图 | +| 炼境 | 无，只经 get_project_file 只读提供同一份文件 | 不编译 goal、不选模型、不判定完成 | + +## 目录语法 + +**位置与骨架**：`.blueprint/catalog.md`，放在 modules/ 之外，依次为引言行、书签、各章、墓碑、附录。 + +```markdown +# 意图目录 +> catalog_version: 1.0 | 前言 → path:AGENTS.md#项目定位 | 语法 → path:docs/ai-context/intent-catalog-guide.md + +## 书签 +- 当前 → path:docs/tasks/2026-10-03-coordination.md#0. 方针与本阶段终点 + +## INT-01 <章名：一个意图方向> +- rev: 1.0 +- 意图: <一句话，人的原意> +- 人看: <人在投影上看到什么就算做对了> +- 机器: <可断言坐标的类型化指针，例如 card:#<卡键>> +- 不做: <边界；多条用「；」分隔> + +## INT-09（已撤销） +- 撤销: YYYY-MM-DD → module:#决策记录 + +## 附录 +- <名称> → <类型化指针> +``` + +**章导语字段**： + +| 字段 | 必填 | 含义 | +|---|---|---| +| rev | 是 | 该章最后一次变更时的目录版本，不大于 catalog_version | +| 意图 | 是 | 人的原意，一句话 | +| 人看 | 是 | 人看的投影坐标（对应 human_verify） | +| 机器 | 是 | agent 可断言的坐标，只写指针，不写命令全文 | +| 不做 | 是 | 边界，agent 扩范围时的刹车 | +| 风险 | 否 | 低、中、高，或指向不可逆操作的说明 | +| 假设 | 否 | 指向既有的证伪落点（某张 spike 卡或复盘），目录里不存证伪状态 | +| 证据 | 否 | 指向已有证据（卡上的 verify 记录、PR） | +| 墙 | 否 | 关联的承重墙编号，例如 `W12,W13` | + +**防膨胀（硬限制）**： + +- 每个字段只写一行，不超过 120 字； +- 每个章块不超过 12 行； +- 全文件不超过 200 行、8KB； +- 禁止出现 `status`、`progress`、`doc`、`files`、`acceptance`、`model` 键，也不写模型名； +- 不设文件内修订历史，修订历史看 git log。 + +**类型化指针**（多个指针用「；」分隔）： + +| 前缀 | 写法 | 校验方式 | +|---|---|---| +| path: | `path:<相对路径>[#标题前缀]` | 文件存在；有 `#` 时标题能匹配 | +| module: | `module:[#段名]` | `.blueprint/modules/.md` 存在 | +| card: | `card:#<卡键>` | 该模块里存在这张卡；卡键取标题去掉状态前缀后的第一个 token，例如 `IC6`、`P8e` | +| spec: | `spec:<路径>#标题` | 指向子项目已有的规格（例如 `.specify/specs/...`），只指向不复制 | +| cmd: | `cmd:<命令或工具名>` | 只校验格式，不执行 | +| W | `W1`–`W14` | 承重墙编号，定义见模块文件「承重墙」节 | + +**ID 规则**：章用两位数 `INT-NN`，永不复用。撤销的章保留墓碑 `## INT-NN（已撤销）`，注意编号后面紧跟全角括号、没有空格。 + +**卡侧挂靠（单向）**： + +- 卡上可选写一行 `- intent: INT-NN@X.Y`，放在 `- complexity:` 后面，表示这张卡服务哪一章、编译自目录哪一版。 +- 模块头 blockquote 可选写 `| intent: INT-NN` 作为整个模块的默认挂靠，不带版本，影响分析里计为低置信。 +- 章的「机器:」只是验收坐标，不登记成员名单。反向索引现算，不存储。 + +**终验记录**：卡上另起一行 `- 终验: YYYY-MM-DD 通过|否决：<理由>`，由 agent 记录人在会话里给出的裁决。不要写进 `- notes:`，因为多条 notes 后一条会覆盖前一条。 + +**解析器约束**：模块 md 里，「任务卡」段以外一律不用 `###`。未识别的 `##` 段下出现 `###` 会被当成任务卡。 + +## 修订与钉版 + +**版本**：引言里写一个 `catalog_version: X.Y`；每章有自己的 `rev`。这套版本号与 manifest.iteration 互不借号。 + +| 级别 | 什么时候 | 怎么做 | 版本变化 | +|---|---|---|---| +| 补丁 | 只改正文（卡、模块），目录不动 | agent 自主完成，照常走需求对齐协议 | 无 | +| 小版本 | 改某章的人看、机器或不做；由正文反推修改目录 | agent 提出 S 级三行确认卡，附 diff 和 base blob，人说「确认」 | Y+1；被改章的 rev = 新版本 | +| 大版本 | 增删章节、调整方向 | 人主导，agent 协助起草 | X+1、Y 归零；涉及的章更新 rev；删掉的章留墓碑；按 T4 检查 AGENTS.md「项目定位」 | + +**提案**：附上目录 diff 和 base blob，base blob 用下面的命令取： + +```bash +git rev-parse --short HEAD:.blueprint/catalog.md +``` + +人确认后提交，提交前再取一次 blob。如果已经不等于 base，说明目录被别人改过，必须重新提案，不能硬合。 + +**提交格式**： + +- 首行：`docs(intent): <改了什么>` +- body：一句理由，必要时写来源，例如某次终验否决、某张卡的设计发现。 +- 末尾：带 `Feature-Confirmed: true`。 +- 目录改动单独小提交，不和代码混在一起。 + +**钉版**：卡写 `- intent: INT-NN@X.Y`；goal 标签写 `INT-NN@X.Y#`。 + +**影响分析**： + +| 判定 | 条件 | 处理 | +|---|---|---| +| stale | 卡钉的版本低于章 rev，且卡未完成 | 复核 acceptance。没变化就改钉，算补丁，并在简报里报告；有变化就按小版本走 | +| orphan | 卡钉在已撤销的章上 | 停下找人，决定改挂哪一章还是撤卡 | +| low_confidence | 卡只有模块默认挂靠，没有卡侧钉版 | 编译 goal 前补写卡侧 intent | + +**在制品保护**：钉旧版的 🔵 卡照常做完，只复核 acceptance。章被撤销，或新的「不做」覆盖了这张卡时，停下找人。任何情况下都不自动改写卡。 + +## goal 编译 + +本流程只依赖读文件和 git，不依赖任何特定客户端或模型。Claude 的 /architect 只是可选包装，任何 agent 都可以照着手工执行。产出是一张目标确认卡加一段 /goal 文本。 + +1. **定位** + - 读 `.lian-jing/context.json` 取 project_id；记下当前分支、worktree 路径和 `git rev-parse --short HEAD`。 + - 要求 `git status --porcelain -- .blueprint/catalog.md` 输出为空：目录有未提交改动时不编译。 + - 取 catalog blob：`git rev-parse --short HEAD:.blueprint/catalog.md`。 +2. **读书签**：书签指向当前章（P8 期间指向 coordination §0 的终点）。读该章的导语和 rev。 +3. **校验**：跑「离线检查」一节的全部命令（Phase 4 后改为 `node .claude/hooks/intent-gate.cjs --report INT-NN --impact`）。只要出现悬空指针、stale 或 orphan、防膨胀超限，就先修或先提案，不往下编译。 +4. **收卡** + - 取挂在本章、标题前缀为 📋 或 🔵 的卡。 + - 没有可执行 agent_verify 的卡，列入「须先补 acceptance」，不进 goal。 +5. **合成终点** + - 取各卡 agent_verify 的合取，改写成在会话里能判定的形式：贴出命令和预期输出、纳入卡前缀都是 ✅、回执已写入。 + - human_verify 不进终点，单列为终验待办。 + - 过程词黑名单命中数必须为 0：「按方针」「符合设计」「设计已完成」「基本完成」，以及任何无法从会话输出判定的形容词。 +6. **写停止条件**：遇到以下任一情况必须停下找人： + - human_verify； + - 写运行中的数据库； + - 删除文件、数据或分支； + - 凭据或机器状态变更； + - 超出纳入卡或本章范围； + - 需要修改目录； + - 出现 stale 或 orphan； + - 同一问题失败 3 次。 +7. **输出**：一张目标确认卡（格式见下一节），加 /goal 文本，首行带同样的标签。人读完亲手粘贴就算确认；要改就重新编译。agent 不得自行启动 goal，也不得静默改写 goal 文本。 + +## 确认卡与回执 + +**目标确认卡**（兼作最小任务简报，新会话只读它就能开工）： + +```text +[INT-NN@X.Y#] 目标确认卡 +项目: | 分支/worktree: @ | HEAD: +章意图: <一句> | 不做: <…> +纳入卡: <卡键>（来源 agent_verify 原文）、<卡键>（…） +终点（合取）: 1) <命令> → <预期输出> 2) … 3) 纳入卡均 ✅ 且已写 Goal-Receipt +终验待办: <各卡 human_verify> +停止找人: <第 6 步清单> +能力入口: <校验命令，例如 pnpm typecheck / cargo test；可用的 MCP 工具> +没验什么: <编译时已知的盲区> +作废: 分支变化或 catalog blob ≠ +``` + +由非 Claude 客户端编译时，在提交 body 里另加一行 `Compiled-By: <客户端名>`，用于跨 agent 验证。 + +**收口回执**：goal 收口时写进收口提交的 body；M 级同时复制到 PR body；炼境在线时可以再调一次 append_project_note。 + +```text +Goal-Receipt: INT-NN@X.Y# +Goal-Cards: <纳入卡键列表> +Goal-Result: 判对|误判|中止(<原因>) +Goal-Rounds: <轮数> +Goal-Interventions: <人工介入次数> +Goal-Tokens: <客户端可得时填，否则 n/a> +Not-Verified: <没验什么> +Human-Pending: <待人终验项> +``` + +回执不写进模块决策记录，因为 UI 会把它当决策展示；也不要手改 `.blueprint/notes-archive.jsonl`，它以炼境 DB 为事实源，会被整文件重写。 + +## 离线检查 + +试用期的检查全部是 shell 单行命令，在仓库根目录执行。期望输出写在每条后面的注释里。 + +```bash +# 1. 版本行恰好一行 +grep -c '^> catalog_version: ' .blueprint/catalog.md # → 1 +# 2. 有效章数（墓碑不计） +grep -cE '^## INT-[0-9]{2} ' .blueprint/catalog.md # → 章数 +# 3. 体量 +wc -l < .blueprint/catalog.md; wc -c < .blueprint/catalog.md # → ≤200 行、≤8192 字节 +# 4. 禁用键与模型名 +grep -cE '^- (status|progress|doc|files|acceptance|model):' .blueprint/catalog.md # → 0 +# 5. path 指针可解析（没有输出即通过） +grep -oE 'path:[^ #；|]+' .blueprint/catalog.md | sed 's/^path://' | sort -u | while read -r p; do test -e "$p" || echo "悬空: $p"; done +# 6. module 指针可解析（没有输出即通过） +grep -oE 'module:[a-z0-9-]+' .blueprint/catalog.md | sed 's/^module://' | sort -u | while read -r m; do test -e ".blueprint/modules/$m.md" || echo "悬空: $m"; done +# 7. 卡侧 intent 引用的章都存在且未撤销（没有输出即通过） +comm -23 <(grep -hoE '^- intent: INT-[0-9]{2}' .blueprint/modules/*.md | grep -oE 'INT-[0-9]{2}' | sort -u) <(grep -oE '^## INT-[0-9]{2} ' .blueprint/catalog.md | grep -oE 'INT-[0-9]{2}' | sort -u) +# 8. 钉版与章 rev 对照（人工比对：钉的版本低于 rev 且卡未完成，即为 stale） +grep -hoE 'intent: INT-[0-9]{2}@[0-9]+\.[0-9]+' .blueprint/modules/*.md | sort | uniq -c +awk '/^## INT-[0-9]{2} /{c=$2} /^- rev:/{print c, $3}' .blueprint/catalog.md +# 9. 改模块 md 前后的任务卡计数应相等（新增卡时等于新增数），防止误写 ### +cat .blueprint/modules/*.md | grep -c '^### ' +# 10. goal 文本的过程词黑名单（把 /goal 文本存成临时文件后检查） +grep -cE '按方针|符合设计|设计已完成|基本完成' # → 0 +``` + +card: 指针目前只能人工核对，到模块文件里搜索卡键，Phase 4 后由门控自动校验。指针中带 `#标题` 的部分，也是同样的人工核对方式。