9. 运行、测试和调试指南
9.1 环境要求
仓库声明需要：
- Node.js
^22.19 || >=24。 - Corepack 启用的
pnpm@11.7.0。 - Git 2.26+。
- 可选
DEEPSEEK_API_KEY。
9.2 命令分类
已执行并验证
2026-09-02 在证据提交 4e84901e 上执行：
sh
pnpm exec vitest run <11 个定向测试文件>
# 11 test files passed; 660 tests passed
pnpm dsh --help
# 成功输出 launcher 选项、web/plugin 子命令与示例
DSH_HOME=<temp> pnpm dsh --profile web --dump-default-config
# 成功输出 base 与 web Bundle 组合树；临时目录随后删除此外执行了 Git 提交、状态、文件和符号的只读检查。上面的通过结果只覆盖指定核心包与 CLI 帮助，不代表真实模型、Web UI、全部 E2E 或发布流程已经通过。
仓库声明但未执行
sh
pnpm run clean
pnpm run test # 全仓测试未执行；只执行了三个核心包
pnpm run test:coverage
pnpm run test:e2e
pnpm run test:snapshot
pnpm run typecheck
pnpm run lint
pnpm run build
pnpm run hygiene
pnpm run doc-sync
pnpm dsh --profile headless "task"
pnpm run demo:cordis
pnpm run demo:acp推荐的最小复验
sh
pnpm exec vitest run packages/core/session/tests/session.spec.ts packages/core/agent-loop/tests/loop.spec.ts packages/core/tools/tests/tools.spec.ts packages/core/tools/tests/ptc.spec.ts学习者仍应先用 rg --files <package> 确认测试范围，避免把路径拼错后“零测试通过”误记为成功。
9.3 安装步骤
建议流程：
sh
pnpm install
pnpm run typecheck如果只是读代码，不安装依赖也可以完成大部分静态分析。真实运行、构建和测试需要依赖。
9.4 最小启动步骤
Web：
sh
pnpm run build
pnpm dsh webHeadless：
sh
pnpm run build
pnpm dsh --profile headless "summarize this workspace"这些启动命令来自根 README.md 和 docs/development.md，【待确认】本次未进行需要真实 Key 的端到端启动。第一次实践优先使用 mock LLM 或只 dump 配置。
9.5 常用开发命令
pnpm run dev:web：重建客户端 bundle，配合 Web HMR。pnpm run mock:llm：启动 mock LLM server。pnpm dsh --profile web --dump-config：查看组合树。
9.6 测试命令
优先从 package 级测试入手，不要一上来跑全量。根 package.json 的 test 是 vitest run。
9.7 如何运行单个测试
Vitest 通常支持：
sh
pnpm run test -- <test-file-pattern>当前仓库 Vitest 已验证可直接接受 package 路径。运行单文件时应检查输出中的 Test Files/Tests 数量，确保过滤条件确实选中了目标。
9.8 如何开启调试
Node/tsx 可配合 IDE 断点。核心断点：
packages/core/agent-loop/src/agent.ts:255的turn()。packages/core/agent-loop/src/agent.ts:341的step()。packages/core/agent-loop/src/agent.ts:453的buildRequest()。packages/core/tools/src/index.ts:1333的execute()。
9.9 日志位置
源码里常见 ctx.logger.warn，不是统一文件日志。Session 持久化默认 root 来自 dshHomePath('sessions')，见 packages/bundle/base/cordis.patch.yml。浏览器和 telemetry 有独立机制。
9.10 环境变量
常用：
text
DEEPSEEK_API_KEY
DEEPSEEK_BASE_URL
DSH_PERMISSION_MODE
DSH_TELEMETRY_MODE
DSH_TELEMETRY_DISABLED
DSH_TELEMETRY_OTLP_URL
DSH_TOOLS_MODE9.11 常见启动失败原因
- 没有安装依赖。
- 没有先 build，导致缺 Typert artifacts 或 client bundle。
- Node/pnpm 版本不匹配。
- bundle/patch 行引用了不存在的插件或 id。
- 缺少
DEEPSEEK_API_KEY时，真实模型调用失败。 - 端口被占用。
- Windows 与 POSIX shell 平台差异导致 bash/pwsh 行选择不同。
9.12 最小故障排查流程
- 看 CLI 第一阶段报错是启动器还是应用参数。
--dump-config看组合树是否正确。- 检查 profile
package.json和cordis.patch.yml。 - 用
--patchoverlay 做最小复现。 - 在
runProfile、boot()、Agent 创建处断点。 - 如果与模型相关，确认 adapter 注册、provider/model、key、base URL。
- 如果与工具相关，确认
ctx.tools注册、schema、权限和 guard。
9.13 一张可复用的故障分层表
| 最后成功点 | 下一检查点 | 不应优先检查 |
|---|---|---|
| CLI help | 参数所有权与 Profile 路径 | 模型输出质量 |
| dump config | Cordis entry 激活与 inject | 浏览器 CSS |
| Agent 创建 | inbox、pre-step 与 Session append | 发布脚本 |
| request/header | Adapter、Key、base URL 与 stream | Tool body |
| tool/call | schema、restriction、guard 与 scheduler | Profile 查找 |
| Session event | persistence/downlink/projection | LLM 路由 |
每次排查保存：复现命令、提交、环境版本、最小输入、最后成功点、首个错误和恢复步骤。只有这些 信息齐全，故障记录才可被另一个开发者重放。