peon-ping-use

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

peon-ping-use

Set which voice pack (character voice) plays for the current chat session.

设置当前聊天会话使用的语音包（角色语音）。

How it works

工作原理

When the user types

/peon-ping-use <packname>

, a beforeSubmitPrompt hook intercepts the command before it reaches the model and handles it instantly:

Validates the requested pack exists
Enables
```
agentskill
```
rotation mode in config.json
Maps the current session ID to the requested pack in .state.json
Returns immediate confirmation (zero tokens used)

When the hook blocks the message, Cursor keeps your cursor in the input field so you can type your next message right away.

The hook scripts (

scripts/hook-handle-use.sh

and

scripts/hook-handle-use.ps1

) do all the work - this SKILL.md file exists solely for discoverability in the

command autocomplete menu.

当用户输入

/peon-ping-use <packname>

时，一个beforeSubmitPrompt钩子会在命令发送给模型之前拦截它并立即处理：

验证请求的语音包是否存在
在config.json中启用
```
agentskill
```
轮换模式
在.state.json中将当前会话ID映射到请求的语音包
返回即时确认（不消耗任何令牌）

当钩子拦截消息时，Cursor会保持光标在输入框中，让你可以立即输入下一条消息。

所有工作由钩子脚本（

scripts/hook-handle-use.sh

和

scripts/hook-handle-use.ps1

）完成，这份SKILL.md文件仅用于在

命令自动补全菜单中被发现。

Usage

使用方法

Users can invoke this by typing:

/peon-ping-use peasant
/peon-ping-use glados
/peon-ping-use sc_kerrigan

If the hook is not installed or fails, you can fallback to manual execution by following the instructions below.

用户可以通过输入以下命令调用：

/peon-ping-use peasant
/peon-ping-use glados
/peon-ping-use sc_kerrigan

如果钩子未安装或运行失败，你可以按照以下说明手动执行。

Manual fallback (if hook fails)

手动回退方案（当钩子失效时）

If for some reason the hook doesn't intercept the command, follow these steps:

如果钩子无法拦截命令，请按照以下步骤操作：

1. Parse the pack name

1. 解析语音包名称

Extract the pack name from the user's request. Common pack names:

```
peon
```
— Warcraft Peon
```
glados
```
— Portal's GLaDOS
```
sc_kerrigan
```
— StarCraft Kerrigan
```
peasant
```
— Warcraft Peasant
```
hk47
```
— Star Wars HK-47

从用户的请求中提取语音包名称。常见的语音包名称：

```
peon
```
— 魔兽争霸苦工
```
glados
```
— 《传送门》GLaDOS
```
sc_kerrigan
```
— 《星际争霸》凯瑞甘
```
peasant
```
— 魔兽争霸农民
```
hk47
```
— 《星球大战》HK-47

2. List available packs

2. 列出可用语音包

Run this command to see installed packs:

bash

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh packs list

Parse the output to verify the requested pack exists.

运行以下命令查看已安装的语音包：

bash

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh packs list

解析输出结果，验证请求的语音包是否存在。

3. Get session ID

3. 获取会话ID

The session ID is available in the environment variable

CLAUDE_SESSION_ID

. Read it:

bash

echo "$CLAUDE_SESSION_ID"

If empty (Cursor users): Use

"default"

as the key in

session_packs

. This applies the pack to all sessions without explicit assignment. Add

session_packs["default"] = {"pack": "PACK_NAME", "last_used": UNIX_TIMESTAMP}

会话ID可通过环境变量

CLAUDE_SESSION_ID

获取。执行以下命令查看：

bash

echo "$CLAUDE_SESSION_ID"

如果为空（Cursor用户）： 在

session_packs

中使用

"default"

作为键。这会将语音包应用到所有未明确分配的会话。添加

session_packs["default"] = {"pack": "PACK_NAME", "last_used": UNIX_TIMESTAMP}

。

4. Update config to enable agentskill mode

4. 更新配置以启用agentskill模式

Read the config file:

bash

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/config.json

Required: Set

pack_rotation_mode

"agentskill"

. The pack must exist in the packs directory; if the assigned pack is missing or invalid, peon-ping falls back to

active_pack

and removes the stale assignment. The hook also adds the pack to

pack_rotation

