知识库

本页是一篇完整方案指南:以 doc-knowledge 插件(com.auraboot.doc-knowledge,命名空间 dk)为例,从用户场景一路讲到它如何成为 Aura Bot 的知识来源、开发实施与典型错误。它是 config 型插件——5 个 model、18 条命令、15 个页面 + 1 个看板全部是 DSL JSON 声明,没有一行后端 Java。下面每个标识符你都能在插件目录 plugins/doc-knowledge/config/ 里 grep 到、对运行实例调得通。

这个插件依赖 com.auraboot.template.project-management(项目管理模板)——文档可以关联到项目,所以导入前要先有项目管理插件。

1. 用户场景

一家制造企业要把分散在网盘和邮件里的图纸、规范、报告、会议纪要、合同统一管起来,同时沉淀一套可检索的知识文章。日常:

• 工程师新建文档(草稿)→ 填标题、类型、所属项目、访问级别、正文 → 发布后全员可见;
• 文档需要改动时修订退回草稿,改完再发布;过期的文档归档,从活跃列表移走但保留可查;
• 每次重要改动留一条版本记录,带变更说明和内容快照,后面能对照看历史;
• 文档按分类树归置(产品文档 / 政策制度 / 培训资料 / 故障排查);
• 文档按访问级别(公开 / 内部 / 机密 / 受限)控制可见范围;
• 文档可以关联到项目,从项目视角追溯相关的规范、设计稿、合规证书;
• 另有一套知识文章,比文档更短、更聚焦主题,同样有草稿 → 发布 → 归档的编辑生命周期。

文档管理员、文档编辑、文档查看者看到的内容和能做的操作各不相同。

2. 需求痛点

• 没有生命周期:网盘里的文件没有「草稿 / 已发布 / 已归档」状态,谁都不知道哪份是定稿、哪份还在改。
• 版本断链:覆盖式上传把旧版本冲掉,想回溯「上一版改了什么、谁改的」查不到。
• 操作无授权无审计:谁发布了、谁归档了、什么时候,没有记录;发布只能靠口头通知。
• 访问控制靠人盯:机密图纸混在公开目录里,靠命名约定防泄露,不可靠。
• 与项目脱节:项目相关的文档散落各处,无法从项目一键看到它的全部规范和合规材料。

这些都不是「再建一个文件夹」能解决的,而是受控状态变更 + 结构化关联的问题。

3. 产品方案

在 AuraBoot 里,每一个文档动作都是一条命令,走统一的 命令管道:

• 「发布」按钮调用 dk:publish_document,而不是裸写 PUT /api/dk_document;命令在管道里统一鉴权 → 状态机校验 → 执行 → 审计 → 发事件。
• 文档生命周期由状态字段 dk_doc_status + 三条 state_transition 命令(dk:publish_document / dk:archive_document / dk:revise_document)守护,非法跳转(比如对一份草稿直接归档)会被状态机拒绝。
• 版本历史是一个真实模型 dk_doc_version,通过 parentModel: dk_document 挂在文档下,在文档详情页以子表形式出现——它继承列表、详情、搜索、导出、审计,和其他业务实体共享同一套机制,不用另建「版本管理控制台」。
• 同一条命令既是 UI 按钮的目标,也能被自动化规则、BPM 审核流调用——比如「自动归档 18 个月未触达的文档」直接发 dk:archive_document,不需要人工二次操作。

4. 功能设计

4.1 数据模型(5 个)

文档关键字段(config/fields.json):dk_doc_title(标题)、dk_doc_type(类型 enum)、dk_doc_project_id / dk_doc_category_id(reference)、dk_doc_abstract / dk_doc_content(text 正文)、dk_doc_access_level(访问级别 enum)、dk_doc_author / dk_doc_owner_id(创建时由 current_username 自动填)。

4.2 命令与状态机

18 条命令,命名 dk:<动词>_<名词>(冒号分隔,不是点号)。按类型分:

文档的状态机:dk:publish_document(draft → published)→ dk:revise_document(published → draft,退回再编辑)→ dk:archive_document(published → archived)。知识文章同构。

每条命令都是一段声明。例如 dk:publish_document(config/commands.json)的真实定义:

