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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modesto_ma/dsh-guanxiang",
-  "version": "0.1.0",
+  "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 } }
+}