PACT — AI Agent 业务系统交付控制平台

⚠️ 本项目已归档（Archived），不再维护
自 2026-08-12 起，本仓库停止维护：不再接受 issue 与 PR，不再发布新版本。
接替项目：https://github.com/vima-tech/vima-cli
已安装 @vima-tech/pact 的用户可继续使用现有版本，但不会再收到更新与修复；新项目请直接使用接替项目。本仓库保留只读，作为历史存档。

PACT — AI Agent 业务系统交付控制平台

PACT = Product · Architecture · Contracts · Tests

PACT 的终极目标是让 Claude Code、Codex 等 AI Agent 在一套可检查、可追溯、可恢复的控制协议下，快速把真实需求落地为规范、准确实现、真正可用、稳定可演进的业务操作系统。Agent 负责推理与编码，PACT 负责规格、契约、变更和完成证据。

交付不用一个含混的“100%”表示，而是逐级通过 implemented、buildable、startable、integrated、business-closed-loop、accepted、deployable、stable。

一套 agent skills：把 PRD / SDD / SPEC / 验收标准 / 施工范围熔成一份单文件完备规格 PACT.md，并驱动它落地。用于新建项目开局与大需求设计。

它的验收标准只有一条，且必须被真实检验：

一个对本项目一无所知的人或 AI，只读这一份文件即可开始编码，且不需要追问背景、不需要猜测意图、不会遗漏约束。

PACT Platform：统一治理，独立交付

本仓库现同时承载三类工程创建工具，但不把它们合成一个包：

pact/ 与 pact-*：通用规格、执行图谱和验收闭环，始终不依赖 Vima；
products/vima-ui-admin/：独立的 @vima-tech/ui-admin npm 包；
templates/vima-starter/：独立的 create-vima-starter 全栈脚手架；
platform/：能力、限制、兼容矩阵、选择规则和三单元发布编排。

Agent 必须先把需求归类为 generic、admin-ui 或 business-system。Vima 是可选能力；只有 business-system 才会看到 Starter adapter 候选。当前 Starter 产品为 partial，全栈 adapter 为 blocked，因为业务权限、生产安全、后端测试和 FullStackSpec adapter 尚未达标，平台不会把现有空壳能力描述成“可稳定生成完整业务系统”。

npm run governance:check
printf'%s\n''{"version":"1","kind":"business-system"}'| npm run platform:inspect
npm run release:plan -- --base HEAD^
npm run verify
npm run release:pack # 仅写 artifacts/release，不发布、不 push

PACT 仓库内的 products/vima-ui-admin 与 templates/vima-starter 是唯一工程入口；旧的两个 /home/renmk/projects/vima-* 别名已退役。导入来源、保留备份、规范化哈希和 finalized 时间记录在 platform/registry/provenance.v1.json；.pre-pact-20260811 快照不随别名删除。

八个工作命令

命令	干什么	停止条件
`/pact-new`	创建 pact 物料包（新项目 / 大需求 / 多文档熔合通吃）：访谈 → 写四层 → 完备门 → 冻结 → 生成知识库 + 执行图谱	物料齐备且机检 + 冷读门全过
`/pact-run`	按物料施工：执行图谱取活 → 实现（`@pact` 标注）→ 自动验收 → 回写状态	`pact-review.sh` exit 0（完成度 100%）
`/pact-review`	审查实现完成度：五道机检聚合 + 抽查，出完成度与缺口清单；也是 `/pact-run` 的停止判据	单次，只读
`/pact-check`	体检物料质量：机检 + 物料反扫 + 零知识冷读门，出问题与遗漏清单	单次，只读
`/pact-change`	需求变更入口（S10-CR）：回 P5 立 R-ID → 补验收 → 改契约 → changelog → 同步图谱 → 判断重跑冷读门	六步走完 + 影响面报告
`/pact-list`	项目内全部物料总览：状态 / 工序进度 / 完成度 + 下一步建议	单次，只读
`/pact-estimate`	估算门：四前提核对 + 驱动因子分层测算 + 三条线（对外只承诺交付线）	单次
`/pact-install`	完整安装后的诊断、Agent Skills 修复与未来 Adapter 扩展入口	`pact doctor` ready 或明确冲突

