@lyra-ai/toolkit 0.0.1

package/.env.example

@@ -0,0 +1,8 @@
+# 必需
+ZENTAO_URL=https://your-zentao.example.com
+ZENTAO_USERNAME=your-account
+ZENTAO_PASSWORD=your-password
+# 可选
+ZENTAO_DEFAULT_PROJECT=1
+ZENTAO_TOKEN_TTL=3600
+ZENTAO_LOG_LEVEL=info

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zentao-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @lyra-ai/toolkit
+
+面向 AI agent 的零依赖开发工具集。纯 JS（`.mjs`，Node 18+，无编译、无运行时依赖）。
+当前工具：**zentao**（禅道 REST v1）。预留 `log-query`、`skill-hub` 等扩展位。
+
+## 工程骨架
+```
+bin/zentao.mjs        # 命令入口（薄封装）→ src/zentao.mjs
+src/zentao.mjs        # zentao 工具逻辑
+src/shared/           # 预留：多工具共享底座（config/http/output/errors）
+test/*.test.mjs       # node:test，零测试依赖
+package.json          # bin 多命令声明
+.env.example          # 配置模板（占位符，无真实凭证）
+```
+新增工具：在 `bin/` 加入口、`src/` 加逻辑、`package.json` 的 `bin` 加一行。
+
+## 安装
+```bash
+npm install -g @lyra-ai/toolkit   # 发布后
+# 或本地开发：
+cd <本目录> && npm link            # 全局可用 zentao 命令
+```
+配置：复制 `.env.example` 为 `~/.zentao-cli/.env` 或 cwd `.env`，填 `ZENTAO_URL/USERNAME/PASSWORD`。
+或用 `zentao config set` 命令行管理配置，或 `zentao init` 向导式初始化。
+
+## 命令速查（agent 直接用）
+- `zentao ping` → `{"ok":true,"url":...}`
+- `zentao init` → 交互式向导（填 URL/用户/密码，末了验证连通性）
+- `zentao init --url <url> --username <u> --password <p> [--project <id>] [--ping]` → 非交互式（脚本/AI）
+- `zentao project list [--status active|closed|all] [--limit N] [--offset N]`
+- `zentao product list [--status active|closed|all] [--limit N] [--offset N]`
+- `zentao config` → 列出所有配置（密码脱敏为 `***`）
+- `zentao config get <key>` → 取单个值（密码需 `--raw` 才显原文）
+- `zentao config set <key> <value>` → 写入 `~/.zentao-cli/.env`
+- `zentao config unset <key>` → 删除配置项
+- `zentao config path` → 输出配置文件路径
+- `zentao bug list [--title <kw>] [--status S] [--severity 1-4] [--priority 1-4] [--assigned-to U] [--opened-by U] [--mine] [--product <ID|名称前缀>] [--project ID] [--start YYYY-MM-DD] [--end YYYY-MM-DD] [--order id_desc|...] [--limit N] [--offset N]` → 本地缓存检索（需先 sync）；`bug search` 等价别名
+- `zentao bug get <id>` → Bug 详情 JSON（live）
+- `zentao bug create --title T [--product ID --severity 1 --priority 2 --assigned-to U]`（`--project` 为兼容别名，作用域为产品）
+- `zentao bug resolve <id> --resolution fixed [--comment ...]`
+- `zentao bug assign <id> --to <user>`
+
+### 本地 bug 索引（先 sync 再 list/search，统一为缓存检索）
+- `zentao bug sync [--product ID] [--status <browseType>] [--mine]` → 一次性同步某产品 bug 到本地（默认 `unclosed`）；`--mine` 只缓存指派给我的
+- `zentao bug browse-types` → 列出 `sync --status` 的合法 browseType（`all`/`unclosed`/`assigntome`/...）
+
+> 缓存位于 `~/.zentao-cli/cache/bugs-<productId>.json`；关键判断仍走 `bug get`（live）。
+> `bug list` 的 `--product` 支持产品 ID 或**产品名前缀**（如 `--product 财司`，内部调用 products API 解析）。
+> `--mine` 一律本地按 `ZENTAO_USERNAME` 过滤，可与任意过滤叠加。
+> 缓存 >1h（`ZENTAO_CACHE_STALE_MS` 可配）时 search 会在 stderr 提示过期。
+
+默认输出 JSON（stdout），错误走 stderr。退出码：0 成功 / 2 参数配置 / 3 认证 / 4 网络 / 5 API。
+
+## JSON 示例
+```json
+{"total":1,"count":1,"bugs":[{"id":"9","title":"t","severity":"1","priority":"2","status":"active","assignedTo":"a"}]}
+```

package/bin/zentao.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// zentao 命令入口（薄封装）—— 逻辑在 src/zentao.mjs。
+// 后续扩展其它工具时，在 package.json 的 bin 增加新入口（如 log-query、skill-hub）。
+import { main } from '../src/zentao.mjs';
+
+const code = main();
+if (code != null) process.exit(code);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@lyra-ai/toolkit",
+  "version": "0.0.1",
+  "description": "面向 AI agent 的零依赖开发工具集",
+  "type": "module",
+  "bin": {
+    "zentao": "./bin/zentao.mjs"
+  },
+  "engines": { "node": ">=18" },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    ".env.example"
+  ],
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "publish:check": "node scripts/prepublish-check.mjs",
+    "prepublishOnly": "node scripts/prepublish-check.mjs"
+  },
+  "dependencies": {},
+  "devDependencies": {},
+  "license": "MIT",
+  "keywords": ["zentao", "cli", "ai-agent", "zero-dependency"]
+}

package/src/zentao.mjs

