oh-my-dws 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,173 @@
-# 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 8850   # 本地调试
+npm pack --dry-run                            # 检查发布内容
+npm publish                                   # 发布（需 npm 登录）
+```
+
+## 注意
+
+- 图片消息正文只返回 `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);
+  }
+})();

package/docs//344/275/277/347/224/250/350/257/264/346/230/216.md

@@ -0,0 +1,129 @@
+# oh-my-dws 使用说明
+
+把钉钉项目群的消息**归档到本机**，用一个本地网页控制台浏览、搜索、增量拉取、导出 Markdown。
+数据全部落在 `~/.oh-my-dws`，代码与聊天数据完全分开；服务只监听 `127.0.0.1`，不上传任何东西。
+
+- 版本：`0.0.1`
+- 运行时：**Node.js ≥ 18**（零第三方依赖）
+- 数据源：本机 `dws`（钉钉 CLI，需已登录 `dws auth login`）
+- 默认地址：**http://127.0.0.1:25258**
+
+---
+
+## 一、装好并跑起来
+
+```bash
+# 1) 全局安装（或 npx oh-my-dws start 直接用）
+npm i -g oh-my-dws
+
+# 2) 确认本机 dws 已登录
+dws auth status
+
+# 3) 后台起服务（会打开浏览器）
+oh-my-dws start
+```
+
+三条命令就够用；后面是日常会用到的那些。
+
+## 二、命令行
+
+| 命令 | 作用 |
+|---|---|
+| `oh-my-dws start [--port N] [--data 目录] [--no-open]` | 后台启动，写 `~/.oh-my-dws/server.json`，日志到 `~/.oh-my-dws/_运行/server.log`，起来后自动开浏览器 |
+| `oh-my-dws status` | 打印 PID / 端口 / URL / 版本 / 数据目录 / 日志路径（会探 `/api/health`） |
+| `oh-my-dws stop` | 停止后台服务（SIGTERM，5 秒不退再 SIGKILL），并清掉 `server.json` |
+| `oh-my-dws restart [选项]` | 先停再起（`--port` 可在这一步换端口） |
+| `oh-my-dws update` | `npm i -g oh-my-dws@latest`；如果服务正在跑，会顺手重启 |
+| `oh-my-dws` | 前台启动，`Ctrl+C` 结束（老用法；适合看实时日志） |
+| `oh-my-dws 26000` | 前台启动 + 指定端口（位置参数兼容写法） |
+| `oh-my-dws -v` / `-h` | 版本 / 完整帮助 |
+
+`status` 的退出码：`0` 在跑、`3` 没跑、`4` 进程在但 HTTP 无响应、`1` 异常——方便写进脚本。
+
+常用选项：
+
+- `-p, --port <端口>`：监听端口，默认 **25258**
+- `--data <目录>`：聊天数据目录，默认 `~/.oh-my-dws`（等价环境变量 `OH_MY_DWS_HOME`）
+- `--no-open`：不自动打开浏览器（等价 `NO_OPEN=1`）
+
+`start` 和 `restart` 是幂等的：已经在跑时 `start` 只提示地址，不会起第二份；要换端口先 `stop` 或用 `restart --port`。
+
+## 三、网页怎么用
+
+### 侧栏
+
+- **默认收起**：收起后是一条 32px 窄条，顶部 `»` 展开，下面的圆点是**当前会话首字头像**，点它也展开。
+- **收起**：展开状态下鼠标移到侧栏上，右边缘中部会出现 `«` 把手，点一下收起；或者按 **⌘/Ctrl + B**（随时可切，状态会记住）。
+- **调宽**：拖侧栏右边缘（200–560px），双击边缘恢复默认 310px；宽度也记住。
+- 搜索框不再常驻：**右键 →「🔍 搜索群…」** 才出现（按地名/会话 ID 过滤，Esc 或清空后收起）。
+
+### 右键菜单
+
+| 在哪右键 | 能看到 |
+|---|---|
+| 某个会话 | 成员 / 人员 ID、拉取最新消息、复制会话 ID、删除归档；分隔线下：搜索群、拉取全部最新 |
+| 侧栏空白处 / 底部 / 账号胶囊 | 搜索群、拉取全部最新 |
+| 会话项右侧的「⋯」 | 同「某个会话」右键（鼠标悬停在会话上才出现，不用猜位置） |
+
+### 顶部与账号
+
+- **账号胶囊**：头像 + `姓名 · 组织`，绿点已登录 / 橙点未登录。点开是「dws 登录信息」：状态、组织、账号、profile、token / refresh 到期、最近登录；底部按钮 **刷新 / 退出登录 / 登录·重新登录**。
+  - 登录：后台跑 `dws auth login`（OAuth loopback，自动开浏览器），登录完成页面自动刷新。
+  - **退出登录**：`dws auth logout -y`，二次确认后清本机登录态；之后要重新授权才能拉消息。
+- **＋ 新群**（胶囊右侧）：搜索群并纳管，或手填「名称 + openConversationId + 单聊/群聊」直接归档。
+
+### 消息区
+
+- **默认倒序**（最新在最上），工具栏可切「最早在前」；支持关键词、发送者、来源群、时间范围过滤。
+- 新拉到的消息会高亮，逐条带 `messageId`、时间、发送者头像（按人员 ID 稳定配色 + 姓名首字）。
+- 引用消息显示成引用块，点一下跳到被引用的那条；`**加粗**`、`` `代码` ``、@人、链接都会渲染。
+- **图片直接看**：`[图片消息]` 按需下载到 `_媒体/` 并内联显示，点开可放大预览（Esc 关闭）。
+- **拉取最新消息**（消息区右上角）：从最后一条时间 −1 分钟拉到当前，按 `messageId` 去重合并，回写 JSON + Markdown + 群索引。
+- **发消息**：右下角「✏️ 发消息」，`⌘/Ctrl + Enter` 发送，草稿按会话保存；默认不带 AI 角标。注意——**这是以你本人钉钉身份发出的真消息**。
+- **@我 聚合**：「@我的消息」把所有已归档群里的 @我 汇总成一条时间线，来源群列在下面；每条消息可「归档定位 / 打开钉钉 / 复制定位信息」。只扫已归档的群，新增群后点「重新汇总」。
+
+## 四、数据在哪、怎么备份
+
+```
+~/.oh-my-dws/
+├── 群索引.md                 群名 → 群 ID / 成员数 / 文件位置（自动重建，别手改）
+├── server.json               后台服务 PID / 端口（start 写、stop 删）
+├── _运行/server.log          后台服务日志
+├── _原始数据/                dws 原始 JSON + dws-login.log
+├── _媒体/                    图片/文件缓存（可删，会重新拉）
+├── _回收站/                  删除的归档（确认不要了再手动清）
+└── <群简称>/
+    ├── 群信息与人员ID.md      群 ID、群主、成员表（openDingtalkId / memberDingtalkId）
+    └── 群消息-YYYYMMDD-YYYYMMDD.md
+```
+
+- 备份/迁移：整个目录拷走即可；换机器用 `oh-my-dws start --data /path/to/备份`。
+- 删除归档进 `_回收站/<简称>__<时间戳>/`，想恢复就搬回去再刷新页面。
+- 归档文件是内部资料，注意别外发。
+
+## 五、常见问题
+
+**端口被占用**：`oh-my-dws status` 看是不是已经在跑；换端口 `oh-my-dws restart --port 25259`。
+
+**页面提示「dws 未就绪 / 未登录」**：`dws auth status` 确认；点胶囊里的「登录 dws」，或命令行 `dws auth login --recommend`。
+
+**拉取报超时/失败**：`dws` 单次调用默认 300 秒超时；群特别大时先小范围拉（时间范围），再增量补。日志在 `_运行/server.log`。
+
+**没有新消息但侧栏没绿点**：只有真有新消息才亮绿点；打开会话即清零已读。
+
+**macOS 双击 `启动.command`**：等价 `oh-my-dws start`（后台常驻 + 开浏览器），关掉终端窗口服务照旧跑；停用 `oh-my-dws stop`。
+
+## 六、自己发布这个包
+
+```bash
+npm login                       # 账号：你的 npm 用户
+npm --version && npm pack --dry-run   # 先看打包内容
+npm publish                     # 第一次发 0.0.1（publishConfig.access=public）
+```
+
+发布后就能：
+
+```bash
+npm i -g oh-my-dws            # 装
+oh-my-dws update              # 以后升级 + 自动重启
+```