构建一个能说会做的智能体

项目代码仓库：LS-XH/MyUniverse

这个作业属于哪个课程	计科 24 级 56 班
这个作业要求在哪里	构建一个能说会做的智能体
我希望在这门课达到的目标	学习Agent开发范式，ReAct架构，Agent Loop，MCP与Tool Use，以及LangGraph框架的使用

参与成员：
李文争 3124004171
邓子豪 3124004165
黄琪 3124004169

MyUniverse：让 AI 从“回答问题”走向“参与世界观创作”

本文介绍 MyUniverse 中 Agent 与工具系统的设计。项目面向小说、剧本和游戏设定创作：用户可以在一个结构化工作台中管理世界对象，并让 AI 基于这些资料进行查询、创作和审校。

一、项目简介

长篇创作的难点不只是生成文字，还包括维护人物、地点、势力、事件之间的一致关系。MyUniverse 将世界观整理为可编辑的结构化对象，提供人物关系网、地图、Markdown 管理和 AI 创作助手。AI 可以阅读现有设定，帮助作者构思、检查并提出修改建议；作者则保留最终决定权。

项目使用 React 与 TypeScript 构建桌面应用，桌面容器基于 Tauri，通过Rust的invoke与本地交互，也可以使用vite使用web版本。模型通过 OpenAI 兼容接口接入，Agent 及工具执行由应用自身的运行时负责。当前工具注册与模型调用采用 MCP 风格的数据结构，并转换为兼容模型接口所需的 tool/function 格式；有Tool Use、Planning、Memory、Muti-Agent Manager使用/创建/管理，Skill加载/创建/管理等等能力。

二、需求描述

2.1 面向创作者的需求

创作者希望 AI 能理解自然语言中的创作目标，结合当前世界已有资料给出贴合设定的回答。更进一步，AI 应能调用工具检索对象、向用户追问缺少的信息，并提出新增或修改设定的建议。

因此，系统需要具备以下能力：

• 自然语言交互：用户用日常语言描述创作和审校任务，模型生成流式回复。
• 世界资料检索：按需发现类别、列出实例、读取指定实例的完整 Markdown 正文。
• 可控的修改能力：AI 创建或修改世界对象时先提交提议，展示差异，由用户采纳或拒绝。
• 多轮任务执行：模型可以在一次任务中先查询、再分析，必要时继续调用工具，最后组织成自然语言答复。
• 复杂流程编排：通过可视化 Agent 工作流连接模型、工具、条件、循环和子 Agent。
• 上下文与能力隔离：聊天会话有独立上下文；每个 Agent 只使用明确授予的工具、技能和子 Agent。

2.2 Agent 场景

MyUniverse 的 Agent 是“世界观创作助手”。例如，用户可以要求：“检查林澈的设定，并提出一段更符合他与顾遥关系的补充。”Agent 先读取相关对象，再结合用户要求形成建议。建议进入聊天提议区，用户检查差异后决定是否写入正式设定。

这里的“会做”包括读取世界资料、调用获准的工具、等待用户回答、运行编排流程，以及生成待采纳的修改建议。高影响的世界内容变更由用户确认后完成，避免模型一句话就静默覆盖原始资料。

三、Agent 架构设计

3.1 总体分层

系统把模型、Agent、工具和世界数据分开管理。模型连接负责通信参数；Agent 负责任务策略及获准能力；Tool 负责具体动作；世界对象模块负责数据读写、校验和持久化；聊天界面负责输入、过程展示和提议确认。

flowchart TD U[用户自然语言输入] --> C[聊天与会话层] C --> A[Agent 运行时] A --> L[OpenAI 兼容模型接口] L -->|文本或工具调用| A A --> P[能力与参数校验] P --> T[Tool 注册表与执行器] T --> W[世界对象 API / Skill / Agent 会话] W --> T T -->|工具结果| A A -->|最终答复与过程事件| C T -->|修改提议| C C -->|用户采纳| W

3.2 三类 Agent

项目提供三种 Agent 类型，适合不同的任务复杂度：

类型	适用方式	主要特点
Workflow	需要明确、可重复的步骤	在画布上编排节点、条件、循环、变量和 ToolCalls，流程由图结构控制
ReAct	一般对话与工具协作	模型结合当前问题和工具结果，迭代决定下一步调用或直接回答
Advanced	需要更多技能或 Agent 协作的任务	在 ReAct 能力基础上按授权发现、加载技能，并可启用会话成员管理

Workflow 与 ReAct/Advanced 共用基础模型、工具和运行约束。内置 ReAct、高级及多角色 Agent 由程序生成核心流程，主要通过系统提示词、工具、子 Agent、技能和轮次上限配置；自定义 Workflow 则可编辑图本身。

