@ohos-cpf/3rdloop 0.0.3 → 0.0.5

package/README.md

@@ -34,73 +34,145 @@ npm i -g @ohos-cpf/3rdloop
 
 ## 使用
 
+按使用场景组织：装好之后，先做**环境自检**并完成**必要配置**，然后**快速开启一个任务**；进阶场景（PR 检视/自动提 PR、Web 界面、自更新）按需查阅。
 
+### 场景一：初次使用 —— 环境自检
 
-### 前置条件
+安装后第一步，先跑环境自检：
+
+```bash
+3rdloop doctor
+```
+
+`doctor` 会逐项检查 Node / opencode / `.env` 凭据 / SKILL 目录 / 数据目录，缺什么会明确提示。除此之外还需要了解：
 
 - **Node.js** >= 22
-- **opencode CLI**：`3rdloop` 会自动拉起 `opencode serve`（在项目上一级目录运行），退出时清理进程树；已存在则复用
-- **LLM 凭据**：以下任一层配置即可
-  - 项目级：仓库 `Server/.env`
-  - 用户级：`~/.3lib/.env`
-  - 系统环境变量：`setx DASHSCOPE_API_KEY "sk-xxx"`
+- **opencode CLI**：`3rdloop` 会自动拉起 `opencode serve`（在项目上一级目录运行），退出时清理进程树；已存在则复用，一般无需手动管理
+- **LLM 凭据**：`doctor` 提示凭据缺失时，见下面"配置"一节
 
+### 场景二：配置 —— 需要注意哪些配置项
 
+绝大多数配置项都有内置默认值，**开箱即用**。只有 LLM 凭据是必配项：
 
-### 快速开始
+```bash
+# 必配：百炼 API Key（从 https://bailian.console.aliyun.com/ 获取，get/list 脱敏显示）
+3rdloop config set DASHSCOPE_API_KEY <sk-xxxxxxxx>
+```
+
+按需可选（不设置即关闭/自动）：
 
 ```bash
-# 环境自检
-3rdloop doctor
+# GitCode Token（仅访问私有仓库时需要，get/list 脱敏显示）
+3rdloop config set GIT_TOKEN <your-gitcode-token>
+
+# SKILL 目录覆盖（等效 --skill-dir，不设置则自动解析）
+3rdloop config set 3LIB_SKILL_DIR </path/to/Skills>
+```
+
+有默认值、一般无需改（调整时参考）：
+
+```bash
+# LLM 端点（默认百炼 OpenAI 兼容端点，仅切换其他 LLM 服务时修改）
+3rdloop config set LLM_BASE_URL https://dashscope.aliyuncs.com/compatible-mode/v1
+
+# LLM 模型 id
+3rdloop config set LLM_MODEL glm-5.2
+
+# 默认 CLI 类型（opencode | deveco-code，HarmonyOS 场景切 deveco-code）
+3rdloop config set CLI_TYPE deveco-code
+
+# 数据存储目录（默认 ~/.3lib/3rdloop/db，如团队共享目录）
+3rdloop config set 3LIB_DATA_DIR "D:\code\team\shared-db"
+```
+
+> 其余配置项（`LLM_MAX_TOKENS` / `LLM_ENABLE_THINKING` / `SELECTOR_*` / `MAX_CONCURRENT_SESSIONS` / `OPENCODE_*` / `DEVECO_*`）均有内置默认值，完整清单执行 `3rdloop config list` 查看。`3LIB_ROOT` / `3LIB_HOME` 仅支持系统环境变量（`export` / `setx`），`config set` 会拒绝写入。
 
