基于 Loop Engineering 范式的 AI 任务自动化编排系统：自然语言任务 → 拆解 → 编排 → 执行 → 准出审核 → 循环迭代，直至满足验收标准

🔁 3rdLibraryLoop — AI 大循环编排引擎

基于 Loop Engineering 范式的 AI 任务自动化编排系统：自然语言任务 → 拆解 → 编排 → 执行 → 准出审核 → 循环迭代，直至满足验收标准。

📖 项目简介

3rdLibraryLoop 是一个面向 ArkTS / 鸿蒙三方库 自动化检视与处理的 AI 编排引擎。它采用「大循环」设计模式，将复杂任务分解为可独立执行的步骤，通过多 SKILL 协同完成全流程闭环：

自然语言任务
    │
    ▼
┌──────────────────────────────────────────────────────────┐
│                     LoopEngine（大循环）                  │
│                                                          │
│   ┌─────────┐    ┌──────────────┐    ┌──────────┐       │
│   │  Brain  │───→│ Orchestrator │───→│ TestCheck│       │
│   │ 拆解/重规│    │   编排执行    │    │ 准出审核  │       │
│   └────▲────┘    └──────────────┘    └────┬─────┘       │
│        │                                  │              │
│        └────────── 未通过 ────────────────┘              │
│                                                          │
│   循环终止：准出通过 OR 达到最大循环次数                  │
└──────────────────────────────────────────────────────────┘

核心能力

🧠 Brain（任务拆解）：接收自然语言任务描述，通过 LLM 拆解为含依赖关系的步骤图
🔀 Orchestrator（编排调度）：按依赖关系并行/串行执行步骤，支持重试、循环检测、死锁检测
🏃 FlexRunner（步骤执行）：语义匹配最佳 SKILL，通过 CLI（opencode）执行
✅ TestCheck（准出审核）：对照验收标准逐条评估，决定是否通过或触发重规划
📚 KnowledgeManager（知识沉淀）：将有效经验持久化，实现跨任务/跨轮次复用
🎯 SkillSelector（SKILL 选择器）：ReAct Agent，BM25 模糊匹配 + LLM 排序，自动选出最佳 SKILL

支持哪些任务

平台	鸿蒙化适配	代码检视	测试用例生成	编译验证	质量评估
ArkTS 鸿蒙原生库	—	✅	✅ Demo + XTS	✅	✅ 6 维
Flutter OHOS	✅	✅	✅ Demo + 集成测试	✅ 多版本	✅ 6 维
React Native OHOS	✅	✅	✅ Demo + XTS	✅	✅ 7 维
C/C++ 三方库	—	✅ PR 规范	—	—	—

质量评估维度：稳定性 → 一致性 → 编码质量 → 内存泄露 → 文档质量 → 用例覆盖度（RN 额外含已知问题检视）

典型场景与示例

#	场景	典型自然语言输入	涉及 SKILL 链路
1	PR 代码检视	"检视 xxx 库的 PR #123"	`arkts-code-check` / `flutter-code-check` / `rn-code-check` / `tpc-cpp-check`
2	仓库质量扫描	"对 xxx 库做全面质量评估"	`ohos-lib-quality-scan`（编排 6~7 维并行检视，综合评分）
3	鸿蒙化适配	"把 xxx Flutter 库适配到鸿蒙"	`flutter-lib-adapt-analyzer` → `flutter-lib-adapt` → `flutter-build-test`
4	适配方案分析	"评估 xxx 库是否需要鸿蒙化"	`flutter-lib-adapt-analyzer` / `rn-lib-adapt-analyzer`
5	接口规格提取	"提取 xxx 库的公开接口"	`arkts-library-interface-spec` / `flutter-interface` / `rn-library-interface-analyzer`
6	Demo 生成	"为 xxx 库未覆盖接口生成 Demo"	覆盖率分析 → 场景文档 → 代码生成 → 编译验证
7	XTS 测试生成	"为 xxx 库生成 XTS 测试用例"	覆盖率分析 → 用例文档 → 代码生成 → 执行
8	编译验证	"验证 xxx 库在哪些 Flutter 版本可编译"	`flutter-build-test`（6 版本切换编译）/ `arkts-library-compile-validate`
9	版本差异分析	"对比 xxx 库 0.72 和 0.82 版本差异"	`flutter-lib-version-diff` / `rnoh-lib-version-diff`
10	Issue 分析	"分析 xxx 库的 Issue #45"	`ohos-lib-issue-analysis`
11	提 PR	"把修改提交到 xxx 库的源仓库"	`gitcode-repo-fork` → `ohos-lib-pr-push` / `ohos-lib-pr-repush`
12	文档更新	"更新 xxx 库的 README 到 v0.4.2 模板"	`rn-lib-update-doc`
13	知识沉淀	"把这条经验导入知识库"	`knowledge-import` / `rn-library-issue-generalizer`

