example-git/ai-cli-toolkit

# AI Cli 工具包 AI Cli Toolkit 是一个封装了多种 AI 编码 CLI 的统一包装器： - Claude Code - OpenAI Codex CLI - GitHub Copilot CLI - Gemini CLI 它通过一个受管的 mitmproxy 层来运行每个工具，以一致地注入指令，处理每个工具的请求格式，并将会话工具集中在一处。 ## 早期版本声明 这是一个早期的 `0.1.0` 版本。功能仍在演进中，行为可能会发生变化，部分工作流可能不完整或不稳定。 使用本项目风险自负。您需对使用方式负责，包括遵守平台政策、服务条款及适用法律。维护者不对误用、数据丢失、账户问题、服务中断或使用本工具导致的其他后果承担责任。 ## 当前状态 已实现并通过冒烟测试： - 多工具分发和别名式 argv 路由 - 每个工具的指令注入插件 - 动态每次会话的代理端口 - 跨多个 Agent 的会话提取 - 启动时最近上下文注入（基于 cwd 作用域，跨 Agent） - 交互式菜单、更新命令、补全、安装程序、状态栏 ## 主要功能 - 单一入口点：`ai-cli [DIR] [args...]` - 可选别名功能，使 `claude`、`codex`、`copilot`、`gemini` 通过包装器路由 - 分层指令组合： - Canary - Base - Per-tool - Per-project - User custom - 与 Agent 无关的会话检查： - `ai-cli session --list` - `ai-cli session --agent claude --tail 20` - `ai-cli session --all --grep "keyword"` - 启动连续性上下文： - 在工具启动时，从会话日志中构建匹配当前 cwd 的最近上下文 - 上下文块包含在启动提示文本中，并在初始化时打印 - 每个工具的更新器： - `ai-cli update --list` - `ai-cli update codex` - `ai-cli update --all` ## 系统要求 - Python `>=3.8` - `mitmproxy`（如果缺失，首次运行时自动安装） - 已安装被封装的工具二进制文件（`claude`、`codex`、`copilot`、`gemini`） ## 安装 ### 推荐方式 ``` bash install.sh ``` 实用参数： - `--reinstall` - `--alias-all` - `--alias `（可重复使用） - `--no-alias` - `--auto-install-deps`（允许安装程序安装所需的系统依赖，如 `tmux`） - `--yes`（对交互式提示默认为是） - `--non-interactive` ### 手动开发安装 ``` python3 -m pip install --user -e . ``` ## CLI 使用 ``` ai-cli [DIR] [args...] ai-cli menu ai-cli status ai-cli system [tool] ai-cli system prompt [model] ai-cli prompt-edit [tool] ai-cli history [options] ai-cli session [options] # alias for history ai-cli traffic [options] ai-cli cleanup [options] ai-cli update [tool|--all] ai-cli completions generate [--shell bash|zsh|all] ``` 目录启动行为： - 如果 `` 后的第一个参数是一个现有目录，ai-cli 将在该目录中启动被封装的工具。 - 这适用于： - `ai-cli claude /path/to/project` - `claude /path/to/project`（当 `claude` 被别名为 ai-cli 包装器时） `ai-cli menu` 在交互式 TTY 中使用 curses，否则回退到非交互式状态输出。 工具： - `claude` - `codex` - `copilot` - `gemini` Codex 用户注意： - 在封装的 `ai-cli codex` 会话中，`Ctrl+G` 外部编辑器行为默认启用。 - 要禁用 Codex 外部编辑器行为，请设置： `AI_CLI_CODEX_DISABLE_EXTERNAL_EDITOR=1` ## 配置 配置文件： - `~/.ai-cli/config.json` 关键字段： - 全局 `instructions_file` 和 `canary_rule` - Proxy 主机和 CA 路径 - 保留策略： - `retention.logs_days` - `retention.traffic_days` - 隐私策略： - `privacy.redact_traffic_bodies` - 每个工具的覆盖设置： - `enabled` - `binary` - `instructions_file` - `canary_rule` - `passthrough` - `debug_requests` - `developer_instructions_mode`（Codex：`overwrite`、`append`、`prepend`；默认为 `overwrite`） - 别名状态跟踪 Codex 提示处理（`developer_instructions_mode=overwrite`）构建分段的开发者消息： - 来自全局用户指令文件（`instructions_file`）的 `` - 来自 codex 特定指令的 `` - 在标记的循环部分中保留的循环运行时块（权限/应用/协作模式） 在 `ai-mux` 会话中： - `F7` 在编辑器中打开全局提示文件（使用 `VISUAL`/`EDITOR`，回退到 `nano`/`vi`/`vim`） - `F8` 打开当前工具的提示文件 - Codex 注入会在每次请求时读取这些文件，因此文件编辑会应用于同一对话中的后续轮次 ## 指令文件 指令来源： 1. Canary 规则 2. 基础模板（`templates/base_instructions.txt` 或 `~/.ai-cli/base_instructions.txt`） 3. 每个工具（`~/.ai-cli/instructions/.txt`） 4. 项目（`./.ai-cli/project_instructions.txt`） 5. 用户（`~/.ai-cli/system_instructions.txt` 或配置的文件） 运行时行为： - `compose_instructions()` 构建用于包装器日志/哈希可见性的 5 层文本。 - 插件使用全局指令文件 + canary 规则进行注入。 - 对于 Codex，当 `developer_instructions_mode=overwrite` 时，`~/.ai-cli/instructions/codex.txt` 也用作 `` 部分。 - 启动时的最近上下文会附加到 canary 规则（除非被禁用）。 快速编辑： ``` ai-cli system ai-cli system codex ai-cli prompt-edit global ai-cli prompt-edit tool codex ``` ## 保留与隐私 - 包装器启动时会运行尽力而为的内务处理： - 使用 `retention.logs_days` 从 `~/.ai-cli/logs` 清理旧的包装器日志 - 使用 `retention.traffic_days` 从 `~/.ai-cli/traffic.db` 清理旧记录 - 默认情况下，流量主体捕获会对常见的秘密/token 模式进行脱敏（`privacy.redact_traffic_bodies = true`）。 ## 会话工具 列出所有发现的会话： ``` ai-cli session --list ``` 显示合并的时间线： ``` ai-cli session --all --tail 50 ``` 按 Agent 过滤： ``` ai-cli session --agent codex --tail 30 ``` 按文本过滤： ``` ai-cli session --all --grep "statusline" ``` ## Shell 补全 `install.sh` 将补全源文件从此仓库复制到 shell 补全目录： - Zsh 源：`completions/_ai-cli` -> `~/.oh-my-zsh/custom/completions/_ai-cli`（或 `~/.zsh/completions/_ai-cli`） - Bash 源：`completions/ai-cli.bash` -> `~/.local/share/bash-completion/completions/ai-cli` 您也可以直接生成脚本： ``` ai-cli completions generate --shell all ``` ## 状态栏 一个多工具感知的状态栏命令被安装到： - `~/.claude/statusline-command.sh` 安装程序会更新 `~/.claude/settings.json` 以将 `statusLine` 指向该脚本。 ## 开发 基础检查： ``` python3 -m compileall ai_cli python3 -m pip install -e '.[dev]' pytest pre-commit run --all-files python3 -m ai_cli --help python3 -m ai_cli session --help python3 -m ai_cli update --help bash -n install.sh ``` CI 配置在 `.github/workflows/ci.yml` 中，当前运行 `pre-commit` 和 `pytest`。 ## 文档 其他用户文档位于 `docs/` 下： - `docs/index.md` - `docs/getting-started.md` - `docs/cli-reference.md` - `docs/config-reference.md` - `docs/operations-runbook.md` - `docs/privacy-data-handling.md` ## 故障排除 - 代理已启动但工具无法访问 API： - 确认 CA 存在于 `~/.mitmproxy/mitmproxy-ca-cert.pem` - 检查 `~/.ai-cli/logs/*.mitmdump.log` 中的 TLS/连接错误 - Codex 注入/流量捕获停止： - 确保 `~/.codex/config.toml` 包含 `[network] allow_upstream_proxy = true` 且 `mitm = false` - 没有出现流量记录： - 验证工具是通过 `ai-cli` 启动的 - 检查保留配置是否过于激进（`retention.traffic_days`） - 安装程序因缺少 `tmux` 而失败： - 使用 `--auto-install-deps` 重新运行（或先手动安装 `tmux`） ## 项目结构 - `ai_cli/` 核心包 - `ai_cli/tools/` 工具规范和注册表 - `ai_cli/addons/` mitmproxy 注入插件 - `templates/` 基础指令模板 - `completions/` shell 补全脚本 - `statusline/` 状态栏命令脚本 - `reference/` 保留的源/参考材料 ## README 维护 本 README 旨在作为一份活的操作指南。 当行为发生变化时，请在同一变更集中更新此文件，涉及： - CLI 命令或参数 - 安装程序行为 - 配置 schema/默认值 - 会话发现/解析行为 - 提示/指令组合行为

标签：AI编程助手, AI网关, Claude, CLI封装器, Cutter, CVE检测, DLL 劫持, DLL注入, DNS 反向解析, Gemini, GitHub Copilot, IP 地址批量处理, Mitmproxy, OpenAI Codex, Python, SOC Prime, 上下文管理, 人工智能, 代理管理, 会话管理, 大语言模型, 威胁情报, 工作流自动化, 开发工具, 开发者工具, 无后门, 流量审计, 用户模式Hook绕过, 统一接口, 逆向代理, 逆向工具