@zhin.js/adapter-line 2.0.1 → 2.0.3

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # @zhin.js/adapter-line
 
+## 2.0.3
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
+## 2.0.2
+
+### Patch Changes
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/host-api@2.0.5
+  - @zhin.js/host-router@2.0.3
+  - @zhin.js/logger@1.0.74
+  - zhin.js@4.1.2
+
 ## 2.0.1
 
 ### Patch Changes

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` — `messageGatewayToken` 入站/出站
+- `@zhin.js/host-http` — `httpHostToken` 注册 Webhook 路由（**非** legacy host-router/Koa）
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+
+入站：`gateway.receive({ adapter, target: channelId, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → Reply API（缓存 replyToken）或 Push API
 
 ## 前置条件
 
@@ -15,13 +33,16 @@ 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 才可达
+
+必填字段：`channelSecret`、`channelAccessToken`。
 
 ## 最小配置
 
 ```yaml
-# zhin.config.yml
-adapters:
-  - context: line
+# zhin.config.yml（Plugin Runtime）
+plugins:
+  line:
     name: my-line-bot
     channelSecret: ${LINE_CHANNEL_SECRET}
     channelAccessToken: ${LINE_CHANNEL_ACCESS_TOKEN}
@@ -29,6 +50,8 @@ adapters:
     apiBaseUrl: https://api.line.me   # 可选，调试时可改为 LINE API 沙盒地址
 ```
 
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-line`（`instanceKey: line`）。
+
 ## 环境变量
 
 | 变量 | 说明 |
@@ -40,7 +63,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 +71,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 +100,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.ts

@@ -0,0 +1,26 @@
+/**
+ * Convention entry: discover `adapters/line.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import { LineEndpoint } from '../src/endpoint.js';
+import {
+  resolveLineConfig,
+  type LineAdapterConfig,
+} from '../src/protocol.js';
+
+export { LineEndpoint } from '../src/endpoint.js';
+export type { LineEndpointOptions, LineFetch } from '../src/endpoint.js';
+
+export default defineAdapter<LineAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new LineEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      http: context.use(httpHostToken),
+      config: resolveLineConfig(context.config),
+    });
+  },
+});

package/agent/tools/get_group_members.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getLineApiConfig } from '../../src/line-agent-deps.js';
+
+export default defineAgentTool<{ groupId: string }>({
+  description: 'Get LINE group member IDs',
+  inputSchema: z.object({
+    groupId: z.string().min(1),
+  }),
+  async execute({ groupId }) {
+    if (!groupId.startsWith('G')) {
+      throw new Error(`Invalid groupId "${groupId}": must start with G`);
+    }
+    const { accessToken, apiBaseUrl } = getLineApiConfig();
+    const response = await fetch(`${apiBaseUrl}/v2/bot/group/${groupId}/members/ids`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`LINE Group Members API error ${response.status}: ${errorText}`);
+    }
+    return await response.json();
+  },
+});

package/agent/tools/get_profile.ts

@@ -0,0 +1,24 @@
+import { defineAgentTool } from '@zhin.js/agent/tools';
+import { z } from 'zod';
+import { getLineApiConfig } from '../../src/line-agent-deps.js';
+
+export default defineAgentTool<{ userId: string }>({
+  description: 'Get LINE user profile by userId',
+  inputSchema: z.object({
+    userId: z.string().min(1),
+  }),
+  async execute({ userId }) {
+    if (!userId.startsWith('U')) {
+      throw new Error(`Invalid userId "${userId}": must start with U`);
+    }
+    const { accessToken, apiBaseUrl } = getLineApiConfig();
+    const response = await fetch(`${apiBaseUrl}/v2/profile/${userId}`, {
+      headers: { Authorization: `Bearer ${accessToken}` },
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`LINE Profile API error ${response.status}: ${errorText}`);
+    }
+    return await response.json();
+  },
+});

package/lib/endpoint.d.ts

@@ -1,38 +1,46 @@
-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>;
+/**
+ * LineEndpoint — lifecycle, outbound, admit, OpenAPI helpers for agent tools.
+ */
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { HttpHost } from '@zhin.js/host-http';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type LineEvent, type ResolvedLineConfig } from './protocol.js';
+export type LineFetch = (url: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    json(): Promise<unknown>;
+}>;
+export interface LineEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly http: HttpHost;
+    readonly config: ResolvedLineConfig;
+    readonly fetch?: LineFetch;
+}
+export declare class LineEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: LineEndpointOptions);
+    /** Used by webhook handler. */
+    get isOpen(): boolean;
+    get config(): ResolvedLineConfig;
+    getApiConfig(): {
+        accessToken: string;
+        apiBaseUrl: string;
+    };
+    start(): Promise<void>;
+    open(): void;
+    close(): void;
+    stop(): Promise<void>;
+    send({ target, payload }: {
+        readonly target: string;
+        readonly payload: unknown;
+    }): Promise<string>;
+    /** Test / internal: admit a parsed event when open (non-webhook path). */
+    admit(event: LineEvent): void;
 }
-//# sourceMappingURL=endpoint.d.ts.map