功能开发文档

文档标识

• 任务前缀：chat-file-remap
• 文档文件名：chat-file-remap-功能开发文档.md
• 更新时间：2026-04-24
• 文档定位：实现对齐与验收口径（运行时逐条 user file 注入）

0. 开发目标与约束

• 功能目标：修复 file-only user message 发给模型时退化为 null 的问题，并确保历史记录中每条带 file URL 的 human message 在运行时把文件内容注入回自己的 user message。
• 代码范围：v1/v2/chatTest 保存层回退、chat/tool 运行时消息构造、文件解析 helper、相关测试与文档同步。
• 非目标：历史数据回填、file_url 直传模型、API/DB schema 调整、前端交互调整。
• 实现原则：保存层不污染原始输入；运行时只改 LLM messages 副本；文件内容进 user message，不进 system prompt。
• 文件上限：每条 user query 的文件解析数量沿用 chatConfig.fileSelectConfig.maxFiles，不做跨 message URL 去重。
• 必须遵循规范：references/style-standards-entry.md。
• 适用维度：API[ ] DB[ ] Front[ ] Logger[ ] Package[x] BugFix[x] DocUpdate[x] DocI18n[ ]。

1. 实施任务拆解（可直接执行）

2. 文件级改动清单

2.1 关键代码片段（用于规划核对）

// 保存层：禁止保存增强后的 userContent
await finalizeChatRound({
  ...params,
  userContent: userQuestion
});

// 运行时：只增强发给 LLM 的 messages 副本
const userMessages = await Promise.all(
  rawUserMessages.map(async (message) => {
    if (message.obj !== ChatRoleEnum.Human) return message;

    return {
      ...message,
      value: await rewriteUserQueryWithFileContent({
        userQuery: message.value,
        requestOrigin,
        maxFiles,
        customPdfParse,
        parseFileContentFromUrls,
        teamId,
        tmbId
      })
    };
  })
);

// 注入规则：文件内容回填到所属 user message，不集中塞到最后一条
const finalText = [originText, filePrompt].filter(Boolean).join('\n\n===---===---===\n\n');

3. 后端实施说明

3.1 API 改动

N/A（无对外接口结构变化）。

内部保存链路要求：

1. prepareChatRound、finalizeChatRound、pushChatRecords、updateInteractiveChat 均使用原始 userQuestion。
2. 不在 API handler 中解析文件并改写 userQuestion。
3. 不新增请求/响应字段。

3.2 Service/Core 改动

3.3 运行时注入算法

1. 输入为 chatHistories 与当前轮 user prompt，先 clone 或新建消息数组，不能 mutate 原对象。
2. Chat/Tool 外层通过 Promise.all 并行处理运行时 messages。
3. 非 human message 原样返回；human message 调用 rewriteUserQueryWithFileContent。
4. 单条 user query 内只收集本条 file.url，不做跨 message URL 去重或共享缓存。
5. 调用 parseFileContentFromUrls 统一完成 URL 标准化、过滤、maxFiles 截断与文件解析。
6. 将解析结果回填到当前 user query：
   • message 原本有 text：追加分隔符和 <FilesContent>。
   • message 原本无 text：新增 text part。
7. 构造最终 chats2GPTMessages / tool-call messages。
8. 进入 loadRequestMessages 后，file_url 可以继续被过滤，但 text 中的文件正文必须保留。

3.4 数据层改动

N/A（不改 schema、索引、迁移逻辑）。

3.5 Bug 修复实施

修复关键伪代码：

const userMessages = await Promise.all(
  rawUserMessages.map(async (message) =>
    message.obj === ChatRoleEnum.Human
      ? {
          ...message,
          value: await rewriteUserQueryWithFileContent({
            userQuery: message.value,
            maxFiles,
            requestOrigin,
            customPdfParse,
            parseFileContentFromUrls,
            teamId,
            tmbId
          })
        }
      : message
  )
);

const messages = [
  ...getSystemPrompt_ChatItemType(concatenateSystemPrompt),
  ...userMessages
];

回归验证：

1. 当前轮 file-only 不再变 null。
2. 历史每条 human file 都注入回自己的 user message。
3. 保存层不新增 <FilesContent>。
4. 无 file 场景无回归。

4. 前端实施说明

N/A（本期无前端改动）。

5. 日志与可观测性

注意事项：

• 不新增观测方案。
• 不在日志中输出用户文件正文、解析文本或完整 prompt。

6. 文档更新提醒

7. 文档 i18n 实施说明

N/A，原因：本次只改 .claude/design 研发文档，不改 document/content/docs 目录。

8. 测试与验证

8.1 测试文件映射

8.2 自动化测试设计

8.3 场景覆盖核对

8.4 执行命令

pnpm -s vitest run test/cases/service/core/ai/llm/utils.test.ts

实现新增运行时注入测试后，同步补充对应 test file 命令。

8.5 手工验证（可选）

9. 质量自检清单

• 保存链路三入口（v1/v2/chatTest）均回退为原始 userQuestion
• 未改动 API/DB schema
• 未引入 file_url 直传模型逻辑
• 文件内容不进入 system prompt
• 历史 human file 逐条注入到所属 user message
• 当前轮 user file 同样注入到当前轮 user message
• maxFiles 作为单条 user query 的解析上限
• Tool node 有 readFiles tool 时跳过预解析
• 测试覆盖当前轮、历史轮、Tool、maxFiles、保存层不污染
• 文档更新提醒已填写

10. 发布与回滚

10.1 发布步骤

1. 完成 T1-T4 代码实现与测试。
2. 执行自动化测试并记录结果。
3. 合并发布。

10.2 回滚触发条件

• LLM 请求构造异常。
• 历史文件解析导致明显性能问题。
• Tool node 文件读取行为与 readFiles tool 冲突。

10.3 回滚步骤

1. 回退运行时逐条文件注入 helper 与调用点。
2. 保持保存层原始 userQuestion 逻辑不变。
3. 重新验证 file_url 过滤回归测试。

11. AI 实施提示（给执行模型）

• 先做保存层回退，再做运行时注入，不要反过来糊一锅。
• 注入对象是 LLM messages 副本，禁止 mutate userQuestion、histories 原对象。
• 历史文件内容必须回填到所属 user message，不能统一拼到最后一条。
• system prompt 禁止出现 <FilesContent>。
• 不扩展到历史回填、协议调整或前端 UI。