---
phase: 06-
plan: 04
subsystem: ui
tags: [mentions, references, uploads, playwright, threads]
requires:
  - phase: 06-01
    provides: 输入框基础与消息发送交互
  - phase: 06-02
    provides: artifacts/threads 基础能力
  - phase: 06-03
    provides: UAT 缺口诊断基线
provides:
  - 任意输入位置 `@` 触发候选与键盘选择
  - 引用预览内嵌到 textarea 区域并限制 6 个
  - artifact 引用物化为 uploads 上下文契约后再提交
affects: [06-UAT, input-box, thread-submit, e2e]
tech-stack:
  added: []
  patterns: [artifact-reference-materialization, inline-reference-preview, anchored-mention-panel]
key-files:
  created: [.planning/phases/06-/06-04-SUMMARY.md]
  modified:
    - frontend/src/components/workspace/input-box.tsx
    - frontend/src/core/threads/submit-files.ts
    - frontend/src/core/threads/hooks.ts
    - frontend/src/core/threads/hooks.test.ts
    - frontend/tests/e2e/input-and-compose.spec.ts
key-decisions:
  - "候选面板改为 textarea 区域内的绝对定位层，避免通用 Dropdown 锚点偏移。"
  - "artifact 引用在 submit 前先 fetch+upload 物化为 `/mnt/user-data/uploads/*`，与后端上下文识别契约对齐。"
patterns-established:
  - "引用上下文提交前标准化：artifact -> upload virtual_path；失败标记 stale 并软失败。"
  - "E2E 对输入态优先走键盘路径，规避聊天区悬浮层点击拦截。"
requirements-completed: [ATREF-01, ATREF-02, ATREF-03, ATREF-04]
duration: 9min
completed: 2026-04-15
---

# Phase 06 Plan 04: 输入引用交互与上下文契约收口 Summary

**输入框 `@` 引用链路已收口：候选贴边定位、内嵌引用预览与 6 个上限、artifact 引用可转为上下文可消费的 uploads 契约。**

## Performance

- **Duration:** 9 min
- **Started:** 2026-04-15T03:35:00Z
- **Completed:** 2026-04-15T03:44:34Z
- **Tasks:** 3
- **Files modified:** 5

## Accomplishments

- 实现任意输入位置触发 `@` 候选；候选面板锚定到 textarea 上方；选中后保持输入焦点与展开态。
- 引用展示从输入框上方独立层迁移到 textarea 区域内，改为专用预览 UI（不再用 `Tag` 渲染引用）；上限与提示调整为 6。
- 在提交阶段增加 artifact 引用物化逻辑（fetch artifact 后上传为 upload），确保 `additional_kwargs.files` 可按 uploads 契约进入后端上下文链路。

## Task Commits

1. **Task 1: 修正 @ 候选定位与触发策略** - `de8b404a` (feat)
2. **Task 2: 重构引用展示与数量约束** - `4532f395` (feat)
3. **Task 3: 对齐 artifact 引用上下文提交契约** - `3edf85c8` (feat)

## Files Created/Modified

- `frontend/src/components/workspace/input-box.tsx` - `@` 触发/候选层/内嵌引用预览/输入态保持。
- `frontend/src/core/threads/submit-files.ts` - 新增 artifact 引用物化函数并与现有 submit 文件构建衔接。
- `frontend/src/core/threads/hooks.ts` - 提交前执行 artifact->upload 物化，统一走 `buildFilesForSubmit`。
- `frontend/src/core/threads/hooks.test.ts` - 增加 artifact/upload 差异与软失败（stale）覆盖。
- `frontend/tests/e2e/input-and-compose.spec.ts` - 更新 DF-INPUT-007/008 选择路径并新增 6 上限回归用例。

## Decisions Made

- 候选选择在 E2E 中采用键盘路径（`Enter`/`ArrowDown`），规避消息区悬浮层对鼠标点击的拦截。
- artifact 物化失败不阻断消息发送，统一沿用 stale 软失败提示语义。

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] 修复 E2E 点击被界面遮挡层拦截导致超时**
- **Found during:** Task 3 验证
- **Issue:** `DF-INPUT-007` 在新布局下点击候选被其他悬浮层拦截，测试超时。
- **Fix:** 测试改为先触发展开遮罩，再使用键盘选择候选；消除点击拦截不稳定性。
- **Files modified:** `frontend/tests/e2e/input-and-compose.spec.ts`
- **Verification:** `pnpm -s test:e2e --grep "DF-INPUT-007|DF-INPUT-008"` 通过（007 pass, 008 skip）
- **Committed in:** `3edf85c8`

---

**Total deviations:** 1 auto-fixed (Rule 1: bug)
**Impact on plan:** 无范围膨胀，属于验证链路稳定性修复。

## Issues Encountered

- E2E 在复用线程场景存在输入区遮罩和消息区悬浮层，导致鼠标选择候选不稳定；已切换到键盘路径验证。

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness

- 06-UAT 的 4 个缺口对应改动已覆盖到代码与验证命令。
- 可直接进入 orchestrator 的汇总校验与状态写回。

## Threat Flags

None.

## Self-Check: PASSED

- FOUND: `.planning/phases/06-/06-04-SUMMARY.md`
- FOUND commits: `de8b404a`, `4532f395`, `3edf85c8`