@modesto_ma/dsh-channels 0.7.0 → 0.8.0-beta.1

package/src/topics/contract.ts

@@ -0,0 +1,149 @@
+/**
+ * Types of the `feishuTopics` service: another DSH plugin starts a
+ * group-shared Feishu topic Session from an external trigger (for example
+ * 观象's log-platform analyze API).
+ *
+ * One launch posts a root card into an authorized group, opens a topic below
+ * it, creates the Session in a workspace below the channel's `baseDir`, and
+ * streams the first turn (the prompt, verbatim) in that topic. The root card's
+ * status tag follows the first turn (进行中 → 已完成 / 已停止 / 失败) and turns
+ * 已中断 when DSH restarts before it settles. Every member admitted in the
+ * group may continue the topic.
+ *
+ * This module has no runtime exports, and the package subpath
+ * `@modesto_ma/dsh-channels/topics` exposes only its types. A consumer imports
+ * them with `import type`, looks the service up per call with
+ * `ctx.get('feishuTopics')` (absent while dsh-channels is not loaded or
+ * reloading), and checks {@link FeishuTopicService.version} before calling.
+ *
+ * @module dsh-channels/topics/contract
+ */
+
+/** Name the service is provided under (`ctx.get('feishuTopics')`). */
+export type FeishuTopicsServiceName = 'feishuTopics'
+
+/**
+ * Version of this contract. It changes only when a change would make an older
+ * consumer misbehave; a consumer refuses a provider whose version it does not
+ * know.
+ */
+export type FeishuTopicsVersion = 1
+
+/** One run of the root card's lead sentence. */
+export interface TopicCardText {
+  /** Plain text; Markdown characters are shown literally. */
+  readonly text: string
+  /** Shown in bold. */
+  readonly bold?: boolean
+}
+
+/** One linked row of the root card's table. */
+export interface TopicCardLink {
+  /** Row label. */
+  readonly name: string
+  /** `http(s)` address opened by the row's link. */
+  readonly url: string
+}
+
+/** What the root card shows besides its status. */
+export interface TopicRootCard {
+  /** Header title. */
+  readonly title: string
+  /**
+   * Word naming the work in the status texts, e.g. `分析` gives the tag
+   * `分析中` and the footer `分析已完成，结果见话题…`.
+   */
+  readonly taskName: string
+  /** Lead sentence, shown after an @-mention of the requester. */
+  readonly lead: readonly TopicCardText[]
+  /** Optional table of links (at most 50 rows). */
+  readonly links?: {
+    /** Header of the label column. */
+    readonly nameHeader: string
+    /** Header of the link column. */
+    readonly linkHeader: string
+    readonly rows: readonly TopicCardLink[]
+  }
+}
+
+/** One topic to start. */
+export interface TopicLaunchSpec {
+  /**
+   * Idempotency key (1–200 visible ASCII characters). A launch whose key was
+   * already accepted answers that launch's result instead of posting again.
+   * Keys are shared by every caller; a caller that may collide with another
+   * prefixes its keys.
+   */
+  readonly key: string
+  /**
+   * Caller-defined fingerprint of the request behind {@link key}, compared on
+   * replay: the same key with another fingerprint is refused (`key-conflict`).
+   */
+  readonly fingerprint: string
+  /** Target group chat (`oc_…`). It must be an authorized group, or the channel must run in `open` access mode. */
+  readonly chatId: string
+  /** Feishu `user_id` of the person the launch is for: @-mentioned on the root card and recorded as the route's requester. */
+  readonly requesterUserId: string
+  readonly card: TopicRootCard
+  /**
+   * Workspace of the Session: directory segments below the channel's
+   * `baseDir` (1–8 segments of `A-Z a-z 0-9 . _ -`, the first not one of the
+   * channel's own `p2p`, `groups`, `topics`, `_staging`), and its title in
+   * the DSH workspace list. Launches with the same segments share the
+   * workspace, each in its own topic directory.
+   */
+  readonly workspace: {
+    readonly segments: readonly string[]
+    readonly title: string
+  }
+  /** First user message of the Session, sent verbatim (at most 100 000 characters). */
+  readonly prompt: string
+}
+
+/**
+ * Why a launch was refused. Nothing was posted for `invalid`,
+ * `not-connected`, `forbidden-chat`, and `key-conflict`; `send-failed` means
+ * the root card could not be posted.
+ */
+export type TopicLaunchFailureCode =
+  /** The spec breaks a rule documented on {@link TopicLaunchSpec}. */
+  | 'invalid'
+  /** The Feishu connection is not established, or the channel is shutting down. */
+  | 'not-connected'
+  /** The target group is not authorized. */
+  | 'forbidden-chat'
+  /** The key was accepted before with another fingerprint. */
+  | 'key-conflict'
+  /** Feishu refused the root card (usually: the bot is not in the group). */
+  | 'send-failed'
+
+/** Outcome of {@link FeishuTopicService.launch}. */
+export type TopicLaunchResult =
+  | {
+    readonly ok: true
+    /** Whether this answers an earlier launch with the same key. */
+    readonly replayed: boolean
+    readonly chatId: string
+    /** Root card message id; the topic hangs below it. */
+    readonly messageId: string
+  }
+  | {
+    readonly ok: false
+    readonly code: TopicLaunchFailureCode
+    /** Readable reason (Chinese). */
+    readonly message: string
+  }
+
+/** The `feishuTopics` service. */
+export interface FeishuTopicService {
+  readonly version: FeishuTopicsVersion
+  /**
+   * Post the root card and start the topic. The promise settles once the
+   * root card is posted and recorded; the topic, Session, and first turn start
+   * in the background, and a failure there ends on the root card (失败, with
+   * the reason) instead of rejecting.
+   * @param spec - the topic to start.
+   * @returns the root card, or why nothing was started.
+   */
+  launch(spec: TopicLaunchSpec): Promise<TopicLaunchResult>
+}

