AI Customer Service Skill (v1.2)

This document is the Coding Agent's execution SOP. It also serves as a user-friendly guide reference. For any natural-language intent involving "build / integrate AI customer service," the AI must read this file first before taking action. All script calls must strictly follow §10 Tool Whitelist.

0. Path Baseline (SKILL_ROOT / PROJECT_ROOT) —— 🔴 Top Priority — Read First

All runtime assets of this Skill (capabilities/, scripts/, scenarios/, auto_adapters/, start.sh) reside in the Skill's own directory and are not necessarily at the user's workspace root. The Skill can be installed in arbitrary locations: a project subdirectory, .agents/skills/, .codebuddy/skills/, and will work across IDEs (Claude Code / Codex / Cursor) in the future. Therefore, never assume "Skill root == Workspace root."

0.1 Definition of the Two Roots

Demo path (A) uses SKILL_ROOT (fetch capability sources + start core) and PROJECT_ROOT (where demo artifacts land); Integration path (B) uses SKILL_ROOT (fetch capability sources + start core) and PROJECT_ROOT (integration target). These two may or may not be the same — do not mix them up.

0.2 Hard Rules for Path Usage

1. All commands that call Skill-bundled scripts / assets must use the absolute path of `SKILL_ROOT`, e.g.:

   cd "$SKILL_ROOT" && python3 scripts/add-capability.py ...
   # or
   python3 "$SKILL_ROOT/scripts/add-capability.py" ...

Do not write bare relative paths (e.g., python3 scripts/...) assuming they resolve against the workspace root — that was the root cause of bugs in previous versions.

1. For all command templates in this document that contain $SKILL_ROOT / $PROJECT_ROOT, the Agent must substitute them with actual absolute paths before execution.
2. The scripts themselves (start.sh / add-capability.py / post-install-patch.py) already self-locate

(via __file__ / BASH_SOURCE), so as long as you invoke them with their absolute path, they work regardless of cwd.

1. If SKILL_ROOT cannot be determined immediately, fall back to a one-shot detection (do not ask the user to move directories):

   find "$PWD" -maxdepth 4 -name SKILL.md -path '*ai-service*' 2>/dev/null | head -1

If still not found, ask the user where the Skill is installed. Never ask the user to move the Skill directory to the workspace top level.

1. When to Use This Skill

Trigger conditions (activate this Skill if any match):

• The user message contains one of the §triggers.keywords
• The user message contains "TRTC" and refers to "customer service / after-sales / customer support"
• The user, in a session where this Skill is already loaded, explicitly expresses "let's start / run it / integrate it"

Not applicable (refuse and explain):

• Purely a general voice conversation demo (not customer service business) → direct to the conversation-core README
• Requires digital human / outbound phone calls → not in current scope
• User is in a non-TRTC ecosystem (Agora / Shengwang) → suggest the corresponding Skill

Product positioning note: This Skill encapsulates TRTC Conversational AI (voice) capabilities. The selling point is "voice customer service." Therefore the demo scenario (Path A) is voice-first. If the user only wants plain text and merely reuses the RTC channel, advise them to configure it themselves. This Skill does not generate artifacts for text-only scenarios.

2. Interaction Language Detection (Hard Constraint Throughout the Process)

Purpose: Throughout the setup process, all of the AI's guidance text, ask_followup_question questions / options, prompts, and summaries must follow the natural language of the user's first prompt. Do not hardcode Chinese.

Detection rules (complete after Skill start, before §3; store the result in the internal variable interaction_lang):

• Use the message that triggered this Skill as the basis for detection
• Predominantly Chinese → interaction_lang = zh
• Predominantly English (or other non-Chinese language) → interaction_lang = en (approximate other languages with English)
• If the user explicitly requests a language switch mid-session → update interaction_lang immediately and apply to all subsequent interactions

Scope (must be followed):

Relationship with artifact UI language (only Path A involves UI):

• interaction_lang controls the language of the setup process dialogue.
• Path A artifact UI default language (recipe.yaml metadata.language) defaults to following `interaction_lang`,

unless the user specifies otherwise.

• Path B generates no UI, so there is only "dialogue language," not "artifact UI language." Delivered code comments / READMEs use interaction_lang.

Do not default to Chinese in conversations just because SKILL.md itself is originally written in Chinese. Follow the user's language.

2.5 Prompt Reporting

• Root/host bootstrap handles Prompt reporting and routing. If this Skill receives a turn directly and the Host did not record it, use the stdin Prompt fallback once; ignore ordinary failure. Handle C20 markers per the root dispatcher. On TRTC_REPORTING_NOTICE_REQUIRED_V1, finish the answer first; the installed post-answer Host Hook displays runtime/continuation-notice.md, so do not append or paraphrase it.
• Before a clarification, run the same helper with context --question "<完整问题>"; fixed choices still use ask_followup_question.

3. Environment Check (Fully Automatic — No User Action Needed)

AI guidance text (output the following in interaction_lang):

