Lixiaoyiao/deepseek-harness-action

DeepSeek Harness for GitHub

CI
Release
MIT

English

让 GitHub 里的 PR、Issue、失败 CI 和维护者编写的自动化流程直接调用 DeepSeek Harness。

GitHub PR / Issue / CI  →  DeepSeek Harness  →  Review / Diagnose / Fix / Issue → PR

Action 会启动与凭据隔离的 DSH worker，校验结构化结果，再由受信任的 Controller 发布评论或经过验证的改动。这是社区项目，并非 DeepSeek 或 GitHub 官方产品，由 @Lixiaoyiao 维护。

核心能力

| 能力             | 作用                                                                            |
| ---------------- | ------------------------------------------------------------------------------- |
| PR 审查          | 审查新提交，发布一条汇总，并为高置信度问题添加行内评论                          |
| 通用任务         | 回答仓库问题，或执行经过明确授权的编码任务                                      |
| CI 诊断与修复    | 读取失败的检查和日志；受信任 workflow 可以验证并发布修复                        |
| Issue 实现       | 把经过授权的 Issue 请求实现为已验证的分支和 PR                                  |
| Composition 模式 | 默认保留现有受控工具档位，并提供实验性的 DSH native 模式                        |
| 受控工具         | 以精确工具档位提供原生、固定命令、Controller GitHub、MCP、Bundle 与 Plugin 工具 |
| 结构化结果       | 保留 schema-v1 审计信封，并可校验维护者定义的可选 task 结果                     |

v0.8.2 继续提供基于锁定 DSH 0.1.1-rc.2 runtime 的实验性 dsh-mode: native 路径及其官方生态 composition。Native MCP server、Profile Bundle、direct Cordis Plugin、仓库 Skills、Subagent 和 Workflow 保留 DSH-native discovery 与行为。controlled 仍是兼容默认值，因此未配置 dsh-mode 的 workflow 会继续使用原有 composition、权限、工具、budget、receipt 和输出行为。

Native 模式并不是 unsafe 模式。它把 DSH 内部 headless composition、capability graph 和 model-visible inventory 的 ownership 交还给 DSH。Native MCP 通过官方 @deepseek-ai/dsh-mcp-client 加载；Bundle 作为官方 Profile layer 组合；direct Plugin 通过 Cordis 加载；仓库 Skills、Subagent 与 Workflow 保留 DSH-native 行为。它使用 definition-only 扩展 schema 来声明 owner 和进程需求，而不是声明 Action tool、grant 或 per-tool budget。动态生态工具只通过运行时 observedTools 出现，native toolPolicy 不会虚构 Controller effectiveTools。

Action 仍拥有 trusted-workflow admission、package exact pin、lifecycle script 禁用、runtime inventory audit、Docker 与 .git-less workspace 边界、run-scoped DeepSeek 凭据代理、GitHub 凭据隔离、actor/repository trust、validation 与 deferred write、deadline、cancellation 和 secret redaction。Native 仍仅支持 Docker；bridge network 和 read/write mount 都是 whole-worker 能力，不是 per-extension 或 per-tool sandbox。用户自行配置并携带自有凭据的 GitHub MCP 属于受信任外部扩展，其直接副作用不享受 Controller Gateway 的 binding、revalidation、validation 或 deferred-mutation 保证。Controller-owned command. 与 github. 能力继续作为独立且与 mode 正交的平面。

v0.8.2 修复生产 controlled/native 路径的结构化结果可靠性，并更新 upstream 兼容性预警。一次有界、无工具的结果修复不会重新运行 worker 任务；严格输出 schema 与所有 Controller 写入门禁仍然生效。Release canary 为两种模式分别保留诊断。现有输入、输出、默认行为、权限语义和 DSH 0.1.1-rc.2 固定版本保持兼容，不增加 Session/Resume 或新的 GitHub 能力。

真实运行

以下是本仓库的公开运行记录，可以直接查看评论和 Actions 日志。

| 场景                            | 运行记录                                                                                                                                                              |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| PR 审查，以及复跑时不重复发评论 | PR #3 · Actions run |
| 根据失败的检查和日志进行诊断    | Actions run                                                                         |
| 在受信任写模式下修复并验证      | Actions run                                                                         |
| 实现 Issue 后创建 PR            | Issue #4 → PR #5                    |

快速开始

在需要接入的仓库根目录运行安装器：

npm create deepseek-harness-action@latest

选择一种模式：

- PR Review 创建 .github/workflows/dsh-review.yml。
- @dsh Coding Commands 创建 .github/workflows/dsh-commands.yml。
- Both 创建以上两个 workflow 文件。

在 CI 或其它非交互环境中，必须显式传入 mode，安装器不会等待 stdin：

npm create deepseek-harness-action@latest -- --mode both

非交互使用时，省略 --dsh-mode 会保持兼容的 controlled 默认值。交互流程
会明确询问；除非确实需要 native composition，否则请选择 Controlled：

npm create deepseek-harness-action@latest -- --mode both --dsh-mode native

安装器会按需创建 .github/workflows/，如果目标 workflow 已存在则拒绝覆盖。
它不会添加 Secret、commit 或 push 改动，也不会创建 PR。安装器 v0.2.0
只根据正式 v0.8.0 release identity 构建，生成的 workflow 固定到不可变 commit
86fff4c4527694c7eefdc65c6cf7a633b5ea8cb1，不会使用 candidate SHA、浮动 Tag
或分支。

安装完成后，在 Settings → Secrets and variables → Actions 中添加 DEEPSEEK_API_KEY。打开或更新一个非 draft PR 即可触发 Review；使用 Coding Commands 时，把 @dsh 命令写在 Issue 或 PR 评论的第一行。完整 onboarding 与安全说明见安装指南。

