@allbluecn/web-app 0.12.0 → 0.12.2

package/src/server/ai-gateway/tools/create-pr.ts

@@ -0,0 +1,296 @@
+// 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 { toolDefinition } from "@tanstack/ai"
+import { z } from "zod"
+import type { AppContext } from "../types"
+import { decryptApiKey } from "@/plugins/core/server/api-key-cipher"
+import { assertFetchableUrl } from "@/server/fetch-guard"
+
+/** secrets 模式：匹配 .env / .env.* / secrets 等文件路径，防提交敏感信息 */
+const SECRET_PATTERNS = [
+  /\.env$/,
+  /\.env\./,
+  /\.env\.local$/,
+  /\.env\.\w+$/,
+  /secrets?\./,
+  /\.pem$/,
+  /\.key$/,
+  /\.credentials$/,
+]
+
+function containsSecrets(files: string[]): string[] {
+  return files.filter((f) =>
+    SECRET_PATTERNS.some((re) => re.test(f)),
+  )
+}
+
+export const createPullRequestDef = toolDefinition({
+  name: "create_pull_request",
+  description:
+    "把沙箱工作区变更提交为新分支并创建 Pull Request（write 级，需逐次审批）。" +
+    "注意：变更集含 .env* / secrets* 等敏感文件时会自动拒绝并返回文件清单。",
+  needsApproval: true,
+  inputSchema: z.object({
+    title: z.string().min(1).max(200).describe("PR 标题（必填）"),
+    body: z.string().max(5000).optional().describe("PR 描述（可选）"),
+    branch: z.string().max(100).optional().describe("目标分支名（默认自动派生）"),
+    files: z
+      .array(
+        z.object({
+          path: z.string().describe("相对路径，相对于仓库根目录"),
+          content: z.string().describe("文件内容的 base64 编码"),
+        }),
+      )
+      .default([])
+      .describe(
+        "要提交的文件列表（沙箱完成后从 snapshots.artifacts 获取；未提供时工具会先创建空分支再报错，提示模型补充文件内容）",
+      ),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+    prUrl: z.string().optional().describe("PR URL（成功时）"),
+    branch: z.string().describe("实际创建的分支名"),
+    message: z.string().optional(),
+  }),
+})
+
+export const createPullRequestTool = createPullRequestDef.server<AppContext>(
+  async ({ title, body, branch, files }, { context: appCtx }) => {
+    const filesList = files ?? []
+    // desktop 分支：无 PR 概念，提示用户在编辑器查看 + 打开目录
+    if (process.env.DEPLOY_TARGET === "desktop") {
+      return {
+        success: false as const,
+        message: "desktop 版请直接在编辑器查看变更，PR 功能仅 SaaS 可用",
+        branch: "desktop-mode",
+      }
+    }
+
+    // 校验 workspaceContext 是否已注入（由 harness 路由选中仓库后注入）
+    if (!appCtx.workspaceContext || appCtx.workspaceContext.type !== "github") {
+      return {
+        success: false as const,
+        message: "未配置代码工作区，请先在 Harness 侧边栏选择 GitHub 仓库",
+        branch: "",
+      }
+    }
+
+    const { owner, repo, defaultBranch } = appCtx.workspaceContext
+
+    // 分支策略：恒新分支，不动默认分支
+    const targetBranch = branch ?? `code-patch-${Date.now()}`
+
+    // 读取 GitHub token（优先 AiProviderConfig 持久化，其次 Account session 级）
+    let token: string | null = null
+    try {
+      const providerConfig = await appCtx.db.aiProviderConfig.findFirst({
+        where: { userId: appCtx.userId, providerId: "github" },
+        select: { apiKey: true },
+      })
+      if (providerConfig?.apiKey) {
+        token = decryptApiKey(providerConfig.apiKey)
+      }
+    } catch {
+      // token 解密失败，降级为 null
+    }
+    if (!token) {
+      try {
+        const account = await appCtx.db.account.findFirst({
+          where: { userId: appCtx.userId, provider: "github" },
+          select: { access_token: true },
+        })
+        token = account?.access_token ?? null
+      } catch {
+        // account 查询失败
+      }
+    }
+    if (!token) {
+      return {
+        success: false as const,
+        message: "未配置 GitHub 访问令牌，请先在 Harness 工作区选择器中连接 GitHub 账户",
+        branch: targetBranch,
+      }
+    }
+
+    // fetch-guard：GitHub API URL 必须过白名单，防止 owner/repo 参数注入 SSRF
+    const githubBase = assertFetchableUrl(
+      `https://api.github.com/repos/${owner}/${repo}`,
+      { allowedHosts: ["api.github.com"] },
+    ).origin
+
+    const apiHeaders = {
+      Authorization: `Bearer ${token}`,
+      "User-Agent": "AllBlue",
+      Accept: "application/vnd.github.v3+json",
+    }
+
+    // 获取默认分支的 tip commit SHA
+    const defaultBranchRefResp = await fetch(
+      `${githubBase}/git/refs/heads/${defaultBranch}`,
+      { headers: apiHeaders },
+    )
+    if (!defaultBranchRefResp.ok) {
+      return {
+        success: false as const,
+        message: `无法获取默认分支 ${defaultBranch} 的引用，请确认仓库名称和分支名正确`,
+        branch: targetBranch,
+      }
+    }
+    const defaultBranchRef = (await defaultBranchRefResp.json()) as { object?: { sha?: string } }
+    const baseSha = defaultBranchRef?.object?.sha
+    if (!baseSha) {
+      return {
+        success: false as const,
+        message: `无法解析默认分支 ${defaultBranch} 的 SHA，请确认仓库存在且可访问`,
+        branch: targetBranch,
+      }
+    }
+
+    if (filesList.length === 0) {
+      return {
+        success: false as const,
+        message: "未提供要提交的文件内容。请先在沙箱中完成代码修改，然后通过 snapshots.artifacts 获取变更文件后再调用本工具",
+        branch: targetBranch,
+      }
+    }
+
+    // secrets 阻断：文件路径含 .env* / secrets* 等敏感模式时直接拒绝
+    const secrets = containsSecrets(filesList.map((f) => f.path))
+    if (secrets.length > 0) {
+      return {
+        success: false as const,
+        message: `变更集包含敏感文件，已阻断：${secrets.join(", ")}`,
+        branch: targetBranch,
+      }
+    }
+
+    // 1. 为每个文件创建 git blob
+    const blobResps = await Promise.all(
+      filesList.map(async (file) => {
+        const resp = await fetch(`${githubBase}/git/blobs`, {
+          method: "POST",
+          headers: apiHeaders,
+          body: JSON.stringify({ content: file.content, encoding: "utf-8" }),
+        })
+        if (!resp.ok) {
+          const err = (await resp.json()) as { message?: string }
+          throw new Error(err?.message ?? `创建 blob 失败（${resp.status}）`)
+        }
+        return (await resp.json()) as { sha: string; size: number }
+      }),
+    )
+    const blobShas = blobResps.map((r) => r.sha)
+
+    // 2. 创建 git tree（引用所有 blob）
+    const treeItems = filesList.map((file, i) => ({
+      path: file.path,
+      sha: blobShas[i],
+      mode: "100644" as const,
+      type: "blob" as const,
+    }))
+    const treeResp = await fetch(`${githubBase}/git/trees`, {
+      method: "POST",
+      headers: apiHeaders,
+      body: JSON.stringify({ tree: treeItems }),
+    })
+    if (!treeResp.ok) {
+      const err = (await treeResp.json()) as { message?: string }
+      return {
+        success: false as const,
+        message: `创建 git tree 失败：${err?.message ?? "未知错误"}`,
+        branch: targetBranch,
+      }
+    }
+    const treeData = (await treeResp.json()) as { sha: string }
+    const treeSha = treeData.sha
+
+    // 3. 创建 commit（父 commit = defaultBranch 的 tip）
+    const commitResp = await fetch(`${githubBase}/git/commits`, {
+      method: "POST",
+      headers: apiHeaders,
+      body: JSON.stringify({
+        message: title,
+        tree: treeSha,
+        parents: [baseSha],
+      }),
+    })
+    if (!commitResp.ok) {
+      const err = (await commitResp.json()) as { message?: string }
+      return {
+        success: false as const,
+        message: `创建 commit 失败：${err?.message ?? "未知错误"}`,
+        branch: targetBranch,
+      }
+    }
+    const commitData = (await commitResp.json()) as { sha: string }
+    const commitSha = commitData.sha
+
+    // 4. 更新分支引用指向新 commit
+    const updateBranchResp = await fetch(
+      `${githubBase}/git/refs/heads/${targetBranch}`,
+      {
+        method: "PATCH",
+        headers: apiHeaders,
+        body: JSON.stringify({ sha: commitSha, force: true }),
+      },
+    )
+    if (!updateBranchResp.ok) {
+      const err = (await updateBranchResp.json()) as { message?: string }
+      return {
+        success: false as const,
+        message: `更新分支 ${targetBranch} 失败：${err?.message ?? "未知错误"}`,
+        branch: targetBranch,
+      }
+    }
+
+    // 5. 创建 PR
+    const prBody = body ?? `自动生成的 Pull Request\n\n由 AllBlue AI 助手在 ${new Date().toISOString().slice(0, 10)} 创建。`
+    const createPrResp = await fetch(
+      `${githubBase}/pulls`,
+      {
+        method: "POST",
+        headers: apiHeaders,
+        body: JSON.stringify({
+          title,
+          body: prBody,
+          head: targetBranch,
+          base: defaultBranch,
+        }),
+      },
+    )
+    const createPrData = await createPrResp.json()
+    if (!createPrResp.ok || "message" in createPrData) {
+      const err = createPrData && "message" in createPrData
+        ? (createPrData as { message: string }).message
+        : `创建 PR 失败（HTTP ${createPrResp.status}）`
+      return {
+        success: false as const,
+        message: `创建 PR 失败：${err}`,
+        branch: targetBranch,
+      }
+    }
+
+    const pr = createPrData as { html_url: string }
+    return {
+      success: true as const,
+      prUrl: pr.html_url,
+      branch: targetBranch,
+      message: `PR 已成功创建（含 ${filesList.length} 个文件，commit ${commitSha.slice(0, 8)}）`,
+    }
+  },
+)

