minecraft-dev-starter 0.0.0-stage → 0.1.0

package/src/client/styles.js

@@ -0,0 +1,329 @@
+/**
+ * 样式：一次性注入 <style>，**只使用 DSH 的设计 token**（`--dsw-*`）。
+ *
+ * 规则来自系统自身：颜色一律走 `--dsw-alias-*`，字号走 `--dsw-font-*`，
+ * 控件高度对齐 24/28、圆角 3/4/8。不写死任何色值——跟随主题与皮肤切换，
+ * 也不会在亮色主题下突然出现一块深色面板。
+ *
+ * 这条约束由测试守护：`test/styles.test.js` 会拒绝出现原始色值的声明。
+ * @module minecraft-dev-starter/client/styles
+ */
+
+export const STYLE_ID = 'mcdev-styles'
+
+export const CSS = `
+.mcdev-anchor { position: relative; display: inline-flex; }
+.mcdev-capsule { display: inline-flex; align-items: center; gap: 4px; }
+
+/* 标题栏胶囊：与系统控件同高同圆角，默认无底色 */
+.mcdev-pill {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 24px;
+  max-width: 220px;
+  padding: 0 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 999px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-xxs-12);
+  cursor: pointer;
+}
+.mcdev-pill:hover { background: var(--dsw-alias-interactive-bg-hover); }
+/* 窄的时候让工程名让步：目标名永远完整显示 */
+.mcdev-pill-text { display: flex; align-items: center; min-width: 0; }
+.mcdev-pill-project {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--dsw-alias-label-secondary);
+}
+.mcdev-pill-sep { flex: none; padding: 0 4px; color: var(--dsw-alias-label-tertiary); }
+.mcdev-pill-target { flex: none; white-space: nowrap; }
+
+.mcdev-dot {
+  width: 7px;
+  height: 7px;
+  flex: none;
+  border-radius: 50%;
+  background: var(--dsw-alias-label-tertiary);
+}
+.mcdev-dot[data-state="ok"] { background: var(--dsw-alias-state-success-primary); }
+.mcdev-dot[data-state="warn"] { background: var(--dsw-alias-state-warn-primary); }
+.mcdev-dot[data-state="error"] { background: var(--dsw-alias-state-error-primary); }
+
+/* 浮层：三层结构（表头 / 列表 / 选择区），选工程时列表高度不变 */
+.mcdev-flyout {
+  position: absolute;
+  top: 30px;
+  right: 0;
+  z-index: 60;
+  display: flex;
+  flex-direction: column;
+  width: 340px;
+  max-height: 60vh;
+  padding: 0;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 8px;
+  background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-xxs-12);
+  box-shadow: 0 8px 24px var(--dsw-alias-bg-mask-1);
+  overflow: hidden;
+}
+.mcdev-flyout-head {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex: none;
+  padding: 10px 10px 8px;
+  border-bottom: 1px solid var(--dsw-alias-hairline);
+}
+.mcdev-flyout-list {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: auto;
+  padding: 6px;
+}
+.mcdev-flyout-pane {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  flex: none;
+  padding: 8px 10px 10px;
+  border-top: 1px solid var(--dsw-alias-hairline);
+}
+
+/* 列表行：一行一个工程，高度恒定 */
+.mcdev-list-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  width: 100%;
+  height: 30px;
+  padding: 0 8px;
+  border: 0;
+  border-radius: 4px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-xxs-12);
+  text-align: left;
+  cursor: pointer;
+}
+.mcdev-list-row:hover { background: var(--dsw-alias-interactive-bg-hover); }
+.mcdev-list-row[data-current="true"] { background: var(--dsw-alias-interactive-bg-hover); }
+.mcdev-list-row[data-current="true"] .mcdev-list-name { font: var(--dsw-font-xxs-strong-12); }
+.mcdev-list-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.mcdev-list-meta { flex: none; color: var(--dsw-alias-label-tertiary); font: var(--dsw-font-xxxs-11); }
+.mcdev-ellipsis { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+
+.mcdev-title { font: var(--dsw-font-xxs-strong-12); }
+.mcdev-sub { color: var(--dsw-alias-label-secondary); }
+.mcdev-muted { color: var(--dsw-alias-label-tertiary); }
+.mcdev-code { font-family: var(--dsw-font-mono); font-size: 11px; }
+.mcdev-warn { color: var(--dsw-alias-state-warn-primary); }
+.mcdev-error { color: var(--dsw-alias-state-error-primary); }
+
+.mcdev-row { display: flex; align-items: baseline; gap: 8px; }
+.mcdev-key { flex: none; width: 78px; color: var(--dsw-alias-label-tertiary); }
+
+.mcdev-mini {
+  display: inline-flex;
+  align-items: center;
+  gap: 3px;
+  height: 22px;
+  padding: 0 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xxxs-11);
+  cursor: pointer;
+}
+.mcdev-mini:hover { background: var(--dsw-alias-interactive-bg-hover); color: var(--dsw-alias-label-primary); }
+.mcdev-mini-icon { width: 22px; padding: 0; justify-content: center; }
+
+/* 目标标签：中性徽标，不是按钮——M2 之前没有可点的动作 */
+.mcdev-badges { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 6px; }
+.mcdev-badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 20px;
+  padding: 0 6px;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-3);
+  color: var(--dsw-alias-label-secondary);
+  font: var(--dsw-font-xxxs-11);
+}
+.mcdev-badge[data-guessed="true"] {
+  border-style: dashed;
+  background: transparent;
+  color: var(--dsw-alias-label-tertiary);
+}
+.mcdev-badge-tag { color: var(--dsw-alias-label-tertiary); }
+
+.mcdev-hint { color: var(--dsw-alias-label-tertiary); font: var(--dsw-font-xxxs-11); }
+
+/* 运行按钮：系统尺寸（24 高、4 圆角），中性底色 */
+.mcdev-actions { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 6px; }
+.mcdev-run {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  height: 24px;
+  padding: 0 8px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 4px;
+  background: transparent;
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-xxs-12);
+  cursor: pointer;
+}
+.mcdev-run:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); }
+.mcdev-run:disabled { opacity: 0.4; cursor: default; }
+.mcdev-run[data-tone="stop"] { color: var(--dsw-alias-danger); border-color: var(--dsw-alias-danger); }
+.mcdev-run-icon { width: 24px; padding: 0; justify-content: center; }
+
+/* 目标单选列表：一行一个，模块名做小标题 */
+.mcdev-options { display: flex; flex-direction: column; gap: 2px; margin-top: 6px; }
+.mcdev-option-group { display: flex; flex-direction: column; gap: 2px; }
+.mcdev-option-module { margin-top: 4px; color: var(--dsw-alias-label-tertiary); font: var(--dsw-font-xxxs-11); }
+.mcdev-option {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  height: 22px;
+  padding: 0 4px;
+  border-radius: 4px;
+  cursor: pointer;
+}
+.mcdev-option:hover { background: var(--dsw-alias-interactive-bg-hover); }
+.mcdev-option.is-disabled { opacity: 0.5; cursor: default; }
+.mcdev-radio { margin: 0; accent-color: var(--dsw-alias-accent); }
+.mcdev-option-label { font: var(--dsw-font-xxs-12); }
+
+.mcdev-status { margin-top: 6px; color: var(--dsw-alias-state-success-primary); font: var(--dsw-font-xxxs-11); }
+.mcdev-inline-status {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  margin-left: 8px;
+  color: var(--dsw-alias-state-success-primary);
+  font: var(--dsw-font-xxxs-11);
+}
+
+/* 日志尾部：等宽、可滚，底色用系统层级 3 */
+.mcdev-logs {
+  max-height: 220px;
+  margin: 8px 0 0;
+  padding: 8px;
+  overflow: auto;
+  border: 1px solid var(--dsw-alias-border-l1);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-3);
+  color: var(--dsw-alias-label-secondary);
+  font-family: var(--dsw-font-mono);
+  font-size: 11px;
+  line-height: 1.5;
+  white-space: pre-wrap;
+}
+
+/* 运行日志标签：顶部一条控制带，下面是整块日志 */
+.mcdev-logtab { display: flex; flex-direction: column; height: 100%; min-height: 0; padding: 8px 10px 10px; }
+.mcdev-log-head { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; padding-bottom: 8px; }
+.mcdev-select {
+  height: 24px;
+  max-width: 220px;
+  padding: 0 6px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-primary);
+  font: var(--dsw-font-xxxs-11);
+}
+.mcdev-follow { display: inline-flex; align-items: center; gap: 4px; color: var(--dsw-alias-label-tertiary); font: var(--dsw-font-xxxs-11); }
+.mcdev-diagnosis {
+  margin-bottom: 8px;
+  padding: 8px;
+  border: 1px solid var(--dsw-alias-state-error-primary);
+  border-radius: 4px;
+  background: var(--dsw-alias-bg-layer-2);
+}
+.mcdev-diagnosis-hint { color: var(--dsw-alias-state-error-primary); font: var(--dsw-font-xxs-strong-12); }
+.mcdev-logs-full { flex: 1 1 auto; min-height: 0; max-height: none; margin: 0; }
+
+.mcdev-section { margin-top: 12px; }
+.mcdev-section > h4 {
+  margin: 0 0 4px;
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xxxs-strong-11);
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+.mcdev-table { width: 100%; border-collapse: collapse; font: var(--dsw-font-xxxs-11); }
+.mcdev-table th,
+.mcdev-table td { padding: 3px 6px 3px 0; text-align: left; vertical-align: top; }
+.mcdev-table thead th {
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xxxs-strong-11);
+  border-bottom: 1px solid var(--dsw-alias-hairline);
+}
+
+.mcdev-detail { padding: 12px; font: var(--dsw-font-xxs-12); color: var(--dsw-alias-label-primary); }
+.mcdev-stack { display: flex; flex-direction: column; gap: 4px; }
+.mcdev-icon { display: inline-flex; align-items: center; justify-content: center; flex: none; }
+.mcdev-icon-text { display: inline-flex; align-items: center; gap: 4px; }
+
+/* 动效：短、克制；系统开了"减少动态效果"就全部关掉 */
+@keyframes mcdev-pop-in {
+  from { opacity: 0; transform: translateY(-4px); }
+  to { opacity: 1; transform: none; }
+}
+@keyframes mcdev-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.45; }
+}
+.mcdev-flyout { animation: mcdev-pop-in 120ms ease-out; }
+.mcdev-dot[data-pulse="true"] { animation: mcdev-pulse 1.6s ease-in-out infinite; }
+.mcdev-pill,
+.mcdev-run,
+.mcdev-mini,
+.mcdev-option { transition: background-color 120ms ease, color 120ms ease, border-color 120ms ease; }
+
+/* 骨架：扫描/加载中的占位，避免一片空白 */
+.mcdev-skeleton { display: flex; flex-direction: column; gap: 6px; margin-top: 8px; }
+.mcdev-skeleton-row {
+  height: 10px;
+  border-radius: 3px;
+  background: var(--dsw-alias-interactive-bg-hover);
+  animation: mcdev-pulse 1.4s ease-in-out infinite;
+}
+.mcdev-skeleton-row:nth-child(2) { width: 72%; }
+.mcdev-skeleton-row:nth-child(3) { width: 46%; }
+
+@media (prefers-reduced-motion: reduce) {
+  .mcdev-flyout,
+  .mcdev-dot[data-pulse="true"],
+  .mcdev-skeleton-row { animation: none; }
+  .mcdev-pill,
+  .mcdev-run,
+  .mcdev-mini,
+  .mcdev-option { transition: none; }
+}
+`
+
+/** 注入一次；重复调用无副作用。 */
+export function ensureStyles() {
+  if (typeof document === 'undefined') return
+  if (document.getElementById(STYLE_ID) !== null) return
+  const style = document.createElement('style')
+  style.id = STYLE_ID
+  style.textContent = CSS
+  document.head.appendChild(style)
+}

