PactKit

PactKit 支持多种 AI 编程工具，全部通过 pip 安装——没有单独的 plugin / marketplace 通道。

方案 A：pip 安装（Claude Code、OpenCode、Codex CLI）

Claude Code 支持包含在核心包内；OpenCode 与 Codex CLI 是可选 extras，按需安装：

pip install pactkit                 # Claude Code（classic）
pip install "pactkit[opencode]"     # 追加 OpenCode
pip install "pactkit[codex]"        # 追加 Codex CLI
pip install "pactkit[all]"          # 两者兼得，另含 lint / visualize extras

前置要求

  • Python 3.10+
  • 已安装对应的 AI 编程工具（Claude Code / OpenCode / Codex CLI）

安装与部署

pip install pactkit
pactkit init

可选依赖

PactKit 提供可选依赖组以增强功能：

pip install pactkit[lint]        # 包含 ruff，用于 lint 门禁
pip install pactkit[visualize]   # 包含 tree-sitter，用于 AST 级可视化
pip install pactkit[all]         # 全部（lint + visualize + IDE 适配器）

推荐的外部工具

以下工具与 PactKit 集成但无法通过 pip 分发：

工具用途安装方式缺失时行为
ghGitHub CLI（issue 同步、发版、PR）brew install ghIssue 同步不可用
codegraph符号索引与调用链分析npm install -g codegraph回退到 grep/find

所有外部工具均优雅降级——PactKit 在没有它们的情况下仍可正常工作，但特定功能（issue 同步、代码图查询）将不可用。

v2.9.0 起，pip install pactkit 已包含所有 IDE 适配器（无需单独安装 pactkit-opencode 或 pactkit-codex）。执行 pactkit init 将同时部署全部 IDE 配置：

Claude Code（部署至 ~/.claude/）：

路径内容
CLAUDE.md总章根文件（通过 @import 引用 8 个规则模块）
rules/7 个模块化规则文件
agents/9 个 Agent 定义
commands/12 个由 Core 管理的生命周期入口
skills/19 个专用与 Portable Method Skill

OpenCode（部署至 ~/.config/opencode/）：

路径内容
AGENTS.md精简头部（规则通过 opencode.json instructions 加载）
rules/8 个规则文件（3 个核心规则始终加载（instructions）+ 6 个按需加载（@reference））
agents/9 个 Agent 定义（mode: subagent，工具以 record 格式表示）
commands/12 个由 Core 管理的生命周期入口（agent: build + 路由）
skills/19 个 Skill（带 SKILL.md frontmatter 以支持自动发现）
opencode.json全局配置（instructions，保留用户 provider 配置）

Codex CLI（部署至 ~/.codex/）：

路径内容
AGENTS.md单 Agent 文件（10KB 预算 + 截断）
skills/project-*/SKILL.md12 个 managed lifecycle command facade
config.toml用户拥有的 Codex 配置；PactKit 不重写已有文件
.pactkit-deployed.json已验证的宿主能力与部署哈希

如需仅部署单个 IDE，可使用 --format 参数：pactkit init --format opencode 或 pactkit init --format codex。

更新与升级

pip install --upgrade pactkit
pactkit update

OpenCode 与 Claude Code 的关键差异

特性Claude CodeOpenCode
规则加载CLAUDE.md 中 @import（全部 8 个规则）懒加载分层：3 个核心规则通过 instructions + 6 个按需规则通过 AGENTS.md 中 @reference
Agent 格式name:、permissionMode:、字符串工具mode: subagent，无 name，record 格式工具
Command frontmatterallowed-tools: [...]agent: build + model: provider/model-id
配置文件.claude/pactkit.yaml.opencode/pactkit.yaml
模型路由提示级别建议配置级别强制执行（通过 model: frontmatter）

懒加载规则（OpenCode）

OpenCode v2.1.1 引入了懒加载规则，每轮 token 消耗减少约 62%：

  • 核心规则（通过 opencode.json instructions 始终加载）：01-core-protocol、02-hierarchy-of-truth、09-credential-safety
  • 按需规则（通过 AGENTS.md 中 @reference 由 AI 按需加载）：03-file-atlas、04-routing-table、05-workflow-conventions、06-mcp-integration、07-shared-protocols、08-architecture-principles

