常驻 PowerShell 工具 Elevator14B/dsh-all-in-pwsh

dsh-all-in-pwsh

一个 DeepSeek Harness 智能体预设：只给模型一个工具——常驻 PowerShell 7 shell——其余所有已挂载的工具都从这个 shell 内部暴露出来，变成可复用的 PowerShell 工具对象，每次调用返回一个结果对象。

维护者：Huanqi Cao。已在 Windows 11 上测试，PowerShell 7.6.5（预设自己的常驻 shell 报告的版本），对接 DeepSeek Harness 桌面运行时 0.1.6-alpha.1.20260917.2。

它做什么

- 模型只看得见一个工具。 线上目录里只有 pwsh。其余所有已挂载的工具都直接对模型禁用，改由预设根据实时目录生成的参考文档列出。
- 先发现，再通过对象调用。 Get-DshTool 列出目录（名称加一行摘要）。Get-DshTool -Name <name> 取一次定义，返回可复用对象；打印它会显示参数、返回契约和一段简短的验证过的示例，把变量留着，后面的代码块就能再次调用。属性访问是本地行为：不会和桥接通信。

Get-DshTool # catalog: name and summary
$read, $write = Get-DshTool -Name read, write # reusable tool objects
$read # parameters, return contract, example

$source = $read.Invoke(@{ file_path = 'orders.json' })
$orders = $source.Value.Text | ConvertFrom-Json # complete file text
$source.DisplayText # presentation only

- 每次调用返回一个结果对象。 字段有 Ok、HasValue、Value、Content、DisplayText、Error 和 Metadata。打印时显示有界预览加一行状态；赋值则保留结构化字段。空数组和单元素数组保持原形状，字符串仍是字符串，键存在但值为 $null 与键不存在是两回事。对象键保留原拼写；点号访问不区分大小写，除非键之间只差大小写，这时用精确键索引可同时保留两者。整数尽量解码为 Int64，其次 Decimal 或 Double；不承诺跨 JSON 边界的任意精度。
- 读取会返回所请求范围内的完整数据。 预设会在会话的注册表层注册自己的 read 操作，因此当没有请求范围时，工具自身产生的值就是整个解码后的文件；或者恰好是所请求的 offset/limit 范围：.Value.Text 加上 .Value.lines 中逐行相同范围的内容（未截断，无终止符），旁边还有 .Path、.Offset、.Limit、.EndLine 和 .TotalLines。打印出的文本是同一个服务商读取结果的有界预览；它绝不会截断 .Value。超过配置的 readFullMaxBytes 的整文件读取会以服务商的 FS_TOO_LARGE 失败，文本超过该值的显式行范围会以一条消息失败，两者都不返回前缀。
- 原生 PowerShell 参数。 参数是哈希表、有序字典或 PSCustomObject——绝不是 JSON 文本，绝不是参数文件：

$write.Invoke(@{
file_path = 'C:\work A\note.txt'
content = @'
中文 "quoted", O'Brien & Sons, $var and a backtick: tick C:\folder\file.txt '@ })

单引号 here-string 以 @' 开头，后跟换行，并以 '@ 结束，位于自己行的开头。其中的引号和反斜杠是字面量。Invoke-DshTool -Name ... -Arguments ... 和 dsh-tool 别名仍是便捷入口点，返回相同的结果对象；-PassThru 被接受，不改变任何东西。
- 失败会停止块，或显式分支。 预设的 shell 默认为 $ErrorActionPreference = 'Stop'，因此失败的 .Invoke 会终止语句，依赖的写入不会在缺失数据上运行。当失败是预期分支时，.TryInvoke(@{ ... }) 返回相同的结果对象，其中 Ok = false 和结构化的 Error（kind、code、message、tool、parameterPath）。放宽错误策略的调用方显式放弃停止保证。
- 一切仍然通过工具注册表运行。 桥接调用是嵌套的工具执行，携带原始 exec 上下文，因此审批、取消、作用域和会话日志的行为与任何其他调用一样，Web 对话将它们渲染为 PTC 风格的子调用行。全文读取通过注册的文件系统服务商（ctx.fs）完成，因此沙箱执行、取消和服务商错误仍然适用。
- 定义不会静默过期。 每个工具对象携带定义指纹；如果定义已更改，调用会在执行前被拒绝，并指明 Refresh()。句柄可在创建它的会话的各个块之间重用，不能用于另一个会话或桥接实例。
- 每次执行的身份。 在每个 shell 命令之前，宿主将新的调用 id 和能力写入该 shell 的环境，并在命令结束时撤销它们，因此由较早命令启动的后台进程会被拒绝，而不是继承较晚命令的身份。

Install

powershell
git clone https://github.com/Elevator14B/dsh-all-in-pwsh
cd dsh-all-in-pwsh
pwsh -NoProfile -File ./install.ps1

