@zhin.js/adapter-milky 5.0.0 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # @zhin.js/adapter-milky
 
+## 5.0.1
+
+### Patch Changes
+
+- cdf64e7: 多方向审计修复批（8 面 30+ bug）：
+
+  - **安全**：钉钉 webhook 验签绕过修复（缺 timestamp/sign 一律 403 + ±1h 防重放）；exec-policy fail-closed（换行/`$(`/反引号拒绝、管道逐段过白名单、env dump 复合拆段）；wecom 验签改 timingSafeEqual；config:set 拒绝 `__proto__` 等魔术键、host 键优先防覆写。
+  - **P0 功能**：`zhin packages` scoped 包名解析为空导致 rm -rf 风险；命令数字参数解析失败炸断消息链路（dispatch 捕获 continue）；TaskQueue 监听器首个事件自摘除导致 assistant 队列挂死（+超时后完成不覆盖终态）；DatabaseHost 跨世代共享崩溃（define 幂等 + stop 改进程级）；rss 按不存在 id 列删除改业务键。
+  - **Runtime/HMR**：native watcher 过滤忽略目录（lib/.zhin 不再触发重载风暴）；host 段配置 patch（http.port 等）存在 installResources 时全量重建；capability 目录非 entry 支持文件升级进程重启；documentTransaction 失败回滚。
+  - **CLI 写侧**：config/setup 对 toml 静默假成功改统一 config-file（不支持格式报错）；doctor/onboard 默认配置改新形态 plugins 映射；schedule add 改 --prompt；migrate engines/中文模板误伤/覆盖前备份。
+  - **适配器生命周期**：napcat/milky start 失败竞态与僵尸连接、心跳 close 清理、stop-during-connect settle；slack webhook 二次 writeHead + messageChannelMap LRU。
+  - **Host/向导**：logs/stats 与 inbox 查询改 DB 侧 count/orderBy/limit 下推；save-yaml 写入前校验；zhipu/moonshot baseUrl 必填预填；.env 写入转义 + 幂等合并；setup 数据库密码不再明文落 config；60s fetch 超时与 JSON 守卫。
+
+- 2d0a159: 审计尾账清零（P2 批）：
+
+  - Runtime：reload 前重读配置文档消除陈旧快照；组合式根 schema 显式报错（不再静默空 view）；ConfigPatch 支持数组数字索引（`endpoints.0.url`）；console 配置读写单一数据源 + 写入串行化；watch tick 防重叠 + fetch 超时。
+  - Host/MCP：MCP client stop 成功才标记 + handoff 补 quiescePrevious/resumePrevious（独占端口不再新旧并存）；readJsonBody 超限保留连接回 413；dispatchHttp 统一 HttpBodyError 状态码；inbox endpoint 名仅命中才缓存；create_plugin 工具生成物改 definePlugin 新格式。
+  - Agent：CapabilityIngress 按 projection 归属记账（key 振荡不再泄漏/误 purge）；敏感目录 `data` 锚定工作区根（src/data 不再误伤）；passive-group-buffer 死 key 清扫；tool scopes 数组校验。
+  - 插件：blackjack 终局「回复 1」复活（getLatestForUser）；60s apiBase 改运行时求值（弃 process.env）；rss \_db lifecycle 清理；group-suite flush 不丢计数 + checkin 串行化防双签；milky SSE start 失败复位。
+  - 工具链：applyAdaptersToConfig 改合并（重跑 wizard 不丢手工 endpoint）；html-renderer 提示识别 plugins 映射；create-zhin CLI 项目名校验 + task XML/NSSM 修复；setup --ai 补 @zhin.js/tool；layout 发现支持 .ts。
+
+- 078e3f7: 架构统一批（AURA）：
+
+  - **EndpointLifecycle 基座**（@zhin.js/adapter 新增 `createEndpointLifecycle`）：WS/SSE 端点的 start 失败复位、仅曾 open 才退避重连（指数+jitter 可配）、stop 不重连、PONG 看门狗、定时器集中清理、陈旧事件防叠套；napcat/milky/onebot11/onebot12/satori 已迁移（删除各自手写状态机），从此同类竞态在结构上不可能再犯。
+  - **Generation-store**（@zhin.js/plugin-runtime 新增 `createGenerationStore`）：模块级运行时状态的一等能力，provide 自动挂 lifecycle 反注册（代际结束自动清理）；lottery deps 与 rss db 已迁移，公开 API 兼容。
+  - **Resolver 管线收敛**（@zhin.js/runtime）：解析规则统一为 local path → workspace → node_modules 单管线；optional 引用对所有 PackageResolutionError 容错（消除 message 前缀补丁）。
+  - **工具目录准入统一**（@zhin.js/agent）：RegisteredToolSource 与 ExternalToolSource 共用同一 `canAccessTool` 准入（platforms/scopes/permissions/hidden 四元组全链路透传），同名覆盖 warn；AgentToolRegistration 补 platforms/scopes。两条注册通道（静态约定 vs 动态注册）职责边界已文档化。
+
+- 9c997b2: 通用 endpoint 管理命令套件：`@zhin.js/adapter` 新增 `createEndpointCommands(spec, defineCommand)`——`<adapter> endpoint list / add <name> key=value... / remove <name>` 三件套，含 kv 解析、`.env` 凭据派生（`<ADAPTER>_<NAME>_<FIELD>`）、yaml 写回保留注释、master 权限门禁（通用 `isEndpointOperator`）、自定义 bindFlow 钩子。QQ 迁移至套件（行为与扫码绑定流程不变）；napcat / onebot11 / onebot12 / milky / slack / telegram 接入（字段对齐各自 schema，features 补 @zhin.js/command）。
+- 09d4f25: Console 社交读取面（management 语义端口）多平台落地：napcat/onebot11/onebot12/milky（好友+群+群成员，OneBot 标准动作）；discord/kook/satori（guild+频道+成员，分页聚合，id 保精度留字符串）；slack（workspace 成员+public channels+conversations.members）；line（群/room 成员分页+profile 回退）；wechat-mp（followers openid）；weixin-ilink（context_token 对端推导）；lark（chats+members 全分页）。`EndpointFriend.user_id`/`EndpointGroup.group_id` 放宽为 `number | string`（雪花 id 不丢精度）。telegram/wecom/dingtalk/github/email/sandbox 注明平台无列表面暂不接。
+- 6cb6152: 统一消息元素通道（UNI-Channel）落地：
+
+  - **入站契约**：`IncomingMessage.segments`（canonical Segment[]，与 content 纯文本视图同源双轨），Message 透传；AI 兜底链路经 `collectSegmentMedia` 把图片/语音/视频/文件 MediaRef 写入会话 extra——多模态输入不再丢失。
+  - **出站协商**：`normalizeOutboundPayload` 升级全量 canonical 归一（复用 generic-segment-mapper），html→image 按端点 `segments.outboundMedia` 声明降级（base64 直发 / url-or-text / passthrough 自行物化）；`MediaRef.kind` 新增 `'file'` 承载平台不透明引用（file_id/resource_id）。
+  - **能力声明**：`defineAdapter.segments` policy（outboundMedia / interactive），三道段门禁复活（探测点改 adapters/\*.ts，豁免名单渐进收敛）。
+  - **首批迁移**：icqq 全保真出入站（CQ ↔ canonical，quote→reply 段）；milky/telegram/discord 入站媒体段恢复（附件/贴纸/callback action）；napcat/onebot11/onebot12 出站 canonical→OneBot 数组段；wechat-mp/wecom `/cgi-bin/media/upload` 与 lark `/im/v1/images` 上传通路（base64/URL 图片不再静默丢图，失败降级文本）。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [2d0a159]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [50497a5]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/command@1.0.3
+  - @zhin.js/agent@1.0.6
+  - @zhin.js/plugin-runtime@1.1.1
+  - @zhin.js/host-http@1.0.3
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
 ## 5.0.0
 
 ### Patch Changes

