name	cangjie-translate-lib
description	将任意语言的三方库/SDK/工具包翻译为纯仓颉 cjpm 包。关注 API 面、依赖策略、包骨架与构建验证；不涉及 HarmonyOS 应用资源与 UI
argument-hint	[source-lib-path] [--lang <hint>]

三方库翻译为仓颉 cjpm 包

将位于 $1 的三方库翻译为纯仓颉 cjpm 包。--lang <hint> 可选，在无法从 manifest 自动判定源语言时使用。

本 skill 面向库级别翻译，产物为 cjpm 包。不包含应用资源迁移、$r() 引用、HarmonyOS entry/ 骨架、UI 截图辅助等 app 级逻辑 —— 这些由 /cangjie-translate 负责。

前置检查（启动翻译前必须完成）

#	检查项	获取方式	未就绪时
1	源项目路径	参数 `$1` 或用户指定	询问用户提供路径
2	源语言	从 manifest 自动推断（见 Phase 1）；无法推断时用 `--lang`	询问用户确认
3	分流判定	检查源项目是 app 还是 lib（见 Phase 0）	app → 切到 `/cangjie-translate`
4	仓颉 SDK 可用	`~/.cangjie-sdk/` 或 `.env` 中配置	提示用户安装（Phase 9 构建验证需要）
5	输出目标路径	默认当前目录下以源库名创建	确认用户是否有特殊要求

Phase 0 — 分流自检（强制前置）

在执行任何翻译前先判定本 skill 是否适用：

源项目形态	产物目标	应使用
可运行 app / HarmonyOS 应用 / 含 UI 资源（`entry/`、`Assets.xcassets/`、Android `res/`）	HAP 应用	`/cangjie-translate`
库 / SDK / CLI 工具 / 算法包 / 纯逻辑工具包	cjpm package	本 skill
混合仓库（app + 内部库）	—	先用本 skill 抽出库部分，app 部分走 `/cangjie-translate`

自检规则：若源项目含下列任一应用入口，属 app 场景，应切到 /cangjie-translate：

HarmonyOS：module.json5 含 abilities 且有 UIAbility
Android：AndroidManifest.xml 含 <activity> 且声明 LAUNCHER
iOS：@main AppDelegate / App 结构体
Web：index.html + 运行时入口
Server/CLI 应用：可执行二进制入口（main 函数 + 被 manifest 标记为 bin）。注意：CLI 参数解析库、工具函数库等仍属于库，应使用本 skill

判定结果在产出的翻译报告首行明确写出："分流判定：lib / 继续本 skill"。

翻译流程（10 阶段，源语言无关）

Phase 1 — 源项目摸底

识别构建系统 manifest（命中任一即可推断源语言）：

Manifest	源语言
`package.json`	JS/TS（含 ArkTS）
`tsconfig.json` + `.ts`	TypeScript
`Package.swift` / `*.podspec`	Swift/Obj-C
`pom.xml` / `build.gradle(.kts)`	Java/Kotlin
`Cargo.toml`	Rust
`go.mod`	Go
`setup.py` / `pyproject.toml`	Python
`*.cabal` / `stack.yaml`	Haskell
`CMakeLists.txt` + 无上述	C/C++
`mix.exs` / `rebar.config`	Elixir/Erlang

多 manifest 共存时，以声明导出/构建主产物的那个为主。

记录事实：语言与版本、工具链版本、目标运行时（Node / JVM / Swift runtime / 裸机 …）、入口文件、测试目录、CI 配置。
警示：若项目依赖特定运行时特性（如 JVM 反射、Node event loop、Swift runtime 动态派发），在 decisions.md（Phase 6）中登记。

Phase 2 — 公共 API 面盘点

按源语言可见性规则提取对外 API：
- TS/JS：export / export default / .d.ts
- Swift：public / open
- Java/Kotlin：public / 模块 exports
- Rust：pub + mod.rs 再导出
- Go：首字母大写标识符
- Python：__all__ / 未 _ 前缀

产出 <lib-name>_api.md：

## 公共 API 清单

| 源签名 | 仓颉目标签名 | 备注 |
|--------|-------------|------|
| `func add(a: number, b: number): number` | `public func add(a: Int64, b: Int64): Int64` | 数值宽窄已锁定 |

## 内部 API（不对外导出）

- `internalHelper(...)` — 保留但不 public

翻译过程中 API 签名定稿后不得擅自改名；若必须改名（仓颉保留字冲突等），在备注列写明原因。

