minecraft-dev-starter 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,166 @@
+# AGENTS.md
+
+给在这个仓库里干活的 agent（和以后的自己）看的。用户向的说明在 [README](./README.md)。
+
+## 这是什么
+
+DeepSeek Harness（DSH）插件：识别工作区里的 Minecraft 模组工程，并在会话标题栏提供一个
+IDEA 风格的运行控件（选中目标 → 启动 / 停止 / 看日志）。
+
+- 宿主侧：ESM、无 TypeScript、JSDoc 注解；Node ≥ 20。
+- 客户端侧：React 组件用 `h()` 手写（不用 JSX），由 esbuild 打成 CJS，再包一层
+  `window.__ModuleLoader__.load({ id, factory })`。
+- 设计文档：[策划](./doc/策划.md)（架构、规则、里程碑）、[DSH 插件机制调研](./doc/调研-DSH插件机制.md)。
+
+## 目录
+
+```
+src/index.js          宿主入口：inject + apply，挂 HTTP 路由与工具
+src/tools.js          四个模型工具（mc_projects / mc_launch / mc_launch_logs / mc_launch_stop）
+src/lib/
+  api.js              /mcdev/api 的方法实现（scan / detail / state / launch.*）
+  detect.js           工程画像：loader、模块、run 目标、证据与警告
+  scanner.js          工作区 BFS（深度 3、剪枝、上限）
+  gradle.js           build.gradle / settings.gradle / gradle.properties 的解析
+  metadata.js         mods.toml / fabric.mod.json / plugin.yml / archive.yml
+  java.js             JDK 探测与版本匹配（读 <jdk>/release，不起进程）
+  launches.js         启动服务：spawn、就绪判定、日志环形缓冲、停止、状态对账
+  state.js            ~/.dsh/mc-dev-starter 下的状态与日志文件
+  argv.js             gradlew 命令行构造（含 Windows 引号规则）
+  text.js / toml.js   小工具
+src/client/
+  index.js            客户端入口：胶囊 slot、两个标签类型、better-sidebar 可选注册
+  Capsule.js          标题栏胶囊（状态点 + 目标名 + 启停）
+  Flyout.js           浮层（单工程特化 / 多工程三段结构）
+  DetailTab.js        工程面板（版本、环境、模块、证据、警告）
+  LogTab.js           日志标签（历史、跟随、归因）
+  state.js / selection.js / format.js / icons.js / styles.js / runtime.js
+lib/client.js         构建产物（提交进仓库，运行时直接加载）
+test/                 59 个测试 + fixtures（真实工程形态的假仓库）
+doc/                  策划与调研
+```
+
+## 命令
+
+```powershell
+node --test "test/*.test.js"      # 全部测试
+node scripts/build-client.mjs     # 构建客户端（改 src/client 后必须跑）
+node scripts/build-client.mjs --watch
+node scripts/scan-catalog.mjs     # 扫真实工程，输出识别结果表
+```
+
+改完客户端**必须**重新构建 `lib/client.js` 并跑测试；样式改动还要过 `test/styles.test.js`
+（颜色/字号必须引用 `--dsw-*` 令牌，不许写字面色值）。
+
+## 开发期安装
+
+```powershell
+node <npm>/@deepseek-ai/dsh/lib/bin.js plugin --profile m0test add link:C:/Projects/minecraft-dev-starter
+node <npm>/@deepseek-ai/dsh/lib/bin.js --profile m0test --port 3499 --no-open
+```
+
+`link:` 才能改完即生效；`file:` 会被 pnpm 拷贝成副本，编辑仓库不影响已装副本。
+
+## 硬坑（都踩过，别再踩）
+
+| 现象 | 原因 | 做法 |
+|---|---|---|
+| 客户端整包不加载 | 没有 `__ModuleLoader__.load` 包装、或 factory 里用了 ESM | esbuild 打 CJS，banner/footer 由 `scripts/build-client.mjs` 生成 |
+| `ctx.get('x')` 拿到 undefined | cordis 要求服务先声明在 `inject` | 需要什么写进 `inject`；可选服务用 `ctx.inject([...], cb)` 或 `ctx.get(name, false)` |
+| 注册 slot 报 "not declared" | 父条目还没声明该 slot | 用 `ctx.slots.inject(name, …)`，或注册失败后重试 |
+| 启动后日志 0 字节 | Windows 上 `detached: true` 让子进程丢掉我们的管道（`DETACHED_PROCESS` 与 `CREATE_NO_WINDOW` 冲突） | Windows 关闭 detached，保留 `windowsHide`；POSIX 才 detached（要进程组） |
+| 启动时多一个控制台窗口 | 同上：没有可继承的隐藏控制台，java 自己开一个 | 同上，关闭 detached 后消失 |
+| 中文日志乱码 | `.bat` 输出按 GBK 编码 | `decodeLine`：先按 UTF-8 解，失败再按 GBK |
+| 工具报 "value is not lossless JSON" | 返回值里带了 `undefined` | 只放存在的字段；测试里用 `assertLossless()` |
+| 改 profile 后启动失败 | `package.json` 写入了 BOM | 用无 BOM 的 UTF-8 写；改完必须重启 DSH |
+| 侧栏标签打不开 | `openTab` 的展开是异步的 | 打开后等一帧再断言 `isExpanded()` |
+
+其他约定：
+
+- 用户能看到的每个结论都必须带证据（loader 从哪个插件来、目标从哪个 run 块来）；
+  `unknown` 是合法答案，不许猜成确定值。
+- 推测出来的目标要标 `guessed: true`，UI 显示「未验证」，不许隐藏。
+- 不做隐含的 `clean`；构建目录不碰。
+- 一个工程同时只允许一个实例；跨工程可以并行。
+- 状态文件读写要 tmp + rename，进程探活失败记 `unknown`，不伪造结束原因。
+
+## 验证记录
+
+历史里程碑的验证结论。原始长文已并入这里，`doc/` 只保留设计与调研。
+
+### M0 加载协议与槽位（2026-10-30，通过）
+
+客户端包能在真实运行时里加载、激活、注册标题栏 slot 与右侧栏标签，并能驱动 `openTab` 展开侧栏。
+产出四个后续一直沿用的结论：bundle 必须 `__ModuleLoader__.load` 包装；CSS 以 `<style>` 注入；
+服务要先声明 `inject`；`openTab` 展开是异步的。
+
+### M1 识别引擎（2026-10-31，通过）
+
+22 个真实工程跑通，识别 loader / Minecraft 版本 / 模块 / run 目标；esbuild 构建链与面板接通。
+两处修正：`net.neoforged.moddev.legacyforge` 产出的是 **Forge** 1.20.1 模组（曾误判成 NeoForge）；
+聚合仓库的 loader 只写在子模块里，因此加了模块级插件回退与 `loaders[]`；推测目标按"每个具体平台一个
+Client"收敛，避免一个工程刷出十几个目标。
+
+### M2 托管启动（2026-10-31，通过）
+
+识别出的目标可以真的启动、进入运行态、读日志、停止，且不留孤儿进程。关键决策：宿主不托管子进程句柄，
+用 `taskkill /PID <pid> /T /F` 杀整棵树；就绪用日志标记（client：LWJGL/OpenAL/`[Render thread/INFO]`；
+server：`Done (…s)!`）；状态落盘并做重启后对账。顺带修了 GBK 解码。
+
+### M3 胶囊与浮层（2026-10-31，通过）
+
+标题栏胶囊成为唯一入口：目标名、状态点、启停；浮层收敛成单选并记住每个工程的选择；
+每个工程互斥、跨工程可并行；旧的 `DEV_AUTO_OPEN` 开关下线。
+
+### M4 日志标签（2026-10-31，通过）
+
+日志成为独立标签：按工程列历史、默认最新、可跟随、崩溃时给归因；启动后自动打开，可用
+`autoOpenLogTab` 关掉。确认插件**不需要**导出 schemastery 的 `Config`——patch 行的 `config`
+会原样传给 `apply(ctx, config)`。
+
+### M5 AI 工具（2026-10-31，通过）
+
+四个工具与面板共用同一套服务：`mc_projects` / `mc_launch` / `mc_launch_logs` / `mc_launch_stop`。
+依赖 `@deepseek-ai/dsh-tools@0.2.1-rc.3`（与桌面运行时对齐）。
+
+### M7 UI 打磨（2026-10-31，完成）
+
+手绘 16px 图标（避免顶层 require 第三方包）、骨架空态、动效并尊重 `prefers-reduced-motion`、
+文案去内部术语（"推测"→"未验证"）。样式护栏测试从此时开始。
+
+### M8 真机验证（desktop profile，2026-10-31）
+
+挂载方式：`dependencies` 加 `link:` + `dsh.profile.bundles` 追加，桌面自带 pnpm 安装。
+首次挂载后启动 EnchatingPaper Client 成功，关闭后状态同步，四个工具在真实运行时注册成功。
+
+三个问题：
+
+1. **日志 0 字节**：`detached: true` 在 Windows 上丢管道（同一命令 detached 0 字节 / attached 564 字节）。
+2. **多一个控制台窗口**：同源，关闭 detached 后消失（已由用户确认）。
+3. **`mc_projects` 报 0 个目标**：渲染读 `runTargets`，而输出值里字段叫 `targets`。
+
+第二轮：
+
+4. **日志标签不跟新实例**：旧逻辑只在没选过时挑一次 → `pickLogTarget()`（有实例在跑就跟它）。
+5. **工具输出 "not lossless JSON"**：返回值含 `undefined` 字段，注册器整条拒绝。
+
+第三轮：**切会话不同步**——宿主用"最近创建的会话"当工作区，且胶囊只在挂载时扫一次。
+改为胶囊按 `sessionId` 订阅 `useSessions` 的 cwd，cwd 变化时清空旧结果重扫；启动校验放宽为
+"落在任一活跃会话 cwd 之内"；工具改用调用方会话的 cwd。
+
+最终 59 个测试。
+
+### M9 生态集成与单工程特化（2026-10-31）
+
+- 向 `dsh-better-sidebar` 注册两个带图标页面（`ctx.betterSidebar.registerTab`，`icon` 支持
+  `(size) => ReactNode`）。用 `ctx.inject(['betterSidebar'], …)` 做可选依赖，未安装则静默跳过。
+- 原生右侧栏标签**没有 icon 字段**，只能文字；图标只出现在 better-sidebar。
+- 面板改名「MC 工程」→「Mod Dev」（功能名，不是名词描述），浮层表头/标签/详情页统一。
+- 单工程工作区跳过工程列表：表头直接承担工程身份（名字 + loader/版本 + 路径）。
+
+## 还没做的事
+
+- **M6 通用启动器**：HMCL 实例库 + 直启 java，让面板也能起非 Gradle 工程（估 5–8 天）。
+- **发布**：目前只在本地 `link:` 安装。发布流程见 README 的「发布」一节。
+- 跨 profile 共用 `~/.dsh/mc-dev-starter/state.json`：不同 profile 的实例记录会混在一起，
+  日志标签已按工程过滤，暂不影响使用，但值得按 profile 分目录。

