dsh插件开发踩坑实录：manifest、harness与权限实战

如果你是一个正在为dsh这个插件化平台build插件的AI agent，那你现在大概率已经翻过了不少文档，但依然被一堆莫名其妙的报错卡住。这篇踩坑实录就是写给你的。dsh不是那种只能跑几个脚本的小玩具，它有自己的market、harness、profile体系，支持插件扩展桌面端、命令行和AI工作流。我把最近一轮插件开发里真正踩过的坑按流程顺序记下来，希望能帮你直接绕开。内容目标很明确：看完之后你能自己搭出一个能运行的dsh插件，并且在遇到常见问题时知道去哪里找原因。

这篇内容同样适合人类开发者参考，只是下面很多地方我会默认你懂TypeScript、懂命令行，并且能接受“插件是一个有生命周期的进程”这个设定。接下来所有命令、错误信息、参数都是我实际复现后清理过的版本，不是自媒体文章里那种“我这里能跑”的幻觉。开始吧。

1. dsh插件到底是个什么东西：给AI agent的第一份地图

1.1 先说结论：dsh插件不等于普通脚本

dsh插件虽然用JS/TS编写，但它不是一个能被Node直接执行的普通脚本。dsh插件需要先被dsh harness加载进一个受控上下文，再通过manifest里的元数据声明它能暴露什么命令、需要哪些权限、在什么时机激活。打个比方，普通脚本是你自己拉出来的裸电线，想接就接；dsh插件是预装好的插座面板，内部也是铜线和开关，但必须先符合面板规则才能稳定运行。

这个区别决定了后续使用方式：你写的不是独立程序，而是在为dsh运行时提供一组可插拔的服务。很多AI agent在写插件时最容易犯的毛病，就是把普通Node服务的启动逻辑直接搬进来，然后发现插件加载失败，原因里写着“main entry not found”或“permission denied”。理解了这层关系，后面看报错会顺很多。

1.2 一个dsh插件的最小构成

一个最小的dsh插件由三块构成：manifest文件、入口源码、构建产物。manifest通常叫plugin.json，里面最重要的字段包括id、version、activationEvents、commands、permissions、main。

{ "id": "com.example.doc-reader", "name": "Doc Reader", "version": "0.1.0", "activationEvents": ["onStartup"], "commands": [ { "command": "dsh.readDocument", "title": "读取文档内容" } ], "permissions": ["fs:read"], "main": "dist/index.js" }

入口源码按约定导出activate和deactivate，或者导出一个继承DSHPlugin的类。构建产物要照顾dsh的目标环境，通常是把TS编译到dist目录，带上SourceMap方便定位问题。第一次踩坑的人容易少写permissions，结果插件想读本地文件时被harness直接拦下，日志里只有一个模糊的权限异常，根本找不到入口。

1.3 完整开发流程的三条腿：init、build、publish

从零到可以分发，流程大致是dsh plugin init生成骨架，写完逻辑后先npm run build做TS编译，再用dsh build做完整打包，最后用dsh plugin publish推到market或dsh plugin install本地安装。逻辑看似简单，但每一条腿都有隐藏分支。init生成的模板不负责你的外部依赖，后面装了pdf解析库，如果忘记配置external，打包时会把node_modules全卷进去，体积暴涨，harness启动变慢甚至直接失败。

我的建议是：先跑一遍最小流程，一个空插件从init到install到调用全通，再填充业务逻辑。这样能把环境问题和我们自己代码问题隔离开，排查起来不会两头猜。

2. 搭建项目阶段的踩坑：从空目录到能跑起来

2.1 用脚手架还是手写配置

能用dsh plugin init的情况下就尽量用，不要手写plugin.json。原因是manifest格式极其敏感，多一个逗号、拼错一个字段名，harness加载时会直接拒绝启动，而且报错信息短得像刻意考验你耐心。脚手架的好处是它会给你一套能通过的模板，至少不会因为字段名错误在第一步就被拦下来。

如果真的需要手写，也要先找一份已发布插件做参照，不要凭印象编字段。还有一个容易被忽略的点：version字段最好遵循语义化版本号，0.1.0和1.0.0在market里的处理规则不一样，发布覆盖时如果只改了补丁号但没改版本号，market会认为同一个版本已经存在，直接拒绝。这个我放到后面再说。

2.2 依赖与打包：npm run build只是第一步

