Back to Details

axi

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent eXperience Interface (AXI)

Agent eXperience Interface (AXI)

AXI defines ergonomic standards for building CLI tools that autonomous agents interact with through shell execution.
AXI定义了构建供自主Agent通过shell执行交互的CLI工具的人机工程标准。

Before you start

开始之前

Read the TOON specification before building any AXI output.
在构建任何AXI输出前，请先阅读TOON规范。

1. Token-efficient output

1. 令牌高效输出

Use TOON (Token-Oriented Object Notation) as the output format on stdout. TOON provides ~40% token savings over equivalent JSON while remaining readable by agents. Convert to TOON at the output boundary — keep internal logic on JSON.
tasks[2]{id,title,status,assignee}:
  "1",Fix auth bug,open,alice
  "2",Add pagination,closed,bob
在stdout上使用TOON（Token-Oriented Object Notation）作为输出格式。 与等效的JSON相比，TOON可节省约40%的令牌，同时仍可被Agent读取。 在输出边界转换为TOON格式——内部逻辑仍使用JSON。
tasks[2]{id,title,status,assignee}:
  "1",Fix auth bug,open,alice
  "2",Add pagination,closed,bob

2. Minimal default schemas

2. 最小化默认schema

Every field in stdout costs tokens — multiplied by row count in collections. Default to the smallest schema that lets the agent decide what to do next: typically an identifier, a title, and a status.
  • Default list schemas: 3-4 fields, not 10
  • Default limits: high enough to cover common cases in one call (if most repos have <100 labels, default to 100, not 30)
  • Long-form content (bodies, descriptions) belongs in detail views, not lists
  • Offer a 
    --fields
    flag to let agents request additional fields explicitly
stdout中的每个字段都会消耗令牌——消耗总量会乘以集合中的行数。 默认使用能让Agent决定下一步操作的最小schema：通常包含标识符、标题和状态。
  • 默认列表schema：3-4个字段，而非10个
  • 默认限制：足够高以覆盖单次调用的常见场景（如果大多数仓库的标签数<100，默认设为100，而非30）
  • 长文本内容（正文、描述）应放在详情视图中，不要放在列表里
  • 提供
    --fields
    参数，允许Agent显式请求额外字段

3. Content truncation

3. 内容截断

Detail views often contain large text fields. Omitting them forces agents to hunt; including them wastes tokens. Truncate by default and tell the agent how to get the full version.
task:
  number: 42
  title: Fix auth bug
  state: open
  body: First 500 chars of the issue body...
    ... (truncated, 8432 chars total)
help[1]: Run `tasks view 42 --full` to see complete body
  • Never omit large fields entirely — include a truncated preview
  • Show the total size so the agent knows how much it's missing
  • Suggest the escape hatch (
    --full
    ) only when content is actually truncated
  • Choose a truncation limit that covers most use cases (500-1500 chars)
详情视图通常包含大文本字段。完全省略会迫使Agent额外查找，完全包含则会浪费令牌。 默认进行截断，并告知Agent如何获取完整版本。
task:
  number: 42
  title: Fix auth bug
  state: open
  body: First 500 chars of the issue body...
    ... (truncated, 8432 chars total)
help[1]: Run `tasks view 42 --full` to see complete body
  • 永远不要完全省略大字段——保留截断后的预览
  • 显示内容总大小，让Agent知道缺失了多少内容
  • 仅当内容确实被截断时，才提供解决方案（
    --full
    ）建议
  • 选择能覆盖大多数场景的截断长度（500-1500字符）

4. Pre-computed aggregates

4. 预计算聚合数据

The most expensive token cost is often not a longer response — it's a follow-up call. If your backend has data that agents commonly need as a next step, compute it and include it.
Aggregate counts: include the total count in list output, not just the page size. Agents need "how many are there?" and will paginate if the answer isn't definitive.
count: 30 of 847 total
tasks[30]{number,title,state}:
  1,Fix auth bug,open
  ...
Derived status fields: when the next step almost always involves checking related state, include a lightweight summary inline.
task:
  number: 42
  title: Deploy pipeline fix
  state: open
  checks: 3/3 passed
  comments: 7
