Halaman utama Jelajahi Bantuan
Masuk
WangKang
/
emoon-backend
1
0
Fork 0
Berkas Masalah 0 Permintaan Tarik 0 Wiki
Cabang: master
Ranting Tag
emoon-backend
/
docs
/
initiatives
/
FEAT-202606-006-agent-semantic-interaction
/
开发进度.md

开发进度.md 16 KB
Permalink Riwayat Mentahan

doc_id: DEV-202607-001 feature_id: FEAT-202606-006-agent-semantic-interaction type: dev-progress title: Agent 语义交互与命令治理阶段零/阶段一开发计划 status: draft owner: 医梦研发团队 created_at: 2026-07-02 updated_at: 2026-07-02 reviewers: [] related_docs:

  • PRD-202606-002
  • ODS-202606-002
  • DDS-202606-004
  • API-202606-004
  • DES-202606-003
  • TST-202606-001
  • ADR-202606-001 related_modules:
  • emoon-openplatform
  • emoon-ai-agent
  • emoon-ai-mcp tags:
  • Agent
  • FastGPT
  • ToolCatalog
  • TaskState
  • ResultSnapshot
  • 开发计划 ---

Agent 语义交互与命令治理阶段零/阶段一开发计划

当前开发口径

本文只覆盖 FEAT-202606-006 的阶段零和阶段一，严格按已批准的需求、设计、ADR、 迁移方案以及当前仍在观察中的接口/测试文档组织开发顺序：

  1. 先完成阶段零 FastGPT 能力验证；
  2. 仅在阶段零门禁通过后进入阶段一查询链实现；
  3. 本轮不进入命令链、emoon-ai-card -> emoon-ai-command 迁移、L1/L2 写命令、 动态 Presentation 模板和 v2 单次切换。

API-202606-004 与 TST-202606-001 当前仍在观察/确认中，因此本计划允许先启动 阶段零验证和阶段一任务准备，但不得跳过接口契约、测试计划和阶段零门禁直接宣称完成。

开发前必须读透

文档 必须理解的点
docs/standards/AI中台工程约束.md FastGPT 只读 ToolCatalog、TaskState 事实源、ResultSnapshot 绑定、OpenPlatform/MCP/Agent 模块边界
docs/standards/工程规约生效说明.md 阶段零/阶段一门禁、旧 Card 链禁止扩张、架构测试要求
专题索引.md 当前评审状态、下一步、流程裁剪
需求文档.md FR-08 FastGPT 边界、FR-09 只读工具目录、验收项 13/15/18
概要设计.md TaskState/ResultSnapshot/ToolCatalog 的整体职责和模块落位
详细设计.md ToolCatalog 生成、查询参数与 TaskState、ResultSnapshot、异常与安全规则
接口说明.md 终端不可提交内部状态、租户/项目/患者/会话绑定要求、只读 ToolCatalog 说明
迁移方案.md 阶段零和阶段一的目标、门禁和停止条件
测试计划.md TST-021、TST-022、TST-031、TST-032、TST-033 等本轮直接相关验收项

阶段门禁

阶段 目标 必须完成 未通过处理
阶段零 验证目标 FastGPT 版本可稳定承载文本流和只读工具调用 正常、参数错误、超时、空结果四类场景都能给出明确结论；只注册 Mock 只读工具；记录目标版本、事件格式、目录下发方式和 traceId 回传情况 停止后续开发，保留旧演示链，不进入阶段一
阶段一 构建最小查询链：FastGptAgentEngine、只读 ToolCatalog、TaskState 查询上下文、ResultSnapshot、租户/会话绑定 纯文本可完成查询；无效参数最多修复一次后自然语言澄清；ResultSnapshot 具备过期/版本/绑定校验；FastGPT 不可见写工具 不进入命令链，不宣称 v2 查询链稳定

任务拆分

