内容
# Planr
Planr 是一个本地优先的规划和执行协调工具，适用于编码代理。它将可审查的 Markdown 计划与依赖感知的工作图结合起来，使 Codex、Claude Code、Cursor、通用 MCP 客户端和人类操作员可以安全地驱动相同的工作 — 从想法到可验证的完成。
[**查看演示 →**](https://x.com/kevinkern/status/2066957434564808884?s=20)
[**文档 →**](https://planr.so/docs)
```text
想法 -> 产品计划 -> 构建计划 -> 地图 -> 选择 -> 日志 -> 审查/证据 -> 关闭
```
## 为什么选择 Planr
扁平的待办事项列表在实际工作具有结构时就会崩溃。Planr 将工作建模为依赖图，因为工作实际上就是这样：
- **准备就绪是计算出来的，而不是猜测的。** 只有当阻塞项关闭时，某项工作才变为“就绪”；`planr pick` 返回实际可以开始的工作。
- **并行代理需要原子声明。** 选择是数据库强制的原子声明 — 一个项，一个所有者，没有检查列表竞争。
- **“完成”是有门槛的，而不是断言的。** 关闭需要日志支持的证据（文件、命令、测试），而开放的审查会阻塞目标。
- **状态在会话之间存活。** Markdown 计划保留范围和验收标准；SQLite 图在移交、重启和代理切换期间保留实时状态。
- **失败是结构化的。** 过时的选择、超时和重试是可检测和可恢复的（`planr recover sweep`）。
三个层次实现了这一点：**计划**（可审查的 Markdown 包）、**地图**（具有选择、审查、日志的实时依赖图）和 **代理循环**（适用于每种主要编码代理的技能、CLI 和 MCP 工作流）。完整模型：[任务图模型](docs/TASK_GRAPH_MODEL.md) 和 [操作模型](docs/OPERATING_MODEL.md)。
## 安装
```bash
brew install instructa/tap/planr
```
或者通过 npm（提供平台原生二进制文件，无需工具链）：
```bash
npm install -g planr
```
或者使用发布安装程序：
```bash
curl -fsSL https://raw.githubusercontent.com/instructa/planr/main/scripts/install.sh | sh
```
然后初始化一个项目。选择后，Claude Code 和 Cursor 也会接收到独立的项目工作者/审查者角色；Codex 工作流技能来自其插件：
```bash
planr project init "我的产品" --client all
```
手动下载、从源代码构建和客户端连接细节：[安装指南](docs/INSTALL.md)。
## 安装插件（技能）
`plugins/planr` 下的插件包含十种 Planr 工作流技能。可选的模型路由角色来自存储库本地的路由包。需要单独使用 `planr` CLI（上面）。
<a id="install-plugin-codex"></a>
<details>
<summary><strong>Codex</strong></summary>
```bash
codex plugin marketplace add instructa/planr
codex plugin add planr@planr
```
</details>
<a id="install-plugin-claude-code"></a>
<details>
<summary><strong>Claude Code</strong></summary>
在 Claude Code 会话中：
```text
/plugin marketplace add instructa/planr
/plugin install planr@planr
```
重启 Claude Code 后。技能具有命名空间（`/planr:planr`，`/planr:planr-loop`），插件会自动注册 `planr-worker` 和 `planr-reviewer` 子代理。
</details>
<a id="install-plugin-cursor"></a>
<details>
<summary><strong>Cursor</strong></summary>
一条命令安装插件将携带的所有内容：
```bash
planr install cursor # 写入.cursor/mcp.json、.cursor/agents/ 和 .cursor/skills/
planr install cursor --no-mcp # 项目技能、子代理和钩子；无 MCP 配置
```
干燥运行还会打印一个单击的 `cursor://` 深度链接，用于用户级 MCP 安装。市场列表正在审查中。多任务处理与 Cursor 子代理：[Cursor 指南](docs/CURSOR.md)。
</details>
<a id="install-plugin-opencode"></a>
<details>
<summary><strong>opencode</strong></summary>
暂无插件。使用 Planr 作为 MCP 服务器，并将 CLI 提示粘贴到您的代理指令中：
```bash
planr mcp # stdio MCP 服务器
planr prompt cli
```
</details>
## 告诉你的代理
记住一个公共入口点：`$planr`。它从实时 Planr 状态路由请求，包括仅规划工作和自主目标准备。阶段技能是由路由器选择的先进表面。
从一个想法开始一个新产品：
```text
使用 $planr。
创建一个可生产的 Habit Tracker 网络应用计划。创建产品计划，
拆分 MVP 构建计划，检查它，然后构建 Planr 地图。暂时不要实施。
```
对于长时间的自主运行，请在驱动程序外部准备。准备结果打印一个实际的计划 ID；然后，Codex 或 Claude Code 仅启动计划绑定的循环驱动程序：
```text
使用 $planr 准备一个用于每周概览功能的自主目标。
/goal 使用 $planr-loop on plan <plan-id>。循环合约存储在 planr
上下文（标签：goal-contract）。
目标：发布每周概览功能。当所有范围内地图项都关闭
具有日志证据，所有审查都关闭完成，并且实时验证日志显示
浏览器中的功能。迭代预算：10。
```
中途工作（现有项目的新功能，重构或修复）的工作方式相同 — 它有自己的功能范围计划，并扩展现有的地图。两个旅程的示例提示：[两个旅程（新项目与现有项目）](docs/SKILLS.md#two-journeys-new-project-vs-existing-project)。随时使用 `planr map show` 查看进度。
## 新增功能
- **1.5.0 — 可选路由策略：** Planr Core 保持提供者中立，而可独立构建的 `planr-routing` 包拥有 Codex、Claude Code、Cursor 和混合主机设置的模型策略和主机绑定。从 [路由包](docs/ROUTING_BUNDLES.md)、[`planr-routing` 指南](planr-routing/docs/MODEL_ROUTING_POLICY.md) 和 [1.5.0 版本说明](https://github.com/instructa/planr/releases/tag/v1.5.0) 开始。
- **1.4.0 — 验证预设：** 增加了策略驱动的组合、评估、签名注册表证据和公共目录。参见 [1.4.0 版本说明](https://github.com/instructa/planr/releases/tag/v1.4.0)。
- **1.3.0 — 原生主机钩子：** 增加了自动会话状态注入和支持主机循环的恢复。参见 [钩子指南](docs/HOOKS.md) 和 [1.3.0 版本说明](https://github.com/instructa/planr/releases/tag/v1.3.0)。
有关完整的版本历史，请参见 [更新日志](CHANGELOG.md)。
## 文档
- [安装](docs/INSTALL.md)
- [技能](docs/SKILLS.md)
- [长期目标](docs/GOALS.md)
- [模型路由](docs/MODEL_ROUTING.md) · [示例：网络应用](docs/EXAMPLE_WEBAPP.md)
- [主机钩子](docs/HOOKS.md)
- [CLI 参考](docs/CLI_REFERENCE.md)
- [MCP 指南](docs/MCP_GUIDE.md)
- [Codex](docs/CODEX.md) · [Claude Code](docs/CLAUDE_CODE.md) · [Cursor](docs/CURSOR.md)
- [操作模型](docs/OPERATING_MODEL.md)
- [任务图模型](docs/TASK_GRAPH_MODEL.md)
- [架构](docs/ARCHITECTURE.md)
- [测试](docs/TESTING.md)
- [故障排除](docs/TROUBLESHOOTING.md)
- [规格包](docs/planr-spec/README.md)
- 更多：[更新日志](CHANGELOG.md)、[导入](docs/IMPORT.md)、[安全](docs/SECURITY.md)、[移交和故事](docs/HANDOFFS_AND_STORIES.md)、[npm 包](docs/NPM.md)
## 许可证
MIT。参见 `LICENSE.md`。
