@dreamor/atlas-cli 0.7.1 → 0.7.3

package/README.md

@@ -1,84 +1,61 @@
-# Atlas CLI
-
-> 斑马云图（Banma）人力基线管理工具
-
-## 安装
+# @dreamor/atlas-cli
 
 ```bash
 npm i -g @dreamor/atlas-cli
 ```
 
-> Node 20+ 是引擎基线（package.json 已声明 `engines.node: >=20`）。
+> Node 20+
 
-## 升级
+---
 
-```bash
-npm update -g @dreamor/atlas-cli
-```
+## For Agents
 
-## 首次使用
+本 CLI 设计为 AI agent 可自省调用的接口工具。以下是 agent 需要知道的契约。
+
+### 1. JSON 模式
+
+所有命令支持 `--json` 或环境变量 `ATLAS_OUTPUT=json`：
 
 ```bash
-atlas --help
-atlas auth login       # 打开浏览器完成 SSO 登录
-atlas auth status     # 检查登录态
+ATLAS_OUTPUT=json atlas auth status
+atlas baseline month --month 2026-06 --json
 ```
 
-`auth login` 需要 Playwright 启动无头浏览器（仅首次）：
+stdout 始终是统一 JSON 信封；进度日志走 stderr，不污染管道。
+
+### 2. 发现入口
 
 ```bash
-npm i -g playwright
-npx playwright install chromium
+# 命令树 + 每个命令的参数 schema + 输出 schema
+atlas schema commands --describe
+
+# 单命令自省
+atlas <cmd> --describe
 ```
 
-未安装时 CLI 会给清晰提示，不会阻塞主命令的安装与运行。
-
-## 会话存储
-
-- macOS：默认使用 Keychain（依赖 `keytar`，通常随 Atlas 安装自动就绪）
-- 其他平台或 `keytar` 安装失败：自动降级到文件存储（`~/.atlas/cookies.json`）
-
-## 命令速览
-
-| 命令 | 说明 |
-|------|------|
-| `atlas --help` | 帮助 |
-| `atlas auth {login,status}` | SSO 登录/状态 |
-| `atlas find <kind> <query>` | 搜索 project / department / mp-type / line-plan-type / area-code |
-| `atlas projects` | 列出你有权限的项目 |
-| `atlas link [project]` / `unlink` | 绑定/解绑默认项目 |
-| `atlas baseline month/summary/export` | 基线（计划）人力 |
-| `atlas actual show/month/summary/export` | 实际工时 |
-| `atlas compare` | 基线 vs 实际对比 |
-| `atlas schema {export,commands}` | CLI 自省（字典/参数 schema） |
-| `atlas daemon` | 本地守护进程 |
-| `atlas exec --plan-file <path>` | 批量执行（agent 用） |
-| `atlas update` | 由 npm registry 管理，CLI 只提示更新命令 |
-| `atlas suggest <query>` | 自然语言→命令翻译 |
-
-## 全局选项
-
-- `--json` / `ATLAS_OUTPUT=json`：JSON 信封输出
-- `--quiet` / `ATLAS_QUIET=1`：静默
-- `--describe`：输出参数 schema（agent 自省）
-
-## 退出码
-
-| 码 | 含义 |
-|----|------|
-| 0 | 成功 |
-| 1 | 通用错误 |
-| 2 | 会话过期 |
-| 3 | API 错误 |
-| 4 | 项目匹配歧义 |
-| 5 | 项目未找到 |
-| 6 | API 限流 |
-| 7 | 网络错误 |
-| 8 | 版本更新异常 |
-| 64 | 配置错误/未实现 |
-
-## 文档
-
-- [INSTALL.md](./INSTALL.md) — 安装/环境变量/故障排查
-- [CHANGELOG.md](./CHANGELOG.md) — 变更日志
-- [CLAUDE.md](./CLAUDE.md) — 开发者指南（架构、命令、设计决策）
+### 3. 鉴权
+
+- `atlas auth status` 返回 `data.loggedIn: boolean`
+- agent **不能自动执行** `atlas auth login`（弹浏览器做 SSO，非终端环境报 exit 64）
+
+### 4. 退出码速查
+
+| 码 | 含义 | agent 应对 |
+|----|------|-----------|
+| 0 | 成功 | 继续 |
+| 2 | 会话过期 | 提示用户重新登录 |
+| 3 | API 错误 | 不重试 |
+| 6 | 限流 | 退避 10s 重试 ≤1 次 |
+| 7 | 网络错误 | 退避 5s 重试 ≤1 次 |
+| 64 | 配置/未实现 | 不重试 |
+| 65 | 输出超限 | 改用 `--out <file>` |
+
+### 5. Skill 入口
+
+完整 agent 行为契约见 [.claude/skills/atlas/SKILL.md](.claude/skills/atlas/SKILL.md)
+
+### 6. 数据单位
+
+- 所有 `manpower` 字段 = **人月**（不要二次换算）
+- `atlas compare`：`diff = 实际 - 基线`（人月），**不要再除 22**
+- 月份格式 `YYYY-MM`，已修正 CST 偏移

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

