cpm-planner

cpm-planner

cpm-planner 是一款用于 Agent 工作的关键路径法（CPM）规划器，以 MCP 服务的形式提供。提交任务图后，它会计算计划：最早和最晚开始时间与完成时间、时差、关键路径，以及决定完工时间的瓶颈任务。随后，它会分配考虑锁定状态的就绪任务组，这些任务组中的交付项文件集彼此不重叠，因此多个工作者可以并行执行而不会发生冲突。计划可以作为代码形式的文件保存在代码库中，并支持分支变体和对比；只读工具可以检查计划、根据资源容量进行资源平衡并运行蒙特卡洛风险分析；挣值工具可以根据冻结的基线跟踪 PV、EV、AC、SPI 和 CPI；可选的 AI 评审还可以提出经过验证的计划改进。任何 MCP 客户端（Claude Code、Cursor、VS Code、Codex、自定义编排器或 praxec 工作流）都可以通过 stdio 驱动它。它是一个独立工具，不依赖 praxec。

目录

• 安装
  • 预构建二进制文件（推荐）
  • 固定版本
  • npm
  • 从源码安装
  • Docker
  • 验证安装
• 快速入门：计划即代码
• 快速入门：挣值
• 与 AI Agent 配合使用
• MCP 工具
  • 计划即代码工作流
  • 计划评审（可选）
• 作为库使用
• Praxec
• 环境变量
• 文档
• 贡献
• 许可证

安装

预构建二进制文件（推荐）

已为 Linux、macOS 和 Windows 的 x86_64 与 ARM64 平台发布预构建包。

安装程序会识别你的操作系统和 CPU，并下载匹配的归档文件。它们会 在安装前验证归档文件的 SHA-256 是否与发布版本的 checksums.sha256 一致， 然后在用户本地目录中原子替换二进制文件。如果校验和不匹配，安装程序会以非零状态退出， 不会安装任何内容。再次运行安装程序会原地升级。

# Linux / macOS  ->  ~/.local/bin/cpm-planner
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh

# Windows (PowerShell)  ->  %LOCALAPPDATA%\Programs\cpm-planner\cpm-planner.exe
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex

安装程序会打印安装路径的绝对路径。向 GUI 客户端注册服务时，请使用该路径。

# Linux / macOS
curl -fsSLO https://github.com/praxec/cpm-planner/releases/latest/download/install.sh
less install.sh
sh install.sh --version <version>

# Windows
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 -OutFile install.ps1
Get-Content install.ps1
.\install.ps1 -Version <version>

固定版本

在本 README 的命令中，<version> 是诸如 v0.2.0 的发布标签。请从发布页面中选择一个版本。

# Linux / macOS
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh -s -- --version <version>

# Windows (PowerShell): the piped form cannot take parameters, so use the environment variable...
$env:PRAXEC_VERSION = '<version>'; irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex
# ...or a script block
& ([scriptblock]::Create((irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1))) -Version <version>

npm

使用 Node 18 或更高版本，从 npm 安装 cpm-planner 命令：

npm install -g @matthew-cochran/cpm
cpm-planner --version

此软件包是一个轻量级启动器。它会下载适用于你平台的发布二进制文件、验证校验和并缓存该文件；此操作会在安装期间进行，若 npm 跳过安装脚本，则会在首次运行时进行。软件包版本与发布版本一致，因此 npm install -g @matthew-cochran/[email protected] 可以固定到指定版本。若要运行而不安装，请使用 npx -y @matthew-cochran/cpm。详情和环境变量请参阅 npm/README.md。

从源代码构建

使用 Cargo 构建并安装带标签的发布版本（需要 Rust 1.99 或更高版本）：

cargo install --git https://github.com/praxec/cpm-planner --tag <version> --locked

在下一次执行 cargo publish 之前，crates.io 上的列表会落后于 GitHub 发布版本，因此 cargo install cpm-planner 目前无法安装最新版本。请按上述方式从标签安装。

Docker

docker pull ghcr.io/praxec/cpm-planner
docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner

-i 会保持 stdin 打开，以供 stdio 传输使用。

此镜像设置了 CPM_PLANNER_DB=/data/cpm-planner.db，并将 /data 声明为由非特权 app 用户拥有的卷，因此命名卷可以在多次运行间保留计划状态。对于绑定挂载（-v "$PWD:/data"），请以你自己的身份运行，确保目录可写：--user "$(id -u):$(id -g)"。仅在需要覆盖路径时传入 -e CPM_PLANNER_DB=...。

要将此镜像注册到客户端，请将 docker 放入 command，其余内容放入 args。例如，在 Claude Code 中：

claude mcp add cpm-planner --scope user -- docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner

验证安装

cpm-planner --version

它会输出 cpm-planner <version>。若要在不使用客户端的情况下检查 MCP 端，请运行仓库中的冒烟测试脚本。该脚本会执行 MCP initialize 和 tools/list 握手；如果缺少 plan.submit、plan.status 或 plan.get，则会失败：