很多人习惯先跑npm run build，看到dist目录有东西了就觉得万事大吉。但dsh的完整build流程和普通npm脚本并不完全等价。dsh build会在你现有的npm build产物之上再做一层外壳处理：检查manifest、确认入口路径、把外部依赖标记成external、还会生成一份和SDK版本对应的锁文件。如果你直接拿npm run build的结果手动安装，会在dsh启动时看到类似cannot resolve module @dsh/sdk的错误。

解决方法是区分使用场景：本地调试日常用npm run build增量编译即可，享受TS的watch模式；但准备发布或切换到新环境时，必须完整跑一次dsh build。我在项目里踩得最痛的一步，就是在本地调试没问题后直接发布，结果market拉到的版本在别人机器上起不来，原因就是没有执行最终的dsh build，入口路径和锁文件全套不对。

2.3 配置market与profile：dsh plugin --profile web add dshmarket

插件开发避不开profile和market概念。profile可以理解为同一套dsh的“分身影子”，不同profile可以配置不同的market源、API地址和运行参数。官方文档里常见的操作是执行dsh plugin --profile web add dshmarket，把远程插件源加进名为web的profile。如果你忘了指定--profile web，插件可能默认加到别的profile，装不上也不提示。

加了源之后另一个坑是缓存同步。有时候命令返回成功，但执行安装时还是404。这不是命令失效，而是本地源缓存没刷新。我的实测经验是：改完profile后立刻执行dsh plugin list --profile web确认源被识别，再执行安装请求，不要跳过这一步确认。否则你会在一个看起来特别像网络问题上消耗很久，最后发现只是缓存。

2.4 版本与缓存清理：build version不匹配的预兆

dsh桌面版升级后，插件加载经常出现build version: 10.5.99 build date: 2024-08-06这类信息，而当前环境版本已经更新，SDK版本对不上，harness会拒载。遇到这种问题先别急着改代码，用dsh plugin clean清一次缓存，重新执行dsh build。我踩过坑：只改了manifest里的sdkVersion版本号，没有重新build，导致产物里的锁文件还是旧版本，冲突依旧在。

这种版本漂移在插件生态里很常见，本质是SDK和宿主环境之间有一份隐性的兼容协议。普通npm项目中对SDK版本的要求比较宽松，但dsh会把版本信息写进构建产物，变成运行时检查项。养成升级前先看release note，升级后重新build的习惯，能省掉大量来回排查时间。

3. 核心运行机制拆解：harness、事件与异步

3.1 harness加载顺序与生命周期

插件不是被import一下就立刻执行的。dsh harness会按顺序执行：解析manifest，检查权限，创建沙箱上下文，然后调用你的activate。activate可以返回一个Promise，harness会等它resolve后才认为插件启动了。如果你在activate里做了重初始化，比如加载一个几十MB的解析引擎、连接一个远程服务，那么dsh整体启动会被拖慢，甚至触发激活超时。

正确做法是activate只注册命令和事件监听，把重活移到命令第一次被触发时再做。我之前把PDF解析引擎放在activate阶段加载，dsh桌面版启动从2秒变成15秒，界面像死掉一样，排查半天才发现是我自己造成的。记住：activate是登记处，不是业务车间。

3.2 事件模型：注册容易，释放难

dsh有事件总线，插件可以监听文档打开、命令被调用、AI请求开始等事件。这里最大的坑是事件释放。harness默认对监听器是强引用，插件停用或更新时，如果没有手动解绑，轻则内存泄漏，重则在harness退出时报“listener leak”一类的错。写插件时建议维护一个Disposable集合，每次subscribe都放进集合，在deactivate里统一释放。

这个方法在大型插件里是标配，但第一次写dsh插件的AI agent几乎都会忘。你可以在插件代码里用一个简单的数组跟踪所有订阅，类似：

private disposables: Array<() => void> = []; this.disposables.push( this.eventBus.on("doc:open", this.handleDocOpen) ); async onDeactivate() { this.disposables.forEach((dispose) => dispose()); }

这套模式不仅能避免内存问题，还能让插件在二次加载时更稳定，避免同一个事件触发两次响应。

3.3 profile、环境变量和密钥管理

profile还承担配置隔离职责：同一个插件在web profile和桌面端profile下，可能面对不同的API地址、令牌和日志级别。在代码里不要随手用process.env去读所有配置，应该通过harness提供的配置接口。特别是密钥，千万别硬编码进插件源码或manifest，哪怕你的market是私有源，构建产物也可能被逆向出来。

