MonkeyPlanner：本地优先的AI编程助手任务记忆中枢设计与实战

1. 项目概述：为AI编程助手打造的本地优先任务记忆中枢

如果你和我一样，日常开发重度依赖像Claude Code、Cursor这类AI编程助手，那你一定遇到过这样的困境：你让AI帮你修复一个bug，它噼里啪啦一顿操作，代码改好了，也提交了。但第二天，当你想让它继续优化相关功能，或者回顾一下昨天的改动点时，你和AI都陷入了“失忆”状态。你不得不重新描述上下文，AI也像第一次见面一样，需要重新理解任务背景。这种上下文断裂感，严重拖慢了人机协作的流畅度。

MonkeyPlanner就是为了解决这个核心痛点而生的。它不是一个传统的项目管理工具，而是一个专为“人类-AI”协作工作流设计的本地优先任务记忆中枢。你可以把它理解为你和AI助手之间的一个“共享大脑”或“任务看板”。它的核心设计哲学是“一键批准，AI干活”。你作为人类，负责发现需求、创建任务、审核批准和最终验收；而AI助手则通过MCP协议，无缝接入这个系统，自动读取任务指令、执行编码工作、更新进度，并在完成后提交给你审核。

最吸引我的是它的“本地优先”和“零遥测”承诺。所有数据——任务、看板、评论——都存储在你自己的机器上，默认使用SQLite，也支持PostgreSQL。没有云服务，没有数据上报，代码完全开源。这意味着你的项目规划、待办事项乃至与AI的对话记录，都完全由你掌控，这对于处理敏感或私有项目至关重要。

2. 核心设计思路：重塑人机协作的工作流边界

在深入代码之前，理解MonkeyPlanner的设计哲学至关重要。它没有试图让AI完全自主，也没有让人陷入繁琐的微观管理，而是在两者之间划出了一条清晰、高效的协作边界。

2.1 状态流转：精心设计的审批门控

MonkeyPlanner的任务状态机是其工作流的骨架，设计得非常克制且有效：

Pending（待定） → Approved（已批准） → InProgress（进行中） → QA（待审核） → Done（已完成） ↑ └─────────────── Rejected（已拒绝，需附原因）

这个流程的精妙之处在于几个关键控制点：

1. 强制审批门控（Pending → Approved）：这是第一个也是最重要的人工干预点。任何由AI或你创建的新任务，初始状态都是Pending。它不能直接被AI认领或开始工作。必须通过专用的POST /api/issues/{id}/approve端点（或在Web界面上点击“批准”按钮）才能进入Approved状态。这个设计强制了“先思考，后行动”的流程，避免了AI盲目开始错误或低优先级的工作。

2. QA审核闭环（QA → Done/Rejected）：当AI完成任务并提交后，状态变为QA。此时，必须由人类进行最终验收。如果通过，则标记为Done；如果发现问题，则使用reject_issue工具将其打回InProgress状态，并且必须提供拒绝原因。这个带原因的拒绝机制，为AI提供了明确的反馈，让它知道哪里需要改进，形成了有效的学习循环。

3. 灵活的中间状态：在Approved和Done之间，状态可以相对自由地流转（通过通用的PATCH更新）。AI可以claim_issue（认领）任务进入InProgress，也可以submit_qa提交审核。这种灵活性适应了实际开发中任务可能被中断、重新评估或转移的情况。

实操心得：在实际使用中，我强烈建议你严格遵守这个状态流。不要因为图省事而直接通过API把任务状态从Pending改成InProgress。这个审批步骤看似多余，实则是保证任务质量、让你对工作流有全局掌控的关键。它迫使你在AI开始“搬砖”前，花几秒钟确认一下：“这个任务描述清楚了吗？优先级合理吗？” 这能避免大量后续的沟通和返工成本。

2.2 数据模型：为AI理解而优化的任务结构

一个任务（Issue）在MonkeyPlanner中不仅仅是标题和描述。它被设计成包含AI高效工作所需的所有上下文信息：

