Skip to content

Feat/skills improve #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HugoChaan merged 2 commits into from
Mar 25, 2026
Merged

Feat/skills improve #21

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7e36dfa
feat: convoai integration improve
chenyuguo-agora Mar 25, 2026
593f4fb
feat: convoai integration improve
chenyuguo-agora Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@
# Editor
.vscode/
.idea/
.kiro/

# Local testing
*.local.md
Expand Down
83 changes: 57 additions & 26 deletions skills/voice-ai-integration/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,22 @@ license: MIT
metadata:
author: shengwang
version: "1.0.0"
runtime:
required_binaries:
- bash
- curl
- git
network_hosts:
- doc.shengwang.cn
- doc-mcp.shengwang.cn
- gitee.com
required_env:
- SHENGWANG_APP_ID
- SHENGWANG_APP_CERTIFICATE
conditional_env:
- RTC_TOKEN
- provider-specific API keys
- provider-specific service identifiers
---

# Shengwang Integration
Expand All @@ -27,38 +43,30 @@ This file is the documentation index — all doc lookups depend on it.
Do NOT proceed to Step 1 until this file exists or the download has been attempted.
If download fails, proceed with local reference docs and fallback URLs.

### Step 1: Collect kickoff information
### Step 1: Analyze the user's need and choose the product module

Use [intake](intake/README.md) to collect kickoff information.
Use [intake](intake/README.md) only for lightweight needs analysis and product routing.
Ask only for details the user has not already provided.

Collect only the details needed to remove implementation blockers:
- User's use case / target solution
- Main Shengwang product
- Platform or client stack
- Backend language if relevant
- Any key technical details already known that affect routing or implementation
Collect only the details needed to determine:
- the user's use case / target solution
- the primary Shengwang product
- any supporting Shengwang products
- one remaining routing blocker, if the product is still unclear

Use a conversational flow:
- Infer obvious context from the user's request when it is safe to do so
- Ask only for missing details that block routing or implementation
- Stop asking as soon as there is enough information to continue
- Ask only for missing details that change product routing
- Do not ask product-specific configuration questions in the root router
- Stop asking as soon as the correct product module is clear

ConvoAI has a special intake mode:
- If ConvoAI is clearly the primary product, switch to the consolidated ConvoAI intake in [intake/convoai.md](intake/convoai.md)
- Ask for all unresolved kickoff fields plus unresolved ConvoAI provider/config fields in one message
- Show numbered choices for each unresolved field and ask for a one-line numeric reply
- Do not repeat fields the user already answered
- For ConvoAI implementation, prefer the official sample repo, `agent-server-sdk` on the server side, and `agora-agent-client-toolkit` on the client side when the target stack supports it, over building directly from the REST spec
- Treat raw REST as a fallback only for unsupported operations, debugging, or when the user explicitly asks for a REST-first implementation
ConvoAI has a dedicated product module:
- If ConvoAI is clearly the primary product, route to [references/conversational-ai/README.md](references/conversational-ai/README.md)
- The ConvoAI module handles its own internal routing through `request-modes.md` and the appropriate sub-flow
- Do not duplicate ConvoAI-specific quickstart, advanced-feature, or debugging logic in the root router

For ConvoAI, the user must still explicitly answer or confirm any unresolved `Other` follow-up value before implementation.

For unresolved ConvoAI fields with defaults, keep them visible and treat omission as an explicit default confirmation. This includes `Platform = Web` and `Backend = Python`.
If the first consolidated reply is incomplete, ask only a narrow follow-up for the unresolved mandatory blocker.

If the user already gave enough information, do not repeat questions.
Produce a lightweight kickoff recap, then continue automatically unless a required detail is still missing.
If the product mapping is already clear, do not ask extra questions.
Produce a lightweight routing recap, then continue automatically unless one routing blocker is still missing.

### Step 2: Start with local references

Expand All @@ -72,7 +80,7 @@ If the available information is sufficient, begin implementation using the exist
| Credentials, AppID, REST auth | [general](references/general/credentials-and-auth.md) |
| Download SDK, sample project, Token Builder, GitHub repo | Route to the relevant product module |
| Generate Token, token server, AccessToken2, RTC/RTM auth | [token-server](references/token-server/README.md) |
| ConvoAI operation (with details already known) | [conversational-ai](references/conversational-ai/README.md) for SDK/sample-first guidance; use REST docs only as fallback reference |
| ConvoAI voice agent work | [conversational-ai](references/conversational-ai/README.md) for module entry, internal routing, and SDK/sample-first guidance |
| RTC SDK integration | [rtc](references/rtc/README.md) |
| RTM messaging / signaling | [rtm](references/rtm/README.md) |
| Cloud Recording | [cloud-recording](references/cloud-recording/README.md) |
Expand All @@ -93,9 +101,32 @@ Research order:

Once Step 3 provides enough information, proceed with implementation.

## Runtime Requirements

This skill expects the following runtime basics:
- `bash` and `curl` for local doc-fetch helper scripts
- `git` for sample-repo inspection when the sample-aligned path is chosen
- Network access to `doc.shengwang.cn`, `doc-mcp.shengwang.cn`, and `gitee.com` when using doc fetch or sample inspection