任务 模块 状态 负责人 备注
D0 开发基线锁定 文档/模块边界 open 孙泽皓 锁定阶段零和阶段一范围，明确不进入命令链
D1 FastGPT Tool 调用验证 emoon-ai-agent in_progress Codex 已完成本地 tool_calls 识别/累积测试，待补目标 FastGPT 实例联调记录
D2 ToolCatalog 原型 emoon-ai-mcp + emoon-ai-agent in_progress Codex 已完成只读目录 DTO/元数据原型与定向测试，待补实际注入方式确认
D3 FastGptAgentEngine 收敛 emoon-ai-agent in_progress Codex 已基于现有引擎补齐 tool_calls 元数据收集，待补联调与异常场景记录
D4 TaskState 查询上下文 emoon-ai-agent + emoon-openplatform in_progress Codex 已补参数校验服务最小骨架，支持 schema 必填/未知字段/日期一次修复/自然语言澄清，并已接入 select_doctor -> querySchedules 查询入口
D5 ResultSnapshot 表和服务 emoon-ai-agent in_progress Codex 已补 DO/Mapper/Service 与定向测试，待补查询链集成与真实迁移执行
D6 租户/会话绑定 emoon-openplatform + emoon-ai-agent + emoon-ai-mcp open 待分配 查询链全程绑定租户、项目、患者、会话和任务
D7 阶段一集成验证 emoon-ai-agent + emoon-ai-mcp + emoon-openplatform open 待分配 以查询链门禁为准，不提前混入命令链

10D 排期

按 10 个工作日安排，并预留约 30% buffer 用于前期需求理解、后期测试联调、数据库执行和部署确认。 当前里程碑以“阶段零先过门禁、阶段一再进查询链”为唯一顺序，不并行挤压。

工作日 里程碑 目标 当前判断
D1 范围冻结与门禁对齐 锁定阶段零/阶段一范围、确认评审结论、收敛不做项 已启动
D2-D3 阶段零能力验证 完成 FastGPT Tool 事件、只读 ToolCatalog、traceId/超时/空结果/参数错误验证记录 进行中
D4-D5 阶段一事实层收口 完成 TaskState 版本/activeResult、ResultSnapshot 表和服务、数据库脚本 进行中
D6-D7 查询链接入 将只读查询结果接入 TaskState/ResultSnapshot，补参数校验、一次修复和澄清链路 待开始
D8 集成回归 跑查询链定向测试、编译、架构约束和关键回归 待开始
D9-D10 Buffer 联调、数据库执行、部署验证、缺陷修补和文档收尾 预留

里程碑说明

  • D1-D3 属于阶段零门禁，不通过则暂停 D4-D10 的宣称完成口径；
  • D4-D7 只做查询链，不提前引入命令链、emoon-ai-card -> emoon-ai-command 迁移和 v2 单次切换；
  • D9-D10 不视为“空闲时间”，默认用于数据库迁移执行、目标环境验证、接口观察项收口和回归缺陷处理。

任务说明

D0 开发基线锁定

  • 以现有 TaskStateService、McpToolService、FastGptAgentEngine 为代码基线收敛实现；
  • 不再扩展旧 cardKey/cardData/nextCard 作为流程推进语义；
  • 阶段零未通过前，不接受“先写查询链、回头再补验证”的倒序做法；
  • API-202606-004 与 TST-202606-001 的观察项继续保留，不在本计划中伪造已确认结论。

D1 FastGPT Tool 调用验证

目标完全来自 迁移方案.md 的阶段零：

  1. 验证目标 FastGPT 版本的文本流和工具调用事件；
  2. 验证医梦 ToolCatalog 能通过 MCP ToolSet、HTTP ToolSet 或 Workflow 工具节点下发；
  3. 验证工具参数 Schema、超时、错误和 traceId 能稳定回传；
  4. 只注册 Mock 只读工具，不接写工具。

本任务产出必须包含：

  • 目标 FastGPT 部署版本；
  • 工具调用事件样例和失败样例；
  • ToolCatalog 实际下发方式；
  • 阶段零通过/停止结论。

D2 ToolCatalog 原型

目标完全来自 需求文档.md、概要设计.md 和 详细设计.md：

  • ToolCatalog 的权威来源是 MCP Tool Registry；
  • 只保留 READ_ONLY 工具；
  • 按 tenant/project/agent/scene/terminal 做权限过滤；
  • 暴露稳定的 name/description/inputSchema/timeoutMs/riskLevel/dataClassification；
  • 发布时保存 ToolCatalog 版本和摘要，运行时记录实际版本。

实现约束：

  • 不把面向标准 Tool API 的完整读写目录直接暴露给 FastGPT；
  • 不允许模型自行发现或枚举内部写工具；
  • 目录差异只存在于 Adapter 注入方式，不改变医梦后端的工具权限模型。

