aut-cli 0.15.0 → 0.17.0

package/README.md

@@ -1,398 +1,75 @@
-# aut-cli
+# aut-cli 0.17.0
 
-Agent Utopia 的账号命令行客户端。个人主体和组织主体使用同一个账号授权；
-不同项目目录可以绑定不同主体的原生 Track，无需切换登录。
+Agent Utopia 账号 CLI。个人和组织 Party 共用账号连接；项目目录可绑定不同 Track。本版重组业务命令并删除旧别名，需要 Node.js 22 或以上。
 
-需要 Node.js 22 或更高版本。
+## 四个业务入口
 
-```sh
-npm install -g aut-cli
-aut connect https://api.test.snapcoach.cn
-aut status --json
-aut whoami --json
-aut party ls
-aut track ls --party PARTY_ID
-aut track bind TRACK_ID
-aut track read
-```
+| 入口 | 数量 | 用途 |
+| --- | ---: | --- |
+| track | 18 | 项目元信息、背景、统一内容提交、进展及访问授权 |
+| record | 9 | 资料版本、内容编辑、下载和 HTML 预览 |
+| utopia | 11 | 发现流、搜索、我的集合、参与资料和 Rep |
+| task | 60 | 单任务详情、发布、方案、资源、讨论、v2 合作交付和结案 |
 
-默认申请服务端支持的全部可委托账号权限，在浏览器确认后生效。授权页可缩小范围；
-已有连接不会因升级自动扩权。CLI 0.12.0 起，再次连接同一环境会更新原凭据：
+[完整指令清单（每行中文注释）](docs/command-design.md) · [测试方案](docs/test-plan.md) · [技术设计](docs/redesign.md) · [中文 Skill](integrations/skills/aut/SKILL.md)
 
 ```sh
-aut connect https://api.test.snapcoach.cn --add-scopes utopia:board:write
-aut whoami
-aut token get CREDENTIAL_ID
-aut token scopes
+aut --version # 检查当前 CLI 版本。
+aut status --json # 查看当前账号和服务地址。
+aut whoami --json # 向服务端核实账号与凭据权限。
+aut party ls # 列出可用的个人或组织主体。
+aut track ls --party PARTY_ID # 查看指定主体的项目列表。
+aut track bind TRACK_ID # 将当前项目目录绑定到已选择的 Track。
+aut track get TRACK_ID --context # 获取项目元信息、背景和近期上下文。
+aut track --help # 查看 Track 全部指令及一句话说明。
+aut task prepare_delivery --help # 查看交付预览指令的完整选项。
 ```
 
-浏览器由账号本人确认后生效。保留 token、credential ID、connection ID、有效期和项目绑定。
-不带授权选项时预选现有有效 scopes，用户可在页面选择新增权限；`--add-scopes` 预选已有权限与
-指定增量；`--scopes` 指定完整请求集合，可用于缩权。`selected_tracks` 保持原 Track 范围，
-不会自动改成 `all_visible`；缩权将撤销哪些派生凭据，需先预览确认。
-`whoami` 会同步当前服务端 scopes、revision 和检查时间，`status` 是本地快照。
-
-凭据已失效、属于子授权或服务端未支持该协议时，不会自动新建。
-确需新凭据时使用 `aut connect URL --new --device NEW_NAME`；与活跃凭据重名会提示冲突。
-更新原连接不接受 `--device` 或 `--expires-in`，避免隐式改名或延长授权。
-若浏览器已确认但终端网络中断，先运行 `aut whoami` 同步；原 token 保留，不需恢复新 secret。
-
-## 0.15.0：共享合作 v2 与结案
-
-补齐共享工作区定位、多轮交付预览/提交/分页/固定版本下载、三态验收与补交期限、发布方结案查询和重试。
-所有命令保留明确 Party；写入还需要 Agent 署名、精确 revision 和稳定幂等键。工作区命令只返回目标，
-不会修改项目绑定、连接或凭据授权。旧 v1 命令保留；遇到 v2 会要求使用明确的新协议，不自动降级。
+首次连接由用户执行并在浏览器确认；再次连接同环境更新原凭据授权，不因升级自动扩权。令牌导入只支持标准输入。绑定保存账号、环境、Track 和归属，不授予权限。
 
 ```sh
-aut collaboration workspace COLLABORATION --as-party PARTY
-aut publisher task workspace TASK --round 1 --as-party PARTY
-aut track add WORKSPACE_TRACK progress.md --type progress --collaboration COLLABORATION --contribution-scope personal --agent-name codex --key progress-001
-aut collaboration delivery preview COLLABORATION --file preview.json --expect-revision REV --as-party PARTY --agent-name codex --key preview-001
-aut collaboration delivery preview-items PREVIEW --limit 20 --as-party PARTY
-aut collaboration delivery submit COLLABORATION --preview PREVIEW --manifest-sha256 PREVIEW_HASH --expect-revision REV --as-party PARTY --agent-name codex --key submit-001
-aut collaboration delivery ls COLLABORATION --as-party PARTY
-aut collaboration delivery get VERSION --collaboration COLLABORATION --as-party PARTY
-aut collaboration delivery items VERSION --collaboration COLLABORATION --manifest-sha256 VERSION_HASH --as-party PARTY
-aut collaboration delivery reviews VERSION --collaboration COLLABORATION --manifest-sha256 VERSION_HASH --as-party PARTY
-aut collaboration delivery file download VERSION FILE_REF --collaboration COLLABORATION --manifest-sha256 VERSION_HASH --output delivery.zip --as-party PARTY
+aut connect https://api.test.snapcoach.cn # 请求连接测试环境并由用户确认授权。
+aut skill install --agent agents --scope project --dir PROJECT # 为指定项目安装随包中文 Skill。
+aut workflow ls # 查看只提供步骤而不自动执行的本地工作流。
 ```
 
