@ohos-cpf/3rdloop 0.0.2 → 0.0.4

package/lib/doctor.js

@@ -1,114 +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 };
+/**
+ * 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

@@ -1,31 +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',
+/**
+ * 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

@@ -1,156 +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`);
-    }
+/**
+ * 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`);
+    }
 }