ECC 持续学习技能全解析从 Stop Hook 模式提取到 v2 本能Instinct架构演进【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC本文以 ECC 仓库中 docs/es/skills/continuous-learning/SKILL.md 为骨架结合仓库内 v1 与 v2 的实际实现源码系统讲解 ECCAgent Harness Performance Optimization System中「持续学习」技能的完整脉络v1 如何通过 Stop Hook 在会话结束时自动提取可复用模式、如何配置与调参以及 v2 如何以「本能Instinct」为原子单位实现更可靠的观察、置信度评分与项目级隔离。读完本文你将掌握在 Claude Code 中配置会话级模式提取、迁移到 instinct 架构并驱动/evolve、/promote等命令的完整实战方案。一、技能现状v1 已过时v2 是唯一推荐路径ECC 的持续学习能力经历了两个版本的迭代。仓库中的 v1 SKILL.md 已在2026-04-28被标记为OBSOLETO过时其 frontmatter 明确要求不要调用 v1将持续学习、会话学习与模式提取请求都导向 continuous-learning-v2。v2 被定义为 v1 的严格超集strict superset三条核心升级对应三个维度的缺陷修复维度v1 做法v2 做法观察方式Stop Hook会话结束时PreToolUse / PostToolUse100% 可靠学习单位完整 skills原子化 instincts带置信度评分存储范围仅全局项目级 全局提升promotion文档保留 v1 文件目的仅是「归档参考」与「对既有安装的向后兼容」。因此本文先完整剖析 v1 的机制这是原文档的主体再顺藤摸瓜展开 v2 的架构实现。二、v1 工作原理Stop Hook 驱动的会话后模式提取v1 的核心定位一句话概括在 Claude Code 会话结束时自动评估会话提取可复用的模式并保存为 learned skills。它作为一个Stop Hook在每次会话末尾触发执行三步流水线会话评估Session Evaluation检查会话是否包含足够多的消息默认阈值10 条以上模式检测Pattern Detection从会话中识别可提取的复用模式技能提取Skill Extraction将有价值的模式保存到~/.claude/skills/learned/目录。2.1 源码级验证evaluate-session.sh 的真实执行逻辑上述流程并非文档空谈。仓库中 skills/continuous-learning/evaluate-session.sh 就是 v1 的实际执行脚本其关键逻辑与文档描述一一对应配置加载脚本启动时读取同目录config.json且通过jq解析若未安装jq则回退到默认值MIN_SESSION_LENGTH10并将learned_skills_path中的~展开为用户主目录MIN_SESSION_LENGTH$(jq -r .min_session_length // 10 $CONFIG_FILE) LEARNED_SKILLS_PATH$(jq -r .learned_skills_path // ~/.claude/skills/learned/ $CONFIG_FILE | sed s|~|$HOME|)确保目录存在mkdir -p $LEARNED_SKILLS_PATH获取会话转录路径从 stdin 的 JSONClaude Code Hook 输入格式中提取transcript_path并兼容旧版环境变量CLAUDE_TRANSCRIPT_PATH作为回退统计消息数通过grep -c type:user统计用户消息条数会话过短则直接跳过if [ $message_count -lt $MIN_SESSION_LENGTH ]; then echo [ContinuousLearning] Session too short ($message_count messages), skipping 2 exit 0 fi触发评估信号输出提示信息指示 Claude 对会话进行可提取模式评估。从源码可以看出v1 的脚本本身只负责「判定是否需要评估」并给出信号真正的模式提炼仍由 Claude 在会话上下文内完成——这正对应文档中 v1 的「分析基于主上下文」的定位。三、v1 配置详解config.json 全参数说明原文档给出了完整的config.json配置示例仓库中 skills/continuous-learning/config.json 与之完全一致可直接复制使用{ min_session_length: 10, extraction_threshold: medium, auto_approve: false, learned_skills_path: ~/.claude/skills/learned/, patterns_to_detect: [ error_resolution, user_corrections, workarounds, debugging_techniques, project_specific ], ignore_patterns: [ simple_typos, one_time_fixes, external_api_issues ] }各参数的作用与建议取值参数默认值含义与使用建议min_session_length10触发评估所需的最少消息数。会话越短可提取的稳定模式越少调高可减少噪音调低可覆盖更多会话。脚本通过grep -c type:user统计仅在达到该阈值时才进入评估extraction_thresholdmedium模式提取的激进程度低/中/高。阈值越低越容易提取但误报也越多实战中建议从medium起步auto_approvefalse是否自动批准保存提取出的技能。false时每次落盘前需人工确认与 /learn 命令「先展示草稿、要求明确批准」的安全策略一致learned_skills_path~/.claude/skills/learned/learned skills 的存储目录。脚本会将其中的~展开为$HOME并保证目录存在patterns_to_detect5 类见下需要主动检测的模式类型白名单ignore_patterns3 类见下明确排除的低价值模式黑名单四、模式类型检测什么、忽略什么原文档以表格给出了 v1 可检测的五类模式这是提取环节的语义基础模式描述error_resolution特定错误是如何被解决的user_corrections用户纠正的模式例如用户把类写法改成函数式写法workarounds针对框架/库怪癖的绕行方案debugging_techniques有效的调试方法project_specific项目特有的约定忽略清单则用于过滤低价值内容避免把噪音固化成技能simple_typos简单拼写错误one_time_fixes一次性修复例如特定 API 故障external_api_issues外部 API 问题非己方可控。这一「检测白名单 忽略黑名单」的机制与 /learn 命令的提取守则一脉相承不提取琐碎修复、不提取一次性问题、聚焦未来会话中能节省时间的模式并坚持一个技能只聚焦一个模式。五、Hook 配置与选型为什么是 Stop Hook5.1 settings.json 注册方式v1 作为手动安装的技能需要在~/.claude/settings.json中注册 Stop Hook{ hooks: { Stop: [{ matcher: *, hooks: [{ type: command, command: ~/.claude/skills/continuous-learning/evaluate-session.sh }] }] } }5.2 选型理由原文档给出了选择 Stop Hook 而非其他 Hook 点的三个理由evaluate-session.sh头部的注释也印证了这一决策轻量Ligero仅在会话结束时执行一次而不是每个消息都触发非阻塞No bloqueante不会为每条消息增加延迟——与之对比UserPromptSubmit每次消息都运行代价高昂完整上下文Contexto completo能够访问整段会话的完整转录transcript。用evaluate-session.sh中的原话来说Stop runs once at session end (lightweight)而UserPromptSubmit runs every message (heavy, adds latency)。六、手动补充通道/learn 命令除了会话结束时的自动提取原文档的「相关」章节还指向了 /learn 命令——会话中途手动提取模式。两者形成互补触发时机自动v1 Stop Hook手动/learn时机会话结束会话进行中的任意时刻适用场景无感沉淀解决了一个非平凡问题、趁热打铁/learn的提取规范同样覆盖文档中列举的四类模式错误解决、调试技巧、绕行方案、项目特有模式并且输出格式有着严格的安全要求对会话内容按「不可信数据」处理脱敏 secrets/PII、排除提示注入文本、校验pattern-name为小写连字符 slug 并拒绝路径穿越、目标已存在时必须展示 diff 并要求显式覆盖批准最后以SKILL.md目录形式落盘到~/.claude/skills/pattern-name/SKILL.md。七、v1 的局限与 v2 的诞生Homunculus 对比研究原文档以「研究笔记2025 年 1 月」的形式记录了对社区项目 Homunculus v2 的对比分析这正是 v2 架构的设计源头特征v1我们的方案Homunculus v2观察Stop Hook会话结束PreToolUse/PostToolUse100% 可靠分析主上下文后台 AgentHaiku粒度完整 skills原子化「本能instincts」置信度无加权 0.3–0.9演进直接生成 skillinstincts → 聚类 → skill/command/agent共享无导出/导入 instinctsHomunculus 给出的关键洞察是v1 依赖 skills 来观察。skills 是概率性的——大约 50-80% 的时间会触发。v2 用 hooks 做观察100% 可靠并把 instinct 作为习得行为的原子单位。基于此原文档列出了 v2 的五个改进方向而这些方向全部在仓库的 v2 实现中落地基于 instinct 的学习——更小的原子行为 置信度评分后台观察者——Haiku Agent 并行分析置信度衰减——instinct 被反驳时降低置信度领域标签——code-style、testing、git、debugging 等演进路径——把相关 instincts 聚类为 skills/commands。八、v2 架构落地instinct 模型与完整数据流v2 的完整设计规范见 docs/continuous-learning-v2-spec.md核心实现位于 skills/continuous-learning-v2/文档声明该文件是「文档与翻译的稳定参考路径」。8.1 什么是 instinct一个 instinct 是一个「小而美的习得行为」用 YAML 描述具备五个属性原子性一个触发条件、一个动作、置信度加权0.3 试探性0.9 近乎确定、领域标签code-style、testing、git、debugging、workflow 等、证据支撑记录由哪些观察产生、作用域感知project默认或global--- id: prefer-functional-style trigger: when writing new functions confidence: 0.7 domain: code-style source: session-observation scope: project project_id: a1b2c3d4e5f6 project_name: my-react-app --- # Prefer Functional Style ## Action Use functional patterns over classes when appropriate. ## Evidence - Observed 5 instances of functional pattern preference - User corrected class-based approach to functional on 2025-01-158.2 端到端数据流Session Activity (in a git repo) | | Hooks capture prompts tool use (100% reliable) | detect project context (git remote / repo path) v --------------------------------------------- | projects/project-hash/observations.jsonl | | (prompts, tool calls, outcomes, project) | --------------------------------------------- | | Observer agent reads (background, Haiku) v --------------------------------------------- | PATTERN DETECTION | | * User corrections - instinct | | * Error resolutions - instinct | | * Repeated workflows - instinct | | * Scope decision: project or global? | --------------------------------------------- | | Creates/updates v --------------------------------------------- | projects/project-hash/instincts/personal/ | | * prefer-functional.yaml (0.7) [project] | | * use-react-hooks.yaml (0.9) [project] | --------------------------------------------- | instincts/personal/ (GLOBAL) | | * always-validate-input.yaml (0.85) [global]| | * grep-before-edit.yaml (0.6) [global] | --------------------------------------------- | | /evolve clusters /promote v --------------------------------------------- | projects/hash/evolved/ (project-scoped) | | evolved/ (global) | | * commands/new-feature.md | | * skills/testing-workflow.md | | * agents/refactor-specialist.md | ---------------------------------------------8.3 观察钩子实现observe.shhooks/observe.sh 是 v2 观察能力的实现核心对应 v1 的evaluate-session.sh但做了根本性升级双阶段观察通过命令行参数区分prePreToolUse记录tool_start与postPostToolUse记录tool_complete并兼容CLAUDE_HOOK_EVENT_NAME环境变量回退防止手动安装时 PreToolUse 被误归类JSON 解析与字段裁剪使用 Python 解析 stdin Hook JSON提取 tool_name、tool_input、tool_response、session_id、cwd 等字段并对大输入/输出截断到 5000 字符秘密脱敏secrets scrubbing写入观察文件前用线性时间的正则匹配api_key/token/secret/password/authorization等字段并替换为[REDACTED]避免凭据落盘——源码注释还记录了曾因灾难性回溯导致 Python 100% CPU 的历史问题#2278因此刻意使用有界量词解析失败回退解析失败时记录parse_error事件并同样脱敏且用SIGALRM8 秒自终止防止异步 Hook 超时被孤儿化文件轮转observations.jsonl超过 10MB 时原子归档唯一后缀重命名避免竞争超过 30 天的归档文件自动清理观察者懒启动与节流启用后台观察者时通过flockmacOS 回退lockfile/mkdir原子锁做原子化的 check-then-act 启动对 observer 的SIGUSR1唤醒信号做 N 次观察一次的节流默认 20ECC_OBSERVER_SIGNAL_EVERY_N可调防止高频工具调用导致失控的并行分析进程。8.4 项目检测与隔离v2.1 的核心新增是项目级 instincts。项目检测优先级实现在 scripts/detect-project.sh 中与文档声明一致CLAUDE_PROJECT_DIR环境变量最高优先级——显式覆盖即使目录不是 git 仓库也按绝对路径哈希建立项目身份git remote get-url origin——哈希生成可移植项目 ID同一仓库在不同机器上得到相同 ID检测时还会剥离远程 URL 中嵌入的凭据并做 URL 归一化去除协议头、.git后缀、统一小写git rev-parse --show-toplevel——仓库根路径回退机器相关全局回退——未检测到项目时instincts 进入全局作用域。每个项目获得一个 12 字符哈希 ID如a1b2c3d4e5f6注册表文件${XDG_DATA_HOME:-~/.local/share}/ecc-homunculus/projects.json将 ID 映射到人类可读名称每个项目目录下还维护project.json元数据镜像id/name/root/remote通过 Python 原子写临时文件 os.replace保证一致性。多 worktree 场景下没有 remote 的仓库会先解析主 worktree 根再哈希。8.5 数据目录与迁移v2 刻意把观察数据放在~/.claude之外避免 Claude Code 的敏感路径守卫拦截后台 instinct 写入。目录解析优先级源码与文档一致CLV2_HOMUNCULUS_DIR须为绝对路径否则忽略并告警$XDG_DATA_HOME/ecc-homunculus$HOME/.local/share/ecc-homunculus。旧版用户数据在~/.claude/homunculus可一次性迁移bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh九、v2 快速上手从安装到命令9.1 启用观察 Hook以插件方式安装推荐无需在settings.json手动添加 Hook 块Claude Code v2.1 会自动加载插件hooks/hooks.jsonobserve.sh已在那里注册。若之前曾手动把observe.sh复制进~/.claude/settings.json务必删除重复的PreToolUse/PostToolUse块——重复注册会导致双重执行和${CLAUDE_PLUGIN_ROOT}解析错误该变量仅在插件管理的hooks/hooks.json条目内可用。手动安装到~/.claude/skills时在~/.claude/settings.json添加{ hooks: { PreToolUse: [{ matcher: *, hooks: [{ type: command, command: ~/.claude/skills/continuous-learning-v2/hooks/observe.sh }] }], PostToolUse: [{ matcher: *, hooks: [{ type: command, command: ~/.claude/skills/continuous-learning-v2/hooks/observe.sh }] }] } }9.2 初始化目录结构系统在首次使用时自动创建目录也可以手动预建# Global directories mkdir -p ${XDG_DATA_HOME:-$HOME/.local/share}/ecc-homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects}项目目录会在 Hook 首次于 git 仓库内运行时自动创建。9.3 六个 instinct 命令命令说明/instinct-status展示全部 instincts项目级 全局及其置信度/evolve将相关 instincts 聚类为 skills/commands并给出提升建议/instinct-export导出 instincts可按作用域/领域过滤/instinct-import file带作用域控制地导入 instincts/promote [id]将项目级 instincts 提升到全局作用域/projects列出所有已知项目及其 instinct 数量9.4 后台观察者配置编辑 config.json 控制后台观察者行为{ version: 2.1, observer: { enabled: false, run_interval_minutes: 5, min_observations_to_analyze: 20 } }键默认值说明observer.enabledfalse启用后台观察者 Agentobserver.run_interval_minutes5观察者分析观察数据的间隔observer.min_observations_to_analyze20触发分析所需的最少观察条数注意平台限制后台观察者要求 WSL2、Linux 或 macOS。在原生 WindowsGit Bash/MSYS2下观察者启动时会报告成功但 Hook 进程退出、其 Job Object 关闭后进程即被杀死因此永远不会真正执行分析——observer.enabled: true在那里实际是空操作参见 issue #2489。observe.sh会在后续 Hook 调用中检测到这一情况并在连续多次未存活后向observer-start.log写入解释性告警告警阈值由ECC_OBSERVER_NOSURVIVE_WARN_AFTER默认 3控制。9.5 作用域决策指南instinct 应该放在项目级还是全局原文档给出了清晰的决策表模式类型作用域示例语言/框架约定projectUse React hooks、Follow Django REST patterns文件结构偏好projectTests in__tests__/、Components in src/components/代码风格projectUse functional style、Prefer dataclasses错误处理策略projectUse Result type for errors安全实践globalValidate user input、Sanitize SQL通用最佳实践globalWrite tests first、Always handle errors工具工作流偏好globalGrep before Edit、Read before WriteGit 实践globalConventional commits、Small focused commits9.6 提升Promotion项目 → 全局当同一个 instinct 在多个项目中出现且置信度高时它就是提升到全局作用域的候选者。自动提升标准同一 instinct ID 出现在 2 个项目、平均置信度 ≥ 0.8。手动提升# Promote a specific instinct python3 instinct-cli.py promote prefer-explicit-errors # Auto-promote all qualifying instincts python3 instinct-cli.py promote # Preview without changes python3 instinct-cli.py promote --dry-run/evolve命令也会建议提升候选。CLI 的其他子命令status/import/export/projects/prune 等完整实现于 scripts/instinct-cli.py。9.7 置信度评分机制置信度随时间演化分值含义行为0.3试探性仅建议不强制执行0.5中等相关时应用0.7强自动批准应用0.9近乎确定核心行为置信度上升模式被反复观察、用户未纠正建议行为、其他来源的相似 instincts 一致。置信度下降用户明确纠正该行为、模式长时间未被观察到、出现矛盾证据。十、为什么 hooks 优于 skills 做观察v2 文档中的原话回答了架构选型的根本问题v1 依赖 skills 来观察。skills 是概率性的——基于 Claude 的判断大约 50-80% 的时间才触发。Hooks 则100% 确定性触发带来的三个直接收益每次工具调用都被观察、没有模式会被遗漏、学习是全面的。这正是「观察」环节从 v1 的 Stop Hook 演进到 v2 的 PreToolUse/PostToolUse 的原因。十一、隐私与兼容性隐私边界观察数据完全留在本地机器项目级 instincts 按项目隔离只有 instincts模式可以导出原始观察数据不可导出不共享实际代码或对话内容导出与提升完全由你控制。向后兼容v2.1 与 v2.0、v1 完全兼容——~/.claude/homunculus/instincts/的既有全局 instincts 可通过scripts/migrate-homunculus.sh迁移v1 的~/.claude/skills/learned/技能仍然可用Stop Hook 仍会运行现在同时为 v2 供数支持并行运行、渐进迁移。十二、v1 与 v2 的选择建议综合原文档状态说明与上述对比给出实操建议新安装一律使用continuous-learning-v2不要注册 v1 的 Stop Hook保留 v1 的场景你明确想要更简单的 Stop Hook 提取流程或需要兼容更早的 learned skills 工作流升级路径先在既有环境并行运行 v2v1 的 Stop Hook 继续工作用migrate-homunculus.sh迁移数据确认 instincts 正常运行后再摘除 v1 Hook 注册。两个版本的完整文件结构全局 项目级目录树可在 v2 SKILL.md 的「File Structure」章节查阅v1 的归档文档与 v2 规范分别位于 docs/es/skills/continuous-learning/SKILL.md 与 docs/continuous-learning-v2-spec.md。Instinct-based learning: teaching Claude your patterns, one project at a time.【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考