AI 仅在当前任务需要时才读取按需规则（例如，仅在提交操作时才读取 05-workflow-conventions.md），避免每轮不必要的 token 开销。

模型路由

OpenCode Command 会自动路由至最合适的模型：

Command模型原因
/project-plan、/project-clarify、/project-design继承主模型深度推理任务
/project-act、/project-done、/project-check 等Sonnet实现任务
后台任务（标题、压缩）Haiku（small_model）轻量级任务

在 pactkit.yaml 中配置：

command_models:
  project-act: sonnet
  project-done: sonnet
  project-check: sonnet

其他命令

# 检查版本
pactkit version

# 预览至自定义目录
pactkit init -t /tmp/preview
pactkit init --format opencode -t /tmp/oc-preview

Codex CLI 与 Claude Code 的关键差异

特性Claude CodeCodex CLI
Agent 模式多 Agent（9 个角色）App Server thread + Core WorkUnit
Command 格式Command playbook带 SKILL.md frontmatter 的 Skill
配置格式.claude/pactkit.yaml.codex/pactkit.yaml + config.toml
品牌引用Claude 原生自动替换（Claude → Codex）
Sprint 命令原生多 Agent 编排串行 Plan → Act → Check → Done fallback
恢复能力Claude lifecycle 集成持久化 thread、跨进程 thread/resume、版本化 retry

方案 B：GitHub Copilot

Copilot 与其他适配器的工作方式不同。 它部署到项目级 .github/ 目录，而非用户级 ~/ 路径。每个新项目都需要单独执行 pactkit init --format copilot。

pip install pactkit pactkit-copilot
cd your-project
pactkit init --format copilot

然后在支持 Copilot 的 IDE 中打开项目，执行 /project-init。

路径内容
.github/skills/19 个 Skill（带 SKILL.md frontmatter）
.github/agents/9 个 Agent 定义（独立 .md 文件）
.github/prompts/12 个斜杠命令（.prompt.md 文件）
.github/copilot-instructions.md项目级指令

与其他 IDE 的关键差异：

特性Claude Code / OpenCode / CodexCopilot
部署目标用户级（~/）项目级（.github/）
配置频率一次即可每个项目都需要
规则加载@import / @reference / 内联仅内联（不支持 @include）
安装包pactkit（已内置）pactkit + pactkit-copilot
Sprint 命令原生或串行 fallback串行 fallback

完整指南请参阅 GitHub Copilot。

方案 C：Trae（即将推出）

Trae 适配正在积极开发中。

Trae 支持计划在未来版本中推出。适配器将遵循与 OpenCode 和 Codex 相同的薄适配器模式——安装 pactkit-trae 并执行 pactkit init --format trae。敬请关注后续更新。

项目初始化

通过任意方式安装 PactKit 后，对每个工作项目执行初始化：

/project-init

这将创建治理结构（docs/specs/、docs/product/sprint_board.md、docs/architecture/graphs/ 等）以及适合当前环境的项目指令：

  • Claude Code：.claude/CLAUDE.md，包含架构概览、开发命令和 @ 引用
  • OpenCode：./AGENTS.md + opencode.json，包含 permission、mcp 模板和 instructions
  • Codex CLI：.codex/AGENTS.md + config.toml，包含沙箱和 Hooks 配置
  • Copilot：.github/copilot-instructions.md + agents/prompts/skills（需先执行 pactkit init --format copilot）

忘记初始化了？ 没关系——/project-plan 和 /project-doctor 会自动检测未初始化的项目并为你处理。

多开发者协作

对于团队，在 pactkit.yaml 中设置 developer 字段以避免 Story ID 冲突：

developer: alice

Story ID 将变为 STORY-alice-001，当多名开发者在各自分支上工作时可防止合并冲突。详见配置。

P.A.C.T. — 治理哲学

人类与 AI 智能体之间的治理契约：CODE 即法则，Data 即真相，Prompt 只是指令，AI 只做创造。

示例

常用场景与逐步操作演练

目录

方案 A：pip 安装（Claude Code、OpenCode、Codex CLI）前置要求安装与部署可选依赖推荐的外部工具更新与升级OpenCode 与 Claude Code 的关键差异懒加载规则（OpenCode）模型路由其他命令Codex CLI 与 Claude Code 的关键差异方案 B：GitHub Copilot方案 C：Trae（即将推出）项目初始化多开发者协作