owned-account-pool-cli 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# 自有账号池 CLI
 
-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.
+面向 `https://handover.luckyjun.top` 的账号池与任务登记工具。支持交互登录、选择客户和账号、录入帖子与独立评论、编辑原稿、提交任务和失败恢复。
+
+## 安装
+
+需要 Node.js 24 LTS（24.15.0 起）或 26 及以上版本。
+
+```sh
+npm install -g owned-account-pool-cli
+owned-pool
+```
+
+也可直接运行。
+
+```sh
+npx --yes --package owned-account-pool-cli owned-pool
+```
+
+## 交互使用
+
+```sh
+owned-pool post create
+owned-pool comment create
+```
+
+命令会依次收集缺失的账号密码、客户、帖子用途、回复目标、社区、账号来源、权重阈值、账号、标题、正文、留存要求以及保存方式。正文支持直接输入、UTF-8 文件和系统编辑器，备注可留空。
+
+评论使用自有账号，回复社区通过服务端解析目标 URL 获得。账号选择保留服务端资格限制。草稿保存与提交通过 `--draft`、`--submit` 选择，也可在终端回答。
+
+这套流程创建系统登记任务，后续 Reddit 发布由发布人员执行。
+
+## 登录
+
+交互终端隐藏密码输入。可通过环境变量提供登录凭据。
+
+| 变量 | 用途 |
+| --- | --- |
+| `HANDOVER_USERNAME` | 系统登录账号 |
+| `HANDOVER_PASSWORD` | 系统登录密码 |
+| `HANDOVER_BASE_URL` | 服务根地址 |
+
+登录账号也支持 `--username`，服务地址支持 `--base-url`。Cookie、密码及 CSRF 仅在进程内使用，结束时发起退出登录。
+
+```sh
+owned-pool login
+owned-pool clients
+owned-pool accounts
+owned-pool candidates --client 12 --kind post --subreddit example --group current --weight 5
+```
+
+## 完整参数录入
+
+以下 ID 和内容为占位示例。脚本调用需要预先设置登录环境变量。
+
+```sh
+owned-pool post create --client 12 --account account-opaque-id --subreddit example --group current --weight 5 --purpose external_original --title "帖子标题" --body-file ./post.md --retention-hours 24 --notes "内部说明" --draft --non-interactive --json
+
+owned-pool comment create --client 12 --account account-opaque-id --target-url "https://www.reddit.com/r/example/comments/abc123/topic/" --group pool --weight 5 --body-file ./comment.md --retention-hours 48 --draft --non-interactive --json
+```
+
+客户支持 ID、唯一名称和编号。账号支持完整字符串 ID、唯一显示名和 Reddit 用户名。社区支持 `r/` 前缀，留存支持 `24/48/72/168/720` 小时，权重支持 `5/10/20/30`。帖子用途支持 `external_original/community_internal`，账号来源支持 `current/pool`。
+
+`--non-interactive` 缺少必要值会返回 `MISSING_INPUT` 和字段、可用选项。成功结果写入 stdout，错误和更新提醒写入 stderr，错误退出码为 1，用户中断为 130。`--json` 输出紧凑 JSON，`--dry-run` 输出录入方案。
+
+## 任务管理
+
+```sh
+owned-pool tasks list --view mine --page 1
+owned-pool tasks show 123
+owned-pool tasks edit 123 --body-file ./updated.md --draft
+owned-pool tasks submit 123
+```
+
+编辑保留已有素材及可编辑的跟帖，写入携带任务版本。新增录入支持文本原稿，图片可通过系统网页补充。
+
+写入失败时返回任务 ID 和本地恢复文件路径。该文件包含原稿内容，保存在用户目录 `.owned-account-pool/recovery`。使用返回的恢复命令继续操作，成功后自动清理。
+
+```sh
+owned-pool tasks resume "/完整路径/example.recovery.json"
+```
+
+创建请求超时、结果未知时，先查询 `tasks list` 确认对应记录，再通过 `--task-id` 恢复。版本冲突时，先读取最新任务并合并修改。
+
+## 配套 skill 与更新
+
+```sh
+owned-pool skill install --agent codex
+owned-pool skill install --agent claude
+owned-pool skill path
+owned-pool update-check
+owned-pool update-check --json
+```
+
+skill 随包发布，可安装到 Codex、Claude Code，也可用 `skill install --dir <目录>` 指定目标。它指导 AI 查询候选项、向用户补齐缺失数据、录入任务和处理恢复文件。
+
+每次业务命令都会并行检查 npm 最新版本，超时为 1.5 秒。有新版本时提示更新命令，相同版本、较旧版本或检查失败时静默继续。检查会在当前命令结束时输出提醒。独立 `update-check` 在没有新版本时保持安静，`--json` 可查看检查结果。
+
+```sh
+npm install -g owned-account-pool-cli@latest
+owned-pool skill install --agent codex
+```
+
+## 本地开发
+
+```sh
+npm ci
+npm test
+node bin/owned-pool.js --help
+npm pack --dry-run
+```
+
+接口依据本目录 2026-11-11 的 API 文档及站点前端调用。测试覆盖模拟服务的认证、CSRF、录入、分页选择、版本冲突、恢复、更新提示和 CLI 入口。

package/bin/owned-pool.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+await main();

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "owned-account-pool-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "自有账号池 CLI，交互登录、客户与账号选择、帖子和评论任务录入",
+  "type": "module",
+  "bin": {
+    "owned-pool": "bin/owned-pool.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "skills/"
+  ],
+  "scripts": {
+    "start": "node bin/owned-pool.js",
+    "test": "node --test",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": "^24.15.0 || >=26.0.0"
+  },
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "8.8.0",
+    "commander": "15.1.0",
+    "semver": "7.8.6",
+    "tough-cookie": "6.1.0"
+  }
+}

