@modesto_ma/dsh-channels 0.0.0-stage → 0.1.0

package/src/client/styles.ts

@@ -0,0 +1,98 @@
+/**
+ * Settings panel styling. DSH semantic tokens (`--dsw-alias-*`) with neutral
+ * fallbacks so the page follows the active theme; only pseudo-classes and
+ * responsive rules live here (everything else is inline in the component).
+ *
+ * @module dsh-channels/client/styles
+ */
+
+const STYLE_ATTRIBUTE = 'data-dsh-channels-css'
+
+const CSS = `
+.dsh-channels-cfg{container-type:inline-size;display:flex;flex-direction:column;gap:12px;width:100%;max-width:720px;color:var(--dsw-alias-label-primary,#1f2328);font-size:13px;line-height:20px}
+.dsh-channels-cfg__head{display:flex;flex-direction:column;gap:4px}
+.dsh-channels-cfg__title{margin:0;font-size:16px;font-weight:500;line-height:24px}
+.dsh-channels-cfg__desc{margin:0;color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:12px;line-height:18px}
+.dsh-channels-cfg__card{display:flex;flex-direction:column;gap:10px;padding:12px 14px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:12px}
+.dsh-channels-cfg__cardHead{display:flex;align-items:center;gap:8px;min-height:20px;flex-wrap:wrap}
+.dsh-channels-cfg__cardTitle{font-size:13px;font-weight:500}
+.dsh-channels-cfg__cardMeta{margin-left:auto;color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:12px}
+.dsh-channels-cfg__statusRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.dsh-channels-cfg__badge{display:inline-flex;align-items:center;gap:5px;padding:1px 8px;border-radius:999px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));font-size:12px;line-height:18px;white-space:nowrap}
+.dsh-channels-cfg__dot{width:7px;height:7px;border-radius:50%;background:currentColor;flex:none}
+.dsh-channels-cfg__badge--ok{color:var(--dsw-alias-state-business-primary,#0a7d33);border-color:currentColor}
+.dsh-channels-cfg__badge--warn{color:var(--dsw-alias-state-warning-primary,#a15c00);border-color:currentColor}
+.dsh-channels-cfg__badge--bad{color:var(--dsw-alias-state-danger-primary,#c62828);border-color:currentColor}
+.dsh-channels-cfg__badge--muted{color:var(--dsw-alias-label-tertiary,#8a8f98)}
+.dsh-channels-cfg__facts{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:8px 16px}
+.dsh-channels-cfg__fact{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dsh-channels-cfg__factLabel{color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:12px;line-height:16px}
+.dsh-channels-cfg__factValue{font-variant-numeric:tabular-nums;overflow-wrap:anywhere}
+.dsh-channels-cfg__actions{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.dsh-channels-cfg__btn{display:inline-flex;align-items:center;justify-content:center;gap:4px;min-height:28px;padding:0 12px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:8px;background:transparent;color:inherit;font:inherit;font-size:13px;cursor:pointer;white-space:nowrap}
+.dsh-channels-cfg__btn:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover,rgba(0,0,0,.05))}
+.dsh-channels-cfg__btn:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary,#0a67d3);outline-offset:2px}
+.dsh-channels-cfg__btn:disabled{color:var(--dsw-alias-label-dimmed,#b0b4ba);cursor:default}
+.dsh-channels-cfg__btn--primary{background:var(--dsw-alias-button-primary-fill,#0a67d3);border-color:transparent;color:var(--dsw-alias-label-primary-foreground,#fff)}
+.dsh-channels-cfg__btn--primary:hover:not(:disabled){background:var(--dsw-alias-button-primary-hover,#0b5cba)}
+.dsh-channels-cfg__btn--danger{color:var(--dsw-alias-state-danger-primary,#c62828);border-color:currentColor}
+.dsh-channels-cfg__grid{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px 20px;align-items:start}
+.dsh-channels-cfg__field{display:flex;flex-direction:column;gap:4px;min-width:0}
+.dsh-channels-cfg__field--wide{grid-column:1/-1}
+.dsh-channels-cfg__labelRow{display:flex;align-items:center;gap:6px;flex-wrap:wrap;min-width:0}
+.dsh-channels-cfg__label{font-size:12px;color:var(--dsw-alias-label-secondary,#5c6169)}
+.dsh-channels-cfg__tag{display:inline-flex;align-items:center;padding:0 5px;border-radius:4px;border:1px dashed currentColor;font-size:11px;line-height:16px;color:var(--dsw-alias-label-tertiary,#8a8f98);white-space:nowrap}
+.dsh-channels-cfg__tag--override{color:var(--dsw-alias-state-business-primary,#0a67d3);border-style:solid}
+.dsh-channels-cfg__tag--restart{color:var(--dsw-alias-state-warning-primary,#a15c00)}
+.dsh-channels-cfg__help{color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:11px;line-height:16px}
+.dsh-channels-cfg__reasonBad{color:var(--dsw-alias-state-danger-primary,#c62828)}
+.dsh-channels-cfg__input{box-sizing:border-box;width:100%;min-height:28px;padding:3px 10px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:8px;background:var(--dsw-alias-bg-layer-1,transparent);color:inherit;font:inherit;font-size:13px;outline:none}
+.dsh-channels-cfg__input:focus{border-color:var(--dsw-alias-state-business-primary,#0a67d3)}
+.dsh-channels-cfg__input--invalid{border-color:var(--dsw-alias-state-danger-primary,#c62828)}
+select.dsh-channels-cfg__input{appearance:auto;cursor:pointer}
+.dsh-channels-cfg__check{display:inline-flex;align-items:center;gap:6px;min-height:28px;cursor:pointer;font-size:13px}
+.dsh-channels-cfg__checkbox{width:15px;height:15px;margin:0;accent-color:var(--dsw-alias-state-business-primary,#0a67d3);cursor:pointer}
+.dsh-channels-cfg__fieldError{color:var(--dsw-alias-state-danger-primary,#c62828);font-size:11px;line-height:16px}
+.dsh-channels-cfg__notice{display:flex;flex-direction:column;gap:2px;padding:8px 10px;border-radius:8px;font-size:12px;line-height:18px}
+.dsh-channels-cfg__notice--ok{color:var(--dsw-alias-state-business-primary,#0a7d33);background:color-mix(in srgb,currentColor 8%,transparent)}
+.dsh-channels-cfg__notice--error{color:var(--dsw-alias-state-danger-primary,#c62828);background:color-mix(in srgb,currentColor 8%,transparent)}
+.dsh-channels-cfg__banner{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding:8px 10px;border-radius:8px;border:1px dashed var(--dsw-alias-state-warning-primary,#a15c00);color:var(--dsw-alias-state-warning-primary,#a15c00);font-size:12px;line-height:18px}
+.dsh-channels-cfg__footer{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding-top:2px}
+.dsh-channels-cfg__spacer{flex:1}
+.dsh-channels-cfg__readOnly{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:8px 20px}
+.dsh-channels-cfg__kv{display:flex;flex-direction:column;gap:2px;min-width:0}
+.dsh-channels-cfg__kvKey{color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:12px;line-height:16px}
+.dsh-channels-cfg__kvValue{overflow-wrap:anywhere}
+.dsh-channels-cfg__mono{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;font-size:12px}
+.dsh-channels-cfg__creds{display:flex;flex-direction:column;gap:6px}
+.dsh-channels-cfg__cred{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.dsh-channels-cfg__cred .dsh-channels-cfg__input{flex:1 1 240px;min-width:0;width:auto}
+.dsh-channels-cfg__accessSection{display:flex;flex-direction:column;gap:6px}
+.dsh-channels-cfg__accessList{list-style:none;margin:0;padding:0;display:flex;flex-direction:column;gap:6px}
+.dsh-channels-cfg__accessRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap;padding:6px 8px;border:1px solid var(--dsw-alias-border-l2,rgba(0,0,0,.12));border-radius:8px}
+.dsh-channels-cfg__accessMain{display:flex;flex-direction:column;gap:1px;min-width:0;flex:1 1 200px;overflow-wrap:anywhere}
+.dsh-channels-cfg__accessMeta{color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:11px;line-height:16px;overflow-wrap:anywhere}
+.dsh-channels-cfg__accessActions{display:flex;align-items:center;gap:6px;flex-wrap:wrap}
+.dsh-channels-cfg__accessAdd{display:flex;align-items:center;gap:8px;flex-wrap:wrap}
+.dsh-channels-cfg__accessInput{flex:1 1 140px;min-width:0;width:auto}
+.dsh-channels-cfg__error{padding:10px 12px;border:1px solid var(--dsw-alias-state-danger-primary,#c62828);border-radius:10px;color:var(--dsw-alias-state-danger-primary,#c62828);font-size:12px;line-height:18px;display:flex;flex-direction:column;gap:8px}
+.dsh-channels-cfg__loading{padding:16px 0;color:var(--dsw-alias-label-tertiary,#8a8f98);font-size:12px}
+.dsh-channels-cfg__issues{margin:0;padding-left:18px}
+@container (max-width:560px){
+.dsh-channels-cfg__facts{grid-template-columns:repeat(2,minmax(0,1fr))}
+.dsh-channels-cfg__grid,.dsh-channels-cfg__readOnly{grid-template-columns:minmax(0,1fr)}
+}
+`
+
+/** Append the panel stylesheet once (idempotent across HMR / remounts). */
+export function installStyles(): () => void {
+  const existing = document.querySelector(`style[${STYLE_ATTRIBUTE}]`)
+  if (existing !== null) return () => {}
+  const style = document.createElement('style')
+  style.setAttribute(STYLE_ATTRIBUTE, '')
+  style.textContent = CSS
+  document.head.append(style)
+  return () => {
+    style.remove()
+  }
+}

