PyHarness — Everything is a Plugin

万物皆插件。 一个基于 pluggy + Pydantic V2 的极简 Python Agent 框架，对标 DeepSeek Harness。

✨ Features

🚀 Quick Start

# 安装（含全部可选依赖）
pip install pyharness[all]

# 配置 API Key
export DEEPSEEK_API_KEY="sk-..."

# 启动 Web UI
pyharness serve
# → 打开浏览器访问 http://127.0.0.1:3080

CLI 模式

# 单轮对话
pyharness run --provider http -m deepseek-chat -i "Hello"

# 流式 REPL
pyharness chat --provider http -m deepseek-chat

# 查看版本
pyharness version

Python API

from pyharness import Harness, AgentConfig
from pyharness.plugins.llm import entry as llm

# 初始化 Harness（自动加载内置插件）
h = Harness()

# 配置 LLM 提供方
llm.use_http(
    models=("deepseek-chat",),
    base_url="https://api.deepseek.com/v1",
    api_key="sk-...",
)

# 运行 Agent 会话
ctx = await h.run_session(
    AgentConfig(name="demo", model="deepseek-chat"),
    initial_text="用 Python 写一个快速排序",
)

# 流式输出
async for chunk in h.stream_session(
    AgentConfig(name="demo", model="deepseek-chat"),
    initial_text="用 Python 写一个快速排序",
):
    print(chunk.delta, end="")

🏗️ Architecture

graph TD
    subgraph Core["🧠 PyHarness Core"]
        Harness["Harness<br/>(EventBus + Session Lifecycle)"]
        Specs["AgentHooks<br/>(pluggy contract)"]
        Schema["Pydantic V2 Schema<br/>(Frozen + model_copy)"]
    end

    subgraph Plugins["🔌 Plugins"]
        LLM["LLM Provider<br/>(dummy / http / stream)"]
        Tools["Tool Executors<br/>(python / fs / web)"]
        CLI["CLI Plugin<br/>(typer + rich)"]
        WebUI["Web UI Plugin<br/>(FastAPI + WebSocket)"]
        Store["Session Store<br/>(SQLite + FTS5)"]
        Guard["Guard Approval<br/>(human-in-the-loop)"]
        Workflow["Workflow<br/>(Plan + Subagent)"]
    end

    Harness --> Specs
    Harness --> Schema
    Harness --> Plugins

    style Core fill:#1a1a2e,color:#fff,stroke:#e94560,stroke-width:2px
    style Plugins fill:#16213e,color:#fff,stroke:#0f3460,stroke-width:2px

设计哲学：核心只做三件事 —— 事件总线 (pluggy)、上下文管理 (contextvars)、插件加载。所有领域能力（LLM、工具、UI）都通过插件注入。

🛠️ Built-in Plugins

🧪 Testing

# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest tests/ -v

# Lint
ruff check src/ tests/

75 个测试全绿，覆盖 Core、LLM、CLI、Web UI、Workflow、Session Store。

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.