Merge branch 'master' into steering-unwrap

2026-07-20 17:02:18 +08:00
parent f593ef5ab5 34c0800d3c
commit bd99e8d04a
175 changed files with 8626 additions and 852 deletions
--- a/website/.vitepress/config/api-sidebar.json
+++ b/website/.vitepress/config/api-sidebar.json
@@ -66,6 +66,10 @@
      "text": "ctx.sandbox",
      "link": "/zh-CN/api/harness/sandbox"
    },
+    {
+      "text": "ctx.sandboxPolicy",
+      "link": "/zh-CN/api/harness/sandbox-policy"
+    },
    {
      "text": "ctx.sessionPersistence",
      "link": "/zh-CN/api/harness/session-persistence"
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -6,7 +6,7 @@

 Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The namespace is rebuilt for every model bash call: ambient `DSH_*` values are discarded by the executor, then the registry's current snapshot is injected. Built-in shell facts remain owned by the registry itself while plugins can register additional, enumerable facts with effect-scoped disposal.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L102)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L103)

 ### ctx.bashEnv.register(contributor)

@@ -26,7 +26,7 @@ Register one environment contributor. Names and keys are unique; built-in keys a

 **Returns** the disposer that unregisters the contribution.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L123)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L124)

 ### ctx.bashEnv.collect(execution)

@@ -45,7 +45,7 @@ Build the trusted `DSH_*` snapshot for one bash tool execution.

 **Returns** an immutable environment overlay containing built-ins and current contributions.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L165)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L166)

 ### ctx.bashEnv.list()

@@ -61,4 +61,4 @@ Enumerate plugin-contributed variables without executing their resolvers.

 **Returns** declarations sorted by environment variable name.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L197)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/tool-bash/src/index.ts#L198)
--- a/website/zh-CN/api/harness/bash.md
+++ b/website/zh-CN/api/harness/bash.md
@@ -11,7 +11,7 @@ Implementations must honor these semantics:
 - BashProcess.readOutput is incremental: consecutive reads never repeat output. Lossy reads report truncation and available spill files.
 - Disposal kills all running background processes and awaits their exit.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L49)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L48)

 ### ctx.bash.sandboxMode

@@ -26,7 +26,7 @@ get sandboxMode(): SandboxMode | undefined

 The sandbox mode this executor applies by default, or `undefined` when it does not sandbox commands.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L59)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L58)

 ### ctx.bash.resolve(request)

@@ -46,7 +46,7 @@ Apply implementation-owned defaults and caps to a request before execution.

 **Returns** the fully-specified spec to hand to `run`/`start`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L69)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L68)

 ### ctx.bash.run(spec)

@@ -66,7 +66,7 @@ Run a command in the foreground; resolves when it finishes.

 **Returns** the outcome; nonzero exits, timeout kills, and abort kills resolve with a descriptive result rather than reject.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L77)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L76)

 ### ctx.bash.start(spec)

@@ -85,4 +85,4 @@ Start a background process and return its handle immediately.

 **Returns** the live process handle (reads, kill, quiescence promise).

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L84)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L83)
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -470,7 +470,7 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 - `target` — the resolved target about to be edited.
 - `actor` — the opaque tool-execution context the decider keys off.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L61)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L62)

 ### fs/observed

@@ -494,7 +494,7 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 - `version` — the version the actor now holds as its observation.
 - `actor` — the observing tool-execution context; undefined records nothing useful.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L70)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L71)

 ### fs/write-intent

@@ -517,7 +517,7 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 - `target` — the resolved target about to be written.
 - `actor` — the opaque tool-execution context the decider keys off.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L53)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L54)

 ## llm/*

--- a/website/zh-CN/api/harness/fs.md
+++ b/website/zh-CN/api/harness/fs.md
@@ -6,7 +6,30 @@

 Abstract filesystem provider. Targets must preserve identity across aliases; reads expose regular UTF-8 text or typed errors, listings are stable and content-free, and mutations are atomic. Optional guards add stale protection without changing the unguarded provider contract.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L80)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L81)
