git:20260814.ebcf12e to git:20260814.eb45799

# Nova Agent 工程规则

本文件是所有人类开发者与 Coding Agent 的**强制入口**。开始任何修改前，必须先阅读本文件；涉及架构、状态、公共契约、兼容或跨模块改动时，还必须阅读 [`engineering-rules.md`](engineering-rules.md)。修改测试、测试基础设施或 Renderer/Electron 生命周期时，还必须阅读 [`tests/AGENTS.md`](tests/AGENTS.md)。

规则优先级：任务明确要求 > 本文件 > 详细工程规则 > 现有代码惯例。现有代码不因存在已久而自动成为正确范例。

---

## 强制写作规范（必须遵守）

以下三条对所有 Agent **一律强制**，不得以「便于追踪」「方便以后看」为由放宽。

### 1. 严禁任务编号与过程痕迹

注释、commit message、PR 说明、代码文档中**严禁**出现：

- 任务编号、阶段号、PR 编号（如 `P0`/`P1`/`P4`、`Phase 6`、`#1853`）

- 临时方案名、验收项编号、内部工单号

- 「完成了某任务」「修复了某 Bug」「按某某计划」这类过程汇报

这些内容应留在 Git 历史之外的任务系统里；写进仓库会污染可读性。

### 2. Commit message：像软件更新说明

Commit 面向「读 changelog 的人」，写**优化了什么、改进了什么、重写了什么**，不要写成技术实现流水账。

**要求：**

- 标题：`type(scope): 一句话概括用户/产品侧变化`（conventional commits）

- 正文：若干短 bullet，每条说清一项可感知的变化

- 用产品语言：体验、观感、行为、能力；少提具体组件名、类名、文件名、API、CSS 选择器

- 不要列「改了哪个文件」「删了哪个函数」

**推荐写法：**

```text

feat(chat): 优化输入体验与代码块观感

- 输入框改用官方 Composer，去掉自研包壳

- 技能斜杠补全改走官方菜单

- 发送被拒时保留草稿，不被误清空

- 技能菜单限制宽度，长描述不再撑破边界

- 回到底部改为清晰的悬浮小箭头

- 代码块配色与羊皮纸主题统一，深浅色均可辨认

- 补充输入相关契约测试

```

**禁止写法（难读、过技术）：**

```text

feat(chat): 接入官方 Composer，并打磨技能菜单与代码块观感

- 输入框改用 Astryx ChatComposerInput，去掉自研 textarea 包壳

- slash 技能补全改为官方 trigger，删除旧 SkillAC 浮层

- Enter 仍由产品层控制，编排忙/拒发时保留草稿不被清空

- ...

```

后者堆砌实现名词，读起来像补丁说明，不像产品更新。

### 3. 注释要短：概括「做什么 / 用什么」，不要写说明书

- 默认少写注释；命名与结构能说清的，不要再写一段。

- 需要注释时：一两句概括职责、关键不变量、为何不能改成别的写法即可。

- **禁止**给每个函数写大段 AI 式说明、逐步复述代码、堆叠背景故事。

- 注释只解释长期成立的「为什么」（并发、安全、协议、边界）；不写修改历史、任务过程、阶段标签。

---

## 不可破坏的边界

1. **一项职责，一个 Owner**

- 每个模块的核心职责必须能用一句话说明。

- 每项可变状态必须只有一个写入 Owner；其他模块只能查询、订阅或请求 Owner 修改。

- Facade、Coordinator、Service 和 Store 不得成为承接无关功能的万能容器。

2. **Agent kernel 保持纯粹**

- Agent Loop 只负责「调用模型 → 执行工具 → 写回结果 → 判断继续或停止」的循环。

- 权限、持久化、上下文压缩、协议适配、Skill、Workflow、产品路由、UI 与 Electron 生命周期必须由独立 Owner 管理。

- kernel 不得直接依赖产品执行器、Renderer、Electron 或具体持久化实现。

3. **依赖只能朝允许方向流动**

- `shared` 不依赖其他应用层；runtime 的 core/domain 只依赖 `shared`、同层公共契约和显式端口；`main` 负责装配 Electron、基础设施与 runtime；`preload` 只暴露类型化桥接；`renderer` 只依赖自身与 `shared`。

- 禁止跨层反向 import、循环依赖、从 barrel 或相对路径绕过边界、直接访问其他模块内部文件。

- 现有 import boundary 测试是最低门禁；不得用宽泛 allowlist 放行新债务。

4. **契约必须显式且唯一**

- 跨模块命令、事件和数据使用唯一来源的类型化契约。

- 禁止 `any`、松散 payload、复制相似类型、未校验的类型断言。

