@dreamor/atlas-cli 0.7.21 → 0.7.23

package/README.md

@@ -36,6 +36,7 @@ atlas <cmd> --describe
 ### 3. 鉴权
 
 - `atlas auth status` 返回 `data.loggedIn: boolean`
+- `atlas auth refresh` — 无头模式静默刷新 access_token（依赖 SSO_REFRESH_TOKEN）；session 过期时 agent 先试此命令
 - agent **不能自动执行** `atlas auth login`（弹浏览器做 SSO，非终端环境报 exit 64）
 
 ### 4. 退出码速查
@@ -43,10 +44,13 @@ atlas <cmd> --describe
 | 码 | 含义 | agent 应对 |
 |----|------|-----------|
 | 0 | 成功 | 继续 |
-| 2 | 会话过期 | 提示用户重新登录 |
+| 2 | 会话过期 | 先试 `atlas auth refresh`，失败再让用户手动 login |
 | 3 | API 错误 | 不重试 |
+| 4 | 项目匹配歧义 | 用 `atlas find project` 让用户挑 |
+| 5 | 项目未找到 | 改关键词重试 1 次后报告 |
 | 6 | 限流 | 退避 10s 重试 ≤1 次 |
 | 7 | 网络错误 | 退避 5s 重试 ≤1 次 |
+| 8 | 升级异常 | 忽略 |
 | 64 | 配置/未实现 | 不重试 |
 | 65 | 输出超限 | 改用 `--out <file>` |
 

package/dist/adapters/atlas/auth/index.js

@@ -1,3 +1,4 @@
-export { loginCmd, statusCmd } from './login.js';
+export { loginCmd, statusCmd, sandboxLoginGuide } from './login.js';
 export { refreshCmd, refreshSession } from './refresh.js';
 export { getSessionToken, getBanmaIdentity, readBanmaIdentity } from './session.js';
+export { exportCmd, importCmd, doctorCmd, recommendPath } from './portable.js';

package/dist/adapters/atlas/auth/login.js

@@ -111,8 +111,35 @@ export async function loginStatus() {
     }
     return { loggedIn: false };
 }