package/skills/owned-account-pool/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: owned-account-pool
+description: 使用 owned-pool CLI 查询自有账号池、客户和登记任务，录入或编辑帖子与评论原稿，提交给发布人员，并在 npm 包有新版本时提醒用户。适用于 handover.luckyjun.top 自有账号发布系统。
+---
+
+# 自有账号池 CLI
+
+使用 npm 包 `owned-account-pool-cli` 提供的 `owned-pool` 命令。需要 Node.js 24 LTS（24.15.0 起）或 26 及以上版本。系统默认地址为 `https://handover.luckyjun.top`，其他部署可通过 `--base-url` 或 `HANDOVER_BASE_URL` 指定。
+
+## 安装与版本检查
+
+先运行 `owned-pool --version`。命令缺失时按用户安装授权运行 `npm install -g owned-account-pool-cli`，或用 `npx --yes --package owned-account-pool-cli owned-pool` 执行。
+
+每次开始处理本系统的新请求时运行 `owned-pool update-check --json`。只有 `update_available=true` 时，向用户说明当前版本、最新版本和 `update_command`。检查结果相同、当前版本更新、网络检查失败时静默继续。业务命令也会在 stderr 输出 `[UPDATE_AVAILABLE]`，同一轮对话已经提醒过相同版本时合并提示。更新由用户授权后执行。
+
+升级后可运行 `owned-pool skill install --agent codex` 更新本机配套 skill。Claude Code 使用 `--agent claude`。
+
+## 登录与缺失信息
+
+业务命令每次运行均需要登录账号与密码。交互终端会询问缺失值并隐藏密码输入。脚本调用通过 `HANDOVER_USERNAME` 和 `HANDOVER_PASSWORD` 环境变量提供凭据，账号也可用 `--username`。会话仅保存在当前进程，命令结束后退出。
+
+用户尚未提供凭据时询问用户。通过执行环境传入密码，避免在可见命令、日志和交付文件中展示密码。自动化调用使用 `--non-interactive --json`，成功结果在 stdout，错误 JSON 在 stderr。缺失数据的 `error.code` 为 `MISSING_INPUT`，`field` 和 `choices` 提供补全线索。根据缺失字段询问用户，并复用此前已给出的信息。
+
+选择客户、账号、社区、留存时间或提交方式时，以用户已明确提供的数据为准。缺少选择就询问用户。客户和账号可以用 ID 或唯一名称定位，同名时使用 ID。账号 ID 保持完整字符串。
+
+## 查询与录入
+
+使用 `owned-pool --help` 或子命令的 `--help` 查看当前参数。
+
+```sh
+owned-pool login
+owned-pool clients --json
+owned-pool accounts --json
+owned-pool candidates --client 12 --kind post --subreddit example --group current --weight 5 --json
+owned-pool tasks list --view mine --json
+owned-pool tasks show 123 --json
+```
+
+在交互终端运行 `owned-pool` 可进入菜单，`owned-pool post create` 和 `owned-pool comment create` 会询问缺失数据。AI 自动化应先查询客户和候选账号，把可用选项提供给用户，再带齐参数执行录入。
+
+帖子录入示例中所有业务值都需要替换为用户确认的数据。
+
+```sh
+owned-pool post create --client 12 --account account-opaque-id --subreddit example --group current --weight 5 --purpose external_original --title "标题" --body-file ./post.md --retention-hours 24 --notes "内部备注" --draft --non-interactive --json
+```
+
+评论使用回复目标 URL，CLI 从服务端解析目标社区并以 `account_mode=owned` 选择自有账号。
+
+```sh
+owned-pool comment create --client 12 --account account-opaque-id --target-url "https://www.reddit.com/r/example/comments/abc123/topic/" --group pool --weight 5 --body-file ./comment.md --retention-hours 48 --draft --non-interactive --json
+```
+
+- `--group` 取 `current` 客户账号或 `pool` 公用账号池。
+- `--weight` 取 `5`、`10`、`20`、`30`。
+- 帖子用途 `--purpose` 取 `external_original` 或 `community_internal`。
+- 留存 `--retention-hours` 取 `24`、`48`、`72`、`168`、`720` 小时。
+- `--draft` 保存草稿，`--submit` 保存后提交给发布人员。依据用户要求选择，缺少要求时询问。
+- 长正文、多行内容使用 UTF-8 的 `--body-file`。可选备注在非交互模式下省略即为空。
+- `--dry-run` 用于检查收集完成的录入方案。它包含登录和只读查询。
+
+成功结果包含 `task_id`、`status`、`version`。向用户汇报任务 ID 与状态。此工作流记录系统任务，Reddit 实际发布由发布人员执行。
+
+## 编辑、提交与恢复
+
+```sh
+owned-pool tasks edit 123 --body-file ./updated.md --draft --non-interactive --json
+owned-pool tasks submit 123 --non-interactive --json
+owned-pool tasks resume "恢复文件的完整路径" --non-interactive --json
+```
+
+编辑保留原稿现有素材和可编辑跟帖，使用读取时的任务版本。出现 `VERSION_CONFLICT` 时读取最新任务，结合用户要求合并修改后再次保存。
+
+录入分为创建任务和保存原稿。写入中断时，错误中包含 `recovery_file` 和 `next_command`。优先恢复既有任务。创建请求结果未知时，先查 `tasks list`，找到对应任务，再使用 `tasks resume ... --task-id ID`。恢复文件保存在用户目录 `.owned-account-pool/recovery`，含录入正文，成功恢复后清理。
+
+本 CLI 覆盖账号查询与任务登记流程。客户绑定、账号资格等服务端配置问题按接口错误提示处理。

package/src/api.js

