ShaoHua
4fe0b5a963
本次提交完成了项目核心基础架构升级： 1. 新增动态API中间件与权限控制系统，支持匿名/鉴权接口分离 2. 搭建云同步服务体系，包含认证、任务同步、安全策略等核心模块 3. 实现语音控制全链路，从STT/意图解析到命令执行 4. 新增任务类型、附件实体与相关仓储接口 5. 重构前端配置与代理规则，统一后端端口为5057 6. 新增多平台测试项目与CI脚本优化 7. 完善项目文档与代码注释规范 移除了旧版迁移文件与冗余代理配置，调整项目结构适配跨平台部署需求。
208 lines
9.6 KiB
Markdown
208 lines
9.6 KiB
Markdown
# 研发工单 v1.3.0 - 总览
|
||
|
||
> 术语澄清：本文件中"研发工单"指智能体/开发者执行的**编码工作项**，与业务侧的 Todo 待办项无关。详见 [.trae/rules/全局/05-研发工单规则.md](../../../.trae/rules/全局/05-研发工单规则.md)。
|
||
|
||
---
|
||
|
||
## 一、背景与目标
|
||
|
||
Hua.Todo v1.3.0 版本聚焦于三个核心能力的升级：
|
||
|
||
| 序号 | 能力 | 描述 |
|
||
|---|---|---|
|
||
| 1 | **MCP 服务映射** | 将现有 HTTP 服务转换为 MCP（Model Context Protocol）服务，提升服务调用效率与可扩展性 |
|
||
| 2 | **语音控制与 AI 辅助** | 通过语音指令操作 Todo 待办项（CRUD + 子任务），通过 LLM 提供 AI 辅助任务拆分建议 |
|
||
| 3 | **会议任务拆分** | 以"会议"为入口记录会议内容（录音/文字），通过 AI 分析自动生成待办项拆分建议，用户确认后批量创建 |
|
||
|
||
---
|
||
|
||
## 二、工单拆分
|
||
|
||
### 2.1 并行工单（可同步执行）
|
||
|
||
| 工单编号 | 标题 | 负责人 | 状态 |
|
||
|---|---|---|---|---|---|---|
|
||
| 01 | HTTP 服务转换为 MCP 服务 | - | 已完成 |
|
||
| 02 | 语音控制与 AI 辅助 | - | 已完成 |
|
||
| 03 | 会议任务拆分 | - | 待开始 |
|
||
| 04 | 富文本描述、附件与外部链接 | - | 已完成 |
|
||
|
||
### 2.2 03 子工单拆分
|
||
|
||
| 子工单 | 标题 | 依赖 | 状态 |
|
||
|---|---|---|---|
|
||
| 03-01 | 会议数据模型与 API | 无 | 待开始 |
|
||
| 03-02 | 音频录制与转写 | 03-01 | 待开始 |
|
||
| 03-03 | AI 任务拆分服务 | 03-01、工单 02 LlmClientService | 待开始 |
|
||
| 03-04 | 任务建议与确认 UI | 03-01、03-03 | 已完成 |
|
||
|
||
### 2.3 串行工单（依赖前置工单完成）
|
||
|
||
当前版本暂无串行工单依赖。
|
||
|
||
---
|
||
|
||
## 三、各子工单摘要
|
||
|
||
### 3.1 工单 01 - HTTP 服务转换为 MCP 服务
|
||
|
||
**目标**：基于 C# 现有映射框架，将 Hua.Todo 的 HTTP API 转换为 MCP 服务
|
||
|
||
**核心需求**：
|
||
- 将现有的 HTTP API 端点映射为 MCP 工具描述符
|
||
- 生成符合 MCP 规范的契约文档
|
||
- 验证 MCP 服务的可用性与正确性
|
||
|
||
**验收标准**：
|
||
- MCP 服务可正常对外提供接口
|
||
- 所有原有 HTTP API 功能在 MCP 服务中可正常使用
|
||
|
||
### 3.2 工单 02 - 语音控制与 AI 辅助
|
||
|
||
**目标**：实现语音控制 Todo 待办项能力与 AI 辅助任务拆分功能
|
||
|
||
**核心需求**：
|
||
- 语音输入（STT）：平台原生语音识别 → 文字
|
||
- 语音播报（TTS）：执行结果语音反馈
|
||
- 语音指令解析与执行（CRUD + 子任务 + 歧义处理）
|
||
- AI 辅助任务拆分（LLM 生成子任务建议，用户确认后批量创建）
|
||
|
||
**不包含**：
|
||
- 语音通话功能（场景不明确，本期不做）
|
||
|
||
**验收标准**：
|
||
- 各平台 STT/TTS 可正常工作
|
||
- 语音指令可准确执行 Todo 业务操作
|
||
- 歧义场景返回候选列表而非直接执行
|
||
- AI 拆分建议需用户确认后才创建子任务
|
||
|
||
### 3.3 工单 03 - 会议任务拆分
|
||
|
||
**目标**：以"会议"为入口，通过录音/文字记录会议内容，AI 自动提取行动项生成待办项建议
|
||
|
||
**核心需求**：
|
||
- 新增"会议"类型标记（TaskType.Meeting）
|
||
- 录音：前端 MediaRecorder → 后端 STT 转写
|
||
- 文字：直接输入/粘贴会议纪要
|
||
- AI 会议拆分（LLM 分析会议内容 → 待办项建议列表）
|
||
- 建议审阅与确认 UI（勾选、编辑、批量创建子任务）
|
||
|
||
**不包含**：
|
||
- 实时语音转写（本期不做）
|
||
- 音频持久存储（转写完成后删除音频）
|
||
|
||
**验收标准**：
|
||
- 可通过"会议"类型创建待办项，显示会议图标
|
||
- 录音可正常录制并提交转写
|
||
- 文字纪要可保存/编辑
|
||
- AI 拆分返回 3-10 条结构化建议，含优先级和原因
|
||
- 用户可审阅、勾选、编辑建议后批量创建为子任务
|
||
- 离线模式拒绝 AI 拆分（提示降级）
|
||
|
||
### 3.4 工单 04 - 富文本描述、附件与外部链接
|
||
|
||
**目标**：为 Todo 待办项新增多行描述、文件附件管理与外部程序/链接启动能力（仅桌面端）
|
||
|
||
**核心需求**：
|
||
- `TaskEntity` 新增 `Description` 多行描述字段
|
||
- 新增 `AttachmentEntity` 数据模型，支持本地文件上传、下载、删除
|
||
- 支持外部链接（URL）作为附件，点击在默认浏览器打开
|
||
- 桌面端通过系统关联程序打开本地附件（`Process.Start` / `xdg-open`）
|
||
- 前端编辑对话框扩展描述 textarea + 附件管理区域
|
||
|
||
**不包含**：
|
||
- 移动端附件管理（本期仅 Windows/Linux 桌面端）
|
||
- 附件云同步（后续版本规划）
|
||
- 附件预览（如图片缩略图，本期不做）
|
||
- 富文本编辑器（本期仅纯文本）
|
||
|
||
**验收标准**：
|
||
- 描述字段可正常编辑和保存
|
||
- 附件可上传、下载、删除，文件完整性校验
|
||
- 外部链接可添加并在浏览器中打开
|
||
- 本地附件可通过系统关联程序打开
|
||
- 附件数量（20个）和大小（50MB）限制生效
|
||
|
||
---
|
||
|
||
## 四、待验证表
|
||
|
||
| 子工单 | 验证项 | 状态 | 备注 |
|
||
|---|---|---|---|
|
||
| 01 | MCP 服务契约文档生成 | 已验证 | 动态工具自动生成，工具名/描述/参数 schema 均已覆盖 |
|
||
| 01 | MCP 服务可用性测试 | 已验证 | 17 个单元测试全部通过（含工具调用端到端验证） |
|
||
| 01 | 原有 API 功能兼容性 | 已验证 | 所有 ITaskService 方法均生成 MCP 工具，覆盖 CRUD 全部 9 个 API |
|
||
| 01 | CloudSync MCP 工具 | 已知缺口 | CloudSync 服务未实现 IDynamicApiService，需手动映射或重构 |
|
||
| 02 | STT/TTS 平台适配 | 待验证 | Windows 优先，其他平台后续 |
|
||
| 02 | 语音指令识别准确率 | 待验证 | - |
|
||
| 02 | 歧义处理正确性 | 待验证 | - |
|
||
| 02 | AI 拆分建议质量 | 待验证 | - |
|
||
| 02 | Todo 业务操作覆盖度 | 待验证 | CRUD + 子任务 + 取消完成 |
|
||
| 03 | 会议数据模型迁移 | 待验证 | TaskType 字段 + DB 迁移 |
|
||
| 03 | 录音与转写链路 | 待验证 | 录制 → 上传 → 转写 → 保存 |
|
||
| 03 | AI 会议拆分质量 | 待验证 | 建议含标题+优先级+原因 |
|
||
| 03 | 建议审阅与批量创建 | 待验证 | MeetingBreakdownDialog 已实现：勾选/编辑/确认后创建子任务 |
|
||
| 04 | 描述字段编辑与保存 | 待验证 | - |
|
||
| 04 | 附件上传/下载/删除 | 待验证 | - |
|
||
| 04 | 外部链接添加与打开 | 待验证 | - |
|
||
| 04 | 本地文件通过系统程序打开 | 待验证 | Process.Start / xdg-open |
|
||
| 04 | 附件数量/大小限制 | 待验证 | 20 个 / 50MB |
|
||
| 04 | 待办项删除时附件级联清理 | 待验证 | - |
|
||
| 04 | 跨平台编辑安全（移动端不覆盖描述/附件） | 待验证 | 桌面设值 → 移动端改标题 → 桌面验证不丢失 |
|
||
|
||
---
|
||
|
||
## 五、关键决策
|
||
|
||
| 决策点 | 结论 |
|
||
|---|---|
|
||
| MCP 框架选择 | 使用 TRAE 平台内置的 MCP 服务框架 |
|
||
| STT/TTS 分层 | 接口在 Core，实现在各平台目录（同全局快捷键模式） |
|
||
| 语音指令解析 | A+C 混合方案：在线走 LLM 意图解析（LlmIntentParser），离线降级到规则匹配（RuleIntentParser），双策略通过 HybridVoiceIntentParser 自动切换 |
|
||
| 歧义处理策略 | 目标不唯一时返回候选列表；LLM confidence < 0.8 时触发确认；confidence < 0.5 按 UNKNOWN 处理 |
|
||
| AI 拆分安全性 | LLM 调用在 Host 端，建议需用户确认后才创建 |
|
||
| LLM 复用 | 意图解析与 AI 拆分共用同一 LLM 基础设施（LlmClientService） |
|
||
| 语音通话 | 本期不做，场景不明确 |
|
||
| 会议类型 | 新增 `TaskType` 枚举区分普通待办项与会议，会议有专属录音/纪要/拆分 UI |
|
||
| 录音存储 | 转写完成后删除原始音频文件，节省空间 |
|
||
| 音频转写 | 优先服务端 Whisper API；后续补各平台原生 STT |
|
||
| LLM 拆分 prompt | 会议专用 prompt，侧重"提取行动项"，输出优先级+原因 |
|
||
| 工单 02 复用 | `LlmClientService` 直接复用；会议拆分 prompt 独立于语音意图解析 |
|
||
| 多入口覆盖规则 | 后续每项新增功能必须在需求阶段确认 UI 入口 + 语音控制入口覆盖情况，详见 [05-多入口功能同步规范.md](../../../.trae/rules/项目/05-多入口功能同步规范.md) |
|
||
| 附件存储策略 | 附件存储在应用数据目录 `Attachments/` 子目录；外部链接不复制文件仅存 URL；单文件 50MB / 每待办项 20 个上限 |
|
||
| 外部程序启动 | 通过 `IPlatformAttachmentOpener` 接口实现平台差异：Windows 用 `Process.Start`，Linux 用 `xdg-open` |
|
||
| 工单 04 与 03 共享文件 | `TaskEntity.cs`、`TodoDbContext.cs`、`task.ts`、`TaskEditDialog.vue` 为共享文件，工单 03 先写入，04 后续追加 |
|
||
|
||
---
|
||
|
||
## 六、依赖与前置条件
|
||
|
||
| 依赖项 | 状态 | 来源 |
|
||
|---|---|---|
|
||
| TRAE MCP SDK | 已就绪 | 平台内置 |
|
||
| 各平台原生 STT/TTS API | 已就绪 | 平台内置 |
|
||
| Hua.Todo v1.2.0 | 已完成 | 上一版本 |
|
||
| LLM API（AI 拆分） | 待确认 | Host 端调用 |
|
||
| 浏览器 MediaRecorder API | 已就绪 | 前端录音 |
|
||
| 工单 02 LlmClientService | 待实现 | 会议拆分复用 |
|
||
|
||
---
|
||
|
||
## 七、风险与回滚
|
||
|
||
| 风险 | 影响 | 应对策略 |
|
||
|---|---|---|
|
||
| MCP 服务注册失败 | 无法对外提供服务 | 保留 HTTP API 作为降级方案 |
|
||
| 平台 STT 识别准确率不足 | 用户体验下降 | 提供文字输入作为备选方案 |
|
||
| Linux STT 可用性差 | Linux 语音控制不可用 | Web Speech API 降级；或 `vosk` 离线模型 |
|
||
| LLM API 不稳定 | AI 拆分功能不可用 | 功能降级，语音指令其他部分不受影响 |
|
||
| 会议录音文件过大 | 上传超时/存储压力 | 前端限制最长 2 小时；压缩音频格式 |
|
||
| 浏览器 MediaRecorder 兼容性 | 部分平台录音不可用 | 降级提示使用文字输入 |
|
||
| STT 转写准确率不足 | 会议纪要质量差 | 转写后支持用户编辑修正 |
|
||
|
||
---
|
||
|
||
**创建日期**：2026-06-15
|
||
**修订日期**：2026-06-16
|
||
**版本**：v1.3.0
|