Cheng Zhou
b491b6a146
Client Quality Gates / Shared client and Web (push) Has been cancelled
Client Quality Gates / macOS Desktop (push) Has been cancelled
Storage Persistence Guard / storage-persistence-audit (push) Has been cancelled
Client Quality Gates / Shared client and Web (pull_request) Has been cancelled
Client Quality Gates / macOS Desktop (pull_request) Has been cancelled
Storage Persistence Guard / storage-persistence-audit (pull_request) Has been cancelled
57 lines
4.1 KiB
Markdown
57 lines
4.1 KiB
Markdown
# Agent Instructions
|
|
|
|
处理 CTMS 桌面端任务前，必须先阅读 `docs/desktop-project-plan.md`。桌面端任务包括但不限于 Tauri、macOS、Windows、桌面打包、桌面存储、文件集成、系统通知和桌面端安全边界。
|
|
|
|
桌面端当前阶段边界以 `docs/desktop-project-plan.md` 为准。除非先明确修改计划书，否则不要实现离线功能、本地业务数据存储、内嵌后端服务、离线同步或新的阶段性桌面产品线。
|
|
|
|
`docs/desktop-project-plan.md` 是当前桌面端进展和工作边界的事实来源。本文件只保留执行约束，不重复维护审查结论或优化方向；不得重新按第一阶段空白项目初始化 Tauri，也不得绕过现有 `frontend/src/runtime/` 适配层直接在业务模块中使用 Tauri API。如实际代码状态与计划书不一致，先更新计划书再实现。
|
|
|
|
处理前端或桌面端实现时，优先保持以下边界：
|
|
|
|
- 共享业务代码通过 `frontend/src/runtime/index.ts` 获取平台能力。
|
|
- Tauri API 仅允许出现在 `frontend/src/runtime/`、`frontend/src-tauri/` 或有明确记录的窄入口中。
|
|
- 新增或调整 Tauri command、capability、CSP、updater、凭据、文件、通知能力时，必须同步评估 `frontend/scripts/verify-desktop-release.mjs`、`npm run runtime:check` 和桌面发布检查清单是否需要更新。
|
|
- token、附件下载凭据和敏感业务信息不得写入 URL、日志、系统通知正文或明文浏览器存储。
|
|
- Windows 仍只作为第二阶段兼容性验证目标；未获明确批准前不发布正式 Windows 安装包。
|
|
|
|
## 分支与发布治理
|
|
|
|
处理代码提交、分支同步、版本晋级、正式发布或生产热修复前，必须先阅读：
|
|
|
|
- `docs/guides/branch-maintenance-sop-zh.md`
|
|
- `docs/branch-governance.md`
|
|
- 涉及网页端或桌面端客户端发布时，还需阅读 `docs/guides/client-release.md`
|
|
|
|
必须遵守以下规则：
|
|
|
|
- CTMS 网页端和桌面端属于同一个产品，共用 `dev`、`main`、`release` 分支，不创建 `web-dev`、`desktop-dev`、`web-release`、`desktop-release` 等长期平行分支。
|
|
- 默认晋级路径为短期任务分支进入 `dev`，再由 `dev` 晋级到 `main`，最后由 `main` 发布到 `release`。
|
|
- Agent 创建分支时默认使用 `codex/<任务名称>`；分支必须从最新 `dev` 创建，并在合并到 `dev` 后删除。
|
|
- `codex/ctms-desktop` 是历史桌面端临时集成分支，不再作为当前工作线；不得继续向该分支提交、变基或推送新的桌面端工作，除非用户明确要求做收尾或删除分支。
|
|
- 生产热修复从 `release` 创建，合并到 `release` 后必须依次回合并到 `main` 和 `dev`。
|
|
- 网页端和桌面端必须使用同一个语义化版本号、正式标签和源代码提交。修改客户端版本时使用 `frontend/package.json` 中的 `version:set` 和 `version:check` 命令。
|
|
- 平台差异必须收敛在 `frontend/src/runtime/` 之后，不能通过长期分支或复制业务代码维护桌面差异。
|
|
- 未经用户明确要求，不执行提交、推送、合并、变基、打标签、删除分支或强制更新远程分支。
|
|
- 执行用户明确要求的 Git 操作前，先检查工作区和目标分支，只暂存本次任务相关文件，不覆盖或撤销用户已有改动。
|
|
- 如果工作区处于 detached HEAD 或包含尚未归属到分支的提交，执行任何分支切换、提交、推送或变基前必须先说明目标基线，并等待用户明确指令。
|
|
- 分支治理规则发生变化时，必须同步更新上述治理文档，不能只修改 `AGENTS.md`。
|
|
|
|
## 常用质量门禁
|
|
|
|
前端或桌面端代码变更应按影响范围执行相关检查。发布、桌面端适配层、Tauri 配置或安全边界相关变更至少考虑：
|
|
|
|
```bash
|
|
cd frontend
|
|
npm run version:check
|
|
npm run release:env:check
|
|
npm run runtime:check
|
|
npm run desktop:release:check
|
|
npm run ui:contract
|
|
npm run type-check
|
|
npm run test:unit
|
|
npm run build
|
|
npm run desktop:build:app
|
|
```
|
|
|
|
正式桌面发布构建仍必须使用组织批准的 updater 签名私钥和 Apple 签名/公证流程；未签名或 ad-hoc 构建只能作为内部验证构建描述。
|