@@ -0,0 +1,133 @@
+import { CookieJar } from 'tough-cookie';
+import { CliError, assert } from './errors.js';
+
+export const DEFAULT_BASE_URL = 'https://handover.luckyjun.top';
+
+export class ApiClient {
+  constructor(baseUrl = DEFAULT_BASE_URL, { timeout = 30000, fetchImpl = fetch } = {}) {
+    const url = new URL(baseUrl);
+    assert(['https:', 'http:'].includes(url.protocol) && !url.username && !url.password,
+      'INVALID_BASE_URL', '服务地址须为 HTTP(S) 地址，且不含账号密码。');
+    assert(url.pathname === '/' && !url.search && !url.hash,
+      'INVALID_BASE_URL', '服务地址只填写站点根地址，例如 https://handover.luckyjun.top');
+    this.baseUrl = url.origin;
+    this.timeout = timeout;
+    this.fetchImpl = fetchImpl;
+    this.jar = new CookieJar();
+    this.csrf = null;
+    this.member = null;
+    this.loggedIn = false;
+  }
+
+  async request(method, path, { query = {}, body, timeout = this.timeout } = {}) {
+    assert(path.startsWith('/api/'), 'INVALID_PATH', '接口路径须以 /api/ 开头。');
+    const url = new URL(path, this.baseUrl);
+    assert(url.origin === this.baseUrl, 'INVALID_PATH', '接口路径必须属于当前服务。');
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, value);
+    }
+    const headers = { Accept: 'application/json' };
+    const cookie = await this.jar.getCookieString(url.href);
+    if (cookie) headers.Cookie = cookie;
+    if (body !== undefined) headers['Content-Type'] = 'application/json';
+    if (!['GET', 'HEAD', 'OPTIONS'].includes(method) && this.csrf) {
+      headers['X-CSRF-Token'] = this.csrf;
+    }
+    let response;
+    let text;
+    try {
+      response = await this.fetchImpl(url, {
+        method, headers, body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: 'manual', signal: AbortSignal.timeout(timeout),
+      });
+      for (const cookieValue of response.headers.getSetCookie()) {
+        await this.jar.setCookie(cookieValue, url.href);
+      }
+      text = await response.text();
+    } catch (error) {
+      const code = ['TimeoutError', 'AbortError'].includes(error.name) ? 'REQUEST_TIMEOUT' : 'NETWORK_ERROR';
+      throw new CliError(code, `${method} ${url.pathname} 请求未完成，请检查连接和服务状态。`, {
+        method, path: url.pathname, outcome_unknown: method !== 'GET',
+      });
+    }
+    let data;
+    try {
+      data = text ? JSON.parse(text) : null;
+    } catch {
+      throw new CliError('INVALID_RESPONSE', `接口返回了非 JSON 数据（HTTP ${response.status}）。`, {
+        status: response.status, path: url.pathname, outcome_unknown: method !== 'GET',
+      });
+    }
+    if (!response.ok) {
+      const error = data?.error;
+      let message = error?.message || `接口请求失败（HTTP ${response.status}）。`;
+      if (body?.password) message = message.replaceAll(body.password, '[REDACTED]');
+      throw new CliError(error?.code || `HTTP_${response.status}`,
+        message, {
+          status: response.status, path: url.pathname,
+          ...(!body?.password && error?.details?.fields ? { fields: error.details.fields } : {}),
+        });
+    }
+    return data;
+  }
+
+  async login(username, password) {
+    const result = await this.request('POST', '/api/community-workbench/auth/login', {
+      body: { username, password },
+    });
+    this.loggedIn = true;
+    this.csrf = result?.csrf;
+    let identity = result;
+    if (!this.csrf) {
+      identity = await this.request('GET', '/api/community-workbench/auth/me');
+      this.csrf = identity?.csrf;
+    }
+    assert(this.csrf, 'MISSING_CSRF', '登录响应缺少 CSRF，请检查服务端认证接口。');
+    this.member = identity.member || result.member;
+    return this.member;
+  }
+
+  async logout() {
+    try {
+      if (this.loggedIn) {
+        await this.request('POST', '/api/community-workbench/auth/logout', { timeout: 3000 });
+      }
+    } finally {
+      this.loggedIn = false;
+      this.csrf = null;
+      this.member = null;
+      await this.jar.removeAllCookies();
+    }
+  }
+}
+
+export function itemsOf(data, key = 'items') {
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.[key])) return data[key];
+  if (Array.isArray(data?.items)) return data.items;
+  throw new CliError('INVALID_RESPONSE', '接口列表格式与预期不符。');
+}
+
+export async function allPages(api, path, query = {}, key = 'items') {
+  const results = [];
+  const seen = new Set();
+  for (let page = 1; ; page += 1) {
+    const data = await api.request('GET', path, { query: { ...query, page } });
+    const items = itemsOf(data, key);
+    let added = 0;
+    for (const item of items) {
+      const id = String(item.id ?? item.account_id ?? JSON.stringify(item));
+      if (!seen.has(id)) {
+        seen.add(id);
+        results.push(item);
+        added += 1;
+      }
+    }
+    if (Array.isArray(data) || !items.length) break;
+    if (data.total_pages !== undefined && page >= Number(data.total_pages)) break;
+    if (data.total !== undefined && results.length >= Number(data.total)) break;
+    if (!added) throw new CliError('INVALID_PAGINATION', '分页重复返回相同记录，无法读取完整列表。');
+    if (data.total_pages === undefined && data.total === undefined) break;
+  }
+  return results;
+}

package/src/cli.js

