文档是 Alius 与用户沟通的核心载体。统一的文档结构能降低用户的查找成本，提升内容的可读性和可维护性。

文档页面结构

每一篇文档都应遵循统一的内容结构，从上到下依次为：

标题

• 每篇文档只有一个一级标题
• 标题应简短、准确、概括页面主题
• 不超过 15 个中文字符
• 不使用问句形式（FAQ 除外）

一行摘要

紧跟标题下方，用一句话概括本篇文档的内容。

• 不超过 50 个中文字符
• 使用陈述句，不用描述性从句
• 帮助用户快速判断是否需要阅读全文

目标读者

说明本文档面向的读者群体。

• 使用标签或列表形式
• 如：“面向初次使用 Agent CLI 的开发者”
• 如：“面向需要集成 Alius SDK 的硬件工程师”
• 帮助用户确认本文档是否适合自己

前置条件

列出阅读或执行本文档内容前需要满足的条件。

• 使用列表形式，每项一个条件
• 包含已完成的步骤、已安装的工具、已有的权限
• 格式示例：“已完成 Agent CLI 安装”、“拥有至少一台已连接的机器人设备”
• 为每个前置条件提供跳转链接到对应的安装或配置文档

正文结构

步骤指引

操作类文档使用编号步骤格式。

• 每个步骤以编号开头：第一步、第二步，或 1、2、3
• 每个步骤包含：操作说明、预期结果、可能遇到的问题
• 步骤之间有明确的因果关系
• 长步骤可拆分为子步骤
• 每个步骤不超过 3 个子操作

示例代码

涉及编程或配置的文档必须提供完整的示例代码。

• 代码块标注语言类型（bash、python、yaml、json 等）
• 代码必须是可运行的完整示例，不是片段
• 关键行添加行内注释说明
• 代码块提供复制按钮
• 如有多种实现方式，分别提供示例并说明适用场景

参数说明

涉及配置项或 API 的文档必须提供参数说明表格。

• 表格包含：参数名、类型、是否必填、默认值、说明
• 参数名使用等宽字体
• 类型标注准确：string、number、boolean、array、object
• 默认值列标注”无”表示没有默认值
• 说明列简短描述参数用途和取值范围

常见问题 FAQ

文档末尾提供常见问题的解答。

• 使用问句作为标题
• 按出现频率排序，最常见的问题在最前
• 每个问题提供具体的解决方案
• 引用文档内相关章节或外部资源链接
• 如果问题列表过长，考虑拆分为独立的故障排除页面

下一步

文档末尾提供”下一步”引导，帮助用户继续学习路径。

• 列出 2-4 个推荐的后续阅读内容
• 每项包含标题和简要说明
• 使用链接跳转到对应文档
• 引导顺序应符合从入门到进阶的学习曲线

相关资源

提供与本文档相关的额外资源链接。

• 关联文档、API 参考、示例项目、社区讨论
• 使用列表形式，每项附带简要说明
• 不超过 5 个链接
• 避免重复引用正文中已出现的链接

写作规范

语言与语气

• 使用标准中文书写
• 语气平和、专业、不居高临下
• 使用”你”而非”您”
• 不使用感叹号（错误提示除外）
• 不使用口语化表达

格式规范

• 一级标题（#）仅用于页面标题
• 二级标题（##）用于主要章节
• 三级标题（###）用于子章节
• 标题层级不跳级（如 ## 后不直接跟 ####）
• 列表项使用 - 符号
• 有序列表使用数字编号

代码规范

• 命令行示例使用 bash 语法高亮
• 命令前使用 $ 提示符
• 输出结果与命令分开展示
• 路径使用相对路径或明确标注绝对路径
• 占位符使用大写：YOUR_API_KEY、YOUR_DEVICE_ID

链接规范

• 优先使用站内链接
• 外部链接标注来源
• 链接文字应描述目标内容，不使用”点击这里”
• 链接定期检查有效性