@chatcode/cco-better-sidebar 0.18.0-alpha.0

package/lib/types/ui-tweaks/turn-outcome.d.ts

@@ -0,0 +1,57 @@
+/**
+ * dsh-ui-tweaks — turn outcome projection (host half).
+ *
+ * Registers the `dshTurnOutcome` session projection unit: the outcome of the
+ * session's most recent agent turn, folded from the log's `turn/end` events.
+ * The task notifier reads it off each sessions-list row (`projectionValues`)
+ * so it can announce WHY a turn ended — completed vs user-aborted vs failed —
+ * instead of announcing every running-drop as a plain finish.
+ *
+ * Whole-value rule: every `turn/end` replaces the previous value outright
+ * (last-wins), and `null` means no completed turn yet. Error turns keep a
+ * truncated copy of the structured failure message for notification bodies.
+ *
+ * `TurnEndReason` is merge-extensible upstream; unknown future kinds flow
+ * through as their literal kind string and the client falls back to a generic
+ * finish announcement.
+ * @module dsh-ui-tweaks/turn-outcome
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+/** Projection key the browser notifier reads through list-row `projectionValues`. */
+export declare const TURN_OUTCOME_PROJECTION_KEY = "dshTurnOutcome";
+/** The stock `TurnEndReason` kinds (the map is merge-extensible upstream). */
+export type TurnOutcomeKind = 'completed' | 'aborted' | 'blocked' | 'error' | 'max-tokens' | 'interrupted';
+/** Whole projection value: why the latest turn ended. */
+export interface TurnOutcomeValue {
+    kind: TurnOutcomeKind;
+    /** Unix epoch ms of the `turn/end` event. */
+    time: number;
+    /** Turn number carried by the same event. */
+    turn?: number;
+    /** Truncated human-readable failure text; present only on `error` outcomes. */
+    errorMessage?: string;
+}
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionMap {
+        /** Outcome of the session's most recent agent turn; null before the first one ends. */
+        dshTurnOutcome: TurnOutcomeValue | null;
+    }
+    interface SessionProjectionStateMap {
+        /** Host fold state for the turn-outcome key (same shape as the wire value). */
+        dshTurnOutcome: TurnOutcomeValue | null;
+    }
+}
+/** Registration-ready unit type with the client-visible `wire` block narrowed in. */
+type TurnOutcomeProjectionUnit = Omit<ProjectionDefinition<'dshTurnOutcome', TurnOutcomeValue | null>, 'wire'> & {
+    wire: NonNullable<ProjectionDefinition<'dshTurnOutcome', TurnOutcomeValue | null>['wire']>;
+};
+/** The `dshTurnOutcome` projection unit: last-wins fold over `turn/end`. */
+export declare const turnOutcomeProjectionDefinition: TurnOutcomeProjectionUnit;
+/**
+ * Register the projection whenever the `sessionProjections` service is
+ * present. Headless assemblies without the registry stay unaffected.
+ * @param ctx - plugin context owning the registration effect.
+ */
+export declare function installTurnOutcomeProjection(ctx: Context): void;
+export {};

package/lib/types/ui-tweaks/web.d.ts

@@ -0,0 +1,55 @@
+/**
+ * dsh-ui-tweaks — optional Web routes.
+ *
+ * The browser Settings panel reads and writes the `ui-tweaks` namespace through
+ * this same-origin route, because the Web settings RPC only exposes a fixed
+ * allowlist of namespaces (hardcoded in dsh-host-apiproxy since rc.6). The route
+ * proxies to the real `ctx.settings` service, so the settings document
+ * (settings.yaml) stays the single source of truth and hand edits keep working.
+ * @module dsh-ui-tweaks/web
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Context } from '@deepseek-ai/cordis';
+/** Exact route used by the browser Settings page. */
+export declare const SETTINGS_ROUTE = "/_dsh/ui-tweaks/settings";
+/** Project-owned logo, served to the browser from the packaged assets folder. */
+export declare const LOGO_ROUTE = "/_dsh/ui-tweaks/assets/logo.svg";
+/** Public Settings snapshot; no secrets exist in this namespace. */
+export interface UITweaksSnapshot {
+    writable: boolean;
+    value: unknown;
+    revision: number;
+}
+type JsonResponse<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** Accept state-changing requests only from the DSH Web application's origin. */
+export declare function sameOriginPost(req: IncomingMessage): boolean;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function json<T>(res: ServerResponse, status: number, body: JsonResponse<T>): void;
+export declare function requestError(res: ServerResponse, status: number, code: string, message: string): void;
+export declare function readJson(req: IncomingMessage, maxBytes?: number): Promise<unknown>;
+export declare function messageOf(error: unknown): string;
+/** Same-origin Settings read/write handler. */
+export declare class UITweaksWebBackend {
+    private readonly ctx;
+    constructor(ctx: Context);
+    private descriptor;
+    private snapshot;
+    /** Handle the exact Settings route. */
+    handle(req: IncomingMessage, res: ServerResponse): Promise<void>;
+}
+/**
+ * Attach the Settings route whenever a webServer service is present.
+ * @param ctx - plugin context owning route effects.
+ * @param backend - Settings handler.
+ */
+export declare function installUITweaksWeb(ctx: Context, backend: UITweaksWebBackend): void;
+export {};

