merge master

.github/workflows/sync-upstream-main.yml

@@ -0,0 +1,197 @@
+name: Sync upstream main
+
+on:
+  schedule:
+    # 05:00 Asia/Shanghai daily.
+    - cron: "0 21 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: sync-upstream-main
+  cancel-in-progress: false
+
+env:
+  UPSTREAM_REPO: zts212653/clowder-ai
+  SYNC_BRANCH: sync/upstream-main-to-develop
+
+jobs:
+  sync:
+    name: Sync upstream/main into main and develop
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout fork
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.UPSTREAM_SYNC_TOKEN || github.token }}
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: pnpm
+
+      - name: Configure git
+        run: |
+          set -euo pipefail
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Fetch refs
+        run: |
+          set -euo pipefail
+          git remote add upstream "https://github.com/${UPSTREAM_REPO}.git"
+          git fetch --prune origin \
+            +refs/heads/main:refs/remotes/origin/main \
+            +refs/heads/develop:refs/remotes/origin/develop
+          git fetch --prune upstream \
+            +refs/heads/main:refs/remotes/upstream/main
+
+      - name: Merge upstream into main
+        id: main
+        run: |
+          set -euo pipefail
+          git switch -C main origin/main
+          git reset --hard origin/main
+
+          before="$(git rev-parse HEAD)"
+          git merge --no-edit upstream/main
+          after="$(git rev-parse HEAD)"
+
+          if [ "$before" = "$after" ]; then
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Install dependencies
+        if: steps.main.outputs.changed == 'true'
+        run: pnpm install --frozen-lockfile
+
+      - name: Gate merged main
+        if: steps.main.outputs.changed == 'true'
+        # Runs the same gate the upstream CI workflow enforces, but expanded
+        # explicitly so we can skip `pnpm check:capability-tips`. That check is
+        # an incremental guard (each PR adding a new feature doc must also add
+        # a matching capability tip), gated on `git diff origin/main...HEAD`.
+        # In this batch-merge sync context, that diff includes every upstream
+        # commit's file changes, so every newly synced feature/skill file is
+        # treated as "missing" — which is the wrong semantics for sync. The
+        # incremental check still runs on regular PRs against fork develop,
+        # where the diff range is correct.
+        #
+        # GIT_* env vars mirror upstream ci.yml's Test (Public) job (added in
+        # upstream PR #994). F208 execute-apply tests spawn `git commit` inside
+        # scripts/with-test-home.sh sandbox, which switches HOME and drops the
+        # workflow's `git config` settings — env vars survive that switch.
+        env:
+          GIT_AUTHOR_NAME: CI Runner
+          GIT_AUTHOR_EMAIL: ci@clowder-ai.dev
+          GIT_COMMITTER_NAME: CI Runner
+          GIT_COMMITTER_EMAIL: ci@clowder-ai.dev
+        run: |
+          set -euo pipefail
+          pnpm biome check . --diagnostic-level=error
+          pnpm check:features
+          pnpm check:sop-definitions
+          pnpm check:skills:manifest
+          pnpm check:skills:surfaces
+          pnpm check:env-ports
+          pnpm check:env-registry
+          pnpm check:env-example
+          pnpm check:start-profile-isolation
+          pnpm check:pre-merge-gate
+          pnpm check:guides
+          pnpm check:followup-tails
+          pnpm check:scripts-ascii-only
+          pnpm --filter @cat-cafe/shared build
+          pnpm --filter @cat-cafe/api build
+          pnpm --filter @cat-cafe/web build
+          pnpm --filter @cat-cafe/api run test:public
+          bash scripts/check-dir-size.sh
+
+      - name: Push main
+        if: steps.main.outputs.changed == 'true'
+        run: git push origin HEAD:main
+
+      - name: Prepare develop sync branch
+        id: develop
+        run: |
+          set -euo pipefail
+          git switch -C "$SYNC_BRANCH" origin/develop
+
+          if git merge-base --is-ancestor main HEAD; then
+            echo "needs_pr=false" >> "$GITHUB_OUTPUT"
+            echo "push_branch=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          git merge --no-edit main
+
+          if git diff --quiet origin/develop HEAD; then
+            echo "needs_pr=false" >> "$GITHUB_OUTPUT"
+            echo "push_branch=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          echo "needs_pr=true" >> "$GITHUB_OUTPUT"
+
+          remote_ref="refs/remotes/origin/${SYNC_BRANCH}"
+          if git ls-remote --exit-code --heads origin "$SYNC_BRANCH" >/dev/null 2>&1; then
+            git fetch origin "+refs/heads/${SYNC_BRANCH}:${remote_ref}"
+            if git diff --quiet "$remote_ref" HEAD; then
+              echo "push_branch=false" >> "$GITHUB_OUTPUT"
+            else
+              echo "push_branch=true" >> "$GITHUB_OUTPUT"
+            fi
+          else
+            echo "push_branch=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Push develop sync branch
+        if: steps.develop.outputs.needs_pr == 'true' && steps.develop.outputs.push_branch == 'true'
+        run: git push --force-with-lease origin HEAD:refs/heads/${SYNC_BRANCH}
+
+      - name: Create or update develop PR
+        if: steps.develop.outputs.needs_pr == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.UPSTREAM_SYNC_TOKEN || github.token }}
+        run: |
+          set -euo pipefail
+          body="$(cat <<'BODY'
+          Automated daily sync from `main` into `develop`.
+
+          This PR is created after the scheduled upstream sync workflow gates the merged `main` branch.
+          BODY
+          )"
+
+          pr_number="$(
+            gh pr list \
+              --repo "$GITHUB_REPOSITORY" \
+              --head "$SYNC_BRANCH" \
+              --base develop \
+              --state open \
+              --json number \
+              --jq '.[0].number // empty'
+          )"
+
+          if [ -n "$pr_number" ]; then
+            gh pr edit "$pr_number" \
+              --repo "$GITHUB_REPOSITORY" \
+              --title "sync: main to develop" \
+              --body "$body"
+          else
+            gh pr create \
+              --repo "$GITHUB_REPOSITORY" \
+              --base develop \
+              --head "$SYNC_BRANCH" \
+              --title "sync: main to develop" \
+              --body "$body"
+          fi