-# 提交并阻塞到准出终态（最常用）
+配置完成后统一验证：
+
+```bash
+3rdloop config list      # 查看全部配置项及当前生效值
+3rdloop doctor           # 环境自检
+```
+
+凭据也可以不通过 `config` 配置，任选一层即可：系统环境变量（`setx DASHSCOPE_API_KEY "sk-xxx"`）、用户级 `~/.3lib/.env`、项目根 `Server/.env`。
+
+### 场景三：快速开启一个任务
+
+在目标三方库仓库目录下，一句话描述任务，提交并阻塞到准出终态（**最常用**）：
+
+```bash
 3rdloop run "为 libcurl 生成鸿蒙 demo 场景并跑通编译"
+```
+
+`run` 会自动完成"任务拆解 → 编排执行 → 准出审核"的完整大循环，多轮次自动重规划直到通过；退出码 `0` 即通过。
 
-# 提交并立即返回 taskId（进程内继续跑，需保持进程存活）
+任务比较耗时、不想干等？提交后立即返回 taskId（进程内继续跑，需保持进程存活），之后可用 `3rdloop progress/wait/result <taskId>` 跟进：
+
+```bash
 3rdloop submit "分析 sqlite3 的鸿蒙化可行性"
+```
+
+### 场景四：跑预置工作流（PR 检视 / 自动提 PR 等）
+
+常用固定流程已封装为一键工作流，先看有哪些：
+
+```bash
+3rdloop workflows                # 列出已注册的固定编排工作流
+3rdloop run <工作流名> --help     # 查看某个工作流的参数说明
+```
+
+**三方库自动提 PR**（fork 工作区修改 → 源仓库 Issue/PR + 触发 CI）：
 
-# 等待到终态 / 查询进度 / 中止 / 列表 / 结果
-3rdloop wait <taskId> --timeout 30m
-3rdloop progress <taskId> --watch
-3rdloop abort <taskId>
-3rdloop list --status running
-3rdloop result <taskId> --json
+```bash
+# 最常用：在 fork 仓库克隆目录下直接执行（workspace-dir 缺省取当前目录）
+3rdloop run pr-push
+
+# 显式指定工作区与可选参数
+3rdloop run pr-push --workspace-dir D:\work\fork-repo --upstream-url https://gitcode.com/CPF-RN/lib \
+  --changelog auto --dry-run false
+```
+
+> 提 PR 是非幂等发布操作，失败不会自动重试；执行成功后报告 `ohos-lib-pr-push-report.md` 会自动复制到执行目录。先用 `--print-taskdef` dry-run 可以核对将执行的编排定义。
+
+### 场景五：用 Web 界面操作（serve / web）
+
+除了命令行，也可以在浏览器里使用 Web 工作台（提交任务 / 查看循环进度 / PR 检视等），由两个命令提供支撑：
+
+**`3rdloop serve` —— 启动 Server HTTP 后端**（供前端 / 脚本反向代理调用）：
+
+```bash
+# 只启动后端（默认 http://127.0.0.1:3000，可用 --port / 3LIB_SERVER_PORT 覆盖）
+3rdloop serve
+
+# 后端 + Web 前端一起拉起（前端默认 8080，可用 --web-port / 3LIB_WEB_PORT 覆盖）
+3rdloop serve --web
 ```
 
+> CLI 的 `run`/`submit`/`wait` 等命令保持嵌入式模式，不经此后端；两者可独立使用。
+
+**`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
+
+# 禁用全部扩展（纯核心工作台模式）
+3rdloop web --no-ext
+```
+
+扩展机制（tag / issue / prcheck 等二级目录功能以扩展形式按需安装，不随 npm 包分发）：
+
+```bash
+3rdloop web install-ext <扩展目录>   # 安装扩展到 ~/.3lib/3rdloop/web-ext/
+3rdloop web list-ext                 # 列出可用扩展（含来源与挂载点）
+3rdloop web remove-ext <扩展名>      # 移除已安装扩展
+```
 
+更多进阶用法（任务管理、`step` 单步执行、`orch` 自定义编排、工作流注册等），见仓库 `cli/README_DEVELOP.md` 或 `3rdloop <子命令> --help`。
 
