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

package/skills/trtc-ai-service/auto_adapters/README.md

@@ -0,0 +1,40 @@
+# auto_adapters - Tech Stack Decoupling Adapter Component Library
+
+> Read by the Agent during the integration phase. Based on the tech stack identified by `stack_detector`,
+> selects the corresponding adapter, renders template code, and injects it into the user's project.
+
+## Adapter Index
+
+| Adapter | Matching Tech Stack | Injected Artifact | Default Target |
+|:---|:---|:---|:---|
+| `frontend-spa` | `react` / `vue` / `angular` / `next` | `VoiceAgent.{tsx,vue,ts}` component | `src/components/` |
+| `node-backend` | `express` / `koa` / `fastify` | Reverse proxy middleware | `routes/voice-agent.js` |
+| `java-backend` | `spring-boot` / `quarkus` | `Filter` or `Quarkus Filter` | `src/main/java/.../VoiceAgentFilter.java` |
+| `python-backend` | `flask` / `fastapi` / `django` | Decorator / sub-router | `voice_agent_proxy.py` |
+
+## Template Rendering Variables
+
+All `.tpl` files use `${VAR}` placeholders (to avoid conflicts with JS / Python `{{}}`):
+
+| Variable | Default | Description |
+|:---|:---|:---|
+| `${SKELETON_BASE_URL}` | `http://localhost:3000` | conversation-core process address |
+| `${API_PREFIX}` | `/api/v1` | Skeleton REST prefix |
+| `${COMPONENT_NAME}` | `VoiceAgent` | Frontend component name |
+| `${ROUTE_PREFIX}` | `/voice-agent` | Backend proxy route prefix |
+
+## Three-Level Degradation Chain
+
+```
+L1 Full Auto:  stack_detector.primary matched → adapter.render() → write to user project
+       │
+       │  Failed (syntax conflict / path conflict)
+       ▼
+L2 Semi-Auto:  Output INTEGRATION_GUIDE.md (based on integration_templates/generic-*.md)
+       │
+       │  stack_detector.primary is None
+       ▼
+L3 Manual API: Output integration_templates/generic-rest-api.md
+```
+
+See `scripts/lib/degrader.py` and `scripts/add-capability.py` for details.

package/skills/trtc-ai-service/auto_adapters/frontend-spa/README.md

@@ -0,0 +1,27 @@
+# frontend-spa Adapter
+
+> Connect the conversation-core skeleton REST API to any frontend SPA.
+> The Agent selects the appropriate subdirectory template based on the current `tech_stack` during the L1 phase and renders it into the user's project.
+
+| tech_stack | Template | Default Target |
+|:---|:---|:---|
+| react / next | `react/VoiceAgent.tsx.tpl` | `src/components/${COMPONENT_NAME}.tsx` |
+| vue          | `vue/VoiceAgent.vue.tpl`   | `src/components/${COMPONENT_NAME}.vue` |
+| angular      | `angular/voice-agent.component.ts.tpl` | `src/app/voice-agent/voice-agent.component.ts` |
+
+## Dependency Installation (written by Agent into package.json)
+
+- `trtc-sdk-v5 >= 5.0.0`
+
+## Security
+
+- Templates use `${SKELETON_BASE_URL}` for fetch; in production this must be replaced with an HTTPS address (skeleton manifest `security.network.enforce_https = true`).
+- TRTC SDK requires a wss channel; allow in CSP:
+  ```
+  connect-src https://${SKELETON_BASE_URL} wss://*.trtc.tencent-cloud.com;
+  ```
+
+## Capability Overlay
+
+- With `tool-calling` installed: type `/tool xxx {...}` in the Send box to trigger local tool calls.
+- With `human-handoff` installed: sending keywords like "talk to agent" triggers the queue-and-connect flow.

package/skills/trtc-ai-service/auto_adapters/frontend-spa/angular/voice-agent.component.ts.tpl

