cangming-ai-dev-kit 0.1.0

data/domains/harmony/skills/harmony-code/SKILL.md

@@ -0,0 +1,73 @@
+# harmony-code — HarmonyOS 代码编写
+
+## description
+在纯血 HarmonyOS 项目中使用 ArkTS / ArkUI 编写高质量代码。
+
+## when to use
+- 编写 HarmonyOS 页面/组件
+- 实现 HarmonyOS 业务逻辑
+- 重构 HarmonyOS 代码
+
+## 核心规则
+
+### 1. 只写 HarmonyOS 代码
+- **不写** Flutter / Android / iOS 代码
+- 使用 ArkTS（兼容 TypeScript 语法子集）
+- 使用 ArkUI 声明式 UI
+
+### 2. 分层架构
+
+```
+page/          — 页面层（组合组件、管理页面状态）
+components/   — 可复用组件层
+model/        — 数据模型层
+service/      — 网络请求/数据处理层
+utils/        — 工具函数层
+```
+
+### 3. 不把复杂逻辑塞进 build()
+❌ 错误：
+```typescript
+build() {
+  // 100 行复杂逻辑
+  let result = complexCalculation(); // 不要！
+  this.dataList = transformData(rawData); // 不要！
+}
+```
+
+✅ 正确：
+```typescript
+aboutToAppear() {
+  this.initData();
+}
+
+build() {
+  Column() {
+    TitleBar({ title: this.title });
+    ContentList({ data: this.dataList });
+  }
+}
+
+private initData(): void {
+  this.dataList = this.transformData(rawData);
+}
+```
+
+### 4. 状态管理
+- 页面级状态用 @State + @Link
+- 跨页面状态用 AppStorage
+- 组件级状态用 @Prop
+- 深层传递用 @Provide + @Consume
+
+### 5. 修改后验证
+每次修改后必须执行：
+```bash
+bash domains/harmony/scripts/verify_harmony.sh
+```
+
+## done criteria
+- [ ] 符合 HarmonyOS 分层架构
+- [ ] build() 中无复杂逻辑
+- [ ] 状态管理使用正确
+- [ ] 无跨平台代码混入
+- [ ] 验证脚本通过

data/domains/harmony/skills/harmony-plan/SKILL.md

@@ -0,0 +1,68 @@
+# harmony-plan — HarmonyOS 项目计划
+
+## description
+针对纯血 HarmonyOS（鸿蒙原生）项目的计划制定。覆盖 ArkTS、ArkUI、路由、状态管理等关键环节。
+
+## when to use
+- 启动新的 HarmonyOS 项目
+- 为 HarmonyOS 项目添加新功能
+- HarmonyOS 项目重构
+
+## workflow
+1. 确认是纯血 HarmonyOS 项目（非 Android 套壳）
+2. 阅读项目结构（src/ets 目录结构）
+3. 页面拆解和路由设计
+4. 状态管理层设计
+5. 权限声明检查
+6. 本地存储方案确定
+7. 服务层设计
+8. 测试与构建方案
+9. 输出计划
+
+## 检查清单
+
+### 页面拆解
+- [ ] 列出所有页面及导航关系
+- [ ] 每个页面的输入和输出定义
+- [ ] 公共组件复用拆分
+
+### 路由
+- [ ] router.pushUrl / router.replaceUrl 使用
+- [ ] 路由参数类型定义
+- [ ] 页面返回逻辑
+
+### 状态管理
+- [ ] @State / @Prop / @Link / @Provide + @Consume
+- [ ] AppStorage / LocalStorage 使用
+- [ ] 全局状态 vs 局部状态
+
+### 权限
+- [ ] oh-permission 声明
+- [ ] 动态权限申请
+- [ ] 权限被拒绝的处理
+
+### 本地存储
+- [ ] Preferences 使用
+- [ ] 数据库（关系型/RDB）使用
+- [ ] 文件存储
+
+### 服务层
+- [ ] http 请求封装
+- [ ] 数据模型定义
+- [ ] 错误处理
+
+### 测试与构建
+- [ ] ohpm install 依赖
+- [ ] hvigorw assembleHap 构建
+- [ ] hdc 安装部署
+
+## output format
+遵循 core/skills/plan-first/SKILL.md 的输出格式，加上 HarmonyOS 专项检查结果。
+
+## done criteria
+- [ ] 页面拆解完成
+- [ ] 路由方案确定
+- [ ] 状态管理方案确定
+- [ ] 权限列表明确
+- [ ] 存储方案确定
+- [ ] 构建验证方案确定

data/domains/harmony/skills/harmony-verify/SKILL.md

