convez.ai
AgenteAutomaçãoIntermediário
yanqr213

AI Agent Context Kit

yanqr213/ai-agent-context-kit

Empacota repositórios em contexto estruturado para IA de coding

Ver no GitHub
InicialPluginScore · de 0 a 100

CLI Python offline que transforma repositórios em pacotes de contexto auditáveis e reproduzíveis para ferramentas de IA (Codex, Claude Code, Cursor). Gera bundles Markdown, manifests JSON e prompts de handoff pré-formatados, eliminando a necessidade de reexplicar projetos a cada sessão de codificação assistida.

Instalação

$npx convez-ai yanqr213/ai-agent-context-kit

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Preparar sessões de AI coding com contexto auditável e reproduzível
  • Compartilhar especificações de projeto em equipes para colaboração com IA
  • Gerar bundles de contexto com diferentes orçamentos de tokens para diferentes modelos
  • Validar conteúdo de contexto em CI (detectar arquivos grandes, binários, potenciais secrets)

Veredito

Ferramenta robusta e pragmática para quem trabalha regularmente com AI coding. Zero dependências de runtime, offline-first, com boas garantias de segurança (detecção de secrets, auditoria de exclusões). Ideal para times que querem reproduzibilidade e controle sobre contexto enviado a modelos de IA.

README

A tradução para o português deste README ainda está na fila.

ai-agent-context-kit

ai-agent-context-kit 是一个零运行时依赖的 Python CLI,用来把一个代码仓库整理成可控大小、可审计、可复现的 AI 编程上下文包。

它面向使用 Codex、Claude Code、ChatGPT、Cursor 等 AI 编程工具的开发者:当你需要让模型快速理解一个仓库时,可以先生成一份 Markdown bundle、JSON manifest 和可复制的 agent handoff prompt,而不是在每个会话里反复解释项目背景。

适用场景

  • 新开 AI 编程会话前,快速提供仓库结构、关键源码和约束。
  • 在团队中共享“这次要给 AI 的上下文”,让输入可审计、可复现。
  • 给 Codex 或 Claude Code 准备不同预算的上下文包。
  • 在 CI 中检查上下文包是否会包含大文件、二进制文件或潜在密钥。
  • 为 issue、PR、外包协作或代码审查生成最小可用项目背景。

功能

  • 扫描仓库文件并生成 Markdown 上下文包。
  • 生成 JSON manifest,记录 included/excluded 文件、预算、hash、警告和筛选条件。
  • 生成 *.handoff.md,把上下文包转换成下一轮 agent 可直接使用的启动说明和复制型 prompt。
  • 遵守 .gitignore 风格忽略规则,并内置常见目录和二进制类型排除。
  • 支持按扩展名、路径 glob、最大文件大小筛选。
  • 支持字符预算和简易 token 预算估算。
  • 默认排除大文件、二进制文件和疑似密钥文件。
  • 提供 generic、codex、claude、claude-code 输出 profile。
  • 仅使用 Python 标准库,适合离线和 CI 环境。

安装

需要 Python 3.9 或更新版本。

开发模式安装:

python -m pip install -e .

也可以不安装,直接从源码运行:

python -m ai_agent_context_kit.cli --help

安装后可使用:

aictx --help

快速开始

在仓库根目录运行:

aictx . --profile codex

默认会生成:

.aictx/context-bundle.md
.aictx/context-bundle.manifest.json
.aictx/context-bundle.handoff.md

给 Claude Code 生成较小上下文:

aictx . --profile claude-code --token-budget 40000 --include-ext py,md,toml,json

只收集源码和文档,排除测试快照:

aictx . \
  --include-ext py,md,yml,toml \
  --exclude-path "tests/fixtures/*" \
  --exclude-path "*.snapshot"

在安全检查中发现疑似密钥时让 CI 失败:

aictx . --fail-on-secret

命令参数

