@ohos-cpf/3rdloop 0.0.1

package/vendor/Server/Brain/PlanPersistence.js

@@ -0,0 +1,196 @@
+/**
+ * PlanPersistence —— 拆解计划持久化与历史加载
+ *
+ * 职责：
+ *   - 持久化 BrainPlan 到文件系统（按轮次独立保存 + 最新快照）
+ *   - 按 planId / taskId / taskId+loopCount 加载计划
+ *   - 加载某个 Task 下所有轮次的历史计划
+ *   - 列出所有历史计划（去重）
+ *
+ * 设计原则：
+ *   - 持有 storage 引用，不持有 Brain 的业务状态
+ *   - 无状态工具类，所有操作基于 storage 文件系统
+ */
+
+export class PlanPersistence {
+    /**
+     * @param {object} deps
+     * @param {object} deps.storage - 存储门面（createStorage() 返回值）
+     */
+    constructor({ storage }) {
+        this.storage = storage;
+    }
+
+    /**
+     * 持久化拆解计划到文件系统。
+     *
+     * 多轮循环持久化策略：
+     *   - brain_loop{n}.json — 每轮独立保存，完整保留历史
+     *   - brain.json — 最新快照，方便快速加载最新计划
+     *
+     * 目录结构：
+     *   db/task/{taskId}/
+     *     ├── brain_loop0.json         ← 第 0 轮初始拆解
+     *     ├── brain_loop1.json         ← 第 1 轮重规划
+     *     ├── brain.json               ← 最新计划快照（= 最后一轮的 brain_loop{n}）
+     *     ├── testcheck_loop0.json     ← 第 0 轮审核结果（TestCheck 写入）
+     *     ├── testcheck_loop1.json     ← 第 1 轮审核结果
+     *     ├── stepid_1_loop0.json      ← 第 0 轮步骤执行记录（FlexRunner 写入）
+     *     ├── stepid_1_loop1.json      ← 第 1 轮步骤执行记录
+     *     └── ...
+     *
+     * @param {BrainPlan} plan
+     */
+    async persistPlan(plan) {
+        try {
+            const json = this.storage.json('task');
+            const loopCount = plan.loopCount ?? 0;
+
+            // 按轮次独立保存（完整保留历史）
+            await json.write(`${plan.taskId}/brain_loop${loopCount}`, plan);
+
+            // 同时写入最新快照（兼容已有 loadPlan / listPlans 逻辑）
+            await json.write(`${plan.taskId}/brain`, plan);
+        } catch (err) {
+            console.warn(`[Brain] 持久化计划失败: ${err.message}`);
+        }
+    }
+
+    /**
+     * 从文件系统加载历史计划。
+     *
+     * 支持三种加载方式：
+     *   - 按 planId 遍历查找（回退路径，兼容旧调用）
+     *   - 按 taskId 加载最新计划（options.taskId，读取 brain.json 快照）
+     *   - 按 taskId + loopCount 加载指定轮次计划（options.taskId + options.loopCount）
+     *
+     * @param {string} planId
+     * @param {object} [options]
+     * @param {string} [options.taskId]     - 直接按 taskId 加载，避免遍历
+     * @param {number} [options.loopCount]  - 指定轮次（0=首轮, 1+=重规划轮）
+     * @param {Map<string, BrainPlan>} [plansCache] - Brain 内存缓存（可选）
+     * @returns {Promise<BrainPlan|null>}
+     */
+    async loadPlan(planId, options = {}, plansCache = null) {
+        // 先从内存查找
+        if (plansCache) {
+            const cached = plansCache.get(planId);
+            if (cached) return cached;
+        }
+
+        try {
+            const json = this.storage.json('task');
+
+            // 快速路径：直接按 taskId 读取
+            if (options.taskId) {
+                let plan;
+                if (options.loopCount != null) {
+                    // 加载指定轮次
+                    plan = await json.read(`${options.taskId}/brain_loop${options.loopCount}`);
+                } else {
+                    // 加载最新快照
+                    plan = await json.read(`${options.taskId}/brain`);
+                }
+                if (plan && plansCache) {
+                    plansCache.set(plan.planId, plan);
+                }
+                return plan;
+            }
+
+            // 回退路径：遍历 db/task/ 子目录查找匹配 planId 的计划
+            // 同时检查 brain.json（快照）和 brain_loop{n}.json（历史轮次）
+            const entries = await json.list();
+            for (const entry of entries) {
+                const isBrainFile = entry.key.endsWith('/brain') ||
+                    /\/brain_loop\d+$/.test(entry.key);
+                if (isBrainFile && entry.data?.planId === planId) {
+                    if (plansCache) {
+                        plansCache.set(planId, entry.data);
+                    }
+                    return entry.data;
+                }
+            }
+            return null;
+        } catch {
+            return null;
+        }
+    }
+
+    /**
+     * 加载某个 Task 下所有轮次的拆解计划（按轮次排序）。
+     *
+     * 扫描 db/task/{taskId}/brain_loop{n}.json 文件，返回按 loopCount 升序排列的计划数组。
+     *
+     * @param {string} taskId
+     * @returns {Promise<Array<BrainPlan>>}
+     */
+    async loadPlanHistory(taskId) {
+        try {
+            const json = this.storage.json('task');
+            const entries = await json.list();
+            const plans = entries
+                .filter(e => {
+                    if (!e.key.startsWith(`${taskId}/brain_loop`) || !e.data) return false;
+                    return /^brain_loop\d+$/.test(e.key.slice(taskId.length + 1));
+                })
+                .map(e => {
+                    const match = e.key.match(/brain_loop(\d+)$/);
+                    return { loop: match ? parseInt(match[1], 10) : 0, plan: e.data };
+                })
+                .sort((a, b) => a.loop - b.loop);
+            return plans.map(p => p.plan);
+        } catch {
+            return [];
+        }
+    }
+
+    /**
+     * 列出所有历史计划。
+     *
+     * 遍历 db/task/ 下所有子目录的 brain.json 和 brain_loop{n}.json 文件，
+     * 按 planId 去重（brain.json 与 brain_loop{n}.json 内容相同时只保留一份）。
+     *
+     * @param {Map<string, BrainPlan>} [plansCache] - Brain 内存缓存（可选，合并未落盘的计划）
+     * @returns {Promise<Array>}
+     */
+    async listPlans(plansCache = null) {
+        try {
+            const json = this.storage.json('task');
+            const entries = await json.list();
+            const rawPlans = entries
+                .filter(e => {
+                    if (!e.data) return false;
+                    return e.key.endsWith('/brain') ||
+                        /\/brain_loop\d+$/.test(e.key);
+                })
+                .map(e => e.data);
+
+            // 按 planId 去重（brain.json 快照与 brain_loop{n}.json 内容相同）
+            const seen = new Set();
+            const plans = [];
+            for (const plan of rawPlans) {
+                if (plan.planId && !seen.has(plan.planId)) {
+                    seen.add(plan.planId);
+                    plans.push(plan);
+                }
+            }
+
+            // 合并内存中的计划（可能尚未落盘）
+            if (plansCache) {
+                for (const [id, plan] of plansCache) {
+                    if (!seen.has(id)) {
+                        seen.add(id);
+                        plans.push(plan);
+                    }
+                }
+            }
+            return plans.sort((a, b) =>
+                new Date(b.createdAt) - new Date(a.createdAt)
+            );
+        } catch {
+            return plansCache ? Array.from(plansCache.values()) : [];
+        }
+    }
+}
+
+export default PlanPersistence;

