Skip to content

Latest commit

 

History

History
194 lines (139 loc) · 20.3 KB

quality-workflow.md

File metadata and controls

194 lines (139 loc) · 20.3 KB

工程质量工作流

状态:current / Refactor v2

本页定义 Lime 的最低交付门禁。测试策略与作者规则见 ../test/testing-strategy-2026.md,第二期覆盖计划见 ../roadmap/benchmark/README.md。

唯一受测业务主链

Desktop Host / CLI-TUI Host
  -> App Server JSON-RPC
  -> RuntimeCore
  -> Thread / Turn / Item projection
  -> GUI / terminal projection

测试必须说明覆盖了链路中的哪一段。旧命令、旧 runtime、生产 mock fallback、外部数据集 runner 或历史 release report 通过,均不能证明 current 产品链可交付。Desktop 与 Terminal 可以有各自的 host/interaction 测试,但业务状态机、协议 fixture 和 canonical Thread/Turn/Item 断言必须复用同一事实源。

选择最低门禁

先跑最贴风险的定向测试,再按跨层影响扩大。全量检查不能替代真实 GUI 或跨层证据;跨层证据还必须说明是否实际经过目标进程边界。

只读调查、skill 与纯规则文档更新先检查格式、链接、命令存在性与相关文档守卫;没有产品代码变化时不启动全量 Rust 或 Electron。若改变了执行脚本、public boundary 或实际门禁,再验证对应行为。verify:tasks 依据整个工作树规划;有并行脏改动时不把其结果当成本轮写集的验证要求。

改动 最低验证
skill / 纯规则文档 skill 格式校验、引用/命令存在性、相关文档守卫;不冒充产品验证
纯 TypeScript selector/projection/parser npm run test:related -- <paths...>;必要时 lint/typecheck
React 组件/hook related unit/component;用户可见变更补五语言与稳定 DOM 断言
Rust crate npm run test:rust:related -- <paths...>;跨 crate 行为追加 integration layer
App Server method/protocol/schema/generated client npm run test:contracts + 公共 JSON-RPC 集成测试
Agent loop/queue/turn/item/read model Rust related/integration + npm run smoke:agent-runtime-current
App Server Rust session/transport cargo test --manifest-path "lime-rs/Cargo.toml" -p app-server-client + npm run smoke:app-server-stdio
TUI reducer/render/composer cargo test --manifest-path "lime-rs/Cargo.toml" -p tui + 稳定 TestBackend 断言;交互变更补 npm run smoke:tui-gate-b
CLI 参数/非交互 Agent 流程 cargo test --manifest-path "lime-rs/Cargo.toml" -p cli + npm run smoke:cli-gate-b 或受影响 CLI surface fixture
CLI npm launcher/平台包/发布顺序 npm --prefix packages/cli test + smoke:cli-npm-gate-b + release/CLI guard
tool/approval/sandbox/context owner 集成测试 + current runtime fixture;命令边界追加 contracts
MCP/Skills/Multi-Agent owner 集成测试 + npm run smoke:mcp-current 或对应 current fixture
Provider/lowering/multimodal provider request capture + Rust related/integration + modality contracts
GUI 壳/Workspace/主路径 related tests + npm run verify:gui-smoke + 风险匹配的 Gate A
Electron/preload/IPC/read model/恢复 npm run test:contracts + 对应真实 Electron Gate B fixture
版本/Forge/workspace manifest npm run verify:app-version;release 边界追加 Forge guard
脚本目录 npm run governance:scripts
legacy/dead surface 删除 npm run governance:legacy-report + 相关负向回流守卫

默认本地入口是 npm run verify:local。需要完整本地门禁时使用 npm run verify:local:full。前端全量测试中断后使用 npm run test:resume,不要从第一批无差别重跑。 Rust 分层测试入口和本地门禁的 Cargo 测试默认通过独立临时 LIME_CONFIG_PATH、LIME_HOME 和显式 LIME_CREDENTIALS_STORE=file 运行,结束后清理,避免读取或改写开发者配置与系统密钥库;显式传入配置路径时保留该文件,凭据仍隔离。显式 live 测试保留调用方环境。直接运行 cargo test 时需自行提供隔离配置与凭据环境;真实 OS keyring 测试使用独立随机身份并自行清理,不能把本机配置污染导致的失败改成生产静默 fallback。 verify:local 进入前端测试前同样读取既有 Vitest 状态;存在失败、中断、运行中或未完成批次时委托 npm test -- --resume。完成态不能作为新源码的测试缓存,无未完成批次时仍运行新一轮;损坏状态显式失败。子进程被信号中断、启动失败或未返回退出状态时,聚合门禁必须失败;后续单项通过不能覆盖已中断阶段。标准和 smoke Vitest 配置都排除 .lime 生成产物,发布候选副本不参与源码测试发现。 续跑复用当前测试发现与live过滤,新增文件追加pending批次,保留旧批次与失败起点并跳过已passed批次。它不按源码摘要失效旧通过结果;续跑期间改动已通过的测试或其owner时,另跑受影响定向回归并记录证据。

