@ohos-cpf/3rdloop 0.0.6 → 0.0.8

package/README.md

@@ -44,10 +44,10 @@ npm i -g @ohos-cpf/3rdloop
 3rdloop doctor
 ```
 
-`doctor` 会逐项检查 Node / opencode / `.env` 凭据 / SKILL 目录 / 数据目录，缺什么会明确提示。除此之外还需要了解：
+`doctor` 会逐项检查 Node / CLI_TYPE 配置 / AI CLI（按 `CLI_TYPE` 检测 opencode 或 deveco）/ `.env` 凭据 / SKILL 目录 / 数据目录 / serve 服务连通性，缺什么会明确提示。除此之外还需要了解：
 
 - **Node.js** >= 22
-- **opencode CLI**：`3rdloop` 会自动拉起 `opencode serve`（在项目上一级目录运行），退出时清理进程树；已存在则复用，一般无需手动管理
+- **AI CLI**（默认 `deveco`，`CLI_TYPE` 可切 `opencode`）：`3rdloop` 会自动拉起对应的 `serve` 服务（在项目上一级目录运行），退出时清理进程树；已存在则复用，一般无需手动管理
 - **LLM 凭据**：`doctor` 提示凭据缺失时，见下面"配置"一节
 
 ### 场景二：配置 —— 需要注意哪些配置项
@@ -78,8 +78,9 @@ npm i -g @ohos-cpf/3rdloop
 # LLM 模型 id
 3rdloop config set LLM_MODEL glm-5.2
 
-# 默认 CLI 类型（opencode | deveco-code，HarmonyOS 场景切 deveco-code）
-3rdloop config set CLI_TYPE deveco-code
+# 默认 CLI 类型（默认 deveco-code；如需切回 opencode）
+# 切换后 doctor 按新类型检测，run/step/orch/workflow 拉起对应 serve 并连接
+3rdloop config set CLI_TYPE opencode
 
 # 数据存储目录（默认 ~/.3lib/3rdloop/db，如团队共享目录）
 3rdloop config set 3LIB_DATA_DIR "D:\code\team\shared-db"
@@ -106,6 +107,8 @@ npm i -g @ohos-cpf/3rdloop
 
 `run` 会自动完成"任务拆解 → 编排执行 → 准出审核"的完整大循环，多轮次自动重规划直到通过；退出码 `0` 即通过。
 
+> **环境预检**：`run`/`submit`/`step run`/`orch run|start` 及工作流在正式执行前会自动做环境预检（Node 版本 / CLI_TYPE / AI CLI / LLM 凭据 / SKILL 目录 / 数据目录）。任一项不通过直接退出码 `1`，并打印对应修复命令（如 `3rdloop config set DASHSCOPE_API_KEY <sk-xxx>`）；完整自检用 `3rdloop doctor`。`--print-taskdef` 等 dry-run 不预检。
+
 任务比较耗时、不想干等？提交后立即返回 taskId（进程内继续跑，需保持进程存活），之后可用 `3rdloop progress/wait/result <taskId>` 跟进：
 
 ```bash
@@ -134,41 +137,32 @@ npm i -g @ohos-cpf/3rdloop
 
 > 提 PR 是非幂等发布操作，失败不会自动重试；执行成功后报告 `ohos-lib-pr-push-report.md` 会自动复制到执行目录。先用 `--print-taskdef` dry-run 可以核对将执行的编排定义。
 
-### 场景五：用 Web 界面操作（serve / web）
-
-除了命令行，也可以在浏览器里使用 Web 工作台（提交任务 / 查看循环进度 / PR 检视等），由两个命令提供支撑：
+### 场景五：用 Web 界面操作（serve）
 
