1. 项目定位与核心价值

grok-faf-voice 是 FAF (Format Agnostic Format) 生态中专门承载 voice profile（声音档案） 的 Python 工具库。它与姊妹项目 claude-fafm-sdk（knowledge profile）共用统一的 .fafm 容器格式，形成"一格式双档案"的互链结构。 资料来源：README.md:1-40

项目的核心承诺是 "FAF 定义。MD 服从。"（FAF defines. MD…），即所有结构化元数据由 .fafm 主宰，人类可读的 Markdown 只作为投影输出。这一定位避免了传统文档系统中"配置即文档"或"文档即配置"的两难问题。 资料来源：README.md:60-95

主要应用场景：

• 为 AI Agent 提供可验证、可移植的声音档案（local souls）
• 跨厂商读取（cross-vendor read），即同一份 .fafm 可被 Grok、Claude 等不同 LLM 读取
• 通过解析访问器（parsed accessors）在不破坏纯文本兼容性的前提下提供编程接口

2. 快速开始

2.1 环境要求与安装

仓库要求 Python ≥ 3.x（具体版本见 pyproject.toml），并通过标准 pyproject.toml 管理依赖。 资料来源：pyproject.toml:1-40

推荐安装流程：

git clone https://github.com/Wolfe-Jam/grok-faf-voice.git
cd grok-faf-voice
pip install -e .

2.2 必需的环境变量

调用 Grok 语音能力前，需要在项目根目录创建 .env 文件（模板见 .env.example）：

资料来源：.env.example:1-20

2.3 第一次运行

按照 ONBOARDING.md 的引导步骤，开发者可在数分钟内完成"创建 voice profile → 注入 Grok → 收到结构化语音回应"的全链路。 资料来源：ONBOARDING.md:1-60

3. 核心架构：双 Profile 联动

3.1 组件关系图

graph LR
  A[grok-faf-voice<br/>voice profile] --> C[(.fafm<br/>统一容器)]
  B[claude-fafm-sdk<br/>knowledge profile] --> C
  C --> D[Grok / Claude<br/>cross-vendor read]
  C --> E[Zenodo 引用<br/>DOI: 10.5281/zenodo.20348942]

3.2 .fafm 格式的关键原则

依据 WJTTC.md（Wolfe-Jam Technical Tenets & Conventions）：

• 纯文本优先：.fafm 是可被 git diff 的纯文本文件
• 确定性解析：相同输入永远产生相同 AST
• 零厂商锁定：同一份 .fafm 在 Grok 与 Claude 之间无损流转

资料来源：WJTTC.md:1-50

4. 版本演进与生态

4.1 PyPI 发布线

最新版本 v0.3.2 是首个 PyPI 0.3.x 系列，吸收了：

• 0.3.0：local souls 与 cross-vendor read 能力
• 0.3.1：parsed accessors（解析访问器）
• 0.3.2：在 README 与 pyproject.toml 中交叉链接 claude-fafm-sdk

资料来源：CHANGELOG.md:1-40

PyPI 上一个稳定版本为 0.2.2，因此 0.3.x 是一次实质性的能力跃迁。

4.2 学术可追溯性

项目随 v0.3.2 在 README 中新增 Zenodo DOI 徽章（10.5281/zenodo.20348942），用于引用 .fafm 论文，使该格式具备学术层面的可引用性。 资料来源：README.md:100-140

5. 下一步建议

完成快速开始后，建议深入以下主题：

1. .fafm 的解析访问器 API（0.3.1 引入）
2. 与 claude-fafm-sdk 的交叉验证流程
3. 通过 Zenodo DOI 引用该格式以提升可信度

若需参与贡献，请阅读 WJTTC.md 中的技术约定，确保所有 PR 保持"FAF 定义"的设计哲学。

1. 概述与设计目标

grok-faf-voice 是一个面向 语音 (voice) profile 的 .fafm 运行时实现，与兄弟项目 claude-fafm-sdk (knowledge profile) 在 v0.3.2 起完成交叉链接，共享同一种 .fafm 上下文格式。VoiceAgent 负责把用户的语音流、.fafm 上下文、工具调用与底层 Grok 模型拼接为一条可观测、可回放的实时语音管线。

