extract

提取技能

通常通过 SessionStart 钩子自动运行。

处理之前会话中待处理的学习提取。

工作原理

SessionStart 钩子会运行：

ao extract

此操作会检查排队等待处理的提取项，并输出提示词，供 Claude 处理。

手动执行

给定 /extract：

步骤 1：检查待处理的提取项

ao extract 2>/dev/null

或者检查待处理队列：

cat .agents/ao/pending.jsonl 2>/dev/null | head -5

步骤 1.5：没有 ao CLI 时——手动提取

如果无法使用 ao CLI，请手动处理待处理队列：

if ! command -v ao &>/dev/null; then
  echo "ao CLI not available — running manual extraction"

  # Check for pending queue
  if [ -f .agents/ao/pending.jsonl ] && [ -s .agents/ao/pending.jsonl ]; then
    echo "Found pending extractions:"
    cat .agents/ao/pending.jsonl

    # For each pending entry, check for corresponding forge output
    # Forge outputs live in .agents/forge/
    for forge_file in .agents/forge/*.md; do
      [ -f "$forge_file" ] || continue
      echo "Processing: $forge_file"
    done
  else
    echo "No pending extractions found."
  fi

  # After processing, check .agents/forge/ for unprocessed candidates
  FORGE_COUNT=$(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')
  if [ "$FORGE_COUNT" -gt 0 ]; then
    echo "$FORGE_COUNT forge candidates found — review and extract learnings manually."
    echo "For each candidate in .agents/forge/:"
    echo "  1. Read the candidate file"
    echo "  2. Extract actionable learnings using the template in Step 3"
    echo "  3. Write to .agents/learnings/YYYY-MM-DD-<topic>.md"
    echo "  4. High-confidence items (>= 0.7) can be promoted directly"
  fi
fi

对于每个 forge 候选项，使用本技能步骤 3 中定义的相同模板格式提取学习内容。将结果写入 .agents/learnings/。处理完成后，清空待处理队列：

# Clear processed entries
> .agents/ao/pending.jsonl
echo "Pending queue cleared"

步骤 2：处理每个待处理项

对于队列中的每个会话：

1. 阅读会话摘要
2. 提取可执行的学习内容
3. 写入 .agents/learnings/

步骤 3：写入学习内容

写入位置： .agents/learnings/YYYY-MM-DD-<session-id>.md

# Learning: <Short Title>

**ID**: L1
**Category**: <debugging|architecture|process|testing|security>
**Confidence**: <high|medium|low>

## What We Learned

<1-2 sentences describing the insight>

## Why It Matters

<1 sentence on impact/value>

## Source

Session: <session-id>

步骤 3.5：验证学习内容

写入学习文件后，验证每个文件都包含必需字段：

1. 扫描新写入的文件：

ls -t .agents/learnings/YYYY-MM-DD-*.md 2>/dev/null | head -5

2. 检查每个文件的必需字段：

   • 标题： 文件必须以 # Learning: <title> 开头（标题不能为空）
   • 类别： 必须包含 **Category**: <value>，其中 value 必须为以下之一：debugging、architecture、process、testing、security
   • 置信度： 必须包含 **Confidence**: <value>，其中 value 必须为以下之一：high、medium、low
   • 内容： 必须包含 ## What We Learned 章节，且标题下至少有一行非空内容

3. 报告验证结果：

   • 对于每条有效的学习内容：“✓ : 有效”
   • 对于每条无效的学习内容：“⚠ : 缺少 ”（列出所有缺失字段）

4. **不要删除或重试无效的学习内容。**记录警告并继续。无效的学习内容仍胜过没有学习内容——警告有助于长期发现提取质量问题。

步骤 4：清空队列

ao extract --clear 2>/dev/null

步骤 5：报告完成情况

告知用户：

• 提取的学习内容数量
• 关键见解
• 学习文件的位置

知识循环

Session N ends:
  → ao forge --last-session --queue
  → Session queued in pending.jsonl

Session N+1 starts:
  → ao extract (this skill)
  → Claude processes the queue
  → Writes to .agents/learnings/
  → Validates required fields
  → Loop closed

关键规则

• 自动运行——通常通过钩子运行
• 处理队列——不要让提取项一直处于待处理状态
• 具体明确——提取可执行的学习内容，而非模糊的观察
• 闭合循环——提取完成知识循环

示例

SessionStart 钩子调用

钩子触发：session-start.sh 在会话开始时运行

执行过程：

1. 钩子调用 ao extract 2>/dev/null
2. CLI 输出排队的会话 ID 和提示词
3. Agent 处理每个待处理的提取项
4. Agent 将学习内容写入 .agents/learnings/<date>-<session>.md
5. Agent 验证必需字段并报告结果
6. 钩子调用 ao extract --clear 清空队列

**结果：**之前会话中的知识会在会话开始时自动提取，无需用户操作。

手动触发提取

用户说：/extract 或“从上一个会话中提取学习内容”

执行过程：

1. Agent 使用 ao extract 检查待处理队列
2. Agent 阅读队列中的会话摘要
3. Agent 提取决策、学习内容和失败经验
4. Agent 按正确结构写入 .agents/learnings/
5. Agent 验证字段（类别、置信度、内容）
6. Agent 清空队列并报告完成情况

**结果：**手动处理待提取项，清空队列，并为学习内容建立索引。

故障排除

问题	原因	解决方案
未找到待处理的提取内容	队列为空或 ao CLI 不可用	检查 .agents/ao/pending.jsonl 是否存在；确认已安装 ao CLI
学习内容警告无效	缺少类别、置信度或内容	检查学习文件，补上缺失字段；不要删除
extraction --clear 失败	CLI 不可用或权限错误	作为备用方案，手动清空 .agents/ao/pending.jsonl
提取内容重复	处理后队列未清空	写入学习内容后，务必运行 ao extract --clear