@zhin.js/adapter-line 0.1.0 → 1.1.0

package/README.md

@@ -1,13 +1,31 @@
 # @zhin.js/adapter-line
 
-Zhin.js 适配器 — LINE Messaging API (Webhook 模式)
+Zhin.js LINE Messaging API 适配器（Plugin Runtime），通过 Runtime Host HTTP Webhook 收发消息。
 
 ## 功能
 
-- 接收并解析 LINE Webhook 事件（text、image、video、audio、file、location、sticker）
-- 支持私聊、群组、多人聊天（room）三种场景
-- Reply API / Push API 发送消息
-- HMAC-SHA256 签名验证
+- Webhook 事件接收（`httpHostToken` POST + HMAC-SHA256 签名验证）
+- 解析 text / image / video / audio / file / location / sticker
+- 支持私聊、群组、多人聊天（room）
+- Reply API（有 replyToken 时）/ Push API 发送
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+
+## 安装
+
+```bash
+pnpm add @zhin.js/adapter-line
+```
+
+## Plugin Runtime
+
+- `@zhin.js/adapter` — 约定式 `adapters/line.ts`（`defineAdapter`）
+- `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `zhin.js` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+
+入站：`gateway.receive({ conversation, message: { conversation, id }, content: text, sender, metadata })`  
+出站：`send({ conversation, payload })` → Reply API（缓存 replyToken）或 Push API
 
 ## 前置条件
 
@@ -15,20 +33,26 @@ Zhin.js 适配器 — LINE Messaging API (Webhook 模式)
 2. 获取 **Channel Secret** 和 **Channel Access Token**
 3. 设置 Webhook URL 为 `https://your-domain/line/webhook`
 4. 在 Console 中启用 **Use webhooks** 并关闭 **Auto-reply messages**
+5. Runtime Host（`http`）须已 listen，Webhook 才可达
+
+必填字段（`endpoints[i]`）：`name`、`channelSecret`、`channelAccessToken`。
 
 ## 最小配置
 
 ```yaml
-# zhin.config.yml
-adapters:
-  - context: line
-    name: my-line-bot
-    channelSecret: ${LINE_CHANNEL_SECRET}
-    channelAccessToken: ${LINE_CHANNEL_ACCESS_TOKEN}
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  line:
     webhookPath: /line/webhook       # 可选，默认 /line/webhook
     apiBaseUrl: https://api.line.me   # 可选，调试时可改为 LINE API 沙盒地址
+    endpoints:
+      - name: my-line-bot
+        channelSecret: ${LINE_CHANNEL_SECRET}
+        channelAccessToken: ${LINE_CHANNEL_ACCESS_TOKEN}
 ```
 
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-line`（`instanceKey: line`）。
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -40,7 +64,7 @@ adapters:
 
 LINE 要求 Webhook URL 以 HTTPS 开头。常见方案：
 
-- **反向代理**：Nginx/Caddy 将 `https://your-domain/line/webhook` 转发到本地 zhIn 端口
+- **反向代理**：Nginx/Caddy 将 `https://your-domain/line/webhook` 转发到本地 zhin 端口
 - **Cloudflare Tunnel**：`cloudflared tunnel --url http://localhost:端口`
 - **ngrok**：调试用 `ngrok http 端口`
 
@@ -48,15 +72,23 @@ LINE 要求 Webhook URL 以 HTTPS 开头。常见方案：
 
 ## 消息类型映射
 
-| LINE 类型 | Zhin.js Segment | 说明 |
-|-----------|----------------|------|
-| text | text | 纯文本 |
-| image | image | 图片（暂不支持二次获取） |
-| video | video | 视频 |
-| audio | audio | 音频 |
-| file | file | 文件 |
-| location | location | 位置信息 |
-| sticker | sticker | 贴纸 |
+| LINE 类型 | 入站 content（文本摘要） | 出站 wire |
+|-----------|--------------------------|-----------|
+| text | 原文 | text |
+| image | `[image]` | image（需 `url`） |
+| video | `[video]` | video（需 `url`） |
+| audio | `[audio]` | audio（需 `url`） |
+| file | `[file: name]` | — |
+| location | address 或坐标 | location |
+| sticker | `[sticker: pkg/id]` | sticker |
+
+## AI 工具
+
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具（2 个） | `agent/tools/`（`line_get_profile`、`line_get_group_members`） |
+| 技能说明 | `agent/skills/line.md` |
 
 ## 已知限制
 
@@ -69,7 +101,7 @@ LINE 要求 Webhook URL 以 HTTPS 开头。常见方案：
 
 | 问题 | 排查方法 |
 |------|---------|
-| Webhook Verify 失败 | 检查 HTTPS 证书、域名解析、端口是否可达 |
+| Webhook Verify 失败 | 检查 HTTPS 证书、域名解析、端口是否可达；确认 host-http 已 listen |
 | 签名验证 403 | 确认 Channel Secret 与 Console 一致 |
 | 发送 401 | 确认 Channel Access Token 未过期 |
 | 发送 400 | 检查消息格式是否符合 LINE API 规范 |

