@modesto_ma/dsh-channels 0.5.0-beta.2 → 0.5.0-beta.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modesto_ma/dsh-channels",
-  "version": "0.5.0-beta.2",
+  "version": "0.5.0-beta.4",
   "description": "DeepSeek Harness (DSH) 飞书渠道插件：一个 dsh 实例对应一个飞书机器人，私聊/群聊/话题群 @ 触发会话，话题绑定 session，卡片 2.0 流式回复；Web 设置里提供「飞书渠道」状态与常用配置面板",
   "repository": {
     "type": "git",

package/src/access/controller.ts

@@ -156,7 +156,38 @@ export class AccessController {
    * execution inside someone else's topic.
    */
   ownsRoute(msg: NormalizedMessage, record: RouteRecord): boolean {
-    return record.senderUserId === msg.senderId && record.chatId === msg.chatId
+    return this.mayActOnRoute(msg.senderId, msg.chatId, record)
+  }
+
+  /**
+   * Whether `userId`, acting in `chatId`, may continue or decide for the
+   * route's Session: the route owner, or, on a group-shared route
+   * (`record.shared`), any user the admission matrix allows in that chat.
+   * @param userId - Feishu user_id of the actor.
+   * @param chatId - chat the action comes from (must be the route's chat).
+   * @param record - the route acted on.
+   * @returns true when the action is allowed.
+   */
+  mayActOnRoute(userId: string | undefined, chatId: string, record: RouteRecord): boolean {
+    if (userId === undefined || record.chatId !== chatId) return false
+    if (record.senderUserId === userId) return true
+    if (record.shared !== true) return false
+    return decideAccess(
+      { chatType: record.chatType, chatId, senderId: userId },
+      this.config(),
+      this.deps.store.snapshot(),
+    ).kind === 'allow'
+  }
+
+  /**
+   * Whether the analyze API may post into `chatId`: an authorized group, or
+   * any group in `open` access mode.
+   * @param chatId - target group chat id.
+   * @returns true when the chat is a permitted target.
+   */
+  mayAnalyzeIn(chatId: string): boolean {
+    if (this.config().accessMode === 'open') return true
+    return this.deps.store.snapshot().groups.has(chatId)
   }
 
   /** Drop in-memory notices (shutdown; durable state lives in the store). */

package/src/analyze/contract.ts

@@ -0,0 +1,121 @@
+/**
+ * Wire contract of the log-platform analyze API.
+ *
+ * `POST /dsh-channels/analyze` on the dedicated `analyzeListen` port, with
+ * `Authorization: Bearer <token>`, an `Idempotency-Key` header, and a JSON
+ * body naming the requester, the trigger time, the subject (application +
+ * error code), the log-platform detail pages, the target group, and the
+ * prompt. A valid request posts the analysis root card into the group and
+ * answers `202`; the analysis then streams in a topic below that card. Log
+ * packages are the prompt's business: the analysis skill fetches whatever the
+ * prompt names, and the detail pages are only listed on the card.
+ *
+ * @module dsh-channels/analyze/contract
+ */
+
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { FEISHU_USER_ID_PATTERN } from '../domain.ts'
+
+/** The only path the analyze listener serves. */
+export const ANALYZE_ROUTE = '/dsh-channels/analyze'
+
+/** Largest accepted request body (the prompt dominates it). */
+export const ANALYZE_MAX_BODY_BYTES = 1024 * 1024
+
+/** Largest accepted prompt, in characters. */
+export const ANALYZE_MAX_PROMPT_CHARS = 100_000
+
+/**
+ * `Idempotency-Key` format: 1–200 visible ASCII characters without spaces, so
+ * a platform can use a UUID or its own `type:id` token.
+ */
+export const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,200}$/u
+
+/**
+ * Application / error-code segment: it names a workspace directory
+ * (`<baseDir>/analyze/<app>/<errorCode>`), so only path-safe characters pass.
+ */
+const SUBJECT_SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/u
+
+/** Most detail pages one request may list on its root card. */
+export const ANALYZE_MAX_LOG_DETAILS = 50
+
+/** Feishu group chat id (`oc_…`). */
+const CHAT_ID = /^oc_[A-Za-z0-9_-]{1,128}$/u
+
+/** JSON body of one analyze request. */
+export const analyzeRequestSchema = z.object({
+  /** Feishu user_id of the person who started the analysis on the platform. */
+  requesterUserId: z.string().regex(FEISHU_USER_ID_PATTERN, 'must be a Feishu user_id').max(128),
+  /** When the analysis was started on the platform, shown verbatim on the root card. */
+  triggeredAt: z.string().min(1).max(64).refine(value => value.trim() !== '', 'must not be blank'),
+  /** Application the logs belong to (workspace directory segment). */
+  app: z.string().regex(SUBJECT_SEGMENT, 'must be 1-128 of A-Z a-z 0-9 . _ -'),
+  /** Error code of the logs (workspace directory segment). */
+  errorCode: z.string().regex(SUBJECT_SEGMENT, 'must be 1-128 of A-Z a-z 0-9 . _ -'),
+  /** Log-platform detail pages of the logs that triggered the analysis (listed on the root card). */
+  logDetails: z.array(z.object({
+    /** Row label. */
+    name: z.string().min(1).max(200).refine(value => value.trim() !== '', 'must not be blank'),
+    /** Detail page address. */
+    url: z.url({ protocol: /^https?$/u, error: 'must be an http(s) URL' }).max(2048),
+  }).strict()).min(1).max(ANALYZE_MAX_LOG_DETAILS),
+  /** Target group chat (`oc_…`); must be an authorized group. */
+  chatId: z.string().regex(CHAT_ID, 'must be a Feishu group chat_id (oc_...)'),
+  /** Prompt forwarded verbatim as the analysis Session's first user message. */
+  prompt: z.string().min(1).max(ANALYZE_MAX_PROMPT_CHARS)
+    .refine(value => value.trim() !== '', 'must not be blank'),
+}).strict()
+
+export type AnalyzeRequest = z.infer<typeof analyzeRequestSchema>
+
+/** Body of an accepted (or replayed) request. */
+export interface AnalyzeAccepted {
+  readonly ok: true
+  /** Target group chat id. */
+  readonly chatId: string
+  /** Root card message id; the analysis topic hangs below it. */
+  readonly messageId: string
+}
+
+/** Body of a refused request. */
+export interface AnalyzeRefused {
+  readonly ok: false
+  /** Readable reason (Chinese, shown to platform operators). */
+  readonly error: string
+}
+
+/** One HTTP answer of the analyze handler. */
+export interface AnalyzeResponse {
+  readonly status: number
+  readonly body: AnalyzeAccepted | AnalyzeRefused
+}
+
+/**
+ * Fingerprint of one validated request, used to tell a retry of the same
+ * request from a reused `Idempotency-Key`. Field order is fixed.
+ * @param request - the validated request.
+ * @returns SHA-256 hex digest.
+ */
+export function analyzeRequestHash(request: AnalyzeRequest): string {
+  const canonical = JSON.stringify([
+    request.requesterUserId, request.triggeredAt, request.app, request.errorCode,
+    request.logDetails.map(detail => [detail.name, detail.url]), request.chatId, request.prompt,
+  ])
+  return createHash('sha256').update(canonical).digest('hex')
+}
+
+/**
+ * Validate one decoded JSON body.
+ * @param raw - the decoded body.
+ * @returns the request, or a readable list of field errors.
+ */
+export function parseAnalyzeRequest(raw: unknown): { ok: true; value: AnalyzeRequest } | { ok: false; error: string } {
+  const parsed = analyzeRequestSchema.safeParse(raw)
+  if (parsed.success) return { ok: true, value: parsed.data }
+  const details = parsed.error.issues
+    .map(issue => `${issue.path.join('.') || '(body)'}: ${issue.message}`)
+    .join('; ')
+  return { ok: false, error: `请求参数不合法：${details}` }
+}

package/src/analyze/launcher.ts

@@ -0,0 +1,353 @@
+/**
+ * Log-platform analysis launcher: the business side of the analyze API.
+ *
+ * Synchronously (before the `202`): service state, target-group permission,
+ * `Idempotency-Key` replay, and the root card (分析中). In the background: the
+ * topic (opened by the first streaming card, replied in thread below the root
+ * card), the `<baseDir>/analyze/<app>/<errorCode>` workspace and its per-topic
+ * directory, the Session, the group-shared route, and the first turn: the
+ * platform prompt verbatim, streamed into that card like any topic turn. When
+ * the first turn settles, the root card's status follows it (已完成 / 已停止 /
+ * 失败), and the request record keeps the same status. At channel start,
+ * records still `running` belong to analyses a previous instance never
+ * finished; {@link AnalyzeLauncher.markInterrupted} marks their cards 已中断.
+ * Log packages are fetched by the analysis skill the prompt invokes.
+ *
+ * The topic is reserved in the inbound router from its creation until the
+ * route and the first prompt are published, so replies posted meanwhile queue
+ * behind the first turn. Follow-ups then use the ordinary topic routing: the
+ * route is `shared`, so every member admitted in the group may continue it. A
+ * failure before the first turn (including a disconnect meanwhile) marks the
+ * root card failed with the reason, closes the streaming card, and leaves no
+ * route.
+ *
+ * @module dsh-channels/analyze/launcher
+ */
+
+import { randomUUID } from 'node:crypto'
+import type { AgentHandle, HostContext, SessionId } from '../dsh-types.ts'
+import type { FeishuConfig } from '../config.ts'
+import { buildAnalyzeRootCard, buildCard, initialStreamingCard } from '../cards.ts'
+import type { AnalyzeStatus, AnalyzeSubject } from '../cards.ts'
+import type { RouteOperationQueue } from '../commands.ts'
+import type { AnalyzeRequestRecord, FeishuDomainHandle, RouteRecord } from '../domain.ts'
+import type { FeishuChannel } from '../feishu-channel.ts'
+import { feishuUserMessage } from '../routing/inbound.ts'
+import { enterTopic, placementServices, planTopic } from '../session/isolation.ts'
+import type { TopicPlacement } from '../session/isolation.ts'
+import type { SessionManager } from '../session/manager.ts'
+import type { InflightRepair } from '../session/repair.ts'
+import type { RouteStore } from '../session/routes.ts'
+import type { TurnStreamer } from '../streamer.ts'
+import { ensureAnalyzeWorkspace, topicTokenFor } from '../workspaces.ts'
+import { analyzeRequestHash } from './contract.ts'
+import type { AnalyzeAccepted, AnalyzeRequest, AnalyzeResponse } from './contract.ts'
+import type { AnalyzeHandler } from './server.ts'
+
+/** Collaborators of the launcher (late-bound where the service swaps them per connection). */
+export interface AnalyzeLauncherDeps {
+  ctx: HostContext
+  config: FeishuConfig
+  started(): boolean
+  channel(): FeishuChannel | undefined
+  domain(): FeishuDomainHandle | undefined
+  routes: RouteStore
+  repair: InflightRepair
+  sessions: SessionManager
+  streamer(): TurnStreamer | undefined
+  /** Shared per-route FIFO (the first turn must precede any follow-up). */
+  queue: RouteOperationQueue
+  /**
+   * Reserve an opened topic until its route is published, so replies posted
+   * meanwhile wait instead of being dropped or starting a competing Session.
+   * The returned closer is called exactly once.
+   */
+  reserveTopic(threadId: string): () => void
+  /** Whether the analyze API may post into the group. */
+  mayAnalyzeIn(chatId: string): boolean
+  /** Resolve the configured bearer token; undefined when unresolvable. */
+  resolveToken(): Promise<string | undefined>
+}
+
+/** One accepted request still answering its `202`. */
+interface PendingAccept {
+  readonly bodyHash: string
+  readonly response: Promise<AnalyzeResponse>
+}
+
+/** Readable reason of an error value. */
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export class AnalyzeLauncher implements AnalyzeHandler {
+  /** `Idempotency-Key` → request still being accepted (concurrent retries share it). */
+  private readonly accepting = new Map<string, PendingAccept>()
+  /** Background analyses still starting (drained on shutdown). */
+  private readonly running = new Set<Promise<void>>()
+
+  constructor(private readonly deps: AnalyzeLauncherDeps) {}
+
+  async token(): Promise<string | undefined> {
+    return await this.deps.resolveToken()
+  }
+
+  async analyze(request: AnalyzeRequest, idempotencyKey: string): Promise<AnalyzeResponse> {
+    const bodyHash = analyzeRequestHash(request)
+    const pending = this.accepting.get(idempotencyKey)
+    if (pending !== undefined) {
+      if (pending.bodyHash !== bodyHash) return reusedKey()
+      return await pending.response
+    }
+    const response = this.accept(request, idempotencyKey, bodyHash)
+    this.accepting.set(idempotencyKey, { bodyHash, response })
+    try {
+      return await response
+    } finally {
+      this.accepting.delete(idempotencyKey)
+    }
+  }
+
+  /**
+   * Wait for every background analysis that is still starting. Called after
+   * `started` turns false, so each one ends on its failure card or, when its
+   * first prompt was already sent, as an ordinary topic.
+   */
+  async drain(): Promise<void> {
+    await Promise.allSettled([...this.running])
+  }
+
+  /**
+   * Mark every analysis still `running` as interrupted, on its card and in
+   * its record. Called at channel start before the listener opens, so each
+   * such record belongs to a previous instance whose first turn never
+   * settled. A card that cannot be updated (deleted, recalled) is logged and
+   * still recorded as interrupted, so it is not retried on every start.
+   */
+  async markInterrupted(): Promise<void> {
+    const channel = this.deps.channel()
+    const domain = this.deps.domain()
+    if (channel === undefined || domain === undefined) return
+    for (const [key, record] of [...domain.analyzeRequests.entries()]) {
+      if (record.status !== 'running') continue
+      await channel.updateCard(record.messageId, buildAnalyzeRootCard(record.subject, { kind: 'interrupted' }))
+        .catch((error: unknown) => {
+          this.deps.ctx.logger?.warn?.('dsh-channels: marking analysis card %s interrupted failed: %s', key, String(error))
+        })
+      await this.recordStatus(key, 'interrupted')
+    }
+  }
+
+  private async accept(request: AnalyzeRequest, key: string, bodyHash: string): Promise<AnalyzeResponse> {
+    const channel = this.deps.channel()
+    const domain = this.deps.domain()
+    if (!this.deps.started() || channel === undefined || domain === undefined) {
+      return refused(503, '飞书渠道尚未连接，请稍后重试')
+    }
+    const stored = domain.analyzeRequests.get(key)
+    if (stored !== undefined) {
+      if (stored.bodyHash !== bodyHash) return reusedKey()
+      return { status: 202, body: { ok: true, chatId: stored.chatId, messageId: stored.messageId } }
+    }
+    if (!this.deps.mayAnalyzeIn(request.chatId)) {
+      return refused(403, '目标群未授权：请管理员在该群发送 /auth group add，或在设置面板「访问与授权」中添加')
+    }
+    const subject = subjectOf(request)
+    let rootId: string
+    try {
+      rootId = (await channel.send(request.chatId, {
+        card: buildAnalyzeRootCard(subject, { kind: 'running' }),
+      })).messageId
+    } catch (error) {
+      return refused(502, `分析卡片发送失败（机器人需在目标群内）：${messageOf(error)}`)
+    }
+    const body: AnalyzeAccepted = { ok: true, chatId: request.chatId, messageId: rootId }
+    try {
+      await domain.analyzeRequests.put(key, {
+        key, bodyHash, chatId: request.chatId, messageId: rootId, acceptedAt: Date.now(),
+        subject: { ...subject, logDetails: [...subject.logDetails] }, status: 'running',
+      })
+    } catch (error) {
+      // The card is visible already; a lost record only means a retry of this
+      // key would post a second analysis.
+      this.deps.ctx.logger?.warn?.('dsh-channels: recording analyze request %s failed: %s', key, String(error))
+    }
+    const run = this.launch(channel, request, subject, rootId, key)
+    this.running.add(run)
+    void run.finally(() => { this.running.delete(run) })
+    return { status: 202, body }
+  }
+
+  /** Start the analysis below an accepted root card; every failure ends on the cards. */
+  private async launch(
+    channel: FeishuChannel,
+    request: AnalyzeRequest,
+    subject: AnalyzeSubject,
+    rootId: string,
+    key: string,
+  ): Promise<void> {
+    const warn = (message: string, ...args: unknown[]): void => {
+      this.deps.ctx.logger?.warn?.(message, ...args)
+    }
+    const showStatus = async (status: AnalyzeStatus): Promise<void> => {
+      await channel.updateCard(rootId, buildAnalyzeRootCard(subject, status)).catch((error: unknown) => {
+        warn('dsh-channels: updating analysis card %s failed: %s', rootId, String(error))
+      })
+      await this.recordStatus(key, status.kind)
+    }
+    const sessionId = randomUUID() as SessionId
+    let handle: AgentHandle | undefined
+    let cardId: string | undefined
+    let threadId: string | undefined
+    let releaseTopic: (() => void) | undefined
+    let published = false
+    try {
+      const topic = await this.openTopic(channel, request.chatId, rootId, sessionId)
+      cardId = topic.cardId
+      threadId = topic.threadId
+      releaseTopic = this.deps.reserveTopic(threadId)
+      const services = placementServices(this.deps.ctx)
+      const workspace = await ensureAnalyzeWorkspace(
+        this.deps.ctx, this.deps.config.baseDir, request.app, request.errorCode,
+      )
+      const topicToken = topicTokenFor(threadId, 'thread', sessionId)
+      const plan = await planTopic(services, this.deps.config, workspace.path, topicToken, warn)
+      this.assertStarted()
+      handle = await this.deps.sessions.createSession(sessionId, plan.cwd)
+      const placement: TopicPlacement = await enterTopic(
+        services, handle.agent, plan, workspace.path, topicToken, warn,
+      )
+      if (plan.cwd === workspace.path) {
+        void Promise.resolve(workspace.attachSession(sessionId)).catch((error: unknown) => {
+          warn('dsh-channels: attaching analysis session %s to workspace failed: %s', sessionId, String(error))
+        })
+      }
+      await this.deps.sessions.mountGuidance(handle.agent, placement.sessionDir)
+      this.assertStarted()
+
+      const createdAt = handle.agent.session.header.createdAt
+      const record: RouteRecord = {
+        key: threadId,
+        kind: 'thread',
+        sessionId,
+        chatId: request.chatId,
+        chatType: 'group',
+        senderUserId: request.requesterUserId,
+        workspacePath: workspace.path,
+        sessionDir: placement.sessionDir,
+        ...(placement.worktreeBranch === undefined ? {} : { worktreeBranch: placement.worktreeBranch }),
+        cardMessageId: cardId,
+        createdAt,
+        lastActivityAt: createdAt,
+        sessionHistory: [{ sessionId, createdAt }],
+        shared: true,
+      }
+      await this.deps.repair.write({
+        key: cardId,
+        sessionId,
+        chatId: request.chatId,
+        triggerMessageId: rootId,
+        cards: [{ messageId: cardId, mode: 'card' }],
+        startedAt: Date.now(),
+        attempts: 0,
+      })
+      const agent = handle.agent
+      const routeKey = threadId
+      const streamCardId = cardId
+      // Route, stream binding, and prompt land in one queue slot, so a reply
+      // posted in the topic meanwhile is delivered after the first turn.
+      await this.deps.queue.run(routeKey, async () => {
+        this.assertStarted()
+        await this.deps.routes.put(routeKey, record)
+        published = true
+        this.deps.streamer()?.attach(agent.session, streamCardId, rootId, undefined, {
+          onSettled: outcome => { void showStatus({ kind: outcome }) },
+        })
+        agent.followup(feishuUserMessage(request.prompt))
+      })
+    } catch (error) {
+      const reason = messageOf(error)
+      warn('dsh-channels: analysis for %s/%s failed to start: %s', request.app, request.errorCode, reason)
+      if (published && threadId !== undefined) {
+        await this.deps.routes.remove(threadId).catch((removeError: unknown) => {
+          warn('dsh-channels: removing analysis route %s failed: %s', threadId, String(removeError))
+        })
+      }
+      await handle?.dispose().catch(() => {})
+      if (cardId !== undefined) {
+        void this.deps.repair.clear(cardId)
+        await channel.updateCard(cardId, buildCard({
+          phase: 'error',
+          reasoning: '',
+          body: `❌ 分析未能开始：${reason}`,
+          stats: { sessionId, inputTokens: 0, outputTokens: 0 },
+        })).catch(() => {})
+      }
+      await showStatus({ kind: 'failed', reason })
+    } finally {
+      releaseTopic?.()
+    }
+  }
+
+  /**
+   * Open the analysis topic: the first streaming card, replied in thread below
+   * the root card. The topic id is read from that card (or the root card, in
+   * topic groups).
+   */
+  private async openTopic(
+    channel: FeishuChannel,
+    chatId: string,
+    rootId: string,
+    sessionId: SessionId,
+  ): Promise<{ cardId: string; threadId: string }> {
+    const sent = await channel.send(chatId, { card: initialStreamingCard(sessionId) }, {
+      replyTo: rootId, replyInThread: true,
+    })
+    const threadId = await channel.threadIdOfMessage(sent.messageId).catch(() => undefined)
+      ?? await channel.threadIdOfMessage(rootId).catch(() => undefined)
+    if (threadId === undefined) {
+      await channel.updateCard(sent.messageId, buildCard({
+        phase: 'error',
+        reasoning: '',
+        body: '❌ 无法在目标群创建话题',
+        stats: { sessionId, inputTokens: 0, outputTokens: 0 },
+      })).catch(() => {})
+      throw new Error('无法在目标群创建话题（读取话题 id 失败）')
+    }
+    return { cardId: sent.messageId, threadId }
+  }
+
+  /** Store a root card status in the request record (best-effort; the card already shows it). */
+  private async recordStatus(key: string, status: AnalyzeRequestRecord['status']): Promise<void> {
+    const domain = this.deps.domain()
+    const record = domain?.analyzeRequests.get(key)
+    if (domain === undefined || record === undefined) return
+    try {
+      await domain.analyzeRequests.put(key, { ...record, status })
+    } catch (error) {
+      this.deps.ctx.logger?.warn?.('dsh-channels: recording analysis %s status failed: %s', key, String(error))
+    }
+  }
+
+  private assertStarted(): void {
+    if (!this.deps.started()) throw new Error('飞书渠道已断开，分析已取消')
+  }
+}
+
+function subjectOf(request: AnalyzeRequest): AnalyzeSubject {
+  return {
+    requesterUserId: request.requesterUserId,
+    triggeredAt: request.triggeredAt,
+    app: request.app,
+    errorCode: request.errorCode,
+    logDetails: request.logDetails,
+  }
+}
+
+function refused(status: number, error: string): AnalyzeResponse {
+  return { status, body: { ok: false, error } }
+}
+
+function reusedKey(): AnalyzeResponse {
+  return refused(409, 'Idempotency-Key 已被内容不同的请求使用')
+}