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

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

<domain>
## Phase Boundary

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

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

</domain>

<decisions>
## 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` 的精确字段命名（前提是语义清晰且不破坏现有消费逻辑）。

</decisions>

<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>

<specifics>
## Specific Ideas

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

</specifics>

<deferred>
## Deferred Ideas

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

</deferred>

---

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