112 lines
5.7 KiB
Markdown
112 lines
5.7 KiB
Markdown
# 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*
|