Agent / GUI 主链实现前,在执行计划填写 Agent Verification Contract。先定向验证,再运行受影响 current fixture、GUI smoke 与默认本地门禁;新改动、失败或未关闭风险才触发扩大或重跑。

Rust 依赖审计

lime-rs/deny.toml 是 Rust 许可、公告和来源门禁的唯一配置。安全漏洞与 unsoundness 必须修复,不能降级或用停维例外代替修复。advisories.ignore 只登记已核对的具体停维公告;每项必须记录实际依赖链、运行时输入边界、无安全升级路径的依据和负责迁移的现役 owner。依赖或消费者变化、出现对应安全公告时重新复核;每次发布复核现有例外并清理已不再命中的项。

本地加密凭据采用 age 的 scrypt 接口和安全维护分支,不启用 HPKE/P-256。TUI 从 two-face 加载内置语法和主题,不启用 syntect/yaml-load 或加载外部 bincode。配置与技能 frontmatter 使用 YAML 官方组织维护的 yaml_serde,通过 Cargo package rename 保留现有 serde_yaml 调用名;没有第二套解析器。

network-proxy/vendor/rama-dns 通过 Cargo patch 替换同版本注册表依赖,保留 current Rama 接口并升级到 Hickory 0.26 安全分支;来源、源码摘要、许可证和必要 API 适配登记在该目录的 UPSTREAM.json。不得重新引入 Hickory 0.25 或并行编译第二份 DNS 实现。

Linux 密钥库仍通过 infra 的 keyring/Secret Service owner;zbus 类型合并的停维通知不等于原生凭据迁移完成。更换该依赖链必须验证 Linux 的密钥库不可用/锁定、类型化错误、加解密与权限合同,并补 macOS/Windows 原生回归。

Codex 对齐与旧资产迁移

GUI 对齐范围及用户明确保留差异以 design-language.md 为准。公开 Rust 源码决定共享协议和 runtime 语义;Desktop 布局与模块结构由指定安装包的 REA Evidence 或已获准的运行观察证明。记录版本、摘要、Evidence ID 和覆盖限制,不能把压缩局部符号当成原始名称,不能把静态分析写成运行证据。

每个切片的账本至少包含上游模块/可确认符号、Lime current owner、行为合同、调用者、删除项和验证。检查结构、函数、类型、类与命名迁移,以及多模型、专家广场和消息渠道是否继续走既有 owner;同名文件数和视觉相似度不证明全面对齐。

直接替换时同步迁移或删除旧代码、文档、测试、snapshot、fixture、扫描规则与白名单:

  • 有效风险由 current owner 的行为测试继续覆盖,断言输入、输出、identity、状态转移与失败终态。
  • 过期组件形状、旧 DOM 布局、已删除命令的正向测试直接迁出,不为其恢复实现或加 alias。
  • 护栏守住唯一 owner、协议、权限、持久化与 production mock 边界;旧文件名和结构扫描只能作为相关回流守卫,不能锁死合法对齐。
  • 旧计划和原始分析可作为历史证据,但不保留与 current 事实源冲突的 active checklist 或导航。

完成度分别报告规则/研究、行为、结构/命名、清理与产品验证,并写清分母;不得把某个切片 100% 当成整体 GUI 对齐 100%。

证据等级