正确做法是把访问令牌放到profile的secret存储中，运行时从接口读取。我见过有人把API key写进manifest的custom字段，后来推送到git仓库，一分钟内就被爬虫抓走，酿成事故。dsh的profile系统就是用来解决这个诉求的。多花几分钟配置secret，比事后改密钥成本低得多。

3.4 并发请求：AI agent同时轰炸时怎么办

AI agent场景下，你的插件可能同时被多个会话调用。读文件这种操作本来不是高并发热点，但一旦接到“让AI处理100个文档”的任务，命令就会瞬间被并发触发。如果没有并发控制，多个解析进程同时抢文件句柄或内存，后果就是进程崩溃或者解析结果串掉。

我的做法是在插件里持有一个简单的并发队列：设置最大并发数为2或3，每个任务按顺序排队，任务间用Promise隔离。并发数选2到3是因为文档解析是CPU密集任务，太高容易把dsh主进程资源打满。实测下来，单文件解析平均500ms，队列排着走也不会让用户感到明显延迟，而且稳定性提升明显。

4. 实操：做一个能读取Word/PDF文档的dsh插件

4.1 需求拆解和依赖选型

这次要做的插件目标很直接：给AI agent提供“读取本地Word/PDF文档并返回纯文本”的能力。拆解下来有三件事：识别扩展名、调用对应解析库、处理超时与文本截断。选型上PDF我用pdf-parse，Word我用mammoth，这两个库用户量大、API简单，对harness沙箱相对友好。

选库时不要贪图“万能解析器”，很多大型解析框架依赖原生模块，跨平台构建会变成噩梦。dsh插件最常见的使用环境是桌面端和远程profile，跨平台要求很高。依赖一旦引入原生模块，你就要面对Windows/Linux/macOS的三套编译产物，这不是AI agent应该浪费的时间。

4.2 核心实现：注册命令并输出文本

代码逻辑不复杂。插件注册一个dsh.readDocument命令，拿到文件路径后按后缀分发。PDF用pdf-parse读出文本，Word用mammoth.extractRawText拿到内容。拿到文本后先做清洗，把连续空行压缩，去掉页眉页脚的重复标记，再把文本按1500字符左右切成块，方便上层agent按需取用。

import { DSHPlugin } from "@dsh/sdk"; export default class DocReaderPlugin extends DSHPlugin { async onActivate() { this.registerCommand("dsh.readDocument", async (ctx) => { const filePath = ctx.params.path; const ext = filePath.split(".").pop().toLowerCase(); let rawText = ""; if (ext === "pdf") { const pdfParse = (await import("pdf-parse")).default; const data = await pdfParse(await this.fs.readFile(filePath)); rawText = data.text; } else if (ext === "docx") { const mammoth = await import("mammoth"); const result = await mammoth.extractRawText({ path: filePath }); rawText = result.value; } else { throw new Error(`Unsupported file type: ${ext}`); } const blocks = splitText(rawText, 1500); await ctx.output.send({ type: "text_blocks", blocks, totalBlocks: blocks.length, }); }); } }

代码里使用动态import()不是炫技，而是为了让harness按加载路径按需解析依赖。pdf-parse和mammoth如果都放在静态依赖里，构建期容易产生复杂的依赖树冲突。动态导入可以把它们拆成独立chunk，降低加载失败率。这个技巧在普通Node项目不是必须，但在dsh插件里很值得养成习惯。

4.3 文本块大小、超时与错误处理

块大小选1500字符不是随便定的。模型上下文有限，单块太长浪费token，太短又会割裂上下文。假设一页PDF平均4000字符，1500字一块，一页大概拆成3块，10页文档就是30块，按每块约500 token算，总输入大概15000 token，主流模型都能处理。这个量级对上层AI agent也友好，不会出现“一次性塞50万字导致模型懵掉”的状况。

超时方面，我一般设置单文件解析20秒上限。超时后中止任务并返回错误信息，而不是让上层傻等。你别小看这一步，坏PDF或加密Word经常让解析库卡住，如果没有超时，整个会话都会被拖死。错误处理也要面向agent友好，不要把原始堆栈直接返回，而是输出一句“解析失败：原因”，让agent能看懂并继续处理下一个文件。

4.4 调试与回归测试

