@ohos-cpf/3rdloop 0.0.1

package/lib/config.js

@@ -0,0 +1,318 @@
+/**
+ * config.js —— CLI 环境装配
+ *
+ * 职责：
+ *   - 定位项目根（3LIB_ROOT env > git 仓库根 > cwd 上溯）
+ *   - 加载 .env 链：环境变量 > ~/.3lib/.env（用户级） > 项目根 Server/.env（仓库内）
+ *   - 定位数据目录（--data-dir > 3LIB_DATA_DIR > ~/.3lib/<project>/db）
+ *   - 生成 clinic 安全唯一 taskId（随机位 8）
+ *   - SKILL 目录优先级链（--skill-dir > 3LIB_SKILL_DIR > vendor/Skills）
+ *
+ * 数据目录策略（A3）：
+ *   每用户隔离 ~/.3lib/<project>/db，多成员各自独立，避免并发冲突。
+ *   team 共享审计留待 v2 loop serve + 中央 db。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// cli/ 目录的绝对路径（本文件在 cli/lib/ 下）
+const CLI_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// vendor 目录（核心引擎副本所在，发布时存在；开发期可能是软链/直接引用仓库）
+const VENDOR_DIR = path.join(CLI_ROOT, 'vendor');
+
+/**
+ * 解析命令行全局选项的统一入口。
+ * 所有子命令共用 --json/-v/--quiet/--data-dir/--project/--skill-dir。
+ *
+ * @param {string[]} argv - 传入命令（不含子命令名）的剩余参数
+ * @returns {{ json: boolean, verbose: boolean, quiet: boolean, dataDir: string, projectName: string, skillDir: string, rest: string[] }}
+ */
+export function parseGlobalFlags(argv) {
+    const opts = {
+        json: false,
+        verbose: false,
+        quiet: false,
+        dataDir: '',
+        projectName: '',
+        skillDir: '',
+        rest: [],
+    };
+
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+
+        switch (arg) {
+            case '--json':
+                opts.json = true;
+                break;
+            case '-v':
+            case '--verbose':
+                opts.verbose = true;
+                break;
+            case '--quiet':
+                opts.quiet = true;
+                break;
+            case '--data-dir':
+                opts.dataDir = argv[++i] || '';
+                break;
+            case '--project':
+                opts.projectName = argv[++i] || '';
+                break;
+            case '--skill-dir':
+                opts.skillDir = argv[++i] || '';
+                break;
+            default:
+                // 非 flags 参数统一归入 rest
+                if (arg.startsWith('--')) {
+                    // 未知 flag：忽略但保留以便子命令自行校验
+                    opts.rest.push(arg);
+                } else {
+                    opts.rest.push(arg);
+                }
+        }
+    }
+    return opts;
+}
+
+/**
+ * 解析时长字符串为毫秒。
+ * 支持：'30s' / '2m' / '1h' / '90'（默认为秒）；纯数字视为分钟。
+ *
+ * @param {string} value
+ * @returns {number} 毫秒
+ */
+export function parseDurationMs(value) {
+    const str = String(value || '').trim().toLowerCase();
+    if (!str) return 0;
+
+    const match = str.match(/^(\d+(?:\.\d+)?)(s|m|h|ms)?$/);
+    if (!match) {
+        throw new Error(`无法解析时长: "${value}"（支持 30s / 2m / 1h）`);
+    }
+    const num = parseFloat(match[1]);
+    const unit = match[2] || 'm';
+    const unitMs = { ms: 1, s: 1000, m: 60000, h: 3600000 }[unit];
+    return Math.round(num * unitMs);
+}
+
+/**
+ * 定位项目根。
+ *
+ * 优先级：
+ *   1. 环境变量 3LIB_ROOT（显式指定）
+ *   2. 从 cwd 向上找到含 package.json 且含 Server/ 的目录（仓库根）
+ *   3. 从 cwd 向上找到第一个含 .git 的目录
+ *   4. cwd 本身
+ *
+ * 对 "嵌入式复用 Server/" 的意义：核心引擎在仓库 Server/ 下，找到仓库根
+ * 即可正确引用 vendor/Server 或直接引用源码 Server/。
+ *
+ * @returns {string}
+ */
+export function detectProjectRoot() {
+    if (process.env['3LIB_ROOT'] && fs.existsSync(process.env['3LIB_ROOT'])) {
+        return path.resolve(process.env['3LIB_ROOT']);
+    }
+
+    let dir = process.cwd();
+    while (true) {
+        // 判定：存在 package.json 且存在 Server/ 目录
+        if (fs.existsSync(path.join(dir, 'Server')) && fs.existsSync(path.join(dir, 'package.json'))) {
+            return dir;
+        }
+        // 判定：存在 .git
+        if (fs.existsSync(path.join(dir, '.git'))) {
+            return dir;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+    }
+    return process.cwd();
+}
+
+/**
+ * 生成项目名（默认取 git 仓库根目录名，可用 --project 覆盖）。
+ * @param {string} root 项目根路径
+ * @returns {string}
+ */
+export function getProjectName(root, override = '') {
+    if (override) return override;
+    return path.basename(root) || 'default';
+}
+
+/**
+ * 加载 .env 链。
+ *
+ * 优先级（后者不覆盖前者，dotenv.config 默认不覆盖已存在 env）：
+ *   1. 已存在的系统环境变量（最高）
+ *   2. ~/.3lib/.env（用户级，跨项目）
+ *   3. 项目根 Server/.env（仓库内）
+ *
+ * 这样实现 A3/D1：谁配了 .env 用谁的，key 不进包。
+ *
+ * @param {string} projectRoot - 项目根路径
+ * @param {string} user3libHome - 用户 3lib 主目录（~/.3lib）
+ */
+export async function loadEnvChain(projectRoot, user3libHome) {
+    const dotenv = await _loadDotenv();
+    if (!dotenv) return;
+
+    const candidates = [
+        path.join(user3libHome, '.env'),
+        path.join(projectRoot, 'Server', '.env'),
+        path.join(projectRoot, '.env'),
+    ];
+
+    for (const envPath of candidates) {
+        try {
+            if (fs.existsSync(envPath)) {
+                dotenv.config({ path: envPath, quiet: true });
+            }
+        } catch {
+            // 单个 .env 损坏不影响整体
+        }
+    }
+}
+
+let _dotenvPromise = null;
+function _loadDotenv() {
+    if (_dotenvPromise) return _dotenvPromise;
+    _dotenvPromise = (async () => {
+        try {
+            const mod = await import('dotenv');
+            return mod.default;
+        } catch {
+            return null;
+        }
+    })();
+    return _dotenvPromise;
+}
+
+/**
+ * 计算用户级 3lib 主目录。
+ * 提供 3LIB_HOME 覆盖，默认 ~/.3lib。
+ * @returns {string}
+ */
+export function getUser3libHome() {
+    if (process.env['3LIB_HOME']) return process.env['3LIB_HOME'];
+    const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+    return path.join(home, '.3lib');
+}
+
+/**
+ * 确定数据目录。
+ *
+ * 优先级：
+ *   1. --data-dir 显式参数
+ *   2. 环境变量 3LIB_DATA_DIR
+ *   3. <项目根同级>/db （默认，仓库同级共享数据目录，如 D:\code\3rdLibraryLoop → D:\code\db）
+ *
+ * 说明：默认从"每用户隔离 ~/.3lib/<项目>/db"调整为"仓库根同级共享 db"，
+ * 便于团队在同机共享任务数据（任务写入 <dataDir>/task/{taskId}/）。
+ * 如需每用户隔离，仍可用 --data-dir 或 3LIB_DATA_DIR 覆盖（A3 保留覆盖能力）。
+ *
+ * @returns {string} 数据根目录绝对路径
+ */
+export function resolveDataDir({ dataDirFlag, projectName, user3libHome, projectRoot }) {
+    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');
+    }
+    fs.mkdirSync(rootDir, { recursive: true });
+    return rootDir;
+}
+
+/**
+ * 确定 SKILL 目录。
+ *
+ * 优先级：
+ *   1. --skill-dir 显式参数
+ *   2. 环境变量 3LIB_SKILL_DIR
+ *   3. vendor/Skills（发布包内）
+ *   4. 仓库内 Server/Skills（开发期）
+ *
+ * @param {string} projectRoot
+ * @returns {string}
+ */
+export function resolveSkillDir({ skillDirFlag, projectRoot, cliRoot = CLI_ROOT }) {
+    if (skillDirFlag) return path.resolve(skillDirFlag);
+    if (process.env['3LIB_SKILL_DIR']) return path.resolve(process.env['3LIB_SKILL_DIR']);
+
+    const vendorSkills = path.join(vendorDir(), 'Server', 'Skills');
+    if (fs.existsSync(vendorSkills)) {
+        return vendorSkills;
+    }
+
+    const repoSkills = path.join(projectRoot, 'Server', 'Skills');
+    if (fs.existsSync(repoSkills)) {
+        return repoSkills;
+    }
+    return path.join(cliRoot, 'vendor', 'Server', 'Skills');
+}
+
+/**
+ * 返回 vendor 目录绝对路径。
+ * @returns {string}
+ */
+export function vendorDir(cliRoot = CLI_ROOT) {
+    return VENDOR_DIR;
+}
+
+/**
+ * 生成 taskId。
+ *
+ * 格式：task_<ts36><rand8>
+ * 随机位 8（~1e10 空间），避免并发提交碰撞（对照 Server 原始 rand4）。
+ * 可选前缀：--project 或环境变量 3LIB_TASK_PREFIX（团队审计用）。
+ *
+ * @returns {string}
+ */
+export function generateTaskId() {
+    const ts = Date.now().toString(36);
+    let rand = '';
+    // 用 crypto 安全随机，避免 Math.random 精度 53bit 导致 rand8 可预测性
+    try {
+        const bytes = crypto.randomBytes(6);
+        rand = bytes.toString('base64url').replace(/[^a-z0-9]/gi, '').slice(0, 8).toLowerCase();
+    } catch {
+        rand = Math.random().toString(36).substring(2, 10);
+    }
+    if (rand.length < 8) {
+        rand = (rand + Math.random().toString(36).substring(2, 10)).slice(0, 8);
+    }
+    const prefix = process.env['3LIB_TASK_PREFIX'] || '';
+    return `${prefix}task_${ts}${rand}`;
+}
+
+/**
+ * 读取项目 version（来自 package.json 或 vendor/VERSION）。
+ * @returns {string}
+ */
+export function getCliVersion() {
+    try {
+        const pkg = JSON.parse(fs.readFileSync(path.join(CLI_ROOT, 'package.json'), 'utf8'));
+        return pkg.version || '0.0.0';
+    } catch {
+        return '0.0.0';
+    }
+}
+
+/**
+ * 检查 Node 版本 >= 22。
+ * @returns {boolean}
+ */
+export function checkNodeVersion() {
+    const major = Number(process.version.match(/^v(\d+)/)?.[1] || 0);
+    return major >= 22;
+}

