yuxuanhui
5.2 KiB
5.2 KiB
AI 能力接入与工作区联动
Status: ready-for-agent
用户于 2026-09-08 确认按架构评审建议实施。当前基线为 3d26827，保留平台研究范围发现修复。
范围与决定
- 实施 A：按领域集中工具参数、描述、查询/准备产物/确认执行策略、处理函数、提交后通知及工作区展示信息。运行时统一管理登录、预算、确认、审计与事务。
- 配套实施 B：统一卡片外壳、按明确 renderer 分派，移除前端工具标题和写入名单；服务端返回刷新目标，前端按目标刷新并保持草稿。导航动作显式映射，未知能力显示保守降级。
- 模型使用有界摘要，持久化卡片保留完整的业务返回；摘要截断显式标记。PnL 仍只返回摘要，完整序列按业务引用读取。
- 保留现有工具名称、参数与确认记录；旧持久化记录由当前能力定义补齐展示信息。已移除能力的待确认操作拒绝执行。
- 查询不得产生业务写入；准备能力仅保存约定的本地产物；需要确认的操作保留固定目标、版本检查与幂等。所有工具业务操作使用保存点，失败回滚业务修改并保存失败审计。通知只在提交后进行。
- 提交后通知失败时保留已完成操作，持久化并展示
_warning，继续结束聊天；不重复提交业务操作。通知只负责唤醒或中断既有 runner，不能承担业务落库。 - 不改变单管理员、单进程、回测确认和生成中断恢复语义；不实施 C、不增加持久研究焦点、自动续跑、框架、依赖或迁移。
接入路径
- 明确领域归属、输入/输出、范围/版本/单位/null、失败和副作用；业务 implementation 复用既有 module。
- 在领域的
ai_tools.py（Alpha/任务暂位于ai/）声明完整 Capability；新领域在ai/tools.py装配一次。 - 提供查询或 prepare handler；确认操作同时提供 preview、execute 和必要的 after_commit。身份和事务由 AIRuntime 管理，不从 handler 提交事务。
- 固定研究输入与来源，生产候选复用 ResearchBuilder / Backtests；长任务只返回既有任务或运行引用。
- 复用已有 renderer；新展示形态只在前端工具卡装配处注册一次，展示与业务逻辑留在领域。声明需要刷新的资源，补齐明确的 UIAction 目标。
- 测试跨业务 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。