@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@modesto_ma/dsh-channels",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "DeepSeek Harness (DSH) 飞书渠道插件：一个 dsh 实例对应一个飞书机器人，私聊/群聊/话题群 @ 触发会话，话题绑定 session，卡片 2.0 流式回复；Web 设置里提供「飞书渠道」状态与常用配置面板",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/modestoma/dsh_channels.git"
+  },
+  "packageManager": "pnpm@12.14.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./src/client/index.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "docs",
+    "README.md",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.client.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build:host": "tsdown --config tsdown.config.ts",
+    "build:client": "tsdown --config tsdown.client.config.ts",
+    "build": "pnpm build:host && pnpm build:client",
+    "verify:host": "node scripts/verify-host-loader.mjs",
+    "verify:client": "node scripts/verify-client-loader.mjs",
+    "prepack": "pnpm build",
+    "check": "pnpm typecheck && pnpm test && pnpm build && pnpm verify:host && pnpm verify:client"
+  },
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "feishu",
+    "lark",
+    "im-bridge",
+    "web-ui",
+    "settings-panel"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.76.0",
+    "zod": "^4.6.7"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "react": "^18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": false
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.5",
+    "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/github": "^12.0.10",
+    "@semantic-release/npm": "^13.2.0",
+    "@semantic-release/release-notes-generator": "^14.1.1",
+    "@types/node": "^26.6.5",
+    "@types/react": "~18.3.31",
+    "conventional-changelog-conventionalcommits": "10.3.0",
+    "react": "18.3.1",
+    "semantic-release": "^25.0.9",
+    "tsdown": "0.22.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}

package/src/access/cards.ts

