3bb2f8f1c5
* chore: wire docs/agents config into AGENTS.md Agent skills section
Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: rebrand to GSD Core and restructure docs with Diataxis
Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
* docs: backfill changeset PR number (#605)
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
81 lines
3.2 KiB
Markdown
81 lines
3.2 KiB
Markdown
# Monitor de Janela de Contexto
|
|
|
|
Um hook pós-ferramenta (`PostToolUse` para o Claude Code, `AfterTool` para o Gemini CLI) que avisa o agente quando o uso da janela de contexto está elevado.
|
|
|
|
## Problema
|
|
|
|
A barra de status exibe o uso de contexto para o **usuário**, mas o **agente** não tem consciência dos limites de contexto. Quando o contexto está se esgotando, o agente continua trabalhando até atingir o limite — potencialmente no meio de uma tarefa, sem nenhum estado salvo.
|
|
|
|
## Como Funciona
|
|
|
|
1. O hook da barra de status grava métricas de contexto em `/tmp/claude-ctx-{session_id}.json`
|
|
2. Após cada uso de ferramenta, o monitor de contexto lê essas métricas
|
|
3. Quando o contexto restante cai abaixo dos limiares, ele injeta um aviso como `additionalContext`
|
|
4. O agente recebe o aviso em sua conversa e pode agir de acordo
|
|
|
|
## Limiares
|
|
|
|
| Nível | Restante | Comportamento do Agente |
|
|
|-------|----------|-------------------------|
|
|
| Normal | > 35% | Sem aviso |
|
|
| ALERTA | <= 35% | Encerrar a tarefa atual, evitar iniciar trabalhos complexos novos |
|
|
| CRÍTICO | <= 25% | Parar imediatamente, salvar estado (`/gsd-pause-work`) |
|
|
|
|
## Debounce
|
|
|
|
Para evitar sobrecarregar o agente com avisos repetidos:
|
|
- O primeiro aviso sempre é disparado imediatamente
|
|
- Avisos subsequentes exigem 5 usos de ferramenta entre eles
|
|
- A escalada de severidade (ALERTA -> CRÍTICO) ignora o debounce
|
|
|
|
## Arquitetura
|
|
|
|
```
|
|
Hook da Barra de Status (gsd-statusline.js)
|
|
| escreve
|
|
v
|
|
/tmp/claude-ctx-{session_id}.json
|
|
^ lê
|
|
|
|
|
Monitor de Contexto (gsd-context-monitor.js, PostToolUse/AfterTool)
|
|
| injeta
|
|
v
|
|
additionalContext -> Agente recebe o aviso
|
|
```
|
|
|
|
O arquivo de ponte é um objeto JSON simples:
|
|
|
|
```json
|
|
{
|
|
"session_id": "abc123",
|
|
"remaining_percentage": 28.5,
|
|
"used_pct": 71,
|
|
"timestamp": 1708200000
|
|
}
|
|
```
|
|
|
|
## Integração com o GSD
|
|
|
|
O comando `/gsd-pause-work` do GSD salva o estado de execução. A mensagem de ALERTA sugere utilizá-lo. A mensagem CRÍTICA instrui o salvamento imediato do estado.
|
|
|
|
## Configuração
|
|
|
|
Ambos os hooks são registrados automaticamente durante a instalação do `npx @opengsd/gsd-core` — nenhuma etapa manual é necessária em circunstâncias normais. Para detalhes de configuração de hooks, substituições de limiares e exemplos de registro manual, consulte [Configuração](CONFIGURATION.md).
|
|
|
|
Como referência rápida: o hook da barra de status se registra como `statusLine` em `settings.json`; o monitor de contexto (`gsd-context-monitor.js`) se registra como um hook `PostToolUse` (ou `AfterTool` para o Gemini CLI). Ambas as entradas utilizam o caminho absoluto do executável Node que executou o instalador. No Windows PowerShell, prefixe caminhos de executáveis entre aspas com `&`.
|
|
|
|
## Segurança
|
|
|
|
- O hook envolve tudo em try/catch e encerra silenciosamente em caso de erro
|
|
- Ele nunca bloqueia a execução de ferramentas — um monitor com falha não deve interromper o fluxo de trabalho do agente
|
|
- Métricas obsoletas (com mais de 60s) são ignoradas
|
|
- Arquivos de ponte ausentes são tratados de forma elegante (subagentes, sessões novas)
|
|
|
|
---
|
|
|
|
## Relacionados
|
|
|
|
- [Arquitetura](ARCHITECTURE.md)
|
|
- [Configuração](CONFIGURATION.md)
|
|
- [Índice da documentação](README.md)
|