@coremail/lunkr-openclaw 1.0.0 → 1.0.2

package/docs/DEVELOPMENT.md

@@ -1,239 +0,0 @@
-# Lunkr Extension 开发指南
-
-本文档提供 Lunkr 扩展的完整开发、测试和部署命令参考。
-
-## 快速参考
-
-| 场景 | 命令 |
-|------|------|
-| 安装依赖 | `npm install` |
-| 运行测试 | `npm test` |
-| 测试监视模式 | `npm run test:watch` |
-| 编译 | `npm run build` |
-| 快速部署 | `npm run deploy:local` |
-| 完整部署 | `npm run deploy:local:full` |
-| 打包发布 | `npm run pack` |
-
-## 开发工作流
-
-### 1. 日常开发
-
-```bash
-# 终端 1: 运行测试监视器
-npm run test:watch
-
-# 终端 2: 编辑代码...
-# 测试会自动运行
-```
-
-### 2. 调试 CLI 命令
-
-直接运行 TypeScript，无需编译：
-
-```bash
-# 使用 tsx 直接运行
-npx tsx src/bin/lunkr-cli.ts status
-npx tsx src/bin/lunkr-cli.ts login --email your@email.com
-npx tsx src/bin/lunkr-cli.ts search-contact test
-```
-
-### 3. 在 OpenClaw 中测试
-
-```bash
-# 快速部署（假设已编译）
-npm run deploy:local
-
-# 或完整流程：清理 → 测试 → 编译 → 部署
-npm run deploy:local:full
-
-# 测试
-openclaw lunkr status
-```
-
-## 命令详解
-
-### 开发命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm run dev` | 热重载开发模式（监视文件变化） |
-| `npm run dev:cli` | 直接运行 CLI（不编译） |
-
-### 测试命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm test` | 运行所有测试 |
-| `npm run test:watch` | 监视模式，文件变化自动重跑 |
-| `npm run lint` | 代码检查 |
-
-### 构建命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm run clean` | 清理 dist/ 目录 |
-| `npm run build` | 编译 TypeScript → dist/ |
-| `npm run build:release` | 生产构建（esbuild 打包） |
-
-### 部署命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm run deploy:local` | 快速部署到本地 OpenClaw（仅复制） |
-| `npm run deploy:local:full` | 完整部署：clean → test → build → deploy |
-
-### 发布命令
-
-| 命令 | 说明 |
-|------|------|
-| `npm run pack` | 打包为 .tgz 文件 |
-| `npm publish` | 发布到 npm registry |
-
-## 部署目标配置
-
-默认部署路径：
-```
-~/work/ai/openclaw/extensions/lunkr
-```
-
-可通过环境变量自定义：
-
-```bash
-# 自定义 OpenClaw 根目录
-export OPENCLAW_ROOT=/path/to/openclaw
-npm run deploy:local
-
-# 或自定义扩展目录
-export OPENCLAW_EXT=/custom/extensions/path
-npm run deploy:local
-```
-
-## 典型工作日
-
-```bash
-# 早上开始工作
-cd extensions/lunkr
-npm run test:watch          # 终端 1: 开着测试
-
-# 编写代码...
-# 测试自动运行
-
-# 中午想集成测试
-npm run deploy:local        # 快速部署（跳过测试，因为刚才测过了）
-
-# 继续开发...
-
-# 下班前提交
-npm run deploy:local:full   # 完整流程确保没问题
-```
-
-## 发布流程
-
-### 版本管理
-
-使用语义化版本号 (SemVer)：`MAJOR.MINOR.PATCH`
-
-```bash
-# 补丁版本 - bug fixes
-npm version patch   # 1.0.0 → 1.0.1
-
-# 小版本 - 新功能，向后兼容
-npm version minor   # 1.0.1 → 1.1.0
-
-# 大版本 - 破坏性变更
-npm version major   # 1.1.0 → 2.0.0
-```
-
-`npm version` 命令会：
-1. 更新 `package.json` 中的版本号
-2. 自动创建 git commit
-3. 自动创建 git tag
-
-### 打包测试
-
-```bash
-# 打包为 tar.gz
-npm run pack
-
-# 输出: coremail-lunkr-openclaw-1.0.0.tgz
-
-# 在其他地方测试安装
-npm install ./coremail-lunkr-openclaw-1.0.0.tgz
-```
-
-### 发布到 npm
-
-```bash
-# 1. 确保测试通过
-npm test
-
-# 2. 提升版本号
-npm version patch  # 或 minor / major
-
-# 3. 推送代码和标签
-git push --follow-tags
-
-# 4. 发布到 npm
-npm publish --access public
-```
-
-## 项目结构
-
-```
-extensions/lunkr/
-├── src/                    # TypeScript 源码
-│   ├── adapters/           # OpenClaw 适配器
-│   ├── cli/                # CLI 命令
-│   ├── core/               # 核心逻辑
-│   ├── i18n/               # 国际化
-│   ├── internal/           # 内部模块
-│   └── index.ts            # 入口
-├── dist/                   # 编译输出
-├── skills/                 # OpenClaw 技能
-├── docs/                   # 文档
-├── scripts/                # 构建脚本
-│   ├── deploy-local.mjs    # 本地部署
-│   └── build-release.js    # 生产构建
-├── package.json
-├── tsconfig.json
-└── README.md
-```
-
-## 环境要求
-
-- **Node.js**: v22+
-- **npm**: v10+
-- **TypeScript**: v5+
-
-## 故障排除
-
-### 编译失败
-
-```bash
-# 清理后重试
-npm run clean
-npm run build
-```
-
-### 部署后不生效
-
-```bash
-# 确保 OpenClaw gateway 重启
-openclaw gateway restart
-
-# 或重启整个服务
-openclaw restart
-```
-
-### 测试失败
-
-```bash
-# 查看详细输出
-npm test -- --reporter=verbose
-```
-
-## 相关文档
-
-- [README.md](../README.md) - 项目介绍和配置
-- [USAGE.md](./USAGE.md) - 使用指南
-- [AUTHENTICATION.md](./AUTHENTICATION.md) - 认证说明

