sync: complete remaining files (source ji)

docs/agentscope-多智能体报告协作工作台-交互重设计方案.md

@@ -0,0 +1,188 @@
+# 报告协作工作台 — 交互重设计方案（v2）
+
+> 日期：2026-09-07
+> 状态：**待确认**（确认后按 §7 分期实施）
+> 取代：现行「规则澄清 + 三张模板方案卡 + 画布为主」的交互
+> 原则：回到最初设计 —— **协调者智能体全程与用户对话的主线**
+
+---
+
+## 1. 设计目标与总体形态
+
+用户视角只有一条主线：**和一个规划师智能体对话 → 它摸清意图并规划工作流 → 确认后执行、过程在流程图上可见 → 随时插话干预、指定智能体重跑 → 最终成稿、继续对话式修改**。
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  阶段1 计划模式        阶段2/3 执行+干预      阶段4 成稿  │
+│  ┌───────────┐        ┌───────────┐        ┌──────────┐ │
+│  │ 规划师对话 │  确认   │ 聊天时间线 │  审稿过 │ 对话改稿 │ │
+│  │ 需求摘要卡 │ ─────→ │ +成员Tab  │ ─────→ │ 版本/diff│ │
+│  │ 工作流卡   │  冻结   │ +流程图动画│  报告卡 │ 上游重跑 │ │
+│  └───────────┘        └───────────┘        └──────────┘ │
+│        ↑ 回到计划模式（replan）随时可触发 ↑                │
+└─────────────────────────────────────────────────────────┘
+```
+
+与现行的核心差异：
+
+| 维度 | 现行（做偏的） | v2 |
+|------|----------------|-----|
+| 需求澄清 | 规则模板问句秒回 | 规划师智能体（LLM）领域化提问 |
+| 工作流来源 | 3 张确定性模板 | LLM 按意图生成自定义 DAG，对话迭代修改 |
+| 执行展示 | 画布为主、聊天为辅 | **聊天时间线为主**（成员 Tab 切换保留），**执行状态在流程图上动画呈现** |
+| 干预 | 命令确认卡体系 | 输入框常开 → 协调者智能体分类；支持**指定智能体重跑** |
+| 报告修改 | 改写候选（纯文字层） | 意图分流：润色走改写；**事实性问题触发上游节点重跑** |
+
+---
+
+## 2. 阶段 1：计划模式 — 需求梳理与工作流规划
+
+### 2.1 计划模式状态
+
+- 用户发出第一条需求消息起进入**计划模式**，Header 显示徽章「📋 计划模式」，输入框提示语切换为「梳理需求中，你可以随时补充或纠正…」。
+- 计划模式在**工作流确认冻结**时结束；执行期大改可通过 replan 回到计划模式（见 §5.4）。
+
+### 2.2 规划师对话（LLM，替换现行规则路由）
+
+- 必须调用独立内置智能体 `report-collaboration-intent` 的真实 LangGraph thread，并原样消费 `messages-tuple` SSE；禁止用 `ainvoke()` 等待完整 JSON 后再包装成一话。
+- 流式正文、思考内容和工具步骤直接进入工作台现有 `MessageList`，与普通智能体问答采用同一套步骤条 / Reasoning 展示。
+- 模型：`report_collaboration.planner_model`（回退 `coordinator_model` → 默认模型，复用现有 model_resolver 冻结机制）。
+- 提问是领域化的：写市场分析就问「关注整车还是供应链 / 要不要竞品对比 / 给谁看 / 篇幅」，而非固定模板问句。
+- 澄清轮次上限沿用 `max_clarification_rounds`；用户随时可以说「直接开始」按默认假设推进。
+
+### 2.3 需求摘要卡
+
+信息足够后，规划师在对话中输出一张**结构化需求摘要卡**（业务卡插槽渲染）：主题 / 目的 / 读者 / 角度清单 / 篇幅与重点 / 默认假设。用户逐项看，可在对话里继续改（「读者改成投资人」→ 卡片更新出新版）。
+
+### 2.4 工作流生成与迭代
+
+- 规划师判断意图信息足够后，立即按已确认意图自动生成**一份**工作流方案（不是三选一），不再要求用户额外点击“确认意图/生成方案”；方案以工作流卡（成员构成、各节点使命、预计时长/成本）+ 右侧流程图预览呈现。
+- 生成约束（保证可执行）：**节点类型受词表约束** — `research / verify / analyze / write / review`；自由的是结构（几条线、并行还是串行、核验深度）与每个节点的使命/角度/工具。
+- 对话式修改：「把价格策略单独拆一条线」「加一个政策风险分析」→ 规划师修订后出新版工作流卡（带变更说明），再确认。
+- 「开始执行」→ 冻结需求 + 工作流（含模型/预算快照，沿用现有 freeze 机制）。
+
+---
+
+## 3. 阶段 2：执行 — 过程在流程图上可见
+
+### 3.1 流程图动画规格（执行状态的可视化主载体）
+
+节点状态 → 样式（`ReportFlowCanvas` / `ReportFlowNode`，状态源 `selectNodeStatusMap`，事件源 `node.status.changed` SSE）：
+
+| 状态 | 节点样式 | 连入边 |
+|------|----------|--------|
+| planned / queued | 灰色常态 | 静态 |
+| **running** | 主色描边 + **呼吸脉冲动画**（ring）+ 角标 spinner | **流动动画**（@xyflow 内置 `animated: true` 的 dash 流动） |
+| **completed** | 绿色 + ✓ 角标，常驻 | 恢复静态实线 |
+| failed | 红色 + 错误角标 | 红色虚线 |
+| awaiting_input | 橙色 + ？角标 | 橙色静态 |
+| interrupted / superseded | 半透明降级 | 灰 |
+
+- 语义：**边流动 = 数据正在流入该节点**（该节点执行中）；节点完成即停动画换完成样式。
+- 实现成本：@xyflow 原生支持 animated 边与自定义节点 className，纯 CSS 补呼吸动画即可，无需新依赖。
+
+### 3.2 聊天区（保留现有 Tab 切换）
+
+- 并行成员沿用 **AgentStageSelector Tab 切换**（维持现状，不改交错时间线）。
+- 每个 Tab 内是该成员的完整流式输出：思考、工具调用卡、检索过程、正文 —— 与普通智能体问答同观感（message-adapter 已具备映射能力）。
+- 协调者播报（「研究线 A 完成，核心发现 X，开始交叉核验」）进入总时间线 Tab。
+
+---
+
+## 4. 阶段 3：干预 — 对话即干预 + 指定重跑
+
+### 4.1 输入框常开，协调者智能体分流
+
+执行期输入框永远可用，所有输入先到协调者（LLM 分类，规则高精度直判兜底——复用 RC-BE-014 IntentRouter 骨架，把「规则优先」反转为「LLM 优先 + 规则快路径」）：
+
+| 用户意图 | 协调者行为 | 生效时机 |
+|----------|-----------|----------|
+| 提问（「查到什么了？」） | 直接回答 | 立即，不打断 |
+| 修正方向（「重点看下沉市场」） | 小改：在安全点注入 overlay，并回复说明 | 下个安全点 |
+| **指定重跑**（见 §4.2） | 出确认卡 → 重开节点 attempt | 确认后 |
+| 大改（砍线/加线） | 提议 replan → 回计划模式 | 用户确认 |
+| 停止 | 直接取消 | 立即 |
+
+### 4.2 指定智能体重跑（新增核心交互）
+
+**场景**：用户发现某节点传给下游的信息不对（如研究线 B 的结论有误）。
+
+两个入口，同一后端动作：
+
+1. **对话**：「研究线 B 的结果不对，重新查，重点看价格战」→ 协调者解析出 `node_id` + 新指令；
+2. **画布**：点节点 → 抽屉（NodeInspectorDrawer）加「↻ 重新执行」按钮。
+
+**级联规则**（复用并补全 ledger 的 targeted rework）：
+
+```
+重跑节点 N（attempt+1，带用户新指令作为 mission overlay）
+  → N 完成 → 所有直接/间接依赖 N 产物的下游节点标记 superseded
+  → 按 DAG 依赖序逐波重跑（边动画重新流动，用户全程可见）
+  → 受影响章节重新生成
+```
+
+- 确认卡必须展示**影响面**：「将级联重跑 核验B / 分析 / 写作 共 3 个节点，预计 +8 分钟」。
+- 成本保护：级联重跑计入 run 预算（现有 budget 机制），预算不足时明确报因。
+
+---
+
+## 5. 阶段 4：报告成稿与对话式修改
+
+### 5.1 成稿
+
+审稿通过 → 报告卡出现在时间线（点开 ReportPreviewDialog 全文），协调者播报总结（各线核心发现 → 结论如何形成）。
+
+### 5.2 修改意图分流（协调者 LLM 判定）
+
+| 用户说 | 判定 | 动作 |
+|--------|------|------|
+| 「把第二章结论写得更笃定」 | 文字润色 | 改写候选（现有 rewrite API）→ 对比预览 → apply → 新版本 |
+| 「这个数据不对 / 重新收集一下」 | **事实性问题** | 定位来源节点 → **触发该节点重跑（可带新角度）→ 级联 §4.2 → 受影响章节重生成 → 新版本** |
+| 「再从供应链角度补一节」 | 结构性新增 | replan：回计划模式改工作流（只增不删已完成部分） |
+| 「恢复到上一版」 | 版本回退 | 现有 restore API |
+
+- 版本链：每次 apply / restore / 级联重跑产出均产生新 head，历史完整保留（现有机制）。
+- 修改对话里协调者必须先**复述理解**（「你是想让研究线 B 换个角度重查，然后重写第三章，对吗？」）再执行，避免误触发昂贵的级联。
+
+---
+
+## 6. 工程改造清单
+
+### 6.1 保留（本次联调已验证）
+
+- 持久化 13 张表 + durable SSE + `after_seq` 断线续传；幂等键 / 乐观锁 / 预算框架。
+- MessageList 复用链路（message-adapter → LangGraph Message → 业务卡插槽）。
+- AgentStageSelector Tab、commands 安全点骨架（RC-BE-014）、报告版本三件套（RC-BE-015）、前端 hooks/reducer/selectors 主体。
+- 「清空历史」「生成候选方案」等本次新增入口。
+
+### 6.2 后端重做 / 新建
+
+| 项 | 说明 |
+|----|------|
+| 规划师智能体 | LLM 多轮澄清（替换 `requirement/intent_router.py` 规则路由）+ 需求摘要结构化 + **工作流 LLM 生成**（受 §2.4 词表约束，替换 `planning/controller.py` 三模板）+ 对话式工作流修订 |
+| 协调者智能体升级 | 干预分类 LLM 优先；修改意图分流（§5.2）；执行前复述确认 |
+| 指定重跑 + 级联 | ledger targeted rework 补全级联 superseded/重跑波次；确认卡带影响面计算 |
+| AgentScope 适配器修复 | `count_tokens` 协议缺失（上下文压缩必崩）；attempt 耗尽终态化（防僵尸 run） |
+| 事件补齐 | 边流动所需的节点状态事件已有；补「级联影响预告」事件 |
+
+### 6.3 前端重做 / 新建
+
+| 项 | 说明 |
+|----|------|
+| 计划模式 UI | Header 徽章、composer 提示切换、需求摘要卡、工作流卡（替换现三张模板卡） |
+| 流程图动画 | running 节点呼吸动画 + 入边 `animated`、completed ✓ 样式、级联重跑时边动画重流（§3.1） |
+| 节点抽屉 | 加「重新执行」按钮 → 确认卡 |
+| 干预交互 | 执行期输入框常开；意图确认卡（含影响面）；修改对话复述确认 |
+| 布局 | 聊天为主、画布为辅的默认比例微调（不动整体两栏结构） |
+
+---
+
+## 7. 实施分期
+
+| 期 | 内容 | 验收 |
+|----|------|------|
+| **P0 地基** | AgentScope `count_tokens` 修复；attempt 耗尽终态化；级联重跑的 ledger 补全 | 执行阶段不崩、无僵尸 run、单节点重跑级联正确（后端测试） |
+| **P1 计划模式 + 执行可视化** | 规划师 LLM 对话、需求摘要卡、工作流 LLM 生成与迭代、计划模式 UI、流程图动画 | 从新会话到确认工作流全程对话完成；执行时动画正确随状态流转 |
+| **P2 干预 + 成稿修改** | 协调者 LLM 分类、指定重跑（两入口 + 影响面确认卡）、报告修改意图分流、上游级联重跑 | 四类干预各自走通；「数据不对→重跑→新章节→新版本」全链路 |
+
+每期结束跑 RC 全量测试（当前基线 233 通过）+ 前端 26 单测，不引入对其他模块的影响。

docs/agentscope-多智能体报告协作工作台-前端对接指南.md

@@ -229,23 +229,27 @@ sequenceDiagram
 
 ```http
 POST /api/report-collaboration/sessions
