session-chronicle

Session Chronicle

挖掘 Claude Code 会话日志，为研究发现、ADR 决策和代码贡献记录完整溯源信息。追踪跨多个自动压缩会话的 UUID 链。

关键原则：注册表条目必须自包含。提交时记录所有会话 UUID（主会话 + 子 Agent）。未来的维护者不应需要考古才能了解溯源信息。

S3 工件共享：工件可以上传到 S3，供团队访问。参见 S3 共享 ADR。

自我演进的技能：此技能会在使用中不断改进。如果说明有误、参数发生漂移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实且可复现的问题进行更新。

何时使用此技能

• 用户询问“是谁创建的？”或“这个是从哪里来的？”
• 用户要求“记录此发现”，并提供完整的会话上下文
• ADR 或研究发现需要追踪溯源信息
• Git 提交需要引用会话 UUID
• 追踪跨自动压缩会话的编辑
• 为研究会话创建注册表条目

---

文件归属模型

目录	是否提交？	用途
findings/registry.jsonl	是	主索引（小型、仅追加的 NDJSON）
findings/sessions/<id>/iterations.jsonl	是	迭代记录（小型、仅追加）
outputs/research_sessions/<id>/	否	研究工件（体积较大，由 git 忽略）
tmp/	否	上传到 S3 前的临时归档
S3 example-findings-bucket/sessions/<id>/	不适用	永久的团队共享归档

核心原则：仅提交 findings/。研究工件放在由 git 忽略的 outputs/ 和 S3 中。

---

第 0 部分：预检

验证会话存储，查找项目会话，并检查所需工具（jq、brotli、aws、op）。

完整脚本：预检脚本

步骤摘要：

1. 验证会话存储 - 确认 ~/.claude/projects/ 存在
2. 查找当前项目会话 - 编码 CWD 路径，枚举主会话和子 Agent 的 .jsonl 文件
3. 验证所需工具 - 检查是否已安装 jq、brotli、aws、op

Step 4（在分享任何 S3 内容前必须执行）：清理

原始 Claude Code 会话 JSONL 文件分享起来很危险。 其中通常包含真实凭据（AWS 密钥、GitHub PAT、Telegram 机器人令牌、Tailscale API 密钥、1Password 服务令牌）、内部主机名、Tailscale CGNAT IP 地址、电子邮件地址，以及其他基础设施机密。这些信息会通过屏幕截图、环境变量转储和 shell 命令泄漏到提示词中。

在压缩并上传到 S3 之前，运行清理工具：

SKILL_DIR="$(find $HOME/.claude/plugins/marketplaces/cc-skills -type d -name session-chronicle | head -1)"
"$SKILL_DIR/scripts/sanitize_sessions.py" \
  --input  /path/to/raw/claude-sessions-export-raw \
  --output /path/to/sanitized/claude-sessions-export \
  --report /path/to/redaction_report.txt

该清理工具具备字段感知能力（不会破坏 UUID、工具调用 ID 或外汇小数——v1 的电话正则表达式误报率高达 92%，会破坏结构标识符），并覆盖以下内容：

• AWS / GitHub / OpenAI / Anthropic / Slack / Stripe / Google / JWT / Bearer / Authorization
• Tailscale API 密钥（tskey-*）、CGNAT IP 地址（100.64–127.x.x）、tailnet DNS（*.ts.net）、tailnet 名称
• 1Password 服务令牌（ops_*）、op:// URL，以及 op CLI 上下文之后的 32 位字符条目 ID
• Cloudflare API 令牌、Global API Key 和 CF_AppSession
• Doppler（dp.*）、Docker PAT（dckr_pat_*）、npm（npm_*）、Supabase（sbp_*）、SendGrid（SG.*）
• Telegram 机器人令牌（<bot_id>:<secret> 格式）——可检测粘贴到环境变量转储中的令牌
• 包含嵌入式凭据的 ClickHouse URL
• .internal 主机名、172.25.x.x 私有地址范围
• PEM 私钥块（OPENSSH / RSA / EC / DSA / PGP / ED25519）
• JSON/YAML/env 格式中的通用 password=、api_key=、secret= 声明
• 电子邮件地址
• 电话号码——仅在包含分隔符时检测（避免破坏 UUID/小数）

输出：一份列出各模式匹配数量的脱敏报告。打包前请检查报告，确认没有重要内容被误删（完整性检查：UUID 应保持完整）。

S3 上传顺序：始终按原始文件 → 清理 → 压缩 → S3 → 预签名 URL 的顺序操作。切勿直接上传 -raw/。

---

Part 1：AskUserQuestion 流程

Flow A：识别来源追溯目标

触发该技能时，首先确认用户想追溯什么：

