dsh-assembler

September 8, 2026 · View on GitHub

把一句话需求装配成一个能干活的 AI agent,并且交得出去。

dsh-assembler 是一个 DeepSeek Harness (DSH) 插件。用户用自然语言描述想要的 agent("帮我做一个能查订单、开工单、转人工的客服机器人"),装配器从能力目录匹配零件、发射 agent preset、然后在真实会话里试跑验收——新会话选中该 preset 即可使用。

能力目录由索引流水线自动生长:开源库、公开 API、客户自有接口、客户知识,都能一条命令收进目录,过质检门才入库。不写胶水代码,只写配置。

从你的座位看,它是这样工作的:你用一句话描述想要的 agent。助手先把架构摆给你看——能力清单、数据模型、工作流,以及目录覆盖不了的缺口(每个缺口都由你拍板:现场造件、降级、还是砍掉)——等你点头才动手。零件靠毫秒级目录检索找到,每个候选都带价签(它的说明书会给 agent 每轮对话加多少 token、要不要拉进程、要什么凭证);preset 由确定性发射产出、全部安全闸门在场;最后由独立考官在真实会话里试跑证明它能干活,才连同网页、供应链 BOM 和一份可反复自查的体检包一起交到你手上。

毕业不受惩罚:这里的一切都是真实可查的工件——零件是普通进程、出处钉死,交付的 agent 是一份可 diff 的文本组合加它的 BOM,执行层与框架无关。哪天你不用装配器了,东西全归你:零件照跑、preset 照挂,没有任何东西被扣作人质。

一览


能力目录	103 个零件 / 311 个工具——71 库型、27 服务型、5 第一方(`index/catalog.yml`)
验证	每次装配以独立黑盒探针在真实会话收尾;每张网页过可达门 + 真会话环路门
耗时	单 agent 典型几分钟内交付,含验收

特性

直接开口:在任意 DSH 会话里描述你要的 agent。助手先和你过一遍架构(缺口逐个由你拍板),毫秒级检索选件,装配后只交付独立探针验证过的东西
装配即验证:装配完成后自动派生验收探针,在绑定新 preset 的真实会话里试跑,按内容型验收标记判 PASS/FAIL;FAIL 带证据返回——哪一轮、缺哪个验收标记、agent 实际回了什么——修复因此是外科式的(换零件、收紧 persona、同名重发),而不是盲目重试;PASS 时还会在 preset 旁落一份 selfcheck.json,日后任何改动都能用同一张考卷复查(find → assemble → verify 闭环)。探针快速且诚实:agent 中途向(不在场的)用户求助即判 FAIL 并带回问题原文,每一轮探针的工具动作实时上链
多轮场景探针:派生器自行决定探针形态——纯计算需求出单轮题,跨轮需求(记账/归档/追踪)出 2-4 轮场景脚本,同一会话里逐轮验收,后面的轮次查询前面轮次写入的状态。全程黑盒:只看回复,不看轨迹
多 agent 班子:直接要一套("客服、对账、库存三个 agent,共享同一套商品/订单数据"),agent 逐个装配并钉到同一个共享数据库,交接本身也被验证:独立探针让一个 agent 写入一条记录、再让另一个 agent 读回来
缺件工单:选型报出目录尚不能覆盖的能力时,装配器把可执行工单写进 <preset>/gaps/:缺什么、造零件的真实入库命令、以及闭环的重跑命令。写缺失零件的活交给调用方 agent(它有全套 coding harness);装配脊柱保持确定性,验收永远归装配器自己的黑盒探针
装配直播台:每次装配把行动链双写进 <preset>/progress.log;直播台页面(/assembler/ui/_console)轮询它,让慢装配变成一条可见的、带时间戳的轨迹——"卡了还是在干活"一眼可判,而不是一颗沉默的转圈 chip。选型、发射、探针轮次、每轮工具动作、20s 心跳都在那里滚动
知识包(via: knowledge):客户手册/SOP/产品目录作为静态教材进目录,过检索命中门(探针问题检不出预期片段就拒收),装配时拷进 preset 的 kb/——交付物自包含
凭证契约(接口先就位,key 后补):零件只声明需要哪个环境变量及用途,值永不进 preset;未配时零件照常启动、listTools 成功、调用返回可行动错误;装配侧对应为"装配成功 + 探针 SKIPPED + 配置指引"。可选凭证(如 GitHub 公开读)走匿名降级不拦验证
客户私有目录:catalogs/<client>/ 自带 generated/、index/、capabilities.yml——A 客户的零件不会出现在 B 客户的装配里,隔离靠分文件而非过滤条件
服务型零件:19 个实时数据服务已接入(天气/汇率/地理编码/节假日/宏观数据/美股财报/学术检索/维基事实/研究图谱/包情报/飞书/Slack/GitHub…)。库型锁 repo@rev,服务型锁条款 + 速率限制 + 数据许可,同样进 BOM
零件物料清单(BOM):每次装配随 preset 发射 parts.lock.yml——每个零件的出处、许可、验证状态、实际挂载名、知识包来源版本、待配凭证清单
联邦索引缓存:零件工具清单按(连接配置 + 适配器文件指纹)缓存,冷 ~5s → 热 0.002s
persona lint:机械核查 persona(点名的工具必须在挂载面里、禁止"第 N 步"编舞句式、长度界)
宪法与设计文档:docs/CONSTITUTION.md(把 vibe assembly 当一门编程语言来治,九条全带判法)· DESIGN.md —— 装配器做什么、不做什么,以及边界在哪

