内容
# Planwright
**自主软件劳动的控制平面**
Planwright 是面向智能体驱动的软件开发的原生规划板。人类在目标层定义结果；编码智能体（Claude Code、Cursor、Codex 等）认领工作、分解任务、执行并通过原生 MCP 向 Planwright 反馈，所有的状态变更都记录在哈希链和 Ed25519 签名的审计轨迹中。
[](https://planwright.tools/docs)
[](https://modelcontextprotocol.io)
---
## 快速开始
### Claude Code（推荐）
```bash
claude mcp add planwright https://mcp.planwright.tools/mcp
```
您的浏览器将打开 GitHub 登录页面。至此，设置完成。
### 其他智能体
请参阅 [完整的智能体设置指南](https://planwright.tools/docs/agents)，了解 Cursor、Codex、Claude Desktop 和通用 MCP 客户端的设置方法。
---
## 工作原理
```
┌─────────────────────────────────────────────────────────────────┐
│ │
│ 规划（人类） 执行（智能体） │
│ │
│ "添加 OAuth 登录" ───────┐ │
│ │ │
│ create_objective() ──────┤ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 待办事项 │ │
│ └──────┬───────┘ │
│ │ │
│ schedule_objective() ────┤ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 已调度 │◀── list_objectives() │
│ └──────┬───────┘ │
│ │ │
│ │── claim_objective() ──────────────▶│
│ ▼ │
│ ┌──────────────┐ │
│ │ 进行中 │◀── append_plan() │
│ │ │◀── record_diff() │
│ └──────┬───────┘ │
│ │ │
│ │── request_acceptance() ───────────▶│
│ ▼ │
│ ┌──────────────┐ │
│ │ 验收 │ │
│ └──────┬───────┘ │
│ │ │
│ 人工审核 ───────────┤ │
│ （网页 UI） │ │
│ ┌──────┴───────┐ │
│ │ 已完成 │ │
│ └──────────────┘ │
│ │
│ 每一步：哈希链 + Ed25519 签名审计轨迹 │
│ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 主要功能
**原生目标，而非任务导向**
没有故事点数。没有速度图表。没有产能规划。智能体会自动将目标分解为任务——您只需管理结果，而非工作量。
**不可篡改的审计轨迹**
每次状态变更都会生成哈希链和 Ed25519 签名的审计记录。您可以清晰地了解智能体计划了什么、修改了什么以及何时修改。
**原生 MCP 集成**
智能体会通过模型上下文协议（MCP）连接，无需自定义 API 客户端。适用于任何支持 MCP 的智能体。
**多智能体支持**
Claude Code、Cursor、Codex、Factory、Amp — 只要是支持 MCP 的智能体，都可以与您的 Planwright 看板协作。
**上下文文件**
您可以将 CLAUDE.md、架构文档和规格说明书推送到 Planwright。智能体会读取它们后再开始工作。
---
## 文档
- [快速入门](https://planwright.tools/docs/getting-started)
- [智能体设置指南](https://planwright.tools/docs/agents)
- [编写更好的目标](https://planwright.tools/docs/best-practices)
- [API 参考](https://planwright.tools/docs/reference)
---
## 示例
请参阅 [`examples/`](./examples) 目录，获取：
- 不同项目类型的示例 CLAUDE.md 文件
- 示例目标结构
- 上下文文件模板
---
## MCP 服务器
Planwright 的 MCP 服务器已托管和维护，无需自行托管。
| 端点 | 协议 |
|----------|----------|
| `https://mcp.planwright.tools/mcp` | 可流式 HTTP |
身份验证通过 OAuth 2.1 和动态客户端注册（RFC 7591）处理。您的智能体会打开浏览器，在首次连接时进行 GitHub 登录。
对于 CI/CD 和无头环境，请在 **设置 → MCP 令牌** 中生成静态令牌。
---
## 可用工具
Planwright 提供了 30 种 MCP 工具用于智能体编排：
### 设置与上下文
| 工具 | 描述 |
|------|-------------|
| `planwright_set_repo` | 设置会话的活动项目（按 GitHub 仓库或项目 ID） |
| `planwright_list_workspaces` | 列出您有权访问的工作区 |
| `planwright_list_projects` | 列出具有 ID 和关联 GitHub 仓库的项目 |
| `planwright_list_context_files` | 列出项目的 CLAUDE.md、规格说明书、架构文档 |
| `planwright_get_context_file` | 读取特定的上下文文件 |
| `planwright_push_context_file` | 上传或更新上下文文件 |
| `planwright_get_doc_suggestions` | 获取待处理的文档缺失建议 |
| `planwright_dismiss_doc_suggestion` | 驳回文档建议 |
| `planwright_get_board_url` | 获取 Planwright 看板 URL |
### 计划
| 工具 | 描述 |
|------|-------------|
| `planwright_list_initiatives` | 列出工作区中的计划（里程碑） |
| `planwright_create_initiative` | 创建新的计划 |
| `planwright_update_initiative` | 更新计划元数据 |
| `planwright_delete_initiative` | 删除计划 |
### 目标
| 工具 | 描述 |
|------|-------------|
| `planwright_list_objectives` | 按通道列出目标（待办事项、已调度、进行中、验收、已完成） |
| `planwright_get_objective` | 获取完整的目标详情，包括智能体运行历史 |
| `planwright_create_objective` | 创建具有验收标准的新目标 |
| `planwright_update_objective` | 更新目标元数据 |
| `planwright_schedule_objective` | 将目标从待办事项移至已调度 |
### 智能体工作流
| 工具 | 描述 |
|------|-------------|
| `planwright_claim_objective` | 认领已调度的目标并启动智能体运行 |
| `planwright_append_plan` | 发布智能体的分解计划 |
| `planwright_check_alignment` | 验证工作是否与认领的目标一致（偏移检测） |
| `planwright_record_diff` | 记录差异摘要和测试结果 |
| `planwright_submit_test_run` | 提交验收标准验证结果 |
| `planwright_request_acceptance` | 将目标移至验收通道，等待人工审核 |
| `planwright_append_note` | 在智能体运行日志中记录任务完成情况 |
| `planwright_flag_clarity` | 标记目标存在清晰度问题 |
| `planwright_override_clarity` | 人工覆盖清晰度标记 |
### 丰富与分类
| 工具 | 描述 |
|------|-------------|
| `planwright_list_unenriched` | 列出缺少意图摘要的目标/计划 |
| `planwright_list_unclassified` | 列出缺少战略分类的目标 |
| `planwright_list_my_bugs` | 列出该项目的 bug |
---
## 支持
- [文档](https://planwright.tools/docs)
- [GitHub 讨论](https://github.com/Planwright/planwright/discussions)
- [报告 bug](https://github.com/Planwright/planwright/issues/new?template=bug_report.md)
---
## 许可证
Planwright 是一款商业产品。本存储库中提供的 MCP 集成示例遵循 MIT 许可证。
详见 [LICENSE](./LICENSE)。
