weflow-cli 1.8.2 → 1.10.0

package/docs/RELEASING.md

@@ -32,8 +32,25 @@ npm 包与 GitHub 分开发布，中间隔多久都不奇怪——`1.5.0` 与主
 ```powershell
 npm run build
 npm test
+py scripts/check_readme_commands.py          # 文档/脚本调用/capabilities 里写的命令必须真的存在
 ```
 
+最后那条盯的是**用户先发现的那一类漂移**：`1.5.0` 与主线拉开 128 个提交时，用户照着 README 敲
+`init --path` 得到 `unknown option`。它逐级问 CLI 的 `--help`（不复刻命令表），扫**三个手写的命令面**：
+**用户文档**的围栏代码块（两份 README + 仓库根那几份 + `docs/*.md`，排除按性质记录过去的
+`CHANGELOG.md` 与 `docs/DECISIONS.md` —— 它们会成段引用当时的命令；同一批代码块里
+`node …/cli.cjs <命令>`、`npx tsx bin/weflow-cli.ts <命令>` 也算这一面 —— 那是同一套命令换个写法）、
+同一批代码块里的
+`python|py scripts/x.py --flag` 调用（**不跑脚本**，按 AST 读它们的 `add_argument` 声明表 —— 仓库对
+Python 脚本的既定纪律就是不 import 也不运行），以及 `capabilities --json` 里手写的 `cli:` **与 `preview:`**
+串（`preview:` 是两阶段约定的第一步 —— 用户与 agent 都按它来，所以它和 `cli:` 一样会被手写漂移；
+那个输出的 MCP 那半是从真实注册表派生的，不用管。串里有这个输出自己的记法：`<a|b>` 是"或"、
+括号外的 `|` 是"两种写法"、`…` 之后截断 —— 判据会按这个归一化后再验）。`--self-test` 是十三条正对照；
+文档命令那一面还有反空扫（缺省语料一定有命令，扫到 0 条就不报通过）。CI 的 `node` job 每次推送都会跑这两步。
+
+> 2026-10-11 它就是这么抓到东西的：`OPERATIONS.md` 教用户敲 `search --no-rerank`，而 CLI 从来没有
+> 这个旗标（Python 侧一直有）。只扫两份 README 时它一条也扫不到 —— 所以缺省集合就是"用户文档"。
+
 ## 4. 打包检查（**不能跳过**）
 
 ```powershell
@@ -57,6 +74,46 @@ grep -E "^output/|^models/|node_modules|\.env|\.db$|\.dat$|secret|credential" /t
 grep -E "新文件名" /tmp/list.txt
 ```
 