+/**
+ * 沙盒登录降级文案（对齐 dws 三条路径）。
+ * 纯函数，便于测试。
+ */
+export function sandboxLoginGuide(agentCode, reason) {
+    const head = reason ?? '无法拉起浏览器完成 SSO';
+    const agent = agentCode ? `（agent=${agentCode}, no DISPLAY/TTY）` : '（无浏览器环境）';
+    return `检测到当前是沙盒环境${agent}，${head}。请任选一种方式完成登录：
+
+  [推荐] 从本地宿主机导出登录态：
+    (本地) atlas auth export --base64
+    (沙盒) export ATLAS_COOKIES_B64=<粘贴上一步输出>
+           atlas auth doctor   # 确认识别成功
+
+  [网络可达宿主机] 复用 daemon：
+    (本地) atlas daemon
+    (沙盒) export ATLAS_DAEMON_URL=http://host.docker.internal:8765
+           export ATLAS_DAEMON_TOKEN=<~/.atlas/daemon.token 内容>
+           atlas auth status   # 走 daemon 透明鉴权
+
+  [文件传输] 直接拷贝 bundle：
+    (本地) atlas auth export -o /tmp/atlas-auth.tar.gz
+    (沙盒) atlas auth import -i /tmp/atlas-auth.tar.gz
+`;
+}
 export async function loginCmd(opts) {
-    // Try daemon first if cookies available
+    const { detectEnvironment } = await import('../util/environment.js');
+    const env = detectEnvironment();
+    // 优先复用 daemon（已存在逻辑）
     const daemonCookies = await fetchCookiesFromDaemon();
     if (daemonCookies && daemonCookies.length > 0) {
         await writeCookies(daemonCookies);
@@ -122,10 +149,23 @@ export async function loginCmd(opts) {
         }
         return;
     }
-    if (!process.stdout.isTTY) {
-        throw new AtlasError('atlas auth login 需要在终端中交互完成 SSO，当前为非终端环境。请手动在终端执行 `atlas auth login` 后重试', 'INTERACTIVE_REQUIRED');
+    // 沙盒环境：直接走引导路径，不尝试拉起 Firefox
+    if (!env.canLaunchBrowser) {
+        throw new AtlasError(sandboxLoginGuide(env.agentCode, env.isContainer ? '容器环境无法拉起 GUI' : '无 TTY/DISPLAY'), 'INTERACTIVE_REQUIRED');
+    }
+    // 本地环境：尝试拉起浏览器；失败降级为引导提示而非硬崩
+    try {
+        await login();
+    }
+    catch (e) {
+        log(sandboxLoginGuide(env.agentCode, '浏览器拉起失败'));
+        if (opts.json || isJsonMode()) {
+            // 已在 stderr 给出引导，仍抛出错误让上层以 INTERACTIVE_REQUIRED 退出
+        }
+        throw e instanceof Error
+            ? new AtlasError(`浏览器登录失败：${e.message}\n${sandboxLoginGuide(env.agentCode, '浏览器拉起失败')}`, 'INTERACTIVE_REQUIRED')
+            : e;
     }
-    await login();
     if (opts.json || isJsonMode()) {
         jsonOk({ status: 'logged_in' });
     }

package/dist/adapters/atlas/auth/portable.js

@@ -0,0 +1,193 @@
+/**
+ * atlas auth export / import / doctor 命令。
+ *
+ * 完全对齐 dws 参数：
+ *   atlas auth export [-o <path>] [--base64] [--refresh-only] [--include-access-token]
+ *   atlas auth import [-i <path>] [--base64] [--force] [--persist]
+ *   atlas auth doctor
+ *
+ * 安全护栏详见 docs/sandbox-login-plan.md §4.3/§4.4 与 §8。
+ */
+import { readFileSync } from 'fs';
+import { buildBundle, serializeBundleBase64, writeBundleToFile, parseBundleBase64, parseBundleFile, } from '../util/portable-store.js';
+import { detectEnvironment, resolveDaemonConfig, probeDaemonReachable, } from '../util/environment.js';
+import { readCookies, writeCookies } from './session.js';
+import { isJsonMode, jsonOk, log, printError } from '../util/output.js';
+import { ConfigError } from '../util/errors.js';
+import { getCookieFile } from '../util/paths.js';
+const REFRESH_TOKEN_WARNING = '⚠️  即将输出的 refresh token 是长期凭证，请仅在受信任的环境粘贴，且仅用于一次性导入。';
+/** 当前 ISO 时间戳（命令层调用，纯逻辑层不依赖） */
+function nowIso() {
+    return new Date().toISOString();
+}
+export async function exportCmd(opts) {
+    // refresh-only 默认开启；--include-access-token 显式关闭
+    const refreshOnly = opts.includeAccessToken ? false : opts.refreshOnly !== false;
+    const cookies = await readCookies();
+    if (!cookies || cookies.length === 0) {
+        throw new ConfigError('本地无登录态，无法导出。请先执行：atlas auth login');
+    }
+    const bundle = buildBundle(cookies, {
+        refreshOnly,
+        exportedAt: nowIso(),
+    });
+    // 输出到 stdout（base64 模式无 -o，明显是给 agent 管道用的，先打 stderr 警告）
+    if (opts.base64 && !opts.out) {
+        log(REFRESH_TOKEN_WARNING);
+        const b64 = await serializeBundleBase64(bundle);
+        process.stdout.write(b64 + '\n');
+        if (opts.json || isJsonMode()) {
+            // JSON 模式下也输出信封，但 stdout 已被 b64 占用——只在 stderr 给提示
+            log('（JSON 模式下 base64 优先写 stdout；信封省略）');
+        }
+        return;
+    }
+    // base64 模式 + -o：写到文件
+    if (opts.base64 && opts.out) {
+        const resolved = await writeBundleToFile(bundle, opts.out, true);
+        if (refreshOnly)
+            log(REFRESH_TOKEN_WARNING);
+        log(`已导出到 ${resolved}（refresh-only=${refreshOnly}，base64 文本）`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({ exported: true, path: resolved, refreshOnly, base64: true, count: bundle.cookies.length });
+        }
+        return;
+    }
+    // 无 base64 写二进制 gzip 文件（需 -o）
+    if (opts.out) {
+        const resolved = await writeBundleToFile(bundle, opts.out, false);
+        if (refreshOnly)
+            log(REFRESH_TOKEN_WARNING);
+        log(`已导出到 ${resolved}（refresh-only=${refreshOnly}，gzip 二进制）`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({ exported: true, path: resolved, refreshOnly, base64: false, count: bundle.cookies.length });
+        }
+        return;
+    }
+    // 既无 base64 也无 -o：默认走 base64 stdout（对齐 dws `export` 无参行为）
+    log(REFRESH_TOKEN_WARNING);
+    const b64 = await serializeBundleBase64(bundle);
+    process.stdout.write(b64 + '\n');
+}
+export async function importCmd(opts) {
+    const persist = opts.persist !== false; // 默认落盘
+    let bundle;
+    let osMismatch = false;
+    // 从 stdin 读 base64：--base64 且无 -i
+    if (opts.base64 && !opts.input) {
+        const b64 = readFileSync(0, 'utf-8').trim(); // fd 0 = stdin
+        const result = await parseBundleBase64(b64);
+        bundle = result.bundle;
+        osMismatch = result.warning.osMismatch;
+    }
+    else if (opts.input) {
+        const result = await parseBundleFile(opts.input);
+        bundle = result.bundle;
+        osMismatch = result.warning.osMismatch;
+    }
+    else {
+        throw new ConfigError('请指定导入源：-i <文件> 或 --base64 从 stdin 读取（如 ATLAS_COOKIES_B64 环境变量自动导入请使用环境变量方式）');
+    }
+    if (bundle.cookies.length === 0) {
+        throw new ConfigError('导入的 bundle 不含任何 cookies，请确认导出源已登录');
+    }
+    // 跨 OS 警告（不阻断）
+    if (osMismatch) {
+        log(`⚠️  bundle 在 ${bundle.manifest.os} 导出，当前为 ${process.platform}，跨平台 cookies 可能失效`);
+    }
+    // 已有 cookies 且未 --force 时拒绝覆盖
+    const existing = await readCookies();
+    if (existing && existing.length > 0 && !opts.force) {
+        throw new ConfigError('本地已存在登录态，拒绝覆盖。使用 --force 强制覆盖（将丢失旧 cookies）');
+    }
+    if (persist) {
+        await writeCookies(bundle.cookies);
+        log(`已导入 ${bundle.cookies.length} 个 cookies 到 ${getCookieFile()}`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({
+                imported: true,
+                count: bundle.cookies.length,
+                osMismatch,
+                refreshOnly: bundle.manifest.refreshOnly,
+                persisted: true,
+            });
+        }
+    }
+    else {
+        // 仅内存缓存（不落盘），用于一次性会话
+        // readCookies 走 cachedCookies，需手动注入缓存
+        const { __setCachedCookiesForImport } = await import('./session.js');
+        __setCachedCookiesForImport(bundle.cookies);
+        log(`已内存导入 ${bundle.cookies.length} 个 cookies（未落盘）`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({
+                imported: true,
+                count: bundle.cookies.length,
+                osMismatch,
+                refreshOnly: bundle.manifest.refreshOnly,
+                persisted: false,
+            });
+        }
+    }
+}
+/** 推导 recommendedPath（纯函数，便于测试） */
+export function recommendPath(opts) {
+    if (opts.canLaunchBrowser)
+        return 'browser';
+    if (opts.daemonReachable)
+        return 'daemon';
+    if (opts.cookiesReady)
+        return 'manual_export_hint';
+    return 'import';
+}
+export async function doctorCmd(opts) {
+    const env = detectEnvironment();
+    const daemonCfg = resolveDaemonConfig();
+    const daemonReachable = await probeDaemonReachable(daemonCfg.url ?? undefined, daemonCfg.token ?? undefined);
+    const recommendedPath = recommendPath({
+        canLaunchBrowser: env.canLaunchBrowser,
+        cookiesReady: env.cookiesReady,
+        daemonReachable,
+        daemonVia: daemonCfg.via,
+    });
+    const result = {
+        agentCode: env.agentCode,
+        agentSignal: env.agentSignal,
+        sandbox: !env.canLaunchBrowser,
+        canLaunchBrowser: env.canLaunchBrowser,
+        cookies: { path: getCookieFile(), present: env.cookiesReady, expired: null },
+        daemon: {
+            url: daemonCfg.url,
+            reachable: daemonReachable,
+            via: daemonCfg.via,
+        },
+        recommendedPath,
+    };
+    if (opts.json || isJsonMode()) {
+        jsonOk(result);
+        return;
+    }
+    // 人类可读输出
+    log('Atlas auth 诊断');
+    log(`  agent: ${env.agentCode || '(未识别)'} ${env.agentSignal ? `[${env.agentSignal}]` : ''}`);
+    log(`  沙盒环境: ${result.sandbox ? '是' : '否'}`);
+    log(`  可拉起浏览器: ${env.canLaunchBrowser ? '是' : '否'} (TTY=${env.hasTTY}, DISPLAY=${env.hasDisplay}, container=${env.isContainer})`);
+    log(`  本地 cookies: ${env.cookiesReady ? '已就绪' : '缺失'} (${getCookieFile()})`);
+    log(`  Daemon: ${daemonCfg.url ? `${daemonCfg.url} (${daemonCfg.via})` : '未配置'} - ${daemonReachable ? '可达' : '不可达'}`);
+    log(`  推荐路径: ${recommendedPath}`);
+    if (result.sandbox && !env.cookiesReady && !daemonReachable) {
+        log('');
+        log('沙盒登录引导：');
+        log('  [推荐] 从本地导出 → 沙盒导入：');
+        log('    (本地) atlas auth export --base64');
+        log('    (沙盒) export ATLAS_COOKIES_B64=<粘贴上一步输出> && atlas auth doctor');
+        log('  [或] 复用宿主机 daemon：');
+        log('    (本地) atlas daemon');
+        log('    (沙盒) export ATLAS_DAEMON_URL=http://host.docker.internal:8765');
+        log('           export ATLAS_DAEMON_TOKEN=<~/.atlas/daemon.token 内容>');
+    }
+}
+/** 兼容错误打印 helper（cli.ts handleError 用不到，保留给子命令内部用） */
+export function reportError(err, json) {
+    printError(err, { json });
+}

package/dist/adapters/atlas/auth/session.js

@@ -8,13 +8,27 @@ let cachedCookies = null;
 /**
  * 读取持久化的 cookies（从本地文件）
  * Playwright SSO 登录后将 cookies 写入此文件
+ *
+ * 沙盒免命令登录：本地文件缺失时若设置了 ATLAS_COOKIES_B64，则内存中一次性
+ * import（不落盘），让 agent 只注入 secret 就能用上。这条路径在 startAuthRefresh
+ * 之外的成本几乎为零，避免每次调用都重新解 base64/gzip。
  */
 export async function readCookies() {
     if (cachedCookies)
         return cachedCookies;
     try {
-        if (!existsSync(COOKIE_FILE))
+        if (!existsSync(COOKIE_FILE)) {
+            // 沙盒自动导入：ATLAS_COOKIES_B64 内存注入（不落盘）
+            const b64 = process.env.ATLAS_COOKIES_B64;
+            if (b64 && b64.trim().length > 0) {
+                const imported = await importFromEnvBase64(b64);
+                if (imported && imported.length > 0) {
+                    cachedCookies = imported;
+                    return imported;
+                }
+            }
             return null;
+        }
         const data = await readFile(COOKIE_FILE, 'utf-8');
         const cookies = JSON.parse(data);
         cachedCookies = cookies;
@@ -24,6 +38,34 @@ export async function readCookies() {
         return null;
     }
 }
+/**
+ * 解 ATLAS_COOKIES_B64 环境变量为新版 portable bundle（gzip+base64 JSON）。
+ * 兼容旧格式：纯 JSON 数组 cookies（无 manifest 包装）。
+ * 失败返回 null，绝不抛——避免阻塞主流程。
+ */
+async function importFromEnvBase64(b64) {
+    try {
+        const { parseBundleBase64 } = await import('../util/portable-store.js');
+        const { bundle } = await parseBundleBase64(b64);
+        return bundle.cookies;
+    }
+    catch {
+        // 兼容：直接是纯 JSON 数组字符串（非 gzip）
+        try {
+            const parsed = JSON.parse(b64);
+            if (Array.isArray(parsed))
+                return parsed;
+        }
+        catch {
+            // fallthrough
+        }
+        return null;
+    }
+}
+/** 仅内存导入（importCmd --persist=false 用），不落盘 */
+export function __setCachedCookiesForImport(cookies) {
+    cachedCookies = cookies;
+}
 export async function writeCookies(cookies) {
     cachedCookies = cookies;
     await secureMkdir(SESSION_DIR, { recursive: true });
@@ -39,22 +81,32 @@ export async function clearCookies() {
     }
 }
 /**
- * 从 daemon 获取 cookies（附带 daemon.token 鉴权）
+ * 从 daemon 获取 cookies（附带 Bearer token 鉴权）。
+ *
+ * 连接配置走 resolveDaemonConfig()：优先 ATLAS_DAEMON_URL + ATLAS_DAEMON_TOKEN
+ * （沙盒连宿主机 daemon），回退 localhost + 本机 ~/.atlas/daemon.token（本机复用）。
+ * 失败返回 null，绝不抛——调用方据此降级到本地 cookies。
  */
-export async function fetchCookiesFromDaemon(port = 8765) {
+export async function fetchCookiesFromDaemon() {
     try {
-        // 读取 daemon token 用于 Authorization header
-        const { getDaemonTokenFile } = await import('../util/paths.js');
-        const tokenFile = getDaemonTokenFile();
-        let token = '';
-        if (existsSync(tokenFile)) {
-            token = (await readFile(tokenFile, 'utf-8')).trim();
+        const { resolveDaemonConfig } = await import('../util/environment.js');
+        const cfg = resolveDaemonConfig();
+        if (!cfg.url)
+            return null;
+        // token：env 优先（ATLAS_DAEMON_TOKEN），回退本地 token 文件（default 分支）
+        let token = cfg.token ?? '';
+        if (!token) {
+            const { getDaemonTokenFile } = await import('../util/paths.js');
+            const tokenFile = getDaemonTokenFile();
+            if (existsSync(tokenFile)) {
+                token = (await readFile(tokenFile, 'utf-8')).trim();
+            }
         }
         const { request } = await import('undici');
         const headers = {};
         if (token)
             headers['Authorization'] = `Bearer ${token}`;
-        const resp = await request(`http://localhost:${port}/api/cookies`, {
+        const resp = await request(`${cfg.url.replace(/\/$/, '')}/api/cookies`, {
             headers,
             headersTimeout: 5000,
             bodyTimeout: 5000,

package/dist/adapters/atlas/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
 // Auth
-import { authLoginCmd, authStatusCmd, authRefreshCmd } from './commands/auth.js';
+import { authLoginCmd, authStatusCmd, authRefreshCmd, authExportCmd, authImportCmd, authDoctorCmd } from './commands/auth.js';
 // Project commands (find, projects, link, unlink)
 import { findCmd, projectsCmd, linkCmd, linkStatusCmd, unlinkCmd, } from './commands/project/index.js';
 // Baseline commands (month, summary, export)
@@ -143,6 +143,50 @@ function registerAuthCommands(program) {
             handleError(e);
         }
     });
+    auth
+        .command('export')
+        .description('导出登录态为便携 bundle（默认 --refresh-only 剥离短命 token）')
+        .option('-o, --out <path>', '输出文件路径（省略时 --base64 写 stdout）')
+        .option('--base64', 'base64 文本格式（gzip+JSON），方便管道/env 传输')
+        .option('--refresh-only', '仅长期凭证（默认开启）', true)
+        .option('--include-access-token', '包含短命 access_token（默认剥离）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await authExportCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    auth
+        .command('import')
+        .description('从便携 bundle 导入登录态（覆盖本地 cookies）')
+        .option('-i, --input <path>', '导入文件路径（省略 --base64 时从 stdin 读）')
+        .option('--base64', '输入为 base64 文本格式')
+        .option('--force', '本地已有登录态时强制覆盖')
+        .option('--persist', '落盘到 ~/.atlas/cookies.json（默认开启）', true)
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await authImportCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
+    auth
+        .command('doctor')
+        .description('诊断当前环境的登录路径（沙盒 agent 自省用）')
+        .option('--json', '输出 JSON 信封')
+        .action(async (opts) => {
+        try {
+            await authDoctorCmd(opts);
+        }
+        catch (e) {
+            handleError(e);
+        }
+    });
 }
 function registerProjectCommands(program) {
     // atlas find
@@ -291,6 +335,7 @@ function registerActualCommands(program) {
         .command('show <staffId>')
         .description('查看单个人员的实际工时明细'))
         .option('--month <yyyymm>', '查询月份（YYYY-MM，默认当前月）')
+        .option('--status <status>', '筛选审批状态: approved | pending | all', 'approved')
         .option('--json', '输出 JSON 信封')
         .action(async (staffId, opts) => {
         try {
@@ -307,7 +352,7 @@ function registerActualCommands(program) {
         .option('--month <yyyymm>', '查询月份（YYYY-MM，与 --from/--to 互斥）')
         .option('--from <yyyymm>', '起始月份（YYYY-MM，包含，与 --month 互斥）')
         .option('--to <yyyymm>', '结束月份（YYYY-MM，包含，与 --month 互斥）')
-        .option('--status <status>', '筛选审批状态: pending | approved | all', 'all')
+        .option('--status <status>', '筛选审批状态: approved | pending | all', 'approved')
         .option('--department <name>', '按团队负责人/部门筛选（子串，不区分大小写）')
         .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
         .option('--staff-name <name>', '按姓名/工号筛选（子串，不区分大小写）')
@@ -326,7 +371,7 @@ function registerActualCommands(program) {
         .description('按月/部门/角色汇总实际工时'))
         .option('--by <axis>', 'month | department | role', 'month')
         .option('--month <yyyymm>', '查询月份')
-        .option('--status <status>', 'pending | approved | all', 'all')
+        .option('--status <status>', 'approved | pending | all', 'approved')
         .option('--department <name>', '按部门筛选')
         .option('--role <name>', '按角色筛选')
         .option('--from <yyyymm>', '起始月份')
@@ -347,7 +392,7 @@ function registerActualCommands(program) {
         .requiredOption('--format <fmt>', 'csv | json')
         .requiredOption('--out <path>', '输出文件路径')
         .option('--by <axis>', 'month | department | role', 'month')
-        .option('--status <status>', 'pending | approved | all', 'all')
+        .option('--status <status>', 'approved | pending | all', 'approved')
         .option('--department <name>', '按部门筛选')
         .option('--role <name>', '按角色筛选')
         .option('--from <yyyymm>', '起始月份')
@@ -372,7 +417,7 @@ function registerCompareCommands(program) {
         .option('--month <yyyymm>', '查询月份（YYYY-MM，优先级高于 from/to 用于实际数据 API）')
         .option('--department <name>', '按部门名称/ID 筛选（子串，不区分大小写）')
         .option('--role <name>', '按角色/备注筛选（子串，不区分大小写）')
-        .option('--status <status>', '筛选审批状态: pending | approved | all', 'all')
+        .option('--status <status>', '筛选审批状态: approved | pending | all', 'approved')
         .option('--threshold <n>', '差异绝对值阈值（人月），低于此值不标记', '0')
         .option('--flag-overrun', '用 ⚠️ 标记实际 > 基线的情况')
         .option('--page <n>', '页码（从 1 开始）')
@@ -393,6 +438,11 @@ function registerUtilityCommands(program) {
         .command('daemon')
         .description('启动本地守护进程（沙盒环境使用，保持浏览器会话）')
         .option('--port <n>', '监听端口（默认 8765，也可用 ATLAS_DAEMON_PORT 环境变量）')
+        .option('--host <host>', '监听地址（默认 127.0.0.1；非 loopback 需配 --allow-ip 或 --insecure）')
+        .option('--allow-ip <cidr>', 'IP 白名单（CIDR 或单 IP，可多次传）', (v, p) => [...p, v], [])
+        .option('--tls-cert <path>', 'TLS 证书文件路径（需与 --tls-key 同时指定）')
+        .option('--tls-key <path>', 'TLS 私钥文件路径')
+        .option('--insecure', '显式允许明文监听非 loopback 接口（仅本机开发）')
         .option('--json', '输出 JSON 信封')
         .action(async (opts) => {
         try {

package/dist/adapters/atlas/commands/actual/_logic.js

@@ -4,8 +4,14 @@
  * 与命令解析层（index.ts）分离：这里不做 IO、不调 API、不输出，
  * 只做数据变换。便于单元测试（参见 tests/actual_logic.test.ts）。
  *
- * 单位约定：manpower 字段为人月（API 直接返回人月）。
+ * 单位约定（关键）：
+ * - API detail.manpower 字段单位为**人天**，不是人月。
+ * - 网页"人力汇总"页显示的人月 = Σ(叶子节点 detail.manpower) ÷ WORK_DAYS_PER_MONTH。
+ * - 经 2026-07-01 实测验证：BMW(2548) 2026-03 叶子节点合计 321.9 人天 ÷ 22 = 14.63 人月，
+ *   与网页"各项目显示值:已确认"完全一致。
  */
+/** 每月工作日，用于把 API 返回的人天换算为人月（与网页口径一致） */
+export const WORK_DAYS_PER_MONTH = 22;
 /**
  * expandMonths 已移至 util/months.ts，此处不再导出。
  */
@@ -13,6 +19,21 @@
 export function annotateWithMonth(entries, month) {
     return entries.map((p) => ({ ...p, month }));
 }
+/** 将 CLI 字符串选项规范化为 StatusFilter，默认 approved（与网站默认视图对齐） */
+export function normalizeStatusFilter(raw) {
+    if (raw === 'all' || raw === 'pending' || raw === 'approved')
+        return raw;
+    return 'approved';
+}
+/** 判断单条 detail 记录是否通过状态筛选 */
+function passesStatusFilter(statusRaw, filter) {
+    const status = Number(statusRaw);
+    if (filter === 'approved')
+        return status === 2;
+    if (filter === 'pending')
+        return status !== 2;
+    return true;
+}
 /**
  * 按轴聚合人月。
  * - month：按月份分组（需先用 annotateWithMonth 打标）
@@ -40,42 +61,56 @@ export function filterByStaff(entries, staffId) {
     return entries.filter((p) => p.staffId === staffId || p.staffName?.includes(staffId));
 }
 /**
- * 走查 summaryByTeam 返回的树结构，提取指定项目的实际工时条目。
+ * 走查 summaryByProject 返回的树结构，提取指定项目的实际工时条目（人月）。
+ *
+ * 关键口径（与网页"人力汇总"页一致，2026-07-01 实测验证）：
+ * 1. **只在叶子节点累加**：manager 节点的 detail 是下属汇总的副本，
+ *    若一并计入会把同一笔工时重复累加（实测会把 321.9 人天虚增到 440.6）。
+ *    叶子 = children 为 null 或空数组的节点。
+ * 2. **人天 ÷ 工作日 → 人月**：API detail.manpower 单位是人天，
+ *    需除以 WORK_DAYS_PER_MONTH(22) 才是网页显示的人月。
+ * 3. **状态筛选**：默认 approved 只统计 status===2（已确认），与网页默认视图对齐。
  *
- * 树中同一员工可能出现在 manager 层（汇总下属）和 leaf 层（个人），
- * 采取走最深层的策略：越深的节点 detail 越精确。
+ * 返回按员工去重的条目，manpower 为人月（四舍五入 2 位）。
  */
-export function flattenTree(nodes, targetPid) {
+export function flattenTree(nodes, targetPid, statusFilter = 'approved') {
     const byStaffId = new Map();
-    function walk(items, depth) {
+    function isLeaf(node) {
+        const kids = node.children;
+        return !Array.isArray(kids) || kids.length === 0;
+    }
+    function walk(items) {
         for (const raw of items ?? []) {
             const node = raw;
-            const details = (node.detail ?? []);
-            let projectManpower = 0;
-            for (const d of details) {
-                if (String(d.projectId) === targetPid) {
-                    projectManpower += Number(d.manpower ?? 0);
+            // 只在叶子节点累加 detail，避免 manager 层重复计入
+            if (isLeaf(node)) {
+                const details = (node.detail ?? []);
+                let personDays = 0;
+                for (const d of details) {
+                    if (String(d.projectId) === targetPid && passesStatusFilter(d.status, statusFilter)) {
+                        personDays += Number(d.manpower ?? 0);
+                    }
                 }
-            }
-            if (projectManpower > 0) {
-                const sid = String(node.staffId ?? '');
-                const existing = byStaffId.get(sid);
-                if (!existing || depth > existing.depth) {
+                if (personDays > 0) {
+                    const sid = String(node.staffId ?? '');
+                    const manMonths = personDays / WORK_DAYS_PER_MONTH;
+                    // 同一叶子节点不可能重复出现；若员工跨多节点，按 manpower 累加
+                    const existing = byStaffId.get(sid);
+                    const total = (existing?.manpower ?? 0) + manMonths;
                     byStaffId.set(sid, {
-                        depth,
-                        entry: {
-                            staffId: sid,
-                            staffName: String(node.realname ?? ''),
-                            manpower: Math.round(projectManpower * 100) / 100,
-                            departmentName: String(node.department ?? ''),
-                            role: String(node.role ?? ''),
-                        },
+                        staffId: sid,
+                        staffName: String(node.realname ?? ''),
+                        manpower: Math.round(total * 100) / 100,
+                        departmentName: String(node.department ?? ''),
+                        role: String(node.role ?? ''),
                     });
                 }
             }
-            walk(node.children, depth + 1);
+            else {
+                walk(node.children);
+            }
         }
     }
-    walk(nodes, 0);
-    return [...byStaffId.values()].map((v) => v.entry);
+    walk(nodes);
+    return [...byStaffId.values()];
 }