docs(project): 同步维护冻结与运行文档

补齐解析模块维护冻结规则，并同步 CURRENT_STATUS、CURRENT_GAPS、PROJECT_PLAN、RPC 参考、部署指南、用户指南和官方资源运行说明。文档同时反映 bat-api 资源 bootstrap/分发边界、官方同步解析缓存、TextUnit 队列、双目录发布和 patch 入口的当前状态。验证：未运行新命令；本轮已按要求停止重复构建/测试。
2026-09-18 08:14:55 +08:00 · 2026-07-31 00:45:46 +08:00
parent 3f78f8f880
commit 03021ad649
16 changed files with 946 additions and 225 deletions
@@ -117,6 +117,10 @@ git push origin feature/your-feature-name

 禁止使用 demo、临时实现、硬编码路径或只为当前测试通过的伪实现。确实未完成的能力应写入当前缺口文档，而不是用 `TODO` 或 `FIXME` 隐藏。

+### 解析模块冻结
+
+UnityFS / AssetBundle / Addressables / TypeTree 解析当前处于维护冻结。冻结期不得新增解析类型、扩大解析覆盖、开放新的写入型解析 RPC/CLI，或用合成 fixture 宣称新增能力。允许变更仅限编译、测试、clippy、真实运行回归、诊断和文档一致性修复。细则见 `docs/reports/PARSER_FREEZE.md`。
+
 ### Go
 - 遵循 [Effective Go](https://golang.org/doc/effective_go)
 - 使用 `gofmt` 格式化
@@ -149,17 +153,31 @@ go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
 Go 边界与进度以 `docs/reports/GO_STATUS.md` 为准：

 - **同步/运维命令行** = Rust `bat`（近乎全自动）
- **资源分发服务** = `cmd/bat-api`（`make build-go-api`）
+- **资源 bootstrap/分发服务** = `cmd/bat-api`（`make build-go-api`）
 - **默认 Go 门禁** = `make test-go-api`（无 FFI）
 - 试验 CLI 产物为 `bin/bat-go`（`make build-go-cli`），**禁止**与 Rust `bat` 重名
 - 修改 FFI 时再跑 `make test-go-ffi`

+开发环境不能本地全量运行 Rust `bat` 时，`bat-api` 不需要真实生产资源目录。用 fixture 或 mock RPC 验证服务面；生产联调再连接远程服务器上同环境运行的 `bat.sock`：
+
+```bash
+make test-go-api
+BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
+  --listen 127.0.0.1:18080 \
+  --public-base-url http://127.0.0.1:18080 \
+  --resource-root internal/api/testdata/release \
+  --refresh-interval 0
+```
+
+生产默认路径仍是 `--socket` / `BAT_API_SOCKET`，资源根由 Rust `bat` RPC 返回；`--resource-root` 只用于上述 fixture 或应急只读诊断。
+
 ### 常用聚焦命令

 ```bash
 cargo test -p bat-core -- --nocapture
 cargo test -p bat-adapters -- --nocapture
 cargo test -p bat-ffi -- --nocapture
+cargo test -p bat-patch -- --nocapture
 cargo test -p bat-infrastructure -- --nocapture
 cargo test -p bat-infrastructure --bin bat -- --nocapture
 cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets -- -D warnings
@@ -195,6 +213,112 @@ cargo run -p bat-infrastructure --bin bat -- \

 开发环境真实官方资源下载默认写入 `./bat-resources`；汉化产物默认写入独立的 `./bat-localized`。如果要覆盖，官方原版资源使用 `--output` / `BAT_OUTPUT`，汉化产物使用 `--localized-output` / `BAT_LOCALIZED_OUTPUT`。两者都必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录，也不要把汉化输出覆盖到官方原版资源目录。

+官方 release 拉取并校验完成后会在当前 release 根目录维护
+`official-resource-changes.json`、`crowdin-translation-handoff.json`、
+`official-parse-cache.json` 和 `official-textunit-index.json`，随后从
+Added/Modified 资源、parse cache 与 TextUnit 明细索引派生
+`official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`。本地已有旧完整
+版本时，新版本发布后会先按 manifest destination 对比旧/新 release，只把新增和
+内容变更的资源写入解析与 Crowdin handoff；删除资源只记录差异，不进入翻译队列。
+up-to-date 轮询发现本地文件、解析缓存、TextUnit 明细索引和 TextUnit 队列未变时不会重复解析。
+Crowdin 队列当前只落本地文件，不发网络请求。
+
+需要把已校验官方 release 导入 CAS + `ResourceRepository` 时，显式启用：
+
+```bash
+cargo run -p bat-infrastructure --bin bat -- \
+  --auto-discover \
+  --import-repository \
+  --import-cas-root /tmp/bat-test.cas \
+  --import-resource-db /tmp/bat-test-resources.sqlite
+```
+
+对应 `.env` / 环境变量键为 `BAT_IMPORT_REPOSITORY`、
+`BAT_IMPORT_CAS_ROOT` 和 `BAT_IMPORT_RESOURCE_DB`。只读查询命令：
+
+```bash
+cargo run -p bat-infrastructure --bin bat -- parse-status
+cargo run -p bat-infrastructure --bin bat -- parse-text-units --limit 50
+cargo run -p bat-infrastructure --bin bat -- parse-errors --limit 50
+cargo run -p bat-infrastructure --bin bat -- localized-status
+cargo run -p bat-infrastructure --bin bat -- resource-index --limit 50
+```
+
+`parse-status` 会额外显示 TextUnit 明细索引和队列摘要；`parse-text-units` /
+`parse-errors` 可按 destination、archive entry、path id、class id、field path
+和 format 分页查询当前官方 release 的 TextUnit 明细与解析错误；
+`resource-index` 返回的资源 JSON 包含 release、平台、bundle path、TextAsset 和 TextUnit metadata；
+`localized-status` 只有在 `localized-version-state.json`、`current` symlink 和
+`localized-patch-manifest.json` 都匹配当前官方 release 时才返回 `localized`。
+
+文件级写入命令只处理显式输入/输出文件，不切换官方或汉化 release：
+
+```bash
+cargo run -p bat-infrastructure --bin bat -- patch-apply \
+  --patch-kind text \
+  --source-file /tmp/bat-source.txt \
+  --patch-file /tmp/bat-source.text-patch.json \
+  --target-file /tmp/bat-target.txt
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-text-asset \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --replacement-file /tmp/replacement.bytes \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-string-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --string-field-path message \
+  --replacement-text "老师" \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --field-path scores[1] \
+  --expected-json '{"kind":"signed","value":20}' \
+  --replacement-json '{"kind":"signed","value":42}' \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --field-path difficulty \
+  --expected-json '{"kind":"enum","value":{"type_name":"ScenarioDifficulty","storage_type":"int","value":2}}' \
+  --replacement-json '{"kind":"enum","value":{"type_name":"ScenarioDifficulty","storage_type":"int","value":3}}' \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --field-path target_layers \
+  --expected-json '{"kind":"bit_field","value":{"type_name":"LayerMask","storage_type":"UInt32","bits":5}}' \
+  --replacement-json '{"kind":"bit_field","value":{"type_name":"LayerMask","storage_type":"UInt32","bits":9}}' \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --field-path messages \
+  --replacement-json '{"kind":"array","value":[{"kind":"string","value":"你好"},{"kind":"string","value":"老师"}]}' \
+  --target-file /tmp/target.bundle
+
+cargo run -p bat-infrastructure --bin bat -- unityfs-patch-field \
+  --bundle-file /tmp/source.bundle \
+  --serialized-file CAB-Example \
+  --object-path-id 1 \
+  --field-path texts \
+  --replacement-json '{"kind":"map","value":[{"kind":"object","value":[{"name":"first","value":{"kind":"string","value":"jp"}},{"name":"second","value":{"kind":"string","value":"你好"}}]}]}' \
+  --target-file /tmp/target.bundle
+```
+
 生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。

 ### 基准测试