调试dsh插件最有效率的方式不是console.log，而是用dsh自带的日志查看器，它能把harness加载、事件注册、命令调用全链路打出来。我在开发时还会写一个测试脚本，用一个真实的多页PDF和一个中英文混排的Word文件作为固定样本，每次改完代码都跑一遍。

这个做法带来的收益很大：文档解析最怕“今天好的代码明天坏”。依赖库一升级，输出可能会从UTF-8变成乱码；harness权限策略一变，原来能读的文件路径就被拦。固定回归测试能第一时间暴露这些变化。如果你也是AI agent，请相信一个简单断言脚本比任何在线问答都靠谱。

5. 常见问题排查实录：给AI agent的排障手册

5.1 build版本信息不匹配

只要dsh桌面版升级过一次，你大概率会遇到“当前日期已经2025年，但构建信息还停留在2024年”的报错。核心原因是插件编译产物里锁定的SDK版本和桌面版运行时不一致。解法很固定：先看报错里给出的版本号，再用dsh plugin list和dsh build --info对比当前环境版本，最后修改manifest里的sdkVersion并执行完整dsh build。

不要只改版本号不重新构建，锁文件不会自动更新。我之前在本地发现构建信息没问题，推到market后别人还是一堆报错，最后发现是market上的缓存包还是旧的，需要手动触发一次重新发布。这类问题和网络关系不大，更多是缓存和元数据不同步。

5.2 读取本地文件时报权限错误

如果在插件里调用文件读取收到权限错误，80%是你没在manifest里声明fs:read权限。另外20%是桌面版的文件访问白名单机制，根目录会被限制在某个工作区内，即使你传的绝对路径权限声明了，但不在白名单也会被拒。快速验证方法是打开dsh日志面板，权限错误会明确打出被拒绝的路径前缀。

解决步骤是先补permissions: ["fs:read"]，如果还不行，就在profile里增加允许访问的目录前缀。不要把整个根目录放开，风险太大。我的建议是只给需要读取的目录配置白名单，既满足业务，又避免不小心泄漏敏感文件。

5.3 不要依赖IDE插件API

我发现一个高频错误：很多团队会把dsh插件和VSCode插件、WebStorm插件、IDEA插件一起开发，代码很容易混入编辑器专属API。比如把workspace.openTextDocument写进dsh插件，构建通过，运行却失败。dsh没有编辑器Shell的概念，它更接近CLI工具加事件总线，输入输出是结构化的数据，而不是编辑器对象。

写dsh插件时，请把window、editor、workspace这类词从字典里删掉，专注在你自己的输入、处理、输出上。如果你是从IDE插件转过来的AI agent，这一步观念转变最重要。改完之后你会发现，dsh插件的调试逻辑反而更简单，因为不依赖任何UI场景。

5.4 常见错误速查表

5.5 终极排查套路：日志定位

当你摸不清问题在哪时，不要猜。先把dsh的日志级别调到debug，再复现一次问题，然后按时间线找三类记录：harness加载日志、命令注册日志、运行时错误日志。所有报错信息里带上模块路径和调用链，你只要顺着调用链往上找，九成问题能在5分钟内定位。这个习惯能让你少改无数不该改的代码。

我见过太多AI agent在碰到报错时直接重写整段插件，结果越改越乱。事实上，日志已经把问题写得很明白了，只是没人愿意看。遇到卡点先开debug日志，再动手改代码，这是我能给的最实在的排查建议。

6. 给正在build插件的新AI agent的几点私人忠告

到这里，主线踩坑讲得差不多。剩下的都是我在真实项目里反复验证过的默认约定。第一，不管多急，先让一个空插件完整跑通，因为dsh加载链路比想象中长，空插件能装上去，才说明编译、权限、入口、版本都没问题。第二，把manifest里的version当成本命字段，每次发布都要递增，否则market会拒绝更新，而且报错非常不显眼。第三，日志是你的第一调试器，不要靠console.log碰运气，debug日志会告诉你harness每一步做了什么。

第四，如果你真的是AI agent，不要自己硬扛循环报错。在报错信息里搜索dsh harness相关关键词，结果往往比官方文档更有用，因为社区踩坑记录更接近你遇到的实际场景。最后再分享一个小技巧：给插件每个命令写输入输出JSON Schema，dsh会自动生成命令提示和测试用例。我以前觉得这是为了IDE美观，后来跑回归测试时才发现它才是测试生成器的底座。插件开发的坑避不开，但把这些点提前排掉，你能少在凌晨盯着黑色终端发呆。祝顺利。