�🏗️ 架构总览

目录结构

3rdLibraryLoop/
├── Server/                         # 后端服务
│   ├── LoopEngine/                 # 大循环协调引擎（入口）
│   ├── Brain/                      # 任务拆解引擎
│   ├── Orchestrator/               # 编排调度器 + StepNode 步骤模型
│   ├── FlexRunner/                 # 通用执行模块
│   ├── TestCheck/                  # 准出审核引擎
│   ├── Knowledge/                  # 知识沉淀系统
│   ├── Agent/
│   │   └── SkillSelector/          # SKILL 选择器 ReAct Agent
│   ├── CLI/                        # CLI 适配器（opencode）
│   ├── DbUse/                      # 统一持久化存储（Json/Jsonl/Sqlite/File）
│   ├── Routes/                     # HTTP 路由 + 控制器 + SSE 推送
│   ├── Skills/                     # SKILL 技能库
│   ├── library/                    # 公共工具（CST时间、统计服务）
│   └── Scripts/                    # 脚本目录
│
├── Web/                            # 前端静态服务 + 反向代理
│   ├── server.js                   # 静态托管 + /api/* 代理到后端
│   └── public/                     # 大循环控制台 UI
│       ├── loop.html
│       ├── loop.css
│       └── loop.js
│
├── Archive/                        # 本地文档检索引擎（SQLite FTS5）
├── db/                             # 运行时数据目录
│   ├── Knowledge/                  # 经验知识库
│   ├── Session/                    # 对话存档（jsonl + meta）
│   └── task/                       # 任务产物
│
├── package.json
├── AGENTS.md
└── README.md

模块协作关系

flowchart LR
    User["用户自然语言任务"] --> LoopEngine

    LoopEngine -->|"① 拆解 / ⑤ 未通过时重规划"| Brain
    Brain -->|"② 任务 JSON（步骤图）"| Orchestrator

    Orchestrator -->|"③ 逐步调度（依赖并行 / 成功失败分支）"| FlexRunner
    FlexRunner -.->|"执行成功后异步经验沉淀"| Knowledge["KnowledgeManager 知识沉淀"]
    FlexRunner -->|"执行 SKILL"| CLI
    CLI --> opencode["opencode"]
    CLI --> deveco["deveco"]
   

    Orchestrator -->|"④ 全部完成"| TestCheck
    TestCheck -->|"执行审核 SKILL"| CLI
    TestCheck -->|"通过"| Done["✅ 循环结束"]
    TestCheck -->|"未通过（携带改进建议）"| Brain

要点说明：

Brain / TestCheck 与 FlexRunner 共用同一套执行底座（SkillSelector 匹配 + CLI 执行 + LLM 推理），区别仅在编排层职责

SkillSelector 为三路 BM25 融合召回（动作通道 / 领域通道 / 原文兜底，默认权重 0.4 / 0.4 / 0.2），再用 LLM 排序选出最佳 SKILL

知识沉淀为异步链路（fire-and-forget）：FlexRunner 执行成功后经同一 Session 生成 Summary，再由 KnowledgeManager 登记，不阻塞步骤流转

🔧 技术栈

层级	技术	说明
运行时	Node.js ≥ 22	ESM 模块，内置 `node:sqlite`
LLM	百炼 / DashScope（GLM-5.1）	OpenAI 兼容端点，ReAct 推理
CLI 引擎	opencode	统一适配器封装
存储	JSON / JSONL / SQLite / File	四层适配器架构，统一管理
实时通信	SSE（Server-Sent Events）	按任务频道分组推送
前端	原生 HTML/CSS/JS	无框架依赖，静态托管
文档检索	SQLite FTS5 + BM25	Archive 模块，jieba-wasm 分词

🚀 快速开始

1. 环境准备

确保以下工具已安装：

工具	版本要求	安装方式
Node.js	≥ 22（需内置 `node:sqlite`）	nodejs.org 或 `nvm install 22`
opencode	任意版本	`npm install -g opencode`
devecocli	≥ 1.2	`npm install -g @deveco/deveco-cli`

以上为所有任务通用的基础依赖。以下为Flutter / RN 鸿蒙化适配类任务的额外依赖，仅在执行适配、编译验证、集成测试等 SKILL 时需要：