-**`3rdloop serve` —— 启动 Server HTTP 后端**（供前端 / 脚本反向代理调用）：
+除了命令行，也可以在浏览器里使用 Web 工作台（提交任务 / 查看循环进度 / PR 检视等）。`3rdloop serve` 一条命令**同时启动** Server HTTP 后端（默认 3000）与 Web 前端（默认 8080，静态托管 + `/api/*` 反代到后端 + 扩展挂载）：
 
 ```bash
-# 只启动后端（默认 http://127.0.0.1:3000，可用 --port / 3LIB_SERVER_PORT 覆盖）
+# 后端（默认 http://127.0.0.1:3000）+ Web 前端（默认 http://localhost:8080）同时启动
 3rdloop serve
 
-# 后端 + Web 前端一起拉起（前端默认 8080，可用 --web-port / 3LIB_WEB_PORT 覆盖）
-3rdloop serve --web
-```
-
-> CLI 的 `run`/`submit`/`wait` 等命令保持嵌入式模式，不经此后端；两者可独立使用。
+# 启动后自动打开浏览器
+3rdloop serve --open
 
-**`3rdloop web` —— 启动 Web 前端服务**（静态托管 + `/api/*` 反代到后端 + 扩展挂载，默认端口 8080）：
-
-```bash
-# 启动并自动打开浏览器（--backend 默认指向 http://127.0.0.1:3000，配合 serve 使用）
-3rdloop web --open
-
-# 自定义端口 / 后端地址
-3rdloop web --port 8081 --backend http://127.0.0.1:3000
+# 自定义端口（--port 后端 / --web-port 前端，也可用 3LIB_SERVER_PORT / 3LIB_WEB_PORT 覆盖）
+3rdloop serve --port 3001 --web-port 8081
 
 # 禁用全部扩展（纯核心工作台模式）
-3rdloop web --no-ext
+3rdloop serve --no-ext
 ```
 
+> CLI 的 `run`/`submit`/`wait` 等命令保持嵌入式模式，不经此后端。
+
 扩展机制（tag / issue / prcheck 等二级目录功能以扩展形式按需安装，不随 npm 包分发）：
 
 ```bash
-3rdloop web install-ext <扩展目录>   # 安装扩展到 ~/.3lib/3rdloop/web-ext/
-3rdloop web list-ext                 # 列出可用扩展（含来源与挂载点）
-3rdloop web remove-ext <扩展名>      # 移除已安装扩展
+3rdloop serve install-ext <扩展目录>   # 安装扩展到 ~/.3lib/3rdloop/web-ext/
+3rdloop serve list-ext                 # 列出可用扩展（含来源与挂载点）
+3rdloop serve remove-ext <扩展名>      # 移除已安装扩展
 ```
 
 更多进阶用法（任务管理、`step` 单步执行、`orch` 自定义编排、工作流注册等），见仓库 `cli/README_DEVELOP.md` 或 `3rdloop <子命令> --help`。
