企业官网建设流程全解析

1. 项目概述：为AI开发工具装上“长期记忆”

如果你和我一样，日常重度依赖Claude Code或Cursor这类AI编程助手来写代码、重构项目，那你肯定也遇到过那个让人头疼的问题：聊着聊着，AI就把之前讨论过的关键业务规则、架构决策给忘了。一个复杂的特性开发到一半，你问它“这里为什么不用缓存？”，它可能已经记不起十分钟前你刚解释过的“用户数据实时性要求极高，缓存会导致数据不一致”这条铁律了。这种“渐进式上下文丢失”在开发大型、复杂的项目时尤其致命，经常导致AI给出看似合理但实则违背项目核心约束的方案。

BigRack.dev 瞄准的就是这个痛点。它本质上是一个本地优先的、基于Model Context Protocol的服务器。你可以把它理解成给你心爱的AI助手（比如Claude Code）外接了一个“项目专用大脑”或者“长期记忆库”。这个大脑里存储着你项目的所有“家规”：业务逻辑、术语表、架构模式、团队规范，甚至是一个带依赖关系的任务分解图。AI助手通过MCP协议，可以随时查询这个大脑，确保它给出的每一行代码、每一个建议，都建立在对你项目完整、持久的理解之上，而不是仅基于聊天窗口里那有限的上下文。

它的核心价值在于“结构化”和“持久化”。不同于你在聊天框里零散地粘贴文档，BigRack让你以“Rack”（项目仓库）、“Project”（特性/修复单元）、“Task”（原子任务）的层级来组织信息。所有业务上下文都会被自动转换成向量嵌入（用的是本地运行的Xenova/all-MiniLM-L6-v2模型），支持你用自然语言进行语义搜索。比如，你可以直接问：“我们这个项目的认证要求是什么？”或者“处理用户支付时有哪些边界情况？”，BigRack会从你的记忆库中找出最相关的几条信息返回给AI。

最让我安心的一点是它的100%本地化架构。所有数据——SQLite数据库、向量索引——都老老实实待在你的~/.bigrack/目录里。没有云端API调用，没有数据泄露风险，离线照样工作。这对于处理公司内部代码或敏感项目的开发者来说，是个巨大的加分项。

简单说，BigRack想解决的是：如何让AI助手在参与复杂软件开发时，能像一个真正熟悉项目历史、牢记业务细节的资深队友一样可靠。它不是要取代你，而是要成为你和AI之间那个永不遗忘的“项目知识中枢”。

2. 核心概念与架构深度解析

要玩转BigRack，得先吃透它设计的几个核心概念。这不仅仅是名词解释，理解了它们，你才知道该怎么最高效地利用这个工具来组织你的工作。

2.1 核心概念三层级：Rack, Project, Task

Rack（货架/仓库）这是最高层级的容器，通常对应一个完整的代码仓库或业务领域。比如，你有一个“用户中心微服务”的Git仓库，那就可以为它创建一个Rack。bigrack.json文件就是这个Rack的身份证，放在项目根目录。Rack里存放的是这个领域最稳定、最核心的知识资产：

• 业务规则：例如，“用户密码必须满足PCI DSS标准”、“免费用户API调用频率限制为每分钟100次”。
• 术语表：定义项目内的黑话，比如“幽灵用户”特指注册后7天内未激活的用户。
• 架构模式：“所有外部服务调用必须通过ServiceClient抽象层”、“数据库访问统一使用Repository模式”。
• 团队规范：“提交信息遵循Conventional Commits”、“React组件必须使用TypeScript接口定义Props”。

Rack是知识的基石，它里面的内容对其下的所有Projects和Tasks都是可见的、可继承的。

Project（项目）这代表一个具体的工作单元，通常对应一个Git分支上的开发目标，比如“实现用户双因素认证（2FA）”、“修复订单支付超时BUG”。一个Rack下可以有多个Projects。Project会自动继承其父Rack的所有上下文，同时你也可以为这个Project添加独有的、临时性的上下文。例如，在“实现2FA”这个Project里，你可以添加一条临时规则：“在开发阶段，短信验证码默认为‘000000’”。这样，AI在帮你写这个特性的代码时，既能遵循Rack里关于用户认证的通用规则，也知道这个临时的开发捷径。

