feat(product): unify interactive capability control

.github/workflows/ci.yml

@@ -355,6 +355,9 @@ jobs:
       - name: Check repository hygiene
         run: pnpm run check:repo-hygiene
 
+      - name: Validate interactive capability contract
+        run: pnpm run capabilities:check && pnpm run capabilities:test && pnpm run website:test && pnpm run website:build
+
       - name: Check core boundaries
         run: node --test scripts/check-core-boundaries.test.mjs
 

deploy/openbitfun-host/README.md

@@ -28,6 +28,7 @@ clone、`crontab` 整表安装、市场 first-install 或空 volume 的 `deploy.
 | 产品 | 公网 | 源站 | 仓库内入口 |
 | --- | --- | --- | --- |
 | 官网 + 下载页 | `https://openbitfun.com/` 、`/download` | Nginx → `BitFun-Website/dist` | 本文「官网」 |
+| BitFun Playbook | `https://playbook.openbitfun.com/` | Nginx → `/srv/bitfun-playbook/current` | 本文「BitFun Playbook」 |
 | Release 镜像 | `https://openbitfun.com/release/` | cron → `/srv/bitfun-release` | 本文「Release 镜像」；脚本在 `scripts/openbitfun-release-sync.sh` |
 | Relay | `https://remote.openbit.fun/relay` | `bitfun-relay:9700` | `src/apps/relay-server/README.md` + 本文 Nginx |
 | MiniApp 市场 | `https://market.openbitfun.com/miniapp/` | `127.0.0.1:9710` | [../miniapp-market/README.md](../miniapp-market/README.md) |
