@zhin.js/adapter-github 3.0.2 → 4.0.0

package/lib/{src/github-tool-handlers.js → github-tool-handlers.js}

@@ -1,15 +1,22 @@
-import { formatCompact } from 'zhin.js';
+import { formatCompact } from '@zhin.js/logger';
 import { getCurrentCommMessage } from '@zhin.js/agent/security';
 import { GhClient } from './gh-client.js';
 import { getAdapter, getGithubAgentDeps } from './github-agent-deps.js';
 function oauthModel() {
-    const db = getGithubAgentDeps().plugin.root?.inject('database');
+    const db = getGithubAgentDeps().getDatabase?.();
     return db?.models?.get('github_oauth_users');
 }
 function subscriptionsModel() {
-    const db = getGithubAgentDeps().plugin.root?.inject('database');
+    const db = getGithubAgentDeps().getDatabase?.();
     return db?.models?.get('github_subscriptions');
 }
+function depsLogger() {
+    return getGithubAgentDeps().logger ?? {
+        debug: (...args) => console.debug(...args),
+        warn: (...args) => console.warn(...args),
+        error: (...args) => console.error(...args),
+    };
+}
 export async function executeGithubStar(args, commMessage) {
     const adapter = getAdapter();
     const msg = commMessage ?? getCurrentCommMessage();
@@ -35,7 +42,7 @@ export async function executeGithubStar(args, commMessage) {
 }
 export async function executeGithubBind(_args, commMessage) {
     const adapter = getAdapter();
-    const { plugin } = getGithubAgentDeps();
+    const log = depsLogger();
     const msg = commMessage ?? getCurrentCommMessage();
     if (!msg?.$adapter || !msg?.$sender?.id)
         return '❌ 无法获取当前用户信息';
@@ -63,7 +70,7 @@ export async function executeGithubBind(_args, commMessage) {
         ].join('\n');
         tokenPromise.then(async (tokenData) => {
             if (!tokenData) {
-                plugin.logger.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.$adapter, sender: msg.$sender.id }));
+                log.warn(formatCompact({ op: 'device_flow', ok: false, platform: msg.$adapter, sender: msg.$sender.id }));
                 return;
             }
             const userGh = new GhClient({ host, token: tokenData.access_token });
@@ -77,12 +84,12 @@ export async function executeGithubBind(_args, commMessage) {
                 access_token: tokenData.access_token,
                 created_at: Date.now(),
             });
-            plugin.logger.debug(formatCompact({ op: 'bind', platform: msg.$adapter, sender: msg.$sender.id, login }));
+            log.debug(formatCompact({ op: 'bind', platform: msg.$adapter, sender: msg.$sender.id, login }));
             if (msg?.$reply) {
                 await msg.$reply(`✅ GitHub 账号绑定成功！\n👤 ${login}`);
             }
         }).catch((err) => {
-            plugin.logger.error('GitHub Device Flow 错误:', err);
+            log.error('GitHub Device Flow 错误:', err);
         });
         return replyMsg;
     }
@@ -212,4 +219,3 @@ export async function executeGithubSubscriptions(_args, commMessage) {
             return `  📦 ${s.repo}\n     📡 ${events.join(', ') || '(无事件)'}`;
         }).join('\n\n');
 }
