ycode/docs/专家运行语义核对-20261016.md

专家运行语义核对

日期：2026-10-16。范围：四份 REA 恢复专家包、已保存的原版规范/daemon/renderer 导出，以及 YCode 专家、能力工具与 OMP 接线。原版观察全部来自 REA；没有重新操作原版运行时，没有直接读取原版目录。本轮未发模型请求、未运行专家业务脚本。

结论：已修正“plugin.skills 被当成启动预加载”的语义差异。角色消息层级、maxTurns 和原 CLI 插件/Agent 切换仍未对齐，不能把当前可选专家、资源可读宣称为原运行时等价。

证据身份

原宿主 WorkBuddy 5.8.2，ASAR root SHA 035254bc76310ea46317433e4840602094543ef323d2d5c5aff7c131729de918。所有读取的归档正文先校验其 SHA。

证据	文件 / SHA256	本次使用范围
ev_a4b0f399496f62f4dc41998e8327fb219ab84f3dca536ec6554553605b106735	expert-manager references/agent-md-spec.md，ec7373578a5f84d73ba16dcc71e73755e57aa4170cb07cd9bf379627c0f9c007	Agent YAML skills 启动预加载、maxTurns 规范
同上	references/plugin-json-spec.md，14e1a6b99c74815c22772a54725ba6d34750a6c9db4c75746c1188e31d2504f3	plugin.skills 为 Skill 目录路径资源声明、agentName 为主 Agent 名称
ev_81de6f628a156599f26ca795f6747ad3f8ec108de66fdba6e3723705905716f3	main/module.app-server.js，281666dbf81b76d64f95162a19dd2d02a41b35ec54239e0efc4e8e52419eb125	原会话插件切换与 Agent override
ev_c3df29dcb19c5fcaa9e458b1b9acff92e8c75ac935791e0c81900733e61b6282	main/daemon-app-server-main.js，a3b9d6f3ca17954a89d4e442137348b230c8ea9c74181625556bfae2ffe98154	专家包解析、准备、插件启用和会话绑定
ev_717fa5e846e64d67ac19c8925d121bff632c0d3aefb3603b10858559cabb2dcb	runtime 导出 workbuddy-provider-DkH2YFYM.js，b588e875c469978f216beec86bdf4b6c33a31c0266f9bf996881b8dbf37b5dc7	renderer hydration 的真实选择元数据与发送前配置准备

四包的证据保存在各自 evidence-manifest.json，原始正文由逐文件 retainedExport 定位：

专家	包 root SHA256	Agent MD SHA256 / Evidence
C++ 超级专家	b90023e9622bd74c55d583051bee3625eb491b552baeea17ae10ac792a352498	93306e405cb7e0c4fc94514179031a8fc3d7f25f06a095a728a2dfa4a34da154 / ev_f06dd5bf43984bec8520feadaf2d9b24f7fb6e96acd34de5f91469aa6e561c1f
高级项目经理｜关德豪	304805c85b87e8266294fb3aaf283d45fc71d7977af064fcb1eed1199e9389e6	d9187e37363679e5bb56879d35cdbdb73b319c0344ca157619d1f602db3c5bec / ev_7faf6a7a38f49bf647382424d3e814639dfddd232458326090df4c2729b438fe
UI设计师｜像素君	c9c83df190f0f0f871706d52b7e372f20b7ad63fde739f59cf9181ace1d08afa	d6e54ca64ab54c6d3122ff0114a46d3820cedd1f05a5a14c541afa6a55e654aa / ev_a7ec53f363a1aa9621ef324f4e20a74f0fcc58bb6bac88e129a5b908bd3b6053
高级算法工程师｜小算	44ed0738d809fe492a36c697b0edd53b72ed75549f5b773291d05f9cf4a6c66f	e383e97fda6cff3ebb15c420d0218bbdafa84d0b74d0acf45040866b1361a42c / ev_b55ad8135706d337f9c3f844d5324e154a56aad7f81fcf090d214754f0374d18

skills：资源注册与启动预加载

原 agent-md-spec.md UTF-16 offset 368 起明确给出 skills: [{skill-name}]，说明是“启动时预加载的 Skill”。plugin-json-spec.md offset 757 附近把 skills 放在资源声明表，类型为 Skill 目录路径数组。这是两个不同字段，不能按同一数组处理。

专家	plugin.skills 注册目录	Agent YAML skills	Agent maxTurns
C++	cpp-mastery	cpp-mastery	50
PM	minimax-docx	未声明	未声明
UI	impeccable、frontend-dev、browser-use	未声明	未声明
算法	algorithm-engineering-playbook	algorithm-engineering-playbook	100

修复前 expertTurnContext 无条件把 plugin.skills 下的所有 SKILL.md 完整正文附在专家 prompt 后。PM/UI 因而在普通回合中提前加载所有 Word/设计/浏览器指令，与上述规范字段含义不符。

