关于自定义指令

[ilovesusu]

@lyricat 在你的计划中，这个自定义指令是干啥的，有相对具体的定义吗？

我最近打算用语音控制一些软件的打开，或者是执行预定义的shell。

下面是我的一些想法，然后个GPT聊完后的结果！我直接完整的贴上来吧！我感觉还是很实用的！

---

🚀语音输入法 + 自定义指令系统（Linux）

🎯 背景

当前语音输入法主要能力集中在：

• 语音转文字（Speech-to-Text）

但在 Linux 开发环境中，用户更需要的是：

语音 + 自动化 + 系统操作 + AI 工作流的一体化能力

因此希望在保留基础语音输入能力的前提下，引入“语音指令系统（Voice Command System）”。

---

✨ 核心目标

在不破坏现有语音输入体验的基础上，新增一层：

语音 → 指令解析 → 执行动作（或输出文本）

两种模式并存：

• 📝 纯输入模式（默认）：语音 → 文字输入
• ⚙️ 指令模式：语音 → 自动执行动作

---

🧠 功能设计建议

1️⃣ 保留基础能力（必须）

用户说：今天开会在下午三点
输出：今天开会在下午三点

✔ 不做任何解析
✔ 不影响输入延迟
✔ 保持输入法本质

---

2️⃣ 自定义语音指令（核心能力）

示例 1：Shell 命令

语音：重启 nginx

执行：

sudo systemctl restart nginx

---

示例 2：开发任务

语音：启动项目

执行：

pnpm install
pnpm dev

---

示例 3：Git 操作

语音：提交代码

执行：

git add .
git commit -m "auto commit"
git push

（可扩展 AI 自动生成 commit message）

---

示例 4：AI 操作

语音：解释一下

行为：

• 获取当前选中文本
• 调用 LLM
• 返回解释结果（弹窗 / 替换 / 复制）

---

示例 5：窗口控制

语音：打开 vscode

执行：

code

---

语音：切换窗口

模拟快捷键：

Alt + Tab

---

示例 6：浏览器

语音：打开知乎

执行：

xdg-open https://zhihu.com

---

示例 7：系统操作

语音：锁屏

执行：

loginctl lock-session

---

3️⃣ 工作流（Macro / Pipeline）

支持多步骤语音指令：

语音：开始工作

执行：

• 打开 VSCode
• 打开 Terminal
• 启动浏览器
• 打开 Notion
• 启动项目

---

语音：下班

执行：

• git push
• 关闭应用
• 同步文件
• 锁屏 / 关机

---

4️⃣ YAML/DSL 自定义指令系统（强烈建议）

允许用户定义语音映射：

commands:
  - trigger: "启动博客"
    steps:
      - exec: code ~/blog
      - exec: kitty
      - exec: pnpm dev
      - speak: "博客已启动"

  - trigger: "查公网IP"
    steps:
      - exec: curl ifconfig.me
      - copy_output: true

---

5️⃣ AI 集成能力（可选但强烈建议）

支持：

• clipboard → AI → clipboard
• selection → AI → replace
• prompt optimization
• code explanation
• translation

示例：

语音：翻译一下

流程：

• 获取剪贴板
• AI 翻译
• 自动回填

---

6️⃣ 安全机制（必须）

危险命令必须确认：

rm -rf /
shutdown now
format disk

建议：

• 二次确认
• 或 whitelist 机制
• 或 sandbox mode

---

🧩 架构建议（实现思路）

建议系统拆分为：

Speech-to-Text Layer
        ↓
Intent Parser（规则 + LLM）
        ↓
Command Router
        ↓
Executor Plugins

插件类型：

• shell plugin
• window manager plugin
• browser plugin
• ai plugin
• clipboard plugin
• system plugin

---

💡 Demo 场景合集

🧑‍💻 开发者模式

• “启动项目”
• “提交代码”
• “查看日志”
• “释放显存”
• “重启服务”