package/src/index.js

@@ -0,0 +1,165 @@
+/**
+ * 宿主入口：挂 `/mcdev/api` 路由，把请求交给方法表。
+ *
+ * 工作区根从"最近一个活跃会话的 cwd"取——HTTP 请求本身不带会话，
+ * 而模型工具那条路径有 `exec.agent.session.header.cwd`；两条路径最终都落到同一个扫描器。
+ * @module minecraft-dev-starter
+ */
+
+import { createApi } from './lib/api.js'
+import { createLaunchService } from './lib/launches.js'
+import { applyTools } from './tools.js'
+
+/** Cordis 插件名。 */
+export const name = 'mcdev-host'
+
+/** 依赖的宿主服务。 */
+export const inject = ['webServer', 'sessions', 'tools']
+
+/** 插件版本；客户端会显示，用来确认两边同一份代码。 */
+const VERSION = '0.1.0'
+
+/**
+ * @param {import('node:http').IncomingMessage} req
+ * @returns {Promise<unknown>}
+ */
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk) => {
+      raw += chunk
+      if (raw.length > 1024 * 1024) reject(new Error('body too large'))
+    })
+    req.on('end', () => {
+      if (raw.trim() === '') return resolve(undefined)
+      try {
+        resolve(JSON.parse(raw))
+      } catch (error) {
+        reject(error)
+      }
+    })
+    req.on('error', reject)
+  })
+}
+
+/**
+ * @param {import('node:http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} value
+ */
+function writeJson(res, status, value) {
+  const body = JSON.stringify(value)
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+/**
+ * 活跃会话的工作目录清单。
+ *
+ * 面板切会话时由客户端把 cwd 显式传下来；这里是"没传时"的兜底与启动校验的依据。
+ * `MCDEV_WORKSPACE` 是测试/固定工作区的逃生门。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {string[]}
+ */
+function sessionCwds(ctx) {
+  const pinned = process.env.MCDEV_WORKSPACE
+  if (typeof pinned === 'string' && pinned !== '') return [pinned]
+  /** @type {string[]} */
+  const roots = []
+  try {
+    for (const session of ctx.sessions.list()) {
+      const cwd = session?.header?.cwd
+      if (typeof cwd === 'string' && cwd !== '' && !roots.includes(cwd)) roots.push(cwd)
+    }
+  } catch {
+    /* 没有会话服务时退回进程 cwd */
+  }
+  if (roots.length === 0) roots.push(process.cwd())
+  return roots
+}
+
+/**
+ * 最近一个活跃会话的工作目录（扫描默认值）。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {string | undefined}
+ */
+function resolveWorkspaceRoot(ctx) {
+  return sessionCwds(ctx).at(-1)
+}
+
+/** 部署配置默认值；patch 行的 `config` 会覆盖同名项。 */
+const DEFAULTS = {
+  autoOpenLogTab: true,
+  readyTimeoutMs: 90_000,
+  logRingLines: 2_000,
+}
+
+/**
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {Record<string, unknown>} [config]
+ */
+export function apply(ctx, config = {}) {
+  const settings = { ...DEFAULTS, ...(config ?? {}) }
+  const api = createApi({
+    version: VERSION,
+    resolveRoot: () => resolveWorkspaceRoot(ctx),
+    resolveRoots: () => sessionCwds(ctx),
+    config: { autoOpenLogTab: settings.autoOpenLogTab !== false },
+    launchService: createLaunchService({
+      readyTimeoutMs: Number(settings.readyTimeoutMs) || DEFAULTS.readyTimeoutMs,
+      maxLogLines: Number(settings.logRingLines) || DEFAULTS.logRingLines,
+    }),
+  })
+
+  // 面板与模型共用同一套服务；工具只是薄封装（M5）
+  applyTools(ctx, { api })
+
+  ctx.effect(
+    () =>
+      ctx.webServer.register({
+        kind: 'prefix',
+        path: '/mcdev/api',
+        handler: async (req, res) => {
+          const { pathname } = new URL(req.url ?? '/', 'http://dsh.internal')
+
+          if (req.method === 'GET' && pathname === '/mcdev/api/ping') {
+            writeJson(res, 200, { ok: true, version: VERSION, pid: process.pid })
+            return
+          }
+          if (req.method !== 'POST') {
+            writeJson(res, 405, { ok: false, error: { code: 'method', message: 'use POST' } })
+            return
+          }
+
+          const method = pathname.startsWith('/mcdev/api/') ? pathname.slice('/mcdev/api/'.length) : ''
+          if (method === '' || method.includes('/')) {
+            writeJson(res, 404, { ok: false, error: { code: 'not-found', message: `unknown method "${method}"` } })
+            return
+          }
+          const handler = Object.hasOwn(api, method) ? api[method] : undefined
+          if (typeof handler !== 'function') {
+            writeJson(res, 404, { ok: false, error: { code: 'not-found', message: `unknown method "${method}"` } })
+            return
+          }
+
+          try {
+            const payload = await readJsonBody(req)
+            const result = await handler(payload)
+            writeJson(res, 200, { ok: true, result })
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error)
+            console.warn(`[mcdev] ${method} failed: ${message}`)
+            writeJson(res, 500, { ok: false, error: { code: 'internal', message } })
+          }
+        },
+      }),
+    'mcdev: /mcdev/api routes',
+  )
+
+  console.log(`[mcdev] host ready (${VERSION}) — /mcdev/api/{projects.scan,projects.detail,state.info}`)
+}