@@ -0,0 +1,985 @@
+#!/usr/bin/env node
+// 禅道 CLI —— 面向 AI agent，零依赖单文件
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline';
+// undici 随 Node 内置但未暴露为 bare specifier，按需动态 import；不可用时回退到全局 fetch 默认 dispatcher
+let UndiciAgent = null;
+async function loadUndiciAgent() {
+  if (UndiciAgent === null) {
+    try {
+      const mod = await import('undici');
+      UndiciAgent = mod.Agent;
+    } catch {
+      UndiciAgent = undefined; // 环境无 undici 包：退化为全局 fetch 默认 dispatcher
+    }
+  }
+  return UndiciAgent;
+}
+
+// 统一错误类型：kind 用于映射退出码与上层分支
+export class ZentaoError extends Error {
+  constructor(kind, message) { super(message); this.name = 'ZentaoError'; this.kind = kind; }
+}
+// kind -> 进程退出码
+export function exitCodeFor(kind) {
+  switch (kind) {
+    case 'CONFIG_ERROR':
+    case 'INVALID_PARAMETER': return 2;
+    case 'AUTH_ERROR': return 3;
+    case 'NETWORK_ERROR': return 4;
+    case 'API_ERROR': return 5;
+    default: return 5;
+  }
+}
+
+// Bug 解决方案枚举（依据 禅道APIv1.0.md §解决Bug：bydesign|duplicate|external|fixed|notrepro|postponed|willnotfix|tostory）
+// 注：brief 原始列表缺 tostory、external 写作 externalbug，按 API 文档修正
+// 放在 HELP 之前，使 HELP 能从常量插值，避免两处列表漂移
+const RESOLUTIONS = ['bydesign', 'duplicate', 'external', 'fixed', 'notrepro', 'postponed', 'willnotfix', 'tostory'];
+
+const HELP = `zentao-cli —— 面向 AI agent 的禅道 CLI
+
+命令:
+  project list [--status active|closed|all] [--limit N] [--offset N] [--pretty]
+  product list [--status active|closed|all] [--limit N] [--offset N] [--pretty]
+  bug list    [--title <kw>] [--status S] [--severity 1-4] [--priority 1-4]
+              [--assigned-to U] [--opened-by U] [--mine]
+              [--product <ID|名称前缀>] [--project ID] [--start YYYY-MM-DD] [--end YYYY-MM-DD]
+              [--order id_desc|openedDate_desc|severity_desc|priority_desc|...]
+              [--limit N] [--offset N] [--pretty]
+              # 本地缓存检索（需先 bug sync）；bug search 等价别名；--product 支持名称前缀
+  bug get     <bugId> [--pretty|--raw]
+  bug create  --title T [--product ID] [--severity 1-4] [--priority 1-4]
+              [--assigned-to U] [--type code] [--steps ...] [--pretty]
+  bug resolve <bugId> --resolution <r> [--build B] [--comment ...]
+              r ∈ {${RESOLUTIONS.join(',')}}
+  bug assign  <bugId> --to <user>
+  bug sync    [--product <ID|名称前缀>] [--status <browseType>] [--mine]   # 同步产品 bug 到本地索引（默认 unclosed）
+  bug browse-types                                            # 列出 sync --status 的合法 browseType
+  config                列出所有配置（密码脱敏）
+  config get   <key>    取单个配置值（ZENTAO_PASSWORD 需 --raw 才显原文）
+  config set   <key> <v> 写入 ~/.zentao-cli/.env
+  config unset <key>    删除配置项
+  config path           输出配置文件路径
+  init                  向导式初始化配置（交互提示填 URL/用户/密码等）
+  init --url <u> --username <u> --password <p> [--project <id>]
+                        非交互式初始化（适合脚本/AI agent）
+  ping        验证连通性 + 凭据
+
+通用: --pretty(人读) --raw(原始 JSON) 默认输出规整 JSON
+配置: ZENTAO_URL / ZENTAO_USERNAME / ZENTAO_PASSWORD（必需），见 .env.example
+支持: ZENTAO_DEFAULT_PROJECT / ZENTAO_TOKEN_TTL / ZENTAO_LOG_LEVEL / ZENTAO_CACHE_STALE_MS
+`;
+
+function fileTokenStore(cachePath) {
+  return {
+    read: () => readTokenCache(cachePath, fs),
+    write: (c) => writeTokenCache(cachePath, c, fs),
+    clear: () => { try { fs.unlinkSync(cachePath); } catch { /* ignore */ } },
+  };
+}
+
+function loadFilesText() {
+  const userEnv = path.join(os.homedir(), '.zentao-cli', '.env');
+  const cwdEnv = path.join(process.cwd(), '.env');
+  const files = [];
+  for (const p of [cwdEnv, userEnv]) { try { files.push(fs.readFileSync(p, 'utf8')); } catch { /* ignore */ } }
+  return files; // 项目级在前（优先级高）
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const parsed = parseArgs(argv);
+  if (parsed.flags.help || parsed.command == null) {
+    process.stdout.write(HELP);
+    return 0;
+  }
+  (async () => {
+    const isBootstrapCmd = parsed.command === 'config' || parsed.command === 'init';
+    let config;
+    try {
+      config = loadConfig({ env: process.env, filesText: loadFilesText() }, { required: !isBootstrapCmd });
+    } catch (e) {
+      if (e instanceof ZentaoError) { process.stderr.write(`${e.kind}: ${e.message}\n`); process.exit(exitCodeFor(e.kind)); }
+      process.stderr.write('CONFIG_ERROR: ' + (e?.message || e) + '\n'); process.exit(2);
+    }
+    const cachePath = path.join(os.homedir(), '.zentao-cli', 'token.cache');
+    const cacheDir = path.join(os.homedir(), '.zentao-cli', 'cache');
+    const deps = { tokenStore: fileTokenStore(cachePath), cacheDir, fs, now: Date.now, isBootstrapCmd };
+    const r = await runCommand(parsed, { config, deps });
+    if (r.stdout) process.stdout.write(r.stdout.endsWith('\n') ? r.stdout : r.stdout + '\n');
+    if (r.stderr) process.stderr.write(r.stderr.endsWith('\n') ? r.stderr : r.stderr + '\n');
+    process.exit(r.exitCode ?? 0);
+  })().catch((e) => { process.stderr.write('NETWORK_ERROR: ' + (e?.message || e) + '\n'); process.exit(4);
+  });
+}
+
+// 手写 .env parser：逐行 KEY=VALUE，忽略空行与 # 注释，去两端引号
+export function parseEnvFile(text) {
+  const out = {};
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim();
+    let val = line.slice(eq + 1).trim();
+    if ((val.startsWith('"') && val.endsWith('"')) ||
+        (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+const REQUIRED = ['ZENTAO_URL', 'ZENTAO_USERNAME', 'ZENTAO_PASSWORD'];
+
+export function loadConfig({ env, filesText }, { required } = {}) {
+  // filesText: 数组，靠前优先级高（项目级 .env 在前，用户级在后）
+  const merged = {};
+  for (let i = filesText.length - 1; i >= 0; i--) {
+    Object.assign(merged, parseEnvFile(filesText[i]));
+  }
+  Object.assign(merged, env); // env 优先级最高
+
+  const requiredKeys = required !== false ? REQUIRED : [];
+  const missing = requiredKeys.filter((k) => !merged[k]);
+  if (missing.length) {
+    throw new ZentaoError('CONFIG_ERROR', `缺少必需环境变量: ${missing.join(', ')}（见 .env.example）`);
+  }
+  return {
+    zentaoUrl: String(merged.ZENTAO_URL || '').replace(/\/+$/, ''),
+    username: merged.ZENTAO_USERNAME || '',
+    password: merged.ZENTAO_PASSWORD || '',
+    defaultProject: merged.ZENTAO_DEFAULT_PROJECT || undefined,
+    tokenTtl: Number(merged.ZENTAO_TOKEN_TTL) || 3600,
+    logLevel: merged.ZENTAO_LOG_LEVEL || 'info',
+  };
+}
+
+// ---- config 读写（操作 ~/.zentao-cli/.env）----
+
+export function configFilePath() {
+  return path.join(os.homedir(), '.zentao-cli', '.env');
+}
+
+// 已知配置键（用于 list 展示顺序与 set 校验提示）
+const KNOWN_KEYS = ['ZENTAO_URL', 'ZENTAO_USERNAME', 'ZENTAO_PASSWORD', 'ZENTAO_DEFAULT_PROJECT', 'ZENTAO_TOKEN_TTL', 'ZENTAO_LOG_LEVEL', 'ZENTAO_CACHE_STALE_MS'];
+
+// 敏感键：list/get 默认脱敏
+const SENSITIVE_KEYS = new Set(['ZENTAO_PASSWORD']);
+
+export function readConfigFile(filesystem) {
+  const p = configFilePath();
+  try { return filesystem.readFileSync(p, 'utf8'); } catch { return ''; }
+}
+
+export function writeConfigFile(content, filesystem) {
+  const p = configFilePath();
+  const dir = path.dirname(p);
+  if (!filesystem.existsSync(dir)) filesystem.mkdirSync(dir, { recursive: true });
+  filesystem.writeFileSync(p, content, 'utf8');
+}
+
+// 更新（或追加）一行 KEY=VALUE；保留注释与顺序
+export function setConfigKey(key, value, filesystem) {
+  const content = readConfigFile(filesystem);
+  const lines = content ? content.split(/\r?\n/) : [];
+  let found = false;
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) continue;
+    if (trimmed.slice(0, eq).trim() === key) {
+      lines[i] = `${key}=${value}`;
+      found = true;
+      break;
+    }
+  }
+  if (!found) lines.push(`${key}=${value}`);
+  writeConfigFile(lines.join('\n'), filesystem);
+}
+
+// 删除一行 KEY=VALUE
+export function unsetConfigKey(key, filesystem) {
+  const content = readConfigFile(filesystem);
+  if (!content) return;
+  const lines = content.split(/\r?\n/);
+  const out = lines.filter((line) => {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) return true;
+    const eq = trimmed.indexOf('=');
+    if (eq < 0) return true;
+    return trimmed.slice(0, eq).trim() !== key;
+  });
+  writeConfigFile(out.join('\n'), filesystem);
+}
+
+// ---- 命令实现 ----
+const BOOL_FLAGS = new Set(['pretty', 'raw', 'help']);
+
+export function parseArgs(argv) {
+  const flags = {};
+  const positional = [];
+  let command = null, sub = null;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const name = a.slice(2);
+      const eq = name.indexOf('=');
+      if (eq >= 0) { flags[name.slice(0, eq)] = name.slice(eq + 1); continue; }
+      if (BOOL_FLAGS.has(name)) { flags[name] = true; continue; }
+      // --flag value
+      const next = argv[i + 1];
+      flags[name] = next === undefined || next.startsWith('--') ? true : (i++, next);
+    } else {
+      if (command === null) command = a;
+      else if (sub === null) sub = a;
+      else positional.push(a);
+    }
+  }
+  return { command, sub, flags, positional };
+}
+
+// 禅道 v1 用户字段可能为字符串(account)或嵌套对象 {account,realname,...}，统一取 account 字符串
+function userToAccount(v) {
+  if (v == null) return '';
+  if (typeof v === 'string') return v;
+  // account 优先于 realname，因为 account 是稳定登录标识
+  if (typeof v === 'object') return v.account ?? v.realname ?? '';
+  return String(v);
+}
+
+// 输出整形：保留 agent 关心的字段，统一命名（pri -> priority）
+export function shapeProject(p) {
+  return {
+    id: p.id, name: p.name, status: p.status,
+    begin: p.begin ?? '', end: p.end ?? '',
+    openedBy: userToAccount(p.openedBy), openedDate: p.openedDate ?? '',
+  };
+}
+
+export function shapeProduct(p) {
+  return {
+    id: p.id, name: p.name, code: p.code ?? '',
+    status: p.status, type: p.type ?? '',
+    desc: p.desc ?? '',
+  };
+}
+
+export function shapeBugListItem(b) {
+  return {
+    id: b.id, title: b.title, severity: b.severity, priority: b.pri,
+    status: b.status, openedBy: userToAccount(b.openedBy), openedDate: b.openedDate ?? '',
+    assignedTo: userToAccount(b.assignedTo), projectId: b.project ?? '', productId: b.product ?? '',
+  };
+}
+
+export function shapeBugDetail(b) {
+  return {
+    ...shapeBugListItem(b),
+    type: b.type ?? '', os: b.os ?? '', browser: b.browser ?? '',
+    steps: b.steps ?? '', deadline: b.deadline ?? '',
+    resolution: b.resolution ?? '', resolvedBy: userToAccount(b.resolvedBy),
+    resolvedDate: b.resolvedDate ?? '', resolvedBuild: b.resolvedBuild ?? '',
+    closedBy: userToAccount(b.closedBy), closedDate: b.closedDate ?? '',
+    lastEditedBy: userToAccount(b.lastEditedBy), lastEditedDate: b.lastEditedDate ?? '',
+  };
+}
+
+export function projectsToMarkdown({ total, count, projects }) {
+  const lines = ['# Projects List', '', `Found ${total} projects (showing ${count})`, '',
+    '| ID | Name | Status | Begin | End | OpenedBy | OpenedDate |', '|---|---|---|---|---|---|---|'];
+  for (const p of projects) {
+    lines.push(`| ${p.id} | ${p.name} | ${p.status} | ${p.begin} | ${p.end} | ${p.openedBy} | ${p.openedDate} |`);
+  }
+  return lines.join('\n');
+}
+
+export function productsToMarkdown({ total, count, products }) {
+  const lines = ['# Products List', '', `Found ${total} products (showing ${count})`, '',
+    '| ID | Name | Code | Status | Type | Desc |', '|---|---|---|---|---|---|'];
+  for (const p of products) {
+    lines.push(`| ${p.id} | ${p.name} | ${p.code} | ${p.status} | ${p.type} | ${p.desc} |`);
+  }
+  return lines.join('\n');
+}
+
+export function bugListToMarkdown({ total, count, bugs }) {
+  const lines = ['# Bug List', '', `Found ${total} bugs (showing ${count})`, '',
+    '| ID | Title | Sev | Pri | Status | AssignedTo | OpenedBy | OpenedDate |', '|---|---|---|---|---|---|---|---|'];
+  for (const b of bugs) {
+    lines.push(`| ${b.id} | ${b.title} | ${b.severity} | ${b.priority} | ${b.status} | ${b.assignedTo} | ${b.openedBy} | ${b.openedDate} |`);
+  }
+  return lines.join('\n');
+}
+
+export function bugDetailToMarkdown(b) {
+  const f = (k) => b[k] === '' || b[k] == null ? '-' : b[k];
+  return [
+    `# Bug #${b.id}: ${b.title}`, '',
+    `- **Severity**: ${b.severity} | **Priority**: ${b.priority} | **Status**: ${b.status}`,
+    `- **Project**: ${b.projectId} | **Product**: ${b.productId}`,
+    `- **OpenedBy**: ${b.openedBy} ${b.openedDate} | **AssignedTo**: ${f('assignedTo')}`,
+    `- **Resolution**: ${f('resolution')} by ${f('resolvedBy')} ${f('resolvedDate')}`,
+    '', '## Steps', '', b.steps || '(empty)',
+  ].join('\n');
+}
+
+// HTTP 状态码 -> 统一错误 kind/message
+export function mapHttpError(status) {
+  switch (status) {
+    case 401: case 403: return { kind: 'AUTH_ERROR', message: '认证失败：检查用户名/密码与 ZENTAO_URL' };
+    case 404: return { kind: 'INVALID_PARAMETER', message: '资源不存在：检查 ID 是否正确' };
+    case 429: return { kind: 'API_ERROR', message: '请求过于频繁，请稍后重试' };
+    default: return { kind: 'API_ERROR', message: `API 请求失败，状态码 ${status}` };
+  }
+}
+
+// Token 缓存：文件读写 + 过期判断（fs 注入便于测试）
+export function readTokenCache(path, fs) {
+  try {
+    const raw = fs.readFileSync(path, 'utf8');
+    const obj = JSON.parse(raw);
+    if (obj && typeof obj.token === 'string') return { token: obj.token, expiresAt: Number(obj.expiresAt) };
+    return null;
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null;
+    return null; // 损坏的缓存当作无缓存
+  }
+}
+
+export function writeTokenCache(path, data, fs) {
+  // 确保父目录存在（首次运行 ~/.zentao-cli 不存在）
+  try {
+    if (typeof fs.mkdirSync === 'function') {
+      const dir = path.replace(/[\\/][^\\/]+$/, '');
+      if (dir && dir !== path) fs.mkdirSync(dir, { recursive: true });
+    }
+  } catch { /* ignore mkdir errors（测试用内存 fs 可能无 mkdirSync） */ }
+  fs.writeFileSync(path, JSON.stringify(data), { mode: 0o600 });
+  try { if (typeof fs.chmodSync === 'function') fs.chmodSync(path, 0o600); } catch { /* Windows no-op */ }
+}
+
+export function isExpired(cache, nowMs) {
+  if (!cache) return true;
+  return nowMs >= cache.expiresAt;
+}
+
+export function createClient(config, { fetch = globalThis.fetch, tokenStore, agent } = {}) {
+  let _dispatcher;
+  async function getDispatcher() {
+    if (agent) return agent;
+    if (!_dispatcher) {
+      const UndiciAgentCls = await loadUndiciAgent();
+      if (UndiciAgentCls) _dispatcher = new UndiciAgentCls({ connect: { rejectUnauthorized: false } });
+    }
+    return _dispatcher;
+  }
+
+  async function rawFetch(url, opts) {
+    const dispatcher = await getDispatcher();
+    return fetch(url, { ...opts, ...(dispatcher ? { dispatcher } : {}) }); // 测试用 fake fetch 会忽略 dispatcher
+  }
+
+  async function login() {
+    const res = await rawFetch(`${config.zentaoUrl}/api.php/v1/tokens`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ account: config.username, password: config.password }),
+    });
+    if (!res.ok) {
+      const m = mapHttpError(res.status);
+      throw new ZentaoError(m.kind, '认证失败：' + m.message);
+    }
+    const data = await res.json();
+    if (!data.token) throw new ZentaoError('AUTH_ERROR', '登录响应缺少 token');
+    const cache = { token: data.token, expiresAt: Date.now() + config.tokenTtl * 1000 };
+    tokenStore.write(cache);
+    return cache.token;
+  }
+
+  async function getToken() {
+    const cache = tokenStore.read();
+    if (cache && !isExpired(cache, Date.now())) return cache.token;
+    return login();
+  }
+
+  async function request(method, path, { params, body, _retried = false } = {}) {
+    const token = await getToken();
+    const url = new URL(config.zentaoUrl + path);
+    if (params) for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, v);
+    let res;
+    try {
+      res = await rawFetch(url, {
+        method,
+        headers: { 'Content-Type': 'application/json', Accept: 'application/json', Token: token },
+        body: body ? JSON.stringify(body) : undefined,
+      });
+    } catch (e) {
+      throw new ZentaoError('NETWORK_ERROR', e && e.message ? e.message : '网络请求失败');
+    }
+    if (res.status === 401 || res.status === 403) {
+      if (!_retried) { tokenStore.clear(); return request(method, path, { params, body, _retried: true }); }
+      throw new ZentaoError('AUTH_ERROR', '认证失败：检查凭据');
+    }
+    if (!res.ok) {
+      const m = mapHttpError(res.status);
+      let detail = '';
+      try { detail = (await res.json())?.message || ''; } catch { /* ignore */ }
+      throw new ZentaoError(m.kind, detail ? `${m.message}（${detail}）` : m.message);
+    }
+    // 防御空响应体/204：先读文本，非空再解析，保持现有 JSON 端点行为不变
+    const text = await res.text();
+    return text ? JSON.parse(text) : {};
+  }
+
+  return { getToken, request, login };
+}
+
+// 分页辅助：在内存数组上切片，返回统一分页结构
+function paginate(items, limit, offset) {
+  const start = Math.min(offset, items.length);
+  const end = Math.min(start + limit, items.length);
+  const slice = items.slice(start, end);
+  return { total: items.length, count: slice.length, offset, has_more: end < items.length, next_offset: end < items.length ? end : undefined, items: slice };
+}
+
+async function cmdPing(parsed, client, config) {
+  await client.request('GET', '/api.php/v1/projects', { params: { limit: 1 } });
+  return { stdout: JSON.stringify({ ok: true, url: config.zentaoUrl, defaultProject: config.defaultProject ?? null }, null, 2) };
+}
+
+// ---- config 子命令 ----
+
+function maskIfSensitive(key, value) {
+  if (SENSITIVE_KEYS.has(key) && value) return '***';
+  return value ?? '';
+}
+
+function configToObj(config) {
+  return {
+    ZENTAO_URL: config.zentaoUrl,
+    ZENTAO_USERNAME: config.username,
+    ZENTAO_PASSWORD: config.password,
+    ZENTAO_DEFAULT_PROJECT: config.defaultProject ?? '',
+    ZENTAO_TOKEN_TTL: String(config.tokenTtl),
+    ZENTAO_LOG_LEVEL: config.logLevel,
+    ZENTAO_CACHE_STALE_MS: process.env.ZENTAO_CACHE_STALE_MS || '',
+  };
+}
+
+function cmdConfigList(config) {
+  const obj = configToObj(config);
+  const out = {};
+  for (const k of KNOWN_KEYS) {
+    if (obj[k]) out[k] = maskIfSensitive(k, obj[k]);
+  }
+  return { stdout: JSON.stringify(out, null, 2) };
+}
+
+function cmdConfigGet(parsed, config) {
+  const key = parsed.positional[0];
+  if (!key) return { stderr: '用法：zentao config get <key>', exitCode: 2 };
+  const obj = configToObj(config);
+  const keyUpper = key.toUpperCase();
+  if (obj[keyUpper] === undefined) return { stderr: `未知配置项: ${key}（合法值: ${KNOWN_KEYS.join(', ')}）`, exitCode: 2 };
+  const raw = parsed.flags.raw;
+  const val = raw ? obj[keyUpper] : maskIfSensitive(keyUpper, obj[keyUpper]);
+  return { stdout: val };
+}
+
+function cmdConfigSet(parsed, filesystem) {
+  const key = parsed.positional[0];
+  const value = parsed.positional[1];
+  if (!key || value === undefined) return { stderr: '用法：zentao config set <key> <value>', exitCode: 2 };
+  const keyUpper = key.toUpperCase();
+  if (!KNOWN_KEYS.includes(keyUpper)) {
+    return { stderr: `未知配置项: ${key}（合法值: ${KNOWN_KEYS.join(', ')}）。如需自定义变量请直接编辑 .env`, exitCode: 2 };
+  }
+  setConfigKey(keyUpper, value, filesystem);
+  return { stdout: JSON.stringify({ set: keyUpper, value: maskIfSensitive(keyUpper, value) }, null, 2) };
+}
+
+function cmdConfigUnset(parsed, filesystem) {
+  const key = parsed.positional[0];
+  if (!key) return { stderr: '用法：zentao config unset <key>', exitCode: 2 };
+  const keyUpper = key.toUpperCase();
+  unsetConfigKey(keyUpper, filesystem);
+  return { stdout: JSON.stringify({ unset: keyUpper }, null, 2) };
+}
+
+function cmdConfigPath() {
+  return { stdout: configFilePath() };
+}
+
+// ---- init 向导 ----
+
+// 掩码密码输入（不回显），仅在 TTY 下有效
+async function maskedPrompt(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    let buf = '';
+    const onData = (c) => {
+      const ch = c.toString();
+      if (ch === '\r' || ch === '\n') {
+        process.stdout.write('\n');
+        process.stdin.removeListener('data', onData);
+        process.stdin.setRawMode(false);
+        resolve(buf);
+      } else if (ch === '') {
+        process.stdout.write('\n');
+        process.exit(0);
+      } else if (ch === '\x7f' || ch === '\b') {
+        if (buf.length > 0) { buf = buf.slice(0, -1); process.stdout.write('\b \b'); }
+      } else {
+        buf += ch;
+        process.stdout.write('*');
+      }
+    };
+    process.stdin.setRawMode(true);
+    process.stdin.on('data', onData);
+  });
+}
+
+async function cmdInit(parsed, config, deps) {
+  const { url, username, password, project, ping: doPing } = parsed.flags;
+  const hasAllRequired = url && username && password;
+
+  // 非交互模式：三参数齐全直接写入
+  if (hasAllRequired) {
+    setConfigKey('ZENTAO_URL', url, deps.fs);
+    setConfigKey('ZENTAO_USERNAME', username, deps.fs);
+    setConfigKey('ZENTAO_PASSWORD', password, deps.fs);
+    if (project) setConfigKey('ZENTAO_DEFAULT_PROJECT', project, deps.fs);
+
+    if (doPing) {
+      const newCfg = loadConfig({ env: {}, filesText: [deps.fs.readFileSync(configFilePath(), 'utf8')] });
+      try {
+        const c = createClient(newCfg, deps);
+        await c.request('GET', '/api.php/v1/projects', { params: { limit: 1 } });
+        return { stdout: JSON.stringify({ ok: true, message: '已保存，连通性验证通过', pingOk: true }, null, 2) };
+      } catch (e) {
+        return { stdout: JSON.stringify({ ok: true, message: '已保存，连通性验证失败: ' + (e?.message || e), pingOk: false }, null, 2) };
+      }
+    }
+    return { stdout: JSON.stringify({ ok: true, message: '配置已保存' }, null, 2) };
+  }
+
+  // 给了部分参数但不全 → 报错
+  if (url || username || password) {
+    return { stderr: '非交互模式需同时指定 --url --username --password', exitCode: 2 };
+  }
+
+  // 交互模式需要 TTY
+  if (!process.stdin.isTTY) {
+    return { stderr: '非交互终端请传参：zentao init --url <url> --username <u> --password <p> [--project <id>] [--ping]', exitCode: 2 };
+  }
+
+  // ---- 交互式向导 ----
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q, def) => new Promise((resolve) => {
+    rl.question(def ? `${q} [${def}]: ` : `${q}: `, (ans) => resolve(ans.trim() || def || ''));
+  });
+
+  process.stdout.write('\n🧙 zentao-cli 初始化向导\n\n');
+
+  const u = await ask('禅道地址 (ZENTAO_URL)', config.zentaoUrl || '');
+  const un = await ask('用户名 (ZENTAO_USERNAME)', config.username || '');
+  const pw = await (async () => {
+    rl.pause();
+    const p = await maskedPrompt('密码 (ZENTAO_PASSWORD): ');
+    rl.resume();
+    return p;
+  })();
+
+  rl.close();
+
+  setConfigKey('ZENTAO_URL', u, deps.fs);
+  setConfigKey('ZENTAO_USERNAME', un, deps.fs);
+  setConfigKey('ZENTAO_PASSWORD', pw, deps.fs);
+
+  // 验证连通性
+  process.stdout.write('\n🔍 验证连通性...\n');
+  let pingOk = false;
+  let pingErr = '';
+  try {
+    const newCfg = loadConfig({ env: {}, filesText: [deps.fs.readFileSync(configFilePath(), 'utf8')] });
+    const c = createClient(newCfg, deps);
+    await c.request('GET', '/api.php/v1/projects', { params: { limit: 1 } });
+    pingOk = true;
+  } catch (e) {
+    pingErr = e?.message || String(e);
+  }
+
+  return {
+    stdout: JSON.stringify({
+      ok: true,
+      message: pingOk ? '配置已保存，连通性验证通过 ✓' : `配置已保存，但连通性验证失败（${pingErr}）。请检查 ZENTAO_URL 和凭据。`,
+      pingOk,
+      hint: pingOk ? '下一步：zentao project list 查看项目 → zentao config set ZENTAO_DEFAULT_PROJECT <id> 设默认项目' : null,
+    }, null, 2),
+  };
+}
+
+async function cmdProjectList(parsed, client) {
+  const data = await client.request('GET', '/api.php/v1/projects');
+  let projects = data.projects || [];
+  if (parsed.flags.status && parsed.flags.status !== 'all') {
+    projects = projects.filter((p) => parsed.flags.status === 'closed' ? p.status === 'closed' : p.status !== 'closed');
+  }
+  const limit = Number(parsed.flags.limit) || 20;
+  const offset = Number(parsed.flags.offset) || 0;
+  const page = paginate(projects, limit, offset);
+  const out = { total: page.total, count: page.count, offset: page.offset, has_more: page.has_more, next_offset: page.next_offset, projects: page.items.map(shapeProject) };
+  if (parsed.flags.pretty) return { stdout: projectsToMarkdown({ ...out, projects: page.items.map(shapeProject) }) };
+  return { stdout: JSON.stringify(out, null, 2) };
+}
+
+async function cmdProductList(parsed, client) {
+  const data = await client.request('GET', '/api.php/v1/products');
+  let products = data.products || [];
+  if (parsed.flags.status && parsed.flags.status !== 'all') {
+    products = products.filter((p) => parsed.flags.status === 'closed' ? p.status === 'closed' : p.status !== 'closed');
+  }
+  const limit = Number(parsed.flags.limit) || 20;
+  const offset = Number(parsed.flags.offset) || 0;
+  const page = paginate(products, limit, offset);
+  const out = { total: page.total, count: page.count, offset: page.offset, has_more: page.has_more, next_offset: page.next_offset, products: page.items.map(shapeProduct) };
+  if (parsed.flags.pretty) return { stdout: productsToMarkdown({ ...out, products: page.items.map(shapeProduct) }) };
+  return { stdout: JSON.stringify(out, null, 2) };
+}
+
+// 统一 bug 列表 → 全走本地缓存（先 sync 后查）
+// bug list / bug search 两者等价，search 为隐藏别名
+async function cmdBugList(parsed, config, deps) {
+  const { cacheDir, fs, now } = deps;
+  // 解析 --product：非数字按产品名前缀匹配
+  let wantProduct = parsed.flags.product;
+  if (wantProduct && !/^\d+$/.test(String(wantProduct))) {
+    const client = deps.client || createClient(config, deps);
+    const data = await client.request('GET', '/api.php/v1/products');
+    const matches = (data.products || []).filter((p) => p.name && String(p.name).startsWith(wantProduct));
+    if (!matches.length) {
+      const names = (data.products || []).slice(0, 20).map((p) => p.name).filter(Boolean).join(', ');
+      return { stderr: `未找到名前缀匹配 "${wantProduct}" 的产品。已知产品: ${names || '(无)'}`, exitCode: 2 };
+    }
+    wantProduct = matches[0].id; // 优先取第一个匹配
+  }
+  const products = wantProduct ? [String(wantProduct)] : listCacheProducts(fs, cacheDir);
+  if (!products.length) {
+    return { stderr: '无本地缓存，请先：zentao bug sync --product <ID>', exitCode: 2 };
+  }
+  const nowMs = typeof now === 'function' ? now() : (now ?? Date.now());
+  let merged = [];
+  let oldestSync = Infinity;
+  let missing = false;
+  for (const pid of products) {
+    const cache = readBugCache(cacheDir, pid, fs);
+    if (!cache) { missing = true; continue; }
+    oldestSync = Math.min(oldestSync, cache.syncedAt);
+    for (const b of cache.bugs) merged.push({ ...b, productId: cache.product });
+  }
+  if (!merged.length && missing) {
+    return { stderr: `产品 ${wantProduct} 无本地缓存，请先：zentao bug sync --product ${wantProduct}`, exitCode: 2 };
+  }
+
+  // ---- 本地过滤 ----
+  let out = merged;
+  if (parsed.flags.mine) out = out.filter((b) => b.assignedTo === config.username);
+  if (parsed.flags.title) {
+    const kw = String(parsed.flags.title).toLowerCase();
+    out = out.filter((b) => String(b.title || '').toLowerCase().includes(kw));
+  }
+  if (parsed.flags.status && parsed.flags.status !== 'all') out = out.filter((b) => b.status === parsed.flags.status);
+  if (parsed.flags.severity) out = out.filter((b) => String(b.severity) === String(parsed.flags.severity));
+  if (parsed.flags.priority) out = out.filter((b) => String(b.priority) === String(parsed.flags.priority));
+  if (parsed.flags['assigned-to']) out = out.filter((b) => b.assignedTo === parsed.flags['assigned-to']);
+  if (parsed.flags['opened-by']) out = out.filter((b) => b.openedBy === parsed.flags['opened-by']);
+  if (parsed.flags.project) out = out.filter((b) => String(b.projectId) === String(parsed.flags.project));
+  if (parsed.flags.start) out = out.filter((b) => String(b.openedDate || '') >= parsed.flags.start);
+  if (parsed.flags.end) out = out.filter((b) => String(b.openedDate || '') <= parsed.flags.end);
+
+  // ---- 本地排序 ----
+  if (parsed.flags.order) {
+    const ORDERS = { id_desc: ['id', -1], id_asc: ['id', 1], openedDate_desc: ['openedDate', -1], openedDate_asc: ['openedDate', 1], severity_desc: ['severity', -1], severity_asc: ['severity', 1], priority_desc: ['priority', -1], priority_asc: ['priority', 1], status_desc: ['status', -1], status_asc: ['status', 1], title_asc: ['title', 1], title_desc: ['title', -1] };
+    const [field, dir] = ORDERS[parsed.flags.order] || [null, 0];
+    if (field) {
+      out = [...out].sort((a, b) => {
+        const va = (a[field] ?? ''), vb = (b[field] ?? '');
+        return dir * String(va).localeCompare(String(vb), undefined, { numeric: true });
+      });
+    }
+  }
+
+  // ---- 分页 ----
+  const limit = Number(parsed.flags.limit) || 20;
+  const offset = Number(parsed.flags.offset) || 0;
+  const start = Math.min(offset, out.length);
+  const end = Math.min(start + limit, out.length);
+  const page = out.slice(start, end);
+
+  // staleness 提示
+  let stderr;
+  if (isFinite(oldestSync) && nowMs - oldestSync > CACHE_STALE_MS) {
+    const hrs = ((nowMs - oldestSync) / 3600000).toFixed(1);
+    stderr = `⚠ 缓存可能过期（${hrs}h 前同步），关键判断请 'bug get <id>' 或重新 'bug sync'`;
+  }
+  if (parsed.flags.pretty) {
+    return { stdout: bugListToMarkdown({ total: out.length, count: page.length, bugs: page }), stderr };
+  }
+  const body = { syncedAt: isFinite(oldestSync) ? oldestSync : null, total: out.length, count: page.length, offset, has_more: end < out.length, bugs: page };
+  return { stdout: JSON.stringify(body, null, 2), stderr };
+}
+
+async function cmdBugGet(parsed, client) {
+  const bugId = parsed.positional[0];
+  if (!bugId) return { stderr: '错误：缺少 bugId（用法：zentao bug get <bugId>）', exitCode: 2 };
+  const data = await client.request('GET', `/api.php/v1/bugs/${bugId}`);
+  if (parsed.flags.raw) return { stdout: JSON.stringify(data, null, 2) };
+  const shaped = shapeBugDetail(data);
+  if (parsed.flags.pretty) return { stdout: bugDetailToMarkdown(shaped) };
+  return { stdout: JSON.stringify(shaped, null, 2) };
+}
+
+// 创建 Bug
+// 依据 禅道APIv1.0.md §创建Bug：POST /products/id/bugs（brief 原写 /projects/id/bugs 为误，文档以产品为作用域）
+// TODO 依据 禅道APIv1.0.md §创建Bug，实测受限(只读环境)未做活体验证
+async function cmdBugCreate(parsed, client, defaultProject) {
+  // 文档作用域为 product；保留 --project 旗标与 defaultProject 配置以兼容现有 cfg，语义等同 productId
+  const productId = parsed.flags.project || parsed.flags.product || defaultProject;
+  if (!productId) throw new ZentaoError('INVALID_PARAMETER', '未指定 --project 且无 ZENTAO_DEFAULT_PROJECT');
+  if (!parsed.flags.title) return { stderr: '错误：缺少 --title', exitCode: 2 };
+  const body = {
+    title: parsed.flags.title,
+    // severity/pri/type 文档标为必填；这里仅透传，缺失时由后端校验
+    ...(parsed.flags.severity ? { severity: parsed.flags.severity } : {}),
+    ...(parsed.flags.priority ? { pri: parsed.flags.priority } : {}),
+    ...(parsed.flags['assigned-to'] ? { assignedTo: parsed.flags['assigned-to'] } : {}),
+    ...(parsed.flags.type ? { type: parsed.flags.type } : {}),
+    ...(parsed.flags.steps ? { steps: parsed.flags.steps } : {}),
+    // openedBuild 在部分版本必填，留 TODO：实测后补默认值
+  };
+  const data = await client.request('POST', `/api.php/v1/products/${productId}/bugs`, { body });
+  return { stdout: JSON.stringify({ id: data.id ?? data.bugId ?? null }, null, 2) };
+}
+
+// 解决 Bug
+// 依据 禅道APIv1.0.md §解决Bug：POST /bugs/id/resolve，body resolution 必填
+async function cmdBugResolve(parsed, client, deps) {
+  const bugId = parsed.positional[0];
+  if (!bugId) return { stderr: '错误：缺少 bugId', exitCode: 2 };
+  if (!parsed.flags.resolution) return { stderr: `错误：缺少 --resolution（可选：${RESOLUTIONS.join(',')}）`, exitCode: 2 };
+  const body = {
+    resolution: parsed.flags.resolution,
+    ...(parsed.flags.build ? { resolvedBuild: parsed.flags.build } : {}),
+    ...(parsed.flags.comment ? { comment: parsed.flags.comment } : {}),
+  };
+  const data = await client.request('POST', `/api.php/v1/bugs/${bugId}/resolve`, { body });
+  // best-effort 更新本地索引（不阻断）
+  if (deps?.cacheDir && deps?.fs) {
+    updateCachedBugAnywhere(deps.cacheDir, bugId, { status: 'resolved', resolution: parsed.flags.resolution }, deps.fs);
+  }
+  return { stdout: JSON.stringify({ id: bugId, resolved: true, raw: data?.id ?? null }, null, 2) };
+}
+
+// 指派 Bug
+// 依据 禅道APIv1.0.md §2.14.4 修改Bug：PUT /bugs/id（禅道 REST v1 无独立 assignTo 端点，
+// 亦无独立 comment 端点）。指派复用「修改 Bug」通道，body 仅传 assignedTo 字段。
+// 字段名 assignedTo 为禅道各动作体（confirm/active/task 等）通用指派字段，与文档一致。
+// TODO 实测受限(只读环境)未做活体验证。
+async function cmdBugAssign(parsed, client, deps) {
+  const bugId = parsed.positional[0];
+  if (!bugId) return { stderr: '错误：缺少 bugId', exitCode: 2 };
+  if (!parsed.flags.to) return { stderr: '错误：缺少 --to <user>', exitCode: 2 };
+  const body = { assignedTo: parsed.flags.to };
+  const data = await client.request('PUT', `/api.php/v1/bugs/${bugId}`, { body });
+  // best-effort 更新本地索引（不阻断）
+  if (deps?.cacheDir && deps?.fs) {
+    updateCachedBugAnywhere(deps.cacheDir, bugId, { assignedTo: parsed.flags.to }, deps.fs);
+  }
+  return { stdout: JSON.stringify({ id: bugId, assignedTo: parsed.flags.to, raw: data?.id ?? null }, null, 2) };
+}
+
+// ============ 本地 Bug 索引（sync / search） ============
+
+// bug 列表服务端 browseType 合法值（源码 module/bug/model.php getBugs 398-414）
+// bysearch(queryID 写死0)/bymodule(需moduleID)/bybranch 经 REST 不可用，故不列。
+export const BUG_BROWSE_TYPES = [
+  { value: 'all', desc: '全部' },
+  { value: 'unclosed', desc: '未关闭（sync 默认）' },
+  { value: 'unresolved', desc: '未解决' },
+  { value: 'toclosed', desc: '待关闭' },
+  { value: 'assigntome', desc: '指派给我' },
+  { value: 'openedbyme', desc: '我创建的' },
+  { value: 'resolvedbyme', desc: '我解决的' },
+  { value: 'assignedbyme', desc: '我指派的' },
+  { value: 'assigntonull', desc: '未指派' },
+  { value: 'unconfirmed', desc: '未确认' },
+  { value: 'longlifebugs', desc: '长期未解决' },
+  { value: 'postponedbugs', desc: '延期处理' },
+  { value: 'needconfirm', desc: '需确认' },
+  { value: 'overduebugs', desc: '已过期' },
+  { value: 'review', desc: '待评审' },
+];
+
+// 缓存过期阈值（ms），默认 1h，可由 ZENTAO_CACHE_STALE_MS 覆盖
+const CACHE_STALE_MS = Number(process.env.ZENTAO_CACHE_STALE_MS) || 3600 * 1000;
+
+// 本地 bug 索引缓存 I/O（注入 fs 便于测试）
+export function cacheFilePath(dir, productId) {
+  return `${dir}/bugs-${productId}.json`;
+}
+
+export function readBugCache(dir, productId, fs) {
+  try {
+    const raw = fs.readFileSync(cacheFilePath(dir, productId), 'utf8');
+    const obj = JSON.parse(raw);
+    if (obj && Array.isArray(obj.bugs)) return obj;
+    return null; // 结构不符当作无缓存
+  } catch (e) {
+    if (e && e.code === 'ENOENT') return null;
+    return null; // 损坏缓存当作无缓存
+  }
+}
+
+// 原子写：先写 .tmp 再 rename，避免崩溃损坏；目录自动建；权限收紧
+export function writeBugCache(dir, productId, data, fs) {
+  const final = cacheFilePath(dir, productId);
+  const tmp = `${final}.tmp`;
+  try { fs.mkdirSync(dir, { recursive: true }); } catch { /* 已存在或不可建 */ }
+  fs.writeFileSync(tmp, JSON.stringify(data), { mode: 0o600 });
+  try { if (typeof fs.chmodSync === 'function') fs.chmodSync(tmp, 0o600); } catch { /* Windows no-op */ }
+  fs.renameSync(tmp, final);
+}
+
+// 列出已缓存的产品 id（扫描 cacheDir 下 bugs-<id>.json）
+export function listCacheProducts(fs, cacheDir) {
+  let entries = [];
+  try { entries = fs.readdirSync(cacheDir); } catch { return []; }
+  const out = [];
+  for (const name of entries) {
+    const m = name.match(/^bugs-(.+)\.json$/);
+    if (m) out.push(m[1]);
+  }
+  return out;
+}
+
+// best-effort 更新某产品缓存中指定 bug；命中并写入返回 true，否则 false；失败静默
+export function updateCachedBug(cacheDir, productId, bugId, patch, fs) {
+  try {
+    const cache = readBugCache(cacheDir, productId, fs);
+    if (!cache) return false;
+    let hit = false;
+    cache.bugs = cache.bugs.map((b) => {
+      if (String(b.id) === String(bugId)) { hit = true; return { ...b, ...patch }; }
+      return b;
+    });
+    if (hit) writeBugCache(cacheDir, productId, cache, fs);
+    return hit;
+  } catch {
+    return false;
+  }
+}
+
+// 扫描所有已缓存产品，更新命中 bug（写命令后 best-effort）
+export function updateCachedBugAnywhere(cacheDir, bugId, patch, fs) {
+  let hit = false;
+  for (const pid of listCacheProducts(fs, cacheDir)) {
+    if (updateCachedBug(cacheDir, pid, bugId, patch, fs)) hit = true;
+  }
+  return hit;
+}
+
+// 输出 browseType 合法值
+function cmdBugBrowseTypes(parsed) {
+  const rows = BUG_BROWSE_TYPES;
+  if (parsed.flags.pretty) {
+    const lines = ['# Bug browseTypes（sync --status 取值）', '', '| value | desc |', '|---|---|'];
+    for (const r of rows) lines.push(`| ${r.value} | ${r.desc} |`);
+    return { stdout: lines.join('\n') };
+  }
+  return { stdout: JSON.stringify({ browseTypes: rows.map((r) => r.value) }, null, 2) };
+}
+
+// 一次性同步某产品 bug 到本地索引
+async function cmdBugSync(parsed, client, config, { cacheDir, fs }) {
+  let productId = parsed.flags.product || config.defaultProject;
+  // --product 非数字 → 产品名前缀匹配
+  if (productId && !/^\d+$/.test(String(productId))) {
+    const data = await client.request('GET', '/api.php/v1/products');
+    const matches = (data.products || []).filter((p) => p.name && String(p.name).startsWith(productId));
+    if (!matches.length) {
+      const names = (data.products || []).slice(0, 20).map((p) => p.name).filter(Boolean).join(', ');
+      throw new ZentaoError('INVALID_PARAMETER', `未找到名前缀匹配 "${productId}" 的产品。已知产品: ${names || '(无)'}`);
+    }
+    productId = matches[0].id;
+  }
+  if (!productId) throw new ZentaoError('INVALID_PARAMETER', '未指定 --product 且无 ZENTAO_DEFAULT_PROJECT');
+  const browseType = parsed.flags.status || 'unclosed'; // sync 的 --status = 服务端 browseType，默认 unclosed
+  const limit = 100;
+  const all = [];
+  for (let page = 1; ; page++) {
+    const data = await client.request('GET', `/api.php/v1/products/${productId}/bugs`, { params: { status: browseType, limit, page } });
+    const bugs = (data.bugs || []).map(shapeBugListItem);
+    all.push(...bugs);
+    if (!data.bugs || data.bugs.length < limit) break; // 不足一页 = 取完
+  }
+  // --mine：本地按 assignedTo === 当前账号 过滤（可与任意 browseType 叠加）
+  const final = parsed.flags.mine ? all.filter((b) => b.assignedTo === config.username) : all;
+  const cache = { product: String(productId), status: browseType, syncedAt: Date.now(), count: final.length, bugs: final };
+  writeBugCache(cacheDir, productId, cache, fs); // 仅成功后写，失败不破坏旧缓存
+  return { stdout: JSON.stringify({ product: String(productId), status: browseType, syncedAt: cache.syncedAt, count: final.length, cached: final.length }, null, 2) };
+}
+
+// 命令分发：根据 parsed 派发到对应 cmd，捕获 ZentaoError 转 exitCode
+export async function runCommand(parsed, { config, deps }) {
+  const client = deps.client ?? (deps.isBootstrapCmd ? null : createClient(config, deps));
+  try {
+    let res;
+    if (parsed.command === 'config' && parsed.sub == null) res = cmdConfigList(config);
+    else if (parsed.command === 'config' && parsed.sub === 'get') res = cmdConfigGet(parsed, config);
+    else if (parsed.command === 'config' && parsed.sub === 'set') res = cmdConfigSet(parsed, deps.fs);
+    else if (parsed.command === 'config' && parsed.sub === 'unset') res = cmdConfigUnset(parsed, deps.fs);
+    else if (parsed.command === 'config' && parsed.sub === 'path') res = cmdConfigPath();
+    else if (parsed.command === 'init') res = await cmdInit(parsed, config, deps);
+    else if (parsed.command === 'project' && parsed.sub === 'list') res = await cmdProjectList(parsed, client);
+    else if (parsed.command === 'product' && parsed.sub === 'list') res = await cmdProductList(parsed, client);
+    else if (parsed.command === 'bug' && (parsed.sub === 'list' || parsed.sub === 'search')) res = await cmdBugList(parsed, config, deps);
+    else if (parsed.command === 'bug' && parsed.sub === 'get') res = await cmdBugGet(parsed, client);
+    else if (parsed.command === 'bug' && parsed.sub === 'create') res = await cmdBugCreate(parsed, client, config.defaultProject);
+    else if (parsed.command === 'bug' && parsed.sub === 'resolve') res = await cmdBugResolve(parsed, client, deps);
+    else if (parsed.command === 'bug' && parsed.sub === 'assign') res = await cmdBugAssign(parsed, client, deps);
+    else if (parsed.command === 'bug' && parsed.sub === 'sync') res = await cmdBugSync(parsed, client, config, deps);
+    else if (parsed.command === 'bug' && parsed.sub === 'browse-types') res = cmdBugBrowseTypes(parsed);
+    else if (parsed.command === 'ping') res = await cmdPing(parsed, client, config);
+    else return { stderr: `未知命令：${[parsed.command, parsed.sub].filter(Boolean).join(' ')}（见 --help）`, exitCode: 2 };
+    return { stdout: res.stdout ?? '', stderr: res.stderr ?? '', exitCode: res.exitCode ?? 0 };
+  } catch (e) {
+    if (e instanceof ZentaoError) return { stderr: `${e.kind}: ${e.message}`, exitCode: exitCodeFor(e.kind) };
+    return { stderr: 'NETWORK_ERROR: ' + (e?.message || String(e)), exitCode: 4 };
+  }
+}
+
+export { main };
+
+// 仅在直接执行时跑 main（被测试 import 时不跑）—— 放在文件末尾，确保所有 const 已初始化
+// 用 realpath 比较：npm 全局安装时 node_modules/zentao-cli 是软链，argv[1] 软链路径 ≠ import.meta.url 真实路径，
+// 直接字符串比较会导致 main 不触发（全局命令无输出）。realpath 把两者都解析到真实文件再比较。
+const __isMain = (() => {
+  try {
+    return !!process.argv[1] && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (__isMain) {
+  const code = main();
+  if (code != null) process.exit(code);
+}