From 2becaf0c65d81cf4a61b01f094caa00c4b5512c5 Mon Sep 17 00:00:00 2001
From: KiriAky 107 <KiriAky107@qq.com>
Date: Sun, 30 Aug 2026 23:00:11 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E4=BB=A3=E7=A0=81?=
 =?UTF-8?q?=E6=B3=A8=E9=87=8A=E4=B8=8ETODO=E7=BB=B4=E6=8A=A4=E7=BA=A6?=
 =?UTF-8?q?=E5=AE=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                  |  3 ++-
 docs/代码注释与TODO约定.md | 43 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 45 insertions(+), 1 deletion(-)
 create mode 100644 docs/代码注释与TODO约定.md

diff --git a/README.md b/README.md
index f83380c..0ec3f54 100644
--- a/README.md
+++ b/README.md
@@ -118,7 +118,7 @@ cd frontend
 pnpm test
 ```
 
-当前回归基线为后端 71 项测试、前端 14 项测试，且生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。
+当前回归基线为后端 71 项测试、前端 23 项测试，且生产构建通过。测试数量会随功能增长，以本地实际输出和 CI 为准。
 
 构建产物位于 `frontend/dist`，该目录不提交到 Git。
 
@@ -138,6 +138,7 @@ pnpm test
 | [前端写作体验](docs/前端写作体验优化开发说明.md) | Milkdown、CodeMirror、格式栏和 Shiki |
 | [前端视觉与轻量动效](docs/前端视觉与轻量动效优化开发说明.md) | Design Token、页面美化、性能边界与主题注入约定 |
 | [Git 使用细则](docs/Git使用细则-团队开发版.md) | 分支、提交、PR、Review 与合并流程 |
+| [代码注释与 TODO 约定](docs/代码注释与TODO约定.md) | 注释原则、TODO 格式、领域标签与当前待办索引 |
 | [后端审阅复盘](docs/后端全面审阅问题与修复复盘.md) | 后端问题原因、后果与修复方案 |
 | [Knowledge/Retrieval 复盘](docs/Knowledge与Retrieval-Core问题与修复复盘.md) | 检索与事务问题复盘 |
 | [前端审阅复盘](docs/前端合并审阅问题与修复复盘.md) | 前端工程、契约和交互问题复盘 |
diff --git a/docs/代码注释与TODO约定.md b/docs/代码注释与TODO约定.md
new file mode 100644
index 0000000..232dcb2
--- /dev/null
+++ b/docs/代码注释与TODO约定.md
@@ -0,0 +1,43 @@
+# 代码注释与 TODO 约定
+
+本文用于统一团队在前后端代码中编写注释和待办项的方式。注释应解释设计意图、边界条件和不明显的取舍，不重复代码本身已经清楚表达的内容。
+
+## 注释原则
+
+- 模块或核心类说明其职责和边界，例如 Agent 编排器、工具执行边界、凭据存储边界。
+- 异步流程说明顺序、快照、去重、回滚和竞态处理原因。
+- 安全相关流程说明默认拒绝、权限收敛、输入净化和凭据优先级。
+- 简单赋值、显然的条件判断、类型定义和展示模板不添加翻译式注释。
+- 注释随实现一并维护；实现变化后已经失真的注释应在同一提交中修改或删除。
+
+## TODO 格式
+
+前端使用：
+
+```ts
+// TODO(editor): 描述尚未完成的能力、完成条件或替换目标。
+```
+
+后端使用：
+
+```python
+# TODO(agent): 描述尚未完成的能力、完成条件或替换目标。
+```
+
+领域标签使用小写英文，当前约定包括 `agent`、`ai-core`、`chat`、`desktop`、`editor`、`extension`、`performance`、`security` 和 `streaming`。一个 TODO 应对应真实存在的工程缺口；小型清理工作直接完成，不长期保留无负责人、无目标的占位待办。
+
+## 当前待办索引
+
+以下内容可通过 `rg "TODO\\(" backend/app frontend/src` 定位，代码中的注释是最新状态：
+
+| 领域 | 当前边界 |
+| --- | --- |
+| Agent / Streaming | 运行事件仍在进程内保存，后续需要持久化、`Last-Event-ID` 和断线重连 |
+| Security | 本地主密钥目前保存在数据目录，桌面端接入后迁移到系统凭据库 |
+| Extension | 扩展安装状态尚未持久化；MCP Host、进程隔离、签名与来源校验属于第二阶段 |
+| AI Core | 音频转写当前只读取文本或 Host 预生成旁路文本，后续接入本地 ASR 队列 |
+| Desktop | Workspace 仍使用 Web Mock，后续由 Tauri IPC 文件系统适配器替换 |
+| Editor / Chat | 待补文件冲突合并、受控链接对话框及会话持久化 |
+| Performance | Shiki 已复用单例，后续按首屏指标评估延迟加载或 Web Worker |
+
+TODO 完成后应删除对应代码注释并同步更新本索引；若工作超过一个提交，应建立 Issue，并在 Issue 中引用代码位置，而不是在源码中记录长篇设计讨论。