@acosmi/sdk-ts 2.14.0 → 2.15.0

package/dist/node/{openai-BRreM1fK.d.cts → openai-B6mz3cyj.d.cts}

@@ -1,4 +1,4 @@
-import { P as ProviderAdapter, p as ProviderFormat, n as ModelCapabilities, e as ChatRequest, f as ChatResponse, w as StreamEvent } from './index-BoxWrEq0.cjs';
+import { P as ProviderAdapter, p as ProviderFormat, n as ModelCapabilities, e as ChatRequest, f as ChatResponse, y as StreamEvent } from './index-yOZUFtNQ.cjs';
 
 /**
  * Anthropic 内容块

package/dist/node/{openai-Dpz9QgEJ.d.ts → openai-DuQHy2AA.d.ts}

@@ -1,4 +1,4 @@
-import { P as ProviderAdapter, p as ProviderFormat, n as ModelCapabilities, e as ChatRequest, f as ChatResponse, w as StreamEvent } from './index-BoxWrEq0.js';
+import { P as ProviderAdapter, p as ProviderFormat, n as ModelCapabilities, e as ChatRequest, f as ChatResponse, y as StreamEvent } from './index-yOZUFtNQ.js';
 
 /**
  * Anthropic 内容块

package/docs//345/274/200/345/217/221/344/270/216/345/217/221/345/270/203/346/211/213/345/206/214.md

@@ -582,45 +582,92 @@ git tag vX.Y.Z
 git push origin vX.Y.Z
 ```
 
-### 9.2.1 打 tag 的两个坑（2026-08-02 v2.14.0 实测踩过）
-
-发版流程的真实拓扑与本节 Step 1 的描述有出入：**SDK 源码真源在 monorepo 的
-`acosmi-sdk-ts/` 子目录**，由 `mirror-subtrees.yml` subtree-split 后 force-push 到
-公开仓 `acosmi/sdk-ts`；`release.yml` 只存在于公开仓，tag 也只在公开仓上打。所以
-「改代码」发生在 monorepo、「打 tag」发生在公开仓，中间隔着一次镜像同步。
-
-**坑 1：被 tag 的 commit 的 message 不能带 `[skip ci]`。**
-GitHub 对 `push` 事件一律尊重 `[skip ci]`，**tag push 也算 push**。subtree split 会
-**原样保留原始 commit message**，所以 monorepo 里那个带 `[skip ci]` 的发版 commit
-镜像过去之后，tag 指向它 → `release.yml` 静默不触发（tag 建得好好的、workflow 是
-active、Actions 权限正常，就是没有 run，排查时极具迷惑性）。
-→ **发版那一个 commit 必须不带 `[skip ci]`**。确认方法：
-```bash
-gh api repos/acosmi/sdk-ts/commits/<被tag的sha> --jq '.commit.message' | head -1
-```
+### 9.2.1 发版真实拓扑与触发方式（2026-08-02 v2.14.0 实测修订）
+
+**拓扑**（本节 Step 1 假设的「独立仓」已不是现状）：SDK 源码真源在 monorepo 的
+`acosmi-sdk-ts/` 子目录，由 `mirror-subtrees.yml`（**只在 `acosmi/cloud-agent` 跑**，
+另两个 remote 上恒 skipped）subtree-split 后 force-push 到公开仓 `acosmi/sdk-ts`；
+`release.yml` 与 tag 都只在公开仓。所以「改代码」在 monorepo、「发版」在公开仓，
+中间隔着一次镜像同步。
+
+**发版入口：用 `workflow_dispatch`，不要依赖 tag push。**
 
-**坑 2：tag 必须用真的 `git push` 推，不能用 REST API 建 ref。**
-`gh api repos/acosmi/sdk-ts/git/refs -X POST -f ref=refs/tags/vX.Y.Z ...` 只产生
-`create` 事件、**不产生 `push` 事件**，而 `release.yml` 监听的是 `on: push: tags`。
-本地没有公开仓 clone 时，临时建一个最省事：
 ```bash
-git init tmp && cd tmp
-git remote add origin https://github.com/acosmi/sdk-ts.git
-git fetch --depth=1 origin <mirror-main-sha>
-git tag vX.Y.Z <mirror-main-sha>
-git push origin refs/tags/vX.Y.Z      # 必须是 git push
+# 1) 确认镜像已同步到要发的内容
+gh api repos/acosmi/sdk-ts/contents/package.json --jq .content | base64 -d | grep -m1 version
+SHA=$(gh api repos/acosmi/sdk-ts/commits/main --jq .sha)
+
+# 2) 在公开仓打 tag（仍要打——Release 页面与 npm provenance 都指向它）
+git clone https://github.com/acosmi/sdk-ts.git tmp && cd tmp
+git tag vX.Y.Z "$SHA" && git push origin vX.Y.Z
+
+# 3) 触发发布
+gh workflow run release.yml --repo acosmi/sdk-ts --ref vX.Y.Z
+gh run watch <run-id> --repo acosmi/sdk-ts
 ```
 
-**打 tag 前的落地检查**（别拿 tag 试错——`npm publish` 之前还有 typecheck / lint /
-test / build / docs 五道，红了要删 tag 重来）：
+> **为什么用 `workflow_dispatch` 而不是 tag push**：v2.14.0 发版时，**连续 5 次**
+> 创建 tag（REST 建 ref ×1、浅仓 `git push` ×3、完整 clone `git push` ×1）**都没有
+> 产生任何 workflow run**。当时结论写的是「成因未定位」—— 那是错的，2026-08-02
+> 已用对照实验查清。
+>
+> **根因：GitHub 扫描 commit message 全文，不只是标题行。** 被 tag 的 commit 只要
+> **任何一行**出现 skip 指令字面量（`[skip ci]` / `[ci skip]` / `[no ci]` /
+> `[skip actions]` / `[actions skip]`），该次 push 就被静默跳过 —— tag push 也是
+> push 事件。跳过时不报错、不留 run、Actions 页面上什么都没有。而 subtree split
+> **原样保留 monorepo 的 commit message**，monorepo 又为省 CI 额度常带该指令，
+> 标记就这么被一路带进公开仓，落在待发版的那个 commit 上。
+>
+> 5 次尝试全部命中：整个尝试窗口内公开仓 main 的 HEAD 依次是 `ee2a3a8a` →
+> `b72efe62` → `73603e52` → `fd7cfd48`，**四个 commit 的 message 里都含该字面量**。
+> 前两个是标题行里的真指令（从 monorepo 带过来的）；后两个标题行是干净的，
+> 但**正文里为了记录这个现象而引用了该字面量** —— 原话是「被 tag 的 commit
+> message 不含 …」「本 commit 不带 …」。**否认它的那句话本身包含了它。**
+> 这也正是当初判定「已排除 skip 指令」的由来：人只看标题行，GitHub 匹配全文。
+>
+> **对照实验**（2026-08-02 13:50Z；同一分钟、同一 `git push`、同一 workflow，
+> 唯一变量是被 tag 的 commit）：
+>
+> | 探针 tag | 指向 commit | 字面量位置 | 结果 |
+> |---|---|---|---|
+> | `v0.0.0-probe-control` | `9f17a8a8` | 无 | **2 秒内产生 run**，一路绿到 `Publish to npm` 才因版本已存在而失败 |
+> | `v0.0.0-probe-skipci` | `73603e52` | 仅正文 | **零 run** |
+>
+> 两个 tag 均已确认推到远端；实验后都已删除。
+>
+> **硬规则：commit message 里永远不要出现那个方括号字面量，哪怕是在讨论、引用或
+> 否认它。** 需要提及时写成不带方括号的 `skip-ci 指令`。**文件正文不受影响** ——
+> GitHub 只扫 commit message，所以本文档里写全字面量是安全的。
+>
+> **仍以 `workflow_dispatch` 为推荐入口**，理由不是 tag push 坏了（它没坏，上面
+> 的对照组证明此刻完全正常），而是 dispatch **不是 push 事件、对这一整类失败
+> 结构性免疫**；而 monorepo 常规使用 skip 指令，靠人每次记得检查 message 全文
+> 不可靠。tag 仍然要打（Release 页面与 npm provenance 都锚定它），只是不靠它触发。
+
+**一条被证伪的旁证，别再当信号用**：当时观察到「仓库事件流里连 `CreateEvent` 都
+没有」，被当成「tag 根本没注册上」的旁证。那是 events API 的假象 —— 发版成功的
+`v2.14.0` 那次 tag 创建同样查不到 `CreateEvent`（而 tag 删除的 `DeleteEvent` 条条
+都在）。**tag 的 `CreateEvent` 在这个仓从来不出现，不能用它判断 tag push 是否生效。**
+
+**一条至今未验证的说法**：「REST 建 ref（`gh api .../git/refs -X POST`）只产生
+`create` 事件、不产生 `push` 事件，故对 `on: push: tags` 无效」。本次唯一用 REST 的
+那次尝试已被 skip 指令完整解释，**没有为这个说法留下任何证据**；此前手册断言它成立
+是误写。要么实测，要么直接用 `git push` 绕开这个问题。
+
+**打 tag / dispatch 前的落地检查**（`npm publish` 之前还有 typecheck / lint / test /
+build / docs 五道，本地先跑绿，别拿发版流水线试错）：
+
 ```bash
-gh api repos/acosmi/sdk-ts/contents/package.json --jq .content | base64 -d | grep -m1 version   # = 待发版本
-gh api repos/acosmi/sdk-ts/commits/main --jq '.commit.message' | head -1                        # 不含 [skip ci]
-npm run typecheck && npm run lint && npm run build && npm run test:pack && npm run docs          # 本地先全绿
+npm run typecheck && npm run lint && npm run build && npm run test:pack && npm run docs
 ```
-> lint 尤其容易漏：v2.14.0 第一版用了 `InputModality | (string & {})` 这个「保留自动
-> 补全」的类型技巧，撞本仓 `@typescript-eslint/ban-types`，带着它推 tag 会在 publish
-> 前一步失败。
+> lint 最容易漏：v2.14.0 第一版用了 `InputModality | (string & {})` 这个「保留自动
+> 补全」的类型技巧，撞本仓 `@typescript-eslint/ban-types`（禁 `{}`），会在 publish
+> 前一步失败。已改朴素 `string` —— 补全的价值在**书写**字面量，而那个类型描述的是
+> 从目录**读到**的数据，技巧本就不必要。
+>
+> 本机（Windows）`npm test` 有一条恒红：`test/store/file-token-store.test.ts` 的跨
+> 进程 flock（`fs.open(..,'wx')` EPERM）。CI 的 ubuntu 上不复现 —— 该用例早于
+> v2.13.0，而 v2.13.0/v2.14.0 的 Release run 里 `Test` 步骤都是绿的。
 
 ### 9.3 公开仓清洁度检查（push 前必看）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acosmi/sdk-ts",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "description": "Acosmi TypeScript SDK：模型网关、Agent Run Gateway 与 Compliance（电子证据、时间章、报告、签署 envelope）统一客户端，支持浏览器 / Node ≥18 / Deno / Bun。",
   "type": "module",
   "main": "./dist/node/index.cjs",