目录

AI 时代通过引入私域知识库，可以帮助模型更精准地理解私域知识，以便生成更加贴合自身特色的个性化回答。

为了最大程度发挥 AI 生成的效果，需要从两个方面进行实践。一方面是构建高质量的知识库，确保知识数据的质量；另一方面是清晰的知识库权限分配，确保知识库的可见范围符合预期。为此知识库管理员需要：

  • 1、提供 AI 友好的、高质量的知识数据，如文档或代码等，陈旧或不准确的信息不仅无法带来增益，反而可能会误导模型，影响回答的准确性。
  • 2、构建一个结构合理、权限隔离的知识库。这不仅保障了数据的隐私和隔离，还保障了知识库的易管理性和可维护性。权限管理混乱的知识库可能会引发数据安全等问题。

文档规范影响知识库的质量，所以对于私域的文档，需要遵循一定的规范。

中文技术文档编写指南。本文借鉴了多位专家关于中文文档编写的指导原则，收集了适合技术开发人员使用的文档规范清单，并结合实践经验进行整理。

文件命名

  • 建议小写。

    跨平台、易读、与系统目录文件命名错开、方便命令操作。为什么文件名要小写？ - 阮一峰的网络日志

  • 建议用横杠-连接单词。

    建议使用横杠-分隔，而非_。

  • 文件命名尽量不出现空格。

  • 特殊情况。

    为了醒目，某些说明文件的文件名，可以使用大写字母，比如 README.md、LICENSE.md。

标题

  • 1、标题尽量不超过四级。
  • 2、下级标题不重复上级标题名称。
  • 3、标题层级不跳跃，如从#跳到###。
  • 4、标题的命名要有层级关系。
  • 5、上级与下级标题中间可以有引导介绍内容。
  • 6、标题要求简洁概括。尽量做到如果把文章内容删除，只看标题也能够大致知道文章在介绍什么。

段落

  • 1、首行不缩进。

    每段之前空两格是我们从小学写作文就养成的习惯，也是正式文体的格式要求，其目的是为了区分自然段；

    但是像我们现在接触的阅读，都是没有固定的格式要求的，如微信公众号、电子文档等，所以大家一般都采用「空出一行」进行自然段与自然段之间的区分，这种写作方式非常省事，而且很整齐。所以只要没有明确的格式要求，写作的排版无须首行缩进。

  • 2、段落之间使用一个空行隔开。

  • 3、标题一般不用特意使用加粗或斜体。

文本

句子

  • 1、避免使用长句。

    句子长度尽量保持在 20 个字以内，20～29 个字的句子，可以接受；30～39 个字的句子，语义必须明确，才能接受；多于 40 个字的句子，任何情况下都不能接受。

    错误：本产品适用于从由一台服务器进行动作控制的单一节点结构到由多台服务器进行动作控制的并行处理程序结构等多种体系结构。

正确：本产品适用于多种体系结构。无论是由一台服务器（单一节点结构），还是由多台服务器（并行处理结构）进行动作控制，均可以使用本产品。

  • 2、尽量使用简单句和并列句，避免使用复合句。

    并列句：他昨天生病了，没有参加会议。

复合句：那个昨天生病的人没有参加会议。

  • 3、尽量使用肯定句，少使用否定句表达。

    错误：请确认没有接通装置的电源。

正确：请确认装置的电源已关闭。

  • 4、避免使用双重否定句。

    错误：没有删除权限的用户，不能删除此文件。

正确：用户必须拥有删除权限，才能删除此文件。

  • 5、尽量使用主动语态，少使用被动语态。

    错误：假如此软件尚未被安装，

正确：假如尚未安装这个软件，

  • 6、正式文档尽量书面化。

    错误：Lady Gaga 的演唱会真是酷毙了，从没看过这么给力的表演！！！

正确：无法参加本次活动，我深感遗憾。

    注：对于一些非正式结果文档，我们觉得允许个性化，允许俏皮话。

  • 7、尽量使用现代汉语常用表达方式，避免不顺畅的文言文。

    错误：这是唯二的快速启动的方法。

正确：这是仅有的两种快速启动的方法。

  • 8、用对“的”、“地”、“得”。

    她露出了开心的笑容。
（形容词＋的＋名词）

她开心地笑了。
（副词＋地＋动词）

