WeKnora 融合实施计划（执行清单）
版本 0.2 · 2026-09-29 · 状态：随方案 v0.2 重排为 S0–S4；S0 待执行 与 融合方案（v0.2，双核定位）的关系：方案定架构与决策（why），本文件定执行顺序、步骤与验收（how）。v0.1 的阶段 0/1 已完成，执行记录见 §1；原阶段 1b/2/3/4 并入 S1–S4。 依据：2026-09-27/28 实测执行 + 2026-09-29 对
7.weknora（部署实例）与8.xgb_wiki（HEAD9429969）的核对盘点。远端增量已于 2026-09-29 并轨复核：staging 分发通道五笔（b189b70..c8b379e，数据分发方案：GitHub Releases 取数免 clone 整仓）与融合方案无冲突。
0. 当前基线（2026-09-29 核对）
| 项 | 状态 | 证据 |
|---|---|---|
| WeKnora v0.8.2 部署 | ✅ 运行中 | 6 容器自 2026-09-27 起健康（app/frontend/docreader/postgres/redis/neo4j），API 18080 / UI 18081 |
| 全量推送 | ✅ 完成 | 推送进度标记 data/weknora_push.json 与文档映射 data/weknora_map.json 各 4844 条（2026-10-03 补推 9/25–9/30 共 34 篇后核对；9/29 基线 4810 条时曾与库内 knowledges/chunks/21 个月份标签完全对账）；窗口 2025-01-01 → 2026-09-30 |
| KB 配置 | 现状 | xgb-研报（ID abe10e59-0100-4fdf-b319-b696a7caec98）：wiki_enabled=false / graph_enabled=false / vector+keyword=true / extract_config disabled——S2 前不动 |
| 模型 | ✅ 已定型 | embedding = doubao-embedding-vision（dim 2048，换型需清库重灌）；chat 默认 doubao-seed-2-1-pro（builtin_models.yaml，已从注册时的 ark-code-latest 切换）；无 rerank |
| API key | ⚠️ 过宽 | 1 把 key 14 项能力（retrieve/chat/ingest + 全套 manage_*），方案建议仅 ingest+retrieve——S0 收紧（D9） |
| MCP（Model Context Protocol，模型上下文协议） | ❌ 未开始 | mcp_endpoints=0、mcp_services=0（S1/S3） |
| 本机 8.xgb_wiki | 已与远端并轨 | master = 远端 staging 五笔（数据分发通道）+ 本地融合管道/方案/清扫提交；远端推送已切 SSH（gh 凭据助手不可用，改用 SSH 密钥） |
1. 已完成执行记录（v0.1 阶段 0/1，留档）
- 实例初始化 + 手灌验收（阶段 0，2026-09-27）：注册管理员（seuzxh）；声明式模型注册（
builtin_models.yaml+.env插值）；建 KB；.env三项WEKNORA_*配置并实测；runner 裸名 bug 修复（7d65bd8）；--seed 50实推 50/50（首轮 27 篇因 Ark 账号级 429 失败，分批 reparse 每 5 篇/90s 全部重试成功，终态 50/50 completed、801 chunks）；hybrid-search 预验命中正确。沉淀：Ark plan 端点账号级限流必须分批限速；reparse 正确端点为POST /api/v1/knowledge/{id}/reparse（不嵌套在 knowledge-bases 下）。 - 滚动窗口全量（阶段 1，2026-09-27/28）：近 3 月窗口 729 篇（推送 679 + 按推送进度标记跳过 50 + 0 失败，10 篇/90s 无一次 429）；窗口扩展
--since 2025-01-01共 4810 篇（nohup 常驻约 12.5h，2026-09-28 09:27 收尾）；月份标签体系上线（9cafebb）：推送自动打 YYYY-MM 标签 + 服务端文档 ID 映射留存（weknora_map.json），存量 730 篇按标题回连回填（100% 命中）；推送进度标记与文档映射每批增量落盘（9429969）。 - 遗留待办（转入 S0）：runner 回归测试、sync 链式挂载（D2 已拍板未接线）、UI 问答验收（原步骤 9，因问答迁离决策改在 WeKnora UI 验收）。
2. S0 收尾与加固（约半天）
- sync 链式挂载（D2 接线）：
scripts/sync/sync_data.py成功末尾调push_to_weknora.py（增量当日）；push 失败不阻断 sync 本身（退出码区分、日志提示可补跑），push 幂等靠推送进度标记。注意：sync 在持有 MySQL 凭据的环境跑，接线需同时兼容无 WeKnora 配置的环境（缺配置跳过并提示） - runner 回归测试：run_tests.py §15 扩展——按推送进度标记跳过 / DuplicateKnowledge(409) 记入推送进度标记 / 配置缺失退出码 2 / 导入名静态检查（防裸名 NameError 复发）
- API key 收紧（D9）：WeKnora UI 重建仅授
ingest + retrieve的 key（若 S2 实测需 wiki 写，按 D9 结论追加）；旧 key 吊销；8.xgb_wiki/.env同步替换 - WeKnora UI 问答验收（替代 v0.1 手灌步骤 9）：3–5 题（例："CPO 最近有什么观点？"、"9 月券商对半导体设备的首次覆盖有哪些？"），核对引用命中、小节定位、无编造；chat 模型按 seed-2-1-pro 验收，质量不足换模型（零迁移，不动数据）
验收标准：sync 后 WeKnora 当日新增对账一致；重跑 push 全跳过；run_tests 全绿（§15 扩展项通过）；新 key 实测 ingest/retrieve 双通、manage 类调用 403；问答验收通过并在本文勾选。
3. S1 问答迁离（约半天）
- WeKnora MCP endpoint → ZCode：UI「设置→发布集成→MCP Server」建端点 →
/mcp/<endpoint_id>（Streamable HTTP + Bearer）→ 写入 ZCode 配置 → 新会话验证工具可见（检索/阅读/ask） - xgb 站点下线问答：移除
templates/chain.html:22-42问答框；移除/api/ask路由（src/web/api.py:26-37）；src/llm/qa.py打 tagask-frozen→ 用户确认 → 删除；nlq不动 - 配套：run_tests §3（API 节）与静态站相关断言同步调整；链页加"AI 问答已迁 WeKnora"指引链接（UI 地址）；docs/architecture.md 路由表同步
验收标准：ZCode 会话内可直接检索研报库并 ask（带引用）；/api/ask 返回 404、链页无问答框；run_tests 全绿；ask-frozen tag 已打。
4. S2 图谱接管（约 2–3 天）
顺序敏感：先实测门，再铺量。
- 两项 Wiki 实测（go/no-go 门，方案 §4.2）：
- a. 试点 KB（新建 50 篇小库或直接主库）开 wiki 能力 →
GET …/wiki/stats观察pending_tasks/is_active是否对存量文档排队 LLM 生成；API 建页是否触发生成 - b. 现 API key 调
POST …/wiki/pages验证写权限；无则走服务账号 Bearer / 申请能力（结论回填 D9） - 本体统一：以
src/kg/ontology.py（8 实体/11 关系）为唯一本体源；graph.db的 5 实体/4 关系简化模型不再演进 - Wiki 本体页生成 runner：
scripts/kg/push_wiki_pages.py——主库表 → 页面 Markdown（题材页=链位置+时间窗口径+关联个股按衰减热度+近期观点 top N+source_refs关联原文；链页=环节序列+题材清单）→[[互链]]+ aliases 同义词 → REST 建页/更新（幂等键 slug + version 乐观锁，409 重读再写）；代码放置遵守 AGENTS 决策表 - 试点 ≈50 主题：优先高频题材（近 90 天出现次数 top50），人工抽检 10 页（链位置/个股/观点/互链/别名）
- Neo4j 直写（方案 §4.1 路径 B）：
src/integrations/weknora/graph.py+scripts/kg/sync_weknora_graph.py；三处门控配置（GraphEnabled=false + ExtractConfig.Enabled=true + 最小 few-shot）；Neo4j 凭据7.weknora/SECRETS.txt - /graph 退役：移除路由与模板（含静态站 graph 产物），导航指向 WeKnora UI Wiki 图谱页（按 D8 结论：iframe 实测可嵌则内嵌，否则外链/薄视图）；
graph.db+build_graph.py+kg_{extractor,schema,query,cluster}.py打 taggraphdb-frozen→ 用户确认 → 删除；保留ontology.py/rdf_export.py/gen_chain_map.py/extract_viewpoints_llm.py
验收标准：WeKnora Wiki 图谱页可浏览本体（overview 可见主题聚类、题材页 ego 展开正确）；聊天管线实体检索与 Agent 工具 query_knowledge_graph 返回本体实体；抽检 3 个题材节点 chunks 指向正确原文；/graph 404、导航生效；run_tests 全绿；graphdb-frozen tag 已打。
5. S3 精确查询注入 WeKnora（约半天，可与 S2 并行）
scripts/ops/mcp_server.py加--http（FastMCPtransport="streamable-http"，10–15 行 + 端口/日志参数）- 常驻（D3 建议 systemd user unit +
Restart=on-failure；备选 docker/手动） - WeKnora「工具箱→MCP 服务」注册（仅 SSE/HTTP，禁 stdio）
验收标准：WeKnora Agent 对话中调 search_themes/hot_streaks 返回精确结构化数据；组合问题（"近5天连涨且 9 月研报提及的题材"）Agent 能自动混用 RAG（检索增强生成）检索与 MCP 工具。
6. S4 内容回流增强（可选，暂不排期）
报告详情页"语义相关研报"（hybrid-search API，仅 Flask 形态）；题材页"相关观点检索"；KB 标签扩展（栏目/题材标签，推送时随月份标签一并打）。启动前先做一周使用回看（ZCode/WeKnora 问答频次与命中质量）再定优先级。
7. 决策点汇总
| # | 决策 | 结论/建议 |
|---|---|---|
| D1 | Chat LLM 选型 | ✅ 已定：默认 doubao-seed-2-1-pro（原 ark-code-latest 已切换）；质量不满足再换，零迁移 |
| D2 | 日常推送挂载点 | ✅ 已定：sync 链式调用（2026-09-27 拍板）；S0 接线 |
| D3 | mcp_server 常驻方式 | 待定。建议 systemd user unit + Restart=on-failure |
| D4 | 滚动窗口 N | ✅ 事实已定：2025-01-01 起全量完成（累计 4844 篇）；日常增量随补推 |
| D5 | HTML 渲染器 | 待定（低优先）。首期 strip_html 保底；外部工具就绪后插拔（协议已预留，export.py:20） |
| D6 | embedding 本地 vs 外部 | ✅ 已定：外部 Ark doubao-embedding-vision（dim 2048） |
| D7 | Wiki 通道启用方式 | 待 S2 实测：若开 wiki 能力触发存量 LLM 扇出 → 不开管线、仅 API 建页；若连 API 建页也受限 → 图谱浏览降级薄视图 |
| D8 | /graph 替代形态 | 待定。fallback 链：iframe 直嵌 WeKnora UI（实测登录态与 CSP（内容安全策略））→ 外链跳转 → 本站薄视图（读 wiki/graph API 自渲染） |
| D9 | API key 能力收紧范围 | S0 先收到 ingest+retrieve；S2 按 wiki 写权限实测结论决定是否追加（或改服务账号 Bearer） |
8. 风险与对策
| 风险 | 对策 |
|---|---|
| Wiki 能力开启触发存量 4844 篇 LLM 逐篇生成扇出（成本 + 429） | S2 实测门先行（wiki/stats 观测）；不可控则走 D7 降级 |
| API key 无 wiki 路由写权限 | S2 实测；缺则 D9 处理 |
| iframe 嵌 WeKnora 主 UI 被拦（CSP frame-ancestors 仅配 embed.html；主 UI 需登录态） | D8 fallback 链 |
| manual 导入自定义 metadata 被服务端丢弃 | 幂等只靠本地推送进度标记与标题回连；结构化过滤走 KB 标签 |
| 检索无时间权重（7 月/9 月混排实测） | 提问带时间词 + 月份标签过滤；精确时间窗走 nlq/MCP |
| 重解析/重导入删图谱不重建 | 直写 runner 幂等可重跑；运维红线写入 operations.md（S2 时） |
| Ark 账号级 429 限流 | 推送分批限速（10 篇/90s 实测安全）；Wiki 生成同样限速 |
| WeKnora 升级 API 漂移 | 升级前 --dry-run 冒烟；client.py 以实际响应为准 |
| 另一台机器未同步提交 | 本文件按本机 9429969 基线；同步后复核，必要时修订 S0–S4 |
9. 协作边界（两仓分工）
- 所有新代码进
8.xgb_wiki（按 AGENTS.md 放置规则与 Conventional Commits）；7.weknora仅作部署+配置+数据，不改其源码（builtin_models.yaml 等声明式配置除外） - 实施每阶段完成后：更新
weknora-integration.md状态行 + 本文勾选验收项 - 退役一律"tag 冻结 → 用户确认 → 删除"，提交说明注明 tag 名与替代物