命令参考
下面的清单以 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 <code> --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 <edgeId>，可重复指定，且与
--remove-orphans 互斥（混用即拒绝）。被点名的边仍是活边时拒绝删除。同一锁文件里的
既有孤儿不会被连带清理。
contract #
| 子命令 | 作用 | 典型调用 |
|---|---|---|
list | 列出已注册契约 | artifact-graph contract list --format json |
explain | 解释某个契约 | artifact-graph contract explain --contract <major-id> |
validate | 用契约校验数据 | artifact-graph contract validate --contract <major-id> --data '{}' |
normalize | 规范化数据 | artifact-graph contract normalize --contract <major-id> --data '{}' |
check-policy | 检查策略 | artifact-graph contract check-policy --contract <major-id> --policy '{}' |
validate-markers | 校验 Markdown 里的契约标记 | artifact-graph contract validate-markers --contract <major-id> --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 带着走，不必硬记全部命令。