flashclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GuLu9527
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,305 @@
+# ⚡ FlashClaw
+
+> 闪电龙虾 - 快如闪电的 AI 助手
+
+<p align="center">
+  <img src="assets/flashclaw-logo.png" alt="FlashClaw" width="400">
+</p>
+
+## 特点
+
+- ⚡ **快速响应** - 直接 API 调用，2-5 秒响应
+- 🧱 **乐高式架构** - 通讯渠道和工具都是可插拔的插件
+- 🔥 **热加载** - 运行时加载插件，无需重启
+- 🇨🇳 **中国本土** - 飞书原生支持
+- 🤖 **智能响应** - 群聊 @提及、私聊自动回复
+- 📅 **定时任务** - 支持 cron、间隔、一次性任务，具备精确定时、并发控制、超时保护和自动重试
+
+## 安装
+
+```bash
+npm install -g flashclaw
+```
+
+## 快速开始
+
+```bash
+# 启动服务
+flashclaw start
+```
+
+## 更新日志
+
+详见 [CHANGELOG.md](CHANGELOG.md)
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `flashclaw` | 启动服务（默认） |
+| `flashclaw start` | 启动服务 |
+| `flashclaw version` | 显示版本 |
+| `flashclaw -v` / `flashclaw --version` | 显示版本（快捷方式） |
+| `flashclaw help` | 显示帮助 |
+| `flashclaw -h` / `flashclaw --help` | 显示帮助（快捷方式） |
+| `flashclaw plugins list` | 列出已安装插件 |
+| `flashclaw plugins list --available` | 列出可安装插件 |
+| `flashclaw plugins install <name>` | 安装插件 |
+| `flashclaw plugins uninstall <name>` | 卸载插件 |
+| `flashclaw plugins update <name>` | 更新插件 |
+| `flashclaw plugins update --all` | 更新所有插件 |
+| `flashclaw config list-backups` | 列出配置备份 |
+| `flashclaw config restore [n]` | 恢复配置备份（n=1-5） |
+
+**安装插件示例：**
+
+```bash
+# 从官方仓库安装
+flashclaw plugins install hello-world
+flashclaw plugins install web-fetch
+```
+
+## 插件系统
+
+FlashClaw 采用乐高式插件架构，添加功能就像放 Minecraft Mod 一样简单：
+
+```
+plugins/
+├── feishu/          # 飞书渠道插件
+├── send-message/    # 发送消息工具
+├── schedule-task/   # 创建定时任务
+├── list-tasks/      # 列出定时任务
+├── cancel-task/     # 取消定时任务
+├── pause-task/      # 暂停定时任务
+├── resume-task/     # 恢复定时任务
+├── memory/          # 长期记忆（remember/recall）
+├── register-group/  # 注册群组
+└── my-plugin/       # 你的自定义插件
+```
+
+### 插件类型
+
+| 类型 | 说明 | 示例 |
+|------|------|------|
+| `channel` | 消息渠道插件 | 飞书、Telegram、Slack |
+| `tool` | AI 工具插件 | 发送消息、定时任务 |
+
+### 创建插件
+
+1. 在 `~/.flashclaw/plugins/` 创建文件夹
+2. 添加 `plugin.json` 和 `index.ts`
+3. 重启服务（开发模式下会自动热加载）
+
+详见 [FLASHCLAW.md](FLASHCLAW.md)
+
+## 配置
+
+配置文件位于 `~/.flashclaw/.env`（首次运行自动创建）。
+
+**特性：**
+- 支持环境变量替换：`${VAR}` 或 `${VAR:-default}`
+- 自动备份：每次修改前自动保存备份（最多 5 个）
+- 使用 `flashclaw config restore` 恢复误操作
+
+```bash
+# AI API 配置（三选一）
+# 方式1：Anthropic 官方 API（两者任选其一）
+ANTHROPIC_AUTH_TOKEN=sk-ant-xxx
+ANTHROPIC_API_KEY=sk-ant-xxx
+
+# 方式2：API 代理（如 MiniMax）
+ANTHROPIC_BASE_URL=https://api.minimaxi.com/anthropic
+ANTHROPIC_AUTH_TOKEN=your-token
+AI_MODEL=MiniMax-M2.1
+ANTHROPIC_MODEL=claude-4-5-sonnet-20250929
+
+# 飞书配置
+FEISHU_APP_ID=cli_xxx
+FEISHU_APP_SECRET=xxx
+
+# 其他配置
+BOT_NAME=FlashClaw
+LOG_LEVEL=info
+TIMEZONE=Asia/Shanghai
+```
+
+## 架构
+
+### 用户数据目录
+
+安装后，FlashClaw 在用户主目录创建配置文件夹：
+
+```
+~/.flashclaw/                 # Windows: C:\Users\用户名\.flashclaw\
+├── .env                     # API 密钥和配置
+├── config/
+│   └── plugins.json         # 插件启用/禁用配置
+├── data/
+│   ├── flashclaw.db         # SQLite 数据库
+│   └── flashclaw.pid        # 进程 PID
+├── logs/
+│   └── flashclaw.log        # 运行日志
+├── plugins/                 # 用户自定义插件
+└── groups/                  # 群组记忆
+```
+
+### 项目结构
+
+```
+flashclaw/
+├── src/                      # 核心源码
+│   ├── index.ts             # 主入口、消息路由
+│   ├── cli.ts               # 命令行接口
+│   ├── commands.ts          # 聊天命令处理
+│   ├── session-tracker.ts   # Token 用量追踪
+│   ├── paths.ts             # 路径管理
+│   ├── agent-runner.ts      # AI Agent 运行器
+│   ├── db.ts                # SQLite 数据库
+│   ├── task-scheduler.ts    # 定时任务调度
+│   ├── core/                # 核心模块
+│   │   ├── api-client.ts    # AI API 客户端
+│   │   ├── memory.ts        # 记忆管理
+│   │   └── model-capabilities.ts  # 模型能力检测
+│   └── plugins/             # 插件系统
+│       ├── manager.ts       # 插件管理器
+│       ├── loader.ts        # 插件加载器
+│       ├── installer.ts     # 插件安装器
+│       └── types.ts         # 插件类型定义
+│
+├── plugins/                  # 内置插件（9个）
+│   ├── feishu/              # 飞书渠道
+│   ├── memory/              # 长期记忆
+│   ├── schedule-task/       # 定时任务
+│   ├── list-tasks/          # 列出任务
+│   ├── cancel-task/         # 取消任务
+│   ├── pause-task/          # 暂停任务
+│   ├── resume-task/         # 恢复任务
+│   ├── send-message/        # 发送消息
+│   └── register-group/      # 注册群组
+│
+└── community-plugins/        # 社区/官方扩展插件
+    ├── hello-world/         # 测试插件
+    └── web-fetch/           # 网页内容获取
+```
+
+> community-plugins 作为扩展插件库示例，默认不随 npm 包发布，可通过插件安装命令单独获取。
+
+## 功能特性
+
+### 智能响应
+
+- **私聊**：直接回复，无需触发词
+- **群聊**：@机器人 触发响应
+- **自动注册**：新会话自动注册，无需手动配置
+
+### 聊天命令
+
+在对话中使用斜杠命令快速操作：
+
+| 命令 | 说明 |
+|------|------|
+| `/help` | 显示帮助信息 |
+| `/status` | 查看会话状态和 Token 用量 |
+| `/new` | 重置当前会话 |
+| `/compact` | 压缩上下文（生成摘要） |
+| `/tasks` | 查看定时任务 |
+| `/ping` | 测试机器人响应 |
+
+**上下文管理：**
+- 系统会实时统计 Token 使用量
+- 达到 70% (140k tokens) 时自动提示
+- 使用 `/compact` 可手动压缩，保留摘要继续对话
+- 使用 `/new` 完全重置会话
+
+### 多模态支持
+
+- **文本消息**：完整支持
+- **图片消息**：自动检测模型能力，不支持时提示用户
+- **文件消息**：识别文件名和类型
+- **富文本**：支持飞书富文本消息解析
+
+### 定时任务
+
+支持三种调度方式：
+- **cron** - 使用 cron 表达式（如 `0 9 * * *` 每天 9 点）
+- **interval** - 固定间隔执行（毫秒数）
+- **once** - 一次性任务（ISO 时间字符串）
+
+**核心特性：**
+- **精确定时器** - 按需唤醒，而非固定轮询，资源占用极低
+- **并发控制** - 最多同时执行 3 个任务，避免资源耗尽
+- **超时保护** - 默认 5 分钟超时，防止任务卡死
+- **自动重试** - 失败任务自动重试，使用指数退避策略（默认最多 3 次）
+
+```
+用户：每天早上9点提醒我喝水
+AI：好的，已创建定时任务（任务ID: task_xxx，下次执行: 2024-02-04 09:00:00）
+
+用户：创建一个每30分钟检查一次的任务，最多重试5次
+AI：已创建任务，配置：间隔 30 分钟，最大重试 5 次
+
+用户：我有哪些任务？
+AI：你有以下定时任务：
+    1. 每日喝水提醒 (cron: 0 9 * * *, 下次: 2024-02-04 09:00:00)
+
+用户：取消任务1
+AI：已取消任务
+```
+
+### 记忆系统
+
+FlashClaw 支持多层级记忆：
+
+| 层级 | 存储位置 | 作用域 |
+|------|----------|--------|
+| **用户记忆** | `~/.flashclaw/data/memory/users/{userId}.md` | 跨会话共享，同一用户在私聊和群聊中记忆互通 |
+| **会话记忆** | `~/.flashclaw/data/memory/{chatId}.md` | 单个会话内有效 |
+| **全局记忆** | `~/.flashclaw/groups/global/CLAUDE.md` | 所有会话共享的系统提示 |
+
+```
+用户（私聊）：记住我喜欢吃苹果
+AI：好的，已记住
+
+用户（群聊）：我喜欢吃什么？
+AI：你喜欢吃苹果  ← 跨会话记忆生效
+```
+
+## 平台支持
+
+| 平台 | 状态 |
+|------|------|
+| Windows | ✅ 原生运行 |
+| Linux | ✅ 原生运行 |
+| macOS | ✅ 原生运行 |
+
+## 消息平台
+
+| 平台 | 状态 | 连接方式 |
+|------|------|----------|
+| 飞书 | ✅ 完整支持 | WebSocket 长连接 |
+| Telegram | 📋 计划中 | - |
+| Slack | 📋 计划中 | - |
+| Discord | 📋 计划中 | - |
+
+**注意**：所有平台都使用长连接，**无需公网服务器**！
+
+## 安全说明
+
+FlashClaw 的 AI Agent 直接在本机运行，**可以访问所有文件和执行命令**。这是为个人助手设计的，请确保：
+
+- 只在可信环境运行
+- 只添加可信的群组
+- 定期检查 AI 的操作日志
+
+## 文档
+
+- [开发规则](FLASHCLAW.md) - 插件开发指南
+- [设计要求](docs/REQUIREMENTS.md) - 架构决策
+- [API 文档](docs/API.md) - 内部 API
+- [技术规格](docs/SPEC.md) - 详细规格
+- [安全模型](docs/SECURITY.md) - 安全说明
+- [贡献指南](CONTRIBUTING.md) - 如何贡献
+
+## 许可证
+
+MIT

