Skip to content

AionCore CLI Capabilities

Jump to bottom
kaizhou-lab edited this page Jul 8, 2026 · 4 revisions

AionCore CLI 能力 / AionCore CLI Capabilities

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

This page documents the AionCore agent-facing CLI contract. It is intended for agent / skill automation, not as a human-oriented interactive CLI manual.

定位 / Positioning

aioncore CLI 有两类入口：

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

aioncore exposes two kinds of command surfaces:

  • Agent-facing CLI: used by AionUi built-in skills, assistants, scheduled tasks, and agent conversations.
  • Internal / developer CLI: used by AionCore itself, team MCP plumbing, packaging, and developer diagnostics.

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

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

The agent-facing CLI is designed to be stable, machine-readable, and safe:

  • Stable command names.
  • Business input is passed through stdin JSON, not flags.
  • stdout returns a JSON envelope.
  • stderr returns a stable single-line error code.
  • Sensitive fields are redacted by default.
  • Runtime context is injected by AionUi; skills should not discover ports, build ad hoc HTTP clients, or inspect processes.

快速入口 / Quick Start

顶级能力索引：

Top-level capability index:

aioncore capabilities

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

capabilities does not require the AionUi runtime environment. It is safe to use for discovering which agent-facing domains the current binary supports.

在 AionUi agent 运行时中应使用：

Inside an AionUi agent runtime, use:

"$AIONUI_HELPER_BIN" capabilities

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

The top-level index only answers: which agent-facing domains are supported, and where each domain's detailed contract lives. It does not expand every command field, so the output stays compact and stable.

详细 domain contract：

Detailed domain contracts:

"$AIONUI_HELPER_BIN" config capabilities
"$AIONUI_HELPER_BIN" diagnose capabilities

capabilities 与 help / capabilities vs help

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

Traditional --help or help output is primarily for humans. Its formatting can change with clap, wording, and layout, so it should not be treated as a stable skill input.

capabilities 是 agent-facing contract：

capabilities is the agent-facing contract:

  • 输出稳定 JSON envelope。 / It returns a stable JSON envelope.
  • 明确 domain、命令路径、输入模式、selector、运行时依赖和安全边界。 / It declares domains, command paths, input modes, selectors, runtime requirements, and safety boundaries.
  • 可由 skill 在运行时读取，避免把所有字段永久穷举在 SKILL.md 中。 / Skills can read it at runtime instead of hardcoding every field forever in SKILL.md.
  • 允许后续新增 domain 时先注册能力，再让 skill 按 contract 调用。 / New domains can be registered first, then consumed by skills through their contracts.

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

Therefore, --help can remain a developer convenience, while skills and agent automation should rely on capabilities.

能力发现模型 / Capability Discovery Model

推荐两层发现：

Use two-level discovery:

层级 / Level 命令 / Command 用途 / Purpose
顶级索引 / Top-level index aioncore capabilities 列出 agent-facing domains、模式、风险、安全边界、详细 contract 命令 / Lists agent-facing domains, modes, risks, safety boundaries, and detailed contract commands
领域 contract / Domain contract aioncore config capabilities 列出 config domain 的完整命令、stdin 字段、selector、写入/readback/脱敏契约 / Lists config commands, stdin fields, selectors, write/readback behavior, and redaction rules
领域 contract / Domain contract aioncore diagnose capabilities 列出 diagnose domain 的完整命令、stdin 字段、只读边界、HTTP escape hatch / Lists diagnose commands, stdin fields, read-only boundaries, and the controlled HTTP escape hatch

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

When adding a new agent-facing domain, register it in top-level capabilities first, then provide its own <domain> capabilities.

运行时上下文 / Runtime Context

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

AionUi injects runtime context into agent conversations. The CLI should not rely on skills to discover processes, ports, or database paths.

核心环境变量：

Core environment variables:

环境变量 / Variable 中文说明 English Description
AIONUI_HELPER_BIN 当前 aioncore 可执行文件路径，skill 应通过它调用 CLI Path to the current aioncore executable; skills should invoke the CLI through it
AIONUI_BASE_URL 当前运行中的 aioncore HTTP base URL Base URL of the running aioncore HTTP server
AIONUI_CONVERSATION_ID 当前 agent 对话 id，是最重要的上下文锚点 Current agent conversation id; the primary context anchor
AIONUI_USER_ID 当前用户 id Current user id
AIONUI_LOG_DIR 可选，日志目录，主要给 diagnose logs tail 使用 Optional log directory, mainly used by diagnose logs tail

核心规则：

Core rules:

  • conversation_id: "current" 解析为 AIONUI_CONVERSATION_ID。 / conversation_id: "current" resolves from AIONUI_CONVERSATION_ID.
  • assistant_id: "current" 通过当前 conversation 关联查询 assistant。 / assistant_id: "current" resolves through the assistant associated with the current conversation.
  • user_id: "current" 解析为 AIONUI_USER_ID。 / user_id: "current" resolves from AIONUI_USER_ID.
  • 不设计复杂 selector DSL，保持简单字符串 selector。 / Do not introduce a complex selector DSL; keep simple string selectors.

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

