LLM-WIKI 控制面技术方案

# LLM-WIKI 控制面技术方案

1. 覆盖范围

LLM-WIKI 控制面是 MVP 唯一必须自研的核心能力。它不替代 GitHub、RAGFlow、Docusaurus 或 Meilisearch，而是把这些产品编排成一个 Git-backed、Agent-iterated、Human-approved 的文档系统。

支撑产品	控制面职责
LLM-WIKI 控制仓库	配置、状态、发布目录和 adapter 协议
文档收集器	来源读取、三方 diff、冲突报告、Sync PR
发布工作目录	publish/** 目录治理和文档状态管理
文档迭代智能体	RAGFlow AgentBridge、任务输入输出协议
文档展示产品	DisplayBackend adapter
知识索引产品	Index adapter、索引 manifest
问答产品	Answer API 标准化
智能体访问产品	Agent Access API/tool adapter、scope、ContextPack、调用审计
反馈与任务产品	FeedbackBridge、Issue 创建

2. 如何购买或获取

控制面自研，不购买。

依赖成本来自：

• GitHub Actions 执行分钟数。
• RAGFlow 所在服务器和模型调用。
• Meilisearch 托管或自建资源。
• Docusaurus 静态站点托管。

3. 如何开发

控制面的实现必须遵守四组技术协议。技术协议是产品特性实现推理的工程落点，用来约束组件边界、输入输出、状态、错误处理和验收。

技术协议	控制面职责
SyncEngine 技术协议	实现来源同步、三方 diff、冲突报告和 Sync PR
AgentBridge 技术协议	把 RAGFlow 输出转换为 Git diff 和 Release PR
Answer API 与 Agent Access 技术协议	标准化问答、智能体工具、scope 授权和反馈
Publish / Display Manifest 技术协议	生成页面状态、发布影响、展示层对账和索引状态

3.1 模块划分

scripts/
  sync_sources.py          # 来源同步和三方 diff
  detect_changes.py        # source lock 变更检测
  validate_docs.py         # 发布目录校验
  generate_impact_report.py # PR 发布影响报告
  publish_docusaurus.py    # Docusaurus 发布 adapter
  index_meilisearch.py     # Meilisearch 索引 adapter
  ragflow_adapter.py       # RAGFlow API adapter
  answer_api.py            # 统一问答 API，可后续服务化
  agent_access_api.py      # 面向智能体的工具访问入口
  feedback_github.py       # 反馈转 GitHub Issue
config/
  sources.yaml
  site.yaml
  ragflow.yaml
  index.yaml
  publish.yaml
state/
  source-lock.json
  source-lock.previous.json
  source-changes.json
  page-manifest.json
  publish-manifest.json
  publish-impact-report.json
  site-manifest.json
  index-manifest.json

3.2 核心数据对象

对象	用途
SourceConfig	描述来源 repo、ref、sourcePath、publishPath
SourceLock	记录上次同步的来源文件 hash 和 ref
DocumentRecord	描述发布目录中的页面、来源、版本、状态
SyncChange	新增、更新、删除、保留、冲突
IterationTask	给 RAGFlow 的文档迭代任务
AnswerResult	标准问答结果，包含引用和无答案原因
ContextPack	面向智能体任务的结构化上下文包
AgentAccessRequest	智能体工具调用请求，包含 caller、scope、tool 和 requestId
PublishManifest	发布后端产物记录
PublishImpactReport	PR 合并或发布前的页面影响报告
EditContext	编辑入口需要携带的页面来源、历史、相关任务和影响范围
AnswerSession	多轮问答会话状态，包含 scope、turns、引用上下文和限制
SiteManifest	展示层发布产物和页面 URL/hash 对账记录
IndexManifest	索引记录和版本

3.3 三方 diff 规则

三方输入：

符号	含义
A	上一次同步的来源基线
B	当前上游来源文档
C	当前 publish/** 文件

决策：

A -> B	A -> C	动作
未变	未变	无动作
变更	未变	用 B 更新 C
未变	变更	保留 C
变更	变更	冲突，生成报告
删除	未变	删除 C
删除	变更	删除冲突
新增	不存在	新增 C

4. 如何部署

控制面以 CLI + GitHub Actions 方式部署，不需要独立后端服务。

MVP workflows：

• docs-sync.yml：运行 sync_sources.py 和 detect_changes.py。
• docs-publish.yml：运行 validate_docs.py 和 Docusaurus build。
• docs-index.yml：运行 Meilisearch 和 RAGFlow dataset 索引同步。
• docs-agent.yml：手动或 Issue 触发 RAGFlow 文档迭代。

5. 如何配置

5.1 来源配置

config/sources.yaml 是控制面的入口。

关键字段：

• id
• repo
• ref
• sourcePath
• publishPath
• include
• exclude
• deletePolicy
• conflictPolicy

5.2 发布目录状态

每个文档可通过 frontmatter 或 sidecar metadata 标记状态：

---
llmWiki:
  sourceProject: kunora-kgent
  sourceRef: docs-publish
  qualityStatus: approved
  indexable: true
  qaVisible: true
---

同时，控制面必须生成 state/page-manifest.json，作为页面治理状态的机器可读事实。

建议字段：

{
  "path": "publish/system/components/kunora-kgent/index.md",
  "sourceProject": "kunora-kgent",
  "sourceRef": "docs-publish",
  "sourceCommit": "...",
  "contentHash": "...",
  "qualityStatus": "approved",
  "feedbackOpen": 0,
  "hasSourceConflict": false,
  "indexStatus": "indexed",
  "lastApprovedAt": "...",
  "relatedIssues": [],
  "relatedPullRequests": []
}

约束：

• Docusaurus 页面状态、搜索 metadata、RAGFlow metadata 和 Agent Access metadata 都应从 manifest 或同源数据生成。
• 手写 frontmatter 只能承载页面局部声明，不能替代控制面状态。
• manifest 可重建，不能成为唯一内容事实源。

5.3 质量事件模型

控制面需要把用户、智能体和系统产生的质量信号统一成事件，供报表、Issue 聚合和后续文档迭代使用。

事件类型：

事件类型	来源	用途
qa_no_answer	Answer API / Agent Access API	识别知识缺口
qa_low_confidence	RAGFlow / Answer API	识别低可信答案
search_no_result	Search API / Meilisearch	识别检索缺口
page_feedback	Docusaurus feedback widget	收集人工纠错和建议
broken_link	validate docs / build check	识别页面质量问题
source_conflict	SyncEngine	识别上游同步冲突

建议事件结构：

{
  "eventId": "...",
  "eventType": "qa_no_answer",
  "occurredAt": "...",
  "caller": {
    "type": "human|agent|system",
    "id": "..."
  },
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main"
  },
  "pagePath": "publish/system/components/kunora-kgent/index.md",
  "question": "...",
  "citations": [],
  "severity": "medium",
  "relatedIssue": null
}

聚合规则：

• 按 pagePath、sourceProject、eventType、severity、最近发生时间聚合。
• 同一页面的重复无答案或低置信事件应合并到同一个改进 Issue。
• 聚合报告可以先生成到 state/quality-report.json 和 Markdown 报告。
• 质量事件不直接修改文档，只能创建 Issue、触发迭代任务或影响页面状态。

5.4 发布影响报告

控制面必须为 Sync PR、Release PR 和 main 发布生成 PublishImpactReport。

建议结构：

{
  "reportId": "...",
  "baseRef": "main",
  "headRef": "docs-release/...",
  "generatedAt": "...",
  "changedPages": [
    {
      "path": "publish/system/components/kunora-kgent/index.md",
      "action": "update",
      "url": "/system/components/kunora-kgent/",
      "sourceProject": "kunora-kgent",
      "qualityStatusBefore": "approved",
      "qualityStatusAfter": "approved",
      "affectedIndexes": ["ragflow-approved", "meilisearch"],
      "relatedIssues": []
    }
  ],
  "build": {
    "docusaurus": "pending|passed|failed",
    "brokenLinks": 0
  }
}

生成规则：

• 对比 PR base/head 或发布前后 manifest，识别新增、更新、删除页面。
• 将文件路径映射到页面 URL、来源项目和索引影响。
• 报告写入 state/publish-impact-report.json，并摘要注入 PR body 或 workflow summary。
• 发布影响报告是审批辅助信息，不替代 Git diff。

5.5 编辑上下文

编辑入口必须能向 GitHub 编辑页、Issue 或 PR 模板传递 EditContext。

建议结构：

{
  "pagePath": "publish/system/components/kunora-kgent/index.md",
  "editUrl": "https://github.com/.../edit/...",
  "sourceProject": "kunora-kgent",
  "sourceRef": "docs-publish",
  "sourceCommit": "...",
  "lastApprovedCommit": "...",
  "relatedPages": [],
  "relatedIssues": [],
  "qualityStatus": "approved",
  "expectedChangeIntent": "fix|add|restructure|update-version"
}

约束：

• Docusaurus 只展示编辑入口，EditContext 由控制面从 page manifest、Git 历史和 Issue 关系生成。
• PR 模板应要求填写改动意图、风险、影响页面和引用依据。
• 上下文不完整时仍可编辑，但 PR 检查应提示补充说明。

5.6 Answer Session

多轮追问通过 Answer API 的会话协议实现，RAGFlow session 只是底层能力之一。

建议结构：

{
  "sessionId": "...",
  "caller": {
    "type": "human|agent",
    "id": "..."
  },
  "scope": {
    "paths": ["publish/system/components/kunora-kgent"],
    "version": "main"
  },
  "turns": [
    {
      "question": "...",
      "answer": "...",
      "citations": [],
      "confidence": "medium"
    }
  ],
  "limits": {
    "maxTurns": 8,
    "maxContextTokens": 12000
  }
}

约束：

• 后续追问默认继承初始 scope，不能自动扩大访问范围。
• 每轮回答都必须保留引用或明确无答案。
• 会话状态可以短期保存在运行服务中；MVP 不要求长期持久化。
• 超过轮数或上下文长度时必须裁剪旧轮次，并保留引用摘要。

5.7 展示层对账 manifest

Docusaurus 静态站不应被当成内容事实源，但发布后仍需要 SiteManifest 做漂移检测。

建议结构：

{
  "publishedAt": "...",
  "gitCommit": "...",
  "pages": [
    {
      "path": "publish/system/components/kunora-kgent/index.md",
      "url": "/system/components/kunora-kgent/",
      "sourceHash": "...",
      "renderedHash": "...",
      "status": "published"
    }
  ]
}

对账规则：

• 构建时基于 publish/** 和 Docusaurus 输出生成 URL/hash 映射。
• 部署后至少校验关键页面 URL 可访问，并保存结果。
• 漂移检测比较 Git commit、publish manifest、site manifest 和静态站可访问状态。
• 发现缺页、hash 不一致或部署版本落后时生成报告，不直接修改内容。

6. 如何使用

用户	使用方式
维护者	修改配置、review PR、处理冲突
智能体	通过 AgentBridge 读取任务并提交 PR
发布系统	读取 main 的 publish/**
问答系统	读取已审批索引

7. 验收标准

• 同步不会覆盖已整理内容。
• 所有冲突可审查。
• 所有正式变更进入 PR。
• 控制面能调用 RAGFlow、Docusaurus、Meilisearch adapter；向量存储属于 RAGFlow 实施细节，不作为控制面直接依赖。
• 任意发布页面能追溯来源项目和来源版本。