Site IA Restructure — Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Restructure dev.fsagent.cc from "by engineering layer" to "by audience path" — primary readers are research colleagues (semi-tech, mostly WeChat); secondary is the operator (Liang). Add /use/, /status/, /about/; delete /developer/; archive MASTER_PLAN.md; push the unpushed v0.1.1 git tag.

Architecture: Pure VitePress content + nav reorganization. No source code changes in core/, skill/, src/. Single PR. Each task ends with a commit; site builds cleanly between tasks (uses ignoreDeadLinks: true to tolerate transient dangling links during the multi-task transition; full dead-link sweep is the final task).

Tech Stack: VitePress 1.5.x · pnpm · Cloudflare Pages auto-deploy via GitHub Actions (already set up; no infra change needed).

Branch: docs/site-ia-restructure-spec (already created from main; spec already committed at 96fdfce). Plan tasks land additional commits on the same branch. Final PR opens this branch against main.

Reference spec: docs/planning/superpowers/specs/2026-05-08-site-ia-restructure-design.md

File map

Created:

docs/about/index.md
docs/use/index.md
docs/use/wechat.md
docs/use/price-freshness.md
docs/use/what-it-can-answer.md
docs/use/cli.md
docs/use/feedback.md
docs/status/index.md
docs/planning/archive/2026-05-07-master-plan.md (via git mv from repo root)

Modified:

docs/index.md — rewrite home (hero + features)
docs/.vitepress/config.ts — nav (5 items) + sidebar (drop overview/developer; add use/status/about)
docs/overview/what-is-it.md → frontmatter redirect to /about/
docs/overview/roadmap.md → frontmatter redirect to /status/
docs/planning/index.md — drop Status column; reword recommended reading order
docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase1.md — add 📤 已迁出本站点 callout above P1.1 pricing
docs/planning/plans/2026-05-07-v0.1.1-hotfix.md — Phase 2 banner update

Deleted:

docs/overview/why.md (content merged into /about/)
docs/developer/index.md + docs/developer/ directory
docs/getting-started.md (content moved to /use/cli.md)
MASTER_PLAN.md (via git mv, see Created above)

Operator-side (no file):

git push origin v0.1.1 — push the existing-but-unpushed tag

Task 1: Write `/about/index.md`

Files:

Create: docs/about/index.md

This page combines the old overview/what-is-it.md and overview/why.md into one page, plus a small roadmap pointer to /status/.

[ ] Step 1.1: Create file with full content

markdown

# 关于本项目

一个基于团队内部 **Hermes** 框架构建的 **A 股投研 Agent**，目前服务团队内部投研同事。

## 是什么

- **只做投研，不做下单。** 输出投研结论，不触发交易。
- **数据驱动，引用强制。** 每个数字、每个论断都必须有可追溯的来源（cite envelope）。
- **可演化、可复用。** A 股是第一个 vertical，框架本身要能复用到其他垂直领域。

## 不是什么

- ❌ 不下单、不做自动交易
- ❌ 不做实时高频策略
- ❌ 没有 cite 的"凭感觉"判断不被接受
- ❌ 暂不对外（对外付费版本将在独立站点 + 独立项目中推出）

## 谁在用

- 团队内部投研同事（v0.1.x，Direct 模式或 WeChat bot）
- 操作者（Liang）作为幕后支持

具体怎么用见 [/use/](/use/)。

## 路线大图

当前能查个股价格 + 基本面（v0.1.1）。下一步是把后端服务化（P1.0），再加多源数据、Web 搜索、研报抽取等能力。完整状态见 **[/status/](/status/)**。

## 为什么这样设计

LLM 时代的投研工具有两个常见失败模式：

1. **数字编造** — 模型把 P/E、EPS 这种关键数字"凭感觉"输出，没有任何来源校验
2. **黑盒推理** — 给出一个结论，但没法回答"这个数字是从哪来的"、"这个判断的依据是什么"

对投研场景而言，这两个问题都不可接受 —— 一个错误的数字可能导致错误的决策。

本项目的回答：

- **Citation Protocol 强制每个数字带 `cite` 字段** —— 不带就被 Verifier 拒绝
- **Competence 机制让知识可溯** —— 每个领域知识都注册成 Competence，带来源
- **单 Agent + 确定性 Verifier** —— 不靠"另一个 LLM 检查"，靠确定性代码校验输出

### 为什么基于 Hermes

- 团队已有的内部框架，Skills + Competences 抽象天然适合本场景
- Competence 概念让 citation 自然落地（Competence = 知识 + 来源）
- 团队上手成本低

详见 [ADR-0001: Hermes 作为运行时](/architecture/adr/0001-hermes-runtime)。

### 为什么先做 A 股

- 市场清晰、数据规范（CSRC 监管框架、Tushare 等高质量源）
- 团队对域有积累
- 复杂度可控，适合作为 Harness 框架的第一个 instance

详见 [04 — Harness 框架](/planning/04-harness-framework)。

[ ] Step 1.2: Commit

bash

git add docs/about/index.md
git commit -m "docs: add /about/ — merged overview/what-is-it + why"

Task 2: Write `/use/` subtree (6 files)

Files:

Create: docs/use/index.md
Create: docs/use/wechat.md
Create: docs/use/price-freshness.md
Create: docs/use/what-it-can-answer.md
Create: docs/use/cli.md
Create: docs/use/feedback.md

The 6 pages collectively form the B-audience entry. The index.md shows 3 cards (wechat / price-freshness / what-it-can-answer) — the primary investor-colleague trio. CLI and feedback are accessible via sidebar / anchor link, not hero card.

[ ] Step 2.1: Create docs/use/index.md

markdown

---
title: 怎么用
---

# 怎么用

团队内部 A 股投研助手 —— 多数同事在 WeChat 群里向 `stock-research_Agent` 提问，少数同事走命令行直接调脚本。

<div class="vp-doc">

## 给投研同事看的

- **[在 WeChat 里使用 →](/use/wechat)** 加入 bot 群、提问、读懂带 cite 的回答
- **[价格新鲜度语义 →](/use/price-freshness)** "当前价" vs "最近收盘" 何时是哪个
- **[现在能查什么 →](/use/what-it-can-answer)** v0.1.1 真实能力清单 + 不能查什么

## 给操作者 / 接入工程师

- **[命令行用法（开发者）→](/use/cli)** `fetch_price.py` / `fetch_fundamentals.py` 直接调用

## 反馈

bot 答错或答不上时怎么把信息给到我，见 **[反馈通道](/use/feedback)**。
</div>

[ ] Step 2.2: Create docs/use/wechat.md

markdown

# 在 WeChat 里使用

> 给投研同事的 5 分钟上手 —— 你刚被拉进 `stock-research_Agent` 群，怎么快速提问、怎么读回答、答错了怎么反馈。

## 1. 添加 bot

由 Liang 把你拉进 `stock-research_Agent` WeChat 群。**不需要自己 add bot**，群里 bot 已经常驻。

## 2. 提问怎么写

| ✅ 好例子 | ❌ 坏例子 | 为什么 |
|---|---|---|
| 查 600519 当前价 | 茅台怎么样 | 太宽泛，没有具体数据点；Verifier 会拒 |
| 600519 和 000858 谁 P/E 低 | 哪只酒类股票值得买 | "值得买"含主观判断；本 bot 只给数据 |
| 600519 在 2026-04-27 收盘 | 茅台之前涨了多少 | 没有具体日期，bot 会反问 |

