产品设计文档 V9.0 · 系统 V12.11.0001 · 2026-08-24 · AI 全栈开发级

知微 · 产品设计文档

款多多全集团「数据大脑与知识底座」— 12 章节国际顶级开发规格，可直接用于开发排期

知微 · 产品设计文档（PRODUCT DESIGN DOCUMENT V9.0 · AI 全栈开发规格）

**系统**: 知微（ZHIWEI）— 款多多（KDD Auto）全球零售业 AI+Robot 体系 · 数据平面

**系统版本**: V12.11.0001 | **文档版本**: V9.0 | **最后更新**: 2026-08-24

**文档类型**: 国际顶级 AI 全栈开发级规格（对标 Palantir Foundry / Databricks / Microsoft Azure AI）

**可开发性**: 本文档包含用户故事+验收标准、数据模型 ER、API 契约、算法规格（复杂度+伪代码）、NFR、测试策略、部署运维，可直接用于开发排期。

**作者**: 知微工作区（CodeBuddy）

[产品定位与价值主张](#1-产品定位与价值主张)
[用户角色与用户故事（含验收标准）](#2-用户角色与用户故事含验收标准)
[系统架构（五层+服务集群+数据流）](#3-系统架构五层服务集群数据流)
[数据模型设计（ER + 表结构）](#4-数据模型设计er--表结构)
[API 契约（端点规格）](#5-api-契约端点规格)
[算法规格（7类60+ 含复杂度/伪代码）](#6-算法规格7类60-含复杂度伪代码)
[非功能需求（NFR）](#7-非功能需求nfr)
[测试策略（单元/集成/E2E/验收）](#8-测试策略单元集成e2e验收)
[部署与运维](#9-部署与运维)
[版本路线与发布计划](#10-版本路线与发布计划)
[风险与依赖](#11-风险与依赖)
[附录：术语表与参考](#12-附录术语表与参考)

1. 产品定位与价值主张

1.1 定位声明

知微（ZHIWEI）= 款多多全集团的「数据大脑与知识底座」：将全网 13 源情报、企业内部知识、多 AI 协同过程，加工为可检索、可推理、可自进化的知识图谱与智能检索服务。

**使命**: 从细微信息中发现全局趋势（见微知著）
**价值锚点**: 为天枢决策、中枢业务、地枢执行提供**零摩擦数据供给**
**竞争对标**: Palantir Foundry（知识图谱+数据网格）/ World Monitor（情报监测）/ Databricks Lakehouse（数据治理）

1.2 能力域与价值矩阵（RICE 评分）

能力域	覆盖范围(R)	影响(I)	信心(C)	投入(E)	RICE	优先级
情报采集	13 源×每日	3	0.9	2	17.6	P0
知识图谱	5633实体	3	0.85	3	8.5	P0
GraphRAG 检索	全问答	4	0.9	2	18.0	P0
多AI协同	五系统	4	0.8	3	10.7	P1
算法自进化	全系统	5	0.6	5	6.0	P2
记忆总线	全AI	3	0.9	2	13.5	P0

1.3 成功指标（North Star）

指标	定义	当前	6月目标	12月目标
NSM 核心	GraphRAG 回答采纳率	68%	75%	85%
知识增速	图谱实体月增	300/月	500/月	800/月
检索质量	RAGAS ctx_p	0.976	0.985	0.99
协同效率	驾驶舱任务完成率	82%	90%	95%
自进化	算法落地率	60%	80%	100%

2. 用户角色与用户故事（含验收标准）

2.1 用户角色

角色	描述	系统内身份
U1 长庚总/决策层	查行业趋势、拍板	驾驶舱管理员
U2 天枢编排者	决策需数据	API 消费者
U3 中枢分析师	报告素材	专题订阅者
U4 地枢运营	零售情报	API 消费者
U5 灵枢 Agent 工程师	训练知识底座	数据提供者
U6 系统管理员	运维/审计	管理控制台

2.2 用户故事（含 Given-When-Then 验收标准）

US-01 全局问答（P0）

作为 **U1 长庚总**，我希望能用一句话问行业趋势，并看到带证据链的回答，这样我能快速决策。

**Given** 我已登录驾驶舱并输入"2026 白酒行业趋势"
**When** 系统执行 GraphRAG 全局问答
**Then** 返回回答 + 至少 3 条证据链（来源/社区路径），响应 ≤5s
**验收**: RAGAS ctx_p ≥0.95；证据可追溯；无空壳回答

US-02 图谱搜索（P0）

作为 **U2 天枢编排者**，我希望通过 API 精确查实体及邻居关系，这样我能拿到决策数据。

**Given** 我调用 `GET /api/kg/entity/{name}`
**When** 实体存在
**Then** 返回实体属性 + 一级关系邻居（≤50）
**验收**: 响应 ≤300ms；命中率 100%（幂等查重）

US-03 多AI协同指令（P1）

作为 **U1 长庚总**，我希望在驾驶舱向全部 AI 下发指令并实时看进度，这样我能掌控协同。

**Given** 驾驶舱发送指令 target=all
**When** Hermes 收到并 delegation 扇出
**Then** 返回 run_id，前端 3s 轮询展示思考/工具/回答事件流
**验收**: 指令 ≤3s 返回 run_id；事件流实时；完成回执

US-04 情报定时采集（P0）

作为 **U6 管理员**，我希望 13 源每日自动采集并入库，这样情报不靠人工。

**Given** workflow-engine 定时触发
**When** 采集执行
**Then** SimHash 去重后入库，记录来源/时间戳
**验收**: 每日任务完成率 ≥98%；重复率 ≤5%；失败自动重试

US-05 记忆总线共享（P0）

作为 **U2-U5 任一 AI**，我希望跨 AI 共享记忆并保持版本一致，这样协同不丢上下文。

**Given** 某 AI 写记忆
**When** 走记忆总线 WAL
**Then** 同步 DB 写 + 异步治理，读侧 v_seq 校验
**验收**: 写 P95 ≤200ms；读 P95 ≤500ms；越权 403

US-06 算法自进化（P2）

作为 **U6 管理员**，我希望系统基于反馈自动微调检索排序，这样质量持续提升。

**Given** 反馈数据（点赞/点踩）累积
**When** 置信度足够
**Then** Thompson Sampling 更新路径权重，RAGAS 评估后发版
**验收**: 无人工干预；RAGAS 不降级；可回滚

2.3 用户旅程（采集→问答）

长庚总: 驾驶舱提问 → 看到回答+证据 → 点赞反馈
         ↑                                      ↓
workflow-engine 定时采集 ←—— 反馈回流强化检索 ←—— 检索服务
    ↓
13源采集 → SimHash去重 → 图谱注入(幂等) → 向量化 → Qdrant
    ↓
    下一次提问命中率更高

3. 系统架构（五层+服务集群+数据流）

3.1 五层技术架构

层	组件	技术	责任
L1 业务层	驾驶舱/专题/搜索/AI对话	React/HTML + FastAPI 6002	用户交互
L2 算法层	图谱嵌入/GNN/RAG/深度/强化	TransE/GraphSAGE/bge-m3/Reranker	智能处理
L3 数据层	MySQL/Qdrant/记忆总线	SQL/1024维向量/WAL	存储检索
L4 协议层	REST/WS/MCP	JSON-RPC/Ed25519	系统互连
L5 硬件层	CVM 4核7.4G/118G	Hermes/workflow-engine	运行底座

3.2 服务集群（端口分配）

服务	端口	职责	状态
AI Agent 主服务	6002	全部 API + 路由 + 鉴权	✅
Workflow Engine	6003	APScheduler 定时调度	✅
Qdrant 向量库	6004	1024维向量检索	✅
MCP Server	6005	22 工具 MCP 协议	✅
Wiki.js	6001	知识库前端	✅

3.3 数据流（核心闭环）

[采集] 13源 → SpiderEngine → SimHash去重 → TextCNN分类 → 质量门禁
                                    ↓
[入库] 图谱注入(幂等) → entities/relations → node2vec/bge-m3嵌入 → Qdrant
                                    ↓
[检索] 用户问题 → 混合检索(BM25+向量+图谱) → Reranker → GraphRAG → 回答+证据
                                    ↓
[反馈] 点赞/点踩 → 反馈表 → Thompson Sampling 权重更新 → 回到检索

3.4 部署架构（当前 + 目标）

当前: 单机 CVM（6001-6005 全部本地）
目标: 采集集群 / 图谱集群 / 检索集群 水平扩展

4. 数据模型设计（ER + 表结构）

4.1 实体关系总览（ER）

[entities] 1───n [relations] n───1 [entities]
   │                          │
   │                          ├── [entity_embeddings] (node2vec/bge-m3)
   │                          └── [community_summaries] (GraphRAG社区)
   │
   ├── [crawl_state] / [crawl_jobs] / [crawl_visited]   (SpiderEngine)
   ├── [news_snapshots]                                   (采集快照)
   ├── [memory_bus]                                       (记忆总线)
   └── [feedback]                                         (检索反馈)

4.2 核心表结构（DDL 规格）

表 entities（实体）

CREATE TABLE entities (
  entity_id   VARCHAR(64)  PRIMARY KEY,     -- 唯一ID(幂等)
  entity_type VARCHAR(32)  NOT NULL,        -- 35类白名单
  name        VARCHAR(255) NOT NULL,
  properties  JSON,                          -- 动态属性
  summary     TEXT,
  created_at  DATETIME,
  updated_at  DATETIME,
  UNIQUE KEY uk_name_type (name, entity_type)  -- 幂等查重
);

表 relations（关系）

CREATE TABLE relations (
  relation_id   VARCHAR(64) PRIMARY KEY,
  source_id     VARCHAR(64) NOT NULL,
  target_id     VARCHAR(64) NOT NULL,
  relation_type VARCHAR(32) NOT NULL,       -- supply/compete/found...
  properties    JSON,
  created_at    DATETIME,
  FOREIGN KEY (source_id) REFERENCES entities(entity_id),
  FOREIGN KEY (target_id) REFERENCES entities(entity_id)
);

表 entity_embeddings（向量）

CREATE TABLE entity_embeddings (
  entity_id  VARCHAR(64) PRIMARY KEY,
  embedding  BLOB NOT NULL,                  -- 1024维 bge-m3 / 128维 node2vec
  model      VARCHAR(32) DEFAULT 'node2vec', -- 来源模型
  updated_at DATETIME
);

表 memory_bus（记忆总线）

CREATE TABLE memory_bus (
  memory_id   VARCHAR(64) PRIMARY KEY,
  agent_id    VARCHAR(64) NOT NULL,
  memory_type VARCHAR(16),                   -- long_term/fact/task
  content     TEXT,
  v_seq       INT NOT NULL,                  -- 版本链
  namespace   VARCHAR(32),
  created_at  DATETIME
);

表 feedback（反馈）

CREATE TABLE feedback (
  feedback_id VARCHAR(64) PRIMARY KEY,
  query       TEXT,
  answer_id   VARCHAR(64),
  rating      TINYINT,                       -- 1赞/0/-1踩
  agent_id    VARCHAR(64),
  created_at  DATETIME
);

4.3 数据一致性设计

场景	机制
实体幂等	name+type 唯一键查重
关系完整性	外键约束 + 悬空检测
记忆版本	v_seq 乐观锁 + WAL
图谱/向量同步	双写事务 + 重建脚本

5. API 契约（端点规格）

全部端点：`X-API-Key` 鉴权（nginx 注入）+ JWT 可选。响应统一 `{status, data, code}`。

5.1 图谱 API（kg）

方法	路径	请求	响应	说明
GET	/api/kg/entity/{name}	-	{entity, relations[]}	精确查实体+邻居
GET	/api/kg/search?q=&limit=	q,limit	{results[]}	模糊搜索
GET	/api/kg/stats	-	{entities, relations}	图谱统计
POST	/api/kg/entity	{name,type,props}	{entity_id}	创建(幂等)
POST	/api/kg/relation	{source,target,type}	{relation_id}	创建关系
GET	/api/kg/community/{id}	-	{summary, entities}	社区摘要

5.2 RAG 检索 API

方法	路径	请求	响应	说明
POST	/api/rag/global-query	{query, no_cache?}	{answer, evidence[]}	GraphRAG 全局问答
POST	/api/rag/hybrid-search	{query, top_k}	{hits[]}	混合检索
POST	/api/rag/feedback	{query, rating}	{ok}	反馈回灌

5.3 记忆总线 API（memory_bus）

方法	路径	请求	响应	说明
POST	/api/memory/write	{agent,type,content}	{v_seq}	写记忆(WAL)
POST	/api/memory/read	{agent_id?}	{memories[]}	读记忆(越权403)
GET	/api/memory/stats	-	{count, by_type}	统计
POST	/api/memory/rebuild	{confirm}	{ok}	重建缓存

5.4 驾驶舱 API（cockpit）

方法	路径	请求	响应	说明
GET	/api/cockpit/overview	-	{local, tianshu}	驾驶舱聚合
GET	/api/cockpit/run/{run_id}	-	{status, events[]}	执行追踪
POST	/api/cockpit/command	{instruction, target}	{run_id}	指令下发
GET	/api/cockpit/runs	?limit=	{runs[]}	历史执行

5.5 系统 API

方法	路径	说明
GET	/health	健康检查
GET	/api/stats/system	系统统计
GET	/api/auth/verify	鉴权验证
POST	/api/workflows/{name}/run	触发工作流

5.6 API 错误码约定

code	含义	HTTP
200	成功	200
401	未认证	401
403	越权/身份不符	403
404	不存在	404
409	冲突(幂等/版本)	409
422	参数缺失	422
502	上游不可用	502

6. 算法规格（7类60+ 含复杂度/伪代码）

6.1 知识图谱嵌入（KGE）

算法	输入	输出	复杂度	用途
TransE ✅	(h,r,t) 三元组	实体/关系向量	O(E·d)	基础嵌入
RotatE	三元组	复数向量	O(E·d)	对称关系
ComplEx	三元组	复数嵌入	O(E·d)	链路预测
ConvE	三元组	卷积嵌入	O(E·d)	高表达
DistMult	三元组	对角嵌入	O(E·d)	高效

TransE 伪代码

输入: 三元组集合 S = {(h,r,t)}，实体集 E，维度 d
初始化: θ = {e ∈ R^d, r ∈ R^d} ~ U(-6/√d, 6/√d)
for epoch in 1..N:
    S_batch = 采样 batch 个正样本
    S_neg   = 对每个 (h,r,t) 替换头/尾生成负样本
    loss = Σ [γ + d(h+r,t) - d(h'+r,t')]+   # margin hinge
    θ ← θ - η·∇loss
输出: 实体向量表 (E×d)，关系向量表 (R×d)

6.2 图神经网络（GNN）

算法	复杂度	适用规模	用途
GCN	O(E·d²)	<100万节点	实体分类
GAT	O(E·d²)	<100万	重要邻居
GraphSAGE	O(k·	V	·d)	大规模	采样聚合
node2vec ✅	O(	V	·L·p)	大规模	实体向量

node2vec 流程

输入: 图 G(V,E)，游走长度 L，p/q 参数
for 每次游走:
    u = 随机起点
    walk = [u]
    for i in 2..L:
        u = 根据 (p,q) 偏置采样下一个节点
    SkipGram(walk) 更新节点向量
输出: 每个节点 128 维向量

6.3 检索增强（RAG）

技术	复杂度(查询)	说明
BM25	O(词典大小)	稀疏关键词
HNSW 索引	O(log N)	近似最近邻
bge-m3 编码	模型推理	1024维
RRF 融合	O(K)	多路结果合并

混合检索伪代码

输入: query, top_k
1. s1 = BM25(query)                     # 稀疏
2. s2 = cos(bge-m3(query), 向量库)       # 稠密
3. s3 = 图谱实体邻居匹配                  # 结构
4. rrf_score(d) = Σ 1/(k+rank_i(d))      # 加权融合
5. top = 排序取 top_k
6. rerank = bge-reranker(query, top)     # 精排
7. return top_5 + 证据链

6.4 深度学习 NLP

算法	复杂度(训练)	用途
TextCNN ✅	O(n·d·k)	分类(快)
LSTM	O(n·d²)	序列
BERT	O(n²·d)	语义(重)
Transformer	O(n²·d)	长文本

TextCNN 流程: 词向量 → 多核卷积(2,3,4) → MaxPool → 拼接 → Softmax → 标签

6.5 强化学习（RL）

算法	状态	动作	应用
Thompson ✅	检索路径 Beta 分布	选路	A/B 探索
PPO	对话状态	回答策略	对话优化
DQN	决策状态	动作	路由

Thompson Sampling 伪代码

每条路径 i: 维护 Beta(α_i, β_i)
for 每次查询:
    θ_i ~ Beta(α_i, β_i)  for all i
    选 argmax θ_i 执行
    若命中: α_i += 1  否则 β_i += 1

6.6 联邦学习（FL）

算法	通信量	隐私	应用
FedAvg ✅	O(模型)	高	多Agent聚合
FedProx	O(模型)	高	异构

FedAvg 流程

for round t:
    服务端广播 W_t 到各节点
    各节点本地训练 K 步 → W_t^k
    服务端聚合 W_{t+1} = Σ (n_k/N)·W_t^k

6.7 治理算法

算法	复杂度	用途
Louvain ✅	O(E)	社区发现
SimHash ✅	O(文本)	去重
K-Means ✅	O(N·K·iter)	聚类
PageRank ✅	O(E·iter)	实体重要性
Apriori	O(2^item)	关联规则

7. 非功能需求（NFR）

7.1 性能（SLA）

场景	P50	P95	P99	约束
图谱实体查询	50ms	300ms	1s	单实体
混合检索	300ms	1s	2s	Top-K
GraphRAG 问答	2s	3.77s	6.5s	全局
记忆写入	80ms	200ms	500ms	同步段
驾驶舱轮询	100ms	500ms	1s	overview

7.2 可用性

服务可用性 ≥ 99.5%（周）
定时工作流完成率 ≥ 98%
故障恢复 ≤ 5min（systemd 自愈）

7.3 容量

资源	当前	规划
图谱实体	5,633	100,000
图谱关系	725万	5,000万
Qdrant 向量	6集合	20集合
记忆总线	12,441	100万

7.4 安全

项	要求
身份	Ed25519 签名 + X-Agent-Id 实名
鉴权	API Key + JWT fail-fast
越权	403 拒绝 + 审计日志
注入	SQL 全参数化 / SSRF 白名单 / 路径穿越校验
密钥	只从环境变量读取，fail-fast
日志	不落密钥/记忆正文

7.5 可观测性

健康检查 `/health`
关键指标: 检索延迟/成功率/图谱增速/工作流完成率
审计日志: 全部写操作留痕

8. 测试策略（单元/集成/E2E/验收）

8.1 测试金字塔

层	数量	覆盖
单元测试	150+（目标）	解析/映射/状态机
集成测试	30+	API 全端点 curl
E2E	10+	驾驶舱全流程
验收	6 条	US-01~06

8.2 关键测试用例

T-01 图谱幂等（集成）

Given: POST /api/kg/entity {name:"白酒行业", type:"industry"}
When:  同一请求再发一次
Then:  第二次返回已存在 entity_id（不新建）

T-02 越权读（安全）

Given: AI-A 请求读 AI-B 的记忆 (agent_id=B)
When:  X-Agent-Id=A
Then:  403 IDENTITY_MISMATCH

T-03 防空壳（检索）

Given: 节点 completed 但无产出
Then:  状态标 ⚠ 而非 ✔

T-04 GraphRAG 长尾增强（质量）

Given: 短问题(<23字) 命中社区为空
Then:  kg_direct 直补图谱证据，回答 ≥300 字

8.3 回归体系

`pytest` 全量：120+ 项当前，目标 150+
`regression_check.sh`：布局/语法/健康 5 步
`check_layout_gate.sh`：HTML 门禁

9. 部署与运维

9.1 部署拓扑

[nginx :443] ─→ 6002 AI Agent ─→ 6003 WF / 6004 Qdrant / 6005 MCP
              └→ /cockpit /zhiwei-* 静态页

9.2 发布流程

1. 版本文件同步 (VERSION.md → version.py --sync)
2. 单测全绿 (pytest ≥150)
3. 重启 6002 (systemctl restart)
4. curl 冒烟 (health + overview 200)
5. 灰度 (可选: 新端点先于旧)
6. 回滚 (systemctl + 版本回退)

9.3 运维清单

任务	频率	命令
健康检查	每日	curl /health
图谱备份	每周	mysqldump kg_db
向量备份	每周	Qdrant snapshot
日志轮转	自动	logrotate
内存监控	实时	Swap<50% 告警

10. 版本路线与发布计划

版本	代号	时间	里程碑	交付物
v4.2	联微	2026-08~09	记忆总线/驾驶舱	cockpit + memory_bus
v5	慧微	2026-09~11	算法自进化	reranker+feedback闭环
v6	耀微	2026-12~2027	联邦/多Agent	FedAvg+MARL

11. 风险与依赖

风险	等级	缓解
天枢 API 不可用	P1	本地双轨降级
Hermes 单点	P1	workflow-engine 兜底
图谱数据稀疏	P2	主动学习+人工标注
模型资源受限	P2	蒸馏+增量学习
Swap 内存紧张	P1	内存门禁(≥3G+Swap<50%)

12. 附录：术语表与参考

术语	定义
GraphRAG	图增强检索生成
RAGAS	RAG 四维评测框架
delegation	Hermes 子智能体扇出
WAL	Write-Ahead Log 预写日志
v_seq	记忆版本号(乐观锁)
KGE	知识图谱嵌入

参考: 地枢中台产品文档 V5.3 / 地枢蓝图 V7.3 / 玄机9层推理 / 天工开发规范

文档版本 V9.0 · 2026-08-24 · 可直接用于开发排期（P0: 图谱/检索/记忆/驾驶舱）

知微 · 产品设计文档 V9.0 · 2026-08-24 · 国际顶级 AI 全栈开发规格 · 参考地枢 V5.3