AingDesk文档规范

AingDesk是一款简单好用的AI助手，支持知识库、模型API、分享、联网搜索、智能体、MCP，它还在飞快成长中。

文档规范

本文档旨在规范AingDesk所有对外文档（包括但不限于产品文档、API文档、白皮书文档等）的基本格式及风格。AingDesk文档书写语法为Markdown，关于Markdown的更多信息，可参考https://github.github.com/gfm/

注：本标准参考腾讯云文档写作规范。

总体方针	以解决用户问题为目标，注重场景化。 遵循5W1H分析法： （What）这是什么产品？ （Who）针对哪些客户群体？ （Why）我为什么要使用这个产品？这个产品解决什么问题？ （When+Where）使用产品的具体场景是什么？ （How）怎么使用这个产品？ 分清读者对象，按不同的类型、不同层次的读者，决定怎样适应他们的需要。
基本方法论	关注一致性、准确性（上下文、文字、标点符号与图片） 把可能使用的名词、缩略语都在文首列出，避免文档中出现从未见过的名词。注意标点的正确使用，截图中出现的文字与说明需保持强一致性。 例子：堡塔企业级防篡改（又称防篡改）
	清晰、易读 关注文档结构，构建易读的索引。 多使用图、表，增强易懂性。同时注意图表的清晰度，规范统一的图表风格

1. 字体、颜色规范

AingDesk在线文档均在Github统一编辑发布，采用Markdown编写方式，文档中的的字体、颜色请保持默认风格，不要使用特殊字体、颜色。 AingDesk离线文档统一为PDF格式，请使用Markdown编辑器编写，有形如以上的规范。

2. 标题/列表规范

文档标题有形如下的格式规范，目录从一级开始，最多可到第三级。（三级以上的标题不符合常规阅读需求，请拆分或使用标题内的列表进行相应处理）

标题层级	显示样式	Markdown语法
第一级标题	## 第一级标题	Markdown请注意采用二级‘##’语法，对应Word字号为22.5
第二级标题	### 第二级标题	Markdown请注意采用三级‘###’语法，对应Word字号为17.5
第三级标题	#### 第三级标题	Markdown请注意采用四级‘####’语法，对应Word字号为13

内容列表有形如下的格式规范：

列表层级	显示样式
正文第一级列表	1. 列表项一 2. 列表项二
列表中的第二级列表	1. 列表项一 这是一段说明 1) 二级列表项一 2) 二级列表项二
二级列表中的第三级列表	1. 列表项一 这是一段说明 1) 二级列表项一 这是另一段说明 A. 三级列表项1 B. 三级列表项2 2) 二级列表项二

3. 特殊表达及标点规范

特殊表达	表达方式	说明
强调	粗体+斜体+前后空格	非普通文字和短语或重要文字和短语的特殊标记。 </td>
正文中的参数、表达式或代码	内联代码	必须使用内联代码标识正文中的参数、表达式或代码。Markdown语法为 ``
代码块	文档中出现的完整代码	与正文分开，使用代码块标识。Markdown语法为``` ```
界面标志	【中文方括号】	标识 UI 上的指定内容以便识别。 在【云服务器】选项卡中，点击【新建】按钮。
交叉引用/外链	超链接	多使用超链接进行文档间关系的建立。 产品文档中引用的链接地址请统一直接拷贝磐石产品文档中的相对路径，/document/product/ +数字路径，例如/document/product/213/6090。
互斥参数	(圆括号 | 和 | 竖 | 线)	代码中，分割线表示必须从中选择一个选项的选项集。 % data = hdfread (start | stride | edge)
可选参数	[英文方括号]	代码中，方括号表示完全可选的命令或参数。 ssh [-l, -q] root@10.10.10.10
变量	<箭头括号>	代码中，箭头括号表示必须替换为有效值的变量。 mount /dev/vdb1 %<%your-mountpoint>

4. 文档风格规范

文案风格

1. 一定多检查，确保没有错别字。即使是流行语中的谐音错别字也不要使用，比如”墙裂”、”童鞋”、“程序猿”等。
2. 段落之间使用一个空行隔开。段落开头 不要 留出空白字符。
3. 请把对表达意思没有明显作用的字、词、句删除，在不影响表达效果的前提下把文案长度减到最短。
4. 避免口语，使用规范的书面语。例子：避免使用“么”、“喔”、“挂掉”等口语词汇。
5. 尽量避免中英文混杂。
6. 请一定注意“的”、“地”、“得”的用法。
7. 第一人称：推荐使用“AingDesk”、“我们”，不推荐使用“小编”、“笔者”。
8. 避免多介词的复合长句。注意句子成分要齐全。

例如： 改前：对于apt-get下载源，不需要添加软件源，可以直接安装软件包。为了加速软件安装，目前系统已经在内网预先配置了Ubuntu的mirror，这个mirror是官网x86_64的完全镜像，与官网源一致。

改后：对于apt-get下载源，不需添加软件源则可直接安装软件包。为了加速软件安装，腾讯云已在内网预先配置了Ubuntu的x86_64完全镜像，与官方源一致。

中文、英文、数字混排时空格的使用

1. 英文与非标点的中文之间需要有一个空格。如“使用宝塔一键迁移 API 版本迁移网站”而不是“使用宝塔一键迁移API版本迁移网站”。
2. 尽可能使用中文数词，特别是当前后都是中文时。例如：“我们发布了五个产品”。

标点相关

1. 只有中文或中英文混排中，一律使用中文 / 全角标点
2. 中英文混排中如果出现整句英文，则在这句英文中使用英文 / 半角标点。
3. 省略号：请使用”……“标准用法，不要使用”。。。“。
4. 感叹号：请勿使用”！！“。尽量避免使用”！“。请先冷静下来再坐电脑前敲键盘。
5. 波浪号：请勿在文章内使用“~”，活泼地卖萌有很多其他的表达方式。

一些常用名词的正确用法

正确使用	错误使用
App / 应用	APP、软件、程序
Android	android、安卓
iOS	ios、IOS
iPhone	IPHONE、iphone
App Store	AppStore、app store
WiFi	wifi、Wifi、Wi-fi
email	E-mail、Email
IP	Ip、ip