她笑得很开心。
（动词＋得＋副词）

    注：别小看这个建议，很多时候，为了简便、快速，可能就让输入法自由输出了。

  • 9、名词前不要使用过多的形式词。

    错误：此设备的使用必须在接受过本公司举办的正式的设备培训的技师的指导下进行。

正确：此设备必须在技师的指导下使用，且指导技师必须接受过由本公司举办的正式设备培训。

空格与间距

  • 1、中文与英文之间一般需要增加空格。

    比如：Google、Facebook 和 Apple ID 等。

  • 2、中文与数字之间一般需要增加空格。

    比如：iOS MDM 服务提供 10 个接口能力。

  • 3、中文全角标点与英文单词之间不需要空格。

    比如：刚刚收到了一台 iPhone，这是一台测试机。

  • 4、数字与单位之间，不建议有空格。

    比如：MongoDB 中的 notifications 集合存储大小为 25GB。

    争议：有些文章作者会建议有空格。我们不建议有空格。

标点符号

  • 1、中文语句的标点符号，均应该采取全角符号，这样可以与全角文字保持视觉上的一致。

  • 2、如果整句为英文，则该句使用英文/半角标点符号。

  • 3、句号、问号、叹号、逗号、顿号、分号和冒号不应该出现在行首。

  • 4、点号（句号、逗号、顿号、分号、冒号）不应该出现在标题的末尾，而标号（引号、括号、破折号、省略号、书名号、着重号、间隔号、叹号、问号）可以。

  • 5、中文语句结尾必须用上全角句号。

    标题不是句子，所以不建议用上点号，而中文语句是个完整的句子，需要用上句号。

  • 6、避免一逗到底，应该有断句。

  • 7、并列词应该使用顿号。

    比如：Google、Facebook 和 Apple ID 等。

  • 8、分号用于并列分句。

  • 9、表示时间时，使用半角冒号:。

    比如 8:00 。

  • 10、避免使用。。。非标准形式的省略号。

  • 11、全角与半角避免混用。

    比如：在中文句子里应该使用全角（）,在英文句子里应该使用半角()。

数值

  • 1、阿拉伯数字使用半角，不使用全角。

    错误：这件商品的价格是 １０００ 元。

正确：这件商品的价格是 1000 元。

  • 2、建议使用千分号。

    XXX 公司的实收资本为 ￥1,258,000 人民币。

    对于 4 位的数值，千分号是选用的，比如 1000 和 1,000 都可以接受。对于 4 位以上的数值，应添加千分号。

  • 3、数值范围。

    表示数值范围时，用波浪线（～）或横杠（—）连接。

    100~200

67%～89%

  • 4、变化程度。

    数字的增加要使用“增加了”、“增加到”。“了”表示增量，“到”表示定量。

    增加到过去的两倍
（过去为一，现在为二）

增加了两倍
（过去为一，现在为三）

    数字的减少要使用“降低了”、“降低到”。“了”表示增量，“到”表示定量。

    降低到百分之八十
（定额是一百，现在是八十）

降低了百分之八十
（原来是一百，现在是二十）

名词

  • 专有名词使用正确的大小写。

    建议：
GitHub、iOS、iPhone 6s、MacBook Pro、Google、Android、Facebook、JavaScript、HTML5

不建议：
github、IOS、iphone 6s、macbook pro

结构风格

总 - 分 - 总的结构风格。

  • 总

    文首先告诉读者会读到什么，如果读者不感兴趣的话可以省下来读一篇文章的时间，而如果感兴趣的话正好是个好引子。

  • 分

    分散表达需要表达的几个观点。

  • 总

    最后总结文章，要假设读者并没有时间详读全文，但这里的总结可以让读者能在 10 秒内仍然知道你在这篇文章里表达了什么或结论是什么。

可能遇到的坑

  • 内部链接引用 md 文件，要用绝对路径。
  • 表格的第二行 |–| 数量要和第一行列名对应。
  • 非 md 内链直接用外链到 gitLab。
  • 每页 md 文件有且只有一个 # 一级标题，就是总标题。
  • 如果内容中有类似 19:30:00的时间，会被转义为 emoji 表情，可以包含在``中。

工具

我们可以通过命令行或 IDE 工具实现自动检查和纠正不规范的句子。

注：为了避免保存时，扩展工具未提前告知自动调整格式保存，找到对应工具下的配置，不开启保存格式化或Format On Save。

参考

9ong@TsingChan 2025 markdown