Only include derived fields your backend can provide cheaply — a summary ("3/3 passed"), not the full data.
最高的令牌消耗往往不是更长的响应，而是后续的额外调用。如果你的后端有Agent下一步通常需要的数据，提前计算并包含在响应中。
聚合计数：在列表输出中包含总计数，而不仅是当前页大小。Agent需要知道“总共有多少条”，如果没有明确的答案，他们会进行分页查询。
count: 30 of 847 total
tasks[30]{number,title,state}:
  1,Fix auth bug,open
  ...
衍生状态字段：当下一步操作几乎总是需要检查关联状态时，在内联响应中包含轻量摘要。
task:
  number: 42
  title: Deploy pipeline fix
  state: open
  checks: 3/3 passed
  comments: 7
仅包含后端可以低成本提供的衍生字段——只需摘要（如“3/3 passed”），无需完整数据。

5. Definitive empty states

5. 明确的空状态

When the answer is "nothing", say so explicitly. Ambiguous empty output causes agents to re-run with different flags to verify.
$ tasks list --state closed
tasks: 0 closed tasks found in this repository
State the zero with context. Make it clear the command succeeded — the absence of results is the answer.
当查询结果为“无”时，要明确说明。模糊的空输出会导致Agent使用不同参数重新运行命令进行验证。
$ tasks list --state closed
tasks: 0 closed tasks found in this repository
给出带上下文的零值说明，明确表明命令执行成功——没有结果本身就是答案。

6. Structured errors & exit codes

6. 结构化错误与退出码

Idempotent mutations

幂等变更操作

Don't error when the desired state already exists. If the agent closes something already closed, acknowledge and move on with exit code 0. Reserve non-zero exit codes for situations where the agent's intent genuinely cannot be satisfied.
$ tasks close 42
task: #42 already closed (no-op)    # exit 0
当目标状态已存在时不要返回错误。如果Agent要关闭的对象已经是关闭状态，确认状态后返回退出码0继续执行。仅当Agent的意图确实无法满足时，才使用非零退出码。
$ tasks close 42
task: #42 already closed (no-op)    # exit 0

Structured errors on stdout

stdout输出结构化错误

Errors go to stdout in the same structured format as normal output, so the agent can read and act on them. Include what went wrong and an actionable suggestion. Never let raw dependency output (API errors, stack traces) leak through.
error: --title is required
help: tasks create --title "..." [--body "..."]
  • Validate required flags before calling any dependency
  • Translate errors — extract actionable meaning, discard noise
  • Never leak dependency names — suggestions reference your CLI's commands, not the underlying tool
错误信息与正常输出使用相同的结构化格式输出到stdout，方便Agent读取和处理。要包含错误原因和可执行的解决方案。永远不要暴露原始依赖输出（API错误、栈追踪）。
error: --title is required
help: tasks create --title "..." [--body "..."]
  • 在调用任何依赖前先校验必填参数
  • 对错误进行转译——提取可执行的含义，丢弃无关信息
  • 永远不要暴露依赖名称——建议中只引用你的CLI命令，不要提及底层工具

No interactive prompts

无交互式提示

Every operation must be completable with flags alone. If a required value is missing, fail immediately with a clear error — don't prompt for it. Suppress prompts from wrapped tools.
所有操作必须仅通过参数即可完成。如果缺少必填值，立即返回明确错误，不要进行交互式提示。禁用封装工具的提示功能。

Output channels

