ParkingRobot/docs/superpowers/specs/2026-08-03-daily-summary-job-skill-design.md

Daily Summary Job 个人技能设计

目标

创建个人技能 daily-summary-job，在用户按需要求记录进展、生成今日日报或更新今日日报时，整理当前开发工作的成果、问题发现、改善措施、验证状态和下一步，并生成事实一致的 Markdown 主报告与单文件交互式 HTML。

技能面向任意本地项目。项目缺少日报目录、模块目录或日期目录时，技能只初始化报告归档结构，不创建或修改业务代码目录。

名称与安装范围

• 规范技能名：daily-summary-job。
• 界面显示名：Daily Summary Job。
• 安装范围：个人技能目录 $CODEX_HOME/skills/daily-summary-job；CODEX_HOME 未设置时使用 ~/.codex/skills/daily-summary-job。
• dailySummary_job 只作为用户原始名称保留在说明中，不作为目录名或 YAML 名称。

按需触发

技能不后台运行，也不自动监听 Agent。以下是意图示例，不是固定口令：

• “记录当前进展”“把刚才的问题加入今日记录”进入检查点模式。
• “生成今日日报”“汇总今天的开发工作”进入生成模式。
• “更新今天的日报”“把刚解决的问题补充进去”进入更新模式。
• 显式使用 $daily-summary-job 时最可靠；自然语言明确表达日报、今日问题整理或进展记录意图时也应触发。

工作流

当前对话与 Agent 汇报 ─┐
Git 提交、改动与文档 ──┼─→ 结构化事实源 ─→ Markdown 主报告
已有测试与构建结果 ────┘                  └→ 交互式 HTML

1. 确定项目根目录和项目机器的本地日期；用户可以覆盖日期。
2. 从当前对话、主 Agent 与子 Agent 汇报中提取成果、问题、调查结论、改善和遗留事项。
3. 用当天 Git 提交、未提交改动、设计/计划文档以及已有测试结果交叉核对。
4. 将信息压缩为结构化事实源，并根据稳定问题标识去重。
5. 自动识别单模块、多模块或无法分类的工作范围。
6. 初始化缺失的报告、模块和日期目录。
7. 由同一结构化事实源生成 Markdown 与 HTML，避免两者事实漂移。
8. 更新模式合并新证据并重新生成原有文件对，不重复创建相同主题。

默认不重新运行耗时构建或测试。已有证据不足时标记“待验证”；完全没有有效开发证据时不生成空日报。

上下文预算

技能采用渐进式读取：

• SKILL.md 只保留核心流程和路由规则。
• 先读取当天检查点索引，再加载相关模块的必要记录。
• 不读取历史日期的日报，除非用户明确要求比较。
• 检查点不复制完整对话或完整日志，只保存结论和证据引用。
• 每次检查点最多记录 5 条成果、5 个问题和 3 个下一步；单条说明尽量不超过 120 个汉字。
• 长日志只记录命令、文件路径、提交号、结果摘要和原始证据位置。

磁盘上的历史文件不会自动进入上下文；只有本次任务选中的文件才会读取。

证据模型

每条问题至少包含：

• 稳定标识、标题和所属模块；
• 问题如何被发现、实际现象和正确预期；
• 原因或当前假设、影响范围；
• 已采取的改善、验证结果和下一步；
• 证据引用与证据等级。

证据等级固定为：

等级	含义
已验证	有测试、构建、运行输出或可复核改动支持。
静态分析	可从当前代码和控制流确认，但尚无运行复现。
对话发现	Agent 或用户在讨论中提出，尚未完成独立核验。
待验证风险	合理推断，仍需要专门实验或回归。

多个 Agent 给出冲突结论时，不擅自合并为单一事实。结构化事实源保留冲突双方、各自证据和待验证动作，报告明确显示“结论冲突”。

自动分类与目录初始化

项目根目录优先使用 Git 根；没有 Git 时使用当前工作目录。分类顺序如下：

