截图分析

Codely CLI 提供了智能的截图分析功能，允许用户通过剪贴板直接粘贴图片到输入提示中，系统会自动保存图片并插入引用。

概述

截图功能是 Codely CLI 的一个便捷特性，它能够：

• 自动检测剪贴板中的图片：识别剪贴板是否包含图像数据

• 自动保存到临时目录：将图片保存到项目的 .codely-cli/clipboard/ 目录

• 智能插入引用：在光标位置自动插入图片引用文本

• 跨平台支持：支持 Windows 和 macOS 系统

• 自动清理：自动清理超过 1 小时的临时图片文件

工作原理

检测流程

• 用户按下 Ctrl+V 进行粘贴操作
• 系统检测剪贴板内容类型
• 如果是图片，执行截图保存流程
• 如果是文本，执行普通文本粘贴

保存流程

用户截图 → 复制到剪贴板 → Ctrl+V 粘贴
    ↓
检测剪贴板类型
    ↓
保存到 .codely-cli/clipboard/clipboard-\{timestamp\}.png
    ↓
在光标位置插入 "Screenshot saved to {relativePath}."

非交互模式使用

在非交互模式下，截图功能通过键盘快捷键触发。

基本用法

# 启动 Codely CLI
codely

# 在输入提示中：
# 1. 使用系统截图工具截图（如 Windows 的 Win+Shift+S 或 macOS 的 Cmd+Shift+4）
# 2. 按下 Ctrl+V 或者 Alt+V 粘贴

使用示例

1. 基础截图粘贴

