Feature Request: Official extension directory for user plugins with stable service injection

[lunerstarcloud]

Proposal: Support user extensions in <project-root>/extensions/ with stable plugin loading and .gitignore inclusion

---

问题背景

在 deepseek-harness 项目中，我们希望开发自定义插件，对外暴露稳定的 REST API，以便第三方系统集成 DSH 的 workspace、session、providers、models 等核心能力。
这些插件不应受官方内部重构影响，且应能独立于官方代码库进行维护。

当前，我们尝试将自定义插件放在项目根目录下的 user/ 目录中，并通过 web profile 的 cordis.patch.yml 挂载。但遇到核心障碍：自定义插件无法注入 router 服务，导致 dsh web 启动失败。

---

核心期望

1. 官方认可一个明确的扩展目录（建议命名为 extensions/），用于放置用户自定义的功能插件。
   该目录应被加入 .gitignore，确保用户代码不会被提交到官方仓库，也不会因 git pull 被覆盖或影响。

2. 提供稳定的插件加载机制，确保位于 extensions/ 下的插件能正常访问 router、workspaceRegistry、sessions 等核心服务，并能注册 HTTP 路由或 Remote 方法。

3. 即使 DSH 内部进行重大重构（如 bundle 结构、依赖注入方式变更），只要公开的数据结构（如 Workspace、Session 等类型）保持不变，外部集成应继续工作，无需修改插件代码。

4. 提供官方文档和示例，指导开发者如何在 extensions/ 目录下开发、构建、加载自定义插件，并说明与官方插件的集成约定。

---

当前阻碍（复现步骤）

1. 在项目根目录创建 user/session-list-api/（或 extensions/session-list-api/），编写自定义插件（尝试注册 HTTP 路由 /api/lunerstar/workspaceSessions）。
2. 在 ~/.dsh/profiles/web/cordis.patch.yml 中添加 insert 块挂载该插件。
3. 构建插件，并在 profile 的 node_modules 中创建符号链接或安装包。
4. 执行 pnpm dsh web，启动失败，错误日志显示：

   @deepseek-ai/dsh-session-list-api: pending (waiting for service: router)
   Error: cannot get property "router" without inject
   

尝试过的解决方案（均失败）：

• 使用 static inject 注入 router、ctx 等。
• 使用 apply 函数直接访问 ctx.router。
• 使用 ctx.ready、ctx.on('ready') 等待服务就绪。
• 使用轮询重试检测服务可用性。

所有这些尝试都因 Cordis 依赖注入机制的限制（服务未注册时禁止通过 ctx.router 访问）而失败。

根本原因（推测）：
官方 bundle（如 dsh-base、dsh-web-app）中的插件在 router 服务注册之后加载，因此注入成功；而用户通过 cordis.patch.yml 的 insert 块加载的插件在 router 服务注册之前执行，导致无法注入。

---

期望的解决方案

1. 明确扩展目录并加入 .gitignore

• 将 <project-root>/extensions/ 作为官方认可的扩展目录，并添加到根目录的 .gitignore 中。
• 该目录下的代码完全由用户维护，不参与官方版本控制。

2. 提供官方支持的挂载方式

