actflare 0.4.0

WeChat Work callback service powered by Claude Agent SDK

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(日志绑定) → 回复(附带给用户)

安装

pip install actflare

从源码安装：

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

快速开始

1. 首次运行

actflare server

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

vim ~/.config/actflare/config.yml

2. 配置必填项

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

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，还需配置：

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

3. 启动服务

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

# 终端 1 — API 服务器
actflare server

# 终端 2 — 任务 Worker
actflare worker

4. 配置企业微信回调

在企业微信管理后台中，将回调 URL 设为配置文件中 webhook_path 对应的路径：

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

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

命令参考

actflare server

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

actflare worker

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

actflare status

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

actflare skills

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

actflare distill

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

actflare memory-stats

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

actflare conversation-stats

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

actflare migrate-config

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 文件即可：

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

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

配置说明

完整示例见 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 独立注册路由。

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

开发

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

License

MIT