@@ -0,0 +1,188 @@
+/**
+ * Access-control cards: the bot-added group information card, the
+ * administrator's authorization request cards, and their terminal state.
+ *
+ * The request cards carry an opaque token in the button callback value; the
+ * token is resolved server-side against the durable request table, so a card
+ * can never grant anything by itself (see `docs/access-control-design.md`
+ * §5.7/§5.8).
+ *
+ * @module dsh-channels/access/cards
+ */
+
+import { columnSet, divider, markdown, note, standaloneCard, textButton } from '../cards/primitives.ts'
+
+/** Terminal status of one settled authorization request. */
+export type SettledRequestStatus = 'approved' | 'denied' | 'expired'
+
+/** Inputs of the group-information card sent to the administrator. */
+export interface GroupInfoCardInput {
+  /** Feishu `chat_id` of the group the bot was added to (or was seen in). */
+  chatId: string
+  /** Group name, when `getChatInfo()` could read it. */
+  name?: string
+  /** Member count, when available. */
+  memberCount?: number
+  /** Group owner `open_id`, when available. */
+  ownerId?: string
+  /** `open_id` of whoever invited/triggered the bot. */
+  inviterOpenId?: string
+  /** Whether the group already passed the first admission gate. */
+  authorized: boolean
+  /** Opaque request token; only present for a *pending* group request. */
+  token?: string
+  /** Render timestamp (defaults to now). */
+  now?: number
+}
+
+/** Inputs of the user-authorization request card sent to the administrator. */
+export interface UserRequestCardInput {
+  /** `open_id` of the user asking for access. */
+  openId: string
+  /** Display name of that user, when known. */
+  name?: string
+  /** Chat the request originated from. */
+  chatId?: string
+  /** Name of the authorized group the user was seen in. */
+  groupName?: string
+  /** Display name of the requester (the inbound sender). */
+  requesterName?: string
+  /** Opaque request token. */
+  token: string
+  /** Render timestamp (defaults to now). */
+  now?: number
+}
+
+/** Inputs of the terminal replacement card. */
+export interface RequestSettledCardInput {
+  /** What kind of grant the request was about. */
+  kind: 'group' | 'user'
+  /** `chat_id` (group) or `open_id` (user) the request targeted. */
+  targetId: string
+  /** Human-readable target name, when known. */
+  targetName?: string
+  /** Settled state; pending requests never use this card. */
+  status: SettledRequestStatus
+  /** Render timestamp (defaults to now). */
+  now?: number
+}
+
+/** Truncate one display string so the card stays far below the size budget. */
+function clip(value: string, max = 120): string {
+  const trimmed = value.trim()
+  return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max)}…`
+}
+
+/** Render one epoch-ms instant as a stable UTC `YYYY-MM-DD HH:mm` string. */
+function formatTime(timestamp?: number): string {
+  const value = timestamp ?? Date.now()
+  if (!Number.isFinite(value)) return '—'
+  const date = new Date(value)
+  if (Number.isNaN(date.getTime())) return '—'
+  return `${date.toISOString().replace('T', ' ').slice(0, 16)} UTC`
+}
+
+/** Two side-by-side decision buttons carrying the opaque request token. */
+function decisionButtons(token: string, allowLabel: string, denyLabel: string): object {
+  return columnSet([
+    textButton({
+      label: allowLabel,
+      type: 'primary',
+      width: 'fill',
+      margin: '0px',
+      value: { token, action: 'allow' },
+    }),
+    textButton({
+      label: denyLabel,
+      type: 'danger',
+      width: 'fill',
+      margin: '0px',
+      value: { token, action: 'deny' },
+    }),
+  ])
+}
+
+/** `**字段**：值` line used across both request cards. */
+function field(label: string, value: string): object {
+  return markdown(`**${label}**：${value}`)
+}
+
+/**
+ * The group-information card the administrator receives when the bot joins a
+ * group (and, as a fallback, on the first denied access in an unauthorized
+ * group). Unauthorized groups with a pending request carry「授权本群 / 忽略」.
+ */
+export function buildGroupInfoCard(input: GroupInfoCardInput): object {
+  const name = input.name === undefined ? undefined : clip(input.name)
+  const elements: object[] = []
+  elements.push(field('群名', name === undefined || name === '' ? '（未知）' : name))
+  elements.push(field('群 ID', `\`${input.chatId}\``))
+  if (input.memberCount !== undefined) elements.push(field('成员数', String(input.memberCount)))
+  if (input.ownerId !== undefined && input.ownerId !== '') {
+    elements.push(field('群主', `\`${input.ownerId}\``))
+  }
+  if (input.inviterOpenId !== undefined && input.inviterOpenId !== '') {
+    elements.push(field('邀请人', `\`${input.inviterOpenId}\``))
+  }
+  elements.push(field('加入时间', formatTime(input.now)))
+  elements.push(divider())
+
+  if (!input.authorized && input.token !== undefined && input.token !== '') {
+    elements.push(note('该群尚未授权：群内目前只有管理员可以与我对话；授权后群内白名单用户也可使用。'))
+    elements.push(decisionButtons(input.token, '授权本群', '忽略'))
+  } else if (input.authorized) {
+    elements.push(note('✅ 该群已授权，群内白名单用户可正常使用（管理员不受白名单限制）。'))
+  } else {
+    elements.push(note('该群当前未授权（仅管理员可用），且没有可用的授权令牌；可在 Web 设置面板的「访问与授权」中授权。'))
+  }
+  return standaloneCard('**📋 群信息**', elements)
+}
+
+/**
+ * The user-authorization request card: an unauthorized user mentioned the bot
+ * inside an authorized group, so the administrator can grant that `open_id`
+ * from the DM card.
+ */
+export function buildUserRequestCard(input: UserRequestCardInput): object {
+  const display = clip(input.name ?? input.requesterName ?? '')
+  const groupName = input.groupName === undefined ? undefined : clip(input.groupName)
+  const elements: object[] = [
+    field('用户', display === '' ? '（未知昵称）' : display),
+    field('open_id', `\`${input.openId}\``),
+  ]
+  if (groupName !== undefined && groupName !== '') {
+    const group = input.chatId === undefined ? groupName : `${groupName}（\`${input.chatId}\`）`
+    elements.push(field('所在群', group))
+  } else if (input.chatId !== undefined && input.chatId !== '') {
+    elements.push(field('所在群', `\`${input.chatId}\``))
+  }
+  elements.push(field('申请时间', formatTime(input.now)))
+  elements.push(divider())
+  elements.push(note('授权后该用户可在所有已授权群里使用；私聊仍仅管理员可用。'))
+  elements.push(decisionButtons(input.token, '授权用户', '忽略'))
+  return standaloneCard('**🙋 用户授权申请**', elements)
+}
+
+/** Title/description pairs for the three settled states. */
+const SETTLED_PRESENTATION: Record<SettledRequestStatus, { title: string; line: string }> = {
+  approved: { title: '✅ 已授权', line: '授权已生效。' },
+  denied: { title: '❌ 已忽略', line: '本次申请已被忽略。' },
+  expired: { title: '⏱ 已过期', line: '申请超过有效期，已自动失效。' },
+}
+
+/**
+ * The terminal replacement for a request card (decision or expiry). Carries
+ * no buttons: the request token can settle exactly once.
+ */
+export function buildRequestSettledCard(input: RequestSettledCardInput): object {
+  const presentation = SETTLED_PRESENTATION[input.status]
+  const kindLabel = input.kind === 'group' ? '群' : '用户'
+  const name = input.targetName === undefined ? undefined : clip(input.targetName)
+  const target = name === undefined || name === '' ? `\`${input.targetId}\`` : `${name}（\`${input.targetId}\`）`
+  const elements: object[] = [
+    field(kindLabel, target),
+    field('处理时间', formatTime(input.now)),
+    note(presentation.line),
+  ]
+  return standaloneCard(`**${presentation.title}**`, elements)
+}