安装器会先暂存并校验这个包，再把它装到 <DSH home>/.agent-presets/dsh-all-in-pwsh，同时把装好的 bootstrap 路径替换进组合里。它绝不会碰你的全局 PowerShell 配置档。

- 换一个 home 或 id：./install.ps1 -DshHome C:\dsh -PresetId my-preset
- 更新：再跑一次就行。你在预设里新增或改动的文件会保留为 <id>.backup-<timestamp>-<unique>。
- 卸载：./install.ps1 -Uninstall，同样会保留你的改动。
- 不是安装器创建的目录，它一律不动，除非你传 -Force；外来目录它绝不占用；校验失败的包不会影响正在用的安装。

然后启动宿主，为新会话挑这个预设： powershell
dsh web --port 8080

测试

免账号检查——不需要 DSH 宿主，不需要模型，不需要网络。103 项 PowerShell 检查覆盖参数保真、工具与结果对象、目录拒绝处理、JSON 解码、失败分支、句柄标识与定义变更、bootstrap 默认值、安装器归属与回滚、README 片段解析，以及仓库卫生。另有 12 项检查覆盖宿主插件的按智能体串行队列。
powershell
pwsh -NoProfile -File ./tests/unit/run.ps1 # objects + module contract + installer + hygiene
node ./tests/unit/serial-locks.mjs # per-agent serial queue cleanup
pwsh -NoProfile -File ./tests/unit/mutations.ps1 # optional: each installer check must catch its regression

最后一项是对检查本身的检查：它一次往 install.ps1 的临时副本里加一个小回归，如果测试套件没发现就判失败。它比较慢，所以不在默认运行范围内。

集成检查会启动真实的 DSH 运行时，用装好的预设对着一个临时 DSH home 跑。冷启动探针覆盖首次使用和预热并发，对象探针端到端覆盖对象与读取契约（小文件、超过 2000 行、单行超过 2000 字符、超过 50 KiB、空文件、CRLF/Unicode 以及显式范围读取时，.Value.Text 与磁盘上的文件比对；FS_TOO_LARGE；offset 越过 EOF；Invoke 失败后不留任何依赖写入；TryInvoke 各分支；跨块复用句柄；定义漂移与 Refresh()；提示词里的示例逐字执行；图片内容留在自己的通道），生命周期探针覆盖调用超时存活、取消和中止，以及按 shell 的锁，模型探针则端到端驱动真实工具调用： powershell
node ./tests/integration/run.cjs # cold + objects + lifecycle
node ./tests/integration/run.cjs --with-model # adds the model-backed acceptance probe
运行器会自动检测当前用户本地应用数据目录下的桌面运行时。设置 DSH_PROBE_RUNTIME 和 DSH_PROBE_EXE 可以指向另一个构建；没有运行时它会打印 SKIP 并以 0 退出。

模型探测是唯一需要模型路由的探测，也是 --with-model 把 settings.yaml 和 .credentials.yaml 复制进一次性 home 的唯一原因。探测退出时这些副本会被删除，无论通过还是失败。

兼容性

对象 API 改变了之前的返回约定：Invoke-DshTool 始终返回结果对象，包括不带 -PassThru 时。它的 .Text 别名表示显示文本；文本读取的数据要用 .Value.Text。Get-DshToolSchema 现在返回结构化 schema 对象，不再是 JSON 字符串。无参数的工具调用 .Invoke(@{})；.Invoke() 不是重载。其他工具保持各自声明的值形状；缺少输出 schema 并不意味着存在 .Value.Text 属性。

- 仅支持 Windows 加 PowerShell 7。在其他环境预设会拒绝挂载，而不是半可用。
- 预设复用官方 dsh-terminal-bash PTY 后端，配 shellDialect: pwsh；不修改也不替换任何 DSH 包。
- 读取约定由预设注册进会话自身注册表层的 read 操作补全，因此它只在该会话内遮蔽挂载的工具，同时保留其分发、守卫、权限、取消、fs/observed 观测和 UI 卡片。它只用已注册的文件系统服务商操作（ctx.fs.resolve、stat、readBytes、streamText）；预设自己从不读取文件。读取未挂载、或被限制掉的会话不受影响，注册失败会抛出，而不是静默提供窗口化读取。
- 它需要 DSH 构建的运行时暴露它用到的扩展点：system-prompt/assemble 瀑布、systemPrompt.section、tools.guard、tools/execute 瀑布、ctx.tools.get/schemas/execute 和 ctx.terminals.list/startSend。随附的桌面和 web 配置档都具备。

结构与行为边界

