@perrylink/dsh-github 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +153 -194
- package/README.hi.md +153 -194
- package/README.md +122 -187
- package/README.pt.md +146 -187
- package/README.zh.md +230 -0
- package/cordis.patch.yml +1 -1
- package/package.json +121 -82
- package/scripts/action-patch.mjs +152 -138
- package/scripts/action-post.mjs +61 -48
- package/scripts/check-readmes.mjs +3 -1
- package/scripts/local-test.mjs +259 -0
- package/README.zh-CN.md +0 -292
package/README.pt.md
CHANGED
|
@@ -1,129 +1,90 @@
|
|
|
1
|
-
<
|
|
2
|
-
|
|
3
|
-
<p align="center">
|
|
4
|
-
<b>Traga o GitHub para o DeepSeek Harness.</b><br/>
|
|
5
|
-
Crie pull requests · revise PRs com comentários inline ou de resumo · gerencie issues · pesquise — toda gravação exige aprovação humana e o token nunca é registrado em log.
|
|
6
|
-
</p>
|
|
7
|
-
|
|
8
|
-
<p align="center">
|
|
9
|
-
<a href="README.md">English</a> ·
|
|
10
|
-
<a href="README.zh-CN.md">中文</a> ·
|
|
11
|
-
<a href="README.es.md">Español</a> ·
|
|
12
|
-
Português ·
|
|
13
|
-
<a href="README.hi.md">हिन्दी</a>
|
|
14
|
-
</p>
|
|
15
|
-
|
|
16
|
-
<p align="center">
|
|
17
|
-
<img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="License: Apache 2.0">
|
|
18
|
-
<img src="https://img.shields.io/badge/dsh-0.1.0--rc.6-4D6BFE" alt="dsh: 0.1.0-rc.6">
|
|
19
|
-
<img src="https://img.shields.io/badge/dsh-dsh--plugin-4D6BFE" alt="dsh-plugin">
|
|
20
|
-
<img src="https://img.shields.io/badge/node-%5E22.19%20%7C%7C%20%3E%3D24-brightgreen" alt="Node: ^22.19 || >=24">
|
|
21
|
-
<img src="https://github.com/PerryLink/dsh-github/actions/workflows/ci.yml/badge.svg" alt="CI">
|
|
22
|
-
<img src="https://img.shields.io/badge/documents-EN%2FZH%2FES%2FPT%2FHI-8257D0" alt="Documents: EN/ZH/ES/PT/HI">
|
|
23
|
-
</p>
|
|
1
|
+
<div align="center">
|
|
24
2
|
|
|
25
|
-
|
|
3
|
+
# dsh-github
|
|
4
|
+
|
|
5
|
+
**PRs, revisões, issues e CI do GitHub para o DeepSeek Harness — toda gravação aprovada por um humano e o token nunca registrado em log.**
|
|
6
|
+
|
|
7
|
+
*Crie, revise, mescle e pesquise no GitHub a partir do agente, com uma ação composta de CI, um bot de revisão por polling e uma barreira de status-check.*
|
|
8
|
+
|
|
9
|
+
[](LICENSE)
|
|
10
|
+
[](https://github.com/topics/dsh-plugin)
|
|
11
|
+
[](#)
|
|
12
|
+
[](https://github.com/PerryLink/dsh-github/actions)
|
|
13
|
+
[](https://github.com/PerryLink/dsh-github/releases)
|
|
14
|
+
[](https://www.npmjs.com/package/@perrylink/dsh-github)
|
|
15
|
+
[](https://www.npmjs.com/package/@perrylink/dsh-github)
|
|
26
16
|
|
|
27
|
-
|
|
17
|
+
[English](README.md) · [简体中文](README.zh.md) · [Español](README.es.md) · [Português](README.pt.md) · [हिन्दी](README.hi.md)
|
|
28
18
|
|
|
29
|
-
|
|
30
|
-
- ⌨️ **3 famílias de comandos** — `/pr create` · `/review` (start/stop/post) · `/issue open`
|
|
31
|
-
- 🔀 **Ciclo de vida completo do PR** — criar → revisar → atualizar (título/corpo/estado/rama base) → mesclar (merge/squash/rebase, exclusão opcional da rama head)
|
|
32
|
-
- 📝 **Revisões inline** — `review_post` publica um único comentário de resumo ou comentários de revisão ancorados por linha no commit head do PR
|
|
33
|
-
- 🔒 **Gravações com aprovação obrigatória** — toda gravação no GitHub passa por `ctx.approval` (padrão `ask`, falha fechada); os motivos de aprovação pré-visualizam títulos, tamanhos de corpo e substituições de comentários
|
|
34
|
-
- 🗝 **Sigilo do token** — camada de credenciais → ambiente → CLI `gh`, resolvido por operação, nunca em logs, eventos, renderizações ou erros
|
|
35
|
-
- ⏱ **Jobs de revisão em segundo plano** — `/review` roda em `ctx.jobs` com a própria superfície `job_list` / `job_output` / `job_kill` do host, e reporta o status de CI e a contagem de comentários junto com os achados
|
|
36
|
-
- 🤖 **Opção de revisão por modelo** — `reviewMode: "model"` delega o diff limitado a um subagente de uso único pela seam `subagents` do host; o modo `static` padrão permanece determinístico e sem gasto de tokens
|
|
37
|
-
- 🚦 **Backoff de 429 + exibição de cota** — o modelo vê o limite de taxa restante em todo resultado, incluindo falhas; os erros de busca por seção são exibidos em vez de engolidos
|
|
38
|
-
- 🌐 **Documentação em 5 idiomas** — English · 中文 · Español · Português · हिन्दी
|
|
19
|
+
</div>
|
|
39
20
|
|
|
40
21
|
---
|
|
41
22
|
|
|
42
23
|
## 📚 Índice
|
|
43
24
|
|
|
44
|
-
- [
|
|
45
|
-
- [
|
|
46
|
-
- [
|
|
47
|
-
- [
|
|
48
|
-
- [
|
|
49
|
-
- [
|
|
50
|
-
- [Arquitetura](
|
|
51
|
-
- [
|
|
52
|
-
- [
|
|
53
|
-
- [
|
|
54
|
-
- [
|
|
55
|
-
- [
|
|
25
|
+
- [Compatibilidade](#compatibilidade)
|
|
26
|
+
- [O que você obtém](#o-que-você-obtém)
|
|
27
|
+
- [Início rápido](#início-rápido)
|
|
28
|
+
- [Instalação e desinstalação](#instalação-e-desinstalação)
|
|
29
|
+
- [Configuração](#configuração)
|
|
30
|
+
- [Ferramentas e superfícies](#ferramentas-e-superfícies)
|
|
31
|
+
- [Arquitetura](#arquitetura)
|
|
32
|
+
- [Permissões e dados](#permissões-e-dados)
|
|
33
|
+
- [Limites de segurança](#limites-de-segurança)
|
|
34
|
+
- [Limitações conhecidas](#limitações-conhecidas)
|
|
35
|
+
- [Desenvolvimento](#desenvolvimento)
|
|
36
|
+
- [Estrutura do repositório](#estrutura-do-repositório)
|
|
37
|
+
- [Tópicos](#tópicos)
|
|
38
|
+
- [Contribuidores](#contribuidores)
|
|
39
|
+
- [Família de plugins DSH da PerryLink](#família-de-plugins-dsh-da-perrylink)
|
|
56
40
|
- [Licença](#licença)
|
|
57
41
|
|
|
58
|
-
##
|
|
42
|
+
## Compatibilidade
|
|
59
43
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
# 2. configure a GitHub token (recommended: the credentials seam)
|
|
68
|
-
# $DSH_HOME/.credentials.yaml
|
|
69
|
-
# GITHUB_TOKEN: <your token>
|
|
70
|
-
|
|
71
|
-
# 3. use it — in the dsh web UI or headless
|
|
72
|
-
# /pr create "add dark mode" → agent drafts & opens the PR (approval required)
|
|
73
|
-
# /review 42 → background review job, read it with job_output
|
|
74
|
-
# /review post github-review-1 → publish the review comment (approval required)
|
|
75
|
-
# /issue open "crash on startup" → agent opens the issue (approval required)
|
|
76
|
-
```
|
|
44
|
+
| Superfície | Status |
|
|
45
|
+
|---|---|
|
|
46
|
+
| Harness | DeepSeek Harness `0.1.0-rc.6` (compatibilidade declarada para `0.1.0-rc.5`–`0.1.0-rc.6`) |
|
|
47
|
+
| Node | `^22.19.0 \|\| >=24.0.0` |
|
|
48
|
+
| Plataformas | Todas (plugin host; rede de saída para o GitHub) |
|
|
49
|
+
| Modelo | Qualquer (a revisão estática é determinística; `reviewMode: "model"` é opcional) |
|
|
77
50
|
|
|
78
|
-
|
|
51
|
+
## O que você obtém
|
|
79
52
|
|
|
80
|
-
|
|
53
|
+
O `dsh-github` preenche a lacuna do GitHub entre o `dsh` e ferramentas como o Claude Code e o Codex: seu agente pode ler, revisar, abrir, atualizar e mesclar pull requests, ler metadados de repositórios e arquivos, comentar e fechar issues, e pesquisar — enquanto um humano aprova toda gravação e o token permanece em segredo.
|
|
81
54
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
| **Gerenciar issues** | `issue_open` cria, `issue_comment` comenta (também funciona em PRs), `issue_close` fecha com um motivo de estado opcional — todos com aprovação obrigatória |
|
|
94
|
-
| **Pesquisar** | `gh_search` consulta issues e pull requests com a sintaxe de busca do GitHub, exibindo a cota de busca separada |
|
|
95
|
-
| **Aprovação** | `tools/pre-execute` consulta `ctx.approval` para toda gravação; a allowlist `allowedActions` nega antes de perguntar |
|
|
96
|
-
| **Segurança do segredo** | O token é lido por operação e enviado apenas no cabeçalho Authorization; um teste dedicado garante que ele nunca aparece em nenhuma saída visível |
|
|
97
|
-
| **Resiliência** | Nova tentativa em 429 com backoff `Retry-After`/`x-ratelimit-reset`; as ferramentas de leitura são seguras para concorrência; todas as chamadas respeitam o cancelamento |
|
|
98
|
-
| **Observabilidade** | Visível ao modelo ⇔ registrado: tudo o que o modelo vê flui pelos próprios eventos de sessão do host (`tool/result`, `user/message`, `command/run`, `approval/asked`…) |
|
|
99
|
-
|
|
100
|
-
## 📦 Instalação
|
|
101
|
-
|
|
102
|
-
Quatro canais documentados — escolha um.
|
|
103
|
-
|
|
104
|
-
| Canal | Comando | Observações |
|
|
105
|
-
|---|---|---|
|
|
106
|
-
| **npm registry** | `dsh plugin --profile <name> add @perrylink/dsh-github` | Publicado no npm — o canal mais simples |
|
|
107
|
-
| **tarball npm** | `dsh plugin --profile <name> add ./dsh-github-<version>.tgz` | Envia com `lib/` compilado — sem permissão de build |
|
|
108
|
-
| **fonte git** | `dsh plugin --profile <name> add "github:PerryLink/dsh-github#<sha>"` | Requer `prepare` + `allowBuilds` (veja abaixo); fixe o commit |
|
|
109
|
-
| **link local** | `pnpm link --dir .` e depois `dsh plugin add @perrylink/dsh-github` | Desenvolvimento |
|
|
55
|
+
- **12 ferramentas** — `pr_create`, `pr_merge`, `pr_update`, `gh_review`, `review_post`, `gh_issue`, `issue_open`, `issue_comment`, `issue_close`, `gh_search`, `gh_repo`, `gh_file`, todas com JSON canônico via `defineTool`.
|
|
56
|
+
- **3 famílias de comandos** — `/pr create`, `/review` (start/stop/post), `/issue open`.
|
|
57
|
+
- **Ciclo de vida completo do PR** — criar → revisar → atualizar (título/corpo/estado/rama base) → mesclar (merge/squash/rebase, exclusão opcional da rama head).
|
|
58
|
+
- **Revisões inline** — `review_post` publica um único comentário de resumo ou comentários de revisão ancorados por linha no commit head do PR.
|
|
59
|
+
- **Gravações com aprovação** — toda gravação no GitHub passa por `ctx.approval` (padrão `ask`, falha fechada); os motivos de aprovação pré-visualizam títulos, tamanhos de corpo e substituições de comentários.
|
|
60
|
+
- **Sigilo do token** — camada de credenciais → ambiente → CLI `gh`, resolvido por operação, nunca em logs, eventos, renderizações ou erros.
|
|
61
|
+
- **Jobs de revisão em segundo plano** — `/review` roda em `ctx.jobs` com a própria superfície `job_list` / `job_output` / `job_kill` do host.
|
|
62
|
+
- **Resiliência** — nova tentativa em 429 com backoff `Retry-After`/`x-ratelimit-reset`; as ferramentas de leitura são seguras para concorrência; todas as chamadas respeitam o cancelamento.
|
|
63
|
+
- **Superfície de CI** — a ferramenta de execução única `ci_run`, um bot de revisão por polling e uma barreira de status-check (ação composta `action.yml`).
|
|
64
|
+
|
|
65
|
+
## Início rápido
|
|
110
66
|
|
|
111
|
-
|
|
67
|
+
```sh
|
|
68
|
+
# 1. instale o bundle no seu perfil
|
|
69
|
+
dsh plugin --profile web add "github:PerryLink/dsh-github#main"
|
|
112
70
|
|
|
113
|
-
|
|
71
|
+
# ou do npm (versões publicadas)
|
|
72
|
+
dsh plugin --profile web add @perrylink/dsh-github
|
|
114
73
|
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
'@perrylink/dsh-github': true
|
|
74
|
+
# 2. reinicie e verifique a linha
|
|
75
|
+
dsh --profile web --dump-config | grep -A3 'id: dsh-github'
|
|
118
76
|
```
|
|
119
77
|
|
|
120
|
-
|
|
78
|
+
## Instalação e desinstalação
|
|
121
79
|
|
|
122
|
-
**
|
|
80
|
+
- **canal git** (último `main`): `dsh plugin --profile web add "github:PerryLink/dsh-github#main"` — o script `prepare` compila apenas com dependências de produção.
|
|
81
|
+
- **canal npm** (versões publicadas): `dsh plugin --profile web add @perrylink/dsh-github`.
|
|
82
|
+
- **canal tarball**: `pnpm pack` neste repositório e depois `dsh plugin --profile web add ./dsh-github-<version>.tgz`.
|
|
83
|
+
- **desinstalar**: `dsh plugin --profile web remove dsh-github` (ou remova a linha do patch de perfil).
|
|
123
84
|
|
|
124
|
-
##
|
|
85
|
+
## Configuração
|
|
125
86
|
|
|
126
|
-
|
|
87
|
+
Todos os ajustes são campos `Config` do Schemastery (modificáveis a partir do cordis.yml). Uma substituição direcionada por id troca toda a linha — redeclare cada chave de que você precisa. O `cordis.patch.yml` documenta cada chave em linha.
|
|
127
88
|
|
|
128
89
|
| Chave | Padrão | Significado |
|
|
129
90
|
|---|---|---|
|
|
@@ -148,99 +109,73 @@ Validado pelo Schemastery no momento do carregamento (falha em alto e bom som).
|
|
|
148
109
|
| `apiBaseUrl` | `https://api.github.com` | URL base da API REST do GitHub (GitHub Enterprise) |
|
|
149
110
|
| `allowedActions` | `['pr.create','pr.merge','pr.update','review.post','issue.create','issue.comment','issue.close','ci.run']` | Allowlist de ações de gravação; qualquer outra coisa é negada antes da aprovação |
|
|
150
111
|
| `workspaceDir` | process cwd | Diretório de trabalho para inspeção somente leitura do git |
|
|
151
|
-
| `ci` | `{ enabled: false, … }` | Seção de integração CI: bot de revisão por polling,
|
|
152
|
-
|
|
153
|
-
## 🛠 Ferramentas
|
|
154
|
-
|
|
155
|
-
| Ferramenta | Tipo | Parâmetros | Retorna |
|
|
156
|
-
|---|---|---|---|
|
|
157
|
-
| `pr_create` | gravação | `title*`, `body?`, `base?`, `head?`, `draft?`, `ownerRepo?` | `{status:'created', url, number, title, state, draft, base, head, rateLimit}` ou erro estruturado |
|
|
158
|
-
| `pr_merge` | gravação | `pr*` (number / `#n` / `o/r#n` / URL), `mergeMethod?`, `commitTitle?`, `commitMessage?`, `deleteBranch?` | `{status:'merged', merged, sha?, message, url, branchDeleted, branchDeleteNote?, rateLimit}` ou erro estruturado |
|
|
159
|
-
| `pr_update` | gravação | `pr*` (number / `#n` / `o/r#n` / URL), `title?`, `body?`, `state?` (`open`/`closed`), `base?` | `{status:'updated', url, number, title, state, base, rateLimit}` ou erro estruturado |
|
|
160
|
-
| `gh_review` | leitura | `pr*` (number / `#n` / `o/r#n` / URL), `fields?`, `maxDiffChars?` | metadados, diff limitado (texto completo `diff.text` + trecho limitado `diff.excerpt` + estatísticas por arquivo), comentários, CI, achados estáticos, campos de `error` por seção, limite de taxa |
|
|
161
|
-
| `gh_repo` | leitura | `ownerRepo?` | `{repo, description, defaultBranch, visibility, stars, forks, openIssues, language, license, topics, url, updatedAt, rateLimit}` ou erro estruturado |
|
|
162
|
-
| `gh_file` | leitura | `ownerRepo?`, `path*`, `ref?`, `maxChars?` | `{repo, path, ref, size, truncated, content, sha, url, rateLimit}` ou erro estruturado |
|
|
163
|
-
| `gh_issue` | leitura | `action*` (`list`/`get`/`comments`), `ownerRepo?`, `issueNumber?`, `state?`, `limit?` | itens normalizados (cada um marcado `kind: issue/pr/comment`) + limite de taxa |
|
|
164
|
-
| `review_post` | gravação | `jobId*`, `mode?` (`summary`/`inline`), `body?` | `{status:'posted', mode, url, commentId?, reviewId?, findings, rateLimit}` ou erro estruturado |
|
|
165
|
-
| `issue_open` | gravação | `title*`, `body?`, `labels?`, `ownerRepo?` | `{status:'created', url, number, title, rateLimit}` ou erro estruturado |
|
|
166
|
-
| `issue_comment` | gravação | `issueNumber*`, `body*`, `ownerRepo?` | `{status:'commented', url, commentId, issueNumber, rateLimit}` ou erro estruturado |
|
|
167
|
-
| `issue_close` | gravação | `issueNumber*`, `ownerRepo?`, `stateReason?` (`completed`/`not_planned`) | `{status:'closed', url, number, title, rateLimit}` ou erro estruturado |
|
|
168
|
-
| `gh_search` | leitura | `q*`, `sort?`, `order?`, `perPage?` | `{query, total, items[{number,title,state,kind,author,url,repo,comments,createdAt}], rateLimit}` ou erro estruturado |
|
|
169
|
-
|
|
170
|
-
`execute` retorna apenas o JSON canônico declarado por `output.schema`. Falhas de token ausente e da API do GitHub são variantes de erro estruturado que carregam fatos do limite de taxa; falhas de infraestrutura lançam exceção (→ `isError`). `exec.signal` é respeitado em todos os lugares.
|
|
171
|
-
|
|
172
|
-
## ⌨️ Comandos
|
|
173
|
-
|
|
174
|
-
| Comando | Efeito |
|
|
175
|
-
|---|---|
|
|
176
|
-
| `/pr create [title]` | Lê o estado do git e enfileira uma instrução `pr_create` para o modelo (corpo rascunhado, padrões, sem commit/push a menos que `autoCommit`). Criar o PR solicita aprovação. |
|
|
177
|
-
| `/review <pr>` | Inicia um job de revisão em segundo plano; imprime o id do job. A conclusão é anunciada pelo host; leia-a com `job_output`. |
|
|
178
|
-
| `/review <pr> --max-diff <n> --no-ci --no-comments` | Substituições por job: limite de diff e quais seções suplementares o job busca. |
|
|
179
|
-
| `/review stop <jobId>` | Cancela o job (controle local, sem gravação no GitHub). |
|
|
180
|
-
| `/review post <jobId>` | Enfileira uma instrução `review_post` para o modelo (resumo ou inline); publicar solicita aprovação. |
|
|
181
|
-
| `/issue open <title>` | Enfileira uma instrução `issue_open` para o modelo; criar solicita aprovação. |
|
|
112
|
+
| `ci` | `{ enabled: false, … }` | Seção de integração CI: bot de revisão por polling, barreira de status-check e a ferramenta de execução única `ci_run` (contém todas as chaves `ci.*`) |
|
|
182
113
|
|
|
183
|
-
##
|
|
114
|
+
## Ferramentas e superfícies
|
|
184
115
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
116
|
+
| Superfície | Tipo | Observações |
|
|
117
|
+
|---|---|---|
|
|
118
|
+
| `pr_create` | ferramenta | Cria uma pull request (gravação; com aprovação) |
|
|
119
|
+
| `pr_merge` | ferramenta | Mescla uma PR (merge/squash/rebase, exclusão opcional da rama head) |
|
|
120
|
+
| `pr_update` | ferramenta | Atualiza uma PR (título/corpo/estado/rama base) |
|
|
121
|
+
| `gh_review` | ferramenta | Lê uma PR: metadados, diff limitado, comentários, CI, achados estáticos |
|
|
122
|
+
| `review_post` | ferramenta | Publica um comentário de revisão (resumo ou inline ancorado por linha) |
|
|
123
|
+
| `gh_issue` | ferramenta | Lista / obtém / comenta issues (PRs marcados `kind: "pr"`) |
|
|
124
|
+
| `issue_open` | ferramenta | Cria um issue |
|
|
125
|
+
| `issue_comment` | ferramenta | Comenta um issue ou PR |
|
|
126
|
+
| `issue_close` | ferramenta | Fecha um issue (motivo de estado opcional) |
|
|
127
|
+
| `gh_search` | ferramenta | Pesquisa issues e PRs (cota de busca separada) |
|
|
128
|
+
| `gh_repo` | ferramenta | Lê os metadados do repositório |
|
|
129
|
+
| `gh_file` | ferramenta | Lê um arquivo em uma rama/tag/commit |
|
|
130
|
+
| `/pr create` | comando | Lê o estado do git e enfileira uma instrução `pr_create` |
|
|
131
|
+
| `/review` | comando | Inicia / para / publica um job de revisão em segundo plano |
|
|
132
|
+
| `/issue open` | comando | Enfileira uma instrução `issue_open` |
|
|
133
|
+
| `ci_run` | ferramenta | Revisão CI de execução única conduzida pela ação composta / driver CI |
|
|
134
|
+
| bot de revisão | superfície | Bot de revisão por polling com comentários inline idempotentes (`ci.*`) |
|
|
135
|
+
| barreira de status-check | superfície | Publica o veredito `success` / `needs-changes` por commit head de PR (`action.yml`) |
|
|
136
|
+
|
|
137
|
+
## Arquitetura
|
|
205
138
|
|
|
206
139
|
- **Camada de credenciais.** `tokenSource: auto` resolve por operação na ordem camada de credenciais (referência `GITHUB_TOKEN`) → variável de ambiente → token da CLI `gh`. O valor é uma variável local entregue ao cliente REST; ele nunca entra em valores canônicos, renderizações, cards, saídas de comandos, avisos injetados, saídas de jobs, motivos de aprovação ou mensagens de erro.
|
|
207
|
-
- **
|
|
208
|
-
- **
|
|
209
|
-
- **
|
|
210
|
-
|
|
140
|
+
- **Barreira de aprovação.** Todas as gravações passam pelas ferramentas do modelo. Um listener waterfall `tools/pre-execute` retorna `ask` para as ferramentas de gravação, de modo que o registro pergunta ao humano por meio de `ctx.approval` (o host registra o par de auditoria `approval/asked` + `approval/decided`) e falha fechado sem um respondedor. Comandos nunca gravam diretamente: um comando de gravação coleta contexto somente leitura e então acorda o agente para que o modelo execute a ferramenta com aprovação dentro de um turno.
|
|
141
|
+
- **Job de revisão em segundo plano.** `/review <pr>` inicia um job `github-review` em `ctx.jobs`; o job busca metadados (capturando o SHA do commit head para a publicação inline), o diff limitado, as verificações de CI e os comentários existentes, e então executa o analisador determinístico de múltiplos arquivos (`src/review.ts`). Com `reviewMode: "model"`, o job entrega o diff limitado a um subagente de uso único pela seam `subagents` do host. A conclusão chega à sessão por meio do consumidor `dsh-tool-jobs` do host; o modelo a lê com `job_output` e a publica com `review_post`.
|
|
142
|
+
- **Ação composta de CI / bot de revisão / barreira de status-check.** O repositório inclui uma ação composta (`action.yml`) que revisa PRs, corrige CI e escreve o relatório; um bot de revisão por polling publica comentários inline idempotentes; e uma barreira de status-check publica o veredito por commit head de PR. A ferramenta de execução única `ci_run` conduz a execução headless. Toda gravação permanece sujeita a aprovação.
|
|
143
|
+
|
|
144
|
+
## Permissões e dados
|
|
211
145
|
|
|
212
|
-
|
|
146
|
+
- **Permissões**: as gravações usam a camada de aprovação oficial; nada é reimplementado nem contornado. O plugin declara `network:outbound` e `filesystem:write` em seu manifesto de workshop.
|
|
147
|
+
- **Dados**: o relatório de revisão vive na memória do processo, indexado pelo id do job; nada durável é gravado em disco.
|
|
148
|
+
- **Log de sessão**: o plugin não adiciona tipos de evento de sessão personalizados; todo conteúdo visível ao modelo flui por superfícies registradas pelo host (`tool/result`, `user/message`, `command/run`, `approval/asked`…).
|
|
213
149
|
|
|
214
|
-
|
|
215
|
-
- Toda gravação no GitHub exige `allowed-once` de `ctx.approval` (política padrão `ask`); `rejected`, `cancelled` e `unavailable` falham todos de forma fechada.
|
|
216
|
-
- `/pr create` nunca faz commit ou push por conta própria; com `autoCommit: true`, o modelo realiza essas gravações pela própria barreira de aprovação da ferramenta bash. O dsh-github **não** gerencia a identidade do git (trabalho do dsh-git-identity) nem worktrees (trabalho do dsh-worktree).
|
|
217
|
-
- O job de revisão não realiza gravações: ele lê um diff e armazena um relatório na memória do processo; apenas `review_post` publica, após aprovação.
|
|
218
|
-
- Os comentários publicados interpolam nomes de arquivo derivados do diff, que são conteúdo de repositório não confiável: `formatPostBody` escapa as crases e escapa em HTML os nomes de arquivo para que uma PR hostil não possa injetar Markdown no comentário de revisão.
|
|
219
|
-
- O conteúdo de arquivos lido por `gh_file` e os corpos de issues/PRs, os comentários e os resultados de busca lidos do GitHub são conteúdo externo não confiável que entra no contexto do modelo — a mesma contrapartida inerente à busca na web; o plugin os marca como conteúdo externo em suas renderizações.
|
|
220
|
-
- Limites de taxa: os 429 são repetidos com backoff e a cota restante é exibida ao modelo em todo resultado, incluindo falhas.
|
|
150
|
+
## Limites de segurança
|
|
221
151
|
|
|
222
|
-
|
|
152
|
+
- **Aprovação, não aplicação.** As gravações apenas produzem decisões `ask`/deny na camada oficial; o sandbox e os sistemas de aprovação continuam sendo a autoridade de aplicação.
|
|
153
|
+
- **Falha fechada.** A ausência de respondedor de aprovação degrada para a decisão mais estrita — nunca para uma passagem silenciosa.
|
|
154
|
+
- **O token nunca sai do processo.** É lido por operação e enviado apenas no cabeçalho Authorization; nunca é registrado, renderizado, injetado nem aparece em erros.
|
|
155
|
+
- **Sem gravações fora da aprovação.** `/pr create` nunca faz commit ou push por conta própria; com `autoCommit: true`, o modelo realiza essas gravações pela própria barreira de aprovação da ferramenta bash. O job de revisão não realiza gravações; apenas `review_post` publica, após aprovação.
|
|
156
|
+
- **Conteúdo não confiável é escapado e marcado.** `formatPostBody` escapa as crases e em HTML os nomes de arquivo derivados do diff, e o conteúdo externo do GitHub (arquivos, corpos, comentários, resultados de busca) é marcado como externo nas renderizações.
|
|
157
|
+
- **Trabalho limitado e limites de taxa.** Os 429 são repetidos com backoff; a cota restante é exibida em todo resultado, incluindo falhas.
|
|
158
|
+
|
|
159
|
+
## Limitações conhecidas
|
|
223
160
|
|
|
224
161
|
- **Sem eventos de sessão personalizados** — deliberado (veja Arquitetura); as trilhas de auditoria dependem do próprio vocabulário de eventos do host.
|
|
225
|
-
- **Analisador estático por padrão** — regras determinísticas (`src/review.ts`), zero tokens, reproduzível. `reviewMode: "model"`
|
|
226
|
-
- **Jobs e registros são locais ao processo** — o relatório de revisão vive na memória do plugin, indexado pelo id do job
|
|
227
|
-
- **As dist-tags `latest` do npm estão desatualizadas** —
|
|
228
|
-
- **CI / GitHub Action** — incluído neste repositório (v0.6.0): uma ação composta (`action.yml`) que revisa PRs, corrige CI e escreve o relatório; um bot de revisão por polling com comentários inline idempotentes; e um gate de status-check. Toda gravação permanece sujeita a aprovação.
|
|
162
|
+
- **Analisador estático por padrão** — regras determinísticas (`src/review.ts`), zero tokens, reproduzível. `reviewMode: "model"` consome tokens e requer a seam `subagents` e um provedor registrado.
|
|
163
|
+
- **Jobs e registros são locais ao processo** — o relatório de revisão vive na memória do plugin, indexado pelo id do job; o mapa de registros é limitado por `maxReviewRecords` (os registros concluídos mais antigos são removidos primeiro).
|
|
164
|
+
- **As dist-tags `latest` do npm estão desatualizadas** — instale por meio do fechamento de perfil que o `dsh-base` fornece; nunca com um simples `npm i @deepseek-ai/dsh-tools`.
|
|
229
165
|
|
|
230
|
-
##
|
|
166
|
+
## Desenvolvimento
|
|
231
167
|
|
|
232
168
|
```sh
|
|
233
|
-
pnpm install
|
|
234
|
-
pnpm
|
|
235
|
-
pnpm
|
|
236
|
-
pnpm
|
|
237
|
-
pnpm
|
|
238
|
-
pnpm run
|
|
169
|
+
pnpm install # node ^22.19 || >=24
|
|
170
|
+
pnpm run build # tsc --noEmitOnError → lib/
|
|
171
|
+
pnpm run prepare # build autocontido para instalação via git (scripts/prepare.mjs)
|
|
172
|
+
pnpm run prepublishOnly # compilar + testar antes de publicar
|
|
173
|
+
pnpm test # vitest run
|
|
174
|
+
pnpm run typecheck # tsc --noEmit
|
|
175
|
+
pnpm run check:readmes # cruza âncoras de TOC, ferramentas e chaves de configuração nos 5 READMEs
|
|
239
176
|
```
|
|
240
177
|
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
## 🗂 Estrutura do repositório
|
|
178
|
+
## Estrutura do repositório
|
|
244
179
|
|
|
245
180
|
```
|
|
246
181
|
src/index.ts plugin entry (name/inject/apply, applyWithDeps for tests)
|
|
@@ -260,12 +195,36 @@ cordis.patch.yml bundle patch (one insert row)
|
|
|
260
195
|
scripts/prepare.mjs self-contained git-install build
|
|
261
196
|
```
|
|
262
197
|
|
|
263
|
-
##
|
|
264
|
-
|
|
265
|
-
Tópicos recomendados do repositório GitHub (defina-os nas configurações do repositório — eles alimentam a [página de tópicos `dsh-plugin`](https://github.com/topics/dsh-plugin) e os marketplaces de plugins DSH):
|
|
198
|
+
## Tópicos
|
|
266
199
|
|
|
267
200
|
`dsh` · `dsh-plugin` · `deepseek-harness` · `github` · `pull-request` · `code-review` · `issue-tracker`
|
|
268
201
|
|
|
202
|
+
## Contribuidores
|
|
203
|
+
|
|
204
|
+
- [@PerryLink](https://github.com/PerryLink) — criador e mantenedor: a superfície de ferramentas do GitHub, a barreira de aprovação, os jobs de revisão em segundo plano, a ação composta de CI, o bot de revisão, a barreira de status-check e a documentação em cinco idiomas.
|
|
205
|
+
|
|
206
|
+
## Família de plugins DSH da PerryLink
|
|
207
|
+
|
|
208
|
+
Este projeto é um dos [15 plugins do DeepSeek Harness](https://github.com/PerryLink) mantidos por [PerryLink](https://github.com/PerryLink). Se este lhe ajuda, os outros provavelmente também ajudarão:
|
|
209
|
+
|
|
210
|
+
| Plugin | Descrição |
|
|
211
|
+
|---|---|
|
|
212
|
+
| [dsh-mcp-panel](https://github.com/PerryLink/dsh-mcp-panel) | Painel MCP de somente leitura em tempo de execução: comando /mcp + aba de ajustes com status, ferramentas e erros |
|
|
213
|
+
| [dsh-doublecheck](https://github.com/PerryLink/dsh-doublecheck) | Guardião de disciplina de engenharia: interrogatório de requisitos, portões de testes, revisão adversária |
|
|
214
|
+
| [dsh-background-agents](https://github.com/PerryLink/dsh-background-agents) | Agentes filhos em segundo plano duráveis com barra lateral web, mensagens e interrupção |
|
|
215
|
+
| [dsh-lsp-actions](https://github.com/PerryLink/dsh-lsp-actions) | Diagnósticos, formatação, conclusão, ações de código e renomeação LSP sobre servidores de linguagem |
|
|
216
|
+
| [dsh-output-styles](https://github.com/PerryLink/dsh-output-styles) | Troca de estilo em tempo de execução equivalente ao outputStyles do Claude Code |
|
|
217
|
+
| [dsh-checkpoint-rewind](https://github.com/PerryLink/dsh-checkpoint-rewind) | Equivalente ao /rewind do Claude Code: instantâneos, bifurcações de sessão, restauração de uso único |
|
|
218
|
+
| [dsh-permission-rules](https://github.com/PerryLink/dsh-permission-rules) | Regras de permissão declarativas allow/deny/ask estilo Claude Code com auditoria |
|
|
219
|
+
| [dsh-auto-review](https://github.com/PerryLink/dsh-auto-review) | Auto-revisão por segundo modelo na cadeia de aprovação, falha fechada por padrão |
|
|
220
|
+
| [dsh-memento](https://github.com/PerryLink/dsh-memento) | Memória entre sessões com aprovação: seam ctx.memory + SQLite + ferramenta de memória |
|
|
221
|
+
| [dsh-skill-pack-security](https://github.com/PerryLink/dsh-skill-pack-security) | Pacote de habilidades de auditoria de segurança: varredura de segredos, revisão de dependências e cadeia de suprimentos |
|
|
222
|
+
| [dsh-session-pin](https://github.com/PerryLink/dsh-session-pin) | Fixa sessões na barra lateral web com ordenação durável |
|
|
223
|
+
| [dsh-composer-history](https://github.com/PerryLink/dsh-composer-history) | Histórico de entrada estilo terminal para o compositor web: setas, busca Ctrl+R |
|
|
224
|
+
| **[dsh-github](https://github.com/PerryLink/dsh-github)** | Integração de PR/issues do GitHub para DSH, toda gravação com aprovação |
|
|
225
|
+
| [dsh-plugin-guide](https://github.com/PerryLink/dsh-plugin-guide) | Base de conhecimento de desenvolvimento de plugins como habilidade de agente sob demanda |
|
|
226
|
+
| [dsh-claude-move](https://github.com/PerryLink/dsh-claude-move) | Migra sessões, memória, habilidades e CLAUDE.md do Claude Code para o DSH |
|
|
227
|
+
|
|
269
228
|
## Licença
|
|
270
229
|
|
|
271
|
-
[Apache License 2.0](LICENSE)
|
|
230
|
+
[Apache License 2.0](LICENSE) © 2026 dsh-github contributors
|