Phase 005: vendor ArkScope, land the Arco style baseline, and fix bridge interpreter resolution

- Vendor ArkScope decorative layers (ScrambleTitle / IsometricWave) with provenance notes; decorative-only per AGENTS.md red lines
- Migrate theme tokens to Arco, register the Arco theme, and add hook adapter composables (useMessage / useDialog / useNotification) with matching signatures
- Sample pages: LoginView and AppSidebar on the new baseline; docs/arco-mapping.md and docs/ui-baseline.md land
- agent-bridge: prefer the PM-selected venv from facts.json over legacy in-tree venvs (legacy lacks the mcp extra, so every MCP server showed 0 tools / not connected)
- agent-bridge python (vendored, deliberate deviation): MCP discovery import fallback and pyyaml -> hermes_yaml so plugins and MCP work under the PM env; install the mcp extra via `hermes pm install --extra mcp`
- Chat-chain fragment: docs/chat-chain-changes/2026-10-17-phase005-arkscope-baseline.md

Verified: harness:check, test (2020 passed), test:e2e (30 passed), build all green; manual: plugins 100/0 warnings, MCP 6/6 servers connected with 104 tools.

docs/arco-mapping.md

@@ -0,0 +1,65 @@
+# Naive UI → Arco Design Vue 组件映射表
+
+Phase 005 起，新代码与迁移代码一律使用 Arco Design Vue。本文表是迁移的唯一映射依据：
+**先查表，再改代码**。表中没有的组件，先在此表补一行再动手。
+
+- 全局注册：`main.ts` 全量 `app.use(ArcoVue)`，不做按需引入
+- 主题：`body[arco-theme='dark']`（见 `styles/arco-theme.ts` 与 `docs/ui-baseline.md`）
+- hooks：`useMessage` / `useDialog` / `useNotification` 适配层在 `packages/client/src/composables/`，
+  签名冻结，**不得**在页面里直接 import Arco 的 `Message` / `Modal` / `Notification`
+
+## Provider / hooks
+
+| Naive | Arco | 备注 |
+|---|---|---|
+| `NConfigProvider` | 直接用 `body[arco-theme]` | 不需要组件 |
+| `NMessageProvider` / `useMessage` | `composables/useMessage.ts` | 适配层，签名冻结 |
+| `NDialogProvider` / `useDialog` | `composables/useDialog.ts` | `positiveText→okText`、`onPositiveClick→onBeforeOk`（resolve false / reject → 保持打开）由适配层转换 |
+| `NNotificationProvider` / `useNotification` | `composables/useNotification.ts` | `description→content` 由适配层转换 |
+
+## 基础组件（按当前仓库用量排序）
+
+| Naive | Arco | 用量 | 备注 |
+|---|---|---|---|
+| `NButton` | `a-button` | 732 | `block`→`long`、`size="tiny"`→`size="mini"`、`type="warning"`→`type="primary" status="warning"`、`quaternary`→`status="secondary"` |
+| `NInput` | `a-input` / `a-textarea` | 160 | `type="textarea"` 用独立 `a-textarea`；`a-input` 关闭了 attrs 透传，`autofocus` 无效，需 `ref` + `focus()` |
+| `NModal` | `a-modal` | 138 | `v-model:show`→`v-model:visible`；`preset="dialog"` 无对应，信息型弹窗用 `:footer="false"`（`footer` 为 Boolean prop，默认 true） |
+| `NFormItem` | `a-form-item` | 136 | 校验规则 API 不同（`rules` 结构、`required` 表达式）需适配 |
+| `NSelect` | `a-select` | 97 | `options` 的 `label/value` 语义一致；`consistent-menu-width` 等 prop 无对应 |
+| `NSpin` | `a-spin` | 86 | `show`→`loading` |
+| `NTooltip` | `a-tooltip` | 76 | `trigger="hover"` 默认一致；`placement` 语义基本一致 |
+| `NTag` | `a-tag` | 57 | `bordered` prop 存在（默认 true）；`size="small"` 一致；naive `type="info"`→`color="arcoblue"` 等内建色（`red/orange/green/arcoblue/...`），自定义色用 `color` 传 CSS 颜色 |
+| `NSwitch` | `a-switch` | 53 | `value`/`v-model` 一致 |
+| `NSpace` | `a-space` | 51 | `size` 语义一致（数字/预设名） |
+| `NInputNumber` | `a-input-number` | 43 | `min`/`max`/`precision` 一致 |
+| `NPopconfirm` | `a-popconfirm` | 36 | `positive-text`→`ok-text`；`@positive-click`→`@ok` |
+| `NForm` | `a-form` | 32 | 校验规则 API 不同，需适配 |
+| `NTabPane` | `a-tab-pane` | 30 | `NTabs/NTabPane` → `a-tabs/a-tab-pane` |
+| `NDrawer` / `NDrawerContent` | `a-drawer` | 27 | Arco 无独立 content 组件；`footer` slot 用 `a-drawer` 的 `footer` |
+| `NDropdown` | `a-dropdown` | 25 | `options` 结构不同（`label`→`content`，需转换函数） |
+| `NDescriptions` / `NDescriptionsItem` | `a-descriptions` / `a-descriptions-item` | 19 | 基本一致 |
+| `NAlert` | `a-alert` | 19 | `type` 一致；`show-icon` 一致 |
+| `NRadioButton` / `NRadioGroup` / `NRadio` | `a-radio`（`type="radio-button"`）/ `a-radio-group` | 32 | Arco radio-button 是 `a-radio` 的 `type` prop |
+| `NCheckbox` / `NCheckboxGroup` | `a-checkbox` / `a-checkbox-group` | 17 | `options` 数组语义一致 |
+| `NEmpty` | `a-empty` | 12 | 基本一致 |
+| `NCollapse` / `NCollapseItem` | `a-collapse` / `a-collapse-item` | 24 | `arrow` 语义不同 |
+| `NUpload` | `a-upload` | 9 | `file-list` 结构不同，需适配 |
+| `NText` | `<a-typography>` / 原生 `span` | 8 | 多数场景直接用原生元素 + class |
+| `NTabs` | `a-tabs` | 6 | 见 NTabPane 行 |
+| `NBreadcrumb` / `NBreadcrumbItem` | `a-breadcrumb` / `a-breadcrumb-item` | 8 | 基本一致 |
+| `NDataTable` | `a-table` | 4 | **列定义 API 差异最大**（`columns`/`render`/`slots`），逐例处理 |
+| `NSlider` | `a-slider` | 3 | 基本一致 |
+| `NScrollbar` | `a-scrollbar` | 3 | Arco 全局可用，无需组件包裹注册 |
+| `NPopselect` | `a-select`（`trigger-element`） | 3 | 无直接对应，改用 `a-dropdown` 或带 trigger 的 `a-select` |
+| `NPopover` | `a-popover` | 3 | `trigger` 语义有差异 |
+| `NIcon` | `<icon-*>`（`@arco-design/web-vue/es/icon`） | 3 | Arco 图标是独立组件，需 import |
+| `NBadge` | `a-badge` | 3 | `value`→`count` |
+| `NTree` | `a-tree` | 2 | 结构差异大，逐例处理 |
+| `NCard` | `a-card` | — | 当前仓库未直接使用；若出现按此映射 |
+| `NProgress` | `a-progress` | — | 当前仓库未直接使用；若出现按此映射 |
+| `NLayout` / `NLayoutSider` | `a-layout` / `a-layout-sider` | — | 当前仓库未使用（侧栏是手写 div），保持手写或按需引入 |
+
+## 迁移批次（Phase 006/007 使用）
+
+- Phase 006：聊天页（`components/hermes/chat/`）——消息气泡内部**不用** Arco 组件（性能红线）
+- Phase 007：其余视图 + `stores/` + `composables/` 批量替换 + 删除 naive-ui 依赖