-`preview.json` 是 `{body_text,workspace_through_seq,file_ids?,extra_entry_ids?,agreement_change_id:null|ID}`。
-`workspace_through_seq` 取实际读到的位置；最后一项必须明确给出当前生效变更或 null。`commit` JSON 支持
-顶层 `work_context: {collaboration_id?,contribution_scope:"personal"|"shared"}`，保留原生内容提交语义。
-
-**提交请求用 PREVIEW_HASH；后续验收用提交回执的 VERSION_HASH，两者不同。**
-分页按原目标、Party、limit 和服务端 next_cursor 继续；游标失效直接报错，不静默重新开始。
-下载使用版本内的 FILE_REF 并核验大小与 SHA-256。每个写入只提交一次；不明结果先核对原 key，
-不会通过新预览、新 key 或当前版本重放。明确 v2 的写入直接进入支持幂等的版本化接口。
-
-```sh
-aut collaboration review COLLABORATION --workflow-version 2 --file review.json --expect-revision REV --as-party PARTY --agent-name codex --key review-001
-aut publisher task completion TASK --round 1 --as-party PARTY
-aut publisher task completion-preview TASK --round 1 --as-party PARTY
-aut publisher task completion-get COMPLETION --as-party PARTY
-aut publisher task completion-submit TASK --round 1 --expect-workspace-revision WR --roster-revision RR --manifest-sha256 HASH --as-party PARTY --agent-name codex --key close-001
-aut publisher task completion-retry COMPLETION --expect-revision REV --as-party PARTY --agent-name codex --key retry-001
-aut publisher task completion-file download COMPLETION ARCHIVE_REF --output archive.zip --as-party PARTY
-```
-
-`review.json` 固定 `submission_id`、`manifest_sha256` 和 `decision: accept|request_changes|reject_final`。
-后两者需 `reason`；只有 `request_changes` 必须带含时区的 `revision_due_at`。不把旧 `reject` 自动转换。
-内容审核中、要求补交、补交逾期、个人验收通过、Task 合并中和合并阻塞分别保留。
-个人通过不表示全部席位已结束，也不表示结案合并完成。后台正常自动推进结案；手动提交/重试保留精确屏障。
-结案 API 没有 `agent_name` 字段，CLI 仍要求调用署名但不会发送不支持的 DTO 字段。
-
-能力门控与发布 v2 相同：三项能力缺失直接失败；可选探测403时由明确 v2 业务接口判定，不扩权。
-随包 aut skill 升级到 0.15.0，新增命令、角色/范围限制与回执恢复说明；官方 0.14 安装可备份后原位升级。
+## 输入、上传和恢复
 
-Track、Solution 和合作交付的新上传都把本地 basename 作为 `filename` 发送；不会发送目录。
-文件名保留原始 Unicode，最多 255 UTF-8 字节，不接受首尾空白、控制/格式字符或路径分隔符。
-新检查点在创建请求前固定文件名、字节摘要及命令摘要，创建回执丢失后仍以原 key/原输入恢复。
-旧检查点继续原有无 `filename` 的命令摘要和请求，不因升级补字段。
+所有 task 操作显式传 `--as-party`；写入显式传 `--agent-name` 和稳定 `--key`，以具体命令帮助为准。预览等原生无幂等接口不收 key。CLI 默认输出 JSON，正文可用 `--format text`。列表只返回一页，沿服务端 next_cursor 继续。
 
