cortex-code

Cortex Code 集成技能

安装

# Install via npm skills ecosystem (works with Claude Code, Cursor, Codex, and 40+ agents)
npx skills add snowflake-labs/subagent-cortex-code --copy

# Prerequisite: Cortex Code CLI must be installed and configured
# See: https://docs.snowflake.com/en/user-guide/cortex-code
which cortex  # verify installation

此技能可让你的编码 Agent 利用 Cortex Code 在 Snowflake 方面的专业能力，将与 Snowflake 相关的操作智能地路由至无头模式下的 Cortex Code CLI。

架构概览

路由原则：只有 Snowflake 操作 → Cortex Code。其他所有操作 → 你的编码 Agent。

主要组件：

• 在会话初始化时动态发现技能
• 基于 LLM 的语义路由（而非关键词匹配）
• 带有审批模式（prompt/auto/envelope_only）的安全封装层
• 通过上下文增强实现无状态的 Cortex 执行
• 混合内存管理
• 用于合规审计的日志记录

安全性

此技能在 Cortex 执行外部包含一个安全封装层，提供三种审批模式：

审批模式

1. prompt（默认）：高安全性

   • 向用户显示审批提示，其中包含预测的工具和置信度
   • 执行前必须获得用户批准
   • 无需审计日志
   • 适用于：交互式会话、不可信提示词、生产环境

2. auto：中等安全性

   • 所有操作均自动批准
   • 必须记录审计日志
   • 仍会强制执行信封限制
   • 适用于：自动化工作流、可信环境

3. envelope_only：中等安全性

   • 不预测工具（速度更快）
   • 自动批准并记录审计日志
   • 仅依赖信封阻止列表
   • 适用于：可信环境、低延迟需求

配置：在技能安装目录中的 config.yaml 里设置，或通过组织策略设置。

IMPORTANT — config.yaml 是可选的。 此技能仅提供作为模板的 config.yaml.example。如果不存在 config.yaml，Python 脚本会采用安全默认值（approval_mode: prompt、default_envelope: RO）。执行前请勿搜索、glob 或使用 ls 查找 config.yaml — ConfigManager 会在内部处理。仅当用户明确要求更改设置时，才读取/创建 config.yaml。

内置保护

• 提示词清理：自动移除 PII 并检测注入
• 凭据阻止：检测到凭据路径时阻止路由
• 安全缓存：位于 ~/.cache/cortex-skill/ 的 SHA256 验证缓存
• 审计日志：结构化 JSONL 日志（auto/envelope_only 模式下为必需）
• 组织策略：通过 ~/.snowflake/cortex/claude-skill-policy.yaml 进行企业级覆盖

重复查询的快速路径

会话状态会被缓存 — 不要对每个查询都重新运行初始化步骤。

如果以下步骤已在当前会话中运行过，请跳过：

• discover_cortex.py — 输出已缓存至 ~/.cache/cortex-skill/cortex-capabilities.json
• route_request.py — 对于明显的 Snowflake 查询（用户提到“Snowflake”“Cortex”“databases”“warehouse”等），可以跳过路由，直接执行
• cortex connections list — 活动连接在会话期间不会变化；请重复使用
• 任何对 config.yaml / 组织策略的检查 — 由 ConfigManager 处理（见上文说明）

后续 Snowflake 查询的最简流程（会话中的第一次查询之后）： 1.（如果 approval_mode: prompt）向用户征求批准 2. 使用增强后的提示词和信封调用 execute_cortex.py 3. 返回结果

就这些。三个步骤 — 无需重新发现、重新路由或检查配置。

会话初始化

首次加载此技能时：

步骤 1：发现 Cortex 能力

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/discover_cortex.py

此脚本会：

1. 运行 cortex skill list，列出所有可用的 Cortex 技能
2. 读取各技能的 SKILL.md frontmatter 和触发模式
3. 使用 CacheManager 将能力缓存到配置的缓存目录
4. 返回关于 Cortex 可处理内容的结构化数据

预期输出：将技能名称映射到其触发模式和能力的 JSON。

步骤 2：加载路由上下文

将发现的能力加载到内存中，为整个会话期间的路由决策提供依据。

工作流：处理用户请求

第 1 步：使用基于 LLM 的路由分析请求

