TT-Wang/dsh-assembler

dsh-assembler — Vibe Assembly for DSH

把一句话需求装配成一个能干活的 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 读回来
- 缺件工单:选型报出目录尚不能覆盖的能力时,装配器把可执行工单写进 /gaps/:缺什么、造零件的真实入库命令、以及闭环的重跑命令。写缺失零件的活交给调用方 agent(它有全套 coding harness);装配脊柱保持确定性,验收永远归装配器自己的黑盒探针
- 装配直播台:每次装配把行动链双写进 /progress.log;直播台页面(/assembler/ui/_console)轮询它,让慢装配变成一条可见的、带时间戳的轨迹——"卡了还是在干活"一眼可判,而不是一颗沉默的转圈 chip。选型、发射、探针轮次、每轮工具动作、20s 心跳都在那里滚动
- 知识包(via: knowledge):客户手册/SOP/产品目录作为静态教材进目录,过检索命中门(探针问题检不出预期片段就拒收),装配时拷进 preset 的 kb/——交付物自包含
- 凭证契约(接口先就位,key 后补):零件只声明需要哪个环境变量及用途,值永不进 preset;未配时零件照常启动、listTools 成功、调用返回可行动错误;装配侧对应为"装配成功 + 探针 SKIPPED + 配置指引"。可选凭证(如 GitHub 公开读)走匿名降级不拦验证
- 客户私有目录:catalogs// 自带 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/)。页面直连 host 公开 wire(session.create / session.prompt / events.mux),与 DSH 对话页共用同一个 agent、同一个持久工作区;打开页面自动拉取当前状态。

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

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

任务看板(暗色)

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

审批台

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

记录台

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

聊天台

机制:

- 前端模板零件(via: frontend,第五种零件):7 张模板——聊天台(兜底,每个 preset 默认自带)、表单工单台、记录台、仪表盘、任务看板(拖拽)、审批台、文件台;选型器按交互形状恰选一张
- 观感:基于 Franken UI(shadcn/ui 的免构建 HTML 版,MIT),本地 vendored——离线/内网交付零 CDN 依赖;亮暗自适应
- 前后端契约:页面在提问里自带 - 前端也过验收:装配即验证新增两道前端门——页面可达门(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):
yaml
- 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/)。工件都在 ~/.dsh/.agent-presets//: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//      # ★ 客户私有目录:自带 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 判定,机器可判读。
bash
收开源库
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  --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(节选)
yaml
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

开发
bash
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 各条目;服务型零件的数据许可与条款同样逐条记录在目录条目里。