node scripts/mcp-smoke.mjs /absolute/path/to/cpm-planner

快速入门：将计划作为代码

将计划（PlanGraph）写入 .cpm-planner/plans/<name>/<variant>.json：

1. plan.lint {path: ".cpm-planner/plans/checkout/main.json"} — 静态检查，不写入状态。
2. plan.sync {path: ".cpm-planner/plans/checkout/main.json"} — 注册该变体并返回其 plan_id。
3. plan.status {plan_id} — 查看进度安排、关键路径、就绪集和锁。

plan.sync 会根据内容哈希追踪文件；如果被追踪的文件与存储的头部图不一致，plan.status 会报告 definition_drift。

快速入门：挣值管理

冻结基线、记录进度，然后读取报告（earning_rule: "weighted" 时，earned_pct 按比例挣值；fifty_fifty 会在可交付成果开始进行或报告了任何 earned_pct 后计入 50%；默认的 zero_hundred 则在完成时计入全部挣值）：

1. plan.baseline {plan_id} — 冻结 CPM 进度安排和预算，作为基线 1。
2. plan.mark_status {plan_id, deliverable_id, caller_id, status: {"status": "in_progress"}, earned_pct: 50, actual_effort_hours: 4} — 报告进度和实际成本。
3. plan.ev {plan_id} — 查看 PV、EV、AC、SV、CV、SPI、CPI、EAC 和警报。
4. plan.snapshot {plan_id, format: "markdown"} — 追加读数并导出 Markdown 表格。

分母为零的比率会显示为 null，并在 undefined 中说明；警报（SPI_BELOW_0_9、CPI_BELOW_0_9）会比较最近两次存储的读数。

与 AI Agent 配合使用

任何 MCP 客户端都可以通过 stdio 运行 cpm-planner：将 cpm-planner 二进制文件注册为命令，或者在 Node 18 或更高版本中使用 npx -y @matthew-cochran/cpm。 对于图形界面客户端，请使用安装程序输出的绝对路径。

使用 cpm-planner skills install --target <tool> --user（或 --project <dir>）安装 Agent 技能（/cpm-plan 等），其中 <tool> 可以是 claude、codex、cursor、copilot、gemini、all 或 agents-md（仅限项目）。

docs/AGENT-INSTALL.md 提供各客户端的安装步骤（Claude Code、Claude Desktop、Codex、Cursor、VS Code、Gemini CLI 等）、env 代码块、验证和故障排除。llms.txt 为大模型编制了文档索引。

MCP 工具

plan.lint、plan.simulate 和 plan.review 必须且只能使用内联 graph、已存储的 plan_id 或计划文件 path 三者之一；plan.schedule 接受 graph 或 plan_id； plan.schedule 和 plan.simulate 会拒绝 plan.submit 所拒绝的内容，而 plan.lint 会将其报告为问题。对于相同平台和工具链，给定种子时 Monte Carlo 输出可复现；由于浮点数学函数可能存在差异，不保证不同目标平台或编译器版本之间的结果逐位完全相同。

计划即代码工作流

将计划编写为文件，保存到 .cpm-planner/plans/<name>/<variant>.json，使用 plan.lint {path} 检查，通过 plan.sync {path} 注册，然后执行返回的 plan_id。一个具名计划行可以有多个变体，但只能有一个选定变体：plan.fork 根据结构化编辑创建草案，plan.compare 对变体评分，plan.select 则指定一个可执行变体。请将定义保存在已跟踪的文件中，切勿保留未跟踪的临时图。

计划审查（可选）

plan.review 会通过 OpenRouter 向 Jev（typesafe/jev-1.13）——TypeSafe 的校准判断模型——询问一个通过 lint 检查的计划：每次审查最多批量提出 64 个问题。设置 OPENROUTER_API_KEY（或 CPM_OPENROUTER_KEY_FILE）后才会启用；若未设置密钥，工具仍会响应，并返回 review_unavailable 和 lint 报告。无效的 LLM 设置不会导致服务停止：它会在启动时记录日志，而 plan.review 会返回 review_unavailable，并说明具体设置项。

• 概率仅供参考。 请将审查结果视为第二意见。提案会通过机械方式验证（编辑后的计划必须通过 lint 检查，并模拟出更短的总工期）；使用 plan.fork {edits} 应用一项提案，然后运行 plan.compare。

• 成本。 每次实际调用评审模型的 plan.review 请求，都会产生一笔 OpenRouter 费用；Jev 在 OpenRouter 上的输入费用约为每百万个 token 0.042 美元。每份报告都会在服务提供方提供 usage 时附上该信息。每台服务最多同时运行 2 次调用评审模型的审查；更多请求会等待空位（在调用模型前就结束的审查，例如缺少密钥或存在 lint 错误的审查，无需等待）。

