八荒启·交互动画帮助中心

《知识库 AI 调用指南》

通过超级管理员登录会话，让 AI 查询、编写、修订、审核、发布和归档知识

正式版本 1.2.0适用范围：具备 HTTP 请求能力的 AI、超级管理员及其受控工具

一、撰写前必须读取的标准

所有 AI、自动化程序和其他创作工具，在新建或修改知识内容前，必须完整读取并遵守《知识中心文档撰写规范》（STD-KNOWLEDGE-WRITING-001）的当前已发布版本。 取得草稿编辑授权不等于已经完成标准读取。

1. 获取与核对

  1. 读取目标环境的公开调用协议，按既有流程取得合法读取权限。
  2. 使用 detail 查询标准，按 currentVersionId 精确选择当前已发布版本；不能取版本数组第一项、最新草稿或凭记忆选择版本。
  3. 完整读取该版本正文、机器规则和 Schema，记录编号、版本 ID、版本号、内容摘要及读取时间到工具执行记录，不能写入知识正文。
  4. 再读取目标知识的完整内容、版本、引用、采用情况及发布配置，按标准撰写。
  5. 保存前重新确认标准当前版本和摘要；如有变化，重新读取并检查草稿后再保存。

查询命令示例，发送到当前授权支持的命令入口：

{
  "operation": "detail",
  "knowledgeCode": "STD-KNOWLEDGE-WRITING-001"
}

2. 失败时停止，不降级绕过

情况 必须执行
无当前已发布版本、读取失败或无权限 停止撰写与保存，报告原因，不索取或绕过更高权限
内容被截断、字段未读全 补齐读取，完成前不开始撰写
只有旧缓存或聊天中的摘要 先核对当前版本与摘要，摘要不能替代完整标准
保存前标准发生变化 读取新版本，重新核查草稿

正文按标准组织层级、示例、图表、强调与引用，不重复文章标题，不夹带文章自身元信息或制作过程。机器字段同步表达约束，但不代替面向人的必要解释。

3. 引用与实际采用

调用指南对该标准构成规范性引用，跟随当前已发布版本，不复制标准全文。平台引用记录应指向标准的稳定编号，来源标识为 DOC-KNOWLEDGE-AI-AUTHORING-001。

引用关系与消费端采用记录不是同一件事。采用记录只能由真实消费工具在完整读取并实际执行后，按平台支持的协议登记实际版本和摘要；不能将计划采用写成已经采用。没有登记权限时报告待登记，不伪造成功。

这项要求是工具必须执行的前置步骤。写入指南和机器规则不会自动部署服务端拦截，也不表示所有外部工具已经落实自动读取。

二、推荐方式：本机桌面弹窗、24 小时草稿编辑授权

AI 仅获得 knowledge:draft-edit，不能获得官网账号密码、网站登录 Cookie、审核、发布或归档权限。无需打开官网页面。Windows/Linux 的图形桌面由临时 Python 3 + tkinter 小工具显示输入窗，完成后关闭并退出；缺少图形桌面或 tkinter 时明确报告，不在聊天中收集密码。

  1. 读取公开协议的 draftAuthorization.desktopHelper，核对 source 的 UTF-8 SHA-256 与 sha256 一致，将参考源码写入本机临时脚本。只采用可信官网来源，源代码可供用户检查，不使用远程命令字符串或任意回调域名。
  2. AI 请求 POST /api/public/knowledge/authoring/authorizations，JSON 为 {"label":"工具名称"}。返回 requestId、deviceCode、userCode、authorizationMethod=local-desktop、expiresIn=600、interval=5。
  3. AI 在用户本机图形桌面运行 python knowledge_ai_desktop_authorize.py --request-id <requestId> --user-code <userCode>。Windows 可用 BAT 调起同一个脚本。命令行只传非秘密的申请编号和核对码，不传账号、密码、网站 Cookie 或 AI 凭证。不能在远程云容器中启动窗口冒充用户桌面。
  4. 用户在本机小窗口输入官网账号和密码。工具只向 https://bahuangqi.com 发送登录和授权请求，禁止跨域跳转。复用已有账号密码登录与二次验证服务，验证码或风控要求继续生效，不得绕过。官网 Cookie 仅保存在小工具进程内存，验证结束退出并丢弃，不发给 AI、不写入磁盘。
  5. AI 每 5 秒请求 POST /api/public/knowledge/authoring/authorization-status，请求头 X-Knowledge-AI-Token: <deviceCode>。状态 active 后才可调用 POST /api/public/knowledge/authoring/commands；包络与原命令一致。申请十分钟未确认即失效。
  6. 从确认授权起固定 86400 秒有效，不滚动续期、不自动刷新。只允许 list/detail/publication/validate/audit/consumers/create/create-version/save-draft。submit-review/approve/reject/reopen/publish/archive 全部拒绝，审核、发布和归档由用户自己在网站操作。
  7. ApiResponse.code=40171 表示缺少、过期、撤销或凭证变更，AI 停止写入，重新申请并再次调起本机弹窗；40172 表示等待当前申请确认，只继续轮询，不重复弹窗；40371 表示该操作不在草稿授权范围，交给用户；40372 表示账号、超级管理员关系或操作权限不可用，停止并报告，不循环弹窗。HTTP 200 不等于成功，必须读取业务 code。
  8. 提前撤销可用同一工具附加 --revoke，由用户在本机输入账号密码执行。保留非秘密 requestId 与核对码，过期后无须撤销。AI 凭证只能放在受保护的工具内存，不得进聊天、URL、正文、命令历史或日志。

