@zhin.js/adapter-github 5.0.2 → 5.0.5

package/CHANGELOG.md

@@ -1,5 +1,95 @@
 # @zhin.js/adapter-github
 
+## 5.0.5
+
+### Patch Changes
+
+- 36c7400: Replace `AgentPromptBuildContext.commMessage` with an authenticated platform projection and make Agent prompt assembly consume canonical Turn identity. Platform contributors and prompt hooks no longer receive a classic IM `Message`.
+
+  Remove the unused Message field and active-context escape hatch from PromptController; turn scheduling is keyed only by canonical session identity.
+
+- Updated dependencies [6f9c366]
+- Updated dependencies [373a56b]
+- Updated dependencies [0de46a8]
+- Updated dependencies [c106ecc]
+- Updated dependencies [ca92e03]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [b08f7fe]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [a9fa72e]
+- Updated dependencies [c8de3ef]
+- Updated dependencies [60f0fc8]
+- Updated dependencies [574c990]
+- Updated dependencies [d096f16]
+- Updated dependencies [3f29623]
+- Updated dependencies [2916852]
+- Updated dependencies [d047869]
+- Updated dependencies [162fa34]
+- Updated dependencies [e62561e]
+- Updated dependencies [3eeeb46]
+- Updated dependencies [85d0f82]
+- Updated dependencies [61bfc1c]
+- Updated dependencies [04bad47]
+- Updated dependencies [e40b048]
+- Updated dependencies [5a5b1bb]
+- Updated dependencies [f1708c3]
+- Updated dependencies [d254a81]
+- Updated dependencies [7123c47]
+- Updated dependencies [05befc1]
+- Updated dependencies [0663b6a]
+- Updated dependencies [f28f9b3]
+- Updated dependencies [9f340f7]
+- Updated dependencies [e53444f]
+- Updated dependencies [5eedd26]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [f919b6f]
+- Updated dependencies [098e411]
+- Updated dependencies [e1b7c01]
+- Updated dependencies [9b94f87]
+- Updated dependencies [a7df753]
+  - @zhin.js/agent@1.1.5
+  - @zhin.js/host-http@1.0.8
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/command@1.0.9
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.4
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/host-http@1.0.7
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/agent@1.1.4
+  - @zhin.js/command@1.0.8
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 5.0.3
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - @zhin.js/command@1.0.7
+  - @zhin.js/host-http@1.0.6
+  - @zhin.js/agent@1.1.3
+  - zhin.js@6.0.2
+
 ## 5.0.2
 
 ### Patch Changes

package/README.md

@@ -6,7 +6,7 @@ GitHub Plugin Runtime 适配器 — Issue/PR 评论区即聊天通道，GitHub A
 
 - **聊天通道**：Issue/PR 评论区映射为群聊，支持收发消息
 - **Webhook 入站**：HMAC-SHA256 验签 → `messageGatewayToken`
-- **出站**：`send({ target, payload })` → Issue/PR comment（target 为 channel ID）
+- **出站**：`send({ conversation, payload })` → Issue/PR comment（`conversation.id` 为 channel ID）
 - **GitHub App 认证**：JWT → Installation Token
 - **Agent 工具**：`agent/` 下 star/bind/subscribe/workspace 等保留
 
@@ -85,7 +85,7 @@ plugins:
 | `src/gh-client.ts` | GitHub API 客户端 |
 
 - 入站：`httpHostToken` POST → `messageGatewayToken.receive`
-- 出站：`send({ target, payload })`
+- 出站：`send({ conversation, payload })`
 
 ## License
 

package/adapters/github.js

