oh-my-dws 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,193 @@
-# Temporary Holding Version
+# oh-my-dws
 
-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.
+把钉钉项目群的消息**归档到本地**，并用一个本地网页控制台浏览、搜索、增量拉取、导出 Markdown。
+按「一群一目录」组织，数据全部落在 `~/.oh-my-dws`，代码与聊天数据完全分开。
+
+- 运行时：**Node.js ≥ 18**（零第三方依赖，只用标准库）
+- 数据源：本机 `dws`（钉钉 CLI，需已登录 `dws auth login`）
+- 网络：只监听 `127.0.0.1`，不上传任何数据
+
+## 安装
+
+```bash
+# 直接用（不安装）
+npx oh-my-dws start
+
+# 或全局安装
+npm i -g oh-my-dws
+oh-my-dws start                  # 后台起服务并打开浏览器（默认 25258）
+
+# 或从源码跑
+git clone https://github.com/duzhenxun/oh-my-dws.git
+cd oh-my-dws && node bin/oh-my-dws.js start
+```
+
+macOS 也可以双击仓库里的 `启动.command`。
+
+## 用法
+
+```bash
+oh-my-dws start                     # 后台启动（默认 http://127.0.0.1:25258）
+oh-my-dws status                    # 看 PID / 端口 / URL / 版本
+oh-my-dws restart                   # 重启
+oh-my-dws stop                      # 停止
+oh-my-dws update                    # 升到 npm 最新版（在跑会自动重启）
+
+oh-my-dws                           # 前台启动，Ctrl+C 结束（老用法）
+oh-my-dws 26000                     # 前台 + 指定端口（位置参数兼容写法）
+oh-my-dws start --port 26000 --no-open
+oh-my-dws start --data /Volumes/ext/dws    # 数据目录换到移动盘
+oh-my-dws --help
+```
+
+| 命令 / 选项 | 说明 |
+|---|---|
+| `start` | 后台启动，日志落 `~/.oh-my-dws/_运行/server.log`，PID 写 `server.json` |
+| `stop` / `restart` | 停止 / 重启后台服务（先 SIGTERM，超时再 SIGKILL） |
+| `status` | 运行状态（同时探 `/api/health`）；退出码 `0` 在跑 / `3` 未跑 / `4` 进程在但无响应 |
+| `update` | `npm i -g oh-my-dws@latest`，正在运行则自动重启 |
+| `-p, --port <端口>` | 监听端口，默认 `25258` |
+| `--data <目录>` | 聊天数据目录，默认 `~/.oh-my-dws` |
+| `--no-open` | 不自动打开浏览器 |
+| `-v, --version` / `-h, --help` | 版本 / 帮助 |
+
+环境变量：`OH_MY_DWS_HOME`（等价 `--data`）、`NO_OPEN=1`（等价 `--no-open`）。
+
+完整使用说明见 [docs/使用说明.md](docs/使用说明.md)。
+
+## 目录结构
+
+```
+oh-my-dws/                    # 代码（npm 包）
+├── bin/oh-my-dws.js          # CLI 入口
+├── src/
+│   ├── server.js             # HTTP 服务与路由
+│   ├── actions.js            # 拉取/纳管/发送/删除/打开钉钉
+│   ├── archive.js            # 归档读写与 Markdown/索引生成
+│   ├── media.js              # 图片/文件下载与缓存
+│   ├── auth.js               # dws 登录态与登录
+│   ├── dws.js                # dws 调用封装
+│   ├── paths.js / util.js    # 路径与时间/文件工具
+├── web/index.html            # 网页界面（单文件，无外部依赖）
+├── docs/使用说明.md           # 面向使用者的完整说明
+├── 启动.command              # macOS 双击启动
+└── README.md
+
+~/.oh-my-dws/                 # 数据（聊天相关文件全在这里，可整体备份/迁移）
+├── 群索引.md                 # 群名 → 群 ID / 成员数 / 文件位置（每次拉取后自动重建）
+├── server.json              # 后台服务的 PID/端口（`start` 写、`stop` 删）
+├── _运行/server.log          # 后台服务日志
+├── _原始数据/                # dws 原始 JSON（便于二次加工/复核）
+│   ├── <群简称>_消息.json
+│   ├── <群简称>_成员.json
+│   └── dws-login.log         # 网页点「登录 dws」时的后台日志
+├── _媒体/                    # 消息图片/文件缓存（可随时删，会重新拉）
+├── _回收站/                  # 删除归档时的暂存区（可手动恢复）
+└── <群简称>/
+    ├── 群信息与人员ID.md      # 群 ID、群主、成员表（openDingtalkId / memberDingtalkId）
+    └── 群消息-YYYYMMDD-YYYYMMDD.md   # 消息全文，带时间、发送者、messageId
+```
+
+首次启动会自动创建 `~/.oh-my-dws/_原始数据`。
+
+## 功能
+
+- 左侧会话列表（可搜索），分 **@我 聚合 / 单聊 / 群聊** 三组；右侧看某个会话的**全部消息**
+- **侧栏默认收起**：收起后是 32px 窄条（`»` 展开、显示当前会话首字头像）；展开后悬停侧栏会在右边缘出现 `«` 把手一点就收；**⌘/Ctrl + B** 随时切；**拖右边缘可调宽**（200–560px，双击回默认 310px），宽度和收起状态都记在 localStorage
+- 侧栏圆点：只有**真有新消息**时才亮绿点并显示 `+N 新`；无新消息是空心灰圈（`complete=false` 才变红）；打开该会话即自动清零已阅
+- **默认倒序**：最新一条在最上面，打开即见最新（工具栏可切「最早在前」）
+- 消息区渲染钉钉正文的 `**加粗**`、`` `代码` ``、链接、@人，按日期分段
+- 每条消息带**头像**（按人员 ID 稳定配色 + 姓名首字；钉钉接口不返回真实头像 URL）
+- **引用/回复消息显示成引用块**（灰底竖线），点击引用块直接跳到被引用的那条消息
+- **图片直接看图**：`[图片消息]` 通过 `dws chat +messages-resource-download` 下载到 `_媒体/<群简称>/` 并内联显示（懒加载，滚到才下载，已下载走缓存），点击在页面内弹窗预览大图；没网络/无权限时退化成「图片加载失败」
+- 顶部 **拉取最新消息**：从「最后一条消息时间 − 1 分钟」拉到当前，按 `messageId` 去重合并，回写 JSON + Markdown + 群索引；新消息高亮
+- **侧栏顶部账号胶囊**：头像（姓名首字 + 按账号稳定配色）+ 姓名 · 组织，绿点=已登录 / 橙点=未登录；胶囊右侧是 **＋ 新群**；点击胶囊弹出「dws 登录信息」面板，展示状态、组织、账号、profile、token/refresh 到期、最近登录（来自 `dws auth status` + `dws profile list`），底部三个按钮：**刷新 / 退出登录 / 登录（重新登录）**；**未登录时是「登录 dws」按钮**，后台跑 `dws auth login` 走 OAuth loopback 网页授权（自动开浏览器，日志落 `_原始数据/dws-login.log`），登录后自动刷新；**退出登录**走 `dws auth logout -y`（二次确认，清本机登录态，之后需重新扫码授权才能拉消息）
+- **搜索群 / 拉取全部最新收进右键菜单**：侧栏空白处（或任意会话上）右键即见；搜索框默认收起，点「🔍 搜索群…」才展开（Esc 收起）
+- **拉取全部最新**（右键菜单「⬇️ 拉取全部最新」）：所有会话依次增量刷新
+- **右键会话**：成员 / 人员 ID、拉取最新消息、复制会话 ID、删除归档（移到 `_回收站/`，可恢复）；下面隔开的全局项：搜索群、拉取全部最新
+- **工具栏一行到底**：搜索框 + 发送者 / 来源群 / 时间范围（全部·今天·近 4 档）/ 排序（最新在前·最早在前）+ 条数
+- **发消息默认收起**：右下角「✏️ 发消息」悬浮按钮，点开才展开浮层（`⌘/Ctrl + Enter` 发送，× 或 Esc 收起）；有草稿自动展开；点发送即直接投递（不弹确认框），发送后自动回读归档确认落库；草稿按会话保存；可勾选是否带「AI 角标」（默认**不带**）
+- **@我 聚合**：把「**已归档群聊**」里的 `@我` 消息汇总成一条时间线。侧栏在「@我的消息」下标出**来源群子级 + 条数**；每条消息带 📍 群名标签、左侧竖条按群配色；「来源群」页看群排行。**只扫已归档的群**，新增/删除群后点「重新汇总」修正
+  - 每条 @我 消息底部三个按钮：
+    - **🗄 归档定位** = 跳到左侧该群归档并高亮这条消息（精确可靠）
+    - **💬 打开钉钉** = 唤起桌面钉钉 + 只把「群名」写进剪贴板（粘进钉钉顶部「搜索或提问」框即可命中）；钉钉**没有开放「按会话/消息直达」的协议**（官方 AppLink 只收 chatId，开放接口拿不到反向映射），所以进群仍需粘贴群名搜索；完整定位信息走旁边的「复制定位信息」
+    - **📋 复制定位信息** = 只复制不动钉钉
+- **成员 / 人员 ID**：左侧会话**右键 →「👥 成员 / 人员 ID」**弹窗查看（姓名、群昵称、角色、openDingtalkId、memberDingtalkId）；@我 聚合弹「来源群」表，单聊弹参与者
+- **＋ 新群**（账号胶囊右边）：关键词调 `dws chat +chat-search` 找群；也可手动填「名称 + openConversationId + 单聊/群聊」直接归档
+- **会话项悬停出「⋯」**：点击等同右键（成员 / 复制 ID / 拉取 / 删除），不用猜在哪右键
+- 标题一行装下全部信息；**会话 ID 默认隐藏**，悬停标题行才显示，点击即复制
+- URL 可深链：`#<群简称>`
+
+> **发消息是以你本人钉钉身份发送的真消息**：群聊走 `chat +messages-send --group <cid>`，单聊走 `--open-dingtalk-id <对方>`；点「发送」即直接投递（服务端带 `--yes`），不弹确认框。
+> 单聊没有成员接口，参与者由消息发送者推断写入 `群信息与人员ID.md`。
+> 删除默认进 `_回收站/<简称>__<时间戳>/`，确认不需要再手动清空。
+> `群索引.md` 由服务自动重建，手改会被覆盖；其他手工文件不会被触碰。
+
+## 约定
+
+- **群简称**：取群名主干（如 `11.12-11.16闻香识美人`），去掉 `【待排期】` 等状态前缀。
+- **群 ID 唯一**：`openConversationId`（形如 `cidE6Ix+J4uPPaRd1TCp/hfEw==`）是拉消息、拉成员的唯一稳定 ID，群名会变，ID 不变。
+- **人员 ID**：发送者过滤、@人、发消息一律用 `openDingTalkId`，不要用展示名。
+- **字段大小写不一致**：`+chat-members-list` 返回有时是 `openDingtalkId`、有时是 `openDingTalkId`，解析按两者兜底（`src/archive.js` 的 `openIdOf`）。
+- **群主不一定在 users[0]**：成员顺序不固定，按 `role == "群主"` 找。
+- **完整性字段**：每份消息文件保留 `complete` / `hasMore` / 条数 / 范围，不完整要显式标注，不得当全量使用。
+
+## 常用 dws 命令
+
+```bash
+# 搜群，拿 openConversationId
+dws chat +chat-search --query "<群名关键词>" --format json
+
+# 拉群成员（含姓名、角色、openDingTalkId）
+dws chat +chat-members-list --group "<cid>" --format json
+
+# 拉群消息（全部时间，正序，忽略表情回应）
+dws chat +chat-messages --group "<cid>" --order asc --page-all --page-limit 50 --no-reactions --format json
+
+# 拉指定时间范围
+dws chat +chat-messages --group "<cid>" --start "2026-11-12T00:00:00+08:00" --end "2026-11-17T00:00:00+08:00" --order asc --page-all --no-reactions --format json
+
+# 按关键词搜消息（默认近 7 天）
+dws chat +search-msg --chat-query "<群名>" --query "<关键词>" --start "..." --end "..." --page-all --format json
+
+# 下载消息里的图片/文件（仅在需要时开）
+dws chat +chat-messages --group "<cid>" --page-all --download-resources --output-dir "<目录>" --format json
+```
+
+## 开发
+
+```bash
+node bin/oh-my-dws.js --no-open --port 26000   # 本地调试（前台）
+npm run check                                  # 语法 + 网页 id 引用自检
+npm pack --dry-run                             # 检查发布内容
+```
+
+## 发版（打 tag 自动发 npm）
+
+仓库里已有 `.github/workflows/release.yml`：**推 `v*` tag 就自动 `npm publish`**。
+
+1. 一次性（二选一）：
+   - **可信发布（推荐）**：npm 包页面 `/access` → Trusted Publishers → Add publisher → GitHub Actions，
+     填 `duzhenxun` / `oh-my-dws` / `release.yml`，Environment 留空；不用任何 token
+   - **或用 token**：npm 建 **Automation** token，存进 GitHub Secrets，名字 `NPM_TOKEN`
+2. 以后一条命令发版：
+
+```bash
+npm run release          # 0.0.1 → 0.0.2（改版本 + commit + tag + push）
+npm run release:minor    # → 0.1.0
+npm run release:major    # → 1.0.0
+```
+
+CI 会校验 **tag 与 `package.json` 版本一致**、跑 `npm run check`、`npm pack --dry-run`、
+已发布过则跳过，最后 `npm publish --access public` 并建 GitHub Release。
+细节与报错处理见 [docs/使用说明.md](docs/使用说明.md)。
+
+## 注意
+
+- 图片消息正文只返回 `mediaId`，需要实际图片时由网页按需下载。
+- 消息正文落盘视为内部资料，注意不要外发；`_原始数据` 可能含敏感字段时请先脱敏。
+- 历史上有 Python 实现（`server.py`），已迁移为 Node.js，旧文件保留在 git 历史里。
+
+## License
+
+MIT

