|
|
"灵枢"软件设计方案
|
|
|
==================
|
|
|
|
|
|
**项目背景**
|
|
|
------------
|
|
|
|
|
|
随着国防现代化建设不断深入，信息化、智能化已成为提升作战效能和日常战备水平的关键驱动力。当前，各类军事业务系统------包括情报处理、侦察监视、装备管理、后勤保障以及无人平台控制------在各自专业领域内已形成较为完备的能力体系，并逐步开放了标准化应用程序接口。然而，在实际战备值班、日常勤务和演习训练中，大量需要跨系统协同、按固定周期执行的业务流程仍然高度依赖人工操作或零散脚本，暴露出以下突出问题。
|
|
|
|
|
|
**（1）跨系统业务流程难以自动化，响应效率受限。**
|
|
|
|
|
|
一个典型的战备任务往往需要串联多个独立系统：例如从情报数据库拉取最新目标清单，调用图像识别模型对重点目标进行确认，通过无人机指控系统派发抵近侦察任务，最后将侦察结果汇总并写入指挥系统的简报模块。当前，由于各系统接口独立、调用协议各异，执行上述流程需要值班人员反复登录不同系统、手动导出导入数据、逐条下达命令。这不仅消耗大量人力，而且在紧急情况下容易遗漏步骤或操作失误。虽然各系统自身具备较强的接口能力，但缺少一个能够将这些接口"按需编排、定时触发"的统一环境，导致整体自动化水平不高。
|
|
|
|
|
|
**（2）周期性军事任务缺乏集中管理手段。**
|
|
|
|
|
|
军事业务天然具有强周期性：每日战备数据汇总、每小时装备状态轮询、每周装备完好率统计、每月情报归档，以及各类演习中按时间轴推进的自动动作。目前这些任务的管理方式极为分散：有的写在值班日志中由人工定时提醒执行，有的通过服务器定时脚本运行，有的内嵌于某个专用软件中。没有一个统一的控制台可以让指挥员或系统管理员集中查看当前有哪些任务在运行、上次执行是否成功、下次执行预计何时、失败任务如何处置。当某个任务需要临时停止、修改参数或复制到另一个作战单元时，往往需要找到原始开发人员修改代码或配置文件，响应周期过长，难以适应快节奏的军事需求。
|
|
|
|
|
|
**（3）智能模型与数据源能力未能充分赋能一线用户。**
|
|
|
|
|
|
近年来，军工单位陆续部署了多种人工智能模型（如语音转写、目标识别、文本摘要、威胁判定），以及丰富的结构化与非结构化数据源（数据库、文件服务器、流数据接口）。然而，这些能力大多以"后端服务"的形式存在，普通参谋或操作人员无法通过简单的操作界面将这类能力"装配"到自己的日常任务中。例如，一位情报分析员希望创建一个"每天早晨自动读取前一日侦察日志，调用摘要模型生成简报，并推送至指挥终端"的工作流程，当前流程需要向开发部门提需求、排期、开发、测试，周期长达数周。理想情况下，这类任务应该由用户自己在较短时间内通过可视化配置完成，而无需依赖开发人员。
|
|
|
|
|
|
**（4）成熟任务流程难以沉淀为组织知识资产。**
|
|
|
|
|
|
在长期战备和演习中，各单位积累了数百个经过实战检验的任务流程------例如某型无人机边境巡逻的数据处理与异常告警流程、某指挥所的每日情报自动分发流程、某保障单位的装备健康度定时评估流程。这些流程目前以文档、邮件、脚本片段或个人经验的形式存在。当人员轮换或新单位组建时，往往需要重新梳理、重新开发，无法"一键复用"前人已验证的最佳实践。不同任务流程之间存在共性模式（如"定时拉取数据→调用模型分析→通过接口派发动作"），如果能够将这些模式沉淀为可共享、可检索、可一键转换的模板，将极大提升组织整体的战备响应速度和任务标准化水平。
|
|
|
|
|
|
**（5）多用户环境下的安全隔离与权限控制难以落实。**
|
|
|
|
|
|
军事业务涉及不同密级、不同岗位、不同任务组的严格隔离要求。现有的一些脚本或工具往往缺乏用户概念，多个操作人员共用同一套配置和存储空间，容易造成数据交叉污染、误操作影响他人任务，且无法追溯操作记录。即使部分系统实现了登录认证，也缺乏细粒度的"每个用户拥有自己独立的工作空间"------包括自己的任务定义、自己的数据源配置、自己的执行日志、自己的装配技能。同时，还需要支持跨用户的有限共享（例如将某个任务模板发布到公共区域），这要求在系统设计层面实现严密的用户隔离和脱敏机制。
|
|
|
|
|
|
因此，研发一套面向军事业务场景、支持可视化编排、定时触发、集中管控、安全隔离的统一任务编排与定时执行平台，已成为提升国防信息化系统协同效率、降低人工依赖、加快战备响应速度、沉淀组织作战能力的迫切需求。
|
|
|
|
|
|
本项目正是为解决上述问题而设计，通过提供任务编排、任务配置、集中任务管理、个人工作空间、安全权限隔离、任务广场共享等核心能力，让一线参谋、值班员、系统管理员无需编写代码，即可快速将多系统接口、智能模型、数据源与执行动作组装成可定时、可触发、可监控的自动化任务，实现跨系统业务流程一体化、周期性任务管理规范化、作战经验模板化、能力复用高效化、运行安全可控化，最终全面提升部队战备值班、勤务保障、演习训练的智能化与自动化水平，为国防现代化与实战化建设提供可靠支撑。
|
|
|
|
|
|
**总体体系架构**
|
|
|
----------------
|
|
|
|
|
|
1. **总体分层架构**
|
|
|
|
|
|
系统采用五层纵向分层架构，自底向上依次为：硬件资源层、容器引擎层、AI
|
|
|
中台层、核心服务层、应用交互层。如图1所示。
|
|
|
|
|
|
{width="2.207638888888889in"
|
|
|
height="7.1715277777777775in"}
|
|
|
|
|
|
图1 灵枢系统总体分层架构图
|
|
|
|
|
|
2. **各层核心作用说明**
|
|
|
|
|
|
**1.硬件资源层**
|
|
|
|
|
|
承载物理服务器、GPU、存储、网络设备，提供算力、存储与网络基础支撑，满足军事业务离线部署、高并发、高可靠需求。实现存储分区治理、算力资源池化，保障高频数据交换与大模型推理性能。
|
|
|
|
|
|
**2.容器引擎层**
|
|
|
|
|
|
基于 Docker 与 NVIDIA Container Toolkit，实现服务容器化封装、GPU
|
|
|
资源调度、环境隔离，支持离线一键部署、弹性扩缩容。统一管理镜像、服务生命周期，屏蔽底层硬件差异，降低运维复杂度。
|
|
|
|
|
|
**3.AI 中台层**
|
|
|
|
|
|
以 Ollama 推理引擎、Dify
|
|
|
开发平台为核心，提供大模型加载、智能体编排、工具集成、API
|
|
|
封装能力，为上层业务提供标准化 AI
|
|
|
能力支撑。实现模型离线部署、智能体快速配置、接口标准化输出，支撑任务编排中的
|
|
|
AI 能力调用。
|
|
|
|
|
|
**4.核心服务层**
|
|
|
|
|
|
平台核心业务逻辑载体，包含任务调度服务、配置管理服务、权限安全服务、共享生态服务、协同作业服务，实现任务全生命周期、Agent
|
|
|
配置、资源共享、团队协作的核心能力。对接 OpenClaw
|
|
|
调度引擎，完成任务触发、执行、监控、日志归集，是连接上层应用与底层资源的关键枢纽。
|
|
|
|
|
|
**5.应用交互层**
|
|
|
|
|
|
面向终端用户的可视化界面，包含工作台、任务中心、应用空间、团队协作空间、配置中心，提供零代码操作、可视化编排、集中管控、数据概览能力。适配军事业务操作习惯，简洁专业、高效易用，实现用户需求到系统执行的直观转化。
|
|
|
|
|
|
平台功能架构
|
|
|
------------
|
|
|
|
|
|
1. **总体功能**
|
|
|
|
|
|
{width="5.7625in"
|
|
|
height="8.297916666666667in"}
|
|
|
|
|
|
图2 灵枢系统功能架构图
|
|
|
|
|
|
2. **典型业务流程**
|
|
|
|
|
|
**1.新建任务**
|
|
|
|
|
|
（1）用户登录，进入任务中心 → 新建任务。
|
|
|
|
|
|
（2）填写任务名称、任务描述、任务分类。
|
|
|
|
|
|
（3）选择触发方式：
|
|
|
|
|
|
- 定时触发（Cron / 自然语言时间）
|
|
|
|
|
|
- 手动触发（点一下就跑）
|
|
|
|
|
|
（4）选择或输入 Skill：
|
|
|
|
|
|
- 从平台已注册的 Skill
|
|
|
> 列表直接选择（如：情报摘要、目标检测、数据拉取、文件推送、指令下发）
|
|
|
|
|
|
- 手动输入Skill，调用自定义能力
|
|
|
|
|
|
（5）配置该Skill所需输入参数。
|
|
|
|
|
|
（6）绑定数据源/凭证（数据库、接口、文件路径等）。
|
|
|
|
|
|
（7）设置执行策略：超时时间、重试次数、失败告警方式。
|
|
|
|
|
|
（8）保存并启动任务，进入调度/待命状态。
|
|
|
|
|
|
**2. 任务执行与监控流程**
|
|
|
|
|
|
（1）任务按所选触发方式被激活：定时到点/手动点击。
|
|
|
|
|
|
（2）平台加载对应 Agent 角色（soul.md） 与 纪律规则（memory.md）。
|
|
|
|
|
|
（3）调用指定 Skill，完成数据读取 → 模型推理 → 业务动作 → 结果输出。
|
|
|
|
|
|
（4）执行过程实时写入日志，记录：入参、返回值、耗时、资源占用、异常信息。
|
|
|
|
|
|
（5）用户在任务监控页查看：执行状态、日志、历史记录、成功率趋势。
|
|
|
|
|
|
（6）异常自动告警：弹窗、系统消息、终端推送。
|
|
|
|
|
|
**3. Agent 与 Skill 匹配配置流程**
|
|
|
|
|
|
（1）在配置中心维护 Agent：角色定位、能力边界、可调用 Skill 清单。
|
|
|
|
|
|
（2）为 Agent 配置纪律约束：安全红线、资源限制、执行规则。
|
|
|
|
|
|
（3）系统自动做Skill 权限冲突检测：
|
|
|
|
|
|
（4）支持自然语言生成 / 优化 Agent 规则，自动压缩、版本管理。
|
|
|
|
|
|
（5）任务执行时，Agent 按规则约束 Skill 行为，确保安全合规。
|
|
|
|
|
|
**4. Skill 与任务模板共享流程**
|
|
|
|
|
|
（1）用户将常用 Skill + 参数组合 保存为个人模板。
|
|
|
|
|
|
（2）成熟任务可发布到任务广场，成为公共模板：包含触发方式、Skill、参数建议。
|
|
|
|
|
|
（3）其他用户检索 → 一键导入 → 修改数据源 → 直接运行。
|
|
|
|
|
|
（4）支持按场景分类：情报处理、装备监控、侦察任务、后勤统计、指挥简报。
|
|
|
|
|
|
**5. 团队协同任务流程**
|
|
|
|
|
|
（1）管理员创建团队空间，共享内部 Skill、任务模板、数据源。
|
|
|
|
|
|
（2）成员新建任务时可直接选用团队公共 Skill 与配置。
|
|
|
|
|
|
（3）团队内任务执行状态、日志、操作记录统一可查、可审计。
|
|
|
|
|
|
（4）支持按角色分权：仅管理员可发布 / 修改关键任务与 Skill。
|
|
|
|
|
|
4. **模块详细设计**
|
|
|
----------------
|
|
|
|
|
|
**（一）任务中心**
|
|
|
|
|
|
**1.功能概述**
|
|
|
|
|
|
任务中心是平台的核心功能模块，负责用户任务的全生命周期管理。用户可通过可视化界面新建、编辑、保存、启动、停止、复制、删除任务，支持Cron表达式及自然语言触发规则。任务执行后自动记录日志，展示执行状态与结果。用户可将验证成功的成熟任务发布到任务广场，标注贡献者，供其他用户一键转换为己用。任务中心实现了从个人任务编排到团队知识复用的完整闭环，显著提升周期性数据处理效率。
|
|
|
|
|
|
**2.详细设计**
|
|
|
|
|
|
**（1）新建、编辑、保存复杂任务**
|
|
|
|
|
|
用户可以在任务中心创建新的任务。首先需要填写任务名称和描述信息，然后设置任务的触发规则。接下来用户需要选择要调用的Skill（例如文本分析、语音识别、图像处理等），并根据Skill的要求配置输入参数。此外，用户还可以绑定已经装配好的数据源，并设置任务的超时时间和失败重试次数。编辑任务时，所有已配置的信息都可以修改，修改后保存即可更新任务。保存时可以选择"保存为草稿"（暂不生效）或"正式保存"（保存后处于停止状态，等待手动启动）。所有任务信息都会保存在系统中，方便后续管理。
|
|
|
|
|
|
**（2）启动、停止、复制、删除任务**
|
|
|
|
|
|
任务创建并正式保存后，初始状态为"停止"。用户可以在任务列表中点击"启动"按钮，任务便会按照设定的时间规则自动开始执行。如果需要暂停任务，可以点击"停止"，任务将不再自动触发，但保留所有配置。对于需要频繁创建相似任务的场景，用户可以使用"复制"功能：点击复制后，系统会自动生成一个配置完全相同的副本（任务名称会加上"-副本"字样），用户稍作修改即可作为新任务使用，避免重复填写。当某个任务不再需要时，用户可以点击"删除"，系统会弹出确认提示，确认后该任务及其所有执行记录都会被移除。对于正在运行的任务，删除前会自动先停止调度。
|
|
|
|
|
|
**（3）将成熟的任务发布到任务广场，标注贡献者**
|
|
|
|
|
|
当用户创建的某个任务已经过测试并且稳定运行，就可以将其发布到公共的"任务广场"上，与其他用户分享。发布时，用户需要填写模板名称、选择分类（如情报处理、数据报表等），并可以标注自己的昵称作为"贡献者"。发布成功后，该任务模板会出现在任务广场中，其他用户可以在广场浏览、搜索，并一键将模板转换为自己的任务，转换后需要根据自身环境补充数据源连接信息。广场上的每个模板都会显示贡献者名称和使用次数，方便大家找到高质量的任务模板。
|
|
|
|
|
|
**3.实现机制**
|
|
|
|
|
|
任务中心采用前后端分离的架构，前端以桌面客户端形式运行，后端作为轻量级服务与底层调度引擎通信。用户创建任务时，前端收集任务名称、Cron表达式、Skill
|
|
|
标识及参数等配置信息，提交给后端。后端将任务配置存入数据库，此时任务处于停止状态，不触发任何调度。
|
|
|
|
|
|
当用户启动任务时，后端从数据库读取该任务的完整配置，并调用OpenClaw引擎提供的命令行接口，将Cron规则与Skill信息注册到OpenClaw的内部调度器中。停止或删除任务时，后端同样通过命令行接口通知OpenClaw移除对应调度。OpenClaw自身具备独立的定时触发能力，到达设定时间后自动执行Skill，并通过回调接口将执行结果返回给后端，后端将结果存入数据库并供前端查询展示。
|
|
|
|
|
|
OpenClaw执行Skill
|
|
|
的过程中，会调用预先编排的智能体服务，该服务连接本地大模型完成推理。所有底层组件（调度引擎、智能体、模型）均通过容器化方式封装，对前端用户完全透明。用户仅通过桌面客户端即可完成任务的配置、启动、停止及结果查看，无需关心底层实现细节。此机制实现了任务定义与执行逻辑的解耦，保证了系统的可维护性与扩展性。
|
|
|
|
|
|
**（二）配置中心**
|
|
|
|
|
|
**1.功能概述**
|
|
|
|
|
|
配置中心是平台的核心参数管理模块，负责 Agent
|
|
|
角色定位与行为约束的全生命周期管理。用户可通过可视化界面配置 Agent
|
|
|
的身份信息（soul.md）和纪律规则（memory.md），支持自然语言输入与 Agent
|
|
|
辅助优化。配置中心提供规则分类体系、冲突检测与警告、版本快照管理等功能，确保
|
|
|
Agent
|
|
|
在任务执行过程中始终遵循安全约束和行为规范。用户可对角色定位进行一键压缩优化，也可通过自然语言描述快速创建纪律规则，所有配置变更自动生成版本快照，支持回滚和对比。配置中心实现了从用户意图到
|
|
|
Agent 运行时行为的完整映射，是用户与 OpenClaw
|
|
|
引擎之间的核心桥梁，显著提升了 Agent 配置的效率和准确性。
|
|
|
|
|
|
**2.详细设计**
|
|
|
|
|
|
**（1）角色定位配置（soul.md 的编辑与管理）**
|
|
|
|
|
|
用户可以在配置中心为每个 Agent 定义核心身份信息。首先需要配置 Agent
|
|
|
的名称和代号，然后选择角色类型（如文本分析、数据采集、信息检索、安全审查等），并描述
|
|
|
Agent 的主要职责范围和能力边界。接下来用户可以设置 Agent
|
|
|
的交互风格（如简洁执行者、分析顾问等），以及授权调用的 skill
|
|
|
类别。配置完成后，系统会自动生成可视化的身份卡片，以卡片形式展示 Agent
|
|
|
的头像/图标、代号、3 至 5
|
|
|
个核心能力关键词、角色摘要和当前状态指示，方便用户快速了解每个 Agent
|
|
|
的定位。身份卡片从 soul.md 内容自动生成，随配置修改动态更新。
|
|
|
|
|
|
编辑角色定位时，用户可以选择两种方式：一是手动编辑 Markdown
|
|
|
内容，直接修改 soul.md 文件；二是通过自然语言指令让 Agent
|
|
|
辅助改写。例如用户输入\"使其更接近严格的数据分析工作\"，Agent
|
|
|
将自动将角色风格改写为\"数据分析师\"，调整为精确、数据驱动的回复风格。当
|
|
|
soul.md 内容冗长时，用户还可以触发一键压缩优化，Agent
|
|
|
会进行语义精炼：消除冗余描述、保留关键身份信息和权限定义、减少 Token
|
|
|
消耗，并展示压缩前后的 Token
|
|
|
数量变化、具体新增/删除/修改（高亮显示）和语义一致性确认，供用户审阅确认。
|
|
|
|
|
|
保存角色定位时，系统会自动触发冲突检测。在角色与 skill
|
|
|
一致性层面，系统检查新角色定位与已装备 skill
|
|
|
之间的逻辑一致性，包括权限冲突（如角色定位为\"只读分析\"但配置了\"数据写入
|
|
|
skill\"）、能力不匹配（如角色设定为\"文本处理\"但 skill
|
|
|
包含\"图像识别\"）、风格冲突等。在多 Agent 场景中，系统还检查不同 Agent
|
|
|
之间的角色重叠或职责矛盾。检测到冲突时系统显示警告信息，详细说明冲突内容并建议修改方案，用户可选择调整或覆盖强制保存（操作记录在审计日志中）。
|
|
|
|
|
|
**（2）纪律约束配置（memory.md 的规则管理）**
|
|
|
|
|
|
用户可以在配置中心为 Agent 定义行为准则与安全红线，通过 memory.md
|
|
|
配置文件管理纪律规则。纪律规则按重要性和操作特性分为五大类别：
|
|
|
|
|
|
- **安全规则（最高优先级）：**涵盖数据安全、通信安全、访问控制等核心领域。具有最严格的保护机制，不可删除、不可压缩、不可禁用，任何违反保护机制的操作都会被系统拒绝并记录日志。仅管理员可修改安全规则，且需要通过验证。
|
|
|
|
|
|
- **资源管理规则：**确保 Agent
|
|
|
在任务执行过程中合理使用计算资源和系统资源，定义资源预警阈值（如
|
|
|
CPU/内存使用率预警）、任务最大执行时长、动态资源调整策略等。不可删除，但阈值可调。
|
|
|
|
|
|
- **环境约束规则：**定义 Agent
|
|
|
在特定运行环境条件下的操作边界，包括网络环境要求、系统负载限制、并发任务数量限制等。支持动态切换功能：当系统检测到运行环境变化时，会自动匹配并激活相应的环境约束规则。可调整、可禁用。
|
|
|
|
|
|
- **任务执行规则：**规范 Agent
|
|
|
在任务执行过程中的行为策略，包括任务超时处理（暂停/终止/继续）、最大失败重试次数、多
|
|
|
Agent
|
|
|
协调规则（如通信同步频率、任务分配策略）、数据采集质量标准等。可根据不同任务类型灵活配置。
|
|
|
|
|
|
- **经验规则：**通过历史任务积累优化策略与经验教训，记录特定场景下的最佳实践、任务失败原因汇总、用户个性化操作偏好等。支持压缩整合（合并相似经验）、可禁用、具有过期机制（超过30天未更新的经验自动标记为\"待验证\"）。
|
|
|
|
|
|
除五个内置规则类别外，系统还支持用户自定义新类别以满足特定任务场景需求。创建自定义类别时，用户需声明类别名称、描述、操作权限（可删除/可压缩/可禁用）、默认优先级等属性。自定义类别的优先级不能高于安全规则，且不能与内置类别的规则冲突。
|
|
|
|
|
|
用户可以通过自然语言输入快速创建新规则。例如用户输入\"当处理时间超过60秒时自动终止任务\"，配置中心会将自然语言发送给
|
|
|
OpenClaw Agent，由 Agent
|
|
|
自动识别规则类别（任务执行）、提取条件（处理时间\>60秒）和动作（终止任务）、确定优先级，生成结构化规则条目供用户确认或手动调整后保存。对于已累积大量规则的
|
|
|
memory.md 文件，用户可触发压缩优化，Agent
|
|
|
会分析所有规则内容，识别重复、过时和可优化的条目，生成包含合并方案、归档列表和
|
|
|
Token
|
|
|
变化的压缩报告，展示压缩前后对比供用户审阅确认。安全规则在压缩过程中被强制跳过，确保不会误删安全约束。
|
|
|
|
|
|
规则以列表形式展示，每条显示启用/禁用开关（安全规则灰色不可操作）、规则类别标签（颜色编码区分类别）、规则内容摘要、优先级、来源和最后修改时间。支持按类别、关键词或状态搜索，支持优先级拖拽排序。
|
|
|
|
|
|
**（3）Agent 辅助优化与版本管理**
|
|
|
|
|
|
配置中心的所有智能功能均通过 OpenClaw Agent 实现，平台不直接调用 LLM
|
|
|
模型。用户触发智能操作（如点击\"一键优化\"、输入自然语言指令、触发压缩）时，配置中心构建包含当前配置内容和优化目标的请求，发送至
|
|
|
OpenClaw Agent API。Agent
|
|
|
内部完成推理后返回结果，配置中心展示结果供用户确认。Agent
|
|
|
调用过程中系统提供实时状态反馈（处理中/成功/失败/超时），失败时显示错误信息并提供重试或手动编辑选项。
|
|
|
|
|
|
每次配置变更都会自动生成版本快照，记录版本号、修改时间、修改来源（用户手动/Agent
|
|
|
优化/系统自动）和修改内容摘要。用户可以查看所有历史版本（按时间倒序显示）、比较任意两个版本的差异（新增/删除/修改高亮显示）、一键回滚到任一历史版本（回滚生成新版本，不删除当前版本）。管理员可以进行版本清理，但最新10个版本不可删除。安全规则的修改会生成独立的版本标签，便于追踪关键变更；版本回滚时系统会验证安全规则完整性，防止回滚导致安全规则丢失。
|
|
|
|
|
|
**3.实现机制**
|
|
|
|
|
|
配置中心采用前后端分离的架构，前端以桌面客户端形式运行，后端作为轻量级服务管理配置数据并与
|
|
|
OpenClaw 引擎通信。用户配置 Agent
|
|
|
时，前端收集角色定位（soul.md）和纪律约束（memory.md）的配置信息，提交给后端。后端将配置数据存入数据库（包括
|
|
|
config_entity 主表、soul_config 角色定位表、memory_rule
|
|
|
纪律规则表、config_version 版本表），同时同步更新文件存储中的 Markdown
|
|
|
文件，确保数据库（主数据源，支持查询和索引）和文件系统（辅助存储，支持
|
|
|
OpenClaw 直接加载）的一致性。
|
|
|
|
|
|
配置中心的所有智能功能（自然语言转结构化配置、一键压缩优化、冲突检测分析）均通过
|
|
|
OpenClaw Agent 实现。当用户触发智能操作时，配置中心向OpenClaw Agent
|
|
|
API发送包含操作类型（rewrite_soul/compress_soul/convert_rule/compress_memory/conflict_check）、上下文信息和用户指令的请求，由
|
|
|
Agent 内部调度并完成推理后返回结果。配置中心不直接调用 LLM
|
|
|
模型，无需关心模型选择和调用细节。Agent
|
|
|
调用采用异步模式，支持短超时（10秒，用于简单操作）和长超时（30秒，用于复杂操作）策略，超时后自动降级为手动编辑模式。当
|
|
|
Agent 不可用时，系统的基本编辑功能（手动修改
|
|
|
soul.md/memory.md）始终可用，智能功能显示\"暂时不可用\"状态，用户原始输入被保留，允许在
|
|
|
Agent 恢复后重新提交。系统还具备熔断器机制：若5分钟内 Agent
|
|
|
调用失败率超过50%，临时禁用智能功能并显示整体状态通知，同时定期检测
|
|
|
Agent 可用性以自动恢复。
|
|
|
|
|
|
任务执行前，任务中心从配置中心读取对应 Agent 的 soul.md 和 memory.md
|
|
|
文件，加载角色身份和纪律约束到 OpenClaw 引擎的运行时上下文中。OpenClaw
|
|
|
执行 Skill 的过程中，首先检查 memory.md
|
|
|
中所有前置条件是否满足，随后在执行过程中持续监控约束条件，一旦发现规则违规即触发相应的保护机制。Agent
|
|
|
广场中的每个 Agent 各自对应独立的 soul.md 和 memory.md
|
|
|
配置，定义各自的角色和行为边界。任务广场中发布的任务模板也可包含推荐配置模板，帮助用户快速设置匹配的角色和约束配置。所有底层组件（调度引擎、智能体、模型）均通过容器化方式封装，对前端用户完全透明。用户仅通过桌面客户端即可完成
|
|
|
Agent
|
|
|
的角色配置、纪律设置、版本管理和结果查看，无需关心底层实现细节。此机制实现了配置定义与执行逻辑的解耦，保证了系统的可维护性与扩展性。
|
|
|
|
|
|
**（三）应用空间**
|
|
|
|
|
|
应用空间是该系统价值落地与生态拓展的重要载体，遵循"用户个性化为核心、空间公共共享"的设计理念，以智能体广场、任务广场为核心，辅以团队空间，打通个人个性化使用与公共生态共享的双向链路，明确平台在个人效率提升、开发者生态共建、场景落地及团队协作等方向的应用价值，实现从单用户AI助手到开放共享式AI生态平台的能力跃迁。该应用空间三个板块具体如下：
|
|
|
|
|
|
**1.智能体广场：开箱即用的智能体能力共享生态**
|
|
|
|
|
|
**（1）模块定位**
|
|
|
|
|
|
作为公共智能体能力枢纽，智能体广场旨在将各类优质智能体API标准化、平台化，实现智能体API的一次开发、全平台复用，降低智能体应用落地门槛，为所有用户提供能力共享与技术交流渠道，让非技术用户也能轻松使用专业智能体，实现高端专业功能的快速落地。
|
|
|
|
|
|
**（2）核心场景**
|
|
|
|
|
|
个人用户：零代码筛选、嵌入办公、学习、科研等智能体API，一键搭建专属智能体助手，支持API二次编辑，实现非技术用户的专业级智能体能力快速获取。
|
|
|
|
|
|
开发者/机构：开发者可上传自研垂直领域智能体API，实现技术复用与交流；部门机构上传专业技术智能体，降低智能体学习门槛，执行人员无需专业知识即可轻松实现技能掌握并提出合理意见，实现复杂技能简易化、专业技能通用化，构建上传-共享-调用-迭代的技术生态。
|
|
|
|
|
|
**2.任务广场：可复用的自动化任务共享平台**
|
|
|
|
|
|
**（1） 模块定位**
|
|
|
|
|
|
作为自动化任务共享枢纽，将成熟常用的任务、流程模板化公共化，实现一次配置、全平台复用，衔接任务中心实现任务全生命周期管理，避免重复劳动的同时推动系列任务模块流程标准化，借助任务模板还可支持数据情报收集格式标准化，利于后续相关处理。
|
|
|
|
|
|
**（2）核心场景**
|
|
|
|
|
|
个人办公：一键调用自动化任务模板，支持二次编辑适配个人流程，实现办公自动化，提升个人工作效率。
|
|
|
|
|
|
部门协作：部门相关/专业人员上传标准任务模块，执行人员调用该任务模块，确保不同执行人员在开展同类工作时流程统一、标准一致、输出规范，减少因操作差异带来的质量波动，同时降低新人上手成本与跨岗位协作沟通成本，实现部门工作高效、规范、可追溯。
|
|
|
|
|
|
**3.团队空间：团队内部专属协同共享平台**
|
|
|
|
|
|
**（1）模块定位**
|
|
|
|
|
|
基于公共共享理念打造的私有化协同空间，实现团队内智能体、任务的安全共享、统一管理与协同作业，解决团队资源分散、重复开发、协同低效的痛点，适配部门、科研机构等团队需求。
|
|
|
|
|
|
**（2）核心能力**
|
|
|
|
|
|
私有化共享：支持团队资源统一归集，按角色设置精细化权限，成员可一键调用并二次编辑团队资源，实现一次沉淀、全团队复用。
|
|
|
|
|
|
统一管理：对团队资源进行分类归档、版本管控与闲置清理，打造标准化团队资源库。
|
|
|
|
|
|
协同作业：支持团队共同创建编辑任务，实时同步执行状态；支持智能体能力共建与反馈迭代，提供团队级使用数据统计与分析。
|
|
|
|
|
|
多团队隔离：支持创建子团队/部门空间，不同子空间资源独立管理，同时管理员可实现总-分式全局管控。
|
|
|
|
|
|
对于公开共享的智能广场和任务广场，具备以下重要功能：
|
|
|
|
|
|
**1.检索功能**
|
|
|
|
|
|
为便于用户找到需求的智能体API和任务资源，智能体广场与任务广场要求用户上传资源时进行标签选择，同时为不确定具体标签的用户提供自主识别的标签推荐功能。广场界面有检索框、标签选择和热点推荐板块，支持用户通过关键词、标签搜索需求资源并借助热点推荐关注流行趋势、收获"好评"资源。同时支持用户在搜索后按照时间、热度（使用率）对资源进行排序，提高资源检索效率。
|
|
|
|
|
|
**2.更新功能**
|
|
|
|
|
|
广场支持用户对于自己的智能体API和任务资源进行上传、更新、删除操作，用户可自行决定是否保留历史资源，同时系统会保留操作日志，便于用户查看。
|
|
|
|
|
|
5. **界面设计**
|
|
|
------------
|
|
|
|
|
|
**（一）主界面UI**
|
|
|
|
|
|
本系统界面采用单页应用式布局，左侧固定导航菜单，右侧动态内容区域，整体风格简洁专业，适配军事业务场景的严肃性与高效性要求。界面设计遵循模块化、可扩展原则，确保用户能够快速定位核心功能并完成日常任务编排与监控。
|
|
|
|
|
|
左侧导航栏包含系统主要功能入口，自上而下依次为：工作台、任务中心、应用空间（下设"智能体广场"与"任务模板广场"两个子菜单）、团队协作空间以及核心配置中心。导航菜单支持折叠与展开，当前激活的页面或子菜单以高亮背景色和图标进行区分，便于用户感知当前位置。每个菜单项配有直观的图标与文字标签，减少学习成本。导航栏顶部展示软件名称"灵枢"及Logo图标，强化品牌识别。
|
|
|
|
|
|
右侧内容区域顶部设有固定栏，从左至右依次显示：当前页面标题，全局检索入口，通知中心图标（点击可查看系统消息或任务执行结果），以及当前登录用户的身份信息（头像、姓名/职务）。顶部栏保持操作一致性，使用户在任何页面都能快速发起搜索或查看通知。
|
|
|
|
|
|
图3展示了系统主界面的整体结构。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.5409722222222224in"}
|
|
|
|
|
|
图3 灵枢系统主页面
|
|
|
|
|
|
**（二）工作台**
|
|
|
|
|
|
工作台作为用户登录后的默认概览页，采用卡片式指标布局与多维度数据可视化。主要展示以下关键数据：运行中任务数量、任务总数、本月任务触发次数、当前告警数量，每个指标卡片内嵌微型趋势图，直观反映近期变化。工作台下方提供快捷操作按钮，包括"创建新任务"和"逛逛任务广场"，帮助用户快速进入核心功能。
|
|
|
|
|
|
数据概览区域包含四个图表模块：
|
|
|
|
|
|
任务执行趋势：支持切换近7天/近30天视图，以折线图展示成功与失败任务数量变化。
|
|
|
|
|
|
任务状态分布：环形饼图展示运行中、已停止、错误三类任务的比例。
|
|
|
|
|
|
智能体调用量：柱状图展示各智能体（如Qwen3.5摘要、图像识别、数据库统计、无人机API）的累计调用次数。
|
|
|
|
|
|
系统资源监控：三个仪表盘分别展示CPU、内存、GPU的实时使用率，采用半圆弧进度指示器。
|
|
|
|
|
|
图4为工作台的实际页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.732638888888889in"}
|
|
|
|
|
|
图4 灵枢系统工作台页面
|
|
|
|
|
|
3. **任务中心**
|
|
|
|
|
|
任务中心包含任务列表与可视化编排两大核心子视图。
|
|
|
|
|
|
**1.任务列表视图**
|
|
|
|
|
|
顶部设有筛选栏，支持按任务名称关键字实时搜索、按状态（运行中/已停止/全部）筛选。任务列表以独立卡片形式展示每个任务项，卡片内容包括：任务名称、SKil名称、触发方式l、关联智能体名称、运行状态标签（●
|
|
|
运行中 / ⏸
|
|
|
已停止）。卡片右侧提供操作按钮组：启动/停止（状态自适应）、编辑配置、流程编排、监控、发布到广场。点击"编辑配置"弹出模态框，支持修改任务名称、Cron规则及关联智能体；点击"流程编排"进入编排视图；点击"监控"进入任务监控页面；点击"发布到广场"弹出发布模态框。图5展示了任务列表的实际页面。
|
|
|
|
|
|
{width="5.1722222222222225in"
|
|
|
height="2.4409722222222223in"}
|
|
|
|
|
|
图5 灵枢系统任务列表页面
|
|
|
|
|
|
**2.任务监控页面**
|
|
|
|
|
|
任务监控页面用于实时查看单个任务的执行详情，采用暗色终端风格与可视化图表结合。页面顶部显示任务名称及"手动执行一次"、"返回列表"按钮。
|
|
|
|
|
|
页面主体分为四部分：
|
|
|
|
|
|
执行进度区（手动触发时显示）：进度条展示任务执行百分比，实时更新。
|
|
|
|
|
|
实时日志终端：以暗色背景、彩色文字滚动显示任务执行过程中的详细日志，支持按日志级别过滤，并支持自动滚动开关。
|
|
|
|
|
|
性能仪表区：包含CPU、内存使用率仪表盘和执行耗时趋势柱状图，直观反映任务执行时的资源消耗与性能波动。
|
|
|
|
|
|
执行历史时间轴：按时间倒序列出最近多次执行记录，每条记录包含执行时间、状态（成功/失败）、耗时、备注信息，并以圆点颜色区分状态。图6为任务监控页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.7416666666666667in"}
|
|
|
|
|
|
图6 灵枢系统任务监控页面
|
|
|
|
|
|
4. **应用空间**
|
|
|
|
|
|
应用空间包含两个并列的子页面，均采用网格卡片布局，每行自适应展示多个卡片。
|
|
|
|
|
|
**1.智能体广场**
|
|
|
|
|
|
每个卡片展示智能体名称、提供方、分类标签、使用次数及简要功能描述。卡片底部提供"查看
|
|
|
API
|
|
|
接口文档"按钮，点击后弹出模态框，详细展示接口地址、鉴权方式、请求参数JSON示例及cURL调用示例，方便开发者集成调用。图7为智能体广场页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.7416666666666667in"}
|
|
|
|
|
|
图7 灵枢系统智能体广场页面
|
|
|
|
|
|
**2.任务模板广场**
|
|
|
|
|
|
每个卡片展示任务模板名称、贡献者、分类标签、使用次数及简要说明。卡片底部提供"导入为我的任务"按钮，点击后一键将模板复制到当前用户的任务列表中（状态默认为"已停止"），并提示用户根据自身环境补充数据源凭证。两个广场均支持顶部检索框、标签筛选下拉框以及按时间/热度排序功能，提高资源发现效率。图8为任务模板广场页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.7305555555555556in"}
|
|
|
|
|
|
图8 灵枢系统任务模板广场页面
|
|
|
|
|
|
5. **团队协作空间**
|
|
|
|
|
|
团队协作空间页面顶部展示团队基本信息：团队名称、团队隔离空间ID、成员数量、共享任务模板数量及存储空间占用。页面右上角设有"邀请新成员"按钮，点击后弹出输入框，输入姓名即可添加成员。
|
|
|
|
|
|
页面主体分为四大区域：
|
|
|
|
|
|
团队成员列表：以卡片形式展示成员头像、姓名、在线状态（绿点/灰点）、角色（管理员/编辑者/查看者）。管理员可修改他人角色或移除成员。
|
|
|
|
|
|
共享任务模板：列表展示团队内已共享的任务模板，包括模板名称、创建者、使用次数，成员可"应用到我"一键导入自己的任务列表，创建者可取消共享。
|
|
|
|
|
|
操作日志：按时间倒序列出团队内的关键操作（如创建任务、修改流程、发布模板等），便于审计与追溯。
|
|
|
|
|
|
讨论留言区：支持成员发表评论，实时显示发言者姓名、时间及内容，便于团队协作沟通。图9为团队协作空间页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.3826388888888888in"}
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.685416666666667in"}
|
|
|
|
|
|
图9灵枢系统团队协作空间页面
|
|
|
|
|
|
6. **核心配置中心**
|
|
|
|
|
|
配置中心页面分为两大区块：
|
|
|
|
|
|
数据源与外部凭证管理：以卡片形式展示已配置的数据源，包含连接地址、连通状态标签及"修改凭证"按钮。点击修改凭证弹出模态框，支持填写主机地址、用户名、密码/Token，系统承诺对凭证进行AES-256加密存储，仅在任务执行时解密调用。
|
|
|
|
|
|
本地 AI
|
|
|
引擎状态：展示Ollama离线大模型推理框架的运行状态（服务就绪标签）、硬件资源，并提供"重启服务"和"扫描模型"操作按钮，便于运维人员管理底层算力与模型。图10为配置中心页面。
|
|
|
|
|
|
{width="5.752777777777778in"
|
|
|
height="2.717361111111111in"}
|
|
|
|
|
|
图10 灵枢系统配置中心页面
|
|
|
|
|
|
**架构设计与环境配置**
|
|
|
----------------------
|
|
|
|
|
|
图11展示了本系统的环境配置层级架构图。
|
|
|
|
|
|
{width="3.4451388888888888in"
|
|
|
height="4.093055555555556in"}
|
|
|
|
|
|
图11 灵枢系统的环境配置层级架构
|
|
|
|
|
|
首先，在硬件资源管理方面，本系统实施了分区治理方案，以平衡响应速度与存储容量。操作系统
|
|
|
Ubuntu 20.04 LTS 安装于 1TB 固态硬盘，并将 2TB 固态硬盘挂载为 /workspace
|
|
|
目录，通过软链接映射所有普通用户的主目录以确保高频数据交换在固态介质上完成。针对大容量数据存储需求，本小组利用
|
|
|
LVM 技术将两块 4TB 机械硬盘合并为 8TB 的 /data 存储池，专门承载 Docker
|
|
|
镜像、模型权重及OpenClaw的源码资源，同时安装了 MySQL
|
|
|
数据库，并配置了远程访问权限以支持业务数据持久化。
|
|
|
|
|
|
其次，在算力环境与容器化引擎配置方面，为充分调用 4 张 NVIDIA RTX 3090
|
|
|
显卡资源，系统安装了 NVIDIA 535
|
|
|
版本的显卡驱动，并启用了持久化模式，以保障高负载任务下的显卡稳定性。针对离线镜像文件体积巨大的特点，Docker
|
|
|
引擎的默认存储目录已从系统盘迁移至
|
|
|
/data/docker_root，有效防止了系统空间溢出。此外，通过部署 NVIDIA
|
|
|
Container Toolkit，实现了 Docker
|
|
|
容器对物理显卡计算资源的直接调用，确保了大模型的标准化部署。
|
|
|
|
|
|
然后，在模型部署方面，系统在无外网环境下通过离线镜像导入方式，完成了核心
|
|
|
AI 组件的运行。Ollama
|
|
|
服务以容器化方式部署，其模型存储路径挂载至机械硬盘，并已完成Qwen3.5大模型参数文件的离线导入与校验。同时，Dify
|
|
|
平台的全量微服务集群已完成离线加载，涵盖了 API、Worker、Web
|
|
|
及数据库代理等核心模块，为大模型的上层调用开发提供支持。这一步使得平台具有
|
|
|
AI 流程编排的能力，为 OpenClaw这一上层应用提供了稳定的中台支撑。
|
|
|
|
|
|
最后，在后续的业务部署与智能体配置阶段，工作重心将聚焦于 OpenClaw
|
|
|
系统的落地与智能体集成。我们将 OpenClaw 的源码及资源统一存放于
|
|
|
/data/OpenClaw_resources，配置其与 MySQL 数据库及本地 Ollama
|
|
|
接口的通信链路，并通过 Docker 启动业务容器。随后，在 Dify 管理后台中将
|
|
|
Ollama
|
|
|
注册为模型供应商，根据业务需求编排具备提示词逻辑、工具调用权限及记忆机制的智能体。最终通过配置智能体与
|
|
|
OpenClaw
|
|
|
接口的交互规则，实现从用户请求到模型处理再到业务动作执行的完整闭环。
|
|
|
|
|
|
表1是环境配置概览表。
|
|
|
|
|
|
------------ ------------ ------------------------------ ----------------------------------------------
|
|
|
**维度** **配置项** **详细参数/版本** **部署位置/备注**
|
|
|
**存储层** 系统空间 1TB NVMe SSD 存放 Ubuntu 20.04 的系统文件、内核、驱动程序
|
|
|
工作空间 2TB NVMe SSD 存放 OpenClaw 的开发源码、脚本文件、配置文件
|
|
|
存储池 8TB (2 x 4TB Enterprise HDD) 存放 Docker 镜像库、大模型参数、离线资源包
|
|
|
**算力层** GPU 显卡 4 x NVIDIA RTX 3090 (24GB) 开启 Persistence Mode (持续性能模式)
|
|
|
显卡驱动 NVIDIA Driver v535 裸机环境安装
|
|
|
**引擎层** 容器引擎 Docker CE / Docker Compose 用于隔离环境，部署大模型
|
|
|
运行时环境 NVIDIA Container Toolkit 支持容器调用 GPU 算力
|
|
|
**模型层** 推理引擎 Ollama 映射至 /data/models/ollama
|
|
|
预置大模型 Qwen3.5 已完成离线校验
|
|
|
**平台层** 开发中台 Dify v0.6.x (微服务集群) 包含 API, Worker, Redis, Postgre 等
|
|
|
数据库 MySQL 8.0 支持 OpenClaw 及 Dify 业务数据
|
|
|
------------ ------------ ------------------------------ ----------------------------------------------
|
|
|
|
|
|
表1 灵枢系统的环境配置概览表
|
|
|
|
|
|
---
|
|
|
|
|
|
灵枢与 OpenClaw 集成设计
|
|
|
------------------------
|
|
|
|
|
|
### 4.1 集成架构与通信机制
|
|
|
|
|
|
#### 4.1.1 总体集成架构
|
|
|
|
|
|
灵枢与 OpenClaw 调度引擎之间采用**服务端对服务端**的集成模式，前端用户界面对 OpenClaw 的存在完全透明。灵枢 Flask 后端（`app.py`）是唯一与 OpenClaw 通信的主体，对应的通信逻辑集中封装于独立模块 `openclaw.py`。整体集成架构如下：
|
|
|
|
|
|
```
|
|
|
浏览器（前端）
|
|
|
│ REST API（JWT 认证）
|
|
|
▼
|
|
|
灵枢后端 Flask（:5000） ← Docker 容器，宿主机 host-gateway 可达
|
|
|
│ JSON-RPC 2.0 over WebSocket（ACP 协议）
|
|
|
│ ws://host-gateway:18789/acp
|
|
|
▼
|
|
|
OpenClaw Gateway（:18789） ← 宿主机进程，监听 0.0.0.0
|
|
|
│ 推理调用
|
|
|
▼
|
|
|
GLM4.7 大模型（本地部署）
|
|
|
│
|
|
|
└─── 执行完成后 HTTP POST 回调
|
|
|
→ http://host-gateway:5000/api/openclaw/callback/{task_id}
|
|
|
→ 灵枢后端写入执行结果与日志
|
|
|
```
|
|
|
|
|
|
灵枢以 **Docker 容器**方式运行，OpenClaw 以**宿主机进程**方式运行，两者通过 Docker 内置的 `host-gateway` 域名实现跨边界互访。灵枢容器主动发起 WebSocket 连接访问 OpenClaw；OpenClaw 执行完成后通过 HTTP POST 主动回调灵枢的 REST 接口，形成完整的双向通信闭环。
|
|
|
|
|
|
所有地址均通过环境变量注入，在 `docker-compose.yml` 中集中配置，无需修改代码即可适配不同部署环境：
|
|
|
|
|
|
| 环境变量 | 默认值 | 说明 |
|
|
|
|---|---|---|
|
|
|
| `OPENCLAW_URL` | `http://127.0.0.1:18789` | OpenClaw 服务基础地址 |
|
|
|
| `OPENCLAW_PROTOCOL` | `websocket` | 传输协议（`websocket` 或 `http`） |
|
|
|
| `OPENCLAW_WS_PATH` | `/acp` | WebSocket 端点路径 |
|
|
|
| `OPENCLAW_TOKEN` | 空 | 客户端认证令牌 |
|
|
|
| `OPENCLAW_TIMEOUT` | `10` | 请求超时秒数 |
|
|
|
| `LINGSHU_CALLBACK_URL` | `http://localhost:5000` | 灵枢回调基础地址（供 OpenClaw 调用） |
|
|
|
|
|
|
#### 4.1.2 传输协议：JSON-RPC 2.0 over WebSocket（ACP 协议）
|
|
|
|
|
|
灵枢与 OpenClaw 之间的业务通信基于 **ACP（Agent Control Protocol）**协议，本质是 JSON-RPC 2.0 承载于 WebSocket 之上。每次调用采用**短连接模式**：建立连接、完成认证、发送请求、读取响应、关闭连接，保持实现简单、资源占用低。
|
|
|
|
|
|
系统同时保留了 **HTTP POST** 模式作为备用，通过环境变量 `OPENCLAW_PROTOCOL=http` 一键切换，便于与不同版本或配置的 OpenClaw 实例对接。地址自动转换规则如下：
|
|
|
|
|
|
```
|
|
|
OPENCLAW_URL=http://host:18789 → ws://host:18789/acp
|
|
|
OPENCLAW_URL=https://host:18789 → wss://host:18789/acp
|
|
|
```
|
|
|
|
|
|
#### 4.1.3 WebSocket 连接与客户端认证流程
|
|
|
|
|
|
OpenClaw Gateway 启用了客户端认证机制，要求连接方在 WebSocket 握手完成后立即完成"配对"认证，才能接受后续业务请求。完整的单次调用流程分为五个阶段：
|
|
|
|
|
|
```
|
|
|
阶段一：TCP + WebSocket 握手
|
|
|
灵枢 → OpenClaw: HTTP Upgrade 请求
|
|
|
灵枢 ← OpenClaw: 101 Switching Protocols
|
|
|
（HTTP 升级头中携带 Authorization: Bearer <token>）
|
|
|
|
|
|
阶段二：客户端认证（connect 帧）
|
|
|
灵枢 → OpenClaw:
|
|
|
{ "type": "connect", "token": "<OPENCLAW_TOKEN>", "clientId": "<uuid>" }
|
|
|
|
|
|
灵枢 ← OpenClaw（认证通过）:
|
|
|
{ "type": "connected", "sessionId": "..." }
|
|
|
灵枢 ← OpenClaw（认证拒绝）:
|
|
|
{ "type": "error", "reason": "..." } → 抛出异常，终止调用
|
|
|
|
|
|
阶段三：发送业务 RPC 请求
|
|
|
灵枢 → OpenClaw:
|
|
|
{ "jsonrpc": "2.0", "id": "<uuid>", "method": "...", "params": {...} }
|
|
|
|
|
|
阶段四：接收业务 RPC 响应
|
|
|
灵枢 ← OpenClaw:
|
|
|
{ "jsonrpc": "2.0", "id": "<uuid>", "result": {...} }
|
|
|
（按 id 匹配，跳过心跳等无关帧，最多跳过 10 帧）
|
|
|
|
|
|
阶段五：关闭连接
|
|
|
灵枢 → OpenClaw: WebSocket Close 帧
|
|
|
```
|
|
|
|
|
|
认证阶段的容错处理：服务端可能在 `connected` 帧前夹杂心跳等无关帧，灵枢最多读取 3 帧进行判断；若均未命中 `connected`，则判定为认证握手超时，抛出异常并触发降级逻辑。
|
|
|
|
|
|
#### 4.1.4 执行结果回调机制
|
|
|
|
|
|
OpenClaw 采用**异步回调**模式返回执行结果，即 RPC 调用成功仅代表 OpenClaw 已接收任务，实际执行结果由 OpenClaw 在 Skill 运行完成后主动 POST 至灵枢的回调接口：
|
|
|
|
|
|
```
|
|
|
POST /api/openclaw/callback/{task_id}
|
|
|
Content-Type: application/json
|
|
|
|
|
|
{
|
|
|
"execution_id": 123,
|
|
|
"job_id": "lingshu_task_1_exec_123",
|
|
|
"status": "success", // success / failed / timeout
|
|
|
"duration_ms": 1500,
|
|
|
"cpu_usage_pct": 35.2,
|
|
|
"memory_usage_pct": 28.1,
|
|
|
"error_message": "",
|
|
|
"logs": [
|
|
|
{ "level": "info", "time": "2026-01-01 12:00:00.000",
|
|
|
"message": "执行完成", "node": "step1" }
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
回调接口无需 JWT 认证（由 OpenClaw 直接调用），灵枢收到回调后执行以下操作：
|
|
|
1. 更新 `task_executions` 表中的执行状态、耗时、资源占用；
|
|
|
2. 更新 `tasks` 表的 `last_run_at` 字段；
|
|
|
3. 将 `logs` 数组逐条写入 `task_logs` 表；
|
|
|
4. 若状态为 `failed` 或 `timeout`，向任务归属用户写入告警通知（`alert_notifications`）。
|
|
|
|
|
|
#### 4.1.5 降级保护机制
|
|
|
|
|
|
当 OpenClaw 服务不可达时，灵枢不会直接返回失败，而是自动切换至**本地模拟执行**模式：
|
|
|
|
|
|
- 写入模拟执行日志（标注 `[降级]` 前缀）；
|
|
|
- 用随机生成的资源占用数据（CPU 10–60%、内存 20–50%）填充执行记录；
|
|
|
- 将执行状态标记为 `success` 并写入耗时；
|
|
|
- 任务调度侧标记为 `degraded: True`，系统日志保留告警，待 OpenClaw 恢复后可接管。
|
|
|
|
|
|
此机制确保任务管理平台的基本可用性不受调度引擎故障影响，同时保持对降级状态的可见性与可追溯性。
|
|
|
|
|
|
---
|
|
|
|
|
|
### 4.2 核心指令映射关系
|
|
|
|
|
|
灵枢的任务操作经由 `openclaw.py` 模块统一翻译为 ACP 协议指令，发送至 OpenClaw。下表列出了全部指令的映射关系。
|
|
|
|
|
|
#### 4.2.1 灵枢操作 → ACP 指令映射总表
|
|
|
|
|
|
| 灵枢用户操作 | 灵枢侧函数 | ACP method | 说明 |
|
|
|
|---|---|---|---|
|
|
|
| 启动定时任务 | `register_task()` | `jobs.register.cron` | 将 Cron 表达式与 Skill 注册为周期性调度 |
|
|
|
| 启动手动触发任务 | `register_task()` | `jobs.register.run_once` | 注册为立即执行一次的调度（延迟 0 秒） |
|
|
|
| 手动执行一次 | `trigger_once()` | `jobs.register.run_once` | 以独立 job_name 触发单次执行，携带 execution_id |
|
|
|
| 停止任务 | `unregister_task()` | `jobs.cancel` | 通知 OpenClaw 移除该 job 的调度 |
|
|
|
| 查询任务状态 | `query_job()` | `jobs.get` | 查询 OpenClaw 中指定 job 的当前状态 |
|
|
|
|
|
|
#### 4.2.2 ACP 指令详细说明
|
|
|
|
|
|
**`jobs.register.cron`** — 注册定时调度
|
|
|
|
|
|
用于将有 Cron 表达式的任务注册到 OpenClaw 调度器。job_name 格式为 `lingshu_task_{task_id}`，注册成功后 OpenClaw 返回的 `jobId` 被持久化至数据库 `workflow_json.openclaw_job_id` 字段，供后续停止/查询使用。
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"job": {
|
|
|
"name": "lingshu_task_42",
|
|
|
"cron": "0 8 * * *",
|
|
|
"executor": { "type": "skill", "skill": "morning_report", "params": {}, "timeout": 300,
|
|
|
"callbackUrl": "http://host-gateway:5000/api/openclaw/callback/42",
|
|
|
"callbackParams": { "execution_id": null } },
|
|
|
"retry": 3,
|
|
|
"taskName": "每日早报生成"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**`jobs.register.run_once`** — 注册单次执行
|
|
|
|
|
|
用于手动触发和无 Cron 表达式的任务。手动触发时 job_name 追加 `_exec_{execution_id}` 后缀，以区分同一任务的多次手动执行，`callbackParams` 中携带 `execution_id` 供回调时精准匹配执行记录。
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"job": {
|
|
|
"name": "lingshu_task_42_exec_789",
|
|
|
"executor": { "type": "skill", "skill": "morning_report", "params": {}, "timeout": 300,
|
|
|
"callbackUrl": "http://host-gateway:5000/api/openclaw/callback/42",
|
|
|
"callbackParams": { "execution_id": 789 } },
|
|
|
"delaySeconds": 0,
|
|
|
"taskName": "每日早报生成"
|
|
|
}
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**`jobs.cancel`** — 取消/移除调度
|
|
|
|
|
|
```json
|
|
|
{ "jobId": "lingshu_task_42" }
|
|
|
```
|
|
|
|
|
|
停止时优先使用数据库中持久化的 `openclaw_job_id`，若数据库中无记录则回退使用 `lingshu_task_{task_id}` 格式。当 OpenClaw 返回 404（job 不存在）时视为停止成功，不报错。
|
|
|
|
|
|
**`jobs.get`** — 查询任务状态
|
|
|
|
|
|
```json
|
|
|
{ "jobId": "lingshu_task_42" }
|
|
|
```
|
|
|
|
|
|
由 `query_job()` 调用，返回 OpenClaw 中该 job 的当前运行状态，供灵枢前端状态面板展示。
|
|
|
|
|
|
#### 4.2.3 Executor 类型路由规则
|
|
|
|
|
|
灵枢根据 `skill_name` 的内容自动选择 executor 类型，规则如下：
|
|
|
|
|
|
| 条件 | executor 类型 | 适用场景 |
|
|
|
|---|---|---|
|
|
|
| `skill_name` 包含 `/` | `shell` | 绝对/相对路径脚本，如 `/opt/scripts/sync.sh` |
|
|
|
| `skill_name` 以 `.sh` 或 `.py` 结尾 | `shell` | 脚本文件名，如 `export_data.py` |
|
|
|
| 其他 | `skill` | OpenClaw 平台内注册的 Skill 名称，如 `morning_report` |
|
|
|
|
|
|
Shell executor 将 `skill_params` 序列化为 JSON 字符串作为命令行参数传入；Skill executor 直接将 `skill_params` 作为结构化对象传递，并附带 `callbackUrl` 和 `callbackParams`。
|
|
|
|
|
|
#### 4.2.4 job_id 持久化机制
|
|
|
|
|
|
每次成功注册调度后，OpenClaw 返回的 `jobId` 会被写入对应任务的 `workflow_json` 字段（JSON 对象中的 `openclaw_job_id` 键），作为后续停止、查询操作的稳定标识符。此设计使 `job_id` 的管理与任务配置完全耦合，无需额外的数据表，同时支持 OpenClaw 侧动态分配 job_id 的场景。
|
|
|
|
|
|
#### 4.2.5 异步调用与线程安全
|
|
|
|
|
|
任务启动（`register_task`）和手动执行（`trigger_once`）均在独立守护线程中执行，不阻塞 Flask 主线程对前端的响应。线程内的失败处理逻辑负责：
|
|
|
|
|
|
- 将任务状态回写为 `stopped`（启动失败时）；
|
|
|
- 将执行记录标记为 `failed`（执行失败时）；
|
|
|
- 向归属用户写入告警通知。
|
|
|
|
|
|
停止任务（`unregister_task`）在主线程同步执行，原因是停止操作需要在接口响应前确认 OpenClaw 已收到取消指令，保证状态一致性。
|