package/src/commands/registry.ts

@@ -0,0 +1,155 @@
+/**
+ * The channel's slash-command registry: one declarative source for the
+ * command vocabulary, admission rules, `/help` rendering, and dispatch.
+ *
+ * Adding a command means adding one entry here (plus its handler): the
+ * supported-name list, the help text, and the admission gate all derive from
+ * this table.
+ *
+ * @module dsh-channels/commands/registry
+ */
+
+/** Help grouping, in render order. */
+export const COMMAND_GROUPS = ['基础', '会话', '模型与上下文', '导出'] as const
+export type CommandGroup = typeof COMMAND_GROUPS[number]
+
+export interface ChannelCommandSpec {
+  /** Canonical command name (without the leading slash). */
+  readonly name: string
+  readonly group: CommandGroup
+  readonly description: string
+  /** Argument hint shown in help, e.g. `[id|reset]`. */
+  readonly usage?: string
+  /** Answerable without any Session work (and inside a retired topic). */
+  readonly routeFree?: boolean
+  /** Answerable with or without a bound Session: bound runs on the command plane. */
+  readonly sessionOptional?: boolean
+  /** Unthreaded group messages require a bot mention before the command answers. */
+  readonly mentionGate?: boolean
+  /** Only usable in this chat type. */
+  readonly chatType?: 'p2p' | 'group'
+  /** Answer with a direct reply instead of creating a topic. */
+  readonly directReply?: boolean
+  /**
+   * Answered by the channel itself (`/stop`), never through the agent command
+   * plane, and never cold-resuming a Session just to answer.
+   */
+  readonly channelPlane?: boolean
+  /**
+   * Registered inside each Agent scope for the agent command plane. Defaults
+   * to true; `false` for route-free commands, channel-plane commands, and the
+   * native host `/compact`.
+   */
+  readonly agentScoped?: boolean
+}
+
+/** The complete command vocabulary. */
+export const CHANNEL_COMMANDS = [
+  {
+    name: 'help', group: '基础', description: '显示当前支持的斜杠命令',
+    routeFree: true, directReply: false,
+  },
+  {
+    name: 'userid', group: '基础', description: '在私聊中显示当前用户 ID',
+    routeFree: true, mentionGate: true, chatType: 'p2p', directReply: true, agentScoped: false,
+  },
+  {
+    name: 'groupid', group: '基础', description: '在群聊中显示当前群组 ID',
+    routeFree: true, mentionGate: true, chatType: 'group', directReply: true, agentScoped: false,
+  },
+  {
+    name: 'health', group: '基础', description: '显示 Harness 与飞书通道健康状态',
+    sessionOptional: true,
+  },
+  {
+    name: 'status', group: '会话', description: '显示当前 Session 状态与性能指标',
+  },
+  {
+    name: 'workspace', group: '会话', description: '显示当前 Session 工作目录',
+  },
+  {
+    name: 'permissions', group: '会话', description: '查看（或按配置切换）当前 Session 权限预设',
+    usage: '[name]', channelPlane: true, agentScoped: false,
+  },
+  {
+    name: 'auth', group: '会话', description: '查看/管理访问授权（仅管理员）',
+    usage: '[status|allow|revoke|list|user add <open_id>|user remove <open_id>]',
+    routeFree: true, channelPlane: true, agentScoped: false,
+  },
+  {
+    name: 'renew', group: '会话', description: '在当前话题创建并绑定新 Session',
+  },
+  {
+    name: 'stop', group: '会话', description: '停止当前正在运行的回合',
+    channelPlane: true, agentScoped: false,
+  },
+  {
+    name: 'effort', group: '模型与上下文', description: '查看或切换当前 Session 推理强度',
+    usage: '[id|reset]',
+  },
+  {
+    name: 'model', group: '模型与上下文', description: '查看或切换当前 Session 模型',
+    usage: '[id|provider/model|reset]',
+  },
+  {
+    name: 'compact', group: '模型与上下文', description: '压缩当前 Session 上下文', agentScoped: false,
+  },
+  {
+    name: 'history', group: '导出', description: '显示当前话题的 Session 历史',
+  },
+  {
+    name: 'export', group: '导出', description: '导出当前 Session 的逻辑日志',
+  },
+] as const satisfies readonly ChannelCommandSpec[]
+
+/** Canonical command name literal union. */
+export type ChannelCommandName = typeof CHANNEL_COMMANDS[number]['name']
+
+/** User-facing aliases, resolved to their canonical command. */
+export const COMMAND_ALIASES = { new: 'renew' } as const
+export type ChannelCommandAlias = keyof typeof COMMAND_ALIASES
+
+/** Any command name a user may type. */
+export type SupportedCommandName = ChannelCommandName | ChannelCommandAlias
+
+const BY_NAME = new Map<string, ChannelCommandSpec>(
+  CHANNEL_COMMANDS.map(spec => [spec.name, spec as ChannelCommandSpec]),
+)
+
+/** Resolve one typed name (canonical or alias) to its command spec. */
+export function commandSpec(name: string): ChannelCommandSpec | undefined {
+  const canonical = (COMMAND_ALIASES as Record<string, string>)[name] ?? name
+  return BY_NAME.get(canonical)
+}
+
+/** Canonical command names, in registry order. */
+export function commandNames(): readonly ChannelCommandName[] {
+  return CHANNEL_COMMANDS.map(spec => spec.name)
+}
+
+/** Every typeable name (canonical + aliases), for the supported-name list. */
+export function supportedCommandNames(): readonly SupportedCommandName[] {
+  return [...commandNames(), ...Object.keys(COMMAND_ALIASES)] as SupportedCommandName[]
+}
+
+/** `用法：/effort [id|reset]` line, or undefined without a usage hint. */
+export function commandUsage(spec: ChannelCommandSpec): string | undefined {
+  if (spec.usage === undefined) return undefined
+  return `/${spec.name} ${spec.usage}`
+}
+
+/** Grouped `/help` markdown, derived from the registry. */
+export function groupedCommandHelp(): string {
+  const sections: string[] = []
+  const specs: readonly ChannelCommandSpec[] = CHANNEL_COMMANDS
+  for (const group of COMMAND_GROUPS) {
+    const lines = specs
+      .filter(spec => spec.group === group)
+      .map(spec => {
+        const usage = commandUsage(spec)
+        return `**/${spec.name}**${usage === undefined ? '' : ` ${spec.usage}`} — ${spec.description}`
+      })
+    if (lines.length > 0) sections.push(`**${group}**\n${lines.join('\n')}`)
+  }
+  return sections.join('\n\n')
+}

