构建AI编程助手的本地记忆库：@morsa/guidance-bank实战指南

1. 项目概述：为你的AI编程伙伴建立一个“记忆中枢”

如果你和我一样，已经深度依赖像Cursor、Claude Code或Codex这类AI编程助手来辅助日常开发，那你一定遇到过这个痛点：每次开启一个新项目，或者换一个AI工具，你都得像个复读机一样，把那些“项目要用TypeScript”、“代码风格要遵循Airbnb规范”、“别动package.json里的私有依赖”之类的规则，一遍又一遍地告诉你的AI伙伴。更糟的是，当你在一个项目里好不容易调教出一个得心应手的“智能副驾”，积累了大量的项目专属提示和最佳实践，这些宝贵的“经验”却像沙滩上的字迹，换一个项目或者重启一次会话，就被潮水冲刷得一干二净。

@morsa/guidance-bank（我们后面就亲切地叫它gbank）就是为了解决这个“AI健忘症”而生的。它本质上是一个本地的、持久化的“AI指导银行”或“记忆库”。你可以把它想象成给你的所有AI编程助手配备了一个共享的、可成长的“第二大脑”。这个大脑不依赖于任何特定的云服务商，就安安静静地待在你的本地机器上，专门用来存储那些跨项目、跨会话、甚至跨不同AI工具都需要用到的规则、技能和项目指导。

它的核心价值在于，将原本碎片化、临时性的AI提示工程，转变为一个可积累、可复用、可管理的资产层。以前，你的项目规范可能散落在AGENTS.md、.cursorrules、.claudeconfig等不同文件里，彼此割裂。现在，gbank提供了一个统一的、规范化的存储中心。无论是要求AI“提交代码前必须运行单元测试”这样的通用规则，还是“本项目使用zustand进行状态管理，请优先使用create函数”这样的项目特定知识，都可以被结构化地存入这个银行。从此，你的AI助手在开始工作前，会先“查阅”这个记忆库，自动加载所有相关的上下文和约束，大大减少了重复提示的成本，也显著提升了AI输出的一致性和质量。

2. 核心设计理念与架构解析

2.1 为何需要独立的“指导层”？

在深入使用之前，理解gbank的设计哲学至关重要。当前主流的AI编程工具，其规则系统大多存在几个根本性限制：

首先是供应商锁定问题。你在Cursor里精心编写的.cursorrules文件，到了Claude Code里完全无效。这意味着你需要为每个工具维护一套独立的规则集，这不仅效率低下，而且当规则需要更新时，你必须在多个地方进行同步，极易出错和遗漏。

其次是规则生成的质量问题。很多工具提供的“自动生成项目规则”功能，其产出往往流于表面。它们可能会扫描你的目录结构，生成类似“src/目录下是源代码，tests/目录下是测试”这样的描述性总结。但这并不是真正的“操作指导”。真正的指导应该源于代码库的实际证据和开发者的真实意图，比如“本项目的API响应统一包装在{ data, code, message }结构体中”，或者“工具函数应放置在lib/utils/下，并优先使用已存在的formatDate方法”。

最后是知识的孤立性与不可复用性。一个在React项目中总结出的关于Hooks使用的最佳实践，无法轻松地应用到下一个React项目中。每个项目都像一座孤岛，AI助手无法携带任何“经验”跨海。

gbank的解决方案是引入一个独立的“指导层”。这个层位于你的本地文件系统（~/.guidance-bank）和上层的各类AI工具之间。它明确区分了两种类型的指导：

1. 跨项目可复用指导：这些是与你个人或团队编码习惯、通用技术栈规范相关的规则和技能。例如，“所有异步函数必须使用try-catch进行错误处理并记录日志”，“组件Props定义必须使用TypeScript接口”。这部分指导是全局共享的。
2. 项目特定指导：这些是从特定代码库中衍生出的知识。gbank鼓励（并计划通过AI代理增强）从真实的项目结构、代码模式、配置文件（如tsconfig.json、eslintrc）中提取出有操作价值的规则，而非简单的目录描述。

这种分离使得通用知识得以沉淀和复用，而项目特定知识也能被结构化地保存，供长期使用。

2.2 架构与数据模型浅析

