@agentunion/fastaun-browser 0.4.13 → 0.5.1

package/_packed_docs/cli/CLI/346/211/213/345/206/214.md

@@ -0,0 +1,331 @@
+# AUN CLI 手册
+
+## 位置与入口
+
+AUN CLI 是 Python SDK 的命令行工具，源码位于：
+
+```text
+D:\modelunion\kite\aun-sdk-core\python\src\aun_cli
+```
+
+仓库内相对路径为 `python/src/aun_cli`。安装入口在 `python/pyproject.toml`：
+
+```toml
+[project.scripts]
+aun = "aun_cli.main:app"
+```
+
+开发环境可直接运行：
+
+```powershell
+cd D:\modelunion\kite\aun-sdk-core\python
+pip install -e .
+aun --help
+```
+
+也可以不安装包，直接指定 `PYTHONPATH`：
+
+```powershell
+$env:PYTHONPATH="D:\modelunion\kite\aun-sdk-core\python\src"
+python -m aun_cli --help
+```
+
+## 全局用法
+
+```text
+aun [全局选项] <command> [参数]
+```
+
+全局选项：
+
+| 选项 | 说明 |
+|------|------|
+| `--profile, -p` | 仅本次命令使用指定 profile |
+| `--json` | 输出 JSON，适合脚本 |
+| `--debug` | 启用 debug 日志 |
+| `--no-color` | 禁用彩色输出 |
+| `--timeout, -t` | 操作超时秒数，默认 30 |
+| `--version, -V` | 显示版本 |
+| `--install-completion` | 安装当前 shell 的补全脚本，Typer 自动提供 |
+| `--show-completion` | 输出补全脚本，Typer 自动提供 |
+| `--help` | 显示帮助 |
+
+CLI 不提供 `--gateway` 选项；Gateway 发现由 SDK 处理。
+
+非 JSON 模式会先打印当前 `profile`、`aid`、`active_group` 和 `trace`，命令结束时可能输出 RPC summary。脚本里建议使用 `--json`。
+
+## 配置与 Profile
+
+默认配置文件为 `~/.aun/cli.toml`。常用命令：
+
+```powershell
+aun profile create dev --aid alice.agentid.pub
+aun profile switch dev
+aun profile current
+aun profile list
+
+aun config set timeout 60
+aun config get timeout
+aun config list
+```
+
+`profile` 也挂在 `config` 下，`aun config profile list/current/create/switch` 与根级 `aun profile ...` 使用同一套实现。
+
+当前 profile 的核心字段：
+
+| 字段 | 说明 |
+|------|------|
+| `aid` | 默认操作身份 |
+| `aun_path` | 本地身份、密钥、日志等数据目录 |
+| `active_group` | 默认群组；省略 group_id 时使用 |
+| `debug` / `trace` / `timeout` | 调试、trace 和超时配置 |
+
+有效 profile 选择顺序：
+
+```text
+--profile > AUN_PROFILE > 当前终端标签页状态 > default.profile
+```
+
+## 身份命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun register <aid>` | 注册新 AID，并写入当前 profile |
+| `aun login [aid]` | 加载本地身份、认证并连接一次 |
+| `aun whoami` | 查看当前 profile / AID / 数据目录 |
+| `aun identity list` | 列出本地身份 |
+| `aun identity check <aid>` | 检查本地身份材料和远端注册状态 |
+
+示例：
+
+```powershell
+aun register alice.agentid.pub
+aun login alice.agentid.pub
+aun whoami
+aun identity check alice.agentid.pub
+```
+
+## P2P 消息命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun send <target-aid> <message>` | 发送 P2P 消息，默认加密 |
+| `aun send <target-aid> -` | 从 stdin 读取消息 |
+| `aun pull [--from aid] [--limit N] [--after-seq N]` | 拉取离线消息 |
+| `aun ack <sender-aid> --seq N` | 确认消息 seq |
+| `aun listen [--from aid] [--group group_id]` | 实时监听 P2P 和群消息 |
+
+示例：
+
+```powershell
+aun send bob.agentid.pub "hello"
+Get-Content .\msg.txt | aun send bob.agentid.pub -
+aun pull --limit 20
+aun listen --from bob.agentid.pub
+```
+
+## 群组命令
+
+| 命令 | 用法 |
+|------|------|
+| `aun group create <name> [--members a,b] [--group-name name]` | 创建群；成功后自动设为 active group |
+| `aun group use <group-id>` | 设置当前 active group |
+| `aun group current` | 查看当前 active group |
+| `aun group send [group-id] <message>` | 发送群消息；省略 group-id 时使用 active group |
+| `aun group list` | 列出已加入群 |
+| `aun group info [group-id]` | 查看群详情 |
+| `aun group members [group-id]` | 查看成员 |
+| `aun group invite [group-id] <aid...>` | 邀请成员 |
+| `aun group add-member [group-id] <aid> [--role member|admin]` | 直接添加成员 |
+| `aun group kick [group-id] <aid>` | 移除成员 |
+| `aun group leave [group-id]` | 退出群 |
+| `aun group dissolve [group-id]` | 解散群 |
+| `aun group bind [group-id] [--group-name name]` | 为匿名群补齐 group_aid；`bind-aid` 是公开别名 |
+| `aun group transfer [group-id] <new-owner>` | 转移群主 |
+| `aun group complete-transfer [group-id]` | 完成转让后的 group.fs rekey |
+
+`aun group add_member` 是 `aun group add-member` 的公开兼容别名。
+
+示例：
+
+```powershell
+aun group create "项目讨论组" --members bob.agentid.pub,carol.agentid.pub
+aun group current
+aun group send "大家好"
+aun group members
+aun group add-member dave.agentid.pub --role member
+```
+
+## 群文件系统命令
+
+`aun group fs` 对应 `group.fs.*` 和 SDK `client.group.fs`。裸路径使用当前 active group；完整 group path 也可直接传入。
+
+| 命令 | 用法 |
+|------|------|
+| `aun group fs ls [path] [-l]` | 列出目录 |
+| `aun group fs find [path] [--name "*.md"] [--type f]` | 查找节点 |
+| `aun group fs stat <path>` | 查看节点 |
+| `aun group fs lstat <path>` | 查看链接本身 |
+| `aun group fs mkdir <path> [-p]` | 创建目录 |
+| `aun group fs rm <path> [-r] [--force]` | 删除节点 |
+| `aun group fs cp <src> <dst> [-r] [--force]` | 上传、下载或远程复制 |
+| `aun group fs mv <src> <dst> [--force]` | 远程移动 |
+| `aun group fs df [path]` | 查看用量 |
+| `aun group fs setfacl <path> -m role:admin:<perms>` | 群主授予群自有区 admin 角色 ACL |
+| `aun group fs setfacl <path> -x role:admin` | 群主撤销群自有区 admin 角色 ACL |
+| `aun group fs getfacl <path>` | 查看群自有区角色 ACL |
+| `aun group fs mount <path> [--readonly/--readwrite]` | 挂载成员数据区 |
+| `aun group fs umount <path>` | 卸载成员数据区 |
+
+示例：
+
+```powershell
+aun group fs mkdir /docs -p
+aun group fs cp .\README.md /docs/README.md
+aun group fs ls /docs -l
+aun group fs setfacl /docs -m role:admin:rwx
+aun group fs getfacl /docs
+aun group fs cp /docs/README.md .\downloaded.md
+```
+
+群自有区写入需要使用当前 `group_identity` 对应的 `group_aid` 身份签名时，可通过 `--as <group-aid>` 指定操作者。`setfacl/getfacl` 只允许当前 group owner 调用；当前只支持 `role:admin` 角色 ACL，权限位对外显示为 POSIX 视图 `rwx`。
+
+## Storage VFS 命令
+
+`aun fs` 是普通 Storage VFS 入口，路径格式为 `<AID>:/path`。裸路径自动使用当前 profile AID。
+
+| 命令 | 用法 |
+|------|------|
+| `aun fs ls <path> [-l]` | 列目录 |
+| `aun fs stat <path> [-L]` | 查看节点，`-L` 跟随链接 |
+| `aun fs cat <path>` | 输出文件内容 |
+| `aun fs cp <src> <dst>` | 本地/远程上传下载或远程复制 |
+| `aun fs mv <src> <dst>` | 同 AID 内原子移动 |
+| `aun fs rm <path> [-r]` | 删除 |
+| `aun fs ln -s <target> <link-path>` | 创建软链 |
+| `aun fs mkdir <path> [-p]` | 创建目录 |
+| `aun fs touch <path> [-p] [--no-create] [--mtime TS]` | 创建空文件或更新时间戳 |
+| `aun fs df <aid:>` | 查看用量 |
+| `aun fs quota [aid:]` | 查看配额 |
+| `aun fs du <path> [-h] [--max-depth N]` | 汇总路径占用 |
+| `aun fs find <path> [--name PATTERN] [--type f|d|l]` | 查找 |
+| `aun fs chmod +r <path>` / `aun fs chmod o-r <path>` | 设置 public/private |
+| `aun fs setfacl <path> -m aid:<AID>:<perms>` / `-x aid:<AID>` | 设置或移除 ACL |
+| `aun fs getfacl <path>` | 查看 ACL |
+| `aun fs mount/approve/reject/umount ...` | 挂载生命周期 |
+| `aun fs token issue/revoke/ls ...` | 访问 token 管理 |
+
+示例：
+
+```powershell
+aun fs mkdir alice.agentid.pub:/docs -p
+aun fs touch alice.agentid.pub:/docs/empty.txt --mtime 1700000000
+aun fs cp .\a.txt alice.agentid.pub:/docs/a.txt
+aun fs cat alice.agentid.pub:/docs/a.txt
+aun fs token issue alice.agentid.pub:/docs/a.txt
+```
+
+## 对象存储兼容命令
+
+`aun storage` 是对象级快捷入口，适合低层调试和兼容旧用法：
+
+```powershell
+aun storage ls docs/
+aun storage info docs/a.txt
+aun storage upload .\a.txt --name docs/a.txt --force
+aun storage download docs/a.txt -o .\a.txt --force
+aun storage delete docs/a.txt
+```
+
+新应用优先使用 `aun fs`。
+
+## Collab 命令
+
+`aun collab` 操作版本化协作目录：
+
+| 命令 | 用法 |
+|------|------|
+| `aun collab ls-files <collab-root>` | 列出文档 |
+| `aun collab create <root> <doc> <source>` | 创建文档 |
+| `aun collab show <root> <doc> [--rev N] [-o file]` | 查看版本 |
+| `aun collab commit <root> <doc> <source> --onto N` | 提交版本 |
+| `aun collab merge <root> <doc> <source> --onto N` | 三方合并 |
+| `aun collab log <root> <doc>` | 历史 |
+| `aun collab diff <root> <doc> --from A --to B` | 差异 |
+| `aun collab revert <root> <doc> --rev N` | 回退 |
+| `aun collab clone <src> <dest> [--reroot]` | 克隆 |
+| `aun collab prune/gc/reflog ...` | 清理和审计 |
+| `aun collab ls-remote <group-aid>` | 列群内协作目录 |
+| `aun collab unregister <group-aid> <root>` | 取消群注册 |
+| `aun collab tag create/list/show/diff/restore/rm/prune ...` | 目录级标签 |
+
+示例：
+
+```powershell
+aun collab create alice.agentid.pub:/repo notes.md .\notes.md
+aun collab show alice.agentid.pub:/repo notes.md -o .\notes.md
+aun collab commit alice.agentid.pub:/repo notes.md .\notes.md --onto 1 --message "update"
+```
+
+## agent.md、密钥、诊断和压测
+
+agent.md：
+
+```powershell
+aun agentmd upload
+aun agentmd download bob.agentid.pub
+aun agentmd check bob.agentid.pub --max-unsynced-days 1
+```
+
+`upload_agent_md`、`download_agent_md`、`check_agent_md` 是 `upload`、`download`、`check` 的公开兼容别名。
+
+密钥：
+
+```powershell
+aun keys list
+aun keys rotate --type spk
+aun keys change-seed --old-seed .seed --new-seed "new-seed"
+```
+
+诊断：
+
+```powershell
+aun status
+aun ping bob.agentid.pub --count 3
+aun doctor
+aun logs --tail 100
+aun logs --follow
+```
+
+压测：
+
+```powershell
+aun bench send bob.agentid.pub --count 100 --concurrency 4
+aun bench group-send group.agentid.pub/10042 --count 100 --concurrency 4
+aun bench group send --count 100
+```
+
+`aun bench group_send` 是 `aun bench group-send` 的公开兼容别名。
+
+## 退出码
+
+| 退出码 | 含义 |
+|--------|------|
+| 0 | 成功 |
+| 1 | 通用错误 |
+| 2 | 参数错误 |
+| 3 | 认证失败 |
+| 4 | 连接失败 |
+| 5 | 超时 |
+| 6 | 权限不足 |
+| 7 | 目标不存在 |
+
+## 相关实现文件
+
+| 文件 | 说明 |
+|------|------|
+| `python/src/aun_cli/main.py` | 根应用和命令注册 |
+| `python/src/aun_cli/config.py` | CLI 配置、profile、标签页状态 |
+| `python/src/aun_cli/adapter.py` | SDK 会话桥接、错误映射、RPC summary |
+| `python/src/aun_cli/output.py` | 输出格式 |
+| `python/src/aun_cli/commands/*.py` | 各命令组实现 |

