agent4hypermesh计划

📋 从 "只有几段工具代码 + 手动 JSON 解析" 到完整 RAG‑Agent（HyperMesh + 文档检索 + 脚本生成）的路线图

文章目录

[📋 从 "只有几段工具代码 + 手动 JSON 解析" 到 **完整 RAG‑Agent（HyperMesh + 文档检索 + 脚本生成）** 的路线图](#📋 从 “只有几段工具代码 + 手动 JSON 解析” 到 完整 RAG‑Agent（HyperMesh + 文档检索 + 脚本生成） 的路线图)
- [📅 总体时间线（工作日）](#📅 总体时间线（工作日）)
- [🏁 阶段细化](#🏁 阶段细化)
- - [0️⃣ 项目准备 & 环境搭建（1 天）](#0️⃣ 项目准备 & 环境搭建（1 天）)
  - [1️⃣ 文档采集 & 清洗（4‑5 天）](#1️⃣ 文档采集 & 清洗（4‑5 天）)
  - - [1.1 采集所有帮助页面](#1.1 采集所有帮助页面)
    - [1.2 预处理（每种文件类型统一转 markdown）](#1.2 预处理（每种文件类型统一转 markdown）)
    - [1.3 代码块抽取 & 元数据标记](#1.3 代码块抽取 & 元数据标记)
    - [1.4 Chunk 切分](#1.4 Chunk 切分)
    - [1.5 产出](#1.5 产出)
  - [2️⃣ 向量化 & 索引（RAG 基础）（2‑3 天）](#2️⃣ 向量化 & 索引（RAG 基础）（2‑3 天）)
  - [3️⃣ Agent + Tool‑Calling（5‑6 天）](#3️⃣ Agent + Tool‑Calling（5‑6 天）)
  - - [3.1 迁移到 **LangChain Function‑Calling**（而不是手写正则）](#3.1 迁移到 LangChain Function‑Calling（而不是手写正则）)
    - [3.2 建立 **Agent**（Function‑Calling + Retrieval Augmented Generation）](#3.2 建立 Agent（Function‑Calling + Retrieval Augmented Generation）)
    - [3.3 添加 **后处理（结果展示）**](#3.3 添加 后处理（结果展示）)
    - [3.4 统一 **异常捕获**](#3.4 统一 异常捕获)
    - [3.5 单元测试 & 示例脚本](#3.5 单元测试 & 示例脚本)
  - [4️⃣ 自动化测试 & 质量评估（3‑4 天）](#4️⃣ 自动化测试 & 质量评估（3‑4 天）)
  - [5️⃣ 部署、UI & 文档（3‑5 天）](#5️⃣ 部署、UI & 文档（3‑5 天）)
  - - [5.1 Docker 镜像](#5.1 Docker 镜像)
    - [5.2 交互方式](#5.2 交互方式)
    - [5.3 文档 & 使用手册](#5.3 文档 & 使用手册)
- [📦 完整交付物清单（MVP）](#📦 完整交付物清单（MVP）)
- [⚠️ 关键风险 & 对策](#⚠️ 关键风险 & 对策)
- [📆 推荐的 **迭代节奏**（Sprint）](#📆 推荐的 迭代节奏（Sprint）)
- [🎯 快速启动的 **最小可运行 MVP**（2 天）](#🎯 快速启动的 最小可运行 MVP（2 天）)
- [📚 关键参考资源](#📚 关键参考资源)
- [🚀 下一步行动（立即执行）](#🚀 下一步行动（立即执行）)

下面的计划把 当前状态（0 % RAG） 拆成 5 大阶段 ，每个阶段列出 关键任务、交付物、估计工时 （工作日）以及 里程碑 。
整个项目的 最保守估计≈ 5 周 （约 25 工作日），若资源充足（并行多人成员）可以在 3‑4 周 完成 MVP（最小可行产品）。

前置假设

你已有一台可以跑 ollama（或 OpenAI）的大模型（qwen2.5‑coder / gpt‑4‑o‑mini）以及 Python 3.10+ 环境。

已经有 HyperMesh 2025 正式安装，且可以通过 import hypermesh as hm（或 hmapi）调用 Python API。

本地磁盘有 完整离线帮助目录 （即你贴的 .../help_doc/help/hwdesktop/altair_help/）。

项目代码管理使用 Git ，部署目标是 Docker‑Compose（后期可迁移到 Kubernetes / CI‑CD）。

📅 总体时间线（工作日）

阶段	时间	关键里程碑
0. 项目准备 & 环境搭建	1 d	repo、虚拟环境、Ollama/OPENAI、FAISS、LangChain 安装完成
1. 文档采集 & 清洗	4‑5 d	所有离线帮助 → 结构化、干净的纯文本 + 代码块
2. 向量化 & 索引（RAG 基础）	2‑3 d	FAISS / Pinecone 索引生成、检索 API 完成
3. Agent + Tool‑Calling（语言模型 + 工具）	5‑6 d	LangChain‑Agent（JSON/Function Call）+Gmsh +HyperMesh API 集成
4. 自动化测试 & 质量评估	3‑4 d	单元/集成测试、错误率、成功率报告
5. 部署、UI & 文档	3‑5 d	Docker 镜像、CLI/Web UI、使用手册、监控脚本
总计	≈ 20‑25 d	MVP 可交付（可在本地跑、接受自然语言指令生成 HyperMesh 脚本）

🏁 阶段细化

下面逐阶段列出 任务清单、输出（产出） 、所需技术/工具 和 时间估计 。

在每个阶段结束时请进行 回顾（Retro） ，确认是否达到 Definition of Done (DoD) 再进入下一阶段。

0️⃣ 项目准备 & 环境搭建（1 天）

任务	说明	DoD
创建 Git 仓库（`hypermesh-rag-agent`）	包含 `src/`, `data/`, `scripts/`, `docker/`, `README.md`	`git init` & `remote` 建立
设置 Python 虚拟环境	`python -m venv .venv` → `pip install -r requirements.txt`	`python -c "import langchain"` 成功
安装 LLM 后端	- `ollama pull qwen2.5-coder:7b` - 或 `pip install openai` 并配置 API key	能成功 `curl http://localhost:11434/api/generate`
安装向量库	`faiss-cpu`（或 `faiss-gpu`）	`python -c "import faiss"`
安装 LangChain 生态	`langchain`, `langchain-community`, `langchain-core`, `langchain-ollama`	无报错
添加 Gmsh & HyperMesh 包	`pip install gmsh` + `export ALT_HM_PYTHONPATH=...` 让 `import hypermesh` 可用	`import gmsh, import hypermesh` 正常
基础 CI（GitHub Actions）	`python -m pytest` 通过	CI 通过

1️⃣ 文档采集 & 清洗（4‑5 天）

1.1 采集所有帮助页面

递归遍历 help/hwdesktop/altair_help/ → 收集 .html, .htm, .xml。
同时可选采集 pythonapi/_sources/**/*.py（示例脚本）和 tcl 文档。

1.2 预处理（每种文件类型统一转 markdown）

文件	处理方式	关键点
HTML	`BeautifulSoup` → 去除 `<nav>`, `<script>`, `<style>`；保留 `<h1‑h6>`, `<p>`, `<pre class="code">`（Python/TCL）	把标题层级记作 `metadata["hierarchy"]`
Python 示例	直接读取，去除注释中的冗余路径	`metadata["source"]="pythonapi/.../example.py"`
TCL 文档	同 HTML 处理，只保留代码块	`metadata["lang"]="tcl"`

1.3 代码块抽取 & 元数据标记

对每段代码块（Python/TCL）生成 单独的 Document ，字段包括：tool_name（如果出现 h_ 前缀）、api_category、description。
为每个 文本段 （非代码）标记 section_path（如 Reference → Geometry → h_import) 以及 language（zh‑cn、en）。

1.4 Chunk 切分

使用 RecursiveCharacterTextSplitter ：chunk_size=400, chunk_overlap=50（可调）。
为每个 chunk 保存 token_count （通过 tiktoken）和 source_id（文件 + 行号）。

1.5 产出

data/clean_docs/*.jsonl（每行一个 {"page_content": "...", "metadata": {...}}）
scripts/prepare_docs.py（完整可复用的脚本）

预计工时 ：2 天（采集）+ 1 天（清洗、抽取）+ 1 天（Chunk & 验证） = ≈ 4 天

2️⃣ 向量化 & 索引（RAG 基础）（2‑3 天）

步骤	说明	技术细节
Embedding 选型	- OpenAI `text-embedding-3-large` （质量最高） - 或本地 `sentence-transformers/all-mpnet-base-v2`（离线）	需要 API key 或 `torch` GPU
批量嵌入	`embeddings.embed_documents([doc["page_content"] for doc in docs])`	5000‑10000 条文档每批 100‑200
构建向量库	`FAISS.from_documents(docs, embeddings)` 或 Pinecone（云）	保存为 `faiss.index` 与 `metadata.pkl`
检索包装	`vectorstore.as_retriever(search_kwargs={"k": 5, "filter": {"doc_type": "python"}})`	支持过滤（`doc_type`, `section`, `language`）
持久化	`vectorstore.save_local("rag_index")`	为后续部署提供 `load_local` 接口

产出

rag_index/（FAISS 索引 + 元数据）
scripts/build_index.py（一键生成）

预计工时 ：1 天（Embedding & 参数调优）+ 1 天（持久化 & 验证） = ≈ 2 天

3️⃣ Agent + Tool‑Calling（5‑6 天）

3.1 迁移到 LangChain Function‑Calling（而不是手写正则）

python 复制代码

from langchain_core.tools import tool

@tool
def create_cube(length:float, width:float, height:float, mesh_size:float=5.0) -> str: ...

# 同理 create_cylinder, create_sphere, create_beam

把 tools.py 改写为 LangChain Tool （返回 ToolResult）
拆分 create_* 为两套实现：
1. Gmsh（当前示例） -- 方便快速原型
2. HyperMesh Python API（正式版） -- 真正交付

3.2 建立 Agent（Function‑Calling + Retrieval Augmented Generation）

python 复制代码

from langchain_ollama import ChatOllama
from langchain_core.prompts import ChatPromptTemplate
from langchain.agents import initialize_agent, AgentType

retriever = vectorstore.as_retriever()

# Prompt: 让模型先检索相关文档，再生成函数调用
prompt = ChatPromptTemplate.from_messages([
    ("system", """你是 HyperMesh 自动建模专家。...
                只能返回下面的函数调用 JSON（不要解释）。"""),
    ("human", "{input}"),
])

llm = ChatOllama(model="qwen2.5-coder:7b", temperature=0)

agent = initialize_agent(
    tools=[create_cube, create_cylinder, create_sphere, create_beam],
    llm=llm,
    agent_type=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,
    retriever=retriever,
    verbose=True,
)

关键点 ：
- 系统提示中加入 *"先搜索文档（使用检索），再生成函数调用"。
- 检索过滤 （doc_type=="reference"）让模型只看到 API 说明。
- 返回结构 统一为 {"name":"create_cube","arguments":{...}}（LangChain 自动验证）。

3.3 添加后处理（结果展示）

python 复制代码

def post_process(tool_output: str) -> str:
    # 把返回的文件路径包装成 markdown:
    return f"✅ {tool_output}\n\n📂 结果文件已保存在 `{tool_output.split()[-1]}`"

3.4 统一异常捕获

用 ToolException 捕获 gmsh / hypermesh 报错，返回 结构化错误 （{"error":"..."}），让 LLM 再次尝试或给用户解释。

3.5 单元测试 & 示例脚本

目标	说明	示例
正向案例	"创建 100×50×30 mm 长方体，网格 5 mm"。	`agent.run("帮我建一个...")`
参数缺失	"给我一个圆柱体"。	LLM 自动使用默认 `mesh_size=5`
单位转换	"半径 15 mm 的球"。	LLM 将半径 → 直径，生成调用
错误恢复	输入非法数值（`-10`），模型应返回错误并让用户改正	通过 `ToolException` 捕获

产出

src/agent.py（完整 RAG‑Agent）
tests/（pytest 用例）
scripts/run_demo.py（交互 CLI）

预计工时 ：3 天（改工具、LLM Prompt、Agent 代码）+ 2 天（测试、调优） = ≈ 5 天

4️⃣ 自动化测试 & 质量评估（3‑4 天）

检测维度	目标	实现方式
功能成功率	≥ 90 % 的自然语言请求产生可执行脚本（无异常）	使用 30+ 随机用户查询 → 统计成功率
脚本可运行性	脚本执行后生成的 .inp/.cdb 文件存在且非空	自动检查文件大小
文档匹配度	检索到的文档覆盖生成的 API 参数	计算检索相关度阈值（向量相似度 > 0.75）
响应时间	≤ 3 秒（检索+LLM）	测量 `time.perf_counter()`
错误恢复	对无效输入返回友好中文提示	捕获 `ToolException`、检查返回 `summary`
安全性	脚本只能调用白名单函数	在 `Tool` 定义阶段明确 `allowed_functions`

实现：建立 pytest + pytest-benchmark 流水线，生成报告（HTML、CSV）。

产出

reports/evaluation_2025.md （详细指标）
scripts/evaluate.py （自动跑评估）

5️⃣ 部署、UI & 文档（3‑5 天）

5.1 Docker 镜像

Dockerfile 复制代码

FROM python:3.11-slim

# 系统依赖
RUN apt-get update && apt-get install -y libgl1-mesa-glx libglib2.0-0 \
    && rm -rf /var/lib/apt/lists/*

# Python 环境
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制代码 & 索引
COPY src/ /app/src/
COPY rag_index/ /app/rag_index/
WORKDIR /app

ENTRYPOINT ["python", "-m", "src.run_cli"]

Docker‑Compose ：包含 Ollama 容器（或 openai）以及 HyperMesh （如果需要 Windows GUI，可使用 wine + VNC，或仅在本地 Windows 机器跑）。
持久化 ：把 rag_index 挂在卷，避免每次重建。

5.2 交互方式

方式	实现	示例
CLI	`python -m src.run_cli "帮我建一个..."`	快速本地调试
Web UI (optional)	FastAPI + Gradio / Streamlit	浏览器输入自然语言 → 返回 JSON + 文件下载
VSCode Extension (future)	用 `language-server` 调用 Agent	在 CAD 脚本编辑器里直接生成代码

5.3 文档 & 使用手册

README.md → 项目简介、快速启动、Docker 运行、示例。
docs/ →
- 快速上手（三步跑通）
- API 列表 （create_*）
- 常见错误 & 排查
- 扩展指南（添加新工具、接入其他求解器）

📦 完整交付物清单（MVP）

类别	文件/目录	说明
代码	`src/agent.py`, `src/tools.py`, `src/run_cli.py`	主体逻辑、工具、入口
文档	`README.md`, `docs/quickstart.md`, `docs/tools.md`	使用手册
数据	`rag_index/`（FAISS 索引），`data/clean_docs/`（原始清洗）	静态资源
脚本	`scripts/prepare_docs.py`, `scripts/build_index.py`, `scripts/evaluate.py`	数据 pipeline、评估
测试	`tests/`（pytest + benchmark）	单元/集成
部署	`Dockerfile`, `docker-compose.yml`	容器化
报告	`reports/evaluation_2025.md`	性能 & 质量报告

⚠️ 关键风险 & 对策

风险	描述	缓解措施
文档体积大、加载慢	文档约 2‑3 GB（HTML + 资源），一次性读取会占内存	采用懒加载（只读取正文），在 Chunk 前过滤掉图片、脚本资源；索引只保存文本
LLM 幻觉（Hallucination）	模型可能自行编造参数	强制 JSON schema （LangChain `tool`）+ Re‑rank（使用检索得分过滤）
HyperMesh 许可证/API 兼容性	需要合法许可证，Python API 只在 Windows 上运行	在容器里挂载许可证文件，使用 Docker‑Volume ；在 CI 中使用 Mock 替代真实调用，防止泄露
跨语言（Python ↔ TCL）	某求解器只能接受 TCL 脚本	先实现两套工具（Python、TCL），在 Agent 中加入 `fallback_tool`（如 `create_cylinder_tcl`）
嵌入成本	使用 OpenAI 嵌入需要付费	在 MVP 阶段先用本地 `sentence-transformers`，后期可切换为 OpenAI 以提升质量
安全（任意代码执行）	通过 Tool 调用可能执行恶意代码	白名单（只注册 `create_*`），在 `tool` 装饰器里加入 `sandbox`（只允许 `gmsh`/`hypermesh` API），不允许 `os.system`、`subprocess` 之外的调用

📆 推荐的迭代节奏（Sprint）

周	目标	产出
W1	环境、文档采集、清洗	`data/clean_docs/`、`prepare_docs.py`
W2	向量化、索引、检索基准	`rag_index/`、`build_index.py`、检索性能报告
W3	完整 Agent（RAG+Tool）	`src/agent.py`、CLI Demo、基础测试
W4	完整性测试、错误恢复、性能调优	`tests/`、`evaluate.py`、报告
W5	Docker、UI、文档、交付	Docker 镜像、README、使用手册
W6 (可选)	扩展：HyperMesh Python API、TCL 双写、模型微调	`hypermesh_api_tools.py`、示例库

每周一次 Sprint Review → 演示 UI，收集反馈后决定是否提前进入下阶段（比如在第 3 周就开始 Docker 化）。

🎯 快速启动的最小可运行 MVP（2 天）

如果时间紧迫，只想验证 "自然语言 → 函数调用 → 网格生成" 的闭环，可以先：

跳过索引 → 直接把 tools.py 加入 LangChain tool ，让 LLM 强制 JSON （如你现在的 system_prompt）。
用 ChatOllama （或 gpt‑4o‑mini）直接 model.invoke(prompt) → json.loads → 调用对应 create_*。
只保留 离线文档 （HTML）用于 手工复制 参数（不做检索）。

这一步能在 1 天 完成，随后再逐步加入 RAG 、HyperMesh 、Docker。

📚 关键参考资源

类型	链接
LangChain Tool & Agent 文档	https://python.langchain.com/docs/modules/agents/
LangChain Retrieval‑Augmented Generation	https://python.langchain.com/docs/modules/data_connection/retrievers/
Gmsh + Python API 示例	http://gmsh.info/doc/texinfo/gmsh.html#Python-API
HyperMesh Python API 官方手册	`help/hwdesktop/altair_help/topics/reference/hwat/` (download 2025)
FAISS 官方文档	https://faiss.ai/cplusplus_api/
Ollama 使用指南	https://github.com/ollama/ollama
Docker + Ollama 示例	https://github.com/ollama/ollama/blob/main/examples/docker-compose.yml

🚀 下一步行动（立即执行）

初始化仓库 & 环境 （git init && python -m venv .venv），把 requirements.txt 填好（langchain, langchain-ollama, faiss-cpu, beautifulsoup4, tiktoken, gmsh, hypermesh）。
运行 scripts/prepare_docs.py ，确认能输出 clean_docs/*.jsonl（手动检查几条记录）。
生成向量索引 ：python scripts/build_index.py → rag_index/。
在 src/agent.py 实现 LangChain Agent （参考上面代码块），并跑 python -m src.run_cli "帮我建一个 100×50×30 mm 的长方体" 检查输出。
写第一个 pytest ：验证 create_cube 正确返回文件路径。
写 README 并记录第一次运行日志，形成 Sprint 1 的交付物。

完成以上 6 步，你将拥有 最小可运行的 RAG‑Agent，后续只需按计划加入检索、评估、容器化即可。

祝你项目顺利 🚀！如果在任何阶段卡住，随时贴出错误日志或需求，我可以帮你细化实现细节或调优提示。

agent4hypermesh计划

📋 从 "只有几段工具代码 + 手动 JSON 解析" 到 完整 RAG‑Agent（HyperMesh + 文档检索 + 脚本生成） 的路线图

文章目录

📅 总体时间线（工作日）

🏁 阶段细化

0️⃣ 项目准备 & 环境搭建（1 天）

1️⃣ 文档采集 & 清洗（4‑5 天）

1.1 采集所有帮助页面

1.2 预处理（每种文件类型统一转 markdown）

1.3 代码块抽取 & 元数据标记

1.4 Chunk 切分

1.5 产出

2️⃣ 向量化 & 索引（RAG 基础）（2‑3 天）

3️⃣ Agent + Tool‑Calling（5‑6 天）

3.1 迁移到 LangChain Function‑Calling（而不是手写正则）

3.2 建立 Agent（Function‑Calling + Retrieval Augmented Generation）

3.3 添加 后处理（结果展示）

3.4 统一 异常捕获

3.5 单元测试 & 示例脚本

4️⃣ 自动化测试 & 质量评估（3‑4 天）

5️⃣ 部署、UI & 文档（3‑5 天）

5.1 Docker 镜像

5.2 交互方式

5.3 文档 & 使用手册

📦 完整交付物清单（MVP）

⚠️ 关键风险 & 对策

📆 推荐的 迭代节奏（Sprint）

🎯 快速启动的 最小可运行 MVP（2 天）

📚 关键参考资源

🚀 下一步行动（立即执行）

📋 从 "只有几段工具代码 + 手动 JSON 解析" 到完整 RAG‑Agent（HyperMesh + 文档检索 + 脚本生成）的路线图

0️⃣ 项目准备 & 环境搭建（1 天）

1️⃣ 文档采集 & 清洗（4‑5 天）

2️⃣ 向量化 & 索引（RAG 基础）（2‑3 天）

3️⃣ Agent + Tool‑Calling（5‑6 天）

3.3 添加后处理（结果展示）

3.4 统一异常捕获

4️⃣ 自动化测试 & 质量评估（3‑4 天）

5️⃣ 部署、UI & 文档（3‑5 天）

📆 推荐的迭代节奏（Sprint）

🎯 快速启动的最小可运行 MVP（2 天）