虽然gbank目前对外是一个命令行工具，但其背后隐含了一个简单的数据模型。理解这个模型有助于你更有效地组织你的指导内容。

在~/.guidance-bank目录下，数据大致被组织为两部分：

• 全局存储区：存放跨项目的共享规则（Rules）和技能（Skills）。你可以把规则看作是“约束”或“规范”，例如代码风格、安全要求；而技能更像是“模板”或“套路”，例如“如何创建一个新的React组件”，“如何添加一个新的API端点”。这部分数据独立于任何具体项目。
• 项目关联区：当你在某个项目目录下运行gbank init或被AI代理初始化后，会为该创建一个项目专属的指导文件（或链接）。这个文件会引用或包含适用于该项目的全局规则，并添加本项目特有的指导条目。

其工作流程设计得非常“被动”和“以代理为中心”。工具本身不主动扫描或强制注入什么，而是提供一个存储和查询接口。真正的主动权在集成了gbank的AI代理（如Cursor）手中。代理在启动时，会去解析当前项目的gbank上下文。如果不存在，它可以提示用户或自动建议创建。在后续的编码会话中，代理可以持续地从这个银行中“提取”指导来约束自己的行为，也可以将本次会话中产生的新经验“存入”银行，实现学习和进化。

注意：截至当前版本，gbank更侧重于提供存储框架和基础CLI。从项目证据中自动提取高质量规则、以及智能化的银行管理（如合并冲突、规则优化）等功能，更多地依赖于接入它的AI代理的能力。你可以将其视为为AI代理赋能的一个“基础设施”，而非一个全自动的规则生成器。

3. 从零开始：安装、初始化与基础操作

3.1 环境准备与全局安装

使用gbank的前提非常简单：你需要一个Node.js环境（建议使用LTS版本）和一个已经安装并配置好的、受支持的AI编程工具（如Cursor、Claude Code等）。

安装过程通过npm进行，推荐全局安装，这样你可以在任何终端位置使用gbank命令：

npm install -g @morsa/guidance-bank

安装完成后，在终端输入gbank --help，如果能看到命令列表，说明安装成功。

实操心得：在团队环境中，可以考虑将gbank的安装写入项目的devDependencies或团队的标准化开发环境配置脚本中，确保所有成员都具备相同的基础工具链。虽然它是全局工具，但通过package.json的scripts钩子或npx来调用，也能保证版本一致性。

3.2 初始化你的第一个AI指导银行

安装后的第一步，也是唯一需要手动执行的设置步骤，就是初始化：

gbank init

这个命令会启动一个交互式的终端会话。它会做以下几件事：

1. 检测环境：检查你的系统上是否安装了受支持的AI提供者CLI（例如cursor、claude等）。它需要至少找到一个，以便了解如何与这些工具交互。
2. 创建存储目录：在你的用户主目录下创建~/.guidance-bank文件夹，这是所有数据的家。
3. 基础配置：可能会询问你一些初始偏好，例如默认的规则分类方式、是否启用某些实验性特性等（具体交互可能随版本更新而变化）。

执行成功后，你的本地AI指导银行就建立好了。此时银行里几乎是空的，只有一些基础的元数据和结构。真正的“财富”——那些规则和技能——需要你后续通过AI代理的工作来积累，或者手动进行管理（虽然当前CLI对直接编辑的支持有限，但你可以通过查看存储文件来理解其格式）。

3.3 在项目中的工作流集成

初始化完成后，日常使用就变得非常轻量化和自动化。理想的工作流如下：

1. 打开项目：像往常一样，在VSCode或Cursor中打开你的项目文件夹。
2. 代理感知：当你启动集成了gbank的AI代理（例如在Cursor中开启Composer模式）并开始编程会话时，代理会自动尝试解析当前项目的gbank上下文。
3. 引导创建：如果代理发现当前项目还没有关联的指导银行，它很可能会在对话中提示你：“检测到该项目尚未配置AI指导银行，是否要基于当前项目结构创建初始规则集？” 你确认后，代理便会调用gbank的API，创建一个项目专属的指导文件，并可能基于对项目代码的初步分析，注入一些基础规则（例如识别出是Next.js项目，则加入关于app/或pages/路由的规则）。
4. 持续交互：在接下来的编码过程中，代理会持续参考这个银行里的规则。例如，当你要求它“创建一个新的用户服务模块”时，它会自动应用银行中关于“服务层应放在src/services/目录下”、“需使用统一的apiClient进行HTTP调用”等规则。同时，如果你在对话中纠正了代理的某个行为（比如“不，这里应该用useMemo而不是useEffect”），一个成熟的代理可能会建议将这条修正作为一条新规则或技能存入银行，供未来参考。