@@ -1,2 +1,2 @@
 export { loginCmd, statusCmd } from './login.js';
-export { getSessionToken, readSession, writeSession, clearSession, getBanmaIdentity, readBanmaIdentity } from './session.js';
+export { getSessionToken, getBanmaIdentity, readBanmaIdentity } from './session.js';

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

@@ -1,5 +1,6 @@
 import { writeCookies, readCookies, fetchCookiesFromDaemon } from './session.js';
 import { isJsonMode, jsonOk, log } from '../util/output.js';
+import { AtlasError } from '../util/errors.js';
 const BANMA_HOST = 'banma-yuntu.alibaba-inc.com';
 // 白名单：只保存 getBanmaIdentity 真正需要的 cookies，避免整域 cookies 落盘
 const WANT_COOKIES = new Set(['access_token', 'buc_username', 'buc_userinfo']);
@@ -9,19 +10,19 @@ const EMP_ID_NAMES = new Set(['emp_id', 'empId', 'employeeId']);
  * 环境下无法启动（连 --version 都 require 失败），故改为运行时动态 import + try/catch
  * 降级：只在真正执行 `auth login` 时才需要 playwright，未安装则给出清晰提示。
  */
-async function loadChromium() {
+async function loadFirefox() {
     try {
         const pw = await import('playwright');
-        return pw.chromium;
+        return pw.firefox;
     }
     catch {
-        throw new Error("未安装 playwright。运行时需要：设 ATLAS_AUTO_BOOTSTRAP=1 自动安装，或执行 `npm install playwright && npx playwright install chromium`");
+        throw new Error("未安装 playwright。运行时需要：设 ATLAS_AUTO_BOOTSTRAP=1 自动安装，或执行 `npm install playwright && npx playwright install`");
     }
 }
 export async function login(_port) {
     log('正在打开浏览器进行 Banma SSO 登录...');
-    const chromium = await loadChromium();
-    const browser = await chromium.launch({
+    const firefox = await loadFirefox();
+    const browser = await firefox.launch({
         headless: false,
     });
     const page = await browser.newPage();
@@ -85,6 +86,9 @@ export async function loginCmd(opts) {
         }
         return;
     }
+    if (!process.stdout.isTTY) {
+        throw new AtlasError('atlas auth login 需要在终端中交互完成 SSO，当前为非终端环境。请手动在终端执行 `atlas auth login` 后重试', 'INTERACTIVE_REQUIRED');
+    }
     await login();
     if (opts.json || isJsonMode()) {
         jsonOk({ status: 'logged_in' });

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

@@ -113,42 +113,3 @@ export async function readBanmaIdentity() {
     const cookies = await readCookies();
     return getBanmaIdentity(cookies);
 }
-/** Keytar session — legacy, keep for backward compat */
-export async function readSession() {
-    try {
-        const keytar = await import('keytar');
-        const stored = await keytar.default.getPassword('atlas-cli', 'session');
-        if (stored)
-            return JSON.parse(stored);
-    }
-    catch {
-        // keytar not available
-    }
-    return null;
-}
-export async function writeSession(session) {
-    try {
-        const keytar = await import('keytar');
-        await keytar.default.setPassword('atlas-cli', 'session', JSON.stringify(session));
-        return;
-    }
-    catch {
-        // keytar not available
-    }
-}
-export async function clearSession() {
-    cachedCookies = null;
-    try {
-        const keytar = await import('keytar');
-        await keytar.default.deletePassword('atlas-cli', 'session');
-    }
-    catch {
-        // ignore
-    }
-    try {
-        await unlink(COOKIE_FILE);
-    }
-    catch {
-        // ignore
-    }
-}

package/dist/adapters/atlas/cli.js

@@ -12,11 +12,11 @@ import { showCmd as actualShowCmd, monthCmd as actualMonthCmd, summaryCmd as act
 import { compareCmd } from './commands/compare/index.js';
 // Utility commands
 import { daemonCmd } from './daemon/index.js';
-import { schemaCommandsCmd, schemaExportCmd } from './commands/schema.js';
+import { schemaCommandsCmd } from './commands/schema.js';
 import { execCmd } from './commands/exec.js';
 import { suggestCmd } from './commands/suggest.js';
 import { updateCmd } from './commands/update.js';
-import { BanmaApiError, ConfigError, NotImplementedError, SessionExpiredError, isAtlasError, } from './util/errors.js';
+import { BanmaApiError, ConfigError, NotImplementedError, OutputTooLargeError, SessionExpiredError, isAtlasError, } from './util/errors.js';
 import { isJsonMode, printError } from './util/output.js';
 import { getOutputSchema } from './commands/_output_schema.js';
 export function handleError(err) {
@@ -40,6 +40,11 @@ export function handleError(err) {
         console.error(err.message);
         process.exit(64);
     }
+    if (err instanceof OutputTooLargeError) {
+        const debug = process.env.DEBUG === '1';
+        console.error(debug ? err.stack ?? err.message : err.message);
+        process.exit(65);
+    }
     const debug = process.env.DEBUG === '1';
     console.error(err instanceof Error ? (debug ? err.stack ?? err.message : err.message) : String(err));
     process.exit(1);
@@ -49,6 +54,8 @@ export function exitCodeFor(err) {
         return 2;
     if (err instanceof BanmaApiError)
         return 3;
+    if (err instanceof OutputTooLargeError)
+        return 65;
     if (err instanceof NotImplementedError)
         return 64;
     if (isAtlasError(err)) {
@@ -59,6 +66,7 @@ export function exitCodeFor(err) {
             case 'NETWORK_ERROR': return 7;
             case 'UPDATE_ERROR': return 8;
             case 'CONFIG_ERROR': return 64;
+            case 'INTERACTIVE_REQUIRED': return 64;
             default: return 1;
         }
     }
@@ -382,20 +390,6 @@ function registerUtilityCommands(program) {
     });
     // schema
     const schema = program.command('schema').description('CLI 自省 / 字段字典导出');
-    schema
-        .command('export')
-        .description('导出字典 + 部门树，供 skill 缓存对照')
-        .option('--out <path>', '同时写入文件路径')
-        .option('--refresh', '刷新缓存')
-        .option('--json', '输出 JSON 信封')
-        .action(async (opts) => {
-        try {
-            await schemaExportCmd(opts);
-        }
-        catch (e) {
-            handleError(e);
-        }
-    });
     schema
         .command('commands')
         .description('列出所有命令的参数 schema 及输出 schema 标注')
@@ -474,7 +468,8 @@ export function buildProgram() {
    6  API 限流（RateLimited）
    7  网络错误（NetworkError）
    8  版本更新异常（UpdateError）
-  64  配置错误 / 未实现（ConfigError）
+  64  配置错误 / 未实现（ConfigError / NotImplementedError）
+  65  输出超限（OutputTooLargeError）
 `)
         .showHelpAfterError()
         .hook('preAction', (thisCommand, actionCommand) => {

package/dist/adapters/atlas/commands/_output_schema.js

@@ -8,6 +8,7 @@ const schemas = {
                     type: 'object',
                     properties: {
                         status: { type: 'string', enum: ['logged_in'] },
+                        via: { type: 'string', enum: ['daemon'] },
                     },
                 },
             },
@@ -37,6 +38,26 @@ const schemas = {
             },
         },
     },
+    'atlas find': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'array',
+                    items: { type: 'object' },
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        count: { type: 'number' },
+                        kind: { type: 'string' },
+                        query: { type: 'string' },
+                    },
+                },
+            },
+        },
+    },
     'atlas link': {
         jsonSchema: {
             type: 'object',
@@ -48,6 +69,24 @@ const schemas = {
                         projectId: { type: 'string' },
                         projectName: { type: 'string' },
                         linkedAt: { type: 'string' },
+                        linked: { type: 'object', description: '已绑定的项目信息（link 无参时）' },
+                        envProjectId: { type: 'string', description: 'BANMA_PROJECT_ID 环境变量值' },
+                        dryRun: { type: 'boolean' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas unlink': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        unlinked: { type: 'boolean' },
+                        projectName: { type: 'string' },
                     },
                 },
             },
@@ -61,8 +100,16 @@ const schemas = {
                 data: {
                     type: 'object',
                     properties: {
-                        months: { type: 'array', items: { type: 'string' } },
-                        totalManpower: { type: 'number' },
+                        projectId: { type: 'string' },
+                        months: { type: 'array', items: { type: 'string' }, description: 'YYYY-MM 格式月份列表' },
+                        entries: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                description: '单个月份的基线条目',
+                            },
+                        },
+                        totalManpower: { type: 'number', description: '单位：人月' },
                     },
                 },
             },
@@ -78,14 +125,231 @@ const schemas = {
                     items: {
                         type: 'object',
                         properties: {
-                            month: { type: 'string' },
-                            manpower: { type: 'number' },
+                            month: { type: 'string', description: 'YYYY-MM' },
+                            manpower: { type: 'number', description: '单位：人月' },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    'atlas baseline export': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        exported: { type: 'number', description: '导出行数' },
+                        format: { type: 'string', enum: ['csv', 'json'] },
+                        out: { type: 'string', description: '导出文件绝对路径（经过白名单校验）' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas actual show': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        staffId: { type: 'string' },
+                        month: { type: 'string', description: 'YYYY-MM' },
+                        personnel: { type: 'array', items: { type: 'object' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas actual month': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        projectId: { type: 'string' },
+                        entries: { type: 'array', items: { type: 'object' } },
+                    },
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        failedMonths: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas actual summary': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        rows: { type: 'array', items: { type: 'object' } },
+                    },
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        failedMonths: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas actual export': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        exported: { type: 'number', description: '导出行数' },
+                        format: { type: 'string', enum: ['csv', 'json'] },
+                        out: { type: 'string', description: '导出文件绝对路径' },
+                    },
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        failedMonths: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas compare': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        rows: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    month: { type: 'string', description: 'YYYY-MM' },
+                                    plan: { type: 'number', description: '基线人月' },
+                                    actual: { type: 'number', description: '实际人月' },
+                                    diff: { type: 'number', description: '实际 - 基线（人月）' },
+                                },
+                            },
+                        },
+                    },
+                },
+                meta: {
+                    type: 'object',
+                    properties: {
+                        failedMonths: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas schema commands': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        commands: { type: 'array', items: { type: 'string' } },
+                    },
+                },
+            },
+        },
+    },
+    'atlas exec': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        results: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    step: { type: 'number' },
+                                    command: { type: 'string' },
+                                    status: { type: 'string', description: 'success | failed: <msg>' },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+    'atlas suggest': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        query: { type: 'string' },
+                        suggestions: {
+                            type: 'array',
+                            maxItems: 5,
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    command: { type: 'string', description: 'atlas 子命令片段' },
+                                    description: { type: 'string' },
+                                    score: { type: 'number' },
+                                },
+                            },
                         },
                     },
                 },
             },
         },
     },
+    'atlas update': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        mode: { type: 'string', enum: ['npm', 'other'] },
+                        disabled: { type: 'boolean' },
+                        current: { type: 'string', description: '当前版本号' },
+                        updateCommand: { type: 'string', description: 'npm 更新命令' },
+                        migrationCommand: { type: 'string', description: '迁移到 npm 安装的命令' },
+                    },
+                },
+            },
+        },
+    },
+    'atlas daemon': {
+        jsonSchema: {
+            type: 'object',
+            properties: {
+                ok: { type: 'boolean' },
+                data: { type: 'object' },
+            },
+        },
+    },
 };
 export function getOutputSchema(commandPath) {
     return schemas[commandPath] ?? {

package/dist/adapters/atlas/commands/exec.js

@@ -1,4 +1,5 @@
 import { readFile } from 'fs/promises';
+import { spawn } from 'child_process';
 import { z } from 'zod';
 import { isJsonMode, jsonOk, log } from '../util/output.js';
 import { ConfigError } from '../util/errors.js';
@@ -9,6 +10,32 @@ const ExecStepSchema = z.object({
 const ExecPlanSchema = z.object({
     steps: z.array(ExecStepSchema).max(100, '步骤数不能超过 100'),
 });
+/**
+ * 用 spawn 执行一条 atlas 子命令，返回 Promise。
+ * 使用 process.execPath + process.argv[1] 确保无论 npx / global / direct 都能正确找到入口。
+ */
+function runStep(command, extraArgs = []) {
+    const parts = command.split(/\s+/);
+    // parts[0] === 'atlas', 去掉后剩下的才是子命令参数
+    const args = [process.argv[1], ...parts.slice(1), ...extraArgs];
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, args, {
+            stdio: 'inherit',
+            env: { ...process.env },
+        });
+        child.on('close', (code) => {
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`进程退出码 ${code}`));
+            }
+        });
+        child.on('error', (err) => {
+            reject(new Error(`无法启动进程: ${err.message}`));
+        });
+    });
+}
 export async function execCmd(opts) {
     let raw;
     try {
@@ -33,16 +60,12 @@ export async function execCmd(opts) {
         const step = plan.steps[i];
         log(`[${i + 1}/${plan.steps.length}] ${step.command}`);
         try {
-            // 执行时始终用 spawn('atlas', [...subcmd, ...args]) 数组形式，禁止字符串 shell
-            // 当前阶段只注册不执行，未来实装时遵循上述原则
-            results.push({ step: i + 1, command: step.command, status: 'registered' });
+            await runStep(step.command, step.args);
+            results.push({ step: i + 1, command: step.command, status: 'success' });
         }
         catch (e) {
-            results.push({
-                step: i + 1,
-                command: step.command,
-                status: `failed: ${e instanceof Error ? e.message : String(e)}`,
-            });
+            const msg = e instanceof Error ? e.message : String(e);
+            results.push({ step: i + 1, command: step.command, status: `failed: ${msg}` });
             if (opts.json || isJsonMode()) {
                 jsonOk({ results }, { completed: i, total: plan.steps.length });
             }

package/dist/adapters/atlas/commands/schema.js

@@ -1,10 +1,5 @@
 import { isJsonMode, jsonOk, log } from '../util/output.js';
-import { NotImplementedError } from '../util/errors.js';
 import { emitDescribe } from '../cli.js';
-export async function schemaExportCmd(_opts) {
-    // 后续待实装：调用 dictionary/selectAll 和 department/tree 接口拉取真实数据
-    throw new NotImplementedError('schema export 暂未完整实现。当前返回空字典，待后续拉取部门树 + 字典值后补全');
-}
 export function schemaCommandsCmd(program, opts) {
     const commands = [];
     program.commands.forEach((cmd) => {

package/dist/adapters/atlas/commands/suggest.js

@@ -1,20 +1,37 @@
 import { isJsonMode, jsonOk, log } from '../util/output.js';
 const RULES = [
-    { pattern: /登录|login|sso|auth/i, command: 'atlas auth login', description: 'SSO 登录', weight: 10 },
-    { pattern: /状态|status|会话/i, command: 'atlas auth status', description: '查看会话状态', weight: 10 },
-    { pattern: /项目.*列表|列出.*项目|projects/i, command: 'atlas projects', description: '列出所有项目', weight: 10 },
-    { pattern: /绑定|link/i, command: 'atlas link <project>', description: '绑定项目', weight: 10 },
-    { pattern: /解绑|unlink/i, command: 'atlas unlink', description: '解绑项目', weight: 10 },
-    { pattern: /搜索|找|find|查询项目/i, command: 'atlas find project <query>', description: '搜索项目', weight: 10 },
-    { pattern: /基线|计划|baseline/i, command: 'atlas baseline month', description: '查看基线人力', weight: 5 },
-    { pattern: /基线.*汇总/i, command: 'atlas baseline summary', description: '基线汇总', weight: 5 },
-    { pattern: /基线.*导出/i, command: 'atlas baseline export', description: '导出基线', weight: 5 },
-    { pattern: /实际|actual|工时/i, command: 'atlas actual month', description: '查看实际工时', weight: 5 },
-    { pattern: /实际.*汇总/i, command: 'atlas actual summary', description: '实际工时汇总', weight: 5 },
-    { pattern: /实际.*导出/i, command: 'atlas actual export', description: '导出实际工时', weight: 5 },
-    { pattern: /实际.*人员|人员.*明细/i, command: 'atlas actual show <staffId>', description: '查看人员实际工时', weight: 5 },
-    { pattern: /对比|比较|compare|差异/i, command: 'atlas compare', description: '基线 vs 实际对比', weight: 10 },
-    { pattern: /升级|更新|update/i, command: 'atlas update', description: '升级到最新版本', weight: 10 },
+    // ── 鉴权类 ─────────────────────────────
+    { pattern: /登录|login|sso|auth/i, command: 'atlas auth login', description: 'SSO 登录（需终端交互）', weight: 10, requiresAuth: false, exitCodes: [0, 1, 64] },
+    { pattern: /状态|status|会话/i, command: 'atlas auth status', description: '查看会话状态', weight: 10, requiresAuth: false, exitCodes: [0] },
+    // ── 项目类 ─────────────────────────────
+    { pattern: /项目.*列表|列出.*项目|projects/i, command: 'atlas projects', description: '列出所有项目', weight: 10, requiresAuth: true, exitCodes: [0, 2] },
+    { pattern: /绑定|link|关联/i, command: 'atlas link <project>', description: '绑定项目（可省后续 --project-id）', weight: 10, requiresAuth: true, exitCodes: [0, 4, 5] },
+    { pattern: /解绑|unlink/i, command: 'atlas unlink', description: '解绑项目', weight: 10, requiresAuth: true, exitCodes: [0] },
+    { pattern: /搜索|找|find|查询项目/i, command: 'atlas find project <query>', description: '搜索项目（也支持 department/mp-type/line-plan-type/area-code）', weight: 10, requiresAuth: true, exitCodes: [0, 2] },
+    { pattern: /部门|department/i, command: 'atlas find department <query>', description: '搜索部门', weight: 7, requiresAuth: true, exitCodes: [0, 2] },
+    { pattern: /字典|类型|mp.type|line.plan/i, command: 'atlas find mp-type <query>', description: '搜索 MP 类型字典值', weight: 7, requiresAuth: true, exitCodes: [0, 2] },
+    // ── 基线人力 ────────────────────────────
+    { pattern: /基线|计划|baseline|人月.*计划/i, command: 'atlas baseline month --month YYYY-MM', description: '查看指定月份基线人力', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3, 4, 5] },
+    { pattern: /基线.*汇总|baseline.*summar/i, command: 'atlas baseline summary [--by month|department|role]', description: '按月/部门/角色汇总基线人力', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3] },
+    { pattern: /基线.*导出|baseline.*export/i, command: 'atlas baseline export --from YYYY-MM --to YYYY-MM [--format csv|json] [--out <path>]', description: '导出基线条目', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3, 65] },
+    // ── 实际工时 ────────────────────────────
+    { pattern: /实际|actual|工时|人月.*实际/i, command: 'atlas actual month --month YYYY-MM', description: '查看指定月份实际工时（人月）', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3, 4, 5] },
+    { pattern: /实际.*汇总|actual.*summar/i, command: 'atlas actual summary [--by month|department|role]', description: '汇总实际工时', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3] },
+    { pattern: /实际.*导出|actual.*export/i, command: 'atlas actual export --from YYYY-MM --to YYYY-MM [--format csv|json] [--out <path>]', description: '导出实际工时', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3, 65] },
+    { pattern: /实际.*人员|人员.*明细|staff|成员.*工时/i, command: 'atlas actual show <staffId> --month YYYY-MM', description: '查看单人员工实际工时明细', weight: 5, requiresAuth: true, exitCodes: [0, 2, 3] },
+    // ── 对比 ───────────────────────────────
+    { pattern: /对比|比较|compare|差异|偏差/i, command: 'atlas compare --from YYYY-MM --to YYYY-MM', description: '基线 vs 实际对比（diff = 实际 - 基线，人月）', weight: 10, requiresAuth: true, exitCodes: [0, 2, 3, 4, 5] },
+    // ── 批量执行 ────────────────────────────
+    { pattern: /批量|batch|exec|编排/i, command: 'atlas exec --plan-file <path>', description: '按 plan-file 顺序执行多条 atlas 命令', weight: 7, requiresAuth: false, exitCodes: [0, 1] },
+    // ── 自省 / 帮助 ─────────────────────────
+    { pattern: /命令.*列表|命令树|帮助|自省|schema/i, command: 'atlas schema commands [--describe]', description: '列出所有命令 + 输出 schema（agent 自省入口）', weight: 8, requiresAuth: false, exitCodes: [0] },
+    { pattern: /升级|更新|update/i, command: 'atlas update', description: '升级到最新版本', weight: 10, requiresAuth: false, exitCodes: [0] },
+    { pattern: /守护|daemon/i, command: 'atlas daemon', description: '启动本地守护进程（保持浏览器会话）', weight: 5, requiresAuth: false, exitCodes: [0] },
+    // ── 模糊匹配：问"某项目" ────────────
+    { pattern: /项目\S+|(\S+项目)/i, command: 'atlas find project <query>', description: '搜索项目（含模糊匹配参数）', weight: 3, requiresAuth: true, exitCodes: [0, 2] },
+    // ── 月份推算 ────────────────────────────
+    { pattern: /上个月|本月|上月|这个月|当月|当前月/i, command: 'atlas baseline month --month $(date +%Y-%m)', description: '查看当前/上个月基线（月份参数可推算）', weight: 3, requiresAuth: true, exitCodes: [0, 2, 3] },
+    { pattern: /上季度|上个季度|本季度/i, command: 'atlas compare --from $(date -d "$(date +%Y-%m-01) -3 months" +%Y-%m) --to $(date +%Y-%m)', description: '按季度范围对比（月份参数自动推算）', weight: 3, requiresAuth: true, exitCodes: [0, 2, 3] },
 ];
 export function suggestCmd(query, opts) {
     const suggestions = [];
@@ -24,17 +41,24 @@ export function suggestCmd(query, opts) {
                 command: rule.command,
                 description: rule.description,
                 score: rule.weight,
+                requiresAuth: rule.requiresAuth,
+                exitCodes: rule.exitCodes,
             });
         }
     }
-    // Simple fuzzy score: more pattern matches = higher score
+    // 模糊分提升：查询词在命令中出现越多加分
     const queryLower = query.toLowerCase();
     for (const s of suggestions) {
         const cmdLower = s.command.toLowerCase();
         let score = 0;
         for (const word of queryLower.split(/\s+/)) {
-            if (cmdLower.includes(word))
+            if (word.length >= 2 && cmdLower.includes(word))
                 score += 0.5;
+            // 月份/具体数值命中额外加分
+            if (/^\d{4}[-\/]\d{2}$/.test(word))
+                score += 1;
+            if (/^\d+$/.test(word) && word.length >= 2 && cmdLower.includes(word))
+                score += 1;
         }
         s.score += score;
     }
@@ -51,6 +75,9 @@ export function suggestCmd(query, opts) {
     log(`自然语言查询: "${query}"`);
     log('建议命令:');
     for (const s of suggestions.slice(0, 5)) {
-        log(`  ${s.command}  — ${s.description}`);
+        const authMark = s.requiresAuth ? '🔑' : '  ';
+        log(`  ${authMark} ${s.command}  — ${s.description}`);
     }
+    log('');
+    log('标记 🔑=需要登录，无标记=无需鉴权');
 }

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

@@ -29,6 +29,16 @@ export class NotImplementedError extends Error {
         this.name = 'NotImplementedError';
     }
 }
+export class OutputTooLargeError extends Error {
+    bytes;
+    limit;
+    constructor(bytes, limit) {
+        super(`输出 ${bytes} 字节超过上限 ${limit} 字节`);
+        this.bytes = bytes;
+        this.limit = limit;
+        this.name = 'OutputTooLargeError';
+    }
+}
 export class AtlasError extends Error {
     code;
     constructor(message, code) {

package/dist/adapters/atlas/util/output-limit.js

@@ -1,10 +1,11 @@
-import { ConfigError } from './errors.js';
+import { OutputTooLargeError } from './errors.js';
 const MAX_OUTPUT_BYTES_ENV = 'ATLAS_MAX_OUTPUT_BYTES';
 /**
  * 在写出文件前校验输出字节数上限。
  *
  * 读取 ATLAS_MAX_OUTPUT_BYTES（字节数，需为正数）。未设置或非法值时放行；
- * 超限时抛 ConfigError（退出码 64），供 agent 场景防止生成超大 CSV/JSON 占满磁盘。
+ * 超限时抛 OutputTooLargeError（退出码 65，error.code: OUTPUT_TOO_LARGE），
+ * agent 可据此区分"输出过大"和"配置错误"。
  */
 export function enforceOutputLimit(content) {
     const raw = process.env[MAX_OUTPUT_BYTES_ENV];
@@ -15,6 +16,6 @@ export function enforceOutputLimit(content) {
         return;
     const bytes = Buffer.byteLength(content, 'utf-8');
     if (bytes > limit) {
-        throw new ConfigError(`输出 ${bytes} 字节超过 ATLAS_MAX_OUTPUT_BYTES 上限 ${limit} 字节`);
+        throw new OutputTooLargeError(bytes, limit);
     }
 }

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

@@ -1,4 +1,4 @@
-import { BanmaApiError, AtlasError, ConfigError, NotImplementedError, SessionExpiredError } from './errors.js';
+import { BanmaApiError, AtlasError, ConfigError, NotImplementedError, OutputTooLargeError, SessionExpiredError } from './errors.js';
 export function isJsonMode() {
     return process.env.ATLAS_OUTPUT === 'json';
 }
@@ -23,6 +23,9 @@ export function printError(err, opts) {
         else if (err instanceof AtlasError) {
             jsonError(err.code, err.message);
         }
+        else if (err instanceof OutputTooLargeError) {
+            jsonError('OUTPUT_TOO_LARGE', err.message);
+        }
         else if (err instanceof Error) {
             jsonError('ERROR', err.message);
         }
@@ -44,6 +47,9 @@ export function printError(err, opts) {
     else if (err instanceof NotImplementedError) {
         console.error(err.message);
     }
+    else if (err instanceof OutputTooLargeError) {
+        console.error(err.message);
+    }
     else if (err instanceof AtlasError) {
         console.error(`[${err.code}] ${err.message}`);
     }

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

@@ -1 +1 @@
-export const ATLAS_VERSION = '0.7.1';
+export const ATLAS_VERSION = '0.7.3';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreamor/atlas-cli",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Atlas CLI - 斑马云图人力基线管理工具",
   "type": "module",
   "bin": {
@@ -40,7 +40,6 @@
     "zod": "^3.23.8"
   },
   "optionalDependencies": {
-    "keytar": "^7.9.0",
     "playwright": "^1.49.0"
   },
   "devDependencies": {