Skip to main content
工具与扩展

系统提示词

替换或扩展 Qoder CLI 的系统提示词，控制加载哪些指令文件，并查看实际进入上下文的内容。

系统提示词决定了一个通用模型会成为什么样的 Agent：它的语气、优先级，以及哪些规则不可逾越。 Qoder Agent SDK 提供三层能力，可以叠加使用。建议从改动最小的一层开始，仅在确有需要时再往下：
层级机制适用场景
追加到预设之后systemPrompt / system_prompt 预设形式保留 Qoder CLI 的 Agent 行为，同时加入自己的规则
加载指令文件settingSources / setting_sources规则存放在仓库中，且需对人和 Agent 同时生效
完全替换systemPrompt / system_prompt 字符串构建非编程用途的 Agent，需要自定义完整的行为约定
两种语言均支持这三层。Python 还额外支持从文件加载的形式，TypeScript 没有——详见从文件加载提示词。

追加到预设之后

推荐的默认做法。Qoder CLI 预设内置了工具使用规范、任务规划行为和输出约定，它们是 Agent 在长任务中持续收敛的关键。追加方式保留这一切，只在末尾加入你的规则。 
options: {
  systemPrompt: {
    type: 'preset',
    preset: 'qodercli',
    append: [
      'Always write tests before implementation.',
      'Never edit files under vendor/.',
      'Reply in Simplified Chinese.',
    ].join('\n'),
  },
}
凡是属于团队规约性质的规则，都应优先用这种形式。为了加三条规则而重写整个提示词，会连带丢失原本无意改动的行为。

完全替换提示词

传入字符串会覆盖预设。Agent 仍保留其工具和循环，但除此之外的行为不再有任何预设约束。 
options: {
  systemPrompt: `You are a release auditor.

Inspect the repository and report findings. You may read files and run
read-only commands. Never modify the working tree. Answer with a numbered
list of findings, each tagged CRITICAL, WARNING, or INFO.`,
}
正是这一层让 SDK 的用途超出编程助手：分诊 Agent、数据分析 Agent、文档 Agent 都可以替换提示词，同时复用同一套 Harness——Agent 循环、工具执行、权限校验和会话管理保持不变。
完全替换会在移除预设风格的同时移除其安全约束。若替换后的提示词未提及校验改动或限定在工作目录内，Agent 便没有相应指令可循。完全替换时，应同时配置明确的权限控制。

从文件加载提示词

Python SDK 支持第三种形式：从磁盘读取提示词。这样可将较长的提示词从应用代码中剥离，独立进行版本管理和评审。 
options = QoderAgentOptions(
    system_prompt={"type": "file", "path": "./prompts/release-auditor.md"},
)
语言可用性：仅 Python。TypeScript 没有对应的文件形式。在 TypeScript 中，请自行读取文件内容，再以字符串形式传入。

从文件系统加载指令

指令文件让规则与其约束的代码放在一起，从而对人和 Agent 施加同一份指引。settingSources 决定会话读取其中哪些文件。 
// 加载用户级、项目级和本地指令文件（CLI 默认行为）
options: { settingSources: ['user', 'project', 'local'] }

// 不从磁盘加载任何文件——应用是唯一的事实来源
options: { settingSources: [] }
多租户或托管部署应使用 settingSources: []。否则 Agent 的行为将取决于运行 Qoder CLI 的机器上恰好存在哪些文件，导致不同主机上的运行结果无法复现。

查看实际加载的内容

提示词问题往往源于"不知道那个文件也被加载了进来"。InstructionsLoaded Hook 会为每个指令文件触发一次，因此可以记录真实的组成，而非凭经验推测。 
options: {
  hooks: {
    InstructionsLoaded: [
      {
        hooks: [
          async (input) => {
            console.log(`[instructions] ${input.memory_type} ${input.file_path} (${input.load_reason})`);
            return {};
          },
        ],
      },
    ],
  },
}
字段取值含义
memory_typeUser、Project、Local、Managed文件来自哪个作用域
load_reasonsession_start、nested_traversal、path_glob_match、include、compact被加载的原因
file_path路径被加载的文件
nested_traversal 和 include 是最易被忽视的两种：指令文件可以引入其他文件，因此实际生效的提示词可能比你编写的单个文件大得多。

单独调整输出风格

输出风格影响 Agent 如何呈现结果，但不改变其行为规则。它是设置层的取值，而非查询选项： 
options: {
  settings: { outputStyle: 'concise' },
}
当前风格及可选集合可从会话初始化消息中读取： 
const init = await q.initializationResult();
console.log(init.output_style, init.available_output_styles);
当问题是"太啰嗦"或"格式不对"时，调整输出风格；当问题是"做错了事"时，调整 systemPrompt。

下一步

  • 自定义工具 —— 扩展 Agent 能做什么，而不只是如何表现
  • Skills —— 将可复用的指令封装为按名调用的能力
  • 子 Agent —— 为委派的任务配置独立的提示词和工具集
  • Hooks —— 在会话的各生命周期节点检查并拦截
快速开始
核心概念
对话与会话
工具与扩展
控制与安全
参考