package/docs/USAGE.md

@@ -1,337 +0,0 @@
-# Lunkr Channel Plugin - Usage Guide
-
-This document provides detailed information on using the Lunkr channel plugin for OpenClaw.
-
-## Bot Simulation
-
-The Lunkr plugin simulates a bot by using the authenticated user's account to send and receive messages. This approach is called "Bot Simulation" because:
-
-1. **The bot is you**: The AI responds using your Lunkr account
-2. **Bot replies are marked**: Bot messages are prefixed with `[@!BotName]` to distinguish them from your regular messages
-3. **Self-triggering**: In normal chats, you trigger the bot by sending a message that starts with the command prefix
-
-### How Bot Simulation Works
-
-```
-User (You)                    Lunkr Server                   OpenClaw
-   |                              |                              |
-   |-- "Hello" ----------------->|                              |
-   |                              |                              |
-   |                              |-- "Hello" ------------------>|
-   |                              |                              |
-   |                              |    (Bot triggers AI)         |
-   |                              |                              |
-   |                              |<-- "[@!Bot] Hi there!" ------|
-   |                              |                              |
-   |<-- "[@!Bot] Hi there!" ------|                              |
-```
-
-## Trigger Rules
-
-The bot triggers based on where the message is sent and who sends it.
-
-### Bot Discussions (Recommended)
-
-Bot Discussions are dedicated discussion groups where **all messages** trigger the AI agent.
-
-```
-+---------------------------+
-|  Bot Discussion Group     |
-|                           |
-|  Alice: How do I reset?   | --> Triggers AI
-|  Bob: Check settings      | --> Triggers AI
-|  Bot: [@!Bot] To reset... | --> Does NOT trigger (bot reply)
-+---------------------------+
-```
-
-**Setup:**
-```yaml
-channels:
-  lunkr:
-    botDiscussions:
-      "group-id-abc123":
-        name: "AI Assistant"
-        creatorUid: "admin-uid"
-        createdAt: "2024-01-01T00:00:00Z"
-```
-
-### Normal Groups and DMs
-
-In regular groups and direct messages, only **you** can trigger the bot by prefixing your message with the command prefix (default: `/bot`).
-
-```
-+---------------------------+
-|  Regular Group Chat       |
-|                           |
-|  Alice: Hello everyone    | --> No trigger
-|  Bob: /bot What is AI?    | --> Triggers AI (if Bob is you)
-|  You: /bot Explain X      | --> Triggers AI
-|  Bot: [@!Bot] X is...     | --> Does NOT trigger (bot reply)
-+---------------------------+
-```
-
-### Trigger Summary Table
-
-| Scenario | Message From | Message Content | Triggers AI? |
-|----------|-------------|-----------------|--------------|
-| Bot Discussion | Anyone | Anything | Yes |
-| Bot Discussion | You (Bot reply) | `[@!BotName] ...` | No |
-| Normal Group/DM | You | `/bot help` | Yes |
-| Normal Group/DM | You | `Hello` | No |
-| Normal Group/DM | Others | `/bot help` | No |
-| Normal Group/DM | Others | `Hello` | No |
-
-## Configuration Reference
-
-### Complete Configuration Schema
-
-```yaml
-channels:
-  lunkr:
-    # Enable this channel
-    enabled: true
-
-    # Bot display name (appears in bot replies)
-    botName: "AI Assistant"
-
-    # Command prefix for normal chats
-    commandPrefix: "/bot"
-
-    # Bot discussion groups (all messages trigger AI)
-    botDiscussions:
-      "discussion-id-1":
-        name: "Support Channel"
-        agentId: "support-agent"    # Optional: route to specific agent
-        creatorUid: "user-123"
-        createdAt: "2024-01-15T10:30:00Z"
-
-    # Direct message policy
-    dmPolicy: "allow"              # allow | deny | whitelist
-    allowFrom:                     # Whitelisted users (for dmPolicy: whitelist)
-      - "user-id-1"
-      - "user-id-2"
-
-    # Group message policy
-    groupPolicy: "allow"           # allow | deny | whitelist
-    groups:                        # Whitelisted groups (for groupPolicy: whitelist)
-      - "group-id-1"
-      - "group-id-2"
-```
-
-### Policy Values
-
-#### `dmPolicy`
-
-| Value | Description |
-|-------|-------------|
-| `allow` | Accept DMs from all users (default) |
-| `deny` | Reject all DMs to the bot |
-| `whitelist` | Only accept DMs from users in `allowFrom` list |
-
-#### `groupPolicy`
-
-| Value | Description |
-|-------|-------------|
-| `allow` | Respond in all groups when triggered (default) |
-| `deny` | Never respond in groups |
-| `whitelist` | Only respond in groups in `groups` list |
-
-### Bot Discussion Configuration
-
-Each bot discussion entry requires:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Display name for this discussion |
-| `agentId` | string | No | Agent ID to route messages to |
-| `creatorUid` | string | Yes | User ID of the creator |
-| `createdAt` | string/number | Yes | Creation timestamp (ISO or epoch ms) |
-
-## Multi-Agent Routing
-
-You can route different Bot Discussions to different AI agents:
-
-```yaml
-# In your OpenClaw config
-agents:
-  sales-agent:
-    # Sales-specific agent configuration
-  support-agent:
-    # Support-specific agent configuration
-
-channels:
-  lunkr:
-    botDiscussions:
-      "sales-group-id":
-        name: "Sales Bot"
-        agentId: "sales-agent"
-        creatorUid: "admin"
-        createdAt: "2024-01-01"
-      "support-group-id":
-        name: "Support Bot"
-        agentId: "support-agent"
-        creatorUid: "admin"
-        createdAt: "2024-01-01"
-```
-
-When a message arrives in a Bot Discussion with an `agentId` configured, it is automatically routed to that specific agent.
-
-## Message Handling
-
-### Inbound Messages
-
-Messages from Lunkr are processed as follows:
-
-1. **Receive**: Message arrives via Socket.IO real-time connection
-2. **Analyze**: Determine if message should trigger the bot
-3. **Convert**: Transform Lunkr format to OpenClaw format
-4. **Route**: Send to appropriate agent for processing
-
-### Outbound Messages
-
-Bot replies are formatted with the `[@!BotName]` prefix:
-
-```
-[@!AI Assistant] Here is my response to your question...
-```
-
-This prefix helps distinguish bot messages from your regular messages.
-
-### Message Types Supported
-
-| Type | Support |
-|------|---------|
-| Text | Full support |
-| Images | Supported |
-| Files | Supported |
-| Reactions | Supported |
-| Edits | Supported |
-| Replies | Supported |
-
-## Security Considerations
-
-### Bot Reply Detection
-
-The plugin identifies bot replies by checking if:
-- The message is from the authenticated user (self)
-- The content starts with `[@!<botName>]`
-
-These messages are never re-processed by the bot to prevent loops.
-
-### Self-Message Triggering
-
-In normal chats, only messages from the authenticated user that start with the command prefix trigger the bot. This prevents:
-- Accidental triggers from other users
-- Message loops from bot replies
-
-### Whitelist Security
-
-When using whitelist policies:
-
-```yaml
-dmPolicy: whitelist
-allowFrom:
-  - "trusted-user-1"
-  - "trusted-user-2"
-```
-
-Only messages from whitelisted users will be processed.
-
-### Pairing Flow
-
-Users can request to be whitelisted via pairing:
-
-1. User sends a pairing request
-2. Admin approves with: `openclaw pairing approve lunkr <code>`
-3. User's ID is added to `allowFrom`
-
-## Examples
-
-### Example 1: Simple Bot Discussion
-
-```yaml
-channels:
-  lunkr:
-    enabled: true
-    botName: "Helper"
-    botDiscussions:
-      "abc123":
-        name: "Help Channel"
-        creatorUid: "admin"
-        createdAt: "2024-01-01"
-```
-
-Any message in group `abc123` triggers the bot.
-
-### Example 2: Restricted DM Access
-
-```yaml
-channels:
-  lunkr:
-    enabled: true
-    dmPolicy: whitelist
-    allowFrom:
-      - "user-001"
-      - "user-002"
-    groupPolicy: deny
-```
-
-Only `user-001` and `user-002` can DM the bot. No group messages are processed.
-
-### Example 3: Multi-Agent Setup
-
-```yaml
-agents:
-  code-reviewer:
-    model: "claude-3"
-    systemPrompt: "You are a code reviewer..."
-
-  translator:
-    model: "gpt-4"
-    systemPrompt: "You are a translator..."
-
-channels:
-  lunkr:
-    botDiscussions:
-      "code-review-group":
-        name: "Code Reviews"
-        agentId: "code-reviewer"
-        creatorUid: "dev-team"
-        createdAt: 1704067200000
-      "translation-group":
-        name: "Translations"
-        agentId: "translator"
-        creatorUid: "intl-team"
-        createdAt: 1704067200000
-```
-
-### Example 4: Custom Command Prefix
-
-```yaml
-channels:
-  lunkr:
-    enabled: true
-    commandPrefix: "!"
-```
-
-Now use `! help` instead of `/bot help` to trigger the bot in normal chats.
-
-## Troubleshooting
-
-### Bot Not Responding in Bot Discussion
-
-1. Verify the discussion ID matches your configuration
-2. Check that the message is not a bot reply (starts with `[@!...]`)
-3. Review gateway logs for errors
-
-### Wrong Agent Receiving Messages
-
-1. Check the `agentId` in the bot discussion configuration
-2. Verify the agent ID exists in your agents configuration
-3. Check for typos in the discussion ID mapping
-
-### DM Whitelist Not Working
-
-1. Ensure `dmPolicy` is set to `whitelist` (not `allow`)
-2. Verify user IDs in `allowFrom` are correct
-3. Remember to restart the gateway after config changes