Task（任务）这是最小的工作单元，应该是原子性的、可独立完成或验证的。BigRack鼓励你将一个Project分解成多个有依赖关系的Tasks，形成一个有向无环图。每个Task包含：

• 标题、描述、状态：基础信息。
• 类型与优先级：是feature、bugfix还是refactor？优先级是critical还是low？
• 依赖关系：明确哪些Task必须先完成。比如，“设计数据库表结构”必须先于“实现数据访问层”。
• 验收标准：明确怎么才算完成。比如，“Task完成时，需要新增的API端点能通过Postman集合中的所有测试用例”。
• 预估时间 & Git分支：关联到具体的代码变更。

这种层级结构的美妙之处在于，它把模糊的“开发一个特性”变成了清晰的、可追踪的步骤。AI可以查看整个DAG（有向无环图），知道当前任务的上下游，从而给出更精准的代码建议，比如提醒你“这个函数里调用的sendSMS方法，其接口定义依赖于‘设计短信服务接口’这个Task，那个完成了吗？”

2.2 本地向量搜索与RAG引擎的工作原理

这是BigRack的“智能”核心。很多人听到“向量搜索”、“RAG”就觉得是云端大模型的玩意儿，但BigRack把它完全搬到了本地。

1. 嵌入过程：当你通过bigrack context add或AI助手添加一条业务规则时，BigRack在后台会做这样几件事：

• 文本预处理：清理你的输入文本。
• 本地模型推理：调用已下载的Xenova/all-MiniLM-L6-v2模型。这是一个轻量级的句子转换模型，只有大约22.6MB，专门为在浏览器或Node.js环境中高效运行而优化。它会把你的文本转换成一段384维的浮点数向量。这个向量可以理解为这段文本在高维空间中的一个“数学指纹”，语义相近的文本，其向量在空间中的距离也更近。
• 向量存储：将这个向量，连同原始文本、元数据（类型、所属Rack/Project等）一起，存入SQLite数据库。BigRack使用Prisma ORM来管理这些数据。

2. 查询过程：当你或AI助手查询“What are the authentication requirements?”时：

• 查询向量化：同样使用上述模型，将查询语句本身也转换成384维的向量。
• 相似度计算：在数据库里，计算查询向量与所有已存储上下文向量的余弦相似度。这是一种衡量两个向量方向相似程度的算法，值越接近1，表示语义越相似。
• 检索与返回：系统会取出相似度最高的前K条（比如前5条）上下文记录，将它们的原始文本按相关性排序后返回。这就是RAG（检索增强生成）中的“检索”部分。AI助手拿到这些最相关的“记忆片段”，就能生成更准确、更贴合你项目实际的回答。

> 注意：由于模型较小（384维 vs. 一些云端模型1536维），它在处理非常长或特别复杂的句子时，精度可能不如顶级商用嵌入模型。但对于代码注释、业务规则、API描述这类开发上下文，它的表现已经足够出色，且换来了完全的离线、免费和即时响应。首次运行时会自动下载模型文件，请确保网络通畅。

2.3 技术栈与项目结构剖析

BigRack采用了一个清晰的Monorepo结构，使用Turborepo进行管理，这对于一个包含核心包、未来Web应用等模块的项目来说非常合适。