package/vendor/Server/Brain/SkillExecutor.js

@@ -0,0 +1,251 @@
+/**
+ * SkillExecutor —— opencode CLI SKILL 执行引擎
+ *
+ * 职责：
+ *   - 惰性加载 CLIController（避免测试时加载重依赖）
+ *   - 通过 opencode CLI 创建 Session、发送 prompt、轮询完成
+ *   - 读取 SKILL 结果文件，解析 JSON
+ *
+ * 设计原则：
+ *   - 无状态工具类，不持有 Brain 的业务状态
+ *   - 所有方法接收参数而非访问实例属性（除 _cli 缓存外）
+ *   - 可独立单元测试
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+
+// CLIController 为惰性加载：测试中通过 deps 注入 mock 时不需要加载重依赖（@opencode-ai/sdk 等）。
+let _CLIController = null;
+
+async function _loadCLIController() {
+    if (!_CLIController) {
+        const mod = await import('../CLI/cli.js');
+        _CLIController = mod.CLIController;
+    }
+    return _CLIController;
+}
+
+/** 轮询间隔（ms） */
+const POLL_INTERVAL_MS = 5000;
+/** 轮询超时（ms），单次 SKILL 执行最多等待 10 分钟 */
+const POLL_TIMEOUT_MS = 30 * 60 * 1000;
+
+/** SKILL 轮询终止专用错误（由 abortSignal.isAborted 检测触发） */
+export class SKILL_ABORTED_ERROR extends Error {
+    /**
+     * @param {string} [message]
+     */
+    constructor(message = 'SKILL 执行被终止') {
+        super(message);
+        this.name = 'SkillAbortedError';
+    }
+}
+
+export { POLL_INTERVAL_MS, POLL_TIMEOUT_MS };
+
+export class SkillExecutor {
+    /**
+     * @param {object} [deps]
+     * @param {object} [deps.cli] - CLIController 实例（可选，不传则惰性加载）
+     */
+    constructor(deps = {}) {
+        this._cli = deps.cli || null;
+    }
+
+    /**
+     * 获取 CLIController 实例（惰性加载）。
+     *
+     * @returns {Promise<object>} CLIController 实例
+     */
+    async getCLI() {
+        if (!this._cli) {
+            const CLIController = await _loadCLIController();
+            this._cli = new CLIController('opencode');
+        }
+        return this._cli;
+    }
+
+    /**
+     * 通过 opencode CLI 执行 SKILL。
+     *
+     * 流程：
+     *   1. 健康检查
+     *   2. 构建 prompt（含任务描述、SKILL 目录、输出路径、上下文信息）
+     *   3. 创建 Session（指定 cwd = workDir）并发送 prompt
+     *   4. 轮询等待 Session 完成
+     *   5. 读取结果文件，解析 JSON
+     *
+     * @param {string} skillDir        - SKILL 目录绝对路径
+     * @param {string} workDir         - 工作目录（Session 的 cwd）
+     * @param {string} resultFilePath  - 结果文件输出路径
+     * @param {string} title           - Session 标题
+     * @param {Array<string>} contextSections - prompt 中的上下文段落列表
+     * @param {object} [abortSignal]   - 终止信号 { isAborted: () => boolean, onSessionCreated: (sid) => void }
+     * @returns {Promise<{success: boolean, json: object|null, raw: string, sessionId: string}>}
+     */
+    async invokeSkill(skillDir, workDir, resultFilePath, title, contextSections, abortSignal = null) {
+        const cli = await this.getCLI();
+
+        // ── 1. 健康检查 ──
+        const health = await cli.checkHealth();
+        if (health.status !== 'ok') {
+            throw new Error(`opencode 服务不可用: ${health.message || 'health check failed'}`);
+        }
+
+        // ── 1b. 确保工作目录存在 ──
+        // opencode 在 promptAsync 时会 realPath 检查 session 的 directory，
+        // 如果目录不存在会静默失败（返回 204 但不处理，tokens=0+0）。
+        // 必须在创建 session 之前创建工作目录。
+        if (workDir) {
+            fs.mkdirSync(workDir, { recursive: true });
+        }
+        // 确保结果文件的父目录也存在
+        if (resultFilePath) {
+            const resultDir = path.dirname(resultFilePath);
+            fs.mkdirSync(resultDir, { recursive: true });
+        }
+
+        // ── 2. 构建 prompt ──
+        const prompt = this.buildSkillPrompt(skillDir, workDir, resultFilePath, contextSections);
+
+        // ── 3. 创建 Session 并发送 prompt ──
+        // const { sessionId } = await cli.startSession(title, prompt, { cwd: workDir });
+        const { sessionId } = await cli.startSession(title, prompt);
+
+        // 通知上层登记 sessionId（abortLoop 可据此远程中止 opencode session）
+        if (abortSignal && typeof abortSignal.onSessionCreated === 'function') {
+            try {
+                abortSignal.onSessionCreated(sessionId);
+            } catch { /* 回调异常不影响主流程 */ }
+        }
+
+        // Session 创建后终止标志已置位（终止发生在 startSession 过程中）→ 立即中止并退出
+        if (abortSignal && typeof abortSignal.isAborted === 'function' && abortSignal.isAborted()) {
+            try {
+                await cli.abortSession(sessionId);
+            } catch { /* 已自然结束 */ }
+            throw new SKILL_ABORTED_ERROR(`SKILL 执行被终止（session ${sessionId} 创建后即中止）`);
+        }
+
+        // ── 4. 轮询等待完成 ──
+        const completed = await this.pollSession(cli, sessionId, abortSignal);
+        if (!completed) {
+            throw new Error(`SKILL 执行超时（Session ${sessionId} 未在 ${POLL_TIMEOUT_MS / 1000}s 内完成）`);
+        }
+
+        // ── 5. 读取结果文件 ──
+        const result = await this.readSkillResult(resultFilePath);
+        // 将 sessionId 透传给调用方，供 Brain 记录到 plan 中
+        result.sessionId = sessionId;
+        return result;
+    }
+
+    /**
+     * 构建 SKILL 执行 prompt。
+     *
+     * @param {string} skillDir        - SKILL 目录路径
+     * @param {string} workDir         - 工作目录
+     * @param {string} resultFilePath  - 结果文件输出路径
+     * @param {Array<string>} contextSections - 上下文段落
+     * @returns {string}
+     */
+    buildSkillPrompt(skillDir, workDir, resultFilePath, contextSections) {
+        const parts = [];
+
+        // SKILL 目录（告诉 opencode 读取并遵循该 SKILL 的指令）
+        parts.push(`## SKILL 目录\n${skillDir}`);
+        parts.push('请读取上述 SKILL 目录中的 SKILL.md 文件，并严格按照其中的指令执行任务。');
+
+        // 工作目录
+        if (workDir) {
+            parts.push(`## 工作目录\n${workDir}\n\n所有文件操作请在此目录下执行。`);
+        }
+
+        // 结果文件输出路径
+        parts.push(`## 结果文件输出路径\n${resultFilePath}`);
+        parts.push('执行完成后，请将结果写入上述路径。结果文件为纯 JSON 格式，不要追加任何额外内容。');
+
+        // 上下文段落
+        for (const section of contextSections) {
+            if (section) parts.push(section);
+        }
+
+        parts.push('请按照 SKILL 中的指令执行，确保输出结果格式正确、字段完整。');
+
+        return parts.join('\n\n');
+    }
+
+    /**
+     * 轮询 opencode Session 状态，直到完成或超时。
+     *
+     * @param {object} cli       - CLIController 实例
+     * @param {string} sessionId - Session ID
+     * @param {object} [abortSignal] - 终止信号 { isAborted: () => boolean }；
+     *                                  置位时在下一轮询周期抛 SKILL_ABORTED_ERROR 退出
+     * @returns {Promise<boolean>} 是否完成
+     */
+    async pollSession(cli, sessionId, abortSignal = null) {
+        const deadline = Date.now() + POLL_TIMEOUT_MS;
+
+        while (Date.now() < deadline) {
+            // 终止检查：比超时检查优先，确保终止请求即时生效
+            if (abortSignal && typeof abortSignal.isAborted === 'function' && abortSignal.isAborted()) {
+                // 远程中止 opencode session（尽力而为），阻止其继续在后台运行
+                try {
+                    await cli.abortSession(sessionId);
+                } catch { /* 已自然结束 */ }
+                throw new SKILL_ABORTED_ERROR(`SKILL 执行被终止（session ${sessionId}）`);
+            }
+
+            await this.sleep(POLL_INTERVAL_MS);
+
+            try {
+                const { status } = await cli.checkSessionStatus(sessionId);
+                if (status === 'completed') return true;
+                if (status === 'error') return false;
+            } catch (err) {
+                console.warn(`[SkillExecutor] 轮询 Session 状态失败: ${err.message}`);
+            }
+        }
+        return false;
+    }
+
+    /**
+     * 读取 SKILL 执行结果文件，解析 JSON。
+     *
+     * 结果文件格式：纯 JSON（不含 markdown 代码块标记或执行状态字段）。
+     *
+     * @param {string} resultFilePath - 结果文件路径
+     * @returns {Promise<{success: boolean, json: object|null, raw: string}>}
+     */
+    async readSkillResult(resultFilePath) {
+        const raw = await fs.readFileSync(resultFilePath, 'utf-8');
+
+        // 提取 JSON 部分（首个 { 到末个 }）
+        const jsonStart = raw.indexOf('{');
+        const jsonEnd = raw.lastIndexOf('}');
+        let json = null;
+
+        if (jsonStart !== -1 && jsonEnd !== -1 && jsonEnd > jsonStart) {
+            const jsonStr = raw.substring(jsonStart, jsonEnd + 1);
+            json = JSON.parse(jsonStr);
+        }
+
+        // JSON 解析成功即视为执行成功
+        const success = json !== null;
+
+        return { success, json, raw };
+    }
+
+    /**
+     * Promise 版 sleep。
+     * @param {number} ms
+     * @returns {Promise<void>}
+     */
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+
+export default SkillExecutor;

package/vendor/Server/Brain/index.js

@@ -0,0 +1,11 @@
+/**
+ * Brain 模块统一导出
+ *
+ * 外部使用：
+ *   import { Brain, BrainStatus } from './Brain/index.js';
+ *   const brain = new Brain({ sseHub, storage });
+ *   const plan = await brain.planTask('对 libcurl 进行鸿蒙化分析');
+ */
+
+export { Brain, BrainStatus } from './Brain.js';
+export { default } from './Brain.js';

package/vendor/Server/CLI/cli.js

@@ -0,0 +1,243 @@
+import OpenCodeCLI from './opencode/index.js';
+import { StatsService } from '../library/StatsService.js';
+
+/**
+ * 通用 CLI 控制类
+ *
+ * 封装 opencode-cli，对外暴露统一的 Session 管理接口。
+ *
+ * @example
+ * const cli = new CLIController('opencode', { host: 'localhost', port: '4096' });
+ *
+ * // 通用接口
+ * await cli.checkHealth();
+ * const { sessionId } = await cli.startSession('任务标题', '初始提示词');
+ * await cli.sendMessage(sessionId, '继续消息');
+ * const status = await cli.checkSessionStatus(sessionId);
+ * const sessions = await cli.listSessions();
+ * const session = await cli.getSession(sessionId);
+ * await cli.abortSession(sessionId);
+ * await cli.deleteSession(sessionId);
+ */
+class CLIController {
+    /**
+     * @param {'opencode'} type - CLI 类型
+     * @param {object} [options={}]       - 传递给对应适配器的配置项
+     *
+     * opencode 选项：
+     *   options.host    {string} - 服务主机（默认 localhost）
+     *   options.port    {string} - 服务端口（默认 4096）
+     *   options.baseUrl {string} - 完整 URL，优先级高于 host/port
+     *
+     * 公共选项：
+     *   options.archive    - MessageArchive 实例（消息存档与卡死检测），不传则适配器内部自建
+     */
+    constructor(type = 'opencode', options = {}) {
+        this.type = type;
+
+        switch (type) {
+            case 'opencode':
+                this.adapter = new OpenCodeCLI(options);
+                break;
+            default:
+                throw new Error(
+                    `不支持的 CLI 类型: "${type}"，可选值为 'opencode'`
+                );
+        }
+    }
+
+    // ─── 运行状态检查 ──────────────────────────────────────────────────────────
+
+    /**
+     * 检查 CLI 服务是否正常运行
+     * @returns {Promise<{ status: 'ok'|'error'|'disabled', message: string }>}
+     */
+    async checkHealth() {
+        return this.adapter.checkHealth();
+    }
+
+    // ─── Session 管理 ──────────────────────────────────────────────────────────
+
+    /**
+     * 获取所有 Session
+     * @returns {Promise<Array<object>>}
+     */
+    async listSessions() {
+        return this.adapter.listSessions();
+    }
+
+    /**
+     * 获取指定 Session
+     * @param {string} sessionId
+     * @returns {Promise<object>}
+     */
+    async getSession(sessionId) {
+        return this.adapter.getSession(sessionId);
+    }
+
+    /**
+     * 删除 Session
+     * @param {string} sessionId
+     * @returns {Promise<object>}
+     */
+    async deleteSession(sessionId) {
+        return this.adapter.deleteSession(sessionId);
+    }
+
+    /**
+     * 终止 Session（中断正在运行的任务或进程）
+     * @param {string} sessionId
+     * @returns {Promise<object>}
+     */
+    async abortSession(sessionId) {
+        return this.adapter.abortSession(sessionId);
+    }
+
+    /**
+     * 向 Session 发送消息
+     * @param {string} sessionId
+     * @param {string} message
+     * @returns {Promise<{ success: boolean, response?: string }>}
+     */
+    async sendMessage(sessionId, message) {
+        return this.adapter.sendMessage(sessionId, message);
+    }
+
+    /**
+     * 向 Session 发送消息并同步等待 AI 回复完成
+     *
+     * 发送消息后阻塞等待 AI 生成完整回复，然后返回回复内容。
+     * 与 sendMessage（异步 fire-and-forget）不同，此方法会等到 AI 回复完成。
+     *
+     * @param {string} sessionId
+     * @param {string} message
+     * @returns {Promise<{ success: boolean, response: object|string, content: string }>}
+     */
+    async sendAndWaitMessage(sessionId, message) {
+        return this.adapter.sendAndWaitMessage(sessionId, message);
+    }
+
+    /**
+     * 向 Session 注入提示词/上下文（不触发 AI 响应）
+     *
+     * 利用 opencode SDK 的 noReply: true 能力，将文本注入对话历史
+     * 但不触发 AI 生成回复。适用于对话过程中动态补充上下文、规则、指令。
+     *
+     * 向 Session 注入上下文（不触发 AI 响应，基于 opencode noReply 模式）。
+     *
+     * @param {string} sessionId
+     * @param {string} message  - 要注入的提示词/上下文
+     * @returns {Promise<{ success: boolean }>}
+     */
+    async injectPrompt(sessionId, message) {
+        return this.adapter.injectPrompt(sessionId, message);
+    }
+
+    /**
+     * 创建新 Session，可选附带初始提示词
+     * @param {string} title    - Session 标题
+     * @param {string} [prompt] - 初始提示词（可选）
+     * @param {object} [options]
+     * @param {string} [options.cwd] - 工作目录（指定后 opencode session 的文件操作在此目录下执行）
+     * @returns {Promise<{ sessionId: string, action: string, message: string }>}
+     */
+    async startSession(title, prompt, options = {}) {
+        // 记录 Session 调用次数（异步执行，不影响主流程）
+        StatsService.incrementSessionCount().catch(err => {
+            // 统计失败不影响正常业务，仅记录日志
+            console.warn('[CLIController] Session 统计记录失败:', err.message);
+        });
+        
+        return this.adapter.startSession(title, prompt, options);
+    }
+
+    /**
+     * 查询 Session 当前状态
+     * @param {string} sessionId
+     * @returns {Promise<{ status: string, lastMessage?: object }>}
+     */
+    async checkSessionStatus(sessionId) {
+        return this.adapter.checkSessionStatus(sessionId);
+    }
+
+    /**
+     * 获取 Session 消息历史
+     * @param {string} sessionId
+     * @returns {Promise<Array<object>>}
+     */
+    async getSessionMessages(sessionId) {
+        return this.adapter.getSessionMessages(sessionId);
+    }
+
+    /**
+     * 读取本地已归档的消息（持久化文件，不请求远端，用于事后审计/对比）
+     * @param {string} sessionId
+     * @returns {Promise<Array<object>>}
+     */
+    async getArchivedMessages(sessionId) {
+        return this.adapter.getArchivedMessages(sessionId);
+    }
+
+    /**
+     * 实时查看当前对话消息（运行中安全调用，不写入存档）
+     *
+     * 从远端 / 内存拉取当前已有消息并转为精简格式返回。
+     * 适用于对话进行中查看 "目前聊了什么"，不影响后续归档去重。
+     *
+     * @param {string} sessionId
+     * @returns {Promise<Array<{id?,role,content,finish?,timestamp?}>>}
+     */
+    async getLiveMessages(sessionId) {
+        return this.adapter.getLiveMessages(sessionId);
+    }
+
+    /**
+     * 导出完整对话（合并远端 + 本地，支持运行中 / 已结束）
+     *
+     * @param {string} sessionId
+     * @param {object} [opts]
+     * @param {'json'|'markdown'} [opts.format='json'] - 导出格式
+     * @returns {Promise<object|string>}
+     */
+    async exportSession(sessionId, opts) {
+        return this.adapter.exportSession(sessionId, opts);
+    }
+
+    /**
+     * 读取本地存档元信息（含 lastResponseAt / archivedCount / status 等，用于卡死判断）
+     * @param {string} sessionId
+     * @returns {Promise<object>}
+     */
+    async getArchiveMeta(sessionId) {
+        return this.adapter.getArchiveMeta(sessionId);
+    }
+
+    /**
+     * 列出所有本地已存档的 Session（基于存档文件）
+     * @returns {Promise<Array<object>>}
+     */
+    async listArchivedSessions() {
+        return this.adapter.archive.listSessions();
+    }
+
+    // ─── 元信息 ────────────────────────────────────────────────────────────────
+
+    /**
+     * 返回当前使用的 CLI 类型
+     * @returns {'opencode'}
+     */
+    getType() {
+        return this.type;
+    }
+
+    /**
+     * 返回底层适配器实例（供高级用途）
+     * @returns {OpenCodeCLI}
+     */
+    getAdapter() {
+        return this.adapter;
+    }
+}
+
+export { CLIController, OpenCodeCLI };
+export default CLIController;