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

package/skills/trtc-ai-service/auto_adapters/python-backend/manifest.yaml

@@ -0,0 +1,45 @@
+name: "python-backend"
+version: "1.0.0"
+target_role: "backend"
+tech_stack: ["flask", "fastapi", "django"]
+description: "Python backend reverse proxy: decorator / sub-router form to connect to skeleton"
+
+templates:
+  flask:
+    file: "flask.py.tpl"
+    target_path: "voice_agent_proxy.py"
+    install_hint: |
+      In main app:
+        from voice_agent_proxy import bp
+        app.register_blueprint(bp, url_prefix='${ROUTE_PREFIX}')
+    package_dependencies:
+      - "Flask>=3.0"
+      - "requests>=2.31"
+  fastapi:
+    file: "fastapi.py.tpl"
+    target_path: "voice_agent_proxy.py"
+    install_hint: |
+      In main app:
+        from voice_agent_proxy import router
+        app.include_router(router, prefix='${ROUTE_PREFIX}')
+    package_dependencies:
+      - "fastapi>=0.110"
+      - "httpx>=0.27"
+  django:
+    file: "django.py.tpl"
+    target_path: "voice_agent_proxy/views.py"
+    install_hint: |
+      In urls.py:
+        from voice_agent_proxy.views import proxy_view
+        urlpatterns += [path('${ROUTE_PREFIX}/<path:rest>', proxy_view)]
+    package_dependencies:
+      - "Django>=4.2"
+      - "requests>=2.31"
+
+defaults:
+  SKELETON_BASE_URL: "http://localhost:3000"
+  API_PREFIX: "/api/v1"
+  ROUTE_PREFIX: "/voice-agent"
+
+security:
+  https_required: true

package/skills/trtc-ai-service/capabilities/__init__.py