{
  "code": "dk:publish_document",
  "displayName:zh-CN": "发布文档",
  "displayName:en": "Publish Document",
  "description": "Publish a draft document",
  "type": "state_transition",
  "modelCode": "dk_document",
  "stateField": "dk_doc_status",
  "fromStates": ["draft"],
  "toState": "published",
  "permissions": ["dk.document.publish"],
  "extension": {
    "confirmMessage:zh-CN": "确认发布此文档？",
    "confirmMessage:en": "Confirm publish this document?"
  }
}

读出来的设计信息:这是一条 state_transition,只能从 draft 走到 published(fromStates 不含别的状态,对已发布或已归档文档点发布会被拒);要求 dk.document.publish 权限(注意:这条权限和 dk.document.manage 是分开的——能编辑不等于能发布);点击时弹确认框。create 型命令(如 dk:create_document)则带 inputFields 列出可填字段、autoSetFields 声明 dk_doc_no 用 DOC-{yyyyMMdd}-{seq} 自动生成、dk_doc_status 固定为 draft、作者取 current_username。

4.3 权限与角色

9 个权限码,命名 dk.<资源>.<动作>(点号分隔,注意权限码用点号、命令码用冒号,二者不同):

dk.document.manage     dk.document.read     dk.document.publish
dk.category.manage     dk.version.manage
dk.article.manage      dk.article.read      dk.article.publish
dk.link.manage

manage 覆盖增改删归档,publish 单独拆出来(发布是更高权限),read 是数据型权限(resourceType: data),用于列表/详情的数据可见性。

3 个角色(config/roles.json):

• dk_manager(文档管理员)—— 全部 9 个权限,含发布;
• dk_editor(文档编辑)—— 能增改、管版本和关联,但没有 dk.document.publish / dk.article.publish;
• dk_viewer(文档查看者)—— 只有 dk.document.read + dk.article.read。

4.4 页面

15 个 DSL 页面(config/pages.json):每个 model 的 list / form,以及 dk_document / dk_knowledge_article / dk_doc_category / dk_doc_version / dk_project_document 的 detail。另有 1 个看板(config/dashboards/dk_dashboard.json),由 6 条命名查询(dk_dashboard_kpi / dk_docs_by_type / dk_docs_by_status / dk_articles_by_status / dk_recent_documents / dk_recent_articles)喂数据。菜单(config/menus.json)挂在 /doc-knowledge 下:看板、文档、分类、版本、文章、项目文档。

4.5 作为 Aura Bot 的知识来源

这个插件本身是纯文档/知识库 CRUD,没有内建向量检索或 RAG 管道——它不声明 embedding 模型、答案溯源模型,也没有自带的检索打分逻辑。它在 AI 体系里的位置是:已发布的文档与知识文章,就是 Aura Bot 可以回答的知识来源。

衔接是平台 Agent System 默认就有的能力,而不是这个插件额外写的代码:

• 读工具自动生成:DSL Tool Provider 会为每个模型自动挂上 list:<modelCode> 与 get:<modelCode> 读工具,命名查询则成为 nq:<queryCode>。把 list:dk_knowledge_article / get:dk_document / nq:dk_recent_documents 放进某个 Agent 的 tools 白名单,它就能在回合里查文档库回答用户问题。
• 权限即检索边界:Agent 以调用用户的身份运行(见 Aura Bot §权限)。用户没有 dk.document.read 的文档,Agent 同样看不到;dk_doc_access_level(public / internal / confidential / restricted)配合 ABAC 策略进一步收窄可见范围。换句话说,Bot 永远不会读到调用者本人读不到的内容。
• 写命令按需暴露给 Agent:这套命令默认不带 agent_hint / cmd_risk_level,也就是默认不开放给 Agent 自动执行。要让 Agent 能起草文章或发起归档,在对应命令上补 agent_hint(说明何时用)和 cmd_risk_level(发布/归档这类用 L2+ 走 Approval Gate),让人工先确认——契约见 Agent Builder。

所以:文档与知识沉淀在这里,检索、权限、审计、暴露策略都复用平台同一套机制;它不是再造一个「AI 知识库控制台」,而是让 AI 顺着既有的模型、命令、权限说话。

