@zhin.js/adapter-email 3.0.2 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # @zhin.js/adapter-email
 
+## 4.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - zhin.js@5.0.0
+
+## 3.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@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
 ## 3.0.2
 
 ### Patch Changes

package/README.md

@@ -1,14 +1,14 @@
 # @zhin.js/adapter-email
 
-Zhin.js 邮件适配器，通过 SMTP 发送和 IMAP 接收邮件，将邮箱作为聊天平台接入。
+Zhin.js 邮件适配器（Plugin Runtime），通过 SMTP 发送和 IMAP 接收邮件，将邮箱作为聊天通道接入。
 
 ## 功能特性
 
 - SMTP 邮件发送（基于 nodemailer）
 - IMAP 邮件接收（基于 imap + mailparser）
-- 支持附件处理
-- 定时轮询新邮件
+- 定时轮询未读邮件
 - TLS/SSL 加密连接
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -16,135 +16,78 @@ Zhin.js 邮件适配器，通过 SMTP 发送和 IMAP 接收邮件，将邮箱作
 pnpm add @zhin.js/adapter-email
 ```
 
+## Plugin Runtime
+
+- `@zhin.js/adapter` — 约定式 `adapters/email.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`smtp` / `imap`）
+
+入站：`gateway.receive({ adapter, target: fromEmail, content: text, sender, metadata })`  
+出站：`send({ target, payload })` → nodemailer（payload 已由 gateway/core 渲染；无 segment-mapper）
+
 ## 前置条件
 
 | 要求 | 说明 |
 |------|------|
-| **邮箱账号** | 可用的 SMTP 发信与 IMAP 收信账号（或同一邮箱双协议） |
-| **应用专用密码** | Gmail、Outlook 等常需开启「第三方应用访问」或生成应用密码 |
+| **邮箱账号** | 可用的 SMTP 发信与 IMAP 收信账号 |
+| **应用专用密码** | Gmail、Outlook 等常需应用密码 |
 | **网络** | 出站可连 SMTP/IMAP 端口（465/587/993 等） |
-| **host-router** | 不需要；IMAP 轮询在适配器内完成 |
-
-必填字段见 `EmailEndpointConfig`：`context`、`name`、`smtp`、`imap`（含 `auth.user` / `auth.pass` 与 `user` / `password`）。
+| **host-http** | 不需要；IMAP 轮询在适配器内完成 |
 
 ## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-email"
-
-endpoints:
-  - context: email
-    name: my-email-bot
-    smtp:
-      host: smtp.example.com
-      port: 465
-      secure: true
-      auth:
-        user: bot@example.com
-        pass: "${EMAIL_PASSWORD}"
-    imap:
-      host: imap.example.com
-      port: 993
-      tls: true
-      user: bot@example.com
-      password: "${EMAIL_PASSWORD}"
+  email:
+    endpoints:
+      - name: my-email-bot
+        smtp:
+          host: smtp.example.com
+          port: 465
+          secure: true
+          auth:
+            user: bot@example.com
+            pass: "${EMAIL_PASSWORD}"
+        imap:
+          host: imap.example.com
+          port: 993
+          tls: true
+          user: bot@example.com
+          password: "${EMAIL_PASSWORD}"
 ```
 
-## 配置
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-email`（`instanceKey: email`）。
 
 ### 可选 IMAP 字段
 
-```yaml
-    imap:
-      host: imap.example.com
-      port: 993
-      tls: true
-      user: bot@example.com
-      password: "${EMAIL_PASSWORD}"
-      # checkInterval: 30000     # 轮询间隔（毫秒），默认 30 秒
-      # mailbox: INBOX           # 监听的邮箱文件夹
-      # markSeen: true           # 已读标记
-```
-
-### TypeScript 配置
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'email',
-      name: 'my-email-bot',
-      smtp: {
-        host: 'smtp.example.com',
-        port: 465,
-        secure: true,
-        auth: {
-          user: 'bot@example.com',
-          pass: process.env.EMAIL_PASSWORD!,
-        },
-      },
-      imap: {
-        host: 'imap.example.com',
-        port: 993,
-        tls: true,
-        user: 'bot@example.com',
-        password: process.env.EMAIL_PASSWORD!,
-      },
-    }
-  ],
-  plugins: ['@zhin.js/adapter-email']
-})
-```
-
-## 使用示例
+- `checkInterval`：轮询间隔（毫秒），默认 `60000`
+- `mailbox`：默认 `INBOX`
+- `markSeen`：默认 `true`
 
-### 注册命令
+### 附件下载
 
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
+`attachments.enabled: true` 时，入站邮件附件会落盘并把保存信息写入消息 metadata（`attachments: [{ filename, path, contentType, size }]`）：
 
-const { addCommand } = usePlugin()
-
-addCommand(
-  new MessageCommand('status')
-    .desc('查询状态')
-    .action(() => 'Agent 运行中')
-)
-```
-
-### 消息处理
-
-```typescript
-import { usePlugin } from 'zhin.js'
-
-const { root } = usePlugin()
-
-root.addMiddleware(async (message, next) => {
-  if (message.$adapter === 'email') {
-    console.log('收到邮件:', message.$sender.name, message.$content)
-  }
-  await next()
-})
-```
+- `downloadPath`：保存目录，默认 `./downloads/email`
+- `maxFileSize`：单附件上限（字节），默认 10MB，超限跳过
+- `allowedTypes`：允许的 MIME 类型白名单，不在列表内跳过
 
 ## 故障排查
 
 | 现象 | 排查 |
 |------|------|
