@vibe-lark/larkpal 0.1.27 → 0.1.28

package/README.md

@@ -0,0 +1,333 @@
+# LarkPal 外部接入规范
+
+本文档描述外部业务方接入 LarkPal 平台时需遵循的协议和配置规范。
+
+---
+
+## 目录
+
+1. [环境变量配置](#环境变量配置)
+2. [Agent Completion API（作为 AI 能力消费方）](#agent-completion-api)
+3. [Chat 流式对话 API（多端 Agent Chat）](#chat-流式对话-api)
+4. [RuntimeAdapter 接口（自定义 AI 引擎）](#runtimeadapter-接口)
+5. [MCP 扩展配置（仅 CC 模式）](#mcp-扩展配置)
+6. [网关路由总览](#网关路由总览)
+
+---
+
+## 环境变量配置
+
+### 必填
+
+| 变量名 | 用途 | 示例 |
+|--------|------|------|
+| `LARK_APP_ID` | 飞书应用 App ID | `cli_xxx` |
+| `LARK_APP_SECRET` | 飞书应用 App Secret | - |
+| `ANTHROPIC_API_KEY` | Anthropic API Key（CC Runtime 需要） | `sk-ant-xxx` |
+
+### 可选
+
+| 变量名 | 用途 | 默认值 |
+|--------|------|--------|
+| `LARKPAL_RUNTIME` | 切换 RuntimeAdapter 实现 | `claude-code` |
+| `CLAUDE_MODEL` | 指定 LLM 模型名 | CC 默认模型 |
+| `LARKPAL_WORKSPACE` | 工作目录根路径 | `~/.larkpal/workspace` |
+| `LARKPAL_GATEWAY_HOST` | 网关监听地址 | `localhost` |
+| `LARKPAL_EXTERNAL_URL` | 外部可访问的网关 URL | - |
+| `LARKPAL_PUBLIC_URL` | OAuth 回调公开 URL | `http://localhost:3000` |
+| `LARKPAL_API_SECRET` | Agent Completion API 鉴权密钥 | `dev-internal-secret` |
+| `LARKPAL_COMPLETION_CWD` | Agent Completion 工作目录 | `/tmp/larkpal-completion` |
+| `LARKPAL_CC_IDLE_TIMEOUT` | CC 进程空闲超时（秒） | `0`（永不超时） |
+| `LARKPAL_ENCRYPTION_KEY` | 用户凭证加密密钥（32字节 hex） | 未设置（明文，仅限开发） |
+| `LARKPAL_PLUGINS` | 声明式加载的插件列表 | 空 |
+| `LARKPAL_CHAT_JWT_SECRET` | Chat API JWT 签名密钥 | fallback 到 `LARKPAL_API_SECRET` |
+
+### larkpal-agent Runtime 专用（LARKPAL_RUNTIME=larkpal-agent 时必填）
+
+| 变量名 | 用途 | 示例 |
+|--------|------|------|
+| `LARKPAL_AGENT_LLM_BASE_URL` | 火山方舟 LLM 端点 | `https://ark.cn-beijing.volces.com/api/v3` |
+| `LARKPAL_AGENT_LLM_API_KEY` | 火山方舟 API Key | - |
+| `LARKPAL_AGENT_LLM_MODEL` | 模型 endpoint ID | `ep-20250327140538-xxxxx` |
+| `LARKPAL_AGENT_MAX_TURNS` | Agent 最大对话轮数（可选） | `25` |
+
+---
+
+## Agent Completion API
+
+外部业务方作为 AI 能力消费方，调用 LarkPal 的通用 AI 补全接口。
+
+### 请求
+
+```http
+POST /api/agent/completion
+Content-Type: application/json
+X-Internal-Secret: {LARKPAL_API_SECRET}
+X-Callback-Url: https://your-server/callback  (可选，有则为异步模式)
+
+{
+  "taskId": "your-unique-task-id",
+  "task": "extract",                          // 可选，仅日志用
+  "prompt": "请分析以下文档...",
+  "files": [                                  // 可选，附件
+    { "name": "doc.txt", "contentBase64": "..." }
+  ],
+  "options": {
+    "maxTurns": 10,                           // 可选
+    "resultFileName": "output.json"           // 可选，优先读取 CC 写入的此文件
+  }
+}
+```
+
+### 同步模式响应
+
+无 `X-Callback-Url` 时，等待执行完成后返回：
+
+```json
+{ "code": 0, "mode": "sync", "result": "分析结果..." }
+```
+
+### 异步模式
+
+有 `X-Callback-Url` 时，立即返回：
+
+```json
+{ "code": 0, "mode": "async", "message": "accepted" }
+```
+
+完成后 POST 回调到你的 URL：
+
+```json
+{ "taskId": "xxx", "status": "success", "result": "..." }
+// 或
+{ "taskId": "xxx", "status": "failed", "error": "timeout" }
+```
+
+---
+
+## Chat 流式对话 API
+
+为外部客户端（Web、移动端、桌面端等）提供流式 Agent Chat 能力，支持多会话管理和多端消息同步。
+
+### 鉴权流程
+
+1. 客户端通过飞书 OAuth 获取用户身份
+2. 调用 LarkPal 签发 JWT：
+
+```http
+POST /api/chat/auth
+X-Internal-Secret: {LARKPAL_API_SECRET}
+Content-Type: application/json
+
+{ "tenantKey": "xxx", "userId": "user_xxx", "openId": "ou_xxx" }
+```
+
+响应：
+```json
+{ "token": "eyJ...", "expiresAt": 1234567890 }
+```
+
+3. 后续所有 Chat API 请求携带：`Authorization: Bearer {token}`
+
+### 会话管理
+
+**列出会话**
+```http
+GET /api/chat/sessions
+Authorization: Bearer {token}
+```
+
+**创建会话**
+```http
+POST /api/chat/sessions
+Authorization: Bearer {token}
+Content-Type: application/json
+
+{ "title": "知识库诊断" }
+```
+
+**删除会话**
+```http
+DELETE /api/chat/sessions/{sessionId}
+Authorization: Bearer {token}
+```
+
+### 流式对话（SSE）
+
+```http
+POST /api/chat/stream
+Authorization: Bearer {token}
+Content-Type: application/json
+Accept: text/event-stream
+
+{
+  "session_id": "可选，不传则自动创建",
+  "prompt": "帮我诊断知识库质量",
+  "options": { "maxTurns": 10 }
+}
+```
+
+**SSE 事件流**：
+
+| 事件 | 说明 | data 示例 |
+|------|------|-----------|
+| `text-delta` | AI 回复文本增量 | `{"text": "好的"}` |
+| `thinking-delta` | AI 思考过程增量 | `{"text": "我需要先..."}` |
+| `tool-use-start` | 开始调用工具 | `{"toolName": "list-spaces", "input": {...}}` |
+| `tool-result` | 工具调用结果 | `{"toolUseId": "xxx"}` |
+| `tool-progress` | 工具执行进度 | `{"toolName": "xxx", "elapsedSeconds": 5}` |
+| `turn-end` | 单轮结束 | `{"stopReason": "end_turn"}` |
+| `done` | 对话完成 | `{"sessionId": "xxx", "durationMs": 3200}` |
+| `error` | 错误 | `{"message": "..."}` |
+
+### 历史消息
+
+```http
+GET /api/chat/history?session_id={id}&cursor={msgId}&limit=50
+Authorization: Bearer {token}
+```
+
+返回该会话的完整消息历史（含飞书端和客户端两侧的消息）。
+
+### 多端同步说明
+
+- 消息 `channel` 字段标识来源通道：如 `'feishu-bot'`（飞书机器人端）、`'web'`（Web 客户端）、`'mobile'`（移动端）等
+- 客户端始终能看到完整对话（含飞书端触发的消息）
+- 飞书端仅显示飞书端的消息（受限于飞书 API，无法向 bot 会话注入外部消息）
+- 用户通过 `openId` 关联，同一用户在不同端共享会话列表
+
+---
+
+## RuntimeAdapter 接口
+
+自定义 AI 引擎需实现以下接口：
+
+```typescript
+interface RuntimeAdapter {
+  readonly name: string;
+
+  // 执行 prompt，通过 callbacks 流式返回结果
+  executePrompt(config: RuntimeStartConfig, callbacks: RuntimeStreamCallbacks): Promise<void>;
+
+  // 停止指定会话
+  stopProcess(sessionId: string): Promise<void>;
+
+  // 停止所有会话
+  stopAll(): Promise<void>;
+
+  // 查询会话进程信息
+  getProcessInfo(sessionId: string): RuntimeProcessInfo | undefined;
+  getAllProcessInfo(): RuntimeProcessInfo[];
+}
+```
+
+### RuntimeStartConfig
+
+```typescript
+interface RuntimeStartConfig {
+  sessionId: string;
+  cwd: string;
+  prompt: string | CCContentBlock[];
+  maxTurns?: number;
+  maxBudgetUsd?: number;
+  model?: string;
+  userContext?: UserContext;
+}
+```
+
+### RuntimeStreamCallbacks
+
+```typescript
+interface RuntimeStreamCallbacks {
+  onTextDelta?: (text: string) => void;
+  onThinkingDelta?: (text: string) => void;
+  onToolUseStart?: (toolName: string, toolInput: unknown) => void;
+  onToolResult?: (toolUseId: string) => void;
+  onToolProgress?: (toolName: string, elapsedSeconds: number) => void;
+  onTurnEnd?: (stopReason: string) => void;
+  onResult?: (result: RuntimeResultMessage) => void;
+  onError?: (error: Error) => void;
+}
+```
+
+### 切换 Runtime
+
+通过环境变量切换：
+
+```bash
+LARKPAL_RUNTIME=claude-code      # 默认，使用 Claude Code 子进程
+LARKPAL_RUNTIME=larkpal-agent    # 使用 larkpal-agent 引擎（火山方舟 LLM）
+```
+
+使用 `larkpal-agent` 时的完整配置示例：
+
+```bash
+LARKPAL_RUNTIME=larkpal-agent
+LARKPAL_AGENT_LLM_BASE_URL=https://ark.cn-beijing.volces.com/api/v3
+LARKPAL_AGENT_LLM_API_KEY=your-api-key
+LARKPAL_AGENT_LLM_MODEL=ep-20250327140538-xxxxx
+LARKPAL_AGENT_MAX_TURNS=25
+```
+
+**工具发现**：由 larkpal-agent 自身的 MCP Client 负责。larkpal-agent 启动时自动连接配置的 MCP Server，发现并注册外部工具。larkpal 平台层不涉及工具层。
+
+**systemPrompt 来源**：读取 `~/.claude/CLAUDE.md` 文件内容。可通过修改此文件自定义 Agent 人设。
+
+---
+
+## MCP 扩展配置（仅 CC 模式）
+
+LarkPal 在 CC 模式下作为 MCP Client 代理层，支持双层 MCP Server 配置合并。larkpal-agent 模式下工具发现由 Agent 自身 MCP Client 负责。
+
+| 层级 | 路径 | 说明 |
+|------|------|------|
+| 全局 | `~/.claude/mcp-servers.json` | 所有用户共享的 MCP Server |
+| 用户私有 | `{workspace}/users/{userId}/mcp-servers.json` | 用户自定义（优先级更高） |
+
+配置格式：
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "npx",
+      "args": ["-y", "my-mcp-server"],
+      "env": { "API_KEY": "xxx" }
+    },
+    "remote-server": {
+      "url": "http://localhost:8080/mcp/sse"
+    }
+  }
+}
+```
+
+合并规则：用户配置同名 key 覆盖全局配置。
+
+---
+
+## 网关路由总览
+
+| 路由 | 方法 | 功能 |
+|------|------|------|
+| `/api/agent/completion` | POST | 通用 AI 补全（外部主接入点） |
+| `/api/chat/auth` | POST | 签发 Chat JWT |
+| `/api/chat/stream` | POST | SSE 流式对话 |
+| `/api/chat/sessions` | GET/POST | 会话列表 / 创建会话 |
+| `/api/chat/sessions/:id` | DELETE | 删除会话 |
+| `/api/chat/history` | GET | 会话历史消息 |
+| `/api/execute` | POST | 单次执行（飞书会话绑定） |
+| `/api/execute/batch` | POST | 批量执行 |
+| `/api/execute/:taskId` | GET | 查询任务状态 |
+| `/api/execute/:taskId/cancel` | POST | 取消任务 |
+| `/api/skills/*` | - | 技能管理 |
+| `/api/scheduled-tasks` | - | 定时任务 CRUD |
+| `/hooks/*` | POST | 飞书事件 Hook 接收 |
+
+---
+
+## 安全注意事项
+
+1. `LARK_APP_SECRET` 启动后从 `process.env` 中删除，防止子进程继承
+2. `ANTHROPIC_API_KEY` 保留（CC 子进程需要），但通过 `settings.json` deny 规则禁止 CC 通过 shell 读取
+3. `LARKPAL_API_SECRET` 用于 Agent Completion API 鉴权，生产环境务必设置强密钥
+4. 用户凭证加密需设置 `LARKPAL_ENCRYPTION_KEY`（32 字节 hex/base64），否则明文存储

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-lark/larkpal",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "LarkPal - Lark/Feishu bot service",
   "type": "module",
   "main": "./dist/main.mjs",
@@ -45,6 +45,9 @@
     "uuid": "^11.1.0",
     "zod": "^4.3.6"
   },
+  "optionalDependencies": {
+    "@vibe-lark/larkpal-agent": "^0.1.0"
+  },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/express": "^5.0.2",

package/dist/cli.mjs

@@ -1,85 +0,0 @@
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-//#region src/cli.ts
-/**
-* LarkPal CLI 入口 — 子命令路由
-*
-* 用法:
-*   larkpal            启动服务（凭证未配置时自动进入初始化流程）
-*   larkpal init       交互式初始化向导
-*   larkpal --help     显示帮助信息
-*   larkpal --version  显示版本号
-*
-* 不依赖 commander / yargs 等外部包，仅使用 process.argv 解析。
-*/
-const CYAN = "\x1B[36m";
-const DIM = "\x1B[2m";
-const BOLD = "\x1B[1m";
-const YELLOW = "\x1B[33m";
-const RESET = "\x1B[0m";
-function getVersion() {
-	try {
-		const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-		return JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? "unknown";
-	} catch {
-		return "unknown";
-	}
-}
-function printHelp() {
-	const version = getVersion();
-	console.log(`
-${BOLD}LarkPal${RESET} ${DIM}v${version}${RESET} — 飞书 AI Bot 服务
-
-${BOLD}用法:${RESET}
-  larkpal              启动服务
-  larkpal init         交互式初始化向导
-  larkpal --help       显示帮助信息
-  larkpal --version    显示版本号
-
-${BOLD}环境变量:${RESET}
-  LARK_APP_ID          飞书应用 App ID（可选，覆盖 lark-cli 配置）
-  LARK_APP_SECRET      飞书应用 App Secret（可选，覆盖 lark-cli 配置）
-  LARKPAL_WORKSPACE    工作目录根路径（默认 /workspace）
-  CLAUDE_MODEL         Claude 模型名称（如 ark-code-latest）
-
-${DIM}首次使用？运行 ${CYAN}larkpal init${DIM} 开始配置。${RESET}
-`);
-}
-async function cli() {
-	const command = process.argv.slice(2)[0];
-	if (command === "--version" || command === "-v") {
-		console.log(getVersion());
-		return;
-	}
-	if (command === "--help" || command === "-h") {
-		printHelp();
-		return;
-	}
-	if (command === "init") {
-		const { runInteractiveInit } = await import("./interactive-init-dZe9f9Ne.mjs");
-		const exitCode = await runInteractiveInit();
-		process.exit(exitCode);
-	}
-	if (command && !command.startsWith("-")) {
-		console.log(`${YELLOW}未知命令: ${command}${RESET}\n`);
-		printHelp();
-		process.exit(1);
-	}
-	const { LarkCliCredentialProvider } = await import("./lark-cli-provider-CR0eLl0q.mjs").then((n) => n.n);
-	if (!LarkCliCredentialProvider.isConfigured()) {
-		console.log(`\n${YELLOW}⚠️  飞书应用凭证未配置${RESET}\n`);
-		console.log(`  LarkPal 需要飞书应用凭证才能启动。正在进入初始化向导...\n`);
-		const { runInteractiveInit } = await import("./interactive-init-dZe9f9Ne.mjs");
-		const exitCode = await runInteractiveInit();
-		if (exitCode !== 0) process.exit(exitCode);
-		console.log(`${DIM}凭证配置完成，正在启动服务...${RESET}\n`);
-	}
-	await import("./main.mjs");
-}
-cli().catch((err) => {
-	console.error("LarkPal CLI 启动失败:", err);
-	process.exit(1);
-});
-//#endregion
-export {};