@dreamor/atlas-cli 0.7.22 → 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
@@ -394,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/auth.js

@@ -1 +1 @@
-export { loginCmd as authLoginCmd, statusCmd as authStatusCmd, refreshCmd as authRefreshCmd, } from '../auth/index.js';
+export { loginCmd as authLoginCmd, statusCmd as authStatusCmd, refreshCmd as authRefreshCmd, exportCmd as authExportCmd, importCmd as authImportCmd, doctorCmd as authDoctorCmd, } from '../auth/index.js';

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

@@ -1,10 +1,13 @@
-import { createServer } from 'http';
+import { createServer as httpCreateServer } from 'http';
+import { createServer as httpsCreateServer } from 'https';
 import { randomBytes, timingSafeEqual } from 'crypto';
+import { readFileSync } from 'fs';
 import { dirname } from 'path';
 import { log } from '../util/output.js';
 import { getDaemonTokenFile } from '../util/paths.js';
 import { secureMkdir, secureWriteFile } from '../util/secure-fs.js';
 import { AtlasError } from '../util/errors.js';
+import { parseCidrList, isIpAllowed, isLoopback, } from '../util/cidr.js';
 /** 生成 32 字节 hex token */
 function generateToken() {
     return randomBytes(32).toString('hex');
@@ -22,6 +25,50 @@ function isAuthorized(req, token) {
     }
     return timingSafeEqual(a, b);
 }
