dsh-assembler

dsh-assembler — Vibe Assembly for DSH

English | 中文

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

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

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

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

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

---

一览

---

特性

• 直接开口:在任意 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 包

---

能力目录

四种能力来源:

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

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

第一方零件 —— 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 脚手架)

库型零件(按领域)

完整工具级清单

• 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

---

开发