1. 项目概述用结构化反馈驯服你的AI编码助手如果你和我一样已经深度使用Claude Code、Cursor或者GitHub Copilot这类AI编码助手超过半年那你肯定经历过这种场景你花半小时写了一份详细的Markdown实现计划从架构设计到API接口定义都列得清清楚楚然后满怀期待地把这个计划丢给AI让它开始干活。结果呢AI要么完全无视你计划里的关键约束自己“放飞自我”写了一堆不符合预期的代码要么就是它确实按计划写了但你在它写到一半时突然发现计划里有个致命的逻辑漏洞这时候你只能尴尬地打断它“等等这里不对我们得重来”。整个沟通过程充满了不确定性。你得像猜谜一样去理解AI到底有没有读懂你的意图或者得在聊天窗口里打一大堆“这里要改”、“那里注意”的指令这些指令散落在聊天历史里下次重启会话时上下文又丢了。这种体验就像和一个听力时好时坏的远程同事协作效率低下且让人心累。MD Feedback就是为了解决这个核心痛点而生的。它不是一个花哨的AI玩具而是一个极其务实的“人机协作协议”工具。它的核心思想很简单把人类和AI的协作锚定在一个可版本控制、可结构化评审的Markdown文件上。你作为人类只负责在Markdown计划里用三种简单的标记高亮、修复、提问指出“哪里有问题”和“哪里需要关注”AI则通过标准的MCP协议读取这些结构化指令负责思考“如何解决”并汇报执行结果。所有状态——哪些问题待处理、哪些已完成、哪些被驳回——都直接保存在Markdown文件本身的HTML注释里跟着Git走永不丢失。简单说它把原本模糊、易失的AI聊天指令变成了清晰、持久、可追踪的工单系统。你从“在聊天框里和AI讨价还价”的模式切换到了“在代码仓库里给AI派发和验收任务”的模式。这个转变对于追求确定性和工程效率的开发者来说是革命性的。2. 核心设计哲学与工作流拆解2.1 为什么是“人类指问题AI想方案”MD Feedback的设计哲学第一条就是Humans only state what is wrong. AI decides how to fix it.这背后有深刻的工程心理学考量。在传统的AI编码交互中人类很容易陷入“微观管理”的陷阱。比如你发现一个函数名取得不好你可能会对AI说“把calculateUserData改成computeUserStats然后在第45行加上错误处理用try-catch包起来日志要打ERROR级别……” 你不仅在指出问题还在规定解决方案的每一个细节。这有两个坏处第一你的认知负荷很高需要思考具体怎么做第二你限制了AI的创造力它可能有一个更优雅的解法但因为你规定了细节它只能照办。MD Feedback通过强制分离“问题描述”和“解决方案”把人类解放了出来。你只需要选中那段有问题的文本按下快捷键2打上一个[Fix]标签脑子里想的是“这里的数据处理逻辑不健壮”。至于AI是通过重构函数、增加校验还是引入重试机制来解决那是它的事。它需要为它的方案负责并在实现后向你汇报。你从“监工”变成了“产品经理”只验收结果不干预过程。这种协作模式更接近高效的人类团队协作。2.2 三色标签系统为何三种注释就足够工具只提供了三种注释类型Highlight黄色高亮、Fix红色修复、Question蓝色提问。看起来简单甚至有些简陋但这恰恰是经过深思熟虑的。Highlight代表“这里很重要请注意”。它不要求行动只起到阅读标记和引起注意的作用。比如你在计划中标注了核心算法部分AI在实现时会格外关注这里。Fix代表“这里有错误或不完善需要修改”。这是最核心的指令要求AI采取行动。AI必须分析上下文提出修改方案执行并标记为完成。Question代表“这里我不确定需要澄清”。这可能是关于需求模糊也可能是对AI生成计划部分的质疑。AI需要解答疑问或与你讨论以达成一致。为什么不是五种、十种因为过多的标签会导致决策疲劳。“这里到底算‘优化’还是‘重构’” MD Feedback认为AI足够智能可以从Fix的上下文是在描述业务逻辑还是代码风格中推断出你的真实意图。三种基础标签配合自然语言描述已经能覆盖99%的评审场景。这种极简设计降低了使用门槛让工具保持锋利。2.3 完整工作流闭环从计划到交付MD Feedback构建了一个完整的、可循环的AI协作工作流下图清晰地展示了这个从人类计划到AI执行再到人类评审的闭环过程[ 人类领域 ] ┌─────────┐ │ 步骤1 │ │ 撰写计划│ └────┬────┘ │ ┌────▼────┐ │ 步骤2 │ │ 评审标注│◄───┐ └────┬────┘ │ │ │ [ 协议桥梁 ] │ ┌────▼────┐ │ │ MCP │ │ │ 协议 │ │ └────┬────┘ │ │ │ [ AI代理领域 ] │ ┌────▼────┐ │ │ 步骤3 │ │ │ 读取指令│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤4 │ │ │ 执行变更│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤5 │ │ │ 质量门禁│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤6 │ │ │ 生成报告│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤7 │ │ │ 人类评审│────┘ └────┬────┘ │ ┌────▼────┐ │ 批准/驳回│ └─────────┘ │ ┌────▼────┐ │ 完成或迭代│ └─────────┘阶段一人类规划与评审步骤1-2你首先在Markdown文件中编写详细的项目计划或设计文档。然后你像代码评审一样审视这份计划使用MD Feedback的侧边栏或快捷键1/2/3在需要关注的文本上添加Highlight、Fix或Question注释。例如在一个API设计段落旁你可能会添加一个[Fix] 需要增加分页参数的注释。阶段二AI代理执行步骤3-4当你启动一个支持MCP协议的AI助手如配置了MD Feedback的Claude Desktop时神奇的事情发生了。AI助手直接读取到这些嵌入在文件中的结构化注释就像读取一个任务列表。它理解每个Fix都需要一个解决方案每个Question都需要一个回答。然后它开始自主工作修改代码、更新文档、回答问题并将每个动作的结果例如代码差异报告回来。阶段三自动化质量门禁步骤5MD Feedback引入了“质量门禁”的概念。你可以定义一些通过条件例如“所有Fix类注释必须被标记为Done”。AI在完成任务后会自动评估这些门禁。状态会从“阻塞”有未完成的修复变为“进行中”最后变为“通过”。这为AI的工作设立了明确的完成标准避免了“好像做完了又好像没做完”的模糊状态。阶段四人类验收与上下文传递步骤6-7AI完成一批更改后会生成一份“交接报告”并通知你进行评审。你在编辑器中可以看到清晰的代码对比然后点击“批准”或“请求修改”。更重要的是所有评审状态、开放的讨论、已完成的决策都通过HTML注释保存在Markdown文件中。这意味着即使你关掉电脑第二天换一个AI会话只要打开同一个文件所有的上下文都完整无缺。AI可以立刻接着上次中断的地方继续工作。这个闭环将一次性的、脆弱的AI聊天变成了一个可暂停、可恢复、可审计的持久化协作流程。3. 核心功能深度解析与实操要点3.1 注释系统不仅仅是标记MD Feedback的注释在底层被存储为HTML注释例如!-- [Fix]: 这里的错误处理需要加强 --。这种设计带来了几个关键优势绝对的可移植性任何能渲染Markdown的工具GitHub、GitLab、VS Code预览、Typora都会忽略HTML注释因此你的文档在任何地方看起来都是干净的。但MD Feedback或任何能解析它的工具却能读取其中的丰富信息。完美的版本控制兼容性注释作为文件内容的一部分会随着你的每一次git commit被完整记录。你可以清晰地看到在某个时间点项目存在哪些待解决的问题。这对于团队协作和项目审计至关重要。丰富的状态机每个注释不仅有类型还有状态Open, Working, Review, Answered, Done, Failed, Won‘t Fix。这个状态由AI和你的互动来驱动。AI开始处理一个Fix时会将其置为Working完成修改后置为Review等待你批准你批准后变为Done。这个状态流使得任务追踪一目了然。实操技巧高效使用快捷键安装扩展后最快的上手方式就是记住三个数字键1(高亮),2(修复),3(提问)。在编辑器中选中文本后直接按键注释瞬间生成无需鼠标点选侧边栏。这是将评审思维“流式化”的关键让你的反馈几乎不打断写作或阅读的心流。3.2 MCP集成无缝的AI通信管道MCP是MD Feedback的灵魂。没有它你就需要手动“导出”注释到某个文件然后复制粘贴给AI流程是割裂的。有了MCPAI助手就变成了一个直接连接到你项目“任务系统”的智能工人。配置详解以Claude Desktop为例在你的用户配置目录如~/.config/claude/下找到或创建mcp.json文件。添加以下配置{ mcpServers: { md-feedback: { command: npx, args: [-y, md-feedback] } } }重启Claude Desktop后你的AI助手就获得了读取和处理MD Feedback注释的能力。当它分析你的项目时它会主动发现这些注释并询问你是否要处理它们。这个过程是完全自动化的。注意工作空间路径问题某些MCP客户端如一些较老的集成方式可能无法正确识别当前工作目录。如果你的AI助手找不到注释你可能需要显式指定工作空间路径{ command: npx, args: [-y, md-feedback, --workspace/absolute/path/to/your/project] }在Windows上注意使用双反斜杠或正斜杠--workspaceC:\\work\\my-project3.3 质量门禁为AI工作设定完成标准“质量门禁”是MD Feedback里一个非常工程化的概念。它允许你定义一些必须满足的条件才能认为某个阶段的工作“完成”。例如在你的“数据库迁移计划.md”中你可以设置一个门禁!-- [Gate]: 数据迁移前置检查 -- !-- [Condition]: All Fix annotations in this document are resolved -- !-- [Condition]: At least one Question about rollback plan is Answered --这个门禁告诉AI只有本文档中所有Fix都被解决并且至少有一个关于回滚计划的Question被回答后这个门禁才算通过。AI在工作的过程中会持续评估这些门禁条件。在侧边栏你会看到门禁的状态从红色的Blocked变为黄色的In Progress最后变为绿色的Passed。这为你提供了一个清晰的、自动化的进度看板。实操心得门禁的灵活运用不要只把门禁用于最终验收。我习惯在计划的不同阶段设置门禁。比如在“架构设计”部分完成后设置一个“架构评审通过”的门禁条件是所有关于架构的Question都被回答。这样AI在开始写具体代码前必须确保我们对设计达成了共识避免了后期返工。3.4 会话交接打破AI的“金鱼记忆”AI助手最大的局限之一就是会话失忆。重启一个会话之前的讨论上下文就没了。MD Feedback通过“交接报告”完美解决了这个问题。当AI完成一个阶段的工作或你手动触发时它可以生成一份交接报告。这份报告不是一个简单的文本摘要而是一个包含了所有关键决策点、未解决问题、当前门禁状态和下一步建议的结构化文档。更重要的是这份报告本身就是一个新的、包含了所有之前注释和状态的Markdown文件。工作流程示例周一晚上你评审了一个计划加了5个Fix。AI处理了3个剩下2个。你保存文件并关机。周二早上你打开新AI会话并打开这个Markdown文件。AI通过MCP立刻读取到文件状态“有2个Open状态的Fix3个Done状态的Fix门禁A是Blocked状态。”AI可以无缝地接着处理剩下的2个Fix就像从未中断过。这个特性使得与AI进行长期、复杂的项目协作成为可能。项目上下文被持久化在项目仓库中而不是锁死在某个AI服务的临时会话里。4. 高级应用场景与实战技巧4.1 场景一Vibe Coding氛围编码工作流这是MD Feedback最自然的用法。你有一个新功能或Bug修复的想法但还没想清楚所有细节。快速起草在feature-auth.md里快速列出要点“用户登录接口”、“JWT令牌生成”、“密码加密存储”。自我评审通读草案用Highlight标出核心部分“JWT密钥必须从环境变量读取”用Question标出不确定处“加密算法用bcrypt还是Argon2”。交给AI启动Claude Code它看到你的文件和注释开始提问“关于加密算法我建议使用Argon2因为它更能抵抗GPU破解这是实现代码……” 它同时会将那个Question的状态改为Answered。迭代推进你看到AI生成的代码草案发现一个问题直接在相关代码行的描述上打一个[Fix] 这里需要添加输入验证。AI接收修改并标记为Done。整个过程中你始终在“定义问题”和“验收结果”AI在“解决问题”和“汇报进展”。计划文件成了唯一的真理来源和协作日志。4.2 场景二团队设计文档评审在团队中技术方案评审常常依赖会议效率低下。MD Feedback可以改变这一点。发起评审工程师A在design-api-v2.md中撰写新API设计。异步标注工程师B、C收到PR他们不需要安排会议而是直接在文件的具体行上添加注释。工程师B加了一个[Fix] 响应格式应该遵循公司统一标准工程师C加了一个[Question] 这个端点预计的QPS是多少是否需要限流。AI整合与澄清工程师A或者一个指定的AI助手查看所有注释。对于FixAI可以直接修改设计文档对于QuestionAI可以调研后给出答案或工程师C进行讨论。所有讨论都附着在具体的设计点上。形成决议当所有Fix被处理所有Question被回答文档即被视为评审通过。这个全过程在Git历史中清晰可查。4.3 场景三复杂任务分解与追踪对于大型任务你可以利用MD Feedback创建分层的计划追踪。主计划文件project-launch.md里面不写细节只写高级阶段和门禁。# 项目启动计划 !-- [Gate]: 阶段一基础框架 -- !-- [Condition]: file:setup-infra.md Gate is Passed -- !-- [Gate]: 阶段二核心功能 -- !-- [Condition]: file:develop-core.md Gate is Passed -- !-- [Gate]: 阶段三测试部署 -- !-- [Condition]: file:test-deploy.md Gate is Passed --子计划文件每个阶段一个独立的Markdown文件如setup-infra.md里面包含具体的任务列表和Fix注释。AI分层推进AI首先查看主计划发现“阶段一”的门禁依赖于setup-infra.md文件。它打开该文件开始处理里面的具体Fix注释如“配置Dockerfile”、“初始化数据库”。完成该文件的所有任务后该文件的Gate状态变为Passed进而触发主计划中“阶段一”门禁的通过。AI随后自动进入“阶段二”。这种方法将项目管理逻辑也编码进了可被AI理解和执行的结构中实现了真正自动化的任务推进。5. 常见问题排查与配置优化5.1 MCP连接失败怎么办这是新手最常见的问题。请按以下步骤排查问题现象可能原因解决方案AI助手完全看不到注释1. MCP配置错误2.md-feedback未全局安装3. 工作空间路径不对1. 检查mcp.json格式是否正确路径是否正确特别是Windows的路径分隔符和转义。2. 在项目目录下运行npx -y md-feedback测试服务器是否能正常启动。3. 在MCP配置中尝试使用--workspace参数绝对路径。能看到注释但状态不同步VS Code扩展与MCP服务器版本不匹配确保你通过VS Code扩展商店安装的是最新版同时npm上的md-feedback包也是最新版。运行npm update -g md-feedback或使用npx总是最新。只有部分注释出现文件未被MCP服务器正确索引确保你的Markdown文件在MCP服务器启动时指定的工作空间目录或子目录下。重启AI助手和MCP服务器。一个关键技巧在VS Code中打开MD Feedback侧边栏如果它显示“Connected to MCP server”则连接正常。你也可以查看VS Code的“输出”面板选择“MD Feedback”通道查看详细的服务器日志和通信信息。5.2 如何处理大型文档的性能问题当你对一个超过1000行的、包含大量Mermaid图表和代码块的Markdown文件进行频繁注释操作时可能会感到界面略有卡顿。调整自动刷新间隔在VS Code设置中搜索md-feedback.autoRefreshDelay。默认值是100毫秒。对于超大文档可以适当增加这个值例如设为500毫秒以减少UI更新的频率。禁用实时预览在侧边栏顶部有一个“眼睛”图标用于切换注释的“内联渲染”即在文中显示彩色背景。在纯文本编辑时可以关闭此功能以提升性能。分文件管理这是最有效的办法。将大型计划按模块拆分成多个*.md文件通过主文件链接。MD Feedback可以跨文件追踪门禁状态这样每个文件体积变小操作更流畅。5.3 导出功能当MCP不可用时的备选方案虽然MCP是首选但MD Feedback也提供了强大的导出功能支持11种不同的AI工具格式。这在某些尚未支持MCP的在线平台或特定工作流中非常有用。操作流程在VS Code中完成对Markdown计划的评审和标注。在MD Feedback侧边栏底部点击“Export”按钮。选择目标工具如“Claude Code”、“Cursor”、“GitHub Copilot”。扩展会自动生成一个对应的指令文件如CLAUDE.md或.cursor/rules/md-feedback.md并将其内容复制到剪贴板。你只需要将内容粘贴到目标AI工具的指令区域即可。注意事项导出是静态快照。AI在外部工具中处理任务时无法像通过MCP那样实时更新MD Feedback中的注释状态如将Fix标记为Done。因此导出模式更适合一次性的、离散的任务评审。对于需要多次交互的复杂协作强烈建议配置MCP。5.4 安全机制防止AI误操作MD Feedback内建了一些安全防护防止AI做出破坏性操作文件保护默认阻止AI向.env、*.key、credentials.*以及node_modules/等敏感或无关目录进行写入。这个列表可以在设置中配置。精确文本替换当同一段文本在文件中多次出现时AI如果试图替换它必须明确指定是第几个出现的位置。这避免了AI因为全局替换而误改不该改的地方。并发安全锁当AI正在通过MCP处理一个任务时该文件会被锁定防止其他同时运行的AI进程产生冲突写入保护数据一致性。这些机制让你可以更放心地将文件系统的写权限授予AI代理因为它被约束在了一个相对安全的沙箱中行动。6. 个人使用体会与进阶建议经过数月的深度使用MD Feedback已经彻底改变了我与AI协作的模式。它带来的最大价值不是“自动化”而是“确定性和可管理性”。我不再需要记住上次和AI聊到哪了也不再需要把冗长的指令反复粘贴。一切都有迹可循有态可查。几个让我效率倍增的细节善用“Checkpoints”在侧边栏的“Checkpoints”面板你可以手动创建计划快照。在开始一个大的重构之前点一下“创建检查点”。如果AI的改动跑偏了你可以快速对比当前状态和检查点甚至回滚。这比依赖git更轻量、更聚焦于“计划”本身。CodeLens的妙用在编辑器中每个注释旁都会出现小的“Approve”和“Reject”按钮。在评审AI的修改时我几乎不用打开侧边栏直接在这些内联按钮上点击效率极高。状态栏就是仪表盘VS Code底部状态栏的MD Feedback区域会实时显示“待评审数”和“门禁状态”。我养成了时不时瞥一眼的习惯它让我对AI代理的工作进度一目了然完全被动接收信息零认知负担。从“导出”过渡到“MCP”如果你刚开始用可以从导出模式入手。但一旦你配置好MCP就再也回不去了。那种“文件保存即指令下达AI自动接单”的无感体验才是这个工具的精髓。给开发者的最后建议不要试图用MD Feedback去管理所有琐事。它最适合的是有明确产出物的协作场景写一份设计文档、实现一个模块、修复一个复杂的Bug。对于天马行空的头脑风暴和探索性聊天传统的聊天框依然合适。把MD Feedback看作是你项目工具箱里一把锋利的手术刀用于那些需要精确、可追溯、可重复执行的任务它能将你和AI的协作效率提升到一个全新的高度。
MD Feedback：用结构化注释与MCP协议提升AI编码协作效率
1. 项目概述用结构化反馈驯服你的AI编码助手如果你和我一样已经深度使用Claude Code、Cursor或者GitHub Copilot这类AI编码助手超过半年那你肯定经历过这种场景你花半小时写了一份详细的Markdown实现计划从架构设计到API接口定义都列得清清楚楚然后满怀期待地把这个计划丢给AI让它开始干活。结果呢AI要么完全无视你计划里的关键约束自己“放飞自我”写了一堆不符合预期的代码要么就是它确实按计划写了但你在它写到一半时突然发现计划里有个致命的逻辑漏洞这时候你只能尴尬地打断它“等等这里不对我们得重来”。整个沟通过程充满了不确定性。你得像猜谜一样去理解AI到底有没有读懂你的意图或者得在聊天窗口里打一大堆“这里要改”、“那里注意”的指令这些指令散落在聊天历史里下次重启会话时上下文又丢了。这种体验就像和一个听力时好时坏的远程同事协作效率低下且让人心累。MD Feedback就是为了解决这个核心痛点而生的。它不是一个花哨的AI玩具而是一个极其务实的“人机协作协议”工具。它的核心思想很简单把人类和AI的协作锚定在一个可版本控制、可结构化评审的Markdown文件上。你作为人类只负责在Markdown计划里用三种简单的标记高亮、修复、提问指出“哪里有问题”和“哪里需要关注”AI则通过标准的MCP协议读取这些结构化指令负责思考“如何解决”并汇报执行结果。所有状态——哪些问题待处理、哪些已完成、哪些被驳回——都直接保存在Markdown文件本身的HTML注释里跟着Git走永不丢失。简单说它把原本模糊、易失的AI聊天指令变成了清晰、持久、可追踪的工单系统。你从“在聊天框里和AI讨价还价”的模式切换到了“在代码仓库里给AI派发和验收任务”的模式。这个转变对于追求确定性和工程效率的开发者来说是革命性的。2. 核心设计哲学与工作流拆解2.1 为什么是“人类指问题AI想方案”MD Feedback的设计哲学第一条就是Humans only state what is wrong. AI decides how to fix it.这背后有深刻的工程心理学考量。在传统的AI编码交互中人类很容易陷入“微观管理”的陷阱。比如你发现一个函数名取得不好你可能会对AI说“把calculateUserData改成computeUserStats然后在第45行加上错误处理用try-catch包起来日志要打ERROR级别……” 你不仅在指出问题还在规定解决方案的每一个细节。这有两个坏处第一你的认知负荷很高需要思考具体怎么做第二你限制了AI的创造力它可能有一个更优雅的解法但因为你规定了细节它只能照办。MD Feedback通过强制分离“问题描述”和“解决方案”把人类解放了出来。你只需要选中那段有问题的文本按下快捷键2打上一个[Fix]标签脑子里想的是“这里的数据处理逻辑不健壮”。至于AI是通过重构函数、增加校验还是引入重试机制来解决那是它的事。它需要为它的方案负责并在实现后向你汇报。你从“监工”变成了“产品经理”只验收结果不干预过程。这种协作模式更接近高效的人类团队协作。2.2 三色标签系统为何三种注释就足够工具只提供了三种注释类型Highlight黄色高亮、Fix红色修复、Question蓝色提问。看起来简单甚至有些简陋但这恰恰是经过深思熟虑的。Highlight代表“这里很重要请注意”。它不要求行动只起到阅读标记和引起注意的作用。比如你在计划中标注了核心算法部分AI在实现时会格外关注这里。Fix代表“这里有错误或不完善需要修改”。这是最核心的指令要求AI采取行动。AI必须分析上下文提出修改方案执行并标记为完成。Question代表“这里我不确定需要澄清”。这可能是关于需求模糊也可能是对AI生成计划部分的质疑。AI需要解答疑问或与你讨论以达成一致。为什么不是五种、十种因为过多的标签会导致决策疲劳。“这里到底算‘优化’还是‘重构’” MD Feedback认为AI足够智能可以从Fix的上下文是在描述业务逻辑还是代码风格中推断出你的真实意图。三种基础标签配合自然语言描述已经能覆盖99%的评审场景。这种极简设计降低了使用门槛让工具保持锋利。2.3 完整工作流闭环从计划到交付MD Feedback构建了一个完整的、可循环的AI协作工作流下图清晰地展示了这个从人类计划到AI执行再到人类评审的闭环过程[ 人类领域 ] ┌─────────┐ │ 步骤1 │ │ 撰写计划│ └────┬────┘ │ ┌────▼────┐ │ 步骤2 │ │ 评审标注│◄───┐ └────┬────┘ │ │ │ [ 协议桥梁 ] │ ┌────▼────┐ │ │ MCP │ │ │ 协议 │ │ └────┬────┘ │ │ │ [ AI代理领域 ] │ ┌────▼────┐ │ │ 步骤3 │ │ │ 读取指令│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤4 │ │ │ 执行变更│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤5 │ │ │ 质量门禁│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤6 │ │ │ 生成报告│ │ └────┬────┘ │ │ │ ┌────▼────┐ │ │ 步骤7 │ │ │ 人类评审│────┘ └────┬────┘ │ ┌────▼────┐ │ 批准/驳回│ └─────────┘ │ ┌────▼────┐ │ 完成或迭代│ └─────────┘阶段一人类规划与评审步骤1-2你首先在Markdown文件中编写详细的项目计划或设计文档。然后你像代码评审一样审视这份计划使用MD Feedback的侧边栏或快捷键1/2/3在需要关注的文本上添加Highlight、Fix或Question注释。例如在一个API设计段落旁你可能会添加一个[Fix] 需要增加分页参数的注释。阶段二AI代理执行步骤3-4当你启动一个支持MCP协议的AI助手如配置了MD Feedback的Claude Desktop时神奇的事情发生了。AI助手直接读取到这些嵌入在文件中的结构化注释就像读取一个任务列表。它理解每个Fix都需要一个解决方案每个Question都需要一个回答。然后它开始自主工作修改代码、更新文档、回答问题并将每个动作的结果例如代码差异报告回来。阶段三自动化质量门禁步骤5MD Feedback引入了“质量门禁”的概念。你可以定义一些通过条件例如“所有Fix类注释必须被标记为Done”。AI在完成任务后会自动评估这些门禁。状态会从“阻塞”有未完成的修复变为“进行中”最后变为“通过”。这为AI的工作设立了明确的完成标准避免了“好像做完了又好像没做完”的模糊状态。阶段四人类验收与上下文传递步骤6-7AI完成一批更改后会生成一份“交接报告”并通知你进行评审。你在编辑器中可以看到清晰的代码对比然后点击“批准”或“请求修改”。更重要的是所有评审状态、开放的讨论、已完成的决策都通过HTML注释保存在Markdown文件中。这意味着即使你关掉电脑第二天换一个AI会话只要打开同一个文件所有的上下文都完整无缺。AI可以立刻接着上次中断的地方继续工作。这个闭环将一次性的、脆弱的AI聊天变成了一个可暂停、可恢复、可审计的持久化协作流程。3. 核心功能深度解析与实操要点3.1 注释系统不仅仅是标记MD Feedback的注释在底层被存储为HTML注释例如!-- [Fix]: 这里的错误处理需要加强 --。这种设计带来了几个关键优势绝对的可移植性任何能渲染Markdown的工具GitHub、GitLab、VS Code预览、Typora都会忽略HTML注释因此你的文档在任何地方看起来都是干净的。但MD Feedback或任何能解析它的工具却能读取其中的丰富信息。完美的版本控制兼容性注释作为文件内容的一部分会随着你的每一次git commit被完整记录。你可以清晰地看到在某个时间点项目存在哪些待解决的问题。这对于团队协作和项目审计至关重要。丰富的状态机每个注释不仅有类型还有状态Open, Working, Review, Answered, Done, Failed, Won‘t Fix。这个状态由AI和你的互动来驱动。AI开始处理一个Fix时会将其置为Working完成修改后置为Review等待你批准你批准后变为Done。这个状态流使得任务追踪一目了然。实操技巧高效使用快捷键安装扩展后最快的上手方式就是记住三个数字键1(高亮),2(修复),3(提问)。在编辑器中选中文本后直接按键注释瞬间生成无需鼠标点选侧边栏。这是将评审思维“流式化”的关键让你的反馈几乎不打断写作或阅读的心流。3.2 MCP集成无缝的AI通信管道MCP是MD Feedback的灵魂。没有它你就需要手动“导出”注释到某个文件然后复制粘贴给AI流程是割裂的。有了MCPAI助手就变成了一个直接连接到你项目“任务系统”的智能工人。配置详解以Claude Desktop为例在你的用户配置目录如~/.config/claude/下找到或创建mcp.json文件。添加以下配置{ mcpServers: { md-feedback: { command: npx, args: [-y, md-feedback] } } }重启Claude Desktop后你的AI助手就获得了读取和处理MD Feedback注释的能力。当它分析你的项目时它会主动发现这些注释并询问你是否要处理它们。这个过程是完全自动化的。注意工作空间路径问题某些MCP客户端如一些较老的集成方式可能无法正确识别当前工作目录。如果你的AI助手找不到注释你可能需要显式指定工作空间路径{ command: npx, args: [-y, md-feedback, --workspace/absolute/path/to/your/project] }在Windows上注意使用双反斜杠或正斜杠--workspaceC:\\work\\my-project3.3 质量门禁为AI工作设定完成标准“质量门禁”是MD Feedback里一个非常工程化的概念。它允许你定义一些必须满足的条件才能认为某个阶段的工作“完成”。例如在你的“数据库迁移计划.md”中你可以设置一个门禁!-- [Gate]: 数据迁移前置检查 -- !-- [Condition]: All Fix annotations in this document are resolved -- !-- [Condition]: At least one Question about rollback plan is Answered --这个门禁告诉AI只有本文档中所有Fix都被解决并且至少有一个关于回滚计划的Question被回答后这个门禁才算通过。AI在工作的过程中会持续评估这些门禁条件。在侧边栏你会看到门禁的状态从红色的Blocked变为黄色的In Progress最后变为绿色的Passed。这为你提供了一个清晰的、自动化的进度看板。实操心得门禁的灵活运用不要只把门禁用于最终验收。我习惯在计划的不同阶段设置门禁。比如在“架构设计”部分完成后设置一个“架构评审通过”的门禁条件是所有关于架构的Question都被回答。这样AI在开始写具体代码前必须确保我们对设计达成了共识避免了后期返工。3.4 会话交接打破AI的“金鱼记忆”AI助手最大的局限之一就是会话失忆。重启一个会话之前的讨论上下文就没了。MD Feedback通过“交接报告”完美解决了这个问题。当AI完成一个阶段的工作或你手动触发时它可以生成一份交接报告。这份报告不是一个简单的文本摘要而是一个包含了所有关键决策点、未解决问题、当前门禁状态和下一步建议的结构化文档。更重要的是这份报告本身就是一个新的、包含了所有之前注释和状态的Markdown文件。工作流程示例周一晚上你评审了一个计划加了5个Fix。AI处理了3个剩下2个。你保存文件并关机。周二早上你打开新AI会话并打开这个Markdown文件。AI通过MCP立刻读取到文件状态“有2个Open状态的Fix3个Done状态的Fix门禁A是Blocked状态。”AI可以无缝地接着处理剩下的2个Fix就像从未中断过。这个特性使得与AI进行长期、复杂的项目协作成为可能。项目上下文被持久化在项目仓库中而不是锁死在某个AI服务的临时会话里。4. 高级应用场景与实战技巧4.1 场景一Vibe Coding氛围编码工作流这是MD Feedback最自然的用法。你有一个新功能或Bug修复的想法但还没想清楚所有细节。快速起草在feature-auth.md里快速列出要点“用户登录接口”、“JWT令牌生成”、“密码加密存储”。自我评审通读草案用Highlight标出核心部分“JWT密钥必须从环境变量读取”用Question标出不确定处“加密算法用bcrypt还是Argon2”。交给AI启动Claude Code它看到你的文件和注释开始提问“关于加密算法我建议使用Argon2因为它更能抵抗GPU破解这是实现代码……” 它同时会将那个Question的状态改为Answered。迭代推进你看到AI生成的代码草案发现一个问题直接在相关代码行的描述上打一个[Fix] 这里需要添加输入验证。AI接收修改并标记为Done。整个过程中你始终在“定义问题”和“验收结果”AI在“解决问题”和“汇报进展”。计划文件成了唯一的真理来源和协作日志。4.2 场景二团队设计文档评审在团队中技术方案评审常常依赖会议效率低下。MD Feedback可以改变这一点。发起评审工程师A在design-api-v2.md中撰写新API设计。异步标注工程师B、C收到PR他们不需要安排会议而是直接在文件的具体行上添加注释。工程师B加了一个[Fix] 响应格式应该遵循公司统一标准工程师C加了一个[Question] 这个端点预计的QPS是多少是否需要限流。AI整合与澄清工程师A或者一个指定的AI助手查看所有注释。对于FixAI可以直接修改设计文档对于QuestionAI可以调研后给出答案或工程师C进行讨论。所有讨论都附着在具体的设计点上。形成决议当所有Fix被处理所有Question被回答文档即被视为评审通过。这个全过程在Git历史中清晰可查。4.3 场景三复杂任务分解与追踪对于大型任务你可以利用MD Feedback创建分层的计划追踪。主计划文件project-launch.md里面不写细节只写高级阶段和门禁。# 项目启动计划 !-- [Gate]: 阶段一基础框架 -- !-- [Condition]: file:setup-infra.md Gate is Passed -- !-- [Gate]: 阶段二核心功能 -- !-- [Condition]: file:develop-core.md Gate is Passed -- !-- [Gate]: 阶段三测试部署 -- !-- [Condition]: file:test-deploy.md Gate is Passed --子计划文件每个阶段一个独立的Markdown文件如setup-infra.md里面包含具体的任务列表和Fix注释。AI分层推进AI首先查看主计划发现“阶段一”的门禁依赖于setup-infra.md文件。它打开该文件开始处理里面的具体Fix注释如“配置Dockerfile”、“初始化数据库”。完成该文件的所有任务后该文件的Gate状态变为Passed进而触发主计划中“阶段一”门禁的通过。AI随后自动进入“阶段二”。这种方法将项目管理逻辑也编码进了可被AI理解和执行的结构中实现了真正自动化的任务推进。5. 常见问题排查与配置优化5.1 MCP连接失败怎么办这是新手最常见的问题。请按以下步骤排查问题现象可能原因解决方案AI助手完全看不到注释1. MCP配置错误2.md-feedback未全局安装3. 工作空间路径不对1. 检查mcp.json格式是否正确路径是否正确特别是Windows的路径分隔符和转义。2. 在项目目录下运行npx -y md-feedback测试服务器是否能正常启动。3. 在MCP配置中尝试使用--workspace参数绝对路径。能看到注释但状态不同步VS Code扩展与MCP服务器版本不匹配确保你通过VS Code扩展商店安装的是最新版同时npm上的md-feedback包也是最新版。运行npm update -g md-feedback或使用npx总是最新。只有部分注释出现文件未被MCP服务器正确索引确保你的Markdown文件在MCP服务器启动时指定的工作空间目录或子目录下。重启AI助手和MCP服务器。一个关键技巧在VS Code中打开MD Feedback侧边栏如果它显示“Connected to MCP server”则连接正常。你也可以查看VS Code的“输出”面板选择“MD Feedback”通道查看详细的服务器日志和通信信息。5.2 如何处理大型文档的性能问题当你对一个超过1000行的、包含大量Mermaid图表和代码块的Markdown文件进行频繁注释操作时可能会感到界面略有卡顿。调整自动刷新间隔在VS Code设置中搜索md-feedback.autoRefreshDelay。默认值是100毫秒。对于超大文档可以适当增加这个值例如设为500毫秒以减少UI更新的频率。禁用实时预览在侧边栏顶部有一个“眼睛”图标用于切换注释的“内联渲染”即在文中显示彩色背景。在纯文本编辑时可以关闭此功能以提升性能。分文件管理这是最有效的办法。将大型计划按模块拆分成多个*.md文件通过主文件链接。MD Feedback可以跨文件追踪门禁状态这样每个文件体积变小操作更流畅。5.3 导出功能当MCP不可用时的备选方案虽然MCP是首选但MD Feedback也提供了强大的导出功能支持11种不同的AI工具格式。这在某些尚未支持MCP的在线平台或特定工作流中非常有用。操作流程在VS Code中完成对Markdown计划的评审和标注。在MD Feedback侧边栏底部点击“Export”按钮。选择目标工具如“Claude Code”、“Cursor”、“GitHub Copilot”。扩展会自动生成一个对应的指令文件如CLAUDE.md或.cursor/rules/md-feedback.md并将其内容复制到剪贴板。你只需要将内容粘贴到目标AI工具的指令区域即可。注意事项导出是静态快照。AI在外部工具中处理任务时无法像通过MCP那样实时更新MD Feedback中的注释状态如将Fix标记为Done。因此导出模式更适合一次性的、离散的任务评审。对于需要多次交互的复杂协作强烈建议配置MCP。5.4 安全机制防止AI误操作MD Feedback内建了一些安全防护防止AI做出破坏性操作文件保护默认阻止AI向.env、*.key、credentials.*以及node_modules/等敏感或无关目录进行写入。这个列表可以在设置中配置。精确文本替换当同一段文本在文件中多次出现时AI如果试图替换它必须明确指定是第几个出现的位置。这避免了AI因为全局替换而误改不该改的地方。并发安全锁当AI正在通过MCP处理一个任务时该文件会被锁定防止其他同时运行的AI进程产生冲突写入保护数据一致性。这些机制让你可以更放心地将文件系统的写权限授予AI代理因为它被约束在了一个相对安全的沙箱中行动。6. 个人使用体会与进阶建议经过数月的深度使用MD Feedback已经彻底改变了我与AI协作的模式。它带来的最大价值不是“自动化”而是“确定性和可管理性”。我不再需要记住上次和AI聊到哪了也不再需要把冗长的指令反复粘贴。一切都有迹可循有态可查。几个让我效率倍增的细节善用“Checkpoints”在侧边栏的“Checkpoints”面板你可以手动创建计划快照。在开始一个大的重构之前点一下“创建检查点”。如果AI的改动跑偏了你可以快速对比当前状态和检查点甚至回滚。这比依赖git更轻量、更聚焦于“计划”本身。CodeLens的妙用在编辑器中每个注释旁都会出现小的“Approve”和“Reject”按钮。在评审AI的修改时我几乎不用打开侧边栏直接在这些内联按钮上点击效率极高。状态栏就是仪表盘VS Code底部状态栏的MD Feedback区域会实时显示“待评审数”和“门禁状态”。我养成了时不时瞥一眼的习惯它让我对AI代理的工作进度一目了然完全被动接收信息零认知负担。从“导出”过渡到“MCP”如果你刚开始用可以从导出模式入手。但一旦你配置好MCP就再也回不去了。那种“文件保存即指令下达AI自动接单”的无感体验才是这个工具的精髓。给开发者的最后建议不要试图用MD Feedback去管理所有琐事。它最适合的是有明确产出物的协作场景写一份设计文档、实现一个模块、修复一个复杂的Bug。对于天马行空的头脑风暴和探索性聊天传统的聊天框依然合适。把MD Feedback看作是你项目工具箱里一把锋利的手术刀用于那些需要精确、可追溯、可重复执行的任务它能将你和AI的协作效率提升到一个全新的高度。
