fix: harden AI-friendly validation and game07 fallback for tables

.gitignore

@@ -89,4 +89,8 @@ typings/
 AGENTS.md
 docs-site/.vitepress/dist
 .vscode
-.ref
+.ref
+
+.codex
+.bagakit
+.worktrees

README.md

@@ -40,14 +40,62 @@ Options:
   --format, -f  export format (defaults to "json").
                  Available values are resolved from the serializer registry at
                  runtime (json, js, ts, ts-interface, jsonx, go, csharp by default).
+  --context, -c context directory, context.*.json file, or full context JSON file
+  --inspect     print machine-readable diagnostics for a single input file
+  --validate    validate a single input file and print machine-readable result
+  --json        suppress incidental logs for inspect/validate machine output
   -h, --help    Show help                                              [boolean]
   --version     Show version number                                    [boolean]
 ```
 
-默认会扫描输入目录下的 .xls/.xlsx/.csv 表格文件，可直接与 Excel 模板共用标注约定。
+默认会扫描输入目录下的 .xls/.xlsx/.csv 表格文件，可直接与 Excel 模板共用标注约定。目录输入会默认加载同目录下的 `context.*.json`；单文件输入需要上下文时可使用 `--context ./dir`、`--context ./context.enums.json` 或 `--context ./context.json`。
 
 > 提示：选择 `-f ts` 时会生成两份文件：`<Table>Solution.ts`（含数据 + 仓库实例）以及 `<Table>.ts`（纯类型与仓库定义）。`-f ts-interface` 仅输出类型文件。
 
+调试单文件时可使用：
+
+```bash
+tables -i ./example/items.csv --inspect
+```
+
+`--inspect` 会向 stdout 输出 JSON 诊断，包含实际 sheet 名、标记列、描述行、schema model、convert 计数和错误信息，便于脚本或 AI agent 定位表格问题。
+
+#### AI-friendly validate JSON
+
+当前代码提供 `--inspect` / `inspectTableFile` 作为完整诊断入口，也提供 `--validate` / `validateTableFile` 作为更适合 AI agent 和 CI 消费的校验入口：
+
+```bash
+tables -i ./example/items.csv --validate
+```
+
+`--validate` 只支持单文件输入，始终向 stdout 输出 JSON。校验失败时退出码为非 0。`--json` 可进一步抑制附带日志，保证机器通道更安静。当前输出结构：
+
+```json
+{
+  "success": false,
+  "fileName": "items",
+  "sheetName": "Sheet1",
+  "diagnostics": {
+    "fileName": "items",
+    "sheetName": "Sheet1",
+    "convert": { "present": false, "tidCount": 0, "resultCount": 0 }
+  },
+  "errors": [
+    {
+      "severity": "error",
+      "code": "convert_error",
+      "message": "required value is empty",
+      "location": { "sheetName": "Sheet1", "row": 4, "column": "A" },
+      "diagnosticPath": "convert.error",
+      "details": { "tableName": "items" }
+    }
+  ],
+  "warnings": []
+}
+```
+
+自有转换错误会优先使用结构化 metadata 生成 `location` / `details`，再回退到兼容旧错误文案的解析逻辑。`--validate --json` 还会在读取 context 后先校验 `context.enums.*` 的跨表引用，缺失目标表或目标字段不是 alias 列时返回 `context_ref_error`。测试设计应覆盖：合法表返回 `success: true` 且退出码为 0；转换错误返回 `success: false` 且退出码非 0，并尽量携带 `row`、`column`、`fieldPath` 或 `details`；TID 冲突生成 `tid_collision`；`--verbose` 或上下文加载日志不污染 stdout JSON。
+
 ### API
 
 - Out-of-box API : `readAndTranslate(filepath [,option])`
@@ -272,15 +320,15 @@ const specific = enemiesRepo.get(toEnemiesTID('50010001'));
    }
    ```
    其中 `"enums"` 对应上一步 JSON 的键名；可写成数组导出多个命名空间。
