knowledge-extractor

Knowledge Extractor Skill

用途

此 Skill 会自动从对话、调试会话、失败的尝试和已解决的问题中提取、综合并保存知识。它将短暂的互动转化为持久的组织知识，从而提升未来的表现。

何时使用此 Skill

• 会话结束分析：在会话上下文丢失前提取经验
• 复杂调试后：趁记忆犹新，记录根本原因和解决方案
• 尝试失败后：记录哪些方法无效以及原因
• 成功解决问题后：保存解决方案，供日后复用
• 发现新模式时：识别值得记录的模式
• 工作流重复出现时：判断是否需要创建新的专用 Agent
• 跨会话学习：从单次会话中积累组织记忆

核心理念：知识保存

会话上下文：如果不主动保存，就会丢失的短暂对话上下文
持久知识：能够提升未来表现的结构化经验
模式识别：识别重复出现、值得自动化的解决方案
组织成长：将个人经验转化为系统级改进

知识提取框架

三种知识提取类型

1. 发现——新见解和根本原因

记录内容：遇到的问题、查明的根本原因、实施的解决方案

提取时机：

• 解决复杂 Bug 后
• 调试发现意外行为时
• 发现错误假设时
• 发现缺失功能后
• 弄清某件事失败的原因时

DISCOVERIES.md 格式：

## [Brief Title] (YYYY-MM-DD)

### Issue

What problem or challenge was encountered?

### Root Cause

Why did this happen? What was the underlying issue?

### Solution

How was it resolved? Include code examples if relevant.

### Key Learnings

What insights were gained? What should be remembered?

### Prevention

How can this be avoided in the future?

质量标准：

• ✅ 描述具体问题，而非泛泛的建议
• ✅ 清楚指出根本原因
• ✅ 包含可行的解决方案
• ✅ 总结可复用的经验
• ✅ 记录预防策略

2. 模式——可复用的解决方案

记录内容：针对反复出现的问题、架构方法和设计模式的成熟解决方案

提取时机：

• 解决与已知模式类似的问题后
• 识别出重复出现的问题类型时
• 实施成熟解决方案时
• 发现有效的最佳实践时
• 解决方案适用于多种场景时

PATTERNS.md 格式：

## Pattern: [Name]

### Challenge

What problem does this pattern solve?

### Solution

How does the pattern work? Include code/examples.

### Key Points

- Main insight 1
- Main insight 2
- When to use / when not to use

### When to Use

Specific scenarios where this pattern applies.

### Real Impact

Where has this pattern been used successfully?

### Related Patterns

Links to similar or complementary patterns.

质量标准：

• ✅ 足够通用，适用于多种情况
• ✅ 清楚定义问题
• ✅ 解决方案经过实践验证
• ✅ 提供可运行的代码示例
• ✅ 明确说明适用和不适用的情况

3. 创建 Agent——自动化重复工作流

记录内容：频繁重复的工作流、专门的专业领域、复杂的多步骤流程

提取时机：

• 相同工作流已执行 2–3 次后
• 识别出专门的技能领域时
• 工作流具有明确的输入和输出时
• 自动化能节省大量时间时
• 问题领域范围狭窄且定义明确时

创建 Agent 的触发条件清单：

• 相同工作流已重复 2 次以上
• 执行该工作流需要 30 分钟以上
• 工作流有明确的专门用途
• 可使用当前工具实现工作流自动化
• 问题领域范围狭窄且定义明确
• 自动化具有很高的价值

创建 Agent 示例：

## Recommended New Agent: [domain]-[specialty]

### Problem

What repeated workflow would this agent handle?

### Scope

What's in scope | What's explicitly out of scope

### Inputs

What information does the agent need?

### Process

Step-by-step workflow the agent follows

### Outputs

What does the agent produce?

### Value

How much time/effort does this save?

### Integration

Where in the workflow does this fit?

分步提取流程

步骤 1：会话分析（5 分钟）

回顾完整的对话/会话：

1. What was the original problem/request?
2. What approaches were tried?
3. Which attempts failed and why?
4. What succeeded and why?
5. What was learned in the process?
6. What surprised you?
7. What took longer than expected?
8. What would have helped?

步骤 2：模式识别（5 分钟）

识别工作中的模式：

1. Have I seen this problem before? (→ DISCOVERIES)
2. Is this a generalizable solution? (→ PATTERNS)
3. Would this be worth automating? (→ AGENT)
4. What was the root cause? (Why, not just what)
5. What should others know about this?
6. What should be remembered to avoid repetition?

第 3 步：知识提取（10 分钟）

提取并整理知识：

对于 DISCOVERIES.md：

• 遇到的具体问题
• 根因分析
• 实施的解决方案
• 总结提炼的关键经验
• 预防策略

对于 PATTERNS.md：

• 该模式解决的问题
• 模式的工作方式
• 适用场景 / 不适用场景
• 可运行的代码示例
• 相关模式

对于新 Agent：

• 识别出的重复工作流
• 明确的范围和边界
• 输入 / 输出要求
• 分步流程
• 预期价值 / 时间节省