手工安装

先在仓库的 Settings → Secrets and variables → Actions 中添加 DEEPSEEK_API_KEY，再创建 .github/workflows/dsh-review.yml：

name: DSH review

on:
pull_request_target:
types: [opened, synchronize, ready_for_review, reopened]

permissions:
contents: read
pull-requests: write

jobs:
review:
if: github.event.pull_request.draft == false
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
with:
ref: ${{ github.event.pull_request.base.sha }}
persist-credentials: false
fetch-depth: 1
- uses: Lixiaoyiao/deepseek-harness-action@v0.8.2
with:
deepseek-api-key: ${{ secrets.DEEPSEEK_API_KEY }}
dsh-version: 0.1.1-rc.2

打开一个非 draft PR。Action 只会检出受信任的 base SHA，通过 GitHub API 读取 PR，并且不会运行 fork 中的代码。

生产环境应把 v0.8.2 替换为该版本发布时的完整、不可变 commit SHA。权限、版本固定、安全检出规则和完整模板见安装指南。

常用 @dsh 命令

命令必须写在 Issue 或 PR 评论的第一行。

| 命令                       | 用途                               |
| -------------------------- | ---------------------------------- |
| @dsh task --read   | 解释代码、检查仓库或回答通用问题   |
| @dsh task --write  | 请求编码任务；所有写入关卡仍须通过 |
| @dsh review              | 重新审查当前 PR                    |
| @dsh diagnose            | 诊断失败的检查和日志               |
| @dsh fix                 | 在受信任写模式下修复同仓库 PR      |
| @dsh implement           | 实现 Issue 并创建 PR               |

--write、fix 和 implement 只是请求能力，并不授予权限。workflow 必须显式启用写模式，并提供由 Controller 执行的验证命令。命令和自动化用法见使用指南，完整关卡见配置参考。

维护者可以修改 trigger phrase，添加 label/assignee 路由，过滤 actor 或历史评论，选择 base branch，并配置确定性 branch template。这些设置只改变路由和命名；GitHub authority 仍由 Controller policy 与 workflow token scope 决定。

安全边界

- Agent 不会拿到真实的 GITHUB_TOKEN 或 DeepSeek key。只有 Controller 能调用 Action-owned github. 写入 API；显式配置的外部 GitHub MCP 使用其自有凭据和 authority，边界见下文。
- 仓库内容、diff、Issue、PR、评论、日志、模型输出和工具输出始终是不可信数据。
- fork 审查使用没有 .git、没有凭据的 worker；workflow 只能检出受信任的 base SHA，并设置 persist-credentials: false。
- 写入需要受信任的同仓库上下文、通过授权检查的操作者、Docker、allow-write: "true"、非空固定验证命令，以及全部验证成功；受保护路径和 Validation Integrity 检查仍然有效。
- Typed github. mutation 使用精确 ID、绑定当前 entity，并延迟到 Controller 验证成功后执行，同时保留有界 receipts 与 reconciliation；不存在 arbitrary REST、GraphQL、raw URL 或凭据透传。
- Validation Integrity 针对已支持的 entrypoint、package script、test/config 变弱、lock/toolchain 控制和已知 wrapper/interpreter 提供高置信度变弱检测与 baseline replay；它不是完整的跨语言 dependency provenance 或形式化完整性证明。
- Validation 可能使用 Docker bridge network。在 self-hosted runner 或企业网络中，仓库验证代码可能访问 runner 可达的网络服务；应使用专用 runner 以及 runner 级网络分段和出口控制。
- 获准的 Bundle、Plugin 或 stdio MCP server 属于受信任的 worker code。Controlled ToolRuntime 只限制模型路由的调用；native 的路由与 inventory 由 DSH 自己管理。两种模式都不能沙箱化扩展启动、后台任务或直接进程 I/O，任何 bridge/RW 能力都作用于整个 worker。
- github.* 使用 Controller GitHub Gateway；另行配置的 GitHub MCP 使用它自己的外部凭据，不享受 Gateway 的 binding、revalidation、validation 和 deferred-write 保证。

启用写模式、host 执行、网络访问或第三方扩展前，请完整阅读安全策略。

文档

| 指南                                                       | 内容                                                                 |
| ---------------------------------------------------------- | -------------------------------------------------------------------- |
| 安装指南 · English | 安装器、手工安装、Secret、权限、安全检出和模板                       |
| 使用指南 · English | @dsh 命令、task、review、diagnose、fix、implement 和自动化         |
| 配置参考                          | 输入、权限档位、工具、验证、扩展和输出                               |
| 架构 · 不变量     | 组件职责、authority 边界与稳定系统不变量                             |
| 故障排查                        | 权限拒绝、Docker、超时、取消、验证和扩展故障                         |
| 安全策略                                    | 信任模型、凭据边界、网络行为和已知限制                               |
| 扩展契约                    | MCP、Profile、Bundle、Plugin、ToolRuntime 和 receipts 的深层技术约束 |
| 维护者发布指南               | 本地检查、核心 E2E、release canary、版本更新和发布                   |
| 贡献指南 · 更新记录     | 开发流程和版本历史                                                   |

开发

需要 Node.js 24。

npm ci
npm run check

具体流程见 CONTRIBUTING.md。用于 GitHub Marketplace 的 dist/ 会随版本提交，请勿手工修改。

许可证

本项目采用 MIT 许可证。第三方许可见 THIRD_PARTY_NOTICES.md 和 BUNDLED_DEPENDENCIES.md。

DeepSeek Harness 提供 headless runtime 和官方扩展机制。GitHub 集成还参考了采用 MIT 许可证的 Claude Code Action 模式，以及 Codex GitHub Action 对执行权限和发布权限的分离方式；准确的来源说明记录在第三方许可文件中。