dym-agent-desktop-session

用途

dym-agent-desktop-session 用于让一次桌面操作（computer-use）留下可复核的凭据：当某个裁决或结论需要靠日志而不是靠模型口述来支撑时（例如 /br qc、/fdk-poc 或任何需要可反驳 verdict 的流程），使用本技能开启会话并记录追踪。

它同时面向多 agent 并行场景：多个 agent 在同一台 macOS 上运行（如 Orca worktree 环境）时，鼠标是共享资源，需要 lease 机制，也需要区分哪个光标属于哪个 agent。

如果只是执行一条单独的只读命令，则跳过本技能，会话是多余的。

主要能力

会话管理：为整轮工作开启一次会话，追踪默认开启。
追踪记录：会话范围内的所有命令自动写入 JSONL，无需逐条命令加 --trace。
证据读取：trace show 输出便于 agent 阅读的紧凑 JSON；trace export 输出单文件 HTML 供人查看。
事件结构：每条命令产生 command.start → 业务事件（如 snapshot.saved 带 ref_count、snapshot_id）→ command.end（带 duration_ms、ok）。事件带 ts_ms 和按进程单调递增的 seq，可还原多进程之间的真实顺序。
多 agent 光标：可为每个 agent 分配独立光标（颜色/标签），并通过 lease 串行化对共享 OS 光标的访问。
清理：session end 结束会话，session gc 清理已结束且超过指定时长的会话。

使用方式

为整轮工作开启一次会话（追踪已开启）：

$AD session start --name br-frame-07        # → data.session_id, data.next
export AGENT_DESKTOP_SESSION=run-1788964205617-6007-0

若需要每个动作的前后截图以便回放，使用 session start --screenshots（artifacts: full）——该选项敏感，应视同截图，不要推入仓库。

之后正常执行工作，会话范围内的所有命令自动写入 JSONL，无需逐条加 --trace。Segment 位于 $AGENT_DESKTOP_HOME/sessions/<id>/trace/<pid>-<procTs>.jsonl。

读取证据：

$AD trace show --limit 200                  # JSON 紧凑，供 agent 阅读
$AD trace export --out ./scratchpad/run.html   # 单文件 HTML，供人查看

结束并清理：

$AD session end $AGENT_DESKTOP_SESSION
$AD session gc --ended --older-than 86400

多 agent 并行（资料注明：本轮未以真实运行验证，依据工具文档）：

$AD session start --cursor --multi-agent    # 一个共享 session
AGENT_DESKTOP_AGENT_ID=frame-07 $AD click "@s..:e5"   # 每个 agent 一个稳定 ID
$AD cursor-overlay disable                  # 关闭该 session 的所有光标

Harness 向所有 subagent 传递同一个 session ID；每个 subagent 自行声明 AGENT_DESKTOP_AGENT_ID（或 --agent-id，命令行标志优先于环境变量）。三个不同 ID → 三个带各自颜色/标签的光标。UI 操作必须有 ID；观察/剪贴板/管理类操作则不需要。Lease 用于串行化对共享 OS 光标的访问。

规则与限制

会话不会自动传播到后续进程：session start 只创建 manifest，必须自行传递 AGENT_DESKTOP_SESSION 或 --session <id>。优先级：--session > 环境变量 > 无会话。
裸的 --session <id>（没有来自 session start 的 manifest）只选择 snapshot 命名空间，不会开启 trace——旧调用方不会因此多出陌生文件。
Trace 会自动遮蔽敏感字段（text、value、name、token、password、url、title 等 → {"redacted": true}）。但 --screenshots 不做任何遮蔽——图片就是图片。
--trace <path> 覆盖为写入单个文件，用于 CI/一次性场景。--trace-strict 才会在 trace 写入失败时报错；默认的事后 trace 是 best-effort → 不要用“没有 trace 行”作为“没有动作”的证据。
Ref 在命名空间内是 snapshot 作用域的；查找永远不会跨到其他命名空间。Agent A 不能使用 Agent B 的 ref，除非处于同一 session 且同一 snapshot。
在把 trace 当作凭据之前，status 必须显示 tracing: true 且 session_id 正是当前使用的那个。

技能介绍

用途

主要能力

使用方式

规则与限制