Agent-Tools/IMPLEMENTATION.md

AgentDock Wave 2.2 实现说明

基线：工位 git wave-2.1 tag（d2e9de1，即 HEL-137 交付的 agentdock-wave-2.1-source.zip）。 本波对应老板复验 Wave 2.1 后提的 4 条「可用性」硬要求，逐条解决如下。

1. 安装输出实时滚动 + 失败提示人话化

根因：旧 run_streaming 先读 stdout、读完后才读 stderr，且主循环只在一行到达时才检查取消。导致 stderr 内容全部延迟到进程结束才一次性上屏（老板所见「最后才显示结果和中间过程」）。

修复（crates/agentdock-core/src/process.rs）：

• run_streaming / run_streaming_cancellable 改为两条读取线程并发消费 stdout/stderr，经 mpsc 通道按到达顺序实时回调，主循环用 recv_timeout(200ms) 兜底（静默期也能响应取消）。
• 新增 resolve_exe（PATH 解析到 .exe/.cmd/.bat 实际路径）、run_with_stdin（API Key 经 stdin 注入官方登录命令）、run_terminal（CREATE_NEW_CONSOLE 一次性终端窗口）、open_with_shell（explorer/xdg-open 打开文件或 URL）。
• RunningProcess 提供 request_cancel / cancel_flag；kill 在 Windows 用 taskkill /T /F 杀整棵进程树，避免 .cmd 包装的 node 子进程变孤儿。

人话化错误映射（crates/agentdock-core/src/errors_zh.rs）：

• program not found → 「未找到 X 命令：需要先安装 Y（可在本机环境区一键安装）」+ missing_runtime（npm→node、python→python、git、winget、uv…）。
• 网络超时/连接拒绝/DNS、磁盘不足、权限不足等均映射为中文建议。
• 原始报错保留在 raw，事件 data 携带结构化 ErrorHint { code, friendly_zh, raw, missing_runtime }（ActionEvent::error_hint）。

前端（pages/CliDetail.tsx）：失败态默认展示人话版，原始报错折叠可展开；missing_runtime 时给内联「去安装 Node.js」按钮，直达本机环境区一键安装（联动第 3 条）。

2. 软件内授权（PRD FR-06）

引擎（crates/agentdock-core/src/engine.rs）：

• 新增 Engine::authorize_stream + cancel_authorize + 会话注册表（可取消进程句柄）。
• 四类流程：
  • api_key：有官方命令时（如 codex login --with-api-key）从密钥库读 key 经 stdin 注入；无命令（opencode）仅核对密钥库。
  • browser_oauth：后台运行官方登录命令，流式回传、可取消、结束后刷新授权状态。
  • device_code：运行官方命令，parse_device_code 解析 user_code + verification_url（ANSI 去色 + 正则），大号验证码上屏。
  • local_tui：run_terminal 打开一次性本机终端窗口，结束只回传脱敏成败状态。
• 全程不记录令牌明文，日志/状态只存枚举；输出经 redact 脱敏。

前端（components/AuthPanel.tsx）：配置页「授权 / 登录」第一层从说明文字升级为可操作流程——每个授权方式一个「开始授权」按钮，弹「授权进行中」面板（可取消），设备码大号展示 + 一键复制 + 「打开授权网页」，结束后即时刷新授权状态灯。

3. 本机环境一键安装 + 修总览诊断

运行时来源表（crates/agentdock-core/src/runtime_install.rs）：

• 内置 node/python/git/winget/uv 官方来源（download_url + download_page + size_approx + elevate_needed + allowed_hosts）。
• is_url_host_allowed 白名单校验（安全红线）；download_with_curl 用系统 curl.exe 下载。

IPC（src-tauri/src/commands/runtime.rs）：previewRuntimeInstall / installRuntime（下载→打开安装向导，进度经 runtime-install-event 回传）/ openRuntimePage（官网兜底）。

前端（components/RuntimeInstallModal.tsx + pages/Overview.tsx）：本机环境未安装项变「安装」按钮 → 弹确认框（官方来源/体积/权限）→ 下载并打开安装向导；失败或不可直接安装时兜底「打开官方下载页」。

修诊断：新增 diagnoseAll IPC（对全部已装工具跑诊断），总览「立即诊断」（诊断卡 + 快速操作两处）都接上，弹全量诊断汇总。

4. 总览加载闪烁

• hooks/useDetectAll.ts / useEnv.ts：检测结果模块级本地缓存——切页回来先用缓存立即渲染，后台静默刷新。
• pages/Overview.tsx：检测未完成（首次、无缓存）时显示骨架屏「正在检测本机 CLI…」，绝不显示「工具箱是空的」；该文案仅在检测完成且确实零安装时出现。

涉及文件

• Rust：process.rs、errors_zh.rs（新）、runtime_install.rs（新）、engine.rs、types.rs、lib.rs（core）；commands/cli.rs、commands/runtime.rs（新）、commands/mod.rs、lib.rs（desktop）；secrets/src/keyring.rs（加真机往返测试）。
• 前端：ipc/index.ts、ipc/types.ts、components/AuthPanel.tsx（新）、components/RuntimeInstallModal.tsx（新）、components/ConfigForm.tsx、pages/CliDetail.tsx、pages/Overview.tsx、hooks/useDetectAll.ts、hooks/useEnv.ts、styles/global.css。

未引入任何新依赖（下载用系统 curl.exe、打开用 explorer.exe、任务树终止用 taskkill）。