站点信息架构重构 — 设计 Spec

Scope: 把 dev.fsagent.cc 文档站从"按工程分层组织"翻成"按受众路径组织"，让投研同事自助用文档，让操作者（Liang）拿到唯一权威的现状索引。
不在本 spec 范围: 写新内容（如 P1.0 backend 业务代码）；改 core/ 或 skill/ 源代码；做对外 PaaS 站点。

1. Why this work

1.1 现象

进站读者（无论投研同事还是新接手工程师）说不清楚"现在到底做了什么、没做什么、计划什么、剩什么"。具体表现：

路线图口径错位 — /overview/roadmap 把 v0.2.0 P1.0 写成"进行中"，但 main 分支上 src/service/ 仍是空目录。真实状态：Tasks 7-10 实施完毕在 feat/p1.0-backend-skeleton（PR #13 OPEN/MERGEABLE），95/95 tests green；Tasks 11-12（Vultr deploy + profile 迁移）操作者侧未开工。
状态散落 4 处 — roadmap.md / planning/index.md 表格 / 各 spec 文档头部 banner / 仓库根 MASTER_PLAN.md，同一件事四处出现且口径不一致。
双轴规划自己打架 — 层级规划（01-09）和阶段规划（superpowers/）并列，同一项工作（如 P1.0 backend）出现在 06-v0.1.1-hotfix-and-p1、superpowers/specs/phase1、superpowers/plans/phase1、plans/2026-05-07-v0.1.1-hotfix.md 四处，无"以哪个为准"的标注。
MASTER_PLAN.md 游离 — 是最完整的产品 spec，却没纳入 nav，读者看不到。
/developer/ 是空壳 — 占着一级 nav 位置，里面只有一个 stub index.md。
缺 "Now / Next / Later" 单页 — 拼出当前进度需要点 4-5 个文档。
首页措辞对外不当 — Hero 区出现"Hermes 框架可复用"等内部黑话；features 区放"Phase 2 三 initiative"等规划术语。

1.2 受众优先级

优先	受众	真实场景	文档需求
主	投研同事（半技术）	多数在 WeChat 向 stock-research_Agent 发问；少数走命令行	"这能查什么 / 怎么提问 / cite 怎么读 / 不能查什么 / 答错怎么反馈"
辅	操作者（Liang，幕后支持）	给同事贴链接、维护 profile、推进 roadmap	唯一权威的现状索引；plan / spec 全集仍可达
不服务	外部潜在付费用户	—	整套迁出本站；本站不放价格、营销话术

依据：本次 brainstorming（2026-05-08）。

2. Goals / Non-goals

Goals

投研同事只看 /use/ 5 篇文档就能用 bot，且能正确读懂 cite。
操作者**贴一个 URL（/status/）**就能让协作者搞清当前进度。
站点任何字眼不暴露价格、对外营销内容。
v0.1.1 已 ship 的"价格路由 / served_by cite 字段"被当作产品语义记录，而非 changelog 一行字。
现有 spec / plan 全集保持可达，URL 不破。

Non-goals

不重写 /architecture/ 子树（保留原状）。
不删除 /planning/01-09-*.md 内容（仅调 sidebar 文案）。
不实施 P1.0 backend、不改 core/ 源代码。
不为对外 PaaS 站点做任何准备（那是独立项目）。

3. 新信息架构

3.1 一级 nav（5 项）

顶部 nav（从左到右）：
  使用 ──→ /use/                   B 受众主入口
  状态 ──→ /status/                A 受众主入口
  架构 ──→ /architecture/          深度读者 / 新接手工程师
  规划 ──→ /planning/              内部 spec 与 plan 全集
  关于 ──→ /about/                 项目摘要 + 边界

3.2 首页 `docs/index.md` 重写

Hero name: A 股投研 Agent
Hero text: 团队内部 A 股投研助手
Hero tagline: 数据可信 · 引用可溯 · 推理可审计 · 不下单只投研
Hero actions: 开始用 → /use/、项目状态 → /status/、这是什么 → /about/
Features（4 卡）:
- 回答带 cite — 每个数字、每个论断都附 tool_call_id / source / as_of / served_by，未引用即拒绝
- 价格自动路由 — 盘中走 akshare 实时盘口，盘后走 Tushare daily，cite 里 served_by 透明显示
- 不下单只投研 — 输出投研结论，不触发交易；没有 cite 的"凭感觉"判断不被接受
- 内部团队工具 — A 股是第一个 vertical；目前服务团队投研同事

