11 篇文章带有标签 “dsh”

本文档以 @wangjunjian/dsh-artifact-viewer 为实例，系统梳理 DeepSeek Harness（DSH）bundle 插件的开发方法：工作原理、架构设计、构建打包、测试、发布自动化，以及开发和发布过程中实际踩过的坑。

1. 工作原理

Bundle 插件是什么

DSH 的 bundle 插件是一个普通 npm 包，通过 package.json 里的 dsh 字段声明自己：

{
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["@deepseek-ai/dsh-client-runtime"],
      "external": ["@deepseek-ai/dsh-client-ui-primitives"]
    }
  }
}

• dsh.bundle.patch：指向一个 cordis patch 文件，负责把插件注册进 loader 树。
• dsh.client：声明浏览器半部分的运行平台、注入依赖和 external 包。

一份面向本仓库（DeepSeek Harness 外部 Bundle 插件）的全面开发规范。 内容均基于本仓库真实代码（src/、tsdown.config.ts、package.json、tests/ 等）提炼， 而非泛泛而谈的通用建议。改动代码前先读本文，能少踩 80% 的坑。

0. 项目定位速览

本仓库是一个 DeepSeek Harness（以下简称 DSH）外部 Bundle 插件，对外暴露一个面向模型（model-facing）的工具 github_trending，抓取 https://github.com/trending 的公开页面，返回结构化热门仓库列表。

基于 deepseek-ai/deepseek-harness（TypeScript / Cordis 插件总线）与 openai/codex（Rust / codex-rs crate 体系）两个成熟开源项目的真实源码整理。 本文把每层的关键数据结构、控制流、不变量讲清楚，并为每个核心模块附上实现逻辑——这些是写 Agent 时真正会踩坑的地方。 所有 代码路径 均为实际文件，可下钻核对。伪代码为便于阅读对真实实现做了抽象，但结构与关键分支与源码一致。

0. 先定位：Agent 是什么

Agent = 以 LLM 为决策核心、以 Tool 为手、以 Sandbox 为边界、以 Append-Only 会话日志为记忆的闭环。

两条跨实现的底层信条：

1. 会话日志是模型上下文的唯一真相（model-visible ⟺ logged）。 任何进模型请求的内容都必须能从日志重建。
2. 能力是可替换的 seam。 模型、工具、文件系统、沙箱都通过接口/adapter 解耦。

分层总览

基于 deepseek-ai/deepseek-harness（TypeScript / Cordis 插件总线）与 openai/codex（Rust / codex-rs crate 体系）两个成熟开源项目的源码与架构文档整理。 目标：用「分层 + 核心模块详解」的方式，把一个 Agent 讲清楚。

0. 先定位：什么是 Agent

一个 Agent 本质上是一个以 LLM 为决策核心、以工具为手、以沙箱为边界、以会话日志为记忆的闭环系统：

• 它接收用户意图（自然语言 / 注入上下文）；
• 把意图和环境信息组装成模型上下文，向 LLM 发请求；
• 解析 LLM 返回的「思考」与「工具调用」；
• 在受控环境里执行工具（读文件、跑命令、改代码）；
• 把结果写回会话日志，再驱动下一轮，直到任务完成。

无论 TS 还是 Rust 实现，所有 Agent 的模块都收敛到同一组子系统。下面按自底向上的依赖顺序分成 7 层。

分层总览

分析对象：packages/ 下全部 @deepseek-ai/dsh-* 插件。 统计口径：直接扫描每个包的 package.json（name / description 字段）+ 分组级 README.md，逐包核对，无遗漏。 结论：共 50 个能力分组、226 个插件包。 核心理念：everything is a plugin。整个 harness 建立在 vendored Cordis 之上，每个能力都以插件形式通过 ctx.effect() / ctx.on() / ctx.waterfall() 贡献。 架构范式：能力分离（capability seam）——同一能力族通常拆成「服务定义（Service Definition）/ 具体提供方（Provider）/ 消费方/工具（Consumer）」三层，互不耦合、可独立替换。

0. 总览：50 个分组 / 226 个包

分析对象：packages/**/src 下所有经 defineTool(...) / ctx.tools.register(defineTool(...)) 注册、或运行时注入的模型侧工具。 排除：测试 fixture、浏览器端 UI 占位工具、zod schema 字段名（误报）。 所有工具均由独立「消费方」插件注册，底层能力提供方（Provider）可在不改工具契约的前提下替换。

一、总览（按能力族分组的工具数）

