# ZDHarness

**Repository Path**: zengdi2006/zdharness

## Basic Information

- **Project Name**: ZDHarness
- **Description**: No description available
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-23
- **Last Updated**: 2026-11-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZDHarness

ZDHarness 是一个基于 Qt 框架构建的智能体（Agent）框架：以插件化内核（AgentKernel）+
纯头插件接口层（PluginInterface）为骨架，提供智能体生命周期、LLM 适配、会话持久化、
工具调用、技能管理、团队委派、工作流与聊天界面的全链路能力。本仓库中它作为库集合
被宿主应用（GroundMonitoring / AuxiliaryMeansSoft）直链或经 C 接口装配使用。

## 功能特性

- **核心智能体框架**：`Agent` 生命周期管理、状态控制、消息收发；`AgentShell`/`ILoopEngine`
  壳/引擎分裂——壳管身份与会话接线，循环过程归引擎。
- **多岗位引擎插件化**（2026-10-05 落地）：用途不同的智能体跑**代码不同的循环**——
  岗位 = 独立插件 DLL 实现 `ILoopEngine` + 注册唯一 `engineTag`；顶层创建携 tag
  路由、tag 落盘、resume 自动复路由；第三方可按样例库自行扩展。详见
  `Docs/智能体框架-多岗位引擎-插件化设计.md`。
- **DeepSeek 深度集成**：内置 DeepSeek LLM 适配器（SSE 流式解析、工具调用、图像、
  错误重试），Token 估算与上下文窗口管理。
- **工具（Tools）系统**：`ToolRegistry` 动态注册/执行/权限控制；`ToolPipeline`
  守卫-执行-后置钩子流水线；重复执行提醒（RepeatReminder）；MCP 客户端。
- **技能（Skills）管理**：从本地目录扫描 Markdown 技能定义（Frontmatter 规范），
  含目录渲染、参数校验与动态调用。
- **会话管理（Session）**：`SessionStore` JSONL 高速持久化；会话分叉（Fork）、
  恢复（Resume）与崩溃恢复；事件总线（EventBus）+ 作用域链（Scope Chain）过滤。
- **团队与提醒**：子智能体团队委派（spawn / team 轴，子会话引擎可路由到任意岗位）；
  定时提醒（Schedule）。
- **智能体预设（Presets）**：配置预设绑定轴（与引擎路由轴正交，可组合）。
- **工作流（Workflow）**：QJSEngine 脚本化流程引擎（子进程宿主形态）。
- **UI 交互界面**：聊天面板（AgentChatPanel）、并行聊天中心（AgentChatCenter）、
  上下文环（ContextRing）、工具卡片（ToolCard）、子智能体列表面板；共享内核宿主
  `SharedKernelHost` 一键装配全插件栈。
- **C / C++ API 桥接**：完整 `ZDHC` C 接口（句柄 + 错误码 + JSON 载荷），
  `zdh_runtime_create` 一键装配；C++ 面全部核心服务均为 named services
  （Svc::\* 词表），零 LIBS 插件经命名面触达一切。
- **完善的测试套件**：覆盖 Core/Session/LLM/Tools/Agent/AgentLoop/Team/Workflow/
  Presets/Ui/CAPI 等全部模块，双腿（debug/release）全量扫波回归。

## 项目结构

ZDHarness 采用模块化设计，各组件为独立插件库（Qt Plugin，QPluginLoader 按名装载）：

- **ZDHarnessCore**：框架核心。
  - `FrameworkContext`：全局上下文，服务与事件的注册中心。
  - `AgentKernel`：能力（AgentCapability）登记与拓扑排序（Kahn），initialize/shutdown 编排。
  - `EventBus`：事件总线，串行/并行/瀑布流模式；`Scope` 作用域层级隔离。
  - `PluginLoader`：插件按名装载（`pluginDir()` 缺省 = exe 目录）。
  - `PluginInterface/`：纯头插件接口层（ILoopEngine/IHarnessPlugin/AgentCatalog 词表等）——
    插件唯一编译依赖，零 LIBS 天尺。
- **ZDHarnessLLM**：大语言模型层。
  - `DeepSeekAdapter`：DeepSeek API 通信（SSE 流式解析与错误重试）。
  - `LLMRegistry`：模型注册与路由中心；`AttachmentStore`：图像附件存取。
- **ZDHarnessSession**：会话数据层。
  - `Session`/`SessionStore`（创建、存储、加载）；`ProjectionRegistry` 投影视图。
- **ZDHarnessTools**：工具执行层。`ToolRegistry`、`ToolPipeline`、MCP 客户端。
- **ZDHarnessAgent**：智能体逻辑层。
  - `Agent`/`AgentRegistry`（工厂与生命周期）；`AgentShell`（壳，包引擎）。
  - `AgentRuntimeCapability`：Svc::Agent 命名面（含**岗位注册六法**：
    RegisterEngineFactory/UnregisterEngineFactory/RegisterProvider/UnregisterProvider/
    ListEngineFactories/ListProviders）。
  - Schedule 定时提醒面；ZDHC C 接口（ZDHCAgent）。
- **ZDHarnessAgentLoop**：默认循环引擎 `AgentLoop`（回合/步进调度、并行工具调用、
  维护相位、手动压缩）——全局厂默认岗，多岗位机制下守恒不动。
