山东大学创新实训-面向算法学习的智能在线 OJ 平台（5）

TerminalOJ Dify Agent 工作流编排方案最后更新2026-05-31目标在不改变前端/api/ai/*调用契约的前提下把 TerminalOJ 的 AI pipeline 对接到 Dify Workflow/Agent 编排。1. 需求分析worker.skill对 AI 侧的要求是“完成调用工作和 pipeline 工作”核心能力包括能力当前入口Dify 工作流任务AI 聊天 / 问题POST /api/ai/chattaskchatAI 辅助代码鉴别错误POST /api/ai/code-diagnosistaskcode_diagnosisAI 整理做题信息 / 知识图谱POST /api/ai/knowledge-graphtaskknowledge_graphAI 解题辅助POST /api/ai/solvetasksolve项目已有前端组件、Pinia store、后端 handler 和会话落库能力因此 Dify 不直接暴露给浏览器。边界如下Frontend AI panel - TerminalOJ backend /api/ai/* - backend/internal/ai.Client - Dify Workflow App /v1/workflows/run - normalized response back to existing frontend contract这样可以保留 JWT 鉴权、用户隔离、题目上下文装配、最近提交摘要查询和 Mock 降级。2. Dify 文档对齐本设计对齐 Dify 官方文档中的这些约束Workflow/Chatflow 通过节点画布组织 Start、LLM、Agent、Code、条件分支、End 等节点。Workflow API 使用POST /v1/workflows/run请求体包含inputs、response_mode、user。当前后端同步 JSON 接口使用response_modeblockingDify streaming 可以后续通过 SSE 另开路由。Agent 节点适合承载“解题教练”“代码诊断员”等带工具/推理策略的分支。参考Dify Workflow APIhttps://docs.dify.ai/api-reference/workflows/run-workflowDify Workflow by ID APIhttps://docs.dify.ai/api-reference/workflows/run-workflow-by-idDify Agent 节点https://docs.dify.ai/en/guides/workflow/node/agentDify Workflow 节点文档https://docs.dify.ai/en/guides/workflow/node3. 后端接入配置backend/config.yaml新增 Dify provider 兼容项ai:enabled:trueprovider:difyendpoint:https://api.dify.ai/v1api_key:app-xxxxxxxxmodel:gpt-4o-miniworkflow_id:response_mode:blockingtimeout_seconds:30说明enabledfalse仍走本地 Mock。providerexternal沿用原先{task, model, payload}envelope调用{endpoint}/chat等端点。providerdify调用 Dify Workflow API。workflow_id留空时调用/workflows/run填写后调用/workflows/{workflow_id}/run。api_key使用 Dify App API Key不放到前端。后端传给 Dify 的inputs固定为{task:chat | code_diagnosis | knowledge_graph | solve,model:gpt-4o-mini,payload:{...JSON string...}}其中payload是现有后端请求对象序列化后的 JSON 字符串包含userId、problem、history、code、recentSubmissions等上下文。4. 工作流模型在 Dify 中建立一个 Workflow AppStart 节点定义 3 个输入变量变量类型说明taskShort Text路由任务名modelShort Text后端配置的模型标识可作为提示词变量payloadParagraphJSON 字符串上游已装配业务上下文节点编排Start - Code: Normalize Payload - IF/ELSE: Route by task chat - Agent: OJ Tutor code_diagnosis - Agent: Code Doctor knowledge_graph - LLM: Learning Graph Builder - Code: Graph JSON Normalizer solve - Agent: Problem Solver - Code: Pack Result - End各分支职责分支节点建议目标输出chatAgent{ reply: ..., metadata: {} }code_diagnosisAgent structured JSON{ summary: ..., issues: [], suggestions: [], rawMarkdown: ... }knowledge_graphLLM Code{ summary: ..., nodes: [], edges: [], rawMarkdown: ... }solveAgent{ answer: ..., hints: [], complexity: ... }End 节点只暴露一个变量{result:{...task response JSON...}}后端适配器也兼容这些输出形式outputs.result为 JSON 字符串或 JSON 对象。outputs.response/outputs.output/outputs.data为 JSON 字符串或 JSON 对象。直接把reply、rawMarkdown、answer、summary等字段作为 outputs 返回。仅返回纯文本时后端会按任务包装成reply、rawMarkdown或answer。5. Prompt 约束各 Agent/LLM 节点统一遵守不直接给出完整 AC 代码除非tasksolve且levelfull。题目页上下文优先使用payload.problem不要猜测不存在的题目条件。代码诊断必须区分语法错误、边界条件、复杂度风险和评测信息。知识图谱节点输出稳定 JSONnodes[].id要可复用如tag:dynamic_programming、problem:1001。所有 Markdown 都允许包含 LaTeX 和代码块前端已有渲染能力。6. 联调流程在 Dify 新建 Workflow App按dify/terminaloj-agent-workflow.model.yaml搭建节点。发布 App复制 API Key。修改backend/config.yamlai:enabled:trueprovider:difyendpoint:https://api.dify.ai/v1api_key:app-xxxxxxxxresponse_mode:blocking启动后端并调用现有前端 AI 功能。若返回dify workflow response missing outputs检查 End 节点是否暴露了result。7. 后续扩展新增/api/ai/chat/stream将 Difyresponse_modestreaming转发为 SSE。将 Dify Workflow 拆成多个 App对话、诊断、图谱、解题分别用不同 API Key。在 Dify 中配置 HTTP 工具访问只读题库 API但仍建议通过后端代理避免泄露内部服务地址和用户权限。