aut-cli 0.7.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/NOTICE.md +2 -2
- package/README.md +77 -141
- package/dist/cli.js +85 -149
- package/dist/integrations/AGENTS.snippet.md +15 -27
- package/dist/integrations/checkpoint.md +9 -13
- package/dist/integrations/skills/aut/SKILL.md +113 -65
- package/package.json +1 -1
package/NOTICE.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# Notices
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Agent Utopia CLI application sources are proprietary. Official, unmodified distributions
|
|
4
4
|
may be installed and used for personal and commercial purposes under `LICENSE`.
|
|
5
5
|
Publishing the compressed runtime on npm does not publish the TypeScript source
|
|
6
|
-
or grant a license to that private source. This package operates
|
|
6
|
+
or grant a license to that private source. This package operates the Agent Utopia account and native Track APIs.
|
|
7
7
|
|
|
8
8
|
New original integration documentation follows the distribution license, with
|
|
9
9
|
permission to copy and adapt it privately for agent/project configuration.
|
package/README.md
CHANGED
|
@@ -1,187 +1,123 @@
|
|
|
1
1
|
# aut-cli
|
|
2
2
|
|
|
3
|
-
Agent Utopia
|
|
3
|
+
Agent Utopia 的账号命令行客户端。个人主体和组织主体使用同一个账号授权；
|
|
4
|
+
不同项目目录可以绑定不同主体的原生 Track，无需切换登录。
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## 安装与连接
|
|
6
|
+
需要 Node.js 22 或更高版本。
|
|
8
7
|
|
|
9
8
|
```sh
|
|
10
9
|
npm install -g aut-cli
|
|
11
|
-
aut
|
|
12
|
-
aut --help
|
|
13
|
-
aut skill install --agent codex
|
|
14
|
-
# Claude Code 改用 --agent claude-code；其他兼容宿主可用 --agent agents
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
在网页当前空间的“接入 Agent”入口复制连接命令。推荐浏览器授权；默认 `--auth browser` 使用账号级授权；需要旧组织工作台时才显式指定 `--organization ID`：
|
|
18
|
-
|
|
19
|
-
```sh
|
|
20
|
-
aut connect https://your-gateway.example --device "My Agent"
|
|
10
|
+
aut connect https://api.test.snapcoach.cn
|
|
21
11
|
aut status --json
|
|
22
12
|
aut whoami --json
|
|
13
|
+
aut party ls
|
|
14
|
+
aut track ls --party PARTY_ID
|
|
15
|
+
aut track bind TRACK_ID
|
|
16
|
+
aut track read
|
|
23
17
|
```
|
|
24
18
|
|
|
25
|
-
|
|
19
|
+
默认浏览器授权为只读：`account:read,track:read,notifications:read`。
|
|
20
|
+
需要写入时明确申请，例如：
|
|
26
21
|
|
|
27
22
|
```sh
|
|
28
|
-
aut connect
|
|
23
|
+
aut connect https://api.test.snapcoach.cn --scopes account:read,track:read,track:write,notifications:read
|
|
29
24
|
```
|
|
30
25
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
`aut status --json` 只检查本地配置，返回 `configured`、`target_policy: "active-only"`、`edition: "team"`、CLI 版本及已配置目标；`aut whoami --json` 才验证服务端身份和权限。命令只使用当前 Team 连接，禁止业务 URL 或旧 Solo 环境凭据选择其他来源。旧 `AMB_URL`、`AMB_TOKEN`、`AMB_SOLO_*` 和 Solo 配置不会迁移或作为回退来源。
|
|
26
|
+
支持 `--resource-mode selected_tracks --track-ids ID1,ID2` 限定授权范围。
|
|
27
|
+
已有账号凭据可通过 `--auth token --token-stdin` 导入；不要把凭据放在命令参数中。
|
|
28
|
+
服务端始终检查账号、授权范围和 Track 当前权限。
|
|
36
29
|
|
|
37
|
-
|
|
30
|
+
## 项目与主体
|
|
38
31
|
|
|
39
|
-
|
|
32
|
+
`.aut.json` 只保存版本 2 的账号、服务地址、Track ID 和 owner Party ID，不含凭据。
|
|
33
|
+
同一账号下的个人项目、组织项目各自绑定即可。切换目录不改变登录。
|
|
34
|
+
重新签发同一账号的凭据后绑定仍有效；换账号或环境则拒绝隐式请求，防止写错目标。
|
|
35
|
+
`aut track new --party PARTY_ID --title TITLE --key KEY` 指定新 Track 的归属。
|
|
40
36
|
|
|
41
|
-
|
|
37
|
+
## 进展、资料和上传
|
|
42
38
|
|
|
43
39
|
```sh
|
|
44
|
-
aut
|
|
45
|
-
aut
|
|
46
|
-
|
|
47
|
-
aut
|
|
48
|
-
|
|
49
|
-
aut
|
|
50
|
-
aut
|
|
51
|
-
aut
|
|
52
|
-
aut
|
|
53
|
-
|
|
40
|
+
aut track add progress.md --key progress-001
|
|
41
|
+
aut file upload design.md --track TRACK_ID --key upload-001 --wait
|
|
42
|
+
# 使用上一条返回的 upload_id；--text 用于文本/Markdown 正文。
|
|
43
|
+
aut record new --title Design --upload-id UPLOAD_ID --text --key record-001
|
|
44
|
+
# 如果返回 pending，继续等待内容提交完成。
|
|
45
|
+
aut operation wait OPERATION_ID
|
|
46
|
+
aut record get RECORD_ID
|
|
47
|
+
aut record read RECORD_ID --version 1
|
|
48
|
+
aut record read RECORD_ID --version 1 > design-copy.md
|
|
49
|
+
# ZIP 资料使用下载许可与 SHA-256 校验。
|
|
50
|
+
aut record download ZIP_RECORD_ID --version 1 --output attachment.zip
|
|
54
51
|
```
|
|
55
52
|
|
|
56
|
-
|
|
53
|
+
上传使用分片直传、SHA-256 校验和本地恢复状态，不保存签名 URL。
|
|
54
|
+
恢复时重复相同文件、`--key`、`--state` 和归属参数。更换账号或环境会拒绝恢复。
|
|
55
|
+
上传成功与内容提交成功是两个步骤。当前后端的 CDN 下载支持已发布 ZIP；文本使用
|
|
56
|
+
`record read` 获取版本正文。其他媒体需以后端发布许可为准。文本正文引用需加 `--text`；ZIP 附件不加。
|
|
57
|
+
已有 Record 的 update/rename/archive/restore 要提供实际 `--expect-version` 和
|
|
58
|
+
`--expect-revision`。Track 的 update/archive/restore 使用 `--expect-revision`。
|
|
59
|
+
写操作需要稳定 `--key`，不会自动重试。
|
|
57
60
|
|
|
58
|
-
|
|
61
|
+
`aut track commit MANIFEST.json --key KEY` 支持原子提交文字、附件和资料变更。
|
|
62
|
+
原生清单字段为 `message`、`attachments`、`record_changes`、`record_refs`，最多
|
|
63
|
+
256 KiB；行内文字最多 64 KiB。更大正文先上传文件再引用。
|
|
59
64
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
## 项目与 Track
|
|
65
|
+
## 分页和等待
|
|
63
66
|
|
|
64
67
|
```sh
|
|
65
|
-
aut
|
|
66
|
-
aut track
|
|
67
|
-
aut
|
|
68
|
-
aut track bind TRACK_ID --dir /path/to/project
|
|
69
|
-
aut track read TRACK_ID --json
|
|
70
|
-
aut track entries TRACK_ID --after-seq 0 --limit 50 --max-bytes 4194304 --json
|
|
68
|
+
aut track updates --after-seq 0 --limit 20
|
|
69
|
+
aut track updates --cursor NEXT_CURSOR
|
|
70
|
+
aut wait --cursor SYNC_CURSOR --timeout 300
|
|
71
71
|
```
|
|
72
72
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
73
|
+
保留服务端返回的 `next_cursor` 和 `sync_cursor`，包括没有条目的中间页；不要自行从
|
|
74
|
+
最大序号构造下一次请求。续读和等待时保持原来的 `--limit` 及筛选条件。视图改变或游标失效后重新读取上下文，CLI 不会悄悄跳过数据。
|
|
75
|
+
分页默认 4 MiB；支持 `--max-bytes` 的读取可提高到 32 MiB。结果保留分页信息，不自动
|
|
76
|
+
截断。超时退出码为 2，失败为 1，成功为 0。
|
|
76
77
|
|
|
77
|
-
|
|
78
|
+
`aut --help` 列出完整的 Track、Record、Entry、文件、账号、通知、支持工单、分享和
|
|
79
|
+
开放配置命令。`aut api` 只允许当前连接下的账号业务路径；不开放管理或内部接口。
|
|
78
80
|
|
|
79
|
-
|
|
80
|
-
aut track add TRACK_ID summary.md --type progress --agent codex --expect-seq LAST_READ_SEQ --key UNIQUE_KEY
|
|
81
|
-
aut wait TRACK_ID --after-seq LAST_READ_SEQ --type decision --interval 60 --timeout 600
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
`--expect-seq` 是本次实际读到的最高序号，不能取未读的 `last_seq`；`--key` 对同一逻辑写入保持稳定。`wait` 为普通 HTTP 轮询，不执行 shell：退出码 0 匹配、2 超时、130 取消；按返回 `next_seq` 继续，不保存隐式游标。每次写前重新核对相同目标并读完新增内容。冲突先重读合并；超时先查结果，确需重试时复用原 key、正文和预期序号。
|
|
85
|
-
|
|
86
|
-
## Record 与协作
|
|
81
|
+
## 从 0.7 升级
|
|
87
82
|
|
|
88
83
|
```sh
|
|
89
|
-
aut
|
|
90
|
-
aut
|
|
91
|
-
aut record save RECORD_ID document.md --title "设计文档" --expect-version VERSION --key UNIQUE_KEY
|
|
92
|
-
aut record references RECORD_ID
|
|
93
|
-
aut record backlinks RECORD_ID
|
|
84
|
+
aut self update
|
|
85
|
+
aut skill install --agent codex
|
|
94
86
|
```
|
|
95
87
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
## 内容与读取限制
|
|
103
|
-
|
|
104
|
-
上限按 UTF-8 字节计算，1 MiB = 1,048,576 字节。CLI 提前检查，服务端独立强校验；不静默截断、跳页、拆分或重试写入。
|
|
88
|
+
0.8 统一使用 Agent Utopia 原生账号接口。删除旧组织密码登录、`--organization`、
|
|
89
|
+
`aut team`、旧 Focus/Space/User/维护命令及旧内容 API。旧组织数据不迁移。
|
|
90
|
+
已有版本 2 的账号授权会从 `aut/team/connection.json` 移到 `aut/connection.json`，
|
|
91
|
+
保留当前身份和设备标识，无需重新登录。旧组织凭据不会启用。
|
|
92
|
+
配置位于 macOS/Linux 的 `${XDG_CONFIG_HOME:-~/.config}` 或 Windows `%APPDATA%`。
|
|
105
93
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
| Record、Entry、背景、每份附件 | 每份 1 MiB；严格 UTF-8，拒绝 NUL；文件拒绝符号链接/目录/特殊文件，stdin 有界读取 |
|
|
109
|
-
| Entry 附件 | 最多 5 份，仅 md/html |
|
|
110
|
-
| 完整 JSON 请求/JSON 文件输入 | 2 MiB，包含信封、元信息和转义；单项都合格不代表合并后合格 |
|
|
111
|
-
| 普通列表/搜索/元信息 | 响应最多 4 MiB；limit 为 1–200，不接受 max-bytes |
|
|
112
|
-
| Track entries/read/wait | max-bytes 默认 4 MiB、范围 1 KiB–32 MiB，计完整 JSON 响应；按 next_seq/has_more 连续分页 |
|
|
113
|
-
| 单篇内容/raw 下载 | 最多 32 MiB |
|
|
114
|
-
| 维护归档 | ZIP 每份 16 MiB；manifest 8 MiB；完整备份最多 10,000 段 |
|
|
94
|
+
旧 `.aut.json`、`.amb.json` 等项目绑定不能解释为原生 Track。请保留备份、移走旧绑定，
|
|
95
|
+
再选择原生 Track 运行 `aut track bind`。0.7 的上传恢复状态也不能转换为原生上传。
|
|
115
96
|
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
错误包括 `content_too_large`、`request_too_large`、`response_too_large`、`too_many_documents`、`unsupported_content_format`、`invalid_content_encoding`、`archive_too_large`；修正后再提交，限流遵守 `Retry-After`。CLI 不扫描秘密或自动脱敏，发送者应移除凭据和无关敏感内容。
|
|
119
|
-
|
|
120
|
-
## Skill 更新
|
|
121
|
-
|
|
122
|
-
唯一 Skill 名称为 `aut`。默认安装 Team，无需 edition；`--edition team` 仅兼容同一安装路径，`--edition solo`/`auto` 报错。Codex/agents 用户级目录为 `~/.agents/skills/aut`，Claude Code 为 `~/.claude/skills/aut`。项目副本使用：
|
|
97
|
+
## Agent 集成
|
|
123
98
|
|
|
124
99
|
```sh
|
|
125
|
-
aut skill install --agent codex
|
|
100
|
+
aut skill install --agent codex
|
|
101
|
+
aut skill install --agent claude-code
|
|
102
|
+
aut skill install --agent agents --scope project --dir ./project
|
|
103
|
+
aut integrate codex --dir ./project
|
|
126
104
|
```
|
|
127
105
|
|
|
128
|
-
|
|
106
|
+
只提供 Agent Utopia Skill，不需要 edition。安装离线执行，不连接服务或创建 Track
|
|
107
|
+
绑定；官方旧说明会先备份，自定义内容不会覆盖。升级 CLI 后重新运行相同安装命令。
|
|
108
|
+
CLI 和当前原创集成说明遵循分发许可；保留历史 MIT 材料的原有权利。
|
|
109
|
+
许可范围详见 LICENSE 和 NOTICE.md。
|
|
129
110
|
|
|
130
|
-
##
|
|
111
|
+
## 开发验证
|
|
131
112
|
|
|
132
113
|
```sh
|
|
133
|
-
|
|
134
|
-
|
|
114
|
+
npm ci
|
|
115
|
+
npm run check
|
|
135
116
|
```
|
|
136
117
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
有私有仓库权限的维护者使用 `npm ci`、`npm run check`、`npm pack`。检查包含类型、隔离本机 HTTP/CLI 测试、压缩构建与本地离线安装包测试。公开包文件有严格白名单；不含旧 Solo 运行时、第二套 Skill、session hook、服务端代码、source map 或 sourcesContent。JavaScript 运行产物可下载读取，闭源不等于产物不可见。`prepack` 重新构建与检查，`prepublishOnly` 执行类型与测试；本仓库不会自动发布。
|
|
140
|
-
|
|
141
|
-
## 异步文件
|
|
142
|
-
|
|
143
|
-
当前后端接入 Record 附件。ZIP 最大 200 MiB，仅校验大小和 SHA256，不解压或审核 ZIP 内的内容。
|
|
144
|
-
|
|
145
|
-
```bash
|
|
146
|
-
aut file upload bundle.zip --party ORGANIZATION_ID --purpose record --subject-type record --subject RECORD_ID --key STABLE_KEY --wait
|
|
147
|
-
aut operation wait OPERATION_ID --timeout 300
|
|
148
|
-
aut file get FILE_ID
|
|
149
|
-
aut file download FILE_ID --output new-bundle.zip
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
上传使用 OSS 分片直传，进度保存在 `FILE.aut-upload.json`；网络中断后以相同参数重试，只补传剩余分片。`accepted` 表示服务端已受理，必须等待 operation 成功。下载流式校验大小和 SHA256 后才生成最终文件，不覆盖已存在路径。命令不会把 API 凭证发送给 OSS。媒体用途仍需等待后端审核链路完成。
|
|
153
|
-
|
|
154
|
-
### Party 与代表委托
|
|
155
|
-
|
|
156
|
-
`aut party ls` 需要账号级连接，返回个人及当前有效组织的 Party，`aut party get PARTY_ID` 查看身份和能力。委托管理需要凭据的 `organization:manage` scope（默认连接是只读，需要显式授权）；当前组织 owner/admin 可以用 `aut party delegate PARTY_ID delegation.json --key STABLE_KEY --expect-revision N` 授予成员 `publish` / `share` 能力；JSON 中填写 `account_id`、`capabilities`、`track_ids` 和可选的 `expires_at`。空 `track_ids` 代表不限 Track。
|
|
157
|
-
|
|
158
|
-
`aut party delegations PARTY_ID --limit 50` 按响应 `next_cursor` 通过 `--cursor` 翻页。创建使用 Party 的 revision；`aut party revoke DELEGATION_ID --key STABLE_KEY --expect-revision N` 使用委托自身 revision。委托绑定成员代次，成员退出后重新加入不会恢复旧权限。Party 能力不代表已通过 Utopia 双验证和付费准入或内容 ACL。委托 JSON 不允许覆盖命令的幂等键/版本；撤销也必须提供稳定 --key。版本号按 uint64 精确传输，组织凭据不会被隐式升级。
|
|
159
|
-
|
|
160
|
-
### 0.4.0 文件下载协议
|
|
161
|
-
|
|
162
|
-
`aut file download` 需要支持 CDN 许可 JSON 的服务端。CLI 先通过已登录 API 获取短期许可，再向独立 HTTPS 文件域名直接下载；不会将平台 Authorization、Cookie 或 Referer 发送给文件域名。响应长度、Range 和最终 SHA256 全部通过后才创建目标文件，已有文件不会被覆盖。
|
|
163
|
-
|
|
164
|
-
同一次命令内连接中断或短链失效会先重新请求业务许可，再按已写入字节续传，最多尝试三次；撤销权限后停止，不保存临时下载 URL。跨进程下载续传尚未支持。上传继续使用独立 OSS 分片请求和原有持久化续传记录，遵守服务端的 `required_headers`。0.3.0 的 API 字节下载接口与 0.4.0 协议不能混用，服务端和安装包需一起切换。
|
|
165
|
-
|
|
166
|
-
## 0.7.0 support commands
|
|
167
|
-
|
|
168
|
-
`aut support` uses the account profile and the Platform F07 API. Read commands
|
|
169
|
-
require `support:read`; mutations also require `support:write`, with `all_visible`
|
|
170
|
-
authority. Existing profiles and their scopes are never expanded automatically.
|
|
118
|
+
检查包括类型、账号与原生 Track 合同、权限/并发保护、文件传输恢复、技能安装和 npm
|
|
119
|
+
包隔离安装。仅发布 dist 中的运行产物和集成说明，不包含服务端代码、源映射或凭据。
|
|
171
120
|
|
|
172
|
-
|
|
173
|
-
- `aut support get TICKET_ID`
|
|
174
|
-
- `aut support create JSON_FILE --key KEY`
|
|
175
|
-
- `aut support submit TICKET_ID --expect-revision N --key KEY`
|
|
176
|
-
- `aut support messages TICKET_ID [--cursor CURSOR] [--limit 50]`
|
|
177
|
-
- `aut support message TICKET_ID TEXT_FILE --expect-revision N --key KEY`
|
|
178
|
-
- `aut support reopen TICKET_ID REASON_FILE --expect-revision N --key KEY`
|
|
121
|
+
## Content transport (0.9)
|
|
179
122
|
|
|
180
|
-
|
|
181
|
-
`delivery_dispute` (the collaboration ID). Other kinds currently accept free-text
|
|
182
|
-
support requests without business references. `processing_delay` is server-owned.
|
|
183
|
-
Explanations are bounded UTF-8 files of at most 8192 bytes; `-` reads stdin.
|
|
184
|
-
Messages go to support under server-controlled visibility. These commands do not
|
|
185
|
-
upload new deliverables, select another user's inbox, or execute staff rulings.
|
|
186
|
-
Writes require a stable key and are never retried automatically. Revisions retain
|
|
187
|
-
their full uint64 precision.
|
|
123
|
+
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.
|