package/src/server/ai-gateway/tools/delegate-task.ts

@@ -0,0 +1,91 @@
+// 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 { toolDefinition } from "@tanstack/ai"
+import { z } from "zod"
+import { BIZ_AGENT_KEYS, type BizAgentKey } from "../runs/biz-keys"
+import { runChatAsAgent } from "../runs/agent-runtime"
+import type { AppContext } from "../types"
+import type { AgentToolKey } from "./select"
+
+/** 防子 agent 自递归：delegate_task 不进入子链工具面 */
+const DELEGATE_TASK_KEY = "delegate_task"
+
+/** 并发上限：同一时间最多 N 个委派同时执行，防止 token 超支 */
+const MAX_CONCURRENT_DELEGATIONS = 3
+/** 单次委派墙钟超时 */
+const DELEGATION_TIMEOUT_MS = 60_000
+
+const activeDelegations = new Map<string, boolean>()
+
+export const delegateTaskDef = toolDefinition({
+  name: DELEGATE_TASK_KEY,
+  description:
+    "把子任务委派给指定板块智能体执行并返回结构化结果。" +
+    "适合：需要另一领域专家（PRD/故事/知识库）补充信息或生成内容时调用。" +
+    "注意：自身不可递归委派（子 agent 见不到本工具）。",
+  needsApproval: true,
+  inputSchema: z.object({
+    bizKey: z
+      .enum(BIZ_AGENT_KEYS)
+      .describe("目标板块 bizKey（harness.default 排除，防自递归）"),
+    task: z.string().min(1).max(2000).describe("委派给子 agent 的具体任务描述"),
+    context: z
+      .string()
+      .max(1000)
+      .optional()
+      .describe("额外上下文（可选，子 agent 会参考但不保证完全沿用）"),
+  }),
+  outputSchema: z.object({
+    summary: z.string().describe("子 agent 执行结果的摘要（≤200 字）"),
+    result: z.string().describe("子 agent 返回的完整原始文本"),
+  }),
+})
+
+export const delegateTaskTool = delegateTaskDef.server<AppContext>(
+  async ({ bizKey, task, context }, { context: appCtx }) => {
+    const key = `${appCtx.userId}-${Date.now()}`
+
+    if (activeDelegations.size >= MAX_CONCURRENT_DELEGATIONS) {
+      return {
+        summary: "并发委派已达上限",
+        result: `当前已有 ${activeDelegations.size} 个委派在执行，请稍后重试`,
+      }
+    }
+
+    activeDelegations.set(key, true)
+    try {
+      const signal = AbortSignal.timeout(DELEGATION_TIMEOUT_MS)
+      const result = await runChatAsAgent(bizKey, [{ role: "user", content: task }], {
+        userId: appCtx.userId,
+        workspaceId: appCtx.workspaceId ?? undefined,
+        parentRunId: appCtx.runId,
+        allowedTools: (appCtx.allowedTools ?? []).filter(
+          (t): t is AgentToolKey => t !== DELEGATE_TASK_KEY,
+        ) as AgentToolKey[],
+      })
+      return { summary: result.slice(0, 200), result }
+    } catch (e) {
+      return {
+        summary: "委派执行失败",
+        result: e instanceof Error ? e.message : String(e),
+      }
+    } finally {
+      activeDelegations.delete(key)
+    }
+  },
+)

