# Lime Quality Workflow

> Choose Lime validation commands for GUI, command/bridge, config, version, and PR-readiness changes.

- Skill: `limecloud/lime-quality-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add limecloud/lime-quality-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/limecloud/lime-quality-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: limecloud (https://skillmd.com/u/limecloud)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/limecloud/lime-quality-workflow

---


# Lime 工程质量

先读取 `internal/aiprompts/quality-workflow.md`（仓库事实源）。
如果需要快速找入口，再看 `internal/aiprompts/README.md`。

如果任务涉及：

- Electron IPC / App Server / legacy desktop facade / Bridge / mock / 前端 API 网关：再读 `internal/aiprompts/commands.md`
- 新旧并存、兼容层收口、旧入口回流：再读 `internal/aiprompts/governance.md`
- GUI 续测、页面交互验证：再读 `internal/aiprompts/playwright-e2e.md`

如果当前任务本身是在更新工程质量规则，先改仓库里的 `internal/aiprompts/quality-workflow.md`，再视需要同步本 skill 的参考文件。

## Fast Path

用户问“结论 / 复核 / 是否能删 / 是否 dead”时，先用 `3-8` 行给结论和关键证据；不要自动升级成 `verify:local`、`test:contracts`、GUI smoke 或全量质量矩阵。只有用户要求继续实现、修文档、补守卫、提交前验证，或改动已经真实触达 GUI / 命令 / bridge / 配置边界时，才进入完整质量工作流。

目录级旧实现若已脱离构建 / workspace manifest、当前工作树已物理删除或 staged delete、已有 current owner 承接，且边界守卫能防回流，可直接按目录级 `dead / deleted / forbidden-to-restore` 判定；不要求逐文件证明业务语义无价值。`internal/exec-plans/**`、旧路线图和 git history 里的旧路径默认是历史 evidence，不是当前质量缺口。

## 何时使用

当任务涉及以下任一问题时，使用本 skill：

- 不确定这次改动最少该跑哪些校验
- 改了 GUI 壳、DevBridge、Workspace、前端主路径
- 改了 Electron IPC、App Server JSON-RPC、legacy desktop facade、Bridge、mock、`safeInvoke` / `invoke`
- 改了配置结构、版本文件、依赖或发布相关边界
- 需要判断“代码通过检查”是否已经等于“可以交付”

## Codex 工作流

### 0. 路线图任务先校准目标

如果用户明确要求对齐路线图主线，先在脑内完成这三个判断，再决定跑什么校验：

1. 本轮改动对应路线图哪一节
2. 它推进的是主链，还是只是从属清理
3. 本轮最低门槛校验是否能证明这一步真的在向目标收敛

如果答案只是“代码没报错”，但无法证明主线前进了，就要先纠偏，再谈校验。

如果当前改动只是让已经过时、且明确无需兼容的旧实现继续通过校验，不要把这轮验证当成有效进展；应先回到主线，删除或下线旧实现后再验证 current 路径。

校验前同时检查新增命名：新程序、目录、crate/package、命令、API 网关、类型、模块和脚本默认不得添加 `Lime` / `lime_` / `lime-` 品牌前缀；除非属于历史兼容、对外品牌标识或外部生态固定名，并已在计划中说明。

如果新增的是 AI Agent / runtime / host integration / 跨 App 复用能力，质量检查还必须确认它走 App Server JSON-RPC current 主链；Electron 只能作为 Desktop Host bridge；`agent_runtime_*` 只能作为 retired guard / 历史 evidence，已删除 runtime 不能恢复为兼容 facade 或新业务逻辑事实源。

质量检查还必须确认生产路径没有 mock fallback。`safeInvoke` / `invoke`、Electron Host、App Server sidecar、GUI smoke 和业务 E2E 不能回退 `mockPriorityCommands`、`defaultMocks`、`invokeMockOnly`、renderer mock fallback 或 mock backend；这些只允许测试夹具显式使用。

如果本轮涉及 Agent Runtime / Claw chat 主路径、历史恢复、流式事件、工具终态、消息列表完成态、代码产物工作台或 Plugin task read model，进入 GUI smoke / Playwright 前先跑 `npm run smoke:agent-runtime-current-fixture`。该入口必须保持非 live Provider、非 App Server mock backend、非 renderer mock fallback，只作为 current fixture 回归门槛，不替代真实 Electron / Playwright 闭环。修 streaming 卡住、无法停止、输入框不可用、用户消息 / assistant 输出不可见时，terminal 回归必须覆盖 App Server current `turn.completed` 投影后的 `turn_completed`，不能靠固定 timeout / grace timer 合成 `final_done`。若问题直接涉及历史详情 hydrate、最近对话恢复或归档 / 反归档后的 read model 读取，聚合 guard 通过后再显式跑 `npm run smoke:agent-session-history-electron-fixture`；该入口启动真实 Electron，但使用 `APP_SERVER_BACKEND_MODE=unavailable`，不调用模型后端。若问题直接涉及代码产物、artifact snapshot、从历史打开工作台或工作台面板渲染，聚合 guard 通过后再显式跑 `npm run smoke:code-artifact-workbench-electron-fixture`；该入口启动真实 Electron 并使用 external fixture backend，不调用正式模型。若问题直接涉及 Claw 输入框不可见、用户输入不显示、assistant 输出卡住、自然语言新闻请求或 `agentSession/turn/start` GUI 链路，聚合 guard 通过后再显式跑 `npm run smoke:claw-chat-current-fixture`；该入口启动真实 Electron 但仍使用 external fixture backend，不调用正式模型，且应覆盖 `message.delta + turn.completed` 单终态完成态，不要求 `turn.final_done`。

如果涉及 Electron packaging / installer / signing / notarization / updater metadata，质量检查必须确认 current 事实源是 `forge.config.mjs`、`electron-forge package`、`electron-forge make` 与 Forge 官方 maker；旧 builder 配置 / CLI、自定义 Windows installer maker 与旧 YAML / blockmap updater metadata 按 `dead` 处理，不得继续作为文档、CI、质量任务、i18n evidence 或守卫输入。运行时更新以 `electron/updateHost.ts` + Electron 内置 `autoUpdater` 为 current；Windows installer 必须走 Forge Squirrel。

如果涉及新增脚本或 `scripts/` 目录治理，质量检查必须确认 `scripts/` 根目录和一级领域目录没有继续膨胀。新增可执行脚本默认进入已有 `scripts/<domain>/`、`scripts/lib/` 或所属 package；根目录或新领域目录例外必须同步 `scripts/README.md`、`scripts/script-root-governance-baseline.json` 和执行计划。最低校验包含 `npm run governance:scripts`。

如果本轮要继续前端全量 Vitest，先检查 `.lime/test/vitest-smart-last-run.json`。已有失败、中断、running 或 pending 批次时，默认用 `npm run test:resume`，或用 `npm test -- --from-batch <N>` / `npm test -- --only-batch <N>` 精确补批次；不要无理由从第 1 批重跑。局部源码改动优先用 `npm run test:related -- <files>` 或 `npm run test:changed -- <ref>` 缩小反馈环，再按发布 / GUI 风险决定是否扩大验证。CI 横向压缩前端全量时可用 Vitest `--shard=<index>/<count>` 做分片；本地失败续跑仍以 `.lime/test/` 状态为准。

### 1. 先判断改动类型

先把当前改动归到最接近的一类：

- 普通前端改动
- Electron IPC / App Server / legacy desktop facade / Bridge / mock 改动
- GUI 壳 / Workspace / 页面主路径改动
- 配置结构改动
- 版本相关改动
- Rust 模块改动
- 需要真实交互验证的 GUI 改动

如果改动同时落在多类，按最高风险边界组合校验，不要只跑最轻的一层。

### 2. 先跑最贴边界的最低门槛

默认参考仓库里的最低门槛矩阵：

- 普通前端改动：`npm run verify:local`
- Electron IPC / App Server / legacy desktop facade / Bridge / mock 改动：`npm run verify:local` + `npm run test:contracts`
- GUI 壳 / Workspace / 页面主路径改动：`npm run verify:local` + `npm run verify:gui-smoke`
- Agent Runtime / Claw chat 主路径改动：先跑 `npm run smoke:agent-runtime-current-fixture`，再按 GUI / bridge 风险补 `verify:gui-smoke`、`test:contracts` 或 Playwright
- 配置结构改动：`npm run verify:local`
- 版本相关改动：`npm run verify:app-version`
- Rust 模块改动：先跑受影响 crate / 模块定向测试，再决定是否全量 `cargo test`
- 真实交互验证：先跑 `npm run verify:gui-smoke`，再进入 Playwright MCP

### 3. GUI 产品不要只看“代码通过”

如果改动影响 GUI 壳、Bridge、Workspace、主页面路径，不要把以下结果当成交付结论：

- `lint` 通过
- `typecheck` 通过
- 前端单测通过
- Rust 单测通过

至少还要确认：

- `DevBridge` 已就绪
- 默认 workspace 准备态可用
- 最小 GUI smoke 已跑通或明确说明为什么当前环境不能跑

### 4. 边界类改动必须成组检查

如果改动涉及命令、桥接、配置、版本或依赖，至少检查这些成组事项有没有同步：

- 命令边界：前端调用、Electron host / preload、App Server protocol / client、legacy Rust 注册、治理目录册、mock 集合
- 配置结构：schema、校验器、消费者、文档
- 版本相关：`package.json`、Electron 配置、`lime-rs/Cargo.toml`、App Server manifest
- 依赖相关：`package-lock.json`、`lime-rs/Cargo.lock`

Electron packaging / release 相关改动还必须成组检查：`forge.config.mjs`、`electron/forge/*`、`package.json` / `package-lock.json`、release workflows、`scripts/run-electron-package-dir.mjs`、`scripts/stage-electron-release-assets.mjs`、`scripts/verify-electron-package-resources.mjs`、entrypoint/docs guards、contract guard 和 `internal/roadmap/appserver/release-updater.md`。

脚本目录治理相关改动还必须成组检查：`scripts/README.md`、`scripts/script-root-governance-baseline.json`、`scripts/check-scripts-governance.mjs`、`scripts/lib/scripts-governance-core.mjs` 与 `package.json#scripts`，并运行 `npm run governance:scripts`。

不要只改实现，不补文档或锁文件。

### 5. UI 改动必须补稳定回归

如果改动是用户可见 UI：

- 优先补 `*.test.tsx` 里的关键文案、状态、交互断言
- 如果目标区域已有 snapshot 或结构化快照机制，沿用现有机制
- 不要因为“只是 UI 细节”就跳过回归

新增或重写前端逻辑时，先判断测试分层：

- 筛选、分组、formatter、request builder、runtime 参数投影、状态机、reducer 等可纯化逻辑，必须优先抽到 View Model / projection / selector / helper，并用 `*.unit.test.ts` 覆盖。
- `*.test.tsx` / component 测试只保留 React 渲染、真实 DOM 事件、hook 生命周期和少量关键接线回归；不要把大量业务分支继续塞进挂载测试。
- 如果暂时无法抽成纯单元，必须在路线图或执行计划写明原因、风险层级和退出条件，避免后续 Agent 把临时组件测试当成新规范。
- 跑 `npm run test:layers:stats` 时关注 `Component unit-migration candidates`，把它作为后续抽 VM 的候选名单，而不是当前失败门禁。

### 6. 本地入口与 CI 口径保持一致

优先使用仓库已有统一入口，而不是手工拼临时命令：

```bash
npm run verify:local
npm run verify:local:full
```

如果需要解释为什么 CI 触发某个检查，回到：

- `.github/workflows/quality.yml`
- `scripts/quality-task-planner.mjs`
- `scripts/quality-task-selector.mjs`
- `scripts/local-ci.mjs`

不要在汇报里发明一套独立于仓库实际脚本之外的“建议流程”。

### 7. 交付结论必须明确

汇报时不要只说“我跑了测试”。

必须明确说明：

- 本次改动属于哪类风险
- 实际跑了哪些最低门槛命令
- 哪些命令因环境限制没跑，限制是什么
- GUI 主路径是否已验证
- 还差哪一步才算可交付

## Codex 约束

- Lime 是 GUI 桌面产品，不要把“静态检查通过”等同于“产品可交付”。
- 优先使用仓库已有脚本，不要临时发明平级校验脚本。
- 命令 / Bridge / mock 改动，默认把 `npm run test:contracts` 纳入最小验证集合。
- 生产路径如果靠 mock 才通过，不得标为可交付；只能记录为 current 主链阻塞缺口。
- GUI 壳 / Workspace / 主路径改动，默认把 `npm run verify:gui-smoke` 纳入最小验证集合。
- Rust 校验默认先小后大，不要一上来无差别全量 `cargo test`。优先用 `npm run test:rust:changed`、`npm run test:rust:related -- <paths...>`、`npm run test:rust:unit -- -p <crate> <filter>`、`npm run test:rust:integration -- -p <crate> --test <target>` 收缩范围；`changed/related` 会按 `lime-rs` 路径推导 workspace crate 并用 `cargo metadata` 扩展反向依赖，workspace manifest / lockfile 边界自动扩大到 `--workspace`，无法映射 crate 时 fail closed；冷编译慢时优先复用 `lime-rs/target`、增量缓存和可选 `RUSTC_WRAPPER=sccache`，只有工具链和 CI 已配置后才把 `cargo nextest run` 作为默认门禁。
- `verify:local` 的 smart 模式遇到 Rust 路径改动应走 `test:rust:changed`，`--staged` 走 `test:rust:related -- <staged-rust-paths>`；`--full`、无改动兜底和 workflow 全局风险才保留 workspace 全量 `cargo test`。
- 如果因为环境限制无法完成 GUI smoke 或交互验证，必须在结果里明确写出来，不能假装已经验证。
- 过时实现即使校验通过，也不等于 current 路线图可交付；对已判 `dead` / `deprecated` 且明确无需兼容的路径，不要为了“测过”继续保留。

## 输出要求

汇报结果时，始终给出：

1. 本次改动属于哪类风险
2. 实际执行了哪些校验
3. 哪些校验因为环境限制未执行
4. 当前是否达到 Lime 的可交付门槛
5. 如果还未达到，下一步最该补哪一项

如果任务来自路线图，再额外说明：

6. 这轮校验证明了哪条路线图主线在前进，而不是只证明局部代码可运行