@modesto_ma/dsh-guanxiang 0.2.0-beta.1 → 0.2.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modesto_ma/dsh-guanxiang",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.2",
   "description": "观象 GuanXiang：DeepSeek Harness (DSH) 日志分析插件。/guanxiang 识别日志所属应用，把分析派发给工作目录为该应用代码仓库的子 Agent；Web 左侧栏提供「观象」设置面板",
   "repository": {
     "type": "git",
@@ -82,6 +82,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",
+    "@modesto_ma/dsh-channels": "^0.8.0-beta.1",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/github": "^12.0.10",
     "@semantic-release/npm": "^13.2.0",

package/src/analyze/contract.ts

@@ -0,0 +1,124 @@
+/**
+ * 日志平台分析接口的请求与响应。
+ *
+ * `POST /open-api/logalyze`（DSH Web 服务器上），带
+ * `Authorization: Bearer <令牌>`、`Idempotency-Key` 请求头和 JSON 请求体：
+ * 发起人、触发时间、应用与错误码、日志详情页、目标群和提示词。合法请求把
+ * 分析根卡片发进群并回 `202`，分析随后在卡片下的话题里流式进行。日志包由
+ * 提示词调用的分析 SKILL 自行获取，详情页只列在卡片上。
+ *
+ * 接口原由 dsh-channels 0.7 提供；迁到观象后请求、响应和错误文本不变。
+ *
+ * @module dsh-guanxiang/analyze/contract
+ */
+
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+
+export { ANALYZE_ROUTE } from '../settings/contract.ts'
+
+/** 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
+
+/** Feishu `user_id`: not an `open_id` (`ou_`), `union_id` (`on_`), or chat id (`oc_`). */
+const FEISHU_USER_ID = /^(?!ou_|on_|oc_)[A-Za-z0-9_-]+$/u
+
+/**
+ * Application / error-code segment: it names a workspace directory
+ * (`<baseDir>/analyze/<app>/<errorCode>` below the Feishu channel's
+ * `baseDir`), 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, '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()
+
+/** One validated analyze request. */
+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: dsh-channels
+ * 0.7 stored the same digest, so its accepted keys keep replaying.
+ * @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/server.ts

@@ -0,0 +1,195 @@
+/**
+ * 日志平台分析接口在 DSH Web 服务器上的路由。
+ *
+ * 只在宿主同时提供 `webServer` 和版本兼容的 dsh-channels `feishuTopics`
+ * 服务时注册精确路由 `POST /open-api/logalyze`；dsh-channels 未加载、重载
+ * 中、版本不兼容或为 0.7 及更早版本（自己注册该路由）时观象不注册，两者
+ * 不会争用同一路径。
+ * 本模块按顺序做传输层检查：路径、开关、方法、Bearer 令牌、
+ * `Idempotency-Key`、媒体类型、请求体大小和 JSON 校验；通过后交给
+ * `feishuTopics`。请求体、令牌和提示词都不写日志。
+ *
+ * @module dsh-guanxiang/analyze/server
+ */
+
+import { createHash, timingSafeEqual } from 'node:crypto'
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import type { HostContext, HostWebServer } from '../host.ts'
+import {
+  ANALYZE_MAX_BODY_BYTES, ANALYZE_ROUTE, IDEMPOTENCY_KEY_PATTERN, parseAnalyzeRequest,
+} from './contract.ts'
+import type { AnalyzeRequest, AnalyzeResponse } from './contract.ts'
+import { FEISHU_TOPICS_SERVICE, launchAnalysis, lookupTopics } from './topics.ts'
+
+/** The plugin side of the route: switch and token, read per request. */
+export interface AnalyzeGate {
+  /** @returns whether the API is switched on; false answers every request with 404. */
+  enabled(): boolean
+  /** Credential reference holding the bearer token, named in the 503 answer while it is unset. */
+  tokenEnv(): string
+  /**
+   * Resolve the expected bearer token.
+   * @returns the token, or undefined when it is not configured or cannot be read.
+   */
+  token(): Promise<string | undefined>
+}
+
+/** Everything after transport checks: start the analysis of one validated request. */
+export type AnalyzeLaunch = (request: AnalyzeRequest, idempotencyKey: string) => Promise<AnalyzeResponse>
+
+class HttpError extends Error {
+  constructor(readonly status: number, message: string) {
+    super(message)
+  }
+}
+
+function send(res: ServerResponse, response: AnalyzeResponse): void {
+  const body = JSON.stringify(response.body)
+  res.writeHead(response.status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(body),
+  })
+  res.end(body)
+}
+
+function refuse(res: ServerResponse, status: number, error: string, headers: Record<string, string> = {}): void {
+  for (const [name, value] of Object.entries(headers)) res.setHeader(name, value)
+  send(res, { status, body: { ok: false, error } })
+}
+
+/** Constant-time token comparison over fixed-length digests. */
+function tokenMatches(presented: string, expected: string): boolean {
+  const left = createHash('sha256').update(presented).digest()
+  const right = createHash('sha256').update(expected).digest()
+  return timingSafeEqual(left, right)
+}
+
+/** The bearer credential of one request, or undefined. */
+function bearerOf(req: IncomingMessage): string | undefined {
+  const header = req.headers.authorization
+  if (header === undefined) return undefined
+  const match = /^Bearer[ \t]+(\S+)[ \t]*$/iu.exec(header)
+  return match?.[1]
+}
+
+/** Read the body up to {@link ANALYZE_MAX_BODY_BYTES}; larger bodies fail with 413. */
+async function readBody(req: IncomingMessage): Promise<string> {
+  const declared = Number(req.headers['content-length'])
+  if (Number.isFinite(declared) && declared > ANALYZE_MAX_BODY_BYTES) {
+    throw new HttpError(413, `请求体超过 ${ANALYZE_MAX_BODY_BYTES} 字节`)
+  }
+  const chunks: Buffer[] = []
+  let size = 0
+  for await (const chunk of req) {
+    const buffer = typeof chunk === 'string' ? Buffer.from(chunk) : chunk as Buffer
+    size += buffer.length
+    if (size > ANALYZE_MAX_BODY_BYTES) throw new HttpError(413, `请求体超过 ${ANALYZE_MAX_BODY_BYTES} 字节`)
+    chunks.push(buffer)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+/**
+ * Handle one HTTP request against the analyze API.
+ * @param req - the incoming request.
+ * @param res - its response.
+ * @param gate - switch and token.
+ * @param launch - starts the analysis of a validated request.
+ */
+export async function handleAnalyzeHttp(
+  req: IncomingMessage,
+  res: ServerResponse,
+  gate: AnalyzeGate,
+  launch: AnalyzeLaunch,
+): Promise<void> {
+  const pathname = new URL(req.url ?? '/', 'http://analyze.invalid').pathname
+  if (pathname !== ANALYZE_ROUTE) {
+    refuse(res, 404, '未知路径')
+    return
+  }
+  if (!gate.enabled()) {
+    refuse(res, 404, '日志分析接口未开启，请在观象设置面板「分析接口」打开开关')
+    return
+  }
+  if ((req.method ?? 'GET').toUpperCase() !== 'POST') {
+    refuse(res, 405, '只接受 POST', { allow: 'POST' })
+    return
+  }
+  const expected = await gate.token()
+  if (expected === undefined || expected === '') {
+    refuse(res, 503, `分析接口未配置访问令牌，请在观象设置面板「分析接口」保存令牌（凭据名 ${gate.tokenEnv()}）`)
+    return
+  }
+  const presented = bearerOf(req)
+  if (presented === undefined || !tokenMatches(presented, expected)) {
+    refuse(res, 401, '访问令牌无效', { 'www-authenticate': 'Bearer' })
+    return
+  }
+  const idempotencyKey = req.headers['idempotency-key']
+  if (typeof idempotencyKey !== 'string' || !IDEMPOTENCY_KEY_PATTERN.test(idempotencyKey)) {
+    refuse(res, 400, '缺少或不合法的 Idempotency-Key 请求头（1-200 个可见 ASCII 字符）')
+    return
+  }
+  const mediaType = (req.headers['content-type'] ?? '').split(';')[0]?.trim().toLowerCase()
+  if (mediaType !== 'application/json') {
+    refuse(res, 415, 'Content-Type 必须是 application/json')
+    return
+  }
+  let raw: unknown
+  try {
+    raw = JSON.parse(await readBody(req))
+  } catch (error) {
+    if (error instanceof HttpError) {
+      refuse(res, error.status, error.message)
+      return
+    }
+    refuse(res, 400, '请求体不是合法的 JSON')
+    return
+  }
+  const parsed = parseAnalyzeRequest(raw)
+  if (!parsed.ok) {
+    refuse(res, 400, parsed.error)
+    return
+  }
+  send(res, await launch(parsed.value, idempotencyKey))
+}
+
+/**
+ * Register the route while the host provides both `webServer` and a
+ * compatible `feishuTopics`; it is removed when either goes away. Requests skip the DSH
+ * login gate on purpose: the bearer token is this API's only credential.
+ * @param ctx - the plugin context.
+ * @param gate - switch and token.
+ */
+export function mountAnalyzeRoute(ctx: HostContext, gate: AnalyzeGate): void {
+  const attach = (scope: HostContext): void => {
+    const server = scope.get?.('webServer') as HostWebServer | undefined
+    if (server === undefined) return
+    const topics = lookupTopics(scope.get?.(FEISHU_TOPICS_SERVICE))
+    if (topics.availability !== 'ready') {
+      if (topics.availability === 'incompatible') ctx.logger?.warn?.('guanxiang: dsh-channels 的 feishuTopics 服务版本与观象不兼容，分析接口未注册；请把两者升级到相互兼容的版本')
+      return
+    }
+    const { service } = topics
+    const launch: AnalyzeLaunch = (request, key) => launchAnalysis(service, request, key)
+    scope.effect(() => server.register({
+      kind: 'exact',
+      path: ANALYZE_ROUTE,
+      handler: async (req, res) => {
+        try {
+          await handleAnalyzeHttp(req, res, gate, launch)
+        } catch (error) {
+          ctx.logger?.warn?.('guanxiang: 分析请求处理失败：%s', String(error))
+          if (!res.headersSent) refuse(res, 500, `分析请求处理失败：${String(error)}`)
+          else res.destroy()
+        }
+      },
+    }), 'guanxiang: analyze route')
+  }
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['webServer', FEISHU_TOPICS_SERVICE], attach)
+    return
+  }
+  attach(ctx)
+}

