# FC_Agent

**Repository Path**: chaiysh/fc_-agent

## Basic Information

- **Project Name**: FC_Agent
- **Description**: FreeCAD 智能体
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-05-28
- **Last Updated**: 2026-05-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FreeCAD智能体 (FC_Agent_V1)

基于FreeCAD的智能体应用程序，能够通过自然语言指令创建三维模型。

## 功能特性

### 1. 界面设计
- **侧边栏**：包含自然语言输入区域和大模型反馈显示区域
- **顶部菜单栏**：包含文件操作、编辑操作和设置功能
- **技能管理**：可视化的技能管理界面
- **FreeCAD对象选择器**：可视化选择FreeCAD中的对象、面、边、点等元素
- **工具调试窗口**：独立的工具调试界面，支持查看工具信息、填写参数、执行调用

### 2. 核心功能
- **自然语言理解**：支持通过自然语言指令创建3D模型
- **ReAct架构**：实现思考-行动-观察的智能体架构
- **多轮对话**：支持连续的多轮对话交互
- **工具封装**：将FreeCAD API封装为可直接调用的工具
- **实时反馈**：在侧边栏显示智能体的思考过程和操作结果
- **技能系统**：模块化的技能管理，支持动态加载和配置
- **对象选择器**：可视化选择FreeCAD对象，支持多选、添加、删除操作
- **工具调试**：独立的工具调试窗口，支持查看所有工具详情、参数辅助填写、执行测试
- **图像转模型**：支持从图片识别并生成3D模型

### 3. 支持的操作

#### 草图操作
- 创建多段线草图（支持直线和圆弧）
- 添加矩形、圆形到草图
- 拉伸特征（Pad）
- 旋转特征（Revolution）
- 放样（Pocket）
- 约束管理（清理冗余/冲突约束）

#### 齿轮设计
- 正齿轮（直齿圆柱齿轮）
- 斜齿轮
- 渐开线齿轮
- 齿轮副（一对啮合齿轮）

#### 装配功能
- 零部件组装
- 约束添加

#### 对象管理
- 删除对象、列出对象、获取对象信息
- 移动、旋转、缩放
- 面倒角、倒圆角
- 抽壳、厚度调整

#### 任务管理
- 创建待办事项列表
- 步骤执行跟踪
- 进度查询

## 系统要求

- **操作系统**：Windows 10/11
- **FreeCAD**：1.0.0+（推荐 1.1.0+）
- FreeCAD内置Python环境（无需单独安装Python）

## 安装步骤

