Patterns Discovered

Patterns Discovered

Pattern: [名称]

• Context: 何时使用该模式
• Implementation: 如何应用
• Example: 代码片段

Best Practices Applied

1. [实践名称]
   • Why it works: 为什么有效
   • When to apply: 何时应用

Mistakes to Avoid

1. [错误描述]
   • What went wrong: 出了什么问题
   • How to prevent it: 如何避免

Suggested Skill Updates

如果模式足够重要，建议更新：

• skills/coding-standards/SKILL.md
• skills/[domain]/SKILL.md
• rules/[category].md

注意最后一项的“落地路径”。以仓库自身为例，`coding-standards` 的实体文件就是 [skills/coding-standards/SKILL.md](https://gitcode.com/GitHub_Trending/ev/ECC/blob/22e8cf01d0b54719b3a49002fab2ccbda4ff5b9e/skills/coding-standards/SKILL.md?utm_source=gitcode_repo_files)，它定义了基线级编码约定（命名、可读性、KISS/DRY/YAGNI、错误处理、代码异味检测等）；按领域细分的 Skill 则分布在 [skills/](https://gitcode.com/GitHub_Trending/ev/ECC/blob/22e8cf01d0b54719b3a49002fab2ccbda4ff5b9e/skills/?utm_source=gitcode_repo_files) 目录（如 `python-patterns`、`golang-patterns`、`react-patterns`）；更短小、可直接作为 rule 复用的表述放在 [rules/](https://gitcode.com/GitHub_Trending/ev/ECC/blob/22e8cf01d0b54719b3a49002fab2ccbda4ff5b9e/rules/?utm_source=gitcode_repo_files)（例如其中 `common/` 下的跨语言通用规则）。`/learn` 在“Suggested Skill Updates”中给出的是**更新建议**而非直接写入，最终改动仍需用户确认——这与下文的安全写入要求一致。

### ECC 实际使用 learn 的方式

`.opencode/README.md` 的命令表把 `/learn` 描述为 “Extract patterns”，并把它的兄弟命令 `instinct-status`（查看 instincts）、`instinct-import` / `instinct-export`（导入/导出）、`evolve`（聚类 instincts）、`promote`（提升项目 instincts 为全局）并列呈现，说明在实际工作流里，learn 产出的知识并不只停留在一次性的“会议纪要”，而是进入可迁移、可演化的知识管道。

## 四、把模式写成 Skill：Guarded Write 安全写入流程

当会话中的某个 pattern 足够重要、需要固化到**个人 Skill 根目录**时，目标路径是：

~/.claude/skills//SKILL.md

在写文件之前，`commands/learn.md` 强制应用一组 **guarded-write（受控写入）要求**，其核心理念是：**把会话中派生出的内容当作不可信输入来处理**。

### 1. 内容消毒（Sanitization）

- 将会话内容视为不可信数据；
- 剔除 secrets、PII 等敏感值；
- 排除 prompt-injection / 政策覆盖类文本；
- 拒绝那些请求工具、权限或无关操作的不可信指令。

### 2. 目标路径校验（Slug 与目录穿越防护）

- 校验 `pattern-name` 必须是**小写连字符 slug**；
- 拒绝路径分隔符与路径穿越（path traversal）；
- 解析目标路径并确认其仍位于批准的 Skill 根目录 `~/.claude/skills/` 之内。

### 3. 覆盖保护（Overwrite Approval）

- 若目标 Skill 已存在：展示 diff，并要求**明确的覆盖批准**，或另选新名字；
- 绝不允许静默替换已有 Skill。

### 4. 写入前确认（YAML 合法性与显式批准）

- 以合法 YAML 序列化带引号的值；
- 展示清洗后的草稿与完整目标路径；
- 在进行全局持久化前，要求用户显式批准。

### Skill 文件的 Frontmatter 模板

```markdown
---
name: pattern-name
description: "Use when <可观察的触发条件> — <该 pattern 的一句话总结>"
metadata:
  origin: auto-extracted
---

# [描述性 Pattern 名称]

**Extracted:** [日期]
**Context:** [该模式适用的场景简述]

## Problem
[该模式解决的具体问题]

## Solution
[模式/技巧/workaround]

## Example
[适用时的代码示例]

## When to Use
[触发条件——什么情况应激活该 Skill]

把这段模板与仓库中真实的 Skill 结构对照即可发现，ECC 的 Skill 正是在 frontmatter 中以 name + description 声明触发语义。例如 skills/coding-standards/SKILL.md 的 description 明确写有 “Use when reviewing code quality or naming with no framework-specific skill that applies”，并以 metadata.origin: ECC 标注来源。由 /learn 自动抽取的 Skill 则把 origin 标为 auto-extracted，用于区分“官方内置”与“会话习得”。

五、Instinct 格式：把经验接进 continuous-learning-v2

learn 文档为 continuous-learning-v2 提供了一种更轻量的“本能”格式，用于把单条学习固化为一条可计分、可触发、可迁移的 instinct：

{
  "trigger": "[触发该学习的情境]",
  "action": "[应该怎么做]",
  "confidence": 0.7,
  "source": "session-extraction",
  "timestamp": "[ISO 时间戳]"
}

这套 JSON 结构与仓库中 instinct 的 YAML 实体一一对应。以 skills/continuous-learning-v2/SKILL.md 中的示例为准：

---
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-15

两种表达共享同一套字段语义：

• trigger：可观察的激活条件，决定“何时该应用”；
• action / ## Action：具体行为；
• confidence：置信度，0.3 = 试探性，0.9 = 接近确定，系统据此决定是否自动应用（见下表）；
• source：来源标记（learn 输出为 session-extraction，hook 观察为 session-observation）；
• timestamp：时间戳，用于过期判断。

置信度的演化规则决定了 learn 产物后续的命运：当同一模式被反复观察、用户未纠正时 confidence 上升；当用户明确纠正、模式长时间未被观察或出现矛盾证据时下降。这意味着 /learn 输出时的 confidence 只是一个初始估值，后续会被 observer 的观察证据持续修正。

置信度	含义	系统行为
0.3	Tentative（试探性）	仅建议，不强制
0.5	Moderate（中等）	相关场景下应用
0.7	Strong（强）	自动批准应用
0.9	Near-certain（接近确定）	视为核心行为

六、Skill 落盘后的可发现性验证

learn 命令要求写入后必须验证可发现性（discoverability），而不是写完就宣布成功。六步流程如下：

1. 回顾会话，寻找可抽取的 pattern；
2. 找出最有价值/可复用的洞见；
3. 起草 Skill 文件；
4. 先征求用户确认再保存；
5. 保存到 ~/.claude/skills/<pattern-name>/SKILL.md；
6. 验证可发现性并循环直至通过。

验证项非常具体：

• 文件必须命名为 SKILL.md；
• Skill 的父目录名必须与 frontmatter 中的 name: 一致；
• --- 分隔的 frontmatter 必须能被解析为合法 YAML；
• description: 非空，且以可观察的 “Use when ...” 触发条件开头。

任一检查失败，应报告具体失败原因、移除或隔离非法文件并停止；若需修复，先准备好修正草稿但不写入，展示完整路径，获得新的显式批准后再写入并重新验证——直到全部通过才能宣称成功。

文档解释了为什么目录形态与 frontmatter 如此重要：Claude Code 只从 <name>/SKILL.md 结构发现个人 Skill，扁平存放的 skills/learned/<name>.md 文件并不是合法的 Skill 入口；而“触发器优先”的 description 帮助 Claude 判断何时应自动加载该 Skill。换言之，learn 的产出要真正生效，不止是“内容正确”，还必须“位置正确、形状正确、描述可触发”。

七、从 Skill 到 Evolved 结构：经验的长生命周期

learn 的一次产出只是知识生命周期的起点。在 ECC 的 instinct 体系中，多条相关 Skill/instinct 还可以继续向上聚合为命令、Skill 或 Agent 三种“进化结构”。commands/evolve.md 给出的判定规则：

• → Command（用户主动调用）：当 instincts 描述用户会显式请求的动作，且存在可重复的步骤序列。例如“新增表要建迁移 / 更新 schema / 重新生成类型”三条 instincts 聚合成 new-table 命令；
• → Skill（自动触发）：当 instincts 描述应自动发生的行为（模式匹配触发、错误处理响应、代码风格约束），如 “写函数时偏好函数式风格”；
• → Agent（复杂多步流程）：当 instincts 描述复杂、多步骤的过程。

运行方式为 python3 instinct-cli.py evolve [--generate]，其中 --generate 才会真正在 evolved/{skills,commands,agents} 下生成文件，否则只输出建议。

值得注意的是，仓库中 learn 命令（.opencode 版与根级 commands 版）的“Suggested Skill Updates”提示了更新现有 skills/coding-standards/SKILL.md 等官方 Skill 的可能性，而 evolve 则是生成全新的 evolved 结构——两者构成“补充既有知识”与“长出新知识”两条路径。

八、让 Skill 覆盖项目/全局双作用域

learn 产生的个人 Skill 默认落在 ~/.claude/skills/ 个人作用域，而 instinct 则进一步区分 project 作用域与 global 作用域。这是 skills/continuous-learning-v2/SKILL.md 中 v2.1 的核心设计：

• project 作用域（默认）：React 模式留在 React 项目、Python 约定留在 Python 项目，避免跨项目污染；
• global 作用域：普适模式（如 “始终校验用户输入” “写代码前先 grep”）对所有项目生效；
• promote：当同一 instinct 在 2 个以上项目出现且平均置信度 ≥ 0.8 时，系统判定其具备普适性，可被提升为全局。

作用域的存储位置由 scripts/instinct-cli.py 中 _resolve_homunculus_dir() 的解析顺序决定：CLV2_HOMUNCULUS_DIR 环境变量（绝对路径）→ $XDG_DATA_HOME/ecc-homunculus → ~/.local/share/ecc-homunculus。选择放在 ~/.claude 之外，是为了规避 Claude Code 的敏感路径保护对后台 instinct 写入的拦截。

项目 ID 的生成逻辑在同文件的 _project_hash() 中：对 git remote URL 做 SHA-256 哈希后取前 12 位（如 a1b2c3d4e5f6），并通过 _normalize_remote_url() 剥离凭据与 .git 后缀，使同一仓库在不同机器上产生相同 ID，实现“可移植的项目作用域”。这也解释了为什么 learn 萃取出的经验在导入/导出后仍能保持正确的归属。

九、/learn 的兄弟命令：经验的可迁移闭环

为了让 /learn 产出的经验在不同项目、不同机器之间流转，ECC 提供了完整的导入/导出命令族：

命令	用途	关键选项
/instinct-status	按 domain 分组展示项目 + 全局 instincts，带 confidence 条形图	无参数，直接查看
/instinct-export	导出为可分享的 YAML 文件	--scope project|global|all（默认 all）、--domain、--min-confidence、--output
/instinct-import	从文件/URL 导入 instincts	导入时做 scope 控制
/evolve	聚类 related instincts 为 skills/commands	--generate 生成文件
/promote	将项目 instincts 提升至全局	按 ID 或全部自动提升，支持 --dry-run 预览
/projects	列出所有已知项目及其 instinct 数量	—

例如在 learn 萃取完成后：

# 只导出高置信度的测试相关经验
/instinct-export --domain testing --min-confidence 0.7

# 预览提升候选，不改动任何文件
python3 skills/continuous-learning-v2/scripts/instinct-cli.py promote --dry-run

隐私设计贯穿其中：observations 只保存在本地、按项目隔离；可导出的只有 instinct（模式）而非原始观测；实际代码与会话内容不会离开机器；导出、提升都由用户控制。/learn 同样遵循这一原则——被写入 Skill 的是“去除了敏感信息的模式”，而不是会话原文。

十、后台观察与 /learn 的配合使用建议

从配置层面看，Continuous Learning v2 的后台观察是可选的。其 config.json 中的默认配置为：

{
  "version": "2.1",
  "observer": {
    "enabled": false,
    "run_interval_minutes": 5,
    "min_observations_to_analyze": 20
  }
}