@dreamor/atlas-cli 0.7.0

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

@@ -0,0 +1,117 @@
+import { createClient } from '../../http/client.js';
+import { isJsonMode, jsonOk, log } from '../../util/output.js';
+import { enforceOutputLimit } from '../../util/output-limit.js';
+import { ConfigError, SessionExpiredError } from '../../util/errors.js';
+import { expandMonths } from '../../util/months.js';
+import { resolveSecureExportPath, secureWriteFile } from '../../util/secure-fs.js';
+import { annotateWithMonth, aggregateByAxis, filterByStaff, } from './_logic.js';
+function getProjectId(opts) {
+    const pid = opts.projectId ?? process.env.BANMA_PROJECT_ID ?? '';
+    if (!pid)
+        throw new ConfigError('请指定 --project-id 或设置 BANMA_PROJECT_ID 环境变量');
+    return pid;
+}
+async function fetchActual(pid, month) {
+    const client = createClient();
+    return client.post('/yuntu-service/manpower/weekly/summaryByTeam.json', { projectId: pid, month });
+}
+export async function showCmd(staffId, opts) {
+    const pid = getProjectId(opts);
+    const m = opts.month ?? expandMonths()[0];
+    const data = await fetchActual(pid, m);
+    const filtered = filterByStaff(data, staffId);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ staffId, month: m, personnel: filtered });
+        return;
+    }
+    if (filtered.length === 0) {
+        log(`${staffId} 在 ${m} 无实际工时数据`);
+        return;
+    }
+    for (const p of filtered) {
+        log(`  ${p.staffName} (${p.staffId}): ${p.manpower.toFixed(2)} 人月`);
+    }
+}
+export async function monthCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = opts.month ? [opts.month] : expandMonths(opts.from, opts.to);
+    const all = [];
+    const failedMonths = [];
+    for (const m of months) {
+        try {
+            const data = await fetchActual(pid, m);
+            all.push(...annotateWithMonth(data, m));
+        }
+        catch (e) {
+            if (e instanceof SessionExpiredError)
+                throw e;
+            failedMonths.push({ month: m, error: e instanceof Error ? e.message : String(e) });
+            log(`月 ${m} 拉取失败: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    if (opts.json || isJsonMode()) {
+        jsonOk({ projectId: pid, entries: all }, { failedMonths });
+        return;
+    }
+    if (all.length === 0) {
+        log('无实际工时数据');
+        return;
+    }
+    for (const p of all) {
+        log(`  ${p.staffName}: ${p.manpower.toFixed(2)} (${p.role ?? ''})`);
+    }
+}
+export async function summaryCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = opts.month ? [opts.month] : expandMonths(opts.from, opts.to);
+    const all = [];
+    const failedMonths = [];
+    for (const m of months) {
+        try {
+            all.push(...annotateWithMonth(await fetchActual(pid, m), m));
+        }
+        catch (e) {
+            if (e instanceof SessionExpiredError)
+                throw e;
+            failedMonths.push({ month: m, error: e instanceof Error ? e.message : String(e) });
+            log(`月 ${m} 拉取失败: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    const axis = (opts.by ?? 'month');
+    const rows = aggregateByAxis(all, axis);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ rows }, { failedMonths });
+        return;
+    }
+    for (const r of rows) {
+        log(`  ${r[axis]}: ${r.manpower.toFixed(2)} 人月`);
+    }
+}
+export async function exportCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = expandMonths(opts.from, opts.to);
+    const rows = [];
+    const failedMonths = [];
+    for (const m of months) {
+        try {
+            const data = await fetchActual(pid, m);
+            rows.push(...annotateWithMonth(data, m));
+        }
+        catch (e) {
+            if (e instanceof SessionExpiredError)
+                throw e;
+            failedMonths.push({ month: m, error: e instanceof Error ? e.message : String(e) });
+            log(`月 ${m} 拉取失败: ${e instanceof Error ? e.message : e}`);
+        }
+    }
+    const content = opts.format === 'csv'
+        ? (await import('papaparse')).default.unparse(rows)
+        : JSON.stringify(rows, null, 2);
+    enforceOutputLimit(content);
+    const safePath = resolveSecureExportPath(opts.out);
+    await secureWriteFile(safePath, content);
+    log(`已导出 ${rows.length} 条记录`);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ exported: rows.length, format: opts.format, out: safePath }, { failedMonths });
+    }
+}

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

