docs(07): research phase domain
This commit is contained in:
parent
c4fe34ed23
commit
88de7e1e8f
|
|
@ -0,0 +1,287 @@
|
|||
# Phase 07: Phase 06 验收后补丁归档（mention/upload语义与附件预览复用）- Research
|
||||
|
||||
**Researched:** 2026-04-15
|
||||
**Domain:** 前后端 mention/upload 语义收敛、附件预览组件复用、memory 清理与验证归档
|
||||
**Confidence:** HIGH
|
||||
|
||||
## User Constraints (from CONTEXT.md)
|
||||
|
||||
`07-phase-06-mention-upload` 目录下不存在 `*-CONTEXT.md`，因此无可逐字拷贝的 Locked Decisions/Discretion/Deferred。 [VERIFIED: codebase grep `.planning/phases/07-phase-06-mention-upload/*-CONTEXT.md`]
|
||||
|
||||
基于本次 objective 的硬约束如下：将 Phase 06 已验收绕行改动正式纳入 Phase 07，范围必须覆盖 mention/upload 语义统一、附件预览复用、memory 清理、可验证提交路径。 [VERIFIED: user objective]
|
||||
|
||||
## Summary
|
||||
|
||||
Phase 06 的代码层关键补丁已经在仓库内落地：前端通过 `additional_kwargs.files` 单一 envelope 发送 uploads + mentions，后端 `UploadsMiddleware` 已区分 `ref_kind=mention` 并单独注入 `<mentioned_files>`，且 `new_files` 不再错误吸收 mention。 [VERIFIED: codebase grep `frontend/src/core/threads/hooks.ts`, `frontend/src/core/threads/submit-files.ts`, `backend/.../uploads_middleware.py`]
|
||||
|
||||
memory 侧也已有清理链路：`MemoryMiddleware` 在入队前剥离 `<uploaded_files>/<mentioned_files>`，`MemoryUpdater` 在落盘前清除上传事件句子与 facts；对应回归测试存在且本地通过。 [VERIFIED: codebase grep `backend/.../memory_middleware.py`, `backend/.../memory/updater.py`, `backend/tests/test_memory_upload_filtering.py`; VERIFIED: test run `uv run pytest -q tests/test_memory_upload_filtering.py`]
|
||||
|
||||
Phase 07 的核心不是“再造新功能”，而是“归档与验证闭环”：统一术语契约、固定附件预览复用边界、补齐 E2E 选择器漂移、同步 UAT/Validation/Requirements 文档状态，形成可审计提交路径。 [VERIFIED: codebase grep `.planning/phases/06-/06-VERIFICATION.md`, `.planning/phases/06-/06-UAT.md`, `.planning/REQUIREMENTS.md`; VERIFIED: test run `pnpm -s test:e2e --grep "DF-INPUT-007|DF-INPUT-008|DF-INPUT-009"`]
|
||||
|
||||
**Primary recommendation:** Phase 07 按 `docs/contract-fix -> test-fix -> re-verify -> archive` 四段执行，禁止再扩展功能面。 [VERIFIED: repo state + phase goal]
|
||||
|
||||
## Project Constraints (from CLAUDE.md)
|
||||
|
||||
项目根目录不存在 `CLAUDE.md`，无额外项目级强制约束。 [VERIFIED: filesystem check `test -f CLAUDE.md`]
|
||||
|
||||
## Standard Stack
|
||||
|
||||
### Core
|
||||
| Library | Version | Purpose | Why Standard |
|
||||
|---------|---------|---------|--------------|
|
||||
| `@radix-ui/react-dropdown-menu` | repo: `^2.1.16`; npm latest: `2.1.16` (2025-08-13) | mention 候选面板（键盘/焦点/定位） | 已在输入框实现且与现有 shadcn 体系一致，避免自定义浮层分叉。 [VERIFIED: codebase grep `frontend/src/components/workspace/input-box.tsx`; VERIFIED: npm registry `npm view @radix-ui/react-dropdown-menu version time`] |
|
||||
| `sonner` | repo: `^2.0.7`; npm latest: `2.0.7` (2025-08-02) | stale/上限提示 | 现有错误提示已基于 toast 语义，便于保持软失败行为一致。 [VERIFIED: codebase grep `toast.error` in `hooks.ts`/`input-box.tsx`; VERIFIED: npm registry `npm view sonner version time`] |
|
||||
| `PromptInputAttachment`（内部组件） | repo internal | 输入区附件/引用缩略预览 | 当前 reference 预览已复用该组件，是 Phase 07 应固化的复用基线。 [VERIFIED: codebase grep `frontend/src/components/workspace/input-box.tsx`, `frontend/src/components/ai-elements/prompt-input.tsx`] |
|
||||
| `UploadsMiddleware` + `MemoryMiddleware`（内部中间件） | repo internal | upload/mention 注入与 memory 入队清理 | 语义分层已形成：`uploaded_files` 与 `mentioned_files` 分离，memory 过滤双重防线。 [VERIFIED: codebase grep `backend/.../uploads_middleware.py`, `backend/.../memory_middleware.py`, `backend/.../memory/updater.py`] |
|
||||
|
||||
### Supporting
|
||||
| Library | Version | Purpose | When to Use |
|
||||
|---------|---------|---------|-------------|
|
||||
| `@playwright/test` | repo: `^1.48.0`; CLI: `1.48.0` | 前端 @引用 回归 | 验证 DF-INPUT-007/008/009 与 testid 合同一致性。 [VERIFIED: `frontend/package.json`; VERIFIED: command `pnpm exec playwright --version`] |
|
||||
| `pytest` via `uv run` | backend dev: `pytest>=8.0.0` | 后端 middleware/memory 回归 | 本机无全局 `pytest` 时使用 `uv run pytest`。 [VERIFIED: `backend/pyproject.toml`; VERIFIED: env check `command -v pytest`; VERIFIED: test run] |
|
||||
|
||||
### Alternatives Considered
|
||||
| Instead of | Could Use | Tradeoff |
|
||||
|------------|-----------|----------|
|
||||
| `DropdownMenu` | 自定义绝对定位浮层 | 自定义层更易与焦点管理/E2E 选择器漂移。 [VERIFIED: historical phase docs + current selector mismatch] |
|
||||
| `PromptInputAttachment` 复用 | 新建 mention-only 预览组件 | 会重复实现删除/图片缩略行为，增加 UI 行为分叉。 [VERIFIED: code comparison in `input-box.tsx` + `prompt-input.tsx`] |
|
||||
|
||||
**Installation:**
|
||||
```bash
|
||||
cd frontend && pnpm install
|
||||
cd backend && uv sync
|
||||
```
|
||||
|
||||
## Architecture Patterns
|
||||
|
||||
### Recommended Project Structure
|
||||
```text
|
||||
frontend/src/components/workspace/input-box.tsx # mention candidate + 引用预览
|
||||
frontend/src/core/threads/submit-files.ts # files envelope 归一化
|
||||
frontend/src/core/threads/hooks.ts # 发送链路 + stale 软失败
|
||||
backend/packages/harness/.../uploads_middleware.py # uploaded/mentioned 语义拆分
|
||||
backend/packages/harness/.../memory_middleware.py # 入队前剥离标签
|
||||
backend/packages/harness/.../memory/updater.py # 落盘前清理上传事件
|
||||
backend/tests/test_uploads_middleware_core_logic.py # mention/upload 后端回归
|
||||
backend/tests/test_memory_upload_filtering.py # memory 清理回归
|
||||
frontend/tests/e2e/input-and-compose.spec.ts # DF-INPUT-007/008/009
|
||||
```
|
||||
[VERIFIED: codebase grep]
|
||||
|
||||
### Pattern 1: 单一提交 Envelope + 语义位区分
|
||||
**What:** 统一走 `additional_kwargs.files`，通过 `ref_kind/ref_source` 区分 mention 与 upload。 [VERIFIED: `submit-files.ts`, `hooks.ts`, `uploads_middleware.py`]
|
||||
**When to use:** 所有消息级文件上下文（上传/引用）都应遵循。 [VERIFIED: current implementation]
|
||||
**Example:**
|
||||
```typescript
|
||||
// Source: frontend/src/core/threads/submit-files.ts
|
||||
referenceFiles.push({
|
||||
filename: reference.filename,
|
||||
size: reference.size ?? 0,
|
||||
path: reference.path,
|
||||
status: "uploaded",
|
||||
ref_kind: "mention",
|
||||
ref_source: reference.ref_source,
|
||||
});
|
||||
```
|
||||
|
||||
### Pattern 2: 输入区预览复用 `PromptInputAttachment`
|
||||
**What:** 引用预览与上传附件预览统一使用同一渲染组件。 [VERIFIED: `input-box.tsx` + `prompt-input.tsx`]
|
||||
**When to use:** 输入区顶部预览条（包含图片缩略图和删除动作）。 [VERIFIED: current UI structure]
|
||||
**Example:**
|
||||
```tsx
|
||||
// Source: frontend/src/components/workspace/input-box.tsx
|
||||
<PromptInputAttachment
|
||||
data={{ type: "file", id: `reference:${reference.ref_source}:${reference.path ?? reference.filename}`, filename, mediaType, url }}
|
||||
onRemove={() => onRemoveReference(reference)}
|
||||
/>
|
||||
```
|
||||
|
||||
### Pattern 3: 双层 memory 清理
|
||||
**What:** 入队前去标签 + 落盘前清句子/事实。 [VERIFIED: `memory_middleware.py`, `updater.py`]
|
||||
**When to use:** 任何会把会话瞬时文件路径写入上下文的中间件链路。 [VERIFIED: existing middleware design]
|
||||
**Example:**
|
||||
```python
|
||||
# Source: backend/packages/harness/deerflow/agents/middlewares/memory_middleware.py
|
||||
stripped = _UPLOAD_BLOCK_RE.sub("", content_str).strip()
|
||||
```
|
||||
|
||||
### Anti-Patterns to Avoid
|
||||
- **再开并行字段（如 `mentions`）:** 会破坏既有 `additional_kwargs.files` 消费链。 [VERIFIED: `hooks.ts`, `message-list-item.tsx`]
|
||||
- **mention 进入 `new_files`:** 会把引用误判为本次上传，污染 `<uploaded_files>`。 [VERIFIED: `uploads_middleware.py` tests]
|
||||
- **E2E 依赖不存在 testid:** `reference-chip-remove` 当前无实现，导致回归假红。 [VERIFIED: grep `reference-chip-remove` only in test files]
|
||||
|
||||
## Don't Hand-Roll
|
||||
|
||||
| Problem | Don't Build | Use Instead | Why |
|
||||
|---------|-------------|-------------|-----|
|
||||
| mention 候选浮层 | 自定义定位/焦点层 | `DropdownMenu*` 组件族 | 避免键盘焦点与收起时机出现分叉。 [VERIFIED: `input-box.tsx`] |
|
||||
| 引用缩略预览 | 新写一套 chip/thumbnail | `PromptInputAttachment` | 已含图片/文件两类渲染与 remove 交互。 [VERIFIED: `prompt-input.tsx`] |
|
||||
| memory 上传清理 | 单点字符串替换 | `memory_middleware` + `updater` 双层过滤 | 一层漏掉仍可在另一层兜底。 [VERIFIED: code + `test_memory_upload_filtering.py`] |
|
||||
|
||||
**Key insight:** Phase 07 的价值在“收口”，不是“扩面”。任何新造轮子都会重新引入 Phase 06 已解决的不一致。 [VERIFIED: phase artifacts + current code]
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
### Pitfall 1: 测试选择器漂移导致误判回归
|
||||
**What goes wrong:** E2E 断言 `reference-chip-remove` 失败，但功能未必失效。 [VERIFIED: test run output]
|
||||
**Why it happens:** 预览组件复用后删除按钮 testid 未对齐旧用例。 [VERIFIED: grep results]
|
||||
**How to avoid:** 在复用组件上补稳定选择器，或更新用例改查 aria-label。 [ASSUMED]
|
||||
**Warning signs:** `DF-INPUT-007` 单点失败且 `reference-chip` 仍可见。 [VERIFIED: test run output]
|
||||
|
||||
### Pitfall 2: mention/upload 语义回退
|
||||
**What goes wrong:** mention 被算成 `uploaded_files`。 [VERIFIED: historical issue + tests]
|
||||
**Why it happens:** `_files_from_kwargs` 未过滤 `ref_kind=mention`。 [VERIFIED: `uploads_middleware.py`]
|
||||
**How to avoid:** 保持过滤并用 mixed-list 测试守护。 [VERIFIED: `test_uploads_middleware_core_logic.py`]
|
||||
**Warning signs:** `<uploaded_files>` 出现 source=mention 的条目。 [VERIFIED: middleware behavior]
|
||||
|
||||
### Pitfall 3: 会话瞬时文件路径被写入长期 memory
|
||||
**What goes wrong:** 后续会话反复检索不存在的旧路径。 [VERIFIED: `updater.py` docstring/comments]
|
||||
**Why it happens:** 上传标签/句子未在 memory pipeline 剥离。 [VERIFIED: `memory_middleware.py`, `updater.py`]
|
||||
**How to avoid:** 保留双层清理并跑 `test_memory_upload_filtering.py`。 [VERIFIED: test pass]
|
||||
**Warning signs:** memory facts 出现 `/mnt/user-data/uploads/`。 [VERIFIED: regex intent]
|
||||
|
||||
## Code Examples
|
||||
|
||||
### mention 与 upload 分流（后端）
|
||||
```python
|
||||
# Source: backend/packages/harness/deerflow/agents/middlewares/uploads_middleware.py
|
||||
if f.get("ref_kind") == "mention":
|
||||
continue
|
||||
```
|
||||
|
||||
### 构建单一 files envelope（前端）
|
||||
```typescript
|
||||
// Source: frontend/src/core/threads/hooks.ts
|
||||
const { files: filesForSubmit, staleCount } = buildFilesForSubmit(
|
||||
uploadedFileInfo,
|
||||
normalizedReferences,
|
||||
);
|
||||
```
|
||||
|
||||
### memory 标签剥离（中间件）
|
||||
```python
|
||||
# Source: backend/packages/harness/deerflow/agents/middlewares/memory_middleware.py
|
||||
_UPLOAD_BLOCK_RE = re.compile(
|
||||
r"<(?:uploaded_files|mentioned_files)>[\\s\\S]*?</(?:uploaded_files|mentioned_files)>\\n*",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
```
|
||||
|
||||
## State of the Art
|
||||
|
||||
| Old Approach | Current Approach | When Changed | Impact |
|
||||
|--------------|------------------|--------------|--------|
|
||||
| mention 与 upload 同池处理 | `ref_kind/ref_source` 明确区分并分块注入 | Phase 06 后段（2026-04-15） | 消除“引用被当上传”副作用。 [VERIFIED: git log + middleware code] |
|
||||
| memory 仅靠提示词约束不记上传 | middleware + updater 双层代码过滤 | 已在当前工作树 | 减少长期 memory 污染。 [VERIFIED: `memory_middleware.py`, `updater.py`, tests] |
|
||||
|
||||
**Deprecated/outdated:**
|
||||
- 仅依赖文档状态判断 Phase 06 完成度（未同步会误判）。 [VERIFIED: `06-VERIFICATION.md` vs `06-UAT.md`/`REQUIREMENTS.md` 状态差异]
|
||||
|
||||
## Assumptions Log
|
||||
|
||||
| # | Claim | Section | Risk if Wrong |
|
||||
|---|-------|---------|---------------|
|
||||
| A1 | 通过补 `data-testid` 或改为 aria 断言即可稳定 DF-INPUT-007 | Common Pitfalls | 可能需要更深层 UI 结构调整。 |
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **Phase 07 是否要“改代码”还是“仅归档文档+测试修正”？**
|
||||
- What we know: 语义与 memory 主链路代码已到位。 [VERIFIED: code + tests]
|
||||
- What's unclear: 你是否接受只修测试契约与文档闭环，不再动功能实现。
|
||||
- Recommendation: 先锁定“最小变更原则”，避免 Phase 07 再引入行为漂移。 [ASSUMED]
|
||||
|
||||
2. **E2E 断言口径是否改为可访问性语义？**
|
||||
- What we know: `reference-chip-remove` testid 当前缺失。 [VERIFIED: grep + test output]
|
||||
- What's unclear: 团队更偏好稳定 testid 还是 aria 文案断言。
|
||||
- Recommendation: 若追求跨重构稳定，优先 aria；若追求低改动，补 testid。 [ASSUMED]
|
||||
|
||||
## Environment Availability
|
||||
|
||||
| Dependency | Required By | Available | Version | Fallback |
|
||||
|------------|------------|-----------|---------|----------|
|
||||
| Node.js | frontend tests/tooling | ✓ | v24.14.0 | — |
|
||||
| pnpm | frontend scripts | ✓ | 10.32.1 | `npm`（不推荐，lockfile 不一致） |
|
||||
| Playwright CLI | DF-INPUT E2E | ✓ | 1.48.0 | — |
|
||||
| Python | backend tests | ✓ | 3.12.3 | — |
|
||||
| uv | backend test runner | ✓ | 0.10.10 | — |
|
||||
| pytest (global) | backend tests | ✗ | — | `uv run pytest` |
|
||||
|
||||
[VERIFIED: local command checks]
|
||||
|
||||
**Missing dependencies with no fallback:**
|
||||
- None. [VERIFIED: local checks]
|
||||
|
||||
**Missing dependencies with fallback:**
|
||||
- 全局 `pytest` 缺失；使用 `uv run pytest`。 [VERIFIED: local checks + successful runs]
|
||||
|
||||
## Validation Architecture
|
||||
|
||||
### Test Framework
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Framework | Node test runner + Playwright + pytest (via uv) |
|
||||
| Config file | `frontend/playwright.config.ts`, `backend/pyproject.toml` |
|
||||
| Quick run command | `cd frontend && node --test src/core/threads/hooks.test.ts` |
|
||||
| Full suite command | `cd backend && uv run pytest -q tests/test_uploads_middleware_core_logic.py tests/test_memory_upload_filtering.py && cd ../frontend && pnpm -s test:e2e --grep "DF-INPUT-007|DF-INPUT-008|DF-INPUT-009"` |
|
||||
|
||||
[VERIFIED: codebase files + executed commands]
|
||||
|
||||
### Phase Requirements → Test Map
|
||||
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
||||
|--------|----------|-----------|-------------------|-------------|
|
||||
| P7-SEM-01 | mention 不计入 new upload | unit | `cd backend && uv run pytest -q tests/test_uploads_middleware_core_logic.py -k "mention or files_from_kwargs"` | ✅ |
|
||||
| P7-MEM-01 | memory 不保留上传事件 | unit | `cd backend && uv run pytest -q tests/test_memory_upload_filtering.py` | ✅ |
|
||||
| P7-UI-01 | @候选/引用 chip 交互稳定 | e2e | `cd frontend && pnpm -s test:e2e --grep "DF-INPUT-007|DF-INPUT-008|DF-INPUT-009"` | ✅（当前有失败） |
|
||||
| P7-DOC-01 | 验收状态文档闭环 | docs check | `rg -n "ATREF-01|ATREF-02|ATREF-03|ATREF-04|status:" .planning/REQUIREMENTS.md .planning/phases/06-/06-UAT.md .planning/phases/06-/06-VALIDATION.md` | ✅ |
|
||||
|
||||
### Sampling Rate
|
||||
- **Per task commit:** 对应最小命令（前端 unit 或后端 targeted pytest）。 [VERIFIED: commit guide + current tests]
|
||||
- **Per wave merge:** 跑后端双测 + 前端三条 E2E。 [VERIFIED: current phase scope]
|
||||
- **Phase gate:** 三类测试全绿且文档状态同步后再进入 verify-work。 [VERIFIED: verification gaps]
|
||||
|
||||
### Wave 0 Gaps
|
||||
- [ ] `frontend/tests/e2e/input-and-compose.spec.ts` 与组件选择器合同未对齐（`reference-chip-remove`）。 [VERIFIED: test failure + grep]
|
||||
- [ ] `.planning/phases/06-/06-UAT.md` 状态未回写到最新结果。 [VERIFIED: file content]
|
||||
- [ ] `.planning/REQUIREMENTS.md` 中 `ATREF-01..04` 仍 Pending。 [VERIFIED: file content]
|
||||
|
||||
## Security Domain
|
||||
|
||||
### Applicable ASVS Categories
|
||||
| ASVS Category | Applies | Standard Control |
|
||||
|---------------|---------|-----------------|
|
||||
| V2 Authentication | no | 本 phase 不新增 auth 面。 [VERIFIED: scope] |
|
||||
| V3 Session Management | no | 不改会话机制。 [VERIFIED: scope] |
|
||||
| V4 Access Control | yes | mention 候选限定当前 thread 数据源。 [VERIFIED: `input-box.tsx` + phase docs] |
|
||||
| V5 Input Validation | yes | 后端 `_files_from_kwargs` 校验 filename/path。 [VERIFIED: `uploads_middleware.py`] |
|
||||
| V6 Cryptography | no | 无加密实现变更。 [VERIFIED: scope] |
|
||||
|
||||
### Known Threat Patterns for this phase stack
|
||||
| Pattern | STRIDE | Standard Mitigation |
|
||||
|---------|--------|---------------------|
|
||||
| 跨线程文件引用泄露 | Information Disclosure | 候选仅取当前 thread artifacts/uploads。 [VERIFIED: `input-box.tsx`] |
|
||||
| 伪造 `additional_kwargs.files` 注入 | Tampering | 后端校验 basename 与 `/mnt/user-data/` 前缀。 [VERIFIED: `uploads_middleware.py`] |
|
||||
| memory 泄露临时路径 | Information Disclosure | middleware + updater 双层过滤上传标签与句子。 [VERIFIED: memory code + tests] |
|
||||
|
||||
## Sources
|
||||
|
||||
### Primary (HIGH confidence)
|
||||
- 本仓库代码：`frontend/src/components/workspace/input-box.tsx`、`frontend/src/components/ai-elements/prompt-input.tsx`、`frontend/src/core/threads/hooks.ts`、`frontend/src/core/threads/submit-files.ts`。 [VERIFIED: codebase grep]
|
||||
- 本仓库代码：`backend/packages/harness/deerflow/agents/middlewares/uploads_middleware.py`、`memory_middleware.py`、`memory/updater.py`。 [VERIFIED: codebase grep]
|
||||
- 本地执行结果：`node --test`, `uv run pytest`, `pnpm test:e2e --grep ...`。 [VERIFIED: command output]
|
||||
- npm registry：`@radix-ui/react-dropdown-menu`、`sonner` 版本与发布时间。 [VERIFIED: npm view]
|
||||
|
||||
### Secondary (MEDIUM confidence)
|
||||
- `.planning/phases/06-/06-VERIFICATION.md`、`06-UAT.md`、`06-VALIDATION.md`、`.planning/REQUIREMENTS.md` 的状态交叉对比。 [VERIFIED: local docs]
|
||||
|
||||
### Tertiary (LOW confidence)
|
||||
- None.
|
||||
|
||||
## Metadata
|
||||
|
||||
**Confidence breakdown:**
|
||||
- Standard stack: HIGH - 基于当前仓库依赖与 npm registry 实查。
|
||||
- Architecture: HIGH - 关键链路均有代码与测试证据。
|
||||
- Pitfalls: MEDIUM - 一部分为当前失败现象，一部分为经验性防回退建议。
|
||||
|
||||
**Research date:** 2026-04-15
|
||||
**Valid until:** 2026-05-15（30 天）
|
||||
Loading…
Reference in New Issue