The same context model should cover one-on-one conversations, team chats, and scheduled tasks. As long as the agent runtime injects the current conversation id, the CLI uses the same conversation_id: "current" semantics. If a runtime does not provide conversation context, commands that depend on the current conversation should return a stable error instead of letting the skill guess assistant or backend state.

通用输入契约 / Input Contract

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

Except for no-input commands, the agent-facing CLI uses stdin JSON:

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

选择 stdin JSON 的原因：

Why stdin JSON:

  • agent 不需要记忆哪些字段是 flag、哪些字段是 body。 / Agents do not need to remember which fields are flags and which fields are request bodies.
  • 复杂对象、长文本、MCP transport、provider config 都能使用同一种输入方式。 / Complex objects, long text, MCP transport config, and provider config use one input style.
  • 敏感值不会进入 argv。 / Sensitive values do not appear in argv.
  • CLI 层可以在转发前处理 selector、校验和脱敏。 / The CLI layer can resolve selectors, validate payloads, and redact data before forwarding.

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

Business parameters should not be modeled as command-line flags. Flags are appropriate for CLI execution control, not agent-facing business fields.

通用输出与错误契约 / Output and Error Contract

成功时 stdout 输出 JSON envelope：

On success, stdout returns a JSON envelope:

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

字段约定：

Field contract:

字段 / Field 中文说明 English Description
success CLI 命令是否成功完成 Whether the CLI command completed successfully
data 命令返回数据，通常来自后端 API 的 data Command result data, usually from backend API data
meta CLI 层元信息，例如 schema version、resolved selectors、readback、escape hatch 标记 CLI metadata, such as schema version, resolved selectors, readback, and escape hatch markers

失败时：

On failure:

  • stdout 不输出成功 envelope。 / stdout does not emit a success envelope.
  • stderr 输出稳定单行错误。 / stderr emits a stable single-line error.
  • 进程返回非零 exit code。 / The process exits with a non-zero code.

错误格式：

Error format:

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

示例 / Examples:

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 原始请求/响应。

Error messages must not include prompts, secrets, MCP headers, environment values, file contents, or raw provider requests/responses.

Agent-facing Domains

config

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

Purpose: manage AionUi desired state. This domain can write configuration.

详细 contract：

Detailed contract:

"$AIONUI_HELPER_BIN" config capabilities

主要能力：

Main capabilities:

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

安全规则：

Safety rules:

  • 写操作应 read-before-write 或 readback。 / Write operations should perform read-before-write or readback.
  • 默认脱敏 provider keys、MCP headers、env、prompt/rule 内容。 / Provider keys, MCP headers, env values, and prompt/rule content are redacted by default.
  • 修改 assistant rule 后应告诉用户：新的 rule 通常对新对话生效；当前对话可能仍使用启动时的 snapshot。 / After changing an assistant rule, tell the user that the new rule usually applies to new conversations; the current conversation may still use its startup snapshot.
  • 不保留旧 cron-helper。定时任务通过 config cron current ... 或 config cron jobs ... 管理。 / Do not keep the old cron-helper; scheduled tasks are managed through config cron current ... or config cron jobs ....

diagnose

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

Purpose: read-only troubleshooting for AionUi runtime state. This domain must not write configuration.

详细 contract：

Detailed contract:

"$AIONUI_HELPER_BIN" diagnose capabilities

主要能力：

Main capabilities:

子域 / Subdomain 中文能力 English Capability
context 读取当前诊断运行时上下文 Read current diagnostic runtime context
health 读取 backend health/version/build metadata Read backend health/version/build metadata
overview 聚合 health、providers、MCP、cron、running conversations Aggregate health, providers, MCP, cron, and running conversations
conversations list 列出 conversation 和 runtime summary List conversations and runtime summaries
conversations get 读取单个 conversation，并附带 stuck/waiting hint Read one conversation with stuck/waiting hints
conversations messages 读取 conversation messages，可筛 error Read conversation messages, optionally filtering errors
providers summary 汇总 provider model health Summarize provider model health
mcp summary 汇总 MCP server 和 enabled-but-zero-tools 状态 Summarize MCP servers and enabled-with-zero-tools state
cron summary 汇总 scheduled jobs 和 failing last run Summarize scheduled jobs and failing last runs
teams summary 汇总 team 和成员 conversation state Summarize teams and member conversation state
logs tail 读取 aioncore log tail，支持 errors_only/conversation_id Tail aioncore logs with errors_only/conversation_id support
http get 受控 GET escape hatch Controlled GET escape hatch

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

diagnose http get preserves the old troubleshooting helper's raw GET capability, but only as a controlled escape hatch:

  • GET only。 / GET only.
  • path 只能是 /health 或 /api/...。 / The path must be /health or /api/....
  • 默认脱敏。 / Redacted by default.
  • 输出可截断。 / Output may be truncated.
  • capabilities 中标记为 escape_hatch: true。 / Marked as escape_hatch: true in capabilities.
  • skill 应优先使用命名命令，只有未覆盖的诊断读才使用 escape hatch。 / Skills should prefer named commands and use the escape hatch only for uncovered read-only diagnostics.

