@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/ai-gateway/sandbox/__tests__/harness-sandbox.test.ts

@@ -9,6 +9,8 @@ const mocks = vi.hoisted(() => {
   const resolveSandboxProvider = vi.fn()
   const prismaInstanceStore = vi.fn()
   const pgLockStore = vi.fn()
+  const generationRunFindMany = vi.fn()
+  const generationRunFindUnique = vi.fn()
   return {
     withSandbox,
     defineSandbox,
@@ -16,6 +18,8 @@ const mocks = vi.hoisted(() => {
     resolveSandboxProvider,
     prismaInstanceStore,
     pgLockStore,
+    generationRunFindMany,
+    generationRunFindUnique,
   }
 })
 
@@ -41,6 +45,14 @@ vi.mock("../instance-store", () => ({
 vi.mock("../../locks/pg-lock", () => ({
   pgLockStore: mocks.pgLockStore,
 }))
+vi.mock("@allbluecn/database", () => ({
+  prisma: {
+    generationRun: {
+      findMany: mocks.generationRunFindMany,
+      findUnique: mocks.generationRunFindUnique,
+    },
+  },
+}))
 
 import { InMemoryRunStore } from "@tanstack/ai"
 import { InMemoryLockStore } from "@tanstack/ai/locks"
@@ -68,6 +80,8 @@ describe("buildSandboxMiddleware 装配", () => {
     mocks.pgLockStore.mockReturnValue({ lock: "pg" })
     mocks.sandboxPolicyFor.mockImplementation((level: string) => ({ policy: level }))
     mocks.withSandbox.mockReturnValue({ middleware: "sandbox" })
+    mocks.generationRunFindMany.mockReset()
+    mocks.generationRunFindUnique.mockReset()
   })
 
   afterEach(() => vi.unstubAllEnvs())
@@ -168,3 +182,77 @@ describe("buildSandboxMiddleware 装配", () => {
     }
   })
 })
+
+describe("snapshots artifacts/blobs store 装配", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.unstubAllEnvs()
+    delete process.env.DEPLOY_TARGET
+    mocks.resolveSandboxProvider.mockResolvedValue({ provider: { name: "mock" } })
+    mocks.defineSandbox.mockImplementation((config: unknown) => config)
+    mocks.prismaInstanceStore.mockReturnValue({ store: "prisma" })
+    mocks.pgLockStore.mockReturnValue({ lock: "pg" })
+    mocks.sandboxPolicyFor.mockImplementation((level: string) => ({ policy: level }))
+    mocks.withSandbox.mockImplementation((_sandbox: unknown, options: unknown) => options)
+  })
+
+  function snapshotStores() {
+    return (mocks.withSandbox.mock.calls[0][1] as {
+      snapshots?: {
+        persistence?: {
+          stores?: {
+            artifacts?: { listForThread: (threadId: string) => Promise<Array<Record<string, unknown>>> }
+            blobs?: { get: (key: string) => Promise<{ arrayBuffer: () => Promise<ArrayBuffer> } | null> }
+          }
+        }
+      }
+    }).snapshots!.persistence!.stores!
+  }
+
+  it("listForThread 每条记录 blobKey 恒为非空字符串（1.0 必填契约）", async () => {
+    const startedAt = new Date("2026-10-25T00:00:00Z")
+    mocks.generationRunFindMany.mockResolvedValue([
+      { id: "run-with-artifact", artifactId: "art-123", startedAt },
+      { id: "run-no-artifact", artifactId: null, startedAt },
+    ])
+
+    await buildSandboxMiddleware(baseParams())
+    const records = await snapshotStores().artifacts!.listForThread("thread-1")
+
+    expect(records).toHaveLength(2)
+    for (const record of records) {
+      expect(typeof record.blobKey).toBe("string")
+      expect((record.blobKey as string).length).toBeGreaterThan(0)
+    }
+  })
+
+  it("artifactId 为空的行 blobKey 回退为该行 runId，且能被 blobs.get 按 id 解析", async () => {
+    const startedAt = new Date("2026-10-25T00:00:00Z")
+    mocks.generationRunFindMany.mockResolvedValue([
+      { id: "run-no-artifact", artifactId: null, startedAt },
+    ])
+    mocks.generationRunFindUnique.mockImplementation(
+      async (args: { where: { id: string } }) => {
+        // 模拟 generationRun 表按主键查询：只有真实存在的行命中
+        if (args.where.id === "run-no-artifact") {
+          return { result: Buffer.from("blob").toString("base64") }
+        }
+        return null
+      },
+    )
+
+    await buildSandboxMiddleware(baseParams())
+    const stores = snapshotStores()
+    const records = await stores.artifacts!.listForThread("thread-1")
+
+    const record = records[0]
+    expect(record.runId).toBe("run-no-artifact")
+    expect(record.blobKey).toBe("run-no-artifact")
+
+    const blob = await stores.blobs!.get(record.blobKey as string)
+    expect(blob).not.toBeNull()
+    expect(mocks.generationRunFindUnique).toHaveBeenCalledWith(
+      expect.objectContaining({ where: { id: "run-no-artifact" } }),
+    )
+  })
+})

