# AGENTS.md — Tk Toolkit（ComfyUI-Anima-Batch-LoRA）

> **接手第一步**：读 `docs/HANDOFF-2026-09-13-cards-autocomplete.md`（**当前版本 v2.12.0**：
> ②区联想的中文角色名支持 —— 数据来源、匹配分级、Anima 括号转义、性能、踩过的坑）。
> 上一版状态读 `docs/HANDOFF-2026-09-13-2.11.0.md`（版本谱系「为什么是 2.11 而不是 2.9」）。
> 需要改动细节时再往下读 `docs/HANDOFF-2026-09-13.md`（画廊/outputs）与
> `docs/HANDOFF-2026-09-13-engineering.md`（CI 连红 5 次排查 + Registry 全过程）。
> 审计结论见 `docs/工程化审计-2026-09-13.md`。

## 0. 当前状态（2026-09-13 · v2.12.1）

| 项 | 值 |
|---|---|
| **版本** | **2.12.1**（`VERSION` 唯一真源；`__init__.py` 运行时读它） |
| 远端 main | `ffc5130e`（本地 == 远端） |
| **CI** | 只读验证 CI，**连续多次全绿**（`.github/workflows/ci.yml`） |
| GitHub Release | `v2.10.0`、`v2.11.0`、`v2.12.0`、`v2.12.1` |
| **ComfyUI Registry** | ✅ **`anima-toolkit` @ `toki`**：2.11.0 / 2.12.0 / **2.12.1** 均已上传待审 |
| 离线测试 | **129 passed** |
| `__init__.py` | 2657 → **2448 行**（更新链已拆到 `services/github_update.py`） |
| ⚠️ **运行目录** | py/js/data 已同步到 2.12.1，但 **ComfyUI 未重启**（需用**绘世启动器**重启） |

### 本轮（2.12.0 → 2.12.1）= ②区联想的中文角色名支持 + 更新链漏发修复

**中文角色名**（2.12.0）。核心结论：**坏的是数据覆盖与排序，不是匹配逻辑**。

- 中文角色名走 **`anima_alias_index.json`（插件根目录，8.9MB，随包发布）**，由
  `tools/build_tag_alias_index.py` 从三个**可验证**来源合成：AnimaDex 角色表
  （`tools/harvest_animadex.py`，36488 角色 / 3702 作品）、Civitai LoRA 元数据挖出的
  中文名↔danbooru 标签配对（`tools/harvest_civitai_zh_aliases.py`，2638 条带证据）、
  社区词典 + 原 CSV「关键词」字段。**没有任何 LLM 编造的中文名。**
- harvest 原始数据在 `data/_sources/`（48MB，**已 gitignore**，运行时不读）。刷新词典顺序：
  `harvest_animadex.py` → `harvest_civitai_zh_aliases.py` → `build_tag_alias_index.py` → 跑测试 → 提交。
  只换词典不改代码时按 mtime 指纹热重载，**不必重启 ComfyUI**。
- 中文查询**不再扫描 20 万条英文说明**（插件加载时后台线程预热）；英文查询 350ms → 60ms。
- **索引必须在插件根目录**，理由见下方坑 7。

**更新链漏发**（2.12.1）：见坑 7 —— 这是"老用户能不能真的用上"的关键。

**运行中的 ComfyUI 仍是旧加载状态**（本轮改了 py，必须重启才会生效）。

## 1. ⭐ 改完代码先跑这一条

```bash
cd "E:\claude program\ComfyUI-Anima-Batch-LoRA"
python tests/run_tests.py          # = CI 会跑的那一套（6 个环节）
```

涵盖：Python 编译 / 离线 pytest / **离线 pytest（模拟 CI 干净环境）** / `ai_verify` /
JS 测试 / panel `tsc`。**发布前必跑**，`0` = 全过。

单项用：

```bash
python -m pytest tests -q          # ⚠️ 必须传 tests 目录（配置在 tests/pytest.ini）
python tests/tools/ai_verify.py    # 节点注册 / README 图片与链接 / 版本一致性 / Registry 元数据
python tests/run_tests.py --integration   # 需要真实浏览器 + ComfyUI(:8188)，仅本机
```

**测试分层**（`tests/README.md` 是权威说明，`tests/layer-manifest.json` 是权威清单）：

| 层 | 位置 | CI |
|---|---|---|
| unit（25） | `tests/*.py` | ✅ |
| js（3） | `tests/js/` + 顶层 `*.mjs`/`*.js` | ✅ |
| integration（57） | `tests/integration/` | ❌ 要真实浏览器 + ComfyUI |
| smoke（4） / repro（12） | `tests/smoke_*.py` / `tests/repro/` | ❌ |
| tools（5） / fixture（1） | `tests/tools/` / `clothing_draw_ui_harness.html` | 单独调用 |

