Jupiter's Lab

我的个人博客与 GitHub 开源体系搭建记录

Mon, 01 Jun 2026 00:00:00 GMT

我的个人博客与 GitHub 开源体系搭建记录

这是我的第一篇博客。

我搭建这个网站的目标不是做一个传统简历站，而是构建一个长期维护的个人技术实验室，用来记录：

AI Agent 学习笔记
MCP 与工具调用实践
LangGraph / Spring AI 学习过程
GitHub 开源项目建设
后端架构与工程化经验

后续我会把 GitHub 仓库、技术文章和学习路线统一组织起来。

实习日报｜2026-05-28

Thu, 28 May 2026 00:00:00 GMT

一、今日主要工作

围绕供应交付智能助手平台原生化重构，完成 Supply_Delivery_Agent_MCP_Tool_Enhancement_Plan_v2_1 方案设计与优化。
基于旧供应交付 Agent 的 Skill/API 能力，推进旧 Skill 到 MCP Tool 的映射适配，明确后续平台统一以 MCP Tool 作为真实业务代码调用入口。
完成 Phase 0、Phase 1、Phase 2 三个阶段的推进与验收，包括旧 Skill 能力盘点、单 MCP Tool 最小闭环、校验类 Tool 接入和 Tool 匹配准确率增强。
新增并验证供应交付 Agent 第一批、第二批 MCP Tool，覆盖订单交付查询、未发货订单查询、供应能力查询、到货确认检查、订单发放检查、验收材料查询等能力。
参与并整理线上反馈提交“第一次失效，第二次成功”问题排查，完成从 Nginx 日志、数据库记录、应用日志到根因定位的完整证据链梳理。
沉淀 Phase 验收报告和线上问题排查文档，为后续开发验收、业务联调、问题复盘和系统加固提供依据。

二、核心完成内容

1. 供应交付 Agent MCP Tool 化方案设计

今天首先完成了供应交付智能助手平台原生化重构方案的整理与优化。该方案以旧供应交付 Agent 为业务样板，目标不是简单迁移旧 Agent，也不是黑盒纳管旧 Agent，而是通过旧 Agent 中沉淀的真实业务场景、Skill、API 调用链路和业务状态机，反向打磨新平台的 Plan-and-Execute 与 MCP Tool 调用基座。

本次方案明确了当前阶段的两条核心主线：

Plan-and-Execute 范式适配
让平台能够基于用户自然语言意图生成结构化 Plan，并将每个 Step 映射到一个或少量 MCP Tool。
MCP Tool 统一执行链路
将旧 Agent 中原有 Skill/API 调用方式统一改造为 MCP Tool 调用方式，后续平台执行真实业务代码统一通过 MCP Tool 完成。

方案中也明确当前阶段不建设记忆系统，不做 Conversation Memory、Working Memory、Long-term Memory 等实现，仅保留 conversationId、runId、executionContext 等轻量上下文字段作为后续扩展点。

本次方案的核心调整是：Skill 不再作为真实业务代码执行入口，而是退化为能力描述层和历史资产映射来源。真实执行主链路从原来的：

Plan Step → SkillMatcher → SkillInvoker → Tool

调整为：

Plan Step → ToolSelector / PlanValidator → McpToolStepExecutor → McpToolInvoker → MCP Tool

这种设计有利于统一工具发现、参数 Schema、调用审计、风险治理和后续高风险操作确认。

2. Phase 0：旧 Skill/API 能力盘点与 Tool 映射设计

今天完成了 Phase 0 阶段验收，主要目标是对旧供应交付 Agent 的 Skill/API 能力进行系统盘点，并形成旧 Skill 到 MCP Tool 的映射设计。

Phase 0 完成内容包括：

梳理旧 Agent 的 29 个 SKILL.md；
梳理每个 Skill 实际调用的 API、Service 或 Function；
按复杂度将旧 Skill 归类为 ONE_TOOL、FEW_TOOLS、FLOW_RESERVED、UI_RESERVED、SKIP；
形成 legacy_skill_code → mcp_tool_name 映射表；
明确第一批查询类 Tool；
明确第二批校验类 Tool；
明确第三批执行类 Tool 及其风险等级；
输出 MCP Tool 命名规范和分阶段接入顺序。

本阶段统计结果显示：

ONE_TOOL：7 个，适合单 Skill 映射为单 MCP Tool；
FEW_TOOLS：4 个，适合由 2-3 个 MCP Tool 通过 Plan 编排；
FLOW_RESERVED：5 个，后续进入 FlowEngine；
UI_RESERVED：8 个，后续结合表单或页面交互扩展；
SKIP：3 个，属于通用或元能力 Skill，暂不纳入供应交付业务 Tool 化范围。

同时，本阶段也完成了风险等级分布标注，其中查询类能力风险较低，执行类能力如订单发放、PO 审批、ShipSet 更新、ATP 初始化等被标记为高风险，后续需要接入 Human-in-the-loop、审计和幂等控制。

3. Phase 1：Plan-and-Execute + 单 MCP Tool 最小闭环

今天完成 Phase 1 阶段验收，目标是验证新平台可以通过 Plan-and-Execute 生成 MCP_TOOL_CALL Step，并调用 MCP Tool 完成供应交付查询类任务。

Phase 1 接入的第一批 3 个 MCP Tool 包括：

order_delivery_query：订单交付查询；
unshipped_order_query：未发货订单查询；
supply_capacity_query：供应能力查询。

本阶段主要完成以下开发任务：

新增供应交付 Agent Profile；
绑定 MCP Skill Server；
注册第一批 3 个 MCP Tool；
建立 agent_tool_bind；
建设 ToolCatalogProvider；
改造 PlanGenerator，使其能够读取 Tool Catalog 并生成 MCP_TOOL_CALL；
新增 PlanValidator，校验 Tool 存在性和参数完整性；
新增 McpToolStepExecutor；
新增 McpToolInvoker；
新增 ToolResultNormalizer；
将 Tool 调用记录写入 agent_tool_call_record。

同时新增了 agent_tool_capability 和 agent_skill_tool_mapping 两张表。其中，agent_tool_capability 用于保存 Tool 能力增强元数据，例如 intent examples、required slots、planning hints 等；agent_skill_tool_mapping 用于保存旧 Skill 到新 MCP Tool 的映射关系。

Phase 1 验收中，7 条验收标准全部通过，包括：

Planner 能生成 MCP_TOOL_CALL；
Step 中包含 serverCode、toolName、arguments；
Tool 来自当前 Agent Tool Catalog；
参数缺失时可生成 ASK_CLARIFICATION；
Tool 结果可被标准化；
最终回复可解释查询结果；
agent_run、agent_plan、agent_plan_step、agent_tool_call_record 均有审计记录。

端到端测试中，订单交付查询、未发货订单查询、供应能力查询等场景均完成验证，4 次运行状态均为 COMPLETED。测试期间还修复了两个问题：PlanPromptBuilder Prompt 模板缺少 inputContext 输出指示，以及 PlanFallbackFactory.parseAndCreate() 未解析 inputContext 字段。

4. Phase 2：校验类 Tool 接入与匹配准确率增强

今天还完成了 Phase 2 阶段验收，目标是在 Phase 1 查询类 Tool 的基础上，扩展校验类 Tool，并增强 Tool 匹配准确率和匹配过程审计能力。

Phase 2 新增 3 个 Tool：

arrival_confirmation_check：到货确认检查；
order_release_check：订单发放障碍检查；
acceptance_materials_query：验收材料文件查询。

本阶段主要完成内容包括：

为 Phase 1 和 Phase 2 的 Tool 补充 intent examples；
为每个 Tool 补充 required slots 和 inputSchema；
为 Tool 补充 risk_level 和 complexity_type；
保持 Planner Prompt 注入 Tool Catalog；
新增 agent_tool_match_record 表、实体和 Mapper；
在 PlanValidator 中增加 Tool 存在性和参数完整性校验；
增加 Tool 误命中回归测试集；
完成核心语义区分测试，防止相似 Tool 混淆。

Phase 2 的端到端测试包括：

到货确认检查；
订单发放检查；
验收材料查询。

测试结果均为 COMPLETED，其中部分返回如权限异常或未查到记录属于符合预期的业务行为。本阶段也验证了相似 Tool 的区分能力，例如“查询发货状态”和“执行发放”不能误命中同一 Tool。

截至 Phase 2，供应交付 Agent 的业务 Tool Catalog 累计达到 6 个，包括 3 个查询类 Tool 和 3 个校验/查询类 Tool。验收结论为 Phase 2 通过，Tool 匹配准确率阶段目标达成，6/6 工具命中正确。

5. MCP Tool 标准执行链路优化

今天在方案和阶段验收中进一步明确了 MCP Tool 标准执行链路。新的执行链路强调：Planner 不再主要面向旧 Skill 列表生成计划，而是面向当前 Agent 绑定的 Tool Catalog 生成 Tool-aware Plan。

标准链路如下：

用户输入
  → AgentRunController
  → ToolCatalogProvider
  → PlanGenerator
  → PlanValidator
  → McpToolStepExecutor
  → McpToolInvoker
  → MCP Client Gateway
  → MCP Skill Server
  → ERP Tool Wrapper
  → ERP Service / API
  → ToolResultNormalizer
  → ResultSynthesizer
  → 最终回复

该链路能够保证：

Tool 必须来自当前 Agent 绑定的 Tool Catalog；
不允许 Planner 编造不存在的 toolName；
参数缺失时应追问或返回参数不足，不允许乱猜关键业务参数；
Tool 调用结果统一标准化，便于最终回复生成；
Tool 调用全过程可以落库审计。

这为后续接入执行类 Tool、HIL、复杂 Flow 和平台级治理打下基础。

6. 线上问题排查：反馈提交第一次失效、第二次成功

除了供应交付 Agent MCP Tool 化工作外，今天还参与并整理了一个线上间歇性问题排查：用户反馈提交时出现“第一次失效，第二次成功”。

问题场景为用户调用 POST /api/portal/feedback 提交反馈。现象是用户第一次提交后数据库没有生成反馈记录，过一段时间再次提交同类反馈则成功。

本次排查过程包括：

定位应用服务进程和日志文件
通过 ps -ef | grep java 确认问题服务为 langchain-agent，进一步通过 /proc/<PID>/fd/1 定位标准输出日志为 /home/jar/langchain-agent/logs/console.log。
确认问题发生时间范围
结合用户反馈，将重点时间段定位到 2026-05-28 14:14 左右。
检查 Nginx 访问日志
检索 /api/portal/feedback 请求，确认 14:14 左右请求真实到达 Nginx，且 HTTP 状态码返回 200。
对比数据库反馈记录
将 Nginx 请求时间与数据库记录对比，发现 14:14 左右多次请求虽然 HTTP 200，但数据库没有对应记录；14:27 之后请求恢复正常并成功落库。
检索应用异常日志
在 14:14 时间段发现 AI-UDS 网关调用异常，核心错误为 401 Unauthorized，同时业务日志中出现 SkillAccessLogService 网关返回失败记录。

最终形成的证据链表明：请求已经到达服务端，Nginx 返回 HTTP 200，但后端业务链路中调用 AI-UDS 网关记录访问日志时出现 401 Unauthorized，导致反馈提交业务未完整执行，最终反馈记录未落库。

本次问题定性为：

外部 AI-UDS 网关认证异常导致反馈提交业务失败，同时接口仍返回 HTTP 200，造成用户侧“提交成功假象”和数据库未落库问题。

7. 线上问题优化建议沉淀

针对本次线上问题，今天也沉淀了后续优化建议：

对 AI-UDS 401 Unauthorized 增加专项处理，例如刷新 token 后重试一次；
避免非核心访问日志链路阻断反馈主业务落库；
修正接口返回语义，避免业务失败仍返回 HTTP 200 假成功；
前端不能只根据 HTTP 200 判断成功，应结合响应体业务 code；
外部网关调用失败日志中补充 traceId、用户 ID、skillCode、entityType、HTTP 状态码、重试次数等上下文；
对 AI-UDS 401、反馈落库失败、HTTP 200 但业务失败等情况增加监控告警；
建立修复后的验证场景，包括正常提交、AI-UDS 401、AI-UDS 不可用和 HTTP 200 假成功校验。

该排查文档可以作为后续修复、复盘和线上问题处理手册的一部分。

三、今日工作产出

完成《供应交付智能助手平台原生化重构与 MCP Tool 化接入计划 v2.1》方案制作与优化。
完成 Phase 0 验收：旧 Agent 29 个 Skill 盘点、复杂度归类、风险等级标注和 Skill → MCP Tool 映射设计。
完成 Phase 1 验收：Plan-and-Execute + 单 MCP Tool 最小闭环，接入 3 个查询类 MCP Tool。
完成 Phase 2 验收：新增 3 个校验/查询类 Tool，并增强 Tool 匹配准确率和匹配审计能力。
新增并验证供应交付 Agent Profile、MCP Skill Server 绑定、agent_tool_bind、Tool Catalog、PlanValidator、McpToolStepExecutor、McpToolInvoker、ToolResultNormalizer 等能力。
新增 agent_tool_capability、agent_skill_tool_mapping、agent_tool_match_record 等表或能力，为旧 Skill 映射、Tool 元数据增强和 Tool 匹配审计提供数据基础。
完成 6 个供应交付业务 Tool 的阶段性接入和端到端验证。
完成 Phase 1 共 28 个测试用例验证，构建通过；Phase 2 完成核心 Tool 命中验证，6/6 工具命中正确。
完成线上反馈提交问题排查记录，定位 AI-UDS 网关 401 认证异常导致 HTTP 200 假成功和反馈未落库问题。
沉淀线上问题优化建议，包括 token 刷新重试、主业务与访问日志解耦、接口返回语义治理和监控告警建设。

四、遇到的问题与解决情况

1. 旧 Skill 能力复杂，直接迁移容易导致平台主线发散

