xgb_wiki 文档
xgb_wiki：将选股宝脱水研报（内网 MySQL，7981 篇，2023-11 → 2026-09）整理为题材本体——题材在产业链中的位置、关联个股（出现次数 / 衰减热度 / 5-30日时间窗 / 活跃天数）、推荐观点、券商引用、评级事件与图片证据。8 实体 / 11 关系，schema 兼容 Ontology-Playground，实例数据经 Flask 本地展示 + Cloudflare Pages 静态站（CI 自动发布，含 /daily 每日简报、/mindmap 当日脑图、/graph 知识图谱），并经 /api/nlq、MCP（Model Context Protocol，模型上下文协议）server 与 skill 对外提供自然语言查询能力。
文档地图（按类别）
① 项目核心——设计、架构与数据
| 文档 |
内容 |
什么时候读 |
| 设计方案 |
为什么这样设计：数据事实基础、本体 schema、衰减热度 / 时间窗与活跃天数 / 推荐观点 / 开放字典等模型（§2.4、§2.4b、§2.5、§2.6）、决策记录（v2.1，已实施状态） |
改本体结构、加实体关系、改时间窗口径之前必读 |
| 整体架构 |
系统怎么组织：数据流水线、模块划分与依赖方向、Web 路由（含每日题材 /timeline）、技术选型理由、部署形态（本机 Flask + CI 静态站 + MCP/skill 对外） |
想了解全貌 / 定位代码位置 |
| 数据模型 |
数据长什么样：全库 ER 关系图、8 实体表 + 7 关系表逐字段字典（含时间窗列与 theme_daily）、开放字典文件格式、chain_map 格式、本体↔存储对照、源库→本地映射（§5 含 MySQL 源库实测结构） |
写 SQL / 改 schema / 做导出时查 |
| 名词解释 |
术语什么意思：脱水研报/大涨题材行/衰减热度/时间窗/数据日/活跃天数/自然语言查询/MCP·skill…按业务域分组 |
读其他文档遇到生词时 |
② 数据同步与分发——从源库到各端
| 文档 |
内容 |
什么时候读 |
| 四系统总览 |
一页看懂全局：MySQL 生产库 / xgb-wiki / 火山 TOS / WeKnora 四系统的角色、位置、谁写谁读，两台机器职责与凭据分布，F1–F5 全部数据流程与新鲜度对账口径 |
系统多了理不清关系 / 新人入门第一篇 / 排查"数据为什么不新"时 |
| 数据分发方案 |
分发链路怎么定的：同步分层（镜像先行）、数据出 git 走 GitHub Releases、staging 分片版本化（TOS + 官方 SDK）的完整设计与决策记录（v1.4） |
动分发链路 / 了解四条通道（镜像/ETL/Releases/分片）状态时先读 |
| staging 镜像同步 |
原表镜像怎么同步：MySQL → staging.db 的环境准备（conda/VPN/.env）、命令速查、同步规则、验收对账、TOS 备份取回、故障排查 |
跑镜像同步 / 换设备初始化 / 排障 |
| staging 表结构 |
镜像库长什么样：5 张源表逐字段释义、表关系速览、栏目 tag 字典、新手陷阱、查询示例（agent 读 data/staging_schema.json） |
查 staging / 写镜像层 SQL 时当字典 |
| staging 工具实施计划 |
工具怎么落地的：五 Task TDD 实施计划（已全部完成）+ P1c 分片衔接与实测坑位记录 |
改造 staging 工具 / 复盘实施过程 |
| 数据同步（ETL） |
本体库怎么更新：MySQL→xgb_wiki.db 增量/全量同步的五阶段流程（环境检查/备份/临时库/校验/回退）、进度标记规则、校验清单、同步日志、备份恢复与排障 |
日常更新数据 / 同步报错 / 想了解校验与回退机制 |
③ 运维与发布——怎么跑、怎么上线
| 文档 |
内容 |
什么时候读 |
| 运行手册 |
怎么跑：环境准备、数据同步与时间窗重算、链映射审校、图片解析队列、对外查询（MCP/CLI/skill）、CI 发布、已知坑与红线 |
日常操作与排障 |
| Pages 发布 |
怎么发布：研报站 Cloudflare Pages CI（GitHub Actions 自动构建部署）+ 本体 schema 推 Playground fork + 文档站 MkDocs 完整配置 |
发布研报站 / 要创建文档站时 |
| EdgeOne 部署规划 |
大陆第二通道（规划稿）：腾讯 EdgeOne Pages 双通道架构、CLI 接入、默认域免备案、内容策略决策点、分阶段实施与验收 |
要新增大陆友好发布通道时 |
④ 专项方案——PRD 与融合规划
| 文档 |
内容 |
什么时候读 |
| 每日简报 PRD |
每日简报的需求与决策：观点单元口径（聚合拆分/正文分节主源）、实测依据、已确认决策与分期 |
做 /daily 相关功能之前 |
| 股池策略 PRD |
推荐股池量化策略的需求与调研：股池实测规模、文献证据（事件漂移/入场时点/关注度拥挤）、策略假设空间、回测防自欺协议、待拍板项 |
做量化策略相关功能之前 |
| WeKnora 融合 |
WeKnora 后台核心知识库（方案 v0.2）：双核定位与能力迁移映射（复杂逻辑下沉边界）、文档导入管道（已实施，4810 篇对账）、图谱接管（Wiki 本体页 + Neo4j 直写）、问答迁离、MCP 双向集成、S0–S4 路线与决策记录 |
做 WeKnora 接入 / RAG（检索增强生成）问答 / 图谱接管之前 |
| WeKnora 融合实施计划 |
WeKnora 融合的执行清单（how）：当前基线对账、已完成执行记录、S0–S4 分阶段步骤与验收标准、决策点 D1–D9、风险与两仓分工 |
执行任一阶段前 / 勾验收项时 |
⑤ 历史与记录——决策过程存档
| 文档 |
内容 |
什么时候读 |
| 合并调研 |
与旧项目 2_xuangubao 合并的决策与实施记录：同源同数据结论、五路线对比、拍板记录（§7-8）、吸收清单与遗留待办 |
了解本项目与旧研报助手的关系 / 接手合并后续阶段时 |
| 分层重构 |
2026-09 目录分层重构记录：四阶段提交、四域包与蓝图结构由来、任务书外发现与修复、pip install -e . 前置说明 |
了解代码为什么这样组织 / 接手重构分支时 |
另有工作台文件不列入地图：specs/daily-brief-pending.md（简报待办清单）、diagrams/（交互图，见各文档内链）。
推荐阅读路径
- 新协作者：名词解释 → 设计方案 §1–2（含 §2.4b 时间窗与活跃天数模型）→ 整体架构
- 接手运维：运行手册 → staging 镜像同步 → 数据同步（ETL）→ 数据模型（当字典查）
- 要动数据链路 / 分发：数据分发方案（全景与决策）→ staging 镜像同步 → 数据同步（ETL）
- 准备发布：Pages 发布（含检查清单）
- 要查题材数据 / 接入智能体：名词解释（自然语言查询、MCP·skill 条目）→ 运行手册"对外查询"节（CLI 一行命令即可上手）
- 要接入 WeKnora / 做 RAG 问答：WeKnora 融合方案（§4 图谱接管与 §6 能力迁移映射是核心）→ 融合实施计划（当前阶段从 S0 起步）
目录约定
- 文件名用英文 slug（URL 友好），内容为中文；按五个子目录归类：
core/（项目核心）、data-sync/（数据同步与分发）、ops/（运维与发布）、specs/（专项方案）、history/（历史与记录），本地图与 MkDocs 导航分组与之对应；diagrams/ 为跨文档共用的交互图
- 站内一律相对链接（跨目录用
../）；指向仓库外或仅本地可用的资源（如内网路径）会明确标注
- 本目录可直接被 Jekyll / MkDocs / docsify 渲染为静态站（见 publishing.md）
- 原单文件版设计文档《实施方案.md》（v1.0–v1.1）已并入 design.md 并升级至 v2.0，git 历史
docs/实施方案.md → docs/design.md 连续