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.
This commit is contained in:
hyper
2026-09-12 20:11:34 +08:00
parent 53620e0a92
commit 2ed69d744a
4 changed files with 98 additions and 6 deletions
+36 -5
View File
@@ -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