Metadata-Version: 2.4
Name: foxcode
Version: 0.1.6
Summary: FoxCode - 一个强大的 AI 终端编码助手
Project-URL: Homepage, https://github.com/foxcode/foxcode
Project-URL: Documentation, https://github.com/foxcode/foxcode#readme
Project-URL: Repository, https://github.com/foxcode/foxcode
Project-URL: Issues, https://github.com/foxcode/foxcode/issues
Author-email: FoxCode Team <foxcode@example.com>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE.txt
Keywords: ai,cli,coding-assistant,llm,terminal
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: anthropic>=0.18.0
Requires-Dist: click>=8.1.0
Requires-Dist: cryptography>=41.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: markdown-it-py>=3.0
Requires-Dist: nicegui>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: openai>=1.0.0
Requires-Dist: pathspec>=0.12.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyside6>=6.5.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=0.47.0
Requires-Dist: tiktoken>=0.5.0
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: watchdog>=3.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: llama-cpp-python>=0.2.0; extra == 'local'
Description-Content-Type: text/markdown

# FoxCode | 简体中文

### 赞助商

[Fai](https://Fai.shunx.top/)

[English](README_EN.md) | [简体中文](README.md)

**新一代 AI 终端编码助手**

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19433875.svg)](https://zenodo.org/records/19433875)

### 贡献

#### 我们欢迎对 FoxCode 的贡献！您可以通过以下方式贡献：

1，贡献代码 您可以提交新功能或者修复bug，优化代码

2，贡献文档 您可以为 FoxCode 编写文档，包括用户手册、开发指南、API 文档等

3，维护问题：帮助管理 GitHub 问题，包括修复 bug、优化性能、添加新功能等

### Future

#### 贡献者奖励计划

(贡献者奖励计划由Fai提供)

我们将视贡献情况给予不同奖励

奖励使用模型包括：gpt-oss-120b，laguna-xs-2.1等等

（请查看issue和pr，重复的不给予奖励）

#### TODO

- [ ] 进一步完善TUI

- [ ] 修复TUI历史聊天的3个点的BUG

#### 怎么做？

克隆到本地：克隆您的 Fork 仓库到本地

创建新分支：在本地创建一个新的分支，用于您的贡献

提交贡献：在您的分支上进行贡献，提交到您的 Fork 仓库

创建 Pull Request：创建一个 Pull Request 到 FoxCode 仓库，描述您的贡献内容，请求您的贡献被合并

### 您可以做什么

1，贡献代码 您可以提交新功能或者修复bug，优化代码（长期计划）

2，编写多语言文档，多语言模块（长期计划）

3，维护问题：帮助管理 GitHub 问题，包括修复 bug、优化性能、添加新功能等（长期计划）

#### 贡献者奖励计划

我们计划在5月份发放赞助商api站点，参与有用贡献都会获得积分以奖励贡献者。

### 我的文档

1. 更新 pyproject.toml 中的版本号
2. 更新 __init__.py 中的版本号
3. tag Actions

### News

#### 2026

4.8 shunian 我需要一个foxcode的启动自动检查更新 ok

4.8 shunian 在每次工程完成后记录反思存在的问题，下次加入上下文中，可以大大提高效率，减少犯错 ok

4.6 shunian 如果使用/mcp url就可以直接安装mcp，或许可以极大地推动mcp的发展 ok

### 请注意，foxcode遵循AGPLv3，但不更改本软件代码不触发AGPLv3

### 简介

FoxCode 是一个终端 cli AI 编码助手，使用 Python 编写。它支持多种 AI 模型，提供智能代码生成、文件操作、任务规划、工作流程管理等功能，帮助开发者提高编码效率

### 特性

#### 核心功能
- **多模型支持**: OpenAI、Anthropic Claude、DeepSeek、Step、本地模型
- **文件操作**: 读取、写入、编辑、搜索文件
- **Shell 执行**: 在终端中安全执行命令
- **任务规划**: 管理复杂任务的执行流程
- **工作流程管理**: 标准化的开发工作流程（设计→编码→测试→合并→推送）
- **技能系统**: 可扩展的技能框架，支持动态加载
- **MCP 协议**: 支持 Model Context Protocol，连接外部工具
- **安全沙箱**: 可配置的命令执行安全策略
- **交互式界面**: 现代化的 TUI 终端界面
- **会话管理**: 保存和恢复对话历史，支持加密
- **多种运行模式**: 默认、YOLO、规划模式、自动接受编辑模式
- **语义代码索引**: 基于向量嵌入的代码语义搜索，支持增量更新和依赖图生成
- **知识库管理**: 跨会话知识存储，支持分类、标签和语义检索
- **上下文压缩**: 智能对话压缩和知识蒸馏，优化长对话处理
- **智能任务规划**: 自动任务分解、依赖分析和拓扑排序
- **项目结构分析**: 自动检测技术栈、代码质量评分和架构模式识别
- **错误分析**: 智能错误解析、根因分析和修复建议
- **高级调试**: 条件断点、日志断点、变量监视和调用栈分析
- **性能分析**: 执行时间分析、内存追踪和瓶颈识别
- **安全扫描**: 漏洞检测、敏感信息扫描和依赖安全检查
- **代码格式化**: 多语言代码格式化（Python、JavaScript、TypeScript 等）
- **重构建议**: 代码异味检测、设计模式建议和重构方案
- **依赖解析**: Python/Node.js 依赖分析和冲突检测
- **测试生成**: pytest 风格测试生成、边界用例和 TDD 支持
- **文档生成**: API 文档、docstring 和 README 自动生成
- **Git 高级操作**: 智能提交、冲突解决和分支管理
- **多模态处理**: 图像分析、Mermaid/PlantUML 图表生成

### 安装

```bash
pip install foxcode
```

### 快速开始

```bash
# 启动交互式会话 (CLI 模式)
foxcode

# 启动 TUI 图形终端界面
foxcode --tui

# 或通过 Python 直接启动 TUI
python -c "from foxcode.tui import run_tui; run_tui()"

# 直接提问
foxcode "帮我分析这个项目的结构"

# YOLO 模式（自动执行）
foxcode --yolo "创建一个 Flask 应用"

# 规划模式（只读）
foxcode --plan "分析代码库中的安全问题"

# 指定模型
foxcode -m claude "帮我重构这段代码"

# 恢复上次会话
foxcode -r
```

### TUI 终端界面

FoxCode 提供基于 Textual 构建的全功能 TUI（终端用户界面），1:1 复刻 Claude Code 的交互体验。

#### TUI 键盘快捷键

| 快捷键 | 动作 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行 |
| `Ctrl+L` | 清屏 |
| `Ctrl+N` | 新会话 |
| `Ctrl+S` | 保存会话 |
| `Ctrl+B` | 切换侧栏 |
| `Ctrl+T` | 循环模式 (yolo/plan/accept) |
| `F1 / ?` | 帮助 |
| `F11` | 全屏切换 |
| `PageUp / PageDown` | 上下翻页 |
| `Ctrl+A` | 全选文本 |
| `Ctrl+E` | 光标到行尾 |
| `Ctrl+K` | 删除到行尾 |
| `Ctrl+W` | 删除词 |
| `Ctrl+U` | 清空行 |
| `Esc` | 取消 |
| `Ctrl+C` | 仅在输入框中退出；在聊天区不退出（留给复制） |
| `Ctrl+Q` | 退出 FoxCode |
| `Ctrl+Y` | 复制上一条 AI 回复（静默，不提示） |
| `C` | 复制选中的消息（先点击消息选中，静默） |
| `D` | 删除选中的消息 |

#### TUI 斜杠命令（本地指令，不发给 AI）

以 `/` 开头的输入会被当作本地指令执行，而不是发送给 AI 代理。即使 AI 正在输出，命令也会立即执行。

**命令解析顺序：**
1. 先在 TUI 内置命令中查找（下表），命中即在 TUI 内执行；
2. 若 TUI 不认识，则把整条命令**原样转交给 CLI 的命令处理器**（`cli._handle_command`）执行——因此 README「交互式命令」里那一长串 CLI 命令（`/init` `/features` `/index` `/search` `/kb` `/debug` `/test` `/doc` `/git` `/topic` 等）无需在 TUI 中重复实现，直接在 TUI 里输入即可；
3. 只有 TUI 与 CLI 都不认识时，才在聊天区报错「未知命令」。

| TUI 内置命令 | 说明 |
|------|------|
| `/help` | 显示 TUI 命令列表 |
| `/clear` | 清空聊天（会取消正在进行的输出） |
| `/save` | 保存当前会话 |
| `/mode [name]` | 设置运行模式：`yolo` / `plan` / `accept_edits` |
| `/new` | 开始新会话（会取消正在进行的输出） |
| `/sidebar` | 切换侧栏 |
| `/fullscreen` 或 `/fs` | 切换全屏 |
| `/theme [name]` | 切换主题（dark / light / dark-ansi / light-ansi / dark-daltonized / light-daltonized） |
| `/history` | 显示输入历史 |
| `/quit` 或 `/exit` | 退出 FoxCode |
| `//text` | 发送一个以 `/` 开头的字面消息给 AI |

> 其余所有 `/命令` 均转发给 CLI 执行，CLI 输出会被捕获并显示在聊天区。TUI 通过临时重定向 CLI 的 `console` 来避免破坏终端界面。

#### TUI 特性

- **多行输入**: 支持 Shift+Enter 换行的 TextArea
- **命令历史**: Up/Down 导航历史命令
- **消息操作栏**: 光标选中消息后显示 E=编辑/C=复制/D=删除/J=跳转
- **动画 Spinner**: Linux 标准 `-/\\|` 旋转动画，带停滞检测和 Glimmer 扫光效果
- **Clawd 吉祥物**: ASCII 狐狸吉祥物，支持 4 种姿态动画
- **全屏模式**: F11 切换全屏，隐藏侧栏扩展主面板
- **会话持久化**: 自动保存/恢复会话到 `~/.foxcode/sessions/`
- **6 套主题**: dark / light / dark-ansi / light-ansi / dark-daltonized / light-daltonized
- **品牌色**: `#ffd56b` 暖金色
- **对话框系统**: 帮助、确认、权限请求、Diff 查看器、成本警告

### 命令行选项

| 选项 | 说明 |
|------|------|
| `--model, -m` | 指定 AI 模型（支持别名） |
| `--mode` | 运行模式 (default/yolo/plan/accept_edits) |
| `--yolo` | 快捷启用 YOLO 模式 |
| `--plan` | 快捷启用规划模式 |
| `--resume, -r` | 恢复上次会话 |
| `--session` | 指定会话 ID |
| `--list-sessions` | 列出所有会话 |
| `--config` | 显示配置 |
| `--debug` | 启用调试模式 |
| `--tui` | 启用 TUI 图形终端界面 |
| `--no-tui` | 禁用 TUI 界面 |
| `--version, -v` | 显示版本 |
| `--help, -h` | 显示帮助 |

### 交互式命令

在交互式会话中，可以使用以下命令：

#### 基本命令

| 命令 | 说明 |
|------|------|
| `/help` | 显示帮助 |
| `/clear` | 清空对话 |
| `/save` | 保存会话 |
| `/load <id>` | 加载会话 |
| `/mode <mode>` | 切换模式 |
| `/model <name>` | 切换模型 |
| `/token` | 显示 Token 使用统计 |
| `/sessions` | 列出会话 |
| `/exit` 或 `/quit` | 退出 |

#### 长时间运行模式命令

| 命令 | 说明 |
|------|------|
| `/init` | 生成项目初始化脚本 |
| `/progress` | 显示当前进度 |
| `/features [add/complete/list]` | 管理功能列表 |
| `/summary` | 生成会话摘要 |
| `/next` | 获取下一个建议任务 |
| `/long-running [on/off]` | 切换长时间运行模式 |
| `/index` | 构建语义代码索引 |
| `/index status` | 查看索引状态 |
| `/index update` | 增量更新索引 |
| `/search <query>` | 语义搜索代码 |
| `/kb` | 显示知识库状态 |
| `/kb add <content>` | 添加知识条目 |
| `/kb search <query>` | 搜索知识库 |
| `/kb tags` | 列出所有标签 |
| `/analyze` | 分析当前项目 |
| `/analyze tech` | 分析技术栈 |
| `/analyze quality` | 分析代码质量（bug） |
| `/debug start` | 启动调试会话 |
| `/debug break <file:line>` | 设置断点 |
| `/debug continue` | 继续执行 |
| `/debug step` | 单步执行 |
| `/debug vars` | 显示变量 |
| `/profile` | 启动性能分析 |
| `/profile report` | 查看分析报告 |
| `/security` | 运行安全扫描（bug） |
| `/security deps` | 扫描依赖漏洞（bug） |
| `/topic` | 显示当前输出主题模式 |
| `/topic default` | 切换到默认模式（完整输出） |
| `/topic debug` | 切换到调试模式（详细输出） |
| `/topic minimalism` | 切换到极简模式（精简输出） |
| `/format [files]` | 格式化代码 |
| `/refactor` | 获取重构建议 |
| `/test gen <file>` | 生成测试用例 |
| `/doc gen <file>` | 生成文档 |
| `/git smart-commit` | 智能提交 |
| `/git conflicts` | 分析冲突 |
| `/diagram <type>` | 生成图表 (mermaid/plantuml) |

### 配置

配置文件位置（按优先级排序）：
1. 项目级: `.foxcode.toml` 或 `foxcode.toml`
2. 用户级: `~/.foxcode/config.toml`


### 工作流程

FoxCode 提供了标准化的开发工作流程：

```
设计规划 → 编码实现 → 质量评估 → 本地测试 → 合并主分支 → 集成测试 → 推送分支
```

每个阶段都有状态追踪：
- 待处理 (pending)
- 进行中 (in_progress)
- 已完成 (completed)
- 失败 (failed)
- 已跳过 (skipped)
- 已阻塞 (blocked)

### 安全特性

- **沙箱模式**: 支持黑名单/白名单模式限制命令执行
- **命令验证**: 防止危险的命令注入攻击
- **敏感信息过滤**: 自动过滤 API Key 等敏感信息
- **会话加密**: 支持会话数据加密存储
- **安全审计**: 记录安全事件日志

### 开发

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
foxcode
```

### 项目结构

```
src/foxcode/
├── __init__.py              # 包入口
├── cli.py                   # CLI 入口
│
├── core/                    # 核心模块
│   ├── __init__.py
│   ├── agent.py             # AI 代理
│   ├── config.py            # 配置管理
│   ├── config_validator.py  # 配置验证
│   ├── providers.py         # 模型提供者
│   ├── session.py           # 会话管理
│   ├── session_encryption.py # 会话加密
│   ├── tasks.py             # 任务管理
│   ├── workflow.py          # 工作流程
│   ├── skill.py             # 技能系统
│   ├── sandbox.py           # 安全沙箱
│   ├── sensitive_masker.py  # 敏感信息屏蔽
│   ├── progress.py          # 进度管理
│   ├── feature_list.py      # 功能列表
│   ├── handoff.py           # 代理切换
│   ├── evaluator.py         # 评估器
│   ├── orchestrator.py      # 编排器
│   ├── command_manager.py   # 命令管理
│   ├── init_script.py       # 初始化脚本
│   ├── hooks.py             # 钩子管理
│   ├── work_mode.py         # 工作模式
│   ├── work_mode_config.py  # 工作模式配置
│   ├── open_space.py        # 开放空间
│   ├── process_watchdog.py  # 进程监控
│   ├── updater.py           # 更新器
│   │
│   │── 高级功能模块 ──
│   ├── semantic_index.py    # 语义代码索引
│   ├── knowledge_base.py    # 知识库管理
│   ├── task_planner.py      # 智能任务规划
│   ├── project_analyzer.py  # 项目结构分析
│   ├── error_analyzer.py    # 错误分析
│   ├── advanced_debugger.py # 高级调试器
│   ├── performance_analyzer.py # 性能分析
│   ├── security_scanner.py  # 安全扫描
│   ├── code_formatter.py    # 代码格式化
│   ├── refactoring_suggester.py # 重构建议
│   ├── dependency_resolver.py # 依赖解析
│   ├── test_generator.py    # 测试生成
│   ├── doc_generator.py     # 文档生成
│   ├── git_advanced_ops.py  # Git 高级操作
│   ├── multimodal_processor.py # 多模态处理
│   ├── enhanced_tools.py    # 增强工具集成
│   │
│   └── hooks/               # 钩子模块
│       ├── __init__.py
│       ├── base.py          # 钩子基类
│       ├── app_hooks.py     # 应用钩子
│       ├── command_hooks.py # 命令钩子
│       ├── config_hooks.py  # 配置钩子
│       ├── service_hooks.py # 服务钩子
│       ├── session_hooks.py # 会话钩子
│       ├── skill_hooks.py   # 技能钩子
│       ├── tool_hooks.py    # 工具钩子
│       └── work_mode_hooks.py # 工作模式钩子
│
├── commands/                # 命令模块
│   ├── __init__.py
│   ├── command.py           # 命令基类
│   ├── help.py              # 帮助命令
│   ├── prompt.py            # 提示命令
│   └── tool.py              # 工具命令
│
├── tools/                   # 工具模块
│   ├── __init__.py
│   ├── base.py              # 工具基类
│   ├── ai_tools.py          # AI 工具
│   ├── file_tools.py        # 文件操作
│   ├── shell_tools.py       # Shell 执行
│   ├── code_tools.py        # 代码分析
│   ├── mcp_tools.py         # MCP 工具
│   └── playwright_tools.py  # Playwright 工具
│
├── services/                # 服务模块
│   ├── __init__.py
│   ├── mcp.py               # MCP 协议
│   ├── mcp_installer.py     # MCP 安装器
│   └── api/                 # API 客户端
│       ├── client.py        # API 客户端
│       └── unified_client.py # 统一客户端
│
├── context/                 # 上下文模块
│   ├── __init__.py
│   ├── context_bridge.py    # 上下文桥接
│   ├── context_compressor.py # 上下文压缩
│   └── context_reset.py     # 上下文重置
│
├── tui/                     # TUI 界面 (Textual)
│   ├── __init__.py
│   ├── app.py               # 主应用入口
│   ├── icons.py             # 公开图标库
│   ├── theme.py             # 6 套主题系统
│   ├── styles.tcss          # TCSS 样式表
│   ├── screens/
│   │   ├── repl.py          # REPL 主屏
│   │   └── welcome.py       # 欢迎屏
│   ├── widgets/
│   │   ├── spinner.py       # Spinner 动画系统
│   │   ├── logo.py          # Clawd 吉祥物 + Logo
│   │   ├── message.py       # 消息渲染
│   │   ├── message_list.py  # 虚拟消息列表
│   │   ├── prompt_input.py  # 多行输入
│   │   ├── sidebar.py       # 侧栏会话列表
│   │   ├── dialog.py        # 对话框系统
│   │   ├── diff_viewer.py   # Diff 查看器
│   │   ├── permission.py    # 权限请求
│   │   └── cost_dialog.py   # 成本警告
│   └── design_system/
│       ├── divider.py       # 分割线
│       ├── tabs.py          # 选项卡
│       ├── progress.py      # 进度条
│       ├── status_icon.py   # 状态图标
│       └── themed_box.py    # 主题容器
│
├── types/                   # 类型定义
│   ├── __init__.py
│   └── message.py           # 消息类型
│
├── utils/                   # 工具函数
│   ├── __init__.py
│   ├── encoding.py          # 编码处理
│   └── statistics.py        # 统计信息
│
├── hooks/                   # 全局钩子
│   └── __init__.py
│
├── constants/               # 常量定义
│   └── __init__.py
│
├── components/              # 组件模块
│   └── __init__.py
│
└── screens/                 # 屏幕模块
    └── __init__.py
```

### 环境变量

| 变量名 | 说明 |
|--------|------|
| `OPENAI_API_KEY` | OpenAI API Key |
| `ANTHROPIC_API_KEY` | Anthropic API Key |
| `DEEPSEEK_API_KEY` | DeepSeek API Key |
| `STEP_API_KEY` | Step API Key |
| `FOXCODE_DEBUG` | 启用调试模式 |
| `FOXCODE_LOG_LEVEL` | 日志级别 |

### QFA

Q: 如果你觉得终端内容太多了，怎么启用终端极简模式：

/topic minimalism 

Q: 如何使用本地模型？

```bash
foxcode --model local --base-url http://localhost:8000/v1
```

Q: 如何查看 Token 使用情况？

在交互式会话中使用 `/token` 命令。

Q: 如何启用调试模式？

```bash
foxcode --debug
```

Q: 配置文件放在哪里？

项目级配置放在项目根目录的 `.foxcode.toml`，用户级配置放在 `~/.foxcode/config.toml`。


### License

AGPLv3 License - 详见 [LICENSE](LICENSE.txt) 文件
