AionCore CLI Capabilities zh CN

AionCore CLI 能力

语言：中文 | English

本文是 AionCore agent-facing CLI 的 wiki 文档，描述的是 agent / skill 调用契约，不是面向普通用户的交互式命令手册。

定位

aioncore CLI 有两类入口：

Agent-facing CLI：给 AionUi 内置 skill、assistant、定时任务和 agent 对话自动化调用。
Internal / developer CLI：给 AionCore 自身、团队 MCP、打包或开发排查使用。

Agent-facing CLI 的设计目标是稳定、机器可解析、安全可控：

命令名稳定。
输入以 stdin JSON 为主，不用业务 flag。
stdout 输出 JSON envelope。
stderr 输出稳定单行错误码。
默认脱敏敏感字段。
依赖运行时注入上下文，而不是在 skill 里自行发现端口、拼 HTTP、查进程。

快速入口

顶级能力索引：

aioncore capabilities

capabilities 不依赖 AionUi 运行时环境，适合用于发现当前二进制支持哪些 agent-facing domain。

顶级索引只回答“这个 aioncore 支持哪些 agent-facing domain，以及每个 domain 的详细 contract 在哪里”。它不会展开所有命令字段，避免输出变成过大的全量手册。

详细 domain contract：

aioncore config capabilities
aioncore diagnose capabilities

`capabilities` 与 `help`

传统 CLI 的 --help 或 help 主要服务人工阅读，输出格式会跟随 clap、文案和排版变化，不适合作为 skill 的稳定输入。

capabilities 是 agent-facing contract：

输出稳定 JSON envelope。
明确 domain、命令路径、输入模式、selector、运行时依赖和安全边界。
可由 skill 在运行时读取，避免把所有字段永久穷举在 SKILL.md 中。
允许后续新增 domain 时先注册能力，再让 skill 按 contract 调用。

因此，--help 可以继续作为开发者临时查看命令的入口；skill 和 agent 自动化应以 capabilities 为准。

能力发现模型

推荐两层发现：

层级	命令	用途
顶级索引	`aioncore capabilities`	列出 agent-facing domains、模式、风险、安全边界、详细 contract 命令
领域 contract	`aioncore config capabilities`	列出 config domain 的完整命令、stdin 字段、selector、写入/readback/脱敏契约
领域 contract	`aioncore diagnose capabilities`	列出 diagnose domain 的完整命令、stdin 字段、只读边界、HTTP escape hatch

新增 agent-facing domain 时，必须先把它注册进顶级 capabilities，再提供自己的 <domain> capabilities。

运行时上下文

AionUi 会向 agent 对话注入运行时环境。CLI 不应该依赖 skill 自己发现进程、端口或数据库位置。

本文示例统一使用 aioncore，便于阅读。在 AionUi 托管的 agent runtime 中，agent 应使用 AIONUI_HELPER_BIN 注入的 helper binary；例如，aioncore config capabilities 在运行时对应 "$AIONUI_HELPER_BIN" config capabilities。

核心环境变量：

环境变量	含义
`AIONUI_HELPER_BIN`	当前 aioncore 可执行文件路径，skill 应通过它调用 CLI
`AIONUI_BASE_URL`	当前运行中的 aioncore HTTP base URL
`AIONUI_CONVERSATION_ID`	当前 agent 对话 id，是最重要的上下文锚点
`AIONUI_USER_ID`	当前用户 id
`AIONUI_LOG_DIR`	可选，日志目录，主要给 `diagnose logs tail` 使用

核心规则：

conversation_id: "current" 解析为 AIONUI_CONVERSATION_ID。
assistant_id: "current" 通过当前 conversation 关联查询 assistant。
user_id: "current" 解析为 AIONUI_USER_ID。
不设计复杂 selector DSL，保持简单字符串 selector。

同一套上下文模型应覆盖单聊、team 群聊和定时任务。只要 agent 运行时能注入当前 conversation id，CLI 就用同一个 conversation_id: "current" 语义解析当前会话；如果某个运行场景没有 conversation 上下文，需要依赖当前会话的命令应返回稳定错误，而不是由 skill 自行猜测 assistant 或后端状态。

