@henjicc/ai-sdk 0.2.8 → 0.3.0

package/docs/model-adaptation//346/226/207/346/241/243/351/207/207/351/233/206/346/211/213/345/206/214.md

@@ -1,311 +1,338 @@
-# 文档采集手册
-
-> 这份手册只记**做过一遍才知道**的东西。目标：下次做模型调研时，不再重新踩一遍坑。
-> 最后更新：2026-08-28（补充 SDK 官方资料先行、事件契约与首发验证规范）
-
----
-
-## 一、怎么发现文档：先拿全量索引，别靠单页链接往下点
-
-**最大的坑：一个模型往往对应多份文档、多个端点，只看用户给的那一个链接必然漏。**
-上一版适配 Midjourney 只做了 2 个端点，实际有 18 个；Grok Imagine 2.0 漏掉了整块图层选区编辑。
-
-### 三个平台都有 `llms.txt` 全量索引，第一步就抓它
-
-```bash
-curl -sL https://docs.apimart.ai/llms.txt -o apimart-index.txt   # 171 行，含全部页面
-curl -sL https://docs.kie.ai/llms.txt     -o kie-index.txt       # 517 行
-curl -sL https://fal.ai/llms.txt          -o fal-index.txt       # 只是代表性列表，不全，见下
-```
-
-然后**按前缀过滤出目标模型的所有页面**，而不是凭印象猜：
-
-```bash
-grep -oE "https://docs\.apimart\.ai/en/api-reference/(images|videos)[^)]*\.md" apimart-index.txt | sort -u
-grep -oE "https://docs\.kie\.ai/cn/market/[^)]*\.md" kie-index.txt | sort -u
-```
-
-### 发现「同一个模型有多份文档」的信号
-
-| 信号 | 例子 |
-|---|---|
-| 同目录下多个页面 | `images/midjourney/{generation,imagine,blend,describe,upscale,...}` 18 个 |
-| `official` / `ext` 后缀 | `gpt-image-2/{generation,official}`、`grok-imagine-2.0-ext/{generation,layer-region-edit,official}` |
-| `-lite` / `-fast` / `-mini` 变体 | `gemini-3.1-flash/{generation,generation-lite}` |
-| 平级的辅助能力 | `minimax-h3/{generation,context-ir,regeneration}`、`seedance-2-0/private-avatar` |
-| KIE 把能力拆成独立 model | `kling-3.0-omni/{text-to-video,image-to-video,reference-to-video,transformation}` |
-
-**判断标准**：只要索引里同一个模型名下有第二个页面，就必须打开看，哪怕名字看起来像「辅助说明」。
-
-### Fal 的索引不全，要靠探测
-
-`fal.ai/llms.txt` 只列代表性端点。Fal 的端点是**可组合路径**（`<厂商>/<模型>/<档位>/<输入形态>`），用 HTTP 状态码探测存在性最快：
-
-```bash
-for p in bytedance/seedance-2.0/text-to-video bytedance/seedance-2.0/image-to-video \
-         bytedance/seedance-2.0/reference-to-video; do
-  code=$(curl -sL -o /dev/null -w "%{http_code}" "https://fal.ai/models/$p/llms.txt")
-  echo "$code  $p"
-done
-```
-
-常见组合维度：`{text-to-video, image-to-video, reference-to-video}`、`{pro, standard}`、`{turbo}`、`{edit}`。
-探测出来的 404 也是信息——比如 `google/gemini-omni-flash/text-to-video` 不存在，说明 Fal 上做不了纯文生视频。
-
----
-
-## 二、怎么找文档：优先拿原始 Markdown，浏览器是最后手段
-
-### 1. 文档站：URL 后面加 `.md` 就是原文
-
-`docs.apimart.ai` 和 `docs.kie.ai` 都支持，且 `/cn/` 前缀是中文版：
-
-```bash
-curl -sL "https://docs.apimart.ai/cn/api-reference/images/midjourney/imagine.md"
-curl -sL "https://docs.kie.ai/cn/market/kling/kling-3-0.md"
-```
-
-**比浏览器渲染好在**：拿到的是完整原文（含被折叠的参数、被 Tab 隐藏的示例），不会因为 UI 折叠而丢内容。
-
-### 2. Fal：每个模型的 `llms.txt` 是权威实时 schema
-
-```bash
-curl -sL "https://fal.ai/models/<endpoint-id>/llms.txt"
-```
-
-它由平台元数据实时生成，**不会与线上端点漂移**，且**同时包含 schema 和价格**。
-
-枚举值被折叠成 `ImageSize | Enum` 时，去拿 OpenAPI 才能看到具体取值：
-
-```bash
-curl -sL "https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=bytedance/seedream/v5/pro/text-to-image"
-# → image_size 的真实枚举：square_hd / square / portrait_4_3 / ... / auto_1K / auto_2K
-```
-
-### 3. 官方控制台是 SPA，curl 拿不到正文——去找它的内容接口
-
-火山方舟的文档页 `curl` 只能拿到 18 个字符。用 ego-browser 打开后列出网络请求，就能找到真正的内容 API：
-
-```js
-await js(`performance.getEntriesByType('resource').map(e => e.name)
-  .filter(n => /api|doc|content/i.test(n))`)
-```
-
-火山方舟的结果（**可直接 curl，无需登录**）：
-
-```bash
-# 单篇文档全文（Result.MDContent 是完整 Markdown，Result.UpdatedTime 是官方更新时间）
-curl -sL "https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=1541523&type=online"
-# 全库目录（用来找价格页、模型列表页的 DocumentID）
-curl -sL "https://docs.volcengine.com/api/doc/getDocList?LibraryID=82379&DataSchema=all_second_nav&type=online"
-```
-
-常用 DocumentID：`1541523` 图片生成 API、`1544106` 模型价格、`1330310` 模型列表。
-
-**通用做法**：任何 SPA 文档站，都先用这招找内容 API，找到就退回 curl，别在浏览器里跟折叠 UI 搏斗。
-
-### 4. 阿里云百炼是 SSR，直接 curl 就有全文
-
-```bash
-curl -sL "https://help.aliyun.com/document_detail/3047054.html"   # 会 302 到 slug 页
-curl -sL "https://help.aliyun.com/zh/model-studio/model-pricing"  # 价格页，3.4 MB HTML
-```
-
-用户给的控制台链接里的 `url=3047054` 就是 `document_detail` 的 ID，可以直接换算。
-
-### 5. 价格页只能用浏览器（ego-browser）
-
-APIMart 和 KIE 的定价都是前端渲染的：
-
-- **APIMart**：图像/视频/LLM/音频是**标签页**，切了才渲染。用 `js()` 找文本等于「视频」的可见元素点一下，等 4 秒再取 `document.body.innerText`
-- **KIE**：441 个模型的**搜索框** + 分页。`fillInput('input[type="text"]', 'seedance')` → 等 3.5 秒 → 取全文
-  - ⚠️ 注意底部的 `1-25 of 28`：**默认每页 25 条，会漏**。换更精确的搜索词（如 `bytedance/seedance-2,` 带逗号）把结果压到 25 条以内
-
-把 ego-browser 的输出落盘要这样写（`cliLog` 走的是进程输出）：
-
-```bash
-ego-browser nodejs > out.txt 2>&1 <<'EOF'
-const task = await useOrCreateTaskSpace(<空间id>)
-cliLog(await js(`document.body.innerText`))
-EOF
-```
-
----
-
-## 三、怎么处理文档：两个提取脚本 + 一轮交叉校验
-
-### 1. KIE 文档是 OpenAPI YAML，用脚本提 schema
-
-KIE 每页正文是一个 ```` ```yaml ```` 代码块包着的完整 OpenAPI。手读会漏字段，**必须用脚本递归展开**（含 `enum` / `default` / `minItems` / `maxItems` / 嵌套对象）：
-
-```python
-# kie_extract.py  —— 用法：python3 kie_extract.py <文件...>
-import sys, re, yaml, json
-
-def fmt(name, sch, indent=0, req=()):
-    pad = '  ' * indent
-    typ = sch.get('type', '')
-    if 'enum' in sch:    typ += ' enum=' + json.dumps(sch['enum'], ensure_ascii=False)
-    if 'default' in sch: typ += f" default={json.dumps(sch['default'], ensure_ascii=False)}"
-    for k in ('minimum','maximum','minLength','maxLength','minItems','maxItems'):
-        if k in sch: typ += f" {k}={sch[k]}"
-    desc = re.sub(r'\s*\n\s*', ' ', (sch.get('description') or '').strip())
-    print(f"{pad}- {name} [{typ}] {'必填' if name in req else '可选'}: {desc[:1400]}")
-    if sch.get('type') == 'object' and 'properties' in sch:
-        r = tuple(sch.get('required', ()))
-        for k, v in sch['properties'].items(): fmt(k, v, indent + 1, r)
-    if sch.get('type') == 'array' and isinstance(sch.get('items'), dict):
-        it = sch['items']
-        if it.get('type') == 'object' and 'properties' in it:
-            r = tuple(it.get('required', ()))
-            for k, v in it['properties'].items(): fmt(k, v, indent + 1, r)
-
-for path in sys.argv[1:]:
-    t = open(path, encoding='utf-8').read()
-    m = re.search(r'```yaml\n(.*?)\n```', t, re.S)
-    if not m: print(f'{path}: 无 OpenAPI 块'); continue
-    d = yaml.safe_load(m.group(1))
-    print('\n=====', path.split('/')[-1])
-    for p, ops in d.get('paths', {}).items():
-        for method, op in ops.items():
-            print(f"### {method.upper()} {p} | {op.get('summary')} | {op.get('operationId')}")
-            rb = op.get('requestBody', {}).get('content', {}).get('application/json', {}).get('schema')
-            if rb:
-                req = tuple(rb.get('required', ()))
-                for k, v in (rb.get('properties') or {}).items(): fmt(k, v, 1, req)
-```
-
-**`input` 是 `oneOf` 的要单独展开**（KIE 用它表达「二选一的输入形态」，如 Kling Omni 的「单张首帧」vs「仅视频输入」）——上面脚本会跳过，需要另外 dump `schema['properties']['input']`。
-
-对比多个变体的字段差异，一行就够：
-
-```bash
-for f in seedance-2 seedance-2-fast seedance-2-mini; do
-  echo -n "$f: "; python3 kie_extract.py raw/$f.md | grep -oE "^    - [a-z_]+" | tr -d ' -' | tr '\n' ' '; echo
-done
-# 一眼看出 mini 少了 return_last_frame
-```
-
-### 2. APIMart 文档是 MDX，代码示例占 80%，先剥掉
-
-每页会把同一个请求写成 15 种语言的示例，正文被淹没：
-
-```python
-# apimart_strip.py —— 保留 bash/json，其余语言的代码块换成占位符
-import sys, re
-for path in sys.argv[1:]:
-    t = open(path, encoding='utf-8').read()
-    t = re.sub(r'```([^\n]*)\n(.*?)```',
-               lambda m: m.group(0) if m.group(1).startswith(('bash','json'))
-                         else f'\n[[{m.group(1).strip()} 示例已省略]]\n', t, flags=re.S)
-    print(re.sub(r'\n{3,}', '\n\n', t))
-```
-
-之后配合 `sed -n '/^## Body/,$p'` 直接跳到参数区。
-
-### 3. 必做的三项交叉校验
-
-| 校验 | 为什么 | 这次的实例 |
-|---|---|---|
-| **API 文档正文价格 vs 定价页价格** | 文档正文更新慢，经常是过期价 | Seedream Pro 文档写 $0.045/$0.09，定价页是 $0.02928/$0.05856 |
-| **同一模型跨供应商的取值集合** | 名字一样但取值/默认值经常不同 | Lite 分辨率官方是 2K/3K/4K，旧文档抄成了 1K/2K；`adaptive`(APIMart/KIE) vs `auto`(Fal)；`duration` 整数 vs 字符串 |
-| **schema 内部自相矛盾** | 供应商文档确实会写错 | KIE Qwen3-Pro 的 `enum` 与 `default` 不一致；KIE z-image 的 `aspect_ratio` 描述提到 `auto` 但枚举里没有 |
-
-**处理原则**：两处不一致时**两个都写进文档**并说明以哪个为准；文档自相矛盾时标注「接入前实测确认」，不要替供应商猜。
-
----
-
-## 四、SDK 官方资料先行与首发验证（唯一详细规范）
-
-Henji-AI 是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主。新模型、新供应商或新协议必须先在这里完成官方调研、SDK 实现和完整验证，再发布版本；消费项目只接入已经验证并发布的精确版本。禁止先在消费项目按猜测实现协议，再把结果回填 SDK。
-
-### 1. 先文档，后代码
-
-编码前必须把以下信息写入本目录对应的供应商/模型文档，并能逐项追溯到官方来源：
-
-- 模型展示名、API model ID 与适用区域/版本；
-- Base URL、端点、方法、鉴权、请求字段、枚举、限制和默认值；
-- 当前价格、计费维度、价格来源与冲突取舍；
-- 同步响应，或轮询、SSE、WebSocket 等异步/流式协议的完整事件契约；
-- 错误、终态、取消、断线、超时、资源释放与连接复用规则。
-
-缺少官方来源，或模型、端点、价格、事件契约中任一项仍无法确定时，必须把未知项和已查入口写清并暂停编码；不得用相近模型、旧版本、SDK 现状或消费项目行为替官方契约作结论。官方资料本身矛盾时同时保留冲突来源，标为“实现前待官方确认/授权实测”，不能替供应商猜。
-
-### 2. 流式与异步协议必须有事件契约矩阵
-
-只要涉及 WebSocket、SSE、流式 HTTP、上传后轮询或回调，就必须在供应商/模型文档中按官方资料建立事件级矩阵。每一个官方事件/状态单独一行，不得只写一条 happy path 示例：
-
-| 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
-|---|---|---|---|---|---|---|---|---|
-| 官方事件名或状态值 | 允许从哪些状态进入 | 逐字段写清存在性、类型与可空性 | `null`、空串、空数组、字段缺失分别是否合法以及是否忽略 | 保持/迁移到哪个状态 | partial/final/usage/finish 或无输出 | ack、上传、轮询、计时器、资源释放等 | 是否终止；官方错误码/原因 | 继续收消息、等待关闭、主动关闭或可开启下一会话 |
-
-矩阵还必须说明状态机不变量：首事件、合法重复/乱序、是否允许先终态后结果、什么才算“有效 final”、空终态如何处理、断线后能否恢复、取消与正常结束各释放哪些资源。若官方没有说明某项，明确写“官方未说明”，不要把实现假设写成官方事实。
-
-### 3. 官方示例与 fixture 一一对应
-
-官方资料中出现的每一个字面请求、响应或事件示例，都要逐项进入 `packages/ai-sdk/tests/fixtures/`，或由测试逐字内联引用同一份 fixture。fixture 必须记录：
-
-- 精确来源 URL 与抓取日期；
-- 内容是官方原样、仅做脱敏/不可联网替换，还是从字段表构造；
-- 任何替换的字段及替换原因；
-- 对应事件矩阵的行或场景。
-
-原样示例只允许做安全脱敏、ID/URL 不可联网替换和必要的稳定化，不得为了让当前 parser 通过而补字段。官方只有字段表、没有字面示例时，可以据表构造 fixture，但必须标为“依据官方字段表构造”，不能标为官方原样。合成负例必须放在独立场景或独立文件并标为 `synthetic-negative`（或同等清晰标记），不得冒充官方样本。fixture 的通用格式与现有目录约定见 [../../tests/fixtures/README.md](../../tests/fixtures/README.md)。
-
-### 4. fixture、parser 与测试必须闭环
-
-协议实现的精确测试必须从事件矩阵和 fixture 推导，至少覆盖实际适用的下列场景：
-
-- 官方 happy path 的逐事件解析与完整状态迁移；
-- 合法空值（包括合法空始帧/心跳/无输出事件）；
-- required 字段缺失或类型错误的明确拒绝；
-- 空终态、结束前无有效 final、重复事件、乱序事件；
-- 供应商错误事件、网络断开、取消、超时；
-- 正常结束、失败、取消、断线后的连接、计时器、迭代器和会话资源释放。
-
-“测试通过”还不够，门禁必须做一次**断牙验证**：临时破坏被测试的不变量（例如把合法空事件误判为错误、接受缺失必填字段、漏掉终态释放），确认对应测试确实失败，再恢复实现并确认重新通过。断牙改动不能提交；交接中记录破坏点和实际失败的测试。只匹配标题、关键词或 fixture 数量的检查不算协议门禁。
-
-### 5. SDK 首发与消费顺序
-
-发布和接入严格按以下顺序进行，任一步失败都在当前阶段修复，不跨阶段绕过：
-
-1. 在 Henji-AI 跑变更协议/模型的精确契约测试与宿主集成测试；
-2. 跑 SDK 全量测试、可移植性检查、类型/构建、打包与本地安装包验证；
-3. 从将要发布的包或远端预发布/正式包回装，在受限运行环境验证公开入口、按需 bundle 与版本内容；
-4. 发布 SDK；
-5. 消费项目精确锁定已验证版本及 lockfile integrity，不使用 workspace 提升、浮动范围或源码旁路；
-6. 消费项目再运行宿主 transport、凭据、媒体、取消、日志和资源释放的集成测试。
-
-真实付费网络只在用户明确授权时执行；没有真网不妨碍协议契约测试，但必须在交接中准确写明边界，不能把 fixture/scripted 测试表述成真实供应商成功。
-
----
-
-## 五、零散但会卡住你的坑
-
-| 坑 | 表现 | 解法 |
-|---|---|---|
-| **KIE 限流** | 连续请求后返回 HTTP **200**，但内容是 HTML 外壳 | 用 `grep -l "DOCTYPE html"` 检出，加 2 秒延迟重试。批量下载后一定要跑一次这个检查 |
-| **zsh 不做单词分割** | `for p in $PATHS` 把整个多行变量当成一个词 | 用 `while IFS= read -r p; do ... done < 路径文件` |
-| **Bash 工具禁用前台 `sleep`** | 加延迟的循环跑不了 | `perl -e 'select(undef,undef,undef,2.0)'` |
-| **ego-browser 里 `require` + 顶层 await 冲突** | `Cannot determine intended module format` | 别在 heredoc 里写文件，用 `> out.txt 2>&1` 重定向 |
-| **shell 工作目录会跨调用保留** | 上一条 `cd` 影响下一条 | 一律用绝对路径 |
-| **文件名带 `/`** | 批量落盘时路径炸掉 | `tr '/' '~'` 做扁平文件名 |
-| **Fal 价格标注 tentative** | 价格会变 | 文档里注明「接入前重新读一次 `llms.txt`」 |
-
----
-
-## 六、推荐执行顺序
-
-1. **抓三份 `llms.txt` 索引** → 按模型名前缀过滤，列出**完整**页面清单（这一步决定会不会漏能力）
-2. **Fal 端点探测** → 补上索引里没有的组合路径
-3. **批量 curl 落盘**（`.md` / `llms.txt`），完成后检查有没有 HTML 外壳
-4. **官方站**：SPA 找内容 API，SSR 直接 curl
-5. **价格页**：ego-browser，注意标签页与分页
-6. **用两个脚本提取** schema 与正文，逐字段成表
-7. **三项交叉校验**，不一致的地方写清来源与取舍
-8. 涉及异步/流式协议时，完成第四节的事件矩阵、官方 fixture 与测试场景清单
-9. 每份文档结尾写「原始链接索引」，标注**是否需要登录**
-
----
-
-相关：[README.md](README.md)（模型清单与结构约定）、[docs/rules/model-adaptation.md](../../../../docs/rules/model-adaptation.md)（代码侧适配规范）
+# 文档采集手册
+
+> 这份手册只记**做过一遍才知道**的东西。目标：下次做模型调研时，不再重新踩一遍坑。
+> 最后更新：2026-08-31（明确 SDK 仓内开发、公共发布与外部消费边界）
+
+---
+
+## 一、怎么发现文档：先拿全量索引，别靠单页链接往下点
+
+**最大的坑：一个模型往往对应多份文档、多个端点，只看用户给的那一个链接必然漏。**
+上一版适配 Midjourney 只做了 2 个端点，实际有 18 个；Grok Imagine 2.0 漏掉了整块图层选区编辑。
+
+### 三个平台都有 `llms.txt` 全量索引，第一步就抓它
+
+```bash
+curl -sL https://docs.apimart.ai/llms.txt -o apimart-index.txt   # 171 行，含全部页面
+curl -sL https://docs.kie.ai/llms.txt     -o kie-index.txt       # 517 行
+curl -sL https://fal.ai/llms.txt          -o fal-index.txt       # 只是代表性列表，不全，见下
+```
+
+然后**按前缀过滤出目标模型的所有页面**，而不是凭印象猜：
+
+```bash
+grep -oE "https://docs\.apimart\.ai/en/api-reference/(images|videos)[^)]*\.md" apimart-index.txt | sort -u
+grep -oE "https://docs\.kie\.ai/cn/market/[^)]*\.md" kie-index.txt | sort -u
+```
+
+### 发现「同一个模型有多份文档」的信号
+
+| 信号 | 例子 |
+|---|---|
+| 同目录下多个页面 | `images/midjourney/{generation,imagine,blend,describe,upscale,...}` 18 个 |
+| `official` / `ext` 后缀 | `gpt-image-2/{generation,official}`、`grok-imagine-2.0-ext/{generation,layer-region-edit,official}` |
+| `-lite` / `-fast` / `-mini` 变体 | `gemini-3.1-flash/{generation,generation-lite}` |
+| 平级的辅助能力 | `minimax-h3/{generation,context-ir,regeneration}`、`seedance-2-0/private-avatar` |
+| KIE 把能力拆成独立 model | `kling-3.0-omni/{text-to-video,image-to-video,reference-to-video,transformation}` |
+
+**判断标准**：只要索引里同一个模型名下有第二个页面，就必须打开看，哪怕名字看起来像「辅助说明」。
+
+### Fal 的索引不全，要靠探测
+
+`fal.ai/llms.txt` 只列代表性端点。Fal 的端点是**可组合路径**（`<厂商>/<模型>/<档位>/<输入形态>`），用 HTTP 状态码探测存在性最快：
+
+```bash
+for p in bytedance/seedance-2.0/text-to-video bytedance/seedance-2.0/image-to-video \
+         bytedance/seedance-2.0/reference-to-video; do
+  code=$(curl -sL -o /dev/null -w "%{http_code}" "https://fal.ai/models/$p/llms.txt")
+  echo "$code  $p"
+done
+```
+
+常见组合维度：`{text-to-video, image-to-video, reference-to-video}`、`{pro, standard}`、`{turbo}`、`{edit}`。
+探测出来的 404 也是信息——比如 `google/gemini-omni-flash/text-to-video` 不存在，说明 Fal 上做不了纯文生视频。
+
+---
+
+## 二、怎么找文档：优先拿原始 Markdown，浏览器是最后手段
+
+### 1. 文档站：URL 后面加 `.md` 就是原文
+
+`docs.apimart.ai` 和 `docs.kie.ai` 都支持，且 `/cn/` 前缀是中文版：
+
+```bash
+curl -sL "https://docs.apimart.ai/cn/api-reference/images/midjourney/imagine.md"
+curl -sL "https://docs.kie.ai/cn/market/kling/kling-3-0.md"
+```
+
+**比浏览器渲染好在**：拿到的是完整原文（含被折叠的参数、被 Tab 隐藏的示例），不会因为 UI 折叠而丢内容。
+
+### 2. Fal：每个模型的 `llms.txt` 是权威实时 schema
+
+```bash
+curl -sL "https://fal.ai/models/<endpoint-id>/llms.txt"
+```
+
+它由平台元数据实时生成，**不会与线上端点漂移**，且**同时包含 schema 和价格**。
+
+枚举值被折叠成 `ImageSize | Enum` 时，去拿 OpenAPI 才能看到具体取值：
+
+```bash
+curl -sL "https://fal.ai/api/openapi/queue/openapi.json?endpoint_id=bytedance/seedream/v5/pro/text-to-image"
+# → image_size 的真实枚举：square_hd / square / portrait_4_3 / ... / auto_1K / auto_2K
+```
+
+### 3. 官方控制台是 SPA，curl 拿不到正文——去找它的内容接口
+
+火山方舟的文档页 `curl` 只能拿到 18 个字符。用 ego-browser 打开后列出网络请求，就能找到真正的内容 API：
+
+```js
+await js(`performance.getEntriesByType('resource').map(e => e.name)
+  .filter(n => /api|doc|content/i.test(n))`)
+```
+
+火山方舟的结果（**可直接 curl，无需登录**）：
+
+```bash
+# 单篇文档全文（Result.MDContent 是完整 Markdown，Result.UpdatedTime 是官方更新时间）
+curl -sL "https://docs.volcengine.com/api/doc/getDocDetail?LibraryID=82379&DocumentID=1541523&type=online"
+# 全库目录（用来找价格页、模型列表页的 DocumentID）
+curl -sL "https://docs.volcengine.com/api/doc/getDocList?LibraryID=82379&DataSchema=all_second_nav&type=online"
+```
+
+常用 DocumentID：`1541523` 图片生成 API、`1544106` 模型价格、`1330310` 模型列表。
+
+**通用做法**：任何 SPA 文档站，都先用这招找内容 API，找到就退回 curl，别在浏览器里跟折叠 UI 搏斗。
+
+### 4. 阿里云百炼是 SSR，直接 curl 就有全文
+
+```bash
+curl -sL "https://help.aliyun.com/document_detail/3047054.html"   # 会 302 到 slug 页
+curl -sL "https://help.aliyun.com/zh/model-studio/model-pricing"  # 价格页，3.4 MB HTML
+```
+
+用户给的控制台链接里的 `url=3047054` 就是 `document_detail` 的 ID，可以直接换算。
+
+### 5. 价格页只能用浏览器（ego-browser）
+
+APIMart 和 KIE 的定价都是前端渲染的：
+
+- **APIMart**：图像/视频/LLM/音频是**标签页**，切了才渲染。用 `js()` 找文本等于「视频」的可见元素点一下，等 4 秒再取 `document.body.innerText`
+- **KIE**：441 个模型的**搜索框** + 分页。`fillInput('input[type="text"]', 'seedance')` → 等 3.5 秒 → 取全文
+  - ⚠️ 注意底部的 `1-25 of 28`：**默认每页 25 条，会漏**。换更精确的搜索词（如 `bytedance/seedance-2,` 带逗号）把结果压到 25 条以内
+
+把 ego-browser 的输出落盘要这样写（`cliLog` 走的是进程输出）：
+
+```bash
+ego-browser nodejs > out.txt 2>&1 <<'EOF'
+const task = await useOrCreateTaskSpace(<空间id>)
+cliLog(await js(`document.body.innerText`))
+EOF
+```
+
+---
+
+## 三、怎么处理文档：两个提取脚本 + 一轮交叉校验
+
+### 1. KIE 文档是 OpenAPI YAML，用脚本提 schema
+
+KIE 每页正文是一个 ```` ```yaml ```` 代码块包着的完整 OpenAPI。手读会漏字段，**必须用脚本递归展开**（含 `enum` / `default` / `minItems` / `maxItems` / 嵌套对象）：
+
+```python
+# kie_extract.py  —— 用法：python3 kie_extract.py <文件...>
+import sys, re, yaml, json
+
+def fmt(name, sch, indent=0, req=()):
+    pad = '  ' * indent
+    typ = sch.get('type', '')
+    if 'enum' in sch:    typ += ' enum=' + json.dumps(sch['enum'], ensure_ascii=False)
+    if 'default' in sch: typ += f" default={json.dumps(sch['default'], ensure_ascii=False)}"
+    for k in ('minimum','maximum','minLength','maxLength','minItems','maxItems'):
+        if k in sch: typ += f" {k}={sch[k]}"
+    desc = re.sub(r'\s*\n\s*', ' ', (sch.get('description') or '').strip())
+    print(f"{pad}- {name} [{typ}] {'必填' if name in req else '可选'}: {desc[:1400]}")
+    if sch.get('type') == 'object' and 'properties' in sch:
+        r = tuple(sch.get('required', ()))
+        for k, v in sch['properties'].items(): fmt(k, v, indent + 1, r)
+    if sch.get('type') == 'array' and isinstance(sch.get('items'), dict):
+        it = sch['items']
+        if it.get('type') == 'object' and 'properties' in it:
+            r = tuple(it.get('required', ()))
+            for k, v in it['properties'].items(): fmt(k, v, indent + 1, r)
+
+for path in sys.argv[1:]:
+    t = open(path, encoding='utf-8').read()
+    m = re.search(r'```yaml\n(.*?)\n```', t, re.S)
+    if not m: print(f'{path}: 无 OpenAPI 块'); continue
+    d = yaml.safe_load(m.group(1))
+    print('\n=====', path.split('/')[-1])
+    for p, ops in d.get('paths', {}).items():
+        for method, op in ops.items():
+            print(f"### {method.upper()} {p} | {op.get('summary')} | {op.get('operationId')}")
+            rb = op.get('requestBody', {}).get('content', {}).get('application/json', {}).get('schema')
+            if rb:
+                req = tuple(rb.get('required', ()))
+                for k, v in (rb.get('properties') or {}).items(): fmt(k, v, 1, req)
+```
+
+**`input` 是 `oneOf` 的要单独展开**（KIE 用它表达「二选一的输入形态」，如 Kling Omni 的「单张首帧」vs「仅视频输入」）——上面脚本会跳过，需要另外 dump `schema['properties']['input']`。
+
+对比多个变体的字段差异，一行就够：
+
+```bash
+for f in seedance-2 seedance-2-fast seedance-2-mini; do
+  echo -n "$f: "; python3 kie_extract.py raw/$f.md | grep -oE "^    - [a-z_]+" | tr -d ' -' | tr '\n' ' '; echo
+done
+# 一眼看出 mini 少了 return_last_frame
+```
+
+### 2. APIMart 文档是 MDX，代码示例占 80%，先剥掉
+
+每页会把同一个请求写成 15 种语言的示例，正文被淹没：
+
+```python
+# apimart_strip.py —— 保留 bash/json，其余语言的代码块换成占位符
+import sys, re
+for path in sys.argv[1:]:
+    t = open(path, encoding='utf-8').read()
+    t = re.sub(r'```([^\n]*)\n(.*?)```',
+               lambda m: m.group(0) if m.group(1).startswith(('bash','json'))
+                         else f'\n[[{m.group(1).strip()} 示例已省略]]\n', t, flags=re.S)
+    print(re.sub(r'\n{3,}', '\n\n', t))
+```
+
+之后配合 `sed -n '/^## Body/,$p'` 直接跳到参数区。
+
+### 3. 必做的三项交叉校验
+
+| 校验 | 为什么 | 这次的实例 |
+|---|---|---|
+| **API 文档正文价格 vs 定价页价格** | 文档正文更新慢，经常是过期价 | Seedream Pro 文档写 $0.045/$0.09，定价页是 $0.02928/$0.05856 |
+| **同一模型跨供应商的取值集合** | 名字一样但取值/默认值经常不同 | Lite 分辨率官方是 2K/3K/4K，旧文档抄成了 1K/2K；`adaptive`(APIMart/KIE) vs `auto`(Fal)；`duration` 整数 vs 字符串 |
+| **schema 内部自相矛盾** | 供应商文档确实会写错 | KIE Qwen3-Pro 的 `enum` 与 `default` 不一致；KIE z-image 的 `aspect_ratio` 描述提到 `auto` 但枚举里没有 |
+
+**处理原则**：两处不一致时**两个都写进文档**并说明以哪个为准；文档自相矛盾时标注「接入前实测确认」，不要替供应商猜。
+
+---
+
+## 四、SDK 官方资料先行与首发验证（唯一详细规范）
+
+Henji-AI 是 `@henjicc/ai-sdk` 的主开发仓库与首发验证宿主。新模型、新供应商或新协议必须先在这里完成官方调研、SDK 实现和完整验证，再发布版本；消费项目只接入已经验证并发布的精确版本。禁止先在消费项目按猜测实现协议，再把结果回填 SDK。
+
+### 1. 先文档，后代码
+
+编码前必须把以下信息写入本目录对应的供应商/模型文档，并能逐项追溯到官方来源：
+
+- 模型展示名、API model ID 与适用区域/版本；
+- Base URL、端点、方法、鉴权、请求字段、枚举、限制和默认值；
+- 当前价格、计费维度、价格来源与冲突取舍；
+- 同步响应，或轮询、SSE、WebSocket 等异步/流式协议的完整事件契约；
+- 错误、终态、取消、断线、超时、资源释放与连接复用规则。
+
+缺少官方来源，或模型、端点、价格、事件契约中任一项仍无法确定时，必须把未知项和已查入口写清并暂停编码；不得用相近模型、旧版本、SDK 现状或消费项目行为替官方契约作结论。官方资料本身矛盾时同时保留冲突来源，标为“实现前待官方确认/授权实测”，不能替供应商猜。
+
+### 2. 流式与异步协议必须有事件契约矩阵
+
+只要涉及 WebSocket、SSE、流式 HTTP、上传后轮询或回调，就必须在供应商/模型文档中按官方资料建立事件级矩阵。每一个官方事件/状态单独一行，不得只写一条 happy path 示例：
+
+| 事件/状态 | 前置状态 | 字段契约（required / optional / nullable） | 空值/缺字段语义 | 下一状态 | 对外输出 | 副作用 | 终态/错误 | 连接复用 |
+|---|---|---|---|---|---|---|---|---|
+| 官方事件名或状态值 | 允许从哪些状态进入 | 逐字段写清存在性、类型与可空性 | `null`、空串、空数组、字段缺失分别是否合法以及是否忽略 | 保持/迁移到哪个状态 | partial/final/usage/finish 或无输出 | ack、上传、轮询、计时器、资源释放等 | 是否终止；官方错误码/原因 | 继续收消息、等待关闭、主动关闭或可开启下一会话 |
+
+矩阵还必须说明状态机不变量：首事件、合法重复/乱序、是否允许先终态后结果、什么才算“有效 final”、空终态如何处理、断线后能否恢复、取消与正常结束各释放哪些资源。若官方没有说明某项，明确写“官方未说明”，不要把实现假设写成官方事实。
+
+### 3. 官方示例与 fixture 一一对应
+
+官方资料中出现的每一个字面请求、响应或事件示例，都要逐项进入 `packages/ai-sdk/tests/fixtures/`，或由测试逐字内联引用同一份 fixture。fixture 必须记录：
+
+- 精确来源 URL 与抓取日期；
+- 内容是官方原样、仅做脱敏/不可联网替换，还是从字段表构造；
+- 任何替换的字段及替换原因；
+- 对应事件矩阵的行或场景。
+
+原样示例只允许做安全脱敏、ID/URL 不可联网替换和必要的稳定化，不得为了让当前 parser 通过而补字段。官方只有字段表、没有字面示例时，可以据表构造 fixture，但必须标为“依据官方字段表构造”，不能标为官方原样。合成负例必须放在独立场景或独立文件并标为 `synthetic-negative`（或同等清晰标记），不得冒充官方样本。fixture 的通用格式与现有目录约定见 [../../tests/fixtures/README.md](../../tests/fixtures/README.md)。
+
+### 4. fixture、parser 与测试必须闭环
+
+协议实现的精确测试必须从事件矩阵和 fixture 推导，至少覆盖实际适用的下列场景：
+
+- 官方 happy path 的逐事件解析与完整状态迁移；
+- 合法空值（包括合法空始帧/心跳/无输出事件）；
+- required 字段缺失或类型错误的明确拒绝；
+- 空终态、结束前无有效 final、重复事件、乱序事件；
+- 供应商错误事件、网络断开、取消、超时；
+- 正常结束、失败、取消、断线后的连接、计时器、迭代器和会话资源释放。
+
+“测试通过”还不够，门禁必须做一次**断牙验证**：临时破坏被测试的不变量（例如把合法空事件误判为错误、接受缺失必填字段、漏掉终态释放），确认对应测试确实失败，再恢复实现并确认重新通过。断牙改动不能提交；交接中记录破坏点和实际失败的测试。只匹配标题、关键词或 fixture 数量的检查不算协议门禁。
+
+### 5. SDK 首发与消费顺序
+
+发布和接入严格按以下顺序进行，任一步失败都在当前阶段修复，不跨阶段绕过：
+
+1. 在 Henji-AI 跑变更协议/模型的精确契约测试与宿主集成测试；
+2. 跑 SDK 全量测试、可移植性检查、类型/构建、打包与本地安装包验证；
+3. 从将要发布的包或远端预发布/正式包回装，在受限运行环境验证公开入口、按需 bundle 与版本内容；
+4. 发布 SDK；
+5. 消费项目精确锁定已验证版本及 lockfile integrity，不使用 workspace 提升、浮动范围或源码旁路；
+6. 消费项目再运行宿主 transport、凭据、媒体、取消、日志和资源释放的集成测试。
+
+真实付费网络只在用户明确授权时执行；没有真网不妨碍协议契约测试，但必须在交接中准确写明边界，不能把 fixture/scripted 测试表述成真实供应商成功。
+
+### 6. SDK 开发态、发布态与消费态
+
+`@henjicc/ai-sdk` 只有一个源码主仓和一个正式分发渠道。不要把 Henji-AI 仓内为了开发而存在的 workspace 解析方式，误当成其他项目的安装方式。
+
+| 状态 | 权威来源 | 允许的依赖/包形态 | 必须证明什么 |
+|---|---|---|---|
+| 开发态与首发验证 | Henji-AI 的 `packages/ai-sdk` | 仓内 workspace 源码、构建产物、由当前源码生成的本地 tarball | 源码改动、公共导出、类型、可移植性、打包内容与宿主集成正确 |
+| 待发布/正式发布 | 当前版本生成的 npm 包 | `npm pack` 产物用于发布前回装；正式包只发布到公共 npm registry | tarball 内容等于待发布版本；完整改动已通过发布门禁及消费者影响核查，按持续授权自主发布；公共 registry 可匿名读取 |
+| 外部消费 | 公共 npm 上已经发布的不可变版本 | `@henjicc/ai-sdk` 精确版本及对应 lockfile resolved/integrity | 在没有 Henji-AI workspace、源码旁路和用户 npm/GitHub 凭据时仍能安装、导入和运行所需入口 |
+
+硬性边界：
+
+1. Henji-AI 之外的仓库一律视为外部消费者，只能从 `https://registry.npmjs.org/` 安装已发布版本。禁止使用 `workspace:`、`file:`、Git URL、GitHub Packages、源码复制、软链接或手工 tarball 路径作为正式依赖。
+2. 外部消费者的 manifest 必须写精确版本，不使用 `^`、`~`、`latest` 等浮动范围；lockfile 必须解析到公共 npm tarball，并保存与正式包一致的 integrity。Henji-AI 根 manifest 虽然也声明精确版本，但仓内可能由 npm workspace 解析到本地源码，因此不能拿本仓的安装结果替代仓外验证。
+3. 消费项目需要尚未发布的能力时，先在 Henji-AI 完成官方资料、实现、契约测试、SDK 全量门禁、打包和回装；正式发布后，消费项目再升级。禁止先在消费方复制 provider/parser/transport 内核或长期 patch SDK。
+4. **用户已持续授权 Agent 自主发布 `@henjicc/ai-sdk`，无需逐次确认。** 一组完整 SDK 功能或修复完成后，应完成版本升级、变更说明和发布门禁，再自主发布到公共 npm；不能只提交源码或重建本地 dist 就声称外部消费者已获得更新。具体要求：
+   - **发布单位**：可独立验证的一组完整改动，不为每次小编辑发版本。影响 SDK 对外功能、请求契约、兼容性或可消费产物的改动进入发布流程；仅痕迹AI界面、规则、文档或测试调整不触发发布。用户明确要求暂缓某次发布时遵从该要求。
+   - **版本级别**：兼容性修复升级 patch，兼容性新增能力升级 minor；删除公共入口、改变参数含义或其他破坏性变更不得作为 patch 发布。稳定版破坏性变更升级 major，`0.x` 阶段升级 minor，并写明迁移方法。
+   - **发布前核查**：读取 [消费项目清单](../consumers.md)，核对公共导出和请求/响应契约的实际使用；破坏性变更先确认可行的迁移路径，必要时提供过渡入口。关键兼容性影响尚不明确或发布门禁失败时，先解决并报告阻塞，不以已有授权绕过验证，也不把重新询问发布许可当成修复手段。
+   - **发布验证**：完成本手册要求的 SDK 全量门禁、候选 tarball 打包回装和 Henji-AI 首发验证；确认对应发布提交的必需 CI 门禁通过。版本号、包内容与已验证源码必须一致，发布内容不得夹带其他任务未验证的改动。
+   - **发布后同步**：按第 5、8 条完成公共 registry 匿名安装验证，并只升级实际需要新能力或修复的消费者；不要求所有项目机械追随每个新版本。报告已发布版本、验证结果、消费者升级情况及尚未验证的部分。
+   - **授权边界**：本授权针对 SDK 公共 npm 发布，不自动授权真实付费生成、改换分发渠道、绕过权限或改写远端历史。遇到必须由用户完成的 2FA 或凭据操作时，仅请求该必要协助，不重复询问是否允许发布。
+5. 发布前用当前源码产生唯一候选 tarball并完成本地回装；发布后必须在仓外临时目录移除项目级 workspace 影响和用户 npm/GitHub 凭据，从公共 npm 重新安装，核对包名、版本、公开入口和实际所需 bundle。只有这一步通过，才能称为“别人可以直接安装”。
+6. npm 返回 2FA、token 或权限错误时，只修复公共 npm 的鉴权；不得改用私有 registry、GitHub Packages 或源码安装绕过。若发布结果不确定，先查询公共 registry：版本已存在就按 npm 不可变原则发布新版本，版本不存在才重试原版本。
+7. GitHub Packages 只可作为历史记录，不再发布新版本，也不得在消费项目新增 `@henjicc` scope 的 GitHub registry 映射。历史包是否删除不影响公共 npm 消费链路。
+8. 正式发布并通过仓外验证后，读取 [消费项目清单](../consumers.md)，只升级实际受影响的消费者，逐个记录精确版本、integrity、同步 commit、宿主边界与验证结果。
+
+---
+
+## 五、零散但会卡住你的坑
+
+| 坑 | 表现 | 解法 |
+|---|---|---|
+| **KIE 限流** | 连续请求后返回 HTTP **200**，但内容是 HTML 外壳 | 用 `grep -l "DOCTYPE html"` 检出，加 2 秒延迟重试。批量下载后一定要跑一次这个检查 |
+| **zsh 不做单词分割** | `for p in $PATHS` 把整个多行变量当成一个词 | 用 `while IFS= read -r p; do ... done < 路径文件` |
+| **Bash 工具禁用前台 `sleep`** | 加延迟的循环跑不了 | `perl -e 'select(undef,undef,undef,2.0)'` |
+| **ego-browser 里 `require` + 顶层 await 冲突** | `Cannot determine intended module format` | 别在 heredoc 里写文件，用 `> out.txt 2>&1` 重定向 |
+| **shell 工作目录会跨调用保留** | 上一条 `cd` 影响下一条 | 一律用绝对路径 |
+| **文件名带 `/`** | 批量落盘时路径炸掉 | `tr '/' '~'` 做扁平文件名 |
+| **Fal 价格标注 tentative** | 价格会变 | 文档里注明「接入前重新读一次 `llms.txt`」 |
+
+---
+
+## 六、推荐执行顺序
+
+1. **抓三份 `llms.txt` 索引** → 按模型名前缀过滤，列出**完整**页面清单（这一步决定会不会漏能力）
+2. **Fal 端点探测** → 补上索引里没有的组合路径
+3. **批量 curl 落盘**（`.md` / `llms.txt`），完成后检查有没有 HTML 外壳
+4. **官方站**：SPA 找内容 API，SSR 直接 curl
+5. **价格页**：ego-browser，注意标签页与分页
+6. **用两个脚本提取** schema 与正文，逐字段成表
+7. **三项交叉校验**，不一致的地方写清来源与取舍
+8. 涉及异步/流式协议时，完成第四节的事件矩阵、官方 fixture 与测试场景清单
+9. 每份文档结尾写「原始链接索引」，标注**是否需要登录**
+
+---
+
+相关：[README.md](README.md)（模型清单与结构约定）、[docs/rules/model-adaptation.md](../../../../docs/rules/model-adaptation.md)（代码侧适配规范）