等级 证明内容 不能证明
Unit 纯转换、状态转换、selector/projection 的确定性 跨模块接线、进程边界
Domain integration current Rust/TS owner 与可控依赖的协作 App Server 公共协议、Electron
App Server integration public JSON-RPC、notification、read model、恢复 Renderer/Electron 可见状态
Current fixture RuntimeCore/provider fixture/tool/event terminal 主链 live provider 或真实桌面壳,除非 fixture 显式启动 Electron
Gate A browser/Renderer projection、DOM、交互、可见状态 Electron main、preload、IPC
Gate B Electron、preload/IPC、app_server_handle_json_lines、App Server、runtime/read model、GUI live provider,除非场景显式使用并记录
CLI Gate B 真实 lime exec、stdio transport、App Server、runtime/read model、CLI 可见输出 TUI 交互、Desktop Host、live provider,除非场景显式使用并记录
TUI Gate B 真实 lime、PTY、alternate screen、键盘输入、App Server、runtime/read model、TUI 可见输出和终端恢复 Desktop Host、live provider,除非场景显式使用并记录
Live/eval 指定 provider/model/config 下的能力与稳定性 其他 provider、地区或平台的普遍正确性
Platform/packaged 实际 macOS/Windows 和打包产物 未运行平台

npm run test:e2e 是 Vitest 的 e2e 分层入口,不等于 Electron Gate B。Gate A 不能替代 Gate B。

smoke:agent-runtime-current 聚合 Code Mode、会话恢复和运行中 Turn 恢复三个真实 Electron 入口。只计实际成功执行且满足合同的场景;没有启动、提前失败或仅静态 guard 通过均不能写 Gate B。explicit external / unavailable backend 要记录绕过的执行层,不冒充 live provider 或完整 production backend 证据。

测试作者合同

对齐 Codex 的测试标准:

  1. Agent 逻辑变更优先写 integration test;单元测试只守住真正独立的代数、转换和状态转移。
  2. App Server 测试必须从 public JSON-RPC 进入,不直接调用私有 handler 伪造跨层成功。
  3. Provider fixture 必须捕获结构化请求;优先断言完整 request、event、Thread/Turn/Item 或 read model 对象。
  4. 等待业务事件或 terminal predicate,不用固定 sleep、长 grace timer 或测试侧合成 completed。
  5. 测试不修改进程全局环境;从 builder 注入路径、配置、时钟、provider 和 capability。
  6. 每个测试使用隔离 app data、workspace、数据库和端口;不得依赖真实用户目录或上一个测试留下的状态。
  7. 不测试静态定义值,不为已删除逻辑保留正向行为测试。旧名字只允许出现在负向 guard 或不可变 evidence。
  8. 测试 helper 只承接环境与观察能力,不暴露第二套 production API;仅一个测试使用的 helper 留在测试文件内。
  9. 测试失败信息必须包含 scenario/identity/expected/actual,不能只报 timeout。
  10. 修复线上或 Gate 缺陷时,在最接近根因的 owner 层补回归;必要时再补一条跨层产品证据。