不再出现：Hermes 框架可复用、Phase 2 三 initiative、¥198/月、Lite tier 等措辞。

4. `/use/` 子树（B 受众主入口）

4.1 文件清单

路径	一行承诺	来源（复用 / 新写）
`/use/index.md`	用法总览 + 3 张子页卡片 + "能答 / 不能答"摘要	新写
`/use/wechat.md`	WeChat 加 bot、提问、读 cite、答错怎么反馈	新写
`/use/price-freshness.md`	"当前价" vs "最近收盘" 何时是哪个	复用 + 改写自 `skill/stock-research/references/price-freshness.md`
`/use/what-it-can-answer.md`	v0.1.1 真实能力 + 不能答 + 计划中（含预期版本）	重写自 `overview/what-is-it.md` 后半段
`/use/cli.md`	`fetch_price.py / fetch_fundamentals.py` 用法 + 升级到 Service 模式的路径	新写（薄一层） · 目标读者：操作者 + 接入工程师，非 WeChat 投研同事
`/use/feedback.md`	bot 答错时怎么把信息给到操作者	新写

/use/index.md 索引页约束：3 张子页卡片 = wechat / price-freshness / what-it-can-answer（投研同事看的）。cli 和 feedback 不在 hero 卡里——cli 通过 sidebar 暴露给开发者；feedback 仅作为 wechat 页底部锚点链接。这样普通投研同事进 /use/ 不会被 CLI 章节干扰。

4.2 每篇正文骨架（具体到段标题）

`/use/wechat.md`

添加 bot — 由操作者拉群，无需自己加
提问怎么写 — 好例子 / 坏例子各 3 条（好例 = 查 600519 当前价，坏例 = 茅台怎么样 因 verifier 拒）
读懂回答 — 截图标注 value / metric / cite.served_by / cite.as_of / cite.tool_call_id
常见状况 — 交易时段 vs 盘后路由不同；不是 bug
答不上来时 — 见 /use/feedback

反馈渠道（已确认 2026-05-08）：直接在 stock-research_Agent 微信群里 @Liang。Liang 会手动把可复盘的反馈归档到 GitHub issue。不另建独立频道（避免分散运营负担）。

`/use/price-freshness.md`

路由表（提问场景 → metric / served_by / 数据延迟）
怎么主动问历史价
akshare 镜像 5-15 min 延迟的应对（cite.fetched_at 字段）

源数据：直接复用 skill/stock-research/references/price-freshness.md，转成 user-facing 措辞。

`/use/what-it-can-answer.md`

3 段固定结构：

✅ 现在能答（v0.1.1）
  - 个股价格（当前 / 历史收盘）
  - 个股基本面：P/E、P/B、ROE、毛利率、净利率、资产负债率
  - 简单组合（"600519 和 000858 谁 P/E 低"）

⏳ 计划中（标注预期版本，链 status 页）
  - 卖方研报抽取（P2，未启动）
  - 一致预期（P1.2）
  - 行业 peer 比较（P1.2）
  - 宏观（P1.2，akshare）
  - 美股 / ADR / 汇率（P1.2，Yahoo）

❌ 永远不会做
  - 下单 / 自动交易
  - 高频实时策略
  - 没有 cite 的"凭感觉"判断

`/use/cli.md`

安装：bash install.sh
配置：.env.example 里需要的 TUSHARE_TOKEN 等
跑：./scripts/fetch_price.py 600519 / ./scripts/fetch_fundamentals.py 600519 --period 20240331
输出：cite envelope JSON
升级路径：P1.0 backend 上线后自动走 Service 模式，无需改命令；只需写 TWILIGHT_SERVICE_URL + TWILIGHT_API_TOKEN 进 .env，删 TUSHARE_TOKEN

目标读者：操作者 + 接入工程师 + CI 测试。不是 WeChat 投研同事。Sidebar 文案明示这一点（如 命令行（开发者））。

⚠️ TBD-2（仍保留）— 是否在 P1.0 上线时给本页贴 deprecate 横幅？延后到 P1.0 启动时再决定，不是本次 IA 重构的拦路问题。

`/use/feedback.md`

必须包含：完整提问原文 / 完整回答（含 cite JSON）/ 提问时间精确到分钟
不要只贴 "答错了"——cite 是定位 root cause 的全部
投递通道：直接在 stock-research_Agent 微信群 @Liang。Liang 会评估后把可复盘的归档到 GitHub issue（运营 SOP 见 plan 阶段）。

