Kronecker/NotesAgentic
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 5 Wiki Activity

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

Browse Source
This commit is contained in:
admin
2026-09-01 09:55:40 +08:00
parent 49dbacb296
commit a5b709a46f
23 changed files with 263 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture/第二阶段团队分工表.md
+821
View File
@@ -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
```