诊断报告 · ClaudeA Plan 质量分析
触发:用户 2026-05-19 18:00 报告 "ClaudeA 进展不顺 · shell 顶部工具栏没自动按五段实现 / 卡在底部比例显示分频 / 卡在锁定悬浮"
诊断方:AIOS 调度内核
范围:对照 4 份输入(layout-demo / REFACTOR-v4-PLAN / PROMPT-shell-slot-store / frontend_vue3 实际代码)· 评估 plan 质量
结论一句话:plan 不是粗糙,而是"语义鸿沟"——demo 端的"窗口管理"基础设施在 PROMPT 中被默认省略了,导致 ClaudeA 把它当成"业务",而不是"必做的地基"。
1. TL;DR(给人类的 30 秒结论)
| 维度 | 评分 | 说明 |
|---|---|---|
| 任务粒度 | ⭐⭐⭐⭐ ⅘ | PROMPT 487 行 · Step 1-4 + 验收清单详尽,粒度 OK |
| 架构方向 | ⭐⭐⭐⭐⭐ 5/5 | Slot Store 模式正确 · ClaudeA 已落地基本骨架 |
| 范围完整性 | ⭐⭐ ⅖ | 只覆盖了"内容注入"· 漏掉了"窗口管理基础设施" |
| 术语一致性 | ⭐⭐ ⅖ | "五段"概念在 plan 中未明确定义 · ClaudeA 与你对"五段"理解不同 |
| 验收可执行性 | ⭐⭐⭐ ⅗ | 验收 7 条偏功能性 · 缺"按 demo 视觉对齐"的硬性截图比对 |
根因:PROMPT-shell-slot-store.md 把 demo 中已存在的"窗口管理"基础设施(ratio-tools / split-tools / locked vs floating / resize handle / dock 四向 / localStorage 持久化)默认为"已知前提",但 Vue 端是从零起步的 —— ClaudeA 看不到 demo 里那 200+ 行 CSS 与 100+ 行 JS,自然不会自动实现。
结果:ClaudeA 实现了 Slot Store 数据流(已 OK),但卡在了 demo 里"用户视为理所当然"的窗口管理细节上。
2. 三方对照证据矩阵
2.1 顶栏"五段"对齐分析
| 段位 | demo(REFACTOR-v4-PLAN §3.1) | PROMPT-shell-slot-store(派给 ClaudeA) | frontend_vue3 实际 |
|---|---|---|---|
| ① Stage Pills(stage 切换) | ✅ 行 1 左段 4 pill | ⚠️ 未提及 | ⚠️ StageBar 中硬编码 4 stages(不读 store) |
| ② mode-switcher | ✅ 行 1 中段 chip | ✅ §2.1 modes + setModes |
✅ 已实现 · 从 shellSlots.modes 读 |
| ③ stageToolbar | ✅ 行 1 右段左侧 | ✅ §2.1 toolbar + setToolbar |
✅ 已实现 · 从 shellSlots.toolbar 读 |
| ④ 音频引擎全局组(▶ ■ 🔄 ●) | ✅ 行 1 右段中部 | ❌ PROMPT 完全未提 | ❌ 完全缺失 · audioEngineStore 已建但未挂顶栏 |
| ⑤ 浮窗+锁+主题+License | ✅ 行 1 右段尾部 | ❌ PROMPT 完全未提 | ⚠️ 部分散落在 XiStudioShell · 非"段化"组织 |
| ⑥ doc-tabs 行 2(sub-tabs-bar) | ✅ 行 2(仅 XL/XT) · .with-subtabs-bar 切换 |
⚠️ §2.1 docTabs 字段有 · 但未提"双行顶栏 70px"机制 |
⚠️ SubTabs.vue 已建 · 但 with-subtabs-bar class 切换待核 |
关键证据:StageBar.vue template 只有 4 个段(stage pills + mode-switcher + history-group + stageToolbar)· 缺音频引擎组 + 浮窗+锁+主题段。这两段在 demo 里是 Shell 级、跨 Stage 共用的(REFACTOR-v4-PLAN §3.1 行 76 明示),不是 Stage 注入的,所以 ClaudeA 在写 Slot Store 注入逻辑时根本不会自动想到要做。
这就是用户说的"shell 顶部工具栏没自动按五段实现"的根因 —— PROMPT 里就没让 ClaudeA 做!
2.2 窗口管理基础设施对齐分析
| 特性 | demo(index.html + codex.css §15) | PROMPT-shell-slot-store | frontend_vue3 实际 |
|---|---|---|---|
locked vs floating 双模式(.ide.locked) |
✅ 完整实现 + ⌘\ 快捷键 | ❌ PROMPT 未提 | ✅ layoutStore.locked + toggleLock() 已实现 |
| dock 四向位置切换(left/right/top/bottom) | ✅ 完整 + CSS grid 切换 | ❌ PROMPT 未提 | ✅ layoutStore.dockPos + setDockPos() 已实现 |
| 高度比例 ratio-tools(½、⅓、¼) | ✅ 仅 top/bottom dock 显示 | ❌ PROMPT 未提 | ⚠️ layoutStore.ratio 已建 · 但 DrawerHeader 是否渲染按钮组待核 |
| drawer 内部 split(横/纵 + 拖拽 handle) | ✅ split-tools + split-handle | ❌ PROMPT 未提 | ⚠️ layoutStore.split/splitDir/splitRatio 字段建了 · 但 DrawerLeft/Right 模板没渲染第二个面板(只有单 component) |
| drawer 边缘 resize handle 拖拽 | ✅ 4 个边各一个 | ❌ PROMPT 未提 | ⚠️ useWindowResize 已建 · 但 DrawerLeft 只挂了 1 个右侧 handle |
localStorage 持久化(key: xistudio-layout-v1) |
✅ 完整 saveLayout/loadLayout | ❌ PROMPT 未提 | ❓ layoutStore 是否 persist 待核 |
dl-open / dr-open / b-open 状态机 |
✅ Shell DOM 三 class | ❌ PROMPT 未提 | ⚠️ layoutStore.drawerLeft.visible 字段对应 · 命名不同 |
结论:demo 的窗口管理体系(约 400 行 CSS + 200 行 JS)完全没出现在 PROMPT 里,但 ClaudeA 已经"凭直觉"建了 layoutStore + useDrawerDock + useWindowResize —— 说明 ClaudeA 看到了 demo 自学的,但 plan 没派任务、没验收、没截止 → ClaudeA 自己加任务自己卡进度。
这就是用户说的"卡在底部比例显示分频 / 锁定悬浮"的根因 —— 不是技术难,是任务没被 plan 显式承认。
2.3 verifications 验收标准对齐分析
PROMPT §「验收标准」7 条:
| # | 验收条目 | 是否覆盖窗口管理 |
|---|---|---|
| 1 | tsc --noEmit 全绿 | ❌ 不覆盖 |
| 2 | vitest run 全绿 | ❌ 不覆盖 |
| 3 | playwright 全绿(含新增 shell-slot-injection.spec) | ❌ 不覆盖 |
| 4 | 路由 /xilink → ActivityBarLeft 显示 5 图标 | ❌ 不覆盖 |
| 5 | 路由 /xitune → ActivityBarLeft 自动变空 | ❌ 不覆盖 |
| 6 | 路由切回 /xilink → 5 图标重现 | ❌ 不覆盖 |
| 7 | 引擎按钮 toggle:true 切换 + 跨 stage 状态保留 | ⚠️ 仅引擎状态 · 不含五段视觉 |
结论:验收 7 条全部围绕"slot 注入数据流"· 零条要求"视觉对齐 demo"。这就是为什么 ClaudeA "技术验收过了但用户体感很差" —— 验收标准本身就漏了视觉/窗口管理这条线。
3. 根因分类(回答用户的问题)
3.1 用户原问题:"是 plan 写得太粗糙 还是 功能定义不详细?"
两个都不是,真正的问题是第 3 类 —— 范围漏档 + 术语未定义。
| 用户怀疑 | 我的判断 | 证据 |
|---|---|---|
| plan 太粗糙? | ❌ 否 | PROMPT 487 行 + 4 步法 + 代码骨架直贴 · 粒度足够 |
| 功能定义不详细? | ❌ 否(单看 slot store 范畴) | §2.1 字段表 18 项一一列出 · 接口签名给到 |
| 范围有漏档? | ✅ 是 | demo 的"窗口管理基础设施"完全不在 PROMPT 范围内 → ClaudeA 不知道要做就是要做 |
| 术语未定义? | ✅ 是 | "五段"在 PROMPT 里未明确列出是哪五段 → ClaudeA 与用户的"五段"理解不同(用户=demo §3.1 那 5 段 / ClaudeA=Slot Store §2.1 文档里能 setXxx 的那些段) |
3.2 二级根因分析
ClaudeA 进展不顺
├── R1【plan 范围漏档】 demo 的窗口管理体系未派 →【高频致命】
│ ├── ratio-tools(1/2 1/3 1/4) → 用户说"卡在底部比例显示分频"
│ ├── locked vs floating → 用户说"卡在锁定悬浮"
│ ├── 内部 split + 拖拽 handle → 用户没说但 layoutStore 字段已建未渲染
│ └── localStorage 持久化 → 关键 UX 但无验收
├── R2【术语未对齐】"五段"含义双方不同 →【中频致命】
│ └── 用户期望 = 顶栏视觉 5 段(stage / mode / toolbar / engine / shell-utils)
│ ClaudeA 理解 = Slot Store 18 字段中"能动态注入的几段"(modes / toolbar / docTabs / status / hint)
├── R3【验收维度单一】缺"视觉对齐 demo"硬验收 →【高频但可补救】
│ └── 现有验收全在功能流 · 缺截图比对 / 像素级回归
└── R4【源-目标语义映射缺失】demo 用 postMessage 协议 / Vue 用 Pinia · 但映射表只在 Phase 0 §3.2 一行带过
└── doc-tabs-inject / mode-switcher-inject 等协议名 → setDocTabs / setModes 等 action 名 → 中间没"为什么这样映射"的说明
3.3 不是问题的"伪问题"
- ❌ 不是 ClaudeA 偷懒(它已经主动建了 layoutStore + useDrawerDock,远超 PROMPT 要求)
- ❌ 不是架构选错(Slot Store 模式 + Pinia 完全对得上 demo 的 postMessage 协议表)
- ❌ 不是粒度太粗(PROMPT 4 步法已经够细)
4. 给人类的拍板项(请逐项确认)
4.1 立即追加 PROMPT 补丁(我可起草 · 不写业务代码)
我建议给 ClaudeA 派一个 PROMPT-shell-slot-store-PATCH-01.md,补充以下三类内容:
- 窗口管理基础设施任务清单(Phase 1 内独立 Step 5,必须做):
- locked vs floating 双模式 + ⌘\ 快捷键 + persist 到 localStorage
- drawer 四向 dock 切换(DrawerHeader 增加 dock-tools 按钮组)
- top/bottom dock 时 ratio-tools(½、⅓、¼)显示 + 切换
- drawer 内部 split(横/纵)+ split-handle 拖拽改比例
- 4 边 resize handle(目前只有 1 个右侧)
-
localStorage 持久化(key:
xistudio-layout-v1· 与 demo 同 key 便于联调) -
顶栏五段定义补丁(明确术语):
- 段①:Stage Pills ·
XiStudioShell.vue主导 · 从 stageStore + licenseStore 读 · 不归 shellSlotsStore 管 - 段②:mode-switcher · shellSlotsStore.modes(已 OK)
- 段③:stageToolbar · shellSlotsStore.toolbar(已 OK)
- 段④:音频引擎全局组 ·
audioEngineStore直接读 · 在XiStudioShell.vue顶栏渲染 · 不在 StageBar 里(因为跨 stage 共用) -
段⑤:浮窗+锁+主题+License · 各自独立 store · 在
XiStudioShell.vue顶栏右段渲染 -
视觉验收清单:
- 启动 dev server + 打开 layout-demo/index.html · 同屏对照截图 · 关键 5 处必须像素级一致(顶栏 / 双行顶栏 / drawer ratio / locked 切换 / split)
- 加 e2e:
shell-window-management.spec.ts覆盖 ratio + split + locked 切换
4.2 流程改进项(避免下次再发生)
| # | 建议 | 触发时机 |
|---|---|---|
| 1 | PROMPT 起草前先做 demo 全特征清单(scoping pass) | 每个新 PROMPT |
| 2 | 术语对齐表(用户说的 X = plan 中的 Y = 代码中的 Z) | 每个 PROMPT 开头 |
| 3 | 验收必须含视觉对照项(截图 diff / Storybook) | 所有 UI 类 PROMPT |
| 4 | Step 收口前 ClaudeA 必须发 demo 对照截图 · AIOS+人类 review | 每个 Step |
| 5 | plan 与 demo 出现"语义鸿沟"时,优先 PATCH 不要全篇重写 | 增量优于推倒 |
4.3 是否需要 ADR
✅ 建议起 ADR-AIOS-02:PROMPT 派发的"demo 全特征 scoping pass"流程
理由:这次问题不是单点失误,是流程规范缺失 —— 任何"基于 demo 做 Vue 化"的 PROMPT 都会再踩同一个坑。需要把"先做 demo 全特征清单"写入 SOP。
5. 执行建议(等你拍板后我做的事)
| 你说 | 我做的事 |
|---|---|
| "起草 PATCH-01" | 我用 1 次 write_to_file 起草 PROMPT-shell-slot-store-PATCH-01.md · 含 §4.1 三类内容 · 你审过即可派给 ClaudeA |
| "起草 ADR-AIOS-02" | 我起 ADR 草稿 · 走 Conflict-Resolution.md 的 4 级流程 |
| "都不用 · 我自己跟 ClaudeA 沟通" | 我把诊断报告 commit 入库 · KANBAN §5 阻塞清单加一条"shell-slot-store 范围漏档 · 已诊断 · 等待 PATCH" |
| "先看代码再说" | 我可继续 use_subagents 抽样读 stage 端实现 · 但建议先拍板 §4.1 |
6. 不下场写代码的原则声明
按 .clinerules/aios-orchestration.md §角色声明:调度 10% · 不写业务代码 · 我不会去改 layoutStore.ts / DrawerLeft.vue / StageBar.vue。所有补救都通过派 PATCH PROMPT 给 ClaudeA 完成。
唯一例外(本文件):AIOS 自己的诊断报告写入 40-aios/ 知识库 · 属于"调度产物" · 不属于"业务代码"。
诊断报告 v1.0 · 2026-05-19 · AIOS 调度内核出具 · 等待人类拍板下一步动作