-POST /api/report-collaboration/sessions/{sessionId}/messages
-Content-Type: application/json
-
-{ "text": "请写一份…", "target_node_id": null, "agent_run_id": null }
+POST /api/intent/init
+POST /api/intent/stream
+POST /api/report-collaboration/sessions/{sessionId}/intent-turns
 ```
 
-- `useReportCollaborationSession.send()`：当 `session.status` 不是 `running` / `awaiting_input` / `reviewing` 时走 `sendMessage`。
+- 报告页面固定调用内置 `report-collaboration-intent` 智能体；`/api/intent/stream` 原样透传 LangGraph `messages-tuple`，不是等待模型完成后包装响应。
+- 正文 token、provider reasoning 和工具调用步骤实时写入当前 `MessageList` 气泡；终态后 `/intent-turns` 只负责持久化镜像与状态交接，不再调用模型识别意图。
+- 旧 `/sessions/{sessionId}/messages` 在 `empty/clarifying` 阶段返回 `409 USE_STREAMING_INTENT`，防止退回阻塞式 `ainvoke` 路径。
 - 会话状态：`empty` → `clarifying` → `planning` → `proposal_ready`。
 - 澄清问题以 `CollaborationMessage` 进入时间线；业务卡通过 `MessageList` 的 `businessCardSlot` 渲染（`additional_kwargs.report_collaboration_card`）。
+- 意图智能体输出 `INTENT_READY` 后，`POST /intent-turns` 自动创建并完成 `plan_request`；前端无需再展示“确认意图”或“生成候选方案”按钮。
 
 ### 5.3 阶段 2：候选方案
 
 ```http