问题：旧供应交付 Agent 中存在查询、校验、执行、UI、多轮状态机等多类 Skill，如果直接整体迁移，容易导致新平台执行链路复杂化。
处理：在 Phase 0 中将 29 个 Skill 按复杂度分为 ONE_TOOL、FEW_TOOLS、FLOW_RESERVED、UI_RESERVED、SKIP，并明确分阶段接入顺序。
结果：形成清晰的 Tool 化改造路线，优先推进低风险单工具查询和校验能力，复杂 Flow 与 UI 能力后置。

2. Planner 可能生成不存在或不属于当前 Agent 的 Tool

问题：LLM 在生成 Plan 时可能编造 toolName，或者选择未绑定给当前 Agent 的工具。
处理：引入 ToolCatalogProvider 和 PlanValidator，Planner 只能基于当前 Agent 的 Tool Catalog 生成 MCP_TOOL_CALL，PlanValidator 再校验 Tool 存在性和参数完整性。
结果：Phase 1、Phase 2 验收中 Tool 来自 Agent Tool Catalog，PlanValidator 能拦截未知 Tool。

3. Tool 返回格式不统一影响最终回复生成

问题：不同业务 Tool 的返回结果格式可能不一致，影响 ResultSynthesizer 对结果的理解和最终回复生成。
处理：新增 ToolResultNormalizer，对标准 JSON 和非 JSON 返回进行统一包装和规范化。
结果：Tool 调用结果可以稳定进入后续最终回复合成链路。

4. Tool 语义相似导致误命中风险

问题：供应交付场景中“查询发货状态”“检查能否发放”“执行发放”等表达相近，容易导致 Tool 误匹配。
处理：Phase 2 中为每个 Tool 补充 intent examples、required slots、risk_level、complexity_type，并新增 ToolMatchRecord 审计能力。
结果：核心测试集中 6/6 工具命中正确，相似 Tool 的语义边界得到加强。

5. 线上反馈提交存在 HTTP 200 假成功

问题：Nginx 日志显示反馈接口返回 200，但数据库中没有记录，用户感知为提交成功但实际未生效。
处理：通过 Nginx 日志、数据库记录、应用日志进行交叉比对，定位到 14:14 左右 AI-UDS 网关调用 401 Unauthorized。
结果：明确问题根因为外部网关认证异常影响反馈主流程，同时接口返回语义未正确表达业务失败。

6. 外部访问日志链路与主业务存在耦合风险

问题：AI-UDS 访问日志网关异常可能影响反馈落库，说明非核心外部依赖存在阻断主业务的风险。
处理：在排查记录中提出将反馈落库与访问日志写入解耦，例如先写主业务，再异步写日志，失败进入补偿或降级。
结果：形成后续优化方向，减少外部日志依赖对核心反馈提交链路的影响。

五、明日计划

继续推进供应交付 MCP Tool 化 Phase 3 设计，重点关注执行类 Tool 的高风险治理、HIL 确认节点、幂等和审计能力。
补充更多查询类、校验类 Tool 的误命中测试集，继续提高 Tool 选择准确率。
优化 Tool Catalog 中 intent examples、negative examples、planning_hint、parameter_hint 等元数据质量。
完善 agent_tool_match_record 的实际记录逻辑，进一步追踪候选 Tool、匹配原因、缺失参数和最终选择结果。
继续验证多 Tool 少步骤 Plan 编排能力，例如“查询订单 → 发放检查 → 结果汇总”的组合场景。
跟进反馈提交线上问题修复方案，确认 AI-UDS token 刷新、401 重试和主业务解耦方案是否进入开发排期。
补充反馈提交问题的复测场景，包括正常提交、token 失效、外部网关不可用、HTTP 200 但业务失败等情况。
继续完善排查手册，将 Nginx、应用日志、数据库、外部网关日志串联为标准化排查流程。

六、总结

今天主要围绕供应交付智能助手平台原生化重构和线上问题排查两条主线展开工作。一方面，完成了 Supply_Delivery_Agent_MCP_Tool_Enhancement_Plan_v2_1 方案制作，并推进 Phase 0、Phase 1、Phase 2 的开发与验收，使旧供应交付 Agent 的 Skill/API 能力逐步映射为 MCP Tool，并验证了 Plan-and-Execute 生成 MCP_TOOL_CALL、调用 MCP Tool、标准化结果和审计落库的完整链路。另一方面，完成了反馈提交“第一次失效，第二次成功”的线上问题排查，定位到 AI-UDS 网关 401 Unauthorized 导致 HTTP 200 假成功和反馈未落库问题，并沉淀了后续修复与监控优化建议。整体来看，今天既推进了 Agent 平台的核心工具化能力，也提升了线上问题定位和工程可观测性的实践经验。

实习日报｜2026-05-27

Wed, 27 May 2026 00:00:00 GMT

一、今日主要工作

围绕智能体管理平台的“Agent 装配工厂”方向，完成从单 Agent Plan-and-Execute 引擎到多 Agent 可配置装配模式的核心改造。
完成 Agent 级模型隔离、MCP Server 绑定、工具权限隔离、装配聚合 API、知识库预留 SPI、Agent 直连 Tool 等关键能力开发。
对后端 Agent 执行链路、MCP Gateway 适配链路、工具权限策略和前端管理页面进行联调与问题修复。
完成数字员工 / Agent 管理从前端 localStorage 模式向后端 API 驱动模式的改造，并新增工具广场页面。
整理《Agent 装配工厂实现方案与攻坚记录》，记录今日核心改造方案、攻坚过程、测试结果和后续规划。

二、核心完成内容

1. 模块开发与功能实现

今天主要围绕 Agent 装配工厂能力进行开发。改造前，系统虽然已有 AgentProfileEntity 和基础 CRUD，但运行时仍偏向单 Agent 模式，核心执行链路实际只能围绕默认 Agent 运行，无法真正支持不同 Agent 的模型、工具、MCP Server 和权限隔离。

本次改造后，Agent 的运行配置从固定代码逻辑逐步调整为数据库驱动的装配模式。一个 Agent 可以由以下能力组合而成：

AgentProfile 主配置；
模型卡绑定；
Local Skill 绑定；
MCP Server 绑定；
MCP Tool 直接绑定；
Agent 级工具权限策略；
知识库绑定预留。

这使得新增 Agent 不再依赖新增 Java 代码，而是可以通过管理端或 API 写入配置完成装配，为后续“Agent 工厂”提供了基础结构。

2. Agent 级模型隔离改造

今天首先解决了不同 Agent 无法使用不同模型的问题。改造前，PlanGenerator、LlmStepExecutor、ResultSynthesizer、LlmSkillSelector、SkillArgumentExtractor 等核心 LLM 调用类都在构造函数中创建单例 ChatClient，导致所有 Agent 共用默认模型配置。

本次新增 AgentChatClientFactory，作为 Agent 模型选择的统一入口。其核心逻辑是：

如果 AgentProfile 绑定了 modelCardId，则读取模型卡中的 baseUrl、apiKey 和 model 信息，创建独立 ChatClient；
如果没有绑定模型卡但存在 modelCode，则复用全局 baseUrl / apiKey，只覆盖模型名；
如果两者都不存在，则回退到默认 ChatClient。

在该过程中，也清理了原有 AgentChatStreamService.resolveModelCard() 中的硬编码 API Key 风险，使模型配置从代码硬编码切换为模型卡驱动。

3. LLM 调用链路级联改造

为了让不同 Agent 的模型配置能够真正传递到执行链路中，今天对多个核心类进行了级联改造。改造涉及：

SkillInvoker 接口增加 agentId 参数；
ResultSynthesizer.synthesize() 增加 profile 参数；
LlmSkillSelector.select() 增加 profile 参数；
SkillArgumentExtractor.extract() 增加 profile 参数；
PlanAndExecuteServiceImpl 负责向后传递 AgentProfile；
SkillMatcher、SkillStepExecutor 等组件同步透传 profile 和 agentId。

这部分改动涉及多个文件的调用链联动，修改过程中按“从外到内逐层改、每改一层立即编译验证”的方式推进，避免一次性大改造成定位困难。

同时修复了 ResultSynthesizer 中一个关键问题：原先 buildPrompt(run) 只读取用户输入，没有拼接 Step 执行结果，导致最终流式回复可能无法使用 Tool 的真实返回结果。本次改造后，执行完成后从 AgentRun 中读取 finalResult 再拼装 prompt，保证最终回复能够基于真实执行结果生成。

4. Agent 级 MCP Server 绑定

今天完成了 Agent 与 MCP Server 的绑定隔离。改造前，mcp_server_config 是全局配置，所有 Agent 默认能看到全部 MCP Server，无法做到“某个 Agent 只能访问特定 MCP Server”。

本次新增 agent_mcp_bind 表，沿用已有 agent_skill_bind 的多对多关联模式，实现 Agent 与 MCP Server 的绑定关系。随后在 McpClientGatewayAdapter.callTool() 中增加 Agent-Server 准入校验：

如果当前调用携带 agentId，则校验该 Agent 是否绑定目标 MCP Server；
如果未绑定，则拒绝调用并提示需要先在 Agent 配置中绑定服务。

同时，为了保证默认 Agent 的兼容性，在启动初始化逻辑中为 Agent ID=1 自动补齐默认 mcp-skill-server 绑定记录，避免历史 E2E 测试因新增准入校验而失败。

5. Agent 级工具权限隔离

今天还完成了 MCP 工具权限策略的 Agent 维度隔离。改造前，mcp_tool_policy 表没有 Agent 维度，一旦某个工具被设置为 DENY，会影响所有 Agent，无法实现不同 Agent 对同一工具的差异化权限控制。

本次在 mcp_tool_policy 表中新增可空的 agent_id 字段：

agent_id IS NULL 表示全局策略，保持向后兼容；
agent_id IS NOT NULL 表示该策略只对指定 Agent 生效。

策略优先级设计为：

Agent 私有 + 精确工具名
  > Agent 私有 + 通配符
  > 全局 + 精确工具名
  > 全局 + 通配符
  > 默认规则

同优先级内遵循：

DENY > APPROVAL > ALLOW

为了验证策略隔离效果，还在 McpToolController 中补充了最小化测试 API，用于查询、创建和删除策略。验证结果包括：

Agent 4 私有 DENY math_add 后，Agent 4 被拒绝；
Agent 1 不受 Agent 4 私有策略影响；
全局 DENY 对所有 Agent 生效；
删除策略后调用恢复。

这说明工具权限隔离已经具备 Agent 粒度的治理能力。

6. 装配聚合 API 与知识库预留

为了支撑前端 Agent 配置页，今天新增了装配聚合端点：

GET /api/ai/v1/agents/{id}/assembly

改造前，前端进入 Agent 配置页需要分别请求 profile、skills、mcpServers、tools、policies 等多个接口，容易出现局部失败导致页面状态不一致的问题。新增聚合接口后，可以一次性返回：

Agent 基本信息；
模型卡信息；
已绑定 Skills；
已绑定 MCP Servers；
MCP Tools；
工具权限策略；
知识库绑定信息。

同时，本次只对知识库能力做接口预留，新增 KnowledgeBaseProvider SPI 和 NoOpKnowledgeBaseProvider 默认实现。后续接入 RAG 时，可以通过实现该 SPI 完成知识库注入，不需要大幅改动当前执行链路。

7. Agent 直连 Tool 链路改造

今天进一步优化了 MCP Tool 的调用路径。原有 MCP Tool 调用需要绕过一层 skill_definition：

Agent → agent_skill_bind → skill_definition → invokeConfig → MCP Tool

在大量 MCP 类型 Skill 中，skill_definition.invokeConfig 实际只是记录 serverCode 和 toolName，容易变成纯转发表。

本次新增 agent_tool_bind 表，让 Agent 可以直接绑定 MCP Tool：

Agent → agent_tool_bind → MCP Tool

同时在 SkillStepExecutor 中实现双路径执行：

如果 SkillMatcher 命中 Local Skill 或原有 Skill，则走原有 Skill 调用路径；
如果 SkillMatcher 未命中，则查询 agent_tool_bind，直接通过 McpClientGatewayAdapter.callTool() 调用 MCP Tool。

为了兼容历史数据，还在启动时自动将已有 MCP Skill 绑定迁移为 Tool 绑定。这样既保留 Local Skill 的扩展能力，又减少 MCP Tool 调用中不必要的中间层。

8. 前端 Agent 工厂相关改造

今天也同步完成了部分前端管理端改造。

首先，将 DigitalEmployeesView.vue 从纯 localStorage 模式改为后端 API 驱动。数字员工与后端 AgentProfile 的字段关系进行了统一映射：

DigitalEmployee.name 对应 agentCode；
DigitalEmployee.title 对应 agentName；
DigitalEmployee.roleDefinition 对应 systemPrompt；
DigitalEmployee.modelCardIds[0] 对应 modelCardId；
DigitalEmployee.reasoningMode 对应 reasoningMode，默认使用 plan_execute。

其次，新增工具广场页面 /tools，左侧展示 MCP Server 目录，右侧展示 Tool 开关勾选，并支持 Agent 下拉切换。用户切换 Agent 后可以刷新对应工具勾选状态，切换 Server 后可以加载对应 Tool 列表。

最后，对模型对话页面做了精简，移除模型选择器，保留 Agent 下拉和当前模型提示。模型选择权交由 Agent 配置决定，避免用户在对话页同时选择 Agent 和模型造成配置冲突。

9. 问题攻坚与修复

今天开发过程中解决了多个联调问题：

Spring AI M7 版本 OpenAiApi 构造函数不匹配
编译发现构造函数参数数量不一致，最终参考已有备份配置，确认需要同时传入 RestClient.Builder 和 WebClient.Builder。
调用链级联改造导致编译失败
通过从入口到内部组件逐层修改和验证，逐步完成 profile / agentId 透传。
默认 Agent 兼容问题
Agent-MCP 绑定校验上线后，默认 Agent 因缺少绑定会被拒绝。通过启动时自动插入默认绑定解决。
前后端响应字段不一致
后端不同接口返回存在 message 和 msg 差异，前端 unwrap() 方法增加兼容处理。
agent_profile 缺少 description 字段
前端表单存在“说明”字段，后端实体缺列。本次补充 description 字段并同步表结构。
Agent 选择器 ID 映射不一致
前端 Agent 下拉和后端查询字段不一致，最终统一使用 agentCode 作为选择 key，与后端 findByAgentCode() 对齐。
Tool 直连路径参数提取缺少 inputSchema
Tool 直连时没有 SkillDefinition，可用 dummySkill 占位。当前通过 SkillArgumentExtractor 的兜底 prompt 实现参数提取，后续可进一步从 mcp_tool_definition.input_schema_json 注入真实 Schema。