package/src/analyze/topics.ts

@@ -0,0 +1,109 @@
+/**
+ * 分析请求到 dsh-channels `feishuTopics` 服务的转换：根卡片内容、工作区
+ * `analyze/<app>/<errorCode>`、幂等键与指纹，以及服务结果到 HTTP 响应的映射。
+ * 卡片、工作区和指纹与 dsh-channels 0.7 自带的分析接口一致，升级前接受的
+ * `Idempotency-Key` 升级后仍按原结果重放。
+ *
+ * 只从 `@modesto_ma/dsh-channels/topics` 引入类型；服务在运行时经
+ * `ctx.get('feishuTopics')` 取得，版本不符时不调用。
+ *
+ * @module dsh-guanxiang/analyze/topics
+ */
+
+import type {
+  FeishuTopicService, FeishuTopicsVersion, TopicLaunchResult, TopicLaunchSpec,
+} from '@modesto_ma/dsh-channels/topics'
+import type { TopicsAvailability } from '../settings/contract.ts'
+import { analyzeRequestHash } from './contract.ts'
+import type { AnalyzeRequest, AnalyzeResponse } from './contract.ts'
+
+/** Name dsh-channels provides the service under. */
+export const FEISHU_TOPICS_SERVICE = 'feishuTopics'
+
+/** The `feishuTopics` contract version this plugin speaks. */
+export const FEISHU_TOPICS_VERSION: FeishuTopicsVersion = 1
+
+/** Result of looking the service up. */
+export type TopicsLookup =
+  | { readonly availability: 'ready'; readonly service: FeishuTopicService }
+  | { readonly availability: Exclude<TopicsAvailability, 'ready'> }
+
+/**
+ * Classify the value `ctx.get('feishuTopics')` returned. The provider is
+ * another package that may be older or newer than this one, so its version
+ * is checked at run time.
+ * @param value - the looked-up service, or undefined.
+ * @returns the usable service, or why there is none.
+ */
+export function lookupTopics(value: unknown): TopicsLookup {
+  if (value === undefined || value === null) return { availability: 'missing' }
+  const service = value as Partial<Record<keyof FeishuTopicService, unknown>>
+  if (service.version !== FEISHU_TOPICS_VERSION || typeof service.launch !== 'function') return { availability: 'incompatible' }
+  return { availability: 'ready', service: value as FeishuTopicService }
+}
+
+/**
+ * The topic one analyze request starts.
+ * @param request - the validated request.
+ * @param idempotencyKey - the request's `Idempotency-Key`, used unchanged as the launch key.
+ * @returns the launch spec.
+ */
+export function analyzeTopicSpec(request: AnalyzeRequest, idempotencyKey: string): TopicLaunchSpec {
+  return {
+    key: idempotencyKey,
+    fingerprint: analyzeRequestHash(request),
+    chatId: request.chatId,
+    requesterUserId: request.requesterUserId,
+    card: {
+      title: '日志分析',
+      taskName: '分析',
+      lead: [
+        { text: `于 ${request.triggeredAt} 发起了对 ` },
+        { text: request.app, bold: true },
+        { text: ' 应用 ' },
+        { text: request.errorCode, bold: true },
+        { text: ' 错误码不良日志的分析。' },
+      ],
+      links: { nameHeader: '日志', linkHeader: '详情页', rows: request.logDetails },
+    },
+    workspace: {
+      segments: ['analyze', request.app, request.errorCode],
+      title: `日志分析 · ${request.app} · ${request.errorCode}`,
+    },
+    prompt: request.prompt,
+  }
+}
+
+/**
+ * HTTP answer of one launch result.
+ * @param result - what the service answered.
+ * @returns status and body.
+ */
+export function analyzeResponseOf(result: TopicLaunchResult): AnalyzeResponse {
+  if (result.ok) return { status: 202, body: { ok: true, chatId: result.chatId, messageId: result.messageId } }
+  switch (result.code) {
+    case 'not-connected': return refused(503, result.message)
+    case 'forbidden-chat': return refused(403, result.message)
+    case 'key-conflict': return refused(409, 'Idempotency-Key 已被内容不同的请求使用')
+    case 'send-failed': return refused(502, result.message)
+    // The request passed this plugin's own validation, so a refused spec is a
+    // disagreement between the two plugins, not a client error.
+    case 'invalid': return refused(500, `分析请求处理失败：${result.message}`)
+    default: return refused(500, `分析请求处理失败：${String((result as { message?: unknown }).message)}`)
+  }
+}
+
+/**
+ * Start the analysis topic of one validated request.
+ * @param topics - the `feishuTopics` service.
+ * @param request - the validated request.
+ * @param idempotencyKey - the request's `Idempotency-Key`.
+ * @returns the HTTP answer.
+ */
+export async function launchAnalysis(topics: FeishuTopicService, request: AnalyzeRequest, idempotencyKey: string): Promise<AnalyzeResponse> {
+  return analyzeResponseOf(await topics.launch(analyzeTopicSpec(request, idempotencyKey)))
+}
+
+function refused(status: number, error: string): AnalyzeResponse {
+  return { status, body: { ok: false, error } }
+}