通用输入契约

除无输入命令外，agent-facing CLI 使用 stdin JSON：

aioncore config assistants get <<'JSON'
{
  "assistant_id": "current",
  "locale": "en-US"
}
JSON

选择 stdin JSON 的原因：

agent 不需要记忆哪些字段是 flag、哪些字段是 body。
复杂对象、长文本、MCP transport、provider config 都能使用同一种输入方式。
敏感值不会进入 argv。
CLI 层可以在转发前处理 selector、校验和脱敏。

业务参数不应设计成命令行 flag。flag 只适合真正的 CLI 运行控制，不适合 agent-facing 业务字段。

通用输出与错误契约

成功时 stdout 输出 JSON envelope：

{
  "success": true,
  "data": {},
  "meta": {
    "schema_version": 1
  }
}

字段约定：

字段	含义
`success`	CLI 命令是否成功完成
`data`	命令返回数据，通常来自后端 API 的 data
`meta`	CLI 层元信息，例如 schema version、resolved selectors、readback、escape hatch 标记

失败时：

stdout 不输出成功 envelope。
stderr 输出稳定单行错误。
进程返回非零 exit code。

错误格式：

<DOMAIN>_<CODE> command="<command path>" field="<field>" status="<http-status>": <message>

示例：

CONFIG_ENV_MISSING command="config context" field="AIONUI_CONVERSATION_ID": missing required environment variable
DIAGNOSE_PAYLOAD_INVALID command="diagnose http get" field="path": path must start with /health or /api/
CAPABILITIES_STDOUT_WRITE_FAILED command="capabilities": failed to write JSON output

错误信息不得包含 prompt、密钥、MCP headers、env value、文件内容或 provider 原始请求/响应。

Agent-facing Domains

`config`

定位：管理 AionUi 期望状态。允许写入。

详细 contract：

aioncore config capabilities

主要能力：

子域	能力
`context`	读取当前 user、conversation、assistant、base URL
`assistants`	list/get/create/update/delete/import/state
`assistants rule`	read/write/delete assistant rule
`assistants skill`	read/write/delete assistant skill content
`skills`	list/info/paths/import/delete/scan
`skills external-paths`	list/add/remove external skill paths
`skills market`	enable/disable skill market
`mcp servers`	list/get/create/update/delete/toggle/import
`mcp oauth`	check-status/login/logout/authenticated
`providers`	list/create/update/delete/detect-protocol/fetch-models/health-check
`settings`	get/patch backend settings
`settings client`	get/put client preferences
`agents`	list/enable/overrides/custom agent management
`cron jobs`	list/get/create/update/delete/run/skill state
`cron current`	list/create/update scheduled task for current conversation

安全规则：

写操作应 read-before-write 或 readback。
默认脱敏 provider keys、MCP headers、env、prompt/rule 内容。
修改 assistant rule 后应告诉用户：新的 rule 通常对新对话生效；当前对话可能仍使用启动时的 snapshot。
不保留旧 cron-helper。定时任务通过 config cron current ... 或 config cron jobs ... 管理。

`diagnose`

定位：只读排查 AionUi 运行状态。不得写入。

详细 contract：

aioncore diagnose capabilities

主要能力：

子域	能力
`context`	读取当前诊断运行时上下文
`health`	读取 backend health/version/build metadata
`overview`	聚合 health、providers、MCP、cron、running conversations
`conversations list`	列出 conversation 和 runtime summary
`conversations get`	读取单个 conversation，并附带 stuck/waiting hint
`conversations messages`	读取 conversation messages，可筛 error
`providers summary`	汇总 provider model health
`mcp summary`	汇总 MCP server 和 enabled-but-zero-tools 状态
`cron summary`	汇总 scheduled jobs 和 failing last run
`teams summary`	汇总 team 和成员 conversation state
`logs tail`	读取 aioncore log tail，支持 errors_only/conversation_id
`http get`	受控 GET escape hatch

diagnose http get 只保留旧 troubleshooting helper 的原始 GET 能力，但必须受控：

