130 lines
13 KiB
Markdown
130 lines
13 KiB
Markdown
# 专家运行语义核对
|
||
|
||
日期：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 校验，该修改不归本子任务所有。
|