# 使用指南 安装、更新、卸载的完整流程，以及命令行接口的全部选项。 ## 0.4.0 候选与组件默认值 本检出是未发布候选；验收采用已批准的 OPS 0.3.x BM-01 基线与文件/发现 BM-03 预算，Bash 仍常驻且完整总数另列，见[候选状态](0.4.0发布候选.md)。新 profile 的七行默认开启 file/PTC/discovery，三个平台都开启 shell，panel/TUI/替换关闭；已有显式开关和带名称配置在升级后保留。Native 初始常驻 read_files/discover_tools 及可用 Bash（Windows 为固定载荷，POSIX 为发行版 bash），文档能力按需加载。PTC 有18个类型化 API，使用独立配置池与 SDK 加载器。[配置参考](配置参考.md)说明内置表单和可选浏览器承载行；升级按[手动验收](手动验收.md)复核。 --- ## 前置条件 | 项 | 要求 | | --- | --- | | 操作系统 | Windows x64、Linux x64 或 macOS Apple Silicon（darwin-arm64） | | Node.js | `^22.19 \|\| >=24`（`package.json` 的 `engines`） | | 宿主 | DSH `0.2.0-rc.2` | | 目标应用 | 已初始化 | ### macOS arm64 macOS 没有自带 shell 载荷，原生 worker 也不在任何平台的仓库里，因此多两步。 先在检出目录构建并 stage 一次原生 worker（需要 Rust >= 1.88）： ```console cargo build --release --manifest-path native/Cargo.toml node bin/native-runtime.mjs stage --platform darwin-arm64 ``` 然后在 shell 组件行用 `bashPath` 指向本机已有的 bash： ```yaml - id: dsh-ops-shell name: dsh-ops/shell disabled: false config: bashPath: /opt/homebrew/bin/bash ``` macOS 上桌面应用自带的 CLI 位于其安装包内（`.../Contents/Resources/runtime/cli/bin/dsh`）， 而不是 Windows 的 `%LOCALAPPDATA%` 路径。宿主在 macOS 上不暴露 pwsh 行，因此 PowerShell 7 在 macOS 上不可用。能力矩阵与已知限制见 [macOS arm64](macos-arm64.md)。 --- ## 安装 ### 官方插件市场 在目标 DSH 应用的插件市场中输入 npm 包名 **`dsh-ops`**，安装后选择启用。安装归属于当前运行的 profile，桌面端为 `desktop`。主包把 Windows bash 载荷声明为可选依赖（`@dsh-ops/bash-win32-x64@0.2.1`），Windows x64 安装时自动拉取固定版本的 PortableGit 运行时（GNU bash 5.3.15）；其它平台跳过该依赖，继续使用系统 bash。PowerShell 继续由宿主管理。安装不运行 shell 下载脚本，不改系统 PATH。 ### 可选 Bash 运行时 Windows 上固定版本的 bash 载荷随安装到位；`bash-runtime` 保留为缺失或损坏时的选择与修复路径，可显式安装经过校验的托管副本，或选择已有的 Git Bash： ```console dsh-ops bash-runtime status dsh-ops bash-runtime install dsh-ops bash-runtime git dsh-ops bash-runtime managed dsh-ops bash-runtime remove # 只预览 dsh-ops bash-runtime remove --yes # 只移除有托管收据的版本 ``` `git` 和 `managed` 输出供宿主配置编辑器使用的绝对 `bashPath`，不改 profile 或 PATH。应用选择、安装或移除运行时后重新加载 shell 组件。移除前先停止 Bash jobs；移除会拒绝托管路径中的链接，并保留没有收据的目录、系统 Git 与 PowerShell。`install` 复用 `provision-shells --bash` 的固定下载与校验流程；`--dry-run` 不下载、不写入。Windows 受限模式仍要求固定 MSYS 与 IPC 兼容性匹配；其它 Git Bash 只能用于完全访问模式，审批无法修复不兼容的受限运行时。Linux/macOS 继续使用宿主 Bash。 ### npm 一键安装 ```console npx --yes dsh-ops@latest install --profile desktop npx --yes dsh-ops@latest install --profile web npx --yes dsh-ops@latest install --profile tui ``` 必须显式选择目标 profile；`tui` 映射到 **dsh-TUI 产品的 `dsh-tui` profile**，不是旧的 `tui` 目录。请先初始化目标应用。该入口委托官方 DSH CLI 安装，不另写一套 profile 锁与回滚逻辑。 桌面端必须使用桌面应用自带的 CLI；默认探测 `%LOCALAPPDATA%\Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd`。安装在其它位置时加 `--dsh-cli "<安装目录>\resources\runtime\cli\bin\dsh.cmd"`。Web/TUI 需要可用的 DSH CLI，可同样显式指定。 ### 直接使用官方命令 ```console dsh plugin --profile web add dsh-ops dsh plugin --profile dsh-tui add dsh-ops "<桌面安装目录>\resources\runtime\cli\bin\dsh.cmd" plugin --profile desktop add dsh-ops ``` 普通 DSH CLI 不能管理保留的 `desktop` profile；不要把它与桌面自带入口混淆。 --- ## 更新 重新运行相同的 `npx --yes dsh-ops@latest install --profile ...`，或用官方 CLI `add dsh-ops@latest`。按应用提示重载；替换已加载代码时重启应用。 --- ## 卸载与查看状态 ```console npx --yes dsh-ops@latest status --profile desktop npx --yes dsh-ops@latest uninstall --profile desktop ``` 把 `desktop` 换成 `web` 或 `tui` 即可。也可在市场卸载，或执行官方 `dsh plugin --profile ... remove dsh-ops`。二进制随 profile 的插件依赖管理；卸载移除依赖引用，不误删系统 shell、其它 profile 的副本或包管理器共享缓存。 旧版显式 provision 的 `/dsh-ops/` 文件（provision 的 shell，以及早期版本可 provision 的 FastCtx 运行时）需单独清理：`npx --yes dsh-ops@latest uninstall --yes`。已移除的后台组件留下的 `~/.fastctx/` 状态默认不删；需要时显式加 `--purge-fastctx` 一并删除。 --- ## Windows 宿主 PowerShell OPS 不再捆绑 PowerShell，也不修改宿主 `pwshPath`。Windows PowerShell 5.1、已有的自定义执行器以及旧 OPS 托管副本都保留。安装或升级标准 PowerShell 7 安装前，先查看执行计划： ```console dsh-ops upgrade-host-pwsh dsh-ops upgrade-host-pwsh --yes --dry-run dsh-ops upgrade-host-pwsh --yes ``` 只有 `--yes` 才运行 WinGet；`--dry-run` 始终只预览。该操作精确选择 `winget` 源的稳定版 `Microsoft.PowerShell`，保留 WinGet 的安装器与协议提示，可能要求 Windows 提权。缺少 WinGet 时仅返回操作指引，不尝试安装；详见 [Microsoft 的 Windows 安装指南](https://learn.microsoft.com/zh-cn/powershell/scripting/install/install-powershell-on-windows)。 成功后重启 DSH，让宿主重新探测执行器。显式配置的宿主 `pwshPath` 仍然优先；如它指向其它位置，请在宿主设置中检查。结果 `no-update` 只说明 WinGet 未找到此包的适用更新，不代表全部自定义 PowerShell 副本都是最新版。安装器已启动后取消操作，副作用状态为未知；重试前先检查标准安装。旧命令 `provision-shells --pwsh` 仍保留为显式兼容下载，但 OPS 不会自动启用其副本。 ## 命令行接口 ```console dsh-ops install --profile [--dsh-cli ] dsh-ops uninstall --profile [--dsh-cli ] dsh-ops status --profile Report target-profile installation (tui maps to dsh-tui) dsh-ops build-ptc Build the independent native Rust worker (all platforms) dsh-ops uninstall [--yes] [--purge-fastctx] dsh-ops ladder [--json] [--config ] prompt ladder actually renders; nothing is spawned dsh-ops upgrade-host-pwsh [--yes] [--dry-run] dsh-ops provision-shells [--bash] [--pwsh] [--force] [--dry-run] [--pin ] their digests, and install them under /dsh-ops/shells dsh-ops panel [--serve] [dir] [--port ] Serve the panel viewer and capture reports over loopback ``` With `--profile`, install/uninstall delegate to the official DSH profile manager. Without `--profile`, uninstall only cleans legacy provisioned runtime/shell files. `resolve`、`status`（不带 `--profile`）、`build` 与 `provision` 已随 FastCtx 后台组件移除；调用它们会退出并提示替代命令。 ### 面板查看器 panel 采集行默认关闭；启用后，每个新对话写入 `/.dsh-ops/panel/.json`，并留下不内联数据的静态 `panel.html`。不用再手工拖文件或自己起静态服务： ```console dsh-ops panel # 服务 ./.dsh-ops/panel，只绑 127.0.0.1 dsh-ops panel <采集目录> # 服务其它工作区写出的目录 dsh-ops panel --port 8123 # 固定回环端口；默认 0 由系统分配 ``` 命令会打印 `http://127.0.0.1:<端口>/`，默认打开最新一份有效报告，并列出同目录其它有效报告供切换；`--serve` 是可选的显式别名。服务只绑定回环地址、只读该目录、不写任何文件，并会列出跳过的格式错误文件。采集行本身仍不开端口：只有这条运维命令会起服务。直接用 `file://` 打开 `panel.html` 时仍需拖入 JSON，因为浏览器会拦截同目录 `fetch`；经任意静态服务访问时可在地址后加 `?data=.json`。 采集写在对话自己的工作目录里。提交前请把 `.dsh-ops/` 加入该项目的 `.gitignore`：报告里可能包含提示词、对话文本和工具输出。 ### 环境变量 | 变量 | 作用 | | --- | --- | | `HTTPS_PROXY` | Proxy handed to curl explicitly by provision-shells | | `DSH_OPS_REQUIRE_RUNTIME` | 让 `npm run verify` 要求运行时存在 | | `DSH_OPS_WORKER_BIN` | 选择 worker 构建（否则按 `runtime/-/` → `native/target/release` 顺序解析） | | `DSH_OPS_VCVARS64` | 构建 Bash IPC 代理时需要时提供 MSVC 环境 | --- ## 脚本文件：`command` 与 `script_path` `ops_bash` 的 `command` 适合短命令和短管道。对于超过约 1 KB，或包含 heredoc、引号、反斜杠、中文等内容的多行脚本，请先用宿主的文件工具写入脚本文件，再传入 `script_path` 执行；不要把整段 heredoc 塞进 `command`。这样可以显著减少模型在工具调用 JSON 中进行多层转义的负担，降低整轮因 `MALFORMED_RESPONSE` 作废的概率。 `script_path` 只接收脚本路径，脚本内容不会重复进入 `ops_bash` 的工具参数；`command` 与 `script_path` 必须二选一。该接口不会替模型修复非法 JSON，工具调用本身若未能解析，仍需由宿主或模型重试。 `ops_bash` 必须提供非空 `description`，输入字段和结果类型与宿主 Bash 保持一致：`foreground`、`background` 或 `promoted`。默认超时 120 秒，上限 600 秒。宿主 jobs 服务可用时，`run_in_background: true` 立即返回 job ID；前台等待超时会把同一个运行中任务交给宿主管理。用宿主 `job_output` 收集输出、`job_kill` 停止任务。没有 jobs 服务时不声明后台参数，前台超时会停止命令。未知参数在执行前被拒绝。 `sandbox_permissions` 和 `justification` 可通过宿主审批服务申请更宽的权限。一次批准只作用于当前命令；拒绝后不执行，也不修改会话模式。审批与沙箱准备后都会重新检查会话权限。Windows 如实报告宿主的实际约束级别（包括 `partial`）；不兼容的 Bash 运行时直接拒绝执行。 `script_path`（替代 `command`）、`graceMs` 和 `includeDiagnostics` 是保留的 OPS 兼容扩展，不改变宿主命令契约或超时上限。 --- ## 进程回收 本版本不启动常驻服务进程：原生文件 worker 归 file 组件所有，随组件一同停止。带后台组件的早期版本会启动 `fastctx serve` 客户端，并可能留下共享的 FastCtx `runtime-host`；该进程在无客户端约十分钟后自行退出。新版不清理旧版本留下的进程，也不要按进程名批量杀它们。 --- ## 更新配置修改区 `lib/config-updates.js` 集中维护一次性配置迁移。0.2.5 首次启动时逐个自有配置行执行自检： - 未完成迁移（无 `configUpdateVersion` 或值为 `0`）：把旧 `allowSystemShellFallback: true` 改为 `false`，在任何执行器解析/工具发布前生效。 - 通过官方 loader 的配置生命周期写回该行，并加入 `configUpdateVersion: 1`；保留其它字段，不修改外来插件、PATH 或全局配置。未启用的组件在它首次启动时迁移。 - 完成后重启/热加载不再覆盖；你之后主动改回 `true` 会被保留。不要删除迁移标记，否则会重新自检。 - 没有 loader 配置行时只应用本次运行的安全值并告警；写入失败由迁移/loader 日志报告，未落盘的标记不能保证跨重启一次性。 --- ## 相关文档 - [配置参考](配置参考.md) —— 配置项逐个说明 - [组件参考](组件参考.md) —— 组件与工具列表 - [常见问题](常见问题.md) —— 报错与排查 - [原生 PTC](native-ptc.md) —— PTC 设计与使用 ## Native 文件结果 Native 文件工具以 `=== FILE: path (Lines a-b of n) ===` 和 `N | text`（完整多文件范围使用紧凑 `N|text`，同父目录可共用 JSON 引号路径，见[紧凑范围](紧凑文件范围.md)） 显示内容，并保留路径、已观察到的 revision 与分页提示。PTC 的执行值仍是结构化对象， 使用前须检查 `status` 和完整性。Grep 的上下文行号对应真实源文件；glob 的路径模式 每行显示一个路径。Stat 保留大小、revision 与元数据，diff 显示删除／添加的行； 修改操作只返回简短回执，不重复输出文件内容。 只有物理 LF 才是行边界（CRLF 只算一个）。空文件有零行，末尾 LF 不产生额外空行； 单独 CR 和 Unicode 分隔符不增加行数；显示时转义控制分隔符，避免拆开带行号的一行。写入保留原始字节和换行符。非法 UTF-8 或 不支持的文本编码返回 `ERR_INVALID_ENCODING`，建议使用专用文档／二进制读取工具或 `view: "hex"`，不会用乱码替代非法字节。 Native 内容块经 JSON 转义后最多 64 KiB。截断显示明确标记 `Display incomplete` / `TruncatedBy: output-budget`；应缩小原始读取范围，不能跳过尚未显示的内容。 单行截断无法通过下一行偏移恢复尾部，须用 hex 字节行读取。修改回执显示被截断时， 应先检查当前状态，不能为了获取回执重复写入。错误提示在可能很长的诊断文字之前 显示副作用状态与重试指引。