preset/preset.yml display metadata
preset/agent.cordis.yml the agent composition (bootstrap path is a placeholder)
preset/plugin/dsh-all-in-pwsh.mjs host plugin: catalog collapse, guard, bridge, lock, read contract
preset/plugin/DshCli.psm1 the PowerShell tool and result objects
preset/plugin/DshCli.format.ps1xml display views for the object types
preset/plugin/bootstrap.ps1 imported by the persistent shell at startup (sets the Stop policy)
install.ps1 install / update / uninstall
THIRD-PARTY-NOTICES.md what is adapted from DeepSeek Harness, and its MIT notice
tests/unit/... no account needed
tests/integration/... needs the real DSH runtime

- 面向模型的参考信息在每次组装提示词时，都从实时目录生成，所以它始终与当前会话实际拥有的工具一致。它只列出名称和摘要；参数与 schema 通过打印工具对象来披露。
- 桥接监听回环地址，每个实例的 token 存放在 DSH home 下（访问权限由 Windows 文件系统权限控制）。机器上任何能读到该文件的进程都能访问桥接；这是本地开发者工具，不是多租户设计。
- 只有仍在运行的 shell 命令才能调用工具。后台进程保留它继承的身份；命令一旦结束，身份即被撤销，其调用会被拒绝。
- 同一个 shell 中的命令串行执行；不同会话与主机并行运行。
- 这里的一切都不会改动 DSH 本身，安装器也绝不会编辑你的全局 PowerShell 配置档。

故障排查

失败是结构化的。$result.Ok 为 false，$result.Error 指明分组；抛出的失败会先打印一行 [dsh] FAILED <tool> (kind=..., code=..., parameter=...): <message>，然后代码块停止，所以即使命令包装器吞掉了终止性错误，原因依然可见：

1. 参数无效（在任何请求之前 kind = Bridge，或由模块抛出）：传了 DateTime 而不是 ISO-8601 字符串、字典键不是字符串、出现循环引用，或嵌套超过 48 层的 JSON 预算。消息会指明参数路径和出错的类型。
2. 桥接或主机拒绝（kind = Bridge 或 kind = Host）：桥接不可达，执行身份缺失或已被撤销（IDENTITY_REVOKED），工具对象属于另一个桥接实例或会话（HANDLE_INSTANCE_MISMATCH / HANDLE_SESSION_MISMATCH），或定义已变更（kind = DefinitionChanged，其中会指明 Refresh()）。派发之后的连接失败会以 Metadata.outcome = 'unknown' 报告：操作可能已生效，也可能没有，且绝不会自动重试。
3. 已执行工具的失败（kind = Tool）：调用已运行，工具失败。读取不存在的路径会报告服务商的 FS_NOT_FOUND；整文件读取超过配置的字节上限会报告服务商的 FS_TOO_LARGE；显式指定行范围、但其文本超过该上限时会失败，消息中不带 code。TryInvoke 返回这些错误而不终止，而执行被撤销的控制流即使在 TryInvoke 中也会抛出。

其他症状：

- dsh-all-in-pwsh is not active in this shell —— 该命令不在预设的 shell 调用中运行，例如由更早的命令启动的后台作业。请在前台运行它。
- 失败的调用之后仍执行了依赖的写操作 —— shell 的错误策略被放宽了。预设会在启动时设置 $ErrorActionPreference = 'Stop'；脚本若设为 Continue，就放弃了停止保证，应改用 TryInvoke。
- 代码块只以退出码结束 —— 每次抛出的失败都会先打印自己的 [dsh] FAILED ... 原因行，诊断依据是这一行，而不是退出码。代码块内原生命令失败时，仍然通过它自己的 stderr 和 $LASTEXITCODE 上报。
- 某个参数似乎没有生效 —— harness 会把插件的参数编译进一个隐式开放的对象根，因此工具的 InputSchema 没有声明的名字会被忽略，而不是被拒绝。预设会在调用运行前打印 [dsh] WARNING <tool> ignores undeclared argument(s): <names> (declared: <names>)，并且仍然执行这次调用。如果工具用 additionalProperties: false 关闭了自己的根，harness 本身就会拒绝它，上面的失败行会报告这一点。
- 选择器里找不到预设 —— 检查 <DSH home>/.agent-presets/dsh-all-in-pwsh/agent.cordis.yml 是否存在，以及宿主是否按你预期的方式解析 <DSH home>（DSH_HOME）。
- 预设挂载失败 —— 挂载错误会指出是哪一行。常见原因是 DSH 构建版本早于上面列出的扩展点。
- Get-Command dsh-tool 报告的是 Application 而不是 Alias —— PATH 上有另一个 dsh-tool。把它删掉；在预设 shell 里应该由模块别名胜出。

License

MIT，Copyright (c) 2026 Huanqi Cao。预设组合改编自 DeepSeek Harness 随附的智能体预设，后者采用 MIT 协议，Copyright (c) 2026 DeepSeek；见 THIRD-PARTY-NOTICES.md。