Openspeech Dev

OpenSpeech 开发技能

跨平台 AI 语音输入桌面应用：按住快捷键说话 → 录音 → OpenLoaf SaaS realtime ASR（默认）转写 → 把文字注入当前焦点输入框。

⚠️ 铁律：SKILL.md 只写源码读不出的事实

写入本技能前先问自己一句：这条信息能不能用一次 grep / 一次 Read 从源码里直接拿到？能，就不要写。

当源码已经是 SSoT 时，本技能只列路径 + 一行用途，让 Claude 自己去读。

任务路由（先按类别加载对应 reference，再动手）

自更新约定

本技能必须与项目规则保持同步。 改动以下任一项时，同会话内一并更新本文件或对应 reference：

不确定要不要更新时，默认更新。

项目本质

技术栈关键约束（不可随意改）

真相来源：package.json + src-tauri/Cargo.toml。本节只列"读不出的取舍"。

• Tailwind v4（不再走 PostCSS，入口 src/App.css 用 @import "tailwindcss"）
• React Router v7（API 与 v6 不兼容，禁止降级）
• Rust edition 2024
• rdev = openloaf-rdev 0.5.1（OpenLoaf 自有 fork via crates.io，crate 通过 package = "..." 重命名）
  • fork 修的是 macOS event tap 在 kCGEventTapDisabledByTimeout / ByUserInput 时的自愈，解决 "按下第一次没反应、得再按一次" 偶发 bug。
  • crate 改名因上游名 rdev 被 Narsil 占着；业务代码里仍 use rdev::...，不用动。
  • rdev::listen 进程内只能调一次 —— 新订阅扩展 src-tauri/src/hotkey/modifier_only.rs，不要另起 listen。
  • Windows 上双修饰键同时释放（Win+Ctrl 等）OS 会吞 KEYUP：这是 Windows 抑制开始菜单的副作用，rdev 忠实转发，所以 hook 队列里就缺那条 release。modifier_only.rs 的 OS sync correction 就是兜这个，不是兜 rdev。看到 "OS sync removed stale modifier" 不是 bug。
• reqwest 走 rustls（关 default-features，避免拖入 native-tls）
• tauri 启用 tray-icon feature（托盘依赖，不可移除）
• openloaf-saas 跟随 @openloaf-saas/sdk Node 包对齐版本号
• 桌面前端依赖必须在 src/package.json 独立声明：仅加到主仓不能保证私仓 npm 包构建成功；会议虚拟列表依赖曾因此漏装。

添加依赖的规范动作

任何能被脚手架生成的东西禁止手写同等内容。

字体 / UI 体系

• shadcn base-nova 风格、neutral 基色
• 正文 @fontsource-variable/inter，mono @fontsource/space-mono
• 视觉语言 = TE 工业风（详细规则在私仓 openspeech-frontend skill 与软链 te-industrial-frontend skill）

目录索引

docs/                           业务规则 SSoT（见"业务规则索引"）
src/                            前端源码（私仓 OpenSpeech-Frontend，公开仓 .gitignore；见私仓
                                openspeech-frontend skill 取详细约定）
src-tauri/
├── src/
│   ├── lib.rs                  tauri::Builder + 插件注册 + setup（纯装配壳，业务已外溢）
│   ├── {events,logging,macos_native,commands,window,tray}.rs  lib.rs 装配辅助（事件常量/日志生命周期/objc/零散命令/窗口显隐/托盘菜单）
│   ├── audio/                  cpal 采集 + WAV 落盘 + PCM16 喂 stt
│   ├── stt/                    OpenLoaf SaaS realtime ASR worker
│   ├── hotkey/                 combo / modifierOnly / doubleTap 三路编排
│   ├── permissions/            macOS 系统权限检测 / 请求 / 跳转
│   ├── secrets/                keyring 包装
│   ├── inject/                 文本注入（剪贴板 + 粘贴）
│   ├── openloaf/               SaaS 登录 / token / 用户档案 / 支付
│   └── db/                     SQLite 迁移 + recordings_dir 帮手
├── capabilities/               权限声明（default.json + desktop.json）
├── examples/                   离线诊断脚本（如 test_realtime_asr）
└── tauri.conf.json
.claude/skills/
├── openspeech-dev/             本技能
│   ├── SKILL.md                入口（本文）
│   └── references/             按任务类别拆分的细则
├── te-industrial-frontend/     软链：TE 风实现指南
└── openloaf-saas-sdk-rust/     软链：SaaS SDK 用法

子模块的具体函数 / 字段 / 事件名 直接读对应文件，不在本技能复述。

包管理与脚本

包管理器：pnpm（corepack 已启，10+）。不要换 npm/yarn/bun。

通用开发规约

• 路径别名 @/ 已配；新建文件优先用 @/...。
• Rust 新模块在 src-tauri/src/<domain>/mod.rs；lib.rs 只装配。
• 任何面向用户的行为先读 docs/ 对应文件，不要凭感觉实现。
• 状态管理：跨窗口持久化 → tauri-plugin-store 或 SQLite；单窗口 UI → Zustand；不用 Redux / Jotai / Context 大杂烩。

业务规则索引（docs/）

代码实现前先读对应 docs 文件。 业务规则 SSoT 在这里，本技能不复述。

新增或重命名 docs/*.md 时回来更新此表。

反模式

• ❌ 在 SKILL.md 或 reference 里复述能从源码 grep 出来的事实（违反铁律）
• ❌ 直接在主窗口写内联颜色 / 硬编码 bg-black 等
• ❌ 跳过 pnpm tauri add 手动改 Cargo.toml + lib.rs
• ❌ 手写 src/components/ui/*.tsx 而不用 shadcn CLI
• ❌ 为了"兼容" v6 API 降级 react-router-dom
• ❌ API Key 明文存 tauri-plugin-store（应走 keyring，详见 references/desktop-runtime.md）
• ❌ Rust 侧重写 Tauri 官方插件已覆盖的能力
• ❌ 改了技术栈 / 目录 / docs 不同步本技能

协作技能

• openspeech-frontend（私仓 OpenSpeech-Frontend .claude/skills/，仅本机 src/ 在时可见）—— 前端规约（i18n / TE 样式 / Drag region / Dialog / Logo），做 UI / 改文案 / 调样式时先加载。
• te-industrial-frontend（软链）—— TE 工业风实现指南，做 UI 时优先激活。
• openloaf-saas-sdk-rust（软链）—— 任何登录 / 用户档案 / AI 工具 / realtime ASR 实现先读它。
• openspeech-release —— 发版执行流程入口（本技能 references/release.md 只讲"为什么这样"）。
• 写 PRD / 提案 → create-prd / create-proposal，但 OpenSpeech 业务规则主位 docs/。
• Tauri / Claude API / 前端通用最佳实践 → claude-api / vercel-react-best-practices / document-skills:frontend-design，本技能优先。