feat(workspace): rename workspace summary endpoint and update naming …

…logic

- Changed the endpoint from `/workspace-summary` to `/workspace-name` to better reflect its purpose.
- Updated the logic to generate a concise display name for workspaces, ensuring it adheres to user interface language.
- Adjusted the frontend to utilize the new endpoint and handle the updated response structure.
- Enhanced the documentation to clarify the changes in workspace naming conventions and API usage.

design-docs/18.2-insight-architecture-redesign.md

@@ -1,9 +1,14 @@
 # 18.2 - Insight 架构重构：结构化数据优先，图片可选
 
-> 状态：方向已定，详细设计待补充  
+> 状态：方向已定；前置 API 错误契约已完成；Phase 3 / structured-first Insight 实施待启动  
 > 创建日期：2026-04-30  
-> 前置依赖：`design-docs/18-api-error-guardrails-and-chart-insight-failure.md` Phase 1 完成  
+> 前置依赖：`design-docs/18-api-error-guardrails-and-chart-insight-failure.md` Phase 1/2 已完成  
 > 相关规范：`dev-guides/1-streaming-protocol.md`
+> 最近两次提交核对（2026-04-30）：  
+> - ✅ 前置错误契约、`apiRequest()` / `streamRequest()` 迁移、Chart Insight 可见失败治理已完成  
+> - ❌ `py-src/data_formulator/insights/` 包尚未创建  
+> - ❌ `TableInsightProfiler` / `ChartInsightProfiler` / `InsightNarratorAgent` / `VisionInsightFallback` 尚未实现  
+> - ❌ Chart Insight 仍未改为 structured-first，图片路径尚未降级为 fallback  
 
 ## 1. 动机
 
@@ -166,16 +171,19 @@ LLM 的职责是基于这些事实生成自然语言，不再负责从图片中
 
 ## 7. 实施内容
 
-- 新增 `py-src/data_formulator/insights/` 包，承载所有不调用 LLM 的 profile 生成逻辑。
-- 新增 `TableInsightProfiler`，从 table rows、metadata、schema 和 sample 生成表格 profile，支持 Agent 只生成数据表时直接产出表格洞察。
-- 新增 `ChartInsightProfiler`，从 chart spec、encoding map、visual aggregate、table profile 和 lineage 生成图表 profile。
-- 新增 `InsightNarratorAgent`，接收 profiler facts 并调用 LLM 生成标题和 takeaways。
-- `ChartInsightAgent` 先保留为 `/chart-insight` 的兼容门面，默认走 profile + narrator，不再默认接收 chart image。
-- 自动洞察在 profile 可生成时不等待图片缓存；仅 vision fallback 场景使用 `waitForChartImage()`。
-- 区分 `profile_generation_failed`、`chart_image_not_ready` 和后端失败。
-- 对 `Table` 图表走 table insight profile；对 `Auto` / `?` 图表等待 chart 类型确定后再触发。
-- 对自定义图表和 profile 不足的场景，保留低分辨率 image fallback，并在响应 diagnostics 中标记 `image_used`。
-- 测试覆盖：profile 大小上限、字段统计正确性、聚合后数据点摘要、无图片路径的洞察生成。
+当前最近两次提交只完成了前置稳定性工作，本节 structured-first Insight 仍未开始：
+
+- ✅ 前置：错误 envelope、Chart Insight 失败反馈、前端统一 API client 已完成。
+- ❌ 新增 `py-src/data_formulator/insights/` 包，承载所有不调用 LLM 的 profile 生成逻辑。
+- ❌ 新增 `TableInsightProfiler`，从 table rows、metadata、schema 和 sample 生成表格 profile，支持 Agent 只生成数据表时直接产出表格洞察。
+- ❌ 新增 `ChartInsightProfiler`，从 chart spec、encoding map、visual aggregate、table profile 和 lineage 生成图表 profile。
+- ❌ 新增 `InsightNarratorAgent`，接收 profiler facts 并调用 LLM 生成标题和 takeaways。
+- ❌ `ChartInsightAgent` 先保留为 `/chart-insight` 的兼容门面，默认走 profile + narrator，不再默认接收 chart image。
+- ❌ 自动洞察在 profile 可生成时不等待图片缓存；仅 vision fallback 场景使用 `waitForChartImage()`。
+- ❌ 区分 `profile_generation_failed`、`chart_image_not_ready` 和后端失败。
+- ❌ 对 `Table` 图表走 table insight profile；对 `Auto` / `?` 图表等待 chart 类型确定后再触发。
+- ❌ 对自定义图表和 profile 不足的场景，保留低分辨率 image fallback，并在响应 diagnostics 中标记 `image_used`。
+- ❌ 测试覆盖：profile 大小上限、字段统计正确性、聚合后数据点摘要、无图片路径的洞察生成。
 
 ## 8. 待详细设计的问题
 

