NotesAgentic/docs/guides/代码注释与TODO约定.md

代码注释与 TODO 约定

本文用于统一团队在前后端代码中编写注释和待办项的方式。注释应解释设计意图、边界条件和不明显的取舍，不重复代码本身已经清楚表达的内容。

注释原则

• 模块或核心类说明其职责和边界，例如 Agent 编排器、工具执行边界、凭据存储边界。
• 异步流程说明顺序、快照、去重、回滚和竞态处理原因。
• 安全相关流程说明默认拒绝、权限收敛、输入净化和凭据优先级。
• 简单赋值、显然的条件判断、类型定义和展示模板不添加翻译式注释。
• 注释随实现一并维护；实现变化后已经失真的注释应在同一提交中修改或删除。

TODO 格式

前端使用：

// TODO(editor): 描述尚未完成的能力、完成条件或替换目标。

后端使用：

# 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 中引用代码位置，而不是在源码中记录长篇设计讨论。