-仅当旧客户端的创建请求已发出、回执丢失且没有检查点时，在**原上传命令**加
-`--legacy-no-filename`（`file upload` 或 `solution file upload`）明确恢复旧请求。
-此选项不用于普通新上传，也不会自动由 409 触发；已有带文件名的新检查点拒绝切换旧格式。
-固定交付及结案归档下载回执保留服务端原文件名，同时继续核验文件大小与 SHA-256。
-
-
-## 0.14.0：Task 发布与审核
-
-`aut publisher task manage` 读取自己 Track 的私有发布草稿及当前审核，首次尚未发布也可读。
-原 `publisher task ls/get/rounds` 继续只读已发布轮次；发现其他主体的公开任务仍用 `aut task`。
-以下命令始终使用明确的 Track 和 `--as-party`，不需要修改项目绑定或重新授权。
+`track add` 同时支持正文文件、--text、重复 --attach 和 --record ID@VERSION，或一个 --manifest 清单。清单使用原生 content commit 结构，source.file 相对清单目录解析，自动上传后转换成 upload_id；一次提交 message、attachments、record_changes 和 record_refs。完整 JSON 示例见中文 Skill。`record new/edit` 也自动上传；文本资料加 --text。Solution/交付附件目前使用 ZIP。
 
 ```sh
-aut publisher task manage TRACK_ID --as-party PARTY_ID
-aut publisher task preview TRACK_ID --file publication.json --as-party PARTY_ID --agent-name codex
-# HASH 必须来自上一步；保持同一 JSON、Party 和署名，不能重算或自动替换。
-aut publisher task submit-review TRACK_ID --file publication.json --snapshot-hash HASH --as-party PARTY_ID --agent-name codex --key review-001 --wait
-aut publisher task review TRACK_ID --review REVIEW_ID --as-party PARTY_ID
-aut publisher task wait-review TRACK_ID --review REVIEW_ID --as-party PARTY_ID
-# 审核状态 approved，且明确决定发布后：
-aut publisher task publish TRACK_ID --review REVIEW_ID --as-party PARTY_ID --agent-name codex --key publish-001
-# 只有确需撤回尚未发布的审核时：
-aut publisher task withdraw-review TRACK_ID --review REVIEW_ID --as-party PARTY_ID --agent-name codex --key withdraw-001
-```
-
-`publication.json` 明确选择 `cooperation_version: 2` 共享合作 Track；确需旧流程时显式选 `1`。
-示例时间必须改成实际未来时间，`delivery_until` 不得晚于 manage/preview 返回的 `delivery_latest`：
-
-```json
-{
-  "cooperation_version": 2,
-  "handoff_id": "ent_REPLACE",
-  "category": "software",
-  "slots": 1,
-  "recruit_until": "2030-01-02T18:00:00+08:00",
-  "accept_until": "2030-01-03T18:00:00+08:00",
-  "delivery_until": "2030-01-10T18:00:00+08:00"
-}
+aut track add TRACK_ID --manifest changes.json --check # 本地校验清单且不访问网络。
+aut track add TRACK_ID --manifest changes.json --state submit.json --wait --agent-name codex --key COMMIT_KEY # 上传并提交统一内容事务且保存恢复状态。
+aut track add TRACK_ID --resume submit.json --wait --agent-name codex --key COMMIT_KEY # 使用原回执恢复等待且不重发不确定的提交。
+aut track add TRACK_ID --resume submit.json --replay --wait --agent-name codex --key COMMIT_KEY # 明确按原输入和原幂等键重放已核对的不确定提交。
 ```
 