现在的 Agent 分支：

1. plugin.skills 只注册包内目录，解析每份 SKILL.md 的真实 frontmatter name 和 description，输出按需加载目录。
2. 只有选定 Agent YAML skills 中的名称，且能唯一匹配已注册 SKILL.name，才预加载完整正文。名称与目录 basename 可以不同；不按文件夹名猜测。
3. 无 skills / 空 skills 均不自动加载所有正文。重复选择去重；非法、未注册、歧义名称明确报错。
4. 全部文本资源仍可通过 ycode_expert_resource 按路径读取，原文 SHA 保持。目录提示模型在实际需要技能时先读取完整 SKILL.md。

本地名称检查是显式宿主校验：1–128 位字母/数字起始，后续允许字母、数字、点、下划线、连字符；这不是对所有原版技能命名方式的完整证明。非 agent manifest 的运行语义未在此次扩展，未据此给 skill/plugin 类型新增“可用”结论；现有本地 activation/validation 边界保持。

这次对齐的是预加载选择规则。当前仍每回合生成 capability context，并未实现原插件引擎“Agent 启动一次”的生命周期；不能把选择规则通过称为完整技能调度等价。原版 PM/UI 在真实 CLI 会话何时按需加载技能，本次没有新的运行时 trace，只能依据规范与包字段给出预期。

角色与消息层级

核对时的 YCode 链路：

• expertTurnContext 去掉 Agent YAML 外壳，取角色正文和选定技能，形成 active-expert/skill-directory/package-host context。
• createCapabilitySnapshot 合并该 context 与可用技能信息。
• ipc.ts 将用户 text、附件说明、资源引用和 capabilitySnapshot.context 拼为 promptText。
• OMP 分支将 promptText 交给 OmpKernel.prompt，发送 {type:'prompt',message:...}；没有独立专家 system 参数。
• Gateway fallback 也将同一 promptText 放入 user 消息；其 system 仍是通用 YCode coding assistant 文本。历史 user capabilityContext 会继续参与回放。

因此当前角色与技能是用户消息中的附加文本，不是已证实的独立系统层配置；UI 助理头像/身份快照也不能证明后端 Agent 切换。

原版静态链路是包/Agent 运行配置：

• assemblePreparedFacts [101864,102658) 解析实际 Agent prompt 并形成 prepared facts；函数体 SHA beac3fb7291ff761f0a8e8f8435ac6a18dcc6f6a40d7a21f443d9d39d2671d77。
• applyPreparedExpertSettings [112541,113125) 注入 enabledPlugins/marketplace 配置，函数体 SHA bb5f347e4eec6e8d7a49544a801b15d4cd8e95ae816233257c059640e9eab60d。
• activateExpertRuntimeForSession [122030,123704) 以 pluginName/agentName/sourcePluginId 做会话绑定；函数体 SHA debd8d43e02342b90958ffafb04672a02f08741be172b01cfa3fa0aad919ef0f。

这证明原版会做插件/Agent override，尚不能证明其最终上游请求具体使用 system/developer 哪个 role、如何保留基础系统指令、动态切换如何改写历史。当前保存的规范/daemon 导出没有原 CLI 模型请求序列；不把普通增强提示或 handoff 的 systemPrompt 示例当作专家链路证明。

保存的 REA runtime provider 导出也做了复核：hydrateSelectedExpertForRuntime [431496,433326) 会读取本地/目录专家，保留 prompt、defaultInitPrompt、pluginRegisteredName、agentName、marketplace、expertRootDir；发送前 ensureSessionLaunchConfigBeforePrompt 还会等待会话配置更新并 hydrate。该字段链说明“选中专家”包含实际运行配置，不只展示名；仍不能据此推断上游 message role。本次查询脚本先核验了归档 339 项正文 SHA，没有操作原版 UI。

本机 YCode 使用的 OMP 只读检查：--version 返回 omp/18.6.3；--help 成功，stdout SHA 437cbc3126153d271efe7846653ff8577bd860c80f2c30bc1122531a59f6a107，公开 --system-prompt、--append-system-prompt、--system-prompt-template，以及 --no-skills/--skills。当前 OmpKernel argv 未使用这些 system flags。没有验证动态 RPC set_system_prompt，更不能猜一个新 RPC 命令就宣称成功。

可修方向是把当前专家角色与普通用户正文分离，在有证据和真实受控请求验收后接入宿主系统上下文；需要同时验证同会话切换/移除、历史分支、重启恢复及 Gateway fallback。此轮没有改 IPC、OMP 或 role 层级。

agentName、maxTurns 与插件切换

agentName 当前用于选择 agents/<agentName>.md 和生成 expert-v2 runtimeIdentity。算法包尤其需要区分：plugin.name 是 senior-algorithm-expert，Agent 文件/YAML name 是 senior-algorithm-engineer。现有文件定位与身份映射通过了真实四包验证。

