Metadata-Version: 2.4
Name: actflare
Version: 0.4.0
Summary: WeChat Work callback service powered by Claude Agent SDK
License: MIT
Keywords: wechat,wecom,claude,agent,chatbot
Author: Zan Yuan
Author-email: yfinddream@gmail.com
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: claude-agent-sdk (>=0.1.0)
Requires-Dist: click (>=8.0,<9.0)
Requires-Dist: fastapi (>=0.110.0,<0.111.0)
Requires-Dist: httpx (>=0.27.0,<0.28.0)
Requires-Dist: huey (>=2.5.0,<3.0.0)
Requires-Dist: jieba (>=0.42.1,<0.43.0)
Requires-Dist: pycryptodome (>=3.20.0,<4.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: structlog (>=24.0.0,<25.0.0)
Requires-Dist: uvicorn (>=0.29.0,<0.30.0)
Project-URL: Bug Tracker, https://github.com/seqyuan/actflare/issues
Project-URL: Homepage, https://github.com/seqyuan/actflare
Description-Content-Type: text/markdown

# ActFlare

企业微信 (WeChat Work) 回调服务，基于 Claude Agent SDK。接收用户消息，通过 Claude CLI 异步处理，将回复推送回企业微信。

## 特性

- **企业微信对接** — AES-256-CBC 消息加解密、签名校验、回调 URL 验证
- **多账户多模式** — Bot/App 双模式自适应，动态路由注册，多通道并存
- **异步任务队列** — SQLite 驱动的 Huey 队列，无需 Redis
- **Claude Agent SDK** — 可配置工具、系统提示词、环境变量和 CLI 参数
- **多轮对话** — 5 分钟会话窗口，同一用户连续消息自动共享对话历史（最近 10 条）
- **记忆系统** — 自动保存成功案例，关键词匹配+时间衰减检索，后续相似问题注入历史参考
- **用户反馈** — 回复附带任务编号，用户发「评价 xxx 好/不好」零 API 成本更新评分
- **知识蒸馏** — 高评分案例自动聚类生成 skill 草稿，人工审核后升级为正式 skill
- **Skills 系统** — 可编辑的 Markdown 领域知识文件，注入 Agent 上下文，支持自改进
- **结构化日志** — structlog 统一输出，关键字参数结构化，全模块一致
- **API 熔断器** — 连续失败自动熔断 Agent 调用，防止雪崩，60 秒自动恢复探测
- **全链路追踪** — trace_id 从 HTTP 请求生成，贯穿 Huey 队列到消息回复
- **代理友好** — 支持自定义 `ANTHROPIC_BASE_URL` 和模型映射

## 架构

```
用户消息 → 企业微信(加密 POST) → FastAPI(解密验签, 生成 trace_id) → Huey 队列 → 立即响应微信

Worker 取任务 → 会话管理(5min超时) → 查询记忆库 → 拼接对话历史+历史案例
    → 熔断检查 → 调用 Claude CLI → 保存回复到会话 → 截断至 2000 字 → 推送至企业微信
    → 成功案例自动存入记忆库

反馈消息(「评价 xxx 好」) → FastAPI 层拦截 → 直接更新评分(零 API 成本)

trace_id: FastAPI(生成) → Huey(传递) → Worker(日志绑定) → 回复(附带给用户)
```

## 安装

```bash
pip install actflare
```

从源码安装：

```bash
git clone https://github.com/seqyuan/actflare.git
cd actflare
poetry install
```

## 快速开始

### 1. 首次运行

```bash
actflare server
```

首次运行会自动在 `~/.config/actflare/config.yml` 创建默认配置文件，然后编辑它：

```bash
vim ~/.config/actflare/config.yml
```

### 2. 配置必填项

以下字段**必须**修改为你的实际值：

```yaml
paths:
  claude_cli: "/path/to/claude"              # Claude CLI 可执行文件路径

channels:
  wecom:
    enabled: true
    default_account: "bot"
    accounts:
      bot:
        mode: "bot"
        webhook_path: "/wecom/bot"
        token: "your_bot_token"
        encoding_aes_key: "43位Base64编码AES密钥"
        receive_id: "your_bot_receive_id"
      app:
        mode: "app"
        webhook_path: "/wecom/app"
        corpid: "ww1234567890abcdef"
        corpsecret: "your_corpsecret"
        agent_id: 1000002
        token: "your_callback_token"
        encoding_aes_key: "43位Base64编码AES密钥"
```

如果使用代理服务器访问 Claude API，还需配置：

```yaml
agent:
  env:
    ANTHROPIC_BASE_URL: "http://your-proxy:3001"
    ANTHROPIC_AUTH_TOKEN: "your-api-key"
```

### 3. 启动服务

需要同时运行两个进程：API 服务器和任务 Worker。

```bash
# 终端 1 — API 服务器
actflare server

# 终端 2 — 任务 Worker
actflare worker
```

### 4. 配置企业微信回调

在[企业微信管理后台](https://work.weixin.qq.com/)中，将回调 URL 设为配置文件中 `webhook_path` 对应的路径：

- Bot 模式: `http://your-server:8001/wecom/bot`
- App 模式: `http://your-server:8001/wecom/app`

Token 和 EncodingAESKey 填写与配置文件中相同的值。

## 命令参考

### `actflare server`

```bash
actflare server                          # 使用默认配置
actflare server -c /path/to/config.yml   # 指定配置文件
```

### `actflare worker`

```bash
actflare worker                          # 使用默认配置
actflare worker -c /path/to/config.yml   # 指定配置文件
```

### `actflare status`

```bash
actflare status <task_id>                # 查询任务运行状态
```

### `actflare skills`

```bash
actflare skills                          # 列出已加载的 skill 文件
```

### `actflare distill`

```bash
actflare distill                         # 蒸馏高评分案例为 skill 草稿
actflare distill --min-feedback 0.8      # 仅蒸馏评分 >= 0.8 的案例
```

### `actflare memory-stats`

```bash
actflare memory-stats                    # 查看记忆系统统计
```

### `actflare conversation-stats`

```bash
actflare conversation-stats              # 查看会话统计信息
```

### `actflare migrate-config`

```bash
actflare migrate-config                  # 将旧 wechat: 格式迁移为 channels: 格式
```

配置文件查找顺序：

1. `-c` 参数指定的路径
2. `ACTFLARE_CONFIG` 环境变量
3. `~/.config/actflare/config.yml`

## Skills 系统

Skills 是可编辑的 Markdown 知识文件，自动注入 Agent 的 system prompt，让 Agent 掌握公司特有的数据目录规范、路径模式等领域知识。

### 加载顺序

Skills 从两个目录加载（同名文件以全局目录为准）：

1. `~/.config/actflare/skills/` — 全局 skills（默认优先）
2. `{workspace}/skills/` — 项目级 skills（补充）

首次运行时自动从模板创建全局 skills 目录。

### 自改进机制

Agent 拥有 Edit/Write 权限，可以直接修改 skill 文件。当 Agent 在实践中发现更准确的规律（如新的路径模式、目录结构变更），会自动更新对应的 skill 文件，形成 **memory 记住具体案例 + skill 记住通用规律** 的双层知识体系。

### 知识蒸馏

高评分的 memory 案例可通过 `actflare distill` 或 Huey 定时任务（每周日 3AM）自动聚类生成 skill 草稿，保存到 `~/.config/actflare/skills/drafts/`。审核后移入正式 skills 目录即可生效。

### 添加新 Skill

在 `~/.config/actflare/skills/` 目录下创建 `.md` 文件即可：

```bash
vim ~/.config/actflare/skills/my_knowledge.md
```

**注意**: skills 文件可能包含公司内部路径等敏感信息，已在 `.gitignore` 中排除。

## 配置说明

完整示例见 [`config.example.yml`](config.example.yml)。

`paths` 中的相对路径基于配置文件所在目录解析（即 `~/.config/actflare/`）。

### paths

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `claude_cli` | (必填) | Claude CLI 可执行文件的绝对路径 |
| `huey_db` | (必填) | Huey 任务队列 SQLite 数据库 |
| `workspace` | (必填) | Claude Agent 文件操作的工作目录 |
| `memory_db` | `./data/memory.db` | 记忆系统 SQLite 数据库 |
| `workdir` | `./workdir` | 任务根目录 |
| `task_db` | `./data/task.db` | 任务跟踪 SQLite 数据库 |
| `conversation_db` | `./data/conversation.db` | 多轮对话会话 SQLite 数据库 |

### channels

多账户多模式的通道配置。每个 channel 下可配置多个 account，每个 account 独立注册路由。

```yaml
channels:
  wecom:
    enabled: true
    default_account: "bot"
    accounts:
      bot:
        mode: "bot"                    # Bot 模式: response_url 回复
        webhook_path: "/wecom/bot"
        token: "..."
        encoding_aes_key: "..."
        receive_id: "..."
      app:
        mode: "app"                    # App 模式: access_token API 回复
        webhook_path: "/wecom/app"
        corpid: "..."
        corpsecret: "..."
        agent_id: 1000002
        token: "..."
        encoding_aes_key: "..."
```

| 字段 | 模式 | 说明 |
|------|------|------|
| `mode` | 共用 | `"bot"` 或 `"app"` |
| `webhook_path` | 共用 | 回调 URL 路径，如 `/wecom/bot` |
| `token` | 共用 | 回调验证 Token |
| `encoding_aes_key` | 共用 | 43 位 Base64 编码 AES 密钥 |
| `receive_id` | Bot | 机器人接收 ID |
| `corpid` | App | 企业微信 Corp ID |
| `corpsecret` | App | 应用 Secret |
| `agent_id` | App | 应用 AgentID (整数) |

敏感字段支持环境变量覆盖: `ACTFLARE_{ACCOUNT}_CORPID`、`ACTFLARE_{ACCOUNT}_CORPSECRET`、`ACTFLARE_{ACCOUNT}_TOKEN`。

### agent

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `max_turns` | `10` | 单次请求最大 Agent 轮次 |
| `allowed_tools` | `[Read, Glob, Grep, Bash, Edit, Write]` | Agent 可用工具列表 |
| `system_prompt` | `你是企业内部开发助手...` | 系统提示词 |
| `permission_mode` | `default` | 权限模式: `default`, `acceptEdits`, `bypassPermissions` |
| `model` | `null` | 模型覆盖，`null` 使用 SDK 默认值 |
| `env` | `{}` | 注入 Claude CLI 子进程的环境变量 |
| `cli_args` | `[]` | 追加到 Claude CLI 的额外参数 |

### server / worker

| 字段 | 默认值 | 说明 |
|------|--------|------|
| `server.host` | `0.0.0.0` | 服务器绑定地址 |
| `server.port` | `8001` | 服务器端口 |
| `worker.concurrency` | `2` | Worker 并发数 |
| `worker.worker_type` | `process` | `process` 或 `thread` |

## 开发

```bash
git clone https://github.com/seqyuan/actflare.git
cd actflare
poetry install
poetry run pytest
poetry run black actflare/
```

## License

MIT

