main
将自然语言描述的行动意图转化为标准化结构化行动计划的全栈智能体工程。 行动背景设定为 15 世纪欧亚战争时期(战船、重装骑士、城堡攻防、早期火器)。
严格前后端分离架构:
action_intent_planner/ ├── README.md ├── .gitignore ├── backend/ # 后端工程(FastAPI) │ ├── app/ │ │ ├── __init__.py │ │ ├── main.py # 应用入口(CORS / 路由挂载 / 单例装配) │ │ ├── config.py # 配置管理(.env 环境变量) │ │ ├── api/ │ │ │ ├── __init__.py │ │ │ ├── routes.py # RESTful API 路由 │ │ │ └── ws.py # WebSocket 实时推送端点 │ │ ├── core/ │ │ │ ├── __init__.py │ │ │ ├── event_bus.py # 进程内事件总线(进度/结果推送,带历史回放) │ │ │ └── plan_store.py # 计划结果存储(内存版,可替换 Redis/DB) │ │ ├── models/ │ │ │ ├── __init__.py │ │ │ └── schemas.py # Pydantic 数据模型(请求/五大模块/计划) │ │ ├── prompts/ │ │ │ ├── __init__.py │ │ │ ├── scenario_templates.py # 四大场景阶段模板 + 预设资源池 │ │ │ └── system_prompts.py # System Prompt 模板与构建函数 │ │ └── services/ │ │ ├── __init__.py │ │ ├── llm_service.py # LLM 调用封装(LangChain / JSON 提取) │ │ ├── plan_service.py # 核心编排:解析→生成→渲染(含离线模式) │ │ └── resource_service.py # 资源池生成服务 │ ├── scripts/ │ │ └── smoke_test.py # 离线模式冒烟测试(REST + WebSocket 全流程) │ ├── .env.example # 环境变量模板 │ ├── requirements.txt │ └── run.py # 后端启动脚本(uvicorn) └── frontend/ # 前端工程(Vue3 + Element Plus) ├── package.json ├── vite.config.js # /api 与 /ws 代理(开发环境同源无跨域) ├── index.html ├── public/ │ └── favicon.svg └── src/ ├── main.js # 入口(Element Plus 中文语言包 + 图标注册) ├── style.css # 全局样式(15 世纪军令文书风) ├── App.vue # 主页面(状态编排 / WebSocket 接收 / 导出) ├── api/ │ └── index.js # API 请求封装 + WebSocket 连接工具 └── components/ ├── IntentForm.vue # 输入表单(意图/预期/场景/资源池) ├── PlanProgress.vue # 生成进度步骤条 + 流式输出控制台 ├── PlanMarkdown.vue # 计划文档(预览 / 在线编辑) └── PlanJson.vue # 结构化 JSON(校验/编辑/同步预览)
cd backend # 创建并激活虚拟环境 python -m venv .venv # Windows (Git Bash) source .venv/Scripts/activate # Windows (PowerShell) # .venv\Scripts\Activate.ps1 # Linux / macOS # source .venv/bin/activate # 安装依赖 pip install -r requirements.txt # 配置环境变量(可选:不配置则以离线演示模式运行) cp .env.example .env # 编辑 .env,填入 LLM_API_KEY 等配置 # 启动(开发模式,热重载) python run.py # 或:uvicorn app.main:app --reload --port 8000
启动后访问交互式 API 文档:http://127.0.0.1:8000/docs
cd frontend npm install npm run dev
访问 http://localhost:5173 即可使用。 开发环境通过 Vite 代理访问后端(/api、/ws 同源转发),天然无跨域问题; 后端同时按 CORS_ORIGINS 配置放行了前端来源,直连部署同样可用。
/api
/ws
CORS_ORIGINS
cd backend python scripts/smoke_test.py
以离线模式跑通 REST + WebSocket 全流程(健康检查 / 场景列表 / 资源池生成 / 计划生成事件流 / 结果查询 / 编辑重渲染),无需任何 LLM Key。
编辑 backend/.env:
backend/.env
LLM_API_KEY
your-api-key
LLM_BASE_URL
https://open.bigmodel.cn/api/paas/v4
https://api.openai.com/v1
https://api.deepseek.com/v1
http://127.0.0.1:11434/v1
LLM_MODEL
glm-4-plus
gpt-4o
deepseek-chat
LLM_TEMPERATURE
0.7
LLM_TIMEOUT
120
http://localhost:5173
离线演示模式:未配置 Key(或未安装 langchain)时,后端基于四大场景的 阶段模板与预设资源池做规则化生成,输出同样完整的五大模块计划,方便无 Key 演示与联调;页面右上角会显示当前模式。
前端表单(意图 / 预期 / 资源池 / 场景) │ POST /api/plans/generate ▼ 后端创建 plan_id,后台异步任务三步执行 ──┐ │ 202 {plan_id, ws_path} │ 1. 意图解析(LLM) ▼ │ 2. 结构化生成(LLM 流式,严格 JSON Schema) 前端连接 /ws/plans/{plan_id} ◄───────────┘ 3. Markdown 文档渲染 │ 实时事件:progress / stage_done / llm_token / complete / error ▼ 双 Tab 展示:📜 计划文档(Markdown)|🧩 结构化数据(JSON) │ 在线编辑:Markdown 直接改;JSON 改后 POST /api/plans/render 同步预览 ▼ 一键导出:下载 .md / .json
action_intent
action_tasks
deployment
phases
readiness
/api/health
/api/scenarios
/api/resources/generate
{scenario, hint}
/api/plans/generate
{intent, expected_outcome, resources[], scenario}
{plan_id, ws_path}
/api/plans/{plan_id}
/api/plans/render
{plan}
/ws/plans/{plan_id}
服务端下发事件(JSON):
{"type": "subscribed", "plan_id": "xxx"} // 连接确认 {"type": "progress", "step": 1, "total_steps": 3, "stage": "intent_parsing", "message": "…"} {"type": "stage_done", "stage": "intent_parsing", "result": {…}} // 阶段完成(附中间结果) {"type": "llm_token", "content": "…"} // 大模型流式片段 {"type": "complete", "plan": {…}, "markdown": "…"} // 生成完成(双格式结果) {"type": "error", "message": "…"} // 生成失败
事件总线带历史回放:WebSocket 晚于任务启动连接也能拿到全部事件,不丢消息。
Prompt 定义于 backend/app/prompts/system_prompts.py,共 3 组:
backend/app/prompts/system_prompts.py
PLAN_SYSTEM_PROMPT_TEMPLATE
get_plan_system_prompt()
INTENT_SYSTEM_PROMPT
RESOURCE_SYSTEM_PROMPT
核心 Prompt 的设计要点(四层约束保证专业性与可解析性):
后端还内置中文键容错归一化(plan_service.normalize_plan_dict)与 尾逗号修复(LLMService.extract_json),即使模型偶发输出偏差也能稳定解析。
plan_service.normalize_plan_dict
LLMService.extract_json
完整 Prompt 原文见 backend/app/prompts/system_prompts.py, 模板数据见 backend/app/prompts/scenario_templates.py。
backend/app/prompts/scenario_templates.py
PlanStore
PlanEventBus
save/update/get
publish/subscribe
npm run build
版权所有:中国计算机学会技术支持:开源发展技术委员会 京ICP备13000930号-9 京公网安备 11010802047560号
⚔️ 行动意图计划生成智能体(action_intent_planner)
将自然语言描述的行动意图转化为标准化结构化行动计划的全栈智能体工程。 行动背景设定为 15 世纪欧亚战争时期(战船、重装骑士、城堡攻防、早期火器)。
严格前后端分离架构:
一、工程目录结构
二、快速启动
1. 后端(端口 8000)
启动后访问交互式 API 文档:http://127.0.0.1:8000/docs
2. 前端(端口 5173)
访问 http://localhost:5173 即可使用。 开发环境通过 Vite 代理访问后端(
/api、/ws同源转发),天然无跨域问题; 后端同时按CORS_ORIGINS配置放行了前端来源,直连部署同样可用。3. 后端冒烟测试(可选)
以离线模式跑通 REST + WebSocket 全流程(健康检查 / 场景列表 / 资源池生成 / 计划生成事件流 / 结果查询 / 编辑重渲染),无需任何 LLM Key。
三、LLM 配置说明
编辑
backend/.env:LLM_API_KEYyour-api-keyLLM_BASE_URLhttps://open.bigmodel.cn/api/paas/v4、OpenAIhttps://api.openai.com/v1、DeepSeekhttps://api.deepseek.com/v1、Ollamahttp://127.0.0.1:11434/v1LLM_MODELglm-4-plus/gpt-4o/deepseek-chatLLM_TEMPERATURE0.7LLM_TIMEOUT120CORS_ORIGINShttp://localhost:5173离线演示模式:未配置 Key(或未安装 langchain)时,后端基于四大场景的 阶段模板与预设资源池做规则化生成,输出同样完整的五大模块计划,方便无 Key 演示与联调;页面右上角会显示当前模式。
四、核心功能与数据流
结构化计划五大模块(严格输出)
action_intentaction_tasksdeploymentphasesreadiness四大任务场景(阶段模板)
五、API 一览
REST
/api/health/api/scenarios/api/resources/generate{scenario, hint}/api/plans/generate{intent, expected_outcome, resources[], scenario},返回{plan_id, ws_path}/api/plans/{plan_id}/api/plans/render{plan}WebSocket:
/ws/plans/{plan_id}服务端下发事件(JSON):
事件总线带历史回放:WebSocket 晚于任务启动连接也能拿到全部事件,不丢消息。
六、System Prompt 设计说明
Prompt 定义于
backend/app/prompts/system_prompts.py,共 3 组:PLAN_SYSTEM_PROMPT_TEMPLATE→get_plan_system_prompt())——核心 Prompt;INTENT_SYSTEM_PROMPT)——提取核心目标 / 敌我研判 / 约束 / 风险;RESOURCE_SYSTEM_PROMPT)——按 5 类生成带规模的资源标签。核心 Prompt 的设计要点(四层约束保证专业性与可解析性):
后端还内置中文键容错归一化(
plan_service.normalize_plan_dict)与 尾逗号修复(LLMService.extract_json),即使模型偶发输出偏差也能稳定解析。七、生产部署提示
PlanStore/PlanEventBus为单进程内存实现;多副本部署时替换为 Redis Pub/Sub + 持久化存储(保持save/update/get与publish/subscribe接口不变即可)。npm run build产物为纯静态文件,可由 Nginx 托管并将/api、/ws反向代理至后端。/api/plans/generate增加速率限制(如 slowapi)防止滥用。