连续学习与 Instinct 模型

连续学习与 Instinct 模型

学习目标

本章要解决什么问题：理解 ECC 如何通过 Hook 驱动的持续学习系统，从会话中提取可复用的模式。

读完本章后，你将了解：

• Hook 驱动观察与 Skill 驱动观察的触发率差异
• ECC 的 Instinct 模型设计（原子化、置信度、作用域）
• Observer Agent 的后台分析架构
• 项目隔离与 Instinct 晋升机制

前置知识

本章涉及记忆系统和连续学习的通用原理，建议先阅读：

• 记忆系统设计 — Hook 驱动持续学习的通用架构
• 连续学习与 Instinct 模型 — 原子化 Instinct、置信度评分、演化管线
• Hook 系统架构 — 工具生命周期事件与钩子执行模型

下文假设你已理解上述概念，直接聚焦 ECC 的具体实现。

---

项目实践

v2.1 相对于 v1 的关键演进

ECC 的连续学习系统经历了两个主要版本的演进：

维度	v1	v2	v2.1
观察捕获	Stop 钩子（会话结束）	PreToolUse/PostToolUse（100%）	同 v2，增强项目检测
分析方式	主上下文中分析	后台 Agent（Haiku）	同 v2
粒度	完整技能	原子化 Instinct	同 v2
置信度	无	0.3-0.9 加权	同 v2
存储位置	~/.claude/homunculus/	XDG 数据目录	项目隔离 + 注册表
作用域	全局（所有项目共享）	项目隔离	项目 → 全局晋升
命令	无	4 个（status/evolve/export/import）	6 个（+promote/projects）

实现架构：从观察到演化的完整管线

ECC 的具体实现分布在多个组件中：

关键实现文件：

文件	职责
scripts/hooks/observe-runner.js	Hook 包装器，调用 observe.sh 并处理跨平台路径转换
skills/continuous-learning-v2/hooks/observe.sh	实际观察捕获逻辑，记录提示和工具调用
scripts/hooks/evaluate-session.js	Stop 阶段会话评估，提取可提取模式
skills/continuous-learning-v2/SKILL.md	完整技能文档，包含 Instinct 模型定义、配置、命令
skills/continuous-learning-v2/config.json	Observer 配置（启用状态、分析间隔、最小观察数）

项目检测的实现

v2.1 新增的项目作用域隔离依赖准确的项目检测：

1. CLAUDE_PROJECT_DIR 环境变量（最高优先级）
2. git remote get-url origin — 哈希生成可移植项目 ID（同一仓库在不同机器上得到相同 ID）
3. git rev-parse --show-toplevel — 回退使用仓库路径（机器特定）
4. 全局回退 — 无项目检测时，Instinct 归入全局作用域

项目 ID 是一个 12 字符的哈希值。注册表文件映射 ID 到人类可读名称：

// ${XDG_DATA_HOME}/ecc-homunculus/projects.json
{
  "a1b2c3d4e5f6": {
    "name": "my-react-app",
    "root": "/home/user/projects/my-react-app",
    "remote": "git@github.com:user/my-react-app.git"
  }
}

数据目录迁移

v2.1 将数据从 ~/.claude/homunculus/ 迁移到 XDG 标准目录：

# 自动迁移脚本
bash skills/continuous-learning-v2/scripts/migrate-homunculus.sh

迁移原因：Claude Code 的敏感路径守卫阻止后台 Agent 写入 ~/.claude/ 下的某些路径。XDG 目录（~/.local/share/）不受此限制。

---

问题与规避

跨项目污染（v2.0 之前的问题）

问题：项目 A 的 React 模式被应用到项目 B 的 Python 代码中。

ECC v2.1 的规避：项目作用域隔离。每个项目的 Instinct 存储在独立的 projects/<hash>/ 目录下，仅在对应项目中激活。

Observer 成本

问题：每次工具调用都触发观察分析，消耗 Token。

ECC 的规避：

• Observer 使用 Haiku 模型（最低成本）
• 默认未启用（config.json 中 observer.enabled: false）
• 最小观察数阈值（默认 20 条才触发分析）
• 可配置的分析间隔（默认 5 分钟）

Hook 重复执行

问题：如果用户同时在 settings.json 和插件 hooks.json 中注册了 observe hook，会导致双重执行。

ECC 的建议：如果通过插件安装，不需要在 settings.json 中重复注册 Hook。ECC 文档明确警告：“重复注册会导致双重执行和 ${CLAUDE_PLUGIN_ROOT} 解析错误。“

---

设计取舍

为什么选择 XDG 目录而非 ~/.claude/？

这是一个平台约束驱动的设计决策：

• Claude Code 的路径守卫阻止后台 Agent 写入 ~/.claude/ 的某些子目录
• XDG 标准（~/.local/share/）是 Linux 社区的用户数据约定位置
• 对于 macOS 用户，~/.local/share/ 同样是可接受的替代方案

代价：旧用户需要手动迁移。ECC 提供了 migrate-homunculus.sh 一次性迁移脚本。

为什么 Instinct 是 YAML 而非 JSON？

Instinct 文件使用 YAML frontmatter + Markdown body 格式：

• 可读性：人类可直接阅读和编辑
• 与 Skill 格式一致：ECC 的 SKILL.md 也使用 frontmatter，工具链统一
• 版本控制友好：diff 清晰

代价：YAML 解析比 JSON 慢，但 Instinct 文件体积小（通常 <1KB），性能影响可忽略。

为什么默认关闭 Observer？

config.json 中 observer.enabled: false 是默认值：

• Observer 需要后台 Agent（Haiku）持续运行，有成本
• 不是所有用户都需要连续学习功能
• 用户可以先体验基础功能，再按需启用

---

参考来源

• 源码验证: skills/continuous-learning-v2/SKILL.md — 完整 Instinct 模型定义
• 源码验证: skills/continuous-learning-v2/config.json — Observer 配置
• 源码验证: scripts/hooks/observe-runner.js — 跨平台 Hook 包装器
• 源码验证: scripts/hooks/evaluate-session.js — 会话评估逻辑
• 连续学习与 Instinct 模型 — 通用 Instinct 设计模式