rlwj-lab/opsxshell
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: 保存工作副本——客户端授权新契约(双端点/验签/令牌/周检)与桌面会话可靠性改进

Browse Source
This commit is contained in:
Logan.Li committed 2026-09-14 22:10:22 +08:00
1 parent f71eef0eba
commit ae6093c9b3
163 files changed
+4911 -2494
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/README.md
+12 -11
View File
@@ -2,16 +2,17 @@
文档按使用、开发、验收和发布分开维护，避免把规划能力写成已支持功能。
| 文档 | 内容 |
| ------------------------------------------ | ----------------------------------------------------- |
| [使用指南](./user-guide.md) | SSH、SFTP、代理、串口、AI 助手和数据安全 |
| [架构说明](./architecture.md) | Tauri/Rust 分层、原生服务、AI 与安全边界 |
| [架构重构轨道](./architecture-refactor.md) | EventSink / specta / infrastructure（未开始，单独做） |
| [SSH Agent CLI](./ai-agent.md) | ReAct 执行循环、工具、风险、记忆取舍与评测 |
| [测试验收](./testing-acceptance.md) | 本地门禁、真实 SSH 探针和发版验收 |
| [发布指南](./release.md) | 构建与产物；签名/公证/自动更新的做法（当前未完成） |
| [路线图](../ROADMAP.md) | 已完成基线与下一阶段（根目录权威副本） |
| [当前任务](../TASKS.md) | Hermes / OpenClaw 可勾选任务 |
| [测试计划](../TDD_PLAN.md) | 巡检、门禁与下一任务的测试先行 |
| 文档 | 内容 |
| -------------------------------------------------- | --------------------------------------------------------- |
| [使用指南](./user-guide.md) | SSH、SFTP、代理、串口、AI 助手和数据安全 |
| [架构说明](./architecture.md) | Tauri/Rust 分层、原生服务、AI 与安全边界 |
| [架构重构轨道](./architecture-refactor.md) | EventSink / specta / infrastructure（未开始，单独做） |
| [SSH Agent CLI](./ai-agent.md) | ReAct 执行循环、工具、风险、记忆取舍与评测 |
| [测试验收](./testing-acceptance.md) | 本地门禁、真实 SSH 探针和发版验收 |
| [发布指南](./release.md) | 构建、Tauri DMG、本机签名；公证 staple 与自动更新仍待完成 |
| [Apple 开发者签名](../download/Apple开发者签名.md) | 申请 Developer Program、Developer ID、导入钥匙串 |
| [路线图](../ROADMAP.md) | 已完成基线与下一阶段（根目录权威副本） |
| [当前任务](../TASKS.md) | Hermes / OpenClaw 可勾选任务 |
| [测试计划](../TDD_PLAN.md) | 巡检、门禁与下一任务的测试先行 |
项目定位、功能概览和开发命令见仓库根目录的 [README](../README.md)，未完成事项只在 [ROADMAP.md](../ROADMAP.md) / [TASKS.md](../TASKS.md) 维护。
docs/ai-agent.md
+6 -4
View File
@@ -9,6 +9,8 @@ OpsXShell 适合吸收 aiops Agent CLI 的执行 Harness，不适合照搬它的
产品目标是：用户在已连接的 SSH 终端中输入自然语言任务，Agent 通过少量、边界清晰的工具获取真实证据，按用户选择的安全模式决定确认阈值，失败后根据输出换方法，最后给出有证据的结论。无论选择哪种模式，目标主机始终可见，critical 命令始终硬拒绝。
设计边界声明：OpsXShell Agent 只服务桌面端当前 SSH 会话。任务开始时锁定当前 connectionId，后续执行和取消始终作用于该连接；标签切换不得让任务迁移到另一台主机。Agent 专用 SSH 结果在 Rust 原生层脱敏后才返回界面和模型上下文。OpsXShell 不复用 OpsXCLI 的本机执行器，也不承担 AIOps 的资产授权、审批和永久审计职责。
## 参考来源
本设计已逐篇评估同级 `aiops/docs/ai-agent/00-08` 及它们引用的工程基线：
@@ -43,9 +45,9 @@ OpsXShell 适合吸收 aiops Agent CLI 的执行 Harness，不适合照搬它的
-> 失败换方法 / 继续验证 / FINAL
```
- 单次任务最多 8 步。aiops 默认 16 轮适合后端异步任务；OpsXShell 是前台桌面工具，8 步更符合注意力、时延和成本边界。
- 单次任务最多 12 步。aiops 默认 16 轮适合后端异步任务；OpsXShell 是前台桌面工具，12 步兼顾排查+修复与注意力、时延、成本。
- 相同命令最多出现 2 次，第 3 次在执行前停止。
- 第 4 轮检查是否已有足够证据，第 8 轮强制优先收敛；连续失败时 Prompt 要求更换排查路径。
- 第 6 轮检查是否已有足够证据，第 12 轮强制优先收敛；连续失败时 Prompt 要求更换排查路径。
- 单步输出进入 Agent 前有 12,000 字符上限，任务观察上下文有 48,000 字符上限。
- `analyze_output` 是本地确定性工具：统计行数、提取错误关键行、保留首尾，不为压缩输出额外调用模型。
@@ -74,7 +76,7 @@ OpsXShell 适合吸收 aiops Agent CLI 的执行 Harness，不适合照搬它的
| OpenAI / Anthropic LLM 适配 | 已吸收 | 保留 OpenAI Chat、Responses、Anthropic Compatible 及自定义 Provider |
| `ssh_execute` | 已吸收 | 固定使用当前活跃 `connectionId`，不重新管理一套凭据 |
| `analyze_output` | 已适配 | 本地确定性摘要，降低 token 和幻觉 |
| ReAct 16 轮 | 适配为 8 步 | GUI 前台执行，优先快速收敛 |
| ReAct 16 轮 | 适配为 12 步 | GUI 前台执行；12 步够排查+验证，仍低于后台异步 16 轮 |
| 失败反馈和循环检测 | 已吸收 | 退出码和真实输出回传，连续失败换路，相同命令限次 |
| 五级风险 | 已吸收 | critical 硬拒绝，其他等级按安全模式阈值确认 |
| 两级安全模式 | 已适配 | 严格从 medium、宽松从 high 确认；critical 前后端均硬拒绝 |
@@ -131,7 +133,7 @@ src-tauri/src/services/ai/
### P1：运维效率
1. 任务中断和“停止”，不等待全部 8 步。
1. 任务中断和“停止”，不等待全部 12 步。
2. 只读组合命令的参数级评估，减少误判。
3. 用户显式保存的 Runbook 模板，支持变量预览和逐步确认。
4. 把已选终端文本、主机标签和系统信息组成最小上下文包，并显示实际发送范围。
docs/architecture-refactor.md
+2 -2
View File
@@ -6,7 +6,7 @@
- `infrastructure/` 只有 `file_log`，services 并不走它。
- `application/state.rs` 是服务集合，不是端口组合根。
- `DomainError` 零引用。
- 稳定 IPC 错误码放在 `domain/error.rs` 的 `codes`（如 `native.taskJoin`），不是空壳 `DomainError` 类型。
- SSH / 存储 / 桌面服务直接 `use tauri::AppHandle`；known_hosts 还用 `bind_app_handle` 全局 static。
- 前后端契约靠手写 `src/desktop.d.ts` + `shared/types/`，没有 specta / ts-rs。
@@ -66,7 +66,7 @@ pub trait EventSink: Send + Sync {
`infrastructure/mod.rs` 里现在的「SQLite / keychain / PTY 适配器」是过期注释，做 C 轨时改成与真实 trait 一致，没做的删掉，避免再写成已存在。
`DomainError`：有调用方再留，否则删。不要为空壳再加一层错误类型。
IPC 错误码继续用 `domain/error.rs` 的 `codes` 常量，不要再加一层空壳 `DomainError`。
## 明确不做（本轨道也不做）
docs/architecture.md
+4 -4
View File
@@ -82,7 +82,7 @@ XTerm 当前焦点分屏
-> 当前 connectionId 的 ssh_exec
-> stdout/stderr/exit_code + 本地 analyze_output
-> 真实观察脱敏后交给 AI 判断下一步
-> 最多 8 步后收敛
-> 最多 12 步后收敛
```
- Provider 配置和模型路由保存在 `ai-providers-v1`，不包含 API Key。
@@ -108,7 +108,7 @@ XTerm 当前焦点分屏
- `ForwardStatus` 由 Rust `TunnelManager` 管理，只在当前进程有效，包含监听端口、开始时间、连接数和流量。
- 每个运行实例有唯一 `forwardId` 和取消标志。用户点停止 / 删除正在运行的规则、关闭标签、连接面板手动断开，或进程退出时，Rust 才关闭真实 Listener。终端 SSH 断开、空闲挂起或重连不得拆掉未停止的规则。
- 本地 / 动态转发：本机 TCP 监听长住，每条规则共用一条专用 SSH 会话（保活；会话挂了只重建传输，不拆本地端口）。远程转发：专用会话保活，断开后在进程内自动重听。
- SSH 重连（同一 `user@host:port`）通过 `adopt_orphans` 把仍在监听的运行实例挂到新 connectionId。运行态仍不落盘。
- SSH 重连（同一 `user@host:port`）通过 `adopt_orphans` 把仍在监听的运行实例挂到新 connectionId。运行态仍不落盘。原生 `ssh_disconnect` 必须带真实 reason（keepalive / idle suspend / 用户关闭）；空缺时用 `connection closed`，不要再写 `closed by user`。
- 规则支持编辑和复制。复制只产生新的规则 ID，不复制运行态；运行中的规则必须先停止真实 Listener 才能编辑。
- 应用重启后不得根据上次 UI 状态显示“运行中”，必须以 `ssh_forward_list` 返回的原生状态为准。运行态只存在当前进程内存。
- 状态栏「转发」打开右侧抽屉：动态 SOCKS5 固定 `127.0.0.1:1080`（每台 SSH 主机一条），本地 / 远程规则可列表启停；右键状态栏项复制 `socks5://127.0.0.1:1080`。
@@ -118,7 +118,7 @@ XTerm 当前焦点分屏
## 远程桌面生命周期
- RDP / VNC 仅在 Tauri 原生应用中可用；浏览器预览不得显示为可连接。
- 会话运行态只存在原生内存；Canvas 帧与输入经 Tauri 事件传递；断开即取消 worker。
- 会话运行态只存在原生内存；Canvas 帧与输入经 Tauri 事件传递；断开即取消 worker。标签还开着时意外断开会有限次自动重连（新会话）；不发送假指针对抗空闲 GPO。
- RDP 可选剪贴板与共享盘（本机下载目录映射）；VNC 剪贴板按 UTF-8 发送。
- 桌面会话不参与批量命令与终端广播。
@@ -160,7 +160,7 @@ SSH 传输本身受协议 MAC 保护；当前应用额外执行大小校验，
- 不持久化终端命令历史或批量命令输出。
- 不持久化 AI 提示词、回答或终端上下文；API Key 不得返回 WebView 或写入普通 settings。
- 未实现能力不能在界面中显示为可用。
- 自动更新必须具备签名公钥、HTTPS 更新源和回滚策略，否则保持关闭。当前未接入 updater，做法见 [发布指南](./release.md#签名公证和自动更新未完成)。
- 自动更新必须具备签名公钥、HTTPS 更新源和回滚策略，否则保持关闭。当前未接入 updater，做法见 [发布指南](./release.md#签名公证和自动更新)。
- 五层目录补全、specta、EventSink 是单独轨道，见 [架构重构](./architecture-refactor.md)；未开始前继续按本文件的 commands → services → platform 扩展。
- 应用不能静默绕过 changed host key 或 known_hosts 不匹配。
docs/release.md
+85 -37
View File
@@ -1,5 +1,34 @@
# 发布指南
<a id="macos-next-steps"></a>
## 当前你要做的操作（v2.1.1 macOS）
本机已打出 **Tauri 窗口布局** 的 Developer ID 签名 DMG（不是手搓 `hdiutil`，Finder 里是大图标 + 拖到 Applications）：
```text
release/v2.1.1/macos-arm64/OpsXShell_2.1.1_aarch64.dmg
```
这份包**还没公证、没 staple**。别人下载后仍可能被 Gatekeeper 拦。你这边只差公证：
1. Finder 里弹出 `/Volumes/OpsXShell`（挂载中无法 staple）。
2. 开 Clash：`proxy-on`（公证走 HTTPS；时间戳构建阶段已经用 HTTP 回退签过了）。
3. 不要把 App 专用密码发到聊天。终端执行其一：
```bash
APPLE_ID='1024way@gmail.com' ./scripts/macos-notarize.sh
# 或
bash ~/Documents/apple签名/公证OpsXShell.sh
```
4. 弹出框里填 **App 专用密码**（appleid.apple.com → 登录与安全 → App 专用密码，标签如 `app notary`）。
5. 脚本会 `notarytool submit --wait --timeout 15m`。第一次可能很久；`--wait` 卡住时等它超时，再跑同一条命令——**已 Accepted 的不会重新上传，只会 staple**。不要对同一份未变化的 DMG 连续第三次 `submit`。
6. 成功标志：`xcrun stapler validate` 通过，且 `codesign -dv` 能看到钉票。把 **这一份** DMG 发出去（尽量不要走微信，隔离属性会更烦）。
7. 改代码后再 `./scripts/build.sh mac-arm64 --quick` 会得到新哈希，必须重新公证。
Windows Authenticode、自动更新仍未做，不要对外写「已公证」直到第 6 步完成。
## 构建命令
```bash
@@ -9,6 +38,10 @@
# macOS Apple Silicon 指定版本
./scripts/build.sh v2.1.1 mac-arm64
# 构建完成后公证并钉票（新 DMG 必须再跑；已 staple 会直接退出）
proxy-on # 本机 Clash；codesign 时间戳另见下文 HTTP 回退
APPLE_ID='你的开发者邮箱' ./scripts/macos-notarize.sh
# Windows x86_64（推荐在 Windows CMD/PowerShell 中执行）
scripts\build.bat v2.1.1 win-x64
@@ -87,64 +120,79 @@ lsof +D /Volumes/<临时卷名>
先正常退出该 OpsXShell 进程，再卸载对应的临时卷并重新构建。不要在应用仍从卷内运行时直接删除 `rw.*.dmg`。
## 签名、公证和自动更新（未完成）
<a id="签名公证和自动更新未完成"></a>
**当前状态：没有签名凭据，公开包是 ad-hoc / 未签名，未公证，没有自动更新。**
没有 `APPLE_*` / Authenticode 证书、minisign 私钥和 HTTPS 更新源之前，不得在 README、界面、Release 说明或 CI 绿勾上写「已签名」「已公证」「支持自动更新」。`tauri.conf.json` 的 `signingIdentity` 现在是 `"-"`；`plugins` 只有 deep-link，没有 updater。
## 签名、公证和自动更新
现有门禁只做「有凭据才验、没凭据就标明开发包」：
申请账号和 Developer ID、导入钥匙串的完整步骤见 [download/Apple开发者签名.md](../download/Apple开发者签名.md)。
**当前状态（本机可签 macOS；这份 DMG 待公证；自动更新仍未做）：**
- 仓库 `tauri.conf.json` 的 `signingIdentity` 仍是 `"-"`，没证书的环境还能打 ad-hoc 开发包。
- 本机若已导入 **Developer ID Application**，把身份写进 **gitignore** 的 `src-tauri/tauri.signing.conf.json`。`./scripts/build.sh` 发现该文件就会按 Developer ID 签名。
- DMG 必须走 Tauri bundler（`bundle.macOS.dmg`：窗口 720×440，应用图标与 Applications 分列）。不要用手搓 `hdiutil create`，Finder 图标会变小。
- `timestamp.apple.com:443` 不通时，构建会用 `scripts/macos-codesign-wrapper.sh` 走 HTTP 时间戳。可设 `CODESIGN_USE_SYSTEM_TIMESTAMP=1` 关闭。
- **每次新打的 DMG 都必须再公证并 staple**：`APPLE_ID='…' ./scripts/macos-notarize.sh`。已钉票会直接退出。`--wait` 卡住时脚本会超时后尝试 staple。
- 证书、CSR、私钥放本机文稿 `~/Documents/apple签名/`，不要进 git。Team 内其他 Mac 桌面应用可复用同一张 Developer ID。
- Windows Authenticode、minisign 自动更新仍未接线。没有凭据、或尚未 staple 时，不得在 README / 界面 / CI 上写「已签名」「已公证」「支持自动更新」。
门禁：
- `REQUIRE_SIGNING=true` 时，`scripts/release-preflight.mjs` 检查环境变量齐全，`scripts/verify-release.mjs` 拒绝 macOS ad-hoc、要求 Windows Authenticode `Valid`。
- 未设该变量时，`./scripts/build.sh` 仍可打开发包，验证只检查架构和体积。
- CI 工作流 `.github/workflows/tauri-release.yml` 已能在 Secrets 齐全时写入 `src-tauri/tauri.signing.conf.json` 再构建；**本地 `build.sh` 还不会生成这份配置**，所以本机即使导出了同样的环境变量，也不会走出 ad-hoc。
- 全仓库没有 `notarytool` / `staple`。Developer ID 签过但未公证的 `.app`，用户机器上仍会被 Gatekeeper 拦。
- `scripts/release.py` 仍提示「右键打开」——这是 ad-hoc 包的权宜说明，正式公证后必须删掉。
- 未设该变量时，`./scripts/build.sh` 仍可打开发包；若存在 `tauri.signing.conf.json` 则会签 Developer ID。
- CI `.github/workflows/tauri-release.yml` 在 Secrets 齐全时写入 `tauri.signing.conf.json`。本机用同一文件名即可，不要提交。
下面是有凭据之后的做法。没齐之前不要改 `signingIdentity`、不要接 updater 插件、不要在设置里放「检查更新」。
### 1. 凭据
### 1. 凭据（先买/申请，再接线）
| 平台 | 要什么 | 放到哪里 |
| -------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| macOS | Apple Developer Program；**Developer ID Application**（不是 Development）；App 专用密码 | 本机钥匙串 + gitignore 的 `tauri.signing.conf.json`；CI Secrets：`APPLE_CERTIFICATE`（p12 的 base64）、`APPLE_CERTIFICATE_PASSWORD`、`APPLE_SIGNING_IDENTITY`、`APPLE_ID`、`APPLE_PASSWORD`、`APPLE_TEAM_ID` |
| Windows | 代码签名证书（OV/EV PFX） | `WINDOWS_CERTIFICATE_BASE64`、`WINDOWS_CERTIFICATE_PASSWORD` |
| 自动更新 | 单独的 **minisign** 密钥对，与 Apple/Authenticode 不是同一把 | 私钥只进 CI Secrets；**公钥**写进仓库的 updater 配置 |
| 平台 | 要什么 | 放到哪里 |
| -------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| macOS | Apple Developer Program；**Developer ID Application** 证书（`.p12`）；App 专用密码 | 本机环境变量 + GitHub/Gitee Secrets：`APPLE_CERTIFICATE`（p12 的 base64）、`APPLE_CERTIFICATE_PASSWORD`、`APPLE_SIGNING_IDENTITY`（如 `Developer ID Application: …`）、`APPLE_ID`、`APPLE_PASSWORD`、`APPLE_TEAM_ID` |
| Windows | 代码签名证书（OV/EV PFX） | `WINDOWS_CERTIFICATE_BASE64`、`WINDOWS_CERTIFICATE_PASSWORD` |
| 自动更新 | 单独的 **minisign** 密钥对，与 Apple/Authenticode 不是同一把 | 私钥只进 CI Secrets；**公钥**写进仓库的 updater 配置 |
`src-tauri/tauri.signing.conf.json` 必须进 `.gitignore`，不得提交。macOS 示例：
Linux 安装包（deb/rpm/AppImage）不走 Apple/Authenticode。自动更新的 `.sig` 是另一套签名，三平台都要。
`src-tauri/tauri.signing.conf.json` 由脚本现场生成，必须进 `.gitignore`，不得提交。
```json
{
"bundle": {
"macOS": {
"signingIdentity": "Developer ID Application: Logan Li (B8DVUUUF6W)"
}
}
}
```
### 2. 本地与 CI 同源签名
目标：本机 `REQUIRE_SIGNING=true ./scripts/build.sh` 与 CI 走同一条路径，都能复现同一类签名产物。
1. `build.sh` / `build.bat` 在签名变量齐全时，生成 `tauri.signing.conf.json`（macOS 写 `bundle.macOS.signingIdentity`；Windows 写 thumbprint / sha256 / timestamp），再 `npx tauri build --config src-tauri/tauri.signing.conf.json`。
2. 不要改仓库里的 `tauri.conf.json` 默认 `"-"`——没凭据的开发机构必须还能打 ad-hoc。
3. `REQUIRE_SIGNING=true` 时 `verify-release.mjs` 必须失败于 ad-hoc / 无效 Authenticode；不要为了绿而关校验。
4. 正式标签才设 `REQUIRE_SIGNING=true`。日常 PR 构建保持未签名。
1. 不要改仓库里的 `tauri.conf.json` 默认 `"-"`。
2. `REQUIRE_SIGNING=true` 时 `verify-release.mjs` 必须失败于 ad-hoc。
3. 正式标签才设 `REQUIRE_SIGNING=true`。日常 PR 保持未签名。
### 3. macOS 公证（notarytool + staple）
签名成功 ≠ 用户能打开。必须公证并钉票：
签名成功 ≠ 用户能打开。必须公证并钉票。不要对同一份未变化的 DMG 连续多次 `submit`。
```bash
# 构建并 Developer ID 签名之后
xcrun notarytool submit "$DMG" \
--apple-id "$APPLE_ID" --password "$APPLE_PASSWORD" --team-id "$APPLE_TEAM_ID" \
--wait
xcrun stapler staple "$DMG"
# 若 staple 的是 .app，再重新打 DMG，或对 DMG 再 staple
spctl --assess --type install --verbose "$DMG"
# 先弹出已挂载的安装盘，再：
APPLE_ID='开发者邮箱' ./scripts/macos-notarize.sh
# 可选：指定 DMG 路径
APPLE_ID='开发者邮箱' ./scripts/macos-notarize.sh release/v2.1.1/macos-arm64/OpsXShell_2.1.1_aarch64.dmg
```
验收（必须在**另一台未关 SIP、未关 Gatekeeper 的 Mac**上，不要只在构建机看 `spctl`）：
脚本会：已 staple 则退出；否则先 staple；没有票据才要 App 专用密码并 `notarytool submit --wait --timeout 15m`，超时仍 staple。开发者后台网页没有这份 DMG 的进度页，用终端或：
1. 下载 DMG，双击打开，拖到「应用程序」，**不要**右键「打开」、不要 `xattr -d`。
```bash
xcrun notarytool info <submission-id> --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID"
xcrun notarytool log <submission-id> --apple-id "$APPLE_ID" --team-id "$APPLE_TEAM_ID"
```
验收（必须在**另一台未关 SIP、未关 Gatekeeper 的 Mac**上）：
1. 下载 **staple 之后** 的 DMG，双击打开，拖到「应用程序」，不要右键「打开」、不要 `xattr -d`。
2. 能启动、能连 SSH，菜单里没有 DevTools。
3. `codesign --verify --deep --strict` 且 `codesign -dv` 不是 `Signature=adhoc`。
4. 删掉 Release 说明和 `release.py` 里的「右键绕过 Gatekeeper」。
3. `codesign --verify --deep --strict` 且 `codesign -dv` 含 `Notarization Ticket=stapled`，不是 `Signature=adhoc`。
没做完 staple 之前，文档继续写「未公证」。
没做完 staple 之前，对外说明不要写「已公证」。
### 4. Windows Authenticode
docs/testing-acceptance.md
+1 -1
View File
@@ -62,7 +62,7 @@ npm run acceptance:full
9. 新增 Provider 后测试前“保存”禁用；测试实际发送“你是什么模型？请简短回答。”，期间 settings 与 secrets 均无写入；只有非空成功回答显示 HTTP 200，随后保存才写入加密 Key。
10. 切换 Endpoint、模型、协议或 API Key 后“保存”立即重新禁用。
11. 每一轮只接受唯一单行命令；默认宽松模式下 safe/low/medium 自动执行、high 先确认；严格模式从 medium 起确认；critical 前后端均硬拒绝。需要确认时，对话框打开前和用户取消后 `ssh_exec` 调用次数必须为 0。Agent 发起的 `ssh_exec` 必须带 `fromAgent`。
12. 确认后只向当前 connectionId 执行；真实输出和 exit code 必须交给下一轮，直到 FINAL 或 8 步上限。
12. 确认后只向当前 connectionId 执行；真实输出和 exit code 必须交给下一轮，直到 FINAL 或 12 步上限。
13. `rm -rf /`、`mkfs`、对磁盘覆盖的 `dd` 等 critical 命令必须在确认对话框前硬拒绝。
14. 相同命令第 3 次必须在执行前拦截；连续失败的下一轮 Prompt 必须要求更换路径。
15. 超长工具输出必须限长，`analyze_output` 保留总行数、错误行和首尾；关闭面板后命令与输出消失。
docs/user-guide.md
+21 -5
View File
@@ -2,6 +2,12 @@
OpsXShell 主打简单好用：常用远程操作走短路径，高级选项默认收起。不做堡垒审计。
## 安装（macOS）
从 `release/v*/macos-arm64/` 打开 `.dmg`，把 OpsXShell 拖到「应用程序」。Finder 里应是 Tauri 那套大图标布局（应用在左、Applications 在右）。**已经 staple 的正式包**一般可直接打开。
自己改代码后重新打包：先 `./scripts/build.sh mac-arm64 --quick`（本机有签名配置就会签 Developer ID），再 `./scripts/macos-notarize.sh`（会要 App 专用密码）。新打的 DMG 在公证完成前仍会被 Gatekeeper 拦截。你现在要做的步骤见 [发布指南](./release.md#macos-next-steps)。
## 快速连接
按 `Cmd/Ctrl + K`，输入 `user@host` 或 `user@host:port` 后连接。默认端口为 `22`。快速连接适合临时使用，不会自动保存会话。
@@ -47,13 +53,23 @@ socks5://127.0.0.1:1080
- 保存的是规则，不是“运行中”状态；应用重启后需要用户再次启动。同一窗口内只要没点「停止」，SSH 断线、保活失败、空闲挂起或重连都会继续监听（本地 / SOCKS 端口不拆，远程转发会自动重听）。点停止、关闭标签、连接面板手动断开，或退出应用，才会关闭真实 Listener。关闭标签后再开同一会话不会自动拉起转发。
- SOCKS5 默认仅监听本机，当前不提供局域网开放和客户端密码认证。
## 连接保活与重连
默认对齐常见 SSH / RDP 客户端，分三层，不要把「窗口还开着」理解成无视服务器超时：
- **链路心跳**：空闲时发 SSH 协议 keep-alive（不写入 Shell）。挡的是 NAT/防火墙丢掉空闲 TCP，挡不住 Bash `TMOUT` 或 Windows 空闲 GPO。
- **意外断线**：终端、SFTP 或远程桌面标签还开着时，有限次自动重连。SSH 重连后是新 Shell（长任务请在服务器上用 `tmux`/`screen`）；SFTP 会回到断线前的远程目录；RDP/VNC 重连是新会话，不会发假鼠标。
- **会话策略**：远端 `TMOUT` / `logout` 只关掉那一格 Shell，点「重新打开 Shell」即可。关标签、空闲挂起不会硬续连接。
设置里的「保持心跳」和「自动重连」对应前两层；第三层尊重服务器，客户端不伪造按键。
## 远程桌面（RDP / VNC）
欢迎页或会话入口可打开 RDP / VNC 连接对话框（仅原生桌面应用）：
- RDP：填写主机、端口、用户名、密码与可选域名；原生 IronRDP 引擎，支持剪贴板同步与共享盘（本机下载目录对应远端共享盘）。
- RDP：填写主机、端口、用户名、密码与可选域名；原生 IronRDP 引擎，支持剪贴板同步与共享盘（本机下载目录对应远端共享盘）。画面铺满当前窗口（任务栏贴底），连接时按窗口客户区请求分辨率；窗口缩放后再走 Display Control。
- VNC：填写主机、端口与可选密码；原生 RFB 引擎，剪贴板按 UTF-8 发送。
- 连接后在独立标签中显示画面；工具栏可粘贴本机剪贴板、放入共享盘文件（RDP）或断开。
- 连接后在独立标签中显示画面；工具栏可粘贴本机剪贴板、放入共享盘文件（RDP）或重新连接。标签还开着时网络闪断会有限次自动重连（新会话，不对抗服务器空闲注销）。
- 桌面会话不参与批量命令与终端广播。
## 导入 OpenSSH 配置
@@ -69,7 +85,7 @@ socks5://127.0.0.1:1080
包含 `*`、`?` 或 `!` 的 Host 模式不会生成会话。导入后请检查目标、用户名、密钥路径和跳板关系再连接。
会话导出为 JSON，不包含密码、私钥口令或代理密码；私钥路径会保留，便于在同一台电脑恢复配置。
会话导出默认保存为 `opsxshell-hosts.oxs`（密码加密的主机清单，格式类似 KeePass `.kdbx`、MobaXterm `.mxtsessions`）。旧版 `.bak` 与 OpenSSH `config` 仍可导入。导出包含主机分组、密钥和密码，务必保管备份密码。
## SFTP
@@ -82,7 +98,7 @@ SFTP 使用双栏文件管理器。中间箭头可上传/下载；上传和下
- 当前拖拽只支持单个文件，不递归传输目录；同侧拖拽不会执行移动或重命名。
- 远程文本编辑直接读写远程文件，不会在本地创建同名文件，也不等同于上传或下载。可编辑类型按扩展名排除归档/二进制等；单文件约 **2MB** 上限，超限、二进制或非 UTF-8 会提示并拒绝打开，请下载后用本地编辑器处理。
- 上传/下载若目标已存在同名项，会询问「覆盖」或「跳过」；失败或取消的任务可在传输队列里一键重试。
- SSH 断线后，SFTP 一键重连会优先回到断线前的远程目录；进行中的传输会标为失败，可重试。终端标签本身也支持一键重新连接（及可选自动重连）。
- SSH 断线后，SFTP 会按与终端相同的有限次自动重连，并优先回到断线前的远程目录；进行中的传输会标为失败，可重试。也可一键手动重连。
- 刷新时状态栏显示「正在刷新…」，传输忙时浏览类操作会立即返回忙提示而不是卡住界面。
- 传输失败会在传输队列和界面通知中显示经多语言映射后的原因。
@@ -120,7 +136,7 @@ SFTP 使用双栏文件管理器。中间箭头可上传/下载；上传和下
- 直接输入任务，例如“排查 nginx 为什么启动失败并修复”。回车发送，`Shift+回车` 换行；不需要先选“解释 / 生成命令 / 排障 / 执行”。
- 有终端选区时会作为初始上下文；没有选区时不抓取整屏，Agent 通过真实 `ssh-exec` 自主取证。
- Agent 最多执行 8 步。每步只能准备一条单行命令，界面会显示当前主机、命令和五级风险。默认「宽松」仅高风险命令确认；「严格」从中风险开始确认。critical（格式化磁盘、删除根目录等）始终硬拒绝，后端也会再拦一次。
- Agent 最多执行 12 步。每步只能准备一条单行命令，界面会显示当前主机、命令和五级风险。默认「宽松」仅高风险命令确认；「严格」从中风险开始确认。critical（格式化磁盘、删除根目录等）始终硬拒绝，后端也会再拦一次。
- 格式化磁盘、删除根目录等 critical 命令会被硬拒绝，不提供确认放行。相同命令第 3 次会在执行前拦截。
- 执行后的真实输出和退出码会回给 AI，用于判断下一步或收敛结论。连续失败时 Agent 会被要求换方法。
- 长输出由本地 `analyze_output` 提取错误行并保留首尾；Rust 在发给云模型前做常见敏感信息脱敏。