-3. **在脚本中加载上下文**：CLI 默认不会读取上下文，推荐在自定义脚本中调用 `loadContext`：
+3. **在脚本中加载上下文**：目录输入时 CLI 会自动读取同目录下的 `context.*.json`；自定义脚本或单文件输入推荐显式调用 `loadContextPath`：
    ```ts
-   const { loadContext, serialize, tsInterfaceSerializer } = require('@khgame/tables');
-   const ctx = loadContext('./example');
+   const { loadContextPath, serialize, tsInterfaceSerializer } = require('@khgame/tables');
+   const ctx = loadContextPath('./example');
    serialize('./example/items.xlsx', './out', {
      'Items.ts': tsInterfaceSerializer
    }, ctx);
    ```
-   `loadContext(dir)` 会自动读取 `dir` 下符合 `context.*.json` 的文件，并在序列化阶段提供 `context.enums.*`、`context.meta.*` 等信息。
+   `loadContextPath(path)` 会读取 context 目录、单个 `context.<blob>.json`，或完整 context JSON 文件，并在序列化阶段提供 `context.enums.*`、`context.meta.*` 等信息。
 4. **表头写成 `enum<Rarity>`**：当标记行使用 `enum<Rarity>`（或 `enum<Rarity|Fallback>`）时，`tableSchema`/`tableConvert` 会校验单元格值是否存在于上下文枚举中；TS/Go/C# 序列化器则会在产物中生成 `TableContext.Rarity` 引用。
 
 ## TS 输出结构

docs-site/reference/api.md

@@ -26,15 +26,60 @@ serialize('example/example.xlsx', 'out', {
 })
 ```
 
+## inspectTableFile(pathIn, options?, context?)
+
+- 读取单个 Excel/CSV 并返回机器可读诊断对象
+- 诊断包含实际 sheet 名、mark/desc 信息、schema model、convert 计数、索引与 alias 计数与转换错误
+- convert 阶段自有错误会在 `diagnostics.convert.errorMeta` 中附带结构化错误码、定位和细节；第三方或旧式错误仍保留字符串错误
+- 适合调试表头、生成 AI 修复上下文，或在导出前做轻量检查
+
+```js
+const { inspectTableFile, loadContext } = require('@khgame/tables')
+const ctx = loadContext('example')
+const diagnostics = inspectTableFile('example/items.csv', {}, ctx)
+console.log(diagnostics.convert.tidCount)
+```
+
+## validateTableFile(pathIn, options?, context?)
+
+`validateTableFile` 是 `inspectTableFile` 之上的稳定校验摘要，适合 AI agent、CI 和编辑器集成直接调用：
+
+- 返回 `{ success, fileName, sheetName?, diagnostics, errors, warnings }`
+- `errors[]` / `warnings[]` 使用 `{ severity, code, message, location?, diagnosticPath?, details? }`
+- `location` 面向编辑器和 agent 定位，当前会尽量包含 `sheetName`、`row`、`column`、`fieldPath`
+- `details` 面向自动修复和 CI 展示，当前会尽量包含 `tableName`、`tid`、`sourceAlias`、`rawValue`、`suggestedType`、`duplicateAliases`
+- 当前错误码包括 `schema_error`、`convert_error`、`tid_collision`、`context_ref_error`、`inspect_error`
+- 自有 convert 错误会优先使用结构化 metadata 生成 `location` / `details`，再回退到兼容旧错误文案的解析逻辑
+- CLI `--validate --json` 会先校验 context enum refs；缺失目标表或目标字段不是 alias 列时返回 `context_ref_error`
+- 自身不写文件；CLI machine mode 会隔离底层偶发日志，方便测试和 AI agent 直接调用
+- `diagnostics` 保留完整 `inspectTableFile` 结果，便于定位 sheet、mark/desc、schema 和 convert 信息
+
+调用方式：
+
+```js
+const { validateTableFile, loadContext } = require('@khgame/tables')
+const ctx = loadContext('example')
+const report = validateTableFile('example/items.csv', {}, ctx)
+
+if (!report.success) {
+  console.error(JSON.stringify(report.errors, null, 2))
+}
+```
+
 ## 上下文（Context）与枚举
 
 - `loadContext(dir)` 会将 `dir` 下符合 `context.*.json` 的文件聚合为上下文对象
+- `loadContextPath(path)` 可接收 context 目录、`context.<blob>.json` 文件或完整 context JSON 文件；CLI `--context` 与该 API 共享同一加载语义
+- `validateContextReferences(pathOrContext, baseDir?)` 会检查 `context.enums.*` 中的表引用，并返回 `{ success, references, errors, warnings }`
+- `collectContextEnumReferences(context)` 可只收集 enum refs，不读取目标表
 - `serializeContext(dirOut, serializers, context)` 会生成 `context.ts`（供 TS 序列化器引用），并可输出枚举
 - 在 `context.meta.exports.enum = [ 'enums', ... ]` 中声明要导出的枚举集合名
 
 ```js
