dsh-ops 0.0.0-stage → 0.2.1

package/cordis.patch.yml

@@ -0,0 +1,160 @@
+# ============================================================================
+# dsh-ops — DSH bundle patch
+# ============================================================================
+# This is the plugin's "mount declaration". DSH applies every bundle patch in
+# the profile's `dsh.profile.bundles` order at startup; this file inserts the
+# dsh-ops row into that tree.
+#
+# Install:
+#   dsh plugin --profile desktop add <path to this package>
+#   dsh plugin --profile web     add <path to this package>
+#
+# The row's config is validated by lib/config.js; every key below is optional
+# and the values shown are the defaults. An unknown key fails the plugin at load
+# rather than being ignored.
+# ----------------------------------------------------------------------------
+
+- insert:
+    - id: dsh-ops
+      name: dsh-ops
+      config:
+        # Absolute path to the FastCtx executable. When set, the plugin hosts
+        # exactly this file and fails loud if it is unusable.
+        # binaryPath: 'C:\path\to\fastctx.exe'
+
+        # The FastCtx server's own name, used to attribute the server
+        # instructions this plugin publishes as a prompt section. The model
+        # never sees it: this plugin speaks MCP to the server it spawns itself
+        # and registers every tool under its own ops_<tool> name.
+        serverName: fastctx
+
+        # Deployment opt-in only. Command/job tools are published per session
+        # only when sandboxPolicy.resolve() reports danger-full-access.
+        enableShellTools: true
+
+        # Per-call deadline for one FastCtx tool call, in milliseconds.
+        toolCallTimeoutMs: 300000
+
+        # Fail plugin activation when the FastCtx server cannot start. Keep
+        # false so a missing runtime degrades to "prompt policy only" instead of
+        # taking the plugin down.
+        required: false
+
+        # 'advise'   — inject the prompt policy only.
+        # 'deny-host-shell' — additionally refuse the host shell tools below at
+        #                     the tools/pre-execute gate.
+        shellPolicy: advise
+
+        # Host tool names refused under 'deny-host-shell'.
+        deniedHostTools:
+          - pwsh
+          - bash
+          - pwsh_persistent
+
+        # Inject the repository-tooling prompt section.
+        promptPolicy: true
+
+        # ---- L2: the plugin's own bash -------------------------------------
+        # Absolute path to the bash this plugin runs `ops_bash` through. When
+        # set, the plugin runs exactly this file and refuses the rung when it is
+        # unusable; leave it unset to search the plugin's own bundled copy
+        # first, then PATH, then the well-known Git for Windows locations.
+        # bashPath: 'C:\Program Files\Git\bin\bash.exe'
+
+        # Layer 2: preferred executor for general commands, pipelines and scripts.
+        # Requires a resolved bash, host subprocess and session full access.
+        publishBashTool: true
+
+        # Fall back to a system-installed bash when the plugin carries no copy
+        # of its own. Set false to confine the bash rung to plugin-provided
+        # shells. (L3 needs no such switch: whether the host's pwsh row runs
+        # the plugin's own pwsh is decided by the executable's presence — see
+        # the L3 override below.)
+        allowSystemShellFallback: true
+
+# ----------------------------------------------------------------------------
+# L3: run the host's pwsh tool on the plugin's own PowerShell 7.
+#
+# WHY ONE LINE IS ENOUGH. `pwsh-local`'s Config owns a `pwshPath` field
+# ("Explicit pwsh executable", packages/shell/pwsh-local/src/index.ts:71-77),
+# and `pwsh-sandbox` inherits it verbatim because it declares
+# `type Config = LocalConfig` (packages/shell/pwsh-sandbox/src/index.ts:40).
+# Pointing this row at the plugin's executable therefore gets the bundled pwsh
+# 7 under the host's sandbox, credential scrub, and output governance with no
+# custom executor and no patched internals.
+#
+# WHY IT CAN EVALUATE TO `undefined` — and that is the safe answer. The row's
+# `pwshPath` default is `undefined`, and `undefined` means "resolve a pwsh the
+# official way" (PowerShell 7 install, PATH, Windows PowerShell 5.1;
+# packages/shell/pwsh-local/src/resolve.ts:67-79). The expression keeps exactly
+# four guards:
+#
+#   1. the platform gate, matching the row's own `disabled` gate: this override
+#      is meaningless off Windows, where `pwsh-sandbox` is not mounted;
+#   2. an existence check over the SAME THREE PLACES, IN THE SAME ORDER, as the
+#      plugin's own probe in `lib/shells.js` (`PWSH_LAYOUT_ORDER`): first the
+#      provisioned store, `<DSH_HOME>/dsh-ops/shells/pwsh/<version>/bin/pwsh.exe`
+#      (what `dsh-ops provision-shells` installs, and the copy the plugin
+#      prefers), then `@dsh-ops/pwsh-<platform>-<arch>` with the shell at
+#      `bin/pwsh.exe` (a deployment that installed the platform package), then
+#      the vendored `vendor/pwsh/<platform>-<arch>/pwsh.exe` (a checkout that
+#      carries its own copy). Keeping the order identical is what makes the
+#      ladder's L3 and the host row the same fact rather than two guesses;
+#   3. a `lstat`-based usability test, so a Windows Store execution alias (a
+#      symlink whose target is not statable) counts, while a directory named
+#      `pwsh.exe` does not — the same rule `resolveShells` applies;
+#   4. a wrapping `try`/`catch` around the whole body, plus a `try` each for the
+#      store scan, the plugin-package resolution, and the platform-package
+#      resolution: an absent store, an unresolvable package, and a malformed
+#      manifest alike may not fail the boot. The store scan sits outside the
+#      plugin resolution on purpose — a provisioned copy is an absolute path
+#      under `DSH_HOME`, so a profile whose `baseUrl` cannot resolve `dsh-ops`
+#      still gets it rather than losing the rung.
+#
+# The store scan picks the greatest version name that holds the executable —
+# the identical comparison `provisionedShell` makes in `lib/shells.js`, which is
+# why it is one expression rather than a version list repeated here. The store's
+# root mirrors `dshHome` there too: `DSH_HOME` when the deployment names one,
+# `~/.dsh` otherwise.
+#
+# Until one of those three places actually carries the executable, the
+# expression yields `undefined` and the host row is left completely untouched.
+#
+# "Installed means used" is the point of the rung: a deployment that carries
+# the plugin's pwsh 7 wants the host's pwsh tool to run it, not the machine's.
+# A deployment that does NOT want this rewrite removes or edits this patch
+# entry in its OWN profile `cordis.patch.yml` — that layer applies after every
+# bundle layer (docs/user/develop/basic/publish.md:118-130), so it has the last
+# word. There is deliberately no plugin config key for it: a bundle patch is
+# evaluated before any dsh-ops row is mounted (the Loader defers a row's `!!js`
+# interpolation until that row's own injections are active), so a config key
+# could not reach this expression, and a key that pretends to is a ladder that
+# lies about the row it never changed.
+#
+# `!!js` SCOPE, VERIFIED IN THE VENDORED LOADER. The Loader evaluates these
+# expressions as `with (ctx) { return eval(expr) }`
+# (vendor/loader/src/config/utils.ts:5-9), so bare `baseUrl` (the owning config
+# tree's base URL) and `ctx` are both in scope — the same convention the shipped
+# bundle uses at packages/bundle/web-app/presets/cordis.patch.yml:147.
+# `dsh-ops` is a dependency of the profile, so
+# `createRequire(baseUrl).resolve('dsh-ops/package.json')` finds the package
+# whether it was installed as a link or from the registry.
+#
+# WHOLE-OBJECT REPLACEMENT — AUDITED, NOT ASSUMED. A patch replaces the target
+# row's ENTIRE `config` object rather than deep-merging it
+# (docs/user/develop/basic/publish.md:129), so every non-default field of the
+# target must be restated here. The base row this targets is
+# packages/bundle/base/cordis.patch.yml:241-243:
+#
+#     - id: pwsh-sandbox
+#       name: '@deepseek-ai/dsh-pwsh-sandbox'
+#       disabled: !!js process.platform !== 'win32'
+#
+# It declares NO `config` at all, and this patch writes only `config` (the
+# row's `name` and its platform `disabled` gate are untouched), so there is no
+# non-default field to restate and nothing is silently dropped. If the base row
+# ever gains one, it must be restated here.
+# ----------------------------------------------------------------------------
+- id: pwsh-sandbox
+  config:
+    pwshPath: !!js "(() => { if (process.platform !== 'win32') return undefined; try { const builtin = (name) => process.getBuiltinModule(name); const fs = builtin('node:fs'); const nodePath = builtin('node:path'); const win = process.platform + '-' + process.arch; const usable = (file) => { try { const stat = fs.lstatSync(file); return stat.isFile() || stat.isSymbolicLink(); } catch { return false; } }; const named = process.env.DSH_HOME; const home = typeof named === 'string' && named.trim() !== '' ? nodePath.resolve(named) : nodePath.join(builtin('node:os').homedir(), '.dsh'); const layouts = []; try { const store = nodePath.join(home, 'dsh-ops', 'shells', 'pwsh'); const versions = fs.readdirSync(store, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort().reverse(); for (const version of versions) layouts.push(nodePath.join(store, version, 'bin', 'pwsh.exe')); } catch {} try { const requires = builtin('node:module').createRequire(String(baseUrl).replace(/[^/]*$/, 'noop.json')); const dir = nodePath.dirname(requires.resolve('dsh-ops/package.json')); try { const pluginRequire = builtin('node:module').createRequire(nodePath.join(dir, 'package.json')); const pkg = nodePath.dirname(pluginRequire.resolve('@dsh-ops/pwsh-' + win + '/package.json')); layouts.push(nodePath.join(pkg, 'bin', 'pwsh.exe')); } catch {} layouts.push(nodePath.join(dir, 'vendor', 'pwsh', win, 'pwsh.exe')); } catch {} for (const candidate of layouts) { if (usable(candidate)) return candidate; } return undefined; } catch { return undefined; } })()"