(manual fallback can do the same).

Example config after setup:

json

"pack_rotation_mode": "agentskill",
"pack_rotation": ["peasant", "peon", "ra2_kirov"]

pack_rotation_mode

"random"

"round-robin"

, change it to

"agentskill"

. If the requested pack is not in

pack_rotation

, add it.

读取配置文件：

bash

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/config.json

必填操作： 将

pack_rotation_mode

设置为

"agentskill"

。语音包必须存在于语音包目录中；如果分配的语音包缺失或无效，peon-ping会回退到

active_pack

并删除无效的分配记录。钩子还会将语音包添加到

pack_rotation

中（手动回退也可以执行此操作）。

设置后的配置示例：

json

"pack_rotation_mode": "agentskill",
"pack_rotation": ["peasant", "peon", "ra2_kirov"]

如果

pack_rotation_mode

为

"random"

或

"round-robin"

，请将其改为

"agentskill"

。如果请求的语音包不在

pack_rotation

中，请添加进去。

5. Update state to assign pack to this session

5. 更新状态以将语音包分配给当前会话

Read the state file:

bash

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/.state.json

Update the

session_packs

object to map this session to the requested pack. If

session_packs

doesn't exist, create it:

json

{
  "session_packs": {
    "SESSION_ID_HERE": "pack_name_here"
  }
}

Use StrReplace or edit the JSON to add/update the entry:

If
```
session_packs
```
exists: add or update the session ID key
If
```
session_packs
```
doesn't exist: add it after the opening brace

读取状态文件：

bash

cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/.state.json

更新

session_packs

对象，将当前会话映射到请求的语音包。如果

session_packs

不存在，请创建它：

json

{
  "session_packs": {
    "SESSION_ID_HERE": "pack_name_here"
  }
}

使用字符串替换或编辑JSON来添加/更新条目：

如果
```
session_packs
```
已存在：添加或更新会话ID对应的键
如果
```
session_packs
```
不存在：在左大括号后添加该对象

6. Confirm to user

6. 向用户确认

Report success with a message like:

Voice set to [PACK_NAME] for this session
   Rotation mode: agentskill

发送如下消息告知操作成功：

本次会话已设置为使用[PACK_NAME]语音
   轮换模式: agentskill

Error handling

错误处理

Pack not found: List available packs and ask user to choose one
No session ID: Inform user this feature requires Claude Code
File read/write errors: Report the error and suggest manual config editing

语音包未找到： 列出可用语音包并请用户选择
无会话ID： 告知用户此功能需要Claude Code
文件读写错误： 报告错误并建议手动编辑配置

Example interaction

交互示例

User: Use GLaDOS voice for this chat
Assistant: [Lists packs to verify glados exists]
Assistant: [Gets session ID]
Assistant: [Updates config.json to set pack_rotation_mode: "agentskill"]
Assistant: [Updates .state.json to set session_packs[session_id] = "glados"]
Assistant: Voice set to GLaDOS for this session
           Rotation mode: agentskill

用户: 本次聊天使用GLaDOS语音
助手: [列出语音包以验证glados存在]
助手: [获取会话ID]
助手: [更新config.json，设置pack_rotation_mode: "agentskill"]
助手: [更新.state.json，设置session_packs[session_id] = "glados"]
助手: 本次会话已设置为使用GLaDOS语音
           轮换模式: agentskill

Cursor compatibility note

Cursor兼容性说明

Cursor doesn't expose session IDs. Use

session_packs["default"]

instead: when doing the manual fallback, add

"default": {"pack": "peasant", "last_used": 0}

session_packs

. This applies the voice to sessions without explicit assignment (including Cursor chats).

Cursor不会暴露会话ID。请改用

session_packs["default"]

：在手动回退时，向

session_packs

中添加

"default": {"pack": "peasant", "last_used": 0}

。这会将语音包应用到所有未明确分配的会话（包括Cursor聊天）。

Reset to default

重置为默认设置

To stop using a specific pack for this session, remove the session ID from

session_packs

.state.json

, or change

pack_rotation_mode

back to

"random"

"round-robin"

要停止为当前会话使用特定语音包，请在.state.json的

session_packs

中删除对应的会话ID，或者将

pack_rotation_mode

改回

"random"

或

"round-robin"

。