工具	适用任务	安装方式
flvm	Flutter 适配 / 编译验证 / 集成测试	`npm install -g @ohos-cpf/flvm`（仓库：https://gitcode.com/lalhanOrz/flvm ）
OHOS Flutter SDK	Flutter 适配 / 编译验证	经 flvm 安装：`flvm init --deveco "<DevEco路径>"` → `flvm use oh-3.35.7-dev`

📖 flvm 完整使用指南（安装、初始化、版本切换、故障排查）见 FLVM 使用指南。

安装项目依赖（根目录 + Server）：

cd 3rdLibraryLoop
npm install
cd Server && npm install

💡 也可以跳过手动安装，直接运行第 3 步的环境检测脚本，会自动检测并安装缺失依赖。

2. 配置环境变量

cd Server
cp .env.example .env

编辑 Server/.env，填入百炼平台 API Key：

# 百炼平台 API Key（必填），从 https://bailian.console.aliyun.com/ 获取
DASHSCOPE_API_KEY=your_api_key_here

# LLM 端点与模型（OpenAI 兼容模式）
LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
LLM_MODEL=glm-5.2

# 采样参数（可选）
LLM_TEMPERATURE=0.1
LLM_MAX_TOKENS=2048
LLM_ENABLE_THINKING=false

# SkillSelector 配置（可选）
SELECTOR_TOP_K=5
FALLBACK_MODEL=qwen3.7-max

同时需配置 opencode 的模型信息，编辑 ~/.config/opencode/opencode.json：

{
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "volcengine",
      "options": {
        "apiKey": "your_api_key",
        "baseURL": "https://ark.cn-beijing.volces.com/api/v3"
      },
      "models": {
        "ep-xxxxxxxx": {
          "name": "GLM-4.7",
          "reasoningEffort": "medium"
        }
      }
    }
  }
}

2.1 配置 AI CLI 权限（headless 模式必填）

deveco-code / opencode 在 headless serve 模式下，AI 访问工作目录以外的路径时会触发 external_directory 权限询问。由于 headless 模式无 UI 应答，未预先放行的路径会导致任务永久卡死。

编辑 ~/.config/deveco/deveco.jsonc（deveco-code）或 ~/.config/opencode/opencode.json（opencode），在 permission.external_directory 中声明允许访问的目录：

{
  // ... provider / model 等配置 ...
  "permission": {
    "external_directory": {
      "/Applications/DevEco-Studio.app/*": "allow",   // DevEco SDK
      "/path/to/db/*": "allow",                        // 项目数据目录
      "/path/to/flutter_sdk/*": "allow",              // Flutter SDK
      "/tmp/*": "allow",                               // 系统临时目录
      "/private/tmp/*": "allow",                       // macOS /tmp 软链实际路径
      "/var/folders/*": "allow",                       // macOS 系统临时缓存
      "/Users/<user>/*": "allow"                       // 用户主目录（兜底）
    }
  }
}

⚠️ 常见症状：任务长时间卡在 running 状态，deveco 日志（~/.local/share/deveco/log/deveco.log）中出现 asking id=per_... permission=external_directory 即为此问题。每遇到新的未放行路径都需追加规则并重启 serve。

3. 一键启动（推荐）

项目提供了环境检测 + 服务启动一体化脚本，会自动完成以下工作：

环境检测：检查 .env 配置、Node.js、opencode、devecocli、模型配置、项目依赖（缺失依赖自动 npm install）
启动服务：
- Server / Web：先关闭占用端口的旧进程，再重新启动
- opencode serve：检测到已在运行则跳过，避免重复启动

# 环境检测 + 启动全部服务
node start-services.mjs

# 跳过环境检测，直接启动服务
node start-services.mjs --skip-check

# 仅执行环境检测（不启动服务）
node check-env.mjs

启动成功后：

服务	地址	说明
Server 后端 API	`http://127.0.0.1:3000`	REST API + SSE 推送
Web 前端	`http://localhost:8080`	AI Loop 大循环控制台
opencode serve	后台服务	CLI 引擎，供 Server 调用

访问 http://localhost:8080 即可打开 AI Loop 大循环控制台。

按 Ctrl+C 停止由本脚本启动的服务（opencode serve 若之前已在运行则不受影响）。

4. 手动启动（可选）

如需分别启动各个服务：

# opencode serve（需在项目上一级目录执行）
cd ..
opencode serve &

# 后端 API 服务（默认 127.0.0.1:3000）
cd 3rdLibraryLoop
node Server/Routes/server.js --port 3000 --type opencode

# 前端 Web 服务（默认 8080，自动代理 /api/* 到后端）
node Web/server.js --port 8080 --backend http://127.0.0.1:3000

🎯 SKILL 技能库

系统内置以下 SKILL，覆盖 ArkTS/鸿蒙三方库检视全流程：