这个流程的核心思想是：让AI代理来驱动银行的管理，而不是让人去手动编写和维护一堆复杂的配置文件。人只需要在关键决策点进行确认和微调。

4. 核心功能详解与高级用法

4.1 规则与技能：存储什么，如何存储？

gbank存储的两类核心内容——规则（Rules）和技能（Skills）——需要被正确理解和使用。

• 规则：这是对AI行为的约束性指令。它们通常以“必须”、“应该”、“禁止”、“确保”等关键词开头，定义了代码生成或修改的边界。

  • 示例（通用规则）：“所有React函数组件必须使用React.FC或显式注解Props类型。”
  • 示例（项目规则）：“本项目使用@tanstack/react-query进行数据获取，禁止直接使用fetch或axios在组件内发起请求。”
  • 规则的目标是保证代码的一致性、安全性和符合既定架构。

• 技能：这是可复用的操作模板或模式。它们更像是一个个“锦囊”，告诉AI如何完成一项特定任务。

  • 示例（通用技能）：“技能：创建Redux Slice。步骤：1. 在src/features/[featureName]/slice.ts创建文件。2. 定义State接口。3. 使用createSlice...”
  • 示例（项目技能）：“技能：添加新的API端点。步骤：1. 在src/pages/api/下创建[endpoint].ts。2. 导入withMiddleware进行鉴权。3. 使用NextApiResponse和NextApiRequest类型...”
  • 技能的目标是提升效率，确保重复性任务按照最佳实践来完成。

在底层，这些内容很可能以结构化的格式（如JSON或YAML）存储，包含id、type(rule/skill)、content、scope(global/project)、tags(e.g., ‘react‘, ‘security‘, ‘api‘)、createdAt等字段。虽然目前CLI可能不提供丰富的直接编辑功能，但了解这个结构有助于你未来通过脚本或高级工具来批量管理你的知识库。

4.2 使用gbank stats洞察你的记忆库

当你积累了一段时间后，可能会好奇：“我的银行里到底存了多少东西？哪个项目用得最多？”这时，gbank stats命令就是你最好的朋友。

基础用法非常简单：

gbank stats

这会输出一个清晰的文本概览，显示：

• 共享库统计：全局规则和技能的总数。
• 项目库状态：列出了已检测到的、关联了gbank的项目路径，以及每个项目中规则和技能的数量。
• 近期活动：显示最近对银行进行增删改查的事件日志（审计事件）。
• 工具活跃度：一个简单的统计，显示不同AI提供者（如Cursor vs Claude Code）调用银行数据的频率。

对于自动化脚本或更深入的分析，你可以使用JSON格式输出：

gbank stats --json

这将把上述所有数据以JSON格式打印到标准输出，方便你用jq等工具进行解析，或者集成到你的数据看板中。

如果你只想查看某个特定项目的状态，可以指定项目路径：

gbank stats --project /Users/yourname/Projects/your-awesome-app

注意事项：stats命令目前提供的是基础可见性。像“哪些规则最常被触发”、“哪些技能从未被使用”、“规则之间的冲突”等更深入的分析，可能是未来版本的发展方向。现阶段，它主要帮你确认银行在正常工作，并了解大致的知识积累规模。

4.3 与不同AI代理的集成实践

gbank的价值在于其跨提供者的能力。以下是针对当前已支持工具的集成思路：

• Cursor：作为深度集成AI的编辑器，Cursor是gbank最自然的搭档。你可以在Cursor的设置中寻找或通过其AI指令，引导它去读取和写入~/.guidance-bank。一种常见的模式是，在.cursorrules文件中，加入一条基础规则：“在开始编码前，优先查询并应用当前项目的AI指导银行（位于~/.guidance-bank）中的规则。” 这样，Cursor Agent在每次会话初始化时，就会自动加载你的持久化指导。

