coding-tool-x 3.8.4 → 3.8.5

package/docs/superpowers/specs/2026-09-01-realtime-logs-panel-design.md

@@ -0,0 +1,27 @@
+# 实时日志面板空白修复设计
+
+## 问题
+
+渠道管理页的 `RightPanel.vue` 模板使用了 `<ProxyLogs>`，但脚本没有导入 `./ProxyLogs.vue`。Vue 将其保留为未解析的自定义元素，因此日志区域只渲染空容器，不显示标题、表头或日志内容。
+
+## 方案
+
+在 `src/web/src/components/RightPanel.vue` 的现有组件导入区补充：
+
+```js
+import ProxyLogs from './ProxyLogs.vue'
+```
+
+保留现有的 `:source="currentChannel"` 绑定，不改动日志状态、WebSocket、统计接口或布局逻辑。
+
+## 验收标准
+
+1. 进入 `/cli/omp` 等渠道管理页后，日志区域实际渲染 `ProxyLogs` 组件。
+2. 面板显示“实时日志”、表头和已有日志；无日志时显示“暂无日志”，而不是空白区域。
+3. 当前渠道切换和 WebSocket 实时日志追加行为保持不变。
+4. 回归测试覆盖 `RightPanel.vue` 对 `ProxyLogs.vue` 的导入，前端构建成功。
+5. 使用 `http://localhost:19999/cli/omp` 进行浏览器冒烟验证。
+
+## 范围与风险
+
+仅修改组件导入和对应回归测试。不会触碰工作区已有的 `Home.vue`、`Home.test.js` 改动。风险为低：不改变公开接口或运行时数据流。

package/docs/superpowers/specs/2026-09-02-config-driven-platform-boundary-design.md

@@ -0,0 +1,64 @@
+# 配置化平台边界设计
+
+## 目标
+
+删除按平台复制的 API、项目配置适配器和共享目录，把平台差异集中到 Registry/Manifest 与 Driver；`src/server` 只保留通用应用、HTTP 注册和基础设施。
+
+## 边界
+
+### `src/platforms`
+
+- Manifest 描述平台能力、路由别名、配置资源和可用操作。
+- `src/platforms/drivers/<platform>/` 保存平台专属业务：渠道、代理、会话、统计、原生配置、项目配置和 CLI/API 操作。
+- 平台目录不再创建 `shared` 子目录。
+
+### `src/shared`
+
+保存跨平台、与 HTTP 无关的核心工具：
+
+- 项目配置文件读写和路径安全
+- MCP 配置格式转换和 secret 脱敏
+- Driver 结果、错误和调用上下文
+- 通用模型、渠道、会话 DTO 转换
+
+### `src/server`
+
+- `src/server/api` 只保留通用路由工厂、请求解析、响应转换和路由注册。
+- `src/server/services` 只保留通用应用服务、缓存、日志、调度和持久化基础设施。
+- 不再保留 `codex-channels.js`、`gemini-proxy.js`、`project-config-adapters/codex.js` 等按平台文件。
+
+## API 设计
+
+统一路由从 manifest 和 capability 生成，兼容原有 URL 前缀：
+
+```js
+const route = {
+  path: '/:platform/channels',
+  capability: 'channels',
+  operation: 'list'
+};
+
+const driver = runtime.getDriver(platform, route.capability);
+const result = await driver[route.operation](requestContext);
+return sendDriverResult(response, result);
+```
+
+平台 API 不再直接 import 具体 Driver 实现文件。平台专属校验、默认值、CLI 安装检测、配置文件路径和响应字段由 Driver 暴露的能力处理。
+
+## 项目配置
+
+`project-config-adapters/<platform>.js` 移入对应 Driver 的 `project-config.js`。跨平台文件工具和 MCP 安全逻辑移入 `src/shared/project-config`。`ProjectConfigService` 只按 manifest 获取 Driver adapter，不维护平台工厂表。
+
+## 删除策略
+
+- 删除重复的平台 API 路由文件和旧项目配置 adapter 目录。
+- 删除迁移后没有生产调用方的兼容入口。
+- 保留旧 URL，由统一路由注册器按 manifest aliases 注册。
+- 不删除用户磁盘上的配置和会话数据。
+
+## 验证
+
+- 静态扫描确认 `src/server/api` 和 `src/server/services` 不再直接引用平台实现文件。
+- 每个平台的 channels、proxy、nativeConfig、sessions、statistics、projectConfig Driver 均可通过 Runtime 获取。
+- 完整 `tests/unit` 通过。
+- 旧平台 API URL 的响应格式和状态码测试通过。

