flywheel

Flywheel 技能

循环位置： 运行循环中的第 7 步（捕获 + 棘轮）——监测由晋升棘轮推动的知识池健康状况。 监测知识飞轮的健康状况。

飞轮模型

Sessions → Transcripts → Forge → Pool → Promote → Knowledge
     ↑                                               │
     └───────────────────────────────────────────────┘
                    Future sessions find it

速度 = 知识流动的速率。摩擦 = 阻碍飞轮运转的瓶颈。

折叠触发器（ag-s43tg wave 1）：ratchet 路由至此

• ratchet → 飞轮门控跟踪。 当用户要求记录 Brownian Ratchet 门控时使用 — 跟踪 RPI 工作流中的进度，其中包含永久门控 （Progress = Chaos × Filter → Ratchet；已合并／已关闭／已存储的进度无法取消棘轮）。
• 门控接口：.agents/ao/chain.jsonl 中的链可通过 ao ratchet status / ao ratchet check <step> / ao ratchet record <step> --output "<artifact-path>" 操作 （步骤：research、plan、implement、vibe、post-mortem）。
• Ratchet 跟踪并锁定进度；它本身不运行循环——需搭配 /crank （史诗循环）或 /swarm（Ralph 循环）来执行工作。

执行步骤

收到 /flywheel 后：

第 1 步：测量知识池

# Count top-level artifact files (avoid counting directories)
LEARNINGS=$(find .agents/learnings -maxdepth 1 -type f 2>/dev/null | wc -l)
PATTERNS=$(find .agents/patterns -maxdepth 1 -type f 2>/dev/null | wc -l)
RESEARCH=$(find .agents/research -maxdepth 1 -type f 2>/dev/null | wc -l)
RETROS=$(find .agents/retros -maxdepth 1 -type f 2>/dev/null | wc -l)
echo "Learnings: $LEARNINGS"
echo "Patterns: $PATTERNS"
echo "Research: $RESEARCH"
echo "Retros: $RETROS"

第 2 步：检查近期活动

# Recent learnings (last 7 days)
find .agents/learnings -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l
# Recent research
find .agents/research -maxdepth 1 -type f -mtime -7 2>/dev/null | wc -l

第 3 步：检测过时内容

# Old artifacts (> 30 days without modification)
find .agents/ -name "*.md" -mtime +30 2>/dev/null | wc -l

第 3.5 步：检查缓存健康状况

if command -v ao &>/dev/null; then
  # Get citation report (cache metrics)
  CITE_REPORT=$(ao metrics cite-report --json --days 30 2>/dev/null)
  if [ -n "$CITE_REPORT" ]; then
    HIT_RATE=$(echo "$CITE_REPORT" | jq -r '.hit_rate // "unknown"')
    UNCITED=$(echo "$CITE_REPORT" | jq -r '(.uncited_learnings // []) | length')
    STALE_90D=$(echo "$CITE_REPORT" | jq -r '.staleness["90d"] // 0')
    echo "Cache hit rate: $HIT_RATE"
    echo "Uncited learnings: $UNCITED"
    echo "Stale (90d uncited): $STALE_90D"
  fi