• Claude Code / Codex：这些通常作为IDE插件或CLI工具存在。集成方式可能略有不同。你可能需要在插件的配置项中指定一个“外部规则文件”或“上下文文件”的路径，并将其指向gbank为当前项目生成的文件。或者，通过编写一个简单的包装脚本，在调用Claude Code之前，先将gbank中的相关规则内容预置到会话的初始提示（System Prompt）中。

• 通用模式：对于任何支持自定义系统提示或上下文文件的AI编程工具，你都可以手动或通过脚本实现集成。核心步骤是：1. 在项目根目录运行gbank相关命令（或由代理自动运行），导出当前项目适用的所有规则和技能。2. 将这些内容格式化后，作为前置上下文注入到AI工具的提示中。这虽然需要一些手动编排，但实现了跨工具的指导统一。

避坑技巧：在初期集成时，建议从一个简单的、无副作用的规则开始测试，例如“所有代码注释必须使用英文”。确保AI代理正确读取并遵守了这条规则后，再逐步添加更复杂的约束。同时，注意规则冲突。如果你在gbank中有一条全局规则“使用双引号”，但在某个项目的.prettierrc中配置了单引号，AI代理可能会困惑。理想的gbank实现应该能处理这种优先级（通常是项目规则 > 全局规则）。

5. 实战场景：构建一个全栈项目的AI指导银行

让我们通过一个虚构的“全栈待办事项应用”项目，来模拟gbank在实际开发中如何积累和使用。

项目栈：Next.js 14 (App Router), TypeScript, Tailwind CSS, Prisma (PostgreSQL), NextAuth.js。

5.1 项目初始化与银行创建

1. 使用create-next-app创建新项目。
2. 在项目根目录，通过Cursor打开。当Cursor Agent启动时，它检测到没有gbank项目文件。
3. Agent提示：“这是一个新的Next.js 14项目。是否要为其初始化AI指导银行，并基于技术栈生成初始规则？” 你选择“是”。
4. Agent调用gbank，创建项目关联，并自动注入一批推断出的规则：
   • 规则ID-001：“本项目使用Next.js 14 App Router。页面组件应放置在app/目录下，使用page.tsx命名。API路由应放置在app/api/目录下。”
   • 规则ID-002：“样式使用Tailwind CSS。禁止内联style属性或创建单独的.css文件，除非绝对必要。”
   • 规则ID-003：“数据库操作通过Prisma Client进行。禁止在API路由或组件中直接编写原始SQL。”

5.2 在开发中持续积累

场景一：定义数据获取模式你在开发第一个API端点app/api/todos/route.ts时，告诉Agent：“按照我们项目的模式，需要验证用户身份，然后用Prisma查询。” Agent完成代码后，可能会建议：“这看起来是我们项目标准的数据获取模式。是否将其保存为一条技能‘创建受保护的CRUD API端点’？”你同意后，这条技能被存入项目银行。

• 技能ID-101：“技能：创建受保护的CRUD API端点。步骤：1. 导入getServerSession和authOptions。2. 在函数开头进行会话检查。3. 使用prisma.[model]进行数据库操作。4. 统一返回NextResponse.json({ data, message })格式。”

场景二：纠正与优化Agent在生成一个组件时，使用了useState来管理一个派生状态。你指出：“这里应该用useMemo来优化性能。” Agent不仅可以修正代码，还可以提议：“是否将‘当状态依赖于其他状态或Props且计算成本高时，优先使用useMemo’添加为一条React性能规则？” 这条规则被添加到银行中，可能同时标记为global（因为适用于所有React项目）和project。

5.3 跨项目复用与银行演化

几周后，你开始第二个Next.js项目。当你用Cursor打开它并初始化gbank时，神奇的事情发生了：

1. Agent首先加载了所有全局规则（如TypeScript规范、React Hooks规则）。
2. 然后，它可能会基于项目相似性（检测到next.config.js、prisma/schema.prisma），智能推荐从第一个项目中导入一些相关的项目规则和技能，例如关于Prisma的使用规范和API响应格式规则。
3. 你只需点击确认，这些经过实战检验的指导就瞬间注入新项目，让AI助手从第一天起就“经验丰富”。

