docs: document Translation Memory and config contracts

USERGUIDE.md

@@ -73,6 +73,7 @@ HTTPS_PROXY=http://user:pass@127.0.0.1:7890 bat --auto-discover --daemon
 | `clean-stable` | 清理 `.part`/`.tmp`/失效锁、PID、socket（daemon 运行中会拒绝执行） |
 
 `status`/`stop`/`logs`/`reload` 和默认形态的 `refresh` 优先走 `bat.sock` JSON-RPC；socket 不可用时 `status`/`stop` 回退到 PID/状态文件兼容路径。
+需要替换 daemon 启动参数时使用 `restart`，或给 `reload` 显式传入同步、输出、worker/TM 等启动参数；未显式传参的 `restart` 复用上次保存的启动命令。
 
 Rust `bat` 工作流的完整命令、工作台字段、重打包 spec、调度计划和
 `bat-api` 调度接口见 [`docs/guides/bat-workflows.md`](docs/guides/bat-workflows.md)。
@@ -149,6 +150,8 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
 | `GET /admin/parse/errors?...` | 分页查询当前 release 解析错误；需要管理 token |
 | `GET /admin/translation/tasks?limit=100&worker_status=failed` | 读取/过滤 Rust 翻译任务和 provider worker 状态；需要管理 token |
 | `GET /admin/translation/handoff` | 读取当前 release 的完整翻译交接视图；需要管理 token |
+| `GET /admin/translation/memory/summary` | 读取 Rust TM schema、记录总数及 candidate/trusted 等状态计数；需要管理 token |
+| `GET /admin/translation/memory/query?source_text=...&source_context=...&limit=100` | 按 raw source/context 查询 Rust TM 记录、复用判定和 provenance；需要管理 token |
 | `GET /admin/translation/status` | 读取当前汉化 release、current 指针和 workflow 状态；需要管理 token |
 | `POST /admin/control/{action}` | 经白名单转发 Rust `bat` 控制请求；见下文 |
 
@@ -183,6 +186,7 @@ launcher 兼容端点只服务启动前资源发现。它们复用 Rust `bat` sn
 | `translation-task-update` | `translation.task.update` | `{ "task_id": "...", "status": "completed", "provider": "manual", "provider_run_id": "...", "translation_results": [{ "unit_id": "...", "source_text": "...", "translated_text": "..." }] }` | `202` + 当前任务记录 |
 | `translation-worker-run` | `translation.worker.run` | `{ "provider": "mock", "concurrency": 8, "max_tasks": 2 }` | `202` + worker task |
 | `translation-proofread` | `translation.proofread` | 无 | `202` + 汉化状态 |
+| `translation-memory-confirm` | `translation.memory.confirm` | `{ "record_id": "...", "reviewer": "...", "reason": "..." }` | `202` + 已确认的 TM 记录 |
 | `localized-publish` | `localized.publish` | `{ "translation_file": "...", "localized_release_id": "..." }` 或 `{ "from_worker": true, "localized_release_id": "..." }` | `202` + localized release manifest |
 | `localized-rollback` | `localized.rollback` | 可选 `{ "localized_release_id": "..." }` | `202` + rollback report |
 
@@ -272,16 +276,40 @@ curl -i -H 'Range: bytes=0-1023' \
 - 强制刷新：每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 各一次。
 - 状态类文件默认 `0600` 权限，读写不跟随 symlink。
 
-### 配置文件（`.env`，无参启动）
+### 配置文件（config.toml，无参启动）
 
-`bat` 首次启动时会在**二进制所在目录**释放一个 `.env` 配置模板（`0600` 权限，已存在则不动）。之后每次启动自动加载该文件，把其中的键作为进程环境变量（不覆盖已存在的环境变量），因此编辑 `.env` 后直接运行 `bat`（无参数）即可按配置启动。
+`bat` 首次启动时会在**二进制所在目录**释放一个 `config.toml.example` 配置模板（`0600` 权限，已存在则不动）。程序只读取同目录下的 `config.toml`；`config.toml.example` 只是模板，不会被自动读取，也不会自动复制或重命名为 `config.toml`。没有 `config.toml` 时，程序继续使用进程环境变量和内置默认值启动。
 