bigrack.dev/ ├── apps/ # 应用层（展示与交互） │ ├── website/ # 官网（Next.js 14），负责宣传和文档 │ ├── api/ # （规划中）未来可能的云端API或同步服务 │ └── dashboard/ # （规划中）本地Web管理面板，可视化查看Rack和Task ├── packages/ # 核心包（逻辑与数据） │ ├── mcp/ # 心脏：@bigrack/mcp 包 │ │ ├── src/ │ │ │ ├── mcp/ # MCP服务器实现，定义和暴露工具（Tools）给AI │ │ │ ├── cli/ # 命令行交互，用户直接操作BigRack的入口 │ │ │ ├── storage/ # 数据持久层，Prisma Schema定义和SQLite操作 │ │ │ ├── embeddings/ # 向量化与搜索逻辑，封装transformers.js调用 │ │ │ └── logger/ # 基于Pino的日志记录，便于调试 │ │ └── prisma/ # 数据库迁移文件和Schema定义 │ ├── shared/ # 共享的类型定义和工具函数 │ └── config/ # 共享的构建或运行时配置 └── ...

关键的技术选型考量：

• Node.js + TypeScript：保证了跨平台能力和强大的类型安全，与主流AI开发工具链契合。
• SQLite + Prisma：SQLite是实现“单机、零配置”的基石，Prisma提供了优雅的类型安全数据库访问。
• Xenova/transformers.js：这个库使得在Node.js中直接运行Hugging Face格式的模型成为可能，是本地嵌入的关键。
• Commander, Inquirer, Chalk, Ora：这套CLI工具链提供了专业、友好的命令行用户体验。

这种架构分离了关注点：packages/mcp是纯粹的、无UI的后端服务，通过MCP协议提供能力。apps/下的项目则是不同的消费端或管理界面。目前，我们主要通过CLI和AI助手来交互，未来Dashboard可能会提供一个更直观的管理视图。

3. 从零开始的完整实操指南

理论说得再多，不如动手装一遍。下面是我从零搭建并集成到Claude Code的全过程记录，包含了每一步的意图和可能遇到的坑。

3.1 环境准备与项目克隆

首先，确保你的开发环境符合要求。BigRack要求Node.js版本在20以上，这是为了使用一些较新的API和保证性能。

# 检查Node.js版本 node --version # 应输出 v20.x.x 或更高 # 如果没有安装或版本过低，建议使用nvm管理Node版本 # 安装nvm后，执行： nvm install 20 nvm use 20

接下来，克隆仓库并安装依赖。由于是Monorepo，根目录的安装会处理所有子包。

# 克隆项目 git clone https://github.com/baptiste-mnh/bigrack.dev.git cd bigrack.dev # 安装所有依赖（包括packages/mcp和apps/website等） npm install # 可选但推荐：全局安装Turbo，方便后续运行Monorepo脚本 npm install -g turbo

> 实操心得：第一次npm install可能会花点时间，因为要安装Prisma、transformers.js等依赖。如果网络不佳，可以考虑配置npm镜像。另外，确保你的磁盘有足够空间，因为后续会下载约23MB的嵌入模型。

3.2 构建与链接MCP核心包

BigRack的核心功能都在@bigrack/mcp这个包里。我们需要先构建它，然后“链接”到全局，让系统命令bigrack和你的AI助手都能找到它。

# 进入MCP包目录（虽然从根目录运行脚本也可以，但明确路径更清晰） cd packages/mcp # 构建TypeScript代码为JavaScript npm run build # 或者从项目根目录运行：npm run build:mcp # 将当前包链接到全局node_modules，创建`bigrack`命令 npm link # 或者从项目根目录运行：npm run link:mcp

链接成功验证：

bigrack --version

如果看到版本号输出（比如0.1.0-beta），说明链接成功。如果提示“命令未找到”，可能是全局node_modules的bin目录不在你的系统PATH中。可以尝试：

# 查看npm全局安装路径 npm config get prefix # 通常为 /usr/local 或 %APPDATA%\npm # 确保该路径下的 `bin` 文件夹已添加到系统的PATH环境变量中。

3.3 全局初始化与基础配置

链接成功后，需要在你的机器上进行一次性初始化。这个命令会创建~/.bigrack/目录（在Windows上是C:\Users\<用户名>\.bigrack\），并初始化SQLite数据库。

bigrack init

执行后，你应该能看到类似这样的输出：

