OpenTBook 产品需求文档 (PRD)

┌─────────────────────────────────────────────────────────┐
│                    OpenTBook 项目                         │
├──────────┬──────────────┬──────────────┬────────────────┤
│  内容层   │    展示层     │   工具链层    │   AI 辅助层    │
│ content/ │  Docus v5    │  markdownlint│  Claude Code   │
│ Markdown │  Nuxt 4      │  commitlint  │  Skills/Rules  │
│ MDC 语法  │  HMR 预览    │  husky hooks │  文档生成/校验   │
└──────────┴──────────────┴──────────────┴────────────────┘
         │                                    │
         ▼                                    ▼
    Git 仓库（Alibaba Cloud Codeup）      本地开发环境

OpenTBook/
├── .claude/                          # Claude Code 配置
│   ├── rules/                        # 自定义规则
│   │   ├── markdown-standards.md     # Markdown 写作标准
│   │   └── frontmatter-schema.md     # frontmatter 规范
│   └── skills/                       # 自定义技能
│       ├── new-doc.md                # 创建新文档
│       └── review-doc.md             # 审查文档质量
├── .husky/                           # Git 钩子
│   ├── pre-commit                    # lint-staged → markdownlint
│   └── commit-msg                    # commitlint
├── content/                          # 文档内容（核心目录）
│   ├── 0.index.md                    # 站点首页（Landing Page）
│   ├── 1.guide/                      # 入门指南
│   │   ├── _dir.yml                  # 分区元数据
│   │   ├── 1.introduction.md         # 项目介绍
│   │   ├── 2.quick-start.md          # 快速开始
│   │   └── 3.writing-guide.md        # 写作规范
│   ├── 2.engineering/                # 工程技术
│   │   ├── _dir.yml
│   │   ├── architecture/             # 架构设计
│   │   ├── development/              # 开发规范
│   │   └── devops/                   # 运维部署
│   ├── 3.research/                   # 研究笔记
│   │   ├── _dir.yml
│   │   ├── papers/                   # 论文阅读
│   │   ├── experiments/              # 实验记录
│   │   └── models/                   # 模型文档
│   ├── 4.projects/                   # 项目文档
│   │   └── _dir.yml
│   ├── 5.processes/                  # 流程规范
│   │   ├── _dir.yml
│   │   ├── code-review.md            # 代码审查流程
│   │   ├── release.md                # 发版流程
│   │   └── onboarding.md             # 入职指南
│   └── 6.resources/                  # 资源参考
│       ├── _dir.yml
│       ├── tools.md                  # 工具推荐
│       ├── links.md                  # 常用链接
│       └── glossary.md               # 术语表
├── public/                           # 静态资源
│   └── images/                       # 文档图片
├── templates/                        # 文档模板（不被 Docus 渲染）
│   ├── tech-doc.md                   # 技术文档模板
│   ├── paper-note.md                 # 论文笔记模板
│   ├── experiment-log.md             # 实验记录模板
│   ├── meeting-note.md               # 会议纪要模板
│   └── adr.md                        # 架构决策记录模板
├── .gitignore                        # Git 忽略规则
├── .markdownlint.jsonc               # markdownlint 规则
├── app.config.ts                     # Docus 主题配置
├── CLAUDE.md                         # Claude Code 项目指南
├── commitlint.config.js              # 提交信息规范
├── nuxt.config.ts                    # Nuxt/Docus 核心配置
├── package.json                      # 项目依赖与脚本
├── prd.md                            # 本文档
└── tsconfig.json                     # TypeScript 配置

{
  "name": "opentbook",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build",
    "preview": "nuxt preview",
    "generate": "nuxt generate",
    "lint:md": "markdownlint-cli2 \"content/**/*.md\"",
    "lint:md:fix": "markdownlint-cli2 --fix \"content/**/*.md\"",
    "prepare": "husky"
  },
  "devDependencies": {
    "nuxt": "^4.3.1",
    "docus": "^5.9.0",
    "better-sqlite3": "^12.6.2",
    "markdownlint-cli2": "^0.17.0",
    "lint-staged": "^15.0.0",
    "@commitlint/cli": "^19.0.0",
    "@commitlint/config-conventional": "^19.0.0",
    "husky": "^9.0.0"
  },
  "lint-staged": {
    "content/**/*.md": [
      "markdownlint-cli2"
    ]
  }
}

export default defineNuxtConfig({
  extends: ['docus'],
})

export default defineAppConfig({
  docus: {
    locale: 'zh-CN',
  },
  ui: {
    colors: {
      primary: 'emerald',
      neutral: 'zinc',
    },
  },
  header: {
    title: 'OpenTBook',
  },
  toc: {
    title: '本页目录',
  },
  github: {
    url: 'https://codeup.aliyun.com/uueic/UUAILab/AITeaM/OpenTBook',
    branch: 'master',
  },
})

{
  "default": true,
  "MD013": {
    "line_length": 120,
    "heading_line_length": 80,
    "code_block_line_length": 120,
    "tables": false
  },
  "MD024": {
    "siblings_only": true
  },
  "MD033": {
    "allowed_elements": ["br", "details", "summary", "sup", "sub"]
  },
  "MD041": false
}

export default {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'docs',      // 文档内容变更（最常用）
        'feat',      // 新功能/新模板
        'fix',       // 修正错误内容
        'style',     // 格式调整
        'refactor',  // 重构文档结构
        'chore',     // 工具链/配置变更
        'ci',        // CI/CD 变更
      ],
    ],
    'subject-max-length': [2, 'always', 100],
    'subject-case': [0],   // 允许中文 subject
  },
}

