agents-gitflow-guard 0.0.26 → 0.0.28
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.de.md +211 -0
- package/README.es.md +137 -0
- package/README.fr.md +138 -0
- package/README.it.md +137 -0
- package/README.ja.md +466 -0
- package/README.ko.md +136 -0
- package/README.md +1 -1
- package/README.pt.md +137 -0
- package/README.ru.md +136 -0
- package/README.zh-tw.md +136 -0
- package/README.zh.md +1 -1
- package/package.json +11 -2
package/README.pt.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# agents-gitflow-guard
|
|
2
|
+
|
|
3
|
+
> **Cansado de agentes de IA ignorando seu GitFlow?**
|
|
4
|
+
|
|
5
|
+
Um guardião configurável para papéis de branches Git, desenvolvido para agentes de codificação IA — [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity e Pi.
|
|
6
|
+
Defina suas próprias branches — **integration** (funcionalidades são mescladas via PR/MR), **preview** (ambientes de teste), **production** (produção), **archive** (arquivo) — cada uma com suas próprias regras de atualização. Os agentes não podem burlar o processo e os merges críticos permanecem sob seu controle humano.
|
|
7
|
+
|
|
8
|
+
[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Licença](LICENSE)
|
|
9
|
+
|
|
10
|
+
[](https://ko-fi.com/keanz21)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Índice
|
|
15
|
+
|
|
16
|
+
- [Início Rápido — 30 segundos para proteger seu repositório](#início-rápido--30-segundos-para-proteger-seu-repositório)
|
|
17
|
+
- [Por que — O problema resolvido por este plugin](#por-que--o-problema-resolvido-por-este-plugin)
|
|
18
|
+
- [Para quem — Cenários e equipes](#para-quem--cenários-e-equipes)
|
|
19
|
+
- [Funcionalidades — O que o plugin faz](#funcionalidades--o-que-o-plugin-faz)
|
|
20
|
+
- [O que o plugin NÃO faz — Limites](#o-que-o-plugin-não-faz--limites)
|
|
21
|
+
- [Proteção do lado do servidor vs este plugin](#proteção-do-lado-do-servidor-vs-este-plugin)
|
|
22
|
+
- [Como funciona — O mecanismo em três linhas](#como-funciona--o-mecanismo-em-três-linhas)
|
|
23
|
+
- [Referência de Configuração](#referência-de-configuração)
|
|
24
|
+
- [Matriz de Decisão — O que é bloqueado e o que é permitido](#matriz-de-decisão--o-que-é-bloqueado-e-o-que-é-permitido)
|
|
25
|
+
- [Onde o humano mantém o controle](#onde-o-humano-mantém-o-controle)
|
|
26
|
+
- [Instalação Detalhada](#instalação-detalhada)
|
|
27
|
+
- [Perguntas Frequentes (FAQ)](#perguntas-frequentes-faq)
|
|
28
|
+
- [Glossário](#glossário)
|
|
29
|
+
- [Roteiro (Roadmap)](#roteiro-roadmap)
|
|
30
|
+
- [Suporte](#suporte)
|
|
31
|
+
- [Desenvolvimento](#desenvolvimento)
|
|
32
|
+
- [Licença](#licença)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Início Rápido — 30 segundos para proteger seu repositório
|
|
37
|
+
|
|
38
|
+
**Passo 1 — Instalação.** Todos os seis clientes utilizam o mesmo pacote npm `agents-gitflow-guard`:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
# DSH — Plugin in-process (reinicie o DSH após a instalação)
|
|
42
|
+
dsh plugin --profile web add agents-gitflow-guard
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# Claude Code · Codex · OpenCode · Antigravity — Hooks autônomos (sem necessidade de DSH)
|
|
47
|
+
npm i -g agents-gitflow-guard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Pi — Extensão in-process
|
|
52
|
+
npm i -D agents-gitflow-guard
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Passo 2 — Conectar o cliente (nenhum arquivo de configuração necessário).** O plugin vem com **padrões integrados que protegem `develop` (integração) + `main` (arquivo)** — ativado por padrão com zero configuração:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Claude Code → .claude/settings.json deste repositório
|
|
59
|
+
gitflow-guard wire --client claude --project --yes
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
# Codex / OpenCode / Antigravity (arquivos dedicados por cliente)
|
|
64
|
+
gitflow-guard wire --client codex --project --yes
|
|
65
|
+
gitflow-guard wire --client opencode --project --yes
|
|
66
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Pré-visualização sem gravação / Remoção / Assistente interativo:
|
|
71
|
+
gitflow-guard wire --client claude --dry-run
|
|
72
|
+
gitflow-guard wire --client claude --unwire
|
|
73
|
+
gitflow-guard setup
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`wire` insere as configurações de forma **não destrutiva** nos arquivos existentes.
|
|
77
|
+
|
|
78
|
+
> ⚠️ **main é protegido por padrão.** Para fluxos Trunk-based, desative o guard definindo `{ "enabled": false }` em `gitflow-guard.config.json`.
|
|
79
|
+
|
|
80
|
+
**Passo 3 — Verificação.** Peça ao agente para executar `git push origin develop`. A operação será bloqueada:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
|
|
84
|
+
Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Por que — O problema resolvido por este plugin
|
|
90
|
+
|
|
91
|
+
Os agentes de codificação IA trabalham diretamente no seu repositório. As instruções em prompts e arquivos de documentação (`AGENTS.md`, `CLAUDE.md`, etc.) são **regras flexíveis**: os modelos podem ignorá-las ou esquecê-las.
|
|
92
|
+
|
|
93
|
+
Este plugin transforma regras de texto em **mecanismos rígidos**. Qualquer comando Git executado pelo agente é interceptado e validado contra o estado real do repositório local antes de sua execução.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Funcionalidades — O que o plugin faz
|
|
98
|
+
|
|
99
|
+
- **Bloqueio pré-execução**: Push direto, force push e exclusão de branches protegidas (integration, preview, production, archive) são bloqueados antes de rodar.
|
|
100
|
+
- **Merge exclusivo por humanos (Merge-by-user)**: Os agentes podem criar PR/MR para produção ou arquivo, mas o merge efetivo só pode ser realizado pelo usuário.
|
|
101
|
+
- **Auditoria segura**: Todo bloqueio é registrado em `~/.local/state/gitflow-guard/` fora do repositório.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Matriz de Decisão — O que é bloqueado e o que é permitido
|
|
106
|
+
|
|
107
|
+
| Ação do Agente | Decisão |
|
|
108
|
+
|---|---|
|
|
109
|
+
| commit / push na branch feature / sync / rebase | ✅ allow (permitido) |
|
|
110
|
+
| Push direto / force push / exclusão em integration / preview / production / archive | 🚫 block (bloqueado) |
|
|
111
|
+
| Criação de PR/MR: feature → integration / preview | ✅ allow (permitido) |
|
|
112
|
+
| Criação de PR/MR: feature → production | ✅ Criação permitida; **Merge bloqueado** (usuário realiza o merge) |
|
|
113
|
+
| Criação de PR/MR → archive | ✅ Criação permitida; 🚫 **Merge bloqueado** (usuário realiza o merge) |
|
|
114
|
+
| `git merge feature/x` local em integration / preview | 🚫 block (PR/MR obrigatório) |
|
|
115
|
+
| Comandos encadeados (`checkout develop && merge feature/x`) | 🚫 block (simulado por segmento) |
|
|
116
|
+
| `git checkout -B` / `git switch -C` para branches protegidas | 🚫 block |
|
|
117
|
+
| Comandos Git executados via `sudo` | 🚫 Invólucro removido e comando subjacente validado |
|
|
118
|
+
|
|
119
|
+
---
|
|
120
|
+
|
|
121
|
+
## Instalação Detalhada
|
|
122
|
+
|
|
123
|
+
**Pré-requisito**: **Node.js ≥ 22** no seu `PATH`.
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
npm i -g agents-gitflow-guard
|
|
127
|
+
gitflow-guard wire --client claude --project --yes
|
|
128
|
+
gitflow-guard wire --client codex --project --yes
|
|
129
|
+
gitflow-guard wire --client opencode --project --yes
|
|
130
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Licença
|
|
136
|
+
|
|
137
|
+
[MIT](LICENSE) © FeatureAgents
|
package/README.ru.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# agents-gitflow-guard
|
|
2
|
+
|
|
3
|
+
> **Устали от того, что ИИ-агенты нарушают ваш GitFlow?**
|
|
4
|
+
|
|
5
|
+
Настраиваемый страж ролей веток Git для ИИ-агентов кодинга — поддержка [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH), Claude Code, Codex, OpenCode, Antigravity и Pi.
|
|
6
|
+
Определяйте свои ветки — **integration** (слияние фич через PR/MR), **preview** (тестовые окружения), **production** (продакшн), **archive** (архив) — каждая со своими правилами. Агенты не могут обойти процесс, а критические слияния остаются под контролем человека.
|
|
7
|
+
|
|
8
|
+
[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [Лицензия](LICENSE)
|
|
9
|
+
|
|
10
|
+
[](https://ko-fi.com/keanz21)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## Содержание
|
|
15
|
+
|
|
16
|
+
- [Быстрый старт — Защита репозитория за 30 секунд](#быстрый-старт--защита-репозитория-за-30-секунд)
|
|
17
|
+
- [Зачем это нужно — Проблема, которую решает плагин](#зачем-это-нужно--проблема-которую-решает-плагин)
|
|
18
|
+
- [Для кого — Сценарии и команды](#для-кого--сценарии-и-команды)
|
|
19
|
+
- [Возможности — Что делает плагин](#возможности--что-делает-плагин)
|
|
20
|
+
- [Ограничения — Чего плагин НЕ делает](#ограничения--чего-плагин-не-делает)
|
|
21
|
+
- [Защита на стороне сервера vs этот плагин](#защита-на-стороне-сервера-vs-этот-плагин)
|
|
22
|
+
- [Принцип работы — Механизм в трех строках](#принцип-работы--механизм-в-трех-строках)
|
|
23
|
+
- [Справочник по конфигурации](#справочник-по-конфигурации)
|
|
24
|
+
- [Матрица решений — Что блокируется, а что разрешено](#матрица-решений--что-блокируется-а-что-разрешено)
|
|
25
|
+
- [Контроль человека](#контроль-человека)
|
|
26
|
+
- [Подробная установка](#подробная-установка)
|
|
27
|
+
- [Часто задаваемые вопросы (FAQ)](#часто-задаваемые-вопросы-faq)
|
|
28
|
+
- [Глоссарий](#глоссарий)
|
|
29
|
+
- [Планы развития (Roadmap)](#планы-развития-roadmap)
|
|
30
|
+
- [Поддержка](#поддержка)
|
|
31
|
+
- [Разработка](#разработка)
|
|
32
|
+
- [Лицензия](#лицензия)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Быстрый старт — Защита репозитория за 30 секунд
|
|
37
|
+
|
|
38
|
+
**Шаг 1 — Установка.** Все 6 клиентов используют один и тот же npm-пакет `agents-gitflow-guard`:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
# DSH — Внутрипроцессный плагин (перезапустите DSH после установки)
|
|
42
|
+
dsh plugin --profile web add agents-gitflow-guard
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# Claude Code · Codex · OpenCode · Antigravity — Автономные хуки (DSH не требуется)
|
|
47
|
+
npm i -g agents-gitflow-guard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Pi — Внутрипроцессное расширение
|
|
52
|
+
npm i -D agents-gitflow-guard
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Шаг 2 — Подключение клиента (файл конфигурации не требуется).** Плагин поставляется со **встроенными настройками по умолчанию, защищающими `develop` (интеграция) + `main` (архив)** — включен сразу без настроек:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Claude Code → .claude/settings.json текущего репозитория
|
|
59
|
+
gitflow-guard wire --client claude --project --yes
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
# Codex / OpenCode / Antigravity (отдельные файлы конфигурации для каждого клиента)
|
|
64
|
+
gitflow-guard wire --client codex --project --yes
|
|
65
|
+
gitflow-guard wire --client opencode --project --yes
|
|
66
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Предпросмотр без записи / Удаление / Интерактивный мастер:
|
|
71
|
+
gitflow-guard wire --client claude --dry-run
|
|
72
|
+
gitflow-guard wire --client claude --unwire
|
|
73
|
+
gitflow-guard setup
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`wire` внедряет конфигурацию **неразрушающим образом** в существующие файлы.
|
|
77
|
+
|
|
78
|
+
> ⚠️ **main защищен по умолчанию.** Для Trunk-based разработки отключите плагин, указав `{ "enabled": false }` в `gitflow-guard.config.json`.
|
|
79
|
+
|
|
80
|
+
**Шаг 3 — Проверка.** Попросите агента выполнить `git push origin develop`. Команда будет заблокирована:
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
|
|
84
|
+
Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## Зачем это нужно — Проблема, которую решает плагин
|
|
90
|
+
|
|
91
|
+
ИИ-агенты кодинга работают непосредственно в вашем репозитории. Инструкции в системных промптах и проектных файлах (`AGENTS.md`, `CLAUDE.md` и др.) — это лишь **мягкие правила**, которые модели могут пропустить или проигнорировать.
|
|
92
|
+
|
|
93
|
+
Этот плагин превращает текстовые правила в **жесткие системные ограничения**. Каждая Git-команда перехватывается и проверяется относительно реального состояния локального репозитория до ее фактического запуска.
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Возможности — Что делает плагин
|
|
98
|
+
|
|
99
|
+
- **Блокировка до выполнения**: Прямой push, force push и удаление защищенных веток (integration, preview, production, archive) блокируются до старта.
|
|
100
|
+
- **Слияние только человеком (Merge-by-user)**: Агенты могут создавать PR/MR, но фактическое слияние в production/archive выполняет только человек в веб-интерфейсе.
|
|
101
|
+
- **Безопасный журнал аудита**: Все факты блокировок записываются в `~/.local/state/gitflow-guard/` вне рабочего каталога репозитория.
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## Матрица решений — Что блокируется, а что разрешено
|
|
106
|
+
|
|
107
|
+
| Действие агента | Решение |
|
|
108
|
+
|---|---|
|
|
109
|
+
| commit / push в ветке feature / rebase / sync | ✅ allow (разрешено) |
|
|
110
|
+
| Прямой push / force push / удаление в integration / preview / production / archive | 🚫 block (заблокировано) |
|
|
111
|
+
| Создание PR/MR: feature → integration / preview | ✅ allow (разрешено) |
|
|
112
|
+
| Создание PR/MR: feature → production | ✅ Создание разрешено; **Слияние заблокировано** (выполняет человек) |
|
|
113
|
+
| Создание PR/MR → archive | ✅ Создание разрешено; 🚫 **Слияние заблокировано** (выполняет человек) |
|
|
114
|
+
| Локальный `git merge feature/x` на integration / preview | 🚫 block (требуется PR/MR) |
|
|
115
|
+
| Принудительное пересоздание защищенной ветки (`git checkout -B` / `git switch -C`) | 🚫 block |
|
|
116
|
+
| Git-команды, обернутые в `sudo` | 🚫 Оболочка снимается, проверяется вложенная Git-команда |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Подробная установка
|
|
121
|
+
|
|
122
|
+
**Требование**: **Node.js ≥ 22** в вашем `PATH`.
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npm i -g agents-gitflow-guard
|
|
126
|
+
gitflow-guard wire --client claude --project --yes
|
|
127
|
+
gitflow-guard wire --client codex --project --yes
|
|
128
|
+
gitflow-guard wire --client opencode --project --yes
|
|
129
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## Лицензия
|
|
135
|
+
|
|
136
|
+
[MIT](LICENSE) © FeatureAgents
|
package/README.zh-tw.md
ADDED
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
# agents-gitflow-guard
|
|
2
|
+
|
|
3
|
+
> **有沒有受夠了 AI Agent 隨意跳過你的 GitFlow 合併流程？**
|
|
4
|
+
|
|
5
|
+
一個可自由配置分支角色的流程守衛，專為 AI 寫碼 Agent 而生 — 支援 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)、Claude Code、Codex、OpenCode、Antigravity 與 Pi。
|
|
6
|
+
你自己定義分支 — **集成分支**（feature 經 PR/MR 合入）、**預覽分支**（環境端點）、**生產分支**、**歸檔分支** — 每個角色各自配置規則。Agent 無法跳過流程，敏感合併始終留在你手上。
|
|
7
|
+
|
|
8
|
+
[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [授權條款](LICENSE)
|
|
9
|
+
|
|
10
|
+
[](https://ko-fi.com/keanz21)
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 目錄
|
|
15
|
+
|
|
16
|
+
- [快速上手 — 30 秒為倉庫啟用守衛](#快速上手--30-秒為倉庫啟用守衛)
|
|
17
|
+
- [為什麼需要 — 本外掛解決的核心痛點](#為什麼需要--本外掛解決的核心痛點)
|
|
18
|
+
- [適用對象 — 場景與團隊](#適用對象--場景與團隊)
|
|
19
|
+
- [功能特點 — 它能做什麼](#功能特點--它能做什麼)
|
|
20
|
+
- [局限性 — 它不能做什麼](#局限性--它不能做什麼)
|
|
21
|
+
- [服務端分支保護 vs 本外掛](#服務端分支保護-vs-本外掛)
|
|
22
|
+
- [運作機制 — 三行看懂底層原理](#運作機制--三行看懂底層原理)
|
|
23
|
+
- [配置參考](#配置參考)
|
|
24
|
+
- [門禁判定矩陣 — 攔截與放行清單](#門禁判定矩陣--攔截與放行清單)
|
|
25
|
+
- [人為介入與控制點](#人為介入與控制點)
|
|
26
|
+
- [詳細安裝指南](#詳細安裝指南)
|
|
27
|
+
- [常見問題 (FAQ)](#常見問題-faq)
|
|
28
|
+
- [術語表](#術語表)
|
|
29
|
+
- [路線圖 (Roadmap)](#路線圖-roadmap)
|
|
30
|
+
- [支援與贊助](#支援與贊助)
|
|
31
|
+
- [開發](#開發)
|
|
32
|
+
- [授權條款](#授權條款)
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 快速上手 — 30 秒為倉庫啟用守衛
|
|
37
|
+
|
|
38
|
+
**第 1 步 — 安裝。** 六個客戶端共用同一個 npm 套件 `agents-gitflow-guard`：
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
# DSH — 進程內外掛（安裝後重啟 DSH 生效）
|
|
42
|
+
dsh plugin --profile web add agents-gitflow-guard
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
# Claude Code · Codex · OpenCode · Antigravity — 獨立 Hook（無需 DSH）
|
|
47
|
+
npm i -g agents-gitflow-guard
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
# Pi — 進程內擴充
|
|
52
|
+
npm i -D agents-gitflow-guard
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**第 2 步 — 連接客戶端（無需配置文件）。** 守衛內建 **預設保護 `develop` (integration) + `main` (archive)** — 零配置、開箱即用啟用：
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
# Claude Code → 當前倉庫的 .claude/settings.json
|
|
59
|
+
gitflow-guard wire --client claude --project --yes
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
# Codex / OpenCode / Antigravity（寫入各客戶端專屬設定檔）
|
|
64
|
+
gitflow-guard wire --client codex --project --yes
|
|
65
|
+
gitflow-guard wire --client opencode --project --yes
|
|
66
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# 預覽（不寫入）/ 解除連接 / 互動式精靈：
|
|
71
|
+
gitflow-guard wire --client claude --dry-run
|
|
72
|
+
gitflow-guard wire --client claude --unwire
|
|
73
|
+
gitflow-guard setup
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`wire` 指令會 **非破壞性** 地合併進你現有的設定檔中。
|
|
77
|
+
|
|
78
|
+
> ⚠️ **main 預設受保護。** 若你的團隊採用 Trunk-based 單分支主幹開發，請在 `gitflow-guard.config.json` 中設定 `{ "enabled": false }` 關閉守衛。
|
|
79
|
+
|
|
80
|
+
**第 3 步 — 驗證。** 讓 Agent 嘗試執行 `git push origin develop`，該操作將被直接攔截：
|
|
81
|
+
|
|
82
|
+
```text
|
|
83
|
+
Error: [gitflow-guard] blocked: Protected branch "develop" forbids direct push
|
|
84
|
+
Next: Integration branch (develop) is updated via PR/MR from a feature branch: push the feature first, then `gh pr create --base develop` / `glab mr create --target-branch develop`.
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
## 為什麼需要 — 本外掛解決的核心痛點
|
|
90
|
+
|
|
91
|
+
AI 寫碼 Agent 直接在你的程式碼倉庫中工作。儘管在專案文檔（`AGENTS.md`、`CLAUDE.md` 等）中寫明了流程規約，但那只是文字層面的 **軟約束**。
|
|
92
|
+
|
|
93
|
+
本外掛將軟約束轉化為 **機械式硬門禁**。Agent 嘗試執行的每一條 Git 指令，都會在執行前對比本地倉庫的真實狀態進行判定，違規操作在執行前即被阻斷。
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 功能特點 — 它能做什麼
|
|
98
|
+
|
|
99
|
+
- **執行前攔截**：直推、強制推動、刪除受保護分支（integration、preview、production、archive）均在執行前被攔截。
|
|
100
|
+
- **敏感合併僅限人工 (Merge-by-user)**：Agent 可起草 PR/MR，但生產與歸檔分支的合併必須由用戶親手點擊確認。
|
|
101
|
+
- **不可篡改的審計記錄**：所有攔截日誌寫入倉庫外部的 `~/.local/state/gitflow-guard/` 目錄。
|
|
102
|
+
|
|
103
|
+
---
|
|
104
|
+
|
|
105
|
+
## 門禁判定矩陣 — 攔截與放行清單
|
|
106
|
+
|
|
107
|
+
| Agent 動作 | 門禁判定 |
|
|
108
|
+
|---|---|
|
|
109
|
+
| feature 分支上 commit / push / sync / rebase | ✅ allow (放行) |
|
|
110
|
+
| 直推 / 強推 / 刪除 integration / preview / production / archive | 🚫 block (攔截) |
|
|
111
|
+
| 建立 PR/MR：feature → integration / preview | ✅ allow (放行) |
|
|
112
|
+
| 建立 PR/MR：feature → production | ✅ 允許建立；**禁止合併**（用戶親手點合併） |
|
|
113
|
+
| 建立 PR/MR → archive | ✅ 允許建立；🚫 **禁止合併**（用戶親手點合併） |
|
|
114
|
+
| 在 integration / preview 上本地執行 `git merge feature/x` | 🚫 block (必須走 PR/MR) |
|
|
115
|
+
| 強制重建受保護分支 (`git checkout -B` / `git switch -C`) | 🚫 block (ref-update 門禁攔截) |
|
|
116
|
+
| 透過 `sudo` 包裝的 Git 指令 | 🚫 自動剝除外殼並判定底層 Git 指令 |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## 詳細安裝指南
|
|
121
|
+
|
|
122
|
+
**前置條件**：系統 `PATH` 中需有 **Node.js ≥ 22**。
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
npm i -g agents-gitflow-guard
|
|
126
|
+
gitflow-guard wire --client claude --project --yes
|
|
127
|
+
gitflow-guard wire --client codex --project --yes
|
|
128
|
+
gitflow-guard wire --client opencode --project --yes
|
|
129
|
+
gitflow-guard wire --client antigravity --project --yes
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
---
|
|
133
|
+
|
|
134
|
+
## 授權條款
|
|
135
|
+
|
|
136
|
+
[MIT](LICENSE) © FeatureAgents
|
package/README.zh.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
一个可自由配置分支角色的流程守卫,为 AI 编码 agent 而生——[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)、Claude Code、Codex、OpenCode、Antigravity、Pi。
|
|
6
6
|
你自己定义分支——**集成分支**(feature 经 PR/MR 合入)、**预览分支**(环境终点)、**生产分支**、**归档分支**——每个角色各自配规则。agent 无法跳过流程,敏感合并始终留在你手上。
|
|
7
7
|
|
|
8
|
-
[English](README.md) · [许可证](LICENSE)
|
|
8
|
+
[English](README.md) · [简体中文](README.zh.md) · [繁體中文](README.zh-tw.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Deutsch](README.de.md) · [Français](README.fr.md) · [Italiano](README.it.md) · [Português](README.pt.md) · [Español](README.es.md) · [Русский](README.ru.md) · [许可证](LICENSE)
|
|
9
9
|
|
|
10
10
|
[](https://ko-fi.com/keanz21)
|
|
11
11
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "agents-gitflow-guard",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.28",
|
|
4
4
|
"description": "A configurable branch-role guard for AI coding agents (DSH / Claude Code / Codex / OpenCode / Antigravity / Pi) — zero-config defaults (develop+main) out of the box, deep-merge override, and per-client native hooks via gitflow-guard wire/setup; integration/preview/production/archive, each with its own update rules",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -21,7 +21,16 @@
|
|
|
21
21
|
"pi",
|
|
22
22
|
"opencode",
|
|
23
23
|
"README.md",
|
|
24
|
-
"README.zh.md"
|
|
24
|
+
"README.zh.md",
|
|
25
|
+
"README.zh-tw.md",
|
|
26
|
+
"README.ja.md",
|
|
27
|
+
"README.ko.md",
|
|
28
|
+
"README.de.md",
|
|
29
|
+
"README.fr.md",
|
|
30
|
+
"README.it.md",
|
|
31
|
+
"README.pt.md",
|
|
32
|
+
"README.es.md",
|
|
33
|
+
"README.ru.md"
|
|
25
34
|
],
|
|
26
35
|
"bin": {
|
|
27
36
|
"gitflow-guard": "bin/gitflow-guard.mjs"
|