配置 — PactKit Docs

本页面涵盖 pip install 部署方式。如果您通过 Claude Code Plugin 安装，所有组件会自动部署，不使用 pactkit.yaml。

pactkit.yaml

pactkit.yaml 文件控制部署哪些组件以及它们的行为方式。

位置: PactKit 根据环境自动检测配置文件：

环境	配置路径
Claude Code	`.claude/pactkit.yaml`
OpenCode	`.opencode/pactkit.yaml`

两个路径都会自动检查——无需手动配置。

参考

字段	类型	默认值	描述
`stack`	string	自动检测	项目技术栈（`python`, `node`, `go`, `java`）
`version`	string	当前版本	生成配置的 PactKit 版本
`developer`	string	`""`	Story ID 的开发者前缀
`agents`	list	全部 9 个	要部署的 Agent 定义
`commands`	list	全部 11 个	要部署的命令剧本
`skills`	list	全部 10 个	要部署的 Skill
`rules`	list	全部 8 个	要部署的规则模块
`ci`	object	`provider: none`	CI/CD 流水线生成
`issue_tracker`	object	`provider: none`	外部问题追踪
`hooks`	object	禁用	可选 hook 模板
`lint_blocking`	bool	`false`	lint 失败是否阻止提交
`auto_fix`	bool	`false`	是否自动修复 lint 错误
`e2e`	object	`type: none`	E2E 测试策略配置
`venv`	object	`auto_detect: true`	虚拟环境检测
`release`	object	`github_release: true`	发布自动化行为
`regression`	object	`strategy: impact`	基于影响的测试选择
`check`	object	见下文	QA 验证行为
`done`	object	见下文	提交和经验质量行为
`agent_models`	object	`{}`	每 Agent 模型覆盖
`command_models`	object	默认值	每命令模型覆盖（OpenCode）

所有条件功能（CI/CD、问题追踪、hooks、lint 阻塞）默认关闭，只有在明确配置后才会激活。

多开发者协作

设置 developer 以避免团队成员间的 Story ID 冲突：

developer: alice

Story ID 变为 STORY-alice-001、STORY-alice-002 等。每个开发者拥有自己的 ID 命名空间。

模型路由

配置每个 Agent 或命令使用的模型：

agent_models:
  code-explorer: haiku     # 快速探索
  system-architect: opus   # 深度分析
  senior-developer: sonnet # 实现

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

模型简称（sonnet、opus、haiku）会自动解析为正确的 provider 格式。

E2E 测试

在 /project-check Phase 4 中配置端到端测试策略：

e2e:
  type: none        # none | cli | frontend | backend | fullstack
  blocking: false   # E2E 失败是否阻止 /project-done
  test_dir: tests/e2e
  env_file: .env.test
  # api_spec: docs/api/openapi.yaml  # frontend/backend 的 OpenAPI 规范路径
  compose_file: docker-compose.test.yml  # fullstack 的 Docker Compose 文件

E2E 类型

类型	描述	工具
`none`	跳过 E2E（默认）	—
`cli`	通过 subprocess 测试 CLI 工具	pytest + subprocess
`frontend`	使用 API mock 的浏览器测试	Playwright + MSW
`backend`	使用测试数据库的 API 测试	pytest + httpx
`fullstack`	使用 docker-compose 的全栈测试	docker-compose + Playwright

配置字段

字段	类型	默认值	描述
`e2e.type`	string	`none`	使用的 E2E 策略
`e2e.blocking`	bool	`false`	若为 `true`，E2E 失败阻止 `/project-done`
`e2e.test_dir`	string	`tests/e2e`	E2E 测试文件目录
`e2e.env_file`	string	`.env.test`	测试凭证文件（API 令牌、数据库连接串）
`e2e.api_spec`	string	`""`	OpenAPI/Swagger 规范路径（用于 frontend/backend 类型）
`e2e.compose_file`	string	`docker-compose.test.yml`	Docker Compose 文件（用于 fullstack 类型）

E2E 是可选功能——设置 type: none（默认）则跳过。启用后，测试将在 /project-check Phase 4 中基于 Story 的验收标准生成。

示例：CLI 项目

对于像 PactKit 这样的 CLI 工具：

e2e:
  type: cli
  test_dir: tests/e2e/cli

测试通过 pytest 运行，使用 subprocess 调用 CLI 命令。

示例：Web 应用

对于全栈 Web 应用：

e2e:
  type: fullstack
  blocking: true
  env_file: .env.test

通过 docker-compose 启动技术栈，针对真实服务运行 Playwright 测试。

语言配置

PactKit 自动检测项目技术栈并配置相应工具：

技术栈	测试运行器	Lint 命令
`python`	`pytest tests/`	`ruff check src/ tests/`
`node`	`npx jest`	`npx eslint .`
`go`	`go test ./...`	`golangci-lint run`
`java`	`mvn test`	`mvn checkstyle:check`

更新

pactkit update    # 重新部署全部 IDE 配置（Claude Code + OpenCode + Codex CLI）

可随时安全重新运行。重新部署所有托管文件，同时保留您的自定义配置。如需仅更新单个 IDE，可使用 --format 参数：

pactkit upgrade --format opencode  # 仅 OpenCode
pactkit upgrade --format codex     # 仅 Codex CLI

预览

预览部署而不修改生产目录：

pactkit init -t /tmp/preview
pactkit init --format opencode -t /tmp/oc-preview