-//# sourceMappingURL=github-tool-handlers.js.map

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+export { buildChannelId, enrichInboundContent, formatInboundContent, formatNotification, formatOutboundBody, normalizeWebhookPath, parseChannelId, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, resolveGithubConfig, shouldAutoReplyRepo, verifyWebhookSignature, type GithubAdapterConfig, type GithubInboundComment, type GithubWireSegment, type ResolvedGithubConfig, } from './protocol.js';
+export * from './types.js';
+export { getAdapter, getGithubAgentDeps, registerGithubAgentEndpoint, setGithubAgentDeps, type GithubAgentDeps, type GithubAgentEndpoint, } from './github-agent-deps.js';
+export { GhClient } from './gh-client.js';
+export { WorkspaceManager } from './workspace-manager.js';
+export { parseMessageChannel, issueBranchName, resolveWorkspaceBranch, formatChannelContext, } from './github-channel-context.js';
+export { GithubEndpoint, defaultCreateClient, type GithubEndpointOptions, } from './endpoint.js';
+export { GITHUB_OAUTH_USERS_TABLE, GITHUB_OAUTH_USERS_SCHEMA, defineGithubOauthUsersTable, lookupGithubOauthAccessToken, } from './oauth-users.js';
+export { registerGithubWebhookRoutes, handleGithubWebhookRequest, dispatchGithubWebhookPayload, type GithubWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -0,0 +1,9 @@
+export { buildChannelId, enrichInboundContent, formatInboundContent, formatNotification, formatOutboundBody, normalizeWebhookPath, parseChannelId, parseIssueCommentInbound, parsePrReviewCommentInbound, parsePrReviewInbound, resolveGithubConfig, shouldAutoReplyRepo, verifyWebhookSignature, } from './protocol.js';
+export * from './types.js';
+export { getAdapter, getGithubAgentDeps, registerGithubAgentEndpoint, setGithubAgentDeps, } from './github-agent-deps.js';
+export { GhClient } from './gh-client.js';
+export { WorkspaceManager } from './workspace-manager.js';
+export { parseMessageChannel, issueBranchName, resolveWorkspaceBranch, formatChannelContext, } from './github-channel-context.js';
+export { GithubEndpoint, defaultCreateClient, } from './endpoint.js';
+export { GITHUB_OAUTH_USERS_TABLE, GITHUB_OAUTH_USERS_SCHEMA, defineGithubOauthUsersTable, lookupGithubOauthAccessToken, } from './oauth-users.js';
+export { registerGithubWebhookRoutes, handleGithubWebhookRequest, dispatchGithubWebhookPayload, } from './webhook.js';

package/lib/oauth-users.d.ts

@@ -0,0 +1,33 @@
+import type { DatabaseHost } from '@zhin.js/plugin-runtime';
+export declare const GITHUB_OAUTH_USERS_TABLE = "github_oauth_users";
+export declare const GITHUB_OAUTH_USERS_SCHEMA: {
+    readonly id: {
+        readonly type: "integer";
+        readonly primary: true;
+    };
+    readonly platform: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly platform_uid: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly github_login: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly access_token: {
+        readonly type: "text";
+        readonly nullable: false;
+    };
+    readonly created_at: {
+        readonly type: "integer";
+        readonly nullable: false;
+    };
+};
+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>;

package/lib/oauth-users.js

@@ -0,0 +1,38 @@
+/**
+ * github_oauth_users — SSOT for Runtime user-token binding (gh bind / Endpoint lookup).
+ */
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('github');
+export const GITHUB_OAUTH_USERS_TABLE = 'github_oauth_users';
+export const GITHUB_OAUTH_USERS_SCHEMA = {
+    id: { type: 'integer', primary: true },
+    platform: { type: 'text', nullable: false },
+    platform_uid: { type: 'text', nullable: false },
+    github_login: { type: 'text', nullable: false },
+    access_token: { type: 'text', nullable: false },
+    created_at: { type: 'integer', nullable: false },
+};
+export function defineGithubOauthUsersTable(host) {
+    host.define(GITHUB_OAUTH_USERS_TABLE, { ...GITHUB_OAUTH_USERS_SCHEMA });
+}
+/** Resolve a stored PAT/device-flow token; null when DB missing or no row. */
+export async function lookupGithubOauthAccessToken(database, platform, platformUid) {
+    if (!database?.started)
+        return null;
+    const model = database.models.get(GITHUB_OAUTH_USERS_TABLE);
+    if (!model)
+        return null;
+    try {
+        const rows = await model.select().where({ platform, platform_uid: platformUid });
+        const token = rows[0]?.access_token;
+        return typeof token === 'string' && token.trim() ? token : null;
+    }
+    catch (error) {
+        logger.debug(formatCompact({
+            op: 'oauth_lookup_fail',
+            platform,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+        return null;
+    }
+}

package/lib/protocol.d.ts

@@ -0,0 +1,87 @@
+/**
+ * GitHub webhook / comment helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import type { IncomingMessage } from 'node:http';
+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 host?: string;
+    readonly app_id?: string | number;
+    readonly appId?: string | number;
+    readonly private_key?: string;
+    readonly privateKey?: string;
+    readonly webhook_secret?: string;
+    readonly webhookSecret?: string;
+    readonly webhook_path?: string;
+    readonly webhookPath?: string;
+    readonly poll_interval?: number;
+    readonly pollInterval?: number;
+    readonly auto_reply_repos?: readonly string[];
+    readonly autoReplyRepos?: readonly string[];
+    readonly bot_login?: string;
+    readonly botLogin?: string;
+    readonly workspace_root?: string;
+    readonly workspaceRoot?: string;
+    /** Transitional: legacy root `endpoints[]` with `context: github`. */
+    readonly endpoints?: ReadonlyArray<Partial<ResolvedGithubConfig> & {
+        readonly context?: string;
+        readonly app_id?: string | number;
+        readonly private_key?: string;
+        readonly webhook_secret?: string;
+        readonly webhook_path?: string;
+        readonly poll_interval?: number;
+        readonly auto_reply_repos?: readonly string[];
+        readonly bot_login?: string;
+        readonly workspace_root?: string;
+    }>;
+}
+export interface ResolvedGithubConfig {
+    readonly context: 'github';
+    readonly name: string;
+    readonly host?: string;
+    readonly appId?: string | number;
+    readonly privateKey?: string;
+    readonly webhookSecret?: string;
+    readonly webhookPath: string;
+    readonly pollInterval: number;
+    readonly autoReplyRepos: readonly string[];
+    readonly botLogin?: string;
+    readonly workspaceRoot?: string;
+}
+export interface GithubWireSegment {
+    readonly type: string;
+    readonly data?: Record<string, unknown>;
+}
+export interface GithubInboundComment {
+    readonly id: string;
+    readonly channelId: string;
+    readonly sender: string;
+    readonly content: string;
+    readonly repo: string;
+    readonly kind: 'issue_comment' | 'pr_review_comment' | 'pr_review';
+    readonly createdAt: number;
+}
+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;
+/** Prepend synthetic @bot for auto_reply repos (gateway text path). */
+export declare function enrichInboundContent(content: string, config: Pick<ResolvedGithubConfig, 'autoReplyRepos' | 'botLogin'>, botLogin: string | undefined, repo: string): string;
+/** Build inbound text for MessageGateway.receive from markdown/comment body. */
+export declare function formatInboundContent(body: string): string;
+/** Build markdown body for Issue/PR comment send. */
+export declare function formatOutboundBody(payload: unknown): string;
+export declare function verifyWebhookSignature(secret: string, rawBody: string, signatureHeader: string | undefined): boolean;
+export declare function headerValue(headers: IncomingMessage['headers'], name: string): string;
+export declare function readTextBody(request: IncomingMessage, options?: {
+    readonly limit?: number;
+}): Promise<string>;
+export declare function parseIssueCommentInbound(payload: IssueCommentPayload): GithubInboundComment | null;
+export declare function parsePrReviewCommentInbound(payload: PRReviewCommentPayload): GithubInboundComment | null;
+export declare function parsePrReviewInbound(payload: PRReviewPayload): GithubInboundComment | null;
+export declare function formatNotification(event: string, p: GenericWebhookPayload): string;
+/** Parse @mentions in markdown into a flat display string (gateway text path). */
+export declare function parseMarkdownMentions(md: string): string;

package/lib/protocol.js

@@ -0,0 +1,241 @@
+/**
+ * GitHub webhook / comment helpers — no legacy Adapter/Endpoint / segment-mapper.
+ * Canonicalization is owned by gateway/core before endpoint.send.
+ */
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { pickCredential } from '@zhin.js/adapter';
+import { buildChannelId, } from './types.js';
+export { buildChannelId, parseChannelId } from './types.js';
+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);
+    const appId = appIdRaw ? (Number(appIdRaw) || appIdRaw) : undefined;
+    const privateKey = pickCredential(config.privateKey, config.private_key, entry?.privateKey, entry?.private_key) || undefined;
+    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)
+        || process.env.GITHUB_BOT_NAME
+        || 'github-bot';
+    const webhookSecret = config.webhookSecret ?? config.webhook_secret
+        ?? entry?.webhookSecret ?? entry?.webhook_secret
+        ?? process.env.GITHUB_WEBHOOK_SECRET
+        ?? undefined;
+    const host = config.host ?? entry?.host;
+    const webhookPath = normalizeWebhookPath(config.webhookPath ?? config.webhook_path ?? entry?.webhookPath ?? entry?.webhook_path
+        ?? '/github/webhook');
+    const pollInterval = Number(config.pollInterval ?? config.poll_interval ?? entry?.pollInterval ?? entry?.poll_interval ?? 60) || 60;
+    const autoReplyRepos = [
+        ...(config.autoReplyRepos ?? config.auto_reply_repos
+            ?? entry?.autoReplyRepos ?? entry?.auto_reply_repos ?? []),
+    ];
+    const botLogin = config.botLogin ?? config.bot_login ?? entry?.botLogin ?? entry?.bot_login;
+    const workspaceRoot = config.workspaceRoot ?? config.workspace_root
+        ?? entry?.workspaceRoot ?? entry?.workspace_root;
+    return {
+        context: 'github',
+        name,
+        ...(host ? { host } : {}),
+        ...(appId != null ? { appId } : {}),
+        ...(privateKey ? { privateKey } : {}),
+        ...(webhookSecret ? { webhookSecret } : {}),
+        webhookPath,
+        pollInterval,
+        autoReplyRepos,
+        ...(botLogin ? { botLogin } : {}),
+        ...(workspaceRoot ? { workspaceRoot } : {}),
+    };
+}
+export function normalizeWebhookPath(path) {
+    const trimmed = path.trim() || '/github/webhook';
+    return trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+}
+export function shouldAutoReplyRepo(config, repo) {
+    const list = config.autoReplyRepos;
+    if (!list.length)
+        return false;
+    const key = repo.toLowerCase();
+    return list.some((r) => r.toLowerCase() === key);
+}
+/** Prepend synthetic @bot for auto_reply repos (gateway text path). */
+export function enrichInboundContent(content, config, botLogin, repo) {
+    const login = config.botLogin || botLogin;
+    if (!login || !shouldAutoReplyRepo(config, repo))
+        return content;
+    if (content.includes(`@${login}`))
+        return content;
+    return `@${login} ${content}`;
+}
+/** Build inbound text for MessageGateway.receive from markdown/comment body. */
+export function formatInboundContent(body) {
+    return body;
+}
+/** Build markdown body for Issue/PR comment send. */
+export function formatOutboundBody(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    if (payload == null)
+        return '';
+    if (!Array.isArray(payload)) {
+        if (typeof payload === 'object' && payload !== null && 'text' in payload) {
+            return String(payload.text ?? '');
+        }
+        return String(payload);
+    }
+    return payload.map((seg) => {
+        if (typeof seg === 'string')
+            return seg;
+        const item = seg;
+        switch (item.type) {
+            case 'text':
+                return String(item.data?.text ?? '');
+            case 'mention':
+            case 'at':
+                return `@${item.data?.name || item.data?.id || item.data?.target || ''}`;
+            case 'image':
+                return item.data?.url ? `![image](${item.data.url})` : '[image]';
+            case 'link':
+                return `[${item.data?.text || item.data?.url || ''}](${item.data?.url || ''})`;
+            default:
+                return String(item.data?.text ?? `[${item.type}]`);
+        }
+    }).join('');
+}
+export function verifyWebhookSignature(secret, rawBody, signatureHeader) {
+    if (!signatureHeader?.startsWith('sha256='))
+        return false;
+    const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
+    try {
+        const a = Buffer.from(signatureHeader);
+        const b = Buffer.from(expected);
+        if (a.length !== b.length)
+            return false;
+        return timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    }
+}
+export function headerValue(headers, name) {
+    const raw = headers[name] ?? headers[name.toLowerCase()];
+    if (Array.isArray(raw))
+        return raw[0] ?? '';
+    return raw ?? '';
+}
+export async function readTextBody(request, options = {}) {
+    const limit = options.limit ?? 1_048_576;
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > limit) {
+            request.destroy();
+            throw new Error(`Request body exceeds ${limit} bytes`);
+        }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function parseIssueCommentInbound(payload) {
+    if (payload.action !== 'created' || !payload.comment)
+        return null;
+    const repo = payload.repository.full_name;
+    const isPR = 'pull_request' in payload.issue;
+    return {
+        id: String(payload.comment.id),
+        channelId: buildChannelId(repo, isPR ? 'pr' : 'issue', payload.issue.number),
+        sender: payload.sender.login,
+        content: payload.comment.body,
+        repo,
+        kind: 'issue_comment',
+        createdAt: new Date(payload.comment.created_at).getTime(),
+    };
+}
+export function parsePrReviewCommentInbound(payload) {
+    if (payload.action !== 'created' || !payload.comment)
+        return null;
+    const repo = payload.repository.full_name;
+    const body = payload.comment.path
+        ? `**${payload.comment.path}**\n${payload.comment.diff_hunk ? `\`\`\`diff\n${payload.comment.diff_hunk}\n\`\`\`\n` : ''}${payload.comment.body}`
+        : payload.comment.body;
+    return {
+        id: String(payload.comment.id),
+        channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+        sender: payload.sender.login,
+        content: body,
+        repo,
+        kind: 'pr_review_comment',
+        createdAt: new Date(payload.comment.created_at).getTime(),
+    };
+}
+export function parsePrReviewInbound(payload) {
+    if (payload.action !== 'submitted' || !payload.review.body)
+        return null;
+    const repo = payload.repository.full_name;
+    const stateLabel = {
+        approved: '✅ APPROVED',
+        changes_requested: '🔄 CHANGES REQUESTED',
+        commented: '💬 COMMENTED',
+        dismissed: '❌ DISMISSED',
+    };
+    const body = `**[${stateLabel[payload.review.state] || payload.review.state}]**\n${payload.review.body}`;
+    return {
+        id: String(payload.review.id),
+        channelId: buildChannelId(repo, 'pr', payload.pull_request.number),
+        sender: payload.sender.login,
+        content: body,
+        repo,
+        kind: 'pr_review',
+        createdAt: new Date(payload.review.submitted_at).getTime(),
+    };
+}
+export function formatNotification(event, p) {
+    const repo = p.repository.full_name;
+    const sender = p.sender.login;
+    const repoUrl = p.repository.html_url;
+    switch (event) {
+        case 'push': {
+            const branch = p.ref?.replace('refs/heads/', '') || '?';
+            const commits = p.commits || [];
+            const compareUrl = commits.length >= 2
+                ? `${repoUrl}/compare/${commits[0].id.substring(0, 12)}...${commits[commits.length - 1].id.substring(0, 12)}`
+                : commits.length === 1 ? `${repoUrl}/commit/${commits[0].id}` : '';
+            let msg = `📦 ${repo}\n🌿 ${sender} pushed ${commits.length} commit(s) to \`${branch}\`\n`;
+            if (commits.length) {
+                msg += '\n';
+                msg += commits.slice(0, 5).map((c) => `  • [\`${c.id.substring(0, 7)}\`](${repoUrl}/commit/${c.id}) ${c.message.split('\n')[0]}`).join('\n');
+                if (commits.length > 5)
+                    msg += `\n  ... +${commits.length - 5} more`;
+            }
+            if (compareUrl)
+                msg += `\n\n🔗 ${compareUrl}`;
+            return msg;
+        }
+        case 'issues': {
+            const i = p.issue;
+            const act = p.action === 'opened' ? '📝 opened' : p.action === 'closed' ? '✅ closed' : `🔄 ${p.action || 'updated'}`;
+            return `🐛 ${repo}\n👤 ${sender} ${act} issue #${i.number}\n📌 ${i.title}\n🔗 ${i.html_url}`;
+        }
+        case 'star': {
+            const starred = p.action !== 'deleted';
+            return `${starred ? '⭐' : '💔'} ${repo}\n👤 ${sender} ${starred ? 'starred' : 'unstarred'}\n🔗 ${repoUrl}`;
+        }
+        case 'fork':
+            return `🍴 ${repo}\n👤 ${sender} forked → ${p.forkee.full_name}\n🔗 ${p.forkee.html_url}`;
+        case 'pull_request': {
+            const pr = p.pull_request;
+            const act = p.action === 'opened' ? '📝 opened'
+                : p.action === 'closed' ? (pr.state === 'closed' ? '❌ closed' : '✅ merged')
+                    : `🔄 ${p.action || 'updated'}`;
+            return `🔀 ${repo}\n👤 ${sender} ${act} PR #${pr.number}\n📌 ${pr.title}\n🌿 ${pr.head.ref} → ${pr.base.ref}\n🔗 ${pr.html_url}`;
+        }
+        default:
+            return `📬 ${repo}\n📡 ${event}${p.action ? ` (${p.action})` : ''} by ${sender}\n🔗 ${repoUrl}`;
+    }
+}
+/** Parse @mentions in markdown into a flat display string (gateway text path). */
+export function parseMarkdownMentions(md) {
+    return md;
+}

