oh-my-pi Magic Keywords 指南：用 `ultrathink`、`orchestrate`、`workflowz` 一句话切换智能体行为

oh-my-pi Magic Keywords 指南：用ultrathink、orchestrate、workflowz一句话切换智能体行为

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi

本篇技术指南讲解 oh-my-pi（⌥ Coding agent with the IDE wired in）中的Magic Keywords（魔法关键词）机制：如何在用户提示词中以纯文本关键词为当前回合注入隐藏的、归属用户的指令通知（notice），从而在不改变消息正文的前提下定向调整模型行为。读完本文你将掌握三个内置关键词（ultrathink、orchestrate、workflowz）的精确匹配规则、TUI 渐变高亮原理、以及如何通过/settings面板或omp config命令按需开关，并深入理解底层源码实现。

什么是 Magic Keywords

Magic Keywords 是出现在用户提示词（prompt）正文中的独立散文单词（standalone prose words），当它们被识别后，系统会为该回合追加一条隐藏的、归属记为用户的指令通知。这相当于一种"写在自然语言里的开关"：你不需要记住斜杠命令或图形界面选项，只要在消息里自然写下关键词，当前回合的模型行为就会被定向调整，而用户消息本身保持原样可见。

该功能在 oh-my-pi 中默认启用（notice injection is enabled by default）。TUI 在编辑输入时会用动画渐变高亮被识别出的关键词，发送后的消息气泡中则以静态渐变呈现；这一高亮属于纯视觉辅助（visual affordance），即使在设置中关闭了通知注入，高亮也仍然保留。

需要特别说明的是：关键词只影响包含它的那一回合（the instruction applies only to the turn containing the keyword），不会改变后续回合的行为，也不会污染用户消息的显示内容——隐藏通知是非显示的（display: false）自定义消息，且归属（attribution）记为用户本人，见下文源码分析。

三个内置关键词及其效果

下表是 oh-my-pi 内置的全部 Magic Keywords 及其效果说明：

使用方式

把关键词用在提示词散文中的任意位置即可：

ultrathink about the failure modes before changing this API orchestrate the migration described in docs/plan.md workflowz an adversarial review of the authentication changes

关键词不要求出现在句首或特定位置，只要是"独立的散文单词"就会被识别。

匹配规则：刻意收紧，避免误触发

Magic Keywords 的匹配规则是刻意设计的，目的只有一个：防止源码和路径中恰好出现的字符串意外改变智能体行为。核心规则如下：

• 必须使用精确的小写拼写。Ultrathink、Orchestrate、Workflowz这类大小写变体都不会触发。
• 关键词必须是独立的散文单词。句末标点和引号可以与关键词紧贴（如orchestrate,匹配），但字母、数字、下划线、斜杠、反斜杠、连字符、文件扩展名、符号引用和调用语法均不允许紧贴（例如orchestrated、orchestrate.ts、foo::orchestrate、orchestrate()都不匹配）。
• 围栏代码块（反引号或波浪线）、行内代码 span、HTML/XML 注释/标签/元素及其内容都会被忽略，其中的关键词不会触发任何效果。
• 同一提示词中多个已启用的关键词可以各自追加自己的通知；可见的单词仍保留在用户消息中，隐藏通知是非显示的自定义消息，归属记为用户。
• 指令仅对包含关键词的那一回合生效。

匹配规则的源码实现

这些规则并非文档承诺，而是有明确的代码落地：

