场景剧本

场景一 · 第一次把项目接进来 #

新项目首次接入时，仅执行只读体检，经授权后方可启用 artifact-chain-bootstrap。依据真实 Graph 公开清单及项目当前形态与阶段，选择实际采用的制品类型。此过程不仅建立配置，还需选定项目本地模板、检查清单及 workflow profile/方法绑定，同步创建必要目录结构、来源声明与采用说明。候选类型不会自动启用；若已有配置，则仅做最小补丁更新并保留本地定制，禁止重新初始化。是否安装 hook 由项目授权决定，不默认启用。

初始化时助手读取已解析 Graph 包里的公开清单，入口是 artifact-graph/project-artifact-profiles，不另存清单。共同最小三项 feature、scenario、design 会出现在候选里；形态为 skill-plugin 时再加标准项 agent_skill、e2e_test。阶段项和能力项不会自动启用。项目配置拥有采用权，已有追加类型保留。尚未采用的标准项记在 missing_standard_types，与 gaps 中的配置、类型登记、目录、模板和方法缺口分开。公开清单读不到或 schema_version 不是 1.0 时，只暂停依赖清单的推荐，不回退复制表。遇到清单读取或兼容问题，先按安装说明核对精确的 Graph 版本 artifact-graph@1.2.0，再继续依赖清单的推荐。

请先使用 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 <edgeId>

--remove-orphan-edge 与 --remove-orphans 互斥；被点名的边仍是活边时拒绝删除，同一锁文件 里的既有孤儿也不会被连带清理。只给"分析并生成迁移计划"的授权时，不要执行 apply。

场景七 · 从材料缺口收敛 SPEC #

要把需求、场景与设计中的变更交给实现者时，使用 spec-author。提供本轮原始要求、相关场景及项目现有模板；入口先核实类型、路径、编号、关系和方法绑定能否表达需求，再分别核对范围依据、正文充分性、必要关系及适用评审。定义缺口通过已有 artifact-chain-bootstrap 打补丁；正文或评审缺口须沿已有制作与评审入口补全，补全前不得命名或交付本轮规格。

例如一项导出变更由提交和结果交付两个职责共同完成，根规格须明确本轮全部增量、保留要求、共同边界及所有验收项。详细合同仍由原始需求、场景与设计维护，未变更部分保持引用不变。提交与交付两个职责都能读取完整必要合同；提交任务无需加载交付域的内部实现或历史，仅依赖已声明契约与边界。

短小单职责规格保持为单文件，多个领域夹带大量无关材料时，才按完整业务能力和公共接口拆分。拆分不按固定字数进行。多职责或跨会话任务交付时，须创建独立启动单（说明目标和首项工作的启动文档）、唯一公共计划与各职责任务文件。

作者须逐段核实前置条件，顺序生成规格与执行输入；主会话启动须掌握全部目标与共同边界；实现者读取时，应包含其完整任务、公共接口与相关实现。独立审阅者须从原始要求出发，查找遗漏，分段读完全部必要正文，再集中核对接口、异常、兼容性及验收归属；未读部分不得报通过。

未提交来源须以工作树基线与已核验快照标明版本。沿主会话启动、代表性实现、作者与独立审阅四类路径继续展开必读引用，检查简短索引是否仍带入无关全文。分次读取仍会累积上下文，接续时保留授权、共同边界与来源版本；正文变化须复核，若继承了全部历史，须如实说明限制。

必要附件缺失、用户限定为单文件但宿主无法可靠局部读取、或一个完整合同仍超处理能力时，必须指出具体缺口与受影响任务，不得靠摘要或截断报完成。无实际测量依据，不承诺词元用量、速度或指令遵循改善。

采用 artifact.spec@1 时，从实际使用的 Graph 包调用 contract explain 获取真实 identity、revisionDigest 与 semanticMarkers。确认必需标记包含 changes、scope、acceptance，再以该摘要调用 contract validate-markers。保留 acceptance-record 与 archive-record 生命周期记录。此检查仅覆盖根文件标记，不验证附件是否存在或全文语义；仍须不同职责方完成完整独立审阅。check-workflow-profile 的 OK 仅说明方法可解析，不代替真实正文与评审。

请使用 spec-author 核对本轮必要制品、关系和评审。前置完成后，按职责组织规格与执行输入；短规格保持单文件，长规格保留完整根入口与唯一领域正文。沿实际必读引用核对读取范围，并完成根文件标记检查及独立全文审阅。

出口 #

• 接新项目：setup 体检，授权后 bootstrap；或 CLI init + doctor。
• 加制品类型：改配置 paths / idPatterns，再 refresh + validate。
• 卡提交：hooks install-git --hook all。
• 接助手：按 INSTALL.md 安装插件，用 help / setup 起步，用 context 取上下文。
• 编写 SPEC：用 spec-author 补齐必要材料与评审，交付规格和执行输入，并完成标记检查及独立正文审阅。
• 重组制品：restructure inspect → 语义映射 + 独立复审 → plan → 确认后 apply， 再用 --remove-orphan-edge 收尾本次产生的孤儿锁。