安装 CLI 与创建环境

oasn-sa-dev 0.7.3 是开发者的受控命令入口：它校验安装来源，处理 OAuth、安全凭据库、Workspace 来源选择、公钥绑定与真实 SSH 探测，还能配置业务 WebUI 端口和调用公开 Developer Portal 操作。不要用旧版 0.2.x 的命令表判断当前能力。

安全安装：只从可信提示词进入

1. 复制完整 Build With Local Agent 提示词

   提示词把当前 agent_id、agent_version_id 与固定 Skill 入口绑定在一起。原样交给本地 AI，不替换 URL、摘要或 ID。

2. 执行 Skill 中的受限 bootstrap

   bootstrap 校验 HTTPS、大小、响应头摘要和正文 SHA-256，再调用脚本自身安装。下面只解释最终安装参数，真正下载步骤必须使用本次 Skill 给出的值：

   # Windows（已校验的临时文件）
   py <已校验的-oasn-sa-dev.py> install --expected-sha256 <Skill绑定的SHA-256>
   
   # macOS / Linux
   python3 <已校验的-oasn-sa-dev.py> install --expected-sha256 <Skill绑定的SHA-256>
   

3. 用返回的绝对命令核对版本

   安装 JSON 返回 command、installed_path 和 path_hint。先运行返回的完整 command --version，必须是 0.7.3 或更新；PATH 中另一个旧副本不能作为证据。

摘要不一致必须停止

CLI_DIGEST_MISMATCH 表示文件与 Skill 绑定版本不同。删除本次临时下载，从官网重新生成可信提示词；不要忽略校验或修改 expected digest。

先做只读检查

oasn-sa-dev --version
oasn-sa-dev auth status
oasn-sa-dev doctor
oasn-sa-dev workspace sources --version-id <agent_version_id>

doctor 检查 Python、OpenSSH、ssh-keygen、本地回环和已有公钥，不修改远端。workspace sources 返回当前可续用 Workspace、可恢复的历史版本和 fresh 选项；先把实际选项展示给开发者确认，不能把 recommended_source_version_id 当自动授权。

创建或续用正确的 Workspace

续用已有 Sandbox

sources 返回 existing_workspace 时，保留现场并用该 ID 查询/连接，不再 create。

恢复已发布快照

开发者确认来源后，用 --source-version-id 创建独立 Workspace。

从基础环境开始

开发者明确选择空白环境时使用 --fresh。

# 从已确认的来源版本恢复
oasn-sa-dev workspace create --version-id <目标draft版本ID> --source-version-id <来源版本ID>

# 明确使用平台基础环境
oasn-sa-dev workspace create --version-id <目标draft版本ID> --fresh

创建命令会轮询到 active、终态或超时，但不会读取、生成或上传本机公钥。来源快照只提供代码、文件和依赖，不复制来源版本的 Card、Pricing、模型、Resources 或 WebUI 端口。

超时后继续查询原 Workspace

oasn-sa-dev workspace status --workspace-id <WORKSPACE_TIMEOUT返回的ID>

超时只是本次等待耗尽，不等于创建失败。不得用新的 create 隐藏未知结果，也不要并发启动多个 status。

active 后必须 connect

oasn-sa-dev workspace connect --workspace-id <workspace_id>

新 Workspace 可以是 status=active 但 ssh_binding_status=unbound。connect 会：

1. 从本机私钥导出公钥，确认公私钥匹配。
2. 对 unbound Workspace 使用稳定幂等意图绑定公钥；binding 状态只允许用同一 key 恢复。
3. 使用 Workspace 独立 known_hosts 做 host key 保护。
4. 以 -vvv、IdentitiesOnly=yes 和 BatchMode=yes 执行真实认证探测。

连接完成门

只有 CLI 返回 ssh_binding_status=bound 且 ssh_verified=true，才使用该结果里的完整 ssh_command 和 scp_command。不要直接执行旧 status 响应或手工拼 host、端口、用户、key 参数。

本机没有 key 时，创建动作会修改用户文件，必须先明确同意：

oasn-sa-dev ssh-key ensure --create
# 或在明确的新路径创建
oasn-sa-dev ssh-key ensure --create --path <新私钥路径>

连接过期与 resume

oasn-sa-dev workspace resume --workspace-id <workspace_id>

resume 只在开发者明确继续使用同一 active + expired Workspace 时续签短期连接和稳定 Gateway 会话；不新建 Sandbox、不绑定/覆盖 key。需要 SSH 仍要再用 connect 验证。

Workspace 成功摘要

{
  "workspace_id": "dws_example",
  "agent_id": "agt_example",
  "version_id": "sav_example",
  "source_version_id": "sav_source_or_null",
  "status": "active",
  "connection_status": "ready",
  "ssh_binding_status": "bound",
  "ssh_verified": true,
  "remote_project_dir": "/oasn",
  "webchat_url": "https://...",
  "webui_urls": [],
  "ssh_command": "ssh -vvv ...",
  "scp_command": "scp ...",
  "expires_at": "..."
}

字段以当前 CLI 实际 JSON 为准；上面是脱敏完成门示例，不要复制其中 ID/URL。Sandbox 内还会注入非敏感的 OASN_AGENT_ID 和 OASN_AGENT_VERSION_ID；它们是身份上下文，不是 Token 或 Owner 授权。

WebUI 与 Portal 命令已经可用

# WebUI 端口：查询、整体替换、刷新链接
oasn-sa-dev version webui-ports get --version-id <agent_version_id>
oasn-sa-dev version webui-ports set --version-id <agent_version_id> --ports 7860
oasn-sa-dev version webui-ports refresh --version-id <agent_version_id>

# 列出当前部署的官网开发者操作
oasn-sa-dev portal commands

端口与严格输出 JSON 的完整步骤见 结构化输入与 WebUI JSON。Portal 写操作必须对应开发者已经明确要求的当前动作，并携带命令要求的确认、ETag 和幂等参数；它不授权后续阶段。

命令边界速查

CLI 没有通用 sync，也没有 workspace close/delete/publish。代码同步按 安全同步 使用 connect 返回的参数；发布/上线按当前网站或 portal commands 明确列出的受控操作执行，不能猜原始 API。

常见连接错误不要合并处理

完整参数表和 WebUI 状态处理见 CLI 命令参考。