5. `/status/` 现状页（A 受众主入口）

核心约束：这页是唯一说"现在到底什么状态"的权威源头。其他页面（包括 spec 头部 banner）可以局部标注，但口径冲突时以这页为准。

5.1 页面结构（单页 5 段）

段 1: 一句话现状（callout）

每次有里程碑就改这一行（按 PR 合并状态选用）：

[PR #13 未合]  v0.1.1 已发布 · P1.0 backend 实施完毕（PR #13 待合）· 站点 dev.fsagent.cc 可用
[PR #13 已合]  v0.1.1 已发布 · P1.0 backend 已合主线 · 待 Vultr 部署 · 站点 dev.fsagent.cc 可用

段 2: Now（正在做）

只列真的有人在动手或下一步立刻动手的事。当前为空 / 一项。绝不把"骨架就绪"也写到 Now——那是 Done。

段 3: Done（按里程碑倒序）

每条 5-8 行：日期（git tag 或 PR 合并日，不是 spec 撰写日）+ 货物清单（具体到包名 / 路径 / PR 号）+ 引用 spec/plan。

要包含的里程碑（按 IA 重构 PR 合并时点的真实状态填入）：

2026-05-08 — 站点 IA 重构（PR #?）— 即本 spec 的实施
2026-05-08 — P1.0 backend Tasks 7-10：FastAPI + DuckDB cache + bearer auth + issue-token CLI（commit bd7b6d7，PR #13）
- 实施依据：docs/planning/plans/2026-05-07-v0.1.1-hotfix.md Phase 2 Tasks 7-10 + superpowers/plans/phase1 Tasks 1-4
- 95/95 tests green；Tasks 11-12（Vultr deploy + profile 迁移）仍 pending
- 状态写法：PR #13 合并前写 ⏳ 实施完毕，PR #13 待合；合并后改 ✅ 已合主线
2026-05-07 — 部署骨架 + 文档站上线（PR #10/#11/#12）
2026-05-07 — Hermes 对齐重构（PR #9）
2026-05-07 — v0.1.1 价格新鲜度 hotfix（commits 084843b/2d7e5ce）— ⚠️ git tag v0.1.1 尚未 push（plan 阶段一并 push）
2026-05-07 — v0.1.0 — 03 Agent 框架 MVP（commit 179008e）
2026-04-27/28 — Spec & Planning 基线

段 4: Next（按 spec 来源链接，不复述细节）

v0.2.0 — P1.0 MVP Backend
- Tasks 7-10（FastAPI / DuckDB cache / bearer auth / issue-token CLI）：✅ 实施完毕在 feat/p1.0-backend-skeleton，PR #13 OPEN
- Task 11（Vultr deploy via cloudflared api.fsagent.cc）：⏳ 待操作（依赖 PR #13 合主线 → GHCR image build → ssh VPS 跑 deploy/install.sh）
- Task 12（stock-research_Agent profile 迁移到 Service 模式）：⏳ 待操作（依赖 Task 11 + 颁发 user bearer + 改 profile .env）
- 实施依据：superpowers/plans/phase1 Tasks 1-4 + 2026-05-07-v0.1.1-hotfix Phase 2
v0.3.0 — P1.1 Onboarding + Payment ⏳ 计划
- ⚠️ 付费部分（landing 页、WeChat Pay）实施时迁到独立对外站点；本站点呈现仅限 provisioner / profile 克隆 / Postgres schema 等技术部分
v0.4.0 — P1.2 多源数据 ⏳ 计划
v0.5.0 — P1.3 Web Search Proxy ⏳ 计划（注意 P2-C SearXNG 替换）

段 5: Later / Phase 2

3 个 initiative 各一段话 + 链 phase2 spec：

Initiative C — Token Gateway（建议先做）
Initiative A — 数据仓库
Initiative B — Profile Manager

5.2 维护约定

谁更新：操作者（Liang）。
何时更新：每个 PR 合并时改 Done；启动新阶段时改 Now/Next。
被取代的旧约定：
- roadmap.md 删除。
- planning/index.md 表格的 Status 列删除。
- 各 spec 文件头部 banner 保留（spec 局部状态注解）。

6. `/about/` 子树（项目摘要）

6.1 文件清单

路径	内容
`/about/index.md`	是什么 / 不是什么 / 谁在用 / 路线大图

合并自：overview/what-is-it.md + overview/why.md + 精简版 roadmap.md 头部段落。

6.2 内容骨架

是什么 — 一句话定位 + 5 行核心特性
不是什么 — 不下单 / 不高频 / 不做无 cite 的判断 / 不对外（暂时）
谁在用 — 团队内部投研同事 + 操作者
路线大图 — 一段话指向 /status/ 拿细节
为什么这样设计（合并自 why.md）— 为什么强制 cite / 为什么单 Agent + Verifier / 为什么先做 A 股

7. 现有页面归位表（删 / 改名 / 合并 / 留路径）

7.1 一级 nav 变化

当前	新位置	操作
`概览` `/overview/what-is-it`	`/about/`	合并
`架构` `/architecture/`	`/architecture/`	保留
`规划` `/planning/`	`/planning/`	保留，nav 后撤一档
`开发者` `/developer/`	—	删除（空壳）
—	`/use/`	新增（nav 第 1）
—	`/status/`	新增（nav 第 2）

7.2 `/overview/` 三页处理

旧文件	新位置	操作
`overview/what-is-it.md`	`/about/index.md`	合并 + 重写
`overview/why.md`	`/about/index.md` 后半段	并入
`overview/roadmap.md`	拆 → `/status/` + `/about/`	删除

留 redirect：/overview/what-is-it、/overview/roadmap 加 frontmatter <meta http-equiv="refresh"> 跳新地址（VitePress 兼容）。/overview/why 因无外部链接，可直接删（404 容忍）。

7.3 `/planning/` 子树

条目 + 内容保留，仅以下调整：

文件	操作
`planning/index.md`	删 Status 列（指向 `/status/`），保留索引功能 + 推荐阅读顺序
`planning/00 ~ 09-*.md`	全部保留，文件头部 banner 不变
`planning/superpowers/specs/phase1.md`	在 P1.1 pricing 段落上方加 `📤 已迁出本站点` callout
`planning/superpowers/specs+plans/*`	其余保留
`planning/plans/2026-05-07-deploy-pattern.md`	保留
`planning/plans/2026-05-07-hermes-restructure.md`	保留（status 已 Implemented）
`planning/plans/2026-05-07-v0.1.1-hotfix.md`	保留；Phase 2 改成 "⏳ 未开工，已被 phase1 plan 取代"（避免双源）
`planning/plans/2026-04-30-p1-service.md`	保留（已 Superseded）
`planning/plans/archive/*`	保留

7.4 仓库根 `MASTER_PLAN.md`

操作：git mv MASTER_PLAN.md docs/planning/archive/2026-05-07-master-plan.md，加 Superseded by 横幅指向 /status/ 和 superpowers/。

拆解去向：

内容段	去向
Executive Summary + Part 1 当前状态	`/status/` 的 Done 段
Part 2 Phase 1 outstanding	已存在于 `superpowers/specs+plans/phase1`，不再重复
Part 3 Phase 2 三 initiative	已存在于 `superpowers/specs/phase2`，不再重复
Part 4 文档重组方案	由本 spec 取代
Part 5 执行 roadmap	`/status/` 的 Next 段

仓库根从此没有规划文档。

7.5 `docs/getting-started.md`

内容	去向
CLI 安装步骤	`/use/cli.md`
数据 token 配置	`/use/cli.md` 的 `.env` 段
其余	删除

操作：内容拆完后删除文件（无外部入站链接，安全删）。

7.6 `.vitepress/config.ts` 改动

区域	改动
`nav`	5 项重写（使用 / 状态 / 架构 / 规划 / 关于）
`sidebar` `/overview/`	删除整段
`sidebar` `/use/`	新增：6 项（index + 5 篇）
`sidebar` `/status/`	新增：单页（无子项）
`sidebar` `/about/`	新增：单页
`sidebar` `/architecture/`	保留
`sidebar` `/planning/`	保留（条目顺序略调）
`sidebar` `/developer/`	删除整段
`themeConfig.outline`	保留

8. 成功标准

文档站重构完成后：

dev.fsagent.cc/use/ 上有且仅有给投研同事看的 5 篇短文，每篇 < 300 行。
dev.fsagent.cc/status/ 单页能被任何协作者看完 5 分钟内搞清当前进度，不需要点其他链接。
站点搜索 "¥198"、"Lite tier"、"PaaS"、"pricing"等词 0 命中。
仓库根目录 ls 没有规划文档（MASTER_PLAN.md 不在）。
/overview/what-is-it、/overview/roadmap 旧 URL 仍能访问（redirect 到 /about/、/status/）。
git tag --list 显示 v0.1.1（与本 spec 同 PR push）。
操作者贴给同事的链接稳定：/use/wechat、/use/price-freshness、/status/ 这三个最常用的 URL 不再变。
v0.1.1 价格路由、served_by cite 字段在 /use/price-freshness 上有用户语义说明，不再仅作为 changelog 提及。

9. Risks

风险	缓解
删除 `MASTER_PLAN.md` 后某些工具/脚本/外部链接仍引用它	归档而非真删；Superseded 横幅指向新位置；`grep -rn "MASTER_PLAN"` 一遍清残链
`/overview/*` 旧 URL 被外部书签 / Slack 历史链接	加 `<meta http-equiv="refresh">` redirect；保留 30 天后再考虑彻底删
`/use/cli.md` 是否在 P1.0 上线时贴 deprecate 横幅	TBD-2 保留；P1.0 启动时再决定；目标读者已澄清（开发者，非投研同事），不影响本次重构
重构期间站点中断	单 PR 整体上线（不分多 PR），CF Pages 部署原子；提前 `pnpm run docs:build` 本地验证无 dead link
spec/plan banner 与 `/status/` 口径冲突	在每个 spec 文件头部 banner 旁加一行"完整状态见 `/status/`"
WeChat 反馈渠道集中在 Liang 一人 → 单点失败	已确认 2026-05-08：用 stock-research_Agent 群 + 手动归档 GitHub issue；plan 阶段补"反馈→issue"运营 SOP；如反馈量超过每周 5 条再考虑独立频道
IA 重构 PR 与 PR #13（P1.0 backend）合并顺序	推荐先合 PR #13 再开 IA 重构 PR — 这样 `/status/` Done 段可直接写 `✅ 已合主线`，不必双状态切换；若顺序颠倒，按 §5.1 段 1 + 段 3 的"PR #13 未合 / 已合"两套写法对应填入

10. TBDs

#	内容	何时解决
~~TBD-1~~	~~`/use/wechat.md` 反馈渠道~~	已解决 2026-05-08：用 `stock-research_Agent` 微信群 @Liang，Liang 手动归档 GitHub issue（不另建独立频道）
TBD-2	`/use/cli.md` 是否在 P1.0 上线时贴 deprecate 横幅	等 P1.0 启动时再决定，不是本次 IA 重构的拦路问题。目标读者已澄清为"操作者 + 接入工程师"，独立于本次决策

11. 参考

MASTER_PLAN.md（即将归档）— Part 1 / 2 / 3 提供了状态原始素材
docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase1.md — P1.0–P1.3 spec（不动）
docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase2.md — P2 三 initiative spec（不动）
skill/stock-research/references/price-freshness.md — /use/price-freshness.md 数据源
docs/.vitepress/config.ts — 主要 nav/sidebar 改动文件
docs/index.md — 首页改写
PR #13 https://github.com/LaCatFly/twilight-drive/pull/13 — P1.0 backend 实施，本 spec /status/ 段 3/段 4 引用

站点信息架构重构 — 设计 Spec ​

1. Why this work ​

1.1 现象 ​

1.2 受众优先级 ​

2. Goals / Non-goals ​

Goals ​

Non-goals ​

3. 新信息架构 ​

3.1 一级 nav（5 项） ​

3.2 首页 docs/index.md 重写 ​

4. /use/ 子树（B 受众主入口） ​

4.1 文件清单 ​

4.2 每篇正文骨架（具体到段标题） ​

/use/wechat.md ​

/use/price-freshness.md ​

/use/what-it-can-answer.md ​

/use/cli.md ​

/use/feedback.md ​

5. /status/ 现状页（A 受众主入口） ​

5.1 页面结构（单页 5 段） ​

段 1: 一句话现状（callout） ​

段 2: Now（正在做） ​

段 3: Done（按里程碑倒序） ​

段 4: Next（按 spec 来源链接，不复述细节） ​

段 5: Later / Phase 2 ​

5.2 维护约定 ​

6. /about/ 子树（项目摘要） ​

6.1 文件清单 ​

6.2 内容骨架 ​

7. 现有页面归位表（删 / 改名 / 合并 / 留路径） ​

7.1 一级 nav 变化 ​

7.2 /overview/ 三页处理 ​

7.3 /planning/ 子树 ​

7.4 仓库根 MASTER_PLAN.md ​

7.5 docs/getting-started.md ​

7.6 .vitepress/config.ts 改动 ​

8. 成功标准 ​

9. Risks ​

10. TBDs ​

11. 参考 ​