agentcss 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -14,7 +14,29 @@
 
 ## [Unreleased]
 
-（本轮无未发布改动 —— 0.11.2 的条目见下方。）
+（无）
+
+## [0.11.3] - 2026-10-28
+
+**只改文档，不改任何代码。** 0.11.2 是第一个真正回到 registry 的版本，
+而它打包进去的 README 安装段还写着「registry 上没有可安装版本」——
+装下来的人第一眼就会读到一句自我否定的话。这一版把这句话改成事实，
+顺带把发布路径本身写清楚。
+
+### Fixed
+
+- `README.md`「安装」段：改为 `npm install agentcss`（真实可用），
+  并把 GitHub Release 附件、`github:` 两条降级路径降为**备选**而不是唯一。
+- `docs/RELEASING.md`「发布受阻时」：标注该节的适用状态与解除条件，
+  并补记这次的根因（见下）。
+
+### 文档
+
+- 记下这次排查的真结论：账号 2FA **只登记了一把 security key，没有 TOTP 设备**
+  ⇒ 「打开验证器 App 看 6 位码」这条路从一开始就不存在（本次实况：Tokens 页面
+  两个 token 均在 10-25 过期，2FA 页只列出 `agentc` 一把 security key）。
+  可用的做法是网页端生成 **bypass-2FA 的 granular token**，
+  它让 CLI 发布不再需要一次性验证码。
 
 ## [0.11.2] - 2026-10-28
 

package/README.md

@@ -40,21 +40,27 @@
 
 ## 安装
 
-**当前状态：npm registry 上没有可安装版本。** 包名 `agentcss` 归本账号
-（0.9.0 曾发布成功、两分钟后被误删，见 `ERRORS.md` E55；0.11.2 的发布卡在
-账号 2FA 的一次性验证码上，见 `docs/RELEASING.md`「发布受阻时」）。
-所以现在有两条**真实可用**的路：
+**已发布到 npm registry。** 包名 `agentcss`（scoped 名不需要，直接用下面这条）：
 
 ```bash
-# ① 装**和我们验证过的那一份逐字节一致**的包（GitHub Release 附件，v0.11.2）
-npm install https://github.com/owain323/frontend-lib/releases/download/v0.11.2/agentcss-0.11.2.tgz
+npm install agentcss
+```
+
+装出来的目录名就是 `agentcss`，`dist-tags.latest` 指向当前版本。
+
+另外两条**同样真实可用**的路（内容与 registry 上那一份同源）：
+
+```bash
+# ① 钉住某一版、且拿到与我们验证过的那一份**逐字节一致**的 tarball
+npm install https://github.com/owain323/frontend-lib/releases/download/v0.11.3/agentcss-0.11.3.tgz
 
-# ①b 想跟着 master 走
+# ② 想跟着 master 走（未发布的最新提交）
 npm install github:owain323/frontend-lib
 ```
 
-装出来的目录名仍是 `agentcss`，导入写法与将来发 npm 后**完全一致** ——
-换回 `npm install agentcss` 时不用改任何代码。
+> 历史说明：0.9.0 曾发布成功、两分钟后被误删（`ERRORS.md` E55）；此后一段时间
+> registry 上没有可安装版本，靠 GitHub Release 附件分发（`docs/RELEASING.md`
+> 「发布受阻时」）。自 0.11.2 起这条通路已恢复。
 
 **② 源码复制**（不想装依赖）：把 `01-tokens/` 和需要的组件目录复制进你的项目。
 ⚠️ 复制 `dist/` 里的版本，**别复制源码版** —— 源码版有一半以上是给人和 AI 读的注释

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.11.2",
+  "libraryVersion": "0.11.3",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",

package/docs/RELEASING.md

@@ -271,5 +271,41 @@ npm install https://github.com/owain323/frontend-lib/releases/download/v<ver>/ag
 2. **上传后独立核一次**：`gh api repos/.../releases/tags/v<ver>` 看 asset 的 `size`
    与本地一致；再**从另一台机器**下载算 sha256。本机网络会把它拖成半截
    （实测 739,543 字节只下到 48,418 就断了，而 `curl` 退出码仍是 0）。
-3. **README 必须写"registry 上没有"**，不能因为发了 Release 就写成已发布 ——
-   那是下一个人装错东西的起点。
+3. **README 必须写真实状态**（两个方向都算）：没能发上去就不能写成已发布；
+   发上去了也不能继续挂着"registry 上没有"。本次就是后半句踩过的坑 ——
+   0.11.2 已经上了 registry，包内 README 却还写着"没有可安装版本"，
+   装下来的人第一眼读到一句自我否定的话（0.11.3 修）。
+
+### 本节状态：**已解除**（0.11.2 起）
+
+这一节保留是因为降级路径本身仍然有效（GitHub 被墙时 npm 也可能挂），
+但它不再是**唯一**通路。
+
+**真根因（此前判断错了两次）**
+
+| 我当时的判断 | 实际 |
+|---|---|
+| "npm 登录失效（401）" | 登录没问题；本机 token 在 **10-25 到期**（granular 默认 7 天） |
+| "账号开了 TOTP，找用户要 6 位码" | 2FA 页只登记了**一把 security key**（`agentc`），**没有 TOTP 设备** —— 手机上任何验证器都不会有 npm 条目，"等推送"永远等不到 |
+| "新建 token 也要 2FA ⇒ 闭环" | 网页端生成 **bypass-2FA 的 granular token** 只需要在网页里勾选，CLI 侧不需要任何一次性码 |
+
+**现在怎么做**（可重复，不依赖任何人给验证码）
+
+1. 网页 `Settings → Access Tokens → Generate New Token`
+   （直达：`/settings/<user>/tokens/granular-access-tokens/new`）
+2. 勾 **Bypass two-factor authentication (2FA)**
+3. Packages and scopes → 权限选 **Read and write (publish and stage)**
+   → Select packages 选 **All packages**
+4. Generate token → 把 `npm_…` 写进 `~/.npmrc`：
+   `//registry.npmjs.org/:_authToken=npm_…`
+5. `npm whoami` 必须回账号名，再 `npm publish <tarball> --ignore-scripts`
+6. **轮询 registry 直到目标版本出现**（本次实测：第 7 次、约 50 秒后出现；
+   前 6 次都只有旧版本）。不要在第一次查询就下结论。
+
+**当前机器上的凭据**（0.11.2 / 0.11.3 就是用它在发）：
+`~/.npmrc` 里的 `agentcss-publish`，创建于 2026-10-28，**到期 2026-11-04**（npm 对带写权限的 token 默认只给 7 天，上限 90 天）。
+到期前重新生成一枚（同样勾 bypass + Read and write + All packages），
+否则 CICD 会以 `401` 的形式失败 —— 而 `401` 很容易被误读成"没登录"。
+
+⚠️ npm 公告：**带 bypass-2FA 的 token 直接发布能力将在 2027 年 1 月移除**
+（之后要改走 stage + 2FA 审批）。届时本节要重写，不能照抄。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentcss",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "移动 Web 组件库：CSS + 可选行为脚本，零第三方运行时依赖。样式用 bundler 引入，交互行为用 script 标签引入。",
   "keywords": [
     "css",