Prompt 定制与多模态
默认情况下，Cody 会把你当成通用编程助手来组织系统提示。很多场景下，你希望它变成专用助手：只做安全审查、只按某种语气回复，或者能「看见」截图里的界面再写代码。本篇用同一条叙事线：先给可运行的完整示例，再拆开讲 system_prompt()、extra_system_prompt() 以及多模态 MultimodalPrompt。
本系列演示模型统一为 qwen3.5-plus。请像第 01 篇那样配置环境变量（CODY_MODEL、CODY_MODEL_API_KEY、CODY_MODEL_BASE_URL），下面示例中的 Cody().workdir("...").build() 即可不显式写模型；需要写死模型时可用 .model("qwen3.5-plus").base_url("https://coding.dashscope.aliyuncs.com/v1").api_key("sk-xxx")。
先看完整例子：安全审查 + 中文回复
下面这段程序一次性做完两件事：用 system_prompt() 把「人设」换成安全审查员，用 extra_system_prompt() 要求始终用中文回答。跑通之后再读后面各节，会很容易对应上每个 API 在做什么。
import asyncio from cody.sdk import Cody async def main() -> None: # 替换默认编程助手人设，并追加「始终中文」约束 client = ( Cody() .workdir(".") .system_prompt("You are a security reviewer. Focus on injection and secrets.") .extra_system_prompt("Always reply in Chinese.") .build() ) result = await client.run("请快速审查：这段代码有没有明显的安全问题？") print(result) if __name__ == "__main__": asyncio.run(main())
system_prompt()：替换角色
system_prompt() 会替换默认的通用编程助手 persona（基础系统角色），适合你把 Agent 定义成「只做一类事」的专家，例如安全审查、文档生成、测试编写等。
# system_prompt() —— 替换默认 persona client = Cody().workdir(".").system_prompt("You are a security reviewer.").build()
一旦设置了 system_prompt()，框架不再使用内置的「通用编程助手」那段基础人设；其余与项目、工具、技能相关的内置说明仍会按框架逻辑组装（与「整段系统提示全部手写」不同）。若你只想加几条规矩而保留默认人设，请用下一节的 extra_system_prompt()。
extra_system_prompt()：追加约束
extra_system_prompt() 在所有内置 prompt 之后再追加一段文字，不会换掉默认编程助手身份。典型用法：输出语言、格式（如 Markdown 标题层级）、语气、合规话术等。
# extra_system_prompt() —— 在所有内置 prompt 后追加 client = ( Cody() .workdir(".") .extra_system_prompt("Always reply in Chinese.") .build() )
对比：system_prompt 与 extra_system_prompt
两者名字相近，但语义一个是「换身份」，一个是「加备注」。下面表格帮你一次记清。
| 维度 | system_prompt() |
extra_system_prompt() |
|---|---|---|
| 作用 | 替换默认基础人设（persona） | 在内置系统提示末尾追加一段说明 |
| 与内置 prompt 的关系 | 不再使用框架提供的默认「通用编程助手」基础角色 | 保留完整内置系统提示，仅在其后拼接你的约束 |
| 典型场景 | 专用 Agent：安全审计、只写测试、只写文档等 | 全局偏好：语言、格式、风格、禁止事项等 |
| 可多次调用 | 以 Builder 最后一次设置为准（覆盖） | 以 Builder 最后一次设置为准（覆盖） |
| 能否同时使用 | 可以。常见组合：自定义人设 + 追加语言/格式约束（见下文）。 | |
组合使用
生产里经常出现「我要专用身份，但还要统一加几条全项目规矩」。这时两个 API 一起用即可：先 system_prompt() 定角色，再 extra_system_prompt() 叠约束。
client = (
Cody()
.workdir(".")
.system_prompt(
"You are a security reviewer. Prioritize OWASP-style issues and false-positive hints."
)
.extra_system_prompt(
"Always reply in Chinese. Use Markdown with ## for sections."
)
.build()
)
若你只写 extra_system_prompt()，用户感知仍是「还是那个 Cody 编程助手，但多了几条家规」；若加上 system_prompt()，对话基调会明显变成你定义的专家角色。
多模态：MultimodalPrompt 与 ImageData
有时用户任务不是纯文本，而是一张设计稿或界面截图。Cody 提供 MultimodalPrompt：一段 text 加上若干 ImageData（Base64 字符串 + MIME 类型 + 可选文件名）。注意 需要模型本身支持视觉（如支持图像输入的 qwen3.5-plus 等多模态模型），否则会失败或表现异常。
单图示例
从本地读入 PNG，编码为 Base64，再交给 client.run() 或 client.stream()。
import base64 from cody.core.prompt import MultimodalPrompt, ImageData from cody.sdk import Cody client = Cody().workdir(".").build() with open("screenshot.png", "rb") as f: b64 = base64.b64encode(f.read()).decode() prompt = MultimodalPrompt( text="实现这个页面", images=[ ImageData( data=b64, media_type="image/png", # image/png | image/jpeg | image/webp | image/gif filename="screenshot.png", ) ], ) result = await client.run(prompt)
多图与格式
单图与多图的区别仅在于 images 列表长度：一张图时列表里一个 ImageData；多张图时按顺序放入多个 ImageData，模型会同时看到多张参考图（具体上限取决于模型与服务商）。
media_type 需与文件真实格式一致，常用取值：
image/pngimage/jpegimage/webpimage/gif
# 多图：在 images 列表中放多个 ImageData prompt = MultimodalPrompt( text="对比这两张图，列出 UI 差异并给出改法", images=[ ImageData(data=b64_a, media_type="image/png", filename="before.png"), ImageData(data=b64_b, media_type="image/jpeg", filename="after.jpg"), ], ) # 流式同样传入 MultimodalPrompt async for chunk in client.stream(prompt): ...
ImageData 的 data 为 Base64 编码的原始字节对应的字符串（不要带 data:image/png;base64, 前缀，除非你的接入层另有约定）。filename 便于日志与调试，可按需填写。
小结
本篇你掌握了：用 system_prompt() 换掉默认编程助手人设、用 extra_system_prompt() 在内置系统提示后追加约束，以及用 MultimodalPrompt + ImageData 把截图/design 喂给支持视觉的模型。下一篇我们会进入 Skills，让 Agent 按项目约定加载可复用能力，请继续阅读 07. 使用 Skills。