安装与本机检查

# Windows（对已校验的临时脚本）
py oasn-sa-dev.py install --expected-sha256 <Skill绑定的64位SHA-256>

# macOS / Linux
python3 oasn-sa-dev.py install --expected-sha256 <Skill绑定的64位SHA-256>

安装结果返回 installed_path、command 和 path_hint。先用返回的完整 command 再执行 --version；若 PATH 仍指向旧副本，不要反复安装或自行修改 shell 配置。

认证与 SSH key

oasn-sa-dev auth status
oasn-sa-dev auth login
oasn-sa-dev auth logout

oasn-sa-dev ssh-key ensure
oasn-sa-dev ssh-key ensure --create
oasn-sa-dev ssh-key ensure --create --path <新私钥路径>

• auth status 只查安全凭据库；auth login 用于明确重试 OAuth；需要认证的其他命令也会按需启动浏览器。
• auth logout 分别报告本地删除和服务端吊销结果；server_status=unconfirmed 不能当作已确认撤销。
• 未加 --create 的 ssh-key ensure 只查找/校验公钥。创建新 key 必须取得明确授权，目标已存在时 CLI 拒绝覆盖。
• 私钥始终留在本机；平台只接收公钥。CLI 使用系统 Credential Manager、Keychain 或 Secret Service，不回退到明文会话文件。

选择来源、创建并连接 Workspace

1. 只读查询来源

oasn-sa-dev workspace sources --version-id <agent_version_id>

结果可能提供当前 existing_workspace、可恢复的已发布版本与 recommended_source_version_id。推荐项不是自动授权；开发者必须在“续用已有 Workspace / 指定历史快照 / fresh 基础环境”中明确选择。

2. 创建或续用

# 基于开发者确认的已发布版本快照
oasn-sa-dev workspace create --version-id <目标draft版本ID> --source-version-id <来源版本ID>

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

# 只读查询已知 Workspace 生命周期
oasn-sa-dev workspace status --workspace-id <workspace_id>

来源 Version 只恢复兼容的代码/文件快照，不复制 Agent Card、Pricing、模型、资源规格或 WebUI 端口。若 sources 已返回可续用的 Workspace，就使用其 ID，不用 create 覆盖。

3. 绑定公钥并真实验证 SSH

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

status=active 只表示生命周期就绪，不证明 SSH 可用。workspace connect 会核对本机公私钥、按稳定幂等意图绑定未绑定 Workspace、使用 Workspace 隔离的 known_hosts，并执行真实 -vvv 认证探测。只有返回 ssh_binding_status=bound 且 ssh_verified=true 后，才逐字执行结果中的完整 ssh_command/scp_command。

4. 仅续签短期连接

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

只在开发者明确要求继续使用同一 active + expired Workspace 时执行。resume 不新建 Sandbox、不绑定 SSH key，也不替代后续 workspace connect 的认证探测。

等待参数

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,8765

# 经开发者明确确认后，清空全部端口
oasn-sa-dev version webui-ports set --version-id <agent_version_id> --clear

# 保留完整端口并创建新一代业务链接
oasn-sa-dev version webui-ports refresh --version-id <agent_version_id>

• 端口为唯一整数 1..65535，不能使用 22/18789/18790。
• set 是整体替换；相同列表是幂等空操作。refresh 不是 set，也不清空、不重建 Sandbox。
• 结果中的端口 revision 不是官网草稿 ETag。
• sync_status=ready 只证明声明同步；proxy_status=ready 才提供当前有效 webui_urls，但仍须真实测试 HTTP。

官网开发者操作

# 离线列出当前部署支持的官网操作及写入属性
oasn-sa-dev portal commands

0.7.3 的 portal 命令使用与官网相同的公开接口。只读命令可直接查询；写命令必须是开发者已经明确要求的当前动作，并携带命令要求的 --confirm、稳定 --idempotency-key、原始带引号 --if-match 或临时 --body-file。具体操作和参数以本机 portal commands 与 --help 为准，不从旧手册猜测。

兼容 Skill Link

oasn-sa-dev skill-link create --version-id <VERSION_ID>

这是仍被解析器接受的兼容入口。推荐主流程仍是在官网点击 Build With Local Agent，复制绑定当前 Agent/Version 的完整可信提示词。

仍然不存在或不能替代的操作

常见稳定错误