package/adapters/line.js

@@ -0,0 +1,31 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * Convention entry: discover `adapters/line.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LineEndpoint } from "../lib/endpoint.js";
+import { resolveLineConfig, } from "../lib/protocol.js";
+import { lineRuntimeStateToken } from "../lib/line-runtime-state.js";
+export { LineEndpoint } from "../lib/endpoint.js";
+export default defineAdapter({
+    capabilities: ['inbound', 'outbound'],
+    // LINE Messaging API 媒体消息仅消费远程 URL；无按钮交互面，交互段降级纯文本。
+    segments: {
+        outboundMedia: ['url'],
+        interactive: 'text',
+    },
+    create(context) {
+        const config = resolveLineConfig(context.config);
+        // 注册到插件运行时状态（line.endpoint list 的"运行中"数据源）
+        context.use(lineRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
+            mode: 'webhook',
+        });
+        return new LineEndpoint({
+            id: context.id,
+            http: context.use(httpHostToken),
+            config,
+        });
+    },
+});

package/adapters/line.ts

@@ -0,0 +1,36 @@
+/**
+ * Convention entry: discover `adapters/line.ts` → defineAdapter.
+ */
+import { defineAdapter } from 'zhin.js/adapter';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LineEndpoint } from '../src/endpoint.js';
+import {
+  resolveLineConfig,
+  type LineAdapterConfig,
+} from '../src/protocol.js';
+import { lineRuntimeStateToken } from '../src/line-runtime-state.js';
+
+export { LineEndpoint } from '../src/endpoint.js';
+export type { LineEndpointOptions, LineFetch } from '../src/endpoint.js';
+
+export default defineAdapter<LineAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  // LINE Messaging API 媒体消息仅消费远程 URL；无按钮交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url'],
+    interactive: 'text',
+  },
+  create(context) {
+    const config = resolveLineConfig(context.config);
+    // 注册到插件运行时状态（line.endpoint list 的"运行中"数据源）
+    context.use(lineRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
+      mode: 'webhook',
+    });
+    return new LineEndpoint({
+      id: context.id,
+      http: context.use(httpHostToken),
+      config,
+    });
+  },
+});

package/agent/tools/get_group_members.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ groupId: string }>({
+  description: 'Get LINE group member IDs',
+  adapter: 'line',
+  inputSchema: z.object({
+    groupId: z.string().min(1),
+  }),
+  async execute({ groupId }, context) {
+    if (!groupId.startsWith('G')) {
+      throw new Error(`Invalid groupId "${groupId}": must start with G`);
+    }
+    return context.$client.getGroupMemberIds(groupId);
+  },
+});

package/agent/tools/get_profile.ts

@@ -0,0 +1,16 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+
+export default defineAgentTool<{ userId: string }>({
+  description: 'Get LINE user profile by userId',
+  adapter: 'line',
+  inputSchema: z.object({
+    userId: z.string().min(1),
+  }),
+  async execute({ userId }, context) {
+    if (!userId.startsWith('U')) {
+      throw new Error(`Invalid userId "${userId}": must start with U`);
+    }
+    return context.$client.getProfile(userId);
+  },
+});

package/commands/endpoint/add/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { lineEndpointCommands } from "../../../lib/line-endpoint-commands.js";
+export default lineEndpointCommands.add;

package/commands/endpoint/add/[id].ts

@@ -0,0 +1,3 @@
+import { lineEndpointCommands } from '../../../src/line-endpoint-commands.js';
+
+export default lineEndpointCommands.add;

package/commands/endpoint/list.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { lineEndpointCommands } from "../../lib/line-endpoint-commands.js";
+export default lineEndpointCommands.list;

package/commands/endpoint/list.ts

@@ -0,0 +1,3 @@
+import { lineEndpointCommands } from '../../src/line-endpoint-commands.js';
+
+export default lineEndpointCommands.list;

package/commands/endpoint/remove/[id].js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { lineEndpointCommands } from "../../../lib/line-endpoint-commands.js";
+export default lineEndpointCommands.remove;

package/commands/endpoint/remove/[id].ts

@@ -0,0 +1,3 @@
+import { lineEndpointCommands } from '../../../src/line-endpoint-commands.js';
+
+export default lineEndpointCommands.remove;

package/lib/client.d.ts

@@ -0,0 +1,33 @@
+import type { LineFetch } from './endpoint.js';
+import type { LineEvent, ResolvedLineConfig } from './protocol.js';
+export interface LineGroupMember {
+    readonly user_id: string;
+    readonly nickname: string;
+}
+/** Direct LINE Messaging API client; it has no Endpoint lifecycle methods. */
+export declare class LineClient {
+    readonly config: ResolvedLineConfig;
+    readonly fetch: LineFetch;
+    constructor(config: ResolvedLineConfig, fetch: LineFetch);
+    request<T = unknown>(path: string, init?: {
+        readonly method?: string;
+        readonly body?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+    getProfile(userId: string): Promise<unknown>;
+    getGroupMemberIds(groupId: string, start?: string): Promise<{
+        readonly memberIds?: string[];
+        readonly next?: string;
+    }>;
+    getGroupMembers(groupId: string): Promise<LineGroupMember[]>;
+}
+export type LineClientEventMap = Record<string, LineEvent>;
+declare module '@zhin.js/feature-kit' {
+    interface AdapterClientRegistry {
+        readonly line: {
+            readonly client: LineClient;
+            readonly events: LineClientEventMap;
+        };
+    }
+}
+export declare const lineClient: import("@zhin.js/adapter").EndpointClientToken<LineClient, LineClientEventMap>;

package/lib/client.js

@@ -0,0 +1,54 @@
+import { defineEndpointClient } from 'zhin.js/adapter';
+/** Direct LINE Messaging API client; it has no Endpoint lifecycle methods. */
+export class LineClient {
+    config;
+    fetch;
+    constructor(config, fetch) {
+        this.config = config;
+        this.fetch = fetch;
+    }
+    async request(path, init = {}) {
+        const response = await this.fetch(`${this.config.apiBaseUrl}${path}`, {
+            method: init.method ?? 'GET',
+            headers: {
+                Authorization: `Bearer ${this.config.channelAccessToken}`,
+                ...(init.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+            },
+            ...(init.body === undefined ? {} : { body: init.body }),
+            signal: init.signal ?? AbortSignal.timeout(30_000),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`LINE API error ${response.status}: ${text}`);
+        }
+        return await response.json();
+    }
+    getProfile(userId) {
+        return this.request(`/v2/profile/${encodeURIComponent(userId)}`);
+    }
+    getGroupMemberIds(groupId, start) {
+        const kind = groupId.startsWith('R') ? 'room' : 'group';
+        const query = start ? `?start=${encodeURIComponent(start)}` : '';
+        return this.request(`/v2/bot/${kind}/${encodeURIComponent(groupId)}/members/ids${query}`);
+    }
+    async getGroupMembers(groupId) {
+        const kind = groupId.startsWith('R') ? 'room' : 'group';
+        const ids = [];
+        let next;
+        do {
+            const page = await this.getGroupMemberIds(groupId, next);
+            ids.push(...(page.memberIds ?? []).filter((id) => typeof id === 'string' && id.length > 0));
+            next = page.next || undefined;
+        } while (next);
+        return Promise.all(ids.map(async (userId) => {
+            try {
+                const profile = await this.request(`/v2/bot/${kind}/${encodeURIComponent(groupId)}/member/${encodeURIComponent(userId)}`);
+                return { user_id: userId, nickname: String(profile.displayName ?? userId) };
+            }
+            catch {
+                return { user_id: userId, nickname: userId };
+            }
+        }));
+    }
+}
+export const lineClient = defineEndpointClient('line');

package/lib/endpoint.d.ts

@@ -1,38 +1,42 @@
-import { Endpoint, Message, SendOptions } from "zhin.js";
-import { type Router } from "@zhin.js/host-router/router";
-import type { LineEndpointConfig, LineEvent } from "./types.js";
-import type { LineAdapter } from "./adapter.js";
-export declare class LineEndpoint implements Endpoint<LineEndpointConfig, LineEvent> {
-    adapter: LineAdapter;
-    private router;
-    $config: LineEndpointConfig;
-    $connected: boolean;
-    get pluginLogger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: LineAdapter, router: Router, $config: LineEndpointConfig);
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private handleWebhook;
-    private verifySignature;
-    private handleEvent;
-    private handleMessageEvent;
-    private handleFollowEvent;
-    private handleJoinEvent;
-    $formatMessage(event: LineEvent): Message<LineEvent>;
-    private generateMessageId;
-    private resolveChannel;
-    private extractRawText;
-    private parseMessageContent;
-    $sendMessage(options: SendOptions): Promise<string>;
-    private replyTokenCache;
-    /**
-     * 缓存 replyToken，用于后续发送回复消息
-     */
-    cacheReplyToken(channelId: string, replyToken: string): void;
-    private replyMessage;
-    private pushMessage;
-    private buildLineMessages;
-    private buildTextMessage;
-    $recallMessage(_id: string): Promise<void>;
+import { Endpoint } from 'zhin.js/adapter';
+/**
+ * LineEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import { type EndpointManagement, EndpointSendRequest } from 'zhin.js/adapter';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from 'zhin.js';
+import { type LineEvent, type ResolvedLineConfig } from './protocol.js';
+import { LineClient } from './client.js';
+export type LineFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+    readonly signal?: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface LineEndpointOptions {
+    readonly id: CapabilityId;
+    readonly http: HttpHost;
+    readonly config: ResolvedLineConfig;
+    readonly fetch?: LineFetch;
+}
+export declare class LineEndpoint extends Endpoint<LineClient> {
+    #private;
+    readonly client: LineClient;
+    readonly management: EndpointManagement;
+    constructor(options: LineEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedLineConfig;
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event: LineEvent): void;
 }
-//# sourceMappingURL=endpoint.d.ts.map