DocAgent规则体系揭秘：.lingma目录角色设定与触发机制完全指南
DocAgent规则体系揭秘：.lingma目录角色设定与触发机制完全指南
DocAgent 是一款专为仓颉语言打造的文档助手，核心在于 .lingma 目录中的规则体系：通过角色设定、触发机制与 JSON Schema 校验，让大模型智能体自动完成文档的编写、优化与重构。本文将带你完整解析这套规则系统的设计逻辑。
.lingma 目录结构一览
整个 DocAgent 的"大脑"都藏在 .lingma 目录里，它由三部分协作完成文档生成流水线：
| 目录/文件 | 职责 | 说明 |
|---|---|---|
| rules/readme.md | 规则总纲 | 角色设定 + 加载所有子规则 |
| rules/module_api.md | API 转换规则 | 将 Markdown 转为结构化 JSON |
| rules/module_index.md | 目录索引规则 | 按功能分组重构包入口 |
| schema/api.schema.json | 格式校验 | 校验 API JSON 输出 |
| schema/index.schema.json | 格式校验 | 校验索引 JSON 输出 |
| bin/ | 文档生成器 | cjdocgen 命令的执行核心 |
这种分层设计非常巧妙：智能体负责"想"，Schema 负责"查"，生成器负责"写"，既保证了智能化，又确保了输出质量的一致性。
角色设定：智能体如何成为"颉哥"
readme.md 是整个规则体系的总纲，文件开头的元数据定义了它的触发方式：
---
trigger: always_on
---
always_on 意味着这条规则每次对话都会自动加载，它做了三件关键的事：
- 身份设定：智能体自称"颉哥"，一位经验丰富的编程语言文档工作者，优先使用中文、以质量为准，遇到存疑问题及时标注而非掩盖
- 规则入口声明：明确要求智能体以该文件为入口，加载
./.lingma/rules/下的所有规则；仓库中其他文件只能作为触发条件与输入信息，不能视作规则文件 - 红线约束：严格强调"在不符合触发条件的情况下工作是致命的错误"，防止智能体在无关场景乱用规则
这套设定的价值在于：它把一个通用大模型"驯化"成了领域专家，同时用硬约束防止了 AI 最容易出现的问题——在错误的时机做正确的事。
触发机制：两条规则如何按需生效
与总纲不同，两条子规则都采用条件触发模式，只有用户指令命中触发条件时才生效。
触发机制对比
| 规则文件 | 触发条件 | 输出位置 | 校验 Schema |
|---|---|---|---|
| module_api.md | 用户要求转换某文档，如"转换 test.md" | [库名]_package_index/ 目录 |
api.schema.json |
| module_index.md | 用户要求转换包的目录文档，如"转换 test 包的目录" | 包根目录 [包名]_package_readme.json |
index.schema.json |
module_api.md：API 文档转换规则
这条规则指导智能体将类、结构体、接口、枚举等 API 文档从 Markdown 转换为 JSON，每个顶级类型生成独立的 [名称]_[类型].md 对应 JSON 文件（如 Demo_class.json）。规则中明确规定了输出结构：构造函数、成员函数、静态函数、运算符重载、拓展接口等字段各自有固定数组位置，保证生成器能稳定解析。
module_index.md：目录索引转换规则
这条规则专注于"导航层"：按实际功能（而非数据类型）对 API 分组，例如"数据操作、线程操作、文件操作"，为整个包重构入口文件，显著改善阅读体验。它还有一条严格的链接约束——link 字段必须跳转到 Markdown 文件，禁止指向 JSON 文件，确保最终文档的跳转体验完整可用。
Schema 校验：给 AI 输出装上"安全护栏"
两条规则都要求生成的 JSON 附加 $schema 字段，例如 http://localhost:8000/api.schema.json。配合在 .lingma/schema 目录启动的本地服务器（python -m http.server 8000），IDE 就能对生成文件做实时格式校验——字段缺失、类型错误会直接出现波浪线提示。
这一步是整个流程的关键质量关卡：api.schema.json 通过 oneOf 精确约束了六种合法类型（common、function、class、struct、interface、enum），并对函数名等字段施加了正则约束（如不允许出现括号）。AI 的自由发挥被限制在严格的"轨道"内，输出即规范。
生成器收尾：cjdocgen 一键构建文档
JSON 中间表示就绪后，最后一棒交给生成器。在 bash 或 Git Bash 中执行 CjDocAgent.rc：
source CjDocAgent.rc
cjdocgen [包名]
该脚本会根据是否处于 MINGW 环境，自动将 cjdocgen 命令指向 .lingma/bin/ 目录下对应的 losu 可执行文件（提供 Windows / Linux / macOS 三平台版本）。生成器会逐个读取 JSON 文件，将其渲染为包含构造函数表、成员函数表、枚举值表等表格的 Markdown 文档——正如上文截图所示，每个文件的处理进度都会清晰输出。
小结：这套规则体系值得借鉴的设计
- 总纲 + 子规则分层：
always_on负责身份与纪律，条件触发规则各司其职，避免规则互相干扰 - 触发条件显式声明：每条规则开头就写明触发条件，并强调误触发的严重后果，AI 行为可预期
- 中间表示 + Schema 双保险：Markdown → JSON → Markdown 的三段式流水线，让"智能生成"与"严格校验"解耦
- 本地工具链闭环：
bin/目录内置多平台生成器，一条source命令即可激活完整文档构建能力
如果你正在为自己的项目搭建 AI 文档助手，DocAgent 的 rules/ 目录和整体三层流水线设计，是一个非常值得参考的开源范本。