harmonyos-ai-workspace
Advanced tools
Rule pack + PostToolUse hooks + skills for AI coding assistants (Claude Code / Codex CLI / Cursor / Copilot) writing HarmonyOS / ArkTS code that actually compiles.
一行命令把"鸿蒙领域规则包"装进你的 app，让 Claude / Codex / Cursor / Copilot 写出能编译过的鸿蒙代码。
cd ~/WorkSpace/apps/my-harmony-app # 进你的鸿蒙 app 根目录
npx -y harmonyos-ai-workspace # 30 秒搞定，0 改你的源码
| 你是 | 你会得到 |
|---|---|
| 🆕 vibe coder（不熟鸿蒙，让 AI 写） | AI 不再写 ArkTS 编译错；不再瞎编 OHPM 包名；不再让 UI 不刷新；编译失败时 AI 能精确定位 |
| 🛠 老 HarmonyOS 开发者（让 AI 协助） | 一套大家都遵守的硬约束（V1/V2 选型、状态铁律、装饰器规范）；编辑 .ets 后自动校验；提审 Top 20 拒因预防式提示 |
| 👥 团队 lead（多人多 AI 工具） | 同一份规则同时喂 Claude Code / Codex / Cursor / Copilot；钩子保证违规 0 漏过；新人 git clone 即拥有完整规则 |
前置要求：你在用 Claude Code / Codex CLI / Cursor / GitHub Copilot 中至少一个；本仓库不是独立 IDE，是给它们装的"鸿蒙领域规则包"。
没装过 AI 助手 / DevEco Studio？看 docs/SETUP-FROM-SCRATCH.md（macOS 干净状态到 hello world，30-60 分钟）。
| 痛点 | 没装本仓库 | 装了之后 |
|---|---|---|
| AI 写 ArkTS Pass@1 仅 3.13%（ArkEval 论文 实测） | AI 写 100 行代码 ~97 行编译不过 | 规则注入 + 钩子校验，假阳率实测 21% → 0% |
AI 瞎编 OHPM 包（如 @ohos/lottie-player、@ohos/axios） | ohpm install 失败浪费 10 分钟 | 安装时三层校验：黑名单 → 白名单 → ohpm view，假包当场拦截 |
AI 写 this.list.push(x) 状态不刷新（LLM 第一坑） | UI 不更新，调试半小时才发现 | 钩子立刻报 STATE-002 · High，给改写示例 |
| AI 引用旧 API（DevEco 12 → 22 多次变化） | 用了已弃用的 picker.PhotoViewPicker | ARKTS-DEPRECATED-PICKER 即时拦截 + 给新 API |
| AGC 上架前才发现拒因 | 提审被打回再修 = 1 周 | 20 条 AGC-RJ-* 稳定 ID 编辑时就提示 |
| 多 AI 工具规则不一致（Claude / Cursor 各写一套） | 同一项目下 AI 给不同建议 | 单源 fan-out：5 个默认 SKILL → Cursor 6 个 .mdc（按 globs 触发）+ Copilot root < 4KB + instructions/*.md 按 applyTo 触发 |
# 1) 进你的鸿蒙 app 根目录
cd ~/WorkSpace/apps/my-harmony-app
# 2) 一行装好
npx -y harmonyos-ai-workspace
# 3) 启动你的 AI 助手——CLAUDE.md / AGENTS.md 自动加载
claude # 或 codex / cursor
v0.4 起的安全保障：
CLAUDE.md / AGENTS.md 会被保护（绝不覆盖）written / 哪些 skipped.harmonyos-ai-workspace.manifest + sha256 校验）更多选项：
npx -y harmonyos-ai-workspace --dry-run # 预览不真写
npx -y harmonyos-ai-workspace --targets=claude,codex,cursor,copilot # 加 Cursor / Copilot
npx -y harmonyos-ai-workspace --mirror=ghproxy # 国内 GitHub 不通时
npx -y harmonyos-ai-workspace --force # 覆盖已存在文件
npx -y harmonyos-ai-workspace --uninstall # 安全卸载
安装后还会带上 AI 调试闭环脚本：
bash tools/harmony-dev-cycle.sh quick-check # 轻量 ArkTS/OHPM 扫描
bash tools/harmony-dev-cycle.sh build-check # ohpm install → codeLinter → build HAP
bash tools/harmony-dev-cycle.sh cycle-once # build → install → run → 抓 8s hilog 给 AI
# 1) 模拟 AI 写一个反模式（数组就地 mutation = LLM 写鸿蒙的第一大坑）
mkdir -p test && cat > test/Bad.ets <<'EOF'
@Entry @Component struct X {
@State items: number[] = [];
build() { Button('+').onClick(() => { this.items.push(1) }) }
}
EOF
# 2) 触发钩子（模拟 Claude Code 编辑文件后调用）
echo '{"tool_name":"Edit","tool_input":{"file_path":"test/Bad.ets"}}' | bash tools/hooks/post-edit.sh
# ✅ 预期看到：
# [STATE-002 · High] test/Bad.ets:3: this.items.push(1) ...
# ↳ 数组就地 mutation 不触发重渲染。改写：this.X = [...this.X, item]
# 3) 清理
rm -rf test
看到 STATE-002 · High = 钩子工作。从此每次 Claude Code 编辑 .ets / .ts 自动跑这套校验，违规会反馈给 AI 让它自我修正。
装好之后怎么开始干活？ → docs/USER-GUIDE.md
里面写了：
┌──────────────────────────────────────────────────────────────────┐
│ 你的鸿蒙 app 项目 │
│ ┌─────────┐ │
│ │ AI 助手 │ Claude Code / Codex / Cursor / Copilot │
│ └────┬────┘ │
│ │ 启动时自动加载 │
│ ▼ │
│ CLAUDE.md / AGENTS.md / .cursor/rules/ / .github/copilot-… │
│ │ AI 读到鸿蒙硬约束 + 8 SKILL 触发索引 │
│ ▼ │
│ AI 写代码 → Edit .ets / .ts / oh-package.json5 │
│ │ │
│ ▼ ⚡ 钩子触发（仅 Claude Code 强校验） │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ tools/hooks/post-edit.sh │ │
│ │ ├─ scan-arkts.sh 31 条规则 + 装饰器上下文 + 折叠 │ │
│ │ ├─ check-ohpm-deps.sh 4 类（FAKE/NET/UNKNOWN/OK） │ │
│ │ └─ module.json5 权限提示 │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ├─ High 级 → exit 2 + stderr ▶ AI 看到，自我修正 │
│ └─ Medium → exit 0 + stderr ▶ AI 看到，但不阻塞 │
│ │ │
│ ▼ │
│ 写入 .claude/.harmonyos-last-scan.txt（下一轮 AI 可读） │
│ │
│ 人类 → hvigorw assembleHap → 设备 │
│ 或：AI agent → tools/harmony-dev-cycle.sh → │
│ build-check / cycle-once / device-check → hilog → AI 分析 │
│ （完整闭环，详见 04-build-debug-tools/README §⚡️） │
└──────────────────────────────────────────────────────────────────┘
详细工作流见 docs/USER-GUIDE.md § 3。AI agent 自治调试闭环
（让 Claude / Codex / OpenClaw 在终端完整跑 build→install→run→log，不再切 DevEco GUI）
见 04-build-debug-tools/README.md §⚡️。
| 资产 | 内容 |
|---|---|
| AI 规则集 | CLAUDE.md（Claude Code）+ AGENTS.md（agents.md 标准 24+ 工具通用）+ 8 个按需触发的 .claude/skills/ |
| 8 个 SKILL | 5 个默认 fan-out（arkts-rules / state-management / build-debug / signing-publish / runtime-pitfalls，对所有项目通用）+ 3 个领域专项（harmonyos-review / multimodal-llm / web-bridge，仅 Claude Code 自动激活，其他工具按需手动读） |
| PostToolUse 钩子链路 | Edit .ets/.ts/oh-package.json5 后自动跑 ArkTS 反模式扫描 + OHPM 包名核验 + 权限提示 |
| 多工具 fan-out | 5 个默认 SKILL → Cursor 6 个 .mdc（按 globs 触发，单文件 < 12KB）+ Copilot root < 4KB + .github/instructions/*.md 5 个按 applyTo 触发 |
doctor 体检 | npx harmonyos-ai-workspace doctor 或 bash tools/doctor.sh：PASS/WARN/FAIL 三态报告，含钩子端到端自测（喂故意的 STATE-002 看是否被抓） |
| CLI 工具集 | install.sh（manifest + sha256 安装）/ run-linter.sh（离线 codeLinter）/ check-ohpm-deps.sh（4 类校验）/ check-rename-module.sh（模块改名一致性）/ test-suite.sh（19 项回归断言）/ scaffold-deveco-project.sh（一键补 DevEco 脚手架 11 文件）/ harmony-dev-cycle.sh（quick-check / build-check / cycle-once / device-check，绕开 DevEco GUI Run 按钮） |
| Recipe Templates | 8 个可粘贴最小可用代码 — 基础 4 个：permission/ / list/ / dark-mode/ / login/；进阶 4 个（OctoDesk 抽取）：web-bridge-h5-shell/ / llm-sse-client/ / huks-secure-store/ / scan-qrcode/ |
| 2026 提审 Top 20 拒因 | 07-publishing/checklist-2026-rejection-top20.md，含 AGC-RJ-001..020 稳定 ID + 6 条高频项配可粘贴代码 |
| Case Studies | docs/case-studies/llm-chat-app.md — 真鸿蒙 LLM 对话 app M3-M13 实战（M3-M12 原始里程碑 + M13 运维期 layered icon / 9568297），12 节"症状/错误信息/修复 diff/教训"四段式 + docs/case-studies/android-parity-migration.md — paseo-harmony 14 阶段 Phase A/B 真修复笔记 |
| 测试 fixture | 9 个回归 fixture 覆盖 inline 装饰器 / @CustomDialog / @Reusable / 普通工具类等边界 |
| MCP | .mcp.json 接通 mcp-harmonyos（npx 自动）；动作型 MCP 接入指引见 docs/MCP-INTEGRATION.md |
| 可选官方文档镜像 | 5300+ 中文 + 5100+ 英文 OpenHarmony md（按需 bootstrap-upstream-docs.sh -y 拉，~2.7 GB） |
PostToolUse 钩子并非孤例（yibaiba/harmonyos-skills-pack 也有 hooks），本仓库的真实差异点：
tools/check-ohpm-deps.sh。同类无人做AGC-RJ-001..020）+ 高频项配可粘贴代码 —— harmonyos-review skill 与扫描器可用同一编号互引tools/hooks/lib/scan-arkts.sh，PrivateTalk 真工程实测假阳率 0%CLAUDE.md 永不被吞，本工具写的所有文件可精确卸载完整对比见 docs/USAGE-GUIDE.md § B。
本仓库的规则按用途分四层，不应被合并表述为单一数字：
| 层 | 数量 | 位置 | 用途 |
|---|---|---|---|
| 自动化扫描（钩子触发） | 32 条 | tools/hooks/lib/scan-arkts.sh 内联 + awk 装饰器上下文检测 | grep-based 快扫，毫秒级反馈；支持 inline-suppress |
| 代码审查清单 | 36 条（9 大类） | .claude/skills/harmonyos-review/references/checklist.md | review skill 引用的稳定 ID（SEC-001 / STATE-002 / KIT-003 等） |
| AGC 提审拒因 | 20 条 | 07-publishing/checklist-2026-rejection-top20.md | 上架审核拒因映射，含 AGC-RJ-* 稳定 ID |
| OHPM 黑名单（已知伪包） | ~25 项 | tools/data/ohpm-blacklist.txt + 脚本内联 | 防 AI 虚构包名 |
合计 ~95 条编号规则，分布在四层；它们用于不同场景。
接线层陷阱（scanner 抓不到、灰度才暴露的）单独整理在 05-best-practices/bridge-integration-pitfalls.md：12 类常见 Web Bridge + 原生外壳集成坑（capability 握手 fail-closed、javaScriptProxy 生命周期、idempotencyKey 强制、envelope schema validation、token / SecureStore 写入原子性、pasteboard 提示时机、App-Linking 双侧配置 + EntryAbility 双入口、HMS ScanKit dual-import 等），沉淀自下游真工程教训。
Monorepo 接入：HarmonyOS shell 是大 monorepo 子目录的项目（不是 npm app 形态），参考 samples/integrations/monorepo-consumer/ —— 三个文件薄 wrapper、scope 到子目录、单一来源、零文件复制；包含 token 成本实测与降噪方案。
# 鸿蒙系统侧（API 编号是单一权威，不同 API 对应不同 HarmonyOS 系统版本）
harmonyos_system:
min_supported_api: 12 # API 12 = HarmonyOS 5（NEXT）时代起，本仓库规则适用最低线
current_consumer_stable: 22 # API 22 = HarmonyOS 6.0.2，2026-01-23 起对 Mate 80/70/Pura 80 推送
first_stable_release: 21 # API 21 = HarmonyOS 6.0.1，2025-11-25 随 Mate 80 首发
developer_preview_api: 23 # API 23 Developer Beta（最新预览，跟随华为发布节奏 — 跑生产 app 别选）
recommended_target: 21 # 新项目推荐 targetSDK
recommended_min: 12 # 新项目推荐 minSDK
toolchain:
arkts: ">= 1.2.0"
deveco_studio: ">= 6.0"
ohpm: ">= 1.4"
ai_assistants:
claude_code: ">= 0.5"
codex_cli: ">= 0.1"
cursor: ">= 1.0"
copilot: "ChatGPT-class instructions OK"
last_verified_docs_snapshot: "2026-05-07"
如何读这张表：API 编号才是单一权威——HarmonyOS 5 = API 12+ 时代，HarmonyOS 6 = API 21+ 时代。"6.0" / "6.0.2" / "6.1" 这种系统版本号会在不同发布节点指向不同 API 编号，直接看 API 数字最准。
生产应用选 API 22（minSDK 12 / target 21–22 都行）；developer beta（API 23）当下仅尝鲜用。鸿蒙生态快速迭代：本仓库每次发版前在
last_verified_docs_snapshot日期对齐一次"当前消费稳定版"。
curl -fsSL https://raw.githubusercontent.com/Octo-o-o-o/harmonyos-ai-workspace/main/tools/install.sh | bash
git clone https://github.com/Octo-o-o-o/harmonyos-ai-workspace.git ~/WorkSpace/HarmonyOS_DevSpace
cd ~/WorkSpace/HarmonyOS_DevSpace
bash tools/bootstrap-upstream-docs.sh # 拉 OpenHarmony 官方文档镜像（~2.7 GB，可选）
bash tools/verify-environment.sh # 检查本机环境
适合：想系统学习鸿蒙、想让 AI 在本目录开发、想给本仓库贡献。
git clone https://github.com/Octo-o-o-o/harmonyos-ai-workspace.git ~/WorkSpace/HarmonyOS_DevSpace
cd ~/WorkSpace/HarmonyOS_DevSpace
bash tools/setup-from-scratch.sh # 半自动向导：装基础工具 → 引导装 DevEco → 配 PATH → 装 Claude Code
完整指南见 docs/SETUP-FROM-SCRATCH.md。
vibe coding 卡死的 90% 场景是"AI 写完看起来 OK 但 hvigorw 报错；我把错误贴给 AI，它瞎猜"。最高效路径：
# 1) 直接复制 hvigorw 的报错原文，含错误码
hvigorw assembleHap -p buildMode=debug 2>&1 | tail -30 | pbcopy # macOS 进剪贴板
# 2) 把这段贴给 Claude/Codex/Cursor，附一句：
# "请按 .claude/skills/arkts-rules/references/spec-quick-ref.md 里的稳定 ID
# 找出违反的规则编号 + 给最小 diff，不要重写整个文件"
# 3) 装包失败贴 hilog（hdc 真机）
hdc hilog | grep -E "FAULT|ERROR|9568" | tail -30
# 4) 钩子已经写过的违规会落到这里——下一轮启动 AI 前先让它读
cat .claude/.harmonyos-last-scan.txt 2>/dev/null
.ets 后没看到扫描输出）cat .claude/settings.json # 应含 PostToolUse + post-edit.sh 路径
echo '{"tool_name":"Edit","tool_input":{"file_path":"x.ets"}}' | \
bash tools/hooks/post-edit.sh # 直接跑钩子测试
HOOK_DEBUG=1 bash tools/hooks/post-edit.sh < /dev/null # 开调试日志
chmod +x tools/hooks/post-edit.sh tools/hooks/lib/*.sh # 修可执行位
# settings.json 改动需重启 Claude Code 才生效
# 让 ohpm CLI 在 PATH（DevEco 装好就有）
ls ~/Library/Huawei/Sdk/*/openharmony/toolchains/ohpm*
export PATH="$PATH:~/Library/Huawei/Sdk/HarmonyOS-NEXT-DB1/openharmony/toolchains/ohpm/bin"
hvigorw codeLinter 找不到which hvigorw # 应有；没有就到鸿蒙工程根目录跑
cd ~/WorkSpace/apps/my-app && bash ../../HarmonyOS_DevSpace/tools/run-linter.sh
grep -rln 'Octo-o-o-o' --include='*.md' --include='*.sh' --include='*.json' . | \
xargs sed -i '' 's|Octo-o-o-o|YOUR_GITHUB_USER|g'
涉及文件：README.md / CHANGELOG.md / tools/install.sh 顶部 REPO_OWNER。
更多故障场景见 docs/USER-GUIDE.md § 6。
upstream-docs/.../reference/，没有再上 developer.huawei.comthis.list.push(x) 不会重渲染，要 this.list = [...this.list, x]any / 解构 / 索引签名 / 对象字面量无类型 / for…in / delete@kit.*，不要 @ohos.*（旧式）.ets 文件二选一；默认 V1（生态最成熟）hvigorw codeLinter && hvigorw assembleHap -p buildMode=debug.har/.hsp完整版见 CLAUDE.md 第 0、11、12、13 节 + 8 个 SKILL（按需触发）。
.ets 跑通.hap（单 module）/ .app（应用包）/ .har（静态库）/ .hsp（共享库）CONTRIBUTING.mdCHANGELOG.mddocs/archive/reviews/ — 6 轮多视角评审 + PrivateTalk 真用户验收hvigorw codeLinter 输出CLAUDE.md、AGENTS.md、.claude/skills/、脚本、示例）：MIT License（详见 LICENSE）upstream-docs/openharmony-docs/（运行 bootstrap 拉取）：CC-BY-4.0，版权归 OpenAtom Foundation / OpenHarmony 项目FAQs
Rule pack + PostToolUse hooks + skills for AI coding assistants (Claude Code / Codex CLI / Cursor / Copilot) writing HarmonyOS / ArkTS code that actually compiles.
The npm package harmonyos-ai-workspace receives a total of 3 weekly downloads. As such, harmonyos-ai-workspace popularity was classified as not popular.
We found that harmonyos-ai-workspace demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
The PHP Foundation says Chainguard broke a security embargo ahead of critical RCE patches, as leaks disrupted the coordinated release.
Security News
PHP releases emergency patches for two critical RCE vulnerabilities as agencies urge organizations to take unpatched sites offline.
Threat Research
/Security News
A supply chain attack compromised LiteLLM 1.107.0 on PyPI and Docker, spreading malware that steals cloud credentials, developer secrets, and AI provider keys.