decision-history

用途

Decision History 是一个决策历史仪表盘，用于按时间顺序查看 OrchestKit 的架构决策，理解每个决策背后的原因，并追踪最佳实践的采纳情况。它同时追踪 Claude Code 版本的演进（从 2.1.0 到 2.1.16+），帮助使用者回顾决策、理解演进脉络。

主要能力

按时间顺序查看架构决策
追踪 Claude Code 版本演进（2.1.0 → 2.1.16+）
理解每个决策背后的理由（rationale）
为文档生成 Mermaid 时间线图
按类别、CC 版本或日期范围查询决策
提供列表、详情、时间线、统计、搜索等多种视图
支持 ASCII 表格、ASCII 时间线和 Mermaid 时间线三种输出格式

数据来源

决策从多个来源聚合，按优先级顺序为：

来源	位置	说明
Session	`.claude/context/knowledge/decisions/active.json`	最近的会话内决策
CHANGELOG	`CHANGELOG.md`	解析后的版本历史
Coordination	`.claude/coordination/decision-log.json`	多实例决策

使用方式

快速开始：

# 列出最近的决策
node hooks/bin/decision-history.mjs list

# 显示特定 CC 版本的决策
node hooks/bin/decision-history.mjs list --cc-version 2.1.16

# 生成 Mermaid 时间线
node hooks/bin/decision-history.mjs mermaid --output timeline.md

# 按类别筛选
node hooks/bin/decision-history.mjs list --category security

# 显示最近 30 天
node hooks/bin/decision-history.mjs list --days 30

# 查看统计
node hooks/bin/decision-history.mjs stats

# 搜索决策
node hooks/bin/decision-history.mjs search "typescript hooks"

完整 CLI 命令：

# 带筛选条件列出决策
decision-history list [--cc-version VER] [--category CAT] [--days N] [--limit N]

# 显示决策详情
decision-history show <decision-id>

# 显示时间线视图
decision-history timeline [--group-by cc_version|category|month]

# 显示统计
decision-history stats

# 生成 Mermaid 图
decision-history mermaid [--output FILE] [--full] [--group-by FIELD]

# 从所有来源同步（刷新缓存）
decision-history sync

# 搜索决策
decision-history search <query>

输出格式

默认输出为 ASCII 表格，包含日期、CC 版本、摘要和类别列。此外还提供 ASCII 时间线（按版本分组）和 Mermaid 时间线（可用于 GitHub 原生渲染和文档）。

决策数据结构

每个决策包含以下字段：

interface Decision {
  id: string;              // 例如 "4.28.0-architecture-1"
  date: string;            // ISO 日期："2026-01-21"
  summary: string;         // 简要描述
  rationale?: string;      // 完整说明
  ccVersion?: string;      // 例如 "2.1.16"
  pluginVersion?: string;  // 例如 "4.28.0"
  category: string;        // 例如 "architecture"、"security"
  impact: 'high' | 'medium' | 'low';
  status: 'proposed' | 'implemented' | 'deprecated' | 'superseded';
  source: 'changelog' | 'session' | 'coordination' | 'mem0';
  bestPractice?: string;   // 相关最佳实践
  entities?: string[];     // 相关概念
}

实现细节

该技能以 TypeScript 实现，属于 hooks 基础设施的一部分：

文件	用途
`hooks/src/lib/decision-history.ts`	核心模块（解析器、聚合器、格式化器）
`hooks/bin/decision-history.mjs`	CLI 入口点
`hooks/dist/hooks.mjs`	打包模块（通过 esbuild）

关键函数包括：parseChangelog(content) 将 CHANGELOG.md 解析为结构化数据；aggregateDecisions() 合并所有来源并去重；filterDecisions(decisions, options) 应用 CC 版本、类别、日期筛选；formatTable(decisions) 输出 ASCII 表格；formatTimeline(decisions) 输出按版本分组的 ASCII 时间线；formatMermaid(decisions) 生成 Mermaid 图；formatStats(aggregated) 输出统计摘要。

关键设计决策

决策	选择	理由
语言	TypeScript ESM	与 hooks 迁移保持一致，类型安全
CLI 模式	Node.js 脚本	与 hooks 基础设施相同
时间线格式	Mermaid	GitHub 原生、对文档友好
数据聚合	多来源	CHANGELOG + session + coordination
缓存	基于文件	`.claude/feedback/changelog-decisions.json`

适用场景

回顾 OrchestKit 的架构决策及其原因
追踪 Claude Code 版本演进对项目的影响
为文档生成决策时间线图
按类别、版本或时间范围检索历史决策
统计决策分布情况

限制

资料中未提供关于收费、价格、平台支持范围、性能上限或具体使用限制的说明，暂未提供。