package/lib/types.d.ts

@@ -0,0 +1,149 @@
+export interface GitHubEndpointConfig {
+    context: 'github';
+    /** Endpoint 标识名称 */
+    name: string;
+    /** GitHub Enterprise 主机名（默认 github.com） */
+    host?: string;
+    /** GitHub App ID */
+    app_id?: string | number;
+    /** GitHub App 私钥（PEM 内容或文件路径） */
+    private_key?: string;
+    /** Webhook Secret（配置后启用 Webhook 接收事件，不配置则使用轮询） */
+    webhook_secret?: string;
+    /** Webhook 路由路径（默认 /github/webhook） */
+    webhook_path?: string;
+    /** 事件轮询间隔（秒，默认 60，Webhook 模式下作为降级备选） */
+    poll_interval?: number;
+    /** 这些仓库的人类 Issue/PR 评论自动触发 AI（无需 @bot） */
+    auto_reply_repos?: string[];
+    /** 覆盖 App bot 登录名（默认 {slug}[bot]） */
+    bot_login?: string;
+    /** 托管 git 工作区根目录（默认 {cwd}/data/github-workspaces） */
+    workspace_root?: string;
+}
+export interface ParsedChannel {
+    repo: string;
+    type: 'issue' | 'pr';
+    number: number;
+}
+export declare function parseChannelId(channelId: string): ParsedChannel | null;
+export declare function buildChannelId(repo: string, type: 'issue' | 'pr', number: number): string;
+export interface GitHubUser {
+    login: string;
+    id: number;
+    html_url: string;
+}
+export interface GitHubComment {
+    id: number;
+    body: string;
+    user: GitHubUser;
+    created_at: string;
+    updated_at: string;
+    html_url: string;
+}
+export interface GitHubRepo {
+    full_name: string;
+    html_url: string;
+    description?: string;
+}
+export interface GitHubIssue {
+    number: number;
+    title: string;
+    html_url: string;
+    state: string;
+    user: GitHubUser;
+}
+export interface GitHubPR {
+    number: number;
+    title: string;
+    html_url: string;
+    state: string;
+    user: GitHubUser;
+    head: {
+        ref: string;
+    };
+    base: {
+        ref: string;
+    };
+}
+export interface IssueCommentPayload {
+    action: 'created' | 'edited' | 'deleted';
+    comment: GitHubComment;
+    issue: GitHubIssue;
+    repository: GitHubRepo;
+    sender: GitHubUser;
+}
+export interface PRReviewCommentPayload {
+    action: 'created' | 'edited' | 'deleted';
+    comment: GitHubComment & {
+        diff_hunk?: string;
+        path?: string;
+    };
+    pull_request: GitHubPR;
+    repository: GitHubRepo;
+    sender: GitHubUser;
+}
+export interface PRReviewPayload {
+    action: 'submitted' | 'edited' | 'dismissed';
+    review: {
+        id: number;
+        body: string | null;
+        state: 'approved' | 'changes_requested' | 'commented' | 'dismissed';
+        user: GitHubUser;
+        html_url: string;
+        submitted_at: string;
+    };
+    pull_request: GitHubPR;
+    repository: GitHubRepo;
+    sender: GitHubUser;
+}
+export interface GenericWebhookPayload {
+    action?: string;
+    repository: GitHubRepo;
+    sender: GitHubUser;
+    ref?: string;
+    commits?: Array<{
+        id: string;
+        message: string;
+        author: {
+            name: string;
+            username?: string;
+        };
+        url: string;
+    }>;
+    issue?: GitHubIssue;
+    pull_request?: GitHubPR;
+    forkee?: {
+        full_name: string;
+        html_url: string;
+        owner: {
+            login: string;
+        };
+    };
+}
+export type EventType = 'push' | 'issue' | 'star' | 'fork' | 'unstar' | 'pull_request';
+export interface Subscription {
+    id: number;
+    repo: string;
+    events: EventType[];
+    target_id: string;
+    target_type: 'private' | 'group' | 'channel';
+    adapter: string;
+    endpoint: string;
+}
+export type PrAction = 'list' | 'view' | 'diff' | 'merge' | 'create' | 'review' | 'close';
+export type IssueAction = 'list' | 'view' | 'create' | 'close' | 'comment';
+export type RepoAction = 'info' | 'branches' | 'releases' | 'runs' | 'stars';
+export interface GitHubOAuthUser {
+    id: number;
+    /** 来源平台 (icqq, kook, discord …) */
+    platform: string;
+    /** 该平台上的用户 ID */
+    platform_uid: string;
+    /** GitHub 用户名 */
+    github_login: string;
+    /** OAuth Access Token */
+    access_token: string;
+    /** 绑定时间 (ms) */
+    created_at: number;
+}

package/lib/{src/types.js → types.js}

@@ -13,4 +13,3 @@ export function parseChannelId(channelId) {
 export function buildChannelId(repo, type, number) {
     return type === 'issue' ? `${repo}/issues/${number}` : `${repo}/pull/${number}`;
 }
-//# sourceMappingURL=types.js.map

package/lib/webhook.d.ts

@@ -0,0 +1,13 @@
+/**
+ * GitHub webhook HTTP: verify → parse → admit inbound comments.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { HttpHost, HttpRouteRegistration } from '@zhin.js/host-http';
+import { type GithubInboundComment, type ResolvedGithubConfig } from './protocol.js';
+export interface GithubWebhookHandler {
+    readonly config: ResolvedGithubConfig;
+    admit(comment: GithubInboundComment): void;
+}
+export declare function registerGithubWebhookRoutes(http: HttpHost, handler: GithubWebhookHandler): HttpRouteRegistration[];
+export declare function handleGithubWebhookRequest(request: IncomingMessage, response: ServerResponse, handler: GithubWebhookHandler): Promise<void>;
+export declare function dispatchGithubWebhookPayload(event: string, payload: unknown, handler: GithubWebhookHandler): Promise<void>;