claude-smart是什么:让Claude Code、Codex与OpenCode越用越聪明的AI自我学习插件完整指南
claude-smart是什么:让Claude Code、Codex与OpenCode越用越聪明的AI自我学习插件完整指南
claude-smart 是一款面向 Claude Code、Codex 和 OpenCode 的 AI 自我学习插件,它能把你的每一次"纠错"自动沉淀为可复用的偏好(Preferences)与技能(Skills),让编码助手在之后的会话中不再犯同样的错误。只需一条 npx claude-smart install 命令完成安装,无需手动编写任何规则。
🧠 什么是 claude-smart?
用一句话概括:claude-smart 是让你的 AI 编码助手"越用越聪明"的自改进插件。
大多数记忆类插件只是"记录"你说过什么;而 claude-smart 专注于"学习"——它把你纠正 AI 的过程提炼成结构化、可执行的规则,在下次你提出相关请求时自动注入上下文。例如:
- 你纠正过一次"这个仓库要用
pnpm dev:all而不是npm run dev" - 下次新会话中,助手直接沿已验证的路径启动,省去反复试错
- 同一类错误纠正两次,规则会自动合并、精炼,库变得"更锋利"而不是"更臃肿"
官方基准测试显示:在与同类记忆插件的 32 个场景对比中,claude-smart 在纠错类场景的召回得分是 3.00 vs 0.88,整体得分 2.84 vs 1.91(详见 EXPERIMENT.md 与 benchmarks/memory_comparison/)。
⚡ 学习 vs 记忆:claude-smart 到底有什么不同
| 对比维度 | 传统记忆插件 | claude-smart |
|---|---|---|
| 纠错处理 | 只记录"发生过什么" | 提炼成下次能直接遵循的规则 |
| 已验证流程 | 每次会话重新探索 | 记录并优化成功路径,直接复用 |
| 作用范围 | 会话结束即消失 | 项目专属技能 + 跨项目共享技能 |
| 上下文开销 | 历史记录越长越臃肿 | 规则去重后仅占几十个 token |
举例:部署因 Prisma 大版本升级而失败,你让 AI 回滚。 记忆式插件只记下"升级后部署挂了,用户回滚了"; claude-smart 学到的规则是:"ORM/数据库驱动的大版本升级视为破坏性变更——用集成测试验证,而不只是单元测试"。
📚 它构建哪三类学习产物?
claude-smart 在你日常使用时悄悄构建三种产物,并在需要时精准注入 Claude Code、Codex 或 OpenCode 的上下文:
- Preferences(偏好,项目级)——你在这个仓库里的工作方式,如"用 pnpm 不用 npm"、"回答尽量简短"
- Project-specific skills(项目专属技能)——带触发条件和理由的持久规则,如"
npm test必须加--run,否则 watch 模式挂死 CI" - Shared skills(共享技能)——从多个项目中提炼、可跨项目迁移的通用模式,如"集成测试必须用真实 Postgres——mock 曾掩盖过迁移故障"
技能库还会自我清理:重复的纠正自动合并,你改主意后旧规则自动归档。技术细节可查看 ARCHITECTURE.md,核心是由 6 个生命周期钩子(定义在 plugin/hooks/hooks.json)驱动数据流:
用户提示 / 工具调用
→ 写入本地 JSONL 缓冲区
→ 会话节点发布到 reflexio 引擎
→ 提取器生成 偏好 + 项目技能 → 汇总为共享技能
→ 下一次提问时混合检索(向量 + BM25)注入相关命中
🚀 最快上手:一键安装 claude-smart 插件
安装前准备
- Node.js 20+(用于
npx) - 已安装目标宿主 CLI:
claude、codex或opencode,且在PATH中
引导式安装(推荐新手)
npx claude-smart install
向导会引导你完成两件事:
- 选择要集成的编码代理(方向键 + 空格多选,Enter 确认)
- 选择数据存储方式:
- Local Reflexio:在本机启动后台服务,数据全部留在自己的机器上
- Managed Reflexio:指定 HTTPS 端点与 API Key,学习在云端进行,本地不跑后端
安装完成后激活集成:在 Claude Code 会话中执行 /reload-plugins;Codex 开新会话即可;OpenCode 重启一次(加 --global 可对全部项目生效)。
免交互安装(适合 CI 或批量部署)
npx claude-smart install --host claude-code,codex --backend local --provider codex
常用参数速查:
| 参数 | 作用 |
|---|---|
--host |
指定宿主,可逗号分隔多个(claude-code,codex,opencode) |
--backend |
local(本机)或 managed(云端) |
--provider |
本地模式下用于后台学习的代理 CLI |
--yes |
跳过交互确认 |
--read-only |
只读取已学习记忆,不发布新交互 |
检查与卸载
npx claude-smart status # 查看已安装版本
npx claude-smart uninstall --host codex # 仅移除指定宿主集成
卸载不会删除 ~/.reflexio/ 与 ~/.claude-smart/ 下已学习的数据,换宿主也不丢技能。
🖥️ 仪表盘:可视化查看你的 AI 学到了什么
claude-smart 自带一个 Web 仪表盘(默认 http://localhost:3001),可以浏览会话历史、检查偏好、编辑项目技能与共享技能。在 Claude Code 里执行 /claude-smart:dashboard 即可自动启动并打开浏览器;源码位于 plugin/dashboard/。
偏好(Preferences)页面——项目级偏好一览,可直接编辑或删除:
技能(Playbooks)页面——从纠正中跨会话学到的规则,标注了 CURRENT 状态与提炼理由:
仪表盘默认使用 Local 数据源;若配置了 Managed 云端,可在 Data source 下拉中切换查看云端汇总。
⌨️ 5 个常用命令:从查看到强制学习
claude-smart 以斜杠命令(Claude Code)或等价请求(Codex)暴露能力,命令定义在 plugin/commands/:
| Claude Code 命令 | 作用 |
|---|---|
/claude-smart:dashboard |
打开仪表盘(未启动则自动拉起后端服务) |
/claude-smart:show |
打印当前项目技能、共享技能与偏好,随时审计学习状态 |
/claude-smart:learn [备注] |
手动把上一轮标记为"纠正",并立即触发一次提取 |
/claude-smart:restart |
重启 reflexio 后端与仪表盘(升级插件后推荐执行) |
/claude-smart:clear-all |
⚠️ 危险操作:清空全部学习数据,重新开始 |
实用技巧:自动启发式偶尔会漏掉你的纠正,这时用 /claude-smart:learn 注意:CI 必须串行跑测试 手动标记,提取器会给予更高权重。在 Codex 中则使用 claude-smart learn with note "..." 的等价请求(映射规则见 plugin/skills/claude-smart/SKILL.md)。
🔍 回复末尾的引用标记怎么理解?
当一条偏好或技能实质性影响了回答时,助手会在末尾追加一行:
✨ claude-smart rule applied: [git 安全规则](http://localhost:3001/rules/s1-123)
点击链接即可跳转到仪表盘查看具体规则,透明度完全可控;不想看到可关闭(CLAUDE_SMART_CITATIONS,详见 DEVELOPER.md)。
🗂️ 数据都存放在哪里?
本地模式下所有数据都在你自己的机器上:
| 路径 | 内容 |
|---|---|
~/.reflexio/data/reflexio.db |
学到的偏好、技能、交互记录(SQLite,可用 sqlite3 查看) |
~/.claude-smart/.env |
钩子与后端读取的配置 |
~/.claude-smart/sessions/*.jsonl |
每会话的本地缓冲,断网时自动落盘,恢复后自动补发 |
~/.claude-smart/backend.log |
后端日志,排查问题先看这里 |
❓ 常见问题(FAQ)
Q:支持哪些环境?远程环境能用吗? Claude Code Cowork、claude.ai/code 网页版、以及无本地钩子的远程 Codex 环境不受支持——它们运行在本地机器之外,无法访问本地后端。
Q:需要额外配置 API Key 吗?
本地模式下不需要。学习循环复用你已登录的宿主 CLI(claude -p 或 codex exec)作为推理提供方。
Q:离线了会丢数据吗? 不会。后端不可达时,钩子把交互缓冲到磁盘 JSONL,下次成功发布时自动排空(见 ARCHITECTURE.md)。
Q:遇到问题去哪查?
先看官方排障指南 TROUBLESHOOTING.md,再附上 ~/.claude-smart/backend.log 提交 Issue。
📌 总结:claude-smart 适合谁?
| 你的情况 | 价值 |
|---|---|
| 同一个错误反复纠正 AI | ✅ 纠错自动变成持久规则 |
| 多个项目、多种编码代理混用 | ✅ 一套数据跨 Claude Code / Codex / OpenCode 共享 |
| 在意隐私 | ✅ 本地模式全程离线存储 |
| 想让助手少走弯路 | ✅ 复用已验证路径,减少 token 与等待 |
claude-smart 核心卖点:把"你教它"的成本一次性付清——纠错即学习,会话即沉淀。现在就用 npx claude-smart install 开始,让你的 AI 编码助手越用越懂你。
项目采用 Apache 2.0 许可证(LICENSE),底层由开源引擎 Reflexio 驱动,核心 Python 实现位于 plugin/src/claude_smart/,测试套件见 tests/。

