AI 服务集成方案

目标

将 Electron 端 AI 智能编程助手升级为可持续使用的项目级服务，并满足以下要求：

1. 每个项目具有独立、可持久化的 AI 会话记忆。
2. AI 助手采用类似 VS Code 的右侧可停靠面板，可展开、收缩和恢复；默认收缩。
3. 默认使用 LingBuilder 系统内置 AI，同时允许用户配置自己的 AI 服务、地址、模型和密钥。

LangChain.js 可以引入，但仅作为 AI 服务的模型编排、消息历史、检索和工具调用适配层。它不替代 LingBuilder 的工作台 UI、账户系统、权限控制、项目文件边界、AI Bridge 或代码修改审批机制。

总体架构

右侧 AI 助手 UI
        |
CommandService / Workbench 配置
        |
AIService
  |-- 会话服务：项目级历史、摘要、会话列表
  |-- 上下文服务：当前文件、工作区索引、模块和设计器上下文
  |-- 模型服务：系统 AI、用户自定义 AI、流式输出
  |-- 编辑服务：预览、确认、应用、撤销
        |
LangChain.js / LangGraph（可选编排层）
        |
系统 AI 网关 或 用户自定义 Provider

服务边界必须保持明确：React 组件只显示会话和分发操作；模型调用、会话持久化、上下文裁剪、工具调用和安全审计由服务层处理。

一、项目级会话记忆

行为要求

• 每个工作区或项目拥有独立会话集合，切换项目时不得混入其他项目的消息、摘要、代码片段或检索结果。
• 会话包含标题、创建时间、最后更新时间、消息列表、模型来源、摘要和关联文件信息。
• 用户可新建会话、切换历史会话、重命名、删除和清空当前项目会话。
• 默认打开当前项目最近使用的会话；无历史时创建欢迎会话。
• 不应把整个历史无限发送给模型。超过上下文窗口时，保留最近消息并将早期对话压缩为项目会话摘要。
• 代码、设计器模型和构建日志只作为受限上下文传入；不得把工作区全部内容或其他项目内容无差别上传。

持久化要求

• 会话数据按稳定项目 ID 或规范化工作区路径隔离。
• 本地项目数据建议保存到 .lingbuilder/ai/，例如：

.lingbuilder/ai/sessions.json
.lingbuilder/ai/session-index.json

• 生产版本可迁移到 Electron 主进程管理的 SQLite；渲染进程不得直接依赖 localStorage 作为会话记忆的唯一来源。
• API Key、访问令牌和系统账号凭据继续使用 Electron safeStorage，不得写入会话文件、项目文件、日志或模型调用命令行。
• 会话文件使用 UTF-8、原子写入、版本号和损坏恢复策略；加载失败时给出中文诊断，不得静默丢失其他会话。

LangChain.js 的职责

• 将项目会话记录转换为模型消息。
• 负责历史消息裁剪、摘要和可选的检索增强上下文组装。
• 通过统一的 Provider Adapter 调用系统模型或用户模型。
• 不能让 LangChain.js 自行持有跨项目全局 Memory；Memory 的权威数据源必须是 LingBuilder 的项目会话服务。

二、右侧 AI 助手面板

交互要求

• 使用工作台右侧可停靠区域，不占用左侧资源管理器主位置。
• 默认收缩，编辑器优先；用户可通过活动栏图标、菜单、命令面板和快捷键打开或收起。
• 面板支持宽度调整、展开/收缩、会话列表与对话区域切换，并恢复用户上次的可见状态和宽度。
• 窄屏时应自动转为覆盖式侧栏或底部面板，不能压缩编辑器至不可用宽度。
• 所有动作通过 CommandService 注册，菜单入口通过 MenuService 注册；不可在 JSX 中单独实现业务命令。

工作台配置

现有 workbench.aiPanel.visible 可作为可见性配置的基础，并补充：

workbench.aiPanel.visible       是否显示右侧 AI 面板，默认 false
workbench.aiPanel.width         右侧 AI 面板宽度
workbench.aiPanel.activeSession 当前项目最后使用的会话 ID

配置按用户和工作区范围分别存储。项目会话内容不应写入通用工作台配置。

三、系统内置 AI 与用户自定义 AI

默认系统 AI

• 首选模式为 system，使用 LingBuilder 账号、模型目录、额度和流式请求通道。
• 未登录、无可用模型或系统服务不可用时，界面给出明确中文状态，并允许用户切换到自定义 AI。
• 系统 AI 的账户、模型选择、用量和计费逻辑保留在现有云服务与 Electron IPC 边界中。

用户自定义 AI

• 提供 byok 模式，允许设置 Provider、Base URL、模型名和 API Key。
• 首期兼容 OpenAI 兼容接口，并通过受控适配器支持 Gemini、Anthropic、DeepSeek 等已有模型类型。
• API Key 只保存在 Electron 安全凭据存储；配置文件仅保存 Provider、地址、模型名及非敏感选项。
• 连接测试、模型调用、错误诊断和取消请求统一由 AIService 处理，避免各组件直接 fetch 模型接口。
• 自定义接口必须进行地址校验、超时限制、流量大小限制和中文错误提示；不得允许绕过工作区访问和编辑审批约束。

四、代码编辑与 AI Bridge 安全边界

• 聊天、解释和建议可以直接流式显示；涉及文件、设计器或项目结构的变更必须先生成可审查草稿。
• 应用修改必须经过现有的预览、用户确认、原子应用和撤销机制。
• AI Bridge 的 readonly、preview、yolo 权限语义保持不变；LangChain.js 不得开放任意 shell、任意文件访问或绕过 AiBridgeService。
• 每个模型请求只接收经过裁剪的当前项目上下文，并记录必要的安全审计信息。
• 系统 AI 和 BYOK 都必须使用同一套 .lcpp 规则、模块上下文、controlRef 语义、诊断和编辑校验服务。

五、建议实施顺序

1. 新建 AIService、AiConversationService、项目会话数据模型和持久化接口，并把现有组件中的聊天状态迁移出去。
2. 接入项目级会话列表、历史恢复、摘要和上下文裁剪；增加隔离、损坏恢复和迁移测试。
3. 将 AI 助手迁移为工作台右侧可停靠面板，补齐命令、菜单、快捷键、宽度持久化和窄屏布局。
4. 抽象系统 AI 与 BYOK Provider Adapter，统一连接测试、流式输出、取消和错误处理。
5. 引入 LangChain.js，先用于消息编排、摘要和 Provider 适配；需要多步骤工具工作流时再评估 LangGraph。
6. 将代码编辑、工作区检索、模块上下文和 AI Bridge 权限全部接入统一 AIService，并完成端到端测试。

验收标准

• 项目 A 和项目 B 的会话记录、摘要和检索上下文严格隔离；重启 IDE 后仍可恢复各自最近会话。
• 默认启动时 AI 面板收缩，用户可从统一命令打开、收起和调整宽度；桌面与窄屏视口无重叠。
• 未配置时可使用系统内置 AI；用户可切换到自定义 AI，密钥不出现在配置文件和会话记录中。
• 聊天支持流式输出和取消；模型或网络错误有明确中文提示。
• AI 修改代码始终先预览、后确认、可撤销，且不能绕过 AI Bridge 权限、项目路径限制、模块语义和 .lcpp 校验。
• 新增服务和界面通过 TypeScript 检查、现有 AI 相关测试及新增的会话隔离、持久化、布局和 Provider 适配测试。