SKILL	阶段	说明
`task-decomposition`	规划	自然语言任务拆解为步骤图
`acceptance-check`	审核	任务准出审核，逐条评估验收标准
`arkts-code-check`	检视	ArkTS 三方库 PR 代码检视（多平台）
`arkts-library-stability-check`	Phase 2	稳定性检视（异常处理、资源释放、并发安全）
`arkts-library-code-quality-check`	Phase 3	编码质量检视（华为 ArkTS 编程规范）
`arkts-library-memory-leak-check`	Phase 4	内存泄露检视（生命周期、NAPI 引用管理）
`arkts-library-documentation-quality-check`	Phase 5	文档质量检视（完整性、准确性、JSDoc）
`arkts-library-test-coverage-check`	Phase 6	用例覆盖度检视（公开接口测试覆盖）
`arkts-library-compile-validate`	收尾	ArkTS 生成代码质量检查与编译验证（迁移 + Linter + 编译修复 + ohpm 兜底）

📡 API 概览

所有 API 通过后端 http://127.0.0.1:3000 提供，前端通过反向代理访问 /api/*。

主要路由

路径	方法	说明
`/api/health`	GET	健康检查（CLI 服务状态）
`/api/brain/*`	POST	任务拆解（Brain 引擎）
`/api/orchestrator/*`	POST	编排调度（加载任务、启动、查询进度）
`/api/flexrunner/*`	POST	步骤执行（对话、控制、文件操作）
`/api/loopengine/*`	POST	大循环控制（启动、进度、终止）
`/stream`	GET	SSE 实时推送（按 taskId 频道订阅）

启动大循环示例

curl -X POST http://127.0.0.1:3000/api/loopengine/start \
  -H "Content-Type: application/json" \
  -d '{
    "taskDescription": "检视 ArkTS 三方库 xxx 的代码质量与稳定性",
    "maxLoops": 3
  }'

🗄️ 存储架构

采用四层分层设计，统一管理所有持久化数据：

┌─────────────────────────────────────────────┐
│  Store 层 (SessionStore / TaskStepStore)    │  业务语义
├─────────────────────────────────────────────┤
│  StorageManager                             │  工厂/注册表/根目录
├─────────────────────────────────────────────┤
│  Adapter 层 (Json / Jsonl / Sqlite / File)  │  存储格式实现
└─────────────────────────────────────────────┘

数据目录布局

db/
├── Knowledge/              # 经验知识库
│   ├── index.json          # 经验索引（全部记录摘要）
│   └── kn_xxxx.json        # 单条经验详情
├── Session/                # 对话存档
│   ├── <sid>.jsonl         # 消息流（append-only）
│   └── <sid>.meta.json     # 元信息
└── task/                   # 任务产物
    └── <taskId>/           # 按任务 ID 组织

🧩 核心模块详解

LoopEngine — 大循环协调引擎

协调 Brain → Orchestrator → TestCheck 的完整闭环。审核未通过时自动触发 Brain 重新规划，进入下一轮循环。循环终止条件：准出通过或达到最大循环次数（默认 3 次）。

Brain — 任务拆解引擎

通过 task-analysis / task-decomposition SKILL 将自然语言任务拆解为含依赖关系的步骤图，并产出任务级验收标准，产出 Orchestrator 可直接消费的任务 JSON。支持 replanTask() 重规划（携带上轮审核结果与失败上下文）。

Orchestrator — 编排调度器

接收任务 JSON，按依赖关系调度执行：无依赖步骤并行、成功走 nextStepId、失败走 failStepId。内置循环检测和死锁检测，支持运行时配置修改。

FlexRunner — 通用执行模块

单步骤执行引擎：初始化上下文 → 语义匹配 SKILL → 通过 CLI 执行 → 检查结果 → 持久化。支持暂停/继续/终止控制。

SkillSelector — SKILL 选择器 ReAct Agent

采用 ReAct（Reason + Act）设计模式：先扫描 SKILL 目录构建候选池，再通过 LLM 拆解任务语义，然后用三路 BM25 融合召回（动作通道 / 领域通道 / 原文兜底，加权融合）选出 Top-K 候选，最后 LLM 分维度评分排序选出最佳 SKILL。Brain / FlexRunner / TestCheck 共用同一实例。

TestCheck — 准出审核引擎

复用 FlexRunner 的执行模式（SkillSelector 匹配审核 SKILL → CLI 执行 → LLM 评估）：对照 Brain 生成的任务级验收标准，逐条评估执行产物是否满足准出条件，产出结构化审核报告（通过/未通过 + 逐条评估 + 改进建议），未通过时携带改进建议触发 Brain 重规划。

📄 License

Apache-2.0

项目介绍