用 ae-cli system 做 Agent…

当需要以 root 或 agent_admin 身份通过 ae-cli system 管理 Agent 成员、沙箱、共享工具、公司模型、用量统计、成本配额、余额告警和 IM 渠道时使用。

适用场景

解决思路

1. 确认当前用户 Agent 角色为 root 或 agent_admin，否则不要执行这些命令。
2. 先运行 ae-cli auth login --host <host> 建立有效的用户 CLI-token 会话；沙箱身份头不能替代授权。
3. 把 te-agent 的 /api/admin/** 和 /api/cli/channel/v1/** 端点视为最终授权边界；收到 HTTP 403 权限错误后不要重试登录或换端点。
4. 任何更新或删除前，先用对应的 list 命令发现真实 ID（用户、沙箱、模型、配额规则、渠道），绝不猜测 ID。
5. 每次写入前先运行 --dry-run，展示目标与影响，并获得用户明确确认；--yes 只是跳过 CLI 的 high-risk-write 提示，不是安全边界。
6. 用 --dry-run 检查 method、path、query 和被脱敏的 body，而不实际执行。
7. JSON 输入支持内联 JSON、@file 或 - 从 stdin 读取；渠道凭据等敏感值优先用 @file。
8. 默认输出为 JSON；仅在更适合人读时使用 --format table。
9. 每条命令后检查 stderr 和 _notice.host_compat，若存在则先展示版本警告及其更新命令，再展示业务结果。
10. 不要因为 ae-cli 缺少某命令就认为 HTTP 端点不可达；有 Bash/网络权限的 Agent 可直接构造请求，真正的控制是服务端认证、角色检查、公司隔离和资源归属。
11. 不要通过临时 HTTP 调用 DELETE /api/admin/members?openId=... 或 /api/internal/sandboxes/**，这些集成契约由其他系统负责。
12. 成员管理：用 +list-member-candidates 列出可添加的 AE 公司用户，用 +list-members 列出当前公司 Agent 成员（支持 --q、--status all|enabled|disabled、--page、--page-size 1-100、--all、--sort-field periodUsedAmount、--sort-dir asc|desc）。
13. 成员管理：用 +add-members 添加一个或多个 AE 用户，--members 为包含 openId（必填）、loginName、displayName 的 JSON 数组，可选 --rule-id 和 --create-sandbox true|false。
14. 成员管理：用 +set-member-status 启用/禁用成员，用 +set-member-role 在 agent_admin 与 member 之间切换非 root 成员，用 +remove-member 移除非 root 成员，用 +get-member-stats 查看单个成员的 token 用量和近期会话数。
15. 沙箱管理：用 +list-sandboxes 列出公司沙箱，用 +get-sandbox-config 读取功能状态和创建/活跃席位上限。
16. 沙箱管理：用 +batch-create-sandboxes 为 1-100 个用户创建个人沙箱（--user-ids 为 JSON 数组，可带 --description）。
17. 沙箱管理：用 +update-sandbox 更新描述，用 +set-sandbox-enabled 启用/禁用，用 +start-sandbox / +stop-sandbox 启停容器。
18. 沙箱管理：用 +list-sandbox-users 列出绑定用户，用 +bind-sandbox-user 绑定成员，用 +unbind-sandbox-user 解绑，用 +remove-sandbox 删除沙箱及其绑定。
19. 沙箱命令必须使用 +list-members 返回的 Agent 数据库 user ID，而不是 AE openId。
20. 共享工具：用 +upload-sandbox-tool 校验、打包 ZIP 并上传已有工具目录；用 +npm-install 在临时沙箱目录安装精确 npm CLI 版本、生成 tool.json 并上传。
21. 共享工具：用 +list-sandbox-tools 列出预置和自定义工具，用 +sync-sandbox-tools 从服务端清单同步预置工具，用 +get-sandbox-tool-distribution 查看正在接收某工具的沙箱。
22. 共享工具：用 +set-sandbox-tool-enabled 启用/禁用已注册工具，用 +remove-sandbox-tool 删除已完全回收的工具注册，用 +activate-sandbox-tools / +deactivate-sandbox-tools 在选定或全部运行中沙箱上激活/移除命令 shim，用 +refresh-sandbox-tool-status 刷新观测状态，用 +list-sandbox-tool-operations 查看激活/停用历史。
23. 上传的工具以 enabled=false 注册到当前公司，上传不会在任何运行中沙箱激活它；上传后需通过沙箱工具管理审查并启用/激活。
24. 激活/停用/状态操作：--target-mode selected 需要 1-50 个 --sandbox-ids，all-running 禁止传 --sandbox-ids；--tool-ids 为 1-20 个来自 +list-sandbox-tools 的真实 ID；可用 --command-names-by-tool-id 限定命令，用 --expected-tool-snapshots-by-id 做乐观并发校验；分发变更前先 dry-run 并获用户确认。
25. npm 流程：在目标 Linux te-agent 沙箱内先 ae-cli auth login --host <host>，再运行 ae-cli system +npm-install --package eslint@9.32.0；scoped 包或自定义标识用 --package @scope/example-cli@1.2.3 --name example-cli。
26. npm 流程要求：--package 必须是精确 registry 版本，拒绝 tag、range、URL、Git 源、npm alias 和本地路径；安装包必须至少暴露一个 package.json bin 入口，每个 bin 成为一个工具命令；默认工具名为去 scope 的包名，仅在需要不同合法小写标识时用 --name。
27. npm 流程默认用 --ignore-scripts 禁用生命周期脚本；仅在审查并信任该包及其全部传递依赖后才用 --allow-scripts true。
28. npm 流程在开始安装前调用 admin upload-policy 端点；功能禁用、会话过期或非管理员角色会在安装前失败。
29. npm 流程使用临时 prefix 并省略开发依赖；无论上传成功或失败，临时安装和 ZIP 文件都会被清理。
30. npm 流程会把 npm 创建的 node_modules/.bin 符号链接转换为 ZIP 中的常规可执行包装；其他符号链接、特殊文件及解析到包根之外的链接都会被拒绝。
31. npm 流程支持纯 JavaScript Node.js CLI 基线；需要原生插件、下载平台二进制、构建工具、系统库或生命周期设置的包在禁用脚本或不同运行时镜像中可能失败；若必须用生命周期脚本，应在将执行该工具的同一 Linux 沙箱镜像族中安装并上传。
32. 已有目录流程：用 ae-cli system +upload-sandbox-tool --path /absolute/path/to/tool-root；目录根必须恰好包含一个 tool.json，仅当根无 tool.json 时才可用 --manifest /absolute/path/to/tool.json 指定外部清单。
33. 上传契约：name 和命令名必须以小写字母开头，仅含小写字母、数字、.、_、-，最长 64；命令名不得替换 node、npm、npx、bash、python、git、curl、sudo 等保留运行时命令。
34. 上传契约：每个命令 entry 必须是上传根下的常规文件；JavaScript 入口用 runtime: "node"，仅对与沙箱 Linux 镜像兼容的可执行文件用 runtime: "native"；路径必须相对且规范化，拒绝绝对路径、..、反斜杠、控制字符、空段和 current 段。
35. 上传契约：ZIP 限制为压缩 50 MB、解压 500 MB、单文件 50 MB、10000 个文件；服务端会独立校验相同边界后才发布。
36. 上传契约：不要从沙箱预创建或写入 /data/app/te_agent_ta/share/tools，该目录对沙箱只读，最终写入和注册由已认证的 te-agent 上传端点负责。
37. 上传契约：在此首个静态版本流程中，一个工具名每公司只能注册一次；上传前先确定最终名称和版本。
38. 模型管理：用 +list-system-models 列出系统模型及公司可见性，用 +set-system-model-enabled 切换系统模型对当前公司的可见性。
39. 模型管理：用 +get-model-sync-settings / +set-model-sync-settings 读取和更新新同步系统模型的默认可见性策略。
40. 模型管理：用 +get-system-model-price-rules 读取某受管系统模型的定价快照，用 +list-company-models 列出公司模型（含禁用），用 +set-company-model-enabled 为公司所有用户切换公司模型。
41. 模型管理：用 +get-default-models 读取 AE_AGENT 和 AI_QA 默认槽位，用 +set-default-model 设置某个默认槽位（--biz-type AE_AGENT|AI_QA，默认 AE_AGENT），用 +clear-default-model 清除某个默认槽位；使用模型列表返回的数据库 id，而非 provider 模型名。
42. 用量统计：用 +get-usage-summary 获取相对或绝对区间的 token/成本汇总（--days 1..365 或同时提供 --start-date 和 --end-date，日期格式 YYYY-MM-DD，二者不可混用；--refresh true 可绕过概览缓存）。
43. 用量统计：用 +get-usage-details 获取按 user|model|date|app_type 分组的翻页用量（--start-date 和 --end-date 必填，可选 --search、--open-id、--model-id、--model-scope、--app-type，--model-scope 需配合 --model-id，--sort-by totalTokens|cost|share|requestCount，--sort-dir asc|desc）。
44. 用量统计：用 +get-agent-tool-calls 获取区间内 Agent 工具调用次数（可 --refresh true 刷新缓存）。
45. 用量统计：用 +get-usage-combinations 下钻一个父分组到剩余维度，必须恰好一个父选择器：user→仅 --open-id，model→仅 --model-id 和 --model-scope，app_type→仅 --app-type，date→仅 --date 且在所选区间内。
46. 用量统计：用 +export-usage 将过滤后的单维度用量分组流式导出为 CSV，用 +export-usage-details 导出完整或多维度下钻明细为 CSV；必须显式指定 --output，目标文件独占创建、绝不覆盖已有文件，HTTP 或流失败会删除不完整文件，JSON 结果报告绝对本地路径、写入字节数、服务端文件名和 content type。
47. 成本控制：用 +get-cost-summary 获取公司成本、配额和用量汇总，用 +get-balance 获取当前模型账户余额和币种，用 +list-over-limit-users 列出超出成本或 token 配额限制的成员。
48. 成本控制：用 +get-balance-alert / +set-balance-alert 读取和启用/更新/禁用余额告警（如 --enabled true --threshold 100）。
49. 成本控制：用 +list-quota-rules 列出成本/token 配额规则，用 +create-quota-rule 创建公司或用户配额规则，用 +update-quota-rule 更新（接受部分对象），用 +remove-quota-rule 删除，用 +bind-quota-rule-user 将规则绑定到 AE 用户 openId。
50. 配额规则 JSON：subjectType 为 USER|COMPANY，periodType 为 DAY|WEEK|MONTH，quotaType 为 COST|TOKEN；COST 用 budgetAmount，TOKEN 用 totalTokens（以百万为单位）；allowedModels 和 modelLimits 按服务端规则类型可选。
51. 渠道管理：进行渠道设置、路由、WhatsApp Web 链接或飞书用户绑定前，先阅读 references/channel-management.md，它定义了两个确认阶段以及 ae-cli 加 Feishu OpenAPI MCP 工作流。
52. 渠道管理：用 +list-channels 列出所有已配置渠道，用 channel get 读取单个渠道及其验证状态和端点，用 +create-channel 创建渠道，用 +update-channel 更新设置/凭据/模型/prompt/启用状态，用 +remove-channel 删除渠道并解绑用户、停止连接。
53. 渠道管理：用 channel verify 验证凭据并发现端点，用 channel routing get / channel routing set 读取和替换某端点的群消息路由。
54. 渠道管理：用 channel whatsapp-web status 读取 WhatsApp Web 链接状态和 QR 数据，用 channel whatsapp-web start 启动或恢复 QR 链接，用 channel whatsapp-web unlink 解绑并删除存储凭据。
55. 渠道管理：用 channel binding list 列出渠道用户绑定，用 channel binding bind-feishu 绑定单个飞书用户，用 +bind-feishu-users 绑定 1-100 个飞书用户并可分配 Agent，用 channel binding unbind 删除单个绑定，用 channel binding set-agent 设置或清除某绑定的私聊默认 Agent。
56. 渠道管理：使用规范的 snake_case 请求字段；四个原始命令也接受旧 camelCase JSON 字段以兼容；凭据和批量名单始终用 @file（如 --channel @channel.json、--bindings @bindings.json）。
57. 遇到权限错误响应（ok:false、error.type:permission）时：不要换其他 admin 路径重试；除非服务端返回 401，否则不要建议重新登录；告知用户需要 root 或 agent_admin 角色。
58. 注意已认证的 root 或 agent_admin 仍被限制在自己公司内；服务端会对照会话检查数据库角色和公司，成员、渠道、沙箱工具和沙箱管理路由会做公司/资源归属检查；不要据此声称所有未审查的 admin 路由都安全。

适用边界 · 注意事项

• 当前用户不是 root 或 agent_admin 角色时不要使用这些命令。
• 收到 HTTP 403 权限错误后不要重试登录或尝试其他 admin 端点。
• 不要通过临时 HTTP 调用 DELETE /api/admin/members?openId=... 或 /api/internal/sandboxes/**，这些契约由其他系统负责。
• 不要从沙箱预创建或写入 /data/app/te_agent_ta/share/tools，该目录对沙箱只读。