5.7 KiB

Raw Blame History

Phase 06: 输入框 @ 引用文件能力 - Context

Gathered: 2026-04-15 Status: Ready for planning

## Phase Boundary

本阶段仅实现输入框中 @ 引用文件能力：用户在聊天输入框输入 @ 时，可从“当前线程已生成 artifacts 与已上传附件”中选择并引用文件，随消息提交给后端。

不扩展跨线程/全局检索，不新增后端能力边界外的文件系统能力。

## Implementation Decisions

引用来源与触发方式

D-01: 引用来源限定为“当前线程”的 artifacts + uploads，不做跨线程或全局文件池。
D-02: 输入 @ 即刻弹出候选面板；继续输入即进行过滤。

输入框交互与展示

D-03: 选中文件后，在输入框内展示为可删除标签（chip），而非纯文本 @文件名。
D-04: 同名文件场景下，候选项展示“文件名 + 类型徽标 + 路径尾段”，避免歧义。
D-09: @ 触发后的文件选择面板必须使用 dropdown 组件实现（不使用自定义浮层替代）。

提交协议与兼容策略

D-05: 复用 additional_kwargs.files 作为提交数据结构，不新增并行主结构。
D-06: 在 files 项内增加来源/类型元信息（如 ref_kind / ref_source），用于区分“引用文件”与“上传文件”，保持与现有渲染链路兼容。

失效与上限策略

D-07: 采用软失败：引用项失效时自动剔除并给出 toast，不阻止整条消息发送。
D-08: 每条消息最多允许 10 个引用文件，超限时给出提示并阻止继续添加。

the agent's Discretion

@ 候选面板的具体键盘交互细节（上下选择、回车确认、Esc 关闭）的实现方式。
chip 的具体视觉样式与动画，不改变已确认交互语义。
ref_kind / ref_source 的精确字段命名（前提是语义清晰且不破坏现有消费逻辑）。

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

阶段边界与需求来源

.planning/ROADMAP.md — Phase 6 条目与依赖关系（Depends on Phase 5）。
.planning/STATE.md — Phase 6 来源说明（Roadmap Evolution）。
.planning/PROJECT.md — 核心原则：旧视觉一致性与新逻辑稳定并存。
.planning/REQUIREMENTS.md — 既有质量与回归约束（尤其测试与稳定性约束）。

输入框与提交主链路

frontend/src/components/workspace/input-box.tsx — 输入框容器、按钮区与 PromptInput 接入点。
frontend/src/components/ai-elements/prompt-input.tsx — 输入/附件状态、提交时 PromptInputMessage 组装、键盘行为。
frontend/src/core/threads/hooks.ts — 发送消息主流程、optimistic files、上传后写入 additional_kwargs.files。
frontend/src/app/workspace/chats/[thread_id]/page.tsx — 页面层输入框挂载与提交入口。
frontend/src/components/ui/dropdown-menu.tsx — dropdown 交互基座（Phase 6 强制用于 @ 文件候选面板）。

文件来源与展示链路

frontend/src/components/workspace/chats/chat-box.tsx — 当前线程 artifact 列表来源（thread.values.artifacts）。
frontend/src/components/workspace/artifacts/artifact-file-list.tsx — artifact 文件列表与路径展示语义。
frontend/src/core/uploads/api.ts — 当前线程 uploads 列表/上传/删除 API 契约。
frontend/src/core/uploads/hooks.ts — uploads 查询与提交流程封装。
frontend/src/components/workspace/messages/message-list-item.tsx — additional_kwargs.files 渲染与文件卡片展示逻辑。
frontend/src/core/messages/utils.ts — 文件相关消息结构解析与兼容逻辑。

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

PromptInput 已具备附件状态、文件选择、粘贴/拖拽、提交流程，可在同一输入域扩展 @ 引用交互。
useThreadWithOptimistic（core/threads/hooks.ts）已处理 additional_kwargs.files 的上传态与已上传态，适合复用为引用态承载容器。
chat-box.tsx + artifacts context 已提供当前线程 artifact 文件集合，不需要新增跨线程聚合层。
uploads/api.ts + uploads/hooks.ts 已提供当前线程上传文件可查询能力，可直接作为 @ 候选数据源之一。

Established Patterns

文件相关元数据统一挂载在消息 additional_kwargs.files，渲染侧已依赖该模式。
输入框行为尽量在 PromptInput / InputBox 层闭环，页面层主要做组合。
错误处理倾向非阻断（toast + 继续主流程），与本次“软失败”决策一致。

Integration Points

InputBox/PromptInputTextarea 负责 @ 触发、候选过滤、chip 编辑交互。
发送前在 core/threads/hooks.ts 汇总“上传文件 + 引用文件”并统一写入 additional_kwargs.files。
message-list-item.tsx 消费 additional_kwargs.files；需保证新增引用元信息不会破坏现有显示。
uploads 与 artifacts 作为候选数据源，仅限当前线程 threadId。

</code_context>

## Specific Ideas

你明确要求沿用当前消息扩展结构：引用文件“复用 additional_kwargs.files”，不另起并行主结构。
你明确要求一次性覆盖全部灰区并锁定 A 方案（来源/触发/展示/去歧义/失效策略）。

## Deferred Ideas

跨线程/全局文件引用能力（可作为后续独立 phase）。
基于语义检索或标签检索的高级文件查找（超出本阶段范围）。

Phase: 06- Context gathered: 2026-04-15

5.7 KiB Raw Blame History Unescape Escape