> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentkit cli SPEC

# AgentKit CLI 文档规范

本规范适用于 `productions/agentkit-cli/preview/{zh,en}` 下的 AgentKit CLI 文档。根目录 `SPEC.md` 是上位规范；若本文件与根规范冲突，以根规范为准。本文件只补充 AgentKit CLI 子文档库的组织、书写和排版要求。

## 内容范围

* 只把 `preview` 作为当前版本来源；`archives` 仅用于已发布版本事实修正，不作为新文档结构的依据。
* AgentKit CLI 文档面向需要安装 CLI、登录、初始化项目、部署运行时、管理资源、执行评测和接入工作流的用户。
* 文档只描述公开命令、公开配置文件、公开工作流与用户可观察行为，不记录内部实现、源码文件或内部管理接口。
* 中英文内容并列维护：`zh` 与 `en` 文件路径、页面层级、参数覆盖范围、示例和警告必须保持等价。

## 目录与导航

`preview` 目录固定为双语结构：

```text theme={null}
productions/agentkit-cli/preview/
├── zh/
│   ├── index.mdx
│   ├── quickstart.mdx
│   ├── agentkit-yaml.mdx
│   ├── commands/
│   └── workflows/
└── en/
    ├── index.mdx
    ├── quickstart.mdx
    ├── agentkit-yaml.mdx
    ├── commands/
    └── workflows/
```

* `index.mdx`：概述 CLI 能力、命令分组与全局约定。
* `quickstart.mdx`：安装、登录和最短部署路径。
* `agentkit-yaml.mdx`：项目根目录 `agentkit.yaml` 与发布配置 `.agentkit/agentkit.yaml` 的配置参考，说明两者对应的命令和使用范围。
* `commands/`：命令参考。每个页面覆盖一个顶级命令组或强相关子命令组。
* `commands/eval/`：评测相关命令参考，按 dataset、evaluator、run、experiment 拆分。
* `workflows/`：端到端场景和最佳实践，例如飞书机器人、前端 SSO、Harness、Codex 沙箱和评测闭环。

新增、删除或移动页面时，必须同步更新 `docs.json` 中 AgentKit CLI 的 Preview 导航，并同步中英文两侧。

## 页面类型

### 概述页

概述页用简短正文说明 CLI 的用途，然后用表格列出命令分组或使用路径。

* 首页可使用 `<CardGroup>` 展示少量核心入口，但不要把所有导航重复成卡片。
* 命令分组表使用 `分组 / 管理内容` 或英文等价列名。
* 约定章节用于说明全局行为，例如配置目录、区域、认证方式、`--json` 输出等。

### 快速开始

快速开始应覆盖最短可用路径：

1. 安装 CLI；
2. 确认版本；
3. 登录或配置鉴权；
4. 初始化项目；
5. 部署并验证结果。

可使用 `<Tabs>` 表示不同安装方式或鉴权方式，使用 `<Steps>` 表示连续操作。每个步骤只完成一个明确动作，并给出可复制命令。

### 命令参考

命令参考页面以命令名作为二级标题，例如 `## runtime list`、`## deploy apply`。每个命令条目按以下顺序书写：

1. 一句话说明命令用途和关键行为。
2. 参数表，列为 `标志/参数`、`说明`、`默认值`。
3. 一个最小可运行示例。
4. 必要时补充交互行为、风险、输出格式或与相近命令的差异。

参数表规则：

* 必填位置参数写作 `` `<runtime>` ``，可选位置参数写作 `` `[name]` ``。
* 短标志与长标志写在同一格，例如 `` `-r, --region <region>` ``。
* 布尔标志默认值写作 `` `false` `` 或 `` `true` ``。
* 无默认值使用 `—`；自动推断写清来源，例如“自动检测”“当前活跃配置”“来自本地配置”。
* 没有选项的命令仍保留参数表，写作 `_（无选项）_ / 该子命令不接受任何选项。 / —`。
* 所有子命令和标志都必须覆盖；不得只写常用标志。

命令更新不能只修改命令总览或 Changelog。新增或变化的子命令、位置参数、标志、别名、默认值、交互提示和破坏性行为必须落到对应命令页；涉及跨命令流程时，再同步更新工作流页面。

### 配置参考

`agentkit-yaml.mdx` 先给完整示例，再按配置块解释字段。配置参考必须：

* 使用 `yaml` 代码块，按对应命令标明项目根目录的 `agentkit.yaml` 或发布配置 `.agentkit/agentkit.yaml`，不能混用两种格式。
* 对每个公开字段给出说明，能确认默认值时给出默认值。
* 凭证使用环境变量或明确占位符，不得写入真实密钥。仅在字段明确支持环境变量插值时使用 `${VAR}`，并说明实际展开方式；项目根目录 `agentkit.yaml` 不会自动展开文件中的此类引用。
* 对自动创建、自动推断、幂等更新等行为写清触发条件和影响。
* 对飞书、企业微信、钉钉、前端、鉴权、基础设施等可选块分别说明，不合并成泛泛描述。