---
title: 页面中文标题                    # 必填
description: 简短描述（50-160 字符）    # 必填
authors:                               # 必填
  - name: 作者姓名
    date: 2026-04-13                   # ISO 日期格式
navigation:
  title: 侧边栏短标题                  # 可选
  icon: i-lucide-book-open             # 可选
---

title: string           # 页面标题（中文）
description: string     # 页面描述（50-160 字符）
authors: array          # 至少一个作者
  - name: string        # 作者姓名
    date: string        # YYYY-MM-DD

navigation.title: string   # 侧边栏短标题
navigation.icon: string    # 图标名称
toc: boolean               # 是否显示目录（默认 true）
draft: boolean             # 草稿（不出现在导航中）

撰写 ──▶ 预览 ──▶ 提交 ──▶ 审核 ──▶ 合并
 │         │        │        │        │
 │         │        │        │        │
任意      npm     husky    Codeup   master
编辑器   run dev   钩子     MR 评审   分支
               自动校验

# 方式一：手动创建，参照 templates/ 中的模板
# 方式二：使用 Claude Code（推荐）
# 在终端中使用 /new-doc 技能从模板创建

pnpm dev    # 或 npm run dev
# 浏览器访问 http://localhost:3000
# 文件保存后自动热更新（HMR），无需手动刷新

git add content/2.engineering/1.new-feature.md
git commit -m "docs(engineering): 添加新功能技术方案"

git push origin docs/my-feature
# 在 Codeup 上创建合并请求（Merge Request）

# 1. 克隆仓库
git clone https://codeup.aliyun.com/uueic/UUAILab/AITeaM/OpenTBook.git
cd OpenTBook

# 2. 安装依赖
pnpm install    # 或 npm install

# 3. 启动开发服务器
pnpm dev        # 或 npm run dev

# 4. 打开浏览器访问
# http://localhost:3000

# 1. 创建分支
git checkout -b docs/my-first-doc

# 2. 在 content/ 对应目录下创建 .md 文件
# 参照 templates/ 中的模板，添加完整 frontmatter

# 3. 保存后浏览器自动刷新预览

# 4. 提交
git add content/1.guide/4.my-first-doc.md
git commit -m "docs(guide): 添加我的第一篇文档"
git push origin docs/my-first-doc

# 5. 在 Codeup 上发起合并请求

---
title: 文档标题
description: 简短描述（50-160 字符）
authors:
  - name: 作者姓名
    date: YYYY-MM-DD
---

## 概述

简要说明本文档的目的和背景。

## 问题/需求

描述要解决的问题或需求。

## 方案设计

### 技术选型

### 架构设计

### 关键实现

## 影响评估

### 性能影响

### 兼容性

## 参考资料

- [链接名称](URL)

---
title: '论文标题'
description: 论文核心贡献的一句话总结
authors:
  - name: 笔记作者
    date: YYYY-MM-DD
---

## 论文信息

- **标题**：
- **作者**：
- **发表**：会议/期刊 + 年份
- **链接**：[arXiv](URL) | [PDF](URL)

## 核心贡献

## 方法概述

## 实验结果

## 个人思考

## 与团队工作的关联

---
title: '实验名称'
description: 实验目标的一句话总结
authors:
  - name: 实验者
    date: YYYY-MM-DD
---

## 实验目标

## 实验设置

### 数据集

### 模型配置

### 超参数

## 实验结果

## 分析与结论

## 后续计划

---
title: 'YYYY-MM-DD 会议主题'
description: 会议核心议题总结
authors:
  - name: 记录人
    date: YYYY-MM-DD
---

## 会议信息

- **时间**：YYYY-MM-DD HH:MM
- **参与者**：
- **地点/链接**：

## 议题与讨论

### 议题 1

### 议题 2

## 决议事项

| 事项 | 负责人 | 截止日期 |
|------|-------|---------|

## 待办跟踪

---
title: 'ADR-NNN: 决策标题'
description: 决策的一句话总结
authors:
  - name: 提议者
    date: YYYY-MM-DD
---

## 状态

提议中 | 已采纳 | 已废弃 | 已替代

## 背景

什么情况下需要做这个决策？

## 决策

我们决定...

## 理由

为什么选择这个方案？考虑了哪些替代方案？

## 影响

这个决策带来什么后果？

<!-- 提示框 -->
::note
这是一条信息提示。
::

::tip
这是一条建议。
::

::warning
这是一条警告。
::

::caution
这是一条危险提示。
::

<!-- 代码组 -->
::code-group

```bash [pnpm]
pnpm install

## 附录 C：常见问题

**Q: 可以用 npm 代替 pnpm 吗？**

A: 可以。所有 `package.json` scripts 兼容 npm。运行 `npm install` + `npm run dev` 即可。

**Q: 图片应该放在哪里？**

A: 放在 `public/images/{section}/` 目录下，在 Markdown 中用 `/images/{section}/{filename}.png` 引用。

**Q: 如何添加新的内容分类？**

A: 在 `content/` 下创建新目录（如 `7.new-section/`），添加 `_dir.yml` 设置标题和图标，Docus 会自动识别。

**Q: 能否离线使用？**

A: 可以。安装依赖后所有功能均在本地运行，不依赖外部服务。