Before we officially start, the system will automatically check if your runtime environment meets the requirements. You don't need to do anything for this step — just wait a moment.

Checks performed:

• Python version >= 3.9
• Skill directory files are intact
• Whether the three keys (cloud service credentials) have been configured

If all checks pass, we'll automatically move to the next step. If something fails, the system will tell you exactly what's missing and how to fix it.

AI execution actions (substitute $SKILL_ROOT in all commands with the absolute path determined in §0 before execution):

3.1 Python ≥ 3.9

python3 -c "import sys; assert sys.version_info >= (3, 9), sys.version" && echo OK || echo BAD_PY

Fail → tell the user:

Your Python version is too old. You need version 3.9 or above. You can download the latest version at https://www.python.org/downloads/. Once installed, we'll continue.

Do not proceed until the Python version is satisfied.

3.2 SKILL_ROOT Verification

test -f "$SKILL_ROOT/capabilities/conversation-core/manifest.yaml" && echo OK || echo MISSING

• OK → path baseline is correct. Continue.
• MISSING → $SKILL_ROOT was set incorrectly. Use the find fallback from §0.2 item 4 to re-determine SKILL_ROOT, then rerun this check. Only ask the user for the Skill install location if it still fails.

3.3 .env Status

test -f "$SKILL_ROOT/capabilities/conversation-core/.env" && echo OK || echo MISSING

• OK → First run cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py --type all (the file may have been copied from the template but not filled in yet). All ok → tell the user:

I see you've configured your keys before. We can reuse them directly. If you want to reconfigure, just let me know.

Can skip §5 (unless the user explicitly wants to "reconfigure keys"). Any failure → §5 (already-valid entries need not be refilled).

• MISSING → The first step must be §5 Three-Keys Configuration.

4. Path Selection

AI guidance text:

Environment check passed! Now let's make a choice — how would you like to get started?

First required action: Use the ask_followup_question tool to present a single-choice question:

[{
  "id": "path",
  "question": "How would you like to set up your AI customer service?",
  "options": [
    "Quick Start — Get the agent running right away. You'll see the results in your browser (a web chat window + ticket management dashboard). You'll need to configure 3 keys, and the system will automatically install default capabilities. You should see results within 2-3 minutes. Best for first-timers who want to see 'what this thing looks like'",
    "Integrate into My System (backend capabilities only) — If you already have your own website or app and want to plug in the AI customer service 'brain', choose this. The system will provide a set of API interfaces with no web UI generated. You'll need to configure 3 keys, then choose the interaction mode and additional capabilities"
  ],
  "multiSelect": false
}]

• Choose A → Go to §6 (Path A: Quick Start)
• Choose B → Go to §7 (Path B: Integrate into My System)

Fallback when Coding Agent does not support ask_followup_question: List both paths in natural language and collect the user's answer from the conversation. Do not make assumptions.

Key boundaries the AI should proactively explain:

Whichever you choose, I'll walk you through it step by step. Here's a quick summary of the two paths: - Quick Start: I'll generate a complete customer service web interface for you. You'll be able to see and experience it right in your browser. - Integrate into My System: I'll give you the AI customer service backend capabilities only (API interfaces). The UI is yours — I'll hand you the API docs and sample code, and your developers can connect to them directly.

5. Three-Keys Configuration

Trigger condition: §3.3 returned MISSING, or a key was subsequently judged as failed by verify-credentials.py. Substitute $SKILL_ROOT in commands with absolute paths before execution.

AI guidance text:

To get the customer service agent running, you'll need to configure 3 keys — they're the access passes for cloud services. Don't worry, I'll walk you through each one.

We'll go in this order: first register and create the voice agent on the TRTC standalone site (this is the "core"), then get the Tencent Cloud API Key (this is the "control plane" that issues temporary credentials), last the LLM API Key (this is the "brain").

⚠️ Link Usage Red Line (violation = defect): The console URLs below are full URLs with tracking parameters (utm_campaign, _channel_track_key, …). When presenting these links to users, the Agent MUST copy-paste the full URL verbatim — do not simplify, truncate, or strip query parameters. These are marketing attribution entry points; simplifying the links causes tracking data loss.

Console links (VERBATIM):

Never show the 国内站 links to English users. Tell Chinese users to get Key 1 and Key 2 from the same site.

5.1 How Keys Are Collected

Only the SDKAppID is collected in chat. The SDKSecretKey, SecretId / SecretKey and the LLM key / URL / model are typed into .env by the user. Never ask for a secret in chat; if the user pastes one anyway, do not repeat it — ask them to put it in .env instead.

Step 0 · Prepare `.env`. Confirm .env is git-ignored if the project is a git repo (add it to .gitignore first if not), then:

cd "$SKILL_ROOT/capabilities/conversation-core" && (test -f .env || cp .env.example .env) && chmod 600 .env

5.2 Step 1 · Collect the SDKAppID (chat)

Short-circuit: If session already has root-collected sdkappid (non-zero int, from trtc/flows/collect-sdkappid.md), do not ask — just write it.

