58 lines
7.4 KiB
Markdown
58 lines
7.4 KiB
Markdown
# Agent 命令执行环境
|
|
|
|
设置 → 通用 → 命令执行环境。当前接入 OMP 命令工具，独立于系统默认终端窗口；不修改 Windows Terminal、系统环境变量或其他软件的配置。
|
|
|
|
## 使用
|
|
|
|
1. 选择自动检测、Git Bash、PowerShell 7、Windows PowerShell、CMD 或自定义路径。
|
|
2. 自定义模式填写 Shell 可执行文件的绝对路径，也可通过“浏览”选择。接受 bash、sh、zsh、pwsh、powershell、cmd；不接受 Windows Terminal 等窗口启动器。
|
|
3. 选择后自动验证并保存；自定义路径在失焦、按 Enter 或浏览选择文件后保存。程序实际执行固定的验证命令，验证成功才持久化；路径不存在、无法启动、执行失败或超时会显示错误，保留原来的已保存配置。界面不显示额外保存按钮、正常状态说明或检测出的路径。
|
|
4. 下一次发送消息时应用新的配置。运行中的回合继续使用启动时的 Shell，不因保存设置重启或中断。
|
|
|
|
自动检测依次尝试 Git Bash → PowerShell 7 → Windows PowerShell → CMD，跳过不存在或验证失败的候选。探测结果显示实际可执行文件路径；每次新回合还会检查是否可用。指定类型不可用时直接提示错误，不悄悄改用其他类型。
|
|
|
|
## 实现约束
|
|
|
|
- SQLite 设置键 `execution_shell` 存储模式和自定义路径；保存命令只写偏好，不触碰正在运行的内核配置。
|
|
- 在 OMP 回合准备阶段解析 Shell，将实际路径/类型加入内核配置标识，变更时在空闲边界重启并恢复当前会话。
|
|
- OMP 启动时加载 Ygent 私有的 `omp-profile/ygent-shell.yml`，追加实际 Shell 和语法的系统指令。关闭登录 Shell/PowerShell profile 加载，使探测与执行使用相同环境。
|
|
- 本机 OMP 的普通 `bash` 工具实际使用内置 POSIX 解析器，单独设置 `shellPath` 无法执行 PowerShell 语法。因此显式加载 `ygent-shell-adapter.mjs`，在 `tool_call` 中将原始命令作为单个参数安全引用，再调用所选 Shell。仍走 OMP 原有执行、授权、流式输出、超时与取消链路，不另设绕过授权的执行工具。
|
|
- Windows 可执行文件路径统一使用反斜杠，避免 OMP 对 CMD 正斜杠路径的错误解析。CMD 命令写入随机临时目录中的 UTF-8 `.cmd` 脚本，以保留引号、多行和中文；脚本在本次工具结果或会话关闭时清理。
|
|
- 具名后台服务（`bash` 的 `name`）自身使用 `shellPath` 启动，不重复包装。其他工具与 Skill/MCP 调用不改写。工具详情可能显示包装后的实际执行命令。
|
|
- 当前仅接入 OMP；直连模式及 Codex 底座不应用此选项。
|
|
|
|
## 验收 SOP
|
|
|
|
按 [原生调试 SOP](ygent-debug.md) 启动 WebView2 CDP 9335，在临时真实会话验收，完成后恢复原会话与设置。截图/会话输出放用户私有目录，不能提交凭证、真实聊天内容。
|
|
|
|
1. 在设置页检查六种选择、路径输入、验证反馈与重新打开后的持久化。使用无效路径确认保存失败且旧配置保留。
|
|
2. 选择 PowerShell，在真实命令工具中执行 `$PSVersionTable.PSVersion` 和 `(Get-Process -Id $PID).Path`，核对实际版本/路径；不能用设置页“已验证”代替内核调用验收。
|
|
3. 执行带等待的命令，在工具仍运行时保存另一种 Shell，确认 OMP PID 不变、当前命令仍返回旧 Shell 的输出。结束后下一回合检查新 Shell 的语法与实际输出。
|
|
4. 自定义有效路径与对应预设应产生相同执行环境；自定义不存在的路径必须拒绝。Git Bash 未安装或损坏时显示失败。
|
|
5. 检查六档字体的 computedStyle、控件矩形和 scrollWidth；长路径需换行，不得撑宽设置页。
|
|
6. 编译前端、执行 Rust 测试并编译桌面程序。更换 OMP 二进制版本后重新验证工具 hook、参数引用及具名后台服务行为。
|
|
|
|
## 2026-10-09 验收记录
|
|
|
|
- 真实 Tauri WebView2：六种选项展示、Windows PowerShell 点击保存、无效自定义路径错误及旧偏好保留通过。六档字体无横向溢出。
|
|
- 后续简化设置页：移除正常状态说明、路径展示和保存按钮，真实 UI 验证选择 Windows PowerShell 自动持久化、无效自定义路径保留旧偏好并显示错误、恢复自动检测成功。
|
|
- 自动检测跳过本机损坏的 Git Bash 启动器，找到 PowerShell 7。真实 OMP 命令返回 PowerShell 7.6.5 的版本及进程路径。
|
|
- Windows PowerShell 真实语法执行返回 5.1.26100.9444；等待 12 秒期间保存 CMD，OMP PID 保持不变，当前命令成功以原 Shell 完成。
|
|
- 新回合使用 CMD，真实 OMP 工具返回 COMSPEC 和 Windows 版本；命令适配器搭配同版本 OMP 原生 Shell 验证环境变量、双引号、单引号、多行与中文，全部通过。具名服务及其他工具未被该 hook 包装。
|
|
- 前端生产编译、TypeScript 检查、Rust 桌面编译及 35 个 Rust 测试通过。
|
|
- Git Bash 本机安装缺少 `usr/bin/bash.exe`，未验收实际 Bash 命令；其验证失败路径已确认。具名后台服务不重复包装，但完整后台生命周期尚未单独验收。
|
|
|
|
## 2026-10-12：重复包装与失败重试修复
|
|
|
|
真实 bundled OMP 18.6.3 的隔离对照确认：普通 `bash` 仍经内置 POSIX 执行器，不能删除所选 Shell 的适配。原始 PowerShell 脚本经过一层包装可正常执行；把已包装的历史参数重新作为脚本提交会形成嵌套，并产生 `-NoLogo` 等意外标记错误。内存中的下一次模型请求仍保留原始参数，但持久会话恢复后，模型上下文会读到保存的执行包装。两种路径不能混为一谈。
|
|
|
|
修复入口为 `src-tauri/src/shell-adapter.mjs`，由 `shell::adapter_in` 写入每个隔离 profile，保留实际 Shell、取消、超时、输出和授权链路：
|
|
|
|
- 在通用 `context` hook 中，仅克隆并还原助手 `bash` 调用中与本回合 Shell/参数精确匹配的完整单参数包装。不修改持久审计文件、工具结果、其他工具或具名后台服务，不依赖渠道协议。
|
|
- 工具启动前同样去除可严格验证的重复包装，最多还原八层，然后仅包装一次。不解析任意 Shell 表达式；带其他标志、管道或重定向的脚本不能被当作自身包装去除。
|
|
- CMD 的历史包装指向已清理的临时脚本，无法据路径重建原始内容。明确要求重新提供原始 CMD 脚本，不能重放未知临时文件。正常 CMD 的中文、多行和结果后清理仍保留。
|
|
- 同回合、同 cwd 的同一原始命令失败两次后，结果保留原错误并补充诊断提示；失败三次后拒绝第四次原样尝试。换用实际不同的诊断/修复命令仍可执行。计数按内核实例及回合隔离，成功清除相应失败计数，迟到和重复结果不累加。
|
|
- 限次不代表任务完成、取消或通过，不新增人工授权。缺少前置条件时沿现有员工与经理协作处理。它只约束同一命令的重复失败，不宣称能识别所有等价命令或所有无效诊断循环。
|
|
|
|
回归入口：`cargo test --lib --manifest-path src-tauri/Cargo.toml shell::tests -- --test-threads=1` 检查实际生成模块；`scripts/shell-adapter-native-check.mjs` 使用隔离 profile、真实 OMP 与本机受控 SSE，验证原始命令、历史包装、上下文恢复、真实输出及非零退出。私有证据不进仓库；本节源码修复不表示已替换正在运行的用户进程。
|