claude-smart是什么:让Claude Code、Codex与OpenCode越用越聪明的AI自我学习插件完整指南

原创2026-10-26 17:42:202,205 阅读

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 的上下文:

  1. Preferences(偏好,项目级)——你在这个仓库里的工作方式,如"用 pnpm 不用 npm"、"回答尽量简短"
  2. Project-specific skills(项目专属技能)——带触发条件和理由的持久规则,如"npm test 必须加 --run,否则 watch 模式挂死 CI"
  3. 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

向导会引导你完成两件事:

  1. 选择要集成的编码代理(方向键 + 空格多选,Enter 确认)
  2. 选择数据存储方式:
    • 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)页面——项目级偏好一览,可直接编辑或删除:

claude-smart 仪表盘中的 Preferences 偏好管理页面截图

技能(Playbooks)页面——从纠正中跨会话学到的规则,标注了 CURRENT 状态与提炼理由:

claude-smart 仪表盘中的 Skills 技能管理页面截图

仪表盘默认使用 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/。

登录后查看全文
claude-smart