design-docs/19-multi-model-routing.md

@@ -1,9 +1,15 @@
 # 19 - 多模型路由：后端按任务类型自动选择模型
 
-> 状态：方向已定，Phase 2/3 实施  
+> 状态：方向已定；前置 API 错误契约已完成；`ModelResolver` 实施待启动  
 > 创建日期：2026-04-30  
-> 前置依赖：`design-docs/18-api-error-guardrails-and-chart-insight-failure.md` Phase 1 完成  
+> 前置依赖：`design-docs/18-api-error-guardrails-and-chart-insight-failure.md` Phase 1/2 已完成  
 > 相关文档：`design-docs/18.2-insight-architecture-redesign.md`
+> 最近两次提交核对（2026-04-30）：  
+> - ✅ 多模型路由的前置错误契约、统一 API client、streaming error 事件清理已完成  
+> - ❌ `ModelResolver` 类尚未实现  
+> - ❌ `AGENT_CAPABILITIES` / task type 声明尚未实现  
+> - ❌ `DF_INSIGHT_MODEL` / `DF_CHEAP_MODEL` 等任务级 env override 尚未实现  
+> - ❌ `get_completion()` 仍在 `client_utils.py` 内硬编码 `reasoning_effort = "low"`，尚未参数化  
 
 ## 1. 动机
 
@@ -187,9 +193,10 @@ Phase 2 的 `InsightProfiler`（`18.2` 文档）与 `ModelResolver` 协同：
 
 ## 10. 实施顺序
 
-1. **Phase 1（已规划）**：`reasoning_effort` 参数化，`get_completion()` 接受参数
-2. **Phase 2**：新增 `ModelResolver` 类 + `.env` 配置 + `AGENT_CAPABILITIES` 声明
-3. **Phase 3**：前端可选 UI（显示实际使用的模型、高级配置面板）
+1. ✅ **前置已完成**：错误契约、`apiRequest()` / `streamRequest()` 和应用错误 HTTP 200 策略已稳定。
+2. ❌ **Phase 3a**：`reasoning_effort` 参数化，`get_completion()` 接受调用方传入的 effort（当前仍硬编码 `"low"`）。
+3. ❌ **Phase 3b**：新增 `ModelResolver` 类 + `.env` 配置 + `AGENT_CAPABILITIES` 声明。
+4. ❌ **Phase 3c**：前端可选 UI（显示实际使用的模型、高级配置面板）。
 
 ## 11. Open Questions
 

design-docs/20-phased-api-insight-implementation-plan.md

@@ -1,6 +1,6 @@
 # 20 - API 错误契约与 Insight 稳定性分期实施计划
 
-> 状态：Phase 2 已完成（2c/2d 全量迁移 + HTTP 200 策略修订）  
+> 状态：Phase 2 已完成（2c/2d 全量迁移 + HTTP 200 策略修订 + legacy 解析清理）；静态扫描/CI 与 Phase 3 待启动  
 > 创建日期：2026-04-30  
 > Phase 0 完成日期：2026-04-30  
 > Phase 1 完成日期：2026-04-30  