-- 优先级：**命令行参数 > 进程环境变量 > `.env` > 内置默认值**。
-- 语法：每行 `KEY=VALUE`；`#` 开头为注释；值两侧成对引号会剥除；空值视为未设置。
-- 支持的键：`BAT_OUTPUT`、`BAT_STATE_DIR`、`BAT_AUTO_DISCOVER`、`BAT_WATCH`、`BAT_DAEMON`、`BAT_PROXY`、`BAT_NO_PROXY`、`BAT_INTERVAL_SECONDS`、`BAT_ERROR_RETRY_SECONDS`、`BAT_APP_VERSION`、`BAT_CONNECTION_GROUP`、`BAT_LAUNCHER_VERSION`、`BAT_PLATFORMS`、`BAT_CURL`、`BAT_UNZIP`、`BAT_JSON`、`BAT_QUIET_UP_TO_DATE`；也可以直接写 `HTTPS_PROXY` 等通用环境变量（走现有代理自动检测）。布尔值支持 `1/0/true/false/yes/no/on/off`。
-- `BAT_WATCH` / `BAT_DAEMON` 只对无子命令的 `bat` 生效（两者同时为 `1` 时 daemon 优先）；命令行显式传入 `--watch` / `--daemon` / `--dry-run` 时 `.env` 的模式开关让位。`status` / `verify` 等子命令不受它们影响。
+由于 `config.toml` 可能包含代理凭据，Unix 下实际 `config.toml` 必须保持 `0600` 或更严格；权限过宽时程序会拒绝读取。
+
+- 优先级：**命令行参数 > 进程环境变量 > `config.toml` > 内置默认值**。
+- `config.toml` 的字段按职责分组：`[runtime]`、`[resource]`、`[localized]`、`[repository]`、`[network]`、`[translation.worker]`。
+- 现有 `BAT_*` 环境变量仍然有效，可继续覆盖 `config.toml` 中的同名配置。
+- `BAT_SKIP_ENV_FILE` 已废弃且不再影响启动。
+- 支持的环境变量：`BAT_OUTPUT`、`BAT_LOCALIZED_OUTPUT`、`BAT_STATE_DIR`、`BAT_AUTO_DISCOVER`、`BAT_WATCH`、`BAT_DAEMON`、`BAT_IMPORT_REPOSITORY`、`BAT_IMPORT_CAS_ROOT`、`BAT_IMPORT_RESOURCE_DB`、`BAT_PROXY`、`BAT_NO_PROXY`、`BAT_INTERVAL_SECONDS`、`BAT_ERROR_RETRY_SECONDS`、`BAT_APP_VERSION`、`BAT_CONNECTION_GROUP`、`BAT_LAUNCHER_VERSION`、`BAT_PLATFORMS`、`BAT_CURL`、`BAT_DOWNLOAD_CONCURRENCY`、`BAT_UNZIP`、`BAT_JSON`、`BAT_QUIET_UP_TO_DATE`、`BAT_TRANSLATION_PROVIDER`、`BAT_TRANSLATION_FIXTURE`、`BAT_TRANSLATION_MEMORY_PATH`、`BAT_TRANSLATION_CONCURRENCY`、`BAT_TRANSLATION_MAX_ATTEMPTS`、`BAT_TRANSLATION_LEASE_SECONDS`、`BAT_TRANSLATION_RETRY_BACKOFF_SECONDS`、`BAT_TRANSLATION_MAX_TASKS`、`BAT_TRANSLATION_WORKER_ID`；也可以直接写 `HTTPS_PROXY` 等通用环境变量（走现有代理自动检测）。布尔值支持 `1/0/true/false/yes/no/on/off`。
+- `BAT_WATCH` / `BAT_DAEMON` 只对无子命令的 `bat` 生效（两者同时为 `1` 时 daemon 优先）；命令行显式传入 `--watch` / `--daemon` / `--dry-run` 时运行模式设置让位。`status` / `verify` 等子命令不受它们影响。
+- 已运行的 daemon 不会热读 `config.toml`；默认 `reload` 只唤醒后台重新发现和刷新。需要应用配置文件变更时，使用带显式启动参数的 `restart`/`reload`，或先 `stop` 再重新启动 daemon。
 - `BAT_REDIS_URL` / `BAT_REDIS_PASSWORD` 为**预留键**：Redis 任务后端尚未接入，当前任务历史持久化在 `<state-dir>/bat-tasks.json`。
-- 设 `BAT_SKIP_ENV_FILE=1` 可让 `bat` 完全跳过 `.env` 的生成与加载。
+
+### Translation Memory V1
+
+Translation Memory 由 Rust `bat` 独立持有，默认路径为
+`<output>/translation-memory.sqlite`，不在 `versions/<id>` 内，也不使用当前 release
+的 `translation-tasks.sqlite`。可通过 `[translation.worker].translation_memory_path`、
+`BAT_TRANSLATION_MEMORY_PATH` 或 `--translation-memory-path` 覆盖。
+
+```bash
+bat i18n memory summary
+bat i18n memory query --tm-source-text '原始文本' --tm-context-json '{"destination":"Table.bytes","archive_entry":"","field_path":"Text"}'
+bat i18n memory confirm --tm-record-id 'tm-...' --tm-reviewer 'operator' --tm-reason '人工校对通过'
+```
+
+只有 raw source 完全相同、完整 context 完全相同且状态为 `trusted` 的记录会被 worker
+自动复用。provider 输出写入先是 `candidate`；manual task result 即使 completed 也不会自动
+建立 TM 或 trusted。查询、诊断和显式 confirm 对应 Rust
+RPC `translation.memory.summary`、`translation.memory.query`、`translation.memory.confirm`。
+context 不完整或不一致、normalized source 辅助命中和 workflow `proofread` 都不会自动
+建立 trusted 记录。
 
 ---