dsh-plugin-dev-kb 1.0.0

package/kb/site/en/reference/tool-execution-pipeline.md

@@ -0,0 +1,66 @@
+---
+editSource: "docs/tool-execution-pipeline.md"
+---
+
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Tool Execution Pipeline
+
+This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.
+
+```mermaid
+flowchart TD
+  model["Assistant message contains tool-call block"]
+  toolCall["Session event: <code>tool/call</code><br/>logged before execution"]
+  presentCall["UI pending card<br/>presentCall(args)"]
+  pre["<code>tools/pre-execute</code> waterfall<br/>hooks, permission, sandbox"]
+  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]
+  denied["denied or approval refused<br/>tool body skipped"]
+  approval["<code>ctx.approval</code> one-shot prompt<br/>absent or unanswerable: deny"]
+  around["<code>tools/execute</code> waterfall<br/>timeout, retry, metrics (around dispatch)"]
+  toolBody["Registered tool execute() body"]
+  fsGate["<code>fs/write-intent</code> or <code>fs/edit-intent</code><br/>tool-fs mutations only"]
+  owned["Tool-owned session events<br/><code>todo/write</code>, <code>fs/observed</code>, <code>hook/invoked</code>, <code>hook/result</code>, <code>tool/code-dispatch</code>"]
+  post["<code>tools/post-execute</code> waterfall<br/>accept, block, replace, add context"]
+  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]
+  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]
+  final["<code>tools/result</code> synchronous notification<br/>frozen authoritative outcome"]
+  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]
+  toolResult["Session event: <code>tool/result</code><br/>single model-facing outcome"]
+  allResults["Tool batch settled<br/>recorded tool/result events complete"]
+  presentResult["UI completed card<br/>presentResult(args, result)"]
+  model --> toolCall
+  toolCall --> presentCall
+  toolCall --> pre
+  pre -->|allow| guards
+  guards -->|allow| around
+  guards -->|deny| denied
+  guards -.->|throw| normalized
+  around --> toolBody
+  pre -->|deny| denied
+  pre -->|ask| approval
+  approval -->|allowed-once| guards
+  approval -->|rejected, cancelled, unavailable| denied
+  approval -.->|throw| normalized
+  denied --> post
+  pre -.->|throw| normalized
+  toolBody --> fsGate
+  fsGate --> toolBody
+  toolBody --> owned
+  toolBody --> around
+  around --> post
+  around -.->|wrapper throws| normalized
+  post -.->|throw| normalized
+  post --> finalize
+  normalized --> finalize
+  finalize --> final
+  final --> toolResult
+  toolResult --> presentResult
+  toolResult --> allResults
+  allResults --> context
+```
+
+Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition's snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.
+
+Maintenance mode: curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs.

package/kb/site/guide/providers.md