package/docs/manual-validation.md

@@ -0,0 +1,53 @@
+# dsh-ops 手动验收清单
+
+本轮按风雪要求：不补/改回归测试，不加 CI，不运行旧套件。本清单是操作者步骤，不是自动化门禁。替换源码后先重启 DSH。
+
+## 工具发布与提示词
+
+- `workspace-write`、`read-only`：目录只有四个 ops 文件工具；没有任何 `ops_run` / `ops_job_*`，提示词也不出现这些名字。
+- `danger-full-access` 且 `enableShellTools: true`：五个命令/job 工具一起出现。
+- `enableShellTools: false`、无 sandboxPolicy 服务、无会话：命令组不出现。
+- 同时开受限会话与完全权限会话：两者目录互不污染。受限子 agent 不继承祖先的命令组。
+- 同一会话切换受限 → 完全权限 → 受限：每次下一请求目录/提示词跟随变化，不重连 FastCtx；旧命令句柄不能继续调用。
+- 受限会话不发布 `ops_bash`；完全权限 + publishBashTool=true + bash 可解析 + subprocess 可用时出现，通用命令优先走它。FastCtx 缺失或 enableShellTools=false 时 bash 层仍独立可用。
+- 提示词仅一段 `dsh-ops:repository-tooling`：工具包 → bash → pwsh7；不混语法，不因 bash 报错切 PowerShell。Windows 原生操作才用 pwsh。没有旧 host-shell 段或 `mcp:fastctx`。
+- publishBashTool=false 隐去 bash 这一层；bash 权限动态切换、受限子 agent 继承过滤和卸载清理一起验证。
+- `promptPolicy: false`：不发布路由提示词。
+- `deny-host-shell`：有无 ops 命令组都应拒绝配置的宿主 shell；若工具来自继承层，目录也应遮蔽。无可用执行器时不推荐不可调用的 ops 命令。
+
+## 文件工具
+
+- 多文件多区间 `files[]`，各自 offset/limit/encoding；重复路径读取不同区间，结果有序。
+- GBK 文本显式 encoding；单文件 grep encoding、目录 fallback_encoding。
+- grep `pattern` 是字符串，不传数组；`glob[]` 可混正负规则。
+- glob `pattern[]`、`!` 排除、paths/details；没有 count 模式。
+- grep schema 只公开 context；content/count/summary 与分页结果仍符合上游行为。
+- PDF text、pages 翻页、hex；text 模式外不要让 ops 渲染图像。
+- 普通图片路径：错误明确说使用宿主 read_image；改后缀的图像也不能返回成功占位符。图像 `view: hex` 可以读取字节。
+- 跨文件替换先 dry_run，再在临时副本上应用；精确编辑走宿主 edit。
+- 只读工具可并发；替换/命令不应声明并发安全。
+
+## 任务与输出隔离
+
+- 当前会话没启动 job：ops 结果没有别的会话的 Background 行。
+- 启动 job，保留返回 ID；输出、列表、kill 只操作自己的 ID。
+- A/B 两会话各启动 job：各自 footer/list 只见自己，不能读取/kill 对方 ID。
+- 完成/kill 后仍能读取自己已有 ID 的日志。
+- job_list status/limit/offset 是自己的分页，不暴露全局总数/offset；空列表明确为空。
+- 大全局 job 存储扫描不完整时必须报告 Partial，不冒充完整；原工具结果的 Complete/Partial 续页提示不能丢。
+- 重连后不认领旧 ID；操作者可通过上游工具清理持久 job。权限降级不自动杀已运行任务，须操作者管理。
+
+## 生命周期与边界
+
+- 服务端断线立即撤下工具与对应提示词项，恢复后重新出现。
+- 卸载后工具/提示词/限制全部消失；共享注册表方法未改写，外来同名工具仍可按自己的 scope 注册。
+- 未知配置键报错点名；required=true 的缺失/不可用二进制拒绝激活。
+- 取消/传输超时只表明停止等待，不把它误读为命令已停止。ops_run 的 timeout_ms 才是上游进程树超时。
+
+## 数字复核
+
+运行 `node scripts/measure-schemas.mjs docs/schema-current.json`，对比 `schema-baseline.json`。不执行真实文件/命令操作。统计的是紧凑 schema JSON 的 UTF-8 字节，tokens≈bytes/4，不是使用频率或准确账单。基线来自修改前 dee3c57 + FastCtx 0.2.6；工具调用频率仍未知，不据此删除 ops_replace。
+
+## 不可误读为已解决的边界
+
+四个 FastCtx 文件工具仍是非宿主沙箱后端，ops_replace 没有 workspace confinement；命令权限门不解决这件事。没有文件系统约束设计前，不作为不可信受限环境的安全方案。宿主审批策略与 sandbox mode 独立，本插件没有新增逐命令审批升级。

