562 lines
27 KiB
Markdown
562 lines
27 KiB
Markdown
# AgentDock 技术架构方案
|
||
|
||
版本：1.0 · 日期：2026-08-24 · 角色：总工 · 状态：方案期交付
|
||
依据：`PRODUCT-REQUIREMENTS.md` v0.1 + `agent-cli-survey-2026-08-24.md`
|
||
范围：首批 14 适配器设计；第二批 4 个仅预留扩展点，不实现
|
||
|
||
---
|
||
|
||
## 0. 一句话定位与竞品差异
|
||
|
||
**AgentDock** = 本机桌面「Agent CLI 生命周期管家」：发现 → 环境检查 → 安装/识别 → 中文配置 → 授权 → 更新/卸载 → 诊断。
|
||
|
||
| 维度 | AgentDock | 智谱 ZCode（竞品） |
|
||
|---|---|---|
|
||
| 形态 | 纯本地桌面管理器 | GUI 开发环境 + 管理 |
|
||
| 模型绑定 | **渠道中立**，不绑任何厂商套餐 | 捆绑 GLM Coding Plan |
|
||
| 管理对象 | 官方渠道安装的第三方 CLI | 自家 Harness + 切换多工具 |
|
||
| 数据与密钥 | 全本地；密钥进系统钥匙串 | 订阅与账号体系偏云端 |
|
||
| 核心卖点 | 中文化、离线可用、可扩展适配器 | 可视化切换 + 自家模型 |
|
||
|
||
差异化口号（给总管翻译老板用）：**「不卖模型、不绑套餐——只管帮你把各家官方 CLI 装好、配好、查清楚。」**
|
||
|
||
---
|
||
|
||
## 1. 技术栈清单（以 PRD 4.2 为基线）
|
||
|
||
| 层 | 选型 | 理由 | 以后怎么扩展 |
|
||
|---|---|---|---|
|
||
| 桌面壳 | **Tauri 2** | 体积小、Rust 本机能力天然契合；比 Electron 更适合「管本机命令/文件」 | 二期加 macOS / ARM 时复用同一壳 |
|
||
| UI | **React 19 + TypeScript + Vite** | 生态熟、施工员上手快；与赛博风组件库兼容 | 可加路由/状态库，不换栈 |
|
||
| 样式 | **CSS Variables 设计 Token + 少量 Tailwind（或纯 CSS Modules）** | Token 对接美术师规范；避免硬编码颜色 | 主题切换 = 换 Token 集 |
|
||
| 动效 | **Framer Motion（布局/页面）+ CSS `@property`/滤镜光效；重粒子用 Canvas 可选** | 可控帧率、易降级 | 高特效档可再加 WebGL |
|
||
| 本机能力 | **Rust（Tauri commands + 独立 crate）** | 进程、PATH、文件原子写、密钥库、平台差异 | 能力以 IPC 契约暴露，UI 不直调 OS |
|
||
| 适配器定义 | **版本化 YAML（主）+ JSON Schema 校验** | 人可读、可热更新目录；PRD 已示意 YAML | 远程目录更新可不发版 |
|
||
| 本地状态 | **SQLite（`rusqlite` / `sqlx`）** | 安装记录、诊断历史、备份索引；比散落 JSON 好查 | 导出仍可用 JSON |
|
||
| 敏感信息 | **keyring crate** → Win Credential Manager / Linux Secret Service | 满足 PRD 4.2/8；禁止明文落盘 | 迁移仅钥匙串或用户重授权 |
|
||
| 配置解析 | **toml / serde_json / serde_yaml**；Crush 用专用 `crushrc` 解析器 | 覆盖 14 家格式差异 | 新格式 = 新 `ConfigCodec` |
|
||
| 包构建 | **tauri-cli + NSIS（Win）+ deb + AppImage（Ubuntu）** | 覆盖目标平台 | 二期可加 flatpak |
|
||
| 自动更新 | **Tauri updater（签名校验）**；更新源仅官方 CDN | 离线核心功能不依赖更新 | 可关自动检查 |
|
||
| 测试 | **Rust：cargo test；前端：Vitest；适配器：fixture 驱动** | 双平台 CI 矩阵 | 真机 smoke 人工/脚本 |
|
||
|
||
### 相对 PRD 的明确修正（仅 2 处）
|
||
|
||
1. **本地状态优先 SQLite，不用「纯原子 JSON」作主库**——诊断历史、备份索引、操作审计需要查询；配置文件本身仍原子写。
|
||
2. **适配器主格式定 YAML**——与 PRD 示例一致；运行时编译/校验为内部 JSON 表示，避免双源真相。
|
||
|
||
---
|
||
|
||
## 2. 目录结构与模块边界
|
||
|
||
```text
|
||
agentdock/
|
||
├── apps/
|
||
│ └── desktop/ # Tauri 2 应用入口
|
||
│ ├── src/ # React UI
|
||
│ │ ├── pages/ # 总览 / 目录 / 我的CLI / 配置 / 备份 / 设置
|
||
│ │ ├── components/
|
||
│ │ ├── tokens/ # 对接美术师：颜色/字体/动效/光效变量
|
||
│ │ ├── hooks/
|
||
│ │ └── ipc/ # 类型化 invoke 封装（唯一前端→Rust 入口）
|
||
│ ├── src-tauri/
|
||
│ │ ├── src/
|
||
│ │ │ ├── main.rs
|
||
│ │ │ ├── commands/ # Tauri IPC 命令（薄层）
|
||
│ │ │ └── lib.rs
|
||
│ │ └── tauri.conf.json
|
||
│ └── package.json
|
||
├── crates/
|
||
│ ├── agentdock-core/ # 编排：发现/安装/配置/授权/诊断流水线
|
||
│ ├── agentdock-adapter/ # schema 加载、版本校验、dry-run、执行器接口
|
||
│ ├── agentdock-platform/ # Win/Linux：PATH、权限提升探测、发行版识别
|
||
│ ├── agentdock-config/ # 原子写入、备份、多格式编解码
|
||
│ ├── agentdock-secrets/ # 系统密钥库封装 + 脱敏
|
||
│ ├── agentdock-exec/ # 参数白名单、禁止 shell 拼接的进程执行
|
||
│ ├── agentdock-diag/ # 规则引擎
|
||
│ └── agentdock-store/ # SQLite schema 与仓库
|
||
├── adapters/ # 版本化适配器 YAML（14 + 目录元数据）
|
||
│ ├── catalog.yaml # 目录索引
|
||
│ ├── schema/
|
||
│ │ └── adapter.schema.json # JSON Schema（校验 YAML）
|
||
│ └── tools/
|
||
│ ├── codex.yaml
|
||
│ ├── claude-code.yaml
|
||
│ ├── gemini.yaml
|
||
│ ├── copilot.yaml
|
||
│ ├── kimi.yaml
|
||
│ ├── qwen.yaml
|
||
│ ├── codebuddy.yaml
|
||
│ ├── opencode.yaml
|
||
│ ├── crush.yaml
|
||
│ ├── goose.yaml
|
||
│ ├── aider.yaml
|
||
│ ├── cursor.yaml
|
||
│ ├── cline.yaml
|
||
│ └── warp.yaml
|
||
├── docs/
|
||
│ └── architecture.md # 本方案落仓后副本
|
||
└── tests/
|
||
├── fixtures/ # 假 PATH、假配置文件、假 --version 输出
|
||
└── e2e/ # 可选：双平台 smoke 脚本
|
||
```
|
||
|
||
### 四层边界（施工员铁律）
|
||
|
||
| 层 | 职责 | 禁止 |
|
||
|---|---|---|
|
||
| **界面层** | 渲染适配器数据、表单、确认对话框、赛博视觉 | 直接拼命令、读写密钥、解析配置格式 |
|
||
| **本机能力层（Rust）** | IPC、编排、平台检测、执行、密钥、SQLite | 硬编码某 CLI 的特殊路径逻辑（应进适配器） |
|
||
| **适配器层** | 声明安装/检测/配置/授权/诊断；提供 dry-run | 在 YAML 里写任意 shell 字符串 |
|
||
| **状态存储** | SQLite 元数据 + 用户配置文件原子写 + 钥匙串 | 把 API Key 写入 SQLite/日志/备份默认项 |
|
||
|
||
### 模块关系（简图）
|
||
|
||
```text
|
||
UI --invoke--> commands --→ core orchestrator
|
||
├→ adapter registry (YAML)
|
||
├→ platform (env detect)
|
||
├→ exec (safe spawn)
|
||
├→ config codecs + atomic IO
|
||
├→ secrets (keyring)
|
||
├→ diag engine
|
||
└→ store (sqlite)
|
||
```
|
||
|
||
### 关键 IPC 契约（示意，施工员按此生成 TS 类型）
|
||
|
||
```typescript
|
||
// 均返回 Result；错误带 code + message_zh + raw（原始错误永不吞）
|
||
detectEnv(): PlatformEnv
|
||
listCatalog(): CatalogEntry[]
|
||
detectCli(id: string): DetectResult
|
||
previewAction(id, action, opts): DryRunPlan // 安装/更新/卸载/写配置/授权/修复
|
||
runAction(id, action, opts): ActionStream // 事件流：step/stdout/stderr/done
|
||
readConfig(id): ConfigFormState
|
||
writeConfig(id, patch): WriteResult
|
||
authStatus(id): AuthStatus
|
||
authorize(id, mode): AuthFlowHandle
|
||
diagnose(id): DiagnosticReport
|
||
listBackups() / createBackup() / restoreBackup(id, preview)
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 适配器 Schema（完整定义 + 14 工具渠道矩阵）
|
||
|
||
### 3.1 Schema 核心（在 PRD §6 上扩展）
|
||
|
||
```yaml
|
||
# adapter.schema 关键字段（v1）
|
||
id: string # 稳定 ID，如 codex
|
||
name: string # 展示名
|
||
name_zh: string
|
||
vendor: string
|
||
adapter_version: semver
|
||
license: string # 展示用；专有许可注明「仅官方渠道安装、不重打包」
|
||
platforms:
|
||
windows:
|
||
architectures: [x64]
|
||
notes: string? # 如 Gemini 要求 Win11 24H2+
|
||
linux:
|
||
distributions: [ubuntu]
|
||
architectures: [x64]
|
||
min_ubuntu: "22.04"?
|
||
official:
|
||
homepage: url
|
||
docs: url
|
||
allowed_hosts: [string] # 网络白名单（诊断/下载仅可访问）
|
||
runtime_deps: # 依赖探测
|
||
- id: node | python | git | powershell | ...
|
||
semver_range: ">=20"
|
||
required_for: [install|run]
|
||
install:
|
||
preferred: channel_id # 默认渠道
|
||
channels:
|
||
- id: npm | official_script | winget | choco | scoop | brew | apt | pypi_uv | github_release
|
||
platforms: [windows|linux]
|
||
# 命令必须是 argv 数组，禁止字符串拼接
|
||
command: [string, ...]
|
||
# 脚本类：下载 URL 必须在 allowed_hosts；执行走专用 runner，不经 /bin/sh -c
|
||
script:
|
||
url: url?
|
||
kind: powershell_irm | bash_pipe | ps1_file
|
||
integrity: { sha256: hex }? # 有则强制校验
|
||
package: string? # npm/pypi 包名
|
||
elevate: never | if_needed | required
|
||
elevate_reason_zh: string?
|
||
post_checks: [detect] # 安装后自动检测
|
||
detect:
|
||
executable: string # PATH 上的命令名；Cursor 为 agent
|
||
version_args: [string]
|
||
version_regex: string
|
||
version_unconfirmed: bool? # 调研标注「文档未能确认」时 true，UI 显示「实测兜底」
|
||
path_hints: [string]? # 非 PATH 常见位置
|
||
update:
|
||
method: npm_update | self_update_cmd | channel_reinstall | winget_upgrade | ...
|
||
command: [string, ...]?
|
||
uninstall:
|
||
method: npm_uninstall | package_manager | manual_delete
|
||
command: [string, ...]?
|
||
keep_config_default: true
|
||
authorization:
|
||
modes: # 可多选
|
||
- mode: browser_oauth | device_code | api_key | local_tui
|
||
command: [string, ...]?
|
||
env_keys: [string]? # 写入钥匙串后注入的环境变量名
|
||
status_command: [string, ...]? # 如 codex login status
|
||
notes_zh: string
|
||
configuration:
|
||
files:
|
||
- path: string # 支持 ~ 与平台变量
|
||
format: toml | json | jsonc | yaml | env | crushrc
|
||
scope: user | project | system
|
||
environment:
|
||
- key: string
|
||
sensitive: bool
|
||
maps_to_field: string
|
||
fields: # 中文配置表单
|
||
- id: string
|
||
label_zh: string
|
||
help_zh: string
|
||
required: bool
|
||
sensitive: bool
|
||
type: string | url | enum | bool
|
||
storage: file | env | keyring # keyring 永不进普通备份
|
||
platforms: [windows|linux]?
|
||
docs_url: url?
|
||
diagnostics:
|
||
- rule_id: string # 引用规则库或内联
|
||
documentation:
|
||
quickstart_zh: string
|
||
commands: [{ cmd, desc_zh }]
|
||
updated_at: date
|
||
risks_zh: [string]
|
||
```
|
||
|
||
### 3.2 统一执行器接口（Rust trait）
|
||
|
||
```text
|
||
AdapterExecutor:
|
||
detect() -> DetectResult
|
||
install(plan) / update / uninstall
|
||
read_config() / write_config(patch)
|
||
authorization_status() / authorize(mode)
|
||
diagnose() -> Vec<Finding>
|
||
dry_run(action) -> DryRunPlan # 必须：命令 argv、权限、影响文件、回滚说明
|
||
```
|
||
|
||
所有 `command` 经 `agentdock-exec`：`Command::new(prog).args(args)`，**禁止** `cmd /C`、`sh -c`、管道字符串。官方「curl | bash」类安装：下载到临时文件 → SHA256（若有）→ 用明确解释器执行文件（PowerShell `-File` / `bash script.sh`），并在 UI 展示完整脚本来源。
|
||
|
||
### 3.3 首批 14 CLI 安装渠道与设计依据（均来自调研底稿）
|
||
|
||
| ID | 命令 | 首选安装（Win / Ubuntu） | 备选 | 配置格式 | 授权模式 | 备注（底稿依据） |
|
||
|---|---|---|---|---|---|---|
|
||
| `codex` | `codex` | Win: 官方 PS 脚本或 npm `@openai/codex`；Ubuntu: 官方脚本或 npm | brew、GitHub Releases | TOML `~/.codex/config.toml` | browser + device_code + api_key | `--version` 文档未列，`version_unconfirmed` |
|
||
| `claude-code` | `claude` | Win: winget `Anthropic.ClaudeCode` 或 PS 脚本；Ubuntu: 官方脚本或 apt | npm（Node 22+） | JSON `~/.claude/settings.json` | browser + api_key | 专有许可：只引导官方安装 |
|
||
| `gemini` | `gemini` | 双端 npm `@google/gemini-cli`（Node 20+） | brew | JSON `~/.gemini/settings.json` | browser + api_key + vertex | Win 官方要求 11 24H2+，适配器 notes 声明 |
|
||
| `copilot` | `copilot` | Win: winget `GitHub.Copilot`（需 PS v6+）或 npm；Ubuntu: 脚本/npm/brew | — | JSON + env（`COPILOT_*`） | local_tui(`/login`) + PAT env | `--version` 未确认；需 Copilot 订阅 |
|
||
| `kimi` | `kimi` | 官方 `code.kimi.com` 脚本（内装 uv + **PyPI `kimi-cli`**） | `uv tool install kimi-cli` | TOML `~/.kimi/config.toml` | browser + api_key | **禁止** npm 仿名包 `kimi-code` |
|
||
| `qwen` | `qwen` | npm `@qwen-code/qwen-code`（Node 22+）或阿里 OSS 独立脚本 | brew | JSON `~/.qwen/settings.json` | **仅 api_key**（OAuth 已停） | `--version` 未确认 |
|
||
| `codebuddy` | `codebuddy` | npm `@tencent-ai/codebuddy-code` | `codebuddy install stable` 原生线 | 经 `codebuddy config`（路径待实测） | browser（微信登录）；api_key 未确认 | 双升级路径要分 channel |
|
||
| `opencode` | `opencode` | Win: choco/scoop；Ubuntu: 官方脚本/npm | brew、Releases | JSON/jsonc `~/.config/opencode/opencode.json` | api_key + browser + device_code | 授权面最全之一 |
|
||
| `crush` | `crush` | Win: winget `charmbracelet.crush`；Ubuntu: 官方 apt（GPG） | npm、scoop、Releases | **crushrc**（Bash 语法） | api_key（环境变量） | `--version` 未确认；FSL 许可展示说明 |
|
||
| `goose` | `goose` | Win: 官方 `download_cli.ps1`；Ubuntu: 官方脚本 | brew、deb | YAML；Win 注意 `%APPDATA%\Block\goose\...` | api_key + 订阅 ACP | 密钥默认进系统钥匙串 |
|
||
| `aider` | `aider` | 官方 `aider-install` / PS 脚本 / PyPI `aider-chat` | uv/pipx；**不推荐 brew** | YAML `.aider.conf.yml` | **仅 api_key** | 独立 Python 3.12 环境 |
|
||
| `cursor` | `agent` | **仅官方脚本**（Win PS / Linux curl）；**无 npm** | — | Cursor 账户体系 | browser（`agent login`） | 命令名是 `agent` 不是 cursor-agent |
|
||
| `cline` | `cline` | npm `cline`（Node 22+） | nightly 通道 | JSON `~/.cline/data/settings/providers.json` | browser + api_key + 本地模型 | 密钥已用系统 keychain |
|
||
| `warp` | `warp` | Win: 官方 agent-cli.ps1；Ubuntu: curl 脚本 | brew cask（Linux） | Warp 账户 / `WARP_API_KEY` | device_code + browser + api_key | 管 Agent CLI，不管 Warp 终端本体 |
|
||
|
||
### 3.4 第二批（暂缓，仅 catalog 占位 `status: watch`）
|
||
|
||
`grok`、`amp`、`deepseek-dsh`、`plandex` —— schema 允许加载但不出现在默认「可安装」列表，或灰显「观察中」。
|
||
|
||
---
|
||
|
||
## 4. 安全设计
|
||
|
||
### 4.1 密钥库封装
|
||
|
||
| 平台 | 后端 | API |
|
||
|---|---|---|
|
||
| Windows | Credential Manager（via `keyring`） | `secrets::set(service, account, secret)` |
|
||
| Linux | Secret Service / libsecret | 同上；无 daemon 时降级：**拒绝写入明文**，UI 提示安装 `gnome-keyring` |
|
||
|
||
- `service` 固定前缀 `agentdock.<cli_id>`；`account` 为字段 id（如 `api_key`）。
|
||
- 读配置时：表单敏感字段只显示「已保存 / 未保存」，回显用遮罩；真实值仅在写回目标 CLI 时短暂注入。
|
||
- **禁止**：SQLite、普通备份、日志、崩溃报告、剪贴板默认复制密钥。
|
||
|
||
### 4.2 命令执行边界
|
||
|
||
1. 仅执行适配器声明的 argv；用户输入只作为**已校验参数槽位**（枚举/路径/版本号），不做字符串拼接。
|
||
2. 默认禁止：管道、重定向、`$()`、反引号、`&&` 链、隐式脚本。
|
||
3. 工作目录限制在用户主目录或用户确认的项目根。
|
||
4. 下载：HTTPS + `allowed_hosts`；可选 SHA256；展示来源 URL。
|
||
5. 权限提升：`elevate: if_needed|required` 时弹窗说明 `elevate_reason_zh`；**应用本身不以管理员启动**。
|
||
6. 禁止远程网页驱动本机执行；禁止任意 URL 代理（防 SSRF）。
|
||
|
||
### 4.3 日志脱敏规则
|
||
|
||
| 模式 | 处理 |
|
||
|---|---|
|
||
| `sk-` / `xai-` / `ghp_` / `gho_` / JWT 形态 | 替换为 `***REDACTED***` |
|
||
| 适配器标记 `sensitive: true` 的 env/字段值 | 一律脱敏 |
|
||
| 家目录绝对路径 | 可选折叠为 `~`（诊断导出前提示） |
|
||
| 原始错误 | 保留结构，但过脱敏器后再落盘 |
|
||
|
||
---
|
||
|
||
## 5. 环境检测方案（Win 10/11 x64 · Ubuntu 22.04/24.04 x64）
|
||
|
||
`PlatformEnv` 结构：
|
||
|
||
```text
|
||
os: windows | linux
|
||
os_version: ...
|
||
arch: x64 | other(reject)
|
||
distro?: string # 发行版名，如 ubuntu（Windows 为 None）
|
||
distro_version?: string # 发行版版本，如 22.04（Wave 1 拆分：原 distro?: ubuntu + version）
|
||
shells: powershell_version?, bash_available?
|
||
runtimes: { node?, npm?, python?, uv?, git?, winget?, apt? }
|
||
path_entries: [...]
|
||
capabilities: { keyring: ok|missing, can_elevate: bool }
|
||
```
|
||
|
||
| 检测项 | Windows | Ubuntu |
|
||
|---|---|---|
|
||
| OS/版本 | `RtlGetVersion` / 注册表 | `/etc/os-release` |
|
||
| PATH | 用户+系统 PATH 合并，注意商店别名 | `$PATH` + `~/.local/bin` 是否在内（Goose/Cursor 常见坑） |
|
||
| Node/npm | `where node` + `node -v` | `command -v` + 版本 |
|
||
| Python/uv | `py -0p` / `uv --version` | 同上 |
|
||
| 包管理器 | winget / choco / scoop 可用性 | apt；可选 brew-on-linux |
|
||
| PowerShell | 区分 Windows PowerShell 5 vs pwsh 6+（Copilot winget 依赖） | N/A |
|
||
| 密钥库 | Credential Manager 可用性 | `secret-tool` / DBus Secret Service |
|
||
|
||
检测失败分类（对齐 FR-02）：`not_installed` | `not_in_path` | `permission_denied` | `exec_failed` | `version_unparseable`。
|
||
Wave 1 已把 `permission_denied` 从一般执行失败中拆分为独立状态（`std::io::ErrorKind::PermissionDenied` 单独归类），`RuntimeInfo.status` 相应支持该值。
|
||
|
||
---
|
||
|
||
## 6. 配置读写设计
|
||
|
||
### 6.1 原子写入 + 自动备份
|
||
|
||
对任意目标文件 `F`：
|
||
|
||
1. 若 `F` 存在 → 复制到 `F.bak.<timestamp>`（及 SQLite 备份索引）。
|
||
2. 写入临时文件 `F.tmp.<pid>`。
|
||
3. `fsync` 后 `rename` 覆盖（Windows 用 `MoveFileEx` 替换语义）。
|
||
4. 失败则保留原文件与临时文件，UI 展示原始错误。
|
||
|
||
### 6.2 多格式统一策略：`ConfigCodec` trait
|
||
|
||
| format | 实现要点 | 代表 CLI |
|
||
|---|---|---|
|
||
| `toml` | `toml_edit` 保注释 | Codex、Kimi |
|
||
| `json` / `jsonc` | jsonc 用 `jsonc-parser` 或 strip comments | Claude、Gemini、Qwen、OpenCode、Cline、Copilot |
|
||
| `yaml` | serde_yaml | Goose、Aider |
|
||
| `env` | KEY=VALUE 行；敏感键走钥匙串引用 | 多 CLI 辅助 |
|
||
| `crushrc` | **专用解析器**：识别 Crush 内建赋值语句，不做任意 bash 执行；未知行保留原样 | Crush |
|
||
|
||
表单字段 `storage`：
|
||
|
||
- `file` → Codec 读写
|
||
- `env` → 用户级环境变量（Win：用户环境；Linux：`~/.config/agentdock/env.d/*.sh` 并提示加入 shell，或仅会话注入说明）
|
||
- `keyring` → 只写钥匙串；可选写入 CLI 期望的「env 变量名指针」到配置（如 Codex `env_key`）
|
||
|
||
Goose：尊重其「密钥默认进系统钥匙串」——AgentDock 与之对齐，不把 Key 写入 `config.yaml`。
|
||
|
||
---
|
||
|
||
## 7. 授权状态统一模型
|
||
|
||
```text
|
||
AuthStatus = authorized | unauthorized | unknown | possibly_expired
|
||
AuthMode = browser_oauth | device_code | api_key | local_tui
|
||
```
|
||
|
||
| 模式 | AgentDock 行为 |
|
||
|---|---|
|
||
| `browser_oauth` | 启动适配器 login 命令；监听进程结束；可选检测本机打开浏览器；结果只存状态枚举 |
|
||
| `device_code` | 弹出「设备码」面板展示 stdout 中的 user_code + verification_url（解析规则在适配器）；不截获 token 明文到日志 |
|
||
| `api_key` | 表单写入钥匙串；按 CLI 要求设置 env 或 `login --with-api-key`（stdin 传，不进 argv） |
|
||
| `local_tui` | 打开一次性伪终端面板（如 Copilot `/login`、部分 onboarding）；结束后关闭，只留脱敏状态 |
|
||
|
||
状态探测优先级：
|
||
|
||
1. 适配器 `status_command`（如 `codex login status`、`opencode auth list`）
|
||
2. 钥匙串是否有对应 key
|
||
3. 配置文件非敏感标记
|
||
4. 否则 `unknown`
|
||
|
||
Qwen：UI 文案明确「免费 OAuth 已停用，请配置 API Key」。
|
||
Kimi：安装源校验拦截非官方 npm。
|
||
|
||
---
|
||
|
||
## 8. 赛博风 UI 技术支撑与性能底线
|
||
|
||
### 8.1 与美术师对接点（施工员只消费 Token）
|
||
|
||
```text
|
||
src/tokens/
|
||
color.css /* --ad-bg, --ad-neon-cyan, --ad-danger, ... */
|
||
typography.css
|
||
space.css
|
||
motion.css /* --ad-duration-fast/mid, --ad-ease-cyber */
|
||
effects.css /* --ad-glow-strength, --ad-scanline-opacity */
|
||
tiers.css /* data-fx-tier="high|balanced|low" */
|
||
```
|
||
|
||
页面结构按 PRD §7：总览 / CLI 目录 / 我的 CLI / 配置中心 / 备份 / 设置。视觉细节以美术师 HEL-101 规范为准；架构只保证：**所有颜色/光晕/动效时长走 Token，组件不写死魔法数。**
|
||
|
||
### 8.2 实现分层
|
||
|
||
| 层级 | 技术 | 用途 |
|
||
|---|---|---|
|
||
| L0 静态 | CSS 渐变、网格背景、边框霓虹（`box-shadow` Token） | 常驻，成本低 |
|
||
| L1 过渡 | Framer Motion / CSS transition | 路由、列表、按钮 |
|
||
| L2 光效 | SVG/CSS 扫光、有限 blur | 卡片 hover、焦点 |
|
||
| L3 粒子/噪点 | 可选 Canvas，**默认关** | 总览背景 |
|
||
|
||
### 8.3 性能底线与降级
|
||
|
||
- 目标：集成显卡笔记本上总览页 **≥45 FPS**；交互延迟 <100ms。
|
||
- 默认档 `balanced`：关 L3、降低 blur、减少同时动画数量（`max-concurrent-motions ≤ 3`）。
|
||
- `low`：仅 L0+必要过渡；`prefers-reduced-motion` 强制 `low`。
|
||
- 长列表虚拟滚动；日志终端用虚拟化，避免万行 DOM。
|
||
- WebView 合成层：大面积滤镜仅用于静态背景层，不叠在滚动内容上。
|
||
|
||
---
|
||
|
||
## 9. 安装包分发与自动更新
|
||
|
||
| 产物 | 工具链 | 校验 |
|
||
|---|---|---|
|
||
| Windows x64 安装包 | Tauri + NSIS（或 MSI 二选一，首期 NSIS） | Authenticode 签名（有证书则必须；无证书时 UI 提示校验 SHA256） |
|
||
| Ubuntu | `.deb` + **AppImage**（覆盖无 root 场景） | deb 可用 GPG；AppImage 附 SHA256SUMS |
|
||
| 更新 | Tauri Updater | ed25519/minisign 签名；更新端点在 `allowed_hosts` |
|
||
| 回滚 | 保留上一版安装包；失败则提示卸载重装 + Git tag 对应版本 | 方案期约定：发版打 tag，坏版本从更新通道撤下 |
|
||
|
||
应用自动更新与「CLI 更新」分离：设置页两项独立开关。核心管理功能 **离线可用**（目录 YAML 内置；在线仅用于检查更新与声明过的诊断 URL）。
|
||
|
||
---
|
||
|
||
## 10. 诊断规则引擎
|
||
|
||
### 10.1 规则模型
|
||
|
||
```yaml
|
||
rule_id: path.missing_executable
|
||
severity: path | dependency | version_conflict | config_corrupt | network | auth
|
||
severity: info | warn | error
|
||
when: { adapter_expr } # 可选：仅某些 CLI
|
||
check: # 声明式检查器
|
||
type: which | semver | file_parse | http_head | keyring_has
|
||
...
|
||
message_zh: "..."
|
||
evidence: capture # 原始 which 输出等
|
||
fix:
|
||
- id: add_to_path
|
||
dry_run: true
|
||
reversible: true
|
||
impact_zh: "..."
|
||
```
|
||
|
||
### 10.2 四类必检（可扩展）
|
||
|
||
| 类 | 示例规则 |
|
||
|---|---|
|
||
| PATH | 可执行文件不在 PATH；Windows Store alias 劫持；`~/.local/bin` 未入 PATH |
|
||
| 依赖缺失 | Node 版本不满足（Gemini≥20、Claude/Qwen/Cline/Copilot npm≥22）；无 Git；无 uv（Kimi） |
|
||
| 版本冲突 | 多路径同名命令；npm global 与独立脚本双装（CodeBuddy 双通道） |
|
||
| 配置损坏 | JSON/TOML/YAML 解析失败；crushrc 无法识别关键赋值；权限不可读 |
|
||
|
||
网络类：仅 `HEAD/GET` 适配器 `allowed_hosts`。
|
||
输出：级别 + 证据 + 中文解释 + 推荐修复（修复前 dry-run + 备份）。
|
||
|
||
---
|
||
|
||
## 11. 测试策略
|
||
|
||
| 层级 | 内容 |
|
||
|---|---|
|
||
| 适配器单元测试 | 每个 YAML：schema 校验；dry-run 快照；version_regex 对 fixture stdout；危险命令（含 shell 元字符）必须拒载 |
|
||
| Codec 测试 | 各格式往返；保留未知键；原子写失败注入 |
|
||
| Exec 测试 | 拒绝管道字符串；参数白名单 |
|
||
| Secrets 测试 | mock keyring；断言日志无明文 |
|
||
| 平台检测测试 | Win/Ubuntu CI 或容器：`PlatformEnv` 字段；对「未安装」场景断言错误码 |
|
||
| UI 冒烟 | 目录渲染 14 条；安装确认框展示 argv；降级档无运行时错误 |
|
||
| 手工验收（对齐 PRD §10） | 双平台干净机：装应用→检测→至少 1 个 CLI GUI 安装成功→配置往返→Key 不进日志 |
|
||
|
||
Wave A 五个适配器必须先有绿灯测试，再扩 Wave B。
|
||
|
||
---
|
||
|
||
## 12. 分波次交付节奏（14 = 5 + 9，每步可运行）
|
||
|
||
对齐 PRD §11，并按老板升级的 14 适配器拆波：
|
||
|
||
### Wave 0 — 空壳可运行（约 1 迭代）
|
||
|
||
Tauri2 + React 壳、Token 占位、IPC 心跳、SQLite 空库、平台检测页、假目录。
|
||
|
||
### Wave 1 — 适配器框架 + 环境检测
|
||
|
||
Schema、加载器、dry-run、exec 沙箱、密钥库封装、日志脱敏。
|
||
|
||
### Wave 2 — Wave A 五件套打通全链路（安装→检测→配置→授权状态→诊断）
|
||
|
||
优先选「文档全、双平台稳、配置清晰」：
|
||
|
||
1. **Codex**（三授权 + TOML）
|
||
2. **Claude Code**（winget/脚本 + JSON）
|
||
3. **Gemini**（npm + JSON Schema）
|
||
4. **Kimi**（脚本/PyPI，验证非 npm 路径）
|
||
5. **OpenCode**（多渠道 + 多授权）
|
||
|
||
验收：五者均可 detect；至少两者 GUI 安装成功；API Key 配置往返；三类诊断可命中。
|
||
|
||
### Wave 3 — Wave B 补齐 9 个
|
||
|
||
**B1（npm/脚本同类）**：Qwen、CodeBuddy、Cline、Copilot
|
||
**B2（包管理器/特殊）**：Crush（winget/apt + crushrc）、Goose（PS 脚本 + YAML 路径差异）、Aider（Python 安装器）
|
||
**B3（闭源脚本）**：Cursor（`agent`）、Warp（`warp`）
|
||
|
||
每合入一个：单元测试 + 双平台 detect 记录。
|
||
|
||
### Wave 4 — 备份迁移 + 安装包 + 更新通道
|
||
|
||
备份不含密钥；Win NSIS + Ubuntu deb/AppImage；签名/SHA256；赛博视觉按美术规范挂满并做降级开关。
|
||
|
||
### Wave 5 — 打磨
|
||
|
||
批量更新、文档页中文、诊断规则扩容、第二批 watch 列表 UI。
|
||
|
||
---
|
||
|
||
## 13. 施工员开工检查清单（拿到本方案应无需再问架构）
|
||
|
||
- [ ] 按目录建 monorepo；适配器只加 YAML，不改 core 流程
|
||
- [ ] 一切安装命令来自上表与调研底稿，禁止凭记忆改包名
|
||
- [ ] Kimi 绝不走 npm；Cursor 绝不走 npm；命令名 `agent`
|
||
- [ ] 用户确认前只 `dry_run`；确认后流式展示 stdout/stderr
|
||
- [ ] 密钥只进 keyring；日志过脱敏
|
||
- [ ] 颜色/动效只引用 `tokens/`，等美术师规范合并
|
||
- [ ] 不实现第二批 4 个，不建远程业务后端
|
||
- [ ] 每 Wave 结束保持 `cargo test` + 前端 build 通过
|
||
|
||
---
|
||
|
||
## 14. 风险与需总管转告老板的点（非阻塞，已在方案内消化）
|
||
|
||
1. 若干 CLI 的 `--version` 官方未文档化 → 适配器 `version_unconfirmed` + 实测表。
|
||
2. CodeBuddy 配置路径、Copilot 登录是浏览器还是设备码 → Wave B 实测补字段。
|
||
3. Gemini 官方写 Win11 24H2+ → 低版本 Win10 显示「官方未支持」而非强装。
|
||
4. 无代码签名证书时 Win 智能筛选会报警 → 提供 SHA256 核对说明。
|
||
5. Crush FSL 许可 → 关于页展示，不做竞品再分发其源码。
|
||
|
||
---
|
||
|
||
**本方案只交付设计，不含实现代码、不建仓库、不部署。**
|
||
施工员以本文 + PRD + 调研底稿三件套开工；视觉以美术师规范为准。
|