dsh-plugin-guide 0.3.42 → 0.4.1

package/references/official-docs/docs/user/develop/practice/llm-adapter.i18n.yaml

@@ -1,34 +0,0 @@
-# Bilingual-pair consistency record for llm-adapter.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/develop/practice/llm-adapter.md
-/llm-adapters:
-  en: 3ed9fd352e2c3edd
-  zh: f575c12bb4409a7f
-/llm-adapters/overview:
-  en: 613076de2e5c7c2d
-  zh: 9df5bf6bca93267f
-/llm-adapters/minimal-implementation:
-  en: 2eeb1c65c2b1e67b
-  zh: 0dbee75ec52aa2d5
-/llm-adapters/streamchunk-protocol:
-  en: c5b80f3ab607300c
-  zh: 6d143add0d5fc44c
-/llm-adapters/streamchunk-protocol/key-rules:
-  en: c0138e6ba95197fa
-  zh: fc1e2b8047e08d2a
-/llm-adapters/generateoptions:
-  en: 5bdb364bd44239c4
-  zh: ca0f2854069aa134
-/llm-adapters/register-an-adapter:
-  en: 8e0ac8990c049f29
-  zh: f8c3de63ee4d6757
-/llm-adapters/use-it-from-cordis-yml:
-  en: b83c91da871dca8c
-  zh: d21046627e3cb0c4
-/llm-adapters/reference-implementations:
-  en: e05d4b0a901e8ef0
-  zh: 9516cebb3e5c3692
-/llm-adapters/error-handling:
-  en: d54065c52caf7910
-  zh: 79b3ebc22a38286d

package/references/official-docs/docs/user/develop/practice/llm-adapter.md

