actflare 0.1.3__tar.gz

actflare-0.1.3/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: actflare
+Version: 0.1.3
+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: pycryptodome (>=3.20.0,<4.0.0)
+Requires-Dist: pyyaml (>=6.0,<7.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 验证
+- **异步任务队列** — SQLite 驱动的 Huey 队列，无需 Redis
+- **Claude Agent SDK** — 可配置工具、系统提示词、环境变量和 CLI 参数
+- **记忆系统** — 自动保存多轮成功案例，后续相似问题时注入历史参考
+- **代理友好** — 支持自定义 `ANTHROPIC_BASE_URL` 和模型映射
+- **工具调度** — 通过 YAML 注册表将生物信息学工具调度到 annoeva 或 annotask 执行
+- **Skills 系统** — 可编辑的领域知识文件，注入 Agent 上下文，支持自改进
+
+## 架构
+
+```
+用户消息 → 企业微信(加密 POST) → FastAPI(解密验签) → Huey 队列 → 立即响应微信
+
+Worker 取任务 → 查询记忆库 → 拼接历史案例 → 调用 Claude CLI
+    → 收集结果 → 截断至 2000 字 → 推送至企业微信 → 用户收到回复
+    → 多轮成功案例自动存入记忆库
+```
+
+## 安装
+
+```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 可执行文件路径
+
+wechat:
+  corpid: "ww1234567890abcdef"               # 企业 ID
+  token: "your_callback_token"               # 回调 Token
+  encoding_aes_key: "43位Base64编码AES密钥"   # 回调 EncodingAESKey
+  agent_id: 1000002                          # 应用 AgentID
+  corpsecret: "your_corpsecret"              # 应用 Secret
+```
+
+如果使用代理服务器访问 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 设为：
+
+```
+http://your-server:8001/callback
+```
+
+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 tools`
+
+```bash
+actflare tools                           # 列出所有已注册的工具
+```
+
+### `actflare dispatch`
+
+```bash
+actflare dispatch scrna_pipeline                 # annoeva 工具（无需输入文件）
+actflare dispatch bindiff /data/tasks.sh         # annotask 工具（需要输入文件）
+```
+
+### `actflare status`
+
+```bash
+actflare status <task_id>                        # 查询任务运行状态
+```
+
+### `actflare skills`
+
+```bash
+actflare skills                                  # 列出已加载的 skill 文件
+```
+
+配置文件查找顺序：
+
+1. `-c` 参数指定的路径
+2. `ACTFLARE_CONFIG` 环境变量
+3. `~/.config/actflare/config.yml`
+
+## 工具注册与调度
+
+actflare 通过 YAML 注册表管理可调度的生物信息学工具。Claude Agent 自动识别已注册工具，用户通过自然语言请求即可触发执行。
+
+### 注册表位置
+
+```
+~/.config/actflare/tools.yml
+```
+
+首次运行 `actflare tools` 或 `actflare dispatch` 时从模板自动创建。
+
+### 工具分类
+
+工具只有两种后端：
+
+| 后端 | 执行命令 | 说明 |
+|------|---------|------|
+| `annoeva` | `annoeva addproject -p <task_id> -t <type> -d <workdir>` | 项目级流水线管理 |
+| `annotask` | `annotask qsubsge/local <tool_path> -i <infile> ...` | 并行任务执行 |
+
+### 注册新工具
+
+编辑 `tools.yml`，在 `tools:` 下添加条目：
+
+**annoeva 工具** — 只需 `description`、`backend`、`type`：
+
+```yaml
+tools:
+  scrna_pipeline:
+    description: "单细胞 RNA-seq 全流程分析"
+    backend: annoeva
+    type: scrna
+```
+
+**annotask 工具 (qsubsge)** — 需要 `tool_path`，固定参数 `line`、`cpu`、`h_vmem`：
+
+```yaml
+  bindiff:
+    description: "差异基因分析（SGE 集群并行）"
+    backend: annotask
+    tool_path: "/path/to/bindiff"
+    mode: qsubsge
+    line: 2
+    cpu: 2
+    h_vmem: 8
+```
+
+**annotask 工具 (local)** — 需要 `tool_path`，固定参数 `line`、`thread`：
+
+```yaml
+  bindiff_local:
+    description: "差异基因分析（本地并行）"
+    backend: annotask
+    tool_path: "/path/to/bindiff"
+    mode: local
+    line: 1
+    thread: 4
+```
+
+### 目录自动创建
+
+调度任务时自动创建工作目录（基于 `config.yml` 中的 `workdir` 配置）：
+
+- **annoeva 任务**: `{workdir}/annoeva/{task_id}/` 含 `Analysis/`、`info/info.xls`、`Filter/GO.sign`
+- **annotask 任务**: `{workdir}/annotask/{task_id}/`
+
+### 任务跟踪
+
+每次调度自动生成唯一任务 ID（如 `scrna_pipeline_20260223_a1b2c3`）并记录到 SQLite 数据库，支持状态查询：
+
+```bash
+actflare status scrna_pipeline_20260223_a1b2c3
+```
+
+### 调度方式
+
+**CLI 手动调度：**
+
+```bash
+actflare dispatch scrna_pipeline                   # annoeva 流水线
+actflare dispatch bindiff /data/tasks.sh           # annotask 集群任务
+```
+
+**Agent 自动调度：**
+
+已注册工具会自动注入 Agent 的系统提示词。用户在企业微信中发送类似「帮我跑一下单细胞分析」的消息，Agent 会自动识别并调用对应工具。
+
+## Skills 系统
+
+Skills 是可编辑的 Markdown 知识文件，自动注入 Agent 的 system prompt，让 Agent 掌握公司特有的数据目录规范、路径模式等领域知识。
+
+### 加载顺序
+
+Skills 从两个目录加载（同名文件以全局目录为准）：
+
+1. `~/.config/actflare/skills/` — 全局 skills（默认优先）
+2. `{workspace}/skills/` — 项目级 skills（补充）
+
+首次运行时自动从模板创建全局 skills 目录。
+
+### 内置 Skill
+
+| 文件 | 内容 |
+|------|------|
+| `data_io.md` | 数据 I/O 规范：项目目录结构、分析/过滤目录位置、云端路径、CellRanger 数据 |
+
+### 自改进机制
+
+Agent 拥有 Edit/Write 权限，可以直接修改 skill 文件。当 Agent 在实践中发现更准确的规律（如新的路径模式、目录结构变更），会自动更新对应的 skill 文件，形成 **memory 记住具体案例 + skill 记住通用规律** 的双层知识体系。
+
+### 添加新 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` | `./data/huey.db` | Huey 任务队列 SQLite 数据库 |
+| `memory_db` | `./data/memory.db` | 记忆系统 SQLite 数据库 |
+| `workspace` | `./workspace` | Claude Agent 文件操作的工作目录 |
+| `tools_yml` | (空) | 工具注册表路径，空则使用 `~/.config/actflare/tools.yml` |
+| `workdir` | `./workdir` | 任务根目录（annoeva/annotask 任务在此创建） |
+| `task_db` | `./data/task.db` | 任务跟踪 SQLite 数据库 |
+
+### wechat
+
+| 字段 | 说明 |
+|------|------|
+| `corpid` | 企业微信 Corp ID |
+| `token` | 回调验证 Token |
+| `encoding_aes_key` | 43 位 Base64 编码 AES 密钥 |
+| `agent_id` | 应用 AgentID (整数) |
+| `corpsecret` | 应用 Secret |
+
+### agent
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `max_turns` | `10` | 单次请求最大 Agent 轮次 |
+| `allowed_tools` | `[Read, Glob, Grep, Bash, Edit, Write]` | Agent 可用工具列表 |
+| `system_prompt` | `你是企业内部开发助手...` | 系统提示词 |
+| `permission_mode` | `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
+

actflare-0.1.3/README.md

@@ -0,0 +1,329 @@
+# ActFlare
+
+企业微信 (WeChat Work) 回调服务，基于 Claude Agent SDK。接收用户消息，通过 Claude CLI 异步处理，将回复推送回企业微信。
+
+## 特性
+
+- **企业微信对接** — AES-256-CBC 消息加解密、签名校验、回调 URL 验证
+- **异步任务队列** — SQLite 驱动的 Huey 队列，无需 Redis
+- **Claude Agent SDK** — 可配置工具、系统提示词、环境变量和 CLI 参数
+- **记忆系统** — 自动保存多轮成功案例，后续相似问题时注入历史参考
+- **代理友好** — 支持自定义 `ANTHROPIC_BASE_URL` 和模型映射
+- **工具调度** — 通过 YAML 注册表将生物信息学工具调度到 annoeva 或 annotask 执行
+- **Skills 系统** — 可编辑的领域知识文件，注入 Agent 上下文，支持自改进
+
+## 架构
+
+```
+用户消息 → 企业微信(加密 POST) → FastAPI(解密验签) → Huey 队列 → 立即响应微信
+
+Worker 取任务 → 查询记忆库 → 拼接历史案例 → 调用 Claude CLI
+    → 收集结果 → 截断至 2000 字 → 推送至企业微信 → 用户收到回复
+    → 多轮成功案例自动存入记忆库
+```
+
+## 安装
+
+```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 可执行文件路径
+
+wechat:
+  corpid: "ww1234567890abcdef"               # 企业 ID
+  token: "your_callback_token"               # 回调 Token
+  encoding_aes_key: "43位Base64编码AES密钥"   # 回调 EncodingAESKey
+  agent_id: 1000002                          # 应用 AgentID
+  corpsecret: "your_corpsecret"              # 应用 Secret
+```
+
+如果使用代理服务器访问 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 设为：
+
+```
+http://your-server:8001/callback
+```
+
+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 tools`
+
+```bash
+actflare tools                           # 列出所有已注册的工具
+```
+
+### `actflare dispatch`
+
+```bash
+actflare dispatch scrna_pipeline                 # annoeva 工具（无需输入文件）
+actflare dispatch bindiff /data/tasks.sh         # annotask 工具（需要输入文件）
+```
+
+### `actflare status`
+
+```bash
+actflare status <task_id>                        # 查询任务运行状态
+```
+
+### `actflare skills`
+
+```bash
+actflare skills                                  # 列出已加载的 skill 文件
+```
+
+配置文件查找顺序：
+
+1. `-c` 参数指定的路径
+2. `ACTFLARE_CONFIG` 环境变量
+3. `~/.config/actflare/config.yml`
+
+## 工具注册与调度
+
+actflare 通过 YAML 注册表管理可调度的生物信息学工具。Claude Agent 自动识别已注册工具，用户通过自然语言请求即可触发执行。
+
+### 注册表位置
+
+```
+~/.config/actflare/tools.yml
+```
+
+首次运行 `actflare tools` 或 `actflare dispatch` 时从模板自动创建。
+
+### 工具分类
+
+工具只有两种后端：
+
+| 后端 | 执行命令 | 说明 |
+|------|---------|------|
+| `annoeva` | `annoeva addproject -p <task_id> -t <type> -d <workdir>` | 项目级流水线管理 |
+| `annotask` | `annotask qsubsge/local <tool_path> -i <infile> ...` | 并行任务执行 |
+
+### 注册新工具
+
+编辑 `tools.yml`，在 `tools:` 下添加条目：
+
+**annoeva 工具** — 只需 `description`、`backend`、`type`：
+
+```yaml
+tools:
+  scrna_pipeline:
+    description: "单细胞 RNA-seq 全流程分析"
+    backend: annoeva
+    type: scrna
+```
+
+**annotask 工具 (qsubsge)** — 需要 `tool_path`，固定参数 `line`、`cpu`、`h_vmem`：
+
+```yaml
+  bindiff:
+    description: "差异基因分析（SGE 集群并行）"
+    backend: annotask
+    tool_path: "/path/to/bindiff"
+    mode: qsubsge
+    line: 2
+    cpu: 2
+    h_vmem: 8
+```
+
+**annotask 工具 (local)** — 需要 `tool_path`，固定参数 `line`、`thread`：
+
+```yaml
+  bindiff_local:
+    description: "差异基因分析（本地并行）"
+    backend: annotask
+    tool_path: "/path/to/bindiff"
+    mode: local
+    line: 1
+    thread: 4
+```
+
+### 目录自动创建
+
+调度任务时自动创建工作目录（基于 `config.yml` 中的 `workdir` 配置）：
+
+- **annoeva 任务**: `{workdir}/annoeva/{task_id}/` 含 `Analysis/`、`info/info.xls`、`Filter/GO.sign`
+- **annotask 任务**: `{workdir}/annotask/{task_id}/`
+
+### 任务跟踪
+
+每次调度自动生成唯一任务 ID（如 `scrna_pipeline_20260223_a1b2c3`）并记录到 SQLite 数据库，支持状态查询：
+
+```bash
+actflare status scrna_pipeline_20260223_a1b2c3
+```
+
+### 调度方式
+
+**CLI 手动调度：**
+
+```bash
+actflare dispatch scrna_pipeline                   # annoeva 流水线
+actflare dispatch bindiff /data/tasks.sh           # annotask 集群任务
+```
+
+**Agent 自动调度：**
+
+已注册工具会自动注入 Agent 的系统提示词。用户在企业微信中发送类似「帮我跑一下单细胞分析」的消息，Agent 会自动识别并调用对应工具。
+
+## Skills 系统
+
+Skills 是可编辑的 Markdown 知识文件，自动注入 Agent 的 system prompt，让 Agent 掌握公司特有的数据目录规范、路径模式等领域知识。
+
+### 加载顺序
+
+Skills 从两个目录加载（同名文件以全局目录为准）：
+
+1. `~/.config/actflare/skills/` — 全局 skills（默认优先）
+2. `{workspace}/skills/` — 项目级 skills（补充）
+
+首次运行时自动从模板创建全局 skills 目录。
+
+### 内置 Skill
+
+| 文件 | 内容 |
+|------|------|
+| `data_io.md` | 数据 I/O 规范：项目目录结构、分析/过滤目录位置、云端路径、CellRanger 数据 |
+
+### 自改进机制
+
+Agent 拥有 Edit/Write 权限，可以直接修改 skill 文件。当 Agent 在实践中发现更准确的规律（如新的路径模式、目录结构变更），会自动更新对应的 skill 文件，形成 **memory 记住具体案例 + skill 记住通用规律** 的双层知识体系。
+
+### 添加新 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` | `./data/huey.db` | Huey 任务队列 SQLite 数据库 |
+| `memory_db` | `./data/memory.db` | 记忆系统 SQLite 数据库 |
+| `workspace` | `./workspace` | Claude Agent 文件操作的工作目录 |
+| `tools_yml` | (空) | 工具注册表路径，空则使用 `~/.config/actflare/tools.yml` |
+| `workdir` | `./workdir` | 任务根目录（annoeva/annotask 任务在此创建） |
+| `task_db` | `./data/task.db` | 任务跟踪 SQLite 数据库 |
+
+### wechat
+
+| 字段 | 说明 |
+|------|------|
+| `corpid` | 企业微信 Corp ID |
+| `token` | 回调验证 Token |
+| `encoding_aes_key` | 43 位 Base64 编码 AES 密钥 |
+| `agent_id` | 应用 AgentID (整数) |
+| `corpsecret` | 应用 Secret |
+
+### agent
+
+| 字段 | 默认值 | 说明 |
+|------|--------|------|
+| `max_turns` | `10` | 单次请求最大 Agent 轮次 |
+| `allowed_tools` | `[Read, Glob, Grep, Bash, Edit, Write]` | Agent 可用工具列表 |
+| `system_prompt` | `你是企业内部开发助手...` | 系统提示词 |
+| `permission_mode` | `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

actflare-0.1.3/actflare/__init__.py

@@ -0,0 +1,14 @@
+"""
+ActFlare: WeChat Work callback service powered by Claude Agent SDK.
+
+Receives messages from WeChat Work, processes them asynchronously via
+Claude Agent SDK, and pushes replies back to WeChat Work.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Zan Yuan"
+__email__ = "yfinddream@gmail.com"
+
+from actflare.config import load_config, get_config
+
+__all__ = ["load_config", "get_config"]