echovic 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()inpackages/cli/scripts/qualification.ts— 定义本地 14 项和生产 16 项顺序门禁testTypesinpackages/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 或双语文档部署