5. 具体开发与实施

先掌握基础。本插件没有任何后端 Java,全靠平台的几个核心契约。动手前请先读:Model 与 Field · Command · 命令管道 · Permission · 插件清单 · 纯配置 Plugin · Page Designer。

落地一个像 doc-knowledge 这样的 config 插件,步骤是:

1. 写清单 —— plugin.json 声明 pluginId / namespace(dk)/ pluginType: config / dependencies(本插件依赖项目管理模板),并在 resourceDirs 里把每个配置文件登记进去(models / commands / permissions / modelFieldBindings …)。详见 插件清单。
2. 定义 model 与字段 —— config/models.json(5 个 model,版本模型用 parentModel + parentField 声明父子关系)+ config/fields.json,字段类型用平台 dataType(string / enum / reference / text…)。详见 Model 与 Field。
3. 声明命令 —— config/commands.json,状态流转用 type: state_transition + fromStates / toState,增删改用 create / update / delete,并在 permissions 绑权限码。详见 Command。
4. 配 model-field binding —— config/bindings.json,并在 resourceDirs.modelFieldBindings 注册(见「典型错误」)。
5. 权限、角色、字典、菜单、页面 —— config/permissions.json / roles.json / dicts.json / menus.json / pages.json / dashboards/。
6. 打包导入 —— 用 aura CLI 的 import-directory-sync(参数是目录 path)或平台导入接口;校验返回 success:true 才算导入成功。导入前确保依赖的 project-management 已先导入。

6. 常见配置

• 文档生命周期:状态字段 dk_doc_status(字典 dk_doc_status:draft / published / archived),三条 state_transition 命令守护;要支持「下架重编」就配 dk:revise_document(published → draft)。
• 访问级别:字段 dk_doc_access_level 选字典 dk_access_level 的 public / internal / confidential / restricted,配合 ABAC 策略控制文档可见范围。
• 分类树:dk_doc_category 用 dk_cat_parent_id 自引用构成多级分类;文档通过 dk_doc_category_id(reference)挂分类。
• 版本快照:每次重要改动调 dk:create_version 写一条 dk_doc_version,带 dk_ver_change_summary(变更说明)和 dk_ver_content_snapshot(内容快照);版本以子表出现在文档详情页。
• 项目关联:dk:link_document 写 dk_project_document 桥表,把文档挂到项目;dk:unlink_document 解除。
• 自动归档:配自动化规则,对长期未触达的已发布文档发 dk:archive_document,无需人工。

7. 典型错误

• 命令码用点号:写成 dk.document.publish 跑不通——命令码是冒号 + 动词_名词:dk:publish_document。而权限码才用点号:dk.document.publish。同名不同分隔符,别混。
• 绕过命令直接改文档表:直接 UPDATE dk_document 的状态会跳过状态机校验、handler 和审计/事件投递。一切文档变更都走命令。
• 对已归档文档点发布:dk:publish_document 的 fromStates 只含 draft,对 published / archived 文档调用会被状态机拒绝——这是设计,不是 bug。
• 编辑权限当成发布权限:dk.document.manage 不含 dk.document.publish(dk_editor 角色就没有发布权);要让某角色能发布,得单独授 dk.document.publish。
• 导入时缺依赖:本插件 dependencies 声明依赖 com.auraboot.template.project-management,先导入它再导本插件,否则 dk_doc_project_id / dk_project_document 的 project 引用解析不了。
• bindingRules 写进 commands.json 内联:不会被导入;必须独立 bindings.json 并在 resourceDirs.modelFieldBindings 注册,否则报 [S-EXT-HANDLER] references unregistered handler。详见 纯配置 Plugin。
• 命令执行 payload 结构:字段放在 { "payload": { ... }, "operationType": ... },目标记录用 targetRecordId(不是 recordId)——放错位会出现「执行成功却字段为空」的迷惑性报错。

下一步

• 系统总览 —— 插件、命令与运行时如何拼到一起
• 命令管道 —— 上面每条命令都走的执行契约
• 权限 —— 上面三个角色背后的五层模型
• 插件清单 —— 插件如何声明依赖与资源目录