package/config/plugins.json

@@ -0,0 +1,23 @@
+{
+  "plugins": {
+    "feishu": {
+      "enabled": true
+    },
+    "send-message": {
+      "enabled": true
+    },
+    "schedule-task": {
+      "enabled": true
+    },
+    "list-tasks": {
+      "enabled": true
+    },
+    "cancel-task": {
+      "enabled": true
+    },
+    "memory": {
+      "enabled": true
+    }
+  },
+  "hotReload": true
+}

package/dist/agent-runner.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Agent Runner for FlashClaw
+ * 使用 Anthropic SDK 直接调用 API
+ *
+ * Features:
+ * - Direct Anthropic API integration
+ * - IPC-based tools for messaging and task scheduling
+ * - Per-group isolation via working directories
+ * - 记忆系统集成
+ */
+import { RegisteredGroup } from './types.js';
+import { ToolSchema } from './core/api-client.js';
+import { MemoryManager } from './core/memory.js';
+/**
+ * 图片附件
+ */
+export interface ImageAttachment {
+    type: 'image';
+    /** base64 data URL 或纯 base64 数据 */
+    content: string;
+    mimeType?: string;
+}
+export interface AgentInput {
+    prompt: string;
+    sessionId?: string;
+    groupFolder: string;
+    chatJid: string;
+    isMain: boolean;
+    isScheduledTask?: boolean;
+    /** 用户 ID，用于用户级别记忆 */
+    userId?: string;
+    /** 图片附件列表 */
+    attachments?: ImageAttachment[];
+}
+export interface AgentOutput {
+    status: 'success' | 'error';
+    result: string | null;
+    newSessionId?: string;
+    error?: string;
+}
+/**
+ * IPC 上下文
+ */
+interface IpcContext {
+    chatJid: string;
+    groupFolder: string;
+    isMain: boolean;
+    userId: string;
+}
+/**
+ * 工具执行结果
+ */
+interface ToolResult {
+    content: string;
+    isError?: boolean;
+}
+/**
+ * 获取所有可用工具（完全依赖插件）
+ */
+export declare function getAllTools(): ToolSchema[];
+/**
+ * 创建工具执行器
+ * 完全依赖插件工具
+ */
+export declare function createToolExecutor(ctx: IpcContext, memoryManager: MemoryManager): (name: string, params: unknown) => Promise<ToolResult>;
+/**
+ * 获取全局记忆管理器
+ * 使用 memory.ts 中的全局单例
+ */
+export declare function getMemoryManager(): MemoryManager;
+interface RetryConfig {
+    maxRetries: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    retryableErrors: string[];
+}
+/**
+ * 运行 Agent（带重试）
+ */
+export declare function runAgent(group: RegisteredGroup, input: AgentInput, retryConfig?: RetryConfig): Promise<AgentOutput>;
+export declare function writeTasksSnapshot(groupFolder: string, isMain: boolean, tasks: Array<{
+    id: string;
+    groupFolder: string;
+    prompt: string;
+    schedule_type: string;
+    schedule_value: string;
+    status: string;
+    next_run: string | null;
+}>): void;
+export interface AvailableGroup {
+    jid: string;
+    name: string;
+    lastActivity: string;
+    isRegistered: boolean;
+}
+/**
+ * Write available groups snapshot for the agent to read.
+ * Only main group can see all available groups (for activation).
+ * Non-main groups only see their own registration status.
+ */
+export declare function writeGroupsSnapshot(groupFolder: string, isMain: boolean, groups: AvailableGroup[], registeredJids: Set<string>): void;
+export {};
+//# sourceMappingURL=agent-runner.d.ts.map

package/dist/agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../src/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAWH,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAA0B,UAAU,EAAuC,MAAM,sBAAsB,CAAC;AAE/G,OAAO,EAAE,aAAa,EAA8C,MAAM,kBAAkB,CAAC;AAU7F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,OAAO,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qBAAqB;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa;IACb,WAAW,CAAC,EAAE,eAAe,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC;IAC5B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAID;;GAEG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AA0BD;;GAEG;AACH,wBAAgB,WAAW,IAAI,UAAU,EAAE,CAE1C;AAGD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,IAuBhE,MAAM,MAAM,EAAE,QAAQ,OAAO,KAAG,OAAO,CAAC,UAAU,CAAC,CAuClE;AAID;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,aAAa,CAEhD;AAOD,UAAU,WAAW;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAuID;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,UAAU,EACjB,WAAW,GAAE,WAAkC,GAC9C,OAAO,CAAC,WAAW,CAAC,CAqCtB;AA+RD,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,KAAK,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB,CAAC,GACD,IAAI,CAYN;AAED,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,cAAc,EAAE,EACxB,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,GAC1B,IAAI,CAYN"}