package/docs/schema-baseline.json

@@ -0,0 +1,64 @@
+{
+  "format": "dsh-ops-schema-measurement-v1",
+  "metric": "UTF-8 bytes of compact JSON {name,description,parameters}; approximate tokens = ceil(bytes/4), not a tokenizer or usage-frequency count",
+  "runtimeVersion": "fastctx 0.2.6",
+  "tools": [
+    {
+      "name": "ops_glob",
+      "bytes": 2485,
+      "approximateTokens": 622
+    },
+    {
+      "name": "ops_grep",
+      "bytes": 3766,
+      "approximateTokens": 942
+    },
+    {
+      "name": "ops_inspect_local_file",
+      "bytes": 4375,
+      "approximateTokens": 1094
+    },
+    {
+      "name": "ops_job_kill",
+      "bytes": 289,
+      "approximateTokens": 73
+    },
+    {
+      "name": "ops_job_list",
+      "bytes": 889,
+      "approximateTokens": 223
+    },
+    {
+      "name": "ops_job_output",
+      "bytes": 1717,
+      "approximateTokens": 430
+    },
+    {
+      "name": "ops_replace",
+      "bytes": 2181,
+      "approximateTokens": 546
+    },
+    {
+      "name": "ops_run",
+      "bytes": 1672,
+      "approximateTokens": 418
+    },
+    {
+      "name": "ops_run_background",
+      "bytes": 1515,
+      "approximateTokens": 379
+    }
+  ],
+  "total": {
+    "bytes": 18889,
+    "approximateTokens": 4723
+  },
+  "toolingPrompt": {
+    "bytes": 3373,
+    "approximateTokens": 844
+  },
+  "rawServerInstructions": {
+    "bytes": 246,
+    "approximateTokens": 62
+  }
+}