@@ -9,9 +9,13 @@
 > Phase 2c 进度：credentials ✅ | knowledge ✅ | sessions ✅ | tables ✅ | agents ✅ | data_connector ✅ | app ✅  
 > Phase 2d 进度：前端 thunk 全部迁移到 apiRequest() ✅  
 > HTTP 状态码修订：应用错误 HTTP 200，仅 auth 401/403 ✅  
-> 待办：移除 parseApiResponse legacy 兼容 | 前端 vitest 验证 | 静态扫描 CI  
+> 待办：`fetchCodeExpl` / `fetchFieldSemanticType` 20s 硬编码 timeout 清理 | 前端全量 vitest/回归验证 | 静态扫描脚本与 CI 接入 | Phase 3 Structured-first Insight + ModelResolver  
 > 前置文档：`design-docs/18-api-error-guardrails-and-chart-insight-failure.md`、`design-docs/18.2-insight-architecture-redesign.md`、`design-docs/19-multi-model-routing.md`  
 > 相关规范：`dev-guides/1-streaming-protocol.md`、`dev-guides/7-unified-error-handling.md`
+> 最近两次提交核对（2026-04-30）：  
+> - `4455d3d`：完成 Phase 2 大批普通 JSON API 迁移、前端 `apiRequest()` 适配、credentials/knowledge 合约测试和文档归档。  
+> - `59d09e1`：统一应用错误 HTTP 200 策略、补齐 streaming / auth / storage-full 等错误处理、移除 legacy response 解析和 stream error token、补充后端协议合约与前端 API client 测试。  
+> - 未完成：`fetchCodeExpl` / `fetchFieldSemanticType` timeout 配置化、静态扫描脚本/CI、structured-first Insight、`ModelResolver`、per-agent `reasoning_effort` 参数化。
 
 ## 1. 背景
 
@@ -226,8 +230,9 @@ return title and takeaways
 新增统一 response helper：
 
 - `json_ok(data)`：成功响应统一为 `{"status": "success", "data": {...}}`。
-- `json_error(error)`：错误响应统一为 `{"status": "error", "error": {"code", "message", "retry"}}`。
-- `AppError` 根据 `ErrorCode` 映射 HTTP status。
+- `raise AppError(...)`：应用错误响应统一为 `{"status": "error", "error": {"code", "message", "retry"}}`。
+- `stream_preflight_error(error)`：流建立前应用错误返回 HTTP 200 + JSON error envelope。
+- `AppError` 根据 `ErrorCode` 映射 HTTP status：应用错误 200，auth 401/403。
 
 迁移范围：
 
@@ -241,17 +246,17 @@ return title and takeaways
 
 `token` 处理：
 
-- 响应 body 不再回传 `token`。
-- 请求 body 中的 `token` 可先兼容忽略。
-- 后续清理时再删除读取逻辑。
+- ✅ 响应 body 不再回传通用 `token`。
+- ✅ 前端业务 thunk 不再发送通用 `token`。
+- ✅ 后端 route 不再依赖通用请求 `token` 读取逻辑。
 
 ### 6.3 前端改动
 
 `apiRequest()` 成为普通 JSON API 的标准入口：
 
-- 先检查 `response.ok`。
+- 先防御性检查 `response.ok`，捕获 auth / transport 错误。
 - 成功时只返回 `body.data`。
-- 失败时抛出 `ApiRequestError`。
+- body `status:"error"` 时抛出 `ApiRequestError`（应用错误通常是 HTTP 200）。
 - 不再兼容裸 `{error: ...}`、`error_message`、`message`、`body.result`。
 
 业务 thunk 改造：
@@ -269,63 +274,65 @@ NDJSON endpoint 与普通 JSON endpoint **统一**使用 HTTP 200：
 
 - 流建立后：HTTP 200 + `application/x-ndjson`，运行中错误通过 `{type: "error"}`。
 - 流建立前：返回 `200 application/json + status:"error"`（使用 `stream_preflight_error()`）。
