# ALCOMD3 maintenance notes

语言: [English](MAINTENANCE.md) | [日本語](MAINTENANCE.ja.md) | 简体中文

这些笔记记录 ALCOMD3 当前项目行为、兼容性边界和维护决策。修改 ALCOMD3 代码或从任何外部来源选择性引入修复时使用。

### 品牌

ALCOMD3 使用自己的品牌，同时保留既有安装所需的兼容性点。

- 产品和可见应用名：`ALCOMD3`。
- 窗口标题：`ALCOMD3`。
- Windows 安装器显示名称：`ALCOMD3`。
- Windows 快捷方式：`ALCOMD3`。
- Windows setup 输出名：`alcomd3-{version}-setup.exe`。
- 已安装主程序保留 legacy file name，用于兼容既有安装路径、协议关联和 updater/install migration。
- Windows 安装器更新既有应用安装，而不是并排安装。
- 当没有明确用户选择时，`vcc://` URL 快捷方式关联默认启用。

重要文件：

- `vrc-get-gui/Tauri.toml`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/commands/util.rs`
- `vrc-get-gui/src/config.rs`
- `vrc-get-gui/bundle/windows-setup.iss`
- `xtask/src/bundle_alcom.rs`
- `xtask/src/bundle_alcom/setup_exe.rs`

### 启动和窗口显示

保留这些行为：

- 创建主窗口时应用保存的初始窗口大小和最大化状态。
- 主窗口以隐藏状态启动，在前端调用 frontend-ready command 后由后端显示。
- `index.html` 保持静态首帧背景色，避免 CSS 和 JavaScript 加载前出现纯白闪烁。
- 正常 UI 启动前拒绝不支持的非 ASCII 主机名。

### Material Design 3 UI

保留这些行为：

- Material Theme 入口显示在侧边导航中。
- 侧边导航可显示可选 BOOTH、VRChatAvatarLearn 和版本按钮，可通过 `hide_sidebar_links` 隐藏。
- 版本按钮显示 `version: v{actual_version}` 并复制 `v{actual_version}`。
- Toast 使用圆角 MD3 样式、MD3 语义进度颜色和应用基础背景色。
- 重要项目/包操作使用 ALCOMD3 emphasis button 样式。
- setup 和 settings 文案中的用户可见文本使用 `ALCOMD3`。

重要区域：

- `vrc-get-gui/app`
- `vrc-get-gui/components`
- `vrc-get-gui/app/globals.css`
- `vrc-get-gui/lib/material-theme.ts`
- `vrc-get-gui/locales/*.json5`
- `vrc-get-gui/src/config.rs`

### 图标和第三方声明

应用图标使用 ALCOMD3 主题色 `#6cb6ff`，并由项目第三方资源声明覆盖。

- 重新生成图标时保留完整 logo 设计。
- 除非有明确设计决策，不要把小尺寸图标替换为简化版本。
- 保持 `vrc-get-gui/THIRD-PARTY.md` 准确。
- 应用内 Licenses 页面由 `vrc-get-gui/scripts/vite-build-license-json.ts` 生成。

重要资源：

- `vrc-get-gui/app-icon.png`
- `vrc-get-gui/icons/*`
- `vrc-get-gui/icon-LICENSE`
- `vrc-get-gui/third-party/Anton-Regular-OFL.txt`
- `vrc-get-gui/third-party/NotoSans-OFL.txt`

### 软件包操作

ALCOMD3 拥有 package operation progress 和 cancellation behavior。

保留这些行为：

- 安装、移除、重装软件包时显示进度弹窗。
- 弹窗显示逐包状态、整体进度和成功/失败数量。
- 失败的软件包可以重试。
- 用户可以终止长时间操作。
- 操作期间关闭主窗口时请求终止，而不是立即关闭应用。
- 终止不应把已经成功的软件包变成失败项。
- 可以并行时继续执行并行软件包工作；一个软件包失败不应无谓停止无关软件包。

后端规则：

- `AbortCheck` 在前端取消、窗口关闭拦截、包下载、包解压和包应用步骤之间共享。
- Download/cache verification 和 zip extraction 在 copy chunk 之间检查取消。
- 包安装/移除/重装进度通过 `TauriProjectApplyProgress` 上报。
- 收集并报告部分包失败，同时允许成功包继续完成。

重要区域：

- `vrc-get-gui/app/_main/projects/manage`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`
- `vrc-get-gui/src/state/project_apply.rs`
- `vrc-get-vpm/src/traits.rs`
- `vrc-get-vpm/src/environment/package_installer.rs`
- `vrc-get-vpm/src/unity_project/pending_project_changes.rs`
- `vrc-get-vpm/src/utils/extract_zip.rs`

### 项目复制、备份和恢复

保留这些行为：

- 项目复制显示进度并可取消。
- 备份和恢复 workflow 上报进度，避免看起来卡住。
- 主窗口关闭处理与正在运行的长任务协调，避免静默中断。

重要区域：

- `vrc-get-gui/app/_main/projects`
- `vrc-get-gui/src/commands/project.rs`
- `vrc-get-gui/src/commands/start.rs`

### 仓库管理

保留 ALCOMD3 仓库管理功能：

- 仓库排序 / 优先级调整。
- 查看仓库包含的软件包列表。

从任何来源引入包或仓库管理改动时，都要保留这些功能。

重要区域：

- `vrc-get-gui/app/_main/packages/repositories`
- `vrc-get-gui/components/ReorderableList.tsx`

### MCP bridge

ALCOMD3 包含可选本地 MCP bridge。除非未来变更通过 review 和 UI approval flow 明确扩展，否则保留最小只读边界。

保留这些规则：

- MCP data access 默认关闭，工具返回 ALCOMD3 数据前必须从 GUI 启用。
- 外部 MCP server 是通过 stdio 运行的 `alcomd3-mcp`。
- `alcomd3-mcp` 的 stdout 只能包含 MCP JSON-RPC 消息；诊断输出写入 stderr。
- GUI 运行时暴露 private localhost TCP IPC endpoint，并在本地数据目录的 `mcp/endpoint.json` 写入 metadata。
- GUI MCP enable/disable control 只 gate 工具数据访问，不应停止 local endpoint；禁用时工具调用返回 `mcp_disabled`。
- `ALCOMD3_MCP_ENDPOINT_FILE` 可为开发和测试覆盖 endpoint metadata path。
- 工具只读：list projects、get registered project details、list repositories、search already loaded packages。
- 读取详情前，`project_path` 必须匹配 ALCOMD3 registered project。
- MCP package search 不得强制 repository refresh。
- `initialize` 和 `tools/list` 不得启动 GUI。
- endpoint 不可用时，实际 tool call 可以启动 GUI。bridge 只能启动 packaged/sibling ALCOMD3 GUI executable 或明确的 `ALCOMD3_GUI_EXECUTABLE` override。
- `alcomd3-mcp` 不得 install、update 或 repair GUI。
- GUI shutdown 应删除 endpoint file。

重要区域：

- `docs/mcp.md`
- `alcomd3-mcp/`
- `alcomd3-mcp-protocol/`
- `vrc-get-gui/src/mcp.rs`
- `vrc-get-gui/src/commands/mcp.rs`
- `vrc-get-gui/app/_main/mcp/index.tsx`
- `xtask/src/build_alcom.rs`
- `xtask/src/bundle_alcom.rs`

### 更新器和发布

ALCOMD3 使用自己的 update source 和 signing key。

保留这些规则：

- Stable endpoint：`https://alcomd3.cqmhv.com/api/gui/tauri-updater.json`。
- Beta endpoint：`https://alcomd3.cqmhv.com/api/gui/tauri-updater-beta.json`。
- update-available dialog 包含打开 `https://alcomd3.cqmhv.com/` 的官网动作。
- 自动检查更新失败时对用户静默。
- 手动检查更新时，无更新和更新失败都显示 dialog。
- 版本使用 `2.1.0-beta.1` 这类 SemVer 字符串。
- updater private key 不得进入 git。
- 签名 updater installer 时遵循 `docs/RELEASE.zh-CN.md` 和 `docs/ALCOMD3_UPDATER.zh-CN.md`。
- 发布 website updater JSON 前，对每个将被服务的 JSON 文件运行 `cargo xtask verify-alcom-updater-json`。

### Windows 安装器

保留这些规则：

- Installer product name 是 `ALCOMD3`。
- Output setup file 使用 `alcomd3` 并包含版本。
- `VersionInfoProductVersion` 使用 Windows-compatible numeric version。
- Setup icon 使用 `vrc-get-gui/icons/icon.ico`。
- 安装时删除 legacy desktop/start menu shortcut。
- 已安装主程序保留 legacy file name。

### GitHub 配置

通用继承而来的 GitHub workflows 已有意移除。需要时应为本仓库明确重建 ALCOMD3 release automation。

保留：

- `.github/ISSUE_TEMPLATE/*`

当前仓库不维护 GitHub release workflow 或 signing action。本地 release automation 通过
`cargo xtask release-*` 维护；详见 `docs/RELEASE.zh-CN.md`。

有意删除：

- `.github/actions/sign-windows/action.yml`
- `.github/workflows/*`
- `.github/dependabot.yml`
- `.github/labeler.yml`
- `.github/scripts/*`
- `.github/copilot-instructions.md`

### Release notes 和本地构建命令

- 当前 stable release note：`release-notes/ALCOMD3_2.0.0.md`。
- 当前 beta release note：`release-notes/ALCOMD3_2.0.1-beta.1.md`。
- 过去 release notes 保留在 `release-notes/` 下。
- 未来 release notes 应聚焦用户可见的 ALCOMD3 变化。

Windows release build：

```powershell
cargo xtask release-build --version 2.0.1 --channel stable
```

预期输出：

- `artifacts/release/v{version}/alcomd3-{version}-setup.exe`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.sig`
- `artifacts/release/v{version}/alcomd3-{version}-setup.exe.zip`

已知非阻塞警告：

- `xtask/src/bundle_alcom/linux.rs` 可能出现 unused `mode` variable warning。
- Vite 可能提示 `vrc-get://localhost/global-info.js` 没有 `type="module"` 时无法 bundle。
