@ohos-cpf/3rdloop 0.0.1 → 0.0.2

package/lib/cli.js

@@ -69,7 +69,7 @@ export async function runCli(argv) {
     _redirectStdoutLogs();
 
     const projectName = getProjectName(projectRoot, flags.projectName);
-    const dataDir = resolveDataDir({ dataDirFlag: flags.dataDir, projectName, user3libHome, projectRoot });
+    const dataDir = resolveDataDir({ dataDirFlag: flags.dataDir, user3libHome });
     const skillDir = resolveSkillDir({ skillDirFlag: flags.skillDir, projectRoot });
 
     // 统计服务写用户数据目录（而非 vendor/Server 相对路径的 cli/db）
@@ -141,6 +141,12 @@ export async function runCli(argv) {
         case 'orch':
             return cmdOrch({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u });
 
+        case 'config':
+            return cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out });
+
+        case 'update':
+            return cmdUpdate({ flags, rest, jsonMode, out });
+
         default:
             process.stderr.write(`未知命令: ${cmd}\n`);
             printHelp();
@@ -193,6 +199,25 @@ async function cmdWorkflows({ jsonMode, out }) {
     return EXIT.OK;
 }
 
+// ─── config（配置 .env 配置项）────────────────────────────────────
+
+async function cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out }) {
+    const { cmdConfigImpl } = await import('./config-cmd.js');
+    return cmdConfigImpl({ projectRoot, user3libHome, jsonMode, out, rest });
+}
+
+// ─── update（自更新）─────────────────────────────────────────────
+
+async function cmdUpdate({ flags, rest, jsonMode, out }) {
+    const { cmdUpdateImpl } = await import('./update.js');
+    const result = await cmdUpdateImpl({ jsonMode, rest });
+    if (jsonMode) {
+        // cmdUpdateImpl 内部已输出 --json 结构化结果到 stdout
+        return result.ok ? EXIT.OK : EXIT.ERROR;
+    }
+    return result.ok ? EXIT.OK : EXIT.ERROR;
+}
+
 // ─── run / submit ──────────────────────────────────────────────────
 
 async function cmdRun({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u }) {
@@ -612,6 +637,8 @@ function printHelp() {
   3rdloop orch tasks                          列出编排任务
   3rdloop workflows                     列出已注册的固定编排工作流
   3rdloop run <工作流名> [--flag <值> ...]     以固定编排执行工作流（阻塞到终态）
+  3rdloop config list|get|set|unset ...  配置 .env 配置项（默认读写 ~/.3lib/.env）
+  3rdloop update [--check] [--yes] [--force] [--registry <url>]  自更新到 npm 最新版
   3rdloop doctor                        环境自检
   3rdloop version                       版本信息
 
@@ -625,11 +652,25 @@ function printHelp() {
 工作流专用选项:
   --print-taskdef  仅构造并打印/落盘 taskDef（dry-run，不触碰引擎），适合调试新工作流
 
+config 子命令:
+  3rdloop config list                 列出全部配置项及当前生效值
+  3rdloop config get <KEY>            查看某项当前生效值
+  3rdloop config set <KEY> <VALUE>    设置某项（文件: ~/.3lib/.env，密钥不回显）
+  3rdloop config unset <KEY>          删除用户级 .env 中的某项（恢复默认）
+  优先级: 系统环境变量 > ~/.3lib/.env > 默认值
+
+update 专用选项:
+  --check          仅检查是否有新版本，不执行更新
+  --yes, -y        跳过交互确认直接更新
+  --force          开发态（npm link）也强制替换为 registry 正式包
+  --registry <url> 覆盖 npm registry（默认尊重用户 npm 镜像配置）
+  注意: 数据目录 ~/.3lib/3rdloop/db 与 SKILL 配置不受更新影响
+
 全局选项:
   --json          结构化输出到 stdout（进度/日志走 stderr）
   -v, --verbose   详细模式
   --quiet         仅输出最终结果
-  --data-dir <p>  数据目录覆盖（默认 <项目根同级>/db）
+  --data-dir <p>  数据目录覆盖（默认 ~/.3lib/3rdloop/db）
   --project <n>   项目名覆盖（默认 git 仓库根名）
   --skill-dir <p>  SKILL 目录覆盖
   -h, --help      帮助

package/lib/config-cmd.js

@@ -0,0 +1,452 @@
+/**
+ * config-cmd.js —— 3rdloop config 命令（配置 .env 配置项）
+ *
+ * 职责：
+ *   - 维护白名单目录 ENV_KEYS（key/label/description/default/validate/secret/envOnly）
+ *   - 读写用户级 ~/.3lib/.env（跨项目全局生效）
+ *   - set/get/unset/list 子命令（密钥类 get/list 脱敏显示）
+ *
+ * 生效路径（无需改动核心）：
+ *   loadEnvChain() 把 ~/.3lib/.env 加载进 process.env，
+ *   resolveDataDir() / resolveSkillDir() 等消费对应环境变量。
+ * 系统环境变量仍是最高优先级（与 dotenv 现状一致）。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const _require = createRequire(import.meta.url);
+
+// ─── 白名单目录（与 Server/.env.example 对齐）────────────────────────────
+
+/** 默认存储路径，集中定义便于文档/测试同步 */
+export const DEFAULT_DATA_DIR = path.join('~', '.3lib', '3rdloop', 'db');
+
+/**
+ * 校验器：返回 true 合法 / false 非法。
+ * 按 .env.example 中的类型约束实现。
+ */
+const validators = {
+    /** 布尔类：true/false */
+    bool: (v) => /^(true|false)$/i.test(String(v).trim()),
+    /** 非负整数（top_k / max_tokens 等） */
+    intPositive: (v) => /^\d+$/.test(String(v).trim()) && Number(v) > 0,
+    /** 0-1 小数（采样/权重） */
+    weight01: (v) => {
+        const n = Number(String(v).trim());
+        return Number.isFinite(n) && n >= 0 && n <= 1;
+    },
+    /** LLM 温度（0-1 或较大数） */
+    temperature: (v) => {
+        const n = Number(String(v).trim());
+        return Number.isFinite(n) && n >= 0;
+    },
+    /** URL（http/https）或空 */
+    urlOrEmpty: (v) => {
+        const s = String(v).trim();
+        return s === '' || /^https?:\/\//i.test(s);
+    },
+    /** 端口 1-65535 或空 */
+    portOrEmpty: (v) => {
+        const s = String(v).trim();
+        if (s === '') return true;
+        const n = Number(s);
+        return Number.isInteger(n) && n >= 1 && n <= 65535;
+    },
+    /** 非空字符串 */
+    nonEmpty: (v) => String(v).trim().length > 0,
+    /** opencode | deveco-code */
+    cliType: (v) => ['opencode', 'deveco-code'].includes(String(v).trim()),
+    /** 任意（不校验） */
+    any: () => true,
+};
+
+/**
+ * 白名单配置项。
+ * - source：配置来源说明（用于 list 展示）
+ * - envOnly：仅在系统环境变量中生效，禁止 set/unset（避免 .env 失效误导）
+ */
+export const ENV_KEYS = [
+    // ── LLM（百炼 / DashScope）───────────────────────────────────────
+    { key: 'DASHSCOPE_API_KEY', label: '百炼 API Key', description: '从 https://bailian.console.aliyun.com/ 获取', default: '', validate: validators.nonEmpty, secret: true },
+    { key: 'LLM_BASE_URL', label: 'LLM 端点', description: '百炼 OpenAI 兼容端点（不要随意修改）', default: 'https://dashscope.aliyuncs.com/compatible-mode/v1', validate: validators.urlOrEmpty },
+    { key: 'LLM_MODEL', label: '模型名', description: '经百炼调用的模型名（如 glm-5-1 / glm-5-2）', default: 'glm-5-1', validate: validators.nonEmpty },
+    { key: 'LLM_TEMPERATURE', label: 'LLM 采样温度', description: '采样温度（可选）', default: '0.1', validate: validators.temperature },
+    { key: 'LLM_MAX_TOKENS', label: 'LLM 最大输出 tokens', description: '单次生成上限（可选）', default: '2048', validate: validators.intPositive },
+    { key: 'LLM_ENABLE_THINKING', label: 'GLM 思考模式', description: 'true=开启思考（慢，质量高）false=关闭（快，推荐）', default: 'false', validate: validators.bool },
+    { key: 'FALLBACK_MODEL', label: '备用模型', description: '连续 3 次 529 过载时切换，留空则不切换', default: '', validate: validators.any },
+
+    // ── SkillSelector 召回/命中 ──────────────────────────────────────
+    { key: 'SELECTOR_TOP_K', label: '召回候选数', description: '模糊匹配召回的候选数量', default: '5', validate: validators.intPositive },
+    { key: 'SELECTOR_HIT_THRESHOLD', label: '命中阈值', description: 'LLM 打分阈值 0-100（top1>=阈值且分差>=10 才算命中）', default: '60', validate: validators.intPositive },
+    { key: 'SELECTOR_WEIGHT_ACTION', label: '动作通道权重', description: '多路召回动作通道权重（默认 0.4）', default: '0.4', validate: validators.weight01 },
+    { key: 'SELECTOR_WEIGHT_DOMAIN', label: '领域通道权重', description: '多路召回领域通道权重（默认 0.4）', default: '0.4', validate: validators.weight01 },
+    { key: 'SELECTOR_WEIGHT_RAW', label: '原文兜底权重', description: '多路召回原文兜底通道权重（默认 0.2）', default: '0.2', validate: validators.weight01 },
+
+    // ── 编排并发 ─────────────────────────────────────────────────────
+    { key: 'MAX_CONCURRENT_SESSIONS', label: 'AI Session 并发上限', description: '跨所有编排任务共享的全局并发信号量上限', default: '50', validate: validators.intPositive },
+
+    // ── CLI / AI 助手后端 ────────────────────────────────────────────
+    { key: 'CLI_TYPE', label: '默认 CLI 类型', description: 'opencode | deveco-code', default: 'opencode', validate: validators.cliType },
+    { key: 'OPENCODE_HOST', label: 'opencode 主机', description: '连接配置（可选）', default: 'localhost', validate: validators.nonEmpty },
+    { key: 'OPENCODE_PORT', label: 'opencode 端口', description: '连接配置（可选，默认 4096）', default: '4096', validate: validators.portOrEmpty },
+    { key: 'DEVECO_HOST', label: 'deveco 主机', description: '连接配置（可选）', default: 'localhost', validate: validators.nonEmpty },
+    { key: 'DEVECO_PORT', label: 'deveco 端口', description: '连接配置（可选，默认 4096）', default: '4096', validate: validators.portOrEmpty },
+    { key: 'GIT_TOKEN', label: 'GitCode Token', description: '访问私有仓库用（可留空）', default: '', validate: validators.any, secret: true },
+
+    // ── CLI 自身（3LIB_*）────────────────────────────────────────────
+    { key: '3LIB_DATA_DIR', label: '默认数据目录', description: '任务中间产物根目录（默认 ~/.3lib/3rdloop/db，命令配置后可全局生效）', default: userDataDirDefault(), validate: validators.nonEmpty },
+    { key: '3LIB_SKILL_DIR', label: 'SKILL 目录覆盖', description: '等效 --skill-dir', default: '', validate: validators.nonEmpty },
+    { key: '3LIB_TASK_PREFIX', label: 'taskId 前缀', description: '审计用（可选）', default: '', validate: validators.any },
+    { key: '3LIB_ROOT', label: '项目根覆盖', description: '仅系统环境变量生效（.env 不生效）', default: '', validate: validators.any, envOnly: true },
+    { key: '3LIB_HOME', label: '用户 3lib 主目录', description: '仅系统环境变量生效（.env 不生效），含日志 logs/', default: '', validate: validators.any, envOnly: true },
+];
+
+/** 3LIB_DATA_DIR 的内置默认值（resolveDataDir 的默认），写入前展开 ~ */
+function userDataDirDefault() {
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir() || '';
+    return path.join(home, '.3lib', '3rdloop', 'db');
+}
+
+/** 按 key 取白名单项 */
+export function getKeyMeta(key) {
+    return ENV_KEYS.find(k => k.key === key) || null;
+}
+
+/** 展开 ~ 前缀（Windows 下也兼容） */
+export function expandHome(p) {
+    if (typeof p !== 'string') return p;
+    if (p === '~') return process.env.HOME || process.env.USERPROFILE || os.homedir() || '';
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        const home = process.env.HOME || process.env.USERPROFILE || os.homedir() || '';
+        return path.join(home, p.slice(2).replace(/^[/\\]/, ''));
+    }
+    return p;
+}
+
+// ─── 读取用户级 .env ──────────────────────────────────────────────────
+
+/** 用户级 .env 绝对路径 */
+export function userEnvPath(user3libHome) {
+    return path.join(user3libHome, '.env');
+}
+
+/** 用 dotenv.parse 解析；文件不存在返回 {}；失败返回 {} 并置 error */
+export function readUserEnv(user3libHome) {
+    const p = userEnvPath(user3libHome);
+    if (!fs.existsSync(p)) return { values: {}, source: p, exists: false };
+    try {
+        const dotenv = _dotenv();
+        const values = dotenv.parse(fs.readFileSync(p, 'utf8'));
+        return { values, source: p, exists: true };
+    } catch {
+        return { values: {}, source: p, exists: true };
+    }
+}
+
+/**
+ * 读取项目级 .env（<projectRoot>/Server/.env 或 <projectRoot>/.env），
+ * 合并为 values（前者优先，与 loadEnvChain 顺序一致）。
+ */
+export function readProjectEnv(projectRoot) {
+    const dotenv = _dotenv();
+    const values = {};
+    const candidates = [
+        projectRoot ? path.join(projectRoot, 'Server', '.env') : '',
+        projectRoot ? path.join(projectRoot, '.env') : '',
+    ];
+    for (const p of candidates) {
+        if (!p) continue;
+        try {
+            if (fs.existsSync(p)) {
+                Object.assign(values, dotenv.parse(fs.readFileSync(p, 'utf8')));
+            }
+        } catch { /* 单个 .env 损坏不影响整体 */ }
+    }
+    return { values };
+}
+
+/** 同步加载 dotenv（避免 Promise 化），失败回退手写解析 */
+function _dotenv() {
+    try {
+        const dotenv = _require('dotenv');
+        if (dotenv && typeof dotenv.parse === 'function') return dotenv;
+    } catch { /* 回退手写解析 */ }
+    return {
+        parse: (s) => {
+            const r = {};
+            for (const line of String(s).split('\n')) {
+                const m = line.match(/^\s*([\w.]+)\s*=\s*(.*)$/);
+                if (m) r[m[1]] = m[2].trim().replace(/^["']|["']$/g, '');
+            }
+            return r;
+        },
+    };
+}
+
+/**
+ * 行级写入：保留注释/其他键，目标键存在则覆写值、不存在则在末尾追加。
+ * 返回 true 表示写入成功。
+ */
+export function applyEnvKey(user3libHome, key, value) {
+    const p = userEnvPath(user3libHome);
+    fs.mkdirSync(user3libHome, { recursive: true });
+    const lines = fs.existsSync(p) ? fs.readFileSync(p, 'utf8').split('\n') : [];
+    const outLines = [];
+    let found = false;
+    for (const line of lines) {
+        // 保留空白/纯注释/其他键；只对 "KEY=" 开头（允许行首空白）覆写
+        const m = line.match(/^\s*([\w.]+)\s*=/);
+        if (m && m[1] === key) {
+            outLines.push(`${key}=${formatValue(value)}`);
+            found = true;
+        } else {
+            outLines.push(line);
+        }
+    }
+    if (!found) {
+        // 末尾补空行再追加，保证与前面内容分隔
+        if (outLines.length > 0 && outLines[outLines.length - 1].trim() !== '') outLines.push('');
+        outLines.push(`${key}=${formatValue(value)}`);
+    }
+    fs.writeFileSync(p, outLines.join('\n').replace(/\n+$/, '\n'), { encoding: 'utf8' });
+    return true;
+}
+
+/** 行级删除：只删目标键行（保留注释/其他键） */
+export function removeEnvKey(user3libHome, key) {
+    const p = userEnvPath(user3libHome);
+    if (!fs.existsSync(p)) return false;
+    const lines = fs.readFileSync(p, 'utf8').split('\n');
+    const outLines = lines.filter(line => {
+        const m = line.match(/^\s*([\w.]+)\s*=/);
+        return !(m && m[1] === key);
+    });
+    fs.writeFileSync(p, outLines.join('\n').replace(/\n+$/, '\n') + '\n', { encoding: 'utf8' });
+    return true;
+}
+
+/** 值写入 .env 的引号策略：含特殊字符时加引号 */
+function formatValue(v) {
+    const s = String(v ?? '');
+    if (/[\s#"'$`]/.test(s)) {
+        return `"${s.replace(/"/g, '\\"')}"`;
+    }
+    return s;
+}
+
+/** 脱敏：AK/Token 类只显示部分 */
+export function maskSecret(value) {
+    const s = String(value ?? '');
+    if (!s) return '';
+    if (s.length <= 8) return '****';
+    if (s.length <= 16) return `${s.slice(0, 4)}****${s.slice(-4)}`;
+    return `${s.slice(0, 8)}…${s.slice(-4)}`;
+}
+
+/**
+ * 计算"当前生效值"及来源。
+ *
+ * 由于 loadEnvChain 会把 .env 链全部加载进 process.env，无法用 process.env 反推真实来源。
+ * 改为读各层文件，依次判定：
+ *   1. 系统环境变量（process.env 中存在，且不等同于用户/项目 .env 中的值）
+ *   2. 用户级 ~/.3lib/.env
+ *   3. 项目级 <projectRoot>/Server/.env（及 <projectRoot>/.env）
+ *   4. 默认值
+ *
+ * @param {string} key
+ * @param {object} userEnv - readUserEnv(user3libHome).values
+ * @param {object} projectEnv - readProjectEnv(projectRoot).values
+ */
+export function effectiveValue(key, userEnv, projectEnv) {
+    const envVal = process.env[key];
+    const uVal = (userEnv && userEnv[key] !== undefined) ? String(userEnv[key]).trim() : '';
+    const pVal = (projectEnv && projectEnv[key] !== undefined) ? String(projectEnv[key]).trim() : '';
+
+    // 系统环境变量优先：只要它不是来自两个 .env 的值，就算系统级
+    if (envVal !== undefined && envVal !== '' && envVal !== uVal && envVal !== pVal) {
+        return { value: envVal, source: 'env' };
+    }
+    // 用户 .env
+    if (uVal !== '') return { value: uVal, source: 'user-env' };
+    // 项目 .env
+    if (pVal !== '') return { value: pVal, source: 'project-env' };
+    // 默认值（3LIB_DATA_DIR 为展开后的绝对路径）
+    const meta = getKeyMeta(key);
+    const def = meta && meta.default ? expandHome(meta.default) : '';
+    return { value: def, source: 'default' };
+}
+
+// ─── 子命令实现（供 cli.js 调用）──────────────────────────────────
+
+/**
+ * 解析并执行 config 子命令。
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.user3libHome
+ * @param {boolean} opts.jsonMode
+ * @param {function} opts.out
+ * @param {string[]} opts.rest - config 子命令剩余参数（[sub, key, ...value]）
+ * @returns {Promise<number>} 退出码
+ */
+export async function cmdConfigImpl({ projectRoot, user3libHome, jsonMode, out, rest = [] }) {
+    const [sub, key, ...valueParts] = rest;
+    const value = valueParts.join(' ');
+
+    switch (sub) {
+        case undefined:
+        case '--help':
+        case '-h':
+            return configHelp();
+        case 'set':
+            return configSet({ user3libHome, key, value, jsonMode, out });
+        case 'get':
+            return configGet({ projectRoot, user3libHome, key, jsonMode, out });
+        case 'unset':
+            return configUnset({ user3libHome, key, jsonMode, out });
+        case 'list':
+        case 'ls':
+            return configList({ projectRoot, user3libHome, jsonMode, out });
+        default:
+            process.stderr.write(`未知 config 子命令: ${sub}\n`);
+            configHelp();
+            return 1;
+    }
+}
+
+// ─── 子命令实现 ─────────────────────────────────────────────────
+
+function configHelp() {
+    process.stdout.write(`3rdloop config —— 配置 .env 配置项（默认读写 ~/.3lib/.env）
+
+用法:
+  3rdloop config list                列出全部配置项及当前生效值
+  3rdloop config get <KEY>           查看某项当前生效值
+  3rdloop config set <KEY> <VALUE>   设置某项（密钥不回显）
+  3rdloop config unset <KEY>         删除用户级 .env 中的某项（恢复默认）
+
+示例:
+  3rdloop config set 3LIB_DATA_DIR D:\\code\\team\\db
+  3rdloop config get LLM_MODEL
+  3rdloop config list --json
+
+优先级（从高到低）：系统环境变量 > ~/.3lib/.env > 默认值
+`);
+    return 0;
+}
+
+function fmtErr(key, meta) {
+    return `未知配置项: ${key}
+已知配置项见 "3rdloop config list"。`;
+}
+
+async function configSet({ user3libHome, key, value, jsonMode, out }) {
+    const meta = getKeyMeta(key);
+    if (!meta) {
+        if (jsonMode) out({ ok: false, error: fmtErr(key) });
+        else process.stderr.write(`${fmtErr(key)}\n`);
+        return 1;
+    }
+    if (meta.envOnly) {
+        const msg = `${key} 仅支持系统环境变量（3LIB_ROOT/3LIB_HOME），写入 ~/.3lib/.env 不生效。请用 setx / export 设置。`;
+        if (jsonMode) out({ ok: false, error: msg });
+        else process.stderr.write(`${msg}\n`);
+        return 1;
+    }
+    if (!value) {
+        const msg = `缺少值: 3rdloop config set ${key} <VALUE>`;
+        if (jsonMode) out({ ok: false, error: msg });
+        else process.stderr.write(`${msg}\n`);
+        return 1;
+    }
+    if (!meta.validate(value)) {
+        const msg = `配置项 ${key} 的值不合法: "${value}"（${meta.description}）`;
+        if (jsonMode) out({ ok: false, error: msg });
+        else process.stderr.write(`${msg}\n`);
+        return 1;
+    }
+    applyEnvKey(user3libHome, key, value);
+    if (jsonMode) {
+        out({ ok: true, key, value: meta.secret ? maskSecret(value) : value });
+    } else {
+        const shown = meta.secret ? '<已设置（密钥不回显）>' : value;
+        process.stdout.write(`已设置 ${key} = ${shown}\n`);
+    }
+    return 0;
+}
+
+async function configGet({ projectRoot, user3libHome, key, jsonMode, out }) {
+    const meta = getKeyMeta(key);
+    if (!meta) {
+        if (jsonMode) out({ ok: false, error: fmtErr(key) });
+        else process.stderr.write(`${fmtErr(key)}\n`);
+        return 1;
+    }
+    const { value, source } = effectiveValue(key, readUserEnv(user3libHome).values, readProjectEnv(projectRoot).values);
+    if (meta.envOnly && source === 'default') {
+        const msg = `${key} 为系统环境变量专用，未检测到已设置`;
+        if (jsonMode) out({ ok: true, key, value: '', source, envOnly: true });
+        else process.stderr.write(`${msg}\n`);
+        return 0;
+    }
+    const shown = meta.secret ? maskSecret(value) : value;
+    if (jsonMode) out({ ok: true, key, value: shown, source, secret: !!meta.secret });
+    else process.stdout.write(`${shown}\n`);
+    return 0;
+}
+
+async function configUnset({ user3libHome, key, jsonMode, out }) {
+    const meta = getKeyMeta(key);
+    if (!meta) {
+        if (jsonMode) out({ ok: false, error: fmtErr(key) });
+        else process.stderr.write(`${fmtErr(key)}\n`);
+        return 1;
+    }
+    if (meta.envOnly) {
+        const msg = `${key} 仅支持系统环境变量，无法从 ~/.3lib/.env 删除。请直接移除系统环境变量。`;
+        if (jsonMode) out({ ok: false, error: msg });
+        else process.stderr.write(`${msg}\n`);
+        return 1;
+    }
+    const removed = removeEnvKey(user3libHome, key);
+    if (jsonMode) out({ ok: true, key, removed });
+    else process.stdout.write(removed ? `已删除 ${key}（恢复默认）\n` : `${key} 未在 ~/.3lib/.env 中，无需删除\n`);
+    return 0;
+}
+
+async function configList({ projectRoot, user3libHome, jsonMode, out }) {
+    const userEnv = readUserEnv(user3libHome).values;
+    const projectEnv = readProjectEnv(projectRoot).values;
+    const rows = ENV_KEYS.map(meta => {
+        const { value, source } = effectiveValue(meta.key, userEnv, projectEnv);
+        const shown = meta.secret ? maskSecret(value) : (meta.envOnly ? (source === 'default' ? '' : value) : value);
+        return {
+            key: meta.key,
+            value: shown,
+            source,
+            secret: !!meta.secret,
+            envOnly: !!meta.envOnly,
+            default: meta.default ? expandHome(meta.default) : '',
+            description: meta.description,
+        };
+    });
+    if (jsonMode) {
+        out({ ok: true, total: rows.length, items: rows });
+        return 0;
+    }
+    process.stdout.write(`配置项（优先级：系统环境变量 > ~/.3lib/.env > 默认值）\n`);
+    for (const r of rows) {
+        const v = r.secret && r.value ? `${maskSecret(r.value)}` : (r.value || (r.source === 'default' ? `默认: ${r.default || '(空)'}` : '(未设置)'));
+        const tag = r.envOnly ? ' [envOnly]' : '';
+        process.stdout.write(`  ${r.key}${tag.padEnd(4)} = ${v}\n`);
+        if (r.description) process.stdout.write(`      ${r.description}（${sourceLabel(r.source)}）\n`);
+    }
+    return 0;
+}
+
+function sourceLabel(s) {
+    return { env: '系统环境变量', 'user-env': '~/.3lib/.env', 'project-env': '项目 Server/.env', default: '默认值' }[s] || s;
+}

package/lib/config.js

@@ -4,13 +4,13 @@
  * 职责：
  *   - 定位项目根（3LIB_ROOT env > git 仓库根 > cwd 上溯）
  *   - 加载 .env 链：环境变量 > ~/.3lib/.env（用户级） > 项目根 Server/.env（仓库内）
- *   - 定位数据目录（--data-dir > 3LIB_DATA_DIR > ~/.3lib/<project>/db）
+ *   - 定位数据目录（--data-dir > 3LIB_DATA_DIR > ~/.3lib/3rdloop/db）
  *   - 生成 clinic 安全唯一 taskId（随机位 8）
  *   - SKILL 目录优先级链（--skill-dir > 3LIB_SKILL_DIR > vendor/Skills）
  *
- * 数据目录策略（A3）：
- *   每用户隔离 ~/.3lib/<project>/db，多成员各自独立，避免并发冲突。
- *   team 共享审计留待 v2 loop serve + 中央 db。
+ * 数据目录策略：
+ *   用户级统一 ~/.3lib/3rdloop/db（跨平台，由 getUser3libHome 解析），
+ *   不与执行目录耦合（默认不再落在执行目录上级），也不随 npm 卸载包而清空。
  */
 
 import fs from 'node:fs';
@@ -210,24 +210,25 @@ export function getUser3libHome() {
  * 优先级：
  *   1. --data-dir 显式参数
  *   2. 环境变量 3LIB_DATA_DIR
- *   3. <项目根同级>/db （默认，仓库同级共享数据目录，如 D:\code\3rdLibraryLoop → D:\code\db）
+ *   3. <用户 3lib 主目录>/3rdloop/db（默认，跨平台统一，如 Windows:
+ *      C:\Users\<用户>\.3lib\3rdloop\db，macOS/Linux: ~/.3lib/3rdloop/db）
  *
- * 说明：默认从"每用户隔离 ~/.3lib/<项目>/db"调整为"仓库根同级共享 db"，
- * 便于团队在同机共享任务数据（任务写入 <dataDir>/task/{taskId}/）。
- * 如需每用户隔离，仍可用 --data-dir 或 3LIB_DATA_DIR 覆盖（A3 保留覆盖能力）。
+ * 设计说明：默认不随执行目录变化（避免在 D:\tmp 执行时误落 D:\db），
+ * 也不放在 npm 包目录内（避免全局重装/卸载时数据被清空）；各命令通过注入的
+ * dataDir 自动跟随，任务写入 <dataDir>/task/{taskId}/。
+ * 如需团队共享或其他自定义位置，可用 --data-dir 或 3LIB_DATA_DIR 覆盖。
  *
  * @returns {string} 数据根目录绝对路径
  */
-export function resolveDataDir({ dataDirFlag, projectName, user3libHome, projectRoot }) {
+export function resolveDataDir({ dataDirFlag, user3libHome }) {
     let rootDir;
     if (dataDirFlag) {
         rootDir = path.resolve(dataDirFlag);
     } else if (process.env['3LIB_DATA_DIR']) {
         rootDir = path.resolve(process.env['3LIB_DATA_DIR']);
     } else {
-        // 仓库根同级：<项目根>/../db
-        const repoRoot = projectRoot || user3libHome;
-        rootDir = path.join(path.dirname(repoRoot), 'db');
+        // 用户级统一位置（跨平台由 getUser3libHome 解析）
+        rootDir = path.join(user3libHome, '3rdloop', 'db');
     }
     fs.mkdirSync(rootDir, { recursive: true });
     return rootDir;

package/lib/queries.js

@@ -17,7 +17,7 @@ import path from 'node:path';
 
 /**
  * 计算 taskRoot 目录绝对路径。
- * @param {string} dataDir - 数据目录（~/.3lib/<project>/db）
+ * @param {string} dataDir - 数据目录（~/.3lib/3rdloop/db）
  * @returns {string}
  */
 export function taskDir(dataDir) {