knowledge-engineering-quality-and-delivery

## Module Structure 该域不是单一模块，而是把确定性测试、付费模型轨迹、制品级门禁和 tag 驱动发布串成一条跨 CLI、Web、ACP、TUI 与文档的交付链。 ### Directory Layout - `packages/cli/tests/` — CLI 核心的 unit、integration、CLI、E2E、real-api、performance、snapshot 与 security 测试 - `packages/cli/web/tests/` — Web 组件、Store、服务和 bundle 预算测试 - `packages/cli/scripts/` — 测试运行器、资格编排、构建、凭据加载与发布脚本 - `scripts/` — 仓库级发布辅助和独立基准脚本 - `.github/workflows/` — CI、tag 发布与 Docs Pages 部署 - `docs/` — 中文默认站点、英文镜像、设计规格和准出证据 - `package.json`、`packages/cli/package.json` — 工作区命令、发布包边界与版本 - `biome.json`、`packages/cli/vitest.config.ts`、`packages/cli/web/vitest.config.ts` — 静态检查与测试项目定义 ### Key Entry Points - `createQualificationPlan()` in `packages/cli/scripts/qualification.ts` — 定义本地 14 项和生产 16 项顺序门禁 - `testTypes` in `packages/cli/scripts/test-config.js` — 定义各 Vitest 项目、超时、环境和发布阻断文件白名单 - `packages/cli/scripts/build.ts` — 构建 CLI ESM 产物并把 Web 输出到同一发布目录 - `.github/workflows/ci.yml` — 聚合确定性 CI 作业 - `.github/workflows/publish.yml` — 校验 tag/包版本并通过 npm Trusted Publishing 发布 - `.github/workflows/docs.yml` — 生成文档站 changelog 并部署 Pages ## Branching Table | 维度 | 本地或确定性分支 | 生产或发布分支 | |------|------------------|----------------| | 资格入口 | `qualify:local` 顺序执行 14 项且不接触付费凭据 | `qualify:production` 在本地门禁后追加 Chromium preflight 和付费真实 API | | 测试证据 | unit/integration/E2E 允许隔离、mock 或本地 fixture | release matrix 要求真实 Provider、production surface 和宿主侧副作用证据 | | 覆盖率与性能 | coverage 插桩运行除 performance 外的项目 | performance 在 production build 后独立运行，避免插桩污染时序 | | 发布准备与发布 | 本地负责冻结候选、版本、双语 changelog、资格证据与 tag | tag workflow 只校验版本、构建、幂等发布 npm/GitHub Release | | 文档源与站点产物 | `docs/`、`CHANGELOG.md`、`CHANGELOG.zh.md` 是 Git 可见源 | `docs/changelog.md` 与 `docs/en/changelog.md` 在部署时生成且被忽略 | | 浏览器依赖 | npm 包携带固定 Playwright 运行库但不下载 Chromium | 浏览器门禁要求显式安装并通过离线 launch/close preflight | ## Affected Scope - `packages/cli/src/` — 每个运行时变更都要映射到确定性回归与适当的真实轨迹 - `packages/cli/web/src/` — Web 行为同时受组件测试、production Chromium 轨迹和 bundle 预算约束 - `packages/cli/tests/` — 汇集本地回归、跨表面驱动、资源回收和发布矩阵 - `packages/cli/scripts/` — 决定测试项目选择、超时、凭据隔离、构建顺序和本地发布行为 - `.github/workflows/` — 把静态检查、跨平台 smoke、coverage、安全审计、npm 与 Pages 分成独立作业 - `packages/cli/package.json` — 发布版本、npm 文件清单、运行时依赖和质量命令的权威入口 - `CHANGELOG.md`、`CHANGELOG.zh.md` — 英文包内更新信息与中文同步发布记录 - `docs/` — 用户行为契约、设计冻结记录和可审计的资格证据 ## Gotchas - `bun run test:all` 不是完整准出：它不执行资格编排的类型、格式、lint、构建、浏览器 preflight 和付费矩阵，发布判断必须使用 `qualify:local` 与 `qualify:production` (`package.json`, `packages/cli/scripts/qualification.ts`) - tag 触发的发布工作流不重新运行测试或真实 API；错误地把 `publish.yml` 成功当作候选质量证明，会发布仅“可构建”的未资格版本 (`.github/workflows/publish.yml`, `docs/testing/qualification.md`) - 当前 `release:patch` 路径由配置关闭测试、代码质量和安全检查，只能做版本/tag 编排，不能替代冻结 SHA 上的资格流程 (`packages/cli/release.config.js`, `packages/cli/scripts/release.js`) - `tests/e2e/` 的名称不代表生产端到端证据，其中仍有 mock 与占位断言；发布级行为由显式 `realApiQualification.files` 决定 (`packages/cli/tests/e2e/core-features.test.ts`, `packages/cli/tests/e2e/flows/chat-flow.test.ts`, `packages/cli/scripts/test-config.js`) ## Architecture - 资格编排严格串行且首个非零退出即停止，避免后续通过项掩盖更早的失败；CI 则拆成并行作业，最终由 `ci-pass` 汇总失败与取消状态 (`packages/cli/scripts/qualification.ts`, `.github/workflows/ci.yml`) - 交付证据分为确定性代码门禁、真实 Provider/宿主轨迹、冻结候选 evidence 文档和 tag 后 registry/Release 验证，任一层都不能由另一层替代 (`docs/testing/qualification.md`) - 构建把后端与 Web 放入 `packages/cli/dist/`，npm 包再通过 `files` 白名单发布该目录及少量运行时资产；性能与 Web 制品测试因此必须位于构建之后 (`packages/cli/scripts/build.ts`, `packages/cli/package.json`, `packages/cli/scripts/qualification.ts`) ## Decisions - 公共 CI 不注入付费 Provider 凭据，真实 API 是发布者在候选 SHA 上显式运行的门禁；这避免 secret 暴露，但意味着 tag workflow 本身不是完整准出权威 (`docs/testing/qualification.md`, `.github/workflows/ci.yml`) - 每个独立功能或修复单独发布 patch，并让版本、双语 changelog、用户文档和资格证据共同描述同一个行为增量 (`AGENTS.md`) ## Patterns - 高风险功能通常同时增加确定性单测、真实 API 跨表面轨迹、`test-config.js` 白名单断言、资格文档和最终版本元数据，缺一项会留下未覆盖分支 (`packages/cli/tests/unit/scripts/test-runner.test.ts`, `docs/testing/qualification.md`) - 近期开版提交稳定地把 `packages/cli/package.json`、`CHANGELOG.md` 与 `CHANGELOG.zh.md` 一起变更，防止包版本与两种语言的发布记录漂移 (`packages/cli/package.json`, `CHANGELOG.md`, `CHANGELOG.zh.md`, `git:1ce74b03`) ## Conventions - 中文文档位于 `docs/` 根，英文镜像位于 `docs/en/`；行为变化需要同步两边，而生成的站点 changelog 只能由部署工作流复制 (`AGENTS.md`, `.github/workflows/docs.yml`) ## Branching Behavior - 非付费检查会主动移除 real-API 开关、凭据文件位置和各 Provider key/model 变量；只有标记为 `paid-api` 的最后一项接收物化后的凭据环境 (`packages/cli/scripts/qualification.ts`) - production 分支在真实 API 前执行不联网的 Chromium 检查，preflight 失败会令顺序执行器停止，从而保证零 Provider 请求 (`packages/cli/scripts/qualification.ts`, `packages/cli/tests/unit/scripts/qualification.test.ts`) - coverage 分支排除 wall-clock performance，而本地资格分支在构建后单独执行 performance；新增制品性能断言时必须同时考虑这两个入口 (`packages/cli/vitest.config.ts`, `packages/cli/scripts/test-config.js`, `packages/cli/scripts/qualification.ts`) - 发布分支以 `packages/cli/package.json` 的版本匹配 `v*.*.*` tag；仓库根 `package.json` 的私有 monorepo 版本不是 npm 发布版本 (`package.json`, `packages/cli/package.json`, `.github/workflows/publish.yml`) ## Child Knowledge Nodes - `./unit-integration-and-shared-test-harnesses/SKILL.md` — Navigate when: 新增 unit/integration/Web 测试，调整 Vitest project、mock、临时目录或测试进程清理 - `./real-api-qualification-and-e2e/SKILL.md` — Navigate when: 修改真实 Provider、发布矩阵、跨表面驱动、凭据或资格证据 - `./performance-security-and-snapshot-gates/SKILL.md` — Navigate when: 调整性能预算、安全检查、coverage 或快照更新策略 - `./build-release-and-documentation/SKILL.md` — Navigate when: 修改构建输出、npm 包内容、版本/tag 发布、CI action 或双语文档部署