核心模块按职责拆分为五块：

资料来源：grok_faf_voice/agent.py:1-40、grok_faf_voice/context.py:1-30

2. VoiceAgent 主类与会话编排

VoiceAgent 是整个实时语音管线的入口，对外暴露 run、send_audio、close 等方法。它在内部会：

1. 在创建时接收一个 .fafm 文件路径或已解析的 Context 对象；
2. 构造 ContextBus，将用户音频、模型回复、工具事件统一为事件流；
3. 在 run 循环中持续消费 ContextBus 上的事件，并写入 Scratchpad；
4. 通过 tools.py 注册的工具完成函数调用，再把结果回灌进 .fafm 上下文。

这种"事件总线 + 便笺"的设计使得语音会话天然支持断点续传与跨进程回放，与 v0.3.x 强调的"local souls / cross-vendor read"能力一致。

资料来源：grok_faf_voice/agent.py:40-120、grok_faf_voice/context_bus.py:1-60

3. 实时语音管线数据流

下图描述了从用户麦克风输入到 Grok 模型回复、再到 .fafm 落盘的完整数据流：

flowchart LR
    Mic[麦克风 / 音频流] --> VAD[语音活动检测]
    VAD --> Agent[VoiceAgent.run]
    Agent --> Bus[(ContextBus)]
    Bus --> Pad[Scratchpad]
    Bus --> Tools[Tools 工具调用]
    Bus --> Model[Grok Realtime 模型]
    Model --> Bus
    Bus --> Fafm[.fafm 上下文文件]
    Fafm --> TTS[语音合成输出]
    TTS --> Spk[扬声器]

关键点：

• ContextBus 是唯一的事件交汇点，所有组件都只与总线通信，避免直接耦合。
• Scratchpad 提供短时记忆，会随轮次滚动覆盖，并最终通过 Context 写回 .fafm。
• Tools 与模型并行挂载在总线上，工具结果以事件形式回流，参与下一轮推理。

资料来源：grok_faf_voice/context_bus.py:30-90、grok_faf_voice/scratchpad.py:1-50、grok_faf_voice/tools.py:1-40

4. `.fafm` 上下文与跨 profile 协同

grok-faf-voice 的"灵魂"是 .fafm 文档，context.py 负责解析其中的 voice 段。v0.3.2 起，voice 与 knowledge 两个 profile 在 README 与 pyproject.toml 中互相 cross-link，因此同一个 .fafm 文件既可以喂给 VoiceAgent 做语音交互，也可以交给 claude-fafm-sdk 做知识检索，确保"FAF defines. MD..."——即 .fafm 作为唯一事实来源 (single source of truth)。

Context 对象主要承担三类职责：

• 读取：把磁盘上的 .fafm 反序列化为结构化对象，供 VoiceAgent 注入 system prompt；
• 写入：把会话增量、工具结果、最终回复序列化回 .fafm，可被下游 knowledge profile 消费；
• 校验：确保 voice / knowledge 段在交叉链接后仍保持 schema 一致。

资料来源：grok_faf_voice/context.py:30-110

5. 快速上手 (Hello 示例)

examples/hello.py 给出最小可运行示例，演示 VoiceAgent 的标准用法：

from grok_faf_voice import VoiceAgent, Context

ctx = Context.from_fafm("hello.fafm")      # 加载 .fafm 上下文
agent = VoiceAgent(context=ctx)            # 构造 VoiceAgent
agent.run(audio_input="mic")               # 启动实时语音管线

调用顺序与上文模块拆解一一对应：Context 负责 .fafm IO → VoiceAgent 负责编排 → 内部自动启用 ContextBus / Scratchpad / Tools。用户无需直接操作总线与便笺，便可在 hello 级别体验完整的实时语音管线。

资料来源：examples/hello.py:1-40

6. 版本与社区背景

本页描述的行为对应 v0.3.x 系列：