package/docs/superpowers/specs/2026-09-02-platform-implementation-driver-boundary-design.md

@@ -0,0 +1,123 @@
+# Platform Implementation Driver Boundary
+
+## Problem
+
+The previous migration added Registry/Runtime Driver entry points, but several built-in Drivers still delegate their implementation to platform-specific modules under `src/server`:
+
+- `src/platforms/drivers/{gemini,opencode,omp}/channels.js` delegate to `src/server/services/*-channels.js`.
+- `src/platforms/drivers/*/proxy.js` delegate to `src/server/*-proxy-server.js`.
+- `src/platforms/drivers/*/{sessions,statistics,native-config}.js` delegate to platform-specific services.
+- `src/commands/channels.js` and `src/commands/toggle-proxy.js` retain platform conditionals and direct server imports.
+
+This leaves Driver ownership nominal rather than real and prevents unused platform services from being removed.
+
+## Goals
+
+1. Move platform-specific behavior and I/O into the corresponding platform/capability Driver.
+2. Keep `src/server` limited to transport facades, shared application orchestration, and platform-neutral infrastructure.
+3. Make CLI channel/proxy commands Runtime-driven instead of platform-switch-driven.
+4. Delete platform service/proxy modules after all production callers and test seams are migrated.
+5. Preserve public HTTP paths, CLI commands, response shapes, native-config protection, OMP managed mode, and existing provider behavior.
+6. Keep platform code separated by platform directory; do not create one monolithic Driver implementation.
+
+## Non-goals
+
+- Do not remove public legacy HTTP URLs.
+- Do not expose arbitrary user-provided executable Driver modules.
+- Do not move generic SQLite/cache/scheduler/security infrastructure into every platform Driver.
+- Do not change provider protocol semantics while relocating ownership.
+
+## Target structure
+
+```text
+src/platforms/drivers/
+  claude/
+    channels.js
+    proxy.js
+    sessions.js
+    statistics.js
+    native-config.js
+    resource-sync.js
+    prompts.js
+    mcp.js
+    helpers/                 # only Claude-specific helpers
+  codex/
+    ...
+  gemini/
+    ...
+  opencode/
+    ...
+  omp/
+    ...
+  shared/                    # result contracts and truly platform-neutral helpers
+
+src/server/api/              # HTTP URL/parameter/response compatibility facades
+src/commands/                # CLI interaction and output formatting only
+src/server/services/base/    # shared application and infrastructure services
+```
+
+A Driver may be split into platform-local helper files when a capability is large. Platform-specific configuration paths, provider serialization, auth lookup, wire conversion, proxy request handling, session parsing, and statistics parsing must remain under that platform directory.
+
+## Ownership rules
+
+### Driver-owned
+
+- Channel storage normalization and platform-specific native synchronization.
+- Platform provider IDs, model/provider configuration, auth/keychain integration, and platform-specific environment updates.
+- Proxy lifecycle and request protocol conversion, including headers, body formats, retry behavior, upstream target resolution, and usage extraction.
+- Native configuration read/write/restore and protection semantics.
+- Session inventory/parsing/read/mutation semantics that depend on a platform schema.
+- Platform statistics parsing, pricing selection, and persistence payload construction.
+- Platform-specific prompt, MCP, resource, and config serialization.
+- Capability metadata used by CLI, including `supportsCliCreate`, managed-mode behavior, and available operations.
+
+### Server-owned
+
+- Express routers, legacy URL mounting, HTTP status/response conversion, and websocket transport.
+- CLI prompts, menus, terminal formatting, and command dispatch.
+- Generic channel application operations, scheduler policy, health aggregation, caches, SQLite schema/orchestration, worker lifecycle, security validation, and logging infrastructure.
+- Registry/Runtime lookup and capability iteration.
+
+Server facades may translate old argument order and return shapes, but must not contain provider I/O, platform branches, or duplicated platform business logic.
+
+## Dispatch contracts
+
+CLI code obtains capability objects through Runtime:
+
+```js
+const runtime = getPlatformRuntime();
+const channels = runtime.getDriver(platform, 'channels');
+const proxy = runtime.getDriver(platform, 'proxy');
+```
+
+The CLI must use capability metadata/methods instead of checking concrete platform names. A new manifest platform with compatible generic Drivers must be discoverable without editing `src/commands`.
+
+Legacy HTTP modules may retain names and paths, but their implementation is limited to:
+
+1. deserialize and validate request input;
+2. get the Driver from Runtime;
+3. invoke the capability;
+4. map Driver DTOs/results to the old response shape;
+5. broadcast transport events.
+
+## Migration order
+
+1. Characterize existing platform service/proxy behavior and identify production callers.
+2. Move remaining channel implementations, then proxy/wire implementations.
+3. Move sessions, statistics, native config, resource sync, prompts, and MCP implementations.
+4. Replace CLI platform branches with Runtime capability dispatch.
+5. Remove `legacy.js` mappings to platform-specific server modules.
+6. Migrate tests and `require.cache` seams to Driver/facade boundaries.
+7. Delete server modules with no production or explicitly supported compatibility caller.
+8. Run API, CLI, capability contract, reachability, and full regression checks.
+
+## Acceptance criteria
+
+- No production `src` import from CLI or shared application code directly requires a platform-specific channel/session/statistics/settings/proxy implementation under `src/server`.
+- No Driver capability is only a wrapper around a platform-specific server implementation.
+- `legacy.js` contains no mapping to the migrated platform-specific implementation files.
+- `src/commands/channels.js` and `toggle-proxy.js` contain no platform-specific require/switch branches.
+- Public legacy HTTP URLs and CLI command names remain functional.
+- Platform-specific implementation files exist only under their platform Driver directories, except explicitly classified shared protocol/infrastructure utilities.
+- Reachability reports no unexplained orphan modules.
+- Focused behavior tests cover each migrated capability and preserve error/secret/native-config semantics.