**通用模板**：`查 <股票代码> <具体数据点> <可选时间>`。

## 3. 读懂回答

bot 回答里每个数字后面都有一个 `cite` 字段（小字 / 灰色块）。它的核心 5 个字段：

| 字段 | 含义 | 例子 |
|---|---|---|
| `value` | 实际数字 | `1801.23` |
| `metric` | 数字代表什么 | `current_price` / `close` / `pe_ttm` |
| `cite.served_by` | 数据从哪个源来的 | `akshare`（盘中实时）/ `tushare`（盘后/历史） |
| `cite.as_of` | 数据对应哪一天 | `2026-05-08` |
| `cite.tool_call_id` | 这次查询的唯一 ID | `tc_71387d9cc564`（用于反馈定位） |

**怎么用**：看到数字时，先看 `served_by` 决定它是不是实时；再看 `as_of` 决定时点；如果你怀疑数字不对，把整个回答（含 cite）截图发到群里 @Liang，附上 `tool_call_id`。

详细 cite envelope 字段见 [`/architecture/citation-protocol`](/architecture/citation-protocol)。

## 4. 常见状况

### "为什么上午问的价和下午问的不一样？"

**这不是 bug，这是路由**。详见 [价格新鲜度](/use/price-freshness)。

简短版：
- 09:30–15:00 工作日 → 走 akshare 实时盘口（`metric: current_price`，`served_by: akshare`）
- 盘后 / 周末 / 节假日 → 走 Tushare daily 收盘（`metric: close`，`served_by: tushare`）

bot 会在回答里明确说"当前价"还是"最近收盘"，**不会**模糊。

### "为什么有些问题它回 '我没有这个能力'？"

bot 严格按 [现在能查什么](/use/what-it-can-answer) 里列出的 ✅ 项答。其他领域（研报、宏观、美股、行业排名等）一律回拒，不编造。

## 5. 答不上来 / 答错时

直接在群里 @Liang，并附上：

1. 你的提问原文
2. bot 的完整回答（截图，含 cite JSON 块）
3. 提问时间（精确到分钟）

详见 [反馈通道](/use/feedback)。

[ ] Step 2.3: Create docs/use/price-freshness.md

markdown

# 价格新鲜度语义

> 同一个问题"600519 现在多少钱"，上午问和晚上问 cite 不一样。这页解释为什么、怎么读、什么时候要警惕 stale。

## 路由表

| 提问场景 | `metric` | `cite.served_by` | 数据延迟 | 含义 |
|---|---|---|---|---|
| 09:30–15:00 工作日"现在价" | `current_price` | `akshare`（雪球盘口）| ~1.4 秒 | 盘中实时 spot |
| 盘后 / 周末 / 节假日"现在价" | `close` | `tushare` | T+0 收盘 | 上一交易日收盘 |
| 显式问"X 月 X 日收盘" | `close` | `tushare` | 历史 daily | 那一日的收盘价 |
| akshare 抓取失败（如 ST 标识、退市）回退 | `close` | `tushare` | T+0 收盘 | fallback；可能有 warning 日志 |

> "Market open" 由 `core.data._market.is_market_open(token)` 判定：09:30–15:00（含 11:30–13:00 午休）& 交易日。交易日来自 Tushare `trade_cal`（按日缓存）；Tushare 不可达时降级为周一到周五。

## 怎么主动问历史价

如果你想要某一具体日期的收盘价：

查 600519 在 2026-04-27 收盘


bot 会走 Tushare daily 路径，cite 显示 `served_by: tushare`、`as_of: 2026-04-27`、`metric: close`。

## 措辞约束

bot 在表述时会严格区分：

| `metric` + `served_by` | 用语 | 不会用 |
|---|---|---|
| `current_price` + `akshare` | "**当前价 ¥1801.23**（akshare 实时，2026-05-08 10:30）" | "今日收盘"——盘还没收 |
| `close` + `tushare`（无显式日期）| "**最近收盘 ¥1371.05**（Tushare daily，2026-05-07）" | "当前价"——可能差一个周末 |
| `close` + `tushare`（指定日期）| "**¥1718.50（2026-04-27 收盘）**" | "目前 ¥1718.50" |

**核心约束**：`close` 在交易时段读到的是**前一交易日**的收盘，永远不是今天的。把它当作"现在"是 v0.1.1 修复掉的 bug，不会再让它从行文里漏出来。

## 什么时候要警惕 stale

- akshare 镜像延迟通常 5-15 分钟（小概率）。`cite.fetched_at` 字段是抓取的实际 UTC 时间戳；如果它比你提问时早 > 15 分钟，建议再问一次。
- Tushare daily 在每个交易日 17:00 之后才会有当日数据。盘后立刻问可能仍返回前一日。

## 完整 trace 示例

详见 [架构 / 完整 trace 示例](/architecture/example-trace)。

[ ] Step 2.4: Create docs/use/what-it-can-answer.md

markdown

# 现在能查什么 / 不能查什么

> 当前能力清单（v0.1.1）。⏳ 计划中的注明预期版本，链 [/status/](/status/) 拿细节。

## ✅ 现在能答（v0.1.1）

- **个股价格**
  - 当前价（盘中走 akshare 实时；盘后走 Tushare daily 收盘）
  - 历史收盘（任意交易日）
- **个股基本面**（来自 Tushare `fina_indicator`）
  - P/E (TTM)
  - P/B
  - ROE
  - 毛利率
  - 净利率
  - 资产负债率
- **简单组合查询**（如 `600519 和 000858 谁 P/E 低`）

