Tocket框架：为AI编程助手构建持久化共享记忆，告别会话失忆
1. 项目概述：为AI协作引入“共享记忆”
如果你和我一样，在日常开发中深度依赖像Claude Code、Cursor、Gemini这类AI编程助手，那你一定遇到过这个令人头疼的“失忆”问题：每次新开一个聊天会话，AI助手就像第一次来到这个项目一样，需要你重新解释一遍项目的架构、技术栈、当前正在做什么，甚至刚刚讨论过的决策。当你在多个AI助手（比如用Gemini做架构设计，用Claude Code写实现）之间切换时，情况更糟——它们各自为战，工作重复，甚至可能做出相互冲突的修改。
这背后的根本原因在于，当前AI助手的工作模式是“会话隔离”的。所有的上下文都局限在单次聊天的历史记录里，一旦会话结束或切换，这些宝贵的项目认知就消失了。我们开发者的大脑里有一个关于项目的“心智模型”，但AI助手没有。Tocket这个项目，就是为了解决这个问题而生的。它不是一个全新的AI工具，而是一个工程框架，一个文件协议。它的核心思想极其简单却有力：将项目的“共享记忆”和“协作规则”用纯文本文件的形式，固化在代码仓库里。
简单来说，Tocket在你的项目根目录下引入了一个.context/目录和几个关键的Markdown文件。这些文件构成了项目的“记忆银行”（Memory Bank）。任何能读取文件的AI助手，在开始工作前，都会先读取这个记忆银行，从而“继承”之前所有会话的上下文和进展。这就像为你的AI助手们建立了一个共享的、持久化的“项目维基”，彻底告别了每次都要从头解释的繁琐。
2. 核心设计：文件即协议，无厂商锁定
Tocket最吸引我的设计哲学是它的“无侵入性”和“开放性”。它不要求你安装某个特定的IDE插件，也不绑定任何一家AI服务提供商。它的全部“魔法”都基于一个简单的文件约定。
2.1 记忆银行（Memory Bank）的构成
运行tocket init后，你的项目结构会多出以下核心部分：
your-project/ ├── .context/ # 记忆银行核心目录 │ ├── activeContext.md # 【动态】当前焦点：正在做什么、最近变更、待定决策 │ ├── systemPatterns.md # 【半静态】系统模式：架构、代码规范、设计模式 │ ├── techContext.md # 【半静态】技术上下文：技术栈、构建工具、关键配置 │ ├── productContext.md # 【静态】产品上下文：项目是做什么的、用户是谁、核心价值 │ └── progress.md # 【动态】进展日志：已完成的工作、里程碑、Git提交摘要 ├── TOCKET.md # 【协议】Tocket核心规则（所有AI助手通用） ├── CLAUDE.md # 【指令】Claude Code执行器专用指令（自动生成） └── GEMINI.md # 【指令】Gemini架构师专用指令（自动生成）为什么是Markdown？这是Tocket设计的高明之处。Markdown是人类和AI都能完美阅读和理解的格式。它可读性强，易于版本控制（Git），并且被所有主流AI模型原生支持。这意味着你完全可以用记事本打开并编辑这些文件，而AI助手也能精准解析其中的信息。
各文件的生命周期与更新策略：
activeContext.md：这是最高频更新的文件，相当于项目的“工作记忆”。每次会话开始和结束时都应该更新它，包含“当前任务”、“刚刚修改了哪些文件”、“遇到了什么阻碍”、“下一步计划”等信息。这确保了下一个接手工作的AI（或你自己）能无缝衔接。systemPatterns.md和techContext.md：这些是项目的“长期记忆”。它们定义了项目的骨架和血脉。例如，在systemPatterns.md中，我会写明：“本前端项目采用基于React Router的模块化路由结构，所有API调用必须通过src/libs/api-client这个统一封装层”。在techContext.md中，则记录Node版本、包管理器、环境变量命名规则等。这些文件只在架构或技术栈发生重大变更时才需要更新。productContext.md：这是项目的“初心”。它解释了为什么这个项目存在，解决了用户的什么痛点。这份文档对于新加入项目的开发者或AI理解业务逻辑至关重要，通常很少变动。progress.md：这是项目的“日志簿”。Tocket CLI的tocket sync命令可以自动将最近的Git提交记录整理并追加到此文件，形成可追溯的工作历史。
实操心得：不要试图在初始化时就填满所有文件。从
activeContext.md和systemPatterns.md开始最为高效。在第一次使用AI进行实质性开发任务时，边做边记录，这些文件会自然生长。强迫症似的追求“完美初始化”反而会成为一种负担。
2.2 三角定位法：架构师与执行器的分离
对于复杂任务，Tocket推荐采用“三角定位”工作流。这不是必须的，但对于大型重构或功能开发，它能极大提升决策质量和实现一致性。
这个模式将角色分为两类：
- 架构师：通常由更擅长宏观思考和设计的AI（如Gemini 1.5 Pro、Claude-3 Opus）担任。它的职责是分析需求、查阅记忆银行、设计解决方案，并输出一份结构化的
<payload>XML文件。这份文件不包含具体代码，而是清晰的指令：要修改哪些文件、每个文件的修改意图、验收标准是什么。 - 执行器：通常由更擅长代码生成的AI（如Claude Code、Cursor）担任。它接收架构师生成的
payload.xml，结合记忆银行中的上下文，严格按计划执行代码编写任务。
这个流程的精妙之处在于“关注点分离”和“契约驱动”。架构师专注于“做什么”和“为什么”，而不陷入代码细节；执行器专注于“怎么做”，而不需要重新思考架构。payload.xml就是两者之间不可篡改的契约。工作完成后，你可以使用tocket diff命令，自动对比payload.xml中指定的目标文件与Git实际变更的文件，来验证执行器是否严格遵循了架构师的规划。
一个简化的payload.xml示例：
<payload> <scope> <task id="auth-refactor"> <target>src/auth/AuthProvider.jsx</target> <target>src/auth/useAuth.js</target> <intent>将上下文认证逻辑从Redux迁移至React Context，并封装自定义Hook。</intent> <done>useAuth Hook可被任何组件导入；AuthProvider包裹根组件；原Redux相关认证代码已移除。</done> </task> </scope> </payload>注意事项：对于日常的bug修复或小型功能添加，完全可以让一个AI助手同时扮演两种角色。三角定位法更适合那些牵一发而动全身、需要深思熟虑的变更。你可以通过
tocket config --architect “Gemini” --executor “Claude Code”来配置你偏好的角色分配。
3. 从零开始：安全地引入Tocket到现有项目
直接在生产分支上运行陌生的工具总是令人担忧。Tocket团队显然深谙此道，他们提供了一套非常“Git友好”的安全上手流程。
3.1 初始化与试运行
我强烈建议你在一个专门的分支上开始Tocket初体验：
# 1. 创建一个试验分支 git checkout -b experiment/tocket-integration # 2. 最小化初始化（仅创建最核心的3个文件） npx @pedrocivita/tocket init --minimal--minimal参数非常实用，它只创建.context/activeContext.md、.context/systemPatterns.md和TOCKET.md这三个最基础的文件，避免一开始就被大量文件吓到。
初始化完成后，花点时间编辑这两个.md文件。在activeContext.md里，用一两句话描述你接下来一小时打算用AI做什么（比如：“优化用户登录页面的表单验证逻辑”）。在systemPatterns.md里，写下项目最重要的两三条架构约定。
3.2 配置你的AI助手
接下来，告诉Tocket你常用哪些AI，以及你希望它们扮演什么角色：
# 运行交互式配置向导 npx @pedrocivita/tocket config向导会引导你完成几个部分：
- 身份：设置默认作者名，这会被记录在进度文件中。
- 代理角色：选择你常用的AI工具作为“架构师”和“执行器”。例如，我设置
Architect: Gemini,Executor: Cursor。 - Payload默认值：设置任务的默认优先级、技能标签等。
配置完成后，Tocket会自动在你的项目根目录生成对应的指令文件。如果你设置了Cursor为执行器，就会生成.cursorrules；如果设置了GitHub Copilot，就会更新或创建.github/copilot-instructions.md。这些文件的内容不是随机的，而是Tocket根据你的项目上下文（如检测到的技术栈）和最佳实践预生成的模板，为你省去了从头编写AI指令的麻烦。
3.3 进行第一次“有记忆”的AI会话
现在，打开你的AI助手（比如Cursor）。由于.cursorrules文件已经存在，Cursor会自动读取其中的指令。这些指令的核心第一条就是：“在开始任何工作前，请先阅读.context/目录下的所有Markdown文件以了解项目上下文。”
你会发现，你不再需要输入“这是一个React项目，使用TypeScript，状态管理用Zustand...”。AI助手已经知道了。你可以直接切入正题：“基于activeContext.md里描述的表单验证优化任务，请检查src/components/LoginForm.tsx当前的实现，并提出具体的优化方案。”
3.4 会话结束后的关键一步：同步与交接
任务完成后，千万不要直接关闭聊天窗口。这是固化记忆的关键时刻。
- 更新上下文：手动或引导AI助手更新
.context/activeContext.md。例如，添加一节“【已完成】”，总结刚才的修改；并更新“【当前焦点】”为下一个任务。 - 同步进展：运行
tocket sync命令。这个命令会做两件很棒的事：首先，它会将最近的Git提交记录（包括提交信息）自动整理并追加到.context/progress.md中，形成历史日志。其次，它提供了一个交互提示，让你输入本次会话的文本总结，这部分总结也会被记录下来。 - 生成交接简报：如果你要结束今天的工作，或者想把任务交给另一个AI（或未来的自己），运行
tocket handoff。这个命令会生成一份浓缩的上下文摘要（包含当前焦点、近期变更、系统模式要点），并直接复制到你的系统剪贴板。当你明天打开一个新的AI聊天窗口时，直接粘贴这份摘要，就能瞬间让AI“回到工作状态”。
3.5 安全退出机制
试用了几天，觉得不适合你的工作流？Tocket提供了干净的退出方式：
# 一键移除所有Tocket引入的文件（会要求确认） npx @pedrocivita/tocket eject # 或者，更简单粗暴，直接删除实验分支 git checkout main git branch -D experiment/tocket-integration你的主分支代码库将恢复如初，就像Tocket从未存在过一样。这种零残留的设计让人非常安心。
4. 高级工作流与故障排查
当你熟悉了基础循环后，Tocket的一些高级功能可以进一步提升团队协作和工程化水平。
4.1 集成到团队工作流与CI
Tocket文件是纯文本，天生适合Git。这意味着：
- 代码评审：对
.context/下文件的修改，尤其是systemPatterns.md（架构变更）和techContext.md（技术栈变更），应该像代码变更一样接受评审。 - 新人/新AI上手：新成员克隆仓库后，AI助手通过读取
.context/就能立刻获得对项目深度的、一致的理解，极大降低 onboarding 成本。 - CI检查：你可以编写简单的CI脚本，利用
tocket validate和tocket lint命令来检查上下文文件的完整性和质量。
# 在CI脚本中示例 - name: Validate Tocket Context run: npx @pedrocivita/tocket validate # 此命令会检查必要的上下文文件是否存在且内容有效 - name: Lint Context for Quality run: npx @pedrocivita/tocket lint # 此命令会分析内容，给出改进建议，如“activeContext.md超过一周未更新，可能已过时”4.2 常用命令详解与场景
除了基础的init,sync,handoff，这些命令在日常中非常实用：
tocket focus “重写用户数据导出模块”：快速更新activeContext.md中的当前焦点，无需手动打开文件编辑。tocket status：给你一个仪表盘式的快速概览，显示项目分支、当前焦点、配置的代理角色以及记忆银行健康状态（如文件最后更新时间）。tocket doctor：这是深度诊断工具。它会检查诸如“productContext.md文件是否为空”、“progress.md是否已经很久没有新的Git日志同步”等问题，并给出修复建议。tocket generate --to payload.xml：当你准备启动一个三角定位任务时，此命令会引导你（或你的架构师AI）交互式地生成一个结构化的payload.xml文件。它甚至可以基于当前的Git状态，智能地建议可能相关的文件作为修改目标。
4.3 常见问题与解决思路
在实际使用中，你可能会遇到以下情况：
问题1：AI助手似乎忽略了.context/文件。
- 排查：首先确认对应的指令文件是否已正确生成。例如，对于Cursor，检查项目根目录是否有
.cursorrules文件。然后，打开该文件，确认其内容是否包含引导AI优先读取.context/的指令。 - 解决：可以手动在AI会话的开头，直接粘贴
tocket handoff --to stdout命令的输出，强制注入上下文。同时，检查tocket config的配置是否正确。
问题2：activeContext.md文件变得冗长混乱。
- 解决：这是正常现象。建议将其视为一个“滚动日志”。定期（如每周）将已彻底完成或无关的任务描述移动到
.context/progress.md的底部，并在activeContext.md中仅保留最新的、活跃的焦点任务。Tocket的tocket lint命令也会对此给出提醒。
问题3：多人在同一项目中使用Tocket，上下文冲突了怎么办？
- 解决：这正是Git擅长处理的。将
.context/目录纳入版本控制。当多人同时更新上下文时（比如都修改了activeContext.md），会产生Git合并冲突。像解决代码冲突一样解决它：沟通、合并双方的更新，确保合并后的上下文文件依然清晰、一致。这实际上促进了团队对项目状态的沟通。
问题4：Payload中的任务，执行器没有完全完成。
- 解决：使用
tocket diff命令。它会清晰列出payload中计划修改的文件与Git实际变更的文件之间的差异。如果有关键文件未被修改，你可以将这份diff报告反馈给执行器AI，要求它继续完成。这为AI工作提供了可验证的闭环。
5. 自定义与扩展：让Tocket适应你的团队
Tocket的默认配置已经足够好用，但它也提供了充分的扩展性。
5.1 自定义代理指令模板
如果你对自动生成的CLAUDE.md或.cursorrules内容不满意，或者你的团队有特殊的AI使用规范，你可以创建自定义模板。
- 在用户主目录下创建模板目录：
mkdir -p ~/.tocket/templates - 复制默认模板进行修改：
# 首先找到默认模板位置（通常在npm全局安装目录下，或查看项目源码） # 更简单的方式：运行 `tocket init` 后，将生成的 CLAUDE.md 复制到模板目录并重命名 cp /path/to/your/project/CLAUDE.md ~/.tocket/templates/CLAUDE.md.custom - 编辑
~/.tocket/templates/CLAUDE.md.custom文件，加入你们团队的特定要求，例如：“所有生成的React组件必须使用命名导出而非默认导出”。 - 此后，当你运行
tocket init或tocket config时，Tocket会优先使用你的自定义模板。
5.2 与非标准AI工具集成
你的团队可能在使用其他AI编码工具，或者内部开发的助手。只要这个工具能读取文件，就能与Tocket集成。
方法很简单：为这个工具创建一个指令文件。例如，如果你用的工具叫 “CodePilot”，你可以在项目根目录创建一个CODEPILOT.md文件，内容如下：
# CodePilot 项目指令 在开始回答任何问题或执行任何代码修改前，**你必须**首先阅读并理解本项目 `.context/` 目录下的所有Markdown文件。这些文件包含了项目的完整上下文、架构和当前工作状态。 你的所有建议和代码都必须严格遵循 `.context/systemPatterns.md` 中定义的架构模式，并基于 `.context/activeContext.md` 中描述的当前焦点进行工作。 项目核心信息摘要： - 技术栈: [从 techContext.md 提取] - 当前核心任务: [从 activeContext.md 提取]然后，你需要手动确保你的AI工具在启动时加载这个指令文件。这样，你就将它接入了Tocket的上下文生态系统。
经过一段时间的深度使用，Tocket已经从一个小工具变成了我项目开发基础设施中不可或缺的一环。它带来的最大改变，是让AI辅助编程从“一次性的、随机的对话”变成了“可累积的、系统性的协作”。项目知识不再消散于聊天历史中，而是沉淀为团队资产。无论是自己隔天继续工作，还是新同事加入，都能立刻站在前人的肩膀上开始。它没有引入任何复杂的技术栈，仅仅通过文件和约定，就巧妙地解决了AI时代软件开发中的一个核心协作难题。如果你也在频繁使用多个AI进行开发，我强烈建议你花半小时，在一个功能分支上尝试一下Tocket，这种“有记忆”的编程体验，真的回不去了。