dev-manager-tauri/docs/ai-context/intent-catalog-guide.md

意图目录编写与使用指南

适用对象：所有 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/ 之外，依次为引言行、书签、各章、墓碑、附录。

# 意图目录
> 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:<module>#<卡键>>
- 不做: <边界；多条用「；」分隔>

## INT-09（已撤销）
- 撤销: YYYY-MM-DD → module:<id>#决策记录

## 附录
- <名称> → <类型化指针>

章导语字段：

字段	必填	含义
rev	是	该章最后一次变更时的目录版本，不大于 catalog_version
意图	是	人的原意，一句话
人看	是	人看的投影坐标（对应 human_verify）
机器	是	agent 可断言的坐标，只写指针，不写命令全文
不做	是	边界，agent 扩范围时的刹车
风险	否	低、中、高，或指向不可逆操作的说明
假设	否	指向既有的证伪落点（某张 spike 卡或复盘），目录里不存证伪状态
证据	否	指向已有证据（卡上的 verify 记录、PR）
墙	否	关联的承重墙编号，例如 W12,W13
形态	否	定型（缺省）或 探索；只能由人确认修改，见「探索章与结晶」

不必开章的情况：只是修修补补的卡，照常做，不写 intent；属于某个已有章的，就挂上去，算补丁级。完全没有意图、直接做 MVP 的，先不开章，做两三轮以后再从试用反馈里提炼。目录和卡侧 intent 都是可选的，不会挡住任何工作。

防膨胀（硬限制）：

• 每个字段只写一行，不超过 120 字；
• 每个章块不超过 12 行；
• 全文件不超过 200 行、8KB；
• 禁止出现 status、progress、doc、files、acceptance、model 键，也不写模型名；
• 不设文件内修订历史，修订历史看 git log。

类型化指针（多个指针用「；」分隔）：

前缀	写法	校验方式
path:	path:<相对路径>[#标题前缀]	文件存在；有 # 时标题能匹配
module:	module:<id>[#段名]	.blueprint/modules/<id>.md 存在
card:	card:<module>#<卡键>	该模块里存在这张卡；卡键取标题去掉状态前缀后的第一个 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 用下面的命令取：

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#<blob7>。

影响分析：

判定	条件	处理
stale	卡钉的版本低于章 rev，且卡未完成	复核 acceptance。没变化就改钉，算补丁，并在简报里报告；有变化就按小版本走
orphan	卡钉在已撤销的章上	停下找人，决定改挂哪一章还是撤卡
low_confidence	卡只有模块默认挂靠，没有卡侧钉版	编译 goal 前补写卡侧 intent

在制品保护：钉旧版的 🔵 卡照常做完，只复核 acceptance。章被撤销，或新的「不做」覆盖了这张卡时，停下找人。任何情况下都不自动改写卡。

探索章与结晶

意图常常不是一开始就清楚的，而是做 MVP、反复试用以后才长出来。探索章就是给这种情况用的：先写下在找什么、找多久，等意图结晶出来再改成定型章。

## INT-04 <轮廓名>
- rev: 1.1
- 形态: 探索
- 轮廓: <人的原话，模糊也可以>
- 试探: <这一阶段想弄清的问题，例如「哪种交互最顺手」>
- 不做: <再模糊也要有的边界>
- 预算: <最多 N 轮 MVP 或 N 天>
- 收敛信号: <出现什么就说明方向定了，例如「连续两轮不再想改核心交互」>
- 证据: <各轮试验卡的指针>

	定型章	探索章
必填	rev、意图、人看、机器、不做	rev、形态: 探索、轮廓、试探、不做、预算、收敛信号
回答	做到什么样算对	我们在找什么、找多久
goal 终点	交付终点	每轮试验的终点
度量	goal 一次判对率	几轮收敛、是否守住预算、否决理由是否越来越少

每轮试验：

• 拆一张试验卡，挂到探索章上：- intent: INT-NN@X.Y。
• 人试用后，agent 把反应记成卡上的终验行：- 终验: YYYY-MM-DD 保留|否决：<理由>。
• 这些保留和否决的理由，就是结晶的原料。

结晶（探索 → 定型）：

• 收敛信号出现，或预算用完时，agent 汇总各轮终验行，起草「意图提炼」：建议的意图、人看、机器、不做，以及依据（哪几轮保留、哪几轮否决、为什么）。
• 人确认后，形态改为定型，按小版本修订：Y+1，本章 rev 更新，轮廓、试探、预算、收敛信号几行换成意图、人看、机器。

预算用完仍未收敛：由人三选一：

• 追加预算继续，小版本；
• 换方向重写轮廓，小版本；
• 放弃，大版本，留墓碑。

agent 不得自行延长预算。

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）。
   • 机器检查（第 1–7、9–11 条）必须全部通过。
   • 第 8 条（钉版对照）和 card:、#标题 指针属于人工核对，核对结果写进确认卡；门控落地后改为全自动。
   • 只要出现悬空指针、stale 或 orphan、防膨胀超限，就先修或先提案，不往下编译。
4. 收卡
   • 检查各纳入卡的 depends，未满足的写进确认卡的「前置」行。只要有未满足的前置，就只能做纸面编译，不能粘贴执行。
   • depends 尽量写卡键或模块 id。像「P8 收口」这样的自然语言前置，要在确认卡里写明人工判定的结果。
   • 取挂在本章、标题前缀为 📋 或 🔵 的卡。
   • 没有可执行 agent_verify 的卡，列入「须先补 acceptance」，不进 goal。
5. 合成终点
   • 取各卡 agent_verify 的合取，改写成在会话里能判定的形式：贴出命令和预期输出、纳入卡前缀都是 ✅、回执已写入。
   • human_verify 不进终点，单列为终验待办。
   • 过程词黑名单命中数必须为 0：「按方针」「符合设计」「设计已完成」「基本完成」「符合预期」，以及任何无法从会话输出判定的形容词。
   • 确认卡和 /goal 文本里的终点写法必须一致，都写「命令 → 预期输出」。不能 /goal 里写得精确，确认卡里却改写成「均符合预期」。
   • 探索章不编译「意图的终点」，只编译本轮试验的终点：
     • 做出可试用的 MVP 变体，写明最小动作和可演示方式；
     • 校验命令通过；
     • 试验卡为 ✅ 且已写回执。
     • 人的试用反馈作为终验待办，记到终验行。
     • 确认卡写明这是第几轮、共几轮预算；超出预算就不编译，转入结晶或请人三选一。
6. 写停止条件：遇到以下任一情况必须停下找人：
   • human_verify；
   • 写运行中的数据库；
   • 删除文件、数据或分支；
   • 凭据或机器状态变更；
   • 超出纳入卡或本章范围；
   • 需要修改目录；
   • 出现 stale 或 orphan；
   • 同一问题失败 3 次。
7. 输出：一张目标确认卡（格式见下一节），加 /goal 文本，首行带同样的标签。人读完亲手粘贴就算确认；要改就重新编译。agent 不得自行启动 goal，也不得静默改写 goal 文本。

确认卡与回执

目标确认卡（兼作最小任务简报，新会话只读它就能开工）：

[INT-NN@X.Y#<blob7>] 目标确认卡
项目: <project_id> | 分支/worktree: <branch> @ <path> | HEAD: <sha7>
章意图: <一句> | 不做: <…>
前置: <各纳入卡的 depends 及是否满足；有未满足的，注明「仅纸面」>
形态: 定型 | 探索（第 k/N 轮；收敛信号: <…>）
纳入卡: <卡键>（来源 agent_verify 原文）、<卡键>（…）
终点（合取）: 1) <命令> → <预期输出>  2) …  3) 纳入卡均 ✅ 且已写 Goal-Receipt
终验待办: <各卡 human_verify>
停止找人: <第 6 步清单>
能力入口: <校验命令，例如 pnpm typecheck / cargo test；可用的 MCP 工具>
没验什么: <编译时已知的盲区>
作废: 分支变化或 catalog blob ≠ <blob7>