采取任何操作之前，请先分析用户的请求：

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/route_request.py --prompt "USER_PROMPT_HERE"

此脚本会：

1. 从缓存加载 Cortex 功能
2. 使用 LLM 推理对请求进行分类
3. 返回包含置信度分数的路由决策

路由逻辑：

• 路由到 Cortex：如果请求涉及：

  • Snowflake 数据库、仓库、架构、表
  • 专门针对 Snowflake 的 SQL 查询
  • Cortex AI 功能（Cortex Search、Cortex Analyst、ML 函数）
  • Snowpark、动态表、流、任务
  • Snowflake 环境中的数据治理、数据质量或安全
  • 用户明确提到“Cortex”或“Snowflake”

• 路由到你的编码 Agent：如果请求涉及：

  • 本地文件操作（读取、写入、编辑本地文件）
  • 通用编程（非 Snowflake 专用的 Python、JavaScript 等）
  • 非 Snowflake 数据库（PostgreSQL、MySQL、MongoDB 等）
  • Web 开发、前端工作
  • 与 Snowflake 无关的基础设施/DevOps
  • Git 操作、GitHub、版本控制

第 2 步：根据路由决策执行

如果路由结果为 coding_agent（本地处理）：

使用 Agent 内置功能直接处理请求，不涉及 Cortex。

如果路由到 Cortex Code：

继续执行第 3 步。

第 3 步：选择安全信封并处理审批

执行 Cortex 之前，安全包装器会根据配置模式处理审批。

第 3a 步：检查审批模式

security_wrapper.py 会在内部从 config.yaml 读取 approval_mode —— 请勿自行检查配置文件。 如果 config.yaml 不存在，默认使用 prompt 模式。

• prompt 模式（默认）：需要用户审批
• auto 模式：自动批准并记录审计日志
• envelope_only 模式：自动批准，不预测工具

第 3b 步：处理审批（如果为 prompt 模式）

如果使用 prompt 模式：

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/security_wrapper.py \
  --prompt "ENRICHED_PROMPT" \
  --envelope "RW"

此操作将：

1. 使用 LLM 预测所需工具
2. 向用户显示审批提示：

   Cortex Code needs to execute the following tools:
   
     • snowflake_sql_execute
     • Read
     • Write
   
   Envelope: RW
   Confidence: 85%
   
   Approve execution? [yes/no]
   

3. 如果获批，继续执行第 3c 步
4. 如果被拒绝，则中止执行

第 3c 步：确定安全信封

根据操作确定适当的安全信封：

• RO（只读）：用于查询和读取操作——阻止 Edit、Write 和破坏性 Bash 操作
• RW（读写）：用于数据修改——允许大多数操作，阻止破坏性 Bash 操作
• RESEARCH：用于探索性工作——读取权限以及 Web 工具
• DEPLOY：用于部署操作——阻止破坏性 Bash 命令
• NONE：通过 --disallowed-tools 自定义阻止列表

第 4 步：为 Cortex 丰富上下文

构建包含以下内容的增强提示词：

Claude 对话上下文：

• 当前 Claude 会话中最近 2-3 条相关交流
• 已讨论的任何 Snowflake 专属细节

近期 Cortex 会话上下文：

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/read_cortex_sessions.py --limit 3

此操作会读取 ~/.local/share/cortex/sessions/ 中最近的 Cortex 会话文件，以了解 Cortex 最近处理的内容。

增强提示词格式：

# Context from Current Session
[Recent relevant conversation history]

# Recent Cortex Work
[Summary from recent Cortex sessions]

# User Request
[Original user prompt]

步骤 5：以无头模式执行 Cortex Code

PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)
$PYTHON scripts/execute_cortex.py \
  --prompt "ENRICHED_PROMPT" \
  --connection "connection_name" \
  --envelope "RW" \
  --disallowed-tools "tool1" "tool2"

此脚本会：

1. 调用 cortex -p "prompt" --output-format stream-json
2. 使用打印模式传递提示词，并使用流式 JSON 输出进行非 TTY 解析
3. 通过 --disallowed-tools 禁止列表应用基于信封的安全机制
4. 实时解析 NDJSON 事件流
5. 检测工具调用事件和执行结果