- **ZDHarnessAgentTeam**：子智能体团队委派轴（spawn/team 工具链）。
- **ZDHarnessSkills**：技能扩展层。`SkillDiscovery` 目录扫描；`SkillRegistry` 元数据。
- **ZDHarnessPresets**：智能体配置预设库。
- **ZDHarnessWorkflow**：QJSEngine 工作流引擎库。
- **ZDHarnessUi**：用户界面层。`AgentChatPanel`/`AgentChatCenter`/`ContextRingWidget`/
  `ToolCardWidget`/子智能体列表面板；`SharedKernelHost` 生产装配宿主。
- **ZDHarnessPositions**：**多岗位样例插件库**（零 LIBS）——echo 岗：不跑 LLM 的
  确定性回显循环，是「新增岗位插件」的复制样板 + 全链实证件 + 回归探针。
- **ZDWorkflowHost**：工作流宿主装配面。
- **Tests/**：测试源码，统一按 `Tests/<模块>/[<子测试>]/` 两级镜像组织。

## 环境依赖

- **Qt 5.14**（仓库实测 Qt 5.14 + MinGW 7.3 64 位，qmake 构建）
- **C++17** 兼容编译器（Qt 5.14 内建 gcc 7.3 满足）
- DeepSeek API Key（使用 LLM 功能时）

## 编译与构建

构建纪律以仓库根 `AGENTS.md` 为准，要点：

- 中间产物统一归置 `build/`（镜像源码树：`build/<模块>/`、`build/Tests/<模块>/<子测试>/`），
  **源码树零残留**；qmake 必须在对应 build 子目录下运行。
- 先编库（依赖序），再编测试；debug/release 双腿独立构建。

```bat
:: 单库（以 ZDHarnessCore 为例）
cd build\ZDHarnessCore
qmake ..\..\ProjectLibrarry\ZDHarness\ZDHarnessCore\ZDHarnessCore.pro
mingw32-make
:: 父工程聚合（不含测试）
cd build
qmake ..\ProjectLibrarry\ZDHarness\ZDHarness.pro
mingw32-make
```

产物 DLL 输出到 `dest/<config>/`；测试 exe 同目录，全量回归时对 `dest\release\`
与 `dest\debug\` 下全部 `tst_*.exe` 以 `QT_QPA_PLATFORM=offscreen` 跑
`-o path,xml` 双腿扫波。

## 配置与运行

ZDHarness 无独立可执行程序——它是库 + 插件集合，宿主有三种形态：

- **应用宿主**：GroundMonitoring / AuxiliaryMeansSoft 经 `SharedKernelHost`
  （ZDHarnessUi）装配生产插件栈（名单硬编于 SharedKernelHost.cpp）；
- **C 面宿主**：`zdh_std_kernel_start(jsonSpec)`——spec JSON 的 `plugins` 数组即
  插件名单，一键装配用 `zdh_runtime_create`；
- **测试宿主**：各 `tst_*.exe` 自行 `PluginLoader::loadAll` 按需装载。

LLM 配置：经 `LlmConfigDialog`（ZDHarnessUi）界面配置，或 LLMRegistry 命名面编程
写入（按 provider/model 存 ini）。插件 DLL 放置目录 = `PluginLoader::pluginDir()`
（缺省 = 宿主 exe 所在目录）。

## 使用指南

1. **开始对话**：宿主装配后，聊天面板输入指令；系统提示词由 `PromptAssembler`
   组装后调用 LLM。
2. **使用工具**：技能或系统提示词中的工具定义由智能体按回合自动调用
   （spawn/team/schedule 等内置工具 + 自定义技能）。
3. **岗位路由**：顶层创建智能体时 `AgentCreateArgs.strEngineTag` 填岗位 tag
   （空 = 默认 AgentLoop）；委派子会话走 spawn 工具 `provider` 键；resume 按
   落盘 tag 自动复路由。
4. **监控与调试**：订阅 EventBus（如 `session/event-appended`）监控行为；
   UI 提供实时 Token 消耗显示；日志经 SimpleQtLogger 落盘。

## 扩展开发

- **添加新工具**：在 `ZDHarnessTools` 继承 `ToolDefinition` 注册到 `ToolRegistry`；
  或经 Svc::Tooling 命名面动态注册。
- **适配新模型**：参考 `DeepSeekAdapter` 实现 `LLMAdapter` 接口挂到 `LLMRegistry`。
- **自定义技能**：在技能目录创建 Markdown 文件，按 Frontmatter 规范编写定义。
- **新增岗位引擎插件（多岗位）**：复制 `ZDHarnessPositions` 库——
  ① `.pro` 照抄（零 LIBS，纯头天尺 = ZDHarnessCore/PluginInterface）；
  ② 实现 `ILoopEngine` 全部纯虚法（循环过程自写；`assembler()` 可返 nullptr）；
  ③ Capability 照抄 `PositionCapability`：`dependencies() = {Cap::AgentRuntime}`
  硬声明，initialize 期 `RegisterEngineFactory(tag, 厂闭包, bResumable)` +
  可选 `RegisterProvider(说明书)`，shutdown 反序摘除；
  ④ 上线 = DLL 放 pluginDir + 装配名单加插件名；
  ⑤ 使用 = 创建携 `strEngineTag` / spawn `provider` 键。
  操作细则见 `Docs/智能体框架-多岗位引擎-插件化设计.md` §3。
- **C 面集成**：`zdh_runtime_create` 一键装配六模块 DLL，岗位引擎厂亦可经
  `zdh_agent_register_engine_factory` 纯 C 注册。

## 许可证

本项目遵守 `LICENSE` 文件中规定的开源协议。在使用前请仔细阅读相关条款。

---

**技术栈**: C++17, Qt 5.14, qmake, DeepSeek API, JSONL