Claude Subconscious 概览
理解后台 AI 代理如何通过 Letta Code SDK 增强你的编码体验——从理念到实现
什么是 Claude Subconscious?
想象你在专注编码的时候,有一个隐形的助手在后台默默观察你的代码编辑、理解你的项目结构、记住你的编码习惯——然后在关键时刻轻声提醒你:"这里可能有更好的写法"或者"上次你在这个模块遇到过类似的 bug"。
这就是 Claude Subconscious 的核心理念——让 AI 代理像你的"潜意识"一样工作,不需要你主动提问,它就能理解上下文并给出有价值的建议。
人类的潜意识在后台持续处理信息——整理记忆、识别模式、酝酿创意。你不会意识到它在工作,但它的影响无处不在。Claude Subconscious 就是编码世界的"潜意识":后台代理持续监听你的编码活动,积累项目知识,在你需要的时候提供精准的建议。
持续观察
后台代理通过 Letta Code SDK 监听 Claude Code 的所有交互事件——包括文件编辑、终端命令、对话内容。不需要额外操作,完全被动感知。
学习记忆
代理拥有持久记忆系统,跨会话积累项目知识、用户偏好和编码模式。每次新会话都能利用历史积累,而不是从零开始。
上下文建议
基于观察和学习到的上下文,在合适的时机提供代码改进建议、Bug 预警或最佳实践提示。建议通过 Claude Code 的交互界面呈现。
工具访问
代理可以访问项目文件系统、运行终端命令、查询 API 文档。这让它能提供比单纯文本建议更深层次的辅助,如自动运行测试验证建议。
Letta Code SDK:插件开发的基础
Letta Code SDK 是 Claude Subconscious 的技术基础。它提供了一套标准化的 API,让开发者可以构建与 Claude Code 深度集成的 AI 代理插件。
Letta Code SDK 遵循事件驱动架构:你的代理注册感兴趣的事件(如文件编辑、对话开始),SDK 在这些事件发生时调用你的回调函数。代理可以通过 SDK 的工具接口执行操作(如读取文件、写入代码)。
import { LettaClient, Agent } from '@letta-ai/sdk';
// 初始化 Letta 客户端
const client = new LettaClient({
apiKey: process.env.LETTA_API_KEY,
baseUrl: process.env.LETTA_SERVER_URL
});
// 创建后台代理
const agent = new Agent(client, {
name: 'claude-subconscious',
description: '后台编码助手,观察并学习编码模式',
tools: ['read_file', 'write_file', 'run_command'],
memory: {
type: 'persistent', // 持久化记忆
maxSize: 10000 // 最大记忆条目数
}
});
Letta Code SDK 的初始化过程:
- LettaClient:与 Letta 服务端的连接客户端,需要 API Key 和服务器地址
- Agent 配置:定义代理的名称、描述和可用工具
- 工具列表:代理可以使用的操作——读文件、写文件、运行命令
- 持久记忆:跨会话保存知识,maxSize 控制记忆容量
课程学习路线
本课程将带你从理解概念到实际搭建一个后台 AI 代理。每个模块都包含可运行的代码示例和实践练习。
Claude Subconscious 的核心理念是什么?
核心概念
深入理解后台代理的生命周期、记忆系统架构和工具访问机制
后台代理的生命周期
一个后台代理从创建到销毁,经历完整的生命周期。理解每个阶段的状态变化,是掌握 Claude Subconscious 工作原理的关键。
class SubconsciousAgent {
// 代理核心工作流程
async lifecycle() {
// 1. 初始化:加载配置和工具集
await this.loadConfig();
await this.registerTools();
// 2. 进入事件循环
while (this.isActive) {
// 监听 -> 感知 -> 思考 -> 行动 -> 记忆
const event = await this.observe();
const context = this.recall(event);
const insight = await this.think(event, context);
if (insight.confidence > 0.8) {
await this.whisper(insight);
}
this.remember(event, insight);
}
}
}
代理生命周期的核心循环:
- observe():监听 Claude Code 的编码事件(文件编辑、命令执行)
- recall():从记忆中检索与当前事件相关的历史信息
- think():结合事件和上下文,调用 LLM 进行推理
- whisper():当置信度足够高时,向用户提供建议
- remember():将新获取的信息存入持久记忆
记忆系统架构
记忆系统是 Claude Subconscious 最核心的组件之一。它决定了代理能"记住"多少信息、如何组织这些信息、以及如何在需要时高效检索。
借鉴人类记忆理论,Claude Subconscious 采用三级记忆模型:工作记忆(当前会话的短期上下文)、短期记忆(最近几次会话的信息摘要)、长期记忆(跨所有会话的持久知识)。这种分层设计在记忆容量和检索效率之间取得平衡。
工作记忆(Working Memory)— 当前会话
短期记忆(Short-term Memory)— 最近会话
长期记忆(Long-term Memory)— 持久知识
工具访问:代理的操作能力
记忆系统让代理能"想",工具系统让代理能"做"。通过 Letta Code SDK 的工具接口,代理可以实际操作你的开发环境。
文件系统访问
读取项目文件、搜索代码模式、分析文件依赖关系。代理可以理解整个项目的代码结构,提供跨文件的建议。写入操作需要用户确认。
终端命令执行
运行测试、检查代码风格、查看 Git 状态等。代理可以在提供建议前先运行测试验证,确保建议的正确性。危险命令需要用户确认。
语义搜索
在代码库中进行语义搜索,找到与当前编辑相关的代码片段和文档。利用向量索引实现毫秒级的相似度搜索。
外部 API 调用
查询文档 API、搜索 Stack Overflow、获取包的最新版本信息等。扩展代理的知识范围,使其建议更加准确和及时。
在三级记忆模型中,"编码模式库"属于哪一层记忆?
实践应用
从安装配置到自定义代理开发——动手构建你的编码潜意识助手
插件安装与配置
将 Claude Subconscious 集成到你的开发环境只需要几步。让我们从安装开始,逐步配置到最佳状态。
安装前确保你已有:1) Claude Code CLI 已安装并登录;2) Letta API Key(从 Letta AI 官网获取);3) Node.js 18+ 运行时。Claude Subconscious 作为 Claude Code 插件运行,不需要独立启动。
# 步骤 1: 克隆仓库
git clone https://github.com/letta-ai/claude-subconscious.git
cd claude-subconscious
# 步骤 2: 安装依赖
npm install
# 步骤 3: 配置环境变量
cp .env.example .env
# 编辑 .env,填入:
# LETTA_API_KEY=your_api_key
# LETTA_SERVER_URL=https://api.letta.com
# LETTA_MODE=observe (observe=silent, assist=proactive)
# 步骤 4: 启用插件
claude plugin enable .
# 步骤 5: 验证安装
claude plugin list # 应显示 subconscious (active)
安装过程的五个步骤:
- 克隆仓库:从 GitHub 获取最新版本的插件代码
- 安装依赖:npm install 安装 Letta SDK 和其他依赖
- 环境配置:.env 文件存储 API Key 和运行模式
- 启用插件:通过 Claude Code 的插件系统注册
- 验证安装:确认插件已正确注册并处于活动状态
自定义事件监听器
Claude Subconscious 的核心是事件监听器。通过注册不同的监听器,你可以自定义代理对哪些事件做出反应,以及如何反应。
文件编辑事件
监听文件保存和修改事件。代理可以分析代码变更,检测潜在 Bug、建议改进或记录编码模式。最常用的事件类型。
终端命令事件
监听终端命令执行和输出。代理可以从错误信息中学习,下次遇到类似错误时主动提醒。也可以从成功命令中提取模式。
对话交互事件
监听用户与 Claude Code 的对话内容。代理可以从对话中提取用户意图和偏好,优化后续的交互体验。
import { Agent, EventTypes } from '@letta-ai/sdk';
class CodeReviewListener {
constructor(private agent: Agent) {}
// 监听文件保存事件
@on(EventTypes.FILE_SAVE)
async onFileSave(event: FileSaveEvent) {
const changes = await this.diff(event.filePath);
// 分析代码变更
const analysis = await this.agent.think({
prompt: `分析以下代码变更,检测潜在问题:
文件: ${event.filePath}
变更: ${changes}`,
context: this.agent.recall(event.filePath)
});
// 高风险时立即提醒
if (analysis.riskLevel === 'high') {
await this.agent.whisper({
message: analysis.warning,
priority: 'high'
});
}
// 记录到记忆系统
this.agent.remember({
type: 'code_change',
file: event.filePath,
summary: analysis.summary
});
}
}
自定义事件监听器的开发模式:
- @on 装饰器:声明式地注册事件处理器,代码简洁清晰
- diff 分析:只分析变更部分,减少不必要的计算
- agent.think():调用 LLM 进行智能分析,传入文件路径和变更内容
- 优先级提醒:高风险问题立即通知,低风险可以聚合后批量提醒
- 记忆存储:将分析结果存入记忆,供后续推理使用
构建自定义代理
除了使用默认的后台代理,你还可以基于 Letta Code SDK 构建完全自定义的代理,专注于特定的工作流。
好的代理设计遵循三个原则:单一职责(一个代理专注一个任务)、最小权限(只请求必要的工具权限)、优雅降级(工具不可用时仍能提供文本建议)。不要试图构建一个"万能"代理。
class TestSuggestAgent extends Agent {
"""自动建议测试的专用代理"""
name = 'test-suggester';
tools = ['read_file', 'run_command'];
async onFileSave(event: FileSaveEvent) {
// 只处理源代码文件
if (!event.filePath.match(/\.(ts|js|py)$/)) return;
// 检查是否已有对应测试文件
const testPath = this.getTestPath(event.filePath);
const hasTest = await this.tools.read_file(testPath);
if (!hasTest) {
const code = await this.tools.read_file(event.filePath);
const testCode = await this.generateTest(code);
await this.whisper({
message: `检测到 ${event.filePath} 没有测试。建议添加:`,
suggestion: testCode
});
}
}
}
自定义代理的设计要点:
- 单一职责:这个代理只做一件事——检测缺少测试的文件并建议测试代码
- 最小权限:只需要读取文件和运行命令两个工具
- 文件类型过滤:只处理源代码文件,忽略配置文件等
- 非侵入式:只提供建议,不自动创建文件
如果你想让代理在检测到 TypeScript 文件缺少测试时自动建议测试代码,应该监听什么事件?
进阶主题
多项目管理、模型配置、性能优化和调试技巧——代理开发的高阶实践
多项目环境下的代理管理
开发者通常同时维护多个项目。Claude Subconscious 支持一个代理服务多个项目,同时保持项目上下文隔离。
全局层 — 共享代理实例
项目层 — 独立会话上下文
模型配置与性能优化
选择合适的模型并进行性能优化,是代理开发中的重要技能。不同的任务需要不同的模型配置策略。
代理的性能瓶颈通常在 LLM 调用。优化策略包括:1) 减少调用频率——合并相似事件,避免每次文件保存都调用 LLM;2) 使用轻量模型——简单判断用 Haiku,复杂推理用 Sonnet;3) 缓存推理结果——相似代码模式复用之前的分析结果。
class OptimizedAgent extends Agent {
private eventBuffer: Event[] = [];
private analysisCache = new Map<string, Analysis>();
async onFileSave(event: FileSaveEvent) {
// 1. 事件合并:积累 5 秒内的变更
this.eventBuffer.push(event);
await this.debounce(5000);
// 2. 缓存检查:相似代码复用分析
const cacheKey = this.hashChanges(event);
if (this.analysisCache.has(cacheKey)) {
return this.analysisCache.get(cacheKey);
}
// 3. 模型路由:简单判断用 Haiku
const model = event.isComplex
? 'claude-sonnet-4-20250514'
: 'claude-haiku-4-20250414';
// 4. 批量分析
const analysis = await this.batchAnalyze(
this.eventBuffer, { model }
);
this.analysisCache.set(cacheKey, analysis);
this.eventBuffer = [];
return analysis;
}
}
代理性能优化的四个关键策略:
- 事件合并(Debounce):5 秒内的多次文件保存合并为一次分析
- 缓存复用:相似的代码变更直接返回缓存结果
- 模型路由:简单变更用 Haiku(快+便宜),复杂变更用 Sonnet(精准)
- 批量处理:将积压的事件一起发送给 LLM,减少 API 调用次数
代理调试与监控技巧
开发代理时,调试是不可避免的。Claude Subconscious 提供了多种调试工具和日志系统,帮助你快速定位问题。
结构化日志
代理的所有行为都记录在 ~/.letta/claude-subconscious/logs/ 目录下。日志包含时间戳、事件类型、LLM 输入/输出、工具调用结果等完整信息,支持 JSON 格式导出。
性能指标
内置性能指标收集:每次 LLM 调用的延迟、token 消耗、缓存命中率。通过 /subconscious stats 命令查看实时统计,帮你识别性能瓶颈。
记忆检查器
通过 /subconscious memory 命令查看代理当前的记忆内容,包括工作记忆、短期记忆和长期记忆的详细条目。帮助理解代理为什么给出特定的建议。
在多项目环境中,代理如何区分不同项目的上下文?
总结与练习
回顾核心知识,通过综合练习巩固技能,探索代理开发的更多可能
核心知识回顾
让我们快速回顾本课程最重要的知识点,确保你已经掌握了 Claude Subconscious 的核心概念和实践技能。
代理生命周期
创建 → 初始化 → 监听 → 感知 → 思考 → 行动 → 记忆 → 循环。关键在于 observe → think → whisper 的闭环,让代理持续从编码活动中学习和改进。
三级记忆模型
工作记忆(当前会话事件流)→ 短期记忆(最近 10 次会话摘要 + 编码模式库)→ 长期记忆(用户偏好 + 项目知识图谱)。分层设计平衡容量与效率。
工具与安全
文件系统访问、终端命令执行、语义搜索、外部 API 调用。核心原则:最小权限 + 用户确认 + 非侵入式。危险操作永远需要用户明确授权。
性能优化策略
事件合并(Debounce)、缓存复用、模型路由(Haiku/Sonnet 分层)、批量处理。四大策略协同降低 70% 的 LLM 调用开销。
代理开发最佳实践
综合练习:构建代码审查代理
设计一个代码审查代理,能在开发者保存文件时自动分析代码质量,提供改进建议。需要综合运用事件监听、记忆系统和工具访问。
构建一个代理,具备以下能力:1) 监听文件保存事件;2) 读取保存的文件内容;3) 结合记忆中的项目编码规范进行分析;4) 给出代码质量评分和改进建议;5) 将分析结果存入记忆供后续使用。
class CodeReviewAgent extends Agent {
"""代码审查代理 — 请补充完整实现"""
name = 'code-reviewer';
// TODO 1: 注册事件监听器
async onFileSave(event: FileSaveEvent) {
pass
}
// TODO 2: 分析代码质量
async analyzeQuality(code: string): Promise {
pass
}
// TODO 3: 生成改进建议
async generateSuggestions(analysis: Analysis): Promise {
pass
}
// TODO 4: 更新记忆
updateMemory(result: ReviewResult) {
pass
}
}
完成这个练习的思路:
- TODO 1:过滤只处理源代码文件,忽略 node_modules 等
- TODO 2:调用 LLM 分析代码的可读性、性能、安全性
- TODO 3:基于分析结果生成具体的改进代码片段
- TODO 4:将审查结果和项目的编码规范关联存储
下一步:扩展方向
多代理协作
研究多个代理如何协作:一个代理负责代码审查,另一个负责测试建议,第三个负责性能优化。通过代理间的通信协议实现协同工作。
云端代理
将代理部署到云端,实现跨设备的知识同步。你在公司电脑学到的编码习惯,会自动同步到家里的开发环境。
领域专用代理
为特定领域定制代理:前端开发代理(专注 React/Vue 最佳实践)、DevOps 代理(专注 CI/CD 和部署配置)、安全代理(专注安全漏洞检测)。
Claude Subconscious 的核心优势是什么?
代理设计应该遵循哪个原则?