@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/prompts/registry.ts

@@ -0,0 +1,248 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { prisma } from "@allbluecn/database"
+import {
+  interpolateTemplate,
+  UnknownPromptVariableError as KernelUnknownPromptVariableError,
+} from "@allbluecn/kernel"
+import { PROMPT_DEFINITIONS } from "./builtin"
+import type { PromptDefinition, PromptSection, PromptVariableDef } from "./types"
+
+// 类型契约定义在 ./types（不带 prisma），这里再导出以保持既有导入路径可用
+export type { PromptSection, PromptVariableDef, PromptDefinition } from "./types"
+
+export interface ResolvePromptOptions {
+  userId?: string
+  workspaceName?: string
+}
+
+export class UnknownPromptVariableError extends Error {
+  readonly key: string
+  readonly variable: string
+
+  constructor(key: string, variable: string) {
+    super(`Unknown prompt variable "${variable}" in prompt "${key}"`)
+    this.name = "UnknownPromptVariableError"
+    this.key = key
+    this.variable = variable
+  }
+}
+
+export class PromptKeyNotFoundError extends Error {
+  readonly key: string
+
+  constructor(key: string) {
+    super(`Prompt key "${key}" is not registered`)
+    this.name = "PromptKeyNotFoundError"
+    this.key = key
+  }
+}
+
+const builtins = new Map(
+  PROMPT_DEFINITIONS.map((definition) => [definition.key, definition]),
+)
+const CACHE_TTL_MS = 60_000
+const CACHE_CAPACITY = 64
+const cache = new Map<string, { at: number; sections: PromptSection[] }>()
+
+export function definePromptKey(def: PromptDefinition): PromptDefinition {
+  builtins.set(def.key, def)
+  return def
+}
+
+export function getBuiltinPrompt(key: string): PromptDefinition | undefined {
+  return builtins.get(key)
+}
+
+export function listBuiltinPrompts(): PromptDefinition[] {
+  return [...builtins.values()]
+}
+
+export function invalidatePromptCache(key?: string): void {
+  if (key === undefined) {
+    cache.clear()
+    return
+  }
+  cache.delete(key)
+}
+
+function readCache(key: string): PromptSection[] | undefined {
+  const entry = cache.get(key)
+  if (!entry) return undefined
+  if (Date.now() - entry.at >= CACHE_TTL_MS) {
+    cache.delete(key)
+    return undefined
+  }
+  cache.delete(key)
+  cache.set(key, entry)
+  return entry.sections
+}
+
+function writeCache(key: string, sections: PromptSection[]): void {
+  cache.delete(key)
+  cache.set(key, { at: Date.now(), sections })
+  while (cache.size > CACHE_CAPACITY) {
+    const oldest = cache.keys().next()
+    if (oldest.done) break
+    cache.delete(oldest.value)
+  }
+}
+
+function isSection(value: unknown): value is PromptSection {
+  if (typeof value !== "object" || value === null) return false
+  const s = value as Record<string, unknown>
+  return (
+    typeof s.id === "string" &&
+    s.id.length > 0 &&
+    typeof s.order === "number" &&
+    typeof s.template === "string" &&
+    s.template.trim().length > 0
+  )
+}
+
+function parseSections(key: string, raw: unknown): PromptSection[] | undefined {
+  if (!Array.isArray(raw)) return undefined
+  const sections = raw.filter(isSection)
+  const dropped = raw.length - sections.length
+  if (dropped > 0) {
+    console.warn(
+      `[AI] prompt "${key}" sections 有 ${dropped} 行非法（形状错误或 template 空白）被丢弃，保留 ${sections.length} 行`,
+    )
+  }
+  return sections.length > 0 ? sections : undefined
+}
+
+function formatNow(now = new Date()): string {
+  const y = now.getFullYear()
+  const m = now.getMonth() + 1
+  const d = now.getDate()
+  const pad = (n: number) => String(n).padStart(2, "0")
+  return `${y}-${pad(m)}-${pad(d)} ${y}年${m}月${d}日`
+}
+
+async function resolveBuiltinVars(
+  opts?: ResolvePromptOptions,
+): Promise<Record<string, string>> {
+  const vars: Record<string, string> = {
+    now: formatNow(),
+    locale: "zh",
+  }
+  if (opts?.workspaceName) vars.workspaceName = opts.workspaceName
+  if (!opts?.userId) return vars
+
+  // 未提供 userId（调用方契约错误）不注入 userName：模板引用则严格抛错，
+  // 避免静默发出「用户」兜底文案。提供了 userId 但用户不存在或 DB 故障
+  // （数据层问题）则降级「用户」，不阻断 AI 功能。
+  vars.userName = "用户"
+  try {
+    const user = await prisma.user.findUnique({
+      where: { id: opts.userId },
+      select: { username: true },
+    })
+    if (user?.username) vars.userName = user.username
+  } catch (e) {
+    console.warn(
+      `[AI] prompt userName lookup failed for userId ${opts.userId}:`,
+      e instanceof Error ? e.message : "unknown",
+    )
+  }
+  return vars
+}
+
+async function loadSections(key: string): Promise<PromptSection[]> {
+  const row = await prisma.systemPromptTemplate.findUnique({
+    where: { key },
+    select: { isActive: true, sections: true },
+  })
+  const fromDb = row?.isActive ? parseSections(key, row.sections) : undefined
+  if (fromDb) return fromDb
+
+  // DB 行缺失、已停用或 sections 全为空白 → 一律回落代码内置默认，
+  // 保证运行时永远拿得到非空提示词（admin 只是查看与二次编辑的入口）。
+  const builtin = builtins.get(key)?.sections
+  if (builtin && builtin.length > 0) return builtin
+
+  throw new PromptKeyNotFoundError(key)
+}
+
+// 插值规则（`{{var}}` 语法与变量名校验）的单一来源是 kernel 的 interpolateTemplate，
+// web 运行时与 admin preview 共用同一实现；这里只把 kernel 的错误补上 prompt key
+// 上下文再抛出，保持本模块既有的 UnknownPromptVariableError 契约。
+function interpolateSection(
+  section: PromptSection,
+  vars: Map<string, string>,
+  key: string,
+): string {
+  try {
+    return interpolateTemplate(section.template, Object.fromEntries(vars))
+  } catch (error) {
+    if (error instanceof KernelUnknownPromptVariableError) {
+      throw new UnknownPromptVariableError(key, error.variable)
+    }
+    throw error
+  }
+}
+
+export interface ResolvedPromptSection {
+  id: string
+  order: number
+  text: string
+}
+
+async function resolveSections(
+  key: string,
+  vars: Record<string, string>,
+  opts?: ResolvePromptOptions,
+): Promise<ResolvedPromptSection[]> {
+  let sections = readCache(key)
+  if (!sections) {
+    sections = await loadSections(key)
+    writeCache(key, sections)
+  }
+
+  const merged = new Map<string, string>()
+  for (const [name, value] of Object.entries(await resolveBuiltinVars(opts))) {
+    merged.set(name, value)
+  }
+  for (const [name, value] of Object.entries(vars)) merged.set(name, value)
+
+  return sections
+    .slice()
+    .sort((a, b) => a.order - b.order)
+    .map((section) => ({
+      id: section.id,
+      order: section.order,
+      text: interpolateSection(section, merged, key),
+    }))
+}
+
+export async function resolveSystemPromptSections(
+  key: string,
+  vars: Record<string, string>,
+  opts?: ResolvePromptOptions,
+): Promise<ResolvedPromptSection[]> {
+  return resolveSections(key, vars, opts)
+}
+
+export async function resolveSystemPrompt(
+  key: string,
+  vars: Record<string, string>,
+  opts?: ResolvePromptOptions,
+): Promise<string[]> {
+  return (await resolveSections(key, vars, opts)).map((section) => section.text)
+}