-### 命令一览
-
-
-| 命令                                                                                                                                                         | 说明                                           |
-| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
-| `3rdloop run <desc>`                                                                                                                                       | 提交任务并阻塞到准出终态（默认行为）                           |
-| `3rdloop submit <desc>`                                                                                                                                    | 提交任务，打印 taskId 后进程内继续执行                      |
-| `3rdloop wait <taskId> [--timeout 30m]`                                                                                                                    | 等待任务到终态                                      |
-| `3rdloop progress <taskId> [--watch]`                                                                                                                      | 查询进度；`--watch` 持续轮询到终态                       |
-| `3rdloop abort <taskId>`                                                                                                                                   | 中止任务                                         |
-| `3rdloop list [--status st] [--limit N] [--older-than 7d]`                                                                                                 | 列出任务                                         |
-| `3rdloop result <taskId> [--raw]`                                                                                                                          | 读取最终结果                                       |
-| `3rdloop step run <desc> [--task-id id] [--step-id N] [--input-report p] [--max-retries N] [--loop N] [--task-dir p] [--specified-skill <SKILL name|目录名>]` | 单步执行（FlexRunner 直连，不经拆解/编排/审核）               |
-| `3rdloop step status <taskId> [--step-id N]`                                                                                                               | 查询单步状态/产物/会话                                 |
-| `3rdloop step result <taskId> [--step-id N]`                                                                                                               | 读取该步 result.md 内容                            |
-| `3rdloop orch run <task-def.json>`                                                                                                                         | 加载任务定义 + 启动编排，阻塞到终态                          |
-| `3rdloop orch load <task-def.json>`                                                                                                                        | 仅加载任务定义（落盘 orchestration.json，进程退出后仍可 start） |
-| `3rdloop orch start <taskId>`                                                                                                                              | 从磁盘恢复 LOADED 状态并启动编排，阻塞到终态                   |
-| `3rdloop orch progress <taskId> [--loop N]`                                                                                                                | 查询编排进度                                       |
-| `3rdloop orch abort|pause|resume <taskId>`                                                                                                                 | 终止/暂停/恢复编排                                   |
-| `3rdloop orch tasks`                                                                                                                                       | 列出编排任务                                       |
-| `3rdloop workflows`                                                                                                                                        | 列出已注册的固定编排工作流                                |
-| `3rdloop run <工作流名> [--flag <值> ...]`                                                                                                                      | 以固定编排执行工作流（阻塞到终态）                            |
-| `3rdloop run pr-check --pr-url <URL> [--library-type <arkts|flutter|rn|tpccplus>]`                                                                         | PR 代码检视                                      |
-| `3rdloop run pr-push [--workspace-dir <p>] [--upstream-url <URL>] [--base-branch <b>] [--changelog <auto|true|false>] [--dry-run <true|false>]`            | 三方库自动提 PR（fork 工作区修改 → 源仓库 Issue/PR + 触发 CI） |
-| `3rdloop config list|get|set|unset`                                                                                                                        | 命令配置 `.env` 配置项（默认读写 `~/.3lib/.env`）         |
-| `3rdloop update [--check] [--yes] [--force] [--registry <url>]`                                                                                            | 自更新到 npm 最新版（尊重用户镜像源）                        |
-| `3rdloop doctor`                                                                                                                                           | 环境自检（Node/opencode/.env/SKILL/数据目录）          |
-| `3rdloop version`                                                                                                                                          | 版本信息                                         |
-
-
-更多进阶用法（`step` 参数细节、`orch` 任务定义格式、工作流注册），见仓库 `cli/README_DEVELOP.md` 或 `3rdloop <子命令> --help`。
 
 ### 退出码
 
@@ -119,7 +191,7 @@ npm i -g @ohos-cpf/3rdloop
 
 ## 配置
 
