技能生命周期与分类管理

技能生命周期与分类管理

学习目标

本章要解决什么问题：理解 ECC 如何管理四类不同来源的技能，确保它们共存且互不干扰。

读完本章后，你将了解：

• 四类技能的分类与存储路径策略
• Provenance 元数据系统的设计
• CI 验证：技能存在性、格式和 Manifest 一致性
• 技能健康检查的实现

前置知识

本章涉及插件系统和技能设计的通用原理，建议先阅读：

• 插件系统架构 — 四类核心组件
• 技能设计 — SKILL.md 的结构与最佳实践

---

项目实践

四类技能分类

ECC 将技能严格分为四类，每类有独立的存储路径和生命周期：

类型	存储路径	发布	Provenance	来源
Curated	skills/（仓库）	是	不需要（origin 标记）	仓库维护者
Learned	~/.claude/skills/learned/	否	必须 .provenance.json	会话观察提取
Imported	~/.claude/skills/imported/	否	必须 .provenance.json	外部来源安装
Evolved	~/.local/share/ecc-homunculus/evolved/	否	继承自 Instinct 来源	Instinct 聚类生成

Provenance 元数据系统

对于 Learned 和 Imported 技能，ECC 要求必须有 .provenance.json 文件：

{
  "source": "https://github.com/affaan-m/ECC",
  "created_at": "2026-05-26T00:00:00Z",
  "confidence": 0.85,
  "author": "continuous-learning-v2"
}

必需字段：

字段	类型	说明
source	string	来源（URL、路径或标识符）
created_at	string	ISO 8601 时间戳
confidence	number	0-1 置信度
author	string	谁产生了这个技能

Schema 定义在 schemas/provenance.schema.json，验证逻辑在 scripts/lib/skill-evolution/provenance.js。

CI 验证

ECC 维护了两套 CI 验证脚本：

validate-skills.js（技能验证）：

作用域: 仅 Curated 技能 (skills/ 目录)
检查项:
  - skills/ 不存在 → exit 0（无需验证）
  - 每个子目录必须包含 SKILL.md
  - SKILL.md 非空
  - 不触及 learned/imported/evolved 根目录

validate-install-manifests.js（安装 Manifest 验证）：

作用域: 仅 Curated 路径
检查项:
  - install-modules.json 中所有 paths 必须存在
  - 防止 Manifest 引用已删除的技能

技能计数一致性

ECC 的 CHANGELOG 中声明的技能/代理/命令数量必须与目录实际文件数一致。CI 强制检查：

# 目录计数
ls skills/ | wc -l    # 必须 = CHANGELOG 中声明的数量
ls agents/ | wc -l    # 必须 = CHANGELOG 中声明的数量
ls commands/ | wc -l  # 必须 = CHANGELOG 中声明的数量

这确保了文档与代码的一致性。

技能健康检查

/skill-health 命令（scripts/skills-health.js）检查：

• 所有 Curated 技能的存在性和格式
• 本地技能（learned/imported/evolved）的可加载性
• Provenance 文件的完整性

技能演进管线

Evolved 技能由连续学习系统生成：

Instincts (atomic observations)
    ↓ /evolve 聚类
Clustered Instincts (related groups)
    ↓ 模板生成
Evolved Skills/Commands/Agents
    ↓ 存储到 evolved/ 目录

Evolved 技能继承源 Instinct 的 Provenance，不需要单独的 .provenance.json。

---

问题与规避

本地生成的技能污染仓库

问题：Learned/Imported/Evolved 技能被错误地提交到仓库。

ECC 的规避：

• 本地技能存储在 ~/.claude/ 和 ~/.local/share/（不在仓库内）
• .gitignore 排除这些路径
• CI 只验证仓库内的 skills/ 目录

Provenance 文件缺失

问题：Learned 或 Imported 技能没有 .provenance.json，无法追溯来源。

ECC 的规避：

• 连续学习系统在创建 Learned 技能时自动写入 Provenance
• 安装脚本在安装 Imported 技能时要求提供来源信息
• /skill-health 命令检测缺失的 Provenance 文件

技能目录命名冲突

问题：两个不同技能使用相同的目录名。

规避方案：

• 目录名 = 技能名（skills/<skill-name>/SKILL.md）
• CI 验证每个目录必须有唯一的 SKILL.md
• 命名规范：小写 + 连字符（如 tdd-workflow）

---

设计取舍

为什么分层目录而非扁平目录 + 标签？

四类技能使用独立的存储路径：

• 优势：发布边界清晰，本地生成技能不会污染仓库
• 代价：需要维护四套加载逻辑
• 替代方案：扁平目录 + 标签过滤（如 skills/ 下所有技能带 type 标签）。ECC 选择分层目录因为发布边界是硬要求

为什么 Curated 技能不需要 Provenance？

Curated 技能是仓库的一部分：

• 来源就是仓库本身（通过 origin 字段标记为 ECC 或 community）
• Git 历史已经提供了完整的变更追溯
• Provenance 文件会增加维护负担

纯 Markdown 内容如何做测试？

ECC 的技能测试不测试”内容正确性”，而是测试”结构完整性”：

• 文件存在性
• frontmatter 格式
• SKILL.md 非空
• 目录计数一致性
• Manifest 路径存在性

这些测试通过 Node.js 脚本实现，不需要运行 LLM。

---

参考来源

• 源码验证: docs/SKILL-PLACEMENT-POLICY.md — 技能放置和 Provenance 策略
• 源码验证: scripts/ci/validate-skills.js — 技能验证
• 源码验证: scripts/ci/validate-install-manifests.js — Manifest 验证
• 源码验证: schemas/provenance.schema.json — Provenance Schema
• 源码验证: scripts/lib/skill-evolution/provenance.js — Provenance 验证逻辑
• 技能设计 — 通用技能设计规范