受保护的管理接口：GET /api/superadmin/knowledge/ai/authorizations/{requestId} 查看申请，POST .../{requestId}/approve 使用 {userCode,password} 确认，POST .../{requestId}/revoke 撤销。仅有效超级管理员可操作，已批准申请只能由授权账号管理。

后台记录授权账号、工具名称、请求标识、到期时间，以及本机工具的设备指纹、User-Agent 和 IP 摘要；指纹是审计标记，不是不可复制的硬件身份。凭证在 Redis 仅保存 SHA-256 索引。每次命令重新校验账号状态、密码版本、超级管理员关系与权限，撤销或删除缓存后立即拒绝下一次调用。授权确认使用原子状态转换，包含限流、密码验证频率限制和授权/撤销审计。敏感响应 Cache-Control: no-store。

旧超级管理员会话接口保持兼容；第三方 AI 的默认路径必须使用上述草稿专用凭证，不能要求用户把网站会话交给 AI 来扩大权限。

三、给 AI 的入口

GET /api/public/knowledge/authoring 是公开的机器说明入口，只返回协议、字段和示例，不返回知识或账号数据。

部署后可把 https://bahuangqi.com/api/public/knowledge/authoring 交给支持 HTTPS 请求的 AI/工具。普通聊天模型若不能发送 HTTP 请求，仍需用户为它提供执行工具；仅收到 URL 不会获得管理权限。

认证成功后可用 GET /api/superadmin/knowledge/ai 验证超级管理员身份及读取相同协议。

四、兼容方式：受信管理工具的原有登录

复用现有 POST /api/auth/account/pwdlogin，JSON 为 {"account":"账号","password":"密码"}。用户在自己控制的终端或可信登录工具输入密码，不把密码放在聊天、URL、文档或命令历史。登录失败、验证码或风控要求按原登录流程处理，禁止绕过。

后续请求使用登录接口签发的 bhq_token Cookie（命令行可使用受保护的 cookie jar），或既有登录会话的 Authorization: Bearer ...。本接口不签发永久密钥、不接受每次调用携带密码、不允许伪造 userId。有效期、撤销和退出均服从现有登录系统。

每次命令均校验当前有效超级管理员员工关系，以及当前操作所需权限。原系统要求提权的操作仍要求 X-Privilege-Token、设备指纹及原提权校验，不因 AI 入口放宽。仅有知识编辑权限的普通员工不能使用本入口。

五、命令协议

POST /api/superadmin/knowledge/ai/commands，Content-Type 为 application/json。

{
  "operation": "detail",
  "knowledgeCode": "STD-KNOWLEDGE-DIRECTORY-001"
}

响应沿用 ApiResponse，业务结果位于 data。所有 id 按响应原样保留，特别是字符串形式的 Long，不转换为 JavaScript Number。

operation 权限 参数及行为
list knowledge:read payload 可含 type、status、keyword；沿用现有最多500条的查询限制
detail knowledge:read knowledgeCode；返回正文、机器规则、Schema、版本及引用
publication knowledge:read versionId；读取该版本的 help/docs 配置
audit knowledge:read knowledgeCode；读取审计记录
consumers knowledge:read 读取消费端采用状态
create knowledge:write payload 使用 CreateItem 字段，创建知识及初始 DRAFT
create-version knowledge:write knowledgeCode；payload 使用 CreateVersion 字段，新建版本
save-draft knowledge:write versionId、expectedRevision；payload 使用 SaveDraft，内外 expectedRevision 必须一致
validate knowledge:read versionId；沿用正式校验，不写入或发布
submit-review knowledge:write versionId、expectedRevision、payload.reason
approve / reject knowledge:review versionId、expectedRevision、payload.reason
reopen knowledge:write versionId、expectedRevision、payload.reason，回到 DRAFT
publish knowledge:publish knowledgeCode、versionId、expectedRevision；仅发布已审核通过的指定版本
archive knowledge:publish knowledgeCode、最新版本的 versionId、expectedRevision、payload.reason

