105 lines
6.5 KiB
Markdown
105 lines
6.5 KiB
Markdown
# LianSyn-platform 输入解析模块
|
||
|
||
正式运行时，页面由生产控制平面提供；本目录仍保存现有操作台静态资源和外部解析适配器。任务状态不再以浏览器 `localStorage` 为权威，必须通过控制平面 API 读取和写入。
|
||
|
||
操作台首页只展示按创建时间倒序排列的最近 10 条任务；任务数量超过 10 条时，点击“查看更多”进入 `/history` 历史任务目录。历史目录仍使用同一登录会话和任务详情面板，支持按任务编号/摘要搜索、按状态筛选、分页，以及补充信息、确认提交、插件回查和彻底删除等现有操作。历史目录不新增归档状态，服务端持久化任务仍是唯一事实源。
|
||
|
||
操作台不会在页面刷新、插件重连或状态轮询时自动重交 ERP 任务。只有任务所属员工账号的首次明确确认会申请服务端唯一执行权；领取成功后才向该账号绑定的插件下发。领取后的投递超时或 ERP 回执不确定都会进入“待回查”，禁止自动重试。管理员只使用账号、渠道、解析策略和审计等管理功能，不进入任务数据面。
|
||
|
||
生产控制平面说明见 [../control-plane/README.md](../control-plane/README.md)。
|
||
|
||
本模块只负责接收业务员的原始指令，调用已发布的外部 Agent Profile，返回解析态 `operation` JSON。ERP 填单、浏览器插件和 ERP 提交链路不在本模块的解析调用范围内。`task_id`、`session_id`、提示词版本、重要摘要和通讯状态属于平台响应/任务信封，不写进 Agent `operation`。
|
||
|
||
## 服务端配置
|
||
|
||
> `server.mjs` 是独立解析适配器入口；完整操作台由根目录的生产控制平面提供，需要 PostgreSQL 和管理员登录。
|
||
|
||
外部服务配置只放在运行服务的环境变量中，不要写入浏览器、源码、`.env.example` 或日志：
|
||
|
||
```bash
|
||
export DEERFLOW_BASE_URL="https://superagent.nianxx.cn"
|
||
export DEERFLOW_OPEN_API_KEY="df_open_xxx"
|
||
export PARSER_REQUEST_TIMEOUT_MS="120000"
|
||
export PARSER_TOTAL_TIMEOUT_MS="180000"
|
||
export PARSER_MAX_EVENT_BYTES="65536"
|
||
export PARSER_MAX_TOTAL_BYTES="1048576"
|
||
export PARSER_MAX_EVENTS="2048"
|
||
node server.mjs
|
||
```
|
||
|
||
也可以使用支持 `--env-file` 的 Node.js 版本加载本地私有 `.env` 文件：
|
||
|
||
```bash
|
||
node --env-file=.env server.mjs
|
||
```
|
||
|
||
外部应用策略需要绑定一个已发布且开启 API exposure 的 Profile。调用请求不传 `profile_id`，由 `DEERFLOW_OPEN_API_KEY` 对应的外部应用策略决定实际 Profile。
|
||
|
||
## 本地接口
|
||
|
||
业务系统前端调用：
|
||
|
||
```http
|
||
POST /api/parse
|
||
Content-Type: application/json
|
||
```
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"task_id": "LIANSYN-ERP-20260712153000",
|
||
"raw_text": "产品名称：遇见老挝\n出发日期：2026-08-11",
|
||
"received_at": "2026-07-12T15:30:00+08:00"
|
||
}
|
||
```
|
||
|
||
控制平面为每个任务创建并持久化独立 Open Agent Session；只有任务处于 `awaiting_user_input` 且新消息不以已知业务指令开头时，操作台右侧的补充输入框或 `/api/messages` 才会沿用该会话。首个非空行带业务指令的消息始终创建新任务/新会话，即使请求携带旧任务或会话标识。左侧原始输入区每次都创建新任务。解析适配器的 `/api/parse` 作为独立服务入口，支持显式传入 `turn_no`、`session_id`、`recovery_count` 和 `history`，重复处理同一任务时使用稳定的 session/message 幂等键，不同任务不共享上下文。
|
||
|
||
外部 Profile 必须返回现有解析契约：
|
||
|
||
```json
|
||
{
|
||
"status": "agent_parse_passed",
|
||
"blockers": [],
|
||
"operation": {
|
||
"action": "team_order_create",
|
||
"order_nature": "formal",
|
||
"submit_mode": "dry_run",
|
||
"data": {
|
||
"customer": { "name": "示例客户", "keyword": "示例客户" },
|
||
"product": { "name": "遇见老挝" },
|
||
"departure_dates": ["2026-08-11"],
|
||
"passenger_counts": { "adult": 2, "child_bed": 1, "child_no_bed": 1 },
|
||
"room_counts": { "DBL": 2 }
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
资料缺失但可以由用户补充时返回 `agent_parse_needs_input`，且 `operation` 必须为 `null`，同时必须提供 `reply`；无法解析、越界、缺少 `reply` 或外部服务异常时返回阻断结果，不会将不完整 operation 交给后续模块。
|
||
|
||
接口响应会附带 `external_request` 技术诊断字段。除兼容保留当前请求 `stage` 外，还会记录带时间戳的 `timeline`，覆盖创建会话、SSE 连接、流结束、收到结果、标准契约校验和同会话修复等阶段。控制平面会把这些阶段与 `task_events.payload` 合并到页面唯一的大黑框“任务生命周期”纯文本日志；原始解析、operation、插件执行回执等技术 JSON 按对应事件缩进追加在黑框内，不再单独展示脱离时间的 JSON 面板。
|
||
|
||
解析失败结果会明确返回 `error_code`、`failure_stage`、`failure_source`、`failure_message`、`agent_returned`、`plugin_dispatch_started`、`erp_write_started`、`no_plugin_dispatch` 和 `no_erp_write`。例如 `external_operation_contract_invalid` 表示 Agent 已返回，但 `operation` 未通过解析态契约校验，任务未进入插件，也未写入 ERP；这不是“Agent 没返回”的错误。宿主对 Agent `operation` 只执行解析态契约校验；插件后续再执行前门禁、ERP 只读解析和严格执行态门禁。若外部 Profile 首次输出含未声明字段，适配器会在同一会话内最多发起一次契约修复请求，仍不通过就阻断，不会静默丢弃未知字段。
|
||
|
||
## 启动
|
||
|
||
推荐从项目根目录启动，自动加载项目本地环境文件：
|
||
|
||
```bash
|
||
cd /Users/inmanx/Documents/lwltAPI
|
||
npm run start:platform-adapter
|
||
```
|
||
|
||
也可以在本目录直接使用 Node 的环境文件参数：
|
||
|
||
```bash
|
||
cd /Users/inmanx/Documents/lwltAPI/LianSyn-platform
|
||
node --env-file=.env server.mjs
|
||
```
|
||
|
||
`LianSyn-platform/.env` 仅保存本机运行配置，已被 Git 忽略；部署时使用正式环境变量或部署平台注入配置。
|
||
|
||
完整操作台由控制平面提供。启动根目录的 `npm run dev` 后，打开 `http://127.0.0.1:8786/`，业务员先输入原始指令并点击“创建任务”。Agent 返回结构化结果后，业务员在选中任务的右侧点击一次“确认并提交到 ERP 插件”；插件依次执行前门禁、ERP 唯一解析、严格写前门禁、原生操作和写后回查。需要管理较早任务时打开 `http://127.0.0.1:8786/history`。页面不提供外部服务地址、模型、密钥或提示词编辑入口。`8765` 仅作为 `server.mjs` 的独立解析适配器入口，不提供登录会话接口。
|