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工具之间。它明确区分了两种类型的指导跨项目可复用指导这些是与你个人或团队编码习惯、通用技术栈规范相关的规则和技能。例如“所有异步函数必须使用try-catch进行错误处理并记录日志”“组件Props定义必须使用TypeScript接口”。这部分指导是全局共享的。项目特定指导这些是从特定代码库中衍生出的知识。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这个命令会启动一个交互式的终端会话。它会做以下几件事检测环境检查你的系统上是否安装了受支持的AI提供者CLI例如cursor、claude等。它需要至少找到一个以便了解如何与这些工具交互。创建存储目录在你的用户主目录下创建~/.guidance-bank文件夹这是所有数据的家。基础配置可能会询问你一些初始偏好例如默认的规则分类方式、是否启用某些实验性特性等具体交互可能随版本更新而变化。执行成功后你的本地AI指导银行就建立好了。此时银行里几乎是空的只有一些基础的元数据和结构。真正的“财富”——那些规则和技能——需要你后续通过AI代理的工作来积累或者手动进行管理虽然当前CLI对直接编辑的支持有限但你可以通过查看存储文件来理解其格式。3.3 在项目中的工作流集成初始化完成后日常使用就变得非常轻量化和自动化。理想的工作流如下打开项目像往常一样在VSCode或Cursor中打开你的项目文件夹。代理感知当你启动集成了gbank的AI代理例如在Cursor中开启Composer模式并开始编程会话时代理会自动尝试解析当前项目的gbank上下文。引导创建如果代理发现当前项目还没有关联的指导银行它很可能会在对话中提示你“检测到该项目尚未配置AI指导银行是否要基于当前项目结构创建初始规则集” 你确认后代理便会调用gbank的API创建一个项目专属的指导文件并可能基于对项目代码的初步分析注入一些基础规则例如识别出是Next.js项目则加入关于app/或pages/路由的规则。持续交互在接下来的编码过程中代理会持续参考这个银行里的规则。例如当你要求它“创建一个新的用户服务模块”时它会自动应用银行中关于“服务层应放在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 项目初始化与银行创建使用create-next-app创建新项目。在项目根目录通过Cursor打开。当Cursor Agent启动时它检测到没有gbank项目文件。Agent提示“这是一个新的Next.js 14项目。是否要为其初始化AI指导银行并基于技术栈生成初始规则” 你选择“是”。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时神奇的事情发生了Agent首先加载了所有全局规则如TypeScript规范、React Hooks规则。然后它可能会基于项目相似性检测到next.config.js、prisma/schema.prisma智能推荐从第一个项目中导入一些相关的项目规则和技能例如关于Prisma的使用规范和API响应格式规则。你只需点击确认这些经过实战检验的指导就瞬间注入新项目让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作为一个新兴工具尚处于早期阶段存在一些局限依赖代理的智能其威力很大程度上取决于集成它的AI代理有多“聪明”。一个被动的、只会读取文件的代理和一个主动的、能分析代码、建议新规则、优化旧规则的代理带来的体验是天壤之别。目前你需要选择那些对gbank有良好支持或预留了扩展接口的代理。手动管理成本虽然目标是自动化但在初期你可能需要一定程度地手动审查AI代理建议存入的规则确保其准确性和有效性避免垃圾信息入库。规则冲突与优先级缺乏可视化的规则管理界面和冲突检测机制。当规则库变得庞大时管理复杂度会上升。知识抽象程度如何从具体的代码修改中抽象出普适性强的规则或技能而不是简单的操作记录这对AI和用户都是挑战。应对策略从小处着手。不要试图一开始就建立一个庞大的规则库。从一个项目、几条核心规则开始比如代码风格、项目结构观察AI代理如何应用它们再逐步扩展。把gbank视为一个需要你和AI共同“训练”和“修剪”的智慧树。6.3 生态展望与个人实践建议从项目路线图来看gbank的愿景远不止于本地文件管理。它指向了一个更协作、更智能的未来团队共享未来的gbank可能支持将团队认可的规则库同步到私有服务器或Git仓库实现团队编码规范的统一和自动化传承。成本与效能分析通过分析规则被触发的频率和上下文gbank或许能给出洞察“哪条规则最常被违反”、“哪些技能节省了最多的提示词Token”从而量化AI辅助开发的ROI。可视化与交互一个图形化的规则编辑器、关系图谱和调试工具会让管理复杂的指导体系变得容易。对于现在的你我的建议是立即开始使用但保持耐心和批判性思维。将它应用到你的下一个个人或实验性项目中。观察它如何改变你与AI编程助手的互动模式。你的使用反馈和模式探索本身就是塑造这类工具未来的重要力量。记住最好的“指导银行”不是一蹴而就的而是在一个个真实的编码决策中由你和你的AI伙伴共同沉淀下来的。