# 代码注释与 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 | Web Workspace 已连接 FastAPI 单 Vault；后续由 Tauri IPC 增加原生目录选择、多 Vault 和文件监听 |
| Editor / Chat | 待补文件冲突合并及受控链接对话框；会话持久化已接入后端 SQLite |
| Performance | Shiki 已复用单例，后续按首屏指标评估延迟加载或 Web Worker |

TODO 完成后应删除对应代码注释并同步更新本索引；若工作超过一个提交，应建立 Issue，并在 Issue 中引用代码位置，而不是在源码中记录长篇设计讨论。