package/src/client/page.tsx

@@ -1,13 +1,13 @@
 /**
- * 左侧栏「观象」主区页面：应用仓库、访问令牌、日志下载、高级（含 SKILL 改进）四个分页，共用
- * 一份草稿和底部保存条；令牌值不进草稿，单独存入 DSH 凭据库。仓库拉取中时
- * 每 2 秒刷新状态。
+ * 左侧栏「观象」主区页面：应用仓库、访问令牌、日志下载、分析接口、高级（含 SKILL 改进）五个
+ * 分页，共用一份草稿和底部保存条；令牌值不进草稿，单独存入 DSH 凭据库。
+ * 仓库拉取中时每 2 秒刷新状态。
  *
  * @module dsh-guanxiang/client/page
  */
 
 import { useCallback, useEffect, useMemo, useState } from 'react'
-import type { EditableKey, EditableSettings, GitCredentialSpec, RepoSpec, RepoStatusWire, StateWire, TokenStatusWire } from '../settings/contract.ts'
+import type { AnalyzeWire, EditableKey, EditableSettings, GitCredentialSpec, RepoSpec, RepoStatusWire, StateWire, TokenStatusWire } from '../settings/contract.ts'
 import { clearToken, fetchState, messageOf, resetSettings, saveSettings, saveToken, syncRepos } from './api.ts'
 
 /** Sidebar label and page title. */