Otherwise the AI should say (link per the table above):

Key 1 — TRTC Application Credentials. This is the voice channel for your agent. 1. Go to <Key 1 link> and log in / register 2. Create an RTC Engine application (supports Conversational AI) 3. Inside the app, find the SDKAppID (a number) and send me only the SDKAppID

After receiving it (or on short-circuit):

1. Check it is all digits
2. Edit only the TRTC_SDK_APP_ID= and TRTC_REGION= lines of .env (no secrets are in the file yet). TRTC_REGION is derived, never asked: SDKAppID starting with 14 or 16 → cn, any other valid SDKAppID → intl; keep an existing value the user set explicitly
3. On the non-short-circuit path, call python3 "<当前 trtc skill 根目录>/tools/reporting.py" capture-sdkappid --input-stdin --ide <ide> with a JSON-serialized stdin object containing only the explicitly supplied SDKAppID, known product / framework / skillname, source:"domain-fallback", and cwd; never include any secret. Reporting failure must not block integration

5.3 Step 2 · User Fills In the Rest of .env

The AI should say (substitute the absolute path of $SKILL_ROOT/capabilities/conversation-core/.env; links per the table above; translate to Chinese for Chinese users):

SDKAppID saved. Please open this file and fill in the remaining keys yourself, then save and reply "done" — I'll verify them all: <absolute .env path>

>

1. `TRTC_SDK_SECRET_KEY` — the rest of key 1, on the same application page under "Server-side Integration". ⚠️ The server-side SDKSecretKey, not the client-side STSecretKey 2. `TENCENT_CLOUD_SECRET_ID` / `TENCENT_CLOUD_SECRET_KEY` — key 2, Tencent Cloud API credentials (permissions, STS tokens). Same account and site as key 1, no need to register again: - <Key 2 link> 3. `LLM_API_KEY` / `LLM_API_URL` / `LLM_MODEL` — key 3, the "brain". Any OpenAI-compatible provider you already use; all three values must come from the same provider. For OpenAI you can keep the default URL and model

If the user asks where to get an LLM key, show this table (do not pick for them):

Step 3 · Verify. After the user replies, run cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py --type all. Parse per §5.5: all ok:true → continue; any failure → list every failing item at once, ask the user to fix it in `.env` and reply again, then re-run.

5.4 Security Constraints (Red Lines — Violations Are Defects)

• Never ask for a secret in chat — only the SDKAppID is collected there
• Never pass keys as CLI args; verify-credentials.py reads .env itself
• Never echo keys and never read secret values out of .env
• Never log keys; scripts output only ok/error/latency_ms
• .env is chmod 600 (done in Step 0)

5.5 Error Codes → AI Response Templates

On failure, ask the user to fix the entry in `.env` and reply — never ask them to send the key in chat.

6. Path A: Quick Start

User selected A in §4. Default artifact: Voice Customer Service UI (TRTC real connection, FAQ silent RAG, handoff queue animation + simulated connection, product/order business panel). Substitute $SKILL_ROOT in all commands with absolute paths before execution.

AI guidance text (Path A entry point): Alright, going with the Quick Start path! I'll set up the entire customer service system for you. You don't need to do anything — just wait a moment.

>

This path will automatically install the following capabilities: - Conversation capability: The agent can actually understand what you say and respond (because real AI keys are configured) - Human handoff: You'll see the handoff flow and UI (using demo data) - Knowledge base: You'll see KB search results in action (using demo documents) - Session summary: Default-installed in Path A — when a handoff ticket is created, an LLM-generated summary of the conversation is written into the ticket Description so agents see the context immediately

>

Once set up, you'll open your browser and see a full customer service chat interface and a ticket management dashboard.

6.0 Deployment Parameters (Adjustable)

6.1 Step Sequence (6 Steps)

Step 1: Configure the Three Keys

• Tool: execute_command("test -f \"$SKILL_ROOT/capabilities/conversation-core/.env\" && echo OK || echo MISSING")
• Returns OK → Proceed to Step 2
• Returns MISSING → Enter §5 Three-Keys sub-flow, then return to Step 2 when done

Step 2: Assemble Capability Packages

AI should tell the user: Installing dependencies and assembling default capabilities — this should take about 30-60 seconds...

• Tool: execute_command("cd \"$SKILL_ROOT\" && python3 scripts/add-capability.py knowledge-base human-handoff --apply --json")
• Expected: JSON output with all reports[*].errors == [], no fatal injection.error
• Failure handling:
• Circular dependency / version conflict → explain to user based on stderr output; stop
• L2 (templates) → installed to templates directory; tell user where to manually inject
• L3 (manual) → output the path $SKILL_ROOT/auto_adapters/integration_templates/generic-frontend.md

Step 2.5: Post-Install Patch (Must Run)

• Tool: execute_command("cd \"$SKILL_ROOT\" && python3 scripts/post-install-patch.py")
• Expected: returns {"ok": true, ...}
• This script does 3 things:
• Fixes stale extension point injection errors
• Appends recipe default capability config to .env (existing values untouched)
• Verifies server.py's StaticFiles(html=True)

