mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 13:55:50 +00:00
feat: 整合功能恢复与技能学习闭环(含 ECC v2.1 parity + Opus 4.7 接入 + prompt 工程优化)
主要变更: - Skill Learning 闭环系统 (9/9 AC) - Opus 4.7 模型层接入 + adaptive thinking - Prompt 工程优化 (64 审计测试) - Agent Teams 简化门控 (默认启用) - Windows Terminal 后端修复 (EncodedCommand/WT_SESSION) - TF-IDF 技能搜索精准化 (字段加权/CJK 优化) - Autonomy 系统 (/autonomy 命令) - ACP 协议完整实现 - mock.module 泄漏修复 (CI 全绿) - 152+ lint/type 修复
This commit is contained in:
unraid
288
docs/task/task-017-skill-learning-evolution.md
Normal file
288
docs/task/task-017-skill-learning-evolution.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# Task 017: Skill Learning / Evolution 内置化
|
||||
|
||||
> 设计文档: [skill-learning-evolution-design.md](../features/skill-learning-evolution-design.md)
|
||||
> 需求文档: [skill-learning-ecc-analysis.md](../features/skill-learning-ecc-analysis.md)
|
||||
> 策略规范: [skill-learning-policy.md](../features/skill-learning-policy.md)
|
||||
> 依赖: 当前 `EXPERIMENTAL_SKILL_SEARCH` 已实现并默认启用
|
||||
> 范围: 新增内置 Skill Learning / Evolution 的最小闭环，不改现有 Skill Search 核心算法。
|
||||
|
||||
## 目标
|
||||
|
||||
把 ECC `continuous-learning-v2` 的 observation -> instinct -> evolve -> learned skill 模型内置到项目中，形成可测试的本地学习闭环。
|
||||
|
||||
最终用户效果:
|
||||
|
||||
```text
|
||||
会话 transcript
|
||||
-> 提取 observation
|
||||
-> 生成 project-scoped instinct
|
||||
-> evolve 为 learned SKILL.md
|
||||
-> clearSkillIndexCache()
|
||||
-> 现有 Skill Search 可推荐 learned skill
|
||||
```
|
||||
|
||||
## 文件清单
|
||||
|
||||
### 新增
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| `src/services/skillLearning/types.ts` | Observation / Instinct / Draft 类型。 |
|
||||
| `src/services/skillLearning/featureCheck.ts` | `SKILL_LEARNING` gate 与环境变量控制。 |
|
||||
| `src/services/skillLearning/learningPolicy.ts` | 学习阈值、命名、scope、生成规则。 |
|
||||
| `src/services/skillLearning/projectContext.ts` | 项目识别与 project id 生成。 |
|
||||
| `src/services/skillLearning/observationStore.ts` | observation 写入、读取、归档、scrub。 |
|
||||
| `src/services/skillLearning/sessionObserver.ts` | 从 transcript / observations 提取 instinct 候选。 |
|
||||
| `src/services/skillLearning/instinctStore.ts` | instinct 读写、upsert、status、prune。 |
|
||||
| `src/services/skillLearning/skillGenerator.ts` | 从 instinct cluster 生成 SKILL.md 草稿。 |
|
||||
| `src/services/skillLearning/evolution.ts` | instinct 聚类与 skill/command/agent 分类建议。 |
|
||||
| `src/services/skillLearning/promotion.ts` | project -> global promotion 规则。 |
|
||||
| `src/services/skillLearning/skillLifecycle.ts` | 新 skill 与旧 skill 的 create/merge/replace/archive/delete 决策。 |
|
||||
| `src/services/skillLearning/__tests__/*.test.ts` | 对应单元测试。 |
|
||||
| `src/commands/skill-learning/index.ts` | 命令入口。 |
|
||||
| `src/commands/skill-learning/skill-learning.ts` | `status/ingest/evolve/export/import/prune` 子命令。 |
|
||||
|
||||
### 修改
|
||||
|
||||
| 文件 | 变更 |
|
||||
|------|------|
|
||||
| `src/commands.ts` | 注册 `skill-learning` 命令或同等入口。 |
|
||||
| `src/utils/attachments.ts` | 不需要第一版改动；通过 generated SKILL.md 回流到现有索引。 |
|
||||
| `build.ts` / `scripts/dev.ts` | 可选加入 `SKILL_LEARNING` feature。初版建议 dev 启用，build 暂不默认。 |
|
||||
|
||||
## 实现步骤
|
||||
|
||||
### 1. 类型与 gate
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
types.ts
|
||||
featureCheck.ts
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
- 类型包含 `SkillObservation`、`Instinct`、`LearnedSkillDraft`。
|
||||
- `isSkillLearningEnabled()` 支持:
|
||||
- `SKILL_LEARNING_ENABLED=0`
|
||||
- `SKILL_LEARNING_ENABLED=1`
|
||||
- `feature('SKILL_LEARNING')`
|
||||
|
||||
### 2. Project Context
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
projectContext.resolveProjectContext(cwd)
|
||||
```
|
||||
|
||||
优先级:
|
||||
|
||||
1. `CLAUDE_PROJECT_DIR`
|
||||
2. `git remote get-url origin`
|
||||
3. `git rev-parse --show-toplevel`
|
||||
4. global fallback
|
||||
|
||||
验收:
|
||||
|
||||
- 同一 git remote 在不同路径下生成相同 project id。
|
||||
- 无 git 仓库时返回 global context。
|
||||
- 写入 `projects.json` 与 `project.json`。
|
||||
|
||||
### 3. Observation Store
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
appendObservation()
|
||||
readObservations()
|
||||
ingestTranscript()
|
||||
scrubObservation()
|
||||
archiveLargeObservationFile()
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
- 能从 Claude JSONL transcript 读取 user/assistant/tool_result。
|
||||
- secret 字段被 scrub。
|
||||
- 大字段截断。
|
||||
- 写入 project-specific `observations.jsonl`。
|
||||
|
||||
### 4. Session Observer
|
||||
|
||||
实现最小规则引擎:
|
||||
|
||||
| 规则 | 输出 |
|
||||
|------|------|
|
||||
| 用户明确纠正 | instinct: prefer corrected action |
|
||||
| tool error 后成功 | instinct: error resolution |
|
||||
| 重复 tool sequence | instinct: workflow |
|
||||
| 明确项目约定 | instinct: project convention |
|
||||
|
||||
验收:
|
||||
|
||||
- fixture transcript 中用户说“不要 mock，用 testing-library”能生成 testing instinct。
|
||||
- fixture transcript 中重复 `Grep -> Read -> Edit` 能生成 workflow instinct。
|
||||
- 没有明显模式时不生成 instinct。
|
||||
|
||||
### 5. Instinct Store
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
saveInstinct()
|
||||
loadInstincts()
|
||||
upsertInstinct()
|
||||
updateConfidence()
|
||||
exportInstincts()
|
||||
importInstincts()
|
||||
prunePendingInstincts()
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
- instinct 文件可序列化/反序列化。
|
||||
- 相同 id 的 confirming observation 增加 confidence。
|
||||
- contradiction 降低 confidence。
|
||||
- pending 超过 TTL 可 prune。
|
||||
|
||||
### 6. Skill Generator + Lifecycle
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
generateSkillDraft(instincts)
|
||||
writeLearnedSkill(draft)
|
||||
compareExistingSkills(draft)
|
||||
decideSkillLifecycle(draft, existingSkills)
|
||||
applySkillLifecycleDecision(decision)
|
||||
writeReplacementManifest(manifest)
|
||||
```
|
||||
|
||||
输出路径:
|
||||
|
||||
```text
|
||||
project: <repo>/.claude/skills/<name>/SKILL.md
|
||||
global: ~/.claude/skills/<name>/SKILL.md
|
||||
```
|
||||
|
||||
`origin: skill-learning` 标记这是 learned skill。不要把 active generated skill 放在 `skills/learned/<name>/SKILL.md`，因为当前 skill loader 只索引一层 `skills/<skill>/SKILL.md`。
|
||||
|
||||
验收:
|
||||
|
||||
- 生成合法 frontmatter: `name` + `description`。
|
||||
- body 包含 Trigger、Action、Evidence。
|
||||
- 生成前必须检索现有 skill，判断 create/merge/replace/archive/delete。
|
||||
- merge 只生成 patch 建议，不自动覆盖旧 skill。
|
||||
- replace 必须让旧 skill 从 active index 消失。
|
||||
- 默认 archive-first；hard delete 需要引用检查和 manifest。
|
||||
- 写入后调用 `clearSkillIndexCache()`。
|
||||
|
||||
### 7. Evolution
|
||||
|
||||
实现:
|
||||
|
||||
```text
|
||||
clusterInstincts()
|
||||
classifyEvolutionTarget()
|
||||
suggestEvolutions()
|
||||
generateSkillCandidates()
|
||||
```
|
||||
|
||||
第一版只真正生成 skill，command/agent 只输出建议。
|
||||
|
||||
验收:
|
||||
|
||||
- 2+ 同 domain/trigger instincts 可聚类。
|
||||
- 高置信 cluster 生成 skill candidate。
|
||||
- 低置信 cluster 只报告，不生成。
|
||||
|
||||
旧 skill 处理规则:
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 新能力无覆盖 | create 新 learned skill。 |
|
||||
| 旧 skill 已覆盖主体 | merge，输出 patch 建议。 |
|
||||
| 新 skill 明显更完整且旧 skill 会冲突 | replace，激活新 skill，旧 skill 移出 active index。 |
|
||||
| 旧 skill 低质量/过期 | archive，移动到 `.archive/`。 |
|
||||
| 旧 skill 无引用、可安全移除 | delete，写 tombstone 后删除。 |
|
||||
|
||||
### 8. Commands
|
||||
|
||||
提供命令:
|
||||
|
||||
```bash
|
||||
skill-learning status
|
||||
skill-learning ingest <transcript>
|
||||
skill-learning evolve [--generate]
|
||||
skill-learning export [--scope project|global]
|
||||
skill-learning import <file>
|
||||
skill-learning prune [--max-age 30]
|
||||
```
|
||||
|
||||
验收:
|
||||
|
||||
- 每个子命令有单元测试或集成测试。
|
||||
- 命令输出不依赖外部网络。
|
||||
- 写入文件前路径清晰可见。
|
||||
|
||||
## 测试计划
|
||||
|
||||
### 单元测试
|
||||
|
||||
| 测试文件 | 覆盖 |
|
||||
|----------|------|
|
||||
| `projectContext.test.ts` | project id / registry |
|
||||
| `learningPolicy.test.ts` | 命名、生成阈值、scope 决策 |
|
||||
| `observationStore.test.ts` | transcript ingestion / scrub |
|
||||
| `sessionObserver.test.ts` | 规则提取 |
|
||||
| `instinctStore.test.ts` | upsert / confidence / prune |
|
||||
| `skillGenerator.test.ts` | SKILL.md 生成 |
|
||||
| `evolution.test.ts` | cluster / classify |
|
||||
| `skillLifecycle.test.ts` | create/merge/replace/archive/delete 决策，replace 后旧 skill 不在 active index |
|
||||
|
||||
### 集成测试
|
||||
|
||||
```text
|
||||
fixture transcript
|
||||
-> ingest
|
||||
-> observe
|
||||
-> save instinct
|
||||
-> evolve --generate
|
||||
-> compare with existing skills
|
||||
-> archive/delete superseded skill when replacing
|
||||
-> getSkillIndex finds generated skill
|
||||
```
|
||||
|
||||
## 验证命令
|
||||
|
||||
```bash
|
||||
bun test src/services/skillLearning
|
||||
bun test src/commands/skill-learning
|
||||
bunx tsc --noEmit
|
||||
bun run lint
|
||||
```
|
||||
|
||||
## 风险
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| 学到错误模式 | 默认 pending，生成 skill 需要 confidence/evidence。 |
|
||||
| 污染全局习惯 | 默认 project scope，global 需要 promote。 |
|
||||
| 泄露代码/secret | observation scrub + 不把 raw code 写进 instinct。 |
|
||||
| 过度生成 skill | 低置信只保留 instinct，不生成 skill。 |
|
||||
| 与 ECC 冲突 | 使用 `~/.claude/skill-learning/`，不写 `~/.claude/homunculus/`。 |
|
||||
| 误删旧 skill | 默认 archive-first；hard delete 需要引用检查、manifest 和显式决策。 |
|
||||
|
||||
## 完成标准
|
||||
|
||||
- [ ] `skill-learning ingest` 能从真实 session JSONL 生成 observations。
|
||||
- [ ] `skill-learning status` 能显示 project/global instincts。
|
||||
- [ ] `skill-learning evolve --generate` 能生成 learned `SKILL.md`。
|
||||
- [ ] 生成前能识别现有 skill 并给出 create/merge/replace/archive/delete 决策。
|
||||
- [ ] replace 后旧 skill 不再被 active Skill Search 搜到。
|
||||
- [ ] archive/delete 会写 replacement manifest 或 tombstone。
|
||||
- [ ] 生成的 skill 能被现有 `Skill Search` 搜到。
|
||||
- [ ] `bunx tsc --noEmit` 通过。
|
||||
- [ ] 相关测试全部通过。
|
||||
Reference in New Issue
Block a user