Phase 2.5 — 功能完整度约束（强制）

目标：尽可能翻译完整 API 与核心行为。不要因为仓颉缺少现成 API / 运行时封装，就直接删掉功能、缩窄公共接口，或把核心路径改成空实现。

遇到仓颉没有直接等价能力时，按以下优先级处理：

replace：先确认 std / stdx / 已有仓颉生态是否已有等价能力
implement：若无现成 API，但可用仓颉标准库、自写算法、compat 层、adapter、薄封装实现，优先自己实现
port：若相关能力本身就是小而纯的依赖模块，且直接翻译其实现更划算，则一并移植
stub / skip：只有在确认无法安全实现、或实现成本显著超出本次翻译范围时，才允许最小化占位或跳过

补充约束：

只允许跳过最小功能单元，不要因为一个 API 缺失就放弃整个包或整组公共 API
禁止用虚构 API、无行为 stub、永远返回默认值的假实现来冒充"已完成翻译"
若只能做部分降级实现，必须优先保住主流程和主要公共 API，再在报告里明确差异

Phase 3 — 依赖策略

对每个 dependencies 条目逐一标记决策，产出 deps_plan.md：

决策	适用条件	动作
`replace`	仓颉 `std` / `stdx` 已有等价	查 `cangjie-kernel` 确认签名后映射
`implement`	仓颉无现成 API，但可用标准库 / compat 层 / 自写算法补齐	在当前库内落地最小必要实现，并保持 API 语义稳定
`port`	小而纯、仓颉无等价、直接移植依赖实现更划算	纳入翻译范围，作为子包翻译
`stub`	大型/平台相关/经确认本次确实无法安全实现	定义最小 interface 占位，明确缺口、影响范围与后续方案
`drop`	死码 / 仅构建期工具链（lint、bundler）	完全不翻译

强制：每条依赖必须得到一个决策，不允许悬空。 优先级：replace / implement / port > stub > drop。只要核心功能仍可在仓颉侧落地，就不要因为缺少现成 API 直接 stub 或删功能。

Phase 4 — cjpm 骨架搭建

创建目录：

<lib-name>/
├── cjpm.toml
├── src/
│   └── <root-package>/
│       ├── *.cj
│       └── <subpackage>/
│           └── *.cj
└── tests/
    └── *.cj

cjpm.toml 至少包含：name、version、cjc-version、package、dependencies。版本号保留源库的 major.minor.patch，允许加 -cj.0 预发后缀以示为仓颉翻译版。
包/目录命名：全部小写下划线，禁止驼峰；与源项目模块边界对齐，避免一包打所有文件。
禁止项（与 app skill 划界）：
- ❌ 不新建 entry/、module.json5、app.json5
- ❌ 不引入 entry/src/main/resources/
- ❌ 不写 $r("app.media.*") 或 $rawfile(...)
- ❌ 不为跑 demo 伪造 main() 入口（tests/ 允许 main，库本体不允许）

Phase 5 — 源语言特性到仓颉的映射清单

每文件翻译前按此 checklist 逐条核对，不漏项：

源语言构造	仓颉对应
`null` / `undefined` / `nil` / `Optional<T>` / `T?`	`Option<T>` + `?.` / `??` / `if let`
泛型协变逆变 / `<out T>` / `<in T>`	仓颉泛型约束 `where T <: U`；需要型变时显式 `@!` 或改设计
继承 / `trait` / `protocol` / `interface`	仓颉 `interface` + `open class`；注意单继承多实现
`List` / `Array` / `Vec`	固定长度 `Array<T>` / 可变 `ArrayList<T>`
`Dict` / `Map` / `HashMap`	`HashMap<K, V>`
`Set` / `HashSet`	`HashSet<T>`
数值：`number` / `int` / `Int` / `long`	显式 `Int32` / `Int64` / `UInt*` / `Float32` / `Float64` —— 不允许隐式宽窄
异常 / Result / panic	`throw` + `try/catch` 或 `Option`/`Result`；一个库内风格统一
`Promise` / `Future` / `async/await` / coroutine	`spawn { ... }` + `Future<T>.get()`
正则 / 日期 / 格式化	查 `cangjie-kernel` 对应标准库 API
迭代器 / lazy seq / stream	仓颉迭代器协议
`unsafe` / 指针 / 位运算	限制使用；必要时 `unsafe` 块并在注释一行说明原因

每条映射若在本次翻译中未遇到可跳过，但 Int 宽窄是易错点，必须主动定型。

Phase 6 — 不可直接翻译项

