refactor: unify AI capabilities and workspace integration

.scratch/ai-capability-integration/issues/01-implementation.md

@@ -0,0 +1,28 @@
+# 实施领域 AI 能力接入及工作区联动
+
+Status: ready-for-agent
+
+## 目标
+
+按 ../spec.md 实施 A 和配套 B。用户已授权本地修改与验证。
+
+## 进度
+
+- 2026-09-08 已完成本地实施与验证。`Status` 为分诊标签，实施进度以本节为准。
+- 28 个工具按 Alpha、同步任务、数据目录、研究构建、回测五组声明；通用装配和运行时不再维护独立确认名单或按工具名执行的分支。
+- 卡片外壳消费服务端 presentation，领域卡片负责具体展示；刷新目标和导航动作显式声明，未知展示形态保留原始记录并禁用确认。
+- 模型摘要与完整持久化结果分离；准备产物失败回滚、旧确认恢复、能力移除后的确认拒绝均有回归覆盖。
+- 独立核验发现提交后通知异常会阻止聊天收尾，已通过故障注入复现并修复：保留已提交操作、持久化 `_warning`，继续收尾；重复确认不会再次执行或通知。
+- 模块接入位置、效果类型、展示/刷新/导航标准与测试要求记录在 ../spec.md。
+
+## 验证
+
+- 后端 `uv run pytest -q`：最终全量 **148 passed in 37.22s**。
+- 后端 `uv run ruff check app tests`：通过；本次 Python 文件 Ruff 格式检查通过。
+- 前端 `pnpm build`：类型检查和生产构建通过；保留依赖 lottie-web 已有的 eval 构建提示。
+- 前端 `pnpm test`：最终全量 **16 passed (1.9m)**。覆盖未知 renderer（包括原型属性名称）、旧卡片、确认、草稿保留、窄屏，以及固定输入→聊天确认→回测→原会话→固定输入的来源回链。
+- 本次前端文件 Prettier 检查和 `git diff --check`：通过。
+- 与基线直接比较工具定义：28 个工具名称、JSON schema、描述无变化；确认要求集合一致。平台研究范围仍从当前账号的平台选项读取。
+- 首轮浏览器验证中，新增导航测试因会话标题与消息重名导致定位歧义，已限定到用户消息；既有 workspace 测试发生一次抽屉遮罩时序失败，未修改其业务代码，专项与最终全量重跑均通过。
+
+以上只使用临时数据库、合成模型和模拟 WorldQuant HTTP；未验证真实模型研究质量或真实平台运行。未增加依赖或数据库迁移，未部署或提交 Git。跨轮研究上下文（C）按本次范围留待后续。

.scratch/ai-capability-integration/spec.md