改了 `tests/` 结构后**必须**跑 `python tests/tools/classify_tests.py` 重新生成清单，
否则 `test_layer_manifest.py` 会 FAIL。

## 2. 三目录与发布链

| 目录 | 角色 | 推 GitHub |
|---|---|---|
| `E:\claude program\civitai` | 面板开发目录（`src/`） | ❌ 与远端 main **无共同祖先**；`.git/hooks/pre-push` 会**硬拦**（`TK_ALLOW_CIVITAI_PUSH=1` 可强行放行，后果自担） |
| `E:\claude program\ComfyUI-Anima-Batch-LoRA` | **合并发布仓库**（插件 + `panel/` + `web/js`） | ✅ **唯一发布出口** |
| `E:\1AI\ComfyUI-aki-v3\ComfyUI\custom_nodes\ComfyUI-Anima-Batch-LoRA` | 实际运行目录（非 git） | ❌ 手动同步 |

发布链：`civitai/src` → `npm run build:comfyui` → 运行目录 `app/`；同时同步到本仓库 `panel/src` → 推送 → Actions 重建 `app/`。

**改完 py 必须手动同步到运行目录并重启 ComfyUI**；纯前端（`web/js`、`web/css`）刷新浏览器即可。

## 3. 推送协议（硬约束，违反会静默丢文件）

**只用守卫脚本推送**，永不 `git push`、永不 force：

```bash
python .scratch/api_push_guard.py --dry-run    # 先看计划
python .scratch/api_push_guard.py              # 推送（遇删除默认中止）
python .scratch/api_push_guard.py --allow-delete   # 确认要删才加
```

规则（详见 `.scratch/PUSH_PROTOCOL.md`）：
- 基线取**远端 head 的 tree**（纯 API，不用本地 refs —— 本地谱系可能陈旧）
- 默认**只做加法**；「远端有、本地没有」一律中止（并发环境下几乎都是误伤）
- 推送前二次复查 head，`force:false`
- `app/` 由 CI 重建，守卫默认排除
- 推完用 `git fetch origin main && git reset --soft FETCH_HEAD` 对齐（**`origin/main` 跟踪引用解析异常，必须用 `FETCH_HEAD`**）
- **提交前 `git add` 之后要排除**：`test_gallery.py`（游离脚本，内含硬编码绝对路径）、
  `data/batches/bworker.json`（运行时状态，改一次就脏）

## 4. ⚠️ 接手必读的十个坑（都踩过，已固化防御）

1. **`pytest.ini` 必须在 `tests/` 里，不能放仓库根。**
   仓库根**就是** ComfyUI 插件的 `__init__.py`，pytest 会向上找包边界并把它当包导入 →
   全部用例 setup ERROR。**实测无效、别再试**：`import-mode=importlib`（pytest 9 的 ini 没这选项）、
   `pythonpath = .`、`collect_ignore`、`tests/__init__.py`、`--import-mode=append`、`--rootdir` 覆盖。
   `tests/conftest.py` 负责 stub ComfyUI 运行时（`folder_paths` / `server`）。

2. **测试里 stub 模块必须"看着像包"**：`m.__path__ = []`，子模块挂到父模块属性上，
   否则 `from PIL import Image` 会在 import 机制里炸。**且只在真的缺失时 stub** ——
   用空模块覆盖真 `aiohttp` 不还原会污染同 session 后续测试
   （`conftest.py` 已有守卫，会直接点名是哪个测试干的）。

3. **comfy-cli 在中文 Windows 上 GBK 崩溃**：`'gbk' codec can't decode byte 0xae`。
   必须 `python -X utf8`。**且崩溃发生在"上传之后"** → 会以为失败其实已发布成功
   （重试报 `The node version already exists` 即证）。

4. **`comfy node publish` 报 `Failed to validate token` 有两个完全不同的原因**：
   ① PAT 是在"未登录账号"下生成的（registry 里查不到 user）；
   ② `PublisherId` 含大写（registry 只接受全小写）。
   别急换 PAT，先 `python tools/registry_setup.py --token <PAT> --check` 区分。

5. **测试可能把假数据写进真实工作树。** 曾发生 `test_update_archive.py` 覆盖了仓库根的
   `__init__.py`（变成 `"new init"`）、`VERSION`（`9.9.9`）、`app/index.html`。
   根因：测试重定向了 `PLUGIN_DIR`，但写盘的是**另一个模块**的同名全局（拆分后委托关系变了），
   于是 `shutil.copy2` 打到了真实文件上。**任何会写文件的测试都必须**：
   ① 断言"重定向真的生效"；② 跑前后对真实文件做快照比对。
   （该测试现已具备这两道防线；`conftest.py` 另有 `sys.modules` 污染守卫。）

