1. 项目概述为AI开发工作流引入结构化记忆在AI辅助编程成为日常的今天我们面临一个全新的挑战如何让AI记住我们项目中的关键决策当你在Claude Code、Cursor或Windsurf中与AI结对编程时每次对话都是孤立的。AI助手并不知道昨天你为了性能考量决定在数据库层暂时跳过连接池也不知道上周团队讨论后约定所有API响应必须包含分页元数据。这些“架构决策”或“团队约定”是项目的宝贵记忆但它们通常散落在过时的文档、模糊的会议纪要或某个开发者的脑子里无法被AI在需要时精准调用。DecisionNode正是为了解决这个问题而生。它不是一个简单的笔记工具而是一个专为“AI-开发者”协作设计的结构化记忆存储与检索系统。你可以把它理解为你和你的AI助手之间共享的“第二大脑”一个本地化、语义化、可查询的决策知识库。它的核心价值在于将人类项目中的关键决策为什么选择A方案而非B、某个技术栈的取舍、特定的业务逻辑约束转化为结构化的JSON数据并通过向量嵌入技术让AI能够在你编码时像人类开发者一样“回忆”起相关的历史决策从而做出更一致、更符合项目上下文的选择。这个工具的精妙之处在于其“按需检索”的设计哲学。它不会将海量决策信息一股脑塞进AI的上下文窗口那会浪费宝贵的Token并引入噪音而是通过Model Context ProtocolMCP暴露一个search_decisions工具。当AI在编写与“数据库连接”相关的代码时它会主动调用这个工具以“数据库连接 池 性能”为查询词语义搜索你的决策库并将最相关的几条决策例如之前提到的“跳过连接池”的决策拉取到当前对话中。这实现了真正意义上的上下文感知编程辅助。2. 核心设计理念与架构解析2.1 定位介于文档与规则之间的“记忆层”在理解DecisionNode的定位时我们需要厘清它与其他常见知识承载形式的区别CLAUDE.md/memory.md这类文件通常包含需要AI始终记住的全局性规则、项目规范或固定指令例如“始终使用TypeScript”、“代码注释风格指南”。它们被预置在系统提示词中持续占用上下文。Confluence/Notion文档包含全面的设计文档、会议记录但结构松散难以被AI实时、精准检索。DecisionNode的“决策”它更像是情景记忆。一条决策记录了一个在特定上下文scope下针对特定问题做出的权衡decision及其理由rationale。它不需要被AI时刻记住但需要在相关场景出现时能被迅速“想起来”。例如“在用户服务中因为初期流量预估较低我们选择使用SQLite而非PostgreSQL以简化部署”。这条决策在讨论微服务选型时无关但在优化用户服务数据库时至关重要。这种定位决定了其技术架构必须支持高精度的语义检索而非简单的关键词匹配。2.2 核心架构本地优先与MCP桥梁DecisionNode采用了一种务实且安全的架构纯本地存储所有决策数据、向量嵌入文件vectors.json均存储在用户本地目录~/.decisionnode/。这意味着你的项目决策、技术权衡等敏感信息永远不会离开你的机器满足了企业对代码和设计知识产权安全性的核心要求。本地存储也带来了零网络延迟的检索速度。双接口设计CLI (decide)供开发者直接使用。用于初始化项目、手动添加/编辑决策、执行搜索、管理决策生命周期激活/弃用。这是“源数据”的录入和管理入口。MCP Server (decide-mcp)供AI客户端Claude Code, Cursor, Windsurf调用。MCPModel Context Protocol是Anthropic提出的一个开放协议旨在标准化AI应用与外部工具/数据源之间的交互方式。DecisionNode的MCP服务器暴露了诸如add_decision、search_decisions等标准化工具使得不同的AI IDE都能以同一方式访问你的决策库。向量检索引擎这是实现语义搜索的核心。当一条决策被添加时文本编码系统会提取决策的核心文本内容通常结合scope、decision和rationale字段调用Google Gemini的gemini-embedding-001模型将其转换为一个768维或更高维的向量一组浮点数。这个向量在数学上代表了该段文本的“语义”。本地索引该向量被保存在本地的vectors.json文件中并与原决策的ID关联。相似度计算当进行搜索时查询语句同样被转换为向量然后通过计算余弦相似度Cosine Similarity来度量查询向量与库中每个决策向量的夹角。夹角越小余弦值越接近1语义相似度就越高。系统会返回相似度超过设定阈值默认0.3的决策并按分数排序。实操心得理解“余弦相似度”阈值默认的0.3阈值是一个平衡点。在实践中如果发现搜索返回了太多不相关的结果“噪声”可以将阈值提高到0.5或0.6这会让检索结果更精确但可能漏掉一些弱相关但有用的决策。反之在项目初期决策较少时可以降低到0.2以拓宽检索范围。你可以通过decide config set threshold 0.5来动态调整。2.3 数据模型一个决策包含什么一条决策并非随意记录其结构化的JSON设计确保了信息的完备性和可检索性{ “id”: “auth-012”, “scope”: “Authentication”, “decision”: “采用JWT而非Session Cookie进行API认证”, “status”: “active”, “rationale”: “1. 服务端无状态易于水平扩展。2. 更适合移动端及第三方应用集成。3. 令牌自包含减少了数据库查询。注意需妥善处理令牌刷新和注销黑名单问题。”, “constraints”: [ “令牌有效期设置为2小时” “刷新令牌有效期14天单次使用后失效” ], “createdAt”: “2024-11-20T10:00:00Z” }id: 唯一标识符通常由“范围-序号”组成便于人工引用。scope:最重要的检索字段之一。它定义了决策的上下文边界如“前端”、“后端”、“数据库”、“DevOps”、“认证”等。良好的scope分类能极大提升检索效率。decision: 决策内容的简洁陈述。应使用肯定、明确的语气。status: 生命周期状态active/deprecated。支持软删除便于追溯。rationale:语义检索的核心素材。这里需要详细记录“为什么”——技术权衡、业务考量、性能评估、规避的风险等。这部分内容越丰富向量表征就越准确AI越能理解其深层含义。constraints: 由此决策衍生出的具体行动约束或规则是AI在编码时需要直接遵守的。createdAt: 时间戳用于历史和排序。3. 从零开始安装与核心工作流实操3.1 环境准备与初始化首先你需要安装Node.js环境建议18.x以上版本。随后通过npm全局安装DecisionNodenpm install -g decisionnode安装后进入你的项目根目录开始初始化cd /path/to/your-awesome-project decide init这条命令会在项目根目录下创建一个隐藏的.decisionnode目录用于存储该项目专属的决策库和向量文件。每个项目都可以有自己独立的决策库这符合软件项目隔离的原则。接下来配置嵌入模型API密钥。DecisionNode默认使用Google Gemini的嵌入模型其免费额度对于个人或团队使用通常绰绰有余。decide setup按照提示前往Google AI Studio获取API密钥并填入。密钥同样被安全地存储在本地。3.2 连接你的AI工作伙伴MCP配置这是让AI“活”起来的关键一步。你需要在你使用的AI IDE中配置MCP服务器。以Claude Code为例在终端运行一次连接命令claude mcp add decisionnode -s user decide-mcp-s user表示将服务器配置在用户级别对所有项目生效。重启Claude Code。此时Claude就具备了调用search_decisions等工具的能力。以Cursor为例Cursor的MCP配置通常在全局设置或项目级的.cursor/mcp.json文件中进行。你需要添加一个指向decide-mcp服务器的配置。具体路径可能因版本而异请参考DecisionNode官方文档中关于Cursor的配置部分。配置成功后当你下次在Claude Code中询问“我们之前是怎么处理用户认证的”时Claude可能会在后台自动调用search_decisions(“用户认证”)并将找到的相关决策插入到回复中。3.3 核心CLI命令实战让我们通过一个完整的场景来熟悉CLI操作。假设我们正在开发一个电商后端。场景记录一个关于数据库选型的决策。交互式添加这是最推荐的方式CLI会引导你填写每个字段。decide addScope:输入Database或后端Decision:输入主业务数据库选用 PostgreSQL 分析型查询使用 ClickHouseRationale:详细输入原因例如PostgreSQL 事务支持完善JSONB类型适合产品动态属性。ClickHouse 列式存储对订单、行为日志的聚合查询快10倍以上。两者通过Debezium进行CDC同步。Constraints:输入所有核心业务创建/更新操作必须走 PostgreSQL 按CtrlD结束。快速检索几天后当你需要编写一个数据分析脚本时可以搜索相关决策。decide search “分析查询 数据库”系统会语义化地匹配到之前关于ClickHouse的决策并显示相似度分数。查看与管理decide list --scope Database # 列出某个范围的所有决策 decide deprecate db-001 # 假设db-001决策已过时软删除它 decide activate db-001 # 如果需要可以重新激活全局决策有些决策适用于所有项目比如代码规范。decide add --global -s “Development” -d “所有项目必须使用 Prettier 和 ESLint 进行代码格式化与检查”这条决策会被保存在全局存储中在任何项目下执行decide search “代码格式”时它都会被同时检索到。注意事项为决策撰写高质量的RationaleRationale字段是语义搜索的“燃料”。避免只写“因为性能更好”这样模糊的话。应详细记录1.比较过的选项如也考虑了MySQL和TimescaleDB2.决策依据基准测试数据、团队技能栈、社区生态3.已知的权衡与妥协如ClickHouse的写入延迟较高因此只用于只读分析。这样的记录不仅帮助AI更是给未来接手项目的同事包括六个月后的你自己的一份宝贵上下文。4. 可视化界面洞察决策之间的关系CLI和MCP是生产力接口而decide ui则提供了强大的战略洞察视角。运行decide ui会启动一个本地Web服务器默认localhost:7788提供三个不可替代的视图4.1 图视图决策的关联网络这是最具启发性的视图。每个节点代表一条决策节点之间的连线代表它们的向量相似度余弦相似度超过可调阈值。这个视图能让你直观地看到决策集群哪些决策在语义上紧密相关自然形成一个主题簇例如所有关于“API设计”、“错误处理”、“日志”的决策可能各自聚拢。孤立决策那些与其他决策关联度很低的节点可能是独立的技术点也可能提示其scope或rationale描述方式与众不同值得审视。关键枢纽有些决策可能与多个集群相连这些往往是架构中的基础性或跨领域决策。你可以拖动滑块调整连接阈值观察网络结构如何变化。这有助于你理解决策库的语义密度和结构。4.2 向量空间视图语义的几何表达这个视图将高维向量空间通过UMAP算法降维到2D平面进行可视化。每个决策被表示为一个从原点发出的向量箭头。箭头方向代表该决策语义的主要方向。箭头长度在某种程度上反映向量的“强度”或独特性。集群形成语义相近的决策向量会指向相近的方向在图上形成清晰的扇区或簇。这个视图从数学上验证了你的向量嵌入是否有效。如果所有箭头杂乱无章地混在一起可能意味着嵌入模型未能很好地区分不同决策的语义。4.3 列表视图传统的管理界面这是一个功能齐全的表格/卡片视图支持按scope筛选、按时间排序、关键词搜索非语义以及直接查看决策详情。它是执行批量操作或详细阅读的最佳场所。最酷的功能实时MCP脉冲。当你在Claude Code中操作AI调用search_decisions工具时在UI的图视图和列表视图中被匹配到的决策节点会以对应工具的颜色如Claude Code的橙色高亮脉冲一下。你能 literally “看到” AI在思考时检索了哪条记忆。这个功能对于调试AI的行为和理解其决策过程有巨大帮助。5. 高级特性与运维指南5.1 冲突检测避免决策重复与矛盾在团队中不同成员可能记录相似的决策。DecisionNode的冲突检测功能会在添加新决策时自动与现有决策库进行相似度比对默认阈值75%。如果发现高度相似的决策CLI会发出警告并列出冲突项让你选择是继续添加、更新旧决策还是取消。MCP服务器则会返回冲突信息让AI助手来决定如何处理。这有效维护了决策库的简洁性和一致性。5.2 嵌入健康与维护向量嵌入是搜索的基石必须保持其完整性。decide check列出所有缺失向量嵌入的决策。这通常发生在从旧版本升级或手动修改了数据文件后。decide embed为所有缺失嵌入的决策生成向量。这是一个安全的操作不会覆盖已存在的向量。decide clean清理向量文件中那些已经没有任何决策引用的“孤儿向量”优化存储。建议在团队共享决策库或进行重大数据迁移后运行一次decide check和decide embed。5.3 代理行为模式控制AI的“好奇心”这是一个精细控制AI如何与决策库交互的设置。严格模式 (Strict)这是默认设置。在此模式下search_decisions工具的描述会强烈建议AI“在修改任何代码前必须先搜索相关决策”。这适用于对架构一致性要求极高的项目能强制AI进行上下文检查。宽松模式 (Relaxed)工具描述变为“当你认为搜索历史决策有助于当前任务时可以使用此工具”。这赋予了AI更大的自主权让它自己判断何时需要检索记忆。你可以通过decide config set agentBehavior relaxed来切换模式。我的经验是在项目初期或探索性编程时使用宽松模式在维护大型、稳定项目时使用严格模式。5.4 导入、导出与团队协作决策库本质上是JSON文件这使其易于迁移和共享。decide export json decisions_backup.json导出所有决策包括全局决策为JSON数组。decide import json decisions_backup.json从JSON文件导入决策。导入时会进行冲突检测。团队协作工作流建议可以将项目级的.decisionnode目录纳入版本控制如Git。团队成员在做出重要架构决策后通过CLI添加记录并提交。这样决策历史就和代码变更历史同步了。全局决策库~/.decisionnode/global则更适合个人管理或通过共享文档同步关键条目。6. 实战场景将DecisionNode融入你的开发循环理论说再多不如看它如何解决实际问题。下面是一个贯穿需求、设计、编码、重构的完整场景。场景为一个内容管理平台添加“文章草稿自动保存”功能。需求分析与设计阶段你与产品经理讨论后决定采用“防抖自动保存”而非“实时协同编辑”的方案。你打开终端记录下这个架构决策decide add -s “Frontend” -d “文章编辑采用防抖自动保存而非实时协同” -r “产品需求为单人编辑实时协同复杂度高。防抖方案间隔5秒能在体验和性能间取得平衡避免频繁请求。技术选型为lodash的debounce函数。”同时你决定在后端使用Redis存储草稿因为读写快且有过期功能。decide add -s “Backend” -d “文章草稿数据存储于Redis设置7天过期” -r “草稿数据临时性强Redis读写性能远超MySQL。设置TTL自动清理避免存储膨胀。键设计为 draft:user:{userId}:post:{postId}。”编码阶段在Claude Code中你开始编写前端自动保存的React组件。你对Claude说“帮我在这个Editor组件里实现一个自动保存功能。”Claude在生成代码前自动调用search_decisions(“前端 自动 保存”)。工具返回了之前记录的关于“防抖”和“5秒间隔”的决策。Claude在回复中写道“根据项目历史决策我们采用防抖策略进行自动保存。我将使用lodash的debounce函数并设置5秒延迟。同时我会参考后端决策将草稿数据通过API保存。” 随后它给出了包含正确防抖逻辑和API调用的代码。遇到问题与排查测试时发现快速切换文章编辑时草稿可能会错乱。你怀疑是防抖函数实例管理问题。你手动搜索更具体的决策decide search “防抖 实例 内存泄漏”。虽然没有直接结果但相关的前端决策被检索出来提醒你注意副作用清理。你修复了问题在组件卸载时取消防抖并决定将这次教训也记录下来作为一条约束性更强的决策decide add -s “Frontend” -d “在React组件中使用防抖函数时必须在useEffect清理函数中调用.cancel()” -r “防止组件卸载后防抖函数仍被触发导致状态更新错误或内存泄漏。这是修复草稿编辑切换bug的经验。”代码审查与知识传承新同事Review你的代码对自动保存方案有疑问。你不需要长篇大论解释只需让他运行decide list --scope Frontend。他立刻看到了关于自动保存方案选型、技术实现细节和避坑指南的三条关联决策快速理解了来龙去脉。未来当任何一位团队成员或AI需要修改、优化或重构这个功能时相关的决策记忆都会被自动唤醒确保变更与最初的架构意图保持一致。通过这个流程DecisionNode从一个被动的记录工具变成了一个主动的、融入开发血液的“集体记忆”系统显著提升了决策的连贯性、代码的一致性和团队协作的上下文共享效率。7. 常见问题与故障排查在实际使用中你可能会遇到以下情况1. AI助手Claude/Cursor没有调用搜索工具检查MCP配置首先确认claude mcp list或Cursor的MCP设置中已正确添加decisionnode服务器。检查代理行为模式如果设置为relaxedAI可能认为当前对话不需要搜索。你可以尝试在提问时更明确地提及“参考我们之前的决策”或“查一下我们关于XX是怎么定的”。权限问题确保AI客户端有权限执行本地的decide-mcp命令。2. 语义搜索的结果不准确或遗漏关键决策优化Rationale字段搜索主要基于decision和rationale的嵌入。确保rationale包含了足够多的、描述性的关键词和上下文。避免过于简略。调整搜索阈值使用decide config set threshold 0.4提高阈值以获取更精确但更少的结果或降低阈值以获取更广泛的结果。检查嵌入状态运行decide check确保你想搜索的决策状态是active且拥有嵌入向量。对于deprecated的决策使用decide list --all查看。3.decide ui启动失败或无法访问端口占用默认端口7788可能被占用。DecisionNode UI会尝试其他端口观察启动日志。你也可以通过环境变量DECISIONNODE_UI_PORT指定端口。浏览器缓存如果页面加载异常尝试强制刷新CtrlF5或打开浏览器无痕窗口访问。4. 如何与团队成员共享项目决策库版本控制将项目内的.decisionnode文件夹加入Git仓库。这是最简单直接的方式决策变更将与代码提交历史同步。定期导出/导入作为备选方案可以定期使用decide export将决策库导出为JSON文件放入仓库或共享文档。其他成员再导入。但这种方式无法实时同步。全局决策的共享对于团队级规范可以约定一个共享文件定期手动同步到各自的~/.decisionnode/global目录或通过脚本自动化此过程。5. 向量嵌入调用Gemini API失败API密钥与配额确认Gemini API密钥有效且未超出免费配额。可通过decide config检查或重新设置API密钥。网络问题确保你的网络可以访问Google AI的API服务。降级方案目前DecisionNode主要依赖Gemini Embedding。社区未来可能会支持本地嵌入模型如All-MiniLM-L6-v2这对于完全离线的环境是更好的选择。关注项目更新。这个工具的价值随着时间推移和决策的积累而指数级增长。最初的几十条决策可能感觉不到太大变化但当你的决策库积累到数百条覆盖项目的各个角落时你会发现你和你的AI助手对整个项目的理解达到了一个新的高度——一种基于共同记忆的、连贯的、历史感知的高度。它不仅仅是记录“我们做了什么”更是定义了“我们为什么这样做”而这正是可持续软件工程实践的基石。