10. 测试验证与结果

今天完成了多维度回归测试和联调验证，测试覆盖：

工具注册与发现；
单 Skill 执行路径；
多 Skill 执行路径；
依赖链执行；
闲聊回归；
多 Agent 多模型卡隔离；
硬编码密钥消除；
无效模型卡报错；
MCP Server 绑定 / 解绑准入；
默认 Agent 自动绑定；
工具权限策略；
装配聚合端点；
空 Agent 场景；
知识库桩。

根据今日攻坚记录，累计完成 22 项测试，结果均通过，覆盖后端执行链路、权限隔离、配置聚合和前端联调等关键场景。

三、今日工作产出

完成 Agent 工厂核心装配能力改造，使 Agent 支持模型、Skill、MCP Server、Tool、权限策略和知识库预留的组合配置。
新增 AgentChatClientFactory，支持按 Agent 动态创建 ChatClient，实现不同 Agent 的模型隔离。
清理 AgentChatStreamService 中硬编码模型密钥风险，使模型配置转向模型卡驱动。
新增 agent_mcp_bind，实现 Agent 与 MCP Server 的绑定关系和准入校验。
扩展 mcp_tool_policy.agent_id，实现 Agent 级工具权限隔离。
新增装配聚合接口 /api/ai/v1/agents/{id}/assembly，支撑前端一次性加载 Agent 装配信息。
新增知识库绑定预留实体、Mapper 和 KnowledgeBaseProvider SPI，为后续 RAG 接入预留扩展点。
新增 agent_tool_bind，实现 Agent 直连 MCP Tool，减少 MCP 类型 Skill 对 skill_definition 中间层的依赖。
完成数字员工管理页从 localStorage 到后端 API 驱动的改造。
新增工具广场页面 /tools，支持按 Agent 和 MCP Server 查看 / 勾选工具。
完成 22 项测试验证，覆盖工具注册、执行路径、模型隔离、MCP Server 绑定、工具策略、装配聚合和知识库桩。
沉淀《Agent 装配工厂实现方案与攻坚记录》，记录今日改造背景、技术方案、难点处理、测试结果和后续方向。

四、遇到的问题与解决情况

1. 单 Agent 引擎无法支撑 Agent 工厂化装配

问题：系统虽然已有 AgentProfile 和 CRUD，但运行时仍然围绕默认 Agent 运行，不同 Agent 无法真正隔离模型、工具和 MCP Server。
处理：以数据库驱动为原则，新增 Agent-MCP、Agent-Tool、Agent-KB 等绑定关系，并扩展工具权限策略的 Agent 维度。
结果：Agent 从单一执行实例逐步演进为可配置、可装配、可隔离的运行单元。

2. LLM 调用类共用单例 ChatClient

问题：多个核心 LLM 调用类共用构造函数中创建的单例 ChatClient，导致 AgentProfile 中的模型配置无法生效。
处理：新增 AgentChatClientFactory，并对 PlanGenerator、LlmStepExecutor、ResultSynthesizer、LlmSkillSelector、SkillArgumentExtractor 等调用链进行级联改造。
结果：不同 Agent 可以根据模型卡或 modelCode 创建不同 ChatClient，模型隔离能力得到验证。

3. 工具权限缺少 Agent 维度

问题：原有 mcp_tool_policy 是全局策略，对某工具设置 DENY 会影响所有 Agent。
处理：为 mcp_tool_policy 增加可空 agent_id，并设计 Agent 私有策略优先于全局策略的匹配规则。
结果：实现了 Agent 级工具权限隔离，验证了私有 DENY 不影响其他 Agent，全局 DENY 仍可全局生效。

4. 前端配置页请求分散且状态不一致

问题：Agent 配置页需要多次请求 profile、skills、mcpServers、tools、policies 等数据，局部失败容易导致页面状态不一致。
处理：新增 assembly 聚合接口，一次性返回 Agent 装配详情。
结果：前端配置加载链路更清晰，也方便后续扩展知识库、工具策略和更多装配项。

5. Agent 直连 Tool 时参数提取缺少真实 Schema

问题：Tool 直连路径不再经过 SkillDefinition，导致 SkillArgumentExtractor 无法直接拿到 inputSchema。
处理：当前使用 dummySkill 占位并依赖参数提取兜底 prompt；后续计划从 mcp_tool_definition 中读取真实 inputSchema 进一步增强准确性。
结果：当前联调场景可用，后续仍有优化空间。

五、明日计划

继续完善 Agent 工厂配置链路，重点检查前端工具广场、Agent 管理页与后端 assembly API 的数据一致性。
优化 Agent 直连 Tool 的参数提取能力，考虑从 mcp_tool_definition.input_schema_json 注入真实 Schema。
补充工具权限管理前端能力，使 Agent 级 DENY / ALLOW 策略可以可视化配置。
继续验证多 Agent、多模型、多 MCP Server、多 Tool 组合场景，检查隔离边界是否稳定。
评估 PlanGenerator 流式输出方案，优化计划生成阶段的用户等待体验。
继续推进知识库 RAG 真实接入方案，基于当前 KnowledgeBaseProvider SPI 衔接后续向量库和文档摄入。
梳理 Human-in-the-loop 高风险步骤确认节点设计，为后续安全执行能力做准备。

六、总结

今天主要围绕 Agent 装配工厂能力展开开发和攻坚，完成了从单 Agent Plan-and-Execute 引擎向多 Agent 可配置装配平台的关键改造。通过模型隔离、MCP Server 绑定、Agent 级工具权限、装配聚合接口、知识库 SPI、Agent 直连 Tool 和前端管理页改造，平台已经具备更完整的 Agent 工厂化基础能力。今日还完成了 22 项联调与回归测试，验证了模型隔离、工具发现、执行路径、权限隔离和装配聚合等核心链路，为后续工具治理、知识库接入、Human-in-the-loop 和企业级 Agent 装配平台继续演进打下了基础。

实习日报｜2026-05-26｜MCP Server 与 Agent 集成联调

Tue, 26 May 2026 00:00:00 GMT

一、今日主要工作

围绕智能体管理平台的 MCP 工具服务链路，完成 MCP Server 实现与 Agent 集成联调 相关开发工作。
在已完成 Plan-and-Execute Agent 引擎和 MCP Client Gateway 的基础上，补齐 MCP Server 侧能力，使系统具备从 Agent 到 Tool 的完整调用闭环。
实现进程内 MCP Skill Server，通过 HTTP JSON-RPC 暴露企业供应链相关工具，并支持 Gateway 进行工具发现与工具调用。
完成 Agent 工具绑定链路改造，使 Agent 可以通过 agent_tool_bind 直接绑定 MCP Tool，减少对 skill_definition 中间层的依赖。
联调验证 Agent 在单 Skill、多 Skill、依赖链和闲聊场景下的执行效果，并完成模型隔离、MCP Server 绑定、工具权限策略和装配聚合等能力验证。
整理 MCP Server 实现方案与 Agent 集成文档，沉淀整体架构、关键表结构、接口清单、前端页面和后续规划。

二、核心完成内容

1. MCP Server 模块实现

今天重点完成了 mcpserver 模块的实现和联调。该模块定位为进程内 MCP Skill Server，通过 HTTP JSON-RPC 对外暴露工具能力，供 MCP Client Gateway 发现和调用。

本次实现中，MCP Server 主要包含以下核心组件：

McpJsonRpcController：提供 POST /mcp/rpc 端点，支持 initialize、tools/list、tools/call；
McpToolRegistry：作为内存工具注册中心，基于 ConcurrentHashMap 维护工具元数据和调用统计；
ToolAutoRegistration：应用启动时自动注册工具到内存和数据库；
HttpJsonRpcClientAdapter：Gateway 侧 HTTP 适配器，用于连接本地 MCP Server；
CompositeMcpClientAdapter：作为组合适配器，统一本地 HTTP MCP Server 与远程 MCP 连接；
McpServerAutoRegistrar：应用启动时从数据库读取 MCP Server 配置并自动连接；
McpServerConfigServiceBridge：用于跨包访问 MCP Server 配置服务。

通过该模块，系统具备了本地 MCP Server 工具注册、工具发现、工具调用和调用统计能力，为 Agent 调用内部工具提供了服务端支撑。

2. 8 个企业工具注册与发现

今天完成了 MCP Server 侧 8 个工具的注册与同步，覆盖供应链查询、基础计算和依赖链验证等场景。

已注册工具包括：

query_purchase_order：采购订单查询；
query_supplier_payment_status：供应商付款状态查询；
search_mock_file：模拟文件检索；
math_add：加法计算；
math_multiply：乘法计算；
math_divide：除法计算；
get_order_amount：订单金额获取；
calculate_tax：税费计算。

其中，供应链类工具用于模拟企业业务查询场景，数学类工具用于验证单工具、多工具和依赖链调用是否稳定，get_order_amount 与 calculate_tax 则用于验证前后步骤之间的参数传递和结果消费能力。

通过 tools/list，Gateway 可以获取工具名称、描述和 inputSchema；通过 tools/call，Gateway 可以向 MCP Server 发起 JSON-RPC 调用，并获得工具执行结果。

3. MCP Client Gateway 集成

今天完成了 MCP Server 与 MCP Client Gateway 的集成。Gateway 作为统一调用入口，负责完成工具存在性校验、权限策略校验、Schema 参数校验、实际工具调用和审计落库。

核心调用链路如下：

McpClientGatewayAdapter.callTool(serverCode, toolName, args, agentId)
  → 校验 agent_mcp_bind
  → McpToolInvokeService.invoke()
  → findEnabledTool()
  → McpToolPolicyService.checkAllowed()
  → JsonSchemaValidator.validate()
  → McpClientAdapter.callTool()
  → McpAuditLogService.save()

本次联调中，Gateway 能够通过 HTTP 适配器连接本地 MCP Server，并完成工具同步和工具调用。工具同步结果会写入 mcp_tool_definition，工具调用记录会写入 mcp_tool_call_log，其中包含 agentId、callerId、traceId、调用入参、返回结果、耗时和成功状态等信息。

4. Agent 工具绑定链路改造

今天对 Agent 调用 MCP Tool 的链路进行了进一步优化。原有路径是：

Agent → agent_skill_bind → skill_definition → invokeConfig → MCP Tool

该路径中，MCP 类型的 skill_definition 多数情况下只是一个转发表，主要保存 serverCode 和 toolName，实际业务含义较弱。

本次改造后，引入 agent_tool_bind 表，使 Agent 可以直接绑定 MCP Tool：

Agent → agent_tool_bind → MCP Tool

同时，SkillStepExecutor 支持双路径执行：

路径 1：如果 SkillMatcher 命中 skill_definition，继续走原有 LOCAL_BEAN Skill 调用路径；
路径 2：如果 SkillMatcher 未命中，则查询 agent_tool_bind，直接通过 McpClientGatewayAdapter.callTool() 调用 MCP Tool。

通过该改造，Agent 的 MCP 工具调用链路更加直接，减少了不必要的 Skill 壳层，也更符合“Agent 装配工厂”中按 Agent 绑定 Tool 的设计方向。

5. Agent 配置隔离与装配能力

今天继续完善了 Agent 配置隔离能力，使一个 Agent 可以由多类配置共同组装：

agent_profile：Agent 主配置；
agent_skill_bind：Local Skill 绑定；
agent_mcp_bind：MCP Server 绑定；
agent_tool_bind：MCP Tool 直接绑定；
mcp_tool_policy.agent_id：Agent 级工具权限策略；
agent_knowledge_base_bind：知识库绑定预留。

这样可以做到不同 Agent 使用不同模型、不同 MCP Server、不同工具集合和不同工具权限，避免所有 Agent 共用全局工具与全局策略。

在 Plan 生成阶段，系统会将该 Agent 可用的 Tool 列表注入 Prompt，使 LLM 在生成 Plan 时能够选择合适工具。执行时，如果 Plan 中的 suggestedSkillCode 对应 Tool 名称，则可以进入 Tool 直连路径完成远程工具调用。

6. 单 Skill、多 Skill 与依赖链场景验证

今天重点验证了 Agent 与 MCP Server 集成后的多种执行场景。

验证场景包括：

单 Skill 调用：Agent 生成一个包含单个工具调用的 Plan，并正确调用对应 MCP Tool；
多 Skill 调用：Agent 在一个 Plan 中生成多个 SKILL_CALL 步骤，并按顺序调用多个工具；
依赖链调用：前一步工具返回结果被后一步工具使用，例如先获取订单金额，再计算税费；
闲聊回归：普通闲聊不触发工具调用，仍能走正常 LLM 回复路径。

通过这些验证，可以确认 Agent 不仅能够调用单个 MCP Tool，也能在多步骤计划中进行多个工具的顺序调用，并通过 ResultSynthesizer 汇总最终结果。

7. 工具权限策略验证

今天还完成了 Agent 级工具权限策略的验证。当前 mcp_tool_policy 已支持 agent_id 字段：

agent_id IS NULL 表示全局策略；
agent_id IS NOT NULL 表示 Agent 私有策略。

策略优先级为：

Agent 私有精确匹配
  > Agent 私有通配
  > 全局精确匹配
  > 全局通配
  > 默认规则

同优先级内遵循：

DENY > APPROVAL > ALLOW

本次验证覆盖了 Agent 私有策略和全局策略两类场景，确认 Agent 私有 DENY 不会影响其他 Agent，全局 DENY 则会影响所有 Agent。该能力为后续不同 Agent 配置差异化工具权限提供了基础。

8. 管理端与前端页面联动

今天同步梳理并验证了管理端相关页面与后端能力的联动。

当前前端主要涉及以下页面：