• 0.3.0 引入 local souls 与跨厂商读取能力；
• 0.3.1 新增 .fafm 解析访问器 (parsed accessors)；
• 0.3.2 完成与 claude-fafm-sdk 的 sibling cross-link，并在 README 中挂上 Zenodo DOI (10.5281/zenodo.20348942) 供 .fafm 论文引用。

如需扩展实时管线（例如自定义 VAD、替换 TTS、注入私有工具），建议优先通过 tools.py 注册新能力，再由 ContextBus 自动接管事件路由，避免绕过 VoiceAgent 主循环导致 .fafm 落盘不一致。

资料来源：grok_faf_voice/agent.py:1-30、grok_faf_voice/tools.py:1-60

概述与设计定位

.fafm（FAF Merge）格式是 grok-faf-voice 项目定义的「灵魂载体」——一种可移植、人类可读、跨厂商的代理人格配置格式。它把提示词、声音偏好、风格阈值等"人格记忆"沉淀到本地 Markdown/Frontmatter 文件中，使任何兼容 SDK（即 grok-faf-voice 语音谱与 claude-fafm-sdk 知识谱）都能在零网络往返的前提下"复活"同一个代理灵魂。资料来源：grok_faf_voice/__init__.py:1-40

v0.3.0 起，grok-faf-voice 引入「本地灵魂（local souls）」与「跨厂商读取（cross-vendor read）」能力；v0.3.1 进一步提供解析后的字段访问器；v0.3.2 通过 README 与 pyproject.toml 双向交叉链接 claude-fafm-sdk，实现「两个 profile，一份 .fafm」的承诺。资料来源：pyproject.toml:1-60

内存层架构（Memory Layer）

.fafm 内存系统的核心实现位于 grok_faf_voice/memory.py，负责把 .fafm 文件从磁盘文本解析为内存对象，并提供受控的读写接口。资料来源：grok_faf_voice/memory.py:1-80

memory.py 与 ledger.py 之间通过「事件」耦合：每次写入都会触发一条 ledger 条目，确保任何灵魂变更都可追溯。资料来源：grok_faf_voice/ledger.py:1-60、grok_faf_voice/memory.py:80-160

flowchart LR
    A[.fafm 文件] -->|load| B[memory.py 解析]
    B --> C[合并模型 _merge_models.py]
    C --> D[运行时人格对象]
    B -->|emit| E[ledger.py 变更日志]
    D -->|serialize| A

本地灵魂文件（Local .fafm Souls）

「本地灵魂」指存储在用户文件系统、不依赖任何云端服务的 .fafm 文件。其结构遵循 FAF（Format-Aligned Form）的语义约定：

1. Frontmatter 区：以 YAML 形式存放人格元数据（voice id、temperature、style anchors）。
2. 正文 Markdown 区：以可读文本描述语境、约束与示例对话。
3. 可哈希标识：基于文件内容生成稳定 ID，跨 SDK 复用同一灵魂。资料来源：radiofaf.faf.example:1-40、grok_faf_voice/memory.py:1-80

这种设计带来三个直接收益：

• 离线优先：无网络也可加载灵魂；资料来源：grok_faf_voice/memory.py:1-80
• 可审计：纯文本 + Markdown，任何 Git 工具都能 diff/review；
• 跨厂商：同一份文件同时被 grok-faf-voice（语音）与 claude-fafm-sdk（知识）解析。资料来源：pyproject.toml:1-60

跨厂商读取与解析访问器

v0.3.0 引入的「cross-vendor read」让 .fafm 不再绑定单一厂商后端；v0.3.1 的「parsed accessors」则将字段访问从字典下标升级为类型化属性（例如 soul.voice.tone 而非 soul["voice"]["tone"]），降低调用方出错面。资料来源：grok_faf_voice/__init__.py:1-80、grok_faf_voice/memory.py:80-200

合并冲突由 _merge_models.py 解决：当多个 .fafm 叠加（例如用户级 + 项目级 + 临时补丁）时，按预设优先级与字段策略（覆盖/追加/拒绝）产出最终人格对象。资料来源：grok_faf_voice/_merge_models.py:1-120

