| 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 成功，无 errorcjpm 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 — 不可直译项的决策点（即使为空也保留文件）- 翻译报告：分流判定结论 + 关键取舍 + 已跳过 / 降级项 + 已知遗留项 + 验证结果