+这后半句（"**该有的在不在**"）现在有自动判据：`test/pack-contents.test.ts` 跑一次
+`npm pack --dry-run --json`，断言 `scripts/` 下每个跟踪文件（`.ts` 开发入口除外）与两份 README 引用的
+本地图片都在包里。它防的故障 2026-10-11 在**真实发布物**上量到过：registry 上 `weflow-cli@1.9.0`
+的 501 个文件里同时缺 `scripts/data/wechat_emoji.json` 与 `logo.png` —— 前者让 npm 用户导出的
+聊天记录里一批表情码原样显示成 `[名字]`，后者让包页面挂着一张裂图。这条测试跟着 `npm test` 跑，
+CI 的 `node` job 也在跑；上面那条人工命令留着，用来核对本次**新加**的文件名。
+
+想验到"**装出来真的能跑**"（最强的一道，代价是多装一次依赖）：把包打进临时目录、再装进一个空
+prefix，然后从**装好的那一份**里问版本。它盯的是白名单之外的另一半 —— 清单对、运行时不成立的情况。
+
+```powershell
+npm pack --pack-destination $env:TEMP
+mkdir $env:TEMP\wf-smoke ; cd $env:TEMP\wf-smoke     # 空目录
+npm install --no-save --no-audit --no-fund "$env:TEMP\weflow-cli-<版本>.tgz"
+node node_modules\weflow-cli\cli.cjs --version
+node node_modules\weflow-cli\cli.cjs --help
+```
+
+2026-10-11 拿 1.10.0 跑过一遍：`ALL_NAMES = 222`（不是只有原图的 118 —— 那正是上一版缺
+`scripts/data/wechat_emoji.json` 时的值）、`[乒乓]`/`[冷汗]`/`[开红包]` 都渲染成对应表情、
+`--version` 答 `1.10.0`。
+
+**两个数字口径，免得下一次又花半小时**（2026-10-11 实测）：`npm publish` 的 notice 报
+`package size: 12.5 MB` 用的是**十进制 MB**，而 `npm pack --json` 的 `size` 是**字节**（你按习惯除以
+`1MB` 得到 11.88 是 MiB）—— **同一份 tarball**：12,460,202 字节 = 12.46 MB = 11.88 MiB。
+`unpacked size` 同理（publish 27.9 MB = pack 26.62 MiB，解压实测 27,915,402 字节）。不是
+"publish 比 pack 大"，是两套单位。
+
+**发布时那两条 `npm warn publish … errors corrected` 是修饰性的，不是故障。**
+`bin[weflow-cli]` 那句「cli.cjs was invalid and removed」措辞很吓人，实际只是把 `./cli.cjs` 规范成
+`cli.cjs`；`repository.url` 被改写成 `git+https://…`。**实测证据**：registry 上 `weflow-cli@1.9.0`
+的元数据里 `bin = { 'weflow-cli': 'cli.cjs' }` 完好无损（`npm view weflow-cli@1.9.0 bin repository.url`）
+⇒ `npm i -g` 装出来的命令入口一直都在，**别据此以为发布物少了 bin**。
+（那两条规范化 2026-10-11 已经直接落到仓库里了：`package.json` 的 `bin` 与 `repository.url` 现在就是
+规范形式，发布时不再报这两条 warning，仓库也与 registry 上的一致。）
+
+> ⚠️ **`npm pkg fix` 没有 `--dry-run`**：`npm pkg fix --dry-run` 会把 `--dry-run` 当成不认识的参数**忽略掉**，
+> 然后**直接改你的 `package.json`**（2026-10-11 就是这么被改的 —— 我原以为只是"看看会改什么"）。
+> 想先看结果就用 `git diff package.json` 兜底，别指望它自己停手。
+
 ## 5. 发布
 
 需要 npm 凭据。`ribiaosu` 账号开了 2FA，所以两条路：
@@ -68,7 +125,7 @@ grep -E "新文件名" /tmp/list.txt
 | 现象 | 原因 |
 | --- | --- |
 | `403 ... two-factor authentication ... required` | token 没勾 Bypass 2FA，或没用 OTP |
-| `ENEEAUTH` | 没登录 / 没配 token |
+| `ENEEDAUTH` | 没登录 / 没配 token |
 
 **验证 token 是否可用**（`bypass_2fa` 必须是 `true`）：
 
@@ -111,6 +168,22 @@ npm publish    # 再发一次
 
 报 `409 Conflict - Cannot publish over previously staged version` → **已经发布成功**。
 
+但 409 只说明**版本槽位已被占**，不等于 registry 已经能查到它。发布后 npm 要先扫描再让版本可读，
+**官方不承诺上限**：常见 5 分钟，实测出现过 14、16、25、55 分钟。这个窗口里的表现是：
+
+- `npm view weflow-cli version` 还是旧版本号
+- tarball 直链仍然 404
+- 再发一次仍然是 409 —— 所以 409 **区分不了**「还在传播」和「已经好了」
+
+窗口期内只做一件事：等 + 轮询，**不要改版本号重发**。想确认不是卡在人工审批：
+
+```powershell
+npx --yes npm@11.17.0 stage list weflow-cli --json   # 返回 [] 即无待审批版本，属传播中
+```
+
+（`npm stage` 需要 npm ≥ 11.15；本机装的是 11.6.2，直接跑会报 `Unknown command: "stage"`，
+所以用 npx 临时拉一个高版本。`npm@11.17.0` 是在本机 Node 24.11.1 上验证过能用的。）
+
 ## 8. 兜底：告诉用户怎么绕开镜像
 
 ```powershell
@@ -121,6 +194,30 @@ npm view weflow-cli version --registry=https://registry.npmjs.org  # 用官方
 两个源结果不一致 → 是镜像同步问题，不是包的问题：
 `npm install -g weflow-cli@<版本> --registry=https://registry.npmjs.org` 立刻可用。
 
