harmony-next: 优化 skill 发现与渐进式披露

- 重写 SKILL/KITS/TASK_MAP 作为检索入口\n- 目录分桶与索引适配\n- 更新 README 说明推荐查找流程

Author: linhay

.env.example

@@ -0,0 +1,3 @@
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+CLOUDFLARE_API_TOKEN=your-api-token
+CRAWL_SUBMISSION_COOLDOWN_SECONDS=75

README.md

@@ -1,32 +1,32 @@
 # HarmonyOS NEXT 开发者专家技能包 (Reference Skill)
 
 `harmony-next.skills` 是为 AI 编程助手（如 Gemini CLI, Claude Code, Codex）设计的参考技能库。
-它为 HarmonyOS NEXT (API 12+) 提供本地化的离线知识源，包含超过 3,409 份涵盖 ArkTS、ArkUI 和 NDK 的 Markdown 格式参考文档。
+它为 HarmonyOS NEXT (API 12+) 提供本地化的离线知识源，包含 3,400+ 份涵盖 ArkTS、ArkUI 和 NDK 的 Markdown 格式参考文档。
 
 [English Version](./README_en.md)
 
 ## 核心特性 (v1.0.6+)
 
 除了详尽的 API 参考外，本项目现已包含以下**专家级实战指南**：
-- 🛠 **IDE 实操**：应用签名、断点调试、模拟器与真机配置、AI 智能辅助编程。
-- 🤖 **独立工具链**：**独立命令行工具包 (Standalone CLI)** 的下载、环境变量配置及 CI/CD 深度调优。
-- 📱 **多端适配**：一次开发多端部署（自适应/响应式布局）、折叠屏与平板专项适配。
-- 🔄 **自由流转**：跨端迁移、多端协同的核心逻辑与开发步骤。
-- ⚙️ **NDK 开发**：**Node-API (napi)** 基础、C++ 与 ArkTS 跨语言互调。
-- 🚀 **应用发布**：AppGallery Connect 配置、发布证书申请、上架审核流程。
-- 📈 **性能调优**：深入使用 DevEco Profiler 进行 CPU、内存、帧率及启动耗时分析。
-- 🏗 **架构设计**：HAP/HAR/HSP 包结构深度解析、Stage 模型并发机制。
-- 🧪 **自动化测试**：基于 Hypium 的单元测试与 UI 测试，以及 CI/CD 命令行集成。
+- **IDE 实操**：应用签名、断点调试、模拟器与真机配置、AI 辅助编程。
+- **独立工具链**：独立命令行工具包 (Standalone CLI) 的下载、环境变量配置及 CI/CD 调优。
+- **多端适配**：一次开发多端部署（自适应/响应式布局）、折叠屏与平板适配。
+- **自由流转**：跨端迁移、多端协同的核心逻辑与开发步骤。
+- **NDK 开发**：Node-API (napi) 基础、C++ 与 ArkTS 跨语言互调。
+- **应用发布**：AppGallery Connect 配置、证书申请、上架审核流程。
+- **性能调优**：使用 DevEco Profiler 进行 CPU、内存、帧率及启动耗时分析。
+- **架构设计**：HAP/HAR/HSP 包结构、Stage 模型并发机制。
+- **自动化测试**：基于 Hypium 的单元测试与 UI 测试，以及 CI 命令行集成。
 
 ## 工作原理
 
 当你的编程助手需要 HarmonyOS 相关知识时，应使用本仓库作为检索层，而非依赖大模型的训练记忆（避免幻觉）。
 
-**推荐查找流程：**
-1. 查看 [`KITS.md`](harmony-next/references/KITS.md) 确定所属能力集。
-2. 使用 [`TASK_MAP.md`](harmony-next/references/TASK_MAP.md) 将任务需求映射到技术关键词。
-3. 从 [`INDEX.md`](harmony-next/references/INDEX.md) 中定位具体文件。
-4. 遵循 [`SKILL.md`](harmony-next/SKILL.md) 中的规则，以获取精准的 API 级细节。
+**推荐查找流程（渐进式披露）：**
+1. 打开 [`SKILL.md`](harmony-next/SKILL.md) 了解检索规则与回答约束。
+2. 先缩小范围：[`KITS.md`](harmony-next/references/KITS.md)（Kit 识别 + 关键词/模块前缀）或 [`TASK_MAP.md`](harmony-next/references/TASK_MAP.md)（任务到关键词）。
+3. 再精确命中文件：[`INDEX.md`](harmony-next/references/INDEX.md)（全库路径）与 [`JsEtsAPIReference/INDEX.md`](harmony-next/references/JsEtsAPIReference/INDEX.md)（API 分桶路径）。
+4. 命中路径后，只打开那 1-3 个目标 Markdown 获取 API 级细节（不要盲读大库）。
 
 ## 快速开始
 

README_en.md

