cangming-ai-dev-kit 0.1.0

data/core/skills/safe-code-change/SKILL.md

@@ -0,0 +1,48 @@
+# safe-code-change — 安全地修改代码
+
+## description
+以小步迭代的方式安全地修改代码，最小化引入缺陷的风险。
+
+## when to use
+- 修改已有代码
+- 修复 bug
+- 重构
+- 新增功能
+
+## workflow
+1. 确认计划已批准
+2. 一次只改一个逻辑单元
+3. 每次修改后检查 diff
+4. 运行相关测试
+5. 如果失败：回滚或记录原因
+6. 提交前再次审查 diff
+
+## 规则
+
+### 小步修改
+- 一次改一个文件，或一组紧密关联的文件
+- 每次 diff 不超过 100 行（合理范围内）
+- 修改后立即检查影响
+
+### 不引入无关依赖
+- 不要为了省事引入新的第三方库
+- 优先使用项目已有的依赖
+
+### 不破坏现有 API
+- 不改动已有公开函数签名（除非计划中明确）
+- 如需修改，先标记废弃再替换
+
+### 保持项目风格
+- 遵守项目已有的代码风格
+- 如果项目有 .eslintrc / tsconfig，确保不违反
+
+### 失败处理
+- 如果修改导致测试失败，优先修复
+- 如果无法修复，回滚并记录原因
+
+## done criteria
+- [ ] 修改范围符合计划
+- [ ] diff 已审查
+- [ ] 测试通过
+- [ ] 无新增 lint 错误
+- [ ] 未引入无关依赖

data/core/skills/verify-before-done/SKILL.md

@@ -0,0 +1,71 @@
+# verify-before-done — 完成前必须验证
+
+## description
+在宣布任务完成之前，运行所有验证脚本确保质量。不允许跳过或伪造验证结果。
+
+## when to use
+- 每次代码修改完成后
+- 宣布任务完成之前
+- PR 提交之前
+- Agent 对话结束之前
+
+## workflow
+1. 运行 `bash core/scripts/detect_project_type.sh` 识别项目类型
+2. 根据项目类型运行对应的 verify 脚本
+3. 记录每条命令及其输出
+4. 验证全部通过后才能宣布完成
+5. 如果验证失败 → 修复问题 → 重新验证
+
+## verify 命令
+
+```bash
+# 通用验证
+bash core/scripts/verify_project.sh
+
+# HarmonyOS 专项验证
+bash domains/harmony/scripts/verify_harmony.sh
+
+# MVP 项目自验证
+bash scripts/verify_mvp.sh
+```
+
+## output format
+
+```markdown
+## 验证报告
+
+### 项目类型
+{项目类型}
+
+### 执行命令
+
+1. `{command_1}`
+   输出：
+   ```
+   {output}
+   ```
+   结果：{PASS/FAIL}
+
+2. `{command_2}`
+   输出：
+   ```
+   {output}
+   ```
+   结果：{PASS/FAIL}
+
+### 最终结果
+{全部 PASS / 存在失败项}
+```
+
+## done criteria
+- [ ] 项目类型已识别
+- [ ] 验证脚本已执行
+- [ ] 所有命令已记录
+- [ ] 全部 PASS → 可宣布完成
+- [ ] 存在 FAIL → 继续修复，不完成
+
+## 禁止行为
+- ❌ 不执行验证就宣布完成
+- ❌ 命令失败但说"通过"
+- ❌ 跳过不存在的命令但不记录
+- ❌ 伪造命令输出

data/domains/harmony/references/arkts_syntax.md