@@ -17,12 +17,13 @@ const KB = 1024
 const MB = 1024 * 1024
 const MINUTE = 60 * 1000
 
-type TabId = 'repos' | 'tokens' | 'download' | 'advanced'
+type TabId = 'repos' | 'tokens' | 'download' | 'analyze' | 'advanced'
 
 const TABS: readonly { id: TabId; label: string }[] = [
   { id: 'repos', label: '应用仓库' },
   { id: 'tokens', label: '访问令牌' },
   { id: 'download', label: '日志下载' },
+  { id: 'analyze', label: '分析接口' },
   { id: 'advanced', label: '高级' },
 ]
 
@@ -40,6 +41,7 @@ interface Draft {
   skillUpdatesEnabled: boolean
   skillMaxFiles: string
   skillMaxKb: string
+  analyzeEnabled: boolean
 }
 
 function trimNumber(value: number): string {
@@ -60,6 +62,7 @@ function toDraft(settings: EditableSettings): Draft {
     skillUpdatesEnabled: settings.skillUpdates.enabled,
     skillMaxFiles: String(settings.skillUpdates.maxFiles),
     skillMaxKb: trimNumber(settings.skillUpdates.maxFileBytes / KB),
+    analyzeEnabled: settings.analyze.enabled,
   }
 }
 