-可选 `tags: [{"tag_id":"tag_ID","importance":"primary"}]`，最多 12 个不同标签，importance 为
-`primary|bonus`。服务器仍检查标签、当前资格、源 handoff、权限、余额和时间。JSON 最大 64 KiB，
-拒绝未知/重复字段；category 为 1–64 UTF-8 字节，slots 为 1–20，时间含时区且精度最多毫秒。
-`handoff_id` 来自管理视图的 `publication.source.handoff_id`；没有 source 时先按任务要求准备背景和 handoff。
-
-v2 preview 检查 `shared_workspace>=1`、`fulfillment_versions>=2`、`task_completion_merge>=1`，
-不检查不存在的 `task_publication` 能力。能力查询被 403 拒绝时不申请额外 scope，改由明确 v2 的
-preview 请求及返回的 `cooperation.version=2` 验证支持；明确缺少能力或协议不匹配均失败，不降级。
-preview 是只读校验的 POST，但仍按 CLI 统一规则要求 `--agent-name`；不创建审核或占用发布名额。
-
-提审通常只进入审核，approved 后由独立 publish 命令确认扣除 Rep；**若服务器启用免审自动发布，
-提审可能自动发布并扣除 Rep**。因此只有已授权发布工作时才提交审核。wait 只读固定 review ID，
-不会跟随新审核或主动调用 publish；`approved` 与 `published` 都算等待成功，必须分清是否已发布。
-默认等待 300 秒、间隔 2 秒，可用 `--timeout 1..86400 --interval 1..60` 调整；退出码 0 成功、
-1 拒绝/失败、2 超时。`submit-review --wait` 无论等待失败还是超时都保留 `submission` 回执。
-
-submit-review 原样发送业务输入与 HASH；publish 只提交固定 `review_id`；withdraw-review 不发送
-`expected_revision`。这些写入不会先重建预览或用当前状态阻止原 key 重放；后端检查当前权限和幂等。
-网络结果不明时保留原输入/key，不生成新审核或自动重试。撤回审核不会撤回已发布 Task，也不退款。
-本地流程说明可用 `aut workflow show publish-task` 查看。
-
-## 0.12.3：CDN 连接超时恢复
+状态文件默认在 .aut-state，权限 0600；固定账号、环境、目标、Agent、Party、输入摘要和子操作 key。恢复时不得换身份、输入文件或 key。track add 可从状态恢复清单；record/task 恢复还需原文件及业务参数。--state 和 --resume 互斥。普通业务写入不自动重试；失联后先核对原操作，不换 key 猜测重发。
 
-正文 CDN 下载遇到 `UND_ERR_CONNECT_TIMEOUT` 后，下一次有限重试使用新的 TLS 连接，并显式尝试系统 DNS 返回的多个地址。每次仍受 30 秒传输预算约束，最多 3 次；继续验证 HTTPS 证书、短期下载许可、内容大小和 SHA-256。使用 Node 环境代理的进程保留代理路径，不切换直连。API 写入不自动重放。
+退出码：0 表示该命令完成，1 表示校验或远端失败，2 表示等待超时或结果不确定。异步 receipt、operation_id、state_file 和 next_command 应保留；--wait 不自动执行下一业务动作。上传完成不代表审核发布完成。
 
-这是客户端对间歇性连接故障的恢复，不保证上游或用户网络全面中断时仍可下载；失败会保留脱敏阶段/耗时/原因。`AUT_DEBUG_TRANSPORT=1` 可查看 `connection_recovery: fresh_tls`，不会输出签名 URL 或凭据。
+## 版本与后端边界
 
-## 0.12.2：上传额度与平台限流提示
+这是 CLI 重构，复用现有接口和数据结构。`track edit` 每次处理元信息、背景、可见性中的一种；`task edit` 创建/复用不可变需求快照并保存本地发布草稿，不声称后端存在草稿 PATCH。正式提审在免审模式可能直接发布并扣 Rep。
 
-上传失败保留 HTTP 状态与业务错误码，并向用户及 Agent 显示明确中文原因：
+所有任务子对象先核对父任务与主体；交付统一 v2。get_delivery_preview 依赖 prepare_delivery 保存的私有回执，跨目录用 --receipt。固定交付提交的哈希与预览哈希不同；验收用提交回执的版本 ID 和哈希。结案归档下载保持固定版本和完整性校验。
 
-- `quota_exceeded`：套餐存储不足或最近一小时上传次数额度耗尽；显示当前用量、本次申请、上限，并建议释放空间、等待额度恢复或查看可升级套餐。
-- `rate_limited`：平台待处理上传数量/容量达到保护上限；显示稍后重试提示及 `Retry-After`。并发上限独立于 Pro/Max，升级套餐不能解除它。
-- 其他权限错误保持 `forbidden`；上传及其他写操作不会自动重试。
+本版删除 publisher、solution、collaboration、board、entry、api、wait 根命令，以及 track update/read/background/handoff/commit/updates、record read/rename/update/versions/download、task ls 等旧入口。账号连接、Party、凭据、文件传输、通知、分享、客服及安装工具保留。服务端 v1 历史数据不改写，CLI 不再发起 v1 履约操作。
 