@@ -0,0 +1,90 @@
+# ArkTS 语法规则
+
+ArkTS 是 HarmonyOS 原生开发语言，基于 TypeScript 的子集。
+
+## 基本规则
+
+- ArkTS 是静态类型语言，所有变量必须有类型
+- 使用 `let` 和 `const`，不使用 `var`
+- 文件名使用小驼峰：`myComponent.ets`
+
+## 类型系统
+
+```typescript
+// 基础类型
+let name: string = 'hello';
+let age: number = 25;
+let isActive: boolean = true;
+
+// 数组
+let items: string[] = ['a', 'b', 'c'];
+let numbers: Array<number> = [1, 2, 3];
+
+// 联合类型
+let value: string | number = 'hello';
+
+// 对象类型
+interface User {
+  name: string;
+  age?: number;  // 可选
+}
+```
+
+## class 与 interface
+
+```typescript
+// interface
+interface Product {
+  id: string;
+  name: string;
+  price: number;
+}
+
+// class
+class ShoppingCart {
+  private items: Product[] = [];
+
+  addItem(item: Product): void {
+    this.items.push(item);
+  }
+
+  get total(): number {
+    return this.items.reduce((sum, i) => sum + i.price, 0);
+  }
+}
+```
+
+## 装饰器（@）
+
+ArkTS 中装饰器用于 UI 状态管理：
+
+```typescript
+@Component
+struct MyComponent {
+  @State count: number = 0;
+  @Prop title: string;
+  @Link parentValue: string;
+}
+```
+
+## async/await
+
+ArkTS 支持 async/await：
+
+```typescript
+async fetchData(): Promise<void> {
+  try {
+    const data = await httpRequest();
+    // 处理数据
+  } catch (e) {
+    console.error('请求失败', e);
+  }
+}
+```
+
+## 注意事项
+
+- 不能使用 JavaScript 动态特性（eval、with 等）
+- 不能使用 `as any` 绕过类型检查
+- 推荐用 `for...of` 替代 `for...in`
+- 使用 `===` 和 `!==`，不使用 `==` 和 `!=`

data/domains/harmony/references/arkui_rules.md

@@ -0,0 +1,81 @@
+# ArkUI 规则
+
+ArkUI 是 HarmonyOS 声明式 UI 框架。
+
+## build() 方法
+
+```typescript
+@Component
+struct MyView {
+  build() {
+    Column() {
+      Text('Hello')
+        .fontSize(20)
+        .fontWeight(FontWeight.Bold);
+      Button('Click')
+        .onClick(() => this.handleClick());
+    }
+    .padding(16)
+    .width('100%');
+  }
+}
+```
+
+## 组件拆分原则
+
+- 一个文件一个 struct（组件）
+- 公共 UI 拆分为独立 Component
+- 组件通过 @Prop 接收数据
+
+```typescript
+@Component
+struct UserCard {
+  @Prop user: UserInfo;
+
+  build() {
+    Row() {
+      Image(this.user.avatar)
+        .width(40)
+        .height(40);
+      Column() {
+        Text(this.user.name);
+        Text(this.user.email)
+          .fontSize(12)
+          .fontColor(Color.Gray);
+      }
+    }
+  }
+}
+```
+
+## 状态管理
+
+| 装饰器 | 作用域 | 说明 |
+|--------|--------|------|
+| @State | 组件内 | 组件内部可变状态 |
+| @Prop | 父→子 | 单向传递，只读 |
+| @Link | 双向 | 父子组件双向同步 |
+| @Provide | 提供者 | 向子孙组件提供数据 |
+| @Consume | 消费者 | 接收 @Provide 数据 |
+| @StorageLink | 全局 | AppStorage 全局状态 |
+| @LocalStorageLink | 页面 | LocalStorage 页面状态 |
+
+## 布局组件
+
+| 组件 | 用途 |
+|------|------|
+| Column | 垂直排列 |
+| Row | 水平排列 |
+| Stack | 层叠布局 |
+| Flex | 弹性布局 |
+| Grid | 网格布局 |
+| List | 列表布局 |
+| Scroll | 可滚动容器 |
+
+## 注意事项
+
+- build() 中不要写复杂逻辑（超过 10 行请提取方法）
+- 条件渲染使用 `if`，不支持 switch
+- 循环渲染使用 `ForEach`
+- 使用 `aboutToAppear()` 替代 `ngOnInit` 或 `constructor`
+- TODO SafeArea 需要手动处理

data/domains/harmony/references/common_compile_errors.md

