This is an infrastructure Skill. It does no work; it answers only one thing:You have already decided to call one of Doubaoya's capabilities, now how do you correctly fire off this call.
When the user says "write me a WeChat official account article", "find a few topics", "check whether this copy has prohibited words",do not use this Skill—
go through the corresponding business Skill (if you don't know which one, use the main entry dby). The business Skill decideswhich capability to use,
this Skill only handleshow to call that capability。
0. State this Skill's boundary in one sentence
| This Skill handles | This Skill does not handle |
|---|---|
| Authentication headers, base URL, division of labor between the two routes | Which fields a certain capability's input has (→ pull at runtime, see §1) |
Unified envelope,noResult / notice / detailUrl, error codes |
Which step the business process should do first (→ dby) |
What capabilities exist, which route to take (→ references/capability-index.md) |
How to process results into copy / cover / report (→ business Skill) |
Pitfalls in route selection across capabilities (→ references/routing-pitfalls.md) |
Pricing and quota (→ doubaoya.com console) |
1. 🔴 First protocol:Pull the contract fresh; local docs are only an index
Before calling, fetch this capability's input spec from the detail endpoint. Local docs (including this file) are only an index, not the truth.
This rule is not fastidiousness; it fixes a disease that has already flared up repeatedly:Once a contract is baked into a distribution, it is bound to drift.
The skill package installed on the user's machine isa snapshot, while the platform's input parameters are evolving—the field list hardcoded in the snapshot
becomes, on the next upstream revision, alooks very certain but is actually lyingfake spec. The agent assembles parameters according to it,
gets back VALIDATION_ERROR, and then retries repeatedly in the wrong direction.
Therefore:The capability list may be cached locally (it changes slowly, and if it changes the repository's gate will flag it red), but input parameters absolutely may not.
Where to get the input spec (three levels, stop at the nearest available)
Against the target capability'sdetail endpointsend a GET(no authentication, free, no points charged):
- Platform data capability →
GET https://doubaoya.com/api/apis/<platform>/<slug> - Productized Skill →
GET https://doubaoya.com/api/skills/<slug>
From the same response, take in order:
inputContract— the most authoritative.kindisjson-schemawhen,jsonSchemaiscomputed fresh from the server-side zodthe complete JSON Schema (draft 2020-12), cross-field constraints are carried in each node'sx-constraints, Chinese enums are closed sets;kindwhen it isno-schemait willExplicitly state that there is no specificationand provideroute,In this case, do not make one up yourself。inputUiSchemaof thefieldsarray ——inputContractthe fallback for when it has not yet gone live in the deployment you are working on. Each field has a path, a Chinese label, whether it is required, and a Chinese description (many billing rules are written right in that description). Verified with live pulls:all 94 capabilities 100% have this block, so this fallback holds for every capability today.requestSchema/inputSchema—— Example values, not a specification. Only when neither of the first two levels is available should you start with it, and be prepared to readVALIDATION_ERRORof themessageand correct it round by round.
⚠️
inputContractis a new field; not all deployments are already sending it. 2026-08-18 live pullhttps://doubaoya.comof the detail endpoint, the response does not yet have this field — the server implementation is ready but has not yet gone to production. So the order above mustjudge by whether the field exists, and must not assume it is definitely there.
2. Give business Skill inlinethe minimal protocol
Business Skill should copy the following passage in its entirety into its own SKILL.md, do not just write a single sentence “see doubaoya-gatewayfor details” ——
the agent very likely will not jump over to read it (putting routing knowledge elsewhere and expecting the agent to fetch it itself has really broken an entire chain before).
This passagedeliberately contains only the protocol, no capability list, and no input parameter fields—— that is exactly why it can be safely copied: the protocol is stable, and copying it once can last a long time; capabilities and input parameters are volatile, and the day you copy them in they start to rot.
## 调用都爆鸭(协议,抄自 doubaoya-gateway)
**本 Skill 用到的能力**:`<operationKey>` —— 详情端点 `<GET 路径>`
(只点名能力和详情端点;入参**不在这里写**,每次调用前现拉。)
1. **鉴权**:所有*调用*端点都要 `Authorization: Bearer $DOUBAOYA_API_KEY`。
优先从环境变量 `DOUBAOYA_API_KEY` 读;环境里没有就**问用户一次**,之后不再追问;
**绝不回显、打印或写进日志**,需要确认时只说前缀。基址 `https://doubaoya.com`。
2. **先拉规格,再拼参数**:`GET <详情端点>`(免鉴权、免费)。按 `inputContract` →
`inputUiSchema` 的 `fields` → `requestSchema`(示例值,非规格)的顺序取,**就近取到就停**。
🔴 **绝不照记忆或本文档里的字段名拼入参**——这里从来不写字段名,就是为了让你没得抄。
3. **照 `execution.target` 打,别自己拼地址**:同一个详情响应里有
`execution.target.method` 和 `execution.target.path`,前面拼上基址就是要打的地址。
`execution.mode` 为 `dedicated` 时方法未必是 `POST`(有 `PUT`);为 `unavailable` 时
**没有 `target`,别调**,如实告诉用户这条能力暂时不可用。
4. **两条路由互不回落**:`/api/skills/<slug>/invoke` 与 `/api/apis/<platform>/<slug>/call`
是**两个不相交集合**各自的入口,拿错集合的 slug 去打另一条一律 404,**换着花样重试没有用**。
所以第 3 条不是建议:地址只能来自详情响应。
5. **读信封**:成功失败都是同一层 `{ success, requestId, data, error }`。
**先看 `success`**——`true` 取 `data`,`false` 读 `error.code` / `error.message`。
成功信封上还可能多出三个可选字段(**缺席是常态,不是异常**):
- `noResult`:查询合法、就是没数据,**已不计费**。别当失败重试,如实告诉用户没结果并建议换条件。
- `notice`:本 Skill 有更新的提示,**原样转达**,不影响本次结果。
- `detailUrl`:这次结果在 doubaoya.com 上的详情页,可以给用户点。
6. **报错怎么办**(`HTTP` / `error.code`):
401 `MISSING_API_KEY` / `UNAUTHORIZED` → 让用户去密钥中心生成或重建,更新环境变量;
400 `VALIDATION_ERROR` → 照 `message` 改入参,改前**重拉一次规格**;
400 `DEDICATED_ROUTE` → 走错到通用代理了,`message` 里写着该打哪条,照 `execution.target` 重发;
402 `INSUFFICIENT_CREDITS` → 提示用户充值;
404 `SKILL_NOT_FOUND` / `ENDPOINT_NOT_FOUND` → 见第 4 条,**去另一个集合的发现接口找**,别猜 slug;
发现接口里也没有这条能力时,**多半是本机 skill 已经过期**(它点名的能力早就下架了):
跟用户说一句「你的本鸭 skill 可能过期了」,让他跑一次 `/dby-update`(或说「更新都爆鸭」),
然后**只重试这一次**。🔴 重试仍是 404 就如实告知能力已下架,**不许再更新、不许成环**。
503 `CAPABILITY_UNAVAILABLE` → **别重试**,换能力或如实告知;
502 `PROVIDER_FAILED` → 上游临时失败,**额度已自动退回**,可以直接重试。
🔴 只有上面这条 404 走「先更新再重试」,**别的错一律不许触发更新**——
401 是钥匙问题、400 是入参问题、402 是余额问题,更新 skill 一个都治不了,
把它们也当成「该更新了」只会让每次失败都多跑一遍安装。
🔴 Must neverbe copied into a business Skill
| Must not be copied | Why |
|---|---|
| Any capability’sinput parameter field list(name, type, required, enum values) | This is “baking the contract into the distributable”, which is the disease itself that this round is meant to cure |
references/capability-index.md thatcapability index(the whole table or large excerpts) |
A business Skill should name only the one or two it uses itself; copying the whole table = creating yet another copy that will drift |
| The upstream-returnedfield name list | The output structure will change too; read according to the actual response, do not read according to the documentation |
| Pricing, points, quotaspecific numbers | They will be silently repriced; copying them in means quoting the user the wrong price |
Maybe copied: only two things: the body of the protocol above, andyour own one or two capabilities’ operationKey + detail endpoint。
3. Protocol expansion (the full version of the inline passage)
3.1 Authentication and base URL
All capabilities are mounted under https://doubaoya.com , JSON in and JSON out.
Authorization: Bearer $DOUBAOYA_API_KEY
Content-Type: application/json
The key looks like dyh_…, generated at doubaoya.com → Log in → Key Center,the whole thing shows its full face only at the moment of generation。
The discovery and detail endpoints are exceptions: they do not require authentication and are not billed, so the step “pull the spec before calling” is free, and there is no reason to skip it.
POST /api/skills/recommendis a special case: itmust carryAuthorizationheader—a POST without the header gets stopped by the CSRF gate first and returns 403CSRF_FORBIDDEN(verified with a live call); it looks like an auth error, but actually it never got as far as auth.
3.2 Two collections, two routes,no fallback
| Collection | Discovery interface | Detail endpoint | Invocation route |
|---|---|---|---|
| Productized Skill | GET /api/skills |
GET /api/skills/<slug> |
POST /api/skills/<slug>/invoke |
| Platform data capability | GET /api/apis |
GET /api/apis/<platform>/<slug> |
POST /api/apis/<platform>/<slug>/call |
Live call on 2026-08-18: 17 Productized Skills, 77 platform data capabilities;the bulk of the count is in the latter.
Butdon't copy these two numbers into your judgment—capabilities get added and removed, so take the exact count from your own live call to total .
🔴 These two routesare not two aliases of the same set of capabilities. Hitting them with the slug from the wrong collection always gives 404, andthere is no fallback whatsoever—retrying a hundred times on the wrong half still gives 404.
3.3 execution: the sole source of the address
In both the discovery and detail responses, every capability carries a block like this (below is a response projection from a live call to /api/apis/trend/hot-topics
on 2026-08-18;only protocol-related keys are kept):
{
"platform": "trend",
"slug": "hot-topics",
"operationKey": "api.trend.hotTopics",
"execution": {
"mode": "generic", // generic=通用代理 / dedicated=专用路由 / unavailable=当前不可调
"sideEffect": "read", // read / generate / write_internal / write_external
"target": { "method": "POST", "path": "/api/apis/trend/hot-topics/call" }
}
}
modeisgeneric→ call it pertarget; the body is this capability's input parameters.modeisdedicated→ likewise call it pertarget, butthe method is not necessarilyPOST, and its invocation address has nothing to do with the detail endpoint(for example the detail is at/api/skills/dby-charter, but what you actually call isPUT /api/ip-profile/:id/charter)。so the address for a dedicated route cannot be inferred; you can only readtarget。 If you mistakenly take the generic/invokeyou get 400DEDICATED_ROUTE, and the error message directly says which one to use.modeisunavailable→ in this case there is notargetfield,availabilityofnoteis a reason that can be relayed to the user (the two seen in live calls were both "upstream interface under maintenance; automatically available once restored"). A hard call returns 503CAPABILITY_UNAVAILABLE。
target of path isthe full path, and prefixing the base URL is enough to send it.Don't assemble /api/skills/…yourself—
that is exactly how this repo historically wrote out an entire side of data capabilities as paths that were bound to 404.
3.4 inputContract looks like
Already implemented server-side,not yet in production(see the warning in §1). The shape is a discriminated union with kind :
// kind 为 json-schema:有真规格
{
"kind": "json-schema",
"jsonSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": { "…": "🔴 这一坨才是入参规格。本文档故意不展开——展开就等于把契约烤进分发物" },
"required": [ "…" ],
"additionalProperties": false
},
"route": { "method": "POST", "path": "/api/wechat/publish" }
}
// kind 为 no-schema:**没有**机器可读的规格,别自己编
{ "kind": "no-schema", "note": "…(说明为什么没有)", "route": { "method": "POST", "path": "…" } }
routeappears only ondedicated routecapabilities (the entry point for generic capabilities is already written onexecutionintarget, so it is not repeated).kindisno-schemaandrouteisnull⇒ this capability currently has nowhere it can be called (modeisunavailable)。- the absence of a field carries no meaning;
kindis what carries it—don't infer spec status from "whether a certain field is present".
4. references/ (load on demand; don't read it all at once)
Many interfaces is not a reason to split a skill; it is a reason to split references/ . There is only one gateway; the details are split by topic across the two documents below,
read whichever one you need:
| File | When to read it | What is in it |
|---|---|---|
references/capability-index.md |
You do not yet know which capability to name, or you are not sure which route it takes | The operationKey + one-line purpose + detail endpoint for 94 capabilities.For routing only |
references/routing-pitfalls.md |
After choosing a capability, before actually making the request | Which capabilities should not be mixed, when to use which one, and known pitfalls (including the one and only place where an operationKey name collides) |
🔴 What goes in these two and what does not — one criterion
The local documents answer “which one to use and what to watch out for”; the detail endpoint answers “what it looks like and how to fill in the parameters”. The former is updated as experience accumulates, while the latter changes as the catalog changes —whatever is mixed together is bound to be the part that rots first.
So references/ containsonly routing knowledge(which capabilities should not be mixed, which one to take in which scenario, and pitfalls hit before),
and absolutely no parameter tables / field lists / input-output examples. Other skill libraries can bake parameters into references because their interfaces
change slowly and also have version numbers;this platform's catalog changes in a week(on 2026-08-17 alone, 9 capabilities were added net),
and what is baked in starts rotting the same day — of the 80 packages installed on this machine, 32 are already stuck on old contracts that were long ago cut.
⚠️ This is not just discipline, it is gated: the repository's validator scansthe entire skill package directory(SKILL.md and references/ alike),
and once a per-capability input field appears in any one of them, it is flagged red on the spot.
5. The response snippets in this document were all actually pulled
Actually pulled on 2026-08-18 from the free read-only endpoint of https://doubaoya.com , excerpted as-is:
// GET /api/health
{ "success": true, "requestId": "1b4a97bf-…", "data": { "status": "ok" }, "error": null }
// GET /api/skills/<slug> —— 拿「平台数据能力」那一半的 slug 去打 Skill 详情端点(走错集合)
// HTTP 404
{ "success": false, "requestId": "ee693f75-…", "data": null,
"error": { "code": "SKILL_NOT_FOUND", "message": "Skill not found" } }
// GET /api/apis/<platform>/<slug> —— 一个根本不存在的 slug
// HTTP 404
{ "success": false, "requestId": "4c60e7ae-…", "data": null,
"error": { "code": "ENDPOINT_NOT_FOUND", "message": "Endpoint not found" } }
// POST /api/skills/recommend 不带 Authorization 头 —— HTTP 403,被 CSRF 闸拦在鉴权之前
{ "success": false, "requestId": "5cf9584d-…", "data": null,
"error": { "code": "CSRF_FORBIDDEN", "message": "Origin not allowed" } }
requestId is different every time; only the prefix is kept above.When reporting a problem, give requestId to the user together,
as it is the only clue for the server to locate this particular call.
6. Hard rules
- Pull input specifications fresh before calling, and treat the local documents only as an index. This file does not write the field names of any capability from beginning to end, precisely so that you have nothing to copy.
- The address can only come from
executionintarget, and never assemble it yourself. - Never echo the entire API Key, only say the prefix.
noResultis not a failure, do not retry;CAPABILITY_UNAVAILABLEdo not retry;PROVIDER_FAILEDcan be retried(the quota has been refunded).- Do not treat the counts and prices in this document as facts— rely on what is actually pulled.
- When a business Skill references this Skill,inline the protocol in §2, name only your own one or two capabilities, and copy nothing else.