-- 流式事件中的 `token` 后续移除，但必须等前端消费者不再依赖 `data.token === token` 之后再改后端。
+- 流式错误事件中的通用 `token` 已移除；请求追踪使用 `X-Request-Id` header。
 
 Streaming 剩余待办：
 
 1. ~~先新增后端小 helper。~~ ✅ stream_preflight_error() 已实现。
-2. 前端手写 reader 逐步迁到 streamRequest()。（部分完成）
-3. 确认前端不再依赖流事件中的 	oken 后，后端停止发送 stream 	oken。
+2. ~~前端主要手写 reader 逐步迁到 streamRequest()。~~ ✅ 已完成主要 Agent/streaming 消费者迁移。
+3. ~~确认前端不再依赖流事件中的 token 后，后端停止发送 stream token。~~ ✅ 已完成；`stream_error_event()` 不再携带通用 `token`。
 4. ~~把流建立前校验失败从 200 切到 4xx。~~ ❌ **已取消**（统一 HTTP 200 策略）
 
 伪代码：
 
-`	ext
+```text
 if preflight validation failed:
     return stream_preflight_error(error)  # HTTP 200 + application/json
 
 return ndjson_response(generate)  # HTTP 200 + application/x-ndjson
-`
+```
 
 
 ### 6.5 测试与护栏
 
 后端：
 
-- contract tests 覆盖普通 JSON endpoint 成功和失败 shape。
-- `X-Request-Id` header 测试。
-- Chart Insight、code explanation、model list 等高风险 endpoint 单独覆盖。
+- ✅ contract tests 覆盖普通 JSON endpoint 成功和失败 shape。
+- ✅ `X-Request-Id` header 测试。
+- ✅ Chart Insight、code explanation、model list 等高风险 endpoint 单独覆盖。
 
 前端：
 
-- `apiRequest()` 对 2xx / 4xx / 5xx 的解析测试。
-- legacy 格式触发 `PROTOCOL_VIOLATION`。
-- 业务 thunk 不发送 `token`。
+- ✅ `apiRequest()` 对 2xx / 4xx / 5xx 和 HTTP 200 应用错误的解析测试已补充。
+- ✅ legacy 格式不再静默兼容，触发 malformed/protocol 类错误。
+- ✅ 业务 thunk 不再发送通用 `token`。
 
 静态扫描：
 
-- 检查裸 `jsonify({"error": ...})`。
-- 检查扁平 `status: "ok"`。
-- 检查业务代码直接 `fetchWithIdentity().json()`。
-- 检查未说明的 LLM 硬编码 timeout。
+- ❌ 检查裸 `jsonify({"error": ...})`。
+- ❌ 检查扁平 `status: "ok"`。
+- ❌ 检查业务代码直接 `fetchWithIdentity().json()`。
+- ❌ 检查未说明的 LLM 硬编码 timeout。
 
 ### 6.6 文档更新
 
 - ~~重写 `dev-guides/7-unified-error-handling.md`。~~ ✅ 已完成
-- ~~更新 `dev-guides/1-streaming-protocol.md`：流建立后 200，流建立前校验失败可 4xx JSON。~~ ⚠️ 4xx 切换已取消（统一 200），`dev-guides/1` 中相关描述待同步清理
+- ~~更新 `dev-guides/1-streaming-protocol.md`：流建立后 200，流建立前校验失败可 4xx JSON。~~ ✅ 已按统一 HTTP 200 策略同步清理，早期 4xx 切换方案已取消
 - ~~更新错误处理 skill 和相关 rule。~~ ✅ 已完成（`unified-error-protocol.mdc`、`error-response-safety.mdc`、`backend-test-conventions.mdc`）
 - 将新增 endpoint checklist 改为要求 contract test。
 
 ### 6.7 验收标准
 