@@ -260,7 +254,6 @@ LLM 凭据变量（`DASHSCOPE_API_KEY` / `LLM_MODEL` 等）：按上文场景二
 3rdloop update --registry https://registry.npmjs.org/
 ```
 
-- 以 `npm link` 开发方式安装（连接到仓库源码）时，`update` 默认跳过并提示用 `git pull` 更新源码，加 `--force` 可强制替换为 registry 正式包
 - 更新只替换程序文件，**数据目录** `~/.3lib/3rdloop/db` **与** `~/.3lib/.env` **配置不受影响**
 
 

package/lib/cli.js

@@ -34,7 +34,6 @@ import {
     resolveSkillDir,
     generateTaskId,
     getCliVersion,
-    checkNodeVersion,
 } from './config.js';
 import { EXIT, TERMINAL_LOOP_STATES } from './exit-codes.js';
 
@@ -145,16 +144,16 @@ export async function runCli(argv) {
             return cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out });
 
         case 'serve':
-            return cmdServe({ flags, rest, jsonMode, dataDir });
+            return cmdServe({ flags, rest, jsonMode, dataDir, user3libHome });
 
         case 'update':
             return cmdUpdate({ flags, rest, jsonMode, out });
 
-        case 'web':
-            return cmdWeb({ flags, rest, user3libHome, dataDir, jsonMode, out });
-
         default:
             process.stderr.write(`未知命令: ${cmd}\n`);
+            if (cmd === 'web') {
+                process.stderr.write('提示: "3rdloop web" 已合并到 "3rdloop serve"（Web 前端随 serve 默认启动，扩展管理用 3rdloop serve install-ext/list-ext/remove-ext）\n');
+            }
             printHelp();
             return EXIT.ERROR;
     }
@@ -180,6 +179,19 @@ async function cmdDoctor({ projectRoot, skillDir, dataDir, quiet }) {
     return ok ? EXIT.OK : EXIT.ERROR;
 }
 
+/**
+ * 环境预检 + 失败报告（run/submit 等引擎命令共用）。
+ * 通过返回 true；失败打印各项修复提示（--json 时输出结构化结果）并返回 false。
+ */
+async function _precheckOrReport({ projectRoot, dataDir, skillDir, jsonMode, out }) {
+    const { precheckEnv, reportPrecheckFailures } = await import('./doctor.js');
+    const pre = await precheckEnv({ projectRoot, dataDir, skillDir });
+    if (pre.ok) return true;
+    if (jsonMode) out({ ok: false, error: '环境预检未通过', failures: pre.failures });
+    else reportPrecheckFailures(pre.failures);
+    return false;
+}
+
 // ─── workflows（列出已注册工作流） ────────────────────────────────
 
 async function cmdWorkflows({ jsonMode, out }) {
@@ -224,11 +236,11 @@ async function cmdUpdate({ flags, rest, jsonMode, out }) {
     return result.ok ? EXIT.OK : EXIT.ERROR;
 }
 
-// ─── serve（启动 Server HTTP 后端，供前端展示）─────────────────────────
+// ─── serve（同时启动 Server HTTP 后端 + Web 前端）─────────────────
 
-async function cmdServe({ flags, rest, jsonMode, dataDir }) {
+async function cmdServe({ flags, rest, jsonMode, dataDir, user3libHome }) {
     const { cmdServe: impl } = await import('./serve.js');
-    return impl({ rest: flags.rest, jsonMode, dataDir });
+    return impl({ rest: flags.rest, jsonMode, dataDir, user3libHome });
 }
 
 // ─── run / submit ──────────────────────────────────────────────────
@@ -267,6 +279,11 @@ async function submitAndRunImpl({ flags, rest, projectRoot, dataDir, skillDir, j
         return EXIT.ERROR;
     }
 
+    // ── 环境预检（引擎执行前快速失败：凭据/目录类问题直接退出码 1，
+    //    避免跑到一半才失败、被误报为任务失败退出码 2）──────────────────
+    const preOk = await _precheckOrReport({ projectRoot, dataDir, skillDir, jsonMode, out });
+    if (!preOk) return EXIT.ERROR;
+
     // skill-dir 可能来自全局 flags 已在外部解析
     const r = await runner();
     const taskId = generateTaskId();
@@ -274,20 +291,19 @@ async function submitAndRunImpl({ flags, rest, projectRoot, dataDir, skillDir, j
         projectRoot,
         dataDir,
         skillDir,
-        cliType: 'opencode',
         verbose,
     });
 
-    // 挂载 opencode 生命周期
-    const { OpencodeManager } = await import('./opencode.js');
-    const oc = new OpencodeManager({ projectRoot });
+    // 挂载 AI CLI serve 生命周期（类型由 CLI_TYPE 决定：opencode | deveco-code）
+    const { CliServeManager } = await import('./opencode.js');
+    const oc = new CliServeManager({ projectRoot, cliType: ctx.cliType });
     const ocHealth = await oc.ensureRunning();
     if (!ocHealth.ok) {
         if (jsonMode) {
             process.stdout.write(JSON.stringify({ ok: false, error: ocHealth.message, taskId }, null, 2) + '\n');
         }
         process.stderr.write(`\n错误: ${ocHealth.message}\n`);
-        process.stderr.write('请先启动 opencode serve（项目上一级目录: opencode serve）后重试。\n');
+        process.stderr.write(`请先启动 ${oc.cliType} serve（项目上一级目录: ${oc.bin} serve）后重试。\n`);
         await oc.stop();
         return EXIT.ERROR;
     }
@@ -623,14 +639,6 @@ async function cmdOrch({ flags, rest, projectRoot, dataDir, skillDir, jsonMode,
     return impl({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u });
 }
 
-/**
- * 3rdloop web 命令二段分发（转发到 lib/web.js：前端服务 + 扩展挂载）。
- */
-async function cmdWeb({ flags, rest, user3libHome, dataDir, jsonMode, out }) {
-    const { cmdWeb: impl } = await import('./web.js');
-    return impl({ flags, rest, user3libHome, dataDir, jsonMode, out });
-}
-
 // ─── 帮助 ─────────────────────────────────────────────────────────
 
 function printHelp() {
@@ -659,11 +667,11 @@ function printHelp() {
   3rdloop workflows                     列出已注册的固定编排工作流
   3rdloop run <工作流名> [--flag <值> ...]     以固定编排执行工作流（阻塞到终态）
   3rdloop config list|get|set|unset ...  配置 .env 配置项（默认读写 ~/.3lib/.env）
-  3rdloop serve [--port N] [-w|--web] [--web-port N]  启动 Server HTTP 后端（供前端展示）
-  3rdloop update [--check] [--yes] [--force] [--registry <url>]  自更新到 npm 最新版
-  3rdloop web [--port N] [--backend <url>]       启动 Web 前端服务
-  3rdloop web install-ext <dir>                  安装扩展（tag/issue/prcheck 等二级功能）
-  3rdloop web list-ext | remove-ext <name>       扩展管理
+  3rdloop serve [--port N] [--web-port N]  启动 Server 后端 + Web 前端（同时启动）
+         [--web-root <dir>] [--ext-root <dir>] [--ext <name,...>] [--no-ext] [--open]
+  3rdloop serve install-ext <dir>                安装扩展（tag/issue/prcheck 等二级功能）
+  3rdloop serve list-ext | remove-ext <name>     扩展管理
+  3rdloop update [--check] [--yes] [--registry <url>]  自更新到 npm 最新版
   3rdloop doctor                        环境自检
   3rdloop version                       版本信息
 
@@ -687,7 +695,6 @@ config 子命令:
 update 专用选项:
   --check          仅检查是否有新版本，不执行更新
   --yes, -y        跳过交互确认直接更新
-  --force          开发态（npm link）也强制替换为 registry 正式包
   --registry <url> 覆盖 npm registry（默认尊重用户 npm 镜像配置）
   注意: 数据目录 ~/.3lib/3rdloop/db 与 SKILL 配置不受更新影响
 

package/lib/config-cmd.js

@@ -90,7 +90,7 @@ export const ENV_KEYS = [
     { 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: 'CLI_TYPE', label: '默认 CLI 类型', description: 'opencode | deveco-code', default: 'deveco-code', 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 },

package/lib/config.js

@@ -7,6 +7,7 @@
  *   - 定位数据目录（--data-dir > 3LIB_DATA_DIR > ~/.3lib/3rdloop/db）
  *   - 生成 clinic 安全唯一 taskId（随机位 8）
  *   - SKILL 目录优先级链（--skill-dir > 3LIB_SKILL_DIR > vendor/Skills）
+ *   - 解析 AI CLI 类型（CLI_TYPE：opencode | deveco-code，默认 deveco-code）
  *
  * 数据目录策略：
  *   用户级统一 ~/.3lib/3rdloop/db（跨平台，由 getUser3libHome 解析），
@@ -204,6 +205,37 @@ export function getUser3libHome() {
     return path.join(home, '.3lib');
 }
 
+/** 支持的 AI CLI 类型 */
+const CLI_TYPES = ['opencode', 'deveco-code'];
+/** 默认 CLI 类型（本项目面向 HarmonyOS 三方库场景，默认 DevEco Code） */
+const DEFAULT_CLI_TYPE = 'deveco-code';
+let _warnedInvalidCliType = false;
+
+/**
+ * 解析当前生效的 AI CLI 类型（opencode | deveco-code）。
+ *
+ * 优先级：显式参数 > 环境变量 CLI_TYPE（含 loadEnvChain 注入的
+ * 系统环境变量 > ~/.3lib/.env > 项目 Server/.env 链）> 'deveco-code'（默认）。
+ * 与 Server/CLI/cli.js、check-env.mjs 的 resolveCliType 语义保持一致。
+ *
+ * CLI_TYPE 配了无效值时不崩溃：回退默认值并在 stderr 告警一次
+ * （doctor 会将其作为失败项显式报告）。
+ *
+ * @param {string} [override] - 显式类型（优先级最高）
+ * @returns {'opencode'|'deveco-code'}
+ */
+export function resolveCliType(override) {
+    const raw = String(override ?? process.env.CLI_TYPE ?? '').trim();
+    if (CLI_TYPES.includes(raw)) return raw;
+    if (raw && !_warnedInvalidCliType) {
+        _warnedInvalidCliType = true;
+        process.stderr.write(
+            `[3rdloop] 警告: CLI_TYPE="${raw}" 无效（可选值: ${CLI_TYPES.join(' | ')}），已回退 ${DEFAULT_CLI_TYPE}\n`
+        );
+    }
+    return DEFAULT_CLI_TYPE;
+}
+
 /**
  * 确定数据目录。
  *

package/lib/doctor.js

@@ -1,21 +1,31 @@
 /**
- * doctor.js —— 环境自检（3rdloop doctor）
+ * doctor.js —— 环境自检（3rdloop doctor）+ 引擎前置预检（precheckEnv）
  *
- * 复用 check-env.mjs 的检测维度（轻量版，不耦合启动流程）：
+ * 检查维度（doctor 与预检共用 collectChecks）：
  *   1. Node.js 版本（>=22）
- *   2. opencode 是否安装 + 服务是否运行
- *   3. .env 配置（项目 Server/.env 或用户 ~/.3lib/.env）
- *   4. 核心依赖是否可导入（vendor/Server）
+ *   2. CLI_TYPE 配置有效性（无效值视为配置错误）
+ *   3. AI CLI 可执行文件（按 CLI_TYPE 检测 opencode / deveco）
+ *   4. LLM 凭据（生效环境 DASHSCOPE_API_KEY；LLM_BASE_URL/LLM_MODEL 引擎有内置默认值，不强制）
  *   5. Skill 目录可访问
- *   6. opencode 端口连通性
+ *   6. 数据目录可写
+ *   7. serve 服务端口连通性（非致命：未运行时 run/orch/step/workflow 会自动拉起；
+ *      端口有响应但异常视为失败）
  *
- * 退出码：全部通过 = 0；存在致命问题 = 1。
+ * 每项检查含 fix 字段：不通过时的修复提示（含 3rdloop config set 命令），
+ * doctor 与预检失败时均打印，用户照抄即可配置。
+ *
+ * precheckEnv：run/submit/step run/orch run|start/工作流正式执行前调用，
+ * 任一项不通过直接退出码 1（避免跑到一半才因环境问题失败、误报为任务失败退出码 2）。
+ *
+ * 退出码：doctor 全部通过 = 0；存在致命问题 = 1。
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
-import { C, logLine } from './ui.js';
+import { C } from './ui.js';
+import { resolveCliType } from './config.js';
+import { resolveCliServeConfig } from './opencode.js';
 
 /**
  * 检查命令是否在 PATH 中。
@@ -31,17 +41,37 @@ function which(cmd) {
 }
 
 /**
- * 执行环境自检。
- *
+ * 探测 serve 服务 HTTP /health（2s 超时）。
+ * @param {string} baseUrl
+ * @returns {Promise<{ state: 'running'|'down'|'error', detail: string }>}
+ *   running = 服务正常；down = 未运行（执行命令时会自动拉起，非致命）；
+ *   error = 端口有响应但异常（可能是残留的坏进程，视为致命）
+ */
+async function probeServe(baseUrl) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 2000);
+        const res = await fetch(`${baseUrl}/health`, { signal: controller.signal });
+        clearTimeout(timer);
+        return res.ok
+            ? { state: 'running', detail: `运行中 (${baseUrl})` }
+            : { state: 'error', detail: `响应异常 HTTP ${res.status} (${baseUrl})，可能是残留的异常进程` };
+    } catch {
+        return { state: 'down', detail: `未运行 (${baseUrl})——执行 run/orch/step/workflow 时会自动拉起` };
+    }
+}
+
+/**
+ * 收集全部检查项（doctor 与 precheckEnv 共用）。
+ * 每项：{ name, passed, detail, fix }——fix 为不通过时的修复提示。
  * @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}> }>}
+ * @returns {Promise<Array<{name: string, passed: boolean, detail?: string, fix?: string}>>}
  */
-export async function runDoctor(opts = {}) {
+async function collectChecks({ projectRoot, skillDir, dataDir }) {
     const checks = [];
-    const { projectRoot, skillDir, dataDir } = opts;
 
     // 1. Node.js 版本
     const nodeMajor = Number(process.version.match(/^v(\d+)/)?.[1] || 0);
@@ -49,66 +79,153 @@ export async function runDoctor(opts = {}) {
         name: 'Node.js >= 22',
         passed: nodeMajor >= 22,
         detail: process.version,
+        fix: '请升级 Node.js 至 v22+ 后重试（https://nodejs.org）',
     });
 
-    // 2. opencode 可执行文件
-    const opencodeBin = which('opencode');
+    // 2. CLI_TYPE 配置有效性（解析回退发生在 resolveCliType，这里负责显式报告）
+    const rawCliType = String(process.env.CLI_TYPE ?? '').trim();
+    const cliType = resolveCliType();
+    const cliCfg = resolveCliServeConfig(cliType);
+    if (!rawCliType) {
+        checks.push({
+            name: 'CLI_TYPE 配置',
+            passed: true,
+            detail: '未设置（默认 deveco-code；如需 opencode 可 3rdloop config set CLI_TYPE opencode）',
+        });
+    } else if (rawCliType === cliType) {
+        checks.push({ name: 'CLI_TYPE 配置', passed: true, detail: rawCliType });
+    } else {
+        checks.push({
+            name: 'CLI_TYPE 配置',
+            passed: false,
+            detail: `"${rawCliType}" 无效，可选值: opencode | deveco-code（当前回退 ${cliType}）`,
+            fix: '3rdloop config set CLI_TYPE opencode（可选: opencode | deveco-code），或 3rdloop config unset CLI_TYPE 恢复默认',
+        });
+    }
+
+    // 3. AI CLI 可执行文件（按 CLI_TYPE 检测对应二进制）
+    const cliBin = which(cliCfg.bin);
+    const installHint = cliType === 'deveco-code'
+        ? '未找到，请 npm i -g @deveco/deveco-code（首次需 deveco auth login）'
+        : '未找到，请 npm i -g opencode-ai';
     checks.push({
-        name: 'opencode CLI',
-        passed: !!opencodeBin,
-        detail: opencodeBin || '未找到，请 npm i -g opencode-ai',
+        name: `${cliType} CLI`,
+        passed: !!cliBin,
+        detail: cliBin || installHint,
+        fix: cliType === 'deveco-code'
+            ? 'npm i -g @deveco/deveco-code（安装后首次使用需 deveco auth login）'
+            : '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. LLM 凭据（生效环境检测：loadEnvChain 已注入 系统环境变量 > ~/.3lib/.env > 项目 Server/.env，
+    //    任一层配置即生效。仅强制 DASHSCOPE_API_KEY——LLM_BASE_URL/LLM_MODEL 引擎有内置默认值）
+    const apiKey = String(process.env.DASHSCOPE_API_KEY ?? '').trim();
+    checks.push({
+        name: 'LLM 凭据（DASHSCOPE_API_KEY）',
+        passed: !!apiKey,
+        detail: apiKey
+            ? '已配置（系统环境变量 / ~/.3lib/.env / 项目 Server/.env 任一层）'
+            : '未配置（系统环境变量 / ~/.3lib/.env / 项目 Server/.env 均未设置，LLM 调用将失败）',
+        fix: '3rdloop config set DASHSCOPE_API_KEY <sk-xxxxxxxx>（从 https://bailian.console.aliyun.com/ 获取）',
+    });
 
-    // 4. Skill 目录可访问
+    // 5. Skill 目录可访问
     const skillOk = skillDir && fs.existsSync(skillDir);
     checks.push({
         name: 'SKILL 目录',
         passed: !!skillOk,
-        detail: skillOk ? skillDir : 'SKILL 目录不存在',
+        detail: skillOk ? skillDir : `SKILL 目录不存在: ${skillDir}`,
+        fix: '3rdloop config set 3LIB_SKILL_DIR <SKILL 目录>；发布包缺 SKILL 请重装: npm i -g @ohos-cpf/3rdloop',
     });
 
-    // 5. 数据目录可写
+    // 6. 数据目录可写
     let dataOk = false;
     try {
         fs.mkdirSync(dataDir, { recursive: true });
         dataOk = true;
     } catch { /* 不可写 */ }
-    checks.push({ name: '数据目录', passed: dataOk, detail: dataDir });
+    checks.push({
+        name: '数据目录',
+        passed: dataOk,
+        detail: dataOk ? dataDir : `不可写: ${dataDir}`,
+        fix: '3rdloop config set 3LIB_DATA_DIR <可写目录>，或运行时加 --data-dir <p>',
+    });
+
+    // 7. serve 服务端口连通性（未运行不算失败：执行命令时会自动拉起；
+    //    端口有响应但异常则视为失败，提示清理残留进程）
+    const serve = await probeServe(`http://${cliCfg.host}:${cliCfg.port}`);
+    checks.push({
+        name: `${cliType} serve 服务`,
+        passed: serve.state !== 'error',
+        detail: serve.detail,
+        fix: `端口 ${cliCfg.port} 被异常进程占用，请清理后重试（lsof -i :${cliCfg.port} 定位 / 任务管理器结束进程）`,
+    });
+
+    return checks;
+}
+
+/**
+ * 执行环境自检（3rdloop doctor 命令实现）。
+ *
+ * @param {object} opts
+ * @param {string} opts.projectRoot
+ * @param {string} opts.skillDir
+ * @param {string} opts.dataDir
+ * @param {boolean} [opts.quiet] - 静默模式（不打印表格，仅返回结果）
+ * @returns {Promise<{ ok: boolean, checks: Array<{name: string, passed: boolean, detail?: string, fix?: string}> }>}
+ */
+export async function runDoctor(opts = {}) {
+    const checks = await collectChecks(opts);
 
     // 汇总
     const ok = checks.every(c => c.passed);
 
-    // 打印
+    // 打印（失败项附加修复提示）
     if (!opts.quiet) {
-        process.stderr.write(`\n${C.bold}3rdloop doctor 环境自检${C.reset}\n`);
+        process.stderr.write(`\n${C.bold}3rdloop doctor 环境自检${C.reset}${C.gray}（AI CLI: ${resolveCliType()}）${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');
+            if (!c.passed && c.fix) {
+                process.stderr.write(`      ${C.cyan}修复: ${c.fix}${C.reset}\n`);
+            }
         }
     }
 
     return { ok, checks };
-}
+}
+
+/**
+ * 引擎前置预检（run/submit/step run/orch run|start/工作流正式执行前调用）。
+ *
+ * 与 doctor 同一检查集，语义差异：
+ *   - serve 未运行不算失败（执行命令时会自动拉起；端口异常仍算失败）
+ *   - 轻量：仅文件/PATH/端口探测，不拉起任何进程、不触引擎
+ *
+ * @param {object} opts - { projectRoot, skillDir, dataDir }（与 runDoctor 相同）
+ * @returns {Promise<{ ok: boolean, failures: Array<{name: string, detail?: string, fix?: string}> }>}
+ */
+export async function precheckEnv(opts = {}) {
+    const checks = await collectChecks(opts);
+    const failures = checks
+        .filter(c => !c.passed)
+        .map(({ name, detail, fix }) => ({ name, detail, fix }));
+    return { ok: failures.length === 0, failures };
+}
+
+/**
+ * 预检失败信息打印（stderr，供 cli/workflow/step/orch 共用；--json 模式下调用方自行 out()）。
+ * @param {Array<{name: string, detail?: string, fix?: string}>} failures
+ */
+export function reportPrecheckFailures(failures) {
+    process.stderr.write(`\n环境预检未通过（${failures.length} 项），已阻止任务执行:\n`);
+    for (const f of failures) {
+        process.stderr.write(`  ${C.red}✗${C.reset} ${f.name}${f.detail ? `  ${C.gray}${f.detail}${C.reset}` : ''}\n`);
+        if (f.fix) {
+            process.stderr.write(`      ${C.cyan}修复: ${f.fix}${C.reset}\n`);
+        }
+    }
+    process.stderr.write('完整环境自检: 3rdloop doctor\n');
+}