@follenfang/wowdata 0.0.1 → 0.0.2

package/LICENSE

@@ -1,10 +1,10 @@
-GNU AFFERO GENERAL PUBLIC LICENSE
-Version 3, 19 November 2007
-
-Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
-Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
-
-wowdata is licensed under the GNU Affero General Public License version 3 or any later version.
-
-Full license text:
-https://www.gnu.org/licenses/agpl-3.0.txt
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.
+
+wowdata is licensed under the GNU Affero General Public License version 3 or any later version.
+
+Full license text:
+https://www.gnu.org/licenses/agpl-3.0.txt

package/README.md

@@ -62,6 +62,27 @@ CLI 会在同一次命令中：
 
 准备和下载进度写入 stderr，最终结构化结果写入 stdout JSON。多个独立 CDN 对象和清单默认使用 4 个 worker 并发下载；可以通过 `wowdata cache config --workers N` 调整。
 
+## 输出和退出码
+
+CLI 可以直接用于 Agent，也可以作为普通 Shell 命令组合：
+
+- 成功结果为 `"ok": true`，进程退出码为 `0`。
+- 业务错误为 `"ok": false`，错误详情仍是 stdout 中的 JSON，进程退出码为 `1`。
+- 准备和下载进度只写入 stderr，不会污染 stdout JSON。
+- 参数拼写错误等尚未进入命令处理器的错误写入 stderr，并返回退出码 `1`。
+
+因此脚本既可以判断退出码，也可以继续解析结构化错误：
+
+```bash
+if wowdata db2 rows SpellName --id 133 \
+  --source remote --region cn --product wow --build latest --locale zhCN \
+  >result.json; then
+  jq '.data.rows' result.json
+else
+  jq '.error' result.json
+fi
+```
+
 ## 发现与提前准备
 
 查看某个区域当前提供的真实产品和 Build 组合：
@@ -170,6 +191,10 @@ git push origin v1.2.3
 
 工作流会测试 Go 和 npm、构建五个平台、生成 `SHA256SUMS`、创建 GitHub Release，并发布同版本 `@follenfang/wowdata`。
 
+npm 发布使用绑定到 `Follen/wowdata` 和 `release.yml` 的 Trusted Publisher OIDC，不需要在 GitHub Secrets 中保存 `NPM_TOKEN`。发布 job 固定使用 npm `11.18.0`，并生成 npm provenance。
+
+npm 版本不可覆盖：`0.0.1` 已经发布，后续正式发布从更高的新版本 tag 开始，例如 `v0.0.2`。
+
 ## License
 
 AGPL-3.0-or-later

package/dist/SHA256SUMS

@@ -0,0 +1,5 @@
+c518635ebf3dcdf92b39510ec9fb3f25df27e7eb0132b177553bdeae15089452  dist/wowdata-darwin-amd64
+10470811b3fb51abed29d28ff5548f272ce3939556a16321b94ae85d1736f8be  dist/wowdata-darwin-arm64
+009d40358915132df84dcdf7e9275f4fef9161a390ccc8b1beaa43763564e8ea  dist/wowdata-linux-amd64
+46528408a4ba3ba6b05e0469f7356ae1945386337e0e2305f037a26e2c96e66a  dist/wowdata-linux-arm64
+397884735b784690b01188399cf140ea05bf98494478ada7b7c57c2b31ca0d9d  dist/wowdata-windows-amd64.exe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@follenfang/wowdata",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Auditable CLI for querying World of Warcraft CASC and DB2 data",
   "license": "AGPL-3.0-or-later",
   "type": "commonjs",

package/skill/wowdata/SKILL.md

@@ -1,39 +1,55 @@
 ---
 name: wowdata
-description: Use the wowdata CLI for World of Warcraft CASC, DB2, file, icon, spell, encounter, item, creature, decor, video, Build, cache, and diagnostic tasks.
+description: Query and export World of Warcraft game data with the wowdata CLI, including CASC and DB2 schemas and rows, files, icons, textures, spells, encounters, items, creatures, decor, Builds, profiles, cache, and diagnostics. Use when a user asks to inspect or export WoW data from a local client or CDN, resolve a product/Build/locale target, or diagnose wowdata.
 ---
 
 # wowdata
 
-CLI only. Run `wowdata` from PATH. Do not look for a bundled executable and do not use any server transport.
+Use the `wowdata` executable from `PATH`. This Skill is CLI-only: do not search for a bundled executable and do not use MCP or another server transport.
 