这个过程中，gbank扮演了经验搬运工和模式提取器的角色。它让你在项目间传递的，不是零散的代码片段，而是成体系的、可执行的开发约束和模式。

6. 常见问题、排查与未来展望

6.1 问题排查速查表

问题现象	可能原因	解决方案
运行gbank init失败，提示“No supported provider found”	系统未安装任何受支持的AI提供者CLI（如Cursor、Claude Code）。	1. 确保已安装至少一个支持的工具（如从Cursor官网下载安装）。 2. 确保该工具的CLI命令（如cursor）可以在终端中直接运行（已加入系统PATH）。
AI代理（如Cursor）似乎没有读取银行规则	1. 代理未正确集成gbank。 2. 项目银行文件不存在或路径不对。 3. 代理的上下文窗口未包含银行内容。	1. 检查代理的文档或设置，确认其支持外部指导文件，并已配置指向gbank。 2. 在项目根目录运行gbank stats，确认项目银行已创建且不为空。 3. 尝试在代理的初始指令中明确要求：“请加载并遵循本项目的AI指导银行规则。”
规则之间似乎产生了冲突	一条全局规则和一条项目规则，或者两条项目规则存在矛盾。	1. 审查~/.guidance-bank中的规则文件，定位冲突条目。 2. 目前可能需要手动编辑（如果文件格式可读）或通过未来工具解决。通常，项目特定规则应覆盖全局规则。
gbank stats显示数据，但感觉AI行为未改变	规则可能过于宽泛或描述不清，AI难以准确理解并执行。	优化规则描述，使其更具体、可操作。例如，将“写好代码”改为“函数长度不应超过30行，超过则应考虑拆分为子函数”。
存储文件损坏或格式错误	意外的手动编辑或程序错误导致。	1. 定期备份~/.guidance-bank目录。 2. 尝试使用gbank工具可能提供的修复或重置命令（如果未来版本支持）。 3. 作为最后手段，可删除损坏的文件或整个目录，重新init并依赖AI代理重新积累。

6.2 当前局限性与应对策略

必须承认，gbank作为一个新兴工具，尚处于早期阶段，存在一些局限：

1. 依赖代理的智能：其威力很大程度上取决于集成它的AI代理有多“聪明”。一个被动的、只会读取文件的代理，和一个主动的、能分析代码、建议新规则、优化旧规则的代理，带来的体验是天壤之别。目前，你需要选择那些对gbank有良好支持或预留了扩展接口的代理。
2. 手动管理成本：虽然目标是自动化，但在初期，你可能需要一定程度地手动审查AI代理建议存入的规则，确保其准确性和有效性，避免垃圾信息入库。
3. 规则冲突与优先级：缺乏可视化的规则管理界面和冲突检测机制。当规则库变得庞大时，管理复杂度会上升。
4. 知识抽象程度：如何从具体的代码修改中，抽象出普适性强的规则或技能，而不是简单的操作记录，这对AI和用户都是挑战。

应对策略：从小处着手。不要试图一开始就建立一个庞大的规则库。从一个项目、几条核心规则开始（比如代码风格、项目结构），观察AI代理如何应用它们，再逐步扩展。把gbank视为一个需要你和AI共同“训练”和“修剪”的智慧树。

6.3 生态展望与个人实践建议

从项目路线图来看，gbank的愿景远不止于本地文件管理。它指向了一个更协作、更智能的未来：

• 团队共享：未来的gbank可能支持将团队认可的规则库同步到私有服务器或Git仓库，实现团队编码规范的统一和自动化传承。
• 成本与效能分析：通过分析规则被触发的频率和上下文，gbank或许能给出洞察：“哪条规则最常被违反？”、“哪些技能节省了最多的提示词（Token）？”，从而量化AI辅助开发的ROI。
• 可视化与交互：一个图形化的规则编辑器、关系图谱和调试工具，会让管理复杂的指导体系变得容易。

对于现在的你，我的建议是：立即开始使用，但保持耐心和批判性思维。将它应用到你的下一个个人或实验性项目中。观察它如何改变你与AI编程助手的互动模式。你的使用反馈和模式探索，本身就是塑造这类工具未来的重要力量。记住，最好的“指导银行”不是一蹴而就的，而是在一个个真实的编码决策中，由你和你的AI伙伴共同沉淀下来的。