# dshcode

> 把 dsh 全套基础能力打包成 profile 组合包，作为每个 profile 的第一层 patch，承载模型、工具、沙箱、权限、会话持久化等 60+ 基础行。

## Metadata

- Author: [@whitelonng](https://github.com/whitelonng)
- Repo: <https://github.com/whitelonng/dshcode.git>
- GitHub: [whitelonng/dshcode](https://github.com/whitelonng/dshcode)
- Stars: 90
- Language: TypeScript
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Topics: `agent`, `deepseek`, `deepseekharness-plugin`, `dsh-plugin`, `harness`
- Forks: 8
- Open Issues: 0
- Last push: 2026-08-20T20:02:51.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:whitelonng/dshcode/packages/bundle/base
```

## Wiki

> 入口包名：`@deepseek-ai/dsh-base`，落地页 ID：`whitelonng/dshcode/packages/bundle/base`。下文统称"基础组合包"。

## 一句话定位
它是 dsh 出厂 profile 的"第一层 patch"——把模型、Agent、工具、沙箱、权限、会话持久化、遥测、subagent 等 60 多个基础插件一并注入到空 profile 的根上，相当于浏览器的出厂默认扩展集合；其他模式组合包和用户配置都在它之上叠加或按行覆盖。

## 核心能力
- 引入 LLM 适配器（DeepSeek 原生 + pi-ai 多 provider 桥）和默认模型选择（agent-default-model 默认 deepseek-official / deepseek-v4-flash）
- 挂载 Agent 主循环（agent / agent-loop / agent-default-model / agent-instructions / system-prompt），奠定任务派发骨架
- 暴露基础工具：bash/pwsh（按平台二选一）、fs、fs-search、str-replace-editor、web_search、todo、subagent、subagent-fork、subagent-control、subagent-report、workflow、goal、skill、ralph、jobs 等
- 装配持久化与会话管理：JSONL 会话日志（写到 `$DSH_HOME/sessions`）、SQLite 会话索引（默认内存模式、关闭内容搜索）、内存型 attachment 字节仓库、checkpoint 策略与 projection
- 启用文件沙箱、权限策略与审批开关，默认 workspace-write + ask，提供 read-only / workspace-write / danger-full-access 三档预设
- 提供本地凭据与设置（`$DSH_HOME/.credentials.yaml` + `$DSH_HOME/settings.yaml`，hot-reload）以及 OTLP 遥测挂载（默认关闭）

## 技术实现
- **语言**: TypeScript，但运行时是配置型——本包 `src/index.ts` 仅导出 `{}`，没有运行时 API，所有行为由 `cordis.patch.yml` 描述
- **关键依赖**: `@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-tools`、`@deepseek-ai/dsh-session-persistence-jsonl`（任列 4 即可，详见 `package.json:41-119`）
- **架构模式**: 通过 `package.json#dsh.bundle.patch` manifest 字段声明 patch 路径，profile 组合器解析加载，没有任何 Cordis 钩子或事件注册
- **入口文件**: `src/index.ts`（仅声明 @module）、`cordis.patch.yml`（实质内容）、`src/invariant.ts`（一条空 invariant companion）

## 适用场景
每个出厂的 dsh profile（包括 headless、ACP、CLI、Web）都需要这一层作为开箱可用的能力底座；它不是给普通用户"按需启用"的扩展，而是所有上层 profile 拼装的前置条件。当用户想了解自己 profile 里那些默认能用、不能关的工具和默认值由谁决定时，看这一层的 patch 文件即可。

## 前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未单独声明（仓库未发布 `< dsh-base` 的下限） | 作为 dsh 同源 profile 组合包安装使用 |
| Node | `^22.19.0 \|\| >=24.0.0` | 源自仓库根 `package.json:8-10` 的 engines 字段 |
| 平台 | macOS / Linux / Windows | 同一份 patch，bash 与 pwsh 工具栈按平台互斥挂载 |
| 原生模块 | 无 | 本包自身不引入原生模块，依赖闭包内某些 row 可能依赖 |

> 安装此包会自动引入 70+ 个 workspace 依赖（详见 `package.json:41-119`），包括 LLM、agent、工具、持久化、subagent、shell 等多个核心包。

## 安装方式
```bash
dsh plugin --profile web add github:whitelonng/dshcode/packages/bundle/base
```

## 配置项
本包没有"用户态"配置项；它定义的 50+ 行 row config 是给后续 profile 覆盖使用的默认值。常见的可被外部环境变量覆盖的行：

| 行 / 环境变量 | 默认值 | 说明 |
|---|---|---|
| `sandbox-policy.mode`（环境变量 `DSH_PERMISSION_MODE`） | `workspace-write` | 三档：`read-only` / `workspace-write` / `danger-full-access` |
| `approval.policy`（环境变量同上） | `ask`（在 `danger-full-access` 下为 `never`） | 受 sandbox-policy 行同源取值驱动 |
| `session-telemetry-otel.mode`（环境变量 `DSH_TELEMETRY_MODE`） | `DISABLED` | 设为 `FULL` / `FEEDBACK_ONLY` 开启 OTLP 上报 |
| `session-telemetry-otel.exporter.url`（环境变量 `DSH_TELEMETRY_OTLP_URL`） | `https://harness-telemetry.deepseeksvc.com/v1/logs` | OTLP/HTTP 上报端点，可指向自建收集器 |
| `agent-default-model.provider` / `.model` | `deepseek-official` / `deepseek-v4-flash` | 默认模型选择，可被 user profile 覆盖 |
| `session-query-sqlite.openAt` | `never` | 全文搜索默认关闭，开启需覆盖为 `first-search` 或 `startup`，通常附带 `path` |

> `DSH_TELEMETRY_DISABLED` 只要非空（含 `'0'`/`'false'`）就完全关闭遥测；launcher 在启动时直接 disable 该 row。

## 常见问题

**Q: 这个组合包包含哪些能力？**

A: 它汇集了 dsh 的全部"出厂自带"能力——LLM 适配器、Agent 主循环、bash 与 pwsh 工具、文件系统工具、subagent 派发与 fork、会话 JSONL 持久化、SQLite 会话索引、权限与沙箱策略、本地设置/凭据、OTLP 遥测、token 用量、压缩、计划模式、目标（goal）循环、Web 搜索等。

**Q: 我可以编辑这个组合包吗？**

A: 不需要也不建议。它的"配置"集中在同一份 `cordis.patch.yml`，由 profile 组合器在加载时挂入；你的覆盖应该写在自己 profile 的 `cordis.patch.yml` 里，按 row 的 id 整行覆盖即可。patch 的语义是"替换整行 config"，没有深度合并。

**Q: macOS / Linux 和 Windows 下行为有什么不同？**

A: bash 与 pwsh 两套 shell 栈在同一份 patch 文件里互斥挂载。POSIX 上启用 bash-sandbox 与 tool-bash、禁用 pwsh 系列；Windows 上启用 pwsh 系列、禁用 bash 系列。沙箱、权限和 fs-sandbox 两边都生效，Windows 走 ACL 受限令牌 runner。

**Q: 怎么开启遥测？**

A: 出厂默认关闭。要开启需要把环境变量 `DSH_TELEMETRY_MODE` 设为 `FULL` 或 `FEEDBACK_ONLY`，并把 `DSH_TELEMETRY_OTLP_URL` 指向你的 OTLP/HTTP 收集器；导出记录会带上 `$DSH_HOME/.anonymous-user-id` 里的 UUID 作为 `user.id`。

**Q: 默认是哪种权限模型？**

A: 沙箱默认 `workspace-write`（写入限于工作区与本会话临时子目录），审批默认 `ask`。将环境变量 `DSH_PERMISSION_MODE` 设为 `danger-full-access` 可切到全权访问与免审批；设为 `read-only` 则只读。

**Q: 默认能全文搜索会话历史吗？**

A: 不能。`session-query-sqlite` 行默认 `path: ':memory:'` 且 `openAt: 'never'`，全文搜索调用会返回 `SESSION_QUERY_SEARCH_DISABLED`；精确读取、标题与 lineage 仍可用。要启用需在 profile 覆盖里改成 `first-search` 或 `startup` 并提供持久化 `path`。

**Q: 卸载它会发生什么？**

A: 它是所有出厂 profile 的第一层 patch——把它从 `dsh.profile.bundles` 列表移除，整个 profile 会回到"仅剩用户自定义 row"的空状态，常用工具、模型、持久化都会消失。它不是面向普通用户的可选扩展，建议保留。

**Q: 会话里的图片存在哪里？**

A: 字节放在 `attachment-local` 行配置的本地目录（与 JSONL 会话日志分离）。会话日志里只保留内容寻址引用，由该 row 在每次请求时即时解析。

## 上手难度
入门 — 因为它没有暴露给用户的可写配置面，普通用户不需要懂它；想自定义的话只需要往自己的 `cordis.patch.yml` 里追加整行覆盖即可。

## 已知问题与限制
- **Patch 整行替换语义**：profile 覆盖必须把目标行要保留的每个字段都重写一遍，没有深度合并层；README 显式列出此限制（`README.md:21`）
- **Windows 临时目录是会话私有子目录**：`workspace-write` 把写入限制在工作区与本会话自己的 temp 子目录（`<temp>\dsh-<hash>`，受限子进程的 `TMP`/`TEMP` 被改写），`read-only` 不授予任何临时目录写入（`README.md:22`）
- **bash 与 pwsh 恢复配方必须配对**：在 Windows 上想换回 bash 需要同时禁用 `pwsh-sandbox`/`tool-pwsh` 并重新启用 `bash-sandbox`/`tool-bash`，两边都注册同一个 `bash` 服务，单独开一边会让加载失败
- **全文会话搜索默认关闭**：`session-query-sqlite` 行 `openAt: never`，未在 profile 覆盖中开启前 SQL 不会打开（`cordis.patch.yml:117-122`）
- **遥测默认关闭**：`session-telemetry-otel.mode` 默认 `DISABLED`，未设 `DSH_TELEMETRY_MODE` 不会上报（`cordis.patch.yml:148-161`）

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [dshcode](https://deepseek-plugin.org/plugins/whitelonng/dshcode/packages/bundle/base)
Wiki generated by AI (model: `MiniMax-M3`)