1. 用户明确指定的模块。
2. 当天改动路径与既有 dailywork_report/*_rep 的匹配结果。
3. 代码、测试和文档中占主导的业务目录。
4. 涉及多个独立模块时使用 cross-module_rep。
5. 无法可靠判断或项目没有代码目录时使用 general_rep。

既有项目命名优先，例如已有 pathsmoothing_rep 时不另建语义重复目录。新模块名只允许安全的小写字母、数字和连字符，再追加 _rep。

dailywork_report/
├── .daily-summary-job/
│   └── YYYY-MM-DD/
│       └── checkpoints/
│           └── HHmmss-<module>.json
└── <module>_rep/
    └── YYYY-MM-DD/
        ├── NN-<topic>-daily-summary-report.md
        └── NN-<topic>-daily-summary-visualization.html

• 同日同主题更新原文件对。
• 同日新主题从 01 开始递增编号。
• 检查点目录保存精简、机器可读的中间证据；最终日报目录只保留交付文件。
• 所有目录均按需创建；技能不创建任何业务源码目录。

Markdown 报告

Markdown 使用固定主结构，但允许没有内容的非关键小节省略：

1. 今日结论摘要。
2. 今日完成的工作。
3. 今日发现的问题。
4. 问题如何被发现及证据等级。
5. 已采取的改善和验证结果。
6. 尚未解决的风险与下一步。
7. 变更、测试和资料证据索引。

问题描述采用“发现 → 现象 → 原因/假设 → 影响 → 改善 → 验证 → 下一步”的顺序。不得把未运行的测试写成通过，也不得把候选方案写成已完成修复。

交互式 HTML

每份 Markdown 对应一个单文件离线 HTML。HTML 内嵌 CSS、结构化数据和原生 JavaScript，不使用 CDN、网络请求、第三方库或外部图片。

页面信息流为：

今日总览
   ↓ 选择问题
现象与正确预期对照
   ↓ 展开因果节点
发现过程 → 证据 → 根因/风险
   ↓ 切换改善步骤
修改前 → 改善措施 → 修改后
   ↓ 查看验证门
测试结果 → 遗留风险 → 下一步

交互组件包括：

• 成果、问题、验证和待办总览；
• 问题选择器与证据等级筛选；
• “实际发生 / 正确预期”对照；
• 可展开的发现与因果链；
• 改善方案步骤导航和修改前后切换；
• 构建、测试、安全约束等验证门漏斗；
• 按优先级和模块筛选的下一步路线图；
• 键盘导航、移动端布局与 prefers-reduced-motion 支持。

没有数值证据时只使用明确标注的概念图，不伪造曲线、比例或指标。HTML 与 Markdown 必须由同一份规范化 JSON 生成。

技能组成

daily-summary-job/
├── SKILL.md
├── agents/openai.yaml
├── scripts/prepare_report.py
├── scripts/test_prepare_report.py
├── references/report-schema.md
└── assets/interactive-report-template.html

• SKILL.md：触发、取证、分类、生成和更新流程。
• agents/openai.yaml：显示名、简短说明和默认提示。
• scripts/prepare_report.py：安全规范化名称、选择输出路径、生成 Markdown/HTML 并执行一致性校验。
• scripts/test_prepare_report.py：使用 Python 标准库验证路径、分类、预算、生成和更新行为。
• references/report-schema.md：结构化事实源字段、证据等级和内容约束。
• assets/interactive-report-template.html：响应式、无外部依赖的交互页面模板。

异常与安全边界

• 目标文件存在且无法确认同一主题时，创建新编号，不覆盖未知内容。
• 更新前校验结构化事实源和目标文件配对关系。
• 生成先写入临时文件并校验，成功后再替换文件对；失败时保留已有有效版本。
• 路径、模块和主题统一安全规范化，拒绝目录穿越。
• HTML 中的所有项目文本进行转义，避免把代码或对话内容解释为页面脚本。
• 技能只整理和生成日报；不修复业务代码、不放宽测试或安全门，也不执行 Git 提交。

验证标准

• 技能目录通过 quick_validate.py。
• 路径脚本覆盖 Git/非 Git、单模块、多模块、无模块、非法名称、同主题更新和连续编号。
• 模拟项目完成一次“记录 → 生成 → 更新”流程。
• Markdown 与 HTML 包含相同问题标识、证据等级、改善和下一步。
• HTML 不包含外部 URL、外部脚本或第三方依赖。
• 交互控件、键盘操作、响应式规则和减少动画规则均存在。
• 全部验证不修改 ParkingRobot 的业务源码，也不暂存或提交任何文件。