i18-fe-automator-beta 2.1.2 → 2.1.4

package/dist/commonjs/index.js

@@ -11,9 +11,9 @@ var CheckboxPrompt = require('inquirer/lib/prompts/checkbox.js');
 var md5$1 = require('js-md5');
 var CryptoJS = require('crypto-js');
 var ora = require('ora');
-var xlsx = require('node-xlsx');
 var url = require('url');
 var path = require('path');
+var xlsx = require('node-xlsx');
 var crypto = require('crypto');
 var querystring = require('querystring');
 var uuid = require('uuid');
@@ -114,45 +114,169 @@ function Loading() {
 }
 var Loading$1 = new Loading().spinner;
 
-//加密
-function encrypt(word, keyStr) {
-  keyStr = keyStr ? keyStr : "abcdefgabcdefg12";
-  var key = CryptoJS.enc.Utf8.parse(keyStr); //Latin1 w8m31+Yy/Nw6thPsMpO5fg==
-  var srcs = CryptoJS.enc.Utf8.parse(word);
-  var encrypted = CryptoJS.AES.encrypt(srcs, key, {
-    mode: CryptoJS.mode.ECB,
-    padding: CryptoJS.pad.Pkcs7,
-  });
-  return encrypted.toString();
+//  获取命令行所在的目录
+function getRunCliPath({ directory = false, root = false } = {}) {
+  const __filename = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)));
+  const __dirname = path.dirname(__filename);
+  if (root) {
+    return path.resolve(__dirname, "../");
+  }
+  return directory ? __dirname : __filename;
 }
 
