qiangli/bashy

bashy — o shell agêntico, em uma página

O bashy são duas coisas ao mesmo tempo: um substituto direto do Bash 5.3 (seus scripts funcionam exatamente como antes) e um shell agêntico — um espaço de usuário puramente em Go e um conjunto de verbos nativos para agentes que executam em processo, de forma idêntica no Linux, macOS e Windows. As extensões são aditivas: elas nunca alteram o que um bash válido significa.

bashy é tudo que você precisa

Use o bashy primeiro e expanda-o em vez de contorná-lo:

• Está faltando? Se nenhum comando bashy fizer o trabalho, registre um: bashy commands add NOME --set script=CORPO (ou exec.0=PROGRAMA, download.url=...); ele será listado, documentado e despachado como um comando nativo (bashy commands schema lista todos os campos).
• Não se encaixa? Se um existe mas não se encaixa, molde-o em vez de escrever algo único: bashy shape wish … → verificar → visualizar → aprovar (desfazer fica disponível).
• Construindo ou moldando? Componha pequenos verbos --json em um script de habilidade Bash#, forneça a cada superfície voltada ao usuário um gancho de moldagem, inicie novos ajudantes como exemplos e promova-os para opcionais, depois para o núcleo: bashy kb show extend-bashy-small-verbs-bash-skill-scripts-shaping-hooks-and-th.

bashy é a única habilidade que este binário instala — e não precisa ser mais que uma, porque cada comando bashy também é uma habilidade: bashy <cmd> --help renderiza o mesmo documento de habilidade+MCP que uma pasta de habilidade dedicada teria (frontmatter, prosa e uma definição de ferramenta json mcp em um único arquivo), não apenas uma string de uso.

• Liste o que está acessível aqui: bashy skill list (verificado, com portas de ambiente) ou bashy commands --agentic (a superfície agêntica completa).
• Carregue uma: bashy <cmd> --help — sessões detetadas por agente recebem a forma habilidade+MCP automaticamente; force de um lado ou de outro com --format classic (uso simples) ou --format mcp (apenas a definição da ferramenta).
• Um comando cuja ajuda precisa de mais que sua própria string de uso carrega um documento companheiro em bashy/commands/<cmd>.md (opcionalmente bashy/reference/<cmd>.md) que --help --format skill incorpora antes das seções geradas — conductor, steward, sprint, inbox, supervisor, knowledge-transfer e force-agent-shell já funcionam assim; bashy skill show conductor (e amigos) ainda leem o mesmo documento diretamente.

Para mudanças estrangeiras, contenção de recursos, congelamentos e trabalho com checkout compartilhado, siga bashy skill show collaborate.

Primeiro pulo (faça isso uma vez por sessão)

bashy inspect context --json

Uma única chamada substitui a dança de sondagem usual (uname/hostname/id/env/ which ...): sistema + identidade, caminhos de ferramentas resolvidos, ambiente seguro (segredos redigidos por nome), flags de modo agente, habilidades aplicáveis neste host e uma lista de comandos recomendados. Use o bashy_path relatado para chamadas futuras.

Segundo pulo: estado durável (kb · inbox · todo)

Tudo o resto nesta página ajuda você a fazer o trabalho. Estes três são o estado no qual o trabalho acontece — o que é conhecido, o que precisa de atenção e o que deve ser feito — e são as únicas coisas que sobrevivem à sua sessão. Leia-os antes de começar; escreva para eles antes de terminar. Um agente que os ignora começa do nada toda vez e não deixa nada para trás.

kb — o que é CONHECIDO. Páginas destiladas que agentes antes de você escreveram para quem vier depois: a pegadinha que custou a alguém uma máquina perdida, a build que só falha no Windows, a flag que silenciosamente não faz nada. O verbo único que pode dizer que a tarefa já está resolvida — ou já conhecida como uma armadilha.

bashy kb context --for "<tarefa>" --rings repo,host --forms note,page --budget 700 --json
bashy kb search "<a tarefa, nas suas próprias palavras>"   # recuperar de um anel
bashy kb show <slug>                              # ler um registro completo
bashy kb observe --ring agent --episode E --kind tool-result --ref REF
bashy kb validate <slug> --ring RING --from-gate EVENT_ID
bashy kb note add --candidate --ring agent --episode E --title "..." --body "..."
bashy kb retro                                    # reconciliar após o trabalho

