hellosky983/dsh-foundry

dsh-foundry · Plugin Foundry（插件铸造厂）

Awesome DSH Plugin

一个自举式「一切皆插件」编译器：它本身是一个 DSH 插件，用来研发插件，并能被其它插件扩展。

Overview

Plugin Foundry 解决什么问题？ 在 DeepSeek Harness（DSH）里编写动态 Cordis 插件需要记住繁琐的运行时契约（harness.defineTool 的 output:{schema,render}、parameters 逐属性 DSL、inject 声明、可逆副作用……）。本插件把这些契约固化成蓝图（blueprint），把「写插件」变成「选配方 + 填参数」，一键编译出可直接 cordis_define 的宿主/浏览器代码，并在定义前做静态校验。

适合谁？ DSH 插件作者、需要把能力快速下沉成运行时工具的智能体（本插件与子代理皆可调用）、以及想用「插件扩展插件」的元编程场景。

核心价值：
- 一个 foundry 服务（ctx.get('foundry')），任何插件都能 registerBlueprint(...) 续写配方 → 生态自我生长；
- 三个模型工具 foundry_blueprints / foundry_scaffold / foundry_validate；
- 九种内置蓝图覆盖 Host/Client/RPC/事件/服务/定时器/系统提示/Skill/文件工具；
- 一张 Settings 里的蓝图画廊页（只读）。

Compatibility

| 项目 | 版本 |
|---|---|
| DeepSeek Harness (DSH) | 0.1.0-rc.6 |
| @deepseek-ai/dsh-tools（peerDependency） | ^0.1.0-rc.6 |
| 最后验证日期 | 2026-08-15 |

依赖声明在 package.json 的 peerDependencies。若你的 DSH 版本与 0.1.0-rc.6 差异较大，请先以 README 的「Development」冒烟测试验证。

Install / Uninstall

安装（link 方式）

⚠️ 不要用 dsh plugin --profile web add ./dsh-foundry（会把本地目录当 git 源解析而失败）。请手动 link。

1. 编辑 $DSH_HOME/profiles/web/package.json，在 dependencies 增加：
"dsh-foundry": "link:/绝对路径/dsh-foundry"

并在 dsh.profile.bundles 数组加入 "dsh-foundry"。
2. 在 profile 目录安装：
cd $DSH_HOME/profiles/web && pnpm install

3. 重启 DSH（或重载 web profile），验证：
dsh --profile web --dump-config   # 应看到 "# == dsh-foundry" 层

升级

更新 link 指向的源码目录后，cd $DSH_HOME/profiles/web && pnpm install，重启即可（link 包无需重装版本号）。

禁用 / 彻底移除

彻底移除：从 package.json 的 dependencies 与 dsh.profile.bundles 删掉 "dsh-foundry"
cd $DSH_HOME/profiles/web && pnpm install

Quick start

最小可复现示例（安装并重启后，在任意 DSH 会话里）：

1. foundry_blueprints
→ 返回 9 个蓝图（id / name / category / description / params）

2. foundry_scaffold { blueprint: "host-tool",
params: { toolName: "hello", toolDescription: "say hi" } }
→ 返回可粘贴的 code.host（已内置 output:{schema,render} 契约）

3. 把返回的 code.host 交给 cordis_define + cordis_run
→ 一个名为 hello 的模型工具立即上线，可被你和子代理调用

扩展新配方（任意插件内）：

const foundry = ctx.get('foundry')
if (foundry) foundry.registerBlueprint({
id: 'my-recipe', name: 'My Recipe', category: 'host',
description: '...', whenToUse: '...',
params: [{ name: 'x', label: 'X', type: 'string', required: true, default: '' }],
render: (p) => ({ host: 'return { apply(ctx) { ... } }', client: null, notes: [] }),
})

Configuration

本插件无配置项、无环境变量、无敏感信息。蓝图参数有内置默认值（如 host-tool.toolName 默认 my_tool），调用 foundry_scaffold 时按需覆盖即可。

| 项 | 默认 | 说明 |
|---|---|---|
| 蓝图参数 | 见各蓝图的 params | foundry_blueprints 会列出每个参数的 default |
| /foundry/state 路由 | 只读 GET | 仅向本地浏览器暴露蓝图元数据（无敏感数据） |

Permissions & data
- 文件系统：dsh-foundry 本体不读写任何文件。注意：其 fs-file-tool 蓝图会生成一个宿主文件读写工具——那是你之后自行部署的插件，非本插件行为；该蓝图已在参数说明与源码注释中明确提示（需先 fs.resolve(path)、listDir 结果需映射为标量）。
- 网络：仅在 DSH 的本地 web 服务上注册一个 GET /foundry/state 路由（回环地址），返回蓝图目录元数据。
- 凭据 / 用户数据：不访问、不读取、不上传任何凭据或用户数据。
- 敏感项：无。

故障排查

| 现象 | 原因与解决 |
|---|---|
| curl /foundry/state 返回 HTML 而非 JSON | 路由未注册。确认 bundle 用了 inject:['webServer'] 而非 ctx.get('webServer')（服务激活时序会导致后者在 apply 时为 undefined） |
| 检查服务时报 no catalogued Service named "foundry" | 正常现象：ctx.provide('foundry') 是运行时服务，不出现在静态 Service 目录里，ctx.get('foundry') 仍可用 |
| 安装后工具未出现 | 确认已重启、--dump-config 里有 # == dsh-foundry 层、@deepseek-ai/dsh-tools@^0.1.0-rc.6 已装 |
| parameters.type must be a value schema object | 正式 bundle 的 defineTool 参数必须是逐属性 DSL（{ prop: { type, required? } }），不能用 {type:'object',properties} 包装式 |

日志：插件无独立日志；宿主日志在 DSH 启动/运行输出中。回滚：按「Uninstall」移除，或把 profile 里 dsh-foundry 从 bundles 移除后 pnpm install。

开发

export PATH="/path/to/node/bin:$PATH"
语法检查（ESM）
node --check index.js && node --check client.js

冒烟测试（mock ctx，验证 3 工具 + foundry 服务 + /foundry/state 路由注册）
mkdir -p /tmp/t/node_modules/@deepseek-ai && ln -s  /tmp/t/node_modules/@deepseek-ai/dsh-tools
node --input-type=module -e 'import { name, inject, apply } from "dsh-foundry"; ...'

- 蓝图统一在 index.js 的 BUILTIN_BLUEPRINTS，用 makeBlueprint(...) 追加即可。
- 客户端画廊页在 client.js，通过 window.__ModuleLoader__.load 注册到 settings.section。
- 贡献：欢迎 PR。请确保新蓝图满足「纯 JS 函数体、可逆副作用、正确的 inject 声明」，并附 node --check 与冒烟测试结果。

许可证与安全

- 许可证：MIT（见 LICENSE）。
- 安全报告：请勿公开披露漏洞。发现安全问题请通过私有渠道（如仓库的 Private vulnerability reporting / 直接联系维护者）报告，我们会尽快响应。
- 本仓库不含密钥、个人信息或私有内容。