+
+### ctx.fs.sandboxMode
+
+```ts website-api
+/**
+/**
+ * The sandbox mode this backend enforces on mutations BY DEFAULT, or
+ * `undefined` when it does not confine at all — the capability fact the tool
+ * layer reads to advertise the escalation fields honestly (mirrors
+ * `BashExecutor.sandboxMode`). The base class and the bare local backend
+ * report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`)
+ * overrides it with the deployment default. A session override may make the
+ * effective mode narrower or wider, so strict escalation widening is checked
+ * per call rather than encoded in this default-relative fact.
+ * @returns the configured default mode of a sandboxing backend; `undefined`
+ *   for a backend that never confines.
+ */
+get sandboxMode(): SandboxMode | undefined
+```
+
+/** The sandbox mode this backend enforces on mutations BY DEFAULT, or `undefined` when it does not confine at all — the capability fact the tool layer reads to advertise the escalation fields honestly (mirrors `BashExecutor.sandboxMode`). The base class and the bare local backend report `undefined`; a sandboxing backend (`@deepseek-ai/dsh-fs-sandbox`) overrides it with the deployment default. A session override may make the effective mode narrower or wider, so strict escalation widening is checked per call rather than encoded in this default-relative fact.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L99)

 ### ctx.fs.resolve(path, opts?)

@@ -30,7 +53,7 @@ Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a

 **Returns** the stable target; the same file yields the same `targetKey`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L94)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L112)

 ### ctx.fs.stat(target, signal?)

@@ -51,7 +74,7 @@ Return target metadata, or `undefined` when the target does not exist.

 **Returns** metadata only, never content; undefined for an absent target.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L102)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L120)

 ### ctx.fs.lstat(path, opts?, signal?)

@@ -82,7 +105,7 @@ Return path metadata without following the final path component when it is a sym

 **Returns** metadata only, never content; undefined for an absent path.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L118)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L136)

 ### ctx.fs.readText(target, signal?)

@@ -103,7 +126,7 @@ Read the whole regular text file as a single decoded string.

 **Returns** the full decoded UTF-8 content.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L126)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L144)

 ### ctx.fs.streamText(target, signal?)

@@ -127,7 +150,7 @@ Stream the whole regular text file as decoded text chunks (same text semantics a

 **Returns** the chunk iterable, decoded and validated like `readText`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L137)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L155)

 ### ctx.fs.listDir(target, signal?)

@@ -149,9 +172,9 @@ List direct children of a directory in stable name order. Returns resolved child

 **Returns** one entry per direct child, in stable name order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L146)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L164)

-### ctx.fs.writeText(target, content, expected?, signal?)
+### ctx.fs.writeText(target, content, expected?, signal?, sandboxMode?)

 ```ts website-api
 /**
@@ -161,9 +184,12 @@ List direct children of a directory in stable name order. Returns resolved child
 * @param content - the full new file content.
 * @param expected - the write intent guarding the write; omit for unconditional.
 * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxMode - the per-call sandbox mode this write runs under; a
+ *   sandboxing backend fences the write by it, the bare backend ignores it.
+ *   Omit to leave the backend its own default.
 * @returns the outcome, including the version the write produced.
 */
-abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
+abstract writeText( target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsWriteOutcome>
 ```

 Atomically create or replace UTF-8 text. `expected` guards intent and staleness; omission allows unconditional overwrite.
@@ -172,12 +198,13 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;
 - `content` — the full new file content.
 - `expected` — the write intent guarding the write; omit for unconditional.
 - `signal` — aborts before the atomic rename takes effect.
+- `sandboxMode` — the per-call sandbox mode this write runs under; a sandboxing backend fences the write by it, the bare backend ignores it. Omit to leave the backend its own default.

 **Returns** the outcome, including the version the write produced.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L157)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L178)

-### ctx.fs.editText(target, edit, expected?, signal?)
+### ctx.fs.editText(target, edit, expected?, signal?, sandboxMode?)

 ```ts website-api
 /**
@@ -188,9 +215,12 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;
 * @param edit - the literal search/replace request.
 * @param expected - the version guard; omit for an unconditional edit.
 * @param signal - aborts before the atomic rename takes effect.
+ * @param sandboxMode - the per-call sandbox mode this edit runs under; a
+ *   sandboxing backend fences the edit by it, the bare backend ignores it.
+ *   Omit to leave the backend its own default.
 * @returns the outcome, including the version the edit produced.
 */
-abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
+abstract editText( target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal, sandboxMode?: SandboxMode, ): Promise<FsEditOutcome>
 ```

 Atomically edit literal text. When supplied, the version guard is checked before matching so stale content reports `FS_STALE_VERSION`; omission edits the current content without a freshness precondition.
@@ -199,7 +229,8 @@ Atomically edit literal text. When supplied, the version guard is checked before
 - `edit` — the literal search/replace request.
 - `expected` — the version guard; omit for an unconditional edit.
 - `signal` — aborts before the atomic rename takes effect.
+- `sandboxMode` — the per-call sandbox mode this edit runs under; a sandboxing backend fences the edit by it, the bare backend ignores it. Omit to leave the backend its own default.

 **Returns** the outcome, including the version the edit produced.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L169)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/fs/fs/src/index.ts#L199)
--- a/website/zh-CN/api/harness/permission.md
+++ b/website/zh-CN/api/harness/permission.md
@@ -6,7 +6,7 @@

 Owns the deployment's permission presets and their write path. Requires a confining `ctx.bash` executor and `ctx.approval`; unmatched knob values are reported as CUSTOM_PRESET, not an error.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L94)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L97)

 ### ctx.permission.names

@@ -20,7 +20,7 @@ get names(): readonly string[]

 The advertised preset names, in the preset table's declaration order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L134)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L137)

 ### ctx.permission.current(events)

@@ -41,7 +41,7 @@ Resolve the preset matching the effective knob values. A still-matching last sel

 **Returns** the effective preset name, or `custom` when nothing matches.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L145)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L148)

 ### ctx.permission.resolve(name)

@@ -61,7 +61,7 @@ Resolve a preset's knob bundle.

 **Returns** the configured bundle.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L166)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L169)

 ### ctx.permission.optionOf(name)

@@ -82,7 +82,7 @@ Build the client option for a table entry or CUSTOM_PRESET. A missing label fall

 **Returns** the option a client renders.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L181)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L184)

 ### ctx.permission.set(session, name)

@@ -101,4 +101,4 @@ Record a changed preset, then update each changed knob through its own setter. S
 - `session` — the session the switch belongs to.
 - `name` — the preset to switch to; unknown names throw.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L195)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/ui/permission/src/index.ts#L198)
--- a/website/zh-CN/api/harness/sandbox-policy.md
+++ b/website/zh-CN/api/harness/sandbox-policy.md
@@ -0,0 +1,31 @@
+<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
+
+# ctx.sandboxPolicy
+
+`SandboxPolicyService` — provided by `@deepseek-ai/dsh-sandbox-policy`.
+
+The sandbox-policy service (`ctx.sandboxPolicy`). Owns the deployment default mode and workspace root; enforcing implementations read defaultMode and workspaceRoot, and the tool layers fold each session's `sandbox/mode` override with effectiveSandboxMode on top.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L60)
+
+### ctx.sandboxPolicy.defaultMode
+
+```ts website-api
+/** The deployment default mode — the fallback beneath a session override. */
+readonly defaultMode: SandboxMode
+```
+
+The deployment default mode — the fallback beneath a session override.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L70)
+
+### ctx.sandboxPolicy.workspaceRoot
+
+```ts website-api
+/** The absolute `workspace-write` boundary root both families fence against. */
+readonly workspaceRoot: string
+```
+
+The absolute `workspace-write` boundary root both families fence against.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox-policy/src/index.ts#L72)
--- a/website/zh-CN/api/harness/sandbox.md
+++ b/website/zh-CN/api/harness/sandbox.md
@@ -6,7 +6,7 @@

 Abstract process-sandbox service. confine must return enforcing argv or fail closed at wrap or runner-execution time; silent unconfined passthrough is forbidden. Functional probes arbitrate multi-runner chains and may be skipped for a sole candidate, whose own refusal remains the fail-closed end.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L111)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L122)

 ### ctx.sandbox.confine(argv, policy)

@@ -32,4 +32,4 @@ Wrap `argv` so it executes confined under `policy` on this host; the caller spaw

 **Returns** the argv to spawn instead, plus the enforcement completeness the selected backend achieves for it.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L127)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/sandbox/sandbox/src/index.ts#L138)