GET only。
path 只能是 /health 或 /api/...。
默认脱敏。
输出可截断。
capabilities 中标记为 escape_hatch: true。
skill 应优先使用命名命令，只有未覆盖的诊断读才使用 escape hatch。

Internal / Developer Subcommands

这些不是 agent-facing automation contract：

命令	用途
`doctor`	开发/排查时检查 agent backend 可用性
`mcp-bridge`	team MCP 的 stdio 到 TCP 内部桥
`mcp-team-stdio`	team MCP stdio server
`prepare-managed-resources`	打包阶段准备 managed runtime resources

它们可以出现在顶级 capabilities 的 non_agent_subcommands 中，但 skill 不应把它们当成配置/诊断能力来使用。

与 HTTP API 的关系

CLI 命名参考 HTTP 资源，但不应机械暴露 HTTP 路径。

原则：

CLI 命令按 agent 理解的领域命名，而不是按代码模块或当前 HTTP 路径命名。
HTTP 是实现细节，CLI contract 是 agent-facing 稳定接口。
常用能力应成为命名命令。
raw HTTP 只允许出现在明确的受控 escape hatch 中，例如 diagnose http get。

例子：

Assistant rule 的 HTTP endpoint 可能在 /api/skills/assistant-rule/*，但 CLI 应是 config assistants rule ...，因为 rule 是 assistant 行为定义的一部分。
Cron 的当前对话任务能力通过 config cron current ... 暴露，而不是旧的 cron-helper。

新增 Agent-facing Domain 的 Checklist

新增类似 config / diagnose 的 domain 时，需要同时完成：

在 aioncore capabilities 中注册 domain。
提供 <domain> capabilities，输出完整 agent-readable contract。
明确 domain mode：read-only、read-write 或更细粒度的风险模型。
统一 stdin JSON 输入，不用业务 flag。
统一 stdout JSON envelope。
统一 stderr 稳定错误码。
定义 selector 规则，优先复用 conversation_id: "current"。
明确敏感字段脱敏策略。
给每个关键路径加 E2E 覆盖。
更新对应内置 skill，只调用 CLI，不再依赖 Python、进程发现或手写 HTTP。

Skill 使用建议

内置 skill 调用顺序：

不确定当前 aioncore 支持什么时，先调用：
```
aioncore capabilities
```
已经知道要配置 AionUi 时，调用：
```
aioncore config capabilities
```
已经知道要排查 AionUi 时，调用：
```
aioncore diagnose capabilities
```
根据 domain contract 执行具体命令。

skill 不应该：

自己查 aioncore 进程。
自己探测端口。
直接调用 Python helper。
用 shell 拼复杂 JSON。
把 provider/MCP secret 输出给用户。

当前已覆盖范围

当前 wiki 对应的 CLI 能力包括：

顶级：capabilities
配置：config capabilities、config context、assistants、skills、MCP、providers、settings、agents、cron
诊断：diagnose capabilities、diagnose context、health、overview、conversations、providers、MCP、cron、teams、logs、受控 HTTP GET

如果后续新增 domain，例如 channel、office、workspace 或更细粒度的 repair，应先更新顶级能力索引，再写对应 domain contract 和 skill 文档。

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

AionCore CLI Capabilities zh CN

AionCore CLI 能力

定位

快速入口

`capabilities` 与 `help`

能力发现模型

运行时上下文

通用输入契约

通用输出与错误契约

Agent-facing Domains

`config`

`diagnose`

Internal / Developer Subcommands

与 HTTP API 的关系

新增 Agent-facing Domain 的 Checklist

Skill 使用建议

当前已覆盖范围

Uh oh!

Uh oh!

Clone this wiki locally

Uh oh!

AionCore CLI Capabilities zh CN

AionCore CLI 能力

定位

快速入口

capabilities 与 help

能力发现模型

运行时上下文

通用输入契约

通用输出与错误契约

Agent-facing Domains

config

diagnose

Internal / Developer Subcommands

与 HTTP API 的关系

新增 Agent-facing Domain 的 Checklist

Skill 使用建议

当前已覆盖范围

Uh oh!

Uh oh!

Clone this wiki locally

`capabilities` 与 `help`

`config`

`diagnose`