refactor: separate native platforms and automate signed dual-platform releases

docs/development.md

@@ -0,0 +1,62 @@
+# 开发指南
+
+## 一次修改，两个平台
+
+`apps/macos` 和 `apps/windows` 各自拥有独立 Cargo package，只维护原生界面与交互。共享能力统一位于 `crates`，使用一个根 Cargo.lock 和工作区版本号。
+
+| 需要修改的内容 | 位置 | 联动范围 |
+| --- | --- | --- |
+| 语言、提示词输入、布局数据、消息校验 | `crates/ttree-core` | 两端 |
+| 免费翻译、分流、回退 | `crates/ttree-translate` | 两端 |
+| 流式 AI、HY-MT、本地服务 | `crates/ttree-ai` | 两端；Candle/Metal 实现限 Mac |
+| 配置和历史 | `crates/ttree-storage` | 两端；保持旧格式 |
+| 快捷键、自启和划词入口 | `crates/ttree-platform` | 两端，系统划词实现分目录 |
+| OCR 公共处理/结果类型 | `crates/ttree-ocr/src` | 两端 |
+| AppKit / Win32 控件 | `apps/macos` / `apps/windows` | 对应平台 |
+| 平台截图/OCR | `crates/ttree-ocr/src/macos` / `windows` | 对应平台 |
+
+![目录与依赖示意图](images/workspace.svg)
+
+不要复制两份配置模型或翻译策略。改变公共接口后同步更新两个调用端，保持平台专用依赖受 `cfg(target_os)` 保护。
+
+## 环境与运行
+
+Mac 需要 Rust stable、Xcode Command Line Tools，以及 Metal 编译工具。打 Universal 包还需 `rustup target add aarch64-apple-darwin x86_64-apple-darwin`。如果 `xcrun -f metal` 失败，在完整 Xcode 环境安装 Metal Toolchain。
+
+Windows 需要 Rust stable MSVC、Visual Studio C++ Build Tools 和 Windows SDK。平台包使用 `x86_64-pc-windows-msvc`。CI 的 Windows 2022 runner 已具备这些条件。
+
+```sh
+# 在对应系统任选一个入口；--show 显式显示默认隐藏的窗口
+cargo run -p ttree-macos -- --show
+cargo run -p ttree-windows -- --show
+
+# 编译和单元测试（workspace 成员在非对应平台使用空入口）
+cargo check --workspace --locked
+cargo test --workspace --locked
+
+# 发布脚本、签名失败场景和发布策略合约
+bash scripts/tests/run-release-tests.sh
+
+# Mac 上只做 Windows 类型检查
+cargo check -p ttree-windows --target x86_64-pc-windows-msvc --locked
+```
+
+不需要 Node 前端工具链。Mac 发布阶段使用固定版本的 Tauri 独立 signer，仅用于兼容旧客户端的更新附件签名。
+
+## 验证边界
+
+共享代码修改需检查两端。Mac 本地测试与 Windows 交叉检查通过后，仍需 Windows runner 的原生构建、单元测试、便携 ZIP 校验与启动验证。CI 保存 Windows 启动结果和截图作为 artifact；这只是启动检查，不能代替完整桌面交互回归。
+
+Windows 重绘问题可按需运行 `apps/windows/tests/repaint-regression.py`（需 unlocked desktop、Pillow、pywinauto）；输出放到 `target/repaint-regression`。Mac 签名和录屏权限的跨升级实测是不同证据，见[发布指南](releasing.md)。
+
+## 工作区整洁
+
+源码在 `apps/` 与 `crates/`；文档在 `docs/`；脚本按 `macos`、`windows`、`release` 分类。日志、截图测试证据和中间构建放 `target/`，对外附件放 `dist/`，均不提交。
+
+README 图片放 `docs/images/`，只能提交确认可公开的界面。API Key 当前保存在用户配置目录 JSON 内，Mac 文件权限设为 0600；不要把它描述成 Keychain 存储，也不要将配置或聊天历史用于测试样本。
+
+## 品牌与渲染图
+
+单色 Logo 源文件为 `assets/icons/icon.svg`。Mac 安装 librsvg 后运行 `python3 scripts/branding/generate-icons.py`，统一生成 PNG、ICO、ICNS。Windows 可生成 PNG/ICO；发布前仍须在 Mac 更新 ICNS。Windows build.rs 将图标及版本编译进 EXE，窗口与托盘均读取内嵌图标。
+
+README 产品图源文件为 `docs/design/product.html`，按 1600 × 1080 CSS 像素渲染，导出 `docs/images/product.png`（当前为 2x）。这是基于现有布局的界面示意，不是实机截图；不要用它作为交互验收证据。