Core quickstart prerequisites:
- `SHENGWANG_APP_ID`
- `SHENGWANG_APP_CERTIFICATE`
- ConvoAI service activation in Shengwang Console

Some flows also require conditional credentials such as provider API keys or service identifiers.
Those should always come from environment variables or user-provided secure input, never from hardcoded values.

## Safety & Consent Rules

- Do not clone external repos into the user's main workspace by default. Prefer a temporary path for inspection first.
- Do not modify an existing user project until the user has explicitly asked for code generation or integration work.
- Do not write secrets into project files unless the user explicitly asks for that behavior. Prefer env vars and example placeholders.
- Before performing network fetches or external repo inspection, state what will be downloaded or cloned.
- If a required runtime dependency or credential is missing, stop and explain the blocker instead of improvising around it.

## Download Rules

- Use `git clone --depth 1 <url>` — GitHub URLs must be repo root only (no branch/subdirectory paths)
- Use `git clone --depth 1 <url>` with an HTTPS repo URL by default — GitHub/Gitee URLs must be repo root only (no branch/subdirectory paths)
- On any download failure: report the error, provide the URL for manual download, never silently skip

## Links
Expand Down
144 changes: 55 additions & 89 deletions skills/voice-ai-integration/intake/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,43 @@
# Shengwang Intake — Kickoff Information Collection
# Shengwang Intake — Needs Analysis & Product Routing

First entry point for requests that still need a small amount of information
before implementation can begin.
First entry point for requests that still need lightweight product routing before
implementation begins.

> **Note:** Step 0 doc-index setup is defined in [SKILL.md](../SKILL.md).
> If you are here, Step 0 has already been handled and the root router needs
> a lightweight kickoff summary before moving into implementation research.
> If you are here, Step 0 has already been handled and the root router now needs
> only enough information to decide which Shengwang product module should take over.

---

## Goal

Collect only the minimum missing information needed to proceed.
Do not run a broad discovery interview. Do not ask the user to confirm a full
solution design before continuing.
Use this intake to do **needs analysis and product routing**, not product-specific
solution design.

Ask only for unanswered details that materially affect routing or implementation:
- Use case / target solution
- Main Shengwang product
- Platform or client stack
- Backend language if relevant
- Any key details already known that affect the next step
The top-level intake should answer only these questions:
- What is the user trying to build?
- Which Shengwang product is primary?
- Which supporting products are likely needed?
- Is there one remaining blocker that is still required to choose the right module?

Once those details are gathered, produce a short kickoff summary and continue
to Step 2 automatically unless a required field is still missing.
Do **not** use this layer to collect provider choices, auth strategy, SDK details,
project structure, vendor configuration, or other product-internal implementation
choices unless one of those details is the only remaining routing blocker.

When ConvoAI is clearly the primary product, replace turn-by-turn kickoff with
the consolidated ConvoAI intake in [convoai.md](convoai.md). In that mode, the
assistant should gather unresolved kickoff fields and unresolved ConvoAI provider
choices in one message, then convert the reply into the structured spec.
If the primary product is already obvious from the user's request, do not ask extra
questions here — route directly to the product module.

## Interaction Style

The intake should stay concise and targeted.
The intake should stay concise and routing-focused.

- Prefer natural wording over an interview script
- Ask only for missing information
- For non-ConvoAI flows, ask in priority order and stop early once there is enough information
- For ConvoAI-primary flows, send one consolidated checklist covering unresolved fields, including kickoff fields and optional-default provider fields
- Do not ask "nice to have" questions during kickoff
- Ask only for missing information that changes product routing
- Ask at most one routing blocker at a time when the product is still unclear
- Do not ask product-specific configuration questions at the top level
- Do not propose project structures, implementation plans, or framework choices here
- If a detail is obvious from the user's message, infer it instead of asking again
- After each answer, decide whether to continue or route onward
- As soon as the product mapping is clear, route onward

## Product Routing Aid

Expand All @@ -52,6 +49,8 @@ Use this only to map the user's use case to the likely product set.
| RTM | Real-time messaging / signaling | "聊天", "消息", "chat", "signaling", "notification" |
| ConvoAI | AI voice agent (ASR→LLM→TTS over RTC) | "AI语音", "voice bot", "对话式AI", "AI agent" |
| Cloud Recording | Record RTC sessions server-side | "录制", "recording", "存档" |
| Token generation | Generate RTC / RTM tokens | "token", "鉴权", "token server" |
| Credentials / Auth | Console credentials, REST auth, service activation | "App ID", "Customer Key", "REST auth", "开通服务" |

### Common combinations

Expand All @@ -67,56 +66,33 @@ Use this only to map the user's use case to the likely product set.

## Intake Flow

### Step 1: Ask only for missing kickoff details
### Step 1: Determine product routing

Start from the user's existing message. Do not repeat information they already gave.

Use the shortest set of prompts needed to fill the gaps.

Priority order:
- Use case
- Main product, if unclear
- Platform / client stack, if relevant
- Implementation mode, when a matching ConvoAI sample repo exists and the user explicitly wants to opt out of the default sample-aligned path
- Backend language, if relevant
- One additional blocker only if it materially affects implementation