@@ -0,0 +1 @@
+export { loginCmd as authLoginCmd, statusCmd as authStatusCmd } from '../auth/index.js';

package/dist/adapters/atlas/commands/baseline/index.js

@@ -0,0 +1,122 @@
+import { createClient } from '../../http/client.js';
+import { isJsonMode, jsonOk, log } from '../../util/output.js';
+import { enforceOutputLimit } from '../../util/output-limit.js';
+import { ConfigError } from '../../util/errors.js';
+import { expandMonths } from '../../util/months.js';
+import { monthTsToKey } from '../../util/time.js';
+import { resolveSecureExportPath, secureWriteFile } from '../../util/secure-fs.js';
+function getProjectId(opts) {
+    const pid = opts.projectId ?? process.env.BANMA_PROJECT_ID ?? '';
+    if (!pid)
+        throw new ConfigError('请指定 --project-id 或设置 BANMA_PROJECT_ID 环境变量');
+    return pid;
+}
+/**
+ * 月基线 API 返回 data 为数组，每项含 linePlanMonthDetailList
+ */
+async function fetchBaselineMonth(pid, month) {
+    const client = createClient();
+    const body = { projectId: pid, month };
+    return client.post('/yuntu-service/line/plan/month/select.json', body);
+}
+/** 强化的类型守卫（C6）：检查 month 为有限 number，manpower 可选 */
+function isMonthKey(v) {
+    return typeof v === 'object' && v !== null
+        && typeof v.month === 'number'
+        && Number.isFinite(v.month);
+}
+export async function monthCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = opts.month ? [opts.month] : expandMonths(opts.from, opts.to);
+    const allDetails = [];
+    for (const m of months) {
+        const data = await fetchBaselineMonth(pid, m);
+        // data 是数组，每项含 linePlanMonthDetailList
+        for (const item of (data ?? [])) {
+            const details = (item.linePlanMonthDetailList ?? []);
+            for (const d of details) {
+                if (isMonthKey(d)) {
+                    allDetails.push({
+                        month: d.month ? monthTsToKey(d.month) : m,
+                        manpower: d.manpower ?? 0,
+                        role: item.role,
+                        departmentName: item.departmentName,
+                    });
+                }
+            }
+        }
+    }
+    // 聚合
+    const byMonth = new Map();
+    for (const d of allDetails) {
+        byMonth.set(d.month, (byMonth.get(d.month) ?? 0) + d.manpower);
+    }
+    const monthKeys = [...byMonth.keys()].sort();
+    const total = monthKeys.reduce((s, m) => s + (byMonth.get(m) ?? 0), 0);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ projectId: pid, months: monthKeys, entries: allDetails, totalManpower: Math.round(total * 100) / 100 });
+        return;
+    }
+    log(`项目 ${pid} 基线人力:`);
+    for (const m of monthKeys) {
+        log(`  ${m}: ${(byMonth.get(m) ?? 0).toFixed(2)} 人月`);
+    }
+    log(`  合计: ${total.toFixed(2)} 人月`);
+}
+export async function summaryCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = opts.month ? [opts.month] : expandMonths(opts.from, opts.to);
+    const allDetails = [];
+    for (const m of months) {
+        const data = await fetchBaselineMonth(pid, m);
+        for (const item of (data ?? [])) {
+            for (const d of (item.linePlanMonthDetailList ?? [])) {
+                if (isMonthKey(d)) {
+                    allDetails.push({ month: monthTsToKey(d.month), manpower: d.manpower ?? 0, role: item.role, departmentName: item.departmentName });
+                }
+            }
+        }
+    }
+    const axis = opts.by ?? 'month';
+    const groups = new Map();
+    for (const d of allDetails) {
+        const k = axis === 'month' ? d.month : axis === 'department' ? (d.departmentName ?? '其他') : (d.role ?? '其他');
+        groups.set(k, (groups.get(k) ?? 0) + d.manpower);
+    }
+    const rows = [...groups.entries()].map(([k, v]) => ({ [axis]: k, manpower: Math.round(v * 100) / 100 }));
+    if (opts.json || isJsonMode()) {
+        jsonOk({ rows });
+        return;
+    }
+    log(`汇总:`);
+    for (const r of rows) {
+        log(`  ${String(r[axis])}: ${r.manpower.toFixed(2)} 人月`);
+    }
+}
+export async function exportCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = expandMonths(opts.from, opts.to);
+    const rows = [];
+    for (const m of months) {
+        const data = await fetchBaselineMonth(pid, m);
+        for (const item of (data ?? [])) {
+            for (const d of (item.linePlanMonthDetailList ?? [])) {
+                if (isMonthKey(d)) {
+                    rows.push({ projectId: pid, month: monthTsToKey(d.month), role: item.role ?? '', manpower: d.manpower ?? 0 });
+                }
+            }
+        }
+    }
+    const content = opts.format === 'csv'
+        ? (await import('papaparse')).default.unparse(rows)
+        : JSON.stringify(rows, null, 2);
+    enforceOutputLimit(content);
+    const safePath = resolveSecureExportPath(opts.out);
+    await secureWriteFile(safePath, content);
+    log(`已导出 ${rows.length} 条记录`);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ exported: rows.length, format: opts.format, out: safePath });
+    }
+}
+// 注：baseline fill / import（服务端写操作）已移除，CLI 聚焦查询与导出。
+// 未来按需恢复时，同步接通 ATLAS_SANDBOX dry-run 护卫与导出/导入字节护栏。

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