• 隐私。 以下是该单次请求中发送到 OpenRouter 的全部内容：

  • 固定的任务句子、计划总工期和关键路径（ID）；
  • 问题：每个问题都会包含其类型、问题中提及的交付物 ID，以及引用这些 ID 的问题句子；根据问题类型，句子还会包含前置项的 consumes 文本、交付物的计划工时、计划的计划工时中位数，以及触发缺失依赖问题的启发式信号（描述提及了另一交付物、文件位于相同或嵌套目录中、共享 metadata.owner）；
  • 对于问题提及的每项交付物：其 ID、计划工时、浮动工时、critical 和 milestone 标记、所拥有的文件路径（完整发送，不截断）、前置项（ID、consumes、类型），以及 description、artifact 和 owner 元数据。description、artifact、owner 和 consumes 均截断至 500 个字符。

  图中的其他内容（其他交付物、其他元数据键、估算）均不会发送。请勿审查其内容可能不适合分享给 OpenRouter 的计划。

• 审计。 密钥不会被记录或返回，错误放置的 LLM 变量值也不会。每次 plan.review 调用都会记录一条 plan.review 审计事件，无论结果如何（包括缺少计划、路径错误或审查失败）；唯一不记录审计的情况是因参数无效（invalid_params）而拒绝调用。事件仅包含以下字段：

  • status：ok、review_unavailable、invalid_graph 或 error（审查失败：PLAN_NOT_FOUND、INVALID_PATH、INVALID_CAPACITIES 等）；
  • code：error 时为错误前缀，否则为 null；
  • failure_class：若 review_unavailable 是由评审模型调用失败所致，则为其类别（unauthorized、rate_limited、timeout、upstream、decode、transport、invalid_request）；否则为 null（包括缺少密钥和 LLM 设置不可用的情况）；
  • plan_id：被审查的已存储计划；若使用内联 graph 或 path，则为 null；
  • question_count：发送的问题数量（未调用评审模型时为 0）；
  • jev_called：是否调用了评审模型；
  • prompt_hash：规范化请求的 sha256；未调用评审模型时为 null；
  • model：服务提供方报告的模型；若调用失败，则为已配置的模型；未调用评审模型时为 null；
  • endpoint：评审模型端点的主机名；未配置评审模型、lint 检查发现错误或审查以 error 结束时为 null。

  提示词本身绝不会被记录。

作为库使用

CPM 内核也是一个纯 Rust 库，可独立于 MCP 使用：

use cpm_planner::{CpmAlgorithm, Task, TaskKind};

let mut tasks = vec![
    Task::new("design", "Design", TaskKind::Custom { description: "design".into() }, 4.0),
    Task::new("build", "Build", TaskKind::Custom { description: "build".into() }, 8.0)
        .depends_on("design"),
    Task::new("test", "Test", TaskKind::Custom { description: "test".into() }, 2.0)
        .depends_on("build"),
];

let result = CpmAlgorithm::calculate(&mut tasks);
println!("critical path: {:?}", result.critical_path); // ["design", "build", "test"]
// also: result.bottlenecks, result.optimal_duration_parallel,
// and per-task .float (slack) / .is_critical on each Task.

crate 级文档（运行 cargo doc --open，或在当前版本发布到 docs.rs 后查阅）中包含一个可运行的示例，演示如何通过提交、租用和完成来驱动规划器。

llm::jev::JevJudge（plan.review 裁判）拥有自己的 HTTP 客户端和连接池。池化连接由打开它的 tokio 运行时驱动，因此请在同一个运行时中使用裁判及其克隆，并为其他运行时创建新的裁判。

Praxec

cpm-planner 完全独立：它使用纯 MCP 通信，不依赖任何特定客户端的代码。Praxec 工具包将其作为 MCP 工具使用。要将其接入 praxec 工作流，请声明一个 MCP 连接（仅使用协议，不共享代码）：

connections:
  planner:
    kind: mcp
    command: cpm-planner

最简单的启动方式是使用一条命令完成设置，同时启动它以及使用它的工作流工具包：

curl -fsSL https://raw.githubusercontent.com/praxec/packs/main/setup.sh | bash

请参阅工具包注册表，了解此工具的提供方坐标（容器镜像或发布版二进制文件），以及依赖它的工具包。

环境变量

在客户端的 env 块中设置这些变量（或使用 -e/--env 标志，或 docker run -e）。这些变量均为可选。

租约默认有效期为 5 分钟。对于长时间运行的工作，请在获取租约或发送心跳时传入 ttl_seconds（≤ 服务端上限），并至少每隔 ttl/3 发送一次心跳。

文档

• docs/README.md：项目文档索引。
• docs/AGENT-INSTALL.md：为你的 AI 编码工具安装、注册并验证 cpm-planner。
• docs/architecture.md：模块、请求流程、存储架构和并发。
• docs/releasing.md：发布操作指南。
• CONTRIBUTING.md、SECURITY.md、SUPPORT.md、CHANGELOG.md。

贡献

欢迎贡献。有关工具链、门禁和分支模型，请参阅 CONTRIBUTING.md。 所有参与者均同意遵守行为准则。

许可证

Apache-2.0。