package/_packed_docs/design/2026-05-22-aun-rpc-trace-enhancement.md

@@ -540,3 +540,5 @@
 - Trace 持久化（写入 ClickHouse/Elasticsearch）
 - Trace 可视化（Web UI 展示调用树）
 - Trace 告警（失败率/耗时异常自动通知）
+
+

package/_packed_docs/design/AUNClient/346/213/206/345/210/206/351/207/215/346/236/204/346/211/247/350/241/214/346/226/271/346/241/210.md

@@ -857,3 +857,5 @@ Docker 注意：
 1. SDK 拆分重构主体已收口，本地无服务验收已通过；后续不再新增组件拆分切片，除非单域/双域回归暴露新的 parity 缺口。
 2. 下一步如要继续发布前验收，应在用户确认单域 Docker 服务环境已启动后跑 Python/TS/JS/Go 单域集成/E2E；双域 federation 需确认 `docker-deploy/federation-test` 已启动后单独跑。
 3. 旧主类 shim 可按版本节奏继续保留；若后续清理 shim，需要先把对应兼容测试改成公开行为或组件测试，不新增公开 API。
+
+

package/_packed_docs/design/E2EE_V2/347/256/200/345/214/226/344/270/2721DH/345/212/240Per-AID_Wrap/346/226/271/346/241/210.md