@@ -0,0 +1,46 @@
+# AI 能力接入与工作区联动
+
+Status: ready-for-agent
+
+用户于 2026-09-08 确认按架构评审建议实施。当前基线为 `3d26827`，保留平台研究范围发现修复。
+
+## 范围与决定
+
+- 实施 A：按领域集中工具参数、描述、查询/准备产物/确认执行策略、处理函数、提交后通知及工作区展示信息。运行时统一管理登录、预算、确认、审计与事务。
+- 配套实施 B：统一卡片外壳、按明确 renderer 分派，移除前端工具标题和写入名单；服务端返回刷新目标，前端按目标刷新并保持草稿。导航动作显式映射，未知能力显示保守降级。
+- 模型使用有界摘要，持久化卡片保留完整的业务返回；摘要截断显式标记。PnL 仍只返回摘要，完整序列按业务引用读取。
+- 保留现有工具名称、参数与确认记录；旧持久化记录由当前能力定义补齐展示信息。已移除能力的待确认操作拒绝执行。
+- 查询不得产生业务写入；准备能力仅保存约定的本地产物；需要确认的操作保留固定目标、版本检查与幂等。所有工具业务操作使用保存点，失败回滚业务修改并保存失败审计。通知只在提交后进行。
+- 提交后通知失败时保留已完成操作，持久化并展示 `_warning`，继续结束聊天；不重复提交业务操作。通知只负责唤醒或中断既有 runner，不能承担业务落库。
+- 不改变单管理员、单进程、回测确认和生成中断恢复语义；不实施 C、不增加持久研究焦点、自动续跑、框架、依赖或迁移。
+
+## 接入路径
+
+1. 明确领域归属、输入/输出、范围/版本/单位/null、失败和副作用；业务 implementation 复用既有 module。
+2. 在领域的 `ai_tools.py`（Alpha/任务暂位于 `ai/`）声明完整 Capability；新领域在 `ai/tools.py` 装配一次。
+3. 提供查询或 prepare handler；确认操作同时提供 preview、execute 和必要的 after_commit。身份和事务由 AIRuntime 管理，不从 handler 提交事务。
+4. 固定研究输入与来源，生产候选复用 ResearchBuilder / Backtests；长任务只返回既有任务或运行引用。
+5. 复用已有 renderer；新展示形态只在前端工具卡装配处注册一次，展示与业务逻辑留在领域。声明需要刷新的资源，补齐明确的 UIAction 目标。
+6. 测试跨业务 interface 的可观察行为，覆盖失败原子性、确认、恢复、结果摘要、卡片、来源回链与草稿保留。
+
+## 实际入口与接入标准
+
+| 需要增加的内容 | 修改位置 | 完成标准 |
+| --- | --- | --- |
+| 既有领域的新能力 | `backend/app/<domain>/ai_tools.py`；Alpha/同步任务分别为 `ai/alpha_tools.py`、`ai/job_tools.py` | 名称唯一，声明 schema、description、label、renderer、effect、处理函数和 refresh；修改领域说明中的使用约束 |
+| 新领域 | 领域自己的业务 module 与 `ai_tools.py`，在 `backend/app/ai/tools.py` 的 `DOMAINS` 装配 | 通用 runtime 无工具名分支；业务权限与校验复用既有 interface |
+| 新卡片形态 | 领域展示文件及 `frontend/src/ai/ToolCard.tsx` 的 renderers | 通用确认、错误、通知警告留在外壳；未知 renderer 仍可查看记录，但不能确认 |
+| 新页面或导航动作 | `frontend/src/ai/types.ts`、`frontend/src/ai/workspace.ts` 及目标页面 | 显式资源引用、页面目标及聊天开关策略；穷尽类型检查通过，不能默认跳到 Alpha |
+| 新刷新资源 | 后端 `Resource`、前端 `Resource` 及 `App.tsx` 的刷新处理 | 声明值可校验，已完成工具才触发刷新，重复快照不重复刷新；不清空人工草稿 |
+
+`query` 只读取业务事实，不能声明刷新或提交后通知；`prepare` 只能保存本地输入/预览，不能开始后台执行；`confirm` 必须同时提供 preview 与 execute，执行时重新检查固定目标和版本。效果类型约束在能力装配时检查，handler 的实际副作用通过业务 interface 与行为测试保证，不把声明本身视为隔离机制。
+
+模型拿到 `model_result` 摘要，审计与卡片拿到完整业务返回。长结果应提供分页与稳定引用；领域约定的摘要（如 PnL）仍保持原语义。截断会附带 `_meta.truncated`，不能将摘要解释为全部数据。旧卡片从当前能力补齐 presentation，能力移除后的确认请求会产生失败审计。
+
+新增能力至少提供一个通过实际 runtime 的成功路径，并覆盖与副作用相关的失败/确认/重复请求路径。涉及研究来源或新导航时，再补浏览器中的来源回链；复用既有卡片形态时无需另建一套展示测试。不要复制通用执行器的确认、事务和模型预算逻辑。
+
+## 验证
+
+后端 Ruff 和全量 pytest；前端类型检查/构建及隔离 Playwright。新增接入完整性、prepare 失败原子性、历史确认兼容、摘要不改变持久化产物与前端降级/导航回归。只使用合成模型、模拟 HTTP 与临时数据库。不部署、不提交、不调用真实平台或收费模型。
+
+本文件记录当前任务接入方式，不推广为全局规则或技能。完成证据见 issues/01-implementation.md。