zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(design): 接口协议草案 agentscope 2.0.3→2.0.2 + 克隆路径订正

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
zizi 2026-06-23 18:31:42 +00:00
parent f1ca3b792f
commit 1a36a7279e
1 changed files with 5 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/plans/2026-06-23-接口协议层与可插拔模块-design.md
View File

@ -346,9 +346,9 @@ mapping:
**状态:** 现 —— 生产已跑、判过大量游戏。driven 感知 advisory 分级 = 接(A-model 分支已落、待合并 dev/2.0.0 对账)。
### B-FRAMEWORK-AgentScope — agent 框架适配器 · AgentScope(tier2 自治富游戏轨,锁 2.0.3)
### B-FRAMEWORK-AgentScope — agent 框架适配器 · AgentScope(tier2 自治富游戏轨,锁 2.0.2)
**责任:** 把 AgentScope 2.0.3 这套自治 ReAct 框架接到平台的固定协议上:实现任务协议(经 Agent Service `create_app` 接 A1 GenerationDispatcher)、状态模型(存取 AgentState 而非序列化活对象,映射到 A2)、工具接口(把九工具 + mmx 接进 Toolkit,实现 A7)、验收门禁(在门内迭代、禁 LLM 自评,服从 A5)、遥测(订阅 typed Event System,经 trace 中间件映射到 A2.5)。
**责任:** 把 AgentScope 2.0.2 这套自治 ReAct 框架接到平台的固定协议上:实现任务协议(经 Agent Service `create_app` 接 A1 GenerationDispatcher)、状态模型(存取 AgentState 而非序列化活对象,映射到 A2)、工具接口(把九工具 + mmx 接进 Toolkit,实现 A7)、验收门禁(在门内迭代、禁 LLM 自评,服从 A5)、遥测(订阅 typed Event System,经 trace 中间件映射到 A2.5)。
**形态:** 它是"框架适配器",不是能力包。一边吃平台的五条固定协议,一边用 AgentScope 的机制(Toolkit / AgentState / Event System / Agent Service)去满足它们。换框架(AgentScope → 别的)= 重写这一个适配器,五条 A 协议不动。
@ -356,7 +356,7 @@ mapping:
**语言:** Python(AgentScope 在 Python)。
**状态:** 建 —— tier2 待 0 号 spike,锁 AgentScope 2.0.3(外部源码已 clone 在 /root/oss/agentscope2.0.3)。
**状态:** 建 —— tier2 待 0 号 spike,锁 AgentScope 2.0.2(外部源码已 clone 在 /root/oss/agentscope)。
### 平台级可插拔模块(第二轮:对接 A8–A13)
@ -412,7 +412,7 @@ mapping:
## 4 AgentScope 机制实证
这一节是把"该用 skill 还是 mcp 还是 tool、能不能跨语言"这些定级判断坐实到 AgentScope 2.0.3 源码,而不是凭记忆。以下结论均已核实(源码行号为 2.0.3)。
这一节是把"该用 skill 还是 mcp 还是 tool、能不能跨语言"这些定级判断坐实到 AgentScope 2.0.2 源码,而不是凭记忆。以下结论均已核实(源码行号为 2.0.2)。
**skill = 指令 + 资源包,自身不执行代码。** 一个 skill 是含 `SKILL.md` 的本地目录,SKILL.md 用 YAML frontmatter 携带 name + description(两者缺一即被跳过),正文是 markdown 指令。数据结构 `Skill` dataclass 字段 = name/description/dir/markdown/updated_at(`skill/_base.py:7-20`)。本地加载器 `LocalSkillLoader` 解析 frontmatter 并校验 name/description 必填(`skill/_local_loader.py`)。
@ -426,7 +426,7 @@ skill 怎么被 agent 用:**它不是 tool、不能直接 call。** 两步暴露
**MCP 完全语言无关。** 注册两条路与 skill 平行(直连 Toolkit / `workspace.add_mcp`,后者确实存在,`workspace/_local_workspace.py:906`)。传输两种,由 pydantic config 判别:`StdioMCPConfig`(command/args/env/cwd,起子进程经 stdio_client,stdio 强制 stateful)与 `HttpMCPConfig`(url/headers/timeout,按 url 后缀选 SSE 或 streamable-http)。`command` 可以是任何语言写的 MCP server(rust/go/c++/node 二进制都行);HTTP server 实现语言任意。MCP server 暴露的工具被包成 `MCPTool`(ToolBase 子类),经 `MCPClient.list_tools()/get_tool()` 注册成 agent 可直接 call 的工具,模型侧工具名格式 `mcp__{name}__{tool}`。**这就是 §1 "多语言走 MCP" 的依据:跨语言能力(含任意语言探针)走 MCP 暴露给 agent。**
**tool 必须是进程内 Python(或经适配器跨进程)。纠偏一处:2.0.3 没有 `register_tool_function` 方法。** 全仓 grep 该名零命中(只在 `mcp/_mcp_client.py:372` 的 docstring 提到 `toolkit.register_tool(tool)`,但 Toolkit 上也没有该方法,疑文档滞后)。Toolkit 公开方法只有 get_tool_schemas / call_tool / get_skill_instructions / check_tool_available / get_tool / clear。工具的引入靠**构造器入参** `tools=[ToolBase]` 或 `ToolGroup`,不靠运行时 register 方法。把自定义 Python 函数变工具的适配器 = `FunctionTool(func, ...)`(`tool/_adapters.py:31-88`),它在 call 里直接 `self._func(**kwargs)`(同 / 异步皆可)——这是 1.x `register_tool_function` 的等价物。**这就是 B-FRAMEWORK-AgentScope 里"FunctionTool 薄壳"的依据:九工具的 Python 接线靠 FunctionTool,不靠传说中的 register_tool_function。**
**tool 必须是进程内 Python(或经适配器跨进程)。纠偏一处:2.0.2 没有 `register_tool_function` 方法。** 全仓 grep 该名零命中(只在 `mcp/_mcp_client.py:372` 的 docstring 提到 `toolkit.register_tool(tool)`,但 Toolkit 上也没有该方法,疑文档滞后)。Toolkit 公开方法只有 get_tool_schemas / call_tool / get_skill_instructions / check_tool_available / get_tool / clear。工具的引入靠**构造器入参** `tools=[ToolBase]` 或 `ToolGroup`,不靠运行时 register 方法。把自定义 Python 函数变工具的适配器 = `FunctionTool(func, ...)`(`tool/_adapters.py:31-88`),它在 call 里直接 `self._func(**kwargs)`(同 / 异步皆可)——这是 1.x `register_tool_function` 的等价物。**这就是 B-FRAMEWORK-AgentScope 里"FunctionTool 薄壳"的依据:九工具的 Python 接线靠 FunctionTool,不靠传说中的 register_tool_function。**
**机制归并:** tool = agent 能直接 call 的最细粒度执行单元(FunctionTool 进程内 Python / MCPTool 跨进程 / builtin Bash·Read·Write);skill = 注入提示的指令 + 资源包,经 SkillViewer 回灌、自身不执行;mcp = 跨进程跨语言的工具来源。映射到本设计:写法 / 脚手架 / 避坑知识 → skill;九工具的 Python 接线 → FunctionTool;探针(node/CDP)→ skill + Bash shell-out,或经 MCP;跨语言能力 → MCP。