minecraft-dev-starter 0.1.3 → 0.1.5

package/AGENTS.md

@@ -176,6 +176,18 @@ server：`Done (…s)!`）；状态落盘并做重启后对账。顺带修了 GB
 - 新版本发出去后，用干净 profile 装一次并看启动日志里的 `host ready (x.y.z)`，
   这条同时验证了「版本号读对了」与「包结构完整」。
 
+## 安全告警（npm / Socket）
+
+npm 包页面上会出现两条告警，都来自 peer 依赖图，不是本包代码：
+
+- **High CVE**：`zod@<4.6.6`（GHSA-mrhx-c7xc-m3w5），经 `@deepseek-ai/dsh-llm` 传导，
+  属于官方运行时 `@deepseek-ai/dsh-tools` 的树。本包 `dependencies` 为空，改不了；只能等上游升 zod。
+- **Uses eval**：**误报**。`@deepseek-ai/dsh-ptc-runtime/lib/index.js` 里有一张保留字表，
+  其中一项就是字符串 `"eval"`，静态扫描按字符串命中了。本仓库与产物里 `\beval\b` 零命中（可复查）。
+
+结论：不要为了这两条去改依赖声明（把 peer 改成 optional 也挡不住 CVE，因为它是真实的传递依赖）。
+需要清除误报就往 Socket 的 false positive 通道提；需要修 CVE 就等官方升 `zod`。
+
 ## 还没做的事
 
 - **M6 通用启动器**：HMCL 实例库 + 直启 java，让面板也能起非 Gradle 工程（估 5–8 天）。

package/README.md

@@ -1,136 +1,129 @@
-# minecraft-dev-starter
-
-在 DSH（DeepSeek Harness）的会话标题栏放一个 IDEA 风格的运行控件：认出工作区里的 Minecraft 模组工程，点一下就能起 Client，日志就在右侧栏。
-
-给做模组的人用，不是给 AI 用的——AI 侧只是顺带留了几个工具。
-
-## 能做什么
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Chemiofitor4096/minecraft-dev-starter/main/assets/banner.png" alt="minecraft-dev-starter" width="100%">
+</p>
 
-**识别**：Fabric、Forge、NeoForge、Architectury、Paper、Spigot，覆盖 1.7.10 到 26.x。
-单模块、多模块、聚合仓库都能认；loader 写在子模块里也能认。
-
-**启动**：Client / Server / Data / GameTestServer。自动挑 JDK（读 `<jdk>/release`，不乱起进程）；
-构建完能判断"进游戏了"而不是"进程还活着"；关掉游戏后状态同步；宿主重启后按 pid 对账，不伪造结束原因。
+# minecraft-dev-starter
 
-**看日志**：右侧栏独立标签，按工程列历史、默认显示最新、可跟随尾部；
-崩溃时给一句归因（依赖没解析、JDK 版本不对、端口被占、认证失败等 8 类）。
+为 DeepSeek Harness 添加 Minecraft 模组开发运行控件。
 
-**多工程与多会话**：工作区里每个工程分别记住自己选的目标；切换对话即切换工作区，不需要手动刷新。
+插件识别当前工作区中的 Minecraft 模组与插件工程，在会话标题栏提供运行目标的选择与启动、停止操作，并将运行日志输出到侧边栏标签页。
 
-**AI 工具**（可选）：`mc_projects` / `mc_launch` / `mc_launch_logs` / `mc_launch_stop`，与面板共用同一套服务。
+## 功能
 
