# 开发约定

先读 [README](README.md)、[架构](docs/ARCHITECTURE.md)和[项目状态](docs/STATUS.md)。兼容基线见[调研](docs/RESEARCH.md)，浏览器操作见[检查方法](docs/VALIDATION-browser.md)。

## 文档

- 使用简短中文。每句说明一个动作或事实。固定使用“会话”“回合”“通知”“宿主”“浏览器”等术语。
- 每类可变信息只设一个权威来源，其他位置引用。允许必要的上下文重复。
- STATUS 只维护最新状态和待办。历史由 Git 保存。讨论过程仅在具有持续维护价值时写入文档。

## 修改

- 先检查工作树，保留已有改动。优先维护现有模块，遵守架构中的职责边界。
- 复用官方 Connection、插槽和主题。不要另建配置、鉴权、客户端加载器或事件分类器，也不要改写宿主私有 DOM。
- 通知失败不得阻止 Agent 工作。取消回合、空回合和子代理不得误报完成。
- 事件监听交给 Cordis。手工资源在 `ctx.effect` 中释放，卸载必须结束等待中的 Promise。
- 不记录任务正文、工具参数、审批理由或错误堆栈。测试使用虚构内容。
- 修改判定、去重、游标或异步清理时，保留既有反例，并补充能复现缺陷的行为测试。代码修改后运行 `npm run check`。
- 浏览器代码只修改 `src/`，通过构建生成 `dist/client.js`。纯文档修改核对内容与链接，无需运行代码测试或新增验收记录。
- 更新兼容基线时记录精确版本和提交，再按开发说明检查接口。区分源码检查、真实应用和系统人工结果。

## 提交与发布

- 每个提交只表达一个意图，使用 Conventional Commits。用户可感知的变化写入 CHANGELOG 的“未发布”。
- 测试、验收脚本与兼容检查工具等纯开发基础设施改动留在提交与开发文档中，不写入 CHANGELOG。
- 版本遵循 SemVer，保持 `package.json` 与锁文件一致。发布使用 annotated tag，已发布 tag 不移动。
- 没有明确请求时，不推送、不发布、不修改日常 dsh 配置。