ClearAI（包名 clearai-dsh）在详情页上是一个「认识论循环」插件，一句话是「你的研究，长成一个本体」。但作为工程样本，它更值得看的是另一面：一个纯插件凭什么在不改 DSH 引擎一行代码 的前提下，往宿主里加进一整套认识论契约、本体面板与独立评估？答案不在文档里，在 package.json 和它声明的两条 patch 里。
先说它是什么、怎么装
它在 DSH 里的定位是原生插件 · chat，由 Clearailhc 维护，Apache-2.0 许可，GitHub 星标 1,066，站点记录为「已验证」（已在 dsh 0.2.0-rc.2 下真实安装成功一次，L4 · 真实安装）。安装是标准动作：
装完重启 dsh web，新建会话后在顶部模式选择器里切到 ClearAI 即可。想对照同类插件的中文清单、安装形态与兼容性报告，可以先看 完整插件清单与汉化避坑指南；如果你更习惯先看别人踩过的坑再动手，同一份 完整插件清单与汉化避坑指南 里也把所有可复核字段摊开了。下面进入包结构本身。
两条 patch：bundle 声明的入口
package.json 里真正递交给 DSH 的，是这一段：
两条 patch 各管一摊：./cordis.patch.yml 是宿主侧的接线，./presets/clearai/clearai.patch.yml 是一个 agent preset ------也就是你在模式选择器里看到的那张 ClearAI 卡片。README 把这条路径总结得很直白：ClearAI 加在 DSH 的 composition plane（组合面） 上，拆开就是一个 host 包、一个 agent preset、一个 client 模块，对 DSH 引擎零改动。
这一点是理解整个包结构的钥匙。它没有 fork 引擎、没有打补丁进宿主核心，而是走 DSH 已经开放的组合声明线把新层接上去。所以引擎升级、插件升级可以各走各的。
client 半：platform 与三条 inject
前端那一半也在一处声明清楚：
platform: "web" 说明这个客户端模块只面向 web；三条 inject 声明它要挂靠的宿主能力------会话控制器、右侧边栏 UI、以及 locale（语言）。对应到界面，就是中间那个 Ontology 面板与右侧的 World Tree，以及「系统写出什么语言跟随你输入的语言、面板跟随 UI 语言」这条行为。
运行时依赖只有一个：zod
翻到 dependencies，你会看到整个运行时依赖只有一行：
README 的原话是「Its only runtime dependency is zod.」；而画出本体图与实体图要用到的图栈，是在构建期就打进 client 半的，不在运行时依赖里。这意味着装完之后，节点上不需要为一张图额外装一堆图布局库------它们随包一起来。对一个强调「本地优先（local-first）」的研究工具来说，这个取舍很关键：运行时面越窄，越容易在你的机器上稳稳跑起来。
engines 与 bin：门槛和入口
门槛写在 engines 里：
Node 要 >=22 ，DSH 要 >=0.1.7-alpha.1 ------README 解释这一代 dsh 才引入该预设所依赖的 composition declaration line，并说明已对照宿主的 0.1.7-rc.2 与 0.2.0-rc.1 验证过。入口则交给 bin：
也就是装完会多出一个 clearai-dsh 命令，npx clearai-dsh install 这类引导式安装就走它。顺带一提，站点侧记录的是「未声明 dsh 版本约束」，而 package.json 里另有 engines.dsh------两处口径不同，以包内声明为准更稳妥。
一条设计约束：受治理路径之外，写不进权威账本
把上面几块拼起来，你会看到它的工程哲学：只做宿主做不到的事 。README 把界线划得很清------认识论契约、领域本体、呈现这三件是 ClearAI 加的；而目标续跑、子代理、向你提问、交付物卡片、文件历史这些，全部由 DSH 本身提供。工作方式不受限，但有一条硬约束被测试钉死：受治理路径之外的东西写不进权威账本。
这条约束正是「每一条边都要通过循环挣得」在工程上的落地。别的知识图谱可以靠抽取与断言往图里堆边，这里的边只能走受治理的路径进来------你可以用各种不受限的方式探索，但只有通过认识论契约检验过的结论才进得了本体。
两个容易忽略的实现约束
没有第二个存储。 状态是从会话记录派生的，没有独立的状态库------好处是不用维护第二份真相，代价是会话记录本身成了单点 ：记录损坏或被清掉，本体状态就跟着走。理解这一点，你才会明白为什么备份 ~/.dsh 这类动作在有价值的研究课题上格外值得做。
图是确定性投影。 本体图与实体图来自 clear/ontology/ 下文件的同一份确定性投影，所以同样的文件永远给出同样的图。手改那些文件确实能改图，但也可能让投影与账本不一致------把它当只读产物更安全。
总结
clearai-dsh 的包结构可以一句话收束：用两条 patch（宿主接线 + 一个 agent preset）加一个 platform: web 的 client 模块，挂在 DSH 的 composition plane 上，运行时只依赖 zod，对引擎零改动；更多同类插件的包结构与中文资料，可以在 完整插件清单与汉化避坑指南 里横向对照。
适合与不适合
适合：想学 DSH 插件「如何不改引擎加能力」的插件作者；需要评估一个预设依赖面与治理边界的工程团队；做本地优先、希望运行时依赖越少越好的研究者；已经在 dsh 上跑研究、想弄明白数据落在哪儿的人。
不适合：只想一行命令装完就用、不关心包结构的人；不愿意接受 Node 22 与 dsh 版本硬门槛的环境；把「装了就是成功」当验收标准的团队------插件管理器不比对实际装到的版本，光看回显容易误判。
标签：clearai-dsh、DeepSeek Harness、插件包结构、composition plane
本文由 DeepSeek Harness Hub 自动整理，数据来源于插件详情页。