SystemPrompt

最小定义

We0Agent 构造时必须传入 SystemPrompt。它由多个 SystemPromptBlock 组成，按顺序拼接后进入模型输入。

from we0agent.prompts.core import SystemPrompt, SystemPromptBlock

system_prompt = SystemPrompt(
    blocks=[
        SystemPromptBlock(text="你是一个可靠的工程助手。"),
        SystemPromptBlock(text="回答保持简洁，必要时给出代码。"),
    ]
)

系统提示词默认只参与模型输入投影，不会作为持久化消息写入会话数据库。

构造好的 system_prompt 直接传给 We0Agent：

agent = We0Agent(
    name="assistant",
    model=model,
    system_prompt=system_prompt,
)

Mermaid

Rendering diagram...

Block 字段

字段	类型	说明
`key`	`str \| None`	内容块稳定标识，可省略；省略时按顺序自动生成 `block-1`、`block-2`。
`text`	`str`	渲染后的提示词正文。
`cache_point`	`bool`	对 Anthropic provider 生效，标记该段写入 prompt cache。

PromptBuilder

如果系统提示词需要从文件、变量和条件分段生成，可以使用 PromptBuilder。

from pathlib import Path
from we0agent.prompts.core import PromptBuilder

prompt = (
    PromptBuilder(
        prompts_root=Path("prompts"),
        project_root=Path.cwd(),
    )
    .static("role", file="@role.md")
    .dynamic("repo", text="当前仓库：{{repo_name}}", needs=["repo_name"])
    .with_variables({"repo_name": "we0-agent-sdk"})
    .build()
)

路径解析规则：

写法	解析方式
`@role.md`	相对 `prompts_root`。
`file:docs/system.md`	相对 `project_root`。
`/abs/path/system.md`	绝对路径。
`docs/system.md`	相对 `project_root`。

Static 和 dynamic

static() 必须出现在第一个 dynamic() 之前。这样可以把稳定的角色、约束和长文档放在前面，把动态用户上下文、工作区信息和系统提醒放在后面。

builder.static("role", text="你是一个代码助手。")
builder.static("rules", file="@rules.md").cache_point()
builder.dynamic("workspace", text="当前路径：{{cwd}}", needs=["cwd"])

needs 用来声明变量依赖。依赖变量缺失时，该段会被跳过。模板里的 {{name}} 缺失时会抛出 ValueError，避免静默生成残缺 prompt。

Prompt cache

cache_point() 会把最近追加的一段标记为缓存点。当前内置适配只对 Anthropic family 写入 cache_control，其他 provider 会忽略该标记。

prompt = (
    PromptBuilder(prompts_root=Path("prompts"), project_root=Path.cwd())
    .static("core", file="@core.md")
    .cache_point()
    .dynamic("task", text="{{task}}")
    .with_variables({"task": "整理当前变更。"})
    .build()
)