package/README.md

@@ -1,3 +1,125 @@
-# Temporary Holding Version
+# minecraft-dev-starter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+在 DSH（DeepSeek Harness）的会话标题栏放一个 IDEA 风格的运行控件：认出工作区里的 Minecraft 模组工程，点一下就能起 Client，日志就在右侧栏。
+
+给做模组的人用，不是给 AI 用的——AI 侧只是顺带留了几个工具。
+
+## 能做什么
+
+**识别**：Fabric、Forge、NeoForge、Architectury、Paper、Spigot，覆盖 1.7.10 到 26.x。
+单模块、多模块、聚合仓库都能认；loader 写在子模块里也能认。
+
+**启动**：Client / Server / Data / GameTestServer。自动挑 JDK（读 `<jdk>/release`，不乱起进程）；
+构建完能判断"进游戏了"而不是"进程还活着"；关掉游戏后状态同步；宿主重启后按 pid 对账，不伪造结束原因。
+
+**看日志**：右侧栏独立标签，按工程列历史、默认显示最新、可跟随尾部；
+崩溃时给一句归因（依赖没解析、JDK 版本不对、端口被占、认证失败等 8 类）。
+
+**多工程与多会话**：工作区里每个工程分别记住自己选的目标；切换对话即切换工作区，不需要手动刷新。
+
+**AI 工具**（可选）：`mc_projects` / `mc_launch` / `mc_launch_logs` / `mc_launch_stop`，与面板共用同一套服务。
+
+**better-sidebar**：装了 [dsh-better-sidebar](https://github.com/topics/dsh-better-sidebar)，还会多出两个带图标的侧栏页面。
+
+## 安装
+
+需要 DSH 桌面版（0.2.1 及以上）或 dsh CLI。
+
+```powershell
+# 本地仓库（改完即生效）
+dsh plugin --profile desktop add link:C:/Projects/minecraft-dev-starter
+
+# 打好的 tarball
+dsh plugin --profile desktop add file:./minecraft-dev-starter-0.1.0.tgz
+
+# 从 npm 安装（发布之后）
+dsh plugin --profile desktop add minecraft-dev-starter
+```
+
+装完**重启 DSH** 生效。卸载：
+
+```powershell
+dsh plugin --profile desktop remove minecraft-dev-starter
+```
+
+`dsh plugin` 实际是 pnpm 的转发器：它把包装进 profile、再把声明了 `dsh.bundle` 的依赖加进
+`dsh.profile.bundles` 层列表。所以手工在 profile 的 `package.json` 里加一行再用 pnpm 安装，
+效果是一样的。
+
+## 使用
+
+1. 打开一个模组工程所在的对话。
+2. 标题栏出现 `● Client ▶`。点名字展开浮层，选工程与目标；点 ▶ 开始构建并启动。
+3. 启动后自动打开「运行日志」（可在配置里关掉），日志实时刷新。
+4. 再点一次按钮（变成 ⏹）停止，会连同 Gradle 拉起的整个进程树一起结束。
+
+浮层形态会自适应：工作区里只有一个工程时跳过列表，表头直接是工程名、loader/版本与路径；
+有多个工程时列表固定高度，选谁只换下面的目标区，界面不会跳。
+
+## 配置
+
+在 profile 的 `cordis.patch.yml` 里给插件那行加 `config`：
+
+```yaml
+- id: mcdev-host
+  name: minecraft-dev-starter
+  config:
+    autoOpenLogTab: true   # 启动后自动打开日志标签
+    readyTimeoutMs: 90000  # 等"进游戏"的上限，超时不算失败
+    logRingLines: 2000     # 内存里保留的日志行数（磁盘文件是完整的）
+```
+
+## 支持范围
+
+| 平台 | 版本线 | 说明 |
+|---|---|---|
+| 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 | 按子模块拆目标 |
+| 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 比对，缺了会在面板里提示，不会带着错的版本硬跑。
+
+## 开发
+
+```powershell
+npm install
+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)。
+
+## 发布
+
+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，破坏性改动升主版本。
+5. **兼容性**：宿主 API 会演进（本插件按 0.2.1-rc.3 的 `dsh-tools` 开发）。发布前把
+   `dependencies` 里的 `@deepseek-ai/dsh-tools` 与 `peerDependencies` 的 cordis 范围对齐
+   目标运行时；跨大版本时最好发两个版本而不是硬兼容。
+6. **安装**：用户 `dsh plugin --profile <name> add <包名>` 后重启；也可以在 Plugins 面板里装。
+
+本地想先验证发布形态，可以 `npm pack` 后用 `dsh plugin add file:<tarball>` 装一遍——
+它会走和 npm 安装完全相同的 pnpm 路径。
+
+## 已知限制
+
+- 原生右侧栏的标签类型没有图标位，只有 better-sidebar 的标签能带图标。
+- 只支持 Gradle 工程；HMCL 实例库里的整合包还不能直接起（见 AGENTS.md 的 M6）。
+- 状态文件放在 `~/.dsh/mc-dev-starter/`，多个 profile 共用一份；日志标签按工程过滤，不影响使用。
+- Windows 上第一次构建会下载 Gradle 与依赖，可能要几分钟；之后有 daemon 会快很多。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# minecraft-dev-starter bundle patch
+#
+# 一行宿主插件；客户端半边由 dsh-client-modules 按 package.json 的
+# `dsh.client` 声明自动扫描并挂载，不需要单独的行。
+- insert:
+    - id: mcdev-host
+      name: 'minecraft-dev-starter'