Internal / Developer Subcommands

这些不是 agent-facing automation contract：

These are not agent-facing automation contracts:

命令 / Command 中文用途 English Purpose
doctor 开发/排查时检查 agent backend 可用性 Human/developer self-check for agent backend availability
mcp-bridge team MCP 的 stdio 到 TCP 内部桥 Internal stdio-to-TCP bridge for team MCP
mcp-team-stdio team MCP stdio server Internal team MCP stdio server
prepare-managed-resources 打包阶段准备 managed runtime resources Packaging helper for managed runtime resources

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

They may appear in non_agent_subcommands in top-level capabilities, but skills should not treat them as configuration or diagnostic capabilities.

与 HTTP API 的关系 / Relationship with HTTP APIs

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

CLI names may reference HTTP resources, but they should not mechanically expose HTTP paths.

原则：

Principles:

  • CLI 命令按 agent 理解的领域命名，而不是按代码模块或当前 HTTP 路径命名。 / CLI commands are named by agent-facing domains, not by code modules or current HTTP paths.
  • HTTP 是实现细节，CLI contract 是 agent-facing 稳定接口。 / HTTP is an implementation detail; the CLI contract is the stable agent-facing interface.
  • 常用能力应成为命名命令。 / Common capabilities should become named commands.
  • raw HTTP 只允许出现在明确的受控 escape hatch 中，例如 diagnose http get。 / Raw HTTP is allowed only through explicit controlled escape hatches, such as diagnose http get.

例子：

Examples:

  • Assistant rule 的 HTTP endpoint 可能在 /api/skills/assistant-rule/*，但 CLI 应是 config assistants rule ...，因为 rule 是 assistant 行为定义的一部分。 / Assistant rule endpoints may live under /api/skills/assistant-rule/*, but the CLI should expose them as config assistants rule ... because rules are part of assistant behavior definition.
  • Cron 的当前对话任务能力通过 config cron current ... 暴露，而不是旧的 cron-helper。 / Current-conversation cron task management is exposed through config cron current ..., not the old cron-helper.

新增 Agent-facing Domain 的 Checklist / Checklist for New Agent-facing Domains

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

When adding a new domain similar to config or diagnose, complete all of the following:

  1. 在 aioncore capabilities 中注册 domain。 / Register the domain in aioncore capabilities.
  2. 提供 <domain> capabilities，输出完整 agent-readable contract。 / Provide <domain> capabilities with a full agent-readable contract.
  3. 明确 domain mode：read-only、read-write 或更细粒度的风险模型。 / Define the domain mode: read-only, read-write, or a more specific risk model.
  4. 统一 stdin JSON 输入，不用业务 flag。 / Use stdin JSON consistently; do not use business flags.
  5. 统一 stdout JSON envelope。 / Use a consistent stdout JSON envelope.
  6. 统一 stderr 稳定错误码。 / Use stable stderr error codes.
  7. 定义 selector 规则，优先复用 conversation_id: "current"。 / Define selector rules and prefer reusing conversation_id: "current".
  8. 明确敏感字段脱敏策略。 / Define sensitive field redaction policy.
  9. 给每个关键路径加 E2E 覆盖。 / Add E2E coverage for each critical path.
  10. 更新对应内置 skill，只调用 CLI，不再依赖 Python、进程发现或手写 HTTP。 / Update the related built-in skill to call the CLI only, with no Python, process discovery, or handwritten HTTP.

Skill 使用建议 / Skill Usage Guidance

内置 skill 调用顺序：

Recommended built-in skill flow:

  1. 不确定当前 aioncore 支持什么时，先调用： / If unsure what the current aioncore supports, call:

    "$AIONUI_HELPER_BIN" capabilities

  2. 已经知道要配置 AionUi 时，调用： / When configuring AionUi, call:

    "$AIONUI_HELPER_BIN" config capabilities

  3. 已经知道要排查 AionUi 时，调用： / When diagnosing AionUi, call:

    "$AIONUI_HELPER_BIN" diagnose capabilities

  4. 根据 domain contract 执行具体命令。 / Execute specific commands according to the domain contract.

skill 不应该：

Skills should not:

  • 自己查 aioncore 进程。 / Inspect aioncore processes.
  • 自己探测端口。 / Probe ports.
  • 直接调用 Python helper。 / Call Python helpers directly.
  • 用 shell 拼复杂 JSON。 / Build complex JSON through shell string assembly.
  • 把 provider/MCP secret 输出给用户。 / Print provider or MCP secrets to the user.

当前已覆盖范围 / Current Coverage

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

This wiki currently covers these CLI capabilities:

  • 顶级：capabilities / Top-level: capabilities
  • 配置：config capabilities、config context、assistants、skills、MCP、providers、settings、agents、cron / Config: 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 / Diagnose: diagnose capabilities, diagnose context, health, overview, conversations, providers, MCP, cron, teams, logs, controlled HTTP GET

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

If future domains are added, such as channel, office, workspace, or a more specific repair domain, update the top-level capability index first, then add the matching domain contract and skill documentation.

Clone this wiki locally