speak-with-profile

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Speak With Profile

基于配置文件的语音处理

Use this skill as the front door for speech tasks when the workflow needs reusable profiles, consistent disclosure, and reproducible reporting. Treat built-in

$speech

as the primary synthesis engine, and keep this skill as the policy and profile adapter.

当工作流需要可复用的配置文件、一致的披露规则以及可复现的报告时，请将本Skill作为语音任务的统一入口。将内置的

$speech

作为主要的合成引擎，本Skill则作为策略与配置文件的适配层。

Purpose

用途

Normalize speech requests with deterministic profile precedence.
Enforce disclosure and manifest policy consistently.
Delegate generation to
```
$speech
```
by default in Codex App/CLI conversations.
Keep a script fallback for deterministic local/automation execution.
Support productivity workflows such as narrated notes, spoken drafts, audio summaries, and hands-free review without dropping accessibility-friendly profile options.

基于确定性的配置文件优先级规范语音请求。
统一执行披露规则与运行清单策略。
在Codex应用/CLI会话中，默认将生成任务委托给
```
$speech
```
。
保留脚本回退方案，用于确定性的本地/自动化执行场景。
支持旁白笔记、语音草稿、音频摘要及免提审阅等生产力工作流，同时保留无障碍友好的配置文件选项。

Required UX pattern

必需的UX流程

Route speech requests through
```
$speak-with-profile
```
first.
Resolve profile/default/override values.
Require disclosure text in end-user output context.
Delegate generation to built-in
```
$speech
```
using resolved fields.
Record effective configuration in a run manifest.

首先将语音请求路由至
```
$speak-with-profile
```
。
解析配置文件/默认值/覆盖值。
在最终用户的输出上下文里必须包含披露文本。
使用解析后的字段将生成任务委托给内置的
```
$speech
```
。
在运行清单中记录实际生效的配置。

Execution modes

执行模式

```
delegate
```
(default for conversational usage): use built-in
```
$speech
```
for synthesis.
```
local-cli
```
(fallback for scripted/automation runs): invoke a compatible speech CLI via
```
scripts/speak_with_profile.py
```
.

Use

delegate

unless there is a concrete reason to run the local script path.

```
delegate
```
（对话场景默认模式）：使用内置的
```
$speech
```
进行语音合成。
```
local-cli
```
（脚本/自动化运行的回退模式）：通过
```
scripts/speak_with_profile.py
```
调用兼容的语音CLI工具。

除非有明确的理由需要运行本地脚本，否则请使用

delegate

模式。

Inputs needed

所需输入

Input source: either the exact text to speak or a path to a text file.
Profile choice: a
```
--profile
```
ID if the caller wants a named profile, or no profile if baseline defaults are acceptable.
Profile data source: a
```
--profiles-file
```
path when profile-based resolution is required.
Delivery guidance: any explicit voice, instructions, speed, or format overrides the caller wants to force.
Output intent: target output path or filename expectations for the generated audio.
Execution preference: whether built-in
```
$speech
```
is acceptable or deterministic
```
local-cli
```
behavior is required.
Playback intent: whether the generated file should also be played locally with
```
open
```
or
```
afplay
```
.

Optional skill-local workflow customization from

config/customization.yaml

config/customization.template.yaml

输入源：要朗读的精确文本，或文本文件的路径。
配置文件选择：如果调用者需要指定配置文件，需提供
```
--profile
```
ID；若接受基线默认值，则无需指定。
配置文件数据源：当需要基于配置文件解析时，需提供
```
--profiles-file
```
路径。
交付指引：调用者想要强制设置的任何明确语音、指令、语速或格式覆盖项。
输出意图：生成音频的目标输出路径或文件名要求。
执行偏好：是否允许使用内置的
```
$speech
```
，还是需要确定性的
```
local-cli
```
行为。
播放意图：是否需要使用
```
open
```
或
```
afplay
```
在本地播放生成的文件。
可选的Skill本地工作流自定义：来自
```
config/customization.yaml
```
或
```
config/customization.template.yaml
```
的配置。

Hard constraints

硬性约束