package/docs/superpowers/specs/2026-09-03-cli-platform-correctness-boundary-design.md

@@ -0,0 +1,249 @@
+# CLI 平台正确性边界设计
+
+## 目标
+
+修复配置驱动平台内核之外仍存在的平台硬编码和错误回退，使 CLI 与 HTTP transport 统一通过 Registry/Runtime 解析平台和能力，同时严格保留现有 CLI 命令、旧 API URL、正常响应结构以及 `legacy:*` Driver。
+
+本轮是正确性边界修复，不完成 `legacy.js` 删除、共享 route profile 提取或全部平台实现重写。
+
+## 问题
+
+当前平台目录、Runtime、统一平台路由和 Web 平台目录已经配置驱动，但外围仍存在四类不一致：
+
+1. `cli-type.js` 接受 Registry 中的平台，`ui/menu.js` 却只接受四个内置平台，其他值静默回退 Claude。
+2. 交互式会话列表、搜索、工作区和恢复命令直接 import 或执行 Claude 实现，忽略 `currentCliType`。
+3. Project Config、Commands、Agents 等 HTTP/service 入口维护独立平台白名单，已注册平台仍可能被外层拒绝；部分未知平台会静默回退 Claude。
+4. Manifest route 引用不存在的 Driver operation 时，GET route 可能返回 200 空数据，掩盖配置或实现错误。
+
+这些行为破坏同一 invariant：平台存在性应只由 Registry 决定，能力可用性应只由 capability Driver 决定。
+
+## 决策
+
+采用一个窄的平台访问模块作为共享 seam。CLI 与 HTTP transport 不再判断具体平台名，只提供平台 key、capability 和可选 operation。
+
+不采用逐文件复制解析逻辑，因为那会形成第二套分散约定。不采用一次性删除全部 legacy Driver，因为其回归面超过正确性修复范围。
+
+## 平台访问模块
+
+新增跨 transport、与 Express/Inquirer 无关的平台访问模块。建议位置：
+
+```text
+src/platforms/access.js
+```
+
+模块 interface：
+
+```js
+resolvePlatform(key, options)
+resolveCapability(key, capability, options)
+resolveOperation(key, capability, operation, options)
+```
+
+返回值：
+
+```js
+{
+  key,
+  manifest,
+  driver,
+  operation
+}
+```
+
+`resolvePlatform()` 只验证并返回 Registry definition。`resolveCapability()` 还验证 capability 声明并通过 Runtime 获取 Driver。`resolveOperation()` 再验证 Driver operation 存在。
+
+依赖通过 options 注入，生产环境默认使用 `getPlatformContext()`：
+
+```js
+{
+  registry,
+  runtime,
+  fallback
+}
+```
+
+`fallback` 只适用于调用方没有提供平台值的兼容场景。只要调用方提供了非空平台值，未知值必须报错，绝不回退 Claude。
+
+## 错误模型
+
+平台访问错误包含稳定的机器字段：
+
+```js
+{
+  code: 'not_found' | 'unsupported' | 'invalid' | 'failed',
+  platform,
+  capability,
+  operation,
+  message
+}
+```
+
+错误语义：
+
+| 场景 | code |
+|---|---|
+| 非空平台 key 未注册 | `not_found` |
+| 已注册平台未声明 capability | `unsupported` |
+| capability Driver 不存在 | `unsupported` |
+| Driver 不提供 operation | `unsupported` |
+| 调用参数格式错误 | `invalid` |
+| Driver 创建或执行抛错 | `failed` |
+
+HTTP 层继续使用现有状态映射：`invalid` 400、`not_found`/`unsupported` 404、`failed` 500。CLI 输出明确错误并停止当前操作，不改写配置、不访问 Claude 数据。
+
+## CLI 数据流
+
+### 平台选择与主菜单
+
+`src/commands/cli-type.js` 继续从 Registry 生成可选平台。
+
+`src/ui/menu.js` 删除平台枚举与具体 Driver implementation import。主菜单从 Registry definition 获取 label、terminalColor；通过 `resolveOperation()` 获取：
+
+- `channels.current` 或 `channels.list`；
+- `proxy.status`。
+
+不支持某项能力时只隐藏或显示“不支持”的对应状态，不把整个平台变成 Claude。
+
+### 会话列表与搜索
+
+`src/commands/list.js` 和 `src/commands/search.js` 不再 import Claude sessions implementation。调用方传入当前平台，命令通过 Runtime 获取 `sessions` 和 `projects` Driver。
+
+Driver interface 使用现有标准 operation：
+
+```text
+projects.listProjects(options)
+sessions.recent(limit, options)
+sessions.searchAcrossProjects(keyword, limit, options)
+sessions.search(projectName, keyword, contextLength, options)
+```
+
+CLI 只格式化规范化 DTO。平台专属路径解析、项目显示名和会话文件结构留在 Driver。
+
+如果 Driver 不支持跨项目搜索，CLI 返回明确 `unsupported`，不扫描 Claude 会话目录作为 fallback。
+
+### 工作区
+
+工作区自身的创建、删除和元数据仍由 `workspace-service` 管理。需要发现平台项目时，通过当前平台 `projects` Driver 获取项目集合，不再直接调用 Claude session implementation。
+
+### 恢复会话
+
+`src/commands/resume.js` 不再拼接硬编码的 `claude` 命令。恢复操作调用当前平台的 `sessions.launch(sessionId, options)`。
+
+平台 Driver 负责：
+
+- 可执行文件和参数；
+- 工作目录；
+- session ID/项目 ID 的平台格式；
+- 继承 stdio；
+- 子进程退出码。
+
+本轮只要求内置平台保持已有可支持行为。尚无安全 launch 语义的平台返回 `unsupported`；不能退回 Claude。用户 Manifest 不允许直接声明任意 executable 或 shell 字符串，因此 generic Driver 默认不提供 `launch`。
+
+## HTTP 与应用服务
+
+以下模块删除独立平台 allowlist 或 fallback：
+
+- Project Config API；
+- Commands API/service；
+- Agents API/service；
+- MCP 中仅用于固定平台判定的常量；
+- 共用的 managed platform resolver。
+
+统一规则：
+
+1. 请求层解析字符串和必填字段。
+2. Registry 判断平台是否存在。
+3. capability 判断功能是否存在。
+4. Driver 或应用服务处理平台语义。
+
+Project Config 已经通过 Runtime 构建 adapter；HTTP 层只需删除额外白名单并依赖该 seam。
+
+Commands 和 Agents 在本轮不强制改造成新的 capability Driver。它们仍可维护内置平台的格式映射，但必须：
+
+- 对已注册但实现不支持的平台返回 `unsupported`；
+- 对未知平台返回 `not_found`；
+- 不回退 Claude；
+- 不声称 `resourceTypes.commands/agents` 支持即可自动获得专属实现。
+
+这样先修正边界语义，不扩大为资源系统重写。
+
+## Manifest 与路由验证
+
+Manifest 加载阶段增加 route contract 校验：
+
+1. capability 必须已声明；
+2. operation 必须属于该 capability 的允许 operation 集；
+3. request codec 名必须存在；
+4. response codec 名必须存在；
+5. method/path 仍遵循现有 schema。
+
+operation contract 由代码中的只读表维护，不允许用户 Manifest 定义任意 executable behavior。该表只描述可调用的 interface，不包含平台实现。
+
+`platform-route-factory` 的运行时规则改为：
+
+- Driver 或 operation 缺失时一律返回结构化 `unsupported`；
+- 不再因 GET 请求返回 200 空 payload；
+- 正常 Driver 返回值、旧 aliases 和响应 codec 保持不变。
+
+`emptyPayload()` 仅用于 Driver 明确返回成功但数据为空的正常化，不用于掩盖缺失实现。
+
+## 兼容性
+
+必须保留：
+
+- `ctx claude|codex|gemini|opencode|omp start|stop|restart|status`；
+- 现有 root aliases 和平台 API 前缀；
+- 正常请求的响应字段和状态码；
+- `legacy:*` Driver ID；
+- `legacy.js` 及现有实现模块；
+- 用户磁盘配置和会话数据格式；
+- 现有 Web 平台目录接口。
+
+有意改变：
+
+- 未知平台不再回退 Claude；
+- 已知平台缺少 capability/operation 不再伪造空成功；
+- 当前平台不是 Claude 时，交互式 CLI 不再访问 Claude 会话或配置。
+
+这些属于错误修复，不提供兼容 shim。
+
+## 测试策略
+
+行为测试必须覆盖：
+
+1. 非空未知平台产生 `not_found`，且没有调用 Claude Driver。
+2. 缺省平台仍按原公开契约使用 Claude，仅限明确允许 fallback 的入口。
+3. `omp` 与测试用 `demo-cli` 在主菜单中不被归一为 Claude。
+4. `demo-cli` 声明 generic projects/sessions 后，CLI 通过 Runtime Driver 读取。
+5. 无 `sessions.launch` 的平台恢复会话返回 `unsupported`。
+6. Project Config、Commands、Agents 对未知平台和已知但不支持的平台分别返回正确错误。
+7. Manifest 拒绝未知 codec 和 capability/operation 组合。
+8. route Driver 缺少 operation 时 GET/写请求均返回 `unsupported`。
+9. 五个内置平台命令和旧 API aliases 的既有 contract 保持通过。
+10. 平台 Driver contract、API contract、CLI command contract 和完整 unit suite 通过。
+
+测试只断言可观察行为和 Driver 调用，不把源码正则扫描作为主要正确性证明。
+
+## 实施顺序
+
+1. 建立平台访问模块及错误 contract。
+2. 修正 route validation 和 GET 空成功。
+3. 移除 Project Config/Commands/Agents 的错误回退和 transport 白名单。
+4. 迁移主菜单状态读取。
+5. 迁移会话列表和搜索。
+6. 迁移工作区项目发现。
+7. 引入并迁移 session launch operation。
+8. 运行聚焦回归、CLI smoke 和完整 unit suite。
+
+每一步单独提交，并保持旧公开契约可运行。
+
+## 非目标
+
+- 删除 `legacy:*` 或 `legacy.js`；
+- 重写五个平台的协议实现；
+- 提取共享 API route profile；
+- 修改 Manifest `enabled` 或 Registry `enabledOnly` 语义；
+- 重构全部 Commands/Agents 内部格式映射；
+- 允许用户 Manifest 执行任意命令或加载模块；
+- 修改 Web UI 信息架构；
+- 删除旧 URL、命令别名或响应字段。