---

⚡ 生产力模式

• “开始工作”
• “生成日报”
• “总结今天任务”
• “翻译选中文本”

---

🧠 AI 增强模式

• “解释这段代码”
• “优化这个 prompt”
• “生成 commit message”

---

🪟 系统控制

• “打开 vscode”
• “锁屏”
• “切换窗口”
• “最大化窗口”

---

🚀 总结

该功能本质是：

从「语音输入法」升级为「语音驱动的 Linux 自动化系统」

它将语音输入从：

❌ 输入工具

升级为：

✅ 操作系统级控制接口

---

如果你愿意，我觉得你可以拆下任务，然后一起开发一下！如果你觉得不必要很臃肿，那我就fork 自己弄弄看！

[mistermorph-reviewer]

我建议把这个需求拆开看：它里面有一部分很适合 Coe 当前方向，另一部分已经超出“语音输入工具”的主边界。

当前项目的主链路是：

录音 -> ASR -> LLM 清理/改写 -> 通过 fcitx 或桌面剪贴板/粘贴把文本送回当前应用

README 里也把 custom instructions、custom scenes and scene switching 列为待做项。现有代码已经有内置 general / terminal 场景、场景切换命令、按场景选择 LLM prompt、个人词典、选中文本语音编辑。这说明“让用户定制转写/校正/编辑行为”是合适的；但“语音直接执行任意 shell、窗口控制、系统操作、宏工作流”会把 Coe 从输入法工具扩成系统自动化执行器，风险和维护面都会明显变大。

建议范围

建议把 issue 拆成两个层级：

1. 适合进入近期主线：自定义指令 / 自定义场景

   • 用户可配置额外的 LLM 指令，用来影响听写清理、终端场景、选中文本编辑。
   • 用户可定义 scene：id、display_name、aliases、description、prompt 覆盖。
   • 继续保持默认行为是纯输入：没有命中显式控制命令时，只输出文本，不执行动作。

2. 不建议直接进入近期主线：任意语音命令执行系统动作

   • exec: sudo systemctl restart nginx
   • git add . && git commit && git push
   • shutdown / lock-session
   • 多步骤 macro / plugin system

这些可以后续做成明确标注的实验功能，但不应和 custom instructions 混在同一个 MVP 里。

MVP 拆分

Phase 1：自定义 prompt instructions

先只做配置层能力，不新增执行器。

示例形态：

instructions:
  general:
    correction_prompt_file: ./prompts/general.tmpl
    edit_prompt_file: ./prompts/edit-general.tmpl
  terminal:
    correction_prompt_file: ./prompts/terminal.tmpl

或者更贴近现有结构，扩展到 scene 上：

scenes:
  - id: terminal
    display_name: Terminal
    aliases: ["终端", "shell", "命令行"]
    description: "Linux commands, shell fragments, paths, flags, package names."
    correction_prompt_file: ./prompts/terminal.tmpl
    edit_prompt_file: ./prompts/terminal-edit.tmpl

验收标准：

• 不配置时，现有 general / terminal 行为不变。
• 配置后，ASR 后的 LLM correction 能按当前 scene 使用用户 prompt。
• 选中文本编辑也能按 scene 使用对应 prompt。
• prompt 文件相对路径仍按 config.yaml 所在目录解析，保持现有配置习惯。

Phase 2：自定义 scenes

把当前硬编码 scene catalog 变成“内置 scene + 用户 scene”的组合。

边界建议：

• general 必须存在，不能删除。
• terminal 可以保留为内置默认 scene。
• 用户 scene 的 id 必须稳定、唯一，只允许简单标识符。
• aliases 只用于语音切换 scene，不用于匹配当前应用。
• 自动按应用切换 scene 应使用独立规则，不要把 app matcher 塞进 scene 定义，避免把“语音别名”和“焦点应用匹配”混成一件事。