package/src/server/ai-gateway/sandbox/harness-sandbox.ts

@@ -218,7 +218,7 @@ export async function buildSandboxMiddleware(
                 artifactId: r.id,
                 runId: r.id,
                 threadId,
-                blobKey: r.artifactId ?? undefined,
+                blobKey: r.artifactId ?? r.id,
                 name: r.id,
                 mimeType: "application/octet-stream",
                 size: 0,

package/src/server/ai-gateway/story-handler.ts

@@ -48,7 +48,6 @@ function buildStoryModelOptions(adapterKind: string | undefined, maxTokens: numb
 const POLISH_PROMPTS: Record<string, string> = {
   expand: "扩写现有需求描述：补充实现细节、背景与边界情况，语言保持清晰专业。",
   polish: "润色现有需求描述：修正语病、统一表述、提升可读性，不改变原始含义。",
-  acceptance: "为现有需求补充验收标准：列出可验证的验收要点。",
 }
 
 function resolvePolishInstruction(action: string | undefined): string {
@@ -81,7 +80,7 @@ const storyAiSchema = z
     options: z
       .object({
         splitMode: z.enum(["children", "independent"]).optional(),
-        polishAction: z.enum(["expand", "polish", "acceptance"]).optional(),
+        polishAction: z.enum(["expand", "polish"]).optional(),
       })
       .optional(),
     labels: z.array(z.string()).optional(),
@@ -164,12 +163,18 @@ export async function* handleStoryAiRequest(
 
   const adapterKind = providerConfig?.adapterKind ?? (fallbackConfig ? "openrouter" : undefined)
   const maxTokens = data.mode === "split" ? SPLIT_MAX_TOKENS : STORY_MAX_TOKENS
+  // 1.0 起 threadId 必填：同一条需求的 AI 调用按 story id 幂等派生稳定 threadId，
+  // 无 story 上下文（全新生成，无既有会话可归并）时退化为每请求新 uuid。
+  const threadId = data.context?.story?.id
+    ? `story-${data.context.story.id}`
+    : crypto.randomUUID()
   const stream = chat({
     adapter,
     messages: messages as never,
     systemPrompts: finalPrompts,
     modelOptions: buildStoryModelOptions(adapterKind, maxTokens),
     context,
+    threadId,
     middleware: [loggerMiddleware, rateLimitMiddleware],
   })
 

package/src/server/ai-gateway/tools/plugin-lifecycle-defs.ts

@@ -15,108 +15,17 @@
 // 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/auth import，客户端可安全 import
-// 服务端 execute 见 plugin-lifecycle-server.ts
+// ⚠ 定义本体已单源至 lib/plugin-runtime/plugin-tool-defs.ts（isomorphic 纯净，
+// 零 prisma import）——服务端注册表与客户端工厂共享同一批 toolDefinition 导出
+// （1.0 硬约束：客户端工具 schema 与服务端不一致会静默退化为 generic interrupt）。
+// 服务端 execute 装配见 plugin-lifecycle-server.ts；本文件保留为服务端侧
+// re-export 入口（registry.ts / plugin-lifecycle-server.ts 既有 import 不变）。
 
-import { toolDefinition } from "@tanstack/ai";
-import { z } from "zod";
-
-export const pluginDefineDef = toolDefinition({
-  name: "plugin_define",
-  description:
-    "定义或更新一个 dsh 兼容插件。插件源码会在用户浏览器 Worker 中求值，" +
-    "支持 host/client 双半源码、自定义工具注册。提交后需用户审批才会生效。",
-  needsApproval: true,
-  inputSchema: z.object({
-    name: z.string().min(1).max(64).describe("插件名称，唯一标识"),
-    purpose: z.string().min(1).max(512).describe("插件用途说明"),
-    codeHost: z
-      .string()
-      .max(64_000)
-      .optional()
-      .describe("服务端半源码（浏览器 Worker 内求值，ctx/harness 契约面）"),
-    codeClient: z
-      .string()
-      .max(64_000)
-      .optional()
-      .describe("客户端半源码（UI 侧交互逻辑）"),
-  }),
-  outputSchema: z.object({
-    id: z.string(),
-    version: z.number(),
-    status: z.string(),
-  }),
-});
-
-export const pluginRunDef = toolDefinition({
-  name: "plugin_run",
-  description: "启动一个已定义的插件，在浏览器 Worker 中求值源码并注册工具",
-  needsApproval: true,
-  inputSchema: z.object({
-    name: z.string().min(1).describe("插件名称"),
-  }),
-  outputSchema: z.object({
-    started: z.boolean(),
-    tools: z.array(
-      z.object({
-        name: z.string(),
-        description: z.string(),
-        inputSchema: z.any(),
-      })
-    ),
-    error: z.string().optional(),
-  }),
-});
-
-export const pluginStopDef = toolDefinition({
-  name: "plugin_stop",
-  description: "停止一个正在运行的插件",
-  inputSchema: z.object({
-    name: z.string().min(1).describe("插件名称"),
-  }),
-  outputSchema: z.object({
-    stopped: z.boolean(),
-  }),
-});
-
-export const pluginUndefineDef = toolDefinition({
-  name: "plugin_undefine",
-  description: "删除一个插件（软删除，标记 isDeleted）",
-  inputSchema: z.object({
-    name: z.string().min(1).describe("插件名称"),
-  }),
-  outputSchema: z.object({
-    deleted: z.boolean(),
-  }),
-});
-
-export const pluginInspectListDef = toolDefinition({
-  name: "plugin_inspect_list",
-  description: "列出当前用户的所有插件及其状态",
-  inputSchema: z.object({}),
-  outputSchema: z.object({
-    plugins: z.array(
-      z.object({
-        id: z.string(),
-        name: z.string(),
-        purpose: z.string(),
-        version: z.number(),
-        status: z.string(),
-        tools: z.array(
-          z.object({
-            name: z.string(),
-            description: z.string(),
-          })
-        ),
-      })
-    ),
-  }),
-});
-
-export const pluginLifecycleDefs = [
+export {
   pluginDefineDef,
   pluginRunDef,
   pluginStopDef,
   pluginUndefineDef,
   pluginInspectListDef,
-];
+  pluginLifecycleDefs,
+} from "@/lib/plugin-runtime/plugin-tool-defs";

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

@@ -16,10 +16,13 @@
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 // 服务端动态工具池：读 running 插件 → 构造 client-executed 工具定义
-// 三段前缀：plugin__<pluginName>__<toolName>（运行期与内置工具名隔离）
+// 构造逻辑单源于 lib/plugin-runtime/plugin-tool-defs.ts 的
+// buildPluginDynamicToolDef（客户端工厂用同一 builder，保证
+// plugin__<pluginName>__<toolName> 的 inputSchema 双侧一致——1.0 硬约束：
+// 不一致会静默退化为 generic interrupt）
 
 import { prisma } from "@allbluecn/database";
-import { toolDefinition } from "@tanstack/ai";
+import { buildPluginDynamicToolDef } from "@/lib/plugin-runtime/plugin-tool-defs";
 
 export interface PluginToolDef {
   name: string;
@@ -42,14 +45,7 @@ export async function buildPluginTools(userId: string): Promise<any[]> {
     for (const toolDef of pluginTools) {
       if (!toolDef.name || !toolDef.description) continue;
 
-      const toolName = `plugin__${plugin.name}__${toolDef.name}`;
-      const tool = toolDefinition({
-        name: toolName,
-        description: `[${plugin.name}] ${toolDef.description}`,
-        inputSchema: toolDef.inputSchema || { type: "object", properties: {} },
-      });
-
-      tools.push(tool);
+      tools.push(buildPluginDynamicToolDef(plugin.name, toolDef));
     }
   }
 

package/src/server/ai-task/assigned-query.ts

@@ -0,0 +1,167 @@
+import { Prisma, prisma } from "@allbluecn/database"
+import { mapToUnifiedPriority } from "./priority-map"
+import type { AssignedItem, AssignedResult, TaskSource } from "./types"
+
+// provider 探测与 packages/database/index.ts 同口径（process.env.DATABASE_PROVIDER ?? "postgresql"）
+export function getDatabaseProvider(): string {
+  return process.env.DATABASE_PROVIDER ?? "postgresql"
+}
+
+const storySelect = {
+  id: true,
+  identifier: true,
+  name: true,
+  state: true,
+  priority: true,
+  targetDate: true,
+  updatedAt: true,
+  projectId: true,
+  project: { select: { name: true } },
+} satisfies Prisma.StorySelect
+
+const bugSelect = {
+  id: true,
+  identifier: true,
+  title: true,
+  state: true,
+  severity: true,
+  updatedAt: true,
+  projectId: true,
+  project: { select: { name: true } },
+} satisfies Prisma.BugSelect
+
+const testCaseSelect = {
+  id: true,
+  identifier: true,
+  title: true,
+  state: true,
+  priority: true,
+  updatedAt: true,
+  projectId: true,
+  project: { select: { name: true } },
+} satisfies Prisma.TestCaseSelect
+
+type StoryRow = Prisma.StoryGetPayload<{ select: typeof storySelect }>
+type BugRow = Prisma.BugGetPayload<{ select: typeof bugSelect }>
+type TestCaseRow = Prisma.TestCaseGetPayload<{ select: typeof testCaseSelect }>
+
+// 进行中的口径：已完成/取消（story done/cancelled）、已修复/关闭（bug fixed/closed/wontfix）、
+// 已批准/废弃（testcase approved/deprecated）的条目不再出现在「分配给我的」列表
+const STORY_ACTIVE_STATES = ["backlog", "todo", "in_progress"]
+const BUG_ACTIVE_STATES = ["open", "in_progress"]
+const TESTCASE_ACTIVE_STATES = ["draft", "in_review"]
+
+function queryAssignedStories(userId: string): Promise<StoryRow[]> {
+  return prisma.story.findMany({
+    where: {
+      assigneeId: userId,
+      archived: false,
+      state: { in: STORY_ACTIVE_STATES },
+      project: { members: { some: { userId, status: { not: "suspended" } } } },
+    },
+    select: storySelect,
+    orderBy: { updatedAt: "desc" },
+  })
+}
+
+function queryAssignedBugs(userId: string): Promise<BugRow[]> {
+  return prisma.bug.findMany({
+    where: {
+      assigneeId: userId,
+      archived: false,
+      state: { in: BUG_ACTIVE_STATES },
+      project: { members: { some: { userId, status: { not: "suspended" } } } },
+    },
+    select: bugSelect,
+    orderBy: { updatedAt: "desc" },
+  })
+}
+
+function queryAssignedTestCases(userId: string): Promise<TestCaseRow[]> {
+  return prisma.testCase.findMany({
+    where: {
+      assigneeId: userId,
+      archived: false,
+      state: { in: TESTCASE_ACTIVE_STATES },
+      project: { members: { some: { userId, status: { not: "suspended" } } } },
+    },
+    select: testCaseSelect,
+    orderBy: { updatedAt: "desc" },
+  })
+}
+
+function toStoryItem(row: StoryRow): AssignedItem {
+  return {
+    source: "story",
+    id: row.id,
+    identifier: row.identifier,
+    title: row.name,
+    projectId: row.projectId,
+    projectName: row.project.name,
+    priority: mapToUnifiedPriority("story", row.priority),
+    dueAt: row.targetDate ? row.targetDate.toISOString() : null,
+    href: `/stories/${row.id}`,
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+function toBugItem(row: BugRow): AssignedItem {
+  return {
+    source: "bug",
+    id: row.id,
+    identifier: row.identifier,
+    title: row.title,
+    projectId: row.projectId,
+    projectName: row.project.name,
+    priority: mapToUnifiedPriority("bug", row.severity),
+    dueAt: null,
+    href: `/bugs/${row.id}`,
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+function toTestCaseItem(row: TestCaseRow): AssignedItem {
+  return {
+    source: "testcase",
+    id: row.id,
+    identifier: row.identifier,
+    title: row.title,
+    projectId: row.projectId,
+    projectName: row.project.name,
+    priority: mapToUnifiedPriority("testcase", row.priority),
+    dueAt: null,
+    href: `/test-cases/${row.id}`,
+    updatedAt: row.updatedAt.toISOString(),
+  }
+}
+
+/**
+ * 「分配给我的」三表聚合（story → bug → testcase 组序，组内 updatedAt 倒序，不跨表重排）。
+ * 桌面端 SQLite（DATABASE_PROVIDER=sqlite）无 bug/testcase 数据源，降级为仅 story 并在 degraded 中声明。
+ */
+export async function fetchAssignedToMe(userId: string): Promise<AssignedResult> {
+  const isSqlite = getDatabaseProvider() === "sqlite"
+
+  const pendingBugs: Promise<BugRow[]> = isSqlite
+    ? Promise.resolve([])
+    : queryAssignedBugs(userId)
+  const pendingTestCases: Promise<TestCaseRow[]> = isSqlite
+    ? Promise.resolve([])
+    : queryAssignedTestCases(userId)
+
+  const [storyRows, bugRows, testCaseRows] = await Promise.all([
+    queryAssignedStories(userId),
+    pendingBugs,
+    pendingTestCases,
+  ])
+
+  const items: AssignedItem[] = [
+    ...storyRows.map(toStoryItem),
+    ...bugRows.map(toBugItem),
+    ...testCaseRows.map(toTestCaseItem),
+  ]
+
+  const degraded: TaskSource[] = isSqlite ? ["bug", "testcase"] : []
+
+  return { items, degraded }
+}

package/src/server/ai-task/context-builder.ts

@@ -0,0 +1,182 @@
+import type { TaskSource } from './types'
+
+// 源条目 AI 执行上下文组装（规格 §5.6）：纯函数 row → 文本块。
+// 零 prisma 依赖、零 I/O：row 由调用方（executor）查询后传入；
+// 悬空源由调用方探测（lookup 返回 null 时不得调用本模块）。
+
+const STACK_SUMMARY_LIMIT = 8192
+
+/**
+ * 从 Story/Bug 的 description 字符串中提取 TipTap JSON 的 markdown 段。
+ *
+ * 库内存储形态是 `{ html, markdown }` JSON **字符串**（`String? @db.Text`，
+ * 见 schema.prisma Bug.description 注释）；历史数据可能是裸 HTML/markdown。
+ * 容忍一切非法输入：解析失败、缺 markdown 字段、markdown 非字符串或空串
+ * 一律返回 null（不抛错），由调用方决定降级文案。
+ * 防御性支持已解析对象入参（row 可能被上游预解析）。
+ */
+export function extractTipTapMarkdown(description: unknown): string | null {
+  let parsed: unknown = description
+  if (typeof parsed === 'string') {
+    try {
+      parsed = JSON.parse(parsed)
+    } catch {
+      return null
+    }
+  }
+  if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+    const markdown = (parsed as Record<string, unknown>).markdown
+    if (typeof markdown === 'string' && markdown.length > 0) return markdown
+  }
+  return null
+}
+
+type StepItem = { order: number; action: string; expected?: string }
+
+/** 收窄 `{ steps: [{ order, action, expected? }] }` 形状的 unknown 值；非法输入返回空数组。 */
+function asSteps(raw: unknown): StepItem[] {
+  if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) return []
+  const steps = (raw as Record<string, unknown>).steps
+  if (!Array.isArray(steps)) return []
+  const out: StepItem[] = []
+  steps.forEach((item, index) => {
+    if (typeof item !== 'object' || item === null) return
+    const rec = item as Record<string, unknown>
+    if (typeof rec.action !== 'string' || rec.action.length === 0) return
+    out.push({
+      order: typeof rec.order === 'number' ? rec.order : index + 1,
+      action: rec.action,
+      expected: typeof rec.expected === 'string' ? rec.expected : undefined,
+    })
+  })
+  return out
+}
+
+function renderStepsLines(steps: StepItem[]): string[] {
+  return steps.map((step) =>
+    step.expected !== undefined
+      ? `- [${step.order}] ${step.action} → ${step.expected}`
+      : `- [${step.order}] ${step.action}`,
+  )
+}
+
+/** 读取行字段为展示文本；null/undefined/空串返回 null（对应行省略）。 */
+function fieldText(value: unknown): string | null {
+  if (value === null || value === undefined) return null
+  if (value instanceof Date) return value.toISOString().slice(0, 10)
+  if (typeof value === 'string') return value.length > 0 ? value : null
+  return String(value)
+}
+
+/** 读取 select 进来的嵌套关系对象的 name（如 row.project / row.story）。 */
+function nestedName(value: unknown): string | null {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return null
+  const name = (value as Record<string, unknown>).name
+  return typeof name === 'string' && name.length > 0 ? name : null
+}
+
+/** `字段: 值` 行；值为空时整行省略。 */
+function infoLine(label: string, value: unknown): string | null {
+  const text = fieldText(value)
+  return text === null ? null : `${label}: ${text}`
+}
+
+function truncateStack(text: string): string {
+  return text.length <= STACK_SUMMARY_LIMIT
+    ? text
+    : text.slice(0, STACK_SUMMARY_LIMIT) + '…[截断]'
+}
+
+/** 小节标题 + 正文；正文为空（无行）时整节省略。 */
+function section(title: string, lines: string[]): string[] {
+  return lines.length === 0 ? [] : ['', title, ...lines]
+}
+
+function buildStoryBlock(row: Record<string, unknown>): string {
+  const lines = [
+    infoLine('标识', row.identifier),
+    infoLine('标题', row.name),
+    infoLine('状态', row.state),
+    infoLine('优先级', row.priority),
+    infoLine('所属项目', nestedName(row.project)),
+    infoLine('目标日期', row.targetDate),
+  ].filter((line): line is string => line !== null)
+
+  const markdown = extractTipTapMarkdown(row.description)
+  const block = ['## 需求上下文', ...lines]
+  if (markdown !== null) {
+    block.push('', '### 描述', markdown)
+  }
+  return block.join('\n')
+}
+
+function buildBugBlock(row: Record<string, unknown>): string {
+  const lines = [
+    infoLine('标识', row.identifier),
+    infoLine('标题', row.title),
+    infoLine('严重级别', row.severity),
+    infoLine('关联需求', nestedName(row.story)),
+    infoLine('发生页面', row.url),
+    infoLine('环境', row.env),
+  ].filter((line): line is string => line !== null)
+
+  const block = ['## 缺陷上下文', ...lines]
+
+  const steps = asSteps(row.reproduceSteps)
+  const stepLines = renderStepsLines(steps)
+  if (steps.length > 0) {
+    const summary = row.reproduceSteps as Record<string, unknown>
+    if (typeof summary.expectedResult === 'string' && summary.expectedResult) {
+      stepLines.push(`整体预期: ${summary.expectedResult}`)
+    }
+    if (typeof summary.actualResult === 'string' && summary.actualResult) {
+      stepLines.push(`实际结果: ${summary.actualResult}`)
+    }
+    block.push(...section('### 复现步骤', stepLines))
+  }
+
+  if (typeof row.stackSummary === 'string' && row.stackSummary.length > 0) {
+    block.push(...section('### 堆栈摘要', [truncateStack(row.stackSummary)]))
+  }
+  return block.join('\n')
+}
+
+function buildTestCaseBlock(row: Record<string, unknown>): string {
+  const lines = [
+    infoLine('标识', row.identifier),
+    infoLine('标题', row.title),
+    infoLine('类型', row.type),
+  ].filter((line): line is string => line !== null)
+
+  const block = ['## 测试用例上下文', ...lines]
+
+  const precondition = fieldText(row.precondition)
+  if (precondition !== null) {
+    block.push(...section('### 前置条件', [precondition]))
+  }
+
+  const steps = asSteps(row.steps)
+  if (steps.length > 0) {
+    block.push(...section('### 测试步骤', renderStepsLines(steps)))
+  }
+  return block.join('\n')
+}
+
+/**
+ * 按规格 §5.6 注入字段表，把源条目 row 拼装为定长上下文小节
+ * （拼入 AI 执行的系统提示词）。
+ *
+ * - Story: identifier + name + description(TipTap markdown) + 状态/优先级 + 项目名 + 目标日期
+ * - Bug: identifier + title + severity + reproduceSteps(结构化渲染) + stackSummary(≤8KB 截断) + url/env + 关联 Story 标题
+ * - TestCase: identifier + title + precondition + steps(结构化渲染) + type
+ *
+ * 缺失字段对应行/小节整体省略，任何非法形状不抛错。
+ */
+export function buildSourceContextBlock(
+  source: TaskSource,
+  row: Record<string, unknown>,
+): string {
+  if (source === 'story') return buildStoryBlock(row)
+  if (source === 'bug') return buildBugBlock(row)
+  return buildTestCaseBlock(row)
+}