下列构造不自作主张，登记到 decisions.md，每条形如：

## [决策点 N] <简述>

- 现状：源代码如何用、用在哪里
- 选项：A / B / C
- 推荐：<选项 + 理由>
- 用户确认：[ ]

触发登记的典型场景：

运行时反射 / 动态加载 / eval
注解处理器 / 代码生成 / 源语言宏（仓颉宏语义不同，不直译）
DSL / builder 链 / 操作符重载差异
平台 API（文件系统、线程模型、网络栈的平台特定扩展）
运行时环境耦合（JVM 类加载、Node event loop、process.env 深度依赖）

未获用户明确确认前，不做高风险语义改写。若某功能经确认无法在当前仓颉能力下安全实现，可局部 skip，但必须在 decisions.md 和翻译报告中写清：功能点、影响范围、已尝试方案、跳过原因、后续建议。禁止用空实现冒充完成。

Phase 7 — 分模块翻译

按依赖拓扑序翻译：无依赖的 leaf 包 → 依赖其他包的模块
每完成一个模块立即进入 Phase 9 编译，不积攒错误
翻译每个文件前先查 evolution skill 的已知坑，解决新坑后回写到 cangjie-translate-lib/experience/（Phase 10）
不要一次 diff 写几十个文件；保持"写一个 → 编一次 → 记一笔"节奏

Phase 8 — 冒烟 consumer

在 tests/ 中创建最小使用者，import 本库每个公共 API 并至少调用一次：

目的：验证 API 可见性、签名在消费者侧成立
仅要求编译通过，不等价功能测试
源项目如有测试，另行移植到 tests/ 作为功能回归（可能进入 port 决策的一部分）

Phase 9 — 构建验证

直接调用 /cangjie-lib-build 完成自动化编译与测试（脚本位于 .claude/skills/cangjie-lib-build/lib_build.py）：

python3 ${CLAUDE_SKILL_DIR}/../cangjie-lib-build/lib_build.py <lib-root>

或在交互中直接下发 /cangjie-lib-build <lib-root>（推荐，无路径依赖）。该命令会：

自动检测仓颉 SDK（.env 或 ~/.cangjie-sdk/）
跑 cjpm build，产物落到 <lib-root>/target/
若库根含 tests/ 或 cjpm.toml 含 [test]/[[test]] 段，跑 cjpm test

要求：

cjpm build 成功，无 error
cjpm test（如执行）全部通过
Warning 按常规处理；deprecated / unused 视情况保留
失败时先查 evolution/cangjie/syntax.md、evolution/cangjie/arkui.md；若是库级工程化问题（包循环、导出不一致），写入 cangjie-translate-lib/experience/build.md

Phase 10 — 经验沉淀

解决了非显而易见问题后追加到 cangjie-translate-lib/experience/，按主题分文件：

type-mapping.md — 任意语言 → 仓颉的类型/语义对应细节
deps.md — 依赖替代策略（哪些能 replace，哪些必须 port，常见 stub 形态）
build.md — cjpm 工程化（多包、版本、导出）
api-design.md — 库对外 API 设计取舍（异常 vs Result、可选参数、默认值）

不预先创建空文件，按需生成并更新 experience/README.md 索引。格式遵循 evolution/SKILL.md 的"单条经验格式"。

与 cangjie-translate/*2cangjie/ 的区别：那里沉淀应用翻译中"源语言 → 仓颉"的语法/表达差异；这里沉淀库工程化经验（包布局、API 面、依赖替代、cjpm 构建）。两边有交叉的语法点优先记到 cangjie-translate/*2cangjie/，本目录只记库独有的。

翻译总则

优先保全公共 API 与核心功能；仓颉缺失现成 API 时，先自行实现 compat / adapter / helper，再考虑 stub 或 skip
语义等价，不擅自加功能或改行为
用仓颉惯用写法，不逐行直译
数值宽窄、可空性、错误模型必须显式决定，不靠"约定"
翻译后代码必须 cjpm build 通过；不允许遗留 // TODO: will compile later
不确定的翻译先进 decisions.md，拿到用户确认再落地

输出物清单（翻译完成后应同时交付）

cjpm 包源码（src/ + cjpm.toml + tests/）
<lib-name>_api.md — 公共 API 对照表
deps_plan.md — 依赖决策记录
decisions.md — 不可直译项的决策点（即使为空也保留文件）
翻译报告：分流判定结论 + 关键取舍 + 已跳过 / 降级项 + 已知遗留项 + 验证结果