@@ -0,0 +1,68 @@
+# harmony-verify — HarmonyOS 项目验证
+
+## description
+对 HarmonyOS 项目执行完整的验证流程：依赖安装、lint、测试、构建。
+
+## when to use
+- HarmonyOS 代码修改完成后
+- 构建部署前
+- PR 提交前
+
+## workflow
+1. 确认当前目录是 HarmonyOS 项目
+2. 执行 `ohpm install`（如果 ohpm 可用）
+3. 执行 lint 检查
+4. 执行测试
+5. 执行 `hvigorw assembleHap` 构建
+6. 记录所有结果
+
+## 验证步骤
+
+### 1. 依赖安装
+```bash
+ohpm install
+```
+- 如果 ohpm 不存在：输出 SKIP，原因是命令行工具未安装
+- 如果执行失败：输出 FAIL，需要修复依赖
+
+### 2. Lint
+使用 `hvigorw lint` 或等效命令。
+- 如果命令不存在：输出 SKIP
+- 不伪造结果
+
+### 3. 测试
+```bash
+./hvigorw test
+```
+- 如果命令不存在：输出 SKIP
+- 不伪造结果
+
+### 4. 构建
+```bash
+./hvigorw assembleHap
+```
+- 如果 hvigorw 不存在：输出 SKIP
+- 不伪造结果
+
+## output format
+
+```markdown
+## HarmonyOS 验证报告
+
+| 步骤 | 命令 | 结果 | 说明 |
+|------|------|------|------|
+| install | ohpm install | PASS | / |
+| lint | hvigorw lint | SKIP | 命令不存在 |
+| test | hvigorw test | SKIP | 命令不存在 |
+| build | hvigorw assembleHap | PASS | / |
+
+最终结果：PASS
+```
+
+## done criteria
+- [ ] ohpm install 已完成（或明确跳过）
+- [ ] lint 已执行（或明确跳过）
+- [ ] 测试已执行（或明确跳过）
+- [ ] 构建已完成（或明确跳过）
+- [ ] 无伪造的 PASS
+- [ ] 报告已输出

data/exe/cangming-dev-kit

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/cangming_ai_dev_kit"
+
+CangmingAiDevKit::CLI.start(ARGV)

data/lib/cangming_ai_dev_kit/adapter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module CangmingAiDevKit
+  class Adapter
+    attr_reader :name, :relative_root, :plugin_dir_name, :plugin_file
+
+    def initialize(name, plugin_dir_name:)
+      @name = name
+      @plugin_dir_name = plugin_dir_name
+      @relative_root = "adapters/#{name}"
+      @plugin_file = "#{plugin_dir_name}/plugin.json"
+    end
+
+    def plugin_file_relative
+      "#{relative_root}/#{plugin_file}"
+    end
+
+    def skill_paths(data_root)
+      paths = []
+      skills_dir = File.join(data_root, relative_root, plugin_dir_name)
+      return paths unless Dir.exist?(skills_dir)
+      Dir.glob("#{skills_dir}/skills/*")
+      paths
+    end
+
+    def adapter_full_path(target_dir)
+      File.join(target_dir, "adapters", name)
+    end
+
+    SCAFFOLD_DIRS = %w[
+      skills
+    ].freeze
+
+    SCAFFOLD_FILES = {
+      "claude-code" => {
+        ".claude-plugin/plugin.json"        => "adapters/claude-code/.claude-plugin/plugin.json",
+        "hooks/hooks.json"                  => "adapters/claude-code/hooks/hooks.json",
+        "agents/planner.md"                 => "adapters/claude-code/agents/planner.md",
+        "agents/coder.md"                   => "adapters/claude-code/agents/coder.md",
+        "agents/reviewer.md"                => "adapters/claude-code/agents/reviewer.md",
+      },
+      "codex" => {
+        ".codex-plugin/plugin.json"         => "adapters/codex/.codex-plugin/plugin.json",
+        "AGENTS.md.template"                => "adapters/codex/AGENTS.md.template",
+      },
+    }.freeze
+
+    def scaffold_files(data_root)
+      SCAFFOLD_FILES.fetch(@name, {})
+    end
+
+    SKILL_SOURCE_PATTERNS = [
+      "core/skills/*",       # → skills/core/<name>/SKILL.md
+      "domains/*/skills/*",  # → skills/<domain>/<name>/SKILL.md
+    ].freeze
+
+    def self.available
+      @available ||= {
+        "claude-code" => new("claude-code", plugin_dir_name: ".claude-plugin"),
+        "codex"       => new("codex",       plugin_dir_name: ".codex-plugin"),
+      }
+    end
+
+    def self.resolve(name)
+      available[name] || available["claude-code"]
+    end
+  end
+end

