huahua-dsh-plugin-orchestra

DSH 插件管理系统（host + client profile 插件）：插件清单、更新检测、升级/回滚、备份、跨 agent 迁移。

• 设计文档：docs/S1_架构设计草案.md（权威源）、docs/S2_工具层设计.md、docs/S3_面板设计.md、docs/adr/ADR-001~003
• 当前阶段：一期功能 1-5 交付（M2 ✅ 核心引擎 / M3 ✅ 面板）——105/105 用例全绿（引擎 86 + 面板 19），S7 终审 🔴-1/🟡-3 已清零（client bundle + verify.mjs 门禁），待用户验收
• 领域模型：src/domain/（单一权威类型源，与 --json schemaVersion 同源，S2 §3.6.4）

安装与使用

# 1. 安装为 DSH profile 插件（npm 发布后）
dsh plugin --profile web add huahua-dsh-plugin-orchestra

# 或本地路径安装（开发态）
dsh plugin --profile web add file:./huahua-dsh-plugin-orchestra

# 2. CLI 命令（node lib/cli/index.js，或经 bin 安装后直接 orchestra）
node lib/cli/index.js list --json                # 插件清单（L1 用途摘要，缓存优先）
node lib/cli/index.js check --json               # 检查更新（--force 绕 TTL 缓存但保留 ETag）
node lib/cli/index.js upgrade <pkg> [--to <ver>] [--dry-run] [--yes]   # 升级：自动备份，失败自动回滚
node lib/cli/index.js downgrade <pkg> --to <ver> [--yes]               # 降级
node lib/cli/index.js rollback <pkg> [--backup <id>] [--yes]           # 回滚（缺省最近有效快照）
node lib/cli/index.js backup list|create <pkg>|prune <pkg> [--force]   # 备份管理

• 面板：安装后 settings 页出现「插件管理」入口卡（含可更新数角标）+ 右上角通知中心；清单/详情/变更日志/升级/回滚/备份/设置齐全（S3）。
• 数据目录：~/.dsh/plugin-orchestra/（config.json / cache/ / backups/ / logs/，单一来源，S1 §13）。
• 环境变量：DSH_ORCHESTRA_*（如 DSH_ORCHESTRA_PROFILE / DSH_ORCHESTRA_DATA_DIR）；GITHUB_TOKEN / GH_TOKEN 提升 GitHub 限流配额（匿名 60/h → 5000/h）。
• 退出码：0 ok / 2 用法错 / 3 目标不存在 / 4 无操作 / 5 失败已回滚（可重试）/ 6 失败需人工 / 130 中断；非 TTY 写命令需 --yes（--dry-run 只读演练豁免）。

构建与测试

pnpm install        # 安装 devDeps（typescript 等）
pnpm typecheck      # 双 tsconfig 类型检查（host + client）
pnpm build          # tsc 编译（host → lib/，client → lib/client/）+ bundle-client（lib/client.js 浏览器产物，DSH loader 格式）
pnpm test           # build + node --test（node:test，无需额外框架）
pnpm test:client    # vitest + jsdom（组件测试，CI 跑）
pnpm test:client:direct  # node 直跑面板纯函数单测（沙箱/无 jsdom 环境）

> 注：沙箱/CI 中若 node --test 的 runner 子进程被拒（spawn EPERM）， > 可改为直接执行 node tests/xxx.test.mjs（node:test 内联运行）。

目录

