@zhin.js/adapter-github 3.0.3 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @zhin.js/adapter-github
 
+## 4.0.1
+
+### Patch Changes
+
+- 74b035c: endpoint 管理命令扩展至 18/20 适配器：kook / discord / github（private_key 支持内联文件路径）/ icqq（bindFlow 登记式 add + `icqq login` 引导）/ dingtalk / lark / line / satori / wechat-mp / wecom / weixin-ilink 接入 `endpoint list/add/remove`（字段对齐各自 schema，凭据写 `.env`）。email（smtp/imap 嵌套对象）与 sandbox（无凭据）暂不接。
+- 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
+
+## 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 同步迁移。
+- f32c424: 适配器配置统一为 endpoints 数组格式：`plugins.<adapter>` 为该 adapter 所有 endpoint 的通用配置，`plugins.<adapter>.endpoints[i]` 为单个 endpoint 的特殊配置（逐项覆盖，`name` 必填）。slack / github schema 新增 `endpoints` 属性；icqq / qq / slack 顶层必填改为 `anyOf`（单 endpoint 字段或 `endpoints` 数组二选一，兼容 Ajv strictRequired）。
+- 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/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -24,14 +24,15 @@ Webhook 需要 Root 提供 `@zhin.js/host-http`（`zhin runtime start` 默认装
 # zhin.config.yml
 plugins:
   github:
-    name: my-github-bot
-    app_id: 123456
-    private_key: ./data/github-app.pem
-    webhook_secret: your-secret
     webhook_path: /github/webhook
     auto_reply_repos:
       - zhinjs/zhin
     workspace_root: ./data/github-workspaces
+    endpoints:
+      - name: my-github-bot
+        app_id: 123456
+        private_key: ./data/github-app.pem
+        webhook_secret: your-secret
 ```
 
 ```env
@@ -41,6 +42,20 @@ GITHUB_WEBHOOK_SECRET=your-secret
 
 `private_key` 支持文件路径或 PEM 内容。未配置 `webhook_secret` 时仅 API 出站 / agent 工具可用（无入站）。
 
+多 App：一个插件实例挂多个 endpoint（`endpoints` 数组逐项覆盖顶层字段，`name` 必填）：
+
+```yaml
+plugins:
+  github:
+    endpoints:
+      - name: app-a
+        app_id: 123456
+        private_key: ./data/app-a.pem
+      - name: app-b
+        app_id: 234567
+        private_key: ./data/app-b.pem
+```
+
 ## 已移除的配置
 
 - **`ai.githubMcp.enabled` / `ai.githubMcp.token`**：Plugin Runtime 迁移后 `register-github-mcp`（stdio `@modelcontextprotocol/server-github`，PAT 人身份）已移除，该配置不再生效。如需 MCP 工具，请按新运行时 `mcp/<name>.ts`（`@zhin.js/mcp-feature`）约定自行装配。

package/adapters/github.ts

@@ -10,6 +10,7 @@ import {
   type DatabaseHost,
 } from '@zhin.js/plugin-runtime';
 import { GithubEndpoint } from '../src/endpoint.js';