package/adapters/milky.ts

@@ -14,6 +14,7 @@ import {
   resolveMilkyConfig,
   type MilkyAdapterConfig,
 } from '../src/protocol.js';
+import { milkyRuntimeStateToken } from '../src/milky-runtime-state.js';
 
 export {
   MilkySseEndpoint,
@@ -33,9 +34,19 @@ export type {
 
 export default defineAdapter<MilkyAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // Milky 协议资源 uri 消费 http(s):// 与 base64:// 形式；无卡片交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'base64'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveMilkyConfig(context.config);
     const gateway = context.use(messageGatewayToken);
+    // 注册到插件运行时状态（milky endpoint list 的"运行中"数据源）
+    context.use(milkyRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.connection,
+    });
     if (config.connection === 'webhook') {
       return new MilkyWebhookEndpoint({
         id: context.id,

package/commands/endpoint/add/[name:string].ts

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

package/commands/endpoint/list.ts

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

package/commands/endpoint/remove/[name:string].ts

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

package/lib/endpoint-management.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Milky endpoint management 语义端口（Console 社交面 RPC 消费，见
+ * packages/im/adapter/src/endpoint-management.ts）。
+ *
+ * Milky 协议响应 data 为包裹对象：get_friend_list → {friends:[...]}、
+ * get_group_list → {groups:[...]}、get_group_member_list → {members:[...]}。
+ * 归一化取舍：
+ * - friend → {user_id:number, nickname, remark: remark ?? ''}
+ * - group → {group_id:number, name: group_name ?? name}
+ * - 群成员列表保持 Milky 原生形状，仅保证数组
+ */
+import type { EndpointManagement } from '@zhin.js/adapter';
+/** 管理面只依赖 endpoint 的 callApi（ws/wss/sse/webhook 四种传输各自实现）。 */
+export interface MilkyManagementCaller {
+    callApi(action: string, params?: Record<string, unknown>): Promise<unknown>;
+}
+export declare function createMilkyEndpointManagement(endpoint: MilkyManagementCaller): EndpointManagement;

package/lib/endpoint-management.js

@@ -0,0 +1,47 @@
+export function createMilkyEndpointManagement(endpoint) {
+    return Object.freeze({
+        async listFriends() {
+            const data = asRecord(await endpoint.callApi('get_friend_list'));
+            return toArray(data.friends).map((value) => {
+                const friend = asRecord(value);
+                return {
+                    user_id: toNumberId(friend.user_id, 'user_id'),
+                    nickname: String(friend.nickname ?? ''),
+                    remark: String(friend.remark ?? ''),
+                };
+            });
+        },
+        async listGroups() {
+            const data = asRecord(await endpoint.callApi('get_group_list'));
+            return toArray(data.groups).map((value) => {
+                const group = asRecord(value);
+                return {
+                    group_id: toNumberId(group.group_id, 'group_id'),
+                    name: String(group.group_name ?? group.name ?? ''),
+                };
+            });
+        },
+        async listGroupMembers(groupId) {
+            const data = asRecord(await endpoint.callApi('get_group_member_list', {
+                group_id: toNumberId(groupId, 'group_id'),
+            }));
+            return toArray(data.members);
+        },
+    });
+}
+function asRecord(value) {
+    return value !== null && typeof value === 'object'
+        ? value
+        : {};
+}
+function toArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** console RPC 传入的 gid/uid 可能是字符串，统一收敛为数字。 */
+function toNumberId(value, label) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || String(value ?? '').trim() === '') {
+        throw new TypeError(`milky ${label} 必须是数字: ${String(value)}`);
+    }
+    return n;
+}

package/lib/milky-endpoint-commands.d.ts

@@ -0,0 +1 @@
+export declare const milkyEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage>>>;

package/lib/milky-endpoint-commands.js

@@ -0,0 +1,18 @@
+/**
+ * `milky endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { milkyRuntimeStateToken } from './milky-runtime-state.js';
+export const milkyEndpointCommands = createEndpointCommands({
+    adapterKey: 'milky',
+    adapterDisplayName: 'Milky',
+    fields: [
+        { key: 'baseUrl', required: true, description: 'Milky HTTP API base URL' },
+        { key: 'path', description: 'webhook / reverse-wss 路径' },
+        { key: 'access_token', env: true, description: 'Milky access token' },
+    ],
+    running: (use) => use(milkyRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `baseUrl: ${String(entry.baseUrl)}`,
+}, defineCommand);

package/lib/milky-runtime-state.d.ts

@@ -0,0 +1 @@
+export declare const milkyRuntimeStateToken: import("@zhin.js/plugin-runtime").Token<import("@zhin.js/adapter").EndpointRuntimeState>;

package/lib/milky-runtime-state.js

@@ -0,0 +1,6 @@
+/**
+ * Milky 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
+ * 由 plugin.ts setup() provide，adapter create 与 `milky endpoint` 命令共享（同一 owner generation）。
+ */
+import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
+export const milkyRuntimeStateToken = defineEndpointRuntimeStateToken('milky');

package/lib/protocol.d.ts

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  * Spec: https://milky.ntqqrev.org/
  */
+import type { Segment } from '@zhin.js/core/runtime';
 /** Transitional legacy endpoint row (`endpoints[]` with `context: milky`). */
 export interface MilkyLegacyEndpointRow {
     readonly context?: string;
@@ -124,6 +125,13 @@ export declare function isMessageReceiveEvent(event: MilkyEvent): event is Milky
 /** Gateway reply target：`private:uid` / `group:gid` */
 export declare function formatInboundTarget(data: MilkyIncomingMessage): string;
 export declare function formatInboundContent(data: MilkyIncomingMessage): string;
+/**
+ * 入站消息段 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 媒体段（image/record/video）优先 temp_url（kind=url），缺 URL 时回退
+ * resource_id（kind=file，平台不透明引用，经协议端 get_resource 解析）；
+ * file 段只有 file_id（kind=file）。未识别段类型按宽松段透传，不丢信息。
+ */
+export declare function formatInboundSegments(data: MilkyIncomingMessage): Segment[];
 /** First audio URI from inbound segments (for Agent Host STT preprocess). */
 export declare function extractInboundAudioUrl(data: MilkyIncomingMessage): string | undefined;
 /** 发送者显示名（群名片/群昵称/好友昵称）；没有可靠的显示名时返回 undefined。 */

package/lib/protocol.js

@@ -138,6 +138,127 @@ export function formatInboundContent(data) {
         return '';
     }).join('');
 }
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return undefined;
+}
+/**
+ * 入站消息段 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 媒体段（image/record/video）优先 temp_url（kind=url），缺 URL 时回退
+ * resource_id（kind=file，平台不透明引用，经协议端 get_resource 解析）；
+ * file 段只有 file_id（kind=file）。未识别段类型按宽松段透传，不丢信息。
+ */
+export function formatInboundSegments(data) {
+    const out = [];
+    for (const seg of data.segments) {
+        const segData = seg.data ?? {};
+        switch (seg.type) {
+            case 'text': {
+                const text = String(segData.text ?? '');
+                if (text)
+                    out.push({ type: 'text', data: { text } });
+                break;
+            }
+            case 'mention':
+                out.push({
+                    type: 'mention',
+                    data: {
+                        target: String(segData.user_id ?? ''),
+                        ...(typeof segData.name === 'string' && segData.name
+                            ? { name: segData.name }
+                            : {}),
+                    },
+                });
+                break;
+            case 'mention_all':
+                out.push({ type: 'mention', data: { target: 'all' } });
+                break;
+            case 'face': {
+                const id = firstNonEmptyString(segData.face_id, segData.id);
+                if (id)
+                    out.push({ type: 'face', data: { id } });
+                break;
+            }
+            case 'reply': {
+                const seq = Number(segData.message_seq);
+                if (Number.isFinite(seq)) {
+                    // 与 formatInboundMessageId 同一复合格式，保证 reply 链可定位原消息
+                    out.push({
+                        type: 'reply',
+                        data: { message_id: `${data.message_scene}:${data.peer_id}:${seq}` },
+                    });
+                }
+                break;
+            }
+            case 'image':
+            case 'record':
+            case 'audio':
+            case 'video': {
+                const url = firstNonEmptyString(segData.temp_url, segData.uri, segData.url);
+                const resourceId = firstNonEmptyString(segData.resource_id);
+                if (!url && !resourceId)
+                    break;
+                const type = seg.type === 'image'
+                    ? 'image'
+                    : seg.type === 'video'
+                        ? 'video'
+                        : 'audio';
+                out.push({
+                    type,
+                    data: {
+                        media: url
+                            ? { kind: 'url', value: url }
+                            : { kind: 'file', value: resourceId },
+                        ...(typeof segData.summary === 'string' && segData.summary
+                            ? { alt: segData.summary }
+                            : {}),
+                    },
+                });
+                break;
+            }
+            case 'file': {
+                const fileId = firstNonEmptyString(segData.file_id);
+                if (!fileId)
+                    break;
+                out.push({
+                    type: 'file',
+                    data: {
+                        media: { kind: 'file', value: fileId },
+                        ...(typeof segData.file_name === 'string' && segData.file_name
+                            ? { name: segData.file_name }
+                            : {}),
+                        ...(typeof segData.file_size === 'number'
+                            ? { size: segData.file_size }
+                            : {}),
+                    },
+                });
+                break;
+            }
+            case 'forward': {
+                const forwardId = firstNonEmptyString(segData.forward_id);
+                if (forwardId) {
+                    out.push({
+                        type: 'forward',
+                        data: {
+                            forward_id: forwardId,
+                            ...(typeof segData.title === 'string' && segData.title
+                                ? { title: segData.title }
+                                : {}),
+                        },
+                    });
+                }
+                break;
+            }
+            default:
+                // 未识别段（market_face / light_app / xml 等）按宽松 canonical 段透传
+                out.push({ type: seg.type, data: segData });
+        }
+    }
+    return out;
+}
 /** First audio URI from inbound segments (for Agent Host STT preprocess). */
 export function extractInboundAudioUrl(data) {
     for (const seg of data.segments) {

package/lib/sse-endpoint.d.ts

@@ -1,7 +1,7 @@
 /**
  * Milky SSE client endpoint — GET text/event-stream on /event.
  */
-import type { EndpointInstance } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { callApi, type MilkyEvent, type MilkySseConfig } from './protocol.js';
@@ -22,6 +22,7 @@ export interface MilkySseEndpointOptions {
 }
 export declare class MilkySseEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: MilkySseEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/sse-endpoint.js

@@ -1,28 +1,48 @@
+/**
+ * Milky SSE client endpoint — GET text/event-stream on /event.
+ */
+import { createEndpointLifecycle, } from '@zhin.js/adapter';
 import { formatCompact, getLogger } from '@zhin.js/logger';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, buildSseConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, buildSseConnectOptions, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 import { openSseStream } from './sse-client.js';
 const logger = getLogger('milky');
 export class MilkySseEndpoint {
     #options;
     #callApi;
+    management = createMilkyEndpointManagement(this);
+    #lifecycle;
     #stream;
-    #reconnectTimer;
     #open = false;
-    #started = false;
-    #stopping = false;
     #unregisterAgent;
     constructor(options) {
         this.#options = options;
         this.#callApi = options.callApi ?? callApi;
+        this.#lifecycle = createEndpointLifecycle({
+            name: options.config.name,
+            // reconnect_interval 旧语义为固定间隔：multiplier 1 + 无 jitter + 不封顶
+            reconnect: {
+                initialIntervalMs: options.config.reconnect_interval,
+                multiplier: 1,
+                maxIntervalMs: Number.MAX_SAFE_INTEGER,
+                jitterMs: 0,
+            },
+        });
     }
     async start() {
-        if (this.#started)
+        if (this.#lifecycle.started)
             return;
-        this.#started = true;
-        this.#stopping = false;
         this.#unregisterAgent = registerMilkyAgentEndpoint(this.#options.config.name, this);
-        await this.#connect();
+        try {
+            await this.#lifecycle.start((handle) => this.#connect(handle));
+        }
+        catch (err) {
+            // 与 WS 对齐：start 失败复位由基座保证；agent 反注册留在适配器侧，允许重试
+            this.#unregisterAgent?.();
+            this.#unregisterAgent = undefined;
+            throw err;
+        }
     }
     open() {
         this.#open = true;
@@ -32,17 +52,11 @@ export class MilkySseEndpoint {
     }
     async stop() {
         this.#open = false;
-        this.#stopping = true;
-        this.#started = false;
+        await this.#lifecycle.stop();
         this.#unregisterAgent?.();
         this.#unregisterAgent = undefined;
-        if (this.#reconnectTimer) {
-            clearTimeout(this.#reconnectTimer);
-            this.#reconnectTimer = undefined;
-        }
         this.#stream?.close();
         this.#stream = undefined;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name, mode: 'sse' }));
     }
     async send({ target, payload }) {
         const message = formatOutboundSegments(payload);
@@ -147,6 +161,7 @@ export class MilkySseEndpoint {
     #admitMessage(data, event) {
         const target = formatInboundTarget(data);
         const content = formatInboundContent(data);
+        const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
@@ -154,6 +169,7 @@ export class MilkySseEndpoint {
             adapter: this.#options.id,
             target,
             content,
+            segments,
             sender: String(data.sender_id),
             id: formatInboundMessageId(data),
             metadata: Object.freeze({
@@ -176,7 +192,7 @@ export class MilkySseEndpoint {
             }));
         });
     }
-    async #connect() {
+    async #connect(handle) {
         const { url, headers, safeUrl } = buildSseConnectOptions(this.#options.config);
         const create = this.#options.createSseStream ?? ((opts) => openSseStream(opts));
         await new Promise((resolve, reject) => {
@@ -210,20 +226,30 @@ export class MilkySseEndpoint {
                 },
             });
             this.#stream = stream;
+            handle.onForceClose(() => {
+                try {
+                    stream.close();
+                }
+                catch {
+                    /* ignore */
+                }
+            });
             void stream.closed.then(() => {
-                if (this.#stopping)
-                    return;
-                logger.warn(formatCompact({
-                    op: 'disconnect',
-                    endpoint: this.#options.config.name,
-                    mode: 'sse',
-                    reconnect_ms: this.#options.config.reconnect_interval,
-                }));
+                // stop-during-connect 竞态由基座静默 settle（主动停止不算失败），此处仅对运行期断开告警
+                if (this.#lifecycle.state !== 'stopped') {
+                    logger.warn(formatCompact({
+                        op: 'disconnect',
+                        endpoint: this.#options.config.name,
+                        mode: 'sse',
+                        reconnect_ms: this.#options.config.reconnect_interval,
+                    }));
+                }
+                // 基座语义：仅曾 open 的连接才武装重连；初始连接失败由 start() 的 catch 复位
+                handle.notifyClosed(new Error('Milky SSE closed'));
                 if (!settled) {
                     settled = true;
                     reject(new Error('Milky SSE closed before open'));
                 }
-                this.#scheduleReconnect();
             });
         });
     }
@@ -241,21 +267,4 @@ export class MilkySseEndpoint {
             }));
         }
     }
