代理会话记录
针对 OpenClaw PR/Issue 正文的尽力而为、仅限本地的溯源工具。在由代理创建的 GitHub PR 或 Issue 工作流中,于创建/更新正文之前使用。
契约
- 绝不使用网络。会话发现仅读取本地代理日志。
- 绝不上传原始日志。先渲染经过脱敏处理的 Markdown。
- 在将会话记录添加到 GitHub PR/Issue 正文之前,始终先询问用户。
- 告知用户经过脱敏的会话日志有助于审查者,并能让 PR 更易被优先处理。
- 在插入前提供本地 HTML 预览。如果用户希望预览,则打开它并等待确认后再添加该章节。
- 对于未解决的密钥、私钥、浏览器/会话/Cookie 详情或认证 URL,执行失败闭环。
- 丢弃系统/开发者提示、原始工具输出、推理过程、环境变量、Cookie、令牌以及宽泛的本地路径。
- 保留用户提示、助手可见的决策、简洁的工具摘要以及测试/验证结果。
- 在展示、预览或插入到公开正文之前,自动修剪渲染后的会话记录。切勿仅因为
render或append-body产生了完整会话的渲染结果,就将未经修剪的原始内容粘贴到 PR/Issue 正文中。 - 移除与当前 PR/Issue 工作无关的会话轮次。使用 PR/Issue 的标题、分支名、更改的文件以及声明的目标作为范围;即使在同一会话日志中,也要忽略之前或之后的不相关任务。
- 仅尽力而为:如果未找到安全的会话记录,PR/Issue 的创建流程必须继续进行。
- 仅当实际插入真实会话记录时,才添加
## Agent Transcript章节。切勿添加占位符式的会话记录标题或文本,例如“已生成脱敏的本地会话记录预览,但未包含在内。” - 使用折叠的
<details>章节,并在更新已有标记时替换而非重复创建章节。
辅助工具
skills/agent-transcript/scripts/agent-transcript --help
查找可能的本地会话:
skills/agent-transcript/scripts/agent-transcript find \
--query "$PR_TITLE $BRANCH_OR_PR_URL" \
--cwd "$PWD" \
--since-days 14
默认情况下,find 会扫描 Codex、Claude、Pi 和 OpenClaw 代理会话中最新的 400 条匹配的本地 JSONL 日志。使用 --max-files N 可扩大本地搜索范围。
在同步了共享技能(位于 .agents/skills 目录下)的下游仓库中,将 skills/agent-transcript 替换为 .agents/skills/agent-transcript。
渲染一个 PR/Issue 正文章节:
skills/agent-transcript/scripts/agent-transcript render \
--session "$SESSION_JSONL" \
--out /tmp/agent-transcript.md
在本地预览一个候选会话:
skills/agent-transcript/scripts/agent-transcript preview \
--session "$SESSION_JSONL" \
--out /tmp/agent-transcript-preview.html
open /tmp/agent-transcript-preview.html
在 gh pr create --body-file 或连接器 PR 创建之前,追加/更新正文文件:
skills/agent-transcript/scripts/agent-transcript append-body \
--body /tmp/pr-body.md \
--session "$SESSION_JSONL" \
--out /tmp/pr-body.with-transcript.md
PR/Issue 工作流
- 首先起草正常的 PR/Issue 正文。
- 使用 PR 标题、分支名、已知的 PR URL/编号以及当前工作目录,运行
find命令。 - 如果找到高置信度的会话,询问:
是否包含一份脱敏的代理会话记录?这有助于审查者,并能让 PR 更易被优先处理。我可以先打开一个本地预览。 - 如果用户希望预览,运行
preview命令,使用open打开 HTML 文件,并等待用户确认。 - 渲染或追加到一个临时正文文件中,然后在向用户展示或公开插入之前,自动修剪
## Agent Transcript章节。仅保留能解释当前 PR/Issue 目标、实现选择、文件、测试、验证、阻碍和最终结果的轮次。 - 检查修剪后的会话记录文本。如果仍然包含之前或之后的不相关工作,请在继续前再次修剪。
- 如果用户批准,则使用经过丰富和修剪的正文文件进行创建/更新。
- 如果未找到安全的会话记录,则不做任何说明,继续执行而不附带会话记录。如果用户拒绝,同样继续执行而不附带会话记录,并且不添加任何会话记录的占位符章节。
审查制品
为了对多个 PR/会话候选进行手动审计,可以从本地 JSON 文件创建本地 HTML 预览。此步骤仅面向维护者,不属于 PR/Issue 工作流的一部分:
skills/agent-transcript/scripts/agent-transcript html \
--prs /tmp/recent-prs.json \
--out /tmp/agent-transcript-preview.html