# 知识库架构总览 / Knowledge Base Architecture

本文档总结当前 bid.hao.work 知识库系统架构，并说明如何在迭代中自动适配（自动进化 + 文档迭代控制）。

---

## 1. 架构目标 / Goals
- 统一承载：招投标/采购平台的需求、设计、接口、运维文档统一管理。
- 可追溯：所有文档通过 Git 记录历史与差异。
- 可扩展：REST API 支持文档与迭代管理。
- 可进化：SearXNG + Qwen3-Max 自动沉淀新事实并增量索引到 GraphRAG。

---

## 2. 总体结构 / High-level Architecture

```
[Browser /docs] -> [Nginx HTTPS] -> [Go Docserver]
                         |           - Markdown render
                         |           - Git history/diff
                         |           - REST API
                         |           - Notes/Automation UI
                         v
     +-------------------+-----------------------------+
     |                   |                             |
  docs/*.md     docs/iterations.json       docs/creative-notes.json
  (文档库)          (迭代记录)                   (创意笔记)

                    [Auto Evolve Script]
                SearXNG -> Qwen3-Max -> GraphRAG
                                   |
                                   v
                     /root/ca_v3/cps/input/auto_learning.txt
```

---

## 3. 关键组件 / Key Components

### 3.1 文档服务 / Docserver
- 路径：`/root/ca_v3/bid/tools/docserver/main.go`
- 功能：
  - 文档目录与 Markdown 渲染
  - Git 历史、差异对比
  - REST API（认证、CRUD、迭代、历史、diff）
  - 创意笔记模块
  - 自动化监控页
- 访问入口：
  - `https://bid.hao.work/docs/`
  - `https://bid.hao.work/docs/notes`
  - `https://bid.hao.work/docs/automation`

### 3.2 文档数据 / Docs Data
- 文档存储：`docs/*.md`
- 迭代记录：`docs/iterations.json`
- 创意笔记：`docs/creative-notes.json`（不入库）

### 3.3 REST API / REST API
- 认证：
  - `POST /api/auth/login`
  - `GET /api/auth/me`
- 文档 CRUD：
  - `GET /api/docs`
  - `POST /api/docs`
  - `PUT /api/docs`
  - `DELETE /api/docs`
- 迭代控制：
  - `GET /api/iterations`
  - `POST /api/iterations`
- 版本与对比：
  - `GET /api/docs/history`
  - `GET /api/docs/diff`

### 3.4 自动进化 / Auto Evolve
- 脚本：`tools/auto_evolve/evolve.py`
- 查询队列：`automation/queries.txt`
- 状态输出：`automation/status.json`
- 日志：`automation/logs/`
- GraphRAG 输入：`/root/ca_v3/cps/input/auto_learning.txt`
- 定时任务：
  - `bid-knowledge-evolve.service`
  - `bid-knowledge-evolve.timer`（2 分钟检查，当前固定 2 分钟）

### 3.5 自动调研 / Auto Research
- 脚本：`tools/auto_research/research.py`
- 目标清单：`automation/research_targets.json`
- 状态输出：`automation/research_status.json`
- 日志：`automation/research_logs/`
- 运行产出：`automation/research_runs/`
- GraphRAG 输入：`/root/ca_v3/cps/input/auto_research.txt`

---

## 4. 迭代适配机制 / Iteration Adaptation

系统通过两条路径实现“自动适配迭代”：

### 4.1 文档迭代 / Docs Iteration
1) 使用 `POST /api/iterations` 写入一次迭代记录（版本/标题/摘要/关联文档）。
2) 通过 REST 更新相关文档内容（`/api/docs`）。
3) Git 自动记录历史，可在 UI 查看历史与 diff。

### 4.2 知识进化 / Knowledge Evolution
1) `automation/queries.txt` 定义关注主题。
2) 定时触发 SearXNG。
3) Qwen3-Max 过滤并提炼事实。
4) 追加到 GraphRAG 输入文件。
5) 运行 GraphRAG 增量索引，形成可检索的最新知识。

> 结果：文档与知识库都能持续更新，并可通过 REST + Git 进行版本控制。

---

## 5. 运维与配置 / Ops & Config
- `.env` 管理全部配置（API Key、LLM、GraphRAG、路径、token）。
- Nginx 反向代理 `/docs/` 到 docserver。
- systemd 负责 docserver 与自动进化的可靠运行。
- 时间基准：系统前后端统一 UTC+8。

---

## 6. 建议流程 / Suggested Workflow
1) 新增业务或政策需求 → `docs/*.md` 文档更新。
2) 记录迭代 → `POST /api/iterations`。
3) 自动进化定期补充外部事实。
4) 通过 `/docs/automation` 和 Git 历史审计更新轨迹。

---

如需新增迭代模板或自动化策略，请在 `docs/18-docs-rest-api.md` 与 `docs/19-graphrag-searxng.md` 中补充细节。