d8adc3d0d4
2.0.3 从未发布到 PyPI(最新 2.0.2),requirements.txt 的 ==2.0.3 不可安装。已在 mini-desktop venv 实装 2.0.2 并冒烟:Agent/ReActConfig/Toolkit/FunctionTool/Anthropic*/MCP(Stdio+Http)/create_app(Agent Service)/AgentState/workspace/middleware/event/skill 全在——设计依赖符号对 2.0.2 成立。 活层(docs/tier2/.agents)agentscope 2.0.3→2.0.2:文档+SVG+requirements.txt+knowledge facts(改名 agentscope-2.0.2-facts.md);npm lockfile 第三方 2.0.3 未动。复验 SVG 32 张全过。 注:6c6g 克隆 /root/oss/agentscope 实为 2.0.3-dev(领先 PyPI),与 2.0.2 架构一致(符号已对)。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
16 KiB
date, topic, status, 映射源档
| date | topic | status | 映射源档 | ||||
|---|---|---|---|---|---|---|---|
| 2026-06-23 | tier2 细节图说 · E 族——能力面（skills 清单 / 引擎能力包 / prompt 两阶段角色 / A-model 插件复用） | 设计中（tier2 待 spike）· 每图映射源档见脚注 · 通用读法见本篇 §0/§1 |
|
tier2 细节图说 · E 族 · 能力面：skills 与 prompt
🚧 设计中 · tier2 是待 0号 spike 验证的假设,尚未落代码;过了 spike 才进建设。 本族四张图回答同一个层面的问题:单写 agent 手里握着什么、引擎以什么形态交给它、谁在哪个阶段写、上一条廉价线已经造好的资产怎么接住。 整轨的生命周期与对象结构画在《agentic 运行时架构图说》,本族只放大其中的能力面。
0 阅读约定与同步纪律
E 族映射四份源档:tier2 实现详设的 §「运行时形态:两阶段、service 化与 session 三路径」和 §「前置物清单」,自治富游戏引擎的 §「引擎是能力包,不是底座」和 §「换一种生成方式」,实现计划的 §「与 A-model 分支的关系」,以及 tier2/HANDOFF.md 的 §「与 A-model 分支的协调」。frontmatter 里记了这四份的当前 commit hash,作为防漂移的对账锚——设计一变动,本图说与对应 SVG 必须连同 hash 一起同步更新。
整族都还没落代码,所以"状态"这一维度贯穿每张图,绝不能把待建的东西画成已建。tier2 的整条轨待 0号 spike 验证才决定要不要正式投入,因此本族凡是 tier2 专属的新机制一律画虚线、标"建";凡是承袭现行廉价线已经跑着的东西(九门 harness 的钩子机制、A-model 改过的探针分级范式、A-model 已造的插件契约)画实线、标"现"或"接"。看图时先认线型再读内容:实线 = 有真实现可承袭,虚线 = 还要照这份设计去建。
E 族里只有图 E4 涉及第三种状态。它讲的是 tier2 怎么接住 Mac 那条 A-model 分支已经造好的资产,所以整图基调是"接"——既不是 tier2 从零新建,也不是现行产线已落,而是把一份在飞分支的产出对账过来复用。这个区别在图里用底色和线型分开标。
1 全图通用图例
状态码(贯穿全族,决定线型):现 = 现行廉价线已落、tier2 直接承袭(实线);接 = 复用 A-model 已造资产、合并后对账(实线框 + 接的底色);建 = tier2 专属新机制、待 spike 后落代码(虚线框 + "建"小标);缓 = 排在更后、本族未出现。
工具角色徽章(图 E1 用):核心环(#2563eb)= ReAct 写-构-验主回路上的工具;取证(#b45309)= 只喂软检与人审、绝不进硬门判定;起手收尾(#16a34a)= 一次 session 的开头铺骨架、结尾吐源工程。
五件套维度徽章(图 E2 用):质量(#15803d)标在 skill 与 rag 上,因为这两件直接抬高模型写对的概率。
两阶段维度徽章(图 E3 用):伸缩·多 agent(#7c3aed)= 阶段 1 工作室靠多个设计 agent 发散;数据·只读探(#475569)= 设计 worker 只读不写;质量·单写防冲突(#15803d)= 阶段 2 收敛到单写。
复用维度徽章(图 E4 用):数据(#475569)= 复用引擎无关的契约与命名;质量(#15803d)= 渲染实现按 Phaser 重做、不降级;成本(#16a34a)= 不重新发明、省掉 Mac 那边重复造轮子的工时。
实线箭头(承袭现行)与虚线箭头(待建机制)在图 E3 的拓扑连线里也用同一套语义。
2 图集
图 E1 · 单写 agent 的 toolkit(阶段 2 · skill 清单)
这张图把阶段 2 单写 agent 的工具箱摊开,逐个交代每个工具的目的、边界、产出。看它要先抓住一个形态:这不是一条流水线,而是九个工具围成的一圈自治内循环——写源文件、构建、跑一道便宜快检、跑真玩门、读门的裁决、据裁决再改,绕回写源,直到收敛或熔断触发为止。agent 不按固定顺序走完九步,而是每一轮"想一步、调一个工具、看结果",由它自己决定下一个调谁。所以这九个工具是 ReAct 循环的工具面,不是阶段图。
工具按角色分三类,这层分类才是设计要点。核心环的六个(写源、构建、快检、跑门、读裁决，以及作为收尾的 finish)是主回路上真正驱动迭代的;取证类的截图和查资产是喂给软检与人工的辅助;起手收尾类的模板初始化和 finish 各管一次 session 的开头和结尾。把截图单独划成取证、不让它进 L1 判定,是一条故意设的边界:一旦让模型看截图来给自己的游戏打分、又拿这个分当过关依据,模型会很快学会把游戏优化成"在截图里好看"而不是"真的能玩"。验收要靠 run-gates 在真浏览器里真玩一遍、机器确定性地判,截图只能用来给人减负和 debug。
九个工具里 write-source 是整轨最深的赌注所在。它写的是那 56% 的表现层——逐像素手画的场景和 UI、点击命中、这款游戏独有的规则,既压不成数据表也压不成骨架,只能 LLM 现写,也最容易崩。其余八个工具大半是在给这一件兜底:build 把源工程打成可玩 bundle,headless 在跑全套真玩门之前先做一道便宜快筛、能早断就别浪费一整轮真玩,run-gates 才上确定性的九门加三联动门加经济门加 latch,read-verdict 把裁决喂回循环让 agent 知道该改哪。
脚带那三条边界铁律是这张图最该让人记住的设计约束。第一条单写独占——整个工程只允许一个 agent 写、绝不并行拆,因为经营游戏的多个系统共享同一套状态,拆给并行 agent 几乎必然写出互相矛盾的结果(一手教训是曾经把"造 Flappy Bird"拆并行,背景跑成了马里奥)。第二条 finish 与源项目契约共用一份 schema——agent 交付时吐出来的形状,必须就是落库取回时认的那个形状,两边各写各的迟早对不上。第三条验收零自评,就是前面说的那条防 Goodhart 红线。
图底那条虚线点明本族最大的待建项:这九个工具现在只是概念清单,它们的 Phaser 实现(esbuild 构建 profile、Phaser harness 的钩子)都还没写。第一版打算先把 Phaser 硬编码进 worker,等第二个引擎落地、有两个实现做依据,再去抽通用的能力包接口——这正是图 E2 要讲的克制。
(图源:tier2实现详设.md §运行时形态 / §前置物清单 · 自治富游戏引擎.md §引擎是能力包 · plan U2/U5)
图 E2 · 引擎能力包 manifest(五件套)
这张图回答一个容易想偏的问题:引擎在 tier2 里到底是什么。直觉会把引擎当成"一次选定、所有游戏都长在上面的固定底座",像现行廉价线选了 LittleJS 那样。tier2 故意不这么做。在这套架构里引擎是动态加载的能力包:每个引擎对应一套给 agent 用的五件套——skill、tool、mcp、rag,外加一份起手脚手架。换引擎,对 agent 来说就是换掉"我手里有哪些工具能调"的那一组,不是架构重写。这个设计的好处是它顺着 agent 的工作方式来——agent 本来就是按"我能调什么工具"来干活的,把引擎做成一套工具集,换引擎的代价就被压到了换工具集而非重写主干。
五件套各管一面。skill 是这一引擎下"如何做某一类事"的固化 playbook,把对的写法沉淀下来、少让模型现场摸索;tool 就是图 E1 那九个工具,它们的引擎实现按引擎重写;mcp 经模型上下文协议把引擎侧能力标准化地暴露成可调接口;rag 是引擎文档加范例的检索增强,补模型训练数据里这个引擎的密度——模型见这个引擎的代码越多,自治循环里就越少漂、越少编不存在的 API;脚手架就是模板初始化铺的那套工程骨架,等于平台预建的那 25%,给单写 agent 一个先天能过 boot 的起手点。skill 和 rag 标了质量徽章,因为这两件直接决定模型写得对不对。
图里那个紫色块"换引擎 = 换一套加载的工具集"是核心论点的落点:Phaser 能力包和 Pixi 能力包对 agent 只是两套不同的工具集,切换它不动两阶段角色、也不动三层校验主干。首批两个引擎里 Phaser 有真实现,Pixi 当前留桩。
这张图整体状态是"建",而且它最该让人看清的是那个克制警示——第一版不把五件套建满。如果一上来就把 skill、tool、mcp、rag、脚手架五件全建成抽象接口,而实际只有 Phaser 一个真实现、Pixi 只是个桩,那接口的形状会被 Phaser 这唯一的实现反向决定,等真去接第二个引擎时多半得改。真正的能力包接口要等第二个引擎落地、有两个实现做依据再抽,不为一个实现先建抽象。所以实验阶段只做两件最小的:把九门 harness 的引擎钩子(canvas 选择器、帧计数源)参数化,把 Phaser 的 rag 和脚手架硬编码进 worker,先把这一个引擎跑通。
图底那条绿条标出承袭现行已落的实线部分:九门 harness 的钩子机制本身、A-model 那套 driver 感知分级,都是现行 LittleJS 廉价线已经建好的,tier2 复用它们的哲学、为 Phaser 重写实现,而不是从零新造。
(图源:自治富游戏引擎.md §引擎是能力包不是底座 · tier2实现详设.md §运行时形态)
图 E3 · prompt 两阶段角色
这张图回答"谁在哪个阶段写",并破除一个常见误读:tier2 不是只有一个 agent。它分两阶段,两阶段的 agent 形态故意相反。阶段 1 是工作室设计,用 Agent Team 星形多 agent:一个 leader 分析并拆解用户意图,经 AgentCreate 拉起玩法、关卡、数值、UI、音乐、特效、资产等设计 worker 去发散,再经 TeamSay 把各路结论汇回 leader 收敛成一份设计结论。这一阶段只读加对话——设计 worker 用 PermissionMode.EXPLORE 只读已有工程代码和工程内的设计文档(迭代已有游戏时会用到),并能与用户跨 session 多轮对话,但不写代码。阶段 2 才是单写实现:模板初始化工具铺骨架,把阶段 1 每个设计 agent 的结论写成工程内文档,然后单写 agent 跑 ReAct 多轮写代码,过三层校验,产出一个真 Phaser 源工程。
为什么设计用多 agent、实现用单写,这是两阶段角色最该讲清的道理。设计阶段要的是发散和专业分工,多个 worker 各管一个方面、把可能性铺开,leader 再收敛,这时候多 agent 是优势。实现阶段恰恰相反:经营游戏的多个系统共享同一套状态和约定,如果拆给并行 agent 同时写,几乎必然写出互相不一致的结果,所以实现必须收敛到单写、由一个 agent 持有整个工程的全局视图。图里那个红框拓扑铁律点出了星形的硬约束——worker 只拿到 TeamSay、只能把结果报回 leader,禁止 worker 之间互评或互相喊话,所有协调都过 leader 这个唯一的中心。
红框里还钉了一条容易踩坑的事实:AgentScope 2.0.2 删掉了进程内的 MsgHub 和 pipeline 编排,进程内多 agent 协作那套已经没有了,留下的只有部署态的 Agent Team(TeamCreate / AgentCreate / TeamSay)。工作室必须建在这套 Agent Team 上,而不是去找一个已经不存在的 MsgHub。图里阶段 1 和阶段 2 的内部拓扑都是照 2.0.2 源码逐条核过画的(/root/oss/agentscope),就是为了免得照旧版资料把架构画错。
底部那条蓝带补一句血缘:prompt 生成域承袭现行 studio.py 的多角色 prompt(design / code / fix),tier2 复用它的多角色 prompt 和生成域躯干,是 fork 起步、独立演进,不是照搬。整图的 tier2 专属机制(Agent Team 星形、单写 ReAct 多轮)都画虚线待建,承袭现行的(九门 harness、A-model)画实线。
(图源:tier2实现详设.md §运行时形态:两阶段、service 化与 session 三路径 · 自治富游戏引擎.md §换一种生成方式 + §谁在写:单写者 ReAct)
图 E4 · A-model 4 插件复用
这张图讲 tier2 怎么接住 Mac 那条 A-model 分支已经造好的资产,别重新发明。先要理清两线的关系。A-model 是 Mac 在做的 Tier1 廉价线 agentic 优化,它把廉价线从"声明式数据壳"推进到了"便宜模型自治写真 JS",所以两线的边界不再是过去那个"声明式 vs 自治"的能力档,而是创始人 2026-06-23 重定的引擎/表现层复杂度档:A-model 吃 LittleJS 轻量经营档,tier2 吃 Phaser 重表现富游戏档(肥鹅美食街那一档)。两线分立、不收敛,但 A-model 已经造好的几样东西 tier2 该接住,省掉重复造轮子。
复用的逻辑落在一条论点上:A-model 的 api.d.ts 是引擎无关、零语义的契约,跨得了引擎;而渲染实现绑死在 Canvas 上、跨不了引擎。所以图里那四个插件(scene-fsm 场景状态机、hud-ui 界面、session-score 局内计分、timer-scheduler 定时调度)tier2 都复用它们的契约和命名,只把渲染实现按 Phaser 重做。这就是每张插件卡上那两个徽章的含义——契约复用是数据维度的承袭,渲染按 Phaser 重做是质量维度不降级。横在下面的 sim-business 经营配方卡同理,它是经营和合成的系统骨架配方(数值与系统结构,不是渲染件),tier2 复用配方、用 Phaser 落地数值。
图里还有两块讲接缝怎么对账。九门基线那块:A-model 改过 play.cdp.cjs,加了 SAA-mode 的 __GameBundle 信封、driven 感知的 advisory 分级("driver 缺位就降为只提示、driver 到位就恢复致命")、还有取证用的 _forensicsView。tier2 在 U3/U6 复用它那套分级范式来修 latch 与经营门的 observe→enforce,但 fork 的源和行号锚点要钉到 A-model 合并进 dev/2.0.0 之后的版本重取,而探针本身要为 Phaser 重写——#game-engine 选择器、__engine.frame 帧源、boot 信号全换,这部分是虚线待建。源项目契约那块:A-model 把 source-project.schema.json 升成了 oneOf(1.0/2.0),但它的 2.0 绑死了 __GameBundle 加九门加 ECS-lite 那条 LittleJS 装载路;tier2 的 Phaser 工件走的是另一条装载序列(第二装载分支),所以另立一份独立 schema、不把 3.0 变体加进同一个 oneOf——这是为了避免把 Phaser 的差异焊进 LittleJS 的 keystone 契约。
整图基调是"接":实线框是 A-model 现行已落、承袭即用,虚线框是 tier2 专属待建。最该记住的一条在脚注里——A-model 是 Mac 在飞的分支、还没并进 dev/2.0.0,合并之后这两个接缝(play.cdp.cjs、source-project.schema.json)会刷新,所以实现 tier2 时要以合并后的版本为准对账,别拿当前在飞版本去钉行号。
(图源:plan §与 A-model 分支的关系 · tier2/HANDOFF.md §与 A-model 分支的协调)
3 图清单与状态表
| # | 图名 | 形式 | 状态 | 覆盖内容 |
|---|---|---|---|---|
| E1 | 单写 agent 的 toolkit(阶段 2 · skill 清单) | SVG | 建(演进自 wg1 studio.py) | 九个工具的目的/边界/产出 · 三类角色(核心环 / 取证 / 起手收尾) · 自治内循环形态 · 三条工具边界铁律(单写独占 / finish 共用 schema / 验收零自评) |
| E2 | 引擎能力包 manifest(五件套) | SVG | 建(第一版 Phaser 硬编码 · 通用接口待第二引擎) | 引擎=动态加载的能力包而非固定底座 · skill/tool/mcp/rag/脚手架五件套各管一面 · 换引擎=换工具集非架构重写 · 克制警示(不为一个实现先建抽象) |
| E3 | prompt 两阶段角色 | SVG | 建(阶段 1 Agent Team / 阶段 2 单写 · 2.0.2 API 已核) | 阶段 1 工作室 Agent Team 星形(多 agent 发散+专业分工·只读+对话) · 阶段 2 单写 ReAct(防并行写冲突) · leader-worker 拓扑铁律 · 2.0.2 删 MsgHub 只剩部署态 Agent Team |
| E4 | A-model 4 插件复用 | SVG | 接(复用 A-model 资产 · 合并后对账) | 两线边界(引擎/表现层复杂度档) · 四插件契约复用+渲染按 Phaser 重做 · sim-business 配方复用 · 九门基线 driver 感知分级范式复用 · 源项目契约维持独立 schema |