package/lib/doctor.js

@@ -0,0 +1,114 @@
+/**
+ * doctor.js —— 环境自检（3rdloop doctor）
+ *
+ * 复用 check-env.mjs 的检测维度（轻量版，不耦合启动流程）：
+ *   1. Node.js 版本（>=22）
+ *   2. opencode 是否安装 + 服务是否运行
+ *   3. .env 配置（项目 Server/.env 或用户 ~/.3lib/.env）
+ *   4. 核心依赖是否可导入（vendor/Server）
+ *   5. Skill 目录可访问
+ *   6. opencode 端口连通性
+ *
+ * 退出码：全部通过 = 0；存在致命问题 = 1。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { C, logLine } from './ui.js';
+
+/**
+ * 检查命令是否在 PATH 中。
+ */
+function which(cmd) {
+    try {
+        const tool = process.platform === 'win32' ? 'where' : 'which';
+        const out = execSync(`${tool} ${cmd}`, { stdio: 'pipe', encoding: 'utf-8', timeout: 5000 });
+        return out.trim().split('\n')[0] || null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 执行环境自检。
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.skillDir
+ * @param {string} opts.dataDir
+ * @returns {Promise<{ ok: boolean, checks: Array<{name: string, passed: boolean, detail?: string}> }>}
+ */
+export async function runDoctor(opts = {}) {
+    const checks = [];
+    const { projectRoot, skillDir, dataDir } = opts;
+
+    // 1. Node.js 版本
+    const nodeMajor = Number(process.version.match(/^v(\d+)/)?.[1] || 0);
+    checks.push({
+        name: 'Node.js >= 22',
+        passed: nodeMajor >= 22,
+        detail: process.version,
+    });
+
+    // 2. opencode 可执行文件
+    const opencodeBin = which('opencode');
+    checks.push({
+        name: 'opencode CLI',
+        passed: !!opencodeBin,
+        detail: opencodeBin || '未找到，请 npm i -g opencode-ai',
+    });
+
+    // 3. .env 配置（项目 Server/.env 或用户 ~/.3lib/.env）
+    const envPaths = [
+        path.join(projectRoot, 'Server', '.env'),
+        path.join(process.env.HOME || process.env.USERPROFILE || '', '.3lib', '.env'),
+    ];
+    const foundEnv = envPaths.find(p => fs.existsSync(p));
+    let envOk = false;
+    let envDetail = '';
+    if (foundEnv) {
+        const content = fs.readFileSync(foundEnv, 'utf8');
+        const required = ['DASHSCOPE_API_KEY', 'LLM_BASE_URL', 'LLM_MODEL'];
+        const missing = required.filter(k => !new RegExp(`^\\s*${k}\\s*=\\s*(.+)$`, 'm').test(content));
+        envOk = missing.length === 0;
+        envDetail = missing.length
+            ? `缺少: ${missing.join(', ')} (${foundEnv})`
+            : `配置完整 (${foundEnv})`;
+    } else {
+        envDetail = '未找到 .env（项目 Server/.env 或 ~/.3lib/.env）';
+    }
+    checks.push({ name: 'LLM 环境变量', passed: envOk, detail: envDetail });
+
+    // 4. Skill 目录可访问
+    const skillOk = skillDir && fs.existsSync(skillDir);
+    checks.push({
+        name: 'SKILL 目录',
+        passed: !!skillOk,
+        detail: skillOk ? skillDir : 'SKILL 目录不存在',
+    });
+
+    // 5. 数据目录可写
+    let dataOk = false;
+    try {
+        fs.mkdirSync(dataDir, { recursive: true });
+        dataOk = true;
+    } catch { /* 不可写 */ }
+    checks.push({ name: '数据目录', passed: dataOk, detail: dataDir });
+
+    // 汇总
+    const ok = checks.every(c => c.passed);
+
+    // 打印
+    if (!opts.quiet) {
+        process.stderr.write(`\n${C.bold}3rdloop doctor 环境自检${C.reset}\n`);
+        for (const c of checks) {
+            const icon = c.passed ? `${C.green}✓${C.reset}` : `${C.red}✗${C.reset}`;
+            process.stderr.write(`  ${icon} ${c.name}`);
+            if (c.detail) process.stderr.write(`  ${C.gray}${c.detail}${C.reset}`);
+            process.stderr.write('\n');
+        }
+    }
+
+    return { ok, checks };
+}

package/lib/exit-codes.js

@@ -0,0 +1,31 @@
+/**
+ * exit-codes.js —— 退出码约定
+ *
+ * 退出码语义（脚本消费方核心契约）：
+ *   0    通过 / 成功
+ *   1    错误（参数错误 / 环境不满足 / 任务不存在 / 通用失败）
+ *   2    任务执行失败（终态为 failed / error / not passed）
+ *   3    wait 超时（任务在 --timeout 内未到终态）
+ *   130  SIGINT（Ctrl+C）
+ *   143  SIGTERM
+ *
+ * CI / 管道使用方按此约定判断任务结果，与 stdout/stderr 分离策略配套。
+ */
+export const EXIT = Object.freeze({
+    OK: 0,
+    ERROR: 1,
+    TASK_FAILED: 2,
+    TIMEOUT: 3,
+    SIGINT: 130,
+    SIGTERM: 143,
+});
+
+/** 大循环终态状态集合（用于判断任务是否已结束） */
+export const TERMINAL_LOOP_STATES = Object.freeze([
+    'passed', 'failed', 'aborted', 'error',
+]);
+
+/** 大循环运行中状态集合 */
+export const ACTIVE_LOOP_STATES = Object.freeze([
+    'idle', 'planning', 'executing', 'checking',
+]);

package/lib/opencode.js

@@ -0,0 +1,156 @@
+/**
+ * opencode.js —— opencode serve 生命周期管理
+ *
+ * 策略（A4）：
+ *   - 探测：操作前 checkHealth()（SDK session.list()）
+ *   - 拉起：CLI 自持 spawn('opencode serve')，透传 stderr 前几行；已在运行则复用不接管
+ *   - 归属：CLI 自己拉的记 pid，退出时先 abortLoop 再杀子进程
+ *   - 已知坑（AGENTS.md）：opencode 需在项目上一级目录执行 opencode serve；
+ *     子任务 session 创建时强制指定 cwd 会触发权限问题（已验证 SkillExecutor.drop cwd）
+ *
+ * 跨平台进程清理：
+ *   Windows 无进程组语义，须用 taskkill /T /F 杀进程树；Unix 用 process.kill(SIGTERM)。
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import path from 'node:path';
+import fs from 'node:fs';
+
+/**
+ * opencode 服务管理器。
+ *
+ * @example
+ * const mgr = new OpencodeManager({ projectRoot });
+ * await mgr.ensureRunning();     // 探测 -> 若未运行则拉起
+ * await mgr.stop();              // 若由本 CLI 拉起则杀掉
+ */
+export class OpencodeManager {
+    /**
+     * @param {object} opts
+     * @param {string} opts.projectRoot - 项目根（opencode serve 需在上一级目录运行）
+     * @param {number} [opts.port]      - opencode 端口（默认 4096）
+     */
+    constructor(opts = {}) {
+        this.projectRoot = opts.projectRoot || process.cwd();
+        this.port = opts.port || 4096;
+        this.baseUrl = `http://localhost:${this.port}`;
+        /** @type {import('node:child_process').ChildProcess|null} */
+        this.child = null;
+        /** @type {boolean} 是否由本 CLI 拉起（决定退出时是否杀） */
+        this.spawnedByUs = false;
+    }
+
+    /**
+     * 探测 opencode 是否已在运行。
+     * 通过 HTTP /health 或 session.list 连通性判断。
+     * @returns {Promise<{ ok: boolean, message: string }>}
+     */
+    async checkHealth() {
+        try {
+            // 轻量探测：尝试连接 baseUrl 的 /health（opencode 服务提供）
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), 3000);
+            const res = await fetch(`${this.baseUrl}/health`, { signal: controller.signal });
+            clearTimeout(timer);
+            if (res.ok) {
+                return { ok: true, message: `opencode 服务正常 (${this.baseUrl})` };
+            }
+            return { ok: false, message: `opencode 服务响应异常 (HTTP ${res.status})` };
+        } catch {
+            return { ok: false, message: `opencode 服务未运行 (${this.baseUrl})` };
+        }
+    }
+
+    /**
+     * 确保 opencode serve 正在运行。
+     * 未运行时自动拉起（在项目上一级目录执行）。
+     * @returns {Promise<{ ok: boolean, message: string, spawned: boolean }>}
+     */
+    async ensureRunning() {
+        const health = await this.checkHealth();
+        if (health.ok) {
+            return { ok: true, message: health.message, spawned: false };
+        }
+
+        // 未运行 → 尝试拉起
+        const cwd = path.resolve(this.projectRoot, '..');
+        this._log(`尝试启动 opencode serve (cwd=${cwd})...`);
+
+        try {
+            const child = spawn('opencode', ['serve'], {
+                cwd,
+                stdio: ['ignore', 'pipe', 'pipe'],
+                shell: process.platform === 'win32',
+                detached: false,
+            });
+
+            this.child = child;
+            this.spawnedByUs = true;
+
+            // 透传前几行 stderr 供诊断
+            let stderrLines = [];
+            child.stderr?.on('data', (chunk) => {
+                const text = chunk.toString().trim();
+                if (stderrLines.length < 5) stderrLines.push(text);
+            });
+
+            // 等待健康（最多 15s）
+            const deadline = Date.now() + 15000;
+            while (Date.now() < deadline) {
+                await this._sleep(1000);
+                const healthAgain = await this.checkHealth();
+                if (healthAgain.ok) {
+                    return { ok: true, message: `已启动 opencode serve (${this.baseUrl})`, spawned: true };
+                }
+                // 子进程提前退出则报错
+                if (child.exitCode != null) {
+                    break;
+                }
+            }
+
+            const stderrSnippet = stderrLines.join('\n  ');
+            return {
+                ok: false,
+                message: 'opencode serve 启动超时或失败' + (stderrSnippet ? `：\n  ${stderrSnippet}` : ''),
+                spawned: true,
+            };
+        } catch (err) {
+            return {
+                ok: false,
+                message: `启动 opencode serve 失败: ${err.message}`,
+                spawned: false,
+            };
+        }
+    }
+
+    /**
+     * 停止由本 CLI 拉起的 opencode 进程。
+     */
+    async stop() {
+        if (!this.spawnedByUs || !this.child || this.child.pid == null) return;
+        const pid = this.child.pid;
+        this._log(`停止由本 CLI 拉起的 opencode serve (pid=${pid})`);
+        try {
+            if (process.platform === 'win32') {
+                execSync(`taskkill /pid ${pid} /T /F`, { stdio: 'ignore' });
+            } else {
+                this.child.kill('SIGTERM');
+                // 等待退出
+                await new Promise(resolve => {
+                    const t = setTimeout(resolve, 3000);
+                    this.child.once('exit', () => { clearTimeout(t); resolve(); });
+                });
+            }
+        } catch {
+            // 进程可能已死
+        }
+        this.child = null;
+        this.spawnedByUs = false;
+    }
+
+    _sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
+
+    _log(msg) {
+        process.stderr.write(`[opencode] ${msg}\n`);
+    }
+}