装完即有前端:一键装配出带 Web UI 的 agent

装配不只发射 preset——每个 agent 同时得到一张可直接操作的网页前端,由装配器在 host 上同源伺服(/assembler/ui/<preset>)。页面直连 host 公开 wire(session.create / session.prompt / events.mux),与 DSH 对话页共用同一个 agent、同一个持久工作区;打开页面自动拉取当前状态。

下面每张图都是一次真实装配的产物(真实装配、真实数据、真实截图;判定行原样摘自装配结果):

任务管理助手,帮我记录和推进待办任务,要一个可以拖拽的任务看板页面 → 自动验证:PASS · 前端验收:页面门+环路门 PASS

任务看板(暗色)

报销审批助手,登记报销申请,按额度规则给出审批意见并留痕,要一个能通过驳回的审批页面

审批台

记账助手,把每笔收支记到本地账本,之后可以查询和汇总,要一个能直接记账的网页页面

记录台

日常问答助手,能算日期、聊问题,要一个简洁的聊天页面

聊天台

机制:

前端模板零件(via: frontend,第五种零件):7 张模板——聊天台(兜底,每个 preset 默认自带)、表单工单台、记录台、仪表盘、任务看板(拖拽)、审批台、文件台;选型器按交互形状恰选一张
观感:基于 Franken UI(shadcn/ui 的免构建 HTML 版,MIT),本地 vendored——离线/内网交付零 CDN 依赖;亮暗自适应
前后端契约:页面在提问里自带 ```json 围栏契约(不依赖 persona),agent 回复即渲染成看板/表格/指标卡
前端也过验收:装配即验证新增两道前端门——页面可达门(HTTP 200 + 槽位完整)与会话环路门(按页面同款参数真开会话打一轮口令回显);沿用轮只重页面门
持久同库:装备槽为状态零件钉死默认数据库(工作区 data.db)并预建表结构,前端会话与 DSH 对话会话写同一份账——关页重开,数据仍在
模板盖不住的页面,现写:scaffold 写手席——emit_app 落一套锁死词汇的前端骨架(Vite + React + shadcn/ui + 固定通信 SDK,含记录台/看板两张可整页拷用的范例页),助手在唯一自由区 src/pages/ 照 PAGE-SPEC(每个动作标 face/wire/ai-thin/local 路由)写任意形状的页面;verify_app 五道门黑盒验收(构建/骨架锁/页面 lint/资产可达/行为考:face 动作真执行 SQL 并断言库效,wire 动作跑真会话探针),deploy_app 发布进 preset 同源伺服、留快照可一键回滚。实测定制看板页 face 直连 5.1ms;页面与对话会话仍共享同一份账(双面交付),交接由独立考官验证(一面写、另一面读回)

架构

┌───────── 索引流水线(供应链) ──────────────────────────────────────────┐
│ 开源库 / 公开 API / 客户接口 spec / 客户知识                            │
│   → 切能力点 → MCP 适配 → 质检门(冒烟 / 检索命中)→ 入目录             │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓
┌───────── 装配(能力消费) ─────────────────────────────────────────────┐
│ capabilities.yml(公共或客户目录) + 并行联邦                           │
│   → 毫秒级零件检索(候选带价签)→ 编排者拍板选型                        │
│   → 发射 preset + BOM + 知识包拷入 kb/                                  │
│   → 自动验证:派生探针(单轮或多轮场景)→ 真实会话试跑 → PASS/FAIL     │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓
┌───────── 交付(FDE) ─────────────────────────────────────────────────┐
│ 多 agent 班子:逐台 emit_preset 钉同一 sharedDb 共享库                  │
│   → verify_shared_data 交接考(一台写、另一台读回)→ 每台自带 BOM 档案  │
└─────────────────────────────────────────────────────────────────────────┘
                              ↓
┌───────── 运行时(harness 的领土) ────────────────────────────────────┐
│ 新会话选中 preset → DSH 按行挂载插件 → agent 真实调用零件工具          │
└─────────────────────────────────────────────────────────────────────────┘

装配器是 Cordis 插件,产物是 Cordis 插件组合清单(preset 每行 = 一个插件实例);零件是外部 MCP 服务器进程,通过 @deepseek-ai/dsh-mcp-client 桥接。装配器只在装配时存在——会话跑起来后它的进程死掉,一切照常。

快速开始

1. 安装

加入 DSH profile 的 patch 层(示例 ~/.dsh/profiles/web/cordis.patch.yml):

- insert:
    - id: dsh-assembler
      name: '@dsh-external/dsh-assembler'

package.json 依赖:"@dsh-external/dsh-assembler": "link:/path/to/dsh-assembler"。

服务型零件若需部署方联系方式(SEC 强制 UA、Crossref/OpenAlex polite pool),复制 .env.example 为 .env 并填自己的邮箱——不是凭证,但也不该硬编码任何人的地址。

2. 装配一个 agent

打开 DSH 网页,直接说:

帮我装配一个记账 agent:随手记收支,按月汇总,能设预算超支提醒,有查账网页

动工前你会先看到架构(以及目录缺口,逐个由你拍板);点头后装配、独立探针在真实会话里验收,然后你拿到 preset id、带证据的验收结论、和一张网页(/assembler/ui/<preset>)。工件都在 ~/.dsh/.agent-presets/<preset>/:parts.lock.yml(BOM)、selfcheck.json(体检包)、progress.log(装配直播链)。

3. 交付一整套班子(FDE 路径)

直接在会话里要一套 agent——"给我一套运营 agent 班子:客服、对账、库存、内容四个,共享同一套商品/订单数据,各有前端"——助手把需求拆成分工明确的 agent、逐个装配并验收(每台发射时钉同一个共享库),交接本身也被独立考官验证(verify_shared_data:一个 agent 写、另一个读回,读取指令里不许出现答案——照抄闸)。每台 agent 的 parts.lock.yml 就是它的交付档案:验收结论、零件出处、待配凭证、知识版本,全部从工件长出来。

目录结构

dsh-assembler/
├── src/
│   ├── index.ts            # 装配核心:目录加载/联邦/确定性发射/BOM/装备/知识
│   ├── orchestrated-tools.ts # 工具面:检索/发射/独立考官(search 唯一形态)
│   ├── verify.ts           # 装配即验证:探针机器(单轮/多轮场景)+ 真实会话驱动
│   └── persona-lint.ts     # persona 机械核查
├── capabilities.yml        # ★ 公共组装目录:能力条目 + mcp-servers + requiredSecrets
├── index/                  # ★ 公共零件索引(出处/许可/条款)+ 冒烟报告
├── generated/              # ★ 零件库:78 个 MCP 适配服务器(每零件一目录)
├── catalogs/<client>/      # ★ 客户私有目录:自带 generated/ index/ capabilities.yml knowledge/
├── bench/results/          # 装配质量基准账本(run-tagged,git 收录)
├── presets/
│   └── agent-template.yml  # preset 模板({{persona}}/{{packageRows}}/{{extraRows}}/{{param:k}})
└── scripts/
    ├── index-add.mjs       # ★ 索引流水线 CLI
    └── link-dsh.mjs        # 链接 DSH peer 包

能力目录

四种能力来源:

`via`	来源	例子
`package`	本仓库/自有插件包的工具	`crm-query`
`harness`	DSH 内置工具	`content-search`
`mcp`	MCP 服务器工具(装配时自动联邦)	`mcp-weather-forecast-current-weather` 等 229 条
`knowledge`	客户静态教材(装配时拷入 `kb/`)	`acme-policies-kb`

103 个零件 / 311 个工具 —— 71 库型、27 服务型、5 第一方。

服务型零件 —— 实时数据与外部系统

零件	工具	数据源	许可/条款	凭证
package-registry	`package-info` `package-versions` `check-license`	npm + PyPI registries	registry ToS	免
weather-forecast	`current-weather` `daily-forecast`	Open-Meteo	CC-BY-4.0	免
currency-rates	`latest-rates` `historical-rate` `convert-amount`	Frankfurter (ECB data)	Public-Domain-ECB	免
geocode	`geocode-address` `reverse-geocode`	OpenStreetMap Nominatim	ODbL-1.0	免
public-holidays	`list-holidays` `is-workday` `available-countries`	Nager.Date	MIT	免
worldbank-data	`country-indicator` `common-indicators`	World Bank Open Data	CC-BY-4.0	免
sec-filings	`lookup-cik` `company-filings`	U.S. SEC EDGAR	Public-Domain-US-Gov	免
scholar-search	`search-published` `search-preprints` `doi-lookup`	Crossref + arXiv	CC0-1.0 / arXiv terms	免
wiki-facts	`page-summary` `search-entity` `entity-facts`	Wikimedia (Wikipedia + Wikidata)	CC-BY-SA-4.0	免
research-graph	`search-works` `work-citations` `author-works`	OpenAlex	CC0-1.0	免
feishu-messaging	`send-message` `list-chats` `feishu-capabilities`	飞书开放平台	Feishu API ToS	`FEISHU_APP_ID` `FEISHU_APP_SECRET`
slack-messaging	`post-message` `list-channels` `slack-capabilities`	Slack API	Slack API ToS	`SLACK_BOT_TOKEN`
github-issues	`list-issues` `get-issue` `create-issue` `github-capabilities`	GitHub REST API	GitHub ToS	`GITHUB_TOKEN`(可选)

第一方零件 —— Node 内置薄壳,零第三方依赖

binary-write(write-binary-file) · crypto-hash(hash-text, hmac-sign, generate-uuid) · compress-gzip(compress, decompress) · dns-lookup(resolve-domain, reverse-lookup) · book-intake(浏览器→工作区文件直传 + epub 解析) · webhook-intake(入站事件接收) · ai-call(应用内独立 AI 补全) · static-deploy(把构建好的站点发布为 agent 页面) · app-scaffold(官方 create-vite 脚手架)

库型零件(按领域)

领域	零件(工具数)
文档办公	`pdf-generate`(4) · `pdf-extract`(3) · `pdf-report`(1) · `docx-generate`(3) · `docx-extract`(2) · `pptx-generate`(1) · `excel-read-write`(4) · `zip-archive`(4)
数据格式	`csv-parse`(3) · `yaml-convert`(2) · `toml-parse`(2) · `xml-parse`(3) · `json-query`(2) · `json-schema-validate`(2) · `html-parse`(4) · `html-to-text`(4)
文本处理	`markdown-render`(3) · `html-to-markdown`(1) · `readability-extract`(2) · `text-diff`(3) · `template-render`(4) · `fuzzy-search`(4) · `text-encoding`(2)
中文专项	`pinyin-convert`(2) · `chinese-convert`(2) · `word-segment`(2) · `num-to-chinese`(2)
计算	`math-eval`(2) · `currency-calc`(4) · `number-format`(4) · `semver-check`(3) · `geo-distance`(3) · `color-convert`(2)
时间日历	`date-format`(4) · `cron-parse`(2) · `calendar-parse`(3) · `calendar-generate`(4) · `rrule-expand`(2)
数据库	`sqlite-query`(3) · `mysql-query`(4) · `postgres-query`(4)
网络通信	`http-request`(4) · `email-send`(4) · `email-fetch`(4) · `rss-parse`(4)
媒体识别	`image-process`(4) · `ocr-parse`(3) · `qrcode-generate`(4) · `barcode-generate`(2) · `exif-read`(1) · `file-type-detect`(1)
安全校验	`jwt-decode`(2) · `ip-utils`(2) · `string-validate`(2) · `fake-data`(2) · `phone-parse`(2)
工程工具	`github-api`(4) · `browser-automate`(4) · `url-slugify`(3) · `transliterate`(2) · `safe-filename`(2)

完整工具级清单

email-send — send-email, verify-smtp-config, parse-email-addresses, create-test-account
_{nodemailer/nodemailer@v6.9.13 · MIT}
email-fetch — list-mailboxes, search-messages, fetch-message, list-message-summaries
_{postalsys/imapflow@v1.0.162 · MIT}
http-request — http-request, http-get, http-post, build-url
_{axios/axios@v1.7.2 · MIT}
html-parse — extract-text, extract-attributes, query-elements, serialize-html
_{cheeriojs/cheerio@v1.0.0-rc.12 · MIT}
csv-parse — parse-csv, unparse-csv, validate-csv
_{papaparse/papaparse@5.4.1 · MIT}
pdf-generate — create-pdf, merge-pdfs, extract-pages, pdf-info
_{Hopding/pdf-lib@v1.17.1 · MIT}
date-format — format-date, parse-date, date-diff, date-manipulate
_{iamkun/dayjs@v1.11.11 · MIT}
sqlite-query — query, execute, list-tables
_{WiseLibs/better-sqlite3@v11.1.2 · MIT}
github-api — get-user, get-repo, list-org-repos, search-repositories
_{octokit/rest.js@v20.1.1 · MIT}
markdown-render — render-markdown, render-markdown-inline, tokenize-markdown
_{markedjs/marked@v12.0.2 · MIT}
pdf-extract — get-pdf-text, get-pdf-info, search-pdf-text
_{pdf-parse/pdf-parse@1.1.1 · MIT}
excel-read-write — read-xlsx-file, write-xlsx-file, read-csv-file, write-csv-file
_{exceljs/exceljs@v4.4.0 · MIT}
docx-generate — docx-generate-text, docx-generate-table, docx-patch-document
_{dolanmiu/docx@8.5.0 · MIT}
zip-archive — zip-list-entries, zip-read-file, zip-create-archive, zip-update-archive
_{cthackers/adm-zip@v0.5.12 · MIT}
fuzzy-search — fuzzy-search, fuse-create-index, fuse-search-with-index, fuse-config
_{krisk/Fuse@v7.0.0 · Apache-2.0}
template-render — render-template, precompile-template, render-precompiled, validate-template
_{handlebars-lang/handlebars.js@v4.7.8 · MIT}
html-to-text — html-to-text, html-to-text-batch, html-to-text-table, html-to-text-links
_{html-to-text/node-html-to-text@9.0.5 · MIT}
xml-parse — xml-validate, xml-parse, xml-build
_{NaturalIntelligence/fast-xml-parser@v4.4.0 · MIT}
image-process — image-info, image-resize, image-convert, image-thumbnail
_{lovell/sharp@v0.33.4 · Apache-2.0}
rss-parse — parse-rss-string, parse-rss-url, extract-feed-items, parse-feed-metadata
_{rbren/rss-parser@v3.13.0 · MIT}
calendar-parse — parse-ics, parse-ics-file, fetch-ics-url
_{jens-maus/node-ical@0.19.0 · Apache-2.0}
calendar-generate — create-calendar, create-event, create-all-day-event, create-recurring-event
_{sebbo2002/ical-generator@v7.1.0 · MIT}
mysql-query — mysql-query, mysql-list-tables, mysql-describe-table, mysql-test-connection
_{sidorares/node-mysql2@v3.10.0 · MIT}
number-format — format-number, unformat-number, arithmetic, validate-number
_{adamwdraper/Numeral-js@2.0.6 · MIT}
qrcode-generate — qr-generate-png, qr-generate-data-url, qr-generate-svg, qr-generate-terminal
_{soldair/node-qrcode@v1.5.3 · MIT}
postgres-query — postgres-test-connection, postgres-list-tables, postgres-describe-table, postgres-query
_{brianc/node-postgres@pg@8.12.0 · MIT}
browser-automate — browser-open, browser-extract, browser-click, browser-screenshot
_{microsoft/playwright@v1.45.0 · Apache-2.0}
ocr-parse — ocr-languages, ocr-psm-modes, ocr-recognize
_{naptha/tesseract.js@v5.1.0 · Apache-2.0}
currency-calc — currency-calc, currency-format, currency-distribute, currency-parse
_{scurker/currency.js@v2.0.4 · MIT}
readability-extract — extract-article, extract-batch
_{mozilla/readability@0.5.0 · MIT}
pdf-report — create-report-pdf
_{Hopding/pdf-lib@v1.17.1 · MIT}
binary-write — write-binary-file
_{first-party@- · BSD-3-Clause}
text-diff — create-patch, apply-patch, diff-words
_{kpdecker/jsdiff@v9.0.0 · BSD-3-Clause}
crypto-hash — hash-text, hmac-sign, generate-uuid
_{first-party@v- · BSD-3-Clause}
math-eval — evaluate, unit-convert
_{josdejong/mathjs@v15.2.0 · Apache-2.0}
cron-parse — next-runs, describe-fields
_{harrisiirak/cron-parser@v5.10.0 · MIT}
semver-check — compare, satisfies, coerce-valid
_{npm/node-semver@v7.8.5 · ISC}
yaml-convert — yaml-to-json, json-to-yaml
_{eemeli/yaml@v2.9.0 · ISC}
pinyin-convert — to-pinyin, multi-tone
_{zh-lx/pinyin-pro@v3.29.2 · MIT}
chinese-convert — s2t, t2s
_{nk2028/opencc-js@v1.4.1 · MIT AND Apache-2.0}
html-to-markdown — html-to-markdown
_{mixmark-io/turndown@v7.2.4 · MIT}
text-encoding — decode-base64, encode-to-base64
_{ashtuchkin/iconv-lite@v0.7.3 · MIT}
phone-parse — parse-phone, format-phone
_{catamphetamine/libphonenumber-js@v1.13.11 · MIT}
compress-gzip — compress, decompress
_{first-party@v- · BSD-3-Clause}
dns-lookup — resolve-domain, reverse-lookup
_{first-party@v- · BSD-3-Clause}
json-query — query, query-multi
_{jmespath/jmespath.js@v0.16.0 · Apache-2.0}
json-schema-validate — validate, check-schema
_{ajv-validator/ajv@v8.20.0 · MIT}
toml-parse — toml-to-json, json-to-toml
_{squirrelchat/smol-toml@v1.8.0 · BSD-3-Clause}
docx-extract — docx-to-text, docx-to-html
_{mwilliamson/mammoth.js@v1.12.1 · BSD-2-Clause}
pptx-generate — create-pptx
_{gitbrent/pptxgenjs@v4.0.1 · MIT}
barcode-generate — barcode-png, barcode-types
_{metafloor/bwip-js@v4.11.2 · MIT}
string-validate — validate-string, sanitize-string
_{validatorjs/validator.js@v13.15.35 · MIT}
fake-data — fake-records, fake-text
_{faker-js/faker@v10.6.0 · MIT}
num-to-chinese — to-chinese, from-chinese
_{cnwhy/nzh@v1.0.14 · BSD-2-Clause}
jwt-decode — decode-jwt, verify-jwt-hs256
_{panva/jose@v6.2.9 · MIT}
ip-utils — parse-ip, cidr-match
_{whitequark/ipaddr.js@v2.5.0 · MIT}
transliterate — transliterate-text, make-slug
_{dzcpy/transliteration@v2.6.1 · MIT}
rrule-expand — expand-rrule, describe-rrule
_{jkbrzt/rrule@v2.8.1 · BSD-3-Clause}
exif-read — read-exif
_{MikeKovarik/exifr@v7.1.3 · MIT}
file-type-detect — detect-file-type
_{sindresorhus/file-type@v22.0.2 · MIT}
color-convert — convert-color, contrast-check
_{Evercoder/culori@v4.0.2 · MIT}
word-segment — segment-text, extract-keywords
_{linonetwo/segmentit@v2.0.3 · MIT}
geo-distance — distance, bearing, center-and-bounds
_{manuelbieh/geolib@v3.3.14 · MIT}
url-slugify — slugify, slugify-unique, slugify-custom
_{sindresorhus/slugify@v3.0.0 · MIT}
safe-filename — sanitize, sanitize-path
_{sindresorhus/filenamify@v7.0.2 · MIT}
package-registry — package-info, package-versions, check-license
_{https://registry.npmjs.org · registry ToS}
weather-forecast — current-weather, daily-forecast
_{https://api.open-meteo.com/v1 · CC-BY-4.0}
currency-rates — latest-rates, historical-rate, convert-amount
_{https://api.frankfurter.dev/v1 · Public-Domain-ECB}
geocode — geocode-address, reverse-geocode
_{https://nominatim.openstreetmap.org · ODbL-1.0}
public-holidays — list-holidays, is-workday, available-countries
_{https://date.nager.at/api/v3 · MIT}
worldbank-data — country-indicator, common-indicators
_{https://api.worldbank.org/v2 · CC-BY-4.0}
sec-filings — lookup-cik, company-filings
_{https://data.sec.gov · Public-Domain-US-Gov}
scholar-search — search-published, search-preprints, doi-lookup
_{https://api.crossref.org · CC0-1.0 / arXiv terms}
wiki-facts — page-summary, search-entity, entity-facts
_{https://en.wikipedia.org/api/rest_v1 · CC-BY-SA-4.0}
research-graph — search-works, work-citations, author-works
_{https://api.openalex.org · CC0-1.0}
feishu-messaging — send-message, list-chats, feishu-capabilities
_{https://open.feishu.cn/open-apis · Feishu API ToS}
slack-messaging — post-message, list-channels, slack-capabilities
_{https://slack.com/api · Slack API ToS}
github-issues — list-issues, get-issue, create-issue, github-capabilities
_{https://api.github.com · GitHub ToS}

许可证

所包装代码(库型 + 第一方零件):MIT 46 · Apache-2.0 7 · BSD-3-Clause 7 · ISC 2 · BSD-2-Clause 2 · MIT AND Apache-2.0 1

数据许可 / 服务条款(服务型零件):CC-BY-4.0 2 · registry ToS 1 · Public-Domain-ECB 1 · ODbL-1.0 1 · MIT 1 · Public-Domain-US-Gov 1 · CC0-1.0 / arXiv terms 1 · CC-BY-SA-4.0 1 · CC0-1.0 1 · Feishu API ToS 1 · Slack API ToS 1 · GitHub ToS 1

全部宽松许可,代码侧零 copyleft 风险。服务型零件另记数据许可——那是另一种义务:Nominatim 是 ODbL、Wikipedia 是 CC-BY-SA(署名/共享要求),因此逐条记录并随装配进入 BOM。

完整机器可读清单(含每个零件的 repo@rev、许可、条款、速率限制与工具描述):index/catalog.yml。

索引流水线(收录 CLI)

设计前提是调用方就是 agent:CLI 只做确定性环节(取源、出工单、装依赖、质检、登记),"切能力点 + 写适配代码"留给调用方。每个子命令末行输出 JSON 判定,机器可判读。

# 收开源库
npm run index:add -- kpdecker/jsdiff --pkg diff --id text-diff
npm run index:verify -- text-diff        # install → 冒烟(exit 0 必须)→ 独立 listTools → 报告
npm run index:register -- text-diff      # 幂等登记;下次装配联邦自动看见

# 收公开 API(锁条款/速率/数据许可,而非版本)
node scripts/index-add.mjs scaffold - --service https://api.open-meteo.com/v1 --id weather-forecast \
  --provider 'Open-Meteo' --license CC-BY-4.0 --terms https://open-meteo.com/en/terms --rate-limit '免费非商用无限制'

# 接客户系统(FDE 日常):吃 OpenAPI → 端点清单工单 → 客户私有目录
node scripts/index-add.mjs from-spec <spec-url|file> --id <id> --client acme \
  --requires-secret "TOKEN:用途说明,可含逗号;OTHER:第二个"

# 收客户知识(过检索命中门)
node scripts/index-add.mjs knowledge <文档目录> --id acme-policies --client acme --version 2026-08
# 写 probes.json(问题 + 预期片段)后:
node scripts/index-add.mjs knowledge-verify acme-policies --client acme

# 全自动:一条命令收录(需要在跑的 web profile)
npm run index:auto -- sindresorhus/slugify --pkg @sindresorhus/slugify --id url-slugify

npm run index:check     # 全量回归:跑每个零件的冒烟(离线时网络零件记 SKIPPED 并单独计数)
node scripts/index-add.mjs coverage   # 能力覆盖图:语义判重用

质检门在流水线里:verify 不过,register 直接拒绝。去重两层——机械硬门(同 id / 同 npm 包 / 同上游 repo),以及对着 coverage 覆盖图做能力级判重:目录收的是能力点,不是库。

输出示例

装配即验证(多轮场景)

需求"记账助手,把每笔收支记到本地账本,之后可以查询和汇总"——派生器判定这是跨轮任务,出了一个 3 轮场景:

自动验证:PASS — 多轮场景「证明记账助手能把收支持久化到 SQLite,并在后续轮次中查询和汇总」共 3 轮,逐轮通过
  第1轮 ✓ 「记一笔收入:项目款 8899 元,备注 INV-7781…」标记 [INV-7781, 8899]
  第2轮 ✓ 「再记一笔支出:办公用品 1200 元,备注 OFFICE-2201…」标记 [OFFICE-2201, 1200]
  第3轮 ✓ 「查询本地账本,列出所有记录并汇总收支」标记 [INV-7781, OFFICE-2201, 8899]

第 3 轮查的是前两轮写入的状态——这样验收才能证明状态真的活过了轮次。纯计算类需求则只出单轮题。

凭证的四种状态

# 缺必需凭证:装配成功,探针 SKIPPED,给出配置指引
自动验证:跳过(待配置凭证:SLACK_BOT_TOKEN——装配正确但无法实调外部服务,配好后重跑装配即可验证)
所需凭证:SLACK_BOT_TOKEN(待配置) — Slack Bot User OAuth Token(xoxb- 开头)

# 可选凭证:走匿名路径照常验证通过
自动验证:PASS — 探针「对公开仓库 octocat/Hello-World 做一次巡检…」通过
所需凭证:GITHUB_TOKEN(可选,未配则降级)

零件物料清单 `parts.lock.yml`(节选)

preset: currency-qr-assistant
parts:
  - capability: mcp-qrcode-generate-qr-generate-png
    server: qrcode-generate
    serverName: qrcode-generate-d0fb25cc   # 从 preset 字节读回,永远与实际挂载一致
    repo: soldair/node-qrcode
    rev: v1.5.3
    license: MIT
    verified: true
  - capability: mcp-weather-forecast-current-weather
    kind: service
    service: https://api.open-meteo.com/v1
    terms: https://open-meteo.com/en/terms
    rateLimit: 免费非商用无限制;商用需订阅
knowledge:
  - id: acme-policies
    docs: 2
    source: ACME 客服中心知识库导出
    version: 2026-08

开发

npm run link:dsh   # 链接 DSH peer 包(需要 DSH_SOURCE 或 ~/.dsh/source/current)
npm run build      # tsc 构建到 lib/
npm test           # 构建 + 全套单测(命名与发射闸 / 验收判定 / 联邦缓存 / 工具面契约钉…)
npm run index:check   # 全量零件冒烟回归

改 lib/ 后需重启 DSH web 进程生效;改 capabilities.yml 无需重启(装配时实时读取)。

写网络零件时的两个环境事实:Node 的 fetch 忽略 HTTP(S)_PROXY,除非设了 NODE_USE_ENV_PROXY=1;MCP SDK 的 StdioClientTransport 只透传白名单环境变量,代理设置不会自动进入零件进程。流水线已统一处理这两点,手写冒烟时需要自己把环境传下去。

许可证

BSD-3-Clause。零件适配的上游库许可证见 index/catalog.yml 各条目;服务型零件的数据许可与条款同样逐条记录在目录条目里。

一览

特性