@@ -96,6 +99,7 @@ function fromDraft(draft: Draft): EditableSettings {
       maxFiles,
       maxFileBytes: Math.round(positive(draft.skillMaxKb, '提议单文件大小上限') * KB),
     },
+    analyze: { enabled: draft.analyzeEnabled },
   }
 }
 
@@ -254,6 +258,18 @@ export function GuanxiangPanel(): JSX.Element {
             />
           : null}
         {tab === 'download' ? <DownloadTab draft={draft} setDraft={setDraft} overridden={state.overridden} /> : null}
+        {tab === 'analyze'
+          ? <AnalyzeTab
+              draft={draft}
+              setDraft={setDraft}
+              analyze={state.analyze}
+              credentialsAvailable={state.credentials.available}
+              overridden={state.overridden}
+              busy={busy}
+              onSave={async value => await run(() => saveToken(state.analyze.tokenEnv, value), '已保存分析接口令牌，下一个请求起生效', false) !== undefined}
+              onClear={() => { void run(() => clearToken(state.analyze.tokenEnv), '已清除面板保存的分析接口令牌', false) }}
+            />
+          : null}
         {tab === 'advanced' ? <AdvancedTab draft={draft} setDraft={setDraft} overridden={state.overridden} busy={busy} onReset={() => { void run(resetSettings, '已恢复为 cordis.yml 中的配置', true) }} /> : null}
       </div>
       {notice === undefined ? null : <div className={`gx__notice gx__notice--${notice.kind}`}>{notice.text}</div>}
@@ -482,6 +498,74 @@ function DownloadTab({ draft, setDraft, overridden }: TabProps & { overridden: r
   )
 }
 
