docs(6): research phase domain

2026-04-15 09:34:53 +08:00 · 2026-04-15 09:34:53 +08:00 · fc10d047f6
parent 17a8104384
commit fc10d047f6
1 changed files with 350 additions and 0 deletions
--- a/.planning/phases/06-/06-RESEARCH.md
+++ b/.planning/phases/06-/06-RESEARCH.md
@ -0,0 +1,350 @@
+# Phase 6: 在输入框输入@时，可引用已生成文件和已上传附件 - Research
+
+**Researched:** 2026-04-15  
+**Domain:** 聊天输入框 `@` 文件引用（thread 内 artifacts + uploads）  
+**Confidence:** HIGH
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked 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 个引用文件，超限时给出提示并阻止继续添加。
+
+### Claude's Discretion
+- `@` 候选面板的具体键盘交互细节（上下选择、回车确认、Esc 关闭）的实现方式。
+- chip 的具体视觉样式与动画，不改变已确认交互语义。
+- `ref_kind` / `ref_source` 的精确字段命名（前提是语义清晰且不破坏现有消费逻辑）。
+
+### Deferred Ideas (OUT OF SCOPE)
+- 跨线程/全局文件引用能力（可作为后续独立 phase）。
+- 基于语义检索或标签检索的高级文件查找（超出本阶段范围）。
+</user_constraints>
+
+## Project Constraints (from CLAUDE.md)
+
+- 仓库根目录未发现 `CLAUDE.md`，无额外项目级强制约束可继承。[VERIFIED: codebase grep]
+- 仓库根目录未发现 `AGENTS.md`，无额外项目级指令文件可继承。[VERIFIED: codebase grep]
+- 未发现 `.claude/skills/` 或 `.agents/skills/` 项目技能目录。[VERIFIED: codebase grep]
+
+## Summary
+
+本阶段最稳妥方案是“仅在现有输入与提交链路上加一层 thread-scoped 引用状态”，不改后端主契约、不引入新存储：`InputBox/PromptInputTextarea` 负责 `@` 触发与候选选择，`useThreadStream.sendMessage` 继续作为唯一提交汇总点，把“上传文件 + 引用文件”统一写入 `additional_kwargs.files`。[VERIFIED: codebase grep]
+
+当前代码已具备三块可复用能力：1) 输入框附件管理与提交 (`PromptInput`/`PromptInputMessage`)，2) 当前线程 artifacts 来源 (`thread.values.artifacts`)，3) 当前线程 uploads 查询 API (`/api/threads/{threadId}/uploads/list`)；因此本 phase 核心是“状态拼接与交互补全”，而不是基础设施建设。[VERIFIED: codebase grep]
+
+约束上最关键的是 D-09 与 D-05：候选面板必须基于现有 dropdown（Radix 封装）实现，且最终协议必须落到 `additional_kwargs.files`，这意味着应避免“独立 mention payload”或“自绘浮层”两类分叉实现。[VERIFIED: codebase grep][CITED: https://www.radix-ui.com/primitives/docs/components/dropdown-menu]
+
+**Primary recommendation:** 在 `InputBox` 增加 `referencedFiles`（chip 状态）+ dropdown 候选层，在 `useThreadStream` 合并为单一 `additional_kwargs.files` 提交，并为失效引用执行发送前软剔除。[VERIFIED: codebase grep]
+
+## Standard Stack
+
+### Core
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| `@radix-ui/react-dropdown-menu` | `2.1.16` (project) / `2.1.16` (latest) | `@` 候选弹层、焦点管理、键盘导航 | 仓库已封装 `components/ui/dropdown-menu.tsx`，且官方支持完整键盘导航与焦点管理。[VERIFIED: npm registry][VERIFIED: codebase grep][CITED: https://www.radix-ui.com/primitives/docs/components/dropdown-menu] |
+| `@tanstack/react-query` | `5.90.17` (project) / `5.99.0` (latest) | 复用 uploads 列表查询缓存与失效机制 | 现有 `useUploadedFiles` 已标准化 thread 级文件查询，不应手写请求状态机。[VERIFIED: npm registry][VERIFIED: codebase grep] |
+| `sonner` | `2.0.7` (project) / `2.0.7` (latest) | 软失败 toast（引用失效/超限） | 现有错误提示链路已统一使用 `toast.error`，保持一致性最小回归。[VERIFIED: npm registry][VERIFIED: codebase grep] |
+
+### Supporting
+| Library | Version | Purpose | When to Use |
+|---------|---------|---------|-------------|
+| `react` | `19.0.0` (project) / `19.2.5` (latest) | 输入态、候选态、chip 态管理 | 本 phase 只做组件内状态扩展，不做 React 升级。[VERIFIED: npm registry][VERIFIED: codebase grep] |
+| Internal: `PromptInput` + `useThreadStream` | current repo | 输入与提交主链路 | 所有 `@` 行为应挂接在该链路，避免并行提交路径。[VERIFIED: codebase grep] |
+
+### Alternatives Considered
+| Instead of | Could Use | Tradeoff |
+|------------|-----------|----------|
+| Dropdown 组件 | 自定义绝对定位浮层 | 违背 D-09，且会重复处理焦点/键盘/关闭行为。[VERIFIED: codebase grep] |
+| `additional_kwargs.files` 统一提交 | 新增 `mentions` 顶层字段 | 违背 D-05，增加后端与渲染兼容风险。[VERIFIED: codebase grep] |
+| thread 范围候选 | 全局文件池检索 | 违背 D-01，范围失控并引入权限语义。[VERIFIED: codebase grep] |
+
+**Installation:**
+```bash
+# 本 phase 无需新增依赖
+```
+
+**Version verification:**  
+- `npm view @radix-ui/react-dropdown-menu version time --json` → latest `2.1.16`。[VERIFIED: npm registry]  
+- `npm view @tanstack/react-query version time --json` → latest `5.99.0`（项目当前 `5.90.17`）。[VERIFIED: npm registry]  
+- `npm view sonner version time --json` → latest `2.0.7`。[VERIFIED: npm registry]  
+- `npm view react version time --json` → latest stable `19.2.5`（项目当前 `19.0.0`）。[VERIFIED: npm registry]
+
+## Architecture Patterns
+
+### Recommended Project Structure
+```text
+frontend/src/components/workspace/
+├── input-box.tsx                  # @ 触发、候选 dropdown、chip 交互
+frontend/src/components/ai-elements/
+├── prompt-input.tsx               # 输入事件钩子（onChange/onKeyDown）扩展点
+frontend/src/core/threads/
+├── hooks.ts                       # 发送前合并 uploads + refs -> additional_kwargs.files
+frontend/src/core/messages/
+├── utils.ts                       # FileInMessage 类型扩展与兼容解析
+```
+
+### Pattern 1: Thread-Scoped Candidate Aggregation
+**What:** 候选集合 = `thread.values.artifacts` + `useUploadedFiles(threadId)`，在前端归一为统一候选结构（含 `displayName/type/pathTail/source`）。[VERIFIED: codebase grep]  
+**When to use:** 每次输入框出现 `@` 触发态时。  
+**Example:**
+```typescript
+// Source: frontend/src/components/workspace/chats/chat-box.tsx
+// Source: frontend/src/core/uploads/hooks.ts
+const artifactPaths = thread.values.artifacts ?? [];
+const { data: uploads } = useUploadedFiles(threadId);
+const candidates = normalizeCandidates(artifactPaths, uploads?.files ?? []);
+```
+
+### Pattern 2: Chip State Separate from Raw Text
+**What:** `@` 选择结果保存在独立 `referencedFiles` 状态，不把 `@xxx` 文本作为真实提交依据。  
+**When to use:** 处理删除、去重、同名文件 disambiguation、上限控制。  
+**Example:**
+```typescript
+type ReferencedFile = {
+  key: string; // source + path
+  filename: string;
+  path: string;
+  ref_source: "artifact" | "upload";
+  ref_kind: "mention";
+};
+```
+
+### Pattern 3: Single Submit Envelope
+**What:** 发送前把“已上传附件 + 引用文件”统一组装为 `additional_kwargs.files`。  
+**When to use:** `useThreadStream.sendMessage` 的 `thread.submit` 前。  
+**Example:**
+```typescript
+// Source: frontend/src/core/threads/hooks.ts
+const filesForSubmit = [...uploadedFiles, ...referencedFiles].slice(0, 10);
+await thread.submit({
+  messages: [{ type: "human", content, additional_kwargs: { files: filesForSubmit } }],
+});
+```
+
+### Pattern 4: Soft-Fail on Stale References
+**What:** 提交前校验引用项是否仍存在；失效则自动移除并 toast，不中断文本发送。  
+**When to use:** 后端提交前最后一步校验。  
+**Example:**
+```typescript
+const { validRefs, staleRefs } = validateRefs(referencedFiles, latestCandidates);
+if (staleRefs.length) toast.error("部分引用已失效，已自动移除");
+```
+
+### Anti-Patterns to Avoid
+- **自定义浮层替代 dropdown:** 违反 D-09，并引入焦点逃逸/关闭行为缺陷风险。[VERIFIED: codebase grep]
+- **把引用仅编码进纯文本 `@文件名`:** 无法稳定区分同名文件，且删除/失效处理困难。[VERIFIED: codebase grep]
+- **新增并行提交结构（如 `mentions`）:** 与当前渲染和兼容链路分叉，违反 D-05。[VERIFIED: codebase grep]
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| 候选面板交互 | 自写键盘导航/焦点环 | `DropdownMenu` (Radix) | 官方能力已覆盖焦点与键盘导航，重造成本高且易出无障碍缺陷。[CITED: https://www.radix-ui.com/primitives/docs/components/dropdown-menu] |
+| 线程文件查询缓存 | 手写 `fetch + useEffect` 缓存层 | `useUploadedFiles` + React Query | 现有 query key 与失效逻辑已稳定使用于 uploads 领域。[VERIFIED: codebase grep] |
+| 文件渲染协议 | 新建消息文件协议 | 复用 `additional_kwargs.files` | 现有 `message-list-item` 与 `messages/utils` 已消费该结构。[VERIFIED: codebase grep] |
+
+**Key insight:** 本 phase 的复杂度主要来自“交互状态一致性”，不是“API 能力缺失”；复用现有协议可显著降低回归面。[VERIFIED: codebase grep]
+
+## Common Pitfalls
+
+### Pitfall 1: IME 输入法与 `@` 触发冲突
+**What goes wrong:** 中文输入组合态误触发候选面板。  
+**Why it happens:** 仅监听按键，不区分 `isComposing`。  
+**How to avoid:** 与现有 Enter 逻辑一致，基于 `isComposing` / `nativeEvent.isComposing` 保护 `@` 触发。[VERIFIED: codebase grep]  
+**Warning signs:** 中文拼写期间面板闪烁或误选。
+
+### Pitfall 2: 同名文件引用歧义
+**What goes wrong:** `report.md` 来自 artifact 还是 upload 无法区分。  
+**Why it happens:** 候选展示缺少 path/source。  
+**How to avoid:** 候选项固定显示“文件名 + 类型 + 路径尾段（或来源标签）”。[VERIFIED: codebase grep]  
+**Warning signs:** 选中后 chip 文案无法回溯来源。
+
+### Pitfall 3: 发送时覆盖已有上传文件
+**What goes wrong:** 引用文件写入后把上传文件挤掉。  
+**Why it happens:** 覆盖赋值而非合并数组。  
+**How to avoid:** 在 `hooks.ts` 保持统一 merge（uploads first, refs append, 统一上限）。[VERIFIED: codebase grep]  
+**Warning signs:** 上传成功但消息只显示引用 chip。
+
+### Pitfall 4: 失效引用阻断发送
+**What goes wrong:** 单个引用失效导致整条消息失败。  
+**Why it happens:** 抛异常中断提交。  
+**How to avoid:** 执行 D-07 软失败策略：剔除失效项 + toast + 继续发送文本。[VERIFIED: codebase grep]
+**Warning signs:** 用户可复现“删了附件后消息无法发送”。
+
+### Pitfall 5: Backspace 删除行为冲突
+**What goes wrong:** 空输入框按退格时，附件与引用 chip 删除顺序混乱。  
+**Why it happens:** 当前 `Backspace` 已绑定附件删除，需要定义 chip 优先级。[VERIFIED: codebase grep]  
+**How to avoid:** 统一规则（建议：先删引用 chip，再删附件）。[ASSUMED]  
+**Warning signs:** 用户感觉“按一次退格删错对象”。
+
+## Code Examples
+
+Verified patterns from official sources:
+
+### 1) Dropdown 基础结构（用于 @ 候选）
+```tsx
+// Source: https://www.radix-ui.com/primitives/docs/components/dropdown-menu
+<DropdownMenu open={open} onOpenChange={setOpen}>
+  <DropdownMenuTrigger asChild>
+    <button type="button">Trigger</button>
+  </DropdownMenuTrigger>
+  <DropdownMenuContent align="start" sideOffset={4}>
+    {items.map((item) => (
+      <DropdownMenuItem key={item.key} onSelect={() => select(item)}>
+        {item.label}
+      </DropdownMenuItem>
+    ))}
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+### 2) 现有提交结构（需保持兼容）
+```typescript
+// Source: frontend/src/core/threads/hooks.ts
+await thread.submit({
+  messages: [
+    {
+      type: "human",
+      content: [{ type: "text", text }],
+      additional_kwargs: filesForSubmit.length > 0 ? { files: filesForSubmit } : {},
+    },
+  ],
+});
+```
+
+### 3) 现有消息文件消费（需兼容）
+```typescript
+// Source: frontend/src/components/workspace/messages/message-list-item.tsx
+const files = message.additional_kwargs?.files;
+if (Array.isArray(files) && files.length > 0) {
+  return <RichFilesList files={files as FileInMessage[]} threadId={threadId} />;
+}
+```
+
+## State of the Art
+
+| Old Approach | Current Approach | When Changed | Impact |
+|--------------|------------------|--------------|--------|
+| 从消息正文解析 `<uploaded_files>` 标签 | 优先使用 `additional_kwargs.files` 结构化字段；仅保留正文解析作为兼容回退 | 精确时间未知（代码中已存在回退逻辑） | 新功能应继续写结构化字段，避免文本协议漂移。[VERIFIED: codebase grep] |
+
+**Deprecated/outdated:**
+- 仅依赖 `<uploaded_files>` 文本标签作为主数据源：当前属于兼容路径，不应作为新功能主路径。[VERIFIED: codebase grep]
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | 后端对 `additional_kwargs.files` 中新增 `ref_kind/ref_source` 字段是前向兼容（忽略或透传） | Architecture Patterns / Standard Stack | 若不兼容，将导致提交失败或渲染异常 |
+| A2 | 空输入框 Backspace 的“先删引用 chip 再删附件”顺序是更符合用户预期的规则 | Common Pitfalls | 若预期相反，会造成交互争议，需要产品确认 |
+
+## Open Questions
+
+1. **`ref_kind/ref_source` 的最终字段名与枚举值**
+   - What we know: 语义已锁定为“区分引用文件与上传文件”。[VERIFIED: codebase grep]
+   - What's unclear: 后端/其他消费端对字段命名是否有硬编码。
+   - Recommendation: 在 Phase 6 Plan 的 Wave 0 先做一次全仓搜索与联调验证，确定最终命名再实现。
+
+2. **同名同路径尾段时的最终去歧义显示**
+   - What we know: 决策要求展示“文件名+类型+路径尾段”。[VERIFIED: codebase grep]
+   - What's unclear: 极端冲突（路径尾段仍相同）时的 fallback 文案。
+   - Recommendation: 增加 `source` 徽标（artifact/upload）作为第三级 disambiguation。
+
+## Environment Availability
+
+| Dependency | Required By | Available | Version | Fallback |
+|------------|------------|-----------|---------|----------|
+| Node.js | 前端构建/测试 | ✓ | `v24.14.0` | — |
+| npm | registry 校验/脚本 | ✓ | `11.9.0` | — |
+| pnpm | 项目脚本执行 | ✓ | `10.32.1` | `npm`（不推荐，锁文件不同） |
+| Playwright CLI | E2E 验证 | ✓ | `1.59.1` | 仅做单测/静态检查（覆盖不足） |
+| Frontend dev server (`127.0.0.1:3000`) | 本地 E2E 运行 | ✗ | — | 启动 `pnpm --dir frontend dev` |
+| Backend API (`127.0.0.1:8000`) | uploads/artifacts 联调 | ✗ | — | 启动后端服务或使用 mock 断言 |
+
+**Missing dependencies with no fallback:**
+- 无（CLI 工具均可用）。[VERIFIED: local command]
+
+**Missing dependencies with fallback:**
+- 本地前后端服务当前未运行，可通过启动命令补齐。[VERIFIED: local command]
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Playwright `1.59.1` + existing unit tests (`*.test.ts/.mjs`) |
+| Config file | `frontend/playwright.config.ts` |
+| Quick run command | `pnpm --dir frontend playwright test frontend/tests/e2e/input-and-compose.spec.ts` |
+| Full suite command | `pnpm --dir frontend test:e2e` |
+
+### Phase Requirements → Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| D-01/D-02 | `@` 仅展示当前线程候选并可过滤 | e2e | `pnpm --dir frontend playwright test frontend/tests/e2e/input-and-compose.spec.ts -g "@候选"` | ❌ Wave 0 |
+| D-03/D-08 | 选中后显示 chip；最多 10 个 | e2e | `pnpm --dir frontend playwright test frontend/tests/e2e/input-and-compose.spec.ts -g "chip limit"` | ❌ Wave 0 |
+| D-05/D-06 | 提交落入 `additional_kwargs.files` 且含来源元信息 | unit/integration | `pnpm --dir frontend node --test frontend/src/core/threads/hooks.test.ts` | ✅（需扩展用例） |
+| D-07 | 失效引用软失败，不阻断发送 | e2e | `pnpm --dir frontend playwright test frontend/tests/e2e/input-and-compose.spec.ts -g "stale ref"` | ❌ Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `pnpm --dir frontend playwright test frontend/tests/e2e/input-and-compose.spec.ts`
+- **Per wave merge:** `pnpm --dir frontend test:e2e`
+- **Phase gate:** Full suite green before `/gsd-verify-work`
+
+### Wave 0 Gaps
+- [ ] `frontend/tests/e2e/at-reference-files.spec.ts` — 覆盖 D-01~D-08 的主流程
+- [ ] `frontend/src/core/threads/hooks.test.ts` — 增加 uploads+refs 合并与 soft-fail 场景断言
+- [ ] `frontend/src/core/messages/utils` 相关测试 — 校验新增元信息对渲染兼容性
+
+## Security Domain
+
+### Applicable ASVS Categories
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | no | 由现有会话体系负责（本 phase 不新增认证机制） |
+| V3 Session Management | no | 复用现有线程会话 |
+| V4 Access Control | yes | 严格 thread 范围候选来源（artifacts/uploads with threadId） |
+| V5 Input Validation | yes | 前端仅提交候选池中的受控文件元数据，不信任自由文本路径 |
+| V6 Cryptography | no | 本 phase 不引入加密实现 |
+
+### Known Threat Patterns for frontend mention-reference flow
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| 跨线程文件枚举（IDOR） | Information Disclosure | 候选源仅取当前 `threadId` 的 artifacts/uploads，禁止全局检索 |
+| 客户端伪造文件路径 | Tampering | 提交前按候选池二次校验，失效项软剔除 |
+| 文件名注入 UI（异常字符） | Tampering | 渲染时只做文本展示，不执行 HTML；沿用现有 React 转义 |
+| 超量引用导致 UI/消息膨胀 | Denial of Service | 强制上限 10 并阻止继续添加 |
+
+## Sources
+
+### Primary (HIGH confidence)
+- `frontend/src/components/workspace/input-box.tsx` - 输入框组合、提交入口、附件 UI。[VERIFIED: codebase grep]
+- `frontend/src/components/ai-elements/prompt-input.tsx` - 文本/附件状态、键盘行为、`PromptInputMessage`。[VERIFIED: codebase grep]
+- `frontend/src/core/threads/hooks.ts` - `additional_kwargs.files` 提交与上传流程。[VERIFIED: codebase grep]
+- `frontend/src/components/workspace/messages/message-list-item.tsx` - `additional_kwargs.files` 渲染消费。[VERIFIED: codebase grep]
+- `frontend/src/core/messages/utils.ts` - `FileInMessage` 与兼容解析（含 `<uploaded_files>` 回退）。[VERIFIED: codebase grep]
+- `frontend/src/core/uploads/api.ts` / `frontend/src/core/uploads/hooks.ts` - 当前线程 uploads API 与 query 封装。[VERIFIED: codebase grep]
+- npm registry (`npm view ...`) - 版本与发布时间校验。[VERIFIED: npm registry]
+
+### Secondary (MEDIUM confidence)
+- Radix Dropdown Menu official docs: https://www.radix-ui.com/primitives/docs/components/dropdown-menu  （能力说明：focus management / keyboard navigation）。[CITED: https://www.radix-ui.com/primitives/docs/components/dropdown-menu]
+- TanStack Query official docs (React v5): https://tanstack.com/query/latest/docs/framework/react/overview  （现有 query 模型一致性参考）。[CITED: https://tanstack.com/query/latest/docs/framework/react/overview]
+
+### Tertiary (LOW confidence)
+- 无。
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH - 主要基于仓库现有依赖与 npm registry 实时校验。
+- Architecture: HIGH - 关键链路（输入->提交->渲染）均在代码中可直接定位。
+- Pitfalls: MEDIUM - 大部分可由现有行为推导，个别交互优先级仍需产品确认。
+
+**Research date:** 2026-04-15  
+**Valid until:** 2026-05-15（30 天）