@zhin.js/adapter 1.1.4 → 1.1.5

package/README.md

@@ -27,9 +27,9 @@ Adapter definitions declare `capabilities` for inbound/outbound admission and
 instead of probing optional endpoint methods. The zero-dependency types live in
 [`@zhin.js/im-contract`](../im-contract/README.md).
 
-New framework-facing outbound code should carry a structured `ConversationRef`.
-`EndpointSendRequest.target` remains temporarily for platform codecs that still
-need their legacy target string; it is not a general-purpose message identity.
+Framework-facing outbound code carries a structured `ConversationRef`.
+`EndpointSendRequest` is `{ conversation, payload }`; platform adapters derive
+their native target from `conversation` at the endpoint boundary.
 
 ## Endpoint Control Port
 

package/lib/definition.d.ts

@@ -12,19 +12,9 @@ export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 /** 交互段（卡片/按钮等富交互）的端点消费方式。 */
 export type AdapterInteractiveMode = 'native' | 'text';
 export interface EndpointSendRequest {
-    /**
-     * Structured identity for new callers. The target remains until every
-     * platform adapter has migrated its native boundary codec.
-     */
-    readonly conversation?: ConversationRef;
-    /** @deprecated Use conversation for framework-facing code. */
-    readonly target: string;
+    /** 结构化会话寻址；端点在平台边界自行派生原生 target。 */
+    readonly conversation: ConversationRef;
     readonly payload: unknown;
-    readonly parent?: {
-        readonly type?: string;
-        readonly id?: string;
-        readonly name?: string;
-    };
 }
 export interface EndpointInstance<TResult = unknown> {
     /** Optional platform-neutral Console/Host management surface. */

package/lib/endpoint-commands.d.ts

@@ -89,8 +89,9 @@ export interface EndpointCommandsSpec {
  * provider 层不允许 import @zhin.js/command，故 defineCommand 由调用方注入，
  * 这里只描述结构；适配器侧传入 defineCommand 后 TCommand 即 Readonly<CommandDefinition>。
  *
- * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象），
- * 否则注入的 defineCommand 会因 TS 逆变检查失败（TS2345）。
+ * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象 / rest 段的
+ * `ReadonlyArray<string | number | boolean>`），否则注入的 defineCommand 会因
+ * TS 逆变检查失败（TS2345）。
  */
 export interface EndpointCommandContext {
     readonly config: unknown;
@@ -101,11 +102,16 @@ export interface EndpointCommandContext {
      */
     readonly input?: unknown;
     readonly args: readonly string[];
-    readonly params: Readonly<Record<string, string | number | boolean | Readonly<Record<string, unknown>> | null>>;
+    readonly params: Readonly<Record<string, string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null>>;
     readonly use: EndpointCommandUse;
 }
 export interface EndpointCommandDefinition {
     readonly description?: string;
+    readonly params?: Readonly<Record<string, {
+        readonly type: 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text' | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
+        readonly default?: string | number | boolean | ReadonlyArray<string | number | boolean> | Readonly<Record<string, unknown>> | null;
+        readonly description?: string;
+    }>>;
     execute(context: EndpointCommandContext): unknown;
 }
 export interface EndpointCommands<TCommand = EndpointCommandDefinition> {

package/lib/endpoint-commands.js

@@ -20,7 +20,7 @@
  * 3. src 下 `export const telegramEndpointCommands = createEndpointCommands({ adapterKey: 'telegram', ... }, defineCommand)`
  *    （defineCommand 由调用方从 @zhin.js/command 传入——provider 包之间禁止互相 import，
  *    见 scripts/check-architecture-layers.mjs，故 defineCommand 走依赖注入）。
- * 4. commands/endpoint/{list.ts, add/[name:string].ts, remove/[name:string].ts} 分别
+ * 4. commands/endpoint/{list.ts, add/[name].ts, remove/[name].ts} 分别
  *    `export default telegramEndpointCommands.list|add|remove`。
  *
  * 注意：adapterKey 即实例 key（zhin.config.yml 的 plugins.<key>）；多实例自定义 key 时
@@ -355,6 +355,7 @@ export function createEndpointCommands(spec, defineCommand) {
         add: defineCommand({
             description: spec.addDescription
                 ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
+            params: { name: { type: 'string', description: 'endpoint 名称' } },
             execute({ config, input, params, args, use }) {
                 if (!isEndpointOperator(config, input))
                     return forbidden;
@@ -375,6 +376,7 @@ export function createEndpointCommands(spec, defineCommand) {
         }),
         remove: defineCommand({
             description: `从 zhin.config.yml 的 plugins.${spec.adapterKey}.endpoints 移除指定 endpoint（重启生效）`,
+            params: { name: { type: 'string', description: 'endpoint 名称' } },
             execute({ config, input, params }) {
                 if (!isEndpointOperator(config, input))
                     return forbidden;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "Convention-based Adapter and Endpoint Feature for Zhin Plugin Runtime",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,15 +18,15 @@
   ],
   "dependencies": {
     "yaml": "^2.9.0",
-    "@zhin.js/feature-kit": "1.0.5",
-    "@zhin.js/im-contract": "1.0.0",
+    "@zhin.js/feature-kit": "1.0.6",
+    "@zhin.js/im-contract": "1.0.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/plugin-runtime": "1.1.3"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
-    "@zhin.js/command": "1.0.6"
+    "@zhin.js/command": "1.0.7"
   },
   "zhin": {
     "protocol": 1,

package/src/definition.ts

@@ -22,15 +22,9 @@ export type AdapterOutboundMedia = 'url' | 'path' | 'base64' | 'upload';
 export type AdapterInteractiveMode = 'native' | 'text';
 
 export interface EndpointSendRequest {
-  /**
-   * Structured identity for new callers. The target remains until every
-   * platform adapter has migrated its native boundary codec.
-   */
-  readonly conversation?: ConversationRef;
-  /** @deprecated Use conversation for framework-facing code. */
-  readonly target: string;
+  /** 结构化会话寻址；端点在平台边界自行派生原生 target。 */
+  readonly conversation: ConversationRef;
   readonly payload: unknown;
-  readonly parent?: { readonly type?: string; readonly id?: string; readonly name?: string };
 }
 
 export interface EndpointInstance<TResult = unknown> {

package/src/endpoint-commands.ts

@@ -20,7 +20,7 @@
  * 3. src 下 `export const telegramEndpointCommands = createEndpointCommands({ adapterKey: 'telegram', ... }, defineCommand)`
  *    （defineCommand 由调用方从 @zhin.js/command 传入——provider 包之间禁止互相 import，
  *    见 scripts/check-architecture-layers.mjs，故 defineCommand 走依赖注入）。
- * 4. commands/endpoint/{list.ts, add/[name:string].ts, remove/[name:string].ts} 分别
+ * 4. commands/endpoint/{list.ts, add/[name].ts, remove/[name].ts} 分别
  *    `export default telegramEndpointCommands.list|add|remove`。
  *
  * 注意：adapterKey 即实例 key（zhin.config.yml 的 plugins.<key>）；多实例自定义 key 时
@@ -355,8 +355,9 @@ export interface EndpointCommandsSpec {
  * provider 层不允许 import @zhin.js/command，故 defineCommand 由调用方注入，
  * 这里只描述结构；适配器侧传入 defineCommand 后 TCommand 即 Readonly<CommandDefinition>。
  *
- * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象），
- * 否则注入的 defineCommand 会因 TS 逆变检查失败（TS2345）。
+ * `params` 值域须与 CommandParameterValue 对齐（含 null / 结构化对象 / rest 段的
+ * `ReadonlyArray<string | number | boolean>`），否则注入的 defineCommand 会因
+ * TS 逆变检查失败（TS2345）。
  */
 export interface EndpointCommandContext {
   readonly config: unknown;
@@ -369,13 +370,33 @@ export interface EndpointCommandContext {
   readonly args: readonly string[];
   readonly params: Readonly<Record<
     string,
-    string | number | boolean | Readonly<Record<string, unknown>> | null
+    | string
+    | number
+    | boolean
+    | ReadonlyArray<string | number | boolean>
+    | Readonly<Record<string, unknown>>
+    | null
   >>;
   readonly use: EndpointCommandUse;
 }
 
 export interface EndpointCommandDefinition {
   readonly description?: string;
+  // 与 @zhin.js/command 的 CommandParamSchema 结构对齐（provider 层不能 import
+  // command，字面量联合在此镜像声明；新增参数类型须两侧同步）。
+  readonly params?: Readonly<Record<string, {
+    readonly type:
+      | 'string' | 'number' | 'integer' | 'float' | 'boolean' | 'word' | 'text'
+      | 'mention' | 'image' | 'face' | 'reply' | 'forward' | 'dice' | 'rps';
+    readonly default?:
+      | string
+      | number
+      | boolean
+      | ReadonlyArray<string | number | boolean>
+      | Readonly<Record<string, unknown>>
+      | null;
+    readonly description?: string;
+  }>>;
   execute(context: EndpointCommandContext): unknown;
 }
 
@@ -532,6 +553,7 @@ export function createEndpointCommands<TCommand>(
     add: defineCommand({
       description: spec.addDescription
         ?? `手动添加 ${spec.adapterDisplayName} endpoint（凭据写入 .env 并追加到 zhin.config.yml，重启生效）`,
+      params: { name: { type: 'string', description: 'endpoint 名称' } },
       execute({ config, input, params, args, use }) {
         if (!isEndpointOperator(config, input)) return forbidden;
         const name = endpointNameParam(params);
@@ -550,6 +572,7 @@ export function createEndpointCommands<TCommand>(
     }),
     remove: defineCommand({
       description: `从 zhin.config.yml 的 plugins.${spec.adapterKey}.endpoints 移除指定 endpoint（重启生效）`,
+      params: { name: { type: 'string', description: 'endpoint 名称' } },
       execute({ config, input, params }) {
         if (!isEndpointOperator(config, input)) return forbidden;
         return removeEndpointByName(spec, String(params.name ?? ''));