+## 建 GitHub Release 时的两个坑（2026-10-02 补 1.8.0/1.8.1/1.8.2 时实测）
+
+- **正文上限 125,000 字符。** 1.8.0 那段 CHANGELOG 是 140,154 字符，直接贴会被 API 拒：
+  `HTTP 422 ... body is too long (maximum is 125000 characters)`。处理方式是**按 `### ` 小节边界
+  机械截断**（放到装不下为止），末尾补一句"完整条目在 `CHANGELOG.md`"。**不要凭"哪几段更重要"去挑**：
+  那既不可复现，也不是发布这件事该做的判断。
+- **补历史的 Release 要显式 `--latest=false`。** `gh release create` 默认会把新页面标成 Latest ——
+  给 1.8.x 补账时会把 1.9.0 从 Latest 上挤下去。补完用 `gh release list` 确认 Latest 还是最新的那个。
+- **发布前先确认工作区干净**（`git status` 为空，HEAD 就是你打算打 tag 的那次提交）。
+  理由不是形式主义，是实测出来的：2026-10-02 给 1.8.0/1.8.1/1.8.2 补 tag 时做了逐文件溯源
+  （拿 registry 上的 tarball 与 `git archive <tag>` 比，行尾差异不算），结果是 1.8.1 与 1.8.2 的
+  发布源码与 tag 树**一致**，而 **1.8.0 的包里有两个文档文件在 git 里找不到对应状态**：
+  `docs/DECISIONS.md` 与更晚的一次提交一致，`README.en.md` 则**与任何提交都不一致**（比 tag 那份
+  长约 7,000 字符）。代码部分没问题（逐字节相同），但**那次发布出去的文档再也回不来** ——
+  这正是"不把 npm 发布包当作 GitHub 源码的实时镜像；先确认版本和提交"这条规矩要防的事。
+- **1.9.0 的出处核过了（2026-10-11，用上面同一套办法）**：把 registry 上的 tarball 与
+  `git archive v1.9.0` 逐文件比（行尾归一后比内容）：两边都有的 **289 个文件全部逐字节一致、0 处不同**；
+  包里多出的 212 个是 `dist/`（构建产物、不在 git 里）；tag 里有而包里没有的 124 个是白名单外的
+  东西（`.github/`、`AGENTS.md`、`package-lock.json`、`scripts/*.ts` 等）。
+  ⚠️ 其中 **`logo.png` 与 `scripts/data/wechat_emoji.json` 两个文件当时确实没进包** —— 那正是
+  1.10.0 修掉的缺口（同一件事，两条独立的路都指到它）。
+  **结论：1.8.0 那个"发出去的文档再也回不来"没有在 1.9.0 重演** ✅
+
+
 ## 发布后
 
 - 回到相关 issue 回复「已发布 + 升级方式」
@@ -162,6 +259,23 @@ npm view weflow-cli version --registry=https://registry.npmjs.org  # 用官方
 - 手动跑一次：`py scripts/watch_issues.py`
 - 查看/改频率：`Get-ScheduledTask -TaskName 'WeFlow Issue Watch'`
 