package/lib/types/wire.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Wire helpers for the /sidebar JSON API: bounded body reading, response
+ * writing, and the shared error envelope. Every API method returns
+ * `{ok: true, value}` on success and `{ok: false, error: {code, message}}`
+ * (HTTP 4xx/5xx matching the code) on failure.
+ */
+import type { SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts';
+/** Machine-readable error codes of the sidebar API. */
+export type SidebarErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'too-large' | 'fs-error' | 'git-error' | 'pty-error' | 'pty-deps-missing' | 'job-error' | 'sidechat-error' | 'subagents-unavailable' | 'chatcode-unavailable' | 'chatcode-unauthorized' | 'chatcode-stats-unreachable' | 'chatcode-stats-http' | 'chatcode-stats-rejected' | 'chatcode-update-fetch' | 'chatcode-update-install' | 'release-note-unreachable' | 'release-note-http' | 'release-note-rejected' | 'settings-rejected' | 'settings-conflict' | 'internal';
+/** One API failure with its wire code and HTTP status. */
+export declare class SidebarError extends Error {
+    readonly code: SidebarErrorCode;
+    readonly status: number;
+    constructor(code: SidebarErrorCode, message: string, status?: number);
+}
+/** Success envelope of one API method. */
+export interface SidebarOk<T> {
+    ok: true;
+    value: T;
+}
+/** Failure envelope of one API method. */
+export interface SidebarErr {
+    ok: false;
+    error: {
+        code: SidebarErrorCode;
+        message: string;
+    };
+}
+/** Read and parse the JSON request body (bounded; malformed → bad-request). */
+export declare function readJsonBody(req: SidebarHttpRequest): Promise<unknown>;
+/** Write a JSON response with the given status. */
+export declare function writeJson(res: SidebarHttpResponse, status: number, body: unknown): void;
+/** Write the success envelope. */
+export declare function writeOk(res: SidebarHttpResponse, value: unknown): void;
+/** Write the failure envelope for any thrown value (unknown → internal 500). */
+export declare function writeError(res: SidebarHttpResponse, error: unknown): void;
+/** Narrow an unknown payload value to a string, else throw bad-request. */
+export declare function requireString(payload: unknown, key: string): string;

package/package.json

@@ -0,0 +1,213 @@
+{
+  "name": "@chatcode/cco-better-sidebar",
+  "version": "0.18.0-alpha.0",
+  "description": "ChatCode CLI Web plugin: a VS Code-like right sidebar (explorer / editor / terminal / git / browser), isolated per conversation session. Exposes a service for other plugins to register sidebar tabs and file viewers.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omdsh-dev/DSH-better-sidebar"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/service": {
+      "types": "./lib/types/client/service.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./client/api": {
+      "types": "./lib/types/client/service.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-commands",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-workspace",
+        "@deepseek-ai/dsh-client-modules"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/client-registry.js",
+    "lib/client-terminal.js",
+    "lib/client-editor.js",
+    "lib/client-mermaid.js",
+    "lib/types/**/*.d.ts",
+    "src",
+    "assets/logo.svg",
+    "vendor",
+    "scripts/install.sh",
+    "scripts/install.ps1",
+    "cordis.patch.yml",
+    "README.md",
+    "README_EN.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-commands": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-subagent": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-workspace": "^0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@huanlin/dsh-plugin-better-locale": "^0.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@huanlin/dsh-plugin-better-locale": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@codemirror/commands": "^6.10.4",
+    "@codemirror/lang-cpp": "^6.0.3",
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-go": "^6.0.1",
+    "@codemirror/lang-html": "^6.4.12",
+    "@codemirror/lang-java": "^6.0.2",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.2",
+    "@codemirror/lang-php": "^6.0.2",
+    "@codemirror/lang-python": "^6.2.1",
+    "@codemirror/lang-rust": "^6.0.2",
+    "@codemirror/lang-sql": "^6.10.0",
+    "@codemirror/lang-vue": "^0.1.3",
+    "@codemirror/lang-xml": "^6.1.0",
+    "@codemirror/lang-yaml": "^6.1.3",
+    "@codemirror/language": "^6.12.4",
+    "@codemirror/legacy-modes": "^6.5.3",
+    "@codemirror/search": "^6.7.1",
+    "@codemirror/state": "^6.7.1",
+    "@codemirror/view": "^6.43.8",
+    "@lezer/highlight": "^1.2.3",
+    "clsx": "^2.1.1",
+    "dompurify": "^3.4.14",
+    "mermaid": "^11.16.1",
+    "node-pty": "^1.1.0",
+    "react-icons": "5.7.0",
+    "rxjs": "^7.8.2",
+    "schemastery": "^3.18.0",
+    "ws": "^8.18.0",
+    "yaml": "2.9.0",
+    "@chatcode/cco-builtin-browser": "0.1.21"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/cordis": "4.0.1",
+    "@deepseek-ai/dsh-agent": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-attachment": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-api-session-controller": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-api-workspace-controller": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-locale": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-commands": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-session": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-client-ui-workspace": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-code-runtime": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-scope": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-storage": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-subagent": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.1-rc.1",
+    "@deepseek-ai/dsh-util-time": "0.1.2-alpha.2",
+    "@deepseek-ai/dsh-workspace": "^0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "@huanlin/dsh-plugin-better-locale": "^0.1.0",
+    "@playwright/test": "^1.62.1",
+    "@types/node": "^24.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.1",
+    "@types/ws": "^8.5.10",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^5.5.0",
+    "cordis": "^4.0.0-rc.8",
+    "jsdom": "^29.1.1",
+    "lightningcss": "^1.32.0",
+    "react": "^18.2.0",
+    "react-dom": "18.2.0",
+    "tsdown": "^0.22.2",
+    "typescript": "^5.6.0",
+    "unrun": "^0.2.39",
+    "vitest": "^4.1.8",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('lib',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && tsdown",
+    "typecheck": "tsc --noEmit",
+    "bundle": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "test:browser": "pnpm --filter @chatcode/cco-builtin-browser build && pnpm --filter @chatcode/cco-builtin-browser test",
+    "test:mount": "bash scripts/e2e-mount.sh",
+    "verify:brand": "node scripts/verify-brand.mjs",
+    "check:consumer-types": "bash scripts/check-consumer-types.sh"
+  }
+}

package/scripts/install.ps1

@@ -0,0 +1,310 @@
+## =============================================================================
+# dsh-better-sidebar 一键安装脚本（官方 CLI 方式，Windows PowerShell 5.1+ / pwsh）
+#
+# 通过 ChatCode CLI 插件命令安装 npm 包并自动挂载：
+#   chatcode-cli plugin --profile web add @chatcode/cco-better-sidebar@<version>
+#
+# 包内声明了 dsh.bundle.patch（cordis.patch.yml）：CLI 的 bundle 协调会把它
+# 自动加进 profile 的 dsh.profile.bundles，下次启动即挂载——无需手动写
+# cordis.patch.yml 挂载行。符合仓库硬约束：不修改宿主源码，插件永远作为
+# 独立包被 profile 引用。
+#
+# 用法（任选其一）：
+#   # 默认最新版
+#   $script = (irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1').TrimStart([char]0xFEFF)
+#   & ([scriptblock]::Create($script))
+#   # 指定版本 / 装完重启
+#   $script = (irm 'https://raw.githubusercontent.com/omdsh-dev/DSH-better-sidebar/main/scripts/install.ps1').TrimStart([char]0xFEFF)
+#   & ([scriptblock]::Create($script)) -Version 0.10.2 -Restart
+#   # 本地保存后运行
+#   powershell -ExecutionPolicy Bypass -File install.ps1 -Version 0.10.2 -DryRun
+#   # 修复 node-pty 依赖（终端提示「node-pty 加载失败」时用，见 issue #140）
+#   powershell -ExecutionPolicy Bypass -File install.ps1 -Repair
+#
+# 参数：
+#   -Version    npm 版本号/范围，缺省 latest（自动解析为最新）。
+#   -Repair     修复模式：不重装插件，只确保 profile 的 pnpm-workspace.yaml
+#               放行 node-pty 构建脚本，然后重跑 pnpm install + pnpm rebuild
+#               node-pty。
+#   -Profile    目标 profile 名（缺省 web）；安装与修复模式均适用。
+#   -Restart    装完后尝试 `pm2 restart chatcode-cli-web`（无 pm2 时仅提示）。会断开当前页面会话。
+#   -DryRun     只打印将要执行的操作，不写任何文件。
+#
+# 环境变量（均可省略）：
+#   CHATCODE_CLI_HOME 默认 %USERPROFILE%\.chatcode-cli（兼容读取旧 DSH_HOME）
+#   REGISTRY    默认 https://registry.npmjs.org
+#   CHATCODE_CLI_CMD 默认优先 PATH 上的 chatcode-cli（兼容读取旧 DSH_CMD）
+#
+# 说明：
+# - pnpm 11 的 strict-dep-builds 会拦截 node-pty/protobufjs 的构建脚本并使
+#   `chatcode-cli plugin add` 非零退出。脚本会先把这两个构建许可写进 profile 的
+#   pnpm-workspace.yaml（幂等），保证 CLI 一步成功。
+# - pnpm 11 的 minimumReleaseAge 会拒绝发布 <24h 的新版本。脚本会预写
+#   minimumReleaseAgeExclude（幂等），放行本插件，避免"重跑一次才成功"。
+# - 老版本（<0.10.2）用手动挂载行，bundle 通道激活后需移除，否则双挂载。
+#   脚本会幂等移除 better-sidebar 挂载行。
+# =============================================================================
+param(
+  [string]$Version = '',
+  [switch]$Restart,
+  [switch]$DryRun,
+  [switch]$Repair,
+  [string]$Profile = 'web'
+)
+
+$PKG = '@chatcode/cco-better-sidebar'
+$REGISTRY = if ($env:REGISTRY) { $env:REGISTRY } else { 'https://registry.npmjs.org' }
+
+# Home 优先级：CHATCODE_CLI_HOME > 兼容 DSH_HOME > %USERPROFILE% > $HOME
+if ($env:CHATCODE_CLI_HOME) {
+  $CLI_HOME = $env:CHATCODE_CLI_HOME
+} elseif ($env:DSH_HOME) {
+  $CLI_HOME = $env:DSH_HOME
+} elseif ($env:USERPROFILE) {
+  $CLI_HOME = Join-Path $env:USERPROFILE '.chatcode-cli'
+} else {
+  $CLI_HOME = Join-Path $HOME '.chatcode-cli'
+}
+$PROFILE_DIR = Join-Path $CLI_HOME "profiles\$Profile"
+$WS_YML = Join-Path $PROFILE_DIR 'pnpm-workspace.yaml'
+$PATCH_YML = Join-Path $PROFILE_DIR 'cordis.patch.yml'
+
+function Say([string]$m)  { Write-Host "[install] $m" -ForegroundColor Green }
+function Warn([string]$m) { Write-Host "[warn] $m" -ForegroundColor Yellow }
+function Die([string]$m)  { Write-Host "[error] $m" -ForegroundColor Red; exit 1 }
+
+# 解析版本 -> npm spec（"x.y.z" / "^x.y.z" / latest）
+function Resolve-Spec {
+  param([string]$Given)
+  if ([string]::IsNullOrWhiteSpace($Given) -or $Given -eq 'latest') {
+    $v = $null
+    foreach ($tool in @('npm', 'pnpm')) {
+      if (Get-Command $tool -ErrorAction SilentlyContinue) {
+        $v = (& $tool view $PKG version "--registry=$REGISTRY" 2>$null | Select-Object -Last 1)
+        if ($v) { break }
+      }
+    }
+    if ($v) { return ([string]$v).Trim() }
+    Warn '无法联网解析最新版本（npm/pnpm 查询失败），回退为 latest，由 pnpm 直接解析。'
+    Warn '若已知版本号，可显式传入：-Version 0.10.2'
+    return 'latest'
+  }
+  return $Given
+}
+
+# 组装 ChatCode CLI：正式变量/命令优先，旧变量仅作兼容输入
+function Get-ChatCodeCli {
+  if ($env:CHATCODE_CLI_CMD) { return $env:CHATCODE_CLI_CMD }
+  if ($env:DSH_CMD) { return $env:DSH_CMD }
+  if (Get-Command chatcode-cli -ErrorAction SilentlyContinue) { return 'chatcode-cli' }
+  if (Get-Command cco -ErrorAction SilentlyContinue) { return 'cco' }
+  if (Get-Command npx -ErrorAction SilentlyContinue) { return 'npx' }
+  return $null
+}
+
+# 步骤 1（安装与修复共用）：预写 workspace 设置（幂等），保证 pnpm 不拦截
+# node-pty/protobufjs 构建脚本、放行本插件新版本
+function Ensure-WorkspaceSettings {
+  $wsScript = @'
+const fs = require("fs");
+const p = process.argv[2];
+let t = fs.readFileSync(p, "utf8");
+const before = t;
+t = t.replace(/^(\s*)(node-pty|protobufjs):.*$/gm, "$1$2: true");
+if (!/^\s*allowBuilds:\s*$/m.test(t)) {
+  t += "\nallowBuilds:\n  node-pty: true\n  protobufjs: true\n";
+} else {
+  for (const k of ["node-pty", "protobufjs"]) {
+    if (!new RegExp("^\\s*" + k + ":\\s*true\\s*$", "m").test(t)) {
+      t = t.replace(/^(\s*allowBuilds:\s*)$/m, "$1\n  " + k + ": true");
+    }
+  }
+}
+if (!/^\s*-\s+@chatcode\/cco-better-sidebar\s*$/m.test(t)) {
+  if (/^\s*minimumReleaseAgeExclude:\s*$/m.test(t)) {
+    t = t.replace(/^(\s*minimumReleaseAgeExclude:\s*)$/m, "$1\n  - @chatcode/cco-better-sidebar");
+  } else {
+    t += "\nminimumReleaseAgeExclude:\n  - @chatcode/cco-better-sidebar\n";
+  }
+}
+if (t !== before) fs.writeFileSync(p, t);
+console.log(t === before ? "unchanged" : "updated");
+'@
+  # PowerShell 5.1 把含内嵌双引号的多行 JS 作为参数传给 `node -e` 时，引号会被
+  # Windows 命令行解析吞掉，导致 JS 语法错误（Expected ',', got ':'）。
+  # 改用临时文件方式，兼容 PS 5.1 与 pwsh 7。
+  $wsJs = Join-Path $env:TEMP ("dshbs-ws-" + [guid]::NewGuid().ToString("N") + ".js")
+  Set-Content -LiteralPath $wsJs -Value $wsScript -Encoding UTF8
+  $wsOut = node $wsJs "$WS_YML" 2>&1
+  $wsCode = $LASTEXITCODE
+  Remove-Item -LiteralPath $wsJs -Force -ErrorAction SilentlyContinue
+  $wsResult = (($wsOut | Out-String)).Trim()
+  if ($wsCode -ne 0) { Die "处理 $WS_YML 失败（node 退出码 $wsCode）：$wsResult" }
+  if ($wsResult -eq 'updated') {
+    Say "已确保 $WS_YML：allowBuilds（node-pty/protobufjs: true）+ minimumReleaseAgeExclude（$PKG）"
+  } else {
+    Say 'workspace 设置已就绪，跳过'
+  }
+}
+
+# 前置校验
+if (-not (Get-Command node -ErrorAction SilentlyContinue)) {
+  Die '未找到 node（ChatCode CLI 运行需要 Node.js >= 20），请先安装 Node.js 并加入 PATH。'
+}
+if (-not (Get-Command pnpm -ErrorAction SilentlyContinue)) {
+  Die '未找到 pnpm；安装脚本需要 pnpm >= 10。请先安装或升级 pnpm 并加入 PATH。'
+}
+$pnpmVersion = (& pnpm --version 2>$null | Select-Object -Last 1)
+if ($LASTEXITCODE -ne 0 -or -not $pnpmVersion) {
+  Die '无法读取 pnpm 版本；安装脚本需要 pnpm >= 10。'
+}
+$pnpmVersionText = ([string]$pnpmVersion).Trim()
+$pnpmMajor = 0
+if (-not [int]::TryParse(($pnpmVersionText -split '\.')[0], [ref]$pnpmMajor)) {
+  Die "无法解析 pnpm 版本（输出：$pnpmVersionText）；安装脚本需要 pnpm >= 10。"
+}
+if ($pnpmMajor -lt 10) {
+  Die "安装脚本需要 pnpm >= 10；当前版本为 $pnpmVersionText。请升级 pnpm 后重试。"
+}
+if (-not (Test-Path $PROFILE_DIR)) {
+  Die "找不到 profile 目录：$PROFILE_DIR（请先安装并运行过一次 chatcode-cli web）"
+}
+if (-not (Test-Path $WS_YML)) {
+  Die "找不到 $WS_YML（请先初始化 $Profile profile）"
+}
+
+# ── 修复模式（issue #140）：不重装插件，只修复 node-pty 依赖 ────────────
+# 终端提示「node-pty 加载失败」时运行：确保 allowBuilds 后重跑
+# pnpm install + pnpm rebuild node-pty（重放被 pnpm 11 拦截的构建脚本）。
+if ($Repair) {
+  if ($DryRun) {
+    Say "[dry-run] 修复：确保 $WS_YML 含 allowBuilds（node-pty: true）"
+    Say "[dry-run] 修复：cd $PROFILE_DIR; pnpm install; pnpm rebuild node-pty"
+    exit 0
+  }
+  Say "修复模式：重装 node-pty（profile: $Profile，$PROFILE_DIR）..."
+  Ensure-WorkspaceSettings
+  Push-Location $PROFILE_DIR
+  try {
+    pnpm install
+    if ($LASTEXITCODE -ne 0) { Die "pnpm install 失败（退出码 $LASTEXITCODE）。请确认 pnpm 在 PATH 上、网络可用，然后重试。" }
+    pnpm rebuild node-pty
+    if ($LASTEXITCODE -ne 0) { Die "pnpm rebuild node-pty 失败（退出码 $LASTEXITCODE）。请确认 pnpm 在 PATH 上，然后重试。" }
+  } finally {
+    Pop-Location
+  }
+  Say '修复完成：node-pty 已重装（与 ChatCode CLI 核心保持同一版本）。请重启 ChatCode CLI 后重试终端。'
+  exit 0
+}
+
+$SPEC = Resolve-Spec $Version
+$CLI = Get-ChatCodeCli
+if (-not $CLI) {
+  Die '未找到 chatcode-cli、cco 或 npx。请先安装 ChatCode CLI（并确保 Node/npm 可用），或用 CHATCODE_CLI_CMD 指定。'
+}
+Say "目标：$CLI plugin --profile $Profile add $PKG@$SPEC（profile: $PROFILE_DIR）"
+
+if ($DryRun) {
+  Say "[dry-run] 步骤 1：确保 $WS_YML 含 allowBuilds（node-pty/protobufjs: true）与 minimumReleaseAgeExclude（$PKG）"
+  Say "[dry-run] 步骤 2：执行 $CLI plugin --profile $Profile add $PKG@$SPEC（安装 + bundle 自动注册）"
+  Say "[dry-run] 步骤 3：校验 dsh.profile.bundles 含 $PKG"
+  Say "[dry-run] 步骤 4：幂等移除 $PATCH_YML 里旧的 better-sidebar 手动挂载行（避免双挂载）"
+  if ($Restart) { Say '[dry-run] 步骤 5：pm2 restart chatcode-cli-web' } else { Say '[dry-run] 步骤 5：提示用户手动重启 ChatCode CLI' }
+  exit 0
+}
+
+# 步骤 1：预写 workspace 设置（幂等），保证 pnpm 不拦截构建、放行本插件新版本
+Ensure-WorkspaceSettings
+
+# 步骤 2：官方 CLI 安装 + bundle 自动注册（含挂载）
+if ($CLI -ne 'npx') {
+  $cliArgs = @('plugin', '--profile', $Profile, 'add', "$PKG@$SPEC")
+} else {
+  $cliArgs = @('-y', '--package', '@chatcode/chatcode-cli', 'chatcode-cli', 'plugin', '--profile', $Profile, 'add', "$PKG@$SPEC")
+}
+Say "执行 $CLI plugin --profile $Profile add $PKG@$SPEC ..."
+$addOut = & $CLI @cliArgs 2>&1
+$addCode = $LASTEXITCODE
+$addOut | ForEach-Object { $_ }
+if ($addCode -ne 0) {
+  Warn 'ChatCode CLI plugin add 失败。已预写 allowBuilds 与 minimumReleaseAgeExclude，仍失败的可能原因：'
+  Warn '  - 网络/登录问题：npm registry 不可达或需要登录。'
+  Warn "  - 依赖安装冲突：可手动重试 cd $PROFILE_DIR; pnpm install。"
+  exit 1
+}
+
+# 步骤 3：校验 bundle 已注册（挂载生效的判据）
+$pkgJson = Get-Content -Raw (Join-Path $PROFILE_DIR 'package.json') | ConvertFrom-Json
+$bundles = $pkgJson.dsh.profile.bundles
+if ($bundles -notcontains $PKG) {
+  Warn '@chatcode/cco-better-sidebar 未出现在 dsh.profile.bundles 中——挂载未注册。'
+  Warn "若上面的 pnpm 输出提示 ignored build scripts，请确认 $WS_YML 的 allowBuilds 后重跑本脚本。"
+  exit 1
+}
+Say "bundle 已注册：dsh.profile.bundles 包含 $PKG（下次启动自动挂载）"
+
+# 步骤 4：幂等移除旧的 manual 挂载行（避免与 bundle 双挂载）
+$mountScript = @'
+const fs = require("fs");
+const p = process.argv[2];
+const lines = fs.readFileSync(p, "utf8").split("\n");
+const out = [];
+let i = 0;
+let removed = false;
+while (i < lines.length) {
+  const line = lines[i];
+  if (/^[ \t]*- insert:\s*$/.test(line)) {
+    const block = [line];
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() !== "" && !/^-\s/.test(lines[j])) {
+      block.push(lines[j]);
+      j++;
+    }
+    if (block.some((l) => /id:\s*better-sidebar\b/.test(l))) {
+      while (out.length && /^[ \t]*#/.test(out[out.length - 1])) out.pop();
+      i = j;
+      removed = true;
+      continue;
+    }
+  }
+  out.push(line);
+  i++;
+}
+if (!removed) {
+  console.log("none");
+} else {
+  const t = out.join("\n").replace(/\n{3,}/g, "\n\n");
+  fs.writeFileSync(p, t);
+  console.log("removed");
+}
+'@
+$mountJs = Join-Path $env:TEMP ("dshbs-mount-" + [guid]::NewGuid().ToString("N") + ".js")
+Set-Content -LiteralPath $mountJs -Value $mountScript -Encoding UTF8
+$mountOut = node $mountJs "$PATCH_YML" 2>&1
+$mountCode = $LASTEXITCODE
+Remove-Item -LiteralPath $mountJs -Force -ErrorAction SilentlyContinue
+$mountResult = (($mountOut | Out-String)).Trim()
+if ($mountCode -ne 0) { Die "处理 $PATCH_YML 失败（node 退出码 $mountCode）：$mountResult" }
+if ($mountResult -eq 'removed') {
+  Say "已从 $PATCH_YML 移除旧的 better-sidebar 手动挂载行（bundle 通道接管挂载）"
+} else {
+  Say '无旧手动挂载行，跳过'
+}
+
+Say "安装完成：$PKG@$SPEC"
+
+# 步骤 5：重启提示
+if ($Restart) {
+  if (Get-Command pm2 -ErrorAction SilentlyContinue) {
+    Say '重启 chatcode-cli-web（pm2）...'
+    pm2 restart chatcode-cli-web
+    if ($LASTEXITCODE -ne 0) { Warn 'pm2 restart 失败，请手动重启 ChatCode CLI' }
+  } else {
+    Warn '未找到 pm2，请手动重启 ChatCode CLI（如：chatcode-cli web）'
+  }
+} else {
+  Say '下一步：重启 ChatCode CLI 并硬刷新（Ctrl+Shift+R / Cmd+Shift+R）使新副本生效。'
+  if (Get-Command pm2 -ErrorAction SilentlyContinue) {
+    Say '本机可用：pm2 restart chatcode-cli-web（会短暂断开当前页面会话）'
+  }
+}