@@ -0,0 +1,100 @@
+---
+editSource: "docs/user/guide/providers.zh.md"
+---
+
+# 配置模型
+
+本指南假定你已按照[根 README](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run)启动 Web UI。模型变更会在下一次请求时生效，不需要重启服务器。
+
+## 配置 DeepSeek
+
+打开**设置 → 模型**。DeepSeek 卡片提供一个 API 密钥字段；输入密钥并保存。
+
+![模型页：DeepSeek 卡片，以及添加提供方与添加自定义提供方两个入口](./providers-models-page.zh.png)
+
+密钥是只写的。保存后，页面只会收到脱敏描述符，永远不会收到明文密钥。密钥存储在 `$DSH_HOME/.credentials.yaml` 中，settings 只保留它的凭据引用。
+
+## 添加目录提供方
+
+选择**添加提供方**，选取 Anthropic 或 OpenAI 等提供方，输入其 API 密钥并保存。已安装目录会提供端点、协议和模型列表。
+
+使用原生认证的提供方需要各自的原生凭据。Bedrock、Vertex、Azure 和 Codex 分别使用 AWS 凭据与区域、ADC 项目、`api-version` 和 OAuth；只填写 API 密钥字段无法完成配置。
+
+## 添加自定义提供方
+
+对于公司网关、自建服务器或已安装目录中不存在的提供方，选择**添加自定义提供方**。提供小写 Provider ID、基础 URL、API 协议、凭据和至少一个模型。
+
+![自定义提供方表单：Provider ID、显示名称、API 地址、API 协议、API 密钥](./providers-custom-form.zh.png)
+
+Provider ID 是永久的，因为请求、已保存会话、模型默认值和凭据引用都会使用它。如需重命名提供方，请添加新提供方并删除旧提供方。显示名称、基础 URL、协议、凭据和模型仍可编辑。
+
+在**模型目录**中选择**获取可用模型**，可查询表单当前显示的基础 URL 和凭据。选择候选项只会更新草稿；保存前不会存储提供方。目录提供方使用已安装目录，不发起网络请求。
+
+### 图片输入
+
+手动输入的模型在自己声明之前一律按纯文本对待，因为没有任何环节能去询问端点接受哪些模态。给这类模型附加图片，会在发送前就被拒绝，并点名该模型。
+
+因此自定义提供方下的视觉模型需要加一行。表单没有对应字段；请在 `$DSH_HOME/settings.yaml` 中给该模型加上 `input`：
+
+```yaml
+llm-pi-ai:
+  providers:
+    my-gateway:
+      apiKeyEnv: GATEWAY_API_KEY
+      api: openai-completions
+      baseURL: https://gateway.example/v1
+      models:
+        - id: legacy-chat
+        - id: vision-preview
+          input: [text, image]
+```
+
+`input` 接受 `text` 和 `image`，且只作用于该模型，因此一条路由可以同时服务两类模型。省略它——或写成空列表，两者同义——则保留已安装目录为该模型记录的模态；目录未描述的模型则回退到该路由的 `defaultInput`。
+
+如果你手动录入的模型全都接受图片，可以在路由上设置一次回退值，不必逐个模型写：
+
+```yaml
+llm-pi-ai:
+  providers:
+    vision-gateway:
+      apiKeyEnv: GATEWAY_API_KEY
+      api: openai-completions
+      baseURL: https://vision.example/v1
+      defaultInput: [text, image]
+      models:
+        - id: first-model
+        - id: second-model
+```
+
+`defaultInput` 是回退值而不是覆盖值，默认为 `[text]`：在目录提供方上，它只为目录未描述的模型作答，因此绝不会把目录中本就具备图片能力的模型的该能力去掉。要收窄这类模型，请用它自己的 `input`。目录提供方没有可供填写的 `models` 列表，因此写在 `modelOverrides` 下，以模型 id 为键：
+
+```yaml
+llm-pi-ai:
+  providers:
+    anthropic:
+      modelOverrides:
+        claude-sonnet-4-5:
+          input: [text]
+```
+
+除模型自身的列表外，每个列表都至少要写一项模态；模型自身的空列表与省略它同义。未知模态在任何位置写入都会被拒绝。
+
+这两个字段都是对你端点的断言，而不是对它的检查。声明了端点并不提供的图片能力的模型不会在这里被拦下，改由提供方拒绝该请求。
+
+## 选择模型
+
+已配置的提供方会出现在模型选择器中。选择模型也会将其设为新会话的默认值。已发送过请求的会话会保留自身日志中记录的模型。
+
+如果已保存默认值指向已删除的提供方，输入框会显示**选择模型**，并在选择其他模型前阻止输入。
+
+## 排错
+
+- **`MISSING_CREDENTIAL`**：通过模型页存储提供方密钥，或提供被引用的环境变量。
+- **`UNKNOWN_MODEL`**：选择已配置的模型，或向自定义提供方添加缺失的模型。
+- **获取可用模型返回 401**：检查密钥。模型发现会调用 OpenAI 兼容的 `GET /models` 端点；对于不提供该端点的服务，请手动输入模型。
+- **图片在发送前被拒绝**：该模型未声明图片模态。请给自定义提供方的模型加上 `input: [text, image]`；DeepSeek 自身的 chat-completions 路由是纯文本的，且无法通过配置改变。
+- **提供方拒绝了带图片的请求**：该模型声明了其端点实际并不提供的图片能力。请从授予它图片能力的那个列表中移除 `image`——可能是模型的 `input`，也可能是路由的 `defaultInput`——然后开启新会话：附加的图片会留在会话日志里，因此在会话离开它之前，同一个请求会不断重复。
+
+## 进阶配置
+
+自动生成的[插件配置目录](../reference/config-catalog.md)列出所有受支持的字段与默认值。[`dsh-llm-pi-ai`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-pi-ai/README.md) 和 [`dsh-llm-deepseek`](https://github.com/deepseek-ai/deepseek-harness/blob/master/packages/llm/llm-deepseek/README.md) 参考文档负责直接 `settings.yaml` 配置、目录解析、推理控制、凭据与适配器错误。

package/kb/site/guide/python-sdk.md

@@ -0,0 +1,106 @@
+---
+editSource: "docs/user/guide/python-sdk.zh.md"
+---
+
+# Python SDK 快速上手
+
+本教程介绍 Web UI 之外的程序化使用方式：安装已发布的 Python SDK、运行仓库内置的 agent（智能体）组合，并在自己的程序中调用同一套 API。
+
+## 前置要求
+
+- Python 3.10 或更高版本
+- Git
+- Linux x64、Linux arm64 或 macOS 14 或更高版本的 arm64
+- DeepSeek 兼容的 API 端点与凭据
+- agent 可以修改的隔离 workspace
+
+## 安装 SDK
+
+克隆仓库以使用其中的可运行示例，创建虚拟环境，并安装 SDK 及其同版本内置运行时：
+
+```sh
+git clone https://github.com/deepseek-ai/deepseek-harness.git
+cd deepseek-harness
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install deepseek-harness-sdk
+```
+
+安装后的运行时不需要系统提供 Node.js。需要从源码构建运行时或 wheel 包的仓库贡献者应使用 [Python 贡献者工作流](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/development.md)。
+
+## 运行仓库内置示例
+
+请在环境中设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是通过 OpenAI 兼容代理提供，还需要设置 `DEEPSEEK_BASE_URL`。
+
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
+# export DSH_MODEL=deepseek-v4-flash
+# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'
+```
+
+针对隔离的 workspace 和会话目录运行一个任务：
+
+```sh
+python examples/jsonrpc-agent/minimal.py \
+  --workspace /absolute/path/to/workspace \
+  --session-root /absolute/path/to/sessions \
+  --session-id example-001 \
+  "Inspect the repository and fix the failing tests."
+```
+
+脚本会打印 assistant 的最终回复。会话目录会收到 JSONL 日志，其中包含组装后的模型请求与工具调用。
+
+## 在自己的程序中使用 SDK
+
+仓库内置示例是以下 SDK 调用的轻量包装：
+
+```python
+from pathlib import Path
+
+from deepseek_harness import DeepSeekHarness
+
+config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
+workspace = Path("/absolute/path/to/workspace").resolve()
+sessions = Path("/absolute/path/to/sessions").resolve()
+
+with DeepSeekHarness(
+    provider="deepseek-official",
+    model="deepseek-v4-flash",
+    max_tokens=49_152,
+    cwd=str(workspace),
+    session_root=str(sessions),
+    cordis=str(config),
+) as harness:
+    result = harness.run(
+        "Inspect the repository and fix the failing tests.",
+        session_id="example-001",
+    )
+
+print(result.final_response)
+```
+
+`DeepSeekHarness` 会延迟启动内置运行时，并持续复用，直至退出上下文管理器。复用同一个 harness 与 session id 会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。独立任务应使用新的 session id；只有下一次调用需要延续同一段持久化对话时，才复用原有 id。
+
+## 了解示例组合
+
+| 属性 | 值 |
+|---|---|
+| 系统提示词 | `DSH_SYSTEM_PROMPT`；未设置时使用 `You are a helpful software engineer assistant.` |
+| `minimal.py` 使用的模型 | `--model`，其次为 `DSH_MODEL`，最后为 `deepseek-v4-flash` |
+| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
+| Bash 超时 | 300 秒 |
+| 编辑器输出上限 | 16,000 个字符 |
+| 上下文压缩 | 已关闭 |
+| 文件系统 | 裸本地后端；编辑器使用绝对路径，可以访问运行时进程可见的任何路径 |
+| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
+
+该组合省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具、上下文压缩和其他所有面向模型的插件。沙箱策略事实记录为运行时用户上下文，而不会追加到系统提示词中。
+
+## 选择 workspace 与 session id
+
+`cwd` 用于选择 agent 可访问的 workspace，`session_root` 用于保存会话日志和状态。独立任务应使用新的 session id；只有下一次调用需要延续同一段对话和持久 shell 状态时，才复用原有 id。
+
+该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该组合不支持 Windows agent。
+
+准确的组合内容归 [`jsonrpc-agent` 示例参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/examples/jsonrpc-agent/README.md)所有。[Python SDK 参考](https://github.com/deepseek-ai/deepseek-harness/blob/master/python/sdk/README.md)介绍生命周期、结果、通知、运行时选择和配置；[Cordis primer](../reference/cordis-primer.md)介绍组合语法。

package/kb/site/guide/quickstart.md

@@ -0,0 +1,32 @@
+---
+editSource: "docs/user/guide/index.zh.md"
+---
+
+# 使用 Web UI
+
+请先按照[根目录 README](https://github.com/deepseek-ai/deepseek-harness/blob/master/README.md#run) 中的说明启动 Web UI；命令会打印其访问地址。本指南从服务器已经运行的状态开始。`dsh` 进程会把启动时所在的目录作为默认文件系统位置；全新的 Web UI 则不会选中任何工作区，你需要添加一个工作区。
+
+## 配置模型
+
+打开**设置 → 模型**，输入 [DeepSeek API 密钥](https://platform.deepseek.com/)并保存。模型路由会立即可用，不需要重启服务器。
+
+[模型配置指南](./providers.md)介绍其他提供方和自定义 OpenAI 兼容端点。
+
+## 选择工作区
+
+点击**选择工作区**，添加启动 `dsh` 时所在的项目目录，然后选中它。选中工作区前，会话输入框不可用。
+
+## 运行任务
+
+启动一个会话并发送：
+
+> Summarize this repository and identify its main packages.
+
+Agent（智能体）可以读取和编辑工作区文件、运行命令、委派工作并维护计划。如果根据当前权限策略，某项操作需要审批，Web UI 会先询问你。
+
+## 继续使用
+
+- [配置模型](./providers.md)
+- [使用 Python SDK](./python-sdk.md)
+- [使用其他 CLI 模式](https://github.com/deepseek-ai/deepseek-harness/blob/master/apps/cli/README.md)
+- [开发插件](../develop/basic/index.md)

package/kb/site/index.md

@@ -0,0 +1,8 @@
+---
+editSource: "docs/user/index.zh.md"
+layout: false
+head:
+  - - meta
+    - http-equiv: refresh
+      content: 0; url=./guide/quickstart
+---

package/kb/site/reference/agent-lifecycle.md

@@ -0,0 +1,86 @@
+---
+editSource: "docs/agent-lifecycle.zh.md"
+---
+
+<!-- 英文源文件由 scripts/gen-doc-graphs.ts 生成；本中文文件是通过双语配对维护的经评审对侧。
+     更新时先运行 `pnpm run gen-doc-graphs` 更新英文，再更新本文件并运行 `pnpm run verify-translation-pairing --write docs/agent-lifecycle.md` 重新记录配对。 -->
+
+# Agent 轮次与步骤生命周期
+
+此时序图是 [architecture.md](./index.md#turn-flow) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Agent
+  participant Driver
+  participant Hooks as hook listeners
+  participant Prompt as ctx.systemPrompt
+  participant LLM as ctx.llm
+  participant Tools as ctx.tools
+  participant Session
+  participant SDK as UI or SDK listener
+  User->>Agent: followup(content)
+  Agent-->>SDK: <code>agent/inbox/spliced</code>
+  Agent-->>SDK: <code>agent/inbox/inserted</code> { message }
+  Agent->>Driver: queued work wakes driver
+  Driver-->>SDK: <code>agent/status</code> running
+  Driver->>Session: <code>turn/start</code>
+  Note over Agent,Driver: claim pending next-step input plus one queued prompt
+  Driver-->>SDK: <code>agent/inbox/spliced</code> pure deletion
+  Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+  Driver->>Hooks: <code>agent/pre-step</code> waterfall
+  Hooks-->>Driver: authoritative reject or enter(messages)
+  alt proposed step rejected or pre-step failed
+    Driver-->>Driver: claimed batch stays removed, the open turn spends no step
+  else enter proposed step
+  Driver->>Session: <code>step/start</code>
+  Driver->>Session: <code>user/message</code> per entered message
+  Driver->>Prompt: <code>system-prompt/assemble</code> waterfall
+  Driver->>LLM: <code>agent/request</code> waterfall, then <code>llm/stream</code> waterfall
+  LLM-->>Driver: StreamChunk*
+  Driver->>Session: <code>assistant/chunk</code>*
+  Session-->>SDK: <code>session/event</code> <code>assistant/chunk</code>*
+  alt final adapter or terminal in-band request failure
+    Driver->>Session: <code>step/end</code>
+    Driver->>Hooks: <code>agent/request-error</code> waterfall
+    Hooks-->>Driver: return retry action or preserve the original error
+  else model request succeeded
+  Driver->>Session: <code>assistant/message</code>
+  Driver->>Tools: classify pending call by executionMode
+  loop barriers and bounded rolling pool, reclassify before start
+    opt call starts
+      Driver->>Session: <code>tool/call</code>
+      Driver->>Tools: ordered pre, concurrent execute
+      Tools-->>Session: tool-owned events when applicable
+    end
+    opt next model-order result ready
+      Driver->>Tools: ordered post
+      Driver->>Session: <code>tool/result</code>
+    end
+  end
+  Driver->>Session: <code>step/end</code>
+  opt natural stop and next-step inbox empty
+    Driver->>Hooks: <code>agent/turn-stopping</code> serial terminal checkpoint
+  end
+  opt next-step input is pending
+    Driver-->>Driver: claim pending next-step input
+    Driver-->>SDK: <code>agent/inbox/claimed</code> { message, turn } per message
+    Driver->>Hooks: <code>agent/pre-step</code> waterfall
+    Hooks-->>Driver: authoritative reject or enter(messages)
+  end
+  end
+  end
+  Driver->>Session: <code>turn/end</code>
+  Driver-->>SDK: <code>agent/status</code> idle
+```
+
+`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用。空内容不会进入派生历史，但该持久事件仍会保留用量，并通过 `sourceEventSeqs` 精确列出对应的 `assistant/chunk` 事件，包括显式空列表。
+
+`dsh-compaction-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
+
+以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
+
+需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
+
+维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。