@@ -122,3 +122,5 @@ per-device pull envelope 中，`recipient.device_id=""` 直接按 1DH 解密。
    - Go 跑相关 package 测试。
    - TS/JS 跑类型检查或最小编译检查。
    - 用 1DH/per-AID 构造 P2P 和 Group envelope，验证 row 格式、AAD 无新增字段、解密成功。
+
+

package/_packed_docs/design//350/267/250/350/257/255/350/250/200/345/256/271/345/231/250E2E/346/265/213/350/257/225/346/226/271/346/241/210.md

@@ -663,3 +663,5 @@ federation-test/docker-compose.cross-sdk.yml
 - aid.net TS -> aid.com Python 跨域 E2EE 通过。
 - issuer 错误和篡改 envelope 类用例能稳定失败并给出可定位错误码。
 
+
+

package/_packed_docs/protocol/00-/346/200/273/350/247/210/344/270/216/345/210/206/345/261/202.md

@@ -203,3 +203,5 @@ AUN 采用标准 X.509 v3 证书体系和 ECDSA 算法，通过**四级证书链
 | [附录M-JWT认证实现指南.md](附录M-JWT认证实现指南.md) | JWT 认证实现参考 |
 
 ---
+
+

package/_packed_docs/protocol/00A-/350/256/276/350/256/241/345/216/237/345/210/231-/344/270/272Agent/350/200/214/347/224/237.md