package/src/access/controller.ts

@@ -0,0 +1,201 @@
+/**
+ * Inbound admission controller.
+ *
+ * Every inbound Feishu message passes this gate *before* any side effect
+ * (Session creation, workspace, attachment archive, model call). The pure
+ * matrix lives in `policy.ts`; this module owns the user-facing behavior on
+ * denial:
+ *
+ *  - private chats: non-administrators get one fixed notice (10 s per-sender
+ *    cooldown); with no administrator configured they get the bootstrap
+ *    notice instead;
+ *  - group chats: fully silent, except that addressed denials call back into
+ *    the authorization-request lifecycle so the administrator can be asked;
+ *  - slash commands: `/userid` stays available to every private sender, the
+ *    administrator's commands always pass (including inside an unauthorized
+ *    group), everything else must pass admission.
+ *
+ * The controller never creates a Session or a workspace.
+ *
+ * @module dsh-channels/access/controller
+ */
+
+import type { FeishuConfig } from '../config.ts'
+import type { RouteRecord } from '../domain.ts'
+import type { FeishuChannel, NormalizedMessage } from '../feishu-channel.ts'
+import { decideAccess, isAdminOpenId } from './policy.ts'
+import type { AccessDecision } from './policy.ts'
+import type { AccessStore, AccessStoreSnapshot } from './store.ts'
+
+/** Fixed private-chat notice for non-administrators (no model call). */
+export const DM_DENY_TEXT = '非管理员禁用私聊功能哦～如需使用，请在管理员授权的群里 @ 我；或联系管理员把你的 open_id 加入白名单。'
+
+/** Fixed private-chat notice while no administrator is configured. */
+export const DM_UNCONFIGURED_TEXT = '机器人尚未配置管理员。发送 /userid 可查看你的 open_id，交给部署者配置后即可启用。'
+
+/** Per-sender cooldown for the repeated private-chat notice (10 s). */
+const DM_NOTICE_COOLDOWN_MS = 10_000
+
+/** Collaborators of the admission gate. */
+export interface AccessControllerDeps {
+  /** Current plugin configuration (administrator id + access mode). */
+  config(): FeishuConfig
+  /** Durable whitelists (read through the in-memory snapshot). */
+  store: AccessStore
+  /** Live channel, undefined before startup / after shutdown. */
+  channel(): FeishuChannel | undefined
+  /** Best-effort diagnostics; never rethrown. */
+  warn(message: string, ...args: unknown[]): void
+  /** Addressed message in an unauthorized group (request lifecycle hook). */
+  onDeniedGroup?(msg: NormalizedMessage): void
+  /** Addressed message from an unauthorized user in an authorized group. */
+  onDeniedUser?(msg: NormalizedMessage): void
+  /** Clock seam for tests. */
+  now?(): number
+}
+
+export class AccessController {
+  /** sender open_id → last fixed-notice delivery instant (DM spam guard). */
+  private readonly dmNoticeAt = new Map<string, number>()
+
+  constructor(private readonly deps: AccessControllerDeps) {}
+
+  private config(): FeishuConfig {
+    return this.deps.config()
+  }
+
+  private now(): number {
+    return this.deps.now?.() ?? Date.now()
+  }
+
+  /** True when `openId` is exactly the configured administrator. */
+  isAdmin(openId?: string): boolean {
+    return isAdminOpenId(this.config(), openId)
+  }
+
+  /** Current whitelist snapshot used by the pure policy. */
+  snapshot(): AccessStoreSnapshot {
+    return this.deps.store.snapshot()
+  }
+
+  /** Evaluate the admission matrix for one message (pure; no side effects). */
+  decide(msg: NormalizedMessage): AccessDecision {
+    return decideAccess(
+      { chatType: msg.chatType, chatId: msg.chatId, senderId: msg.senderId },
+      this.config(),
+      this.deps.store.snapshot(),
+    )
+  }
+
+  /**
+   * Full channel-plane admission for one non-slash message. `false` means the
+   * message has been handled (denied silently or with the fixed notice) and
+   * the caller must stop before any side effect.
+   */
+  async admit(msg: NormalizedMessage): Promise<boolean> {
+    const decision = this.decide(msg)
+    if (decision.kind === 'allow') return true
+    try {
+      if (decision.reason === 'dm-non-admin') {
+        if (msg.chatType === 'p2p') await this.noticeDeniedDm(msg)
+        return false
+      }
+      if (decision.reason === 'admin-missing') {
+        // Private chats get the bootstrap instructions; groups stay silent.
+        // Goes through the same per-sender cooldown as the regular notice so a
+        // single sender cannot make the bot answer every message while the
+        // deployment is unconfigured.
+        if (msg.chatType === 'p2p') await this.noticeDeniedDm(msg)
+        return false
+      }
+      // Group denials are silent. Only messages actually addressed to the bot
+      // may trigger the (administrator-facing) authorization request.
+      if (msg.chatType === 'group' && addressedToBot(msg)) {
+        if (decision.reason === 'group-not-authorized') this.deps.onDeniedGroup?.(msg)
+        else if (decision.reason === 'user-not-authorized') this.deps.onDeniedUser?.(msg)
+      }
+    } catch (error) {
+      this.deps.warn('dsh-channels: admission side effect failed: %s', String(error))
+    }
+    return false
+  }
+
+  /**
+   * Slash-command admission. Runs before any command card/topic/Session side
+   * effect. `open` mode keeps the legacy behavior; otherwise private chats
+   * stay administrator-only (with `/userid` as the bootstrap exception) and
+   * group chats must pass the full admission matrix; the administrator is
+   * never constrained by the whitelists, so all of their commands pass even
+   * inside an unauthorized group (`/auth` is the in-conversation grant
+   * entry).
+   */
+  async admitCommand(msg: NormalizedMessage, commandName: string | undefined): Promise<boolean> {
+    if (this.config().accessMode === 'open') return true
+    try {
+      if (msg.chatType === 'p2p') {
+        // `/userid` is the bootstrap entry for everyone: it only echoes the
+        // sender's own open_id and has no storage/model side effect.
+        if (commandName === 'userid') return true
+        if (this.isAdmin(msg.senderId)) return true
+        await this.noticeDeniedDm(msg)
+        return false
+      }
+      if (this.isAdmin(msg.senderId) && (commandName === 'auth' || commandName === 'groupid')) {
+        return true
+      }
+      return this.decide(msg).kind === 'allow'
+    } catch (error) {
+      this.deps.warn('dsh-channels: command admission failed: %s', String(error))
+      return false
+    }
+  }
+
+  /**
+   * Topic/route ownership: a route belongs to the sender (and chat) that
+   * created it. Used to reject foreign replies, attachments, and command
+   * execution inside someone else's topic.
+   */
+  ownsRoute(msg: NormalizedMessage, record: RouteRecord): boolean {
+    return record.senderOpenId === msg.senderId && record.chatId === msg.chatId
+  }
+
+  /** Drop in-memory notices (shutdown; durable state lives in the store). */
+  clear(): void {
+    this.dmNoticeAt.clear()
+  }
+
+  // ---- internals -------------------------------------------------------
+
+  /**
+   * Deliver the fixed private-chat notice (cooled down). While no
+   * administrator is configured the bootstrap text is used instead, so users
+   * are never pointed at an administrator that does not exist yet.
+   */
+  private async noticeDeniedDm(msg: NormalizedMessage): Promise<void> {
+    const now = this.now()
+    const last = this.dmNoticeAt.get(msg.senderId)
+    if (last !== undefined && now - last < DM_NOTICE_COOLDOWN_MS) return
+    this.dmNoticeAt.set(msg.senderId, now)
+    const text = this.config().adminOpenId === undefined ? DM_UNCONFIGURED_TEXT : DM_DENY_TEXT
+    await this.sendText(msg.chatId, text, msg.messageId)
+  }
+
+  /** Best-effort fixed-text send; unavailable channel/failures only warn. */
+  private async sendText(chatId: string, text: string, replyTo?: string): Promise<void> {
+    const channel = this.deps.channel()
+    if (channel === undefined) {
+      this.deps.warn('dsh-channels: channel unavailable; admission notice not delivered')
+      return
+    }
+    try {
+      await channel.send(chatId, { text }, replyTo === undefined ? undefined : { replyTo })
+    } catch (error) {
+      this.deps.warn('dsh-channels: delivering the admission notice failed: %s', String(error))
+    }
+  }
+}
+
+/** Late-trigger condition: only messages addressed to the bot count. */
+function addressedToBot(msg: NormalizedMessage): boolean {
+  return msg.mentionedBot === true || msg.threadId !== undefined
+}