### 工作流与最佳实践

`workflows/` 页面用于完成一个跨命令场景。结构通常为：

1. 首段说明读者会完成什么、会创建或修改哪些资源。
2. 用 `<Note>` 写前置条件，例如账号、权限、控制台准备项和必要凭证。
3. 用 `<Steps>` 展示端到端步骤。
4. 用“要点”或“实践建议”列出关键行为、限制和安全要求。

涉及部署、删除、公开访问、OAuth、飞书 App Secret、API Key、云资源费用等内容时，必须在操作前说明影响范围。

## 排版与组件

* YAML frontmatter 只包含 `title`。
* 标题不使用数字序号；命令名、配置键、文件名和环境变量使用反引号。
* 命令示例主要使用 `bash`，配置使用 `yaml`，流程图使用 `mermaid`。
* 优先使用普通 Markdown 表格；需要提示时使用 Mintlify 组件：
  * `<Note>`：前置条件、背景说明、默认行为。
  * `<Tip>`：推荐做法或效率提示。
  * `<Warning>`：删除、覆盖、发布、费用、安全和不可逆操作。
  * `<Steps>` / `<Step>`：必须按顺序执行的操作流程。
  * `<Tabs>` / `<Tab>`：互斥安装方式、平台或鉴权方式。
* 不要为了视觉效果滥用卡片。卡片只用于入口页的少量重点入口。

## 术语与命名

* 中文正文中的 “agent” 写作「智能体」；命令名、配置键和类名保持原文。
* 产品名保持 `AgentKit CLI`，不要译为“AgentKit 命令行工具”作为正式名称。
* `runtime` 在中文中通常译为「运行时」；`knowledge` 译为「知识库」；`memory` 译为「记忆库」或按语境写「记忆」。
* `profile` 可译为「登录 profile」或「命名配置」，同一页面内保持一致。
* 飞书、企业微信、钉钉、VeFaaS、A2UI、MCP、SSO、OAuth、OIDC、API Key 等按现有文档写法保留。

## 示例与安全

* 命令示例应从用户实际执行目录出发；需要进入项目目录时显式写 `cd <project>`。
* 涉及 `.env`、`.agentkit/agentkit.yaml`、`harness.yaml` 时，明确文件由用户创建或编辑。
* 凭证只使用环境变量或占位符，例如 `${FEISHU_APP_SECRET}`、`your-ak`；不要出现真实内部地址、真实账号或密钥。
* 删除、销毁、覆盖和发布命令必须写清确认参数，例如 `--yes`、`--force`、`--auto-release` 的行为。
* 输出 JSON 的命令必须说明 `--json` 表示原始 JSON 输出，不要推测未验证的字段。

## 版本变更工作流

更新 AgentKit CLI 文档前，先同步目标版本源码，并以该版本的实际 `--help`、公开配置格式和可执行工作流建立影响清单。至少检查：

* 顶级命令、子命令、位置参数、标志、别名、默认值与交互行为；
* `agentkit.yaml`、环境变量、生成文件和公开目录约定；
* 鉴权、区域、项目、镜像、沙箱、A2A、MCP、文件传输和资源生命周期；
* 命令正文、完整参数表、最小示例、工作流、中英文页面和导航。

目标版本必须能够追溯到公开发布 tag 或目标仓库主线。先保存该版本的顶级命令与子命令清单，再比较变更；删除既有命令、参数或工作流说明时，必须有目标版本帮助输出或公开兼容性说明作为依据。来源不属于目标版本的命令设计不得写入 Preview。

对同一源码变更，必须检查已有开放、关闭和已合并文档 PR。关闭但未合并的内容只能作为遗漏线索；合并内容必须继续核对是否完整进入当前主线。不得把旧目录结构、旧版本命令输出或内部实现说明直接搬入 Preview。

功能更新与版本归档必须分开。创建归档前按目标版本重新运行帮助输出并核对 Preview；目标版本之后的命令或配置不得进入归档。

## 更新检查

更新 AgentKit CLI 文档前后至少检查：

* 命令、子命令、标志、默认值与当前 CLI 帮助输出一致。
* 已检查相同源码变更的开放、关闭和已合并文档 PR，并以当前主线为修改基线。
* 已按目标版本建立影响清单，命令正文、参数表、示例、工作流和双语页面均已覆盖。
* `agentkit.yaml` 字段、默认值和自动推断行为与当前 CLI 公开行为一致。
* 中英文页面路径和内容等价。
* 新页面已经加入 `docs.json` Preview 导航。
* 关键示例可复制执行，或已按公开帮助输出核对。
* 已扫描固定旧版本号，确认它们只用于明确的安装、兼容性或复现场景。
* 没有把 `archives` 的过期行为写入 Preview。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.