+/**
+ * 构造 daemon request handler。抽出为纯函数便于测试：
+ * 测试可直接用返回的 handler 起临时 http/https server。
+ *
+ * 路由：
+ * - GET /api/health → 公开，{ok, pid}
+ * - GET /api/cookies → 需 Bearer + IP 白名单，{ok, cookies}
+ * - 其他 → 404
+ */
+export function createDaemonHandler(deps) {
+    return (req, res) => {
+        const sendJson = (status, body) => {
+            res.writeHead(status, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify(body));
+        };
+        const url = req.url ?? '/';
+        const isHealth = url === '/api/health' || url === '/';
+        // health 端点不鉴权、不限 IP（用于探测）
+        if (isHealth) {
+            sendJson(200, { ok: true, pid: process.pid });
+            return;
+        }
+        // IP 白名单（非 health 端点都校验）
+        if (!isIpAllowed(req.socket.remoteAddress, deps.allowList)) {
+            sendJson(403, { ok: false, error: 'forbidden: ip not allowed' });
+            return;
+        }
+        // Bearer 鉴权
+        if (!isAuthorized(req, deps.token)) {
+            sendJson(401, { ok: false, error: 'unauthorized' });
+            return;
+        }
+        if (url === '/api/cookies') {
+            void deps
+                .readCookies()
+                .then((cookies) => sendJson(200, { ok: true, cookies: cookies ?? [] }))
+                .catch(() => sendJson(500, { ok: false, error: 'read cookies failed' }));
+            return;
+        }
+        sendJson(404, { ok: false, error: 'not found' });
+    };
+}
+/** 默认端口号 */
+const DEFAULT_PORT = 8765;
 export async function daemonCmd(opts) {
     const envPort = Number(process.env.ATLAS_DAEMON_PORT);
     const optsPort = opts.port !== undefined ? Number(opts.port) : NaN;
@@ -29,24 +76,57 @@ export async function daemonCmd(opts) {
         ? optsPort
         : Number.isFinite(envPort) && envPort > 0
             ? envPort
-            : 8765;
+            : DEFAULT_PORT;
+    const host = opts.host ?? '127.0.0.1';
+    const hostLoopback = isLoopback(host);
+    const hasTls = Boolean(opts.tlsCert) && Boolean(opts.tlsKey);
+    // 护栏 1：TLS cert/key 必须同时指定
+    if ((opts.tlsCert && !opts.tlsKey) || (opts.tlsKey && !opts.tlsCert)) {
+        throw new AtlasError('--tls-cert 与 --tls-key 必须同时指定', 'CONFIG_ERROR');
+    }
+    // 护栏 2：非 loopback 监听必须有 IP 白名单或显式 --insecure
+    if (!hostLoopback && !opts.insecure && (!opts.allowIp || opts.allowIp.length === 0)) {
+        throw new AtlasError('非 loopback 监听必须指定 --allow-ip 或显式 --insecure（明文传输 token 仅建议本机开发）', 'CONFIG_ERROR');
+    }
+    // 护栏 3：非 loopback + 无 TLS + 明文 → stderr 大红警告
+    if (!hostLoopback && !hasTls && opts.insecure) {
+        log('⚠⚠⚠ 明文监听非 loopback 接口，Bearer token 将以明文传输，仅建议本机开发使用 ⚠⚠⚠');
+    }
+    // 解析 IP 白名单（非法 CIDR 在此抛 ConfigError，启动期失败而非运行期）
+    const allowList = parseCidrList(opts.allowIp);
     // 生成一次性 token，写入 ~/.atlas/daemon.token（0600）
     const token = generateToken();
     const tokenFile = getDaemonTokenFile();
     await secureMkdir(dirname(tokenFile), { recursive: true });
     await secureWriteFile(tokenFile, token);
     log(`Daemon token 已写入 ${tokenFile}`);
-    const server = createServer((req, res) => {
-        // 除 /api/health 外所有端点均需鉴权
-        const isHealth = req.url === '/api/health';
-        if (!isHealth && !isAuthorized(req, token)) {
-            res.writeHead(401, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ ok: false, error: 'unauthorized' }));
-            return;
+    // 动态 import readCookies 避免与 session 模块的循环依赖
+    const handlerDeps = {
+        token,
+        allowList,
+        readCookies: async () => {
+            const { readCookies } = await import('../auth/session.js');
+            return readCookies();
+        },
+    };
+    const handler = createDaemonHandler(handlerDeps);
+    // 创建 server（http 或 https）
+    let server;
+    if (hasTls) {
+        let cert;
+        let key;
+        try {
+            cert = readFileSync(opts.tlsCert);
+            key = readFileSync(opts.tlsKey);
         }
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(JSON.stringify({ ok: true, pid: process.pid }));
-    });
+        catch (e) {
+            throw new AtlasError(`TLS 证书读取失败：${e.message}`, 'CONFIG_ERROR');
+        }
+        server = httpsCreateServer({ cert, key }, handler);
+    }
+    else {
+        server = httpCreateServer(handler);
+    }
     await new Promise((resolve, reject) => {
         server.on('error', (e) => {
             if (e.code === 'EADDRINUSE') {
@@ -56,9 +136,10 @@ export async function daemonCmd(opts) {
                 reject(e);
             }
         });
-        server.listen(port, '127.0.0.1', resolve);
+        server.listen(port, host, resolve);
     });
-    log(`守护进程已启动，监听 127.0.0.1:${port}`);
+    const scheme = hasTls ? 'https' : 'http';
+    log(`守护进程已启动，监听 ${scheme}://${host}:${port}${!hostLoopback && !hasTls && opts.insecure ? '（明文）' : ''}`);
     // Keep running
     await new Promise(() => { });
 }

package/dist/adapters/atlas/util/cidr.js

@@ -0,0 +1,114 @@
+import { ConfigError } from './errors.js';
+const IPV4_OCTET = '(25[0-5]|2[0-4]\\d|1\\d\\d|[1-9]?\\d)';
+const IPV4_RE = new RegExp(`^${IPV4_OCTET}(\\.${IPV4_OCTET}){3}$`);
+const IPV6_FULL_RE = /^[0-9a-fA-F:]+$/;
+/** 是否为 loopback 监听地址（127.0.0.1 / ::1 / localhost） */
+export function isLoopback(host) {
+    if (!host)
+        return false;
+    const h = host.toLowerCase().trim();
+    if (h === 'localhost' || h === '::1')
+        return true;
+    if (IPV4_RE.test(h) && h.startsWith('127.'))
+        return true;
+    return false;
+}
+/** 规范化对端地址：去 IPv4-mapped IPv6 前缀 ::ffff: */
+export function normalizeRemoteAddr(addr) {
+    if (!addr)
+        return '';
+    const trimmed = addr.trim();
+    // ::ffff:1.2.3.4 或 ::ffff:a.b.c.d
+    const mapped = trimmed.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i);
+    if (mapped)
+        return mapped[1];
+    // 也可能出现 ::ffff:xxx.xxx.xxx.xxx 之外的形式，如 2002:... 退回原值
+    return trimmed;
+}
+/** IPv4 点分十进制 → 32 位无符号整数；非法返回 null */
+function ipv4ToInt(ip) {
+    if (!IPV4_RE.test(ip))
+        return null;
+    const parts = ip.split('.').map(Number);
+    // 防止前导零或多段异常（正则已挡，此处二次保险）
+    return (((parts[0] << 24) >>> 0) + (parts[1] << 16) + (parts[2] << 8) + parts[3]) >>> 0;
+}
+function intToIpv4(n) {
+    return [(n >>> 24) & 0xff, (n >>> 16) & 0xff, (n >>> 8) & 0xff, n & 0xff].join('.');
+}
+/**
+ * 解析 CIDR/单 IP 列表为结构化条目。
+ * - IPv4 单 IP 视作 /32，IPv6 单 IP 视作 /128
+ * - IPv6 CIDR 暂不支持（抛 ConfigError），仅允许 IPv6 单 IP
+ * - 非法格式抛 ConfigError，message 含原始输入
+ */
+export function parseCidrList(input) {
+    if (!input || input.length === 0)
+        return [];
+    const entries = [];
+    for (const raw of input) {
+        const item = raw.trim();
+        if (!item)
+            continue;
+        if (item.includes(':')) {
+            // IPv6：仅支持单 IP 全等比较
+            if (item.includes('/')) {
+                throw new ConfigError(`暂不支持 IPv6 CIDR（仅单 IP）：${raw}`);
+            }
+            if (!IPV6_FULL_RE.test(item)) {
+                throw new ConfigError(`非法 IPv6 地址：${raw}`);
+            }
+            entries.push({ raw, family: 'ipv6', network: item.toLowerCase(), prefix: 128 });
+            continue;
+        }
+        // IPv4：CIDR 或单 IP
+        if (item.includes('/')) {
+            const [ip, prefixStr] = item.split('/');
+            const ipInt = ipv4ToInt(ip);
+            const prefix = Number(prefixStr);
+            if (ipInt === null)
+                throw new ConfigError(`非法 IPv4 网络地址：${raw}`);
+            if (!Number.isInteger(prefix) || prefix < 0 || prefix > 32) {
+                throw new ConfigError(`非法 IPv4 前缀长度：${raw}`);
+            }
+            const mask = prefix === 0 ? 0 : (0xffffffff << (32 - prefix)) >>> 0;
+            const netInt = (ipInt & mask) >>> 0;
+            entries.push({ raw, family: 'ipv4', network: intToIpv4(netInt), prefix });
+        }
+        else {
+            const ipInt = ipv4ToInt(item);
+            if (ipInt === null)
+                throw new ConfigError(`非法 IPv4 地址：${raw}`);
+            entries.push({ raw, family: 'ipv4', network: intToIpv4(ipInt), prefix: 32 });
+        }
+    }
+    return entries;
+}
+/**
+ * 判断对端地址是否命中白名单。
+ * - allowList 为空 → 放行（向后兼容 loopback 默认）
+ * - 未提供地址 → 拒绝（无法判定时安全优先）
+ */
+export function isIpAllowed(remoteAddr, allowList) {
+    if (allowList.length === 0)
+        return true;
+    const addr = normalizeRemoteAddr(remoteAddr);
+    if (!addr)
+        return false;
+    for (const entry of allowList) {
+        if (entry.family === 'ipv6') {
+            // IPv6 单 IP 全等比较
+            if (addr.toLowerCase() === entry.network)
+                return true;
+            continue;
+        }
+        // IPv4 CIDR 匹配
+        const ipInt = ipv4ToInt(addr);
+        if (ipInt === null)
+            continue;
+        const mask = entry.prefix === 0 ? 0 : (0xffffffff << (32 - entry.prefix)) >>> 0;
+        if (((ipInt & mask) >>> 0) === (ipv4ToInt(entry.network) >>> 0))
+            return true;
+    }
+    return false;
+}