> [截图并复制到剪贴板]
> [按下 Ctrl+V 或者 Alt+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.

2. 在已有文本中插入截图

> 请分析这个界面的设计：[按下 Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png. 并给出改进建议

3. 多次截图

> 这是第一个截图：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> 这是第二个截图：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>
> 请对比这两个界面的差异

交互模式使用

在交互模式下，截图功能的使用方式与非交互模式相同，主要通过 Ctrl+V 快捷键触发。

交互模式下的应用场景

1. UI/UX 设计评审

> 请帮我评审这个界面的设计：[Ctrl+V 粘贴截图]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 从可用性、美观性和一致性方面给出建议

2. 错误排查

> 我遇到了这个错误：[Ctrl+V 粘贴错误截图]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 请帮我分析可能的原因和解决方案

3. 代码审查

> 请审查这段代码的输出结果：[Ctrl+V 粘贴截图]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 指出可能的问题和改进点

4. 文档编写

> 我要为这个功能写文档，请根据截图：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 生成功能说明和使用步骤

技术实现

平台支持

Windows

使用 PowerShell 进行剪贴板操作：

# 检查剪贴板是否包含图片
Add-Type -AssemblyName System.Windows.Forms
if ([System.Windows.Forms.Clipboard]::ContainsImage()) {
    Write-Output 'true'
} else {
    Write-Output 'false'
}

# 保存剪贴板图片
$image = [System.Windows.Forms.Clipboard]::GetImage()
$image.Save('path/to/file.png', [System.Drawing.Imaging.ImageFormat]::Png)

macOS

使用 AppleScript 和 osascript 进行剪贴板操作：

# 检查剪贴板类型
clipboard info | grep -E "«class PNGf»|TIFF picture|JPEG picture"

# 保存剪贴板图片
set imageData to the clipboard as «class PNGf»
set fileRef to open for access POSIX file "path/to/file.png" with write permission
write imageData to fileRef
close access fileRef

文件命名规则

• 格式：clipboard-{timestamp}.{extension}
• 时间戳：使用毫秒级时间戳确保唯一性
• 扩展名：根据图片格式自动选择（.png、.jpg、.tiff、.gif）

示例：

clipboard-1704096000000.png
clipboard-1704096100000.jpg
clipboard-1704096200000.tiff

存储位置

• 默认目录：<项目根目录>/.codely-cli/clipboard/
• 相对路径引用：插入的引用使用相对于项目根目录的路径

示例：

项目结构：
my-project/
├── .codely-cli/
│   └── clipboard/
│       ├── clipboard-1704096000000.png
│       └── clipboard-1704096100000.png
├── src/
└── README.md

插入的引用：
"Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png."

自动清理机制

系统会自动清理超过 1 小时的临时图片文件：

高级用法

与文件引用结合使用

> 请分析以下文件和截图：
> @src/components/Button.tsx
> 和 [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 检查代码实现与截图显示是否一致

在多行输入中使用

> 我有以下几个问题需要解决：
>
> 1. [Ctrl+V]
>    Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>    这个界面的布局有问题
>
> 2. [Ctrl+V]
>    Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>    这个按钮点击没有反应
>
> 请分别给出解决方案

与斜杠命令结合

> /analyze
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 分析这个截图中的代码结构

常见问题

Q: 为什么我粘贴图片后没有看到引用文本？

A: 可能的原因： 剪贴板中没有图片，系统执行了文本粘贴 系统不支持当前平台的剪贴板操作（目前仅支持 Windows 和 macOS） 图片保存失败（检查磁盘空间和权限）

Q: 截图保存在哪里？

A: 默认保存在项目根目录的 .codely-cli/clipboard/ 目录下。可以使用相对路径引用这些文件。

Q: 临时图片会被自动删除吗？

A: 是的，系统会自动清理超过 1 小时的临时图片文件。如果需要长期保存，请手动复制到其他位置。

Q: 支持哪些图片格式？

A: 系统支持以下格式（按优先级）： PNG（推荐） JPEG TIFF GIF

Q: 可以在 Linux 上使用吗？

A: 目前截图功能仅支持 Windows 和 macOS。Linux 支持计划在未来版本中添加。

Q: 粘贴图片后如何查看？

A: 插入的文本是相对路径引用。你可以： 使用图片查看器打开 .codely-cli/clipboard/ 目录下的文件 让 AI 模型分析图片（如果模型支持多模态） 手动将文件移动到项目中其他位置

Q: 粘贴图片后文本位置不对怎么办？

A: 系统会自动在光标位置插入文本，并智能添加空格。如果位置不对： 使用方向键移动光标到正确位置 删除错误位置的文本 重新粘贴

最佳实践

1. 命名截图以便管理

虽然系统自动生成文件名，但建议在提示中描述截图内容：

> 这是登录界面的截图：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
> 请分析其用户体验

2. 及时清理不需要的截图

虽然系统会自动清理 1 小时前的截图，但建议： 定期检查 .codely-cli/clipboard/ 目录 手动删除不需要的截图 将重要截图移动到项目的文档目录

3. 结合文本描述

单独的截图可能不够清晰，建议结合文本描述：

> 请帮我修复这个 Bug：
>
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> 错误信息显示 "Connection timeout"，发生在点击"提交"按钮后。
> 预期行为是显示成功消息并跳转到下一页。

4. 使用多个截图进行对比

> 请对比这两个设计版本：
>
> 版本 A：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> 版本 B：[Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096100000.png.
>
> 从视觉层次、可读性和交互友好性方面进行分析

5. 在文档中使用截图

> 我要为"用户注册"功能编写文档，请根据以下内容生成 Markdown 文档：
>
> [Ctrl+V]
>  Screenshot saved to .codely-cli/clipboard/clipboard-1704096000000.png.
>
> 功能描述：用户可以通过此表单注册新账号，需要填写邮箱、密码和确认密码。
> 验证规则：邮箱格式验证、密码至少 8 位、两次密码输入必须一致。

键盘快捷键

快捷键	说明
Ctrl+V Alt+V	粘贴剪贴板内容。如果剪贴板包含图片，将自动保存并插入引用

相关功能

• 文件引用：使用 @path/to/file 引用项目中的文件
• 多模态输入：如果 AI 模型支持，可以直接分析图片内容
• 外部编辑器：使用 Ctrl+X 打开外部编辑器进行复杂输入

技术限制

• 平台支持：仅支持 Windows 和 macOS
• 图片格式：依赖系统剪贴板支持的格式
• 存储位置：必须在项目目录内，不支持跨项目共享
• 文件大小：受系统剪贴板和磁盘空间限制
• 并发操作：快速连续粘贴可能导致文件名冲突（通过时间戳缓解）

故障排查

截图未保存

检查：

• 剪贴板是否真的包含图片（尝试粘贴到其他应用）
• .codely-cli/clipboard/ 目录是否有写入权限
• 磁盘空间是否充足
• 查看控制台错误信息

文件引用路径错误

检查：

• 是否在正确的项目目录下运行 Codely CLI
• .codely-cli/clipboard/ 目录是否已创建
• 相对路径计算是否正确

粘贴后无响应

检查：

• 是否正确按下 Ctrl+V
• 是否在输入提示获得焦点时粘贴
• 是否有其他快捷键冲突

参考资源

• 键盘快捷键文档 (编写中)
• 命令行参数文档
• 常见工作流程 (编写中)