package/docs/schema-current.json

@@ -0,0 +1,84 @@
+{
+  "format": "dsh-ops-schema-measurement-v1",
+  "metric": "UTF-8 bytes of compact JSON {name,description,parameters}; approximate tokens = ceil(bytes/4), not a tokenizer or usage-frequency count",
+  "runtimeVersion": "fastctx 0.2.6",
+  "tools": [
+    {
+      "name": "ops_glob",
+      "bytes": 1226,
+      "approximateTokens": 307
+    },
+    {
+      "name": "ops_grep",
+      "bytes": 2019,
+      "approximateTokens": 505
+    },
+    {
+      "name": "ops_inspect_local_file",
+      "bytes": 1968,
+      "approximateTokens": 492
+    },
+    {
+      "name": "ops_job_kill",
+      "bytes": 267,
+      "approximateTokens": 67
+    },
+    {
+      "name": "ops_job_list",
+      "bytes": 694,
+      "approximateTokens": 174
+    },
+    {
+      "name": "ops_job_output",
+      "bytes": 668,
+      "approximateTokens": 167
+    },
+    {
+      "name": "ops_replace",
+      "bytes": 1511,
+      "approximateTokens": 378
+    },
+    {
+      "name": "ops_run",
+      "bytes": 751,
+      "approximateTokens": 188
+    },
+    {
+      "name": "ops_run_background",
+      "bytes": 635,
+      "approximateTokens": 159
+    }
+  ],
+  "total": {
+    "bytes": 9739,
+    "approximateTokens": 2435
+  },
+  "fileOnly": {
+    "bytes": 6724,
+    "approximateTokens": 1681
+  },
+  "fileOnlyPrompt": {
+    "bytes": 470,
+    "approximateTokens": 118
+  },
+  "bashSchema": {
+    "bytes": 894,
+    "approximateTokens": 224
+  },
+  "fullWithBash": {
+    "bytes": 10633,
+    "approximateTokens": 2659
+  },
+  "toolingPrompt": {
+    "bytes": 1053,
+    "approximateTokens": 264
+  },
+  "publishedServerInstructions": {
+    "bytes": 0,
+    "approximateTokens": 0
+  },
+  "rawServerInstructions": {
+    "bytes": 246,
+    "approximateTokens": 62
+  }
+}