Initializing BigRack... ✓ Created global directory at /Users/yourname/.bigrack ✓ Database schema initialized ✓ BigRack initialized successfully!

此时，可以查看一下状态和配置：

bigrack status bigrack config show

status会告诉你当前不在任何一个Rack目录下。config show会显示默认配置，比如嵌入模型路径、日志级别等。

> 注意事项：~/.bigrack/目录是你的所有数据存储地。定期备份这个目录，尤其是在进行重要项目之前。虽然数据库结构可能还在Beta阶段变化，但备份总是好习惯。你可以用简单的复制命令，或者写个cron任务/定时任务来备份。

3.4 与AI助手集成：以Claude Desktop为例

这是让BigRack发挥魔力的关键一步——教会你的AI助手如何使用它。

1. 运行设置命令：

bigrack setup-claude

这个命令做了什么呢？它会定位你的Claude Desktop应用配置目录（通常是~/Library/Application Support/Claude/或%APPDATA%\Claude\），然后在其下创建或修改一个名为claude_desktop_config.json的文件。这个文件告诉Claude Desktop：“嘿，这里还有一个本地的MCP服务器，你可以连接它并使用它提供的工具。”

2. 重启Claude Desktop：必须完全退出并重启Claude Desktop应用，不仅仅是关闭窗口。在macOS上可以右键点击Dock图标选择“退出”，在Windows上通过任务管理器结束进程。重启后，Claude才能加载新的MCP服务器配置。

3. 验证连接：重启Claude后，新建一个对话。你应该能在输入框上方或侧边栏的工具区域，看到除了默认工具外，多出了BigRack提供的工具。通常名称会是bigrack_开头，比如bigrack_create_repo,bigrack_query_context等。如果没看到，可以尝试在Claude的Settings -> Developer 或关于MCP的配置部分查看日志。

对于Cursor用户：过程类似，命令换成：

bigrack setup-cursor

然后同样需要重启Cursor IDE。Cursor对MCP的支持集成在IDE内部，配置方式可能略有不同，但bigrack setup-cursor命令会尝试自动完成配置。

> 踩坑记录：我第一次集成时，setup-claude命令成功了，但重启Claude后没看到工具。原因是我的Claude Desktop版本较旧，对MCP的支持不完全。请确保你的Claude Desktop更新到最新版本。另一个常见问题是配置文件权限错误，如果手动检查配置，确保JSON格式正确，特别是mcpServers部分包含了BigRack的本地服务器路径（通常是bigrack命令的绝对路径或npx调用）。

4. 实战工作流：从创建Rack到驱动开发

现在，工具已经就绪，让我们模拟一个真实的开发场景，看看BigRack如何融入日常编码。

4.1 初始化项目Rack与注入核心知识

假设我正在开发一个名为“TaskFlow”的轻量级任务管理API服务。

# 1. 进入我的项目目录 cd ~/projects/taskflow-api # 2. 通过AI助手初始化Rack # 在Claude Code的聊天框中，我输入： # “请为当前目录初始化一个BigRack Rack，项目名称为‘TaskFlow API’，描述是‘一个用于个人任务管理的RESTful API服务’。” # Claude会调用 `bigrack_create_repo` 工具。 # 或者，我也可以直接用CLI（但通常让AI做更自然）： # bigrack repo init --name "TaskFlow API" --description "..."

初始化后，项目根目录会生成一个bigrack.json文件，内容大致如下：

{ "name": "TaskFlow API", "description": "一个用于个人任务管理的RESTful API服务", "rackId": "rack_xxxxxx" }

这个文件将当前目录与~/.bigrack/数据库中的那个Rack记录关联起来。

3. 注入项目核心上下文：接下来，我把这个项目的“宪法”告诉BigRack。我直接在Claude对话里说：