1. **安装FreeCAD**
   - 从 [FreeCAD官网](https://www.freecad.org/) 下载并安装
   - 默认安装路径：`C:\Program Files\FreeCAD 1.1\` 或 `D:\Program Files\FreeCAD\`
   - 推荐使用 FreeCAD 1.1.0+ 版本

2. **安装Python依赖**
   
   在FreeCAD安装目录下执行（以管理员权限运行命令提示符）：
   ```bash
   cd "C:\Program Files\FreeCAD 1.1\bin"
   python.exe -m pip install -r "你的项目路径\FC_Agent_V1\requirements.txt"
   ```
   
   或使用国内镜像加速：
   ```bash
   python.exe -m pip install -r "你的项目路径\FC_Agent_V1\requirements.txt" -i https://pypi.tuna.tsinghua.edu.cn/simple
   ```
   
   也可以在FreeCAD的Python控制台中安装：
   ```python
   import subprocess, sys
   subprocess.check_call([sys.executable, "-m", "pip", "install", "-r", r"你的项目路径\FC_Agent_V1\requirements.txt"])
   ```

3. **配置FreeCAD路径**
   - 首次运行时，程序会自动检测FreeCAD路径
   - 如检测失败，在「设置」→「FreeCAD路径设置」中手动配置
   - 配置格式：`C:\Program Files\FreeCAD 1.1\bin`

4. **配置API密钥**
   - 在「设置」→「API密钥设置」中配置大模型API密钥
   - 支持OpenAI兼容的API（如阿里云DashScope、DeepSeek等）

5. **启动应用程序**
   - 双击运行 `FreeCAD_AI.bat`
   - 或使用FreeCAD的Python执行：
     ```bash
     "C:\Program Files\FreeCAD 1.1\bin\python.exe" -X utf8 main.py
     ```

### 常见安装问题

1. **pip安装失败**
   - 尝试使用国内镜像源：
     ```bash
     python.exe -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
     ```

2. **权限不足**
   - 以管理员权限运行命令提示符
   - 或添加 `--user` 参数：`python.exe -m pip install --user -r requirements.txt`

3. **PySide6/PySide2冲突**
   - FreeCAD 1.1+ 内置 PySide6，无需单独安装
   - FreeCAD 1.0.x 内置 PySide2，代码会自动适配

4. **opencv-python安装失败**
   - 尝试安装轻量版本：
     ```bash
     python.exe -m pip install opencv-python-headless
     ```

## 使用方法

### 1. 启动应用程序
- 运行 `FreeCAD_AI.bat` 或 `python main.py`
- 等待FreeCAD初始化完成

### 2. 输入自然语言指令
- 在侧边栏的「自然语言指令」文本框中输入指令
- 例如：`创建一个XY平面的草图，画一个矩形，拉伸成实体`
- 点击「发送指令」按钮

### 3. 查看处理过程
- 侧边栏会显示智能体的思考过程
- FreeCAD嵌入界面会实时显示模型创建过程
- 侧边栏会显示操作结果和详细信息

### 4. 使用对象选择器
- 点击侧边栏底部的「📌 FreeCAD对象选择器」按钮
- 在对象选择器中可以：
  - 点击「添加选择」后在FreeCAD视图中选择对象、面、边、点
  - 支持多选（按住Ctrl）
  - 可以移除或清空已选元素
  - 确认后选择结果会保存并在按钮上显示数量

### 5. 使用工具调试窗口
- 通过「设置」→「工具调试」打开工具调试窗口
- 在工具调试窗口中可以：
  - 左侧面板：搜索工具、按分类筛选、选择要调试的工具
  - 右侧上方：查看工具名称、功能说明、参数列表（类型、说明、是否必填）
  - 右侧中间：参数输入表单，根据参数类型自动生成对应控件
  - 底部：点击「运行」按钮执行工具调用
  - 输出区域：显示执行结果、状态和错误信息

## 示例指令

### 草图和拉伸
- `创建一个XY平面的草图，画一个矩形，拉伸成实体`
- `在XY平面创建草图，画一个半径20的圆，拉伸高度50`

### 齿轮设计
- `创建一个模数为2，齿数为20的正齿轮`
- `创建一对啮合齿轮，主动轮20齿，从动轮40齿`

### 对象管理
- `列出所有对象`
- `获取对象信息`

## 技能系统

技能系统允许模块化管理不同功能的提示词和工具使用方法。

### 技能分类

#### 基础技能 (Basic Skills)
- **草图技能 (Sketch Skills)**：草图创建、编辑、约束管理
  - sketch-basic：基础草图创建
  - sketch-advanced：高级草图操作
  - sketch-plane：草图平面设置
  - sketch-tools：草图工具使用
  - modify-sketch：草图修改
- **特征技能 (Feature Skills)**：拉伸、旋转、放样、齿轮设计
  - pad：拉伸特征
  - pocket：挖槽特征
  - revolution：旋转特征
  - gear：齿轮设计
  - chamfer-fillet：倒角倒圆
  - modify-feature：特征修改
- **装配技能 (Assembly Skills)**：零部件组装和约束
  - assembly：装配操作
- **图像技能 (Image Skills)**：图像识别与模型生成
  - image-describeObject：图像对象描述
  - image-CADDrawing：CAD绘图生成
- **构建步骤 (Build Step)**：步骤化构建流程

#### 中级技能 (Mid Level Skills)
- **通用零件 (General Part)**：通用零件创建
- **修改零件 (Modify Part)**：零件修改操作
- **查询 (Query)**：对象查询和分析
- **盒子 (Box)**：立方体创建
- **L型支架 (L-bracket)**：L型支架创建
- **图像转零件 (Image-to-Part)**：从图像生成零件

### 技能管理
- 通过「设置」→「Skill管理」打开技能管理界面
- 支持启用/禁用技能
- 支持查看技能详情

## 项目结构

```
FC_Agent_V1/
├── main.py                         # 主应用程序
├── FreeCAD_AI.bat                  # 启动脚本
├── requirements.txt                # 依赖列表
├── LICENSE                         # 许可证
├── agent/                          # 智能体模块
│   ├── multi_turn_agent.py         # 多轮对话智能体
│   └── sequential_orchestrator.py  # 顺序编排器
├── tools/                          # 工具模块
│   ├── __init__.py                 # 模块初始化
│   ├── base_tools.py               # 基础工具
│   ├── freecad_tools.py            # FreeCAD基础工具
│   ├── sketch_tools.py             # 草图工具
│   ├── sketch_edit_tools.py        # 草图编辑工具
│   ├── feature_tools.py            # 特征工具
│   ├── gear_tools.py               # 齿轮工具
│   ├── constraint_tools.py         # 约束工具
│   ├── transform_tools.py          # 变换工具
│   ├── assembly_tools.py           # 装配工具
│   ├── revolution_tools.py         # 旋转工具
│   ├── thickness_tools.py          # 厚度工具
│   ├── face_selection_tools.py     # 面选择工具
│   ├── datum_tools.py              # 基准工具
│   ├── document_tools.py           # 文档工具
│   ├── skill_tools.py              # 技能工具
│   ├── todo_list.py                # 任务管理工具
│   ├── tool_router.py              # 工具路由
│   ├── tool_categories.py          # 工具分类
│   ├── advanced_freecad_tools.py   # 高级FreeCAD工具
│   └── icons/                      # 工具图标
│       └── sketch_modifier.svg
├── utils/                          # 通用工具
│   ├── utils.py                    # 通用函数
│   ├── qt_compat.py                # Qt兼容性
│   ├── config_manager.py           # 配置管理
│   ├── skill_manager.py            # 技能管理
│   ├── llm_thread.py               # LLM线程管理
│   ├── llm_call_logger.py          # LLM调用日志
│   ├── dashscope_llm.py            # DashScope LLM
│   ├── openai_stream_llm.py        # OpenAI流式LLM
│   ├── command_history.py          # 命令历史
│   ├── debug_log.py                # 调试日志
│   ├── error_feedback.py           # 错误反馈
│   ├── query_answer_display.py     # 查询答案显示
│   ├── selection_manager.py        # 选择管理器
│   ├── token_usage_tracker.py      # Token使用追踪
│   ├── visualization_validation.py # 可视化验证
│   └── wait_selection_signal.py    # 等待选择信号
├── ui/                             # UI模块
│   ├── skill_dialog.py             # 技能管理对话框
│   ├── llm_settings_dialog.py      # LLM设置对话框
│   ├── llm_analysis_dialog.py      # LLM分析对话框
│   ├── stream_thinking_dialog.py   # 流式思考对话框
│   └── tool_debug_dialog.py        # 工具调试对话框
├── config/                         # 配置模块
│   ├── config_manager.py           # 配置管理器
│   ├── llm_config_manager.py       # LLM配置管理器
│   └── freecad_path.txt            # FreeCAD路径配置
├── Skills/                         # 技能目录
│   ├── skillset/
│   │   ├── basic skills/           # 基础技能
│   │   │   ├── sketch skills/      # 草图技能
│   │   │   │   ├── sketch-basic/
│   │   │   │   ├── sketch-advanced/
│   │   │   │   ├── sketch-plane/
│   │   │   │   ├── sketch-tools/
│   │   │   │   ├── modify-sketch/
│   │   │   │   └── sketch-overview/
│   │   │   ├── feature skills/     # 特征技能
│   │   │   │   ├── pad/
│   │   │   │   ├── pocket/
│   │   │   │   ├── revolution/
│   │   │   │   ├── gear/
│   │   │   │   ├── chamfer-fillet/
│   │   │   │   ├── modify-feature/
│   │   │   │   └── feature-overview/
│   │   │   ├── assembly skills/    # 装配技能
│   │   │   │   └── assembly/
│   │   │   ├── image skills/       # 图像技能
│   │   │   │   ├── image-describeObject/
│   │   │   │   ├── image-CADDrawing/
│   │   │   │   └── image-overview/
│   │   │   └── build-step/         # 构建步骤
│   │   ├── mid-level skills/       # 中级技能
│   │   │   ├── general-part/
│   │   │   ├── modify-part/
│   │   │   ├── query/
│   │   │   ├── box/
│   │   │   ├── L-bracket/
│   │   │   ├── image-to-part/
│   │   │   └── overview/
│   │   ├── system_prompt.txt       # 系统提示词
│   │   └── image_prompt.txt        # 图像提示词
│   └── README.md
├── llm/                            # LLM模块
│   └── openai_compatible_client.py # OpenAI兼容客户端
├── logs/                           # 日志目录
│   └── llm_calls/                  # LLM调用日志
├── Tests/                          # 测试脚本
└── README.md                       # 说明文档
```

## 技术架构

### 多轮对话
- 支持连续的多轮对话交互
- 保持上下文记忆
- 支持中断和取消操作

### 工具封装
- 将FreeCAD API功能封装为可直接调用的工具
- 每个工具包含明确的成功/失败反馈机制
- 支持参数化调用，适应不同场景
- 线程安全的recompute操作

### 技能系统
- 模块化的技能定义
- 动态加载和配置
- 与系统提示词集成
- 分层设计：基础技能 → 中级技能

### 交互流程
1. 用户输入自然语言指令
2. 智能体分析指令并规划操作
3. 智能体调用相应的FreeCAD工具
4. 工具执行操作并返回结果
5. 智能体处理结果并显示反馈
6. FreeCAD界面实时更新模型

## 常见问题

### 1. FreeCAD初始化失败
- **原因**：FreeCAD路径配置错误或FreeCAD未安装
- **解决**：检查FreeCAD路径设置，确保FreeCAD已正确安装

### 2. 无法创建立体
- **原因**：FreeCAD工作台未正确激活
- **解决**：应用程序会自动激活Part工作台，无需手动操作

### 3. 指令未被识别
- **原因**：指令表述不够明确或不在支持范围内
- **解决**：使用更明确的指令，如「创建一个边长为50的立方体」

### 4. 草图出现冗余约束警告
- **原因**：草图约束设置过多或冲突
- **解决**：使用「清理草图约束」功能，或让智能体自动清理

### 5. QObject::killTimer错误
- **原因**：Qt线程安全问题
- **解决**：已修复，所有recompute操作都通过主线程执行

### 6. 应用程序崩溃
- **原因**：FreeCAD版本不兼容或资源不足
- **解决**：确保使用FreeCAD 1.0.0+版本，关闭其他占用资源的程序

## 扩展开发

### 添加新工具
1. 在 `tools/` 目录中创建新的工具模块
2. 在 `agent/multi_turn_agent.py` 中注册工具
3. 更新工具描述和参数定义
4. 在 `tools/tool_categories.py` 中添加工具分类

### 添加新技能
1. 在 `Skills/skillset/` 目录中创建新的技能文件夹
2. 创建 `SKILL.md` 文件定义技能内容
3. 在技能管理界面中启用技能
4. 更新对应的 overview skill：
   - 草图类更新 `sketch-overview/SKILL.md`
   - 特征类更新 `feature-overview/SKILL.md`
   - 装配类更新 `assembly/SKILL.md`
   - 图像类更新 `image-overview/SKILL.md`
   - 中级技能更新 `mid-level skills/overview/SKILL.md`

### 优化智能体
1. 修改 `agent/multi_turn_agent.py` 中的命令分析逻辑
2. 调整工具调用参数提取规则
3. 优化思考过程的生成

### 界面定制
1. 修改 `main.py` 中的UI布局
2. 调整侧边栏宽度和窗口大小
3. 添加新的菜单选项和功能

## MCP 服务器

FreeCAD AI 内置 MCP (Model Context Protocol) 服务器，允许外部 AI 客户端（如 Trae IDE、Claude Desktop 等）通过 MCP 协议远程调用所有 FreeCAD 工具。

### 1. 启用 MCP 服务器

1. 打开应用，进入 **设置 → LLM 设置**
2. 找到 **MCP 服务器** 配置区域
3. 启用 **"启用 MCP 服务器"** 开关
4. 选择传输模式（推荐 **SSE (HTTP)**）
5. 配置主机和端口（默认 `localhost:8765`）
6. 点击保存，服务器将自动启动

### 2. 传输模式

| 模式 | 说明 | 适用场景 |
|------|------|----------|
| **SSE (HTTP)** | 基于 HTTP 的 Server-Sent Events | Trae IDE、远程客户端（**推荐**） |
| **Stdio** | 标准输入输出传输 | 子进程集成（GUI 环境下不可用） |

### 3. 在 Trae 中配置

在 Trae 的 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "freecad-ai": {
      "url": "http://127.0.0.1:8765/sse"
    }
  }
}
```

### 4. 验证服务器运行

```powershell
# 健康检查端点
Invoke-WebRequest -Uri http://localhost:8765/health -Method GET

# 检查端口监听
Get-NetTCPConnection -LocalPort 8765 -ErrorAction SilentlyContinue
```

启动成功后，日志将显示：
```
[MCP] 已注册 X 个工具
[MCP] SSE 服务器启动于 http://localhost:8765
```

### 5. 可用工具

MCP 服务器自动暴露 FreeCAD AI 所有工具（草图、特征、基准、布尔运算、装配等共 60+ 个）。详细工具列表见 `.trae/Doc/MCP_Server配置指南.md`。

### 6. 详细文档

完整的 MCP 配置说明、故障排除和高级用法，请参阅：
- `.trae/Doc/MCP_Server配置指南.md`

## 版本信息

- **版本**：1.3.0
- **发布日期**：2026-05-19
- **更新记录**：
  - v1.3.0
    - 新增工具调试窗口功能（设置→工具调试）
    - 工具调试窗口支持：工具列表、分类筛选、参数表单、执行测试、结果展示
    - 更新安装文档，支持FreeCAD内置Python环境安装依赖
    - 更新requirements.txt，新增图像处理依赖（Pillow、opencv-python、numpy）
    - 移除LLM分析窗口菜单项
    - 修复get_face_info的face_index计数方式（统一为从0开始，与其他工具保持一致）
    - 修复get_face_info和get_edge_info过滤逻辑，排除基准平面（XY/YZ/XZ）、基准轴（X/Y/Z_Axis）和PartDesign特征重复
    - 修复get_face_info和get_edge_info去重逻辑，使用对象名称替代id()避免重复处理
    - 简化get_face_info返回信息，移除edge_count、edge_types等边相关字段
    - 修复get_face_info法向量过滤逻辑，只匹配同向面而非同时匹配正反方向
    - 修复get_edge_info方向过滤逻辑，只匹配同向边而非同时匹配正反方向
    - 修复面描述生成逻辑（坐标系映射）
  - v1.2.0
    - 新增FreeCAD对象选择器功能
    - 新增面倒角、倒圆角功能
    - 新增抽壳、厚度调整功能
    - 新增旋转特征（Revolution）功能
    - 新增装配功能
    - 优化技能系统结构
    - 修复多项UI和交互问题
  - v1.1.0
    - 新增技能系统（Skill）
    - 新增任务管理功能（Todo List）
    - 新增齿轮设计功能
    - 新增草图约束清理功能
    - 新增多轮对话支持
    - 新增LLM调用日志
    - 修复Qt线程安全问题
    - 优化错误处理和用户反馈
  - v1.0.0
    - 初始版本，实现基本功能
    - 支持草图创建和拉伸特征
    - 实现ReAct架构的智能体
    - 集成FreeCAD嵌入界面