Phase 3：有限控制命令

如果要继续做“语音控制”，建议先只支持 Coe 内部动作：

• 切换 scene
• 查询当前 scene
• 开关 auto paste
• 重启 Coe

这些动作属于 Coe 自己的状态管理，风险比 shell 小很多，也和现有 D-Bus 接口更接近。

安全模型

如果未来要做 shell / macro，必须单独设计，不能只靠“危险命令二次确认”。

最低要求：

• 默认关闭，用户显式启用。
• 不支持自由文本转 shell。只能执行配置文件里已经声明的命令。
• 语音只匹配 trigger，不能把 LLM 生成的字符串直接拼进 shell。
• exec 默认不走 shell，优先用 argv 结构，避免 shell 注入。
• 禁止默认执行 sudo、rm、shutdown、磁盘格式化、包管理器删除、批量 git push 等高风险动作。
• 高风险动作即使配置存在，也需要确认；确认不能只依赖同一次 ASR 文本。
• 每次执行前记录 action id、trigger、命令摘要和结果，但不要把 API key、环境变量、完整本机路径写入普通日志。
• 配置文件权限要检查，至少提醒 group/world writable 的命令配置不安全。

更合理的配置形态是：

commands:
  enabled: false
  require_confirmation: true
  items:
    - id: open-vscode
      trigger: "打开 vscode"
      action:
        type: exec
        argv: ["code"]

不建议的形态：

commands:
  - trigger: "启动项目"
    exec: "cd ~/repo && pnpm install && pnpm dev"

后者把目录、shell 解析、环境变量、命令注入、失败处理都混在一起，后续很难收住。

与现有 custom instructions / scenes 的关系

这个 issue 里的“自定义指令”建议不要命名成一个同时包含 prompt、scene、shell、AI workflow 的大概念。可以拆成：

• instructions：影响 LLM 如何处理文本。
• scenes：定义当前语境，并选择对应 instructions。
• commands：显式控制动作，后续单独做。

现有实现里已经有：

• llm.prompt / llm.prompt_file：全局 correction prompt 覆盖。
• general / terminal 内置 scene：按场景切换 correction/edit prompt。
• scene switch command：通过前缀门控识别，命中后不再作为普通听写输出。
• selected text edit：有选区时，语音内容作为编辑指令，而不是直接上屏文本。

所以近期最自然的增量是“把这些硬编码能力配置化”，而不是马上引入通用 command executor。

风险

主要风险有五类：

1. 误触发风险：普通听写如果被误判成命令，可能执行错误动作。解决办法是只允许明确前缀或专门 command mode，不做全局自由意图识别。
2. 安全风险：语音、ASR、LLM 都不是可信输入，不能直接驱动 shell。
3. 产品边界风险：系统自动化会显著扩大项目范围，和当前“低 UI、Linux 语音输入”的目标不完全一致。
4. 平台差异风险：Wayland 下窗口控制、全局快捷键、输入注入都受限制，GNOME/KDE/Hyprland 行为不同。
5. 配置复杂度风险：如果一开始就做 plugin / macro / AI workflow，配置会很快变成一套新的自动化 DSL，和 Coe 当前朴素 YAML 风格不一致。

结论

建议接受这个 issue 的方向，但把近期目标限定为：

支持用户自定义 Coe 的文本处理指令和场景；保留纯输入作为默认行为；只把少量 Coe 内部控制命令放进主线。

shell、窗口控制、浏览器控制、系统操作、macro workflow 建议另开 issue，按实验功能处理，并先写安全设计。这个功能有价值，但不应作为 custom instructions 的第一版一起做。

[lyricat]

@ilovesusu 欢迎呀。这确实是我本来想要做的方向。

[ilovesusu]

我拉取了最新的代码，看了历史提交和 docs/feat/xxx 。我看到划词翻译在弄了，怎么进行整体的开发，我想想看怎么着手吧！