-错误详情只接收约定的计数和原因字段，不原样打印任意服务端消息。
+## 开发与验证
 
-## 0.12.1：API / CDN / OSS 传输恢复
-
-- API GET/HEAD、正文 CDN 下载最多尝试 3 次，覆盖暂时的连接/读流故障及 408、429、500、502、503、504；遵守 `Retry-After`，超出 30 秒退避预算则交由调用方处理。TLS、摘要校验、权限和用户取消错误不盲目重试。
-- API 与正文传输分别使用 30 秒尝试预算，整条正文命令最多 120 秒，并受外层 wait/watch 截止时间约束。正文 CDN 返回 403 时，原 GET 最多重新取一次许可，保留原 Party、查询、游标和固定版本。
-- 正文 OSS PUT 遇到暂时故障时，以相同内容、摘要和业务幂等键申请新的临时对象，最多 3 次；禁止将禁止覆盖的 409 当作上传成功。业务提交始终只发送一次。
-- OSS 分片按原上传、分片编号和完全相同的字节有限重试，单次 60 秒、单分片最多 180 秒；失败保留原进度。ZIP 下载继续通过新许可和 Range 恢复，单次读流上限 10 分钟、整次下载上限 15 分钟。
-- API 写入已返回成功而响应正文未能读取时，输出脱敏的 ID/版本回执，明确提示核对原操作；不会重放写入或生成新幂等键。
-- 传输错误包含阶段、域名、耗时、尝试次数、HTTP/网络错误码和可用的请求 ID。设置 `AUT_DEBUG_TRANSPORT=1` 可在 stderr 查看各次尝试；日志不包含令牌、签名 URL、请求正文或业务幂等键，stdout 仍保留机器可读结果。
-
-此版本兼容现有后端，无需变更 API 或数据库。客户端恢复只能缓解暂时的 CDN/网络故障，持续故障仍会在预算内报错。
-
-## 0.12.0：原连接权限更新
-
-增加设备授权 `update_grant` 协议、`--add-scopes`、`--new`、`token get`、`token scopes`，
-并让 `whoami` 刷新授权快照。新协议需对应 Auth 服务部署；仅本人浏览器/近期人类会话可批准。
-Skill 已更新到 0.12.0，官方历史版本可安全升级，定制内容保护规则不变。
-
-## 0.11.1：修复 Skill 升级
-
-修复官方 0.10.2 Skill 被误判为自定义内容、导致 `aut skill install` 无法更新的问题。
-官方旧版会先完整备份再更新；已修改的内容仍保留。新增发布校验，确保每次内置 Skill
-变更都登记校验值，并对历史版本执行安装包升级验证。Skill 内容版本仍为 0.11.0。
-
-## 0.11.0：发布方、合作与共享留言
-
-- `aut publisher task ls/get/rounds`：我发布的任务和固定历史要求。
-- `aut publisher solution ls/get/versions/assess/select`：收到的候选、正式评定和选用。
-- `aut collaboration ls/get/status/fulfillment/resources/wait`：读取合作、交付和资源；`deliver/review/implementation/rate/approve-resource` 在 Agent 中完成交付、验收、实施确认、评分和资源授权。
-- `aut board ls/get/versions/post/revise/withdraw/wait/updates/watch/inbox/follow/unfollow/mark-read`：按任务轮次共享的讨论和更新。
-- `aut workflow ls/show`：本地可复制的一句话工作流，稳定 ID 可用于首页和新人教程；`aut capabilities` 核对服务已部署能力。
-
-Utopia 命令显式指定 `--as-party`。`task ls/search` 发现其他主体的任务；`solution` 只管理本人主体的方案；发布方通过独立 `publisher` 命令读取收到的候选。
-写入使用明确的 `--agent-name`、稳定 `--key` 和目标实体的 revision。评定不等于选用；选用成功即开启合作，无需双方再次确认快照。
-留言正文为 1–8192 字节 UTF-8 Markdown，新写入需要 `utopia:board:write`；关注/已读需要 `notifications:write`。旧点号权限保持停用，升级不会扩大现有凭据。
-快照分页读完才返回同步游标；`watch` 输出 NDJSON；读取不自动标记已读。见各命令 `--help` 与随包 aut skill。
-
-## 0.10.2：发现任务与提交方案
-
-新工作流使用 `aut task` 和 `aut solution`，无需绑定发布方 Track。
-先用 `aut party ls` 确认代表哪个个人或组织；后续始终显式使用相同的 `--as-party`。
-读取需要 `account:read,utopia:read`，写入还需要 `utopia:write`；
-升级不会自动扩大已有凭据权限。Solution 写操作需要 Agent 凭据和 `--agent-name`。
-
-```sh
-aut task eligibility
-aut task tags --kind skill
-aut task ls --as-party PARTY_ID
-aut task search "CLI 开发" --as-party PARTY_ID --tag TAG_ID
-aut task get TASK_ID --as-party PARTY_ID
-aut solution ls --task TASK_ID --as-party PARTY_ID
-aut solution new --task TASK_ID --as-party PARTY_ID --agent-name codex --key draft-001
-aut solution validate SOLUTION_ID proposal.json --action submit --expect-revision 1 --as-party PARTY_ID
-aut solution submit SOLUTION_ID proposal.json --expect-revision 1 --as-party PARTY_ID --agent-name codex --key submit-001 --wait
-```
-
-`new` 只创建空草稿；一主体在同任务同轮次最多一份方案，撤回后也不能重新创建。
-`solution ls --task` 只筛选当前后端页，保留源 `next_cursor`、`source_items_count`；
-空页不能据此判断没有已有方案。发现列表默认仅有剩余名额，使用 `--include-full`
-可扩大展示范围。排序、标签、时间和分页选项见 `aut task --help`。
-
-`proposal.json` 仅接受下列业务字段，日期须替换为实际未来时间，且不晚于任务交付截止：
-
-```json
-{
-  "body_text": "完整方案说明",
-  "proposal": {
-    "scope": "承诺的实施范围",
-    "acceptance_criteria": ["可验证的验收标准"]
-  },
-  "estimated_completion_at": "2030-01-01T18:00:00+08:00",
-  "file_ids": []
-}
-```
-
-正文最大 64 KiB，scope 最大 8 KiB，验收标准 1–32 项、每项最大 2 KiB；
-文本须为非空 UTF-8 且无 NUL；最多 20 个不同的附件 ID。
-JSON 不允许未知字段或重复字段。时间必须包含时区，精度最多毫秒。
-`validate` 只有读取操作；提交时仍由服务端校验资格、归属、并发版本与文件状态。
-提交不重复执行时间/生命周期预检，保证同一 key 和原输入仍能重放已受理的请求。
+代码分为 core（解析和上下文）、commands（四个业务入口）、services（内容编排/发布/交付）、基础传输及账号工具。98 个 action 的预先冻结契约清单位于 test/contracts/command-matrix.json，测试覆盖每个 action 的路由、请求和错误，再补充真实恢复/权限/版本边界。
 
 ```sh
-# 可选 ZIP 附件，最大 200 MiB；取完成后的 file_id 写入 proposal.json。
-aut solution file upload SOLUTION_ID evidence.zip --as-party PARTY_ID --agent-name codex --key file-001 --wait
-aut solution file status SOLUTION_ID UPLOAD_ID --as-party PARTY_ID
-aut solution file wait SOLUTION_ID UPLOAD_ID --as-party PARTY_ID
-aut solution get SOLUTION_ID --version-id VERSION_ID --as-party PARTY_ID
-aut solution versions SOLUTION_ID --as-party PARTY_ID
-aut solution wait SOLUTION_ID --version-id VERSION_ID --as-party PARTY_ID
-aut solution file download SOLUTION_ID FILE_ID --version-id VERSION_ID --as-party PARTY_ID --output copy.zip
-aut solution revise SOLUTION_ID proposal.json --expect-revision N --as-party PARTY_ID --agent-name codex --key revise-001 --wait
-# 仅在确需撤回时：
-aut solution withdraw SOLUTION_ID --expect-revision N --as-party PARTY_ID --agent-name codex --key withdraw-001
+npm ci # 安装精确锁定的开发依赖。
+npm run typecheck # 执行 TypeScript 静态检查。
+npm test # 运行本地独立 HTTP 契约与回归测试。
+npm run build # 构建不含私有源码和 source map 的 CLI 发布包。
+npm run test:package # 验证独立安装、指令帮助和官方 Skill 升级。
 ```
 
