FoxCode - AI 编码代理工具

基于 pydantic-ai 框架的终端交互式 AI 编程助手，支持文件操作、命令执行、网络搜索等功能。

功能

• 文件操作: 读取、创建、编辑（精确替换/覆盖）、追加、删除、重命名、列出文件
• 命令执行: 运行 shell 命令、执行脚本文件（支持 Python/JS/TS/Go/Rust 等）
• 网络搜索: 通过 Bing 搜索获取信息（无需 API Key）
• 撤销恢复: 支持操作撤销，避免误操作
• 对话记忆: 保持多轮对话上下文，长对话自动智能压缩保留关键信息
• 结构化输出: AI 返回清晰的 ActionPlan（解释、修改文件、代码片段），支持 Thinking 过程展示
• 代码库索引: 自动索引项目符号（类/函数/方法），支持快速定位
• Web 预览: 启动本地 HTTP 服务器预览前端项目
• AI 代码审查: 自动分析变更并给出安全、风格、逻辑审查建议
• 项目健康检查: 检测依赖、测试、文档、配置完整性
• 文件引用: 在对话中用 @文件名 引用文件，自动注入内容
• 自动 Git 提示: 进入终端时自动提示未提交的变更
• LSP 桥接: 基于 jedi 提供 Python 代码的跳转定义、查找引用、类型信息（需 jedi）
• 图片理解: 支持 Markdown 图片语法 ![alt](path) 上传图片给 AI 分析
• VS Code 扩展: 一键在 VS Code 中启动 foxcode 终端
• 权限确认系统: allow / ask / deny 规则、高危行为拦截、交互式审批、只读命令自动放行
• 计划模式: 切换后隐藏所有写工具，AI 只读探索并先给出方案
• Subagents: 通过 .foxcode/agents/ 定义只读子代理，用 task 工具调用
• Skills: 通过 .foxcode/skills/ 定义技能，按需注入提示
• MCP 支持: 通过 .foxcode/mcp.json 接入任意 MCP 服务器（stdio / HTTP）
• 项目记忆与用户规则: .foxcode/Memory.md 由 AI 维护重要项目知识/踩坑点（update_memory 工具）；.foxcode/Rules.md 为用户规则（AI 只读，所有文件写工具强制拦截）
• Headless 模式: 一条命令或管道输入即可无人值守运行，支持 JSON 输出

快速开始

1. 安装依赖

pip install -r requirements.txt

或使用 pip 安装包本身：

pip install -e .

2. 配置 API

复制 .env.example 为 .env，填入你的 API 信息：

cp .env.example .env

编辑 .env：

OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxxxxx

支持任何 OpenAI 兼容 API（如 DeepSeek、Claude、Kimi 等）。

3. 启动

python main.py

或安装后：

foxcode

Headless 模式（无人值守 / CI）

# 直接给提示
foxcode -p "列出当前目录所有文件"

# 指定工作目录与模型，JSON 输出
foxcode -p "重构 main.py" --cwd /path/to/project --model gpt-4o --output-format json

# 管道输入
echo "总结 README.md" | foxcode

# 跳过所有权限确认（仅限可信的 CI 环境）
foxcode -p "安装依赖并运行测试" --dangerously-skip-permissions

说明：headless 模式下需要确认的操作会直接拒绝（除非显式配置了 allow 规则或使用 --dangerously-skip-permissions）。

权限系统

权限模式（.foxcode/settings.json 中 permissions.defaultMode）

模式	说明
default	读操作放行，写/执行操作每次询问
acceptEdits	自动接受文件编辑，命令仍询问
plan	拒绝所有写/执行操作
bypass	放行一切（谨慎使用）

规则配置示例

{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(git status)", "Read(*)", "Edit(*)", "Bash(ls .*)"],
    "ask": ["Bash(npm install)", "WebFetch(*)"],
    "deny": ["Bash(rm -rf /)"]
  }
}

• 工具名支持通配符（*），括号内为正则匹配目标参数
• 内置高危操作（rm -rf /、git push --force、磁盘格式化等）无条件拦截
• 只读 shell 命令（ls、cat、git status、git diff、pip list 等）默认自动放行
• 交互式审批支持 y 允许 / n 拒绝 / a 本次会话总是允许