• 词边界正则：magic-keyword-boundary.ts 中的magicKeywordRegex()用左右边界断言构建匹配器——左侧禁止字母/数字/下划线/点/斜杠/反斜杠/连字符及::符号引用（(?<![\p{L}\p{N}_./\\-])(?<!::)），右侧禁止紧贴字母/数字/下划线/斜杠/反斜杠/点扩展名及紧随的左括号（(?![\p{L}\p{N}_/\\-])(?!\.[\p{L}\p{N}_-])(?!\()），并强制u标志。这正是"orchestrated、orchestrate.ts、foo::orchestrate、orchestrate()均不匹配"的出处。
• Markdown 感知的散文检测：markdown-prose.ts 的maskNonProse()返回一个长度保持不变（索引 1:1 映射）的文本副本，把所有围栏代码块、行内代码 span、HTML/XML 标签及包裹内容替换为空格；keywordInProse()先在原文上做一次快速探测，再对掩码后的文本做词边界匹配，保证检测与高亮只落在用户真正写给模型的散文上，同时索引仍指向原文以便着色。
• 检测短路优化：magic-keywords.ts 的hasMagicKeyword()先用三次String#indexOf做子串探测，命中后再走完整 prose 检查，让"缓冲区没有关键词"这一常见路径只有三次indexOf的开销，供编辑器门控 shimmer 定时器使用。

通知注入：隐藏的、归属用户的自定义消息

识别到关键词后，oh-my-pi 不会改写用户消息，而是注入一条隐藏的自定义消息（CustomMessage）。以 agent-session.ts 中的#createMagicKeywordNotices()为例：

• 开关判定由#magicKeywordEnabled()完成：magicKeywords.enabled全局开关与magicKeywords.<keyword>单项开关同时为真才生效。
• ultrathink命中时追加customType: "ultrathink-notice"的消息，内容来自 ultrathink-notice.md，正文是<system-notice>Multi-step reasoning: think carefully through the problem before responding.</system-notice>。
• orchestrate命中时，只有task工具处于启用状态才会注入（否则契约要求的能力不可用，通知会被跳过）；通知内容通过 orchestrate-notice.md 按当前启用的工具列表模板渲染，包含 role/rules/workflow/anti-patterns 四段完整契约。
• workflowz命中时，必须同时启用task与eval工具才注入；通知由 workflow-notice.md 渲染，并按task.batch、scout 是否可用、eval.tools.enabled动态调整内容。
• 所有通知消息均为role: "custom"、display: false（不显示）、attribution: "user"（归属用户）、带统一时间戳。

通知的排队顺序与"仅用户回合"约束

agent-session.ts 表明：prompt()中生成关键词通知时传入的是展开后的提示词，且仅对用户发起的提示词生效——options?.synthetic（合成/智能体发起的回合）一律跳过。流式场景下，通知会先于用户消息排队注入（#queueCustomMessage在前、#queueUserMessage在后），保证模型在读到用户消息之前先看到约束指令。测试 agent-session-magic-keywords.test.ts 明确断言了 "notice 在 user 消息之前" 的排队顺序。

queued-messages.ts 中定义了MAGIC_KEYWORD_NOTICE_TYPES = { "ultrathink-notice": true, "orchestrate-notice": true, "workflow-notice": true }，配合isDisplayableQueuedMessage()、isUserQueuedMessage()等辅助函数，隐藏通知不会渲染进队列 UI，也不会被误当作普通用户消息恢复进编辑器。

ultrathink 与自动思考（Automatic Thinking）的联动

ultrathink的关键词效果不止于追加通知：当自动思考开启时，它还会旁路难度分类器，直接把本回合推理力度设为当前模型支持的最高档。相关实现位于 model-controls.ts：

if (this.#host.magicKeywordEnabled("ultrathink") && containsUltrathink(promptText)) { // 用户显式要求最大思考：跳过分类器（及 providers.autoThinkingMaxEffort 上限）， // 直接跳到该模型支持的最高档 resolved = clampAutoThinkingEffort(model, Effort.Max); } else { // 否则走 classifyDifficulty 难度分类器 ... }

对应地，classifier.ts 的autoEffortCeiling()说明了设计意图：auto档默认（providers.autoThinkingMaxEffort为xhigh）比最高档低一档，只有显式的ultrathink才能达到Effort.Max——即 "the default keepsautoone tier below the top, so only an explicitultrathinkreachesEffort.Max"。

与之配套的设置项定义在 settings-schema.ts：providers.autoThinkingMaxEffort取值xhigh（默认，分类器最高解析到 xhigh）或max（分类器在模型支持时可能解析到 max）。而magicKeywords.ultrathink关闭后，即使提示词中包含ultrathink，也会退回走分类器——测试 agent-session-magic-keywords.test.ts 验证了这一点。

TUI 渐变高亮：动画与静态两态

Magic Keywords 的视觉反馈由三个各自独立的高亮器协作完成（magic-keywords.ts）：

export function highlightMagicKeywords(text: string, resetTo?: string, phase?: number): string { return highlightWorkflow( highlightOrchestrate(highlightUltrathink(text, resetTo, phase), resetTo, phase), resetTo, phase, ); }

三个高亮器链式调用、与顺序无关——较早的 pass 只注入零宽 SGR 转义序列（不产生反引号或尖括号），不会干扰后续 pass 的 Markdown 掩码。各关键词的渐变配色刻意区分：

• ultrathink：ultrathink.ts 采用红→紫全光谱彩虹渐变（hue 0..330，14 个色标，避免绕回红色），对应 TUI 提示语 "watch it glow rainbow"。
• orchestrate：orchestrate.ts 采用青→紫冷色调渐变（hue 150..280）。
• workflowz：workflow.ts 采用琥珀→绿暖色调渐变（hue 30..150）。

phase参数取Date.now()推导出的循环值：编辑器在输入框聚焦时用它驱动 Claude-Code 风格的动态 shimmer，发送后的消息气泡则省略 phase 以呈现静态渐变。

高亮的两个挂载点：

• 编辑器内：custom-editor.ts 的decorateText()先调用hasMagicKeyword()门控 shimmer 定时器（#shimmerEnabled()由magicKeywordsEnabled回调决定，见 interactive-mode.ts），再对文本 span 调用highlightMagicKeywords(span, undefined, phase)完成着色。
• 消息气泡内：user-message.ts 同样调用highlightMagicKeywords(value, keywordReset)，其中keywordReset是气泡自身前景色的 SGR 序列，保证渐变不会渗染到整行其余文字。

配置：全局开关与单项开关

通过 /settings 面板

打开会话内的/settings，进入Interaction → Magic Keywords分组即可看到四个布尔开关（与 settings-schema.ts 的定义一一对应）：

• magicKeywords.enabled：全局开关，门控所有隐藏通知，默认true。
• magicKeywords.ultrathink：门控 ultrathink 通知及其最大自动思考覆盖，默认true。
• magicKeywords.orchestrate：门控 orchestrate 通知，默认true。
• magicKeywords.workflow：门控 workflowz 通知，默认true。

注意：这四个开关目前不会禁用编辑器/消息气泡中的渐变高亮（"These settings do not currently disable the editor/message gradient"）。

通过命令行 omp config

也可以在 shell 中直接配置：

# 关闭全部 Magic Keywords omp config set magicKeywords.enabled false # 只关闭某一个关键词，其余保持启用 omp config set magicKeywords.ultrathink false omp config set magicKeywords.orchestrate false omp config set magicKeywords.workflow false # 查看所有设置及其当前生效值 omp config list

omp config set <key> <value>会按目标键的 schema 类型解析值字符串并写入全局主 YAML 配置文件；omp config list按 tab 分组打印每个设置项及其当前值（凭据字段在人类可读输出中掩码为********）。关于配置的作用域、优先级与项目级覆盖，参见 Settings：配置按built-in defaults <- global config <- project config <- CLI overlays <- runtime overrides的优先级合并，项目级配置位于<cwd>/.omp/config.yml（外加<cwd>/.omp/settings.json兼容旧格式）；omp config set的持久化写入只会落在全局文件，如需项目级覆盖请直接编辑项目配置文件。

工具可用性与通知注入的关系

从#createMagicKeywordNotices()可以总结出一条容易被忽略的规则：通知是否注入还取决于工具是否启用：

• orchestrate通知只有在task工具启用时才注入（编排契约完全围绕task子代理分发展开）；
• workflowz通知只有在task与eval同时启用时才注入；
• 对应测试 agent-session-magic-keywords.test.ts 分别用空工具列表和仅含mockTaskTool的场景验证了 "task 未启用时跳过 orchestrate"、"task 或 eval 未启用时跳过 workflowz" 的行为。

实战建议与边界

• ultrathink用于关键变更前的故障模式分析：例如改 API、重构不安全代码之前，希望模型先做多步推理；在自动思考开启时它还会强制最高推理档，适合高风险回合。
• orchestrate用于跨文件、多阶段的大任务：迁移、批量修改等需要"先界定范围 → 并行派发子代理 → 逐阶段验证"的场景；它明确要求子代理不自证、不自检，验证与格式化由编排者统一完成。
• workflowz用于需要持久化 eval 内核的确定性工作流：广泛调研、评审、迁移、对抗性覆盖；默认以workpool()承载 2 个以上独立工作项，仅在依赖耦合或需要 schema 返回时使用单个agent()handle。
• 注意大小写与粘连：关键词必须小写且独立成词；源码路径、符号引用、调用语法中出现的同名片段不会被识别，这是刻意设计，避免误触发。
• 隐藏通知不改变可见消息：发送后你的消息正文保持原样，只是回合上下文里多了一条归属用户的隐藏约束；多个关键词可同时生效、各自注入通知。

小结

Magic Keywords 是 oh-my-pi 在"自然语言提示词"与"确定性行为控制"之间架起的一座桥梁：三个小写关键词ultrathink、orchestrate、workflowz分别覆盖"深度推理"、"多智能体编排"与"eval 确定性工作流"三类高频诉求，配合刻意收紧的散文匹配规则（magic-keyword-boundary.ts、markdown-prose.ts）、隐藏的用户归属通知注入（agent-session.ts）以及 TUI 双态渐变高亮（magic-keywords.ts），把"一句话切换行为"做得既直观又可靠。无论是想深入理解其实现，还是要在日常会话中熟练运用，本文给出的源码路径与测试用例（agent-session-magic-keywords.test.ts）都可以作为进一步探索的起点。

【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi