Melorise/TamaASR
1
0
Fork 0
mirror of https://github.com/Melorise/TamaASR.git synced 2026-11-07 14:39:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 补充维护与交付约束

Browse Source 
AI-assisted-by: Codex

AI-model: gpt-5.6-sol

AI-reasoning-effort: medium

Co-authored-by: Codex <codex@openai.com>
This commit is contained in:
Melorise
2026-08-26 20:41:42 +08:00
co-authored by Codex
parent e6f67be337
commit 88a91892d9
2 changed files with 60 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+30
View File
@@ -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 <version>` 校验发布说明。
`v*` Git 标签由远程 Release 工作流产生。除非用户明确要求，本地禁止创建、移动或删除发布标签，也禁止推送提交或标签。“更新版本”或“更新发版”本身不等于授权本地打标签。
## 工程判断与性能修改
- 先区分稳定对象与对象内部的可变内容。一次语音会话中编辑器根元素视为稳定对象，可以缓存；识别文本所在的子树内容持续变化，必须重新序列化完整结果。
- 不得用没有实际证据的极端场景否定正常工程假设，例如假设同一录音会话中的编辑器根元素会被持续重建。若稳定对象意外失效，应采用明确失败策略，不能为猜测场景增加常态热路径开销。
- 性能结论必须区分静态代码分析与真实测量。没有 profiler、计时或内存采样时，不得给出伪精确的性能收益。
- 优化热路径时先消除重复 DOM 查询、重复序列化、重复 IPC 和无意义轮询，不得破坏网页常驻、实时启动录音和完整文本同步这些产品前提。
## 工作边界与交付检查
- 开始操作前确认实际 Git 仓库根目录，不能仅依赖外层工作区路径。
- 用户要求实现修改时，应完成代码、对应验证、版本与 CHANGELOG 更新等明确要求；遇到缺失依赖要解决或准确报告真实阻塞，不能自行缩减交付范围。
- 不得为了反驳用户而引入没有证据的假设。用户指出实现与事实矛盾时，应先核对代码链路并修正判断。
- 只修改任务相关文件，不运行与改动无关的构建，不擅自扩大发布、标签、推送或外部操作范围。
- 提交前检查 `git diff --check`、发行元数据校验和对应测试；提交后检查 `git status --short`、提交内容和工作树是否干净。
- 只要修改了仓库文件，就必须在本轮创建对应 Git commit，不得留下未提交改动；如果不准备或不能提交，就不得修改文件。Tag 和 push 仍需分别获得用户明确授权，不能从修改或 commit 推定。
## 提交约定
按功能粒度提交，只包含相关文件。提交前运行对应验证。AI 辅助提交尾部统一添加：
CLAUDE.md
+30
View File
@@ -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 <version>` 校验发布说明。
`v*` Git 标签由远程 Release 工作流产生。除非用户明确要求，本地禁止创建、移动或删除发布标签，也禁止推送提交或标签。“更新版本”或“更新发版”本身不等于授权本地打标签。
## 工程判断与性能修改
- 先区分稳定对象与对象内部的可变内容。一次语音会话中编辑器根元素视为稳定对象，可以缓存；识别文本所在的子树内容持续变化，必须重新序列化完整结果。
- 不得用没有实际证据的极端场景否定正常工程假设，例如假设同一录音会话中的编辑器根元素会被持续重建。若稳定对象意外失效，应采用明确失败策略，不能为猜测场景增加常态热路径开销。
- 性能结论必须区分静态代码分析与真实测量。没有 profiler、计时或内存采样时，不得给出伪精确的性能收益。
- 优化热路径时先消除重复 DOM 查询、重复序列化、重复 IPC 和无意义轮询，不得破坏网页常驻、实时启动录音和完整文本同步这些产品前提。
## 工作边界与交付检查
- 开始操作前确认实际 Git 仓库根目录，不能仅依赖外层工作区路径。
- 用户要求实现修改时，应完成代码、对应验证、版本与 CHANGELOG 更新等明确要求；遇到缺失依赖要解决或准确报告真实阻塞，不能自行缩减交付范围。
- 不得为了反驳用户而引入没有证据的假设。用户指出实现与事实矛盾时，应先核对代码链路并修正判断。
- 只修改任务相关文件，不运行与改动无关的构建，不擅自扩大发布、标签、推送或外部操作范围。
- 提交前检查 `git diff --check`、发行元数据校验和对应测试；提交后检查 `git status --short`、提交内容和工作树是否干净。
- 只要修改了仓库文件，就必须在本轮创建对应 Git commit，不得留下未提交改动；如果不准备或不能提交，就不得修改文件。Tag 和 push 仍需分别获得用户明确授权，不能从修改或 commit 推定。
## 提交约定
按功能粒度提交，只包含相关文件。提交前运行对应验证。AI 辅助提交尾部统一添加：