package/src/lib/api.js

@@ -0,0 +1,186 @@
+/**
+ * `/mcdev/api` 的方法表。宿主入口只负责挂路由，具体动作在这里。
+ *
+ * 方法名与请求体形状一旦定下就是客户端合同，改名前先改客户端与文档。
+ * @module minecraft-dev-starter/lib/api
+ */
+
+import { detectProject } from './detect.js'
+import { discoverJdks } from './java.js'
+import { createLaunchService } from './launches.js'
+import { scanWorkspace } from './scanner.js'
+
+/** 扫描结果的短缓存：面板打开/切会话会连着问几次，没必要每次重扫。 */
+const CACHE_TTL_MS = 5000
+
+/** 客户端诊断上报的最近若干条（只在开发期用）。 */
+const clientReports = []
+
+/**
+ * 判断子路径是否落在父路径之下（Windows 下大小写不敏感）。
+ * @param {string} child
+ * @param {string} parent
+ * @returns {boolean}
+ */
+function isInside(child, parent) {
+  const normalize = (value) => value.replace(/\//g, '\\').replace(/\\+$/, '').toLowerCase()
+  const a = normalize(child)
+  const b = normalize(parent)
+  return a === b || a.startsWith(`${b}\\`)
+}
+
+/**
+ * @param {{ resolveRoot: () => Promise<string | undefined>, resolveRoots?: () => Promise<string[]>, version?: string, config?: Record<string, unknown>, launchService?: ReturnType<typeof createLaunchService> }} options
+ */
+export function createApi(options) {
+  /** @type {Map<string, { at: number, value: unknown }>} */
+  const cache = new Map()
+  const launches = options.launchService ?? createLaunchService()
+
+  /**
+   * @param {string | undefined} requested
+   * @returns {Promise<string>}
+   */
+  async function resolveRoot(requested) {
+    const root = requested ?? (await options.resolveRoot())
+    if (root === undefined || root === '') {
+      throw new Error('找不到工作区目录：请求里没带 root，宿主也没有活跃会话')
+    }
+    return root
+  }
+
+  return {
+    /**
+     * 扫工作区：`{ root?, depth?, refresh? }` → `{ root, projects, truncated, scannedAt }`。
+     * @param {unknown} payload
+     */
+    'projects.scan': async (payload) => {
+      const input = /** @type {{ root?: string, depth?: number, refresh?: boolean }} */ (payload ?? {})
+      const root = await resolveRoot(input.root)
+      const key = `${root}|${input.depth ?? 3}`
+      const cached = cache.get(key)
+      if (input.refresh !== true && cached !== undefined && Date.now() - cached.at < CACHE_TTL_MS) {
+        return cached.value
+      }
+      const jdks = await discoverJdks()
+      const result = await scanWorkspace(root, { depth: input.depth, jdks })
+      console.log(`[mcdev] projects.scan ${root} → ${result.projects.length} 个工程（${result.scannedDirs} 个目录）`)
+      const value = { ...result, scannedAt: new Date().toISOString() }
+      cache.set(key, { at: Date.now(), value })
+      return value
+    },
+
+    /**
+     * 单工程详情：`{ root }` → 完整画像。
+     * @param {unknown} payload
+     */
+    'projects.detail': async (payload) => {
+      const input = /** @type {{ root?: string }} */ (payload ?? {})
+      const root = await resolveRoot(input.root)
+      return detectProject(root, { jdks: await discoverJdks() })
+    },
+
+    /** 宿主/插件版本、工作区根与部署配置，客户端启动时打一次。 */
+    'state.info': async () => ({
+      version: options.version,
+      root: await options.resolveRoot(),
+      config: options.config ?? {},
+    }),
+
+    /**
+     * 启动实例：`{ root, taskPath, label?, kind?, module?, extraArgs? }`。
+     * 只允许启动"识别得出的目标"，并且工程必须落在当前工作区之内。
+     * @param {unknown} payload
+     */
+    'launch.start': async (payload) => {
+      const input = /** @type {{ root?: string, taskPath?: string, label?: string, kind?: string, module?: string, extraArgs?: string[] }} */ (payload ?? {})
+      const root = await resolveRoot(input.root)
+      // 工作区可能不止一个（每个会话一个 cwd）：只要落在其中任意一个之内就放行，
+      // 否则切到另一个工程的会话后会被误判成"越界"。
+      const workspaces = options.resolveRoots === undefined ? [await resolveRoot(undefined)] : await options.resolveRoots()
+      if (!workspaces.some((workspace) => isInside(root, workspace))) {
+        throw Object.assign(new Error(`工程不在当前工作区内：${root}`), { code: 'OUTSIDE_WORKSPACE' })
+      }
+      if (typeof input.taskPath !== 'string' || input.taskPath === '') {
+        throw Object.assign(new Error('缺少 taskPath'), { code: 'BAD_REQUEST' })
+      }
+      const profile = await detectProject(root, { jdks: await discoverJdks() })
+      const targets = /** @type {Array<Record<string, any>>} */ (profile.runTargets ?? [])
+      const target = targets.find((entry) => entry.taskPath === input.taskPath)
+      if (target === undefined) {
+        throw Object.assign(new Error(`工程里没有这个可运行目标：${input.taskPath}`), { code: 'UNKNOWN_TARGET' })
+      }
+      const record = await launches.start({
+        root,
+        taskPath: target.taskPath,
+        label: input.label ?? target.label ?? target.taskPath,
+        kind: input.kind ?? target.kind ?? 'client',
+        module: input.module ?? target.module ?? '.',
+        extraArgs: Array.isArray(input.extraArgs) ? input.extraArgs.filter((entry) => typeof entry === 'string') : [],
+      })
+      console.log(`[mcdev] launch.start ${record.id} ${record.taskPath} @ ${root} (pid ${record.pid})`)
+      return record
+    },
+
+    /**
+     * 停止实例：`{ id }`。
+     * @param {unknown} payload
+     */
+    'launch.stop': async (payload) => {
+      const input = /** @type {{ id?: string }} */ (payload ?? {})
+      if (typeof input.id !== 'string' || input.id === '') {
+        throw Object.assign(new Error('缺少实例 id'), { code: 'BAD_REQUEST' })
+      }
+      const record = await launches.stop(input.id)
+      console.log(`[mcdev] launch.stop ${input.id} → ${record.status}/${record.outcome ?? '-'}`)
+      return record
+    },
+
+    /**
+     * 列实例：`{ root? }`，最新的在前。
+     * @param {unknown} payload
+     */
+    'launch.list': async (payload) => {
+      const input = /** @type {{ root?: string }} */ (payload ?? {})
+      const all = await launches.list()
+      if (typeof input.root !== 'string' || input.root === '') return all
+      const root = input.root.toLowerCase()
+      return all.filter((record) => String(record.root).toLowerCase() === root)
+    },
+
+    /**
+     * 这个工程当前活跃的实例：`{ root }`。
+     * @param {unknown} payload
+     */
+    'launch.current': async (payload) => {
+      const input = /** @type {{ root?: string }} */ (payload ?? {})
+      const root = await resolveRoot(input.root)
+      return (await launches.current(root)) ?? null
+    },
+
+    /**
+     * 读日志：`{ id, offset?, limit? }`。
+     * @param {unknown} payload
+     */
+    'launch.logs': async (payload) => {
+      const input = /** @type {{ id?: string, offset?: number, limit?: number }} */ (payload ?? {})
+      if (typeof input.id !== 'string' || input.id === '') {
+        throw Object.assign(new Error('缺少实例 id'), { code: 'BAD_REQUEST' })
+      }
+      return launches.logs(input.id, Number.isFinite(input.offset) ? Number(input.offset) : 0, Number.isFinite(input.limit) ? Number(input.limit) : 400)
+    },
+
+    /**
+     * 客户端诊断上报（开发期）：`{ event, detail }` → `{ ok, count }`。
+     * 只在宿主日志里留一行，并保留最近 20 条供后续排查。
+     * @param {unknown} payload
+     */
+    'client.report': async (payload) => {
+      const input = /** @type {{ event?: string, detail?: unknown }} */ (payload ?? {})
+      clientReports.push({ at: new Date().toISOString(), event: input.event, detail: input.detail })
+      if (clientReports.length > 20) clientReports.shift()
+      console.log(`[mcdev] client: ${input.event} ${JSON.stringify(input.detail ?? {})}`)
+      return { ok: true, count: clientReports.length }
+    },
+  }
+}