@@ -0,0 +1,131 @@
+// voice-agent.component.ts
+// Auto-generated by conversation-core/auto_adapters/frontend-spa (Angular)
+// Connect to TRTC ConversationAI via skeleton REST
+import { Component, OnInit } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+
+const SKELETON_BASE_URL = '${SKELETON_BASE_URL}';
+const API_PREFIX = '${API_PREFIX}';
+
+interface SessionCfg {
+  session_id: string;
+  sdk_app_id: number;
+  room_id: string;
+  user_id: string;
+  user_sig: string;
+}
+
+@Component({
+  selector: 'app-voice-agent',
+  template: `
+    <div style="font-family:system-ui;padding:16px;">
+      <h3>TRTC Voice Agent</h3>
+      <div *ngIf="health" style="display:flex;gap:16px;margin-bottom:8px;">
+        <span *ngFor="let kv of healthEntries">
+          <span [style.color]="kv.status === 'ok' ? '#1ec97c' : '#e74c3c'">●</span>
+          {{ kv.name }}
+        </span>
+      </div>
+      <button *ngIf="!session" (click)="start()">Start</button>
+      <ng-container *ngIf="session">
+        <button (click)="stop()">Stop</button>
+        <input [(ngModel)]="text" placeholder="type message..." style="margin-left:8px;padding:4px;width:240px;" />
+        <button (click)="send()">Send</button>
+      </ng-container>
+      <pre style="background:#111;color:#0f0;padding:8px;height:200px;overflow:auto;">{{ logs.join('\n') }}</pre>
+    </div>
+  `,
+})
+export class VoiceAgentComponent implements OnInit {
+  health: any = null;
+  healthEntries: { name: string; status: string }[] = [];
+  session: SessionCfg | null = null;
+  logs: string[] = [];
+  text = '';
+  trtc: any = null;
+
+  constructor(private http: HttpClient) {}
+
+  log(m: string) {
+    this.logs = [...this.logs.slice(-20), '[' + new Date().toLocaleTimeString() + '] ' + m];
+  }
+
+  ngOnInit() {
+    this.http.get<any>(SKELETON_BASE_URL + API_PREFIX + '/health').subscribe({
+      next: (h) => {
+        this.health = h;
+        this.healthEntries = Object.entries(h.checks || {}).map(([name, v]: [string, any]) => ({
+          name,
+          status: v.status,
+        }));
+      },
+      error: (e) => this.log('health failed: ' + e.message),
+    });
+  }
+
+  async start() {
+    try {
+      const cfg: any = await this.http
+        .post(SKELETON_BASE_URL + API_PREFIX + '/get_config', {})
+        .toPromise();
+      this.session = cfg.data;
+      this.log('session=' + cfg.data.session_id);
+
+      const TRTC = (await import('trtc-sdk-v5')).default;
+      this.trtc = TRTC.create();
+      await this.trtc.enterRoom({
+        roomId: Number(cfg.data.room_id),
+        sdkAppId: cfg.data.sdk_app_id,
+        userId: cfg.data.user_id,
+        userSig: cfg.data.user_sig,
+      });
+      await this.trtc.startLocalAudio();
+      await this.http
+        .post(SKELETON_BASE_URL + API_PREFIX + '/agent/start', {
+          session_id: cfg.data.session_id,
+          language: 'zh',
+        })
+        .toPromise();
+      this.log('agent started');
+    } catch (e: any) {
+      this.log('start failed: ' + e.message);
+    }
+  }
+
+  async stop() {
+    if (!this.session) return;
+    try {
+      await this.http
+        .post(SKELETON_BASE_URL + API_PREFIX + '/agent/stop', {
+          session_id: this.session.session_id,
+        })
+        .toPromise();
+      if (this.trtc) {
+        await this.trtc.exitRoom();
+        await this.trtc.destroy();
+        this.trtc = null;
+      }
+      this.session = null;
+      this.log('stopped');
+    } catch (e: any) {
+      this.log('stop failed: ' + e.message);
+    }
+  }
+
+  async send() {
+    if (!this.session || !this.text.trim()) return;
+    try {
+      await this.http
+        .post(SKELETON_BASE_URL + API_PREFIX + '/agent/control', {
+          session_id: this.session.session_id,
+          text: this.text,
+          interrupt: true,
+        })
+        .toPromise();
+      this.log('pushed: ' + this.text);
+      this.text = '';
+    } catch (e: any) {
+      this.log('push failed: ' + e.message);
+    }
+  }
+}

