timeline-report

timeline-report 技能概览

timeline-report 是做什么的

timeline-report 会把项目里已记录的 claude-mem 历史，整理成一份带叙事感的开发报告。它不是只给你当前代码库的平铺式摘要，而是会重建项目随时间演进的过程：经历了哪些关键阶段、发生过哪些转向、做过哪些决定，以及整体推进节奏的变化。

适合用于报告写作的场景

当你需要的是一份可读的项目历史文档，而不只是原始事件列表时，就适合使用 timeline-report for Report Writing。它尤其适合创始人、维护者、评审者、顾问，或需要向他人清晰说明项目一路如何走到今天的代理与分析者，输出风格偏向连贯的 “Journey Into [Project]” 式项目历程报告。

它真正解决的问题

大多数用户并不是想看一份泛泛的回顾，他们通常真正想回答的是：

• 这个项目的发展可以分成哪几个主要章节？
• 工作是如何一步步演化的？
• 哪些地方发生了变化、停滞，或者明显加速？
• 怎么把时间线数据整理成一份别人真的看得下去的报告？

这正是 timeline-report 比普通提示词更有价值的地方。

timeline-report 的核心差异

timeline-report 最大的区别在于，它围绕 claude-mem 的持久化时间线来工作，而不是只做一次临时的仓库巡检。如果你要的是“历史叙事”，而不是“现在有哪些文件”，这一点就非常关键。它还自带一套确定正确项目名的工作流建议，包括一个很实用的 worktree 检查步骤，帮助你把报告对准父项目，而不是误指到错误目录。

安装前需要具备什么

只有同时满足以下两个条件，这个技能才真正适合安装使用：

• claude-mem worker 正在 localhost:37777 上运行
• 目标项目里已经有记录到 claude-mem 的 observations

如果缺少任一前提，仅靠 timeline-report install 并不能解决问题；因为它几乎没有足够的历史可供分析，最终也很难产出有用内容。

哪些情况下不适合用这个技能

如果你只需要下面这些内容，就不建议用 timeline-report skill：

• 当前架构概览
• 仅基于 Git 生成的 changelog
• 一段话的项目介绍
• 针对没有 claude-mem 历史的项目做报告

这些场景下，直接写提示词，或者改用别的 repo 分析技能，通常会更简单。

如何使用 timeline-report 技能

timeline-report 的安装上下文

从仓库内容来看，这个技能位于 thedotmack/claude-mem 的 plugin/skills/timeline-report 目录下。基础安装方式是：

npx skills add thedotmack/claude-mem --skill timeline-report

安装完成后，先确认环境，再去判断输出质量，不要一上来就怪结果不理想：

1. 确认 claude-mem worker 可通过 localhost:37777 访问
2. 确认目标项目已经记录过 observations
3. 确认你知道该时间线对应的正确项目名

先读这个文件

建议先从这里看起：

• plugin/skills/timeline-report/SKILL.md

这个技能本质上更偏工作流驱动，采用时最大的风险不在隐藏配置，而在于：你是不是把它用在了错误的项目上，或者拿一个空时间线去生成报告。

先弄清楚必需输入

最关键的输入是 claude-mem 中登记的项目名。如果用户只说“这个项目”，技能文档建议可以先用当前目录 basename 作为参考，但前提是先检查自己是否位于 git worktree 里。

这个细节很重要，因为 worktree 的目录名经常和父项目在时间线中的名字并不一致。

正确处理 git worktrees

上游技能里最实用的一点，就是对 worktree 的检查。如果你当前在一个 worktree 中，应该使用父项目的身份，而不是 worktree 文件夹名。项目名一旦用错，报告看起来就可能像“坏掉了一样”——因为它读到的会是稀疏甚至无关的 memory。

如果你拿不准，先解析 git common directory，再从那里推导出父项目身份，之后再请求生成报告。

timeline-report 在实际使用中的请求写法

一个较弱的请求示例：

• "Write a report on this repo"

一个更强的 timeline-report usage 请求：

• "Use timeline-report to generate a Journey Into my-app based on its claude-mem timeline. Focus on major phases, important decisions, pivots, and the overall development arc."

再进一步、更好的请求：

• "Use timeline-report for my-app. Produce an executive-readable report with sections for origin, milestone phases, key decision points, setbacks, and current trajectory. Base it on the full claude-mem timeline rather than the current repo snapshot."

把模糊目标改写成高质量提示词

想要更好的结果，提示词里最好明确这些要素：

• 准确的项目名
• 目标读者
• 期望的报告形态
• 重点关注方向
• 细节深度

示例：

• "Use timeline-report on tokyo. Write a narrative report for stakeholders, not developers. Explain how the project started, what changed over time, where momentum increased or dropped, and what themes define its evolution."

这会明显优于一句 “summarize the project history”，因为它把语气和输出结构都约束清楚了。

让输出更稳定的建议工作流

一个实用工作流如下：

