Files
ClassHelper/prompts/full-repo-audit-optimize-release.prompt.md
T

11 KiB
Raw Blame History

ClassHelper 全仓审计、优化与本地交付

先读根 AGENTS.md,再完成本文件与审计清单。 以现场源码和本次命令为证据;保留已有工作;每阶段汇报结果。历史报告只作线索。

0. 工作顺序

  1. 确认 cwd、分支、HEAD 和未提交文件;读取 AGENTS.md 及适用的子目录规则。
  2. 读 docs/dev/architecture.md、testing.md、release.md、permissions.md,再用 docs/reference.md 定位实现。
  3. 完成 Phase 0,建立问题账本,再按域修复。自动执行模式逐阶段继续;用户要求先确认计划时先交基线、账本和计划。
  4. 每项按“复现/测量 → 最小修复 → 定向验证 → 按主题提交”闭环。

先用 rg 定位再分段读取。日志保存 .cache/audit/<本次运行>/,对话报告实际摘要。 首次生成唯一 runId,并在账本记录 cwd、HEAD、工具版本、命令和进程标识;中断后沿用原目录,追加日志而不覆盖失败证据。 只读可并行;同一文件单一写者,shared/schema/根配置串行处理,同时只运行一个大构建。 每阶段建议 1–2 小时时间盒;到时报告卡点及下一步,不静默延长。

1. 工程边界

完整契约在 AGENTS.md,修改对应模块前核对:

  • 验收使用临时 SQLite、独立账号与文件目录;真实库不 seed/reset,不改真实班级密码,不发测试消息。
  • 权限同时检查能力、该键范围和业务关系;CLASS_DEVICE 的既有本班能力保留;课表维护范围不能自授任课关系。
  • 单一 Prisma schema,SQLite/MySQL 通用;模型变动新增迁移并同步快照及旧库兼容,保留历史迁移。
  • 批量写入和整库恢复保留事务边界;事件在提交后发;日期/周次使用共享及服务端唯一入口。
  • Electron 保留桥接白名单、CSP、同源导航、缓存隔离、设备归属、去重和 SHA256 门禁。冒烟使用假系统执行器。
  • 岛的透明、几何、投影、触摸、崩溃限流和两种模式规则保持原约束;视觉与联网验收按 testing.md 的授权边界执行。
  • 保留运行数据、依赖缓存、dist、凭据及其他版本交付物;递归文件操作前验证绝对目标路径。
  • 中文文案、文档、注释与 Conventional Commits;LF,只格式化本次改动。
  • 版本只走 scripts/version.mjs;用户已给版本策略时沿用,否则打包前确认级别,建议 patch。
  • 未明确授权不 push、不建 tag/Release、不上传或替换远端资产;本地站点构建不等于发布。

2. 现场证据与账本

账本位于 .cache/audit/<本次运行>/ledger.md:

ID 域/检查项 文件:行号 复现命令与现象 级别 方案 验证日志 状态
示例 A3 具体源码 实际结果 P0 单一主题 本次证据 修复/无问题/后续

清单 A–I 每项必须有结论;“无问题”要证据,“后续”要原因、影响和具体下一步。 P0:越权、数据丢失/错乱、生产中断、迁移损坏;P1:已测量性能缺陷或错误行为;P2/P3:维护与文案。 先复现 P0,再修 P1;候选不是结论,不为凑数改代码。

至少三项性能改进使用相同输入及工具链记录前后值和复现命令。 指标可为查询/模型操作数、载荷、原始/gzip 体积、启动中位数或内存;模型操作数不能冒充底层 SQL 条数。 保留 HTTP、事件和离线格式;必要的安全收紧明确说明触发条件,同步调用方、文档和断言。 单文件超过 40% 或跨多个文件的大重构先报告方案、收益和回滚路径;不做无度量重写、全仓格式化、无关改名。 新运行时依赖须说明现有依赖无法满足的原因、体积和回滚方式。

3. Phase 0:基线

依次记录命令、退出码、耗时和关键输出:

git status --short --branch
git log --oneline -5
node -v
Get-Command pnpm
pnpm --version
pnpm version:check
pnpm check:icons
pnpm lint
pnpm typecheck
pnpm docs:check
pnpm build

实际 pnpm 须匹配根 packageManager;DSH 配置见 AGENTS.md。需要前置时按 install → db:generate → 独立库 db:deploy → build:shared。 基线构建不要求迁移业务库。确需准备独立夹具时,先显式设置本次审计目录内的绝对 SQLite DATABASE_URL,再执行 pnpm --filter @classhelper/server db:deploy,完成后恢复原环境变量;不能沿用 Prisma 从业务 .env 读取的地址。专项优先使用会自建临时库的 verify 包装器。 大构建保存进程标识并轮询,不重复启动。出口:每条命令有本次结果;账本覆盖 A–I;P0 明确;汇报一次。

4. Phase 1–4:修复与优化