/digital-employees：Agent 管理页面，支持 Agent CRUD 和装配详情展示；
/tools：工具广场页面，支持选择 Agent、查看 MCP Server、勾选 Tool 并自动绑定；
/chat：模型对话页面，支持选择 Agent 后进行 SSE 流式对话和 Plan 执行展示；
/models：模型管理页面，用于模型卡配置；
/mcp：MCP 服务配置页面，用于配置 MCP Server。

其中，工具广场是本次 Agent-Tool 绑定链路的重要前端入口。用户可以在页面中选择 Agent，并为其勾选需要开放的 MCP Tool，后端通过 agent_tool_bind 记录绑定关系，使工具配置实时影响 Agent 执行范围。

9. 测试验证与结果

今天完成了多类测试和验证，覆盖工具注册、执行路径、模型隔离、MCP Server 绑定、工具权限策略和装配聚合等模块。

测试结果包括：

工具注册与发现：通过；
单 Skill / 多 Skill / 依赖链 / 闲聊：通过；
多 Agent 多模型卡隔离：通过；
MCP Server 绑定 / 解绑：通过；
Agent 私有策略与全局策略：通过；
装配聚合接口与知识库桩：通过。

累计完成 22 项测试，全部通过。这说明当前 MCP Server 与 Agent 集成链路已经具备较完整的可运行基础。

10. 技术文档沉淀

今天整理了《MCP Server 实现方案与 Agent 集成文档》。文档系统记录了：

管理端、Agent 引擎、MCP Client Gateway、MCP Skill Server 的总体架构；
MCP Server 核心组件和启动流程；
Gateway 调用链路和审计表；
Agent Tool 绑定链路和双路径执行机制；
Agent 配置全景；
Plan 生成中的 Tool 注入方式；
模型隔离机制；
管理端 API 清单；
前端页面说明；
关键数据库表；
测试验证结果；
后续规划。

该文档为后续继续推进 Agent 工厂、工具治理、MCP Server 微服务化和 Human-in-the-loop 提供了清晰参考。

三、今日工作产出

完成进程内 MCP Skill Server 的实现，支持通过 HTTP JSON-RPC 提供 initialize、tools/list、tools/call 能力。
完成 8 个 MCP Tool 注册，包括供应链查询工具、数学验证工具和依赖链测试工具。
完成 MCP Server 与 MCP Client Gateway 的集成，支持工具同步、工具调用、Schema 校验、权限策略和审计落库。
完成 Agent 直连 MCP Tool 的调用链路改造，引入 agent_tool_bind 作为核心绑定表。
完成 SkillStepExecutor 双路径执行机制，使 Local Skill 与 MCP Tool 直连路径可以共存。
完成 Agent 可用 Tool 列表注入 Plan Prompt，使 PlanGenerator 能基于当前 Agent 绑定的工具生成执行计划。
完成单 Skill、多 Skill、依赖链和闲聊场景验证。
完成 Agent 级 MCP Server 绑定和工具权限策略验证。
完成管理端工具广场、Agent 管理、模型对话等前端页面与后端装配能力的联动梳理。
沉淀《MCP Server 实现方案与 Agent 集成文档》，记录整体架构、核心组件、数据库表、接口清单和验证结果。

四、遇到的问题与解决情况

1. MCP Server 与 Gateway 需要统一协议适配

问题：MCP Server 在项目中采用进程内 HTTP JSON-RPC 实现，而 Gateway 原先主要面向 MCP Client Adapter 统一调用，需要适配本地 HTTP JSON-RPC 调用方式。
处理：实现 HttpJsonRpcClientAdapter，并通过 CompositeMcpClientAdapter 组合本地 HTTP 适配器与其他远程 MCP 连接。
结果：Gateway 能够正常调用进程内 MCP Server，实现工具发现与工具调用。

2. MCP Tool 不应全部通过 skill_definition 转发

问题：原有 MCP Tool 调用需要通过 skill_definition 壳层间接转发，导致链路冗余，Tool 管理也不够直观。
处理：新增 agent_tool_bind，让 Agent 可以直接绑定 MCP Tool，并在执行时走 Tool 直连路径。
结果：MCP Tool 调用链路更简洁，前端工具广场也可以直接围绕 Tool 做配置。

3. 多 Skill 与依赖链需要验证执行稳定性

问题：单个工具调用不能证明 Agent 具备复杂任务执行能力，需要验证多个工具按 Plan 顺序执行以及前后步骤结果传递。
处理：设计单 Skill、多 Skill、依赖链和闲聊回归场景进行测试。
结果：相关场景均通过，说明当前 Plan-and-Execute 链路具备基础多工具编排能力。

4. 不同 Agent 的工具权限需要隔离

问题：如果工具策略只按全局维度控制，会导致一个 Agent 的限制影响其他 Agent。
处理：通过 mcp_tool_policy.agent_id 支持 Agent 私有策略，并在 Gateway 调用前进行优先级策略匹配。
结果：验证了 Agent 私有策略与全局策略可以共存，且优先级符合预期。

5. 前端工具配置需要与后端绑定关系一致

问题：工具广场页面需要实时反映当前 Agent 的 Tool 绑定状态，否则容易出现前端显示与后端执行范围不一致。
处理：通过 Agent 下拉、MCP Server 切换和 Tool 勾选机制，将前端操作直接映射到 agent_tool_bind。
结果：工具配置链路更清晰，Agent 的可用工具范围可以通过页面直观管理。

五、明日计划

继续完善工具广场页面，优化 Agent 切换、Server 切换和 Tool 勾选状态的刷新体验。
补充更多 MCP Tool 的异常测试，包括参数缺失、Schema 校验失败、工具不存在和策略拒绝场景。
优化 PlanGenerator 中可用 Tool 列表的描述质量，提高多工具计划生成准确率。
完善 Agent、Gateway、MCP Server 三侧 traceId / requestId 串联，提升问题排查效率。
继续推进工具权限管理前端能力，使 Agent 私有 DENY / ALLOW 策略可视化配置。
评估 MCP Server 后续独立微服务部署方案，减少进程内耦合。
结合知识库绑定预留能力，后续继续推进 RAG 真实接入和 Plan 上下文增强。

六、总结

今天主要围绕 MCP Server 实现与 Agent 集成展开开发和联调工作，完成了进程内 MCP Skill Server、8 个工具注册、Gateway 调用适配、Agent 直连 Tool、工具权限策略、前端工具配置和多场景测试验证。通过今天的工作，平台进一步打通了从管理端配置 Agent，到 Agent 生成计划，再到 Gateway 调用 MCP Server 工具并汇总结果的完整链路，为后续建设更完善的 Agent 装配工厂、工具治理平台和企业级 MCP Server 能力奠定了基础。

实习日报｜2026-05-22

Fri, 22 May 2026 00:00:00 GMT

一、今日主要工作

围绕智能体管理平台的核心执行能力，完成 Plan-and-Execute Agent 引擎 的 MVP 主体开发。
基于 Spring AI 思路，梳理并实现 Agent 从用户输入到计划生成、步骤执行、Skill 调用、结果汇总和执行轨迹记录的主链路。
完成 Agent 执行相关的领域实体、状态枚举、Mapper、配置初始化、应用服务、Planner、Executor、Skill 调用和 API 层开发。
完成管理端桥接工作，将 plan_execute 推理模式接入现有对话流，使前端可通过 Agent 选择器进入 Plan-and-Execute 执行链路。
梳理并沉淀《Spring AI 通用 Agent 平台 MVP 技术实施方案》和《Agent 工厂模块状态与后续规划》，记录当前模块完成情况、已验证能力、已知问题和后续开发路线。

二、核心完成内容

1. 模块开发与功能实现

今天的主要开发工作集中在 com.sangfor.agent.planexecute 模块。该模块是智能体管理平台的核心执行引擎，目标是让系统能够根据用户自然语言请求自动生成执行计划，并按照计划逐步调用 LLM、Local Skill 或 MCP Skill 完成任务。

本次开发重点围绕以下主链路展开：

AgentRunService
  → PlanGenerator
  → PlanAndExecuteService
  → StepExecutor
  → SkillMatcher
  → SkillInvoker
  → ResultSynthesizer

通过该链路，系统可以完成如下流程：

接收用户输入和 Agent 配置；
创建一次 AgentRun 执行记录；
由 PlanGenerator 调用 LLM 生成结构化 Plan；
保存 Plan 和 PlanStep；
按 step_index 顺序执行每个 Step；
根据 Step 类型选择 LLM 执行或 Skill 调用；
记录工具调用和执行过程；
汇总所有步骤结果，生成最终回复。

相比前一天完成的 MCP Client Gateway，今天的工作进一步向上推进到了 Agent 执行层，使平台从“具备工具接入能力”进入到“具备计划生成与执行内核”的阶段。

2. 领域模型与数据持久化开发

今天完成了 Plan-and-Execute Agent 引擎相关的基础实体和数据库结构设计与开发，主要包括：

AgentProfileEntity：描述 Agent 基础配置；
AgentRunEntity：记录一次 Agent 执行过程；
AgentPlanEntity：记录一次任务规划；
AgentPlanStepEntity：记录计划中的具体执行步骤；
SkillDefinitionEntity：描述可调用 Skill；
AgentSkillBindEntity：维护 Agent 与 Skill 的绑定关系；
ToolCallRecordEntity：记录 Skill / Tool 调用日志。

同时完成了对应的状态枚举和模型对象，包括 RunStatus、PlanStatus、StepStatus、StepType、ToolCallStatus、SkillInvokeType、AgentRunResult、StepExecuteResult、SkillMetadata、SkillInvokeResult、PlanGenerateRequest 和 PlanStepResult。

这些基础结构为 Agent 执行过程中的状态流转、计划持久化、步骤追踪和调用审计提供了数据支撑。

3. Plan 生成与解析能力开发

今天完成了 Planner 层核心组件开发，主要包括：

PlanGenerator；
PlanPromptBuilder；
PlanParser；
PlanFallbackFactory。

其中，PlanGenerator 负责根据用户输入、Agent 配置和可用 Skill 列表生成结构化执行计划；PlanPromptBuilder 负责构造计划生成 Prompt；PlanParser 负责解析 LLM 返回的 JSON 计划；PlanFallbackFactory 负责在解析失败时生成兜底计划。

在设计上，MVP 阶段要求 Plan 的步骤数量控制在 3 到 6 步，并将 Step 类型简化为以下几类：

INTENT_ANALYSIS：意图理解；
PARAM_EXTRACT：参数提取；
SKILL_CALL：调用 Skill；
LLM_PROCESS：纯 LLM 处理；
FINAL_RESPONSE：最终回复生成。

同时，为了提高计划生成的稳定性，PlanParser 中考虑了 JSON 解析容错逻辑，包括去除 Markdown 代码块、处理多余解释文字、校验 steps 是否为空、校验 stepIndex 是否连续、校验 stepType 是否在枚举范围内等。

4. Step 执行链路开发

今天完成了 Step 执行相关组件开发，主要包括：

StepExecutor；
DefaultStepExecutor；
LlmStepExecutor；
SkillStepExecutor；
StepContextBuilder。

其中，DefaultStepExecutor 作为统一入口，根据 Step 类型决定交给 LLM 执行器还是 Skill 执行器：

对于 INTENT_ANALYSIS、PARAM_EXTRACT、LLM_PROCESS、FINAL_RESPONSE 等类型，由 LlmStepExecutor 执行；
对于 SKILL_CALL 类型，由 SkillStepExecutor 执行。

LlmStepExecutor 的职责是基于用户原始请求、当前 Plan、已完成步骤结果和当前 Step 目标构造上下文，并调用 LLM 完成当前步骤。SkillStepExecutor 则进一步拆分为 Skill 匹配、参数生成、Skill 调用和调用日志记录几个环节。

这种设计保证每个 Step 只完成当前阶段任务，避免模型在单个步骤中越权执行后续任务，也让整体执行链路更加可追踪。

5. Skill 调用与 MCP Gateway 适配

今天完成了 Agent Skill 调用体系的开发，主要包括：

SkillInvoker 接口；
DefaultSkillInvoker；
LocalSkillInvoker；
McpSkillInvoker；
LocalSkillHandler；
SkillMatcher；
LlmSkillSelector；
SkillArgumentExtractor；
McpClientGatewayAdapter；
McpInvokeConfig。

MVP 阶段的 Skill 调用分为两类：

LOCAL_BEAN：调用本地 Java Skill；
MCP：通过已完成的 MCP Client Gateway 调用外部 MCP Tool。

其中，McpSkillInvoker 通过 McpClientGatewayAdapter 对接前一天完成的 MCP Client Gateway，实现从 Agent Step 到外部 MCP Tool 的适配路径。这样可以复用已有 MCP Gateway 的连接管理、工具调用、参数校验和审计能力，避免 Agent 层直接依赖 MCP SDK。

当前 MCP 类型 Skill 的适配结构已经完成，但文档中也明确记录：MCP 类型 Skill 全链路仍需要后续进一步实测。

6. 管理端桥接与 SSE 流式能力接入

除 Agent 后端执行引擎外，今天还完成了部分管理端桥接工作，使 Plan-and-Execute Agent 能够接入现有管理端对话流。

主要改动包括：

在 AiAdminChatStreamService 中检测 reasoningMode=plan_execute，并路由到 AgentChatStreamService；
通过 AgentConfigController 提供 /api/ai/v1/agents 相关 Agent 配置 API；
在 AgentChatStreamService 中实现心跳、StepEventListener 和 OpenAI 原生流式输出；
在安全配置中放开 /api/ai/v1/**、/api/mcp/**、/api/agent-runs/** 等路径；
在主应用入口中补充 com.sangfor.agent 相关扫描；
扩展 AgentProfileEntity，增加 icon、category、reasoningMode、modelCardId、published、greeting 等字段；
在前端 ModelChatView 中加入 Agent 选择器，并完成基础 Vue 响应式接入。

当前已实现的 SSE 事件包括：

run_created；
plan_created；
step_started；
step_completed；
message；
done。

这使得 Plan-and-Execute 执行过程不仅能在后端运行，也可以逐步接入前端交互体验。

7. 执行轨迹与可观测能力

今天还完成了 Agent 执行轨迹相关能力开发。系统可以将 Agent 执行过程中的核心信息落库，包括：

agent_run：记录一次执行；
agent_plan：记录生成的计划；
agent_plan_step：记录每个步骤的执行状态和输出；
agent_tool_call_record：记录 Skill / Tool 调用过程。

根据开发进度文档，目前已验证的能力包括：

Agent 管理 CRUD；
数字人配置落库；
Plan 生成；
Step 顺序执行；
Plan / Step SSE 实时推送；
最终回复 OpenAI 原生流式输出；
Plan 解析容错与兜底计划；
执行轨迹落库。

这部分能力为后续排查问题、查看运行过程、分析 Agent 执行质量提供了基础。

8. 技术文档与开发进度沉淀

今天在开发过程中同步整理了两份重要文档：

《Spring AI 通用 Agent 平台 MVP 技术实施方案》
该文档明确了 MVP 的目标、边界、核心架构、执行流程、Plan-and-Execute 设计、Skill 调用机制、MCP Gateway 接入方式、数据库设计、接口设计、状态流转、开发顺序和后续扩展方向。
《Agent 工厂模块状态与后续规划》
该文档记录了截至 2026-05-22 的模块状态，包括 MCP Client Gateway、Plan-and-Execute Agent 引擎和管理端桥接的完成情况，同时梳理了已验证能力、已知问题、后续任务和关键文件索引。

这两份文档既是当天开发成果的沉淀，也为后续继续推进前端优化、MCP Skill 实测、本地 Mock Skill、集成测试和 Human-in-the-loop 等能力提供了明确路线。

三、今日工作产出

完成 Plan-and-Execute Agent 引擎 MVP 主体开发，形成从用户输入到计划生成、步骤执行、Skill 调用和结果汇总的执行闭环。
完成 Agent 相关领域实体、状态枚举、Mapper、配置初始化和数据表设计，为执行轨迹落库提供基础。
完成 Planner 层能力，包括 PlanGenerator、PlanPromptBuilder、PlanParser 和 PlanFallbackFactory。
完成 Executor 层能力，包括 StepExecutor、LlmStepExecutor、SkillStepExecutor 和 StepContextBuilder。
完成 Skill 调用体系，包括 LocalSkillInvoker、McpSkillInvoker、SkillMatcher、SkillArgumentExtractor 和 MCP Gateway 适配组件。
完成管理端桥接，使 reasoningMode=plan_execute 的对话请求可以进入 AgentChatStreamService 执行链路。
完成 Agent 配置 API、SSE 状态事件推送、执行轨迹落库等能力。
沉淀《Spring AI 通用 Agent 平台 MVP 技术实施方案》和《Agent 工厂模块状态与后续规划》，形成可复用的开发和交接资料。

四、遇到的问题与解决情况

1. Agent MVP 范围容易过大

问题：Plan-and-Execute Agent 涉及计划生成、步骤执行、Skill 调用、MCP 适配、流式输出、状态追踪等多个模块，如果一次性做完整能力，开发范围容易失控。
处理：在技术方案中明确 MVP 边界，第一阶段只聚焦执行闭环，不做复杂多 Agent 协作、不做正式图编排、不做复杂 ReAct 无限循环、不做复杂 Human-in-the-loop。
结果：开发主线聚焦到 AgentRunService → PlanGenerator → PlanAndExecuteService → StepExecutor → SkillInvoker → ResultSynthesizer 的核心链路，降低了第一版实现复杂度。

2. LLM 生成 Plan 可能存在格式不稳定问题

问题：PlanGenerator 依赖 LLM 输出结构化 JSON，实际使用中可能出现 Markdown 包装、额外解释文字、字段缺失或 stepType 不规范等问题。
处理：设计 PlanParser 容错策略，并加入 PlanFallbackFactory，在解析失败时生成默认兜底计划。
结果：提升了 Plan 生成链路的鲁棒性，避免单次 LLM 输出异常导致整个 Agent 执行失败。

3. 前端流式渲染仍需优化

问题：当前前端流式渲染不够流畅，存在 Vue 响应式批处理与 SSE 逐 token 推送之间不完全匹配的问题。
处理：已在模块状态文档中将其列为 P0 问题，后续计划采用 requestAnimationFrame 或微小延迟优化逐 token 渲染。
结果：问题已明确定位并进入后续优化计划，不影响当前后端 Agent 主链路继续推进。

4. MCP 类型 Skill 仍需全链路实测

问题：MCP Skill 适配组件已经完成，但从 Agent 生成 Plan 到匹配 MCP Skill，再通过 MCP Client Gateway 调用外部工具的全链路仍需进一步验证。
处理：当前先完成 McpSkillInvoker 和 McpClientGatewayAdapter 结构开发，将 MCP 对接测试列入后续 P1 任务。
结果：当前架构已具备 MCP 接入路径，后续可通过注册 MCP Server、同步工具、绑定 Agent、对话调用进行完整验证。

五、今日个人理解

今天的开发让我对 Agent 装配工厂的核心执行层有了更清晰的认识。前一天完成 MCP Client Gateway 后，平台已经具备了“工具接入底座”；今天完成 Plan-and-Execute Agent 引擎后，平台进一步具备了“任务规划与执行内核”。

我理解的 Plan-and-Execute Agent 不是简单地让大模型直接回答用户，而是先把用户请求拆解成可追踪的计划，再按步骤执行。每个 Step 都有明确的目标、类型、状态和输出，Skill 调用也会被记录到 ToolCallRecord 中。这样一来，Agent 的执行过程就不再是黑盒，而是可以查看、追踪和后续优化的工程链路。

同时，我也进一步认识到 MVP 阶段的关键不是追求复杂能力，而是先跑通主链路。只要 Agent 能完成 Plan 生成、Step 顺序执行、Skill 调用、结果汇总和轨迹落库，后续再扩展 Human-in-the-loop、失败重试、知识库增强、多 Agent 协作和图编排才有基础。

六、后续待明确问题

MCP 类型 Skill 是否能在真实外部 MCP Server 场景下完整跑通；
Local Mock Skill 是否需要补充标准测试场景；
前端 SSE 流式渲染如何进一步优化；
Qwen 推理模型是否需要关闭 thinking 模式，避免 token 集中输出；
Step 输出中嵌套 JSON / Markdown 包装如何进一步清洗；
PlanParser 容错测试和全链路集成测试是否需要补齐；
后续是否需要在 Plan 生成阶段也输出 LLM 思考过程；
Human-in-the-loop 节点应在什么版本中接入；
数字人广场、Agent 模板复制、版本管理等管理端能力如何安排开发优先级。

七、明日/后续计划

优先优化前端流式渲染，使 Step 状态和最终回复能够更平滑地展示给用户。
在 OpenAI 兼容流式客户端中评估关闭 Qwen thinking 模式，减少 content 阶段 token 集中到达的问题。
补充 step_started 事件前端渲染，在等待过程中展示“正在执行”状态，提升交互反馈。
实现本地 Mock Skill，例如 MockPaymentStatusHandler，用于验证 LOCAL_BEAN Skill 调用链路。
推进 MCP 对接测试，完成注册 MCP Server、工具发现、绑定 Agent、对话中调用的完整验证。
补充 PlanParser 容错测试和 Plan-and-Execute 全链路集成测试。
继续完善模块状态文档，记录后续问题修复和能力扩展情况。

八、今日总结

今天主要围绕智能体管理平台的 Plan-and-Execute Agent 引擎展开开发，完成了 Agent 执行入口、计划生成、步骤执行、Skill 调用、MCP Gateway 适配、SSE 状态推送和执行轨迹落库等核心能力。通过今天的工作，平台从“具备 MCP 工具接入能力”进一步升级为“具备 Agent 执行内核”，为后续完善 Skill 实测、前端流式体验、Human-in-the-loop 和多 Agent 扩展奠定了基础。

实习日报｜2026-05-21

Thu, 21 May 2026 00:00:00 GMT

一、今日概况

今天主要围绕智能体管理平台中的 MCP Client Gateway 模块展开开发工作。开发过程中，我主要采用 Claude Code 进行 vibe coding 式敏捷开发，通过“需求拆解—代码生成—局部验证—问题修正—文档沉淀”的方式推进模块落地，并在开发完成后整理了技术文档、接口文档、测试方案和测试报告。

除模块开发外，我还结合今天的 AI coding 实践，总结了一套 Claude / Agent 上下文窗口管理方法论，用于解决大项目开发过程中上下文过长、任务边界发散、历史信息污染和跨窗口续接困难等问题。

二、今日主要工作

使用 Claude Code 进行 vibe coding 敏捷开发，推进 MCP Client Gateway 模块的核心代码实现。
完成 MCP Client Gateway 的模块设计、接口设计、测试方案和测试报告沉淀。
围绕 MCP Server 注册、连接测试、工具发现、工具同步、工具调用、健康检查、调用审计等能力进行开发与验证。
基于本地集成测试完成最小可用链路验证，测试覆盖 Server 注册、STDIO 连接握手、工具同步、工具调用和健康检查。
在 AI coding 过程中总结 Claude / Agent 上下文治理方法论，形成针对长任务开发的上下文管理方案。

三、核心完成内容

1. 基于 Claude Code 的 vibe coding 开发实践

今天的代码开发主要采用 Claude Code 辅助完成。我不是简单让 AI 一次性生成完整模块，而是按照敏捷开发的方式，将 MCP Client Gateway 拆成多个可验证的小阶段逐步推进。

整体开发过程大致包括：

先明确当前阶段只做 MCP Client Gateway，不做完整 Agent Planner、不做 MCP Server、不做复杂多轮编排；
将模块拆分为 Server 配置管理、Client 生命周期管理、工具发现、工具调用、策略校验、参数校验、审计日志、健康检查等子任务；
每完成一个小模块后进行局部检查和接口验证；
在功能链路基本跑通后，整理技术文档、接口文档、测试方案和测试报告；
最后通过集成测试验证当前 MVP 链路是否可用。

这种 vibe coding 开发模式提升了今天的开发效率，也让我更清楚地体会到：AI coding 并不是让模型替代开发者直接完成所有代码，而是由我负责把控任务边界、模块拆分、架构取舍和验证标准，AI 负责辅助生成代码、补全结构和加速实现。

2. MCP Client Gateway 模块开发

今天的主要开发内容是 MCP Client Gateway。该模块在智能体管理平台中的定位是“工具接入底座”，用于在完整 Agent 模块尚未搭建完成之前，先独立完成 MCP Client 的连接管理和工具调用能力。

当前阶段模块重点能力包括：

MCP Server 连接配置管理；
MCP Client 初始化与生命周期管理；
外部 MCP Server 工具列表发现；
工具元数据同步和本地缓存；
工具调用统一入口；
调用前参数 Schema 校验；
工具调用策略检查；
调用审计日志记录；
Gateway 整体健康检查；
为后续 Agent Planner、Skill Router、Plan-and-Execute 模块预留标准调用接口。

从平台架构角度看，MCP Client Gateway 并不是完整 Agent 的替代品，而是 Agent 调用外部工具之前的一层标准化网关。后续 Agent 模块可以通过 Gateway 暴露的 REST API 调用工具，不需要直接依赖 MCP SDK，也不需要在每个 Agent 内部重复实现工具连接逻辑。

3. 技术方案与架构沉淀

今天在开发完成后，对 MCP Client Gateway 的整体技术方案进行了文档沉淀。技术文档中明确了模块背景、建设目标、范围边界、技术选型、分层架构、核心流程、数据库设计、REST API 设计、异常处理、可观测性和后续 Agent 接入约定。

当前方案采用 Java 21、Spring Boot 3.3.5、Spring MVC、MCP Java SDK 0.9.0、MyBatis Plus、MySQL/H2、NetworkNT JSON Schema Validator 等技术组合。模块结构按照 controller、application、domain、infrastructure、dto、common 等层次拆分，使代码职责更加清晰。

今天也进一步明确了当前阶段的边界：本阶段重点是完成 MCP Client Gateway，不做完整 Agent Planner，不做 LLM 自动工具选择，不自研 MCP Server，不实现复杂多轮任务编排。这种边界控制可以避免前期开发范围过大，也能让当前模块更聚焦于工具接入和调用治理。

4. 接口设计与文档沉淀

今天整理了 MCP Client Gateway 的接口文档，围绕 /api/mcp 基础路径设计了多类 REST API。

接口主要包括：

MCP Server 管理接口：Server 列表查询、新增配置、更新配置、删除配置、启用/禁用；
连接测试接口：触发 MCP Client 连接和 initialize 握手；
工具发现接口：查询工具列表、查询工具详情、同步指定 Server 工具、同步全部工具；
工具调用接口：支持按 toolId 调用，也支持按 serverCode + toolName 调用；
健康检查接口：查询 Gateway 整体状态和单个 Server 健康状态；
调用日志接口：查询工具调用审计日志。

其中，按 serverCode + toolName 调用工具的接口被设计为后续 Agent 推荐使用方式。这样 Agent 在执行计划步骤时，不需要先感知数据库中的 toolId，而是可以根据工具名称和 Server 编码直接调用 Gateway 统一入口。

接口文档中也统一了响应格式和错误码，包括 Client 未连接、连接失败、工具不存在、工具被策略拒绝、参数不符合 JSON Schema、调用超时等异常场景，为后续前后端联调和问题排查提供了基础。

5. 数据库与调用审计能力设计

今天梳理并沉淀了 MCP Client Gateway 所需的数据库表结构，主要包括：

mcp_server_config：维护 MCP Server 连接配置；
mcp_tool_definition：存储工具元数据、输入 Schema、风险等级等信息；
mcp_tool_call_log：记录每次工具调用的 traceId、入参、出参、耗时、状态和异常信息；
mcp_tool_policy：维护工具调用策略，包括允许、拒绝和审批等状态。

其中，调用审计日志是本模块的重要能力。它可以帮助后续追踪工具调用链路、定位异常问题，并为平台的工具治理、安全控制和后续运维分析提供基础数据。

6. 集成测试与本地验证

今天完成了 MCP Client Gateway 的测试方案和测试报告整理，并进行了本地集成测试验证。测试采用 JUnit 5、Spring Boot Test、MockMvc、H2 内存数据库和 STDIO 子进程 MCP Server。

本次集成测试覆盖 7 个步骤：

注册 STDIO MCP Server；
测试连接并完成 MCP initialize 握手；
同步工具列表；
查询工具列表；
调用 echo 工具；
调用 add 工具；
执行 Gateway 健康检查。

测试结果显示 7 个步骤全部通过，说明当前 MCP Client Gateway 的最小可用链路已经完成本地验证。测试覆盖了 REST API、应用服务层、MCP SDK 适配层、连接注册表、JSON Schema 校验、审计日志和自动建表等关键组件。

需要说明的是，本次测试主要验证 STDIO transport 链路。HTTP/SSE transport 已在技术方案中预留，但仍需要在真实网络环境下继续联调验证。

7. AI coding 上下文治理方法沉淀

除了具体代码开发外，今天我还结合 Claude Code 的实际使用过程，总结了一套 Claude / Agent 上下文治理方法论。

这套方法的核心理解是：上下文治理不是简单压缩聊天记录，而是要把 Agent 工作所需的信息按照生命周期、重要性和使用频率进行分层管理。真正有效的 Agent 不是“什么都记住”，而是“只把当前决策必须依赖的信息放进主上下文”。

我整理的方法中，将上下文拆分为五层：

L1 长期规则层：技术栈、代码规范、架构约束、禁止事项，可放入 CLAUDE.md 或 AGENTS.md；
L2 任务边界层：本轮要做什么、不做什么、完成标准，可放入 docs/ai/current-task.md；
L3 状态进度层：已完成、未完成、下一步，可放入 docs/ai/progress.md；
L4 决策记录层：关键架构决策及原因，可放入 docs/ai/decisions.md；
L5 交接压缩层：跨窗口或 compact 后继续工作的摘要，可放入 docs/ai/handoff-summary.md。

这套方法对今天的 MCP Client Gateway 开发也有直接启发。由于当前模块涉及多个文件、多层架构、接口设计和测试验证，如果不控制上下文，AI coding 很容易出现任务范围扩大、重复读取无关文件、把旧方案当成当前约束等问题。因此，在后续使用 Claude Code 或其他 Agent 工具进行开发时，需要通过 current-task、progress、decisions、handoff 等文件主动管理上下文。

8. 对企业 Agent 平台的启发

今天整理上下文治理方案时，我也进一步联想到我们正在做的智能体管理平台。对于企业级 Agent 装配工厂来说，上下文治理不能只靠提示词临时约束，而应该成为平台能力的一部分。

后续平台可以考虑：

为每个 Agent 维护 Agent Context Registry，记录长期规则、当前任务、已加载 Skill、工具调用摘要、历史摘要和上下文预算；
对 Skill 采用分层加载机制，先加载 Skill Card，再按需加载 Manifest 和 Body；
区分 Profile Memory、Project Memory、Task Memory、Decision Memory、Tool Memory、Error Memory 等不同记忆类型；
对工具调用结果进行摘要化保存，避免大段日志和完整返回结果长期污染主上下文；
在任务切换、模块完成、测试通过、bug 修复、subagent 返回后触发自动压缩或交接摘要更新。

这部分沉淀不仅可以帮助我更高效地使用 Claude Code，也可以为后续设计企业内部 Agent 调度基座提供参考。

四、今日工作产出

完成 MCP Client Gateway 模块的 vibe coding 敏捷开发实践，推进工具接入底座的核心能力实现。
完成并沉淀《MCP Client Gateway 技术文档 v1.1》，系统梳理模块背景、范围边界、架构设计、核心流程、数据库设计、接口设计和后续计划。
完成《MCP Client Gateway 接口文档》，明确 /api/mcp 下的 Server 管理、工具发现、工具调用、健康检查和调用日志等接口。
完成《MCP Client Gateway 测试方案》，设计基于 JUnit 5、Spring Boot Test、MockMvc、H2 和 STDIO MCP Server 的集成测试流程。
完成《MCP Client Gateway 集成测试报告》，记录 7 步全链路测试结果，验证 Server 注册、连接测试、工具同步、工具调用和健康检查均通过。
完成《Claude / Agent 上下文治理方法论》文档，总结长任务开发中的上下文分层管理、任务交接、compact、subagent、slash command、skill 和 hooks 使用边界。
将 AI coding 的工程实践从“代码生成”进一步沉淀为“开发方法 + 上下文管理 + 文档交付”的组合产出。

五、遇到的问题与解决情况

1. Agent 模块尚未完成，MCP 能力需要先行建设

问题：当前智能体管理平台中的完整 Agent 模块尚未搭建，但项目需要先具备 MCP Client 的部署和工具接入能力。
处理：将 MCP Client 抽象为独立的 MCP Client Gateway，不依赖完整 Agent 推理流程，先完成工具连接、发现、调用和审计能力。
结果：形成了一个可独立运行、可本地验证、可供后续 Agent 调用的工具接入底座。

2. vibe coding 需要避免任务范围发散

问题：使用 Claude Code 进行 AI coding 时，如果任务边界不清晰，模型容易把 MCP Client Gateway 扩展成完整 Agent、Skill 装配或 MCP Server 开发。
处理：在开发过程中明确当前阶段只做 MCP Client Gateway，并通过文档记录“不做事项”和模块边界。
结果：开发过程更聚焦，避免了过早引入 Agent Planner、LLM 自动工具选择和复杂任务编排。

3. MCP 工具调用需要统一治理

问题：如果后续 Agent 或业务模块直接调用 MCP SDK，容易造成工具调用分散、权限控制不统一、审计日志缺失等问题。
处理：设计 Gateway 统一 REST API，由 McpToolInvokeService 统一完成策略检查、参数校验、工具调用和审计落库。
结果：后续 Agent 可以通过统一接口调用工具，工具权限、参数校验和调用日志都可以在 Gateway 层集中处理。

4. 传输方式验证范围有限

问题：当前集成测试主要验证了 STDIO transport，HTTP/SSE transport 仍需要在真实网络环境下进一步验证。
处理：在技术文档和测试方案中明确当前验证范围，将 HTTP/SSE 联调作为后续版本计划。
结果：当前版本先保证 STDIO 最小链路稳定可用，同时为后续远程 MCP Server 接入预留扩展空间。

5. 大项目 AI coding 存在上下文污染风险

问题：在长任务开发中，Claude Code 会持续加载对话历史、文件内容、命令输出、工具信息和阶段性尝试，容易导致上下文窗口变大、模型注意力被稀释、旧信息干扰当前任务。
处理：总结上下文治理方法，将长期规则、当前任务、阶段进度、架构决策和交接摘要分别放入不同文档，并使用 /clear、/compact、/context、subagent、slash command、skill 等机制控制上下文。
结果：形成了一套可复用的 AI coding 上下文管理方案，可用于后续 MCP Gateway、Agent 调度基座以及其他长任务开发场景。

六、今日个人理解

今天最大的收获是，我对 AI coding 在真实项目开发中的使用方式有了更清晰的认识。Claude Code 可以显著提升开发效率，但前提是开发者要具备清晰的架构判断、任务拆解能力和验证意识。不能把 vibe coding 理解成“让 AI 随意写代码”，而是要把它变成一种有边界、有节奏、有验证的敏捷开发方式。

在 MCP Client Gateway 开发中，我的角色主要是明确模块定位、控制开发边界、拆分任务步骤、判断架构是否合理，并在开发完成后沉淀接口文档和测试文档。Claude Code 则帮助我加快代码生成、结构补全和局部实现。这样的协作模式比传统手写代码更快，但也更要求我对模块整体逻辑有把控能力。

同时，我也认识到，大项目中的 AI coding 很容易受到上下文窗口影响。如果上下文里混入太多旧任务、无关文件、失败日志或过期设计，Agent 的输出质量会下降。因此，上下文治理本身应该成为使用 AI coding 的重要工程能力。后续无论是继续开发 MCP Gateway，还是建设智能体管理平台，都需要把 current-task、progress、decisions、handoff 等文档机制纳入开发流程。

七、后续待明确问题

HTTP/SSE transport 在真实网络环境中的连接和握手情况；
MCP Client Gateway 后续是否需要接入 Swagger/Knife4j 生成在线接口文档；
工具策略中的 DENY、APPROVAL 场景是否需要补充更完整的测试用例；
高风险工具是否需要接入更正式的人工审批流程；
Gateway 与后续 Agent Planner、Skill Router 的接口契约是否需要进一步固化；
是否需要增加启动时自动连接 enabled Server 和定时健康检查机制；
是否需要接入 Actuator、Micrometer、Prometheus 等运维观测能力；
Claude Code 上下文治理方法是否可以沉淀为项目级 CLAUDE.md、docs/ai/* 或团队内部规范；
是否可以将 context governance 做成 Claude Code skill 或 slash command，减少后续手动维护成本。

八、明日/后续计划

继续完善 MCP Client Gateway 模块，重点关注 HTTP/SSE transport 的联调验证。
根据今天的接口文档，进一步检查 REST API 入参、出参和错误码是否满足后续前端与 Agent 调用需求。
补充工具策略相关测试，尤其是 DENY、APPROVAL、高风险工具拒绝等场景。
结合智能体管理平台后续 Agent 架构，继续梳理 Gateway 与 Planner、Skill Router、Plan-and-Execute 模块之间的调用边界。
将今天沉淀的技术文档、接口文档、测试方案、测试报告和上下文治理方案进一步整理到项目文档目录中，方便团队复用。
尝试在后续 Claude Code 开发中实践上下文治理方法，例如建立 current-task、progress、decisions、handoff-summary 等文件，减少长任务开发中的上下文混乱。

九、今日总结

今天主要围绕智能体管理平台中的 MCP Client Gateway 模块展开工作，并通过 Claude Code vibe coding 的方式完成了较高强度的敏捷开发。开发完成后，我整理了技术文档、接口文档、测试方案和测试报告，并通过本地集成测试验证了 Server 注册、连接握手、工具同步、工具调用和健康检查等核心链路。

除此之外，我还结合 AI coding 过程总结了 Claude / Agent 上下文治理方法论，认识到大项目中使用 Agent 开发不仅要关注代码生成效率，也要关注任务边界、上下文质量、阶段进度和跨窗口交接。今天的工作既推进了 MCP Client Gateway 模块建设，也沉淀了后续持续使用 AI coding 的工程方法。

实习日报｜2026-05-20

Wed, 20 May 2026 00:00:00 GMT

1. 今日概况

今天主要围绕智能体管理平台的代码结构理解、知识库模块开发和开发工具部署三部分展开。上午，我重点阅读并梳理了项目源码，进一步明确了前后端架构、当前开发进度以及自己后续需要负责的模块。下午和晚上，我与同事一起推进知识库模块的 MVP 链路开发，并完成了 Redis 集群、MySQL 数据库等资源配置接入；此外，还在隔离 VDI 环境中完成了 Claude Code 的本地部署，并向同事介绍了部署方法。

2. 今日完成工作

2.1 项目源码与架构理解

上午，我深入阅读了当前项目的源码，对项目整体结构、前后端实现方式以及现有代码组织有了更清晰的认识。通过代码梳理，我了解到当前项目仍处于从 0 到 1 搭建阶段，前端已经有一个初步 Demo，但后端功能还没有完全建设起来。

目前平台前端主要采用 Vue 相关的 Web 前端结构进行开发，已有页面更偏向展示和原型验证，部分数据和交互逻辑仍然是前端写死的形式。后续需要逐步补充后端服务能力，使平台从原型页面过渡到真正可用的智能体管理平台。

通过上午的代码阅读，我进一步明确了当前整体开发进度，也对自己接下来需要参与的模块和任务有了更加充分的了解。

2.2 明确平台从 0 到 1 的建设状态

今天我进一步认识到，当前项目并不是在一个已经完善的系统上做简单功能补充，而是在建设一个从 0 到 1 的智能体管理平台。前两天我已经理解到项目目标是做一个 Agent 基座或智能体装配工厂，今天通过源码和开发进度梳理，我更加明确了这个平台目前仍处在基础能力搭建阶段。

目前的重点不是直接完成一个成熟 Agent，而是先搭建平台底座，包括前端管理页面、后端服务能力、资源配置、知识库模块以及后续 Agent 装配所需的基础结构。这也让我对后续工作的优先级有了更清楚的判断：需要先把基础链路跑通，再逐步完善 Agent 能力。

2.3 知识库模块需求讨论

下午，我和同事一起讨论了业务方提出的新需求：在智能体管理平台中增加知识库模块，用于后续增强 Agent 的回答和业务理解能力。虽然当前智能体工厂还没有形成一个完整可用的 Agent，但业务方希望先把知识库插件能力建设起来，为后续 Agent 接入和增强做准备。

这一需求说明，知识库模块并不是一个孤立功能，而是未来 Agent 能力的重要支撑。后续智能体在处理业务问题时，可以基于知识库进行信息检索和上下文增强，从而减少纯模型回答的不确定性，提高回答依据和业务适配性。

2.4 资源申请与项目配置接入

在开发知识库模块过程中，涉及服务器连接、资源申请和权限访问等问题。下午我们对服务器进行了连接尝试，并向上级部门申请了项目所需的相关资源。

本次明确接入的资源主要包括：

Redis 集群；
MySQL 数据库。

申请完成后，我们将相关资源配置到项目中，为后续知识库模块的数据存储、状态管理和服务调用提供基础支撑。这个过程也让我进一步理解到，实际企业项目开发不仅包括代码实现，还涉及资源权限、环境配置和跨部门资源协调。

2.5 知识库 MVP 链路开发

下午和晚上，我与同事一起推进了知识库模块的 MVP 版本开发。当前目标是先实现一个最小可用链路，保证知识库最核心的流程能够跑通，再逐步补全查询和增强能力。

今天已推进的核心链路包括：

新建知识块；
将知识语料写入项目流程；
对知识语料进行切片处理；
对切片后的内容进行 embedding；
将处理后的语料上传到 Milvus/向量检索侧；
通过项目路由完成知识写入相关流程；
使用 API 调试工具对查询接口进行初步尝试。

目前知识入库相关流程已经基本完成，但知识库查询功能还没有正式开发完成。查询部分今天主要通过 API 调试工具进行尝试，后续还需要在项目中补全正式查询接口和前后端联动逻辑。

2.6 Claude Code 离线环境部署

除了知识库模块开发外，我今天还完成了领导安排的一个额外任务：在本地隔离 VDI 虚拟机环境中部署 Claude Code，并将部署方法介绍给其他同事。

这个任务的难点在于公司内部环境对外网访问存在限制，不能像普通个人电脑一样直接连接外部官网或完成完整在线登录。因此，我没有采用 Cloudflare Tunnel 等外部穿透方式，而是通过修改 Claude Code 的配置文件来解决部署问题。

具体来说，我在 cloudcode.json 配置文件中加入了跳过登录相关配置，使 Claude Code 能够在不连接 Claude 官方 API 或官网登录流程的情况下，在离线或受限网络环境中完成部署。同时，结合 Claude Code Switch 的方式以及跳过登录设置，最终在隔离 VDI 虚拟机上成功完成部署，并配置为调用 DeepSeek 相关模型能力。

完成部署后，我也向同事说明了整体部署思路和关键配置方法，为后续其他同事在相同环境下使用该工具提供了参考。

3. 业务背景理解

3.1 平台定位

当前项目的定位是建设一个智能体管理平台，也可以理解为一个面向业务 Agent 的基础管理平台或装配工厂。它不是单一的智能问答工具，而是要为后续不同业务场景下的 Agent 创建、配置、管理和增强提供统一底座。

今天通过代码阅读和需求讨论，我进一步认识到，平台当前仍处于基础建设阶段，需要先完成前后端架构、后端能力、知识库插件和资源接入等底层能力，后续才能支撑更加完整的 Agent 装配与业务应用。

3.2 当前开发进度

目前平台已有前端 Demo，但后端服务能力还没有完全搭建。前端页面可以表达平台大致形态，但要真正支持智能体管理、知识库接入和 Agent 能力增强，还需要进一步补充后端接口、数据存储、知识处理和查询能力。

因此，当前阶段的开发重点是从“可展示 Demo”向“可运行 MVP”推进。知识库模块就是其中一个重要切入点，它可以先作为平台中的插件能力被建设出来，后续再与 Agent 创建和调用流程结合。

3.3 知识库模块价值

知识库模块的建设是为了增强 Agent 的业务理解和回答依据。对于企业内部场景来说，Agent 不能只依赖模型本身的通用能力，还需要结合企业内部文档、业务规则、操作说明和系统知识。

通过知识库模块，后续 Agent 可以在回答问题或执行任务前先检索相关语料，再结合检索结果生成更可靠的响应。这对于后续智能体管理平台的可用性和业务可信度都非常重要。

4. 技术方案理解

4.1 前后端架构理解

今天通过源码阅读，我对项目前后端架构有了初步理解。前端目前主要承担页面展示、用户交互和基础流程入口的作用；后端则需要逐步补充业务逻辑、数据处理、资源访问和知识库相关能力。

目前由于后端能力尚未完全搭建，前端 Demo 中仍存在写死数据和原型化逻辑。后续需要通过后端接口将智能体管理、知识库管理、知识入库、知识查询等能力真正串联起来。

4.2 知识库入库流程

今天开发的知识库 MVP 主要围绕知识入库链路展开。整体流程可以理解为：用户或系统创建知识块后，项目路由接收相关请求，将语料写入系统，并对语料进行切片和 embedding 处理，最后上传到向量检索侧进行存储。

这个流程是后续 RAG 能力的基础。只有先完成知识入库，后续 Agent 才能基于知识库进行检索增强。

4.3 查询流程待完善

当前查询流程还没有完全接入项目代码。今天主要是通过 API 调试工具尝试调用查询接口，验证查询方向和基础可行性。明天或后续需要重点完成查询模块，包括正式查询接口、检索逻辑、返回结果格式，以及与前端页面或 Agent 调用链路的衔接。

查询能力补齐后，知识库 MVP 才能从“只支持入库”进一步发展为“支持入库与检索”的完整最小闭环。

4.4 离线开发工具部署

Claude Code 的离线部署让我进一步理解到，在企业内部受限网络环境中，开发工具的可用性本身也是工程效率的一部分。通过修改配置文件实现跳过登录，并结合内部可访问的代码和模型配置，可以让开发工具在没有完整外网权限的环境中运行起来。

这类部署经验对后续团队效率提升有一定帮助，尤其是在 VDI 虚拟机、内网环境、外网受限的公司开发场景下。

5. 今日个人理解

今天我对项目当前阶段有了更实际的认识。之前更多是在理解“智能体管理平台”或“Agent 基座”这个目标，今天通过阅读源码和参与开发，我意识到项目目前还处在从 0 到 1 的基础搭建阶段。前端已有雏形，但后端能力、知识库能力和 Agent 运行链路仍需要一步步补齐。

我也进一步理解到，知识库模块虽然看起来只是一个插件需求，但它实际上会影响后续 Agent 的核心能力。如果 Agent 要在企业业务中真正可用，就必须能够接入内部知识、检索相关资料，并基于业务上下文进行回答，而不是只依赖模型本身的泛化能力。

另外，今天完成 Claude Code 在隔离环境中的部署，也让我体会到企业开发中环境约束带来的挑战。很多事情在普通网络环境下很简单，但在公司 VDI 和无外网权限环境中，需要通过配置调整和替代方案才能落地。

6. 后续待明确问题

知识库查询接口的具体实现方式；
查询结果返回格式是否需要统一规范；
知识块、知识库、语料切片之间的数据模型关系；
Redis 集群在知识库模块中具体承担缓存、状态还是其他作用；
MySQL 数据库中需要保存哪些知识库元数据；
Milvus/向量检索侧与项目后端之间的接口边界；
前端知识库管理页面是否需要同步调整；
知识库模块后续如何与 Agent 调用链路结合；
Claude Code 离线部署配置是否需要整理成团队内部文档。

7. 明日/后续计划

明天计划优先补齐知识库查询模块，将今天已经完成的知识入库流程继续向查询流程推进，争取形成知识库最小可用闭环。后续需要完成查询接口开发、检索结果返回、项目路由接入以及必要的接口调试。

同时，我还需要继续熟悉当前项目代码结构，尤其是后端尚未完善的部分，明确知识库模块后续如何与智能体管理平台、Agent 创建流程和未来的 RAG 增强能力结合。

如果时间允许，也可以将今天 Claude Code 在隔离 VDI 环境下的部署方法整理成简要说明，方便后续同事复现和使用。

8. 今日总结

今天的工作让我从代码层面、业务需求层面和工程环境层面对项目有了更深入的认识。上午我通过源码阅读明确了项目前后端结构和当前从 0 到 1 的建设状态；下午和晚上，我参与推进了知识库模块 MVP，完成了资源接入和入库链路开发；同时还解决了 Claude Code 在隔离 VDI 环境下的部署问题。整体来看，今天不仅推进了具体功能开发，也帮助我更清楚地理解了智能体管理平台后续建设的技术路径。

实习日报｜2026-05-19

Tue, 19 May 2026 00:00:00 GMT

1. 今日概况

今天上午，我与带教同事对齐了当前项目的新阶段进度，并进一步明确了近期需要推进的代码任务。通过沟通，我对原有智能体管理平台架构中存在的问题、供应链组织与财务组织之间的系统关系，以及后续如何将 ERP 智能助手接入统一 Agent 基座有了更清晰的理解。
同时，我完成了部分 UI 优化工作，重点调整了登录界面的展示方式和平台命名，使其更符合“智能体管理平台”的产品定位。

2. 今日完成工作

2.1 项目进度对齐

上午与带教同事进行了项目进度沟通，主要围绕新阶段的开发任务展开。通过本次对齐，我明确了当前工作的重点不只是单个功能页面的开发，而是要在已有平台雏形基础上，继续完善智能体创建、管理和后续装配能力。

本次沟通中，我了解到当前平台已经具备一定雏形，可以在平台上新建智能体，并通过管理入口对不同智能体进行配置。后续工作需要进一步规范智能体创建流程，为不同业务智能体接入统一基座提供基础。

2.2 原有架构问题理解

今天我重点理解了原有架构在当前业务推进中面临的问题。当前我们所在的供应链组织主要负责搭建一个类似“Agent 装配工厂”的基础架构，而兄弟部门中的财务组织已经建设了一个面向 ERP 场景的企业智能辅助助手。

随着两个系统都需要进入统一的业务应用链路，原来的单一平台形态已经不能很好支撑后续扩展需求。因此，项目需要从“单个助手”逐步演进为一个可管理、可装配、可扩展的智能体管理平台，将已有的 ERP 智能助手作为一个 Agent 接入到基础架构中。

2.3 个人任务认领

根据同事给出的需求，我近期的主要工作方向是围绕“数字人管理”模块继续完善 Agent 创建与管理能力。当前平台中，核心 Agent 创建入口被命名为“数字人管理”，后续我需要基于这一模块，尝试使用 Plan-and-Execute 的方式搭建 Agent 骨架。

这个骨架的目标不是只服务某一个固定智能助手，而是为后续不同类型 Agent 的动态装配提供基础能力。也就是说，平台后续需要能够根据不同业务场景，配置不同 Agent 的能力边界、执行流程和调用方式。

2.4 UI 界面优化

除架构理解和任务对齐外，我今天还完成了一部分 UI 优化工作。主要调整了登录界面的窗口排版和展示内容，使界面不再只是普通助手入口，而是更直观地体现智能体管理平台的定位。

在命名上，我将原先偏业务助手感的“智能交付助手”调整为“智能体管理平台”。这个改动能够更直接地表达当前平台的核心意义：它不是单一问答助手，而是用于管理、创建和装配不同智能体的基础平台。

3. 业务背景理解

3.1 团队定位

当前我们所在的供应链组织承担的是智能体基础架构建设工作，更偏向于为不同业务系统提供统一的 Agent 管理与装配能力。相比直接开发某一个业务助手，这个基础架构更像是一个“Agent 工厂”，用于承接不同业务组织已有或即将建设的智能助手。

3.2 业务链路现状

目前财务组织已经建设了面向 ERP 场景的企业智能辅助助手，而供应链侧正在建设智能体管理平台。随着业务逐步推进，两个系统之间不应长期割裂，而需要通过统一基座进行接入、管理和复用。

如果每个组织都单独建设自己的智能助手，后续可能会出现能力重复、接口不统一、管理方式不一致、扩展成本较高等问题。因此，需要通过统一平台把不同业务智能体纳入同一套管理体系。

3.3 项目目标

当前项目的目标是将已有的智能体管理平台逐步完善为一个可扩展的 Agent 基座。后续可以把财务组织的 ERP 智能助手作为一个 Agent 接入平台，并进一步支持更多业务场景下的智能体创建与装配。

从业务价值上看，这个平台可以帮助不同部门减少重复建设成本，使 Agent 能力以更规范的方式接入业务系统，也方便后续统一管理、统一配置和统一扩展。

4. 技术方案理解

4.1 智能体管理平台

今天我理解到，智能体管理平台的核心不只是提供一个前端页面，而是要承载 Agent 的创建、配置和管理能力。平台需要能够让不同业务智能体以统一方式接入，并为后续动态装配提供基础。

目前平台已有雏形，可以支持新建智能体。后续需要进一步明确每个智能体的配置格式、执行方式和能力边界，使其能够从单一配置页面逐步发展为真正的 Agent 管理基座。

4.2 ERP 智能助手接入

财务组织已有的 ERP 企业智能辅助助手，可以被看作一个业务 Agent。后续需要将其作为平台中的一个 Agent 进行接入和管理，而不是继续作为孤立系统存在。

这种接入方式可以让 ERP 智能助手复用统一的 Agent 创建、管理和调度能力，同时也为后续供应链、财务等更多业务场景的智能体接入提供参考。

4.3 Plan-and-Execute 骨架设计

今天讨论中，我进一步明确了近期可以尝试采用 Plan-and-Execute 的方式搭建 Agent 骨架。该方式的核心思路是先根据用户需求进行任务规划，再按照规划步骤执行具体能力调用。

对于当前智能体管理平台来说，Plan-and-Execute 的意义在于：它可以为不同 Agent 提供较统一的执行流程，使平台后续不仅能创建 Agent，还能围绕 Agent 的任务规划、执行步骤和能力调用进行扩展。

4.4 动态装配能力

当前“Agent 装配工厂”的概念还没有完全落到代码开发流程中，但今天的讨论让我明确了这个方向的重要性。后续平台需要逐步支持不同智能体能力的动态装配，而不是每接入一个新助手都重新写一套固定逻辑。

如果后续能将 Agent 的基础骨架、能力配置、执行方式和业务 Skill 进行拆分，平台就可以根据不同场景灵活组合智能体能力，从而提升整体扩展性。

5. 风险控制与可靠性设计

5.1 平台规范统一

当前阶段的一个关键问题是，智能体创建和接入方式还需要进一步规范。如果不同 Agent 的配置格式、调用方式和执行流程不统一，后续平台会很难维护。因此，近期需要先在“数字人管理”模块中逐步沉淀统一的 Agent 创建规范。

5.2 Agent 能力边界

ERP 智能助手接入平台后，需要明确它作为一个 Agent 的能力边界。例如它能够处理哪些 ERP 相关问题，哪些能力需要调用后端系统，哪些操作需要进一步确认。这些边界如果不清楚，后续会影响平台管理和业务使用的可靠性。

5.3 后续动态装配风险

动态装配虽然可以提升平台扩展能力，但也会带来流程复杂度增加的问题。后续在设计 Agent 骨架时，需要考虑不同 Agent 之间如何隔离、不同 Skill 如何按顺序或并发执行、失败时如何处理，以及如何避免因配置错误导致执行链路异常。

6. 今日个人理解

今天我对当前项目的定位有了更明确的认识。这个平台不是简单做一个聊天助手，也不是只服务某一个 ERP 场景，而是要逐步形成一个能够管理和装配不同智能体的基础平台。

我理解中的核心任务，是先把 Agent 创建和管理的基础骨架搭起来，让财务组织已有的 ERP 智能助手可以作为一个业务 Agent 接入进来。后续如果其他业务也有类似智能助手，就可以复用这一套平台能力，而不是重复建设。

同时，我也认识到 UI 呈现和平台定位之间是有关系的。登录界面和平台命名虽然属于前端细节，但它会影响使用者对系统的第一理解。因此，将“智能交付助手”调整为“智能体管理平台”，能够更准确地表达当前系统的架构意义。

7. 后续待明确问题

“数字人管理”模块中，Agent 创建需要包含哪些核心配置项；
Plan-and-Execute 骨架在当前代码中应如何落地；
ERP 智能助手接入平台时，需要暴露哪些接口或能力；
不同 Agent 的配置格式是否需要统一模板；
后续动态装配 Skill 时，是采用固定流程编排，还是支持更灵活的任务规划；
平台如何区分单 Agent 调用、多 Skill 顺序调用和多 Skill 并发调用；
UI 层面是否还需要继续强化“智能体管理平台”的产品定位。

8. 明日/后续计划

后续我计划继续围绕“数字人管理”模块推进开发工作，重点熟悉现有代码结构，并思考如何在当前平台雏形上引入 Plan-and-Execute 的 Agent 骨架设计。

同时，我会继续根据同事反馈优化平台 UI，尤其是与智能体创建、管理和配置相关的页面，使界面表达更加贴合平台定位。后续还需要进一步对接同事，明确 ERP 智能助手接入平台时的接口形式和功能边界。

9. 今日总结

今天的主要收获是，我从业务和技术两个层面进一步理解了智能体管理平台的定位。业务上，平台需要承接供应链组织和财务组织之间不同智能助手的统一接入与管理；技术上，平台需要从单一助手形态逐步演进为可创建、可配置、可装配的 Agent 基座。同时，我也完成了登录界面的部分 UI 优化和平台命名调整，为后续系统定位表达打下了基础。

实习日报｜第 1 天：环境搭建与业务理解

Mon, 18 May 2026 00:00:00 GMT

1. 今日概况

今天主要完成了入项前期准备和业务背景理解工作。上午在同事协助下完成公司内部 VDI 虚拟机环境配置，并安装 Java 开发环境，为后续代码阅读、接口调试和功能开发做好基础准备。

下午和晚上主要参加了领导及团队负责人组织的项目介绍和业务沟通会议，初步了解了团队定位、项目目标、财务与供应链之间的流程关系，以及自己后续可能负责的 Agent 智能客服方向。

2. 今日完成的具体工作

2.1 开发环境搭建

由于公司内部研发环境主要依托 VDI 虚拟机设备，因此今天首先完成了开发环境相关配置。

已完成内容包括：

完成 VDI 虚拟机开发环境接入与基础配置；
完成 Java 开发环境安装；
初步具备后续进行项目代码阅读、开发和调试的基础条件。

这一部分虽然属于基础准备工作，但对后续正式参与项目开发非常重要。只有先保证开发环境可用，后续才能进一步开展代码阅读、接口联调和功能开发。

2.2 参加项目规划介绍

在完成环境配置后，领导对当前项目的整体规划进行了介绍。通过这部分沟通，我初步了解到团队当前主要围绕内部业务提效展开工作，目标是通过系统化、自动化的方式减少人工重复操作，提高跨系统流程流转效率。

2.3 参加团队业务会议

晚上团队负责人组织了会议，向参与项目的成员进一步介绍了项目思想和任务方向。通过这次会议，我对个人后续工作内容有了更明确的认识，尤其是对财务、供应链、ERP、Web 自动化和 Agent 智能客服之间的关系有了初步理解。

3. 团队定位与项目背景理解

3.1 团队定位

我所在的小组主要是一个提效类团队，整体上类似于中台提效方向。团队的工作重点不是开发某一个孤立功能，而是围绕公司内部业务流程，减少人工操作成本，打通不同系统之间的流程壁垒。

从部门性质来看，我目前参与的是职能岗相关研发工作，主要服务于公司内部业务系统的流程优化和自动化建设。

3.2 当前项目背景

当前项目涉及财务和供应链等业务模块之间的流程衔接。供应链模块的上游可能会与财务模块产生连接，因此需要解决财务侧数据、表单和流程如何顺畅传递到供应链侧的问题。

过去财务模块和供应链模块之间相对分散，不同平台、不同模块之间的代码结构和业务流程差异较大，导致数据流转和流程处理不够统一。

因此，项目希望通过统一的流程规范和系统设计，将财务到供应链之间的业务链路打通。

4. 财务到供应链流程打通的理解

4.1 当前存在的问题

根据今天的沟通，我理解当前业务中主要存在以下问题：

财务模块和供应链模块之间流程较分散；
两个模块可能分别维护不同的代码逻辑和平台能力；
财务侧表单数据流向供应链侧时，缺少统一标准；
部分操作依赖人工在 ERP 或其他系统中完成，效率较低；
跨系统链路不够顺畅，容易形成流程壁垒。

4.2 项目希望解决的目标

项目的核心目标并不是简单做一个页面或接口，而是希望把财务和供应链之间原本割裂的流程统一起来。

例如，财务侧完成某类表单处理后，表单输出的数据可以按照统一规范直接传递到供应链侧平台或代码模块中，减少中间人工操作和系统差异带来的阻碍。

我的理解是，这项工作的本质是：

将财务侧的表单处理、数据输出和供应链侧的业务流程进行统一编排，使两个模块能够按照同一个流程框架完成衔接。

5. 项目实现方向理解

今天会议中提到的实现方式，可以理解为两个主要方向：一类是 Web 端流程自动化，另一类是企业微信工作台中的智能客服 Agent。

5.1 方向一：Web 端流程自动化

5.1.1 基本思路

第一个方向是从外部操作层面对财务 ERP 中的人工操作进行自动化改造。

财务侧原本可能需要员工在 ERP 系统中手动完成多个报表、表单或流程操作。项目希望将这些人工操作拆解成一个个可执行的链路节点，每个节点负责一系列明确功能，然后通过软件自动化方式完成原本需要人工点击和流转的操作。

5.1.2 我的理解

我的理解是，这相当于把“人在 ERP 系统里一步步点击完成操作”的过程，抽象成系统可以自动执行的流程链路。

员工未来可能不需要手动完成大量重复操作，而是通过外部系统选择或触发对应流程，由系统按照既定链路自动完成后续操作。

这种方式的价值主要体现在：

减少人工重复操作；
降低人为操作错误；
提升财务到供应链的数据流转效率；
为后续 Agent 调用后端服务提供基础链路。

5.2 方向二：企业微信工作台智能客服 Agent

5.2.1 基本思路

第二个方向是将 Agent 能力部署到企业微信工作台中，形成一个类似智能客服的入口。

用户在企业微信工作台点击入口后，可以通过文字或语音转文字的方式描述自己想做的事情。系统不再要求用户像传统 GUI 一样，通过点击多个菜单来寻找功能，而是让用户直接表达自己的需求。

5.2.2 与传统 GUI 的区别

传统 GUI 操作方式通常是：

用户先理解系统功能菜单，再通过点击不同按钮进入对应服务。

Agent 智能客服方式则更接近：

用户直接描述自己想完成什么事情，由 Agent 理解意图并匹配对应服务。

这种方式更贴近用户的真实想法，减少了用户在系统菜单中寻找功能的成本。

6. 我的个人负责方向

6.1 核心任务理解

结合 Leader 的介绍，我理解自己后续主要负责的是企业微信工作台智能客服 Agent 相关方向。

我的任务重点不是直接开发所有底层业务流程，而是利用 Agent 技术完成用户意图识别、参数提取和流程分发。

简单来说，我负责的是：

把用户的自然语言需求，转化成系统能够理解、能够匹配、能够调用的业务流程指令。

6.2 Agent 在链路中的作用

在整个业务链路中，Agent 更像是用户和后端自动化流程之间的中间层。

它需要完成以下工作：

理解用户输入内容；
判断用户真实意图；
提取用户表达中的关键参数；
判断用户想走哪一条业务链路；
将识别结果映射到对应的后端流程分支；
调用同事在 Web 端或后端实现的自动化服务链路；
在关键节点引入用户确认或人工确认。

6.3 整体流程理解

我目前理解的整体流程如下：

用户在企业微信工作台输入需求
        ↓
Agent 识别用户意图
        ↓
Agent 提取关键参数
        ↓
匹配对应业务流程分支
        ↓
调用 Web 端或后端自动化链路
        ↓
必要时进行人工确认
        ↓
确认无误后继续执行业务流程

6.4 个人角色定位

从个人职责来看，我更像是在做“自然语言入口到业务自动化链路之间的连接层”。

我的工作价值在于：

降低用户理解系统菜单的成本；
提高用户触发业务流程的效率；
帮助系统准确判断用户要办理的事项；
将用户需求分发到正确的业务链路；
为财务与供应链流程自动化提供更自然的交互入口。

7. 风险控制与 Human-in-the-loop 设计

7.1 为什么不能完全交给 Agent

Leader 今天也提到，这类业务不能简单地把所有权限都交给 Agent 自主决策和执行。

原因是当前场景涉及财务、供应链、ERP 等企业内部业务系统，很多操作可能影响数据准确性、审批责任和业务结果。如果完全由 Agent 自动执行，风险会比较高。

7.2 Human-in-the-loop 的必要性

因此，项目后续很可能需要引入 Human-in-the-loop 机制，也就是在关键节点加入人工确认或人机交互。

Agent 可以先完成意图识别和参数提取，但在真正调用关键流程之前，需要让用户或相关人员确认识别结果是否正确。

例如：

确认用户想办理的流程类型；
确认表单编号是否正确；
确认供应链流程分支是否正确；
确认财务报表或业务参数是否准确；
确认是否允许继续调用后端流程。

7.3 我的理解

我认为 Human-in-the-loop 是企业级 Agent 场景中非常重要的一环。

它不是降低 Agent 的价值，而是让 Agent 的能力在可控范围内发挥作用。这样既能提升效率，又能降低因模型识别错误带来的业务风险。

8. 知识库增强与 RAG 思路

8.1 为什么需要知识库增强

如果 Agent 只依赖大模型自身能力，可能会出现理解不准确、回答不稳定、依据不足等问题。

在企业内部业务场景中，Agent 需要参考明确的业务规则、流程说明、表单规范和系统操作要求。因此，后续可能需要引入知识库增强能力，让 Agent 的判断更加有依据。

8.2 可放入知识库的内容

后续知识库中可能需要包含以下内容：

财务流程说明；
供应链业务流程规范；
ERP 操作文档；
表单字段说明；
常见问题与处理规则；
不同流程对应的触发条件；
各类业务链路的参数要求；
人工确认和审批规则。

8.3 RAG 在项目中的作用

这部分与 RAG 思路比较接近，即先从知识库中检索相关内容，再让 Agent 基于检索结果进行判断、回复或流程匹配。

这样可以提升 Agent 在业务场景中的：

准确性；
可解释性；
稳定性；
可追溯性；
业务依据可靠性。

9. 今日收获

9.1 对业务的收获

今天我对当前项目的业务目标有了比较清晰的认识。

项目核心不是单纯开发一个功能，而是围绕公司内部流程提效，尤其是打通财务与供应链之间原本分散的系统链路，使表单、数据和流程能够在统一规范下流转。

9.2 对技术方向的收获

从技术角度看，该项目涉及的不只是传统 Web 开发，还包括：

流程自动化；
业务链路编排；
Agent 意图识别；
参数提取；
后端服务调用；
Human-in-the-loop；
知识库增强；
企业微信工作台集成。

9.3 对个人任务的收获

我对自己后续任务的理解更加明确：需要围绕企业微信工作台中的智能客服 Agent 场景，完成用户意图识别、参数提取和业务流程分发，将用户自然语言需求连接到后端自动化链路中。

10. 后续需要继续明确的问题

后续还需要继续和 Leader、同事沟通，进一步明确以下问题。

10.1 业务流程层面

财务到供应链之间具体有哪些核心业务流程需要打通；
每条业务流程的起点、终点和中间节点是什么；
哪些流程当前依赖人工操作；
哪些流程适合优先自动化。

10.2 Web 自动化链路层面

Web 端自动化链路目前已经实现到什么程度；
后端服务是否已经有稳定接口；
每个流程分支需要哪些输入参数；
调用失败或参数异常时如何处理。

10.3 Agent 能力层面

Agent 需要支持哪些典型用户意图；
每类意图需要提取哪些关键参数；
意图识别错误时如何兜底；
多轮对话中如何补充缺失参数；
哪些场景需要转人工。

10.4 企业微信集成层面

企业微信工作台入口形式如何设计；
用户输入是文本为主还是语音转文字为主；
权限控制如何处理；
不同岗位用户是否看到不同能力；
操作日志和流程记录如何留存。

10.5 知识库建设层面

知识库需要纳入哪些业务文档；
文档如何切分和更新；
如何保证检索结果准确；
如何避免 Agent 编造业务规则；
如何让回答和流程调用具备可追溯依据。

11. 今日总结

今天完成了从环境准备到业务认知的初步过渡。

上午主要完成 VDI 虚拟机环境配置和 Java 开发环境安装，具备了后续开发基础。随后通过领导介绍和团队会议，了解了当前团队的提效定位、项目整体目标、财务与供应链之间的业务关系，以及自己后续可能承担的 Agent 智能客服方向。

目前我对个人工作的理解是：围绕企业微信工作台中的智能客服 Agent，完成用户意图识别、参数提取和业务流程分发，将用户自然语言需求连接到后端自动化链路中。

同时，在企业内部业务场景下，Agent 不能只追求自动执行，还需要结合 Human-in-the-loop 和知识库增强机制，保证系统在提升效率的同时具备足够的安全性、准确性和可控性。