@@ -30,8 +30,8 @@ export default defineAdapter({
         const config = resolveGithubConfig(context.config);
         const database = optionalDatabase(context);
         // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
-        context.use(githubRuntimeStateToken).endpoints.set(config.name, {
-            name: config.name,
+        context.use(githubRuntimeStateToken).endpoints.set(config.id, {
+            id: config.id,
             mode: config.webhookSecret ? 'webhook' : 'api',
         });
         if (config.webhookSecret) {

package/adapters/github.ts

@@ -7,7 +7,7 @@ import { messageGatewayToken } from '@zhin.js/core/runtime';
 import { httpHostToken } from '@zhin.js/host-http';
 import {
   databaseHostToken,
-  type DatabaseHost,
+  type PluginDatabaseHost,
 } from '@zhin.js/plugin-runtime';
 import { GithubEndpoint } from '../src/endpoint.js';
 import { githubRuntimeStateToken } from '../src/github-runtime-state.js';
@@ -19,7 +19,7 @@ import {
 export { GithubEndpoint } from '../src/endpoint.js';
 export type { GithubEndpointOptions } from '../src/endpoint.js';
 
-function optionalDatabase(context: AdapterContext): DatabaseHost | undefined {
+function optionalDatabase(context: AdapterContext): PluginDatabaseHost | undefined {
   try {
     return context.use(databaseHostToken);
   } catch {
@@ -38,8 +38,8 @@ export default defineAdapter<GithubAdapterConfig>({
     const config = resolveGithubConfig(context.config);
     const database = optionalDatabase(context);
     // 注册到插件运行时状态（github.endpoint list 的"运行中"数据源）
-    context.use(githubRuntimeStateToken).endpoints.set(config.name, {
-      name: config.name,
+    context.use(githubRuntimeStateToken).endpoints.set(config.id, {
+      id: config.id,
       mode: config.webhookSecret ? 'webhook' : 'api',
     });
     if (config.webhookSecret) {

package/lib/endpoint.d.ts

@@ -1,7 +1,7 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost } from '@zhin.js/host-http';
-import type { CapabilityId, DatabaseHost } from '@zhin.js/plugin-runtime';
+import type { CapabilityId, PluginDatabaseHost } from '@zhin.js/plugin-runtime';
 import { GhClient } from './gh-client.js';
 import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
 import { WorkspaceManager } from './workspace-manager.js';
@@ -9,7 +9,7 @@ export interface GithubEndpointOptions {
     readonly id: CapabilityId;
     readonly gateway: MessageGateway;
     readonly http?: HttpHost;
-    readonly database?: DatabaseHost;
+    readonly database?: PluginDatabaseHost;
     readonly config: ResolvedGithubConfig;
     readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
@@ -37,15 +37,12 @@ export declare class GithubEndpoint implements EndpointInstance {
         target_type: string;
     }[];
     getWorkspaceManager(): WorkspaceManager;
-    getDatabase(): DatabaseHost | undefined;
+    getDatabase(): PluginDatabaseHost | undefined;
     start(): Promise<void>;
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed comment when open. */
     admit(comment: GithubInboundComment): void;
 }

package/lib/endpoint.js

@@ -2,19 +2,19 @@
  * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
 import path from 'node:path';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import { GhClient } from './gh-client.js';
 import { registerGithubAgentEndpoint } from './github-agent-deps.js';
 import { lookupGithubOauthAccessToken } from './oauth-users.js';
-import { enrichInboundContent, formatInboundContent, formatOutboundBody, parseChannelId, } from './protocol.js';
+import { enrichInboundContent, formatInboundContent, formatOutboundBody, githubInboundConversation, parseChannelId, } from './protocol.js';
 import { registerGithubWebhookRoutes } from './webhook.js';
 import { WorkspaceManager } from './workspace-manager.js';
-const logger = getLogger('github');
 /**
  * GitHub 是代码协作面（issue/PR），无好友/群/频道等 IM 社交概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
 export class GithubEndpoint {
+    #logger;
     #options;
     gh;
     config;
@@ -25,9 +25,10 @@ export class GithubEndpoint {
     #started = false;
     #unregisterAgent;
     constructor(options) {
+        this.#logger = getAdapterLogger('github', options.config.id);
         this.#options = options;
         this.config = options.config;
-        this.name = options.config.name;
+        this.name = options.config.id;
         this.gh = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
     }
     getAPI() {
@@ -78,14 +79,14 @@ export class GithubEndpoint {
                     throw new TypeError('GitHub webhook_secret requires httpHostToken');
                 }
                 this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
-                logger.debug(formatCompact({
+                this.#logger.debug(formatCompact({
                     endpoint: this.name,
                     op: 'webhook',
                     path: this.config.webhookPath,
                 }));
             }
             else {
-                logger.debug(formatCompact({
+                this.#logger.debug(formatCompact({
                     endpoint: this.name,
                     op: 'connect',
                     mode: 'api-only',
@@ -95,7 +96,7 @@ export class GithubEndpoint {
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect GitHub endpoint:', error);
+            this.#logger.error('Failed to connect GitHub endpoint:', error);
             throw error;
         }
     }
@@ -112,22 +113,22 @@ export class GithubEndpoint {
         this.#unregisterAgent?.();
         this.#unregisterAgent = undefined;
         this.#started = false;
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ target, payload }) {
-        const parsed = parseChannelId(target);
+    async send({ conversation, payload }) {
+        const parsed = parseChannelId(conversation.id);
         if (!parsed)
-            throw new Error(`无效的 GitHub channel ID: ${target}`);
+            throw new Error(`无效的 GitHub conversation ID: ${conversation.id}`);
         const text = formatOutboundBody(payload);
         const r = parsed.type === 'issue'
             ? await this.gh.createIssueComment(parsed.repo, parsed.number, text)
             : await this.gh.createPRComment(parsed.repo, parsed.number, text);
         if (!r.ok)
             throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
             op: 'github_send',
             endpoint: this.name,
-            target,
+            target: `${conversation.kind}:${conversation.id}`,
             messageId: r.data.id,
         }));
         return String(r.data.id);
@@ -139,23 +140,23 @@ export class GithubEndpoint {
         const botUser = this.config.botLogin || this.gh.getBotLogin() || this.gh.authenticatedUser;
         if (botUser && comment.sender === botUser)
             return;
+        const conversation = githubInboundConversation(String(this.#options.id), comment);
         const content = enrichInboundContent(formatInboundContent(comment.content), this.config, botUser ?? undefined, comment.repo);
         void this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: comment.channelId,
+            conversation,
+            message: { conversation, id: comment.id },
             content,
-            sender: comment.sender,
-            id: comment.id,
+            sender: { id: comment.sender, name: comment.sender },
+            endpointId: this.name,
             metadata: Object.freeze({
-                endpoint: this.name,
                 repo: comment.repo,
                 kind: comment.kind,
                 createdAt: comment.createdAt,
             }),
         }).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'github_gateway_receive_failed',
-                target: comment.channelId,
+                target: `${conversation.kind}:${conversation.id}`,
                 error: err instanceof Error ? err.message : String(err),
             }));
         });

package/lib/github-agent-deps.d.ts

@@ -27,7 +27,7 @@ export interface GithubAgentEndpoint {
     getDatabase?(): unknown;
 }
 export interface GithubAgentDeps {
-    getEndpoint: (endpointId?: string) => GithubAgentEndpoint;
+    getEndpoint: (endpointKey?: string) => GithubAgentEndpoint;
     /** Alias kept for existing agent handlers that call getAdapter(). */
     getAdapter: () => GithubAgentEndpoint;
     getWorkspaceManager: () => WorkspaceManager;
@@ -40,7 +40,7 @@ export interface GithubAgentDeps {
         error: (...args: unknown[]) => void;
     };
 }
-export declare function registerGithubAgentEndpoint(endpointId: string, endpoint: GithubAgentEndpoint): () => void;
+export declare function registerGithubAgentEndpoint(endpointKey: string, endpoint: GithubAgentEndpoint): () => void;
 /** Optional override used by tests / transitional callers. Pass `null` to clear. */
 export declare function setGithubAgentDeps(deps: GithubAgentDeps | null): void;
 export declare function getGithubAgentDeps(): GithubAgentDeps;

package/lib/github-agent-deps.js

@@ -4,11 +4,11 @@
  */
 const endpoints = new Map();
 let override = null;
-export function registerGithubAgentEndpoint(endpointId, endpoint) {
-    endpoints.set(endpointId, endpoint);
+export function registerGithubAgentEndpoint(endpointKey, endpoint) {
+    endpoints.set(endpointKey, endpoint);
     return () => {
-        if (endpoints.get(endpointId) === endpoint) {
-            endpoints.delete(endpointId);
+        if (endpoints.get(endpointKey) === endpoint) {
+            endpoints.delete(endpointKey);
         }
     };
 }
@@ -16,11 +16,11 @@ export function registerGithubAgentEndpoint(endpointId, endpoint) {
 export function setGithubAgentDeps(deps) {
     override = deps;
 }
-function lookup(endpointId) {
-    if (endpointId) {
-        const registered = endpoints.get(endpointId);
+function lookup(endpointKey) {
+    if (endpointKey) {
+        const registered = endpoints.get(endpointKey);
         if (!registered)
-            throw new Error(`Endpoint ${endpointId} 不存在`);
+            throw new Error(`Endpoint ${endpointKey} 不存在`);
         return registered;
     }
     const first = endpoints.values().next().value;

package/lib/oauth-users.d.ts

@@ -1,4 +1,4 @@
-import type { DatabaseHost } from '@zhin.js/plugin-runtime';
+import type { DatabaseHost, PluginDatabaseHost } from '@zhin.js/plugin-runtime';
 export declare const GITHUB_OAUTH_USERS_TABLE = "github_oauth_users";
 export declare const GITHUB_OAUTH_USERS_SCHEMA: {
     readonly id: {
@@ -30,4 +30,4 @@ export declare function defineGithubOauthUsersTable(host: {
     define(name: string, definition: Record<string, unknown>): void;
 }): void;
 /** Resolve a stored PAT/device-flow token; null when DB missing or no row. */
-export declare function lookupGithubOauthAccessToken(database: DatabaseHost | undefined, platform: string, platformUid: string): Promise<string | null>;
+export declare function lookupGithubOauthAccessToken(database: DatabaseHost | PluginDatabaseHost | undefined, platform: string, platformUid: string): Promise<string | null>;

package/lib/protocol.d.ts

@@ -3,12 +3,13 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { IncomingMessage } from 'node:http';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { type GenericWebhookPayload, type IssueCommentPayload, type PRReviewCommentPayload, type PRReviewPayload } from './types.js';
 export type { EventType, GenericWebhookPayload, GitHubComment, GitHubEndpointConfig, GitHubIssue, GitHubOAuthUser, GitHubPR, GitHubRepo, GitHubUser, IssueCommentPayload, ParsedChannel, PRReviewCommentPayload, PRReviewPayload, Subscription, } from './types.js';
 export { buildChannelId, parseChannelId } from './types.js';
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface GithubAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly host?: string;
     readonly app_id?: string | number;
     readonly appId?: string | number;
@@ -41,7 +42,7 @@ export interface GithubAdapterConfig {
 }
 export interface ResolvedGithubConfig {
     readonly context: 'github';
-    readonly name: string;
+    readonly id: string;
     readonly host?: string;
     readonly appId?: string | number;
     readonly privateKey?: string;
@@ -65,6 +66,12 @@ export interface GithubInboundComment {
     readonly kind: 'issue_comment' | 'pr_review_comment' | 'pr_review';
     readonly createdAt: number;
 }
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export declare function githubInboundConversation(endpointKey: string, comment: GithubInboundComment): ConversationRef;
 export declare function resolveGithubConfig(config?: GithubAdapterConfig): ResolvedGithubConfig;
 export declare function normalizeWebhookPath(path: string): string;
 export declare function shouldAutoReplyRepo(config: Pick<ResolvedGithubConfig, 'autoReplyRepos'>, repo: string): boolean;

package/lib/protocol.js

@@ -9,6 +9,19 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('github');
 import { buildChannelId, } from './types.js';
 export { buildChannelId, parseChannelId } from './types.js';
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export function githubInboundConversation(endpointKey, comment) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'channel',
+        id: comment.channelId,
+        parent: { kind: 'channel', id: comment.repo },
+    };
+}
 export function resolveGithubConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'github');
     const appIdRaw = pickCredential(config.appId != null ? String(config.appId) : undefined, config.app_id != null ? String(config.app_id) : undefined, entry?.appId != null ? String(entry.appId) : undefined, entry?.app_id != null ? String(entry.app_id) : undefined, process.env.GITHUB_APP_ID);
@@ -17,8 +30,8 @@ export function resolveGithubConfig(config = {}) {
     if (!appId || !privateKey) {
         throw new TypeError('GitHub adapter requires app_id + private_key (plugins.<key> or GITHUB_APP_ID)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.GITHUB_BOT_NAME
         || 'github-bot';
     const webhookSecret = config.webhookSecret ?? config.webhook_secret
@@ -38,7 +51,7 @@ export function resolveGithubConfig(config = {}) {
         ?? entry?.workspaceRoot ?? entry?.workspace_root;
     return {
         context: 'github',
-        name,
+        id,
         ...(host ? { host } : {}),
         ...(appId != null ? { appId } : {}),
         ...(privateKey ? { privateKey } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-github",
-  "version": "5.0.2",
+  "version": "5.0.5",
   "description": "Zhin.js GitHub adapter for Plugin Runtime (App auth + webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -41,21 +41,22 @@
     "directory": "plugins/adapters/github"
   },
   "dependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/command": "1.0.6",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/command": "1.0.9",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/agent": "1.1.2",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/host-http": "1.0.5",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/agent": "1.1.5",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/host-http": "1.0.8",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -73,8 +74,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/agent": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "files": [
     "adapters",

package/schema.json

@@ -35,6 +35,24 @@
       "type": "string",
       "description": "Managed git workspace root"
     },
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（GitHub user login or id；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted GitHub user login or id"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
       "description": "多账号：一个插件实例挂多个 endpoint",
@@ -42,9 +60,23 @@
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "GitHub App bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（GitHub user login or id）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted GitHub user login or id"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "app_id": {
             "type": [
@@ -75,10 +107,14 @@
           "webhookSecret": {
             "type": "string",
             "description": "Webhook HMAC secret (camelCase alias)"
+          },
+          "id": {
+            "type": "string",
+            "description": "GitHub App bot name"
           }
         },
         "required": [
-          "name"
+          "id"
         ]
       }
     },

package/src/endpoint.ts

@@ -2,11 +2,11 @@
  * GithubEndpoint — lifecycle, outbound send, inbound admit.
  */
 import path from 'node:path';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
-import { formatCompact, getLogger } from '@zhin.js/logger';
-import type { CapabilityId, DatabaseHost } from '@zhin.js/plugin-runtime';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId, PluginDatabaseHost } from '@zhin.js/plugin-runtime';
 import { GhClient } from './gh-client.js';
 import { registerGithubAgentEndpoint } from './github-agent-deps.js';
 import { lookupGithubOauthAccessToken } from './oauth-users.js';
@@ -14,6 +14,7 @@ import {
   enrichInboundContent,
   formatInboundContent,
   formatOutboundBody,
+  githubInboundConversation,
   parseChannelId,
   type GithubInboundComment,
   type ResolvedGithubConfig,
@@ -21,13 +22,11 @@ import {
 import { registerGithubWebhookRoutes } from './webhook.js';
 import { WorkspaceManager } from './workspace-manager.js';
 
-const logger = getLogger('github');
-
 export interface GithubEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
   readonly http?: HttpHost;
-  readonly database?: DatabaseHost;
+  readonly database?: PluginDatabaseHost;
   readonly config: ResolvedGithubConfig;
   readonly createClient?: (config: ResolvedGithubConfig) => GhClient;
 }
@@ -37,6 +36,8 @@ export interface GithubEndpointOptions {
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
 export class GithubEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: GithubEndpointOptions;
   readonly gh: GhClient;
   readonly config: ResolvedGithubConfig;
@@ -48,9 +49,10 @@ export class GithubEndpoint implements EndpointInstance {
   #unregisterAgent?: () => void;
 
   constructor(options: GithubEndpointOptions) {
+    this.#logger = getAdapterLogger('github', options.config.id);
     this.#options = options;
     this.config = options.config;
-    this.name = options.config.name;
+    this.name = options.config.id;
     this.gh = options.createClient?.(options.config) ?? defaultCreateClient(options.config);
   }
 
@@ -94,7 +96,7 @@ export class GithubEndpoint implements EndpointInstance {
     return this.#workspaceManager;
   }
 
-  getDatabase(): DatabaseHost | undefined {
+  getDatabase(): PluginDatabaseHost | undefined {
     return this.#options.database;
   }
 
@@ -110,13 +112,13 @@ export class GithubEndpoint implements EndpointInstance {
           throw new TypeError('GitHub webhook_secret requires httpHostToken');
         }
         this.#routeReleases.push(...registerGithubWebhookRoutes(this.#options.http, this));
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
           endpoint: this.name,
           op: 'webhook',
           path: this.config.webhookPath,
         }));
       } else {
-        logger.debug(formatCompact({
+        this.#logger.debug(formatCompact({
           endpoint: this.name,
           op: 'connect',
           mode: 'api-only',
@@ -125,7 +127,7 @@ export class GithubEndpoint implements EndpointInstance {
       }
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect GitHub endpoint:', error);
+      this.#logger.error('Failed to connect GitHub endpoint:', error);
       throw error;
     }
   }
@@ -144,21 +146,21 @@ export class GithubEndpoint implements EndpointInstance {
     this.#unregisterAgent?.();
     this.#unregisterAgent = undefined;
     this.#started = false;
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
-    const parsed = parseChannelId(target);
-    if (!parsed) throw new Error(`无效的 GitHub channel ID: ${target}`);
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const parsed = parseChannelId(conversation.id);
+    if (!parsed) throw new Error(`无效的 GitHub conversation ID: ${conversation.id}`);
     const text = formatOutboundBody(payload);
     const r = parsed.type === 'issue'
       ? await this.gh.createIssueComment(parsed.repo, parsed.number, text)
       : await this.gh.createPRComment(parsed.repo, parsed.number, text);
     if (!r.ok) throw new Error(`发送失败: ${JSON.stringify(r.data)}`);
-    logger.debug(formatCompact({
+    this.#logger.debug(formatCompact({
       op: 'github_send',
       endpoint: this.name,
-      target,
+      target: `${conversation.kind}:${conversation.id}`,
       messageId: r.data.id,
     }));
     return String(r.data.id);
@@ -169,6 +171,7 @@ export class GithubEndpoint implements EndpointInstance {
     if (!this.#open) return;
     const botUser = this.config.botLogin || this.gh.getBotLogin() || this.gh.authenticatedUser;
     if (botUser && comment.sender === botUser) return;
+    const conversation = githubInboundConversation(String(this.#options.id), comment);
     const content = enrichInboundContent(
       formatInboundContent(comment.content),
       this.config,
@@ -176,21 +179,20 @@ export class GithubEndpoint implements EndpointInstance {
       comment.repo,
     );
     void this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: comment.channelId,
+      conversation,
+      message: { conversation, id: comment.id },
       content,
-      sender: comment.sender,
-      id: comment.id,
+      sender: { id: comment.sender, name: comment.sender },
+      endpointId: this.name,
       metadata: Object.freeze({
-        endpoint: this.name,
         repo: comment.repo,
         kind: comment.kind,
         createdAt: comment.createdAt,
       }),
     }).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'github_gateway_receive_failed',
-        target: comment.channelId,
+        target: `${conversation.kind}:${conversation.id}`,
         error: err instanceof Error ? err.message : String(err),
       }));
     });

package/src/github-agent-deps.ts

@@ -23,7 +23,7 @@ export interface GithubAgentEndpoint {
 }
 
 export interface GithubAgentDeps {
-  getEndpoint: (endpointId?: string) => GithubAgentEndpoint;
+  getEndpoint: (endpointKey?: string) => GithubAgentEndpoint;
   /** Alias kept for existing agent handlers that call getAdapter(). */
   getAdapter: () => GithubAgentEndpoint;
   getWorkspaceManager: () => WorkspaceManager;
@@ -39,13 +39,13 @@ const endpoints = new Map<string, GithubAgentEndpoint>();
 let override: GithubAgentDeps | null = null;
 
 export function registerGithubAgentEndpoint(
-  endpointId: string,
+  endpointKey: string,
   endpoint: GithubAgentEndpoint,
 ): () => void {
-  endpoints.set(endpointId, endpoint);
+  endpoints.set(endpointKey, endpoint);
   return () => {
-    if (endpoints.get(endpointId) === endpoint) {
-      endpoints.delete(endpointId);
+    if (endpoints.get(endpointKey) === endpoint) {
+      endpoints.delete(endpointKey);
     }
   };
 }
@@ -55,10 +55,10 @@ export function setGithubAgentDeps(deps: GithubAgentDeps | null): void {
   override = deps;
 }
 
-function lookup(endpointId?: string): GithubAgentEndpoint {
-  if (endpointId) {
-    const registered = endpoints.get(endpointId);
-    if (!registered) throw new Error(`Endpoint ${endpointId} 不存在`);
+function lookup(endpointKey?: string): GithubAgentEndpoint {
+  if (endpointKey) {
+    const registered = endpoints.get(endpointKey);
+    if (!registered) throw new Error(`Endpoint ${endpointKey} 不存在`);
     return registered;
   }
   const first = endpoints.values().next().value;

package/src/oauth-users.ts

@@ -2,7 +2,7 @@
  * github_oauth_users — SSOT for Runtime user-token binding (gh bind / Endpoint lookup).
  */
 import { formatCompact, getLogger } from '@zhin.js/logger';
-import type { DatabaseHost } from '@zhin.js/plugin-runtime';
+import type { DatabaseHost, PluginDatabaseHost } from '@zhin.js/plugin-runtime';
 
 const logger = getLogger('github');
 
@@ -25,7 +25,7 @@ export function defineGithubOauthUsersTable(
 
 /** Resolve a stored PAT/device-flow token; null when DB missing or no row. */
 export async function lookupGithubOauthAccessToken(
-  database: DatabaseHost | undefined,
+  database: DatabaseHost | PluginDatabaseHost | undefined,
   platform: string,
   platformUid: string,
 ): Promise<string | null> {

package/src/protocol.ts

@@ -7,6 +7,7 @@ import { createHmac, timingSafeEqual } from 'node:crypto';
 import type { IncomingMessage } from 'node:http';
 import { pickCredential } from '@zhin.js/adapter';
 import { isMediaRef } from '@zhin.js/core';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('github');
@@ -39,7 +40,7 @@ export { buildChannelId, parseChannelId } from './types.js';
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface GithubAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly host?: string;
   readonly app_id?: string | number;
   readonly appId?: string | number;
@@ -73,7 +74,7 @@ export interface GithubAdapterConfig {
 
 export interface ResolvedGithubConfig {
   readonly context: 'github';
-  readonly name: string;
+  readonly id: string;
   readonly host?: string;
   readonly appId?: string | number;
   readonly privateKey?: string;
@@ -100,6 +101,23 @@ export interface GithubInboundComment {
   readonly createdAt: number;
 }
 
+/**
+ * 入站归一化 → ConversationRef：Issue/PR 评论区即仓库容器内的 channel 会话，
+ * 仓库（owner/repo）进 `parent`。出站侧用 `parseChannelId(conversation.id)`
+ * 在平台边界还原 repo/type/number。
+ */
+export function githubInboundConversation(
+  endpointKey: string,
+  comment: GithubInboundComment,
+): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'channel',
+    id: comment.channelId,
+    parent: { kind: 'channel', id: comment.repo },
+  };
+}
+
 export function resolveGithubConfig(config: GithubAdapterConfig = {}): ResolvedGithubConfig {
   const entry = config.endpoints?.find((item) => item.context === 'github');
   const appIdRaw = pickCredential(
@@ -121,8 +139,8 @@ export function resolveGithubConfig(config: GithubAdapterConfig = {}): ResolvedG
       'GitHub adapter requires app_id + private_key (plugins.<key> or GITHUB_APP_ID)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.GITHUB_BOT_NAME
     || 'github-bot';
   const webhookSecret = config.webhookSecret ?? config.webhook_secret
@@ -147,7 +165,7 @@ export function resolveGithubConfig(config: GithubAdapterConfig = {}): ResolvedG
 
   return {
     context: 'github',
-    name,
+    id,
     ...(host ? { host } : {}),
     ...(appId != null ? { appId } : {}),
     ...(privateKey ? { privateKey } : {}),