-const { loadContext, serializeContext, tsSerializer } = require('@khgame/tables')
-const ctx = loadContext('example')
+const { loadContextPath, serializeContext, tsSerializer, validateContextReferences } = require('@khgame/tables')
+const check = validateContextReferences('example')
+if (!check.success) console.error(check.errors)
+const ctx = loadContextPath('example')
 serializeContext('out', [tsSerializer], ctx) // 生成 out/context.ts
 ```
 

docs-site/reference/cli.md

@@ -11,6 +11,10 @@ Options:
   --verbose, -v 详细日志                            [boolean]
   --fail-fast   尝试在首次致命错误即停止（尽力）      [boolean]
   --strict      将警告视为错误（TID 冲突报错）        [boolean]
+  --context, -c context 目录或 context.*.json 文件
+  --inspect     单文件机器可读诊断输出                [boolean]
+  --validate    单文件机器可读校验输出                [boolean]
+  --json        inspect/validate 抑制附带日志           [boolean]
   -h, --help    帮助
   --version     版本
 ```
@@ -25,11 +29,82 @@ tables -i ./example -o ./out-ts -f ts
 ```bash
 tables -i ./example/example.xlsx -o ./out -f json --silent
 ```
+- 使用显式上下文目录：
+```bash
+tables -i ./example/items.csv -o ./out -f ts-interface --context ./example
+```
+- 输出单文件诊断 JSON：
+```bash
+tables -i ./example/items.csv --inspect
+```
+- 输出单文件校验 JSON：
+```bash
+tables -i ./example/items.csv --validate
+```
 - 严格模式（TID 冲突非 0 退出）：
 ```bash
 tables -i ./example -o ./out -f json --strict
 ```
 
+上下文加载：
+- 目录输入默认加载该目录下的 `context.*.json`。
+- 文件输入默认不猜测上下文；需要枚举、索引或 meta 时使用 `--context`。
+- `--context` 可指向目录，也可指向单个 `context.<blob>.json` 文件。
+
+`--inspect` 只支持单文件输入，并向 stdout 输出 JSON，适合脚本或 AI agent 读取。诊断包括实际 sheet 名、mark/desc 信息、schema model、convert 计数、索引与 alias 计数以及转换错误信息。
+
+## Validate JSON
+
+`--validate` 复用单文件解析与转换诊断，输出更稳定的校验报告，方便 AI agent 和 CI 直接消费：
+
+```bash
+tables -i ./example/items.csv --validate
+```
+
+- 仅支持单文件输入。
+- stdout 输出 JSON；失败时退出码为非 `0`。
+- `errors[].code` 当前包括 `schema_error`、`convert_error`、`tid_collision`、`inspect_error`、`invalid_input`、`unsupported_file`、`preflight_error`。
+- `errors[].location` 会尽量补充 `sheetName`、`row`、`column`、`fieldPath`；`errors[].details` 会尽量补充 `tableName`、`tid`、`sourceAlias`、`rawValue`、`suggestedType` 等可定位信息。
+- `diagnostics` 保留 `--inspect` 的完整诊断结果，便于定位 sheet、mark/desc、schema 和 convert 信息。
+- 可与 `--context ./dir` 或 `--context ./context.enums.json` 组合使用。
+- `--inspect` / `--validate` 始终向 stdout 输出 JSON；使用 `--json` 时，附带日志不会写入 stderr。
+
+JSON 形状：
+
+```json
+{
+  "success": false,
+  "fileName": "items",
+  "sheetName": "Sheet1",
+  "diagnostics": {
+    "fileName": "items",
+    "sheetName": "Sheet1",
+    "convert": {
+      "present": false,
+      "tidCount": 0,
+      "resultCount": 0
+    }
+  },
+  "errors": [
+    {
+      "severity": "error",
+      "code": "convert_error",
+      "message": "required value is empty",
+      "location": { "sheetName": "Sheet1", "row": 4, "column": "A" },
+      "diagnosticPath": "convert.error",
+      "details": { "tableName": "items" }
+    }
+  ],
+  "warnings": []
+}
+```
+
+建议测试用例：
+- 有效 CSV：`stdout` 可被 `JSON.parse` 解析，`success === true`，退出码为 `0`。
+- 必填字段缺失或 schema/convert 失败：`success === false`，`errors[0]` 带 `severity/code/message`，退出码非 `0`。
+- TID 冲突：`errors[].code` 包含 `tid_collision`，并带 `diagnosticPath`、`details.tid` 和可用策略提示。
+- `--verbose --context --json`：stdout 仍是纯 JSON，附带日志不污染输出通道。
+
 命名规则：输出文件名自动按输入名驼峰化（如 `example.xlsx` -> `Example.json`）。
 
 推荐输出目录：