- 外部输入先以 `unknown` 接收并在边界校验；transport DTO、领域状态、持久化模型和诊断信息不得混成一个无结构对象。

5. **目录表达领域和职责**

- 实现按业务领域放入子目录；测试应镜像或紧邻对应领域，能够直接定位。

- 禁止新增职责模糊的 `utils`、`helpers`、`common` 垃圾桶。

- 新工具必须位于 `src/runtime/tools/<tool-name>/` 并由该目录的 `index.ts` 导出。

- 不按行数机械拆文件；只有存在独立概念、独立契约或独立生命周期时才拆分。

6. **修改必须最小且完整**

- 一次修改只处理一个主要目标。动手前先写清：目标、范围、非目标、不变量、验收方式。

- 在最早破坏约束的位置修根因；禁止在多个下游重复打补丁、创建平行状态或复制主路径。

- 禁止让新旧两套主路径长期并存。兼容代码必须写明兼容对象、存在原因、删除条件和保护测试。

- 不借局部任务大规模重构，不修改与目标无关的稳定行为。

7. **测试要保护风险，不追求数量**

- 测试应保护用户行为、关键状态、容易回归的边界，以及事件顺序、终态唯一性、取消/失败清理、状态写入权限、协议兼容和依赖方向。

- **不要默认给每个改动新增测试，也不强制机械执行 TDD。** 新测试必须能说明它在防止什么真实回归；优先扩展或复用现有测试。

- 禁止重复 assertion、只断言非空、只断言 mock 被调用、过度 mock 状态 Owner、放宽断言或吞错来制造假绿。没有独立保护价值的测试应合并或删除。

- 开发循环只运行受影响的最小测试集合；当前行为完成后运行相关回归。不得每编辑一行就机械跑全量测试；完整 suite、fault/stress 和打包门禁交给 CI / nightly / release。

- 源码变更至少运行相关测试和 `npm run typecheck`；执行与风险直接相关的 lint/build/架构门禁。若所需门禁尚未配置或无法执行，必须明确报告，不能声称验证完成。

8. **保护工作区与安全边界**

- 不读取、输出或硬编码密钥和凭据。

- 不覆盖、删除或回退无关改动；未经要求不 commit、push、rebase、reset、clean 或强制 checkout。

- 不新增依赖、不改变公共 API、持久化格式、默认值或错误语义，除非目标明确要求且迁移与回退已设计。

- 提交时由当前仓库配置的用户身份完成；不要附加与本仓库无关的 bot / co-author 信息。

---

## Coding Agent 停止条件

发现以下任一情况时，停止实现并先汇报，不得自行猜测或补丁化绕过：

- 无法指出某项状态的唯一 Owner；

- 两个公共契约互相冲突或同一事件存在多个类型来源；

- 目标要求跨越禁止的依赖方向；

- 只能靠新增第二条主路径、长期兼容层或重复状态完成；

- 高风险重构无法用测试证明行为保持一致；

- 任务范围、数据安全、公开接口或不可逆操作存在关键歧义。

---

## 开发检查清单

### 修改前

- [ ] 已阅读本文件；必要时已阅读详细工程规则；修改测试或 Electron/Renderer 生命周期时已阅读 `tests/AGENTS.md`。

- [ ] 已查看真实调用方、被调用方、公共类型、相邻实现和相关测试。

- [ ] 已写明目标、范围、非目标、不变量和验收方式。

- [ ] 已确认职责 Owner、状态 Owner、依赖方向和兼容边界。

- [ ] 已检查工作区，确认不会覆盖无关改动。

### 修改中

- [ ] 变更位于最接近根因和正确 Owner 的位置。

- [ ] 未新增跨层 import、重复状态、松散契约、万能容器或垃圾桶目录。

- [ ] 未保留无删除条件的旧主路径或兼容分支。

- [ ] 测试没有因“代码有改动”而机械新增，也没有重复已有保护或把关键 Owner mock 掉。

- [ ] 注释克制：无任务编号、无过程痕迹、无函数说明书式长注释。

### 完成前

- [ ] 已识别本次风险；需要自动化保护的行为有有效测试，不值得维护的重复/表面测试没有继续堆积。

- [ ] 已运行受影响测试、相关回归、typecheck，以及与改动直接相关的架构/lint/build 门禁。

- [ ] 已检查错误、取消、并发、恢复和清理路径。

- [ ] 已检查 diff、tracked/untracked 文件和生成物边界。

- [ ] 若需要 commit：message 像产品更新说明，无任务编号、无实现流水账。

- [ ] 未验证项、剩余风险和兼容删除条件已如实报告。