package/docs/superpowers/specs/2026-09-03-dependency-security-remediation-design.md

@@ -0,0 +1,87 @@
+# Dependency Security Remediation Design
+
+## Problem
+
+A push to the GitHub default branch reports:
+
+```text
+175 vulnerabilities
+84 high, 84 moderate, 7 low
+```
+
+The repository currently contains both npm and pnpm manifests/lockfiles at the root and under `src/web`, while project scripts use npm. Local audit reports are lower but still show tracked vulnerable dependency trees:
+
+- Root: 1 high and 2 moderate vulnerabilities.
+- Web: 1 critical, 9 high, and 6 moderate vulnerabilities.
+- Root `pnpm-lock.yaml` is stale relative to `package.json`; it still locks packages such as `qs@6.13.0` and `lodash@4.17.21`.
+
+The duplicate and inconsistent lockfiles can cause GitHub to scan multiple dependency trees and report repeated or stale alerts.
+
+## Goal
+
+Make the repository's dependency state reproducibly secure and remove stale dependency scan sources.
+
+Success criteria:
+
+1. npm is the sole supported package manager for this repository.
+2. Root and web npm lockfiles match their package manifests.
+3. Root and web `npm audit` report no unresolved high or critical vulnerabilities; the target is zero vulnerabilities where available fixes exist.
+4. Web production build and unit tests pass.
+5. Existing root tests pass.
+6. No runtime vulnerability is hidden through audit exclusions or ignored advisories.
+
+## Scope
+
+### In scope
+
+- Root `package.json` and `package-lock.json` dependency updates.
+- `src/web/package.json` and `src/web/package-lock.json` dependency updates.
+- Removal of the stale root and web `pnpm-lock.yaml` files.
+- Compatibility fixes required by dependency upgrades.
+- Existing test/build configuration adjustments required by major toolchain upgrades.
+
+### Out of scope
+
+- Unrelated business logic refactors.
+- Replacing npm with pnpm.
+- Suppressing or downgrading vulnerability reports.
+- Changes to application security behavior unrelated to dependency compatibility.
+
+## Design
+
+### Package manager policy
+
+Use npm because the repository's scripts invoke npm, the root packaging flow calls `npm run build:web`, and both npm lockfiles are already tracked. Remove the two pnpm lockfiles rather than maintaining a second dependency graph that is not used by the project.
+
+### Root dependency remediation
+
+Refresh the root npm lockfile and update vulnerable transitive packages through direct dependency constraints or the existing `overrides` block. Preserve the current runtime API versions unless a security fix requires an upgrade. Keep `package.json` and `package-lock.json` synchronized.
+
+### Web dependency remediation
+
+Upgrade direct packages with available security fixes, including Axios, ECharts, Markdown-It, Vite, Vitest, and Vue-ECharts. Apply the minimum versions containing fixes. Where a main-version upgrade is required, update only the affected configuration or call sites and verify existing behavior:
+
+- Vite/Vitest/plugin-vue toolchain remains compatible with Node `>=22.13.0`.
+- ECharts/Vue-ECharts chart initialization and option rendering remain compatible.
+- Axios API modules retain their existing request/response behavior.
+- Markdown rendering remains compatible with current components.
+
+Regenerate the web npm lockfile after package changes. Do not hand-edit generated lockfile entries.
+
+## Failure handling
+
+If an upgrade introduces a build or test failure, fix the concrete compatibility issue at its call site or configuration boundary. Do not add fallbacks that mask errors. If an advisory has no available fixed version, retain the dependency and document the exact unresolved path and reason in the implementation result.
+
+## Verification
+
+Run, in order:
+
+1. Root `npm install --package-lock-only` or equivalent manifest-driven lockfile refresh.
+2. Web dependency installation and lockfile refresh.
+3. Root `npm audit`.
+4. Web `npm audit`.
+5. `npm run build:web` from the root.
+6. Web unit tests through the existing web test script.
+7. Root `npm test`.
+
+The final check must inspect the changed files and confirm no pnpm lockfiles remain tracked, no audit-ignore configuration was introduced, and generated locks are reproducible from their manifests.