姚章浩
a42b101a7b
父审发现三处会让目标卡死或状态对不上实际入口，逐条修： 1. 登记成功但没来得及收尾：崩溃重入会撞上"已有生效版本"直接失败， 目标留在维护里、占用也不释放。现在按「本作业+同一快照」识别为自己的 版本，只做收尾（恢复服务/开入口/释放两把占用），不重新捕获、不重写； 别人的版本仍然拒绝。捕获完成但登记失败则明确失败并写"未对目标写入"。 2. 重入覆盖原运行状态：崩溃时服务已被停住，再读一次只会读到 stopped， 写回去会让恢复阶段永远不启动写入者。AcquireInstance/LibraryMaintenance 在 owner 相同的重入时保留已持久化原状态；新作业接管已释放窗口用自己的观察。 真实 PostgreSQL 集成用例覆盖（先红后绿）。 3. 版本登记移进维护窗口：捕获/校验/登记要么一起成立、要么目标原样恢复； 记录失败时窗口已开放，治理状态同步释放，不再"显示维护中、实际已开"。 索引映射读不到时拒绝登记，不再用空摘要写证据。 顺带： - 基线窗口统一收尾抽成 settleBaselineWindow，四种结局各有测试（成功/健康失败/ held 保持维护/已恢复则释放），并用真实 DB 用例证明 baseline 与 sync/restore 共用写互斥、幂等重试不产生第二个作业。 - 新增 cmd/librarydrill：维护隔离 → 整库预备份 → 一致性校验 → canary 漂移检测 → 按预备份恢复 → 逐类复核 → 按原状态恢复服务。用与 worker 相同的 LIBRARY_* 配置，绝不触碰封存源。 - 目标/预备份/维护栈装配收成 internal/librarystack 一份（worker 与演练共用）。 验证：go build/vet/test 全过；TEST_DATABASE_URL 指向临时 PostgreSQL 跑 TestMaintenanceReentryKeepsOriginalServiceState（修复前失败：got app=stopped） 与 TestLibraryWriteMutexCoversBaselineJobs；本地门禁 15/15。
知识治理平台
面向企业多数据源的知识同步、生命周期治理与持续运营平台。
企业知识分散在钉钉、文件目录与业务资料门户中，内容会不断新增、更新和失效。平台连接这些来源与 WeKnora 知识底座，组织资料发现、取件、处理、验收、发布和下架，让知识不只是被导入一次，而是能够持续维护、追踪和治理。
同步是入口，知识库治理是核心，持续运营是目标。
平台解决什么问题
- 资料分散：统一查看来源与目录，按范围选择、标注和获取内容。
- 更新难追踪：通过来源身份、内容摘要、版本、快照与变更集记录变化。
- 处理不透明：查看任务和解析状态，定位失败、停滞和需要人工处理的项目。
- 知识边界不清：区分对内、对外和禁止导入，绑定相应测试与生产知识库。
- 上线不可控：先处理与验收，再按审核策略和生产门禁组织发布。
- 失效难治理：识别需下架内容，提供移除、失败重排与发布回滚等处理机制。
自动同步不等于无条件自动发布。不同来源的扫描、取件、处理和调度能力存在差异；生产变更仍受配置、权限与授权约束。
在 DobotAI 体系中的位置
业务资料来源：钉钉 / AList / PP（资料门户）
↓
知识治理平台：发现与同步 → 状态跟踪 → 验收与治理 → 发布与维护
↓
WeKnora：文档处理、知识组织、索引与检索
↓
Knowledge Adapter / DobotAI 网关
↓
钉钉问答 / 软件内 AI 助理 / Wiki 问答等业务入口
本仓库负责知识治理流程与控制，不重复建设问答应用或检索引擎，也不修改 WeKnora 官方源码。Knowledge Adapter、DobotAI 网关及业务入口属于关联系统，不由本项目部署。
核心能力与当前边界
下表描述仓库已有实现及文档记录的能力，不代表任一部署环境已启用所有功能。现场接线、运行开关与验收结果以对应环境为准。
| 能力 | 已有支持 | 边界 |
|---|---|---|
| 来源与目录管理 | 来源连接、目录浏览、范围选择、对内/对外/禁止导入策略 | 标注是治理意图，不代表已取件、入库或发布 |
| 多源资料获取 | 钉钉取件、AList 来源接入、PP 清单与历史账本接管 | 格式、凭据、目录及调度限制不同，不承诺所有来源全自动同步 |
| 变化与资产管理 | 稳定来源身份、内容摘要去重、来源版本、快照与变更集 | 来源变化与目标知识库处理状态分别记录 |
| 测试处理与验收 | 后台上传、轮询、知识与切片验收、失败恢复 | 解析和索引由对接的知识底座完成；部分检索判断仍需人工 |
| 解析与任务监控 | 处理中、失败/死信、需下架、知识库差异及处理进度视图 | 指标、动作与实际覆盖程度见验收清单，不等于完整告警平台 |
| 审核与发布 | 可配置自动审核策略、人工审核、批次锁定、生产授权与结果追踪 | 对内自动审核默认策略与对外人工控制详见操作流程；锁定不等于发布 |
| 回滚与备份 | 发布回滚、目标库快照门禁、备份配置及恢复工具 | 依赖专用接线、权限和恢复验证，不能仅凭页面存在判定可用 |
| 权限与审计 | 管理员、文档工程师、只读角色与操作记录 | 不等于已实现所有来源到问答端的文档级授权 |
数据源支持
| 来源 | 当前接入方式 | 参考文档 |
|---|---|---|
| 钉钉 | 知识库目录发现与取件；优先 dws，按错误类型决定是否回落兼容路径 | 钉钉取件 |
| AList | 来源目录与资料获取，依赖指定连接和凭据 | 用户操作流程 |
| PP（资料门户） | 本地清单、历史账本接管与只读扫描 | 历史接管、来源扫描 |
IT、行政等是待扩展的业务资料范围，不是已经完成的新连接器。接入敏感资料前，需要先确认 Owner、有效版本、可见范围与知识库路由。
工作流程
- 配置来源与知识库绑定：确认凭据、可见范围和目标库。
- 发现、标注与取件：按目录或文件选择范围，记录资料身份和变化。
- 处理与验收：进入测试知识库，跟踪上传、解析、索引及验收结果。
- 审核与组批：应用审核策略；建立并锁定发布清单，保留可追踪快照。
- 授权发布：核验备份与发布门禁，再执行目标知识库变更并读回验证。
- 持续维护：跟踪后续更新、失败、失效与需下架内容，按流程重排、移除或回滚。
具体操作、确认语句和异常处理见 操作 Runbook；已实测、待验收和已知限制见 用户流程验收清单。
访问与部署
已部署环境
Compose 中网页入口固定映射为 宿主机 8088 → Web 容器 8080。网页和 /api/ 使用同源入口。
- 本机访问：
http://127.0.0.1:8088/ - 局域网访问：
http://<服务器内网IP>:8088/ - 健康入口：
http://127.0.0.1:8088/health
可以由 NAS 反向代理提供 HTTPS 域名入口，目标为平台服务器的 8088，保持路径原样转发。公网开放前必须验证鉴权、访问控制及转发头配置，不直接暴露数据库或内部管理接口。
平台入口展示当前部署版本，不是每次 CI 的构建预览。 CI 静态预览由独立链路提供；CI 通过不会自动更新运行服务。
部署前提
当前 compose.yaml 面向已有接线环境，包含宿主目录、凭据挂载和外部 Docker 网络，不是仅克隆仓库就能直接启动的通用安装包。
部署者需先准备：
- Docker Compose，以及
compose.yaml声明的外部网络。 - PostgreSQL、测试知识库及所启用来源的凭据文件与权限。
- 来源目录、spool 与运行状态挂载；按部署主机调整路径和 UID/GID。
- 测试 WeKnora 连接与对内/对外路由；生产发布按独立配置和授权接线。
准备完成后，由获授权的操作者执行：
docker compose up --build -d
主机需要提权时，由操作者按本机权限规则执行，不在自动化中默认使用 sudo。停止服务可用 docker compose down；不要执行 docker compose down -v，除非明确批准删除数据库卷。
配置与安全边界
- 网页服务地址用于控制台探活与配置核验；真正的发布目标由受限发布运行时配置决定，两者不能混为一谈。
- 密钥通过文件或 secret 引用提供，不写入 Git、网页响应或日志。示例配置不是真实凭据。
- 生产请求与 Release Worker 默认关闭；启用状态必须现场确认。测试处理成功、自动审核或批次锁定都不能绕过生产门禁。
- 来源扫描与取件不应改写原始业务资料；目标知识库的发布、移除和回滚属于独立受控动作。
- 发布与恢复前必须按目标环境准备备份，并核验可恢复性。
开发与 CI
基础环境：Go 1.26、Node.js 22、npm，以及检查脚本所需的 Python 3 和工具链。依赖以仓库锁文件和实际 CI 配置为准。
make verify # 完整检查入口：本地与 CI 使用同一套规则
make list # 查看检查清单与适用范围
单项测试或构建只用于定位问题，不能代替完整验证。远端 CI 校验事件提交身份、汇总必需检查，再按条件生成静态预览与通知；不默认执行部署。
版本与变更见 CHANGELOG，正式版本流程见 发布 Runbook。make version 查看构建身份；日常开发构建与正式构建分开标识，软件版本 tag 不等同于知识发布批次。
问答运营模型配置
管理员在「系统设置 → 服务配置 → 问答评估模型」填写 OpenAI 兼容基础地址、模型和 API Key。测试连接发送最小非业务请求；保存不会启动历史全量任务，自动分析/翻译默认关闭。密钥不回显，保留、更换和清除分别选择；录入只允许有效 HTTPS 或本机回环连接，不允许跳过证书校验。
API 和普通 worker 须只读挂载同一个独立的 32 字节、0600 普通文件，以 QA_AI_MASTER_KEY_FILE 指向容器内路径。文件属主应为实际运行 UID；不要复用 Agent 会话存储或把主密钥写进 Compose/Git。治理库只保存加密后的服务密钥；恢复时必须同时恢复治理库和这份独立主密钥。未配置主密钥时如实显示安全存储未就绪。
当本机代理的 Fake-IP DNS 导致公网端点被安全守卫拒绝时，可仅为这两个治理组件设置 QA_AI_DNS_OVER_TLS=alidns：通过证书验证的公共 DNS-over-TLS 解析，再按同样的公网 IP、HTTPS 和禁止重定向规则发请求；不修改系统 DNS、代理或隧道，不允许以启用私网访问替代修复。
问题流水支持先预览已执行筛选/单条范围，再创建持久后台批次；字段分析和原问题译中独立计数，仅补真正空白。暂停不撤回已发请求，共享任务若仍被另一活动批次需要会继续执行；恢复或重试失败项不扩大原批次分母。详情保留逐字段依据、模型/提示词版本及回填/跳过说明。自动处理首次启用排除历史，关闭暂停未开始的自动任务，重开恢复披露的增量积压；不因保存配置而全量外发。
后续方向
- 扩展多数据源调度与增量同步的覆盖范围。
- 完善处理监控、积压分析、告警及来源与目标知识库的一致性对账。
- 建设知识资产、新鲜度、更新超期与知识缺口报表。
- 对接评测和业务反馈，形成可归因的持续优化闭环。
- 细化敏感资料权限及生命周期规则。
这些是演进方向，不作为当前已上线能力承诺。待办见 BACKLOG。
文档导航
| 文档 | 用途 |
|---|---|
| 操作 Runbook | 使用步骤、配置、凭据续期与异常处理 |
| 用户流程验收 | 实测证据、待验收项及限制 |
| 领域模型 / 状态机 | 模块边界、数据与状态语义 |
| 发布与版本 | 软件发布准备与只读预检 |
| 备份与恢复 | 知识库数据的备份、恢复与演练 |
| 旧 README 存档 | 原阶段说明与历史验收记录；不是实时部署状态 |
仓库结构
cmd/ API、任务 Worker、发布 Worker 与运维工具
internal/ 治理模型、任务队列、持久化、HTTP 与发布适配
web/ React / TypeScript 管理界面
deploy/ Nginx 配置
config/ 发布等受限配置的示例
scripts/ 检查、资料处理与运维脚本
docs/ 操作、设计、验收与历史档案