• 三个直觉：dsh = Agent 的乐高底座；harness = 套在模型外的工程层；2026 = Agent 可编程时代
• 核心事实：MIT 开源 · TypeScript · "一切皆插件" · 2026-08-13 发布
• dsh vs 5 个主流 Agent 能力矩阵（Claude Code / Codex / OpenCode / Gemini / Kimi）：开源✅、模型无关✅、官方级插件体系（独有）、自定义界面✅、headless CI✅
• 选型决策：深度定制+生态 → dsh；开箱即用 → Claude Code

• 一条命令启动：npx -y @deepseek-ai/dsh web → http://127.0.0.1:3080

• 双模式：web（对话 UI）/ headless（dsh --profile headless "任务"，CI 友好）

• 推理档位三档：low（最快/简单任务）· high（默认）· max（最强/复杂推理）——性能关键：思考占工具链 90% 时间。>注：low 为本白皮书实测网关（pi-ai/opencode-go）档位；DeepSeek 官方适配器为 off（关闭思考/最快）/ high / max（见 02-quickstart 2.3 注）

• 第一个插件：Git 面板 4 步挂载

• profile = bundle 栈 + 你的 patch 层（package.json + cordis.patch.yml）
• 挂载插件只需 2 处改动（加依赖 + 加 insert 行）
• host/client 双半：一个 npm 包 = Node 侧工具/服务 + 浏览器侧 UI
• 5 大扩展点：agent/request waterfall、conversationEvents、ctx.slots、settings、ctx.provide
• 6 个真实踩坑：rc.1 依赖断裂、插件缺 main、next() 忘 await、类型不识别、ModuleLoader、端口占用

• 从零写提速插件（完整拆解）：纯函数决策 + agent/request waterfall 注入
• 核心技巧：决策逻辑抽纯函数（单测毫秒级）→ 实机只验证"注入是否发生"
• 3 条开发纪律：先找扩展点 / 逻辑抽纯函数 / 实机验证不能省
• 实机日志证据：calls=[{name:"write"}] => reasoningEffort=low

• Git 面板 push/pull/fetch（PR #10）：--force-with-lease 安全红线 + 本地 bare-repo 集成测试 + Playwright 实机验证
• HTML 草稿预览（PR #11）：沙箱安全约束下的 srcdoc 决策纯函数
• 提速插件示例：长工具链每步思考降档

• 性能模型：工具链任务 90% 时间在模型思考（每次工具调用前）
• 档位策略：简单轮次 low / 日常 high / 复杂 max——降档是最高杠杆提速
• 7 个真实坑：含"简单任务突然变快 = 缓存命中"的评测陷阱
• 看成绩单三问：谁测的 / 什么 harness / 验证器多严

• 官方入口：仓库 / API 文档 / Discord / Discussions
• 当前状态：官方暂不收外部 PR → 做 dsh-plugin 生态项目是官方点名的贡献方式
• 新手路径：用起来 → 小 PR → 发插件 → 写内容

• 60+ 官方能力包地图：工具/上下文/会话/子代理/MCP/工作流/安全
• 内置工具（实测）：read/write/grep/glob/edit/bash/todo/skill
• 产物追踪：工具返回 locations → 对话末尾可打开产物
• 上下文注入：系统提示分层 + 技能目录
• 长对话自动压缩（compaction）+ 沙箱/权限/审批安全层

• MCP：接入外部工具服务器（社区已有 token 追踪插件）
• 子代理：并行委派任务（大仓库调研/长任务分解）
• 工作流：确定性多步编排（拉取→清洗→报表→校验）
• 四阶段新手路径：单 Agent → +MCP → +子代理 → +工作流

• 案例 A：数据质量分析→清洗→可视化（186s，52→35 行归零，chart.png，含权衡说明）
• 案例 B：5-bug 修复 + 49 测试（94s，pytest 49 passed，覆盖除零/负数/精度边界）
• 画像：多步工具链自动编排 + 有判断力 + 产物可追踪
• 隐私声明：全部合成数据/自造代码

• 30+ 术语：harness/profile/bundle/cordis/扩展点/waterfall/compaction…
• 命令速查：dsh 核心 / 环境 / 排障 / 插件开发
• Benchmark：同模型 3 Agent 实测（3 轮中位数）

• 技术/生态/竞争/机会/风险 五维度预测 + 时间线
• 机会点：官方生态早期，做 dsh-plugin 项目是入场红利

• 不稳定性：rc 迭代快、破坏性变更频繁
• 生态早期：官方包 60+ 但插件生态刚起步
• 跨平台短板：Windows 家族踩坑记录（含 Node 版本红线）

• 沙箱机制：进程隔离（bwrap/Landlock/Seatbelt）+ 权限分级 + 审批流
• 社区审计边界：node:vm 非安全边界、approval 回环、workspace-write 递归删除等真实逃逸面
• 插件安全审计清单：第三方审计方法论（#454）

• 缓存机制：上下文缓存 + 命中率实测 97%（Flash 折扣 98% / Pro 99%+）
• 成本模型：token 花在哪 + 推理档位联动 + 真实任务预算
• 可视化：session log / 余额插件看每笔成本

npx -y @deepseek-ai/dsh web          # 安装即启动 Web UI
dsh --profile headless "任务"        # 一次性任务（脚本/CI）

推理档位：low（最快/简单轮次）· high（默认）· max（最强/复杂推理）——low 为实测网关（pi-ai）档位，官方适配器用 off/high/max

工具链任务 90% 时间在思考——降档是最高杠杆提速 完整卡：docs/cheatsheet.md

# ① package.json 加依赖
"my-plugin": "link:C:\\path\\to\\my-plugin"
# ② cordis.patch.yml 加挂载
- insert:
    - id: my-plugin
      name: my-plugin

cd ~/.dsh/profiles/web && pnpm install && dsh web

可克隆模板（含纯函数+waterfall+测试）：examples/plugin-template/

agent-default-model:
  model: deepseek-v4-flash    # 或 deepseek-v4-pro
  reasoningEffort: high       # off（关闭思考/最快）/ high（默认）/ max（最强）

全字段（profile/cordis.patch.yml/常用场景）：docs/config-reference.md

1. dsh 是模型吗？ 不是——是运行时，模型通过 llm 插件接入
2. 和 Claude Code 区别？ Claude Code 是"整车"，dsh 是"乐高底座"（开源可定制）
3. 要花钱吗？ dsh 免费开源；对话按量付费（缓存折扣：Flash 档 98% / Pro 档 99%+，实测会话缓存命中率 97%）
4. 插件装不上 404？ rc.1 依赖断裂——用 ^0.1.0-rc.6 线
5. 能进生产吗？ rc 阶段有破坏性变更；生态玩法现在可入

   完整 FAQ（六类）：docs/faq.md