@@ -1,31 +1,31 @@
 # HarmonyOS NEXT Reference Skill
 
 `harmony-next.skills` is a reference skill for coding agents.
-It provides a local source of truth for HarmonyOS NEXT (API 12+), with 3,409 Markdown references across ArkTS, ArkUI, and NDK topics.
+It provides a local source of truth for HarmonyOS NEXT (API 12+), with 3,400+ Markdown references across ArkTS, ArkUI, and NDK topics.
 
 ## Key Features (v1.0.6+)
 
 Beyond API references, this skill now includes **expert guides** for:
-- 🛠 **IDE Operations**: Signing, Debugging, Emulator/Real Device setup, and AI Assistant.
-- 🤖 **Standalone Toolchain**: Deep dive into **Standalone Command Line Tools** download, env vars, and CI/CD config.
-- 📱 **Multi-device Adaptation**: Strategies for phone, foldable, and tablet (Adaptive/Responsive Layout).
-- 🔄 **Continuation**: Cross-device migration and multi-device collaboration logic.
-- ⚙️ **NDK Development**: Node-API (napi) basics and ArkTS/C++ interoperability.
-- 🚀 **App Publishing**: AGC configuration, certificates, and release process.
-- 📈 **Performance Tuning**: CPU, Memory, Frame Rate, and Launch Analysis via DevEco Profiler.
-- 🏗 **Architecture**: Deep dive into HAP/HAR/HSP structures and Stage Model concurrency.
-- 🧪 **Automation Testing**: Unit and UI testing with Hypium, including CI/CD integration.
+- **IDE Operations**: Signing, Debugging, Emulator/Real Device setup, and AI assistance.
+- **Standalone Toolchain**: Standalone CLI download, env vars, and CI/CD configuration.
+- **Multi-device Adaptation**: Strategies for phone, foldable, and tablet (Adaptive/Responsive Layout).
+- **Continuation**: Cross-device migration and multi-device collaboration logic.
+- **NDK Development**: Node-API (napi) basics and ArkTS/C++ interoperability.
+- **App Publishing**: AGC configuration, certificates, and release process.
+- **Performance Tuning**: CPU, Memory, Frame Rate, and Launch analysis via DevEco Profiler.
+- **Architecture**: HAP/HAR/HSP structures and Stage Model concurrency.
+- **Automation Testing**: Unit and UI testing with Hypium, including CI integration.
 
 ## How It Works
 
 When your agent needs HarmonyOS knowledge, it should use this repository as a retrieval layer instead of guessing from model memory.
 
 Recommended lookup flow:
 
-1. Open [`KITS.md`](harmony-next/references/KITS.md) to locate the correct capability domain.
-2. Use [`TASK_MAP.md`](harmony-next/references/TASK_MAP.md) to map user intent to technical keywords.
-3. Resolve exact files from [`INDEX.md`](harmony-next/references/INDEX.md).
-4. Follow rules in [`SKILL.md`](harmony-next/SKILL.md) to answer with concrete API-level detail.
+1. Read [`SKILL.md`](harmony-next/SKILL.md) for retrieval rules and answer constraints.
+2. Narrow scope via [`KITS.md`](harmony-next/references/KITS.md) (kit identification + keywords/module prefixes) or [`TASK_MAP.md`](harmony-next/references/TASK_MAP.md) (intent to keywords).
+3. Resolve exact files from [`INDEX.md`](harmony-next/references/INDEX.md) (full paths) and [`JsEtsAPIReference/INDEX.md`](harmony-next/references/JsEtsAPIReference/INDEX.md) (bucketed API paths).
+4. Open only the 1-3 matched Markdown files for API-level detail (avoid blind reads).
 
 This keeps responses precise, traceable, and stable.
 

harmony-next/SKILL.md

@@ -1,58 +1,35 @@
 ---
 name: harmony-next
-description: Expert guidance for HarmonyOS NEXT (API 12+) development. Use this skill for ArkTS, ArkUI, and NDK development using official offline documentation for 3,300+ APIs and components.
+description: HarmonyOS NEXT（API 12+）离线参考库导航：按 Kit/任务/索引渐进式定位文档（ArkTS/ArkUI/NDK）。
 ---
 
-# HarmonyOS NEXT Expert
+# HarmonyOS NEXT（离线文档导航）
 
-This skill equips you with comprehensive, offline knowledge of HarmonyOS 5+ (ArkTS, ArkUI, NDK, System Services, etc.). The `references/` directory contains thousands of localized Markdown files directly converted from official developer documentation.
+目标：在不盲读 `references/` 的前提下，快速定位到 1 个或少量目标 Markdown，然后只打开这些文件。
 
-## How to use this skill
+## 渐进式披露（按顺序走）
 
-Because the reference library is massive (~50MB, 3300+ files), **DO NOT attempt to read files blindly**. You MUST use the `grep_search` and `glob` tools to find the exact API or module you need before reading the specific Markdown file.
+1. **先缩小范围（选 Kit 或任务）**
+   - Kit 导航：`references/KITS.md`
+   - 任务导向：`references/TASK_MAP.md`
 