+const TOPICS_STATUS: Readonly<Record<AnalyzeWire['topics'], { pill: string; text: string }>> = {
+  ready: { pill: 'gx__pill--ok', text: '飞书渠道就绪' },
+  missing: { pill: 'gx__pill--bad', text: '未找到飞书渠道' },
+  incompatible: { pill: 'gx__pill--bad', text: '飞书渠道版本不兼容' },
+}
+
+function AnalyzeTab({ draft, setDraft, analyze, credentialsAvailable, overridden, busy, onSave, onClear }: TabProps & {
+  analyze: AnalyzeWire
+  credentialsAvailable: boolean
+  overridden: readonly EditableKey[]
+  busy: boolean
+  onSave: (value: string) => Promise<boolean>
+  onClear: () => void
+}): JSX.Element {
+  const [value, setValue] = useState('')
+  const token = analyze.token
+  const save = (): void => {
+    const trimmed = value.trim()
+    if (trimmed === '' || busy) return
+    void onSave(trimmed).then((ok) => { if (ok) setValue('') })
+  }
+  const topics = TOPICS_STATUS[analyze.topics]
+  const endpoint = new URL(analyze.route.slice(1), document.baseURI).href
+  return (
+    <>
+      <section className="gx__sec">
+        <h2 className="gx__secTitle">日志平台分析接口</h2>
+        <div className="gx__list">
+          <div className="gx__row">
+            <div className="gx__rowText">
+              <div className="gx__rowLabel">开启接口 <Overridden keys={overridden} name="analyze" /><span className={`gx__pill ${topics.pill}`}><span className="gx__dot" />{topics.text}</span></div>
+              <div className="gx__rowSummary">日志平台调用接口后，观象经飞书渠道（dsh-channels 0.8 及以上）在目标群发出分析卡片，并在卡片下的话题里开始分析；群内成员都可以在话题里继续追问。关闭时接口回复 404。</div>
+              {analyze.topics === 'ready' ? null : <div className="gx__rowError">{analyze.topics === 'missing' ? '接口需要 dsh-channels 0.8 及以上版本并已加载；dsh-channels 0.7 自带同名接口，升级前由它提供。' : '请把观象与 dsh-channels 升级到相互兼容的版本。'}</div>}
+            </div>
+            <div className="gx__rowCtl"><input type="checkbox" className="gx__check" aria-label="开启分析接口" checked={draft.analyzeEnabled} onChange={(event) => { setDraft({ ...draft, analyzeEnabled: event.target.checked }) }} /></div>
+          </div>
+          <div className="gx__row gx__row--top">
+            <div className="gx__rowText">
+              <div className="gx__rowLabel">访问令牌 <span className="gx__tag gx__mono">{analyze.tokenEnv}</span>{credentialsAvailable ? tokenPill(token) : null}</div>
+              <div className="gx__rowSummary">日志平台以 <span className="gx__mono">Authorization: Bearer &lt;令牌&gt;</span> 调用接口。令牌未设置时接口回复 503。</div>
+              {credentialsAvailable ? null : <div className="gx__rowError">当前 DSH 组合没有加载凭据服务（@deepseek-ai/dsh-credentials-local），无法保存或读取令牌。</div>}
+              {token?.error === undefined ? null : <div className="gx__rowError">{token.error}</div>}
+              {token !== undefined && token.writable
+                ? (
+                    <div className="gx__addRow gx__addRow--flush">
+                      <input className="gx__input gx__mono" type="password" autoComplete="new-password" spellCheck={false} placeholder={token.configured ? '输入新令牌以替换' : '粘贴令牌'} value={value} onChange={(event) => { setValue(event.target.value) }} onKeyDown={(event) => { if (event.key === 'Enter') save() }} />
+                      <button type="button" className="gx__btn" disabled={busy || value.trim() === ''} onClick={save}>保存令牌</button>
+                      {token.configured && token.source === 'file' ? <button type="button" className="gx__btn gx__btn--ghost" disabled={busy} onClick={onClear}>清除</button> : null}
+                    </div>
+                  )
+                : null}
+            </div>
+          </div>
+        </div>
+      </section>
+      <section className="gx__sec">
+        <h2 className="gx__secTitle">调用方式</h2>
+        <div className="gx__list">
+          <div className="gx__row"><div className="gx__rowText"><div className="gx__rowLabel">地址</div><div className="gx__rowSummary gx__mono">POST {endpoint}</div></div></div>
+          <div className="gx__row"><div className="gx__rowText"><div className="gx__rowLabel">请求头</div><div className="gx__rowSummary gx__mono">Authorization: Bearer &lt;令牌&gt; · Idempotency-Key: &lt;1-200 个可见 ASCII 字符&gt; · Content-Type: application/json</div></div></div>
+          <div className="gx__row"><div className="gx__rowText"><div className="gx__rowLabel">请求体</div><div className="gx__rowSummary gx__mono">requesterUserId, triggeredAt, app, errorCode, logDetails[{'{'}name, url{'}'}], chatId, prompt</div></div></div>
+          <div className="gx__row"><div className="gx__rowText"><div className="gx__rowLabel">响应</div><div className="gx__rowSummary">202 已发出分析卡片（同一 Idempotency-Key 重试返回同一张卡片）；400/401/404/405/409/413/415 请求问题；403 目标群未授权；502 卡片发送失败；503 飞书未连接或令牌未设置。字段说明见观象 README。</div></div></div>
+        </div>
+      </section>
+    </>
+  )
+}
+
 function AdvancedTab({ draft, setDraft, overridden, busy, onReset }: TabProps & { overridden: readonly EditableKey[]; busy: boolean; onReset: () => void }): JSX.Element {
   return (
     <>

package/src/config.ts

@@ -86,6 +86,10 @@ const skillUpdatesSchema = z.object({
   maxFileBytes: z.number().int().min(1).max(16 * 1024 * 1024).default(256 * 1024),
 }).strict()
 
+const analyzeSchema = z.object({
+  enabled: z.boolean().default(false),
+}).strict()
+
 const authorSchema = z.object({
   name: z.string().trim().min(1, '提交作者名不能为空').refine(value => !/[<>\n]/.test(value), '提交作者名不能包含 < > 或换行'),
   email: z.string().trim().min(1, '提交作者邮箱不能为空').refine(value => !/[<>\s]/.test(value), '提交作者邮箱不能包含 < > 或空白'),
@@ -113,6 +117,7 @@ export const editableFields = {
   dispatchTimeoutMs: durationMs(1000),
   download: downloadSchema,
   skillUpdates: skillUpdatesSchema,
+  analyze: analyzeSchema,
 }
 
 const configSchema = z.object({
@@ -125,6 +130,12 @@ const configSchema = z.object({
   dispatchTimeoutMs: editableFields.dispatchTimeoutMs.default(30 * 60 * 1000),
   download: downloadSchema.prefault({}),
   skillUpdates: skillUpdatesSchema.prefault({}),
+  analyze: analyzeSchema.prefault({}),
+  /**
+   * Credential reference (environment-variable name) whose value is the
+   * analyze API's bearer token.
+   */
+  analyzeTokenRef: z.string().trim().regex(TOKEN_ENV_PATTERN, '令牌名称只能包含字母、数字和下划线，且不能以数字开头').default('GUANXIANG_ANALYZE_TOKEN'),
   /**
    * Author and committer of SKILL improvement commits; omitted uses the git
    * identity configured on the host (`user.name` / `user.email`).
@@ -163,6 +174,7 @@ export const overlaySchema = z.object({
   dispatchTimeoutMs: editableFields.dispatchTimeoutMs.optional(),
   download: downloadSchema.optional(),
   skillUpdates: skillUpdatesSchema.optional(),
+  analyze: analyzeSchema.optional(),
 }).strict()
 
 /** Validated panel overlay. */
@@ -247,6 +259,7 @@ export function defaultsOf(config: GuanxiangConfig, env: NodeJS.ProcessEnv = pro
     dispatchTimeoutMs: config.dispatchTimeoutMs,
     download: { ...config.download, allowedHosts: [...config.download.allowedHosts] },
     skillUpdates: { ...config.skillUpdates },
+    analyze: { ...config.analyze },
   }
 }
 
@@ -267,5 +280,6 @@ export function applyOverlay(defaults: EditableSettings, overlay: SettingsOverla
     dispatchTimeoutMs: overlay.dispatchTimeoutMs ?? defaults.dispatchTimeoutMs,
     download: overlay.download ?? defaults.download,
     skillUpdates: overlay.skillUpdates ?? defaults.skillUpdates,
+    analyze: overlay.analyze ?? defaults.analyze,
   }
 }