189 lines
8.6 KiB
Markdown
189 lines
8.6 KiB
Markdown
# 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 的业务源码，也不暂存或提交任何文件。
|