​

AgentKit CLI 文档规范

​

内容范围

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

​

目录与导航

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 沙箱和评测闭环。

​

页面类型

​

概述页

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

​

快速开始

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

​

命令参考

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

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

​

配置参考

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

​

工作流与最佳实践

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

​

排版与组件

• 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.yaml、环境变量、生成文件和公开目录约定；
• 鉴权、区域、项目、镜像、沙箱、A2A、MCP、文件传输和资源生命周期；
• 命令正文、完整参数表、最小示例、工作流、中英文页面和导航。

​

更新检查

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