else
  # ao-free fallback: compute approximate metrics from files
  echo "Cache health (ao-free fallback):"
  echo "Active learnings (30d): $(find .agents/learnings/ -name '*.md' -mtime -30 2>/dev/null | wc -l | tr -d ' ')"
  echo "Forge candidates pending: $(ls .agents/forge/*.md 2>/dev/null | wc -l | tr -d ' ')"
  if [ -f .agents/ao/citations.jsonl ]; then
    echo "Total citations: $(wc -l < .agents/ao/citations.jsonl | tr -d ' ')"
    echo "Unique learnings cited: $(grep -o '"artifact_path":"[^"]*"' .agents/ao/citations.jsonl 2>/dev/null | sort -u | wc -l | tr -d ' ')"
  else
    echo "No citation data (citations.jsonl not found)"
  fi
  [ -f .agents/ao/outcomes.jsonl ] && echo "Session outcomes recorded: $(wc -l < .agents/ao/outcomes.jsonl | tr -d ' ')"
fi

第 4 步：检查 ao CLI 状态

if command -v ao &>/dev/null; then
  ao metrics flywheel status 2>/dev/null || echo "ao metrics flywheel status unavailable"
  ao status 2>/dev/null || echo "ao status unavailable"
  ao maturity --scan 2>/dev/null || echo "ao maturity unavailable"
  ao anti-patterns 2>/dev/null || echo "ao anti-patterns unavailable"
  ao badge 2>/dev/null || echo "ao badge unavailable"

  # Knowledge maintenance
  ao dedup --merge 2>/dev/null || true
  ao contradict 2>/dev/null || true
  ao constraint review 2>/dev/null || true
  ao curate status 2>/dev/null || true
  ao metrics health 2>/dev/null || true
  ao metrics cite-report --days 30 2>/dev/null || true

  # Active pruning: archive stale, evict low-utility, and curate noisy uncited learnings
  ao maturity --expire --archive 2>/dev/null || true
  ao maturity --evict --archive 2>/dev/null || true
  ao maturity --curate --archive 2>/dev/null || true

  # Retrieval quality: use the representative live corpus when it exists
  if [ -d cli/cmd/ao/testdata/retrieval-bench-live ]; then
    ao eval bench --live --corpus cli/cmd/ao/testdata/retrieval-bench-live --json 2>/dev/null || true
  fi
else
  echo "ao CLI not available — using file-based metrics"
  echo "Pool depths:"
  for pool in learnings patterns forge knowledge research retros; do
    echo "  $pool: $(ls .agents/${pool}/*.md 2>/dev/null | wc -l | tr -d ' ')"
  done
  echo "  global patterns: $(ls ~/.claude/patterns/*.md 2>/dev/null | wc -l | tr -d ' ')"
  echo "See references/promotion-tiers.md for tier definitions"
fi

第 4.5 步：处理指标（来自技能遥测）

如果 .agents/ao/skill-telemetry.jsonl 存在，使用 jq 提取：按技能统计的调用次数、每项技能的平均周期时间、门控失败率。在健康报告（第 6 步）的 ## Process Metrics 部分中列出。

第 5 步：验证产物一致性

交叉引用验证：扫描知识产物，查找失效的内部引用。 使用 scripts/artifact-consistency.sh（方法见 references/artifact-consistency.md）。 默认允许列表位于 references/artifact-consistency-allowlist.txt；使用 --no-allowlist 执行完整的原始审计。

健康指标：>90% = 健康，70-90% = 警告，<70% = 严重。

第 6 步：编写健康报告

写入： .agents/flywheel-status.md

# Knowledge Flywheel Health

**Date:** YYYY-MM-DD

## Pool Depths
| Pool | Count | Recent (7d) |
|------|-------|-------------|
| Learnings | <count> | <count> |
| Patterns | <count> | <count> |
| Research | <count> | <count> |
| Retros | <count> | <count> |

## Velocity (Last 7 Days)
- Sessions with extractions: <count>
- New learnings: <count>
- New patterns: <count>

## Artifact Consistency
- References scanned: <count>
- Broken references: <count>
- Consistency score: <percentage>%
- Status: <Healthy/Warning/Critical>

## Cache Health
- Hit rate: <percentage>%
- Uncited learnings: <count>
- Stale (90d uncited): <count>
- Status: <Healthy/Warning/Critical>

## Retrieval Quality
- Live corpus coverage: <percentage or unavailable>
- Live corpus learnings: <count or unavailable>
- Status: <Healthy/Warning/Critical>

## Health Status
<Healthy/Warning/Critical>

## Friction Points
- <issue 1>
- <issue 2>

## Recommendations
1. <recommendation>
2. <recommendation>

第 7 步：向用户汇报

告知用户：

1. 飞轮整体健康状况
2. 知识池深度
3. 近期活动
4. 任何摩擦点
5. 建议

健康指标

指标	健康	警告	严重
每周经验总结	3+	1-2	0
过时产物	<20%	20-50%	>50%
研究／计划比率	>0.5	0.2-0.5	<0.2
缓存命中率	>80%	50-80%	<50%

黄金信号

四个黄金信号（始终显示）揭示知识是否真正实现复利增长，还是只是在累积噪声。

ao flywheel status              # table output with golden signals
ao flywheel status --json       # machine-readable

四项信号

#	信号	问题	关键指标
1	速度趋势	σρ-δ 是否在增长？	基准速度的线性回归斜率（7d/30d）
2	引用管道	引用是否有用？	奖励 > 0.6 的反馈占比
3	研究闭环	研究是否得到挖掘？	孤立研究占比（没有学习反向链接）
4	复用集中度	整个知识池是否活跃？	引用分布的 Gini 系数

判定与阈值

信号	健康	警告	严重
速度趋势	复利增长（斜率 > +0.01）	停滞	衰退（斜率 < -0.01）
引用管道	持续增强（高利用率 >60%）	惰性（30-60%）	恶化（<30%）
研究闭环	持续挖掘（孤立项 <=10%）	—	囤积（孤立项 >=10%）
复用集中度	分布广泛（Gini<0.4，活跃度>30%）	集中	休眠（Gini>0.7 或活跃度<10%）

总体判定： 3 项及以上健康 = 复利增长，3 项及以上严重 = 衰退，混合 = 累积。

建议操作

判断	操作
decaying	运行 /compile 周期，归档过时产物，通过 ao lookup 增加引用
accumulating	检查孤立研究（/research→/post-mortem --quick 流程），提升 /curate --mode=forge 的采集质量
compounding	保持节奏。考虑采集基线（ao metrics baseline），以跟踪趋势

缓存驱逐

阅读 references/cache-eviction.md，了解完整的驱逐流程（被动跟踪 → 置信度衰减 → 成熟度扫描 → 归档）。

Hub 预算与 Phase 4 加固

Phase 4（soc-ytpq）对 ~/.agents/learnings/ 的治理——全部为建议项，默认均不会阻止操作。详情请参阅 references/hub-budget.md。

• 大小预算： 目标 ≤ 250 MB / ≤ 5,000 个文件。通过 ao maturity --evict --target-size=250M 恢复（优先处理效用最低的文件；遵循 lifecycle.IsEvictionEligible，因此规范文件 / 高置信度文件会受到保护）。
• 数量门槛： 当提升数量超过 --max-promotions=N（默认 500；AO_MAX_PROMOTIONS=N 环境变量为后备设置；≤0 时禁用）时，ao harvest 会发出 WARN。仅警告——2,638 项提升的 soc-ujls 清理表明，硬性门槛会错误地阻止合法运行。
• 来源： 每个已提升文件的 frontmatter 中都包含 source_rig:（写入值为空时会序列化为 source_rig: unknown）。harvest.Promote 和 pool.(*Pool).Promote 都会基于同一个 hub 执行内容去重，索引文件为 ~/.agents/pool/promoted-index.jsonl。
• 再次膨胀排查： 检查 SkipGlobalHub 是否默认为 true（agentops-b3v / soc-ujls 修复），然后运行 grep -h '^source_rig:' ~/.agents/learnings/*.md | sort | uniq -c | sort -rn，找出回归的写入方。使用 --target-size，切勿直接运行 rm。

关键规则

• 定期监控 - 飞轮需要关注；及早解决瓶颈
• 为飞轮提供输入 - 运行 /post-mortem（或 /post-mortem --quick）
• 清理过时知识 - 归档旧产物

示例

用户说： /flywheel — 统计知识池深度，检查近期活动，验证产物一致性，并将健康报告写入 .agents/flywheel-status.md。 钩子触发： /post-mortem 之后 — 比较当前与历史指标，标记速度下降和摩擦点。

故障排查

问题	原因	解决方案
所有知识池计数均为零	.agents/ 目录缺失或为空	运行 /post-mortem（或 --quick）以初始化知识池
速度始终为零	近期没有提取操作（过去 7 天）	运行 /post-mortem（或 --quick）以提取并索引经验
“ao CLI not available”	未安装 ao 命令，或它不在 PATH 中	安装 ao CLI，或使用手动统计知识池的后备方案
过时产物占比 >50%	距上次会话已久，或代码库处于非活动状态	运行 /provenance --stale，审核并归档旧产物

参考文档

• references/artifact-consistency.md
• references/promotion-tiers.md
• references/hub-budget.md
• references/cache-eviction.md
• references/flywheel-cli.feature — 可执行规范：ao flywheel CLI 命令行为，关联到 cmd 测试（soc-jnfgi）