athena

Athena — 主动知识智能

运行 Mine → Grow → Defrag 循环，保持知识飞轮健康运转。

此技能的作用

知识飞轮通过 /retro、/post-mortem 被动捕获经验。Athena 通过主动挖掘尚未提取的信号、根据当前代码验证已有经验、综合跨领域洞见，以及清理过时或重复的内容，来闭合这一循环。

使用时机： 在演进周期开始前、大量开发工作完成后，或每周使用。
Athena 不会破坏现有内容——它只会提出修改建议，不会修改已有经验。

输出： .agents/athena/YYYY-MM-DD-report.md

执行步骤

第 1 步 — Mine：提取信号

运行机械式提取。Mine 会扫描 Git 历史记录、.agents/research/ 和代码复杂度热点，查找尚未被记录为经验的模式。

ao mine --since 26h                    # default: all sources, last 26h
ao mine --since 7d --sources git,agents  # wider window, specific sources

读取 .agents/mine/latest.json 并提取：协同变更集群（一起变更的文件）、孤立研究（未被引用的 .agents/research/ 文件）和复杂度热点（近期有编辑记录的高圈复杂度函数）。

回退方案（无 ao CLI 时）： 使用 git log --since="7 days ago" --name-only 查找重复出现的文件组。列出 .agents/research/*.md，并检查经验条目中的引用。

分配初始置信度。 为提取出的每个新经验候选项，根据证据强度分配置信度分数：

证据	分数	原因
单次会话中的观察	0.3	仅为个例——只观察到一次，可能无法推广
用户明确纠正或事后复盘结论	0.5	已得到验证——经用户确认的信号
在 2+ 次会话中观察到的模式	0.6	重复出现——很可能是真实规律，而非巧合
在多个会话或项目中得到验证	0.7	证据充分——可安全地自动应用
经受实战检验，从未被证伪	0.9	几乎确定——始终应用

同时分配一个 scope 标签：project:<name>（项目专属）、language:<lang> （语言约定）或 global（通用模式）。默认使用 project:<current>，除非该模式明确适用于所有语言或工具。

将置信度和 scope 写入经验条目的 frontmatter：

---
title: "Learning title"
confidence: 0.3
scope: project:agentops
observed_in:
  - session: "YYYY-MM-DD"
    context: "Brief description of observation"
---

第 2 步 — 增长：由大模型驱动的综合分析

这是推理阶段。通过工具调用执行每个子步骤。

飞轮健康诊断： 计算 σ（一致性）、ρ（速度）、δ（衰减），并报告逃逸速度状态。测量命令和修复措施请参阅 references/flywheel-diagnostics.md。

2a. 验证重点学习内容并调整置信度

从 .agents/learnings/ 中选出最近的 5 个文件。对每个文件：

1. 阅读学习文件（包括其 confidence 和 scope frontmatter）
2. 如果文件引用了函数或文件路径，使用 Read 确认代码仍然存在
3. 分类为：已验证（相符）、过时（已变更）或相矛盾（情况相反）
4. 根据验证结果调整置信度：
   • 已验证且仍准确：+0.1（最高为 0.9）
   • 已过时但部分正确：不变（标记为待审核）
   • 与当前代码相矛盾：-0.2（最低为 0.1，标记为待移除）
   • 在新项目中验证了该模式：+0.15
   • 30 天以上未引用：-0.05（时间衰减）
   • 90 天以上未引用：-0.1（时间衰减）

使用新的置信度分数更新学习文件的 frontmatter。

自动晋升规则： 调整置信度后，检查该学习内容的置信度是否**> 0.7**。如果是，且尚未收录在 MEMORY.md 中，则将其晋升：

1. 将该学习内容的关键见解添加到相关的 MEMORY.md 主题文件中
2. 记录："Promoted '<title>' to MEMORY.md (confidence: <score>)"
3. 如果同一模式出现在 2 个或更多项目中，且置信度 >= 0.8，则将其范围从 project:<name> 晋升为 global

2b. 救回孤立研究

对于 mine 输出中的每个孤立研究文件：阅读文件，用 2-3 句话概述关键见解，并提出一个新的学习候选项，附上标题和类别。

2c. 跨领域综合分析

按主题（例如“测试模式”“CLI 约定”）对 mine 发现进行分组。对于包含 2 个或更多发现的主题，撰写一个综合模式候选项，概括其共同原则。

2d. 识别知识缺口

将 mine 输出中的主题与现有学习内容进行比较。没有对应学习内容的主题即为知识缺口。逐项列出：主题、证据、建议的学习标题。

第 3 步 — 整理：机械清理

运行清理，查找过时、重复和反复摇摆的条目。

ao defrag --prune --dedup --oscillation-sweep

读取 .agents/defrag/latest.json 并记录：孤立的学习内容（未被引用且已超过 30 天）、近似重复项（内容相似度 >80%）以及摇摆的目标（连续 3 个或更多周期在改进/失败之间交替）。

回退方案： 使用 find .agents/learnings -name "*.md" -mtime +30 查找过时文件。 检查 .agents/evolve/cycle-history.jsonl，查找交替出现的结果模式。

规范化缺陷扫描

整理期间，扫描学习内容和模式池，查找会降低飞轮质量的结构性缺陷：

# Placeholder patterns: files with only frontmatter, no content after closing ---
for f in .agents/patterns/**/*.md .agents/learnings/**/*.md; do
  [ -f "$f" ] || continue
  content_after_frontmatter=$(awk '/^---$/{n++; if(n==2) found=1; next} found{print}' "$f" | grep -c '[^ ]')
  [ "$content_after_frontmatter" -eq 0 ] && echo "PLACEHOLDER: $f"
