ark-documentation

Ark 文档

使用 Diataxis 组织 Ark 文档的指南，并根据 Ark 的需求进行调整。

何时使用此指南

• 创建新文档
• 决定内容应放在哪里
• 审阅文档 PR
• 重组现有文档

Ark 的 Diataxis 结构

docs/content/
├── Introduction
├── Quickstart
├── Tutorials          → Linear learning paths
├── How-to Guides      → Task-oriented, by persona
├── Core Concepts      → Understanding "why" and "how"
├── Reference          → Factual lookup material
├── Marketplace        → External link
└── Disclaimer

术语

Diataxis	Ark 术语	原因
解释	核心概念	更易于理解

四个象限

1. 教程（以学习为导向）

目的：为新手提供动手课程。

特点：

• 线性、编号的步骤（1、2、3……）
• 单一的指定路径，不提供选择
• 频繁展示可见结果
• 以“下一步”结尾 → 操作指南

写作风格：

• 使用“我们”的表述
• 不作解释，而是链接到核心概念

以下内容适合放在此处：

• 通过实践教授技能
• 读者是在学习，而不是工作
• 成功需要按顺序完成步骤

示例：快速入门、运行仪表板、启动新项目、完整的实践示例

---

2. 操作指南（以任务为导向）

目的：帮助有经验的用户完成特定任务。

按角色组织：

使用 Ark 构建（应用开发者）

• 配置模型、创建 Agent、协调团队、运行查询、添加工具。

扩展 Ark（贡献者）

• 在本地构建服务、实现 API、构建 A2A 服务端、添加测试。

运维 Ark（运维人员 / SRE / 安全人员）

• 平台运维：资源配置、部署
• CI/CD 和供应链：构建流水线
• 安全与保障：渗透测试、代码分析

写作风格：

• 以目标为导向：“如果你想实现 X，就执行 Y”
• 假定读者具备相应能力
• 不进行教学，而是链接到教程或核心概念

以下内容适合放在此处：

• 读者有要完成的特定任务
• 读者正在工作，而不是学习

---

3. 核心概念（以理解为导向）

目的：解释 Ark 是什么、如何设计，以及为什么这样设计。

主题：

• Ark 是什么，以及它如何工作。
• 设计有效的 Agent 系统。
• 平台架构概念。
• 可扩展性概念。
• 安全与身份概念。

写作风格：

• 采用阐述式表达：“X 的原因是……”
• 建立概念之间的联系
• 提供设计决策的背景

以下内容适合放在此处：

• 回答“为什么”或“它如何工作”
• 读者正在考虑如何设计、扩展或运维
• 内容提供背景信息，而不是操作流程

---

4. 参考（以信息为导向）

目的：供查阅的事实材料。

按类型组织：

• 接口：Ark API、Broker Service。
• Kubernetes API：CRD、资源。
• 系统行为：查询执行、关系。
• 运维：升级、故障排除。
• 项目：贡献者。

写作风格：

• 简洁、客观、中立
• 结构与产品相对应
• 不包含指令、解释或观点

以下内容适合放在此处：

• 描述某项内容是什么
• 读者需要查找具体细节
• 内容供查阅，而非从头到尾阅读

---

决策指南

Is the reader LEARNING or WORKING?
│
├─ LEARNING (studying)
│   ├─ Hands-on, step-by-step? → TUTORIALS
│   └─ Understanding concepts? → CORE CONCEPTS
│
└─ WORKING (applying)
    ├─ Completing a task? → HOW-TO GUIDES
    └─ Looking up facts? → REFERENCE

索引页

索引页通过链接指向内容，不移动文件：

• tutorials.mdx - 按顺序列出教程。
• how-to-guides.mdx - 按角色分类。
• core-concepts.mdx - 按主题分类。
• reference/index.mdx - 按类型分类。

索引页应：

• 用一句话说明用途。
• 合理组织链接。
• 不重复内容。

角色

角色	章节
终端用户	快速入门、教程
Agent 构建者	教程、操作指南（构建）
平台工程师	操作指南（运维）、参考
贡献者	操作指南（扩展）、核心概念

写作指南

词汇表

• 产品名称写作 Ark——首字母大写，rk 小写。绝不可写作 ARK。这与仓库的 CLAUDE.md 一致，并会在审阅中进行检查。

通用风格

• 简洁直接。
• 使用简单的语言。
• 描述控制在 1–2 句。
• 使用主动语态：“创建 Agent”，而不是“Agent 被创建”。
• 写作“Ark”，而不是“ARK”。
• 使用美式英语。
• 列举时使用牛津逗号。

项目符号

• 首词首字母大写，并以句号结尾。
• 仅在说明一系列操作步骤或后文会引用条目时使用编号列表。

大小写

