feat: merge dev with window-recognition optimization (14 commits)

Author: Aparencia

.env.example

@@ -47,6 +47,12 @@ SUPABASE_JWT_SECRET=
 # Supabase 项目 URL（用于后端验证 JWT issuer）
 SUPABASE_URL=https://your-project-id.supabase.co
 
+# Supabase 服务端密钥（Service Role Key，仅供服务端调用，禁止暴露给前端）
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# Supabase JWT 签名算法（HS256/RS256/ES256）
+# SUPABASE_JWT_ALGORITHM=RS256
+
 # 开发者白名单（AI 网关）：逗号分隔的 Supabase user_id 或邮箱，
 # 命中的账号完全豁免平台配额（不限流/不限费用）并赋予 lifetime 最高身份，
 # 仅供开发者自测，切勿在生产环境加入普通用户。
@@ -56,6 +62,25 @@ SUPABASE_URL=https://your-project-id.supabase.co
 SYNC_SERVICE_PORT=8080
 AI_GATEWAY_PORT=8000
 
+# AI 网关预算控制（每日 token/费用上限，0=不限制）
+# BUDGET_DAILY_TOKEN_LIMIT=100000
+# BUDGET_DAILY_COST_LIMIT=10
+
+# AI 网关开发降级模式（生产环境缺密钥时拒绝启动；仅开发环境可显式开启）
+# GATEWAY_ALLOW_DEV_AUTH=false
+
+# OpenTelemetry 导出端点（可选，配置后网关上报 trace 到 OTLP Collector）
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# 付费系统（面包多，可选——未配置时付费功能禁用）
+# PAYMENT_PROVIDER=mianbaoduo
+# PAYMENT_API_KEY=your-mianbaoduo-api-key
+# PAYMENT_API_SECRET=your-mianbaoduo-api-secret
+# PAYMENT_WEBHOOK_SECRET=your-webhook-secret
+# PAYMENT_API_BASE_URL=https://api.mianbaoduo.com
+# PAYMENT_TIMEOUT_MS=5000
+# PAYMENT_RETRY_COUNT=3
+
 # --- 生产部署配置 ---
 
 # CORS 允许的前端域名（多个用逗号分隔）

.gitattributes

@@ -1 +1 @@
-*.png filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text

.github/workflows/deploy-server.yml

@@ -10,9 +10,32 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
 
+      # 部署前门禁（2026-08 审计 #11）：server 变更直接部署前先跑完整测试，
+      # 防止未验证代码上线（pr-check 只在 PR 流程生效，main 直推会绕过）
+      - name: Gate - AI Gateway tests
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Run AI Gateway tests
+        run: |
+          cd server/ai-gateway
+          pip install -r requirements.txt
+          pip install ruff pytest pytest-asyncio httpx
+          ruff check .
+          pytest tests/ -q
+      - name: Gate - Sync service tests
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+      - name: Run Sync service tests
+        run: |
+          cd server/sync-service
+          go build ./... && go vet ./... && go test ./... -count=1
+
       # 上传 server/ 源码到服务器（服务器非 git 仓库，代码由 CI 同步）
       # 注意：rm 必须为 false —— 服务器上的 .env.production 为真实生产密钥，
       # 不在仓库内（被 gitignore），删除目标目录会导致密钥永久丢失。

.github/workflows/deploy-website.yml

@@ -10,6 +10,7 @@ on:
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       # lfs: true 必需：beian.png / sponsor-qr.png 等由 Git LFS 托管（.gitattributes:
       # *.png filter=lfs），不拉取则为 131 字节指针文件，线上为坏图

.github/workflows/mobile-release.yml

