mengzhx/deepseek-harness
1
0
Fork 0
mirror of https://github.com/deepseek-ai/deepseek-harness.git synced 2026-08-29 04:26:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: rebuild the documentation skill and standards (#2983)

Browse Source
This commit is contained in:
Magolor
2026-08-25 23:47:20 +08:00
committed by GitHub
parent f4d1d3fb25
commit 0b5eba0c8d
1061 changed files with 57862 additions and 12379 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/webhook/webhook-github/README.i18n.yaml
+2 -2
View File
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write packages/webhook/webhook-github/README.md
README.md: 329e29bc1a4911ebbd22ee4eade772a6aa80bd0c
README.zh.md: 642314b1bc5444f7bfd4413349bf8bb62cdf8cee
README.md: ce0e2da0aa355166ba940b9a991f6ee5c7fa1f9c
README.zh.md: c5ad924ec2040281d12c5890e5679413a07a4c81
packages/webhook/webhook-github/README.md
+37 -2
View File
@@ -1,9 +1,28 @@
---
description: "Signed GitHub webhook adapter for deployments routing authenticated JSON events into the webhook runtime."
kind: "package-reference"
---
# @deepseek-ai/dsh-webhook-github
English | [中文](README.zh.md)
`dsh-webhook-github` registers one exact HTTP route on the injected `ctx.webServer`. It bounds and verifies GitHub's raw JSON body, projects a provider-neutral delivery, calls `ctx.webhookRuntime.dispatch()`, and returns `202` without waiting for rules or Sessions.
## Summary
`dsh-webhook-github` registers one exact HTTP route on the injected `ctx.webServer`. It bounds and verifies GitHub's raw JSON body, projects a provider-neutral delivery, calls `ctx.webhookRuntime.dispatch()`, and returns `202` without waiting for rules or Sessions. Use it when a deployment needs authenticated GitHub ingress for the generic webhook runtime.
## Table of Contents
- [Configuration](#configuration)
- [HTTP contract](#http-contract)
- [Dedicated listener composition](#dedicated-listener-composition)
- [Model Experience](#model-experience)
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
- [Dev Note](#dev-note)
-----
<a id="configuration"></a>
## Configuration
| Key | Meaning |
@@ -15,6 +34,7 @@ English | [中文](README.zh.md)
All fields are required. The secret reference is resolved for every request, so rotation affects the next delivery without reloading the plugin.
<a id="http-contract"></a>
## HTTP contract
Only `POST application/json` is accepted. The adapter reads a bounded UTF-8 body, requires `X-Hub-Signature-256`, `X-GitHub-Delivery`, and `X-GitHub-Event`, resolves the secret, verifies HMAC before JSON parsing, and requires a top-level lossless-JSON object. It never logs the secret, signature, or payload.
@@ -23,7 +43,7 @@ Only `POST application/json` is accepted. The adapter reads a bounded UTF-8 body
|---|---|
| `202` | Verified JSON was dispatched in memory. |
| `400` | Required header, UTF-8, JSON, or top-level object was invalid. |
| `401` | Signature was missing or invalid. |
| `401` | Signature was invalid. |
| `405` | Method was not `POST`. |
| `413` | Declared or streamed body exceeded `maxBodyBytes`. |
| `415` | Media type was not `application/json`. |
@@ -31,10 +51,12 @@ Only `POST application/json` is accepted. The adapter reads a bounded UTF-8 body
`202` does not state that any rule matched or that a Session was created. GitHub event-specific field validation belongs to each rule; the adapter guarantees only authenticated generic JSON.
<a id="dedicated-listener-composition"></a>
## Dedicated listener composition
The normal Web profile already owns `ctx.webServer`. Mount another `dsh-host-webserver` and this adapter inside a group that isolates only `webServer`; the adapter still inherits credentials and `webhookRuntime`. The [GitHub review guide](../../../docs/user/guide/github-review.md) uses `127.0.0.1:3081/github` behind a TLS reverse proxy while the UI remains on port 3080.
<a id="model-experience"></a>
## Model Experience
Indirectly, through `dsh-webhook`: this adapter contributes no prompt or tool schema; a matching rule owns the Session request and model-visible text.
@@ -45,7 +67,20 @@ Independent. Authentication and HTTP dispatch do not touch a model request; any
## Known Limitations and Deferred Work
<a id="known-limitations-and-deferred-work"></a>
- **No TLS** — the injected development WebServer is normally loopback-only behind a TLS reverse proxy or tunnel.
- **Generic payload validation only** — rules own validation of the GitHub event fields they consume.
- **No provider acknowledgement of downstream work** — `202` precedes arbitrary rule calls and Session creation.
- **No form encoding** — GitHub must send `application/json`; `application/x-www-form-urlencoded` is rejected.
<a id="dev-note"></a>
### Dev Note
<details>
<summary>Working context for maintainers — click to expand</summary>
None.
</details>
packages/webhook/webhook-github/README.zh.md
+37 -2
View File
@@ -1,9 +1,28 @@
---
description: "面向把已认证 JSON 事件路由到 webhook 运行时的部署，说明带签名的 GitHub webhook 适配器。"
kind: "package-reference"
---
# @deepseek-ai/dsh-webhook-github
[English](README.md) | 中文
`dsh-webhook-github` 会在注入的 `ctx.webServer` 上注册一条精确 HTTP 路由。它限制并验证 GitHub 原始 JSON body，投影提供方无关的交付，调用 `ctx.webhookRuntime.dispatch()`，并在不等待规则或 Session 的情况下返回 `202`。
## 概述
`dsh-webhook-github` 会在注入的 `ctx.webServer` 上注册一条精确 HTTP 路由。它限制并验证 GitHub 原始 JSON body，投影提供方无关的交付，调用 `ctx.webhookRuntime.dispatch()`，并在不等待规则或 Session 的情况下返回 `202`。部署需要为通用 webhook runtime 提供经过身份验证的 GitHub 入口时，请使用它。
## 目录
- [配置](#configuration)
- [HTTP 约定](#http-contract)
- [专用监听器组合](#dedicated-listener-composition)
- [Model Experience](#model-experience)
- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
- [开发备注](#dev-note)
-----
<a id="configuration"></a>
## 配置
| Key | 含义 |
@@ -15,6 +34,7 @@
所有字段均为必填。每次请求都会重新解析密钥引用，因此轮换会在下一次交付生效，而无需重新加载插件。
<a id="http-contract"></a>
## HTTP 约定
只接受 `POST application/json`。适配器读取有界 UTF-8 body，要求 `X-Hub-Signature-256`、`X-GitHub-Delivery` 与 `X-GitHub-Event`，解析密钥，在 JSON 解析前验证 HMAC，并要求顶层是无损 JSON 对象。它绝不记录密钥、签名或 payload。
@@ -23,7 +43,7 @@
|---|---|
| `202` | 已验证 JSON 已在内存中分发。 |
| `400` | 必需 header、UTF-8、JSON 或顶层对象无效。 |
| `401` | 签名缺失或无效。 |
| `401` | 签名无效。 |
| `405` | 方法不是 `POST`。 |
| `413` | 声明或流式 body 超过 `maxBodyBytes`。 |
| `415` | media type 不是 `application/json`。 |
@@ -31,10 +51,12 @@
`202` 不表示任何规则已经匹配，也不表示已创建 Session。GitHub 事件特定字段的验证属于各规则；适配器只保证通过身份验证的通用 JSON。
<a id="dedicated-listener-composition"></a>
## 专用监听器组合
普通 Web profile 已经拥有 `ctx.webServer`。把另一个 `dsh-host-webserver` 和此适配器挂载到仅隔离 `webServer` 的 group 内；适配器仍会继承凭据与 `webhookRuntime`。[GitHub 评审指南](../../../docs/user/guide/github-review.zh.md)在 TLS 反向代理后使用 `127.0.0.1:3081/github`，而 UI 继续位于端口 3080。
<a id="model-experience"></a>
## Model Experience
通过 `dsh-webhook` 间接产生影响：此适配器不贡献提示词或工具 schema；匹配规则拥有 Session 请求与模型可见文本。
@@ -45,7 +67,20 @@
## Known Limitations and Deferred Work
<a id="known-limitations-and-deferred-work"></a>
- **无 TLS** — 注入的开发 WebServer 通常只监听 loopback，并位于 TLS 反向代理或 tunnel 后。
- **仅通用 payload 验证** — 规则负责验证自己消费的 GitHub 事件字段。
- **不向提供方确认下游工作** — `202` 先于任意规则调用与 Session 创建。
- **不支持表单编码** — GitHub 必须发送 `application/json`；`application/x-www-form-urlencoded` 会被拒绝。
<a id="dev-note"></a>
### 开发备注
<details>
<summary>维护者工作上下文——点击展开</summary>
无。
</details>