180 lines
7.6 KiB
Markdown
180 lines
7.6 KiB
Markdown
---
|
||
phase: 02-thread-and-skills-logic-reconciliation
|
||
plan: 01
|
||
type: execute
|
||
wave: 1
|
||
depends_on: []
|
||
files_modified:
|
||
- frontend/src/app/workspace/chats/[thread_id]/page.tsx
|
||
- frontend/src/core/threads/hooks.ts
|
||
- frontend/src/core/skills/api.ts
|
||
- frontend/src/components/workspace/chats/use-thread-chat.ts
|
||
- frontend/src/core/uploads/api.ts
|
||
- frontend/src/core/threads/types.ts
|
||
- frontend/src/core/threads/utils.ts
|
||
- frontend/src/core/skills/types.ts
|
||
- frontend/tests/e2e/thread-routing.spec.ts
|
||
- frontend/src/core/threads/hooks.test.ts
|
||
- frontend/src/core/skills/api.test.ts
|
||
autonomous: true
|
||
requirements:
|
||
- MERGE-02
|
||
- LOGIC-03
|
||
- LOGIC-04
|
||
must_haves:
|
||
truths:
|
||
- "`thread_id/isnew/xclaw_used` 行为与新逻辑一致，缺失语义被删除，不再走旧分支。"
|
||
- "skills bootstrap 合同与新逻辑一致，`content_id/content_ids` 冲突被显式归一。"
|
||
- "聊天主流程只有一条逻辑路径，不再存在重复/死分支。"
|
||
artifacts:
|
||
- path: "frontend/src/app/workspace/chats/[thread_id]/page.tsx"
|
||
provides: "路由参数入口与新逻辑对齐"
|
||
- path: "frontend/src/core/threads/hooks.ts"
|
||
provides: "线程主逻辑单路径"
|
||
- path: "frontend/src/core/skills/api.ts"
|
||
provides: "skills bootstrap 合同归一入口"
|
||
- path: "frontend/src/core/threads/hooks.test.ts"
|
||
provides: "线程逻辑回归保护"
|
||
- path: "frontend/src/core/skills/api.test.ts"
|
||
provides: "合同归一回归保护"
|
||
key_links:
|
||
- from: "page.tsx"
|
||
to: "core/threads/hooks.ts"
|
||
via: "参数归一后调用核心 hooks"
|
||
pattern: "thread_id|isnew|xclaw_used"
|
||
- from: "skills/api.ts"
|
||
to: "bootstrap payload"
|
||
via: "content_id/content_ids 显式归一"
|
||
pattern: "content_id|content_ids"
|
||
---
|
||
|
||
<objective>
|
||
完成 Phase 2 的线程与 skills 逻辑收敛：以新逻辑为唯一主路径，删除旧分支并建立回归保护。
|
||
|
||
Purpose: 落实 D-01/D-02/D-03，消除 merge 遗留的多路径行为风险。
|
||
Output: 路由参数对齐、skills 合同归一、重复逻辑删除、对应自动化测试。
|
||
</objective>
|
||
|
||
<context>
|
||
@.planning/PROJECT.md
|
||
@.planning/REQUIREMENTS.md
|
||
@.planning/ROADMAP.md
|
||
@.planning/phases/02-thread-and-skills-logic-reconciliation/02-CONTEXT.md
|
||
@.planning/phases/01-conflict-inventory-and-decision-matrix/conflict-inventory.csv
|
||
@.planning/phases/01-conflict-inventory-and-decision-matrix/titan-decision-matrix.md
|
||
@frontend/src/app/workspace/chats/[thread_id]/page.tsx
|
||
@frontend/src/core/threads/hooks.ts
|
||
@frontend/src/core/skills/api.ts
|
||
</context>
|
||
|
||
<tasks>
|
||
|
||
<task type="auto" tdd="true">
|
||
<name>Task 1: 线程路由参数与新逻辑单路径对齐（D-01, D-03）</name>
|
||
<files>
|
||
frontend/src/app/workspace/chats/[thread_id]/page.tsx
|
||
frontend/src/core/threads/hooks.ts
|
||
frontend/src/core/threads/types.ts
|
||
frontend/src/core/threads/utils.ts
|
||
frontend/src/components/workspace/chats/use-thread-chat.ts
|
||
frontend/src/core/threads/hooks.test.ts
|
||
</files>
|
||
<behavior>
|
||
- Test 1: `isnew=true` 时强制走新线程分支，忽略旧兼容分支。
|
||
- Test 2: 有 `thread_id` 且非 `isnew` 时复用现有线程。
|
||
- Test 3: `xclaw_used` 仅在新逻辑支持的语义下保留；不支持则删除相关分支。
|
||
</behavior>
|
||
<action>
|
||
按 D-01 将 `thread_id/isnew/xclaw_used` 全量对齐到新逻辑语义；按 D-03 删除 page/component/core 内重复或死分支，保证“参数解析 -> core hooks”单路径。若某参数在新逻辑无定义，直接删除对应旧逻辑与调用链。
|
||
</action>
|
||
<verify>
|
||
<automated>cd frontend && npm run test -- src/core/threads/hooks.test.ts</automated>
|
||
</verify>
|
||
<done>
|
||
参数行为与新逻辑一致，且核心线程流程无重复分支。
|
||
</done>
|
||
</task>
|
||
|
||
<task type="auto" tdd="true">
|
||
<name>Task 2: skills bootstrap 合同归一到新逻辑（D-02, D-03）</name>
|
||
<files>
|
||
frontend/src/core/skills/api.ts
|
||
frontend/src/core/uploads/api.ts
|
||
frontend/src/core/skills/types.ts
|
||
frontend/src/core/skills/api.test.ts
|
||
</files>
|
||
<behavior>
|
||
- Test 1: 新主合同字段按新逻辑生效。
|
||
- Test 2: 旧字段输入可被最小兼容层归一到新合同。
|
||
- Test 3: 不再存在双主合同并行分支。
|
||
</behavior>
|
||
<action>
|
||
以 D-02 为准在 `core/skills/api.ts` 建立唯一合同入口，显式处理 `content_id/content_ids` 归一；旧字段只保留最小兼容层并集中在单位置，删除其它重复转换逻辑（D-03）。同步更新上传/调用链类型定义，避免隐式 any 与分支漂移。
|
||
</action>
|
||
<verify>
|
||
<automated>cd frontend && npm run test -- src/core/skills/api.test.ts</automated>
|
||
</verify>
|
||
<done>
|
||
skills bootstrap 请求只走一套主合同路径，兼容层最小且可审计。
|
||
</done>
|
||
</task>
|
||
|
||
<task type="auto" tdd="true">
|
||
<name>Task 3: 端到端回归与死分支清理验证（MERGE-02, LOGIC-03, LOGIC-04）</name>
|
||
<files>
|
||
frontend/tests/e2e/thread-routing.spec.ts
|
||
frontend/src/core/threads/hooks.test.ts
|
||
frontend/src/core/skills/api.test.ts
|
||
</files>
|
||
<behavior>
|
||
- Test 1: 覆盖 `thread_id/isnew/xclaw_used` 关键组合的行为断言。
|
||
- Test 2: 覆盖 skills 合同归一场景（新合同、旧字段兼容、冲突输入）。
|
||
- Test 3: 用测试断言保障“旧分支已删除”不会被回带。
|
||
</behavior>
|
||
<action>
|
||
为 Phase 2 的关键风险建立自动化回归网：补齐 core 单测与最小 E2E（线程创建/复用 + skills bootstrap 调用路径），并在测试中显式断言旧路径不再可达，确保后续 Phase 3 只改视觉不回退逻辑。
|
||
</action>
|
||
<verify>
|
||
<automated>cd frontend && npm run test -- src/core/threads/hooks.test.ts src/core/skills/api.test.ts && npm run test:e2e -- thread-routing.spec.ts</automated>
|
||
</verify>
|
||
<done>
|
||
Phase 2 逻辑收敛具备可重复验证能力，后续视觉阶段可安全衔接。
|
||
</done>
|
||
</task>
|
||
|
||
</tasks>
|
||
|
||
<threat_model>
|
||
## Trust Boundaries
|
||
|
||
| Boundary | Description |
|
||
|----------|-------------|
|
||
| `route query -> core threads` | URL 参数为不可信输入，进入线程逻辑前必须归一 |
|
||
| `UI payload -> skills bootstrap api` | 前端输入字段可能混用旧/新合同，需要单入口收敛 |
|
||
|
||
## STRIDE Threat Register
|
||
|
||
| Threat ID | Category | Component | Disposition | Mitigation Plan |
|
||
|-----------|----------|-----------|-------------|-----------------|
|
||
| T-02-01 | T (Tampering) | `threads parameter parsing` | mitigate | 在路由入口做参数白名单与归一，删除未知旧语义分支 |
|
||
| T-02-02 | R (Repudiation) | `skills contract mapping` | mitigate | `content_id/content_ids` 映射逻辑集中单文件并加测试断言 |
|
||
| T-02-03 | D (Denial of Service) | `duplicate branches` | mitigate | 删除重复/死分支，防止分支漂移导致异常循环或重复请求 |
|
||
| T-02-04 | I (Information Disclosure) | `legacy fallback paths` | accept | 本阶段仅做前端逻辑收敛，不引入新数据暴露面 |
|
||
</threat_model>
|
||
|
||
<verification>
|
||
1. 任务内 `<automated>` 命令全部返回 0。
|
||
2. 手动抽查 `page.tsx -> core/threads/hooks.ts` 调用链只剩单路径。
|
||
3. 抽查 `core/skills/api.ts` 的合同归一逻辑，确认旧字段仅保留最小兼容层。
|
||
</verification>
|
||
|
||
<success_criteria>
|
||
- MERGE-02：merge 覆写导致的旧逻辑分支被清理，主流程收敛到新逻辑单路径。
|
||
- LOGIC-03：`thread_id/isnew/xclaw_used` 行为与新逻辑一致并可测试验证。
|
||
- LOGIC-04：skills bootstrap 合同冲突被显式归一，且无双主合同并行。
|
||
</success_criteria>
|
||
|
||
<output>
|
||
After completion, create `.planning/phases/02-thread-and-skills-logic-reconciliation/02-SUMMARY.md`
|
||
</output>
|