chore(dev): Add dev runner and split dev ports

Add dev:web (rsbuild) and dev:cli (tttk serve ./content), with dev
running both via scripts/dev.mjs, which shuts both down when either
exits. Also add tttk:inspect for --inspect debugging.

Both servers previously defaulted to port 3000, so the CLI could not
bind while the web dev server was running and the proxy targeted
itself. Pin the web dev server to 5173; the CLI keeps 3000 to match
the proxy. Document the two-process setup and inspector debugging in
docs/development.md.

docs/development.md

@@ -6,9 +6,13 @@
 # 安装依赖
 npm install
 
-# 开发模式（Web）
+# 开发模式（同时启动 CLI 内容服务器 :3000 与 Web 前端 :5173）
 npm run dev
 
+# 也可分别启动
+npm run dev:cli
+npm run dev:web
+
 # 构建（Web）
 npm run build
 
@@ -244,19 +248,46 @@ npm test -- --watch
 
 ## 调试
 
+开发环境由两个进程组成，必须使用不同端口：
+
+- Web 前端：rsbuild 开发服务器，端口 **5173**
+- CLI 内容服务器：`tttk serve`，端口 **3000**（内容 API + Journal）
+
+rsbuild 会把 `/__CONTENT_INDEX.json`、`/__COMPLETIONS.json`、`/content`、`/.ttrpg` 代理到 CLI 的
+3000 端口，因此必须先启动 CLI，否则前端拿不到内容。
+
 ### Web 开发
 
+`npm run dev` 会同时启动两个进程；也可以分开运行：
+
 ```bash
+# 同时启动 CLI（3000）与 Web（5173）
 npm run dev
-# 访问 http://localhost:3000
+
+# 或分别启动
+npm run dev:cli   # CLI 内容服务器，占用 3000
+npm run dev:web   # Web 前端，占用 5173
+# 访问 http://localhost:5173
 ```
 
 ### CLI 调试
 
-```bash
-# 使用 ts-node 直接运行
-npm run ttrpg serve ./content
+CLI 通过 ts-node 运行，加上 `--inspect` 与 `--enable-source-maps` 后即可在编辑器中附加断点。
+如需调试启动/扫描逻辑，用 `--inspect-brk` 在用户代码执行前暂停：
 
+```bash
+node --inspect-brk --enable-source-maps --loader ts-node/esm ./src/cli/index.ts serve ./content
+
+# 或使用脚本（不带 --inspect-brk）
+npm run tttk:inspect -- serve ./content
+```
+
+然后在 Zed / VS Code 中附加到 `localhost:9229`，或打开 `chrome://inspect`。
+
+CLI 只监听内容目录（`.md`/`.csv`/`.yarn`/`.svg`）并重建内存中的注册表，**不会**热重载自身源码；
+修改 `src/cli/**` 后需要重启进程。
+
+```bash
 # 或构建后运行
 npm run cli:build
 node dist/cli/index.js serve ./content

package.json

@@ -19,7 +19,9 @@
     "node": ">=18"
   },
   "scripts": {
-    "dev": "rsbuild dev",
+    "dev": "node scripts/dev.mjs",
+    "dev:web": "rsbuild dev",
+    "dev:cli": "node --enable-source-maps --loader ts-node/esm ./src/cli/index.ts serve ./content",
     "build": "npm run build:web && npm run build:cli",
     "build:web": "rsbuild build",
     "build:cli": "tsc -p tsconfig.cli.json",
@@ -29,6 +31,7 @@
     "cli:build": "npm run build:cli",
     "ttrpg": "node --loader ts-node/esm ./src/cli/index.ts",
     "tttk": "node --loader ts-node/esm ./src/cli/index.ts",
+    "tttk:inspect": "node --inspect --enable-source-maps --loader ts-node/esm ./src/cli/index.ts",
     "gen:reference": "node --loader ts-node/esm ./scripts/generate-reference.ts",
     "gen:skill-reference": "node --loader ts-node/esm ./scripts/generate-reference.ts --out .agents/skills/tttk-authoring/reference.md",
     "test": "jest",

rsbuild.config.ts

@@ -48,6 +48,9 @@ export default defineConfig({
     },
   },
   server: {
+    // Dev web server runs on its own port; the CLI content server keeps
+    // port 3000 (see the proxy targets below).
+    port: 5173,
     proxy: {
       // Proxy content API requests to the CLI dev server (npm run tttk)
       "/__CONTENT_INDEX.json": "http://localhost:3000",

scripts/dev.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/**
+ * Dev runner: starts the CLI content server (port 3000) and the rsbuild web
+ * dev server (port 5173) together, then tears both down when either exits.
+ *
+ *   npm run dev       # both (this script)
+ *   npm run dev:cli   # CLI content server only
+ *   npm run dev:web   # web dev server only
+ */
+import { spawn } from "node:child_process";
+
+const isWindows = process.platform === "win32";
+const children = new Set();
+let shuttingDown = false;
+
+/** Terminate a child and everything it spawned. */
+function killTree(child) {
+  if (child.exitCode !== null || child.signalCode !== null) return;
+  if (isWindows) {
+    spawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+      stdio: "ignore",
+    });
+  } else {
+    try {
+      // Negative pid targets the process group created via `detached`.
+      process.kill(-child.pid, "SIGTERM");
+    } catch {
+      child.kill("SIGTERM");
+    }
+  }
+}
+
+function shutdown(code) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  for (const child of children) killTree(child);
+  process.exitCode = code ?? 0;
+}
+
+for (const script of ["dev:cli", "dev:web"]) {
+  const child = spawn("npm", ["run", script], {
+    stdio: "inherit",
+    shell: true,
+    detached: !isWindows,
+  });
+  children.add(child);
+  child.on("exit", (code) => shutdown(code ?? 0));
+  child.on("error", (error) => {
+    console.error(`[dev] Failed to start ${script}: ${error.message}`);
+    shutdown(1);
+  });
+}
+
+process.on("SIGINT", () => shutdown(0));
+process.on("SIGTERM", () => shutdown(0));