dsh-maf

Readme

# dsh-maf

**Microsoft Agent Framework (MAF) 的 DeepSeek Harness (dsh) 插件** —— 让 dsh 智能体验证、运行和搭建
MAF 的 declarative agents / workflows（YAML 声明式定义）。

> 独立社区项目，非官方。基于 [microsoft/agent-framework](https://github.com/microsoft/agent-framework)（MIT）。
> MAF 是 [Semantic Kernel](https://github.com/microsoft/semantic-kernel) 的企业级继任者（v1.0 已发布）。

## 为什么做

MAF（13k★，Python/.NET）是微软当前的 agent 编排框架，**没有 DSH 适配**。它的核心是
**YAML 声明式 agent/workflow**——正好适合 agent 生成、验证和运行：

| 工具 | 行为 |
|---|---|
| `maf_status` | MAF 包版本 + 环境检查 |
| `maf_validate` | 校验 declarative agent YAML（AgentFactory 解析） |
| `maf_run_agent` | 运行 declarative agent（YAML + prompt） |
| `maf_run_workflow` | 运行 declarative workflow sample（main.py） |
| `maf_scaffold` | 生成 agent/workflow YAML 模板 |

## 前置要求

```bash
pip install agent-framework agent-framework-declarative python-dotenv
```

Agent YAML 的 `model.id` 常引用环境变量（`=Env.OPENAI_CHAT_MODEL_ID`），
运行前配置好 `.env` / 环境变量（provider 密钥）。

## 安装

```yaml
# profile 的 cordis.patch.yml
- insert:
    - id: maf
      name: './src/index.js'
      config:
        pythonCmd: python
        enginePath: scripts/maf.py
```

```bash
pnpm dsh web --patch ./dsh-maf/cordis.patch.yml
```

然后问 agent："maf_status 检查环境，maf_validate 校验 ./agents/Assistant.yaml"。

## 引擎实现

`scripts/maf.py` 包装 MAF SDK：
- `AgentFactory(safe_mode=False).create_agent_from_yaml_path(path)` → `await agent.run(prompt)`
- workflow 用 `python main.py` 标准 sample 布局（workflow.yaml + main.py）

## 配置项

| 键 | 默认 | 说明 |
|---|---|---|
| `pythonCmd` | `python` | Python 解释器 |
| `enginePath` | `scripts/maf.py` | 引擎脚本路径 |
| `timeoutMs` | `180000` | 单次调用超时（agent 运行可能较慢） |

## 已知限制

- `maf_run_agent` / `maf_run_workflow` 消耗配置的 provider API 额度
- declarative agents API 官方标注为 *experimental*（可能变动）
- 输出原样返回（含模型生成内容）

## 目录结构

```
dsh-maf/
  src/index.js            # 5 个工具 + 配置
  scripts/maf.py          # MAF SDK 引擎（status/validate/run/scaffold）
  skills/maf/SKILL.md
  docs/
  cordis.patch.yml
```

## 许可

MIT。