第 4 步：集成（3 分钟）

将知识放入正确的位置：

Memory → Store discovery using store_discovery() from amplihack.memory.discoveries
PATTERNS.md → New pattern in appropriate section
Agent → Create in .claude/agents/amplihack/specialized/

第 5 步：验证（2 分钟）

确保质量：

[ ] Entry is specific, not generic
[ ] Entry follows template format
[ ] Examples/code provided
[ ] Quality sufficient for reuse
[ ] Grammar and clarity checked
[ ] Related items cross-referenced

使用示例

示例 1：修复 Bug 后提取经验

场景：刚花了 45 分钟排查 pre-commit hooks 无法正常工作的原因

User: Extract what we learned from debugging the pre-commit issue.

Claude:
1. Analyzes conversation showing:
   - Initial problem: hooks appeared to run but didn't modify files
   - False leads: blamed merge conflicts, tool versions
   - Root cause found: Hooks couldn't write to files due to cloud sync lock
   - Solution: Added exponential backoff retry logic
   - Time to discover: 45 minutes

2. Creates DISCOVERIES.md entry:
   - Issue: Pre-commit hooks silently failing
   - Root Cause: Cloud sync (OneDrive) file locks
   - Solution: Exponential backoff retry (0.1s, 0.2s, 0.4s...)
   - Key Learning: Cloud sync issues silent - need defensive coding
   - Prevention: Add retry logic for file I/O, test with cloud storage

3. Offers to also:
   - Add pattern for "Resilient File I/O" to PATTERNS.md
   - Suggest new agent for cloud-sync issue detection

示例 2：从成功的实现中提取模式

场景：刚完成模块重新生成策略的实现

User: Extract the pattern we discovered for building regeneratable modules.

Claude:
1. Analyzes implementation showing:
   - Clear __all__ exports defining public interface
   - Self-contained module structure
   - Type-hinted functions with docstrings
   - Comprehensive test coverage
   - Working examples

2. Creates PATTERNS.md entry:
   - Pattern: Module Regeneration Structure
   - Challenge: Modules become tightly coupled, hard to regenerate
   - Solution: Brick & studs design with __all__ public API
   - Key Points: Clear contracts, single responsibility, testable behavior
   - When to Use: Any utility module, anything that might be regenerated
   - Real Impact: Enables AI to rebuild modules without breaking system

3. Cross-references:
   - Relates to "Bricks & Studs Module Design"
   - Enables "Builder Agent Workflow"

示例 3：发现创建新 Agent 的机会

场景：第三次使用 5 步诊断流程排查 CI 故障

User: We keep using the same CI debugging process. Should we automate it?

Claude:
1. Analyzes past sessions:
   - Session 1: 45 minutes CI debugging (version mismatch issue)
   - Session 2: 30 minutes CI debugging (pre-commit hook issue)
   - Session 3: 25 minutes CI debugging (merge conflict issue)
   - Pattern: Same 5-step process each time