-function login(data) {
-  data.password = encrypt(md5$1(data.password));
-  const env=data.env;
-  Loading$1.start(`${env}: 登录中...`);
-  return new Promise((resolve, reject) => {
-    request(
-      {
-        url: `https://${
-          env === "pro" ? "" : `${env}-`
-        }hxjf.hongxinshop.com/sys/login`,
-        method: "POST",
-        json: true,
-        body: data,
-      },
-      function (error, response, body) {
-        const res = body || {};
-        if (!error && res.code == 200) {
-          Loading$1.succeed(`${env}: 登录成功`);
-          const access_token = res.data.access_token;
-          resolve(access_token);
-        } else {
-          Loading$1.fail(`${env}: 登录失败`);
-          reject(error || res.msg || "未知错误");
-        }
-      }
-    );
-  });
+// 获取package.json
+function getPackageJson() {
+  const packageJson = JSON.parse(
+    fs.readFileSync(path.resolve(getRunCliPath({ root: true }), "../package.json"))
+  );
+  return packageJson;
+}
+// 判断是否存在该路径
+function isExistPath(path) {
+  return fs.existsSync(path);
+}
+
+// 写入缓存
+function writeCache(key, value) {
+  fs.writeFileSync(getRunCliPath({ root: true }) + "/.cache/" + key, value);
+}
+// 读取缓存
+function readCache(key) {
+  return fs.readFileSync(getRunCliPath({ root: true }) + "/.cache/" + key);
+}
+
+//加密
+function encrypt(word, keyStr) {
+  keyStr = keyStr ? keyStr : "abcdefgabcdefg12";
+  var key = CryptoJS.enc.Utf8.parse(keyStr); //Latin1 w8m31+Yy/Nw6thPsMpO5fg==
+  var srcs = CryptoJS.enc.Utf8.parse(word);
+  var encrypted = CryptoJS.AES.encrypt(srcs, key, {
+    mode: CryptoJS.mode.ECB,
+    padding: CryptoJS.pad.Pkcs7,
+  });
+  return encrypted.toString();
+}
+
+// 鉴权失败判定: HTTP 401 或响应体 code 401 (集中一处, 后端标识变化只需改这里)
+function isAuthError(response, res) {
+  return response?.statusCode === 401 || res?.code === 401;
+}
+
+// 确保 .cache 目录存在(-sass/-lintc 硬编码账号不走凭据询问, 目录可能不存在)
+function ensureCacheDir$2() {
+  const cacheDir = getRunCliPath({ root: true }) + "/.cache";
+  if (!isExistPath(cacheDir)) {
+    fs.mkdirSync(cacheDir);
+  }
+}
+
+// 读取整个 token 缓存 map(格式: { "env#username": token }), 文件不存在/损坏时返回 {}
+function readTokenMap() {
+  const cacheFilePath = getRunCliPath({ root: true }) + "/.cache/token";
+  if (!isExistPath(cacheFilePath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readCache("token").toString("utf8")) || {};
+  } catch (error) {
+    return {};
+  }
+}
+
+// 读取指定环境+账号的缓存 token
+function readTokenCache(env, username) {
+  return readTokenMap()[`${env}#${username}`] || null;
+}
+
+// 写入 token 缓存(按 env#username 维度隔离, 避免不同账号/环境串 token)
+function writeTokenCache(env, username, token) {
+  ensureCacheDir$2();
+  const map = readTokenMap();
+  map[`${env}#${username}`] = token;
+  writeCache("token", JSON.stringify(map));
+}
+
+// 清除指定环境+账号的缓存 token
+function clearTokenCache(env, username) {
+  const cacheFilePath = getRunCliPath({ root: true }) + "/.cache/token";
+  if (!isExistPath(cacheFilePath)) {
+    return;
+  }
+  const map = readTokenMap();
+  delete map[`${env}#${username}`];
+  writeCache("token", JSON.stringify(map));
+}
+
+function login(data) {
+  data.password = encrypt(md5$1(data.password));
+  const env = data.env;
+  Loading$1.start(`${env}: 登录中...`);
+  return new Promise((resolve, reject) => {
+    request(
+      {
+        url: `https://${
+          env === "pro" ? "" : `${env}-`
+        }hxjf.hongxinshop.com/sys/login`,
+        method: "POST",
+        json: true,
+        body: data,
+      },
+      function (error, response, body) {
+        const res = body || {};
+        if (!error && res.code == 200) {
+          Loading$1.succeed(`${env}: 登录成功`);
+          const access_token = res.data.access_token;
+          // 登录成功后缓存 token, 后续执行复用免登录
+          writeTokenCache(env, data.username, access_token);
+          resolve(access_token);
+        } else {
+          Loading$1.fail(`${env}: 登录失败`);
+          reject(error || res.msg || "未知错误");
+        }
+      }
+    );
+  });
+}
+
+/**
+ * 创建登录态管理器: 优先复用缓存 token, 鉴权失败时自动重登并重试一次
+ * @param credentials { env, username, password }
+ * @returns {{ request(fn): Promise }} fn 接收当前 token; 若 fn reject 的错误带 isAuthError 标记, 自动重登后用新 token 重试
+ */
+async function createAuth({ env, username, password }) {
+  let token = readTokenCache(env, username);
+  if (token) {
+    console.log(chalk.gray(`${env}: 复用缓存登录态`));
+  } else {
+    token = await login({ env, username, password }); // login 内部已写缓存
+  }
+  let relogging = null; // 并发重登去重(如 Promise.all 批量请求同时 401)
+  return {
+    async request(fn) {
+      try {
+        return await fn(token);
+      } catch (e) {
+        if (!e?.isAuthError) throw e;
+        if (!relogging) {
+          relogging = (async () => {
+            clearTokenCache(env, username);
+            console.log(
+              chalk.yellow(`${env}: 登录态已失效, 自动重新登录...`)
+            );
+            token = await login({ env, username, password });
+          })().catch((e) => {
+            // 重登失败复位, 同进程后续请求仍可再次触发重登
+            relogging = null;
+            throw e;
+          });
+        }
+        await relogging;
+        relogging = null;
+        // 重试不再捕获, 再失败直接抛出, 避免无限循环
+        return await fn(token);
+      }
+    },
+  };
 }
 
 function importExcel({ uploadFilePath, token, env }) {
@@ -184,6 +308,11 @@ function importExcel({ uploadFilePath, token, env }) {
         if (!error && res.code == 200) {
           Loading$1.succeed(`${env}: 导入文件成功`);
           resolve(true);
+        } else if (isAuthError(response, res)) {
+          Loading$1.fail(`${env}: 登录态已失效`);
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           Loading$1.fail(`${env}: 导入文件失败`);
           reject(
@@ -262,6 +391,11 @@ function uploadExcel({ data, token, env }) {
         if (!error && res.code == 200) {
           Loading$1.succeed(`${env}: 导入项目成功`);
           resolve(true);
+        } else if (isAuthError(response, res)) {
+          Loading$1.fail(`${env}: 登录态已失效`);
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           Loading$1.fail(`${env}: 导入项目失败`);
           reject(error || res.msg || res.message || "未知错误");
@@ -271,39 +405,8 @@ function uploadExcel({ data, token, env }) {
   });
 }
 
-//  获取命令行所在的目录
-function getRunCliPath({ directory = false, root = false } = {}) {
-  const __filename = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('index.js', document.baseURI).href)));
-  const __dirname = path.dirname(__filename);
-  if (root) {
-    return path.resolve(__dirname, "../");
-  }
-  return directory ? __dirname : __filename;
-}
-
-// 获取package.json
-function getPackageJson() {
-  const packageJson = JSON.parse(
-    fs.readFileSync(path.resolve(getRunCliPath({ root: true }), "../package.json"))
-  );
-  return packageJson;
-}
-// 判断是否存在该路径
-function isExistPath(path) {
-  return fs.existsSync(path);
-}
-
-// 写入缓存
-function writeCache(key, value) {
-  fs.writeFileSync(getRunCliPath({ root: true }) + "/.cache/" + key, value);
-}
-// 读取缓存
-function readCache(key) {
-  return fs.readFileSync(getRunCliPath({ root: true }) + "/.cache/" + key);
-}
-
 // 确保 .cache 目录存在
-function ensureCacheDir() {
+function ensureCacheDir$1() {
   const cacheDir = getRunCliPath({ root: true }) + "/.cache";
   if (!isExistPath(cacheDir)) {
     fs.mkdirSync(cacheDir);
@@ -363,7 +466,7 @@ async function resolveSecretQuestions({
   cacheKey,
   extraCache = {},
 }) {
-  ensureCacheDir();
+  ensureCacheDir$1();
   const cacheSecret = readSecretCache(cacheKey);
   const resolved = {};
   const pendingQuestions = [];
@@ -403,8 +506,8 @@ const sleep = (time) =>
     setTimeout(resolve, time);
   });
 // 上传翻译包(支持 --env/--files/--username/--password/--cache 一键, 参数齐全时跳过确认/选择)
-async function upload$1(cliOpts = {}) {
-  // 空字符串视为未传(与askOrUse语义一致); 兼容交互菜单的to-前缀值(如 to-mit,sit,uat)
+async function upload$1(cliOpts = {}) {
+  // 空字符串视为未传(与askOrUse语义一致); 兼容交互菜单的to-前缀值(如 to-mit,sit,uat)
   const cliEnv = (cliOpts.env || undefined)?.replace(/^to-/, "");
   const cliFiles = cliOpts.files || undefined;
   const cliUsername = cliOpts.username || undefined;
@@ -636,10 +739,10 @@ async function upload$1(cliOpts = {}) {
   // 环境外层循环(每个环境只登录一次)，文件内层循环批量上传
   const failList = [];
   for (const env of envList) {
-    // 1.登录
-    let token;
+    // 1.登录(优先复用缓存token, 失效自动重登)
+    let auth;
     try {
-      token = await login({
+      auth = await createAuth({
         env,
         username,
         password,
@@ -655,20 +758,24 @@ async function upload$1(cliOpts = {}) {
         // 2.读取excel
         const projectList = await readExcel({ uploadFilePath });
         // 3.导入excel
-        await importExcel({
-          uploadFilePath,
-          token,
-          env,
-        });
+        await auth.request((t) =>
+          importExcel({
+            uploadFilePath,
+            token: t,
+            env,
+          })
+        );
         await sleep(2000);
         // 4.上传
-        await uploadExcel({
-          data: {
-            projectList,
-          },
-          token,
-          env,
-        });
+        await auth.request((t) =>
+          uploadExcel({
+            data: {
+              projectList,
+            },
+            token: t,
+            env,
+          })
+        );
         console.log(
           `🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀${env} ${excelFileName} 成功`
         );
@@ -1086,6 +1193,10 @@ function getApplicationList({ appName, env, token }) {
               };
             })
           );
+        } else if (isAuthError(response, res)) {
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           const errorData = error || JSON.stringify(res.data);
           reject(errorData);
@@ -1116,6 +1227,11 @@ function getApplicationConfig({ appId, env, token }) {
         if (!error && res.code == 200) {
           Loading$1.succeed(`获取应用配置成功`);
           resolve(res.data);
+        } else if (isAuthError(response, res)) {
+          Loading$1.fail(`登录态已失效`);
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           Loading$1.fail(`获取应用配置失败`);
           const errorData = error || JSON.stringify(res.data);
@@ -1147,6 +1263,11 @@ function getApplicationButtonConfig({ appId, env, token }) {
         if (!error && res.code == 200) {
           Loading$1.succeed(`获取${env}环境按钮权限配置成功`);
           resolve(res.data);
+        } else if (isAuthError(response, res)) {
+          Loading$1.fail(`登录态已失效`);
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           Loading$1.fail(`获取${env}环境按钮权限配置失败`);
           const errorData = error || JSON.stringify(res.data);
@@ -1176,6 +1297,10 @@ function deleteApplicationButtonConfig({ data, env, token }) {
         const res = body;
         if (!error && res.code == 200) {
           resolve(res.data);
+        } else if (isAuthError(response, res)) {
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           const errorData = error || JSON.stringify(res.data);
           reject(errorData);
@@ -1206,6 +1331,11 @@ function addApplicationButtonConfig({ data, env, token }) {
         if (!error && res.code == 200) {
           Loading$1.succeed(`${data.code}`);
           resolve(true);
+        } else if (isAuthError(response, res)) {
+          Loading$1.fail(`登录态已失效`);
+          reject(
+            Object.assign(new Error("登录态已失效"), { isAuthError: true })
+          );
         } else {
           Loading$1.fail(`${data.code}`);
           const errorData = error || JSON.stringify(res.data);
@@ -1305,9 +1435,9 @@ async function syncSassFlow(cliOpts) {
     type: "list",
     choices: envList.filter((item) => item !== from),
   });
-  let token;
+  let auth;
   try {
-    token = await login({
+    auth = await createAuth({
       env: from,
       username: "superAdmin",
       password: "admin1",
@@ -1329,11 +1459,13 @@ async function syncSassFlow(cliOpts) {
   });
   let applicationList;
   try {
-    applicationList = await getApplicationList({
-      env: from,
-      token,
-      appName: inputAppName,
-    });
+    applicationList = await auth.request((t) =>
+      getApplicationList({
+        env: from,
+        token: t,
+        appName: inputAppName,
+      })
+    );
   } catch (e) {
     console.log(chalk.red(`查询${from}环境应用列表失败: ${e.message || e}`));
     process.exit(1);
@@ -1371,11 +1503,13 @@ async function syncSassFlow(cliOpts) {
   const appId = applicationList.find((item) => item.name === appName).id;
   let fromButtonList;
   try {
-    fromButtonList = await getApplicationButtonConfig({
-      appId,
-      env: from,
-      token,
-    });
+    fromButtonList = await auth.request((t) =>
+      getApplicationButtonConfig({
+        appId,
+        env: from,
+        token: t,
+      })
+    );
   } catch (e) {
     console.log(
       chalk.red(`获取${from}环境按钮权限配置失败: ${e.message || e}`)
@@ -1387,9 +1521,9 @@ async function syncSassFlow(cliOpts) {
     process.exit(1);
   }
   console.log(`开始同步到${to}🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀🚀`);
-  let toToken;
+  let toAuth;
   try {
-    toToken = await login({
+    toAuth = await createAuth({
       env: to,
       username: "superAdmin",
       password: "admin1",
@@ -1400,11 +1534,13 @@ async function syncSassFlow(cliOpts) {
   }
   let toApplicationList;
   try {
-    toApplicationList = await getApplicationList({
-      env: to,
-      token: toToken,
-      appName,
-    });
+    toApplicationList = await toAuth.request((t) =>
+      getApplicationList({
+        env: to,
+        token: t,
+        appName,
+      })
+    );
   } catch (e) {
     console.log(chalk.red(`查询${to}环境应用列表失败: ${e.message || e}`));
     process.exit(1);
@@ -1416,11 +1552,13 @@ async function syncSassFlow(cliOpts) {
   const toAppId = toApplicationList[0].id;
   let toButtonList;
   try {
-    toButtonList = await getApplicationButtonConfig({
-      appId: toAppId,
-      env: to,
-      token: toToken,
-    });
+    toButtonList = await toAuth.request((t) =>
+      getApplicationButtonConfig({
+        appId: toAppId,
+        env: to,
+        token: t,
+      })
+    );
   } catch (e) {
     console.log(chalk.red(`获取${to}环境按钮权限配置失败: ${e.message || e}`));
     process.exit(1);
@@ -1428,14 +1566,16 @@ async function syncSassFlow(cliOpts) {
   try {
     if (toButtonList.length) {
       const deleteButtonPromiseList = toButtonList.map((item) => {
-        return deleteApplicationButtonConfig({
-          data: {
-            id: item.id,
-            ver: item.ver,
-          },
-          env: to,
-          token: toToken,
-        });
+        return toAuth.request((t) =>
+          deleteApplicationButtonConfig({
+            data: {
+              id: item.id,
+              ver: item.ver,
+            },
+            env: to,
+            token: t,
+          })
+        );
       });
       Loading$1.start(`删除${to}环境按钮权限配置中...`);
       await Promise.all(deleteButtonPromiseList);
@@ -1449,17 +1589,19 @@ async function syncSassFlow(cliOpts) {
     try {
       for (const item of fromButtonList) {
         const { code, name, visitConf } = item;
-        await addApplicationButtonConfig({
-          env: to,
-          token: toToken,
-          data: {
-            code1: code.split(":")[0],
-            code,
-            name,
-            visitConf,
-            ascriptionApp: toAppId,
-          },
-        });
+        await toAuth.request((t) =>
+          addApplicationButtonConfig({
+            env: to,
+            token: t,
+            data: {
+              code1: code.split(":")[0],
+              code,
+              name,
+              visitConf,
+              ascriptionApp: toAppId,
+            },
+          })
+        );
       }
       console.log(chalk.green("同步成功"));
     } catch (e) {
@@ -1497,9 +1639,9 @@ async function addSassPermission(cliOpts = {}) {
     type: "list",
     choices: envList,
   });
-  let token;
+  let auth;
   try {
-    token = await login({
+    auth = await createAuth({
       env,
       username: "superAdmin",
       password: "admin1",
@@ -1521,11 +1663,13 @@ async function addSassPermission(cliOpts = {}) {
   });
   let applicationList;
   try {
-    applicationList = await getApplicationList({
-      env,
-      token,
-      appName: inputAppName,
-    });
+    applicationList = await auth.request((t) =>
+      getApplicationList({
+        env,
+        token: t,
+        appName: inputAppName,
+      })
+    );
   } catch (e) {
     console.log(chalk.red(`查询${env}环境应用列表失败: ${e.message || e}`));
     process.exit(1);
@@ -1564,93 +1708,1923 @@ async function addSassPermission(cliOpts = {}) {
       appName = res.appName;
     }
   }
-  let appConfig;
-  try {
-    appConfig = await getApplicationConfig({ appId, env, token });
-  } catch (e) {
-    console.log(chalk.red(`获取应用配置失败: ${e.message || e}`));
+  let appConfig;
+  try {
+    appConfig = await auth.request((t) =>
+      getApplicationConfig({ appId, env, token: t })
+    );
+  } catch (e) {
+    console.log(chalk.red(`获取应用配置失败: ${e.message || e}`));
+    process.exit(1);
+  }
+  // CLI传入的权限名称/编码仅第一圈消费, 后续圈次走交互输入
+  let cliName = cliPermissionName;
+  let cliCode = cliPermissionCode;
+  let goOn = true;
+  while (goOn) {
+    const permissionName = await askOrUse(cliName, {
+      message: "请输入权限名称",
+      name: "permissionName",
+      type: "input",
+      validate: function (value) {
+        if (value) {
+          return true;
+        }
+        return "请输入权限名称";
+      },
+    });
+    const permissionCode = await askOrUse(cliCode, {
+      message: "请输入权限编码",
+      name: "permissionCode",
+      type: "input",
+      validate: function (value) {
+        if (!value) {
+          return "请输入权限编码";
+        }
+        if (value.includes(":")) {
+          return "权限编码不允许包含 :";
+        }
+        return true;
+      },
+    });
+    cliName = undefined;
+    cliCode = undefined;
+    const data = {
+      code1: appConfig.code,
+      name: permissionName,
+      visitConf: permissionCode,
+      ascriptionApp: appConfig.id,
+      code: `${appConfig.code}:${permissionCode}`,
+    };
+    let confirmed = true;
+    if (!oneClick) {
+      const { confirmAdd } = await inquirer.prompt([
+        {
+          message: `确认新增按钮权限? ${chalk.cyan(
+            `${data.name} (${data.code})`
+          )}`,
+          name: "confirmAdd",
+          type: "confirm",
+          default: true,
+        },
+      ]);
+      confirmed = confirmAdd;
+    }
+    if (confirmed) {
+      try {
+        await auth.request((t) =>
+          addApplicationButtonConfig({ data, env, token: t })
+        );
+        console.log(
+          chalk.green(
+            `新增按钮权限成功: ${appName} - ${data.name} (${data.code})`
+          )
+        );
+      } catch (e) {
+        console.log(chalk.red(`新增按钮权限失败: ${e.message || e}`));
+        process.exit(1);
+      }
+    }
+    if (oneClick) {
+      goOn = false;
+    } else {
+      const { continueAdd } = await inquirer.prompt([
+        {
+          message: "是否继续为该应用添加按钮权限?",
+          name: "continueAdd",
+          type: "confirm",
+          default: false,
+        },
+      ]);
+      goOn = continueAdd;
+    }
+  }
+}
+
+// 禅道基础地址/缓存键(联调不符只改这里)
+const ZENTAO_BASE = "https://zentao.hongxinshop.com/zentao";
+const CACHE_KEY = "zentao"; // .cache/zentao: { account, password, zentaosid, products: [{id, name}] }
+
+// 需求列表展示与pull并发的上限
+const PLAN_STORY_TABLE_LIMIT = 50;
+const PULL_CONCURRENCY = 5;
+
+// 确保 .cache 目录存在
+function ensureCacheDir() {
+  const cacheDir = getRunCliPath({ root: true }) + "/.cache";
+  if (!isExistPath(cacheDir)) {
+    fs.mkdirSync(cacheDir);
+  }
+}
+
+// 读取禅道凭据/会话缓存(不存在/损坏返回 {})
+function readZentaoCache() {
+  const cacheFilePath =
+    getRunCliPath({ root: true }) + "/.cache/" + CACHE_KEY;
+  if (!isExistPath(cacheFilePath)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readCache(CACHE_KEY).toString("utf8")) || {};
+  } catch (error) {
+    return {};
+  }
+}
+
+// 写禅道缓存(合并写: resolveSecretQuestions 会整文件回写凭据字段, 非合并会抹掉 zentaosid)
+function writeZentaoCache(obj) {
+  ensureCacheDir();
+  writeCache(
+    CACHE_KEY,
+    JSON.stringify({ ...readZentaoCache(), ...obj })
+  );
+}
+
+/**
+ * 原样移植自禅道 12.3.1 all.js, 勿改动逻辑(服务端密码强度校验用)
+ */
+function computePasswordStrength(password) {
+  if (password.length === 0) return 0;
+  let strength = 0;
+  const length = password.length;
+  let distinct = "";
+  const kinds = {};
+  for (let i = 0; i < length; i++) {
+    const code = password.charCodeAt(i);
+    if (code >= 48 && code <= 57) kinds[2] = 2; // 数字
+    else if (code >= 65 && code <= 90) kinds[1] = 2; // 大写字母
+    else if (code >= 97 && code <= 122) kinds[0] = 1; // 小写字母
+    else kinds[3] = 3; // 特殊字符
+    if (distinct.indexOf(password[i]) === -1) distinct += password[i];
+  }
+  if (distinct.length > 4) strength += distinct.length - 4;
+  let sum = 0;
+  let count = 0;
+  for (const key in kinds) {
+    count += 1;
+    sum += kinds[key];
+  }
+  strength += sum + 2 * (count - 1);
+  if (length < 6 && strength >= 10) strength = 9;
+  strength = strength > 29 ? 29 : strength;
+  return Math.floor(strength / 10);
+}
+
+/**
+ * 禅道 .json 路由请求(响应信封: {status, data: "<再编码JSON字符串>", md5})
+ * 会话过期判定(实测): 禅道返回 200 + JS 跳转页(非302), content-type 不可靠(正常响应也是 text/html),
+ * 用 body 解析失败 / 含 user-login 判定
+ */
+function zentaoRequest({ route, zentaosid, qs }) {
+  return new Promise((resolve, reject) => {
+    request(
+      {
+        url: `${ZENTAO_BASE}/${route}.json`,
+        method: "GET",
+        headers: {
+          Cookie: `zentaosid=${zentaosid}`,
+          // ajax 标识, 禅道据此返回 JSON
+          "X-Requested-With": "XMLHttpRequest",
+        },
+        ...(qs ? { qs } : {}),
+      },
+      (error, response, body) => {
+        if (error) return reject(error);
+        const text = String(body).replace(/^\uFEFF/, "");
+        if (/^\s*<html/i.test(text)) {
+          // 实测过期返回 200 + JS跳转页(<html><meta...><script>self.location='/zentao/user-login-...')
+          // 不用 includes("user-login"): 防需求正文含该字样误判
+          return reject(
+            Object.assign(new Error("禅道会话已失效"), { isAuthError: true })
+          );
+        }
+        let envelope;
+        try {
+          envelope = JSON.parse(text);
+        } catch (e) {
+          return reject(
+            Object.assign(new Error("禅道会话已失效"), { isAuthError: true })
+          );
+        }
+        if (envelope.status !== "success") {
+          return reject(
+            new Error(
+              envelope.message || `禅道接口返回失败: ${envelope.status}`
+            )
+          );
+        }
+        // 响应信封 data 是再编码的 JSON 字符串, 需二次 parse
+        let data = envelope.data;
+        if (typeof data === "string") {
+          try {
+            data = JSON.parse(data);
+          } catch (e) {
+            /* data 本身就是普通值 */
+          }
+        }
+        resolve(data);
+      }
+    );
+  });
+}
+
+/**
+ * 禅道 POST 请求(写操作, 实测 task-create 等创建类接口, 12.3.1):
+ * - 响应信封是 {result: 'success'|'fail', message, locate}, 与 GET 的 {status, data} 不同
+ * - message 校验失败时是对象(如 {estStarted: [『预计开始』不能为空。]}), 统一格式化为文本
+ * - form 字段名必须对齐表单真实 name(如 assignedTo[]): 实测传多余字段(mailto/after/hiddenwin)
+ *   或 desc 含 HTML 标签时, 会出现"返回保存成功但未落库"或空响应, 只传验证过的最小字段集
+ */
+function zentaoPost({ route, zentaosid, form }) {
+  return new Promise((resolve, reject) => {
+    request(
+      {
+        url: `${ZENTAO_BASE}/${route}.json`,
+        method: "POST",
+        form,
+        headers: {
+          Cookie: `zentaosid=${zentaosid}`,
+          // 不带此头返回 HTML 而非 JSON
+          "X-Requested-With": "XMLHttpRequest",
+          // 模拟页面表单提交来源(实测带上更接近浏览器行为)
+          Referer: `${ZENTAO_BASE}/${route}.html`,
+        },
+      },
+      (error, _response, body) => {
+        if (error) return reject(error);
+        const text = String(body).replace(/^\uFEFF/, "");
+        if (/^\s*<html/i.test(text)) {
+          return reject(
+            Object.assign(new Error("禅道会话已失效"), { isAuthError: true })
+          );
+        }
+        let envelope;
+        try {
+          envelope = JSON.parse(text);
+        } catch (e) {
+          return reject(
+            Object.assign(new Error("禅道会话已失效"), { isAuthError: true })
+          );
+        }
+        if (envelope.result === "success") {
+          return resolve(envelope);
+        }
+        const message = envelope.message;
+        const detail =
+          typeof message === "string"
+            ? message
+            : Object.values(message || {})
+                .map((v) => (Array.isArray(v) ? v.join("; ") : String(v)))
+                .join("; ");
+        return reject(new Error(detail || `禅道接口返回失败: ${JSON.stringify(envelope)}`));
+      }
+    );
+  });
+}
+
+/**
+ * 禅道三步登录(实测协议, 12.3.1):
+ * 1. GET 登录页建立会话(下发 zentaosid, 登录前后不变) + 提取 verifyRand(每会话不同)
+ * 2. 计算 password = md5(md5(明文) + verifyRand)
+ * 3. POST 七字段表单(带 X-Requested-With 才返回 JSON), 成功判定 result === 'success'
+ */
+function zentaoLogin({ account, password }) {
+  Loading$1.start("登录中...");
+  // 第1步: GET 登录页, 提取 zentaosid + verifyRand
+  const pre = new Promise((resolve, reject) => {
+    request(
+      { url: `${ZENTAO_BASE}/user-login.html`, method: "GET" },
+      (error, response, body) => {
+        if (error) return reject(error);
+        const setCookies = response.headers["set-cookie"] || [];
+        const sidMatch = setCookies
+          .join(";")
+          .match(/zentaosid=([^;]+)/);
+        const randMatch = String(body).match(
+          /name='verifyRand'[^>]*value='(\d+)'/
+        );
+        if (!sidMatch || !randMatch) {
+          return reject(new Error("解析登录页失败(未找到 zentaosid/verifyRand)"));
+        }
+        resolve({ zentaosid: sidMatch[1], verifyRand: randMatch[1] });
+      }
+    );
+  });
+  // 第2/3步: 计算哈希并 POST(POST 须带会话 cookie, verifyRand 与会话绑定)
+  return pre.then(async ({ zentaosid, verifyRand }) => {
+    const result = await new Promise((resolve, reject) => {
+      request(
+        {
+          url: `${ZENTAO_BASE}/user-login.html`,
+          method: "POST",
+          form: {
+            account,
+            password: md5$1(md5$1(password) + verifyRand),
+            pww: password, // 服务端强度校验用, 原样上送
+            passwordStrength: computePasswordStrength(password),
+            referer: "",
+            verifyRand,
+            keepLogin: "0",
+          },
+          headers: {
+            Cookie: `zentaosid=${zentaosid}`,
+            // 不带此头返回 HTML 而非 JSON
+            "X-Requested-With": "XMLHttpRequest",
+          },
+        },
+        (error, _response, body) => {
+          if (error) return reject(error);
+          try {
+            resolve(JSON.parse(String(body).replace(/^\uFEFF/, "")));
+          } catch (e) {
+            reject(new Error("登录响应解析失败"));
+          }
+        }
+      );
+    });
+    if (result.result === "success") {
+      Loading$1.succeed("登录成功");
+      // zentaosid 在 GET 那步就下发且登录后不变, 成功判定看 result
+      writeZentaoCache({ account, password, zentaosid });
+      return zentaosid;
+    }
+    Loading$1.fail("登录失败");
+    throw new Error(`登录失败: ${result.message || "请检查账号密码"}`);
+  });
+}
+
+// 凭据解析(CLI参数 > --cache缓存 > 交互), login 与无会话时的 plan/detail 共用
+function askZentaoCredentials(cliOpts) {
+  return resolveSecretQuestions({
+    questions: [
+      {
+        message: "请输入禅道账号",
+        name: "account",
+        type: "input",
+        validate: (val) => Boolean(val) || "请输入禅道账号",
+      },
+      {
+        message: "请输入禅道密码",
+        name: "password",
+        type: "password",
+        mask: "*",
+        validate: (val) => Boolean(val) || "请输入禅道密码",
+      },
+    ],
+    cliValues: {
+      account: cliOpts.username,
+      password: cliOpts.password,
+    },
+    useCache: Boolean(cliOpts.cache),
+    cacheKey: CACHE_KEY,
+  }).then((secret) => {
+    // resolveSecretQuestions 会整文件覆盖回写缓存(只剩凭据字段, 发生在登录之前),
+    // 合并写补回 zentaosid 等字段, 防止登录失败时已缓存的有效会话被抹掉
+    writeZentaoCache(secret);
+    return secret;
+  });
+}
+
+/**
+ * 会话管理(参考 createAuth): 优先缓存 zentaosid, isAuthError 时用凭据自动重登并重试一次
+ * (重登即重走三步——旧会话已失效, 必须新 GET 拿新 verifyRand)
+ */
+async function ensureZentaoSession(cliOpts) {
+  const cache = readZentaoCache();
+  // 重登凭据优先级: CLI 参数 > 缓存
+  const credentials = {
+    account: cliOpts.username || cache.account,
+    password: cliOpts.password || cache.password,
+  };
+  let zentaosid = cache.zentaosid;
+  if (!zentaosid) {
+    const secret = await askZentaoCredentials(cliOpts);
+    zentaosid = await zentaoLogin(secret);
+  }
+  let relogging = null; // 并发重登去重
+  return {
+    async request(fn) {
+      try {
+        return await fn(zentaosid);
+      } catch (e) {
+        if (!e?.isAuthError) throw e;
+        if (!credentials.account || !credentials.password) {
+          console.log(
+            chalk.red(
+              "禅道会话已失效且无缓存凭据, 请先执行: fe-it-beta story login"
+            )
+          );
+          process.exit(1);
+        }
+        if (!relogging) {
+          relogging = (async () => {
+            console.log(chalk.yellow("禅道会话已失效, 自动重新登录..."));
+            zentaosid = await zentaoLogin(credentials);
+          })().catch((e) => {
+            // 重登失败复位, 同进程后续请求仍可再次触发重登
+            relogging = null;
+            throw e;
+          });
+        }
+        await relogging;
+        relogging = null;
+        // 重试不再捕获, 再失败直接抛出, 避免无限循环
+        return await fn(zentaosid);
+      }
+    },
+  };
+}
+
+// 拉产品映射: product-all.json -> data.products = { 产品ID: 产品名 } (实测104个)
+function fetchProductMap(zentaosid) {
+  return zentaoRequest({ route: "product-all", zentaosid }).then(
+    (data) => data.products || {}
+  );
+}
+
+// 校验产品ID并返回 {id, name}, 同时存入缓存历史(最近使用的排最前, 去重)
+async function resolveProduct(zentaosid, productID) {
+  productID = String(productID).trim();
+  Loading$1.start("校验产品中...");
+  const products = await fetchProductMap(zentaosid);
+  const name = products[productID];
+  if (!name) {
+    Loading$1.fail("产品不存在");
+    throw new Error(`产品ID ${productID} 不存在, 请检查后重试`);
+  }
+  Loading$1.succeed(`产品: #${productID} ${name}`);
+  const history = readZentaoCache().products || [];
+  const rest = history.filter((p) => p.id !== productID);
+  writeZentaoCache({ products: [{ id: productID, name }, ...rest] });
+  return { id: productID, name };
+}
+
+// 产品选择(plan/pull共用): --product参数直通 > 历史缓存选择/手动输入
+async function selectProduct(zentaosid, cliOpts) {
+  const cliProduct = cliOpts.product && String(cliOpts.product).trim();
+  if (cliProduct) {
+    return resolveProduct(zentaosid, cliProduct);
+  }
+  const history = readZentaoCache().products || [];
+  if (history.length) {
+    const { choice } = await inquirer.prompt([
+      {
+        message: "请选择产品",
+        name: "choice",
+        type: "rawlist",
+        choices: [
+          ...history.map((p) => ({
+            name: `#${p.id} ${p.name}`,
+            value: p.id,
+          })),
+          { name: "输入其他产品ID...", value: "__INPUT__" },
+        ],
+      },
+    ]);
+    if (choice !== "__INPUT__") {
+      const cached = history.find((p) => p.id === choice);
+      return cached; // 历史产品名称已缓存, 直接用
+    }
+  }
+  const { id } = await inquirer.prompt([
+    {
+      message: "请输入产品ID",
+      name: "id",
+      type: "input",
+      validate: (val) =>
+        /^\d+$/.test(String(val).trim()) || "请输入数字产品ID",
+    },
+  ]);
+  return resolveProduct(zentaosid, id);
+}
+
+// 拉计划列表第1页(默认20条, begin倒序最新在前, 用户指定只取1页)
+function fetchPlanList(zentaosid, productID) {
+  return zentaoRequest({
+    route: `productplan-browse-${productID}`,
+    zentaosid,
+  }).then((data) => Object.values(data.plans || {}));
+}
+
+// 拉计划详情: plan + planStories(全量无分页) + products(产品ID->名称映射)
+function fetchPlanDetail(zentaosid, planID) {
+  return zentaoRequest({
+    route: `productplan-view-${planID}`,
+    zentaosid,
+  }).then((data) => ({
+    plan: data.plan,
+    stories: Object.values(data.planStories || {}),
+    products: data.products || {},
+  }));
+}
+
+// 拉需求详情: story(全字段, spec/verify 为HTML) + users(用户名映射)
+function fetchStoryDetail(zentaosid, storyID) {
+  return zentaoRequest({ route: `story-view-${storyID}`, zentaosid }).then(
+    (data) => ({
+      story: data.story,
+      users: data.users || {},
+    })
+  );
+}
+
+// 拉全量项目映射: project-all.json -> data.projects = { 项目ID: 项目名 } (实测2884个, task入参校验用)
+function fetchProjectMap(zentaosid) {
+  return zentaoRequest({ route: "project-all", zentaosid }).then(
+    (data) => data.projects || {}
+  );
+}
+
+// 拉项目需求列表: project(项目信息) + stories(需求)
+function fetchProjectStories(zentaosid, projectID) {
+  return zentaoRequest({
+    route: `project-story-${projectID}`,
+    zentaosid,
+  }).then((data) => ({
+    project: data.project,
+    stories: Object.values(data.stories || {}),
+  }));
+}
+
+// 拉项目任务列表(全部状态, 不含已删除; 供勾选时统计已建任务数 + 创建前后 diff 拿新任务ID)
+// 注1: 不用禅道 storyWebTasks/storyDevTasks 计数——软删除(回收站)的任务也计入, 数据不准(实测)
+// 注2: pager.recTotal 同样含回收站任务(返回数恒小于 recTotal 属正常), 翻页判定用 pageTotal
+// 注3: 子任务不出现在任务列表(挂在父任务 children 下), 子任务统计须逐任务拉 task-view
+function fetchProjectTasks(zentaosid, projectID) {
+  return zentaoRequest({
+    route: `project-task-${projectID}-all`,
+    zentaosid,
+  }).then((data) => ({
+    tasks: Object.values(data.tasks || {}),
+    pageTotal: Number(data.pager?.pageTotal || 1),
+  }));
+}
+
+// 拉单个任务详情(含children子任务映射, subtask命令与子任务统计用)
+function fetchTaskDetail(zentaosid, taskID) {
+  return zentaoRequest({ route: `task-view-${taskID}`, zentaosid }).then(
+    (data) => data.task
+  );
+}
+
+/**
+ * 在项目下为需求创建任务(实测协议, 12.3.1): POST task-create-{projectID}-{storyID}.json
+ * - estStarted/deadline 必填(缺了返回 fail + 字段错误提示)
+ * - 指派字段名是 assignedTo[](数组形式)
+ * - desc 用纯文本(实测含 HTML 标签时会出现"返回保存成功但未落库")
+ * - type 值(表单选项实测): frontend=前端开发, devel=后端开发
+ * - 成功响应 {result:'success'} 不含新任务ID, 由调用方重拉任务列表 diff 获取
+ */
+function createZentaoTask({ zentaosid, projectID, story, name, type, assignedTo, estimate, estStarted, deadline }) {
+  return zentaoPost({
+    route: `task-create-${projectID}-${story.id}`,
+    zentaosid,
+    form: {
+      module: "0",
+      "assignedTo[]": assignedTo,
+      name,
+      story: story.id,
+      type,
+      pri: String(story.pri || 3),
+      estimate: String(estimate),
+      // 纯文本描述: 附需求url便于任务页跳回
+      desc: `需求: ${storyUrl(story.id)}`,
+      estStarted,
+      deadline,
+      uid: String(Date.now()),
+    },
+  });
+}
+
+// 拼任务url(创建成功后输出)
+function taskUrl(taskID) {
+  return `${ZENTAO_BASE}/task-view-${taskID}.html`;
+}
+
+/**
+ * 子任务拆分方案(用户确认规则):
+ * - 工时>8 才拆; 每个子任务 8h, 最后一个补余数(如 20h -> 8/8/4)
+ * - 后端: 名称-1、名称-2...(序号从1递增)
+ * - 前端: 前端开发 = ceil(N/2) 个排前(整8h), 联调 = floor(N/2) 个在后(余数落最后);
+ *   同类>1个带序号(前端开发1..n), 单个不带(16h -> 名称-前端开发 / 名称-联调)
+ * - 实测样例: 16h->1+1, 24h->2+1, 40h->3+2, 48h->3+3
+ */
+function splitTaskPlan(name, hours, taskType) {
+  const total = Number(hours);
+  const count = Math.ceil(total / 8);
+  const lastEstimate = String(total - 8 * (count - 1));
+  if (taskType === "back") {
+    return Array.from({ length: count }, (_, i) => ({
+      name: `${name}-${i + 1}`,
+      estimate: i === count - 1 ? lastEstimate : "8",
+    }));
+  }
+  const devCount = Math.ceil(count / 2);
+  const qaCount = count - devCount;
+  const subs = [];
+  for (let i = 0; i < devCount; i++) {
+    subs.push({
+      name: `${name}-前端开发${devCount > 1 ? i + 1 : ""}`,
+      // 前端开发整8h(排前), 余数由最后一个联调兜
+      estimate: "8",
+    });
+  }
+  for (let i = 0; i < qaCount; i++) {
+    subs.push({
+      name: `${name}-联调${qaCount > 1 ? i + 1 : ""}`,
+      estimate: i === qaCount - 1 ? lastEstimate : "8",
+    });
+  }
+  return subs;
+}
+
+/**
+ * 批量创建子任务(实测表单结构, 12.3.1): POST task-batchCreate-{projectID}-{storyID}-0-{parentTaskID}.json
+ * - 数组字段: module[i]/parent[i]/story[i]/name[i]/type[i]/assignedTo[i]/estimate[i]/estStarted[i]/deadline[i]/pri[i]
+ * - 指派字段名是 assignedTo[i](非 assignedTo[][i], 与单任务创建的 assignedTo[] 不同)
+ * - 只传验证过的最小字段集(对齐 task-create 的实测教训: 多余字段致空响应/假成功)
+ */
+function createZentaoSubtasks({ zentaosid, projectID, story, parentTaskID, type, assignedTo, estStarted, deadline, subs }) {
+  const form = {};
+  subs.forEach((sub, i) => {
+    form[`module[${i}]`] = "0";
+    form[`parent[${i}]`] = String(parentTaskID);
+    form[`story[${i}]`] = String(story.id);
+    form[`name[${i}]`] = sub.name;
+    form[`type[${i}]`] = type;
+    form[`assignedTo[${i}]`] = assignedTo;
+    form[`estimate[${i}]`] = String(sub.estimate);
+    form[`estStarted[${i}]`] = estStarted;
+    form[`deadline[${i}]`] = deadline;
+    form[`pri[${i}]`] = String(story.pri || 3);
+  });
+  return zentaoPost({
+    route: `task-batchCreate-${projectID}-${story.id}-0-${parentTaskID}`,
+    zentaosid,
+    form,
+  });
+}
+
+// 本地时区当天日期(YYYY-MM-DD, 任务estStarted用; toISOString是UTC会差8小时)
+function localToday() {
+  const d = new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+// 拼需求url(输出给 story detail 用)
+function storyUrl(storyID) {
+  return `${ZENTAO_BASE}/story-view-${storyID}.html`;
+}
+
+// 禅道域名(从ZENTAO_BASE派生, 图片等静态资源挂根路径)
+const ZENTAO_ORIGIN = ZENTAO_BASE.replace(/\/zentao$/, "");
+
+// 需求HTML里的相对路径转绝对url(如 /zentao/file-read-xxx.png)
+function absoluteZentaoUrl(src) {
+  const s = String(src || "");
+  if (/^https?:\/\//i.test(s)) return s;
+  return `${ZENTAO_ORIGIN}${s.startsWith("/") ? "" : "/"}${s}`;
+}
+
+// 表格块转行文本: 每个<tr>一行, 单元格间 " | " 分隔, 单元格内换行/段落折叠为单空格
+// (保住字段映射表的列对应关系; 不支持嵌套表格, 禅道需求里无此结构)
+function tableToText(tableHtml) {
+  const rows = tableHtml.match(/<tr[\s\S]*?<\/tr>/gi) || [];
+  return rows
+    .map((row) =>
+      (row.match(/<t[dh][^>]*>[\s\S]*?<\/t[dh]>/gi) || [])
+        .map((cell) =>
+          cell
+            .replace(/<br\s*\/?>/gi, " ")
+            .replace(/<[^>]+>/g, " ")
+            .replace(/&nbsp;/gi, " ")
+            .replace(/&lt;/gi, "<")
+            .replace(/&gt;/gi, ">")
+            .replace(/&quot;/gi, '"')
+            .replace(/&amp;/gi, "&")
+            .replace(/\s+/g, " ")
+            .trim()
+        )
+        .join(" | ")
+    )
+    .filter(Boolean)
+    .join("\n");
+}
+
+// HTML转纯文本(spec/verify 为HTML, detail与pull共用)
+// imgHref: img标签src的转换函数(传了则img转markdown图片语法引用完整url——实测file-read无需登录态; 不传则丢弃img)
+function htmlToText(html, imgHref) {
+  let text = String(html || "");
+  if (imgHref) {
+    // img转markdown图片(先于去标签处理, 防图片信息丢失)
+    text = text.replace(
+      /<img[^>]*\bsrc=['"]([^'"]+)['"][^>]*\/?>/gi,
+      (_m, src) => `\n![图片](${imgHref(src)})\n`
+    );
+  } else {
+    text = text.replace(/<img[^>]*>/gi, "");
+  }
+  // 表格块整块转行文本(先于通用去标签): 单元格内<p>/<br>折叠为空格, 防" | "落进换行中间
+  text = text.replace(
+    /<table[\s\S]*?<\/table>/gi,
+    (m) => "\n" + tableToText(m) + "\n"
+  );
+  return text
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&amp;/gi, "&")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+// 需求涉及的项目名(供AI定位要改的代码仓), 跟随导出范围:
+// front=只前端pool截取(fe-xxx-vue->xxx) | back=只后端pool原名 | all=全部
+function storyProjectsOf(story, scope) {
+  return parsePoolList(story.poollist)
+    .map((pool) => {
+      const frontProject = frontProjectOf(pool);
+      if (scope === "front") return frontProject; // 非前端pool返回null被过滤
+      if (scope === "back") return frontProject ? null : pool; // 后端pool原名
+      return frontProject || pool;
+    })
+    .filter(Boolean);
+}
+
+// 任务目录名: {storyID}-{title截断50 + 过滤文件系统非法字符(含首尾空格与点)}
+function taskDirOf(story) {
+  const title = String(story.title || "")
+    .slice(0, 50)
+    .replace(/[\\/:*?"<>|]/g, "")
+    .trim()
+    .replace(/^[.\s]+|[.\s]+$/g, "");
+  return `${story.id}-${title}`;
+}
+
+// 需求目录名: .zentao-<计划名>(多计划互不混目录); 计划名过滤文件系统非法字符, 空则退回计划id
+function zentaoDirNameOf(plan) {
+  const name = String((plan && plan.title) || "")
+    .slice(0, 50)
+    .replace(/[\\/:*?"<>|]/g, "")
+    .trim()
+    .replace(/^[.\s]+|[.\s]+$/g, "");
+  return `.zentao-${name || (plan && plan.id) || "untitled"}`;
+}
+
+// 下载禅道静态资源(图片), encoding:null 取Buffer; 带会话Cookie(实测file-read无需登录态, 带上更稳)
+function fetchZentaoImage(url, zentaosid) {
+  return new Promise((resolve, reject) => {
+    request(
+      {
+        url,
+        method: "GET",
+        encoding: null,
+        headers: { Cookie: `zentaosid=${zentaosid}` },
+      },
+      (error, response, body) => {
+        if (error) return reject(error);
+        if (response.statusCode !== 200) {
+          return reject(new Error(`HTTP ${response.statusCode}`));
+        }
+        resolve(body);
+      }
+    );
+  });
+}
+
+// 提取HTML里全部img的src(与htmlToText的img处理用同一正则)
+function extractImgSrcs(html) {
+  const srcs = [];
+  String(html || "").replace(
+    /<img[^>]*\bsrc=['"]([^'"]+)['"][^>]*\/?>/gi,
+    (_m, src) => {
+      srcs.push(src);
+      return _m;
+    }
+  );
+  return srcs;
+}
+
+// 图片本地文件名: 取url的basename, 去query, 过滤路径穿越与文件系统非法字符
+function imageFileNameOf(src) {
+  const base =
+    String(src).split("?")[0].split("/").pop().replace(/[\\/:*?"<>|]/g, "_");
+  return base && !/^\.+$/.test(base) ? base : "image";
+}
+
+/**
+ * 需求图片本地化: 提取 spec/verify 的 img src, 并发限流(复用PULL_CONCURRENCY worker池)
+ * 下载到 <zentaoDir>/tasks/<taskDir>/images/(同名taskDir已由调用方先删除, 全量重下),
+ * 返回 Map<storyID, Map<src, 'images/<文件名>'>>(下载失败的src不进映射, task.md引用降级远程url)
+ */
+async function downloadStoryImages({ stories, storyDetails, zentaosid, zentaoDir }) {
+  const tasksRoot = path.join(zentaoDir, "tasks");
+  // 平铺任务(与拉详情同模式的并发限流): {story, src}
+  const jobs = [];
+  for (const story of stories) {
+    const detail = storyDetails.get(String(story.id));
+    if (!detail) continue;
+    const srcs = extractImgSrcs(detail.story.spec).concat(
+      extractImgSrcs(detail.story.verify)
+    );
+    for (const src of srcs) jobs.push({ story, src });
+  }
+  const result = new Map();
+  const setMapping = (storyID, src, ref) => {
+    let mapping = result.get(String(storyID));
+    if (!mapping) {
+      mapping = new Map();
+      result.set(String(storyID), mapping);
+    }
+    mapping.set(src, ref);
+  };
+  let index = 0;
+  const worker = async () => {
+    while (index < jobs.length) {
+      const { story, src } = jobs[index];
+      index += 1;
+      const fileName = imageFileNameOf(src);
+      const target = path.join(tasksRoot, taskDirOf(story), "images", fileName);
+      try {
+        const buf = await fetchZentaoImage(absoluteZentaoUrl(src), zentaosid);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.writeFileSync(target, buf);
+        setMapping(story.id, src, `images/${fileName}`);
+      } catch (e) {
+        console.log(
+          chalk.yellow(`需求 ${story.id} 图片下载失败(${src}): ${e.message}, 该图保留远程链接`)
+        );
+      }
+    }
+  };
+  await Promise.all(
+    Array.from({ length: PULL_CONCURRENCY }, () => worker())
+  );
+  return result;
+}
+
+// 解析poollist为pool数组(实测为逗号分隔字符串, 值可能含制表符)
+function parsePoolList(poollist) {
+  return String(poollist || "")
+    .split(/[,\t\n]/)
+    .map((p) => p.trim())
+    .filter(Boolean);
+}
+
+// 前端pool转项目名: fe-cost-order-pc-vue -> cost-order-pc (前端pool均为fe-开头-vue结尾)
+function frontProjectOf(pool) {
+  if (/^fe-.+-vue$/.test(pool)) {
+    return pool.replace(/^fe-/, "").replace(/-vue$/, "");
+  }
+  return null;
+}
+
+// 汇总需求的pool项目名(按类型): 前端=fe-xxx-vue截取xxx, 后端=非fe-开头pool原名不截取
+// type: 'front'取有前端工时需求的前端pool | 'back'取有后端工时需求的后端pool
+function collectPoolProjects(stories, type) {
+  const projects = new Set();
+  stories.forEach((s) => {
+    const isFront = Number(s.webestimate) > 0;
+    const isBack = Number(s.estimate) > 0;
+    if (type === "front" && !isFront) return;
+    if (type === "back" && !isBack) return;
+    parsePoolList(s.poollist).forEach((pool) => {
+      if (type === "front") {
+        const project = frontProjectOf(pool);
+        if (project) projects.add(project);
+      } else if (!/^fe-/.test(pool)) {
+        projects.add(pool); // 后端pool: 原名不截取
+      }
+    });
+  });
+  return [...projects];
+}
+
+// 生成vscode/trae多项目工作区文件(.code-workspace为二者通用格式)
+// 项目路径默认按"各项目平级clone"假设取 ../<项目名>(相对需求目录.zentao-<计划名>/), 可打开后自行调整
+function writeCodeWorkspace(zentaoDir, planTitle, frontProjects, backProjects) {
+  const zentaoDirName = path.basename(zentaoDir);
+  const folders = [
+    // 第一项为需求目录.zentao-<计划名>(含tasks下的manifest与task.md, 相对workspace文件位置即自身)
+    { name: zentaoDirName, path: "." },
+  ];
+  frontProjects.forEach((name) =>
+    folders.push({ name, path: `../${name}` })
+  );
+  backProjects.forEach((name) =>
+    folders.push({ name, path: `../${name}` })
+  );
+  // 计划title含 / 等非法字符, 过滤后作文件名
+  const fileName =
+    String(planTitle || "")
+      .replace(/[\\/:*?"<>|]/g, "")
+      .trim() + ".code-workspace";
+  const wsPath = path.join(zentaoDir, fileName);
+  fs.writeFileSync(
+    wsPath,
+    // terminal.integrated.cwd 相对第一个 folder(需求目录) 解析: ".." 即调度中心目录, 打开工作区直接 claude 启动主会话
+    // zentao.projectRoot 记录 CLI 运行目录(=需求目录父目录=调度中心), 主会话组装 projectPaths 直接取用, 不依赖启动目录推断
+    // zentao.dir 记录需求目录名(.zentao-<计划名>), 主会话组装 workflow 的 zentaoDir 传参直接取用
+    JSON.stringify(
+      {
+        folders,
+        settings: {
+          "terminal.integrated.cwd": "..",
+          "zentao.projectRoot": process.cwd().replace(/\\/g, "/"),
+          "zentao.dir": zentaoDirName,
+        },
+      },
+      null,
+      2
+    ),
+    "utf8"
+  );
+  console.log(chalk.green(`工作区: ${wsPath} (vscode/trae可直接打开)`));
+  const parts = [];
+  if (frontProjects.length) parts.push(`前端: ${frontProjects.join(", ")}`);
+  if (backProjects.length) parts.push(`后端: ${backProjects.join(", ")}`);
+  if (parts.length) {
+    console.log(chalk.green(`涉及项目 ${parts.join(" | ")} (路径按平级目录假设, 可自行调整)`));
+  }
+}
+
+/**
+ * plan --export 产出需求目录 .zentao-<计划名>/(产出契约见 .trae/documents/story-command-zentao.md 第4节):
+ * tasks/manifest.json(对象结构: 顶部projects汇总全部涉及项目 + stories数组合并去重, 同storyID覆盖title/taskDir/projects, 按storyID数值排序)
+ * + 每条需求 tasks/<taskDir>/task.md(同名taskDir已由 exportPlanStories 先删除, 此处全新写入)
+ * plan.md 与 codex-*.md 是 workflow 的产物(重拉同名taskDir会连带删除, 确认关卡后不要再重导)
+ */
+function writeZentaoTasks({ plan, scope, stories, storyDetails, products, failed, storyImages, zentaoDir }) {
+  const tasksDir = path.join(zentaoDir, "tasks");
+  fs.mkdirSync(tasksDir, { recursive: true });
+
+  // manifest 合并去重(位于 tasks/ 下, 是 tasks 目录的需求索引)
+  // 结构: { projects: [全部需求涉及项目的汇总], stories: [...] }; 兼容读取旧版纯数组格式(迁移为stories, 旧条目无projects字段)
+  const manifestPath = path.join(tasksDir, "manifest.json");
+  let manifestStories = [];
+  if (isExistPath(manifestPath)) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+      manifestStories = Array.isArray(parsed)
+        ? parsed
+        : (parsed && parsed.stories) || [];
+    } catch (error) {
+      manifestStories = [];
+    }
+  }
+  const manifestMap = new Map(
+    manifestStories.map((item) => [String(item.storyID), item])
+  );
+
+  let added = 0;
+  stories.forEach((story) => {
+    // 拉取失败的条目跳过: 不写task.md(防"拉取失败"伪装成"禅道没填"产出空壳), 也不进manifest
+    if (failed.has(String(story.id))) {
+      return;
+    }
+    const taskDir = taskDirOf(story);
+    manifestMap.set(String(story.id), {
+      storyID: String(story.id),
+      title: story.title,
+      taskDir,
+      // 涉及项目(跟随导出范围, 与task.md frontmatter的projects同源), AI据此定位要改的代码仓
+      projects: storyProjectsOf(story, scope),
+    });
+    const taskPath = path.join(tasksDir, taskDir, "task.md");
+    const detail = storyDetails.get(String(story.id));
+    // 图片引用: 已本地化(images/相对路径, 与task.md同目录可直接Read)优先, 下载失败的降级远程url
+    const imgMap =
+      (storyImages && storyImages.get(String(story.id))) || new Map();
+    const imgHref = (src) => imgMap.get(src) || absoluteZentaoUrl(src);
+    const spec = detail ? htmlToText(detail.story.spec, imgHref) : "";
+    const verify = detail ? htmlToText(detail.story.verify, imgHref) : "";
+    const content = [
+      "---",
+      `storyID: "${story.id}"`,
+      // JSON.stringify转义: title含半角冒号/引号等时防frontmatter(YAML)断裂
+      `title: ${JSON.stringify(story.title)}`,
+      `product: ${JSON.stringify(products[story.product] || story.product || "")}`,
+      // plan 用选中计划title(story.planTitle 挂多计划时是拼接串)
+      `plan: ${JSON.stringify(plan.title || "")}`,
+      // 涉及项目(跟随导出范围: front只前端/back只后端/all全部), AI据此定位要改的代码仓
+      `projects: ${JSON.stringify(storyProjectsOf(story, scope).join(", "))}`,
+      // JSON.stringify统一转义: 防frontmatter(YAML)断裂(source含冒号, 与其他字段风格一致)
+      `source: ${JSON.stringify(storyUrl(story.id))}`,
+      "---",
+      "",
+      `# 需求：${story.title}`,
+      "",
+      "## 正文",
+      "",
+      spec || "（禅道未填写描述）",
+      // 验收内容并入正文, 不设独立区块; 为空时不输出
+      verify ? `\n验收标准：\n${verify}` : "",
+      "",
+    ].join("\n");
+    fs.mkdirSync(path.join(tasksDir, taskDir), { recursive: true });
+    fs.writeFileSync(taskPath, content, "utf8");
+    added += 1;
+  });
+
+  const merged = Array.from(manifestMap.values()).sort(
+    (a, b) => Number(a.storyID) - Number(b.storyID)
+  );
+  // 顶部汇总全部需求涉及的项目(各条目projects并集去重排序; 旧格式迁移条目可能无该字段, 忽略)
+  const allProjects = [
+    ...new Set(merged.flatMap((item) => item.projects || [])),
+  ].sort();
+  fs.writeFileSync(
+    manifestPath,
+    JSON.stringify({ projects: allProjects, stories: merged }, null, 2),
+    "utf8"
+  );
+  console.log(
+    chalk.green(
+      `产出完成: 写入 ${added} 条 / 失败 ${failed.size} 条`
+    )
+  );
+  console.log(chalk.green(`输出目录: ${zentaoDir}`));
+  // 部分失败以非零退出码收尾, 供自动化流程感知重试
+  if (failed.size > 0) {
+    console.log(
+      chalk.red(`失败${failed.size}条(详情见上方黄字提示), 已跳过不产出, 可重跑 story plan --export 补齐`)
+    );
+    process.exit(1);
+  }
+}
+
+// 计划选取交互: 关键词过滤 > 命中1条自动选中 > rawlist选取
+async function selectPlan(plans, keyword) {
+  if (keyword && String(keyword).trim()) {
+    const kw = String(keyword).trim().toLowerCase();
+    const filtered = plans.filter((p) =>
+      String(p.title).toLowerCase().includes(kw)
+    );
+    if (!filtered.length) {
+      console.log(chalk.red("未找到匹配的计划"));
+      process.exit(1);
+    }
+    plans = filtered;
+  }
+  if (plans.length === 1) {
+    return plans[0];
+  }
+  const { plan } = await inquirer.prompt([
+    {
+      message: "请选择计划",
+      name: "plan",
+      type: "rawlist",
+      choices: plans.map((p) => ({
+        name: `#${p.id} ${p.title} [${p.begin} ~ ${p.end}] (${
+          p.stories ?? 0
+        }条需求)`,
+        value: p,
+      })),
+    },
+  ]);
+  return plan;
+}
+
+// 拉取计划列表(会话由调用方保证有效), 按begin倒序展示(最新计划在前, id降序兜底)
+async function loadPlanList(zentaosid, productID) {
+  Loading$1.start("拉取计划列表中...");
+  const plans = await fetchPlanList(zentaosid, productID);
+  Loading$1.succeed(`拉取计划列表成功(${plans.length}条)`);
+  plans.sort(
+    (a, b) =>
+      String(b.begin || "").localeCompare(String(a.begin || "")) ||
+      Number(b.id) - Number(a.id)
+  );
+  return plans;
+}
+
+// plan动作: 选中计划后展示计划信息 + 关联需求列表(ID供detail用)
+async function showPlanDetail(zentaosid, selected) {
+  Loading$1.start("拉取计划详情中...");
+  const { plan, stories } = await fetchPlanDetail(zentaosid, selected.id);
+  Loading$1.succeed("拉取计划详情成功");
+  console.log(chalk.bold("\n计划信息"));
+  console.table([
+    {
+      ID: plan.id,
+      名称: plan.title,
+      起止时间: `${plan.begin} ~ ${plan.end}`,
+      描述: htmlToText(plan.desc) || "-",
+    },
+  ]);
+  // 工时统计(基于全量需求, 非仅截断展示的)
+  const totalWeb = stories.reduce(
+    (sum, s) => sum + (Number(s.webestimate) > 0 ? Number(s.webestimate) : 0),
+    0
+  );
+  const totalEst = stories.reduce(
+    (sum, s) => sum + (Number(s.estimate) > 0 ? Number(s.estimate) : 0),
+    0
+  );
+  const frontCount = stories.filter((s) => Number(s.webestimate) > 0).length;
+  const backCount = stories.filter((s) => Number(s.estimate) > 0).length;
+  console.log(
+    chalk.bold(
+      `\n关联需求列表(共${stories.length}条, 前端${frontCount}条${totalWeb}h, 后端${backCount}条${totalEst}h)`
+    )
+  );
+  const displayStories = stories.slice(0, PLAN_STORY_TABLE_LIMIT);
+  if (stories.length > PLAN_STORY_TABLE_LIMIT) {
+    console.log(
+      chalk.yellow(
+        `需求较多(${stories.length}条), 仅展示前${PLAN_STORY_TABLE_LIMIT}条, 完整列表可用 story plan --export 产出`
+      )
+    );
+  }
+  console.table(
+    displayStories.map((s) => {
+      const isFront = Number(s.webestimate) > 0;
+      const hasFrontPool = parsePoolList(s.poollist).some((p) =>
+        frontProjectOf(p)
+      );
+      return {
+        ID: s.id,
+        标题: s.title,
+        前端工时: isFront ? s.webestimate : "-",
+        后端工时: Number(s.estimate) > 0 ? s.estimate : "-",
+        poollist: s.poollist || "-",
+        // 有前端工时但poollist无fe-开头的前端pool => 标记❌(console.table单元格不支持着色)
+        前端pool: isFront ? (hasFrontPool ? "✓" : "❌") : "-",
+      };
+    })
+  );
+  console.log(
+    chalk.blue("提示: ID 供 fe-it-beta story detail <需求ID> 使用(也可传需求url)")
+  );
+}
+
+// 导出动作(plan收尾交互使用): 按范围过滤需求, 拉详情并产出 .zentao-<计划名>/ + 工作区
+// scope: front=有前端工时的需求 | back=有后端工时的需求 | all=全部
+async function exportPlanStories(zentaosid, selected, scope) {
+  const scopeLabel =
+    scope === "front" ? "前端" : scope === "back" ? "后端" : "全部";
+  Loading$1.start("拉取计划详情中...");
+  const { plan, stories: allStories, products } = await fetchPlanDetail(
+    zentaosid,
+    selected.id
+  );
+  // 按导出范围过滤需求
+  const stories = allStories.filter((s) => {
+    if (scope === "front") return Number(s.webestimate) > 0;
+    if (scope === "back") return Number(s.estimate) > 0;
+    return true;
+  });
+  Loading$1.succeed(
+    `拉取计划详情成功(${scopeLabel}${stories.length}/${allStories.length}条)`
+  );
+  if (!stories.length) {
+    console.log(chalk.red(`该计划无${scopeLabel}需求`));
     process.exit(1);
   }
-  // CLI传入的权限名称/编码仅第一圈消费, 后续圈次走交互输入
-  let cliName = cliPermissionName;
-  let cliCode = cliPermissionCode;
-  let goOn = true;
-  while (goOn) {
-    const permissionName = await askOrUse(cliName, {
-      message: "请输入权限名称",
-      name: "permissionName",
-      type: "input",
-      validate: function (value) {
-        if (value) {
-          return true;
-        }
-        return "请输入权限名称";
-      },
+  // 并行限流(并发5)逐条拉取 spec/verify
+  const storyDetails = new Map();
+  const failed = new Map(); // storyID -> 错误信息
+  let done = 0;
+  let index = 0;
+  Loading$1.start(`拉取需求详情 (0/${stories.length})...`);
+  const worker = async () => {
+    while (index < stories.length) {
+      const story = stories[index];
+      index += 1;
+      try {
+        const detail = await fetchStoryDetail(zentaosid, story.id);
+        storyDetails.set(String(story.id), detail);
+      } catch (e) {
+        // 会话失效上抛, 由 ensureZentaoSession 整体重登重试
+        if (e?.isAuthError) throw e;
+        failed.set(String(story.id), e.message || String(e));
+        console.log(chalk.yellow(`需求 ${story.id} 详情拉取失败: ${e.message}`));
+      }
+      done += 1;
+      // ora 的 text 是属性而非方法
+      Loading$1.text = `拉取需求详情 (${done}/${stories.length})...`;
+    }
+  };
+  await Promise.all(
+    Array.from({ length: PULL_CONCURRENCY }, () => worker())
+  );
+  Loading$1.succeed(`拉取需求详情完成(${done}/${stories.length})`);
+  // 需求目录: .zentao-<计划名>(多计划互不混目录)
+  const zentaoDir = path.join(process.cwd(), zentaoDirNameOf(plan));
+  // 同名taskDir直接删除重导(重拉=全新快照, 连带清掉旧images与旧plan/codex报告; 失败条目保留旧数据)
+  stories.forEach((story) => {
+    if (failed.has(String(story.id))) return;
+    const dir = path.join(zentaoDir, "tasks", taskDirOf(story));
+    if (isExistPath(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      console.log(chalk.yellow(`同名任务目录已删除重导: ${taskDirOf(story)}`));
+    }
+  });
+  // 图片本地化到 tasks/<taskDir>/images/(目录已删全量重下, 失败黄字不阻塞, 引用降级远程url)
+  const storyImages = await downloadStoryImages({
+    stories,
+    storyDetails,
+    zentaosid,
+    zentaoDir,
+  });
+  writeZentaoTasks({
+    plan,
+    scope,
+    stories,
+    storyDetails,
+    products,
+    failed,
+    storyImages,
+    zentaoDir,
+  });
+  // 汇总范围内需求的项目(前端fe-xxx-vue截取 / 后端pool原名), 生成多项目工作区
+  const frontProjects =
+    scope === "front" || scope === "all"
+      ? collectPoolProjects(stories, "front")
+      : [];
+  const backProjects =
+    scope === "back" || scope === "all"
+      ? collectPoolProjects(stories, "back")
+      : [];
+  if (frontProjects.length || backProjects.length) {
+    writeCodeWorkspace(zentaoDir, plan.title, frontProjects, backProjects);
+  } else {
+    console.log(chalk.yellow("本范围无关联项目, 跳过工作区生成"));
+  }
+}
+
+/**
+ * story 主入口
+ * @param action login | plan | detail | task | subtask
+ * @param cliOpts 合并后的命令参数(name/username/password/cache/export...)
+ */
+async function storyMain(action, cliOpts) {
+  validateChoice(
+    action,
+    ["login", "plan", "detail", "task", "subtask"],
+    "story <action>"
+  );
+  if (action === "login") {
+    const secret = await askZentaoCredentials(cliOpts);
+    await zentaoLogin(secret);
+    console.log(chalk.green("登录成功, zentaosid 已缓存"));
+    return;
+  }
+  if (action === "detail") {
+    // 入参 = 需求url(完整url/相对路径/纯ID)
+    const input = String(cliOpts.name || "").trim();
+    const match =
+      input.match(/story-view-(\d+)/) ||
+      (/^\d+$/.test(input) ? [input, input] : null);
+    if (!match) {
+      console.log(
+        chalk.red(
+          "请传入需求url(从 story plan 输出的需求列表复制), 如: fe-it-beta story detail https://zentao.hongxinshop.com/zentao/story-view-70026.html"
+        )
+      );
+      process.exit(1);
+    }
+    const storyID = match[1];
+    const session = await ensureZentaoSession(cliOpts);
+    await session.request(async (zentaosid) => {
+      Loading$1.start("拉取需求详情中...");
+      const { story, users } = await fetchStoryDetail(zentaosid, storyID);
+      Loading$1.succeed("拉取需求详情成功");
+      console.log(chalk.bold(`\n需求详情 #${story.id}`));
+      const rows = [
+        ["ID", story.id],
+        ["标题", story.title],
+        ["产品ID", story.product],
+        ["模块ID", story.module],
+        ["状态", story.status],
+        ["阶段", story.stage],
+        ["优先级", story.pri],
+        ["指派给", users[story.assignedTo] || story.assignedTo],
+        ["创建人", users[story.openedBy] || story.openedBy],
+        ["预估工时", story.estimate],
+        ["url", storyUrl(story.id)],
+      ];
+      rows.forEach(([label, value]) =>
+        console.log(chalk.gray(String(label).padEnd(6, "　")) + ": " + value)
+      );
+      console.log(chalk.bold("\n需求描述"));
+      // 图片以markdown引用完整url输出(可复制到浏览器查看)
+      console.log(htmlToText(story.spec, absoluteZentaoUrl) || "-");
+      console.log(chalk.bold("\n验收标准"));
+      console.log(htmlToText(story.verify, absoluteZentaoUrl) || "-");
     });
-    const permissionCode = await askOrUse(cliCode, {
-      message: "请输入权限编码",
-      name: "permissionCode",
-      type: "input",
-      validate: function (value) {
-        if (!value) {
-          return "请输入权限编码";
+    return;
+  }
+  if (action === "task") {
+    // 入参 = 项目ID(完整url/相对路径/纯ID), 如 project-story-2915.html 里的 2915
+    const input = String(cliOpts.name || "").trim();
+    const match =
+      input.match(/project-story-(\d+)/) ||
+      (/^\d+$/.test(input) ? [input, input] : null);
+    if (!match) {
+      console.log(
+        chalk.red(
+          "请传入项目ID(从禅道项目需求页url复制), 如: fe-it-beta story task 2915 或 fe-it-beta story task https://zentao.hongxinshop.com/zentao/project-story-2915.html"
+        )
+      );
+      process.exit(1);
+    }
+    const projectID = match[1];
+    // --type 校验前置, 非法值在网络请求前就红字退出
+    if (cliOpts.type !== undefined) {
+      validateChoice(cliOpts.type, ["front", "back"], "--type");
+    }
+    const session = await ensureZentaoSession(cliOpts);
+    await session.request(async (zentaosid) => {
+      // 项目存在性预校验(不存在的项目ID禅道会返回登录页HTML, 会被误判为会话失效)
+      Loading$1.start("校验项目中...");
+      const projectMap = await fetchProjectMap(zentaosid);
+      if (!projectMap[projectID]) {
+        Loading$1.fail("项目不存在");
+        throw new Error(`项目ID ${projectID} 不存在, 请检查后重试`);
+      }
+      Loading$1.succeed(`项目: #${projectID} ${projectMap[projectID]}`);
+      Loading$1.start("拉取项目需求中...");
+      const pj = await fetchProjectStories(zentaosid, projectID);
+      if (!pj.project || !pj.project.name) {
+        Loading$1.fail("项目不存在");
+        throw new Error(`项目ID ${projectID} 不存在, 请检查后重试`);
+      }
+      Loading$1.succeed(
+        `项目: #${projectID} ${pj.project.name} [${pj.project.begin} ~ ${pj.project.end}] (需求${pj.stories.length}条)`
+      );
+      if (!pj.stories.length) {
+        console.log(chalk.red("该项目无关联需求"));
+        process.exit(1);
+      }
+      // 每条需求的前后端已建任务计数(勾选时提示防重复建)
+      // 自行从项目任务列表统计(禅道 storyWebTasks/storyDevTasks 会把回收站任务也计入, 实测不准)
+      Loading$1.start("拉取项目任务中...");
+      const { tasks: projectTasks, pageTotal } = await fetchProjectTasks(
+        zentaosid,
+        projectID
+      );
+      Loading$1.succeed(
+        `拉取项目任务成功(${projectTasks.length}条, 需求计数用)`
+      );
+      // 任务超单页时计数可能不全(禅道翻页路由不稳定, 只提示不翻页)
+      if (pageTotal > 1) {
+        console.log(
+          chalk.yellow(
+            `项目任务超过单页(${pageTotal}页), 已建计数可能不全`
+          )
+        );
+      }
+      // 前端任务判定: type=frontend 或 名称【前端】前缀(修复前的旧数据 type 误传 devel)
+      const isFrontTask = (t) =>
+        t.type === "frontend" || String(t.name || "").startsWith("【前端】");
+      const tasksOf = (s) =>
+        projectTasks.filter((t) => String(t.story) === String(s.id));
+      const webCount = (s) => tasksOf(s).filter(isFrontTask).length;
+      const devCount = (s) =>
+        tasksOf(s).filter((t) => t.type === "devel" && !isFrontTask(t)).length;
+      const totalCount = (s) => tasksOf(s).length;
+      // 子任务统计: 子任务不出现在任务列表(挂在父任务children下), 逐个拉详情;
+      // 只拉 工时>8 的主任务(只有这些才可能拆过子任务), 并发限流控制请求量
+      const subCountMap = new Map(); // 任务ID -> 子任务数
+      {
+        const candidates = projectTasks.filter(
+          (t) => Number(t.estimate) > 8 && !Number(t.parent)
+        );
+        let index = 0;
+        const worker = async () => {
+          while (index < candidates.length) {
+            const t = candidates[index];
+            index += 1;
+            try {
+              const detail = await fetchTaskDetail(zentaosid, t.id);
+              const n = Object.keys(detail?.children || {}).length;
+              if (n) subCountMap.set(String(t.id), n);
+            } catch (e) {
+              if (e?.isAuthError) throw e;
+              // 子任务统计失败不阻塞主流程(勾选列表仍可用, 只是少了子任务数)
+            }
+          }
+        };
+        await Promise.all(
+          Array.from({ length: PULL_CONCURRENCY }, () => worker())
+        );
+      }
+      // 先勾选需求: 一键(--type直通)自动取候选; 交互则列出项目全部需求
+      let picked;
+      if (cliOpts.type !== undefined) {
+        const presetLabel = cliOpts.type === "front" ? "前端" : "后端";
+        const hourOfPreset = (s) =>
+          Number(cliOpts.type === "front" ? s.webestimate : s.estimate);
+        if (cliOpts.splitOnly) {
+          // 仅拆分模式: 取>8h的需求(有父任务按剩余工时拆, 无父任务自动先建)
+          picked = pj.stories.filter((s) => hourOfPreset(s) > 8);
+          if (!picked.length) {
+            console.log(
+              chalk.yellow(`无超过8h的${presetLabel}需求, 无可拆分项, 结束`)
+            );
+            return;
+          }
+        } else {
+          // 建任务模式: 有该类型工时且未建过的需求
+          picked = pj.stories.filter(
+            (s) =>
+              hourOfPreset(s) > 0 &&
+              (cliOpts.type === "front" ? webCount(s) : devCount(s)) === 0
+          );
+          if (!picked.length) {
+            console.log(
+              chalk.yellow(`候选需求均已建过${presetLabel}任务, 无可创建项, 结束`)
+            );
+            return;
+          }
         }
-        if (value.includes(":")) {
-          return "权限编码不允许包含 :";
+      } else {
+        // 前端子任务计数(排序与展示共用)
+        const frontSubsOf = (s) =>
+          tasksOf(s)
+            .filter(isFrontTask)
+            .reduce(
+              (sum, t) => sum + (subCountMap.get(String(t.id)) || 0),
+              0
+            );
+        // 前端拆分基准工时: 有父任务用父任务实际工时(最大前端任务的工时), 无则用需求webestimate
+        // (手建父任务工时可能与需求webestimate不一致, 应建数按实际父任务算才准)
+        const frontBaseHours = (s) => {
+          const frontTasks = tasksOf(s).filter(isFrontTask);
+          return frontTasks.length
+            ? Math.max(...frontTasks.map((t) => Number(t.estimate) || 0))
+            : Number(s.webestimate);
+        };
+        ({ picked } = await inquirer.prompt([
+          {
+            message: "请勾选要建任务的需求(空格选择, 回车确认)",
+            name: "picked",
+            type: "checkbox",
+            // 到列表边界停止, 不循环回第一条
+            loop: false,
+            choices: [...pj.stories]
+              .sort((a, b) => {
+                // 待办优先级: 0=前端有工时且未建任务(子任务也必无, 全新建)
+                // 1=前端有任务但子任务未满(待补拆, 基准=父任务实际工时) 2=其余有前端工时 3=无前端工时
+                // 组内按需求ID从小到大
+                const rank = (s) => {
+                  if (!(Number(s.webestimate) > 0)) return 3;
+                  const base = frontBaseHours(s);
+                  if (webCount(s) === 0) return 0;
+                  return base > 8 && frontSubsOf(s) < Math.ceil(base / 8)
+                    ? 1
+                    : 2;
+                };
+                return (
+                  rank(a) - rank(b) ||
+                  Number(a.id) - Number(b.id)
+                );
+              })
+              .map((s, i) => {
+                // 子任务进度(仅前端>8h展示, 后端暂不展示): 已建/应建
+                // 应建 = ceil(基准工时/8), 基准=前端父任务实际工时(无父任务用webestimate)
+                // 未满已建数红色, 满则总数绿色; 任务计数后括号内联
+                const subProgress = (hours, count) => {
+                  const total = Math.ceil(Number(hours) / 8);
+                  return count >= total
+                    ? `(${count}/${chalk.green(total)})`
+                    : `(${chalk.red(count)}/${total})`;
+                };
+                const frontSubs = frontSubsOf(s);
+                const base = frontBaseHours(s);
+                // 前端: 任务数(子任务进度); 后端: 任务数(暂不展示子任务)
+                const built = [
+                  Number(s.webestimate) > 0
+                    ? `前端${webCount(s)}个${
+                        base > 8 ? subProgress(base, frontSubs) : ""
+                      }`
+                    : "",
+                  Number(s.estimate) > 0 ? `后端${devCount(s)}个 任务` : "",
+                ]
+                  .filter(Boolean)
+                  .join("/");
+                // 父任务工时不足提示: 有前端父任务但工时 < 需求前端工时(黄字, 手建父任务漏填/填少)
+                const shortWarn =
+                  webCount(s) > 0 && base < Number(s.webestimate)
+                    ? `, ${chalk.yellow(`父任务${base}h<需求${s.webestimate}h, 不足!`)}`
+                    : "";
+                // 第二行详情(已建/警告): 换行 + 缩进对齐, 与标题行区分
+                const detail = [built ? `已建${built}` : "", shortWarn.slice(2)]
+                  .filter(Boolean)
+                  .join(", ");
+                return {
+                  name: `${i + 1}. #${s.id} ${s.title} (前端${
+                    Number(s.webestimate) > 0 ? `${s.webestimate}h` : "-"
+                  } / 后端${
+                    Number(s.estimate) > 0 ? `${s.estimate}h` : "-"
+                  })${detail ? `\n    ${detail}` : ""}`,
+                  value: s,
+                  // 有工时但从未建过任何任务的需求默认勾选
+                  checked: totalCount(s) === 0,
+                };
+              }),
+          },
+        ]));
+      }
+      if (!picked.length) {
+        console.log(chalk.yellow("未勾选需求, 结束"));
+        return;
+      }
+      // 再选任务类型: --type 直通(一键场景) > 选完需求后交互询问
+      let taskType;
+      if (cliOpts.type !== undefined) {
+        taskType = cliOpts.type;
+      } else {
+        ({ taskType } = await inquirer.prompt([
+          {
+            message: "请选择任务类型",
+            name: "taskType",
+            type: "list",
+            choices: [
+              { name: "前端任务", value: "front" },
+              { name: "后端任务", value: "back" },
+            ],
+          },
+        ]));
+      }
+      const typeLabel = taskType === "front" ? "前端" : "后端";
+      // 勾选项中无该类型工时的跳过(黄字提示)
+      const hourOf = (s) =>
+        Number(taskType === "front" ? s.webestimate : s.estimate);
+      const noHour = picked.filter((s) => hourOf(s) <= 0);
+      if (noHour.length) {
+        console.log(
+          chalk.yellow(
+            `需求 ${noHour.map((s) => s.id).join(", ")} 无${typeLabel}工时, 跳过不建`
+          )
+        );
+      }
+      picked = picked.filter((s) => hourOf(s) > 0);
+      if (!picked.length) {
+        console.log(chalk.red(`勾选的需求均无${typeLabel}工时`));
+        process.exit(1);
+      }
+      // 指派: 前端->webuser / 后端->devuser, 为空 fallback 当前登录账号
+      const account = readZentaoCache().account;
+      const assigneeOf = (s) =>
+        (taskType === "front" ? s.webuser : s.devuser) || account;
+      // 处理模式(选择即确认): --split-only > --split > 交互列表 > 一键默认
+      // parent=仅创建父任务 | parent-split=创建父任务+拆分子任务 | split=仅拆分(无父任务自动先建)
+      let taskMode;
+      if (cliOpts.splitOnly) {
+        taskMode = "split";
+      } else if (cliOpts.split) {
+        taskMode = "parent-split";
+      } else if (cliOpts.type !== undefined) {
+        taskMode = "parent"; // 一键默认仅建父任务
+      } else {
+        ({ taskMode } = await inquirer.prompt([
+          {
+            message: `将处理 ${picked.length} 条【${typeLabel}】任务(截止 ${pj.project.end}), 请选择模式`,
+            name: "taskMode",
+            type: "list",
+            choices: [
+              { name: "1. 创建父任务", value: "parent" },
+              { name: "2. 创建父任务+拆分子任务", value: "parent-split" },
+              { name: "3. 拆分子任务(无父任务自动先创建)", value: "split" },
+            ],
+          },
+        ]));
+      }
+      // 现有父任务(pick中已建该类任务的): 拆分类模式复用, 不重复建
+      const existingParentOf = (s) =>
+        tasksOf(s).find((t) =>
+          taskType === "front"
+            ? isFrontTask(t)
+            : t.type === "devel" && !isFrontTask(t)
+        );
+      // 需创建父任务的需求:
+      // parent=全部勾选 | parent-split=无父任务的 | split=无父任务且>8h(仅为拆分而建)
+      const toCreate =
+        taskMode === "parent"
+          ? picked
+          : picked.filter(
+              (s) =>
+                !existingParentOf(s) &&
+                (taskMode === "parent-split" || hourOf(s) > 8)
+            );
+      // 创建前任务基线(创建后 diff 出新任务ID)
+      const baseline = new Set(
+        (await fetchProjectTasks(zentaosid, projectID)).tasks.map((t) =>
+          String(t.id)
+        )
+      );
+      // 逐条创建(串行, 避免并发触发禅道限流)
+      let done = 0;
+      const failedStories = [];
+      if (toCreate.length) {
+        Loading$1.start(`创建任务 (0/${toCreate.length})...`);
+        for (const s of toCreate) {
+          try {
+            await createZentaoTask({
+              zentaosid,
+              projectID,
+              story: s,
+              name: `【${typeLabel}】${s.title}`,
+              // 任务类型(表单选项实测): frontend=前端开发, devel=后端开发
+              type: taskType === "front" ? "frontend" : "devel",
+              assignedTo: assigneeOf(s),
+              estimate: taskType === "front" ? s.webestimate : s.estimate,
+              estStarted: localToday(),
+              deadline: pj.project.end,
+            });
+          } catch (e) {
+            // 会话失效上抛, 由 ensureZentaoSession 整体重登重试
+            if (e?.isAuthError) throw e;
+            failedStories.push(s.id);
+            console.log(
+              chalk.yellow(`需求 ${s.id} 创建失败: ${e.message || String(e)}`)
+            );
+          }
+          done += 1;
+          // ora 的 text 是属性而非方法
+          Loading$1.text = `创建任务 (${done}/${toCreate.length})...`;
         }
-        return true;
-      },
-    });
-    cliName = undefined;
-    cliCode = undefined;
-    const data = {
-      code1: appConfig.code,
-      name: permissionName,
-      visitConf: permissionCode,
-      ascriptionApp: appConfig.id,
-      code: `${appConfig.code}:${permissionCode}`,
-    };
-    let confirmed = true;
-    if (!oneClick) {
-      const { confirmAdd } = await inquirer.prompt([
-        {
-          message: `确认新增按钮权限? ${chalk.cyan(
-            `${data.name} (${data.code})`
-          )}`,
-          name: "confirmAdd",
-          type: "confirm",
-          default: true,
-        },
-      ]);
-      confirmed = confirmAdd;
-    }
-    if (confirmed) {
-      try {
-        await addApplicationButtonConfig({ data, env, token });
+        Loading$1.succeed(
+          `创建完成: 成功 ${toCreate.length - failedStories.length} 条 / 失败 ${failedStories.length} 条`
+        );
+      }
+      // 重拉任务列表 diff 出新任务, 输出任务url
+      const pickedIDs = new Set(picked.map((s) => String(s.id)));
+      const newTasks = (await fetchProjectTasks(zentaosid, projectID)).tasks.filter(
+        (t) => !baseline.has(String(t.id)) && pickedIDs.has(String(t.story))
+      );
+      newTasks.forEach((t) =>
         console.log(
           chalk.green(
-            `新增按钮权限成功: ${appName} - ${data.name} (${data.code})`
+            `任务 #${t.id} ${t.name} -> ${t.assignedTo} (${t.estimate}h)`
+          ),
+          `\n  ${taskUrl(t.id)}`
+        )
+      );
+      // 拆分子任务(parent-split/split 模式, 仅>8h): 父任务 = 新建优先, 否则用已有(按剩余工时)
+      if (taskMode !== "parent") {
+        const newByStory = new Map(
+          newTasks.map((t) => [String(t.story), t])
+        );
+        for (const s of picked) {
+          if (!(hourOf(s) > 8)) continue; // <=8h 无可拆, 跳过
+          const created = newByStory.get(String(s.id));
+          const parent = created || existingParentOf(s);
+          if (!parent) continue; // 创建失败等场景
+          // 截止日期须晚于今天(禅道校验 截止>开始, 旧任务截止已过期的跳过)
+          const deadline = parent.deadline || pj.project.end;
+          if (String(deadline) <= localToday()) {
+            console.log(
+              chalk.yellow(
+                `任务 #${parent.id} ${parent.name} 截止日期 ${deadline} 不晚于今天, 跳过拆分(需先调整父任务截止日期)`
+              )
+            );
+            continue;
+          }
+          // 剩余工时: 新建父任务=全部工时; 已有父任务=工时-已有子任务和(拉详情算)
+          let remaining = hourOf(s);
+          if (!created) {
+            const detail = await fetchTaskDetail(zentaosid, parent.id);
+            const childHours = Object.values(detail?.children || {}).reduce(
+              (sum, c) => sum + Number(c.estimate || 0),
+              0
+            );
+            remaining = Number(parent.estimate) - childHours;
+          }
+          if (!(remaining > 8)) {
+            console.log(
+              chalk.yellow(
+                `任务 #${parent.id} ${parent.name} 剩余工时 ${remaining}h 未超过 8h, 跳过拆分`
+              )
+            );
+            continue;
+          }
+          const subs = splitTaskPlan(parent.name, remaining, taskType);
+          try {
+            await createZentaoSubtasks({
+              zentaosid,
+              projectID,
+              story: s,
+              parentTaskID: parent.id,
+              type: taskType === "front" ? "frontend" : "devel",
+              assignedTo: parent.assignedTo,
+              estStarted: localToday(),
+              // 截止日期跟随父任务(新建父任务即为项目结束日期)
+              deadline: parent.deadline || pj.project.end,
+              subs,
+            });
+            console.log(
+              chalk.green(
+                `子任务 ${subs.length} 个已创建(父任务 #${parent.id}): ${subs
+                  .map((sub) => `${sub.name}(${sub.estimate}h)`)
+                  .join(", ")}`
+              )
+            );
+          } catch (e) {
+            // 会话失效上抛, 由 ensureZentaoSession 整体重登重试
+            if (e?.isAuthError) throw e;
+            console.log(
+              chalk.yellow(
+                `任务 ${parent.id} 子任务创建失败: ${e.message || String(e)}`
+              )
+            );
+          }
+        }
+      }
+      // 部分失败以非零退出码收尾, 供自动化流程感知重试
+      if (failedStories.length) {
+        console.log(
+          chalk.red(
+            `失败${failedStories.length}条(需求ID: ${failedStories.join(", ")}), 详情见上方黄字提示`
           )
         );
-      } catch (e) {
-        console.log(chalk.red(`新增按钮权限失败: ${e.message || e}`));
         process.exit(1);
       }
+    });
+    return;
+  }
+  if (action === "subtask") {
+    // 入参 = 父任务ID(完整url/相对路径/纯ID), 如 task-view-218901.html 里的 218901
+    const input = String(cliOpts.name || "").trim();
+    const match =
+      input.match(/task-view-(\d+)/) ||
+      (/^\d+$/.test(input) ? [input, input] : null);
+    if (!match) {
+      console.log(
+        chalk.red(
+          "请传入父任务ID(从禅道任务页url复制), 如: fe-it-beta story subtask 218901 或 fe-it-beta story subtask https://zentao.hongxinshop.com/zentao/task-view-218901.html"
+        )
+      );
+      process.exit(1);
     }
-    if (oneClick) {
-      goOn = false;
+    const parentID = match[1];
+    const session = await ensureZentaoSession(cliOpts);
+    await session.request(async (zentaosid) => {
+      Loading$1.start("拉取父任务详情中...");
+      const parent = await fetchTaskDetail(zentaosid, parentID);
+      if (!parent || !parent.id) {
+        Loading$1.fail("任务不存在");
+        throw new Error(`任务ID ${parentID} 不存在, 请检查后重试`);
+      }
+      const typeLabel = parent.type === "frontend" ? "前端" : "后端";
+      const taskType = parent.type === "frontend" ? "front" : "back";
+      const totalHours = Number(parent.estimate);
+      // 已有子任务(工时和), 按剩余工时拆
+      const children = Object.values(parent.children || {});
+      const childHours = children.reduce(
+        (sum, c) => sum + Number(c.estimate || 0),
+        0
+      );
+      const remainHours = totalHours - childHours;
+      Loading$1.succeed(
+        `父任务 #${parent.id} ${parent.name} [${typeLabel}] ${totalHours}h -> ${parent.assignedTo} (截止 ${parent.deadline})`
+      );
+      if (children.length) {
+        console.log(
+          chalk.yellow(
+            `已有子任务 ${children.length} 个(共${childHours}h): ${children
+              .map((c) => `#${c.id} ${c.name}(${c.estimate}h)`)
+              .join(", ")}`
+          )
+        );
+      }
+      if (!(remainHours > 8)) {
+        console.log(
+          chalk.yellow(
+            `剩余工时 ${remainHours}h 未超过 8h, 无需拆分${
+              remainHours < 0 ? "(子任务工时已超父任务)" : ""
+            }`
+          )
+        );
+        return;
+      }
+      // 拆分方案(按剩余工时, 名称对齐父任务名)
+      const subs = splitTaskPlan(parent.name, remainHours, taskType);
+      console.log(chalk.bold(`\n拆分方案(${subs.length} 个子任务, 共${remainHours}h):`));
+      subs.forEach((sub) =>
+        console.log(`  ${sub.name} (${sub.estimate}h) -> ${parent.assignedTo}`)
+      );
+      // --split 直通跳过确认(一键场景), 否则询问
+      if (!cliOpts.split) {
+        const { ok } = await inquirer.prompt([
+          {
+            message: "确认创建以上子任务?",
+            name: "ok",
+            type: "confirm",
+            default: true,
+          },
+        ]);
+        if (!ok) {
+          console.log(chalk.yellow("已取消"));
+          return;
+        }
+      }
+      await createZentaoSubtasks({
+        zentaosid,
+        projectID: parent.project,
+        story: { id: parent.story, pri: parent.pri },
+        parentTaskID: parent.id,
+        type: parent.type,
+        assignedTo: parent.assignedTo,
+        estStarted: localToday(),
+        deadline: parent.deadline,
+        subs,
+      });
+      console.log(
+        chalk.green(
+          `子任务 ${subs.length} 个已创建(父任务 #${parent.id}): ${subs
+            .map((sub) => `${sub.name}(${sub.estimate}h)`)
+            .join(", ")}`
+        )
+      );
+      console.log(chalk.green(`查看: ${taskUrl(parent.id)}`));
+    });
+    return;
+  }
+  // plan: 产品选择 -> 计划选取 -> 展示 -> 导出(--export直通一键场景, 不传则收尾交互)
+  const session = await ensureZentaoSession(cliOpts);
+  await session.request(async (zentaosid) => {
+    const product = await selectProduct(zentaosid, cliOpts);
+    const plans = await loadPlanList(zentaosid, product.id);
+    const selected = await selectPlan(plans, cliOpts.name);
+    await showPlanDetail(zentaosid, selected);
+    // 导出范围: --export参数直通(一键场景) > 收尾交互(默认前端)
+    let exportChoice;
+    if (cliOpts.export !== undefined) {
+      validateChoice(cliOpts.export, ["front", "back", "all"], "--export");
+      exportChoice = cliOpts.export;
     } else {
-      const { continueAdd } = await inquirer.prompt([
+      ({ exportChoice } = await inquirer.prompt([
         {
-          message: "是否继续为该应用添加按钮权限?",
-          name: "continueAdd",
-          type: "confirm",
-          default: false,
+          message: "是否导出需求文件(按计划生成 .zentao-<计划名>目录)?",
+          name: "exportChoice",
+          type: "list",
+          choices: [
+            { name: "导出: 前端需求", value: "front" }, // 默认第一项
+            { name: "导出: 后端需求", value: "back" },
+            { name: "导出: 全部需求", value: "all" },
+            { name: "否", value: "none" },
+          ],
         },
-      ]);
-      goOn = continueAdd;
+      ]));
     }
-  }
+    if (exportChoice !== "none") {
+      await exportPlanStories(zentaosid, selected, exportChoice);
+    }
+  });
+}
+
+/**
+ * 命令注册(index.js 只登记调用, 命令定义全部收在本模块内)
+ * @param program commander program 实例
+ * @param helpers { markHandled, addHelpExample }
+ */
+function registerStoryCommand(program, { markHandled, addHelpExample }) {
+  program
+    .command("story <action> [name]")
+    .description(
+      "禅道需求: login 登录 | plan 选计划看需求列表并可导出(按计划生成需求目录+工作区) | detail 看需求详情 | task 勾选项目需求在线建任务 | subtask 给已建任务单独拆子任务"
+    )
+    // 子命令的 option 独立于 program 级: story login --cache 中 --cache 出现在子命令位, 须在子命令上重复注册
+    .option("--username <name>", "禅道账号(story命令用)")
+    .option("--password <pwd>", "禅道密码(story命令用, 日常建议用--cache)")
+    .option("--cache", "凭据静默走缓存")
+    .option("--product <id>", "禅道产品ID(plan用, 不传则交互选择)")
+    .option("--export <scope>", "plan导出范围: front|back|all(传了跳过收尾询问直接导出)")
+    .option("--type <t>", "task任务类型: front|back(传了跳过类型询问与确认, 一键创建)")
+    .option("--split", "task时创建父任务并自动拆分子任务(>8h, 每个8h末个补余); subtask时跳过确认直接拆")
+    .option("--split-only", "task时仅拆分子任务(无父任务的>8h需求自动先建父任务再拆)")
+    .action((action, name, options) => {
+      markHandled(); // 同步置位, 防止 index.js 落入默认翻译分支
+      storyMain(action, { ...program.opts(), ...options, name }).catch(
+        (error) => {
+          // 兜底停掉可能挂着的spinner + 红字报错 + 非零退出码(供自动化判断成败)
+          Loading$1.fail("执行失败");
+          console.error(chalk.red(error.message || String(error)));
+          process.exit(1);
+        }
+      );
+    });
+  // help示例经 helpers 注入 index.js 的 helpExamples, 自动参与列对齐
+  addHelpExample("fe-it-beta story login", "禅道登录, 缓存zentaosid");
+  addHelpExample("fe-it-beta story plan --product 87", "选计划看列表, 交互选导出");
+  addHelpExample("fe-it-beta story detail 需求ID", "按需求ID查看详情");
+  addHelpExample("fe-it-beta story task 项目ID", "选项目勾选需求, 交互建禅道任务");
+  addHelpExample(
+    "fe-it-beta story task 2915 --type front --split --cache",
+    "一键创建前端任务并自动拆分子任务"
+  );
+  addHelpExample("fe-it-beta story subtask 父任务ID", "给已建任务单独拆子任务(按剩余工时)");
+  addHelpExample(
+    "fe-it-beta story plan --product 87 --export front --cache",
+    "一键导出前端需求并生成多项目工作区"
+  );
 }
 
 /**
@@ -2821,9 +4795,9 @@ async function customColumnModule (lintc, fix, rule, parentRule, cliOpts = {}) {
 }
 
 async function getColumn(moduleArr = [], dynamicsArr = [], parentRule) {
-  let token;
+  let auth;
   try {
-    token = await login({
+    auth = await createAuth({
       env: "sit",
       username: "superAdmin",
       password: "admin1",
@@ -2833,16 +4807,36 @@ async function getColumn(moduleArr = [], dynamicsArr = [], parentRule) {
     return;
   }
   const requestArr = moduleArr.map(({ module, path }) =>
-    request$1({
-      url: `http://sit-hxjf.hongxinshop.com/api-item/api/customizedColumns/find`,
-      method: "POST",
-      json: true,
-      body: { module },
-      headers: {
-        Authorization: `Bearer ${token}`,
-        "x-request-vaildate": "open",
-      },
-    })
+    auth.request((t) =>
+      request$1({
+        url: `http://sit-hxjf.hongxinshop.com/api-item/api/customizedColumns/find`,
+        method: "POST",
+        json: true,
+        body: { module },
+        headers: {
+          Authorization: `Bearer ${t}`,
+          "x-request-vaildate": "open",
+        },
+      })
+        .then((body) => {
+          if (isAuthError(null, body)) {
+            throw Object.assign(new Error("登录态已失效"), {
+              isAuthError: true,
+            });
+          }
+          return body;
+        })
+        .catch((e) => {
+          if (e.isAuthError) throw e;
+          // request-promise 对非2xx reject StatusCodeError(含 response/body)
+          if (isAuthError(e.response, e.response?.body)) {
+            throw Object.assign(new Error("登录态已失效"), {
+              isAuthError: true,
+            });
+          }
+          throw e;
+        })
+    )
   );
   Promise.allSettled(requestArr).then(async (res) => {
     const tableData = [];
@@ -3088,6 +5082,16 @@ const helpExamples = [
   ],
   ["fe-it-beta -excel --file export.xlsx --lang vi --cache", ""],
 ];
+
+// ===== 分支子命令注册(命令定义在各分支模块内, 此处只登记) =====
+// 新增分支模块时: 模块导出 registerXxxCommand(program, helpers) 并在此追加一行
+let storyHandled = false;
+registerStoryCommand(commander.program, {
+  // 同步置位标记, 用于下方分发互斥(子命令调用后不再落入默认翻译分支)
+  markHandled: () => (storyHandled = true),
+  addHelpExample: (cmd, desc) => helpExamples.push([cmd, desc]),
+});
+
 commander.program.addHelpText(
   "after",
   "\n" +
@@ -3103,6 +5107,8 @@ commander.program.addHelpText(
       })
       .join("\n")
 );
+// 占位action: 阻止commander在注册子命令后, 无参调用直接输出help退出(保持落入下方默认翻译分支)
+commander.program.action(() => {});
 commander.program.parse(process.argv);
 
 // 判断命令参数
@@ -3138,7 +5144,7 @@ const rules = [
     ],
   },
 ];
-if (sass) {
+if (storyHandled) ; else if (sass) {
   sassMain(cliOpts).catch((error) => console.error(error));
 } else if (upload) {
   upload$1(cliOpts).catch((error) => console.error(error));
@@ -3431,6 +5437,52 @@ function translateUtil(appid, key, projectName, isLintFix, isMergeDecision) {
       // isMergeDecision: true/false为预决定值(一键执行), null表示仍需交互询问
       let isMerge = isMergeDecision;
       if (isMerge === null || isMerge === undefined) {
+        // 询问前预览当前export.xlsx(最近更新时间+内容), 便于判断覆盖还是合并
+        if (fs.existsSync("./export.xlsx")) {
+          const stat = fs.statSync("./export.xlsx");
+          const pad = (n) => String(n).padStart(2, "0");
+          const mtimeStr = `${stat.mtime.getFullYear()}-${pad(stat.mtime.getMonth() + 1)}-${pad(stat.mtime.getDate())} ${pad(stat.mtime.getHours())}:${pad(stat.mtime.getMinutes())}:${pad(stat.mtime.getSeconds())}`;
+          console.log(chalk.green(`export.xlsx 最近更新: ${mtimeStr}`));
+          try {
+            const rows = xlsx.parse(fs.readFileSync("./export.xlsx"))[0].data;
+            const headerRow = rows[0] || [];
+            const dataRows = rows.slice(1);
+            const PREVIEW_LIMIT = 20;
+            // 数据不超过2倍上限时全量展示, 避免头尾重叠导致重复打印
+            const previewRows =
+              dataRows.length <= PREVIEW_LIMIT * 2
+                ? dataRows
+                : [...dataRows.slice(0, PREVIEW_LIMIT), ...dataRows.slice(-PREVIEW_LIMIT)];
+            console.log(
+              chalk.green(
+                dataRows.length <= PREVIEW_LIMIT * 2
+                  ? `当前内容预览(共${dataRows.length}条数据):`
+                  : `当前内容预览(共${dataRows.length}条数据, 展示前${PREVIEW_LIMIT}条与倒数${PREVIEW_LIMIT}条):`
+              )
+            );
+            if (dataRows.length) {
+              // 仅展示编码与中文值两列, 避免全列表格(11列)在终端超宽; 列序以标题行为准, 找不到时退回默认列位(编码=3, 中文值=6)
+              const colIdx = (title, fallback) => {
+                const i = headerRow.indexOf(title);
+                return i < 0 ? fallback : i;
+              };
+              const codeIdx = colIdx("编码", 3);
+              const zhIdx = colIdx("中文值", 6);
+              console.table(
+                previewRows.map((row) => ({
+                  编码: row[codeIdx],
+                  中文值: row[zhIdx],
+                }))
+              );
+            } else {
+              console.log(chalk.yellow("当前文件无数据(仅标题或空文件)"));
+            }
+          } catch (error) {
+            console.log(chalk.yellow("export.xlsx 解析失败, 选择合并将按覆盖处理"));
+          }
+        } else {
+          console.log(chalk.yellow("export.xlsx 不存在, 本次将直接新建"));
+        }
         const res = await inquirer.prompt([
           {
             message: `是否合并至export.xlsx,默认${chalk.red("否,直接覆盖")}`,