系统提示

系统提示可用于约束代理行为、添加特定领域上下文，或设定响应的语气与风格。

默认情况下，SDK 使用内置系统提示，为代理提供核心能力，包括文件编辑、代码搜索和 Shell 访问。您可以完全替换该提示，也可以在其后追加额外指令。

替换默认提示

向 systemPrompt 选项传入字符串即可完全替换内置系统提示。当您需要完全控制代理行为且不希望保留任何默认指令时使用此方式。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  systemPrompt: `You are a code review assistant.
Prioritize finding bugs, security issues, and maintainability risks.
Explain the issue and suggest concrete fixes.`,
});

警告

替换默认提示将移除所有内置说明，包括工具使用指南和安全约束。仅在确有需要完全控制代理行为时才替换提示。

追加到默认提示

要保留内置能力并添加自定义指令，可使用包含 append 字段的系统提示预设对象。预设名称为隐式指定，因此只需提供 {"type": "preset", "append": ...}。该方式会在默认系统提示之后追加您的指令。

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  systemPrompt: {
    type: "preset",
    append: "Focus on Python files. Always run pytest after making changes.",
  },
});

两种 SDKs 均支持仅追加的简写形式：

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  appendSystemPrompt: "Focus on Python files. Always run pytest after making changes.",
});

常见模式

专注于评审的代码检查器

引导代理采取“分析先行”的代码审查行为：

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  appendSystemPrompt: `You are a code reviewer. Follow these rules:
- Prioritize reading code and analyzing behavior before proposing changes.
- Do not modify files unless the user explicitly asks for an implementation.
- Identify bugs, security issues, and style problems.
- Provide specific line numbers and suggested fixes in your response.`,
});

特定领域专家

使代理专注于特定技术或领域：

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  appendSystemPrompt: `You are a SQL and database specialist working with Snowflake.
- Write efficient SQL queries optimized for Snowflake's columnar storage.
- Use Snowflake-specific features like VARIANT columns and FLATTEN.
- Always include LIMIT clauses in exploratory queries.
- Validate SQL syntax before suggesting changes.`,
});

样式强制执行器

确保代理遵循特定的编码标准：

import { createCortexCodeSession } from "cortex-code-agent-sdk";

const session = await createCortexCodeSession({
  cwd: process.cwd(),
  appendSystemPrompt: `Enforce these coding standards in all changes:
- Use TypeScript strict mode conventions.
- Prefer const over let; never use var.
- All functions must have explicit return types.
- Use async/await instead of raw Promises.
- Run "npm run lint" after every file change.`,
});

最佳实践

何时追加与替换

追加到默认提示

替换默认提示

您想要添加域上下文或约束

您需要完全控制代理行为

您希望保留内置工具使用指南

您正在构建高度专业化的代理

您需要确保安全防御机制持续生效

默认说明与您的用例冲突