“请将以下内容作为业务规则添加到BigRack上下文中：” “1.数据模型：核心实体为Task，包含字段：id, title, description, status (pending, in_progress, completed), priority (1-5), dueDate (可选), createdAt, updatedAt。” “2.API设计：遵循RESTful风格，使用JSON作为请求/响应体。所有API端点前缀为/api/v1/。” “3.认证与授权：暂不实现用户系统，所有API无需认证，但未来需预留扩展性。” “4.数据存储：使用SQLite数据库，通过Prisma ORM操作。” “5.错误处理：统一错误响应格式：{ error: { code: string, message: string } }。HTTP状态码需准确。”

Claude会调用bigrack_context_add工具，将这些规则分条存储到当前Rack下。现在，这些规则已经成为了项目“长期记忆”的一部分。

4.2 创建开发Project与任务分解

现在，我要开发第一个特性：“用户任务CRUD API”。我不直接开始写代码，而是先创建一个Project来规划它。

# 通过CLI创建Project，并关联到当前git分支（假设分支名为feat/task-crud） bigrack projects create --name "Task CRUD API Implementation" --type feature --description "实现Task实体的创建、读取、更新、删除接口"

创建成功后，系统会返回一个Project ID。此时，我在Claude里可以继续说：

“为当前Project ‘Task CRUD API Implementation’ 分解任务。请帮我创建以下原子任务，并建立依赖关系：” “1. 设计并创建Task数据表的Prisma Schema。” “2. 实现Prisma数据库连接和Task模型的基础Repository类。” “3. 实现GET /api/v1/tasks 列表查询接口（支持分页和过滤）。” “4. 实现GET /api/v1/tasks/:id 单个任务查询接口。” “5. 实现POST /api/v1/tasks 创建任务接口。” “6. 实现PUT /api/v1/tasks/:id 更新任务接口。” “7. 实现DELETE /api/v1/tasks/:id 删除任务接口。” “8. 编写集成测试，覆盖所有CRUD操作。” “依赖关系：任务1是任务2的前置条件。任务2是任务3-7的前置条件。任务3-7可以并行开发。任务8依赖于所有任务3-7完成。”

Claude会调用BigRack的任务创建工具，将这些任务录入系统，并建立清晰的依赖图。我可以通过CLI查看：

bigrack ticket list --project-id <刚才的Project ID>

我会看到一个任务列表，每个任务都有唯一ID、状态（初始为pending）、优先级和依赖项。

4.3 在开发中查询与利用上下文

现在，我开始开发“任务3：实现列表查询接口”。我切换到对应的Git分支，打开代码编辑器。

当我写到控制器层，不确定分页参数应该如何设计时，我直接问Claude：

“根据我们项目的业务规则，实现GET /api/v1/tasks列表接口时，分页逻辑应该怎么设计？查询参数应该有哪些？”

Claude在回答前，会自动地通过MCP调用bigrack_query_context工具，查询与“API设计”、“分页”相关的上下文。它会检索到我之前添加的“遵循RESTful风格”、“API端点前缀”等规则，并结合其通用编程知识，给我一个符合项目规范的建议，比如：

“根据项目规则，API应遵循RESTful风格。建议分页参数使用page(页码，从1开始) 和limit(每页条数，默认20，最大100)。查询参数还可以包括status和priority用于过滤。响应格式应包含data(任务数组)、pagination(包含total, page, limit等信息的对象)。这符合常见的RESTful分页实践。”

> 实操心得：这种交互模式需要一点习惯。你不是在和一个“失忆”的AI对话，而是在和一个“随时能翻阅项目手册”的专家对话。提问可以更直接、更依赖上下文。例如，你可以问：“我们之前定的错误响应格式具体是什么？我在写这个API的错误处理。” AI能立刻找到那条规则并引用。

4.4 更新任务状态与记录进展

当我完成列表查询接口的编码和基础测试后，我告诉Claude：

“请将任务 ‘实现GET /api/v1/tasks 列表查询接口’ 的状态更新为 ‘completed’，并添加一条注释：‘已完成基础实现，支持分页和按状态、优先级过滤。待与前端联调。’”

