精灵接入说明

当前已经实现什么

先发现，再请求动作

供有源码的开发者使用：运行现有签名的隔离 DEBUG 预览（app.monoware.shotloom.skinpreview），设置临时 DESKCAPTURE_DIAGNOSTIC_DIR，并显式添加 --companion-agent-review 启动参数。启动日志中的 CompanionAgentReview 会给出私有会话目录。Release 构建无法开启此桥；这不是普通用户的安装命令，也不是已发布的 SDK。

使用源码中的 scripts/companion-agent-review.py。下文 SESSION_DIR 是启动日志给出的目录，不是密钥。

python3 scripts/companion-agent-review.py --profile SESSION_DIR runtime.describe
python3 scripts/companion-agent-review.py --profile SESSION_DIR characters.list
python3 scripts/companion-agent-review.py --profile SESSION_DIR capabilities.list
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.create '{"capability":"animation.complete","params":{"durationSeconds":2}}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.get '{"id":"RETURNED_REQUEST_ID"}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR requests.cancel '{"id":"RETURNED_REQUEST_ID"}'

使用发现返回的 ID，检查响应，并保留请求 ID。调试动作时长范围为 0.1–10 秒，运行时可能返回 BUSY 或 RUNTIME_UNAVAILABLE。

发出提示，也要知道有没有回应。

调试桥可以展示或撤回普通提示。accepted 只表示已入队，不能证明用户已阅读或完成任务；当前不会返回按钮选择或输入文字。

python3 scripts/companion-agent-review.py --profile SESSION_DIR notice.create '{"title":"Export complete","seconds":6}'
python3 scripts/companion-agent-review.py --profile SESSION_DIR notice.dismiss '{"id":"RETURNED_NOTICE_ID"}' 

拟议的交互闭环 — 尚未交付

1. 发现已授权能力，读取输入和结果 schema。
2. 用稳定选项 ID、超时和幂等键创建交互。
3. 精灵呈现提示，用户选择、回复、取消，或等待超时。
4. 按请求 ID 读取最终结果，再由调用方明确继续执行。

草案拟定义 requests.create/get/wait/cancel、样式与能力发现，以及 interaction.text/choice/confirm。这些是设计契约，不能直接发给当前 Release App。用户选择、提示已展示、业务执行成功，是不同的结果。

读取终态，别把接受当成功。

现有动画请求返回 running、completed 或 cancelled。被高优先级打断的动作以 cancelled/preempted 结束，不在事后重播。非法参数会被拒绝，精灵隐藏或不可用时不会偷偷重新显示。

调试结果只在当前会话内存中保留，不能假设重启恢复、持久历史、按客户端隔离或生产可用性。完整协议还要求超时、取消和唯一用户终态，这些仍是实施要求。

本机、明确授权的接入

调试邮箱使用 0700 私有目录和 0600 文件，随机密钥从会话 profile 读取。密钥不放进命令参数、公开文档、网址或日志；不会打开 TCP 监听。正式方案计划采用本机 Unix domain socket，并要求明确配对和撤销。

精灵表达接口不授予截图、剪贴板读取、文件访问或任意 Shell 执行能力。业务由调用方负责，精灵只呈现已声明且获授权的能力。