diff --git a/.planning/phases/02-thread-and-skills-logic-reconciliation/02-PLAN.md b/.planning/phases/02-thread-and-skills-logic-reconciliation/02-PLAN.md new file mode 100644 index 00000000..a56b7641 --- /dev/null +++ b/.planning/phases/02-thread-and-skills-logic-reconciliation/02-PLAN.md @@ -0,0 +1,179 @@ +--- +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" +--- + + +完成 Phase 2 的线程与 skills 逻辑收敛:以新逻辑为唯一主路径,删除旧分支并建立回归保护。 + +Purpose: 落实 D-01/D-02/D-03,消除 merge 遗留的多路径行为风险。 +Output: 路由参数对齐、skills 合同归一、重复逻辑删除、对应自动化测试。 + + + +@.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 + + + + + + Task 1: 线程路由参数与新逻辑单路径对齐(D-01, D-03) + + 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 + + + - Test 1: `isnew=true` 时强制走新线程分支,忽略旧兼容分支。 + - Test 2: 有 `thread_id` 且非 `isnew` 时复用现有线程。 + - Test 3: `xclaw_used` 仅在新逻辑支持的语义下保留;不支持则删除相关分支。 + + + 按 D-01 将 `thread_id/isnew/xclaw_used` 全量对齐到新逻辑语义;按 D-03 删除 page/component/core 内重复或死分支,保证“参数解析 -> core hooks”单路径。若某参数在新逻辑无定义,直接删除对应旧逻辑与调用链。 + + + cd frontend && npm run test -- src/core/threads/hooks.test.ts + + + 参数行为与新逻辑一致,且核心线程流程无重复分支。 + + + + + Task 2: skills bootstrap 合同归一到新逻辑(D-02, D-03) + + 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 + + + - Test 1: 新主合同字段按新逻辑生效。 + - Test 2: 旧字段输入可被最小兼容层归一到新合同。 + - Test 3: 不再存在双主合同并行分支。 + + + 以 D-02 为准在 `core/skills/api.ts` 建立唯一合同入口,显式处理 `content_id/content_ids` 归一;旧字段只保留最小兼容层并集中在单位置,删除其它重复转换逻辑(D-03)。同步更新上传/调用链类型定义,避免隐式 any 与分支漂移。 + + + cd frontend && npm run test -- src/core/skills/api.test.ts + + + skills bootstrap 请求只走一套主合同路径,兼容层最小且可审计。 + + + + + Task 3: 端到端回归与死分支清理验证(MERGE-02, LOGIC-03, LOGIC-04) + + frontend/tests/e2e/thread-routing.spec.ts + frontend/src/core/threads/hooks.test.ts + frontend/src/core/skills/api.test.ts + + + - Test 1: 覆盖 `thread_id/isnew/xclaw_used` 关键组合的行为断言。 + - Test 2: 覆盖 skills 合同归一场景(新合同、旧字段兼容、冲突输入)。 + - Test 3: 用测试断言保障“旧分支已删除”不会被回带。 + + + 为 Phase 2 的关键风险建立自动化回归网:补齐 core 单测与最小 E2E(线程创建/复用 + skills bootstrap 调用路径),并在测试中显式断言旧路径不再可达,确保后续 Phase 3 只改视觉不回退逻辑。 + + + 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 + + + Phase 2 逻辑收敛具备可重复验证能力,后续视觉阶段可安全衔接。 + + + + + + +## 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 | 本阶段仅做前端逻辑收敛,不引入新数据暴露面 | + + + +1. 任务内 `` 命令全部返回 0。 +2. 手动抽查 `page.tsx -> core/threads/hooks.ts` 调用链只剩单路径。 +3. 抽查 `core/skills/api.ts` 的合同归一逻辑,确认旧字段仅保留最小兼容层。 + + + +- MERGE-02:merge 覆写导致的旧逻辑分支被清理,主流程收敛到新逻辑单路径。 +- LOGIC-03:`thread_id/isnew/xclaw_used` 行为与新逻辑一致并可测试验证。 +- LOGIC-04:skills bootstrap 合同冲突被显式归一,且无双主合同并行。 + + + +After completion, create `.planning/phases/02-thread-and-skills-logic-reconciliation/02-SUMMARY.md` +