package/docs/schema-measurement.md

@@ -0,0 +1,17 @@
+# Schema measurement
+
+Manual measurement only; not CI, regression coverage, a tokenizer, or tool-use telemetry.
+
+Baseline: plugin `dee3c57`, FastCtx 0.2.6, before presentation changes. Current: same runtime, plugin-only schema projections. Metric: sum of compact UTF-8 JSON `{name,description,parameters}` sizes, no whitespace formatting; tokens ≈ ceil(bytes/4).
+
+| Surface | Baseline bytes | Current bytes | Reduction |
+| --- | ---: | ---: | ---: |
+| Nine FastCtx schemas (full-access session) | 18,889 | 9,739 | 48.4% |
+| Four file schemas | 12,807 | 6,724 | 47.5% |
+| Routing section (original full ladder vs restored compact three-layer table) | 3,373 | 1,053 | 68.8% |
+
+Full-access FastCtx schema estimate: 4,723 → 2,435 tokens. The restored ops_bash schema adds 894 bytes (~224 tokens); full FastCtx+bash surface is 10,633 bytes (~2,659 tokens). Restricted file-only surface: about 1,681 tokens; its routing table is 470 bytes (~118 tokens). No server instructions are published (the original raw server instructions were 246 bytes); the old host-shell section is also removed. Baseline excludes ops_bash, so compare nine FastCtx tools like-for-like rather than treating restoration as a regression of those numbers. Total request savings depend on host presentation; these are not API usage/billing measurements.
+
+`ops_grep` went from 3,766 → 2,019 bytes; `ops_inspect_local_file` from 4,375 → 1,968. `ops_replace` is retained: schema cost cannot establish invocation frequency, and no usage-frequency measurement was collected.
+
+Reproduce the current snapshot with `node scripts/measure-schemas.mjs docs/schema-current.json`. It only starts FastCtx, initializes, lists schemas, then closes it; it executes no tools. Keep the baseline unchanged; a different runtime schema requires an explicitly labeled comparison.