ConvoAI exception:
- If ConvoAI is clearly the primary product, do not stretch kickoff across multiple turns
- Route immediately to [convoai.md](convoai.md) and ask for all unresolved kickoff and ConvoAI provider fields in one checklist-style message
- Include kickoff fields only if still missing, such as use case, platform, backend language, or implementation mode
- Mention that ConvoAI prefers the official sample path, `agent-server-sdk` on the server side, and `agora-agent-client-toolkit` on the client side when possible
- Use case / target solution
- Primary product, if still unclear
- Supporting product, if the use case clearly requires one
- One routing blocker only if it is still needed to choose the right module

Short prompt examples:
ConvoAI handoff:
- If ConvoAI is clearly the primary product, route directly to [conversational-ai](../references/conversational-ai/README.md)
- Do not expand ConvoAI-specific quickstart, provider, auth, or sample questions here
- Let the ConvoAI module handle `request-modes.md` and its internal sub-flows

Short prompt examples:
- Use case:
- ZH: "你想做什么场景？"
- EN: "What are you trying to build?"
- Main product:
- Primary product:
- ZH: "你主要想用 RTC、RTM、ConvoAI，还是录制？如果不确定我可以帮你判断。"
- EN: "Are you mainly using RTC, RTM, ConvoAI, or recording? If you're not sure, I can infer it."
- Platform / client stack:
- ZH: "目标平台是什么，比如 Web、iOS、Android？"
- EN: "What platform are you targeting, such as Web, iOS, or Android?"
- Implementation mode, when a matching ConvoAI sample repo exists:
- ZH: "默认会按官方 quickstart / sample 结构走；如果你想改成最小化自定义实现，再告诉我。"
- EN: "I’ll default to the official quickstart/sample structure unless you specifically want a minimal custom implementation."
- Backend language, when relevant:
- ZH: "服务端准备用什么语言？"
- EN: "What backend language are you using?"

Ask follow-up only when a missing detail affects routing or implementation.
- Supporting product:
- ZH: "除了主链路外，还需要聊天、录制，或者 token 服务吗？"
- EN: "Besides the main flow, do you also need chat, recording, or a token service?"

### Step 2: Determine product mapping

From the user's answers, determine:
- Primary product
- Supporting products, if required
- Any remaining gaps that block implementation

Use the routing aid above to infer combinations.

### Step 3: Produce kickoff summary
### Step 2: Produce routing summary

Present a short progress recap in the user's language:

Expand All @@ -127,9 +103,7 @@ Present a short progress recap in the user's language:
场景： [use case]
主要产品： [primary product]
配套产品： [supporting products / 无]
平台： [platform / client stack]
服务端语言： [backend language / 不涉及]
下一步： [go to implementation research / ask one blocker]
下一步： [route to the product module / ask one routing blocker]
─────────────────────────────
```

Expand All @@ -140,35 +114,27 @@ What I have so far
Use case: [use case]
Primary: [primary product]
Supporting: [supporting products / none]
Platform: [platform / client stack]
Backend: [backend language / not needed]
Next: [go to implementation research / ask one blocker]
Next: [route to the product module / ask one routing blocker]
─────────────────────────────
```

Do not stop for a separate confirmation step.

- If no required detail is missing -> continue automatically to Step 2 in the root workflow.
- If a required detail is still missing -> ask only for that blocker, then continue.

For ConvoAI-primary flows, the kickoff summary may be merged into the ConvoAI
spec output if that is clearer than producing two separate recaps.

### Step 4: Route onward
- If the product mapping is clear -> continue automatically to the product module
- If one routing blocker is still missing -> ask only for that blocker, then continue

For each identified product, route to its detail collection:
### Step 3: Route onward

| Product | Detail intake | Product module |
|---------|--------------|---------------|
| ConvoAI | [intake/convoai.md](convoai.md) | [conversational-ai](../references/conversational-ai/README.md) |
| RTC SDK | — | [rtc](../references/rtc/README.md) |
| RTM | — | [rtm](../references/rtm/README.md) |
| Cloud Recording | — | [cloud-recording](../references/cloud-recording/README.md) |
| Credentials / Auth | — | [general](../references/general/credentials-and-auth.md) |
| Token generation | — | [token-server](../references/token-server/README.md) |
For each identified product, route to its product module:

> Products without a detail intake (marked "—") go directly to the product module.
> The module itself should only collect product-specific missing details.
| Product | Product module |
|---------|---------------|
| ConvoAI | [conversational-ai](../references/conversational-ai/README.md) |
| RTC SDK | [rtc](../references/rtc/README.md) |
| RTM | [rtm](../references/rtm/README.md) |
| Cloud Recording | [cloud-recording](../references/cloud-recording/README.md) |
| Credentials / Auth | [general](../references/general/credentials-and-auth.md) |
| Token generation | [token-server](../references/token-server/README.md) |

When multiple products are needed, run the primary product's intake first,
When multiple products are needed, route to the primary product first,
then address supporting products in order.
Loading
Loading