安装 — PactKit Docs

PactKit 支持多种 AI 编程工具和安装方式。

方案 A：Claude Code Plugin（推荐 Claude Code 用户）

最简单的 Claude Code 安装方式，无需 Python。

# 在 Claude Code 中：
/plugin marketplace add pactkit/claude-code-plugin
/plugin install pactkit

重启 Claude Code，全部 9 个 Agent、11 个 Command、10 个 Skill 和 8 个 Rule 即刻可用。


更新	通过 Marketplace 自动更新，或执行 `/plugin update pactkit`
卸载	`/plugin uninstall pactkit`
隔离性	Plugin 独立存放于自己的缓存目录，与 `~/.claude/` 分离
团队共享	添加至 `.claude/settings.json`，队友将收到安装提示

Plugin 会部署所有组件。如需选择性部署（例如禁用特定 Agent 或 Command），请使用 pip 安装方式并配置 pactkit.yaml。

团队共享

将以下内容添加到项目的 .claude/settings.json，以便自动提示队友安装：

{
  "extraKnownMarketplaces": {
    "pactkit": {
      "source": { "source": "github", "repo": "pactkit/claude-code-plugin" }
    }
  },
  "enabledPlugins": {
    "pactkit@pactkit": true
  }
}

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

适合希望通过 pactkit.yaml 进行精细控制的用户，支持 Claude Code、OpenCode 和 Codex CLI。

前置要求

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

安装与部署

pip install pactkit
pactkit init

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/`	11 个 Command 剧本
`skills/`	10 个 Skill（3 个脚本型 + 7 个纯提示型）

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

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

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

路径	内容
`AGENTS.md`	单 Agent 文件（10KB 预算 + 截断）
`prompts/`	带前置条件注入的剧本式命令文件
`config.toml`	Codex 配置（MCP、沙箱、Hooks）

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

更新与升级

pip install --upgrade pactkit
pactkit update

OpenCode 与 Claude Code 的关键差异

特性	Claude Code	OpenCode
规则加载	CLAUDE.md 中 `@import`（全部 8 个规则）	懒加载分层：3 个核心规则通过 `instructions` + 6 个按需规则通过 AGENTS.md 中 `@reference`
Agent 格式	`name:`、`permissionMode:`、字符串工具	`mode: subagent`，无 `name`，record 格式工具
Command frontmatter	`allowed-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 Code	Codex CLI
Agent 模式	多 Agent（9 个角色）	单 Agent（`AGENTS.md`）
Command 格式	Skill（`SKILL.md` frontmatter）	Playbook（描述性 frontmatter）
配置格式	`.claude/pactkit.yaml`	`.codex/pactkit.yaml` + `config.toml`
品牌引用	Claude 原生	自动替换（Claude → Codex）
Sprint 命令	完整多 Agent 编排	不可用（单 Agent 限制）

方案 C：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/`	10 个 Skill（带 `SKILL.md` frontmatter）
`.github/agents/`	9 个 Agent 定义（独立 `.md` 文件）
`.github/prompts/`	10 个斜杠命令（`.prompt.md` 文件）
`.github/copilot-instructions.md`	项目级指令

与其他 IDE 的关键差异：

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

完整指南请参阅 GitHub Copilot。

方案 D：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，当多名开发者在各自分支上工作时可防止合并冲突。详见配置。