不过有一个疑问，你是赞成 mistermorph-reviewer 的看法 还是我直接弄一个草案pr你看看？或者你空了把我上面说的功能的边界收一下？mistermorph-reviewer 说的有一部分我是赞同的，我怕改了太多pr被拒！最好是你直接收紧一下边界！我在你的最大允许限度上进行功能的开发！

mistermorph-reviewer 提出不做执行命令，但我觉得可以设计成， 显式的展示命令内容，空格直接运行，esc就停止，之类的！

还有就是你觉不觉得现在yaml配置比较多了，需要一个 GUI 直接填写一些东西就可以导出配置yaml，或者是一个Go的 TUI 程序呢？

[lyricat]

划词翻译其实已经可用了。

---

关于你说的建议：

我觉得可以在配置里加上指令配置，用户可以自定义指令，以及每个指令要执行的内容。

简单的做法大概是这样：

commands:
  enabled: false
  items:
    - trigger: "打开某某程序"
      action:
        type: exec
        cmd: ["app.name", "arg1", "arg2"]

然后对用户的语音识别结果进行前缀匹配，如果匹配成功就执行对应的命令。

---

GUI 肯定比 TUI 好

[mistermorph-reviewer]

谢谢，这个方向有价值，但我倾向于先把范围收窄。

Coe 现在的核心还是 Linux 桌面语音输入：录音、ASR、可选 LLM 整理，然后把文本提交回当前应用。README 里列的 custom instructions 也更接近“用户能控制文本处理方式”，而不是一上来把 Coe 做成完整的 Linux 语音自动化平台。

所以我的判断是：

• 自定义指令 / 自定义场景适合纳入 Coe。
• 语音触发 shell / 窗口 / 浏览器 / 系统操作可以考虑，但必须作为受限能力分阶段做。
• 插件系统、复杂 workflow、LLM 自由解析系统动作、跨桌面窗口控制，不适合第一版。

第一版要守住一个原则：默认仍然是纯输入，用户不显式配置、不显式触发时，任何语音都只按文本输入处理。

最小可行设计

1. 默认纯输入不受影响

没有配置命令时，流程保持不变：

语音 -> ASR -> LLM 整理 -> 上屏

普通句子，比如：

今天下午三点开会

必须仍然直接输入为文本，不进入任何指令解析。

这点很重要。语音识别会出错，LLM 也会误判。如果默认尝试理解“意图”，输入法会变得不可预测。

2. 自定义指令先从“文本处理”做起

更适合 Coe 第一阶段的是 scene 级 prompt / instruction。例如：

instructions:
  scenes:
    general:
      correction_prompt_file: "./prompts/general.tmpl"
    terminal:
      correction_prompt_file: "./prompts/terminal.tmpl"
      edit_prompt_file: "./prompts/terminal-edit.tmpl"

用途是：

• 普通写作场景怎么整理标点和语气；
• terminal 场景怎么保留命令、路径、flag；
• 选中文本编辑时怎么理解“改正式一点”“翻译一下”这类语音指令。

这和 Coe 当前已有的场景、LLM correction、选中文本编辑方向一致，改动面也比较可控。

3. 语音命令必须显式触发

如果后续支持执行命令，不建议直接把“打开 vscode”“重启 nginx”这类普通话语拿去匹配。第一版应要求固定前缀，例如：

执行命令 打开编辑器

或者：

coe 打开编辑器

只有命中这个前缀，才进入命令匹配。否则继续按普通听写输出。

这样可以减少误触发，也能让用户形成清晰心智：我现在是在输入文字，还是在要求 Coe 执行动作。

4. 配置格式保持简单

命令执行如果做，第一版建议只支持静态配置：

commands:
  enabled: false
  require_confirmation: true
  trigger_prefixes:
    - "执行命令"
    - "coe"
  items:
    - id: open-editor
      trigger: "打开编辑器"
      action:
        type: exec
        argv: ["code"]

    - id: open-site
      trigger: "打开官网"
      action:
        type: exec
        argv: ["xdg-open", "https://example.com"]