@@ -0,0 +1,39 @@
+/**
+ * compare 命令的纯逻辑层。
+ *
+ * 与命令解析层（index.ts）分离：这里不做 IO、不调 API、不输出，
+ * 只做数据变换（聚合、阈值过滤）。
+ */
+/**
+ * 按轴分组聚合 manpower。
+ * - month → 直接使用 month 字段
+ * - department → departmentName ?? '其他'
+ * - role → role ?? '其他'
+ */
+export function groupByAxis(entries, axis) {
+    const map = new Map();
+    for (const e of entries) {
+        const k = axis === 'department' ? (e.departmentName ?? '其他')
+            : axis === 'role' ? (e.role ?? '其他')
+                : e.month;
+        map.set(k, (map.get(k) ?? 0) + e.manpower);
+    }
+    return map;
+}
+/**
+ * 合并基线 map + 实际 map → CompareRow 数组。
+ * 所有 axis key 去重排序，每个 key 生成一条 { [axis], baselineManpower, actualManpower, diff }。
+ */
+export function mergeBaselineActual(blMap, acMap, axis, threshold) {
+    const keys = [...new Set([...blMap.keys(), ...acMap.keys()])].sort();
+    let rows = keys.map((k) => ({
+        [axis]: k,
+        baselineManpower: Math.round((blMap.get(k) ?? 0) * 100) / 100,
+        actualManpower: Math.round((acMap.get(k) ?? 0) * 100) / 100,
+        diff: Math.round(((acMap.get(k) ?? 0) - (blMap.get(k) ?? 0)) * 100) / 100,
+    }));
+    if (threshold > 0) {
+        rows = rows.filter((r) => Math.abs(r.diff) >= threshold);
+    }
+    return rows;
+}

package/dist/adapters/atlas/commands/compare/index.js