1. 先确认正确的项目名
2. 确认 claude-mem 时间线数据确实存在
3. 以叙事型报告的形式发起请求
4. 检查输出是否过度沉迷于流水账式时间顺序
5. 如果有，就在目标读者、章节结构和重点上给出更清晰的二次指令后重跑

这个技能很适合迭代使用。第一轮先把时间线主线理出来，第二轮再把它修成更像正式报告的成品。

让技能重点突出什么

可以要求它重点强调这些内容：

• 关键里程碑，而不是琐碎事件
• 架构或产品方向的转向
• 朝发布就绪推进的过程
• 调试期或恢复期
• 决策模式中反复出现的规律
• 能解释项目走向的核心主题

如果不给这类引导，时间线报告很容易变得很长，但对判断和决策帮助不大。

如何避免产出泛泛而谈

想让 timeline-report 不要写成乏味的摘要，最好明确要求：

• 写“阶段”，不要只列事件
• 给出因果解释，而不是只有时间点
• 每次重大变化后说明“为什么这件事重要”
• 结尾加上对项目走向的总体判断

这样能把结果从单纯的 memory dump，拉回到真正的报告写作上。

timeline-report 安装与使用中的常见阻碍

最常见的问题基本都出在运行条件，而不是写法风格：

• claude-mem worker 没有运行
• 项目没有 observations
• 项目名填错了
• 把 worktree 名误当成父项目名
• 用户期待的是当前代码分析，而不是历史分析

如果用起来不顺，先排查这些，再考虑重写提示词。

timeline-report 技能 FAQ

timeline-report 比普通提示词更好吗？

如果你的目标是基于 claude-mem 数据做项目历史报告，那么答案是肯定的。普通提示词当然也可以要求“写成叙事风格”，但 timeline-report skill 已经把任务框定在历史开发过程分析，以及 “Journey Into [Project]” 这种典型使用场景上。

timeline-report 对新手友好吗？

整体上算友好，前提是环境已经准备好了。它的使用模式并不复杂，但新手很容易卡在前置条件上：worker 是否在运行、有没有存下 observations、以及是否找对了项目名。

一定要有很长的仓库历史才行吗？

不一定，但如果时间线足够密集、能体现出阶段变化，这个技能的价值会高很多。反过来说，memory 过于稀疏，报告就会显得单薄。

没有 claude-mem 可以用 timeline-report 吗？

不能。这个技能明确依赖 claude-mem 时间线数据，以及运行在 localhost:37777 的 worker。脱离这套生态，它就不是合适的工具。

哪些情况下不该把 timeline-report 用于报告写作？

如果你需要的是下面这些内容，就不要用 timeline-report for Report Writing：

• 当前状态的代码审计
• 安全评审
• API 文档
• 纯粹基于 Git 推导的 changelog
• 从未被 claude-mem 跟踪过的项目分析

timeline-report 也会分析当前代码库吗？

它的核心价值在于历史叙事，而不是完整的 repo 巡检。你当然可以把它和其他分析步骤结合使用，但这个技能本身的重点，是基于 memory observations 还原开发历史。

为什么 timeline-report 输出很弱或者很空泛？

通常是以下原因之一：

• 时间线数据太稀疏
• 目标项目选错了
• 提示词没有说明受众或报告结构
• 用户要求的是宽泛总结，而不是结构化叙事报告

如何改进 timeline-report 技能的使用效果

给 timeline-report 一份明确的报告 brief

提升质量最有效的方法，往往就是把 brief 写得更清楚。告诉 timeline-report：

• 这份报告是给谁看的
• 你要叙事型报告还是 executive summary
• 需要突出哪些主题
• 哪些内容要弱化

示例：

• "Use timeline-report on my-app for an investor-style update. Focus on momentum, milestones, pivots, and evidence of execution."

先提供正确的项目身份

如果报告看起来不完整，先核对项目名，不要急着改别的。尤其在 worktree 场景里，这一个修正带来的提升，往往比怎么微调提示词都更明显。

不要只要摘要，要主动要结构

更强的结构要求，通常能立刻改善可读性。你可以直接要求包含如下章节：

• project origin
• early build phase
• turning points
• consolidation or scaling
• present trajectory

这样更容易让技能产出一份便于浏览、也便于复用的报告。

不要停留在时间顺序本身

一个常见失败模式是：时间线看起来只是按日期排列的笔记。想提升 timeline-report usage，要主动要求解释层：

• "group events into phases"
• "identify the main inflection points"
• "explain what changed after each pivot"
• "highlight recurring themes"

在第一稿之后继续打磨输出

第一轮生成后，不要推倒重来，更适合做一次聚焦型修订请求：

• 要求压缩篇幅
• 要求更偏 executive 读者
• 要求产品决策多于技术细节
• 要求补上一段对项目方向的最终判断

这种方式很有效，因为历史基础不变，你只是在不断优化编辑框架和呈现方式。

让技能服务于正确的结果

当你需要的是故事感、发展弧线和演进背景时，才适合使用 timeline-report skill。如果你真正需要的是技术文档、依赖分析，或者 repo onboarding，那就应该尽早换工具。判断“是否匹配”本身，就是提升结果最快的方法之一。