基于 pydantic-ai 框架的终端交互式 AI 编程助手，支持文件操作、命令执行、网络搜索等功能。
- 文件操作: 读取、创建、编辑（精确替换/覆盖）、追加、删除、重命名、列出文件
- 命令执行: 运行 shell 命令、执行脚本文件（支持 Python/JS/TS/Go/Rust 等）
- 网络搜索: 通过 Bing 搜索获取信息（无需 API Key）
- 撤销恢复: 支持操作撤销，避免误操作
- 对话记忆: 保持多轮对话上下文，长对话自动智能压缩保留关键信息
- 结构化输出: AI 返回清晰的 ActionPlan（解释、修改文件、代码片段），支持 Thinking 过程展示
- 代码库索引: 自动索引项目符号（类/函数/方法），支持快速定位
- Web 预览: 启动本地 HTTP 服务器预览前端项目
- AI 代码审查: 自动分析变更并给出安全、风格、逻辑审查建议
- 项目健康检查: 检测依赖、测试、文档、配置完整性
- 文件引用: 在对话中用
@文件名引用文件，自动注入内容 - 自动 Git 提示: 进入终端时自动提示未提交的变更
- LSP 桥接: 基于 jedi 提供 Python 代码的跳转定义、查找引用、类型信息（需 jedi）
- 图片理解: 支持 Markdown 图片语法
上传图片给 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 输出
pip install -r requirements.txt或使用 pip 安装包本身：
pip install -e .复制 .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 等）。
python main.py或安装后：
foxcode# 直接给提示
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）。
| 模式 | 说明 |
|---|---|
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 后输入目标）启动。流程：
- 主 AI 执行目标（可访问完整上下文与全部工具）
- 完成后启动一个独立上下文、只读的验收 AI，亲自检查工作区真实状态
- 验收通过 → 结束；未通过 → 将验收反馈交回主 AI 继续工作
- 循环直到确认完成（默认最多 8 轮）
为抵抗上下文自动压缩导致的进度丢失，Goal 模式要求 AI 持续维护三个持久化文件：
goal.md- 目标定义、验收标准、完成状态plan.md- 实施计划、当前阶段方案、关键决策todo.md- 任务清单（- [ ]未完成 /- [x]已完成）
每轮开始时 AI 先读取这些文件恢复进度，每完成重要步骤即同步更新。若工作目录是 git 仓库，每轮结束后会自动将这 3 个文件 git add + git commit（提交信息 goal: 第 N 轮进度），形成可回滚的进度检查点，不干扰其他工作区文件。
.foxcode/skills/<名称>/SKILL.md 格式：
---
name: code-review
description: 对代码做安全与性能审查
---
# 代码审查流程
1. 先读取变更文件
2. 检查安全与性能问题
3. 输出修复建议/skills列出所有技能；/skill <名称>把内容注入下一条提示- AI 也可通过
list_skills/use_skill工具按需获取
.foxcode/agents/<名称>.md 格式（frontmatter 可省略）：
---
name: reviewer
description: 代码审查者
model: gpt-4o-mini # 可选，覆盖默认模型
tools: [read_file] # 可选，限制可用工具
---
你负责审查代码质量，只读探索后用中文总结。- 默认只读（写工具自动过滤），适合隔离上下文的探索任务
- AI 用
task(prompt, agent="reviewer")调用；/agents列出所有定义
.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/
├── instructions.md # 项目指南（注入系统提示）
├── settings.json # 权限与运行参数
├── commands/ # 自定义 /命令（.md 文件，文件名即命令名）
├── skills/ # Skills（每技能一个目录）
├── agents/ # 子代理定义（.md 文件）
├── mcp.json # MCP 服务器配置
└── sessions/ # 保存的会话
在交互式终端中输入你的编程需求，AI 会自动调用工具完成。
| 命令 | 说明 |
|---|---|
/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 在推理过程中会自动调用以下工具：
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- 获取 / 列出 Skillsenter_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 服务器提供的工具（前缀区分来源）
在 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 代码分析桥接
AGPLv3