• 人工智能
• AI Agent
• 代码智能体
• AI 应用
• dsh-plugin
• 后端
• 前端
• Agent 工作流

dsh-superagent 是一个为单个 GitHub 仓库服务的主动式编码智能体（proactive coding agent），它的 tests/ 目录用59 个测试文件、约 1.4 万行测试代码，基于 vitest 把核心调度引擎、GitHub/飞书集成、Web 面板 UI 乃至文档本身全部纳入了自动化验证。这篇文章带你快速看懂这套开源项目测试体系是如何组织、又如何跑起来的。

一条命令跑完：pnpm check 是什么

想跑测试不用记复杂命令，package.json 里只定义了两个关键脚本：

全局配置只有三行，位于 vitest.config.ts：

include: ['tests/**/*.spec.{ts,tsx}']

它做了一件不起眼但重要的事：dedupe: ['react', 'react-dom']，让整个 DSH 客户端插件包和测试共享同一个 React 实例，避免"两个 React"导致的渲染崩溃。

💡 新手建议：本地开发时把pnpm check作为提交前的门禁，它会把类型错误、测试失败、构建问题一网打尽。

测试地图：59 个文件按职责分为 6 组

打开 tests/ 目录，文件名本身就是最好的文档。按职责分组后，覆盖结构一目了然：

1️⃣ 核心引擎：智能体"大脑"的状态机验证

智能体从"收到消息"到"交付结果"的完整生命周期，全部在内存中重放：

• tests/core-engine.spec.ts —— 全仓库最核心的测试（1600+ 行）。它用一个harness()函数组装MemoryRepositories（内存版存储）+ 假的Policy/Assessor/Executor，再靠一个pump()函数手动推进时钟，精确断言"谁被准入、工单何时生成、何时需要人工介入"。
• tests/stage.spec.ts —— 工单阶段（stage）流转与失败重试判定。
• tests/policy.spec.ts —— 授权策略：谁被允许、哪些规则生效。
• tests/queue.spec.ts、tests/effects.spec.ts、tests/outbox.spec.ts —— 持久化效果队列的合并、退避重试、暂停期间出站消息的送达。

2️⃣ 来源集成：GitHub 与飞书两大入口

• tests/sources.spec.ts —— 1400 行的"集成大户"，覆盖轮询游标、重试、来源注册、健康上报。
• tests/github-read.spec.ts / tests/feishu-read.spec.ts —— 用假的Commands拦截 git 等外部命令，验证仓库读取逻辑。
• tests/admission-context.spec.ts —— 准入上下文窗口：智能体"看到"哪些历史消息。
• tests/followups.spec.ts —— 续聊路由：订阅线程里的人类消息直接进工单 worker，不再发起评估。

3️⃣ 运行时：并发与健康

• tests/runtime.spec.ts —— 真实Runtime+ 内存 SQLite 的端到端行为。
• tests/runtime-concurrency.spec.ts —— 触发、投递、worker 启动交错时的并发正确性，这是智能体系统最容易出 bug 的地方。
• tests/health.spec.ts、tests/retry-health.spec.ts —— 组件级错误状态与恢复。
• tests/fixtures/host.ts —— 共享的"内存版 DSH 宿主"fixture，一个配置好的ou_alice成员 + 团队聊天频道，让上面这些测试无需真实网络。

4️⃣ Web 面板：React 组件的 UI 级测试

面板（panel）有9 个panel-*.spec.tsx文件，每个对应一个页面标签：tests/panel-overview.spec.tsx、tests/panel-execution.spec.tsx、tests/panel-settings.spec.tsx 等。

它们的秘密在 tests/fixtures/panel.tsx：用 jsdom 挂载真实的<App />组件，点击真实的按钮、读真实的 DOM 文案（如aria-selected、工单阶段标签），而不是 mock 一切。

5️⃣ 契约与"元测试"：测试你的测试，测试你的文档

这是这套体系最精彩的部分——连文档和代码风格本身都有测试：

• tests/docs.spec.ts —— 扫描docs/下所有 Markdown，断言内部链接不失效、docs/007-architecture.md 架构表格中列出的每个源码路径都真实存在。文档写错了路径，CI 会红。
• tests/class-docs.spec.ts —— 正则遍历src/，要求每个class声明前必须紧跟 JSDoc 块，一个都不能少。
• tests/model-surface.spec.ts —— "模型表面"契约测试：orchestrator 和 worker 两个角色的系统提示词 + 工具定义总字符数不得超过预算（59,000 / 40,500），防止提示词悄悄膨胀。
• tests/bundle-patch.spec.ts —— 用 DSH 同款方言解析 cordis.patch.yml，保证 bundle 补丁与 agent 预设始终一致。
• tests/locales.spec.ts / tests/styles.spec.ts —— 中英文字典占位符对齐、CSS 类名与组件引用一致。

6️⃣ 部署与脚本

tests/deployment.spec.ts、tests/environment.spec.ts 在临时目录里构造带空格的路径、软链接、假二进制来验证配置与安装逻辑；tests/service-script.spec.ts 则直接跑 scripts/dsh-superagent 服务脚本，stub 掉ps、tmux和dsh命令。

三个值得抄进你项目的设计

🧪 ① 内存仓储 + 假依赖的 harness 模式

Engine的所有外部依赖（存储、策略、评估器、执行器、时钟）都是接口，tests/core-engine.spec.ts 一次性注入假实现，1600 行测试零 IO、零网络、毫秒级跑完。这是智能体/状态机类代码最可靠的测试姿势。

🎭 ② 一个"挑刺型"假服务器

tests/fixtures/panel-server.ts 完整实现了src/app/api.ts的每一条路由，并且会把任何"未声明的查询参数或 body 不匹配"记进server.misuse，每个测试结束后断言它必须为空——前端偷偷调了一个后端不存在的参数，测试立刻失败。

⚖️ ③ 给提示词设"字数预算"

智能体项目最常见的腐化是 prompt 越写越长。tests/model-surface.spec.ts 把预算写成常量，注释里明确写着"调高必须解释原因"，用测试把约束变成纪律。

如何本地运行这套测试

git clone https://gitcode.com/gh_mirrors/ds/dsh-superagent-prototype cd dsh-superagent-prototype pnpm install pnpm test # 或 pnpm check（类型 + 测试 + 构建）

测试只依赖 Node 的内置node:sqlite与内存 fixture，不需要任何外部服务、token 或真实仓库。

总结：这份测试清单给了你什么

对新手来说，这套体系最大的启示是：测试的边界不止于"功能对不对"，还可以覆盖并发、契约、预算，甚至文档与代码风格。59 个文件、约 1.4 万行代码，就是 dsh-superagent 敢自称"覆盖每一个角落"的底气。

• 人工智能
• AI Agent
• 代码智能体
• AI 应用
• dsh-plugin
• 后端
• 前端
• Agent 工作流