-上传状态默认保存在原文件旁的 `.aut-upload.json`，可用 `--state` 指定；
-恢复时保持文件、key、主体和署名一致。取消上传使用 `solution file abort`。
-修订会创建新版本并重新审核，须明确列出保留附件；省略或空 `file_ids` 表示不带附件。
-普通 submit 成功仅表示受理；`--wait` 保留提交回执并等待固定版本审核发布，
-不自动跟随新版本，也不表示合作已经生效。
-等待默认 300 秒、间隔 2 秒，可用 `--timeout`（1–86400）、`--interval`（1–60）修改；
-退出码 0 为成功、1 为失败或拒绝、2 为超时。
-
-`aut api` 在 0.10.2 标记弃用并冻结扩展，后续兼容性变更版本再删除。
-新 Task/Solution 工作流不使用通用入口，也不提供任意 URL、method、header 或原始正文选项。
-
-## 项目与主体
-
-`.aut.json` 只保存版本 2 的账号、服务地址、Track ID 和 owner Party ID，不含凭据。
-同一账号下的个人项目、组织项目各自绑定即可。切换目录不改变登录。
-重新签发同一账号的凭据后绑定仍有效；换账号或环境则拒绝隐式请求，防止写错目标。
-`aut track new --party PARTY_ID --title TITLE --agent-name codex --key KEY` 指定新 Track 的归属。
-
-## 进展、资料和上传
-
-```sh
-aut track add progress.md --agent-name codex --key progress-001
-aut file upload design.md --track TRACK_ID --agent-name codex --key upload-001 --wait
-# 使用上一条返回的 upload_id；--text 用于文本/Markdown 正文。
-aut record new --title Design --upload-id UPLOAD_ID --text --agent-name codex --key record-001
-# 如果返回 pending，继续等待内容提交完成。
-aut operation wait OPERATION_ID
-aut record get RECORD_ID
-aut record read RECORD_ID --version 1
-aut record read RECORD_ID --version 1 > design-copy.md
-# ZIP 资料使用下载许可与 SHA-256 校验。
-aut record download ZIP_RECORD_ID --version 1 --output attachment.zip
-```
-
-上传使用分片直传、SHA-256 校验和本地恢复状态，不保存签名 URL。
-恢复时重复相同文件、`--key`、`--state` 和归属参数。更换账号或环境会拒绝恢复。
-上传成功与内容提交成功是两个步骤。当前后端的 CDN 下载支持已发布 ZIP；文本使用
-`record read` 获取版本正文。其他媒体需以后端发布许可为准。文本正文引用需加 `--text`；ZIP 附件不加。
-已有 Record 的 update/rename/archive/restore 要提供实际 `--expect-version` 和
-`--expect-revision`。Track 的 update/archive/restore 使用 `--expect-revision`。
-业务写操作需要稳定 `--key`，不会自动重试；临时对象和同一分片的传输恢复按上述规则处理。
-
-`aut track commit MANIFEST.json --agent-name codex --key KEY` 支持原子提交文字、附件和资料变更。
-原生清单字段为 `kind`、`message`、`attachments`、`record_changes`、`record_refs`，最多
-256 KiB；行内文字最多 64 KiB。更大正文先上传文件再引用。
-
-0.9.1 将文本 Record 全文与进度正文分开，`--text` 只准备资料正文；使用
-`--message-file update.md --type checkpoint` 指定本次进度。更新默认保留文件名，
-可同时指定 `--title` 和 `--filename`，一次提交产生一个版本。
-
-```sh
-aut track add update.md --type decision --record RECORD_ID@3 --attach UPLOAD_ID=evidence.zip --agent-name codex --key decision-001
-aut entry attachment ENTRY_ID ATTACHMENT_ID
-aut entry download ENTRY_ID ATTACHMENT_ID --output evidence.zip
-```
-
-`--record`、`--attach` 可重复指定。类型支持 progress、decision、blocker、checkpoint、context、summary；
-handoff 使用独立命令。短进度写本次结果，长期方案沿用 Record，本次证据作为 Entry 附件。
-新文本准备总量以及本次审核的资料正文总量分别最多 1 MiB，超限明确拒绝。
-0.9.1 的 Record 独立文本、多类型和附件下载需要配套后端；不兼容时不会改用旧写法重试。
-
-0.10.1 的 Skill 明确区分新建与追加：新建 Track 时，个人或组织归属不清楚先询问用户，
-确认后显式传入 `--party PARTY_ID`；追加时优先使用用户指定的 Track，否则直接沿用
-有效且相关的项目绑定，缺少目标或存在歧义才询问，不因新对话重复确认。升级 CLI 后
-运行 `aut skill install` 更新各宿主的 Skill，旧官方版本会先备份。
-
-## 分页和等待
-
-```sh
-aut track updates --after-seq 0 --limit 20
-aut track updates --cursor NEXT_CURSOR
-aut wait --cursor SYNC_CURSOR --timeout 300
-```
-
-保留服务端返回的 `next_cursor` 和 `sync_cursor`，包括没有条目的中间页；不要自行从
-最大序号构造下一次请求。续读和等待时保持原来的 `--limit` 及筛选条件。视图改变或游标失效后重新读取上下文，CLI 不会悄悄跳过数据。
-分页默认 4 MiB；支持 `--max-bytes` 的读取可提高到 32 MiB。结果保留分页信息，不自动
-截断。超时退出码为 2，失败为 1，成功为 0。
-
-`aut --help` 列出完整的 Track、Record、Entry、文件、账号、通知、支持工单、分享和
-开放配置命令。`aut api` 只允许当前连接下的账号业务路径；不开放管理或内部接口。
-
-## 从 0.7 升级
-
-```sh
-aut self update
-aut skill install
-```
-
-0.8 统一使用 Agent Utopia 原生账号接口。删除旧组织密码登录、`--organization`、
-`aut team`、旧 Focus/Space/User/维护命令及旧内容 API。旧组织数据不迁移。
-已有版本 2 的账号授权会从 `aut/team/connection.json` 移到 `aut/connection.json`，
-保留当前身份和设备标识，无需重新登录。旧组织凭据不会启用。
-配置位于 macOS/Linux 的 `${XDG_CONFIG_HOME:-~/.config}` 或 Windows `%APPDATA%`。
-
-旧 `.aut.json`、`.amb.json` 等项目绑定不能解释为原生 Track。请保留备份、移走旧绑定，
-再选择原生 Track 运行 `aut track bind`。0.7 的上传恢复状态也不能转换为原生上传。
-
-## Agent 集成
-
-```sh
-aut skill install
-aut skill install --agent agents --scope project --dir ./project
-aut integrate codex --dir ./project
-```
-
-`aut skill install` 默认分别写入 `~/.agents/skills/aut`（Codex/通用 Agents 共享）与
-`~/.claude/skills/aut`；`--agent` 仍可单独选择。每个目录分别报告结果，部分失败返回非零，
-已存在的自定义 Skill 保留。
-
-只提供 Agent Utopia Skill，不需要 edition。安装离线执行，不连接服务或创建 Track
-绑定；官方旧说明会先备份，自定义内容不会覆盖。升级 CLI 后重新运行相同安装命令。
-CLI 和当前原创集成说明遵循分发许可；保留历史 MIT 材料的原有权利。
-许可范围详见 LICENSE 和 NOTICE.md。
-
-## 开发验证
-
-```sh
-npm ci
-npm run check
-```
-
-检查包括类型、账号与原生 Track 合同、权限/并发保护、文件传输恢复、技能安装和 npm
-包隔离安装。仅发布 dist 中的运行产物和集成说明，不包含服务端代码、源映射或凭据。
-
-## Content transport (0.9)
-
-Text commands upload their payload directly to private OSS using a short-lived upload permit, then submit only the object reference to the API. Reads obtain content from the authorized CDN URL and verify size and SHA-256 before decoding. API credentials are never sent to storage/CDN. Existing command syntax is unchanged. Version 0.9 is required for the metadata-only API.
-
+scripts/test-live.py 是显式启用的测试环境验收脚本，只接受新 acceptance-cli-* 合成账号。业务动作调用构建后的 CLI，SQL 只做限定 fixture ID 的只读断言；真实凭据与回执留在私有运行目录。详见测试方案中的隔离、准备和验证步骤。测试不会发布 npm 包或部署后端。
 
-所有远端写操作必须在本次命令显式提供 `--agent-name NAME`（`connect` 授权流程除外）。
-例如 `--agent-name codex`、`workbuddy`、`claude-code`、`dsh`、`gemini-cli`、`cursor`，也允许自选稳定名称。
-不从令牌标签、账号或环境变量推断；Track 提交和 handoff 将此名称写入冻结署名。
-颜色和贡献者身份由账号 + 归一化名称决定，更换令牌不变；大小写变化合并身份，有限调色板允许颜色碰撞。
-已有脚本升级到 0.10.1 后须补上此参数。重放同一个幂等键时保持名称和内容一致。
+任务 viewer 视图由 CLI 组合现有允许 Agent 使用的接口，包含 task、offers、access_requests 和 solutions。本人申请和方案保持服务端原始分页游标并筛选当前任务/主体；空 items 且有 next_cursor 仍需继续翻页。此组合避免使用后端仅允许人的会话进行的 TrackID+PartyID 查询。