From cec16f2e93b049715bf690850c33a52ada3ab754 Mon Sep 17 00:00:00 2001
From: MT-Mint <798521692@qq.com>
Date: Wed, 15 Apr 2026 11:45:18 +0800
Subject: [PATCH] docs(06-04): complete plan 06-04 summary

- document task commits, verification, and deviations
- include self-check results for summary and commit hashes
---
 .planning/phases/06-/06-04-SUMMARY.md | 114 ++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 .planning/phases/06-/06-04-SUMMARY.md

diff --git a/.planning/phases/06-/06-04-SUMMARY.md b/.planning/phases/06-/06-04-SUMMARY.md
new file mode 100644
index 00000000..eaed3f0d
--- /dev/null
+++ b/.planning/phases/06-/06-04-SUMMARY.md
@@ -0,0 +1,114 @@
+---
+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`