package/src/topics/launcher.ts

@@ -0,0 +1,428 @@
+/**
+ * The `feishuTopics` service: other plugins start group-shared topics (see
+ * `./contract.ts`).
+ *
+ * Synchronously (before {@link TopicLauncher.launch} settles): spec
+ * validation, service state, target-group permission, idempotency replay, and
+ * the root card (进行中). In the background: the topic (opened by the first
+ * streaming card, replied in thread below the root card), the launch workspace
+ * and its per-topic directory, the Session, the group-shared route, and the
+ * first turn: the prompt verbatim, streamed into that card like any topic
+ * turn. When the first turn settles, the root card's status follows it
+ * (已完成 / 已停止 / 失败), and the launch record keeps the same status. At
+ * channel start, records still `running` belong to topics a previous instance
+ * never finished; {@link TopicLauncher.markInterrupted} marks their cards
+ * 已中断.
+ *
+ * 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/topics/launcher
+ */
+
+import { randomUUID } from 'node:crypto'
+import { z } from 'zod'
+import type { AgentHandle, HostContext, SessionId } from '../dsh-types.ts'
+import type { FeishuConfig } from '../config.ts'
+import { buildCard, buildTopicRootCard, initialStreamingCard } from '../cards.ts'
+import type { TopicStatus } from '../cards.ts'
+import type { RouteOperationQueue } from '../commands.ts'
+import { FEISHU_USER_ID_PATTERN, rootCardOf } from '../domain.ts'
+import type { FeishuDomainHandle, RouteRecord, TopicLaunchRecord } 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 { ensureLaunchWorkspace, RESERVED_WORKSPACE_ROOTS, topicTokenFor } from '../workspaces.ts'
+import type {
+  FeishuTopicService, FeishuTopicsServiceName, FeishuTopicsVersion, TopicLaunchFailureCode,
+  TopicLaunchResult, TopicLaunchSpec, TopicRootCard,
+} from './contract.ts'
+
+/** Name the launcher is provided under. */
+export const FEISHU_TOPICS_SERVICE: FeishuTopicsServiceName = 'feishuTopics'
+
+/** Contract version the launcher implements. */
+export const FEISHU_TOPICS_VERSION: FeishuTopicsVersion = 1
+
+const text = (max: number) => z.string().min(1).max(max).refine(value => value.trim() !== '', 'must not be blank')
+
+/** Workspace path segment: path-safe, never `.` or `..`. */
+const WORKSPACE_SEGMENT = /^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$/u
+
+/** Feishu group chat id (`oc_…`). */
+const CHAT_ID = /^oc_[A-Za-z0-9_-]{1,128}$/u
+
+/** Launch spec validation: the rules {@link TopicLaunchSpec} documents. */
+const topicLaunchSpecSchema = z.object({
+  key: z.string().regex(/^[\x21-\x7E]{1,200}$/u, 'must be 1-200 visible ASCII characters'),
+  fingerprint: z.string().min(1).max(512),
+  chatId: z.string().regex(CHAT_ID, 'must be a Feishu group chat_id (oc_...)'),
+  requesterUserId: z.string().regex(FEISHU_USER_ID_PATTERN, 'must be a Feishu user_id').max(128),
+  card: z.object({
+    title: text(100),
+    taskName: text(20),
+    lead: z.array(z.object({ text: z.string().max(1000), bold: z.boolean().optional() }).strict()).min(1).max(20),
+    links: z.object({
+      nameHeader: text(20),
+      linkHeader: text(20),
+      rows: z.array(z.object({
+        name: text(200),
+        url: z.url({ protocol: /^https?$/u, error: 'must be an http(s) URL' }).max(2048),
+      }).strict()).max(50),
+    }).strict().optional(),
+  }).strict(),
+  workspace: z.object({
+    segments: z.array(z.string().regex(WORKSPACE_SEGMENT, 'must be 1-128 of A-Z a-z 0-9 . _ -')).min(1).max(8)
+      .refine(segments => !RESERVED_WORKSPACE_ROOTS.includes(segments[0] ?? ''), `must not start with ${RESERVED_WORKSPACE_ROOTS.join(', ')}`),
+    title: text(200),
+  }).strict(),
+  prompt: text(100_000),
+}).strict()
+
+/** Collaborators of the launcher (late-bound where the service swaps them per connection). */
+export interface TopicLauncherDeps {
+  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 a launch may post into the group. */
+  mayLaunchIn(chatId: string): boolean
+}
+
+/** One accepted launch still posting its root card. */
+interface PendingAccept {
+  readonly fingerprint: string
+  readonly result: Promise<TopicLaunchResult>
+}
+
+/** Readable reason of an error value. */
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export class TopicLauncher implements FeishuTopicService {
+  readonly version = FEISHU_TOPICS_VERSION
+  /** Idempotency key → launch still being accepted (concurrent retries share it). */
+  private readonly accepting = new Map<string, PendingAccept>()
+  /** Background topics still starting (drained on shutdown). */
+  private readonly running = new Set<Promise<void>>()
+  /** Whether launches are admitted: from {@link open} after start until {@link close}. */
+  private admitting = false
+
+  constructor(private readonly deps: TopicLauncherDeps) {}
+
+  /**
+   * Start admitting launches. Called at channel start after
+   * {@link markInterrupted}, so a new launch is never marked interrupted.
+   */
+  open(): void {
+    this.admitting = true
+  }
+
+  /** Refuse launches (`not-connected`) ahead of shutdown. */
+  close(): void {
+    this.admitting = false
+  }
+
+  async launch(spec: TopicLaunchSpec): Promise<TopicLaunchResult> {
+    const parsed = topicLaunchSpecSchema.safeParse(spec)
+    if (!parsed.success) {
+      const details = parsed.error.issues
+        .map(issue => `${issue.path.join('.') || '(spec)'}: ${issue.message}`)
+        .join('; ')
+      return refused('invalid', `话题参数不合法：${details}`)
+    }
+    const valid = parsed.data
+    const pending = this.accepting.get(valid.key)
+    if (pending !== undefined) {
+      if (pending.fingerprint !== valid.fingerprint) return reusedKey()
+      return await pending.result
+    }
+    const result = this.accept(valid)
+    this.accepting.set(valid.key, { fingerprint: valid.fingerprint, result })
+    try {
+      return await result
+    } finally {
+      this.accepting.delete(valid.key)
+    }
+  }
+
+  /**
+   * Wait for every acceptance in flight, then every background topic 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> {
+    // Acceptances still sending the root card or writing the record finish
+    // first; each one adds its launch to `running` before it settles.
+    await Promise.allSettled([...this.accepting.values()].map(pending => pending.result))
+    await Promise.allSettled([...this.running])
+  }
+
+  /**
+   * Mark every launch still `running` as interrupted, on its card and in its
+   * record. Called at channel start before admission 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.topicLaunches.entries()]) {
+      if (record.status !== 'running') continue
+      const root = rootCardOf(record)
+      if (root !== undefined) {
+        await channel.updateCard(record.messageId, buildTopicRootCard(root.requesterUserId, root.card, { kind: 'interrupted' }))
+          .catch((error: unknown) => {
+            this.deps.ctx.logger?.warn?.('dsh-channels: marking topic card %s interrupted failed: %s', key, String(error))
+          })
+      }
+      await this.recordStatus(key, 'interrupted')
+    }
+  }
+
+  private async accept(spec: TopicLaunchSpec): Promise<TopicLaunchResult> {
+    const channel = this.deps.channel()
+    const domain = this.deps.domain()
+    if (!this.admitting || !this.deps.started() || channel === undefined || domain === undefined) {
+      return refused('not-connected', '飞书渠道尚未连接，请稍后重试')
+    }
+    const stored = domain.topicLaunches.get(spec.key)
+    if (stored !== undefined) {
+      if (stored.bodyHash !== spec.fingerprint) return reusedKey()
+      return { ok: true, replayed: true, chatId: stored.chatId, messageId: stored.messageId }
+    }
+    if (!this.deps.mayLaunchIn(spec.chatId)) {
+      return refused('forbidden-chat', '目标群未授权：请管理员在该群发送 /auth group add，或在设置面板「访问与授权」中添加')
+    }
+    const card = copyCard(spec.card)
+    let rootId: string
+    try {
+      rootId = (await channel.send(spec.chatId, {
+        card: buildTopicRootCard(spec.requesterUserId, card, { kind: 'running' }),
+      })).messageId
+    } catch (error) {
+      return refused('send-failed', `${spec.card.taskName}卡片发送失败（机器人需在目标群内）：${messageOf(error)}`)
+    }
+    try {
+      await domain.topicLaunches.put(spec.key, {
+        key: spec.key, bodyHash: spec.fingerprint, chatId: spec.chatId, messageId: rootId, acceptedAt: Date.now(),
+        requesterUserId: spec.requesterUserId, card, status: 'running',
+      })
+    } catch (error) {
+      // The card is visible already; a lost record only means a retry of this
+      // key would post a second topic.
+      this.deps.ctx.logger?.warn?.('dsh-channels: recording topic launch %s failed: %s', spec.key, String(error))
+    }
+    const run = this.start(channel, spec, card, rootId)
+    this.running.add(run)
+    void run.finally(() => { this.running.delete(run) })
+    return { ok: true, replayed: false, chatId: spec.chatId, messageId: rootId }
+  }
+
+  /** Start the topic below an accepted root card; every failure ends on the cards. */
+  private async start(
+    channel: FeishuChannel,
+    spec: TopicLaunchSpec,
+    card: TopicRootCard,
+    rootId: string,
+  ): Promise<void> {
+    const warn = (message: string, ...args: unknown[]): void => {
+      this.deps.ctx.logger?.warn?.(message, ...args)
+    }
+    const showStatus = async (status: TopicStatus): Promise<void> => {
+      await channel.updateCard(rootId, buildTopicRootCard(spec.requesterUserId, card, status)).catch((error: unknown) => {
+        warn('dsh-channels: updating topic card %s failed: %s', rootId, String(error))
+      })
+      await this.recordStatus(spec.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, spec.chatId, rootId, sessionId)
+      cardId = topic.cardId
+      threadId = topic.threadId
+      releaseTopic = this.deps.reserveTopic(threadId)
+      const services = placementServices(this.deps.ctx)
+      const workspace = await ensureLaunchWorkspace(
+        this.deps.ctx, this.deps.config.baseDir, spec.workspace.segments, spec.workspace.title,
+      )
+      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 topic 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: spec.chatId,
+        chatType: 'group',
+        senderUserId: spec.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: spec.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(spec.prompt))
+      })
+    } catch (error) {
+      const reason = messageOf(error)
+      warn('dsh-channels: topic %s failed to start: %s', spec.key, reason)
+      if (published && threadId !== undefined) {
+        await this.deps.routes.remove(threadId).catch((removeError: unknown) => {
+          warn('dsh-channels: removing topic 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: `❌ ${card.taskName}未能开始：${reason}`,
+          stats: { sessionId, inputTokens: 0, outputTokens: 0 },
+        })).catch(() => {})
+      }
+      await showStatus({ kind: 'failed', reason })
+    } finally {
+      releaseTopic?.()
+    }
+  }
+
+  /**
+   * Open the 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 launch record (best-effort; the card already shows it). */
+  private async recordStatus(key: string, status: TopicLaunchRecord['status']): Promise<void> {
+    const domain = this.deps.domain()
+    const record = domain?.topicLaunches.get(key)
+    if (domain === undefined || record === undefined) return
+    try {
+      await domain.topicLaunches.put(key, { ...record, status })
+    } catch (error) {
+      this.deps.ctx.logger?.warn?.('dsh-channels: recording topic %s status failed: %s', key, String(error))
+    }
+  }
+
+  private assertStarted(): void {
+    if (!this.deps.started()) throw new Error('飞书渠道已断开，已取消')
+  }
+}
+
+/** A detached copy of the card, so the caller cannot change what is recorded. */
+function copyCard(card: TopicRootCard): NonNullable<TopicLaunchRecord['card']> {
+  return {
+    title: card.title,
+    taskName: card.taskName,
+    lead: card.lead.map(run => (run.bold === undefined ? { text: run.text } : { text: run.text, bold: run.bold })),
+    ...(card.links === undefined
+      ? {}
+      : {
+          links: {
+            nameHeader: card.links.nameHeader,
+            linkHeader: card.links.linkHeader,
+            rows: card.links.rows.map(row => ({ name: row.name, url: row.url })),
+          },
+        }),
+  }
+}
+
+function refused(code: TopicLaunchFailureCode, message: string): TopicLaunchResult {
+  return { ok: false, code, message }
+}
+
+function reusedKey(): TopicLaunchResult {
+  return refused('key-conflict', '幂等键已被内容不同的请求使用')
+}