package/skills/trtc-ai-service/auto_adapters/frontend-spa/manifest.yaml

@@ -0,0 +1,57 @@
+# frontend-spa adapter manifest
+# Rendered by Agent when targeting a frontend SPA project (React / Vue / Angular / Next).
+
+name: "frontend-spa"
+version: "1.0.0"
+target_role: "frontend"
+tech_stack: ["react", "vue", "angular", "next"]
+
+# Render entries: tech_stack -> template file + default target path + install hints
+templates:
+  react:
+    file: "react/VoiceAgent.tsx.tpl"
+    target_path: "src/components/${COMPONENT_NAME}.tsx"
+    install_hint: |
+      In your root component render section, add:
+        import { ${COMPONENT_NAME} } from './components/${COMPONENT_NAME}';
+        <${COMPONENT_NAME} />
+    package_dependencies:
+      - "trtc-sdk-v5@>=5.0.0"
+  next:
+    file: "react/VoiceAgent.tsx.tpl"
+    target_path: "components/${COMPONENT_NAME}.tsx"
+    install_hint: |
+      In app/page.tsx (or pages/index.tsx):
+        'use client';
+        import dynamic from 'next/dynamic';
+        const ${COMPONENT_NAME} = dynamic(() => import('@/components/${COMPONENT_NAME}'), { ssr: false });
+    package_dependencies:
+      - "trtc-sdk-v5@>=5.0.0"
+  vue:
+    file: "vue/VoiceAgent.vue.tpl"
+    target_path: "src/components/${COMPONENT_NAME}.vue"
+    install_hint: |
+      In parent component:
+        <script setup>import ${COMPONENT_NAME} from './components/${COMPONENT_NAME}.vue'</script>
+        <template><${COMPONENT_NAME} /></template>
+    package_dependencies:
+      - "trtc-sdk-v5@>=5.0.0"
+  angular:
+    file: "angular/voice-agent.component.ts.tpl"
+    target_path: "src/app/voice-agent/voice-agent.component.ts"
+    install_hint: |
+      Add VoiceAgentComponent to your NgModule's declarations;
+      use <app-voice-agent></app-voice-agent> in your template.
+    package_dependencies:
+      - "trtc-sdk-v5@>=5.0.0"
+
+# 默认变量（被顶层 default_variables 覆盖）
+defaults:
+  SKELETON_BASE_URL: "http://localhost:3000"
+  API_PREFIX: "/api/v1"
+  COMPONENT_NAME: "VoiceAgent"
+
+# 安全
+security:
+  csp_hint: "TRTC SDK 需要允许 wss://*.trtc.tencent-cloud.com 与 https://${SKELETON_BASE_URL}"
+  https_required: true

package/skills/trtc-ai-service/auto_adapters/frontend-spa/react/VoiceAgent.tsx.tpl