CreateItem、CreateVersion、SaveDraft 的完整字段由公开协议 payloadFields 返回，对应 KnowledgeRequests。公开页面配置沿用 KnowledgePublication，不另建一套字段。保存前必须读取 detail 和 publication，原样保留未修改的配置、机器规则和 Schema；它们不是局部 PATCH。

创建示例：

{
  "operation": "create",
  "payload": {
    "knowledgeCode": "KB-EXAMPLE-001",
    "title": "示例知识",
    "knowledgeType": "internal_knowledge",
    "domainCode": "knowledge-governance",
    "visibility": "internal",
    "aiAllowed": false,
    "initialVersion": "1.0.0",
    "contentMarkdown": "# 示例知识\n\n正文",
    "changeSummary": "建立初始草稿"
  }
}

六、发布与删除

保存、新建与发布相互独立。用户要求保存时只保存；用户明确要求发布指定编号和版本时，依次校验、提交审核、通过审核、发布，每一步重新读取修订号。正文、机器规则、Schema、公开安全、引用及文件平台检查继续复用原工作流。

内部知识发布后仍只在权限范围内可见；面向官网用户展示还需要 public 可见范围及有效的 help/docs 发布配置，不能把“CURRENT”等同于“所有人可见”。

已发布正文不可覆盖，修改必须创建新版本。并发修改返回409，不自动覆盖。写请求超时或结果不明时先读取现状，不盲目重试。

删除采用 archive：撤下当前版本并归档全部版本，保留正文、版本、附件绑定和审计，不执行物理 DELETE。有引用、消费端采用或并发新版本时拒绝归档。恢复通过新建版本、审核和发布完成，不修改已归档历史正文。

此接口直接操作其所在环境的数据库：本地调用只改本地，生产部署后的调用才操作生产。它不自动部署网站、同步整库、运行迁移或重启服务。

七、首次调用顺序

第三方 AI 默认使用上述本机桌面授权流程；只有受信管理工具可兼容原有官网登录会话。读取完整知识、当前版本、引用和采用情况后再编辑，修改已发布内容必须创建新版本。AI 只编辑草稿，用户自行在官网审核和发布。遇到 40171 重新弹本机输入窗，40172 继续等待，40371/40372 停止对应操作，不循环索要密码。

八、字段与机器规则

接口字段、允许的操作及授权范围以目标环境返回的公开协议为准。完整结构放在机器规则与 Schema 字段，不在正文重复整份协议快照。工具应同时执行接口权限检查与撰写前置检查，不能因为取得编辑授权就跳过写作标准。

接口契约变化时核对实际实现；不能仅凭文档中的示例假定服务端已经支持某项能力。

九、版本与草稿对比

1. 版本递增规则

版本采用三段数字：主版本.发布序号.调整序号。一次已完成并保存的草稿调整使第三位加一；正式发布使第二位加一、第三位归零。第二位为9时，下次发布第一位加一，后两位归零。第三位不按9进位，避免把修改误计为发布。

动作 示例
连续调整草稿 1.1.0 → 1.1.1 → 1.1.2
正式发布 1.1.2 → 1.2.0
发布进位 1.9.2 → 2.0.0

前一位变化时，其后各位归零。保存失败不得报告版本已完成；已发布历史不得直接覆盖。版本号变化与editRevision并发控制是两套用途不同的标识，不能相互代替。

2. 草稿自动对比

草稿阅读页应默认与同一知识的紧邻上一版本对比，并清楚展示基准版本和当前版本。新增、替换及删除内容使用红色并配文字标签，保持不变的内容使用绿色；删除内容保留在对比区，不能直接消失。无上一版本时明确提示无基准。

正文、机器规则与Schema分别对比；颜色之外保留增改删标识，保证可访问性。对比标记属于页面呈现，不写入正文，不改变正文摘要或正式发布内容。

该呈现方式及版本自动递增需要编辑器和发布流程支持。工具不得将约定写入文档等同于页面功能已经实现；发布权限仍由用户掌握。

这篇说明是否解决了问题？

知识编号 DOC-KNOWLEDGE-AI-AUTHORING-001 · 当前版本 1.2.0