企业官网建设流程全解析

1. 项目概述：为AI开发工作流引入结构化记忆

在AI辅助编程成为日常的今天，我们面临一个全新的挑战：如何让AI记住我们项目中的关键决策？当你在Claude Code、Cursor或Windsurf中与AI结对编程时，每次对话都是孤立的。AI助手并不知道昨天你为了性能考量，决定在数据库层暂时跳过连接池；也不知道上周团队讨论后，约定所有API响应必须包含分页元数据。这些“架构决策”或“团队约定”是项目的宝贵记忆，但它们通常散落在过时的文档、模糊的会议纪要或某个开发者的脑子里，无法被AI在需要时精准调用。

DecisionNode正是为了解决这个问题而生。它不是一个简单的笔记工具，而是一个专为“AI-开发者”协作设计的结构化记忆存储与检索系统。你可以把它理解为你和你的AI助手之间共享的“第二大脑”，一个本地化、语义化、可查询的决策知识库。它的核心价值在于，将人类项目中的关键决策（为什么选择A方案而非B、某个技术栈的取舍、特定的业务逻辑约束）转化为结构化的JSON数据，并通过向量嵌入技术，让AI能够在你编码时，像人类开发者一样“回忆”起相关的历史决策，从而做出更一致、更符合项目上下文的选择。

这个工具的精妙之处在于其“按需检索”的设计哲学。它不会将海量决策信息一股脑塞进AI的上下文窗口（那会浪费宝贵的Token并引入噪音），而是通过Model Context Protocol（MCP）暴露一个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采用了一种务实且安全的架构：

1. 纯本地存储：所有决策数据、向量嵌入文件（vectors.json）均存储在用户本地目录（~/.decisionnode/）。这意味着你的项目决策、技术权衡等敏感信息永远不会离开你的机器，满足了企业对代码和设计知识产权安全性的核心要求。本地存储也带来了零网络延迟的检索速度。

2. 双接口设计：

   • CLI (decide)：供开发者直接使用。用于初始化项目、手动添加/编辑决策、执行搜索、管理决策生命周期（激活/弃用）。这是“源数据”的录入和管理入口。
   • MCP Server (decide-mcp)：供AI客户端（Claude Code, Cursor, Windsurf）调用。MCP（Model Context Protocol）是Anthropic提出的一个开放协议，旨在标准化AI应用与外部工具/数据源之间的交互方式。DecisionNode的MCP服务器暴露了诸如add_decision、search_decisions等标准化工具，使得不同的AI IDE都能以同一方式访问你的决策库。

3. 向量检索引擎：这是实现语义搜索的核心。当一条决策被添加时：

   • 文本编码：系统会提取决策的核心文本内容（通常结合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全局安装DecisionNode：

npm 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为例：

1. 在终端运行一次连接命令：

   claude mcp add decisionnode -s user decide-mcp

   -s user表示将服务器配置在用户级别，对所有项目生效。
2. 重启Claude Code。此时，Claude就具备了调用search_decisions等工具的能力。

以Cursor为例：Cursor的MCP配置通常在全局设置或项目级的.cursor/mcp.json文件中进行。你需要添加一个指向decide-mcp服务器的配置。具体路径可能因版本而异，请参考DecisionNode官方文档中关于Cursor的配置部分。

配置成功后，当你下次在Claude Code中询问“我们之前是怎么处理用户认证的？”时，Claude可能会在后台自动调用search_decisions(“用户认证”)，并将找到的相关决策插入到回复中。

3.3 核心CLI命令实战

让我们通过一个完整的场景来熟悉CLI操作。假设我们正在开发一个电商后端。

场景：记录一个关于数据库选型的决策。

1. 交互式添加：这是最推荐的方式，CLI会引导你填写每个字段。

   decide add

   • Scope:输入Database或后端
   • Decision:输入主业务数据库选用 PostgreSQL， 分析型查询使用 ClickHouse
   • Rationale:详细输入原因，例如：PostgreSQL 事务支持完善，JSONB类型适合产品动态属性。ClickHouse 列式存储对订单、行为日志的聚合查询快10倍以上。两者通过Debezium进行CDC同步。
   • Constraints:输入所有核心业务创建/更新操作必须走 PostgreSQL， 按Ctrl+D结束。

