项目简介
OpenSpec 是一个企业级 AI 专业长文档生成平台，采用 RAG + 三智能体工作流架构，适用于建筑设计、招投标、汽车维修、医疗等需要生成结构化长文档的行业场景。
- GitHub：github.com/zhuzhaoyun/OpenSpec
- 开源协议：GPLv3
要解决的问题
在建筑设计、招投标等行业，从业者需要频繁产出几十页甚至上百页的专业文档。这些文档必须引用行业标准、前后数据一致、格式符合模板要求。
直接用 ChatGPT / 通义千问等通用大模型生成存在以下问题：
- 上下文丢失：写到第 30 页时前面的数据已经'忘了'，前后矛盾
- 幻觉严重：编造不存在的国标编号，张冠李戴引用条文
- 无审核机制：单个 AI 自己写自己审，发现不了自身错误
- 无知识库：不知道企业用的哪版规范、哪些设计参数
系统架构
整体架构
┌─────────────────────────────┐ │ Knowledge Base (RAG) │ │ Standards / Cases / Docs │ └──┬────────────┬────────────┬─┘ │ │ │ query on query on query on demand demand demand │ │ │ ┌────────┐ ┌──────────▼─┐ ┌─────▼─────┐ ┌▼──────────┐ ┌────────┐ │ Input │──▶│ Researcher │──▶│ Generator │──▶│ Auditor │──▶│ Export │ │ │ │ │ │ │ │ │ │ │ └────────┘ └────────────┘ └─────▲─────┘ └─────┬─────┘ └────────┘ │ │ └── revise ──────┘
三智能体工作流
基于 LangGraph 构建有向图状态机，三个智能体各司其职，每个智能体在发现上下文不足时自主查询知识库：
1. Researcher（检索智能体）
从知识库检索规范条文、历史案例、参考资料。
researcher_tools = [retrieve_case, retrieve_standard]
researcher_llm = llm.bind_tools(researcher_tools)
循环控制：
MAX_RESEARCH_LOOPS = 3（硬性上限）MIN_CONTENT_THRESHOLD = 1000（字符最小阈值）- 支持提前退出：内容充足 / 连续空结果 / LLM 判断资料足够
执行策略为两步式：先流式输出推理链（思考阶段），再生成 Tool Calls 调用检索工具（行动阶段）。
2. Generator（生成智能体）
基于检索上下文逐章生成内容。
核心能力：
- 跨章节关联：提取已生成章节
extract_previous_chapters()，做参数一致性检查 - 关联章节分析：
find_related_chapters()确保引用关系正确 - 智能 Token 计数：
calculate_available_tokens()精确控制篇幅 - 后处理：检测 XX、___ 等占位符替换为
[待填写]
上下文来源：从 Researcher 产出的 ToolMessage 中提取检索结果（最多保留 30 条）。
3. Auditor（校验智能体）
审核生成内容的质量。
auditor_tools = [retrieve_standard, retrieve_case]
auditor_llm = llm.bind_tools(auditor_tools)
五维度校验：
| 维度 | 说明 |
|---|---|
| 逻辑一致性 | 开头声明数量与表格数据是否匹配 |
| 参数合理性 | 数值是否在规范允许范围内 |
| 规范符合性 | 国标编号是否正确引用 |
| 内容完整性 | 必要章节和数据是否完整 |
| 格式规范性 | 符号、单位是否正确 |
校验结果：pass → 结束；revise → 带修改意见打回 Generator 重写。
控制参数：MAX_AUDIT_LOOPS = 1，MAX_AUDITOR_TOOL_CALLS = 5。
RAG 知识库
基于 RAGFlow 实现，提供两类检索工具：
@tooldefretrieve_case(query:str)->str:
"""从知识库检索历史案例"""
return _retrieve_from_kb(query, CASE_KB_IDS, "案例库")
@tooldefretrieve_standard(query:str)->str:
"""从知识库检索行业规范"""
return _retrieve_from_kb(query, STAND_KB_IDS, "规范库")
通用检索函数：
def _retrieve_from_kb(query, kb_ids, kb_name):
rag_object = RAGFlow(api_key=RAGFLOW_API_KEY, base_url=RAGFLOW_BASE_URL)
chunks = rag_object.retrieve(
question=query,
dataset_ids=kb_ids,
page=1,
page_size=10,
similarity_threshold=0.55
)
# 返回格式：【来源：XXX | 相关度：0.95】内容...
支持动态知识库：set_kb_ids() 可在基础库上追加企业特定知识库，retrieve_from_project_kb() 支持按项目 ID 查询。
Prompt 管理
所有 Prompt 通过 Langfuse 统一管理：
prompt_manager = PromptManager()
researcher_prompt = prompt_manager.get_prompt("langchain_researcher")
generator_prompt = prompt_manager.get_prompt("construction_agent_system")
auditor_prompt = prompt_manager.get_prompt("langchain_auditor")
支持在线调整 Prompt，无需改代码重新部署。
API 接口
# 流式生成（单章节，支持审核）
POST /chat/stream
# 参数：message, project_id, template, enable_audit, document_id, chapter_name...
# 批量生成（多章节，非流式）
POST /chat/batch
# 简化流水线：Researcher → Generate，无 Auditor
技术栈
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端 | Vue 3 + TypeScript + Vite | SPA |
| 后端 | Spring Boot 3 + Java 17 | RESTful API |
| AI 工作流 | Python + LangGraph + LangChain | 状态机式多智能体编排 |
| 知识检索 | RAGFlow | 向量检索，支持多知识库 |
| Prompt & 可观测性 | Langfuse | Prompt 管理 + LLM 调用追踪 + 成本分析 |
| 数据库 | PostgreSQL | 项目和文档数据 |
| 部署 | Docker Compose | 一键部署全部服务 |
项目结构
apps/
├── web/ # Vue 3 前端
├── backend/ # Spring Boot 后端
└── agent/ # AI Agent（核心）
├── service/workflow/
│ ├── construction_agent.py # 完整流程（Router + 三智能体）
│ ├── batch_construction_agent.py # 批量生成（无 Auditor）
│ └── rag_graph.py # RAG 简化流程
├── service/tools/
│ └── construction_tools.py # RAG 检索工具
└── api/
└── workflow_api.py # API 端点
应用场景
| 领域 | 知识库内容 | 生成文档 |
|---|---|---|
| 建筑设计 | 国标/地方标准、历史设计说明 | 施工图设计说明、可研报告 |
| 招投标 | 历史方案、施工规范、企业资质 | 投标技术方案 |
| 汽车维修 | 维修手册、故障案例、配件标准 | 维修技术手册 |
| 医疗健康 | 临床指南、诊疗规范 | 临床试验报告 |
快速部署
git clone https://github.com/zhuzhaoyun/OpenSpec.git
cd OpenSpec
cp deploy/docker/.env.example deploy/docker/.env
# 编辑 .env，填入以下必要配置：
# RAGFLOW_API_KEY, RAGFLOW_BASE_URL, DASHSCOPE_API_KEY
cd deploy/docker
docker compose up -d
关键环境变量：
| 变量 | 说明 | 必填 |
|---|---|---|
RAGFLOW_API_KEY | RAGFlow API 密钥 | 是 |
RAGFLOW_BASE_URL | RAGFlow 服务地址 | 是 |
DASHSCOPE_API_KEY | LLM API 密钥（默认通义千问） | 是 |
LANGFUSE_SECRET_KEY | Langfuse 私钥 | 否 |
LANGFUSE_PUBLIC_KEY | Langfuse 公钥 | 否 |
启动后访问 http://localhost 即可使用。