package/dist/adapters/atlas/util/environment.js

@@ -0,0 +1,152 @@
+/**
+ * 沙盒环境识别（对齐 dws agent_code_detect）。
+ *
+ * 四级信号优先级（高 → 低），命中即返回，绝不猜：
+ *   T0  ATLAS_AGENT_CODE 环境变量（显式声明，最高优先级）
+ *   T1  CLI 内嵌签名（claudecode/openclaw/codex/hermes/wukong）
+ *   T2  VSCODE_BRAND（覆盖 Cursor/Qoder/Trae 等 VS Code fork）
+ *   T3  macOS __CFBundleIdentifier（qoder/cursor/vscode/wukong）
+ *   T4  未识别 → 空字符串
+ *
+ * 同时探测沙盒能力（TTY / DISPLAY / 容器 / 浏览器可拉起 / cookies 就绪 / daemon
+ * 可达）。daemon 探测涉及网络 IO，由 detectEnvironmentAsync 单独暴露。
+ */
+import { existsSync } from 'fs';
+import { hostname, platform } from 'os';
+import { getCookieFile, getDaemonTokenFile } from './paths.js';
+/** 已验证的 T1 CLI 签名（envKeys 任一存在即命中） */
+const KNOWN_SIGNATURES = [
+    { code: 'claudecode', envKeys: ['CLAUDECODE', 'CLAUDE_CODE_ENTRYPOINT'] },
+    { code: 'openclaw', envKeys: ['OPENCLAW_BUNDLE_ROOT', 'OPENCLAW_RUNTIME_ROLE'] },
+    { code: 'codex', envKeys: ['CODEX_SANDBOX'] },
+    { code: 'hermes', envKeys: ['HERMES_HOME'] },
+    { code: 'wukong', envKeys: ['WUKONG_SANDBOX', 'WUKONG_RUNTIME'] },
+];
+/** T3: macOS bundle id → agent_code 映射（仅取已验证条目） */
+const BUNDLE_ID_MAP = [
+    { code: 'cursor', bundlePrefix: 'com.todesktop.' }, // cursor 包名为 com.todesktop.230313mzl4w4u92
+    { code: 'qoder', bundlePrefix: 'com.qoder.' },
+    { code: 'vscode', bundlePrefix: 'com.microsoft.VSCode' },
+    { code: 'wukong', bundlePrefix: 'com.antgroup.wukong' },
+];
+/** 同步检测 agent_code（不触碰网络/磁盘可变状态，便于单测）。 */
+export function detectAgentCode(env = process.env) {
+    // T0: 显式声明最高优先级
+    const explicit = env.ATLAS_AGENT_CODE;
+    if (typeof explicit === 'string' && explicit.trim()) {
+        return { agentCode: explicit.trim(), agentSignal: 'env:ATLAS_AGENT_CODE' };
+    }
+    // T1: CLI 内嵌签名
+    for (const sig of KNOWN_SIGNATURES) {
+        for (const k of sig.envKeys) {
+            const v = env[k];
+            if (typeof v === 'string' && v.length > 0) {
+                return { agentCode: sig.code, agentSignal: `env:${k}` };
+            }
+        }
+    }
+    // T2: VSCODE_BRAND（覆盖所有 VS Code fork：Cursor/Qoder/Trae 等）
+    const brand = env.VSCODE_BRAND;
+    if (typeof brand === 'string' && brand.trim()) {
+        return { agentCode: brand.trim().toLowerCase(), agentSignal: 'env:VSCODE_BRAND' };
+    }
+    // T3: macOS __CFBundleIdentifier
+    const bundle = env.__CFBundleIdentifier;
+    if (typeof bundle === 'string' && bundle.length > 0) {
+        for (const m of BUNDLE_ID_MAP) {
+            if (bundle.startsWith(m.bundlePrefix) || bundle === m.bundlePrefix) {
+                return { agentCode: m.code, agentSignal: `bundle:${bundle}` };
+            }
+        }
+    }
+    // T4: 未识别 → 空
+    return { agentCode: '', agentSignal: '' };
+}
+/** 判断是否处于 Linux 容器内（/.dockerenv 或 $container 变量） */
+export function detectContainer(env = process.env) {
+    if (existsSync('/.dockerenv'))
+        return true;
+    const c = env.container;
+    if (typeof c === 'string' && c.trim() && c !== 'off')
+        return true;
+    // Kubernetes 常见信号
+    if (env.KUBERNETES_SERVICE_HOST)
+        return true;
+    return false;
+}
+/** 是否存在 DISPLAY（Linux X11/Wayland）/ macOS 原生 GUI */
+export function detectHasDisplay(env = process.env) {
+    if (typeof env.DISPLAY === 'string' && env.DISPLAY.length > 0)
+        return true;
+    if (typeof env.WAYLAND_DISPLAY === 'string' && env.WAYLAND_DISPLAY.length > 0)
+        return true;
+    // macOS 即使无 DISPLAY 变量也有原生 GUI
+    if (platform() === 'darwin')
+        return true;
+    return false;
+}
+/** ATLAS_SANDBOX=1 可显式强制沙盒行为（测试/调试用） */
+function isForcedSandbox(env) {
+    return env.ATLAS_SANDBOX === '1' || env.ATLAS_SANDBOX === 'true';
+}
+/**
+ * 同步环境能力快照（不探测 daemon，避免阻塞）。
+ * daemon 可达性见 detectEnvironmentAsync()。
+ */
+export function detectEnvironment(env = process.env) {
+    const { agentCode, agentSignal } = detectAgentCode(env);
+    const hasTTY = Boolean(process.stdout.isTTY);
+    const hasDisplay = detectHasDisplay(env);
+    const isContainer = detectContainer(env);
+    const forcedSandbox = isForcedSandbox(env);
+    // 受信任的 GUI 拉起：需要 TTY + DISPLAY 且非容器；ATLAS_SANDBOX=1 强制视为不可拉起
+    const canLaunchBrowser = !forcedSandbox && hasDisplay && !isContainer && hasTTY;
+    const cookiesReady = existsSync(getCookieFile());
+    return {
+        agentCode,
+        agentSignal,
+        hasTTY,
+        hasDisplay,
+        isContainer: isContainer || forcedSandbox,
+        canLaunchBrowser,
+        cookiesReady,
+        daemonReachable: null,
+    };
+}
+/** 异步探测 daemon 是否可达（带超时）。失败返回 false，绝不抛。 */
+export async function probeDaemonReachable(url, token, timeoutMs = 1500) {
+    if (!url)
+        return false;
+    try {
+        const { request } = await import('undici');
+        const headers = {};
+        if (token)
+            headers['Authorization'] = `Bearer ${token}`;
+        const resp = await request(`${url.replace(/\/$/, '')}/api/health`, {
+            headers,
+            headersTimeout: timeoutMs,
+            bodyTimeout: timeoutMs,
+        });
+        return resp.statusCode === 200;
+    }
+    catch {
+        return false;
+    }
+}
+/** 从环境变量 + 默认 token 文件解析 daemon 连接配置（不发起请求） */
+export function resolveDaemonConfig(env = process.env) {
+    const envUrl = env.ATLAS_DAEMON_URL;
+    const envToken = env.ATLAS_DAEMON_TOKEN;
+    if (envUrl) {
+        return { url: envUrl, token: envToken ?? null, via: 'env' };
+    }
+    // 回退默认 localhost + 本机 token 文件
+    const tokenFileExists = existsSync(getDaemonTokenFile());
+    if (tokenFileExists) {
+        const envPort = Number(env.ATLAS_DAEMON_PORT);
+        const port = Number.isFinite(envPort) && envPort > 0 ? envPort : 8765;
+        return { url: `http://localhost:${port}`, token: null, via: 'default' };
+    }
+    return { url: null, token: null, via: 'none' };
+}
+export const __DEV__ = { hostname, getCookieFile, getDaemonTokenFile };