Estes são os cinco estágios de arnês: context monta, search/show recuperam, observe registra um evento, validate --from-gate verifica e note add --candidate persiste. Uma escrita seleciona exatamente um armazenamento com --ring repo|host|agent; contexto lê um conjunto nomeado com --rings e filtra formas de registro com --forms note,page,relation,code (kb search usa --form no singular). kb backlinks resolve links de entrada, kb doctor apenas sinaliza problemas e nunca os corrige, e kb transfer --from memex é o caminho de importação legado suportado.

Agentes nunca devem editar manualmente os pages/*.md ou graph.jsonl de um armazenamento kb. Use os verbos bashy kb: eles impõem atribuição, status de candidato, verificações de duplicatas, redação, propriedade do anel, ids de relacionamento e histórico somente anexo.

Um erro é honesto e barato: a busca informa quais das suas palavras o corpus não carrega e quais carrega, para que você possa distinguir "ninguém sabe disso" de "perguntei com as palavras erradas", e reformular em vez de adivinhar. Se nada relevante existir e a tarefa ensinar algo durável, contribua — bashy kb add --type gotcha --title "..." --description "o que + QUANDO isto se aplica" — estratégia destilada, não uma transcrição, com falhas colocadas como guardrails.

inbox — o que precisa da sua ATENÇÃO. Mensagens para você: bashy inbox (espiar por padrão; buscar com --from/--search; responder com bashy mb send).

Uma visão de leitura única sobre MB, quadros Stand, notificações de Bus e mensagens de função autorizada. MB continua sendo a superfície pública de envio/histórico; inbox evita sondagem transporte por transporte.

bashy inbox                  # ler cada fonte de entrada
bashy skill show inbox
bashy mb post "<mensagem>"    # para todos
bashy mb send <agente> "..."    # para um agente, ou um seletor

Para status que deve permanecer descoberto fora do histórico do terminal, use a caixa de correio principal explícita. Listas e buscas não consomem; apenas ack retira um item da visão pendente.

bashy inbox list --topic harness --search timeout
bashy inbox human list --topic posix-cert --project dhnt
bashy inbox human send --topic posix-cert --project dhnt --status blocked \
  --ref docs/status.md "Profile D precisa de revisão"

As caixas de correio de agente e humano compartilham os mesmos filtros e esquema JSON. read mantém um item pendente, ack é explícito, preserve o reabre e --all inclui histórico reconhecido. Mantenha o status abaixo de 1024 bytes UTF-8 e vincule detalhes por um caminho, commit, issue, sala ou referência de artefato estável e compartilhado.

Nunca consuma mensagens de quadro silenciosamente. Depois que uma leitura retornar postagens, mostre a mensagem completa no console da sessão visível ao usuário quando for curta; caso contrário, mostre o remetente/tópico, um resumo conciso e a ação que requer. A saída da ferramenta pode ser recolhida, portanto o recibo interno sozinho não é coordenação visível ao operador.

todo — o que deve ser FEITO. A lista de trabalho, escopada automaticamente da mesma forma que kb: deste repositório quando você está em um, do host caso contrário.

bashy todo list              # o que está aberto aqui, prioridade primeiro
bashy todo add "<título>"     # registrar trabalho para que sobreviva a esta sessão
bashy sprint claim last STORY_ID # reivindicar trabalho de sprint selecionado
bashy sprint submit last STORY_ID -m "evidência de entrega"

Todos os sprints usam o mesmo ciclo de vida e regras de aceitação; nenhum número de sprint é reservado para manutenção. Selecione um sprint explicitamente ou use last para o cartão mais recentemente criado. A omissão da seleção de sprint usa esse mesmo último cartão; não cria um sprint. Use --no-sprint para um todo de repositório independente. Todos pessoais permanecem independentes por padrão. Leia bashy sprint --help.

Crie um sprint com bashy sprint add "Título": ele aloca e retorna automaticamente o próximo número disponível. Nenhum número ou seletor next é necessário.

As histórias de sprint são fechadas por seu gerente usando sprint accept após verificação; todo done genérico não pode fechar uma história de sprint.

Execute comandos como um agente, não como um humano

• Visualize antes de modificar: bashy --dry-run SCRIPT (manifesto legível por agente com BASHY_AGENTIC=1).
• Verifique um script: bashy check --agent --script SCRIPT.
• Execute com um envelope de resultado capturado e estruturado: bashy run --check --capture -- SCRIPT.
• Consulta de capacidade de um comando (flags, recursos — pule tentativa e erro): bashy commands COMMAND --features.
• Em falhas, leia dicas do stderr: o conselheiro espaço-tempo explica falhas determinadas pelo ambiente (cwd errado, ferramenta faltando, disco cheio) para que você não repita um comando condenado.

Antes de executar algo que você não escreveu, pergunte o que executá-lo significa. bashy inspect actions [--json] [--kind command|script|agent|skill] lista cada ação que este bashy pode executar como uma linha de faceta — kind name identity contract latitude authority effects_declared executor — através de quatro famílias: um comando é exato e determinístico (o shell executa o que foi digitado; os efeitos vêm de seu registro atlas), uma ligação de agente é julgadora/agêntica por definição (executor agentlaunch:<tool>, então seu custo e efeitos são abertos), uma habilidade é ligada pelo contrato mais forte que carrega (face dhnt com efeitos declarados, metadata-checks, ou none; um passo de julgador torna toda a execução agêntica), e script é uma família que nada preenche ainda (relatado como 0, nunca omitido). bashy define NOME imprime a mesma faceta para um nome (linha runs:; objeto action aninhado sob --json), e bashy inspect context --json carrega as contagens como actions: {command, script, agent, skill}. Prefira uma linha exata/determinística quando uma satisfizer a tarefa; recorra a uma linha julgadora/agêntica apenas quando a tarefa precisar da latitude.

Navegue no código sem a dança do grep

• bashy graph impact SYMBOL — qual código está acoplado a um símbolo.
• bashy ast symbols PATH / bashy ast search PADRÃO / bashy ast refs SYMBOL / bashy ast map — baseado em treesitter, sem modelo.
• Memória compartilhada do repositório (uma wiki agêntica onde as descobertas de outros agentes se acumulam): bashy graph recall QUERY para ler; bashy graph note / bashy graph observe para contribuir; bashy graph pitfalls antes de mudanças arriscadas.

Habilidades: procedimentos verificados, com portas para este host

• bashy skill list — apenas habilidades aplicáveis às coordenadas DESTE host (com portas de ambiente); bashy skill show NOME para ler uma.
• bashy skill run NOME — executar uma habilidade verificável por máquina; o contrato de sucesso é verificado e cada execução deixa uma atestação re-verificável. Saída 0 sse o contrato for mantido.
• bashy skill run NOME --adapt --repair-agent "<seu CLI headless>" — auto-reparar uma habilidade falha; correções verificadas são aprendidas uma vez por host e reutilizadas por todos os agentes.
• Contribua de volta: crie uma pasta de habilidade, depois bashy skill learn DIR (a admissão requer que o contrato realmente seja mantido aqui) e bashy skill promote NOME (pacote revisado por humanos — nunca auto-publicado).

Padrões: comandos e páginas kb do pino de origem

Comandos padrão Bash# e páginas kb são fornecidos na fonte do Bashy, não em seu binário. Um primeiro bashy self install (o que os instaladores executam) os configura; para fazer manualmente: bashy src fetch bashy && bashy --bashsharp "${BASHY_HOME:-$HOME/.bashy}/src/bashy/examples/defaults/bashy-defaults.bsh" apply (status para verificar, merge --upgrade após uma atualização: adiciona novos padrões e lista suas páginas que sombreiam páginas alteradas para você reconciliar). As páginas kb padrão são então lidas automaticamente por bashy kb search e bashy recall; sua própria página com o mesmo slug vence.

Edite o catálogo através de verbos, nunca manualmente

Nunca edite arquivos em ~/.config/bashy/ (ou qualquer BASHY_*_DIR) diretamente: entradas embutidas são imutáveis e toda escrita é cópia-ao-escrever no anel local, que apenas os verbos fazem. bashy <noun> schema lista os caminhos pontilhados que um tool/model/agent aceita; bashy <noun> set NOME --set caminho=valor (--unset path) edita um, bashy <noun> show NOME --field caminho o lê de volta. Habilidades: bashy skill add NOME --description "..." fornece um, bashy skill set NOME / bashy skill rm NOME edita e remove, bashy skill show NOME --yaml imprime seu registro (skill add FILE.yaml|- o reimporta).

Frota e espaço de trabalho (quando a tarefa excede uma sessão)

• bashy weave … — espaços de trabalho isolados por issue para execuções de agente em paralelo; bashy sprint … — planejamento/continuidade; bashy dag TASKS.md — DAGs de tarefas definidas em markdown. Leia a habilidade conductor (bashy skill show conductor) antes de orquestrar uma frota.

Regras práticas

1. bashy inspect context --json primeiro; confie nele em vez de suas próprias sondagens.
2. Abra com kb search + inbox + todo list; feche com kb retro. Se você se lembrar de três verbos desta página, lembre-se destes. Todo o resto aqui ...

[truncado para tradução]