-| IMAP 连接失败 | 主机/端口/TLS 是否正确；是否需应用专用密码而非登录密码 |
-| 收不到新邮件 | 默认轮询间隔 30s（`checkInterval`）；检查 `mailbox` 是否为 `INBOX` |
-| SMTP 发送失败 | `secure` 与端口匹配（465 通常 `secure: true`）；发信地址与 `auth.user` 一致 |
-| 重复处理邮件 | 确认 `markSeen: true`；检查是否多实例同时轮询同一邮箱 |
+| IMAP 连接失败 | 主机/端口/TLS；是否需应用专用密码 |
+| 收不到新邮件 | `checkInterval` / `mailbox`；确认 `open()` 后才准入入站 |
+| SMTP 发送失败 | `secure` 与端口匹配；发信地址与 `auth.user` 一致 |
+| 重复处理邮件 | `markSeen: true`；避免多实例轮询同一邮箱 |
 
 建议使用环境变量存储邮箱密码，勿提交到版本库。
 
 ## AI 工具
 
-技能说明见 `agent/skills/email.md`（收发邮件约束与工具列表）。
-
+技能说明见 `agent/skills/email.md`。
 
 ## 文档链接
 

package/adapters/email.ts

@@ -0,0 +1,29 @@
+/**
+ * Convention entry: discover `adapters/email.ts` → defineAdapter.
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { EmailEndpoint } from '../src/endpoint.js';
+import {
+  resolveEmailConfig,
+  type EmailAdapterConfig,
+} from '../src/protocol.js';
+
+export { EmailEndpoint } from '../src/endpoint.js';
+export type { EmailEndpointOptions } from '../src/endpoint.js';
+export type {
+  EmailImapFetchMessage,
+  EmailImapTransport,
+  EmailSmtpTransport,
+} from '../src/transport.js';
+
+export default defineAdapter<EmailAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    return new EmailEndpoint({
+      id: context.id,
+      gateway: context.use(messageGatewayToken),
+      config: resolveEmailConfig(context.config),
+    });
+  },
+});

package/lib/endpoint.d.ts

@@ -1,33 +1,26 @@
-import { Endpoint, Message, MessageSegment, SendOptions } from 'zhin.js';
-import { EventEmitter } from "events";
-import type { EmailEndpointConfig, EmailMessage } from "./types.js";
-import type { EmailAdapter } from "./adapter.js";
-export declare class EmailEndpoint extends EventEmitter implements Endpoint<EmailEndpointConfig, EmailMessage> {
-    adapter: EmailAdapter;
-    $config: EmailEndpointConfig;
-    $connected: boolean;
-    private smtpTransporter;
-    private imapConnection;
-    private checkTimer;
-    get logger(): import("zhin.js").Logger;
-    get $id(): string;
-    constructor(adapter: EmailAdapter, config: EmailEndpointConfig);
-    $connect(): Promise<void>;
-    $disconnect(): Promise<void>;
-    private setupImapListeners;
-    private startEmailCheck;
-    private checkForNewEmails;
-    private handleImapMessage;
-    private parseEmailMessage;
-    $formatMessage(emailMsg: EmailMessage): Message<EmailMessage>;
-    static parseEmailContent(email: EmailMessage): MessageSegment[];
-    $sendMessage(options: SendOptions): Promise<string>;
-    $recallMessage(id: string): Promise<void>;
-    private formatSendContent;
-    private downloadAttachment;
-    /**
-     * HTML → 纯文本转换，处理常见标签和实体
-     */
-    static htmlToText(html: string): string;
+import type { EndpointInstance } from '@zhin.js/adapter';
+import type { MessageGateway } from '@zhin.js/core/runtime';
+import type { CapabilityId } from '@zhin.js/plugin-runtime';
+import { type EmailMessage, type ResolvedEmailConfig } from './protocol.js';
+import { type EmailImapTransport, type EmailSmtpTransport } from './transport.js';
+export interface EmailEndpointOptions {
+    readonly id: CapabilityId;
+    readonly gateway: MessageGateway;
+    readonly config: ResolvedEmailConfig;
+    readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
+    readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
+}
+export declare class EmailEndpoint implements EndpointInstance {
+    #private;
+    constructor(options: EmailEndpointOptions);
+    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 mail when the endpoint is open. */
+    admit(email: EmailMessage): void;
 }
-//# sourceMappingURL=endpoint.d.ts.map