聊天创建时选择并固定 Agent，模型另行选择。这一拆分使“由谁执行、按什么规则执行”和“由哪个模型提供推理能力”成为两类独立配置。

3.3 工具调用闭环

一次典型的模型工具调用按以下步骤运行：

1. Agent 根据当前任务、对话历史及获准能力构造模型请求。
2. 模型返回普通文本，或返回一个/多个带名称和 JSON 参数的工具调用。
3. 运行时按稳定工具 ID 查找工具，并校验调用名、参数 Schema 和权限。
4. 工具执行后，系统把结果连同原始 tool_call_id 放回模型对话协议。
5. Agent 根据结果继续调用工具，或生成最终答复；自动工具交流受轮数及根运行预算限制。

聊天请求支持流式传输。工具调用参数在完整接收并校验前不会执行；取消、格式错误和传输失败会作为运行失败处理，不会把未完成的调用当作成功结果。

3.4 工具目录与 MCP 风格适配

应用自带工具按职责分组管理，包含世界对象查询与修改提议、用户交互、Skill 管理、Agent 成员管理和受管技能文件操作。用户也可以配置 JavaScript 或 HTTP Tool。工具定义包含稳定身份、调用名、用途说明、JSON Schema 与执行实现；注册表供聊天和工作流统一使用。

在模型调用边界，应用把内部工具描述转换为兼容接口理解的 function 工具定义，再把模型的工具调用分派到内部执行器。因此，这里复用了 MCP 风格的工具描述和结果表达，但没有实现 MCP 网络传输，也没有宣称连接外部 MCP 服务。

3.5 世界数据与修改提议

Agent 不直接以任意文本覆盖整个世界。查询工具可读取类别、实例名称和实例正文；修改工具则生成新增或修改提议。提议会在聊天中展示前后差异，用户采纳时系统再次检查结构与冲突，再将修改写入世界数据。拒绝提议则不会应用该项修改。

世界对象以 JSON 作为完整工作区的存储来源，Markdown 主要用于可读预览及显式导入、导出。采纳提议后对象进入工作区并自动存档；需要 Markdown 文件时再导出。这样的职责划分把“模型建议”“用户决定”“数据持久化”串成清晰流程。

3.6 记忆、会话与多智能体

聊天协议历史随会话保存，使自带 Agent 在同一会话中延续上下文；会话间不会共用这份历史。自定义工作流 Agent 还可以使用变量和记忆。子 Agent 的成功结果先暂存，只有根调用成功后才统一校验并提交记忆；失败或取消时，未提交的 Agent 记忆会丢弃。

多角色场景由主 Agent 通过 Agent Manager 管理成员。成员具有独立的模型协议历史，彼此不会读取对方的私有系统提示词、思考过程或工具协议；公开发言进入共享对话。成员创建和调用仍受主 Agent 获准的能力、Schema 校验、调用预算和取消信号约束。

四、业务流描述

以“检查人物设定并提出修改建议”为例：

sequenceDiagram actor User as 用户 participant Chat as 聊天界面 participant Agent as Agent 运行时 participant LLM as 模型服务 participant Tool as 世界查询/提议工具 participant World as 世界对象存储 User->>Chat: 描述创作任务 Chat->>Agent: 会话上下文 + 输入 + Agent/模型配置 Agent->>LLM: 发送消息与获准工具说明 LLM-->>Agent: 请求读取人物实例 Agent->>Tool: 调用查询工具并校验参数 Tool->>World: 按类别和实例读取正文 World-->>Tool: 返回对象资料 Tool-->>Agent: 返回工具结果 Agent->>LLM: 带工具结果继续推理 LLM-->>Agent: 请求提交修改建议 Agent->>Tool: 校验建议并创建提议 Tool-->>Chat: 返回待确认提议和差异 Agent-->>Chat: 流式展示分析与说明 User->>Chat: 采纳或拒绝 Chat->>World: 采纳时校验并更新对象 World-->>Chat: 保存状态与操作结果

实际使用时，模型可能判断无需调用工具而直接回复，也可能先通过提问工具向用户补齐创作条件。具体路径由 Agent 配置、模型判断和当前可用能力共同决定。

五、实现说明

5.1 技术组成

部分	项目实现
前端与交互	React、TypeScript；聊天、Agent 设置和工作流画布
桌面端	Tauri；承载桌面文件与流式请求能力
模型	OpenAI 兼容消息及工具调用接口，支持流式聊天
Agent 执行	项目内 Graph/Agent Runtime，负责调度、工具调用、循环、子调用、取消和预算
工具	应用自带 Tool，以及用户配置的 JavaScript/HTTP Tool
世界存储	JSON 工作区数据；Markdown 用于预览、导入与导出

模型服务需要提供与当前消息及工具调用协议兼容的接口。不同服务对参数和 Tool Calling 的支持可能不同。