@@ -45,6 +46,7 @@ clone、`crontab` 整表安装、市场 first-install 或空 volume 的 `deploy.
 | `/root/repos/BitFun` | BitFun checkout。Relay 静态页和同步脚本从这里读 |
 | `/root/repos/BitFun-Website` | 官网独立仓库 `GCWing/BitFun-Website` |
 | `/srv/bitfun-release` | GitHub Release 镜像（禁止放进 Website `dist/`） |
+| `/srv/bitfun-playbook` | Playbook 的不可变静态版本与 `current` 软链接 |
 | `/srv/bitfun-miniapp-market` | MiniApp 专用 checkout / 数据 / 备份 |
 | `/srv/bitfun-skin-market` | Skin 专用 checkout / 数据 / 备份 |
 | `/etc/bitfun-miniapp-market/market.env` | MiniApp secrets，`root:root` `0600` |
@@ -284,6 +286,50 @@ curl -fsS -o /dev/null -w "%{http_code}\n" \
 
 更新官网：在 Website 仓库拉代码后只跑 `npm run build`，不要动 `/srv/bitfun-release`。
 
+### 5.1 BitFun Playbook
+
+Playbook 源码在 BitFun 仓库的 `website/`。功能与设置的唯一人工维护数据源是
+`src/shared/interactive-capabilities/catalog.json`；网站只读取由它生成的
+`docs/interactive-capabilities/capabilities.json`。构建与上传从开发机执行；源站只保存
+不可变静态版本，不需要 Node 运行时。
+
+```bash
+pnpm run capabilities:check
+pnpm run capabilities:test
+pnpm run website:test
+pnpm run website:build
+PLAYBOOK_RELEASE="$(node -e 'const r=require("./website/dist/release.json");process.stdout.write(r.releaseId)')"
+PLAYBOOK_SAMPLE_ID="$(node -e 'const c=require("./docs/interactive-capabilities/capabilities.json");process.stdout.write(c.capabilities[0].id)')"
+test -n "$PLAYBOOK_RELEASE"
+test -n "$PLAYBOOK_SAMPLE_ID"
+ssh lwb "install -d -m 0755 /srv/bitfun-playbook/releases/$PLAYBOOK_RELEASE"
+rsync -a --delete website/dist/ \
+  "lwb:/srv/bitfun-playbook/releases/$PLAYBOOK_RELEASE/"
+rsync -a deploy/openbitfun-host/nginx-playbook.openbitfun.com.conf \
+  lwb:/tmp/nginx-playbook.openbitfun.com.conf
+ssh lwb "set -eu
+install -m 0644 /tmp/nginx-playbook.openbitfun.com.conf \
+  /etc/nginx/sites-available/playbook.openbitfun.com
+ln -sfn /srv/bitfun-playbook/releases/$PLAYBOOK_RELEASE \
+  /srv/bitfun-playbook/current
+ln -sfn /etc/nginx/sites-available/playbook.openbitfun.com \
+  /etc/nginx/sites-enabled/playbook.openbitfun.com
+nginx -t
+systemctl reload nginx
+curl --retry 5 --retry-delay 1 --retry-all-errors -fsS -o /dev/null \
+  -H 'Host: playbook.openbitfun.com' http://127.0.0.1/
+curl --retry 5 --retry-delay 1 --retry-all-errors -fsS -o /dev/null \
+  -H 'Host: playbook.openbitfun.com' \
+  http://127.0.0.1/capabilities/$PLAYBOOK_SAMPLE_ID/
+curl --retry 5 --retry-delay 1 --retry-all-errors -fsS -o /dev/null \
+  -H 'Host: playbook.openbitfun.com' \
+  http://127.0.0.1/data/capabilities.json"
+```
+
+`systemctl reload` 返回时旧 worker 可能仍短暂接请求，所以源站验收必须带重试。
+最后通过公网检查首页、任一详情页和 `/data/capabilities.json`；若源站 Host 检查为 200、
+公网仍失败，应在云 WAF / DNS 增加该主机名，源站不要自行配置 443。
+
 ### 6. Relay
 
 必须先恢复两个 volume，再启动容器。先跑 `deploy.sh` 会建空卷，账号、同步和
@@ -413,6 +459,11 @@ install -m 0644 \
   /root/repos/BitFun/deploy/openbitfun-host/nginx-openbit.fun.conf \
   /etc/nginx/sites-available/openbit.fun
 ln -sfn /etc/nginx/sites-available/openbit.fun /etc/nginx/sites-enabled/openbit.fun
+install -m 0644 \
+  /root/repos/BitFun/deploy/openbitfun-host/nginx-playbook.openbitfun.com.conf \
+  /etc/nginx/sites-available/playbook.openbitfun.com
+ln -sfn /etc/nginx/sites-available/playbook.openbitfun.com \
+  /etc/nginx/sites-enabled/playbook.openbitfun.com
 install -m 0644 \
   /root/repos/BitFun/deploy/openbitfun-host/nginx-remote.openbit.fun.conf \
   /etc/nginx/sites-available/remote.openbit.fun
@@ -482,6 +533,7 @@ docker exec bitfun-relay /app/relay-admin --db /app/data/bitfun_relay.db list-us
 | 更新 Relay | 源码更新后 `cd src/apps/relay-server && BITFUN_MIRROR=auto bash deploy.sh`。账号 volume 会留下。 |
 | 更新 Release 镜像脚本 | 只改仓库里的 `scripts/openbitfun-release-sync.sh`。cron 已经跑这份文件。 |
 | 更新官网 | 在 `BitFun-Website` 拉代码，`source ~/.nvm/nvm.sh && nvm use 20.20.2 && npm run build`。 |
+| 更新 Playbook | 在开发机校验能力契约并运行 `pnpm run website:build`，再按「BitFun Playbook」使用 `dist/release.json` 的版本目录上传和切换 `current`。 |
 | 更新市场 | 只用对应市场手册。 |
 
 更新 BitFun 源码**不会**自动更新官网、New API 或市场容器。

deploy/openbitfun-host/nginx-playbook.openbitfun.com.conf

@@ -0,0 +1,31 @@
+server {
+    listen 80;
+    listen [::]:80;
+
+    server_name playbook.openbitfun.com;
+
+    root /srv/bitfun-playbook/current;
+    index index.html;
+
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header X-Frame-Options "SAMEORIGIN" always;
+
+    location / {
+        try_files $uri/index.html $uri =404;
+    }
+
+    location = /data/capabilities.json {
+        expires 5m;
+        add_header Cache-Control "public, max-age=300";
+    }
+
+    location ~* \.(js|css|png|ico)$ {
+        expires 1h;
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    gzip on;
+    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;
+    gzip_min_length 1024;
+}

docs/interactive-capabilities/README.md

@@ -0,0 +1,46 @@
+<!-- generated by scripts/generate-interactive-capabilities.mjs; do not edit -->
+# BitFun 功能与设置目录 / BitFun Features & Settings
+
+BitFun Playbook 当前包含 **22 个功能**和 **16 个设置页**，共 **38 个**用户可理解的条目、**297 项**有源码证据的子能力。每个条目有独立 Markdown，并直接服务于说明书网站、BitFun 全局搜索和 `BitFunControl` Agent 工具。
+
+BitFun Playbook currently contains **22 features**, **16 settings pages**, and **297** source-backed sub-capabilities across **38** user-facing entries. Every entry has its own Markdown page and directly powers the website, in-app global search, and the `BitFunControl` agent tool.
+
+## 唯一事实源 / Single source of truth
+
+- 手工维护的唯一语义目录：`src/shared/interactive-capabilities/catalog.json`
+- 生成的公开目录：`docs/interactive-capabilities/capabilities.json`
+- 生成的前端运行目录：`src/web-ui/src/app/global-search/generated/interactive-capabilities.json`
+- 生成的底层审计表：`docs/interactive-capabilities/technical/tauri-command-map.json`
+- 生成的可见交互审计表：`docs/interactive-capabilities/technical/ui-interaction-inventory.json`
+
+说明书、网站、搜索和 Agent 只看“功能 + 设置 + 子能力”。每项子能力都必须引用已注册 Tauri Command 或可解析的源码标记；这些证据不会进入公开目录。当前 **692** 个 Tauri 命令，以及 **370** 个产品交互源码文件中的 **4441** 个交互候选，只用于实现覆盖审计。
+
+Docs, website, search, and agents see only features, settings, and documented sub-capabilities. Every sub-capability must reference a registered Tauri command or a resolvable source marker; evidence is stripped from public projections. The **692** Tauri commands and **4441** interaction candidates across **370** product UI source files remain implementation-audit evidence only.
+
+## 控制边界 / Control boundary
+
+- 每个功能或设置都有可执行的产品入口；存在多视图的设置页还必须把每个视图映射到至少一个子能力，搜索和 Agent 可携带子能力 ID 精确跳转。
+- 简单、稳定且适合自动化的行为才声明为类型化 `operations` 或 `options`。复杂流程由 Agent 打开对应界面交给用户继续，不向 Agent 暴露原始 Tauri Command。
+- `BitFunControl list` 一次返回完整的精简目录（目录上限 50 项）；`search` 默认只返回前 20 项。完整目录和 297 项子能力都不会写入 system prompt。
+- Desktop 只有在前端控制监听器完成握手后才发布工具；CLI、Detached Dispatch 等没有交互界面的运行方式明确不提供该工具。只读 Agent 只能发现和读取目录。
+
+- Every feature or setting has an executable product destination. Multi-view settings pages must map every registered view to at least one documented item, so search and agents can carry an item ID for exact navigation.
+- Only simple, stable, automation-safe behavior becomes a typed `operation` or `option`. Complex flows open their owning UI instead of exposing raw Tauri commands to agents.
+- One default `BitFunControl list` call returns the complete curated catalog (hard limit: 50); `search` defaults to 20 results. Neither the full catalog nor its 297 documented items enters the system prompt.
+- Desktop advertises the tool only after the frontend control listener completes its readiness handshake. Headless surfaces such as CLI and Detached Dispatch explicitly omit it, and read-only agents may only discover and inspect entries.
+
+## 防腐化门禁 / Anti-drift gates
+
+- 设置页、产品动作与场景注册表必须全部映射到一个语义条目。
+- 所有设置子视图必须有同源的子能力直达目标，失效的页签 ID 会阻断生成。
+- 每个功能至少 6 项、每个设置至少 4 项子能力，且中英文、稳定 ID 与证据缺一不可。
+- 当前操作处理器不接受参数；若目录误声明参数，生成会失败，避免 Agent 看到实际不会生效的参数。
+- Tauri 模块命令数和用户可见交互源码摘要均为 reviewed contract；变化会让 `capabilities:check` 失败并给出新的摘要值。
+- 维护者必须先核对功能清单与证据，再只在本语义源中更新 reviewed count/digest，随后运行 `pnpm run capabilities:generate`。
+
+- Every settings page, product action, and scene registration must map to one semantic entry.
+- Every settings subview needs a same-source item destination; stale view IDs fail generation.
+- Features need at least six documented items and settings need at least four, each with bilingual text, a stable ID, and source evidence.
+- Current operation handlers accept no arguments, and generation fails if the catalog advertises arguments that would be ignored.
+- Reviewed Tauri module counts and the user-visible interaction-source digest fail `capabilities:check` on drift.
+- Maintainers review the inventories and evidence first, update the reviewed count/digest only in this semantic source, then run `pnpm run capabilities:generate`.