AskUserQuestion:
  question: "What do you want to trace provenance for?"
  header: "Target"
  multiSelect: false
  options:
    - label: "Research finding/session"
      description: "Document a research session with full session context for reproducibility"
    - label: "Specific code/feature"
      description: "Trace who created a specific function, feature, or code block"
    - label: "Configuration/decision"
      description: "Trace when and why a configuration or architectural decision was made"
    - label: "Custom search"
      description: "Search session logs for specific keywords or patterns"

Flow B：确认 GitHub 归属信息

重要： 每个注册表条目都必须注明 GitHub 用户名。

AskUserQuestion:
  question: "Who should be attributed as the creator?"
  header: "Attribution"
  multiSelect: false
  options:
    - label: "Use git config user (Recommended)"
      description: "Attribute to $(git config user.name) / $(git config user.email)"
    - label: "Specify GitHub username"
      description: "I'll provide the GitHub username manually"
    - label: "Team attribution"
      description: "Multiple contributors - list all GitHub usernames"

Flow C：确认会话范围

重要： 默认包含所有会话。注册表必须完整自包含。

AskUserQuestion:
  question: "Which sessions should be recorded in the registry?"
  header: "Sessions"
  multiSelect: false
  options:
    - label: "ALL sessions (main + subagent) (Recommended)"
      description: "Record every session file - complete provenance for future maintainers"
    - label: "Main sessions only"
      description: "Exclude agent-* subagent sessions (loses context)"
    - label: "Manual selection"
      description: "I'll specify which sessions to include"

重要： 始终默认记录所有会话。子 Agent 会话（agent-*）包含来自 Explore、Plan 和专用 Agent 的关键上下文。省略这些会话会迫使后续维护者重新进行考古分析。

Flow D：预览会话上下文数组

写入之前，向用户展示完整的 session_contexts 数组，然后进行确认：

AskUserQuestion:
  question: "Review the session_contexts array that will be recorded:"
  header: "Review"
  multiSelect: false
  options:
    - label: "Looks correct - proceed"
      description: "Write this to the registry"
    - label: "Add descriptions"
      description: "Let me add descriptions to some sessions"
    - label: "Filter some sessions"
      description: "Remove sessions that aren't relevant"
    - label: "Cancel"
      description: "Don't write to registry yet"

Flow E：选择输出格式

AskUserQuestion:
  question: "What outputs should be generated?"
  header: "Outputs"
  multiSelect: true
  options:
    - label: "registry.jsonl entry (Recommended)"
      description: "Master index entry with ALL session UUIDs and GitHub attribution"
    - label: "iterations.jsonl entries"
      description: "Detailed iteration records in sessions/<id>/"
    - label: "Full session chain archive (.jsonl.br)"
      description: "Compress sessions with Brotli for archival"
    - label: "Markdown finding document"
      description: "findings/<name>.md with embedded provenance table"
    - label: "Git commit with provenance"
      description: "Structured commit message with session references"
    - label: "Upload to S3 for team sharing"
      description: "Upload artifacts to S3 with retrieval command in commit"

Flow F：关联现有 ADR

AskUserQuestion:
  question: "Link this to an existing ADR or design spec?"
  header: "ADR Link"
  multiSelect: false
  options:
    - label: "No ADR link"
      description: "This is standalone or ADR doesn't exist yet"
    - label: "Specify ADR slug"
      description: "Link to an existing ADR (e.g., 2025-12-15-feature-name)"
    - label: "Create new ADR"
      description: "This finding warrants a new ADR"

---

Part 2：会话考古流程

扫描所有会话文件，构建 session_contexts 数组，并可选择追溯 UUID 链。

完整脚本：考古脚本

步骤摘要：

1. 完整项目扫描 - 枚举所有主会话和子 Agent 会话，并记录行数和时间戳
2. 构建 session_contexts 数组 - 创建包含所有会话的数组（session_uuid、type、entries、description）
3. 追溯 UUID 链（可选）- 跨会话跟踪父 UUID 引用，以详细追溯来源

---

Part 3：注册表架构

两个 NDJSON 文件用于追踪来源：

• findings/registry.jsonl - 主索引，每行包含一个完整独立的 JSON 对象
• findings/sessions/<id>/iterations.jsonl - 按会话追踪迭代级别的信息

完整架构、示例和字段说明：注册表架构参考

必填字段（registry.jsonl）

字段	格式
id	YYYY-MM-DD-slug
type	research_session / finding / decision
created_at	ISO8601 时间戳
created_by.github_username	必填 GitHub 用户名
session_contexts	必填 包含所有会话 UUID 的数组

---

第 4 部分：输出生成

使用 Brotli 压缩归档会话，并采用包含来源信息的结构化 git 提交消息。

完整脚本和模板：输出生成

摘要：