@@ -0,0 +1,40 @@
+# 常见编译错误与排查方向
+
+## ArkTS 编译错误
+
+| 错误 | 可能原因 | 排查方向 |
+|------|----------|----------|
+| `Cannot find name` | 变量未声明或未 import | 检查 import 路径 |
+| `Type 'X' is not assignable to type 'Y'` | 类型不匹配 | 检查变量类型声明 |
+| `Property 'X' does not exist on type 'Y'` | 访问了不存在的属性 | 检查接口定义 |
+| `Argument of type 'X' is not assignable to parameter of type 'Y'` | 参数类型错误 | 检查函数签名 |
+| `Object is possibly 'undefined'` | 未做空值检查 | 添加 `?.` 或 `if` 判断 |
+| `Cannot use 'X' as a JSX element` | 组件未正确注册 | 检查 `@Component` 装饰器 |
+| `Decorators are not valid here` | 装饰器位置错误 | 装饰器只能用于 struct/class 成员 |
+
+## ArkUI 运行时错误
+
+| 错误 | 可能原因 | 排查方向 |
+|------|----------|----------|
+| 页面白屏/不显示 | build() 抛异常 | 检查 build() 中是否有异常逻辑 |
+| 状态不更新 | @State 未正确使用 | 确认使用 @State 装饰可变变量 |
+| 页面跳转失败 | 路由未注册 | 检查 module.json5 中的 pages 列表 |
+| 图片不显示 | 资源路径错误 | 使用 `$r('app.media.xxx')` 引用资源 |
+| `@Link` 同步失败 | 父组件未传参 | 检查父组件是否正确绑定 |
+
+## Hvigor 构建错误
+
+| 错误 | 可能原因 | 排查方向 |
+|------|----------|----------|
+| `ohpm install` 失败 | 网络连接异常 | 检查网络/镜像源配置 |
+| `assembleHap` 失败 | 编译错误 | 先执行 `hvigorw clean` |
+| 签名失败 | 签名证书配置错误 | 检查 build-profile.json5 |
+| 依赖冲突 | 版本不兼容 | `ohpm install` 时注意版本输出 |
+
+## 排查通用步骤
+
+1. 查看具体错误栈和行号
+2. 运行 `hvigorw clean` 后重试
+3. 检查 `package.json5` 和 `oh-package.json5` 配置
+4. 确认 DevEco Studio 和 SDK 版本匹配
+5. 搜索社区或官方 issue 看是否有已知问题

data/domains/harmony/references/harmony_project_structure.md

@@ -0,0 +1,56 @@
+# HarmonyOS 项目结构
+
+## 推荐目录结构
+
+```
+MyHarmonyApp/
+├── oh-package.json5          # ohpm 依赖配置
+├── hvigorfile.ts             # 构建配置
+├── build-profile.json5       # 构建配置
+├── hvigor/                   # 构建缓存
+├── AppScope/                 # 应用级资源
+│   ├── app.json5             # 应用配置
+│   └── resources/            # 应用级资源
+├── entry/
+│   ├── oh-package.json5      # entry 模块依赖
+│   ├── build-profile.json5   # entry 构建配置
+│   └── src/main/
+│       ├── ets/
+│       │   ├── pages/        # 页面文件
+│       │   │   ├── Index.ets
+│       │   │   ├── Home.ets
+│       │   │   └── Detail.ets
+│       │   ├── components/   # 可复用组件
+│       │   │   ├── TitleBar.ets
+│       │   │   └── UserCard.ets
+│       │   ├── model/        # 数据模型
+│       │   │   ├── User.ets
+│       │   │   └── Product.ets
+│       │   ├── service/      # 网络/数据服务
+│       │   │   ├── api.ets
+│       │   │   └── storage.ets
+│       │   └── utils/        # 工具函数
+│       │       └── format.ets
+│       ├── resources/        # entry 资源
+│       └── module.json5      # 模块配置
+└── library/                  # 共享库（可选）
+    ├── oh-package.json5
+    └── src/main/ets/
+```
+
+## 分层说明
+
+| 层 | 职责 | 可依赖 |
+|----|------|--------|
+| pages/ | 页面组合、页面级状态 | components, model, service |
+| components/ | 通用 UI 组件 | model |
+| model/ | 数据模型定义 | 无（纯数据类） |
+| service/ | 网络请求、数据处理 | model |
+| utils/ | 纯工具函数 | 无 |
+
+## 关键配置文件
+
+- `AppScope/app.json5` — 应用名称、版本、图标
+- `entry/src/main/module.json5` — 页面注册、权限声明
+- `oh-package.json5` — 三方依赖
+- `build-profile.json5` — 签名、构建配置

data/domains/harmony/references/hvigor_ohpm_hdc_commands.md

@@ -0,0 +1,40 @@
+# hvigor / ohpm / hdc 常用命令
+
+## ohpm（包管理）
+
+| 命令 | 说明 |
+|------|------|
+| `ohpm install` | 安装所有依赖 |
+| `ohpm install @ohos/axios` | 安装指定包 |
+| `ohpm uninstall @ohos/axios` | 卸载包 |
+| `ohpm list` | 列出已安装包 |
+| `ohpm cache clean` | 清理缓存 |
+
+## hvigor（构建工具）
+
+| 命令 | 说明 |
+|------|------|
+| `./hvigorw assembleHap` | 构建 HAP 包 |
+| `./hvigorw assembleApp` | 构建 APP 包 |
+| `./hvigorw clean` | 清理构建产物 |
+| `./hvigorw lint` | 运行 lint |
+| `./hvigorw test` | 运行测试 |
+| `./hvigorw run` | 运行应用 |
+
+## hdc（设备调试）
+
+| 命令 | 说明 |
+|------|------|
+| `hdc list targets` | 列出设备 |
+| `hdc install entry.hap` | 安装 HAP |
+| `hdc uninstall com.example.app` | 卸载应用 |
+| `hdc shell` | 进入设备 shell |
+| `hdc file send local remote` | 推送文件 |
+| `hdc file recv remote local` | 拉取文件 |
+| `hdc hilog` | 查看日志 |
+| `hdc hilog -T xxx` | 按 tag 过滤日志 |
+
+## DevEco Studio
+
+推荐使用 DevEco Studio 进行可视化开发、调试和 profiling。
+命令行主要用于 CI/CD 流程。

