From 88a91892d9df316fb58d816a5b24481f345f61f2 Mon Sep 17 00:00:00 2001 From: Melorise <0d00@0721.hk> Date: Wed, 26 Aug 2026 20:41:42 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85=E7=BB=B4=E6=8A=A4?= =?UTF-8?q?=E4=B8=8E=E4=BA=A4=E4=BB=98=E7=BA=A6=E6=9D=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit AI-assisted-by: Codex AI-model: gpt-5.6-sol AI-reasoning-effort: medium Co-authored-by: Codex --- AGENTS.md | 30 ++++++++++++++++++++++++++++++ CLAUDE.md | 30 ++++++++++++++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8439a64..fd7150d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,8 @@ MeloASR 是仅面向 Linux 的 Fcitx5 桌面语音输入工具。项目名为 `M 除非用户另有要求，文档、界面文字和代码注释使用简体中文。 +`AGENTS.md` 与 `CLAUDE.md` 必须始终逐字一致。修改其中任意一份时必须把相同内容同步到另一份，并在提交前使用字节比较确认一致。 + ## 核心不变量 - 网页编辑器中的当前完整内容是唯一可信识别结果。 @@ -79,6 +81,14 @@ npm run build:fcitx5 ctest --test-dir linux/fcitx5/build --output-on-failure ``` +验证必须与实际改动范围对应，禁止为了展示“完整”而机械扩大测试范围： + +- TypeScript、preload 或 renderer 改动运行 `npm test` 和 `npm run build`； +- 只有修改 Fcitx5 C++、CMake 构建逻辑或本地协议实现时，才运行 `npm run build:fcitx5` 和 `ctest`；仅同步发行版本号不要求重测未改动的 Fcitx5 逻辑； +- FHS 发行版是首要维护目标，FHS 构建或打包问题必须在对应 Debian、Ubuntu、RPM 或 Arch 环境处理，不得默认用 Nix 环境替代；Nix 只用于验证 Nix 打包路径； +- 项目依赖未安装时，按 `package-lock.json` 运行 `npm ci`，不能以 `tsc` 或其它工具缺失为由跳过正常验证； +- 不得声称添加了未实际添加的测试，也不得把无关环境中的成功构建计入目标平台验证结果。 + 最低动态回归：连续三轮；文本缩短、改词和补标点；finish 仅一次；cancel/reset/disconnect；ready gate；登录探测；后端切换；多屏位置和键盘微调；托盘退出/重启；自启动；GTK、Qt、Chromium 和终端；X11 与 Wayland。 不要声称没有真实验证的发行版包或元宝端到端识别已经通过。 @@ -87,6 +97,26 @@ ctest --test-dir linux/fcitx5/build --output-on-failure deb、rpm、Arch/pacman 和 Nix 都必须包含 Electron 应用、desktop/icon/autostart 文件和 Fcitx5 addon。桌面 ID、包名、Socket、addon 名称和版本保持一致。仓库地址和许可证确定前，不得把占位值作为正式发行元数据。 +版本发布时同步 `package.json`、`package-lock.json`、CHANGELOG、AppStream、Fcitx5 addon 版本和各发行版打包元数据，并运行 `scripts/release-metadata.mjs ` 校验发布说明。 + +`v*` Git 标签由远程 Release 工作流产生。除非用户明确要求，本地禁止创建、移动或删除发布标签，也禁止推送提交或标签。“更新版本”或“更新发版”本身不等于授权本地打标签。 + +## 工程判断与性能修改 + +- 先区分稳定对象与对象内部的可变内容。一次语音会话中编辑器根元素视为稳定对象，可以缓存；识别文本所在的子树内容持续变化，必须重新序列化完整结果。 +- 不得用没有实际证据的极端场景否定正常工程假设，例如假设同一录音会话中的编辑器根元素会被持续重建。若稳定对象意外失效，应采用明确失败策略，不能为猜测场景增加常态热路径开销。 +- 性能结论必须区分静态代码分析与真实测量。没有 profiler、计时或内存采样时，不得给出伪精确的性能收益。 +- 优化热路径时先消除重复 DOM 查询、重复序列化、重复 IPC 和无意义轮询，不得破坏网页常驻、实时启动录音和完整文本同步这些产品前提。 + +## 工作边界与交付检查 + +- 开始操作前确认实际 Git 仓库根目录，不能仅依赖外层工作区路径。 +- 用户要求实现修改时，应完成代码、对应验证、版本与 CHANGELOG 更新等明确要求；遇到缺失依赖要解决或准确报告真实阻塞，不能自行缩减交付范围。 +- 不得为了反驳用户而引入没有证据的假设。用户指出实现与事实矛盾时，应先核对代码链路并修正判断。 +- 只修改任务相关文件，不运行与改动无关的构建，不擅自扩大发布、标签、推送或外部操作范围。 +- 提交前检查 `git diff --check`、发行元数据校验和对应测试；提交后检查 `git status --short`、提交内容和工作树是否干净。 +- 只要修改了仓库文件，就必须在本轮创建对应 Git commit，不得留下未提交改动；如果不准备或不能提交，就不得修改文件。Tag 和 push 仍需分别获得用户明确授权，不能从修改或 commit 推定。 + ## 提交约定 按功能粒度提交，只包含相关文件。提交前运行对应验证。AI 辅助提交尾部统一添加： diff --git a/CLAUDE.md b/CLAUDE.md index 8439a64..fd7150d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -8,6 +8,8 @@ MeloASR 是仅面向 Linux 的 Fcitx5 桌面语音输入工具。项目名为 `M 除非用户另有要求，文档、界面文字和代码注释使用简体中文。 +`AGENTS.md` 与 `CLAUDE.md` 必须始终逐字一致。修改其中任意一份时必须把相同内容同步到另一份，并在提交前使用字节比较确认一致。 + ## 核心不变量 - 网页编辑器中的当前完整内容是唯一可信识别结果。 @@ -79,6 +81,14 @@ npm run build:fcitx5 ctest --test-dir linux/fcitx5/build --output-on-failure ``` +验证必须与实际改动范围对应，禁止为了展示“完整”而机械扩大测试范围： + +- TypeScript、preload 或 renderer 改动运行 `npm test` 和 `npm run build`； +- 只有修改 Fcitx5 C++、CMake 构建逻辑或本地协议实现时，才运行 `npm run build:fcitx5` 和 `ctest`；仅同步发行版本号不要求重测未改动的 Fcitx5 逻辑； +- FHS 发行版是首要维护目标，FHS 构建或打包问题必须在对应 Debian、Ubuntu、RPM 或 Arch 环境处理，不得默认用 Nix 环境替代；Nix 只用于验证 Nix 打包路径； +- 项目依赖未安装时，按 `package-lock.json` 运行 `npm ci`，不能以 `tsc` 或其它工具缺失为由跳过正常验证； +- 不得声称添加了未实际添加的测试，也不得把无关环境中的成功构建计入目标平台验证结果。 + 最低动态回归：连续三轮；文本缩短、改词和补标点；finish 仅一次；cancel/reset/disconnect；ready gate；登录探测；后端切换；多屏位置和键盘微调；托盘退出/重启；自启动；GTK、Qt、Chromium 和终端；X11 与 Wayland。 不要声称没有真实验证的发行版包或元宝端到端识别已经通过。 @@ -87,6 +97,26 @@ ctest --test-dir linux/fcitx5/build --output-on-failure deb、rpm、Arch/pacman 和 Nix 都必须包含 Electron 应用、desktop/icon/autostart 文件和 Fcitx5 addon。桌面 ID、包名、Socket、addon 名称和版本保持一致。仓库地址和许可证确定前，不得把占位值作为正式发行元数据。 +版本发布时同步 `package.json`、`package-lock.json`、CHANGELOG、AppStream、Fcitx5 addon 版本和各发行版打包元数据，并运行 `scripts/release-metadata.mjs ` 校验发布说明。 + +`v*` Git 标签由远程 Release 工作流产生。除非用户明确要求，本地禁止创建、移动或删除发布标签，也禁止推送提交或标签。“更新版本”或“更新发版”本身不等于授权本地打标签。 + +## 工程判断与性能修改 + +- 先区分稳定对象与对象内部的可变内容。一次语音会话中编辑器根元素视为稳定对象，可以缓存；识别文本所在的子树内容持续变化，必须重新序列化完整结果。 +- 不得用没有实际证据的极端场景否定正常工程假设，例如假设同一录音会话中的编辑器根元素会被持续重建。若稳定对象意外失效，应采用明确失败策略，不能为猜测场景增加常态热路径开销。 +- 性能结论必须区分静态代码分析与真实测量。没有 profiler、计时或内存采样时，不得给出伪精确的性能收益。 +- 优化热路径时先消除重复 DOM 查询、重复序列化、重复 IPC 和无意义轮询，不得破坏网页常驻、实时启动录音和完整文本同步这些产品前提。 + +## 工作边界与交付检查 + +- 开始操作前确认实际 Git 仓库根目录，不能仅依赖外层工作区路径。 +- 用户要求实现修改时，应完成代码、对应验证、版本与 CHANGELOG 更新等明确要求；遇到缺失依赖要解决或准确报告真实阻塞，不能自行缩减交付范围。 +- 不得为了反驳用户而引入没有证据的假设。用户指出实现与事实矛盾时，应先核对代码链路并修正判断。 +- 只修改任务相关文件，不运行与改动无关的构建，不擅自扩大发布、标签、推送或外部操作范围。 +- 提交前检查 `git diff --check`、发行元数据校验和对应测试；提交后检查 `git status --short`、提交内容和工作树是否干净。 +- 只要修改了仓库文件，就必须在本轮创建对应 Git commit，不得留下未提交改动；如果不准备或不能提交，就不得修改文件。Tag 和 push 仍需分别获得用户明确授权，不能从修改或 commit 推定。 + ## 提交约定 按功能粒度提交，只包含相关文件。提交前运行对应验证。AI 辅助提交尾部统一添加：