provenance

来源追溯技能

追溯知识产物的来源链路。

执行步骤

收到 /provenance <artifact> 时：

步骤 1：读取产物

Tool: Read
Parameters:
  file_path: <artifact-path>

查找来源追溯元数据：

• 来源引用
• 会话 ID
• 日期
• 相关产物

步骤 2：追溯来源链

# Check for source metadata in the file
grep -i "source\|session\|from\|extracted" <artifact-path>

# Search for related transcripts using ao
ao search "<artifact-name>" 2>/dev/null

步骤 3：使用 CASS 搜索会话记录

使用 CASS 查找讨论该产物的时间：

# Extract artifact name for search
artifact_name=$(basename "<artifact-path>" .md)

# Search session transcripts
cass search "$artifact_name" --json --limit 5

解析 CASS 结果以查找：

• 创建或讨论该产物的会话
• 引用时间线
• 按工作区划分的相关会话

CASS JSON 输出字段：

{
  "hits": [{
    "title": "...",
    "source_path": "/path/to/session.jsonl",
    "created_at": 1766076237333,
    "score": 18.5,
    "agent": "claude_code"
  }]
}

步骤 4：构建来源链

Transcript (source of truth)
    ↓
Forge extraction (candidate)
    ↓
Human review (promotion)
    ↓
Pattern recognition (tier-up)
    ↓
Skill creation (automation)

步骤 5：撰写来源追溯报告

# Provenance: <artifact-name>

## Current State
- **Tier:** <0-3>
- **Created:** <date>
- **Citations:** <count>

## Source Chain
1. **Origin:** <transcript or session>
   - Line/context: <where extracted>
   - Extracted: <date>

2. **Promoted:** <tier change>
   - Reason: <why promoted>
   - Date: <when>

## Session References (from CASS)
| Date | Session | Agent | Score |
|------|---------|-------|-------|
| <date> | <session-id> | <agent> | <score> |

## Related Artifacts
- <related artifact 1>
- <related artifact 2>

步骤 6：向用户报告

告知用户：

1. 产物来源链
2. 原始来源
3. 晋升历史
4. 会话引用（来自 CASS）
5. 相关产物

查找孤立产物

/provenance --orphans

查找没有来源追踪信息的产物：

# Files without "Source:" or "Session:" metadata
for f in .agents/learnings/*.md; do
  grep -L "Source\|Session" "$f" 2>/dev/null
done

查找过时产物

/provenance --stale

查找来源可能已变更的产物：

# Artifacts older than their sources
find .agents/ -name "*.md" -mtime +30 2>/dev/null

关键规则

• 每条洞见都有来源——追溯来源
• 追踪晋升——了解层级变更的原因
• 查找孤立产物——清理未追踪的知识
• 维护来源链——来源追溯有助于建立信任
• 使用 CASS——查找讨论产物的时间

示例

追溯产物来源链

用户说： /provenance .agents/learnings/2026-01-15-auth-tokens.md

执行过程：

1. Agent 读取产物并提取来源元数据（会话 ID、日期、引用）
2. Agent 使用 cass search "auth-tokens" --json --limit 5 搜索会话记录
3. Agent 解析 CASS 结果，查找来源会话和时间线
4. Agent 追溯从 forge → learnings → patterns 的晋升历史
5. Agent 构建来源链并将报告写入 Markdown 文件
6. Agent 报告产物层级、引用和相关产物

结果： 提供从会话记录到当前层级的完整来源链，展示产物的创建、讨论和晋升时间。

查找孤立产物

用户说： /provenance --orphans

执行过程：

1. Agent 扫描 .agents/learnings/、.agents/patterns/ 中缺少来源元数据的文件
2. Agent 使用 grep 搜索每个文件中的 "Source:" 或 "Session:" 字段
3. Agent 列出没有来源追踪信息的文件
4. Agent 报告孤立产物数量，并建议添加来源引用

结果： 找出未追踪的知识，以便补充记录历史来源链或归档。

故障排除

问题	原因	解决方案
未找到来源元数据	产物创建于来源追踪机制启用之前	使用 CASS 追溯查找来源会话；手动添加 Source 字段
CASS 未返回结果	会话未编入索引或产物名称不匹配	检查会话记录是否存在；尝试使用更宽泛的搜索词
过时产物检查失败	find 命令不可用或权限错误	使用 `ls -lt .agents/
来源链不完整	产物元数据中未记录晋升信息	根据 git 历史或会话记录重建；记录缺失信息