1 files changed, 83 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..95a13f7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# Mic Clipper
+
+一个面向 Linux 桌面的本机常驻“说话片段录音器”。它持续从 PipeWire/Pulse 的动态默认麦克风输入读取音频，仅在本地 Silero VAD 判为语音时才创建文件。
+
+## 行为与隐私
+
+- 16 kHz 单声道输入；每 32 ms（512 个采样）运行一次本地 ONNX VAD。
+- 语音开始时带 0.5 秒内存前置音频；持续静音 1.5 秒后关闭片段。
+- 使用 Ogg/Opus、`libopus`、24 kbps、语音优化编码，保存为 `*.opus`。
+- 文件写入 `~/Documents/Mic Clips/YYYY-MM-DD/HH-MM-SS.opus`；跨午夜时目录按片段开始日期确定。
+- 静音不会创建文件。音频只在内存中保留有限的前置缓冲；不调用 ASR、不上传、不保存转写文本，也不自动删除旧录音。
+- 单段最长 10 分钟。连续说话会无缝滚动为下一段，避免内存无限增长；相邻段会在边界处保持音频连续。
+- 目录权限为 `0700`，录音文件为 `0600`。日志仅写设备/编码器故障与重试信息，不写音频或文本。
+
+存储量约为 `24 kbit/s / 8 = 3 kB/s`，即每小时约 10.8 MB、每天连续录音约 259 MB。实际仅保存语音片段，通常会低于这个上限。
+
+## 运行时依赖
+
+目标解释器必须是：
+
+```text
+/home/somhairle/.hermes/hermes-agent/venv/bin/python
+```
+
+该解释器需要已有 `numpy` 与 `onnxruntime`。系统需要带 `pulse` 输入和 `libopus` 编码器的 `ffmpeg`。本项目不执行 `pip install`、模型下载或任何联网操作。
+
+部署前必须确认项目包内存在：
+
+```text
+src/mic_clipper/assets/silero_vad_v6.onnx
+```
+
+该权重应从当前机器已验证的 `faster-whisper` 1.2.1 本地资源复制而来，归属和 MIT 许可说明见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。当前开发代码为便于本机测试会回退读取该已预置的本地资源；它不会下载模型。该回退不是自包含部署方案，审阅/部署前必须把权重复制进项目包。
+
+## 安装与服务
+
+以下命令均从项目根目录执行。先用 dry-run 审阅将执行的 systemd 命令；它不会写入家目录。
+
+```bash
+RUNTIME=/home/somhairle/.hermes/hermes-agent/venv/bin/python
+PROJECT=/home/somhairle/projects/mic-clipper
+PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service install --dry-run
+```
+
+经独立审阅后，安装并立即启用用户服务：
+
+```bash
+PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service install
+```
+
+安装器仅写 `~/.config/systemd/user/mic-clipper.service`，然后执行 `daemon-reload` 与 `enable --now`。服务 `Wants`/`After` PipeWire、WirePlumber 与 pipewire-pulse，应用本身会在默认麦克风暂不可用或设备切换时以 1、2、4...60 秒退避重试。`Restart=on-failure` 只处理异常退出，手动 `stop` 不会立即拉起服务。
+
+## 日常命令
+
+```bash
+# 服务状态
+PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service status
+
+# 手动启动、停止、重启
+systemctl --user start mic-clipper.service
+systemctl --user stop mic-clipper.service
+systemctl --user restart mic-clipper.service
+
+# 前台运行（便于排障；Ctrl-C 正常收尾当前编码器）
+PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli run
+
+# 卸载 unit，不删除任何录音
+PYTHONPATH="$PROJECT/src" "$RUNTIME" -m mic_clipper.cli service uninstall
+```
+
+## 故障排查
+
+```bash
+# 查看不含音频内容的服务日志
+journalctl --user -u mic-clipper.service -f
+
+# 确认 PipeWire/Pulse 默认源与 ffmpeg 能力
+pactl get-default-source
+ffmpeg -hide_banner -h demuxer=pulse
+ffmpeg -hide_banner -h encoder=libopus
+```
+
+若日志显示 Pulse 输入退出，确认 `pipewire.service`、`wireplumber.service` 和 `pipewire-pulse.service` 正常运行；应用会自行重试。若 VAD 报模型缺失，先恢复上文列出的包内 ONNX 文件，不能用联网下载替代。