@@ -195,3 +195,5 @@ AUN **不**负责：
 3. **四项原则**：Agent 优先、主体对等、自主至上、职责节制
 4. **六问判据**：主体性、对等性、自主性、边界、自动化友好、去中心化
 5. **红线**：service 思维、平台思维、中心化管控，一律拒绝
+
+

package/_packed_docs/protocol/01-/350/272/253/344/273/275/344/270/216/345/207/255/350/257/201/345/215/217/350/256/256-auth.md

@@ -547,3 +547,5 @@ signature = ECDSA_sign(private_key, SHA256(message))
 - **开放注册策略由运营方决定**：协议不强制限制注册，运营方可根据业务需求实施审批、限流等策略
 
 > 完整威胁模型与防护措施见 [09-安全考虑](09-安全考虑.md)。证书层级与信任模型详见 [02-证书与信任体系](02-证书与信任体系.md)。连接模式与认证流程总览见 [03-Gateway-连接模式](03-Gateway-连接模式.md)。
+
+

package/_packed_docs/protocol/02-/350/257/201/344/271/246/344/270/216/344/277/241/344/273/273/344/275/223/347/263/273.md

@@ -808,3 +808,5 @@ Agent 服务端 ──定期请求──→ OCSP Responder
 → 通过预留的恢复邮箱/电话验证身份
 → 人工审核后吊销
 ```
+
+

package/_packed_docs/protocol/03-Gateway-/350/277/236/346/216/245/346/250/241/345/274/217.md

@@ -260,3 +260,5 @@ WebSocket 连接建立后 **30 秒**内未完成 `auth.connect`，服务端关
 - Gateway 间通过 WebSocket 长连接通信，复用 JSON-RPC 2.0 协议
 - 远端 Gateway 验证请求后转发到本域服务
 - **auth 管凭证，auth.connect 管连接**——两者职责不同
+
+

package/_packed_docs/protocol/04-Peer-/345/255/220/345/215/217/350/256/256.md

@@ -178,3 +178,5 @@ CONNECTED
 - 可调用所有业务方法（`message.*` 等）
 - 身份由**证书链验证结果**确定，非 JWT
 - 会话生命周期与 WebSocket 连接绑定
+
+

package/_packed_docs/protocol/05-Relay-/345/255/220/345/215/217/350/256/256.md

@@ -162,3 +162,5 @@ Relay 模式下的身份认证流程：
 - 消息内容对 Relay 完全透明（尤其适合 E2EE 场景）
 - 所有身份验证由端到端 `peer.*` 完成
 - Relay 唯一的安全保障是 `from` 字段绑定（防止 AID 伪装）
+
+

package/_packed_docs/protocol/07-/351/224/231/350/257/257/347/240/201/344/270/216/347/212/266/346/200/201/346/234/272.md

@@ -232,3 +232,5 @@ submitted → working → completed
 - **-3218x**：升级错误，保留当前稳定通道（参见 [04-Peer-子协议](04-Peer-子协议.md)）
 - **-3204x**：E2EE 错误，群密钥缺失时请求补发，解密失败时检查密钥版本（参见 [08-AUN-E2EE-Group](08-AUN-E2EE-Group.md)）
 - **-3300x**：群组错误，根据错误类型决定重试/提示用户（参见 [10-Group-子协议](10-Group-子协议.md)）
+
+