一份面向本仓库（DeepSeek Harness 外部 Bundle 插件）的全面开发规范。 内容均基于本仓库真实代码（
src/、tsdown.config.ts、package.json、tests/等）提炼， 而非泛泛而谈的通用建议。改动代码前先读本文，能少踩 80% 的坑。
0. 项目定位速览
本仓库是一个 DeepSeek Harness（以下简称 DSH）外部 Bundle 插件，对外暴露一个面向模型（model-facing）的工具 github_trending，抓取 https://github.com/trending 的公开页面，返回结构化热门仓库列表。
分析对象：
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 个包
本文用通俗类比拆解 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），持有独立 AbortControllerrunning：驱动器存活，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 端）