Do not bypass this skill for speech tasks in this repository workflow.
Do not modify built-in
```
$speech
```
behavior assumptions; adapt inputs/outputs around it.
Never modify a compatible downstream speech CLI from this skill; adapt inputs and outputs around it.
Use built-in voices only.
Require
```
OPENAI_API_KEY
```
for live API calls.

本仓库工作流中的语音任务不得绕过本Skill。
不得修改内置
```
$speech
```
的行为假设；需围绕其适配输入/输出。
不得通过本Skill修改兼容的下游语音CLI；需围绕其适配输入/输出。
仅使用内置语音。
实时API调用需要
```
OPENAI_API_KEY
```
。

Disclosure policy

披露策略

Always include a clear disclosure in user-visible output when speech is produced, for example:

"This audio was generated by AI text-to-speech."

If a profile provides

disclosure

, use it. Otherwise, use the default disclosure above.

生成语音时，必须在用户可见的输出中包含明确的披露信息，例如：

"此音频由AI文本转语音生成。"

如果配置文件中提供了

disclosure

字段，则使用该内容；否则使用上述默认披露文本。

Profile resolution order

配置文件解析顺序

Explicit wrapper flags (
```
--voice
```
,
```
--speed
```
,
```
--instructions
```
,
```
--format
```
, output path flags).
Selected profile (
```
--profile
```
).
Default profile from profiles file (
```
default_profile
```
).