计划模式

交互中输入 /plan 切换。开启后：

• 所有写/执行工具对 AI 不可见（run_shell、write_file、git 提交等）
• AI 只能读取、搜索、分析，最终返回方案
• AI 也可自行调用 enter_plan_mode / exit_plan_mode 工具完成"先分析后动手"

Goal 模式（目标验收循环）

交互中输入 /goal <目标>（或 /goal 后输入目标）启动。流程：

1. 主 AI 执行目标（可访问完整上下文与全部工具）
2. 完成后启动一个独立上下文、只读的验收 AI，亲自检查工作区真实状态
3. 验收通过 → 结束；未通过 → 将验收反馈交回主 AI 继续工作
4. 循环直到确认完成（默认最多 8 轮）

为抵抗上下文自动压缩导致的进度丢失，Goal 模式要求 AI 持续维护三个持久化文件：

• goal.md - 目标定义、验收标准、完成状态
• plan.md - 实施计划、当前阶段方案、关键决策
• todo.md - 任务清单（- [ ] 未完成 / - [x] 已完成）

每轮开始时 AI 先读取这些文件恢复进度，每完成重要步骤即同步更新。若工作目录是 git 仓库，每轮结束后会自动将这 3 个文件 git add + git commit（提交信息 goal: 第 N 轮进度），形成可回滚的进度检查点，不干扰其他工作区文件。

Skills（技能）

.foxcode/skills/<名称>/SKILL.md 格式：

---
name: code-review
description: 对代码做安全与性能审查
---

# 代码审查流程

1. 先读取变更文件
2. 检查安全与性能问题
3. 输出修复建议

• /skills 列出所有技能；/skill <名称> 把内容注入下一条提示
• AI 也可通过 list_skills / use_skill 工具按需获取

Subagents（子代理）

.foxcode/agents/<名称>.md 格式（frontmatter 可省略）：

---
name: reviewer
description: 代码审查者
model: gpt-4o-mini   # 可选，覆盖默认模型
tools: [read_file]   # 可选，限制可用工具
---

你负责审查代码质量，只读探索后用中文总结。

• 默认只读（写工具自动过滤），适合隔离上下文的探索任务
• AI 用 task(prompt, agent="reviewer") 调用；/agents 列出所有定义

MCP 支持

.foxcode/mcp.json（或项目根 .mcp.json）格式：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "filesystem": {
      "url": "https://example.com/mcp"
    }
  }
}

• 支持 stdio（command/args/env）和 http（url/headers）两种传输
• 支持 ${ENV_VAR} 环境变量展开（可带默认值 ${VAR:-default}）
• 工具以 服务器名__工具名 暴露给 AI，并受权限系统门控
• /mcp 列出已配置的服务器；配置错误会在启动时提示

项目配置目录 .foxcode/

.foxcode/
├── instructions.md    # 项目指南（注入系统提示）
├── settings.json      # 权限与运行参数
├── commands/          # 自定义 /命令（.md 文件，文件名即命令名）
├── skills/            # Skills（每技能一个目录）
├── agents/            # 子代理定义（.md 文件）
├── mcp.json           # MCP 服务器配置
└── sessions/          # 保存的会话

使用方法

在交互式终端中输入你的编程需求，AI 会自动调用工具完成。

CLI 命令

命令	说明
/help	显示帮助
/goal <目标>	设定目标，AI 完成后由独立上下文验收 AI 确认，未完成则继续直到达成
/plan	切换计划模式（只读探索，先出方案）
/permissions	查看当前权限模式与规则
/mcp	列出已配置的 MCP 服务器
/skills	列出可用 Skills
/skill <名称>	将指定 Skill 内容注入下一条提示
/agents	列出可用子代理
/term	切换终端模式 (Ctrl+X 切换)
/commit [信息]	暂存所有变更并用 AI 生成提交信息后提交
/session list	列出所有已保存的会话
/session save [名称]	保存当前会话
/session load <名称>	加载指定会话
/session del <名称>	删除指定会话
/export [文件名]	导出当前会话为 Markdown
/undo [n]	撤销最近 n 步操作（默认 1 步）
/history	显示操作历史
/usage	显示本次会话的 API 用量和费用统计
/clear	清屏
/exit 或 /quit	退出（自动保存会话）