@@ -1,189 +0,0 @@
-# LLM adapters
-
-English | [中文](llm-adapter.zh.md)
-
-This guide connects a new LLM provider to Harness.
-
-## Overview
-
-An LLM adapter extends `LlmAdapter` and implements `stream()`, translating Harness's provider-neutral request into a provider API call and translating the response back into Harness chunks.
-
-## Minimal implementation
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
-
-class MyAdapter extends LlmAdapter {
-  private apiKey: string
-
-  constructor(apiKey: string) {
-    super()
-    this.apiKey = apiKey
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    // 1. Convert options.messages to the provider format.
-    // 2. Call the streaming API.
-    // 3. Convert the response into StreamChunk values.
-  }
-}
-
-export interface Config {
-  apiKey: string
-  providers: string[]
-}
-
-export const Config: Schema<Config> = Schema.object({
-  apiKey: Schema.string().required(),
-  providers: Schema.array(Schema.string()).required(),
-})
-
-export const name = 'my-llm-adapter'
-export const inject = ['llm']
-
-export function apply(ctx: Context, config: Config) {
-  const adapter = new MyAdapter(config.apiKey)
-  ctx.llm.registerAdapter(config.providers, adapter)
-}
-```
-
-## StreamChunk protocol
-
-`stream()` yields chunks using this protocol:
-
-```ts
-import { brandString } from '@deepseek-ai/dsh-brand'
-import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
-
-async function* exampleChunks(): AsyncIterable<StreamChunk> {
-  // 1. Start each content block with block-start.
-  yield { type: 'block-start', index: 0, blockType: 'text' }
-
-  // 2. Stream text through text-delta.
-  yield { type: 'text-delta', index: 0, text: 'Hello' }
-  yield { type: 'text-delta', index: 0, text: ' world' }
-
-  // 3. End each content block with block-end and the complete block.
-  yield {
-    type: 'block-end',
-    index: 0,
-    block: { type: 'text', text: 'Hello world' },
-  }
-
-  // 4. Tool-call block.
-  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
-  yield {
-    type: 'tool-call-delta',
-    index: 1,
-    id: brandString<ToolCallId>('call-123'),
-    name: 'bash',
-    argumentsDelta: '{"command":"ls"}',
-  }
-  yield {
-    type: 'block-end',
-    index: 1,
-    block: {
-      type: 'tool-call',
-      id: brandString<ToolCallId>('call-123'),
-      name: 'bash',
-      arguments: '{"command":"ls"}',
-    },
-  }
-
-  // 5. Token usage.
-  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
-
-  // 6. Finish reason.
-  yield { type: 'finish', reason: { kind: 'stop' } }
-  // Alternatively, { kind: 'tool-calls' } requests tool execution.
-}
-```
-
-### Key rules
-
-- Every `block-start` has a matching `block-end`.
-- `index` increases from 0 and identifies content-block order.
-- A `tool-call-delta` carries raw JSON text in `argumentsDelta`, either all at once or over multiple chunks.
-- `finish` is the final chunk.
-- Emit `usage` before `finish`.
-
-## GenerateOptions
-
-`stream()` receives the exported `GenerateOptions` type. It includes the model, adapter-owned reasoning-effort id, conversation history, system prompt, tool schemas, generation parameters, stop sequences, and abort signal; treat the TypeScript type exported by `@deepseek-ai/dsh-llm` as authoritative. Map supported fields to the provider API. If the provider cannot honor a field, throw `LlmError` with a stable code instead of silently dropping it.
-
-Override `resolveModel(provider, model, signal?)` to return exact provider/model identity plus optional `context` and `reasoning` metadata in one lookup. Reasoning metadata contains ordered opaque ids and display names plus an optional configured default; preserve the adapter's authoritative selectable list, including `off` when its upstream capability API returns it, instead of promoting those values into a core enum. Honor the optional signal for asynchronous lookup so cancellation and disposal reach quiescence. The service validates the aggregate and rejects unsupported explicit efforts before `stream()`; omitting `reasoning` means that model has no selectable reasoning-effort capability.
-
-## Register an adapter
-
-```ts ignore-check
-ctx.llm.registerAdapter(['my-provider'], adapter)
-```
-
-The first argument lists provider routes handled by the adapter. `GenerateOptions.provider` selects the registered adapter, while `GenerateOptions.model` passes an adapter-owned model id without lifecycle registration. Override `listModels()` when the adapter can advertise model choices to selectors.
-
-## Use it from cordis.yml
-
-```yaml
-- id: my-llm
-  name: './src/my-llm-adapter.ts'
-  config:
-    apiKey: !!js process.env.MY_API_KEY
-    providers:
-      - my-provider
-
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents:
-      - id: main
-        provider: my-provider
-        model: my-model-v1
-```
-
-## Reference implementations
-
-The repository contains complete implementations:
-
-- `packages/llm/llm-deepseek/` — DeepSeek adapter using the Messages API
-- `packages/llm/llm-pi-ai/` — Pi AI adapter using a different API format
-
-Compare the two shipped adapters to see the same harness contract implemented over different provider SDKs.
-
-## Error handling
-
-Adapters throw transport and protocol failures as `LlmError` values with stable codes. The agent loop preserves the error and code for diagnostics and policy; it does not convert an ordinary `Error` automatically. Every provider HTTP request must also merge `attributionHeaders()` and forward `options.signal`.
-
-```ts
-import {
-  attributionHeaders,
-  LlmAdapter,
-  LlmError,
-  type GenerateOptions,
-  type StreamChunk,
-} from '@deepseek-ai/dsh-llm'
-
-class HttpAdapter extends LlmAdapter {
-  constructor(private readonly endpoint: string) {
-    super()
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const response = await fetch(this.endpoint, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        ...attributionHeaders(),
-      },
-      body: JSON.stringify({ model: options.model, messages: options.messages }),
-      ...options.signal ? { signal: options.signal } : {},
-    })
-    if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
-    }
-    // A real adapter parses the response and emits the complete chunk sequence.
-    yield { type: 'finish', reason: { kind: 'stop' } }
-  }
-}
-```

package/references/official-docs/docs/user/develop/practice/llm-adapter.zh.md

@@ -1,189 +0,0 @@
-# LLM 适配器
-
-[English](llm-adapter.md) | 中文
-
-本文介绍如何为 Harness 接入新的模型提供方。
-
-## 概述
-
-LLM 适配器是一个继承 `LlmAdapter` 并实现 `stream()` 方法的类，它会将 Harness 的提供方无关请求转换为具体提供方的 API 调用，并将响应转换回 Harness 分片。
-
-## 最小实现
-
-```ts
-import type { Context } from '@deepseek-ai/cordis'
-import Schema from '@deepseek-ai/schemastery'
-import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
-
-class MyAdapter extends LlmAdapter {
-  private apiKey: string
-
-  constructor(apiKey: string) {
-    super()
-    this.apiKey = apiKey
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    // 1. Convert options.messages to the provider format.
-    // 2. Call the streaming API.
-    // 3. Convert the response into StreamChunk values.
-  }
-}
-
-export interface Config {
-  apiKey: string
-  providers: string[]
-}
-
-export const Config: Schema<Config> = Schema.object({
-  apiKey: Schema.string().required(),
-  providers: Schema.array(Schema.string()).required(),
-})
-
-export const name = 'my-llm-adapter'
-export const inject = ['llm']
-
-export function apply(ctx: Context, config: Config) {
-  const adapter = new MyAdapter(config.apiKey)
-  ctx.llm.registerAdapter(config.providers, adapter)
-}
-```
-
-## StreamChunk 协议
-
-`stream()` 必须按以下协议生成分片：
-
-```ts
-import { brandString } from '@deepseek-ai/dsh-brand'
-import type { StreamChunk, ToolCallId } from '@deepseek-ai/dsh-llm'
-
-async function* exampleChunks(): AsyncIterable<StreamChunk> {
-  // 1. Start each content block with block-start.
-  yield { type: 'block-start', index: 0, blockType: 'text' }
-
-  // 2. Stream text through text-delta.
-  yield { type: 'text-delta', index: 0, text: 'Hello' }
-  yield { type: 'text-delta', index: 0, text: ' world' }
-
-  // 3. End each content block with block-end and the complete block.
-  yield {
-    type: 'block-end',
-    index: 0,
-    block: { type: 'text', text: 'Hello world' },
-  }
-
-  // 4. Tool-call block.
-  yield { type: 'block-start', index: 1, blockType: 'tool-call' }
-  yield {
-    type: 'tool-call-delta',
-    index: 1,
-    id: brandString<ToolCallId>('call-123'),
-    name: 'bash',
-    argumentsDelta: '{"command":"ls"}',
-  }
-  yield {
-    type: 'block-end',
-    index: 1,
-    block: {
-      type: 'tool-call',
-      id: brandString<ToolCallId>('call-123'),
-      name: 'bash',
-      arguments: '{"command":"ls"}',
-    },
-  }
-
-  // 5. Token usage.
-  yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
-
-  // 6. Finish reason.
-  yield { type: 'finish', reason: { kind: 'stop' } }
-  // Alternatively, { kind: 'tool-calls' } requests tool execution.
-}
-```
-
-### 关键规则
-
-- 每个 `block-start` 都必须有与之对应的 `block-end`。
-- `index` 从 0 开始递增，用于标识内容块的顺序。
-- `tool-call-delta` 的 `argumentsDelta` 是原始 JSON 文本的增量，可以在一个分片中完整生成，也可以分多个分片生成。
-- `finish` 必须是最后一个分片。
-- `usage` 必须在 `finish` 之前生成。
-
-## GenerateOptions
-
-`stream()` 接收仓库导出的 `GenerateOptions`。它包含模型、适配器拥有的推理强度 ID、对话历史、系统提示词、工具 schema、生成参数、停止序列和中止信号；完整字段以 `@deepseek-ai/dsh-llm` 导出的 TypeScript 类型为准。适配器必须将支持的字段映射到具体 API；如果无法支持某个字段，应抛出带稳定 code 的 `LlmError`，不得静默丢弃。
-
-请覆写 `resolveModel(provider, model, signal?)`，在一次查询中返回确切的提供方／模型身份以及可选的 `context` 和 `reasoning` 元数据。推理元数据包含有序的不透明 ID、展示名称，以及可选的配置默认值；请保留适配器给出的权威可选列表，包括其上游能力 API 返回的 `off`，不要将这些值提升为核心枚举。异步查询必须响应该可选信号，使取消和资源释放过程完全停稳。服务会校验聚合结果，并在调用 `stream()` 前拒绝显式指定但不受支持的推理强度；省略 `reasoning` 表示该模型没有可选的推理强度能力。
-
-## 注册适配器
-
-```ts ignore-check
-ctx.llm.registerAdapter(['my-provider'], adapter)
-```
-
-第一个参数是该适配器处理的提供方路由列表。`GenerateOptions.provider` 选择已注册的适配器，`GenerateOptions.model` 则传入由适配器拥有、无需在生命周期启动时注册的模型 id。适配器能够向选择器公布模型选项时，请覆写 `listModels()`。
-
-## 在 cordis.yml 中使用
-
-```yaml
-- id: my-llm
-  name: './src/my-llm-adapter.ts'
-  config:
-    apiKey: !!js process.env.MY_API_KEY
-    providers:
-      - my-provider
-
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents:
-      - id: main
-        provider: my-provider
-        model: my-model-v1
-```
-
-## 实战参考
-
-仓库中包含以下两个完整实现：
-
-- `packages/llm/llm-deepseek/` — 使用 Messages API 的 DeepSeek 适配器
-- `packages/llm/llm-pi-ai/` — Pi AI 适配器（不同的 API 格式）
-
-对比这两个已交付的适配器，可以看到同一套 harness 契约如何在不同提供方 SDK 之上实现。
-
-## 错误处理
-
-适配器应通过带稳定 code 的 `LlmError` 抛出传输和协议故障；agent loop（智能体循环）会保留该错误及其 code，用于诊断和策略处理。不要依赖普通 `Error` 被自动转换。每个提供方 HTTP 请求还必须合并 `attributionHeaders()`，并传递 `options.signal`。
-
-```ts
-import {
-  attributionHeaders,
-  LlmAdapter,
-  LlmError,
-  type GenerateOptions,
-  type StreamChunk,
-} from '@deepseek-ai/dsh-llm'
-
-class HttpAdapter extends LlmAdapter {
-  constructor(private readonly endpoint: string) {
-    super()
-  }
-
-  async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    const response = await fetch(this.endpoint, {
-      method: 'POST',
-      headers: {
-        'content-type': 'application/json',
-        ...attributionHeaders(),
-      },
-      body: JSON.stringify({ model: options.model, messages: options.messages }),
-      ...options.signal ? { signal: options.signal } : {},
-    })
-    if (!response.ok) {
-      throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
-    }
-    // A real adapter parses the response and emits the complete chunk sequence.
-    yield { type: 'finish', reason: { kind: 'stop' } }
-  }
-}
-```

package/references/official-docs/docs/user/guide/github-review.i18n.yaml

@@ -1,25 +0,0 @@
-# Bilingual-pair consistency record for github-review.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/guide/github-review.md
-/create-review-sessions-from-github-webhooks:
-  en: d7326712d79158d8
-  zh: 02102a8b9e749928
-/create-review-sessions-from-github-webhooks/prerequisites:
-  en: 6784d85f90231608
-  zh: 3e62e9cadfdc2c18
-/create-review-sessions-from-github-webhooks/start-dsh:
-  en: 6c2c8394bfaf5d11
-  zh: a863fa2ad6bc48bb
-/create-review-sessions-from-github-webhooks/expose-the-dedicated-endpoint:
-  en: f18a2969b3082da9
-  zh: 87d3d0e58d25a62f
-/create-review-sessions-from-github-webhooks/rule-behavior:
-  en: 3306087b78170a99
-  zh: 7c7b0baefa1dc303
-/create-review-sessions-from-github-webhooks/programmatic-extensions:
-  en: d448fc3e440a0ec6
-  zh: 18568898933ef054
-/create-review-sessions-from-github-webhooks/delivery-semantics:
-  en: 8d098eeb5a62a4ba
-  zh: cfc7f2759ebf129d

package/references/official-docs/docs/user/guide/github-review.md

@@ -1,99 +0,0 @@
-# Create review Sessions from GitHub webhooks
-
-English | [中文](github-review.zh.md)
-
-This opt-in overlay adds a signed GitHub endpoint to `dsh web`. When a pull request in the configured repository changes from draft to ready for review, the rule creates a titled root Session under the repository's Web Workspace and starts a read-only review prompt.
-
-## Prerequisites
-
-- A local checkout that DSH may register as a Web Workspace.
-- A high-entropy GitHub webhook secret available through the `DSH_GITHUB_WEBHOOK_SECRET` credential reference.
-- A TLS reverse proxy or tunnel that can forward one public URL to the loopback listener.
-- GitHub webhook subscription to the Pull requests event with content type `application/json`.
-
-The overlay defaults the Workspace to the launch directory and the listener to `127.0.0.1:3081`. Override them with `DSH_GITHUB_REVIEW_WORKSPACE` and `DSH_GITHUB_WEBHOOK_PORT`.
-
-## Start DSH
-
-Generate a secret and retain the same value across restarts:
-
-```sh
-export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
-printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
-```
-
-Install both experimental packages into the Web profile first. Profiles do not install peers automatically; the GitHub adapter needs the webhook runtime explicitly:
-
-```sh
-dsh plugin --profile web add @deepseek-ai/dsh-webhook @deepseek-ai/dsh-webhook-github
-export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
-dsh web --patch "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@deepseek-ai/dsh-webhook-github/examples/github-review/cordis.yml"
-```
-
-The adapter distributes the example, which loads from the profile's installation directory so its rule module can resolve profile-installed peers. Do not run the rule from an arbitrary directory outside the profile. To customize it, copy both example files to `$DSH_HOME/profiles/web/github-review/`, edit the configuration, and point `--patch` at that copy of `cordis.yml`; use `~/.dsh` when `DSH_HOME` is unset.
-
-The repository example lives under `packages/experimental/webhook-github/examples/github-review/`. The CLI does not install webhook packages or list them as Official plugins; installing the packages and supplying the overlay are separate steps.
-
-## Expose the dedicated endpoint
-
-The main Web UI and `/api` remain on port 3080. The overlay mounts a second WebServer in an isolated realm; only `POST /github` is registered there, and every other path returns `404`.
-
-A Caddy configuration can expose only that listener:
-
-```caddyfile
-hooks.example.com {
-  route {
-    @github path /github
-    reverse_proxy @github 127.0.0.1:3081
-    respond 404
-  }
-}
-```
-
-Configure GitHub with:
-
-```text
-Payload URL:  https://hooks.example.com/github
-Content type: application/json
-Secret:       DSH_GITHUB_WEBHOOK_SECRET value
-Events:       Pull requests
-Active:       yes
-```
-
-## Rule behavior
-
-The rule accepts only source `primary-github`, repository `deepseek-ai/deepseek-harness`, event `pull_request`, and action `ready_for_review`. It passes the exact head SHA plus selected PR fields to the review prompt, labeling the JSON as untrusted metadata and forbidding file, branch, PR, or GitHub mutation.
-
-The Session request selects the `standard` agent preset and `read-only` permission preset. `workspacePath` is canonicalized through `WorkspaceRegistry.create()`, so the first matching delivery creates the Web Workspace when absent and later deliveries reuse it.
-
-The HTTP response is intentionally weaker than the Agent outcome: `202` means the signature and JSON were accepted and rule calls were scheduled in memory. It does not mean this rule matched or that a Session was created.
-
-## Programmatic extensions
-
-`run()` is ordinary trusted JavaScript. A deployment can query an internal policy service before returning a Session request:
-
-```js
-const response = await fetch('https://policy.internal/pr-review', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ repository: payload.repository.full_name }),
-  signal,
-})
-if (!response.ok || (await response.json()).automaticReview !== true) return null
-```
-
-It can also map repositories to different local paths:
-
-```js
-const workspacePath = {
-  'deepseek-ai/deepseek-harness': '/path/to/deepseek-harness',
-  'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
-}[payload.repository.full_name]
-if (workspacePath === undefined) return null
-```
-
-## Delivery semantics
-
-The webhook runtime stores no delivery or execution state. Repeated delivery runs the rule and may create another Session. A crash loses rule calls that have not admitted their prompt. After prompt admission, the ordinary Session log, persistence, Workspace, and Agent lifecycle own the work.
-
-The webhook secret authenticates inbound GitHub data only. It grants neither rule code nor the created Agent outbound GitHub access; configure that authority separately when a rule or Agent needs it.

package/references/official-docs/docs/user/guide/github-review.zh.md

@@ -1,99 +0,0 @@
-# 通过 GitHub Webhook 创建评审会话
-
-[English](github-review.md) | 中文
-
-此可选 overlay 会为 `dsh web` 增加一个签名 GitHub 端点。当已配置仓库中的 pull request 从 draft 变为 ready for review 时，规则会在该仓库的 Web Workspace 下创建带标题的根 Session，并启动只读评审提示词。
-
-## 前置条件
-
-- 一个可由 DSH 注册为 Web Workspace 的本地 checkout。
-- 一个可通过 `DSH_GITHUB_WEBHOOK_SECRET` 凭据引用访问的高熵 GitHub webhook 密钥。
-- 一个可以把单个公共 URL 转发到 loopback 监听器的 TLS 反向代理或 tunnel。
-- GitHub webhook 订阅 Pull requests 事件，且 content type 为 `application/json`。
-
-overlay 默认使用启动目录作为 Workspace，并监听 `127.0.0.1:3081`。可通过 `DSH_GITHUB_REVIEW_WORKSPACE` 与 `DSH_GITHUB_WEBHOOK_PORT` 覆盖它们。
-
-## 启动 DSH
-
-生成密钥，并在重启后继续使用同一值：
-
-```sh
-export DSH_GITHUB_WEBHOOK_SECRET="$(openssl rand -hex 32)"
-printf '%s\n' "$DSH_GITHUB_WEBHOOK_SECRET"
-```
-
-先把两个实验包安装到 Web profile。Profile 不会自动安装 peer；GitHub 适配器需要显式安装 webhook 运行时：
-
-```sh
-dsh plugin --profile web add @deepseek-ai/dsh-webhook @deepseek-ai/dsh-webhook-github
-export DSH_GITHUB_REVIEW_WORKSPACE=/path/to/deepseek-harness
-dsh web --patch "${DSH_HOME:-$HOME/.dsh}/profiles/web/node_modules/@deepseek-ai/dsh-webhook-github/examples/github-review/cordis.yml"
-```
-
-示例随 GitHub 适配器发布，并从 profile 的安装目录加载，因此规则模块能解析该 profile 安装的 peer。不要把规则单独放到 profile 之外的任意目录运行。需要定制时，将示例的两个文件复制到 `$DSH_HOME/profiles/web/github-review/`，修改其配置并把 `--patch` 指向复制后的 `cordis.yml`；未设置 `DSH_HOME` 时使用 `~/.dsh`。
-
-仓库中的示例位于 `packages/experimental/webhook-github/examples/github-review/`。Webhook 包不随 CLI 安装，也不出现在官方插件列表中；安装包与提供 overlay 是两个独立步骤。
-
-## 暴露专用端点
-
-主 Web UI 与 `/api` 继续位于端口 3080。overlay 会在隔离 realm 中挂载第二个 WebServer；其中只注册 `POST /github`，其他路径均返回 `404`。
-
-Caddy 配置可以只暴露该监听器：
-
-```caddyfile
-hooks.example.com {
-  route {
-    @github path /github
-    reverse_proxy @github 127.0.0.1:3081
-    respond 404
-  }
-}
-```
-
-GitHub 配置如下：
-
-```text
-Payload URL:  https://hooks.example.com/github
-Content type: application/json
-Secret:       DSH_GITHUB_WEBHOOK_SECRET value
-Events:       Pull requests
-Active:       yes
-```
-
-## 规则行为
-
-规则只接受来源 `primary-github`、仓库 `deepseek-ai/deepseek-harness`、事件 `pull_request` 与动作 `ready_for_review`。它会把精确 head SHA 和选定 PR 字段传给评审提示词，把 JSON 标为不受信任的元数据，并禁止修改文件、分支、PR 或 GitHub 状态。
-
-Session 请求选择 `standard` agent preset 与 `read-only` permission preset。`workspacePath` 通过 `WorkspaceRegistry.create()` 规范化，因此第一次匹配交付会在 Workspace 不存在时创建它，后续交付会复用它。
-
-HTTP 响应刻意弱于 Agent 结果：`202` 表示签名与 JSON 已被接受，规则调用已在内存中调度。它不表示此规则已经匹配，也不表示已创建 Session。
-
-## 程序化扩展
-
-`run()` 是普通受信任 JavaScript。部署可以在返回 Session 请求前查询内部策略服务：
-
-```js
-const response = await fetch('https://policy.internal/pr-review', {
-  method: 'POST',
-  headers: { 'content-type': 'application/json' },
-  body: JSON.stringify({ repository: payload.repository.full_name }),
-  signal,
-})
-if (!response.ok || (await response.json()).automaticReview !== true) return null
-```
-
-它还可以把仓库映射到不同本地路径：
-
-```js
-const workspacePath = {
-  'deepseek-ai/deepseek-harness': '/path/to/deepseek-harness',
-  'deepseek-harness/dsh-sdk': '/path/to/dsh-sdk',
-}[payload.repository.full_name]
-if (workspacePath === undefined) return null
-```
-
-## 交付语义
-
-webhook runtime 不存储交付或执行状态。重复交付会运行规则，并可能创建另一个 Session。崩溃会丢失尚未接纳提示词的规则调用。提示词接纳后，工作由普通 Session 日志、persistence、Workspace 与 Agent 生命周期拥有。
-
-webhook 密钥只验证入站 GitHub 数据。它不会向规则代码或所创建 Agent 授予出站 GitHub 访问权；规则或 Agent 需要时应单独配置该权限。

package/references/official-docs/docs/user/guide/index.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for index.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/user/guide/index.md
-/use-the-web-ui:
-  en: 0c95e166d018a6e9
-  zh: ffb65573f7af49e7
-/use-the-web-ui/configure-a-model:
-  en: 017967a6f7c60eeb
-  zh: 190c812bd8d8a338
-/use-the-web-ui/choose-a-workspace:
-  en: ed78cd0a583896ae
-  zh: d713d7a4b5f34e42
-/use-the-web-ui/run-a-task:
-  en: e1cb5a05bf6e109d
-  zh: 8b181b0fecbc0517
-/use-the-web-ui/continue:
-  en: 6b244134309ca89c
-  zh: 971fa14939d88c6b