@morlay/dsh-sandbox-local 0.0.2 → 0.0.3-alpha.0

package/README.md

@@ -8,12 +8,9 @@
 
 上游沙箱策略只有两个字段：`mode`（`read-only` / `workspace-write` /
 `danger-full-access`）与 `workspaceRoot`；`workspace-write` 的可写路径是硬编码的
-`[工作区, /tmp, os.tmpdir()]`（`packages/sandbox/sandbox/src/roots.ts:52-55`），
+`[工作区, /tmp, os.tmpdir()]`（`vendor/deepseek-harness/packages/sandbox/sandbox/src/roots.ts:52-55`），
 没有任何追加可写根或拒绝项的配置面。于是「让 agent 能写 `$XDG_CACHE_HOME`，
-但永远不许碰项目里的 `mise.*.toml`」这类诉求只能整块放弃隔离。上游自己实现过拒绝项
-（`readDenyPaths`）又撤回：bwrap 要在已置只读的树里创建挂载点、Landlock 无法从自己的
-`/` 读授权里减除，一个「在能生效的地方破坏隔离、在不能生效的地方谎报」的保护被判为
-不如明确的缺失（`.agents/notes/implemented/architecture/2026-07-30-credential-boundaries-and-atomic-registration.md:29`）。
+但永远不许碰项目里的 `mise.*.toml`」这类诉求只能整块放弃隔离。
 
 本包把「能表达多少就说多少」明确下来：Seatbelt 完整生效，其余平台按方言降级，
 并在加载期告警，而不是静默失效。
@@ -92,39 +89,17 @@
 
 ## 装配
 
-本包自带 `cordis.patch.yml`（禁用官方两行 + 插入自己的一行），把本包作为独立 bundle 采用
-的部署直接列进 `dsh.profile.bundles` 即可；行不带 config（schema 默认是空规则）：
+本包自带 `cordis.patch.yml`（禁用官方 `sandbox` / `fs-sandbox` 两行 + 插入自己的一行），
+把本包作为**独立 bundle** 采用的部署直接列进 `dsh.profile.bundles` 即可；行不带 config
+（schema 默认是空规则），patch 内容见该文件。
 
-```yaml
-- id: sandbox
-  disabled: true
-
-- id: fs-sandbox
-  disabled: true
-
-- insert:
-    - id: sandbox-local
-      name: "@morlay/dsh-sandbox-local"
-```
-
-**本部署（`@morlay/dsh-preset`）不走这条路径**：它的 patch 自己禁用官方两行、插入
-`- id: sandbox-local` 行并写上规则，因此示例 app 的 `dsh.profile.bundles` 不需要列出本包，
-只需要 profile 的依赖树能解析模块名（`@morlay/dsh-preset` 已在 `dependencies` 声明本包）。
+**本部署（`@morlay/dsh-preset`）不走这条路径**：装配（禁用官方两行 + 插入
+`sandbox-local` 行）与 `access` 规则一起维护在 preset 的 bundle patch 里，因此示例 app 的
+`dsh.profile.bundles` 不需要列出本包，只需要 profile 的依赖树能解析模块名
+（`@morlay/dsh-preset` 已在 `dependencies` 声明本包）。patch 层级的合并顺序与放置理由见
+[设计 预设生成与装配](../../preset/dsh-preset/.agents/designs/20260917-预设生成与装配.md)。
 两种采用方式互斥：同时上线会重复插入同一行。
 
-**规则写在哪里才会生效**（patch 层按 `[bundle patches, profile patches, home patches,
-overlays]` 合并，后应用者整块替换同一行的 `config`）：
-
-| 载体                                                                          | 生效范围                                              |
-| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
-| profile 的 `cordis.patch.yml`（`$DSH_HOME/profiles/<name>/cordis.patch.yml`） | dev 与打包形态都生效，但只属于本机 home               |
-| app 的 `cordis.patch.yml`                                                     | 打包（`bundle`）形态：作为 seed 的 profile patch 生效 |
-| 一个自有 bundle 的 patch                                                      | 所有形态（随包分发）                                  |
-
-本部署采用最后一种：**装配与规则在 `@morlay/dsh-preset` 的 bundle patch 里一起维护**
-（禁用官方两行 + 插入本包行 + `access` 规则，跨 dev / 打包形态一致），不依赖 app 的
-`dsh.profile.bundles` 再列一层。
-
 ## 前提
 
 - 官方 `sandbox` 与 `fs-sandbox` 行必须禁用：同一 scope 内重复注册同名服务会 fail loud