package/src/commands.ts

@@ -0,0 +1,335 @@
+/**
+ * Feishu slash-command admission primitives.
+ *
+ * This module deliberately contains no channel or Host I/O. It owns the
+ * product command vocabulary, exact parsing, agent-scoped registrations,
+ * per-route admission serialization, and standalone result-card rendering.
+ * Command-specific folds and side effects are added by the later SC tasks.
+ *
+ * @module dsh-channels/commands
+ */
+
+import type {
+  AgentContext, CommandDefinition, CommandDescriptor, CommandResult, CommandRuntime,
+} from './dsh-types.ts'
+import { card } from './cards/primitives.ts'
+
+import {
+  CHANNEL_COMMANDS, commandNames, groupedCommandHelp, commandSpec, supportedCommandNames,
+} from './commands/registry.ts'
+import type { ChannelCommandSpec, SupportedCommandName } from './commands/registry.ts'
+
+/** Canonical channel command names, in registry order (agent-scoped ones included). */
+export const CHANNEL_COMMAND_NAMES = commandNames()
+
+/** Every typeable command name (canonical + aliases). */
+export const SUPPORTED_COMMAND_NAMES = supportedCommandNames()
+
+export type { SupportedCommandName }
+
+export interface ParsedSlashCommand {
+  readonly name: string
+  /** Exact text following the command name, including separator whitespace. */
+  readonly rawInput: string
+}
+
+/** Match Harness' lowercase command grammar without normalizing arguments. */
+export function parseSlashCommand(line: string): ParsedSlashCommand | undefined {
+  const match = /^\/([a-z][a-z0-9_-]*)(?=$|[\t\n\r ])/u.exec(line)
+  if (match === null) return undefined
+  const name = match[1]
+  if (name === undefined) return undefined
+  return { name, rawInput: line.slice(match[0].length) }
+}
+
+export function isSupportedCommand(name: string): name is SupportedCommandName {
+  return commandSpec(name) !== undefined
+}
+
+/** Stable display used by unknown-command and deployment diagnostics. */
+export function supportedCommandList(): string {
+  return SUPPORTED_COMMAND_NAMES.map(name => `/${name}`).join('、')
+}
+
+/** Markdown help, grouped and generated from the command registry. */
+export function supportedCommandHelp(): string {
+  return groupedCommandHelp()
+}
+
+/** Commands registered inside each Agent scope (route-free ones are excluded). */
+const ALL_COMMANDS: readonly ChannelCommandSpec[] = CHANNEL_COMMANDS
+const AGENT_SCOPED_COMMANDS = ALL_COMMANDS.filter(spec => spec.agentScoped !== false)
+
+const DESCRIPTORS: ReadonlyArray<CommandDescriptor> = AGENT_SCOPED_COMMANDS.map(spec => ({
+  name: spec.name,
+  description: spec.description,
+  ...(spec.usage === undefined ? {} : { input: { hint: spec.usage } }),
+}))
+
+function pendingHandler(name: string): CommandDefinition['handler'] {
+  return ({ rawInput }): CommandResult => {
+    if (rawInput.trim() !== '') {
+      return { kind: 'error', text: `用法错误：/${name} 不接受参数。` }
+    }
+    return { kind: 'error', text: `命令 /${name} 的功能将在后续实施任务中启用。` }
+  }
+}
+
+function readyHandler(name: string, text: string): CommandDefinition['handler'] {
+  return ({ rawInput }): CommandResult => {
+    if (rawInput.trim() !== '') {
+      return { kind: 'error', text: `用法错误：/${name} 不接受参数。` }
+    }
+    return { kind: 'success', text }
+  }
+}
+
+const healthHandler: CommandDefinition['handler'] = ({ rawInput }): CommandResult => {
+  if (rawInput.trim() !== '') {
+    return { kind: 'error', text: '用法错误：/health 不接受参数。' }
+  }
+  return { kind: 'success', text: '健康检查已完成。' }
+}
+
+type RenewOperation = (invocation: Parameters<CommandDefinition['handler']>[0]) =>
+  ReturnType<CommandDefinition['handler']>
+
+export type EffortCommandAction =
+  | { readonly kind: 'show' }
+  | { readonly kind: 'set'; readonly value: string }
+  | { readonly kind: 'reset' }
+
+type EffortOperation = (
+  invocation: Parameters<CommandDefinition['handler']>[0],
+  action: EffortCommandAction,
+) => ReturnType<CommandDefinition['handler']>
+
+/** One armed `/model` execution: lists, validates, and switches models. */
+export type ModelOperation = (
+  invocation: Parameters<CommandDefinition['handler']>[0],
+  rawInput: string,
+) => ReturnType<CommandDefinition['handler']>
+
+/** Per-execution authority: handlers stay instance-neutral when an Agent is borrowed. */
+const RENEW_OPERATIONS = new WeakMap<AbortSignal, RenewOperation>()
+const EFFORT_OPERATIONS = new WeakMap<AbortSignal, EffortOperation>()
+const MODEL_OPERATIONS = new WeakMap<AbortSignal, ModelOperation>()
+
+function parseEffortAction(rawInput: string): EffortCommandAction | undefined {
+  const value = rawInput.trim()
+  if (value === '') return { kind: 'show' }
+  if (/\s/u.test(value)) return undefined
+  return value === 'reset' ? { kind: 'reset' } : { kind: 'set', value }
+}
+
+const effortHandler: CommandDefinition['handler'] = invocation => {
+  const action = parseEffortAction(invocation.rawInput)
+  if (action === undefined) {
+    return { kind: 'error', text: '用法错误：/effort [档位-id|reset]。' }
+  }
+  if (action.kind !== 'show' && (
+    invocation.agent.status !== 'idle'
+    || invocation.agent.inbox.nextTurn.length > 0
+    || invocation.agent.inbox.nextStep.length > 0
+  )) {
+    return { kind: 'error', text: '当前 Session 正忙或仍有排队消息，暂时不能切换推理强度。' }
+  }
+  const operation = EFFORT_OPERATIONS.get(invocation.signal)
+  if (operation === undefined) {
+    return { kind: 'error', text: '/effort 只能通过已授权的飞书话题执行。' }
+  }
+  return operation(invocation, action)
+}
+
+const modelHandler: CommandDefinition['handler'] = invocation => {
+  const rawInput = invocation.rawInput.trim()
+  if (/\s/u.test(rawInput)) {
+    return { kind: 'error', text: '用法错误：/model [模型-id|provider/model|reset]。' }
+  }
+  if (invocation.agent.status !== 'idle'
+    || invocation.agent.inbox.nextTurn.length > 0
+    || invocation.agent.inbox.nextStep.length > 0) {
+    return { kind: 'error', text: '当前 Session 正忙或仍有排队消息，暂时不能切换模型。' }
+  }
+  const operation = MODEL_OPERATIONS.get(invocation.signal)
+  if (operation === undefined) {
+    return { kind: 'error', text: '/model 只能通过已授权的飞书话题执行。' }
+  }
+  return operation(invocation, rawInput)
+}
+
+const renewHandler: CommandDefinition['handler'] = invocation => {
+  if (invocation.rawInput.trim() !== '') {
+    return { kind: 'error', text: '用法错误：/renew 不接受参数。' }
+  }
+  if (invocation.agent.status !== 'idle'
+    || invocation.agent.inbox.nextTurn.length > 0
+    || invocation.agent.inbox.nextStep.length > 0) {
+    return { kind: 'error', text: '当前 Session 正忙或仍有排队消息，暂时不能续建。' }
+  }
+  const operation = RENEW_OPERATIONS.get(invocation.signal)
+  if (operation === undefined) {
+    return { kind: 'error', text: '/renew 只能通过已授权的飞书话题执行。' }
+  }
+  return operation(invocation)
+}
+
+const READY_HANDLERS: Readonly<Record<string, CommandDefinition['handler']>> = {
+  help: readyHandler('help', supportedCommandHelp()),
+  health: healthHandler,
+  status: readyHandler('status', 'Session 状态已读取。'),
+  workspace: readyHandler('workspace', '工作目录已读取。'),
+  effort: effortHandler,
+  model: modelHandler,
+  renew: renewHandler,
+  history: readyHandler('history', 'Session 历史已读取。'),
+  export: readyHandler('export', '导出已请求。'),
+}
+
+/** Arm exactly one Feishu-issued `/renew` execution, then return its disarmer. */
+export function armRenewCommand(signal: AbortSignal, operation: RenewOperation): () => void {
+  RENEW_OPERATIONS.set(signal, operation)
+  return () => { RENEW_OPERATIONS.delete(signal) }
+}
+
+/** Arm exactly one Feishu-issued `/effort` execution, then return its disarmer. */
+export function armEffortCommand(signal: AbortSignal, operation: EffortOperation): () => void {
+  EFFORT_OPERATIONS.set(signal, operation)
+  return () => { EFFORT_OPERATIONS.delete(signal) }
+}
+
+/** Arm exactly one Feishu-issued `/model` execution, then return its disarmer. */
+export function armModelCommand(signal: AbortSignal, operation: ModelOperation): () => void {
+  MODEL_OPERATIONS.set(signal, operation)
+  return () => { MODEL_OPERATIONS.delete(signal) }
+}
+
+/** Install only `/model` into a borrowed Agent scope that lacks channel commands. */
+export function registerModelCommand(commands: CommandRuntime): () => void {
+  const descriptor = DESCRIPTORS.find(entry => entry.name === 'model')!
+  return commands.register({ ...descriptor, handler: modelHandler })
+}
+
+/** Install only `/renew` into a borrowed Agent scope that lacks channel commands. */
+export function registerRenewCommand(commands: CommandRuntime): () => void {
+  const descriptor = DESCRIPTORS.find(entry => entry.name === 'renew')!
+  return commands.register({ ...descriptor, handler: renewHandler })
+}
+
+/** Install only `/effort` into a borrowed Agent scope that lacks channel commands. */
+export function registerEffortCommand(commands: CommandRuntime): () => void {
+  const descriptor = DESCRIPTORS.find(entry => entry.name === 'effort')!
+  return commands.register({ ...descriptor, handler: effortHandler })
+}
+
+/**
+ * Register this channel's commands inside one agent scope. `/compact` stays
+ * global and is intentionally not registered here.
+ */
+export function registerChannelCommands(commands: CommandRuntime): void {
+  for (const descriptor of DESCRIPTORS) {
+    commands.register({
+      ...descriptor,
+      handler: READY_HANDLERS[descriptor.name] ?? pendingHandler(descriptor.name),
+    })
+  }
+}
+
+function registerScopedChannelCommands(ctx: AgentContext): void {
+  registerChannelCommands(ctx.commands)
+}
+
+/**
+ * Mount channel commands through an Agent child plugin that explicitly
+ * injects the command service. The Agent scope is minted by `agent-loop`, so
+ * it does not inherit this package's top-level dependency declaration.
+ */
+export async function mountChannelCommands(agentCtx: AgentContext): Promise<void> {
+  await agentCtx.inject(['commands'], registerScopedChannelCommands)
+}
+
+/**
+ * FIFO admission queue keyed by the durable route key. Failures never poison
+ * the tail, and an idle key is retired so the map remains bounded.
+ */
+export class RouteOperationQueue {
+  private readonly tails = new Map<string, Promise<void>>()
+
+  async run<T>(key: string, operation: () => Promise<T> | T): Promise<T> {
+    const previous = this.tails.get(key) ?? Promise.resolve()
+    const result = previous.catch(() => {}).then(operation)
+    const tail = result.then(() => {}, () => {})
+    this.tails.set(key, tail)
+    try {
+      return await result
+    } finally {
+      if (this.tails.get(key) === tail) this.tails.delete(key)
+    }
+  }
+
+  clear(): void {
+    this.tails.clear()
+  }
+}
+
+export type CommandCardKind =
+  | 'success'
+  | 'help'
+  | 'context-error'
+  | 'input-error'
+  | 'unknown'
+  | 'unbound'
+  | 'expired'
+  | 'forbidden'
+  | 'busy'
+  | 'unavailable'
+  | 'internal-error'
+
+export interface CommandCardState {
+  readonly kind: CommandCardKind
+  readonly command?: string
+  readonly text: string
+  readonly supported?: string
+  readonly sessionId?: string
+}
+
+/** Map stable command outcomes onto the shared result-card vocabulary. */
+export function commandResultCardKind(result: CommandResult): CommandCardKind {
+  if (result.kind === 'success') return 'success'
+  if (/^(?:用法错误：|Usage:)/u.test(result.text)) return 'input-error'
+  if (/\b(?:active compaction|not idle|busy)\b|正忙|正在运行/iu.test(result.text)) return 'busy'
+  return 'unavailable'
+}
+
+const CARD_TITLES: Record<CommandCardKind, string> = {
+  success: '✅ 命令执行完成',
+  help: '📖 斜杠命令帮助',
+  'context-error': '⚠️ 使用场景不匹配',
+  'input-error': '⚠️ 命令格式不正确',
+  unknown: '❓ 未知命令',
+  unbound: '🔗 尚未绑定会话',
+  expired: '⌛ 话题已过期',
+  forbidden: '🔒 无权操作此会话',
+  busy: '⏳ 会话正忙',
+  unavailable: '🧩 命令暂不可用',
+  'internal-error': '❌ 命令执行失败',
+}
+
+/** Render a small, non-streaming Feishu card that never contains raw errors. */
+export function buildCommandResultCard(state: CommandCardState): object {
+  const elements: object[] = [
+    { tag: 'markdown', content: `**${CARD_TITLES[state.kind]}**` },
+    { tag: 'markdown', content: state.text },
+  ]
+  if (state.supported !== undefined) {
+    elements.push({ tag: 'markdown', content: `可用命令：${state.supported}`, text_size: 'notation' })
+  }
+  if (state.command !== undefined || state.sessionId !== undefined) {
+    const trace = [
+      state.command === undefined ? undefined : `/${state.command}`,
+      state.sessionId,
+    ].filter((value): value is string => value !== undefined).join(' · ')
+    elements.push({ tag: 'markdown', content: trace, text_size: 'notation' })
+  }
+  return card(elements)
+}