src/
├── index.ts          # host 插件入口（re-export src/host/index）
├── domain/           # 领域模型：类型 + 常量 + 接口签名（零框架依赖）
│   ├── model.ts      # PluginRecord / UnifiedSource / ChangelogEntry ...
│   ├── updater.ts    # UpdateSource 接口 / VersionInfo / UpdateReport ...
│   ├── operation.ts  # op.state.json 阶段 / OperationResult / 退出码 ...
│   ├── config.ts     # ConfigSchema / 键白名单 schema / 面板设置视图
│   └── errors.ts     # 分级错误码（可重试/不可重试）
├── host/             # host 半边（cordis 插件装配 + 服务）
│   ├── index.ts      # 插件入口 + buildServices 装配（三服务 + Remote）+ 陈旧锁恢复
│   ├── remote.ts     # Typert Remote 契约 + 实现（16 方法）
│   ├── config-service.ts  # ConfigService（S1 §13 单一来源 config.json + 环境变量优先级）
│   ├── inventory/    # 清单服务：scanner（四态 spec / status local）/ spec / purpose（L0/L1/L2）/ inventory-service（缓存指纹）
│   ├── updater/      # 更新引擎：sources/（GitHub ETag + npm corgi）/ update-engine（single-flight）/ router / rate-limit / cache / semver / http / errors
│   └── install/      # 操作引擎：operation-engine（原子序列+崩溃恢复）/ op-state / backup（manifest 四态）/ path-guard（🔴-3）/ spawn / verify / drift / checksum
├── cli/             # orchestra CLI（退出码 0-6/130 + --json 外壳 + --force 白名单 + DX 契约）
│   └── index.ts / args.ts / app.ts / output.ts / help.ts / services.ts
└── client/          # client 半边（S3 面板，React）
    ├── index.ts      # client 装配入口（remote.$mount + shell + UI 安装）
    ├── install.ts    # installPluginOrchestraUi：settings 入口卡 + 通知中心 floater
    ├── contribution.ts  # Typert contribution（16 方法字段级 parse + strict codec）
    ├── shell.ts      # createBrowserShell（registerSlot/prompt/openExternal/copyText/...）
    ├── store.ts      # host-backed 数据源（useSyncExternalStore + 事件订阅 + 轮询兜底）
    ├── model.ts      # 视图折叠/筛选/排序/通知去重/recoverySuggestion（纯函数）
    ├── i18n.ts       # 冻结双语 catalog（zh-CN / en）
    ├── markdown.ts   # 受限 Markdown 渲染器（剥离 HTML，安全铁律）
    ├── diff.ts       # 并排行级 LCS diff（自研 ~60 行）
    ├── orchestra.css / css.d.ts
    └── components/   # PluginOrchestraApp（根）/ context / common / Icons
        ├── inventory/PluginListPage.tsx    # 清单页（搜索/筛选/排序/行内操作）
        ├── detail/PluginDetailPage.tsx     # 详情页（5 Tabs + 用途解读 L0/L1/L2）
        ├── ops/ops.tsx                      # ConfirmDialog（dry-run 预览）/ OperationProgress / ResultBanner / RecoveryDialog
        ├── notify/NotificationCenter.tsx    # 通知中心 floater + 角标
        ├── backups/BackupListView.tsx       # 备份管理（verified/corrupt）
        └── settings/SettingsPage.tsx        # 设置页（ADR-002 参数）

测试

tests/
├── 引擎侧（node:test，86 用例全绿）：path-guard 9 / operation-engine 17 / t19-fixes 6 / update-sources 11 / rate-limit 4 /
│   cli 14 / config-service 5 / remote 5 / inventory 5 / spec 4 / backup-manifest 3 / package-contract 2 / bundle-client 1
└── client/（面板，19 用例全绿）：model 8 / markdown 4 / diff 3 / contribution 4 + components.spec.tsx（vitest）

文档

• docs/L1_项目蓝图.md：顶层蓝图（里程碑 M1-M4 ✅）｜ docs/L3_项目纪要.md：阶段纪要
• docs/S1~S3：架构/工具层/面板设计 ｜ docs/adr/ADR-001~003：决策记录
• docs/S4_评审报告.md / S5_复核放行意见.md / S6_引擎层复核报告.md：质量门
• docs/handoff/：S1 阶段 handoff + 一期交付 handoff ｜ docs/一期-验收报告.md：验收报告（痛点→功能→证据）

License

MIT — see LICENSE.