forge

Forge 技能

跨厂商类比： Anthropic Managed Agents 的 memory + dreaming 组合中的捕获部分（2026 年 5 月）。Forge 挖掘对话记录；$curate --mode=dream 在会话之间进行整理。脱离 API、本地运行、跨厂商。

通常通过 SessionEnd hook 自动运行。

循环位置： 操作循环中第 7 步的捕获子步骤。从对话记录中提取候选经验；晋升棘轮决定哪些经验得以保留（一次性经验在交接时淘汰；重复出现的经验晋升到 .agents/learnings/）。Forge 是漏斗，不是筛选器。

从会话对话记录中提取知识。

工作原理

SessionEnd hook 运行：

ao forge transcript --last-session --queue --quiet

这会将该会话加入知识提取队列。

标志

标志	默认值	描述
--promote	关闭	处理 .agents/knowledge/pending/ 中待处理的提取结果，并将其晋升到 .agents/learnings/。整合了原先的 extract 技能。

晋升模式

执行 /forge --promote 时：

晋升步骤 1：查找待处理文件

ls -lt .agents/knowledge/pending/*.md 2>/dev/null
ls -lt .agents/ao/pending.jsonl 2>/dev/null

如果未找到待处理文件，则报告“No pending extractions”并退出。

晋升步骤 2：处理每个待处理文件

对于 .agents/knowledge/pending/ 中的每个文件：

1. 读取文件内容
2. 验证文件是否包含必需字段（# Learning:、**Category**:、**Confidence**:）
3. 复制到 .agents/learnings/（保留文件名）
4. 从 .agents/knowledge/pending/ 中移除源文件

晋升步骤 3：处理待处理队列

if [ -f .agents/ao/pending.jsonl ] && [ -s .agents/ao/pending.jsonl ]; then
  # Process each queued session
  cat .agents/ao/pending.jsonl
  # After processing, clear the queue
  > .agents/ao/pending.jsonl
fi

晋升步骤 4：报告

Promoted N learnings from pending → .agents/learnings/
Queue cleared.

完成。 报告后立即返回。

---

手动执行

执行 /forge [path] 时：

步骤 1：确定对话记录

使用 ao CLI：

# Mine recent sessions
ao forge transcript --last-session

# Mine specific transcript
ao forge transcript <path>

不使用 ao CLI： 查看近期对话历史并手动提取经验。

步骤 2：提取知识类型

阅读 skills/forge/references/uncaptured-lesson-patterns.md，了解信号模式和 26 种已知的未捕获经验类别。

在对话记录中查找以下模式：

类型	信号	权重
决策	“决定了”“选择了”“采用了”	0.8
经验	“了解到”“发现”“意识到”	0.9
失败	“失败是因为”“在……时出错”“不起作用”	1.0
模式	“总是执行 X”“诀窍是”“模式：”	0.7

未捕获经验匹配： 扫描对话记录时，将事件与 26 种已知的未捕获经验模式进行匹配（参见 references/uncaptured-lesson-patterns.md）。根据匹配到的模式元数据（类别、基础置信度、模式编号标签）预填经验模板。

步骤 3：写入候选项

写入位置： .agents/forge/YYYY-MM-DD-forge.md

# Forged: YYYY-MM-DD

## Decisions
- [D1] <decision made>
  - Source: <where in conversation>
  - Confidence: <0.0-1.0>

## Learnings
- [L1] <what was learned>
  - Source: <where in conversation>
  - Confidence: <0.0-1.0>

## Failures
- [F1] <what failed and why>
  - Source: <where in conversation>
  - Confidence: <0.0-1.0>

## Patterns
- [P1] <reusable pattern>
  - Source: <where in conversation>
  - Confidence: <0.0-1.0>

步骤 4：为搜索建立索引

if command -v ao &>/dev/null; then
  ao forge markdown .agents/forge/YYYY-MM-DD-forge.md 2>/dev/null
else
  # Without ao CLI: auto-promote high-confidence candidates to learnings
  mkdir -p .agents/learnings .agents/ao
  for f in .agents/forge/YYYY-MM-DD-*.md; do
    [ -f "$f" ] || continue
    # Extract confidence (numeric or categorical)
    CONF=$(grep -i "confidence:" "$f" | head -1 | awk '{print $NF}')
    # Normalize categorical to numeric: high=0.9, medium=0.6, low=0.3
    case "$CONF" in
      high) CONF_NUM=0.9 ;; medium) CONF_NUM=0.6 ;; low) CONF_NUM=0.3 ;; *) CONF_NUM=$CONF ;;
    esac
    # Auto-promote if confidence >= 0.7, prepending required frontmatter
    if (( $(echo "$CONF_NUM >= 0.7" | bc -l) )); then
      { printf -- '---\ntype: learning\nsource: forge\ndate: %s\nmaturity: provisional\nutility: 0.5\n---\n' "$(date +%Y-%m-%d)"; cat "$f"; } > .agents/learnings/"$(basename "$f")"
      TITLE=$(head -1 "$f" | sed 's/^# //')
      echo "{\"file\": \".agents/learnings/$(basename $f)\", \"title\": \"$TITLE\", \"keywords\": [], \"timestamp\": \"$(date -Iseconds)\"}" >> .agents/ao/search-index.jsonl
      echo "Auto-promoted (confidence $CONF): $(basename $f)"
    fi
  done
  echo "Forge indexing complete (ao CLI not available — high-confidence candidates auto-promoted)"
fi

步骤 5：更新捕获跟踪

提取与未捕获经验模式匹配的经验后（步骤 2），记录已捕获的模式。此状态保存在 .agents/forge/capture-tracking.json 中（运行时产物，绝不放在 skills/ 中）。

mkdir -p .agents/forge

1. 如果 .agents/forge/capture-tracking.json 存在，则读取；否则从 {} 开始
2. 对每个匹配的模式，按模式编号添加或更新条目：

   {
     "3": {"captured": true, "date": "2026-03-30", "learning_path": ".agents/learnings/tooling/use-bin-cp.md"},
     "7": {"captured": true, "date": "2026-03-29", "learning_path": ".agents/learnings/operations/worktree-commit.md"}
   }
   

3. 将更新后的 JSON 写回 .agents/forge/capture-tracking.json

模式编号对应 references/uncaptured-lesson-patterns.md 中带编号的标题（1-30，共 26 种模式）。

步骤 6：报告结果

告知用户：

• 按类型提取的条目数量
• Forge 输出位置
• 可晋升为经验的候选项
• 捕获进度：“已捕获 X/26 种未捕获经验模式”（从 .agents/forge/capture-tracking.json 读取）

质量池

Forge 生成的候选项从第 0 级（.agents/forge/）开始，然后通过人工审核、2 次或更多引用，或置信度 >= 0.7 时自动晋升（ao-free 后备机制），晋升到第 1 级（.agents/learnings/）。

关键规则

• 自动运行 - 通常通过钩子触发
• 提取，而非解读 - 记录实际说过的内容
• 按置信度评分 - 并非所有提取结果都一样
• 加入队列以供审核 - 候选内容需要验证

示例

请参阅 references/examples.md，了解 SessionEnd 钩子的调用流程和手动从转录记录中挖掘内容的流程。

故障排除

问题	原因	解决方案
未找到提取内容	转录记录缺少知识信号，或 ao CLI 不可用	检查转录记录是否包含决策和经验；确认已安装 ao CLI
置信度评分偏低	信号较弱或对话内容模糊	让会话聚焦于具体决策和明确的经验
forge --queue 失败	CLI 不可用或权限错误	手动将包含会话元数据的内容追加到 .agents/ao/pending.jsonl
forge 输出重复	同一会话被多次 forge	写入前检查 forge 文件名；ao CLI 会自动处理重复项

参考文档

• references/forge.feature — 可执行规范：挖掘转录记录 → 将候选内容加入队列；漏斗式收集而非过滤；--promote；使用转录记录而非技能（soc-qk4b）
• references/uncaptured-lesson-patterns.md — 转录记录挖掘中的信号模式和 26 种已知未捕获经验类别
• references/feedback-compiler-drafts.md — 自动起草的学习工作流（F5.4 fail->pass 台账状态转换，cli/internal/feedbackcompiler）