package/bin/oh-my-dws.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * oh-my-dws 命令行入口。
+ *
+ * 前台：oh-my-dws [--port 25258] [--data 目录] [--no-open]
+ * 后台：oh-my-dws start|stop|restart|status|update
+ *
+ * start 会以 detached 子进程跑 `__serve`，PID/端口写进 <数据目录>/server.json，
+ * 日志写进 <数据目录>/_运行/server.log，所以 stop/status 不依赖当前终端。
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+
+const pkg = require('../package.json');
+
+const DEFAULT_PORT = 25258;
+const COMMANDS = ['start', 'stop', 'restart', 'status', 'update', 'serve', '__serve'];
+
+const HELP = `oh-my-dws ${pkg.version} — 钉钉群消息归档（本地网页控制台）
+
+用法
+  oh-my-dws                   前台启动（默认 http://127.0.0.1:${DEFAULT_PORT}）
+  oh-my-dws start [选项]      后台启动（脱离终端，日志落 _运行/server.log）
+  oh-my-dws stop              停止后台服务
+  oh-my-dws restart [选项]    重启后台服务
+  oh-my-dws status            查看运行状态（PID、端口、URL、数据目录）
+  oh-my-dws update            升级到 npm 最新版，并在运行中时自动重启
+
+选项（start / restart / 前台启动通用）
+  -p, --port <端口>    监听端口（默认 ${DEFAULT_PORT}）
+      --data <目录>    聊天数据目录（默认 ~/.oh-my-dws，等价于 OH_MY_DWS_HOME）
+      --no-open        不自动打开浏览器
+  -v, --version        查看版本
+  -h, --help           查看帮助
+
+示例
+  oh-my-dws start                      # 后台起服务并打开浏览器
+  oh-my-dws start --port 26000 --no-open
+  oh-my-dws status
+  oh-my-dws restart
+  oh-my-dws stop
+  oh-my-dws update
+  oh-my-dws                            # 前台跑，Ctrl+C 结束
+  oh-my-dws 26000                      # 前台 + 指定端口（位置参数兼容写法）
+
+数据目录结构（可整体备份/迁移）
+  ~/.oh-my-dws/
+  ├── 群索引.md
+  ├── server.json    后台服务的 PID / 端口（start 写入，stop 删除）
+  ├── _运行/          server.log（后台日志）
+  ├── _原始数据/      CLI 原始 JSON + dws-login.log
+  ├── _媒体/          消息图片/文件缓存
+  ├── _回收站/        删除的归档（可恢复）
+  └── <群简称>/       群信息与人员ID.md、群消息-*.md
+
+依赖：dws（钉钉 CLI，需已登录 dws auth login）
+`;
+
+function parseArgs(argv) {
+  const opts = {
+    cmd: '',
+    port: DEFAULT_PORT,
+    portSet: false,
+    dataDir: process.env.OH_MY_DWS_HOME || '',
+    noOpen: false,
+    help: false,
+    version: false,
+    rest: [],
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '-v' || a === '--version') opts.version = true;
+    else if (a === '--no-open') opts.noOpen = true;
+    else if (a === '-p' || a === '--port') {
+      opts.port = Number(argv[i + 1]);
+      opts.portSet = true;
+      i += 1;
+    } else if (a.startsWith('--port=')) {
+      opts.port = Number(a.slice(7));
+      opts.portSet = true;
+    } else if (a === '--data') {
+      opts.dataDir = argv[i + 1] || '';
+      i += 1;
+    } else if (a.startsWith('--data=')) opts.dataDir = a.slice(7);
+    else opts.rest.push(a);
+  }
+
+  // 第一个位置参数若是已知命令就当命令，否则按老写法视作端口
+  const first = opts.rest[0];
+  if (first && COMMANDS.includes(first)) {
+    opts.cmd = first;
+    opts.rest.shift();
+  } else if (first && /^\d+$/.test(first)) {
+    opts.port = Number(first);
+    opts.portSet = true;
+    opts.rest.shift();
+  }
+
+  if (!Number.isInteger(opts.port) || opts.port <= 0 || opts.port > 65535) opts.port = DEFAULT_PORT;
+  return opts;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+
+if (opts.help) {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (opts.version) {
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+// 必须在 require 业务模块之前设置：paths.js 在 require 时就确定数据目录
+if (opts.dataDir) process.env.OH_MY_DWS_HOME = path.resolve(opts.dataDir);
+if (opts.noOpen) process.env.NO_OPEN = '1';
+
+const P = require('../src/paths');
+
+const STATE_FILE = path.join(P.DATA_DIR, 'server.json');
+const RUN_DIR = path.join(P.DATA_DIR, '_运行');
+const LOG_FILE = path.join(RUN_DIR, 'server.log');
+
+const out = (s) => process.stdout.write(`${s}\n`);
+const err = (s) => process.stderr.write(`${s}\n`);
+
+/* ---------------- 状态文件 ---------------- */
+
+function readState() {
+  try {
+    return JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeState(s) {
+  fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
+  fs.writeFileSync(STATE_FILE, `${JSON.stringify(s, null, 2)}\n`);
+}
+
+function clearState() {
+  try {
+    fs.unlinkSync(STATE_FILE);
+  } catch {}
+}
+
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e) {
+    return e.code === 'EPERM';
+  }
+}
+
+/** 当前是否在跑：状态文件里的 pid 还活着就算 */
+function currentState() {
+  const st = readState();
+  if (!st || !pidAlive(st.pid)) return null;
+  return st;
+}
+
+function urlOf(port) {
+  return `http://127.0.0.1:${port}/`;
+}
+
+async function probeHealth(port, timeout = 1200) {
+  try {
+    const ac = new AbortController();
+    const t = setTimeout(() => ac.abort(), timeout);
+    const r = await fetch(`${urlOf(port)}api/health`, { signal: ac.signal });
+    clearTimeout(t);
+    if (!r.ok) return null;
+    return await r.json();
+  } catch {
+    return null;
+  }
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin'
+    ? ['open', [url]]
+    : process.platform === 'win32'
+      ? ['cmd', ['/c', 'start', '', url]]
+      : ['xdg-open', [url]];
+  spawnSync(cmd[0], cmd[1], { stdio: 'ignore' });
+}
+
+/* ---------------- 命令实现 ---------------- */
+
+async function cmdStatus() {
+  const st = readState();
+  if (!st) {
+    out(`● 未运行（没有找到 ${STATE_FILE}）`);
+    out(`  数据目录：${P.DATA_DIR}`);
+    return 3;
+  }
+  if (!pidAlive(st.pid)) {
+    out('● 未运行（状态文件是上次异常退出留下的，已清理）');
+    clearState();
+    return 3;
+  }
+  const health = await probeHealth(st.port);
+  out(`● 运行中  PID ${st.pid}`);
+  out(`  URL：${urlOf(st.port)}`);
+  out(`  端口：${st.port}`);
+  out(`  启动：${st.startedAt || '—'}`);
+  out(`  版本：${health ? health.version : `${st.version || pkg.version}（HTTP 未响应）`}`);
+  out(`  数据：${health ? health.dataDir : st.dataDir || P.DATA_DIR}`);
+  out(`  日志：${LOG_FILE}`);
+  return health ? 0 : 4;
+}
+
+/* status 退出码：0=运行中  3=未运行  4=进程在但 HTTP 无响应  1=异常 */
+
+async function cmdStart() {
+  const running = currentState();
+  if (running) {
+    out(`● 已在运行：${urlOf(running.port)}  (PID ${running.pid})`);
+    out('  想重启用 oh-my-dws restart，想换端口先 oh-my-dws stop');
+    if (!opts.noOpen) openBrowser(urlOf(running.port));
+    return 0;
+  }
+
+  fs.mkdirSync(RUN_DIR, { recursive: true });
+  const log = fs.openSync(LOG_FILE, 'a');
+  const args = [__filename, '__serve', '--port', String(opts.port), '--no-open'];
+  if (opts.dataDir) args.push('--data', P.DATA_DIR);
+  const child = spawn(process.execPath, args, {
+    detached: true,
+    stdio: ['ignore', log, log],
+    env: { ...process.env, NO_OPEN: '1' },
+  });
+  fs.closeSync(log);
+  child.unref();
+
+  writeState({
+    pid: child.pid,
+    port: opts.port,
+    url: urlOf(opts.port),
+    version: pkg.version,
+    dataDir: P.DATA_DIR,
+    startedAt: new Date().toISOString(),
+    log: LOG_FILE,
+  });
+
+  // 等它真的能响应（最多 ~6s），失败就把日志尾巴打出来
+  let health = null;
+  for (let i = 0; i < 30; i += 1) {
+    health = await probeHealth(opts.port, 400);
+    if (health) break;
+    if (!pidAlive(child.pid)) break;
+    await new Promise((r) => setTimeout(r, 200));
+  }
+
+  if (!health) {
+    if (pidAlive(child.pid)) {
+      out(`● 已启动（PID ${child.pid}），但 ${urlOf(opts.port)} 还没响应`);
+    } else {
+      err('启动失败，日志尾部：');
+      try {
+        err(fs.readFileSync(LOG_FILE, 'utf8').split('\n').slice(-15).join('\n'));
+      } catch {}
+      clearState();
+      return 1;
+    }
+  } else {
+    out(`● 已启动：${urlOf(opts.port)}  (PID ${child.pid})`);
+    out(`  数据：${P.DATA_DIR}`);
+    out(`  日志：${LOG_FILE}`);
+  }
+  if (!opts.noOpen) openBrowser(urlOf(opts.port));
+  return 0;
+}
+
+async function stopByState(st, quiet = false) {
+  if (!st) return 0;
+  if (!pidAlive(st.pid)) {
+    clearState();
+    if (!quiet) out('● 未运行（状态文件已清理）');
+    return 0;
+  }
+  try {
+    process.kill(st.pid, 'SIGTERM');
+  } catch (e) {
+    clearState();
+    err(`停止失败：${e.message}`);
+    return 1;
+  }
+  for (let i = 0; i < 40; i += 1) {
+    if (!pidAlive(st.pid)) break;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  if (pidAlive(st.pid)) {
+    try {
+      process.kill(st.pid, 'SIGKILL');
+    } catch {}
+  }
+  clearState();
+  if (!quiet) out(`● 已停止  PID ${st.pid}`);
+  return 0;
+}
+
+async function cmdStop() {
+  const st = readState();
+  if (!st) {
+    out('● 未运行');
+    return 0;
+  }
+  return stopByState(st);
+}
+
+async function cmdRestart() {
+  const st = readState();
+  if (st) {
+    await stopByState(st, true);
+    out('● 已停止旧进程');
+  }
+  return cmdStart();
+}
+
+async function cmdUpdate() {
+  const running = currentState();
+  out('→ 安装最新版：npm install -g oh-my-dws@latest');
+  const r = spawnSync('npm', ['install', '-g', 'oh-my-dws@latest'], { stdio: 'inherit' });
+  if (r.status !== 0) {
+    err('升级失败（可试试 sudo npm install -g oh-my-dws@latest）');
+    return 1;
+  }
+  if (running) {
+    out('→ 旧进程还在跑，重启以使用新版本…');
+    await stopByState(running, true);
+    return cmdStart();
+  }
+  out('● 已升级；下次 oh-my-dws start 就会用新版本');
+  return 0;
+}
+
+/* 前台服务（默认行为，也是 start 拉起的子进程） */
+function runForeground() {
+  const { createServer } = require('../src/server');
+  return createServer({ port: opts.port, open: !opts.noOpen }).then(({ server }) => {
+    const shutdown = () => {
+      server.close(() => process.exit(0));
+      setTimeout(() => process.exit(0), 1500).unref();
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+}
+
+const dispatch = {
+  start: cmdStart,
+  stop: cmdStop,
+  restart: cmdRestart,
+  status: cmdStatus,
+  update: cmdUpdate,
+  serve: runForeground,
+  __serve: runForeground,
+};
+
+(async () => {
+  const fn = dispatch[opts.cmd || 'serve'] || runForeground;
+  try {
+    const code = await fn();
+    if (typeof code === 'number' && opts.cmd && opts.cmd !== 'serve' && opts.cmd !== '__serve') {
+      process.exit(code);
+    }
+  } catch (e) {
+    if (e && e.code === 'EADDRINUSE') {
+      err(`端口 ${opts.port} 已被占用，换个端口：oh-my-dws start --port ${opts.port + 1}`);
+    } else {
+      err(`启动失败：${(e && e.message) || e}`);
+    }
+    process.exit(1);
+  }
+})();