1

.claude/rules/docs.md

@@ -0,0 +1,6 @@
+---
+paths:
+  - docs/**
+---
+
+Never commit changes under `docs/` — this directory is local reference only, not shipped with code.

.claude/rules/happy-app.md

@@ -0,0 +1,36 @@
+---
+paths:
+  - packages/happy-app/**
+---
+
+## Gotchas
+
+- Never use `Alert` from React Native — always use `@/modal` instead
+- Never use Unistyles for expo-image — use plain inline styles
+- Use `useUnistyles` (NOT `useStyles`) when you need theme/runtime values outside `StyleSheet.create`
+- Custom header: `createHeader` from `@/components/navigation/Header` (not `NavigationHeader`)
+- Screen params ALWAYS in `_layout.tsx`, not in individual pages — avoids layout shifts
+- Always use expo-router API, not react-navigation API
+
+## Patterns to Follow
+
+- `useHappyAction` from `@/hooks/useHappyAction` for async operations — errors handled automatically
+- `t()` from `@/text` for ALL user-visible strings — must add to all 10 languages: `en`, `ru`, `pl`, `es`, `ca`, `it`, `pt`, `ja`, `zh-Hans`, `zh-Hant`
+- Dev/debug pages can skip i18n
+- `ItemList` for most list containers, `Avatar` for avatars, `AsyncLock` for exclusive async locks
+- `useGlobalKeyboard` for hotkeys (Web only, don't modify it)
+- Wrap pages in `memo`, store them in `sources/app/(app)/`
+- Styles at the very end of component/page files
+- Layout width constraints from `@/components/layout` on full-screen ScrollViews
+- Non-trivial hooks → dedicated file in `hooks/` folder with a comment explaining logic
+
+## Core Principles
+
+- Never show loading errors — always retry
+- No backward compatibility unless explicitly asked
+- Web is secondary platform — avoid web-specific implementations unless requested
+- Always show header on all screens
+
+## Changelog
+
+When adding features/fixes, update `/CHANGELOG.md` then run `npx tsx sources/scripts/parseChangelog.ts` to regenerate `sources/changelog/changelog.json`. Auto-parsed during `yarn ota`.

.claude/rules/happy-cli.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - packages/happy-cli/**
+---
+
+## Gotchas
+
+- ALL imports must be at the top of the file — never import mid-code
+- All debugging goes through file-based logger — never use console for debug output (interferes with agent terminal UI)
+- Dual mode architecture: interactive mode spawns CLI process (child_process.spawn, NOT node-pty), remote mode uses internal SDK (`src/claude/sdk/`)
+- Claude SDK is internal (`src/claude/sdk/`), not the `@anthropic-ai/claude-code` npm package
+
+## Patterns to Follow
+
+- Named exports only (no default exports)
+- As few `if` statements as possible — prefer better design over control flow branching
+- Don't create trivial small functions / getters / setters
+- Daemon logs default to `~/.happy/logs/` (or `$HAPPY_HOME_DIR/logs/`)

.claude/rules/happy-server.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - packages/happy-server/**
+---
+
+## Gotchas
+
+- Create Prisma migrations when schema changes — follow existing naming convention (`YYYYMMDDHHMMSS_description`). Run `yarn generate` when new types are needed
+- Avoid enums — use maps instead
+
+## Patterns to Follow
+
+- Use `inTx` for database transactions, `afterTx` to emit events after commit succeeds
+- Don't run non-transactional things (like file uploads) inside transactions
+- Use `eventRouter.emitUpdate()` for persistent events, `emitEphemeral()` for transient
+- Use `privacyKit.decodeBase64` / `privacyKit.encodeBase64` from `privacy-kit` — never use Buffer
+- DB operation files: dedicated file in relevant `@/app/` subfolder, prefix with entity then action (e.g. `friendAdd`)
+- After writing an action, add a documentation comment explaining the logic; keep it in sync
+- All operations must be idempotent — clients may retry automatically
+- Don't return values from action functions "just in case" — only essential returns
+- Don't add logging unless asked
+- Always use GitHub usernames

.claude/skills/deploy-cli.md

@@ -0,0 +1,54 @@
+---
+name: deploy-cli
+description: 构建并全局安装 happy-next-cli，重启 daemon
+---
+
+# CLI 工具部署
+
+构建 happy-cli 包，全局安装，并重启 daemon。
+
+## 执行步骤
+
+逐步执行 `deploy/build-cli.sh` 的内容，提供进度反馈：
+
+### 步骤 1：清理旧构建产物
+
+```bash
+cd /home/coder/workspaces/happy/packages/happy-cli
+rm -f happy-next-cli-*.tgz
+```
+
+### 步骤 2：构建 CLI
+
+```bash
+cd /home/coder/workspaces/happy/packages/happy-cli
+npm run build
+```
+
+完成后反馈：CLI 构建成功
+
+### 步骤 3：打包并全局安装
+
+```bash
+cd /home/coder/workspaces/happy/packages/happy-cli
+TARBALL=$(npm pack)
+npm install -g "./$TARBALL"
+```
+
+完成后反馈：已全局安装，展示安装的包名和版本
+
+### 步骤 4：重启 daemon
+
+```bash
+happy daemon stop && happy daemon start
+```
+
+完成后反馈：daemon 已重启
+
+## 返回格式
+
+向用户展示：
+
+- **构建结果**: 成功/失败
+- **安装包**: 包名和版本
+- **Daemon 状态**: 重启结果

.claude/skills/deploy-server.md

@@ -0,0 +1,75 @@
+---
+name: deploy-server
+description: 部署主服务（server + webapp + voice），包含前置检查和构建进度反馈
+---
+
+# 主服务部署
+
+构建并部署 happy-server、happy-app（webapp）、happy-voice 三个 Docker 镜像，然后用 docker compose 拉起所有服务。
+
+## 前置检查
+
+部署前必须执行以下检查，任一不通过则**暂停并提示用户**：
+
+1. **未提交更改检查**：运行 `git status --porcelain`，如果有未提交的更改，警告用户 `git reset --hard origin/dev` 会丢失这些更改，询问是否继续
+2. **分支状态检查**：运行 `git fetch origin && git log HEAD..origin/dev --oneline`，展示即将拉取的新提交，让用户确认
+3. **Docker 可用性检查**：运行 `docker info`，确认 Docker daemon 正在运行
+
+## 执行步骤
+
+通过逐步执行 `deploy/build-server-web-voice-up.sh` 的内容来提供进度反馈，而不是直接运行整个脚本：
+
+### 步骤 1：同步代码
+
+```bash
+cd /home/coder/workspaces/happy
+git fetch origin
+git reset --hard origin/dev
+```
+
+完成后反馈：代码已同步到 origin/dev 最新提交 `<commit hash>`
+
+### 步骤 2：构建 happy-server 镜像
+
+```bash
+cd /home/coder/workspaces/happy
+docker build -f Dockerfile.server -t happy-server:latest .
+```
+
+完成后反馈：happy-server 镜像构建成功
+
+### 步骤 3：构建 happy-app（webapp）镜像
+
+```bash
+cd /home/coder/workspaces/happy
+docker build -f Dockerfile.webapp -t happy-app:latest .
+```
+
+完成后反馈：happy-app 镜像构建成功
+
+### 步骤 4：构建 happy-voice 镜像
+
+```bash
+cd /home/coder/workspaces/happy/packages/happy-voice
+docker build -f Dockerfile -t happy-voice:latest .
+```
+
+完成后反馈：happy-voice 镜像构建成功
+
+### 步骤 5：启动服务
+
+```bash
+cd /home/coder/workspaces/happy/deploy
+docker compose up -d
+```
+
+完成后反馈：所有服务已启动，运行 `docker compose ps` 展示服务状态
+
+## 返回格式
+
+向用户展示部署摘要：
+
+- **同步提交**: `<commit hash> <message>`
+- **镜像构建**: server / webapp / voice 各自的构建结果
+- **服务状态**: docker compose ps 输出
+- **耗时**: 总部署时间

.claude/skills/expo-coder.md

@@ -0,0 +1,33 @@
+---
+name: expo-coder
+description: 通过 code-server 端口转发启动 Expo 开发模式，无需 ngrok tunnel
+---
+
+# Expo Code-Server 开发启动器
+
+通过 code-server 内置端口转发启动 happy-app，速度比 ngrok tunnel 快。
+
+## 执行步骤
+
+1. 先结束已有的 Expo/Metro 进程
+2. 启动 Expo 并设置 `EXPO_PACKAGER_PROXY_URL` 为 code-server 代理地址
+3. 返回连接信息给用户
+
+## 操作流程
+
+```bash
+# 1. 清理旧进程
+pkill -f "expo start" 2>/dev/null
+pkill -f "metro" 2>/dev/null
+sleep 1
+
+# 2. 启动 Expo（通过 code-server 端口转发）
+EXPO_PACKAGER_PROXY_URL=https://8081--main--dootask--kuaifan.coder.hitosea.com yarn workspace happy-app start
+```
+
+## 返回格式
+
+向用户展示：
+
+- **Code-Server URL**: `https://8081--main--dootask--kuaifan.coder.hitosea.com`
+- **提示**: 在 Expo Go 中手动输入上面的 URL 连接

.claude/skills/expo-tunnel.md

@@ -0,0 +1,61 @@
+---
+name: expo-tunnel
+description: 启动 Expo tunnel 开发模式，返回公网 URL 供手机连接
+---
+
+# Expo Tunnel 开发启动器
+
+启动 happy-app 的 Expo tunnel 模式，获取公网 URL。
+
+## 执行步骤
+
+1. 先结束已有的 Expo/Metro 进程
+2. 后台启动 `yarn workspace happy-app start --tunnel`
+3. 等待 tunnel 连接成功（轮询 ngrok API）
+4. 从 ngrok API 获取公网 URL
+5. 保存 URL 到 `.expo-tunnel` 文件
+6. 返回连接信息给用户
+
+## 操作流程
+
+```bash
+# 1. 清理旧进程
+pkill -f "expo start" 2>/dev/null
+pkill -f "metro" 2>/dev/null
+sleep 1
+
+# 2. 后台启动 tunnel
+yarn workspace happy-app start --tunnel &
+
+# 3. 轮询等待 tunnel 就绪（最多 60 秒）
+for i in {1..12}; do
+  URL=$(curl -s http://localhost:4040/api/tunnels 2>/dev/null | jq -r '.tunnels[] | select(.proto=="https") | .public_url' 2>/dev/null)
+  if [ -n "$URL" ] && [ "$URL" != "null" ]; then
+    break
+  fi
+  sleep 5
+done
+
+# 4. 保存到文件
+echo "$URL" > .expo-tunnel
+
+# 5. 显示结果
+cat .expo-tunnel
+```
+
+## 输出文件
+
+URL 会保存到项目根目录的 `.expo-tunnel` 文件，方便随时查看：
+
+```bash
+cat .expo-tunnel
+```
+
+## 返回格式
+
+向用户展示：
+
+- **Tunnel URL**: `https://xxx.exp.direct`
+- **Expo Go 连接**: `exp://xxx.exp.direct`
+- **文件位置**: `.expo-tunnel`
+- **提示**: tunnel 模式热更新稍慢，摇一摇手机打开开发者菜单