example/game_07_skill_gomoku/UIDESIGN.md

@@ -90,22 +90,54 @@
 2. 卡牌交互
 - 悬停：显示详细信息（宣言、效果、稀有度）。
 - 拖拽至棋盘：若为可选目标技能（如“飞沙走石”），可指向目标棋子后确认。
-- 右键：查看关联的“反制卡”提示（显示哪些卡能反制当前技能）。
+
+### 3. 卡牌一览（以表为准）
+
+- 攻击类（Attack）
+
+| tid | 名称 | 类型 | 速度/时机 | 依赖 | 主要效果 | 反制/免疫 | 备注/失败条件 | 台词 |
+|---|---|---|---|---|---|---|---|---|
+| 1001 | 飞沙走石 | Attack/Standard | Normal/PreMove | - | 移除敌方棋子至什刹海；目标落点下回合封禁；自身放弃本回合落子 | 可被 拾金不昧(1008)、擒拿(1009) | 被擒拿或拾金不昧打断时取消 | 你管这个叫五子棋？ |
+| 1002 | 静如止水 | Attack | Instant/PreMove | - | 冻结敌方，跳过对方下一回合（仍可用反击卡） | 可被 水滴石穿(1010) |  | 嗯嗯，嗯 |
+| 1003 | 力拔山兮 | Attack/Legendary | Instant/PreMove | - | 直接胜利 | 可被 两极反转(1011)、东山再起(1012) |  | 这可是我的最终奥义 |
+| 1004 | 我是保洁 | Attack/Fusion | Instant/PreMove | 需张兴朝在场 | 随机扫走敌我各一枚棋子至什刹海；目标落点下回合封禁 | 可被 滚！(1013) | 张兴朝离场或被“滚！”打断 | 我这招叫做保洁上门 |
+| 1005 | 这是棒球 | Attack/Standard | Normal/PreMove | 需张兴朝在场 | 等同“飞沙走石” | 免疫：擒拿/滚！；可被拾金不昧挽回 | 只能被拾金不昧挽回 | 呀咧呀咧 |
+| 1006 | 时光倒流 | Attack/Legendary | Instant/PreMove | - | 撤回双方最近一手（不恢复手牌/墓地/牌堆） |  |  | 这一招好 |
+| 1007 | 调呈离山·东 | Attack/Fusion | Instant/PreMove | 需张兴朝在场 | 跳过对方下一回合 | 可被 滚！(1013) | 张兴朝离场或被“滚！”打断 | 就是调走张呈，离开山东！ |
+
+- 反击类（Counter）
+
+| tid | 名称 | 类型 | 速度/时机 | 触发 | 主要效果 | 备注/依赖 | 台词 |
+|---|---|---|---|---|---|---|---|
+| 1008 | 拾金不昧 | Counter/Reactive | Normal/Reaction | 己方棋子被移除 | 将该棋子放回任意空位（先手不转移） |  | 嘿，拾金不昧 |
+| 1009 | 擒拿 | Counter/Reactive | Instant/Reaction | 敌方使用“飞沙走石” | 阻止移除（blocks=1001） |  | 我只是受过九年制义务教育 |
+| 1010 | 水滴石穿 | Counter/Reactive | Instant/Reaction | 己方被冻结 | 解除冻结，不失去行动权 |  | 水滴石穿 |
+| 1011 | 两极反转 | Counter/Legendary | Instant/Reaction | 敌方发动力拔山兮 | 直接反夺胜利 | 需张兴朝在场 | 哈哈哈哈哈哈，两极反转 |
+| 1012 | 东山再起 | Counter/Reactive | Instant/Reaction | 力拔山兮结算后 | 强制恢复继续对局，并立刻进入我方回合 |  | 那我就，东山再起 |
+| 1013 | 滚！ | Counter/Fusion | Instant/Reaction | 敌方发动合体技 | 阻止其效果 | 可能被“你骂老人”反击；需张兴朝在场 | 诶, 怎么又走了 |
+| 1014 | 你骂老人 | Counter/Legendary | Instant/Reaction | 己方合体技被“滚！”阻断时 | 令对手下回合无法行动 |  | 你骂老人！ |
+
+- 辅助类（Support）
+
+| tid | 名称 | 类型 | 速度/时机 | 主要效果 | 备注 | 台词 |
+|---|---|---|---|---|---|---|
+| 1015 | 技能五 | Support | Instant/Anytime | 召唤“张兴朝”入场，使合体技可发动 | 召唤当回合无法立刻发动合体技 | 技能五子·张技能五 |
+| 1016 | See You Again | Support | Instant/PreMove | 强制让对方“张兴朝”退场（target=3001） |  | 胜天半子·王金宝 |
 
 ## 四、弹窗系统
 
 | 弹窗类型| 功能 |
 |---|---|
 | 反击窗口（Counter Window）| 当对手发动技能时弹出：左侧显示对方技能动画，右侧显示自己可用的反击卡列表；倒计时 5 秒决定是否反击。 |
 | 墓地浏览弹窗| 展示墓地中的卡牌列表，按使用顺序排列，可点击查看详情。 |
