docs: 重组文档目录并补充CI/CD细则

2026-09-01 09:55:40 +08:00
parent 49dbacb296
commit a5b709a46f
23 changed files with 263 additions and 37 deletions
@@ -0,0 +1,67 @@
+# 第一阶段分工表
+
+> 状态更新：2026-08-30。本文保留原始职责划分，同时记录当前交付状态。第一阶段后端目标已完成，前端 Web 联调页面已完成；尚未纳入本阶段完成项的是 Tauri Host、Stronghold、真实桌面文件系统、独立 MCP Plugin Host、真实音频模型和 Sync Server。
+
+## 当前交付状态
+
+| 领域 | 当前状态 | 说明 |
+| --- | --- | --- |
+| Desktop Frontend / UI | Web 联调版已完成 | 全部业务路由、Markdown 写作/源码编辑、Chat、Search、Agent、扩展管理、设置页和 Provider 配置已落地 |
+| Knowledge / Retrieval Core | 第一阶段已完成 | Markdown Block、SQLite/FTS5、sqlite-vec、Hybrid/RRF/Reranker、Citation 与事务修复均已覆盖测试 |
+| AI / Agent Core | 第一阶段已完成 | Streaming、Agent Loop、Tool、Permission、Trace、Skill/Plugin 与 Knowledge/Retrieval 调用链已落地 |
+| Model Core | 第一阶段已完成 | Mock、OpenAI Chat/OpenAI-Compatible、DeepSeek 预设、Ollama、模型发现和加密凭据链路可用 |
+| Desktop Host / Sync | 后续阶段 | Tauri、Stronghold、系统文件访问、Sidecar 生命周期和云同步尚未实现 |
+
+## 总分工表
+
+| 成员   | 主要职责                         | 第一阶段负责模块                                        | 具体工作内容                                                 | 主要交付物                                                   |
+| ------ | -------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
+| 吉海燕 | 前端设计与交互实现               | Desktop Frontend / UI                                   | 负责 Vue 3 + TypeScript 前端界面设计与实现；完成 Workspace、Markdown Editor、AI Chat、Search、Agent Trace、Skill/Plugin 管理、Theme Manager、Settings 等页面；维护 Design Token 与主题系统；负责前端状态管理与接口联调 | 前端页面、组件库、交互逻辑、主题系统、前端 Store、API Client、前端演示界面 |
+| 范涵宇 | 主要程序开发、整体架构与代码审阅 | Agent Core / Extension Core / Model Core / 后端基础框架 | 负责 Python AI Core 与 FastAPI 后端壳子搭建；负责 Agent Runtime、Tool Registry、Permission、Trace；负责 Skill Runtime、Plugin Runtime、Plugin Host/MCP Bridge 等扩展体系；负责 Provider Adapter、多模型协议统一与 API Key 调用链；负责核心接口设计、模块集成、工程规范与代码 Review | FastAPI Core、Agent Runtime、Tool Registry、Skill Runtime、Plugin Runtime、Provider Adapter、公共接口、代码审阅与集成版本 |
+| 杨星萱 | 本地知识库与检索系统开发         | Knowledge Core / Retrieval Core                         | 负责 Markdown Vault、Note/Block 数据模型、Markdown 解析与增量索引；负责 SQLite 元数据、FTS5 全文检索、sqlite-vec 向量检索；负责 Embedding、Hybrid Retrieval、RRF、Reranker、Metadata Filter、Citation 与笔记定位；负责 RAG 检索 Benchmark | Knowledge Core、Note Block、SQLite/FTS5、VectorStore、Embedding、Hybrid RAG、Reranker、Citation、检索测试数据 |
+
+
+
+## 细则：
+
+| 协作事项                       | 主负责人 | 配合人员       |
+| ------------------------------ | -------- | -------------- |
+| 前后端 API Contract            | 范涵宇   | 吉海燕         |
+| Markdown 编辑与 Note Core 联动 | 杨星萱   | 吉海燕         |
+| Search / Citation 前端展示     | 杨星萱   | 吉海燕         |
+| Agent 调用 RAG                 | 范涵宇   | 杨星萱         |
+| Agent 调用笔记 Tool            | 范涵宇   | 杨星萱         |
+| Skill 调用 Plugin Tool         | 范涵宇   | 吉海燕         |
+| Provider Streaming 前端显示    | 范涵宇   | 吉海燕         |
+| Agent Trace 前端显示           | 范涵宇   | 吉海燕         |
+| RAG Benchmark                  | 杨星萱   | 范涵宇         |
+| Agent Benchmark                | 范涵宇   | 杨星萱         |
+| 整体 Demo 联调                 | 范涵宇   | 吉海燕、杨星萱 |
+| UI/UX 最终统一                 | 吉海燕   | 全员           |
+| PR / 核心代码 Review           | 范涵宇   | 对应模块负责人 |
+
+## 验收：
+
+尽量通过VibeCoding在开学前把demo跑出来
+
+### 分别交付：
+
+吉海燕：能够完整操作 Workspace、编辑 Markdown、搜索、AI Chat，并展示 Citation 和 Agent Trace。
+
+范涵宇：Agent 能调用 Tool、Skill 能加载、Plugin 能注册 Tool、至少两个 Provider 可以切换运行。
+
+杨星萱：Markdown 能完成 Block 化索引，FTS5 + Vector + RRF + Reranker 能完成检索，并返回可定位 Citation。
+
+### 总体验收：
+
+```markdown
+→ 自动建立本地知识索引
+→ 用户向 Agent 提问
+→ Agent 调用 RAG
+→ Retrieval Core 找到 Note Block
+→ Provider 生成回答
+→ 前端显示 Citation
+→ 点击 Citation
+→ 跳转并高亮原笔记
+```
+
@@ -0,0 +1,821 @@
+# 第二阶段团队分工表
+
+## 一、阶段目标
+
+第二阶段延续第一阶段已经形成的模块边界，重点推进多模态输入、MCP 与 Plugin 扩展、更多 Provider、RAG / Agent Benchmark、多格式导出、主题社区格式、Agent Trace 可视化、Mermaid 渲染和函数图像绘制。
+
+第二阶段继续保持第一阶段的模块 ownership：
+
+- 范涵宇：Agent Core、Extension Core、Model Core、Multimodal、整体架构与代码审阅。
+- 杨星萱：Knowledge Core、Retrieval Core、Benchmark、文档导出、函数图像绘制。
+- 吉海燕：Frontend、Theme、Agent Trace、Plugin UI Contribution、Mermaid 渲染。
+
+---
+
+## 二、总分工表
+
+| 成员 | 主要负责方向 | 第二阶段任务 | 配合事项 |
+| --- | --- | --- | --- |
+| 范涵宇 | Agent Core / Extension Core / Model Core / Multimodal / 总体架构 | faster-whisper、pyannote.audio、MCP Bridge、Plugin Command Contribution 后端、Plugin Settings Contribution 后端、更多 Provider、整体集成、代码审阅与统筹 | 与吉海燕联调 Plugin Command / Settings 前端；为杨星萱的 Agent Benchmark 提供 Agent Trace、Tool Call 等测试接口 |
+| 杨星萱 | Knowledge Core / Retrieval Core / Benchmark / Export / 数学内容渲染 | RAG Benchmark、Agent Benchmark 基础设施、Markdown → HTML / PDF / DOCX、函数图像绘制与渲染支持、Retrieval 调优 | 与范涵宇确认 Agent Benchmark 事件和测试数据结构；与吉海燕联调函数图像在编辑器和预览区中的展示 |
+| 吉海燕 | Frontend / Theme / Visualization | Theme Import、Theme Manifest、社区主题格式、Agent Trace 可视化、Plugin Command / Settings 前端、Mermaid 渲染支持 | 与范涵宇联调 Plugin Contribution Contract 与 AgentEvent；与杨星萱联调函数图像及导出预览 |
+
+---
+
+## 三、范涵宇
+
+### 3.1 faster-whisper
+
+负责接入 faster-whisper，完成真实音频转写。
+
+目标链路：
+
+```text
+Audio
+↓
+faster-whisper
+↓
+Timestamped Transcript
+↓
+Knowledge Core
+```
+
+输出至少包含：
+
+```text
+text
+start_time
+end_time
+language
+```
+
+### 3.2 pyannote.audio
+
+负责说话人分离，并与 faster-whisper 组合。
+
+```text
+Audio
+↓
+pyannote.audio
+↓
+Speaker Segments
+↓
+faster-whisper
+↓
+Timestamped + Speaker Transcript
+```
+
+输出至少包含：
+
+```text
+speaker
+start_time
+end_time
+text
+```
+
+### 3.3 MCP Bridge
+
+负责实现 MCP Bridge，使外部 MCP Server 可以进入现有 Plugin / Tool 体系。
+
+```text
+External MCP Server
+↓
+MCP Bridge
+↓
+Plugin Runtime
+↓
+Tool Registry
+↓
+Agent Runtime
+```
+
+Agent Runtime 继续使用项目内部的：
+
+```text
+ToolDefinition
+ToolCall
+ToolResult
+```
+
+MCP Bridge 负责协议转换。
+
+### 3.4 Plugin Command Contribution
+
+负责 Plugin Runtime 中 Command Contribution 的解析、注册和执行接口。
+
+```text
+Plugin Manifest
+↓
+Plugin Runtime
+↓
+Command Registry
+↓
+Frontend Contract
+```
+
+吉海燕负责 Command Palette 等前端展示。
+
+### 3.5 Plugin Settings Contribution
+
+负责 Plugin Manifest 中 Settings Schema 的解析和后端配置接口。
+
+首批支持：
+
+```text
+string
+number
+boolean
+select
+secret reference
+```
+
+范涵宇负责 Manifest Parsing、Settings Schema、Plugin Storage、Secret Reference 和 Runtime Contract。
+
+### 3.6 更多 Provider
+
+继续完善 Provider Adapter。
+
+第二阶段优先验证：
+
+```text
+Normal Chat
+Streaming
+Tool Calling
+Reasoning Event
+Cancellation
+Usage
+Error Mapping
+```
+
+主要协议目标：
+
+```text
+OpenAI Responses
+OpenAI Chat Completions
+OpenAI-Compatible
+Anthropic Messages
+Ollama
+```
+
+Provider 数量不作为主要验收指标，优先保证协议适配稳定。
+
+### 3.7 审阅与统筹
+
+持续负责：
+
+- 公共 Contract 审阅；
+- Agent / Skill / Plugin / Provider 接口审阅；
+- 跨模块 PR Review；
+- 第二阶段整体架构一致性检查；
+- Demo 链路集成；
+- 公共错误类型和事件格式统一；
+- 第二阶段版本合并与发布前检查。
+
+---
+
+## 四、杨星萱
+
+### 4.1 RAG Benchmark
+
+建立正式 RAG Benchmark。
+
+比较：
+
+```text
+FTS5
+Vector Search
+Hybrid Retrieval
+Hybrid + RRF
+Hybrid + RRF + Reranker
+```
+
+核心指标：
+
+```text
+Hit@1
+Hit@5
+Recall@K
+MRR
+Citation Hit Rate
+P50 Latency
+P95 Latency
+```
+
+Dataset 至少记录：
+
+```text
+query
+expected_note_id
+expected_block_id
+expected_citation
+tags
+```
+
+### 4.2 Agent Benchmark
+
+负责 Agent Benchmark 测试框架、Dataset、指标统计和报告生成。
+
+范涵宇提供：
+
+```text
+Agent Run
+Agent Event
+Tool Call
+Tool Result
+Trace
+```
+
+主要指标：
+
+```text
+Task Success Rate
+Tool Selection Accuracy
+Tool Argument Accuracy
+Invalid Tool Call Rate
+Average Steps
+Average Latency
+Token Usage
+```
+
+示例：
+
+```yaml
+id: agent-os-review-001
+
+prompt: >
+  找出操作系统笔记中关于死锁的内容，
+  生成总结并创建三个复习任务。
+
+expected_tools:
+  - rag.search
+  - notes.read
+  - tasks.create
+
+expected_conditions:
+  citation_required: true
+  tasks_created: 3
+```
+
+### 4.3 多格式文档导出
+
+负责建立统一 Export Service：
+
+```text
+Document AST
+↓
+DocumentExporter
+├── HtmlExporter
+├── PdfExporter
+└── DocxExporter
+```
+
+统一接口示意：
+
+```python
+class DocumentExporter(Protocol):
+    async def export(
+        self,
+        document: Document,
+        options: ExportOptions,
+    ) -> ExportResult:
+        ...
+```
+
+第二阶段完成：
+
+```text
+Markdown → HTML
+Markdown → PDF
+Markdown → DOCX
+```
+
+导出时尽量保持：
+
+- 标题；
+- 段落；
+- 列表；
+- 表格；
+- 图片；
+- 引用；
+- 代码块；
+- 数学公式；
+- Mermaid；
+- 函数图像。
+
+Exporter 接口保留未来由 Plugin 增加 EPUB、LaTeX 等格式的扩展空间。
+
+### 4.4 函数图像绘制与渲染支持
+
+负责函数图像相关的数据解析、表达、绘制和渲染支持。
+
+目标示例：
+
+```text
+y = x^2
+y = sin(x)
+y = 2x + 1
+```
+
+内部建议抽象：
+
+```text
+FunctionPlot
+├── expressions
+├── domain
+├── range
+├── axis config
+└── render config
+```
+
+处理链：
+
+```text
+Markdown / Structured Block
+↓
+Function Expression Parser
+↓
+Function Plot Model
+↓
+Renderer
+↓
+Editor / Preview
+```
+
+需要考虑：
+
+- 二维函数；
+- 多函数同图；
+- 定义域；
+- 坐标轴；
+- 缩放；
+- 图像刷新；
+- Markdown 中的持久化格式；
+- HTML / PDF / DOCX 导出时的静态渲染。
+
+可设计独立 fenced block，例如：
+
+````markdown
+```function-plot
+y = x^2
+y = sin(x)
+```
+````
+
+具体语法在实现阶段冻结。
+
+函数图像的数据结构、解析和渲染逻辑由杨星萱负责；吉海燕配合完成前端容器、布局和交互。
+
+### 4.5 Retrieval 调优
+
+根据 RAG Benchmark 数据继续调整：
+
+```text
+Block Chunking
+FTS Query
+Vector Top-K
+RRF Parameters
+Reranker Candidate Count
+Score Threshold
+Metadata Filter
+```
+
+所有调优保留 Benchmark 前后对比数据。
+
+---
+
+## 五、吉海燕
+
+### 5.1 Theme Import
+
+负责 Theme Package 导入。
+
+建议结构：
+
+```text
+my-theme/
+├── theme.yaml
+├── theme.css
+├── preview.png
+└── README.md
+```
+
+流程：
+
+```text
+Import
+↓
+Manifest Validation
+↓
+Preview
+↓
+Install
+↓
+Enable
+↓
+Disable
+↓
+Uninstall
+```
+
+### 5.2 Theme Community Format
+
+负责制定和实现社区主题格式。
+
+示例：
+
+```yaml
+id: example-theme
+name: Example Theme
+version: 1.0.0
+author: example
+min_app_version: 0.2.0
+```
+
+主题继续基于：
+
+```text
+Design Token
+CSS Variables
+Theme Manifest
+```
+
+第二阶段优先完成本地导入和社区包格式，不要求立即实现联网 Theme Marketplace。
+
+### 5.3 Agent Trace 可视化
+
+负责将 Agent Runtime 执行过程可视化。
+
+建议结构：
+
+```text
+User Request
+│
+├── Model Call
+│
+├── rag.search
+│   ├── arguments
+│   ├── duration
+│   └── result
+│
+├── notes.read
+│
+├── Model Call
+│
+└── Completed
+```
+
+Trace Node 可展开查看：
+
+```text
+Arguments
+Result
+Duration
+Permission
+Usage
+Error
+```
+
+需要支持：
+
+- Agent Run 状态；
+- Tool Call 顺序；
+- Tool 调用耗时；
+- Tool Result 摘要；
+- Provider 调用；
+- Token Usage；
+- 错误状态；
+- 用户取消；
+- Citation 跳转。
+
+### 5.4 Plugin Command 前端
+
+负责 Command Contribution 在前端呈现。
+
+主要挂载：
+
+```text
+Command Palette
+Context Menu
+Toolbar Action
+```
+
+前端使用 Plugin Contribution Contract，不直接解析插件后端 Manifest。
+
+### 5.5 Plugin Settings 前端
+
+根据范涵宇提供的 Plugin Settings Schema 动态生成设置表单。
+
+支持：
+
+```text
+Input
+Number
+Switch
+Select
+Secret Input
+```
+
+Secret 类型通过 Secret API 提交，不写入 Pinia 持久化或普通配置文件。
+
+### 5.6 Mermaid 渲染支持
+
+负责在 Markdown 编辑器、预览区域和相关展示界面加入 Mermaid 渲染。
+
+目标 Markdown：
+
+````markdown
+```mermaid
+flowchart LR
+    A[Markdown] --> B[Renderer]
+    B --> C[Diagram]
+```
+````
+
+处理链：
+
+```text
+Markdown
+↓
+Mermaid Code Block
+↓
+Mermaid Renderer
+↓
+SVG
+↓
+Editor / Preview
+```
+
+需要支持：
+
+- Flowchart；
+- Sequence Diagram；
+- Class Diagram；
+- State Diagram；
+- ER Diagram；
+- Gantt 等常用 Mermaid 图；
+- Light / Dark Theme；
+- 编辑后重新渲染；
+- 渲染错误提示；
+- SVG 缩放与查看；
+- 导出时的静态图处理。
+
+Mermaid 渲染需要与 Theme Design Token 联动。
+
+与杨星萱负责的 Export Service 联调时，前端或渲染层需要提供 Mermaid → SVG / Image 的稳定输出，使 HTML、PDF 和 DOCX 导出能够保留图表。
+
+---
+
+## 六、跨成员协作表
+
+| 协作事项 | 主负责人 | 配合人员 |
+| --- | --- | --- |
+| MCP Bridge → Agent Tool | 范涵宇 | 杨星萱 |
+| Plugin Command Runtime | 范涵宇 | 吉海燕 |
+| Plugin Command UI | 吉海燕 | 范涵宇 |
+| Plugin Settings Runtime | 范涵宇 | 吉海燕 |
+| Plugin Settings UI | 吉海燕 | 范涵宇 |
+| Agent Benchmark Framework | 杨星萱 | 范涵宇 |
+| Agent Trace Event Contract | 范涵宇 | 吉海燕、杨星萱 |
+| Agent Trace Visualization | 吉海燕 | 范涵宇 |
+| RAG Benchmark | 杨星萱 | 范涵宇 |
+| Markdown Export | 杨星萱 | 吉海燕 |
+| Mermaid Editor Rendering | 吉海燕 | 杨星萱 |
+| Mermaid Export Rendering | 杨星萱 | 吉海燕 |
+| Function Plot Core / Rendering | 杨星萱 | 吉海燕 |
+| Function Plot Frontend Integration | 吉海燕 | 杨星萱 |
+| Theme Community Format | 吉海燕 | 范涵宇 |
+| Provider Streaming UI | 范涵宇 | 吉海燕 |
+| Multimodal → Knowledge Core | 范涵宇 | 杨星萱 |
+| 第二阶段整体 Demo | 范涵宇 | 吉海燕、杨星萱 |
+| 核心代码 Review | 范涵宇 | 对应模块负责人 |
+
+---
+
+## 七、第二阶段优先级
+
+### P0
+
+#### 范涵宇
+
+```text
+MCP Bridge
+faster-whisper
+pyannote.audio
+```
+
+#### 杨星萱
+
+```text
+RAG Benchmark
+Agent Benchmark Infrastructure
+Markdown → HTML
+函数图像基础渲染
+```
+
+#### 吉海燕
+
+```text
+Agent Trace Visualization
+Theme Manifest / Theme Import
+Mermaid Rendering
+```
+
+### P1
+
+#### 范涵宇
+
+```text
+Plugin Command Contribution
+Plugin Settings Contribution
+Provider Adapter 完善
+```
+
+#### 杨星萱
+
+```text
+Markdown → PDF
+Markdown → DOCX
+Retrieval 调优
+函数图像导出适配
+```
+
+#### 吉海燕
+
+```text
+Theme Community Format
+Plugin Command UI
+Plugin Settings UI
+Mermaid Theme Adaptation
+```
+
+### P2
+
+#### 范涵宇
+
+```text
+更多 Provider
+MCP 兼容性增强
+Multimodal Pipeline 优化
+```
+
+#### 杨星萱
+
+```text
+复杂格式导出
+Benchmark 报告自动生成
+函数图像高级配置
+```
+
+#### 吉海燕
+
+```text
+Theme 浏览与管理体验
+Agent Trace 高级筛选
+Mermaid 高级交互
+```
+
+---
+
+## 八、第二阶段共同验收 Demo
+
+建议使用“课堂学习全过程”作为第二阶段总 Demo：
+
+```text
+导入课堂录音
+↓
+pyannote.audio
+↓
+说话人分离
+↓
+faster-whisper
+↓
+带时间戳 Transcript
+↓
+生成 Markdown
+↓
+Knowledge Core 建立索引
+↓
+用户询问课程内容
+↓
+Agent 调用 RAG
+↓
+返回 Citation
+↓
+Agent Trace 可视化
+```
+
+随后展示：
+
+```text
+选择 Skill
+↓
+调用 Agent
+↓
+通过 MCP Bridge 使用外部 Tool
+↓
+生成整理后的 Markdown
+```
+
+Markdown 中展示：
+
+```text
+普通文本
+数学公式
+Mermaid 图
+函数图像
+```
+
+最后：
+
+```text
+Markdown
+├── Export HTML
+├── Export PDF
+└── Export DOCX
+```
+
+并切换一个导入的 Community Theme。
+
+---
+
+## 九、Definition of Done
+
+### 范涵宇
+
+- [ ] faster-whisper 能完成真实音频转写；
+- [ ] pyannote.audio 能生成说话人分段；
+- [ ] 两者能组合生成带时间戳和 Speaker 的 Transcript；
+- [ ] MCP Server 能通过 MCP Bridge 注册 Tool；
+- [ ] Agent 能调用 MCP Tool；
+- [ ] Plugin Command Contribution 后端可注册；
+- [ ] Plugin Settings Contribution 后端可解析；
+- [ ] Provider Adapter 的 Streaming / Tool Calling / Error Mapping 稳定；
+- [ ] 完成跨模块接口审阅和第二阶段集成。
+
+### 杨星萱
+
+- [ ] RAG Benchmark Dataset 可以稳定运行；
+- [ ] 能输出 Hit@K、Recall@K、MRR、Latency 等指标；
+- [ ] Agent Benchmark Framework 可以执行标准 Case；
+- [ ] Markdown 可以导出 HTML；
+- [ ] Markdown 可以导出 PDF；
+- [ ] Markdown 可以导出 DOCX；
+- [ ] Mermaid 在导出链路中可以保留为静态图；
+- [ ] 函数图像能够由结构化表达生成；
+- [ ] 函数图像能够进入预览和导出链路；
+- [ ] Retrieval 调优结果有 Benchmark 数据支撑。
+
+### 吉海燕
+
+- [ ] Theme Package 可以导入；
+- [ ] Theme Manifest 可以校验；
+- [ ] Theme 可以启用、停用和卸载；
+- [ ] Agent Trace 可以展示完整 Tool Call 顺序；
+- [ ] Trace Node 可以查看参数、结果、耗时和错误；
+- [ ] Plugin Command 可以显示在前端；
+- [ ] Plugin Settings 可以动态生成设置项；
+- [ ] Markdown Mermaid Code Block 可以渲染；
+- [ ] Mermaid 支持主题切换；
+- [ ] Mermaid 渲染错误可以明确展示；
+- [ ] Mermaid 图能够提供给 Export Service。
+
+---
+
+## 十、分工摘要
+
+```text
+范涵宇
+├── faster-whisper
+├── pyannote.audio
+├── MCP Bridge
+├── Plugin Command Runtime
+├── Plugin Settings Runtime
+├── Provider Adapter
+├── Code Review
+└── Integration / Coordination
+
+杨星萱
+├── RAG Benchmark
+├── Agent Benchmark Infrastructure
+├── Retrieval Optimization
+├── Export Service
+│   ├── Markdown → HTML
+│   ├── Markdown → PDF
+│   └── Markdown → DOCX
+└── Function Plot
+    ├── Expression / Data Model
+    ├── Rendering
+    └── Export Integration
+
+吉海燕
+├── Theme Import
+├── Theme Community Format
+├── Agent Trace Visualization
+├── Plugin Command UI
+├── Plugin Settings UI
+└── Mermaid
+    ├── Markdown Rendering
+    ├── Theme Adaptation
+    └── Export Rendering Interface
+```