阶段 工作 出口
1 服务端/数据 清单 A–C;先鉴权、事务、竞态和错误码,再重复查询、序列化、索引 类型检查与相关隔离专项通过,快照/迁移完整,性能有测量
2 Web 清单 D;先构建量体积,再优化加载、守卫、请求、PWA、生命周期 构建与隐藏 UI 通过;样式、交互、组件注册不回归
3 桌面 清单 E;检查真实启动、桥接、缓存、设备、传输、更新及资源调用链 桌面构建和默认 quick 冒烟通过;未改岛不额外占用桌面
4 shared/脚本/CI 清单 F–G;三端契约、退出码、临时资源、跨平台 静态与专项通过;Linux 交付改动有 bash 和 Linux/CI 证据

先保留失败信号再改实现;断言更新须对应明确行为修正,不删断言、不跳过、不放宽鉴权。 缓存初始化或请求内重复计算时,权限变更仍实时生效,快照恢复/换库后初始化状态可重置。

5. Phase 5–6:文档和提示词

按源码同步 README、AGENTS、受影响帮助/开发文档、索引与官网;新增页登记 toc。 核对改动页面全部链接和图片目标,docfx 严格构建不能代替普通链接检查。 展示图保留 docs/images,回归留档 docs/screenshots;自动生成的新截图须人工核验后才交付。 保持官网根站与 /docs/ 布局、脚本版本落点;下载页核对在线元数据及离线兜底路径。 提示词保留目标、边界、现场入口、清单、出口、验证和失败处理,移除重复规则与固定模块/表/测试总数。 用零上下文代理自检 Phase 0 可执行性;修正缺口,不重复昂贵或有副作用的验收。 出口:格式、链接、docs:check、pages:build 通过;有提示词优化前后差异和自检结论。

6. 验证矩阵

以当前 package.json 为准;新改动只重跑受影响检查,最终汇总本批证据。

范围 检查
静态 lint、typecheck、check:icons、version:check
服务端 verify:e2e、verify:v14;权限加 verify:authz
审计/事务/PWA verify:audit;本次问题补夹具及指标
生命周期/迁移 verify:lifecycle、verify:client-migrations、临时旧库升级
课件/设备 verify:courseware、verify:clients-api
更新 verify:update-download、verify:update-installer、verify:client-agent
Web Web 包 build、verify:web:isolated
桌面 build:desktop、verify:desktop、相关逻辑专项
打包 verify:packaged --exe <portable 路径> --offline;服务端副本初始化复验
文档/官网 本次文件格式和链接、docs:check、pages:build、关键输出页检查

默认不执行真实系统指令、安装器、桌面视觉或外网;需要时在已有授权内处理。 记录真实通过/失败/阻塞,不引用历史数量。

7. Phase 7:版本与本地包

  1. 沿用已确认版本策略;未指定时此时确认,建议 patch。确认后通过 version 脚本修改并 version:check。
  2. 检查磁盘和 releases 当前目录,保留其他版本及同号可恢复副本。
  3. 后台执行 dist:all,核对实际产物并完成打包冒烟,不只看退出码。
  4. 写 ReleaseNotes-<版本>.md,说明变化、兼容注意、实际验证和文件清单。
  5. 计算 SHA256SUMS-<版本>.txt,使用 release.md 的上传名,附本地名映射、大小、摘要。
  6. Linux 正式包由 Linux runner 构建;无远端授权时明确待 CI,不用 Windows 交叉包冒充。
  7. releases 无 win-unpacked、staging 或解包副本;只清理本次生成且已确认的临时对象。

出口:Windows 包齐全、哈希可复算、packaged=true 离线两次启动通过,说明与包一致。 远端另按 release.md 在明确授权后执行,并等待 CI。

8. Phase 8:提交与交付

逐主题审阅 diff,排除凭据、业务数据、临时库、缓存和包;按中文 Conventional Commits 分组提交。 保留任务输入外的原有未提交工作,不把历史 result 改写为当前事实。

最终交付:A–I 账本及级别汇总;三项以上性能前后表和命令;验证矩阵及重试原因; 本地包路径/大小/SHA256、ReleaseNotes/清单;文档与提示词差异、自检;提交列表、未覆盖范围和后续。 完成判据:P0 有修复回归,P1 修复或有量化延期理由;各项无“待看”;源码、版本、文档和包一致; 受影响门禁通过或准确说明阻塞;有可审阅提交,没有把未执行检查写成通过。

9. 失败处理

情况 操作
工具版本不对 按 AGENTS 修正 DSH 路径并核验,不为转发壳修改依赖
Node 原生内存错误 留日志、限制并发或用满足 engines 的已安装 Node LTS 复验,记录版本
docfx 缺失/警告 按 build.mjs 提示处理、补 toc;装不上记阻塞,不关严格模式
electron-builder 受限 核对进程访问限制,用已授权环境;不据此重装依赖
失败/超时 查本次日志及进程,只清理本次资源;先复现,不放宽断言
写入受限 尝试授权范围内最小操作,拒绝时完成可行的只读工作并解释
外网/CI 未授权 完成本地交付,远端步骤记后续
中断恢复 先核对 git、日志、任务标识及进程,避免重复构建和覆盖结果