work-timeline-planner

工作时间线规划器

将 Git 历史记录、项目文档、用户描述和聊天记录等证据整理为易读的时间线报告。输出可以是 Markdown、独立 HTML，或两者兼有。

此技能适用于两种主要情况：

• 回顾：回顾过去某段时间内完成的工作，范围可以是一个或多个项目
• 前瞻规划：规划接下来应该做什么、何时做以及按什么顺序进行

技能目录结构

<installed-skill-dir>/
├── SKILL.md
├── references/
│   ├── evidence-model.md
│   ├── output-formats.md
│   └── report-modes.md
└── templates/
    ├── timeline-report.html
    └── timeline-report.md

渐进式加载

• 始终阅读 references/evidence-model.md
• 在个人回顾、导师报告、规划报告或混合报告之间进行选择时，阅读 references/report-modes.md
• 在 Markdown、HTML 或两者之间进行选择，或在 Mermaid、Frappe Gantt 和 Plotly 之间进行选择时，阅读 references/output-formats.md
• 使用 templates/timeline-report.md 和 templates/timeline-report.html 作为输出骨架

核心原则

• 时间线区块应有证据支撑，而不只是依据提交数量
• 提交只是信号，并非全貌；应结合文档、笔记和用户背景信息
• 优先采用少量有意义的工作区块，而不是嘈杂的逐提交图表
• 区分观察到的事实和推断出的日期范围
• 考虑受众：个人多项目回顾范围更广；面向导师的单项目报告则应更精炼、说明更充分
• 对于规划，应将已确定的工作与可选工作或挑战性工作分开
• 选择最轻量、同时又适合用户需求的图表技术

步骤 1 — 对请求进行分类

在收集证据前，先确定主要模式：

• personal-review：回顾过去的工作，通常涉及多个项目
• mentor-report：为一个项目和一类受众总结过去的工作
• next-phase-plan：规划后续工作，包括里程碑和依赖关系
• hybrid：总结近期工作，然后提出下一阶段计划

还需确定：

• 时间范围
• 项目范围
• 受众
• 所需的细节程度
• 输出格式：markdown、html 或 both
• 图表引擎：mermaid、frappe-gantt 或 plotly

如果用户未指定时间范围，请根据上下文推断一个合理范围，并在报告中明确说明。

默认输出策略：

• markdown + mermaid：适用于便于分享且原生于代码仓库的报告
• html + frappe-gantt：适用于更丰富的交互式回顾
• both：适用于用户既需要可存档的报告，又需要更好的本地可视化

步骤 2 — 收集证据

优先收集一手证据。

对于每个纳入范围的代码仓库，收集：

git rev-parse --show-toplevel
git log --date=short --stat --reverse --since="<start-date>" --until="<end-date>"
git log --date=short --pretty=format:"%ad%x09%h%x09%s" --since="<start-date>" --until="<end-date>"

然后补充以下资料：

• 项目文档，例如 README.md、docs/、PROJECT.md、决策日志、实验日志或进展笔记
• 用户提供的笔记或描述
• 用户提供的聊天摘录或会议记录

如果用户需要多项目回顾，请按项目收集证据，并明确划分项目边界。

如果缺少一个或多个代码仓库或笔记，只询问避免臆造时间线所必需的最少补充信息。

步骤 3 — 构建工作区块

将原始证据整理为少量工作区块。

每个区块应包含：

• 项目
• 标题
• 日期范围
• 类型：实现、实验、调试、写作、基础设施、规划、报告或审查
• 证据依据
• 简短成果说明

除非用户明确需要这种细节程度，否则不要将一次提交对应为一个甘特图任务。

应当：

• 将相关提交合并为一个连贯的区块
• 在目标明显发生变化时拆分区块
• 当工作已经开展但提交稀少时，使用文档或笔记说明相关时期的情况

如果日期范围是推断而非明确给出的，应在文字摘要中说明。

第 4 步 — 选择报告形式

请遵循 references/report-modes.md 中的指导。

默认情况下：

• 对于 personal-review，按项目分组，再按工作流分组
• 对于 mentor-report，按项目阶段或交付物分组，而不是按每个技术分支分组
• 对于 next-phase-plan，按里程碑和依赖关系分组

最终输出通常应包含：

• 简短的范围摘要
• 证据说明
• 图表或时间线可视化
• 对关键工作块的简洁叙述性总结
• 可选的下一阶段行动

第 5 步 — 撰写输出报告

请遵循 references/output-formats.md。

对于 Markdown 输出，请使用 templates/timeline-report.md 作为基础结构。

对于 HTML 输出，请使用 templates/timeline-report.html 作为基础结构。

通常应按如下方式选择图表引擎：

• mermaid：轻量级 Markdown 报告的默认选择，适用于保存在代码库中或在聊天中分享的报告
• frappe-gantt：独立 HTML 的默认选择，适用于用户希望在本地通过更好的 UI 查看报告的情况
• plotly：仅在已有干净的结构化任务数据，且需要交互式时间线时使用，尤其适用于由 Python 驱动的工作流

对于 Markdown，默认使用 Mermaid 甘特图：

```mermaid
gantt
    title Example
    dateFormat  YYYY-MM-DD
    section Project A
    Baseline experiments :done, a1, 2026-04-01, 5d
    Model fixes          :done, a2, after a1, 4d
    Next ablation        :active, a3, 2026-04-12, 6d

指南：

• 每个项目或里程碑组使用一个章节
• 任务名称应简短
• 优先采用清晰易读的工作块，而不是精确却杂乱的细节
• 适用时，使用 done 标记已完成的回顾性工作
• 仅在时间安排有依据时，使用 active 或普通未来任务标记当前或计划中的工作
• 对于 HTML 输出，优先使用一个自包含文件，而不是由多个文件组成的小型应用，除非用户明确需要更大的产物

第 6 步 — 按需添加规划内容

如果用户需要前瞻性规划：

1. 将已完成的工作与计划中的工作分开
2. 确定依赖关系和阻碍因素
3. 提出以里程碑为单位的工作块，不要编造看似精确的逐日安排
4. 明确标注不确定性

规划内容应包括：

• 优先级
• 依赖关系
• 预期成果
• 负责人（如相关）

第 7 步 — 最终定稿前进行合理性检查

提交报告前，请检查：

• 所有主要工作块都有实际证据支持
• 明确说明时间范围
• 多项目报告不会混淆项目归属
• 面向导师的报告说明了成果，而不仅仅是活动
• 计划中的工作没有与已完成的工作混在一起
• 所选图表语法或嵌入数据在结构上有效

输出要求

最终输出通常应是一份用户可以留存或分享的文档。

如果用户要求将其保存到代码库中，请使用符合用户目的的路径，例如：

• docs/reports/work_timeline_YYYY_MM.md
• docs/reports/mentor_update_YYYY_MM.md
• docs/plans/next_phase_timeline.md
• docs/reports/work_timeline_YYYY_MM.html
• docs/reports/mentor_update_YYYY_MM.html

如果用户只需要聊天中的草稿，也应将其组织成可以直接保存为文件的形式。