由非 Claude 客户端编译时，在提交 body 里另加一行 Compiled-By: <客户端名>，用于跨 agent 验证。

收口回执：goal 收口时写进收口提交的 body；M 级同时复制到 PR body；炼境在线时可以再调一次 append_project_note。

Goal-Receipt: INT-NN@X.Y#<blob7>
Goal-Cards: <纳入卡键列表>
Goal-Result: 判对|误判|中止(<原因>)
Goal-Rounds: <轮数>
Goal-Interventions: <人工介入次数>
Goal-Tokens: <客户端可得时填，否则 n/a>
Not-Verified: <没验什么>
Human-Pending: <待人终验项>

回执不写进模块决策记录，因为 UI 会把它当决策展示；也不要手改 .blueprint/notes-archive.jsonl，它以炼境 DB 为事实源，会被整文件重写。

离线检查

试用期的检查全部是 shell 单行命令，在仓库根目录执行。期望输出写在每条后面的注释里。

• 没有 Bash 时：命令按 POSIX shell（Git Bash）写成。部分客户端的沙箱里起不了 Bash，这时可以用语义等价的命令（PowerShell 等），并在确认卡的「没验什么」里注明用了哪种替代。
• 一律逐行解析：不要对整份文件跑一个正则，字符类会跨行吞掉换行符，把有效指针误报成悬空。
• 只读演练不写盘：所有检查都用管道或内存字符串完成，不创建临时文件。

# 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; git cat-file -s HEAD:.blueprint/catalog.md   # → ≤200 行、≤8192 字节（量提交里的 blob；工作区可能是 CRLF，wc -c 会多算换行）
# 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 文本的过程词黑名单（用管道检查，不写临时文件）
printf '%s\n' "$GOAL_TEXT" | grep -cE '按方针|符合设计|设计已完成|基本完成|符合预期'   # → 0
# 11. 探索章的必填字段齐全（没有输出即通过）
awk '/^## /{if(e&&!(b&&s))print "缺预算或收敛信号: "c; c=$2;e=0;b=0;s=0} /^- 形态: 探索/{e=1} /^- 预算:/{b=1} /^- 收敛信号:/{s=1} END{if(e&&!(b&&s))print "缺预算或收敛信号: "c}' .blueprint/catalog.md

card: 指针目前只能人工核对，到模块文件里搜索卡键，Phase 4 后由门控自动校验。指针中带 #标题 的部分，也是同样的人工核对方式。