本文从架构视角拆解 deepseek-ai/deepseek-harness（dsh）。旧文的“首日 78,604 stars”缺少可复核的历史快照，不再作为评价依据；值得研究的是它怎样组织可替换能力。
它到底是什么
DeepSeek 官方开发的 Agent harness，以 Cordis 为底座，强调 everything-is-a-plugin。模型适配、工具注册、会话、Agent loop 都参与插件组合，不是一个不可替换的特殊内核加若干外围插件。
先看状态再看野心：README明确写着 developer preview，会有破坏兼容的变化。SAFETY明确未经过安全审计，不能视作安全或生产就绪软件。它能执行模型生成代码、载入插件并接触获准的文件、进程、网络和凭证；审批和沙箱只能降低风险。
它怎么转：插件树组装
架构文档描述：从空条目列表开始，叠加 profile 指定的 bundles，再加 profile patch、home patch 和命令行 overlays。patch 可按 id 替换整行配置或插入条目，preset 内也有自己的插件列表。
当前模板包括 web、headless、sdk、sdk-minimal 和 acp；它们是同一 dsh 启动器下的 profiles，不应拿旧 demo/bin 名称当并列正式启动器。已安装 CLI 后，可用文档中的：
dsh --profile web --dump-config
看实际组装树。模块可替换不等于语义兼容，替换模型、文件系统或执行环境后仍需契约测试和权限检查。
5 类扩展点（先找职责，再写插件）
- 模型适配：注册到
ctx.llm，处理消息和流式协议。 - 工具与执行：通过
ctx.tools和相关事件进入受控执行流水线。 - Agent 生命周期：用
agent/*观察或拦截正在进行的工作。 - 会话与状态：持久事件写入 session log，再由投影提供消费者所需视图。
- 界面与外部入口：复用服务和事件，不绕过统一启动/配置路径。
核心包也不止旧文的四个：当前文档还明确列出 system-prompt、agent-loop、scope 等职责。这里的五类是阅读导图，不是项目全部扩展点的固定数量。
5 条设计纪律（比背术语重要）
- 要委托才调用
next()。 waterfall 的 listener 不继续调用时，下游不会自动执行；有意拒绝工具或请求可以短路。不能同时说“所有 listener 必须 next”又把不 next 的权限拒绝当成正确示例。 - 模型可见输入必须可由日志重建。 这是 model-visible → logged，不是 logged → 全部进入模型。比如
assistant/attempt保留失败、取消或重试记录，却不增加模型历史。 - 区分持久与实时。
assistant/message/assistant/attempt是持久结算事件；UI 增量来自agent/assistant-stream的瞬时帧，不能继续监听旧文猜测的assistant/chunk。 - 完整可替换能力有接口、实现、使用者。 Definition、Provider、Consumer 的分工有助于替换，而不是保证所有 provider 都无缝兼容。
- 注册与卸载是生命周期责任。 可逆 effect 和响应式依赖是设计机制；异步任务、外部副作用、数据迁移仍需清理与测试。
三个最容易翻车的卡点
第一，复制过期代码。 文档和事件快速变化，示例需与依赖版本一致，不能只把事件名换一换就宣称已迁移。
第二，把架构约束当安全审计。 日志、typed events、沙箱和审批都不证明插件可信，也不保护已经允许访问的敏感资源。
第三，忽略外部模型与插件。 提示词、文件内容、工具结果和遥测可能走不同外部路径，必须按实际配置审查。社区插件身份不等于 DeepSeek 或其他模型厂商认可。
上手路径
官方 npm 入口：
npx @deepseek-ai/dsh web
默认 Web UI 为 http://127.0.0.1:3080。源码开发则按 README clone、pnpm install、pnpm run build，再 pnpm dsh web。本次只核对命令，不承诺“五分钟”跑通。
试用使用独立低权限环境和非敏感任务，先读 SAFETY，备份可访问文件，检查配置和插件，再逐步扩大能力。项目采用 MIT，第三方依赖另见其 notices。
我的判断
我认同把模型、执行环境和界面拆成可替换单元的方向。它有利于研究组合和演进，但不是“不用 fork”“不会失控”或“插件换了产品就自动正确”的证明。
值得学的是清晰的能力契约、配置层级和可追溯会话；值不值得用，由具体版本、任务和风险边界决定。
资料核对：2026-10-13，读取官方 README、架构文档、SAFETY 与许可证；未启动 DSH、运行插件或验证隔离和性能。