mcpp计划
AI编码代理的持久任务和步骤跟踪器。使Claude Code(或任何兼容MCP的代理)能够将工作分解为任务,跟踪每个任务中的步骤,并准确记住它在会话中的中断位置。
> 新来的? 看 RAPIDSTART.md --在10分钟内克隆、配置并开始使用它。
> 每天吃狗粮。 该模块通过自身开发、维护和不断改进。每个功能在构建的那一刻都会进行真实世界的测试。
>
> 代理便携。 在一个代理中启动一个任务,在另一个代理中将其拾取——不会丢失上下文。状态存在于数据库中,而不是对话中。
为什么
AI代理在会话之间失去上下文。当你继续谈话时,代理人不知道它在做什么,完成了哪些步骤,或者下一步是什么。mcpp计划通过为代理提供一个由SQLite支持的结构化、持久的任务管理器来解决这个问题。
代理通过MCP工具与它对话。你用简单的英语和代理人说话。代理人管理其余部分。
运作原理```
project
└── user (auto-detected from $USER)
└── task (a focus area, like "build login page")
└── step (individual action, like "create user table")
- **任务** 是顶级工作项(功能、错误、重构)
- **步骤** 是任务中有序的操作
- **一次只有一个任务和一个步骤处于活动状态** --代理人总是知道下一步该做什么
- **国家坚持** 在 `plan.db` 在模块目录内
- **多用户** --每个操作系统用户在共享数据库中获得独立的任务游标
## 安装
mcpp计划是 mcpp 工具模块。通过将工具路径添加到mcpp配置中来安装它。
### 先决条件
- Python 3.10+
- SQLite 3(与Python捆绑在一起)
- MCP兼容代理(克劳德代码等)
### 设置
1. 将两个存储库克隆为兄弟库:```bash
cd ~/projects
git clone git@github.com:pacmac/mcpp.git
git clone git@github.com:pacmac/mcpp-plan.git
mcpp的默认值 tools.yaml 已经包括 ../mcpp-plan,因此,如果它们并排放置,则不需要额外的配置。
- 使用Claude代码注册MCP服务器:```bash
claude mcp add mcpp --scope user \
--env MCPP_LOG_LEVEL=error \
--env MCPP_TIMEOUT_SECONDS=30 \
-- python3 ~/projects/mcpp/mcpp.py
替换 `~/projects` 使用您的安装文件夹。
3. 数据库是按照以下方式自动创建的 `plan.db` 首次使用时在模块目录中。无需设置。
## 工具
所有工具均通过MCP暴露 `plan_` 前缀。
### 任务工具
|工具|说明|
|------|-------------|
| `plan_task_new` |创建具有初始步骤的任务|
| `plan_task_list` |列出任务(默认情况下为您的任务, `show_all` 为大家)|
| `plan_task_show` |显示任务及其步骤|
| `plan_task_status` |显示活动任务和进度|
| `plan_task_switch` |切换到其他任务|
| `plan_task_complete` |将任务标记为已完成|
| `plan_task_adopt` |将另一个用户的任务(深度复制)到自己的列表中|
| `plan_task_notes_set` |为任务设置注释(追加销售:目标/计划按种类替换,注释按ID更新或创建新)|
| `plan_task_notes_get` |查看任务注释(返回带有ID的注释)|
| `plan_task_notes_delete` |按ID从任务中删除注释|
### 步骤工具
|工具|说明|
|------|-------------|
| `plan_step_list` |列出任务中的步骤|
| `plan_step_show` |显示步骤详细信息|
| `plan_step_switch` |切换到特定步骤|
| `plan_step_done` |将步骤标记为完成|
| `plan_step_new` |向任务添加步骤|
| `plan_step_delete` |软删除一个步骤|
| `plan_step_reorder` |重新排序任务中的步骤|
| `plan_step_notes_set` |在步骤上设置注释(追加销售:按ID更新或创建新)|
| `plan_step_notes_get` |查看步骤注释(返回带ID的注释)|
| `plan_step_notes_delete` |按ID从步骤中删除注释|
### 用户工具
|工具|说明|
|------|-------------|
| `plan_user_show` |显示当前用户信息|
| `plan_user_set` |设置您的显示名称|
### 项目工具
|工具|说明|
|------|-------------|
| `plan_project_show` |显示项目元数据|
| `plan_project_set` |设置项目名称和描述|
### 报表工具
|工具|说明|
|------|-------------|
| `plan_project_report` |生成包含所有任务、目标、计划和步骤的项目报告(.md)|
| `plan_task_report` |生成包含目标、计划、步骤和注释的任务报告(.md)|
报告将以带有日期戳的文件名写入工作区目录(例如。 `project_report_260215.md`, `task_report_build-auth_260215.md`).当天文件被覆盖。
### 版本控制
Git操作(检查点、提交、推送、日志、状态、差异、文件历史、文件还原)由提供 **使用 mcpp-git** 作为 `dev_*` 工具。呼唤老人 `plan_*` git工具名称返回一条重定向消息,指向正确的 `dev_*` 等效。
### 配置工具
|工具|说明|
|------|-------------|
| `plan_config_show` |显示当前配置(合并默认值+覆盖)|
### 效用
|工具|说明|
|------|-------------|
| `plan_readme` |显示面向用户的README|
## 用法
您通过您的代理以自然语言与计划进行交互。示例:```
"Create a task called build-auth with steps: design schema, implement JWT, add middleware, write tests"
"What am I working on?"
"Mark step 1 as done"
"Switch to step 2"
"Add a note: decided to use refresh tokens"
"Show me all my tasks"
"Switch to the fix-search task"
代理会自动将这些转换为MCP工具调用。
步骤生命周期```
planned → started → complete
只能迈出一步 `started` 在任务中的某个时间。当你切换步骤时,新的步骤变成 `started`.完成一步标志着它 `complete`.
## 钞票种类
笔记有 `kind` 对其目的进行分类的字段:
|种类|用途|何时使用|
|------|---------|-------------|
| `goal` | **什么** 需要实现|在开始工作之前——确定目标|
| `plan` | **如何** 它将在开始工作之前完成|定义方法|
| `note` |观察和更新|执行期间--自由形式(默认)|
### 设置注释
使用 `_set` 创建或更新笔记的工具。对于目标/计划类型,注释按类型排列(每个任务只有一个目标和一个计划)。对于常规笔记,请通过 `id` 更新或省略以创建新:```
plan_task_notes_set text="Implement user authentication" kind="goal"
plan_task_notes_set text="Use JWT with refresh tokens" kind="plan"
plan_task_notes_set text="Decided to skip OAuth for now"
再次设定目标或计划会取代现有的目标或计划——没有重复。
札记
使用 _get 查看笔记的工具。笔记会返回ID,以便您可以更新或删除它们:```
plan_task_notes_get # all notes
plan_task_notes_get kind="goal" # only goal notes
### 更新和删除笔记
把纸条递给我 `id` (返回者 `_get`, `_set`, `show`,以及 `switch`)要更新或删除:```
plan_task_notes_set text="Revised note" id=42 # update note 42
plan_task_notes_delete id=42 # delete note 42
工作流执行
默认情况下,任务至少需要一个 goal 还有一个 plan 在切换或完成步骤之前请注意。这确保了每项任务在实施之前都有明确的目标和方法。在中禁用此功能 config.yaml:```yaml
workflow:
require_goal_and_plan: false
### 显示
`plan_task_show` 和 `plan_task_switch` 内联显示目标和计划注释,并返回所有带有ID的注释,因此目的和方法始终可见,注释可以在一次后续通话中更新。 `plan_step_show` 和 `plan_step_switch` 同样,包括带有ID的步骤注释。
### 迁移的任务
在引入注释类型之前存在的任务具有迁移占位符注释(`"(migrated — no goal defined)"`).这些内容未显示在 `plan_task_show` 并且不满足工作流执行。通过在这些任务中添加真正的目标和计划注释来取代它们。
## 任务采纳
使用 `plan_task_adopt` 将其他用户的任务(或克隆您自己的任务)深度复制到您的任务列表中。当多个代理或用户想要独立处理类似的任务时,或者当你想将一个任务作为起点时,这很有用。```
plan_task_adopt name="build-auth" new_name="build-auth-v2"
被复制的内容:
- 任务元数据(名称、描述)
- 所有步骤(重新映射父引用)
- 所有任务级笔记(目标、计划、笔记)
- 所有步骤级别注释
什么意思 不 复制:
- 变更日志——创建了一个“从{user}/{task}采用”条目
默认情况下,所有步骤状态都重置为 planned 所以你要重新开始。通过 reset=false 以保持原始状态。
所采用的任务将自动激活。A. new_name 如果项目中已存在具有源名称的任务,则需要。
数据库
所有州都位于一个SQLite数据库中 plan.db 在模块目录中,在所有项目中共享。每个项目都由其绝对文件系统路径标识。
模式
核心表:
project--工作区元数据(名称、路径、描述)users--具有可选显示名称的操作系统用户contexts--任务(名称、状态、所有者、项目)tasks--任务中的步骤(标题、状态、排序)context_state--每个任务的活动步骤光标user_state--每个项目每个用户的活动任务光标context_notes/task_notes--打字笔记(goal,plan,note)changelog--所有状态更改的审核日志
模式迁移是通过中的编号补丁自动应用的 schema_patches/.
配置
全局设置已生效 config.yaml 在模块目录中(旁边 plan.db).该文件是可选的——所有键都有合理的默认值。设置按部分组织。```yaml
workflow:
require_goal_and_plan: true # require goal and plan notes before step progress
allow_reopen_completed: false # allow switching to completed tasks (reopens them)
daily_backup: true # create one backup per day on first use
backup_retain_days: 7 # delete backups older than this many days
enable_steps: true # set false to hide step tools and strip step data
### 功能切换
禁用不需要的功能:```yaml
workflow:
enable_steps: false # hide step tools, strip step data from results
禁用时:
- 工具对MCP发现隐藏(
tools/list) - 直接调用返回一个明确的错误:
"Tool 'X' is disabled (enable_Y: false in config.yaml)" - 从任务结果和显示文本中删除步骤数据
默认值
| 节 | 键 | 默认值 | 描述 |
|---|---|---|---|
workflow |
require_goal_and_plan |
true |
在步骤进展之前需要目标和计划说明 |
workflow |
allow_reopen_completed |
false |
允许切换到已完成的任务(将其设置回活动状态) |
workflow |
daily_backup |
true |
首次使用时每天创建一个备份 |
workflow |
backup_retain_days |
7 |
删除超过此天数的备份 |
workflow |
enable_steps |
true |
设置 false 隐藏步骤工具并删除步骤数据 |
行为
- 缺少文件=所有默认值
- 缺少密钥=这些密钥的默认值
- 未知密钥保留在文件中,但被系统忽略
- 无效的YAML将恢复为所有默认值
工具
plan_config_show--显示当前设置(合并默认值+覆盖)- MCP的配置是只读的--编辑
config.yaml直接更改设置
迁移安全
架构迁移受到多层安全管道的保护(backup.py):
- 已验证备份 --
plan.db已复制到.backups/plan.db.YYMMDDx并且在继续之前,SHA-256校验和被验证为与实时DB匹配。 - 在副本上进行试迁移 --所有补丁首先应用于数据库的临时副本。如果试验失败(SQL错误或数据丢失),则永远不会接触实时数据库。
- 行数验证 --试验后,将每个表的行数与迁移前的行数进行比较。任何减少都会中止迁移。
- 实时迁移+重新验证 --只有在试验通过后,才会将补丁应用于实时数据库,然后进行第二行计数验证。
如果在任何步骤中出现任何失败,迁移将中止,并显示一条明确的错误消息和备份文件的路径。实时数据库保持不变。
备份使用字母后缀(a-z)用于在同一天进行多个备份。应用补丁时会创建迁移备份。此外,每天首次使用时都会运行每日自动备份(可通过以下方式配置 daily_backup),自动修剪早于 backup_retain_days.
提示和技巧
向代理人介绍一个新项目。 当开始处理新的代码库时,让代理先探索它:```
> Discover what this project is about, including its structure,
> and add what you learn to the project notes.
这使代理能够构建自己对代码库的理解——什么在哪里,事物是如何连接的,使用了什么约定——并为未来的会话保留该上下文。
**在不失去焦点的情况下捕捉想法。** 如果你在处理任务时发现了一个无关的问题或想到了一些事情,告诉代理人注意并继续:```
> Add a task: "refactor the cache expiry logic" -- then continue
> what you were doing.
这可以保持你当前的思维流不变,同时确保思想不会丢失。
让代理人先计划一下。 对于复杂的任务,在编写代码之前先考虑一下:```
> Plan how you'd approach this before writing code.
**使用帮助进行发现。** 代理可以调用内置 `help` 工具查看可用内容——无需记住工具名称:```
> What mcpp tools do you have?
建筑```
tool.yaml MCP tool definitions (schema for all plan_* tools)
mcpptool.py MCP entry point -- routes tool calls to Python API
context.py Business logic (create/switch/complete tasks and steps)
config.py Global configuration (config.yaml loading + defaults)
db.py SQLite connection, schema management, user/project helpers
backup.py Migration safety pipeline (verified backup, trial-on-copy, row validation)
schema.sql Base schema
schema_patches/ Incremental migrations (patch-4.sql through patch-11.sql)
```
入口点
execute(tool_name, arguments, context)--每次工具调用时由MCP主机调用get_info(context)--返回工具元数据和用于自动完成的现有任务名称
工具调用的流程
- MCP主机呼叫
execute("plan_step_done", {"number": 3}, {"workspace_dir": "/my/project"}) mcpptool.py路线_cmd_step_done- 处理程序构建命令列表并调用
_run_plan_cmd _run_plan_cmd动态导入db.py和context.py,打开中央数据库,并分派context.py在事务中运行操作- 结果字典返回结构化数据和
display用户的字符串
灵感源自
这个项目的灵感来自 安德烈亚斯·斯皮斯 (GitHub)和他的 人工智能辅助编码视频.
发布说明
看 发布.md 查看完整版本历史。
许可证
PolyForm非商业版1.0.0
免费供个人使用、研究、教育、非营利组织和政府使用。不允许用于商业用途。看 许可证 全文。