package/src/access/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Access-control barrel: one import specifier for the admission policy, the
+ * durable whitelist/request store, the admission controller, the request
+ * lifecycle, and the authorization cards.
+ *
+ * @module dsh-channels/access
+ */
+
+export * from './policy.ts'
+export * from './store.ts'
+export * from './controller.ts'
+export * from './requests.ts'
+export * from './cards.ts'

package/src/access/policy.ts

@@ -0,0 +1,103 @@
+/**
+ * Pure admission policy for inbound Feishu traffic.
+ *
+ * The policy deliberately has no I/O: it takes one normalized subject, the
+ * relevant configuration slice, and a snapshot of the durable authorization
+ * tables, and returns an allow/deny decision. The controller turns a denial
+ * into the user-facing behavior (fixed private-chat notice, silent drop,
+ * authorization request card), which keeps the security-critical matrix
+ * cheap to unit test.
+ *
+ * Access model:
+ *  - the administrator may start/continue a conversation in any private chat
+ *    or any group, regardless of the whitelists;
+ *  - private chats: non-administrators are refused;
+ *  - group chats: non-administrators need the group to be authorized AND
+ *    their open_id to be on the global user whitelist.
+ *
+ * @module dsh-channels/access/policy
+ */
+
+import type { FeishuConfig } from '../config.ts'
+
+/** Chat kinds this policy decides about (matches the channel normalizer). */
+export type AccessChatType = 'p2p' | 'group'
+
+/** The security-relevant facts of one inbound message. */
+export interface AccessSubject {
+  chatType: AccessChatType
+  chatId: string
+  senderId: string
+}
+
+/** Read-only view of the durable authorization tables. */
+export interface AccessSnapshot {
+  /** Authorized group `chat_id`s. */
+  groups: ReadonlySet<string>
+  /** Authorized user `open_id`s (global, across authorized groups). */
+  users: ReadonlySet<string>
+}
+
+/** Why access was denied; drives the controller's response. */
+export type AccessDenyReason =
+  | 'admin-missing'
+  | 'dm-non-admin'
+  | 'group-not-authorized'
+  | 'user-not-authorized'
+
+/** Result of evaluating one inbound message. */
+export type AccessDecision =
+  | { readonly kind: 'allow'; readonly reason: 'open' | 'admin' | 'authorized-user' }
+  | {
+    readonly kind: 'deny'
+    readonly reason: AccessDenyReason
+    /** Which authorization request a denial may trigger, when applicable. */
+    readonly request?: 'group' | 'user'
+  }
+
+/** The configuration slice admission reads (allows easy fakes in tests). */
+export type AccessPolicyConfig = Pick<FeishuConfig, 'accessMode' | 'adminOpenId'>
+
+/** True when `openId` is exactly the configured administrator. */
+export function isAdminOpenId(
+  config: Pick<FeishuConfig, 'adminOpenId'>,
+  openId: string | undefined,
+): boolean {
+  const admin = config.adminOpenId?.trim()
+  if (admin === undefined || admin === '') return false
+  return openId !== undefined && openId.trim() === admin
+}
+
+/**
+ * Evaluate the admission matrix for one message.
+ *
+ * `open` mode reproduces the legacy behavior (the SDK's app-availability scope
+ * is then the only boundary) and exists for debugging/compatibility only.
+ */
+export function decideAccess(
+  subject: AccessSubject,
+  config: AccessPolicyConfig,
+  snapshot: AccessSnapshot,
+): AccessDecision {
+  if (config.accessMode === 'open') return { kind: 'allow', reason: 'open' }
+
+  const admin = config.adminOpenId?.trim()
+  if (admin === undefined || admin === '') return { kind: 'deny', reason: 'admin-missing' }
+
+  // The administrator is never constrained by the whitelists: they may start
+  // a conversation in any private chat or any group, even one that has not
+  // been authorized yet. The group/user gates only restrict non-admins.
+  if (subject.senderId.trim() === admin) return { kind: 'allow', reason: 'admin' }
+
+  if (subject.chatType === 'p2p') {
+    return { kind: 'deny', reason: 'dm-non-admin' }
+  }
+
+  // Non-admin group access needs both gates: the group must be authorized and
+  // the sender must be on the global user whitelist.
+  if (!snapshot.groups.has(subject.chatId)) {
+    return { kind: 'deny', reason: 'group-not-authorized', request: 'group' }
+  }
+  if (snapshot.users.has(subject.senderId)) return { kind: 'allow', reason: 'authorized-user' }
+  return { kind: 'deny', reason: 'user-not-authorized', request: 'user' }
+}