iFlow Harness for VSCode

心流·驭光 — iFlow CLI 的 VSCode 图形前端：通过 ACP（Agent Client Protocol） 驱动本地 iFlow CLI，在编辑器标签页里完成对话、工具审批、代码评审与文件修改的完整 agent 工作流。

亮点

• 开箱即用：扩展内置裁剪版 iFlow CLI，未安装 CLI 的机器装上就能用（整体 VSIX 约 13MB）；本地安装的 CLI 仍会被优先探测，升级不受内置版本影响
• 模型兼容增强：内置 CLI 外挂 5 个定制 loader——按模型配置输出 token 上限（长回复不再被截断）、上下文余量按真实窗口计算、Kimi 采样参数规范化、多模态识别与视觉路由配置化（修复 OpenAI Compatible 模式图片输入）、声明式思考参数规则；loader 源自 iFlow-Mods Mod 机制，默认规则随扩展分发、连接前自动种到 ~/.iflow/（不覆盖已有配置），编辑 JSON 即可自定义模型行为、无需改源码，Mod 可用 iFlow-Mod-Builder 图形化打包
• 完整 agent 工作流：流式对话、工具审批、行号 Diff 与一键 Revert、Plan 计划确认、交互式提问卡（单选 / 多选 / 自由文本）、子智能体进度卡片
• 长任务自动恢复：速率限制按 5s / 15s / 30s 递增退避自动重试；上下文溢出自动压缩并重发原 prompt——限流与长上下文都不再中断任务
• 凭据与审批安全：API Key 只存 VSCode SecretStorage（不落盘明文、不打日志）；审批默认拒绝、5 分钟超时自动拒答；Webview 走 nonce CSP + DOMPurify 净化
• 零等待热切换：切换 API Profile 热重认证、免重启 CLI；iflow.warmStart 窗口打开即后台预热，首次打开面板无需等待
• 精致界面：Win12 风格亚克力材质、深浅色主题跟随编辑器、超长会话离屏渲染流畅不卡

功能

对话与生成

• 流式对话：思考过程折叠、Markdown 渲染、一键中断
• 粘性「正在生成」指示器，生成期间切换类操作全量防呆禁用，操作消息防抖
• 子智能体卡片：按类型着色、步骤进度、本地化标题与日志面板
• 提问卡：agent 发起 ask_user_question 提问时渲染交互卡，支持单选 / 多选 / 自由文本
• Plan 模式审批：agent 提交计划时弹出确认卡，通过或驳回（附理由）
• 自动恢复：速率限制递增退避重试，上下文溢出自动压缩并重发原 prompt
• 提示音：对话完成 / 失败音效（Web Audio 合成，iflow.soundFeedback 可关）

工具与审批

• 工具调用卡片：类型、状态、位置、输出结构化展示
• 行号 Diff 视图，支持一键 Revert 与 VSCode 原生并排对比（Open Diff）
• 审批流：请求卡片（允许一次 / 始终允许 / 拒绝），5 分钟超时自动拒绝，结果回写对话记录
• Revert 前对「编辑器有未保存修改」「磁盘内容与 diff 不一致」二次确认

上下文与输入

• @文件补全：输入框 @ 触发工作区文件模糊搜索，键盘选择插入
• 选区上下文：编辑器右键 Ask iFlow（直接提问）/ Add to iFlow Context（生成代码上下文卡，发送时前置到 prompt，可移除）
• 附件：粘贴 / 拖拽 / OS 文件选择器多路径添加，图片缩略图回显并可内置预览，其他文件作为路径附件发送（>5MB 图片自动降级为文件附件）
• Chat Participant：VSCode Chat 中 @iflow 纯文本通道，富交互仍在面板内

会话与配置

• 会话管理：历史会话切换 / 删除、重启 VSCode 后自动恢复上次会话、无标题会话以首条消息自动命名、恢复时自动滚动到底部
• API 配置：OpenAI 兼容凭据存 VSCode SecretStorage（不落盘明文、不入日志），多 Profile 热重认证免重启 CLI，生成期间禁用凭据变更
• 模型列表实时查询当前 endpoint 的 /models（不使用 CLI 内置硬编码目录），下拉支持模糊搜索，打开时实时刷新配置与模型
• 主题：深 / 浅色切换，默认跟随编辑器主题；Win12 风格亚克力材质界面
• 状态栏：agent 状态（连接中 / 就绪 / 生成中 / 等待审批 / 出错）与当前模型一目了然，点击打开面板

前置要求

• VSCode ^1.90.0
• iFlow CLI（可选）：扩展已内置 CLI，开箱即用；本地安装的 CLI 会被优先探测（PATH 与常见安装位置，也可用 iflow.cliPath 指定）
• 可用的 OpenAI 兼容 API 端点（baseUrl + apiKey + modelName）

扩展设置

使用

1. 安装扩展后，点击状态栏右侧的 iFlow 状态项打开面板（也可用编辑器标签栏图标或命令面板 iFlow: Open Chat Panel）；面板是独立编辑器标签页，宽度可自由拖拽
2. 首次使用按提示配置 API 凭据（OpenAI 兼容地址 + Key + 模型名），或直接切换 CLI 已有的配置
3. 输入消息开始对话；工具调用会在面板中请求审批，Diff 卡片支持 Open Diff 与 Revert
4. Chat 视图中 @iflow <问题> 可走纯文本通道快速提问

开发

npm install
npm run build         # tsc 类型产出 + esbuild 打包 host + vite 构建 webview
npm run typecheck     # host 侧类型检查
npm test              # vitest（136 用例，含 mock ACP agent 集成测试，不依赖真实 CLI/API）
npm run harness       # 驱动真实 CLI 走 ACP 全流程（--record 录制 wire 日志）
npm run vendor:cli    # 拉取并裁剪 iFlow CLI 到 vendor/（package 时自动执行）
npm run defaults:sync # 同步本机 ~/.iflow/ 默认规则到 scripts/iflow-defaults/（发布前）
npm run package       # vendor:cli + build + vsce 打包 → .vsix（含内置 CLI）

• F5 调试：.vscode/launch.json 提供扩展调试配置（Extension Development Host）；启动前先 npm run build，因为 main 指向 ./dist/extension.cjs
• webview 侧类型检查：cd webview && npx tsc --noEmit
• webview 增量构建：npm run webview:dev
• 浏览器调试 webview：webview/dist 用任意静态服务器打开即可（内置 mock host，无需 VSCode）
• 新增 UI 文案请走 i18n：host 用 vscode.l10n.t（英文加 l10n/bundle.l10n.en.json），manifest 用 %key%（补 package.nls*.json），webview 用 src/i18n.ts 字典

发布

CHANGELOG.md 是版本的唯一来源：CI 从顶部 ## [x.y.z] - date 标题读取版本号写入 package.json，其下条目作为发布摘要。新增版本只需在 CHANGELOG 加一节，不要手动改 package.json 的 version。

• ci.yml：release 分支的 push 与 PR 触发，三平台矩阵（ubuntu / windows / macos）跑 typecheck → test → build
• release.yml：仅 release 分支（或手动触发）：读 CHANGELOG 版本与摘要写入 package.json → npm run package（内置 CLI 一起打进 .vsix）→ 打 tag v* 建 GitHub release 并附 .vsix

架构

三层单向数据流：webview/（React 投影）← 节流快照 ← shared/（纯 reducer）← ACP 事件 ← src/（Extension Host）← NDJSON ← iFlow CLI 子进程。状态只存在于 Extension Host，WebView 只渲染快照。

架构细节、开发约定与已知陷阱详见 AGENTS.md。

License

MIT