+**两个任务怎么建**（这一节此前只写"交给计划任务"，**命令本身没记下来过** —— 而 `scripts/health_check.py`
+正是按这两个**名字**判红的，所以缺的从来不是判断，是这三行）：
+
+```powershell
+schtasks /create /tn "WeFlow Issue Watch" /sc minute /mo 30 ^
+  /tr "py \"<仓库路径>\scripts\watch_issues.py\""
+schtasks /create /tn "WeFlow Mail Watch" /sc minute /mo 30 ^
+  /tr "py \"<仓库路径>\scripts\watch_mail.py\""
+```
+
+- 查看：`Get-ScheduledTask -TaskName 'WeFlow *'` ／ 撤销：`schtasks /delete /tn "<任务名>" /f`
+- **PATH 不用操心**（计划任务的 PATH 与交互式会话不同，这是这类任务常见的翻车点）：`watch_issues.py`
+  自己带兜底 —— `GH_CANDIDATES = ['gh', r'C:\Program Files\GitHub CLI\gh.exe']`；`py` 是系统启动器
+  （`C:\Windows\py.exe`）。两者都不依赖任务继承的 PATH。
+- `watch_mail.py` 做的是**另一件事**：把白名单来信追加进本地队列 `~/.weflow-mail-queue.jsonl`
+  （不读别人的信、不发信；真正按指令做事要等一个会话在跑）。
+
 ### 发布后自检
 
 ```powershell

package/mcp-server/http.ts

@@ -0,0 +1,108 @@
+/**
+ * MCP 的 **HTTP 传输**（Streamable HTTP）。stdio 那条路一个字没动，这是**另一条**路。
+ *
+ * 为什么要它：stdio 只能被"能起进程"的客户端用（Claude Code、IDE 插件）。HTTP 那条路在
+ * 生态里已是常态——chatlog 就是拿 Streamable HTTP / SSE 把同一批查询能力摊出来的，于是浏览器型
+ * 客户端、常驻服务、多个客户端同时连都能用。工具集**完全一样**（同一张 `TOOL_DEFS` 派生表），
+ * 变的只是搬运动作的方式。
+ *
+ * 三道边界（判定在 `httpConfig.ts`，纯函数、有测试）：
+ * 1. **默认不开**：不给 `--http` 就是 stdio，行为与以前逐字相同。
+ * 2. **必须带令牌**，且**只绑回环**（远程走 SSH 隧道，见 docs/MCP.md）。
+ * 3. **打开 DNS 重绑定防护**：SDK 的默认是 `false`，而本机 HTTP 服务最现实的攻击面就是
+ *    "你正在浏览的某个网页往 127.0.0.1 发请求"。打开后 Host 头必须对得上，带 Origin 的
+ *    浏览器请求也必须在白名单里。
+ *
+ * 采用**无状态**模式（每个请求一套 server+transport）：这一层只有只读查询，没有要跨请求维持的
+ * 会话，无状态就没有"会话之间串了"这类问题。
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import type { Server as McpServer } from '@modelcontextprotocol/sdk/server/index.js'
+import {
+  allowedHostsFor,
+  allowedOriginsFor,
+  isAuthorized,
+  type HttpOptions,
+} from './httpConfig.js'
+
+export const MCP_HTTP_PATH = '/mcp'
+
+export interface RunningHttpServer {
+  /** 实际绑定的地址（端口传 0 时是内核挑的，所以以这里为准） */
+  url: string
+  port: number
+  close: () => Promise<void>
+}
+
+function json(res: ServerResponse, code: number, body: unknown): void {
+  res.writeHead(code, { 'content-type': 'application/json' })
+  res.end(JSON.stringify(body))
+}
+
+/**
+ * 起 HTTP 传输。`buildServer` 每次调用都必须返回一个**新的** Server（无状态模式每个请求一套）。
+ */
+export async function startHttpServer(
+  opts: HttpOptions,
+  buildServer: () => McpServer,
+  log: (line: string) => void = () => {},
+): Promise<RunningHttpServer> {
+  let allowedHosts: string[] = []
+  let allowedOrigins: string[] = []
+
+  const handler = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    const url = req.url ?? '/'
+    if (url !== MCP_HTTP_PATH && !url.startsWith(MCP_HTTP_PATH + '?')) {
+      json(res, 404, { error: 'not found', hint: `MCP 端点在 ${MCP_HTTP_PATH}` })
+      return
+    }
+    // 令牌先判、再谈别的：没令牌的请求连"MCP 认不认识这个方法"都不该知道。
+    if (!isAuthorized(req.headers.authorization, opts.token)) {
+      json(res, 401, { jsonrpc: '2.0', error: { code: -32001, message: '未授权：缺少或不对的 Bearer 令牌' }, id: null })
+      return
+    }
+
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,          // 无状态
+      enableJsonResponse: true,               // 不强制 SSE：普通客户端拿 JSON 就好
+      enableDnsRebindingProtection: true,     // SDK 默认 false，必须显式开
+      allowedHosts,
+      allowedOrigins,
+    })
+    const server = buildServer()
+    res.on('close', () => { void transport.close(); void server.close().catch(() => {}) })
+    try {
+      await server.connect(transport)
+      await transport.handleRequest(req, res)
+    } catch (error: any) {
+      log(`[mcp-http] 请求处理失败: ${error?.message ?? error}`)
+      if (!res.headersSent) {
+        json(res, 500, { jsonrpc: '2.0', error: { code: -32603, message: '内部错误' }, id: null })
+      }
+    }
+  }
+
+  const httpServer: Server = createServer((req, res) => { void handler(req, res) })
+
+  await new Promise<void>((resolve, reject) => {
+    httpServer.once('error', reject)
+    httpServer.listen(opts.port, opts.host, () => {
+      httpServer.removeListener('error', reject)
+      resolve()
+    })
+  })
+
+  const address = httpServer.address()
+  const port = typeof address === 'object' && address ? address.port : opts.port
+  // **绑定之后**才算白名单：端口传 0 时真实端口此刻才知道，而白名单必须用真实端口。
+  allowedHosts = allowedHostsFor(opts.host, port)
+  allowedOrigins = allowedOriginsFor(opts.host, port)
+
+  const shownHost = opts.host === '::1' ? '[::1]' : opts.host
+  return {
+    url: `http://${shownHost}:${port}${MCP_HTTP_PATH}`,
+    port,
+    close: () => new Promise<void>((resolve) => { httpServer.close(() => resolve()) }),
+  }
+}

