kev/Drawer/AI/docs/coding_rules.md

编码风格约束（微软风格，强制）

以下规则便于 AI 与人工修改代码时一致、可静态检查。

1. 花括号（必须）

• if / else / for / foreach / while / do / using / lock / fixed：一律使用花括号，禁止单行无括号写法。
• 正确：if (x) { Do(); }
• 错误：if (x) Do(); 或 if (x) return;（单行也不省略括号）

2. 命名

• PascalCase：类型、方法、属性、公共字段、常量、枚举成员、命名空间
• camelCase：局部变量、参数、私有字段（私有字段可加 _ 前缀）
• 接口：I 前缀（如 IFormRegistry）
• 异步方法：后缀 Async（如 AskAsync；同步方法如 GetHistoryForLlm 不加 Async）

3. 类型与可空性

• 启用 Nullable 上下文。引用类型需明确可空（string?、ChatSession?）；不可空则不加 ?。
• 避免无谓的 !；仅在确知非 null 时使用。

4. 行与格式

• 单行不宜过长；复杂表达式或参数列表可换行缩进对齐。
• else if 写成独立块并加括号。
• switch：每个 case 用 break 或 return 明确结束；需要 fall-through 时显式写注释。

5. 异步与取消

• 异步方法返回 Task 或 Task<T>，命名带 Async。
• 长时间运行或可能取消的操作应接受 CancellationToken（通常为最后一参，默认 default）。

6. 注释与文档

• 公共 API（接口、公开方法/属性）使用 /// 摘要；复杂逻辑可加简短行内注释。
• 不写无信息量的注释（如重复方法名）。

7. 其他

• var：类型明显时可用；否则写显式类型以提高可读性。
• using：实现 IDisposable 的实例优先用 using 或 await using。
• 集合：对外暴露只读集合时用 IReadOnlyList<T>、IReadOnlyDictionary<K,V> 等，避免直接暴露可变集合。