# https://github.com/Wolfe-Jam/grok-faf-voice 项目说明书

生成时间：2026-07-21 16:44:58 UTC

## 目录

- [项目概览与快速开始 (Overview and Quickstart)](#page-1)
- [VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)](#page-2)
- [`.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)](#page-3)
- [自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)](#page-4)

<a id='page-1'></a>

## 项目概览与快速开始 (Overview and Quickstart)

### 相关页面

相关主题：[VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)](#page-2), [`.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)](#page-3), [自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/README.md)
- [ONBOARDING.md](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/ONBOARDING.md)
- [WJTTC.md](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/WJTTC.md)
- [pyproject.toml](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/pyproject.toml)
- [.env.example](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/.env.example)
- [CHANGELOG.md](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/CHANGELOG.md)
</details>

# 项目概览与快速开始 (Overview and Quickstart)

## 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]()

推荐安装流程：
```bash
git clone https://github.com/Wolfe-Jam/grok-faf-voice.git
cd grok-faf-voice
pip install -e .
```

### 2.2 必需的环境变量

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

| 变量名 | 用途 |
|---|---|
| `XAI_API_KEY` | xAI (Grok) 接口密钥 |
| `FAFM_VOICE_PROFILE` | 默认 `.fafm` 文件路径 |

资料来源：[.env.example:1-20]()

### 2.3 第一次运行

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

## 3. 核心架构：双 Profile 联动

### 3.1 组件关系图

```mermaid
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 定义"的设计哲学。

---

<a id='page-2'></a>

## VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)

### 相关页面

相关主题：[项目概览与快速开始 (Overview and Quickstart)](#page-1), [`.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)](#page-3), [自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [grok_faf_voice/agent.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/agent.py)
- [grok_faf_voice/context.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/context.py)
- [grok_faf_voice/context_bus.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/context_bus.py)
- [grok_faf_voice/scratchpad.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/scratchpad.py)
- [grok_faf_voice/tools.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/tools.py)
- [examples/hello.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/examples/hello.py)
</details>

# VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)

## 1. 概述与设计目标

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

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

| 模块 | 文件 | 职责 |
| --- | --- | --- |
| VoiceAgent 主类 | `grok_faf_voice/agent.py` | 对外统一入口，编排语音会话生命周期 |
| 上下文 (.fafm) | `grok_faf_voice/context.py` | 加载 / 解析 / 校验 `.fafm` 文档 |
| 上下文总线 | `grok_faf_voice/context_bus.py` | 在各组件之间投递事件与增量 |
| 临时便笺 | `grok_faf_voice/scratchpad.py` | 单轮 / 多轮对话中的工作记忆 |
| 工具调用 | `grok_faf_voice/tools.py` | 函数调用与外部能力接入 |
| Hello 示例 | `examples/hello.py` | 端到端最小使用样例 |

资料来源：[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` 落盘的完整数据流：

```mermaid
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 的标准用法：

```python
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]()

---

<a id='page-3'></a>

## `.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)

### 相关页面

相关主题：[VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)](#page-2), [自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)](#page-4), [项目概览与快速开始 (Overview and Quickstart)](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [grok_faf_voice/memory.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/memory.py)
- [grok_faf_voice/ledger.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/ledger.py)
- [grok_faf_voice/_merge_models.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/_merge_models.py)
- [grok_faf_voice/__init__.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/__init__.py)
- [radiofaf.faf.example](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/radiofaf.faf.example)
- [pyproject.toml](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/pyproject.toml)
</details>

# `.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)

## 概述与设计定位

`.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` | 加载/解析/序列化 `.fafm` 文档，暴露字段访问器 |
| `ledger.py` | 维护变更日志（append-only），支撑审计与回滚 |
| `_merge_models.py` | 定义人格字段合并规则，解决多源覆盖冲突 |
| `radiofaf.faf.example` | 参考实现，演示最小可工作 `.fafm` 灵魂 |

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

```mermaid
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]()

---

<a id='page-4'></a>

## 自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)

### 相关页面

相关主题：[VoiceAgent 核心与实时语音管线 (Voice Agent Core & Realtime Pipeline)](#page-2), [`.fafm` 内存系统与本地灵魂文件 (Memory Layer & Local .fafm Souls)](#page-3), [项目概览与快速开始 (Overview and Quickstart)](#page-1)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [grok_faf_voice/custom_voices.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/custom_voices.py)
- [grok_faf_voice/utils/transcribe.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/utils/transcribe.py)
- [grok_faf_voice/utils/__init__.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/grok_faf_voice/utils/__init__.py)
- [examples/hello_custom_voice.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/examples/hello_custom_voice.py)
- [examples/hello_grok_with_etch.py](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/examples/hello_grok_with_etch.py)
- [Dockerfile](https://github.com/Wolfe-Jam/grok-faf-voice/blob/main/Dockerfile)
</details>

# 自定义语音、扩展性与部署运维 (Custom Voices, Extensibility & Deployment)

本页面向开发者说明 `grok-faf-voice` 项目在自定义语音、扩展点以及容器化部署三个维度的设计与使用方式。整体架构围绕 `.fafm` 格式(`grok-faf-voice` 语音 profile + `claude-fafm-sdk` 知识 profile)构建,目标是在保持单文件可读性的同时,允许用户以轻量方式定制 voice 模块并以 Docker 形式发布。

## 模块边界与公共接口

`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 及其在仓库中的对应实现位置:

| 扩展点类别 | 对应文件 | 用途 |
| --- | --- | --- |
| 自定义 voice | `grok_faf_voice/custom_voices.py` | 注册/切换 voice 资源 |
| 转录管线 | `grok_faf_voice/utils/transcribe.py` | 替换底层 ASR,接入第三方引擎 |

仓库的 `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 论文描述)。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: Wolfe-Jam/grok-faf-voice; human_manual_source: deepwiki_human_wiki -->