Step 3: UI Overlay (Must Run — Path A Exclusive) —— Default Voice Customer Service UI

• Artifacts deployed to $PROJECT_ROOT/ai-customer-service-demo/ (independent of Skill directory, easy for later edits)
• Tool (one command to create directory and copy):

  execute_command(
    "mkdir -p \"$PROJECT_ROOT\"/ai-customer-service-demo/admin && \
     cp \"$SKILL_ROOT\"/scenarios/customer-service/ui/voice-customer-service/{index.html,app.js,styles.css,data.js,mock-shop.json,tokens.css} \
        \"$PROJECT_ROOT\"/ai-customer-service-demo/ && \
     cp -R \"$SKILL_ROOT\"/scenarios/customer-service/ui/admin-board/. \
           \"$PROJECT_ROOT\"/ai-customer-service-demo/admin/ && \
     echo \"WEB_DEMO_DIR=$PROJECT_ROOT/ai-customer-service-demo\" >> \"$SKILL_ROOT\"/capabilities/conversation-core/.env"
  )

• Expected: $PROJECT_ROOT/ai-customer-service-demo/ contains index.html / app.js / styles.css / data.js / mock-shop.json / tokens.css + admin/ subdirectory, and WEB_DEMO_DIR is written to .env
• Failure handling: check that $SKILL_ROOT/scenarios/customer-service/ui/voice-customer-service/ is intact

Step 4: Proactively List business_contract (enter §9)

Step 5: Start the Demo

AI should tell the user: Starting the customer service system. The first launch needs to install some dependency packages and may take 30-60 seconds. Please wait...

• Tool: execute_command("cd \"$SKILL_ROOT\" && nohup bash start.sh > /tmp/ai-cs-start.log 2>&1 &")
• Tool: execute_command("sleep 8 && curl -sS http://localhost:3000/api/v1/health")
• First launch creates venv + runs pip install, typically takes 30-60s
• If health check fails after sleep 8 → Tool: execute_command("sleep 25 && curl -sS http://localhost:3000/api/v1/health") try again
• Still fails → tail -80 /tmp/ai-cs-start.log check for pip install errors / port conflicts
• Health check returns {"status":"ok",...} → Proceed to Step 6

Step 6: Output Entry List + Trial Suggestions

The AI should say: All done! Your AI customer service agent is up and running. Open the following URLs in your browser to see it in action:

Try saying / typing:
  · "How do I get a refund"        → AI replies; KB silently augments answer
  · "Talk to agent"                → handoff queue + 8s progress bar + simulated connect
  · Click any product / order card → auto-asks the AI about that item

Note: The human handoff and knowledge base are using simulated data, so you won't see real business integration effects. If you want to connect to a real business system, you can start over and choose "B — Integrate into My System."

6.2 Don'ts