@@ -0,0 +1,216 @@
+import { Command } from 'commander';
+import { ApiClient, DEFAULT_BASE_URL } from './api.js';
+import { Questions, positiveInteger } from './prompts.js';
+import { CliError } from './errors.js';
+import { candidateQuery, candidates, chooseClient, executePlan, getTask, prepareCreate,
+  prepareEdit, resumePlan, submitTask, taskClients } from './tasks.js';
+import { checkUpdate, packageInfo, updateNotice } from './update.js';
+import { installSkill, skillDirectory } from './skill.js';
+
+function redact(value) {
+  if (Array.isArray(value)) return value.map(redact);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.entries(value).filter(([key]) =>
+      !/^(password|csrf|cookie|session|token|access_token|refresh_token|authorization)$/i.test(key))
+      .map(([key, item]) => [key, redact(item)]));
+  }
+  return value;
+}
+
+function print(value, options) {
+  process.stdout.write(JSON.stringify(redact(value), null, options.json ? undefined : 2) + '\n');
+}
+
+async function session(options, handler) {
+  const update = checkUpdate();
+  const questions = new Questions(options);
+  let api;
+  try {
+    const username = await questions.text('username', '系统登录账号', options.username || process.env.HANDOVER_USERNAME || undefined);
+    const password = await questions.text('password', '系统登录密码', process.env.HANDOVER_PASSWORD || undefined, { secret: true });
+    api = new ApiClient(options.baseUrl ?? process.env.HANDOVER_BASE_URL ?? DEFAULT_BASE_URL);
+    await api.login(username.trim(), password);
+    return await handler(api, questions);
+  } finally {
+    if (api?.loggedIn) {
+      try {
+        await api.logout();
+      } catch {
+        process.stderr.write('会话退出请求未完成，本地会话已清理。\n');
+      }
+    }
+    process.stderr.write(updateNotice(await update));
+  }
+}
+
+function authenticated(command, handler) {
+  command.action(async (...args) => {
+    const current = args.at(-1);
+    const options = current.optsWithGlobals();
+    const result = await session(options, (api, questions) => handler(api, questions, options, ...args.slice(0, -2)));
+    print(result, options);
+  });
+  return command;
+}
+
+function contentOptions(command) {
+  return command.option('--body <text>', '正文 Markdown')
+    .option('--body-file <file>', '从 UTF-8 文件读取正文')
+    .option('--notes <text>', '内部备注，可传空字符串')
+    .option('--retention-hours <hours>', '留存小时数 24/48/72/168/720')
+    .option('--draft', '保存为草稿')
+    .option('--submit', '保存后提交给发布人员');
+}
+
+function accountOptions(command) {
+  return command.option('--account <id-or-name>', '账号 ID、显示名或 Reddit 用户名')
+    .option('--subreddit <name>', '社区名称，支持 r/ 前缀')
+    .option('--group <group>', '账号来源 current/pool')
+    .option('--weight <number>', '社区权重阈值 5/10/20/30');
+}
+
+async function listTasks(api, options = {}) {
+  return api.request('GET', '/api/tasks', { query: {
+    page: positiveInteger(options.page || 1, '页码'), view: options.view || 'mine',
+    client_id: options.clientId && positiveInteger(options.clientId, '客户 ID'),
+    task_type: options.type, status: options.status, q: options.search,
+  } });
+}
+
+async function menu(api, questions, options) {
+  for (;;) {
+    const action = await questions.choice('action', '选择操作', undefined, [
+      { name: '录入帖子', value: 'post' },
+      { name: '录入独立评论', value: 'comment' },
+      { name: '查看客户', value: 'clients' },
+      { name: '查看账号', value: 'accounts' },
+      { name: '查看我的任务', value: 'tasks' },
+      { name: '编辑任务原稿', value: 'edit' },
+      { name: '提交任务', value: 'submit' },
+      { name: '退出', value: 'exit' },
+    ]);
+    if (action === 'exit') return { logged_out: true };
+    try {
+      let result;
+      if (['post', 'comment'].includes(action)) {
+        result = await executePlan(api, await prepareCreate(api, questions, action, {}), { dryRun: options.dryRun });
+      } else if (action === 'clients') {
+        result = await taskClients(api);
+      } else if (action === 'accounts') {
+        result = await api.request('GET', '/api/accounts');
+      } else if (action === 'tasks') {
+        result = await listTasks(api);
+      } else {
+        const id = await questions.text('task-id', '任务 ID', undefined);
+        result = action === 'edit'
+          ? await executePlan(api, await prepareEdit(api, questions, id, {}), { dryRun: options.dryRun })
+          : await submitTask(api, await getTask(api, id), options.dryRun);
+      }
+      print(result, options);
+    } catch (error) {
+      if (error.details?.status === 401 || error.name === 'ExitPromptError') throw error;
+      printError(error, options);
+    }
+  }
+}
+
+function printError(error, options) {
+  const result = { error: { code: error.code || 'ERROR', message: error.message, ...error.details } };
+  process.stderr.write(JSON.stringify(redact(result), null, options.json ? undefined : 2) + '\n');
+}
+
+export function buildProgram({ jsonOutput = false } = {}) {
+  const program = new Command().name('owned-pool').version(packageInfo.version)
+    .description('自有账号池 CLI，登录后交互录入帖子、评论并管理登记任务。')
+    .option('--base-url <url>', '系统根地址，默认 HANDOVER_BASE_URL 或 https://handover.luckyjun.top')
+    .option('--username <username>', '系统登录名，也可设置 HANDOVER_USERNAME')
+    .option('--non-interactive', '脚本模式，缺失数据以 MISSING_INPUT 返回')
+    .option('--json', '机器可读 JSON 输出，提示与错误写入 stderr')
+    .option('--dry-run', '收集并预览录入请求')
+    .showHelpAfterError();
+  program.exitOverride();
+  if (jsonOutput) program.configureOutput({ writeErr: () => {} });
+  authenticated(program, menu);
+  authenticated(program.command('login').description('验证账号密码及当前身份'), async api => ({
+    authenticated: true, member: api.member,
+  }));
+  authenticated(program.command('clients').description('列出任务客户'), taskClients);
+  authenticated(program.command('accounts').description('列出账号池'), api => api.request('GET', '/api/accounts'));
+  authenticated(accountOptions(program.command('candidates').description('查询指定客户与社区的候选账号'))
+    .option('--client <id-or-name>', '客户 ID、名称或编号')
+    .option('--kind <kind>', 'post/comment'), async (api, questions, options) => {
+    const client = await chooseClient(api, questions, options.client);
+    const kind = await questions.choice('kind', '内容类型', options.kind, [
+      { name: '帖子', value: 'post' }, { name: '评论', value: 'comment' },
+    ]);
+    return candidates(api, client.id, kind, await candidateQuery(questions, options));
+  });
+  for (const kind of ['post', 'comment']) {
+    const group = program.command(kind).description(kind === 'post' ? '帖子录入' : '独立评论录入');
+    const create = accountOptions(contentOptions(group.command('create').description('选择客户、账号并录入任务')))
+      .option('--client <id-or-name>', '客户 ID、名称或编号');
+    if (kind === 'post') create.option('--title <text>', '帖子标题').option('--purpose <purpose>', 'external_original/community_internal');
+    if (kind === 'comment') create.option('--target-url <url>', '回复的帖子或评论链接').option('--target-context <text>', '目标原文摘录');
+    authenticated(create, async (api, questions, options) =>
+      executePlan(api, await prepareCreate(api, questions, kind, options), { dryRun: options.dryRun }));
+  }
+  const tasks = program.command('tasks').description('任务查询、原稿编辑、提交与失败恢复');
+  authenticated(tasks.command('list').description('分页查询任务')
+    .option('--page <number>', '页码', '1').option('--view <view>', 'mine/all', 'mine')
+    .option('--client-id <id>', '客户 ID').option('--type <type>', 'post/comment/followup')
+    .option('--status <status>', '任务状态').option('--search <text>', '搜索关键词'),
+  (api, questions, options) => listTasks(api, options));
+  authenticated(tasks.command('show [id]').description('查询任务详情'), async (api, questions, options, id) =>
+    getTask(api, await questions.text('task-id', '任务 ID', id)));
+  authenticated(accountOptions(contentOptions(tasks.command('edit [id]').description('编辑原稿，保留现有素材及跟帖')))
+    .option('--title <text>', '修改帖子标题').option('--target-context <text>', '目标原文摘录'),
+  async (api, questions, options, id) => executePlan(api, await prepareEdit(api, questions,
+    await questions.text('task-id', '任务 ID', id), options), { dryRun: options.dryRun }));
+  authenticated(tasks.command('submit [id]').description('将现有原稿提交给发布人员'), async (api, questions, options, id) =>
+    submitTask(api, await getTask(api, await questions.text('task-id', '任务 ID', id)), options.dryRun));
+  authenticated(tasks.command('resume [file]').description('根据恢复文件继续未完成录入')
+    .option('--task-id <id>', '创建结果未知时，指定已创建的任务 ID'),
+  async (api, questions, options, file) => resumePlan(api, questions,
+    await questions.text('recovery-file', '恢复文件路径', file), options));
+  program.command('update-check').description('检查 npm 更新，发现新版本时提醒').action(async (_options, command) => {
+    const result = await checkUpdate();
+    if (command.optsWithGlobals().json) print(result, { json: true });
+    else process.stdout.write(updateNotice(result));
+  });
+  const skill = program.command('skill').description('配套 AI skill');
+  skill.command('path').description('输出 npm 包内的 skill 路径').action(() => process.stdout.write(skillDirectory + '\n'));
+  skill.command('install').description('安装或更新配套 skill')
+    .option('--agent <agent>', 'codex/claude').option('--dir <directory>', '自定义 skill 目标目录')
+    .action(async (_options, command) => {
+      const options = command.optsWithGlobals();
+      const questions = new Questions(options);
+      const agent = options.dir ? undefined : await questions.choice('agent', '安装到哪个 AI 工具', options.agent, [
+        { name: 'Codex', value: 'codex' }, { name: 'Claude Code', value: 'claude' },
+      ]);
+      print(await installSkill(agent, options.dir), options);
+    });
+  return program;
+}
+
+export async function main(argv = process.argv) {
+  const jsonOutput = argv.includes('--json');
+  const program = buildProgram({ jsonOutput });
+  try {
+    await program.parseAsync(argv);
+  } catch (error) {
+    if (['commander.helpDisplayed', 'commander.help', 'commander.version'].includes(error.code)) return;
+    if (error.name === 'ExitPromptError') {
+      process.stderr.write('已取消。\n');
+      process.exitCode = 130;
+      return;
+    }
+    if (error.code?.startsWith('commander.')) {
+      if (jsonOutput) printError(error, { json: true });
+      process.exitCode = error.exitCode || 1;
+      return;
+    }
+    if (!(error instanceof CliError)) error = new CliError('LOCAL_ERROR', error.message);
+    printError(error, program.opts());
+    process.exitCode = 1;
+  }
+}