-- 普通 JSON API 成功响应全部为 `status: "success"` + `data`。
-- 普通 JSON API 失败响应全部为 `status: "error"` + `error.code/message/retry`。
-- 前端业务代码不再直接消费未解析的 `response.json()`。
-- legacy response shape 不再被静默兼容。
-- 静态扫描能发现新增违规。
+- ✅ 普通 JSON API 成功响应全部为 `status: "success"` + `data`。
+- ✅ 普通 JSON API 失败响应全部为 `status: "error"` + `error.code/message/retry`。
+- ✅ 前端业务代码不再直接消费未解析的 `response.json()`（文件下载、blob、auth 特例除外）。
+- ✅ legacy response shape 不再被静默兼容。
+- ❌ 静态扫描能发现新增违规。
 
 ## 7. Phase 3：Structured-first Insight 与多模型路由
 
+> 状态：❌ 待启动。最近两次提交没有新增 `insights/` 包、`ModelResolver` 或 per-agent capabilities。
+
 ### 7.1 目标
 
 在错误契约和用户反馈稳定后，将 Insight 从 vision-first 改为 structured-first，并引入后端任务级模型路由。
@@ -386,15 +393,15 @@ Agent 拆分：
 2. ~~在 matrix 中把 NDJSON streaming 标成“只统计，不做 Phase 1 行为迁移”。~~ ✅
 3. ~~实施 Phase 1 的 Chart Insight 修复，并先跑相关前后端测试。~~ ✅
 4. ~~再启动 Phase 2 普通 JSON API 迁移，按 route 分批开发，但最终同步上线。~~ ✅ 已完成（7/7 route 全量迁移 + 前端 thunk 适配 + HTTP 200 策略修订）
-5. Phase 2 收尾：移除 legacy 格式兼容、前端 vitest 验证、静态扫描 CI、stream `token` 移除。
-6. Phase 2 稳定后再进入 Phase 3 的 structured-first Insight 和 ModelResolver。
+5. Phase 2 收尾：~~移除 legacy 格式兼容、stream `token` 移除~~ ✅；前端全量 vitest/回归验证、静态扫描 CI ❌。
+6. Phase 2 稳定后再进入 Phase 3 的 structured-first Insight 和 ModelResolver（尚未启动）。
 
 ## 9. 当前不建议做的事
 
-- 不建议第一期直接实现 `InsightProfiler`，因为失败反馈和 API 契约尚未稳定。
+- ~~不建议第一期直接实现 `InsightProfiler`，因为失败反馈和 API 契约尚未稳定。~~ ✅ 前置契约已稳定；`InsightProfiler` 可作为 Phase 3 启动项。
 - ~~不建议第一期直接全量迁移所有 `/api/` JSON endpoint，除非同时安排完整前端适配和 contract tests。~~ ✅ 已全量迁移
 - 不建议把 NDJSON streaming 运行中错误改成 HTTP 4xx/5xx，因为流建立后 HTTP status 已经无法改变。
-- 不建议第一期移除 streaming `token` 或改 `data-agent-streaming` 的 legacy `{token, status, result}` 事件格式，因为当前前端仍有消费者依赖它。
+- ~~不建议第一期移除 streaming `token` 或改 `data-agent-streaming` 的 legacy `{token, status, result}` 事件格式，因为当前前端仍有消费者依赖它。~~ ✅ 已在最近提交中完成主要 reader 迁移并移除通用 stream error `token`。
 - ~~不建议第一期把 streaming 预检失败从 `200 application/json` 改为 `4xx application/json`。~~ ❌ 已永久取消（统一 HTTP 200 策略）
 - 不建议前端通过 `model.supports_vision` 决定是否调用 Insight API，这会阻碍后续后端多模型路由。
 
@@ -411,6 +418,7 @@ Agent 拆分：
 
 > 下表是对当前所有 `/api/` 路由的盘点结果。列说明见表头。  
 > **Phase 1 只改了 `/api/agent/chart-insight`**，其余 endpoint 留待 Phase 2 迁移。