• ❌ Use bare relative paths to call scripts (must cd "$SKILL_ROOT" or use absolute paths — see §0)
• ❌ Skip .env check before assembling capability packages
• ❌ Pass any key via command-line arguments to scripts
• ❌ Modify capabilities/*/src/core/ (this is the skeleton layer; do not touch)
• ❌ Skip Step 2.5 (not running post-install-patch.py leaves stale injection errors from add-capability → NameError on startup)
• ❌ Skip Step 3 (not running UI overlay leaves / at the conversation-core built-in voice self-check page → not the intended artifact)
• ❌ Say the admin board URL is /admin/tickets (the correct path is `/static/admin/`)
• ❌ Execute git commit / git push (unless the user explicitly requests it)
• ❌ Echo full key content in chat replies

7. Path B: Integrate into My System (Backend Capabilities Only)

User selected B in §4. Key positioning: Integrate TRTC Conversational AI backend capabilities into the user's existing project (PROJECT_ROOT). - conversation-core is the core: must end-to-end verify the voice conversation pipeline (test until you can actually converse). - Other incremental capabilities (knowledge-base / human-handoff / session-summary / tool-calling): Only deliver interface specifications + mock implementations + sample code. The user replaces them with their own systems as needed. - This path NEVER generates any frontend UI — the UI is the user's own frontend/backend responsibility.

AI guidance text (Path B entry point — must explicitly state boundaries): Alright, going with the "Integrate into My System" path. This path will plug the AI customer service backend capabilities into your existing project.

>

Here's what I'll do: - Install the voice conversation core (conversation-core) and run it end-to-end to confirm it can actually converse - For extra capabilities like knowledge base, human handoff, session summaries, etc., I'll only provide interface specs + mock implementations + sample code. You swap in your own real systems as needed - I will not generate any web UI — the UI is handled by your own project's frontend

>

Now, let's walk through a few steps: first confirm your project, then pick capabilities, and finally choose the interaction mode for the agent.

7.1 Confirm Integration Target (PROJECT_ROOT & Tech Stack)

1. Confirm PROJECT_ROOT (default = current workspace root). If the user's project is in a subdirectory, have them specify it as --target-project.
2. Let the script auto-detect the project tech stack (no manual entry needed):

   cd "$SKILL_ROOT" && python3 scripts/add-capability.py --list --json

Tech stack detection is triggered automatically by --target-project during Step 7.3 assembly (stack_detector). If auto-detection is inaccurate, override with --tech-stack <react|vue|node|python|java|...>.

7.2 Configure Three Keys

• Tool: execute_command("test -f \"$SKILL_ROOT/capabilities/conversation-core/.env\" && echo OK || echo MISSING")
• MISSING → Enter §5 to complete the three keys (voice core hard-depends on all three keys — all are mandatory).

7.3 Capability Selection (Optional Incremental Capabilities — Multi-Select)

The AI should say (using ask_followup_question multi-select mode): Now let's decide what extra capabilities the agent should have. Besides the built-in voice conversation capability, you can add the following. You can pick multiple, or none at all. Without any extras, the agent will only have basic conversation ability.

[{
  "id": "capabilities",
  "question": "Which additional capabilities do you need? (multi-select)",
  "options": [
    "① Knowledge Base — FAQ / KB search",
    "② Human Handoff — Escalate to human + ticket flow",
    "③ Tool Calling — Let AI call your business tools",
    "④ Session Summary — Auto-generate summaries after sessions",
    "(None — just basic conversation)"
  ],
  "multiSelect": true
}]

Made your choice? Just tell me the numbers (e.g., "1, 2, 3" or "all").

Assembly command (renders incremental capability adapters / samples into the user's project):

cd "$SKILL_ROOT" && python3 scripts/add-capability.py <selected capabilities...> \
    --target-project "$PROJECT_ROOT" --apply --json
# If none selected, skip this command (only runs voice core)

• --target-project triggers auto_adapters three-tier fallback rendering:
• L1: Based on detected tech stack, renders room-entry components / backend proxy route examples into $PROJECT_ROOT
• L2: Renders to templates directory and lists TODOs
• L3: Outputs generic integration guide for manual connection
• Parse the returned JSON and tell the user where the files landed

Post-install patch (must run):

cd "$SKILL_ROOT" && python3 scripts/post-install-patch.py

7.4 I/O Modality Selection (Choose the Agent's "Communication Method")

The AI should say (using ask_followup_question single-choice mode): Now let's decide the agent's "communication method" — how will your customer service agent interact with customers? Here are 4 options — pick the one that best fits your business:

[{
  "id": "modality",
  "question": "Which communication method?",
  "options": [
    "① Text-only IM — Chat via text",
    "② Text + TTS — Text replies + voice readout",
    "③ Full Modality — Both text and voice",
    "④ Voice-only Call — Voice call only"
  ],
  "multiSelect": false
}]

Made your choice? Just tell me the number.

7.5 End-to-End Verification (Voice Core — No UI)

Since no UI is provided, voice quality is verified by the user in their own frontend. The Skill-side acceptance criteria are as follows (all three passing = end-to-end verified):

1. Health self-check: GET /api/v1/health — three LEDs (tencent_cloud / trtc / llm) all green
2. Control plane up: POST /api/v1/agent/start returns TaskId / SessionId successfully
3. Integration sample delivered: Room-entry / control sample code rendered per the user's tech stack has landed in $PROJECT_ROOT

Start core:

cd "$SKILL_ROOT" && nohup bash start.sh > /tmp/ai-cs-start.log 2>&1 &
sleep 8 && curl -sS http://localhost:3000/api/v1/health

7.6 Final Deliverables

The AI should say: Assembly complete! Your AI customer service backend capabilities are ready. Here's what has been delivered:

• /api/v1/* backend API contract (output in §9)
• Outbound contract checklist + mock descriptions + replacement guide for each incremental capability
• Integration sample code paths matching your tech stack
• Integration entry point: /docs (Swagger) after launch

What you need to do next: hand the API checklist to your developers and have them follow the documentation to integrate the AI customer service capabilities into your website or app. If you run into issues during integration, come back anytime.

7.7 Don'ts (Path B)

• ❌ Generate any frontend UI / apply voice-customer-service / widget-floating UI (those are Path A only)
• ❌ Use bare relative paths to call scripts (see §0)
• ❌ Replace mock implementations with real business systems on behalf of the user (only provide specs + adapters; the user decides when to swap)
• ❌ Modify capabilities/*/src/core/ skeleton layer

8. Capability Linking: Human Handoff ↔ Session Summary (Implemented)

When human-handoff and session-summary are both installed they automatically link up — no extra configuration by the AI needed. In Path A, session-summary is default-installed (see recipe.yaml install:), so the linkage is active out of the box. In Path B it links up only if the user selected session-summary.

Behavior: When human-handoff creates a ticket, it best-effort triggers session-summary to generate an LLM one-paragraph summary of the conversation (from AI connect → handoff trigger) and writes it into the ticket's `Description` field. When an agent opens the ticket details on the dashboard, they directly see this conversation summary under "Conversation summary" — no separate "Session Summary" block, no manual "Generate Summary" click needed.

