website: generate the API reference from source (cordis + all 15 harness services)
scripts/gen-website-api.ts renders website/zh-CN/api/{cordis,harness}/* and the
api-sidebar.json fragment the VitePress config imports, so pages and navigation
can never drift from the code: signatures, @param/@returns prose, dispatch
modes, and GitHub source links are extracted, never transcribed, and the
generator hard-errors on any rendered member missing docs. verify-website-api
(doc-sync + run-gates) is the freshness gate.
Replaces the hand-written zh api pages (7 pages covering 7 of 15 services,
with phantom APIs: Context.current/Context.events, agent/post-step, tool/call,
compact/*, llm/pre-request none of which exist) with generated English
references: 5 cordis pages, 15 per-service pages, and a 35-event catalog
grouped by scope. The hand-written hub api/index.md stays and now indexes the
full surface; zh for these pages arrives with the unified translation flow.
This commit is contained in:
lintianle
@@ -1,81 +1,138 @@
|
||||
# Bash (dsh-bash)
|
||||
<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
|
||||
|
||||
Bash 命令执行接口。
|
||||
# ctx.bash
|
||||
|
||||
**接口包:** `@deepseek-ai/dsh-bash`
|
||||
**实现:** `@deepseek-ai/dsh-bash-local`
|
||||
**消费者:** `@deepseek-ai/dsh-tool-bash`（内置于 agent-core）
|
||||
`BashExecutor` (abstract seam) — provided by `@deepseek-ai/dsh-bash`.
|
||||
|
||||
## Bash Service
|
||||
Abstract bash execution service. Subclass, implement the abstract methods, and load the subclass as a plugin — it registers as `ctx.bash` (one implementation per context; loading a second throws, which is cordis' standard duplicate-service behavior).
|
||||
Semantics every implementation must honor:
|
||||
- run REJECTS only for infrastructure failures (unusable workdir, missing shell, pre-aborted signal). Nonzero exits, timeout kills, and abort kills RESOLVE with a descriptive BashRunResult — reporting a failed command is the tool layer's job, not an exception.
|
||||
- start returns immediately; no timeout applies to background tasks (callers stop them via kill or the spec's AbortSignal). Completion must fire the onTaskDone listeners exactly once per task, and must NOT fire after the service is disposed.
|
||||
- readOutput is incremental: consecutive reads never re-deliver output. Implementations bound their buffers; reads that lost data flag `lossy` and point at full-stream spill files when available.
|
||||
- Disposal kills every running task and awaits their exit (no orphan processes survive `fiber.dispose()`).
|
||||
|
||||
### ctx.bash.execute(request)
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L59)
|
||||
|
||||
- **request:** `BashRequest`
|
||||
- **返回值:** `Promise<BashResult>`
|
||||
### ctx.bash.resolve(request)
|
||||
|
||||
执行一个 bash 命令。
|
||||
|
||||
## BashRequest
|
||||
|
||||
```typescript
|
||||
interface BashRequest {
|
||||
/** 要执行的命令 */
|
||||
command: string
|
||||
/** 工作目录 */
|
||||
workdir?: string
|
||||
/** 超时时间 (ms) */
|
||||
timeoutMs?: number
|
||||
}
|
||||
```ts website-api
|
||||
abstract resolve(request: BashExecRequest): BashExecSpec
|
||||
```
|
||||
|
||||
## BashResult
|
||||
Resolve a caller's BashExecRequest into a fully-specified BashExecSpec, applying this implementation's config defaults and caps (working directory, default/max timeout). Consumers (tool layer) call this, then pass the result to run/start — keeping defaulting in the implementation that owns the config while the seam type stays explicit (no hidden `?? default` inside run/start).
|
||||
|
||||
```typescript
|
||||
interface BashResult {
|
||||
/** 退出码 */
|
||||
exitCode: number
|
||||
/** stdout 输出 */
|
||||
stdout: string
|
||||
/** stderr 输出 */
|
||||
stderr: string
|
||||
/** 是否超时 */
|
||||
timedOut: boolean
|
||||
}
|
||||
- `request` — the caller's request; omitted fields get this implementation's defaults, capped fields are clamped.
|
||||
|
||||
**Returns** the fully-specified spec to hand to {@link run}/{@link start}.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L84)
|
||||
|
||||
### ctx.bash.run(spec)
|
||||
|
||||
```ts website-api
|
||||
abstract run(spec: BashExecSpec): Promise<BashRunResult>
|
||||
```
|
||||
|
||||
## 配置 (dsh-bash-local)
|
||||
Run a command in the foreground; resolves when it finishes.
|
||||
|
||||
```typescript
|
||||
interface Config {
|
||||
/** 命令超时时间，默认 120000 (2 分钟) */
|
||||
timeoutMs: number
|
||||
}
|
||||
- `spec` — a resolved spec from {@link resolve}, never a raw request.
|
||||
|
||||
**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#L92)
|
||||
|
||||
### ctx.bash.start(spec)
|
||||
|
||||
```ts website-api
|
||||
abstract start(spec: BashExecSpec): BashTask
|
||||
```
|
||||
|
||||
在 `cordis.yml` 中：
|
||||
Start a background task and return its handle immediately.
|
||||
|
||||
```yaml
|
||||
- name: '@deepseek-ai/dsh-bash-local'
|
||||
config:
|
||||
timeoutMs: 60000
|
||||
- `spec` — a resolved spec from {@link resolve}, never a raw request.
|
||||
|
||||
**Returns** the live task handle; completion fires {@link onTaskDone}.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L99)
|
||||
|
||||
### ctx.bash.get(id)
|
||||
|
||||
```ts website-api
|
||||
abstract get(id: BashTaskId): BashTask | undefined
|
||||
```
|
||||
|
||||
## 模型可用的 Tools
|
||||
Look up a background task by id.
|
||||
|
||||
`dsh-tool-bash` 向模型暴露以下 tools（由 `agent-core` 捆绑）：
|
||||
- `id` — the task id to look up.
|
||||
|
||||
| Tool | 说明 |
|
||||
|------|------|
|
||||
| `bash` | 执行命令（同步，等待完成） |
|
||||
| `bash_output` | 获取后台命令的输出 |
|
||||
| `bash_kill` | 终止后台命令 |
|
||||
**Returns** the tracked task, or undefined for an id this executor never issued.
|
||||
|
||||
## 设计模式
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L106)
|
||||
|
||||
Bash 是 Harness 的"能力三件套"典型案例：
|
||||
### ctx.bash.ownerOf(id)
|
||||
|
||||
- `dsh-bash`（接口）：定义 `ctx.bash` 和 `BashRequest`/`BashResult` 类型
|
||||
- `dsh-bash-local`（实现）：通过 `child_process.spawn` 在本地执行
|
||||
- `dsh-tool-bash`（消费者）：将能力包装为模型可调用的 tool
|
||||
```ts website-api
|
||||
abstract ownerOf(id: BashTaskId): OwnerToken | undefined
|
||||
```
|
||||
|
||||
换一个沙箱执行器只需替换 `dsh-bash-local`，接口和 tool 不变。
|
||||
The opaque OWNER token recorded for a background task at start (from the BashExecSpec's `owner`), or `undefined` for an unknown id OR a known-but-ownerless task. The executor stores and returns the token verbatim — it never interprets it; the access POLICY (who may read/kill a task) lives in the consumer (`@deepseek-ai/dsh-tool-bash`), which compares `ownerOf(id)` to the caller's token. Collapsing unknown-id and known-but-unowned into the same `undefined` is fine: the consumer's access gate treats `undefined` as "open", and a genuinely unknown id then fails loudly at the subsequent readOutput/kill ("unknown task"). Storing ownership in the executor (disposed with ITS fiber) — not in the tool plugin — is what makes ownership survive a `tool-bash` HMR reload.
|
||||
|
||||
- `id` — the background task id to look up ownership for.
|
||||
|
||||
**Returns** the token recorded at start, verbatim; undefined for an unknown id or a known-but-ownerless task.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L124)
|
||||
|
||||
### ctx.bash.list()
|
||||
|
||||
```ts website-api
|
||||
abstract list(): BashTask[]
|
||||
```
|
||||
|
||||
All tracked background tasks (insertion order).
|
||||
|
||||
**Returns** every task this executor started, running or finished.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L130)
|
||||
|
||||
### ctx.bash.readOutput(id)
|
||||
|
||||
```ts website-api
|
||||
abstract readOutput(id: BashTaskId): BashTaskRead
|
||||
```
|
||||
|
||||
Read output produced since the previous read. Throws for unknown ids.
|
||||
|
||||
- `id` — the task to read from.
|
||||
|
||||
**Returns** the incremental read; consecutive reads never re-deliver output.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L137)
|
||||
|
||||
### ctx.bash.kill(id)
|
||||
|
||||
```ts website-api
|
||||
abstract kill(id: BashTaskId): boolean
|
||||
```
|
||||
|
||||
Kill a running background task. Returns false when it had already finished (no-op). Throws for unknown ids.
|
||||
|
||||
- `id` — the task to kill.
|
||||
|
||||
**Returns** true when this call killed it, false when it had already finished.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L145)
|
||||
|
||||
### ctx.bash.onTaskDone(listener)
|
||||
|
||||
```ts website-api
|
||||
onTaskDone(listener: BashTaskListener): () => void
|
||||
```
|
||||
|
||||
Register a background-task completion listener (disposed with the calling fiber). Listeners never fire after this service is disposed.
|
||||
|
||||
- `listener` — called exactly once per task completion.
|
||||
|
||||
**Returns** the disposer that unregisters the listener.
|
||||
|
||||
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/bash/bash/src/index.ts#L153)
|
||||
|
||||
Reference in New Issue
Block a user