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

package/skills/trtc-ai-service/tests/test_stack_and_degrader.py

@@ -0,0 +1,101 @@
+"""Tech stack detection + three-tier fallback tests."""
+import json
+import os
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_ROOT))
+
+from scripts.lib import stack_detector as sd
+from scripts.lib import degrader as dg
+
+
+def _mkproj(files: dict) -> Path:
+    tmp = Path(tempfile.mkdtemp(prefix="stack_"))
+    for name, content in files.items():
+        p = tmp / name
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content, encoding="utf-8")
+    return tmp
+
+
+class StackDetectorTests(unittest.TestCase):
+
+    def test_react_project(self):
+        proj = _mkproj({
+            "package.json": json.dumps({"dependencies": {"react": "^18.2.0", "react-dom": "^18.2.0"}}),
+        })
+        res = sd.detect(proj)
+        self.assertEqual(res.primary, "react")
+        self.assertIn("react", res.candidates)
+
+    def test_next_priority_over_react(self):
+        proj = _mkproj({
+            "package.json": json.dumps({"dependencies": {"next": "^14", "react": "^18"}}),
+        })
+        res = sd.detect(proj)
+        self.assertEqual(res.primary, "next")
+
+    def test_express_node_backend(self):
+        proj = _mkproj({"package.json": json.dumps({"dependencies": {"express": "^4"}})})
+        self.assertEqual(sd.detect(proj).primary, "express")
+
+    def test_spring_boot_pom(self):
+        proj = _mkproj({"pom.xml": "<artifactId>spring-boot-starter-web</artifactId>"})
+        self.assertEqual(sd.detect(proj).primary, "spring-boot")
+
+    def test_python_fastapi_priority_over_flask(self):
+        proj = _mkproj({"requirements.txt": "fastapi==0.110\nflask==3.0\n"})
+        self.assertEqual(sd.detect(proj).primary, "fastapi")
+
+    def test_unknown_returns_none(self):
+        proj = _mkproj({"random.txt": "hello"})
+        self.assertIsNone(sd.detect(proj).primary)
+
+    def test_match_adapter(self):
+        adapters = [
+            {"tech_stack": ["react", "vue"], "adapter": "frontend-spa"},
+            {"tech_stack": ["express"], "adapter": "node-backend"},
+        ]
+        self.assertEqual(sd.match_adapter("react", adapters), "frontend-spa")
+        self.assertEqual(sd.match_adapter("express", adapters), "node-backend")
+        self.assertIsNone(sd.match_adapter("unknown", adapters))
+
+
+class DegraderTests(unittest.TestCase):
+
+    def test_l1_when_match_and_codegen_ok(self):
+        d = dg.decide("react", "frontend-spa", True)
+        self.assertEqual(d.level, dg.DegradeLevel.L1_AUTO)
+
+    def test_l2_when_match_but_codegen_failed(self):
+        fb = {"guided_templates": ["x.md"]}
+        d = dg.decide("react", "frontend-spa", False, fallback=fb, code_gen_error="conflict")
+        self.assertEqual(d.level, dg.DegradeLevel.L2_GUIDED)
+        self.assertIn("x.md", d.artifacts)
+        self.assertIn("conflict", d.reason)
+
+    def test_l3_when_no_tech_stack(self):
+        fb = {"manual_api": {"rest_endpoint": "/api/v1", "sdk_packages": [{"npm": "x"}]}}
+        d = dg.decide(None, None, False, fallback=fb)
+        self.assertEqual(d.level, dg.DegradeLevel.L3_MANUAL)
+        self.assertTrue(any("rest_endpoint:/api/v1" in a for a in d.artifacts))
+        self.assertTrue(any("sdk:npm:x" in a for a in d.artifacts))
+
+    def test_l3_when_stack_known_but_no_adapter(self):
+        d = dg.decide("svelte", None, False, fallback={"manual_api": {}})
+        self.assertEqual(d.level, dg.DegradeLevel.L3_MANUAL)
+        self.assertIn("no adapter for tech_stack=svelte", d.reason)
+
+    def test_channel_matrix_has_16_rows(self):
+        rows = dg.channel_combinations_matrix()
+        self.assertEqual(len(rows), 16)
+        verdicts = {r["verdict"] for r in rows}
+        self.assertIn("silent_wait", verdicts)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/trtc-ai-service/tests/test_verify_credentials.py

