Agent Worklog

1. 目标

帮助 Agent 以简洁、可核验、可持续更新的方式记录工作过程，使用户能够回顾任务进度，也使后续 Agent 或新会话能够根据日志继续工作。

日志记录的是可复核的工作事实、决策依据摘要和执行结果，不是冗长的思维过程。不要输出或记录隐藏的逐步推理。

2. 何时使用

在以下场景中使用本 Skill：

用户明确要求记录工作日志、进展或任务交接。
任务涉及多个步骤、多个文件、反复调试或需要后续继续。
完成了一项重要阶段，需要保留修改内容、验证结果或未解决问题。
用户要求继续之前的工作，需要先恢复上下文。

对于一次性、简单且无需后续跟进的问题，不要为了写日志而额外创建文件。

3. 确定日志位置

按以下优先级决定保存位置：

如果用户明确指定了日志文件或目录，使用用户指定的位置。
如果项目中已有明确的工作日志规范或日志文件，优先沿用，不另建重复体系。
如果没有现成约定，默认在当前项目根目录下创建 .agent-worklog/，并为每项多步骤任务建立一个日志文件，文件名采用 YYYY-MM-DD-任务简述.md；同时维护该目录下的 INDEX.md，列出日志文件、任务名称和当前状态。
如果无法确认项目根目录、没有文件写入权限，或当前环境不支持文件操作，不要声称日志已保存；应在回复中提供可复制的日志内容，或向用户询问保存位置。

不要擅自将日志写入项目之外的敏感目录。除非用户要求，不要自动提交、推送或发布日志文件。

4. 执行流程

第一步：确认任务目标

开始记录时，简要整理：

任务要解决什么问题。
用户明确提出的约束与完成标准。
当前已知的环境、分支或相关文件（仅记录已确认的信息）。

信息不足时，不要自行编造；将未知项标为“待确认”。

第二步：记录关键进展

在任务启动、重要阶段完成、关键决策形成、遇到阻塞以及任务结束或交接时更新日志。每条记录应说明：

做了什么。
为什么这样做（简要记录可复核的理由或依据）。
结果是什么。
下一步是什么（如仍有后续工作）。

避免每执行一个微小操作就写一条记录，也不要只写“继续调试”“问题已解决”等无法复核的描述。

第三步：准确记录代码与文件变更

记录实际检查或修改过的文件路径，以及每项变更的目的。必须区分：

已修改：有实际文件变更证据。
已检查：查看过内容，但未修改。
计划修改：尚未执行。
未确认：当前证据不足。

不要把计划写成已完成的工作。不要覆盖用户已有的日志内容；更新已有条目时应保留仍然有效的历史信息。

第四步：记录验证结果

对于构建、测试、脚本或命令行操作，尽可能记录：

实际执行的命令或测试名称。
执行结果与关键输出。
成功、失败、部分通过或未执行的状态。
失败原因（仅在有证据时填写）及后续处理。

只有确实执行并观察到结果，才能标记为“已验证”或“测试通过”。如果只是阅读代码、推断原因或提出建议，应明确标注为“静态分析”“推测”或“尚未验证”。

第五步：结束或交接

任务阶段结束时，更新任务状态，并明确列出：

已完成事项。
尚未解决的问题与风险。
尚未执行的测试或验证。
下一步建议及必要的上下文。
日志文件的实际保存路径。

如果任务尚未完成，应标记为“进行中”或“阻塞”，不能为了形成完整日志而宣称任务已经完成。

5. 日志格式

每个任务日志使用以下模板，并根据任务规模删减不适用的部分：

# 工作日志：<任务名称>

- 日期：<YYYY-MM-DD；无法确认时写“未记录”>
- 项目/仓库：<项目名称或路径；未知时写“未确认”>
- 状态：进行中 / 已完成 / 阻塞
- 目标：<任务目标>
- 完成标准：<用户要求或可核验的完成条件>

## 进展记录

### <阶段或日期>
- 操作：
- 依据/原因：
- 结果：
- 状态：已完成 / 失败 / 部分完成 / 未验证

## 关键决策
- <决策及简要依据；没有则写“暂无”>

## 文件变更
- `<文件路径>`：<实际变更及目的>
- 没有文件变更时，明确写“本阶段未修改文件”。

## 验证结果
- 执行项：
- 结果：
- 结论：通过 / 失败 / 部分通过 / 未执行

## 问题与风险
- <已确认的问题、潜在风险及证据；没有则写“暂无已知问题”>

## 下一步
- [ ] <待办事项>

INDEX.md 使用简单列表即可，例如：

# Agent 工作日志索引

- [2026-10-27-修复查询错误.md](./2026-10-27-修复查询错误.md) — 修复查询错误；状态：进行中

日期、文件名和状态必须以实际情况为准，不要照抄示例中的任务信息。

6. 安全与准确性要求

不记录密码、访问令牌、API Key、私钥、会话 Cookie 或其他凭据；如日志中出现，应先脱敏。
避免记录与任务无关的个人信息、机密数据或大段源代码。
对事实、推断和未验证假设作清楚区分，并保留必要的证据或文件路径。
不伪造时间、命令输出、测试结果、文件修改或用户确认。
不因创建日志而擅自安装依赖、修改项目配置、执行破坏性命令或提交代码。
如果日志写入失败，明确告知用户失败情况，不得假称保存成功。
日志应简明、可检索、可交接，优先记录对后续工作有价值的信息。

7. 恢复先前任务

用户要求继续某项先前工作时：

先查看相关日志和索引（如果存在）。
再检查当前工作区、分支、文件状态或其他可用证据。
对比日志与当前状态，识别已经变化或过期的信息。
以当前实际状态为准；必要时修订日志，并说明重要差异。
从最近一个尚未完成的步骤继续，不要仅凭旧日志认定任务仍处于原状态。

8. 回复用户

完成日志更新后，用简短的自然语言说明：

本次记录了哪些主要内容。
日志保存在哪里，或明确说明尚未保存。
当前任务状态及最重要的下一步。

除非用户要求，不要在回复中重复整份日志。