D3 FastGptAgentEngine 收敛

本任务以仓库现有 com.emoon.mcp.engine.impl.FastGptAgentEngine 为基线，对齐 本专题设计，不另建第二套 FastGPT 引擎实现。

本任务只覆盖：

  • 文本流；
  • 只读工具调用；
  • 引擎能力门禁和元数据适配。

本任务明确不覆盖：

  • 写工具调用；
  • 风险等级裁决；
  • 命令准备、确认和执行；
  • 由模型直接生成可信业务事实。

如果目标 FastGPT 版本不支持可靠 Tool/Function Call，则该引擎只能继续用于纯文本问答， 不得进入后续业务命令链。

D4 TaskState 查询上下文

目标完全来自 详细设计.md 的“查询参数与 TaskState”章节：

  1. 取消单独的 propose_task_constraints 协议；
  2. FastGPT 调用只读工具时提交的参数即候选查询条件；
  3. 后端对参数做 JSON Schema、词典、日期和授权校验；
  4. 校验成功后才写入 TaskState 查询上下文并执行工具；
  5. 校验失败最多修复一次，无法修复时返回自然语言追问；
  6. 查询参数不能写入“已锁号、已挂号、已支付”等确定性状态。

实现约束：

  • 同一会话最多一个 ACTIVE 前台任务；
  • 插入问答不得破坏当前任务；
  • 终端不得提交 journeyState、TaskState、风险等级或 HIS 参数。

D5 ResultSnapshot 表和服务

目标完全来自 详细设计.md 的 ResultSnapshot 章节：

  • 新建 ai_result_snapshot，保存最小化、短期、版本化结果引用；
  • 必须包含：
    • result_ref/result_version/result_type
    • tenant_id/project_id/conversation_id/task_id
    • 可选 patient_binding_id
    • result_json/source_tool_call_id/trace_id/expires_at/created_at
  • 禁止保存完整 HIS 原始响应、无明确用途的长期医疗数据副本、写操作密钥或令牌。

ResultSnapshotService 的职责：

  • 最小化存储；
  • 版本校验；
  • 过期控制；
  • 访问控制；
  • 为文本回答、展示投影和后续选择提供稳定引用。

D6 租户/会话绑定

本任务覆盖查询链的访问边界，而不是命令链本身：

  • TaskState、ResultSnapshot 和工具调用全过程绑定租户、项目、患者、会话、任务和 traceId；
  • 查询和读取结果时必须校验 projectId/partnerId/deviceId 等现有可信上下文；
  • 跨租户、跨患者、跨会话伪造 ID 时返回 403，且不泄露存在性细节；
  • FastGPT 上下文不得注入完整患者资料或完整 HIS 原始响应。

本任务对应的测试计划重点是：

  • TST-021 租户越权；
  • TST-022 模型请求写工具；
  • TST-031 ToolCatalog 过滤；
  • TST-032 查询参数无效。

D7 阶段一集成验证

阶段一集成验证只对查询链门禁负责，目标是证明“不开 Card 也能完成查询链”：

  • 查询链能完成精确查询、空结果和替代推荐；
  • ToolCatalog 不包含任何写工具；
  • ResultSnapshot 具备过期、版本和绑定校验；
  • 无效查询参数能澄清且不暴露内部拒绝细节；
  • 关闭全部 Presentation/Card 后，文本/语音仍可独立完成查询交互。

本任务通过后，才能进入命令链设计与实现；本任务不等于完成命令链。

数据库与状态

涉及表

表 操作 说明
ai_task_instance select / update 持久化 TaskState 查询上下文、活动结果引用和版本
ai_result_snapshot create / insert / select / expire 保存查询结果最小快照，服务于文本、展示和后续选择

状态约束

当前状态 事件 目标状态 是否允许重试
ACTIVE 查询参数校验成功 ACTIVE 是
ACTIVE 查询参数无法修复 ACTIVE 是，转自然语言澄清
ACTIVE ResultSnapshot 过期 ACTIVE 是，要求重新查询
ACTIVE 工具调用超时/空结果 ACTIVE 是，按阶段零/阶段一策略降级

阶段记录

