deepseek-harness-studio/packages/bundle/base

一句话定位

dsh 的「共享核心」组合包。它自己不提供运行时 API，作用是把每个 dsh profile 都需要的基础能力一次性挂到 profile 根上——默认的 DeepSeek 适配器、bash / pwsh 工具、文件系统、subagent、权限预设、Settings / Credentials、Telemetry 都在这一层；后续的 web / headless 等表层 bundle 都建立在这一层之上。

核心能力

以一份 cordis.patch.yml 一次性插入约 78 行插件，构成所有 dsh profile 的共享基底（cordis.patch.yml:15-451 / tests/base.spec.ts:30-42）
引入默认模型适配器：在没有用户 settings 覆盖时，给所有 Agent 装配 deepseek-official provider 的 deepseek-v4-flash 模型（cordis.patch.yml:62-68）
提供 bash / pwsh 两套互补的 shell 栈，并在加载时按平台自动只保留其中一套：bash 在 POSIX 启用、PowerShell 在 Windows 启用（cordis.patch.yml:178-217 / README.md:7）
给出三层权限预设（read-only / workspace-write / danger-full-access），并把审批服务与权限预设挂钩，全局权限模式可通过 DSH_PERMISSION_MODE 切换（cordis.patch.yml:170-217）
提供基础工具集：bash（pwsh）、文件系统读 / 写 / 搜索、jobs、web_search（DeepSeek 搜索源）、todo、goal、subagent（spawn / fork）、str-replace-editor、ralph、skill、workflow（cordis.patch.yml:210-419）
持久化与可观测：session 落 JSONL、附件图片走内容寻址本地存储、SQLite 索引默认走内存模式、Telemetry 通过 DSH_TELEMETRY_MODE 环境变量开关（cordis.patch.yml:98-161）

技术实现

语言: TypeScript (ESM)，"type": "module"，package.json lib/index.js 入口只导出 export {}
关键依赖: @deepseek-ai/cordis（Cordis 插件宿主，对等依赖）、@deepseek-ai/cordis-plugin-loader（patch 加载器）、@deepseek-ai/dsh-invariants（对等依赖 + invariant companion）、约 70 个 dsh-* 工作区包（构成 patch 中插入的 78 个插件行）
架构模式: 该包「自己」不是插件——它的 package.json 在 dsh.bundle.patch 字段下挂一份 cordis.patch.yml，由 profile composer 在加载时把它当作「第一个 patch 层」插入空 profile 根；按 id 寻址，后续 bundle / 用户 profile 的 patch 可以覆盖这些行；src/invariant.ts 是只挂占位的 invariant companion（每个被插入的 row 各自的包自带 invariants）
入口文件: src/index.ts（空导出，仅含模块注释）+ src/invariant.ts（base-bundle-invariant companion）+ cordis.patch.yml（包的实际内容）

适用场景

任何想自己「从零搭一套 dsh profile」、或要给 profile 加一个共享基底的开发者：装上 dsh-base，等于一次性把 DeepSeek 适配器、bash / pwsh 工具、文件系统、subagent、持久化、telemetry、权限预设这些共用行为默认打开——之后 web / headless / 桌面表层只需在它之上再叠加自己关心的层。普通用户一般不会直接安装这一层，而是通过 dsh-cli 内置或 dsh plugin --profile 安装 web-app、headless 这些表层 bundle 间接使用它。

前置依赖与兼容性

依赖	最低版本	说明
DSH	0.1.0-rc.8	作为「第一层 patch」叠加在 dsh-base 之上，需使用同主版本的 dsh CLI
Node	^22.19.0 \|\| >=24.0.0	仓库根 `engines` 字段声明；当前 patch 不直接使用任何 Node 22+ API，但所插入的 row 包以这条线为准
平台	macOS / Linux / Windows	bundle 在自身 patch 中按平台门控 bash / pwsh，因此同一份 patch 在三种系统上都能加载，但只挂一个 shell 栈
原生模块	node:sqlite（`@deepseek-ai/dsh-session-query-sqlite`）	默认 `:memory:`，需重启进程重开索引；不持久化到磁盘
Cordis	peerDependency	`@deepseek-ai/cordis`，由宿主提供

