base/packages/bundle/base

入口包名：@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 文件即可。

前置依赖与兼容性

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

安装方式

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

配置项

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

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）

English | 中文

DSHCode 是一款面向 macOS 和 Windows 的免费开源桌面 AI Agent 应用。它将 DeepSeek 官方开源项目 DeepSeek Harness 的 Web UI 与插件运行时打包成一个可直接安装的 Electron 应用——无需 Node.js、无需终端、无需命令行。

功能特性

DSHCode 继承了 DeepSeek Harness 的完整能力，并加上了开箱即用的桌面体验。

Agent 核心 — 插件化框架，内置 bash、文件系统、网页搜索/抓取、终端、LSP 与子进程工具；支持沙箱隔离与逐操作审批提示。

交互式 UI — 内联渲染的 GenUI 卡片：图表、表格、测验、3D 场景、示意图、表单与进度视图。

Skills 技能 — 可安装的技能目录，为 Agent 提供专项工作流——研究、文档写作、视觉工具等。

编排能力 — Subagent 并行委派，以及可跨多个 Agent 分阶段并行展开的 Workflow。

长任务 — 执行前先审查再批准的 Plan 模式、跨轮次持续进行的 Goal 目标、可恢复的会话。

模型体验 — 通过官方 API 使用 DeepSeek 模型；会话日志完整记录模型所见内容，任何一次运行都可被重建。

模型控制 — 按供应商调节推理强度（关闭到最高）、最大输出 token 数，以及图像输入、图像生成与图像识别等多模态能力开关。

个性化 — 主题与皮肤合集、选区批注工作流、命令快捷键、中英双语界面。

插件管理 — 从 npm 或 Git 仓库安装插件、检查更新，并可逐个启用或禁用。

故障恢复 — 加载失败的插件会连同诊断信息一起报告：可禁用该插件、以安全模式启动，或让 Agent 携带失败上下文自动修复。

归档管理 — 搜索已归档会话，可恢复或彻底删除。

可扩展 — 安装新能力无需改动应用本体。

桌面集成 — 托盘图标、系统通知、单实例运行、加固的 Electron 窗口。

详见 Web UI 指南 的操作讲解，以及桌面应用指南中的架构、平台目标与当前限制。

下载

每个版本都会随安装包发布 SHA-256 校验和（SHA256SUMS.txt）。

预览版安装包尚未进行代码签名或公证，因此 macOS Gatekeeper 与 Windows SmartScreen 可能在首次启动前发出警告。软件本身是安全的；警告只是因为二进制文件缺少付费签名证书：

• macOS：在访达中右键点击应用并选择打开，然后在弹窗中确认。或者在终端执行一次 xattr -cr /Applications/DSHCode.app。
• Windows：在 SmartScreen 弹窗中点击更多信息，然后选择仍要运行。

快速开始

安装 DSHCode 安装包后，从 macOS“应用程序”文件夹或 Windows“开始”菜单打开 DSHCode。应用会自行启动和停止内置 Web profile；安装版用户无需运行终端命令。

从源码运行

开发者仍可从仓库源码运行上游 Web 入口：

git clone https://github.com/whitelonng/dshcode.git
cd dshcode
pnpm install
pnpm run build
pnpm dsh web

命令会打印本地 Web UI 地址。详见 Web UI 指南。

桌面应用

打开 DSHCode 时，应用会启动内置的 Harness Web profile，并在经过安全加固的 Electron 窗口中显示。桌面外壳刻意保持精简；产品行为和 Web UI 仍由上游包提供，因此后续可以继续集成上游更新，而不必维护第二套界面。

本地服务与端口

应用每次启动时都会在 Electron 主进程内启动一个 HTTP 服务。该服务只绑定 127.0.0.1，并让操作系统分配一个可用的临时端口，因此不会占用固定端口，通常也不会与其他本地服务冲突。DSHCode 只允许一个应用实例，只加载其自身的精确回环地址；进程退出前会先释放 Harness 树，所以关闭应用也会停止服务并释放端口。

构建桌面安装包

git clone https://github.com/whitelonng/dshcode.git
cd dshcode
pnpm install
pnpm run desktop:dist

构建产物写入 .artifacts/desktop/release/。名为 Desktop 的 GitHub Actions 工作流会构建 macOS Apple Silicon、macOS Intel 和 Windows x64 安装包；desktop-v* tag 会把完整构建矩阵及 SHA-256 校验和发布到 GitHub Releases。

常见问题

DSHCode 是什么？

DSHCode 是一款免费、开源的桌面应用，把 DeepSeek 的插件化 AI Agent 框架 DeepSeek Harness 变成可直接安装的 macOS 与 Windows 应用，并提供图形化的对话与工作区界面。

DSHCode 是 DeepSeek 官方软件吗？

不是。DSHCode 是独立的社区项目。它保留上游包名、版权、架构、文档和 upstream Git 远程地址，以便正确归属来源并继续合并上游变更；但除非 DeepSeek 明确授权，它不代表 DeepSeek 官方发行、背书或认证。

需要 Node.js 或终端吗？

不需要。安装版用户得到的是普通应用；Node.js、CLI 与终端只在从源码运行或自行构建安装包时才需要。

为什么 macOS/Windows 会弹出安全警告？

预览版安装包尚未进行代码签名或公证。这是签名证书的成本问题，不是安全问题；一次性打开步骤见下载一节。

需要 API Key 吗？

需要。DSHCode 通过官方 API 运行 DeepSeek 模型；在应用设置中配置一次即可。

DSHCode 可以扩展吗？

可以。内置插件安装器可在不改动应用本体的前提下添加新能力；安全模式可以禁用导致崩溃的插件，保证应用仍能正常启动。

项目定位

DeepSeek Harness（dsh）是由 DeepSeek AI 开发的官方开源插件式 agent harness（智能体框架）。DSHCode 作为桌面端配套发行版参与其插件生态，并使用 dsh-plugin 和 deepseekharness-plugin 仓库标签便于检索。

DSHCode 是独立的社区项目。除非 DeepSeek 明确授权，否则它不代表 DeepSeek 官方发行、背书或认证。

开发

请先阅读开发指南、架构文档和桌面应用指南。面向 agent：请遵循 AGENTS.md。

致谢

• LINUX DO — 本项目也在 LINUX DO 社区持续分享与交流。
• dsh-genui — 为内置生成式 UI 能力提供插件实现。
• dsh-annotation — 为内置文本批注流程提供插件实现。
• dsh-web-ui — 为内置 Web UI 功能与皮肤集合提供插件实现。

许可证与品牌

源码继续使用上游 MIT 许可证。再次分发时必须保留 DeepSeek 的版权与许可声明；内置第三方软件及其许可证见 THIRD_PARTY_NOTICES.md，桌面安装包会同时附带这两个文件。

MIT 软件许可证本身不等于获得 DeepSeek 商标或 Logo 的 DSHCode 品牌使用许可。DeepSeek 的用户协议（中文版）保留了这些品牌标识的相关权利。DSHCode 发行版使用独立应用图标；内嵌 Harness 界面保留的上游身份标识及官方 powered by dsh 署名只用于说明兼容关系，不代表官方背书。