AI 可用工具

AI 在推理过程中会自动调用以下工具：

• read_file - 读取文件内容
• read_file_range - 读取指定行范围
• create_file - 创建新文件
• write_file - 查找替换（要求唯一匹配）
• write_file_complete - 覆盖写入整个文件
• append_file - 追加内容到文件末尾
• delete_file - 删除文件
• rename_file - 重命名文件
• copy_file - 复制文件或目录
• list_files - 列出工作区文件
• tree - 以树形结构展示目录（支持深度限制和过滤）
• run_shell - 执行 shell 命令
• run_file - 运行脚本文件
• run_tests - 自动检测并运行测试（pytest/npm/go/cargo 等）
• format_code - 格式化代码（black/prettier/gofmt 等）
• install_deps - 自动检测并安装依赖（pip/npm/cargo/go 等）
• web_search - 搜索网络
• fetch_url - 抓取网页内容
• search_in_files - 在项目中搜索文本
• git_status / git_diff / git_log / git_add / git_commit / git_branch / git_checkout - Git 操作
• undo_last - 撤销操作
• show_history - 查看操作历史
• task - 调用只读子代理（agent 参数指定名称）
• use_skill / list_skills - 获取 / 列出 Skills
• enter_plan_mode / exit_plan_mode - AI 自主进入 / 退出计划模式
• index_codebase / search_symbols / get_symbol_context - 代码库索引与符号搜索
• multi_write_file / apply_diff / batch_create - 多文件批量编辑、diff 应用、批量创建
• start_preview / stop_preview - 启动/停止本地 Web 预览服务器
• review_changes - AI 代码审查，分析当前变更的潜在问题
• project_health - 项目健康检查（依赖、测试、文档、配置）
• go_to_definition / find_references / get_type_info / get_docstring - Python 代码静态分析（基于 jedi）
• mcp__<服务器>__<工具> - MCP 服务器提供的工具（前缀区分来源）

VS Code 扩展

在 vscode-extension/ 目录提供了轻量扩展，支持一键在 VS Code 中启动 foxcode：

# 打包并安装
cd vscode-extension
npx @vscode/vsce package --no-dependencies
code --install-extension foxcode-0.1.0.vsix

安装后按 Ctrl+Shift+P 输入 FoxCode: Start in Right Terminal 即可在右侧终端启动 foxcode。

项目结构

foxcode/
├── main.py                 # 入口文件
├── pyproject.toml          # 项目配置
├── requirements.txt        # 依赖列表
├── .env                    # API 配置（勿提交）
├── .env.example            # 配置示例
├── workspace/              # 工作区目录
├── tests/                  # 冒烟测试
└── src/foxcode/
    ├── __init__.py
    ├── __main__.py         # python -m 入口
    ├── config.py           # 配置加载
    ├── models.py           # 数据模型
    ├── agent.py            # Agent 创建与工具注册
    ├── cli.py              # 交互式终端 / headless 入口
    ├── session.py          # 会话管理
    ├── permissions.py      # 权限确认系统
    ├── skills.py           # Skills 管理
    ├── subagents.py        # 子代理管理
    ├── mcp_manager.py      # MCP 服务器加载
    └── tools/
        ├── file_ops.py     # 文件操作工具
        ├── shell.py        # 命令执行工具
        ├── search.py       # 网络搜索工具
        ├── fetch.py        # URL 抓取工具
        ├── git.py          # Git 操作工具
        ├── grep.py         # 文件搜索工具
        ├── tree.py         # 目录树工具
        ├── copy_file.py    # 文件复制工具
        ├── tests.py        # 测试运行工具
        ├── format.py       # 代码格式化工具
        ├── deps.py         # 依赖安装工具
        ├── undo.py         # 撤销管理工具
        ├── mode.py         # 计划模式切换工具
        ├── security.py     # 安全检测工具
        ├── code_index.py   # 代码库索引工具
        ├── multi_edit.py   # 多文件批量编辑工具
        ├── preview.py      # Web 预览工具
        ├── review.py       # AI 代码审查工具
        ├── health.py       # 项目健康检查工具
        └── lsp_bridge.py   # LSP/jedi 代码分析桥接

License

AGPLv3