完成回归必须区分 public JSON-RPC notification turn/completed、runtime event 与 Renderer turn_completed,并关联同一 Thread/Turn。请求使用 current thread/*、turn/*、item/* 与 server request 合同;历史私有 method 不作为新增测试入口,固定等待或测试侧合成 terminal 不算完成证据。

前端分层

  • *.unit.test.ts:纯 View Model、projection、selector、parser、formatter、state machine、request builder。
  • *.component.test.tsx:React 渲染、DOM 事件、hook 生命周期和少量关键接线。
  • *.contract.test.ts:protocol、typed gateway、Desktop Host、App Server client、catalog 边界。
  • *.integration.test.ts:文件系统、进程、本地 server、数据库或多模块流程。
  • *.e2e.test.ts:Vitest 内的显式产品级流程;仍需按证据等级说明是否触达 Electron。
  • *.live.test.ts:真实网络/provider,默认跳过并要求显式授权。

复杂组件中的筛选、分组、状态机和 runtime 参数投影必须先抽到纯 owner。component test 不重复铺满业务分支;npm run test:layers:stats 的 migration candidates 作为治理输入,不是失败门禁。

Rust 分层

Rust 先 related、后 integration、再按风险扩大:

npm run test:rust:related -- <paths...>
npm run test:rust:integration:related -- <paths...>
npm run test:rust:unit -- -p <crate> <filter>
npm run test:rust:integration -- -p <crate> --test <target>

Agent/runtime 核心行为需要跨 owner 时,不把所有 case 堆进实现文件的 inline unit tests;使用专用测试模块或 integration target。cargo nextest 只在工具链、archive 和 CI shard 稳定后作为执行加速器,不改变本地 related-first 规则。

Windows restricted execution 改动必须把 windows-sandbox-runner.exe 与 app-server.exe、code-mode-host.exe、windows-sandbox-setup.exe 成组构建。Electron Windows resources 和 app-server.release.json 必须包含 runner 及其 windowsSandboxRunnerSha256,verify-package-resources 对缺失或 digest 漂移 fail closed。源码/静态门禁不替代 windows-restricted-execution-evidence-v3 八项真实 Windows/MSVC 矩阵;Quality run 32975574520 已在 SHA 19e08daa2 取得当时七项矩阵的 7/7 历史基线,当前矩阵另含 unelevated managed-network preflight 拒绝,后续 Windows sandbox 改动必须保持 current matrix 和 packaged resource 守卫全绿,否则 readiness 回退为 fail closed。

Gate A 与 Gate B

Gate A 使用可控数据验证 Renderer projection、DOM、交互、错误文案和五语言资源。它可以使用显式 fixture,但证据必须标明 test-only。

Gate B 必须同时证明:

  1. 真实 Electron Desktop Host 和 preload/contextBridge 存在。
  2. IPC 命中 app_server_handle_json_lines。
  3. 命中场景声明的 current App Server method。
  4. runtime/read model/GUI 使用同一 thread/turn/item identity。
  5. production mock fallback 命中为零。
  6. 场景以真实 terminal 或明确 pending 状态结束,不靠固定等待猜测。

需要人工点击、截图或复用会话时继续阅读 playwright-e2e.md。

CLI Gate B 必须同时证明:真实 lime exec 二进制、非 mock app-server 子进程或受控 daemon、initialize/initialized 握手、current v2 method、同一 thread/turn/item identity、CLI 完成输出和子进程回收。TUI Gate B 在此基础上还要覆盖真实 PTY、alternate screen、键盘输入、TUI 可见完成态和终端模式恢复。纯 reducer snapshot 只属于 Unit,CLI smoke 也不冒充 TUI Gate B。

CLI npm packaged evidence 还必须通过 npm run smoke:cli-npm-gate-b 从实际根包 launcher 解析 optional platform package,并证明 sibling App Server、参数/stdin/stdout、退出码与 signal 语义;平台 tarball 内容检查必须覆盖 lime、app-server、code-mode-host、Windows sandbox helpers 和动态库。source-string guard 或单独运行 Rust target 不证明 npm 安装可用。未在对应 OS/arch 实跑的包只能算 staging/结构证据,不得提升为 Platform/packaged 通过。

生产与测试边界

  • 生产 Renderer、Electron、App Server 和 GUI smoke 不得回退 defaultMocks、mockPriorityCommands、invokeMockOnly、renderer mock 或 App Server mock backend。
  • 测试可以显式使用 src/lib/desktop-host/ fixture、unavailable backend 或受控 external backend,但不得把它们作为可交付的生产链证据,也不能冒充 live provider 证据。
  • 用户可见文案覆盖 zh-CN、zh-TW、en-US、ja-JP、ko-KR;protocol enum/schema/evidence facts 不本地化。
  • live test 必须显式授权、隔离凭证、记录模型与配置,并禁止保存 secret、完整真实用户内容或敏感本地路径。

旧测试处理

分类 处理
current 受测 owner 与 v2 一致,保留并赋稳定场景 ID
rewrite 风险仍有效但入口/fixture/断言过时,迁移后删除原测试
merge 重复 boundary/source-string guard 合并到 owner 级测试或治理扫描
dead 测静态值、旧命令正向行为、已删除 runtime 或脱离构建图,直接删除
live-only 移出默认门禁,显式授权运行

不要为了维持旧报告或旧命令可运行而恢复 wrapper、catalog、fixture 或 mock。

架构确认与汇报

重大架构变更必须更新 architecture.md,并由责任开发者在执行计划和 PR 描述完成架构确认。仅新增或重写测试通常不构成架构变更;如果为了可测性改变 public boundary、owner 或依赖方向,则按重大变更处理。

交付汇报必须说明:风险类型、实际命令、证据等级、未执行原因、GUI/Gate B 状态、remaining blocker。路线图任务还要说明本轮证明了哪条主链,而不只写“测试通过”。

常用入口

npm run test:related -- <paths...>
npm run test:rust:related -- <paths...>
npm run test:contracts
npm run smoke:agent-runtime-current
npm run verify:gui-smoke
npm run governance:legacy-report
npm run verify:local