package/src/server/ai-gateway/prompts/seed.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import "./builtin"
+import { listBuiltinPrompts } from "./registry"
+import { prisma, type Prisma } from "@allbluecn/database"
+
+/** Prisma Json 字段不接受强类型数组（缺 index signature），统一 cast */
+function toJson(value: unknown): Prisma.InputJsonValue {
+  return value as unknown as Prisma.InputJsonValue
+}
+
+let seeded = false
+
+/** 幂等 seed：仅当 DB 无此 key 时插入内置（不覆盖用户已编辑模板）。进程内只跑一次。 */
+export async function ensurePromptSeeded(): Promise<void> {
+  if (seeded) return
+  const existing = await prisma.systemPromptTemplate.findMany({
+    select: { key: true },
+  })
+  const existingKeys = new Set(existing.map((r) => r.key))
+  const missing = listBuiltinPrompts().filter((p) => !existingKeys.has(p.key))
+  if (missing.length > 0) {
+    await prisma.systemPromptTemplate.createMany({
+      data: missing.map((p) => ({
+        key: p.key,
+        name: p.name,
+        description: p.description ?? null,
+        sections: toJson(p.sections),
+        variables: toJson(p.variables),
+        isProtected: p.isProtected,
+      })),
+    })
+  }
+  seeded = true
+}
+
+export function resetPromptSeedForTest(): void {
+  seeded = false
+}

package/src/server/ai-gateway/prompts/types.ts

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 提示词定义的类型契约。独立成文件且不依赖 prisma，是因为内置提示词正文
+// （builtin.ts）必须能被 admin 端直接 import 作为「默认值」来源——registry.ts
+// 带 prisma，若把类型放在那里，builtin.ts 就会把 prisma 一起拖进 admin。
+
+export interface PromptSection {
+  id: string
+  order: number
+  template: string
+}
+
+export interface PromptVariableDef {
+  name: string
+  description: string
+}
+
+export interface PromptDefinition {
+  key: string
+  name: string
+  description?: string
+  sections: PromptSection[]
+  variables: PromptVariableDef[]
+  isProtected: boolean
+}

package/src/server/ai-gateway/rerank.ts

@@ -17,6 +17,7 @@
 
 import { rerank } from "@tanstack/ai"
 import { createOpenRouterRerank } from "@tanstack/ai-openrouter"
+import { envApiKey, ENV_OPENROUTER_API_KEY } from "./env-key"
 
 export const RERANK_MODEL = "cohere/rerank-v3.5" as const
 
@@ -40,7 +41,7 @@ export async function rerankCandidates(
   limit: number,
   opts?: { apiKey?: string }
 ): Promise<RerankCandidate[] | null> {
-  const apiKey = opts?.apiKey || process.env.OPENROUTER_API_KEY
+  const apiKey = opts?.apiKey || envApiKey(ENV_OPENROUTER_API_KEY)
   if (!apiKey || candidates.length <= 1) return null
   // 仅用于短路判断：非空文档少于 2 篇时 rerank 无意义；
   // documents 仍传全量 candidates（含空串占位），保证返回 ranking.index 与 candidates 对齐。

package/src/server/ai-gateway/runs/agent-runtime.ts

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import { prisma } from "@allbluecn/database"
+import { runChat, runChatStream, runChatWithModel } from "../adapter"
+import type { SchemaInput } from "@tanstack/ai"
+import { resolveSystemPrompt } from "../prompts/registry"
+import { isAgentToolKey, type AgentToolKey } from "../tools/select"
+import type { UnifiedAiStream } from "../unified-router"
+import { BIZ_KEY_TO_PROMPT, type BizAgentKey } from "./biz-keys"
+
+export interface ResolvedAgent {
+  agentId?: string
+  persona?: string
+  model?: string
+  temperature?: number
+  allowedTools?: AgentToolKey[]
+  knowledgeBaseIds?: string[]
+}
+
+export interface RunAsAgentOptions {
+  userId: string
+  model?: string
+  temperature?: number
+  promptVars?: Record<string, string>
+  workspaceName?: string
+  workspaceId?: string
+  /** 子 agent 工具白名单（从 ResolvedAgent.allowedTools 透传；空 = 不限，由调用方 selectTools 过滤） */
+  allowedTools?: AgentToolKey[]
+  /** 父 runId，用于委派审计链（delegate_task 等写元数据用） */
+  parentRunId?: string
+  /** 顶层 outputSchema：请求结构化输出（如标签建议 JSON），替代 parseLabelSuggestions 的 JSON.parse 路径 */
+  outputSchema?: SchemaInput
+}
+
+export type ChatMessage = { role: "user" | "assistant" | "tool"; content: string }
+
+const AGENT_SELECT = {
+  id: true,
+  systemPrompt: true,
+  model: true,
+  temperature: true,
+  allowedTools: true,
+  knowledgeBaseIds: true,
+} as const
+
+type AgentRow = {
+  id: string
+  systemPrompt: string
+  model: string | null
+  temperature: number | null
+  allowedTools: unknown
+  knowledgeBaseIds: unknown
+}
+
+function toAgentToolKeys(raw: unknown): AgentToolKey[] {
+  if (!Array.isArray(raw)) return []
+  return raw.filter(isAgentToolKey)
+}
+
+function toStringArray(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return []
+  return raw.filter((v): v is string => typeof v === "string")
+}
+
+function mapAgent(row: AgentRow): ResolvedAgent {
+  const allowedTools = toAgentToolKeys(row.allowedTools)
+  const knowledgeBaseIds = toStringArray(row.knowledgeBaseIds)
+  return {
+    agentId: row.id,
+    persona: row.systemPrompt || undefined,
+    model: row.model || undefined,
+    temperature: row.temperature ?? undefined,
+    ...(allowedTools.length > 0 && { allowedTools }),
+    ...(knowledgeBaseIds.length > 0 && { knowledgeBaseIds }),
+  }
+}
+
+export async function resolveAgentFor(
+  bizKey: BizAgentKey,
+  userId: string,
+): Promise<ResolvedAgent | null> {
+  const binding = await prisma.businessAgentBinding.findFirst({
+    where: { userId, bizKey, agent: { isDeleted: false } },
+    select: { agent: { select: AGENT_SELECT } },
+  })
+  if (binding?.agent) return mapAgent(binding.agent)
+
+  const defaultAgent = await prisma.userAgent.findFirst({
+    where: { userId, isDefault: true, isDeleted: false },
+    select: AGENT_SELECT,
+  })
+  if (defaultAgent) return mapAgent(defaultAgent)
+
+  return null
+}
+
+async function assemblePrompts(
+  bizKey: BizAgentKey,
+  agent: ResolvedAgent | null,
+  opts: RunAsAgentOptions,
+): Promise<string[]> {
+  const base = await resolveSystemPrompt(
+    BIZ_KEY_TO_PROMPT[bizKey],
+    opts.promptVars ?? {},
+    { userId: opts.userId, workspaceName: opts.workspaceName },
+  )
+  return agent?.persona ? [agent.persona, ...base] : base
+}
+
+export async function runChatAsAgent(
+  bizKey: BizAgentKey,
+  messages: ChatMessage[],
+  opts: RunAsAgentOptions,
+): Promise<string> {
+  const agent = await resolveAgentFor(bizKey, opts.userId)
+  const systemPrompts = await assemblePrompts(bizKey, agent, opts)
+  const model = agent?.model ?? opts.model
+  const temperature = agent?.temperature ?? opts.temperature
+
+  if (model) {
+    return runChatWithModel(messages, {
+      systemPrompts,
+      userId: opts.userId,
+      model,
+      workspaceId: opts.workspaceId,
+      modelOptions: temperature != null ? { temperature } : undefined,
+      allowedTools: agent?.allowedTools,
+      parentRunId: opts.parentRunId,
+      outputSchema: opts.outputSchema,
+    })
+  }
+
+  return runChat(messages, {
+    systemPrompts,
+    userId: opts.userId,
+    workspaceId: opts.workspaceId,
+    modelOptions: temperature != null ? { temperature } : undefined,
+    allowedTools: agent?.allowedTools,
+    parentRunId: opts.parentRunId,
+    outputSchema: opts.outputSchema,
+  })
+}
+
+export async function runChatStreamAsAgent(
+  bizKey: BizAgentKey,
+  messages: ChatMessage[],
+  opts: RunAsAgentOptions,
+): Promise<UnifiedAiStream> {
+  const agent = await resolveAgentFor(bizKey, opts.userId)
+  const systemPrompts = await assemblePrompts(bizKey, agent, opts)
+  const model = agent?.model ?? opts.model
+
+  return runChatStream(messages, {
+    systemPrompts,
+    userId: opts.userId,
+    workspaceId: opts.workspaceId,
+    model,
+    allowedTools: agent?.allowedTools,
+    parentRunId: opts.parentRunId,
+  })
+}

package/src/server/ai-gateway/runs/biz-keys.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+export const BIZ_AGENT_KEYS = [
+  "harness.default",
+  "story.pm",
+  "story.split",
+  "prd.annotation",
+  "prd.prototype",
+  "translation.run",
+  "knowledge.curator",
+  "label.suggest",
+  "code.workspace",
+] as const
+
+export type BizAgentKey = (typeof BIZ_AGENT_KEYS)[number]
+
+export const BIZ_KEY_LABELS: Record<BizAgentKey, string> = {
+  "harness.default": "Harness 对话",
+  "story.pm": "需求生成（PM）",
+  "story.split": "需求拆解",
+  "prd.annotation": "PRD 注释填充",
+  "prd.prototype": "PRD 原型生成",
+  "translation.run": "翻译",
+  "knowledge.curator": "知识库治理",
+  "label.suggest": "标签推荐",
+  "code.workspace": "代码工作区",
+}
+
+export const BIZ_KEY_TO_PROMPT: Record<BizAgentKey, string> = {
+  "harness.default": "chat.default",
+  "story.pm": "story.generate",
+  "story.split": "story.generate",
+  "prd.annotation": "prd.fill-annotation",
+  "prd.prototype": "prd.prototype",
+  "translation.run": "translation.run",
+  "knowledge.curator": "chat.default",
+  "label.suggest": "story.label-suggest",
+  "code.workspace": "code.workspace",
+}

package/src/server/{serverFns/agents → ai-gateway/runs}/resolve-overrides.ts

@@ -16,14 +16,8 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 import { prisma } from "@allbluecn/database"
-import { AGENT_TOOL_KEYS } from "@/server/ai-gateway"
-import type { AgentToolKey, ChatRequestOverrides } from "@/server/ai-gateway"
-
-const VALID_TOOL_KEYS = new Set(AGENT_TOOL_KEYS)
-
-function isAgentToolKey(v: unknown): v is AgentToolKey {
-  return typeof v === "string" && VALID_TOOL_KEYS.has(v as AgentToolKey)
-}
+import { isAgentToolKey } from "../tools/select"
+import type { ChatRequestOverrides } from "@/server/ai-gateway"
 
 export async function resolveOverrides(
   userId: string,