# charness

**Repository Path**: zytcloud/charness

## Basic Information

- **Project Name**: charness
- **Description**: Charness is a local-first agent harness with tool calling, sessions, and a self-hosted runtime.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-11
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Charness

本地优先的 Agent Harness（Go）。自研 ReAct Loop、Graph Engine、Plan-and-Execute、IM Gateway，可 CLI / HTTP / MCP / IM 多渠道运行。

**文档**：[docs/](docs/README.md) · [官网](website/index.html) · [安装/发版](docs/release.md) · [CHANGELOG](CHANGELOG.md)

[![Release](https://img.shields.io/badge/release-v0.3.0-cyan)](https://gitee.com/zytcloud/charness/releases/tag/v0.3.0)

## 特性概览

| 类别 | 能力 |
|------|------|
| 运行时 | ReAct Loop、Plan-and-Execute（并行 Subagent）、YAML 工作流（条件边 / 并行 / 子图 / Checkpoint） |
| 工具 | 文件/Shell/Git/补丁/代码搜索、`delegate_task`、`run_plugin`、MCP Client（stdio + 远程 URL） |
| 入口 | CLI、`charness serve`（REST + SSE + 可选 MCP）、`charness mcp serve`（stdio / HTTP / SSE）、IM Gateway |
| 渠道 | 钉钉 Stream、飞书 WebSocket、Telegram、Discord；IM 流式回复 |
| 平台 | Run 审计、自动化 API、MCP 远程托管、语义化版本、`make release` 五平台打包 |

## 安装

**预编译包**（推荐）：从 [Gitee Releases v0.3.0](https://gitee.com/zytcloud/charness/releases/tag/v0.3.0) 下载对应平台附件，详见 [docs/release.md](docs/release.md)。

| 平台 | 文件 |
|------|------|
| macOS Intel | `charness_0.3.0_darwin_amd64.tar.gz` |
| macOS Apple Silicon | `charness_0.3.0_darwin_arm64.tar.gz` |
| Linux amd64 | `charness_0.3.0_linux_amd64.tar.gz` |
| Linux arm64 | `charness_0.3.0_linux_arm64.tar.gz` |
| Windows x64 | `charness_0.3.0_windows_amd64.zip` |

## 快速开始

```bash
make build   # 或 go build -o charness ./cmd/charness
./charness config init
export OPENAI_API_KEY=sk-...

./charness chat                              # TTY 默认流式
./charness chat --toolset coding --workspace ~/myproject
./charness serve                             # HTTP API
./charness gateway start                     # IM 渠道
./charness mcp serve --transport streamable-http --addr 0.0.0.0:8090
```

配置与数据：`~/.charness/`（`config.yaml`、`sessions/`、`skills/`、`mcp.json`）。

## 命令

| 命令 | 说明 |
|------|------|
| `charness chat` | 终端交互；`-p` `--mode` `--toolset` `--workspace` |
| `charness serve` | HTTP API；`http.mcp_enabled` 可共存 MCP |
| `charness gateway start` | IM；`http.enabled=true` 可共存 API |
| `charness mcp serve` | MCP Server：`--transport stdio\|streamable-http\|sse` |
| `charness mcp list` | MCP Client 连接（本地 + 远程） |
| `charness graph run` | YAML 工作流；`--checkpoint-dir` `--resume` |
| `charness graph info` | Graph Engine 能力 |
| `charness config init` | 初始化配置 |
| `charness version` | 版本与构建信息（`--json`） |
| `make release` | 交叉编译五平台包到 `dist/` |

开发者指南：[AGENTS.md](AGENTS.md)

## HTTP API

默认 `127.0.0.1:8080`。鉴权：`Authorization: Bearer <http.api_key>`。

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/health` | 健康检查 |
| POST | `/v1/chat` | 对话（`stream` `mode` `toolset`） |
| POST | `/v1/chat/cancel` | 取消对话 |
| GET/DELETE | `/v1/sessions/{id}` | 会话 |
| GET | `/v1/sessions/{id}/runs` | Run 审计 |
| GET | `/v1/runs/{id}/events` | Run 事件 |
| POST | `/v1/hooks/{name}` | Webhook（async 返回 `task_id`） |
| GET | `/v1/automation/tasks` | 自动化任务列表 |
| GET/PUT/DELETE | `/v1/automation/webhooks\|schedules` | 动态自动化 |
| GET | `/v1/tools` | 工具列表 |

SSE：`stream: true` 或 `Accept: text/event-stream`。详见 [docs/automation.md](docs/automation.md)。

## MCP

**Server**（对外暴露 Agent）— 本地 stdio 或远程 HTTP：

```bash
# Cursor 本地
charness mcp serve --toolset coding

# 远程托管
charness mcp serve --transport streamable-http --addr 0.0.0.0:8090 --api-key $KEY
```

**Client**（消费外部工具）— `~/.charness/mcp.json`：

```json
{
  "servers": [
    { "name": "shell", "command": "npx", "args": ["-y", "mcp-shell"] },
    {
      "name": "remote",
      "url": "https://mcp.example.com/mcp",
      "transport": "streamable-http",
      "headers": { "Authorization": "Bearer ${TOKEN}" }
    }
  ]
}
```

详见 [docs/mcp-remote.md](docs/mcp-remote.md)。

## IM 渠道

| 渠道 | 文档 | 说明 |
|------|------|------|
| 飞书 | [docs/feishu.md](docs/feishu.md) | WebSocket，国内可用 |
| 钉钉 | AGENTS.md | Stream，国内可用 |
| Telegram | [docs/telegram.md](docs/telegram.md) | Bot 长轮询 |
| Discord | [docs/discord.md](docs/discord.md) | Gateway + Intent |

## YAML 工作流

```yaml
entry: classify
nodes:
  - id: classify
    type: prompt
    message: "分类：{{input}}"
    output: category
  - id: deep
    type: chat
    message: "深入：{{category}}"
  - id: quick
    type: prompt
    message: "简要回复"
edges:
  - from: classify
    to: deep
    when: "category == complex"
  - from: classify
    to: quick
```

```bash
charness graph run wf.yaml -i "分析代码" --checkpoint-dir ~/.charness/checkpoints
```

详见 [docs/workflow.md](docs/workflow.md)。

## 配置示例

```yaml
provider:
  model: gpt-4o
  fast_model: gpt-4o-mini

http:
  enabled: true
  api_key: ${CHARNESS_API_KEY}
  mcp_enabled: true
  mcp_transport: streamable-http

automation:
  webhook_secret: ${WEBHOOK_SECRET}
  notify_url: https://example.com/hooks/fail
  schedules:
    - name: daily
      at: "09:00"
      timezone: Asia/Shanghai
      message: "每日摘要"

channels:
  feishu:
    enabled: true
    app_id: ${FEISHU_APP_ID}
    app_secret: ${FEISHU_APP_SECRET}
    toolset: safe
```

## 架构

```
CLI / HTTP / MCP / IM → Gateway → Runtime → Loop / Planner → session + audit
```

模块：`internal/agent` · `internal/graph` · `internal/workflow` · `internal/gateway` · `internal/api` · `internal/mcpserver` · `internal/automation`

## License

[MIT License](LICENSE)