package/mcp-server/httpConfig.ts

@@ -0,0 +1,126 @@
+/**
+ * HTTP 传输的**判定**——纯函数，不碰 socket、不连 MCP，所以能离线测。
+ *
+ * 为什么值得单独一个文件：这里每一条规则决定的都是"要不要把本机的私密数据摊到一个网络
+ * 端口上"。服务器本体要起 socket、要装 SDK，测起来重；把判定抽出来，规则就能一条一条钉住
+ * （`test/mcp-http.test.ts`）。
+ *
+ * 边界（写死在这里，不靠调用方自觉）：
+ * - **默认不开**：不给 `--http` 也不给 `WEFLOW_MCP_HTTP` 就还是 stdio，行为与以前逐字相同。
+ * - **必须带令牌**：没给就**拒绝启动**，不给默认值 —— 一个悄悄生成的默认口令比没有更坏，
+ *   因为它看起来是"配好了"。
+ * - **只绑回环**：远程访问自己走 SSH 隧道或反向代理。把私密聊天记录摊到局域网上，
+ *   不该由这个文件顺手打开。
+ */
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+
+/** 默认端口。5030 是 chatlog 的，避开它免得两个服务打架。 */
+export const DEFAULT_HTTP_PORT = 8790
+
+/**
+ * 令牌长度下限。128 位随机（32 个 hex 字符）是常态；24 个字符足够排除"随手敲一个"，
+ * 又不至于逼人非得用某个特定长度。
+ */
+export const MIN_TOKEN_CHARS = 24
+
+/** 允许绑定的地址。**只回环**：`0.0.0.0` 不在此列，而且不是"忘了加"。 */
+export const LOOPBACK_HOSTS = ['127.0.0.1', 'localhost', '::1']
+
+export interface HttpOptions {
+  host: string
+  port: number
+  token: string
+}
+
+/** 这一轮是不是要走 HTTP。`--http`、`--http=8790`、`WEFLOW_MCP_HTTP=1` 都算。 */
+export function httpModeRequested(env: Record<string, string | undefined>, argv: string[]): boolean {
+  if (argv.some((a) => a === '--http' || a.startsWith('--http='))) return true
+  const value = String(env.WEFLOW_MCP_HTTP ?? '').trim()
+  return value !== '' && value !== '0' && value.toLowerCase() !== 'false'
+}
+
+function flagValue(argv: string[], name: string): string | undefined {
+  const hit = argv.find((a) => a.startsWith(`${name}=`))
+  return hit ? hit.slice(name.length + 1) : undefined
+}
+
+/**
+ * 解出 HTTP 模式的参数。**不走 HTTP 就返回 `null`**；要走但配置不合法就**抛错**（fail closed，
+ * 绝不"降级成不安全的默认值"继续跑）。
+ *
+ * 端口允许 `0`：那是让内核挑一个空闲端口，测试要用；正式跑用默认端口。
+ */
+export function resolveHttpOptions(
+  env: Record<string, string | undefined>,
+  argv: string[],
+): HttpOptions | null {
+  if (!httpModeRequested(env, argv)) return null
+
+  const token = String(flagValue(argv, '--token') ?? env.WEFLOW_MCP_TOKEN ?? '').trim()
+  if (!token) {
+    throw new Error(
+      'HTTP 模式必须给令牌：`--token=<随机串>` 或环境变量 WEFLOW_MCP_TOKEN。\n'
+      + '没有默认值是有意的 —— 一个自动生成、只在日志里露一面的口令，看起来像"配好了"。\n'
+      + '生成一个：node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"',
+    )
+  }
+  if (token.length < MIN_TOKEN_CHARS) {
+    throw new Error(`令牌太短（${token.length} < ${MIN_TOKEN_CHARS} 个字符）。用随机串，别用可猜的短语。`)
+  }
+
+  const host = String(flagValue(argv, '--host') ?? '127.0.0.1').trim()
+  if (!LOOPBACK_HOSTS.includes(host)) {
+    throw new Error(
+      `只允许绑回环地址（${LOOPBACK_HOSTS.join(' / ')}），收到 ${host}。\n`
+      + '要从别的机器连，用 SSH 隧道（ssh -L 8790:127.0.0.1:8790 <host>）或自己的反向代理 —— '
+      + '把聊天记录摊到局域网上不该由这个命令顺手打开。',
+    )
+  }
+
+  const raw = flagValue(argv, '--http') ?? flagValue(argv, '--port') ?? env.WEFLOW_MCP_HTTP_PORT ?? String(DEFAULT_HTTP_PORT)
+  const rawText = String(raw).trim()
+  // 先按"纯数字"卡一道：`Number('') === 0`，不卡的话空值会静默变成一个端口。
+  if (!/^\d{1,5}$/.test(rawText)) {
+    throw new Error(`端口要 0-65535 之间的整数（0 = 让系统挑一个空闲端口），收到 ${JSON.stringify(raw)}`)
+  }
+  const port = Number(rawText)
+  if (port > 65535) {
+    throw new Error(`端口要 0-65535 之间的整数，收到 ${JSON.stringify(raw)}`)
+  }
+
+  return { host, port, token }
+}
+
+/**
+ * `Authorization` 头认不认。
+ *
+ * 比的是**摘要**而不是原文：`timingSafeEqual` 要求等长，直接比长度会漏出"令牌有多长"，
+ * 于是"不同长度直接返回 false"就成了一个可测的短路径。两边先过一遍 SHA-256，长度就固定了。
+ * 方案名按 RFC 7235 大小写不敏感。
+ */
+export function isAuthorized(header: string | undefined, token: string): boolean {
+  const raw = String(header ?? '')
+  const space = raw.indexOf(' ')
+  if (space < 0) return false
+  if (raw.slice(0, space).toLowerCase() !== 'bearer') return false
+  const presented = raw.slice(space + 1).trim()
+  if (!presented) return false
+
+  const digest = (value: string) => createHash('sha256').update(value, 'utf8').digest()
+  return timingSafeEqual(digest(presented), digest(token))
+}
+
+/** Host 头允许的取值（DNS 重绑定防护用）。带端口，因为 SDK 比的是**原始 Host 头**。 */
+export function allowedHostsFor(host: string, port: number): string[] {
+  const forms = new Set<string>()
+  for (const h of host === 'localhost' ? ['127.0.0.1', 'localhost'] : [host]) {
+    forms.add(h === '::1' ? `[::1]:${port}` : `${h}:${port}`)
+  }
+  return [...forms]
+}
+
+/** 允许的 Origin（浏览器来的请求会带；命令行客户端通常不带，不带就放行）。 */
+export function allowedOriginsFor(host: string, port: number): string[] {
+  return allowedHostsFor(host, port).map((h) => `http://${h}`)
+}