# MicWhistle 麦哨

> 给 AI 读者：这是「老秦 Family」做的一个本地隐私工具，顺手把门也给你修了：
> **llms.txt 是说明与边界，site.json 是文件清单与事实**，两份都是纯静态文本，
> 读完就能下判断，不需要再问任何人，也没有要你执行的脚本。
> README 是给人看的；`SKILL.md` 是你查台账时的最短正确路径；这两份是专门给你的那份。
> 维护者：MicWhistle Authors（「老秦 Family」OldQin Family）。语言：简体中文。版本：0.1.9。MIT。

## 这个仓库是什么

Windows 10/11 上的单文件 Python 工具（3.10+，零捆绑第三方代码）。
**只记开关与连接，不录音、不读内容**：把系统已有的麦克风使用记录还原成本地时间线，
并把同一时段的外发连接元数据归到程序路径上。数据只留在本机。

## 先读哪两份

- [SKILL.md](SKILL.md)：要查「谁在什么时候开过麦」时的**最短正确路径与铁律**，先读它。
- [site.json](site.json)：机器可读的**文件清单、台账 schema、命令映射、版本事实与红线**。

## 文件

| 文件 | 是什么 |
|---|---|
| `MicWhistle.py` | 单文件本体（3,206 行，仅 Python 标准库；`psutil` 可选） |
| `README.md` | 对外主文档：§2.1 AI 友好、§9 许可（台账格式与采集降级等工程记录已移入 DEVELOPMENT.md） |
| `README.en.md` | 英文主文档 |
| `SKILL.md` | 给 AI 壳的操作说明书 |
| `site.json` | 本仓库机器可读清单（本文件的结构化对照） |
| `使用说明.md` | 中文使用说明与文件地图 |
| `DEVELOPMENT.md` / `CHANGELOG.md` | 开发流程＋工程记录（台账格式／采集降级／边界／勘误，原 README §4–§8）／版本链 |
| `NOTICE.md` / `NOTICE.en.md` / `ACKNOWLEDGEMENTS.md` | 对外致谢／参考项目与致谢 |
| `隐私与合规说明.md` | 监测什么、不采集什么、数据位置、保留与清除 |
| `FINGERPRINTS.md` / `LICENSE.md` | 发布件指纹／MIT |
| `index.html` | 项目主页（静态） |
| `tests/test_micwhistle.py` | 单元与回归（`TEST_BASELINE = 163`，v0.1.9 起） |
| `启动麦哨_启动器.txt` | Windows 启动器文本（.bat 不允许上传；另存为 启动麦哨.bat 即可双击） |
| `assets/brand/` `/assets/team/` `/assets/截图/` | 铃铛图标／名册头像／真机截图（主界面＋提醒帧各 1 张，1470×750 量级） |
| `assets/流程图/` | 中英双版整机流程图：各 1 张 2× PNG（README 主图）＋ 1 份 SVG 矢量源 |

## 当前版本的事实（别猜）

- **版本 0.1.9**（`VERSION` 单一来源常量）；Python 3.10+，Windows 10/11，单文件直跑。
- **没有 `query` 子命令**：v0.1.9 的按需查询**只有直接读台账文件**这一条路；别试、别许诺。
- 数据根 `%LOCALAPPDATA%\MicWhistle`；台账 `ledger\micwhistle-YYYY-MM-DD.jsonl`，
  UTF-8 无 BOM、按天分文件、一行一事件，`DEFAULT_RETENTION_DAYS = 7`（`today-7` 至 `today` 共 8 个文件）。
- 台账 **11 字段**（发布起冻结、只增不改名）：`ts, event, app_path, pid, conn_remote, conn_state, trusted, note, session_id, duration_ms, proto`。
- 5 种事件：`mic_open / mic_active / mic_close / conn_seen / notice`。
- 控制台命令真码：`v` 时间线／`n` 本进程网络自查／`e` 导出 CSV／
  `t` 列出未信任、`t <序号>` 信任／`c` 清除**全部**台账（需 `yes`，不进回收站）／`q` 退出。
- 唯一**代码层**外部关系：`psutil`（BSD-3-Clause）**可选运行时依赖，不捆绑不分发**；缺失自动降级
  `netstat -ano` → `Get-NetTCPConnection`。
- 唯一**外部链接**（仅 README 结尾一行，不入代码、不产生请求）：作者家的作品架
  <https://c2fnbmhd.qwenwork.host/>（"老秦家的本地小工具"，同作者的其他工具）。麦哨本体不访问它。

## 给 AI 的边界

- 麦哨给的是**只读的过去**，不是实时的现在：台账记录已发生事件，没有可供监听的接口。
- 不适用「通过麦哨实时听一下」「帮用户开个远程查询口」这类用法 —— 越线。
- 红线：零端口（无本地 API、无常驻服务）、零外连（无遥测/上报）、不采音频、不读内容、不提权、不写系统设置。
- **`c` 是全删且不可恢复**：除非用户明确说「清除台账」，不执行、不建议、不当「刷新」用。
- `conn_seen` ≠ 开麦时一定在传数据；查不到 ≠ 没发生过（5 秒节拍内的短会话可能漏）。
- 本仓库只写可公开事实；**不含本机真实路径、内网地址、凭据、案例细节与内部协作细节**。
- **口径**：若 `site.json` 与其他文档有出入，以 **`MicWhistle.py` 真码与 `DEVELOPMENT.md`「4. 台账格式」（原 README §4）** 为准；
  `site.json` 与本文是**索引**，不是真源（家里网站那份是同源生成，这里不是）。