Baseline defaults (

voice=cedar

speed=1.0

, format

mp3

, model

gpt-4o-mini-tts-2025-12-15

显式的包装器标志（
```
--voice
```
、
```
--speed
```
、
```
--instructions
```
、
```
--format
```
、输出路径标志）。
选中的配置文件（
```
--profile
```
）。
配置文件中的默认配置（
```
default_profile
```
）。

基线默认值（

voice=cedar

、

speed=1.0

、格式

mp3

、模型

gpt-4o-mini-tts-2025-12-15

）。

Workflow configuration precedence

工作流配置优先级

Explicit user input and wrapper flags.
Skill-local workflow customization in
```
config/customization.yaml
```
, when present.
Skill-local defaults in
```
config/customization.template.yaml
```
.
Workflow defaults described in this skill and
```
references/wrapper-contract.md
```
.

The local wrapper loads supported customization values from

config/customization.yaml

and

config/customization.template.yaml

at runtime. Use skill-local customization to guide wrapper defaults and agent decisions.

preferredExecutionMode

remains documentation-only because the wrapper script implements only

local-cli

, while the skill-level workflow still treats

delegate

as the default conversational path.

显式的用户输入和包装器标志。
Skill本地工作流自定义（若存在
```
config/customization.yaml
```
）。
Skill本地默认值（
```
config/customization.template.yaml
```
）。
本Skill及
```
references/wrapper-contract.md
```
中描述的工作流默认值。

本地包装器会在运行时从

config/customization.yaml

和

config/customization.template.yaml

加载支持的自定义值。使用Skill本地自定义来指导包装器默认值和代理决策。

preferredExecutionMode

仅作为文档参考，因为包装器脚本仅实现了

local-cli

，而Skill层工作流仍将

delegate

作为对话场景的默认路径。

Workflow

工作流

Resolve input text source (
```
--text
```
or
```
--text-file
```
).
Resolve effective workflow settings using explicit input, skill-local customization, then workflow defaults.
Resolve profile and defaults using
```
references/wrapper-contract.md
```
.
Validate configuration against
```
references/profile-schema.md
```
.
Choose execution mode:
- ```
delegate
```
  : call built-in
```
$speech
```
  with resolved fields.
- ```
local-cli
```
  : run
```
scripts/speak_with_profile.py
```
  .
Emit/validate run manifest and include disclosure.

解析输入文本源（
```
--text
```
或
```
--text-file
```
）。
使用显式输入、Skill本地自定义、工作流默认值来解析实际生效的工作流设置。
使用
```
references/wrapper-contract.md
```
解析配置文件和默认值。
根据
```
references/profile-schema.md
```
验证配置。
选择执行模式：
- ```
delegate
```
  ：使用解析后的字段调用内置的
```
$speech
```
  。
- ```
local-cli
```
  ：运行
```
scripts/speak_with_profile.py
```
  。
生成/验证运行清单并包含披露信息。

Output Contract

输出约定

```
delegate
```
: return a user-visible result that confirms speech generation intent, includes the disclosure text, and surfaces the resolved speech settings that matter for the request.
```
local-cli
```
: produce an audio file at the requested or resolved output path and write an adjacent
```
<audio>.manifest.json
```
file.
```
local-cli
```
manifest/result reporting must include:
- output audio path
- manifest path
- disclosure text
- execution mode (
```
local-cli
```
  )
- playback result when
```
open
```
  or
```
afplay
```
  is used
Playback failures must remain explicit rather than being treated as silent success.

```
delegate
```
模式：返回用户可见的结果，确认语音生成意图，包含披露文本，并展示与请求相关的已解析语音设置。
```
local-cli
```
模式：在请求的或解析后的输出路径生成音频文件，并在相邻位置写入
```
<audio>.manifest.json
```
文件。
```
local-cli
```
模式的清单/结果报告必须包含：
- 输出音频路径
- 清单路径
- 披露文本
- 执行模式（
```
local-cli
```
  ）
- 使用
```
open
```
  或
```
afplay
```
  时的播放结果
播放失败必须明确返回，而非视为静默成功。

Failure modes

失败场景

Missing
```
OPENAI_API_KEY
```
: stop before generation and tell the caller that the local environment must provide the API key.
Missing text source or unreadable text file: fail fast rather than guessing input content.
Missing profiles file when
```
--profile
```
is requested: fail fast and require the caller to provide a valid JSON or YAML profiles file.
Invalid profiles file: stop on schema/parse errors and surface the validation failure clearly.
Unknown profile ID: fail with the known profile list from the supplied profiles file.
Input over 4096 characters: fail fast and require the caller to split or chunk the input before running.
Missing compatible speech CLI on the local CLI path: stop and report that
```
--tts-cli-path
```
must point to a valid speech CLI implementation.
Downstream speech CLI failure: propagate the subprocess failure rather than masking it.
Playback failure with
```
open
```
or
```
afplay
```
: return the deterministic playback failure outcome, record it in the manifest, and respect
```
--stop-on-error
```
/
```
--no-stop-on-error
```
.

缺少
```
OPENAI_API_KEY
```
：在生成前终止，并告知调用者本地环境必须提供API密钥。
缺少文本源或文本文件不可读：快速失败，而非猜测输入内容。
当请求
```
--profile
```
时缺少配置文件：快速失败，要求调用者提供有效的JSON或YAML配置文件。
无效的配置文件：在 schema/解析错误处终止，并清晰展示验证失败信息。
未知的配置文件ID：失败并返回提供的配置文件中的已知配置文件列表。
输入超过4096字符：快速失败，要求调用者在运行前拆分或分块输入。
本地CLI路径中缺少兼容的语音CLI：终止并报告
```
--tts-cli-path
```
必须指向有效的语音CLI实现。
下游语音CLI失败：传播子进程失败，而非掩盖。
使用
```
open
```
或
```
afplay
```
播放失败：返回确定性的播放失败结果，记录到清单中，并遵循
```
--stop-on-error
```
/
```
--no-stop-on-error
```
设置。

References

参考资料

Profile schema and validation rules:
```
references/profile-schema.md
```
Starter profile set and examples:
```
references/starter-profiles.md
```
Adapter contract and mode behavior:
```
references/wrapper-contract.md
```
Skill-local workflow customization:
```
references/customization.md
```

配置文件schema和验证规则：
```
references/profile-schema.md
```
初始配置文件集和示例：
```
references/starter-profiles.md
```
适配器约定和模式行为：
```
references/wrapper-contract.md
```
Skill本地工作流自定义：
```
references/customization.md
```

Validation helper

验证工具

Use

scripts/validate_manifest.py

to verify required manifest keys:

bash

uv run --group dev python speak-with-profile/scripts/validate_manifest.py path/to/output/file.manifest.json

使用

scripts/validate_manifest.py

验证清单的必填字段：

bash

uv run --group dev python speak-with-profile/scripts/validate_manifest.py path/to/output/file.manifest.json