artifact-chain-assistant 0.14.1 → 0.14.2

package/site/00-matrix.html

@@ -73,6 +73,6 @@
 <div class="nav-group"><p>进阶</p><a href="06-method-registry.html">方法注册表</a></div>
 <div class="nav-group"><p>参考</p><a href="07-glossary.html">术语库</a><a href="08-maintainer.html">维护者视角</a><a href="09-troubleshoot.html">排错</a><a href="10-roadmap.html">路线图</a></div></nav></dialog>
   <div class="toast" id="editorial-toast" role="status" aria-live="polite"></div>
-  <script id="editorial-search-data" type="application/json">[{"title":"枢纽 · 学习地图","page":"枢纽 · 学习地图","href":"index.html","content":"本站把 artifact-graph 与 artifact-chain-assistant 当成一件事来讲：用一套可复现、Git 原生的方法，把「为什么做、做了什么、怎么验证」连成机器能验的链路。 artifact-graph 是底层运行时、CLI 与 Node 库，负责扫描制品、建图与校验。artifact-chain-assistant 是上层插件，把这套工作法接到 Codex、Claude Code 与 Kimi Code 的日常会话；Qoder 以技能兼容宿主复用同一套共享技能。第一次接触时，先完成下面的只读入口，再按角色选页。 当前插件源版本是 0.14.1。本地源版本不等于已发布或已安装版本；安装与配对以 INSTALL.md 和 compatibility.json 为准。 先跑起来 装好插件后，第一件事是只读查看 Family API（标准族接口）和采用步骤；拿不准该用哪个技能时，交给 artifact-chain-quickstart 分流。这两条都不会改项目文件。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-quickstart，根据当前问题推荐正确入口，不要修改项目。 环境不明时用 artifact-chain-setup 做只读体检。要把一个目标项目接进制品链，再经明确授权走 artifact-chain-bootstrap。 按角色选路径 新使用者：先读它是什么，再按场景剧本抄一条能完成的路径；卡住时查排错与兼容。 已在使用、要看原理：读架构原理、核心概念和方法注册表。 发版维护者：重点看维护者视角与路线图。路线图用状态区分已落地能力与未授权方向。 能力一览 页面 读完能做什么 双工程能力矩阵 对照常规研发做法与制品链做法 它是什么 判断这套工具解决谁的问题、两工程如何配合 架构原理 核对三层边界、Git 原生、关系锁与契约内核 核心概念 辨认制品类型、追溯边、上下文包与评审协议 命令参考 按 artifact-graph --help 查命令，不另造一份会过期的表 场景剧本 按六条常见任务完成第一次接入 方法注册表 理解 Family API 与 Registry 如何把能力落到实现 术语库 查阅本站反复使用的术语 维护者视角 把泄漏扫描、摘要锁和链接边界接进发布门禁 排错与兼容 先体检再按症状恢复 路线图 区分已实现、规划中与未授权方向 怎么读 不必按目录从头读到尾。先完成「先跑起来」，再从当前最痛的场景翻对应页：接项目看场景页，排错看排错页，原理看架构与概念页。各页自包含，跳读不会丢掉入口。 能力第一次出现会标明状态。已实现表示已有决策与代码；方向、未授权表示长期记录，不能当成现状；规划中表示增强路径已写下、方案仍待决策。 旧站的术语气泡依赖自有脚本。本版由 editorial 模板提供导航、搜索与提示词复制；术语定义集中在术语库。"},{"title":"先跑起来","page":"枢纽 · 学习地图","href":"index.html#start","content":"装好插件后，第一件事是只读查看 Family API（标准族接口）和采用步骤；拿不准该用哪个技能时，交给 artifact-chain-quickstart 分流。这两条都不会改项目文件。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-quickstart，根据当前问题推荐正确入口，不要修改项目。 环境不明时用 artifact-chain-setup 做只读体检。要把一个目标项目接进制品链，再经明确授权走 artifact-chain-bootstrap。"},{"title":"按角色选路径","page":"枢纽 · 学习地图","href":"index.html#paths","content":"新使用者：先读它是什么，再按场景剧本抄一条能完成的路径；卡住时查排错与兼容。 已在使用、要看原理：读架构原理、核心概念和方法注册表。 发版维护者：重点看维护者视角与路线图。路线图用状态区分已落地能力与未授权方向。"},{"title":"能力一览","page":"枢纽 · 学习地图","href":"index.html#pages","content":"页面 读完能做什么 双工程能力矩阵 对照常规研发做法与制品链做法 它是什么 判断这套工具解决谁的问题、两工程如何配合 架构原理 核对三层边界、Git 原生、关系锁与契约内核 核心概念 辨认制品类型、追溯边、上下文包与评审协议 命令参考 按 artifact-graph --help 查命令，不另造一份会过期的表 场景剧本 按六条常见任务完成第一次接入 方法注册表 理解 Family API 与 Registry 如何把能力落到实现 术语库 查阅本站反复使用的术语 维护者视角 把泄漏扫描、摘要锁和链接边界接进发布门禁 排错与兼容 先体检再按症状恢复 路线图 区分已实现、规划中与未授权方向"},{"title":"怎么读","page":"枢纽 · 学习地图","href":"index.html#how-to-read","content":"不必按目录从头读到尾。先完成「先跑起来」，再从当前最痛的场景翻对应页：接项目看场景页，排错看排错页，原理看架构与概念页。各页自包含，跳读不会丢掉入口。 能力第一次出现会标明状态。已实现表示已有决策与代码；方向、未授权表示长期记录，不能当成现状；规划中表示增强路径已写下、方案仍待决策。 旧站的术语气泡依赖自有脚本。本版由 editorial 模板提供导航、搜索与提示词复制；术语定义集中在术语库。"},{"title":"双工程能力矩阵","page":"双工程能力矩阵","href":"00-matrix.html","content":"这一页是理解支点。左侧是常规研发已经在做的事，右侧是同一件事在制品链范式下的做法。学习重点落在差异：右侧多出来的约束，用来处理「助手宣称完成、链路其实断着」的问题。 两个工程分别管什么 维度 常规做法 制品链做法 归属 图能力 文档之间靠人记关系，没有工具校验 配置读取、制品扫描、索引、边关系、查询、校验、版本锁 artifact-graph（底层运行时 / CLI） 助手能力 编辑器补全、零散脚本 profile、模板、bootstrap、maintainer、where-am-i、宿主适配器、hook 指导 artifact-chain-assistant（上层插件） 事实来源 散在 wiki、脑图或口头约定 单一 Git 仓库，Git 原生即事实来源 两者共用 结果可信度 「改完了」靠人判断 评审结果协议：默认失败关闭、身份稳定、禁止自我接受 两者共用 安装与运行对照 环节 常规 制品链 安装 未锁定范围的工具依赖 按 INSTALL.md 与 compatibility.json 安装已验证的精确 artifact-graph，禁止未锁定范围 构建 各自 CI 脚本 pnpm 10 会拦下原生构建，必须显式允许 better-sqlite3 校验 单测 / lint artifact-graph validate 与 version-lock audit 初始化 手写配置 artifact-chain-bootstrap 引导；context.universal_baseline 默认开启，未设好时第一次取上下文会非零退出 安全第一步 常被跳过 artifact-chain-setup 与 artifact-graph doctor 只读体检 先看清当前项目位置 不必读完整站。下面两条只读请求用于查看 Family API 与环境位置。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 拿不准下一步时走 artifact-chain-quickstart。正式把目标项目接进来，再授权 artifact-chain-bootstrap。 边界对照 常见误解 实际边界 替业务写实现代码 不管。它管产出是否可追溯、可验证 当成普通依赖 lockfile 不是。version-lock 锁的是追溯关系，同时也是一次提交的事务边界 当成又一个文档站生成器 不是。知识站只是发布阅读面；工具本身产出图与锁 重组制品靠助手直接改文件 不是。语义决定留在技能层，文件集合写入由 restructure 确定性执行，且需操作者确认 重组能力写在哪一层 维度 制品链做法 归属 语义决定 功能边界、共同约束、验收项去向、关系迁移 技能层（artifact-chain-restructure） 确定性执行 检查、候选计划编译、文件集合应用与恢复 artifact-graph restructure 独立复审 只读核对候选与映射，结论绑定被复审的候选 技能层 写入前提 操作者显式确认合作式写者；恢复需显式双维护确认 操作者，机制不自证 采用边界要一并说清，否则容易把候选能力当成已发布保证： 写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS；其他平台返回不可用， 不降级到无事务写入，也不承诺全平台事务保证。 前提是合作式写者。apply 与 prune-recovery 缺少 --confirm-cooperative-writers 即拒绝； recover 缺少停止与独占维护两个确认即返回 MAINTENANCE_CONFIRMATION_REQUIRED。 恢复材料默认保留，只有显式 prune-recovery 才清理。 孤儿锁默认保留；清理要么整体 --remove-orphans，要么按边精确 --remove-orphan-edge \u003cedgeId\u003e，两者互斥。 把下面三条同时成立，才值得引入制品链：助手参与写研发产物；「做完」需要被机器验证；接受 Git 作为唯一事实来源。任一条件不成立，继续用现有文档与 CI 即可。"},{"title":"两个工程分别管什么","page":"双工程能力矩阵","href":"00-matrix.html#roles","content":"维度 常规做法 制品链做法 归属 图能力 文档之间靠人记关系，没有工具校验 配置读取、制品扫描、索引、边关系、查询、校验、版本锁 artifact-graph（底层运行时 / CLI） 助手能力 编辑器补全、零散脚本 profile、模板、bootstrap、maintainer、where-am-i、宿主适配器、hook 指导 artifact-chain-assistant（上层插件） 事实来源 散在 wiki、脑图或口头约定 单一 Git 仓库，Git 原生即事实来源 两者共用 结果可信度 「改完了」靠人判断 评审结果协议：默认失败关闭、身份稳定、禁止自我接受 两者共用"},{"title":"安装与运行对照","page":"双工程能力矩阵","href":"00-matrix.html#install","content":"环节 常规 制品链 安装 未锁定范围的工具依赖 按 INSTALL.md 与 compatibility.json 安装已验证的精确 artifact-graph，禁止未锁定范围 构建 各自 CI 脚本 pnpm 10 会拦下原生构建，必须显式允许 better-sqlite3 校验 单测 / lint artifact-graph validate 与 version-lock audit 初始化 手写配置 artifact-chain-bootstrap 引导；context.universal_baseline 默认开启，未设好时第一次取上下文会非零退出 安全第一步 常被跳过 artifact-chain-setup 与 artifact-graph doctor 只读体检"},{"title":"先看清当前项目位置","page":"双工程能力矩阵","href":"00-matrix.html#do-now","content":"不必读完整站。下面两条只读请求用于查看 Family API 与环境位置。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 拿不准下一步时走 artifact-chain-quickstart。正式把目标项目接进来，再授权 artifact-chain-bootstrap。"},{"title":"边界对照","page":"双工程能力矩阵","href":"00-matrix.html#boundaries","content":"常见误解 实际边界 替业务写实现代码 不管。它管产出是否可追溯、可验证 当成普通依赖 lockfile 不是。version-lock 锁的是追溯关系，同时也是一次提交的事务边界 当成又一个文档站生成器 不是。知识站只是发布阅读面；工具本身产出图与锁 重组制品靠助手直接改文件 不是。语义决定留在技能层，文件集合写入由 restructure 确定性执行，且需操作者确认"},{"title":"重组能力写在哪一层","page":"双工程能力矩阵","href":"00-matrix.html#restructure-layer","content":"维度 制品链做法 归属 语义决定 功能边界、共同约束、验收项去向、关系迁移 技能层（artifact-chain-restructure） 确定性执行 检查、候选计划编译、文件集合应用与恢复 artifact-graph restructure 独立复审 只读核对候选与映射，结论绑定被复审的候选 技能层 写入前提 操作者显式确认合作式写者；恢复需显式双维护确认 操作者，机制不自证 采用边界要一并说清，否则容易把候选能力当成已发布保证： 写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS；其他平台返回不可用， 不降级到无事务写入，也不承诺全平台事务保证。 前提是合作式写者。apply 与 prune-recovery 缺少 --confirm-cooperative-writers 即拒绝； recover 缺少停止与独占维护两个确认即返回 MAINTENANCE_CONFIRMATION_REQUIRED。 恢复材料默认保留，只有显式 prune-recovery 才清理。 孤儿锁默认保留；清理要么整体 --remove-orphans，要么按边精确 --remove-orphan-edge \u003cedgeId\u003e，两者互斥。 把下面三条同时成立，才值得引入制品链：助手参与写研发产物；「做完」需要被机器验证；接受 Git 作为唯一事实来源。任一条件不成立，继续用现有文档与 CI 即可。"},{"title":"它是什么","page":"它是什么","href":"01-what.html","content":"一句话：这是一套让助手写出来的研发产物能追溯、并让机器判断链路是否首尾相接的工具与方法。它处理一个很具体的缺口——助手说「做完了」，与链路真正接上之间，常常隔着一层无法自动验证的空隙。 先看它能做什么 不必先读完原理。插件装好后，第一件事是跑 artifact-chain-help。它只读列出当前可见的 Family API 和采用步骤，也就是接下来能用的能力清单。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 拿不准从哪下手时，改用 artifact-chain-quickstart。要把目标项目接进来，再经授权走 artifact-chain-bootstrap。 解决谁的问题 使用者：要把「需求 → 场景 → 设计 → 实现 → 评审」串成可验证图，不愿只靠人记关系。 维护者：对外发开源时，要守住许可证、NOTICE 与私有边界。 助手：需要以稳定、机器能消费的方式拿到上下文和评审结果协议。 两个工程是什么关系 artifact-graph 是底层：Git 原生的 Markdown 制品图扫描与校验器（命令行 / Node 库）。artifact-chain-assistant 是上层：Codex、Claude Code 与 Kimi Code 插件，把底层能力接到日常会话；Qoder 复用共享技能，不承诺命令包装或 Stop hook 等价。 层 角色 状态 通用图内核多领域拆分 不加载领域默认值的长期方向 方向，未授权 artifact-graph 确定性图能力：配置、扫描、索引、边、查询、校验、版本锁 已实现 artifact-chain-assistant 通用助手：profile、模板、bootstrap、maintainer、适配器、hook 已实现 表中第一行是长期架构方向，还没有实施授权。不要把它和已经落地的 artifact-graph 混为一谈。 和「只写文档 / 只跑 CI」差在哪 做法 它做到什么程度 只写文档 关系靠人记，机器验不了；制品链把关系变成图与边 只跑 CI 校验代码对不对，不校验「为什么做」这条链有没有接上 制品链 文档即图、图即约束、锁即提交边界；助手产出要经过失败关闭的评审协议 已经落地的能力 契约内核：运行时侧一组稳定契约接口，上层统一调用图能力。 标准 Family API：一类制品的通用操作抽象成标准族，新类型靠配置接入。 Registry（方法注册表）公共接口：身份、清单、绑定、投影与方法选择；助手按已锁定版本接线，不复制实现身份。 doctor / artifact-chain-setup：接入之后的环境自检第一步。 判断是否需要它，看三条是否同时成立：助手参与写研发产物；要求「做完」能被机器验证；接受 Git 作为唯一事实来源。"},{"title":"先看它能做什么","page":"它是什么","href":"01-what.html#first-look","content":"不必先读完原理。插件装好后，第一件事是跑 artifact-chain-help。它只读列出当前可见的 Family API 和采用步骤，也就是接下来能用的能力清单。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 拿不准从哪下手时，改用 artifact-chain-quickstart。要把目标项目接进来，再经授权走 artifact-chain-bootstrap。"},{"title":"解决谁的问题","page":"它是什么","href":"01-what.html#who","content":"使用者：要把「需求 → 场景 → 设计 → 实现 → 评审」串成可验证图，不愿只靠人记关系。 维护者：对外发开源时，要守住许可证、NOTICE 与私有边界。 助手：需要以稳定、机器能消费的方式拿到上下文和评审结果协议。"},{"title":"两个工程是什么关系","page":"它是什么","href":"01-what.html#two-projects","content":"artifact-graph 是底层：Git 原生的 Markdown 制品图扫描与校验器（命令行 / Node 库）。artifact-chain-assistant 是上层：Codex、Claude Code 与 Kimi Code 插件，把底层能力接到日常会话；Qoder 复用共享技能，不承诺命令包装或 Stop hook 等价。 层 角色 状态 通用图内核多领域拆分 不加载领域默认值的长期方向 方向，未授权 artifact-graph 确定性图能力：配置、扫描、索引、边、查询、校验、版本锁 已实现 artifact-chain-assistant 通用助手：profile、模板、bootstrap、maintainer、适配器、hook 已实现 表中第一行是长期架构方向，还没有实施授权。不要把它和已经落地的 artifact-graph 混为一谈。"},{"title":"和「只写文档 / 只跑 CI」差在哪","page":"它是什么","href":"01-what.html#diff","content":"做法 它做到什么程度 只写文档 关系靠人记，机器验不了；制品链把关系变成图与边 只跑 CI 校验代码对不对，不校验「为什么做」这条链有没有接上 制品链 文档即图、图即约束、锁即提交边界；助手产出要经过失败关闭的评审协议"},{"title":"已经落地的能力","page":"它是什么","href":"01-what.html#landed","content":"契约内核：运行时侧一组稳定契约接口，上层统一调用图能力。 标准 Family API：一类制品的通用操作抽象成标准族，新类型靠配置接入。 Registry（方法注册表）公共接口：身份、清单、绑定、投影与方法选择；助手按已锁定版本接线，不复制实现身份。 doctor / artifact-chain-setup：接入之后的环境自检第一步。 判断是否需要它，看三条是否同时成立：助手参与写研发产物；要求「做完」能被机器验证；接受 Git 作为唯一事实来源。"},{"title":"架构原理","page":"架构原理","href":"02-architecture.html","content":"这套结构要把助手写出来的研发产物变成一张 Git 原生、结果可复现的图。底下三层、一个内核契约、一份关系锁，各管各的事。先跑两条命令，确认这座架构是否已经立在目标项目里。 现场核对 artifact-graph doctor --format markdown artifact-graph validate --root . --warning-only 两条都给出可读结果，说明底层图能力已经接到当前项目。validate --warning-only 退出 0 仍可能包含问题，必须读 issues，不能把退出码当成图健康。插件侧等价的第一步是 artifact-chain-setup。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 三层边界 当前落地的是业务三层，互不越界： 图内核：读配置、扫制品、算关系、跑查询。当前仍内置软件领域默认类型，包括 decision、entity、feature、scenario、design 以及测试相关类型，并执行默认约束，例如禁止 scenario 直接引用 entity。项目配置可以覆盖路径和字段，这些默认值仍然来自内核。 通用助手（artifact-chain-assistant）：把内核接到开发会话，负责 profile、模板、bootstrap、适配器与 hook 指导。它调用内核，不改内核。 目标项目：自行决定制品类型、模板与技能。配置写在项目的 artifact-graph.config.yaml。覆盖配置不会把内核变成「没有领域默认值」。 调用方向是上层调下层，下层不反向依赖上层。基础工程不反向依赖领域工程，不同领域工程不互相导入内部技能。 不带领域默认值的通用内核仍是长期方向，尚未授权实施。把方向写成现状，会误导后续实现。现行默认类型与约束以本页「三层边界」为准，不把路线图的方向记录当成当前行为。 两个底层约定 Git 原生：制品就是仓库里的文件，关系留在 Git 历史里。不另起数据库，不依赖在线服务；克隆下来就能跑，离网也能验。 确定性：同样的输入得到同样的结果。助手说「做完了」之前，本地校验必须能复现、能机器判定。配置与源文件固定，输出就固定，不随执行者或机器变化。 关系怎么锁住 version-lock（关系锁）记录哪些制品关系已经确认、对应哪次内容。它不是依赖 lockfile，而是追溯关系的版本化基线，同时也是一次提交的边界：关系变了，锁就要一起刷新、一起提交。CI 常用： artifact-graph version-lock audit --root . --strict-missing-lock 来卡住「源变了但锁没刷」的漂移。禁止在 hook 或自动修复里跑 version-lock bootstrap --force，那会掩盖陈旧关系。 能力怎么长出来 Contract Kernel（契约内核）是内核对外能力的稳定边界。标准 Family API 是各业务族接入的统一接口。两者合起来，让「新增一类制品或一种能力」变成填配置，而不是改内核代码。 要在插件侧看现在有哪些 Family API 和采用步骤，运行 artifact-chain-help；拿不准入口时走 artifact-chain-quickstart。完整命令表见命令参考。当前默认类型仍由内核提供；不加载领域默认值是长期方向，见路线图。"},{"title":"现场核对","page":"架构原理","href":"02-architecture.html#verify","content":"artifact-graph doctor --format markdown artifact-graph validate --root . --warning-only 两条都给出可读结果，说明底层图能力已经接到当前项目。validate --warning-only 退出 0 仍可能包含问题，必须读 issues，不能把退出码当成图健康。插件侧等价的第一步是 artifact-chain-setup。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。"},{"title":"三层边界","page":"架构原理","href":"02-architecture.html#layers","content":"当前落地的是业务三层，互不越界： 图内核：读配置、扫制品、算关系、跑查询。当前仍内置软件领域默认类型，包括 decision、entity、feature、scenario、design 以及测试相关类型，并执行默认约束，例如禁止 scenario 直接引用 entity。项目配置可以覆盖路径和字段，这些默认值仍然来自内核。 通用助手（artifact-chain-assistant）：把内核接到开发会话，负责 profile、模板、bootstrap、适配器与 hook 指导。它调用内核，不改内核。 目标项目：自行决定制品类型、模板与技能。配置写在项目的 artifact-graph.config.yaml。覆盖配置不会把内核变成「没有领域默认值」。 调用方向是上层调下层，下层不反向依赖上层。基础工程不反向依赖领域工程，不同领域工程不互相导入内部技能。 不带领域默认值的通用内核仍是长期方向，尚未授权实施。把方向写成现状，会误导后续实现。现行默认类型与约束以本页「三层边界」为准，不把路线图的方向记录当成当前行为。"},{"title":"两个底层约定","page":"架构原理","href":"02-architecture.html#invariants","content":"Git 原生：制品就是仓库里的文件，关系留在 Git 历史里。不另起数据库，不依赖在线服务；克隆下来就能跑，离网也能验。 确定性：同样的输入得到同样的结果。助手说「做完了」之前，本地校验必须能复现、能机器判定。配置与源文件固定，输出就固定，不随执行者或机器变化。"},{"title":"关系怎么锁住","page":"架构原理","href":"02-architecture.html#version-lock","content":"version-lock（关系锁）记录哪些制品关系已经确认、对应哪次内容。它不是依赖 lockfile，而是追溯关系的版本化基线，同时也是一次提交的边界：关系变了，锁就要一起刷新、一起提交。CI 常用： artifact-graph version-lock audit --root . --strict-missing-lock 来卡住「源变了但锁没刷」的漂移。禁止在 hook 或自动修复里跑 version-lock bootstrap --force，那会掩盖陈旧关系。"},{"title":"能力怎么长出来","page":"架构原理","href":"02-architecture.html#kernel-and-family","content":"Contract Kernel（契约内核）是内核对外能力的稳定边界。标准 Family API 是各业务族接入的统一接口。两者合起来，让「新增一类制品或一种能力」变成填配置，而不是改内核代码。 要在插件侧看现在有哪些 Family API 和采用步骤，运行 artifact-chain-help；拿不准入口时走 artifact-chain-quickstart。完整命令表见命令参考。当前默认类型仍由内核提供；不加载领域默认值是长期方向，见路线图。"},{"title":"核心概念","page":"核心概念","href":"03-concepts.html","content":"这一页把散落的名词串起来：制品、关系、上下文包、评审协议、方法注册表。读完应能对着目标仓库说出有哪些制品、它们怎么连、机器怎么验。先取一份上下文，再回头看定义。 现场取上下文 artifact-graph context --target design:DESIGN-xxx artifact-graph query --from feature:FEAT-xxx --format json 返回的是可复现的上下文包雏形。--target 使用 类型:ID。插件侧看能力清单用 artifact-chain-help，体检用 artifact-chain-setup。 制品类型 制品分两套口径，不要混用数字： 基础类型：需求、场景、设计、决策、测试、实现。内核认识这些类型。 扩展类型：按项目配置开启。扩哪一类，由目标项目的 artifact-graph.config.yaml 决定，不写进内核。新增类型是在配置里加 types 条目，而不是改内核。 扩展目录、目录层级与「基线文件数量」是三组不同口径。本站不把其中一组数字套到另一组上。 追溯边与关系锁 制品之间靠边连接（谁实现谁、谁验证谁）。关系锁里有两类边： locks：实现或验证这类已确认关系，是可审计基线。CI 用 version-lock audit 卡住它。 artifactRelations：制品之间的泛化关系；缺该字段时视为空数组，需要 version-lock refresh --all 建立基线。 validate 检查的是这条链有没有接上、有没有断头引用。 评审结果协议 助手做完评审，应交回一份结构化结果，而不是一句「审完了」。要点有三： 失败关闭：校验没过就当失败，不默认放行。 稳定身份：每条结果用执行者与名称定位，重试也能对准同一条。 尝试次数封顶：允许有限重试；禁止把「自己改自己」当成通过。 单独校验一份评审结果： artifact-graph validate-review-result --file review.json 方法注册表 Registry 是方法提供方的接入面，建立在契约内核之上，管身份、清单、绑定、投影与运行期选择。图管制品与关系，注册表管能力提供方，两者正交。细节见方法注册表。 profile、模板与 hook profile：按项目裁剪要加载的技能与模板。 模板：制品起始骨架，写新制品不必从空文件开始。 hook：在 pre-commit / pre-push 自动跑校验。具体步骤在场景剧本。"},{"title":"现场取上下文","page":"核心概念","href":"03-concepts.html#context","content":"artifact-graph context --target design:DESIGN-xxx artifact-graph query --from feature:FEAT-xxx --format json 返回的是可复现的上下文包雏形。--target 使用 类型:ID。插件侧看能力清单用 artifact-chain-help，体检用 artifact-chain-setup。"},{"title":"制品类型","page":"核心概念","href":"03-concepts.html#types","content":"制品分两套口径，不要混用数字： 基础类型：需求、场景、设计、决策、测试、实现。内核认识这些类型。 扩展类型：按项目配置开启。扩哪一类，由目标项目的 artifact-graph.config.yaml 决定，不写进内核。新增类型是在配置里加 types 条目，而不是改内核。 扩展目录、目录层级与「基线文件数量」是三组不同口径。本站不把其中一组数字套到另一组上。"},{"title":"追溯边与关系锁","page":"核心概念","href":"03-concepts.html#edges","content":"制品之间靠边连接（谁实现谁、谁验证谁）。关系锁里有两类边： locks：实现或验证这类已确认关系，是可审计基线。CI 用 version-lock audit 卡住它。 artifactRelations：制品之间的泛化关系；缺该字段时视为空数组，需要 version-lock refresh --all 建立基线。 validate 检查的是这条链有没有接上、有没有断头引用。"},{"title":"评审结果协议","page":"核心概念","href":"03-concepts.html#review-result","content":"助手做完评审，应交回一份结构化结果，而不是一句「审完了」。要点有三： 失败关闭：校验没过就当失败，不默认放行。 稳定身份：每条结果用执行者与名称定位，重试也能对准同一条。 尝试次数封顶：允许有限重试；禁止把「自己改自己」当成通过。 单独校验一份评审结果： artifact-graph validate-review-result --file review.json"},{"title":"方法注册表","page":"核心概念","href":"03-concepts.html#registry","content":"Registry 是方法提供方的接入面，建立在契约内核之上，管身份、清单、绑定、投影与运行期选择。图管制品与关系，注册表管能力提供方，两者正交。细节见方法注册表。"},{"title":"profile、模板与 hook","page":"核心概念","href":"03-concepts.html#daily","content":"profile：按项目裁剪要加载的技能与模板。 模板：制品起始骨架，写新制品不必从空文件开始。 hook：在 pre-commit / pre-push 自动跑校验。具体步骤在场景剧本。"},{"title":"命令参考","page":"命令参考","href":"04-cli.html","content":"下面的清单以 artifact-graph --help 为命令真源。工程改了命令，以当前 CLI 帮助文本为准，不另维护一份会过期的表。拿不准某个命令怎么用，先跑 --help；拿不准该用哪个插件能力，走 artifact-chain-help 或 artifact-chain-quickstart。 先看全貌 artifact-graph --help artifact-graph version-lock --help artifact-graph contract --help 插件侧 artifact-chain-help 列出的是 Family API 与采用步骤，见方法注册表。CLI 命令本身永远以 --help 为准。 命令怎么分两层 artifact-graph 有两层：顶层命令直接跟在 artifact-graph 后面；version-lock、contract、hooks 必须再跟子命令。 顶层命令 命令 作用 典型调用 init 在当前仓库建配置骨架 artifact-graph init --root . scan 扫描制品源、建立或更新索引 artifact-graph scan validate 验制品链完整性 artifact-graph validate --root . --warning-only query 只读查询制品与关系 artifact-graph query --from \u003ccode\u003e --format json context 抽取确定性上下文 artifact-graph context --target design:D-xxx --mode implementation packet 把上下文包写入文件 artifact-graph packet --target design:D-xxx --out packet.json packet-prompt 把上下文包转成给助手的提示词 artifact-graph packet-prompt --target design:D-xxx --out prompt.md packet-audit 批量审计上下文包 artifact-graph packet-audit --discover --out-dir audit/ packet-prompt-audit 批量审计提示词产物 artifact-graph packet-prompt-audit --discover --out-dir audit/ version-index 生成版本索引 artifact-graph version-index --format json --out version-index.json trace-version 追溯某制品的版本链路 artifact-graph trace-version --target design:D-xxx next-id 取下一个制品 id artifact-graph next-id requirement --range main render 渲染派生文档 artifact-graph render --format mermaid doctor 环境体检 artifact-graph doctor --format markdown validate-review-result 校验评审结果协议 artifact-graph validate-review-result --file review.json generate-e2e-registry 生成端到端注册表 artifact-graph generate-e2e-registry --deterministic --check validate --warning-only 退出 0 仍可能带 issues，必须读输出。 带子命令的命令族 version-lock 子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。 contract 子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。 hooks 子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。 restructure 子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。 三个最容易搞混的点 audit 不是顶层命令，它是 version-lock audit 的子命令。 family 不是 CLI 命令。它是 Family API / Registry 的概念，运行在插件侧。 hooks 的真实动作是 install-git。 新接一个项目的建议顺序：init 建配置 → doctor 体检 → validate --warning-only 看链路 → version-lock refresh 建基线。插件里分别由 bootstrap、artifact-chain-setup、artifact-chain-help 带着走，不必硬记全部命令。"},{"title":"先看全貌","page":"命令参考","href":"04-cli.html#help","content":"artifact-graph --help artifact-graph version-lock --help artifact-graph contract --help 插件侧 artifact-chain-help 列出的是 Family API 与采用步骤，见方法注册表。CLI 命令本身永远以 --help 为准。"},{"title":"命令怎么分两层","page":"命令参考","href":"04-cli.html#layers","content":"artifact-graph 有两层：顶层命令直接跟在 artifact-graph 后面；version-lock、contract、hooks 必须再跟子命令。"},{"title":"顶层命令","page":"命令参考","href":"04-cli.html#top","content":"命令 作用 典型调用 init 在当前仓库建配置骨架 artifact-graph init --root . scan 扫描制品源、建立或更新索引 artifact-graph scan validate 验制品链完整性 artifact-graph validate --root . --warning-only query 只读查询制品与关系 artifact-graph query --from \u003ccode\u003e --format json context 抽取确定性上下文 artifact-graph context --target design:D-xxx --mode implementation packet 把上下文包写入文件 artifact-graph packet --target design:D-xxx --out packet.json packet-prompt 把上下文包转成给助手的提示词 artifact-graph packet-prompt --target design:D-xxx --out prompt.md packet-audit 批量审计上下文包 artifact-graph packet-audit --discover --out-dir audit/ packet-prompt-audit 批量审计提示词产物 artifact-graph packet-prompt-audit --discover --out-dir audit/ version-index 生成版本索引 artifact-graph version-index --format json --out version-index.json trace-version 追溯某制品的版本链路 artifact-graph trace-version --target design:D-xxx next-id 取下一个制品 id artifact-graph next-id requirement --range main render 渲染派生文档 artifact-graph render --format mermaid doctor 环境体检 artifact-graph doctor --format markdown validate-review-result 校验评审结果协议 artifact-graph validate-review-result --file review.json generate-e2e-registry 生成端到端注册表 artifact-graph generate-e2e-registry --deterministic --check validate --warning-only 退出 0 仍可能带 issues，必须读输出。"},{"title":"带子命令的命令族","page":"命令参考","href":"04-cli.html#families","content":"version-lock 子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。 contract 子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。 hooks 子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。 restructure 子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。"},{"title":"version-lock","page":"命令参考","href":"04-cli.html#version-lock","content":"子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。"},{"title":"contract","page":"命令参考","href":"04-cli.html#contract","content":"子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。"},{"title":"hooks","page":"命令参考","href":"04-cli.html#hooks","content":"子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。"},{"title":"restructure","page":"命令参考","href":"04-cli.html#restructure","content":"子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。"},{"title":"三个最容易搞混的点","page":"命令参考","href":"04-cli.html#pitfalls","content":"audit 不是顶层命令，它是 version-lock audit 的子命令。 family 不是 CLI 命令。它是 Family API / Registry 的概念，运行在插件侧。 hooks 的真实动作是 install-git。 新接一个项目的建议顺序：init 建配置 → doctor 体检 → validate --warning-only 看链路 → version-lock refresh 建基线。插件里分别由 bootstrap、artifact-chain-setup、artifact-chain-help 带着走，不必硬记全部命令。"},{"title":"场景剧本","page":"场景剧本","href":"05-scenarios.html","content":"这一页不讲概念，直接走最常见的五条任务。每条都给出入口、必要输入和成功信号。遇到分叉再用 artifact-chain-quickstart。CLI 能跑的标了命令，插件侧才有的用提示词。 场景一 · 第一次把项目接进来 新仓库还没有制品链配置。先做只读体检，再经授权走 bootstrap：它会问要哪些制品类型、要不要 hook。完成后得到一份配置骨架和一张空图，等后续填写。 请先使用 artifact-chain-setup 检查环境；若需要初始化，列出将写入的配置与 hook，等待明确授权后再执行 artifact-chain-bootstrap。 也可以先用 CLI 建配置并体检： artifact-graph init --root . artifact-graph doctor --format markdown 向导生成的 artifact-graph.config.yaml 声明本项目有哪些制品类型、各自路径和 id 形态。之后每写一份制品、跑一次 validate，都是在往这张图里填节点和边。doctor 只读检查 CLI、Node 与原生构建，不写文件。 场景二 · 扩展一类制品 要加一类项目自己的制品，例如运维手册。内核不认识新类型。在目标项目配置里补上类型与路径，再刷新关系锁建立新基线： types: runbook: paths: [\"docs/runbooks/**/*.md\"] idPatterns: runbook: \"^RUN-[0-9]{3}$\" artifact-graph version-lock refresh --all --format markdown artifact-graph validate --root . --warning-only 路径用 glob，id 用正则。类型变了，旧基线对不上，所以要刷新锁。validate --warning-only 只报不阻断，方便边改边看。 场景三 · 把校验卡在提交之前 不想靠人记得跑校验时，让 git hook 在提交和推送时自动跑： artifact-graph hooks install-git --hook all --hook all 同时装 pre-commit 与 pre-push。pre-commit 刷新关系锁并检查锁是否随暂存内容漂移；pre-push 跑 validate --warning-only 与 version-lock audit --strict-missing-lock。要卸掉就重跑 install-git --uninstall。hook 只在本机生效，CI 需要独立检查步骤。 场景四 · 接 Codex / Claude / Kimi 按 INSTALL.md 把 artifact-chain-assistant 装进对应宿主。日常先看能力、再体检： 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 装好插件后，不必记全部 CLI 细节。用自然语言描述制品链任务，由 Family API 找到对应能力，由 Registry 负责选择实现。Qoder 复用共享技能，不提供 Claude 那套命令包装与 Stop hook。 场景五 · 带着上下文去改实现 助手改一段代码时，需要知道这次改动满足哪份需求、哪份设计。用 context 取一份上下文包： artifact-graph context --target design:DESIGN-xxx --format markdown artifact-graph packet-prompt --target design:DESIGN-xxx --out prompt.md 上下文包把「这个设计被谁实现、验证过没有」一并抽出。默认开启 context.universal_baseline，缺少约定的基线文件会非零退出。轻量项目可在配置里显式关闭该门槛，或把缺的文件补上。这是基线认知门槛，不是故障。 场景六 · 重组已有制品（拆分 / 改号 / 跨批次移动） 一条记录里塞了两件可独立验收的要求，或者一批用例该换批次和编号时，不要手改：先只读检查， 再把语义决定编译成候选计划，确认后一次性应用。 artifact-graph restructure inspect --root . --input request.json --format json artifact-graph restructure plan --root . --input mapping.json --format json artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers inspect 只读，给出记录跨度、每条关系的出现位置和映射模板。语义作者据此决定功能边界、 共同约束、验收项去向和关系迁移；随后一次独立只读复审，结论只绑定被复审的那份候选。 plan 输出候选、图差异与阻断项；applicable 不为真时不进 apply。 三条限制必须记住： apply 必须由操作者给出 --confirm-cooperative-writers；机制不假设该前提，缺失就拒绝且 不写目标文件。写入能力目前是 candidate 成熟度，资格环境仅为 Darwin / arm64 / APFS。 计划文档要持久化到写集之外的普通目录。进程被中断时只有该文档能用来恢复： restructure recover --plan ... --confirm-all-participants-stopped --confirm-exclusive-maintenance， 两个确认必须同时给出。恢复材料默认保留，只有显式 prune-recovery 才清理。 重组会让旧关系锁变成孤儿。只清理本次改号产生的那条边： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e --remove-orphan-edge 与 --remove-orphans 互斥；被点名的边仍是活边时拒绝删除，同一锁文件 里的既有孤儿也不会被连带清理。只给\"分析并生成迁移计划\"的授权时，不要执行 apply。 出口 接新项目：setup 体检，授权后 bootstrap；或 CLI init + doctor。 加制品类型：改配置 paths / idPatterns，再 refresh + validate。 卡提交：hooks install-git --hook all。 接助手：按 INSTALL.md 安装插件，用 help / setup 起步，用 context 取上下文。 重组制品：restructure inspect → 语义映射 + 独立复审 → plan → 确认后 apply， 再用 --remove-orphan-edge 收尾本次产生的孤儿锁。"},{"title":"场景一 · 第一次把项目接进来","page":"场景剧本","href":"05-scenarios.html#bootstrap","content":"新仓库还没有制品链配置。先做只读体检，再经授权走 bootstrap：它会问要哪些制品类型、要不要 hook。完成后得到一份配置骨架和一张空图，等后续填写。 请先使用 artifact-chain-setup 检查环境；若需要初始化，列出将写入的配置与 hook，等待明确授权后再执行 artifact-chain-bootstrap。 也可以先用 CLI 建配置并体检： artifact-graph init --root . artifact-graph doctor --format markdown 向导生成的 artifact-graph.config.yaml 声明本项目有哪些制品类型、各自路径和 id 形态。之后每写一份制品、跑一次 validate，都是在往这张图里填节点和边。doctor 只读检查 CLI、Node 与原生构建，不写文件。"},{"title":"场景二 · 扩展一类制品","page":"场景剧本","href":"05-scenarios.html#extend-type","content":"要加一类项目自己的制品，例如运维手册。内核不认识新类型。在目标项目配置里补上类型与路径，再刷新关系锁建立新基线： types: runbook: paths: [\"docs/runbooks/**/*.md\"] idPatterns: runbook: \"^RUN-[0-9]{3}$\" artifact-graph version-lock refresh --all --format markdown artifact-graph validate --root . --warning-only 路径用 glob，id 用正则。类型变了，旧基线对不上，所以要刷新锁。validate --warning-only 只报不阻断，方便边改边看。"},{"title":"场景三 · 把校验卡在提交之前","page":"场景剧本","href":"05-scenarios.html#hooks","content":"不想靠人记得跑校验时，让 git hook 在提交和推送时自动跑： artifact-graph hooks install-git --hook all --hook all 同时装 pre-commit 与 pre-push。pre-commit 刷新关系锁并检查锁是否随暂存内容漂移；pre-push 跑 validate --warning-only 与 version-lock audit --strict-missing-lock。要卸掉就重跑 install-git --uninstall。hook 只在本机生效，CI 需要独立检查步骤。"},{"title":"场景四 · 接 Codex / Claude / Kimi","page":"场景剧本","href":"05-scenarios.html#hosts","content":"按 INSTALL.md 把 artifact-chain-assistant 装进对应宿主。日常先看能力、再体检： 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 装好插件后，不必记全部 CLI 细节。用自然语言描述制品链任务，由 Family API 找到对应能力，由 Registry 负责选择实现。Qoder 复用共享技能，不提供 Claude 那套命令包装与 Stop hook。"},{"title":"场景五 · 带着上下文去改实现","page":"场景剧本","href":"05-scenarios.html#context","content":"助手改一段代码时，需要知道这次改动满足哪份需求、哪份设计。用 context 取一份上下文包： artifact-graph context --target design:DESIGN-xxx --format markdown artifact-graph packet-prompt --target design:DESIGN-xxx --out prompt.md 上下文包把「这个设计被谁实现、验证过没有」一并抽出。默认开启 context.universal_baseline，缺少约定的基线文件会非零退出。轻量项目可在配置里显式关闭该门槛，或把缺的文件补上。这是基线认知门槛，不是故障。"},{"title":"场景六 · 重组已有制品（拆分 / 改号 / 跨批次移动）","page":"场景剧本","href":"05-scenarios.html#restructure","content":"一条记录里塞了两件可独立验收的要求，或者一批用例该换批次和编号时，不要手改：先只读检查， 再把语义决定编译成候选计划，确认后一次性应用。 artifact-graph restructure inspect --root . --input request.json --format json artifact-graph restructure plan --root . --input mapping.json --format json artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers inspect 只读，给出记录跨度、每条关系的出现位置和映射模板。语义作者据此决定功能边界、 共同约束、验收项去向和关系迁移；随后一次独立只读复审，结论只绑定被复审的那份候选。 plan 输出候选、图差异与阻断项；applicable 不为真时不进 apply。 三条限制必须记住： apply 必须由操作者给出 --confirm-cooperative-writers；机制不假设该前提，缺失就拒绝且 不写目标文件。写入能力目前是 candidate 成熟度，资格环境仅为 Darwin / arm64 / APFS。 计划文档要持久化到写集之外的普通目录。进程被中断时只有该文档能用来恢复： restructure recover --plan ... --confirm-all-participants-stopped --confirm-exclusive-maintenance， 两个确认必须同时给出。恢复材料默认保留，只有显式 prune-recovery 才清理。 重组会让旧关系锁变成孤儿。只清理本次改号产生的那条边： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e --remove-orphan-edge 与 --remove-orphans 互斥；被点名的边仍是活边时拒绝删除，同一锁文件 里的既有孤儿也不会被连带清理。只给\"分析并生成迁移计划\"的授权时，不要执行 apply。"},{"title":"出口","page":"场景剧本","href":"05-scenarios.html#takeaway","content":"接新项目：setup 体检，授权后 bootstrap；或 CLI init + doctor。 加制品类型：改配置 paths / idPatterns，再 refresh + validate。 卡提交：hooks install-git --hook all。 接助手：按 INSTALL.md 安装插件，用 help / setup 起步，用 context 取上下文。 重组制品：restructure inspect → 语义映射 + 独立复审 → plan → 确认后 apply， 再用 --remove-orphan-edge 收尾本次产生的孤儿锁。"},{"title":"方法注册表","page":"方法注册表","href":"06-method-registry.html","content":"助手要调用一种能力时，不直接硬编码实现，而是走标准 Family API，由 Registry 找到真正的提供方。换实现、加能力时，调用方不必改路由逻辑。本仓助手按已锁定的 Registry 公共接口接线，不复制实现身份，也不把 worker.skill 当成绑定。 先看当前可见能力 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 Family API Catalog 来自插件自带文件，Registry 缺失时静态能力仍可展示。动态安装状态在 Registry v2 verifier 未接入时显示为不可用，不得把候选清单写成已验证提供方。 配置是否合法，仍用图入口核对： artifact-graph validate --root . --warning-only artifact-graph contract list --format json family / registry 是 SPI 概念，运行在插件与助手侧。CLI 不直接暴露这两个子命令。 Registry 管五件事 身份：每个方法提供方有稳定标识，重试和审计都能对准同一个提供方。 清单：登记有哪些方法、各自提供什么能力。宿主发现的插件只能形成候选，不能直接当成可信提供方。 绑定：把能力名映射到具体实现。默认整族原子绑定，避免 author 来自实现 A、review 来自不兼容实现 B。 投影：按调用方视角裁剪暴露的方法；从 API、实现与可信清单确定性生成。 运行期选择：一次运行内，同名方法不许中途替换。安装插件不得自动改写已有项目的有效绑定。 本仓 where-am-i 生成 Method Query candidate，把已解析的绑定对象交给 Registry 的 buildEffectiveIndex 与 queryEffectiveIndex。下游消费返回的 serviceId、apiId、apiMajor 及原生选择状态。 为什么需要它 同一项目可能同时看到开源实现与内部实现，两者都提供同名能力。没有注册表时，今天走到开源、明天走到内部，结果不可复现。有了 Registry：身份区分两个提供方；绑定按项目配置锁定整族实现；运行期选择保证这次运行始终路由到同一实现；投影避免规划器调到未验证的候选。 和图内核的关系 Registry 与 artifact-graph 的图结构正交：图管制品与关系，注册表管能力提供方。两者不互相导入内部实现。缺绑定时保留 Registry 原始不可执行状态；help 与单纯图检查不受影响。"},{"title":"先看当前可见能力","page":"方法注册表","href":"06-method-registry.html#help","content":"请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 Family API Catalog 来自插件自带文件，Registry 缺失时静态能力仍可展示。动态安装状态在 Registry v2 verifier 未接入时显示为不可用，不得把候选清单写成已验证提供方。 配置是否合法，仍用图入口核对： artifact-graph validate --root . --warning-only artifact-graph contract list --format json family / registry 是 SPI 概念，运行在插件与助手侧。CLI 不直接暴露这两个子命令。"},{"title":"Registry 管五件事","page":"方法注册表","href":"06-method-registry.html#spi","content":"身份：每个方法提供方有稳定标识，重试和审计都能对准同一个提供方。 清单：登记有哪些方法、各自提供什么能力。宿主发现的插件只能形成候选，不能直接当成可信提供方。 绑定：把能力名映射到具体实现。默认整族原子绑定，避免 author 来自实现 A、review 来自不兼容实现 B。 投影：按调用方视角裁剪暴露的方法；从 API、实现与可信清单确定性生成。 运行期选择：一次运行内，同名方法不许中途替换。安装插件不得自动改写已有项目的有效绑定。 本仓 where-am-i 生成 Method Query candidate，把已解析的绑定对象交给 Registry 的 buildEffectiveIndex 与 queryEffectiveIndex。下游消费返回的 serviceId、apiId、apiMajor 及原生选择状态。"},{"title":"为什么需要它","page":"方法注册表","href":"06-method-registry.html#why","content":"同一项目可能同时看到开源实现与内部实现，两者都提供同名能力。没有注册表时，今天走到开源、明天走到内部，结果不可复现。有了 Registry：身份区分两个提供方；绑定按项目配置锁定整族实现；运行期选择保证这次运行始终路由到同一实现；投影避免规划器调到未验证的候选。"},{"title":"和图内核的关系","page":"方法注册表","href":"06-method-registry.html#orthogonal","content":"Registry 与 artifact-graph 的图结构正交：图管制品与关系，注册表管能力提供方。两者不互相导入内部实现。缺绑定时保留 Registry 原始不可执行状态；help 与单纯图检查不受影响。"},{"title":"术语库","page":"术语库","href":"07-glossary.html","content":"本页汇总站点反复使用的术语。旧版用页面脚本做悬停气泡；本版把定义写在这里，并可用站点搜索定位。正文里第一次依赖某个词时，也会就近解释。 工程与入口 术语 含义 artifact-graph 底层运行时、CLI 与 Node 库。扫描 Markdown 制品、建图、校验、维护关系锁。 artifact-chain-assistant 上层插件。把图能力接到 Codex、Claude Code、Kimi Code；Qoder 复用共享技能。 Family API 一类制品的标准操作接口，例如 help、author、review、repair。 artifact-chain-help 只读能力说明入口，展示 Family API 与采用步骤。 artifact-chain-setup 默认只读的环境诊断；机械安装步骤须经明确确认。 artifact-chain-quickstart 按自然语言意图路由到正确入口，不执行被路由技能的业务逻辑。 artifact-chain-bootstrap 经授权后做项目级配置决策：类型裁剪、配置合同、版本锁与工作法章节。 artifact-audit 只读健康与能力检查，消费图校验和关系锁结果，不运行目标测试或构建。 图与锁 术语 含义 Git 原生 制品是仓库文件，关系留在 Git 历史；克隆即可跑，不另起数据库。 确定性 同样输入得到同样输出，校验结果可复现、可机器判定。 version-lock 追溯关系的版本化基线，也是一次提交的事务边界。不是依赖 lockfile。 locks 已确认的实现或验证关系。 artifactRelations 制品之间的泛化关系；缺字段时视为空。 失败关闭 校验没过就当失败，不默认放行。 上下文包 按目标制品抽出的上下游材料，供助手消费。 universal_baseline 取上下文前要求一组基线文件存在；缺文件则非零退出。 评审与注册表 术语 含义 评审结果协议 结构化评审输出：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 Contract Kernel 内核对外能力的稳定契约边界。 Registry 方法提供方的身份、清单、绑定、投影与运行期选择。与图结构正交。 整族原子绑定 同一族服务默认来自同一实现，避免混绑不兼容实现。 compatibility.json 插件与已验证 artifact-graph 版本的配对记录。 需要命令细节时回到命令参考；需要排错步骤时到排错与兼容。"},{"title":"工程与入口","page":"术语库","href":"07-glossary.html#projects","content":"术语 含义 artifact-graph 底层运行时、CLI 与 Node 库。扫描 Markdown 制品、建图、校验、维护关系锁。 artifact-chain-assistant 上层插件。把图能力接到 Codex、Claude Code、Kimi Code；Qoder 复用共享技能。 Family API 一类制品的标准操作接口，例如 help、author、review、repair。 artifact-chain-help 只读能力说明入口，展示 Family API 与采用步骤。 artifact-chain-setup 默认只读的环境诊断；机械安装步骤须经明确确认。 artifact-chain-quickstart 按自然语言意图路由到正确入口，不执行被路由技能的业务逻辑。 artifact-chain-bootstrap 经授权后做项目级配置决策：类型裁剪、配置合同、版本锁与工作法章节。 artifact-audit 只读健康与能力检查，消费图校验和关系锁结果，不运行目标测试或构建。"},{"title":"图与锁","page":"术语库","href":"07-glossary.html#graph","content":"术语 含义 Git 原生 制品是仓库文件，关系留在 Git 历史；克隆即可跑，不另起数据库。 确定性 同样输入得到同样输出，校验结果可复现、可机器判定。 version-lock 追溯关系的版本化基线，也是一次提交的事务边界。不是依赖 lockfile。 locks 已确认的实现或验证关系。 artifactRelations 制品之间的泛化关系；缺字段时视为空。 失败关闭 校验没过就当失败，不默认放行。 上下文包 按目标制品抽出的上下游材料，供助手消费。 universal_baseline 取上下文前要求一组基线文件存在；缺文件则非零退出。"},{"title":"评审与注册表","page":"术语库","href":"07-glossary.html#review-registry","content":"术语 含义 评审结果协议 结构化评审输出：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 Contract Kernel 内核对外能力的稳定契约边界。 Registry 方法提供方的身份、清单、绑定、投影与运行期选择。与图结构正交。 整族原子绑定 同一族服务默认来自同一实现，避免混绑不兼容实现。 compatibility.json 插件与已验证 artifact-graph 版本的配对记录。 需要命令细节时回到命令参考；需要排错步骤时到排错与兼容。"},{"title":"维护者视角","page":"维护者视角","href":"08-maintainer.html","content":"发版维护者要同时对外公开与守住私有边界。这一页讲发布治理的通用原则，不点名内部脚本。落到目标仓库时，把下面三件事接进自己的发布流水线即可。铁律是：宁可发布失败，也不漏私有内容。 发布前自检三件事 内容级泄漏扫描：发布产物里不能出现本机用户目录、私有仓名、密钥或令牌。扫描必须先解码 HTML 实体和 JS 转义再匹配，否则编码拼接能绕过字面检查。 文档树摘要锁：给每个文档的标题与章节结构算摘要，和上次比对。结构被误删或章节被改动时立刻发现。 链接越界断言：站内链接不能跳出本站范围；外链只允许指向已发布仓库的固定版本地址，禁用外部 CDN、webfont 或统计脚本。 本站的渲染器会在写入目标前做泄漏扫描，并生成 site-baseline.json 作为产物树摘要。--check 把内存渲染与磁盘基线比对；不一致即漂移。 两条铁律 声明式配置单一来源：发布什么、拷到哪、哪些路径禁止外泄，都写在一份配置里，脚本照着跑。Review 一份配置就能知道这次发版会带出什么。 物理公私隔离：私有内容与公开内容走不同目录，发布前做隔离校验。内容级正则、机器可读边界配置、路径禁止清单三层里任意一层拦到，发布就停。 把自检接进流水线 预提交：本地改了文档或站点，锁或基线变了就拦下，要求回到权威源并重新渲染。这防止只改渲染产物。 推送前：再跑完整性与锁审计，确保进共享仓库的内容干净。 CI / 公开发布前：完整性校验、锁审计、测试与发布就绪性验证。任何一项失败都不进发布。 具体命令以目标仓库自己的发布配置为准。本页不列父工程私有脚本名。 OSS 合规与双语 对外发布的文档遵循 Apache-2.0 与 NOTICE。README、CHANGELOG、INSTALL 维持中英双语；本知识站正文以中文优先。克隆到新仓库时，onboarding 应能照着做就跑起来，这正是 bootstrap 向导存在的原因。许可证头、NOTICE、第三方归属要随每次发版复核。 重组与锁收尾 制品拆分、改号或跨批次移动之后，旧关系锁会变成孤儿。锁清理是发布前的显式维护动作，不是 自动收尾： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e 只点名本次重组产生的那条边。--remove-orphans 是整体清理，与 --remove-orphan-edge 互斥； 同一锁文件里的既有孤儿不因本次重组被连带删除，清理前后的条目都能在锁文件 diff 里回看。 恢复材料默认保留，只有显式 restructure prune-recovery 才清理。 重组写入能力的成熟度是 candidate，资格环境仅为 Darwin / arm64 / APFS，前提是合作式写者， 恢复需要显式的双维护确认。维护者不得把它写成已发布的全平台事务保证，也不得因为 apply 能跑通就省略操作者确认。 派生文档防漂移 很多文档是渲染出来的副本，不是手写权威源。这类文档必须带生成横幅，并能重新渲染后与已提交基线比对；不一致即漂移。只在产物上改、不回改权威源，下次渲染会覆盖改动。外链必须钉到具体版本标签，不能指向会漂移的默认分支。 请使用 artifact-chain-maintainer 说明当前关系锁与文档派生检查该如何刷新；列出将写入的路径，等待授权后再执行。 未授权方向不得写成已实现能力。状态口径见路线图。"},{"title":"发布前自检三件事","page":"维护者视角","href":"08-maintainer.html#preflight","content":"内容级泄漏扫描：发布产物里不能出现本机用户目录、私有仓名、密钥或令牌。扫描必须先解码 HTML 实体和 JS 转义再匹配，否则编码拼接能绕过字面检查。 文档树摘要锁：给每个文档的标题与章节结构算摘要，和上次比对。结构被误删或章节被改动时立刻发现。 链接越界断言：站内链接不能跳出本站范围；外链只允许指向已发布仓库的固定版本地址，禁用外部 CDN、webfont 或统计脚本。 本站的渲染器会在写入目标前做泄漏扫描，并生成 site-baseline.json 作为产物树摘要。--check 把内存渲染与磁盘基线比对；不一致即漂移。"},{"title":"两条铁律","page":"维护者视角","href":"08-maintainer.html#rules","content":"声明式配置单一来源：发布什么、拷到哪、哪些路径禁止外泄，都写在一份配置里，脚本照着跑。Review 一份配置就能知道这次发版会带出什么。 物理公私隔离：私有内容与公开内容走不同目录，发布前做隔离校验。内容级正则、机器可读边界配置、路径禁止清单三层里任意一层拦到，发布就停。"},{"title":"把自检接进流水线","page":"维护者视角","href":"08-maintainer.html#gates","content":"预提交：本地改了文档或站点，锁或基线变了就拦下，要求回到权威源并重新渲染。这防止只改渲染产物。 推送前：再跑完整性与锁审计，确保进共享仓库的内容干净。 CI / 公开发布前：完整性校验、锁审计、测试与发布就绪性验证。任何一项失败都不进发布。 具体命令以目标仓库自己的发布配置为准。本页不列父工程私有脚本名。"},{"title":"OSS 合规与双语","page":"维护者视角","href":"08-maintainer.html#oss","content":"对外发布的文档遵循 Apache-2.0 与 NOTICE。README、CHANGELOG、INSTALL 维持中英双语；本知识站正文以中文优先。克隆到新仓库时，onboarding 应能照着做就跑起来，这正是 bootstrap 向导存在的原因。许可证头、NOTICE、第三方归属要随每次发版复核。"},{"title":"重组与锁收尾","page":"维护者视角","href":"08-maintainer.html#restructure-locks","content":"制品拆分、改号或跨批次移动之后，旧关系锁会变成孤儿。锁清理是发布前的显式维护动作，不是 自动收尾： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e 只点名本次重组产生的那条边。--remove-orphans 是整体清理，与 --remove-orphan-edge 互斥； 同一锁文件里的既有孤儿不因本次重组被连带删除，清理前后的条目都能在锁文件 diff 里回看。 恢复材料默认保留，只有显式 restructure prune-recovery 才清理。 重组写入能力的成熟度是 candidate，资格环境仅为 Darwin / arm64 / APFS，前提是合作式写者， 恢复需要显式的双维护确认。维护者不得把它写成已发布的全平台事务保证，也不得因为 apply 能跑通就省略操作者确认。"},{"title":"派生文档防漂移","page":"维护者视角","href":"08-maintainer.html#derived","content":"很多文档是渲染出来的副本，不是手写权威源。这类文档必须带生成横幅，并能重新渲染后与已提交基线比对；不一致即漂移。只在产物上改、不回改权威源，下次渲染会覆盖改动。外链必须钉到具体版本标签，不能指向会漂移的默认分支。 请使用 artifact-chain-maintainer 说明当前关系锁与文档派生检查该如何刷新；列出将写入的路径，等待授权后再执行。 未授权方向不得写成已实现能力。状态口径见路线图。"},{"title":"排错与兼容","page":"排错与兼容","href":"09-troubleshoot.html","content":"跑不起来或结果不对时，先体检再猜。这一页是 artifact-chain-setup 与 artifact-graph doctor 的主场。两者都只读，可以反复跑。 先体检 artifact-graph doctor --format markdown 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 多数问题会直接报出来：CLI 找不到、配置缺字段、Node 版本不够、原生构建 better-sqlite3 被 pnpm 跳过。把体检输出对照下面的症状。 常见症状 第一次跑 context / packet 就非零退出：多半是 context.universal_baseline 默认开启，而项目缺少约定的基线文件。轻量项目在配置里显式关闭该门槛，或把缺的文件补上。 安装后报 missing binding 或原生模块缺失：原生构建被拦了。在 pnpm 10.26+ 用 allowBuilds，更早的 10.x 用 onlyBuiltDependencies，允许 better-sqlite3。装完用 doctor 复核。 关系锁漂移：源文件或关系变了但锁没刷。先验收受影响的内容，确认关系仍成立，再更新锁。日常工作树用 artifact-graph version-lock refresh --changed-only --worktree 只刷已确认的受影响锁；提交前改用 --staged。--all 重建全量基线。锁和源一起提交。禁止在 hook 里跑 version-lock bootstrap --force。 validate 报断头边：某制品声称被一份设计实现，但那份设计不存在或 id 写错。补上缺失制品，或修正标记里的 id。 CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。 CI 红、本地绿 常见只有两类原因： 原生构建差异：CI 的 pnpm 版本或缓存策略跳过了 better-sqlite3。对照本地 doctor 输出，确认 CI 镜像也带白名单。 基线门槛差异：CI 是干净 checkout，universal_baseline 发现缺文件直接非零退出，本地恰好有这些文件所以没报。在项目配置里显式声明：要么补齐文件，要么关掉该门槛。 排查时把 CI 的命令复制到本地，加 --warning-only 再跑一遍，通常能立刻复现。validate --warning-only 退出 0 仍要读 issues。 把问题缩到最小 症状不直观时，先做最小复现：新建一个只含一份需求与一份设计的仓库，跑 init → validate。能复现，说明是配置或能力本身的问题；不能复现，说明是当前项目某份制品把图带歪了。这时用 query 把关系拉出来看，比猜测快。 兼容 版本配对写在插件的 compatibility.json：Node、CLI 与插件版本。升级前先看该文件，避免本地能跑、CI 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 0.14.1。"},{"title":"先体检","page":"排错与兼容","href":"09-troubleshoot.html#doctor","content":"artifact-graph doctor --format markdown 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 多数问题会直接报出来：CLI 找不到、配置缺字段、Node 版本不够、原生构建 better-sqlite3 被 pnpm 跳过。把体检输出对照下面的症状。"},{"title":"常见症状","page":"排错与兼容","href":"09-troubleshoot.html#symptoms","content":"第一次跑 context / packet 就非零退出：多半是 context.universal_baseline 默认开启，而项目缺少约定的基线文件。轻量项目在配置里显式关闭该门槛，或把缺的文件补上。 安装后报 missing binding 或原生模块缺失：原生构建被拦了。在 pnpm 10.26+ 用 allowBuilds，更早的 10.x 用 onlyBuiltDependencies，允许 better-sqlite3。装完用 doctor 复核。 关系锁漂移：源文件或关系变了但锁没刷。先验收受影响的内容，确认关系仍成立，再更新锁。日常工作树用 artifact-graph version-lock refresh --changed-only --worktree 只刷已确认的受影响锁；提交前改用 --staged。--all 重建全量基线。锁和源一起提交。禁止在 hook 里跑 version-lock bootstrap --force。 validate 报断头边：某制品声称被一份设计实现，但那份设计不存在或 id 写错。补上缺失制品，或修正标记里的 id。 CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。"},{"title":"CI 红、本地绿","page":"排错与兼容","href":"09-troubleshoot.html#ci","content":"常见只有两类原因： 原生构建差异：CI 的 pnpm 版本或缓存策略跳过了 better-sqlite3。对照本地 doctor 输出，确认 CI 镜像也带白名单。 基线门槛差异：CI 是干净 checkout，universal_baseline 发现缺文件直接非零退出，本地恰好有这些文件所以没报。在项目配置里显式声明：要么补齐文件，要么关掉该门槛。 排查时把 CI 的命令复制到本地，加 --warning-only 再跑一遍，通常能立刻复现。validate --warning-only 退出 0 仍要读 issues。"},{"title":"把问题缩到最小","page":"排错与兼容","href":"09-troubleshoot.html#minimize","content":"症状不直观时，先做最小复现：新建一个只含一份需求与一份设计的仓库，跑 init → validate。能复现，说明是配置或能力本身的问题；不能复现，说明是当前项目某份制品把图带歪了。这时用 query 把关系拉出来看，比猜测快。"},{"title":"兼容","page":"排错与兼容","href":"09-troubleshoot.html#compat","content":"版本配对写在插件的 compatibility.json：Node、CLI 与插件版本。升级前先看该文件，避免本地能跑、CI 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 0.14.1。"},{"title":"路线图","page":"路线图","href":"10-roadmap.html","content":"这一页用状态区分：哪些是已经落地的能力，哪些还在方向阶段、没有实施授权，哪些是已有计划、方案仍待决策。读的时候不要把方向当成现状。标成已实现的能力，背后应有对应决策文件。 已实现 业务三层边界：图内核、通用助手、目标项目各管一摊，上层调下层、下层不反向依赖。见架构原理。 契约内核与标准 Family API：内核稳定边界加上业务族统一接入，新类型靠配置接入。见方法注册表。 Registry 公共接口：身份、清单、绑定、投影与查询；助手按已锁定版本接线。 CLI 命令族：init / scan / validate / query / context / packet（含 prompt 与 audit）/ version-lock / trace-version / version-index / hooks / next-id / render / doctor / validate-review-result / generate-e2e-registry / contract / restructure。以 --help 为准。 评审结果协议：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 关系锁两类边：locks 与 artifactRelations。 方向，未授权 通用图内核与多领域规范分层：把混合的软件开发语义拆成「不加载领域默认值的通用内核 + 可独立发布的领域图规范 + 多领域通过规范组合共存」。这是长期架构待办，目前未授权实施。迁移前需要补齐正式需求、场景、设计、决策与验收；物理拆仓必须晚于兼容验证。在那之前，新增设计不得把领域类型继续写进通用内核。 这条方向如果落地，会变成一套不加载领域默认值的通用图内核、多份可独立发布的领域规范，以及一个只做初始化、诊断、规范发现与分诊的通用助手。现在它只是方向记录，不是能力。 规划中 泄漏扫描集随新的密钥前缀和内部路径形态做增量扩充。机制已落地，扩充是维护。 文档树摘要锁接到更多发布环节，让误删章节更早被发现。 快照断言覆盖更多导出形态。当前已覆盖站点 HTML、资源与 .nojekyll。 这三项是增强已落地能力，不引入新范式，也不与上面的架构方向混为一谈。 怎么读成熟度 判定口径只有一条：有没有对应决策文件背书。 已实现：决策已通过、代码已落地、本站有对应页可核对。 规划中：增强路径已写入治理计划，具体方案待决策落定。 方向，未授权：只是方向记录。迁移前必须先补齐正式需求、场景、设计、决策与验收，且不得据此大规模移动目录、改包名或拆仓。 能力是否落地，以决策文件为准，不凭本页注释判断。新能力从方向走到已实现，都会先有决策、再有代码、最后进本站。"},{"title":"已实现","page":"路线图","href":"10-roadmap.html#done","content":"业务三层边界：图内核、通用助手、目标项目各管一摊，上层调下层、下层不反向依赖。见架构原理。 契约内核与标准 Family API：内核稳定边界加上业务族统一接入，新类型靠配置接入。见方法注册表。 Registry 公共接口：身份、清单、绑定、投影与查询；助手按已锁定版本接线。 CLI 命令族：init / scan / validate / query / context / packet（含 prompt 与 audit）/ version-lock / trace-version / version-index / hooks / next-id / render / doctor / validate-review-result / generate-e2e-registry / contract / restructure。以 --help 为准。 评审结果协议：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 关系锁两类边：locks 与 artifactRelations。"},{"title":"方向，未授权","page":"路线图","href":"10-roadmap.html#direction","content":"通用图内核与多领域规范分层：把混合的软件开发语义拆成「不加载领域默认值的通用内核 + 可独立发布的领域图规范 + 多领域通过规范组合共存」。这是长期架构待办，目前未授权实施。迁移前需要补齐正式需求、场景、设计、决策与验收；物理拆仓必须晚于兼容验证。在那之前，新增设计不得把领域类型继续写进通用内核。 这条方向如果落地，会变成一套不加载领域默认值的通用图内核、多份可独立发布的领域规范，以及一个只做初始化、诊断、规范发现与分诊的通用助手。现在它只是方向记录，不是能力。"},{"title":"规划中","page":"路线图","href":"10-roadmap.html#planned","content":"泄漏扫描集随新的密钥前缀和内部路径形态做增量扩充。机制已落地，扩充是维护。 文档树摘要锁接到更多发布环节，让误删章节更早被发现。 快照断言覆盖更多导出形态。当前已覆盖站点 HTML、资源与 .nojekyll。 这三项是增强已落地能力，不引入新范式，也不与上面的架构方向混为一谈。"},{"title":"怎么读成熟度","page":"路线图","href":"10-roadmap.html#how","content":"判定口径只有一条：有没有对应决策文件背书。 已实现：决策已通过、代码已落地、本站有对应页可核对。 规划中：增强路径已写入治理计划，具体方案待决策落定。 方向，未授权：只是方向记录。迁移前必须先补齐正式需求、场景、设计、决策与验收，且不得据此大规模移动目录、改包名或拆仓。 能力是否落地，以决策文件为准，不凭本页注释判断。新能力从方向走到已实现，都会先有决策、再有代码、最后进本站。"}]</script>
+  <script id="editorial-search-data" type="application/json">[{"title":"枢纽 · 学习地图","page":"枢纽 · 学习地图","href":"index.html","content":"本站把 artifact-graph 与 artifact-chain-assistant 当成一件事来讲：用一套可复现、Git 原生的方法，把「为什么做、做了什么、怎么验证」连成机器能验的链路。 artifact-graph 是底层运行时、CLI 与 Node 库，负责扫描制品、建图与校验。artifact-chain-assistant 是上层插件，把这套工作法接到 Codex、Claude Code 与 Kimi Code 的日常会话；Qoder 以技能兼容宿主复用同一套共享技能。第一次接触时，先完成下面的只读入口，再按角色选页。 当前插件源版本是 0.14.2。本地源版本不等于已发布或已安装版本；安装与配对以 INSTALL.md 和 compatibility.json 为准。 先跑起来 装好插件后，第一件事是只读查看 Family API（标准族接口）和采用步骤；拿不准该用哪个技能时，交给 artifact-chain-quickstart 分流。这两条都不会改项目文件。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-quickstart，根据当前问题推荐正确入口，不要修改项目。 环境不明时用 artifact-chain-setup 做只读体检。要把一个目标项目接进制品链，再经明确授权走 artifact-chain-bootstrap。 按角色选路径 新使用者：先读它是什么，再按场景剧本抄一条能完成的路径；卡住时查排错与兼容。 已在使用、要看原理：读架构原理、核心概念和方法注册表。 发版维护者：重点看维护者视角与路线图。路线图用状态区分已落地能力与未授权方向。 能力一览 页面 读完能做什么 双工程能力矩阵 对照常规研发做法与制品链做法 它是什么 判断这套工具解决谁的问题、两工程如何配合 架构原理 核对三层边界、Git 原生、关系锁与契约内核 核心概念 辨认制品类型、追溯边、上下文包与评审协议 命令参考 按 artifact-graph --help 查命令，不另造一份会过期的表 场景剧本 按六条常见任务完成第一次接入 方法注册表 理解 Family API 与 Registry 如何把能力落到实现 术语库 查阅本站反复使用的术语 维护者视角 把泄漏扫描、摘要锁和链接边界接进发布门禁 排错与兼容 先体检再按症状恢复 路线图 区分已实现、规划中与未授权方向 怎么读 不必按目录从头读到尾。先完成「先跑起来」，再从当前最痛的场景翻对应页：接项目看场景页，排错看排错页，原理看架构与概念页。各页自包含，跳读不会丢掉入口。 能力第一次出现会标明状态。已实现表示已有决策与代码；方向、未授权表示长期记录，不能当成现状；规划中表示增强路径已写下、方案仍待决策。 旧站的术语气泡依赖自有脚本。本版由 editorial 模板提供导航、搜索与提示词复制；术语定义集中在术语库。"},{"title":"先跑起来","page":"枢纽 · 学习地图","href":"index.html#start","content":"装好插件后，第一件事是只读查看 Family API（标准族接口）和采用步骤；拿不准该用哪个技能时，交给 artifact-chain-quickstart 分流。这两条都不会改项目文件。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-quickstart，根据当前问题推荐正确入口，不要修改项目。 环境不明时用 artifact-chain-setup 做只读体检。要把一个目标项目接进制品链，再经明确授权走 artifact-chain-bootstrap。"},{"title":"按角色选路径","page":"枢纽 · 学习地图","href":"index.html#paths","content":"新使用者：先读它是什么，再按场景剧本抄一条能完成的路径；卡住时查排错与兼容。 已在使用、要看原理：读架构原理、核心概念和方法注册表。 发版维护者：重点看维护者视角与路线图。路线图用状态区分已落地能力与未授权方向。"},{"title":"能力一览","page":"枢纽 · 学习地图","href":"index.html#pages","content":"页面 读完能做什么 双工程能力矩阵 对照常规研发做法与制品链做法 它是什么 判断这套工具解决谁的问题、两工程如何配合 架构原理 核对三层边界、Git 原生、关系锁与契约内核 核心概念 辨认制品类型、追溯边、上下文包与评审协议 命令参考 按 artifact-graph --help 查命令，不另造一份会过期的表 场景剧本 按六条常见任务完成第一次接入 方法注册表 理解 Family API 与 Registry 如何把能力落到实现 术语库 查阅本站反复使用的术语 维护者视角 把泄漏扫描、摘要锁和链接边界接进发布门禁 排错与兼容 先体检再按症状恢复 路线图 区分已实现、规划中与未授权方向"},{"title":"怎么读","page":"枢纽 · 学习地图","href":"index.html#how-to-read","content":"不必按目录从头读到尾。先完成「先跑起来」，再从当前最痛的场景翻对应页：接项目看场景页，排错看排错页，原理看架构与概念页。各页自包含，跳读不会丢掉入口。 能力第一次出现会标明状态。已实现表示已有决策与代码；方向、未授权表示长期记录，不能当成现状；规划中表示增强路径已写下、方案仍待决策。 旧站的术语气泡依赖自有脚本。本版由 editorial 模板提供导航、搜索与提示词复制；术语定义集中在术语库。"},{"title":"双工程能力矩阵","page":"双工程能力矩阵","href":"00-matrix.html","content":"这一页是理解支点。左侧是常规研发已经在做的事，右侧是同一件事在制品链范式下的做法。学习重点落在差异：右侧多出来的约束，用来处理「助手宣称完成、链路其实断着」的问题。 两个工程分别管什么 维度 常规做法 制品链做法 归属 图能力 文档之间靠人记关系，没有工具校验 配置读取、制品扫描、索引、边关系、查询、校验、版本锁 artifact-graph（底层运行时 / CLI） 助手能力 编辑器补全、零散脚本 profile、模板、bootstrap、maintainer、where-am-i、宿主适配器、hook 指导 artifact-chain-assistant（上层插件） 事实来源 散在 wiki、脑图或口头约定 单一 Git 仓库，Git 原生即事实来源 两者共用 结果可信度 「改完了」靠人判断 评审结果协议：默认失败关闭、身份稳定、禁止自我接受 两者共用 安装与运行对照 环节 常规 制品链 安装 未锁定范围的工具依赖 按 INSTALL.md 与 compatibility.json 安装已验证的精确 artifact-graph，禁止未锁定范围 构建 各自 CI 脚本 pnpm 10 会拦下原生构建，必须显式允许 better-sqlite3 校验 单测 / lint artifact-graph validate 与 version-lock audit 初始化 手写配置 artifact-chain-bootstrap 引导；context.universal_baseline 默认开启，未设好时第一次取上下文会非零退出 安全第一步 常被跳过 artifact-chain-setup 与 artifact-graph doctor 只读体检 先看清当前项目位置 不必读完整站。下面两条只读请求用于查看 Family API 与环境位置。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 拿不准下一步时走 artifact-chain-quickstart。正式把目标项目接进来，再授权 artifact-chain-bootstrap。 边界对照 常见误解 实际边界 替业务写实现代码 不管。它管产出是否可追溯、可验证 当成普通依赖 lockfile 不是。version-lock 锁的是追溯关系，同时也是一次提交的事务边界 当成又一个文档站生成器 不是。知识站只是发布阅读面；工具本身产出图与锁 重组制品靠助手直接改文件 不是。语义决定留在技能层，文件集合写入由 restructure 确定性执行，且需操作者确认 重组能力写在哪一层 维度 制品链做法 归属 语义决定 功能边界、共同约束、验收项去向、关系迁移 技能层（artifact-chain-restructure） 确定性执行 检查、候选计划编译、文件集合应用与恢复 artifact-graph restructure 独立复审 只读核对候选与映射，结论绑定被复审的候选 技能层 写入前提 操作者显式确认合作式写者；恢复需显式双维护确认 操作者，机制不自证 采用边界要一并说清，否则容易把候选能力当成已发布保证： 写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS；其他平台返回不可用， 不降级到无事务写入，也不承诺全平台事务保证。 前提是合作式写者。apply 与 prune-recovery 缺少 --confirm-cooperative-writers 即拒绝； recover 缺少停止与独占维护两个确认即返回 MAINTENANCE_CONFIRMATION_REQUIRED。 恢复材料默认保留，只有显式 prune-recovery 才清理。 孤儿锁默认保留；清理要么整体 --remove-orphans，要么按边精确 --remove-orphan-edge \u003cedgeId\u003e，两者互斥。 把下面三条同时成立，才值得引入制品链：助手参与写研发产物；「做完」需要被机器验证；接受 Git 作为唯一事实来源。任一条件不成立，继续用现有文档与 CI 即可。"},{"title":"两个工程分别管什么","page":"双工程能力矩阵","href":"00-matrix.html#roles","content":"维度 常规做法 制品链做法 归属 图能力 文档之间靠人记关系，没有工具校验 配置读取、制品扫描、索引、边关系、查询、校验、版本锁 artifact-graph（底层运行时 / CLI） 助手能力 编辑器补全、零散脚本 profile、模板、bootstrap、maintainer、where-am-i、宿主适配器、hook 指导 artifact-chain-assistant（上层插件） 事实来源 散在 wiki、脑图或口头约定 单一 Git 仓库，Git 原生即事实来源 两者共用 结果可信度 「改完了」靠人判断 评审结果协议：默认失败关闭、身份稳定、禁止自我接受 两者共用"},{"title":"安装与运行对照","page":"双工程能力矩阵","href":"00-matrix.html#install","content":"环节 常规 制品链 安装 未锁定范围的工具依赖 按 INSTALL.md 与 compatibility.json 安装已验证的精确 artifact-graph，禁止未锁定范围 构建 各自 CI 脚本 pnpm 10 会拦下原生构建，必须显式允许 better-sqlite3 校验 单测 / lint artifact-graph validate 与 version-lock audit 初始化 手写配置 artifact-chain-bootstrap 引导；context.universal_baseline 默认开启，未设好时第一次取上下文会非零退出 安全第一步 常被跳过 artifact-chain-setup 与 artifact-graph doctor 只读体检"},{"title":"先看清当前项目位置","page":"双工程能力矩阵","href":"00-matrix.html#do-now","content":"不必读完整站。下面两条只读请求用于查看 Family API 与环境位置。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 拿不准下一步时走 artifact-chain-quickstart。正式把目标项目接进来，再授权 artifact-chain-bootstrap。"},{"title":"边界对照","page":"双工程能力矩阵","href":"00-matrix.html#boundaries","content":"常见误解 实际边界 替业务写实现代码 不管。它管产出是否可追溯、可验证 当成普通依赖 lockfile 不是。version-lock 锁的是追溯关系，同时也是一次提交的事务边界 当成又一个文档站生成器 不是。知识站只是发布阅读面；工具本身产出图与锁 重组制品靠助手直接改文件 不是。语义决定留在技能层，文件集合写入由 restructure 确定性执行，且需操作者确认"},{"title":"重组能力写在哪一层","page":"双工程能力矩阵","href":"00-matrix.html#restructure-layer","content":"维度 制品链做法 归属 语义决定 功能边界、共同约束、验收项去向、关系迁移 技能层（artifact-chain-restructure） 确定性执行 检查、候选计划编译、文件集合应用与恢复 artifact-graph restructure 独立复审 只读核对候选与映射，结论绑定被复审的候选 技能层 写入前提 操作者显式确认合作式写者；恢复需显式双维护确认 操作者，机制不自证 采用边界要一并说清，否则容易把候选能力当成已发布保证： 写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS；其他平台返回不可用， 不降级到无事务写入，也不承诺全平台事务保证。 前提是合作式写者。apply 与 prune-recovery 缺少 --confirm-cooperative-writers 即拒绝； recover 缺少停止与独占维护两个确认即返回 MAINTENANCE_CONFIRMATION_REQUIRED。 恢复材料默认保留，只有显式 prune-recovery 才清理。 孤儿锁默认保留；清理要么整体 --remove-orphans，要么按边精确 --remove-orphan-edge \u003cedgeId\u003e，两者互斥。 把下面三条同时成立，才值得引入制品链：助手参与写研发产物；「做完」需要被机器验证；接受 Git 作为唯一事实来源。任一条件不成立，继续用现有文档与 CI 即可。"},{"title":"它是什么","page":"它是什么","href":"01-what.html","content":"一句话：这是一套让助手写出来的研发产物能追溯、并让机器判断链路是否首尾相接的工具与方法。它处理一个很具体的缺口——助手说「做完了」，与链路真正接上之间，常常隔着一层无法自动验证的空隙。 先看它能做什么 不必先读完原理。插件装好后，第一件事是跑 artifact-chain-help。它只读列出当前可见的 Family API 和采用步骤，也就是接下来能用的能力清单。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 拿不准从哪下手时，改用 artifact-chain-quickstart。要把目标项目接进来，再经授权走 artifact-chain-bootstrap。 解决谁的问题 使用者：要把「需求 → 场景 → 设计 → 实现 → 评审」串成可验证图，不愿只靠人记关系。 维护者：对外发开源时，要守住许可证、NOTICE 与私有边界。 助手：需要以稳定、机器能消费的方式拿到上下文和评审结果协议。 两个工程是什么关系 artifact-graph 是底层：Git 原生的 Markdown 制品图扫描与校验器（命令行 / Node 库）。artifact-chain-assistant 是上层：Codex、Claude Code 与 Kimi Code 插件，把底层能力接到日常会话；Qoder 复用共享技能，不承诺命令包装或 Stop hook 等价。 层 角色 状态 通用图内核多领域拆分 不加载领域默认值的长期方向 方向，未授权 artifact-graph 确定性图能力：配置、扫描、索引、边、查询、校验、版本锁 已实现 artifact-chain-assistant 通用助手：profile、模板、bootstrap、maintainer、适配器、hook 已实现 表中第一行是长期架构方向，还没有实施授权。不要把它和已经落地的 artifact-graph 混为一谈。 和「只写文档 / 只跑 CI」差在哪 做法 它做到什么程度 只写文档 关系靠人记，机器验不了；制品链把关系变成图与边 只跑 CI 校验代码对不对，不校验「为什么做」这条链有没有接上 制品链 文档即图、图即约束、锁即提交边界；助手产出要经过失败关闭的评审协议 已经落地的能力 契约内核：运行时侧一组稳定契约接口，上层统一调用图能力。 标准 Family API：一类制品的通用操作抽象成标准族，新类型靠配置接入。 Registry（方法注册表）公共接口：身份、清单、绑定、投影与方法选择；助手按已锁定版本接线，不复制实现身份。 doctor / artifact-chain-setup：接入之后的环境自检第一步。 判断是否需要它，看三条是否同时成立：助手参与写研发产物；要求「做完」能被机器验证；接受 Git 作为唯一事实来源。"},{"title":"先看它能做什么","page":"它是什么","href":"01-what.html#first-look","content":"不必先读完原理。插件装好后，第一件事是跑 artifact-chain-help。它只读列出当前可见的 Family API 和采用步骤，也就是接下来能用的能力清单。 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 拿不准从哪下手时，改用 artifact-chain-quickstart。要把目标项目接进来，再经授权走 artifact-chain-bootstrap。"},{"title":"解决谁的问题","page":"它是什么","href":"01-what.html#who","content":"使用者：要把「需求 → 场景 → 设计 → 实现 → 评审」串成可验证图，不愿只靠人记关系。 维护者：对外发开源时，要守住许可证、NOTICE 与私有边界。 助手：需要以稳定、机器能消费的方式拿到上下文和评审结果协议。"},{"title":"两个工程是什么关系","page":"它是什么","href":"01-what.html#two-projects","content":"artifact-graph 是底层：Git 原生的 Markdown 制品图扫描与校验器（命令行 / Node 库）。artifact-chain-assistant 是上层：Codex、Claude Code 与 Kimi Code 插件，把底层能力接到日常会话；Qoder 复用共享技能，不承诺命令包装或 Stop hook 等价。 层 角色 状态 通用图内核多领域拆分 不加载领域默认值的长期方向 方向，未授权 artifact-graph 确定性图能力：配置、扫描、索引、边、查询、校验、版本锁 已实现 artifact-chain-assistant 通用助手：profile、模板、bootstrap、maintainer、适配器、hook 已实现 表中第一行是长期架构方向，还没有实施授权。不要把它和已经落地的 artifact-graph 混为一谈。"},{"title":"和「只写文档 / 只跑 CI」差在哪","page":"它是什么","href":"01-what.html#diff","content":"做法 它做到什么程度 只写文档 关系靠人记，机器验不了；制品链把关系变成图与边 只跑 CI 校验代码对不对，不校验「为什么做」这条链有没有接上 制品链 文档即图、图即约束、锁即提交边界；助手产出要经过失败关闭的评审协议"},{"title":"已经落地的能力","page":"它是什么","href":"01-what.html#landed","content":"契约内核：运行时侧一组稳定契约接口，上层统一调用图能力。 标准 Family API：一类制品的通用操作抽象成标准族，新类型靠配置接入。 Registry（方法注册表）公共接口：身份、清单、绑定、投影与方法选择；助手按已锁定版本接线，不复制实现身份。 doctor / artifact-chain-setup：接入之后的环境自检第一步。 判断是否需要它，看三条是否同时成立：助手参与写研发产物；要求「做完」能被机器验证；接受 Git 作为唯一事实来源。"},{"title":"架构原理","page":"架构原理","href":"02-architecture.html","content":"这套结构要把助手写出来的研发产物变成一张 Git 原生、结果可复现的图。底下三层、一个内核契约、一份关系锁，各管各的事。先跑两条命令，确认这座架构是否已经立在目标项目里。 现场核对 artifact-graph doctor --format markdown artifact-graph validate --root . --warning-only 两条都给出可读结果，说明底层图能力已经接到当前项目。validate --warning-only 退出 0 仍可能包含问题，必须读 issues，不能把退出码当成图健康。插件侧等价的第一步是 artifact-chain-setup。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 三层边界 当前落地的是业务三层，互不越界： 图内核：读配置、扫制品、算关系、跑查询。当前仍内置软件领域默认类型，包括 decision、entity、feature、scenario、design 以及测试相关类型，并执行默认约束，例如禁止 scenario 直接引用 entity。项目配置可以覆盖路径和字段，这些默认值仍然来自内核。 通用助手（artifact-chain-assistant）：把内核接到开发会话，负责 profile、模板、bootstrap、适配器与 hook 指导。它调用内核，不改内核。 目标项目：自行决定制品类型、模板与技能。配置写在项目的 artifact-graph.config.yaml。覆盖配置不会把内核变成「没有领域默认值」。 调用方向是上层调下层，下层不反向依赖上层。基础工程不反向依赖领域工程，不同领域工程不互相导入内部技能。 不带领域默认值的通用内核仍是长期方向，尚未授权实施。把方向写成现状，会误导后续实现。现行默认类型与约束以本页「三层边界」为准，不把路线图的方向记录当成当前行为。 两个底层约定 Git 原生：制品就是仓库里的文件，关系留在 Git 历史里。不另起数据库，不依赖在线服务；克隆下来就能跑，离网也能验。 确定性：同样的输入得到同样的结果。助手说「做完了」之前，本地校验必须能复现、能机器判定。配置与源文件固定，输出就固定，不随执行者或机器变化。 关系怎么锁住 version-lock（关系锁）记录哪些制品关系已经确认、对应哪次内容。它不是依赖 lockfile，而是追溯关系的版本化基线，同时也是一次提交的边界：关系变了，锁就要一起刷新、一起提交。CI 常用： artifact-graph version-lock audit --root . --strict-missing-lock 来卡住「源变了但锁没刷」的漂移。禁止在 hook 或自动修复里跑 version-lock bootstrap --force，那会掩盖陈旧关系。 能力怎么长出来 Contract Kernel（契约内核）是内核对外能力的稳定边界。标准 Family API 是各业务族接入的统一接口。两者合起来，让「新增一类制品或一种能力」变成填配置，而不是改内核代码。 要在插件侧看现在有哪些 Family API 和采用步骤，运行 artifact-chain-help；拿不准入口时走 artifact-chain-quickstart。完整命令表见命令参考。当前默认类型仍由内核提供；不加载领域默认值是长期方向，见路线图。"},{"title":"现场核对","page":"架构原理","href":"02-architecture.html#verify","content":"artifact-graph doctor --format markdown artifact-graph validate --root . --warning-only 两条都给出可读结果，说明底层图能力已经接到当前项目。validate --warning-only 退出 0 仍可能包含问题，必须读 issues，不能把退出码当成图健康。插件侧等价的第一步是 artifact-chain-setup。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。"},{"title":"三层边界","page":"架构原理","href":"02-architecture.html#layers","content":"当前落地的是业务三层，互不越界： 图内核：读配置、扫制品、算关系、跑查询。当前仍内置软件领域默认类型，包括 decision、entity、feature、scenario、design 以及测试相关类型，并执行默认约束，例如禁止 scenario 直接引用 entity。项目配置可以覆盖路径和字段，这些默认值仍然来自内核。 通用助手（artifact-chain-assistant）：把内核接到开发会话，负责 profile、模板、bootstrap、适配器与 hook 指导。它调用内核，不改内核。 目标项目：自行决定制品类型、模板与技能。配置写在项目的 artifact-graph.config.yaml。覆盖配置不会把内核变成「没有领域默认值」。 调用方向是上层调下层，下层不反向依赖上层。基础工程不反向依赖领域工程，不同领域工程不互相导入内部技能。 不带领域默认值的通用内核仍是长期方向，尚未授权实施。把方向写成现状，会误导后续实现。现行默认类型与约束以本页「三层边界」为准，不把路线图的方向记录当成当前行为。"},{"title":"两个底层约定","page":"架构原理","href":"02-architecture.html#invariants","content":"Git 原生：制品就是仓库里的文件，关系留在 Git 历史里。不另起数据库，不依赖在线服务；克隆下来就能跑，离网也能验。 确定性：同样的输入得到同样的结果。助手说「做完了」之前，本地校验必须能复现、能机器判定。配置与源文件固定，输出就固定，不随执行者或机器变化。"},{"title":"关系怎么锁住","page":"架构原理","href":"02-architecture.html#version-lock","content":"version-lock（关系锁）记录哪些制品关系已经确认、对应哪次内容。它不是依赖 lockfile，而是追溯关系的版本化基线，同时也是一次提交的边界：关系变了，锁就要一起刷新、一起提交。CI 常用： artifact-graph version-lock audit --root . --strict-missing-lock 来卡住「源变了但锁没刷」的漂移。禁止在 hook 或自动修复里跑 version-lock bootstrap --force，那会掩盖陈旧关系。"},{"title":"能力怎么长出来","page":"架构原理","href":"02-architecture.html#kernel-and-family","content":"Contract Kernel（契约内核）是内核对外能力的稳定边界。标准 Family API 是各业务族接入的统一接口。两者合起来，让「新增一类制品或一种能力」变成填配置，而不是改内核代码。 要在插件侧看现在有哪些 Family API 和采用步骤，运行 artifact-chain-help；拿不准入口时走 artifact-chain-quickstart。完整命令表见命令参考。当前默认类型仍由内核提供；不加载领域默认值是长期方向，见路线图。"},{"title":"核心概念","page":"核心概念","href":"03-concepts.html","content":"这一页把散落的名词串起来：制品、关系、上下文包、评审协议、方法注册表。读完应能对着目标仓库说出有哪些制品、它们怎么连、机器怎么验。先取一份上下文，再回头看定义。 现场取上下文 artifact-graph context --target design:DESIGN-xxx artifact-graph query --from feature:FEAT-xxx --format json 返回的是可复现的上下文包雏形。--target 使用 类型:ID。插件侧看能力清单用 artifact-chain-help，体检用 artifact-chain-setup。 制品类型 制品分两套口径，不要混用数字： 基础类型：需求、场景、设计、决策、测试、实现。内核认识这些类型。 扩展类型：按项目配置开启。扩哪一类，由目标项目的 artifact-graph.config.yaml 决定，不写进内核。新增类型是在配置里加 types 条目，而不是改内核。 扩展目录、目录层级与「基线文件数量」是三组不同口径。本站不把其中一组数字套到另一组上。 追溯边与关系锁 制品之间靠边连接（谁实现谁、谁验证谁）。关系锁里有两类边： locks：实现或验证这类已确认关系，是可审计基线。CI 用 version-lock audit 卡住它。 artifactRelations：制品之间的泛化关系；缺该字段时视为空数组，需要 version-lock refresh --all 建立基线。 validate 检查的是这条链有没有接上、有没有断头引用。 评审结果协议 助手做完评审，应交回一份结构化结果，而不是一句「审完了」。要点有三： 失败关闭：校验没过就当失败，不默认放行。 稳定身份：每条结果用执行者与名称定位，重试也能对准同一条。 尝试次数封顶：允许有限重试；禁止把「自己改自己」当成通过。 单独校验一份评审结果： artifact-graph validate-review-result --file review.json 方法注册表 Registry 是方法提供方的接入面，建立在契约内核之上，管身份、清单、绑定、投影与运行期选择。图管制品与关系，注册表管能力提供方，两者正交。细节见方法注册表。 profile、模板与 hook profile：按项目裁剪要加载的技能与模板。 模板：制品起始骨架，写新制品不必从空文件开始。 hook：在 pre-commit / pre-push 自动跑校验。具体步骤在场景剧本。"},{"title":"现场取上下文","page":"核心概念","href":"03-concepts.html#context","content":"artifact-graph context --target design:DESIGN-xxx artifact-graph query --from feature:FEAT-xxx --format json 返回的是可复现的上下文包雏形。--target 使用 类型:ID。插件侧看能力清单用 artifact-chain-help，体检用 artifact-chain-setup。"},{"title":"制品类型","page":"核心概念","href":"03-concepts.html#types","content":"制品分两套口径，不要混用数字： 基础类型：需求、场景、设计、决策、测试、实现。内核认识这些类型。 扩展类型：按项目配置开启。扩哪一类，由目标项目的 artifact-graph.config.yaml 决定，不写进内核。新增类型是在配置里加 types 条目，而不是改内核。 扩展目录、目录层级与「基线文件数量」是三组不同口径。本站不把其中一组数字套到另一组上。"},{"title":"追溯边与关系锁","page":"核心概念","href":"03-concepts.html#edges","content":"制品之间靠边连接（谁实现谁、谁验证谁）。关系锁里有两类边： locks：实现或验证这类已确认关系，是可审计基线。CI 用 version-lock audit 卡住它。 artifactRelations：制品之间的泛化关系；缺该字段时视为空数组，需要 version-lock refresh --all 建立基线。 validate 检查的是这条链有没有接上、有没有断头引用。"},{"title":"评审结果协议","page":"核心概念","href":"03-concepts.html#review-result","content":"助手做完评审，应交回一份结构化结果，而不是一句「审完了」。要点有三： 失败关闭：校验没过就当失败，不默认放行。 稳定身份：每条结果用执行者与名称定位，重试也能对准同一条。 尝试次数封顶：允许有限重试；禁止把「自己改自己」当成通过。 单独校验一份评审结果： artifact-graph validate-review-result --file review.json"},{"title":"方法注册表","page":"核心概念","href":"03-concepts.html#registry","content":"Registry 是方法提供方的接入面，建立在契约内核之上，管身份、清单、绑定、投影与运行期选择。图管制品与关系，注册表管能力提供方，两者正交。细节见方法注册表。"},{"title":"profile、模板与 hook","page":"核心概念","href":"03-concepts.html#daily","content":"profile：按项目裁剪要加载的技能与模板。 模板：制品起始骨架，写新制品不必从空文件开始。 hook：在 pre-commit / pre-push 自动跑校验。具体步骤在场景剧本。"},{"title":"命令参考","page":"命令参考","href":"04-cli.html","content":"下面的清单以 artifact-graph --help 为命令真源。工程改了命令，以当前 CLI 帮助文本为准，不另维护一份会过期的表。拿不准某个命令怎么用，先跑 --help；拿不准该用哪个插件能力，走 artifact-chain-help 或 artifact-chain-quickstart。 先看全貌 artifact-graph --help artifact-graph version-lock --help artifact-graph contract --help 插件侧 artifact-chain-help 列出的是 Family API 与采用步骤，见方法注册表。CLI 命令本身永远以 --help 为准。 命令怎么分两层 artifact-graph 有两层：顶层命令直接跟在 artifact-graph 后面；version-lock、contract、hooks 必须再跟子命令。 顶层命令 命令 作用 典型调用 init 在当前仓库建配置骨架 artifact-graph init --root . scan 扫描制品源、建立或更新索引 artifact-graph scan validate 验制品链完整性 artifact-graph validate --root . --warning-only query 只读查询制品与关系 artifact-graph query --from \u003ccode\u003e --format json context 抽取确定性上下文 artifact-graph context --target design:D-xxx --mode implementation packet 把上下文包写入文件 artifact-graph packet --target design:D-xxx --out packet.json packet-prompt 把上下文包转成给助手的提示词 artifact-graph packet-prompt --target design:D-xxx --out prompt.md packet-audit 批量审计上下文包 artifact-graph packet-audit --discover --out-dir audit/ packet-prompt-audit 批量审计提示词产物 artifact-graph packet-prompt-audit --discover --out-dir audit/ version-index 生成版本索引 artifact-graph version-index --format json --out version-index.json trace-version 追溯某制品的版本链路 artifact-graph trace-version --target design:D-xxx next-id 取下一个制品 id artifact-graph next-id requirement --range main render 渲染派生文档 artifact-graph render --format mermaid doctor 环境体检 artifact-graph doctor --format markdown validate-review-result 校验评审结果协议 artifact-graph validate-review-result --file review.json generate-e2e-registry 生成端到端注册表 artifact-graph generate-e2e-registry --deterministic --check validate --warning-only 退出 0 仍可能带 issues，必须读输出。 带子命令的命令族 version-lock 子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。 contract 子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。 hooks 子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。 restructure 子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。 三个最容易搞混的点 audit 不是顶层命令，它是 version-lock audit 的子命令。 family 不是 CLI 命令。它是 Family API / Registry 的概念，运行在插件侧。 hooks 的真实动作是 install-git。 新接一个项目的建议顺序：init 建配置 → doctor 体检 → validate --warning-only 看链路 → version-lock refresh 建基线。插件里分别由 bootstrap、artifact-chain-setup、artifact-chain-help 带着走，不必硬记全部命令。"},{"title":"先看全貌","page":"命令参考","href":"04-cli.html#help","content":"artifact-graph --help artifact-graph version-lock --help artifact-graph contract --help 插件侧 artifact-chain-help 列出的是 Family API 与采用步骤，见方法注册表。CLI 命令本身永远以 --help 为准。"},{"title":"命令怎么分两层","page":"命令参考","href":"04-cli.html#layers","content":"artifact-graph 有两层：顶层命令直接跟在 artifact-graph 后面；version-lock、contract、hooks 必须再跟子命令。"},{"title":"顶层命令","page":"命令参考","href":"04-cli.html#top","content":"命令 作用 典型调用 init 在当前仓库建配置骨架 artifact-graph init --root . scan 扫描制品源、建立或更新索引 artifact-graph scan validate 验制品链完整性 artifact-graph validate --root . --warning-only query 只读查询制品与关系 artifact-graph query --from \u003ccode\u003e --format json context 抽取确定性上下文 artifact-graph context --target design:D-xxx --mode implementation packet 把上下文包写入文件 artifact-graph packet --target design:D-xxx --out packet.json packet-prompt 把上下文包转成给助手的提示词 artifact-graph packet-prompt --target design:D-xxx --out prompt.md packet-audit 批量审计上下文包 artifact-graph packet-audit --discover --out-dir audit/ packet-prompt-audit 批量审计提示词产物 artifact-graph packet-prompt-audit --discover --out-dir audit/ version-index 生成版本索引 artifact-graph version-index --format json --out version-index.json trace-version 追溯某制品的版本链路 artifact-graph trace-version --target design:D-xxx next-id 取下一个制品 id artifact-graph next-id requirement --range main render 渲染派生文档 artifact-graph render --format mermaid doctor 环境体检 artifact-graph doctor --format markdown validate-review-result 校验评审结果协议 artifact-graph validate-review-result --file review.json generate-e2e-registry 生成端到端注册表 artifact-graph generate-e2e-registry --deterministic --check validate --warning-only 退出 0 仍可能带 issues，必须读输出。"},{"title":"带子命令的命令族","page":"命令参考","href":"04-cli.html#families","content":"version-lock 子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。 contract 子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。 hooks 子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。 restructure 子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。"},{"title":"version-lock","page":"命令参考","href":"04-cli.html#version-lock","content":"子命令 作用 典型调用 audit 审计锁完整性 artifact-graph version-lock audit --root . --strict-missing-lock update 更新单个目标的锁 artifact-graph version-lock update --target design:D-xxx --source path.md bootstrap 建立初始基线 artifact-graph version-lock bootstrap refresh 刷新受影响的关系锁 artifact-graph version-lock refresh --changed-only --worktree --format markdown bootstrap --force 不得出现在 hook 或自动修复里，除非得到明确授权。 refresh 默认保留孤儿锁，清理始终是显式动作：--remove-orphans 删除所有当前孤儿； 只清理本次改号产生的那一条边时用 --remove-orphan-edge \u003cedgeId\u003e，可重复指定，且与 --remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的 既有孤儿不会被连带清理。"},{"title":"contract","page":"命令参考","href":"04-cli.html#contract","content":"子命令 作用 典型调用 list 列出已注册契约 artifact-graph contract list --format json explain 解释某个契约 artifact-graph contract explain --contract \u003cmajor-id\u003e validate 用契约校验数据 artifact-graph contract validate --contract \u003cmajor-id\u003e --data '{}' normalize 规范化数据 artifact-graph contract normalize --contract \u003cmajor-id\u003e --data '{}' check-policy 检查策略 artifact-graph contract check-policy --contract \u003cmajor-id\u003e --policy '{}' validate-markers 校验 Markdown 里的契约标记 artifact-graph contract validate-markers --contract \u003cmajor-id\u003e --markdown path.md check-policy 只服务其已约定的单调加严合同，不能当成通用例外判定。"},{"title":"hooks","page":"命令参考","href":"04-cli.html#hooks","content":"子命令 作用 典型调用 install-git 安装 git 钩子 artifact-graph hooks install-git --hook all 卸载 卸掉已装钩子 artifact-graph hooks install-git --uninstall 真实子命令是 install-git，不是 install。--root 是全局参数，在仓库目录内可省略。"},{"title":"restructure","page":"命令参考","href":"04-cli.html#restructure","content":"子命令 作用 典型调用 inspect 只读检查重组来源与入边出边 artifact-graph restructure inspect --root . --input request.json plan 把映射编译为候选计划 artifact-graph restructure plan --root . --input mapping.json apply 按计划应用文件集合 artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers recover 中断后的显式恢复 artifact-graph restructure recover --root . --plan plan.json --confirm-all-participants-stopped --confirm-exclusive-maintenance prune-recovery 显式清理恢复材料 artifact-graph restructure prune-recovery --root . --plan plan.json --confirm-cooperative-writers 三类变换是 record-split（记录物理拆分）、identity-split（编号身份拆分）与 move-renumber（跨文件移动与重编号）。图内核只做确定性编译与应用；能力边界、验收项去向 与模糊关系解释由技能层给出，不进入 CLI。 apply 不会自证并发前提：必须由操作者给出 --confirm-cooperative-writers，缺失即拒绝且 不写目标文件。recover 需要 --confirm-all-participants-stopped 与 --confirm-exclusive-maintenance 同时给出。写入能力成熟度为 candidate，资格环境仅为 Darwin / arm64 / APFS，不承诺全平台事务保证；恢复材料默认保留，只有显式 prune-recovery 才清理。计划文档要持久化到写集之外的普通目录，恢复只依赖该文档。写后校验按 fail-closed 处理规划之后新出现的消费者引用，因此不要把 plan / apply 的 stdout 重定向进项目根内： 规划之后在根内新建、且提到候选路径的文件会被读成未计划消费者，本次 apply 回滚且零残留， 需要重新规划。"},{"title":"三个最容易搞混的点","page":"命令参考","href":"04-cli.html#pitfalls","content":"audit 不是顶层命令，它是 version-lock audit 的子命令。 family 不是 CLI 命令。它是 Family API / Registry 的概念，运行在插件侧。 hooks 的真实动作是 install-git。 新接一个项目的建议顺序：init 建配置 → doctor 体检 → validate --warning-only 看链路 → version-lock refresh 建基线。插件里分别由 bootstrap、artifact-chain-setup、artifact-chain-help 带着走，不必硬记全部命令。"},{"title":"场景剧本","page":"场景剧本","href":"05-scenarios.html","content":"这一页不讲概念，直接走最常见的五条任务。每条都给出入口、必要输入和成功信号。遇到分叉再用 artifact-chain-quickstart。CLI 能跑的标了命令，插件侧才有的用提示词。 场景一 · 第一次把项目接进来 新仓库还没有制品链配置。先做只读体检，再经授权走 bootstrap：它会问要哪些制品类型、要不要 hook。完成后得到一份配置骨架和一张空图，等后续填写。 请先使用 artifact-chain-setup 检查环境；若需要初始化，列出将写入的配置与 hook，等待明确授权后再执行 artifact-chain-bootstrap。 也可以先用 CLI 建配置并体检： artifact-graph init --root . artifact-graph doctor --format markdown 向导生成的 artifact-graph.config.yaml 声明本项目有哪些制品类型、各自路径和 id 形态。之后每写一份制品、跑一次 validate，都是在往这张图里填节点和边。doctor 只读检查 CLI、Node 与原生构建，不写文件。 场景二 · 扩展一类制品 要加一类项目自己的制品，例如运维手册。内核不认识新类型。在目标项目配置里补上类型与路径，再刷新关系锁建立新基线： types: runbook: paths: [\"docs/runbooks/**/*.md\"] idPatterns: runbook: \"^RUN-[0-9]{3}$\" artifact-graph version-lock refresh --all --format markdown artifact-graph validate --root . --warning-only 路径用 glob，id 用正则。类型变了，旧基线对不上，所以要刷新锁。validate --warning-only 只报不阻断，方便边改边看。 场景三 · 把校验卡在提交之前 不想靠人记得跑校验时，让 git hook 在提交和推送时自动跑： artifact-graph hooks install-git --hook all --hook all 同时装 pre-commit 与 pre-push。pre-commit 刷新关系锁并检查锁是否随暂存内容漂移；pre-push 跑 validate --warning-only 与 version-lock audit --strict-missing-lock。要卸掉就重跑 install-git --uninstall。hook 只在本机生效，CI 需要独立检查步骤。 场景四 · 接 Codex / Claude / Kimi 按 INSTALL.md 把 artifact-chain-assistant 装进对应宿主。日常先看能力、再体检： 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 装好插件后，不必记全部 CLI 细节。用自然语言描述制品链任务，由 Family API 找到对应能力，由 Registry 负责选择实现。Qoder 复用共享技能，不提供 Claude 那套命令包装与 Stop hook。 场景五 · 带着上下文去改实现 助手改一段代码时，需要知道这次改动满足哪份需求、哪份设计。用 context 取一份上下文包： artifact-graph context --target design:DESIGN-xxx --format markdown artifact-graph packet-prompt --target design:DESIGN-xxx --out prompt.md 上下文包把「这个设计被谁实现、验证过没有」一并抽出。默认开启 context.universal_baseline，缺少约定的基线文件会非零退出。轻量项目可在配置里显式关闭该门槛，或把缺的文件补上。这是基线认知门槛，不是故障。 场景六 · 重组已有制品（拆分 / 改号 / 跨批次移动） 一条记录里塞了两件可独立验收的要求，或者一批用例该换批次和编号时，不要手改：先只读检查， 再把语义决定编译成候选计划，确认后一次性应用。 artifact-graph restructure inspect --root . --input request.json --format json artifact-graph restructure plan --root . --input mapping.json --format json artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers inspect 只读，给出记录跨度、每条关系的出现位置和映射模板。语义作者据此决定功能边界、 共同约束、验收项去向和关系迁移；随后一次独立只读复审，结论只绑定被复审的那份候选。 plan 输出候选、图差异与阻断项；applicable 不为真时不进 apply。 三条限制必须记住： apply 必须由操作者给出 --confirm-cooperative-writers；机制不假设该前提，缺失就拒绝且 不写目标文件。写入能力目前是 candidate 成熟度，资格环境仅为 Darwin / arm64 / APFS。 计划文档要持久化到写集之外的普通目录。进程被中断时只有该文档能用来恢复： restructure recover --plan ... --confirm-all-participants-stopped --confirm-exclusive-maintenance， 两个确认必须同时给出。恢复材料默认保留，只有显式 prune-recovery 才清理。 重组会让旧关系锁变成孤儿。只清理本次改号产生的那条边： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e --remove-orphan-edge 与 --remove-orphans 互斥；被点名的边仍是活边时拒绝删除，同一锁文件 里的既有孤儿也不会被连带清理。只给\"分析并生成迁移计划\"的授权时，不要执行 apply。 出口 接新项目：setup 体检，授权后 bootstrap；或 CLI init + doctor。 加制品类型：改配置 paths / idPatterns，再 refresh + validate。 卡提交：hooks install-git --hook all。 接助手：按 INSTALL.md 安装插件，用 help / setup 起步，用 context 取上下文。 重组制品：restructure inspect → 语义映射 + 独立复审 → plan → 确认后 apply， 再用 --remove-orphan-edge 收尾本次产生的孤儿锁。"},{"title":"场景一 · 第一次把项目接进来","page":"场景剧本","href":"05-scenarios.html#bootstrap","content":"新仓库还没有制品链配置。先做只读体检，再经授权走 bootstrap：它会问要哪些制品类型、要不要 hook。完成后得到一份配置骨架和一张空图，等后续填写。 请先使用 artifact-chain-setup 检查环境；若需要初始化，列出将写入的配置与 hook，等待明确授权后再执行 artifact-chain-bootstrap。 也可以先用 CLI 建配置并体检： artifact-graph init --root . artifact-graph doctor --format markdown 向导生成的 artifact-graph.config.yaml 声明本项目有哪些制品类型、各自路径和 id 形态。之后每写一份制品、跑一次 validate，都是在往这张图里填节点和边。doctor 只读检查 CLI、Node 与原生构建，不写文件。"},{"title":"场景二 · 扩展一类制品","page":"场景剧本","href":"05-scenarios.html#extend-type","content":"要加一类项目自己的制品，例如运维手册。内核不认识新类型。在目标项目配置里补上类型与路径，再刷新关系锁建立新基线： types: runbook: paths: [\"docs/runbooks/**/*.md\"] idPatterns: runbook: \"^RUN-[0-9]{3}$\" artifact-graph version-lock refresh --all --format markdown artifact-graph validate --root . --warning-only 路径用 glob，id 用正则。类型变了，旧基线对不上，所以要刷新锁。validate --warning-only 只报不阻断，方便边改边看。"},{"title":"场景三 · 把校验卡在提交之前","page":"场景剧本","href":"05-scenarios.html#hooks","content":"不想靠人记得跑校验时，让 git hook 在提交和推送时自动跑： artifact-graph hooks install-git --hook all --hook all 同时装 pre-commit 与 pre-push。pre-commit 刷新关系锁并检查锁是否随暂存内容漂移；pre-push 跑 validate --warning-only 与 version-lock audit --strict-missing-lock。要卸掉就重跑 install-git --uninstall。hook 只在本机生效，CI 需要独立检查步骤。"},{"title":"场景四 · 接 Codex / Claude / Kimi","page":"场景剧本","href":"05-scenarios.html#hosts","content":"按 INSTALL.md 把 artifact-chain-assistant 装进对应宿主。日常先看能力、再体检： 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 装好插件后，不必记全部 CLI 细节。用自然语言描述制品链任务，由 Family API 找到对应能力，由 Registry 负责选择实现。Qoder 复用共享技能，不提供 Claude 那套命令包装与 Stop hook。"},{"title":"场景五 · 带着上下文去改实现","page":"场景剧本","href":"05-scenarios.html#context","content":"助手改一段代码时，需要知道这次改动满足哪份需求、哪份设计。用 context 取一份上下文包： artifact-graph context --target design:DESIGN-xxx --format markdown artifact-graph packet-prompt --target design:DESIGN-xxx --out prompt.md 上下文包把「这个设计被谁实现、验证过没有」一并抽出。默认开启 context.universal_baseline，缺少约定的基线文件会非零退出。轻量项目可在配置里显式关闭该门槛，或把缺的文件补上。这是基线认知门槛，不是故障。"},{"title":"场景六 · 重组已有制品（拆分 / 改号 / 跨批次移动）","page":"场景剧本","href":"05-scenarios.html#restructure","content":"一条记录里塞了两件可独立验收的要求，或者一批用例该换批次和编号时，不要手改：先只读检查， 再把语义决定编译成候选计划，确认后一次性应用。 artifact-graph restructure inspect --root . --input request.json --format json artifact-graph restructure plan --root . --input mapping.json --format json artifact-graph restructure apply --root . --plan plan.json --confirm-cooperative-writers inspect 只读，给出记录跨度、每条关系的出现位置和映射模板。语义作者据此决定功能边界、 共同约束、验收项去向和关系迁移；随后一次独立只读复审，结论只绑定被复审的那份候选。 plan 输出候选、图差异与阻断项；applicable 不为真时不进 apply。 三条限制必须记住： apply 必须由操作者给出 --confirm-cooperative-writers；机制不假设该前提，缺失就拒绝且 不写目标文件。写入能力目前是 candidate 成熟度，资格环境仅为 Darwin / arm64 / APFS。 计划文档要持久化到写集之外的普通目录。进程被中断时只有该文档能用来恢复： restructure recover --plan ... --confirm-all-participants-stopped --confirm-exclusive-maintenance， 两个确认必须同时给出。恢复材料默认保留，只有显式 prune-recovery 才清理。 重组会让旧关系锁变成孤儿。只清理本次改号产生的那条边： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e --remove-orphan-edge 与 --remove-orphans 互斥；被点名的边仍是活边时拒绝删除，同一锁文件 里的既有孤儿也不会被连带清理。只给\"分析并生成迁移计划\"的授权时，不要执行 apply。"},{"title":"出口","page":"场景剧本","href":"05-scenarios.html#takeaway","content":"接新项目：setup 体检，授权后 bootstrap；或 CLI init + doctor。 加制品类型：改配置 paths / idPatterns，再 refresh + validate。 卡提交：hooks install-git --hook all。 接助手：按 INSTALL.md 安装插件，用 help / setup 起步，用 context 取上下文。 重组制品：restructure inspect → 语义映射 + 独立复审 → plan → 确认后 apply， 再用 --remove-orphan-edge 收尾本次产生的孤儿锁。"},{"title":"方法注册表","page":"方法注册表","href":"06-method-registry.html","content":"助手要调用一种能力时，不直接硬编码实现，而是走标准 Family API，由 Registry 找到真正的提供方。换实现、加能力时，调用方不必改路由逻辑。本仓助手按已锁定的 Registry 公共接口接线，不复制实现身份，也不把 worker.skill 当成绑定。 先看当前可见能力 请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 Family API Catalog 来自插件自带文件，Registry 缺失时静态能力仍可展示。动态安装状态在 Registry v2 verifier 未接入时显示为不可用，不得把候选清单写成已验证提供方。 配置是否合法，仍用图入口核对： artifact-graph validate --root . --warning-only artifact-graph contract list --format json family / registry 是 SPI 概念，运行在插件与助手侧。CLI 不直接暴露这两个子命令。 Registry 管五件事 身份：每个方法提供方有稳定标识，重试和审计都能对准同一个提供方。 清单：登记有哪些方法、各自提供什么能力。宿主发现的插件只能形成候选，不能直接当成可信提供方。 绑定：把能力名映射到具体实现。默认整族原子绑定，避免 author 来自实现 A、review 来自不兼容实现 B。 投影：按调用方视角裁剪暴露的方法；从 API、实现与可信清单确定性生成。 运行期选择：一次运行内，同名方法不许中途替换。安装插件不得自动改写已有项目的有效绑定。 本仓 where-am-i 生成 Method Query candidate，把已解析的绑定对象交给 Registry 的 buildEffectiveIndex 与 queryEffectiveIndex。下游消费返回的 serviceId、apiId、apiMajor 及原生选择状态。 为什么需要它 同一项目可能同时看到开源实现与内部实现，两者都提供同名能力。没有注册表时，今天走到开源、明天走到内部，结果不可复现。有了 Registry：身份区分两个提供方；绑定按项目配置锁定整族实现；运行期选择保证这次运行始终路由到同一实现；投影避免规划器调到未验证的候选。 和图内核的关系 Registry 与 artifact-graph 的图结构正交：图管制品与关系，注册表管能力提供方。两者不互相导入内部实现。缺绑定时保留 Registry 原始不可执行状态；help 与单纯图检查不受影响。"},{"title":"先看当前可见能力","page":"方法注册表","href":"06-method-registry.html#help","content":"请使用 artifact-chain-help 展示可用的 Family API 和采用步骤，不要修改项目。 Family API Catalog 来自插件自带文件，Registry 缺失时静态能力仍可展示。动态安装状态在 Registry v2 verifier 未接入时显示为不可用，不得把候选清单写成已验证提供方。 配置是否合法，仍用图入口核对： artifact-graph validate --root . --warning-only artifact-graph contract list --format json family / registry 是 SPI 概念，运行在插件与助手侧。CLI 不直接暴露这两个子命令。"},{"title":"Registry 管五件事","page":"方法注册表","href":"06-method-registry.html#spi","content":"身份：每个方法提供方有稳定标识，重试和审计都能对准同一个提供方。 清单：登记有哪些方法、各自提供什么能力。宿主发现的插件只能形成候选，不能直接当成可信提供方。 绑定：把能力名映射到具体实现。默认整族原子绑定，避免 author 来自实现 A、review 来自不兼容实现 B。 投影：按调用方视角裁剪暴露的方法；从 API、实现与可信清单确定性生成。 运行期选择：一次运行内，同名方法不许中途替换。安装插件不得自动改写已有项目的有效绑定。 本仓 where-am-i 生成 Method Query candidate，把已解析的绑定对象交给 Registry 的 buildEffectiveIndex 与 queryEffectiveIndex。下游消费返回的 serviceId、apiId、apiMajor 及原生选择状态。"},{"title":"为什么需要它","page":"方法注册表","href":"06-method-registry.html#why","content":"同一项目可能同时看到开源实现与内部实现，两者都提供同名能力。没有注册表时，今天走到开源、明天走到内部，结果不可复现。有了 Registry：身份区分两个提供方；绑定按项目配置锁定整族实现；运行期选择保证这次运行始终路由到同一实现；投影避免规划器调到未验证的候选。"},{"title":"和图内核的关系","page":"方法注册表","href":"06-method-registry.html#orthogonal","content":"Registry 与 artifact-graph 的图结构正交：图管制品与关系，注册表管能力提供方。两者不互相导入内部实现。缺绑定时保留 Registry 原始不可执行状态；help 与单纯图检查不受影响。"},{"title":"术语库","page":"术语库","href":"07-glossary.html","content":"本页汇总站点反复使用的术语。旧版用页面脚本做悬停气泡；本版把定义写在这里，并可用站点搜索定位。正文里第一次依赖某个词时，也会就近解释。 工程与入口 术语 含义 artifact-graph 底层运行时、CLI 与 Node 库。扫描 Markdown 制品、建图、校验、维护关系锁。 artifact-chain-assistant 上层插件。把图能力接到 Codex、Claude Code、Kimi Code；Qoder 复用共享技能。 Family API 一类制品的标准操作接口，例如 help、author、review、repair。 artifact-chain-help 只读能力说明入口，展示 Family API 与采用步骤。 artifact-chain-setup 默认只读的环境诊断；机械安装步骤须经明确确认。 artifact-chain-quickstart 按自然语言意图路由到正确入口，不执行被路由技能的业务逻辑。 artifact-chain-bootstrap 经授权后做项目级配置决策：类型裁剪、配置合同、版本锁与工作法章节。 artifact-audit 只读健康与能力检查，消费图校验和关系锁结果，不运行目标测试或构建。 图与锁 术语 含义 Git 原生 制品是仓库文件，关系留在 Git 历史；克隆即可跑，不另起数据库。 确定性 同样输入得到同样输出，校验结果可复现、可机器判定。 version-lock 追溯关系的版本化基线，也是一次提交的事务边界。不是依赖 lockfile。 locks 已确认的实现或验证关系。 artifactRelations 制品之间的泛化关系；缺字段时视为空。 失败关闭 校验没过就当失败，不默认放行。 上下文包 按目标制品抽出的上下游材料，供助手消费。 universal_baseline 取上下文前要求一组基线文件存在；缺文件则非零退出。 评审与注册表 术语 含义 评审结果协议 结构化评审输出：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 Contract Kernel 内核对外能力的稳定契约边界。 Registry 方法提供方的身份、清单、绑定、投影与运行期选择。与图结构正交。 整族原子绑定 同一族服务默认来自同一实现，避免混绑不兼容实现。 compatibility.json 插件与已验证 artifact-graph 版本的配对记录。 需要命令细节时回到命令参考；需要排错步骤时到排错与兼容。"},{"title":"工程与入口","page":"术语库","href":"07-glossary.html#projects","content":"术语 含义 artifact-graph 底层运行时、CLI 与 Node 库。扫描 Markdown 制品、建图、校验、维护关系锁。 artifact-chain-assistant 上层插件。把图能力接到 Codex、Claude Code、Kimi Code；Qoder 复用共享技能。 Family API 一类制品的标准操作接口，例如 help、author、review、repair。 artifact-chain-help 只读能力说明入口，展示 Family API 与采用步骤。 artifact-chain-setup 默认只读的环境诊断；机械安装步骤须经明确确认。 artifact-chain-quickstart 按自然语言意图路由到正确入口，不执行被路由技能的业务逻辑。 artifact-chain-bootstrap 经授权后做项目级配置决策：类型裁剪、配置合同、版本锁与工作法章节。 artifact-audit 只读健康与能力检查，消费图校验和关系锁结果，不运行目标测试或构建。"},{"title":"图与锁","page":"术语库","href":"07-glossary.html#graph","content":"术语 含义 Git 原生 制品是仓库文件，关系留在 Git 历史；克隆即可跑，不另起数据库。 确定性 同样输入得到同样输出，校验结果可复现、可机器判定。 version-lock 追溯关系的版本化基线，也是一次提交的事务边界。不是依赖 lockfile。 locks 已确认的实现或验证关系。 artifactRelations 制品之间的泛化关系；缺字段时视为空。 失败关闭 校验没过就当失败，不默认放行。 上下文包 按目标制品抽出的上下游材料，供助手消费。 universal_baseline 取上下文前要求一组基线文件存在；缺文件则非零退出。"},{"title":"评审与注册表","page":"术语库","href":"07-glossary.html#review-registry","content":"术语 含义 评审结果协议 结构化评审输出：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 Contract Kernel 内核对外能力的稳定契约边界。 Registry 方法提供方的身份、清单、绑定、投影与运行期选择。与图结构正交。 整族原子绑定 同一族服务默认来自同一实现，避免混绑不兼容实现。 compatibility.json 插件与已验证 artifact-graph 版本的配对记录。 需要命令细节时回到命令参考；需要排错步骤时到排错与兼容。"},{"title":"维护者视角","page":"维护者视角","href":"08-maintainer.html","content":"发版维护者要同时对外公开与守住私有边界。这一页讲发布治理的通用原则，不点名内部脚本。落到目标仓库时，把下面三件事接进自己的发布流水线即可。铁律是：宁可发布失败，也不漏私有内容。 发布前自检三件事 内容级泄漏扫描：发布产物里不能出现本机用户目录、私有仓名、密钥或令牌。扫描必须先解码 HTML 实体和 JS 转义再匹配，否则编码拼接能绕过字面检查。 文档树摘要锁：给每个文档的标题与章节结构算摘要，和上次比对。结构被误删或章节被改动时立刻发现。 链接越界断言：站内链接不能跳出本站范围；外链只允许指向已发布仓库的固定版本地址，禁用外部 CDN、webfont 或统计脚本。 本站的渲染器会在写入目标前做泄漏扫描，并生成 site-baseline.json 作为产物树摘要。--check 把内存渲染与磁盘基线比对；不一致即漂移。 两条铁律 声明式配置单一来源：发布什么、拷到哪、哪些路径禁止外泄，都写在一份配置里，脚本照着跑。Review 一份配置就能知道这次发版会带出什么。 物理公私隔离：私有内容与公开内容走不同目录，发布前做隔离校验。内容级正则、机器可读边界配置、路径禁止清单三层里任意一层拦到，发布就停。 把自检接进流水线 预提交：本地改了文档或站点，锁或基线变了就拦下，要求回到权威源并重新渲染。这防止只改渲染产物。 推送前：再跑完整性与锁审计，确保进共享仓库的内容干净。 CI / 公开发布前：完整性校验、锁审计、测试与发布就绪性验证。任何一项失败都不进发布。 具体命令以目标仓库自己的发布配置为准。本页不列父工程私有脚本名。 OSS 合规与双语 对外发布的文档遵循 Apache-2.0 与 NOTICE。README、CHANGELOG、INSTALL 维持中英双语；本知识站正文以中文优先。克隆到新仓库时，onboarding 应能照着做就跑起来，这正是 bootstrap 向导存在的原因。许可证头、NOTICE、第三方归属要随每次发版复核。 重组与锁收尾 制品拆分、改号或跨批次移动之后，旧关系锁会变成孤儿。锁清理是发布前的显式维护动作，不是 自动收尾： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e 只点名本次重组产生的那条边。--remove-orphans 是整体清理，与 --remove-orphan-edge 互斥； 同一锁文件里的既有孤儿不因本次重组被连带删除，清理前后的条目都能在锁文件 diff 里回看。 恢复材料默认保留，只有显式 restructure prune-recovery 才清理。 重组写入能力的成熟度是 candidate，资格环境仅为 Darwin / arm64 / APFS，前提是合作式写者， 恢复需要显式的双维护确认。维护者不得把它写成已发布的全平台事务保证，也不得因为 apply 能跑通就省略操作者确认。 派生文档防漂移 很多文档是渲染出来的副本，不是手写权威源。这类文档必须带生成横幅，并能重新渲染后与已提交基线比对；不一致即漂移。只在产物上改、不回改权威源，下次渲染会覆盖改动。外链必须钉到具体版本标签，不能指向会漂移的默认分支。 请使用 artifact-chain-maintainer 说明当前关系锁与文档派生检查该如何刷新；列出将写入的路径，等待授权后再执行。 未授权方向不得写成已实现能力。状态口径见路线图。"},{"title":"发布前自检三件事","page":"维护者视角","href":"08-maintainer.html#preflight","content":"内容级泄漏扫描：发布产物里不能出现本机用户目录、私有仓名、密钥或令牌。扫描必须先解码 HTML 实体和 JS 转义再匹配，否则编码拼接能绕过字面检查。 文档树摘要锁：给每个文档的标题与章节结构算摘要，和上次比对。结构被误删或章节被改动时立刻发现。 链接越界断言：站内链接不能跳出本站范围；外链只允许指向已发布仓库的固定版本地址，禁用外部 CDN、webfont 或统计脚本。 本站的渲染器会在写入目标前做泄漏扫描，并生成 site-baseline.json 作为产物树摘要。--check 把内存渲染与磁盘基线比对；不一致即漂移。"},{"title":"两条铁律","page":"维护者视角","href":"08-maintainer.html#rules","content":"声明式配置单一来源：发布什么、拷到哪、哪些路径禁止外泄，都写在一份配置里，脚本照着跑。Review 一份配置就能知道这次发版会带出什么。 物理公私隔离：私有内容与公开内容走不同目录，发布前做隔离校验。内容级正则、机器可读边界配置、路径禁止清单三层里任意一层拦到，发布就停。"},{"title":"把自检接进流水线","page":"维护者视角","href":"08-maintainer.html#gates","content":"预提交：本地改了文档或站点，锁或基线变了就拦下，要求回到权威源并重新渲染。这防止只改渲染产物。 推送前：再跑完整性与锁审计，确保进共享仓库的内容干净。 CI / 公开发布前：完整性校验、锁审计、测试与发布就绪性验证。任何一项失败都不进发布。 具体命令以目标仓库自己的发布配置为准。本页不列父工程私有脚本名。"},{"title":"OSS 合规与双语","page":"维护者视角","href":"08-maintainer.html#oss","content":"对外发布的文档遵循 Apache-2.0 与 NOTICE。README、CHANGELOG、INSTALL 维持中英双语；本知识站正文以中文优先。克隆到新仓库时，onboarding 应能照着做就跑起来，这正是 bootstrap 向导存在的原因。许可证头、NOTICE、第三方归属要随每次发版复核。"},{"title":"重组与锁收尾","page":"维护者视角","href":"08-maintainer.html#restructure-locks","content":"制品拆分、改号或跨批次移动之后，旧关系锁会变成孤儿。锁清理是发布前的显式维护动作，不是 自动收尾： artifact-graph version-lock refresh --changed-only --worktree --remove-orphan-edge \u003cedgeId\u003e 只点名本次重组产生的那条边。--remove-orphans 是整体清理，与 --remove-orphan-edge 互斥； 同一锁文件里的既有孤儿不因本次重组被连带删除，清理前后的条目都能在锁文件 diff 里回看。 恢复材料默认保留，只有显式 restructure prune-recovery 才清理。 重组写入能力的成熟度是 candidate，资格环境仅为 Darwin / arm64 / APFS，前提是合作式写者， 恢复需要显式的双维护确认。维护者不得把它写成已发布的全平台事务保证，也不得因为 apply 能跑通就省略操作者确认。"},{"title":"派生文档防漂移","page":"维护者视角","href":"08-maintainer.html#derived","content":"很多文档是渲染出来的副本，不是手写权威源。这类文档必须带生成横幅，并能重新渲染后与已提交基线比对；不一致即漂移。只在产物上改、不回改权威源，下次渲染会覆盖改动。外链必须钉到具体版本标签，不能指向会漂移的默认分支。 请使用 artifact-chain-maintainer 说明当前关系锁与文档派生检查该如何刷新；列出将写入的路径，等待授权后再执行。 未授权方向不得写成已实现能力。状态口径见路线图。"},{"title":"排错与兼容","page":"排错与兼容","href":"09-troubleshoot.html","content":"跑不起来或结果不对时，先体检再猜。这一页是 artifact-chain-setup 与 artifact-graph doctor 的主场。两者都只读，可以反复跑。 先体检 artifact-graph doctor --format markdown 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 多数问题会直接报出来：CLI 找不到、配置缺字段、Node 版本不够、原生构建 better-sqlite3 被 pnpm 跳过。把体检输出对照下面的症状。 常见症状 第一次跑 context / packet 就非零退出：多半是 context.universal_baseline 默认开启，而项目缺少约定的基线文件。轻量项目在配置里显式关闭该门槛，或把缺的文件补上。 安装后报 missing binding 或原生模块缺失：原生构建被拦了。在 pnpm 10.26+ 用 allowBuilds，更早的 10.x 用 onlyBuiltDependencies，允许 better-sqlite3。装完用 doctor 复核。 关系锁漂移：源文件或关系变了但锁没刷。先验收受影响的内容，确认关系仍成立，再更新锁。日常工作树用 artifact-graph version-lock refresh --changed-only --worktree 只刷已确认的受影响锁；提交前改用 --staged。--all 重建全量基线。锁和源一起提交。禁止在 hook 里跑 version-lock bootstrap --force。 validate 报断头边：某制品声称被一份设计实现，但那份设计不存在或 id 写错。补上缺失制品，或修正标记里的 id。 CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。 CI 红、本地绿 常见只有两类原因： 原生构建差异：CI 的 pnpm 版本或缓存策略跳过了 better-sqlite3。对照本地 doctor 输出，确认 CI 镜像也带白名单。 基线门槛差异：CI 是干净 checkout，universal_baseline 发现缺文件直接非零退出，本地恰好有这些文件所以没报。在项目配置里显式声明：要么补齐文件，要么关掉该门槛。 排查时把 CI 的命令复制到本地，加 --warning-only 再跑一遍，通常能立刻复现。validate --warning-only 退出 0 仍要读 issues。 把问题缩到最小 症状不直观时，先做最小复现：新建一个只含一份需求与一份设计的仓库，跑 init → validate。能复现，说明是配置或能力本身的问题；不能复现，说明是当前项目某份制品把图带歪了。这时用 query 把关系拉出来看，比猜测快。 兼容 版本配对写在插件的 compatibility.json：Node、CLI 与插件版本。升级前先看该文件，避免本地能跑、CI 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 0.14.2。"},{"title":"先体检","page":"排错与兼容","href":"09-troubleshoot.html#doctor","content":"artifact-graph doctor --format markdown 请使用 artifact-chain-setup 检查制品链环境是否就绪，不要修改项目。 多数问题会直接报出来：CLI 找不到、配置缺字段、Node 版本不够、原生构建 better-sqlite3 被 pnpm 跳过。把体检输出对照下面的症状。"},{"title":"常见症状","page":"排错与兼容","href":"09-troubleshoot.html#symptoms","content":"第一次跑 context / packet 就非零退出：多半是 context.universal_baseline 默认开启，而项目缺少约定的基线文件。轻量项目在配置里显式关闭该门槛，或把缺的文件补上。 安装后报 missing binding 或原生模块缺失：原生构建被拦了。在 pnpm 10.26+ 用 allowBuilds，更早的 10.x 用 onlyBuiltDependencies，允许 better-sqlite3。装完用 doctor 复核。 关系锁漂移：源文件或关系变了但锁没刷。先验收受影响的内容，确认关系仍成立，再更新锁。日常工作树用 artifact-graph version-lock refresh --changed-only --worktree 只刷已确认的受影响锁；提交前改用 --staged。--all 重建全量基线。锁和源一起提交。禁止在 hook 里跑 version-lock bootstrap --force。 validate 报断头边：某制品声称被一份设计实现，但那份设计不存在或 id 写错。补上缺失制品，或修正标记里的 id。 CLI 报 unknown command：多半敲了文档里的占位命令。以 --help 为准。例如 hook 是 hooks install-git 而不是 hooks install。"},{"title":"CI 红、本地绿","page":"排错与兼容","href":"09-troubleshoot.html#ci","content":"常见只有两类原因： 原生构建差异：CI 的 pnpm 版本或缓存策略跳过了 better-sqlite3。对照本地 doctor 输出，确认 CI 镜像也带白名单。 基线门槛差异：CI 是干净 checkout，universal_baseline 发现缺文件直接非零退出，本地恰好有这些文件所以没报。在项目配置里显式声明：要么补齐文件，要么关掉该门槛。 排查时把 CI 的命令复制到本地，加 --warning-only 再跑一遍，通常能立刻复现。validate --warning-only 退出 0 仍要读 issues。"},{"title":"把问题缩到最小","page":"排错与兼容","href":"09-troubleshoot.html#minimize","content":"症状不直观时，先做最小复现：新建一个只含一份需求与一份设计的仓库，跑 init → validate。能复现，说明是配置或能力本身的问题；不能复现，说明是当前项目某份制品把图带歪了。这时用 query 把关系拉出来看，比猜测快。"},{"title":"兼容","page":"排错与兼容","href":"09-troubleshoot.html#compat","content":"版本配对写在插件的 compatibility.json：Node、CLI 与插件版本。升级前先看该文件，避免本地能跑、CI 挂。能力是否随版本变化，以决策文件为准，不凭路线图注释判断。插件当前源版本是 0.14.2。"},{"title":"路线图","page":"路线图","href":"10-roadmap.html","content":"这一页用状态区分：哪些是已经落地的能力，哪些还在方向阶段、没有实施授权，哪些是已有计划、方案仍待决策。读的时候不要把方向当成现状。标成已实现的能力，背后应有对应决策文件。 已实现 业务三层边界：图内核、通用助手、目标项目各管一摊，上层调下层、下层不反向依赖。见架构原理。 契约内核与标准 Family API：内核稳定边界加上业务族统一接入，新类型靠配置接入。见方法注册表。 Registry 公共接口：身份、清单、绑定、投影与查询；助手按已锁定版本接线。 CLI 命令族：init / scan / validate / query / context / packet（含 prompt 与 audit）/ version-lock / trace-version / version-index / hooks / next-id / render / doctor / validate-review-result / generate-e2e-registry / contract / restructure。以 --help 为准。 评审结果协议：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 关系锁两类边：locks 与 artifactRelations。 方向，未授权 通用图内核与多领域规范分层：把混合的软件开发语义拆成「不加载领域默认值的通用内核 + 可独立发布的领域图规范 + 多领域通过规范组合共存」。这是长期架构待办，目前未授权实施。迁移前需要补齐正式需求、场景、设计、决策与验收；物理拆仓必须晚于兼容验证。在那之前，新增设计不得把领域类型继续写进通用内核。 这条方向如果落地，会变成一套不加载领域默认值的通用图内核、多份可独立发布的领域规范，以及一个只做初始化、诊断、规范发现与分诊的通用助手。现在它只是方向记录，不是能力。 规划中 泄漏扫描集随新的密钥前缀和内部路径形态做增量扩充。机制已落地，扩充是维护。 文档树摘要锁接到更多发布环节，让误删章节更早被发现。 快照断言覆盖更多导出形态。当前已覆盖站点 HTML、资源与 .nojekyll。 这三项是增强已落地能力，不引入新范式，也不与上面的架构方向混为一谈。 怎么读成熟度 判定口径只有一条：有没有对应决策文件背书。 已实现：决策已通过、代码已落地、本站有对应页可核对。 规划中：增强路径已写入治理计划，具体方案待决策落定。 方向，未授权：只是方向记录。迁移前必须先补齐正式需求、场景、设计、决策与验收，且不得据此大规模移动目录、改包名或拆仓。 能力是否落地，以决策文件为准，不凭本页注释判断。新能力从方向走到已实现，都会先有决策、再有代码、最后进本站。"},{"title":"已实现","page":"路线图","href":"10-roadmap.html#done","content":"业务三层边界：图内核、通用助手、目标项目各管一摊，上层调下层、下层不反向依赖。见架构原理。 契约内核与标准 Family API：内核稳定边界加上业务族统一接入，新类型靠配置接入。见方法注册表。 Registry 公共接口：身份、清单、绑定、投影与查询；助手按已锁定版本接线。 CLI 命令族：init / scan / validate / query / context / packet（含 prompt 与 audit）/ version-lock / trace-version / version-index / hooks / next-id / render / doctor / validate-review-result / generate-e2e-registry / contract / restructure。以 --help 为准。 评审结果协议：失败关闭、稳定身份、尝试次数封顶、禁止自我接受。 关系锁两类边：locks 与 artifactRelations。"},{"title":"方向，未授权","page":"路线图","href":"10-roadmap.html#direction","content":"通用图内核与多领域规范分层：把混合的软件开发语义拆成「不加载领域默认值的通用内核 + 可独立发布的领域图规范 + 多领域通过规范组合共存」。这是长期架构待办，目前未授权实施。迁移前需要补齐正式需求、场景、设计、决策与验收；物理拆仓必须晚于兼容验证。在那之前，新增设计不得把领域类型继续写进通用内核。 这条方向如果落地，会变成一套不加载领域默认值的通用图内核、多份可独立发布的领域规范，以及一个只做初始化、诊断、规范发现与分诊的通用助手。现在它只是方向记录，不是能力。"},{"title":"规划中","page":"路线图","href":"10-roadmap.html#planned","content":"泄漏扫描集随新的密钥前缀和内部路径形态做增量扩充。机制已落地，扩充是维护。 文档树摘要锁接到更多发布环节，让误删章节更早被发现。 快照断言覆盖更多导出形态。当前已覆盖站点 HTML、资源与 .nojekyll。 这三项是增强已落地能力，不引入新范式，也不与上面的架构方向混为一谈。"},{"title":"怎么读成熟度","page":"路线图","href":"10-roadmap.html#how","content":"判定口径只有一条：有没有对应决策文件背书。 已实现：决策已通过、代码已落地、本站有对应页可核对。 规划中：增强路径已写入治理计划，具体方案待决策落定。 方向，未授权：只是方向记录。迁移前必须先补齐正式需求、场景、设计、决策与验收，且不得据此大规模移动目录、改包名或拆仓。 能力是否落地，以决策文件为准，不凭本页注释判断。新能力从方向走到已实现，都会先有决策、再有代码、最后进本站。"}]</script>
 </body>
 </html>