@@ -0,0 +1,72 @@
+import { createClient } from '../../http/client.js';
+import { isJsonMode, jsonOk, log } from '../../util/output.js';
+import { ConfigError, SessionExpiredError } from '../../util/errors.js';
+import { expandMonths } from '../../util/months.js';
+import { monthTsToKey } from '../../util/time.js';
+import { groupByAxis, mergeBaselineActual, } from './_logic.js';
+function getProjectId(opts) {
+    const pid = opts.projectId ?? process.env.BANMA_PROJECT_ID ?? '';
+    if (!pid)
+        throw new ConfigError('请指定 --project-id 或设置 BANMA_PROJECT_ID 环境变量');
+    return pid;
+}
+export async function compareCmd(opts) {
+    const pid = getProjectId(opts);
+    const months = opts.month ? [opts.month] : expandMonths(opts.from, opts.to);
+    const allBl = [];
+    const allAc = [];
+    const client = createClient();
+    const failedMonths = [];
+    for (const m of months) {
+        try {
+            const blData = await client.post('/yuntu-service/line/plan/month/select.json', { projectId: pid, month: m });
+            for (const item of (blData ?? [])) {
+                const details = (item.linePlanMonthDetailList ?? []);
+                for (const d of details) {
+                    if (d && typeof d === 'object') {
+                        const monthVal = d.month;
+                        const monthKey = typeof monthVal === 'number'
+                            ? monthTsToKey(monthVal)
+                            : m;
+                        allBl.push({ month: monthKey, manpower: Number(d.manpower ?? 0), role: item.role, departmentName: item.departmentName });
+                    }
+                }
+            }
+        }
+        catch (e) {
+            if (e instanceof SessionExpiredError)
+                throw e;
+            failedMonths.push({ month: m, error: `基线拉取失败: ${e instanceof Error ? e.message : String(e)}` });
+        }
+        // 指数退避：避免连续触发限流（B2）
+        try {
+            const acData = await client.post('/yuntu-service/manpower/weekly/summaryByTeam.json', { projectId: pid, month: m });
+            for (const p of acData ?? []) {
+                allAc.push({ month: m, manpower: p.manpower ?? 0, role: p.role, departmentName: p.departmentName });
+            }
+        }
+        catch (e) {
+            if (e instanceof SessionExpiredError)
+                throw e;
+            failedMonths.push({ month: m, error: `实际工时拉取失败: ${e instanceof Error ? e.message : String(e)}` });
+        }
+    }
+    const axis = (opts.by ?? 'month');
+    const blMap = groupByAxis(allBl, axis);
+    const acMap = groupByAxis(allAc, axis);
+    // C4: 阈值参数校验
+    const threshold = Number(opts.threshold ?? '0');
+    if (!Number.isFinite(threshold) || threshold < 0)
+        throw new ConfigError(`--threshold 必须为非负数，实际: "${opts.threshold}"`);
+    const rows = mergeBaselineActual(blMap, acMap, axis, threshold);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ rows }, { failedMonths });
+        return;
+    }
+    log(`项目 ${pid} 对比:${axis === 'month' ? '按月份' : axis === 'department' ? '按部门' : '按角色'}`);
+    for (const r of rows) {
+        const flag = opts.flagOverrun && r.actualManpower > r.baselineManpower ? ' ⚠️' : '';
+        log(`  ${String(r[axis])}: 基线 ${r.baselineManpower} / 实际 ${r.actualManpower} / 差异 ${r.diff > 0 ? '+' : ''}${r.diff}${flag}`);
+    }
+}
+// monthTsToKey 已从 util/time.ts 导入

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

