主题
05 — 文档系统 (Documentation)
VitePress 是不是一个比较好的方案？
目标 (Goal)
文档要承载 4 类内容：
- 产品介绍 — 是什么、为什么
- 架构说明 — 5 层架构、决策记录 (ADR)
- 使用指南 — Skill / MCP 怎么用、怎么扩展
- 变更日志 — 升级计划、版本历史
文档不是事后写的，是与代码一起演进的。
VitePress 评估
优势
- ✅ Vue 生态、Markdown-first、配置简单
- ✅ 默认主题美观、首屏速度快 (Vite 加持)
- ✅ 支持 Vue 组件嵌入 → 可以做交互式 demo（比如直接展示 Agent 输出）
- ✅ i18n 内置 → 中英双语容易做
- ✅ 部署简单 (静态 HTML，丢 GitHub Pages / Vercel / Cloudflare Pages 都行)
局限
- ❌ 搜索默认是本地搜索，大文档要接 Algolia
- ❌ 不是 docs-as-code 体系最重的工具（不如 Sphinx 在 API doc 自动生成上强）
- ❌ Vue 生态色彩重，团队如果不熟 Vue 改 theme 略费劲
与替代方案对比
| 方案 | 适用场景 | 这个项目的契合度 |
|---|---|---|
| VitePress | 产品/技术文档混合，开发者向 | ⭐⭐⭐⭐⭐ |
| Docusaurus | 大型多版本文档站，i18n 强 | ⭐⭐⭐⭐ |
| Mintlify | API 重、托管型、商业化做得最好 | ⭐⭐⭐ (vendor lock) |
| Starlight (Astro) | 性能极致、轻量 | ⭐⭐⭐⭐ |
| MkDocs Material | Python 生态首选、ADR/规范文档强 | ⭐⭐⭐⭐ |
| Nextra | Next.js 生态、博客+文档 | ⭐⭐⭐ |
结论：VitePress 是合理选择，没毛病。如果未来需要更强的 multi-version 和 versioned API ref，再考虑 Docusaurus。
文档结构建议
docs/
├── index.md # Landing
├── overview/
│ ├── what-is-it.md
│ ├── why.md
│ └── roadmap.md # 升级计划、版本路线图
├── architecture/
│ ├── 5-layers.md
│ ├── citation-protocol.md
│ ├── data-flow.md
│ └── adr/ # Architecture Decision Records
│ ├── 0001-tushare-as-primary.md
│ └── 0002-pdf-parsing-strategy.md
├── verticals/
│ └── astock/
│ ├── data-sources.md
│ ├── skills.md
│ └── examples.md
├── developer/
│ ├── add-a-skill.md
│ ├── add-a-data-adapter.md
│ └── eval.md
└── changelog.md关键决策点 (Open Questions)
Q1. 中文 vs 英文 vs 双语
- A 股市场 → 主要中文
- 但 Harness 复用 → 英文优先
- → 建议：英文为主，中文翻译；或反过来；不建议两边都"差不多"
- → 用户决定
Q2. ADR (Architecture Decision Records) 是否使用
强烈建议 使用。理由：
- 这个项目决策密集（数据源、PDF 方案、agent 架构等）
- ADR 让"为什么这样做"留痕
- 文档量小、价值高
Q3. 与代码的同步
- 选项 A：文档独立 repo
- 选项 B：文档与代码同 repo (推荐) —
docs/子目录，PR 一起改
Q4. Live demo / Playground
是否在文档里嵌入"试用 Agent" 的入口？
- 嵌入 → 体验好但要后端
- 不嵌入 → 一期省事
→ 一期建议：不嵌入，提供 CLI 截图 + 输出样例就够。
下一步
- 用户拍板 VitePress (或换方案)
- 用户决定 Q1 语言策略
- 在 04 Harness 框架确定目录结构后，把 docs 骨架建起来
- 一期最小可用：landing + 5 层架构图 + ADR-0001