• 核心字段：title,body（Markdown格式），status,boardId。
• AI指令区（Agent Instructions）：这是一个独立的Markdown字段，专门用来给AI编写清晰、具体的操作指南。例如：“请检查src/components/Button.tsx文件，将其中所有console.log替换为我们的自定义日志工具logger.debug，并确保类型安全。” 这个字段让任务指令与一般的任务描述（可能包含背景、链接等）分离，使AI能更快抓取重点。
• 成功标准（Success Criteria）：一个可勾选的清单。在创建任务时，你就可以定义好“完成”的具体标准。例如：1. 所有测试通过；2. 代码已提交到feat/button-logger分支；3. 更新了相关文档。AI在完成任务时可以逐一勾选，这既是它的检查表，也是你QA时的验收清单。
• 自定义属性：支持文本、数字、单选、多选、日期、复选框六种类型。你可以为不同的看板（如“Bug修复”、“功能开发”、“代码审查”）定义不同的属性集。比如，为“Bug修复”看板添加“严重程度”（单选：Critical, High, Medium, Low）和“影响版本”（文本）属性。
• 依赖关系：可以设置任务间的阻塞关系。AI在认领任务前，可以通过接口了解到是否有前置任务未完成，从而更合理地安排工作。
• 评论系统：所有关于该任务的沟通——你的补充说明、AI的进度汇报、代码片段分享——都通过评论进行。这形成了一个完整的、围绕单一任务的对话线程，是宝贵的上下文历史。

这种结构化的数据模型，使得任务对于AI而言不再是模糊的自然语言描述，而是一个包含操作指令、验收标准和相关上下文的“可执行工单”。

2.3 本地优先架构：数据主权与离线能力

“Local-first”是MonkeyPlanner的基石。后端使用Go编写，编译为单个二进制文件，前端资源通过embed.FS嵌入其中。这意味着部署极其简单：下载一个二进制，运行，完事。默认使用SQLite数据库，数据库文件就是一个普通的.db文件，放在你指定的目录（如./data）。你可以用任何SQLite工具打开它、备份它、甚至直接查询。

为什么这很重要？

1. 隐私与安全：你的项目规划、任务详情、与AI的协作记录全部留在本地。无需担心云服务的数据泄露、合规问题或服务商窥探。
2. 离线工作：一旦部署，整个应用就在你的局域网或本地机器上运行。即使没有互联网，你和本地运行的AI助手（如Claude Desktop）依然可以无缝协作。
3. 完全可控：你可以自由地修改、扩展，或者将数据库迁移到PostgreSQL以适应团队场景。数据的生杀大权完全在你手里。
4. 性能与延迟：本地网络通信的延迟可以忽略不计，UI的响应速度飞快，拖拽看板、搜索任务都如丝般顺滑。

这种架构选择，与AI编程助手本身强调的本地化、隐私保护特性高度契合，构成了一个真正属于开发者个人的、私密的效率工具链。

3. 部署与配置实战：从零到一的运行指南

理论说再多，不如动手跑起来。下面我将带你完成两种最实用的部署方式：最简单的Docker一键部署，以及适合深度定制和开发的本地构建部署。

3.1 方案一：Docker部署（推荐，5分钟上手）

这是最快、最干净、依赖最少的方式，特别适合只想快速体验或用于生产环境。

步骤1：拉取并运行容器打开你的终端，执行以下命令：

docker run -d \ --name monkey-planner \ -p 8080:8080 \ -v /path/to/your/data:/data \ -e MP_DSN="sqlite:///data/monkey.db" \ ghcr.io/kjm99d/monkeyplanner:latest

• -d: 后台运行。
• --name: 给容器起个名字，方便管理。
• -p 8080:8080: 将容器的8080端口映射到主机的8080端口。你可以把前面的8080改成其他未被占用的端口，如9090:8080。
• -v /path/to/your/data:/data:这是关键！将主机的一个目录挂载到容器的/data目录，用于持久化存储SQLite数据库文件。请将/path/to/your/data替换为你本地真实的目录路径，例如~/monkeyplanner-data。这样即使容器删除，你的数据也不会丢失。
• -e MP_DSN: 设置数据库连接字符串。这里指向容器内的/data/monkey.db文件。如果你用PostgreSQL，可以在这里替换。

步骤2：访问Web界面打开浏览器，访问http://localhost:8080（如果你改了端口，则替换为对应的端口）。你会看到一个内置的欢迎看板，它就像一份交互式教程，一步步引导你创建第一个看板、任务，并尝试批准流程。

步骤3：配置AI客户端（以Claude Code为例）MonkeyPlanner提供了一个超级方便的CLI工具来自动化配置。首先，你需要进入容器内部执行命令：

docker exec -it monkey-planner ./monkey-planner mcp install --for claude-code --dry-run

这个--dry-run参数会预览将要写入的配置内容，而不会实际修改文件。确认无误后，去掉--dry-run执行：

docker exec -it monkey-planner ./monkey-planner mcp install --for claude-code

这条命令会在容器内当前工作目录生成一个.mcp.json配置文件。但我们需要让宿主机上的Claude Code读到这个配置。更实用的方法是，我们直接手动配置。

步骤4：手动配置MCP（更可控）在Claude Code项目根目录（或其他你希望启用MonkeyPlanner的项目目录）下，创建或编辑.mcp.json文件：

{ "mcpServers": { "monkey-planner": { "command": "docker", "args": ["exec", "monkey-planner", "./monkey-planner", "mcp"], "env": { "MP_BASE_URL": "http://host.docker.internal:8080" } } } }

关键解释：

• command: 不再是直接调用二进制，而是调用docker命令。
• args: 告诉docker在名为monkey-planner的容器内执行./monkey-planner mcp命令。
• env.MP_BASE_URL: 这里设置为http://host.docker.internal:8080。这是一个Docker提供的特殊域名，指向宿主机的本地网络。因为MCP服务（在容器内）需要能访问到MonkeyPlanner的HTTP API（也在容器内，但通过宿主机的8080端口暴露）。如果遇到连接问题，可以尝试换成你宿主机的实际IP地址。

保存文件，然后完全重启Claude Code。重启后，在聊天界面，你应该能看到MonkeyPlanner的工具列表已经可用。你可以尝试让AI执行list_boards来测试连接。

3.2 方案二：从源码构建与开发

如果你想深入了解、定制功能或参与贡献，从源码构建是必经之路。

环境准备

• Go 1.26+: 确保已安装。
• Node.js 18+ & npm: 确保已安装。
• Git: 用于克隆代码。

步骤1：克隆与初始化

git clone https://github.com/kjm99d/MonkeyPlanner.git cd MonkeyPlanner make init

make init这个命令非常贴心，它会自动安装Go模块依赖、Node.js依赖，并设置Git钩子。

步骤2：开发模式运行（前后端分离）这是最常用的开发方式，前端热重载，后端代码修改后自动重启。

• 终端1 - 启动后端服务：

  make run-backend

  后端将在http://localhost:8080启动。

• 终端2 - 启动前端开发服务器：

  make run-frontend

  Vite开发服务器将在http://localhost:5173启动。它会自动将/api开头的请求代理到后端的:8080端口，解决跨域问题。此时你应该访问http://localhost:5173来使用应用。

步骤3：生产模式构建（生成单一二进制文件）当你完成开发测试，想要一个可以分发部署的版本时：

make build

这个命令会：

1. 编译前端资源，进行优化。
2. 将优化后的前端资源嵌入到Go二进制文件中。
3. 在./bin/目录下生成一个名为monkey-planner（Windows下为monkey-planner.exe）的独立可执行文件。

你可以将这个二进制文件复制到任何同架构的机器上，直接运行：

./bin/monkey-planner

它同样会在http://localhost:8080启动一个包含完整前后端的服务。

注意事项：在开发模式下，前端(:5173)和后端(:8080)是两个独立的服务。而在生产构建的二进制中，前端被嵌入，只有一个:8080服务。在配置MCP时，MP_BASE_URL环境变量需要指向实际提供API的服务地址。在开发模式下，如果你的AI客户端（如Claude Desktop）配置连接的是前端开发服务器(:5173)，由于代理存在，通常也能工作。但在生产部署或Docker中，务必确保MP_BASE_URL指向正确的后端API地址。

4. 深度使用指南：从看板管理到自动化集成

系统跑起来了，接下来我们看看如何把它用到极致。MonkeyPlanner的功能远比一个简单的待办清单丰富。

4.1 看板与任务管理：打造你的项目指挥中心

创建与定制看板进入Web界面，侧边栏有“创建看板”的入口。你可以为不同项目、不同类型的工作创建独立看板，例如：“产品Backlog”、“本周Sprint”、“Bug追踪”、“技术债”。 每个看板都可以定义自定义属性。这是将看板模板化的关键。例如，在“Bug追踪”看板中，我通常会添加：

• 严重程度(类型：Select， 选项：Critical, High, Medium, Low)
• 重现步骤(类型：Text， 长文本)
• 影响版本(类型：Text)
• 修复分支(类型：Text)

在创建或编辑任务时，这些属性字段就会显示出来，让你和AI都能结构化地记录信息。

任务创建与AI指令编写创建任务时，除了标题和Markdown正文，请务必重视“Agent Instructions”字段。这是AI的行动指南。写得越清晰，AI执行得越准确。我的经验是采用“上下文+具体操作+验收点”的结构：

**上下文**：用户报告在移动设备上，商品详情页的“加入购物车”按钮点击无效。 **相关文件**：`src/components/ProductDetail/MobileActionBar.tsx`, `src/hooks/useCart.ts` **具体操作**： 1. 检查`MobileActionBar.tsx`中按钮的`onClick`事件处理函数是否被正确绑定。 2. 检查`useCart`钩子中的`addToCart`函数在移动端是否有异步或条件判断错误。 3. 使用Chrome开发者工具的移动设备模拟器进行测试。 **验收点**： - [ ] 在iOS Safari和Android Chrome模拟器上点击测试通过。 - [ ] 控制台无错误日志。 - [ ] 成功调用`addToCart` API。

将“验收点”复制到“Success Criteria”检查列表中。这样，AI在完成任务时，可以逐一勾选，你也一目了然。

看板视图与全局搜索MonkeyPlanner提供了看板（Kanban）和表格（Table）两种视图。在看板视图中，你可以通过拖拽来改变任务状态，非常直观。全局搜索（Cmd+K）可以瞬间在所有看板和任务中查找内容，结合状态、看板等过滤器，找东西效率极高。

4.2 MCP工具实战：让AI成为你的高效副驾

MCP是MonkeyPlanner的灵魂。配置成功后，你的AI助手就获得了13种“超能力”。下面通过几个真实场景来演示：

场景一：日常任务巡检与认领你早上开工，可以让AI帮你看看有哪些已批准(Approved)的任务适合开始。

你：列出“本周Sprint”看板里所有状态是“Approved”的任务。 AI：调用`list_issues(boardId="本周Sprint的ID", status="approved")`，返回任务列表。 你：把那个“优化用户登录API响应时间”的任务认领了，开始做吧。 AI：调用`claim_issue(issueId="任务ID")`，任务状态变为`InProgress`。然后AI开始分析代码，执行优化。

场景二：处理突发Bug测试报告了一个新Bug。

你：在“Bug追踪”看板创建一个新任务。标题是“支付页面在Safari浏览器提交后无响应”。正文描述一下现象。Instructions里写：优先检查`payment.js`中Safari特有的API兼容性问题，特别是`Promise`和`fetch`的使用。成功标准是：在Safari 16+上测试通过，且控制台无错误。 AI：调用`create_issue(...)`，创建任务，状态为`Pending`。 你：（在Web界面快速浏览后点击“批准”） AI：检测到任务被批准（或你直接告诉AI去批准），调用`approve_issue(issueId)`。 AI：接着调用`claim_issue(issueId)`，开始排查和修复。

场景三：任务协作与进度更新AI在修复一个复杂功能时遇到了疑问。

AI：调用`add_comment(issueId, “我在`utils/validator.js`第45行发现一个模糊的类型检查，这里的`input`参数可能为`null`，但函数内部没有处理。原逻辑是直接`input.trim()`，这是潜在崩溃点。我打算添加空值检查，你同意吗？”)` 你：（在Web界面看到评论）回复评论：“同意。另外，请一并检查调用这个函数的所有地方，确保传入参数不为空。” AI：读取新评论，继续工作。完成后，调用`submit_qa(issueId, comment=“已修复，添加了空值检查，并审计了3处调用点，均已处理。提交哈希：a1b2c3d。”)`

场景四：基于成功标准的验收AI完成任务后，你进行QA。

你：查看任务，发现AI已经勾选了“所有单元测试通过”和“代码已提交”两个成功标准，但“更新API文档”这一项没勾。 你：调用`reject_issue(issueId, reason=“功能实现很好，但API文档没有同步更新，请补充。”)` AI：任务状态变回`InProgress`。AI读取拒绝原因，去更新文档，然后再次`submit_qa`，并勾选上“更新API文档”标准。 你：验收通过，点击“完成”或让AI调用`complete_issue`。

实操心得：不要一次性让AI处理太多create_issue、approve_issue、claim_issue的连续操作。最好分步进行，每一步都确认结果。特别是approve_issue，这是重要的人工决策点，务必在UI上或通过仔细阅读AI的总结后再批准。另外，善用search_issues工具，让AI帮你从海量任务中快速定位信息，比如“搜索所有包含‘内存泄漏’关键词且状态为InProgress的任务”。

4.3 高级功能与集成

实时同步（SSE）这是MonkeyPlanner一个非常棒的体验细节。当你在一个浏览器标签页中打开看板，然后在另一个终端或通过AI客户端修改了任务（比如批准、添加评论），当前页面会自动、实时地更新，无需手动刷新。这是通过Server-Sent Events实现的，让人机协作的感觉非常流畅。

Webhook自动化通知你可以为看板配置Webhook，当任务创建、批准、状态变更、删除或有新评论时，自动通知到你的团队沟通工具。

1. 进入看板设置，找到“Webhooks”选项。
2. 添加一个新的Webhook，选择事件类型（如issue.created,issue.approved）。
3. 填入Discord/Slack/Telegram的Incoming Webhook URL。
4. 保存后，每当对应事件发生，你的团队频道就会收到一条格式化的消息，包含任务标题、链接和关键信息。

数据导出所有数据都掌握在你手中。通过GET /api/issues?format=jsonAPI（或未来可能增加的UI导出功能），你可以将全部任务数据以JSON格式导出，用于备份、分析或迁移。

多语言与主题Web界面支持英语、韩语、日语和中文，可以在设置中切换。同时支持亮色/暗色主题，保护你的眼睛。

5. 常见问题排查与性能调优

即使设计得再完善，在实际使用中也可能遇到一些小问题。这里我总结了一些常见的情况和解决方法。

5.1 MCP连接失败

这是最常遇到的问题，表现为AI客户端无法调用MonkeyPlanner的工具。

诊断命令： 在配置MCP时，使用--dry-run预览配置，并使用get_version工具进行连通性测试，这是一个轻量级的调用。

# 使用CLI工具测试MCP服务器本身 ./monkey-planner mcp --help

5.2 数据库与性能

5.3 工作流与使用技巧

5.4 自定义与扩展

MonkeyPlanner是MIT协议的开源项目，这意味着你可以自由地修改和扩展它。

• 修改前端界面：前端基于React + TypeScript + Tailwind CSS，结构清晰。如果你想调整看板样式、添加新的任务属性类型，可以修改frontend/src/features/board和frontend/src/components下的相关组件。
• 添加新的API端点：后端是Go语言，路由定义在backend/internal/http/router.go中，业务逻辑在backend/internal/service。例如，如果你想添加一个批量归档已完成任务的端点，可以在这里添加。
• 集成其他工具：你可以利用Webhook功能，将任务事件推送到更多自定义系统。也可以编写脚本，定期调用MonkeyPlanner的JSON导出API，将数据同步到你的BI系统或知识库。

我个人在使用几个月后，最大的体会是，它成功地将原本碎片化、易丢失的“AI任务指令”和“协作上下文”固化到了一个结构化的系统中。它没有引入复杂的概念，而是巧妙地利用了“看板”这一开发者熟悉的形式，在人和AI之间架起了一座稳固的桥梁。当你习惯了让AI去list_issues、claim_issue，并通过add_comment进行异步沟通后，你会发现这种协作模式不仅高效，而且可追溯，极大地提升了复杂项目中人机协作的可靠性和愉悦感。