Mind 测试支架边界与启动契约

1. Scope / Trigger

Trigger：修改 apps/mind-test-harness/ 的 Mind 外部依赖模拟、Bright 手工联调页面、启动入口或环境变量。
Scope：仅开发者手工测试。它可模拟外部 Mind 授权，也可操作/展示 Bright 业务响应；不属于 server、Chrome extension 或生产部署。

2. Signatures

pnpm dev:harness
MIND_MOCK_HOST=127.0.0.1
MIND_MOCK_PORT=8787
MIND_TEST_HARNESS_HOST=127.0.0.1
MIND_TEST_HARNESS_PORT=8788
MIND_TEST_HARNESS_BRIGHT_BASE_URL=http://127.0.0.1:7878

src/entry.ts 必须启动 Mind 授权模拟监听器和 Bright 联调页监听器。
pnpm dev 不得启动、等待或依赖该包；只有显式 pnpm dev:harness 才运行它。
联调页使用 MIND_TEST_HARNESS_BRIGHT_BASE_URL 请求 Bright HTTP 和 WS；不能再由 apps/server 的 /harness 路由提供。

3. Contracts

包可消费 @trade-message-center/onetalk-contract，但不提供给其它 workspace 包消费。任何 apps/*/package.json 都不得声明 @trade-message-center/mind-test-harness 为任一 dependency 类字段。
包内不得有 test/ 目录、*.test.* 文件、test 脚本、build 脚本、TypeScript outDir 或提交的 dist/。根 pnpm build 和生产 Dockerfile 均不得 filter/copy 该包。
该包是顺道编写的低优先级工具，不得被根 dev、typecheck、test 或 build 调度；实现完成不要求测试。其启动或运行失败只在独立命令中报告，不能停止、等待或改变 server/extension 主流程。
浏览器的 Origin 必须与 server 的 MIND_PAGE_ORIGIN 精确相等；默认页面地址为 http://127.0.0.1:8788。Cookie 快捷入口只写页面所在 loopback host 的开发 Cookie，生产 Cookie 仍由 Mind 登录设置。
该包的启动失败、上游 Bright 拒绝、CORS 拒绝和 WS Origin 拒绝必须原样可见，不得加跨域代理、默认成功或静默 fallback。

4. Validation & Error Matrix

条件	结果
`MIND_TEST_HARNESS_PORT` 或 `MIND_MOCK_PORT` 非 0–65535 整数	启动前抛出对应环境变量错误
Bright base URL 不是精确 HTTP/HTTPS origin	启动前抛出 `Invalid MIND_TEST_HARNESS_BRIGHT_BASE_URL`
监听端口已被占用	启动失败并关闭已打开的另一监听器
非 `GET /` 请求联调页监听器	返回 404
`MIND_PAGE_ORIGIN` 与页面 Origin 不相等	Bright 的 CORS/WS 显式拒绝；不得绕过
支架启动或运行失败	仅向 `pnpm dev:harness` 报告；根主流程继续运行

5. Good / Base / Bad Cases

Good：向支架加入可重复的外部依赖 fixture 或 Bright 页面操作，同时保持它只从共享 contract 读取协议版本和 HTTP route 模板。
Base：需要时运行 pnpm dev:harness 进行手工 HTTP/页面 smoke；这不是完成条件，也不是生产发布验证。
Bad：server import 支架以重新开放 /harness；其它包声明它为依赖；把支架加入根 dev/质量门禁；为“覆盖率”在包内加入测试文件；或增加 build/dist 来发布它。

6. Tests Required

mind-test-harness 本身不创建或保留测试文件，也不声明 test 命令。
完成支架改动无需新增或执行测试，也不得把它接入根质量门禁。若做了手工启动，结果仅作为诊断报告，不构成主流程阻塞条件。
错误必须保留可见的日志/退出信息；不要为了保持支架可用而制造成功 fallback。

7. Wrong vs Correct

// Wrong: 将手工页面重新挂回 server，使 server 依赖测试支架。
installOneTalkHarnessRoute(app);

// Correct: 支架自己监听页面端口，server 只保留业务 HTTP/WS 路由。
const harnessServer = createOneTalkHarnessServer(config);

3.8 KiB Raw Blame History Unescape Escape

Mind 测试支架边界与启动契约

1. Scope / Trigger

2. Signatures

3. Contracts

4. Validation & Error Matrix

5. Good / Base / Bad Cases

6. Tests Required

7. Wrong vs Correct

3.8 KiB

Raw Blame History