# WhaleIsle 开发与维护

维护资料帮助找到代码、理解用户行为和保护桌面差异。开发反馈由 CI 提供，发布由成功构建自动完成。本文取代旧候选验收、签署、文档格式门槛和“CI 只能最终手动执行”的流程；历史记录保留事实，不再规定执行步骤。

## 开发

在工作分支实现需求，使用现有的相关验证，然后提 PR。PR 说明原需求、实际变化和验证结果；由用户决定合入 main。代理不能擅自缩减需求、吞掉错误、削弱有效断言，或为假想场景增加重试、兼容层和配置。遇到不能完成的部分直接说明。

本地用能回答当前问题的检查；开发 CI 提供共享环境、回归与装配反馈，不要求先在本机复制完整 CI。失败先查具体原因，修正后只重跑相关检查。已经通过的验证不因提交、推送或“不放心”重复执行。

`npm test` 运行桌面和移动端行为测试；`npm run test:tools` 运行构建、发布及维护工具测试。定向验证直接调用现有测试文件。新增测试应能发现实际故障，不用测试数量或覆盖率目标替代用户结果。

## CI 与发布

`test.yml` 在 PR、main 推送及手动运行时提供开发反馈。文档修改不触发产品构建。产品改动在 Windows 上构建实际分发 profile、运行行为测试、生成安装包并启动打包后的应用；上游行为与原生窗口检查按影响选择。macOS 按需手动启用。

main 的开发 CI 成功后，`release.yml` 使用该次构建的原始资产。package.json 的版本高于已发布版本时自动发布；版本未增加则不发版。上传失败重试分发，不重编译。具体操作见[发布说明](../handbook/modules/release-process.md)。

不再要求候选计划、固定人工全表、验收 JSON、签字字段、验证日期刷新或累计失败计数表。真实缺陷、数据与权限边界仍按用户影响处理；测试记录只能证明实际执行过的行为。

## 项目知识

- [产品手册](../handbook/README.md)：模块、架构和操作入口。
- [功能资料](../features/README.md)：需要长期保持的用户行为与桌面差异。
- [设计语言](../design-language.md)：视觉规范。
- [历史决定](../decisions/README.md)：值得保留的原因和取舍。

同一个事实只在负责位置维护。AGENTS、rules 和技能只负责导航，不能再各自增加一套流程。普通修复写在 PR 中；产品契约改变时更新对应资料，不要求先建卡才能开发。内部资料可用一种语言；已有译文与历史保留，取消结构配对、摘要确认与格式校验。公开文档按读者需要翻译。

文档链接检查可用 `npm run docs:check`，按需执行，不作为产品发布条件。功能卡中的 Gates 和历史用例库用于寻找现成检查，不是必须全部执行的列表。

## 上游合并与差异保护

先查看 `vendor/harness-upstream.json` 和 `src/shared/harness-desktop-forks.js`，识别本地桌面差异；位置标记不能证明功能仍然正常。

1. 对照旧 pin 到目标版本的上游变化，以及当前 vendor 相对旧 pin 的本地修改；`npm run sync:harness -- --dry-run --ref <ref> --sha <sha>` 可预演。
2. 查看交集及受影响的配置消费者、生成资源和实际装配。没有 Git 冲突也要理解行为变化。
3. 保持已交付能力、用户数据和权限约定。上游提供等价实现时可替换本地补丁；涉及功能删减或产品取舍时由用户决定。
4. 验证本次影响的用户路径，更新 pin、差异位置和相关资料。上游带回的治理、hooks 和测试惯例不自动成为本项目流程。

## 验证结果

区分产品故障、测试工具错误和环境缺失；不能把未执行说成通过。UI、安装、数据保存等行为需要对应的实际观察，单测不能证明所有操作。报告实际改动、已观察结果和剩余问题即可，不建立第二套审批或证据平台。