• 压缩 - 使用 Brotli-9 压缩每个会话至 outputs/research_sessions/<id>/*.jsonl.br（已被 git 忽略）
• 清单 - 自动生成包含 target_id、count、timestamp 的 manifest.json
• 提交消息 - 模板包含 registry_id、归属信息、会话数量和 S3 检索命令

---

第 5 部分：确认工作流

写入前的最终确认

务必在追加前向用户展示将要写入的内容：

AskUserQuestion:
  question: "Ready to write to registry. Confirm the entry:"
  header: "Confirm"
  multiSelect: false
  options:
    - label: "Write to registry"
      description: "Append this entry to findings/registry.jsonl"
    - label: "Edit first"
      description: "Let me modify some fields before writing"
    - label: "Cancel"
      description: "Don't write anything"

在提出此问题前，请显示：

1. 完整的 JSON 条目（格式化输出）
2. session_contexts 条目的数量
3. GitHub 用户名归属信息
4. 目标文件路径

写入后验证

写入后，请验证：

# Validate NDJSON format
tail -1 findings/registry.jsonl | jq . > /dev/null && echo "Valid JSON"

# Show what was written
echo "Entry added:"
tail -1 findings/registry.jsonl | jq '.id, .created_by.github_username, (.session_contexts | length)'

---

第 6 部分：工作流摘要

1. PREFLIGHT
   ├── Verify session storage location
   ├── Find ALL sessions (main + subagent)
   └── Check required tools (jq, brotli)

2. ASK: TARGET TYPE
   └── AskUserQuestion: What to trace?

3. ASK: GITHUB ATTRIBUTION
   └── AskUserQuestion: Who created this?

4. ASK: SESSION SCOPE
   └── AskUserQuestion: Which sessions? (Default: ALL)

5. BUILD session_contexts ARRAY
   ├── Enumerate ALL main sessions
   ├── Enumerate ALL subagent sessions
   └── Collect metadata (entries, timestamps)

6. ASK: PREVIEW session_contexts
   └── AskUserQuestion: Review before writing

7. ASK: OUTPUT FORMAT
   └── AskUserQuestion: What to generate?

8. ASK: ADR LINK
   └── AskUserQuestion: Link to ADR?

9. GENERATE OUTPUTS
   ├── Build registry.jsonl entry (with iterations_path, iterations_count)
   ├── Build iterations.jsonl entries (if applicable)
   └── Prepare commit message

10. ASK: FINAL CONFIRMATION
    └── AskUserQuestion: Ready to write?

11. WRITE & VERIFY
    ├── Append to registry.jsonl
    ├── Append to sessions/<id>/iterations.jsonl
    └── Validate NDJSON format

12. SANITIZE (MANDATORY before any S3 share)
    ├── Run scripts/sanitize_sessions.py on the staging directory
    ├── Review redaction_report.txt (verify no structural destruction)
    └── Produce sanitized/ directory for downstream packaging

13. (OPTIONAL) S3 UPLOAD
    ├── Package sanitized/ directory (zip or brotli per-file)
    └── Upload compressed archives, generate presigned URL if sharing externally

---

成功标准

1. 会话枚举完整 - 记录所有主会话和子 Agent 会话
2. GitHub 归属信息 - 始终包含 created_by.github_username
3. 自包含的注册表 - 后续维护者无需追溯历史
4. 用户确认 - 每个步骤都通过 AskUserQuestion 确认
5. 有效的 NDJSON - 所有条目均通过 jq 验证
6. 可复现 - 会话 UUID 支持完整上下文检索

---

参考资料

• S3 共享 ADR
• S3 检索指南
• 注册表架构参考
• 预检脚本
• 历史追溯脚本
• 输出生成
• NDJSON 规范
• jq 手册
• Brotli 压缩

---

故障排除

问题	原因	解决方案
未找到会话存储	Claude Code 尚未初始化	先启动 Claude Code 会话
项目中没有会话	路径编码错误	检查编码后的路径是否与 ~/.claude/projects/ 匹配
jq 解析错误	JSONL 格式错误	使用 jq -c . 逐行验证
未找到 brotli	缺少依赖	使用 brew install brotli 安装
S3 上传失败	缺少 AWS 凭据	配置 AWS CLI 或使用 1Password 注入
UUID 链中断	会话已压缩	检查相关会话是否存在续接记录
缺少 GitHub 用户名	未设置归属信息	注册表条目中始终要求提供 github_username
注册表条目无效	缺少必填字段	确认 id、type、created_at、session_contexts 均存在

执行后反思

此技能执行完毕后，关闭前请检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生偏移，请更新 Usage 示例和 Parameters 表以保持一致。
3. 是否需要变通方案？ — 如果你不得不临时调整（更换标志、增加步骤），请更新此 SKILL.md，以便下次调用时无需采用相同的变通方案。

只有问题确实存在且可复现时才进行更新，不要基于猜测更新。