+import { githubRuntimeStateToken } from '../src/github-runtime-state.js';
 import {
   resolveGithubConfig,
   type GithubAdapterConfig,
@@ -28,9 +29,19 @@ function optionalDatabase(context: AdapterContext): DatabaseHost | undefined {
 
 export default defineAdapter<GithubAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // Issue/PR 评论以 markdown 图片链接消费远程 URL；无交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url'],
+    interactive: 'text',
+  },
   create(context) {
     const config = resolveGithubConfig(context.config);
     const database = optionalDatabase(context);
+    // 注册到插件运行时状态（github endpoint list 的"运行中"数据源）
+    context.use(githubRuntimeStateToken).endpoints.set(config.name, {
+      name: config.name,
+      mode: config.webhookSecret ? 'webhook' : 'api',
+    });
     if (config.webhookSecret) {
       return new GithubEndpoint({
         id: context.id,

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

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

package/commands/endpoint/list.ts

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

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

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

package/lib/endpoint.d.ts

@@ -13,6 +13,10 @@ export interface GithubEndpointOptions {
     readonly config: ResolvedGithubConfig;
     readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export declare class GithubEndpoint implements EndpointInstance {
     #private;
     readonly gh: GhClient;

package/lib/endpoint.js

@@ -10,6 +10,10 @@ import { enrichInboundContent, formatInboundContent, formatOutboundBody, parseCh
 import { registerGithubWebhookRoutes } from './webhook.js';
 import { WorkspaceManager } from './workspace-manager.js';
 const logger = getLogger('github');
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export class GithubEndpoint {
     #options;
     gh;

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

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

package/lib/github-endpoint-commands.js

@@ -0,0 +1,22 @@
+/**
+ * `github endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ *
+ * 字段说明：private_key 内容长且含换行，不适合 kv 直传——运行时（gh-client
+ * resolvePrivateKey）本就支持 PEM 内容或文件路径，故 add 采用**内联路径**形式：
+ * `github endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { githubRuntimeStateToken } from './github-runtime-state.js';
+export const githubEndpointCommands = createEndpointCommands({
+    adapterKey: 'github',
+    adapterDisplayName: 'GitHub',
+    fields: [
+        { key: 'app_id', required: true, env: true, description: 'GitHub App ID' },
+        { key: 'private_key', required: true, description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容' },
+        { key: 'webhook_secret', env: true, description: 'webhook 签名密钥（不配则 API-only）' },
+    ],
+    running: (use) => use(githubRuntimeStateToken).endpoints.values(),
+    describeEntry: (entry) => `app_id: ${String(entry.app_id ?? entry.appId)}`,
+}, defineCommand);

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

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

package/lib/github-runtime-state.js

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

package/lib/workspace-manager.js

@@ -5,7 +5,16 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 const REPO_FULL_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const GIT_REF_ILLEGAL_RE = /[\s\x00-\x1f\x7f~^:?*[\\`;]/;
+const GIT_REF_ILLEGAL_CHARS = new Set('~^:?*[\\`;');
+function containsIllegalGitRefCharacter(ref) {
+    return [...ref].some((character) => {
+        const code = character.charCodeAt(0);
+        return code <= 31
+            || code === 127
+            || /\s/u.test(character)
+            || GIT_REF_ILLEGAL_CHARS.has(character);
+    });
+}
 /**
  * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
  * 返回通过校验的原值，便于调用方直接使用「已消毒」的变量。
@@ -27,7 +36,7 @@ export function assertGitRefName(ref) {
     }
     if (ref.startsWith('-') ||
         ref.includes('..') ||
-        GIT_REF_ILLEGAL_RE.test(ref) ||
+        containsIllegalGitRefCharacter(ref) ||
         ref.endsWith('/') ||
         ref.endsWith('.')) {
         throw new TypeError(`非法的 git ref: ${JSON.stringify(ref)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "3.0.3",
+  "version": "4.0.1",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,20 +41,21 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/command": "1.0.3",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/agent": "1.0.4",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/host-http": "1.0.1",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/agent": "1.0.6",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/host-http": "1.0.3",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -72,11 +73,12 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.4",
-    "zhin.js": "4.1.3"
+    "@zhin.js/agent": "1.0.6",
+    "zhin.js": "5.0.1"
   },
   "files": [
     "adapters",
+    "commands",
     "plugin.ts",
     "schema.json",
     "src",
@@ -102,6 +104,10 @@
       {
         "package": "@zhin.js/adapter",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/command",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/plugin.ts

@@ -1,4 +1,6 @@
+import { createEndpointRuntimeState } from '@zhin.js/adapter';
 import { definePlugin, databaseHostToken } from '@zhin.js/plugin-runtime';
+import { githubRuntimeStateToken } from './src/github-runtime-state.js';
 import { defineGithubOauthUsersTable } from './src/oauth-users.js';
 
 /**
@@ -26,6 +28,8 @@ export default definePlugin({
     displayName: 'GitHub Adapter',
   },
   setup(context) {
+    // 运行中 endpoint 注册表（github endpoint list 的"运行中"数据源）
+    context.resources.provide(githubRuntimeStateToken, createEndpointRuntimeState());
     if (context.resources.has(databaseHostToken)) {
       const host = context.resources.use(databaseHostToken);
       defineGithubOauthUsersTable(host);

package/schema.json

@@ -3,38 +3,10 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "github-bot"
-    },
     "host": {
       "type": "string",
       "description": "GitHub Enterprise hostname (default github.com)"
     },
-    "app_id": {
-      "type": ["string", "number"],
-      "description": "GitHub App ID"
-    },
-    "appId": {
-      "type": ["string", "number"],
-      "description": "GitHub App ID (camelCase alias)"
-    },
-    "private_key": {
-      "type": "string",
-      "description": "GitHub App private key (PEM content or file path)"
-    },
-    "privateKey": {
-      "type": "string",
-      "description": "GitHub App private key (camelCase alias)"
-    },
-    "webhook_secret": {
-      "type": "string",
-      "description": "Webhook HMAC secret; enables httpHostToken POST route"
-    },
-    "webhookSecret": {
-      "type": "string",
-      "description": "Webhook HMAC secret (camelCase alias)"
-    },
     "webhook_path": {
       "type": "string",
       "default": "/github/webhook"
@@ -50,7 +22,9 @@
     },
     "auto_reply_repos": {
       "type": "array",
-      "items": { "type": "string" },
+      "items": {
+        "type": "string"
+      },
       "description": "Repos whose Issue/PR comments auto-trigger AI without @bot"
     },
     "bot_login": {
@@ -60,6 +34,61 @@
     "workspace_root": {
       "type": "string",
       "description": "Managed git workspace root"
+    },
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "GitHub App bot name"
+          },
+          "app_id": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "GitHub App ID"
+          },
+          "appId": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "GitHub App ID (camelCase alias)"
+          },
+          "private_key": {
+            "type": "string",
+            "description": "GitHub App private key (PEM content or file path)"
+          },
+          "privateKey": {
+            "type": "string",
+            "description": "GitHub App private key (camelCase alias)"
+          },
+          "webhook_secret": {
+            "type": "string",
+            "description": "Webhook HMAC secret; enables httpHostToken POST route"
+          },
+          "webhookSecret": {
+            "type": "string",
+            "description": "Webhook HMAC secret (camelCase alias)"
+          }
+        },
+        "required": [
+          "name"
+        ]
+      }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
-  }
+  },
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -32,6 +32,10 @@ export interface GithubEndpointOptions {
   readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
 
+/**
+ * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export class GithubEndpoint implements EndpointInstance {
   readonly #options: GithubEndpointOptions;
   readonly gh: GhClient;

package/src/github-endpoint-commands.ts

@@ -0,0 +1,23 @@
+/**
+ * `github endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ *
+ * 字段说明：private_key 内容长且含换行，不适合 kv 直传——运行时（gh-client
+ * resolvePrivateKey）本就支持 PEM 内容或文件路径，故 add 采用**内联路径**形式：
+ * `github endpoint add mybot app_id=123456 private_key=./data/mybot.pem`。
+ */
+import { createEndpointCommands } from '@zhin.js/adapter';
+import { defineCommand } from '@zhin.js/command';
+import { githubRuntimeStateToken } from './github-runtime-state.js';
+
+export const githubEndpointCommands = createEndpointCommands({
+  adapterKey: 'github',
+  adapterDisplayName: 'GitHub',
+  fields: [
+    { key: 'app_id', required: true, env: true, description: 'GitHub App ID' },
+    { key: 'private_key', required: true, description: 'PEM 文件路径（推荐，如 ./data/xxx.pem）或 PEM 内容' },
+    { key: 'webhook_secret', env: true, description: 'webhook 签名密钥（不配则 API-only）' },
+  ],
+  running: (use) => use(githubRuntimeStateToken).endpoints.values(),
+  describeEntry: (entry) => `app_id: ${String(entry.app_id ?? entry.appId)}`,
+}, defineCommand);

package/src/github-runtime-state.ts

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

package/src/workspace-manager.ts

@@ -7,7 +7,17 @@ import path from 'node:path';
 import type { GhClient, GitHubBotIdentity } from './gh-client.js';
 
 const REPO_FULL_NAME_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
-const GIT_REF_ILLEGAL_RE = /[\s\x00-\x1f\x7f~^:?*[\\`;]/;
+const GIT_REF_ILLEGAL_CHARS = new Set('~^:?*[\\`;');
+
+function containsIllegalGitRefCharacter(ref: string): boolean {
+  return [...ref].some((character) => {
+    const code = character.charCodeAt(0);
+    return code <= 31
+      || code === 127
+      || /\s/u.test(character)
+      || GIT_REF_ILLEGAL_CHARS.has(character);
+  });
+}
 
 /**
  * 校验 GitHub "owner/name" 全名，防止路径穿越与 git 选项注入。
@@ -34,7 +44,7 @@ export function assertGitRefName(ref: string): string {
   if (
     ref.startsWith('-') ||
     ref.includes('..') ||
-    GIT_REF_ILLEGAL_RE.test(ref) ||
+    containsIllegalGitRefCharacter(ref) ||
     ref.endsWith('/') ||
     ref.endsWith('.')
   ) {