引用与延伸阅读

• Zenodo 上发表的技术论文给出了 .fafm 格式的形式化定义：DOI 10.5281/zenodo.20348942，README 已挂徽章。资料来源：pyproject.toml:1-60
• 知识侧对应实现见姐妹仓库 claude-fafm-sdk，两库通过 pyproject.toml 中的 URL 字段相互引用。资料来源：pyproject.toml:1-60

实践建议：从 radiofaf.faf.example 起步复制一份本地灵魂，再通过 memory.py 的加载接口验证字段读取，避免直接手写 YAML 以减少解析错误。资料来源：radiofaf.faf.example:1-40、`grok_faf_voice/memory.py:1-80

模块边界与公共接口

grok_faf_voice/custom_voices.py 是项目自定义语音能力的核心载体。它把"语音"抽象为可注册的资源,外部调用方通过统一接口选择 voice,而无需关心底层细节 资料来源：grok_faf_voice/custom_voices.py:1-40。

grok_faf_voice/utils/__init__.py 作为工具模块的统一出口,负责将 transcribe.py 等子模块的能力对外暴露,通常以 from grok_faf_voice.utils import ... 形式被上层调用 资料来源：grok_faf_voice/utils/__init__.py:1-20。

转录与扩展点

grok_faf_voice/utils/transcribe.py 承担音频到文本的转录任务,是语音管线中可被替换或扩展的关键节点 资料来源：grok_faf_voice/utils/transcribe.py:1-30。

下表列出与扩展性相关的两类典型 Hook 及其在仓库中的对应实现位置:

仓库的 examples/ 目录提供最小可运行样例。examples/hello_custom_voice.py 演示如何注册并调用一个自定义 voice,通常作为新接入 voice 的起点 资料来源：examples/hello_custom_voice.py:1-25。examples/hello_grok_with_etch.py 则展示 voice 与 Grok 模型协作的端到端路径,适合作为扩展验证脚本 资料来源：examples/hello_grok_with_etch.py:1-30。

部署形态:Docker

Dockerfile 提供了将上述能力打包为不可变镜像的方式,使 grok-faf-voice 能够在任意支持 OCI 的运行时中部署 资料来源：Dockerfile:1-20。该文件通常承担以下职责:固定 Python 版本、安装 pyproject.toml 声明的依赖、拷贝 grok_faf_voice/ 与 examples/ 等源码,并设置默认入口命令。

与 .fafm 双 profile 协同

在 v0.3.2 发布中,voice profile 与 claude-fafm-sdk 的知识 profile 通过 .fafm 格式形成 sibling cross-link。这意味着 voice 侧的扩展与知识侧的扩展在单一文件语义下保持一致性,自定义 voice 时不需关心对方实现细节。建议在改动 custom_voices.py 时同时核对跨 profile 的引用入口,以避免单边变更破坏 sibling 关系。

运维建议

• 在修改 custom_voices.py 后,优先运行 examples/hello_custom_voice.py 进行本地冒烟验证。
• 涉及转录实现替换时,保留 transcribe.py 的入参/出参签名,以维持上层调用稳定。
• 升级至 v0.3.x 后,建议同步检查 claude-fafm-sdk 版本与 pyproject.toml 中的 cross-link 声明,确保 voice / knowledge 双 profile 同步推进(参见 Zenodo DOI 10.5281/zenodo.20348942 的 .fafm 论文描述)。

Pitfall Log / 踩坑日志

项目：Wolfe-Jam/grok-faf-voice

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/Wolfe-Jam/grok-faf-voice | host_targets=mcp_host, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/Wolfe-Jam/grok-faf-voice | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/Wolfe-Jam/grok-faf-voice | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/Wolfe-Jam/grok-faf-voice | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/Wolfe-Jam/grok-faf-voice | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/Wolfe-Jam/grok-faf-voice | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/Wolfe-Jam/grok-faf-voice | release_recency=unknown