Hua/Hua.Todo
1
0
Fork 0
Code Issues Wiki Activity

feat(mcp): 新增 MCP 服务基础设施，重构规则文件序号，新增 v1.3.0 工单文档

Browse Source 
- 规则重组：全局/ 下 8 个规则合并为 6 个（01+02→01，05+06→04），序号顺延

- 新增项目规则 05-多入口功能同步规范（UI/语音入口覆盖检查）

- 新增 MCP 服务基础设施：Mcp/ 目录（DI 注册、端点扩展、动态工具描述符）、单元测试

- v1.3.0 工单文档：03 系列（会议任务拆分）、04（富文本描述与附件管理）

- MCP 接口与前端集成指南：docs/manual/08、09
This commit is contained in:
ShaoHua
2026-06-16 01:15:40 +08:00
parent aacc56e952
commit 9223ceca50
30 changed files with 3907 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.trae/rules/全局/01-智能体记忆.md → .trae/rules/全局/01-记忆与存储规范.md
+39 -10
View File
@@ -1,17 +1,46 @@
# 智能体记忆与规范同步规则（必须遵守）
# 智能体记忆与存储规范（必须遵守）
> 适用范围：本规则属于 **全局规则**（语义层面跨项目可复用），关注智能体如何维护记忆与同步规范，与具体项目业务无关。
> 适用范围：本规则属于 **全局规则**（语义层面跨项目可复用），关注智能体如何维护记忆、存储与同步规范，与具体项目业务无关。
>
> `.trae/` 整体目录结构与各子目录职责见 [.trae/索引.md](../../索引.md)，本文件不再重复描述。
## 记忆存储
## 一、记忆存储
### 1.1 存储位置与组织
- 智能体的记忆必须存放在 `.trae/memory` 文件夹中
- 记忆应按对话日期或主题进行组织，便于后续查询和参考
- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息
- **项目即时状态**（当前实现到哪一步、未完结事项、临时决策快照）应同步写入 `.trae/rules/项目/04-即时状态记忆.md`，便于其他智能体或开发者快速对齐
## 规范同步
### 1.2 内容规范
- 记忆文件应保持简洁明了，重点记录重要的开发决策和规范变更
- 避免存储冗余信息，只记录对项目有价值的内容
- 定期清理过时的记忆文件，保持存储空间的合理使用
### 1.3 与"项目即时状态"的边界
- `.trae/memory/` 偏向**长期保留**的对话产物与决策记录
- `.trae/rules/项目/04-即时状态记忆.md` 偏向**当前快照**（实现进度、未完结事项），更新频率高
- 二者不要重复存放同一份信息；以"是否需要长期沉淀"为判定标准
### 1.4 memory/ 生命周期
研发工单验收完成后，对 `memory/` 的处理遵循以下原则：
- **追加而非覆盖**：将本次工单中产生的、值得**长期沉淀**的内容（架构决策、关键避坑经验、引入的新依赖与版本）追加到对应文件
- **不存放过程信息**：实现进度、待办勾选、临时决策这些短期信息应留在 [04-即时状态记忆.md](../项目/04-即时状态记忆.md)，不进 `memory/`
- **不删长期内容**：除非内容已被证伪或过时，否则不删除既有条目；过时内容用"已废弃 / 已被 XX 取代"的形式保留语义而非物理删除
- **新增文件序号化**：当主题足够独立时新建 `NN-名称.md`（序号紧接当前最大值），并在 [.trae/索引.md](../../索引.md) 的 `memory/` 章节同步追加链接
### 1.5 访问权限
- 记忆文件仅供开发团队内部参考使用
- 确保记忆文件中的敏感信息得到适当保护
- 遵循项目的版本控制和代码管理规范
## 二、规范同步
- 每次对话中涉及到的语法或规范相关内容，必须同步整理到 `.trae/rules` 目录下的对应文件中
- **通用规范**（注释、文档同步、工单流程、并行冲突）→ 写入 `.trae/rules/全局/`
@@ -19,11 +48,11 @@
- 若涉及到新的规范或规则，应创建新的规则文件进行记录
- 规范同步应及时、准确，确保规则文件能真实反映当前项目的编码规范和最佳实践
## 文件命名规则（强制）
## 三、文件命名规则（强制）
`.trae/` 下所有子目录中**新增的文件必须沿用 `NN-名称.md` 序号格式**，否则视为不合规：
- **格式**：两位数字 + 连字符 + 中文/英文名称 + `.md`，例如 `08-XXX规范.md`
- **格式**：两位数字 + 连字符 + 中文/英文名称 + `.md`，例如 `06-XXX规范.md`
- **序号取值**：紧接当前目录已有最大序号 +1，不得跳号、不得重复
- **入口/索引文件例外**：`.trae/索引.md` 这类目录入口文件不带序号
- **重排禁止**：除非整体重构，否则不得重排已有文件的序号；新增只能追加在末尾
@@ -34,18 +63,18 @@
| 子目录 | 当前最大序号 | 下一个可用 |
|---|---|---|
| `rules/全局/` | 08 | 09 |
| `rules/项目/` | 04 | 05 |
| `rules/全局/` | 06 | 07 |
| `rules/项目/` | 05 | 06 |
| `memory/` | 01 | 02 |
| `coordination/` | 02 | 03 |
## 实现要求
## 四、实现要求
- 智能体应定期检查并更新规则文件，确保其与项目实际情况保持一致
- 当发现规范冲突或需要调整时，应及时记录并通知相关人员
- 记忆存储和规范同步应作为智能体的核心功能，贯穿于整个开发过程
## 路径规范
## 五、路径规范
- 所有 Markdown 文档中不应使用绝对路径，应使用相对路径
- 相对路径应以项目根目录为基准，例如 `.trae/memory` 而非绝对路径
.trae/rules/全局/03-注释规范.md → .trae/rules/全局/02-注释规范.md
View File
.trae/rules/全局/02-记忆存储规范.md
-33
View File
@@ -1,33 +0,0 @@
# 记忆存储规范
> 适用范围：本规则属于 **全局规则**（跨项目通用），约束 `.trae/memory/` 的使用方式。
## 存储结构
- 记忆文件应存放在 `.trae/memory` 文件夹中
- 避免使用与日期相关的文件名，使用通用的描述性文件名
- 文件命名采用 `NN-名称.md` 序号格式
- 记忆内容应包含对话历史、关键决策、重要代码片段和规范调整等信息
## 内容规范
- 记忆文件应保持简洁明了，重点记录重要的开发决策和规范变更
- 避免存储冗余信息，只记录对项目有价值的内容
- 定期清理过时的记忆文件，保持存储空间的合理使用
## 与"项目即时状态"的边界
- `.trae/memory/` 偏向**长期保留**的对话产物与决策记录
- `.trae/rules/项目/04-即时状态记忆.md` 偏向**当前快照**（实现进度、未完结事项），更新频率高
- 二者不要重复存放同一份信息；以"是否需要长期沉淀"为判定标准
## memory/ 生命周期
研发工单验收完成后，对 `memory/` 的处理遵循以下原则：
- **追加而非覆盖**：将本次工单中产生的、值得**长期沉淀**的内容（架构决策、关键避坑经验、引入的新依赖与版本）追加到对应文件
- **不存放过程信息**：实现进度、待办勾选、临时决策这些短期信息应留在 [04-即时状态记忆.md](../项目/04-即时状态记忆.md)，不进 `memory/`
- **不删长期内容**：除非内容已被证伪或过时，否则不删除既有条目；过时内容用"已废弃 / 已被 XX 取代"的形式保留语义而非物理删除
- **新增文件序号化**：当主题足够独立时新建 `NN-名称.md`（序号紧接当前最大值），并在 [.trae/索引.md](../../索引.md) 的 `memory/` 章节同步追加链接
## 访问权限
- 记忆文件仅供开发团队内部参考使用
- 确保记忆文件中的敏感信息得到适当保护
- 遵循项目的版本控制和代码管理规范
.trae/rules/全局/04-文档同步规范.md → .trae/rules/全局/03-文档同步规范.md
+1 -1
View File
@@ -14,7 +14,7 @@ description: 强制文档同步规范：每次变更代码（如新增功能、
- **准确性**：确保文档中的示例代码、接口说明、安装步骤与实际代码完全一致。
- **协作友好（局部修改）**：当并行处理多个研发工单/需求时，更新文档应尽量只修改与本工单直接相关的段落/小节，避免对不相关内容做无意义的重排、改写或格式化；如必须调整非关联内容，应拆分为独立的变更说明清楚原因与影响范围。
> 术语澄清：本规范中"研发工单"指编码工作项；项目业务里的"任务/Todo 待办项"是用户域实体，二者不要混淆。详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 术语澄清：本规范中"研发工单"指编码工作项；项目业务里的"任务/Todo 待办项"是用户域实体，二者不要混淆。详见 [04-研发工单全流程规范.md](./04-研发工单全流程规范.md)。
## 更新范围
.trae/rules/全局/04-研发工单全流程规范.md
+141
View File
@@ -0,0 +1,141 @@
# 研发工单全流程规范（必须遵守）
> 适用范围：本规则属于 **全局规则**（跨项目通用），覆盖研发工单从术语定义、拆分输出到新增约束的全流程。
> ⚠️ 术语澄清（必读）
>
> 本项目存在两类"任务"概念，必须严格区分：
>
> | 术语 | 含义 | 适用范围 |
> |---|---|---|
> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的**编码工作项** | 本规则的全部内容 |
> | **Todo 待办项（Todo Item）** | Hua.Todo 项目**业务领域**中用户创建的待办事项 | 业务代码、产品文档 |
>
> 在代码、文档与对话中，凡涉及编码侧拆分时，**必须使用"研发工单"或"工单"**，禁止使用"任务"二字。
> 业务侧 `Task` / `SubTask` 等代码标识符**保持不变**（已固化于 API、DB、UI）。
---
## 一、研发工单拆分规范
### 1.1 适用时机
- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出**研发工单拆分文档**
### 1.2 输出要求
1. **先读完所有相关文档**：包括 `docs/`、`docs/project/` 下与本次需求相关的内容
2. **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据
3. **新增专属文件夹**：在 `docs/project` 下新建 `研发工单-<主题>-<日期或版本>` 文件夹
4. **可并行工单拆分**：能同步执行的工单必须拆到不同 Markdown 文件中
5. **文件带序号**：按执行顺序编号（`01-xxx.md`、`02-xxx.md`）
### 1.3 每个研发工单文件必须包含
- 目标 / 范围（做什么、不做什么）
- 前置条件（依赖哪些结论 / 接口 / 文档）
- 验收标准（可执行的验证点）
- 风险与回滚（如有）
### 1.4 子工单完成标记要求
- 子工单完成后，必须在 `00-工单总览.md` 中标注"已完成"
- 维护"待验证表"，记录每个子工单的"待验证 / 已验证"状态
### 1.5 并行冲突规避要求
当工单会被分发到多个 solo 窗口并行推进时，每个研发工单文件必须额外包含 Touch List、共享文件策略与编译绿线策略。详细规约见 [05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)。
### 1.6 推荐结构
```
docs/project/研发工单-<主题>-<版本>/
├── 00-工单总览.md # 背景、目标、关键决策、并行分组、待验证表
├── 01-并行工单A.md
├── 02-并行工单B.md
└── 03-串行工单C.md
```
---
## 二、新增工单约束
> 核心原则：**新增工单时，不得修改、覆盖、重排、删除任何已有工单文件。**
### 2.1 已有文件不可触碰
| 操作 | 是否允许 | 说明 |
|---|---|---|
| 修改已有工单的 `.md` 内容 | ❌ 禁止 | 即使发现格式、措辞可优化 |
| 重命名已有工单文件 | ❌ 禁止 | |
| 删除已有工单文件 | ❌ 禁止 | |
| 重排已有工单的序号 | ❌ 禁止 | 除非用户明确要求整体重构 |
| 修改 `00-工单总览.md` 中已有条目 | ❌ 禁止 | 只能追加新条目 |
| 在 `00-工单总览.md` 中追加新条目 | ✅ 允许 | |
| 修改 `.trae/rules/项目/04-即时状态记忆.md` 中已有快照行 | ❌ 禁止 | 只能追加新版本行 |
| 新增章节到 `04-即时状态记忆.md` | ✅ 允许 | |
### 2.2 子工单拆分格式
```
NN-NN-标题.md
```
- 前两位：主工单序号，后两位：子工单序号
- 示例：`03-01-会议数据模型与API.md`
### 2.3 新增工单的序号确定
1. 列出目标文件夹中已有文件
2. 找出最大主序号
3. 新增工单的主序号 = 最大主序号 + 1
4. 子工单的子序号从 `01` 开始递增
### 2.4 可追加修改的文件（例外）
| 文件 | 允许 | 不允许 |
|---|---|---|
| `00-工单总览.md` | 追加新条目 | 改写已有条目 |
| `.trae/rules/项目/04-即时状态记忆.md` | 新增版本章节 | 修改已有快照行 |
| `.trae/索引.md` | 追加新规则链接 | 修改已有条目 |
---
## 三、与业务侧 Todo 待办项的边界
- 代码、注释、提交信息中描述**编码工作**时：使用"研发工单 / 工单 / 子工单"
- 代码、注释、提交信息中描述**业务功能**时：使用"Todo 待办项 / Todo Item / 父子任务（业务实体）"
- 文档命名前缀：
- 编码侧：`研发工单-<主题>-<版本>/`
- 业务侧：遵循 `docs/` 既有命名习惯
- 提交信息示例：
- ✅ `feat(todo): 新增 Todo 待办项截止日期字段（研发工单 02-后端模型）`
- ❌ `feat: 完成任务 02`（"任务"歧义）
---
## 四、检查清单
### 研发工单拆分检查
1. [ ] 是否已阅读完所有相关文档？
2. [ ] 是否在 `docs/project` 下新建了专属文件夹（命名以"研发工单-"开头）？
3. [ ] 是否产出 `00-工单总览.md`？
4. [ ] 是否将可并行工单拆分为不同 md 文件？
5. [ ] 是否所有 md 文件都带有连续序号？
6. [ ] 子工单完成后是否在总览中标注"已完成"并更新待验证表？
### 新增工单检查
1. [ ] 新增工单的序号是否为当前最大主序号 + 1？
2. [ ] 子工单是否使用了 `NN-NN-标题.md` 格式？
3. [ ] 是否**未修改**任何已有工单文件的内容？
4. [ ] 是否**未修改** `00-工单总览.md` 和 `04-即时状态记忆.md` 中已有条目？
### 并行冲突检查
> 详见 [05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md#最小检查清单)。
---
**关联规则**：[05-并行窗口冲突规约.md](./05-并行窗口冲突规约.md)
.trae/rules/全局/07-并行窗口冲突规约.md → .trae/rules/全局/05-并行窗口冲突规约.md
+1 -1
View File
@@ -7,7 +7,7 @@ description:
> 适用范围：本规则属于 **全局规则**（跨项目通用）。
> ⚠️ 术语澄清：本规范中的「研发工单（Dev Work Item）」专指智能体 / 开发者执行的**编码工作项**，与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。
> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 详见 [04-研发工单全流程规范.md](./04-研发工单全流程规范.md)。
> 凡涉及编码侧拆分时，**必须使用「研发工单」或「工单」**，禁止使用「任务」二字以避免与 Todo 待办项混淆。
## 适用范围
.trae/rules/全局/05-研发工单规则.md
-129
View File
@@ -1,129 +0,0 @@
# 研发工单同步规则汇总（Dev Work Item Rules）
> 适用范围：本规则属于 **全局规则**（跨项目通用），关注智能体如何拆分编码工作。
> ⚠️ 术语澄清（必读）
>
> 本项目存在两类"任务"概念，必须严格区分，避免命名混淆：
>
> | 术语 | 含义 | 适用范围 |
> |---|---|---|
> | **研发工单（Dev Work Item）** | 智能体 / 开发者执行的**编码工作项**（拆分需求、并行开发、集成等） | 本规则文档的全部内容 |
> | **Todo 待办项（Todo Item）** | Hua.Todo 项目**业务领域**中用户创建的待办事项（数据库实体、API 资源、UI 列表项） | 业务代码、产品需求文档、技术设计文档 |
>
> 本文档中所有"研发工单 / 工单 / 子工单"均指**编码工作项**，与业务侧的 Todo 待办项无关。
> 在代码、文档与对话中，凡涉及编码侧拆分时，**必须使用"研发工单"或"工单"**，禁止再使用"任务"二字以避免与 Todo 待办项混淆。
>
> 业务侧由于历史原因仍保留 `Task` / `SubTask` 等代码标识符（API、实体、UI），这些属于 Todo 待办项语义，**不在本规范替换范围内**。
>
> 本汇总文件是 [06-研发工单拆分规范.md](./06-研发工单拆分规范.md) 与 [07-并行窗口冲突规约.md](./07-并行窗口冲突规约.md) 的对外索引，详细规则以这两份源文件为准。
---
## 一、研发工单拆分规范
### 适用时机
- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出**研发工单拆分文档**
### 输出要求
1. **先读完所有相关文档**：包括 `docs/`、`docs/project/` 下与本次需求相关的内容
2. **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据
3. **新增专属文件夹**：在 `docs/project` 下新建 `研发工单-<主题>-<日期或版本>` 文件夹
4. **可并行工单拆分**：能同步执行的工单必须拆到不同 Markdown 文件中
5. **文件带序号**：按执行顺序编号（`01-xxx.md`、`02-xxx.md`）
### 每个研发工单文件必须包含
- 目标 / 范围（做什么、不做什么）
- 前置条件（依赖哪些结论 / 接口 / 文档）
- 验收标准（可执行的验证点）
- 风险与回滚（如有）
### 子工单完成标记要求
- 子工单完成后，必须在 `00-工单总览.md` 中标注"已完成"
- 维护"待验证表"，记录每个子工单的"待验证 / 已验证"状态
---
## 二、并行窗口冲突规约
### 核心原则
1. **先声明后修改**：修改前先声明 Touch List 与共享文件策略
2. **文件所有权唯一**：同一时段内一个文件只能由一个窗口修改
3. **共享文件单点修改**：高耦合 / 共享入口的改动集中到集成窗口完成
4. **绿线优先**：任何可落盘的变更必须保持可编译
### Touch List 要求
- 精确到文件路径
- 标注修改类型（新增 / 小改 / 重构 / 接口变更 / 配置变更）
- 标注是否为共享文件
- 使用相对路径：`src\<module>\<file>`
### 共享文件判定标准（满足其一即为共享）
- 项目入口 / 启动逻辑、依赖注入注册、全局路由
- 公共配置、公共协议与 DTO、公共组件 / 样式
- 解决方案文件（`.sln`、`.csproj`）、锁文件、全局配置
### Writer 约束
- 非 Writer 窗口不得编辑共享文件
- 非 Writer 只能提供"差异建议"给 Writer 落盘
### 协调目录
固定目录：`.trae\coordination\`
- `01-ownership.md`：文件所有权登记表
- `02-shared-files.md`：共享文件清单（集成窗口维护）
- `handoff\`：差异建议 / 交接说明
- `wip\`：编译中途状态说明
### 编译绿线规则
- 不得提交破坏编译的变更
- 临时隔离手段（按优先级）：
1. 新功能先放在新文件中，不在入口路径启用
2. 通过显式开关控制，默认关闭
3. 通过依赖注入分支或特性开关隔离
- 接口演进采用"双写 / 兼容期"策略
---
## 三、推荐文档结构
```
docs/project/研发工单-<主题>-<版本>/
├── 00-工单总览.md # 背景、目标、关键决策、并行分组、待验证表
├── 01-并行工单A.md
├── 02-并行工单B.md
└── 03-串行工单C.md
```
> 注意：上述目录与文件名中的"工单"指**研发工单**，与业务侧 Todo 待办项无关。
---
## 四、检查清单
### 研发工单拆分检查
1. [ ] 是否已阅读完所有相关文档？
2. [ ] 是否在 `docs/project` 下新建了专属文件夹（命名以"研发工单-"开头）？
3. [ ] 是否产出 `00-工单总览.md`？
4. [ ] 是否将可并行工单拆分为不同 md 文件？
5. [ ] 是否所有 md 文件都带有连续序号？
6. [ ] 子工单完成后是否在总览中标注"已完成"并更新待验证表？
### 并行冲突检查
1. [ ] 每个研发工单 md 是否已写 Touch List（精确到文件）？
2. [ ] Touch List 中的共享文件是否指定了唯一 Writer？
3. [ ] 是否避免了对共享文件的无意义格式化 / 重排？
4. [ ] 当前改动是否保持可编译（绿线）？
5. [ ] 若涉及接口演进，是否采用兼容期策略？
---
## 五、与业务侧 Todo 待办项的边界
- 代码、注释、提交信息中描述**编码工作**时：使用"研发工单 / 工单 / 子工单"
- 代码、注释、提交信息中描述**业务功能**时：使用"Todo 待办项 / Todo Item / 父子任务（业务实体）"
- 文档命名前缀：
- 编码侧：`研发工单-<主题>-<版本>/`
- 业务侧（如有）：遵循 `docs/` 既有命名习惯，禁止使用"研发工单"前缀
- 提交信息示例：
- ✅ `feat(todo): 新增 Todo 待办项截止日期字段（研发工单 02-后端模型）`
- ❌ `feat: 完成任务 02`（"任务"歧义，禁用）
.trae/rules/全局/08-AI沟通记录规范.md → .trae/rules/全局/06-AI沟通记录规范.md
View File
.trae/rules/全局/06-研发工单拆分规范.md
-57
View File
@@ -1,57 +0,0 @@
---
alwaysApply: false
---
# 研发工单拆分输出规范（必须遵守）
> 适用范围：本规则属于 **全局规则**（跨项目通用）。
> ⚠️ 术语澄清：本规范中的「研发工单（Dev Work Item）」专指智能体 / 开发者执行的**编码工作项**，与 Hua.Todo 项目业务领域中的「Todo 待办项」是两个完全不同的概念。
> 详见 [05-研发工单规则.md](./05-研发工单规则.md)。
> 凡涉及编码侧拆分时，**必须使用「研发工单」或「工单」**，禁止使用「任务」二字以避免与 Todo 待办项混淆。
## 适用时机
- 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出研发工单拆分文档，再开始写代码或改配置。
## 输出要求
- **先读完所有相关文档**：包括但不限于 `docs/`、`docs/project/` 下与本次需求相关的内容。
- **先写工单拆分，再动手实现**：研发工单拆分产出是后续执行的入口与对齐依据。
- **新增一个专属文件夹**：在 `docs/project` 下新建一个文件夹存放本次研发工单拆分文档。
- 文件夹命名建议：`研发工单-<主题>-<日期或版本>`（保持可检索、避免与既有文档冲突）。
- **可并行的工单要拆成不同 md**：能同步执行（相互无依赖/弱依赖）的工单，必须拆到不同的 Markdown 文件中，便于并行推进与分工。
- **文件必须带序号**：同一文件夹下的 md 文件按执行顺序编号，序号从小到大。
- 文件名建议：`01-xxx.md`、`02-xxx.md`、`03-xxx.md`。
- **每个研发工单文件至少包含**：
- 目标/范围（做什么、不做什么）
- 前置条件（依赖哪些结论/接口/文档）
- 验收标准（怎么判断完成，包含可执行的验证点）
- 风险与回滚（如有）
- **子工单完成后的标记要求**：
- 当任一子工单（例如 `01-*`/`02-*`/`03-*`）完成实现后，必须在对应版本的 `00-工单总览.md` 中同步标注"已完成"。
- 同时必须维护一张"待验证表"（可用 Markdown 表格），对每个子工单给出"待验证/已验证"状态，避免实现完成但验收未闭环。
- **并行冲突规避要求**：当工单会被分发到多个 solo 窗口并行推进时，每个研发工单文件必须额外包含：
- 触碰文件清单（Touch List，精确到文件）
- 共享文件策略（哪些是共享文件、唯一 Writer 是谁、如何与集成窗口对接）
- 编译绿线策略（如何确保阶段性交付不破坏编译）
## 推荐结构（模板）
- `00-工单总览.md`
- 背景与目标
- 关键决策与约束
- 并行分组说明（哪些文件可同步做）
- 待验证表（每个子工单的"待验证/已验证"状态）
- `01-<并行工单A>.md`
- `02-<并行工单B>.md`
- `03-<串行工单C>.md`
## 最小检查清单
1. [ ] 是否确认已阅读完所有相关文档？
2. [ ] 是否在 `docs/project` 下新建了本次专属文件夹（命名以"研发工单-"开头）？
3. [ ] 是否产出 `00-工单总览.md`（或等价总览文件）？
4. [ ] 是否将可并行工单拆分为不同 md 文件？
5. [ ] 是否所有 md 文件都带有连续序号？
6. [ ] 并行工单是否为每个研发工单文件补充了 Touch List/共享文件策略/编译绿线策略？
7. [ ] 子工单完成后，是否在对应版本的 `00-工单总览.md` 标注"已完成"，并在"待验证表"里更新状态？
.trae/rules/项目/02-业务命名规范.md
+1 -1
View File
@@ -3,7 +3,7 @@
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
>
> 本文档规定 **业务实体**（Todo 待办项相关）与 **编码工作项**（研发工单）在代码、文档、提交信息中的命名边界。
> 全局术语规则参见 [.trae/rules/全局/05-研发工单规则.md](../全局/05-研发工单规则.md)。
> 全局术语规则参见 [.trae/rules/全局/04-研发工单全流程规范.md](../全局/04-研发工单全流程规范.md)。
## 一、术语对照（核心）
.trae/rules/项目/04-即时状态记忆.md
+19 -5
View File
@@ -11,8 +11,9 @@
## 一、当前活跃版本
- **进行中版本**：v1.2.0
- **研发工单总览**：[docs/project/研发工单-v1.2.0/00-工单总览.md](../../../docs/project/研发工单-v1.2.0/00-工单总览.md)
- **进行中版本**：v1.2.0（收尾中）、v1.3.0（规划中）
- **v1.2.0 研发工单总览**：[docs/project/研发工单-v1.2.0/00-工单总览.md](../../../docs/project/研发工单-v1.2.0/00-工单总览.md)
- **v1.3.0 研发工单总览**：[docs/project/研发工单-v1.3.0/00-工单总览.md](../../../docs/project/研发工单-v1.3.0/00-工单总览.md)
- **PRD**：[docs/project/产品需求文档-1.2.0.md](../../../docs/project/产品需求文档-1.2.0.md)
## 二、v1.2.0 工单状态快照
@@ -31,14 +32,27 @@
| 08 - cloud_sync 重构 | 已设计 | 待实现 | "同源 Host"方案，Vite proxy 补 `/auth` `/tasks` `/sync` `/security` `/cloud-sync` |
| 09 - CloudSync 同步策略改进 | 已实现 | 待验证 | TaskEntity 继承 ABP 基类；软删除修复（SaveChangesAsync）；前端类型和 cloudSync.ts 已更新；新增 guid.ts |
## 三、关键临时决策
## 三、v1.3.0 工单状态快照
| 子工单 | 实现状态 | 验证状态 | 简要说明 |
|---|---|---|---|
| 01 - HTTP 服务转换 MCP 服务 | 进行中 | 待验证 | 将现有 HTTP API 映射为 MCP 工具描述符 |
| 02 - 语音控制与 AI 辅助 | 待开始 | 待验证 | STT/TTS + 语音指令解析 + AI 辅助任务拆分 |
| 03 - 会议任务拆分 | 待开始 | 待验证 | 会议类型入口 + 录音/文字输入 + AI 拆分建议 + 确认批量创建 |
| 03-01 - 会议数据模型与 API | 待开始 | 待验证 | TaskType 枚举、MeetingNotes/AudioDuration 字段、MeetingController |
| 03-02 - 音频录制与转写 | 待开始 | 待验证 | 前端 MediaRecorder 录音 + 后端 STT 转写 |
| 03-03 - AI 任务拆分服务 | 待开始 | 待验证 | 会议专用 LLM prompt + 批量创建子任务 |
| 03-04 | 任务建议与确认 UI | 待开始 | 待验证 | 录音/纪要/审阅对话框 + Meeting 类型条件渲染 |
| 04 | 富文本描述、附件与外部链接 | 待开始 | 待验证 | 多行描述 + 附件上传下载删除 + 外部链接 + 桌面端 Process.Start/xdg-open |
## 四、关键临时决策
- **MAUI 端不暴露云同步端点**：`MauiProgram.cs` 仅注册 `AddApplicationServices()`，不调 `AddCloudSyncServer()`。云同步端点只在 `Hua.Todo.Host` 暴露。
- **本地用户 ID 固定为 `"local"`**：嵌入式模式下 `Tasks.UserId = TodoUserIds.LocalUserId`，与云端用户隔离逻辑共存而不冲突。
- **SQLite WAL 模式**：嵌入式宿主启动时强制开启 WAL，降低锁冲突。
- **数据库路径**：默认 `LocalApplicationData/Hua.Todo/Hua.Todo.db`（避免安装目录无写权限）；Host 模式使用 `src/Hua.Todo.Host/Hua.Todo.db`（开发/测试）。
## 四、已知未完结事项 / 待办
## 五、已知未完结事项 / 待办
- [ ] 06 客户端"内存模式"在 `allowPersist=false` 时的端到端落盘清理（含 token、同步队列）尚未充分验证
- [ ] 06.1 设计中的 Admin 管理后台前端（位于 `Hua.Todo.Host/wwwroot/admin/`）当前仅有 `index.html` 占位，需 Vue 3 + Vite 实现
@@ -46,7 +60,7 @@
- [ ] Linux Flatpak/AppImage 自包含产物在干净环境的实测验证（v1.2.0 验收 Linux 部分仍为"待验证"）
- [x] CloudSync UNIQUE 约束修复（2026-06-14）：修复了 `existingTasks` 查询在事务外导致并发重同步时 `T_Tasks.Id` UNIQUE 约束冲突；新增 7 个测试（含 5 个 SQLite 集成测试）
## 五、最近一次重大重构（如有）
## 六、最近一次重大重构（如有）
- **术语统一与目录中文化**（2026-06）：
- `.trae/rules/` 全部中文文件名 + 拆分为 `全局/` 和 `项目/` 两个子目录
.trae/rules/项目/05-多入口功能同步规范.md
+85
View File
@@ -0,0 +1,85 @@
# 多入口功能同步规范（Hua.Todo 专属）
> 适用范围：本规则属于 **项目规则**（仅 Hua.Todo 项目生效）。
---
## 一、背景
Hua.Todo 存在两个功能入口：
| 入口 | 位置 | 方式 |
|---|---|---|
| **UI 入口** | WebView / 前端界面（Hua.Todo.Web） | 键盘/鼠标/触控交互 |
| **语音控制入口** | 语音指令（平台原生 STT + LLM 意图解析） | 语音输入 → 指令执行 |
v1.3.0 之前，功能开发只关注 UI 入口。v1.3.0 工单 02 落地后语音控制入口正式就绪，此后**所有新增功能必须在需求阶段同步确认两个入口的覆盖情况**。
---
## 二、核心规则
### 2.1 功能入口检查（强制）
每次新增功能（含新工单、新特性），智能体必须在需求讨论或工单拆分阶段执行以下检查：
| 检查项 | 说明 |
|---|---|
| **UI 入口** | 当前功能是否已有 UI 入口规划？入口在哪个页面/组件？交互方式是什么？ |
| **语音控制入口** | 当前功能是否已有语音指令规划？对应哪个意图？参数是什么？LLM prompt 是否需要更新？ |
### 2.2 缺失时为通知用户，不自行决策
- 任一入口缺失时，**智能体必须主动告知用户**，由用户决定：
1. 本次就做（补上缺失入口）
2. 本次不做（记录为已知缺口，后续版本补）
3. 不需要（该入口不适合此功能，如选项过多需可视化交互的操作）
- **智能体不得在用户未确认的情况下自行跳过或自行补充入口设计**
### 2.3 输出格式（检查表）
智能体在需求讨论阶段，必须输出以下检查表：
```markdown
## 功能入口覆盖检查
| 入口 | 已规划 | 方案 |
|---|---|---|
| UI | ✅ / ❌ | [描述 UI 入口] |
| 语音 | ✅ / ❌ | [描述语音指令与意图] |
> 不可覆盖的入口说明：[如"语音控制暂不支持 XX 操作（原因）"]
```
---
## 三、适用场景
### 3.1 必须检查的场景
- 新增业务功能（如新增双因素认证、新增标签系统）
- 新增 API 端点（如新增导出/导入）
- 新增 UI 页面/组件（如新增设置页、新增弹窗）
- 新工单拆分阶段
### 3.2 无需检查的场景
- 纯 bug 修复
- 纯性能优化（不改变用户可感知功能）
- 纯基础设施调整（如 CI/CD、打包脚本）
- 依赖升级
---
## 四、检查清单
1. [ ] 本次新增功能是否已确认 UI 入口？
2. [ ] 本次新增功能是否已确认语音控制入口？
3. [ ] 缺失入口是否已通知用户并记录决策？
4. [ ] LLM intent parser 的 prompt 是否需要同步更新（新增意图/新增参数）？
---
## 五、与工单 02 的关系
本规范的语音入口覆盖检查表来源于 [docs/project/研发工单-v1.3.0/02-语音通话与语音控制.md](../../../docs/project/研发工单-v1.3.0/02-语音通话与语音控制.md) 的第七章"与其他工单的语音入口衔接"。