本文用通俗类比拆解 deepseek-harness（简称 dsh）的整体架构与核心模块的工作原理。 所有结论均来自仓库 docs/ 下的架构与子系统文档（architecture.md、cordis-primer.md、subsystems/*、capability-seams.md）。 代码路径以 packages/... 与 docs/... 标注，便于深究。

一、一句话总览

dsh 是一个插件化的 AI 智能体运行底座。它有一条铁律：

产品的一切都是插件（everything is a plugin）。

模型适配器、工具注册表、会话日志、甚至驱动循环（agent loop）本身，统统是插件。 没有需要打补丁的"特权核心"——你想改任何一块行为，只要在别处再挂一个插件、或换掉某个实现即可， 因为所有注册都是可逆的副作用（reversible effects），插件卸载时自动回滚。

这就像一座城市：市政府（Cordis 框架）只提供"水电管网"（一套统一的服务注册 + 事件总线）， 各个部门（插件）自己接入管网、各司其职，谁搬走都不影响大楼立着。

二、地基：Cordis 插件框架（用"城市公用事业"来比喻）

docs/cordis-primer.md 把 Cordis 浓缩成五个想法：

一、整体定位：一个"日志驱动"的反应式状态机

ReactLoopAgent（packages/core/agent-loop/src/agent.ts）不是传统意义上的 while-loop 脚本，它是一个三态相机 + 事件日志回放器的复合体：

Phase = idle | maintenance | running

• idle：驱动器不存在，lastTurn 记住上次进度
• maintenance：独占的维护窗口（如 compaction），持有独立 AbortController
• running：驱动器存活，turn/step 计数 + wakeRequested 闩锁

关键设计：同一时刻只有一个驱动器 promise（activityDone），wakeDriver() 在驱动器存活时只设置闩锁而不重入，在 maintenance 或被 abort 的活动期间则把唤醒"挂账"，等收敛时重放（agent.ts:172-193）。这解决了 agent 系统最难的问题之一——唤醒信号的丢失与重入——用一个 latch 而不是消息队列。

二、输入侧：双通道 Inbox 的持久化设计

所有输入通过四个动词进来（agent.ts:113-132）：

1. 一句话定位

DeepSeek Harness 是一个**"一切皆插件"的 Agent 运行时**：以 vendored Cordis 为插件内核，把模型、工具、会话、执行环境、子代理全部抽象成可替换的能力接缝（capability seam），再用分层配置（profile / bundle / patch）组合成产品。它的本质不是"一个 agent"，而是一条生产 agent 的装配线。

2. 分层架构总览

Spritely 是一个跑在 deepseek-harness Web 界面里的浮动小精灵。它盯着 agent 的一举一动——待命、思考、写代码、调工具、等你确认、报错、收工——然后做出对应的表情和动作。眼珠会跟着你的鼠标转，可以被拖到任意角落，还能换角色、换背景。

这个项目完整走完了一条「dsh 客户端插件」的开发—独立化—分发链路，过程中踩了不少坑。这篇文章把三件事讲清楚：它怎么工作、怎么开发、怎么安装。

项目地址：github.com/wang-junjian/spritely

一、它是什么，能做什么

一句话：把 agent 的「内心活动」可视化。agent 长时间跑任务时，你盯着终端只能看到文字流，很难一眼判断它现在在干嘛、是不是卡住了。Spritely 用一个小精灵把状态翻译成表情和动作。

面向第一次接触 dsh 的开发者。读完本文你将能：理解 dsh 插件的运行原理、照着完整流程从零写一个 UI 插件、避开主题/背景/测试等高频坑。

全文以正在开发的 Spritely（精灵插件）为贯穿案例。

1. 心智模型：一句话理解 dsh 插件

dsh（DeepSeek Harness）是一个基于 Cordis 依赖注入框架的插件系统。一个"插件"就是一个可复用的功能单元，通过声明自己需要哪些服务、提供哪些能力，被宿主（host）动态加载和组合。

对客户端 UI 插件而言，一句话概括：

你在写一个 React 组件 + 一份状态源 + 一段注册逻辑。宿主负责在合适的时机、合适的位置把它挂载进界面，并通过"注入面"（inject face）把服务递给你。

一个 UI 插件（如右下角的精灵）由三样东西组成：

组成	作用	在 ui-sprite 里对应
组件	画出来的东西	SpriteMascot.tsx（SVG 精灵 + 菜单 + 面板）
状态源	组件读的数据（可观察）	sprite-state.ts / background-source.ts
注册逻辑	告诉宿主"挂哪、需要什么"	client/index.ts 的 apply / inject

2. 工作原理：插件是怎么被加载的

2.1 双端结构（node 端 / client 端）