@@ -0,0 +1,43 @@
+"""capabilities namespace root.
+
+Subdirectories use hyphenated names (manifest style), but Python modules require underscore names.
+This file creates aliases on import as needed (only when the corresponding directory exists).
+
+Example:
+    capabilities.knowledge-base/  →  import capabilities.knowledge_base
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from pathlib import Path
+
+_ROOT = Path(__file__).resolve().parent
+
+# Hyphenated directory → underscore module alias
+_ALIASES = {
+    "knowledge-base": "knowledge_base",
+    "tool-calling": "tool_calling",
+    "human-handoff": "human_handoff",
+    "session-summary": "session_summary",
+    "digital-human": "digital_human",
+}
+
+
+def _install_alias(dirname: str, modname: str) -> None:
+    full_dir = _ROOT / dirname
+    if not full_dir.exists():
+        return
+    full_name = f"{__name__}.{modname}"
+    if full_name in sys.modules:
+        return
+    # Register a namespace package that sub-modules can continue importing
+    import types
+
+    pkg = types.ModuleType(full_name)
+    pkg.__path__ = [str(full_dir)]  # type: ignore[attr-defined]
+    sys.modules[full_name] = pkg
+
+
+for _d, _m in _ALIASES.items():
+    _install_alias(_d, _m)

package/skills/trtc-ai-service/capabilities/conversation-core/.env.example

@@ -0,0 +1,29 @@
+# conversation-core · 三把 Key 环境变量模板
+# ----------------------------------------------------------
+# 用法：
+#   1. 优先通过 `python scripts/setup-credentials.py` 交互式引导生成 .env
+#   2. 如需手动配置，复制本文件为 .env 并填入实际值
+# 注意：所有凭证仅来自环境变量（env-only），切勿在代码中明文写入
+
+# [1/3] 腾讯云 API 密钥
+TENCENT_CLOUD_SECRET_ID=
+TENCENT_CLOUD_SECRET_KEY=
+TENCENT_CLOUD_REGION=ap-guangzhou
+
+# [2/3] TRTC Conversational AI 应用凭据
+# 默认从 https://console.trtc.io 申请的国际站应用（trtc.intl.tencentcloudapi.com）
+TRTC_SDK_APP_ID=
+TRTC_SDK_SECRET_KEY=
+# （高级）若你的应用在国内站 console.cloud.tencent.com/trtc 申请，去掉下行注释：
+# TRTC_REGION=cn
+
+# [3/3] 外部 LLM 接入（OpenAI 兼容协议）
+LLM_API_KEY=
+LLM_API_URL=https://api.openai.com/v1/chat/completions
+LLM_MODEL=gpt-4o-mini
+LLM_TYPE=openai
+
+# 服务监听
+HOST=0.0.0.0
+PORT=3000
+LOG_LEVEL=INFO

package/skills/trtc-ai-service/capabilities/conversation-core/INTEGRATION.md

@@ -0,0 +1,134 @@
+# conversation-core · Integration Guide (Agent-readable)
+
+> This document is for **AI coding assistants / integration agents** to automatically
+> merge the conversation-core skeleton into user projects. All instructions are designed for programmatic parsing and execution.
+
+---
+
+## Section 1 · Tech Stack Detection
+
+At the integration entry point, the Agent detects user project characteristics in the following order, outputting a `tech_stack` label:
+
+| Signal File | Key Field | Inferred Tech Stack |
+|:---|:---|:---|
+| `package.json` | `dependencies.react` | `react` |
+| `package.json` | `dependencies.vue` | `vue` |
+| `package.json` | `dependencies['@angular/core']` | `angular` |
+| `package.json` | `dependencies.express` / `koa` / `fastify` | `express` / `koa` / `fastify` |
+| `package.json` | `dependencies.next` | `next` |
+| `pom.xml` | `<artifactId>spring-boot-starter</artifactId>` | `spring-boot` |
+| `build.gradle` | `org.springframework.boot` | `spring-boot` |
+| `pom.xml` | `quarkus-core` | `quarkus` |
+| `requirements.txt` / `pyproject.toml` | `flask` / `fastapi` / `django` | `flask` / `fastapi` / `django` |
+
+If multiple tech stack candidates are detected, the most specific one takes priority:
+`next > react/vue/angular > express/koa/fastify > spring-boot/quarkus > flask/fastapi/django`.
+
+---
+
+## Section 2 · Adapter Rule Matching
+
+Read the `integration.auto_adapters` list from this capability's `manifest.yaml`; the first entry whose `tech_stack` matches becomes the target adapter:
+
+```text
+match(tech_stack_detected, manifest.integration.auto_adapters[*].tech_stack)
+  → adapter_name (e.g. "frontend-spa")
+```
+
+The mapping from adapter name to actual generator is provided by Phase 2; this skeleton only declares the interface contract.
+
+---
+
+## Section 3 · Code Generation and Merging
+
+Phase 1 skeleton only exposes REST APIs (default port `3000`). How integrators call the skeleton from their own projects:
+
+### 3.1 Frontend (any SPA)
+
+```js
+// 1) Health check (top status bar)
+const health = await fetch('http://localhost:3000/api/v1/health').then(r => r.json());
+
+// 2) Request room credentials
+const cfg = await fetch('http://localhost:3000/api/v1/get_config', {
+  method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}'
+}).then(r => r.json());
+const { session_id, sdk_app_id, room_id, user_id, user_sig } = cfg.data;
+
+// 3) Join room via TRTC Web SDK using sdk_app_id / user_sig (encapsulated by frontend capability package)
+
+// 4) Start AI channel bot
+await fetch('http://localhost:3000/api/v1/agent/start', {
+  method: 'POST', headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ session_id, language: 'zh' })
+});
+```
+
+### 3.2 Backend (any runtime)
+
+| Runtime | Injection Point | Generator Output |
+|:---|:---|:---|
+| Express / Koa / Fastify | Router layer | Middleware code (reverse proxy `/api/v1/*` to skeleton process) |
+| Spring Boot / Quarkus | Filter Chain | Filter code + `@Value("${trtc.voice-agent.endpoint}")` injection |
+| Flask / FastAPI / Django | Route handler | Decorators + sub-router mounting |
+
+### 3.3 Injection Points (declarative)
+
+`manifest.yaml.injection_points` declares 5 standard injection points. Phase 2 capability packages reference them by `id`, e.g.:
+
+```yaml
+# knowledge-base capability manifest.yaml snippet
+extensions:
+  - inject_at: "agent.before_start"
+    code_template: "templates/inject_kb_to_instructions.py.tpl"
+```
+
+---
+
+## Section 4 · Three-Level Degradation Path
+
+| Level | Trigger Condition | Agent Behavior |
+|:---:|:---|:---|
+| **L1 Full Auto-Merge** | Tech stack detected successfully and code generation has no conflicts | Write directly into user project and auto-run `npm install` / `pip install` |
+| **L2 Semi-Auto Guide** | Tech stack detected successfully but code generation fails (syntax / path conflicts) | Output `INTEGRATION_GUIDE.md` with template code + manual injection steps |
+| **L3 Manual API Fallback** | Tech stack cannot be identified | Output REST API docs (base path `/api/v1`) + SDK package install commands |
+
+L2 / L3 output templates are located in `integration-templates/` (provided by Phase 2).
+
+---
+
+## Section 5 · Verification Checks
+
+After integration, the Agent must execute these checks in order:
+
+1. **Process alive** — `curl -s http://localhost:3000/api/v1/health | jq .status`, expected `"ok"`.
+2. **Three LEDs** — `health.checks.{tencent_cloud,trtc,llm}.status == "ok"`.
+3. **Session handshake** — `POST /api/v1/get_config` → returns non-empty `session_id` and `user_sig`.
+4. **Text injection** — After starting AI, call `POST /api/v1/agent/control { text: "ping" }` expecting `delivered: true`.
+5. **Graceful stop** — `POST /api/v1/agent/stop` returns `status: "stopped"`.
+
+On any step failure, the Agent must output a diagnostic JSON:
+
+```json
+{ "step": "get_config", "error": "...", "remediation": "Check that TRTC_SDK_APP_ID in .env is an integer" }
+```
+
+---
+
+## Appendix A · Error Code Dictionary
+
+| Error Code | Meaning | Remediation |
+|:---|:---|:---|
+| E001 | Tencent Cloud SecretId/SecretKey invalid | Re-run `python scripts/setup-credentials.py` |
+| E002 | TRTC SDKAppID/SDKSecretKey invalid or UserSig generation failed | Verify SDKAppID is an integer; SecretKey is complete |
+| E003 | LLM API Key invalid | Check that `LLM_API_URL` is an OpenAI-compatible endpoint |
+| E004 | Network unreachable | Check egress IP whitelist / proxy |
+| E005 | Service not activated | Enable Conversational AI in TRTC Console |
+
+## Appendix B · Security Compliance
+
+- Credentials only from environment variables (`security.credential_storage.source = env-only`)
+- Credential cache and `.env` file enforced to permission `0600`
+- End-to-end HTTPS (`security.network.enforce_https = true`)
+- Log redaction filter installed at process startup (see `src/log_filter.py`)
+- XSS / Prompt Injection protection switches declared in `security.injection_protection`

package/skills/trtc-ai-service/capabilities/conversation-core/INTERFACE_ADAPT.md

@@ -0,0 +1,111 @@
+# conversation-core Interface Adaptation SOP
+
+> Skeleton-layer interface adaptation guide. In this release, conversation-core has **not been refactored to ports/adapters/core** (Phase 1 compromise, deferred to Phase 4),
+> so this document only explains "which interfaces can be replaced and how", without providing automated generation entry points.
+
+---
+
+## 1. Default Contract Overview
+
+| Contract | Method | Path | Adaptable? |
+|---|---|---|---|
+| `llm.chat_completions`        | POST | `/v1/chat/completions` (OpenAI-compatible)        | **Adaptable** |
+| `trtc.start_ai_conversation`  | POST | Tencent Cloud TencentCloudAPI                     | **Not adaptable** (tightly bound to Tencent Cloud) |
+
+Full field definitions in `manifest.yaml.business_contract.external_apis`.
+
+---
+
+## 2. LLM Interface Replacement (most common)
+
+The skeleton calls LLM using the OpenAI Chat Completions protocol by default:
+- Default `LLM_API_URL = https://api.openai.com/v1/chat/completions`
+- Supports any OpenAI-compatible proxy (DeepSeek / Qwen / Tencent Hunyuan OpenAPI / vLLM etc.)
+
+### 2.1 OpenAI-Compatible Protocol (recommended path)
+
+Only need to switch environment variables — **no code changes required**:
+
+```bash
+# Switch to DeepSeek
+export LLM_API_URL=https://api.deepseek.com/v1/chat/completions
+export LLM_API_KEY=sk-xxx
+export LLM_MODEL=deepseek-chat
+
+# Switch to Qwen (DashScope OpenAI-compatible endpoint)
+export LLM_API_URL=https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions
+export LLM_API_KEY=sk-xxx
+export LLM_MODEL=qwen-turbo
+
+# Switch to self-hosted vLLM
+export LLM_API_URL=http://your-vllm:8000/v1/chat/completions
+export LLM_API_KEY=any-string
+export LLM_MODEL=Qwen2.5-7B-Instruct
+```
+
+> Security: Self-hosted LLM must use https://; http only allowed for localhost. See `security_rules`.
+
+### 2.2 Non-OpenAI Protocols (e.g. Claude Anthropic Messages API)
+
+Requires introducing an "LLM protocol adapter" at the skeleton layer. This mechanism is not delivered in this release; temporary workaround:
+
+1. Deploy an OpenAI ↔ Anthropic protocol translation gateway (e.g. LiteLLM) in the user project
+2. Point the skeleton's `LLM_API_URL` to the gateway
+3. The gateway handles protocol translation
+
+```bash
+# Launch LiteLLM gateway (see https://docs.litellm.ai/)
+litellm --model anthropic/claude-3-5-sonnet --port 4000
+
+# Skeleton configuration
+export LLM_API_URL=http://localhost:4000/v1/chat/completions
+export LLM_API_KEY=sk-anthropic-xxx
+export LLM_MODEL=anthropic/claude-3-5-sonnet
+```
+
+### 2.3 Phase 4 Plan: LLM Adapter Abstraction
+
+The skeleton will introduce a `LlmClient` abstraction (same pattern as human-handoff / knowledge-base):
+
+```
+capabilities/conversation-core/src/
+├── ports/
+│   └── llm_client.py          # ABC: chat / stream_chat / count_tokens
+└── adapters/
+    ├── openai_compat.py       # Current default implementation
+    ├── claude_anthropic.py    # Native Anthropic Messages API
+    ├── tencent_hunyuan.py     # Tencent Hunyuan native OpenAPI
+    └── user_custom.py         # User integration wizard generator
+```
+
+This document will be supplemented with automated adaptation workflows at that time.
+
+---
+
+## 3. TRTC Conversational AI Control Plane (Not Adaptable)
+
+`trtc.start_ai_conversation` / `StopAIConversation` / `ControlAIConversation` /
+`ServerPushText` and other control plane interfaces are **tightly bound to the Tencent Cloud protocol**. If the user's business does not use TRTC,
+they should not continue using this capability package; suggest switching to a text-only conversation approach (using conversation-core's
+`text_input` / `text_output` channels, bypassing the TRTC control plane).
+
+---
+
+## 4. ASR / TTS Service Replacement
+
+The skeleton uses TRTC's built-in ASR/TTS by default (declared via `STTConfig` / `TTSConfig` in StartAIConversation
+requests). To switch to your own ASR/TTS, replace the provider name in the manifest's
+`config.io_modality.voice_input.provider` / `voice_output.provider` fields and implement
+a custom provider extension in the user project per the TRTC ConversationAI documentation.
+
+Custom provider scaffolding is not provided in this release.
+
+---
+
+## 5. Security Checklist
+
+- [ ] All 3 keys come from environment variables only — **no hardcoding**
+- [ ] `LLM_API_URL` must use https:// or http://localhost
+- [ ] Reject private network addresses for self-hosted LLM (except localhost)
+- [ ] `LLM_API_KEY` / `Authorization` headers auto-redacted in logs (handled by skeleton `log_redaction`)
+- [ ] Credential cache file permissions enforced to 600

package/skills/trtc-ai-service/capabilities/conversation-core/QUICK_START.md

@@ -0,0 +1,62 @@
+# conversation-core · Quick Start
+
+> Configure → Run → Verify, done in three steps.
+
+## 0. Prerequisites
+
+- Python ≥ 3.9
+- Activated: Tencent Cloud account + TRTC Conversational AI application + any OpenAI-compatible LLM service
+
+## 1. Install
+
+```bash
+# From repo root
+pip install -r capabilities/conversation-core/requirements.txt
+```
+
+## 2. Configure the 3 Keys
+
+```bash
+python scripts/setup-credentials.py
+```
+
+The script interactively guides you through `[1/3] Tencent Cloud → [2/3] TRTC → [3/3] LLM` in order,
+running a self-check immediately after each key is entered. On failure, it won't proceed to the next key;
+if interrupted mid-way, re-running it will auto-skip keys that already passed (checkpoint resume).
+
+Output artifacts on success:
+
+| Path | Contents | Permissions |
+|:---|:---|:---:|
+| `.env` | Environment variable declarations for the 3 keys | 600 |
+| `.credentials_cache` | SHA256 hashes of verified keys | 600 |
+| `config-report.json` | Verification timestamp / latency / status for each key | 644 |
+
+## 3. Launch Web Demo
+
+```bash
+bash start.sh
+# Equivalent to:
+# cd capabilities/conversation-core && python -m src.server
+```
+
+Open <http://localhost:3000> in your browser.
+
+## 4. Acceptance Criteria
+
+- [x] ASR/LLM/TTS pipeline has no hard-coded business logic (protocol passthrough only)
+- [x] `setup-credentials.py` supports real-time connectivity self-check and checkpoint resume
+- [x] Web Demo top status bar: all three indicator LEDs green
+- [x] manifest.yaml includes skeleton type / injection points / modality / security declarations
+- [x] INTEGRATION.md provides Agent-readable detection logic and three-level degradation path
+- [x] `.credentials_cache` / `.env` permissions 600; no plain-text keys in logs
+
+## 5. Next Steps
+
+Overlay business capability packages at the 5 injection points declared in `manifest.yaml.injection_points`:
+
+```bash
+voice-agent add knowledge-base
+voice-agent add tool-calling
+voice-agent add human-handoff
+```

package/skills/trtc-ai-service/capabilities/conversation-core/manifest.yaml

@@ -0,0 +1,250 @@
+# conversation-core capability self-describing manifest
+# Type: skeleton (always installed by default; no built-in business scenarios)
+
+name: "conversation-core"
+version: "1.0.0"
+type: "skeleton"
+description: "Generic Voice Agent skeleton providing ASR/LLM/TTS/session management core capabilities without any built-in business logic"
+
+# ---------------------------------------------------------------------------
+# Dependency declaration
+# ---------------------------------------------------------------------------
+dependencies: []   # Skeleton layer has no dependencies
+
+# ---------------------------------------------------------------------------
+# Injection points (for Phase 2 capability overlay)
+# Convention: position field uses before:function_name / after:function_name / replace:function_name
+# ---------------------------------------------------------------------------
+injection_points:
+  - id: "agent.before_start"
+    target: "src/agent.py"
+    position: "before:_ext_before_start_"
+    description: "Inject code inside the start_agent method body (e.g. prepend KB search results to instructions); anchor is inside start_agent method body to ensure access to local variables like config/info"
+
+  - id: "agent.after_start"
+    target: "src/agent.py"
+    position: "before:_ext_after_start_"
+    description: "Inject session-level hooks after the AI task is successfully launched (e.g. initialize human handoff state machine); anchor is inside start_agent method body"
+
+  - id: "agent.before_push_text"
+    target: "src/agent.py"
+    position: "before:_ext_before_push_text_"
+    description: "Intercept before text injection is sent (e.g. keyword-triggered handoff / tool calling); anchor is inside push_text method body"
+
+  - id: "server.router_extension"
+    target: "src/server.py"
+    position: "after:app.include_router"
+    description: "Append business capability FastAPI sub-routers"
+
+  - id: "modality.channel_resolver"
+    target: "src/modality.py"
+    position: "replace:resolve_input_channel"
+    description: "Override default channel selection strategy, e.g. disable voice input in e-commerce scenarios"
+
+# ---------------------------------------------------------------------------
+# Configuration interface
+# ---------------------------------------------------------------------------
+config:
+  credentials:
+    - key: "TENCENT_CLOUD_SECRET_ID"
+      required: true
+      description: "Tencent Cloud API SecretId (Key 1)"
+    - key: "TENCENT_CLOUD_SECRET_KEY"
+      required: true
+      description: "Tencent Cloud API SecretKey (Key 1)"
+    - key: "TENCENT_CLOUD_REGION"
+      required: false
+      default: "ap-guangzhou"
+      description: "Tencent Cloud API region"
+    - key: "TRTC_SDK_APP_ID"
+      required: true
+      description: "TRTC Conversational AI application SDKAppID (Key 2)"
+    - key: "TRTC_SDK_SECRET_KEY"
+      required: true
+      description: "TRTC Conversational AI application SDKSecretKey (Key 2)"
+    - key: "LLM_API_KEY"
+      required: true
+      description: "External LLM access key (Key 3)"
+    - key: "LLM_API_URL"
+      required: false
+      default: "https://api.openai.com/v1/chat/completions"
+      description: "OpenAI-compatible protocol endpoint"
+    - key: "LLM_MODEL"
+      required: false
+      default: "gpt-4o-mini"
+      description: "Default LLM model name"
+
+  io_modality:
+    voice_input:
+      enabled: true
+      provider: "trtc-asr"
+      fallback: "text_input"
+      timeout_ms: 5000
+    text_input:
+      enabled: true
+      provider: null
+      fallback: null
+      timeout_ms: 0
+    voice_output:
+      enabled: true
+      provider: "trtc-tts"
+      fallback: "text_output"
+      timeout_ms: 3000
+    text_output:
+      enabled: true
+      provider: null
+      fallback: null
+      timeout_ms: 0
+
+# ---------------------------------------------------------------------------
+# Exposed API endpoints
+# ---------------------------------------------------------------------------
+endpoints:
+  - method: GET
+    path: /api/v1/health
+    description: Real-time connectivity self-check for 3 keys (Web Demo status bar data source)
+  - method: POST
+    path: /api/v1/get_config
+    description: Issue room number / UserSig / modality configuration
+  - method: POST
+    path: /api/v1/agent/start
+    description: Start AI channel bot (StartAIConversation)
+  - method: POST
+    path: /api/v1/agent/stop
+    description: Stop AI channel bot (StopAIConversation)
+  - method: POST
+    path: /api/v1/agent/control
+    description: Text injection / interruption (ControlAIConversation/ServerPushText)
+  - method: GET
+    path: /api/v1/sessions
+    description: In-memory session list (debugging only)
+
+# ---------------------------------------------------------------------------
+# Tech stack integration rules
+# ---------------------------------------------------------------------------
+integration:
+  mode: "auto"
+  auto_adapters:
+    - tech_stack: ["react", "vue", "angular"]
+      adapter: "frontend-spa"
+      description: "Frontend SPA adapter, generates join-room component and embeds web-demo to call skeleton API"
+    - tech_stack: ["express", "koa", "fastify", "next"]
+      adapter: "node-backend"
+      description: "Node.js backend adapter, generates proxy routes forwarding to skeleton /api/v1/*"
+    - tech_stack: ["spring-boot", "quarkus"]
+      adapter: "java-backend"
+      description: "Java backend adapter, generates Filter forwarding to skeleton"
+    - tech_stack: ["flask", "fastapi", "django"]
+      adapter: "python-backend"
+      description: "Python backend adapter, generates decorators or sub-app mounting"
+  fallback:
+    guided_templates:
+      - "integration-templates/generic-frontend.md"
+      - "integration-templates/generic-backend.md"
+    manual_api:
+      rest_endpoint: "/api/v1"
+      sdk_packages:
+        - npm: "@trtc/voice-agent-sdk"
+        - maven: "com.tencent.trtc:voice-agent-sdk"
+        - pypi: "trtc-voice-agent"
+
+# ---------------------------------------------------------------------------
+# Business contract (Phase 3; follows references/business-contract-spec.md v1.0)
+# Note: This is a skeleton capability; source code is not refactored in this phase;
+# only declares the external contract for contract-adapt.py consumption.
+# port_class / default_adapter fields remain null, to be filled in Phase 4 refactor.
+# ---------------------------------------------------------------------------
+business_contract:
+  port_class: null
+  default_adapter: null
+  mock_adapter: null
+  customization_sop: "INTERFACE_ADAPT.md"
+  external_apis:
+    # LLM: OpenAI-compatible protocol is the default contract; can be replaced with Claude / Qwen / DeepSeek etc.
+    - name: llm.chat_completions
+      direction: outbound
+      method: POST
+      path: /v1/chat/completions
+      description: "Call external LLM for text response (OpenAI Chat Completions compatible protocol)"
+      request_schema:
+        model: string
+        messages:
+          - role: enum[system, user, assistant, tool]
+            content: string
+        temperature: float
+        max_tokens: int
+        stream: bool
+      response_schema:
+        choices:
+          - message:
+              role: string
+              content: string
+            finish_reason: string
+        usage:
+          prompt_tokens: int
+          completion_tokens: int
+      adapter_slots:
+        - request.model
+        - request.messages
+        - response.choices
+      auth:
+        type: bearer
+        location: header
+        name: Authorization
+      timeout_ms: 30000
+
+    # Tencent Cloud TRTC Conversational AI (control plane): StartAIConversation etc.
+    # Unlike LLM, the TRTC control plane contract is not adaptable (tightly bound to Tencent Cloud);
+    # declared here only for assembly-phase awareness
+    - name: trtc.start_ai_conversation
+      direction: outbound
+      method: POST
+      path: "tencentcloudapi.com/?Action=StartAIConversation"
+      description: "Tencent Cloud TRTC control plane: launch AI conversation (tightly bound to Tencent Cloud protocol, not adaptable)"
+      request_schema:
+        SdkAppId: int
+        RoomId: string
+        AgentConfig: object
+        STTConfig: object
+        LLMConfig: object
+        TTSConfig: object
+      response_schema:
+        TaskId: string
+        SessionId: string
+      adapter_slots: []        # No remapping allowed
+      timeout_ms: 10000
+
+# ---------------------------------------------------------------------------
+# Security declarations (P0 mitigations in place)
+# ---------------------------------------------------------------------------
+security:
+  log_redaction:
+    enabled: true
+    patterns:
+      - "secret_id"
+      - "secret_key"
+      - "api_key"
+      - "app_key"
+      - "token"
+      - "usersig"
+      - "credential"
+      - "authorization"
+  injection_protection:
+    xss_guard: true
+    prompt_injection_guard: true
+  credential_storage:
+    source: "env-only"     # Credentials only from environment variables
+    cache_file: ".credentials_cache"
+    cache_permission: "0600"
+    env_file_permission: "0600"
+  network:
+    enforce_https: true    # End-to-end HTTPS
+
+# ---------------------------------------------------------------------------
+# Acceptance criteria (aligned with dev guide §11.1)
+# ---------------------------------------------------------------------------
+acceptance:
+  - "ASR/LLM/TTS pipeline has no hard-coded business logic"
+  - "3-key connectivity self-check executed immediately upon input"
+  - "Web Demo top status bar: all 3 indicator LEDs green"
+  - "Credential cache file permissions set to 600; no plain-text keys in logs"

package/skills/trtc-ai-service/capabilities/conversation-core/requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.110.0
+uvicorn[standard]>=0.27.0
+pydantic>=2.5.0
+python-dotenv>=1.0.0
+requests>=2.31.0
+PyYAML>=6.0