@@ -154,7 +129,7 @@ overlays]` 合并，后应用者整块替换同一行的 `config`）：
 - **Windows 额外授权未实现**：官方 `AclWriteGrant` 可以做预授权，但没有把 `AclWriteGrant`
   接进 `confine` 的现成路径，本版只告警。
 
-## 本地开发
+## 验证
 
-根目录 `just test`（vitest，含 `seatbelt.e2e.spec.ts`——非 macOS 或被更外层 Seatbelt
-拦住时自动跳过）、`just lint`（oxlint typeAware）、`just build`（tsdown 构建本包）。
+构建、测试与 lint 走根 `justfile`（含 `seatbelt.e2e.spec.ts`——非 macOS 或被更外层 Seatbelt
+拦住时自动跳过）；本包的接缝与判据见 [`.agents/standards/`](./.agents/standards/)。

package/dist/index.d.mts

@@ -3,27 +3,14 @@ import { Config as Config$2 } from "@deepseek-ai/dsh-sandbox-local";
 import z from "@deepseek-ai/schemastery";
 import { Context } from "@deepseek-ai/cordis";
 //#region src/config.d.ts
-/** 插件配置。 */
 interface Config extends Config$2, Config$1 {
-  /**
-   * 规则条目：`rw <path>`（额外可写根）、`r- <path>`（只读）、`-- <pattern>`（拒绝访问）。
-   * 数组每项一条，或写一段多行文本（每行一条）；`{{ env.NAME }}` 按进程环境展开。
-   */
   access?: string | string[];
 }
-/** 运行时配置 schema。 */
 declare const Config: z<Config>;
 //#endregion
 //#region src/index.d.ts
-/** Cordis 插件名。 */
 declare const name = "sandbox-local";
-/** fs 侧从策略服务取默认模式与工作区回退根，所以先等 `ctx.sandboxPolicy`。 */
 declare const inject: string[];
-/**
- * 注册两个替换实现。
- * @param ctx - 插件上下文（官方 `sandbox` / `fs-sandbox` 行已禁用）。
- * @param config - 已由 schema 填好默认值的配置。
- */
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
 export { Config, apply, inject, name };

package/dist/index.mjs

@@ -6,26 +6,10 @@ import { stat } from "node:fs/promises";
 import { LocalSandboxProvider } from "@deepseek-ai/dsh-sandbox-local";
 import z from "@deepseek-ai/schemastery";
 //#region src/rules.ts
-/**
-* 规则编译：`access` 条目解析（`rw <path>` 额外可写根 / `r- <path>` 只读 /
-* `-- <pattern>` 拒绝访问）、`{{ env.NAME }}` 模板展开、相对工作区路径的绝对化、
-* glob → 正则，以及编译结果的匹配。
-*
-* 命中优先级：`--` 拒绝覆盖一切；`r-` 只读覆盖可写授予；都未命中时才按可写根判定。
-*
-* 生成的正则源码同时交给进程内检查（JS `RegExp`）与 macOS Seatbelt profile
-* （SBPL 的 `(regex #"…")`），因此只用 POSIX ERE 与 JS 正则共有的语法。
-* @module @morlay/dsh-sandbox-local/rules
-*/
-/** `{{ env.NAME }}` 模板；名字限定为环境变量的字符集。 */
 const ENV_TEMPLATE = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
-/** `access` 的条目形式：`rw <path>` / `r- <path>` / `-- <pattern>`；前缀后必须有空白。 */
 const ACCESS_LINE = /^(rw|r-|--)(?:\s+(.*))?$/u;
-/** glob 元字符：规则里出现即按模式匹配，否则按字面路径（含其全部后代）匹配。 */
 const GLOB_META = /[*?[]/;
-/** glob 翻译时需要转义的正则元字符（字符类内部除外）。 */
 const REGEX_META = /[\\^$+.(){}|]/;
-/** 展开规则里的 `{{ env.NAME }}`；引用未定义或为空的环境变量直接抛错。 */
 function expandEnvTemplates(value, env) {
 	return value.replace(ENV_TEMPLATE, (_match, name) => {
 		const resolved = env[name];
@@ -33,13 +17,6 @@ function expandEnvTemplates(value, env) {
 		return resolved;
 	});
 }
-/**
-* 把含 glob 的规则翻译成正则源码。
-* `**` 跨目录层级（`**` 与“`**` 后接斜杠”都能匹配零层），`*` 与 `?` 不跨 `/`，
-* 字符类透传（`[!…]` 按 glob 习惯翻成 `[^…]`），其余正则元字符转义。
-* @param pattern - 已绝对化的 glob 规则。
-* @returns 可同时被 JS `RegExp` 与 SBPL regex 接受的正则源码。
-*/
 function globToRegexSource(pattern) {
 	let source = "";
 	for (let index = 0; index < pattern.length; index += 1) {
@@ -78,24 +55,15 @@ function globToRegexSource(pattern) {
 	}
 	return source;
 }
-/** 规则是否为空——空规则下 provider 不改写任何 runner 参数。 */
 function isEmptyRules(rules) {
 	return rules.allowRoots.length === 0 && rules.readOnlySubtrees.length === 0 && rules.readOnlyPatterns.length === 0 && rules.denySubtrees.length === 0 && rules.denyPatterns.length === 0;
 }
-/** 只读模式不因 `rw` 条目放松：投影出只保留 `r-` / `--` 条目的规则集。 */
 function withoutAllowRoots(rules) {
 	return rules.allowRoots.length === 0 ? rules : {
 		...rules,
 		allowRoots: []
 	};
 }
-/**
-* 解析 `access` 配置：接受字符串数组（每项一条规则）或多行文本（每行一条规则），
-* 空行忽略；`rw <path>` 是额外可写根，`r- <path>` 是只读，`-- <pattern>` 是访问
-* 拒绝（读 + 写）。缺前缀或前缀后没有路径都直接报错——规则不因写法歧义而变形。
-* @param input - 配置里的 `access` 值。
-* @returns `allowWrite` / `readOnly` / `deny` 三组规则（模板尚未展开）。
-*/
 function parseAccess(input) {
 	const lines = (input === void 0 ? [] : typeof input === "string" ? [input] : [...input]).flatMap((value) => value.split(/\r?\n/u)).map((line) => line.trim()).filter((line) => line.length > 0);
 	const allowWrite = [];
@@ -116,13 +84,6 @@ function parseAccess(input) {
 		deny
 	};
 }
-/**
-* 把配置里的 `access` 转成规则来源：模板在这一步展开（加载期，fail-fast），
-* 相对路径留待按调用时的工作区根绝对化。
-* @param config - 含 `access` 的插件配置。
-* @param env - 模板展开用的进程环境。
-* @returns 模板已展开的规则来源。
-*/
 function ruleSourceOf(config, env) {
 	const parsed = parseAccess(config.access);
 	const expand = (values) => values.map((value) => expandEnvTemplates(value, env));
@@ -132,11 +93,9 @@ function ruleSourceOf(config, env) {
 		deny: expand(parsed.deny)
 	};
 }
-/** 绝对化一条规则：相对路径相对工作区根。 */
 function absolutize(value, workspaceRoot) {
 	return isAbsolute(value) ? value : resolve(workspaceRoot, value);
 }
-/** 编译一组字面路径 / glob 规则：字面项按子树（含全部后代）匹配，glob 项按整串匹配。 */
 function compilePaths(values, workspaceRoot) {
 	const subtrees = [];
 	const patterns = [];
@@ -155,13 +114,6 @@ function compilePaths(values, workspaceRoot) {
 		patterns
 	};
 }
-/**
-* 按一个工作区根编译规则。
-* `rw` 条目必须是具体路径（glob 无法表达“可写根”）；`r-` 与 `--` 条目允许 glob。
-* @param source - 已展开模板的规则来源。
-* @param workspaceRoot - 相对规则解析用的工作区根（canonical 绝对路径）。
-* @returns 编译后的规则。
-*/
 function compileRules(source, workspaceRoot) {
 	const allowRoots = [];
 	for (const value of source.allowWrite) {
@@ -178,50 +130,23 @@ function compileRules(source, workspaceRoot) {
 		denyPatterns: deny.patterns
 	};
 }
-/** 字面规则的后代判定（canonical 拼写，与 Seatbelt `subpath` 同一语义）。 */
 function isUnder(path, root) {
 	if (path === root) return true;
 	return path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
-/** 命中任一子树或任一模式。 */
 function matches(canonicalTarget, subtrees, patterns) {
 	for (const subtree of subtrees) if (isUnder(canonicalTarget, subtree)) return true;
 	return patterns.some((pattern) => pattern.regex.test(canonicalTarget));
 }
-/**
-* 判断目标是否被 `--` 条目命中（读与写都拒）。
-* @param rules - 已编译规则。
-* @param canonicalTarget - 目标的 canonical 路径。
-* @returns 命中即 true。
-*/
 function isDenied(rules, canonicalTarget) {
 	return matches(canonicalTarget, rules.denySubtrees, rules.denyPatterns);
 }
-/**
-* 判断目标是否被 `r-` 条目命中（读放行、写拒绝）。
-* @param rules - 已编译规则。
-* @param canonicalTarget - 目标的 canonical 路径。
-* @returns 命中即 true。
-*/
 function isReadOnly(rules, canonicalTarget) {
 	return matches(canonicalTarget, rules.readOnlySubtrees, rules.readOnlyPatterns);
 }
 //#endregion
 //#region src/dialects.ts
-/**
-* 在官方 provider 生成的 confined argv 上追加本包规则：
-* Seatbelt 追加 SBPL 规则（后置规则覆盖先前的 allow，实测 `(deny file-read* file-write*
-* (subpath …))` 能压过 `(allow file-write* (subpath …))`，`r-` 条目则只 deny 写入），
-* bwrap 追加挂载参数（`rw` 用 `--bind-try`，`r-` 与 `--` 都用 `--ro-bind-try`），
-* Landlock 只能追加可写授权（其 allow-list 语义无法减除子路径），
-* Windows ACL runner 没有对应表达。
-*
-* 方言从官方 `ConfinedArgv.argv` 的结构识别：runner 参数在前，`--` 之后是调用方 argv。
-* @module @morlay/dsh-sandbox-local/dialects
-*/
-/** runner 部分与调用方 argv 的分隔符。 */
 const SEPARATOR = "--";
-/** 各方言的规则表达能力——加载期据此告警，运行期据此决定是否改写参数。 */
 const DIALECT_CAPABILITIES = {
 	seatbelt: {
 		allowWrite: true,
@@ -248,17 +173,11 @@ const DIALECT_CAPABILITIES = {
 		denyWriteOnly: false
 	}
 };
-/** runner 部分的结束位置。 */
 function separatorIndex(argv) {
 	const index = argv.indexOf(SEPARATOR);
 	if (index === -1) throw new Error("sandbox rules: the confined argv carries no `--` separator to extend");
 	return index;
 }
-/**
-* 识别 argv 使用的执行方言。
-* @param argv - 官方 provider 返回的完整 confined argv。
-* @returns 方言，或无法识别时的 `undefined`（例如运维自定义的 runnerCommand）。
-*/
 function dialectOf(argv) {
 	const separator = argv.indexOf(SEPARATOR);
 	const runner = separator === -1 ? argv : argv.slice(0, separator);
@@ -267,19 +186,13 @@ function dialectOf(argv) {
 	if (runner.includes("--workspace")) return "windows-acl";
 	if (runner.includes("--ro") || runner.includes("--rw")) return "landlock";
 }
-/** SBPL 字符串字面量。 */
 function sbplString(value) {
 	return `"${value.replaceAll("\\", String.raw`\\`).replaceAll("\"", String.raw`\"`)}"`;
 }
-/**
-* SBPL `#"…"` 的正则体：正则自身的 `\` 必须保留（glob 翻译用它转义元字符），
-* 因此拒绝项里出现双引号时直接报错，而不是产出一个含义变化的 profile。
-*/
 function sbplRegexBody(source) {
 	if (source.includes("\"")) throw new Error(`sandbox rules: deny pattern ${JSON.stringify(source)} cannot be expressed in a Seatbelt profile`);
 	return source;
 }
-/** Seatbelt：把 allow / deny 规则追加到 `-p` 的 profile 文本末尾。 */
 function extendSeatbelt(argv, rules) {
 	const index = argv.indexOf("-p");
 	const profile = index === -1 ? void 0 : argv[index + 1];
@@ -297,11 +210,6 @@ function extendSeatbelt(argv, rules) {
 		...argv.slice(index + 2)
 	];
 }
-/**
-* bwrap：额外可写根用 `--bind-try`（路径不存在时跳过）；`r-` 与 `--` 都用
-* `--ro-bind-try` 覆盖成只读（挂载后行覆盖前行）——也就是说 `--` 在 bwrap 上退化为
-* “只拒写入”。glob 模式无法表达为静态挂载，由调用方在加载期告警。
-*/
 function extendBwrap(argv, rules) {
 	const separator = separatorIndex(argv);
 	const additions = [];
@@ -313,7 +221,6 @@ function extendBwrap(argv, rules) {
 		...argv.slice(separator)
 	];
 }
-/** Landlock：只能追加可写授权（`--rw`），`r-` 与 `--` 都无对应表达。 */
 function extendLandlock(argv, rules) {
 	const separator = separatorIndex(argv);
 	const additions = rules.allowRoots.flatMap((root) => ["--rw", root]);
@@ -323,12 +230,6 @@ function extendLandlock(argv, rules) {
 		...argv.slice(separator)
 	];
 }
-/**
-* 按 argv 的方言追加规则。
-* @param argv - 官方 provider 返回的 confined argv。
-* @param rules - 已编译规则；空规则原样返回。
-* @returns 追加规则后的 argv；方言无法识别时抛错（规则不能静默失效）。
-*/
 function extendConfinedArgv(argv, rules) {
 	if (isEmptyRules(rules)) return [...argv];
 	const dialect = dialectOf(argv);
@@ -342,9 +243,7 @@ function extendConfinedArgv(argv, rules) {
 }
 //#endregion
 //#region src/containment.ts
-/** 视为“路径不存在”的错误码：只有它们能让祖先遍历继续。 */
 const MISSING_CODES = /* @__PURE__ */ new Set(["ENOENT", "ENOTDIR"]);
-/** stat 一次，缺失返回 undefined；其它失败（权限、I/O）继续抛出。 */
 async function statIfPresent(path) {
 	try {
 		return await stat(path, { bigint: true });
@@ -354,11 +253,9 @@ async function statIfPresent(path) {
 		throw error;
 	}
 }
-/** 按大小写敏感性归一用于比较的拼写。 */
 function comparablePath(path, caseSensitive) {
 	return caseSensitive ? path : path.toLowerCase();
 }
-/** 词法包含判定（目标可带尚不存在的后缀）。 */
 function isLexicallyUnder(path, root, caseSensitive) {
 	const comparableTarget = comparablePath(path, caseSensitive);
 	const comparableRoot = comparablePath(root, caseSensitive);
@@ -366,19 +263,9 @@ function isLexicallyUnder(path, root, caseSensitive) {
 	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
 	return comparableTarget.startsWith(prefix);
 }
-/** 两次 stat 是否指向同一个文件系统对象。 */
 function sameIdentity(left, right) {
 	return left.dev === right.dev && left.ino === right.ino;
 }
-/**
-* 判断 canonical 目标是否就是某个根或位于其下。
-* 拼写不同时（Windows 长名/8.3 别名、大小写差异）沿目标的现存祖先比较文件系统身份，
-* 不把包含判定弱化成文本近似。
-* @param path - 目标的 canonical 路径（可带尚不存在的尾部）。
-* @param root - canonical 可写根。
-* @param caseSensitive - 词法比较是否区分大小写；默认按宿主平台约定。
-* @returns 目标是该根或其后代时为 true。
-*/
 async function isPathUnder(path, root, caseSensitive = process.platform !== "win32") {
 	if (isLexicallyUnder(path, root, caseSensitive)) return true;
 	const rootInfo = await statIfPresent(root);
@@ -394,78 +281,39 @@ async function isPathUnder(path, root, caseSensitive = process.platform !== "win
 }
 //#endregion
 //#region src/fs.ts
-/**
-* 官方本机文件系统后端的可配置版本。
-* `--` 条目在解析阶段拒绝目标（覆盖 read / write / edit / list 等一切工具入口），
-* `r-` 与 `--` 条目在写入前拒绝写入（优先于任何可写根），写操作再按
-* `workspace-write` + `rw` 条目复核 containment。
-*/
 var ConfigurableFileSystem = class extends LocalFileSystem {
 	static inject = ["sandboxPolicy"];
 	defaultMode;
 	source;
-	/** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
 	compiled = /* @__PURE__ */ new Map();
 	constructor(ctx, config) {
 		super(ctx, config);
 		this.defaultMode = ctx.sandboxPolicy.defaultMode;
 		this.source = ruleSourceOf(config, process.env);
 	}
-	/** 工具层读它判断后端是否 confine（并据此广告 escalation 字段）。 */
 	get sandboxMode() {
 		return this.defaultMode;
 	}
-	/**
-	* 解析目标后立即执行拒绝判定：工具入口（read / write / edit / list）都先经过
-	* `resolve`，因此一次判定即可覆盖读与写。
-	* @param path - 待解析的路径。
-	* @param opts - cwd 与取消信号；cwd 同时是相对规则的解析根。
-	* @returns 解析后的目标。
-	*/
 	async resolve(path, opts) {
 		const target = await super.resolve(path, opts);
 		this.assertNotDenied(this.rulesFor(opts?.cwd ?? this.ctx.sandboxPolicy.workspaceRoot), target.targetKey, target.displayPath);
 		return target;
 	}
-	/**
-	* 按 per-call 策略复核后写入。
-	* @param target - 工具解析出的目标。
-	* @param content - 新的完整内容。
-	* @param expected - 写入前版本守卫。
-	* @param signal - 取消信号。
-	* @param sandboxPolicy - per-call 策略；省略时用部署默认。
-	* @returns 上游写入结果。
-	*/
 	async writeText(target, content, expected, signal, sandboxPolicy) {
 		return super.writeText(await this.checkedTarget(target, sandboxPolicy), content, expected, signal);
 	}
-	/**
-	* 按 per-call 策略复核后编辑。
-	* @param target - 工具解析出的目标。
-	* @param edit - 字面量 search/replace 请求。
-	* @param expected - 版本守卫。
-	* @param signal - 取消信号。
-	* @param sandboxPolicy - per-call 策略；省略时用部署默认。
-	* @returns 上游编辑结果。
-	*/
 	async editText(target, edit, expected, signal, sandboxPolicy) {
 		return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
 	}
-	/** `--` 条目命中即拒绝访问（读与写都拒）；抛 `FS_SANDBOX_DENIED`。 */
 	assertNotDenied(rules, canonicalTarget, displayPath) {
 		if (!isDenied(rules, canonicalTarget)) return;
 		throw new FsError(`cannot access "${displayPath}": file access denied by the configured "--" rules`, "FS_SANDBOX_DENIED");
 	}
-	/** `--` 或 `r-` 条目命中即拒绝写入，且优先于任何可写根。 */
 	assertWritable(rules, canonicalTarget, displayPath) {
 		this.assertNotDenied(rules, canonicalTarget, displayPath);
 		if (!isReadOnly(rules, canonicalTarget)) return;
 		throw new FsError(`cannot write "${displayPath}": path is read-only by the configured "r-" rule`, "FS_SANDBOX_DENIED");
 	}
-	/**
-	* 写前复核：`--` / `r-` 条目（任何模式）→ 模式本身的只读拒绝 → `workspace-write` 的
-	* `writableRoots + rw` containment，返回必须被写入的那个目标。
-	*/
 	async checkedTarget(target, sandboxPolicy) {
 		const policy = sandboxPolicy ?? this.ctx.sandboxPolicy.resolve();
 		const rules = this.rulesFor(policy.workspaceRoot);
@@ -478,7 +326,6 @@ var ConfigurableFileSystem = class extends LocalFileSystem {
 		for (const root of [...writableRoots(policy), ...rules.allowRoots]) if (await isPathUnder(fresh.targetKey, root)) return fresh;
 		throw new FsError(`cannot write "${target.displayPath}": file access denied under workspace-write mode`, "FS_SANDBOX_DENIED");
 	}
-	/** 取（并按需编译缓存）某个工作区根下的规则。 */
 	rulesFor(workspaceRoot) {
 		const cached = this.compiled.get(workspaceRoot);
 		if (cached !== void 0) return cached;
@@ -489,27 +336,15 @@ var ConfigurableFileSystem = class extends LocalFileSystem {
 };
 //#endregion
 //#region src/sandbox.ts
-/**
-* 官方本机沙箱 provider 的可配置版本。
-* `read-only` 模式不追加 `rw` 条目（只读边界不因额外可写根放松）；`--` 条目在两种
-* confined 模式下都生效。
-*/
 var ConfigurableSandboxProvider = class extends LocalSandboxProvider {
 	source;
-	/** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
 	compiled = /* @__PURE__ */ new Map();
 	constructor(ctx, config) {
 		super(ctx, config);
 		this.source = ruleSourceOf(config, process.env);
 	}
-	/**
-	* 官方拼装 + 规则追加。
-	* @param argv - 调用方即将 spawn 的 argv。
-	* @param policy - 本次调用的文件效果策略。
-	* @returns 追加规则后的 confined argv（空规则时与官方结果一致）。
-	*/
-	confine(argv, policy) {
-		const confined = super.confine(argv, policy);
+	async confine(argv, policy, signal) {
+		const confined = await super.confine(argv, policy, signal);
 		const rules = this.rulesFor(policy.workspaceRoot);
 		const effective = policy.mode === "workspace-write" ? rules : withoutAllowRoots(rules);
 		if (isEmptyRules(effective)) return confined;
@@ -518,7 +353,6 @@ var ConfigurableSandboxProvider = class extends LocalSandboxProvider {
 			argv: extendConfinedArgv(confined.argv, effective)
 		};
 	}
-	/** 取（并按需编译缓存）某个工作区根下的规则。 */
 	rulesFor(workspaceRoot) {
 		const cached = this.compiled.get(workspaceRoot);
 		if (cached !== void 0) return cached;
@@ -529,15 +363,6 @@ var ConfigurableSandboxProvider = class extends LocalSandboxProvider {
 };
 //#endregion
 //#region src/config.ts
-/**
-* 插件配置的单一真源：`access` 规则 + 透传官方的字段。
-*
-* 规则只在这里声明一次——provider 与 fs 后端按构造参数接收已解析的配置，
-* 不各自重复声明 schema；部署层的规则值随插入本行的 patch 写死（本部署见
-* `@morlay/dsh-preset`），包内不预设。
-* @module @morlay/dsh-sandbox-local/config
-*/
-/** 运行时配置 schema。 */
 const Config = z.object({
 	access: z.union([z.array(z.string()), z.string()]).default([]),
 	runnerCommand: z.array(z.string()).default([]),
@@ -548,15 +373,8 @@ const Config = z.object({
 });
 //#endregion
 //#region src/index.ts
-/** Cordis 插件名。 */
 const name = "sandbox-local";
-/** fs 侧从策略服务取默认模式与工作区回退根，所以先等 `ctx.sandboxPolicy`。 */
 const inject = ["sandboxPolicy"];
-/**
-* 规则在进程沙箱侧的能力随平台方言变化，加载期把降级说清楚：
-* `ctx.fs` 侧（read / write / edit 工具）在 macOS / Linux / Windows 上语义一致，
-* 只有 bash 等子进程走平台 runner 的表达能力。
-*/
 function warnAboutDegradedRules(ctx, config) {
 	const rules = ruleSourceOf(config, process.env);
 	const grants = rules.allowWrite.length > 0;
@@ -571,11 +389,6 @@ function warnAboutDegradedRules(ctx, config) {
 	}
 	if (grants && process.platform === "win32") ctx.logger.warn("sandbox-local: \"rw\" entries cannot be granted to confined subprocesses on win32; ctx.fs covers the extra roots, the Windows ACL runner does not");
 }
-/**
-* 注册两个替换实现。
-* @param ctx - 插件上下文（官方 `sandbox` / `fs-sandbox` 行已禁用）。
-* @param config - 已由 schema 填好默认值的配置。
-*/
 function apply(ctx, config) {
 	warnAboutDegradedRules(ctx, config);
 	new ConfigurableSandboxProvider(ctx, config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morlay/dsh-sandbox-local",
-  "version": "0.0.2",
+  "version": "0.0.3-alpha.0",
   "description": "Configurable sandbox bundle: replaces the shipped process-sandbox provider and filesystem fence with implementations that add extra writable roots and access denials on top of the upstream semantics.",
   "keywords": [
     "dsh",
@@ -12,7 +12,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/morlay/better-session.git"
+    "url": "https://github.com/morlay/dsh-plugin.git"
   },
   "files": [
     "dist",
@@ -28,21 +28,21 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-fs-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-fs-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-fs": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-fs-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-fs-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-sandbox-policy": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-fs": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-fs-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-sandbox-policy": "^0.1.6-alpha.2",
     "@deepseek-ai/schemastery": "^3.18.2"
   },
   "dsh": {

package/src/config.ts

@@ -1,26 +1,11 @@
-/**
- * 插件配置的单一真源：`access` 规则 + 透传官方的字段。
- *
- * 规则只在这里声明一次——provider 与 fs 后端按构造参数接收已解析的配置，
- * 不各自重复声明 schema；部署层的规则值随插入本行的 patch 写死（本部署见
- * `@morlay/dsh-preset`），包内不预设。
- * @module @morlay/dsh-sandbox-local/config
- */
-
 import z from "@deepseek-ai/schemastery";
 import type { Config as UpstreamFsConfig } from "@deepseek-ai/dsh-fs-local";
 import type { Config as UpstreamSandboxConfig } from "@deepseek-ai/dsh-sandbox-local";
 
-/** 插件配置。 */
 export interface Config extends UpstreamSandboxConfig, UpstreamFsConfig {
-  /**
-   * 规则条目：`rw <path>`（额外可写根）、`r- <path>`（只读）、`-- <pattern>`（拒绝访问）。
-   * 数组每项一条，或写一段多行文本（每行一条）；`{{ env.NAME }}` 按进程环境展开。
-   */
   access?: string | string[];
 }
 
-/** 运行时配置 schema。 */
 export const Config: z<Config> = z.object({
   access: z.union([z.array(z.string()), z.string()]).default([]),
   runnerCommand: z.array(z.string()).default([]),

package/src/containment.ts

@@ -1,20 +1,9 @@
-/**
- * 目标是否位于某个可写根之下的判定。
- *
- * 语义与上游 `@deepseek-ai/dsh-fs-sandbox/src/containment.ts` 对齐（canonical 拼写走
- * 词法快路径，别名/大小写差异由文件系统身份兜底）；本包自带一份，是因为该模块只存在于
- * 上游包的 `src/` 深处，而发布产物（`lib/`）与安装态 profile 的模块解析都不覆盖深路径。
- * @module @morlay/dsh-sandbox-local/containment
- */
-
 import type { BigIntStats } from "node:fs";
 import { stat } from "node:fs/promises";
 import { dirname, sep } from "node:path";
 
-/** 视为“路径不存在”的错误码：只有它们能让祖先遍历继续。 */
 const MISSING_CODES: ReadonlySet<string> = new Set(["ENOENT", "ENOTDIR"]);
 
-/** stat 一次，缺失返回 undefined；其它失败（权限、I/O）继续抛出。 */
 async function statIfPresent(path: string): Promise<BigIntStats | undefined> {
   try {
     return await stat(path, { bigint: true });
@@ -25,12 +14,10 @@ async function statIfPresent(path: string): Promise<BigIntStats | undefined> {
   }
 }
 
-/** 按大小写敏感性归一用于比较的拼写。 */
 function comparablePath(path: string, caseSensitive: boolean): string {
   return caseSensitive ? path : path.toLowerCase();
 }
 
-/** 词法包含判定（目标可带尚不存在的后缀）。 */
 function isLexicallyUnder(path: string, root: string, caseSensitive: boolean): boolean {
   const comparableTarget = comparablePath(path, caseSensitive);
   const comparableRoot = comparablePath(root, caseSensitive);
@@ -39,20 +26,10 @@ function isLexicallyUnder(path: string, root: string, caseSensitive: boolean): b
   return comparableTarget.startsWith(prefix);
 }
 
-/** 两次 stat 是否指向同一个文件系统对象。 */
 function sameIdentity(left: BigIntStats, right: BigIntStats): boolean {
   return left.dev === right.dev && left.ino === right.ino;
 }
 
-/**
- * 判断 canonical 目标是否就是某个根或位于其下。
- * 拼写不同时（Windows 长名/8.3 别名、大小写差异）沿目标的现存祖先比较文件系统身份，
- * 不把包含判定弱化成文本近似。
- * @param path - 目标的 canonical 路径（可带尚不存在的尾部）。
- * @param root - canonical 可写根。
- * @param caseSensitive - 词法比较是否区分大小写；默认按宿主平台约定。
- * @returns 目标是该根或其后代时为 true。
- */
 export async function isPathUnder(
   path: string,
   root: string,

package/src/dialects.ts

@@ -1,40 +1,19 @@
-/**
- * 在官方 provider 生成的 confined argv 上追加本包规则：
- * Seatbelt 追加 SBPL 规则（后置规则覆盖先前的 allow，实测 `(deny file-read* file-write*
- * (subpath …))` 能压过 `(allow file-write* (subpath …))`，`r-` 条目则只 deny 写入），
- * bwrap 追加挂载参数（`rw` 用 `--bind-try`，`r-` 与 `--` 都用 `--ro-bind-try`），
- * Landlock 只能追加可写授权（其 allow-list 语义无法减除子路径），
- * Windows ACL runner 没有对应表达。
- *
- * 方言从官方 `ConfinedArgv.argv` 的结构识别：runner 参数在前，`--` 之后是调用方 argv。
- * @module @morlay/dsh-sandbox-local/dialects
- */
-
 import { isEmptyRules, type CompiledRules } from "./rules.ts";
 
-/** 官方 provider 可选的执行方言。 */
 export type SandboxDialect = "seatbelt" | "bwrap" | "landlock" | "windows-acl";
 
-/** runner 部分与调用方 argv 的分隔符。 */
 const SEPARATOR = "--";
 
-/**
- * 一个方言能表达的规则能力。
- * `readOnly` 指 `r-` 条目（只拒写入）；`denyWriteOnly` 指 `--` 条目在该方言上只能
- * 退化为“只拒写入”（读取仍放行）。
- */
 export interface DialectCapabilities {
-  /** 能否把额外可写根写进 runner 参数。 */
   readonly allowWrite: boolean;
-  /** 能否表达 `r-`（只拒写入）。 */
+
   readonly readOnly: boolean;
-  /** 能否表达 `--` 的完整语义（读与写都拒）。 */
+
   readonly denyReadWrite: boolean;
-  /** `--` 是否只能退化为拒绝写入。 */
+
   readonly denyWriteOnly: boolean;
 }
 
-/** 各方言的规则表达能力——加载期据此告警，运行期据此决定是否改写参数。 */
 export const DIALECT_CAPABILITIES: Record<SandboxDialect, DialectCapabilities> = {
   seatbelt: { allowWrite: true, readOnly: true, denyReadWrite: true, denyWriteOnly: false },
   bwrap: { allowWrite: true, readOnly: true, denyReadWrite: false, denyWriteOnly: true },
@@ -42,7 +21,6 @@ export const DIALECT_CAPABILITIES: Record<SandboxDialect, DialectCapabilities> =
   "windows-acl": { allowWrite: false, readOnly: false, denyReadWrite: false, denyWriteOnly: false },
 };
 
-/** runner 部分的结束位置。 */
 function separatorIndex(argv: readonly string[]): number {
   const index = argv.indexOf(SEPARATOR);
   if (index === -1) {
@@ -51,11 +29,6 @@ function separatorIndex(argv: readonly string[]): number {
   return index;
 }
 
-/**
- * 识别 argv 使用的执行方言。
- * @param argv - 官方 provider 返回的完整 confined argv。
- * @returns 方言，或无法识别时的 `undefined`（例如运维自定义的 runnerCommand）。
- */
 export function dialectOf(argv: readonly string[]): SandboxDialect | undefined {
   const separator = argv.indexOf(SEPARATOR);
   const runner = separator === -1 ? argv : argv.slice(0, separator);
@@ -66,15 +39,10 @@ export function dialectOf(argv: readonly string[]): SandboxDialect | undefined {
   return undefined;
 }
 
-/** SBPL 字符串字面量。 */
 function sbplString(value: string): string {
   return `"${value.replaceAll("\\", String.raw`\\`).replaceAll('"', String.raw`\"`)}"`;
 }
 
-/**
- * SBPL `#"…"` 的正则体：正则自身的 `\` 必须保留（glob 翻译用它转义元字符），
- * 因此拒绝项里出现双引号时直接报错，而不是产出一个含义变化的 profile。
- */
 function sbplRegexBody(source: string): string {
   if (source.includes('"')) {
     throw new Error(
@@ -84,7 +52,6 @@ function sbplRegexBody(source: string): string {
   return source;
 }
 
-/** Seatbelt：把 allow / deny 规则追加到 `-p` 的 profile 文本末尾。 */
 function extendSeatbelt(argv: readonly string[], rules: CompiledRules): string[] {
   const index = argv.indexOf("-p");
   const profile = index === -1 ? undefined : argv[index + 1];
@@ -108,11 +75,6 @@ function extendSeatbelt(argv: readonly string[], rules: CompiledRules): string[]
   return [...argv.slice(0, index + 1), extended, ...argv.slice(index + 2)];
 }
 
-/**
- * bwrap：额外可写根用 `--bind-try`（路径不存在时跳过）；`r-` 与 `--` 都用
- * `--ro-bind-try` 覆盖成只读（挂载后行覆盖前行）——也就是说 `--` 在 bwrap 上退化为
- * “只拒写入”。glob 模式无法表达为静态挂载，由调用方在加载期告警。
- */
 function extendBwrap(argv: readonly string[], rules: CompiledRules): string[] {
   const separator = separatorIndex(argv);
   const additions: string[] = [];
@@ -123,19 +85,12 @@ function extendBwrap(argv: readonly string[], rules: CompiledRules): string[] {
   return [...argv.slice(0, separator), ...additions, ...argv.slice(separator)];
 }
 
-/** Landlock：只能追加可写授权（`--rw`），`r-` 与 `--` 都无对应表达。 */
 function extendLandlock(argv: readonly string[], rules: CompiledRules): string[] {
   const separator = separatorIndex(argv);
   const additions = rules.allowRoots.flatMap((root) => ["--rw", root]);
   return [...argv.slice(0, separator), ...additions, ...argv.slice(separator)];
 }
 
-/**
- * 按 argv 的方言追加规则。
- * @param argv - 官方 provider 返回的 confined argv。
- * @param rules - 已编译规则；空规则原样返回。
- * @returns 追加规则后的 argv；方言无法识别时抛错（规则不能静默失效）。
- */
 export function extendConfinedArgv(argv: readonly string[], rules: CompiledRules): string[] {
   if (isEmptyRules(rules)) return [...argv];
   const dialect = dialectOf(argv);
@@ -152,7 +107,6 @@ export function extendConfinedArgv(argv: readonly string[], rules: CompiledRules
     case "landlock":
       return extendLandlock(argv, rules);
     case "windows-acl":
-      // windows-acl 的 runner 参数没有承载额外 grant 的入口：加载期已告警，这里保持原 argv。
       return [...argv];
   }
 }

package/src/fs.ts

@@ -1,14 +1,3 @@
-/**
- * 文件系统围栏：继承官方 `@deepseek-ai/dsh-fs-local` 的文本存储机制
- * （resolve / stat / 读流 / 原子写 / read-match-write 编辑），在访问入口叠加规则：
- * `--` 命中即拒绝访问（读与写都拒，任何模式下都生效），`r-` 只拒写入，`rw` 参与
- * `workspace-write` 的可写判定（官方 `writableRoots` 之外的额外可写根）。
- *
- * 与它替换掉的官方 `@deepseek-ai/dsh-fs-sandbox` 一样，这是受信代码里的策略检查，
- * 不是内核边界：内核级隔离仍由 `ctx.sandbox` 侧负责。
- * @module @morlay/dsh-sandbox-local/fs
- */
-
 import type { Context } from "@deepseek-ai/cordis";
 import { FsError } from "@deepseek-ai/dsh-fs";
 import type {
@@ -34,18 +23,12 @@ import {
   type RuleSource,
 } from "./rules.ts";
 
-/**
- * 官方本机文件系统后端的可配置版本。
- * `--` 条目在解析阶段拒绝目标（覆盖 read / write / edit / list 等一切工具入口），
- * `r-` 与 `--` 条目在写入前拒绝写入（优先于任何可写根），写操作再按
- * `workspace-write` + `rw` 条目复核 containment。
- */
 export class ConfigurableFileSystem extends LocalFileSystem {
   static inject = ["sandboxPolicy"];
 
   private readonly defaultMode: SandboxMode;
   private readonly source: RuleSource;
-  /** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
+
   private readonly compiled = new Map<string, CompiledRules>();
 
   constructor(ctx: Context, config: Config) {
@@ -54,18 +37,10 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     this.source = ruleSourceOf(config, process.env);
   }
 
-  /** 工具层读它判断后端是否 confine（并据此广告 escalation 字段）。 */
   override get sandboxMode(): SandboxMode {
     return this.defaultMode;
   }
 
-  /**
-   * 解析目标后立即执行拒绝判定：工具入口（read / write / edit / list）都先经过
-   * `resolve`，因此一次判定即可覆盖读与写。
-   * @param path - 待解析的路径。
-   * @param opts - cwd 与取消信号；cwd 同时是相对规则的解析根。
-   * @returns 解析后的目标。
-   */
   override async resolve(
     path: string,
     opts?: { cwd?: string; signal?: AbortSignal },
@@ -79,15 +54,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     return target;
   }
 
-  /**
-   * 按 per-call 策略复核后写入。
-   * @param target - 工具解析出的目标。
-   * @param content - 新的完整内容。
-   * @param expected - 写入前版本守卫。
-   * @param signal - 取消信号。
-   * @param sandboxPolicy - per-call 策略；省略时用部署默认。
-   * @returns 上游写入结果。
-   */
   override async writeText(
     target: FsTarget,
     content: string,
@@ -103,15 +69,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     );
   }
 
-  /**
-   * 按 per-call 策略复核后编辑。
-   * @param target - 工具解析出的目标。
-   * @param edit - 字面量 search/replace 请求。
-   * @param expected - 版本守卫。
-   * @param signal - 取消信号。
-   * @param sandboxPolicy - per-call 策略；省略时用部署默认。
-   * @returns 上游编辑结果。
-   */
   override async editText(
     target: FsTarget,
     edit: FsEditRequest,
@@ -122,7 +79,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     return super.editText(await this.checkedTarget(target, sandboxPolicy), edit, expected, signal);
   }
 
-  /** `--` 条目命中即拒绝访问（读与写都拒）；抛 `FS_SANDBOX_DENIED`。 */
   private assertNotDenied(
     rules: CompiledRules,
     canonicalTarget: string,
@@ -135,7 +91,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     );
   }
 
-  /** `--` 或 `r-` 条目命中即拒绝写入，且优先于任何可写根。 */
   private assertWritable(rules: CompiledRules, canonicalTarget: string, displayPath: string): void {
     this.assertNotDenied(rules, canonicalTarget, displayPath);
     if (!isReadOnly(rules, canonicalTarget)) return;
@@ -145,10 +100,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     );
   }
 
-  /**
-   * 写前复核：`--` / `r-` 条目（任何模式）→ 模式本身的只读拒绝 → `workspace-write` 的
-   * `writableRoots + rw` containment，返回必须被写入的那个目标。
-   */
   private async checkedTarget(
     target: FsTarget,
     sandboxPolicy?: SandboxExecutionPolicy,
@@ -164,8 +115,7 @@ export class ConfigurableFileSystem extends LocalFileSystem {
         "FS_SANDBOX_DENIED",
       );
     }
-    // workspace-write：在新鲜解析出的 canonical 目标上复核，写入也用它（避免
-    // “检查这里、写那里”的 TOCTOU 窗口）。
+
     const fresh = await super.resolve(target.displayPath);
     this.assertWritable(rules, fresh.targetKey, fresh.displayPath);
     for (const root of [...writableRoots(policy), ...rules.allowRoots]) {
@@ -177,7 +127,6 @@ export class ConfigurableFileSystem extends LocalFileSystem {
     );
   }
 
-  /** 取（并按需编译缓存）某个工作区根下的规则。 */
   private rulesFor(workspaceRoot: string): CompiledRules {
     const cached = this.compiled.get(workspaceRoot);
     if (cached !== undefined) return cached;

package/src/index.ts

@@ -1,19 +1,3 @@
-/**
- * 可配置沙箱插件：替换官方进程沙箱 provider（`ctx.sandbox`）与文件系统后端（`ctx.fs`），
- * 在官方语义之上叠加 `access` 规则。
- *
- * 每条规则以 `rw ` / `r- ` / `-- ` 开头：`rw <path>` 是工作区与平台临时目录之外的额外
- * 可写根，`r- <path>` 是只读（读放行、写拒绝），`-- <pattern>` 是访问拒绝（读 + 写）。
- * 三条都支持 `{{ env.NAME }}`（加载期展开，引用未定义的环境变量直接失败）与相对工作区的
- * 路径；命中优先级是 `--` > `r-` > 可写根。`ctx.fs` 侧语义完整，`ctx.sandbox` 侧在能表达
- * 该语义的方言上生效（见 {@link DIALECT_CAPABILITIES}）。
- *
- * 装配前提：官方 `sandbox` 与 `fs-sandbox` 行必须被禁用（包内 `cordis.patch.yml` 或
- * 部署层 patch），否则同名服务 fail loud；规则由部署层在插入本行时写死
- * （本部署见 `@morlay/dsh-preset`），包内不预设。
- * @module @morlay/dsh-sandbox-local
- */
-
 import type { Context } from "@deepseek-ai/cordis";
 import type { Config } from "./config.ts";
 import { DIALECT_CAPABILITIES } from "./dialects.ts";
@@ -21,20 +5,12 @@ import { ConfigurableFileSystem } from "./fs.ts";
 import { ruleSourceOf } from "./rules.ts";
 import { ConfigurableSandboxProvider } from "./sandbox.ts";
 
-// 值与类型一起转出：Loader 读 `Config`（schema），消费方读类型。
 export { Config } from "./config.ts";
 
-/** Cordis 插件名。 */
 export const name = "sandbox-local";
 
-/** fs 侧从策略服务取默认模式与工作区回退根，所以先等 `ctx.sandboxPolicy`。 */
 export const inject = ["sandboxPolicy"];
 
-/**
- * 规则在进程沙箱侧的能力随平台方言变化，加载期把降级说清楚：
- * `ctx.fs` 侧（read / write / edit 工具）在 macOS / Linux / Windows 上语义一致，
- * 只有 bash 等子进程走平台 runner 的表达能力。
- */
 function warnAboutDegradedRules(ctx: Context, config: Config): void {
   const rules = ruleSourceOf(config, process.env);
   const grants = rules.allowWrite.length > 0;
@@ -60,11 +36,6 @@ function warnAboutDegradedRules(ctx: Context, config: Config): void {
   }
 }
 
-/**
- * 注册两个替换实现。
- * @param ctx - 插件上下文（官方 `sandbox` / `fs-sandbox` 行已禁用）。
- * @param config - 已由 schema 填好默认值的配置。
- */
 export function apply(ctx: Context, config: Config): void {
   warnAboutDegradedRules(ctx, config);
   new ConfigurableSandboxProvider(ctx, config);

package/src/rules.ts

@@ -1,32 +1,15 @@
-/**
- * 规则编译：`access` 条目解析（`rw <path>` 额外可写根 / `r- <path>` 只读 /
- * `-- <pattern>` 拒绝访问）、`{{ env.NAME }}` 模板展开、相对工作区路径的绝对化、
- * glob → 正则，以及编译结果的匹配。
- *
- * 命中优先级：`--` 拒绝覆盖一切；`r-` 只读覆盖可写授予；都未命中时才按可写根判定。
- *
- * 生成的正则源码同时交给进程内检查（JS `RegExp`）与 macOS Seatbelt profile
- * （SBPL 的 `(regex #"…")`），因此只用 POSIX ERE 与 JS 正则共有的语法。
- * @module @morlay/dsh-sandbox-local/rules
- */
-
 import { isAbsolute, resolve, sep } from "node:path";
 import { canonicalPath, writableRoots } from "@deepseek-ai/dsh-sandbox";
 import type { SandboxExecutionPolicy } from "@deepseek-ai/dsh-sandbox";
 
-/** `{{ env.NAME }}` 模板；名字限定为环境变量的字符集。 */
 const ENV_TEMPLATE = /\{\{\s*env\.([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
 
-/** `access` 的条目形式：`rw <path>` / `r- <path>` / `-- <pattern>`；前缀后必须有空白。 */
 const ACCESS_LINE = /^(rw|r-|--)(?:\s+(.*))?$/u;
 
-/** glob 元字符：规则里出现即按模式匹配，否则按字面路径（含其全部后代）匹配。 */
 const GLOB_META = /[*?[]/;
 
-/** glob 翻译时需要转义的正则元字符（字符类内部除外）。 */
 const REGEX_META = /[\\^$+.(){}|]/;
 
-/** 展开规则里的 `{{ env.NAME }}`；引用未定义或为空的环境变量直接抛错。 */
 export function expandEnvTemplates(value: string, env: NodeJS.ProcessEnv): string {
   return value.replace(ENV_TEMPLATE, (_match, name: string) => {
     const resolved = env[name];
@@ -39,13 +22,6 @@ export function expandEnvTemplates(value: string, env: NodeJS.ProcessEnv): strin
   });
 }
 
-/**
- * 把含 glob 的规则翻译成正则源码。
- * `**` 跨目录层级（`**` 与“`**` 后接斜杠”都能匹配零层），`*` 与 `?` 不跨 `/`，
- * 字符类透传（`[!…]` 按 glob 习惯翻成 `[^…]`），其余正则元字符转义。
- * @param pattern - 已绝对化的 glob 规则。
- * @returns 可同时被 JS `RegExp` 与 SBPL regex 接受的正则源码。
- */
 export function globToRegexSource(pattern: string): string {
   let source = "";
   for (let index = 0; index < pattern.length; index += 1) {
@@ -89,39 +65,32 @@ export function globToRegexSource(pattern: string): string {
   return source;
 }
 
-/** 规则来源：模板已在加载期展开，路径仍是相对/绝对的原始拼写。 */
 export interface RuleSource {
-  /** `rw` 条目：额外可写根。 */
   readonly allowWrite: readonly string[];
-  /** `r-` 条目：只读（读放行、写拒绝）。 */
+
   readonly readOnly: readonly string[];
-  /** `--` 条目：拒绝访问（读 + 写）。 */
+
   readonly deny: readonly string[];
 }
 
-/** 一条已编译的模式：源码同时供 JS `RegExp` 与 SBPL regex 使用。 */
 export interface CompiledPattern {
-  /** 正则源码。 */
   readonly source: string;
-  /** 进程内检查用的已编译正则。 */
+
   readonly regex: RegExp;
 }
 
-/** 编译后的规则：按一个工作区根绝对化后的可写根、只读项与拒绝项。 */
 export interface CompiledRules {
-  /** 额外可写根（canonical 绝对路径）。 */
   readonly allowRoots: readonly string[];
-  /** 只读的字面路径（canonical）：命中自身及其全部后代。 */
+
   readonly readOnlySubtrees: readonly string[];
-  /** 只读的模式。 */
+
   readonly readOnlyPatterns: readonly CompiledPattern[];
-  /** 拒绝访问的字面路径（canonical）：命中自身及其全部后代。 */
+
   readonly denySubtrees: readonly string[];
-  /** 拒绝访问的模式。 */
+
   readonly denyPatterns: readonly CompiledPattern[];
 }
 
-/** 规则是否为空——空规则下 provider 不改写任何 runner 参数。 */
 export function isEmptyRules(rules: CompiledRules): boolean {
   return (
     rules.allowRoots.length === 0 &&
@@ -132,18 +101,10 @@ export function isEmptyRules(rules: CompiledRules): boolean {
   );
 }
 
-/** 只读模式不因 `rw` 条目放松：投影出只保留 `r-` / `--` 条目的规则集。 */
 export function withoutAllowRoots(rules: CompiledRules): CompiledRules {
   return rules.allowRoots.length === 0 ? rules : { ...rules, allowRoots: [] };
 }
 
-/**
- * 解析 `access` 配置：接受字符串数组（每项一条规则）或多行文本（每行一条规则），
- * 空行忽略；`rw <path>` 是额外可写根，`r- <path>` 是只读，`-- <pattern>` 是访问
- * 拒绝（读 + 写）。缺前缀或前缀后没有路径都直接报错——规则不因写法歧义而变形。
- * @param input - 配置里的 `access` 值。
- * @returns `allowWrite` / `readOnly` / `deny` 三组规则（模板尚未展开）。
- */
 export function parseAccess(input: string | readonly string[] | undefined): RuleSource {
   const lines = (input === undefined ? [] : typeof input === "string" ? [input] : [...input])
     .flatMap((value) => value.split(/\r?\n/u))
@@ -170,13 +131,6 @@ export function parseAccess(input: string | readonly string[] | undefined): Rule
   return { allowWrite, readOnly, deny };
 }
 
-/**
- * 把配置里的 `access` 转成规则来源：模板在这一步展开（加载期，fail-fast），
- * 相对路径留待按调用时的工作区根绝对化。
- * @param config - 含 `access` 的插件配置。
- * @param env - 模板展开用的进程环境。
- * @returns 模板已展开的规则来源。
- */
 export function ruleSourceOf(
   config: { access?: string | readonly string[] },
   env: NodeJS.ProcessEnv,
@@ -191,12 +145,10 @@ export function ruleSourceOf(
   };
 }
 
-/** 绝对化一条规则：相对路径相对工作区根。 */
 function absolutize(value: string, workspaceRoot: string): string {
   return isAbsolute(value) ? value : resolve(workspaceRoot, value);
 }
 
-/** 编译一组字面路径 / glob 规则：字面项按子树（含全部后代）匹配，glob 项按整串匹配。 */
 function compilePaths(
   values: readonly string[],
   workspaceRoot: string,
@@ -215,13 +167,6 @@ function compilePaths(
   return { subtrees, patterns };
 }
 
-/**
- * 按一个工作区根编译规则。
- * `rw` 条目必须是具体路径（glob 无法表达“可写根”）；`r-` 与 `--` 条目允许 glob。
- * @param source - 已展开模板的规则来源。
- * @param workspaceRoot - 相对规则解析用的工作区根（canonical 绝对路径）。
- * @returns 编译后的规则。
- */
 export function compileRules(source: RuleSource, workspaceRoot: string): CompiledRules {
   const allowRoots: string[] = [];
   for (const value of source.allowWrite) {
@@ -241,13 +186,6 @@ export function compileRules(source: RuleSource, workspaceRoot: string): Compile
   };
 }
 
-/**
- * 一次调用可写入的根集合：官方 `writableRoots` 加上 `rw` 条目；`read-only` 不追加
- * （额外可写根不放松显式选定的只读边界）。
- * @param rules - 已编译规则。
- * @param policy - per-call 策略。
- * @returns canonical 可写根列表。
- */
 export function writableRootsWith(
   rules: CompiledRules,
   policy: SandboxExecutionPolicy,
@@ -256,13 +194,11 @@ export function writableRootsWith(
   return policy.mode === "workspace-write" ? [...roots, ...rules.allowRoots] : roots;
 }
 
-/** 字面规则的后代判定（canonical 拼写，与 Seatbelt `subpath` 同一语义）。 */
 function isUnder(path: string, root: string): boolean {
   if (path === root) return true;
   return path.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
 }
 
-/** 命中任一子树或任一模式。 */
 function matches(
   canonicalTarget: string,
   subtrees: readonly string[],
@@ -274,32 +210,14 @@ function matches(
   return patterns.some((pattern) => pattern.regex.test(canonicalTarget));
 }
 
-/**
- * 判断目标是否被 `--` 条目命中（读与写都拒）。
- * @param rules - 已编译规则。
- * @param canonicalTarget - 目标的 canonical 路径。
- * @returns 命中即 true。
- */
 export function isDenied(rules: CompiledRules, canonicalTarget: string): boolean {
   return matches(canonicalTarget, rules.denySubtrees, rules.denyPatterns);
 }
 
-/**
- * 判断目标是否被 `r-` 条目命中（读放行、写拒绝）。
- * @param rules - 已编译规则。
- * @param canonicalTarget - 目标的 canonical 路径。
- * @returns 命中即 true。
- */
 export function isReadOnly(rules: CompiledRules, canonicalTarget: string): boolean {
   return matches(canonicalTarget, rules.readOnlySubtrees, rules.readOnlyPatterns);
 }
 
-/**
- * 判断目标是否不可写：`--` 与 `r-` 条目都拒绝写入，且优先于任何可写根。
- * @param rules - 已编译规则。
- * @param canonicalTarget - 目标的 canonical 路径。
- * @returns 命中即 true。
- */
 export function blocksWrite(rules: CompiledRules, canonicalTarget: string): boolean {
   return isDenied(rules, canonicalTarget) || isReadOnly(rules, canonicalTarget);
 }

package/src/sandbox.ts

@@ -1,13 +1,3 @@
-/**
- * 进程沙箱 provider：继承官方 `@deepseek-ai/dsh-sandbox-local` 的实现（runner 探测与
- * 选择、Windows ACL 的私有 temp 流程、拒绝方言与 runner 失败规则全部保留），
- * 只在 `confine` 产出的 argv 上追加本包的 `access` 条目（`rw` / `r-` / `--`）。
- *
- * 服务键沿用上游基类的 `ctx.sandbox`；装配时官方 `sandbox` 行必须被禁用，
- * 否则同名服务会 fail loud。
- * @module @morlay/dsh-sandbox-local/sandbox
- */
-
 import type { Context } from "@deepseek-ai/cordis";
 import type { ConfinedArgv, SandboxPolicy } from "@deepseek-ai/dsh-sandbox";
 import { LocalSandboxProvider } from "@deepseek-ai/dsh-sandbox-local";
@@ -22,14 +12,9 @@ import {
   type RuleSource,
 } from "./rules.ts";
 
-/**
- * 官方本机沙箱 provider 的可配置版本。
- * `read-only` 模式不追加 `rw` 条目（只读边界不因额外可写根放松）；`--` 条目在两种
- * confined 模式下都生效。
- */
 export class ConfigurableSandboxProvider extends LocalSandboxProvider {
   private readonly source: RuleSource;
-  /** 规则按工作区根编译一次（相对规则相对该调用的工作区）。 */
+
   private readonly compiled = new Map<string, CompiledRules>();
 
   constructor(ctx: Context, config: Config) {
@@ -37,21 +22,18 @@ export class ConfigurableSandboxProvider extends LocalSandboxProvider {
     this.source = ruleSourceOf(config, process.env);
   }
 
-  /**
-   * 官方拼装 + 规则追加。
-   * @param argv - 调用方即将 spawn 的 argv。
-   * @param policy - 本次调用的文件效果策略。
-   * @returns 追加规则后的 confined argv（空规则时与官方结果一致）。
-   */
-  override confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv {
-    const confined = super.confine(argv, policy);
+  override async confine(
+    argv: readonly string[],
+    policy: SandboxPolicy,
+    signal?: AbortSignal,
+  ): Promise<ConfinedArgv> {
+    const confined = await super.confine(argv, policy, signal);
     const rules = this.rulesFor(policy.workspaceRoot);
     const effective = policy.mode === "workspace-write" ? rules : withoutAllowRoots(rules);
     if (isEmptyRules(effective)) return confined;
     return { ...confined, argv: extendConfinedArgv(confined.argv, effective) };
   }
 
-  /** 取（并按需编译缓存）某个工作区根下的规则。 */
   private rulesFor(workspaceRoot: string): CompiledRules {
     const cached = this.compiled.get(workspaceRoot);
     if (cached !== undefined) return cached;