-### Recommended Workflow (Optimized Search Protocol)
+2. **再精确命中文件（搜路径清单）**
+   - 全库路径清单：`references/INDEX.md`
+   - JS/ETS API 分桶清单：`references/JsEtsAPIReference/INDEX.md`
 
-Due to the massive size of this knowledge base (3,300+ files), you MUST follow this **Three-Tier Search Protocol** to avoid being overwhelmed by irrelevant files:
+3. **仅在必要时浏览目录**
+   `references/JsEtsAPIReference/` 已按桶分层：`modules/`、`topics/`、`capi/headers/`、`types/`、`errors/`、`guides/`。
 
-1. **Tier 1: Identify the Kit (Read `references/KITS.md`)**
-   HarmonyOS 5+ is organized by Kits (e.g., `AbilityKit`, `ArkUI`, `MediaKit`). Read `references/KITS.md` first to identify which Kit contains the functionality you need. This drastically narrows down the search space.
+## 常用检索（直接复制用）
 
-2. **Tier 2: Task-to-File Mapping (Read `references/TASK_MAP.md`)**
-   For common tasks (Layout, Lifecycle, Network), check `references/TASK_MAP.md`. It links tasks to their most important keywords and Kits.
+- 先按关键词命中路径：`rg -n "UIAbility|AbilityStage|Want" references/INDEX.md | head`
+- 查某个 `@ohos.*` 模块：`rg -n "@ohos\\.app\\.ability\\.|@ohos\\.ability\\." references/JsEtsAPIReference/INDEX.md | head`
+- 查 NDK/C API 头文件：`rg -n "^capi/headers/.*(napi|arkui|window|ability).*\\.h\\.md$" references/JsEtsAPIReference/INDEX.md | head`
 
-3. **Tier 3: Surgical Grep (via `references/INDEX.md`)**
-   Once you have the Kit name or specific keywords, use `grep` on `references/INDEX.md` to find the exact filenames.
-   - *Example*: `grep "AbilityKit" references/INDEX.md | grep "Context"`
+## 生成约束（避免踩坑）
 
-### Core Content Structure
+- **不要全量读取**：先在 `INDEX.md` 命中路径，再打开对应 `.md`。
+- **不确定就查文档**：API 签名、入参、返回值以 `references/` 内文本为准，不凭经验补全。
+- **ArkUI 优先声明式**：示例优先使用 `@Entry` / `@Component` / `build()`（除非文档明确是 NDK 或系统服务）。
 
-- `JsEtsAPIReference/`: Detailed API signatures and C-API headers.
-- `quickStart/`: Step-by-step developer guides.
-- `ideGuides/`: Comprehensive IDE guides (Signing, Running, Debugging, CLI Tools, Standalone CLI Config).
-- `performanceAndStandards/`: Performance optimization and UX best practices (Profiler, Latency, Memory).
-- `appBasics/`: Core architecture guides (HAP/HAR/HSP, Stage Model, Concurrency).
-- `multiDevice/`: Multi-device adaptation strategies (Adaptive/Responsive Layout).
-- `continuation/`: Cross-device migration and multi-device collaboration.
-- `ndkGuides/`: Native development guides (Node-API, C++ integration).
-- `publishing/`: AppGallery Connect release and publishing process.
-- `testing/`: Automation testing guides using Hypium.
-- `KITS.md`: The primary navigation hub organized by @kit.
-- `INDEX.md`: The full file list for surgical lookups.
-
-### Directory Structure under `references/`
-
-- `JsEtsAPIReference/` : Contains the bulk of ArkTS and ArkUI component APIs, lifecycle methods, error codes, and C-API/NDK headers.
-- `quickStart/` : Beginner tutorials and fundamental concepts (e.g., page navigation, entry points).
-- `ideGuides/` : IDE operational guides, CLI references, and debugging methodologies.
-- `performanceAndStandards/` : Profiling tools (Insight) and app performance standards.
-- `appBasics/` : Fundamental application architecture, models, and package structures.
-- `testing/` : Testing frameworks and UI automation strategies.
-- `hos/` & `hos_en/` : Core concepts, system services, and framework overviews.
-
-## Core Directives for HarmonyOS Generation
-
-1. **Strictly Declarative**: Always use the declarative UI paradigm syntax (`@Entry`, `@Component`, `build()`).
-2. **No Hallucinations**: Rely strictly on the documentation provided in the `references/` folder when unsure about an API signature in HarmonyOS 5+. Do not assume standard Web JS or Android APIs are available unless verified in the docs.
-3. **TypeScript/ArkTS Validation**: Ensure type safety and use standard ArkTS conventions.
-\n<!-- version: 1.0.1 -->
+<!-- version: 1.1.0 -->