[Feature] Cursor 会话参考图附件自动进入 --edit / Automatically route Cursor image attachments to --edit

[DaYePython]

中文

背景

在 Cursor Agent 会话中直接粘贴或上传参考图片后，模型能够看到并理解图片，但当前 88api-image-gen 只能通过磁盘路径读取参考图：

node generate.mjs --edit --image \"/absolute/path/reference.png\" --prompt \"...\"

如果 Cursor 没有向 Agent 暴露会话附件的可读本地路径，Skill 无法把原始图片传给 /v1/images/edits。目前可能退化为根据视觉描述执行文生图，导致角色身份、造型、构图和材质的一致性下降，而且用户不一定知道参考图并未真正上传。

期望行为

1. 当会话中存在可读取的图片附件路径，自动识别为参考图。
2. 当用户要求保留、修改、换背景、换风格或基于参考图生成时，自动选择 --edit。
3. 多张附件按消息中的顺序转换为多个 --image 参数，并在提示词中标明每张图的用途。
4. 在发起付费请求前验证文件存在、可读、格式受支持且非空。
5. 如果模型能看到图片但工具拿不到附件路径，明确提示用户，不要静默降级为文生图。
6. 提供一个标准化输入通道，方便 Cursor 扩展、SDK 或其他宿主桥接会话附件。

建议实现

Skill 路由

在 SKILL.md 中增加明确规则：

• 存在可读取的附件路径，并且请求要求基于图片修改或生成时，使用 --edit --image <PATH>。
• 缺少可读取路径时停止并提示用户将图片保存到工作区，或通过 @path 引用。
• 未经用户确认，不把参考图任务静默降级为纯文本生成。

CLI 输入

保留现有 --image <PATH>，并考虑增加结构化清单输入：

node generate.mjs --edit --image-manifest attachments.json --prompt \"...\"

{
 \"images\": [
 {
 \"path\": \"/absolute/path/reference.png\",
 \"role\": \"identity-style-reference\"
 }
 ]
}

也可以支持从 stdin 读取结构化附件数据。建议避免把 base64 直接放进命令行参数，以免触发命令长度限制或泄露到进程列表与日志。

Cursor 桥接

如果 Cursor 宿主或扩展能够访问附件原始字节，可以：

1. 将附件保存到会话级私有临时目录。
2. 将绝对路径和用途注入 Agent 消息。
3. 在整个请求和重试生命周期内保留文件。
4. 任务结束后按策略清理临时文件。

建议的结构化附件信息：

{
 \"type\": \"local_image\",
 \"path\": \"/private/tmp/cursor-attachments/session-id/reference.png\",
 \"mimeType\": \"image/png\",
 \"role\": \"identity-style-reference\"
}

验收标准

• 在 Cursor 中提供一个带可读路径的参考图并要求修改时，Skill 自动调用 --edit。
• 多参考图保持顺序并只提交一个组合编辑请求，除非用户明确选择批量编辑。
• 路径缺失、文件不可读或格式不受支持时，不提交付费请求。
• 日志能说明参考图是否已实际加载，但不输出图片内容或敏感路径之外的数据。
• Codex、Claude Code 等现有路径式工作流不受影响。

---

English

Background

When a reference image is pasted or uploaded in a Cursor Agent conversation, the model may be able to see and understand it, while 88api-image-gen can currently load references only from filesystem paths:

node generate.mjs --edit --image \"/absolute/path/reference.png\" --prompt \"...\"

If Cursor does not expose a readable local path for the conversation attachment, the Skill cannot send the original image to /v1/images/edits. The request may then fall back to text-to-image reconstruction, reducing identity, appearance, composition, and material consistency without making it obvious that the reference was not actually uploaded.

Expected behavior

1. Detect readable image attachment paths in the conversation and treat them as references.
2. Automatically select --edit when the user asks to preserve, modify, restyle, replace the background, or generate from a reference.
3. Preserve message order for multiple attachments and map them to ordered --image arguments, with each image role stated in the prompt.
4. Validate existence, readability, supported format, and non-empty content before starting a paid request.
5. If the model can see an image but the tool has no readable attachment path, report that limitation instead of silently falling back to text-to-image.
6. Provide a standardized input channel that Cursor extensions, the Cursor SDK, and other hosts can use to bridge session attachments.

Proposed implementation

Skill routing

Add explicit rules to SKILL.md:

• When readable attachment paths exist and the request is reference-based, use --edit --image <PATH>.
• When no readable path exists, stop and ask the user to save the image in the workspace or reference it with @path.
• Do not silently downgrade a reference-image task to text-only generation without user confirmation.

CLI input

Keep the existing --image <PATH> interface and consider adding a structured manifest:

node generate.mjs --edit --image-manifest attachments.json --prompt \"...\"

{
 \"images\": [
 {
 \"path\": \"/absolute/path/reference.png\",
 \"role\": \"identity-style-reference\"
 }
 ]
}

Structured input over stdin could also be supported. Passing base64 directly through command-line arguments should be avoided because of command-length limits and exposure through process listings or logs.

Cursor bridge

If the Cursor host or an extension can access attachment bytes, it could:

1. Materialize each attachment in a private session-scoped temporary directory.
2. Inject the absolute path and intended role into the Agent message.
3. Retain the file for the full request and retry lifecycle.
4. Clean it up according to a defined retention policy after completion.

Suggested attachment metadata:

{
 \"type\": \"local_image\",
 \"path\": \"/private/tmp/cursor-attachments/session-id/reference.png\",
 \"mimeType\": \"image/png\",
 \"role\": \"identity-style-reference\"
}

Acceptance criteria

• Given a reference image with a readable path in Cursor, a reference-based request automatically invokes --edit.
• Multiple references preserve order and remain one combined edit request unless batch editing is explicitly requested.
• Missing, unreadable, empty, or unsupported inputs do not start a paid request.
• Logs clearly state whether reference images were actually loaded without printing image contents or sensitive data.
• Existing path-based workflows for Codex, Claude Code, and other clients remain compatible.