-    #scheduleReconnect() {
-        if (this.#stopping || !this.#started || this.#reconnectTimer)
-            return;
-        const delay = this.#options.config.reconnect_interval;
-        this.#reconnectTimer = setTimeout(() => {
-            this.#reconnectTimer = undefined;
-            void this.#connect().catch((err) => {
-                logger.warn(formatCompact({
-                    op: 'reconnect',
-                    endpoint: this.#options.config.name,
-                    mode: 'sse',
-                    ok: false,
-                    error: err instanceof Error ? err.message : String(err),
-                }));
-            });
-        }, delay);
-    }
 }

package/lib/webhook-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointManagement } 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';
@@ -12,6 +12,7 @@ export interface MilkyWebhookEndpointOptions {
 }
 export declare class MilkyWebhookEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: MilkyWebhookEndpointOptions);
     start(): Promise<void>;
     open(): void;

package/lib/webhook-endpoint.js

@@ -1,11 +1,13 @@
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { readRequestBody, verifyMilkyAccessToken } from './milky-auth.js';
+import { createMilkyEndpointManagement } from './endpoint-management.js';
 import { registerMilkyAgentEndpoint } from './milky-agent-deps.js';
-import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
+import { buildSendAction, callApi, extractInboundAudioUrl, formatInboundContent, formatInboundMessageId, formatInboundSegments, formatInboundTarget, formatOutboundMessageId, formatOutboundSegments, isMentioned, parseMessageReceiveData, parseMilkyMessageId, senderNickname, } from './protocol.js';
 const logger = getLogger('milky');
 export class MilkyWebhookEndpoint {
     #options;
     #callApi;
+    management = createMilkyEndpointManagement(this);
     #routeReleases = [];
     #open = false;
     #started = false;
@@ -144,6 +146,7 @@ export class MilkyWebhookEndpoint {
     #admitMessage(data, event) {
         const target = formatInboundTarget(data);
         const content = formatInboundContent(data);
+        const segments = formatInboundSegments(data);
         const audioUrl = extractInboundAudioUrl(data);
         const nickname = senderNickname(data);
         const mentioned = isMentioned(data, event.self_id);
@@ -151,6 +154,7 @@ export class MilkyWebhookEndpoint {
             adapter: this.#options.id,
             target,
             content,
+            segments,
             sender: String(data.sender_id),
             id: formatInboundMessageId(data),
             metadata: Object.freeze({

package/lib/ws-endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import { type EndpointInstance, type EndpointManagement } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { callApi, type MilkyEvent, type MilkyWsConfig } from './protocol.js';
@@ -12,6 +12,7 @@ export interface MilkyWsEndpointOptions {
 }
 export declare class MilkyWsEndpoint implements EndpointInstance {
     #private;
+    readonly management: EndpointManagement;
     constructor(options: MilkyWsEndpointOptions);
     start(): Promise<void>;
     open(): void;