@@ -0,0 +1,142 @@
+// ${COMPONENT_NAME}.tsx
+// Auto-generated by conversation-core/auto_adapters/frontend-spa
+// Connect to TRTC ConversationAI via skeleton REST (minimal join-room + status display, non-business version)
+// Install dependency: trtc-sdk-v5
+import React, { useEffect, useRef, useState } from 'react';
+
+const SKELETON_BASE_URL = '${SKELETON_BASE_URL}';
+const API_PREFIX = '${API_PREFIX}';
+
+interface HealthResp {
+  status: 'ok' | 'partial_failure' | string;
+  checks: Record<string, { status: string; latency_ms: number | null; error?: string }>;
+}
+
+interface SessionConfig {
+  session_id: string;
+  sdk_app_id: number;
+  room_id: string;
+  user_id: string;
+  user_sig: string;
+  agent_user_id: string;
+}
+
+export const ${COMPONENT_NAME}: React.FC = () => {
+  const [health, setHealth] = useState<HealthResp | null>(null);
+  const [session, setSession] = useState<SessionConfig | null>(null);
+  const [logs, setLogs] = useState<string[]>([]);
+  const [text, setText] = useState('');
+  const trtcRef = useRef<any>(null);
+
+  const log = (msg: string) =>
+    setLogs((prev) => [...prev.slice(-20), '[' + new Date().toLocaleTimeString() + '] ' + msg]);
+
+  const callJson = async (path: string, body?: unknown) => {
+    const resp = await fetch(SKELETON_BASE_URL + API_PREFIX + path, {
+      method: body ? 'POST' : 'GET',
+      headers: { 'Content-Type': 'application/json' },
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!resp.ok) throw new Error(path + ' -> HTTP ' + resp.status);
+    return resp.json();
+  };
+
+  useEffect(() => {
+    callJson('/health').then(setHealth).catch((e) => log('health failed: ' + e.message));
+  }, []);
+
+  const start = async () => {
+    try {
+      const cfg = await callJson('/get_config', {});
+      const data: SessionConfig = cfg.data;
+      setSession(data);
+      log('session=' + data.session_id + ' room=' + data.room_id);
+
+      // Join room (user side)
+      const TRTC = (await import('trtc-sdk-v5')).default;
+      const trtc = TRTC.create();
+      trtcRef.current = trtc;
+      await trtc.enterRoom({
+        roomId: Number(data.room_id),
+        sdkAppId: data.sdk_app_id,
+        userId: data.user_id,
+        userSig: data.user_sig,
+      });
+      await trtc.startLocalAudio();
+      log('entered room');
+
+      // Start AI channel bot
+      await callJson('/agent/start', { session_id: data.session_id, language: 'zh' });
+      log('agent started');
+    } catch (e: any) {
+      log('start failed: ' + e.message);
+    }
+  };
+
+  const stop = async () => {
+    if (!session) return;
+    try {
+      await callJson('/agent/stop', { session_id: session.session_id });
+      if (trtcRef.current) {
+        await trtcRef.current.exitRoom();
+        await trtcRef.current.destroy();
+        trtcRef.current = null;
+      }
+      log('stopped');
+      setSession(null);
+    } catch (e: any) {
+      log('stop failed: ' + e.message);
+    }
+  };
+
+  const send = async () => {
+    if (!session || !text.trim()) return;
+    try {
+      await callJson('/agent/control', {
+        session_id: session.session_id,
+        text,
+        interrupt: true,
+      });
+      log('text pushed: ' + text);
+      setText('');
+    } catch (e: any) {
+      log('push failed: ' + e.message);
+    }
+  };
+
+  return (
+    <div style={{ fontFamily: 'system-ui', padding: 16 }}>
+      <h3>TRTC Voice Agent</h3>
+      <div style={{ display: 'flex', gap: 16, marginBottom: 8 }}>
+        {health
+          ? Object.entries(health.checks).map(([k, v]) => (
+              <span key={k}>
+                <span style={{ color: v.status === 'ok' ? '#1ec97c' : '#e74c3c' }}>●</span>
+                {' '}
+                {k}
+              </span>
+            ))
+          : 'loading...'}
+      </div>
+      {!session ? (
+        <button onClick={start}>Start</button>
+      ) : (
+        <>
+          <button onClick={stop}>Stop</button>
+          <input
+            value={text}
+            onChange={(e) => setText(e.target.value)}
+            placeholder="type message..."
+            style={{ marginLeft: 8, padding: 4, width: 240 }}
+          />
+          <button onClick={send}>Send</button>
+        </>
+      )}
+      <pre style={{ background: '#111', color: '#0f0', padding: 8, height: 200, overflow: 'auto' }}>
+        {logs.join('\n')}
+      </pre>
+    </div>
+  );
+};
+
+export default ${COMPONENT_NAME};

package/skills/trtc-ai-service/auto_adapters/frontend-spa/vue/VoiceAgent.vue.tpl

@@ -0,0 +1,121 @@
+<!-- ${COMPONENT_NAME}.vue
+     Auto-generated by conversation-core/auto_adapters/frontend-spa
+     Connect to TRTC ConversationAI via skeleton REST (minimal verification version) -->
+<script setup lang="ts">
+import { onMounted, ref } from 'vue';
+
+const SKELETON_BASE_URL = '${SKELETON_BASE_URL}';
+const API_PREFIX = '${API_PREFIX}';
+
+interface SessionCfg {
+  session_id: string;
+  sdk_app_id: number;
+  room_id: string;
+  user_id: string;
+  user_sig: string;
+}
+
+const health = ref<any>(null);
+const session = ref<SessionCfg | null>(null);
+const logs = ref<string[]>([]);
+const text = ref('');
+const trtc = ref<any>(null);
+
+function log(msg: string) {
+  logs.value = [...logs.value.slice(-20), '[' + new Date().toLocaleTimeString() + '] ' + msg];
+}
+
+async function callJson(path: string, body?: unknown) {
+  const resp = await fetch(SKELETON_BASE_URL + API_PREFIX + path, {
+    method: body ? 'POST' : 'GET',
+    headers: { 'Content-Type': 'application/json' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!resp.ok) throw new Error(path + ' -> HTTP ' + resp.status);
+  return resp.json();
+}
+
+onMounted(async () => {
+  try {
+    health.value = await callJson('/health');
+  } catch (e: any) { log('health failed: ' + e.message); }
+});
+
+async function start() {
+  try {
+    const cfg = await callJson('/get_config', {});
+    session.value = cfg.data;
+    log('session=' + cfg.data.session_id);
+
+    const TRTC = (await import('trtc-sdk-v5')).default;
+    const t = TRTC.create();
+    trtc.value = t;
+    await t.enterRoom({
+      roomId: Number(cfg.data.room_id),
+      sdkAppId: cfg.data.sdk_app_id,
+      userId: cfg.data.user_id,
+      userSig: cfg.data.user_sig,
+    });
+    await t.startLocalAudio();
+    log('entered room');
+
+    await callJson('/agent/start', { session_id: cfg.data.session_id, language: 'zh' });
+    log('agent started');
+  } catch (e: any) { log('start failed: ' + e.message); }
+}
+
+async function stop() {
+  if (!session.value) return;
+  try {
+    await callJson('/agent/stop', { session_id: session.value.session_id });
+    if (trtc.value) {
+      await trtc.value.exitRoom();
+      await trtc.value.destroy();
+      trtc.value = null;
+    }
+    log('stopped');
+    session.value = null;
+  } catch (e: any) { log('stop failed: ' + e.message); }
+}
+
+async function send() {
+  if (!session.value || !text.value.trim()) return;
+  try {
+    await callJson('/agent/control', {
+      session_id: session.value.session_id,
+      text: text.value,
+      interrupt: true,
+    });
+    log('pushed: ' + text.value);
+    text.value = '';
+  } catch (e: any) { log('push failed: ' + e.message); }
+}
+</script>
+
+<template>
+  <div class="voice-agent">
+    <h3>TRTC Voice Agent</h3>
+    <div class="status">
+      <span v-if="health" v-for="(v, k) in health.checks" :key="k">
+        <span :style="{ color: v.status === 'ok' ? '#1ec97c' : '#e74c3c' }">●</span> {{ k }}
+      </span>
+      <span v-else>loading...</span>
+    </div>
+    <div class="actions">
+      <button v-if="!session" @click="start">Start</button>
+      <template v-else>
+        <button @click="stop">Stop</button>
+        <input v-model="text" placeholder="type message..." />
+        <button @click="send">Send</button>
+      </template>
+    </div>
+    <pre class="logs">{{ logs.join('\n') }}</pre>
+  </div>
+</template>
+
+<style scoped>
+.voice-agent { font-family: system-ui; padding: 16px; }
+.status { display: flex; gap: 16px; margin-bottom: 8px; }
+.actions input { margin-left: 8px; padding: 4px; width: 240px; }
+.logs { background: #111; color: #0f0; padding: 8px; height: 200px; overflow: auto; }
+</style>

package/skills/trtc-ai-service/auto_adapters/integration_templates/generic-backend.md

@@ -0,0 +1,45 @@
+# Generic Backend Integration Guide (L2 Semi-Auto)
+
+> When the Agent has identified your backend tech stack but auto-rendering failed, follow these steps to complete the integration.
+> Core idea: mount a reverse proxy route in your web framework that transparently forwards `${ROUTE_PREFIX}/*`
+> to the skeleton process's `${API_PREFIX}/*`.
+
+## 1. Deploy conversation-core Skeleton
+
+```bash
+cd capabilities/conversation-core
+python -m src.server     # Default listens on 0.0.0.0:3000
+```
+
+## 2. Copy Reverse Proxy Template
+
+| Framework | Template |
+|:---|:---|
+| Express   | `auto_adapters/node-backend/express.js.tpl` |
+| Koa       | `auto_adapters/node-backend/koa.js.tpl` |
+| Fastify   | `auto_adapters/node-backend/fastify.js.tpl` |
+| Spring Boot | `auto_adapters/java-backend/springboot/VoiceAgentFilter.java.tpl` |
+| Quarkus   | `auto_adapters/java-backend/quarkus/VoiceAgentFilter.java.tpl` |
+| Flask     | `auto_adapters/python-backend/flask.py.tpl` |
+| FastAPI   | `auto_adapters/python-backend/fastapi.py.tpl` |
+| Django    | `auto_adapters/python-backend/django.py.tpl` |
+
+Replace placeholder variables (`${SKELETON_BASE_URL}` / `${API_PREFIX}` / `${ROUTE_PREFIX}`).
+
+## 3. Register Route
+
+Mount the router / filter / blueprint in your app entry point as described in the template's `install_hint`.
+
+## 4. Security Checklist
+
+- **HTTPS**: Enforce in production.
+- **SSRF**: The skeleton address must not come directly from user input; if connecting to an internal network skeleton, first confirm with the user explicitly.
+- **Request Body Limit**: Default `64KB`, preventing large payloads from overwhelming the ASR/LLM pipeline.
+- **Auth**: Inject auth logic (JWT / API Key) in the reverse proxy; the skeleton itself only trusts requests from the reverse proxy source.
+
+## 5. Verify
+
+```bash
+curl -s http://localhost:8000${ROUTE_PREFIX}/health | jq .status
+# Expected: "ok"
+```

package/skills/trtc-ai-service/auto_adapters/integration_templates/generic-frontend.md

@@ -0,0 +1,51 @@
+# Generic Frontend Integration Guide (L2 Semi-Auto)
+
+> When the Agent has identified your frontend tech stack but auto-rendering failed due to path conflicts or syntax errors,
+> follow these steps to complete the integration manually.
+
+## Step 1 · Install Dependencies
+
+```bash
+npm install trtc-sdk-v5
+```
+
+## Step 2 · Copy Component Template
+
+Choose the corresponding template from `auto_adapters/frontend-spa/` based on your framework:
+
+- React / Next:  `react/VoiceAgent.tsx.tpl`
+- Vue:           `vue/VoiceAgent.vue.tpl`
+- Angular:       `angular/voice-agent.component.ts.tpl`
+
+Copy the template content to your project's components directory and replace these placeholder variables with real values:
+
+| Placeholder | Default | Description |
+|:---|:---|:---|
+| `${SKELETON_BASE_URL}` | `http://localhost:3000` | Skeleton process address |
+| `${API_PREFIX}` | `/api/v1` | Skeleton REST prefix |
+| `${COMPONENT_NAME}` | `VoiceAgent` | Component / file name |
+
+## Step 3 · Mount in Parent Component
+
+```tsx
+import { VoiceAgent } from './components/VoiceAgent';
+
+export default function Page() {
+  return <main><VoiceAgent /></main>;
+}
+```
+
+## Step 4 · CSP & HTTPS
+
+If CSP is deployed in production, append:
+
+```
+connect-src https://${SKELETON_BASE_URL} wss://*.trtc.tencent-cloud.com;
+```
+
+## Step 5 · Verify
+
+Open the page; you should see three LEDs at the top: `tencent_cloud / trtc / llm`.
+Once all are green, click `Start` to join the room and talk to the AI.
+
+If any LED is red, check `.env` and the 3 keys based on the diagnostic JSON output in the page console.