Implementation notes (for maintainers):

• Linkage entry point: capabilities/human-handoff/src/summary_link.py (attach_summary_to_ticket)
• Summary generation: capabilities/session-summary/src/summarizer.py → summarize_paragraph(record) (LLM, uses LLM_API_KEY / LLM_API_URL / LLM_MODEL). Falls back to leaving the description unchanged if LLM is not configured or the session has no recorded turns.
• Soft dependency: Dynamically loads session-summary via conversation-core's _capability_loader; not installed / any exception → silently skip, does not affect the main handoff flow
• Dashboard rendering (Path A): admin-board/app.js renders the ticket description as "Conversation summary"; the legacy structured session_summary block has been removed
• The transcript is uploaded by the frontend right before /handoff/request via POST /api/v1/summary/{session_id}/record, so the recorder has the turns to summarize

The LLM summary call runs synchronously inside the ticket-creation chain and may take a few seconds. This is acceptable because the Path A frontend fires /handoff/request without awaiting it (the handoff animation plays in parallel); the ticket Description is populated by the time the agent refreshes the board.

9. API Contract Alignment

Trigger condition: mandatory after assembly is complete. Substitute $SKILL_ROOT in commands with absolute paths before execution.

9.1 List Outbound APIs for Current Capability Packages

Read manifest.yaml.business_contract.external_apis for each capability package. Only list entries where `direction == outbound`, outputting in the following natural language format:

✓ Installed: conversation-core + knowledge-base + human-handoff.
This session uses mock / local implementations as demo data.

Our capability packages call the following external business APIs:

  1. POST   /tickets                      ← human-handoff ticket creation
  2. GET    /tickets/{ticket_id}          ← human-handoff ticket status query
  3. POST   /tickets/{ticket_id}/cancel   ← human-handoff ticket cancellation
  4. POST   /faq/search                   ← knowledge-base FAQ search
  5. GET    /faq                          ← knowledge-base FAQ list
  6. POST   /faq                          ← knowledge-base FAQ create/update
  7. DELETE /faq/{entry_id}               ← knowledge-base FAQ delete

Path B reminder: The contract checklist is one of the core deliverables to the user. Even if the user chooses "run with mocks first," leave this checklist with them.

9.2 Ask the User

The AI should say: Do you want to switch to a real ticketing / knowledge base system? - Connect to my own system and adapt the interfaces accordingly - Run with mock data for now: skip interface adaptation and start directly

Use ask_followup_question single-choice:

• Connect own system → Enter §9.3
• Run with mocks → Jump to §10 (do not change adapter config)

9.3 contract-adapt Flow

1. AI asks "Which capability package to align?" (multi-select: human-handoff / knowledge-base)
2. For each capability package:

• AI asks "Paste your API description: ① curl command ② OpenAPI YAML file path"
• After collecting, write to temp files:
• curl → write_to_file(/tmp/adapt_<cap>.curl.txt, <user's text>)
• OpenAPI → user already has a path; pass it directly
• Tool: execute_command("cd \"$SKILL_ROOT\" && python3 scripts/contract-adapt.py <cap> --curl-file /tmp/adapt_<cap>.curl.txt --json")

or --openapi-file <path>

1. Parse returned JSON:

• {"level":"L1","artifact":"<path>"} → Tell the user "Generated user_custom.py — ready to enable"
• {"level":"L2","artifact":"<path>","todos":[...]} → List TODOs for the user to fill in
• {"level":"L3","guide":"INTERFACE_ADAPT.md#section"} → Have the user follow the documentation

9.4 Enable user_custom

write_to_file append the non-secret lines to $SKILL_ROOT/capabilities/conversation-core/.env; if a token is needed, leave HH_REST_TOKEN= empty and ask the user to fill it in themselves (§5.4):

HH_ADAPTER=user_custom         # or KB_ADAPTER=user_custom
HH_REST_BASE_URL=https://...
HH_REST_TOKEN=                 # if applicable — filled in by the user

10. Launch & Verification

Default port is 3000. Adjust with --port <N> if needed. If port is changed, sync all URLs / health checks below. Substitute $SKILL_ROOT in commands with absolute paths before execution.

10.1 Launch

cd "$SKILL_ROOT" && nohup bash start.sh > /tmp/ai-cs-start.log 2>&1 &
# Custom port: cd "$SKILL_ROOT" && nohup bash start.sh --port 8080 > /tmp/ai-cs-start.log 2>&1 &

10.2 Health Self-Check (first launch needs ≥30s — pip install)

sleep 8 && curl -sS http://localhost:3000/api/v1/health
# If connection refused: wait longer
sleep 25 && curl -sS http://localhost:3000/api/v1/health

Expected: response contains "status":"ok", three LEDs (tencent_cloud / trtc / llm) all ok.

10.3A Path A — All Green → Output Final Message

Setup complete. Open the following URLs:

  · AI Voice Agent     http://localhost:3000             (default)
  · Admin board        http://localhost:3000/static/admin/
  · API docs (Swagger) http://localhost:3000/docs
  · Health probe       http://localhost:3000/api/v1/health

To stop: lsof -ti :3000 -sTCP:LISTEN | xargs kill

Correct entry: The admin dashboard path is /static/admin/ (not /admin/tickets — that route does not exist).

10.3A.1 Path A — Advanced Configuration (Optional: switch STT / LLM / TTS models)

The default Demo uses Tencent's in-house engines for STT / TTS and the LLM you configured in Key 3. If you want to switch to a different model provider — for example, to try a stronger LLM, support a different language via STT, or pick a different voice — this section walks you through the lowest-cost path.

AI should say:

Your default demo is up and running 🎉. Before we call it done, would you like to take a look at advanced configuration? It's completely optional — your current setup works perfectly. But if you want to try a different voice, support another language, or swap to a different LLM, we can do it right now in just a few minutes.

If user says no → output the final wrap-up message (§10.3A.2 below) and end.

If user says yes → walk through the following three sections in order. Each is independent — the user can choose to skip any of them.

#### 10.3A.1.1 Switch STT (Speech-to-Text) model

STT turns the customer's voice into text for the LLM to understand. If you want to recognize a different language (the default is optimized for zh + en), Tencent offers a high-accuracy bigmodel engine with 30+ languages.

AI should say:

Let's start with STT — the speech-to-text engine. Tencent's default is fine for Chinese and English. If you want to support more languages, switch to the bigmodel engine (doc: https://trtc.io/document/69592?product=conversationalai).

>

Supported languages when engine_model_type=bigmodel: zh (Chinese), en (English), yue (Cantonese), ar (Arabic), de (German), fr (French), es (Spanish), pt (Portuguese), id (Indonesian), it (Italian), ko (Korean), ru (Russian), th (Thai), vi (Vietnamese), ja (Japanese), tr (Turkish), hi (Hindi), ms (Malay), nl (Dutch), sv (Swedish), da (Danish), fi (Finnish), pl (Polish), cs (Czech), fil (Filipino), fa (Persian), el (Greek), ro (Romanian), hu (Hungarian), mk (Macedonian). To switch STT engine, append these two lines to your .env and restart the service (no new keys needed): ``bash # STT engine — set engine_model_type=bigmodel to enable multi-language STT_ENGINE_MODEL_TYPE=bigmodel STT_ENGINE_LANGUAGE=zh # pick from the table above ` Then restart: lsof -ti :3000 -sTCP:LISTEN | xargs kill && cd "$SKILL_ROOT" && nohup bash start.sh > /tmp/ai-cs-start.log 2>&1 &`

#### 10.3A.1.2 Switch LLM (Language Model)

The LLM is the "brain" of your customer service agent. You already configured one in Key 3 — if you want to try a different one, the cheapest path is to use the same .env values, just point to a different provider.

AI should say:

For the LLM, swap providers by changing 3 lines in .env — no code change:

Example (DeepSeek — cheapest for Chinese): ``bash LLM_API_KEY=sk-your-key LLM_API_URL=https://api.deepseek.com/v1/chat/completions LLM_MODEL_NAME=deepseek-chat ` Then restart: lsof -ti :3000 -sTCP:LISTEN | xargs kill && cd "$SKILL_ROOT" && nohup bash start.sh > /tmp/ai-cs-start.log 2>&1 &`

#### 10.3A.1.3 Switch TTS (Text-to-Speech) voice

TTS turns the LLM's text replies into voice. Tencent's default voices are good for most cases. If you want a different voice (e.g., a specific timbre, accent, or language), browse the TTS voice library.

AI should say:

For TTS, browse the voice library: https://trtc.io/document/68340?product=conversationalai

>

To switch TTS voice, add to .env and restart: ``bash TTS_VOICE_TYPE=Chinese_Female_Shuanger `> 💡 **Tip**: If you want a non-Chinese voice, make sure you also set STT_ENGINE_MODEL_TYPE=bigmodel and STT_ENGINE_LANGUAGE=<matching code>` in §10.3A.1.1, otherwise the customer's speech and the agent's voice will be in different languages.

10.3A.2 Path A — Final Wrap-up (After All Configuration Done)

All set! Your AI customer service agent is fully configured and running. 🎉

Quick recap of what you have:

  · AI Voice Agent     http://localhost:3000             (default)
  · Admin board        http://localhost:3000/static/admin/
  · API docs (Swagger) http://localhost:3000/docs
  · Health probe       http://localhost:3000/api/v1/health

You can switch STT / LLM / TTS models at any time by editing `.env` and restarting. Have fun! 🚀

To stop: lsof -ti :3000 -sTCP:LISTEN | xargs kill

10.3B Path B — Verification → Output Final Message (No UI)

Backend capabilities integrated. Verification:

  · Health probe       http://localhost:3000/api/v1/health   (3 LEDs green)
  · Control-plane      POST /api/v1/agent/start  → returns TaskId / SessionId
  · API docs (Swagger) http://localhost:3000/docs            (integration entry point)

Delivered to your project ($PROJECT_ROOT):
  · Integration sample code (room entry / control), invocation order: get_config → enter room → agent/start → agent/control → agent/stop
  · Outbound contract checklist + mock descriptions for each incremental capability (swap with your real system as needed)

UI is implemented by your own frontend. Verify voice quality from your frontend after entering a room.
To stop: lsof -ti :3000 -sTCP:LISTEN | xargs kill

11. Common Issues

If you encounter any of the following issues, here are the corresponding solutions:

11.1 Error Recovery Technical Details

#### Can't find assets / "No such file" / scripts won't run

• Root cause: Bare relative paths used; cwd is not SKILL_ROOT (most common issue in older versions).
• Solution: Re-determine the absolute SKILL_ROOT per §0. All commands must cd "$SKILL_ROOT" or use absolute paths. Rerun.
• Never ask the user to move the Skill directory to the workspace top level.

#### .env exists but keys are invalid

1. AI proactively asks "Reconfigure? Keep old values or overwrite all?"
2. Choose "reconfigure" → During §5 flow, ask the user to fix only the failed entries in .env (keep others)
3. Choose "overwrite all" → Backup .env as .env.bak, start from §5 Step 0

#### Port is occupied

• Tool: execute_command("lsof -ti :3000 -sTCP:LISTEN")
• Ask the user "Kill process PID xxx? Or use a different port?"
• Change port: cd "$SKILL_ROOT" && bash start.sh --port 8080
• Kill process: kill <PID> (requires explicit user consent)

#### add-capability reports circular dependency

• Parse "circular dependency among: [...]" from stderr
• Tell the user which capabilities conflict; guide them to modify manifest.yaml.dependencies and retry
• Do not modify any manifest yourself

#### LLM verification failed but user is using a non-OpenAI service

• Ask which service the user is using (DeepSeek / Qwen / Moonshot / Anthropic, etc.)
• Guide them to update LLM_API_URL and LLM_MODEL:
• DeepSeek: https://api.deepseek.com/chat/completions, model: deepseek-chat
• Others: Have the user provide the official base_url + chat completions path
• Rerun: cd "$SKILL_ROOT" && python3 scripts/verify-credentials.py --type llm

#### verify-credentials.py returns E004 (network unreachable)

• Ask if behind a corporate network / need a proxy
• Quick fix: Have the user append HTTPS_PROXY=... to .env
• TRTC deep verification failure can be downgraded: --no-deep for local UserSig self-consistency check only

#### NameError: name 'session_id' is not defined after startup

• Root cause: Stale injection position from older version
• Solution: Run cd "$SKILL_ROOT" && python3 scripts/post-install-patch.py
• Do not manually edit agent.py — let the patch script handle it

#### contract-adapt.py parse failure

• Outputs {"level":"L3", ...} → Guide the user to read the corresponding capability package's INTERFACE_ADAPT.md
• Do not ask the user to repaste curl more than 2 times. On the 3rd attempt, go directly to L3 manual flow

12. AI Tool Whitelist (Mandatory)

Substitute all $SKILL_ROOT / $PROJECT_ROOT with absolute paths before execution. Always cd "$SKILL_ROOT" or use absolute paths when calling scripts.

12.1 Allowed Commands (execute_command)

12.2 Forbidden Commands

12.3 File Write Whitelist (write_to_file)

Other file writes require explicit user confirmation before writing. Special note: capabilities/conversation-core/src/agent.py and capabilities/conversation-core/src/server.py are the skeleton layer. The AI should not directly edit them by hand.

13. Design Standards Reference (Path A UI Only)

Path B generates no UI. This section does not apply to Path B.

Path A UI must follow $SKILL_ROOT/scenarios/customer-service/ui/design-system/DESIGN_GUIDELINES.md:

13.1 Top Bar LED Tooltip Convention

The 3 LEDs in the top right each show a tooltip on hover:

Final Reminders (for the Coding Agent to internalize): - 🔴 Path baseline first: Determine SKILL_ROOT (= injected Base directory) and PROJECT_ROOT per §0 before anything else. Always cd "$SKILL_ROOT" or use absolute paths for all script/asset commands. Never ask the user to move directories. - At each step, first call the tool to get facts, then explain to the user (don't answer from memory) - Tool call failure → give the user a stderr summary; do not hide errors - Uncertain field / path → use read_file to check the manifest, then answer - Strictly follow §12 Tool Whitelist and §5.4 Security Red Lines throughout - This Skill's selling point is voice; text-only requests → advise the user to configure it themselves; do not generate artifacts - Path A must run all 6 steps. Never skip Step 2.5 (post-install-patch) or Step 3 (UI overlay) - Path B never generates any UI; core end-to-end verified + incremental capabilities provide specs/mocks/samples only - human-handoff legacy API field is state (values: waiting/connected/closed/canceled/timeout), not status/queued/cancelled