+> **状态说明（2026-04-30）**：该 matrix 保留为 Phase 0 历史盘点快照；最近两次提交已经完成 Phase 2 全量迁移，表内大量 “当前响应格式 / 消费方式” 不再代表 HEAD 现状。
 
 ### A.1 Agent 路由（`routes/agents.py`，前缀 `/api/agent/`）
 
@@ -552,12 +560,13 @@ Agent 拆分：
 | `DataLoadingChat` (data-loading-chat) | `setTimeout` → `controller.abort()` | 硬编码 120s | ⚠️ Phase 2 应改为统一配置 |
 | `fetchGlobalModelList` / `fetchAvailableModels` | 无 | 无 | 低优先级 |
 | `testModel` | 无 | 无 | 低优先级 |
-| `fetchFieldSemanticType` | 无 | 无 | ⚠️ Phase 2 应补上 |
+| `fetchFieldSemanticType` | `AbortController` | 硬编码 20s | ❌ 待改为统一配置或独立 metadata timeout |
+| `fetchCodeExpl` | `AbortController` | 硬编码 20s | ❌ 待改为 `formulateTimeoutSeconds` 或明确短超时策略 |
 
 ### A.10 文档不一致标记
 
 | 项目 | 现状 | 文档说法 | 建议 |
 |---|---|---|---|
-| `/refine-data` | 普通 JSON endpoint（`jsonify` 返回） | `dev-guides/1-streaming-protocol.md` 列为 NDJSON streaming | 从 streaming 表中移除 |
-| streaming pre-stream error | 全部返回 `200 application/json` | `design-docs/18` 建议改为 `4xx` | Phase 2 后段处理 |
-| `token` 字段 | Agent 相关 endpoint 仍在使用 | `design-docs/18` 建议移除 | Phase 2 后段处理 |
+| `/refine-data` | 普通 JSON endpoint（`json_ok` envelope） | 旧版 `dev-guides/1-streaming-protocol.md` 曾列为 NDJSON streaming | ✅ 已从规范中按当前实现校正 |
+| streaming pre-stream error | 全部返回 `200 application/json` | 早期 `design-docs/18` 建议改为 `4xx` | ✅ 4xx 方案已取消，统一 HTTP 200 |
+| `token` 字段 | 通用 API/stream error token 已移除 | `design-docs/18` 建议移除 | ✅ 已完成主要清理；鉴权/连接器私有 token 不在此范围 |

dev-guides/6-i18n-language-injection.md

@@ -40,7 +40,7 @@ frontend i18n.language
 | 项目 | 当前状态 | 说明 |
 |------|----------|------|
 | `SortDataAgent` | 已接入 | 构造函数接收 `language_instruction`，route 使用 `compact` 模式 |
-| `workspace-summary` | 已接入 | `SimpleAgents` 接收 `language_instruction`，生成短名称使用 `compact` |
+| `workspace-name` | 已接入 | `SimpleAgents` 接收 `language_instruction`，生成 session/workspace 展示名使用 `full` |
 | `nl-to-filter` | 暂不注入 | 当前返回结构化 JSON；未来若返回用户可见自然语言再接入 |
 | `test-model` | 明确豁免 | 健康检查需要固定返回，不应被语言指令影响 |
 | `rec_language_instruction` | 已清理 | 当前 `routes/agents.py` 未再保留该误导性参数 |
@@ -96,7 +96,8 @@ agent = SortDataAgent(client=client, language_instruction=language_instruction)
 |------|------|
 | `DataAgent`、`ChartInsightAgent`、`InteractiveExploreAgent`、`ReportGenAgent` | `full` |
 | `DataRecAgent`、`DataTransformationAgent`、`DataLoadAgent` | `compact` |
-| `SortDataAgent`、`workspace-summary` | `compact` |
+| `SortDataAgent` | `compact` |
+| `workspace-name` | `full` |
 | `test-model`、模型列表、纯状态检查 | 不注入 |
 
 ### 2.2 Agent 层