每个数字都带 cite envelope，详见 [WeChat 使用](/use/wechat#_3-读懂回答)。

## ⏳ 计划中（标注预期版本）

| 能力 | 版本 | 数据源 |
|---|---|---|
| 卖方研报抽取 | P2 | 待研究 |
| 一致预期跟踪 | P1.2 | Tushare + 第三方 |
| 行业 peer 比较 | P1.2 | Tushare 行业分类 |
| 宏观（CPI / PMI / 利率）| P1.2 | akshare |
| 美股 / ADR / 汇率 | P1.2 | Yahoo Finance |
| Web 搜索（新闻、公告检索）| P1.3 → P2-C | DashScope → SearXNG |

完整阶段计划见 [/status/](/status/)。

## ❌ 永远不会做

- **下单 / 自动交易** —— 设计上禁止，与"只做投研"的核心定位冲突
- **实时高频策略** —— 不是 latency-critical 系统的合适抽象
- **没有 cite 的"凭感觉"判断** —— Verifier 会拒；本 bot 不输出未引用的论断

## 答错时

如果你确认 bot 输出的数字不对（比 Wind / 通达信 / 雪球 实测差超过 0.01%），按 [反馈通道](/use/feedback) 提交。这种情况通常是数据源 stale 或路由 bug，需要 root cause 复盘。

[ ] Step 2.5: Create docs/use/cli.md

markdown

# 命令行用法（开发者）

> **目标读者**：操作者 + 接入工程师 + CI 测试。**不是** WeChat 投研同事。如果你是投研同事，请直接看 [WeChat 使用](/use/wechat)。

## 安装

```bash
git clone https://github.com/LaCatFly/twilight-drive.git
cd twilight-drive
bash install.sh

install.sh 会：

创建 Python 3.11+ venv
pip install -e ./core（核心包）
在 ~/.hermes/profiles/stock-research-agent/skills/research/stock-research/ 安装 skill scripts

配置

复制 .env.example 到 .env（profile 模板里有 profile/template-stock-research-pro/.env.example），填：

bash

TUSHARE_TOKEN=<your-tushare-pro-token>
# AKSHARE_ENABLE 默认 1，无需显式配置

P1.0 backend 上线后（见 /status/），改成：

bash

TWILIGHT_SERVICE_URL=https://api.fsagent.cc
TWILIGHT_API_TOKEN=<your-bearer-token-from-issue-token-cli>
# TUSHARE_TOKEN 删除（中心化在 backend）

跑

当前价 / 最近收盘

bash

./skill/stock-research/scripts/fetch_price.py 600519

输出：

json

{
  "value": 1371.05,
  "metric": "close",
  "code": "600519.SH",
  "as_of": "2026-05-07",
  "cite": {
    "kind": "tool",
    "source": "tushare",
    "table": "daily",
    "fetched_at": "2026-05-07T13:42:31.168+00:00",
    "tool_call_id": "tc_fed71513e34b",
    "served_by": "tushare"
  }
}

指定历史日期

bash

./skill/stock-research/scripts/fetch_price.py 600519 --trade-date 20260427

基本面

bash

./skill/stock-research/scripts/fetch_fundamentals.py 600519 --period 20240331

返回 P/E / P/B / ROE / 毛利率 / 净利率 / 资产负债率，每项带 cite。

退出码

Code	含义
0	成功
1	上游无数据（akshare + tushare 都返回空）
2	Tushare token 被拒（HTTP 401-ish）

更多 envelope 形态见 skill/stock-research/references/tool-usage.md。

升级到 Service 模式

P1.0 backend 上线后（/status/ 跟踪进度），不需要改命令；只改 .env：

diff

- TUSHARE_TOKEN=<...>
+ TWILIGHT_SERVICE_URL=https://api.fsagent.cc
+ TWILIGHT_API_TOKEN=<bearer-from-scripts/issue-token.py>

_client.py 自动检测两种 mode 并切换；输出 envelope 形状一致。


- [ ] **Step 2.6: Create `docs/use/feedback.md`**

```markdown
# 反馈通道

> bot 答错、答不上、或你怀疑数字不对时，怎么把信息给到 Liang。

## 投递通道

直接在 `stock-research_Agent` 微信群里 @Liang。Liang 会评估后把可复盘的归档到 GitHub issue（运营 SOP 在 plan 阶段补）。

不另建独立 Slack/飞书频道 —— 反馈量增长到每周 5+ 条再考虑。

## 反馈必须包含

1. **完整提问原文**（直接复制粘贴你打的字）
2. **bot 的完整回答**（截图，**包含 cite JSON 块**）
3. **提问时间**（精确到分钟，如 `2026-05-08 10:42`）

可选但强烈推荐：
- 你期望的正确答案 + 你认为的来源（如"按 Wind 实测应为 1372.50"）
- `cite.tool_call_id`（截图里有）—— 用于 backend log 定位

## 不要

- ❌ 只贴一行 "它答错了" —— cite 是定位 root cause 的全部
- ❌ 只贴问题不贴回答（不带 cite 的回答 = 没有 root cause 入口）
- ❌ 把多个不相关的反馈合并成一条 —— 一次一个 case，方便归档

## 我会做什么

收到反馈后：

1. 30 分钟内 ack（"收到，看一下"）
2. 24 小时内给出 root cause 初判（数据源 stale / 路由 bug / 上游异常 / 其他）
3. 如果是可修复的 bug，开 GitHub issue + 你截图，issue 关闭时通知你
4. 如果是已知 limitation（如 P1.2 才上线的能力），告知预期版本

## 紧急情况

如果 bot 输出的数字会被立刻用于交易决策，**先去 Wind / 通达信 / 雪球 复核**，不要等我回复。本 bot 是辅助工具，不是 sole source of truth。

[ ] Step 2.7: Verify VitePress builds

bash

cd /Users/syone/twilight-drive
pnpm --silent run docs:build 2>&1 | tail -20

Expected: build complete in <X>s. No fatal errors. Dead-link warnings to /status/ and /use/wechat#anchor are tolerated (ignoreDeadLinks: true); they'll resolve as Tasks 3-5 land.

[ ] Step 2.8: Commit

bash

git add docs/use/
git commit -m "docs: add /use/ subtree (6 pages: index + 5 user-facing docs)"

Task 3: Write `/status/index.md`

Files:

Create: docs/status/index.md

The single-page source-of-truth for "what's done / Now / Next / Later". Verify each milestone date and PR number against git log before committing.

[ ] Step 3.1: Verify the truth before writing

bash

git log --oneline --all -20
gh pr view 13 --json state,number,title  # confirm PR #13 status
git tag --list 'v*'                       # confirm v0.1.1 not pushed (output empty if not)
git ls-remote --tags origin 'v0.1.1'      # remote-side check

Capture:

PR #13 state (OPEN / MERGED / CLOSED)
Whether v0.1.1 exists locally and on origin

Use these to choose the correct callout phrasing in step 3.2.

[ ] Step 3.2: Create docs/status/index.md

markdown

---
title: 项目状态
---

# 项目状态

> **唯一权威页面。** 其他页面（包括 spec 头部 banner）的状态注解仅供局部参考；与本页冲突时**以本页为准**。

::: info 当前一句话状态
v0.1.1 已发布 · P1.0 backend 实施完毕（PR #13 OPEN，待合）· Vultr 部署 + profile 迁移待操作 · 站点 dev.fsagent.cc 可用
:::

> ⚠️ 本 callout 在 PR #13 合主线后改为：
> "v0.1.1 已发布 · P1.0 backend 已合主线 · 待 Vultr 部署 + profile 迁移 · 站点 dev.fsagent.cc 可用"

## Now（正在做）

- 站点 IA 重构（本 PR 在合并中）

合并后此格变空 / 替换为下一项启动事项。**绝不**把"骨架就绪"写到 Now —— 那是 Done。

## Done（按里程碑倒序）

### 2026-05-08 — 站点 IA 重构（PR #?）

- 文档站按受众重组：新增 `/use/`（6 页）、`/status/`、`/about/`；删除 `/developer/`、`docs/getting-started.md`、`docs/overview/why.md`
- `MASTER_PLAN.md` 归档到 `docs/planning/archive/2026-05-07-master-plan.md`
- v0.1.1 git tag push（之前 plan Step 6.5 待勾，本次一并完成）
- spec：`docs/planning/superpowers/specs/2026-05-08-site-ia-restructure-design.md`

### 2026-05-08 — P1.0 backend Tasks 7-10（PR #13）

> ⚠️ 本条状态说明：PR #13 合主线之前写"⏳ 实施完毕，PR #13 待合"；合并后改"✅ 已合主线"。

- `src/service/{main,config,auth}.py` —— FastAPI scaffold + Pydantic Settings + SHA256 bearer 中间件 over SQLite
- `src/service/cache.py` —— DuckDB DailyCache (24h TTL) + FundamentalsCache (30d TTL)
- `src/service/routes/{price,fundamentals}.py` —— bearer-authed 路由；akshare 实时路径 bypass cache（保 v0.1.1 freshness 语义）
- `scripts/issue-token.py` —— admin CLI (`issue` / `revoke` / `list`)，明文 token 仅打印一次
- 35 new integration tests across 5 files; 95/95 green; ruff + format + ty 全清
- 实施依据：`docs/planning/plans/2026-05-07-v0.1.1-hotfix.md` Phase 2 Tasks 7-10 + `superpowers/plans/phase1` Tasks 1-4
- Tasks 11-12（Vultr deploy + profile 迁移）操作者侧待办，见 Next 段

### 2026-05-07 — 部署骨架 + 文档站上线（PR #10, #11, #12）

- `deploy/`：Dockerfile、compose.yml、cloudflared 模板、`twilight-{backend,cloudflared}.service` × 2、install.sh、env.example
- 文档站切到 `dev.fsagent.cc`，GitHub Actions 自动部署到 Cloudflare Pages
- 实施依据：`docs/planning/plans/2026-05-07-deploy-pattern.md` Tasks 1-6

### 2026-05-07 — Hermes 对齐重构（PR #9）

- `skill/stock-research/SKILL.md` 迁移到 frontmatter 元数据 + `references/` 拆分
- `profile/template-stock-research-pro/` 4-file 完整模板（AGENTS.md、SOUL.md、config.yaml.template、.env.example、secrets.schema.json）
- `install-skill.sh` 从 `.env.example` 注入 keys
- 实施依据：`docs/planning/plans/2026-05-07-hermes-restructure.md`

### 2026-05-07 — v0.1.1 价格新鲜度 hotfix（commits `084843b`, `2d7e5ce`）

- akshare Xueqiu 单 code 端点（~1.4s，替换原 `stock_zh_a_spot_em` 75s 全表抓取）
- `core/core/data/_market.is_market_open()` + Tushare `trade_cal` 缓存
- `get_price` 自动路由：盘中走 akshare 实时 / 盘后走 Tushare daily
- cite envelope 新增 `served_by` 字段（向后兼容，可选）
- 实施依据：`docs/planning/plans/2026-05-07-v0.1.1-hotfix.md` Phase 1

### 2026-05-07 — v0.1.0 — 03 Agent 框架 MVP（commit `179008e`）

- `twilight-drive-core` 0.1.0 包发布：citation protocol、Verifier、Competence registry、model router、single-agent runtime
- Tushare adapter（`get_price`、`get_fundamentals`）
- `skill/stock-research`：3 个 fetch scripts（含 stub `search_reports.py`）+ dual-mode `_client.py`
- CI：ruff + pytest；release workflow

### 2026-04-27 / 28 — Spec & Planning 基线

- 5 份层级规划（`planning/01-05-*.md`）
- 03 Agent 框架 design spec
- VitePress 文档站初版

## Next（下一阶段计划）

按 spec 来源链接，**不在此处复述细节**。

### v0.2.0 — P1.0 MVP Backend

- **Tasks 7-10**（FastAPI / DuckDB cache / bearer auth / issue-token CLI）✅ 完成于 PR #13（待合主线）
- **Task 11** — Vultr deploy（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 (`scripts/issue-token.py issue`) + 改 profile `.env`
- 实施依据：[`superpowers/plans/phase1`](/planning/superpowers/plans/2026-05-07-twilight-drive-phase1) Tasks 1-4 + [`v0.1.1-hotfix Phase 2`](/planning/plans/2026-05-07-v0.1.1-hotfix)

### v0.3.0 — P1.1 Onboarding + Payment ⏳ 计划

> ⚠️ 付费部分（landing 页、WeChat Pay）实施时迁到独立对外站点；本站呈现仅限 provisioner 服务、profile 克隆、Postgres schema 等技术部分。

详见 [`superpowers/specs/phase1`](/planning/superpowers/specs/2026-05-07-twilight-drive-phase1) §P1.1。

### v0.4.0 — P1.2 多源数据 ⏳ 计划

pytdx3 历史 / akshare 宏观 / Yahoo 美股 / 跨源比对（`served_by` 拓展为多源数组）。

### v0.5.0 — P1.3 Web Search Proxy ⏳ 计划

DashScope 默认 + Google CSE fallback。⚠️ 注意 P2-C SearXNG 自托管会替换这套。

## Later / Phase 2

3 个 initiative 互相独立。每个的技术方案见 [`superpowers/specs/phase2`](/planning/superpowers/specs/2026-05-07-twilight-drive-phase2)。

- **Initiative C — Token Gateway**（建议先做）—— New-API key pool + SearXNG 自托管搜索；解决 SiliconFlow 429 + DashScope 1000/天上限
- **Initiative A — 数据仓库** —— 4 层 DuckDB 模型 + APScheduler batch 入仓 + 跨源质量检查
- **Initiative B — Profile Manager** —— git-backed profile 注册中心 + CLI（claim / push / pull / sync / template）+ 多主机同步

## 维护约定

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

[ ] Step 3.3: Verify build + commit

bash

pnpm --silent run docs:build 2>&1 | tail -10
git add docs/status/
git commit -m "docs: add /status/ — single source of truth for project state"

Task 4: Rewrite `docs/index.md` (home page)

Files:

Modify: docs/index.md
[ ] Step 4.1: Replace file content

markdown

---
layout: home

hero:
  name: A 股投研 Agent
  text: 团队内部 A 股投研助手
  tagline: 数据可信 · 引用可溯 · 推理可审计 · 不下单只投研
  actions:
    - theme: brand
      text: 开始用
      link: /use/
    - theme: alt
      text: 项目状态
      link: /status/
    - theme: alt
      text: 这是什么
      link: /about/

features:
  - title: 回答带 cite
    details: 每个数字、每个论断都附 tool_call_id / source / as_of / served_by。Verifier 自动校验：未引用即拒绝。
  - title: 价格自动路由
    details: 盘中走 akshare 实时盘口（~1.4s），盘后走 Tushare daily。cite 里的 served_by 字段透明显示数据来自哪个源。
  - title: 不下单只投研
    details: 输出投研结论，不触发交易。没有 cite 的"凭感觉"判断不被接受。
  - title: 内部团队工具
    details: A 股是第一个 vertical，目前服务团队投研同事。对外付费版本将在独立站点 + 独立项目中推出。
---

[ ] Step 4.2: Verify forbidden terms absent

bash

grep -nE "Hermes 框架可复用|Phase 2 三 initiative|¥198|Lite tier|pricing|PaaS" docs/index.md

Expected: empty output (zero matches).

[ ] Step 4.3: Verify build + commit

bash

pnpm --silent run docs:build 2>&1 | tail -10
git add docs/index.md
git commit -m "docs: rewrite home for internal-team tone, drop external messaging"

Task 5: Update `.vitepress/config.ts` (nav + sidebar)

Files:

Modify: docs/.vitepress/config.ts
[ ] Step 5.1: Replace nav array

Edit docs/.vitepress/config.ts. Find:

typescript

    nav: [
      { text: "概览", link: "/overview/what-is-it" },
      { text: "架构", link: "/architecture/" },
      { text: "规划", link: "/planning/" },
      { text: "开发者", link: "/developer/" },
    ],

Replace with:

typescript

    nav: [
      { text: "使用", link: "/use/" },
      { text: "状态", link: "/status/" },
      { text: "架构", link: "/architecture/" },
      { text: "规划", link: "/planning/" },
      { text: "关于", link: "/about/" },
    ],

[ ] Step 5.2: Replace sidebar — drop /overview/ and /developer/, add /use/, /status/, /about/

Find:

typescript

      "/overview/": [
        {
          text: "概览",
          items: [
            { text: "这是什么", link: "/overview/what-is-it" },
            { text: "为什么做", link: "/overview/why" },
            { text: "路线图", link: "/overview/roadmap" },
          ],
        },
      ],

Delete this entire block.

Find:

typescript

      "/developer/": [
        {
          text: "开发者指南",
          items: [
            { text: "总览", link: "/developer/" },
          ],
        },
      ],

Delete this entire block.

In the same sidebar: object, add (above /architecture/):

typescript

      "/use/": [
        {
          text: "怎么用",
          items: [
            { text: "总览", link: "/use/" },
            { text: "WeChat 使用", link: "/use/wechat" },
            { text: "价格新鲜度语义", link: "/use/price-freshness" },
            { text: "现在能查什么", link: "/use/what-it-can-answer" },
            { text: "命令行（开发者）", link: "/use/cli" },
            { text: "反馈通道", link: "/use/feedback" },
          ],
        },
      ],
      "/status/": [
        {
          text: "项目状态",
          items: [{ text: "Now / Done / Next / Later", link: "/status/" }],
        },
      ],
      "/about/": [
        {
          text: "关于",
          items: [{ text: "项目摘要", link: "/about/" }],
        },
      ],

[ ] Step 5.3: Verify the file parses + builds

bash

pnpm --silent run docs:build 2>&1 | tail -15

Expected: build succeeds; no TypeScript / config syntax errors.

[ ] Step 5.4: Spot-check live nav by previewing

bash

pnpm --silent run docs:preview &
sleep 2
curl -s http://localhost:4173/ | grep -oE '/(use|status|architecture|planning|about)/' | sort -u
pkill -f 'vitepress preview' 2>/dev/null || true

Expected: 5 lines /use/ /status/ /architecture/ /planning/ /about/.

[ ] Step 5.5: Commit

bash

git add docs/.vitepress/config.ts
git commit -m "docs: rewire VitePress nav (5 items) + sidebar for /use,/status,/about"

Task 6: Add redirects on `/overview/what-is-it.md` and `/overview/roadmap.md`

Files:

Modify: docs/overview/what-is-it.md
Modify: docs/overview/roadmap.md

VitePress doesn't have built-in redirect support, but the standard pattern is <meta http-equiv="refresh"> in markdown frontmatter head directive.

[ ] Step 6.1: Replace docs/overview/what-is-it.md content

markdown

---
title: 这是什么 — 已迁移至 /about/
head:
  - - meta
    - http-equiv: refresh
      content: 0; url=/about/
---

# 已迁移

本页内容已合并到 [/about/](/about/)。3 秒后自动跳转 —— 若未跳转，[点这里](/about/)。

[ ] Step 6.2: Replace docs/overview/roadmap.md content

markdown

---
title: 路线图 — 已迁移至 /status/
head:
  - - meta
    - http-equiv: refresh
      content: 0; url=/status/
---

# 已迁移

本页内容已重构进 [/status/](/status/)（Now / Done / Next / Later 单页）。3 秒后自动跳转 —— 若未跳转，[点这里](/status/)。

[ ] Step 6.3: Verify redirect HTML present in build output

bash

pnpm --silent run docs:build 2>&1 | tail -5
grep -lE 'http-equiv="refresh"' docs/.vitepress/dist/overview/*.html

Expected: both what-is-it.html and roadmap.html listed.

[ ] Step 6.4: Commit

bash

git add docs/overview/what-is-it.md docs/overview/roadmap.md
git commit -m "docs: redirect /overview/{what-is-it,roadmap} to /about/ /status/"

Task 7: Delete `/overview/why.md`, `/developer/`, `docs/getting-started.md`

Files:

Delete: docs/overview/why.md
Delete: docs/developer/index.md
Delete: docs/developer/ (directory)
Delete: docs/getting-started.md

/overview/why.md content already merged into /about/index.md in Task 1. /developer/index.md is a stub. docs/getting-started.md content already moved to /use/cli.md in Task 2.

[ ] Step 7.1: Verify no inbound links to these pages from non-archive content

bash

grep -rn "/overview/why\|/developer/\|/getting-started" docs/ \
  --exclude-dir=archive --exclude-dir=dist 2>&1 | grep -v ".vitepress/dist"

Expected: empty (no inbound links remain). If any line appears, fix the source page first before continuing.

[ ] Step 7.2: Delete the files

bash

rm docs/overview/why.md
rm -r docs/developer
rm docs/getting-started.md

[ ] Step 7.3: Verify build still clean

bash

pnpm --silent run docs:build 2>&1 | tail -10

Expected: build succeeds (ignoreDeadLinks: true covers any residual external links to deleted paths).

[ ] Step 7.4: Commit

bash

git add -A docs/overview docs/developer docs/getting-started.md
git status --short
git commit -m "docs: remove /overview/why, /developer/, getting-started.md"

Task 8: Update `docs/planning/index.md` — drop Status column

Files:

Modify: docs/planning/index.md

The Status column is being deprecated in favor of /status/. The recommended-reading order also needs to drop the dangling MASTER_PLAN.md reference.

[ ] Step 8.1: Read current file

bash

cat docs/planning/index.md

[ ] Step 8.2: Apply these edits to docs/planning/index.md

Find the heading and lead paragraph. Replace the lead so it links to /status/ for state:

Old:

markdown

This directory contains the project's planning corpus, organized in two complementary axes:

- **层级维度 (01–05)**：按架构层切分的设计文档，长青（status 横幅标注当前实现）
- **阶段维度 (`superpowers/`)**：按产品阶段（P1 / P2）切分的可执行 spec + plan
- **dated plans (`plans/`)**：当前周期的 hotfix / sprint 任务清单
- **archive (`plans/archive/`)**：已 implemented 的历史 plan，保留作为参考

New:

markdown

This directory contains the project's planning corpus, organized in two complementary axes:

- **层级维度 (01–09)**：按架构层切分的设计文档，长青；每个 spec 头部 banner 是局部注解
- **阶段维度 (`superpowers/`)**：按产品阶段（P1 / P2）切分的可执行 spec + plan
- **dated plans (`plans/`)**：当前周期的 hotfix / sprint 任务清单
- **archive (`plans/archive/`)**：已 implemented 的历史 plan，保留作为参考

> **当前实施状态见 [/status/](/status/)。** 本页表格是结构索引，不是状态权威。

Find the 层级维度文档 table:

Old:

markdown

| # | File | Scope | Status |
|---|------|-------|--------|
| 00 | [multi-tenancy](./00-multi-tenancy.md) | 锁 / 权限 / 多 profile 单机调度 / 三层模型 | 📐 Architecture baseline |
| 01 | [data-layer](./01-data-layer.md) | 价格 + 基本面 + 数据质量 + 估值 | 🔶 Tushare/akshare 已发；多源待 P1.2 |
| 02 | [research-reports](./02-research-reports.md) | 研报来源、PDF 解析、入库 | ❌ Deferred to P2 |
| 03 | [agent-framework](./03-agent-framework.md) | Hermes / MCP / Skills 5 层架构 | ✅ v0.1.0 已发 |
| 04 | [harness-framework](./04-harness-framework.md) | 跨垂直可复用脚手架 | ❌ 推迟到 v1.0+ |
| 05 | [documentation](./05-documentation.md) | VitePress + 文档结构 | 🔶 站点已发；产品文档重组待 |
| 06 | [v0.1.1-hotfix-and-p1](./06-v0.1.1-hotfix-and-p1.md) | get_price 修复 + P1.0 起步边界 | ✅ v0.1.1 shipped；⏳ P1.0 待 |
| 07 | [aigc-monetization](./07-aigc-monetization.md) | Tier 3 输出形态、unit economics、定价 | 📐 Product baseline |
| 08 | [hermes-aligned-structure](./08-hermes-aligned-structure.md) | Hermes 官方约定对齐 / 单源部署 / 参考文档结构 | ✅ Implemented in v0.1.x (skill + profile template) |
| 09 | [deployment-pattern](./09-deployment-pattern.md) | Vultr Japan + cloudflared tunnel + Docker 隔离 / Risk register | 📐 Architecture proposal · deploy/ skeleton landed |

New (Status column dropped):

markdown

| # | File | Scope |
|---|------|-------|
| 00 | [multi-tenancy](./00-multi-tenancy.md) | 锁 / 权限 / 多 profile 单机调度 / 三层模型 |
| 01 | [data-layer](./01-data-layer.md) | 价格 + 基本面 + 数据质量 + 估值 |
| 02 | [research-reports](./02-research-reports.md) | 研报来源、PDF 解析、入库 |
| 03 | [agent-framework](./03-agent-framework.md) | Hermes / MCP / Skills 5 层架构 |
| 04 | [harness-framework](./04-harness-framework.md) | 跨垂直可复用脚手架 |
| 05 | [documentation](./05-documentation.md) | VitePress + 文档结构 |
| 06 | [v0.1.1-hotfix-and-p1](./06-v0.1.1-hotfix-and-p1.md) | get_price 修复 + P1.0 起步边界 |
| 07 | [aigc-monetization](./07-aigc-monetization.md) | Tier 3 输出形态、unit economics、定价 |
| 08 | [hermes-aligned-structure](./08-hermes-aligned-structure.md) | Hermes 官方约定对齐 / 单源部署 / 参考文档结构 |
| 09 | [deployment-pattern](./09-deployment-pattern.md) | Vultr Japan + cloudflared tunnel + Docker 隔离 / Risk register |

Find the 阶段维度文档 table and remove the Status column similarly:

Old:

markdown

| 文件 | 阶段 | 状态 |
|---|---|---|
| [P1 Spec](./superpowers/specs/2026-05-07-twilight-drive-phase1.md) | Hosted SaaS MVP（P1.0–P1.3） | DRAFT |
| [P1 Plan](./superpowers/plans/2026-05-07-twilight-drive-phase1.md) | P1 任务清单 | DRAFT |
| [P2 Spec](./superpowers/specs/2026-05-07-twilight-drive-phase2.md) | 三 initiative：仓库 / profile mgr / token gateway | DRAFT |
| [P2 Plan](./superpowers/plans/2026-05-07-twilight-drive-phase2.md) | P2 任务清单 | DRAFT |

New:

markdown

| 文件 | 阶段 |
|---|---|
| [P1 Spec](./superpowers/specs/2026-05-07-twilight-drive-phase1.md) | Hosted SaaS MVP（P1.0–P1.3） |
| [P1 Plan](./superpowers/plans/2026-05-07-twilight-drive-phase1.md) | P1 任务清单 |
| [P2 Spec](./superpowers/specs/2026-05-07-twilight-drive-phase2.md) | 三 initiative：仓库 / profile mgr / token gateway |
| [P2 Plan](./superpowers/plans/2026-05-07-twilight-drive-phase2.md) | P2 任务清单 |
| [Site IA Restructure Spec (2026-05-08)](./superpowers/specs/2026-05-08-site-ia-restructure-design.md) | 文档站重构 |
| [Site IA Restructure Plan (2026-05-08)](./superpowers/plans/2026-05-08-twilight-drive-site-ia.md) | 重构任务清单 |

Find dated plans table and drop Status column:

Old:

markdown

| 文件 | 用途 | 状态 |
|---|---|---|
| [`plans/2026-05-07-deploy-pattern.md`](./plans/2026-05-07-deploy-pattern.md) | Docker + cloudflared 部署骨架（deploy/ 目录 + CI image build 占位） | ✅ Tasks 1-6 landed; Tasks 7-8 待 (CI + phase1 spec 已部分更新) |
| [`plans/2026-05-07-hermes-restructure.md`](./plans/2026-05-07-hermes-restructure.md) | Hermes 对齐重构（SKILL.md frontmatter + profile 完整模板 + references 拆分） | ✅ Implemented (PR #9) |
| [`plans/2026-05-07-v0.1.1-hotfix.md`](./plans/2026-05-07-v0.1.1-hotfix.md) | v0.1.1 hotfix 实施记录 + P1.0 backend 起步 | ✅ Phase 1 shipped；⏳ Phase 2 待 |
| [`plans/2026-04-30-p1-service.md`](./plans/2026-04-30-p1-service.md) | P1 第一版 spec | 🔄 Superseded by P1 superpowers spec |

New:

markdown

| 文件 | 用途 |
|---|---|
| [`plans/2026-05-07-deploy-pattern.md`](./plans/2026-05-07-deploy-pattern.md) | Docker + cloudflared 部署骨架（deploy/ 目录 + CI image build 占位） |
| [`plans/2026-05-07-hermes-restructure.md`](./plans/2026-05-07-hermes-restructure.md) | Hermes 对齐重构（SKILL.md frontmatter + profile 完整模板 + references 拆分） |
| [`plans/2026-05-07-v0.1.1-hotfix.md`](./plans/2026-05-07-v0.1.1-hotfix.md) | v0.1.1 hotfix 实施记录 + P1.0 backend 起步 |
| [`plans/2026-04-30-p1-service.md`](./plans/2026-04-30-p1-service.md) | P1 第一版 spec（已 superseded） |

Find recommended-reading line and update:

Old:

markdown

**新人**：03（架构基线）→ 01（数据层决策）→ superpowers/specs/phase1（产品形态）→ MASTER_PLAN.md

New:

markdown

**新人**：[/about/](/about/) → 03（架构基线）→ 01（数据层决策）→ superpowers/specs/phase1（产品形态）→ [/status/](/status/)

[ ] Step 8.3: Verify build + commit

bash

pnpm --silent run docs:build 2>&1 | tail -5
git add docs/planning/index.md
git commit -m "docs: drop Status column from planning index (now /status/'s job)"

Files:

Modify: docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase1.md
Modify: docs/planning/plans/2026-05-07-v0.1.1-hotfix.md
[ ] Step 9.1: Locate the P1.1 pricing section in phase1 spec

bash

grep -n "¥198\|Lite tier\|Pro tier" docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase1.md

Note the line numbers of the first match — that's roughly the start of the P1.1 pricing/landing section.

[ ] Step 9.2: Add callout above the pricing section

Open the file. Find the section heading immediately preceding the first pricing-card mention (likely ## P1.1 … or ### Pricing or similar). Insert this callout block right after that heading and before the pricing content:

markdown

::: warning 📤 已迁出本站点
本节中关于"价格 / Lite tier / 付费 landing 页 / WeChat Pay"等对外内容，在实施时**不**呈现于 `dev.fsagent.cc`。对外付费版本将在独立站点 + 独立项目中推出。本站点呈现此 spec 仅限内部参考；实施时仅写 provisioner 服务、profile 克隆、Postgres schema 等技术部分。
:::

[ ] Step 9.3: Update v0.1.1-hotfix Phase 2 banner

Find at the top of docs/planning/plans/2026-05-07-v0.1.1-hotfix.md:

markdown

> **Status:** ✅ Phase 1 (hotfix) shipped 2026-05-07 · ⏳ Phase 2 (P1.0 backend) pending

Replace with:

markdown

> **Status:** ✅ Phase 1 (hotfix) shipped 2026-05-07 · ✅ Phase 2 Tasks 7-10 implemented in PR #13 (待合主线) · Tasks 11-12 待操作 · 完整状态见 [/status/](/status/)

Find the Phase 2 section heading:

markdown

## Phase 2: P1.0 Backend Skeleton (Week 2, ⏳ pending)

Replace with:

markdown

## Phase 2: P1.0 Backend Skeleton (Week 2, ✅ Tasks 7-10 in PR #13 · ⏳ Tasks 11-12 待操作)

[ ] Step 9.4: Verify build + commit

bash

pnpm --silent run docs:build 2>&1 | tail -5
git add docs/planning/superpowers/specs/2026-05-07-twilight-drive-phase1.md docs/planning/plans/2026-05-07-v0.1.1-hotfix.md
git commit -m "docs: align phase1 spec + v0.1.1-hotfix banners with real state"

Task 10: Archive `MASTER_PLAN.md`

Files:

Move: MASTER_PLAN.md → docs/planning/archive/2026-05-07-master-plan.md

The file is going to be archived under its original authored date (2026-05-07), not the move date. This preserves chronology in the archive folder.

[ ] Step 10.1: git mv with rename

bash

git mv MASTER_PLAN.md docs/planning/archive/2026-05-07-master-plan.md

[ ] Step 10.2: Prepend Superseded banner to the archived file

Open docs/planning/archive/2026-05-07-master-plan.md. At the very top (above the existing # Twilight Drive — Master Plan & Product Launch Spec heading), insert:

markdown

::: danger 🪦 Superseded
- Part 1（当前状态）→ [/status/](/status/) Done 段
- Part 2（Phase 1 outstanding）→ `superpowers/specs/phase1` + `superpowers/plans/phase1`
- Part 3（Phase 2 三 initiative）→ `superpowers/specs/phase2` + `superpowers/plans/phase2`
- Part 4（文档重组方案）→ 由 [`2026-05-08-site-ia-restructure-design`](../superpowers/specs/2026-05-08-site-ia-restructure-design.md) 取代
- Part 5（执行 roadmap）→ [/status/](/status/) Next 段

本文档保留作为历史参考，**不再维护**。任何状态以 [/status/](/status/) 为准。
:::

---

[ ] Step 10.3: Sweep for any remaining references to MASTER_PLAN.md outside the archive

bash

grep -rn "MASTER_PLAN" docs/ --exclude-dir=archive --exclude-dir=dist 2>&1
grep -rn "MASTER_PLAN" README.md scripts/ 2>&1

For each match outside archive: update the link to point to either /status/ (if context is project state) or the archive path (if context is historical reference). Common candidates:

docs/planning/index.md recommended-reading line — already handled in Task 8 (replaced with /status/)
docs/planning/superpowers/README.md — if it cites MASTER_PLAN, change to point at archive path
[ ] Step 10.4: Verify repo root is now clean

bash

ls /Users/syone/twilight-drive/ | grep -i master

Expected: empty output.

[ ] Step 10.5: Verify build + commit

bash

pnpm --silent run docs:build 2>&1 | tail -5
git status --short
git add -A
git commit -m "docs: archive MASTER_PLAN.md (superseded by /status/ + IA spec)"

Task 11: Push the unpushed `v0.1.1` git tag

Files: none (operator-side)

The v0.1.1-hotfix Phase 1 plan Step 6.5 was never executed; the git tag exists locally (or doesn't) but isn't on origin. The /status/ page asserts v0.1.1 is "已发布" — this task makes that true.

[ ] Step 11.1: Verify whether tag exists locally

bash

git tag --list 'v0.1.1'

Two cases:

Case A — tag exists locally: skip to Step 11.3.

Case B — tag does not exist locally: continue to Step 11.2.

[ ] Step 11.2: Create the tag on the v0.1.1 commit

Identify the v0.1.1 commit (the akshare/market routing commits — check git log around the date 2026-05-07 for 084843b and 2d7e5ce):

bash

git log --oneline --all | grep -E "0\.1\.1|akshare|market" | head -5

Expected: at minimum 2d7e5ce Swap akshare adapter to Xueqiu per-code endpoint and 084843b Route get_price to akshare during market hours; bump to 0.1.1.

The version bump commit is 084843b. Tag it:

bash

git tag -a v0.1.1 084843b -m "v0.1.1 — price freshness hotfix (akshare intraday + Tushare daily routing + served_by cite field)"

[ ] Step 11.3: Push the tag to origin

bash

git push origin v0.1.1

Expected: * [new tag] v0.1.1 -> v0.1.1

[ ] Step 11.4: Verify on remote

bash

git ls-remote --tags origin v0.1.1

Expected: one line showing the tag SHA on origin.

[ ] Step 11.5: No commit needed — tag push is a separate git operation, not a working-tree change. Move to Task 12.

Task 12: Final verification — full build + dead-link sweep + forbidden-term sweep

Files: none (verification only)

[ ] Step 12.1: Clean build

bash

rm -rf docs/.vitepress/dist
pnpm --silent run docs:build 2>&1 | tail -30

Expected: build complete line; build duration <60s; no fatal errors.

[ ] Step 12.2: Forbidden-term sweep (must return 0 hits outside archive/dist)

bash

grep -rnE "¥198|Lite tier|PaaS" docs/ \
  --exclude-dir=archive --exclude-dir=dist 2>&1

Expected: empty output. (The archived MASTER_PLAN.md and the phase1 spec inside its 📤 已迁出本站点 callout may legitimately contain pricing terms; that's why the archive directory is excluded.)

Note: The phase1 spec body (post-Task-9 callout) still mentions pricing in the spec text below the callout — that's intentional. The callout makes clear this content is "迁出"; the spec retains it for cross-reference. Exclude phase1 spec from this sweep if needed:
bash
grep -rnE "¥198|Lite tier|PaaS" docs/ \
  --exclude-dir=archive --exclude-dir=dist \
  --exclude="2026-05-07-twilight-drive-phase1.md" 2>&1

[ ] Step 12.3: Dead-link sweep (informational; ignoreDeadLinks: true is on)

bash

pnpm --silent run docs:build 2>&1 | grep -iE "dead link|missing" | head -20

Expected: ideally empty. Any flagged links should be reviewed; /use/wechat#anchor style internal anchors should resolve.

[ ] Step 12.4: Live preview spot check

Start preview server:

bash

pnpm --silent run docs:preview &
sleep 3

Verify the 5 nav links each return 200:

bash

for path in / /use/ /status/ /architecture/ /planning/ /about/; do
  printf "%-20s " "$path"
  curl -s -o /dev/null -w "%{http_code}\n" "http://localhost:4173$path"
done

Expected: all 200.

Verify redirect HTML present:

bash

curl -s http://localhost:4173/overview/what-is-it | grep -oE 'http-equiv="refresh"' | head -1
curl -s http://localhost:4173/overview/roadmap | grep -oE 'http-equiv="refresh"' | head -1

Expected: each command outputs http-equiv="refresh".

Stop preview:

bash

pkill -f 'vitepress preview' 2>/dev/null || true

[ ] Step 12.5: Final git log review

bash

git log --oneline main..HEAD
git diff --stat main..HEAD

Expected: ~10 commits, all with docs: prefix. --stat shows file additions/deletions consistent with file map.

[ ] Step 12.6: No commit needed — verification only.

Task 13: Open the PR

Files: none (uses gh CLI)

[ ] Step 13.1: Push the branch

bash

git push -u origin docs/site-ia-restructure-spec

[ ] Step 13.2: Open PR via gh

bash

gh pr create --base main --head docs/site-ia-restructure-spec \
  --title "docs: site IA restructure (audience-led, /use/ + /status/ + /about/)" \
  --body "$(cat <<'EOF'
## Summary

- Reorganize `dev.fsagent.cc` from "by engineering layer" to "by audience path" — research colleagues (semi-tech, mostly WeChat) primary; operator (Liang) secondary
- New top-level nav (5): 使用 / 状态 / 架构 / 规划 / 关于
- Adds `/use/` (6 docs) — WeChat usage / price-freshness semantics / capability list / CLI / feedback
- Adds `/status/` — single source of truth for project state (Now / Done / Next / Later)
- Adds `/about/` — replaces `/overview/`
- Deletes `/developer/` (empty stub) + `docs/getting-started.md` (content moved to `/use/cli`)
- Archives `MASTER_PLAN.md` under `docs/planning/archive/2026-05-07-master-plan.md`
- Pushes the unpushed `v0.1.1` git tag (Phase 1 plan Step 6.5)

## Spec & plan

- Spec: [`docs/planning/superpowers/specs/2026-05-08-site-ia-restructure-design.md`](docs/planning/superpowers/specs/2026-05-08-site-ia-restructure-design.md)
- Plan: [`docs/planning/superpowers/plans/2026-05-08-twilight-drive-site-ia.md`](docs/planning/superpowers/plans/2026-05-08-twilight-drive-site-ia.md)

## Real-state corrections recorded

- P1.0 backend: written as Tasks 7-10 in PR #13 (OPEN/MERGEABLE), Tasks 11-12 (Vultr + profile migration) operator-side pending
- v0.1.1 git tag pushed in this PR

## Test plan

- [ ] `pnpm run docs:build` — clean build (verify in CI)
- [ ] `dev.fsagent.cc/use/`, `/status/`, `/about/` all live after merge (CF Pages auto-deploy)
- [ ] `/overview/what-is-it` and `/overview/roadmap` redirect correctly
- [ ] `/developer/` returns 404 (acceptable — no inbound links)
- [ ] `git ls-remote --tags origin v0.1.1` shows the tag
- [ ] No occurrence of `¥198 / Lite tier / PaaS` outside `docs/planning/archive/` or the phase1 spec callout

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

[ ] Step 13.3: Capture PR URL

The gh pr create output ends with the PR URL. Capture it (e.g. #14) and update docs/status/index.md placeholder (PR #?) with the actual number, then push:

bash

PR_URL=$(gh pr view --json url --jq .url)
PR_NUM=$(echo "$PR_URL" | grep -oE '[0-9]+$')
echo "PR opened: $PR_URL (#$PR_NUM)"

# Replace the placeholder
sed -i.bak "s/(PR #?)/(PR #$PR_NUM)/g" docs/status/index.md
rm docs/status/index.md.bak
git add docs/status/index.md
git commit -m "docs(status): fill in PR number"
git push

Self-review checklist

After implementing every task:

#	Check	How
1	All 9 spec sections (§1-§11 minus headers) covered by tasks	Spec §1.1→Tasks 1-12; §3-§7→Tasks 1-10; §8 success criteria→Task 12; §9 risks→handled inline; §10 TBDs→Tasks 2.6 + 2.5
2	No `TBD` / `TODO` / `Add appropriate ...` in any task body	grep `TBD\|TODO\|appropriate` in this file should match only the inline "TBD-2 retained" annotation in Step 2.5
3	Every code/markdown block is complete and copy-pasteable	reader does not need to invent any content
4	File paths + commands all absolute or repo-rooted, never `..`	scan for `\.\./` outside the legitimate ADR cross-link in step 1.1
5	Verify-build between major content tasks (2, 3, 4, 5, 7, 8, 9, 10) and a final clean build (12)	each verification step is concrete

Risks (cross-task)

Risk	Mitigation
Task 5 sidebar config typo breaks the build	Task 5.3 runs `pnpm run docs:build` before commit; revert with `git checkout -- docs/.vitepress/config.ts` if it errors
Task 11 tag operation is irreversible (push to origin)	Verify commit SHA in Step 11.2 against `git log --oneline` before tagging; if wrong, use `git tag -d v0.1.1` (local) before push
Task 13 PR opens against the wrong base	Step 13.2 explicitly sets `--base main`; verify branch name in `git branch --show-current` before push
`/overview/why.md` deletion breaks an external link	Acceptable — page had no callers from outside; if discovered post-merge, restore from git history with a redirect

Out of scope (do not do)

Any changes to core/, skill/, or src/ source code
Any merge of PR #13 (operator decision; this PR is independent)
Vultr deployment of the P1.0 backend (Task 11 in v0.1.1-hotfix Phase 2 — operator work)
Profile migration to Service mode (Task 12 in v0.1.1-hotfix Phase 2 — operator work)
Building the external (PaaS) site

Site IA Restructure — Implementation Plan ​

File map ​

Task 1: Write /about/index.md ​

Task 2: Write /use/ subtree (6 files) ​

配置 ​

跑 ​

当前价 / 最近收盘 ​

指定历史日期 ​

基本面 ​

退出码 ​

升级到 Service 模式 ​

Task 3: Write /status/index.md ​

Task 4: Rewrite docs/index.md (home page) ​

Task 5: Update .vitepress/config.ts (nav + sidebar) ​

Task 6: Add redirects on /overview/what-is-it.md and /overview/roadmap.md ​

Task 7: Delete /overview/why.md, /developer/, docs/getting-started.md ​

Task 8: Update docs/planning/index.md — drop Status column ​

Task 9: Annotate phase1 spec + v0.1.1-hotfix Phase 2 banner ​

Task 10: Archive MASTER_PLAN.md ​

Task 11: Push the unpushed v0.1.1 git tag ​

Task 12: Final verification — full build + dead-link sweep + forbidden-term sweep ​

Task 13: Open the PR ​

Self-review checklist ​

Risks (cross-task) ​

Out of scope (do not do) ​

Site IA Restructure — Implementation Plan

File map

Task 1: Write `/about/index.md`

Task 2: Write `/use/` subtree (6 files)

配置

跑

当前价 / 最近收盘

指定历史日期

基本面

退出码

升级到 Service 模式

Task 3: Write `/status/index.md`

Task 4: Rewrite `docs/index.md` (home page)

Task 5: Update `.vitepress/config.ts` (nav + sidebar)

Task 6: Add redirects on `/overview/what-is-it.md` and `/overview/roadmap.md`

Task 7: Delete `/overview/why.md`, `/developer/`, `docs/getting-started.md`

Task 8: Update `docs/planning/index.md` — drop Status column

Task 9: Annotate phase1 spec + v0.1.1-hotfix Phase 2 banner

Task 10: Archive `MASTER_PLAN.md`

Task 11: Push the unpushed `v0.1.1` git tag

Task 12: Final verification — full build + dead-link sweep + forbidden-term sweep

Task 13: Open the PR

Self-review checklist

Risks (cross-task)

Out of scope (do not do)