docs/chat-chain-changes/2026-10-17-phase005-arkscope-baseline.md

@@ -0,0 +1,61 @@
+---
+date: 2026-10-17
+pr: pending
+feature: Phase 005 - ArkScope vendor, Arco theme baseline, and bridge environment fixes
+impact: No chat-chain behavior change; chat components only swap naive-ui rendering for Arco/theme-token rendering and route hooks through the new composables, while the bridge manager prefers the PM-selected venv so MCP/plugin discovery works again.
+---
+
+# Phase 005 — ArkScope vendor + style baseline
+
+Phase: `docs/phases/phase_005.md`
+
+## What Changed
+
+Phase 005 vendors ArkScope decorative layers, migrates the theme to Arco
+tokens, and lands two sample pages (LoginView, AppSidebar). Chain-adjacent
+files touched:
+
+- `packages/client/src/components/hermes/chat/*.vue` — rendering-layer only:
+  naive-ui components replaced with Arco equivalents or native markup, and
+  `useMessage` / `useDialog` / `useNotification` imports moved to the Phase 005
+  composables (`packages/client/src/composables/useMessage.ts` etc., same
+  signatures). Chat run flow, store logic, and keyboard handling were not
+  modified; `MarkdownRenderer.vue` changes are style-token only.
+- `packages/client/src/components/hermes/group-chat/*.vue` — same rendering-layer
+  swap as above.
+- `packages/server/src/services/hermes/agent-bridge/manager.ts` — interpreter
+  resolution now prefers the PM-selected venv recorded in
+  `<hermesHome>/installs/<key>/facts.json` (sha256 of the resolved agent root)
+  before the legacy in-tree `.venv`/`venv` trees. The legacy venv lacks the
+  `mcp` extra, which made every MCP server report `connected: false` with zero
+  tools. `explicitPython` / `HERMES_AGENT_BRIDGE_PYTHON` still wins first.
+- `packages/server/src/services/hermes/agent-bridge/python/bridge_server.py` /
+  `bridge_runtime.py` — vendored read-only bridge got compatibility fixes:
+  MCP registry import fallback (`mcp_tool_discovery`), and `_read_mcp_config`
+  now imports `hermes_yaml` when `pyyaml` is absent (PM env has no `yaml`).
+- `packages/server/src/services/hermes/agent-bridge/README.md` — documents the
+  new interpreter resolution order.
+
+## Contract Check
+
+`/chat-run` event names, field names, field types, and emission timing are
+unchanged (no bridge protocol fields were added or altered; only the Python
+interpreter the bridge runs under changed). No run dispatch, session, or
+usage-recording behavior changed.
+
+Note: `agent-bridge/python/` is marked read-only in AGENTS.md; the two bridge
+python fixes above are deliberate deviations to keep the vendored bridge
+importable under the PM environment, called out for review.
+
+## Verification
+
+```bash
+npm run harness:check
+npm run test
+npm run test:e2e
+npm run build
+```
+
+Manual: bridge resolves to the PM venv (`installs/.../venv/bin/python3`),
+`mcpList` returns 6/6 servers connected with 104 tools, plugins list returns
+100 plugins / 0 warnings.