package/dist/adapters/atlas/util/portable-store.js

@@ -0,0 +1,153 @@
+/**
+ * 便携登录态 bundle（对齐 dws portableAuthBundleManifest）。
+ *
+ * bundle 结构（gzip + JSON 明文，复用 cookies 已明文的事实）：
+ *
+ *   atlas-auth.tar.gz（实际是 gzip(JSON) 单文件，非真 tar — 简化实现）
+ *   └── { manifest: {...}, cookies: [...] }
+ *
+ * base64 模式 = base64(gzip(JSON))，方便通过 env / 管道传输。
+ *
+ * 安全：--refresh-only 默认开启，剥离短命 token（access_token* / refresh_token*），
+ * 只保留 SSO_REFRESH_TOKEN + buc_* + 身份相关 cookies。导出文件权限 0600
+ * （secureWriteFile）。
+ *
+ * 零运行时依赖：仅用 node:zlib + secure-fs。
+ */
+import { gzip, gunzip } from 'zlib';
+import { promisify } from 'util';
+import { readFile, mkdir } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { existsSync } from 'fs';
+import { secureWriteFile } from './secure-fs.js';
+import { ConfigError } from './errors.js';
+import { platform } from 'os';
+const gzipAsync = promisify(gzip);
+const gunzipAsync = promisify(gunzip);
+export const BUNDLE_SCHEMA = 'atlas.auth.bundle/v1';
+export const BUNDLE_VERSION = 1;
+/** 短命 token cookie 名集合（--refresh-only 时剥离） */
+const EPHEMERAL_TOKEN_NAMES = new Set([
+    'access_token',
+    'access_token.sig',
+    'refresh_token',
+    'refresh_token.sig',
+]);
+/** 构造 bundle（纯函数） */
+export function buildBundle(cookies, opts) {
+    const filtered = opts.refreshOnly === false
+        ? cookies
+        : cookies.filter((c) => !EPHEMERAL_TOKEN_NAMES.has(c.name));
+    return {
+        manifest: {
+            schema: BUNDLE_SCHEMA,
+            version: BUNDLE_VERSION,
+            os: opts.os ?? platform(),
+            exportedAt: opts.exportedAt,
+            refreshOnly: opts.refreshOnly,
+        },
+        cookies: filtered,
+    };
+}
+/** 序列化为 gzip + base64 字符串（适合 --base64 stdout） */
+export async function serializeBundleBase64(bundle) {
+    const json = JSON.stringify(bundle);
+    const zipped = await gzipAsync(Buffer.from(json, 'utf-8'));
+    return zipped.toString('base64');
+}
+/** 序列化为 gzip Buffer（适合写文件） */
+export async function serializeBundleBuffer(bundle) {
+    const json = JSON.stringify(bundle);
+    return gzipAsync(Buffer.from(json, 'utf-8'));
+}
+/** 校验 manifest schema/version，失败抛 ConfigError */
+function assertManifest(m) {
+    if (!m || typeof m !== 'object') {
+        throw new ConfigError('无效 bundle：manifest 缺失');
+    }
+    const o = m;
+    if (o.schema !== BUNDLE_SCHEMA) {
+        throw new ConfigError(`无效 bundle：schema 不匹配（期望 ${BUNDLE_SCHEMA}，实际 ${String(o.schema)}）`);
+    }
+    if (typeof o.version !== 'number' || o.version > BUNDLE_VERSION) {
+        throw new ConfigError(`无效 bundle：版本不支持（当前 ${BUNDLE_VERSION}，bundle ${String(o.version)}）`);
+    }
+    if (!Array.isArray(o.cookies) === false && !o.cookies === undefined) {
+        // bundles with cookies at top handled below; manifest-only ok
+    }
+}
+/** 解析 base64 字符串 → AuthBundle */
+export async function parseBundleBase64(b64) {
+    const buf = Buffer.from(b64.trim(), 'base64');
+    let json;
+    try {
+        json = (await gunzipAsync(buf)).toString('utf-8');
+    }
+    catch {
+        // 兼容未压缩的纯 base64 JSON（少数手动构造场景）
+        try {
+            json = buf.toString('utf-8');
+        }
+        catch {
+            throw new ConfigError('无效 bundle：base64 解码失败');
+        }
+    }
+    return parseBundleJson(json);
+}
+/** 解析文件（gzip 二进制 或 base64 文本）→ AuthBundle */
+export async function parseBundleFile(path) {
+    if (!existsSync(path)) {
+        throw new ConfigError(`导入文件不存在：${path}`);
+    }
+    const raw = await readFile(path);
+    // 二进制 gzip 文件（前两字节 0x1f 0x8b）
+    if (raw.length >= 2 && raw[0] === 0x1f && raw[1] === 0x8b) {
+        const json = (await gunzipAsync(raw)).toString('utf-8');
+        return parseBundleJson(json);
+    }
+    // 否则按 base64 文本处理
+    return parseBundleBase64(raw.toString('utf-8'));
+}
+function parseBundleJson(json) {
+    let obj;
+    try {
+        obj = JSON.parse(json);
+    }
+    catch {
+        throw new ConfigError('无效 bundle：JSON 解析失败');
+    }
+    if (!obj || typeof obj !== 'object') {
+        throw new ConfigError('无效 bundle：根节点非对象');
+    }
+    const o = obj;
+    assertManifest(o.manifest);
+    if (!Array.isArray(o.cookies)) {
+        throw new ConfigError('无效 bundle：cookies 字段非数组');
+    }
+    const bundle = {
+        manifest: o.manifest,
+        cookies: o.cookies,
+    };
+    const currentOs = platform();
+    return {
+        bundle,
+        warning: {
+            osMismatch: bundle.manifest.os !== currentOs,
+            refreshOnly: bundle.manifest.refreshOnly,
+        },
+    };
+}
+/**
+ * 写 bundle 到文件路径（secureWriteFile 0600）。
+ *
+ * 与 baseline/actual export 的 --out 白名单（resolveSecureExportPath）不同：
+ * auth export 输出的是便携凭证 bundle，用户主动指定任意路径（如 /tmp 方便传输
+ * 到沙盒）是其核心用例，因此放宽为绝对/相对路径均可，但仍以 0600 写入。
+ */
+export async function writeBundleToFile(bundle, outPath, base64) {
+    const resolved = resolve(process.cwd(), outPath);
+    const content = base64 ? await serializeBundleBase64(bundle) : await serializeBundleBuffer(bundle);
+    await mkdir(dirname(resolved), { recursive: true });
+    await secureWriteFile(resolved, content);
+    return resolved;
+}

package/dist/adapters/atlas/util/version.js

@@ -1 +1 @@
-export const ATLAS_VERSION = '0.7.22';
+export const ATLAS_VERSION = '0.7.23';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamor/atlas-cli",
-  "version": "0.7.22",
+  "version": "0.7.23",
   "description": "Atlas CLI - 斑马云图人力基线管理工具",
   "type": "module",
   "bin": {