# AGENTS.md

## 项目概述

fasr 是一个工业级 Python 语音识别推理库，采用插件式流水线架构。核心包 `fasr` 提供数据结构和流水线框架，模型能力通过插件包（如 `fasr-paraformer`）以 entry_points 注册。

## 架构约定

### 核心数据流

```
Audio → AudioLoader → VoiceDetector → SpeechRecognizer → Sentencizer → Audio
         (loader)      (detector)      (recognizer)       (sentencizer)
```

- `Audio` 包含多个 `AudioChannel`，每个 channel 有 `Waveform`、`segments`（AudioSpan）、`tokens`
- 所有组件继承 `BaseComponent`，通过 `registry` 注册，通过 `AudioPipeline.add_pipe()` 组装
- 流水线各组件在独立线程中运行，通过 `AudioQueue` 传递数据

### 插件机制

- 插件包在 `pipelines/` 目录下，作为 uv workspace 成员
- 通过 `pyproject.toml` 的 `[project.entry-points.'fasr.pipelines']` 注册
- `fasr.load("name")` 通过 `importlib.metadata.entry_points` 发现并加载

### Waveform 字段注意

`AudioChannel.waveform`、`AudioSpan.waveform`、`AudioToken.waveform` 均标记 `exclude=True`，pydantic 序列化时会跳过。涉及持久化时必须单独处理 tensor 数据。

## 代码规范

### Python 风格

- 格式化：`ruff format`，检查：`ruff check --fix`
- line-length: 88，target: py310
- 导包顺序：标准库 → 第三方 → 本地项目，间隔一行

### 类型注解

- DocList 子类（AudioTokenList、AudioSpanList 等）禁止使用下标注解 `Subclass[DocType]`，直接用 `Subclass`
- 使用 `from __future__ import annotations` 延迟求值

### 新组件开发

1. 继承 `BaseComponent`，实现 `predict()` 和 `setup()`
2. 定义 `name`、`input_tags`、`output_tags`
3. 通过 `@registry.components.register("name")` 注册
4. 在插件包的 `__init__.py` 中组装流水线

### 新模型开发

1. ASR 模型继承 `ASRModel`，实现 `transcribe()` 和 `from_checkpoint()`
2. VAD 模型继承 `VADModel`，实现 `detect()` 和 `from_checkpoint()`
3. 标点模型继承 `PuncModel`，实现 `restore()` 和 `from_checkpoint()`
4. 通过对应 registry 注册（`registry.asr_models`、`registry.vad_models` 等）

## 工作流程

- 修改代码后运行 `ruff check --fix && ruff format` 确保风格一致
- Git commit 简洁突出重点
- 不要主动创建文档文件，除非明确要求
- 修改 `pyproject.toml` 依赖后运行 `uv sync` 验证
- 每次更新版本后，更新 `README.md`