日期 进展 风险 下一步
2026-07-02 已根据 PRD、ODS、DDS、ADR、迁移方案和测试计划整理阶段零/阶段一开发计划 目标 FastGPT 版本事件格式尚未实测；API-202606-004 与 TST-202606-001 仍在观察 先执行 D1 阶段零能力验证，再按门禁推进 D2-D7
2026-07-02 已完成 FastGptAgentEngine 的 tool_calls 识别/流式累积最小实现，并通过 FastGptAgentEngineTest 12 条定向测试；已完成 HisToolCatalogService.readOnlyCatalog() 与 FastGptToolCatalogItem 原型，并通过 HisToolCatalogServiceTest 5 条定向测试 当前验证仍限于本地单元测试；目标 FastGPT 部署版本、ToolCatalog 实际下发方式、traceId/超时/空结果/参数错误联调结果仍未形成专题记录 继续梳理 D4/D5 现有代码基线，优先进入 TaskState 查询上下文与 ResultSnapshot 表/服务实现
2026-07-02 已完成 ResultSnapshotService 最小骨架、AiResultSnapshotDO/Mapper、TaskStateService 的版本与活动结果引用字段，并通过 ResultSnapshotServiceTest 4 条、TaskStateServiceTest 11 条定向测试 当前仍未把 ResultSnapshot 接入实际查询链；数据库变更尚未在目标环境执行；TaskState 还未实现 FastGPT 参数校验、一次修复和自然语言澄清 继续把 ResultSnapshot 接入查询链，再补阶段一所需的参数校验与上下文更新逻辑
2026-07-02 已补充 10D 排期和 30% buffer 里程碑，明确 D6-D7 进入查询链接入、D9-D10 留作联调与数据库执行缓冲 阶段零实测结论仍缺，D6-D10 只能按门禁顺延；当前查询结果还未形成真实 ResultSnapshot 绑定 先把只读查询结果接入 ResultSnapshot 与 TaskState activeResult，再继续参数校验与澄清链路
2026-07-02 已新增 TaskQueryConstraintService / TaskQueryConstraintResolution，实现只读查询参数的 schema 必填检查、未知字段拦截、日期一次修复、二次失败转自然语言澄清，并将该规则接入 AgentActionOrchestrator.select_doctor -> his.querySchedules；新增 TaskQueryConstraintServiceTest 3 条与 AgentActionOrchestratorTest 2 条入口测试 当前参数校验只覆盖已接入的挂号查询入口，尚未与 FastGPT tool_calls、更多只读工具和 openplatform 查询应用层完全打通 继续把同一套 D4 规则接到更多只读查询入口，再为 FastGPT 工具调用落正式适配点
2026-07-03 已完成目标 FastGPT 实例阶段零联调补证：确认当前实例可通过 url + key 直连 agent；stream=true + detail=true 时真实工具事件并非 OpenAI 标准 tool_calls，而是 toolCall / toolParams / toolResponse / flowResponses 四类 SSE 事件；并已将 FastGptAgentEngine 调整为流式请求自动开启 detail=true、收集上述 detail 事件并写入 metadata；新增 FastGptAgentEngineTest 3 条，当前该测试共 15 条全部通过 当前已确认的是 FastGPT 自定义 detail 事件协议，不再适合继续把阶段零结论表述为“等待 OpenAI 标准 tool_calls”；但 traceId 回传、超时/空结果/参数错误三类场景还未形成专题化记录，且本轮实测的带参数工具之一仍是参数变量节点，真实 MCP 带参数工具还需继续补证 继续把今天的阶段零实测结论沉淀为更完整的专题记录，并优先推进 D4/D5：把 FastGPT 工具参数校验、ResultSnapshot 和 TaskState activeResult 绑定接入正式查询链

范围变更

日期 变更 原因 是否同步 PRD/设计
2026-07-02 本轮开发计划只覆盖阶段零和阶段一，不进入命令链 与 迁移方案.md、设计交叉评审记录.md 的门禁一致 是

阻塞项

  • 目标 FastGPT 部署版本的 ToolCatalog 下发方式、traceId 回传、超时/空结果/参数错误实测结论尚未补齐；
  • API-202606-004 仍需后端、终端和 FastGPT 联调方最终确认；
  • TST-202606-001 仍需开发和测试共同确认；
  • 阶段零未通过前，不进入命令链和 v2 单次切换。

关联提交或 PR

  • 暂无，待阶段零验证开始后补充。