# AGENTS.md — @app/docs

## 职责

**产品文档站**（VitePress）：面向用户的使用说明，中文在根路径、英文在 `/en`。与 `@app/web` 产品页分离——这里是文档，不是应用路由。

不依赖 `@app/*` 业务包；纯 Markdown + VitePress 配置，无 tRPC / DB。

## 结构

```
.vitepress/
  config.mts        # locales（root=zh-CN, en）、nav、sidebar、搜索文案
  theme/index.ts    # 扩展默认主题；无本地偏好时默认暗色（与主应用一致）
  theme/custom.css  # 自定义样式
guide/              # 中文文档（权威源）
  what-is.md | quick-start.md | mount.md | browse.md
  library.md | danmaku.md | scrape.md | account.md | faq.md
en/guide/           # 英文文档（与 guide/ 同构，逐篇对应）
index.md            # 中文首页
en/index.md         # 英文首页
public/             # 静态资源（favicon 等）
```

## 约定

- **双语同构**：`guide/*.md` 与 `en/guide/*.md` 文件名一一对应；新增页面两边同时加，并在 `config.mts` 的 `zhSidebar` / `enSidebar` 登记。
- 路径用 `cleanUrls: true`（链接不带 `.html`）。
- 文案语气与产品一致（「帆幕」/「Fanmu」）；中文文档用简体中文，不混繁体。
- 搜索为 VitePress local provider，UI 文案在 `config.mts` 的 `themeConfig.search` 内联翻译，不另建 i18n 包。
- 主题默认暗色：`theme/index.ts` 在无 `vitepress-theme-appearance` 时写入 `dark`，与 web 的 `app-theme` 偏好独立。

## 修改指南

- **加一页文档**：`guide/<slug>.md` + `en/guide/<slug>.md` → 更新 `config.mts` 两侧 sidebar。
- **改导航顺序**：只改 `config.mts` 的 `zhNav`/`zhSidebar`/`enNav`/`enSidebar`，保持中英结构对称。
- **加静态资源**：放 `public/`，引用用绝对路径 `/xxx`。
- 不要引入 Vue 组件或自定义布局（当前只用默认主题 + CSS）；确需扩展时走 `theme/index.ts`。
- 构建产物 `.vitepress/dist/` 与缓存 `.vitepress/cache/` 勿手改。

## 命令

```bash
yarn docs:dev                 # 本地预览
yarn docs:build               # 构建到 .vitepress/dist/
yarn workspace @app/docs typecheck
yarn workspace @app/docs lint
```