CodeBuddy 支持通过 {state:xxx} 占位符实现状态管理。实际使用时，建议按照以下流程操作：先定义占位符，再在提示词或指令中引用，最后在 API 请求的 state 字段中传入对应参数值；同时也支持通过 【重置所有{state:xxx}】 清空状态，或使用 [scope:session] 指定作用域，并且需要配合 X-CodeBuddy-State-Mode 请求头一起使用。

在 CodeBuddy 提示词中加入状态管理机制，主要是为了让 AI 在多轮对话或连续请求中准确记住用户设定的角色信息、上下文限制或临时变量，例如“当前分析的文件是report_v2.pdf”“本次不解释原理，只输出JSON”等，从而避免每次提问都重复输入相同条件，提升提示词效率与调用准确性。

用占位符+指令组合实现轻量状态绑定

第一步：在提示词开头定义状态占位符，标准格式为{state:xxx}，例如{state:file_name}或{state:output_format}。这是 CodeBuddy 状态管理的基础写法。

第二步：在后续指令中直接引用该占位符，例如“请基于{state:file_name}中的第三页数据生成摘要”，AI 在执行时会自动将实际传入的值替换进去。

第三步：调用CodeBuddy API时，需要在请求体的state字段中传入对应键值对，例如{"file_name": "log_202405.txt", "output_format": "markdown"}。如果这一步遗漏，占位符会被原样输出，无法完成变量替换。

用分段指令控制状态生命周期

方法一：显式清空指令

在提示词末尾添加一句“【重置所有{state:xxx}占位符】”，当 CodeBuddy 识别到这条固定指令后，会忽略此前传入的 state 字段值，使后续轮次从空状态重新开始。这种方式适合需要重置上下文或清除历史变量的场景。

方法二：作用域限定指令

用[scope:session]包裹某一段提示词，表示其中引用的{state:xxx}仅在当前 API 调用内生效，不会影响下一次请求。不添加此标记时，相关状态默认会跨请求持续保留。

【必须在API请求头中添加X-CodeBuddy-State-Mode: scoped才能使[scope:session]生效】

避免状态污染的关键写法

不要在提示词中直接写“记住上一条消息里的参数”，因为 CodeBuddy 不会自动继承历史输入内容；所有状态变量都必须通过{state:xxx}进行显式声明，并在 API 请求中明确传参。

当多个状态名称语义相近时（如{state:mode}和{state:run_mode}），一定要保持命名清晰且唯一，否则后传入的值可能覆盖先前同名或易混淆项，并且系统不会给出额外警告。这是编写 CodeBuddy 状态管理提示词时需要重点注意的细节。