6. **`web/` 是会被 ComfyUI 服务出去的目录** —— 任何 `.js` 备份都不能放里面，
   否则浏览器把它当第二个扩展加载、`registerExtension` 跑两次（UI 重复注册，表现为按钮成对出现）。
   备份放插件根目录（`.gitignore` 已忽略 `.workbuddy-bak-*/`、`_bak_*/`）。

7. **`AUTOCOMPLETE_LOCK` 必须是 `RLock`，不能是 `Lock`。**
   `_build_autocomplete_alias_tables()` 持锁期间会再调 `_load_autocomplete_entries()`，
   而后者也要拿同一把锁 → **同线程自死锁**。症状极具误导性：
   **不报错、不退出，只是永远卡住**（预热线程和首次查询一起挂），
   探针看起来像"导入很慢"。凡是"持锁期间调用另一个也加锁的函数"，
   一律用可重入锁或把内层调用挪到锁外。

8. **别在报告失败的分支里 print emoji。** Windows 控制台是 GBK，
   `print("❌ ...")` 会 `UnicodeEncodeError`，**把真正的报错盖掉**（`ai_verify.py`
   和 `tests/tools/run_offline_like_ci.py` 都踩过，都只在"失败时"才炸）。
   脚本输出一律用 `[X]` / `[OK]` / `[!]`。

9. **新增文件前先问一句：内置更新链下不发得下去？** 更新链的发布白名单只看
   `is_release_path()`（`services/github_update.py`）：`anima_*` 前缀 / `services/` / `web/` / `app/`
   + 几个根文件；**`data/` 只逐文件放行 `_SHIPPED_DATA_FILES` 里的随包词典**。
   踩过两次：
   - 随包词典放进 `data/` → 老用户点「更新」拿到新代码却拿不到词典，功能**静默失效**
     （不报错、只是查不到）；而且 `check_update` 的 package_match 也看不见它，连"有更新"都判不出来；
   - `__init__.py` 拆分后没放行 `services/` → 老用户点更新会 ImportError、**插件整个加载不了**。
   所以：**随包数据一律放根目录并起 `anima_` 前缀**（新词典就是这么放的）；
   `services/` 已整目录放行，往里加模块不用管。
   护栏：`tests/test_update_archive.py::test_release_path_whitelist_covers_everything_the_plugin_needs_at_runtime`。
   发版前可跑一次"老用户模拟"：取旧发布 commit 的 `services/github_update.py`，
   用它的 `is_release_path` 过滤当前远端 tree，看关键文件是否在列。

10. **别在 PowerShell 里用"数组套数组"做多文件字符串替换。** 实测踩过一次真事故：
    用 `@{file = @(@("old","new"))}` 的哈希表遍历时，**单元素数组会被 PowerShell 展平成字符串**，
    于是 `$pair[0]` 变成了**单个字符**（而不是整条字符串），`String.Replace(char, char)` 把
    **所有**该字符替换掉 —— `#` 全变成空格，`AGENTS.md` 的标题、`anima_gallery.py`/`anima_thumbs.py`
    的注释全毁，**Python 直接语法错误**；`CLAUDE.md` 是 gitignore 的，**git 都救不回来**。
    规矩：① 改文件一律用 `edit` 工具（精确整串匹配，逐个改）；
    ② 非要用脚本，也必须是"每条 `(old,new)` 显式配对"，并**先 `Copy-Item` 备份**；
    ③ 批量改完立刻 `python -m py_compile` + `git diff --stat` 核对，别等到跑测试才发现。

## 5. 版本号纪律（`VERSION` 是唯一真源）

改版本**只跑这一条**，它会一处改五处同步：

```bash
python tools/bump_version.py 2.12.0     # VERSION / __init__ / README / pyproject / CHANGELOG 骨架
```

五处必须一致，任一漂移 `ai_verify` 即 FAIL：`VERSION` / `__init__.py::__version__`（运行时读 VERSION）/
`README.md`「当前发布版本」/ `CHANGELOG.md` 最新条目 / `pyproject.toml` `[project].version`。

**版本号三个口径不要混**（易错点）：

| 口径 | 当前值 | 说明 |
|---|---|---|
| 仓库版本 | **2.11.0** | `VERSION` 唯一真源 |
| GitHub tag/Release | `v2.10.0`、`v2.11.0` | **2.9 及更早从未打 tag**（v2.10.0 是 2026-09-13 补建） |
| Registry 版本 | 2.11.0 | `Pending` 待审核 |

