# 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` 时最可靠；自然语言明确表达日报、今日问题整理或进展记录意图时也应触发。

## 工作流

```text
当前对话与 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`。

```text
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、网络请求、第三方库或外部图片。

页面信息流为：

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

交互组件包括：

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

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

## 技能组成

```text
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 的业务源码，也不暂存或提交任何文件。