目录

⚔️ 行动意图计划生成智能体(action_intent_planner)

将自然语言描述的行动意图转化为标准化结构化行动计划的全栈智能体工程。 行动背景设定为 15 世纪欧亚战争时期(战船、重装骑士、城堡攻防、早期火器)。

严格前后端分离架构:

端 技术栈 说明
后端 Python 3.10+ / FastAPI / Pydantic v2 / LangChain 异步高性能,RESTful API + WebSocket 实时推送
前端 Vue3 / Element Plus / Vite / Axios / marked 双 Tab 展示、在线编辑、一键导出
LLM 任意 OpenAI 兼容服务(GLM / OpenAI / DeepSeek / Ollama…) 未配置 Key 时自动进入离线演示模式

一、工程目录结构

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(校验/编辑/同步预览)

二、快速启动

1. 后端(端口 8000)

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

2. 前端(端口 5173)

cd frontend
npm install
npm run dev

访问 http://localhost:5173 即可使用。 开发环境通过 Vite 代理访问后端(/api、/ws 同源转发),天然无跨域问题; 后端同时按 CORS_ORIGINS 配置放行了前端来源,直连部署同样可用。

3. 后端冒烟测试(可选)

cd backend
python scripts/smoke_test.py

以离线模式跑通 REST + WebSocket 全流程(健康检查 / 场景列表 / 资源池生成 / 计划生成事件流 / 结果查询 / 编辑重渲染),无需任何 LLM Key。


三、LLM 配置说明

编辑 backend/.env:

变量 说明 示例
LLM_API_KEY API Key;留空则进入离线演示模式 your-api-key
LLM_BASE_URL OpenAI 兼容接口地址 智谱 https://open.bigmodel.cn/api/paas/v4、OpenAI https://api.openai.com/v1、DeepSeek https://api.deepseek.com/v1、Ollama http://127.0.0.1:11434/v1
LLM_MODEL 模型名称 glm-4-plus / gpt-4o / deepseek-chat
LLM_TEMPERATURE 采样温度(建议 0.3—0.7) 0.7
LLM_TIMEOUT 单次调用超时(秒) 120
CORS_ORIGINS 允许跨域的前端来源(逗号分隔) 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

结构化计划五大模块(严格输出)

模块 JSON 键 内容
一、行动企图 action_intent 意图 / 命令 / 目的 / 可量化指标
二、行动任务 action_tasks 主要任务列表(名称、描述、负责力量、预期效果)
三、任务布势 deployment 总体态势 + 空间/逻辑部署明细(编成、位置、角色、规模)
四、任务实施阶段 phases 依所选场景模板动态生成(目标、时限、行动、力量、成功标准)
五、完成准备实现 readiness 各部队应具备状态、物资准备、注意事项

四大任务场景(阶段模板)

  • 城堡攻防:围困封锁 → 火力准备 → 突击破城 → 巩固占领
  • 战船海战:侦察预警 → 接敌机动 → 火力交锋 → 追击与收拢
  • 围魏救赵:佯动造势 → 转兵奔袭 → 攻其必救 → 运动歼敌
  • 围点打援:包围要点 → 困守诱援 → 设伏打援 → 攻坚收尾

五、API 一览

REST

方法 路径 说明
GET /api/health 健康检查(含 LLM 接入模式)
GET /api/scenarios 场景列表(含阶段骨架)
POST /api/resources/generate AI 生成 15 世纪可用资源池,body:{scenario, hint}
POST /api/plans/generate 发起计划生成,body:{intent, expected_outcome, resources[], scenario},返回 {plan_id, ws_path}
GET /api/plans/{plan_id} 查询计划结果(running / complete / error)
POST /api/plans/render 编辑后的 JSON 重渲染 Markdown,body:{plan}

WebSocket:/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 晚于任务启动连接也能拿到全部事件,不丢消息。


六、System Prompt 设计说明

Prompt 定义于 backend/app/prompts/system_prompts.py,共 3 组:

  1. 计划生成(PLAN_SYSTEM_PROMPT_TEMPLATE → get_plan_system_prompt())——核心 Prompt;
  2. 意图解析(INTENT_SYSTEM_PROMPT)——提取核心目标 / 敌我研判 / 约束 / 风险;
  3. 资源池生成(RESOURCE_SYSTEM_PROMPT)——按 5 类生成带规模的资源标签。

核心 Prompt 的设计要点(四层约束保证专业性与可解析性):

  • 角色设定:”苍鹰参谋”——15 世纪欧亚战场资深参谋官,锚定领域与语体;
  • 时代背景约束:明确 15 世纪可用技术白名单(早期火器、攻城器械、桨帆战船), 显式禁止超越时代元素,保证历史一致性;
  • 输出格式最高优先级:只输出一个合法 JSON、禁止解释文字与代码块围栏, 并内嵌与 Pydantic 模型一一对应的完整 JSON Schema 示例;
  • 场景阶段骨架注入:按用户所选场景将阶段名/目标动态注入 System Prompt, 要求”可细化内容,不得增删阶段、不得调整顺序”,实现模板驱动的阶段生成;
  • 内容编写原则:力量必须取自资源池、指标必须可量化可检验、 利用时代技术特点(装填慢、火药易潮)设计战术细节。

后端还内置中文键容错归一化(plan_service.normalize_plan_dict)与 尾逗号修复(LLMService.extract_json),即使模型偶发输出偏差也能稳定解析。

完整 Prompt 原文见 backend/app/prompts/system_prompts.py, 模板数据见 backend/app/prompts/scenario_templates.py。


七、生产部署提示

  • PlanStore / PlanEventBus 为单进程内存实现;多副本部署时替换为 Redis Pub/Sub + 持久化存储(保持 save/update/get 与 publish/subscribe 接口不变即可)。
  • 前端 npm run build 产物为纯静态文件,可由 Nginx 托管并将 /api、/ws 反向代理至后端。
  • 建议为 /api/plans/generate 增加速率限制(如 slowapi)防止滥用。
关于
237.0 KB
邀请码
    Gitlink(确实开源)
  • 加入我们
  • 官网邮箱:gitlink@ccf.org.cn
  • QQ群
  • QQ群
  • 公众号
  • 公众号

版权所有:中国计算机学会技术支持:开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号