ae-system

ae-system

使用 system 域管理 Agent 系统：

ae-cli system +<command> [options]
ae-cli system <resource> <action> [options]

强制规则

• 这些命令仅适用于角色为 root 或 agent_admin 的用户。
• te-agent 的 /api/admin/** 和 /api/cli/channel/v1/** 端点是最终授权边界。成员会收到权限错误（HTTP 403）。遇到 403 后，不要重试登录或尝试其他端点。
• 使用此域前，先运行 ae-cli auth login --host <host>。系统管理需要有效的用户 CLI-token 会话；沙箱身份标头不能替代授权。
• +npm-install 是例外：它还必须在 Linux te-agent 沙箱内运行，因为该命令会打包已安装的 Linux 文件。运行者仍须是已登录的 root 或 agent_admin 用户。
• 更新或删除之前，先通过列表命令查询真实 ID。绝不要猜测用户、沙箱、模型、配额规则或频道 ID。
• 每次写入前，先运行 --dry-run，展示目标和影响，并取得用户明确确认。CLI 只会针对 high-risk-write 操作进行提示；--yes 可绕过该提示，并非安全边界。
• 使用 --dry-run 检查方法、路径、查询参数和脱敏后的请求体，但不执行操作。
• JSON 输入支持内联 JSON、@file 或从 stdin 输入的 -。频道凭据和其他敏感值优先使用 @file。
• 成功时默认输出 JSON。只有在表格更便于阅读时，才使用 --format table。
• 每条命令运行后，检查 stderr 和 _notice.host_compat。如果存在，先展示版本警告及其更新命令，再展示业务结果。
• 不要因缺少 ae-cli 命令，就认定 HTTP 端点不可达。具有 Bash/网络访问权限的 Agent 可以直接构造请求；实际的控制措施是服务器身份验证、角色检查、公司隔离和资源所有权检查。
• 不要通过临时 HTTP 请求调用 DELETE /api/admin/members?openId=... 或 /api/internal/sandboxes/**。这些端点由其他系统负责其集成契约，因此本技能有意不包含它们。

命令组

成员

命令	风险	用途
+list-member-candidates	读取	列出可添加的 AE 公司用户。
+list-members	读取	列出当前公司中的 Agent 成员。
+add-members	写入	添加一个或多个 AE 用户，可选绑定配额规则或创建沙箱。
+set-member-status	写入	启用或禁用成员。
+set-member-role	写入	将非 root 成员的角色在 agent_admin 和 member 之间切换。
+remove-member	高风险写入	移除非 root 成员。
+get-member-stats	读取	获取一名成员的令牌用量和近期对话次数。

示例：

ae-cli system +list-members --status enabled --page 1 --page-size 20

ae-cli system +add-members \
  --members '[{"openId":"ou_x","loginName":"alice","displayName":"Alice"}]' \
  --create-sandbox true

ae-cli system +set-member-role --user-id <user-id> --role agent_admin

+list-members 筛选项：

• --q：搜索登录名/显示名称。
• --status：all | enabled | disabled。
• --page、--page-size：页面大小为 1-100。
• --all：返回所有匹配项。
• --sort-field periodUsedAmount、--sort-dir asc|desc：按中央用量排序。

+add-members --members 的架构：

[
  {
    "openId": "required",
    "loginName": "optional",
    "displayName": "optional"
  }
]

可选标志为 --rule-id 和 --create-sandbox true|false。

沙箱

命令	风险	用途
+list-sandboxes	read	列出公司沙箱。
+get-sandbox-config	read	读取功能状态以及创建/活跃席位限制。
+batch-create-sandboxes	write	为 1-100 位用户创建个人沙箱。
+update-sandbox	write	更新沙箱描述。
+set-sandbox-enabled	write	启用或禁用沙箱。
+start-sandbox	write	启动沙箱容器。
+stop-sandbox	write	停止沙箱容器。
+list-sandbox-users	read	列出绑定到沙箱的用户。
+bind-sandbox-user	write	将成员绑定到沙箱。
+unbind-sandbox-user	high-risk-write	移除沙箱用户绑定。
+remove-sandbox	high-risk-write	删除沙箱及其绑定。

示例：

ae-cli system +batch-create-sandboxes \
  --user-ids '["<user-id-1>","<user-id-2>"]' \
  --description "Data team"

ae-cli system +set-sandbox-enabled --id <sandbox-id> --enabled true
ae-cli system +bind-sandbox-user --id <sandbox-id> --user-id <user-id>

沙箱命令请使用 +list-members 返回的 Agent 数据库用户 ID，而不是 AE openIds。

共享沙箱工具

命令	风险	用途
+upload-sandbox-tool	write	验证现有工具目录，将其打包为 ZIP 并上传。
+npm-install	write	在临时沙箱目录中安装指定的精确 npm CLI 版本，生成 tool.json 并上传。
+list-sandbox-tools	read	列出当前公司的预设工具和自定义工具。
+sync-sandbox-tools	write	根据服务端清单同步预设工具。
+get-sandbox-tool-distribution	read	查看当前接收某个工具的沙箱。
+set-sandbox-tool-enabled	write	启用或禁用已注册的工具。
+remove-sandbox-tool	high-risk-write	删除已完全回收的工具注册。
+activate-sandbox-tools	write	在选定的沙箱或所有运行中的沙箱上激活所选命令。
+deactivate-sandbox-tools	write	从选定的沙箱或所有运行中的沙箱中移除托管命令垫片。
+refresh-sandbox-tool-status	write	刷新目标沙箱上观察到的工具状态。
+list-sandbox-tool-operations	read	列出激活/停用历史记录。

上传的工具会以 enabled=false 的状态注册到当前公司。上传不会在任何运行中的沙箱中激活该工具。上传后，请通过沙箱工具管理功能审核并启用/激活该工具。

激活/停用/状态操作：

ae-cli system +activate-sandbox-tools \
  --target-mode selected \
  --sandbox-ids '["<sandbox-id>"]' \
  --tool-ids '["<tool-id>"]'

• --target-mode selected 需要提供 1-50 个 --sandbox-ids；all-running 则禁止提供这些参数。
• --tool-ids 包含 1-20 个来自 +list-sandbox-tools 的真实 ID。
• --command-names-by-tool-id 可选，用于将操作限制为指定命令。
• --expected-tool-snapshots-by-id 包含服务端返回的版本/软件包/命令快照，用于乐观并发检查。
• JSON 映射可通过内联 JSON、@file 或标准输入传入。更改分发前，请使用 dry-run 并征得用户确认。

首选 npm 流程

在目标 Linux te-agent 沙箱中运行：

ae-cli auth login --host <host>
ae-cli system +npm-install --package [email protected]

对于作用域包或自定义共享工具标识符：

ae-cli system +npm-install \
  --package @scope/[email protected] \
  --name example-cli

要求和行为：

• --package 必须是确切的注册表软件包版本。不接受标签、版本范围、URL、Git 源、npm 别名和本地路径。
• 已安装的软件包必须至少公开一个 package.json bin 条目。每个 bin 都会成为一个工具命令。
• 默认工具名称为未加作用域的软件包名称。只有在需要使用其他有效的小写工具标识符时，才使用 --name。
• 默认使用 --ignore-scripts 禁用 npm 生命周期脚本。只有在审查并信任该软件包及其所有传递依赖后，才使用 --allow-scripts true。
• 该命令会在启动 npm 前调用管理上传策略端点。功能已禁用、会话已过期或角色不是管理员时，会在安装前失败。
• 安装使用临时前缀，并省略开发依赖。无论上传成功还是失败，都会删除临时安装文件和 ZIP 文件。
• npm 创建的 node_modules/.bin 符号链接会在 ZIP 中转换为常规可执行包装脚本。其他所有符号链接、特殊文件，以及指向软件包根目录之外的链接都会被拒绝。
• 纯 JavaScript Node.js CLI 是受支持的基准。需要原生插件、下载平台二进制文件、构建工具、系统库或生命周期设置的软件包，在禁用脚本时或在不同的运行时镜像中激活时可能会失败。
• 如果必须运行生命周期脚本，请从将要执行该工具的同一 Linux 沙箱镜像系列中安装并上传。上传无法让不兼容的原生构件变得可移植。

现有目录流程

当工具已安装或已组装完成时，使用低级命令：

ae-cli system +upload-sandbox-tool --path /absolute/path/to/tool-root

目录根目录必须恰好包含一个 tool.json。只有在根目录中没有 tool.json 时，才允许使用外部清单：

ae-cli system +upload-sandbox-tool \
  --path /absolute/path/to/tool-root \
  --manifest /absolute/path/to/tool.json

最简清单：

{
  "schemaVersion": 1,
  "name": "example-cli",
  "displayName": "Example CLI",
  "description": "Optional description",
  "version": "1.2.3",
  "commands": [
    {
      "name": "example",
      "entry": "node_modules/example-cli/bin/example.js",
      "runtime": "node"
    }
  ]
}

上传约定：

• name 和命令名称必须以小写字母开头，且只能包含小写字母、数字、.、_ 或 -，最长为 64 个字符。
• 命令名称不得替换 node、npm、npx、bash、python、git、curl 或 sudo 等保留运行时命令。
• 每个命令的 entry 都必须是上传根目录下的常规文件。JavaScript 入口文件使用 runtime: "node"；只有与沙箱 Linux 镜像兼容的可执行文件才能使用 runtime: "native"。
• 路径必须是相对路径且已规范化。绝对路径、..、反斜杠、控制字符、空路径段以及 current 路径段都会被拒绝。
• ZIP 限制为：压缩后 50 MB、解压后 500 MB、单个文件 50 MB、文件数 10,000 个。服务器只有在独立验证相同限制后才会发布。
• 不要在沙箱中预先创建或写入 /data/app/te_agent_ta/share/tools。沙箱对此目录是只读的；经过身份验证的 te-agent 上传端点负责最终写入和注册。
• 在此首次静态版本流程中，每家公司只能注册一次同名工具。请在上传前确定最终名称和版本。

模型

命令	风险	用途
+list-system-models	read	列出系统模型及其对公司的可见性。
+set-system-model-enabled	write	切换当前公司的系统模型启用状态。
+get-model-sync-settings	read	读取新同步系统模型的默认可见性策略。
+set-model-sync-settings	write	更新新系统模型的可见性策略。
+get-system-model-price-rules	read	读取一个受管理系统模型已存储的定价快照。
+list-company-models	read	列出公司模型，包括已禁用的模型。
+set-company-model-enabled	write	为所有公司用户切换公司模型的启用状态。
+get-default-models	read	读取 AE_AGENT 和 AI_QA 默认槽位。
+set-default-model	write	设置一个默认模型槽位。
+clear-default-model	high-risk-write	清除一个默认模型槽位。

示例：

ae-cli system +list-system-models
ae-cli system +set-system-model-enabled --model-id <model-id> --enabled false
ae-cli system +set-default-model --model-id <model-id> --biz-type AE_AGENT

--biz-type 为 AE_AGENT | AI_QA，默认值为 AE_AGENT。请使用模型列表返回的数据库 id，而不是提供商模型名称。

用量

命令	风险	用途
+get-usage-summary	read	获取相对或绝对时间范围内的 Token／费用汇总。
+get-usage-details	read	获取按用户、模型、日期或应用类型分组的分页用量数据。
+get-agent-tool-calls	read	获取指定时间范围内的 Agent 工具调用次数，可选择刷新缓存。
+get-usage-combinations	read	将一个父分组进一步细分为其余维度。
+export-usage	read	将经过筛选的单维度用量分组流式导出为 CSV。
+export-usage-details	read	将完整或下钻的多维度详情流式导出为 CSV。

示例：

ae-cli system +get-usage-summary --days 30
ae-cli system +get-usage-summary --days 30 --refresh true

ae-cli system +get-usage-details \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --group-by user \
  --page 1 \
  --page-size 20

ae-cli system +get-usage-combinations \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --parent-dimension user \
  --open-id <open-id>

ae-cli system +export-usage \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --group-by user \
  --output ./system-usage.csv

汇总时间范围：

• 使用 --days 1..365，或同时提供 --start-date 和 --end-date。
• 日期格式为 YYYY-MM-DD。
• 不要将 --days 与绝对日期范围组合使用。
• +get-usage-summary 和 +get-agent-tool-calls 支持 --refresh true，用于绕过概览缓存。

详情标志：

• 必须提供 --start-date 和 --end-date。
• --group-by：user | model | date | app_type。
• 可选筛选项：--search、--open-id、--model-id、--model-scope、--app-type。
• --model-scope 必须与 --model-id 配合使用。
• --sort-by：totalTokens | cost | share | requestCount。
• --sort-dir：asc | desc。

组合下钻必须且只能指定一个父级筛选条件：

• user → 仅使用 --open-id。
• model → 仅使用 --model-id 和 --model-scope。
• app_type → 仅使用 --app-type。
• date → 仅使用 --date，且日期必须位于所选范围内。

导出 CSV 时必须明确指定 --output。目标文件采用独占方式创建：绝不覆盖已有文件；如果 HTTP 请求或数据流失败，会删除未完成的文件。JSON 结果会报告本地绝对路径、写入字节数、服务端文件名和内容类型。

成本控制

命令	风险	用途
+get-cost-summary	读取	获取公司成本、配额和用量摘要。
+get-balance	读取	获取当前模型账户余额和货币。
+list-over-limit-users	读取	列出超出成本或 Token 配额限制的成员。
+get-balance-alert	读取	获取余额提醒配置和当前状态。
+set-balance-alert	写入	启用、更新或停用余额提醒。
+list-quota-rules	读取	列出成本／Token 配额规则。
+create-quota-rule	写入	创建公司或用户配额规则。
+update-quota-rule	写入	更新配额规则。
+remove-quota-rule	高风险写入	删除配额规则。
+bind-quota-rule-user	写入	将配额规则绑定到 AE 用户 openId。

示例：

ae-cli system +set-balance-alert --enabled true --threshold 100

ae-cli system +create-quota-rule --rule @quota-rule.json
ae-cli system +bind-quota-rule-user --id <rule-id> --open-id <open-id>

配额规则 JSON：

{
  "name": "Daily user quota",
  "subjectType": "USER",
  "periodType": "DAY",
  "quotaType": "TOKEN",
  "totalTokens": "10",
  "allowedModels": ["<model-id>"],
  "modelLimits": [
    {
      "modelId": "<model-id>",
      "limitTokens": "5"
    }
  ],
  "openIds": ["<open-id>"]
}

规则：

• subjectType：USER | COMPANY。
• periodType：DAY | WEEK | MONTH。
• quotaType：COST | TOKEN。
• COST 使用 budgetAmount；TOKEN 使用 totalTokens。Token 值以百万为单位。
• 根据服务端规则类型，allowedModels 和 modelLimits 为可选项。
• 更新时接受部分规则对象。

渠道

设置渠道、配置路由、关联 WhatsApp Web 或绑定飞书用户前，请先阅读 references/channel-management.md。其中定义了两个确认阶段，以及 ae-cli 与飞书 OpenAPI MCP 工作流。

命令	风险	用途
+list-channels	读取	列出所有已配置的渠道。
channel get	读取	读取一个渠道、其验证状态和端点。
+create-channel	写入	创建一个渠道。
+update-channel	写入	更新渠道设置、凭据、模型、提示词或启用状态。
+remove-channel	高风险写入	删除渠道、解除用户绑定并停止其连接。
channel verify	写入	验证凭据并发现端点。
channel routing get	读取	读取一个端点的群消息路由。
channel routing set	写入	替换一个端点的群消息路由。
channel whatsapp-web status	读取	读取 WhatsApp Web 关联状态和 QR 数据。
channel whatsapp-web start	写入	启动或恢复 WhatsApp Web QR 关联。
channel whatsapp-web unlink	高风险写入	解除 WhatsApp Web 关联并删除已存储的凭据。
channel binding list	读取	列出渠道用户绑定。
channel binding bind-feishu	写入	绑定一个飞书用户。
+bind-feishu-users	写入	绑定 1-100 个飞书用户，并可选择分配 Agent。
channel binding unbind	高风险写入	删除一个渠道用户绑定。
channel binding set-agent	写入	设置或清除一个绑定的私聊默认 Agent。

使用规范的 snake_case 请求字段。为保持兼容，四个原始命令也接受旧版 camelCase JSON 字段。凭据和批量名单务必使用 @file：

ae-cli system +create-channel --channel @channel.json
ae-cli system +update-channel --id <channel-id> --channel @channel-update.json
ae-cli system +bind-feishu-users \
  --channel-id <channel-id> \
  --endpoint-id <endpoint-id> \
  --bindings @bindings.json

权限错误

权限响应如下所示：

{
  "ok": false,
  "error": {
    "type": "permission",
    "message": "..."
  }
}

对于此响应：

1. 不要通过其他管理员路径重试。
2. 除非服务端返回了 401，否则不要建议重新登录。
3. 告知用户需要 root 或 agent_admin 权限。

经过身份验证的 root 或 agent_admin 仍受其所属公司的范围限制。当前服务会根据会话检查数据库角色和公司；经过审计的成员、渠道、沙盒工具和沙盒管理路由会执行公司／资源所有权检查。切勿据此声称所有未经审查的管理员路由都是安全的。

传输状态

这是一个过渡域，由 te-agent /api/admin/** 和 /api/cli/channel/v1/** 提供支持。

• 维护方：te-agent 管理/频道管理路由和 src/commands/te-system/**。
• 迁移目标：系统和频道能力网关。
• 审查日期：2026-10-24。
• 退出条件：等效网关的架构、身份验证、风险、试运行和输出契约稳定后再迁移。