15 篇文章带有标签 “harness”

本文档以 @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 端）

一、项目定位与设计哲学

OpenClaw 不是 AI 模型，而是一个开源（MIT）的 AI Agent 运行时框架（Runtime Framework）——它坐在 AI 模型与外部世界之间，作为一个常驻运行的单体运行时网关（Gateway），负责把自然语言指令转化为真实的系统操作。

定位公式：

OpenClaw = Gateway（网关） + Agent Runtime（运行时） + Skills（技能） + Memory（记忆）

五项核心设计哲学：

理念	说明
Local-first（本地优先）	数据不离开用户设备，记忆为本地 Markdown，配置为 JSON；使用 Ollama/vLLM 本地模型时内容永不外传
网关而非框架	不是 SDK/库，而是独立运行的控制平面进程
模型无关（Model-Agnostic）	一行配置切换 Claude/GPT/Gemini/DeepSeek 等，按任务路由不同模型
插件化内核	Skills、Channels、Providers 均可热插拔（v2026.3.22+ 全面插件化）
工程化 Agent	从聊天机器人升级为任务调度执行系统，强默认不阉割能力，危险路径暴露为操作者可控开关

命名含义： Claw（龙虾钳子）= 抓取/操控/执行能力；Open = 完全开源、社区驱动。

递归自我改进（recursive self-improvement, RSI） 的概念可以追溯到 I. J. Good (1965)，他将"超智能机器"定义为一个能够在所有智力活动中超越人类、并设计出更好的机器来改进自身的系统。Yudkowsky (2008) 使用"递归自我改进"这一术语来描述一个特定的反馈循环：AI 利用其当前的智能来改进产生其智能的认知机制。

这种反馈循环在现代 AI 中可能意味着模型直接重写自身的权重，或者更广泛地说，模型改进了训练流水线和部署系统，从而催生出一个在经济价值任务上表现更优的继任模型。AI 研究发展的速度在前沿实验室中已被证明正在急剧加速（Anthropic；OpenAI）。

我特意提到 "部署系统"，因为原始模型与真实世界环境之间的这一层，似乎与模型原始智能（即预训练后的评估）同等重要。Harness 是 AI 部署的重要组成部分，Claude Code 和 Codex 等成功的编码智能体产品已证明了这一点。Harness 是围绕基础模型的系统，负责编排执行、决定模型如何思考和规划、调用工具和执行动作、感知和管理上下文、存储产物以及评估结果。

本文将聚焦于 harness 工程相关的研究，以及它如何促进 RSI。

• SkVM 论文

上海交通大学

摘要

LLM 智能体越来越多地将技能（skill）作为可复用的组合单元。尽管技能在不同智能体平台间共享，但现有系统将其视为原始上下文处理，导致同一技能在不同智能体上表现不一致。这种脆弱性损害了技能的可移植性与执行效率。

为应对这一挑战，我们分析了 118,000 个技能，并从传统编译器设计中汲取灵感。我们将技能视为代码，将 LLM 视为异构处理器。为使可移植性成为现实，我们将技能的需求分解为一组原语能力（primitive capabilities），并衡量每个模型-执行框架（model-harness）组合对这些能力的支持程度。基于这些能力画像，我们提出了 SkVM——一个面向可移植且高效技能执行的编译与运行时系统。在编译期，SkVM 执行基于能力的编译、环境绑定与并发提取。在运行期，SkVM 应用 JIT 代码固化（code solidification）与自适应重编译以优化性能。

我们在 8 个不同规模的 LLM 和 3 个智能体执行框架上评估了 SkVM，覆盖 SkillsBench 及代表性技能任务。结果表明，SkVM 显著提升了不同模型与环境下的任务完成率，同时降低 Token 消耗高达 40%。在性能方面，SkVM 通过增强并行性实现最高 3.2× 加速，并通过代码固化实现 19–50× 的延迟降低。

1. 引言