关键要点：此包装器有意不将 -p 与 --input-format stream-json 组合使用。Cortex 将 --input-format 保留用于 JSON 标准输入；标准输入关闭时，这种组合可能只会发出一个 init 事件，然后在处理提示词之前退出。

安全信封：

• RO（只读）：禁止 Edit、Write 和具有破坏性的 Bash 命令
• RW（读写）：禁止 rm -rf、sudo 等破坏性操作
• RESEARCH：允许读取和使用 Web 工具，禁止写入操作
• DEPLOY：允许部署操作，禁止具有破坏性的 Bash 命令
• NONE：通过 --disallowed-tools 参数自定义禁止列表

事件流处理：

• type: assistant → Cortex 的回复，显示给用户
• type: tool_use → Cortex 正在调用工具
• type: result → 最终结果

步骤 6：处理权限请求

使用安全包装器时：

• prompt 模式：用户在执行前批准（执行过程中不会出现提示）
• auto/envelope_only 模式：在流式 JSON 模式下，自动批准未被禁止的工具

安全包装器通过以下方式处理权限管理：

1. 预先批准（prompt 模式）：用户在执行前批准预测所需的工具
2. 审计日志记录（auto/envelope_only）：将所有操作记录到技能安装目录中的 audit.log
3. 信封强制执行：仍通过 --disallowed-tools 强制执行工具禁止列表

步骤 7：向用户返回结果

针对当前会话整理 Cortex 的输出：

• 以易读的格式显示 SQL 查询结果
• 显示生成的任何产物
• 报告成功/失败状态
• 提供 Cortex 分析中的相关摘录

示例

示例 1：Snowflake 查询

用户说：“显示 Snowflake 中收入最高的 10 位客户”

路由：→ Cortex Code（Snowflake SQL 查询）

安全信封：RW（允许执行 SQL）

Cortex 操作：

1. 使用 snowflake_sql_execute 运行：SELECT customer_name, SUM(revenue) as total FROM sales GROUP BY customer_name ORDER BY total DESC LIMIT 10
2. 返回格式化结果

结果：向用户显示包含收入最高的 10 位客户的表格。

示例 2：本地文件操作

用户说：“读取此目录中的 config.json 文件”

路由：→ 你的编码 Agent（本地文件操作）

Claude 操作：直接使用 Read 工具，不涉及 Cortex。

结果：显示文件内容。

示例 3：数据质量检查

用户说：“检查 SALES_DATA 表的数据质量”

路由：→ Cortex Code（Snowflake 数据质量——与 Cortex 的 data-quality 技能匹配）

安全信封：RW（允许执行 SQL 进行分析）

Cortex 操作：

1. 使用其 data-quality 技能运行数据质量检查
2. 分析架构、空值比例、重复项等
3. 生成质量报告

结果：提供全面的数据质量报告和建议。

重要说明

安全包装器

此技能使用的安全包装器提供：

• 批准模式：prompt（默认）、auto、envelope_only
• 提示词净化：自动移除 PII 并检测注入
• 凭据拦截：检测到凭据路径时阻止路由
• 审计日志记录：auto/envelope_only 模式下强制启用
• 工具预测：由 LLM 预测所需工具，以供批准提示使用

配置：技能安装目录中的 config.yaml，或通过组织策略配置

无头执行与自动批准

使用 auto 或 envelope_only 模式时：

• 所有工具调用都会自动批准，不会出现交互式提示
• 适用于内置工具（Read、Write、Edit、Bash、Grep、Glob）和非内置工具（snowflake_sql_execute、data_diff、MCP 工具）
• 使用打印模式传递提示词，并使用 stream JSON 模式解析非 TTY 输出
• 安全性通过 --disallowed-tools 阻止列表控制，而非交互式批准；仅在受信任的环境中使用这些模式

无状态执行

每次 Cortex 调用都是无状态的。必须通过补充信息的提示词显式提供上下文。

记忆边界

• 你的编码 Agent 维护：完整的对话历史、用户偏好、项目上下文
• Cortex Code 接收：仅当前操作所需的任务特定上下文
• Cortex 会话的读取用途：仅用于补充历史上下文

安全封套策略

根据操作风险选择封套：

1. 从 RO 或 RW 开始：大多数操作都适用
2. 使用 RESEARCH：需要 Web 访问来开展探索性工作时
3. 使用 DEPLOY：仅用于需要更广泛非破坏性工具访问权限的部署类操作
4. 使用 NONE 并自定义阻止列表：需要精细控制时

性能注意事项

• Cortex 技能发现每个会话仅运行一次（会缓存）
• 每次 Cortex 执行会增加约 2-5 秒延迟
• 合理使用路由，尽量减少不必要的 Cortex 调用

故障排除

错误："Cortex CLI not found"

原因：未安装 Cortex Code，或未将其添加到 PATH

解决方案：

which cortex
# If not found, check installation: ~/.snowflake/cortex/

错误：未显示批准提示（或意外显示）

原因：批准模式配置错误，或被组织策略覆盖

解决方案：

# Check approval mode (path varies by agent: ~/.claude/, ~/.cursor/, ~/.codex/, etc.)
cat "$(dirname $(which cortex))/../skills/cortex-code/config.yaml" | grep approval_mode 2>/dev/null \
  || cat ~/skills/cortex-code/config.yaml | grep approval_mode

# Check organization policy (overrides user config)
cat ~/.snowflake/cortex/claude-skill-policy.yaml 2>/dev/null

# Expected:
#   prompt = shows approval prompts (default)
#   auto = auto-approves all operations
#   envelope_only = auto-approves, no tool prediction

错误："Prompt contains credential file path"

原因：提示词提及了与凭据允许列表匹配的路径（例如，~/.ssh/、.env）

解决方案：

1. 从提示词中移除凭据相关引用
2. 如果是误报，也可以在 config.yaml 中自定义允许列表

错误：提示词中的个人身份信息已移除

症状：电子邮件地址、电话号码被替换为占位符

原因：默认启用了自动清理

解决方案：如有需要，可禁用（不建议）：

security:
  sanitize_conversation_history: false

错误：在自动模式下仍显示“Permission denied”

原因：该工具位于当前封套的 --disallowed-tools 阻止列表中

解决方案：

1. 检查正在使用哪个封套（RO/RW/RESEARCH/DEPLOY）
2. 如果操作安全，请切换到限制较少的封套
3. 避免在 auto/envelope_only 模式下使用 NONE；如有需要，请使用命名封套并指定自定义阻止列表

错误：未创建审计日志

症状：在 auto/envelope_only 模式下没有 audit.log

解决方案：

# Create the skill's install directory if missing and set permissions
# Path is agent-specific: ~/.claude/skills/cortex-code/, ~/.cursor/skills/cortex-code/, etc.
chmod 700 "$(cd "$(dirname "$0")/.." && pwd)"

# Verify audit_log_path in config.yaml within the skill directory
grep audit_log_path config.yaml

错误：工具仍需批准

原因：批准模式、封套阻止列表或 stream JSON 调用配置错误

解决方案：确保包装器调用 cortex -p "..." --output-format stream-json，且不带 --input-format；同时确认配置的封套未阻止所需工具。

问题：路由将 Snowflake 查询发送给你的编码 Agent

原因：路由逻辑未检测到 Snowflake 关键词

解决方案：

1. 检查用户是否明确提到了“Snowflake”
2. 检查 scripts/route_request.py 中的路由脚本逻辑
3. 在路由上下文中添加更多触发模式

问题：Cortex 返回“Connection refused”

原因：Cortex 中未配置 Snowflake 连接

解决方案：

cortex connections list
# Verify connection is active
# Check ~/.snowflake/cortex/settings.json for cortexAgentConnectionName

问题：上下文补充内容过大

原因：包含了过多对话历史

解决方案：仅保留最近 2-3 轮相关对话，并总结更早的上下文。

高级：自定义路由规则

要自定义默认逻辑之外的路由规则，请编辑 scripts/route_request.py：

# Add custom patterns
FORCE_CORTEX_PATTERNS = [
    "snowflake",
    "cortex",
    "warehouse",
    "snowpark"
]

FORCE_CLAUDE_PATTERNS = [
    "local file",
    "git commit",
    "python script" # unless Snowpark
]

参考资料

请参阅 references/ 目录，其中包含：

• cortex-cli-reference.md - 完整的 Cortex CLI 文档
• routing-examples.md - 更多路由决策示例
• session-file-format.md - Cortex 会话文件结构
• troubleshooting-guide.md - 扩展版故障排查指南