-**better-sidebar**：装了 [dsh-better-sidebar](https://github.com/topics/dsh-better-sidebar)，还会多出两个带图标的侧栏页面。
+- **工程识别**：支持 Fabric、Forge、NeoForge、Architectury、Paper 与 Spigot，覆盖 Minecraft 1.7.10 至 26.x。支持单模块、多模块与聚合仓库；loader 声明位于子模块时同样可以识别。
+- **运行目标**：从 Gradle 配置中提取 Client、Server、Data、GameTestServer 等任务。按 loader 惯例推测的目标会标记为未验证，不影响选择与启动。
+- **托管启动**：通过 Gradle Wrapper 启动任务，依据日志标记判定是否进入运行状态，而非仅依据进程存活。停止时终止 Gradle 及其全部子进程。
+- **状态保持**：运行记录持久化到本地。宿主重启后按进程 ID 校验：确认存活则继续跟踪，无法确认则记为未知，不推测退出原因。
+- **运行日志**：独立侧边栏标签页，按工程展示启动历史，支持跟随输出。日志按级别着色：WARN 与 ERROR 高亮，堆栈帧与 Gradle 任务行区分显示，时间、线程与 logger 弱化。异常退出时给出可能原因，覆盖依赖解析失败、JDK 版本不匹配、端口占用、认证失败等情况。
+- **工作区跟随**：以当前会话的工作目录作为工作区，切换会话时自动重新扫描，无需手动刷新。
+- **模型工具**（可选）：提供 `mc_projects`、`mc_launch`、`mc_launch_logs`、`mc_launch_stop` 四个工具，与面板共用同一套服务。
+- **扩展集成**：安装 [dsh-better-sidebar](https://github.com/topics/dsh-better-sidebar) 后，面板与日志可在其侧边栏中作为带图标的标签页打开。
 
 ## 安装
 
-需要 DSH 桌面版（0.2.1 及以上）或 dsh CLI。
+要求 DSH 桌面版 0.2.1 或更高版本，或对应的 `dsh` CLI。
 
 ```powershell
-# 本地仓库（改完即生效）
-dsh plugin --profile desktop add link:C:/Projects/minecraft-dev-starter
+# 从 npm 安装
+dsh plugin --profile desktop add minecraft-dev-starter
 
-# 打好的 tarball
-dsh plugin --profile desktop add file:./minecraft-dev-starter-0.1.0.tgz
+# 本地仓库（修改后即时生效）
+dsh plugin --profile desktop add link:C:/Projects/minecraft-dev-starter
 
-# 从 npm 安装（发布之后）
-dsh plugin --profile desktop add minecraft-dev-starter
+# 使用打包文件
+dsh plugin --profile desktop add file:./minecraft-dev-starter-0.1.3.tgz
 ```
 
-装完**重启 DSH** 生效。卸载：
+安装完成后需重启 DSH 生效。卸载：
 
 ```powershell
 dsh plugin --profile desktop remove minecraft-dev-starter
 ```
 
-`dsh plugin` 实际是 pnpm 的转发器：它把包装进 profile、再把声明了 `dsh.bundle` 的依赖加进
-`dsh.profile.bundles` 层列表。所以手工在 profile 的 `package.json` 里加一行再用 pnpm 安装，
-效果是一样的。
+`dsh plugin` 是 pnpm 的封装：将插件加入 profile 的依赖，并把声明了 `dsh.bundle` 的包加入 `dsh.profile.bundles` 列表。直接编辑 profile 的 `package.json` 后执行 `pnpm install`，效果相同。
 
 ## 使用
 
-1. 打开一个模组工程所在的对话。
-2. 标题栏出现 `● Client ▶`。点名字展开浮层，选工程与目标；点 ▶ 开始构建并启动。
-3. 启动后自动打开「运行日志」（可在配置里关掉），日志实时刷新。
-4. 再点一次按钮（变成 ⏹）停止，会连同 Gradle 拉起的整个进程树一起结束。
+1. 打开包含 Minecraft 工程的工作区会话。
+2. 标题栏显示当前选中的运行目标。点击目标名称打开浮层，从中选择工程与任务。
+3. 点击启动按钮开始构建并运行。启动后自动打开「运行日志」标签页，该行为可通过配置关闭。
+4. 运行期间按钮切换为停止；点击后终止 Gradle 及其子进程。
 
-浮层形态会自适应：工作区里只有一个工程时跳过列表，表头直接是工程名、loader/版本与路径；
-有多个工程时列表固定高度，选谁只换下面的目标区，界面不会跳。
+浮层布局随工程数量变化：单工程工作区不显示工程列表，表头直接呈现工程名称、loader 与版本、路径；多工程工作区显示固定高度的列表，切换工程时仅更新下方目标区域，页面不会跳动。
 
 ## 配置
 
-在 profile 的 `cordis.patch.yml` 里给插件那行加 `config`：
+在 profile 的 `cordis.patch.yml` 中为该插件条目添加 `config` 字段：
 
 ```yaml
 - id: mcdev-host
   name: minecraft-dev-starter
   config:
-    autoOpenLogTab: true   # 启动后自动打开日志标签
-    readyTimeoutMs: 90000  # 等"进游戏"的上限，超时不算失败
-    logRingLines: 2000     # 内存里保留的日志行数（磁盘文件是完整的）
+    autoOpenLogTab: true
+    logDock: right          # right：DSH 原生右侧栏；bottom：dsh-better-sidebar 的底部工作台
+    readyTimeoutMs: 90000
+    logRingLines: 2000
 ```
 
-## 支持范围
+| 配置项 | 类型 | 默认值 | 说明 |
+|---|---|---|---|
+| `autoOpenLogTab` | boolean | `true` | 启动后自动打开运行日志标签页 |
+| `logDock` | `right` \| `bottom` | `right` | 日志打开位置。`bottom` 需要安装 dsh-better-sidebar；未安装时自动回退到右侧栏 |
+| `readyTimeoutMs` | number | `90000` | 等待进入运行状态的超时时间；超时不计为失败 |
+| `logRingLines` | number | `2000` | 内存中保留的日志行数；磁盘上的日志始终完整 |
+
+`logDock` 只影响「自动打开」与面板里的「打开日志」按钮；无论配置为何，两个标签页都同时存在于原生右侧栏与 better-sidebar 的页签列表中，可随时手动打开。
 
-| 平台 | 版本线 | 说明 |
+## 兼容范围
+
+| 平台 | 版本范围 | 说明 |
 |---|---|---|
-| Fabric | 1.14 – 26.x | loom 的 `runClient` 一族 |
-| Forge | 1.7.10 / 1.12.2 / 1.16.5 / 1.20.1 | 包括 legacyforge |
+| Fabric | 1.14 – 26.x | loom 提供的 `runClient` 等任务 |
+| Forge | 1.7.10 / 1.12.2 / 1.16.5 / 1.20.1 | 包含 legacyforge |
 | NeoForge | 1.20.1 – 26.x | moddev 插件 |
-| Architectury | 1.16 – 26.x | 按子模块拆目标 |
+| Architectury | 1.16 – 26.x | 按子模块拆分任务 |
 | Paper / Spigot | 1.7.10 – 26.x | 服务端插件工程 |
 
-JDK 需求按版本推断（1.7.10/1.12.2 → 8，1.18–1.20.4 → 17，1.20.5+ → 21，26.x → 25），
-和机器上已装的 JDK 比对，缺了会在面板里提示，不会带着错的版本硬跑。
+JDK 版本按 Minecraft 版本推断：1.7.10 与 1.12.2 需要 Java 8，1.18 至 1.20.4 需要 Java 17，1.20.5 及以上需要 Java 21，26.x 需要 Java 25。插件将需求与已安装的 JDK 比对，缺失或版本不符时在面板中提示。
 
 ## 开发
 
 ```powershell
 npm install
-npm run build        # 构建客户端到 lib/client.js（改 src/client 后必须跑）
+npm run build        # 构建客户端到 lib/client.js；修改 src/client 后必须执行
 npm test             # 59 个测试
 npm run build -- --watch
 ```
 
-仓库结构、硬坑清单与历史验证结论都在 [AGENTS.md](./AGENTS.md)。
-设计文档：[策划](./doc/策划.md) · [DSH 插件机制调研](./doc/调研-DSH插件机制.md)。
+仓库结构、已知问题与历次验证结论见 [AGENTS.md](./AGENTS.md)。设计文档：[策划](./doc/策划.md)、[DSH 插件机制调研](./doc/调研-DSH插件机制.md)。
 
 ## 发布
 
-DSH 插件的分发就是 npm 包 + 一份清单声明，没有单独的注册流程：
-
-1. **清单**：`package.json` 里声明 `dsh.bundle.patch`（指向 `cordis.patch.yml`）与
-   `dsh.client.platform`（有客户端时）。宿主靠这两项决定"这是不是一个 DSH 插件"。
-2. **产物**：`npm run build` 把客户端打进 `lib/client.js` 并**提交进仓库**——
-   运行时直接读它，不装依赖也不做构建。
-3. **自检**：`npm test`，`npm pack --dry-run` 看包里有没有多余文件（`files` 字段已限定
-   `src`、`lib`、`cordis.patch.yml`、README、AGENTS）。
-4. **发布**：`npm publish --access public`。版本号走 semver，破坏性改动升主版本。
+DSH 插件以 npm 包形式分发，不需要独立注册流程。
 
-   如果用的是 granular token（只允许暂存），会被拒为 `E_STAGE_REQUIRED`，改走两步：
+1. **清单**：`package.json` 声明 `dsh.bundle.patch`（指向 `cordis.patch.yml`）；提供浏览器界面时同时声明 `dsh.client.platform`。宿主依据这两项识别插件。
+2. **产物**：执行 `npm run build` 生成 `lib/client.js`，并将该文件提交到仓库。运行时直接读取产物，不安装依赖，也不执行构建。
+3. **校验**：执行 `npm test`；使用 `npm pack --dry-run` 确认包内容（`files` 字段已限定为 `src`、`lib`、`cordis.patch.yml`、README 与 AGENTS）。
+4. **发布**：`npm publish --access public`。若使用仅允许暂存的 granular token，改为以下流程：
 
    ```powershell
-   npm stage publish                 # 提交到暂存区，拿到 stage-id
-   npm stage list                   # 看到 status: validated 再批准
-   npm stage approve <stage-id>      # 需要人工过 2FA（网页确认）
+   npm stage publish                 # 提交到暂存区
+   npm stage list                   # 等待状态变为 validated
+   npm stage approve <stage-id>      # 人工完成 2FA 确认
    ```
 
-   暂存 → 人工批准是 npm 的设计：机器提交、人确认，token 泄露也发不出正式版本。
-   批准后 `latest` 自动指向新版本，通常十几秒内可从 registry 拉到。
-
-5. **兼容性**：宿主 API 会演进（本插件按 0.2.1-rc.3 的 `dsh-tools` 开发）。发布前把
-   `dependencies` 里的 `@deepseek-ai/dsh-tools` 与 `peerDependencies` 的 cordis 范围对齐
-   目标运行时；跨大版本时最好发两个版本而不是硬兼容。
-6. **安装**：用户 `dsh plugin --profile <name> add <包名>` 后重启；也可以在 Plugins 面板里装。
+   暂存后由人工批准是 npm 的设计：机器提交、人工确认，即使 token 泄露也无法直接发布正式版本。批准后 `latest` 标签自动指向新版本。
+5. **兼容性**：宿主 API 会持续演进。发布前将 `@deepseek-ai/dsh-tools` 与 `@deepseek-ai/cordis` 的版本范围对齐目标运行时；跨大版本时应分别发布版本，而非放宽范围强行兼容。
+6. **安装**：用户执行 `dsh plugin --profile <name> add <包名>` 后重启，或在 Plugins 面板中安装。
 
-本地想先验证发布形态，可以 `npm pack` 后用 `dsh plugin add file:<tarball>` 装一遍——
-它会走和 npm 安装完全相同的 pnpm 路径。
+在本地验证发布形态时，可先 `npm pack`，再通过 `dsh plugin add file:<tarball>` 安装；该路径与 npm 安装完全一致。
 
 ## 已知限制
 
-- 原生右侧栏的标签类型没有图标位，只有 better-sidebar 的标签能带图标。
-- 只支持 Gradle 工程；HMCL 实例库里的整合包还不能直接起（见 AGENTS.md 的 M6）。
-- 状态文件放在 `~/.dsh/mc-dev-starter/`，多个 profile 共用一份；日志标签按工程过滤，不影响使用。
-- Windows 上第一次构建会下载 Gradle 与依赖，可能要几分钟；之后有 daemon 会快很多。
+- 原生右侧栏的标签类型不提供图标字段，图标仅支持 `dsh-better-sidebar` 中的标签。
+- 当前仅支持 Gradle 工程；HMCL 实例库中的整合包尚不支持（见 AGENTS.md 的 M6）。
+- 运行状态保存于 `~/.dsh/mc-dev-starter/`，多个 profile 共用同一份记录；日志标签按工程过滤，功能不受影响。
+- 在 Windows 上首次构建需要下载 Gradle 与项目依赖，耗时可能达到数分钟；后续构建可使用 Gradle daemon。
 
 ## License
 

package/lib/client.js

@@ -238,9 +238,19 @@ async function call(method, payload) {
   return body.result;
 }
 
+// src/client/dock.js
+var LOG_DOCK_RIGHT = "right";
+var LOG_DOCK_BOTTOM = "bottom";
+function chooseLogDock(config, hasBetterSidebar) {
+  if (hasBetterSidebar !== true) return LOG_DOCK_RIGHT;
+  return config?.logDock === LOG_DOCK_BOTTOM ? LOG_DOCK_BOTTOM : LOG_DOCK_RIGHT;
+}
+
 // src/client/runtime.js
 var DETAIL_KIND = "mcdev.detail";
 var LOG_KIND = "mcdev.logs";
+var BETTER_DETAIL_ID = "minecraft-dev-starter:project";
+var BETTER_LOG_ID = "minecraft-dev-starter:logs";
 var runtime = {};
 function open(kind) {
   const sidebar = runtime.ctx?.sidebarRight;
@@ -252,10 +262,25 @@ function open(kind) {
     return false;
   }
 }
+function betterSidebar() {
+  try {
+    return runtime.ctx?.get?.("betterSidebar", false);
+  } catch {
+    return void 0;
+  }
+}
 function openDetailTab() {
   return open(DETAIL_KIND);
 }
-function openLogTab() {
+function openLogTab(config) {
+  const service = betterSidebar();
+  if (chooseLogDock(config, service !== void 0) === LOG_DOCK_BOTTOM) {
+    try {
+      service.openTab({ type: BETTER_LOG_ID, title: "\u8FD0\u884C\u65E5\u5FD7", target: "bottom" });
+      return true;
+    } catch {
+    }
+  }
   return open(LOG_KIND);
 }
 
@@ -296,15 +321,15 @@ var store = createStore({
   flyoutOpen: false,
   /** @type {Record<string, string>} 每个工程记住的目标 key */
   selection: readSelection(),
-  /** @type {{ autoOpenLogTab?: boolean }} 宿主下发的部署配置 */
-  config: { autoOpenLogTab: true },
+  /** @type {{ autoOpenLogTab?: boolean, logDock?: 'right' | 'bottom' }} 宿主下发的部署配置 */
+  config: { autoOpenLogTab: true, logDock: "right" },
   /** @type {string | undefined} 当前会话的工作区（由胶囊从会话上下文注入） */
   workspaceRoot: void 0
 });
 async function loadStateInfo() {
   try {
     const info = await call("state.info", {});
-    store.set({ config: { autoOpenLogTab: true, ...info?.config ?? {} } });
+    store.set({ config: { autoOpenLogTab: true, logDock: "right", ...info?.config ?? {} } });
   } catch {
   }
 }
@@ -396,7 +421,7 @@ async function startTarget(project, target) {
       kind: target.kind,
       module: target.module
     });
-    if (store.get().config.autoOpenLogTab !== false) openLogTab();
+    if (store.get().config.autoOpenLogTab !== false) openLogTab(store.get().config);
   } catch (error) {
     launchStore.set({ error: error instanceof Error ? error.message : String(error) });
   } finally {
@@ -837,7 +862,7 @@ function DetailTab() {
           ),
           h(
             "button",
-            { type: "button", className: "mcdev-run", onClick: () => openLogTab() },
+            { type: "button", className: "mcdev-run", onClick: () => openLogTab(store.get().config) },
             "\u6253\u5F00\u65E5\u5FD7"
           )
         )
@@ -920,6 +945,66 @@ function row(key, value) {
 
 // src/client/LogTab.js
 var import_react5 = require("react");
+
+// src/client/logFormat.js
+var ANSI = /\u001b\[[0-9;]*[A-Za-z]/g;
+function seg(text2, kind) {
+  return { text: text2, kind };
+}
+function levelKind(level) {
+  const upper = level.toUpperCase();
+  if (upper === "WARN" || upper === "WARNING") return "level-warn";
+  if (upper === "ERROR" || upper === "FATAL" || upper === "SEVERE") return "level-error";
+  if (upper === "DEBUG" || upper === "TRACE" || upper === "FINE" || upper === "FINER") return "level-debug";
+  return "level-info";
+}
+var LOG4J = /^\[(\d{2}:\d{2}:\d{2})\]\s+\[([^\]]+?)\/([A-Z]+)\]\s*(?:\[([^\]]*)\]:\s*|:\s*)?(.*)$/;
+var PAPER = /^\[(\d{2}:\d{2}:\d{2}) ([A-Z]+)\]:\s*(.*)$/;
+var BARE_LEVEL = /^(TRACE|DEBUG|INFO|WARN|WARNING|ERROR|FATAL)\s+(.*)$/;
+var STACK = /^\s+(at |\.\.\. \d+ more)/;
+function highlightLine(raw) {
+  const line = String(raw ?? "").replace(ANSI, "");
+  if (line === "") return [seg("", "plain")];
+  if (/^Caused by:|^\s+Suppressed:/.test(line)) return [seg(line, "fail")];
+  if (STACK.test(line)) return [seg(line, "stack")];
+  const log4j = LOG4J.exec(line);
+  if (log4j !== null) {
+    const [, time, thread, level, logger, message] = log4j;
+    const kind = levelKind(level);
+    const parts = [
+      seg(`[${time}] `, "time"),
+      seg(`[${thread}/`, "thread"),
+      seg(level, kind),
+      seg(logger === void 0 ? "]: " : "] ", "thread")
+    ];
+    if (logger !== void 0) parts.push(seg(`[${logger}]: `, "logger"));
+    parts.push(seg(message, kind === "level-error" ? "level-error" : "message"));
+    return parts;
+  }
+  const paper = PAPER.exec(line);
+  if (paper !== null) {
+    const [, time, level, message] = paper;
+    return [
+      seg(`[${time} `, "time"),
+      seg(level, levelKind(level)),
+      seg("]: ", "time"),
+      seg(message, levelKind(level) === "level-error" ? "level-error" : "message")
+    ];
+  }
+  const bare = BARE_LEVEL.exec(line);
+  if (bare !== null) {
+    const [, level, message] = bare;
+    return [seg(`${level} `, levelKind(level)), seg(message, levelKind(level) === "level-error" ? "level-error" : "message")];
+  }
+  if (/^> Task /.test(line) || /^> Configure project /.test(line)) return [seg(line, "task")];
+  if (/^BUILD SUCCESSFUL/.test(line)) return [seg(line, "ok")];
+  if (/^BUILD FAILED/.test(line) || /^FAILURE:/.test(line)) return [seg(line, "fail")];
+  if (/^\* What went wrong:|^\* Where:|^\* Try:/.test(line)) return [seg(line, "level-warn")];
+  if (/^(Reusing configuration cache|Deprecated Gradle features|You can use)/.test(line)) return [seg(line, "muted")];
+  return [seg(line, "plain")];
+}
+
+// src/client/LogTab.js
 var lastLogId;
 function LogTab() {
   const launches = useLaunches(1500);
@@ -1029,7 +1114,20 @@ function LogTab() {
       ),
       h("div", { className: "mcdev-hint mcdev-code" }, log.diagnosis.line)
     ),
-    log?.error === void 0 ? log === void 0 && running ? h(Skeleton, { rows: 4, hint: "\u6B63\u5728\u8BFB\u53D6\u65E5\u5FD7\u2026" }) : h("pre", { ref: body, className: "mcdev-logs mcdev-logs-full" }, (log?.lines ?? []).join("\n") || "\uFF08\u8FD8\u6CA1\u6709\u8F93\u51FA\uFF09") : h("div", { className: "mcdev-error", style: { marginTop: 8 } }, log.error),
+    log?.error === void 0 ? log === void 0 && running ? h(Skeleton, { rows: 4, hint: "\u6B63\u5728\u8BFB\u53D6\u65E5\u5FD7\u2026" }) : h(
+      "pre",
+      { ref: body, className: "mcdev-logs mcdev-logs-full" },
+      (log?.lines ?? []).length === 0 ? "\uFF08\u8FD8\u6CA1\u6709\u8F93\u51FA\uFF09" : (log?.lines ?? []).map(
+        (line, index) => h(
+          "span",
+          { key: index, className: "mcdev-log-line" },
+          highlightLine(line).map(
+            (part, partIndex) => h("span", { key: partIndex, "data-kind": part.kind }, part.text)
+          ),
+          "\n"
+        )
+      )
+    ) : h("div", { className: "mcdev-error", style: { marginTop: 8 } }, log.error),
     h(
       "div",
       { style: { marginTop: 8 } },
@@ -1302,6 +1400,20 @@ var CSS = `
 .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; }
 
+/* \u65E5\u5FD7\u9AD8\u4EAE\uFF1A\u53EA\u6309\u8BED\u4E49\u4E0A\u8272\uFF0C\u65F6\u95F4/\u7EBF\u7A0B/logger \u4E00\u5F8B\u538B\u5230 tertiary\uFF0C\u8BA9\u6B63\u6587\u66F4\u6E05\u695A */
+.mcdev-log-line { display: inline; }
+.mcdev-log-line [data-kind="time"],
+.mcdev-log-line [data-kind="thread"],
+.mcdev-log-line [data-kind="logger"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="muted"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="level-warn"] { color: var(--dsw-alias-state-warn-primary); }
+.mcdev-log-line [data-kind="level-error"] { color: var(--dsw-alias-state-error-primary); }
+.mcdev-log-line [data-kind="level-debug"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="task"] { color: var(--dsw-alias-label-secondary); }
+.mcdev-log-line [data-kind="ok"] { color: var(--dsw-alias-state-success-primary); }
+.mcdev-log-line [data-kind="fail"] { color: var(--dsw-alias-state-error-primary); font: var(--dsw-font-xxxs-strong-11); }
+.mcdev-log-line [data-kind="stack"] { color: var(--dsw-alias-label-secondary); }
+
 .mcdev-section { margin-top: 12px; }
 .mcdev-section > h4 {
   margin: 0 0 4px;
@@ -1422,7 +1534,7 @@ function registerBetterSidebarTabs(ctx) {
     try {
       disposers.push(
         sidebar.registerTab({
-          id: "minecraft-dev-starter:project",
+          id: BETTER_DETAIL_ID,
           title: PANEL_TITLE,
           icon: (size) => h(IconCube, { size }),
           component: () => h(DetailTab)
@@ -1430,7 +1542,7 @@ function registerBetterSidebarTabs(ctx) {
       );
       disposers.push(
         sidebar.registerTab({
-          id: "minecraft-dev-starter:logs",
+          id: BETTER_LOG_ID,
           title: "\u8FD0\u884C\u65E5\u5FD7",
           icon: (size) => h(IconTerminal, { size }),
           component: () => h(LogTab)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minecraft-dev-starter",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "private": false,
   "description": "DSH plugin that detects Minecraft mod projects and launches the client from the session header, with live logs in the sidebar",
   "type": "module",

package/src/client/DetailTab.js

@@ -17,6 +17,7 @@ import {
   selectedProject,
   startTarget,
   stopLaunch,
+  store,
   useLaunches,
   useStoreState,
 } from './state.js'
@@ -122,7 +123,7 @@ export function DetailTab() {
               ),
               h(
                 'button',
-                { type: 'button', className: 'mcdev-run', onClick: () => openLogTab() },
+                { type: 'button', className: 'mcdev-run', onClick: () => openLogTab(store.get().config) },
                 '打开日志',
               ),
             ),

package/src/client/LogTab.js

@@ -9,6 +9,7 @@ import { useEffect, useRef, useState } from 'react'
 import { call } from './api.js'
 import { h } from './h.js'
 import { IconRefresh, IconWarning } from './icons.js'
+import { highlightLine } from './logFormat.js'
 import { launchStatusText, pickLogTarget } from './selection.js'
 import { Skeleton } from './Skeleton.js'
 import { loadLaunches, selectedProject, useLaunches } from './state.js'
@@ -140,7 +141,22 @@ export function LogTab() {
     log?.error === undefined
       ? log === undefined && running
         ? h(Skeleton, { rows: 4, hint: '正在读取日志…' })
-        : h('pre', { ref: body, className: 'mcdev-logs mcdev-logs-full' }, (log?.lines ?? []).join('\n') || '（还没有输出）')
+        : h(
+            'pre',
+            { ref: body, className: 'mcdev-logs mcdev-logs-full' },
+            (log?.lines ?? []).length === 0
+              ? '（还没有输出）'
+              : (log?.lines ?? []).map((line, index) =>
+                  h(
+                    'span',
+                    { key: index, className: 'mcdev-log-line' },
+                    highlightLine(line).map((part, partIndex) =>
+                      h('span', { key: partIndex, 'data-kind': part.kind }, part.text),
+                    ),
+                    '\n',
+                  ),
+                ),
+          )
       : h('div', { className: 'mcdev-error', style: { marginTop: 8 } }, log.error),
     h(
       'div',

package/src/client/dock.js

@@ -0,0 +1,20 @@
+/**
+ * 日志标签的落点选择。
+ *
+ * 右列属于 DSH 原生右侧栏；底部工作台是 dsh-better-sidebar 提供的。
+ * 未安装 better-sidebar 时只能落在右侧栏，配置值在这种情况下被忽略。
+ * @module minecraft-dev-starter/client/dock
+ */
+
+export const LOG_DOCK_RIGHT = 'right'
+export const LOG_DOCK_BOTTOM = 'bottom'
+
+/**
+ * @param {{ logDock?: string } | undefined} config
+ * @param {boolean} hasBetterSidebar
+ * @returns {'right' | 'bottom'}
+ */
+export function chooseLogDock(config, hasBetterSidebar) {
+  if (hasBetterSidebar !== true) return LOG_DOCK_RIGHT
+  return config?.logDock === LOG_DOCK_BOTTOM ? LOG_DOCK_BOTTOM : LOG_DOCK_RIGHT
+}

package/src/client/index.js

@@ -17,7 +17,7 @@ import { LogTab } from './LogTab.js'
 import { report } from './debug.js'
 import { h } from './h.js'
 import { IconCube, IconTerminal } from './icons.js'
-import { DETAIL_KIND, LOG_KIND, runtime } from './runtime.js'
+import { BETTER_DETAIL_ID, BETTER_LOG_ID, DETAIL_KIND, LOG_KIND, runtime } from './runtime.js'
 import { ensureStyles } from './styles.js'
 
 export const name = 'mcdev-client'
@@ -99,7 +99,7 @@ function registerBetterSidebarTabs(ctx) {
     try {
       disposers.push(
         sidebar.registerTab({
-          id: 'minecraft-dev-starter:project',
+          id: BETTER_DETAIL_ID,
           title: PANEL_TITLE,
           icon: (size) => h(IconCube, { size }),
           component: () => h(DetailTab),
@@ -107,7 +107,7 @@ function registerBetterSidebarTabs(ctx) {
       )
       disposers.push(
         sidebar.registerTab({
-          id: 'minecraft-dev-starter:logs',
+          id: BETTER_LOG_ID,
           title: '运行日志',
           icon: (size) => h(IconTerminal, { size }),
           component: () => h(LogTab),

package/src/client/logFormat.js

@@ -0,0 +1,109 @@
+/**
+ * 运行日志的逐行解析：把一行拆成若干片段，交给 CSS 按语义上色。
+ *
+ * 为什么不按 ANSI 上色：Gradle 在管道里默认关闭颜色，Minecraft 的 log4j 也只在
+ * 终端里输出色码。多数日志查看器（mclo.gs / Aternos codex）同样是先解析出 level
+ * 再染色，而不是解析转义序列。这里沿用同一思路，顺便把万一出现的 ANSI 码剥掉。
+ *
+ * 支持的三种真实格式：
+ *   [01:28:45] [Render thread/WARN] [minecraft/SoundEngine]: message   ← log4j
+ *   [01:28:45 INFO]: message                                          ← Paper
+ *   WARN StatusConsoleListener ...                                     ← 无时间戳的 log4j 状态行
+ * 另外识别 Gradle 的 `> Task`、`BUILD SUCCESSFUL`、`FAILURE:` 与堆栈帧。
+ *
+ * @module minecraft-dev-starter/client/logFormat
+ */
+
+const ANSI = /\u001b\[[0-9;]*[A-Za-z]/g
+
+/** @typedef {'time'|'thread'|'level-info'|'level-warn'|'level-error'|'level-debug'|'logger'|'message'|'task'|'ok'|'fail'|'stack'|'muted'} SegmentKind */
+
+/**
+ * @param {string} text
+ * @param {SegmentKind} kind
+ * @returns {{ text: string, kind: SegmentKind }}
+ */
+function seg(text, kind) {
+  return { text, kind }
+}
+
+/**
+ * 把 WARN / ERROR / FATAL 等归一成三档。
+ * @param {string} level
+ * @returns {SegmentKind}
+ */
+function levelKind(level) {
+  const upper = level.toUpperCase()
+  if (upper === 'WARN' || upper === 'WARNING') return 'level-warn'
+  if (upper === 'ERROR' || upper === 'FATAL' || upper === 'SEVERE') return 'level-error'
+  if (upper === 'DEBUG' || upper === 'TRACE' || upper === 'FINE' || upper === 'FINER') return 'level-debug'
+  return 'level-info'
+}
+
+const LOG4J = /^\[(\d{2}:\d{2}:\d{2})\]\s+\[([^\]]+?)\/([A-Z]+)\]\s*(?:\[([^\]]*)\]:\s*|:\s*)?(.*)$/
+const PAPER = /^\[(\d{2}:\d{2}:\d{2}) ([A-Z]+)\]:\s*(.*)$/
+const BARE_LEVEL = /^(TRACE|DEBUG|INFO|WARN|WARNING|ERROR|FATAL)\s+(.*)$/
+const STACK = /^\s+(at |\.\.\. \d+ more)/
+
+/**
+ * 一行日志 → 片段数组。永远至少返回一个片段。
+ * @param {string} raw
+ * @returns {Array<{ text: string, kind: SegmentKind }>}
+ */
+export function highlightLine(raw) {
+  const line = String(raw ?? '').replace(ANSI, '')
+  if (line === '') return [seg('', 'plain')]
+
+  if (/^Caused by:|^\s+Suppressed:/.test(line)) return [seg(line, 'fail')]
+  if (STACK.test(line)) return [seg(line, 'stack')]
+
+  const log4j = LOG4J.exec(line)
+  if (log4j !== null) {
+    const [, time, thread, level, logger, message] = log4j
+    const kind = levelKind(level)
+    /** @type {Array<{ text: string, kind: SegmentKind }>} */
+    const parts = [
+      seg(`[${time}] `, 'time'),
+      seg(`[${thread}/`, 'thread'),
+      seg(level, kind),
+      seg(logger === undefined ? ']: ' : '] ', 'thread'),
+    ]
+    if (logger !== undefined) parts.push(seg(`[${logger}]: `, 'logger'))
+    parts.push(seg(message, kind === 'level-error' ? 'level-error' : 'message'))
+    return parts
+  }
+
+  const paper = PAPER.exec(line)
+  if (paper !== null) {
+    const [, time, level, message] = paper
+    return [
+      seg(`[${time} `, 'time'),
+      seg(level, levelKind(level)),
+      seg(']: ', 'time'),
+      seg(message, levelKind(level) === 'level-error' ? 'level-error' : 'message'),
+    ]
+  }
+
+  const bare = BARE_LEVEL.exec(line)
+  if (bare !== null) {
+    const [, level, message] = bare
+    return [seg(`${level} `, levelKind(level)), seg(message, levelKind(level) === 'level-error' ? 'level-error' : 'message')]
+  }
+
+  if (/^> Task /.test(line) || /^> Configure project /.test(line)) return [seg(line, 'task')]
+  if (/^BUILD SUCCESSFUL/.test(line)) return [seg(line, 'ok')]
+  if (/^BUILD FAILED/.test(line) || /^FAILURE:/.test(line)) return [seg(line, 'fail')]
+  if (/^\* What went wrong:|^\* Where:|^\* Try:/.test(line)) return [seg(line, 'level-warn')]
+  if (/^(Reusing configuration cache|Deprecated Gradle features|You can use)/.test(line)) return [seg(line, 'muted')]
+
+  return [seg(line, 'plain')]
+}
+
+/**
+ * 批量解析，便于测试与 memo 化调用。
+ * @param {string[]} lines
+ * @returns {Array<Array<{ text: string, kind: SegmentKind }>>}
+ */
+export function highlightLines(lines) {
+  return (lines ?? []).map(highlightLine)
+}

package/src/client/runtime.js

@@ -6,12 +6,18 @@
  * @module minecraft-dev-starter/client/runtime
  */
 
-/** 右侧栏「MC 工程」详情标签的 kind。 */
+import { chooseLogDock, LOG_DOCK_BOTTOM } from './dock.js'
+
+/** 右侧栏「Mod Dev」详情标签的 kind。 */
 export const DETAIL_KIND = 'mcdev.detail'
 
 /** 右侧栏「运行日志」标签的 kind。 */
 export const LOG_KIND = 'mcdev.logs'
 
+/** 向 dsh-better-sidebar 注册时用的 tab id；打开底部工作台需要同一个 id。 */
+export const BETTER_DETAIL_ID = 'minecraft-dev-starter:project'
+export const BETTER_LOG_ID = 'minecraft-dev-starter:logs'
+
 /** @type {{ ctx?: any }} */
 export const runtime = {}
 
@@ -30,12 +36,39 @@ function open(kind) {
   }
 }
 
+/**
+ * 取可选的 better-sidebar 服务；未安装时返回 undefined（不抛错）。
+ * @returns {any}
+ */
+export function betterSidebar() {
+  try {
+    return runtime.ctx?.get?.('betterSidebar', false)
+  } catch {
+    return undefined
+  }
+}
+
 /** 打开工程详情标签（openTab 会顺带展开面板）。 */
 export function openDetailTab() {
   return open(DETAIL_KIND)
 }
 
-/** 打开运行日志标签。 */
-export function openLogTab() {
+/**
+ * 打开运行日志标签。
+ *
+ * 落点由配置 `logDock` 决定：`bottom` 且装了 better-sidebar 时落到底部工作台，
+ * 其余情况一律落原生右侧栏。配置由调用方传入，避免 runtime ←→ state 循环依赖。
+ * @param {{ logDock?: string } | undefined} [config]
+ */
+export function openLogTab(config) {
+  const service = betterSidebar()
+  if (chooseLogDock(config, service !== undefined) === LOG_DOCK_BOTTOM) {
+    try {
+      service.openTab({ type: BETTER_LOG_ID, title: '运行日志', target: 'bottom' })
+      return true
+    } catch {
+      /* 落底部失败就退回右侧栏，不吞掉日志入口 */
+    }
+  }
   return open(LOG_KIND)
 }

package/src/client/state.js

@@ -25,8 +25,8 @@ export const store = createStore({
   flyoutOpen: false,
   /** @type {Record<string, string>} 每个工程记住的目标 key */
   selection: readSelection(),
-  /** @type {{ autoOpenLogTab?: boolean }} 宿主下发的部署配置 */
-  config: { autoOpenLogTab: true },
+  /** @type {{ autoOpenLogTab?: boolean, logDock?: 'right' | 'bottom' }} 宿主下发的部署配置 */
+  config: { autoOpenLogTab: true, logDock: 'right' },
   /** @type {string | undefined} 当前会话的工作区（由胶囊从会话上下文注入） */
   workspaceRoot: undefined,
 })
@@ -37,7 +37,7 @@ export const store = createStore({
 export async function loadStateInfo() {
   try {
     const info = await call('state.info', {})
-    store.set({ config: { autoOpenLogTab: true, ...(info?.config ?? {}) } })
+    store.set({ config: { autoOpenLogTab: true, logDock: 'right', ...(info?.config ?? {}) } })
   } catch {
     /* 拉不到就用默认值 */
   }
@@ -172,7 +172,7 @@ export async function startTarget(project, target) {
       module: target.module,
     })
     // 启动成功就把日志摆到人眼前（部署配置可关）
-    if (store.get().config.autoOpenLogTab !== false) openLogTab()
+    if (store.get().config.autoOpenLogTab !== false) openLogTab(store.get().config)
   } catch (error) {
     launchStore.set({ error: error instanceof Error ? error.message : String(error) })
   } finally {

package/src/client/styles.js

@@ -257,6 +257,20 @@ export const CSS = `
 .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; }
 
+/* 日志高亮：只按语义上色，时间/线程/logger 一律压到 tertiary，让正文更清楚 */
+.mcdev-log-line { display: inline; }
+.mcdev-log-line [data-kind="time"],
+.mcdev-log-line [data-kind="thread"],
+.mcdev-log-line [data-kind="logger"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="muted"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="level-warn"] { color: var(--dsw-alias-state-warn-primary); }
+.mcdev-log-line [data-kind="level-error"] { color: var(--dsw-alias-state-error-primary); }
+.mcdev-log-line [data-kind="level-debug"] { color: var(--dsw-alias-label-tertiary); }
+.mcdev-log-line [data-kind="task"] { color: var(--dsw-alias-label-secondary); }
+.mcdev-log-line [data-kind="ok"] { color: var(--dsw-alias-state-success-primary); }
+.mcdev-log-line [data-kind="fail"] { color: var(--dsw-alias-state-error-primary); font: var(--dsw-font-xxxs-strong-11); }
+.mcdev-log-line [data-kind="stack"] { color: var(--dsw-alias-label-secondary); }
+
 .mcdev-section { margin-top: 12px; }
 .mcdev-section > h4 {
   margin: 0 0 4px;

package/src/index.js

@@ -117,6 +117,7 @@ function resolveWorkspaceRoot(ctx) {
 /** 部署配置默认值；patch 行的 `config` 会覆盖同名项。 */
 const DEFAULTS = {
   autoOpenLogTab: true,
+  logDock: 'right',
   readyTimeoutMs: 90_000,
   logRingLines: 2_000,
 }
@@ -131,7 +132,10 @@ export function apply(ctx, config = {}) {
     version: VERSION,
     resolveRoot: () => resolveWorkspaceRoot(ctx),
     resolveRoots: () => sessionCwds(ctx),
-    config: { autoOpenLogTab: settings.autoOpenLogTab !== false },
+    config: {
+      autoOpenLogTab: settings.autoOpenLogTab !== false,
+      logDock: settings.logDock === 'bottom' ? 'bottom' : 'right',
+    },
     launchService: createLaunchService({
       readyTimeoutMs: Number(settings.readyTimeoutMs) || DEFAULTS.readyTimeoutMs,
       maxLogLines: Number(settings.logRingLines) || DEFAULTS.logRingLines,