yuxuanhui
47 lines
5.2 KiB
Markdown
47 lines
5.2 KiB
Markdown
# 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。
|