-POST /api/report-collaboration/sessions/{sessionId}/plan-requests
+# 正常路径：由最后一轮 POST /messages 自动触发规划
 POST /api/report-collaboration/sessions/{sessionId}/plans/{planId}/select
 ```
 
+- `POST /plan-requests` 仅保留给“重新生成”与兼容调用，不是首次规划的必经步骤。
+- 规划师尚未判定 `ready` 时直接调用该兼容接口会返回 `422 REQUIREMENT_NOT_READY`，防止跳过意图确认。
 - **预览方案**（`previewPlanId`）：纯前端，不调 API。
 - **采用方案**：`select` 写 `selected_plan_id`，**不**创建 run。
 - 409：方案 revision 过期 → 前端 `refreshSnapshot`，提示用户重选。

docs/daily-usage-audit-20260914.md

@@ -0,0 +1,31 @@
+# 日常使用复查（2026-09-14）
+
+范围：ji 分支上继续检查知识库管理、助手知识库、我的项目、项目问答和官方入口。沿用本地隔离后端数据目录 `.runtime/ji-acceptance`，浏览器检查 464×642 与 1440×900 两种尺寸；未向生产库写入验收项目。
+
+## 发现与修复
+
+**首屏白屏的直接业务触发点也已修复：** `LlmWikiKnowledgeSelector` 在懒加载/未加载知识目录时，每次渲染创建新的空数组，推荐问题 effect 随之回写父页状态，形成无限更新。将目录空结果和默认助手库选择稳定化后，重新从登录进入新对话成功，欢迎引导、输入框及知识空间下拉均可操作（截图 06）。仅升级依赖并不能消除这个业务循环；上述修复与依赖兼容更新共同保留。
+
+1. **首次进入：高影响，已修复依赖。** 本轮首次登录后出现整页空白，控制台为 ScrollArea `Maximum update depth exceeded`。安装版本 1.2.10 使用不稳定引用回调；升级并锁定 1.2.18，同步 package-lock，核对源码使用稳定 setState 引用。冷启动仍复现组合引用循环，进一步发现各基础组件带入 Slot 1.2.3/1.2.4；统一锁定 Slot 1.3.3，npm 与 pnpm 均配置覆盖间接依赖。依据 [Radix 发布记录](https://www.radix-ui.com/primitives/docs/overview/releases) 的 React 19 无限重渲染及 Slot 引用修复。
+2. **新建项目：已修复。** 手机表单出现两个菜单按钮（截图 01）。由外层提供菜单时不再显示内部按钮；官方入口也去掉无效的内部侧栏按钮。
+3. **项目历史：已修复。** 我的项目侧栏链接跳到旧项目空间（截图 02），导致返回目的地变化。现在保留我的项目路径，普通聊天与旧项目空间保持原路由。手机点历史后菜单自动收起。官方侧栏原本把项目聊天打开为普通聊天，现按项目归属进入项目工作区；`/official/workspace/projects/groups` 根路径回到普通问答项目列表。
+4. **项目设置与失败恢复：已修复。** 默认智能体更新后，同步新对话选择器；项目对话权限/归属加载失败、普通问答项目列表失败均有重试入口。
+5. **助手知识检索：已修复。** 连续检索或切换库时，以递增请求序号隔离过期成功/失败/结束回调，防止旧结果覆盖新库；新检索清除旧结果；空输入禁止提交。无结果原本只有小标签（截图 03），现在说明可调整关键词并提供浏览目录按钮。输入框补充可访问名称。
+6. **窄屏输入栏：已修复。** 464px 截图中发送箭头被工具栏挤出右边缘（截图 07）；工具区允许换行、发送区不收缩，截图 08 确认按钮完整可见。项目问答网络错误也增加“重新加载对话”，只重建读取状态，不自动重发消息。
+
+## 复测记录
+
+- 具名项目创建成功；新建项目对话，通过真实模型收到“项目问答回归通过”；刷新保留消息与项目归属。
+- 修复工具栏后，在窄屏实际点击发送并收到“窄屏发送通过”；首屏知识空间菜单完成加载、选择助手库后显示已选择 1 个，未再出现循环白屏。
+- 手机项目历史链接确认留在 `qa/projects/groups`；桌面官方 groups 根路径跳回正确列表，官方项目历史进入相同项目。
+- 官方和常规项目切换时偶发网络 `Failed to fetch`，刷新/重新挂载恢复历史消息；没有将其描述为已排除的网络问题，新增恢复按钮未进行独立网络故障注入测试。
+- 助手知识库列表、阅读、检索无结果、返回入口实际操作；空查询按钮禁用。检索竞态由代码检查修复，未使用浏览器网络故障注入。
+- 后端 22 个相关文件重新运行：**273 passed**，涵盖知识库管理/导入/检索、Wiki、编码与向量、项目归属隔离、策略持久化及调用边界。
+- 前端项目与策略测试：**33 passed**，新增项目历史保持入口、旧项目和普通聊天/创建向导回归。
+- 生产构建通过。全仓类型检查仍有 **59 个既有错误**，与上一轮错误列表一致；不宣称全仓类型检查通过。
+
+## 证据与边界
+
+本轮截图与日志存放在 `frontend-web/.runtime/daily-usage-audit/`：`01-create-before.png`、`02-history-before.png`、`03-knowledge-search.png`、`04-official-desktop.png`、`05-official-project-after.png`（网络失败状态）、后续 after 截图，以及 tests/build/typecheck 日志。后端日志为 `.runtime/ji-acceptance/daily-regression.txt`。
+
+上一轮真实文件入库、向量命中、方案生成与保存的验证详见 `ji-knowledge-projects-acceptance.md`。本轮不重复付费生成完整方案；没有进行生产全量语料质量评估、负载测试、断网故障注入或完整无障碍合规审计。已检查可见导航、表单名称、窄屏显示和主要失败恢复，不能据此承诺所有模块没有缺陷。代码未提交、推送或部署。

docs/ji-knowledge-projects-acceptance.md

@@ -0,0 +1,37 @@
+# ji 分支知识库与我的项目验收
+
+日期：2026-09-14。基线：`ji` / `f62a512a`，已从 origin fast-forward 更新。
+
+## 修复范围
+
+1. 简洁模式进入我的项目保留功能导航，覆盖列表、策略工作台和问答项目；移动端有菜单展开入口。
+2. 策略结果卡片的模型思考前置；检查意图、评判、方案、展开视图保持过程在正文前。
+3. 普通问答改为真实项目分组：先填写项目名称创建项目，再在项目中创建多条问答。服务端持久归属与权限校验沿用 analysis-projects；不自动迁移或标记历史普通聊天。官方入口支持对应 groups 子路由。
+4. 修复方案列表要求预先选中策略导致无法进入的问题；任务变化后已有方案仍可查看；请求序号避免旧请求失败覆盖成功结果。
+5. 修复知识库管理目录缓存导致上游删除后仍显示的问题；保留检索端缓存。
+6. 项目编辑保留知识库绑定，助手知识库补充普通用户空态。
+
+## 自动化
+
+- 后端 22 个相关测试文件：273 passed（知识库、Wiki、向量、编码器、项目归属、策略配置与持久化、边界等）。
+- 前端策略与项目测试：31 passed。新增用例覆盖未选择策略、已有方案变更任务、未完成评判及全部策略失败。
+- `tests/test_knowledge_live_embedding.py`：真实接口 1 passed；默认跳过，设置 `KNOWLEDGE_TEST_EMBEDDING_KEY` 后运行。默认服务 SiliconFlow、模型 BAAI/bge-m3；可用 `KNOWLEDGE_TEST_EMBEDDING_URL` / `KNOWLEDGE_TEST_EMBEDDING_MODEL` 更换。
+- `pnpm build`：通过。
+- `pnpm typecheck`：未完全通过，59 个错误位于此次未改动文件（nextra 缺失、Markdown 插件类型、旧 JSX 类型及旧问答页等）；修改文件无类型错误。不能将生产构建通过等同于全仓类型检查通过。
+
+## 真实接口与浏览器
+
+测试使用 `.runtime/ji-acceptance` 独立数据目录，保留测试数据便于复查，未操作业务数据库已有项目。
+
+- BAAI/bge-m3：中英文 3 条输入，均返回 1024 维有效向量。
+- 实际检索服务：相关正文排名、指定库范围、草稿排除、概览查询通过。
+- 两个项目 A/B：A 创建两条对话，B 列表为零；跨项目读取 A 的对话返回 404。
+- 浏览器：简洁模式完整菜单可见；新建具名普通问答项目；项目内真实发送并收到回答；第二条对话独立；回列表仍是一张项目卡，刷新后保留。
+- 方案整理：真实模型返回 1539 字符正文，含 agent_done / all_done，流正常结束。
+- 方案入口：完成评判但尚未勾选策略的测试项目出现在方案列表。浏览器进入后勾选策略、生成 2755 字符正文、保存成功；服务端校验 synthesisStatus=done 且 solutionSavedAt 非空，刷新后正文与导出按钮恢复。
+- 官方入口：`/official/workspace/projects/groups/new` 正常展示具名问答项目表单，官方侧栏保留。
+- 助手知识库：创建、重命名、列表、拒绝 .py 上传通过；上传测试文本任务 completed；生成 Wiki 页面，向量检索命中 1 条，详情 HTTP 200。
+
+## 限制
+
+真实模型测试使用最小合成读书活动/设备资料，未对生产全量知识语料进行质量评估。API 密钥仅用于测试进程，不提交配置。仓库原有未跟踪 docx 与 packages1.zip 保持不变。未提交、推送代码，也未执行离线发布。