@tencent-rtc/trtc-agent-skills 0.1.0 → 0.1.3

package/hooks/cursor-adapter.py

@@ -0,0 +1,315 @@
+#!/usr/bin/env python3
+"""cursor-adapter.py — Translate Cursor hook protocol to existing Claude-format guardrails.
+
+Wired from hooks-cursor.json. Each Cursor hook event runs:
+
+    python3 ./hooks/cursor-adapter.py <dispatch-key>
+
+This script:
+  1. Reads the Cursor hook envelope from stdin (camelCase fields).
+  2. Normalizes it to the {tool_name, tool_input} shape the existing
+     guardrail scripts in skills/*/guardrails/ expect.
+  3. Sets CLAUDE_PLUGIN_ROOT and CLAUDE_PROJECT_DIR env vars so the
+     existing scripts find sessions and shared libs unchanged.
+  4. Spawns the underlying script and propagates stdout/stderr.
+  5. Translates exit codes:
+       Claude Code: 0=allow, 1=fail, 2=block
+       Cursor:      0=success, 2=deny (with JSON), other=fail-open
+     We map Claude exit 1 and exit 2 -> Cursor deny (exit 2 + JSON on stdout).
+
+Fail-open principle: if anything goes wrong inside the adapter (missing
+script, malformed stdin, dispatch key unknown), we exit 0 silently so a
+broken adapter never blocks the user's workflow.
+
+Cursor event mapping (see hooks-cursor.json):
+  sessionStart        -> trtc-prepare-ui
+  beforeReadFile      -> gate-slice-read
+  preToolUse          -> gate-slice-write       (filtered to Write/Edit inside)
+  afterFileEdit       -> verify-ui-post-write, verify-slice-must
+  stop                -> stop-apply-evidence, trtc-verify-ui, verify-apply-project
+                         (Claude Code's `Stop` event fires per agent loop
+                          iteration end. Cursor's `stop` event has the same
+                          semantic ("Called when the agent loop ends") and
+                          uniquely supports {"followup_message": "..."} on
+                          stdout to auto-resubmit a corrective user turn —
+                          which is exactly what these end-of-task guardrails
+                          need so the agent can self-correct. Auto-resubmit
+                          is capped at 5 iterations by Cursor's loop_limit.
+
+                          Historical note: a previous revision of this
+                          adapter mapped these to `afterAgentResponse`
+                          because the original author observed `stop` not
+                          firing. Empirically (Cursor 3.3.8) `stop` does
+                          fire reliably; the original "stop never fires"
+                          observation was caused by hooks not being loaded
+                          at all, not by the `stop` event itself. See
+                          install instructions in the README for the
+                          documented user-level `~/.cursor/hooks.json`
+                          install path — plugin-level hooks declared in
+                          .cursor-plugin/plugin.json are NOT loaded by
+                          current Cursor versions.)
+
+To enable verbose tracing during development, set the env var
+TRTC_HOOK_DEBUG_LOG=/path/to/file.log; see _dbg() below. The default is
+silent (no log file written) so production installs don't accumulate logs.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+ADAPTER_DIR = Path(__file__).resolve().parent
+PLUGIN_ROOT = ADAPTER_DIR.parent  # plugin install root
+
+
+# Optional debug logging — only writes when TRTC_HOOK_DEBUG_LOG is set to a
+# path. Useful for diagnosing "why didn't my hook fire" without modifying
+# the script.
+def _dbg(msg: str) -> None:
+    log_path = os.environ.get("TRTC_HOOK_DEBUG_LOG")
+    if not log_path:
+        return
+    try:
+        import datetime as _dt
+        with open(log_path, "a") as f:
+            f.write(f"[{_dt.datetime.now().isoformat(timespec='milliseconds')}] {msg}\n")
+    except Exception:
+        pass
+
+
+# Always-on probe log: writes one line per adapter invocation to
+# /tmp/trtc-hook-probe.log so we can confirm which Cursor hook events
+# actually fire end-to-end. Off by default to avoid unbounded log files
+# in production installs; enable by setting env TRTC_HOOK_PROBE=1.
+def _probe_log(key, payload) -> None:
+    if os.environ.get("TRTC_HOOK_PROBE") != "1":
+        return
+    try:
+        import datetime as _dt
+        ev = (payload or {}).get("hook_event_name", "?")
+        with open("/tmp/trtc-hook-probe.log", "a") as f:
+            f.write(
+                f"[{_dt.datetime.now().isoformat(timespec='milliseconds')}] "
+                f"event={ev!r} key={key!r} "
+                f"pid={os.getpid()} "
+                f"cwd={os.environ.get('CURSOR_PROJECT_DIR') or os.getcwd()!r}\n"
+            )
+    except Exception:
+        pass
+
+
+# Dispatch table: dispatch_key -> relative script path under PLUGIN_ROOT.
+DISPATCH = {
+    "trtc-prepare-ui":      "skills/trtc/room-builder/guardrails/trtc_prepare_ui.py",
+    "gate-slice-read":      "skills/trtc-topic/guardrails/gate_slice_read.py",
+    "gate-slice-write":     "skills/trtc-topic/guardrails/gate_slice_write.py",
+    "verify-ui-post-write": "skills/trtc/room-builder/guardrails/verify_ui_post_write.sh",
+    "verify-slice-must":    "skills/trtc-apply/guardrails/verify_slice_must_rules.py",
+    "stop-apply-evidence":  "skills/trtc-topic/guardrails/stop_require_apply_evidence.py",
+    "trtc-verify-ui":       "skills/trtc/room-builder/guardrails/trtc_verify_ui.py",
+    "verify-apply-project": "skills/trtc-apply/guardrails/verify_apply_project.py",
+}
+
+# Dispatch keys whose underlying scripts read JSON from stdin.
+# Other keys are CLI-only and will receive empty stdin.
+STDIN_KEYS = {
+    "gate-slice-read",
+    "gate-slice-write",
+    "verify-ui-post-write",
+    "verify-slice-must",
+}
+
+
+def _silent_allow() -> None:
+    """Fail-open: never block the user because the adapter itself failed."""
+    _dbg("  EXIT=0 (silent allow)")
+    sys.exit(0)
+
+
+def _read_cursor_payload() -> dict:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        return {}
+    try:
+        data = json.loads(raw)
+        return data if isinstance(data, dict) else {}
+    except (ValueError, TypeError):
+        return {}
+
+
+def _translate_payload(key: str, cursor: dict) -> dict:
+    """Map Cursor's per-event payload to the {tool_name, tool_input} envelope
+    the existing guardrails expect.
+
+    The existing scripts read either:
+      - {"tool_name": "Read",       "tool_input": {"file_path": "..."}}
+      - {"tool_name": "Write|Edit", "tool_input": {"file_path": "..."}}
+    """
+    if key == "gate-slice-read":
+        # Cursor's beforeReadFile payload: {file_path, content, attachments, ...}
+        file_path = cursor.get("file_path") or cursor.get("filePath")
+        return {"tool_name": "Read", "tool_input": {"file_path": file_path}}
+
+    if key == "gate-slice-write":
+        # Cursor's preToolUse payload: {tool_name, tool_input, tool_use_id, cwd, ...}
+        # Cursor only emits "Write" (no separate "Edit"); existing script
+        # accepts both. Pass through unchanged when tool_name is Write/Edit;
+        # silent allow for unrelated tools.
+        tool_name = cursor.get("tool_name") or cursor.get("toolName")
+        if tool_name not in ("Write", "Edit"):
+            return {}  # caller will silent-allow
+        tool_input = cursor.get("tool_input") or cursor.get("toolInput") or {}
+        return {"tool_name": tool_name, "tool_input": tool_input}
+
+    if key in ("verify-ui-post-write", "verify-slice-must"):
+        # Cursor's afterFileEdit payload: {file_path, edits}
+        file_path = cursor.get("file_path") or cursor.get("filePath")
+        return {"tool_name": "Edit", "tool_input": {"file_path": file_path}}
+
+    # CLI-only events (sessionStart, afterAgentResponse) get empty stdin —
+    # they read state from session files and env vars, not stdin.
+    return {}
+
+
+def _emit_cursor_deny(message: str) -> None:
+    """Cursor deny protocol for events that honor blocking (preToolUse,
+    beforeReadFile, afterFileEdit): JSON on stdout + exit 2.
+
+    Fields populated:
+      - permission: "deny" — tells Cursor this action should be blocked.
+      - user_message: surfaced in Cursor's UI on events that support it.
+      - agent_message: shown to the agent so it can self-correct on hooks
+        that run before the agent's loop ends (preToolUse, beforeReadFile).
+
+    NOTE: do not call this for the `stop` event. Cursor docs confirm only
+    `followup_message` is honored on stop; use _emit_cursor_followup()
+    instead so the agent gets re-prompted to fix the issue.
+    """
+    _dbg(f"  EXIT=2 (deny) message={message[:160]!r}")
+    msg = message or "Blocked by TRTC guardrail."
+    payload = {
+        "permission": "deny",
+        "user_message": msg,
+        "agent_message": msg,
+    }
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
+    sys.exit(2)
+
+
+def _emit_cursor_followup(message: str) -> None:
+    """Cursor stop-event protocol: emit {"followup_message": ...} on stdout
+    and exit 0. Cursor will automatically submit the message as the next
+    user turn, giving the agent a chance to self-correct.
+
+    Per Cursor docs, the stop event only honors `followup_message`; other
+    output fields (permission, user_message, agent_message) are accepted by
+    the schema but not enforced by callers. Auto-resubmission is capped by
+    `loop_limit` (default 5) so a guardrail that keeps failing won't loop
+    forever.
+
+    Exit 0 (not 2): we want Cursor to resubmit, not block. Exit 2 on stop
+    just halts with no chance for the agent to fix the problem.
+    """
+    msg = (message or "TRTC guardrail failed; please review and fix.").strip()
+    # Cursor caps message length on some events; keep this generous but bounded
+    # so we don't ship a 50KB stderr trace as the next user message.
+    if len(msg) > 4000:
+        msg = msg[:4000] + "\n…(truncated)"
+    _dbg(f"  EXIT=0 (followup) message={msg[:160]!r}")
+    payload = {"followup_message": msg}
+    sys.stdout.write(json.dumps(payload))
+    sys.stdout.flush()
+    sys.exit(0)
+
+
+def main(argv: list[str]) -> None:
+    key = argv[1] if len(argv) >= 2 else None
+    _dbg(
+        f"ENTER key={key!r} "
+        f"cursor_project_dir={os.environ.get('CURSOR_PROJECT_DIR', '?')!r}"
+    )
+    if not key:
+        _silent_allow()
+
+    # Read stdin first so debug logs see Cursor's hook_event_name even when
+    # the dispatch key is unknown or the script is missing.
+    cursor_payload = _read_cursor_payload()
+    _probe_log(key, cursor_payload)
+    _dbg(
+        f"  hook_event_name={cursor_payload.get('hook_event_name', '?')!r} "
+        f"keys={sorted(cursor_payload.keys()) if cursor_payload else []}"
+    )
+
+    rel_script = DISPATCH.get(key)
+    if not rel_script:
+        # Unknown dispatch key — never block on adapter misconfiguration.
+        _silent_allow()
+
+    script = PLUGIN_ROOT / rel_script
+    if not script.exists():
+        # Script missing (e.g., skill not installed). Same convention the
+        # existing hooks.json uses ("[ ! -f X ] || python3 X").
+        _silent_allow()
+
+    claude_payload = _translate_payload(key, cursor_payload)
+
+    # gate-slice-write returns {} when tool isn't Write/Edit -> silent allow.
+    if key == "gate-slice-write" and not claude_payload:
+        _silent_allow()
+
+    # Build env: surface Cursor's project dir as CLAUDE_PROJECT_DIR so
+    # existing scripts that key off CLAUDE_PROJECT_DIR keep working.
+    env = dict(os.environ)
+    cursor_project_dir = env.get("CURSOR_PROJECT_DIR") or cursor_payload.get("cwd")
+    if cursor_project_dir and not env.get("CLAUDE_PROJECT_DIR"):
+        env["CLAUDE_PROJECT_DIR"] = cursor_project_dir
+    env["CLAUDE_PLUGIN_ROOT"] = str(PLUGIN_ROOT)
+
+    runner = ["bash", str(script)] if script.suffix == ".sh" else ["python3", str(script)]
+    stdin_data = json.dumps(claude_payload) if key in STDIN_KEYS else ""
+
+    try:
+        proc = subprocess.run(
+            runner,
+            input=stdin_data,
+            text=True,
+            env=env,
+            capture_output=True,
+            timeout=30,
+        )
+    except (subprocess.TimeoutExpired, OSError):
+        _silent_allow()
+
+    # Forward whatever the inner script wrote.
+    if proc.stdout:
+        sys.stderr.write(proc.stdout)  # inner stdout -> stderr so we don't
+                                       # corrupt our Cursor JSON channel
+    if proc.stderr:
+        sys.stderr.write(proc.stderr)
+
+    rc = proc.returncode
+    _dbg(f"  inner_rc={rc}")
+    if rc == 0:
+        sys.exit(0)
+    if rc in (1, 2):
+        # Translate fail/block into Cursor's response. Use stderr content as
+        # the agent-facing message so the existing scripts' human-readable
+        # explanations reach the user.
+        msg = (proc.stderr or proc.stdout or "").strip()
+        # On the `stop` event Cursor honors only `followup_message` (which
+        # auto-resubmits a corrective user turn). On preToolUse /
+        # beforeReadFile / afterFileEdit, the deny envelope is enforced.
+        if cursor_payload.get("hook_event_name") == "stop":
+            _emit_cursor_followup(msg)
+        _emit_cursor_deny(msg)
+
+    # Unknown exit code — fail open to mimic Claude Code's permissive default.
+    _silent_allow()
+
+
+if __name__ == "__main__":
+    main(sys.argv)

package/hooks/hooks-cursor.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py trtc-prepare-ui"
+      }
+    ],
+    "beforeReadFile": [
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py gate-slice-read"
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py gate-slice-write"
+      }
+    ],
+    "afterFileEdit": [
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py verify-ui-post-write"
+      },
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py verify-slice-must"
+      }
+    ],
+    "stop": [
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py stop-apply-evidence"
+      },
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py trtc-verify-ui"
+      },
+      {
+        "command": "python3 $HOME/.cursor/plugins/local/trtc-agent-skills/hooks/cursor-adapter.py verify-apply-project"
+      }
+    ]
+  }
+}

package/hooks/hooks.json

@@ -0,0 +1,67 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/trtc_prepare_ui.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/trtc_prepare_ui.py\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/gate_slice_read.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/gate_slice_read.py\""
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/gate_slice_write.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/gate_slice_write.py\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/verify_ui_post_write.sh\" ] || bash \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/verify_ui_post_write.sh\""
+          },
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-apply/guardrails/verify_slice_must_rules.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-apply/guardrails/verify_slice_must_rules.py\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/stop_require_apply_evidence.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-topic/guardrails/stop_require_apply_evidence.py\""
+          },
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/trtc_verify_ui.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc/room-builder/guardrails/trtc_verify_ui.py\""
+          },
+          {
+            "type": "command",
+            "command": "[ ! -f \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-apply/guardrails/verify_apply_project.py\" ] || python3 \"${CLAUDE_PLUGIN_ROOT:-${CODEBUDDY_PLUGIN_ROOT}}/skills/trtc-apply/guardrails/verify_apply_project.py\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/knowledge-base/index.yaml

@@ -331,6 +331,14 @@ slices:
     description: 官方 RoomKit 集成模式下 conference 对象的完整 API 签名、枚举定义、调用时序和代码示例（ui_mode=official-roomkit 专用）
     status: active
 
+  - id: conference/integration-audit
+    name: Conference Web 集成审计
+    tags: [audit, checklist, meta, integration-review, roomkit, online-classroom]
+    platforms: [web]
+    file: slices/conference/web/integration-audit.md
+    description: 横切对照官方 Conference Web 接入流程的审计清单；Path B intent F 使用，不进 scenario 集成队列
+    status: active
+
 # ============================================================
 # Scenarios — 场景组合索引
 # ============================================================

package/knowledge-base/scenarios/conference/base/general-conference.md

@@ -236,12 +236,15 @@ slices:
    ```
    我帮你定位到「通用会议」场景。会议骨架(登录、会前预览、房间生命周期、成员列表、画面布局、设备控制、网络质量)会默认集成。
 
-   你的需求里我识别到要这些增强能力(已勾选):{命中的可选模块中文名}
+   你的需求里我识别到要这些增强能力:{命中的可选模块中文名}
 
-   还要加别的吗?(可多选;如果都不需要,请选择「以上都不需要」)
+   以上无误吗？
    ```
 
-3. **AskUserQuestion**:对「可选模块」做一次多选(`multiSelect: true`),选项 label 用上面的中文名,**预勾选第 1 步命中的项**。一次超过 4 项时按"会中协作 / 视频效果 / 预约邀请"分组拆成多次问(遵守 4 选项上限)。**每组多选必须包含一个「以上都不需要」选项（value=`none`），放在选项列表末尾，作为用户显式拒绝该组所有能力的出口。选中`none`时，该组其他选项视为未勾选；同时选中`none`和其他选项时，以`none`为准（清空其他选择）。**
+3a. **确认优先（`target_features` 已明确时）**：若第 1 步命中的可选模块非空且映射清晰，用 `AskUserQuestion` 单次确认：(1) 确认，按此集成 → 直接写 `confirmed_plan`；(2) 需要调整 → 再走下方多选。不要把用户已在 prompt 里点名的能力再让用户选一遍。
+
+3b. **多选（仅当 `target_features` 为空/模糊，或用户选「需要调整」）**：对「可选模块」做 `multiSelect: true` 多选，预勾选第 1 步命中的项。一次超过 4 项时分组。每组末尾含「以上都不需要」(`none`)。
+
 4. **写 `confirmed_plan`**:`confirmed_plan = 必装骨架 + 用户最终选中的可选模块`(去重,保持上面声明的顺序)。这是 `init_slice_queue.py` 的唯一输入,后续 A2-Q1.5 业务决策、slice 循环、apply 都以它为准。
 5. **不要**把未选中的可选模块写进 `confirmed_plan`,也不要在生成代码时"顺手"加它们的按钮 / composable。
 6. `enhancement_level` 仅为兼容旧字段:全部可选模块都选 → `complete`,否则 → `minimal`。真正的范围以 `confirmed_plan` 为准。

package/knowledge-base/slices/conference/web/integration-audit.md

@@ -0,0 +1,155 @@
+---
+id: conference/integration-audit
+name: Conference Web 集成审计
+product: conference
+platform: web
+tags: [audit, checklist, meta, integration-review, roomkit, online-classroom]
+platforms: [web]
+related:
+  - conference/login-auth
+  - conference/prejoin-check
+  - conference/room-lifecycle
+  - conference/room-schedule
+  - conference/device-control
+  - conference/official-roomkit-api
+related_scenario: general-conference
+---
+
+# Conference Web 集成审计
+
+> **Meta slice** — 横切对照清单，供 Path B intent F（集成审计）使用。
+> **不要**加入 scenario 的 `slices` / `confirmed_plan`，**不要**走 topic 集成队列或 apply 门禁。
+
+> 当用户问「检查业务流程遗漏」「对照官方接入流程」「在线课堂/会议流程是否正常」时使用本 slice。
+> 输出形态：**固定 checklist + slice 引用**；**不要**输出 code review、优缺点列表或「改进建议」段落。
+
+## 如何使用
+
+1. 从 session 读取 `product` / `platform` / `ui_mode` / `scenario`（若有）。
+2. 仅 `(product, platform) == (conference, web)` 时走完整清单；其他组合说明当前 skill 集成 fix 仅覆盖 Conference Web，清单仍可作为对照参考。
+3. 按角色（学生 / 老师 / 通用）裁剪章节；用户未说明角色时输出「通用骨架 + 在线课堂附录」。
+4. 每项标注：**应有** / **常见遗漏** / **对应 slice**。
+5. 用户贴了代码时，只核对清单项是否 wired up，不做风格点评。
+
+---
+
+## 1. 通用骨架（所有 Conference Web 项目）
+
+| # | 检查项 | 常见遗漏 | 参考 slice |
+|---|--------|----------|------------|
+| 1.1 | `conference.login()` / `useLoginState().login()` 先于任何 room/device/chat 调用 | 未登录直接 join | `conference/login-auth` |
+| 1.2 | 登录参数含 `scene: 5001`（skill 生成代码） | 缺 scene | `conference/login-auth` |
+| 1.3 | 登录成功后 `setSelfInfo({ userName, avatarUrl })` | 列表只显示 userId | `conference/login-auth` |
+| 1.4 | UserSig：生产由后端签发；本地可用 config 自动签名（`local-dev`）或控制台粘贴（`console`） | userId 与 userSig 不匹配 | `conference/login-auth` |
+| 1.5 | 监听 `LoginEvent.onLoginExpired` / `onKickedOffline` 并收口 | 只打日志 | `conference/login-auth` |
+| 1.6 | 监听 `RoomEvent.USER_SIG_EXPIRED` / `KICKED_OUT` / `ROOM_DISMISS` | 被动退出 UI 假在线 | `conference/room-lifecycle` |
+| 1.7 | 页面在 **HTTPS** 或 **localhost** 下调试 | 生产 HTTP 无媒体权限 | `conference/device-control` |
+| 1.8 | iframe 嵌入时宿主页 `allow="camera; microphone; display-capture; fullscreen"` | iframe 内黑屏/无权限 | `conference/device-control` |
+| 1.9 | 刷新/关页时 `leaveRoom()` 或等价清理 | 幽灵参会者 | `conference/room-lifecycle` |
+| 1.10 | 房主 `endRoom()` vs 成员 `leaveRoom()` 分支正确 | 老师误用 leave 导致房间未结束 | `conference/room-lifecycle` |
+
+---
+
+## 2. 会前设备检测
+
+| # | 检查项 | 常见遗漏 | 参考 slice |
+|---|--------|----------|------------|
+| 2.1 | 会前用 `startCameraTest` / `stopCameraTest`，**不用** `openLocalCamera` 做预检 | getUserMedia 与 SDK 双轨冲突 | `conference/prejoin-check` |
+| 2.2 | 预检页设备开关用**本地 ref**，不读 `cameraStatus` / `microphoneStatus` | 预检与会中状态串线 | `conference/prejoin-check` |
+| 2.3 | 入会前 `stopCameraTest()` 释放采集 | 进房后设备占用 | `conference/prejoin-check` |
+| 2.4 | 轻量 `getUserMedia` 仅作**权限门禁**；完整预览走 Atomicx 测试 API | 两套检测职责重叠 | `conference/prejoin-check` |
+| 2.5 | 进房后麦克风：先 `openLocalMicrophone()` + 默认 `muteMicrophone()`；摄像头：`open/closeLocalCamera` | 开麦延迟、关摄语义错误 | `conference/device-control` |
+
+---
+
+## 3. 房间生命周期
+
+| # | 检查项 | 常见遗漏 | 参考 slice |
+|---|--------|----------|------------|
+| 3.1 | 即时会议：发起人 `createAndJoinRoom`，他人 `joinRoom` | roomId 来源混乱 | `conference/room-lifecycle` |
+| 3.2 | 预约会议：`scheduleRoom` 成功后，到点仍须 `joinRoom`（预约≠已入会） | 预约后直接认为在会中 | `conference/room-schedule` |
+| 3.3 | `joinRoom` 失败区分：未登录 / 房间不存在 / 密码错误 / 已结束 | 统一提示「进房失败」 | `conference/room-lifecycle` |
+| 3.4 | 被动退出后清理 `currentRoom`、聊天、布局、widget 注册 | 再次入会残留上一场状态 | `conference/room-lifecycle` |
+| 3.5 | `passive_exit_target`：被踢/解散后跳转大厅或登录（业务决策） | 停留在空白会中页 | `conference/room-lifecycle` |
+
+---
+
+## 4. 官方 RoomKit 模式（`ui_mode = official-roomkit`）
+
+| # | 检查项 | 常见遗漏 | 参考 slice |
+|---|--------|----------|------------|
+| 4.1 | 根节点 `UIKitProvider` 包裹 `PreConferenceView` / `ConferenceMainView(H5)` | Provider 缺失 | `conference/official-roomkit-api` |
+| 4.2 | `setWidgetVisible` / `registerWidget` / `onWill` 在 **login 之后、join 之前** | 按钮闪烁、拦截失效 | `conference/official-roomkit-api` |
+| 4.3 | `createAndJoinRoom` / `joinRoom` 成功后立即 `setFeatureConfig({ shareLink })` | 分享链接 roomId 不对 | `conference/official-roomkit-api` |
+| 4.4 | 收集 `registerWidget` / `onWill` 返回的 cleanup；在 `ROOM_LEAVE` 与 `ROOM_DISMISS` 都执行 | 重复注册、泄漏 | `conference/official-roomkit-api` |
+| 4.5 | UI 显隐用 `setWidgetVisible`，**不用** CSS/DOM hack | 升级 SDK 即碎 | `conference/official-roomkit-api` |
+| 4.6 | lockfile 中 `@tencentcloud/roomkit-web-vue3 >= 5.4.3` | 定制 API 不可用 | `conference/official-roomkit-api` |
+
+---
+
+## 5. 在线课堂角色附录
+
+### 学生链路
+
+```text
+登录 → setSelfInfo → 预约列表(room-schedule) → 会前检测(prejoin-check)
+  → joinRoom → 会中（默认禁麦策略）→ 主动 leaveRoom / 被动 ROOM_DISMISS
+```
+
+| 常见遗漏 | 说明 |
+|----------|------|
+| 预约后直接进房未做设备检测 | 应用 prejoin-check 页或等价流程 |
+| 被房主结束会议无提示 | 监听 `RoomEvent.ROOM_DISMISS` |
+| 与「只 join 不 create」的 roomid_origin 不一致 | session 业务决策应对齐 |
+
+### 老师链路
+
+```text
+登录 → setSelfInfo → createAndJoinRoom → 会中开启 AI 字幕(ai-tools) / 录制(控制台+套餐)
+  → endRoom（非 leaveRoom）
+```
+
+| 常见遗漏 | 说明 |
+|----------|------|
+| AI 字幕非房主也调 `startRealtimeTranscriber` | 仅房主应启动 |
+| 结束会议用 `leaveRoom` 而非 `endRoom` | 其他成员仍留在已结束房间上下文 |
+| 录制能力未在控制台开通 | 预制 UI 按钮灰显或启动失败 |
+
+---
+
+## 6. 高频运行时问题速查（审计时顺带提及）
+
+| 现象 / 错误码 | 结论 | 下一步 |
+|---------------|------|--------|
+| **6206** / UserSig expired | 鉴权失败 | 后端刷新 UserSig；监听 `USER_SIG_EXPIRED` |
+| **100211** take-seat not enabled | 非麦位房间内部 seat 同步 | Standard 会议通常**可忽略**；确认未调用上麦/连麦 API |
+| **100006** only open to live room | 在 Standard 房间调了 Live 接口 | 检查 roomType；隐藏 Live 工具栏 widget |
+| 双设备检测冲突 | 职责未分层 | 见 §2 |
+| iframe 无画面 | 缺 allow 权限 | 见 §1.8 |
+| 刷新后幽灵在线 | 未 beforeunload leave | 见 §1.9 |
+
+---
+
+## 7. 推荐输出模板（给 AI）
+
+```markdown
+## Conference Web 集成对照结果
+
+**场景**：{scenario 或「通用会议」} · **UI 模式**：{official-roomkit | headless | 未知}
+
+### 已覆盖（对照官方流程）
+- …
+
+### 可能遗漏（按优先级）
+1. … → 参考 `conference/xxx`
+2. …
+
+### 环境/权限门禁
+- HTTPS / iframe / UserSig：…
+
+### 官方文档
+- [Web RoomKit 快速接入](https://cloud.tencent.com/document/product/647/81962)
+- [设备检测](https://cloud.tencent.com/document/product/647/126939)
+```
+
+**禁止**使用的标题：Critical Review Checklist、改进建议、✅正确 vs ❌错误 对比表（作为主结构）。

package/knowledge-base/slices/conference/web/login-auth.md

@@ -14,7 +14,8 @@ business_decisions:
     tier: blocking
     question: "您的项目当前处于哪个阶段？这决定鉴权凭证（UserSig）的生成方式。"
     options:
-      - { label: "本地开发 / 调试 —— 控制台临时签发，几分钟即可跑通；有有效期、不能用于生产", value: "console" }
+      - { label: "本地开发 —— config 配置 SDKAppID+SecretKey，登录时按 UserID 自动签名（推荐，最快）", value: "local-dev" }
+      - { label: "本地开发 / 调试 —— 到控制台生成 UserSig，复制粘贴到登录页（不配置 SecretKey）", value: "console" }
       - { label: "生产环境（上线）—— 由您的后端接口签发，安全合规（推荐）", value: "backend" }
   - key: userid_strategy
     tier: blocking