dsh-pi-compatible: Pi 工具组契约复刻插件

DeepSeek Harness (DSH) 的核心优势在于其插件化架构和强大的扩展能力。有时，开发者需要复刻特定 Agent（如 Pi）的核心工具交互契约，同时保留 DSH 自身的后端能力（如文件系统、会话管理等）。dsh-pi-compatible 插件正是为了解决这一需求而生。它复刻了 Pi 工具组的 Agent Preset，提供了一套小写核心工具契约，并支持扩展版本，同时底层仍由 DSH 驱动。

核心功能¶

该插件提供两个预设：Pi-compatible Core 和 Pi-compatible Plus。

Pi-compatible Core¶

该预设复刻了 Pi 0.84.2 的核心工具契约，默认暴露七个核心工具。这些工具的命名风格与 Pi 保持一致，但行为由 DSH 实现。

read: 读取文件，支持偏移量和行数限制，最大 64 MiB 安全上限。
bash: 执行 Bash 命令，每次调用创建新进程，无持久状态。
edit: 编辑文件，支持模糊标点回退，保留 BOM 和换行符格式。
write: 写入文件，自动创建父目录。
grep: 基于 ripgrep 的搜索，支持 JSON 输出和上下文控制。
find: 基于 fd 的搜索，支持 glob 模式和 .gitignore 忽略。
ls: 列出目录内容，包含 dotfiles，支持不区分大小写的排序。

Pi-compatible Plus¶

在 Core 的基础上，Plus 预设增加了 DSH 后端支持的扩展工具，包括：
* WebFetch
* WebSearch
* Task
* TodoWrite
* ExitPlanMode
* Think
* SlashCommand
* /plan
* /compact
* 以及 DSH 的基础压缩和工具结果剪裁功能

底层能力¶

上述工具均使用 DSH 的底层能力构建，包括：
* filesystem: 文件读写与目录操作
* subprocess: 子进程管理
* attachment: 附件处理（支持 PNG, JPEG, GIF, WebP, BMP 等）
* session: 会话管理
* cancellation: 取消操作
* model-routing: 模型路由
* presentation: 展示能力

安装与启用¶

安装该插件需要使用 DSH 的 Web profile。

执行安装命令：

    dsh plugin --profile web add kingguuu8-svg/dsh-pi-compatible

或者安装本地检出的代码：

    dsh plugin --profile web add .

安装完成后，插件会解压到 ${DSH_HOME:-~/.dsh}/.agent-presets/pi-compatible/ 目录。该安装过程是幂等的，不会覆盖已存在的完整预设。
创建新会话，并在预设列表中选择 Pi-compatible Core 或 Pi-compatible Plus。

运行时配置¶

插件依赖部分外部工具和配置项。以下环境变量可用于控制行为：

PI_COMPAT_BASH_PATH: 指定真实的 Bash 可执行文件绝对路径。
PI_COMPAT_FD_PATH: 指定 fd 工具的绝对路径。
PI_COMPAT_RG_PATH: 指定 rg (ripgrep) 工具的绝对路径。
PI_COMPAT_OFFLINE=1: 禁用 fd 和 rg 的网络下载。
PI_OFFLINE=1: PI_COMPAT_OFFLINE 的别名，同样禁用网络下载。
DSH_HOME: DSH 的主目录，同时也是私有 pi-compatible/bin 缓存根目录。

工具解析策略：
* Bash: 优先使用 Git Bash (Windows 下)，其次是 PATH 中的 Bash，最后是缓存目录中的版本。
* fd/rg: 优先级为环境变量 > 系统路径 > 缓存目录 > GitHub 最新发布版本（除非处于离线模式）。

权限与信任¶

该插件仅支持 danger-full-access 权限预设。它不会实现针对更窄权限策略的升级工作流。

信任声明: 该插件包含可执行任意 Bash 命令和修改任意文件的权限。作为用户 Preset，它拥有所加载插件的权限。建议在安装前审查源码。
Windows 平台: Windows 是发布阻塞平台。
Pi 基线: Pi baseline 永久冻结为 0.84.2。
兼容性边界: 兼容性指模式和关键行为，不要求字节级错误消息或 TUI 渲染完全一致。DSH 保留了路径授权、文件系统发布、进程树取消等核心控制权。

生态与链接¶

许可证: MIT
目录页: SkillHub - dsh-pi-compatible
源码: GitHub - kingguuu8-svg/dsh-pi-compatible