DeepSeek Harness 学习目录大纲

本大纲基于 DeepSeek Harness 官方文档整理，旨在帮助初中级开发者从零开始，循序渐进地掌握 Harness 插件开发的核心知识与实践技能。

第一部分：基础入门篇

这一部分的目标是让你快速上手，亲手写出第一个可运行的 Harness 插件，并理解插件开发的基本流程。

1.1 第一个插件——Hello Harness

学习目标：理解插件是什么，并成功运行第一个插件。

内容简介：从零开始创建一个最小的 Harness 插件。你将了解插件的本质——一个导出 apply 函数的 TypeScript 模块，框架在加载时调用这个函数来完成初始化。通过实际创建插件文件、注册到配置文件并启动 Web UI，你将亲眼看到插件加载成功的日志输出。此外，你还会接触到插件生命周期中自动清理机制——通过 ctx 注册的任何东西（事件监听、工具、定时器等），在插件卸载时都会被自动清理，无需手动管理。

适合人群：刚接触 Harness 的开发者，建议作为第一个学习章节。

1.2 开发一个工具——让插件拥有"动手能力"

学习目标：学会为模型定义可调用的工具（Tool）。

内容简介：工具是 Harness 中让大语言模型能够"动手"操作外部世界的关键机制。本节通过一个 greet 工具示例，展示如何使用 defineTool 定义工具的名称、描述、参数结构和执行逻辑。你将理解工具开发的完整流程：定义参数 Schema → 编写执行函数 → 注册到工具注册表 → 在对话中让模型调用它。这是构建实用 Agent 应用的基础技能。

适合人群：已完成"第一个插件"章节的开发者。

1.3 插件配置——让插件更灵活

学习目标：掌握为插件添加可配置参数的方法。

内容简介：一个好的插件应该是可配置的，而不是把参数硬编码在代码里。本节讲解如何使用 Schemastery 定义配置 Schema，让用户在 cordis.yml 中传入配置值。你将学会：定义 Config 类型和同名 Schema、设置默认值、进行参数校验，以及理解配置变更如何触发插件的热替换。这是让插件具备生产级质量的关键一步。

适合人群：已掌握插件基本开发的开发者。

1.4 打包与安装——让插件可分享

学习目标：学会将插件打包成可安装的组合包（Bundle），并在 Profile 中安装使用。

内容简介：前面几节我们都是通过 --patch 方式加载本地插件，这种方式适合开发调试。本节教你如何将插件打包成一个标准的 npm 包，通过 dsh plugin add 命令安装到 Profile 中。你将理解两个核心概念——组合包（Bundle，描述"这个包贡献什么"）和  Profile（描述"这套配置由哪些组合包组成"），并掌握从开发到分发的完整流程。

适合人群：已完成插件开发、希望将成果分享或部署的开发者。

第二部分：框架进阶篇

在掌握了基础开发技能后，这一部分将带你深入 Harness 的底层框架——Cordis，理解插件的生命周期、服务机制和事件系统。

2.1 插件与生命周期——理解插件的"生老病死"

学习目标：深入理解 Cordis 插件模型和生命周期状态机。

内容简介：每个 Harness 插件都有一个独立的生命周期。本节详细讲解插件的六种状态——PENDING、LOADING、ACTIVE、FAILED、UNLOADING、DISPOSED——以及状态之间的流转规则。你将理解依赖驱动的加载机制：声明了 inject 的插件会等待所有必需服务就绪后才执行；还会深入理解自动清理机制的原理，以及 ctx.effect() 如何用于管理需要手动清理的自定义资源。此外，本节还涵盖嵌套上下文、手动 dispose 和热模块替换（HMR）等高级话题。

适合人群：希望深入理解框架运行机制的开发者，建议在完成基础篇后学习。

2.2 服务与依赖——让插件对外提供服务

学习目标：学会创建可被其他插件消费的服务。

内容简介：服务是 Harness 中实现能力共享和依赖解耦的核心机制。当一个插件需要向其他插件提供能力时，可以使用类形式的插件来定义服务。本节将讲解如何定义服务接口、如何让其他插件通过 inject 声明依赖，以及服务提供方被替换时依赖方如何自动响应。这是构建可扩展插件体系的关键技能。

适合人群：已掌握插件基础开发、需要构建复杂插件系统的开发者。

2.3 事件系统——让插件之间"对话"

学习目标：掌握使用事件实现插件间松耦合通信的方法。

内容简介：事件是 Cordis 插件间通信的核心机制，Harness 大量使用事件来实现松耦合的扩展点。本节详细介绍 Cordis 提供的四种事件模式：

• emit（广播）：所有监听器同步执行，适合通知类场景。

• bail（短路）：第一个非空返回值即终止，适合"拦截/判断"类场景。

• serial（顺序执行）：异步顺序执行，适合需要按顺序处理的场景。

• waterfall（瀑布/流水线）：每个监听器可以包装下游返回值，形成处理链。

适合人群：需要构建多插件协作系统的开发者。

第三部分：实战进阶篇

这一部分聚焦于 Harness 的高级实践模式，帮助你掌握企业级插件开发的设计思路。

3.1 能力的三种角色设计——构建可替换的能力体系

学习目标：理解并掌握 Service Definition、Service Provider 和 Consumer 三层架构设计模式。

内容简介：当一个能力足够通用、需要支持可替换的提供方时（例如 Bash 执行），Harness 会将其拆分为三种角色：

• Service Definition（服务定义）：定义服务接口和数据契约。

• Service Provider（服务提供方）：实现具体的能力逻辑。

• Consumer（消费方）：将能力以某种方式暴露给用户（如封装为工具）。

本节以 Bash 执行能力为例，详细拆解这三种角色如何协作，并讲解这种拆分带来的三大好处：提供方可替换、独立演进和 依赖解耦。最后通过一个完整的"三步走"教程，带你亲手实现一个三层架构的能力。

适合人群：已掌握基础和框架知识、希望构建生产级可扩展系统的开发者。

3.2 LLM 适配器——接入新的模型提供方

学习目标：学会为 Harness 接入自定义的大语言模型提供方。

内容简介：LLM 适配器是 Harness 扩展模型生态的入口。本节讲解如何通过继承 LlmAdapter 并实现 stream() 方法，将 Harness 的提供方无关请求转换为具体提供方的 API 调用。你将了解：

• 适配器的最小实现结构。

• StreamChunk 协议的完整规范——包括文本块、工具调用块、Token 用量和结束标识的生成规则。

• GenerateOptions 中包含的请求参数。

这是 Harness 中最具深度的高级主题之一，适合希望深度定制模型能力的开发者。

适合人群：已完成前述所有章节、有模型 API 集成经验的开发者。

学习路径建议

建议按照上述顺序逐一学习，每个章节完成后动手实践示例代码。前三部分（基础篇全部章节）是后续学习的前提，不建议跳学。第三部分的两章相对独立，可根据实际需求选择学习顺序。

总结

对于初中级前端开发者来说，Harness 插件开发是一条既有挑战性又充满乐趣的学习路径。你不需要成为 AI 专家，也不需要精通后端架构——你只需要掌握 TypeScript，理解插件的基本契约，就能在 AI Agent 的世界里自由探索。

“一切皆插件” ——这不仅是 Harness 的口号，也是你进入这个世界的入口。从今天起，跟着我，一步步学起来吧！