@@ -0,0 +1,58 @@
+import { readFile } from 'fs/promises';
+import { z } from 'zod';
+import { isJsonMode, jsonOk, log } from '../util/output.js';
+import { ConfigError } from '../util/errors.js';
+const ExecStepSchema = z.object({
+    command: z.string().regex(/^atlas( [a-z\-]+)+$/, 'command 必须是 atlas 子命令，如 "atlas auth login"'),
+    args: z.array(z.string()).optional(),
+});
+const ExecPlanSchema = z.object({
+    steps: z.array(ExecStepSchema).max(100, '步骤数不能超过 100'),
+});
+export async function execCmd(opts) {
+    let raw;
+    try {
+        raw = await readFile(opts.planFile, 'utf-8');
+    }
+    catch (e) {
+        throw new ConfigError(`无法读取计划文件: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    let plan;
+    try {
+        plan = ExecPlanSchema.parse(JSON.parse(raw));
+    }
+    catch (e) {
+        if (e instanceof z.ZodError) {
+            throw new ConfigError(`计划文件校验失败: ${e.errors.map(ee => `${ee.path.join('.')}: ${ee.message}`).join('; ')}`);
+        }
+        throw new ConfigError(`计划文件格式错误: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    log(`执行计划: ${plan.steps.length} 个步骤`);
+    const results = [];
+    for (let i = 0; i < plan.steps.length; i++) {
+        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' });
+        }
+        catch (e) {
+            results.push({
+                step: i + 1,
+                command: step.command,
+                status: `failed: ${e instanceof Error ? e.message : String(e)}`,
+            });
+            if (opts.json || isJsonMode()) {
+                jsonOk({ results }, { completed: i, total: plan.steps.length });
+            }
+            process.exit(1);
+        }
+    }
+    if (opts.json || isJsonMode()) {
+        jsonOk({ results });
+    }
+    else {
+        log('计划执行完毕');
+    }
+}

package/dist/adapters/atlas/commands/project/index.js

@@ -0,0 +1,179 @@
+import { createClient } from '../../http/client.js';
+import { isJsonMode, jsonOk, log, table } from '../../util/output.js';
+import { getBanmaProjectId } from '../../util/env.js';
+import { AtlasError, ConfigError } from '../../util/errors.js';
+import { readFile, unlink } from 'fs/promises';
+import { existsSync } from 'fs';
+import { getLinkFile, getCacheFile, getCacheDir, getAtlasHome } from '../../util/paths.js';
+import { secureMkdir, secureWriteFile } from '../../util/secure-fs.js';
+const LINK_FILE = getLinkFile();
+const PROJECT_CACHE_FILE = getCacheFile('projects');
+async function readLink() {
+    try {
+        if (!existsSync(LINK_FILE))
+            return null;
+        return JSON.parse(await readFile(LINK_FILE, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+async function writeLink(link) {
+    await secureMkdir(getAtlasHome(), { recursive: true });
+    await secureWriteFile(LINK_FILE, JSON.stringify(link, null, 2));
+}
+async function removeLink() {
+    try {
+        await unlink(LINK_FILE);
+    }
+    catch { }
+}
+function getProjectName(p) {
+    return p.name ?? p.projectName ?? String(p.id);
+}
+/** 统一把 id 转成 string，API 可能返回数字 */
+function getProjectId(p) {
+    return String(p.id);
+}
+async function fetchProjectsFromApi(refresh) {
+    if (!refresh) {
+        try {
+            if (existsSync(PROJECT_CACHE_FILE)) {
+                return JSON.parse(await readFile(PROJECT_CACHE_FILE, 'utf-8'));
+            }
+        }
+        catch { }
+    }
+    const client = createClient();
+    // API 直接返回数组: [{id, name}, ...]
+    const data = await client.post('/yuntu-service/project/selectHasPermisValidProject.json', {});
+    const projects = (data ?? []);
+    await secureMkdir(getCacheDir(), { recursive: true });
+    await secureWriteFile(PROJECT_CACHE_FILE, JSON.stringify(projects, null, 2));
+    return projects;
+}
+function resolveProjectId(projects, query) {
+    const exact = projects.find((p) => getProjectId(p) === query || getProjectName(p) === query);
+    if (exact)
+        return { id: getProjectId(exact), name: getProjectName(exact) };
+    const sub = projects.filter((p) => getProjectId(p).includes(query) || getProjectName(p).includes(query));
+    if (sub.length === 1)
+        return { id: getProjectId(sub[0]), name: getProjectName(sub[0]) };
+    if (sub.length > 1)
+        throw new AtlasError(`项目匹配歧义: "${query}" 匹配了 ${sub.length} 个项目`, 'AMBIGUOUS_PROJECT');
+    return null;
+}
+export async function findCmd(kind, query, opts) {
+    const client = createClient();
+    let results = [];
+    if (kind === 'project') {
+        const projects = (await fetchProjectsFromApi(opts.refresh)) ?? [];
+        results = projects
+            .filter((p) => getProjectId(p).includes(query) || getProjectName(p).includes(query))
+            .map((p) => ({ id: getProjectId(p), name: getProjectName(p), kind: 'project' }));
+    }
+    else if (kind === 'department') {
+        const data = await client.post('/yuntu-service/department/tree/select.json', {});
+        // 需要确认实际响应格式
+        const nodes = Array.isArray(data) ? data : [];
+        const flatten = (items) => {
+            const r = [];
+            for (const n of items) {
+                if (n.name.includes(query))
+                    r.push({ id: n.id, name: n.name, kind: 'department' });
+                if (n.children)
+                    r.push(...flatten(n.children));
+            }
+            return r;
+        };
+        results = flatten(nodes);
+    }
+    else {
+        const dictData = await client.post('/yuntu-service/dictionary/select.json', { dictType: kind });
+        const entries = Array.isArray(dictData) ? dictData : [];
+        results = entries
+            .filter((e) => (e.attrName ?? '').includes(query))
+            .map((e) => ({ id: e.attrValue ?? '', name: e.attrName ?? '', kind }));
+    }
+    const limit = parseInt(opts.limit ?? '20', 10);
+    if (!Number.isFinite(limit) || limit <= 0)
+        throw new ConfigError(`--limit 必须为正整数，实际: "${opts.limit}"`);
+    results = results.slice(0, limit);
+    if (opts.json || isJsonMode()) {
+        jsonOk(results, { count: results.length, kind, query });
+        return;
+    }
+    log(`找到 ${results.length} 个${kind}:`);
+    table(results);
+}
+export async function projectsCmd(opts) {
+    const rootData = (await fetchProjectsFromApi(opts.refresh)) ?? [];
+    const projects = rootData;
+    const formatted = projects.map((p) => ({ id: getProjectId(p), name: getProjectName(p) }));
+    if (opts.json || isJsonMode()) {
+        jsonOk(formatted);
+        return;
+    }
+    log(`你有 ${formatted.length} 个项目的权限:`);
+    table(formatted);
+}
+export async function linkCmd(project, opts) {
+    const projects = await fetchProjectsFromApi(opts.refreshProjects);
+    const resolved = resolveProjectId(projects, project);
+    if (!resolved)
+        throw new AtlasError(`未找到项目: "${project}"`, 'PROJECT_NOT_FOUND');
+    const link = { projectId: resolved.id, projectName: resolved.name, linkedAt: new Date().toISOString() };
+    if (opts.dryRun) {
+        log(`[dry-run] 将会绑定项目: ${resolved.name} (${resolved.id})`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({ dryRun: true, link });
+            return;
+        }
+        return;
+    }
+    await writeLink(link);
+    log(`已绑定项目: ${resolved.name} (${resolved.id})`);
+    if (opts.json || isJsonMode()) {
+        jsonOk(link);
+    }
+}
+export async function linkStatusCmd(opts) {
+    const link = await readLink();
+    const envProjectId = getBanmaProjectId();
+    if (opts.json || isJsonMode()) {
+        jsonOk({ linked: link ?? null, envProjectId: envProjectId ?? null });
+        return;
+    }
+    if (link) {
+        log(`当前绑定项目: ${link.projectName} (${link.projectId})\n绑定时间: ${link.linkedAt}`);
+    }
+    else {
+        log('未绑定项目。使用 atlas link <project> 绑定');
+    }
+    if (envProjectId)
+        log(`环境变量 BANMA_PROJECT_ID=${envProjectId}`);
+}
+export async function unlinkCmd(opts) {
+    const link = await readLink();
+    if (!link) {
+        log('当前未绑定项目');
+        if (opts.json || isJsonMode()) {
+            jsonOk({ unlinked: false });
+            return;
+        }
+        return;
+    }
+    if (opts.dryRun) {
+        log(`[dry-run] 将会清除项目绑定: ${link.projectName}`);
+        if (opts.json || isJsonMode()) {
+            jsonOk({ dryRun: true, link });
+            return;
+        }
+        return;
+    }
+    await removeLink();
+    log(`已清除项目绑定: ${link.projectName}`);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ unlinked: true, projectName: link.projectName });
+    }
+}

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

@@ -0,0 +1,30 @@
+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) => {
+        commands.push(cmd.name());
+        if (cmd.commands.length > 0) {
+            cmd.commands.forEach((sub) => {
+                commands.push(`${cmd.name()} ${sub.name()}`);
+            });
+        }
+    });
+    if (opts.describe) {
+        program.commands.forEach((cmd) => {
+            emitDescribe(cmd);
+        });
+        return;
+    }
+    if (opts.json || isJsonMode()) {
+        jsonOk({ commands });
+        return;
+    }
+    log('可用命令:');
+    commands.sort().forEach((c) => log(`  ${c}`));
+}

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

@@ -0,0 +1,56 @@
+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 },
+];
+export function suggestCmd(query, opts) {
+    const suggestions = [];
+    for (const rule of RULES) {
+        if (rule.pattern.test(query)) {
+            suggestions.push({
+                command: rule.command,
+                description: rule.description,
+                score: rule.weight,
+            });
+        }
+    }
+    // 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))
+                score += 0.5;
+        }
+        s.score += score;
+    }
+    suggestions.sort((a, b) => b.score - a.score);
+    if (opts.json || isJsonMode()) {
+        jsonOk({ query, suggestions: suggestions.slice(0, 5) });
+        return;
+    }
+    if (suggestions.length === 0) {
+        log(`未找到匹配的 atlas 命令: "${query}"`);
+        log('提示: 试试 atlas --help 查看所有命令');
+        return;
+    }
+    log(`自然语言查询: "${query}"`);
+    log('建议命令:');
+    for (const s of suggestions.slice(0, 5)) {
+        log(`  ${s.command}  — ${s.description}`);
+    }
+}