2. Recommends new agent:
   - Name: ci-diagnostic-workflow
   - Problem: Each CI failure requires manual diagnosis, takes 30-45 min
   - Scope: Diagnoses CI failures, suggests fixes (doesn't auto-fix)
   - Process:
     1. Check environment (Python version, tool versions)
     2. Analyze CI logs for error patterns
     3. Detect common issues (conflicts, missing deps)
     4. Suggest solutions
     5. Coordinate parallel diagnostic agents
   - Value: Reduce diagnosis time from 45 min → 15 min

3. Proposes creating:
   - .claude/agents/amplihack/ci-diagnostic-workflow.md
   - Can delegate to: fix-agent for implementation

示例 4：多层次提取

场景：复杂的架构决策，包含多项经验

User: Extract everything we learned from deciding on the memory architecture.

Claude:
1. Session involved:
   - 2 failed approaches (too complex, wrong threat model)
   - 1 successful approach (simple, fits threat model)
   - Discovery of meta-pattern for architecture decisions

2. Creates THREE extractions:

   DISCOVERIES.md:
   - Issue: Pattern Applicability Analysis
   - Root Cause: Importing patterns without validating threat match
   - Solution: Five-phase applicability analysis framework
   - Learning: Threat model match is critical first check

   PATTERNS.md:
   - New Pattern: Threat Model Precision Principle
   - Challenge: Fault tolerance mechanisms mismatch problem space
   - Solution: Validate threat model before adopting patterns
   - When: Before adopting any "best practice" from different domain

   Recommended Agent:
   - Name: pattern-applicability-analyzer
   - Automate: Quick assessment of pattern applicability
   - Value: Prevent adopting wrong patterns early

知识质量检查清单

完成提取前，请确认：

对于 DISCOVERIES.md

• 问题具体明确，而非泛泛而谈（“Pre-commit hooks 失败”，而非“工具损坏”）
• 已找出根因（解释为什么，而不只是描述问题）
• 解决方案有效且经过验证
• 经验已总结提炼（可应用于此具体案例之外）
• 预防策略可执行
• 不包含猜测或面向未来的过度设计
• 在适用的情况下提供代码示例

对于 PATTERNS.md

• 问题清晰且易于识别
• 解决方案已有成功实践（成功使用 2 次或以上）
• 何时适用 / 何时不适用的指引清晰
• 模式足够通用，可重复使用
• 代码示例可运行且清晰
• 已交叉引用相关模式
• 已记录实际影响或使用情况

对于新 Agent

• 工作流已重复执行 2 次或以上
• 每次执行可节省 30 分钟或以上
• 问题领域范围明确且定义清晰
• 输入和输出清晰
• 已记录分步流程
• 价值足够高，值得投入自动化工作
• 明确其在工作流中的位置

与系统的集成

发现记录的生命周期

1. 提取：在会话期间通过 store_discovery() 将内容存入记忆
2. 可见性：在会话开始时通过 get_recent_discoveries() 检索
3. 行动：Agent 可在解决类似问题时查询记忆
4. 预防：避免在不同会话中重复犯同样的错误
5. 演进：发现更好的解决方案时更新

PATTERNS.md 的生命周期

1. 提取：模式得到验证后，添加到 PATTERNS.md
2. 编目：纳入可用模式库
3. 使用：在相关 Agent 指令中引用
4. 传授：用于文档和入门培训
5. 改进：随着收集到更多使用数据而不断完善

Agent 创建的生命周期

1. 推荐：将其识别为有价值的自动化候选项
2. 提案：向系统提出，并说明预期价值
3. 创建：创建具有明确范围和边界的新 Agent
4. 集成：添加到 CLAUDE.md 的委派触发条件中
5. 使用：可用于协调各类工作流

实际影响示例

影响 1：避免浪费排查时间

提取知识之前：重复相同的 45 分钟排查流程
提取知识之后：从记忆中检索经验，10 分钟内解决问题

影响 2：更快找到解决方案

未提取知识：从头重新发现解决方案
已提取知识：参考 PATTERNS.md，应用已知解决方案

影响 3：自动化工作流

未创建新 Agent：每次都手动排查 CI 故障（30-45 分钟）
创建新 Agent 后：5-10 分钟内自动完成诊断

应避免的常见提取错误

错误 1：过于笼统

BAD: "Learned that good error handling is important"
GOOD: "Discovered cloud sync issues cause silent file I/O failures - need exponential backoff retry"

错误 2：遗漏根本原因

BAD: "CI failed, fixed it"
GOOD: "CI failed because version mismatch (local 3.12 vs CI 3.11) - fixed by updating pyproject.toml version constraint"

错误 3：缺乏可执行的经验

BAD: "This was complicated"
GOOD: "Multi-layer sanitization at every data transformation prevents credential leakage"

错误 4：过度泛化模式

BAD: "Always use caching everywhere"
GOOD: "Use smart caching with lifecycle management for expensive operations where results may become stale"

错误 5：创建 Agent 却没有投资回报

BAD: "Create agent for task that happens once per quarter"
GOOD: "Create agent for CI debugging workflow that happens 2-3x per week and takes 30-45 minutes"

提取提示词

使用以下提示词触发知识提取：

提取发现

Extract what we discovered/learned from this session.
Focus on: root causes, unexpected behaviors, solutions that worked.
Update DISCOVERIES.md appropriately.

提取模式

What patterns should we capture for future reuse?
These should be proven solutions that apply to multiple situations.
Update PATTERNS.md appropriately.

识别 Agent 机会

Should we create a new agent to automate any repeated workflows?
Check if any workflow has been done 2+ times and takes 30+ minutes.
Recommend creation with scope and value calculation.

完整提取

Perform complete knowledge extraction on this session.
Extract: discoveries, patterns, and agent creation recommendations.
Verify quality and update all three knowledge bases.

集成点

与文档驱动开发集成

• 使用知识提取来更新规范和文档
• 提取模式，为下一步实现提供指导

与 Agent 委派集成

• 委派过程中发现需要新的专长时，进行提取
• 根据反复出现的委派模式创建 Agent

与提交前分析集成

• 提取有关 CI/CD 和测试模式的发现
• 将新发现的方法更新到 PATTERNS.md

与会话反思集成

• 在会话结束时自动提取知识
• 在上下文压缩前保留经验

成效指标

跟踪知识提取的效果：

• 发现复用率：DISCOVERIES.md 避免错误的频率（目标：80% 以上）
• 模式应用率：PATTERNS.md 帮助更快解决问题的频率（目标：70% 以上）
• Agent 使用率：提取出的 Agent 相对于手动方式的使用频率（目标：60% 以上）
• 节省时间：通过复用知识累计节省的时间（目标：每周数小时）
• 重复错误：同一错误再次发生的次数减少情况（目标：95% 以上）

未来演进

此技能应根据以下方面不断发展：

• 哪些类型的知识最值得提取？
• 哪些因素会妨碍有效提取？
• 如何让提取结果更具可操作性？
• 哪些知识来源尚未得到充分利用？
• 如何更好地呈现相关知识？

将经验记录在 ~/.amplihack/.claude/context/DISCOVERIES.md 中。