powerplan

powerplan

将 PLAN.md 作为 Agent 式开发的运营支柱。

powerplan 是一个 MCP 服务，为协调者和工作 Agent 提供基于自然语言的 API，以操作项目的 PLAN.md：查看进度、创建迭代、完成任务、确保标题准确无误——无需随意改写文件。

mcp-name: io.github.CynaCons/powerplan

MCP 服务名称	powerplan
PyPI	powerplan-mcp（powerplan 是另一个无关的软件包）
注册表	io.github.CynaCons/powerplan
状态	v0.9.0 — 回合结束时的状态视图（PLAN.md）
网站	GitHub Pages
搭配使用	PowerSpawn（可选）

---

安装

你需要 uv（提供 uvx）或 Python 3.10+。

uvx powerplan-mcp

这是 stdio MCP 服务。将客户端指向它：

Claude Code / Cursor / .mcp.json

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Claude Desktop

在 claude_desktop_config.json（mcpServers）中使用相同的代码块。

Grok（~/.grok/config.toml 或项目配置）

[mcp_servers.powerplan]
command = "uvx"
args = ["powerplan-mcp"]
env = { PYTHONUNBUFFERED = "1", PYTHONIOENCODING = "utf-8" }
enabled = true

pip（不使用 uv）

pip install powerplan-mcp

{
  "mcpServers": {
    "powerplan": {
      "command": "python",
      "args": ["-m", "powerplan"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

---

Agent 指南

优先使用范围明确的工具。不要为了弄清楚要做什么而读取整个 PLAN.md。

1. 如果工具因“没有 PLAN.md”而失败 → 先运行 create_plan。
2. show_miniplan — 按计划自身的格式显示当前要处理的内容：原样呈现当前迭代及其相邻标题。每次会话都从这里开始。
3. get_current_iteration — 以 JSON 格式返回相同内容。
4. get_iteration(version) — 查看某个迭代的任务和进度。
5. 使用 add_task / add_tasks / complete_task（多项时使用 indexes）/ start_iteration / close_iteration 进行修改。
6. show_plan 用于快速浏览，不会输出完整内容。
7. 每个重要回合结束时（更改了文件、勾选或添加了任务、运行了检查、关闭了迭代），都要在代码块中原样粘贴 show_current_iteration 的结果，让用户一眼了解状态和进度。服务会通过 MCP 指令将此规则发送给每个客户端。

每个工具都接受可选的 plan_path（相对或绝对路径）。默认值：从 cwd 开始向上查找最近的 PLAN.md。

修改操作中的可选参数 agent 会在修改过的行末添加 [agent: id] 标签。

---

原因

Agent 经常手动编辑 PLAN.md。标题会逐渐偏离实际情况，“COMPLETE” 会在没有依据时被标记，多个 Agent 组成的群组也会互相影响。powerplan 是唯一写入者：读取器容错，写入器精确修改，并可选择添加 [agent: …] 标签。

---

工具

工具	行为
create_plan	缺少时初始化 ./PLAN.md（或 plan_path）；使用 force 覆盖
show_miniplan	会话起始工具 — PLAN.md 原始片段：逐字节呈现当前（或指定）迭代，相邻内容折叠为标题行（before/after）
get_current_iteration	推荐 Agent 使用 — 以范围明确的 JSON 显示当前工作
get_iteration	以 JSON 格式显示某个版本（任务、进度）
list_iterations / find_task / get_backlog	无需读取整个文件即可浏览
create_major / create_iteration / add_task / add_tasks	精确修改（批量添加只需一次写入）
complete_task / reopen_task / remove_task / defer_task	修改一项或多项（indexes / tasks）；可选 [agent: id]
start_iteration / close_iteration	ACTIVE/current 与 COMPLETE 生命周期
check_plan	检查结构并进行 lint
show_current_iteration	回合结束工具 — 状态视图（状态、进度计数、目标、任务），每个重要回合结束时都要粘贴
show_plan	紧凑的人类可读概览（非完整内容）

---

受管理的计划格式

构造	模式
Major	## vX.Y — Title
迭代	### vX.Y.Z — Title
目标	**Goal:** …
任务	- [ ] / - [x]
待办列表	## Backlog

类似阶段的标题和其他正文会作为不透明内容块保留原样。

---

从源代码安装

克隆、可编辑安装，或作为 PowerSpawn 子模块——适用于贡献者。

git clone https://github.com/CynaCons/powerplan.git
cd powerplan
pip install -e ".[dev]"
python -m powerplan          # same stdio server
# or: powerplan-mcp

PowerSpawn 可以将此仓库作为 Git 子模块引入。请注册两个 MCP 服务——它们不会合并：

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"]
    },
    "powerspawn": {
      "command": "python",
      "args": ["-m", "powerspawn.mcp_server"]
    }
  }
}

仅使用路径（无需安装）：python /path/to/powerplan/powerplan_server.py

落地页：cd site && npm ci && npm run dev

---

发布（维护者）

完整流程、身份信息和故障历史：docs/RELEASING.md。 Agent 检查清单：项目技能 release-powerplan（/release-powerplan）。

简要流程：递增该指南列出的每个版本文件 → pytest -q → 创建标签 vX.Y.Z → 推送标签。.github/workflows/publish.yml 会将 powerplan-mcp 上传到 PyPI，然后将 server.json 上传到 MCP Registry，名称为 io.github.CynaCons/powerplan。

---

许可证

MIT——详见 LICENSE。