# 架构文档

<p>
  <a href="architecture.en.md">English</a> · <b>简体中文</b>
</p>

本文档说明本项目的核心架构、设计意图与关键取舍。

---

## 1. 问题与定位

传统工作流以预定义结构约束执行过程，而自主 Agent 协作则允许代理动态决定任务分工与执行路径。前者结构明确，但适应性受限；后者灵活，但执行组织不一定能被显式表达和持续治理。

本项目探索两者之间更一般的架构方向：让 Agent 执行组织既能被显式定义、持久化和观察，又能在运行过程中动态调整，并支持人工干预与经验复用。

`dsh-visual-workflow` 构建在 DeepSeek Harness 之上，以图结构表达执行组织，以父代理驱动动态编排，以独立的运行状态维持执行连续性，并通过组织资产与经验积累支持持续改进。

项目的核心不是在固定工作流与自主 Agent 之间选择一种模式，而是让组织结构的设计权、执行过程的决策权与运行时的调整权能够按需分配。

---

## 2. 核心架构

整体分层如下：

```text
┌─────────────────────────────────────┐
│                Client               │
│         可视化、观察与人工干预       │
└──────────────────┬──────────────────┘
                   │ API
┌──────────────────▼──────────────────┐
│                 Host                │
│                                     │
│  图结构与编排：定义、规划、调整       │
│  运行状态与调度：推进、等待、恢复     │
│  组织资产与经验：检索、积累、复用     │
└──────────────────┬──────────────────┘
                   │ Harness 提供的能力
┌──────────────────▼──────────────────┐
│           DeepSeek Harness          │
│    Agent Runtime、Session、Tools 等  │
└─────────────────────────────────────┘
```

### 2.1 显式的执行组织

工作流不仅是待执行的节点列表，也是对阶段划分、职责分工、依赖关系和结构变化的表达。它既可以由人类预先设计，也可以由父代理根据任务目标与执行情况生成和调整。

图结构提供可检查的组织表达，图上显示的状态即为实际执行过程。架构需要使结构、运行状态与实际行为保持足够的关联，才能支持追踪、审查与干预。

### 2.2 结构与执行状态分离

工作流结构描述组织如何安排，运行状态记录执行进行到哪里，Agent Context 则承载代理当前的对话上下文。三者承担不同职责。

将运行状态与 Agent Context 分离，使执行连续性不必依赖某个代理上下文永久存活，并为代理轮换、上下文重建和运行恢复提供基础。

### 2.3 由父代理驱动的动态编排

父代理是编排决策主体，负责任务拆分、职责分配、执行协调和结构调整；运行时负责执行机制、状态维护以及超时、失败等确定性事实的记录与反馈。

这种分工将语义决策与确定性执行机制分离：运行时不擅自决定业务层面的下一步行动，父代理则依据目标、上下文和运行事实作出编排判断。结构变更通过受控机制完成，而非由任意子代理直接修改。

### 2.4 组织资产与经验复用

组织配置和执行经验可以作为可复用资产，在后续任务中被检索和使用。结合运行反馈与人工确认，系统能够逐步改进组织配置和编排决策，而不必将每次执行都视为一次性过程。

这里的目标是支持可控的持续演进，而不是假定系统能够完全自主且正确地改造自身。

---

## 3. 关键设计取舍

| 设计选择 | 主要收益 | 需要承担的代价 |
| --- | --- | --- |
| 显式图结构，而非完全隐式的 Agent 协作 | 组织关系可观察、可检查、可调整 | 需要维护图结构与实际执行行为的一致性 |
| 父代理驱动，而非完全由确定性引擎推进 | 能根据任务与运行情况动态编排 | 增加模型调用、Token 成本与决策不确定性 |
| 结构、运行状态与 Agent Context 分离 | 支持上下文重建、代理替换与运行恢复 | 增加状态管理与一致性维护的复杂度 |
| 基于 Harness 扩展，而非重建 Agent Runtime | 复用现有运行时能力，减少重复实现 | 编排能力受 Harness 提供的接口与运行机制约束 |
| 组织资产与经验可复用，而非仅依赖单次执行 | 支持跨任务积累与持续改进 | 需要处理经验筛选、适用范围与反馈质量 |

这些取舍并不意味着本项目拥有更好的编排方式。它追求的是一种可配置的编排架构：根据任务的不确定性与控制要求，在结构约束、代理自主性和人工治理之间选择合适的平衡。

---

## 4. 架构不变量

以下约束构成长期架构边界：

1. **Harness 优先。** Agent Runtime 等基础执行能力由 DeepSeek Harness 提供，本项目通过其公开能力扩展，不在插件内重复实现或修改 Harness 核心运行时。
2. **结构与状态分离。** 工作流结构、运行状态和 Agent Context 各自承担明确职责，不以单个代理上下文作为长期执行状态的唯一载体。
3. **结构变更受治理。** 子代理不能直接修改工作流结构；运行中的结构调整由父代理通过受控机制发起。
4. **运行事实与语义决策分离。** 运行时提供可验证的状态与执行事实，编排代理负责基于这些事实进行语义判断。
5. **模板、实例、资产三态分离。** 模板的后续修改不应隐式改变已经创建的运行实例，运行实例和模板也不应影响需要作为长期可复用资源的资产。
6. **演进依赖资产与反馈。** 执行经验和组织配置可以积累、筛选与复用，但运行事实本身不自动等同于有效经验。

以上约束用于界定架构边界与评估设计变更。具体实现以代码和测试为准；当长期架构原则发生变化时，应同步更新本文档。