data/domains/harmony/scripts/build_hap.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# build_hap.sh — 对 HarmonyOS 项目执行 HAP 构建
+# 用法: bash domains/harmony/scripts/build_hap.sh [项目目录]
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR" 2>/dev/null
+
+echo "[Harmony Build] 检查项目目录..."
+
+# 判断是否为 HarmonyOS 项目
+if [ ! -f "oh-package.json5" ] && [ ! -f "hvigorfile.ts" ]; then
+    echo "[Harmony Build] 当前目录不是 HarmonyOS 项目，跳过构建"
+    exit 0
+fi
+
+echo "[Harmony Build] 检测到 HarmonyOS 项目"
+
+# 尝试 hvigorw assembleHap
+if [ -f "./hvigorw" ]; then
+    echo "[Harmony Build] 执行 hvigorw assembleHap..."
+    ./hvigorw assembleHap 2>&1
+    EXIT_CODE=$?
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "[Harmony Build] PASS"
+    else
+        echo "[Harmony Build] FAIL (exit code: $EXIT_CODE)"
+    fi
+    exit $EXIT_CODE
+fi
+
+# 尝试 ohpm build
+if command -v ohpm &> /dev/null; then
+    echo "[Harmony Build] 执行 ohpm build (如果有)..."
+    ohpm run build 2>/dev/null && echo "[Harmony Build] PASS" || echo "[Harmony Build] SKIP (未配置 build 脚本)"
+    exit 0
+fi
+
+echo "[Harmony Build] SKIP — 未找到 hvigorw 命令"
+exit 0

data/domains/harmony/scripts/lint_harmony.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+# lint_harmony.sh — 对 HarmonyOS 项目执行 lint 检查
+# 用法: bash domains/harmony/scripts/lint_harmony.sh [项目目录]
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR" 2>/dev/null
+
+echo "[Harmony Lint] 检查项目目录..."
+
+# 判断是否为 HarmonyOS 项目
+if [ ! -f "oh-package.json5" ] && [ ! -f "hvigorfile.ts" ]; then
+    echo "[Harmony Lint] 当前目录不是 HarmonyOS 项目，跳过 lint"
+    exit 0
+fi
+
+echo "[Harmony Lint] 检测到 HarmonyOS 项目"
+
+# 尝试 hvigorw lint
+if [ -f "./hvigorw" ]; then
+    echo "[Harmony Lint] 执行 hvigorw lint..."
+    ./hvigorw lint 2>&1
+    EXIT_CODE=$?
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "[Harmony Lint] PASS"
+    else
+        echo "[Harmony Lint] FAIL (exit code: $EXIT_CODE)"
+    fi
+    exit 0
+fi
+
+# 尝试 ohpm 或其它 lint 工具
+if command -v ohpm &> /dev/null; then
+    echo "[Harmony Lint] 执行 ohpm lint (如果有)..."
+    ohpm run lint 2>/dev/null && echo "[Harmony Lint] PASS" || echo "[Harmony Lint] SKIP (未配置 lint 脚本)"
+    exit 0
+fi
+
+echo "[Harmony Lint] SKIP — 未找到 hvigorw 或 lint 命令"
+exit 0

data/domains/harmony/scripts/test_harmony.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# test_harmony.sh — 对 HarmonyOS 项目执行测试
+# 用法: bash domains/harmony/scripts/test_harmony.sh [项目目录]
+
+PROJECT_DIR="${1:-.}"
+cd "$PROJECT_DIR" 2>/dev/null
+
+echo "[Harmony Test] 检查项目目录..."
+
+# 判断是否为 HarmonyOS 项目
+if [ ! -f "oh-package.json5" ] && [ ! -f "hvigorfile.ts" ]; then
+    echo "[Harmony Test] 当前目录不是 HarmonyOS 项目，跳过测试"
+    exit 0
+fi
+
+echo "[Harmony Test] 检测到 HarmonyOS 项目"
+
+# 尝试 hvigorw test
+if [ -f "./hvigorw" ]; then
+    echo "[Harmony Test] 执行 hvigorw test..."
+    ./hvigorw test 2>&1
+    EXIT_CODE=$?
+    if [ $EXIT_CODE -eq 0 ]; then
+        echo "[Harmony Test] PASS"
+    else
+        echo "[Harmony Test] FAIL (exit code: $EXIT_CODE)"
+    fi
+    exit $EXIT_CODE
+fi
+
+echo "[Harmony Test] SKIP — 未找到 hvigorw 命令"
+exit 0