package/src/workspaces.ts

@@ -5,7 +5,8 @@
  * - p2p:   workspace `<baseDir>/p2p/<user_id>/`
  * - group: workspace `<baseDir>/groups/<chat_id>/<user_id>/`
  * - topic: `<workspace>/topics/<topic-token>/` (the Session's effective cwd)
- * - log-platform analysis: workspace `<baseDir>/analyze/<app>/<errorCode>/`
+ * - `feishuTopics` launch: workspace `<baseDir>/<caller segments…>/` (观象's
+ *   log analyses use `<baseDir>/analyze/<app>/<errorCode>/`)
  *
  * The workspace root is the Session header cwd: it keeps the Session grouped
  * under the user's project in the GUI and stays the sandbox write boundary.
@@ -235,31 +236,37 @@ export async function ensureWorkspace(
 }
 
 /**
- * Workspace directory of one log-platform analysis subject:
- * `<baseDir>/analyze/<app>/<errorCode>/`. Every analysis of the same
- * application and error code is grouped there, each in its own topic
- * directory.
+ * First path segments this module lays out itself; a `feishuTopics` launch
+ * workspace may not start with one of them.
  */
-export function analyzeWorkspacePathFor(baseDir: string, app: string, errorCode: string): string {
-  return path.join(baseDir, 'analyze', safeSegment(app, 'app'), safeSegment(errorCode, 'errorCode'))
-}
+export const RESERVED_WORKSPACE_ROOTS: readonly string[] = ['p2p', 'groups', 'topics', '_staging']
 
-/** Workspace title of one analysis subject in the DSH workspace list. */
-export function analyzeWorkspaceTitleFor(app: string, errorCode: string): string {
-  return `日志分析 · ${app} · ${errorCode}`
+/**
+ * Workspace directory of one `feishuTopics` launch:
+ * `<baseDir>/<segments…>/`. Launches with the same segments share it, each in
+ * its own topic directory.
+ * @throws when a segment is unsafe or the first one is reserved.
+ */
+export function launchWorkspacePathFor(baseDir: string, segments: readonly string[]): string {
+  if (segments.length === 0) throw new Error('dsh-channels: a launch workspace needs at least one path segment')
+  const safe = segments.map(segment => safeSegment(segment, 'launch workspace segment'))
+  if (RESERVED_WORKSPACE_ROOTS.includes(safe[0]!)) {
+    throw new Error(`dsh-channels: launch workspace may not start with reserved segment ${JSON.stringify(safe[0])}`)
+  }
+  return path.join(baseDir, ...safe)
 }
 
 /**
- * Ensure one analysis subject's workspace exists and is registered (idempotent
- * like {@link ensureWorkspace}).
+ * Ensure one launch workspace exists and is registered (idempotent like
+ * {@link ensureWorkspace}).
  */
-export async function ensureAnalyzeWorkspace(
+export async function ensureLaunchWorkspace(
   ctx: HostContext,
   baseDir: string,
-  app: string,
-  errorCode: string,
+  segments: readonly string[],
+  title: string,
 ): Promise<Workspace> {
-  const dir = analyzeWorkspacePathFor(baseDir, app, errorCode)
+  const dir = launchWorkspacePathFor(baseDir, segments)
   await mkdir(dir, { recursive: true })
-  return ctx.workspaceRegistry.create(dir, analyzeWorkspaceTitleFor(app, errorCode))
+  return ctx.workspaceRegistry.create(dir, title)
 }