几个边界：

• commands.enabled 默认必须是 false。
• 只执行配置文件里声明过的命令。
• 语音只匹配 trigger，不能让 LLM 生成 shell。
• argv 用数组，不走 shell 字符串。
• 第一版不支持管道、重定向、命令拼接、sh -c。

这不是为了限制功能，而是为了先把安全边界做清楚。

5. 安全确认和白名单

命令执行至少需要两层保护：

1. 白名单：只有 YAML 中声明的 command id 可以执行。
2. 确认：危险或有副作用的命令必须确认。

第一版可以更保守一点：

• 默认所有命令都需要确认；
• 后续再允许单条命令设置 confirm: false；
• confirm: false 只适合低风险动作，比如打开应用、打开 URL。

不建议第一版支持这些动作：

• sudo
• 删除文件
• 关机 / 重启
• 格式化磁盘
• 包管理删除
• 自动 git add . && git commit && git push
• 任意用户输入拼接进 shell

这些可以以后单独设计风险等级，不要混进 MVP。

6. 执行器边界

第一版执行器只需要一个：

exec(argv)

它只负责启动一个本地进程，并返回退出状态。不要同时设计 shell plugin、browser plugin、window manager plugin、AI plugin。

窗口控制、浏览器控制、剪贴板 AI workflow 这些都可以先放到外部脚本里，由用户在 argv 里调用脚本。Coe 只负责“识别到明确命令后，执行这个白名单 argv”。

也就是说：

argv: ["my-coe-open-workspace"]

比在 Coe 内部做一个完整 workflow DSL 更适合第一版。

可接受的阶段拆分

Phase 1：自定义文本指令

做 scene 级 prompt 覆盖：

• general / terminal 可配置不同 correction prompt；
• 选中文本编辑可配置 edit prompt；
• 不配置时现有行为完全不变；
• 文档说明全局 prompt 和 scene prompt 的优先级。

这部分最适合先合入。

Phase 2：自定义场景

允许用户添加自己的 scene：

scenes:
  items:
    - id: code-review
      display_name: "Code Review"
      aliases: ["代码审阅", "review"]
      description: "Technical review comments."
      correction_prompt_file: "./prompts/code-review.tmpl"

但需要保持简单：

• general 必须存在；
• scene id 要做校验；
• aliases 用于语音切换；
• 用户 scene 没有 prompt 时回退到 general prompt。

Phase 3：受限命令执行

单独做 commands：

• 默认关闭；
• 固定前缀触发；
• 精确匹配 trigger；
• 只执行白名单 argv；
• 默认确认；
• 命中命令后不再把这句话作为普通文本输出。

这个可以另开 issue / PR 做，不建议和 Phase 1 混在一起。

Phase 4：更复杂的自动化能力

以下内容建议暂缓，或者放到外部脚本 / 外部插件：

• 多步骤 workflow / macro；
• browser plugin；
• window manager plugin；
• AI 自动生成命令；
• 根据自然语言自由选择系统动作；
• GUI workflow 编辑器；
• 跨 GNOME / KDE / Hyprland 的窗口控制抽象；
• 自动 commit message + git push 这类高副作用流程。

这些不是不能做，而是第一版一旦包含它们，Coe 的边界会变得很大，安全和桌面兼容性都会拖慢主线。

结论

我支持把这个 issue 拆成两条线：

1. 先做自定义指令 / 自定义场景：这是 Coe 自身输入体验的一部分，适合纳入主项目。
2. 再单独讨论语音命令执行：只做显式启用、固定前缀、白名单、argv 执行、默认确认的最小版本。

这样既能保留你提到的实用性，也不会把 Coe 从“语音输入工具”一次性扩大成“系统级自动化平台”。