5.2 Agent 工作流节点

可视化 Workflow 通过数据线同时表达节点依赖和执行顺序。基础 LLM 节点负责请求模型，ToolCalls 节点负责执行模型提出的调用；消息合并节点维护对话，条件节点选择分支，顺序执行节点串行组织步骤，内部循环节点支持受上限约束的多轮迭代。变量池可保存字符串、数字、布尔值、消息、图片、Tool、Agent 和方法等数据。

例如，可搭建“读取世界类名 → 查询人物对象 → 生成审校意见 → 调用审校 Agent → 汇总结果”的图，并在执行面板观察节点、连线值和循环轮次。创建的图和能力配置可以继续编辑，适合将固定创作规范保存为可复用流程。

5.3 权限与失败处理

Agent 只能使用配置中授予的工具、技能和子 Agent。工具参数会经过 JSON Schema 校验；写入型自定义 JavaScript/HTTP 工具在聊天中需要用户确认。所有 Agent 子调用共用根调用的世界、会话、取消信号和预算，并有调用深度、节点数及总调用数限制，避免递归无界扩张。

运行失败、取消和并发冲突会明确反馈。Agent 的暂存记忆在根运行成功后提交；已经独立提交的 Tool 世界写操作并不自动随整个 Agent 运行回滚。世界修改提议则等待用户采纳后才应用。

六、使用示例（功能演示）

示例一：查询现有设定

用户：“列出这个世界里的所有类别，然后告诉我目前有哪些人物设定。”

Agent 执行：调用世界类别查询工具，再调用人物实例列表查询工具。

Agent 回复：根据实际工具结果用自然语言汇总类别和人物名称。模型只有在配置并获准相应工具后，才能执行这些查询。

示例二：结合上下文提出修改建议

用户：“读取人物‘林澈’和‘顾遥’的资料，帮我补一段体现他们互相不信任、但不得不合作的关系描述。”

Agent 执行：读取两个人物的完整正文，结合用户要求生成候选描述，并提交人物修改提议。

用户确认：检查聊天中展示的修改差异，选择采纳或拒绝。采纳后，正式世界对象才会更新。

示例三：用多 Agent 进行创作审校

可创建创作 Agent 和审校 Agent：创作 Agent 生成草案，审校 Agent 检查角色动机、已有世界设定和前后冲突，主 Agent 汇总反馈并给出修订建议。项目提供可编辑的双 Agent Multiagent 模板；调用关系、提示词、模型和预算由配置决定。

以上示例描述的是系统支持的交互方式。具体回答与调用结果取决于当前世界资料、模型服务和 Agent 的工具授权。

七、项目使用与演示准备

1. 从 GitHub 仓库 获取代码，按仓库 README 安装项目依赖并启动应用。
2. 在应用中创建世界，至少添加人物、地点或事件等实例。
3. 配置一个兼容的模型连接，并测试连接。
4. 新建聊天，选择 ReAct 或高级 Agent，检查其可用工具及技能权限。
5. 先演示查询类问题，再演示提出修改建议并由用户采纳，清晰呈现“能说”和“会做”。
6. 如需展示流程设计，可打开工作流画布运行工具调用或创作/审校示例。

演示前应准备好模型服务及少量示例世界资料。模型供应商是否支持 Tool Calling、服务参数是否兼容，会影响实际调用效果。

八、小组分工

成员	分工
成员一：李文争	Agent 架构与运行时
成员二：邓子豪	工具系统与世界数据交互
成员三：黄琪	聊天界面与交互体验

九、小组成员心得

成员一：李文争

可以围绕 Agent 如何从模型回复发展为“模型决策 + 工具执行 + 结果反馈”的循环，以及自己负责的模块展开。

成员二：邓子豪

可以围绕工具 Schema、调用参数校验、世界数据访问和用户确认机制，说明如何控制 AI 操作的准确性与可追溯性。

成员三：黄琪

可以围绕流式对话、工作流画布、过程可视化或修改差异确认，分享交互设计中的收获。

十、总结

MyUniverse 将 Agent 放在结构化创作场景中：模型负责理解任务与选择下一步，工具负责读取资料和执行明确动作，运行时负责校验权限、调度流程并控制预算，用户负责确认正式世界内容的变更。ReAct、Advanced 和 Workflow 三种形态覆盖从自然语言问答到可视化多步骤编排的不同需求；会话记忆、技能加载和多 Agent 管理则为复杂创作提供扩展空间。

对我们而言，Agent 的关键并非只让模型生成更长的回答，而是为它建立一条可观察、受约束、能与真实数据交互的行动链路。这也是本项目为后续智能应用开发打下的基础。

一些用于支持项目的附加功能

RunTime Tool：

RunTime Skill：

关系网视图：

LLM Wiki：