• 仅专有名词（产品名、工具、服务）首字母大写。
• 标题使用句首字母大写格式：“数据可视化简介”，而不是“数据可视化简介”。
• 以下词语不大写：cloud、internet、machine learning、advanced analytics。

标题

• 避免使用动名词：“开始使用”，而不是“开始使用中”；“自定义布局”，而不是“自定义布局中”。
• 标题应简短且具有描述性，便于搜索发现。

操作说明

• 使用祈使句：“完成配置步骤”。
• 不使用“请”。
• 不使用被动语态：“完成这些步骤”，而不是“这些步骤应当被完成”。

链接

• 使用具有描述性的超链接：了解如何[为 Ark 做贡献](url)。
• 不要写：如需贡献，请参阅[此处](url)。

避免使用

• 标题中使用动名词。
• 使用可能不适用于不同地区的口语表达。
• 使用商业行话：“利用”“运用”“促进”。

不要混用的内容

不要在……中放入	此类内容……
教程	解释、选项。
操作指南	教学内容、完整参考资料。
核心概念	操作说明、参考资料。
参考资料	操作说明、解释。

参考页面结构

CRD 和服务参考页面遵循一致的模板。请使用 reference/resources/query.mdx、team.mdx 和 tools.mdx 作为范例：

1. Frontmatter — title 和一条格式为 "<Kind> CRD reference — ..." 的 description。
2. 简介 — 用一段话说明资源是什么，并链接到任务导向的用户指南操作流程；明确说明本页是逐字段参考。
3. ## Spec — 单个带注释的 YAML 示例，注释按必填/可选分组。
4. ## Fields — 包含 Field | Type | Required | Description 列的表格，涵盖枚举值、默认值和字段间规则。
5. 主题章节 — 视情况添加（策略、参数、身份验证等）。
6. ## Status — 状态 YAML 块、### Status fields 表格、存在阶段枚举时的 ### Phases 表格，以及列出 kubectl get 所呈现列的 ### Print columns 行。
7. ## Related — 链接到相关页面。

对于概览/索引页面，请使用一个表格列出每种资源及其 Kind 和 API 版本。不要保留第二个内容重叠的概览页面——一个主题对应一个页面。服务 API 也遵循同样的原则：每项服务对应一个参考页面（Ark API、Broker Service），并将内置 OpenAPI/Swagger 标明为始终最新的事实来源。

准确性：对照源代码核实

参考文档必须忠实反映代码，而不是设计意图或记忆。页面即使读起来合情合理，也仍可能有误——这是最常见的缺陷。编写或审阅参考文档之前，请核实每一项内容：

• 字段、枚举值、默认值 — 阅读 ark/api/v1alpha1/*_types.go 中的 Go 类型，以及 ark/config/crd/bases/ 中生成的 CRD。+kubebuilder:validation:Enum、+kubebuilder:default 和 json 标签具有权威性，现有的文字说明则不是。
• 行为和约束 — 阅读控制器和 webhook（ark/internal/controller/、ark/internal/validation/）。迁移目标、同一命名空间与跨命名空间的解析方式，以及验证规则都在这里。例如：已弃用的 graph 团队策略会迁移为 sequential（丢弃边），而不是 selector——这已在 validation/defaults.go 中得到确认。即使审阅者声称并非如此，也要核实。
• 运行中的集群 — 如果有可用集群，请通过 kubectl explain、kubectl get <kind>（查看打印列）和实际资源 YAML 进行确认。对于服务 API，请访问运行中服务的 /openapi.json 和 Swagger。
• 版本和发布说明 — 检查发布标签，而不是日历。git grep <pattern> <tag> 可以显示某项内容何时变更；git merge-base --is-ancestor <commit> <tag> 可以确认实际发布的内容。未核实前，不要将章节标为“未发布”，也不要引用版本号（例如，实际上并不存在 v0.2.0）。

本次会话改写的文档中发现了大量虚构字段（spec.model、systemPrompt、spec.agents）、不存在的 CLI 命令（ark check、ark describe；实际命令是 devspace run routes，而不是 make routes），以及错误的迁移目标——这些内容所在的页面看起来都没有问题。

推送前构建并预览

• 使用 cd docs && npm run build 构建（Turbopack）。生产构建可以捕获开发服务器会静默容忍的 MDX 和 mermaid 错误，并在成功时显示页面数量。文档更改未经干净构建验证，切勿推送。
• 预览渲染后的页面（开发服务器 + 截图）。Mermaid 图表会延迟渲染——截图前请滚动到图表处，或使用足够高的视口。
• 让图表和文字说明互为补充，而非重复。如果两个页面涉及相关内容（例如 Core Architecture 和 Query Execution Flow，或 Core Concepts 和 Core Architecture 图表），请添加交叉链接，并将读者引导至相应页面，而不要重复说明。

参考资料

• Diataxis Framework
• Issue #338
• PR #620