@@ -0,0 +1,100 @@
+name: Release PWA (Mobile)
+
+# 由 semantic-release 创建的 v* tag 触发：构建 PWA 移动端产物并部署到
+# ECS 服务器（https://entropydecrease.com/pwa/）。与 release.yml（Electron
+# 桌面端）共用同一 v* tag——双端同版本发布、互不干扰；PR 质量验证复用
+# pr-check.yml（client job 已含 vite build 产出 PWA）。
+on:
+  push:
+    tags: ['v*']
+  # 兜底触发：semantic-release 以内置 GITHUB_TOKEN 推 tag 时 GitHub 防递归
+  # 机制不派发 push 事件（同 release.yml 注释），Release 发布事件补跑
+  release:
+    types: [published]
+  # 手动兜底：在 UI 选择对应 tag 运行，用于补发历史版本
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# 同一 tag 的多个触发源串行执行，避免重复部署竞争
+concurrency:
+  group: release-pwa-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      # lfs: true 必需：pwa-192x192.png 等由 Git LFS 托管，不拉取则为指针文件
+      - uses: actions/checkout@v4
+        with:
+          lfs: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'npm'
+          cache-dependency-path: client/package-lock.json
+      - run: cd client && npm ci
+      - run: cd client && npm run lint
+      - run: cd client && npm run test -- --run
+      # PWA 构建（子路径 /pwa/ 部署）：.env.production 已入库（git 跟踪），
+      # 生产环境变量自动注入；VITE_PWA_BASE 控制构建 base 与 manifest
+      # start_url/scope（vite.config.ts），保证子路径安装入口正确
+      - name: Build PWA (base=/pwa/)
+        env:
+          VITE_PWA_BASE: /pwa
+        run: cd client && npx vite build
+      - name: Verify PWA artifacts
+        run: |
+          cd client
+          test -f dist/index.html && echo "index.html OK"
+          test -f dist/manifest.webmanifest && echo "manifest.webmanifest OK"
+          test -f dist/sw.js && echo "sw.js OK"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pwa-dist
+          path: client/dist/
+          retention-days: 14
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: pwa-dist
+          path: pwa-dist
+      - name: Ensure PWA directory on server
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SERVER_HOST }}
+          username: ${{ secrets.SERVER_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: mkdir -p /opt/Entropydecrease/pwa
+      - name: Upload PWA to server (clean replace)
+        uses: appleboy/scp-action@v0.1.7
+        with:
+          host: ${{ secrets.SERVER_HOST }}
+          username: ${{ secrets.SERVER_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          source: pwa-dist/*
+          target: /opt/Entropydecrease/pwa
+          strip_components: 1
+          rm: true
+      # scp rm:true 重建目录导致 bind mount 失效，须重启 nginx 容器恢复
+      # （同 deploy-website.yml 模式）；顺带写入版本标记 + 验证部署
+      - name: Restart Nginx, write version and verify
+        uses: appleboy/ssh-action@v1
+        with:
+          host: ${{ secrets.SERVER_HOST }}
+          username: ${{ secrets.SERVER_USER }}
+          key: ${{ secrets.SSH_PRIVATE_KEY }}
+          script: |
+            echo "${{ github.ref_name }}" > /opt/Entropydecrease/pwa/version.txt
+            docker restart entropy-decrease-nginx
+            sleep 5
+            curl -sf https://entropydecrease.com/pwa/ | grep -q "熵减" || exit 1
+            echo "PWA deployed: ${{ github.ref_name }}"

.github/workflows/pr-check.yml

@@ -10,6 +10,7 @@ jobs:
   # ===========================================================================
   changes:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     # dorny/paths-filter 需要读取 PR 变更文件列表；Dependabot PR 的只读 token
     # 默认不含该权限，显式声明后 Dependabot PR 的路径检测才能正常工作
     permissions:
@@ -20,6 +21,7 @@ jobs:
       sync-service: ${{ steps.filter.outputs.sync-service }}
       ai-gateway: ${{ steps.filter.outputs.ai-gateway }}
       website: ${{ steps.filter.outputs.website }}
+      docs: ${{ steps.filter.outputs.docs }}
     steps:
       - uses: actions/checkout@v4
       - uses: dorny/paths-filter@v3
@@ -36,6 +38,10 @@ jobs:
               - 'server/shared/**'
             website:
               - 'website/**'
+            docs:
+              - 'docs/**'
+              - 'scripts/docs-check.mjs'
+              - '.docscheckignore'
 
   # ===========================================================================
   # Client —— React + Vite + Electron 前端
@@ -44,6 +50,7 @@ jobs:
     needs: changes
     if: needs.changes.outputs.client == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -53,20 +60,26 @@ jobs:
           cache-dependency-path: client/package-lock.json
       - run: cd client && npm ci
       - name: Lint
-        run: cd client && npm run lint
+        # --deny-warnings：2026-08 已清零全部 warning，此后新 warning 视为失败，
+        # 防止 lint 债务回潮（审计 #4）
+        run: cd client && npx oxlint --deny-warnings
       - name: Typecheck (renderer)
         # 渲染进程（React + Vite）的 TypeScript 编译检查
-        run: cd client && npx tsc --noEmit
+        run: cd client && npm run typecheck
       # Electron 主进程使用独立的 tsconfig（CommonJS / Node 目标），
       # 与渲染进程的 Vite+DOM 配置不同，需单独检查以捕获主进程类型错误
       - name: Typecheck (Electron main process)
-        run: cd client && npx tsc -p electron/tsconfig.json --noEmit
+        run: cd client && npm run typecheck:electron
       - name: Test (with coverage)
         # 启用覆盖率收集，与 vitest.config.ts 中配置的阈值配合，
         # 确保新增代码的测试覆盖不低于设定门槛
         run: cd client && npm run test -- --run --coverage
       - name: Build
         run: cd client && npm run build
+      - name: Audit (client)
+        # 供应链漏洞扫描：默认 registry 为 npmmirror 不支持 advisories API，
+        # 显式指定官方 registry（见 migration-spec §15.5）
+        run: cd client && npm audit --registry=https://registry.npmjs.org --audit-level=high
 
   # ===========================================================================
   # Server / sync-service —— Go + Gin 同步服务
@@ -75,15 +88,16 @@ jobs:
     needs: changes
     if: needs.changes.outputs.sync-service == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     defaults:
       run:
         working-directory: server/sync-service
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-go@v5
         with:
-          # Go 1.25 尚未发布，使用当前最新稳定版 1.24（截至 2026 年 8 月）
-          go-version: '1.24'
+          # 与 go.mod 的 go 1.25 指令一致（此前注释"1.25 尚未发布"已过时）
+          go-version: '1.25'
           cache-dependency-path: server/sync-service/go.sum
       - name: Lint (go vet)
         run: go vet ./...
@@ -99,6 +113,7 @@ jobs:
     needs: changes
     if: needs.changes.outputs.ai-gateway == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     defaults:
       run:
         working-directory: server/ai-gateway
@@ -125,6 +140,7 @@ jobs:
     needs: changes
     if: needs.changes.outputs.website == 'true'
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     defaults:
       run:
         working-directory: website
@@ -142,3 +158,20 @@ jobs:
         run: npx tsc --noEmit
       - name: Build
         run: npm run build
+
+  # ===========================================================================
+  # Docs —— 文档体系一致性检查（链接/索引/命名）
+  # ===========================================================================
+  docs:
+    needs: changes
+    if: needs.changes.outputs.docs == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - name: Docs check
+        # 相对链接完整性 + 索引覆盖 + 命名规范（历史快照豁免见 docs/.docscheckignore）
+        run: node scripts/docs-check.mjs

.github/workflows/release.yml

@@ -24,6 +24,7 @@ concurrency:
 jobs:
   lint-test:
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
@@ -45,6 +46,8 @@ jobs:
       matrix:
         os: [windows-latest]
     runs-on: ${{ matrix.os }}
+    # Electron 打包 + 上传 + CDN 同步：上限 90 分钟
+    timeout-minutes: 90
     steps:
       # lfs: true 必需：app-icon.png 等 PNG 由 Git LFS 托管（.gitattributes:
       # *.png filter=lfs），不拉取则仅为 131 字节指针文件，
@@ -101,6 +104,7 @@ jobs:
   release:
     needs: build
     runs-on: ubuntu-latest
+    timeout-minutes: 30
     # secrets 上下文**不可用于 if 条件**（仅限 env/with/run），否则整个
     # workflow 文件解析失败、所有触发立即 0 秒报错。
     # 故先将条件所需值注入 job 级 env，再在 step 的 if 中用 env.* 引用。

.github/workflows/version-release.yml

@@ -23,6 +23,7 @@ jobs:
   release:
     name: Semantic Release
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     # 发布提交自身携带 [skip ci] 已可被 GitHub 拦截，此处再加一层双保险，防止回环触发
     if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
     steps:
@@ -42,7 +43,8 @@ jobs:
           node-version: 20
 
       - name: Install release tooling
-        run: npm install --no-audit --no-fund
+        # npm ci：基于 lockfile 可复现安装（2026-08 审计 #12）
+        run: npm ci --no-audit --no-fund
 
       - name: Semantic Release
         env:

.gitignore

@@ -3,6 +3,8 @@ node_modules/
 vendor/
 __pycache__/
 *.pyc
+.pytest_cache/
+.ruff_cache/
 
 # Build
 dist/
@@ -47,8 +49,9 @@ Thumbs.db
 !client/.env.production
 
 # Brainstorm scratch (personal notes)
-brainstorm*.md
-ui_brainstorm.md
+# 注意：锚定根目录（/brainstorm*.md），避免误吞 docs/templates/brainstorm-template.md
+/brainstorm*.md
+/ui_brainstorm.md
 
 # Logs
 *.log
@@ -61,3 +64,12 @@ coverage/
 # Scripts temp
 scripts/.mp3tmp/
 scripts/sounds_backup_original/
+# 软著源码文档生成输出（generate_source_code_doc.ps1）
+docs/softcopy-materials/
+
+# 临时截图/审计 scratch（勿提交）
+tmp-*.png
+missing_ai_context.txt
+
+# 音效源文件备份（42 个 wav，零代码引用，勿再提交）
+client/public/sounds/_backup_original/