• 在 dsh 配置中增加 dsh.extensions 或 dsh.plugins.user 选项，指定扩展目录路径。
• 在 web profile 启动时，自动扫描该目录下的所有包（或遵循特定约定，如 extensions/*/package.json），并在合适的生命周期阶段加载它们，确保 router 等核心服务已可用。

3. 提供生命周期钩子

• 提供 ctx.ready 或 ctx.on('services-ready') 等官方钩子，让插件在服务完全初始化后执行路由注册等操作，无需依赖 inject 顺序。

4. 文档与示例

• 在官方文档中添加“用户自定义插件”章节，提供完整示例（包括目录结构、package.json、源码、构建和加载步骤），确保开发者能快速集成。

---

附加说明

• 我们曾尝试使用 TypertRemoteService 和 @Remote 装饰器，但在 TypeScript 严格模式下遇到类型问题，无法顺利构建。若官方能提供稳定的装饰器兼容方案（如更新 tsconfig 推荐配置），将是更优雅的扩展方式。
• 我们期望 extensions/ 目录中的插件能作为独立的 Node 包存在，并通过 pnpm workspace 或 link 方式集成，方便开发和调试。

---

环境信息

• 操作系统：Windows 11
• Node.js：v22.23.2
• pnpm：v11.7.0
• deepseek-harness：main 分支（2026-09-08）
• TypeScript：v6.0.3

---

结论

当前 deepseek-harness 缺乏对用户自定义插件的官方支持路径，导致第三方集成困难。通过上述改进，可以大幅降低集成门槛，同时保证稳定性，使 DSH 成为一个真正可扩展的平台。

如果官方需要，我们可以提供更详细的设计建议或原型代码。请评估此建议的可行性，并告知后续计划。

[lunerstarcloud]

(base) PS D:\deepseek-harness> pnpm dsh web
$ node --import tsx/esm apps/cli/src/bin.ts "web"
D:\deepseek-harness\packages\boot\app-boot\src\index.ts:835
throw new Error(${binName}: ${stage}: ${detail}${stack}, { cause })
^

Error: dsh: plugin tree failed to load: failed to apply loader entry include (cordis:include): failed to apply loader entry sessionListApi (@deepseek-ai/dsh-session-list-api): cannot get property "router" without inject
Error: cannot get property "router" without inject
at registerWithRetry (file:///D:/deepseek-harness/user/session-list-api/lib/index.js:9:28)
at new apply (file:///D:/deepseek-harness/user/session-list-api/lib/index.js:46:5)
at Fiber.execute (D:\deepseek-harness\vendor\cordis\src\fiber.ts:253:30)
at (D:\deepseek-harness\vendor\cordis\src\fiber.ts:366:45)
at file:///C:/Users/Administrator/.dsh/profiles/web/#sessionListApi
at file:///C:/Users/Administrator/.dsh/profiles/web/#include
at boot (D:\deepseek-harness\packages\boot\app-boot\src\index.ts:835:11)
at async runProfile (D:\deepseek-harness\apps\cli\src\profile-boot.ts:264:15)
at async (D:\deepseek-harness\apps\cli\src\bin.ts:29:5) {
[cause]: Error: failed to apply loader entry include (cordis:include): failed to apply loader entry sessionListApi (@deepseek-ai/dsh-session-list-api): cannot get property "router" without inject
at updateError (D:\deepseek-harness\vendor\loader\src\config\entry.ts:26:10)
at Entry._init (D:\deepseek-harness\vendor\loader\src\config\entry.ts:287:13) {
[cause]: Error: failed to apply loader entry sessionListApi (@deepseek-ai/dsh-session-list-api): cannot get property "router" without inject
at updateError (D:\deepseek-harness\vendor\loader\src\config\entry.ts:26:10)
at Entry._init (D:\deepseek-harness\vendor\loader\src\config\entry.ts:287:13)
at async Entry.init (D:\deepseek-harness\vendor\loader\src\config\entry.ts:261:7)
at async Entry.update (D:\deepseek-harness\vendor\loader\src\config\entry.ts:172:41)
at async EntryGroup.create (D:\deepseek-harness\vendor\loader\src\config\group.ts:30:7)
at async Promise.allSettled (index 146)
at async EntryGroup.update (D:\deepseek-harness\vendor\loader\src\config\group.ts:71:24)
at async Include._apply (D:\deepseek-harness\vendor\include\src\index.ts:317:5) {
[cause]: Error: cannot get property "router" without inject
at registerWithRetry (file:///D:/deepseek-harness/user/session-list-api/lib/index.js:9:28)
at new apply (file:///D:/deepseek-harness/user/session-list-api/lib/index.js:46:5)
at Fiber.execute (D:\deepseek-harness\vendor\cordis\src\fiber.ts:253:30)
at (D:\deepseek-harness\vendor\cordis\src\fiber.ts:366:45)
at file:///C:/Users/Administrator/.dsh/profiles/web/#sessionListApi
at file:///C:/Users/Administrator/.dsh/profiles/web/#include
}
}
}

Node.js v22.23.2
[ELIFECYCLE] Command failed with exit code 1.
(base) PS D:\deepseek-harness>