| name | agent-logs |
| description | 面向 agents 的执行日志技能。记录时间、用户原始 prompt、上下文摘要、文件改动、git 操作、模块化隔离与备份检查信息。 |
Agent Logs Skill
这个技能用于记录 agent 执行过程的关键审计信息，便于回溯、复盘和交接。
日志主存储为 Markdown 文件，直接落地在仓库根目录：docs/agent-logs/。
并按天做分区（文件夹分层），作为一个小型日志数仓。
数据库存储约定：
skills 目录中的 agent_logs.db 仅作为空模板库（schema 模板）。- 实际运行数据库位于
docs/agent-logs/agent_logs.db。
记录要点
- 时间（通过 Linux
date 命令获取）
- 用户完整原始 prompt（不截断）
- LLM 执行上下文精简总结
- 改动文件列表
- 是否执行 git 操作
- 是否模块化隔离
- 是否执行备份，以及备份三特性检查
- 用户业务目标（便于回滚时理解“为什么改”）
- 关键代码片段（复制粘贴的 Markdown，便于回滚时定位“改了什么”）
- 关键代码上下文（位于哪个模块/文件、用于做什么）
备份三特性定义
这里默认采用以下三项检查：
integrity_ok：备份数据完整性通过（如校验和）consistency_ok：备份数据一致性通过（逻辑一致）recoverability_ok：备份可恢复性通过（可演练恢复）
命令用法
所有操作通过脚本完成：
python3 .agents/skills/agent-logs/scripts/agent_logs.py <command> ...
存储位置
- 分区目录：
docs/agent-logs/YYYY-MM-DD/
- 单条日志：
docs/agent-logs/YYYY-MM-DD/log-xxxx-<HHMMSS>.md
- 索引文件：
docs/agent-logs/INDEX.md
- 分区索引：
docs/agent-logs/YYYY-MM-DD/INDEX.md
- 总览导出：
docs/agent-logs/AGENT_LOGBOOK.md
1. 新增日志
python3 .agents/skills/agent-logs/scripts/agent_logs.py add \
--prompt "用户完整原始prompt" \
--summary "本次LLM上下文摘要" \
--biz-goal "让自动玩家能在无GUI模式下验证默认关卡可通关" \
--key-change-module ".agents/skills/python-quality-gate/scripts/python_gate.py" \
--key-change-purpose "在质量门禁里执行功能测试与自动通关验证，保证游戏规则与可通关性" \
--key-change-md "### 关键改动1: 自动通关断言\n\n```python\nresult = run_autoplay(assert_optimal=True)\nassert result.success\n```" \
--git-op yes \
--git-detail "执行了 git add 和 git commit" \
--isolated yes \
--backup yes \
--integrity-ok yes \
--consistency-ok yes \
--recoverability-ok no \
--backup-note "未做恢复演练" \
--auto-files \
--new-changes-only
说明：
--auto-files：自动抓取当前 git 变更文件（已跟踪变更+未跟踪文件）
--new-changes-only：仅记录相对最近一条日志“新增”的变更文件（差集），避免把历史遗留脏文件反复写入每条日志
- 也可用
--files 手工传入文件列表
--biz-goal：记录本次改动的用户业务目标--key-change-module：关键代码所在模块/文件（建议写仓库相对路径）--key-change-purpose：关键代码用途（解决什么业务目标）--key-change-md：直接粘贴关键代码片段（Markdown）--key-change-md-file：从文件读取关键代码片段（Markdown）
建议：关键代码片段必须同时填写 --key-change-module 和 --key-change-purpose，否则回滚时仍需要二次定位。
校验规则：当传入 --key-change-md 或 --key-change-md-file 时，脚本会强制要求同时传入 --key-change-module 与 --key-change-purpose。
2. 查看单条日志
python3 .agents/skills/agent-logs/scripts/agent_logs.py get 1
3. 列出最近日志
python3 .agents/skills/agent-logs/scripts/agent_logs.py list --limit 20
4. 导出 Markdown 总览
python3 .agents/skills/agent-logs/scripts/agent_logs.py export
默认导出到：docs/agent-logs/AGENT_LOGBOOK.md