package/src/errors.js

@@ -0,0 +1,12 @@
+export class CliError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function assert(condition, code, message, details) {
+  if (!condition) throw new CliError(code, message, details);
+}

package/src/prompts.js

@@ -0,0 +1,106 @@
+import { input, password, select, search, editor } from '@inquirer/prompts';
+import { readFile } from 'node:fs/promises';
+import { assert } from './errors.js';
+
+export class Questions {
+  constructor({ nonInteractive = false, interactive = process.stdin.isTTY && process.stderr.isTTY } = {}) {
+    this.interactive = Boolean(interactive && !nonInteractive);
+    this.context = { input: process.stdin, output: process.stderr };
+  }
+
+  requireInteractive(field, message, choices) {
+    assert(this.interactive, 'MISSING_INPUT', `缺少${message}。请在终端交互输入，或提供对应参数。`, {
+      field, ...(choices ? { choices } : {}),
+    });
+  }
+
+  async text(field, message, value, { optional = false, max = Infinity, secret = false, defaultValue } = {}) {
+    const validate = candidate => {
+      if (!optional && !candidate.trim()) return '请输入内容。';
+      if (candidate.length > max) return `最多 ${max} 个字符。`;
+      return true;
+    };
+    if (value !== undefined && value !== null) {
+      const problem = validate(String(value));
+      assert(problem === true, 'INVALID_INPUT', `${message}填写有误。${problem === true ? '' : problem}`, { field });
+      return String(value);
+    }
+    if (optional && !this.interactive) return defaultValue ?? '';
+    this.requireInteractive(field, message);
+    const ask = secret ? password : input;
+    return ask({ message, validate, ...(secret ? { mask: '*' } : { default: defaultValue }) }, this.context);
+  }
+
+  async choice(field, message, value, choices, defaultValue) {
+    if (value !== undefined && value !== null) {
+      const match = choices.find(item => String(item.value) === String(value));
+      assert(match && !match.disabled, 'INVALID_INPUT', `${message}选项无效。`, {
+        field, choices: choices.filter(item => !item.disabled).map(item => item.value),
+      });
+      return match.value;
+    }
+    this.requireInteractive(field, message, choices.filter(item => !item.disabled).map(item => item.value));
+    return select({ message, choices, default: defaultValue }, this.context);
+  }
+
+  async record(field, message, value, records, { id, name, aliases = () => [], disabled = () => false }) {
+    assert(records.length, 'NO_OPTIONS', `${message}时没有可用记录，请先在系统中补齐数据。`, { field });
+    const choices = records.map(record => ({
+      name: name(record), value: record, disabled: disabled(record),
+    }));
+    if (value !== undefined && value !== null) {
+      const exact = records.filter(record => String(id(record)) === String(value));
+      const matches = exact.length ? exact : records.filter(record => aliases(record)
+        .some(alias => String(alias).toLowerCase() === String(value).toLowerCase()));
+      if (matches.length === 1) {
+        const reason = disabled(matches[0]);
+        assert(!reason, 'UNAVAILABLE_SELECTION', String(reason), { field });
+        return matches[0];
+      }
+      assert(matches.length, 'SELECTION_NOT_FOUND', `${message}中找不到指定记录。`, { field, value });
+      this.requireInteractive(field, `${message}（存在同名记录，请按 ID 选择）`, matches.map(id));
+      return select({ message, choices: choices.filter(item => matches.includes(item.value)) }, this.context);
+    }
+    assert(choices.some(item => !item.disabled), 'NO_OPTIONS', `${message}时所有记录均不可用。`, { field });
+    this.requireInteractive(field, message, records.map(record => ({ id: id(record), name: name(record) })));
+    return search({
+      message: `${message}（可输入关键词搜索）`, pageSize: 12,
+      source: term => choices.filter(item => item.name.toLowerCase().includes((term || '').toLowerCase())),
+    }, this.context);
+  }
+
+  async body(value, file, defaultValue) {
+    assert(!(value !== undefined && file), 'INVALID_INPUT', '--body 与 --body-file 只能选择一项。');
+    if (file) value = await readFile(file, 'utf8');
+    if (value !== undefined) return this.text('body', '正文', value, { max: 40000 });
+    this.requireInteractive('body', '正文（--body 或 --body-file）');
+    const mode = await this.choice('body-mode', '正文输入方式', undefined, [
+      { name: '输入一段文字', value: 'input' },
+      { name: '读取 UTF-8 / Markdown 文件', value: 'file' },
+      { name: '打开系统编辑器，编辑多行正文', value: 'editor' },
+    ]);
+    if (mode === 'file') {
+      const path = await this.text('body-file', '正文文件路径', undefined);
+      return this.body(undefined, path.trim().replace(/^"|"$/g, ''));
+    }
+    if (mode === 'editor') {
+      return editor({
+        message: '编辑正文并保存退出', default: defaultValue ?? '', postfix: '.md',
+        validate: content => content.trim() && content.length <= 40000 ? true : '正文须为 1–40000 个字符。',
+      }, this.context);
+    }
+    return this.text('body', '正文', undefined, { max: 40000, defaultValue });
+  }
+}
+
+export function positiveInteger(value, label = 'ID') {
+  assert(/^\d+$/.test(String(value)) && Number.isSafeInteger(Number(value)) && Number(value) > 0,
+    'INVALID_INPUT', `${label}须为正整数。`);
+  return Number(value);
+}
+
+export function normalizeSubreddit(value) {
+  const result = value.trim().replace(/^\/?r\//i, '').replace(/\/$/, '').toLowerCase();
+  assert(/^[a-z0-9_]{1,50}$/.test(result), 'INVALID_INPUT', '请填写社区名称，例如 r/example。');
+  return result;
+}

package/src/skill.js

@@ -0,0 +1,18 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+export const skillDirectory = fileURLToPath(new URL('../skills/owned-account-pool/', import.meta.url));
+
+export async function installSkill(agent, directory) {
+  const roots = {
+    codex: join(process.env.CODEX_HOME || join(homedir(), '.codex'), 'skills'),
+    claude: join(homedir(), '.claude', 'skills'),
+  };
+  const destination = resolve(directory || join(roots[agent], 'owned-account-pool'));
+  await mkdir(destination, { recursive: true });
+  const text = await readFile(join(skillDirectory, 'SKILL.md'), 'utf8');
+  await writeFile(join(destination, 'SKILL.md'), text, 'utf8');
+  return { installed: true, path: destination };
+}

package/src/tasks.js

@@ -0,0 +1,276 @@
+import { readFile, mkdir, writeFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { isDeepStrictEqual } from 'node:util';
+import { allPages, itemsOf } from './api.js';
+import { CliError, assert } from './errors.js';
+import { normalizeSubreddit, positiveInteger } from './prompts.js';
+
+const PURPOSES = [
+  { name: '外部原创', value: 'external_original' },
+  { name: '社区内部', value: 'community_internal' },
+];
+const RETENTION = [24, 48, 72, 168, 720].map(value => ({ name: `${value} 小时`, value }));
+const WEIGHTS = [5, 10, 20, 30].map(value => ({ name: String(value), value }));
+const GROUPS = [
+  { name: '客户账号', value: 'current' },
+  { name: '公用账号池', value: 'pool' },
+];
+
+function taskOf(result) {
+  const task = result?.task ?? result;
+  assert(task?.id !== undefined && Number.isInteger(task.version),
+    'INVALID_RESPONSE', '任务响应缺少 id 或 version。');
+  return task;
+}
+
+export async function getTask(api, id) {
+  return taskOf(await api.request('GET', `/api/tasks/${positiveInteger(id, '任务 ID')}`));
+}
+
+export async function taskClients(api) {
+  return itemsOf(await api.request('GET', '/api/tasks/clients'), 'clients');
+}
+
+export async function chooseClient(api, questions, value) {
+  return questions.record('client', '选择客户', value, await taskClients(api), {
+    id: item => item.id,
+    name: item => `${item.name} [${item.id}]${item.code ? ` · ${item.code}` : ''}`,
+    aliases: item => [item.name, item.code].filter(Boolean),
+    disabled: item => item.is_archived ? '客户已归档' :
+      ('upstream_client_id' in item && !item.upstream_client_id ? '客户等待管理员绑定上游客户' : false),
+  });
+}
+
+export async function candidateQuery(questions, options, subreddit) {
+  return {
+    subreddit: normalizeSubreddit(await questions.text('subreddit', '目标社区', subreddit ?? options.subreddit)),
+    group: await questions.choice('group', '账号来源', options.group, GROUPS, 'current'),
+    weight: await questions.choice('weight', '账号社区权重阈值', options.weight, WEIGHTS, 5),
+  };
+}
+
+export async function candidates(api, clientId, kind, query) {
+  return allPages(api, '/api/tasks/candidates', { client_id: clientId, kind, ...query });
+}
+
+async function chooseCandidate(api, questions, options, clientId, kind, subreddit) {
+  const query = await candidateQuery(questions, options, subreddit);
+  const accounts = await candidates(api, clientId, kind, query);
+  const account = await questions.record('account', '选择账号', options.account, accounts, {
+    id: item => item.id,
+    name: item => `${item.display_name || item.id} · u/${item.reddit_username || '?'} [${item.id}]` +
+      (item.unavailable_reason ? ` · ${item.unavailable_reason}` : ''),
+    aliases: item => [item.display_name, item.reddit_username, `u/${item.reddit_username}`].filter(Boolean),
+    disabled: item => !item.selectable ? item.unavailable_reason || '账号当前不可用' : false,
+  });
+  return { account_id: String(account.id), subreddit: query.subreddit, weight: query.weight };
+}
+
+async function submissionChoice(questions, options) {
+  assert(!(options.submit && options.draft), 'INVALID_INPUT', '--submit 与 --draft 只能选择一项。');
+  let mode;
+  if (options.submit) mode = 'submit';
+  if (options.draft) mode = 'draft';
+  return questions.choice('mode', '录入完成后', mode, [
+    { name: '保存为草稿', value: 'draft' },
+    { name: '提交给发布人员', value: 'submit' },
+  ], 'draft');
+}
+
+export async function prepareCreate(api, questions, kind, options) {
+  const client = await chooseClient(api, questions, options.client);
+  let target;
+  if (kind === 'comment') {
+    const url = await questions.text('target-url', '回复目标帖子或评论 URL', options.targetUrl);
+    target = await api.request('GET', '/api/tasks/target', { query: { url: url.trim() } });
+    assert(target?.url && target?.subreddit, 'INVALID_RESPONSE', '回复目标解析缺少 url 或 subreddit。');
+    if (options.subreddit) {
+      assert(normalizeSubreddit(options.subreddit) === normalizeSubreddit(target.subreddit),
+        'INVALID_INPUT', '指定社区与回复目标所属社区不一致。');
+    }
+  }
+  const purpose = kind === 'post'
+    ? await questions.choice('purpose', '帖子用途', options.purpose, PURPOSES) : null;
+  const candidate = await chooseCandidate(api, questions, options, client.id, kind, target?.subreddit);
+  const title = kind === 'post'
+    ? await questions.text('title', '帖子标题', options.title, { max: 300 }) : '';
+  const body = await questions.body(options.body, options.bodyFile);
+  const notes = await questions.text('notes', '内部备注（可留空）', options.notes, { optional: true, max: 5000 });
+  const targetContext = kind === 'comment'
+    ? await questions.text('target-context', '目标原文摘录（可留空）', options.targetContext, { optional: true, max: 20000 }) : '';
+  const retention = await questions.choice('retention-hours', '留存要求', options.retentionHours, RETENTION);
+  const mode = await submissionChoice(questions, options);
+  const accountMode = kind === 'comment' ? { account_mode: 'owned' } : {};
+  return {
+    schema: 1, base_url: api.baseUrl, task_id: null, expected_version: null, mode,
+    create: {
+      client_id: positiveInteger(client.id, '客户 ID'), kind, parent_task_id: null,
+      follow_op: false, post_purpose: purpose, ...accountMode,
+      target_url: target?.url || '', candidates: [candidate],
+    },
+    registration: {
+      content: { title, body, notes, target_context: targetContext, assets: [] },
+      retention_hours: retention, ...accountMode, candidates: [candidate], followups: [],
+    },
+  };
+}
+
+export function editableFollowups(task, member) {
+  return (task.children || []).filter(child => ['draft', 'returned'].includes(child.status) &&
+    (member?.role === 'admin' || String(child.creator_id) === String(member?.id))).map(child => ({
+    id: child.id, version: child.version, content: child.source,
+    follow_op: child.follow_op, account_mode: child.account_mode,
+    candidates: (child.candidates || []).map(candidateFields), removed: Boolean(child.removed),
+  }));
+}
+
+function candidateFields(candidate) {
+  return { account_id: String(candidate.account_id), subreddit: candidate.subreddit, weight: candidate.weight };
+}
+
+export async function prepareEdit(api, questions, id, options) {
+  const task = await getTask(api, id);
+  assert(['draft', 'returned'].includes(task.status), 'INVALID_TASK_STATE', '原稿编辑适用于 draft 或 returned 任务。');
+  const content = { title: '', body: '', notes: '', target_context: '', assets: [], ...task.source };
+  if (task.kind === 'post' && (options.title !== undefined || !content.title)) {
+    content.title = await questions.text('title', '帖子标题', options.title, { max: 300 });
+  }
+  if (options.body !== undefined || options.bodyFile || !content.body || questions.interactive) {
+    content.body = await questions.body(options.body, options.bodyFile, content.body);
+  }
+  content.notes = await questions.text('notes', '内部备注（可留空）', options.notes, {
+    optional: true, max: 5000, defaultValue: content.notes,
+  });
+  if (options.targetContext !== undefined) {
+    content.target_context = await questions.text('target-context', '目标原文摘录', options.targetContext, {
+      optional: true, max: 20000,
+    });
+  }
+  let chosenCandidates = (task.candidates || []).map(candidateFields);
+  const needsCandidate = !chosenCandidates.length && (task.account_mode === 'owned' || task.kind === 'post');
+  const changesCandidate = ['account', 'subreddit', 'group', 'weight'].some(key => options[key] !== undefined);
+  if (changesCandidate || needsCandidate) {
+    const subreddit = task.kind === 'comment'
+      ? task.target?.subreddit || chosenCandidates[0]?.subreddit || options.subreddit
+      : options.subreddit || chosenCandidates[0]?.subreddit;
+    chosenCandidates = [await chooseCandidate(api, questions, options, task.client_id, task.kind, subreddit)];
+  }
+  return {
+    schema: 1, base_url: api.baseUrl, task_id: task.id, expected_version: task.version,
+    mode: await submissionChoice(questions, options),
+    registration: {
+      content,
+      retention_hours: await questions.choice('retention-hours', '留存要求',
+        options.retentionHours ?? task.retention_hours, RETENTION),
+      ...(task.kind === 'comment' && !task.parent_task_id ? { account_mode: task.account_mode } : {}),
+      candidates: chosenCandidates, followups: editableFollowups(task, api.member),
+    },
+  };
+}
+
+async function writeRecovery(path, plan) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, JSON.stringify(plan, null, 2), { mode: 0o600 });
+    await rename(temporary, path);
+  } finally {
+    await unlink(temporary).catch(() => {});
+  }
+}
+
+function registrationMatches(task, registration) {
+  const source = task.source || {};
+  const contentMatches = Object.entries(registration.content).every(([key, value]) =>
+    isDeepStrictEqual(source[key], value));
+  return contentMatches && task.retention_hours === registration.retention_hours &&
+    isDeepStrictEqual((task.candidates || []).map(candidateFields), registration.candidates) &&
+    (registration.account_mode === undefined || task.account_mode === registration.account_mode) &&
+    registration.followups.every(child => {
+      const current = task.children?.find(item => item.id === child.id);
+      return current && isDeepStrictEqual(current.source, child.content) &&
+        Boolean(current.removed) === child.removed && current.follow_op === child.follow_op &&
+        current.account_mode === child.account_mode &&
+        isDeepStrictEqual((current.candidates || []).map(candidateFields), child.candidates);
+    });
+}
+
+export async function submitTask(api, task, dryRun = false) {
+  assert(['draft', 'returned'].includes(task.status), 'INVALID_TASK_STATE', '可提交的原稿状态为 draft 或 returned。');
+  const body = {
+    version: task.version,
+    children: (task.children || []).filter(child => ['draft', 'returned'].includes(child.status))
+      .map(child => ({ id: child.id, version: child.version })),
+  };
+  if (dryRun) return { dry_run: true, method: 'POST', path: `/api/tasks/${task.id}/registration/submit`, body };
+  return taskOf(await api.request('POST', `/api/tasks/${task.id}/registration/submit`, { body }));
+}
+
+export async function executePlan(api, plan, { recoveryPath, recoveryDir, resume = false, dryRun = false } = {}) {
+  if (dryRun) return { dry_run: true, plan };
+  const directory = recoveryDir || join(homedir(), '.owned-account-pool', 'recovery');
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const path = recoveryPath || join(directory, `${randomUUID()}.recovery.json`);
+  let task;
+  try {
+    await writeRecovery(path, plan);
+    if (!plan.task_id) {
+      assert(!resume, 'MISSING_INPUT', '创建结果未知，请先查询任务列表，再通过 --task-id 指定已创建的任务。', { field: 'task-id' });
+      task = taskOf(await api.request('POST', '/api/tasks', { body: plan.create }));
+      plan.task_id = task.id;
+      plan.expected_version = task.version;
+      await writeRecovery(path, plan);
+    } else {
+      task = await getTask(api, plan.task_id);
+    }
+    if (plan.create) {
+      assert(task.client_id === plan.create.client_id && task.kind === plan.create.kind,
+        'RECOVERY_MISMATCH', '恢复任务的客户或类型与原录入内容不一致。');
+    }
+    const alreadySaved = registrationMatches(task, plan.registration);
+    if (!alreadySaved) {
+      assert(['draft', 'returned'].includes(task.status), 'INVALID_TASK_STATE', '任务当前状态不支持保存原稿。');
+      assert(task.version === plan.expected_version, 'VERSION_CONFLICT',
+        '任务版本已变化。录入内容保存在恢复文件中，请查询任务并合并修改。', { current_version: task.version });
+      task = taskOf(await api.request('PUT', `/api/tasks/${task.id}/registration`, {
+        body: { version: plan.expected_version, ...plan.registration },
+      }));
+      plan.expected_version = task.version;
+      await writeRecovery(path, plan);
+    }
+    if (plan.mode === 'submit' && ['draft', 'returned'].includes(task.status)) {
+      task = await submitTask(api, task);
+    }
+  } catch (error) {
+    if (!(error instanceof CliError)) error = new CliError('LOCAL_ERROR', error.message);
+    error.details = { ...error.details, task_id: plan.task_id, recovery_file: path,
+      next_command: `owned-pool tasks resume "${path}"` };
+    throw error;
+  }
+  try {
+    await unlink(path);
+  } catch {
+    return { task_id: task.id, status: task.status, version: task.version,
+      recovery_file: path, warning: '操作成功，恢复文件清理失败，可手动删除。' };
+  }
+  return { task_id: task.id, status: task.status, version: task.version };
+}
+
+export async function resumePlan(api, questions, file, options) {
+  const path = resolve(file);
+  const plan = JSON.parse(await readFile(path, 'utf8'));
+  assert(plan.schema === 1 && plan.registration?.content && Array.isArray(plan.registration.candidates) &&
+    Array.isArray(plan.registration.followups) && ['draft', 'submit'].includes(plan.mode),
+    'INVALID_RECOVERY', '恢复文件格式无效。');
+  assert(plan.base_url === api.baseUrl, 'RECOVERY_MISMATCH', '恢复文件所属服务与当前 --base-url 不一致。');
+  if (!plan.task_id) {
+    plan.task_id = positiveInteger(await questions.text('task-id',
+      '创建结果未知，请查询任务列表并填写对应任务 ID', options.taskId), '任务 ID');
+    const task = await getTask(api, plan.task_id);
+    assert(!task.source?.body || registrationMatches(task, plan.registration),
+      'RECOVERY_MISMATCH', '指定任务已有其他正文，请核对任务 ID 并通过 tasks edit 合并修改。');
+    plan.expected_version = task.version;
+  }
+  return executePlan(api, plan, { recoveryPath: path, resume: true, dryRun: options.dryRun });
+}

package/src/update.js

@@ -0,0 +1,26 @@
+import { readFile } from 'node:fs/promises';
+import semver from 'semver';
+
+export const packageInfo = JSON.parse(await readFile(new URL('../package.json', import.meta.url), 'utf8'));
+
+export async function checkUpdate({ fetchImpl = fetch, timeout = 1500 } = {}) {
+  const result = { package: packageInfo.name, current: packageInfo.version, checked: false, update_available: false };
+  try {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageInfo.name}/latest`, {
+      headers: { Accept: 'application/json' }, signal: AbortSignal.timeout(timeout), redirect: 'error',
+    });
+    if (!response.ok) return result;
+    const latest = (await response.json()).version;
+    if (!semver.valid(latest)) return result;
+    const available = semver.gt(latest, packageInfo.version);
+    return { ...result, checked: true, latest, update_available: available,
+      ...(available ? { update_command: `npm install -g ${packageInfo.name}@latest` } : {}) };
+  } catch {
+    return result;
+  }
+}
+
+export function updateNotice(result) {
+  if (!result.update_available) return '';
+  return `[UPDATE_AVAILABLE] ${result.package} ${result.current} → ${result.latest}\n请运行 ${result.update_command}\n`;
+}