Claude会调用任务更新工具。这样，项目的进度就被实时跟踪了。我可以通过bigrack ticket list --status in-progress快速查看还有哪些任务在进行中。

当这个Project下的所有任务都标记为completed，这个特性开发就算正式完成了。我可以选择关闭这个Project，或者将其作为模板用于类似的特性的开发。

5. 高级技巧、问题排查与未来展望

经过一段时间的深度使用，我积累了一些超出基础文档的实用技巧，也踩过一些坑。这里分享给你，希望能帮你更顺畅地上手。

5.1 高效使用上下文的技巧

1. 结构化存储胜于大段粘贴：不要一次性粘贴一整篇设计文档。将知识拆解成独立的、原子性的条目。例如，将“认证要求”拆成“JWT令牌有效期”、“刷新令牌机制”、“权限角色定义”等单独存储。这样向量搜索时命中率更高，AI获取的信息也更精准。
2. 善用类型标签：添加上下文时，尽量使用--type参数指定类型，如business_rule,glossary,architecture,api_spec。未来你可以按类型筛选查询，管理起来也更清晰。
3. 为Project添加临时上下文：在开发某个特定Project时，会遇到一些临时约定或实验性方案。务必将其添加到当前Project的上下文中，而不是污染顶层的Rack。Project结束后，这些临时上下文可以随Project一起归档，保持Rack的整洁和稳定。
4. 主动查询，验证记忆：在开始一个复杂模块前，可以主动让AI查询相关上下文。例如：“请查询所有与‘数据库事务’和‘错误处理’相关的业务规则。” 这既能帮你复习，也能测试BigRack的检索效果。

5.2 常见问题与排查指南

> 深度排查：如果遇到奇怪的问题，启用调试日志是终极手段。你可以临时修改配置：bigrack config set logLevel debug，然后重现问题，再去查看~/.bigrack/bigrack.log文件，里面会有详细的执行流程和错误信息。

5.3 对当前Beta版的客观评价与期待

BigRack目前处于Public Beta阶段，这意味着它核心功能已可用，但接口和数据结构可能还会调整。我的使用体会是：

优势：

• 理念超前：精准抓住了AI编程助手在复杂项目中的“记忆短板”痛点。
• 本地化实现：数据完全自主，隐私和安全无忧，离线可用，这对开发者极具吸引力。
• 无缝集成：通过MCP协议与主流工具集成，使用流程自然，无需频繁切换界面。
• 任务管理思维：将任务分解与上下文管理结合，提供了从规划到编码的连贯支持。

当前的限制与注意事项：

• Beta期稳定性：正如其警告所言，数据库Schema可能在更新时变化。切勿将其用于生产环境或作为唯一的知识管理工具，重要资料请同步备份在其他地方。
• 模型能力边界：本地嵌入模型在处理极专业或极长的技术文档时，精度可能无法与OpenAI的text-embedding-3等大型模型相比。但对于日常的开发上下文（代码片段、规则、注释），完全够用。
• 交互以文本为主：目前主要通过CLI和AI聊天框交互，缺乏图形化界面来可视化任务依赖图或浏览所有上下文。期待未来apps/dashboard的成熟。

我个人的期待：

1. 更智能的上下文关联：未来或许能自动关联代码提交、Issue与上下文条目。
2. 团队协作功能：如何让一个团队共享同一个Rack的上下文，同时管理权限和变更历史。
3. 更多的AI助手集成：除了Claude和Cursor，扩展到VS Code Copilot Chat、Windsurf等更多环境。

总的来说，BigRack为AI辅助编程打开了一扇新的大门。它不再让AI作为一个“短暂的、健忘的对话伙伴”，而是将其升级为拥有“项目长期记忆和规划能力”的协作者。尽管还在Beta阶段，但对于那些受困于上下文丢失问题的复杂项目开发者来说，现在就是开始尝试、贡献想法、帮助它成长的最佳时机。你可以从一个小型个人项目开始，体验它如何改变你和AI协同编码的节奏。