但 OMP 启动参数只有 mode/profile/model/cwd/no-tools/session-resume；未把该 agentName 注册为 OMP 主 Agent。help 的 omp agents 管理 bundled task agents 也不能被解释为已经支持原版主 Agent override。

maxTurns 当前可从 YAML 读到，但没有交给 OMP，也没有映射到原 agent 循环预算。C++ 50、算法 100 均尚未生效；Gateway 的 maxToolRounds 是另一套配置，不能冒称等价。原规范 normal 默认50、team建议150–200，不足以确定 maxTurns 在原 CLI 内精确计数的是哪种事件，也不能直接用用户消息数或工具次数代替。

原 switchExpertPluginForSession（module.app-server [70565,73626)，函数体 SHA 71c39f763eb4880951c1f48cf256c70608e79c548d4ff04a8c42307622b78cac）会：

• 找到真实会话 endpoint，注册 marketplace、检查/materialize 版本，禁用遗留专家插件。
• POST /api/v1/plugins/switch，persist:false，含 enable/disable、agentName、sourcePluginId。
• 自建 my-experts 特例先启用插件，再发第二次 Agent override refresh。

当前 YCode 是专家 ID 的会话持久化、真实包读取/资源工具与角色文本适配；没有复刻这套原 CLI 插件状态机。OMP kernel 复用依据当前 cwd/model fingerprint，expertId 改变并不是独立 Agent runtime 重建条件。当前更新会话专家会拒绝正在运行的会话，下一回合重取新包，但旧 OMP transcript 中的 user 角色指令仍存在；只有文字层变更尚不能证明干净切换。

已实现与待接证据

项目	状态
角色原文、文件/头像/技能资源 SHA	已验证
Agent YAML skills 选择性预加载	本轮修正并验证
PM/UI 技能按目录可发现、全文按需读取	本轮验证
激活 defaultInitPrompt 来自同一 validated document	保留根上下文新接口，四包验证
独立系统层角色注入与动态移除	未对齐；未猜 RPC
Agent maxTurns	未对齐；没有假预算映射
原 CLI 插件/Agent 生命周期与切换	未对齐；有静态 switch 契约，缺 OMP 等价证明
非 agent / 专家团调度	本轮未扩展，不能由四包 agent 测试外推

下一步所需证据：原 CLI 的 Agent YAML loader/skill preload实现及计数器；受控原版专家首回合/第二回合/切换/移除的消息层级与运行事件；OMP 系统上下文可用接口的官方/本机 RPC 契约与受控 loopback 请求验证。本轮没有通过其他渠道补采原版。

验证与修改文件

实际结果：

• node scripts/test-expert-preloading.mjs：15/15 PASS，报告 .tmp/imported-expert-qa-preloading-KuCSlK/report.json。包含不存在/空/选择性/重复/非法/未注册/歧义/目录别名等边界。
• node scripts/test-imported-expert-resources.mjs：370/370 PASS，四个真实导入包、197 个资源全文 SHA、54 个 UI 字体和两份 BOM csproj 保持；PM/UI 无全文预载、C++/算法各预载唯一声明技能。报告 .tmp/imported-expert-qa-Q43MkK/report.json。
• node scripts/test-experts-backend.mjs：真实隔离 Electron 59+14=73/73 PASS，.tmp/experts-backend-OQBtJR。旧 fixture 改成真实 SKILL frontmatter 和 Agent skills 声明，保留全文预载断言，没有放宽新规则。
• node scripts/test-expert-integration-snapshot.mjs：15/15 PASS，.tmp/expert-review-snapshot-TDMUIy/report.json。
• node/web TypeScript 均通过。没有构建用户正在运行的 out、没有业务脚本/模型 API 验收。

四包测试源快照：experts.ts SHA 26de0cd06964b84f9b0f029ea01eb3c998d86a098b519a99738fd388a808ae2a；runtime.ts SHA 3237e650a2941019968168efe54ce164e2351cdd7fd17bbd829427607f5f8750。测试报告还记录其余被测源码及 bundle SHA。

本子任务修改：

• src/main/capabilities/experts.ts：仅 expertTurnContext 的技能目录/预加载逻辑。
• scripts/test-imported-expert-resources.mjs：按真实 Agent YAML 校验选择性预加载，兼容并验证原子激活返回 defaultInitPrompt。
• 新增 scripts/test-expert-preloading.mjs。
• scripts/test-experts-backend.mjs：修正技能 fixture 格式和显式预加载声明。
• 本文与隔离 .tmp 测试报告。

未改 activateExpert、shared activation 类型、IPC、OMP、runtime.ts、页面或用户目录。根上下文另行同步导入 helper 的 Agent YAML 校验，该修改不归本子任务所有。