-## Target Contract
+## Resolve The Target
 
-Every data command must receive a complete target or an explicit `--profile`.
+Resolve the target before running a command that reads CASC or DB2 data.
 
-1. Preserve source, path, region, product, Build, and locale when the user states them.
-2. For an unspecified remote region, Build, or locale, explicitly pass `--source remote --region cn --build latest --locale zhCN`.
-3. Product has no default. Resolve it from the user's words or the current conversation only when there is one unambiguous product. Otherwise ask the user which product they mean before running the CLI.
-4. Never rely on CLI defaults. The CLI intentionally has none.
+1. If the user gives a Profile, pass only `--profile <name>`. Do not combine a Profile with target flags.
+2. Resolve the product from the user's words or established conversation context. Read [clients.yaml](references/clients.yaml) for English and Chinese aliases. Product has no default; if it is still missing or ambiguous, ask one short product question and do not run a data command yet. Treat “硬核服” as a server rule, not a product: resolve its classic-era or anniversary product from context, or ask which one.
+3. Preserve every explicit source, path, region, product, Build, and locale value.
+4. When no source or local path is stated, use remote CDN data.
+5. For an otherwise unspecified remote target, pass `--source remote --region cn --build latest --locale zhCN` plus the resolved product.
+6. For `--source local`, require the client `--path` and complete every remaining target field explicitly. Do not replace missing local-client facts with guesses.
 
-Read [clients.yaml](references/clients.yaml) for stable product aliases and [locales.yaml](references/locales.yaml) for language aliases. Do not store a current Build number in this Skill.
+Never rely on CLI target defaults; the CLI intentionally has none. `--build latest` resolves at execution time, so never store a current Build number in this Skill. Read [locales.yaml](references/locales.yaml) when mapping natural-language locale names.
 
-## Atomic Use
+Commands that do not read a game target do not need the full target: `video demux`, `doctor`, `cache`, `profile`, `update`, and `uninstall`. `casc products` uses only source discovery flags such as `--source remote --region cn` or `--source local --path <client>`.
 
-Call the business command directly. The CLI checks Build identity and cache integrity, downloads missing data, reports preparation on stderr, then returns the final JSON on stdout. Do not run `warmup` before ordinary queries.
+## Run Atomic Commands
 
-Use `casc products` only when the user asks which combinations exist. Use `warmup` only when the user explicitly asks to download data ahead of time. Use `doctor` when a command reports an environment, cache, target, or network problem.
+Call the business command directly. Do not run `warmup` before an ordinary query. The CLI checks Build identity and cache integrity, downloads missing data, then completes the original query in the same process.
+
+- Use `casc products` when the user asks which products or Builds exist.
+- Use `warmup` only when the user explicitly asks to download data ahead of time.
+- Use `doctor` after an environment, target, cache, or network failure needs diagnosis.
+- Read [commands.md](references/commands.md) before composing an unfamiliar command.
+- Read [tables.yaml](references/tables.yaml) when translating a semantic request into DB2 tables.
+- Never invent a DB2 field name from a natural-language label. If the user requests selected fields without giving exact schema names, run `db2 schema <table>` first, then use names returned by that schema.
+- Use `db2 rows`, never the obsolete `query rows` spelling.
+- Keep exports at the user-requested path, or in the current workspace when no path is given.
+- Do not run `cache clear`, `profile remove`, `update`, or `uninstall` unless the user explicitly requests that action.
 
 ```powershell
-wowdata db2 rows SpellName --id 123 --source remote --region cn --product wow --build latest --locale zhCN
-wowdata spell info --spell-id 123 --source remote --region cn --product wow_classic --build latest --locale zhCN
+wowdata db2 rows SpellName --id 133 --source remote --region cn --product wow --build latest --locale zhCN
+wowdata item textures --item-id 19019 --profile retail-cn
 wowdata icon export --file-data-id 134400 --format png --output output/icon.png --source remote --region cn --product wow --build latest --locale zhCN
-wowdata casc products --source remote --region cn
-wowdata doctor
 ```
 
-Read [commands.md](references/commands.md) before composing unfamiliar commands and [tables.yaml](references/tables.yaml) when mapping a semantic task to DB2 tables. Keep exported files in the user's requested directory or the current workspace.
+## Read Results
+
+Treat the streams and exit status as one contract:
 
