zhouchengcheng/ctms
1
1
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity
Files
release
ctms/AGENTS.md
T
Cheng Zhou 795e0a75ca
Client Quality Gates / Shared client and Web (push) Has been cancelled
Details
Client Quality Gates / macOS Desktop (push) Has been cancelled
Details
build(release): simplify v0.1.0 visible assets
2026-07-17 12:40:16 +08:00

7.8 KiB
Raw Permalink Blame History

Agent Instructions

桌面端项目计划书已完成并移除；当前桌面端执行约束以本文件为准。桌面端任务包括但不限于 Tauri、macOS、Windows、桌面打包、桌面存储、文件集成、系统通知、自动更新和桌面端安全边界。历史设计只作追溯参考，见 docs/desktop-phase-1-design.md、docs/desktop-phase-2-design.md、docs/audits/desktop-release-stabilization-checklist.md。

桌面端当前不是空白初始化项目。Tauri 基线、macOS 在线桌面壳和第二阶段原生能力主体已经形成；后续工作限于修复、稳定化、体验收口、发布准备、在线辅助缓存、Windows 兼容验证和已批准的 Windows 正式发布。不得重新按第一阶段空白项目初始化 Tauri，不得绕过现有 frontend/src/runtime/ 适配层直接在业务模块中使用 Tauri API。

除非用户明确要求先调整本文件中的约束，否则不要实现离线功能、本地业务权威数据存储、内嵌后端服务、离线同步、本地优先工作流或新的阶段性桌面产品线。在线辅助本地缓存只允许作为已认证在线客户端的体验加速能力；处理桌面本地缓存、请求去重、条件请求、缓存诊断或缓存清理相关任务时，必须阅读并遵守 docs/desktop-local-cache-plan.md。

处理前端或桌面端实现时，优先保持以下边界：

  • 共享业务代码通过 frontend/src/runtime/index.ts 获取平台能力。
  • Tauri API 仅允许出现在 frontend/src/runtime/、frontend/src-tauri/ 或有明确记录的窄入口中。
  • 本地缓存能力只能通过 frontend/src/runtime/desktopDataCache.ts、frontend/src/runtime/index.ts、clientRuntime.dataCache 和 API 客户端的受控入口暴露；业务模块不得直接使用 Tauri 存储 API、文件系统、SQLite、IndexedDB 或 Cache Storage 实现缓存。
  • 未完成后端 token 校验和 /me 身份确认前，不得展示业务缓存；登出、切换服务器、切换用户、401/403、权限上下文变化或缓存 schema 变化时必须清理或失效相关缓存。
  • 新增或调整 Tauri command、capability、CSP、updater、凭据、文件、通知、本地缓存持久化或底层存储能力时，必须同步评估 frontend/scripts/verify-desktop-release.mjs、npm run runtime:check 和桌面发布检查清单是否需要更新。
  • token、附件下载凭据和敏感业务信息不得写入 URL、日志、系统通知正文或明文浏览器存储。
  • 正式桌面客户端的默认 CTMS 服务端入口必须由构建环境变量 VITE_DESKTOP_SERVER_URL 注入，不得在运行时代码中写死生产域名；用户仍可在桌面服务器设置中手动覆盖，手动值优先并沿用既有的切换服务器登出与缓存失效边界。该变量只表示业务服务端 origin，不得与 updater 制品前缀 DESKTOP_UPDATE_BASE_URL 混用。
  • Windows x64 NSIS 已获准作为正式桌面发布目标；正式制品必须由 .github/workflows/desktop-release-candidate.yml 从与 macOS/Web 相同的 vX.Y.Z tag 和 SHA 构建。平台签名默认要求组织 Windows 代码签名证书、RFC 3161 时间戳和 Authenticode 校验；只有 frontend/desktop-release-policy.json 中按精确版本记录、经发布负责人批准的例外可跳过平台签名。无论是否采用平台签名例外，都必须使用 updater 私钥、校验 updater feed，并明确标记平台未签名风险。.github/workflows/desktop-windows-internal.yml 仍只用于分支上的无签名兼容性验证，不得生成生产 latest.json、updater feed 或正式发布制品。
  • v0.1.0 另获准在 GitHub Actions 额度不可用时，从最终 release 上不可移动的 v0.1.0 tag/SHA 在受控 macOS 主机本地构建并先行上传 macOS ad-hoc 制品；Windows 只能在额度恢复后从同一 tag/SHA 后补。面向安装用户的 GitHub Release 只保留 DMG 与只校验该安装包的 SHA256SUMS.txt，平台未签名风险和 Windows pending 状态写入 Release Notes。macOS updater 包及 .sig、完整 checksum、provenance、UNSIGNED-PLATFORM 与 Windows pending 证据必须保存在被 Git 忽略的私有发布目录，待 Windows NotSigned 制品和联合 feed 均验证通过后再发布到可匿名读取的独立 HTTPS updater 源；此前不得发布或替换生产 latest.json。该本地/分阶段例外不适用于后续版本。

分支与发布治理

处理代码提交、分支同步、版本晋级、正式发布或生产热修复前，必须先阅读：

  • 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 配置或安全边界相关变更至少考虑：

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

本地缓存相关变更至少执行 runtime:check、desktop:release:check、ui:contract、type-check、test:unit 和 build；若新增 Tauri command、capability、CSP 或底层持久化存储，还需执行 desktop:build:app 并在真实桌面 App 中验证缓存清理和诊断入口。

正式桌面发布构建必须使用组织批准的 updater 签名私钥，updater 签名不可因平台签名例外而关闭。平台签名默认要求 macOS 完成 Apple 签名/公证、Windows 完成组织代码签名、RFC 3161 时间戳和 Authenticode 校验。当前仅批准 v0.1.0 采用受控分发例外：macOS 使用 ad-hoc 签名且不公证，Windows 应用和安装器保持 Authenticode 未签名；制品名、Release Notes、私有发布证据、完整 updater 校验清单和 provenance 必须清楚标注 UNSIGNED-PLATFORM，并提示 Gatekeeper/SmartScreen 警告。面向安装用户的 GitHub Release 可按精确版本策略精简为安装包与对应 checksum，但不得因此删除私有 updater 签名制品或验证证据。该例外不自动适用于后续版本。

Reference in New Issue View Git Blame Copy Permalink