data/domains/harmony/scripts/verify_harmony.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# verify_harmony.sh — HarmonyOS 项目完整验证流程
+# 依次执行: ohpm install → lint → test → build
+# 用法: bash domains/harmony/scripts/verify_harmony.sh [项目目录]
+
+PROJECT_DIR="${1:-.}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$PROJECT_DIR" 2>/dev/null
+
+echo "===== HarmonyOS 验证 ====="
+echo "项目目录: $(pwd)"
+echo ""
+
+# 判断是否为 HarmonyOS 项目
+if [ ! -f "oh-package.json5" ] && [ ! -f "hvigorfile.ts" ]; then
+    echo "[Verify] 当前目录不是 HarmonyOS 项目，跳过验证"
+    echo "===== 验证结束 ====="
+    exit 0
+fi
+
+PASS_COUNT=0
+FAIL_COUNT=0
+SKIP_COUNT=0
+
+# 1. ohpm install
+echo "--- 步骤 1/4: ohpm install ---"
+if command -v ohpm &> /dev/null; then
+    echo "[Verify] 执行 ohpm install..."
+    ohpm install 2>&1
+    if [ $? -eq 0 ]; then
+        echo "[Verify] ohpm install: PASS"
+        PASS_COUNT=$((PASS_COUNT + 1))
+    else
+        echo "[Verify] ohpm install: FAIL"
+        FAIL_COUNT=$((FAIL_COUNT + 1))
+    fi
+else
+    echo "[Verify] ohpm install: SKIP (ohpm 命令未安装)"
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+fi
+echo ""
+
+# 2. lint
+echo "--- 步骤 2/4: Lint ---"
+bash "$SCRIPT_DIR/lint_harmony.sh" "$PROJECT_DIR" 2>&1 | tail -1
+# 从输出判断结果
+LAST_LINE=$(bash "$SCRIPT_DIR/lint_harmony.sh" "$PROJECT_DIR" 2>&1 | tail -1)
+if echo "$LAST_LINE" | grep -q "PASS"; then
+    PASS_COUNT=$((PASS_COUNT + 1))
+elif echo "$LAST_LINE" | grep -q "SKIP"; then
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+else
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+fi
+echo ""
+
+# 3. test
+echo "--- 步骤 3/4: Test ---"
+bash "$SCRIPT_DIR/test_harmony.sh" "$PROJECT_DIR" 2>&1 | tail -1
+LAST_LINE=$(bash "$SCRIPT_DIR/test_harmony.sh" "$PROJECT_DIR" 2>&1 | tail -1)
+if echo "$LAST_LINE" | grep -q "PASS"; then
+    PASS_COUNT=$((PASS_COUNT + 1))
+elif echo "$LAST_LINE" | grep -q "SKIP"; then
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+else
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+fi
+echo ""
+
+# 4. build
+echo "--- 步骤 4/4: Build ---"
+bash "$SCRIPT_DIR/build_hap.sh" "$PROJECT_DIR" 2>&1 | tail -1
+LAST_LINE=$(bash "$SCRIPT_DIR/build_hap.sh" "$PROJECT_DIR" 2>&1 | tail -1)
+if echo "$LAST_LINE" | grep -q "PASS"; then
+    PASS_COUNT=$((PASS_COUNT + 1))
+elif echo "$LAST_LINE" | grep -q "SKIP"; then
+    SKIP_COUNT=$((SKIP_COUNT + 1))
+else
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+fi
+echo ""
+
+# 汇总
+echo "===== 验证汇总 ====="
+echo "PASS: $PASS_COUNT | FAIL: $FAIL_COUNT | SKIP: $SKIP_COUNT"
+if [ $FAIL_COUNT -eq 0 ]; then
+    echo "结果: PASS"
+else
+    echo "结果: FAIL ($FAIL_COUNT 项失败)"
+fi
+echo "===== 验证结束 ====="
+exit $FAIL_COUNT