# AI 助手介绍
## 概述
AI 助手是 pi-visual-editor 内置的对话式编辑能力。你可以用自然语言描述需求，助手会理解当前页面上下文，并将意图转换为**可执行的编辑器命令**，在画布上完成组件增删、布局调整、事件配置、数据绑定等操作。
核心入口：**编辑器右侧「AI 助手」面板**（`AiAssistantPanel`）。
---
## 能做什么
| 能力域 | 示例说法 ||--------|----------|| **页面与画布** | 「保存当前页面」「把选中的组件向右移 20px」「置顶 / 置底」 || **组件** | 「加一个柱状图」「删除选中的按钮」「复制并粘贴到下方」 || **显示与锁定** | 「隐藏这个组件」「锁定选中项」 || **分组** | 「把选中的三个组件打组」「取消分组」 || **事件** | 「给按钮加单击警告弹窗」「修改基础事件的脚本」 || **交互与自定义事件** | 「配置组件联动」「添加页面级自定义事件」 || **问答与说明** | 「当前版本 AI 有哪些能力？」「这个图表怎么配数据？」 |
助手会根据**当前选中组件、页面 ID、权限状态**等上下文决定如何执行，而不是盲目猜测目标。
---
## 如何使用
### 1. 打开面板
在可视化编辑器中打开 **AI 助手** 侧栏即可开始对话。
### 2. 输入或选择示例
- 在底部输入框描述需求，按发送。- 首次进入时，欢迎区提供**快捷示例**，点击即可填入并发送；可点「换一换」刷新示例。
### 3. 查看回复与执行结果
- **普通问答**：以 Markdown 文本展示说明。- **可执行指令**：助手返回 `tool_call` 等结构化协议后，客户端经 `executeAiToolCall` 调用 `EditorCommandService` 在画布上执行，并在对话中反馈结果摘要。- **思考过程**：部分回复会展示可折叠的「思考过程」区域，便于了解推理步骤。
### 4. 会话管理
- 顶部可**清除聊天记录**（含本地持久化的 session）。- 面板显示**剩余提问次数**；次数用尽时可按提示购买额度。
---
## 使用建议
1. **先选中再操作** 涉及「这个组件」「选中的图表」时，请先在画布上选中目标；未选中时助手可能追问澄清。
2. **说清动作与对象** 推荐：「把选中的标题文字组件向右移动 50 像素」 避免：「挪一下」
3. **分步描述复杂需求** 多步任务可拆成多条消息，或让助手先给出 `plan` 再逐步确认执行。
4. **高风险操作会确认** 删除组件、清空事件代码等操作遵循安全策略，可能需要二次确认或 dry-run 预览。
5. **有编辑权限时再改内容** 页面未获取编辑权限（`hasAuth=false`）时，写操作会被拦截。
---
## 工作原理（简要）
```用户输入 → AI 服务（SSE 流式）→ 解析 reply / tool_call / clarify / plan → executeAiToolCall → EditorCommandService → Store 画布操作 → 返回 AiCommandResult → 对话中展示结果```
- 全局调试入口：`window.$aiUtils`（见 [AI_UTILS_USAGE.md](./AI_UTILS_USAGE.md)）- 命令白名单与协议：见 [AI_EDITOR_API_SPEC.md](./AI_EDITOR_API_SPEC.md)- 提示词与上下文注入：见 [AI_EDITOR_PROMPT_GUIDE.md](./AI_EDITOR_PROMPT_GUIDE.md)
---
## 相关文档索引
| 文档 | 说明 ||------|------|| [AI_UTILS_USAGE.md](./AI_UTILS_USAGE.md) | `$aiUtils` API 与命令调用示例 || [AI_EDITOR_API_SPEC.md](./AI_EDITOR_API_SPEC.md) | 命令协议、请求/响应结构 || [AI_EDITOR_PROMPT_GUIDE.md](./AI_EDITOR_PROMPT_GUIDE.md) | 系统提示词与 ToolSpec 模板 || [AI_EVENT_EDITING_GUIDE.md](./AI_EVENT_EDITING_GUIDE.md) | 事件编辑的安全命令与校验 || [EditorCapabilityMap.md](./EditorCapabilityMap.md) | Store 能力与 AI 命令映射 || [EditorStateSnapshotSpec.md](./EditorStateSnapshotSpec.md) | 传给模型的编辑器上下文快照 || [StoreActionRiskList.md](./StoreActionRiskList.md) | 高风险 Store 操作清单 || [AI_EDITOR_E2E_CHECKLIST.md](./AI_EDITOR_E2E_CHECKLIST.md) | 端到端验收清单 || [AI_PANEL_PROTOCOL_UPGRADE.md](./AI_PANEL_PROTOCOL_UPGRADE.md) | 面板协议升级说明 |
---
## 常见问题
**Q：助手说执行了但画布没变化？** 检查是否选中正确组件、是否有页面编辑权限，并在浏览器控制台查看 `[AI Panel] tool_call result` 日志。
**Q：能否直接改任意 JavaScript？** 事件代码类修改受校验与安全策略约束（关键字黑名单、dry-run 等），详见 [AI_EVENT_EDITING_GUIDE.md](./AI_EVENT_EDITING_GUIDE.md)。
**Q：开发如何扩展新命令？** 在 `EditorCommandService` 注册命令并更新 allowlist，同步更新 [AI_EDITOR_API_SPEC.md](./AI_EDITOR_API_SPEC.md) 与模型侧 ToolSpec。
---
## 版本说明
AI 助手能力与后端模型、协议字段会随版本迭代。对接新接口或排查联调问题时，请同时参考 [切换接口对接.md](./切换接口对接.md) 与 [ps_ai_frontend_context_integration.md](./ps_ai_frontend_context_integration.md)。