data/lib/cangming_ai_dev_kit/cli.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+require_relative "commands/init"
+require_relative "commands/sync"
+require_relative "commands/verify"
+
+module CangmingAiDevKit
+  class CLI
+    def self.start(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      command = argv.empty? ? "help" : argv.shift
+
+      case command
+      when "init"
+        do_init(argv)
+      when "sync"
+        do_sync(argv)
+      when "verify"
+        do_verify(argv)
+      when "version", "--version", "-v"
+        puts "cangming-ai-dev-kit #{VERSION}"
+      else
+        help
+      end
+    end
+
+    private
+
+    def do_init(argv)
+      adapter_name = argv.shift || "claude-code"
+      target_dir   = argv.shift || "."
+      with_skills  = argv.include?("--with-skills")
+      force        = argv.include?("--force")
+
+      Commands::Init.new(target_dir, adapter_name, with_skills: with_skills, force: force).run
+    end
+
+    def do_sync(argv)
+      target_dir = "."
+      adapter    = nil
+      dry_run    = false
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: cangming-dev-kit sync [DIR] [options]"
+
+        opts.on("--adapter ADAPTER", "Sync to specific adapter (claude-code, codex)") { |v| adapter = v }
+        opts.on("--dry-run", "Preview only") { |v| dry_run = v }
+      end
+
+      parser.parse!(argv)
+      # 如果还有剩余参数, 视为 target_dir
+      target_dir = argv.shift if argv.first && !argv.first.start_with?("-")
+
+      Commands::Sync.new(target_dir, adapter: adapter, dry_run: dry_run).run
+    end
+
+    def do_verify(argv)
+      target_dir = argv.shift || "."
+      ok = Commands::Verify.new(target_dir).run
+      exit(1) unless ok
+    end
+
+    def help
+      puts "cangming-ai-dev-kit #{VERSION}"
+      puts ""
+      puts "Usage: cangming-dev-kit COMMAND [options]"
+      puts ""
+      puts "Commands:"
+      puts "  init ADAPTER [DIR]     Bootstrap adapter skeleton"
+      puts "    --with-skills        Also sync skills"
+      puts "    --force              Overwrite existing files"
+      puts ""
+      puts "  sync [DIR]             Sync skills to adapter directory"
+      puts "    --adapter ADAPTER    Sync to specific adapter only"
+      puts "    --dry-run            Preview mode"
+      puts ""
+      puts "  verify [DIR]           Validate project structure"
+      puts "  version                Print version"
+      puts ""
+      puts "Adapters: claude-code, codex"
+    end
+  end
+end

data/lib/cangming_ai_dev_kit/commands/init.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module CangmingAiDevKit
+  module Commands
+    class Init
+      def initialize(target_dir, adapter_name, with_skills: false, force: false)
+        @target_dir   = target_dir
+        @adapter_name = adapter_name
+        @with_skills  = with_skills
+        @force        = force
+      end
+
+      def run
+        data_root = Syncer.data_root
+        adapter   = Adapter.resolve(@adapter_name)
+        dest_root = adapter.adapter_full_path(@target_dir)
+
+        FileUtils.mkdir_p(dest_root)
+
+        files = adapter.scaffold_files(data_root)
+        files.each do |relative_dest, source_relative|
+          source = File.join(data_root, source_relative)
+          dest   = File.join(dest_root, relative_dest)
+
+          if File.exist?(dest) && !@force
+            puts "  SKIP #{relative_dest} (已存在，使用 --force 覆盖)"
+            next
+          end
+
+          FileUtils.mkdir_p(File.dirname(dest))
+          FileUtils.cp(source, dest)
+          puts "  #{@adapter_name}/#{relative_dest}"
+        end
+
+        # 创建 skills 占位目录
+        skills_dir = File.join(dest_root, "skills")
+        FileUtils.mkdir_p(skills_dir)
+
+        if @with_skills
+          puts ""
+          puts "--- 同步 skills ---"
+          syncer = Syncer.new
+          syncer.sync(@target_dir, adapter: @adapter_name, dry_run: false)
+        end
+
+        puts ""
+        puts "#{@adapter_name} adapter 已就绪: #{dest_root}"
+      end
+    end
+  end
+end

data/lib/cangming_ai_dev_kit/commands/sync.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CangmingAiDevKit
+  module Commands
+    class Sync
+      def initialize(target_dir, adapter: nil, dry_run: false)
+        @target_dir = target_dir
+        @adapter    = adapter
+        @dry_run    = dry_run
+      end
+
+      def run
+        syncer = Syncer.new
+        stats  = syncer.sync(@target_dir, adapter: @adapter, dry_run: @dry_run)
+
+        puts ""
+        stats.each do |adp, info|
+          status = @dry_run ? "[dry-run]" : "[synced]"
+          puts "#{status} #{adp}: #{info[:count]} skills"
+          info[:skills].each { |s| puts "  - #{s}" }
+        end
+      end
+    end
+  end
+end

data/lib/cangming_ai_dev_kit/commands/verify.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CangmingAiDevKit
+  module Commands
+    class Verify
+      def initialize(target_dir)
+        @target_dir = target_dir
+      end
+
+      def run
+        verifier = Verifier.new(@target_dir)
+        result   = verifier.verify
+
+        puts ""
+        puts "===== 验证汇总 ====="
+        puts "  PASS: #{result.pass}"
+        puts "  FAIL: #{result.fail}"
+        puts "  WARN: #{result.warn}"
+
+        if result.fail.zero?
+          puts ""
+          puts "  MVP_VERIFY_PASS"
+          return true
+        else
+          puts ""
+          puts "  MVP_VERIFY_FAIL (#{result.fail} 项失败)"
+          return false
+        end
+      end
+    end
+  end
+end

data/lib/cangming_ai_dev_kit/syncer.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module CangmingAiDevKit
+  class Syncer
+    # 返回 gem 安装后的项目根目录
+    def self.gem_data_root
+      @gem_data_root ||= begin
+        spec = Gem::Specification.find_by_name("cangming-ai-dev-kit")
+        spec.gem_dir
+      end
+    rescue Gem::LoadError
+      # 开发模式：从 lib/ 往上找到项目根目录
+      File.expand_path("../..", __dir__)
+    end
+
+    def self.data_root
+      @data_root ||= gem_data_root
+    end
+
+    # 收集所有 skill 源
+    # 返回 [{ category:, name:, path: }]
+    def self.skill_sources
+      sources = []
+
+      root = data_root
+      return sources unless Dir.exist?(root)
+
+      # core/skills/*
+      core_skills = File.join(root, "core", "skills")
+      if Dir.exist?(core_skills)
+        Dir.glob("#{core_skills}/*").each do |dir|
+          next unless File.directory?(dir)
+          sources << { category: "core", name: File.basename(dir), path: dir }
+        end
+      end
+
+      # domains/*/skills/*
+      domains_dir = File.join(root, "domains")
+      if Dir.exist?(domains_dir)
+        Dir.glob("#{domains_dir}/*/skills/*").each do |dir|
+          next unless File.directory?(dir)
+          parts = dir.split("/")
+          domain = parts[-3]
+          name   = parts[-1]
+          sources << { category: domain, name: name, path: dir }
+        end
+      end
+
+      sources
+    end
+
+    # 列出所有可用 adapter 的名称
+    def self.adapters_available
+      @adapters_available ||= ["claude-code", "codex"]
+    end
+
+    # 同步 skills 到指定 adapter(s)
+    # target_dir: 目标根目录（包含 adapters/<name>/skills/）
+    # adapter: 可选，仅同步指定 adapter
+    # dry_run: 仅预览，不实际复制
+    # 返回同步统计 { adapter => { count:, skills: [] } }
+    def sync(target_dir, adapter: nil, dry_run: false)
+      adapters = adapter ? [adapter] : self.class.adapters_available
+      sources  = self.class.skill_sources
+      stats    = {}
+
+      adapters.each do |adp|
+        skills_root = File.join(target_dir, "adapters", adp, "skills")
+        copied = []
+
+        if dry_run
+          puts "[#{adp}] 目标: #{skills_root}"
+          puts "[#{adp}] 将清空 skills/ 目录并重新同步"
+        elsif Dir.exist?(skills_root)
+          FileUtils.rm_rf(Dir.glob("#{skills_root}/*"))
+        else
+          FileUtils.mkdir_p(skills_root)
+        end
+
+        sources.each do |src|
+          dest_dir  = File.join(skills_root, src[:category], src[:name])
+          dest_file = File.join(dest_dir, "SKILL.md")
+          src_file  = File.join(src[:path], "SKILL.md")
+
+          if dry_run
+            puts "  #{src[:category]}/#{src[:name]} → #{dest_file}"
+          else
+            FileUtils.mkdir_p(dest_dir)
+            FileUtils.cp(src_file, dest_file)
+          end
+          copied << "#{src[:category]}/#{src[:name]}"
+        end
+
+        stats[adp] = { count: copied.size, skills: copied }
+      end
+
+      stats
+    end
+  end
+end