OpenAgent
OpenAgent

参考

状态与安全

状态决定“现在可以做什么”，安全边界决定“即使能做，也不能泄露或绕过什么”。开发过程应同时满足两类约束。

Workspace 状态决策

状态能否 SSH/SCP/WebChat动作
创建中的非终态否让 CLI 继续轮询；超时后用相同 Workspace ID 查询
activeWebChat 可用；SSH 仍取决于 binding/verification先运行 workspace connect；只有 bound + ssh_verified=true 才使用精确命令，留意 expires_at
failed否记录 failure_code，停止连接尝试
closed否终态；不能“resume”
published否终态；到网站查看发布版本
cleanup_pending否平台收尾中，不继续写入
close_pending否平台关闭中，不继续写入

超时不是终态

WORKSPACE_TIMEOUT 只表示本次等待窗口耗尽。保留错误中的 workspace_id 与 last_status，随后运行 workspace status；不要重复创建。

发布、版本与 Agent 供给状态

发布 Job 与可见性是两条相关但不同的状态轴；页面展示的版本 online/offline 与 Agent 层 supply_status 又是两组不同字段。开发者日常操作以页面的 Online/Offline 为准，排查 API 时不要混写。

层级关键状态完成门
Publish Jobqueued → running → succeeded；或 failed/canceledsucceeded
Publicationpending → syncing → visible；或 failedvisible
Version / UIoffline / online需要正式接受调用时，页面必须显示 Online
Agent supplysuspended / listedOnline 时还应为 listed；不要把这里写成 Online/Offline

推荐把完成条件写成：

publish_job == "succeeded"
and publication == "visible"
and version_status == "online"
and supply_status == "listed"
and real_invocation_verified == true

OAuth 登录安全

CLI 在需要认证时打开浏览器，使用四项关键防护：

  • Loopback callback：回调只绑定本机回环地址，不要求开发者复制访问令牌。
  • state：将授权响应绑定到本次请求，拒绝不匹配回调。
  • PKCE：授权请求和换取会话之间使用挑战/验证值。
  • one-time code：浏览器返回一次性 code，而不是把长期令牌放进 URL。

凭据只进入系统安全存储

平台CLI 使用的存储
WindowsWindows Credential Manager
macOSKeychain
LinuxSecret Service（secret-tool）

如果这些安全存储不可用，CLI 返回 credential_store=unavailable，不会把会话明文写入普通配置文件作为 fallback。不要用自制脚本把 Token 存到项目目录、Shell 历史或环境快照。

SSH key 边界

应当

  • 先运行不修改状态的 ssh-key ensure 查找已有 key。
  • 只有用户明确同意时才加 --create。
  • 私钥留在本机，平台只接收一行 OpenSSH 公钥。
  • 使用 CLI 返回的精确 SSH/SCP 命令。

禁止

  • 覆盖现有 key 文件。
  • 上传私钥、把私钥粘贴进网页或聊天。
  • 在 Workspace ID、Version ID 或主机信息不明时猜连接参数。
  • 把凭据写入 /oasn 或提交到版本库。

日志、截图与协作中的脱敏

  • Token、Cookie、Authorization header、私钥全部移除。
  • SSH/SCP 命令若含临时主机、用户名或连接材料，只保留排障所需部分。
  • 截图裁掉账户邮箱、余额、浏览器密码提示和系统路径中的个人名称。
  • 错误可记录错误码、状态、Workspace ID/Version ID；对外发送前按团队策略处理 ID。
  • 不要把 CLI 的系统凭据库内容或浏览器回调 URL 复制到工单。

控制面边界

网站与 CLI 是开发者公开控制面。CLI 0.7.3 已提供 workspace sources/connect/resume、version webui-ports 和受控 portal 操作；写入仍只限开发者明确要求的当前动作。当前没有通用 sync 或 workspace close/delete/publish 子命令，不能通过猜测内部 URL、复用服务间凭据或手写数据库/API 绕过。

结构化输入与 WebUI 的敏感边界

  • 只从 /oasn/in/invocation.json 读取业务所需的 input.user_prompt 和当次 input.attachments；禁止记录或向浏览器返回完整文件。
  • 附件路径只在服务端使用，不扫描父目录、不复用历史路径、不放进 WebUI URL。
  • oasn-webui 的 URL query/hash 不携带 token、secret、signature、credential、password、authorization 或 api_key。
  • 客户端只信任平台投影的 structuredContent.views[]，不自己从正文解析 fenced block。

搜索文档

推荐搜索