安装方式

dsh plugin --profile web add github:fufankeji/deepseek-harness-studio/packages/bundle/base

配置项

本 bundle 自身不直接暴露用户配置——它通过 cordis.patch.yml 给每个被挂载的 row 注入一份配置。下面列出值得记的几条全局 / 行为级默认：

名称	类型	说明	默认值
`sandbox.mode`	字符串	文件效果边界，取自 `DSH_PERMISSION_MODE` 环境变量	`workspace-write`
`sandbox.workspaceRoot`	路径	受限子进程允许写入的工作区根	`process.cwd()`
`user-approval.policy`	字符串	危险操作前是否询问	`DSH_PERMISSION_MODE === 'danger-full-access'` 时 `never`，否则 `ask`
`bash-sandbox.timeoutMs`	毫秒	单条 bash 命令最长等待时间	`60000`
`web-search-deepseek.apiKeyEnv`	环境变量名	DeepSeek 搜索用的 key 环境变量名	`DEEPSEEK_API_KEY`
`tool-web.searchTimeoutMs`	毫秒	web_search 单次超时	`60000`（DeepSeek 路由），其它 `30000`
`tool-str-replace-editor.maxOutputChars`	数字	str_replace_editor 单次最多输出多少字符	`16000`
`tool-result-pruner` 阈值	字符	超长工具结果被自动裁剪的字符阈值 / 保留头 / 保留尾	`8192 / 4096 / 1024`
`repeat-tool-reminder.thresholds`	数字数组	连续重复同一工具调用时提示的回合数	`[3, 5, 8]`
`session-telemetry.mode`	字符串	OTLP / HTTP 上报模式，取自 `DSH_TELEMETRY_MODE`；空值 = 不上报	`DISABLED`
`session-telemetry.exporter.url`	URL	OTLP logs 上报端点，可被 `DSH_TELEMETRY_OTLP_URL` 覆盖	`https://harness-telemetry.deepseeksvc.com/v1/logs`
`session-query-sqlite.openAt`	字符串	SQLite 索引何时打开；默认值禁止内容搜索	`never`
`session-query-sqlite.path`	字符串	索引存储位置；`:memory:` 是默认	`:memory:`
`session-persistence-jsonl.root`	路径	session log 文件根	`$DSH_HOME/sessions`
`spill-policy.maxInlineBytes`	字节	工具结果以 inline 形式携带的最大尺寸，超过则 spill 到本地	`50000`
`tool-todo.allowParallelInProgress`	布尔	todo_write 是否允许同时存在多个 `in_progress` 项	`true`
`tool-ralph.maxRounds`	数字	Ralph 工具的最大迭代回合	`64`
`tool-fs-search.sampleOverCapGlobResults`	布尔	通配超过上限时是否降采样返回	`false`
`session-title-llm.targetWords` / `targetCjkCharacters`	数字	默认标题长度（西文 / 中文）	`5` / `10`

用户也可在 home 的 settings.yaml 中加 llm-deepseek: / llm-pi-ai: 段覆盖默认的 DeepSeek adapter 与激活 pi-ai 多 provider；不在 patch 内的「配置项」不展开。

常见问题

Q: 这个 bundle 是什么？为什么要先装它？

A: dsh 的「共享核心」组合包。它的 cordis.patch.yml 把所有 profile 都需要的基础插件一次性挂到 profile 根上——LLM 适配器、bash / pwsh 工具、文件系统、subagent、持久化、telemetry、权限预设都来自这一层。任何 dsh profile（web / headless / 桌面等）都默认以这一层为底，不装它就只剩空 profile。

Q: 安装 dsh-base 之后，还需要装官方 dsh-cli 吗？

A: 不重复。dsh-base 是 dsh 安装内部的 in-box bundle，普通用户通过 dsh plugin --profile <name> add 安装的通常是 web-app、headless 这类表层 bundle，dsh-base 已经默认存在于 @deepseek-ai/dsh 生产闭包里。

Q: 安装 dsh-base 会同时启用 Codex / Claude Code 子代理吗？