/pact 本身只做总览与路由：打印速览，按现场状态告诉你该用哪个命令。除 /pact-new、/pact-list 外的命令不给路径时自动扫描 .pact/：恰一份物料直接用；多份列出让你选。旧版布局（根 PACT.md + 扁平 .pact/）用 pact/scripts/pact-migrate.sh . --slug=<名字> 一键迁移。

物料结构：一个大需求 = 一个物料包

<你的项目>/
CLAUDE.md # 怎么写代码（全项目一份）
.pact/
user-auth/ # 第一个 pact（如初建项目）
export-center/ # 第二个 pact（后来的大需求）——并存互不干扰
00_START_HERE.md # ★ 物料目录入口：先读哪份 / 冲突听谁的 / 按角色从哪动手
PACT.md # 【真源】单文件完备规格（四层 P/A/C/T，30 锚点）
board.md # 工序状态表 + 冻结门计分（断点续跑第一真相源）
open-questions.md # ★ 待确认台账：问题 / 卡住谁 / 临时策略
action-graph.json # ★ AI 执行图谱：module→feature→step DAG + 每步实现/测试状态（step 可带 pitfalls 已知坑）
source-of-truth.yaml # 权威源哈希锁 + excluded_from_agent_context（哪些目录不许读）
interview.md source-merge.md assessment.md estimate.md # 闸门记录
cold-read.md changelog.md # 执行态
figures/ # 图源：流程图/结构图的 SVG（agent 绘制，hash 锁定到真源图块）
pact-book/ # 【生成物】（勿手改）
pact-book.html # 给人：正式交付规格书，双击即开、零依赖、可打印，直接发甲方
src/**.md # 给 AI：每条需求一页的施工素材

人读 HTML，AI 读 md：pact-book.html 是可正式对外交付的网页版规格书——hero 封面、目录卡片、四大部分（产品需求↔PRD、系统设计↔SDD、数据与接口规格↔SPEC、验收与交付）+ R-ID 需求索引附录；网页优先：sticky 顶栏与阅读进度、粘性表头、R-ID 悬停预览、明暗主题；真源里的流程图/结构图由 agent 绘制成 SVG 内嵌（figures/，hash 锁定，图块变了没重绘会被 --check 抓漂移）；禁用 JS 也完整可读，Ctrl+P 仍可打印成册； src/r/R###.md 每条需求聚合需求+验收+依赖+决策+契约位置，施工读一页即可。
R-ID 号段全项目唯一：新物料从既有最大号 +1 起，跨物料才能机检野生功能。

执行图谱：AI 施工的依据（DAG）

/pact-new 冻结时生成 action-graph.json：

三级节点：module（功能模块，源自 A2）→ feature（功能点，挂 R-ID 簇）→ step（可执行步骤，引用 C 层契约锚点）；
deps 是跨节点执行依赖（DAG、机检禁环）；施工按「依赖已满足的下一批」取活；
每个 step 携带 impl（todo/doing/done/blocked + file:line 证据）与 test（todo/pass/fail/na + 测试命令或理由）——执行态的唯一真源，取代旧版 coverage.md；
/pact-run 按它干活，/pact-review 按它算完成度，pact-trace.sh 拿它与代码标注对账。

bash pact/scripts/pact-graph.sh .pact/<slug># 进度树 + 完成度
bash pact/scripts/pact-graph.sh .pact/<slug> --next # 下一批可执行步骤
bash pact/scripts/pact-graph.sh .pact/<slug> --require-complete # 收尾门禁

落地是机检的：代码必须能反查回规格

每段业务代码必须带 R-ID 标注：

// @pact R001 单个// @pact R001,R002 一段代码覆盖多个
# @pactR014Python/Shell<!-- @pactR021-->模板/HTML

机检矩阵（自称完成不算数）：

脚本	回答的问题	抓什么
`pact-status.sh`	工序走到哪了	跳步、静默略过、冻结不一致
`pact-lint.sh`	PACT 写够了没有	锚点缺失、占位符、R-ID 无验收、决策无「已否决」
`pact-graph.mjs`	图谱能不能施工、做到哪了	结构非法、DAG 成环、R-ID 无 step 承接、done 无证据
`pact-trace.sh`	代码真按 PACT 做了没有	虚报（图谱说完成、代码没有）、野生功能（代码有、规格没有）
`pact-book.sh --check`	知识库还是不是真源的投影	手改生成物、忘了重生成
`star-consistency.sh`	★ 强制项 P5↔T1 一致吗	漏标、越权升级
`pact-check.sh`	物料本身完备吗（聚合器，/pact-check 入口）	上面前几项 + 冻结态产物齐备
`pact-review.sh`	全部实现了吗（聚合器，/pact-review 入口）	五道门全过 + 完成度 100% 才 exit 0
`pact-list.sh`	项目里有哪些 pact、各自到哪了（/pact-list 入口）	只读总览，不做门禁
`pact-migrate.sh`	旧版布局一键迁移	移动 + 旧路径引用清单（改引用与验证留给人/agent）

三个让它区别于「文档模板」的机制

完备性是机检的：30 个锚点  + pact-lint.sh 九项检查。
零知识冷读门：另起一个全新 agent，只给 PACT.md，让它输出实现计划 + 必须追问的问题清单—— 每问一个问题就是一处规格漏洞，跑到追问清单为空为止。
决策必须留「已否决方案」：理由要能被反驳，后人看到的是路口而不只是结果。

内建估算门（S7）：驱动因子分层法（T1/T2/T3 + 费率卡）、50% 法则、阻塞缓冲 ×1.5–2、三条线只承诺交付线——禁止凭直觉给工期或报价数字。

仓库目录

pact/ 核心 skill：/pact 总览路由 + 共享资源
SKILL.md 协议：物料结构 · 机检 · 十四条禁令 · 估算门
references/ 工序卡(agent-protocol) · 速览(help) · 写作标准 · 范例 · 估算方法
templates/ PACT.md 30 锚点骨架 · action-graph.json · board 等各工序模板
scripts/ 全部机检与生成脚本（见上表）
vendor/ marked.min.js（构建期 markdown 渲染器，产物不内嵌）
pact-new/SKILL.md /pact-new 创建物料包（S0–S9）
pact-run/SKILL.md /pact-run 按物料施工（S10–S11，100% 才停）
pact-review/SKILL.md /pact-review 完成度审查（只读）
pact-check/SKILL.md /pact-check 物料体检（只读）
pact-change/SKILL.md /pact-change 需求变更入口（S10-CR）
pact-list/SKILL.md /pact-list 多物料总览（只读）
pact-estimate/SKILL.md /pact-estimate 估算门独立入口
pact-install/SKILL.md /pact-install 安装诊断与修复入口

安装与上手

主推完整安装：

npm i -g @vima-tech/pact
pact doctor
cd your-project
# 然后对 agent 说：# /pact-new 做一个 <你的需求># /pact-run （物料冻结后）# /pact-review （做完了吗）# /pact-check （规格写够了吗）# /pact-change 导出要支持 Excel （冻结后改需求）# /pact-list （项目里有哪些 pact）# /pact-estimate （多久能做完 / 报个价）# /pact-install （检查/修复安装）

完整安装会提供 pact/vima-pact CLI，并从同版本 npm 包自动向已检测 Agent 注册九个 Skills。另有两个入口：

npx skills add vima-tech/pact -g # 轻量：只全量安装 Skills，不选模块# 或让 Agent 按 docs/installation.md 执行完整安装并运行 pact doctor

完整说明见 docs/installation.md。

手动跑一次机检看看它管什么：

S=~/.claude/skills/pact
bash $S/scripts/pact-lint.sh $S/references/example-PACT.md --level=feature # → PASS
bash $S/scripts/pact-lint.sh $S/templates/PACT.md --level=full # → FAIL（空模板，预期）# 在你的项目里（有物料后）：
bash $S/scripts/pact-check.sh .pact/<slug># 物料质量
bash $S/scripts/pact-review.sh .pact/<slug># 完成度（100% 才 exit 0）

中断后怎么接着干：物料没冻结说 /pact-new 继续，冻结了说 /pact-run。 agent 会先读 board.md 与执行图谱判断进度，不重新访谈、不重写已冻结的规格。

更新已安装的 pact

先确认自己是哪种安装形态（看 skill 目录是不是软链）：

ls -la ~/.claude/skills/ | grep pact

形态 A · npm 完整安装（主推）：

npm i -g @vima-tech/pact@latest
pact doctor

形态 B · Skills 拷贝式安装（npx skills add 装的）——更新要重新拉取：

npx skills update pact
# 或重装：npx skills add vima-tech/pact -g

形态 C · 源码软链安装（目录是指向本仓库 clone 的软链）——更新只需拉代码，链接自动跟随：

cd<你的 pact 仓库 clone>&& git pull

首次做软链安装（clone 仓库后把九个 skill 链进 agent 的 skills 目录）：

REPO=<你的 pact 仓库 clone 的绝对路径>fornin pact pact-new pact-run pact-review pact-check pact-change pact-list pact-estimate pact-install;do
ln -sfn "$REPO/$n"~/.claude/skills/$ndone

从形态 A 切到形态 B 时，先把旧拷贝目录移出 skills 目录再建链—— 旧拷贝里的 SKILL.md 会与新版重名，被 agent 当成同名 skill 重复发现。

更新后验证（任一形态）：

S=~/.claude/skills/pact
bash $S/scripts/pact-help.sh >/dev/null &&echo ok # 脚本可跑
head -5 $S/../pact-new/SKILL.md # 命令 skill 在位

兼容性

SKILL.md 遵循 agent skills 规范，可安装到 Claude Code、Cursor、Codex、Copilot 等支持 skills 的 agent。 bash 脚本零依赖；pact-graph / pact-book / pact-estimate 需 node。

更新记录

见 CHANGELOG.md。

License

MIT

Navigation Menu

Uh oh!

Repository files navigation

⚠️ 本项目已归档（Archived），不再维护

PACT — AI Agent 业务系统交付控制平台

PACT Platform：统一治理，独立交付

八个工作命令

物料结构：一个大需求 = 一个物料包

执行图谱：AI 施工的依据（DAG）

落地是机检的：代码必须能反查回规格

三个让它区别于「文档模板」的机制

仓库目录

安装与上手

更新已安装的 pact

兼容性

更新记录

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.pact/pact-platform-unification		.pact/pact-platform-unification
bin		bin
docs		docs
pact-change		pact-change
pact-check		pact-check
pact-estimate		pact-estimate
pact-install		pact-install
pact-list		pact-list
pact-new		pact-new
pact-review		pact-review
pact-run		pact-run
pact		pact
platform		platform
products/vima-ui-admin		products/vima-ui-admin
templates/vima-starter		templates/vima-starter
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
README.md		README.md
install-manifest.json		install-manifest.json
package-lock.json		package-lock.json
package.json		package.json

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

⚠️ 本项目已归档（Archived），不再维护

PACT — AI Agent 业务系统交付控制平台

PACT Platform：统一治理，独立交付

八个工作命令

物料结构：一个大需求 = 一个物料包

执行图谱：AI 施工的依据（DAG）

落地是机检的：代码必须能反查回规格

三个让它区别于「文档模板」的机制

仓库目录

安装与上手

更新已安装的 pact

兼容性

更新记录

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages