Markplane：基于文件的项目管理系统，让AI助手成为你的项目合伙人

1. 项目概述：当AI成为你的项目合伙人

如果你和我一样，每天都在和AI编码助手（比如Claude Code、Cursor）并肩作战，那你一定经历过这种“甜蜜的烦恼”：AI写代码又快又好，但它对你的项目整体状况却一无所知。你让它“修复登录页面的bug”，它能立刻生成一段漂亮的代码，但它不知道这个bug属于哪个史诗级任务（Epic），优先级是高还是低，是否被其他任务阻塞，甚至不知道这个项目最终要达成什么目标。你的项目数据——那些任务、计划、依赖关系——都被锁在Jira、Linear、Notion这些SaaS工具里，它们活在浏览器标签页里，活在另一个“上下文”里，唯独不在你的代码仓库里，不在你和AI对话的“当下”。

这就是Markplane要解决的核心痛点。它不是一个传统的项目管理工具，而是一个为AI协作而生的、基于文件的项目管理系统。它的设计哲学极其简单，也极其深刻：一切项目数据，都以Markdown文件的形式，存放在你的Git仓库里。任务（Task）、史诗（Epic）、计划（Plan）、笔记（Note），每一个都是一个.md文件，附带结构化的YAML元数据。然后，Markplane会自动生成一个名为.context/的目录，里面是经过高度压缩、为AI大模型上下文窗口优化的项目状态摘要。

这意味着什么？意味着你的AI助手不再是一个“盲人码农”。它可以通过MCP协议，直接读取.context/里的摘要，瞬间理解项目的全貌：哪些任务在进行中，哪个史诗完成了60%，哪些项目被阻塞了。你可以直接用自然语言指挥它：“给登录重定向的bug创建一个高优先级任务，关联到‘用户认证系统重构’这个史诗上。” 它不仅能听懂，还能立刻执行，并在你的仓库里生成对应的文件。第二天你打开编辑器，AI助手能无缝衔接昨天的工作，因为它“记得”整个项目的状态，这些状态就版本化地保存在你刚刚git pull下来的代码里。

2. 核心设计理念：为什么是“文件即数据库”？

2.1 告别SaaS，拥抱Git工作流

传统的SaaS项目管理工具带来了几个根深蒂固的问题：

1. 上下文割裂：你和AI的对话在一个地方（编辑器），项目数据在另一个地方（浏览器）。频繁切换不仅低效，更破坏了思维的连续性。
2. 数据孤岛：项目历史和代码历史是分离的。你想知道“为什么三周前决定把这个任务标记为阻塞”？你得去翻Jira的评论，而不是看git log。
3. 供应商锁定与迁移成本：你的项目数据受制于某个服务商。导出数据往往是一团乱麻的CSV或JSON，失去了原有的结构和关联。

Markplane的“文件即数据库”理念，是对上述问题的彻底反击。它将所有项目实体都视为代码库的一部分：

• 版本控制：git add,git commit,git push。你的项目状态变更和代码变更拥有完全一致的历史记录。你可以用git blame查看是谁在什么时候修改了任务状态，用git diff查看两次提交之间项目计划的变化。
• 无锁定：你的数据就是一堆文本文件。你可以用任何文本编辑器查看、编辑。即使Markplane这个工具消失了，你的项目数据依然完整、可读。
• 工具链集成：你可以用grep搜索所有包含“登录”关键词的任务，用find命令定位所有状态为“阻塞”的文件，用你喜欢的IDE全局搜索和重构项目文档。项目管理彻底融入了开发者的原生工作流。

2.2 AI-Native：为上下文窗口而设计

“AI-Native”是Markplane的另一个核心标签，这绝非噱头。大语言模型有上下文窗口限制，把整个项目的所有Markdown文件（可能几十上百个）都塞给AI是不现实的，Token成本高，且信息噪音大。

Markplane的解决方案是分层摘要与索引路由。它自动生成的.context/目录就是为AI量身定制的“营养浓缩餐”。

• summary.md(~1000 tokens)：项目状态的“电梯演讲”。包含进行中的史诗、进行中的工作、阻塞项、优先级队列和关键指标。这是AI快速了解项目全貌的入口。
• active-work.md(~500 tokens)：当前活跃工作的详细视图，包括依赖关系和负责人。
• INDEX.md：每个目录（如backlog/,roadmap/）都有一个索引文件，以极小的代价（约200 tokens）列出所有条目的ID和状态。AI可以先扫描索引，再按需加载具体的任务或史诗文件，实现精准的“按需读取”。

这种设计使得一个包含数十个任务的中型项目，其完整状态摘要可以轻松控制在1500-2000 tokens以内，完美适配主流AI助手的上下文。相比之下，一个庞大的、未经处理的ROADMAP.md文件很容易就超过10000 tokens。

实操心得：理解“压缩”的本质这里的“压缩”不是指文件体积，而是信息密度的压缩。它去掉了Markdown中的格式标记、冗余描述，只提炼出AI决策所需的核心结构化信息：ID、标题、状态、优先级、依赖关系。这要求我们在编写任务描述时也要有意识地为AI优化：前一两句点明核心，关键信息用列表或加粗突出。

3. 从零开始：安装与初始化实战

3.1 选择你的安装方式

Markplane提供了多种安装方式，推荐根据你的平台和习惯选择。

对于macOS/Linux用户，Homebrew是最佳选择：

brew install zerowand01/markplane/markplane

一行命令，自动完成下载、校验和安装，并且便于后续更新。

如果你没有Homebrew，或者需要自定义安装路径，可以使用安装脚本：

curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | sh

这个脚本默认安装到~/.local/bin/。你可以通过环境变量控制：

# 安装到系统目录（需要sudo权限） curl -fsSL https://raw.githubusercontent.com/zerowand01/markplane/master/install.sh | INSTALL_DIR=/usr/local/bin sh

对于Windows用户：直接从GitHub Releases页面下载对应的markplane-v*-x86_64-pc-windows-msvc.zip文件，解压后将markplane.exe放置在任何在PATH环境变量中的目录，例如%USERPROFILE%\bin或C:\Tools。

注意事项：macOS Gatekeeper问题如果你在macOS上手动下载了二进制文件，首次运行时可能会被系统阻止，提示“无法打开，因为无法验证开发者”。这是因为苹果的Gatekeeper安全机制。解决方法有两个：

1. 推荐：使用上述的安装脚本或Homebrew安装，它们会处理好签名问题。
2. 临时解决：在终端中，进入二进制所在目录，执行：xattr -d com.apple.quarantine markplane。这条命令会移除文件的“隔离”属性。

安装完成后，在终端输入markplane --version，如果显示版本号，则说明安装成功。

3.2 初始化你的第一个Markplane项目

进入你的项目根目录（即你的Git仓库根目录），执行初始化命令：

cd /path/to/your/project markplane init --name "我的AI协作项目"

这条命令会在当前目录下创建一个隐藏的.markplane/文件夹，其结构如下：

.markplane/ ├── config.yaml # 项目配置文件（工作流、状态等） ├── INDEX.md # 项目总览导航页 ├── roadmap/ # 存放史诗（Epic）文件，如 EPIC-xxxxx.md ├── backlog/ # 存放任务（Task）文件，如 TASK-xxxxx.md ├── plans/ # 存放实施计划（Plan）文件，如 PLAN-xxxxx.md ├── notes/ # 存放笔记（Note）文件，如 NOTE-xxxxx.md ├── templates/ # 各类文件的模板 └── .context/ # 【核心】AI优化的上下文摘要目录（自动生成）

同时，它会创建一些示例文件，帮助你快速理解各个部分。如果你希望从一个完全空白的项目开始，可以使用--empty参数：markplane init --name "My Project" --empty。

关键文件解析：config.yaml这个文件是Markplane项目的大脑。初始化后，建议你立即打开它进行浏览。其中最重要的部分是workflows，它定义了任务（Task）的状态流转。默认配置如下：

workflows: task: draft: [backlog] backlog: [planned, cancelled] planned: [in-progress, backlog, cancelled] in-progress: [done, planned, cancelled] done: [archived] cancelled: [archived]

这定义了一个标准的任务生命周期：草稿 -> 待办列表 -> 已计划 -> 进行中 -> 完成。你可以在这里添加自定义状态，比如in-review（评审中）或in-qa（测试中），只需将它们放入合适的分类下（如in-review可以放在planned和in-progress之间）。

4. 核心工作流：CLI、Web UI与AI助手的三角协同

Markplane提供了三种交互界面，它们数据实时同步，你可以根据场景自由切换。

4.1 命令行界面：效率至上

CLI是进行快速操作和脚本化管理的利器。以下是一些高频命令：

创建与管理任务：

# 创建一个高优先级的Bug任务，并打上标签 markplane add "修复登录页面在Safari下的CSS错位问题" --type bug --priority high --tags frontend,css # 列出所有任务，默认按创建时间倒序 markplane ls # 使用过滤器：只看高优先级和严重优先级的任务 markplane ls --priority high,critical # 查看特定任务的详细信息 markplane show TASK-abcd1234 # 开始处理一个任务 markplane start TASK-abcd1234 # 标记一个任务为完成 markplane done TASK-abcd1234

项目概览与维护：

# 在终端中打开一个简单的项目仪表板 markplane dashboard # 手动触发重新生成 .context/ 摘要和 INDEX.md 文件（通常在文件被手动修改后执行） markplane sync # 检查所有跨文件引用（如 [[TASK-xxxx]]）是否有效 markplane check

实操技巧：善用--output格式markplane ls命令支持--output json或--output yaml参数，这在与脚本或其他工具集成时非常有用。例如，你可以用markplane ls --status in-progress --output json | jq '.[].title'来快速获取所有进行中任务的标题列表。

4.2 Web UI：可视化与全局视图

虽然CLI高效，但人类是视觉动物。启动Web UI能给你更直观的项目感受：

markplane serve --open

执行后，你的默认浏览器会自动打开http://localhost:4200。

Web UI提供了几个关键视图：

1. 看板视图：基于任务状态的可视化面板，拖拽即可改变任务状态。
2. 列表视图：所有项目的表格，支持排序和过滤。
3. 依赖关系图：图形化展示任务、史诗、计划之间的blocks（阻塞）和depends_on（依赖）关系，一眼看清项目瓶颈。
4. Markdown渲染：直接以美观的格式预览任务或史诗的详细描述。

Web UI通过WebSocket与后端实时通信。这意味着，无论你是在终端用CLI修改了状态，还是AI助手通过MCP创建了新任务，Web UI的界面都会在瞬间更新，无需手动刷新。

4.3 AI集成：通过MCP赋予AI“管理权”

这是Markplane的“杀手级”功能。MCP是一个让AI助手安全、结构化地访问工具和数据的协议。Markplane内置了一个MCP服务器。

连接AI助手（以Claude Code为例）：

方式一：用户级配置（仅影响你本机）

claude mcp add --transport stdio markplane -- markplane mcp

这条命令会告诉Claude Code：“当你运行时，启动一个markplane mcp进程，并通过标准输入输出与我通信。”

方式二：项目级配置（推荐，团队共享）在你的项目根目录创建一个.mcp.json文件：

{ "mcpServers": { "markplane": { "command": "markplane", "args": ["mcp"] } } }

这样，任何克隆了这个仓库并在Claude Code中打开它的开发者，都会自动获得Markplane的集成能力，无需额外配置。

连接后的魔法：配置成功后，你就可以在Claude Code的对话中直接使用自然语言管理项目了：

• “查看一下当前有哪些高优先级的任务？”
• “创建一个关于优化数据库查询的任务，把它关联到‘性能提升’这个史诗，并标记为中等工作量。”
• “TASK-xyz这个任务已经完成了，请把它标记为完成。”
• “显示所有被‘用户认证迁移’这个任务阻塞的任务。”

AI助手会调用Markplane提供的MCP工具来执行这些操作，并在对话中给你反馈。它不再是只能写代码的“工人”，而是成为了能理解项目上下文并参与管理的“合伙人”。

5. 文件结构与数据模型深度解析

理解Markplane如何在磁盘上组织数据，是高效使用和自定义它的关键。

5.1 实体类型与文件命名

Markplane管理四种核心实体，每种对应一个目录和特定的文件命名规则：

ID生成规则：ID是一个简短的、唯一的字符串（如fq2x8），由工具自动生成，保证了在项目内的唯一性，便于引用。

5.2 文件解剖：YAML Frontmatter + Markdown Body

每一个实体文件都是一个标准的Markdown文件，但在文件开头有一个YAML格式的“前言”（Frontmatter），用于存储结构化数据。

一个典型的TASK-xxxx.md文件内容如下：

--- id: TASK-fq2x8 title: 修复登录页面在Safari下的CSS错位问题 status: in-progress priority: high type: bug effort: S tags: [frontend, css] assignee: alice created: 2023-10-27T08:30:00Z updated: 2023-10-28T14:15:00Z blocks: [] depends_on: [TASK-a1b2c3] related: [EPIC-xyz789] --- # 问题描述 在Safari 16+浏览器上，登录页面的提交按钮与输入框存在约5px的垂直错位，导致视觉不一致。 # 复现步骤 1. 使用Safari浏览器打开登录页。 2. 观察“登录”按钮与上方密码输入框的对齐情况。 # 根本原因分析 经检查，是使用了`flexbox`布局中`align-items: center`与Safari对`button`元素的默认`line-height`处理存在差异。 # 解决方案 将包含按钮的容器的CSS从 `align-items: center` 改为 `align-items: flex-start`，并微调按钮的`margin-top`。

• YAML部分 (---之间)：定义了任务的元数据。这些字段是Markplane系统识别和处理任务的依据。你可以通过config.yaml自定义这些字段。
• Markdown部分：自由格式的内容区，用于详细描述问题、方案、讨论等。这是你和AI助手进行深度协作的空间。

5.3 强大的引用系统

Markplane支持类似Wiki的跨文件引用，这是构建项目知识图谱的基础。

• 链接引用：在Markdown正文中，使用双括号[[TASK-fq2x8]]或[[EPIC-xyz789]]来链接到其他实体。Web UI和生成的摘要会自动将这些转换为可点击的链接。
• 关系字段：
  • depends_on: 表示此任务依赖于哪些其他任务。只有依赖的任务完成后，此任务才能开始。
  • blocks: 表示此任务阻塞了哪些其他任务。此任务不完成，被阻塞的任务就无法进行。
  • related: 表示与此任务相关的其他实体（任务、史诗、计划、笔记），是一种双向的、非阻塞的关联。

注意事项：引用完整性检查手动编辑文件时，很容易打错ID。务必定期运行markplane check命令。它会扫描所有文件，检查[[...]]链接和depends_on/blocks/related字段中的ID是否存在，并报告所有无效的引用，确保项目数据的一致性。

6. 高级配置与定制化

6.1 自定义任务状态工作流

默认的任务状态流转可能不符合你的团队习惯。假设你的团队有“代码评审”和“测试”环节，你可以这样修改config.yaml：

workflows: task: draft: [backlog] backlog: [planned, cancelled] planned: [in-progress, backlog, cancelled] in-progress: [in-review, planned, cancelled] # 完成开发后进入评审 in-review: [in-qa, in-progress, cancelled] # 评审通过进入测试，不通过打回开发 in-qa: [done, in-review, cancelled] # 测试通过进入完成，不通过打回评审 done: [archived] cancelled: [archived]

修改后，Web UI的看板列和CLI/API中可用的状态转移选项都会随之更新。

6.2 自定义字段与模板

你可以在config.yaml的fields部分为不同实体类型添加自定义字段。例如，为任务添加一个“预估工时”字段：

fields: task: - name: estimated_hours type: number label: 预估工时 (小时) description: 完成此任务预计需要的小时数

然后，你可以在templates/task.md中修改默认模板，加入这个字段：

--- id: TASK-${id} title: ${title} status: draft # ... 其他默认字段 ... estimated_hours: 0 ---

这样，每次通过markplane add或Web UI创建新任务时，都会包含这个estimated_hours字段。

7. 实战场景：一个功能开发的完整AI协作周期

让我们通过一个虚构的“为用户个人资料页添加暗黑模式支持”功能，来体验Markplane与AI协作的全流程。

第1步：创建史诗（战略规划）你在Web UI或通过CLI创建了一个史诗：

markplane add "实现用户界面暗黑模式" --type epic --status next

这会在roadmap/目录下生成EPIC-abc123.md文件。你打开文件，在Markdown部分详细描述了背景、目标、验收标准。

第2步：AI辅助任务拆解你打开AI助手（已连接MCP）说：“基于‘实现用户界面暗黑模式’这个史诗，帮我拆解出第一批需要完成的具体任务，优先级设为中等。” AI助手会读取EPIC-abc123.md和.context/summary.md，理解需求，然后调用MCP工具创建一系列任务，例如：

• TASK-def456: 【前端】设计并实现全局CSS暗黑模式变量体系
• TASK-ghi789: 【前端】改造导航栏组件支持主题切换
• TASK-jkl012: 【后端】在用户配置中增加主题偏好字段
• TASK-mno345: 【前端】实现用户设置中的主题切换开关 AI会自动为这些任务添加related: [EPIC-abc123]的关联。

第3步：日常开发与状态更新你开始处理TASK-def456。在编码过程中，你发现需要先确定一套颜色规范。于是你通过AI助手创建了一个笔记：“暗黑模式颜色规范讨论”，并关联到该任务。你和AI在对话中确定了色板，AI将讨论要点更新到笔记中。 完成后，你通过CLI更新状态：markplane done TASK-def456。或者，你直接在Web UI上看板视图里把它拖到“Done”列。