A: 不会。本包显式不带 @deepseek-ai/dsh-subagent-codex 和 @deepseek-ai/dsh-subagent-claude-code，这两类是可选的「产品 provider」，需要单独安装 profile bundle 才会被激活。

Q: 装上后看到 telemetry 行为，是开了吗？

A: 默认没开。session-telemetry-otel 行虽然被 patch 进来，但 mode 默认从环境变量 DSH_TELEMETRY_MODE 取值；该变量为空时落到 'DISABLED'。要上报就把环境变量显式设成 FULL 或 FEEDBACK_ONLY（其它值仍走禁用分支）。

Q: 我用的是 Windows，跑起来为什么 bash / pwsh 工具表现不一样？

A: bundle 在自身 patch 里按平台门控：bash 在 win32 上被 disabled: !!js process.platform === 'win32' 关掉，pwsh 在非 win32 上被关掉——同一份 patch，每台机器恰好挂一个 shell 栈。要在 Windows 上强行使用 bash 需要在 profile 或 home cordis.patch.yml 同时禁 pwsh-sh / tool-pwsh 并重新启用 bash-sh / tool-bash，缺一项会因重复注册同一个 bash 服务而加载失败。

Q: 偏好不联网的本地模型（或 Anthropic / OpenAI / 其它 provider），需要加 provider bundle 吗？

A: 需要。dsh-base 已经把 @deepseek-ai/dsh-llm-pi-ai 作为「零路由」provider 挂上，但没注入任何 provider profile；要让 pi-ai 跑起来要在 home settings.yaml 的 llm-pi-ai: 段填 provider profiles（Web 表层 Models 页面是入口）。不填的话 picker 里只有默认的 DeepSeek adapter。

Q: dsh-base 有自己的运行时 API 吗？我能 import 它的 apply() / 主入口吗？

A: 没有。src/index.ts 是空导出并写明「package's substance is cordis.patch.yml」，profile composer 通过 manifest 的 dsh.bundle.patch 字段解析 patch，不会经过 import。src/invariant.ts 提供一个 no-op companion，理由是本包不挂服务、不发事件、不持可变状态，每条 row 各自的包自带 invariants。

Q: 升级 dsh-base 会修改用户的 home settings.yaml / sessions 目录吗？

A: 不会。settings、sessions、.anonymous-user-id、.credentials.yaml 都由相应的服务独立管理在 $DSH_HOME 下，升级 dsh-base 不动这些位置；session-query-sqlite 默认走 :memory:，重启进程后只把内存中的搜索索引清空，不动磁盘。

上手难度

入门 — 只要会用 dsh plugin --profile 加 bundle、按 home settings.yaml 配 key 和 provider profile 就能让它工作；不需要写 Cordis 插件、不需要跑 loader；要深入则要理解 patch layer 的覆盖语义和键约束。

已知问题与限制

patch 替换整行 config：profile 覆盖必须重述该行需要保留的每个字段，不存在深度合并层（README.md:19-22 / README.zh.md:19-22）
Windows 临时目录授权是按会话的私有子目录——workspace-write 把写入限制在工作区与会话自己的 temp 子目录（<temp>\dsh-<hash>，受限子进程的 TMP/TEMP 被改写）；read-only 不授予任何临时目录写入权限（README.md:19-22）
session 内容搜索默认关闭——session-query-sqlite.openAt: never 让精确读、标题、lineage 仍可用，但搜索调用会以 SESSION_QUERY_SEARCH_DISABLED 失败；想启用需要在更上层 patch 中把 openAt 改为 first-search 或 startup，通常配合一个稳定的 path（cordis.patch.yml:111-122 / 注释在 109-117）
DSH 基线采用整行替换、不做合并：见 cordis.patch.yml 文件头与 README ## Known Limitations and Deferred Work 节
telemetry 默认禁用但 OTLP 上报端点仍写死一个官方域名——session-telemetry-otel.exporter.url 默认指向 https://harness-telemetry.deepseeksvc.com/v1/logs，可通过 DSH_TELEMETRY_OTLP_URL 改写但默认就是该域（cordis.patch.yml:148-161）

Install