版本谱系：2.4.0 → 2.5.x → 2.6.0 → 2.7.x → 2.8.x → **2.9.0**（`357bf1e`）→
**2.10.0**（`6d9ec25`，破坏性：相机控制退役）→ **2.11.0**（`2e071ba`）。
> 注意：2.10.0 那次升级了 `VERSION` 却漏改 README，造成过真实漂移 —— 所以现在有强制校验。

## 6. 发布到 ComfyUI Registry

```bash
python -X utf8 tools/registry_setup.py --token <PAT>          # 体检 + 发布
python -X utf8 tools/registry_setup.py --token <PAT> --check   # 只体检
```

- node id **`anima-toolkit`**、publisher **`toki`**（**均创建后不可改**）
- `PublisherId` 必须**全小写**（`ai_verify` + `test_ci_config` 已强制）
- `requirements.txt` 只放**必需**依赖；`playwright` / `llama-cpp-python` 在 `requirements-optional.txt`；
  **不要**声明 `torch` / `numpy` / `PIL`（ComfyUI 自带，重复声明会版本冲突）
- Registry 与 Manager 收录以此为准，**无需**单独提交 Manager

## 7. UI 规范

按钮/面板图标一律用 `src/utils/icon.ts` 的 `icon('name', size, cls)` 内联 SVG
（24×24、`stroke=currentColor`），**禁 emoji**；缺图标从 lucide 官方 path 补进 `PATHS`
（保持 24×24），不引入新依赖。此规范适用于面板 `panel/src/`。

## 8. 结构速查

```
__init__.py            插件入口：节点注册 + 全部 /anima/* 路由（薄适配层）
services/github_update.py   GitHub 自动更新链（2026-09-13 拆出）
anima_*.py             各节点后端（gallery / prompt_batch / batch_lora / …）
web/js/*.js            节点侧前端 widget（**无 TS 注解**，见下）
web/css/*.css          节点侧样式
panel/src/             Vite + TS 面板源码
anima_alias_index.json 中文别名/角色/作品索引（**必须在根目录** —— 只有 anima_* 前缀才会被更新链下发）
data/                  随包发布的词典（danbooru CSV / 中文词典）+ 用户状态（**更新链只逐文件放行词典**）
data/_sources/         harvest 原始数据（**已 gitignore**，构建输入，运行时不读）
tests/                 分层测试（见 tests/README.md）
tools/                 bump_version.py / registry_setup.py
tools/harvest_animadex.py            抓 AnimaDex 全量角色表
tools/harvest_civitai_zh_aliases.py  抓 Civitai LoRA 中文名证据
tools/build_tag_alias_index.py       合成 anima_alias_index.json
docs/                  交接与审计文档
pyproject.toml         ComfyUI Registry 元数据
requirements*.txt      运行 / 可选 / CI 依赖
```

**铁律：`web/js/*_widget.js` 里禁止任何 TS 类型注解。** Node 24+ 会剥离 TS 所以
`node --check` 会骗你通过，但浏览器 V8 直接抛整个文件的 SyntaxError → 节点 UI 静默不挂载。
改完 widget 必须在真实浏览器里确认节点能挂载。

## 9. 遗留（不影响使用）

- `__init__.py` 只拆了第一阶段；剩余最大的是**翻译路由（约 800 行）**，但与 `_detect_proxy` /
  DeepLX 管理器耦合，需先理清再动。
- integration 层（57 个脚本）**CI 永不跑**（要真实浏览器 + ComfyUI），仅 `--integration` 本机跑。
- `verify_danbooru_gallery_batch.py` 有确定性失败未修。
- `screenshots/tk-danbooru-gallery.png` 仍是旧 UI（布局已换，建议重截）。
- `CONTRIBUTING.md` 缺。
- 运行目录 `tests/` 只有 7 个文件，**跑不了完整回归**（请用发布仓库）。
- 待拍板：`git rm --cached data/batches/bworker.json`（会影响已有部署，**需用户确认**）。
- **中文别名词典仍有噪声**：CSV 的「关键词」字段是机器直译，会产出「万岁伸展」「味园米卡」
  这类错译，以及 `聖園`（日文汉字形）这类片段。它们排在可信来源之后，**不会抢走正确结果**，
  但会出现在下拉副标题里。要再提升就得引入人工校对表或萌娘百科/Bangumi 的日文名 join
  （工程量大，需先解决日文名→罗马字匹配）。
- **`anima_alias_index.json` 有 8.9MB**（已随包发布）。若嫌大，可改存 gzip
  （`json.load(gzip.open(...))`）压到 ~2MB，但要同步改运行时的 `_load_alias_index()`。