2. 快速检索：几天后，当你需要编写一个数据分析脚本时，可以搜索相关决策。

   decide search “分析查询 数据库”

   系统会语义化地匹配到之前关于ClickHouse的决策，并显示相似度分数。

3. 查看与管理：

   decide list --scope Database # 列出某个范围的所有决策 decide deprecate db-001 # 假设db-001决策已过时，软删除它 decide activate db-001 # 如果需要，可以重新激活

4. 全局决策：有些决策适用于所有项目，比如代码规范。

   decide add --global -s “Development” -d “所有项目必须使用 Prettier 和 ESLint 进行代码格式化与检查”

   这条决策会被保存在全局存储中，在任何项目下执行decide search “代码格式”时，它都会被同时检索到。

注意事项：为决策撰写高质量的RationaleRationale字段是语义搜索的“燃料”。避免只写“因为性能更好”这样模糊的话。应详细记录：1.比较过的选项（如：也考虑了MySQL和TimescaleDB）；2.决策依据（基准测试数据、团队技能栈、社区生态）；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融入你的开发循环

理论说再多，不如看它如何解决实际问题。下面是一个贯穿需求、设计、编码、重构的完整场景。

场景：为一个内容管理平台添加“文章草稿自动保存”功能。

1. 需求分析与设计阶段：

   • 你与产品经理讨论后，决定采用“防抖+自动保存”而非“实时协同编辑”的方案。
   • 你打开终端，记录下这个架构决策：

     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}`。”

2. 编码阶段（在Claude Code中）：

   • 你开始编写前端自动保存的React组件。你对Claude说：“帮我在这个Editor组件里实现一个自动保存功能。”
   • Claude在生成代码前，自动调用search_decisions(“前端 自动 保存”)。工具返回了之前记录的关于“防抖”和“5秒间隔”的决策。
   • Claude在回复中写道：“根据项目历史决策，我们采用防抖策略进行自动保存。我将使用lodash的debounce函数，并设置5秒延迟。同时，我会参考后端决策，将草稿数据通过API保存。” 随后，它给出了包含正确防抖逻辑和API调用的代码。

3. 遇到问题与排查：

   • 测试时发现，快速切换文章编辑时，草稿可能会错乱。你怀疑是防抖函数实例管理问题。
   • 你手动搜索更具体的决策：decide search “防抖 实例 内存泄漏”。虽然没有直接结果，但相关的前端决策被检索出来，提醒你注意副作用清理。
   • 你修复了问题（在组件卸载时取消防抖），并决定将这次教训也记录下来，作为一条约束性更强的决策：

     decide add -s “Frontend” -d “在React组件中使用防抖函数时，必须在useEffect清理函数中调用.cancel()” -r “防止组件卸载后防抖函数仍被触发，导致状态更新错误或内存泄漏。这是修复草稿编辑切换bug的经验。”

4. 代码审查与知识传承：

   • 新同事Review你的代码，对自动保存方案有疑问。你不需要长篇大论解释，只需让他运行decide list --scope Frontend。
   • 他立刻看到了关于自动保存方案选型、技术实现细节和避坑指南的三条关联决策，快速理解了来龙去脉。
   • 未来，当任何一位团队成员（或AI）需要修改、优化或重构这个功能时，相关的决策记忆都会被自动唤醒，确保变更与最初的架构意图保持一致。

通过这个流程，DecisionNode从一个被动的记录工具，变成了一个主动的、融入开发血液的“集体记忆”系统，显著提升了决策的连贯性、代码的一致性和团队协作的上下文共享效率。

7. 常见问题与故障排查

在实际使用中，你可能会遇到以下情况：

1. AI助手（Claude/Cursor）没有调用搜索工具？

• 检查MCP配置：首先确认claude mcp list或Cursor的MCP设置中已正确添加decisionnode服务器。
• 检查代理行为模式：如果设置为relaxed，AI可能认为当前对话不需要搜索。你可以尝试在提问时更明确地提及“参考我们之前的决策”或“查一下我们关于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指定端口。
• 浏览器缓存：如果页面加载异常，尝试强制刷新（Ctrl+F5）或打开浏览器无痕窗口访问。

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助手对整个项目的理解达到了一个新的高度——一种基于共同记忆的、连贯的、历史感知的高度。它不仅仅是记录“我们做了什么”，更是定义了“我们为什么这样做”，而这，正是可持续软件工程实践的基石。