-## Output
+- stderr contains preparation and download progress. If it reports `prepare` or `download`, let the command continue; do not start a separate warmup.
+- stdout contains the final JSON. `db2 stream` defaults to JSONL; parse it line by line or pass `--format json` when one JSON document is preferable.
+- Exit code `0` corresponds to `"ok": true`.
+- Exit code `1` with JSON stdout corresponds to `"ok": false`; report `error.code` and `error.message`. A CLI parsing error may instead be plain stderr.
+- An `"ok": true` response with zero rows is a valid empty result. Recheck the ID, product, Build, and locale before trying another query.
 
-Preparation and download progress is stderr. The final structured result is stdout JSON. Preserve product, resolved Build, region, locale, table, fileDataID, output path, and diagnostics in the answer so the result stays traceable.
+Return the requested result, not download narration. Preserve the product, resolved Build, region, locale, table or ID, and output path/hash when present so the answer remains traceable.

package/skill/wowdata/VERSION

@@ -1 +1 @@
-0.0.1
+0.0.2

package/skill/wowdata/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: wowdata
-  short_description: Query and export World of Warcraft data through the wowdata CLI.
-  default_prompt: Use wowdata atomic CLI commands with a complete explicit target. Default remote region/build/locale to cn/latest/zhCN in the Skill, and ask when product is unclear.
+  display_name: "wowdata"
+  short_description: "Query and export World of Warcraft data with the wowdata CLI"
+  default_prompt: "Use $wowdata to query or export WoW data with an explicit product and a complete target."

package/skill/wowdata/references/clients.yaml

@@ -2,12 +2,28 @@ schema: wowdata.clients.v1
 clients:
   retail: wow
   ptr: wowt
+  正式服测试服: wowt
+  "正式服 PTR": wowt
   ptr2: wowxptr
   beta: wow_beta
   classic: wow_classic
+  怀旧服: wow_classic
   classic-ptr: wow_classic_ptr
+  "怀旧服 PTR": wow_classic_ptr
+  怀旧服测试服: wow_classic_ptr
   classic-beta: wow_classic_beta
   classic-era: wow_classic_era
+  怀中怀: wow_classic_era
+  "60级": wow_classic_era
+  香草服: wow_classic_era
   classic-era-ptr: wow_classic_era_ptr
   classic-anniversary: wow_anniversary
   classic-titan: wow_classic_titan
+  泰坦服: wow_classic_titan
+  泰坦重铸: wow_classic_titan
+  时光服: wow_classic_titan
+contextualAliases:
+  硬核服:
+    type: realm-rule
+    products: [wow_classic_era, wow_anniversary]
+    instruction: Do not treat as a product. Resolve the underlying classic-era or anniversary product from context; ask which one when unclear.

package/skill/wowdata/references/commands.md

@@ -1,24 +1,85 @@
 # Command Reference
 
-Run `wowdata <command> --help` when a flag is uncertain. Every data command needs either `--profile <name>` or a complete target.
+Run `wowdata <command> --help` when a flag is uncertain.
 
-| Intent | Atomic command |
+For commands that read CASC or DB2, append either:
+
+```text
+--profile <name>
+```
+
+or a complete target:
+
+```text
+--source remote --region <region> --product <product> --build <latest|version|build-id|config-key> --locale <locale>
+```
+
+Use `--source local --path <client>` plus explicit region, product, Build, and locale for a local client.
+
+## Discovery And Preparation
+
+| Intent | Command |
+| --- | --- |
+| List remote product/Build/locale combinations | `casc products --source remote --region <region>` |
+| List local client combinations | `casc products --source local --path <client>` |
+| Inspect resolved CASC and Build state | `casc info <target>` |
+| Diagnose CDN, root, encoding, archive, cache, and TACT state | `casc diagnose <target>` |
+| Download ahead of time | `warmup <target>` |
+
+Ordinary queries prepare their own dependencies. Do not call `warmup` as a prerequisite.
+
+## DB2 And Domain Queries
+
+| Intent | Command |
 | --- | --- |