.gitignore

@@ -149,6 +149,7 @@ assets/prototypes/
 desktop/node_modules/
 desktop-dist/
 bundled/
+native/ble-helper/macos/.build/
 docs/bug-report/werewolf-investigation/poster-screenshot.png
 .worktrees/
 .review-worktrees/

cat-cafe-skills/open-source-teardown/refs/teardown-method.md

@@ -39,6 +39,123 @@ gh issue list --limit 50 --search "{keyword} sort:reactions-+1-desc" --json numb
 gh issue list --limit 50 --search "bug OR enhancement" --json number,title,labels,reactions,state
 ```
 
+## GitNexus 加速：Step 1 架构地图
+
+GitNexus 是本地代码知识图谱工具（基于 LadybugDB），可以**把"手工 rg/find 几十次画架构图"加速到几次 CLI 查询**。仅用于 Step 1 架构地图绘制；Step 2 明星特性追链路、Step 3 算法剥皮、Step 4 反馈链 **仍需人工读源码**——图谱是"地形图"，不是"质量审计"。
+
+### 何时启用 / 不启用
+
+| 启用 GitNexus | 不启用 |
+|---|---|
+| 仓库 ≥500 个源文件 | <500 文件直接 `rg` / `find` 更快 |
+| Python / JS / TS / Go / Rust / Java / C# 等主流语言 | 非主流语言 / 二进制项目 / 配置仓 |
+| 需要"被引用最多的 hub 节点 / 调用链路 / 影响面" | 只需要看 ls 顶层结构 |
+| 不想读 README 就想知道入口在哪 | 已经知道入口 |
+
+### 5 分钟 setup（一次性，全局）
+
+```bash
+# 装包（npm 11.x 用 pnpm，npx 对 native 依赖有 bug）
+npm install -g gitnexus
+# 或：pnpm install -g gitnexus
+
+# C++ 编译报错时跳过可选 grammar
+GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 npm install -g gitnexus
+
+# 验证机器能力（图存储/全文搜索/向量索引应该都 available）
+gitnexus doctor
+```
+
+### 单次拆解流程
+
+```bash
+# 1. 准备目录（不污染主仓库）
+mkdir -p ~/workspace/teardown && cd ~/workspace/teardown
+
+# 2. clone：用显式 HTTPS URL，绕过代理 SSH fakeip 问题（见 LL-077）
+# ⚠️ 不要写 `gh repo clone {owner}/{repo}` —— 当用户配过 `gh config set git_protocol ssh` 或
+#   `gh auth login --git-protocol ssh` 时，gh 会回退到 SSH，还是撞 fakeip
+gh repo clone https://github.com/{owner}/{repo}.git
+# 或纯 git：
+# git clone https://github.com/{owner}/{repo}.git
+cd {repo}
+
+# 3. 索引（中等项目 1.5k 文件实测 13 秒）
+#
+# ⚠️ 必须用 --index-only！裸 `gitnexus analyze` 不是 read-only：会注入 AGENTS.md / CLAUDE.md
+#    section + 在 .claude/skills/gitnexus/ 下安装 6 个 gitnexus 自带 skill（refactoring / debugging /
+#    exploring / cli / impact-analysis / guide）。这些注入会污染审计目标——后续 `rg / find`
+#    收集"上游真实产物"的证据时会把 gitnexus 自己的注入误当成项目自带，破坏拆解准确性。
+gitnexus analyze --index-only
+# 或单独跳过部分注入：--skip-agents-md / --skip-skills（细粒度组合）
+# warning "FTS extension unavailable; continuing without FTS" 可忽略——影响关键词排序，不影响图查询
+
+# 4. 看索引规模（决定后续查询深度）
+gitnexus list  # 看 nodes / edges / clusters / processes 数量
+```
+
+### Step 1 架构地图查询模板（按顺序跑）
+
+```bash
+# A. 找所有 main 入口（项目骨架的第一信号）
+gitnexus query "main entry point CLI startup"
+
+# B. 拿到候选 uid 后，看具体入口的 360 度（调用/被调用/进程）
+gitnexus context "Function:{path}:{name}"
+# 注意：name 单独传会触发 ambiguous（如 "main" 可能 20 个候选）
+# → 必须用完整 uid 精确指定
+
+# C. 按业务关键词探流程（query 自动识别 process）
+gitnexus query "order placement live trading execution"
+gitnexus query "agent loop iteration tool execution"
+gitnexus query "data ingest pipeline preprocessing"
+
+# D. 影响面分析（修改某符号会波及谁）
+gitnexus impact "Function:{path}:{name}"
+
+# E. 调用链路径（A 怎么调到 B）
+gitnexus trace "{from-uid}" "{to-uid}"
+
+# F. 文件系统补充（gitnexus 不索引 README / CHANGELOG / YAML preset）
+ls -1 src/ && head -80 README.md CHANGELOG.md
+ls -1 src/{interesting-module}/  # YAML / config / preset 列表
+```
+
+### Cypher 查询的实战注意
+
+GitNexus 的 LadybugDB 不是完整 Cypher 方言 — **不要照搬 Neo4j 语法**：
+
+| 失败模式 | 修正 |
+|---|---|
+| `Cannot find property kind for n` | 不要假设属性名，先 `gitnexus context` 看返回 JSON 的字段名 |
+| `function SPLIT does not exist` | 用字符串前缀匹配代替 `split()` |
+| `Cannot find property summary for p` | 同上，跑前 `query` 看属性形态 |
+
+**实用 pattern**：复杂统计能用 `gitnexus query` + 文件系统 `ls / find` 完成的，**别上 cypher**。
+
+### 收尾选项
+
+```bash
+# 留着索引继续问深的（占盘小，安全）
+# 不用操作
+
+# 完全撤掉
+gitnexus clean              # 删当前 repo 的 .gitnexus/
+rm -rf ~/workspace/teardown/{repo}
+# 全局卸载（不推荐，除非确定不再用）
+npm uninstall -g gitnexus
+```
+
+### 局限提醒
+
+GitNexus 索引的是**代码符号关系**，不索引：
+- README / CHANGELOG / SECURITY.md / LICENSE（业务定位、风险声明、license 都得人读）
+- YAML 配置 / preset / 数据文件（关键业务逻辑常在配置里）
+- 注释（设计意图常在注释）
+- 跨语言桥接（部分支持，但不可全信）
+
+→ Step 2 明星特性追链路时，gitnexus 给你 "这个 claim 关联到哪些代码"，**但你仍要 Read 源文件**判断 claim 是否成立（见 SKILL.md "硬规则"：LLM judge 不是算法）。
+
 ## Algorithm Peel Table
 
 | Mechanism | Input | Output | Type | Code path | Mutates future behavior? |