docs/phases/phase_005.md

@@ -153,7 +153,7 @@ export const arcoTheme = {
 
 ```ts
 import ArcoVue from '@arco-design/web-vue'
-import '@arco-design/web-vue/dist/arco-vue.css'
+import '@arco-design/web-vue/dist/arco.css'
 app.use(ArcoVue)
 ```
 

docs/ui-baseline.md

@@ -0,0 +1,134 @@
+# UI 基线（Phase 005 定稿）
+
+本文件是 hermes-ui 的**视觉语言唯一依据**。Phase 006/007 的批量迁移照此执行，
+页面样式与本文冲突时，以本文为准；本文没覆盖的场景，先在 `docs/arco-mapping.md`
+补映射、再回本文补约定，然后才动代码。
+
+- 样板页：`views/LoginView.vue`（装饰位面 + 表单）、`components/layout/AppSidebar.vue`（导航 + 弹窗 + tag）
+- 令牌源：`packages/client/src/styles/variables.scss`（CSS 变量）+ `styles/arco-theme.ts`（Arco 组件主题）
+- 组件映射：`docs/arco-mapping.md`
+
+---
+
+## 1. 色板
+
+黑白水墨（Pure Ink）——**纯黑白灰，无彩色**（status/info 色除外）。三主题：ink light / ink dark / comic。
+
+### 浅色（`html:not(.dark)`）
+
+| 角色 | 变量 | 值 |
+|---|---|---|
+| 页面底 | `--bg-primary` | `#fafafa` |
+| 次级底 / 侧栏 | `--bg-secondary` / `--bg-sidebar` | `#f0f0f0` / `#f5f5f5` |
+| 卡片 / 输入底 | `--bg-card` / `--bg-input` | `#ffffff` |
+| 分割线 | `--border-color` / `--border-light` | `#e0e0e0` / `#ebebeb` |
+| 强调色 | `--accent-primary` / `--accent-hover` | `#333333` / `#1a1a1a` |
+| 正文 | `--text-primary` / `--text-secondary` / `--text-muted` | `#1a1a1a` / `#666666` / `#999999` |
+| 状态 | `--success` / `--error` / `--warning` / `--accent-info` | `#2e7d32` / `#c62828` / `#f57f17` / `#4a90d9` |
+
+### 深色（`.dark`）
+
+| 角色 | 变量 | 值 |
+|---|---|---|
+| 页面底 | `--bg-primary` | `#1a1a1a` |
+| 次级底 / 侧栏 | `--bg-secondary` / `--bg-sidebar` | `#252525` / `#202020` |
+| 卡片 / 输入底 | `--bg-card` / `--bg-input` | `#2a2a2a` |
+| 分割线 | `--border-color` / `--border-light` | `#3a3a3a` / `#333333` |
+| 强调色 | `--accent-primary` / `--accent-hover` | `#e0e0e0` / `#f5f5f5`（反相） |
+| 正文 | `--text-primary` / `--text-secondary` / `--text-muted` | `#e0e0e0` / `#a0a0a0` / `#888888` |
+| 状态 | `--success` / `--error` / `--warning` / `--accent-info` | `#66bb6a` / `#ef5350` / `#ffb74d` / `#6ba3d6` |
+
+- 需要 `rgba()` 透明度时用配套 `--*-rgb` 变量（如 `rgba(var(--accent-primary-rgb), 0.12)`）。
+- 反色场景（强调底上的字）一律用 `--text-on-accent`，不要硬编码白/黑。
+- **Arco 组件配色**：`arco-theme.ts` 冻结 `colorPrimary: #2f2f2f`、`borderRadius: 6`，
+  延续克制灰阶；暗色由 `body[arco-theme='dark']` CSS 变量覆盖承载，
+  **不用** Arco 的 dark theme + overrides 双轨。
+- 主题切换机制：`useTheme.ts` 同时切 `<html>` 的 `dark`/`comic` class（项目令牌）
+  和 `arco-theme` 属性（Arco 组件）；FOUC 脚本内联在 `index.html`，两边同步改。
+
+## 2. 圆角 / 间距 / 字号阶梯
+
+**圆角**（`$radius-*`）：
+
+| token | 值 | 用途 |
+|---|---|---|
+| `$radius-sm` | 6px | 按钮、输入框、小卡片、tag（与 Arco `borderRadius: 6` 对齐） |
+| `$radius-md` / `$radius-lg` | 8px | 面板、弹窗、大卡片 |
+
+**间距**：4px 基数，常用档 `4 / 8 / 12 / 16 / 24 / 32`（组件内边距多用 12/16，区块间 24/32）。
+布局尺寸：侧栏 240px（折叠 64px）、顶栏 60px、移动端断点 768px。
+
+**字号阶梯**：
+
+| px | 用途 |
+|---|---|
+| 10 | 分组标签（uppercase + letter-spacing） |
+| 11–12 | 辅助信息、meta、tag |
+| 13 | 次要正文、列表项、错误提示 |
+| 14 | 正文默认（`body` 基准） |
+| 15 | 输入框文字（`$font-code` 场景） |
+| 16 | 小标题 |
+| 26 | 登录页等展示型大标题 |
+
+## 3. 字体栈
+
+```scss
+$font-ui:   Inter, system-ui, -apple-system, sans-serif;   // 中英混排 UI（fallback 系统字体）
+$font-code: 'JetBrains Mono', 'Fira Code', 'Consolas', monospace;  // 代码、命令、版本号
+```
+
+- comic 主题下 `--font-ui` 被覆盖为 `'Comic Neue', 'ZCOOL KuaiLe', ...`，其余不变。
+- 等宽字体只用于：代码块、命令、版本号、命令行提示（`$font-code`）。
+
+## 4. 阴影 / 分割线
+
+- **分割线**：`1px solid var(--border-color)`（面板/区块）或 `--border-light`（弱分隔）。
+  水墨主题以线为主，不滥用阴影。
+- **阴影**：常规浮层 `0 1px 4px rgba(0, 0, 0, 0.1)`；comic 主题用
+  `3px 3px 0 rgba(0, 0, 0, 0.15)` 硬投影（`--comic-shadow`）。
+- 弹窗/抽屉的遮罩、投影由 Arco 组件自带，页面不重复加。
+
+## 5. 组件使用约定
+
+- **消息 / 对话框 / 通知**：只准调 `composables/useMessage|useDialog|useNotification`
+  适配层（签名冻结），**不得**在页面里直接 import Arco 的 `Message` / `Modal` / `Notification`。
+- **Modal vs Drawer**：短内容确认、纯信息展示用 `a-modal`
+  （信息型弹窗 `:footer="false"`，如样板页 changelog / docker 升级指引）；
+  需要表单编辑、长内容滚动的场景用 `a-drawer`。naive `preset="dialog"` 无直接对应。
+- **按钮**：语义 `type` + `status` 组合（warning 按钮 = `type="primary" status="warning"`）；
+  占满宽用 `long`（naive `block`）；尺寸 `size="mini|small|medium|large"`
+  （naive `tiny`→`mini`）；提交按钮 `html-type="submit"`，加载态用 `:loading`。
+- **输入框**：`a-input` 关闭了 attrs 透传，`autofocus` 无效——需要自动聚焦时
+  `ref` + `onMounted` 调 `focus()`；密码框 `type="password"`。
+- **表格空态**：用 `a-empty`，不手写占位文案。
+- **loading**：按钮级用 `a-button :loading`，区域级用 `a-spin :loading`，
+  全局任务进度用 `useMessage().loading(...)`（用完 close/destroy）。
+- **表单**：`a-form` + `a-form-item`，校验规则 API 与 naive 不同，逐例适配。
+- **tag**：naive `type="info"` → `a-tag color="arcoblue"`（内建色），
+  `:bordered="false"` 直接支持。
+
+## 6. 装饰位面的边界
+
+装饰位面（ArkScope vendor 组件等纯视觉层）的判定标准：
+
+> **不得承载信息、不得承载交互、不得影响可读性。**
+
+| 允许 | 禁止 |
+|---|---|
+| 登录页标题区装饰位面 | 聊天页（消息区 / 输入区 / 侧边栏） |
+| Journey 图谱的背景层 | 任何表单页（Skills / Profiles / Settings / Models） |
+| 首屏 loading / 空状态 | 任何表格页（Usage / Logs / Jobs / Kanban） |
+| | 任何点击交互密集区域 |
+
+**`pointer-events: none` 是硬要求**，装饰层绝不能吃掉点击
+（样板：`LoginView.vue` 的 `.login-decor`，外加 `aria-hidden="true"`）。
+
+vendor 素材边界：`vendor/arkscore/` 下**零图片/音视频素材**，
+由 `tests/client/arkscope-vendor.test.ts` 机械化卡住；Provenance 见
+`vendor/arkscore/PROVENANCE.md`。
+
+## 7. 三条不可破的规则
+
+1. **不引入第三个 UI 库**——只允许 Arco Design Vue（+ 现有图标/工具链）。
+2. **消息气泡内部不用 Arco 组件**（性能红线，见 Phase 006）。
+3. **装饰层一律 `pointer-events: none`**，不承载信息与交互。