app-template/app/docs/AGENTS.md

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/ 勿手改。

命令

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