Kilo VS Code 插件聊天输入框文件附件机制解析图片粘贴、拖放与 file 路径引用【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode导读本篇文章围绕 Kilo 开源仓库中 file-attachments.md 这份功能设计文档展开深入剖析 VS Code 插件聊天输入框当前的附件能力包括图片附件的粘贴与拖放、file路径提及的拖拽引用以及尚未实现的非图片文件内容附件路线图。读完本文你将掌握 Kilo 聊天输入框附件的支持范围、底层实现MIME 白名单校验、DataTransfer 事件处理、URI 路径解析以及后续待办功能的具体设计方向可直接对照源码与测试用例继续深入。现状概览附件能力的两部分已就绪一部分缺失该文档标记优先级为P2对应 Issue#6078开门见山地界定了聊天输入框附件能力的当前状态✅图片附件支持粘贴与拖放✅file路径提及支持通过语法或拖拽将文件路径带入对话❌非图片文件的内容附件尚缺失——即把文本类文件的内容直接作为消息的一部分发送给模型。因此当前的附件体系实际上是路径引用与图片二进制内容两种形态的混合图片走真实文件数据Data URL其他文件走路径引用mention而读取文件内容并入消息的能力仍在规划中。这也解释了为什么仓库中同时存在两套独立的 HookuseImageAttachments.ts 负责图片附件useFileMention.ts 负责提及与路径追踪。支持的图片类型MIME 白名单文档明确列出四种受支持的图片格式用于粘贴与拖放场景格式MIME 类型PNGimage/pngJPEGimage/jpegGIFimage/gifWebPimage/webp这一白名单在源码中有直接且一致的体现。在 image-attachments-utils.ts 中定义了常量export const ACCEPTED_IMAGE_TYPES [image/png, image/jpeg, image/gif, image/webp] /** Returns true if the given MIME type is an accepted image type. */ export function isAcceptedImageType(mimeType: string): boolean { return ACCEPTED_IMAGE_TYPES.includes(mimeType) }配套的单测 image-attachments-utils.test.ts 对白名单做了边界验证image/png等四种类型返回trueapplication/pdf、text/plain、video/mp4、空字符串返回false尤其值得注意的是image/svgxml与image/bmp虽然同为图片格式但因不在白名单内同样被拒绝。这说明附件校验是严格基于 MIME 精确匹配的枚举白名单而非宽泛的image/*前缀匹配——如需扩展格式支持只需同步修改该常量与测试用例。图片粘贴剪贴板事件中的文件项过滤图片粘贴由 useImageAttachments.ts 中的handlePaste处理const handlePaste (event: ClipboardEvent) { const items Array.from(event.clipboardData?.items ?? []) const imageItems items.filter((item) item.kind file ACCEPTED_IMAGE_TYPES.includes(item.type)) if (imageItems.length 0) return event.preventDefault() for (const item of imageItems) { const file item.getAsFile() if (file) add(file) } }处理逻辑要点遍历剪贴板中的DataTransferItem仅当item.kind file且 MIME 命中白名单时才视为图片附件若剪贴板中没有任何受支持的图片直接return不拦截剪贴板事件保证普通文本粘贴不受影响命中后调用event.preventDefault()阻止默认行为再逐个取出File交给add。而add内部使用FileReader.readAsDataURL将图片读取为 Data URL并封装成统一的ImageAttachment结构export interface ImageAttachment { id: string filename: string mime: string dataUrl: string }每条附件拥有独立idcrypto.randomUUID()生成便于后续按id删除remove与整体清空clear。pending信号用于追踪 FileReader 的异步读取进度读取期间界面可据此展示正在处理中的状态。拖放图片为何必须按住 Shift文档特别强调了一个容易踩坑的交互细节拖放图片到聊天输入框时需要按住 Shift 键。原因在于VS Code 在拖拽操作期间会禁用 webview 的 pointer-events以便自身处理编辑器区域内的拖放按住 Shift 拖拽会重新启用 webview 接收 drop 事件要求 VS Code 1.91源自 microsoft/vscode 的相关 issue。也就是说这是 VS Code 宿主环境对 webview 施加的全局限制而非 Kilo 自身的行为缺陷。若不按 Shiftwebview 内根本收不到拖拽事件图片自然无法落入输入框。在 PromptInput.tsx 的容器元素上可以看到拖放事件的完整接线div classprompt-input-container classList{{ prompt-input-container--dragging: imageAttach.dragging() }} onDragOver{imageAttach.handleDragOver} onDragLeave{imageAttach.handleDragLeave} onDrop{(event) { if (readonly()) { event.preventDefault() return } imageAttach.handleDrop(event) }} 值得注意的几点只读态防护当会话处于只读状态时drop事件只做preventDefault()拦截不产生任何附件拖拽视觉反馈dragging信号驱动prompt-input-container--dragging样式类输入框在拖拽悬停时会有明显的视觉提示对应样式见 prompt-input.css拖离判定handleDragLeave借助isDragLeavingComponent判断拖拽是否真正离开了组件边界relatedTarget为空或不在容器内避免鼠标在输入框内部子元素间移动时闪烁拖拽状态。handleDragOver对可接受的拖拽数据类型做了白名单判断只接受三种const acceptable types.includes(Files) || types.includes(application/vnd.code.uri-list) || types.includes(KILO_FILE_PATH_MIME)刻意拒绝纯text/plain——否则普通的文本拖拽会被误拦截为文件拖放破坏常规编辑体验。这三类数据的含义分别是真实文件拖入Files、VS Code 资源管理器/编辑器标签页拖出application/vnd.code.uri-list、Kilo 内部的文件路径拖拽自定义 MIME。文件路径拖放与 file 提及DataTransfer 的多级解析handleDrop的核心是优先解析文件路径其次才兜底到图片文件const handleDrop (event: DragEvent) { setDragging(false) event.preventDefault() const dt event.dataTransfer if (!dt) return // First: check for text/URI file path drops (VS Code explorer, editor tabs) const paths extractDropPaths(dt) if (paths paths.length 0 onFilePaths) { onFilePaths(paths) return } // Second: fall through to image file drops const files dt.files if (!files) return for (const file of Array.from(files)) add(file) }路径解析实现在 path-mentions.ts 的extractDropPaths中按优先级依次检查三类数据源Kilo 内部相对路径拖拽自定义 MIMEapplication/x-kilo-file-path用于 diff 面板文件头等内部场景内容是可直接用作提及的工作区相对路径VS Code URI 列表application/vnd.code.uri-list来自资源管理器、编辑器标签页的拖出内容是file://或vscode-remote://形式的 URItext/plain兜底仅当每一行都满足isFilePathfile:///vscode-remote://前缀、Unix 绝对路径、Windows 盘符路径如C:\时才会被当作路径处理否则保持普通文本拖拽语义。路径拿到后还需经过convertToMentionPath归一化剥离file://与vscode-remote://协议前缀、decodeURIComponent解码、规范化反斜杠并在文件位于工作区内时转换为相对路径如src/index.ts对workspace/app与workspace/app2这类前缀歧义还做了边界字符检查。最后insertPathMentions会给每个路径加上前缀拼入输入框文本const inserted paths.map((path) ${path}).join( ) 这正好对应了文档filepath mentions work的结论拖一个文件进输入框等价于手打一条路径引用模型侧会通过上下文机制读取对应文件内容而无需把文件内容整体塞进消息体。附件生命周期的另一面消息恢复时的回填附件并不只存在于输入框这一个瞬时状态。在消息被恢复例如 revert 到某条历史消息时附件需要被精确回填。相关协议定义在 extension-messages.ts 的SetChatBoxMessage中export interface RestoredImage { dataUrl: string mime: string filename?: string } export interface SetChatBoxMessage { type: setChatBoxMessage text: string /** 被恢复消息携带的文件附件精确相对路径若有如 revert 到带 mention 的消息 */ paths?: string[] /** 被恢复消息引用的历史会话与 paths 同样方式回填 */ sessions?: SessionSearchItem[] /** 被恢复消息附带的图片存在即视为权威值PromptInput 用其替换当前附件 */ images?: RestoredImage[] }设计上有两个细节值得注意paths采用精确路径回填而非从文本正则反推——注释中明确指出当真实路径包含空格时正则无法区分完整提及与截断前缀因此必须携带权威路径列表images字段存在即权威PromptInput会用该列表整体替换当前附件空数组即清空字段缺失则保持现状不动。这避免了恢复动作与用户正在编辑的附件状态互相覆盖。这从协议层面印证了文档所言image attachments … work图片附件的存取、回填链路已经完整闭环。剩余工作路线图非图片文件内容附件文档以 Remaining Work 小节完整列出了下一步规划这是附件能力从路径引用走向内容附件的关键设计清单输入框工具栏新增附件按钮回形针或类似图标支持非图片文件拖放到聊天输入区域通过按钮唤起文件选择对话框文本类文件读取内容作为消息中的文本部分text part随消息发送二进制文件展示不支持提示附件展示在输入框上方以 chips/标签形式列出已附加文件并带移除按钮大小限制限制附件体积超出时给出明确错误提示。对照现有源码结构可以推断出该路线图的落点第 13 项会扩展PromptInput工具栏与useImageAttachments的setFilePathDropHandler机制后者已预留了文件路径拖放回调的注册口子第 45 项需要新增按 MIME 判断文本类 vs 二进制的分派逻辑——现有的ACCEPTED_IMAGE_TYPES白名单模式可以天然扩展为一张包含text/*、application/json等的多级类型表第 6 项可复用图片附件已实现的id-remove-clear删除链路第 7 项则与pending信号、FileReader 读取链路天然衔接。可以说路线图的每一项都能在当前架构中找到对应的挂载点。总结Kilo 聊天输入框的附件能力目前呈双轨形态图片以真实数据Data URL附加其他文件以路径引用。本文从设计文档出发结合 useImageAttachments.ts、path-mentions.ts、PromptInput.tsx 及其配套测试完整还原了 MIME 白名单校验、粘贴/拖放事件处理、VS Code Shift 拖拽限制、URI 路径归一化与消息恢复回填的实现细节。对于希望参与该 P2 功能开发的读者可从文档的 Remaining Work 清单入手以图片附件链路为模板向文本内容附件 chips 展示 大小限制方向扩展即可。【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考