架构原理

这套结构要把助手写出来的研发产物变成一张 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。完整命令表见命令参考。当前默认类型仍由内核提供；不加载领域默认值是长期方向，见路线图。