-| Discover products and Builds | `casc products` |
-| Prepare data ahead of time | `warmup` |
-| DB2 schema, rows, text search, relations, stream | `db2 schema/rows/search/foreign-key/stream` |
-| Spell details, auras, summons | `spell info/auras/summons` |
-| Encounter tree | `encounter get` |
-| File lookup, search, type, fetch, existence, encoding, export | `file lookup/search/extension/get/exists/encoding/export` |
-| Export BLP icon | `icon export` |
-| Build and CASC state | `casc info/products/diagnose` |
-| Item data and assets | `item get/models/geosets/textures` |
-| Creature display and model | `creature display/model` |
-| Decor data | `decor list/get` |
-| Video container | `video demux` |
-| Named complete targets | `profile list/show/set/remove` |
-| Cache lifecycle | `cache status/verify/prune/clear/config` |
-| Installation diagnosis | `doctor` |
-| Package maintenance | `update`, `uninstall` |
-
-Do not use the obsolete `query rows` spelling. The command is `db2 rows`.
+| Inspect table fields and row count | `db2 schema <table> <target>` |
+| Read rows by ID | `db2 rows <table> --id <id[,id...]> [--fields <field,...>] <target>` |
+| Read multiple IDs | `db2 rows <table> --ids <id,...> <target>` |
+| Filter rows | `db2 rows <table> --filter <field=value> [--limit N] <target>` |
+| Search localized or text fields | `db2 search <table> --field <field> --query <text> [--limit N] <target>` |
+| Follow a numeric relation | `db2 foreign-key <table> --field <field> --value <id> <target>` |
+| Stream a large table | `db2 stream <table> [--fields <field,...>] [--filter <field=value>] [--limit N] [--format jsonl|json] <target>` |
+| Inspect spell relationships | `spell info --spell-id <id> [--max-depth N] <target>` |
+| Detect spell aura behavior | `spell auras --spell-id <id> <target>` |
+| Detect summoned NPCs | `spell summons --spell-id <id> [--npc-id <id>] <target>` |
+| Read an encounter section tree | `encounter get --journal-encounter-id <id> <target>` |
+| Read item metadata | `item get --item-id <id> <target>` |
+| Read item model and texture IDs | `item models --item-id <id> [--race-id N] [--gender 0|1] <target>` |
+| Read item geosets | `item geosets --item-id <id> <target>` |
+| Read item textures | `item textures --item-id <id> <target>` |
+| Read a creature display | `creature display (--display-id <id>|--file-data-id <id>) <target>` |
+| Find displays for a creature model | `creature model --file-data-id <id> <target>` |
+| List decor | `decor list [--limit N] <target>` |
+| Read decor | `decor get (--id <id>|--model-file-data-id <id>) <target>` |
+
+Never translate a semantic label such as "name", "description", or "model" directly into a guessed DB2 field. When exact field names are not supplied, run `db2 schema` first and use the returned names. Then use `--fields` to keep large row responses focused.
+
+## Files And Media
+
+| Intent | Command |
+| --- | --- |
+| Resolve a fileDataID | `file lookup --file-data-id <id> <target>` |
+| Search names in the listfile | `file search --query <text> [--limit N] <target>` |
+| List by extension | `file extension --extension <ext> [--limit N] <target>` |
+| Read file size and hash | `file get (--file-data-id <id>|--filename <name>) <target>` |
+| Read or write a raw file | `file get (--file-data-id <id>|--filename <name>) --output <path> <target>` |
+| Test existence | `file exists (--file-data-id <id>|--filename <name>) <target>` |
+| Inspect content/encoding keys | `file encoding --file-data-id <id> <target>` |
+| Export a raw file | `file export (--file-data-id <id>|--filename <name>) --output <path> <target>` |
+| Decode a BLP texture | `icon export --file-data-id <id> --format png|webp --output <path> [--mipmap N] [--mask N] <target>` |
+| Inspect a local VP9 AVI container | `video demux --input <file> [--output <directory>]` |
+
+`file get` without `--output` returns metadata, not raw bytes in JSON. Use `file export` or `file get --output` when the user needs an artifact.
+
+## Profiles, Cache, And Maintenance
+
+| Intent | Command |
+| --- | --- |
+| Manage complete targets | `profile list`, `profile show <name>`, `profile set <name> <target>`, `profile remove <name>` |
+| Inspect or verify cache | `cache status`, `cache verify` |
+| Manage cache | `cache prune`, `cache clear`, `cache config [--max-gb N] [--workers N]` |
+| Diagnose installation | `doctor` |
+| Update package | `update [--version latest|x.y.z]` |
+| Uninstall | `uninstall [--keep-data]` |
+
+Profile flags and explicit target flags are mutually exclusive. Treat cache clearing, Profile removal, update, and uninstall as explicit user actions.