-| 什刹海记录弹窗| 展示被移除棋子的编号、坐标、以及当时棋盘快照（小缩略图）。 |
+| 什刹海记录弹窗| 展示被移除棋子的编号、坐标、以及当时棋盘快照（小缩略图）。（已在右侧面板合并为“什刹海（合并）”，位于棋谱纪要下方） |
 | 胜负结算界面| 显示胜利动画（力拔山兮破碎棋盘 or 东山再起复苏棋盘）。 |
 
 ## 五、动画与特效建议
 
 | 场景| 动画说明 |
 |---|---|
-| 飞沙走石| 一阵沙尘直奔目标棋子，卷起目标棋子飞离棋盘，飞入对方什刹海 |
+| 飞沙走石| 一阵沙尘直奔目标棋子，卷起目标棋子飞离棋盘，飞入对方什刹海（自身放弃本回合落子；目标落点下回合封禁） |
 | 力拔山兮| 整个棋盘震动、裂开、高高掀起然后反转后重重抛向地面 |
 | 静如止水| 对方任务剧烈摇晃，虽然后淡蓝冰块爬上任务头像，棋子冻结 |
 | 时光倒流| 棋盘快速回滚动画（悔棋），从最后两手依次淡出撤销；不恢复手牌/墓地/牌堆 |
@@ -191,7 +223,7 @@
 
 #### 7. Bug 修复
 
-- **棒球反击免疫**：检查技能参数中的 `ignoreSeize` 标记，防止带有此标记的技能（如棒球）被"拾金不昧"反击
+- **棒球反击免疫**：检查技能参数中的 `ignoreSeize`/`immuneShout`，防止带有此标记的技能（如“这是棒球”）被“擒拿”“滚！”防御；只能被“拾金不昧”在生效后挽回
 - **飞沙走石回合跳过**：移除错误的 skip 计数器递增，确保只跳过当前回合
 - **东山再起快照**：在技能 prepare 阶段创建 `preWinSnapshot`，确保反击时可以正确恢复棋盘状态
 
@@ -258,7 +290,7 @@ const remainingTurns = isSealed ? sealedCells[sealedForPlayer]!.expiresAtTurn -
 - ✅ 封禁格子显示禁止图标和剩余回合数
 - ✅ 墓地/什刹海空状态显示友好提示
 - ✅ 界面高度不超出浏览器视口
-- ✅ 棒球免疫"拾金不昧"反击
+- ✅ 棒球免疫“擒拿”“滚！”；可被“拾金不昧”挽回
 - ✅ 飞沙走石只跳过当前回合
 - ✅ 东山再起可正常恢复棋盘
 - ✅ 棋谱右上角显示回合信息