tencent-tds/kuiklyui-ai/kuikly-coroutines-threading

Claude Code and agent skill by tencent-tds/kuiklyui-ai

Trust tier 2
  • community
LLM review pending
Source check pending

Checking that the SKILL.md file is still in the repository.

Kuikly 协程与多线程编程助手。指导如何在 Kuikly 中进行异步编程，包括 Kuikly 内建协程、kotlinx 协程、kuiklyx 协程库。当用户在 Kuikly 中需要执行异步任务、切换线程、使用协程、回到 Kuikly 线程更新 UI、排查线程安全问题时使用。

Install

npx vskill@latest install tencent-tds/kuiklyui-ai/kuikly-coroutines-threading

SKILL.md

Kuikly 协程与多线程编程

核心规则

  • Kuikly 线程约束：所有 Kuikly UI 操作（View、Attr、Event、observable、Module 方法、setTimeout 等）只能在 Kuikly 线程调用，Kuikly UI 相关类非线程安全。
  • 异步任务完成后必须回到 Kuikly 线程才能更新 UI 或访问响应式属性。
  • 动态化场景不支持 kotlinx 协程（js 目标平台不支持多线程），只能使用 Module 机制或 Kuikly 内建协程。

协程实现方式对比

特性回调（无协程）Kuikly 内建协程kotlinx 协程
动态化支持✅ 支持✅ 支持❌ 不支持
依赖库包增量无无kotlinx 协程库
线程安全不涉及自动保障需要考虑

三种协程 API

1. Kuikly 内建协程（推荐用于简单异步）

框架自带，始终在 Kuikly 线程执行，无线程切换开销，支持动态化。

API 入口：

  • GlobalScope.launch { ... } — 全局作用域
  • lifecycleScope.launch { ... } — 绑定 Pager 生命周期（推荐）
  • async { ... } / await() — 并发获取结果

import：

kotlin
import com.tencent.kuikly.core.coroutines.GlobalScope
import com.tencent.kuikly.core.coroutines.launch
import com.tencent.kuikly.core.coroutines.async
import com.tencent.kuikly.core.coroutines.delay

注意： Kuikly 内建协程 API 本身非线程安全，不能在 Kuikly 线程外调用。

2. kotlinx.coroutines 库

Kotlin 官方协程库，支持多线程调度器（Dispatchers.Default/IO/Main 等），不支持动态化。

接入方式：

gradle
// iOS & Android
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_VERSION")
// 鸿蒙
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:$KOTLINX_COROUTINES_OHOS_VERSION")
3. kuiklyx.coroutines 库（切换到 Kuikly 线程）

提供 Dispatchers.Kuikly 调度器和 KuiklyContextScheduler 回调 API，用于从非 Kuikly 线程切回 Kuikly 线程。

接入方式：

gradle
// iOS & Android
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_VERSION")
// 鸿蒙
implementation("com.tencent.kuiklyx:coroutines:$KUIKLYX_COROUTINES_OHOS_VERSION")

协程方式 API：

kotlin
// 启动协程，在 Kuikly 线程执行
GlobalScope.launch(Dispatchers.Kuikly[ctx]) { ... }
// 在协程中切换到 Kuikly 线程
withContext(Dispatchers.Kuikly[ctx]) { ... }

回调方式 API：

kotlin
KuiklyContextScheduler.runOnKuiklyThread(pagerId) { cancel ->
    if (cancel) return  // pager 已销毁
    // 在 Kuikly 线程执行
}

场景选择决策树

根据需求选择合适的异步编程方式：

需要异步编程？
├── 只需简化回调，无多线程诉求？
│   └── → 方式1：Kuikly 内建协程
├── 需要执行耗时任务 + 支持动态化？
│   └── → 方式2：Module 机制（可配合内建协程）
├── 需要多线程 + 不需要动态化？
│   └── → 方式3：kotlinx 协程 + kuiklyx 协程
└── Compose DSL 页面？
    └── → 方式4：LaunchedEffect + withContext
⚠️ 一致性原则：选择方案时，还需关注当前项目或模块中已有的异步编程方式，应优先保持一致，避免在同一模块中混用多套异步方案。

详细场景示例和代码：见 SCENARIOS.md

Compose DSL 中的协程

Compose DSL 页面（继承 ComposeContainer）使用 kotlinx 协程体系：

kotlin
@Composable
fun MyContent() {
    var data by remember { mutableStateOf("") }
    LaunchedEffect(Unit) {
        // 默认在 Kuikly 线程执行（ComposeDispatcher）
        val result = withContext(Dispatchers.IO) {
            // 在 IO 线程执行耗时任务
            fetchData()
        }
        // 自动回到 Kuikly 线程
        data = result
    }
    Text(text = data)
}

关键点：

  • LaunchedEffect 默认运行在 Kuikly 线程（通过 ComposeDispatcher 调度）
  • 使用 withContext(Dispatchers.IO) 切换到 IO 线程执行耗时任务
  • withContext 返回后自动回到 Kuikly 线程
  • viewModelScope 也绑定到 Kuikly 线程，ViewModel 销毁时自动取消

Dispatchers.IO 跨平台定义：

kotlin
// commonMain 中声明 expect
internal expect val Dispatchers.IO: CoroutineDispatcher
 
// androidMain / appleMain / ohosArm64Main
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.IO  // 使用平台原生 IO 调度器
 
// jsMain（不支持多线程）
internal actual val Dispatchers.IO: CoroutineDispatcher
    get() = Dispatchers.Default

线程安全

线程安全规则
  • Kuikly UI 相关类（View、Attr、Event、ObservableProperties、GlobalFunctions、Module 方法、Layout 等）非线程安全，只能在 Kuikly 线程访问
线程安全验证机制

详细用法和示例：见 THREAD_SAFETY.md

kotlin
override fun willInit() {
    super.willInit()
    Pager.VERIFY_THREAD = true              // 开启线程校验
    Pager.VERIFY_REACTIVE_OBSERVER = true   // 开启 observable 校验
    Pager.verifyFailed { exception ->       // 自定义验证失败处理
        println("线程安全验证失败: ${exception.message}")
        throw exception
    }
}

常见陷阱与正确做法

❌ 错误做法✅ 正确做法
在非 Kuikly 线程直接更新 observable通过 Dispatchers.Kuikly 或 KuiklyContextScheduler 切回 Kuikly 线程
在非 Kuikly 线程调用 Module 方法Module 的 acquireModule / toNative 等方法需在 Kuikly 线程调用
在动态化场景使用 kotlinx 协程使用 Kuikly 内建协程或 Module 机制
在 Kuikly 线程外调用内建协程 API内建协程 API 只能在 Kuikly 线程调用
忘记处理 Pager 销毁后的回调KuiklyContextScheduler 回调检查 cancel 参数
在 verifyFailed 回调中操作 UI验证失败通常发生在非 Kuikly 线程，不能调用 UI API
Compose 中在 IO 线程更新 State使用 withContext 回到默认调度器后再更新 State

Security

  • Security scanPassed, 100 of 100Pattern checks on the skill's files.
  • Model reviewNot runA model review is scheduled for the next rescan.

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

Repository stars
134
Repository forks
18
7-day trend score
0

Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/tencent-tds/kuiklyui-ai/kuikly-coroutines-threading/badge)](https://verified-skill.com/skills/tencent-tds/kuiklyui-ai/kuikly-coroutines-threading)

Something wrong with this skill or its page? Tell us.