-
+> 快速上手需要的配置（LLM 凭据等）见上文 [场景二：配置](#场景二配置--需要注意哪些配置项)。本节补充完整的配置参考：数据目录与环境变量清单。
 
 ### 数据目录（中间产物）
 
@@ -136,7 +208,6 @@ npm i -g @ohos-cpf/3rdloop
 
 CLI 自身配置（`3LIB_*` 前缀）：
 
-
 | 变量                 | 作用                                | 默认值                  |
 | ------------------ | --------------------------------- | -------------------- |
 | `3LIB_DATA_DIR`    | 数据目录覆盖（等效 `--data-dir`）           | `~/.3lib/3rdloop/db` |
@@ -145,41 +216,7 @@ CLI 自身配置（`3LIB_*` 前缀）：
 | `3LIB_SKILL_DIR`   | SKILL 目录覆盖（等效 `--skill-dir`）      | 默认按发布/开发状态自动解析       |
 | `3LIB_TASK_PREFIX` | taskId 前缀（审计用）                    | 空                    |
 
-
-LLM 凭据变量（`DASHSCOPE_API_KEY` / `LLM_MODEL` 等）：按上面的 `.env` 加载链任选一层配置即可。
-
-### 命令行配置（3rdloop config）
-
-`config` 子命令对 `.env` 配置项做命令式管理，默认读写用户级 `~/.3lib/.env`（跨项目全局生效），无需手改 `.env` 文件：
-
-```bash
-# 查看当前生效的数据目录
-3rdloop config get 3LIB_DATA_DIR
-
-# 将任务产物统一存到团队共享目录（全局生效，无需每次带 --data-dir）
-3rdloop config set 3LIB_DATA_DIR "D:\code\team\shared-db"
-
-# 查看全部配置项及当前生效值（密钥类脱敏）
-3rdloop config list
-
-# 恢复默认
-3rdloop config unset 3LIB_DATA_DIR
-```
-
-- 读取优先级：**系统环境变量 >** `~/.3lib/.env`**（用户级） > 项目根** `Server/.env` **> 内置默认值**
-- `config` 内置白名单与值校验，未知键 `set` 会报错；`DASHSCOPE_API_KEY` / `GIT_TOKEN` 等密钥在 `get`/`list` 中脱敏显示
-- `3LIB_ROOT` / `3LIB_HOME` 为系统环境变量专用，`config set` 会拒绝，请用 `setx` / `export`
-- `--data-dir` / `--skill-dir` 命令行 flag 仍是最高的单次覆盖
-
-
-
-### 环境加载细节
-
-- `.env` **加载链**：系统环境变量 > `~/.3lib/.env` > 项目根 `Server/.env`
-- **opencode**：自动拉起 `opencode serve`（项目上一级目录），退出时清理进程树；已存在则复用
-- **任务数据隔离**：CLI 任务数据默认与 Web 前端（读取仓库根 `db/`）分离，CLI 提交的任务不会出现在前端任务列表
-
-
+LLM 凭据变量（`DASHSCOPE_API_KEY` / `LLM_MODEL` 等）：按上文场景二所述，系统环境变量 / `~/.3lib/.env` / 项目根 `Server/.env` 任选一层配置即可。
 
 ## API
 
@@ -238,7 +275,7 @@ LLM 凭据变量（`DASHSCOPE_API_KEY` / `LLM_MODEL` 等）：按上面的 `.env
 
 ## 维护者
 
-[@junxiaoliu927](https://gitcode.com/Sincerelyurs/3rdLibraryLoop)
+[@lalhan](https://gitcode.com/lalhanorz)  [@junxiaoliu927](https://gitcode.com/Sincerelyurs)
 
 ## 许可证
 

package/lib/cli.js

@@ -144,9 +144,15 @@ export async function runCli(argv) {
         case 'config':
             return cmdConfig({ flags, rest, projectRoot, user3libHome, jsonMode, out });
 
+        case 'serve':
+            return cmdServe({ flags, rest, jsonMode });
+
         case 'update':
             return cmdUpdate({ flags, rest, jsonMode, out });
 
+        case 'web':
+            return cmdWeb({ flags, rest, user3libHome, dataDir, jsonMode, out });
+
         default:
             process.stderr.write(`未知命令: ${cmd}\n`);
             printHelp();
@@ -218,6 +224,13 @@ async function cmdUpdate({ flags, rest, jsonMode, out }) {
     return result.ok ? EXIT.OK : EXIT.ERROR;
 }
 
+// ─── serve（启动 Server HTTP 后端，供前端展示）─────────────────────────
+
+async function cmdServe({ flags, rest, jsonMode }) {
+    const { cmdServe: impl } = await import('./serve.js');
+    return impl({ rest: flags.rest, jsonMode });
+}
+
 // ─── run / submit ──────────────────────────────────────────────────
 
 async function cmdRun({ flags, rest, projectRoot, dataDir, skillDir, jsonMode, quiet, verbose, out, u }) {
@@ -610,6 +623,14 @@ 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() {
@@ -638,7 +659,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 doctor                        环境自检
   3rdloop version                       版本信息
 

package/lib/config-cmd.js

@@ -73,7 +73,7 @@ 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_MODEL', label: '模型名', description: '经百炼调用的模型名（如 glm-5.2）', default: 'glm-5.2', 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 },

package/lib/serve.js

@@ -0,0 +1,268 @@
+/**
+ * serve.js —— 3rdloop serve 启动 Server HTTP 后端
+ *
+ * 定位：为前端展示启动现成 Server 后端（复用 Server/Routes/server.js 的
+ * createServer，不新增任何 daemon/调度逻辑）。CLI 其余命令仍为嵌入式，不受影响。
+ *
+ * 行为：
+ *   - 默认仅启动 HTTP 后端（--port / 3LIB_SERVER_PORT / 3000）
+ *   - -w/--web 可选：再拉起 Web/server.js 静态前端（反向代理 /api/* 到后端）
+ *   - 复用 CLI 的环境装配（cli.js 已统一执行 .env 链 + stdout 保护），
+ *     与 run/submit 等命令保持一致；json 模式下本模块自行纯化 stdout
+ *   - 端口冲突 / 启动失败给出明确错误，不静默
+ */
+
+import { spawn, execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import process from 'node:process';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+export const CLI_ROOT = path.resolve(moduleDir, '..');
+
+// ─── vendor/Server 路径解析（与 runner.js 保持一致）────────────────
+let _serverModuleRoot = null;
+function resolveVendorServer(cliRoot) {
+    if (_serverModuleRoot) return _serverModuleRoot;
+
+    const vendorServer = path.join(cliRoot, 'vendor', 'Server');
+    if (fs.existsSync(vendorServer)) {
+        _serverModuleRoot = vendorServer;
+        return vendorServer;
+    }
+    const repoServer = path.resolve(cliRoot, '..', 'Server');
+    if (fs.existsSync(repoServer)) {
+        _serverModuleRoot = repoServer;
+        return repoServer;
+    }
+    throw new Error(
+        `无法定位核心引擎目录：期望 cli/vendor/Server 或仓库 Server/。` +
+        `请先运行 npm run prepack（或 clone 仓库到 cli/ 的上一级）`
+    );
+}
+
+/** 动态导入 Server/Routes/server.js（一手段：vendor 优先、开发期回退仓库源码）。 */
+async function _importServerModule() {
+    const serverRoot = resolveVendorServer(CLI_ROOT);
+    const url = new URL(`file://${path.join(serverRoot, 'Routes', 'server.js').replace(/\\/g, '/')}`);
+    return import(url.href);
+}
+
+/** Web 静态前端目录（开发期仓库 Web/；发布期 vendor/Web 预留）。 */
+function resolveWebDir() {
+    const candidates = [
+        path.resolve(CLI_ROOT, '..', 'Web'),
+        path.join(CLI_ROOT, 'vendor', 'Web'),
+    ];
+    for (const dir of candidates) {
+        if (fs.existsSync(path.join(dir, 'server.js')) && fs.existsSync(path.join(dir, 'public'))) {
+            return dir;
+        }
+    }
+    return null;
+}
+
+/**
+ * 解析 flags.rest 中 serve 专用参数（不依赖 cli.js 的 parseGlobalFlags，
+ * 因为 -w/--web 会被它归入 rest）。
+ * @returns {{ web: boolean, port?: number, webPort?: number }}
+ */
+function _parseServeArgs(rest = []) {
+    const args = { web: false };
+    for (let i = 0; i < rest.length; i++) {
+        const arg = rest[i];
+        if (arg === '-w' || arg === '--web') args.web = true;
+        else if (arg === '--port' || arg === '--web-port') {
+            const key = arg === '--port' ? 'port' : 'webPort';
+            const n = parseInt(rest[i + 1], 10);
+            if (Number.isFinite(n) && n > 0) args[key] = n;
+            i++; // 跳过值
+        }
+    }
+    return args;
+}
+
+/**
+ * 3rdloop serve 命令实现。
+ * @param {object} opts
+ * @param {string[]} opts.rest - flags.rest（含 serve 专用参数）
+ * @param {boolean} opts.jsonMode
+ * @returns {Promise<number>} 退出码（serve 为长驻命令，仅 --help/启动失败正常返回）
+ */
+export async function cmdServe({ rest = [], jsonMode = false }) {
+    // --help / -h：打印用法
+    if (rest.includes('--help') || rest.includes('-h')) {
+        _printServeHelp();
+        return 0;
+    }
+
+    const args = _parseServeArgs(rest);
+    const serverPort = args.port ?? _envInt('3LIB_SERVER_PORT', 3000);
+    const webPort = args.webPort ?? _envInt('3LIB_WEB_PORT', 8080);
+
+    if (args.web && serverPort === webPort) {
+        process.stderr.write(`3rdloop serve: 后端端口与 Web 端口相同 (${serverPort})，请用 --web-port 指定不同端口\n`);
+        return 1;
+    }
+
+    const serverModule = await _importServerModule();
+
+    // json 模式下纯化 stdout：Server 内部 console.log/info 重定向到 stderr
+    let restoreStdout = null;
+    if (jsonMode) {
+        restoreStdout = _redirectStdoutLogs();
+    }
+
+    let webChild = null;
+
+    // 优雅退出：清理 Web 子进程（Windows taskkill 树）后退出
+    const cleanup = () => {
+        if (webChild && webChild.pid != null) {
+            try {
+                if (process.platform === 'win32') {
+                    execSync(`taskkill /pid ${webChild.pid} /T /F`, { stdio: 'ignore' });
+                } else {
+                    webChild.kill('SIGTERM');
+                }
+            } catch { /* 进程可能已退出 */ }
+            webChild = null;
+        }
+    };
+    let shuttingDown = false;
+    const onSignal = (sig) => {
+        if (shuttingDown) return;
+        shuttingDown = true;
+        cleanup();
+        process.exit(sig === 'SIGINT' ? 130 : 143);
+    };
+    process.once('SIGINT', () => onSignal('SIGINT'));
+    process.once('SIGTERM', () => onSignal('SIGTERM'));
+
+    try {
+        // cliType 由环境决定（shell > .env > 默认 opencode），与 CLI 嵌入式一致；
+        // dataDir/skillDir 沿用 Server 默认（workspace 根 db/），本期不与 CLI 打通
+        const server = await serverModule.createServer({ port: serverPort });
+
+        if (jsonMode) {
+            process.stdout.write(JSON.stringify({
+                ok: true,
+                type: 'server',
+                pid: process.pid,
+                port: serverPort,
+                url: `http://127.0.0.1:${serverPort}`,
+                web: args.web ? { port: webPort, url: `http://localhost:${webPort}` } : null,
+            }, null, 2) + '\n');
+        } else {
+            process.stderr.write(`[3rdloop serve] Server HTTP 后端已启动: http://127.0.0.1:${serverPort}\n`);
+            process.stderr.write(`[3rdloop serve] 通过 Ctrl+C 停止\n`);
+        }
+
+        // ── 可选启动 Web 前端（默认不拉起，保持聚焦后端） ──
+        if (args.web) {
+            await _startWebFrontend(webPort, serverPort, jsonMode, (child) => { webChild = child; });
+        }
+
+        // 长驻：保持进程存活直到收到信号
+        await new Promise(() => {});
+        return 0;
+    } catch (err) {
+        process.stderr.write(`3rdloop serve 启动失败: ${err.message}\n`);
+        return 1;
+    } finally {
+        restoreStdout?.();
+    }
+}
+
+/** 启动 Web 静态前端（反向代理 /api/* → 后端）。 */
+async function _startWebFrontend(webPort, serverPort, jsonMode, onChild) {
+    try {
+        if (await _isPortOpen(webPort)) {
+            process.stderr.write(`[3rdloop serve] Web 端口 ${webPort} 已被占用，跳过拉起前端（可直接访问该地址）\n`);
+            return;
+        }
+    } catch { /* 探测失败不阻断 */ }
+
+    const webDir = resolveWebDir();
+    if (!webDir) {
+        process.stderr.write('[3rdloop serve] 未找到 Web/ 前端目录，跳过拉起前端\n');
+        return;
+    }
+
+    const child = spawn(process.execPath, [
+        path.join(webDir, 'server.js'),
+        '--port', String(webPort),
+        '--backend', `http://127.0.0.1:${serverPort}`,
+    ], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        shell: false,
+        detached: false,
+    });
+    child.stdout?.on('data', (d) => process.stderr.write(`[web] ${d}`));
+    child.stderr?.on('data', (d) => process.stderr.write(`[web] ${d}`));
+    child.on('error', (err) => {
+        process.stderr.write(`[3rdloop serve] 拉起 Web 前端失败: ${err.message}\n`);
+    });
+    onChild(child);
+    if (!jsonMode) {
+        process.stderr.write(`[3rdloop serve] Web 前端已启动: http://localhost:${webPort}\n`);
+    }
+}
+
+/** 读取正整数环境变量（非法/缺席返回默认值）。 */
+function _envInt(name, def) {
+    const n = parseInt(process.env[name], 10);
+    return Number.isFinite(n) && n > 0 ? n : def;
+}
+
+/** 探测端口是否有响应（尽力而为，不阻断）。 */
+function _isPortOpen(port, timeoutMs = 1500) {
+    return new Promise((resolve) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        fetch(`http://127.0.0.1:${port}/`, { signal: controller.signal })
+            .then(() => resolve(true))
+            .catch(() => resolve(false))
+            .finally(() => clearTimeout(timer));
+    });
+}
+
+/** json 模式下把 Server 内部 console.log/info 重定向到 stderr，返回恢复函数。 */
+function _redirectStdoutLogs() {
+    const safeStringify = (a) => {
+        try { return JSON.stringify(a); } catch { return String(a); }
+    };
+    const toStderr = (args) => {
+        process.stderr.write(args.map((a) => (typeof a === 'string' ? a : safeStringify(a))).join(' ') + '\n');
+    };
+    const origLog = console.log;
+    const origInfo = console.info;
+    console.log = (...args) => toStderr(args);
+    console.info = (...args) => toStderr(args);
+    return () => {
+        console.log = origLog;
+        console.info = origInfo;
+    };
+}
+
+function _printServeHelp() {
+    process.stdout.write(`3rdloop serve —— 启动 Server HTTP 后端（供前端展示）
+
+用法:
+  3rdloop serve [--port N] [-w|--web] [--web-port N]
+
+选项:
+  --port N        后端端口（默认 3000，可用 3LIB_SERVER_PORT 覆盖）
+  -w, --web       同时拉起 Web 前端（默认 8080，可用 --web-port / 3LIB_WEB_PORT 覆盖）
+  --web-port N    Web 前端端口
+  --json          输出结构化启动信息到 stdout（进度/日志走 stderr）
+  -h, --help      本帮助
+
+说明:
+  默认只启动 Server HTTP 后端（http://127.0.0.1:3000），供 Web 前端 / 脚本反向代理调用。
+  CLI 的 run/submit/wait 等命令保持嵌入式模式，不经此后端。
+  退出: Ctrl+C / SIGTERM 优雅停止（Windows 下会清理 Web 子进程树）。
+`);
+}
+
+export default cmdServe;