输出通道

  • stdout: all structured output the agent consumes — data, errors, suggestions
  • stderr: debug logging, progress indicators, diagnostics (agents don't read this)
  • Exit codes: 0 = success (including no-ops), 1 = error, 2 = usage error
Never mix progress messages into stdout. An agent that reads "Fetching data..." will try to interpret it as data.
  • stdout：Agent消费的所有结构化输出——数据、错误、建议
  • stderr：调试日志、进度指示器、诊断信息（Agent不会读取该通道内容）
  • 退出码：0 = 成功（包含无操作场景），1 = 错误，2 = 使用方式错误
永远不要将进度信息混入stdout。Agent读到“Fetching data...”这类内容时，会尝试将其作为数据解析。

7. Ambient context via session hooks

7. 通过会话钩子传递上下文

Register your tool into the agent's session lifecycle so every conversation starts with relevant state already visible — before the agent takes any action.
Pattern:
  1. On first invocation, self-install hooks into the agent's configuration (idempotently)
  2. At session start, a hook runs your tool and outputs a compact dashboard to stdout
  3. The agent receives this as initial context and can act immediately
undefined
将你的工具注册到Agent的会话生命周期中，这样每次会话开始时，Agent无需执行任何操作即可看到相关状态。
模式：
  1. 首次调用时，（幂等地）自动将钩子安装到Agent的配置中
  2. 会话启动时，钩子会运行你的工具，并将精简的仪表盘输出到stdout
  3. Agent会将该内容作为初始上下文接收，并可以立即采取行动
undefined

Agent sees this at session start — no invocation needed:

Agent sees this at session start — no invocation needed:

specs[2]{id,title,status}: 1,Fix auth bug,open 2,Add pagination,in-progress
help[2]: Run 
mytool specs view 1
for details Run 
mytool specs create --title "..."
to add a spec

**Rules:**

- **Default app targets**: by default, support Claude Code and Codex. Do not hard-code a single agent integration when the tool can reasonably support both
- **Self-installing**: register hooks at global/user level on first run — no manual setup required
- **Absolute paths**: hook commands must use the full absolute path of the current executable (via `os.Executable()` or equivalent), not a bare command name. This ensures hooks work regardless of the agent's `$PATH` at runtime
- **Path repair**: on every invocation, check existing hooks and update the executable path if it has changed (e.g., after reinstall or relocation). This turns self-install into self-heal
- **Idempotent**: repeated installs with the same path are silent no-ops
- **Directory-scoped**: show only state relevant to the current working directory
- **Token-budget-aware**: this context loads on _every_ session — ruthlessly minimize it. Include just enough for the agent to orient and act; deep data belongs in explicit invocations
- **Lifecycle capture**: use session-end hooks to capture what happened (transcripts, files touched, specs referenced) so future session-start context gets richer over time

**How to integrate with each app:**

- **Claude Code**: use native hooks in `~/.claude/settings.json` or project `.claude/settings.json`. Prefer `SessionStart` to inject compact context via stdout
- **Codex**: use native hooks in `~/.codex/hooks.json` or `<repo>/.codex/hooks.json`, and ensure `[features].codex_hooks = true` in `config.toml`. Prefer `SessionStart` for ambient context via stdout
specs[2]{id,title,status}: 1,Fix auth bug,open 2,Add pagination,in-progress
help[2]: Run 
mytool specs view 1
for details Run 
mytool specs create --title "..."
to add a spec

**规则：**

- **默认支持多平台**：默认支持Claude Code和Codex。如果工具可以合理支持多个Agent，不要硬编码仅集成单个Agent
- **自动安装**：首次运行时在全局/用户级别注册钩子——无需手动配置
- **绝对路径**：钩子命令必须使用当前可执行文件的完整绝对路径（通过`os.Executable()`或等效方法获取），不要使用裸命令名。这可以确保无论Agent运行时的`$PATH`是什么，钩子都能正常工作
- **路径修复**：每次调用时，检查现有钩子，如果可执行文件路径发生变化（例如重装或移动位置后），则更新路径。将自动安装升级为自动修复
- **幂等性**：使用相同路径重复安装时，静默无操作
- **目录范围**：仅展示与当前工作目录相关的状态
- **令牌预算感知**：这个上下文会在_每次_会话加载——要尽可能精简。仅包含足够Agent定位和行动的信息，深层数据应放在显式调用的返回中
- **生命周期捕获**：使用会话结束钩子捕获会话中发生的内容（对话记录、修改的文件、引用的规范），这样未来的会话启动上下文会越来越丰富

**各平台集成方式：**

- **Claude Code**：使用`~/.claude/settings.json`或项目`.claude/settings.json`中的原生钩子。优先使用`SessionStart`通过stdout注入精简上下文
- **Codex**：使用`~/.codex/hooks.json`或`<repo>/.codex/hooks.json`中的原生钩子，并确保`config.toml`中`[features].codex_hooks = true`。优先使用`SessionStart`通过stdout注入上下文

8. Content first

8. 内容优先

Running your CLI with no arguments should show the most relevant live content — not a usage manual. When an agent sees actual state it can act immediately. When it sees help text, it has to make a second call.
$ tasks
tasks[3]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,open
  3,Update docs,closed
help[2]:
  Run `tasks view <id>` to see full details
  Run `tasks create --title "..."` to add a task
不带参数运行你的CLI时，应展示最相关的实时内容——而不是使用手册。 当Agent看到实际状态时可以立即采取行动，当它看到帮助文本时，就需要进行第二次调用。
$ tasks
tasks[3]{id,title,status}:
  1,Fix auth bug,open
  2,Add pagination,open
  3,Update docs,closed
help[2]:
  Run `tasks view <id>` to see full details
  Run `tasks create --title "..."` to add a task

9. Contextual disclosure

9. 上下文引导

Include a few next steps that follow logically from the current output. The agent discovers your CLI's surface area organically by using it, not by reading a manual upfront.
Rules:
  • Relevant: after an open item → suggest closing; after an empty list → suggest creating; after a list → suggest viewing
  • Actionable: every suggestion is a complete command (or template) carrying forward any disambiguating flags from the current invocation (e.g., 
    --repo
    , 
    --source
    )
  • Parameterize dynamic values: when a suggested command needs a runtime value such as an ID, title, branch, URL, or path, use placeholders like 
    <id>
    or 
    "<title>"
    instead of guessing a concrete value that may mislead the agent
  • Omit when self-contained: when the output fully answers the query (a detail view, a count, a confirmation), suggestions are noise — leave them out. Include them on list and mutation responses where the next step isn't obvious.
  • Guide discovery, not workflows: suggest a variety of possible next actions, don't prescribe a fixed sequence. An agent that already knows what it wants should never be nudged into an extra step.
  • Reveal truncated lists: when a list shows only the most recent N items out of a larger total, add a help hint telling the agent how to see all of them (e.g., 
    Run 'mytool list' for all 47 items
    ). Don't encode pagination into TOON array headers — use help hints instead.
  • Resolve errors: on errors, suggest the specific command that fixes the problem, not "see 
    --help
    "
在当前输出后附带几个逻辑上合理的下一步操作建议。 Agent可以在使用过程中自然发现你的CLI的功能范围，无需提前阅读手册。
规则：
  • 相关性：打开一个项目后 → 建议关闭；空列表后 → 建议创建；列表返回后 → 建议查看详情
  • 可执行：每个建议都是完整的命令（或模板），携带当前调用中所有用于区分上下文的参数（例如
    --repo
    、
    --source
    ）
  • 动态值参数化：当建议命令需要ID、标题、分支、URL或路径等运行时值时，使用
    <id>
    或
    "<title>"
    这类占位符，不要猜测可能误导Agent的具体值
  • 自包含内容省略建议：当输出完全回答了查询（详情视图、计数、确认信息），建议就是多余的——不要添加。仅在下一步操作不明确的列表和变更操作响应中添加建议
  • 引导发现而非规定流程：建议多种可能的下一步操作，不要规定固定的顺序。已经明确目标的Agent不应该被引导执行额外步骤
  • 提示截断列表：当列表仅展示了总数中的最新N条时，添加帮助提示告知Agent如何查看所有内容（例如
    Run 'mytool list' for all 47 items
    ）。不要在TOON数组头中编码分页信息——使用帮助提示替代
  • 错误解决方案：出错时，建议解决问题的具体命令，而不是“查看
    --help
    ”

10. Consistent way to get help

10. 统一的帮助获取方式

The top-level home view should also identify the tool itself before the live data:
  • Include the absolute path of the current executable, with the user's home directory collapsed to 
    ~
  • Include a one-sentence description of what this AXI does
$ tasks
bin: ~/.local/bin/tasks
description: Manage project tasks in the current workspace
...
Every subcommand should support 
--help
with a concise, complete reference: available flags with defaults, required arguments, and 2-3 usage examples. Keep it focused on the requested subcommand — don't dump the entire CLI's manual.
顶级首页视图在展示实时数据前，也应该说明工具本身的信息：
  • 包含当前可执行文件的绝对路径，将用户主目录缩写为
    ~
  • 包含一句说明该AXI功能的描述
$ tasks
bin: ~/.local/bin/tasks
description: Manage project tasks in the current workspace
...
每个子命令都应支持
--help
参数，提供简洁完整的参考：可用参数及默认值、必填参数、2-3个使用示例。内容聚焦于当前查询的子命令——不要输出整个CLI的手册。