@@ -0,0 +1,285 @@
+"""Phase 3 Stage 6: scripts/verify-credentials.py + scripts/lib/credential_validators tests.
+
+Coverage targets:
+- Unit: ValidationResult / BatchResult / load_dotenv / hint error code mapping
+- Integration (subprocess): run verify-credentials.py in a **clean environment**
+    → All three keys unconfigured → must output valid JSON with error == "E000" and non-zero exit code
+- Unit (mock all three services): via patch of ``health.check_*`` verify
+    validate_tencent / validate_trtc / validate_llm / validate_all chain
+    returned ValidationResult fields match ``{ok, type, error, message, latency_ms}``
+
+Red lines (aligned with SKILL.md §12 Tool Whitelist):
+- Verification script **does not** accept keys as CLI arguments → tests only use .env and patch
+- Output JSON must not contain credential plaintext (latency_ms / error code only)
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+
+_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_ROOT))
+
+
+def _run_cli(env_extra=None, args=None):
+    """Fork a verify-credentials.py subprocess in an isolated environment.
+
+    Explicitly empties all three Key env variables to prevent .env file fallback overrides
+    (load_dotenv uses setdefault; empty strings in env prevent real values from .env injection).
+    """
+    env = {
+        "PATH": os.environ.get("PATH", ""),
+        "HOME": os.environ.get("HOME", ""),
+        "PYTHONPATH": str(_ROOT),
+        # Force clear all candidate env variables to ensure ``configured`` is False
+        "TENCENT_CLOUD_SECRET_ID": "",
+        "TENCENT_CLOUD_SECRET_KEY": "",
+        "TRTC_SDK_APP_ID": "",
+        "TRTC_SDK_SECRET_KEY": "",
+        "LLM_API_KEY": "",
+        "LLM_API_URL": "",
+        "LLM_MODEL": "",
+    }
+    if env_extra:
+        env.update(env_extra)
+    cmd = [sys.executable, str(_ROOT / "scripts" / "verify-credentials.py")]
+    if args:
+        cmd.extend(args)
+    proc = subprocess.run(
+        cmd,
+        cwd=str(_ROOT),
+        capture_output=True,
+        text=True,
+        timeout=20,
+        env=env,
+    )
+    return proc
+
+
+class CredentialValidatorsUnitTests(unittest.TestCase):
+    """Pure unit tests for the credential_validators module (no network calls)."""
+
+    def test_validation_result_to_dict_keys(self):
+        from scripts.lib.credential_validators import ValidationResult
+        r = ValidationResult(ok=True, type="tencent", message="ok", latency_ms=42)
+        d = r.to_dict()
+        self.assertSetEqual(
+            set(d.keys()), {"ok", "type", "error", "message", "latency_ms"}
+        )
+        self.assertTrue(d["ok"])
+        self.assertEqual(d["type"], "tencent")
+
+    def test_batch_result_aggregates(self):
+        from scripts.lib.credential_validators import BatchResult, ValidationResult
+        b = BatchResult(
+            ok=False,
+            items=[
+                ValidationResult(ok=True, type="tencent"),
+                ValidationResult(ok=False, type="trtc", error="E002", message="fail"),
+                ValidationResult(ok=True, type="llm"),
+            ],
+        )
+        d = b.to_dict()
+        self.assertEqual(d["type"], "all")
+        self.assertFalse(d["ok"])
+        self.assertEqual(len(d["items"]), 3)
+        self.assertEqual(d["items"][1]["error"], "E002")
+
+    def test_hint_returns_known_codes(self):
+        from scripts.lib.credential_validators import hint
+        self.assertIn("腾讯云", hint("E001"))
+        self.assertIn("TRTC", hint("E002"))
+        self.assertIn("LLM", hint("E003"))
+        # Unknown error code → empty string
+        self.assertEqual(hint("E999"), "")
+
+    def test_load_dotenv_reads_kv(self):
+        from scripts.lib.credential_validators import load_dotenv
+        with tempfile.TemporaryDirectory() as td:
+            envf = Path(td) / ".env"
+            envf.write_text(
+                "FAKE_KEY_FOR_TEST=hello\n# comment\nFAKE_QUOTED=\"world\"\n",
+                encoding="utf-8",
+            )
+            try:
+                # Clear same-name process-level vars to ensure reading from file
+                os.environ.pop("FAKE_KEY_FOR_TEST", None)
+                os.environ.pop("FAKE_QUOTED", None)
+                seen = load_dotenv(envf)
+                self.assertEqual(seen.get("FAKE_KEY_FOR_TEST"), "hello")
+                self.assertEqual(seen.get("FAKE_QUOTED"), "world")
+                self.assertEqual(os.environ.get("FAKE_KEY_FOR_TEST"), "hello")
+            finally:
+                os.environ.pop("FAKE_KEY_FOR_TEST", None)
+                os.environ.pop("FAKE_QUOTED", None)
+
+
+class VerifyCredentialsCliEmptyEnvTests(unittest.TestCase):
+    """Subprocess: verify-credentials.py behavior in a clean environment (no .env, no keys)."""
+
+    def setUp(self):
+        # Use a clean tmp directory as cwd stand-in: point --env-file to a non-existent path
+        # while eliminating the chance of hitting the repo root .env / capabilities/conversation-core/.env
+        self.tmp = tempfile.TemporaryDirectory()
+        self.empty_env = Path(self.tmp.name) / "no.env"
+        self.empty_env.write_text("# empty\n", encoding="utf-8")
+
+    def tearDown(self):
+        self.tmp.cleanup()
+
+    def _run(self, *extra_args):
+        return _run_cli(args=["--env-file", str(self.empty_env), *extra_args])
+
+    def test_tencent_empty_returns_e000(self):
+        proc = self._run("--type", "tencent")
+        self.assertNotEqual(proc.returncode, 0, proc.stderr)
+        out = json.loads(proc.stdout.strip())
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["type"], "tencent")
+        self.assertEqual(out["error"], "E000")
+        self.assertSetEqual(
+            set(out.keys()), {"ok", "type", "error", "message", "latency_ms"}
+        )
+        # Output must not contain real keys (empty_env also ensures this)
+        self.assertNotIn("AKID", proc.stdout)
+        self.assertNotIn("AKID", proc.stderr)
+
+    def test_trtc_empty_returns_e000(self):
+        proc = self._run("--type", "trtc")
+        out = json.loads(proc.stdout.strip())
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["type"], "trtc")
+        self.assertEqual(out["error"], "E000")
+
+    def test_llm_empty_returns_e000(self):
+        proc = self._run("--type", "llm")
+        out = json.loads(proc.stdout.strip())
+        self.assertFalse(out["ok"])
+        self.assertEqual(out["type"], "llm")
+        self.assertEqual(out["error"], "E000")
+
+    def test_all_empty_returns_three_items(self):
+        proc = self._run("--type", "all")
+        self.assertNotEqual(proc.returncode, 0)
+        out = json.loads(proc.stdout.strip())
+        self.assertEqual(out["type"], "all")
+        self.assertFalse(out["ok"])
+        types = {item["type"] for item in out["items"]}
+        self.assertSetEqual(types, {"tencent", "trtc", "llm"})
+
+
+class VerifyCredentialsMockedNetworkTests(unittest.TestCase):
+    """Patch health.check_* to simulate success / failure responses from all three services."""
+
+    def setUp(self):
+        # Inject fake keys at process level (only to make ``configured`` return True)
+        self._keys = {
+            "TENCENT_CLOUD_SECRET_ID": "AKID_TEST_FAKE_FAKE_FAKE_FAKE_FAKE_X",
+            "TENCENT_CLOUD_SECRET_KEY": "FakeKeyFakeKeyFakeKeyFakeKeyFakeKey",
+            "TRTC_SDK_APP_ID": "1400000001",
+            "TRTC_SDK_SECRET_KEY": "FakeTRTCSdkSecretKeyFakeTRTCSdkSecretKey",
+            "LLM_API_KEY": "sk-fake-test-key",
+            "LLM_API_URL": "https://api.openai.example/v1/chat/completions",
+            "LLM_MODEL": "gpt-test",
+            "LLM_TYPE": "openai",
+        }
+        self._saved = {k: os.environ.get(k) for k in self._keys}
+        for k, v in self._keys.items():
+            os.environ[k] = v
+
+    def tearDown(self):
+        for k, prev in self._saved.items():
+            if prev is None:
+                os.environ.pop(k, None)
+            else:
+                os.environ[k] = prev
+
+    def _import_health(self):
+        """Explicitly import conversation-core's health module for patching.
+
+        Clean all cached ``src.*`` modules (side effect from test_handoff_ports / test_kb_ports),
+        and push conversation-core to the top of sys.path so ``src`` resolves back to this capability.
+        """
+        core_dir = _ROOT / "capabilities" / "conversation-core"
+        # First clean up src.* modules injected by previous tests
+        for name in [k for k in list(sys.modules) if k == "src" or k.startswith("src.")]:
+            del sys.modules[name]
+        # Also remove other capabilities paths from sys.path to avoid ambiguity
+        sys.path[:] = [p for p in sys.path if "/capabilities/" not in p]
+        sys.path.insert(0, str(core_dir))
+        import importlib  # noqa: WPS433
+        return importlib.import_module("src.health")
+
+    def test_tencent_ok(self):
+        h = self._import_health()
+        from scripts.lib.credential_validators import validate_tencent
+        with patch.object(h, "check_tencent_cloud") as m:
+            m.return_value = h.CheckResult(ok=True, latency_ms=120, detail="sts ok")
+            r = validate_tencent()
+        self.assertTrue(r.ok)
+        self.assertEqual(r.type, "tencent")
+        self.assertEqual(r.error, "")
+        self.assertEqual(r.latency_ms, 120)
+
+    def test_tencent_failure_maps_to_e001(self):
+        h = self._import_health()
+        from scripts.lib.credential_validators import validate_tencent
+        with patch.object(h, "check_tencent_cloud") as m:
+            m.return_value = h.CheckResult(
+                ok=False, latency_ms=33, error_code="E001", detail="AuthFailure"
+            )
+            r = validate_tencent()
+        self.assertFalse(r.ok)
+        self.assertEqual(r.error, "E001")
+        # Must not echo key plaintext
+        self.assertNotIn("FakeKey", r.message)
+
+    def test_trtc_ok_local_only(self):
+        h = self._import_health()
+        from scripts.lib.credential_validators import validate_trtc
+        with patch.object(h, "check_trtc") as m:
+            m.return_value = h.CheckResult(ok=True, latency_ms=12, detail="local-only")
+            r = validate_trtc(deep=False)
+        self.assertTrue(r.ok)
+        self.assertEqual(r.type, "trtc")
+
+    def test_llm_failure_maps_to_e003(self):
+        h = self._import_health()
+        from scripts.lib.credential_validators import validate_llm
+        with patch.object(h, "check_llm") as m:
+            m.return_value = h.CheckResult(
+                ok=False, latency_ms=55, error_code="E003", detail="401 Unauthorized"
+            )
+            r = validate_llm()
+        self.assertFalse(r.ok)
+        self.assertEqual(r.error, "E003")
+        self.assertEqual(r.type, "llm")
+        # Output message must not contain raw sk-* credentials
+        self.assertNotIn("sk-fake", r.message)
+
+    def test_validate_all_aggregates(self):
+        h = self._import_health()
+        from scripts.lib.credential_validators import validate_all
+        with patch.object(h, "check_tencent_cloud") as a, \
+             patch.object(h, "check_trtc") as b, \
+             patch.object(h, "check_llm") as c:
+            a.return_value = h.CheckResult(ok=True, latency_ms=100)
+            b.return_value = h.CheckResult(ok=True, latency_ms=80, detail="ok")
+            c.return_value = h.CheckResult(ok=False, latency_ms=20, error_code="E003", detail="boom")
+            batch = validate_all()
+        self.assertFalse(batch.ok)
+        items = batch.to_dict()["items"]
+        self.assertEqual(len(items), 3)
+        # Order is fixed: tencent → trtc → llm
+        self.assertEqual([i["type"] for i in items], ["tencent", "trtc", "llm"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/trtc-ai-service/triggers.yaml

@@ -0,0 +1,29 @@
+# trtc-ai-service trigger word registry
+#
+# Documentation only — routing logic is inlined in skills/trtc/SKILL.md.
+# Do NOT reference this file as a runtime routing dependency.
+#
+# Purpose: single source of truth for what triggers the AI service fast-path,
+# so edits happen here and get back-ported to SKILL.md manually.
+
+triggers:
+  include:
+    # Chinese
+    - "AI客服"
+    - "智能客服"
+    - "搭建AI客服"
+    - "集成AI客服"
+    - "对话式AI"
+    - "语音助手 + 客服"          # both tokens must appear together
+    # English
+    - "AI customer service"
+    - "AI customer service agent"
+    - "conversational AI"
+    - "TRTC Conversational AI"
+    - "voice agent + customer service"   # both tokens must appear together
+
+  removed_from_pr:
+    # Removed — too broad, causes false positives on unrelated TRTC queries
+    - "intelligent Q&A"
+    - "智能问答"
+    - "build AI agent"     # no customer-service modifier → too wide

package/skills/trtc-chat/.docs-query.yaml

@@ -0,0 +1,8 @@
+# Path D 运行时状态（与 .trtc-session.yaml 正交；Path D 脚本直接 Read/Write 本文件）
+# sessionId 由 Path D D.0a-i 首次进入时写入一次
+sessionId: ""
+sessionStartedAt: 0
+platform: ""
+types: []
+sdkappid: null
+lastPrompt: ""

package/skills/trtc-chat/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: trtc-chat
+description: >
+  Internal Chat (IM) integration domain skill — enter ONLY via skills/trtc/SKILL.md
+  after product=chat routing. Not a standalone dispatcher entry. Handles Vue 3 Web
+  full/direct chat integration (Path A/B/C/D).
+version: 0.1.4
+---
+
+# Chat Integration Domain Skill
+
+## 前置说明
+
+- **角色**：协同开发者，按 slice 最佳实践生成代码
+- **调用入口（唯一）**：`trtc/SKILL.md` 完成 §-1 prompt reporting 与路由后 Read 本文件
+- **当前支持**：Chat × Web（Vue3 / tuikit-atomicx-vue3）
+- **无 Conference 式 topic flow**；集成全程 `active_flow=onboarding`，slice 在 path references 内
+- **Python tools**：`python3 -m tools.*` 的 cwd 须为 `skills/trtc` 或 `skills/trtc-chat`（后者含 `tools/` shim，委托到 trtc）；**禁止**在用户项目根执行（避免项目自有 `tools/` 抢占）
+
+---
+
+## §0 Cross-IDE 执行契约（最高优先级）
+
+### 0.0 执行纪律
+
+0. **skill 约束优先级高于一切**：gate / phase / 上报是强约束，不得绕过
+1. **先行动后说话**：需要 tool call / Bash 时先执行再写用户可见文字
+2. **先验证后推进**：phase gate 必须有 tool result 证据
+3. **Session 写入后必须 READ 验证**（见 `08-state-config.md` §8.1.3）
+4. **业务上报是 phase postcondition**；节点上报前 Read `13-reporting.md`，用 `reporting_v2.py send`
+5. **用户 prompt**：每轮由 Root `reporting.py`；脚本节点的 `reporting_v2.py send` 见 `13-reporting.md`（含 Path B/C 业务 prompt）
+
+### 0.1 统一操作语义
+
+- Session 读写 → `python3 -m tools.session read` / `write-batch`
+- KB 读取 → `python3 -m tools.kb resolve <path>` → Read 输出绝对路径（见 `08-state-config.md` §8.0；**禁止** `../knowledge-base`）。**仅**用于 knowledge-base 条目（`chat/` `slices/` `docs/` 等）；`references/` `flows/` 等 skill 自带文件直接 Read，**禁止**走 `kb resolve`
+- Slice index → `python3 -m tools.kb resolve chat/web/index.yaml`
+
+### 0.2 证据规则 / 0.3 Fail-Closed
+
+证据缺失视为未执行。阻断码：`BLOCKED: project_root_unresolved` / `session_not_initialized` / `phase_gate_not_satisfied` / `credential_missing` / `unsupported_platform` / `BLOCKED: dispatcher_bypass`
+
+### 0.4 禁止默认替用户决策
+
+未获用户输入前禁止默认 `integration_mode`（full/direct）或凭证。
+
+### 0.5 入口门禁（禁止绕过 Root）
+
+❗ **本文件不是 dispatcher**。仅允许在以下任一条件成立后进入：
+
+| # | 条件 |
+|---|------|
+| 1 | 本轮已由 `trtc/SKILL.md` 路由至本文件（正常路径） |
+| 2 | `.trtc-session.yaml` 存在且 `product=chat` 或 `active_domain_skill=trtc-chat`，且本轮 Agent 已先 Read `../trtc/SKILL.md` 并完成其 §-1 |
+
+**若直接 Read 本文件（未经 Root）**：
+
+1. **STOP** 集成/分流动作
+2. 先 Read `../trtc/SKILL.md`，从 §-1 重新走 session guard → 分类 → 路由
+3. 禁止凭本文件 frontmatter / 描述关键词跳过 dispatcher
+
+**IM 纯咨询（Path D）**：由 Root 路由至 `docs/SKILL.md`，**不要**在本文件 Step 0 偷跑 Path D。
+
+---
+
+## §1 Phase 状态机
+
+`flow_state.chat.phase` 是唯一真相（`.trtc-session.yaml`，经 `tools.session`）。
+
+| phase | 允许动作 |
+|-------|----------|
+| `detect` | 探测 + session 初始化 + A.1 |
+| `collect_credentials` | 收集 SDKAppID / SecretKey |
+| `collect_mode` | Full / Direct |
+| `scaffold` | 脚手架 |
+| `slices` | 一轮一 slice |
+| `done` | 收尾；新功能→Path B；维护→Path C |
+
+`phase=done` 时：加法 → Path B；减法/报错 → Path C。
+
+---
+
+## 入口：读取 session 状态
+
+- `status=active` → 按 `active_flow` / `flow_state.chat.phase` 续接
+- `active_flow=onboarding` 覆盖 detect…slices
+- `status=completed` → 承接 Path B/C/D
+
+---
+
+## Step 0 — Path D 预检
+
+Bash `python3 -m tools.kb resolve chat/web/path-d-signals.yaml` → Read 输出路径，再对照用户句。
+
+命中条件（知识咨询信号 **且**）：
+- 无 `.trtc-session.yaml`，或
+- `product=chat` 且 `flow_state.chat.phase=done` / `status=completed`
+
+命中 → **STOP 本集成流**；应由 Root 已路由至 `docs/SKILL.md`。若尚未路由，Read `../trtc/SKILL.md` §A 后进入 `docs/SKILL.md`。
+
+❗ 路由至 `docs/SKILL.md` 后 **不要**再 Read `path-d-signals.yaml`（门禁已完成；后续见 `docs/SKILL.md` → `05-path-d-script.md` D.1）。
+
+---
+
+## Step 1 — 项目探测
+
+READ `references/01-detect-project.md` + `references/08-state-config.md` → 找根 → 写 `project_state.project_root`
+
+非 vue3 → `BLOCKED: unsupported_platform`
+
+---
+
+## Step 1.5 — Session 初始化
+
+READ `references/vue3.md`（按需）。
+
+```bash
+cd "<当前 trtc skill 目录>"
+# 无 session 时：
+python3 -m tools.session create --product chat --platform web --intent integrate-scenario
+python3 -m tools.session write-batch --updates '{
+  "active_domain_skill": "trtc-chat",
+  "active_flow": "onboarding",
+  "project_state": {"project_root": "<projectRoot>"},
+  "flow_state": {"chat": {"phase": "detect", "chat_path": "A"}}
+}' --expected-version <N>
+```
+
+已有 session → 保留 phase，仅更新必要字段。
+
+---
+
+## Step 2 — 路径分流
+
+| 优先级 | 条件 | 路径 |
+|--------|------|------|
+| 0 | Step 0 知识咨询 | D（经 Root → `docs/SKILL.md`） |
+| 1 | 减法/维护/报错 | C → READ `flows/maintenance.md` |
+| 2 | `phase=done` + 有 tuikit 依赖 | B |
+| 3 | 已依赖 tuikit-atomicx-vue3 | B |
+| 4 | 新项目 / 未依赖 | A |
+
+Path A/B：
+```bash
+python3 -m tools.flow enter --phase onboarding --product chat --platform web
+```
+然后 READ `flows/onboarding.md` → `02-path-a-script.md` 或 `03-path-b-script.md`
+
+**禁止** `enter --phase topic`
+
+Path C → READ `references/04-path-c-script.md`  
+Path D（集成流内不应到达）→ 若误达，Read `docs/SKILL.md`
+
+---
+
+## §3 Path A/B 强约束
+
+- 一轮一 slice；禁止预读下轮 slice
+- Write-then-Verify phase gate
+- Path B 禁止 `reopen-add-feature`（用 §8.5 write-batch）
+
+---
+
+## §4 Hard Rules 摘要
+
+READ `references/06-hard-rules.md` + `06-a-defensive-coding.md`
+
+---
+
+## §5 关键文件
+
+- `{projectRoot}/.trtc-session.yaml`（唯一 session，经 `tools.session`）
+- `{projectRoot}/WHAT-TO-DO-NEXT.md`（A.4 交付物）
+- `skills/trtc-chat/.docs-query.yaml`（Path D 正交态）
+
+---
+
+## §6 规则冲突优先级
+
+本文件 §0/§1/0/1/2 > 路径脚本 > hard rules > 其他
+
+---
+
+## §7 References 索引
+
+见 `references/10-references-index.md`

package/skills/trtc-chat/docs/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: trtc-chat-docs
+description: >
+  Internal Chat IM docs query (Path D) — enter ONLY via skills/trtc/SKILL.md routing.
+  Not a standalone dispatcher entry. IM product/SDK/REST/Webhook/TUIKit/billing/errors.
+version: 0.1.4
+---
+
+# Chat Docs Query — Path D
+
+## 入口门禁
+
+❗ **本文件不是 dispatcher**。仅允许在 `trtc/SKILL.md` 完成 §-1 prompt reporting 并路由至本文件后进入。
+
+若直接 Read 本文件：先 Read `../../trtc/SKILL.md`，从 §-1 重走分类与路由。
+
+## 门禁
+
+- 无 session，或
+- session 存在且 (`product=chat` ∧ (`status=completed` ∨ `flow_state.chat.phase=done`))
+
+## 执行
+
+Read `../references/05-path-d-script.md`，从 **D.0b** 起按 D.0–D.8 完整流程。
+
+❗ **禁止再 Read `path-d-signals.yaml`**：该文件仅用于 Root §A / `trtc-chat/SKILL.md` Step 0 的 Path D **路由门禁**。本轮既已进入本文件，说明门禁已通过；意图分类用 `05-path-d-script.md` **D.1** 内联信号表 + `.docs-query.yaml` 状态机，**不要**重复 resolve/read 信号词文件。
+
+## Prompt 上报
+
+- 每轮用户句：`trtc/SKILL.md` §-1 `reporting.py prompt`
+- 脚本节点：`reporting_v2.py send`（Path D `--json` prompt+answer / feedback；Path B/C 见 `13-reporting.md`）

package/skills/trtc-chat/flows/maintenance.md

@@ -0,0 +1,19 @@
+---
+phase: maintenance
+product: chat
+platform: web
+---
+
+# Chat Maintenance Flow — Path C
+
+> **调用方**：`trtc-chat/SKILL.md` Step 2 分流 Path C 时 Read 本文件。
+>
+> **职责**：维护 / 排障 / 减法 / 样式调整；**不**加载 slice。
+
+## 执行
+
+Read `../references/04-path-c-script.md`，从 C.1 执行完整 Path C 脚本。
+
+可选：设 `active_flow=maintenance`（经 `tools.session write-batch`，禁止直接编辑 yaml）。
+
+**禁止** `flow enter --phase maintenance`（`flow.py` 无此 phase；直读 reference 即可）。