aictx [ROOT]
  -o, --output-dir DIR        输出目录,默认 .aictx
  --name NAME                 输出文件 basename,默认 context-bundle
  --profile PROFILE           generic / codex / claude / claude-code
  --include-ext EXT           只包含扩展名,可重复或逗号分隔
  --exclude-ext EXT           排除扩展名,可重复或逗号分隔
  --include-path GLOB         只包含匹配路径,可重复
  --exclude-path GLOB         额外排除路径,可重复
  --token-budget N            估算 token 预算,默认 120000
  --char-budget N             字符预算
  --max-file-bytes N          单文件大小上限,默认 524288
  --no-gitignore              不读取仓库 .gitignore
  --include-secret-files      包含疑似密钥文件,但写出警告
  --fail-on-secret            检测到疑似密钥时返回非零状态
  --no-handoff                不生成 agent handoff Markdown

输出格式

Markdown bundle 包含:

  • 仓库、生成时间、profile、预算摘要。
  • Agent instructions,帮助 Codex/Claude Code 理解该 bundle 的使用方式。
  • File index,列出路径、字节数、字符数、估算 token 和 SHA-256 前缀。
  • Included files,每个文件以 fenced code block 形式展示。
  • Warnings 和 Excluded files,用于审计被排除内容。

JSON manifest 包含:

{
  "schema_version": "1.0",
  "tool": "ai-agent-context-kit",
  "profile": "codex",
  "repository": { "name": "repo", "root": "/path/to/repo" },
  "budgets": {
    "token_budget": 120000,
    "estimated_tokens": 1234,
    "truncated_by_budget": false
  },
  "included_files": [
    {
      "path": "src/app.py",
      "bytes": 1200,
      "sha256": "...",
      "estimated_tokens": 300
    }
  ],
  "excluded_files": [
    { "path": ".env", "reason": "potential secret (...)" }
  ],
  "warnings": []
}

Agent handoff 包含:

  • bundle 和 manifest 的文件名。
  • profile、预算、included/excluded 数量和是否因预算截断。
  • 最大的 included files,便于模型先理解上下文重心。
  • warnings 和 notable exclusions,提醒 agent 不要对被排除文件做假设。
  • 一段可复制到 Codex/Claude Code/Cursor 的启动 prompt。

隐私与安全边界

  • 工具不会读取或请求 GitHub token,也不会推送 GitHub。
  • 工具不会访问外部网络。
  • 疑似密钥检测是启发式规则,不是完整安全扫描器。
  • 默认会排除疑似密钥文件;如果使用 --include-secret-files,请在共享前人工审查输出。
  • JSON manifest 中不会打印检测到的密钥值,只记录原因摘要。
  • 生成的 Markdown bundle 可能包含源码和业务逻辑,请按内部安全规则保存和共享。

CI 用法

示例 GitHub Actions 已包含在本仓库 .github/workflows/ci.yml:

- name: Build context bundle
  run: |
    python -m ai_agent_context_kit.cli . --fail-on-secret --token-budget 60000
    test -f .aictx/context-bundle.handoff.md

这可以确保上下文包能够在干净环境中生成,并在潜在密钥被检测到时失败。

开发与测试

运行测试:

python -m unittest discover -s tests -v

运行 CLI:

python -m ai_agent_context_kit.cli . --profile codex --output-dir .aictx

English

ai-agent-context-kit is a zero-runtime-dependency Python CLI for building auditable and reproducible prompt/context bundles from a repository.

It helps developers using Codex, Claude Code, ChatGPT, Cursor, and similar AI coding tools provide the right repository context without repeatedly explaining the project. The tool scans text files, respects .gitignore-style rules, applies extension/path filters, estimates character and token budgets, excludes large/binary/secret-like files by default, and writes a Markdown bundle, a JSON manifest, and an agent handoff prompt.

Basic usage:

python -m pip install -e .
aictx . --profile codex --token-budget 60000

Outputs:

.aictx/context-bundle.md
.aictx/context-bundle.manifest.json
.aictx/context-bundle.handoff.md

The handoff file summarizes bundle paths, budget state, largest included files, warnings, notable exclusions, and a copyable prompt for the next Codex/Claude Code/Cursor session. Use --no-handoff when a CI job only needs the bundle and manifest.

Security model:

  • No network access is required.
  • The tool does not read, request, print, or push GitHub tokens.
  • Secret detection is heuristic and should not replace a dedicated security scanner.
  • Secret-like files are excluded by default and reported through warnings.

CI example:

python -m unittest discover -s tests -v
python -m ai_agent_context_kit.cli . --fail-on-secret --token-budget 60000

License

MIT. See LICENSE.

Ver o original no GitHub

Bom para

Relacionados