done

# Stacked frontmatter: multiple --- delimiter pairs (>2 occurrences of ^---$)
grep -rl '^---$' .agents/learnings/ .agents/patterns/ 2>/dev/null | while read f; do
  count=$(grep -c '^---$' "$f")
  [ "$count" -gt 2 ] && echo "STACKED_FRONTMATTER: $f ($count delimiters)"
done

# Bundled multi-learning files: more than one ## Learning heading
grep -rl '^## Learning' .agents/learnings/ 2>/dev/null | while read f; do
  count=$(grep -c '^## Learning' "$f")
  [ "$count" -gt 1 ] && echo "BUNDLED: $f ($count learnings in one file)"
done

# Duplicated headings within a file
for f in .agents/learnings/**/*.md .agents/patterns/**/*.md; do
  [ -f "$f" ] || continue
  dupes=$(grep '^## ' "$f" | sort | uniq -d)
  [ -n "$dupes" ] && echo "DUPLICATE_HEADING: $f — $dupes"
done

在整理输出中报告规范化缺陷。如果发现任何缺陷，请列出并标明严重程度：

• PLACEHOLDER → HIGH（空知识会污染检索结果）
• STACKED_FRONTMATTER → MEDIUM（会导致解析错误，并可能造成数据丢失）
• BUNDLED → HIGH（会破坏逐条学习内容的引用跟踪）
• DUPLICATE_HEADING → LOW（仅影响外观，可能使提取过程产生混淆）

应将这些缺陷标记为待人工审核，或在下一次 forge 周期中自动拆分。

第 4 步 — 报告

mkdir -p .agents/athena

编写 .agents/athena/YYYY-MM-DD-report.md：

# Athena Report — YYYY-MM-DD

## New Learnings Proposed
- [title]: [summary] (source: [research file or synthesis])

## Validations
- Validated: N | Stale: N (list files) | Contradicted: N (list with explanation)

## Knowledge Gaps
- [topic]: [evidence] → suggested learning: "[title]"

## Defrag Summary
- Orphaned: N | Duplicates: N | Oscillating goals: N

## Recommendations
1. [Actionable next step]

如果 bd 可用，则为知识缺口创建问题：

bd add "[Knowledge Gap] <topic>" --label knowledge --label athena

向用户报告发现：建议的学习内容、验证结果、知识缺口以及建议执行的整理操作。

调度 / 自动触发

轻量级整理（清理 + 去重，不进行挖掘）会在会话结束时通过 athena-session-defrag.sh 钩子自动运行。这样无需手动调用 /athena， 就能保持知识库整洁。该钩子：

• 在每次 SessionEnd 事件中，于 session-end-maintenance.sh 之后触发
• 如果没有可用的 ao CLI，则静默跳过
• 只运行 ao defrag --prune --dedup（不运行 --oscillation-sweep 或挖掘）
• 超时时间为 20 秒，以避免阻塞会话关闭

如需运行完整的挖掘 → 增长 → 整理周期，请手动调用 /athena。

示例

用户输入： /athena — 完整的挖掘 → 增长 → 整理周期，并在 .agents/athena/ 中生成报告。

用户输入： /athena --since 7d — 使用更宽的时间窗口（7 天）进行挖掘。

进化前预热： 在运行 /evolve 前运行 /athena，以获取最新且经过验证的知识库。

故障排除

问题	原因	解决方案
找不到 ao mine	PATH 中没有 ao CLI	使用步骤 1 中的手动备用方案
没有孤立研究	所有研究都已被引用	跳过 2b，继续综合
挖掘输出为空	最近没有活动	扩大 --since 时间窗口
振荡扫描结果为空	没有振荡目标	状态正常——无需采取操作

参考文档

• references/confidence-scoring.md
• references/knowledge-synthesis-patterns.md
• references/flywheel-diagnostics.md