第4步：处理阻塞与依赖在实现TASK-ghi789（导航栏）时，你发现它依赖于TASK-def456（CSS变量体系）的完成。你通过AI助手设置依赖关系：“将任务TASK-ghi789的depends_on字段设置为TASK-def456。” 此时，在依赖关系图中，TASK-def456会指向TASK-ghi789。Web UI和.context/blocked-items.md摘要中也会显示TASK-ghi789正处于等待状态。

第5步：每日站会与同步每天早晨，你问AI助手：“今天有哪些优先级高的任务可以处理？” AI读取.context/summary.md，发现TASK-def456已完成，TASK-ghi789的依赖已解除，于是将其推荐给你。整个团队无需开会，即可通过AI同步项目状态。

第6步：归档与总结当整个史诗的所有任务都完成后，你将史诗状态标记为done。一段时间后，运行markplane archive --all-completed，所有状态为done的任务、计划、笔记都会被移动到archive/目录下，保持项目主目录的整洁，但历史记录仍可通过Git追溯。

8. 常见问题与故障排查

Q1: 运行markplane serve后，浏览器无法访问localhost:4200。

• 检查端口占用：可能是4200端口被其他程序占用。你可以用markplane serve --port 8080指定另一个端口。
• 检查防火墙：确保本地防火墙没有阻止该端口的访问。
• 查看日志：运行markplane serve --log-level debug查看更详细的输出，定位错误。

Q2: AI助手（如Claude Code）无法识别Markplane的MCP工具。

• 确认配置：检查你的.mcp.json文件是否在项目根目录，且格式正确。对于用户级配置，运行claude mcp list查看是否已成功添加。
• 重启AI助手：添加MCP服务器后，通常需要重启Claude Code或你的编辑器才能生效。
• 检查命令路径：确保markplane命令在系统的PATH环境变量中。可以在终端直接输入markplane mcp看是否能正常运行。

Q3: 手动修改了.md文件后，Web UI没有实时更新。

• 手动触发同步：WebSocket监听可能偶尔失效。运行markplane sync命令可以强制重新生成索引和上下文摘要，并刷新Web UI的数据。
• 检查文件语法：如果YAML frontmatter格式错误（如缩进不对、冒号后没空格），Markplane可能无法正确解析该文件，导致更新失败。运行markplane check可以帮你找出语法错误。

Q4:.context/目录下的文件内容看起来不完整或过时。

• .context/目录是只读的、自动生成的。你不应该手动编辑其中的文件。
• 它的生成逻辑是基于其他目录的实体文件进行摘要。如果内容过时，请确保你的实体文件（backlog/,roadmap/下的文件）本身是最新的，然后运行markplane sync。
• 摘要的压缩算法会优先保留结构化信息（状态、优先级、标题、依赖关系），而大幅简化Markdown正文内容。这是为了节省Token，是正常现象。

Q5: 如何将现有项目（如Jira导出数据）迁移到Markplane？Markplane目前没有提供一键迁移工具，因为其文件结构非常直接，手动或编写脚本迁移是可行方案。

1. 从旧工具导出数据（通常是CSV或JSON格式）。
2. 编写一个转换脚本（可以用Python、Node.js等），读取导出文件。
3. 脚本逻辑：为每个任务/史诗生成一个Markdown文件，将标题、描述、状态、优先级等信息分别填入YAML frontmatter和Markdown body。ID可以沿用旧ID或生成新的。
4. 将生成的文件批量放入对应的backlog/或roadmap/目录。
5. 运行markplane sync生成上下文摘要。 这个过程虽然有些工作量，但一旦完成，你就永久拥有了完全可控、可版本化的项目数据。

我个人在几个项目中全面转向Markplane后，最深的体会是它带来了一种“宁静”的开发体验。项目管理的噪音被降到了最低——没有多余的网页需要打开，没有复杂的表单需要填写。所有信息都在我触手可及的地方：在终端里、在编辑器侧边栏、在我和AI的对话中。当项目上下文与代码上下文真正统一后，那种流畅感是传统工具无法比拟的。它可能不适合需要复杂权限管理和严格流程控制的大型企业团队，但对于追求效率、热爱自动化的独立开发者或小型技术团队而言，Markplane无疑是将项目管理融入开发者工作流的终极形态。