【免费下载链接】peon-pingWarcraft III Peon voice notifications ( more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.项目地址https://gitcode.com/gh_mirrors/pe/peon-ping点击查看免费下载本指南以 docs/designs/2026-05-09-omp-adapter-design.md 为骨架结合仓库中已落地的源码adapters/omp/peon-ping.ts、adapters/omp.sh、peon.sh与测试tests/omp.bats完整讲解 peon-ping 如何为 oh-my-piCLI 二进制名omp提供声音、通知、训练提醒与中继支持。读完本文你将掌握 omp 扩展的发现与加载机制、6 个生命周期事件到 peon-ping hook 事件的映射关系、source: omp与omp-session-id 前缀双通道 IDE 识别原理以及一键安装/卸载适配器的完整操作。背景为什么 omp 需要一个纯传输层适配器oh-my-pi简称 omp是一个基于 bun/TypeScript 的编码 Agent CLI。在引入本适配器之前peon-ping 对 omp 没有专门支持omp 用户拿不到声音、桌面通知、trainer 与 relay 能力——尽管 peon-ping 侧所有必要原语声音包、CESP 分类、通知、状态机都已就绪缺口完全在适配层。设计文档给出的核心结论是该适配器不做任何 peon-ping 未对其他 IDE 提供的事件翻译逻辑它纯粹是一个传输通道transport。所有 IDE 适配器共享同一形态接收 IDE 事件 → 翻译 → 以 CESP 形状的 JSON 载荷 spawnpeon.sh。peon.sh 已经是 Claude Code 的 hook在 README.md 的 How it works 一节描述了其五步工作流事件映射 → 声音选择 → 异步播放 → 通知/标签页标题 → 远程路由SSH/devcontainer/Codespaces 场景经 HTTP 转发到本机 relay。omp 适配器只需要把事件喂进这条现成管道。omp 扩展机制扩展如何被发现与加载在设计文档中omp 的扩展加载遵循目录发现规则扩展是default导出的 TS 模块自动发现位置有四处cwd/.omp/extensions/项目级作用域~/.omp/agent/extensions/用户级作用域~/.omp/plugins/node_modules/市场插件omp --extension path/omp --hook pathCLI 覆盖目录条目的解析链为package.json含omp.extensions字段→index.ts→index.js→ 目录扫描。这正是 adapters/omp/package.json 中omp: { extensions: [./peon-ping.ts] }字段存在的意义——目录式扩展必须有该字段omp 的目录加载器才能可靠地找到入口文件这也是以后可以直接作为市场插件分发而无需重构的伏笔。事件映射omp 生命周期 → peon-ping hook 事件设计文档给出的音频适配器相关事件全集完整目录见 omp 官方的authoring-hooks.md以及落地代码中的映射关系如下omp 事件触发时机peon-pinghook_event_namesession_start会话加载时触发一次SessionStartturn_start每个用户→Agent 回合开始UserPromptSubmitturn_end每个回合结束Stoptool_result且event.isError true每次工具执行失败PostToolUseFailureauto_compaction_start自动压缩开始前PreCompactsession_shutdown会话关闭时SessionEnd这 6 个事件在 adapters/omp/peon-ping.ts 中逐一注册。每个事件在 peon.sh 中都有对应的 CESP 路由分支例如 peon.sh 中SessionStart映射到session.start分类并设置status readypeon.sh 中PreCompact映射到resource.limit上下文压缩告警peon.sh 中SessionEnd负责清理该 session 的持久化状态。设计文档特别指出一个与 OpenCode 适配器的关键差异OpenCode 的session.created事件在插件订阅之前就触发所以 OpenCode 适配器需要额外用setTimeout延迟补发一次SessionStart而 omp 文档化的生命周期保证session_start在所有扩展加载完成之后才触发因此工厂调用期间同步注册处理器即可无需初始补发定时器。核心实现adapters/omp/peon-ping.ts查找 peon.sh 的候选路径与 OpenCode 适配器完全一致adapters/omp/peon-ping.ts 依次探测两个候选路径const PEON_SH_PATHS [ path.join(os.homedir(), .claude, hooks, peon-ping, peon.sh), path.join(os.homedir(), .openclaw, hooks, peon-ping, peon.sh), ] function findPeonSh(): string | null { for (const p of PEON_SH_PATHS) { try { if (fs.existsSync(p)) return p } catch {} } return null }若找不到peon.sh扩展只打印一行安装指引警告brew install PeonPing/tap/peon-ping或curl -fsSL peonping.com/install | bash并直接返回不注册任何处理器——保证在 peon-ping 未安装时适配器是安静失败的。会话 ID 生成与 IDE 识别兜底扩展生成sessionId omp- Date.now()见 adapters/omp/peon-ping.ts。omp-前缀是刻意的设计即便source字段在某个环节被丢弃peon.sh也能通过 session-id 前缀表回退识别出 IDE。这是双通道识别策略。firePeonCESP 形状的载荷firePeon(event)与 OpenCode 适配器同构adapters/omp/peon-ping.tsfunction firePeon(event: string): void { const payload JSON.stringify({ hook_event_name: event, notification_type: , cwd, session_id: sessionId, permission_mode: , source: omp, }) try { const proc spawn(bash, [peonSh], { stdio: [pipe, ignore, ignore], }) proc.stdin.write(payload) proc.stdin.end() proc.unref() } catch {} }要点payload 使用 CESP 形状字段hook_event_name、notification_type、cwd、session_id、permission_mode、sourcestdio只保留 stdin 管道stdout/stderr 忽略写完后立即proc.unref()让子进程脱离父进程存活不阻塞 omp 的事件循环。处理器与标签页标题守卫adapters/omp/peon-ping.ts 的 6 个处理器全部通过pi.on(...)注册。其中 4 个处理器在ctx.hasUI true时通过 OSC-0 序列\x1b]0;…\x07更新终端标签页标题session_start→ 标题${projectName}: ready触发SessionStartturn_start→ 标题${projectName}: working触发UserPromptSubmitturn_end→ 标题● ${projectName}: done触发Stoptool_result仅event.isError true→ 标题● ${projectName}: error触发PostToolUseFailureauto_compaction_start→ 仅触发PreCompact不写标题session_shutdown→ 仅触发SessionEnd不写标题ctx.hasUI守卫的意义headless 运行与 subagent 会话不拥有自己的 TTY写入 OSC-0 会与 omp 自身持有的 TTY 互相覆盖导致闪烁。交互式场景下该写法在 OpenCode 适配器中已被验证稳定。零第三方依赖与 type-only import导入清单只有node:*内置模块与 omp 的类型adapters/omp/peon-ping.tsimport * as fs from node:fs import * as path from node:path import * as os from node:os import { spawn } from node:child_process import type { ExtensionAPI } from oh-my-pi/pi-coding-agent关键设计ExtensionAPI以type限定导入因此该文件在未安装oh-my-pi/pi-coding-agent包的情况下也能被解析——运行时由 omp 的扩展加载器在加载时刻提供该类型的实际值。这也是后续bun build 无需安装依赖即可通过测试的前提。扩展清单adapters/omp/package.jsonadapters/omp/package.json 是目录式 omp 扩展的必需清单{ name: peon-ping, version: 1.0.0, description: peon-ping adapter for oh-my-pi (omp) — routes lifecycle events through peon.sh., omp: { extensions: [./peon-ping.ts] } }omp.extensions数组指向扩展入口name: peon-ping与仓库内 Claude Code hook 目录命名保持一致。该清单的存在同时保证适配器日后可直接作为 omp 市场插件~/.omp/plugins/node_modules/分发。一键安装adapters/omp.shadapters/omp.sh 的形态与 adapters/opencode.sh 一致核心流程为预检从~/.claude/hooks/peon-ping/peon.sh与~/.openclaw/hooks/peon-ping/peon.sh两个候选路径定位peon.sh找不到则打印安装指引并以退出码 1 结束adapters/omp.sh。创建目录mkdir -p ~/.omp/agent/extensions/peon-ping/并防御性删除可能残留的过期符号链接。写入文件优先下载peon-ping.ts与package.json两个curl -fsSL若设置了测试专用环境变量PEON_PING_LOCAL_ADAPTER_DIR则从本地 checkout 的adapters/omp/目录直接cp完全不依赖 curladapters/omp.sh。输出成功块列出扩展文件、清单与peon.sh的最终路径并提示Restart omp to activate以及后续配置命令peon config/peon trainer on/peon packs list。--uninstall删除整个扩展目录~/.omp/agent/extensions/peon-ping/adapters/omp.sh目录不存在时仅提示并正常退出。注意该适配器v1 不提供 PowerShell 安装器详见下文 Non-Goals。Windows 上 omp 通过 bun 运行只要bash在PATH上同一份peon.sh即可工作真正的 PowerShell 安装器留待用户反馈真实需求后再补。peon.sh 的 IDE 识别表三处微小改动peon.sh的 IDE 解析块实际行号 peon.sh只新增了三个条目这是整个peon.sh的唯一改动面①IDE_ALIASESpeon.sh归一化source字段将 omp 的各类别名统一收拢为ompomp: omp, oh-my-pi: omp, oh_my_pi: omp, pi: omp,normalize_ide_id会先把输入转小写、把空格/下划线替换为连字符再查表——所以oh-my-pi、oh_my_pi、Oh-My-Pi等变体最终都归一化为omp。②prefix_map元组peon.sh位于detect_session_ide内部作为 session-id 前缀的兜底识别(omp-, omp),detect_session_ide的判定顺序是先看归一化后的source跳过resume/compact这两个特殊值→ 再查workspace_rootsCursor 特征→ 最后按 session-id 前缀匹配prefix_map→ 兜底返回claude。因此source: omp缺失时session_id: omp-456依然能正确解析为 omp。③IDE_DISPLAY_NAMESpeon.sh人类可读展示名omp: oh-my-pi,展示名会出现在桌面通知标题与日志中display_ide_name对未命中表的 IDE 会回退为key.replace(-, ).title()式转换。在 tests/omp.bats 中三个 IDE 检测用例通过run_peon向peon.sh喂入合成事件并断言terminal_notifier.log中出现myproject - oh-my-pi分别覆盖source: omp直连、source: oh-my-pi别名归一化、source缺失但session_id: omp-456的前缀兜底。测试 setup 会先把notification_title_ide置为true让通知标题携带 IDE 名以便断言。测试策略BATS 覆盖两套表面tests/omp.bats 共 9 个用例覆盖安装器与 IDE 表两个表面IDE 检测组3 个即上文三用例全部走setup_test_env/run_peon助手来自 tests/setup.bash断言通知标题中的展示名。安装器组6 个独立的setup_installer_env助手会构造干净的临时HOME、mock 一个peon.sh以满足预检、并在PATH前插入一个 mockcurl按 URL 返回固定内容installer: script has valid bash syntax——bash -n语法校验installer: fails when peon.sh is not found—— 预检失败路径installer: fresh install writes extension files—— 断言peon-ping.ts与package.json落盘且内容含omp.extensions与omp字面量installer: re-install is idempotent and overwrites stale content—— 二次安装覆盖陈旧内容installer: --uninstall removes extension directory—— 卸载删除目录installer: PEON_PING_LOCAL_ADAPTER_DIR env var copies from local path instead of curl—— 把 mock curl 改成直接exit 99证明本地目录拷贝路径完全绕开网络CI 侧无需改动GitHub Actions 的 BATS 任务macos-latest会自动拾取tests/omp.bats。peon-ping 的 CI 不运行 TS因此适配器 TS 文件的验证走手动冒烟测试bun build --targetnode adapters/omp/peon-ping.ts应无错误退出type-only import 不要求包已安装若bun不可用可退化为npx -p typescriptlatest tsc --noEmit --target ES2022 --module nodenext --moduleResolution nodenext --skipLibCheck --allowImportingTsExtensions adapters/omp/peon-ping.ts。明确不做的事项YAGNI 边界设计文档清晰划定了 v1 范围以下内容有意排除Windows 原生omp.ps1Windows 上 omp 经 bun 运行调用的是PATH上的同一个bash peon.sh真实 PowerShell 安装器留待用户报告需求。PermissionRequest映射omp 的tool_call阻塞属于 hook 作者面而非用户可见的权限 UI没有干净信号可映射到PermissionRequest等 omp 暴露该信号后再做。Subagent 抑制omp 的 subagent 面是ctx.hasUI false适配器只据此跳过标签页标题写入不发明逐会话抑制方案有需求的用户应自行设置suppress_delegate_sessions: true。branch / tree / TTSR 事件对音频适配器无意义。安装器--local用户可见标志其他适配器安装器也没有测试用PEON_PING_LOCAL_ADAPTER_DIR仅测试 harness 设置重定向来源不暴露生产标志。风险与开放问题设计文档记录了三个已识别风险及其缓解Type-only import 的韧性若oh-my-pi/pi-coding-agent未来移动ExtensionAPI符号import type会在安装期失败。缓解固守文档化的公开类型路径若破坏退化为文件内联结构类型定义不开 import——Kilo 对 OpenCode 采用的就是同一招。turn_start与before_agent_start的选择两者都在回合开始附近触发。已批准映射采用turn_start文档化的稳定面若实测发现它在压缩后续接时触发过早单行即可切换无 schema 影响。标签页标题竞争后台扩展写 OSC-0 与 omp 自身的 TTY 所有权可能闪烁。适配器已用ctx.hasUI守卫避免 headless/subagent 竞争交互场景沿用 OpenCode 适配器验证过的同款方案。成功标准与效果验证设计文档定义的验收标准全部围绕安装可用、识别正确、测试通过、文档同步bash adapters/omp.sh在已装 peon-ping 的干净机器上把扩展装入~/.omp/agent/extensions/peon-ping/扩展激活后omp 会话在会话开始、回合结束、工具错误、压缩、会话关闭时触发既有 peon-ping 声音peon.sh识别source: omp及omp-session-id 兜底IDE 显示名为oh-my-pitests/omp.bats全部通过既有测试保持绿色README 徽章与 Multi-IDE 矩阵包含 omp且中/韩/日译文同步。落地状态可从仓库直接核实README.md 已有完整的 oh-my-pi (omp) setup 章节含快速安装、事件映射表与卸载命令Multi-IDE 表新增 omp 行README.mddocs/public/llms.txt 也已登记 omp 适配器条目。总结omp 适配器是 peon-ping thin adapter 范式的又一次落地不重新实现任何声音/通知逻辑只做事件翻译与进程桥接。扩展侧用 6 个pi.on处理器把 omp 生命周期事件翻译为 CESP 形状的 JSON经 stdin 喂给peon.shpeon.sh侧仅靠三处表项IDE_ALIASES、prefix_map、IDE_DISPLAY_NAMES就获得完整的 IDE 识别、展示与路由能力。整个改动面控制在 4 个新文件 3 处小编辑配合 9 个 BATS 用例与bun build手动冒烟测试完成闭环验证这正是适配层纯传输、复用全部现有原语这一架构决策的直接收益。赞分享【免费下载链接】peon-pingWarcraft III Peon voice notifications ( more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.项目地址https://gitcode.com/gh_mirrors/pe/peon-ping点击查看免费下载相关推荐oh-my-pi 扩展开发完全指南从零编写 ExtensionAPI 工具、命令与事件处理器oh my pi 扩展开发完全指南从零编写 ExtensionAPI 工具、命令与事件处理器 本篇指南以 oh my pi 官方扩展编写文档 docs/ski人工智能AI Agent代码智能体工具调用CLIMCP ClientsFirstmate 接入 ompOh My PiHarness 适配器启动契约、检测机制与主代理集成指南Firstmate 接入 ompOh My PiHarness 适配器启动契约、检测机制与主代理集成指南 导读 本文基于 Firstmate 开源仓库中peon-ping 声音静音开关实战指南/peon-ping-toggle 技能与 peon toggle 命令的完整解析peon ping 声音静音开关实战指南 /peon ping toggle 技能与 peon toggle 命令的完整解析 导读 peon ping 是面向上一篇Aim 实验追踪查询语言 AimQL 实战指南基于 Python 表达式过滤 Runs、Metrics 与 Images下一篇express-validator 废弃的 sanitize 系列中间件全解析API 说明、底层原理与迁移到 check() 的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考