个人命令¶

状态： 个人命令、类型化捕获描述符、听写控制短语和文本转换已在 macOS 上实现；Windows 和 Linux 使用这些转换。本文档记录了已发布的契约。Hex 在嵌入式 QuickJS 中运行配置（quickjs.md）。

用户可以配置的内容¶

个人命令位于 ~/.config/hex/hex.config.ts（或 hex.config.js）中。配置定义了普通命令、捕获描述符、命名文本转换以及可选的听写控制短语。Rust 验证并匹配语法，同时保留唤醒、睡眠、取消和听写生命周期行为。会议生命周期命令是原生功能，且仅供开发者使用。

语音命令和听写控制短语需要持久化的 Commands 主动启用设置，该设置默认关闭。创建配置不会启用它。选定的模式转换可以在 Commands 关闭时运行；热键听写不需要语音命令。

import { defineHexConfig, openUrl } from "@hex/commands"

export default defineHexConfig({
  commands: {
    "open-training": {
      phrases: ["open training"],
      group: "Websites",
      description: "Open the training site",
      action: openUrl("https://example.com/training"),
    },
  },
})

命令键是稳定的 ID。命令可以是全局的，也可以匹配某个确切的应用程序或浏览器主机。浏览器主机上下文目前来自 Brave Browser。更具体的命令可以特化普通的全局命令；在同一特异性下可以共存的命令不能共享同一短语。

可用的操作是 openUrl、openApplication、openPath、press 和 typeText。处理函数返回一个操作、一个操作列表或什么都不返回，也可以通过其 hex 参数将操作排队；Hex 会验证所有操作，并在处理函数返回后按顺序运行它们。处理函数是纯 TypeScript 或 JavaScript，可以导入配置文件夹中的其他文件，但不能导入 npm 包、Effect 或 Node API。

命令可以使用尾随的 {name} 占位符来表示规范化文本，或者使用由 digit、letter、choice、union 和尾随 text 构建的 captures 模式。带模式的命令在每个短语别名中恰好绑定每个声明的捕获一次，并且需要 run 处理函数。Rust 仅在完整的命令转录上匹配这些命令，而不是部分更新。

openUrl 接受绝对 Web URL 和应用深层链接，例如 openUrl("slack://channel?team=T_EXAMPLE&id=C_EXAMPLE")。该 URL 会原样传递给 macOS，macOS 需要为其协议安装相应的处理程序。使用 openApplication("Slack") 按名称或路径启动应用，而不是导航深层链接。API 的拼写是 openUrl，不是 openURL。文件 URL 和内联脚本/数据 URL 仍然不受支持；对于文件系统路径，请使用 openPath。

听写转换¶

配置可以注册命名的字符串转换。在某个模式的 Transformations 部分中选择它们，以便在该模式的更正和可选的 OpenCode 重写之后按显示顺序运行它们。此管道适用于 Paste 和 Send，不适用于 Voice Action 或会议。如果转换阶段失败，Hex 会保留该阶段之前的文本，而不是部分转换后的输出。

import { defineHexConfig } from "@hex/commands"

export default defineHexConfig({
  transformations: {
    "trim-whitespace": {
      name: "Trim whitespace",
      description: "Remove leading and trailing whitespace",
      transform: (text) => text.trim(),
    },
  },
  commands: {},
})

不要复用内置转换 ID lowercase、spongebob-case 或 no-trailing-punctuation；这些 ID 会执行 Rust 的内置转换，而不是已注册的脚本函数。

每次听写都选择一个完整的模式。除非有更具体的应用或浏览器主机模式匹配，否则会应用必需的 Global 模式。模式拥有自己的更正、可选的 AI 重写和选定的自定义转换；上下文模式不会从 Global 继承隐藏的处理。

信任边界¶

配置在 Hex 进程内的 QuickJS 中运行，没有文件系统、网络、环境、进程或计时器 API，并且只能导入 @hex/commands 以及配置文件夹中的文件。它能做的事情仅限于它返回的操作，这些操作以用户的权限运行，因此在启用命令之前请审查代理所做的更改。每次调用有一秒的限制，引擎有 64 MiB 的限制。

无效配置永远不会替换最后一个有效的注册表。Rust 在激活之前验证模式、稳定 ID、受保护短语、上下文谓词和重叠项。当配置失败时，听写仍然可用。

听写控制短语¶

可选的 dictation 部分替换的是原生语音听写短语，而不是原生捕获生命周期：

import { defineHexConfig } from "@hex/commands"

export default defineHexConfig({
  dictation: {
    start: ["begin note"],
    stop: ["finish note"],
    send: ["send note"],
    cancel: ["discard note"],
  },
  commands: {},
})

start 在 Hex 监听时匹配话语前缀。stop、send 和 cancel 在活跃的语音听写期间匹配后缀。每个列表必须至少包含一个短语。省略该部分则使用原生协议。

工作区¶

在 Commands 窗格中选择 Create Config，在 Modes 的 Transformations 中选择 Set up，或运行：

hex commands init

~/.config/hex/
├── hex.config.ts   the user's; created only when no config exists
├── hex.d.ts        types for @hex/commands; Hex rewrites it when it changes
├── AGENTS.md       agent notes; Hex rewrites it when it changes
└── tsconfig.json   created only when missing, for editors and `tsc`

不会安装任何内容。Bun 时代的文件夹只要其配置避免使用 Effect 和 npm 包，就仍可继续工作；它们的 package.json、bun.lock、node_modules、.hex-sdk 和 .agents 均可删除。

当文件夹中的任何 .ts、.js、.mjs 或 .json 文件发生变化时（不包括 .d.ts、点文件夹、node_modules 或符号链接目标），Hex 会在大约三分之一秒后重新加载配置，激活有效更改，并在 Modes 的 Transformations 部分报告最后一次加载错误及其文件、行和列。hex commands check（macOS）会像 Hex 一样加载配置，并打印它注册了哪些内容或失败原因。类型检查是可选的：在文件夹中运行 npx -y -p typescript tsc。

运行时边界¶

hex.config.ts -> type erasure -> QuickJS on one worker thread -> registration
  -> native Rust resolver -> handler call -> actions -> native executor

脚本引擎绝不会在部分转录识别路径中运行。请求队列、每次调用的操作和状态文件都是受限的。加载失败会保留原生命令和最后有效的运行时快照。

剩余工作¶

• 当 Commands 窗格不够用时，为 CLI 添加列表查看、重载和日志检查功能。