package/src/server/ai-gateway/tools/delete-project.ts

@@ -21,6 +21,9 @@ import { z } from "zod"
 export const deleteProjectDef = toolDefinition({
   name: "delete_project",
   description: "删除指定项目（敏感操作，需用户审批）",
+  // destructive 级平台硬规则（设计 §9.2 / ADR 16「防后果」）：
+  // agent 的 allowedTools 白名单只决定「工具是否可见」，不能豁免审批。
+  // selectTools 有防御断言锁定此不变式，未来回归会报错而非静默通过。
   needsApproval: true,
   inputSchema: z.object({
     projectId: z.string().describe("项目 ID"),

package/src/server/ai-gateway/tools/index.ts

@@ -24,7 +24,22 @@ export {
   reindexKnowledgeBaseDef,
 } from "./definitions"
 export { deleteProject, deleteProjectDef } from "./delete-project"
+export { projectionNamespace } from "./projection-namespace"
+export { todoWriteDef, todoWriteTool } from "./todo-write"
+export {
+  planSubmitDef,
+  planSubmitTool,
+  planApprovalInterrupt,
+} from "./plan-submit"
 export { AGENT_TOOL_KEYS, selectTools } from "./select"
+export {
+  toolRegistry,
+  AGENT_TOOL_DEFS,
+  assertUniqueToolNames,
+  assertToolStructureComplete,
+  assertExecutableToolStructure,
+} from "./registry"
+export type { AgentToolDef } from "./registry"
 export {
   constrainKnowledgeBaseId,
   mergeKnowledgeResults,

package/src/server/ai-gateway/tools/keys.ts

@@ -0,0 +1,42 @@
+// 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/>.
+
+// Browser-safe tool key constants.
+// This file MUST NOT import any server-only modules (prisma, database, etc.)
+// because it is consumed by client-side code (agent form, harness route).
+// The full tool definitions live in registry.ts; this file only re-declares
+// the string literal keys for use in zod enums and client-side checks.
+
+export const AGENT_TOOL_KEYS = [
+  "knowledge_search",
+  "document_action",
+  "user_data_query",
+  "web_search",
+  "reindex_knowledge_base",
+  "delete_project",
+  "todo_write",
+  "plan_submit",
+  "plugin_define",
+  "plugin_run",
+  "plugin_stop",
+  "plugin_undefine",
+  "plugin_inspect_list",
+  "delegate_task",
+  "create_pull_request",
+] as const
+
+export type AgentToolKey = (typeof AGENT_TOOL_KEYS)[number]

package/src/server/ai-gateway/tools/plan-submit.ts

@@ -0,0 +1,113 @@
+// 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 { toolDefinition, defineInterrupt } from "@tanstack/ai";
+import { z } from "zod";
+import { prisma, Prisma } from "@allbluecn/database";
+import type { AppContext } from "../types";
+import { projectionNamespace } from "./projection-namespace";
+
+/**
+ * 计划审批 payload schema：LLM 提交计划时携带的完整内容。
+ * 由 planApprovalMiddleware 在 raise interrupt 时从 toolCall.function.arguments
+ * 解析并注入 request.payload；客户端审批卡渲染用。
+ */
+export const planApprovalPayloadSchema = z.object({
+  title: z.string(),
+  steps: z.array(
+    z.object({
+      content: z.string(),
+      detail: z.string().optional(),
+    }),
+  ),
+  summary: z.string().optional(),
+});
+
+/**
+ * 计划审批 response schema：客户端回应审批结果的 shape。
+ * approved=true 表示同意执行；feedback 用于拒绝时向 LLM 反馈修改意见。
+ */
+export const planApprovalResponseSchema = z.object({
+  approved: z.boolean(),
+  feedback: z.string().optional(),
+});
+
+/**
+ * 计划审批 interrupt 定义。id 是跨仓库契约——UI 侧（任务 8）消费同一个 id
+ * 识别 pending interrupts，改名字会破坏前端审批卡路由，勿改。
+ */
+export const planApprovalInterrupt = defineInterrupt({
+  id: "plan_approval",
+  payloadSchema: planApprovalPayloadSchema,
+  responseSchema: planApprovalResponseSchema,
+});
+
+export const planSubmitDef = toolDefinition({
+  name: "plan_submit",
+  description:
+    "提交一个执行计划供用户审批。当任务复杂且需要多步操作时使用；" +
+    "用户批准后 LLM 会收到 tool result 并继续执行，拒绝则收到取消信号应重新规划。",
+  inputSchema: planApprovalPayloadSchema,
+  outputSchema: z.object({
+    status: z.literal("approved").describe("engine 决议已达成 approved，计划已登记"),
+    stored: z.boolean().describe("是否已写入权威快照；false 表示无 threadId 未落库"),
+  }),
+});
+
+/**
+ * plan_submit 的 execute 是「决议兑现」入口——由 planApprovalMiddleware 的
+ * onInterruptResolution 通过 toolResume='continue' 让引擎进入 tool phase
+ * 后调用。execute 只写权威快照，不改 transcript（客户端投影从 transcript 提取）。
+ *
+ * 仅当引擎决议为 continue 时 execute 才被调用；cancel 场景工具被跳过，
+ * 因此 execute 只能返回 approved 单态。
+ */
+export const planSubmitTool = planSubmitDef.server<AppContext>(
+  async ({ title, steps, summary }, { context }) => {
+    const threadId = context.threadId;
+    if (!threadId) {
+      return { status: "approved" as const, stored: false };
+    }
+
+    const namespace = projectionNamespace(threadId);
+    const value = {
+      title,
+      steps,
+      summary,
+      updatedAt: new Date().toISOString(),
+    } satisfies {
+      title: string;
+      steps: Array<{ content: string; detail?: string }>;
+      summary?: string;
+      updatedAt: string;
+    };
+
+    await prisma.chatPersistenceMeta.upsert({
+      where: { namespace_key: { namespace, key: "plan" } },
+      create: {
+        namespace,
+        key: "plan",
+        value: value as unknown as Prisma.InputJsonValue,
+      },
+      update: {
+        value: value as unknown as Prisma.InputJsonValue,
+      },
+    });
+
+    return { status: "approved" as const, stored: true };
+  },
+);