用途
cortex-run 用于在用户显式输入 $cortex-run 或 /cortex-run 时,将请求直接交给 Cortex Code CLI 处理,跳过自动路由的关键词过滤逻辑。它适用于用户明确希望由 Cortex Code 处理其请求的场景,而不是依赖自动路由。
该技能仅限显式调用,不会从自动路由钩子或关键词匹配中加载。自动路由由单独的提示词过滤钩子与 cortex-router 技能负责。
前提条件
使用前,Cortex Code CLI 必须已安装并位于 PATH 中。可通过以下命令确认:
which cortex && cortex --version
若未找到 cortex,需加载 snowflake-cortex-code:cortex-setup 技能进行安装,未安装完成前不应继续。
工作流程
- 检查 Cortex CLI:该步骤为强制步骤,每次均需先执行。命令为:
which cortex 2>/dev/null && cortex --version
若未找到或命令失败,需告知用户 CLI 未安装,并加载 snowflake-cortex-code:cortex-setup 技能进行安装,安装完成且可正常工作前不得进入下一步。
-
提取用户提示词:用户在 $cortex-run 之后输入的内容即为要发送的提示词。若用户仅输入 $cortex-run 而无其他文本,则询问其希望在 Snowflake 中执行什么操作。
-
选择安全范围(Security Envelope),依据操作需求选择:
- RO:用于查询、读取、探索;阻止 Edit、Write 及破坏性 Bash。
- RW:用于数据修改、DDL;阻止破坏性 Bash(如 rm -rf、sudo)。
- RESEARCH:用于探索加网络访问;阻止 Edit、Write 及破坏性 Bash。
- DEPLOY:需要完全访问权限时使用;不阻止任何操作。
除请求明显为只读外,默认使用 RW。
- 通过 Cortex Code 执行,示例命令:
python "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
--prompt "USER_PROMPT_HERE" \
--envelope "RW"
只读查询示例:
python "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
--prompt "USER_PROMPT_HERE" \
--envelope "RO"
指定 Snowflake 连接示例:
python "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
--prompt "USER_PROMPT_HERE" \
--envelope "RW" \
--connection "connection_name"
- 返回结果:以可读表格展示 SQL 结果,显示生成的产物,报告成功或失败;若 Cortex 出错,展示错误并建议修复方式。
上下文补充
发送提示词前,可附加当前 Claude Code 会话中的相关上下文,格式示例:
# Context from Claude Code Session
[Last 2-3 relevant exchanges — Snowflake-specific details only]
# User Request
[The original prompt]
上下文应保持精简——除非恢复会话,Cortex 每次仅能看到当前提示词中发送的内容。
多轮对话:--resume-last 与全新会话
每次 Cortex 调用都会返回一个自动持久化的 session_id。后续轮次可恢复该会话,使 Cortex 看到先前的对话,实现真正的多轮交互,而非每次提示词的单次批处理。
当当前提示词是上一次 Cortex 轮次的延续时添加 --resume-last,例如 "keep going"、"apply the top suggestion"、"dig deeper"、"also show me ..."、"and for last quarter"、"fix that",或对 Cortex 刚给出答案的任何澄清。
当用户切换话题、询问不同的数据库/仓库,或开始明显的新任务时,省略 --resume-last(开始全新会话)。
若已有明确的 id,也可使用 --resume <session_id>。
续接上一轮 Cortex 的示例:
python "${CLAUDE_PLUGIN_ROOT}/scripts/router/execute_cortex.py" \
--prompt "also show me the column types" --envelope "RO" \
--resume-last
示例
用户:$cortex-run show me tables in the RAW schema
- Envelope:RO
- Prompt:"show me tables in the RAW schema"
用户:$cortex-run create a dynamic table that aggregates daily sales
- Envelope:RW
- Prompt:"create a dynamic table that aggregates daily sales"
用户:$cortex-run(无提示词)
- 询问:"What would you like Cortex Code to do?"
说明
- 本技能仅用于显式调用。自动路由由提示词过滤钩子与 cortex-router 技能单独处理。
- 对后续提示词使用 --resume-last,使 Cortex 保留对话上下文。新话题则省略该参数,改为在提示词中包含相关上下文。
- 安全范围强制执行使用 --permission-prompt-tool stdio——每次工具调用均在进程边界由 envelope_policy.decide() 进行门控。