3. 技术栈与工程系统
3.1 技术栈表
| 技术或依赖 | 在项目中的用途 | 核心依赖 | 对应配置或源码位置 | 学习优先级 | 建议掌握程度 |
|---|---|---|---|---|---|
| TypeScript | 全部源码、typed events、declaration merging | 是 | tsconfig.base.json、package.json | 高 | 能读高级泛型和 declaration merging |
| Node.js | Host 运行时、子进程、FS、HTTP、PTY | 是 | package.json.engines | 中 | 理解事件循环、stream、AbortSignal |
| pnpm workspaces | Monorepo 包管理 | 是 | pnpm-workspace.yaml、根 package.json | 高 | 会用 filter/workspace |
| Cordis | 插件运行时、Context、fiber、events、effect | 是 | vendor/、docs/cordis-primer.md | 高 | 理解五思想和四种派发 |
| schemastery | 配置 schema 校验 | 是 | packages/core/agent-loop/src/index.ts:300-311 | 中 | 能读 Config |
| Typert | 类型图、生成 RPC 契约 | 是 | packages/typert/、docs/subsystems/typert.md | 进阶 | 知道它解决什么 |
| tsx | source launch ESM | 是 | 根 package.json 的 dsh script | 中 | 知道 source/build 差异 |
| tsdown / tsc | 构建 Host/Client lib | 是 | package.json build scripts | 中 | 知道 build 阶段 |
| Vite | Web shell / 前端构建 | 是 | apps/web、packages/client/web | 中 | 能调试前端 |
| Vitest | 测试运行器 | 是 | vitest.config.ts、根 scripts | 高 | 会跑单测 |
React + useSyncExternalStore | Web UI 渲染 | 是 | packages/client/ui-renderer、apps/web | 高 | 理解外部 store 订阅 |
| SQLite/JSONL | 会话持久化与检索 | 核心辅助 | packages/session/session-persistence-*、session-query-sqlite | 中 | 理解 append log 与查询 |
| OpenTelemetry | 会话遥测 | 辅助 | packages/session/session-telemetry-otel | 低 | 知道边界 |
3.2 包管理和依赖管理
根 package.json 是 pnpm@11.7.0，workspaces 覆盖 vendor/*、packages/*/*、native/landlock-run、apps/*、website。所有 npm 包使用 @deepseek-ai/dsh-*，vendored 包 rescope。扩展插件依赖 Service Definition，不依赖 concrete provider，见 packages/README.md#dependencies。
3.3 构建流程
根脚本显示：
build
build:lib
build:lib:host
build:lib:client
build:webHost 和 Client 是两个独立 TypeScript aggregate，不能压成一个 program，否则两端对 Context 的 declaration merging 会冲突。typert 只在 Host tsdown 阶段生成类型图。
依据：package.json、docs/development.md#typescript-project-layout。
3.4 开发模式
source launch 使用：
pnpm dsh --profile headless "task"根 script 实际是 node --import tsx/esm apps/cli/src/bin.ts。源码运行必须保持 ESM。Web HMR 由 pnpm run dev:web 重建客户端 bundle，client-hmr 行保持挂载但空闲。
3.5 测试体系
pnpm run test：Vitest 单测。pnpm run test:coverage：CI 覆盖率门禁，packages/*/*/src每文件 100%。pnpm run test:e2e：真实 API e2e，无 key 自动跳过。pnpm run test:snapshot：无 key 的 ACP/headless 回放对比。pnpm run test:web：浏览器快照，需要构建。
这些命令来自根 package.json，本次未执行。
3.6 配置与环境变量
cordis.yml 的 config 支持 !!js 表达式。真实 API 读取 DEEPSEEK_API_KEY，可选 DEEPSEEK_BASE_URL。权限相关可读 DSH_PERMISSION_MODE；遥测可读 DSH_TELEMETRY_MODE、DSH_TELEMETRY_DISABLED。这些在 packages/bundle/base/cordis.patch.yml 有体现。
3.7 发布和部署方式
从仓库声明看，存在 release:dsh、release:pack、release:publish 和 publish:npm-baseline。产品安装后由 apps/cli/lib/bin.js 启动。本教程未执行发布流程。
3.8 开发与生产差异
source launch 依赖 tsx ESM；built launch 依赖 lib/ 产物。测试默认解析 source plane，只有 built artifact smoke 显式运行 lib/。开发模式还有配置 patch 热更新，生产或安装形式仍以配置组合为基础。