package/dsh-plugin.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://raw.githubusercontent.com/T-Auto/dsh-std/8a15541117cb3c13ddb8f2468308691b6051d162/packages/manifest/schema/dsh-plugin-0.15.schema.json",
+  "manifestVersion": "0.15",
+  "id": "dsh-ops.fastctx",
+  "name": "dsh-ops",
+  "version": "0.2.1",
+  "license": "MIT AND Apache-2.0",
+  "facets": {
+    "host": {
+      "entry": "lib/index.js",
+      "apiVersion": "v1alpha1"
+    }
+  },
+  "requires": {
+    "contracts": [
+      {
+        "apiVersion": "tools.dsh/v1alpha1",
+        "kind": "Tool"
+      }
+    ]
+  },
+  "permissions": [
+    {
+      "name": "dsh-ops.process.spawn",
+      "scope": "subprocess",
+      "reason": "Start the FastCtx MCP server and the command execution it owns."
+    },
+    {
+      "name": "dsh-ops.fs.read",
+      "scope": "filesystem-read",
+      "reason": "Read the FastCtx executable, the vendored source, and the runtime receipt."
+    },
+    {
+      "name": "dsh-ops.fs.write",
+      "scope": "dsh-home",
+      "reason": "Install the provisioned runtime into <DSH_HOME>/dsh-ops/bin and record its receipt."
+    }
+  ],
+  "contributes": {
+    "x-display": [
+      {
+        "icon": "./icon.svg",
+        "title": "Repository tools",
+        "description": "Read, search, replace, and run commands through the hosted FastCtx ops_* tool surface instead of shell commands.",
+        "locales": [
+          "locale/en.json",
+          "locale/zh.json"
+        ]
+      }
+    ],
+    "x-prompt-sections": [
+      {
+        "name": "dsh-ops:repository-tooling",
+        "order": 3250,
+        "summary": "Compact tools-to-bash-to-PowerShell-7 routing; prefer bash except for Windows-native operations."
+      }
+    ],
+    "x-tool-namespaces": [
+      {
+        "serverName": "fastctx",
+        "transport": "stdio",
+        "source": "vendored FastCtx runtime",
+        "publicPrefix": "ops_",
+        "tools": [
+          "inspect_local_file",
+          "grep",
+          "glob",
+          "replace",
+          "run",
+          "run_background",
+          "job_output",
+          "job_list",
+          "job_kill"
+        ],
+        "shellPermission": "enableShellTools AND per-session sandboxPolicy danger-full-access"
+      },
+      {
+        "serverName": "dsh-ops",
+        "transport": "in-process",
+        "source": "the plugin's bash layer via host subprocess",
+        "publicPrefix": "ops_",
+        "tools": ["bash"],
+        "shellPermission": "publishBashTool AND per-session sandboxPolicy danger-full-access"
+      }
+    ]
+  },
+  "subscriptions": []
+}

package/icon.svg

@@ -0,0 +1,12 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36" fill="none">
+  <g stroke="#7C7C82" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round">
+    <rect x="4.2" y="6.2" width="27.6" height="23.6" rx="4.2" />
+    <path d="M10 14.4l4 3.8-4 3.8" />
+    <path d="M17.4 22h4.4" />
+    <path d="M25.6 13v10" />
+  </g>
+  <g fill="#7C7C82">
+    <circle cx="25.6" cy="13" r="2.3" />
+    <circle cx="25.6" cy="23" r="2.3" />
+  </g>
+</svg>