场景剧本

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

新仓库还没有制品链配置。先做只读体检，再经授权走 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 <edgeId>

--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 收尾本次产生的孤儿锁。