diff --git a/README.en.md b/README.en.md index d0d852a..fdc31cc 100644 --- a/README.en.md +++ b/README.en.md @@ -38,20 +38,18 @@

+ Quick Start · Project Overview · Core Capabilities · Supported Scope · Known Limitations · Processing Pipeline · - Quick Start · + Build from Source · Security Boundaries · Contributing

-> [!IMPORTANT] -> **LocaleSmith v1.1.0 is officially available from [Microsoft Store](https://apps.microsoft.com/detail/9NP8V6WQNGT0).** Installing from the Store is recommended so that dependencies and future updates are handled automatically; the [GitHub Release](https://github.com/DZXH-TX/LocaleSmith/releases/tag/v1.1.0) also provides the production MSIX signed by Microsoft Marketplace, with no development test certificate required. - ## Thirty-second overview | Focus | Actual behavior | @@ -62,6 +60,41 @@ | **Choice with control** | Ollama, OpenAI-compatible, and Anthropic; explicit model refresh and Token/batch budgets, with private reasoning replayed only inside the same provider protocol loop. | | **Credential and execution boundaries** | API keys stay in Credential Manager and configuration uses AES-256-GCM; models can propose commands, but policy and explicit user confirmation still gate execution. | +## Quick Start + +### Install + +> [!IMPORTANT] +> **Microsoft Store is the recommended installation channel.** It handles framework dependencies and future updates automatically. + + + + + + + + + + + + + + +
ChannelDescription
Microsoft Store
Recommended		Free download with automatic dependency installation and updates. Product ID 9NP8V6WQNGT0
GitHub Release v1.1.0Microsoft Marketplace-signed CRTech.LocaleSmith_1.1.0.0_x64.Msix; no development test certificate required
+ +MSIX checksum (SHA-256): A2F24B73D4B20C9255DE32F3A6949251067ADFC53A24A4732C50B96FBBA84F64　·　System requirements: Windows 10 1809 (build 17763) or later, x64 + +### Three steps + +```text +1. Add packages → Select a JAR / ZIP or one extracted directory; multi-archive folders use Add package multi-select +2. Configure a model → Choose local Ollama or a cloud preset; only cloud services require their API key +3. Start translation → Choose the target language and one style, then queue; output goes to the current Workspace's LocaleSmith.Output +``` + +> [!NOTE] +> The standalone stdio MCP Host `CRTech.LocaleSmith.McpHost` is published at `0.1.1` and exposes only `system.context` and `cli.propose`. See the [package README](./.github/package-readmes/LocaleSmith.McpHost.md) for installation, GitHub Packages authentication, and client configuration. + ## Project Overview **LocaleSmith | 译匠** is designed for Minecraft: Java Edition mods, resource packs, and shader packs, integrating **secure scanning, incremental translation, structural validation, and transactional rebuilding** into a native Windows desktop workbench. @@ -70,36 +103,66 @@ The project combines a native Rust scanning core with a .NET 10 / WinUI 3 deskto ## Core Capabilities +
+Translation and pipeline + +
+ | Capability | Description | | --- | --- | -| **Secure archive scanning** | Detects path traversal, Loader metadata, language resources, signature evidence, and supported Java string references. | -| **Incremental translation pipeline** | Reuses translations by content hash, validates placeholders and structure, and rolls back the entire job on failure. | -| **Mod project synchronization** | The Dashboard treats the same normalized source artifact as one process-local mod project and synchronizes its task objective, progress, status, and artifacts with the assistant; projects are not currently persisted across application restarts. | -| **Specialized prompts and terminology** | Automatically distinguishes mods, resource packs, and shader packs and applies dedicated domain prompts; Simplified Chinese jobs include a specialized terminology glossary for each content type. | -| **Multiple target languages** | Initially supports Simplified Chinese, English, Japanese, French, and Russian; the language catalog is centrally defined and can be extended. | -| **Multiple model integrations** | Provides unified support for Ollama, OpenAI-compatible Chat Completions, and Anthropic Messages. | -| **Provider presets** | Presets for DeepSeek, Qwen, Xiaomi MiMo, MiniMax, OpenAI, Doubao, Zhipu GLM, Kimi, and others fill in the endpoint, model name, and completion-token parameter. Ollama and OpenAI-compatible services that expose `/models` support explicit catalog refresh with manual fallback. Each source can also set response Tokens and the translation batch character target; providers that require cross-tool reasoning continuity replay private protocol state without displaying it in the UI. | -| **Online mod community** | Searches and paginates public mods and discussions; a PAT stored in Windows Credential Manager enables posting, replies, and reports, with direct access to the terms and community guidelines. | -| **Microsoft subscription and safe acceleration** | Uses native Microsoft Store purchase UI, authoritative MCTX backend entitlements, and one-time download grants; the default source always remains available and is used as a safe fallback. | -| **Persistent diagnostic logs** | When the log directory is writable, each translation attempts to persist a pair of Debug and All levels `.log` files through a bounded background writer; logs can be viewed from the left-hand “Logs” page, and the directory can be changed during onboarding or in Settings. | -| **Native desktop experience** | Provides first-run onboarding, a processing queue, a model assistant, model source management, logs, settings, and CLI risk confirmation. | -| **Model activity and real usage** | The assistant shows program-generated model-round and tool activity rather than private reasoning. Provider-reported token usage flows through assistant responses and translation tasks, including completed calls before failure/cancellation; missing or partial usage is marked explicitly and is never estimated. | -| **Credential and configuration protection** | Stores API keys in Windows Credential Manager and encrypts other configuration with AES-256-GCM. | -| **Controlled MCP / CLI** | The in-app assistant adds bounded project tools only when a mod project is active. The standalone stdio Host can still only read safe context and propose commands; CLI execution requires policy revalidation and explicit user confirmation. | +| **Secure archive scanning** | Detects path traversal, Loader metadata, language resources, signature evidence, and supported Java string references | +| **Incremental translation pipeline** | Reuses translations by content hash, validates placeholders and structure, and rolls back the entire job on failure | +| **Specialized prompts and terminology** | Distinguishes mods, resource packs, and shader packs and applies dedicated domain prompts; Simplified Chinese jobs include specialized terminology | +| **Multiple target languages** | Simplified Chinese, English, Japanese, French, and Russian; the centrally defined catalog can be extended | +| **Mod project synchronization** | Treats one normalized source artifact as a process-local project and synchronizes its objective, progress, status, and artifacts with the assistant | -## Supported Scope +
-| Category | Current Support | +
+Model integration + +
+ +| Capability | Description | | --- | --- | -| Input | JAR, ZIP, or one extracted mod/resource-pack/shader-pack directory; container folders with multiple JAR/ZIP files must be selected through Add package | -| Loader metadata | Fabric, Forge, NeoForge, Quilt, Legacy Forge | -| Text resources | Minecraft language JSON, Legacy `.lang`, shader-pack `shaders/lang/*.lang`, `pack.txt`, and supported display text in `pack.mcmeta` | -| Bytecode | Exact `Component.literal(String)` patterns proven by structural analysis; other candidates are reported but not rewritten | -| Model APIs | Ollama, OpenAI-compatible Chat Completions, Anthropic Messages | -| Model presets | DeepSeek, Qwen, Xiaomi MiMo, MiniMax, OpenAI, Doubao, Zhipu GLM, Kimi, and a custom entry point | -| Target languages | `zh_CN`, `en_US`, `ja_JP`, `fr_FR`, `ru_RU` | -| Output | One target language and one translation style selected for the current job; resource names inside the package use lowercase Minecraft locales such as `ja_jp` | -| Platform | Windows x64, minimum Windows 10 1809 | +| **Three protocols** | Ollama · OpenAI-compatible Chat Completions · Anthropic Messages | +| **Provider presets** | DeepSeek, Qwen, Xiaomi MiMo, MiniMax, OpenAI, Doubao, Zhipu GLM, and Kimi fill endpoint, model name, and recommended Token parameters | +| **Model catalog refresh** | Ollama and OpenAI-compatible services exposing `/models` support explicit refresh with manual fallback | +| **Budgets and private reasoning** | Each source sets response Tokens and a translation batch target; providers needing continuity replay private state only within the same protocol loop | +| **Real usage** | Shows only Provider-reported Token usage; completed calls survive failure/cancellation, while missing or partial values are clearly marked and **never estimated** | + +
+ +
+Desktop experience and operations + +
+ +| Capability | Description | +| --- | --- | +| **Native desktop experience** | First-run onboarding, processing queue, model assistant, model-source management, logs, settings, and CLI risk confirmation | +| **Persistent diagnostic logs** | When the directory is writable and the writer has capacity, translation attempts to persist Debug / All levels `.log` pairs; the Logs page and directory setting remain available | +| **Credential and configuration protection** | API keys stay in Windows Credential Manager; other configuration uses AES-256-GCM | +| **Controlled MCP / CLI** | The assistant gets bounded project tools only with an active project; command execution requires policy revalidation and explicit user confirmation | +| **Online mod community** | Browse public mods and discussions; use a Credential Manager PAT for posts, replies, and reports | +| **Microsoft subscription and safe acceleration** | Native Store purchase UI, authoritative backend entitlement, and one-time download grants, with safe fallback to the default source | + +
+ +## Supported Scope + + + + + + + + + + + + +
CategoryCurrent support
InputJAR, ZIP, or one extracted mod / resource-pack / shader-pack directory
Container folders with multiple JAR/ZIP files require Add package multi-select
Loader metadataFabric · Forge · NeoForge · Quilt · Legacy Forge
Text resourcesMinecraft language JSON · Legacy .lang · shader-pack shaders/lang/*.lang · pack.txt · supported display text in pack.mcmeta
BytecodeStructurally proven Component.literal(String) patterns
Other candidates are reported but not rewritten
Model APIsOllama · OpenAI-compatible Chat Completions · Anthropic Messages
Model presetsDeepSeek · Qwen · Xiaomi MiMo · MiniMax · OpenAI · Doubao · Zhipu GLM · Kimi · custom endpoint
Target languageszh_CN · en_US · ja_JP · fr_FR · ru_RU
OutputOne target language + one translation style per job; package resources use lowercase locales such as ja_jp
PlatformWindows x64, minimum Windows 10 1809
## Known Limitations @@ -133,32 +196,53 @@ The assistant's processing view contains only deterministic lifecycle events for ## Microsoft Store Subscription and Domestic Acceleration -LocaleSmith uses `Windows.Services.Store.StoreContext` to read the hidden parent-app-only subscription, display Microsoft purchase UI, and bind desktop modal UI to the main-window HWND. Partner Center is configured for monthly auto-renewal, an eligible new subscriber's seven-day free trial, a US$4.99/month global base tier localized by the Store, and CNY 30.00/month in China. The client UI displays only the actual renewal price returned by the Store for the current region; it does not hard-code the USD base tier for Chinese customers. Microsoft handles billing, and the subscription can be managed or cancelled under [Microsoft Services & subscriptions](https://account.microsoft.com/services); the [privacy policy](https://dow.dzxh-tx.cn/privacy) remains discoverable. Microsoft Store does not support a native “CNY 24 first month, then CNY 30” introductory price, and the client does not simulate one. +LocaleSmith itself is free. Domestic download acceleration is a separate, optional Microsoft Store subscription. -Purchase, restore, and refresh first require the existing LocaleSmith/MCTX account and a PAT with the `downloads:accelerated` scope. `Succeeded` and `AlreadyPurchased` only start `service-ticket → Store ID key → backend verify → entitlements`; they never unlock locally. Only an exact, usable `domestic_download_acceleration` backend entitlement can proceed. Missing `microsoft_store_billing_v1` / `accelerated_downloads_v1`, PAT, scope, entitlement, or fresh backend verification fails closed and hides or disables the paid entry. +
+Subscription and pricing -Source discovery accepts only the relative default source and `additional_source` decision returned by the API. The client never hard-codes an object-storage host, bucket, object key, or long-lived URL. One-time signed GET/HEAD URLs exist briefly only in memory and their HTTPS requests; they are not written to logs, configuration, diagnostics, clipboard, toasts, telemetry, or resume sidecars. Object-storage requests carry no PAT, Cookie, Authorization, Referer, or proxy credential and do not follow redirects. The transport uses a separate HEAD request for a strong ETag, up to four Range + If-Range requests, complete re-authorization and re-signing on grant expiry, and final API size/SHA-256 verification. Authorization, storage, or integrity failure falls back safely to the existing same-origin downloader. +
-Local automation covers the capability/PAT/scope/entitlement refusal matrix, purchase state machine, expiry/cancellation/refund/trial end, cross-device restore, suspended accounts, stale verification, secret request bodies, separate GET/HEAD signatures, exact HTTPS origin, four-way ranges, re-sign/resume, credential-free sidecars, SHA-256, and default-source fallback. The website source contract and replica worker now use the single `domestic_download_acceleration` entitlement. Real Partner Center products, purchase/renewal/refund/cross-device restore, Microsoft recurrence/service tickets, live PostgreSQL/Redis entitlement integration, and private RainS3 E2E remain unverified, and this work did not enable or deploy production acceleration. +| Item | Current configuration | +| --- | --- | +| Billing | Microsoft (Partner Center) | +| Period | Monthly auto-renewal | +| Trial | Seven days for eligible new subscribers | +| Global base tier | US$4.99/month, localized by the Store | +| China market | CNY 30.00/month | +| Manage or cancel | [Microsoft Services & subscriptions](https://account.microsoft.com/services) | -## Translation Logs and Persistent Settings +The client uses `Windows.Services.Store.StoreContext` for Microsoft purchase UI and **shows only the actual renewal price returned for the current region**. These tiers describe the current Partner Center configuration, not a hard-coded client promise. Microsoft Store does not support a native “CNY 24 first month, then CNY 30” introductory price, and LocaleSmith does not simulate one. The [privacy policy](https://dow.dzxh-tx.cn/privacy) remains discoverable. -The “Logs” page in the left navigation lists persistent records by translation job and displays the Debug view by default; switch to All levels to inspect records across all log levels, including fine-grained progress. Logging is a best-effort background diagnostic feature: when the directory is writable and the writer has capacity, a job creates a pair of `.debug.log` / `.all.log` files and incrementally flushes them to disk. On slow devices or when the queue is full, files or individual diagnostic entries may be skipped, but translation is never blocked. After an abnormal process exit, content that was successfully flushed remains available for identifying the last recorded stage. +
-The production Store package uses the logical `%LOCALAPPDATA%\LocaleSmith\logs\translations` default; unpackaged and Dev packages use the isolated `%LOCALAPPDATA%\LocaleSmith.Dev\logs\translations` root, with separate settings, credentials, Sandbox, and security locks. Windows may physically virtualize registered MSIX data under each PFN's `LocalCache\Local`, which remains package-isolated. During first-run onboarding and from the “Settings” page, you can browse for or manually enter a local directory. Once saved, a change takes effect with the next translation and is written to the encrypted configuration when the application closes, together with the last valid settings for language, theme, workspace, and other options. The application retains and lists only the latest 500 sessions; cleanup matches only LocaleSmith's own naming format and does not delete other files in the directory. Logs record only the task ID, package file name, stage, progress, result, and error type. They do not record API keys, full prompts, or the parent directory of a user-selected path. Common bearer, token, and API key patterns are redacted again before being written to disk. +
+Entitlement verification and download path -## Quick Start +
-### Install the release +Purchase, restore, and refresh require the existing LocaleSmith/MCTX account and a PAT with `downloads:accelerated`. `Succeeded` and `AlreadyPurchased` **never unlock locally**; they only start: -| Channel | Description | -| --- | --- | -| [Microsoft Store](https://apps.microsoft.com/detail/9NP8V6WQNGT0) | Recommended; get it free with installation, framework dependencies, and future updates handled by the Store. Product ID: `9NP8V6WQNGT0`. | -| [GitHub Release v1.1.0](https://github.com/DZXH-TX/LocaleSmith/releases/tag/v1.1.0) | Provides the Microsoft Marketplace-signed `CRTech.LocaleSmith_1.1.0.0_x64.Msix` for users who need a direct installer download. | +```text +service-ticket → Store ID key → backend verify → entitlements +``` + +Only an exact, usable `domestic_download_acceleration` backend entitlement can proceed. Missing `microsoft_store_billing_v1` / `accelerated_downloads_v1`, PAT, scope, entitlement, or fresh backend verification fails closed. + +Source discovery accepts only the relative default source and `additional_source` decision returned by the API. One-time GET/HEAD URLs are never persisted or written to logs, configuration, diagnostics, clipboard, toasts, telemetry, or resume sidecars. Storage requests carry no PAT, Cookie, Authorization, Referer, or proxy credentials and do not follow redirects. Transfers use a strong ETag, up to four Range + If-Range requests, full re-authorization and re-signing on grant expiry, and final API size/SHA-256 verification; authorization, storage, or integrity failure safely falls back to the existing same-origin downloader. + +
+ +> [!WARNING] +> **Current status:** local automation covers refusal paths, the purchase state machine, expiry/cancellation/refund/trial end, cross-device restore, four-way ranges, re-sign/resume, SHA-256, and default-source fallback. Real Partner Center products, live purchase/renewal/refund, Microsoft recurrence/service tickets, PostgreSQL/Redis entitlement integration, and private RainS3 E2E remain unverified, and **production acceleration has not been enabled or deployed**. + +## Translation Logs and Persistent Settings -The GitHub MSIX SHA-256 is `A2F24B73D4B20C9255DE32F3A6949251067ADFC53A24A4732C50B96FBBA84F64`. The production release supports Windows x64 and requires Windows 10 1809 (build 17763) or later. +The “Logs” page in the left navigation lists persistent records by translation job and displays the Debug view by default; switch to All levels to inspect records across all log levels, including fine-grained progress. Logging is a best-effort background diagnostic feature: when the directory is writable and the writer has capacity, a job creates a pair of `.debug.log` / `.all.log` files and incrementally flushes them to disk. On slow devices or when the queue is full, files or individual diagnostic entries may be skipped, but translation is never blocked. After an abnormal process exit, content that was successfully flushed remains available for identifying the last recorded stage. + +The production Store package uses the logical `%LOCALAPPDATA%\LocaleSmith\logs\translations` default; unpackaged and Dev packages use the isolated `%LOCALAPPDATA%\LocaleSmith.Dev\logs\translations` root, with separate settings, credentials, Sandbox, and security locks. Windows may physically virtualize registered MSIX data under each PFN's `LocalCache\Local`, which remains package-isolated. During first-run onboarding and from the “Settings” page, you can browse for or manually enter a local directory. Once saved, a change takes effect with the next translation and is written to the encrypted configuration when the application closes, together with the last valid settings for language, theme, workspace, and other options. The application retains and lists only the latest 500 sessions; cleanup matches only LocaleSmith's own naming format and does not delete other files in the directory. Logs record only the task ID, package file name, stage, progress, result, and error type. They do not record API keys, full prompts, or the parent directory of a user-selected path. Common bearer, token, and API key patterns are redacted again before being written to disk. -The standalone stdio MCP Host is maintained as the `CRTech.LocaleSmith.McpHost` .NET tool; the current source package version is `0.1.1`. It still exposes only `system.context` and `cli.propose`, with no App-only project or file tools. See the [package README](./.github/package-readmes/LocaleSmith.McpHost.md) for GitHub Packages authentication, installation, and client configuration. +## Build from Source ### Development prerequisites @@ -171,7 +255,7 @@ The standalone stdio MCP Host is maintained as the `CRTech.LocaleSmith.McpHost` | UI dependencies | Windows App SDK `2.3.1` and CommunityToolkit.Mvvm `8.4.2` are restored through NuGet; running the unpackaged WinUI app also requires Windows App Runtime `2.3.1` to be registered | | MSIX build | Requires Visual Studio Developer PowerShell with Desktop Bridge / WAP targets | -### Build from source +### Build Build the Rust release DLL first, then restore and build the .NET solution: @@ -276,16 +360,40 @@ These results demonstrate the source behavior covered by the current automation. ## Contributing -Pull requests are welcome. Before submitting code, run at least the Rust / .NET validation gates relevant to your changes, and clearly state the target Minecraft version, Loader, input type, and model source. +Pull requests are welcome. Before submitting: + +- [ ] Run the Rust / .NET validation gates relevant to the change +- [ ] State the target Minecraft version and Loader +- [ ] State the input type (JAR / ZIP / directory) and model source +- [ ] Disclose AI assistance that materially affected the project + +See also: [Code of Conduct](./.github/CODE_OF_CONDUCT.md) · [Contributing Guide](./.github/CONTRIBUTING.md) · [Security Policy](./.github/SECURITY.md) ## License This project is open source under the [Apache License 2.0](./LICENSE). -## Artificial Intelligence Use Statement +
+Artificial Intelligence Use Statement + +
This project permits the use of generative artificial intelligence tools for requirements analysis, code and documentation drafting, refactoring suggestions, test design, localization, and similar activities. All AI-assisted output must undergo human review, necessary testing, and security and license verification before submission. Maintainers and contributors remain fully responsible for the correctness, security, compliance, and maintainability of their submissions; AI output does not constitute a factual, legal, or professional guarantee. When using AI tools, do not upload secrets, credentials, personal information, unpublished source code, or restricted third-party content to unauthorized external services, and comply with the applicable terms of service and third-party licenses. Contributors should accurately disclose AI-assisted content with a material impact on the project in their pull requests. This statement does not alter the licensing, copyright, or contribution ownership established under the Apache License 2.0. -Copyright © 2026 **DZXH-TX（道泽星河-天仙）** (copyright holder and licensor). +
+ +
+ +
+ +Copyright © 2026 **DZXH-TX（道泽星河-天仙）** + +Copyright holder and licensor + +
+ +[Project home](https://github.com/DZXH-TX/LocaleSmith) · [Issues](https://github.com/DZXH-TX/LocaleSmith/issues) · [Discussions](https://github.com/DZXH-TX/LocaleSmith/discussions) + +
diff --git a/README.md b/README.md index 25672c3..df00a02 100644 --- a/README.md +++ b/README.md @@ -38,20 +38,18 @@

+ 快速开始 · 项目概览 · 核心能力 · 支持范围 · 已知限制 · 处理流程 · - 快速开始 · + 从源码构建 · 安全边界 · 参与贡献

-> [!IMPORTANT] -> **LocaleSmith v1.1.0 已在 [Microsoft Store](https://apps.microsoft.com/detail/9NP8V6WQNGT0) 正式上架。** 推荐通过商店安装，以自动处理依赖和后续更新；[GitHub Release](https://github.com/DZXH-TX/LocaleSmith/releases/tag/v1.1.0) 同时提供经 Microsoft Marketplace 签名的正式 MSIX，无需安装开发测试证书。 - ## 三十秒了解 | 重点 | 实际行为 | @@ -62,6 +60,41 @@ | **模型可选且可控** | Ollama、OpenAI-compatible、Anthropic；显式刷新模型列表、设置 Token/分批预算，私有推理只在同源协议轮次回放。 | | **凭据和执行有边界** | API Key 在 Credential Manager，配置 AES-256-GCM；模型只能提议命令，执行仍需策略复核和用户确认。 | +## 快速开始 + +### 安装 + +> [!IMPORTANT] +> **推荐通过 Microsoft Store 安装**，商店会自动处理框架依赖与后续更新。 + + + + + + + + + + + + + + +
渠道说明
Microsoft Store
推荐		免费获取，自动安装依赖与更新。产品 ID 9NP8V6WQNGT0
GitHub Release v1.1.0经 Microsoft Marketplace 签名的 CRTech.LocaleSmith_1.1.0.0_x64.Msix，无需安装开发测试证书
+ +MSIX 校验和（SHA-256）：A2F24B73D4B20C9255DE32F3A6949251067ADFC53A24A4732C50B96FBBA84F64　·　系统要求：Windows 10 1809（Build 17763）及以上，x64 + +### 三步上手 + +```text +1. 添加包 → 选择 JAR / ZIP 或单个展开目录；多归档目录使用“添加包”多选 +2. 配置模型 → 选择本地 Ollama 或云端预设；仅云端服务需要对应 API Key +3. 开始翻译 → 选择目标语言与一种风格后入队；产物写入当前 Workspace 的 LocaleSmith.Output +``` + +> [!NOTE] +> 独立 stdio MCP Host `CRTech.LocaleSmith.McpHost` 已发布 `0.1.1`，仅暴露 `system.context` 与 `cli.propose`。安装、GitHub Packages 鉴权与客户端配置见[包 README](./.github/package-readmes/LocaleSmith.McpHost.md)。 + ## 项目概览 **LocaleSmith | 译匠**，面向 Minecraft: Java Edition 模组、资源包与光影包，将**安全扫描、增量翻译、结构验证和事务重建**整合进一个 Windows 原生桌面工作台。 @@ -70,36 +103,66 @@ ## 核心能力 +
+翻译与流水线 + +
+ | 能力 | 说明 | | --- | --- | -| **安全归档扫描** | 识别路径穿越、Loader 元数据、语言资源、签名证据与受支持的 Java 字符串引用。 | -| **增量翻译流水线** | 按内容哈希复用译文，校验占位符与结构，并在失败时回滚整个作业。 | -| **模组项目同步** | Dashboard 将同一规范化源 artifact 作为一个进程内模组项目，向助手同步任务目标、进度、状态与产物；当前不会跨应用重启持久化项目。 | -| **专业提示与术语** | 自动区分模组、资源包与光影包，使用独立领域提示；简体中文任务附带各自的专业术语对照表。 | -| **多目标语言** | 首批支持简体中文、英语、日语、法语与俄语；语言目录集中定义，可继续扩展。 | -| **多模型接入** | 统一支持 Ollama、OpenAI-compatible Chat Completions 与 Anthropic Messages。 | -| **提供方预设** | DeepSeek、Qwen、Xiaomi MiMo、MiniMax、OpenAI、豆包、智谱 GLM 与 Kimi 等预设会同步填充服务地址和模型名，并选择推荐的补全 Token 参数；Ollama 与支持 `/models` 的 OpenAI-compatible 服务可显式刷新模型列表，始终保留手填回退。每个模型源还可设置单次响应 Tokens 与翻译分批字符目标；需要跨工具轮次连续思考的 Provider 会在协议层私下回放推理状态，不显示到 UI。 | -| **联机模组社区** | 可搜索和分页浏览公开模组与讨论；使用保存在 Windows Credential Manager 中的 PAT 发帖、回复和举报，并可直接查看服务条款与社区规范。 | -| **Microsoft 订阅与安全加速** | 使用 Windows 原生 Microsoft Store 购买界面、MCTX 后端权威权益核验与一次性下载 grant；加速不可用时始终保留并回退默认下载源。 | -| **持久化诊断日志** | 日志目录可写时，每次翻译都会尝试通过有界后台写入器持久化一对 Debug 与 All levels `.log`；可在左侧“日志”页查看并在引导或设置中修改目录。 | -| **原生桌面体验** | 提供首次引导、处理队列、模型助手、模型源管理、日志、设置和 CLI 风险确认。 | -| **模型活动与真实用量** | 助手显示由程序产生的模型轮次与工具活动，不展示私有推理；Provider 返回的 Token usage 会贯穿助手与翻译任务，失败/取消前已完成的调用也会保留，缺失或不完整时明确标记且绝不估算。 | -| **凭据与配置保护** | API Key 存入 Windows Credential Manager，其他配置使用 AES-256-GCM 加密。 | -| **受控 MCP / CLI** | App 内助手仅在有活动模组项目时增加受限项目工具；独立 stdio Host 仍只能读取安全上下文和提出命令，CLI 执行必须经过策略复核和用户明确确认。 | +| **安全归档扫描** | 识别路径穿越、Loader 元数据、语言资源、签名证据与受支持的 Java 字符串引用 | +| **增量翻译流水线** | 按内容哈希复用译文，校验占位符与结构，失败时回滚整个作业 | +| **专业提示与术语** | 自动区分模组、资源包与光影包并使用独立领域提示；简体中文任务附带专业术语对照表 | +| **多目标语言** | 简体中文、英语、日语、法语、俄语；语言目录集中定义，可继续扩展 | +| **模组项目同步** | Dashboard 将同一规范化源 artifact 作为一个进程内模组项目，向助手同步任务目标、进度、状态与产物 | -## 支持范围 +
-| 类别 | 当前支持 | +
+模型接入 + +
+ +| 能力 | 说明 | | --- | --- | -| 输入 | JAR、ZIP、展开后的单个模组/资源包/光影包目录；含多个 JAR/ZIP 的容器目录需通过“添加包”多选归档 | -| Loader 元数据 | Fabric、Forge、NeoForge、Quilt、Legacy Forge | -| 文本资源 | Minecraft 语言 JSON、Legacy `.lang`、光影包 `shaders/lang/*.lang`、`pack.txt`、受支持的 `pack.mcmeta` 显示文本 | -| 字节码 | 经结构证明的 `Component.literal(String)` 精确模式；其他候选仅报告、不改写 | -| 模型接口 | Ollama、OpenAI-compatible Chat Completions、Anthropic Messages | -| 模型预设 | DeepSeek、Qwen、Xiaomi MiMo、MiniMax、OpenAI、豆包、智谱 GLM、Kimi，以及自定义入口 | -| 目标语言 | `zh_CN`、`en_US`、`ja_JP`、`fr_FR`、`ru_RU` | -| 输出 | 当前作业选择的一种目标语言与一种翻译风格；包内资源名使用小写 Minecraft locale，如 `ja_jp` | -| 平台 | Windows x64，最低 Windows 10 1809 | +| **三类协议** | Ollama · OpenAI-compatible Chat Completions · Anthropic Messages | +| **提供方预设** | DeepSeek、Qwen、Xiaomi MiMo、MiniMax、OpenAI、豆包、智谱 GLM、Kimi，自动填充服务地址、模型名与推荐 Token 参数 | +| **模型列表刷新** | Ollama 与支持 `/models` 的 OpenAI 兼容服务可显式拉取列表，并始终保留手填回退 | +| **预算与私有推理** | 每个模型源可设置单次响应 Tokens 与翻译分批字符目标；需要连续推理的 Provider 只在同源协议轮次私下回放状态 | +| **真实用量统计** | 只展示 Provider 返回的 Token usage；失败/取消前已完成调用仍保留，缺失或不完整时明确标记，**绝不用字符数估算** | + +
+ +
+桌面体验与运维 + +
+ +| 能力 | 说明 | +| --- | --- | +| **原生桌面体验** | 首次引导、处理队列、模型助手、模型源管理、日志、设置与 CLI 风险确认 | +| **持久化诊断日志** | 日志目录可写且写入器有容量时，翻译会尝试持久化一对 Debug / All levels `.log`；可在“日志”页查看，目录可改 | +| **凭据与配置保护** | API Key 存入 Windows Credential Manager，其他配置使用 AES-256-GCM 加密 | +| **受控 MCP / CLI** | 助手仅在有活动项目时获得受限项目工具；命令执行必须经策略复核与用户明确确认 | +| **联机模组社区** | 可搜索浏览公开模组与讨论，使用 Credential Manager 中的 PAT 发帖、回复与举报 | +| **Microsoft 订阅与安全加速** | 使用原生 Store 购买界面、后端权威权益与一次性下载 grant；不可用时安全回退默认下载源 | + +
+ +## 支持范围 + + + + + + + + + + + + +
类别当前支持
输入JAR、ZIP、展开后的单个模组 / 资源包 / 光影包目录
含多个 JAR/ZIP 的容器目录需通过“添加包”多选归档
Loader 元数据Fabric · Forge · NeoForge · Quilt · Legacy Forge
文本资源Minecraft 语言 JSON · Legacy .lang · 光影包 shaders/lang/*.lang · pack.txt · 受支持的 pack.mcmeta 显示文本
字节码经结构证明的 Component.literal(String) 精确模式
其他候选仅报告、不改写
模型接口Ollama · OpenAI-compatible Chat Completions · Anthropic Messages
模型预设DeepSeek · Qwen · Xiaomi MiMo · MiniMax · OpenAI · 豆包 · 智谱 GLM · Kimi · 自定义入口
目标语言zh_CN · en_US · ja_JP · fr_FR · ru_RU
输出每个作业一种目标语言 + 一种翻译风格；包内资源名使用小写 locale，如 ja_jp
平台Windows x64，最低 Windows 10 1809
## 已知限制 @@ -133,32 +196,53 @@ Dashboard 添加源 artifact 时，会按规范化源路径在当前进程内注 ## Microsoft Store 订阅与国内加速 -LocaleSmith 使用 `Windows.Services.Store.StoreContext` 读取隐藏的父应用内订阅、显示 Microsoft 购买界面，并通过主窗口 HWND 绑定桌面模态 UI。Partner Center 配置为月度自动续费、符合资格的新订阅用户 7 天免费试用、全球 US$4.99/月基础价格档位并由 Store 本地化、中国市场配置 CNY 30.00/月；客户端界面只显示 Store 为当前区域返回的实际续费价，不向中国用户硬编码展示美元基础档位。订阅由 Microsoft 计费，可在 [Microsoft 服务和订阅](https://account.microsoft.com/services) 中管理或取消；[隐私政策](https://dow.dzxh-tx.cn/privacy) 保持可发现。Microsoft Store 不支持“首月 CNY 24、以后 CNY 30”的原生 introductory price，客户端不会伪造该优惠。 +LocaleSmith 本体免费；国内下载加速是独立、可选的 Microsoft Store 订阅。 -购买、恢复与刷新都要求先用现有 LocaleSmith/MCTX 账号和含 `downloads:accelerated` scope 的 PAT 登录。`Succeeded` 或 `AlreadyPurchased` 只会启动 `service-ticket → Store ID key → backend verify → entitlements`，不会直接解锁；只有后端返回精确的 `domestic_download_acceleration` 有效权益才可进入下一步。缺少 `microsoft_store_billing_v1` / `accelerated_downloads_v1`、PAT、scope、有效权益或后端新鲜核验时，购买或加速入口失败关闭。 +
+订阅说明与定价 -下载源发现只接受后端返回的相对默认源和 `additional_source` 判定；客户端不硬编码对象存储主机、bucket、对象 key 或长期 URL。一次性 GET/HEAD 签名 URL 只在内存和对应 HTTPS 请求中短暂存在，不进入日志、配置、诊断、剪贴板、toast、遥测或断点 sidecar；对象存储请求不携带 PAT、Cookie、Authorization、Referer 或代理凭据，也不跟随重定向。传输使用独立 HEAD 取得强 ETag，最多四路 Range + If-Range 下载，grant 过期时重新完成全套后端门控并续签，最终按 API 的 size 与 SHA-256 验证；任何授权、对象存储或完整性异常都会安全回退原有同源默认下载器。 +
-本地自动化已覆盖 capability/PAT/scope/权益拒绝矩阵、购买状态机、过期/取消/退款/试用结束、跨设备恢复、账号暂停、核验陈旧、秘密请求正文、GET/HEAD 分离、精确 HTTPS origin、四路 Range、续签续传、无秘密断点元数据、SHA-256 与默认源回退。网站源码契约和 replica worker 已统一使用唯一权益 `domestic_download_acceleration`，但尚未验证真实 Partner Center 商品、购买/续费/退款/跨设备恢复、Microsoft recurrence/service ticket、真实 PostgreSQL/Redis 权益联调或 RainS3 私有桶 E2E，也未在本次工作中启用或部署生产加速。 +| 项目 | 当前配置 | +| --- | --- | +| 计费方 | Microsoft（Partner Center） | +| 周期 | 月度自动续费 | +| 试用 | 符合资格的新订阅用户 7 天免费 | +| 全球基础档 | US$4.99 / 月，由 Store 按区域本地化 | +| 中国市场 | CNY 30.00 / 月 | +| 管理与取消 | [Microsoft 服务和订阅](https://account.microsoft.com/services) | -## 翻译日志与持久化设置 +客户端通过 `Windows.Services.Store.StoreContext` 显示 Microsoft 购买界面，并**只显示 Store 为当前区域返回的实际续费价**。上述档位是 Partner Center 当前配置，不是客户端硬编码承诺；Microsoft Store 不支持“首月 CNY 24、以后 CNY 30”的原生 introductory price，LocaleSmith 不会伪造该优惠。[隐私政策](https://dow.dzxh-tx.cn/privacy) 保持可发现。 -左侧导航中的“日志”页按翻译作业列出持久化记录，并默认显示 Debug 视图；切换到 All levels 可查看包含细粒度进度在内的完整级别记录。日志是最大限度的后台诊断功能：目录正常可写且写入器有容量时，作业会创建一对 `.debug.log` / `.all.log` 文件并增量刷新到磁盘；慢设备或队列已满时可能跳过文件或丢弃部分诊断条目，但不会阻塞翻译。进程异常退出后，已经成功刷新的内容仍可用于定位最后一个阶段。 +
-正式 Store 包的逻辑默认目录为 `%LOCALAPPDATA%\LocaleSmith\logs\translations`；unpackaged/Dev 包使用隔离的 `%LOCALAPPDATA%\LocaleSmith.Dev\logs\translations`，配置、凭据、Sandbox 与安全锁也不会和正式版混用。registered MSIX 的物理文件可能由 Windows 放入各自 PFN 的 `LocalCache\Local`，仍保持包间隔离。首次引导和“设置”页都可以浏览或手动修改为本地目录；更改保存后从下一次翻译起生效，并会在软件关闭时与语言、主题、工作区等最后一次有效设置一起写入加密配置。程序只保留并列出最新 500 次会话；清理仅匹配 LocaleSmith 自有命名格式，不删除目录内的其他文件。日志仅记录任务 ID、包文件名、阶段、进度、结果与错误类型，不写入 API Key、完整提示词或用户选择路径的父目录；常见 Bearer / Token / API Key 形式还会在写盘前再次脱敏。 +
+权益核验与下载链路 -## 快速开始 +
-### 安装正式版 +购买、恢复与刷新都要求现有 LocaleSmith/MCTX 账号，以及含 `downloads:accelerated` scope 的 PAT。`Succeeded` 或 `AlreadyPurchased` **不会直接解锁**，只会启动： -| 渠道 | 说明 | -| --- | --- | -| [Microsoft Store](https://apps.microsoft.com/detail/9NP8V6WQNGT0) | 推荐方式；免费获取并由商店处理安装、框架依赖与后续更新。产品 ID：`9NP8V6WQNGT0`。 | -| [GitHub Release v1.1.0](https://github.com/DZXH-TX/LocaleSmith/releases/tag/v1.1.0) | 提供 Microsoft Marketplace 签名的 `CRTech.LocaleSmith_1.1.0.0_x64.Msix`，适用于需要直接下载安装包的场景。 | +```text +service-ticket → Store ID key → backend verify → entitlements +``` + +只有后端返回精确的 `domestic_download_acceleration` 有效权益才可继续。缺少 `microsoft_store_billing_v1` / `accelerated_downloads_v1`、PAT、scope、有效权益或后端新鲜核验时，入口失败关闭。 + +下载源发现只接受 API 返回的相对默认源和 `additional_source` 判定。一次性 GET/HEAD URL 不落盘、不进入日志/配置/诊断/剪贴板/toast/遥测/断点 sidecar；对象存储请求不携带 PAT、Cookie、Authorization、Referer 或代理凭据，也不跟随重定向。传输使用强 ETag、最多四路 Range + If-Range，grant 过期时重新完成后端门控并续签，最终核对 API size 与 SHA-256；任何授权、存储或完整性异常都会安全回退原有同源下载器。 + +
+ +> [!WARNING] +> **当前状态**：本地自动化已覆盖拒绝矩阵、购买状态机、过期/取消/退款/试用结束、跨设备恢复、四路 Range、续签续传、SHA-256 与默认源回退；但尚未验证真实 Partner Center 商品、真实购买/续费/退款、Microsoft recurrence/service ticket、真实 PostgreSQL/Redis 权益联调或 RainS3 私有桶 E2E，**也未启用或部署生产加速**。 + +## 翻译日志与持久化设置 -GitHub MSIX 的 SHA-256 为 `A2F24B73D4B20C9255DE32F3A6949251067ADFC53A24A4732C50B96FBBA84F64`。正式版支持 Windows x64，最低系统版本为 Windows 10 1809（Build 17763）。 +左侧导航中的“日志”页按翻译作业列出持久化记录，并默认显示 Debug 视图；切换到 All levels 可查看包含细粒度进度在内的完整级别记录。日志是最大限度的后台诊断功能：目录正常可写且写入器有容量时，作业会创建一对 `.debug.log` / `.all.log` 文件并增量刷新到磁盘；慢设备或队列已满时可能跳过文件或丢弃部分诊断条目，但不会阻塞翻译。进程异常退出后，已经成功刷新的内容仍可用于定位最后一个阶段。 + +正式 Store 包的逻辑默认目录为 `%LOCALAPPDATA%\LocaleSmith\logs\translations`；unpackaged/Dev 包使用隔离的 `%LOCALAPPDATA%\LocaleSmith.Dev\logs\translations`，配置、凭据、Sandbox 与安全锁也不会和正式版混用。registered MSIX 的物理文件可能由 Windows 放入各自 PFN 的 `LocalCache\Local`，仍保持包间隔离。首次引导和“设置”页都可以浏览或手动修改为本地目录；更改保存后从下一次翻译起生效，并会在软件关闭时与语言、主题、工作区等最后一次有效设置一起写入加密配置。程序只保留并列出最新 500 次会话；清理仅匹配 LocaleSmith 自有命名格式，不删除目录内的其他文件。日志仅记录任务 ID、包文件名、阶段、进度、结果与错误类型，不写入 API Key、完整提示词或用户选择路径的父目录；常见 Bearer / Token / API Key 形式还会在写盘前再次脱敏。 -独立 stdio MCP Host 以 .NET 工具包 `CRTech.LocaleSmith.McpHost` 维护；当前源码包版本为 `0.1.1`。它仍只暴露 `system.context` 与 `cli.propose`，不包含 App 专属项目/文件工具。安装、GitHub Packages 鉴权与客户端配置见[包 README](./.github/package-readmes/LocaleSmith.McpHost.md)。 +## 从源码构建 ### 开发环境要求 @@ -171,7 +255,7 @@ GitHub MSIX 的 SHA-256 为 `A2F24B73D4B20C9255DE32F3A6949251067ADFC53A24A4732C5 | UI 依赖 | Windows App SDK `2.3.1`、CommunityToolkit.Mvvm `8.4.2` 由 NuGet 还原；运行 unpackaged WinUI 应用前还需注册 Windows App Runtime `2.3.1` | | MSIX 构建 | 需要包含 Desktop Bridge / WAP targets 的 Visual Studio Developer PowerShell | -### 从源码构建 +### 构建 先生成 Rust release DLL，再还原并构建 .NET solution： @@ -276,16 +360,40 @@ App 内助手始终保留 `system.context` 与 `cli.propose`；选中活动模 ## 参与贡献 -欢迎提交 Pull Request。提交代码前，请至少运行与改动相关的 Rust / .NET 验证门，并清楚说明目标 Minecraft 版本、Loader、输入类型和模型来源。 +欢迎提交 Pull Request。提交前请： + +- [ ] 运行与改动相关的 Rust / .NET 验证门 +- [ ] 说明目标 Minecraft 版本与 Loader +- [ ] 说明输入类型（JAR / ZIP / 目录）与模型来源 +- [ ] 如使用了对项目有实质影响的 AI 辅助，在 PR 中如实说明 + +另见：[行为准则](./.github/CODE_OF_CONDUCT.md) · [贡献指南](./.github/CONTRIBUTING.md) · [安全策略](./.github/SECURITY.md) ## 开源许可 本项目依据 [Apache License 2.0](./LICENSE) 开源。 -## 人工智能使用声明 +
+人工智能使用声明 + +
本项目允许在需求分析、代码与文档草拟、重构建议、测试设计和本地化等环节使用生成式人工智能工具。所有 AI 辅助产出必须经过人工审阅、必要测试以及安全与许可核验后方可提交；维护者和贡献者仍对其提交内容的正确性、安全性、合规性和可维护性承担完整责任，AI 输出不构成事实、法律或专业保证。 使用 AI 工具时，不得向未经授权的外部服务上传密钥、凭据、个人信息、未公开源码或受限制的第三方内容，并应遵守相应服务条款与第三方许可证。对项目有实质影响的 AI 辅助内容，贡献者应在 Pull Request 中如实说明；本声明不改变 Apache License 2.0 下的许可、版权与贡献归属。 -Copyright © 2026 **DZXH-TX（道泽星河-天仙）**（版权所有者与许可人）。 +
+ +
+ +
+ +Copyright © 2026 **DZXH-TX（道泽星河-天仙）** + +版权所有者与许可人 + +
+ +[项目主页](https://github.com/DZXH-TX/LocaleSmith) · [Issues](https://github.com/DZXH-TX/LocaleSmith/issues) · [讨论区](https://github.com/DZXH-TX/LocaleSmith/discussions) + +
diff --git a/docs/verification.md b/docs/verification.md index 0f7b1a4..4875d15 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -6,9 +6,10 @@ - 联合功能基线：`02c34a4`（已进入 `origin/main`，当时远端 Build and Test 与 CodeQL 成功）。 - 打包与状态隔离补强：`c2a6f7d`。 -- 最终二进制源码提交：`2d087426fc5c9c31206bb0de0798800ce298c22e`。 +- 本地 MSIX 二进制验证提交：`2d087426fc5c9c31206bb0de0798800ce298c22e`。 +- PR #12 squash merge 与 MCP 0.1.1 发布提交：`1f3f3d9a7ca5950da381a34565f517f9dd045183`。 - App FileVersion `1.2.0.0`，ProductVersion `1.2.0+2d087426…`。 -- MCP Host FileVersion `0.1.1.0`，ProductVersion `0.1.1+2d087426…`。 +- 已发布 MCP Host FileVersion `0.1.1.0`，ProductVersion `0.1.1+1f3f3d9a…`。 ## 自动化验证 @@ -54,7 +55,7 @@ dotnet pack src/LocaleSmith.McpHost/LocaleSmith.McpHost.csproj ` -PackageVersion 0.1.1 ... ``` -结果： +本地预合并复现结果（提交 `2d087426`）： - `CRTech.LocaleSmith.McpHost.0.1.1.nupkg` - 433,456 bytes @@ -62,7 +63,12 @@ dotnet pack src/LocaleSmith.McpHost/LocaleSmith.McpHost.csproj ` - 本地工具安装与 initialize/tools smoke 通过；服务版本 `0.1.1` - 独立 Host 仍只有 `system.context`、`cli.propose` -远端发布必须由指向上述源码提交、且已可从 `main` 到达的 `mcp-v0.1.1` tag 触发；本地包验证本身不能替代 Publish GitHub Package workflow 与 Packages 页面回读。 +远端发布结果： + +- `mcp-v0.1.1` 指向 `origin/main` 的 squash merge `1f3f3d9a`； +- [Publish GitHub Package run 32784059982](https://github.com/DZXH-TX/LocaleSmith/actions/runs/32784059982) 成功完成测试、pack、安装 smoke、artifact 上传与 GitHub Packages 推送；run 从创建到更新约 59 秒，其中 publish job 为 55 秒； +- Actions artifact ZIP `localesmith-mcp-nuget-0.1.1` 为 430,797 bytes；下载并解包后其中唯一的 nupkg 为 433,460 bytes，SHA-256 `B740AECC8D6B4242F478F1B48503AFD4675E2BA0B0C233B00AC09B2D5815D87D`，nuspec `RepositoryCommit` 与 ProductVersion 均绑定 `1f3f3d9a…`； +- [GitHub Packages 页面](https://github.com/DZXH-TX/LocaleSmith/pkgs/nuget/CRTech.LocaleSmith.McpHost) 已回读为 `0.1.1`“最新”，安装命令固定 `--version 0.1.1`，`0.1.0` 保留为历史版本。 ## 未签名 MSIX 1.2.0.0