DevEco Code 在 Windows/MacOS 双系统上的完整使用指南

本文档将整合 Windows 和 MacOS 两大平台的所有内容，包含丰富的代码示例、详细的注释、实战案例以及全面的附录。

DevEco Code 在 Windows/MacOS 双系统上的完整使用指南

- 摘要
- 目录
- [一、DevEco Code 概述与双平台适配](#一、DevEco Code 概述与双平台适配)
- - [1.1 什么是 DevEco Code](#1.1 什么是 DevEco Code)
  - [1.2 DevEco Code 的技术架构深度剖析](#1.2 DevEco Code 的技术架构深度剖析)
  - [1.3 Windows 与 MacOS 平台的独特优势与挑战对比](#1.3 Windows 与 MacOS 平台的独特优势与挑战对比)
  - - [Windows 平台](#Windows 平台)
    - [MacOS 平台](#MacOS 平台)
    - 双平台对比表
  - [1.4 DevEco Code 与 DevEco Studio、CodeGenie 的区别](#1.4 DevEco Code 与 DevEco Studio、CodeGenie 的区别)
  - [1.5 核心能力总览](#1.5 核心能力总览)
  - [1.6 适用场景与目标用户](#1.6 适用场景与目标用户)
- 二、环境准备与前置条件
- - [2.1 操作系统要求](#2.1 操作系统要求)
  - - [Windows 系统要求](#Windows 系统要求)
    - [MacOS 系统要求](#MacOS 系统要求)
  - [2.2 硬件配置建议](#2.2 硬件配置建议)
  - [2.3 必备软件清单](#2.3 必备软件清单)
  - [2.4 华为开发者账号准备](#2.4 华为开发者账号准备)
  - [2.5 Xcode Command Line Tools 安装（仅 MacOS）](#2.5 Xcode Command Line Tools 安装（仅 MacOS）)
  - [2.6 网络环境准备](#2.6 网络环境准备)
- [三、安装 Node.js 与 npm 环境](#三、安装 Node.js 与 npm 环境)
- - [3.1 方案一：通过官方安装包安装](#3.1 方案一：通过官方安装包安装)
  - - [Windows：通过 MSI 安装包安装（新手推荐）](#Windows：通过 MSI 安装包安装（新手推荐）)
    - [MacOS：通过 Homebrew 安装](#MacOS：通过 Homebrew 安装)
  - [3.2 方案二：通过 nvm/nvm-windows 管理多版本 Node.js](#3.2 方案二：通过 nvm/nvm-windows 管理多版本 Node.js)
  - - Windows：nvm-windows
    - MacOS：nvm
  - [3.3 方案三：通过 fnm 管理 Node.js（双平台推荐）](#3.3 方案三：通过 fnm 管理 Node.js（双平台推荐）)
  - - [Windows 安装 fnm](#Windows 安装 fnm)
    - [MacOS 安装 fnm](#MacOS 安装 fnm)
  - [3.4 验证 Node.js 与 npm 安装](#3.4 验证 Node.js 与 npm 安装)
  - [3.5 配置 npm 国内镜像源加速](#3.5 配置 npm 国内镜像源加速)
  - [3.6 解决 PowerShell 执行策略限制（Windows 核心避坑指南）](#3.6 解决 PowerShell 执行策略限制（Windows 核心避坑指南）)
  - [3.7 解决全局安装权限与路径问题](#3.7 解决全局安装权限与路径问题)
  - - [Windows 解决方案](#Windows 解决方案)
    - [MacOS 解决方案](#MacOS 解决方案)
  - [3.8 Shell 配置文件详解](#3.8 Shell 配置文件详解)
  - - [MacOS：zsh vs bash](#MacOS：zsh vs bash)
    - [Windows：PowerShell Profile](#Windows：PowerShell Profile)
  - [3.9 Node.js 版本选择策略](#3.9 Node.js 版本选择策略)
- [四、安装 DevEco Code](#四、安装 DevEco Code)
- - [4.1 npm 全局安装命令详解](#4.1 npm 全局安装命令详解)
  - [4.2 安装过程全记录与日志分析](#4.2 安装过程全记录与日志分析)
  - [4.3 验证安装成功](#4.3 验证安装成功)
  - [4.4 Apple Silicon 特殊注意事项（仅 MacOS）](#4.4 Apple Silicon 特殊注意事项（仅 MacOS）)
  - [4.5 安装失败常见原因与排查](#4.5 安装失败常见原因与排查)
  - [4.6 离线安装方案（企业内网环境）](#4.6 离线安装方案（企业内网环境）)
- 五、首次启动与登录配置
- - [5.1 终端选择与启动方式](#5.1 终端选择与启动方式)
  - - [Windows 终端选择](#Windows 终端选择)
    - [MacOS 终端选择](#MacOS 终端选择)
  - [5.2 数据库迁移与本地初始化](#5.2 数据库迁移与本地初始化)
  - [5.3 华为开发者账号 OAuth 登录流程](#5.3 华为开发者账号 OAuth 登录流程)
  - [5.4 隐私政策与使用条款](#5.4 隐私政策与使用条款)
  - [5.5 登录状态管理与凭证安全](#5.5 登录状态管理与凭证安全)
  - [5.6 多账号切换策略](#5.6 多账号切换策略)
- 六、模型配置与第三方模型接入
- - [6.1 内置免费模型 GLM-5.1 详解](#6.1 内置免费模型 GLM-5.1 详解)
  - [6.2 使用 /model 命令切换模型](#6.2 使用 /model 命令切换模型)
  - [6.3 接入 DeepSeek API 完整教程](#6.3 接入 DeepSeek API 完整教程)
  - [6.4 接入通义千问（阿里云百炼）](#6.4 接入通义千问（阿里云百炼）)
  - [6.5 接入智谱 GLM-4 Plus](#6.5 接入智谱 GLM-4 Plus)
  - [6.6 接入月之暗面 Moonshot](#6.6 接入月之暗面 Moonshot)
  - [6.7 接入本地 Ollama 模型](#6.7 接入本地 Ollama 模型)
  - [6.8 配置文件 config.json 深度解析](#6.8 配置文件 config.json 深度解析)
  - [6.9 模型性能对比与选择建议](#6.9 模型性能对比与选择建议)
- [七、DevEco Code 核心功能详解](#七、DevEco Code 核心功能详解)
- - [7.1 智能代码生成与上下文补全](#7.1 智能代码生成与上下文补全)
  - [7.2 页面 UI 生成（声明式 ArkUI）](#7.2 页面 UI 生成（声明式 ArkUI）)
  - [7.3 万能卡片（Widget）生成](#7.3 万能卡片（Widget）生成)
  - [7.4 代码重构与架构优化](#7.4 代码重构与架构优化)
  - [7.5 Bug 诊断与自动修复](#7.5 Bug 诊断与自动修复)
  - [7.6 工程辅助与构建管理（Hvigor & ohpm）](#7.6 工程辅助与构建管理（Hvigor & ohpm）)
  - [7.7 知识问答与文档精准查询](#7.7 知识问答与文档精准查询)
  - [7.8 多文件协同编辑与 Diff 预览](#7.8 多文件协同编辑与 Diff 预览)
- 八、斜杠命令与快捷键大全
- - [8.1 高频必备命令](#8.1 高频必备命令)
  - [8.2 会话与上下文管理命令](#8.2 会话与上下文管理命令)
  - [8.3 模型与配置命令](#8.3 模型与配置命令)
  - [8.4 项目级命令](#8.4 项目级命令)
  - [8.5 调试与诊断命令](#8.5 调试与诊断命令)
  - [8.6 快捷键一览（双平台对比）](#8.6 快捷键一览（双平台对比）)
  - [8.7 MacOS 专属快捷键](#8.7 MacOS 专属快捷键)
  - [8.8 Windows 专属快捷键](#8.8 Windows 专属快捷键)
- [九、实战案例：使用 DevEco Code 开发鸿蒙应用](#九、实战案例：使用 DevEco Code 开发鸿蒙应用)
- - [9.1 实战一：从零创建 HarmonyOS 项目并初始化](#9.1 实战一：从零创建 HarmonyOS 项目并初始化)
  - [9.2 实战二：AI 生成电商首页 UI（完整 ArkTS 代码与注释）](#9.2 实战二：AI 生成电商首页 UI（完整 ArkTS 代码与注释）)
  - [9.3 实战三：网络请求与数据绑定（MVVM 架构实现）](#9.3 实战三：网络请求与数据绑定（MVVM 架构实现）)
  - [9.4 实战四：万能卡片开发（FormExtensionAbility）](#9.4 实战四：万能卡片开发（FormExtensionAbility）)
  - [9.5 实战五：Bug 排查与修复](#9.5 实战五：Bug 排查与修复)
  - [9.6 实战六：代码重构与性能优化（LazyForEach 实战）](#9.6 实战六：代码重构与性能优化（LazyForEach 实战）)
  - [9.7 实战七：MVVM 架构完整实现](#9.7 实战七：MVVM 架构完整实现)
- [十、与 DevEco Studio 协同工作](#十、与 DevEco Studio 协同工作)
- - [10.1 DevEco Studio 双平台安装与配置](#10.1 DevEco Studio 双平台安装与配置)
  - [10.2 双工具协同开发工作流](#10.2 双工具协同开发工作流)
  - [10.3 项目路径切换与上下文同步](#10.3 项目路径切换与上下文同步)
  - [10.4 编译、签名与真机调试配合（hdc 工具链）](#10.4 编译、签名与真机调试配合（hdc 工具链）)
  - [10.5 Git 版本控制协同](#10.5 Git 版本控制协同)
- 十一、高级配置与自定义
- - [11.1 配置文件目录结构（双平台路径详解）](#11.1 配置文件目录结构（双平台路径详解）)
  - - [MacOS 路径](#MacOS 路径)
    - [Windows 路径](#Windows 路径)
  - [11.2 自定义 Agent 行为与记忆文件](#11.2 自定义 Agent 行为与记忆文件)
  - [11.3 MCP（Model Context Protocol）扩展配置](#11.3 MCP（Model Context Protocol）扩展配置)
  - [11.4 自定义提示词模板](#11.4 自定义提示词模板)
  - [11.5 环境变量与 Shell 集成（双平台配置）](#11.5 环境变量与 Shell 集成（双平台配置）)
  - - [MacOS ~/.zshrc 配置](#MacOS ~/.zshrc 配置)
    - [Windows PowerShell Profile 配置](#Windows PowerShell Profile 配置)
  - [11.6 iTerm2 深度集成（MacOS）](#11.6 iTerm2 深度集成（MacOS）)
  - [11.7 Windows Terminal 深度集成与美化](#11.7 Windows Terminal 深度集成与美化)
  - [11.8 自动化脚本](#11.8 自动化脚本)
  - - [MacOS Bash 脚本](#MacOS Bash 脚本)
    - [Windows PowerShell 脚本](#Windows PowerShell 脚本)
- 十二、更新与升级
- - [12.1 deveco upgrade 命令](#12.1 deveco upgrade 命令)
  - [12.2 npm 重新安装升级](#12.2 npm 重新安装升级)
  - [12.3 版本回退策略](#12.3 版本回退策略)
  - [12.4 升级注意事项与数据备份](#12.4 升级注意事项与数据备份)
  - [12.5 自动更新检测脚本](#12.5 自动更新检测脚本)
  - - [MacOS Bash 脚本](#MacOS Bash 脚本)
    - [Windows PowerShell 脚本](#Windows PowerShell 脚本)
- 十三、完整卸载流程
- - [13.1 卸载运行时数据与本地数据库](#13.1 卸载运行时数据与本地数据库)
  - [13.2 npm 全局卸载](#13.2 npm 全局卸载)
  - [13.3 清理残留配置与缓存](#13.3 清理残留配置与缓存)
  - - MacOS
    - [Windows PowerShell](#Windows PowerShell)
  - [13.4 卸载 Node.js（可选）](#13.4 卸载 Node.js（可选）)
  - - [使用 fnm 卸载](#使用 fnm 卸载)
    - [使用 nvm 卸载](#使用 nvm 卸载)
    - [使用 Homebrew 卸载（MacOS）](#使用 Homebrew 卸载（MacOS）)
    - 官方安装包卸载（Windows）
  - [13.5 卸载 Homebrew（MacOS 可选）](#13.5 卸载 Homebrew（MacOS 可选）)
  - [13.6 卸载验证与一键清理脚本](#13.6 卸载验证与一键清理脚本)
  - - 验证卸载完成
    - [MacOS 一键卸载脚本](#MacOS 一键卸载脚本)
    - [Windows 一键卸载脚本](#Windows 一键卸载脚本)
- 十四、常见问题与解决方案（FAQ）
- - [14.1 安装类问题](#14.1 安装类问题)
  - [14.3 模型调用类问题](#14.3 模型调用类问题)
  - [14.4 MacOS 特有问题](#14.4 MacOS 特有问题)
  - [14.5 Windows 特有问题](#14.5 Windows 特有问题)
  - [14.6 性能与稳定性问题](#14.6 性能与稳定性问题)
- 十五、总结与展望
- 附录
- [附录 A：DevEco Code 完整命令参考表](#附录 A：DevEco Code 完整命令参考表)
- - [A.1 核心交互命令](#A.1 核心交互命令)
  - [A.2 会话与上下文管理命令](#A.2 会话与上下文管理命令)
  - [A.3 模型与配置命令](#A.3 模型与配置命令)
  - [A.4 项目管理命令](#A.4 项目管理命令)
  - [A.5 调试与诊断命令](#A.5 调试与诊断命令)
  - [A.6 升级与维护命令](#A.6 升级与维护命令)
  - [A.7 命令行启动参数](#A.7 命令行启动参数)
- [附录 B：双平台环境变量与配置文件速查表](#附录 B：双平台环境变量与配置文件速查表)
- - [B.1 关键环境变量](#B.1 关键环境变量)
  - [B.2 关键配置文件路径对照表](#B.2 关键配置文件路径对照表)
  - [B.3 关键目录路径对照表](#B.3 关键目录路径对照表)
- [附录 C：双平台常用终端命令速查](#附录 C：双平台常用终端命令速查)
- - [C.1 文件与目录操作](#C.1 文件与目录操作)
  - - [MacOS Terminal](#MacOS Terminal)
    - [Windows PowerShell](#Windows PowerShell)
  - [C.2 系统信息与环境查看](#C.2 系统信息与环境查看)
  - - MacOS
    - [Windows PowerShell](#Windows PowerShell)
  - [C.3 网络工具](#C.3 网络工具)
  - - MacOS
    - [Windows PowerShell](#Windows PowerShell)
  - [C.4 常用开发工具命令](#C.4 常用开发工具命令)
  - - [Git 常用命令（双平台通用）](#Git 常用命令（双平台通用）)
    - [ohpm 包管理命令（HarmonyOS 专用）](#ohpm 包管理命令（HarmonyOS 专用）)
- [附录 D：模型 API 参数对照表](#附录 D：模型 API 参数对照表)
- - [D.1 供应商 API 基础信息](#D.1 供应商 API 基础信息)
  - [D.2 模型能力详细对照](#D.2 模型能力详细对照)
  - [D.3 config.json 完整配置示例（多模型全接入）](#D.3 config.json 完整配置示例（多模型全接入）)
- [附录 E：Homebrew 常用 Formulae 列表（MacOS）](#附录 E：Homebrew 常用 Formulae 列表（MacOS）)
- - [E.1 核心开发工具](#E.1 核心开发工具)
  - [E.2 终端增强工具](#E.2 终端增强工具)
  - [E.3 GUI 应用（Homebrew Cask）](#E.3 GUI 应用（Homebrew Cask）)
  - [E.4 Homebrew 常用操作命令](#E.4 Homebrew 常用操作命令)
- [附录 F：ArkTS 常用装饰器速查表](#附录 F：ArkTS 常用装饰器速查表)
- - [F.1 状态管理装饰器](#F.1 状态管理装饰器)
  - [F.2 V2 状态管理装饰器（API 12+）](#F.2 V2 状态管理装饰器（API 12+）)
  - [F.3 组件定义与 UI 构建装饰器](#F.3 组件定义与 UI 构建装饰器)
  - [F.4 生命周期方法速查表](#F.4 生命周期方法速查表)
  - [F.5 装饰器使用规则速查](#F.5 装饰器使用规则速查)
  - [F.6 完整状态管理代码示例](#F.6 完整状态管理代码示例)
- [附录 G：一键安装脚本（双平台 PowerShell/Bash）](#附录 G：一键安装脚本（双平台 PowerShell/Bash）)
- - [G.1 MacOS 一键安装脚本（Bash）](#G.1 MacOS 一键安装脚本（Bash）)
  - [G.2 Windows 一键安装脚本（PowerShell）](#G.2 Windows 一键安装脚本（PowerShell）)
- 学习资料与推荐资源
- - 一、官方核心资源
  - 二、推荐学习路径
  - - [入门阶段（1-2 周）](#入门阶段（1-2 周）)
    - [进阶阶段（2-4 周）](#进阶阶段（2-4 周）)
    - [高级阶段（1-2 个月）](#高级阶段（1-2 个月）)
  - 三、社区与交流平台
  - 四、推荐书籍
  - 五、实用工具推荐
  - [六、DevEco Code 高效使用的 10 条黄金法则](#六、DevEco Code 高效使用的 10 条黄金法则)
- 最终总结

摘要

随着 HarmonyOS NEXT 生态在 2026 年的全面爆发，华为在 HDC 2026 期间震撼发布了面向鸿蒙开发场景的 AI Agent 工具------DevEco Code。这款革命性的工具基于开源项目 OpenCode 深度定制，专为 HarmonyOS 应用及元服务开发进行了全方位的专项优化。它不仅深度理解 ArkTS 语法体系、声明式 UI 范式、Stage 模型、Hvigor 构建系统以及 ohpm 包管理机制，更以终端原生（Terminal-Native）的交互形态，让开发者通过自然语言对话完成从代码生成、页面构建、Bug 修复到工程重构的全链路开发任务。

本文档以 Windows 10/11 和 MacOS 13+ 双系统为平台，从零基础出发，全面覆盖环境搭建、Node.js 安装与多版本管理、npm 镜像配置、权限问题解决、DevEco Code 安装与启动、华为账号登录、内置 GLM-5.1 免费模型使用、DeepSeek 等第三方模型接入、斜杠命令体系、实战开发案例（含完整代码与详细注释）、与 DevEco Studio 的协同工作流、高级自定义配置、MCP 扩展、版本更新升级以及完整卸载流程。

全文结构严谨、步骤详实、代码注释完善，力求为 Windows 和 MacOS 双平台上的鸿蒙开发者提供一份"案头必备"的一站式操作手册。无论你是刚从移动端转型鸿蒙开发的初学者，还是追求极致效率的资深架构师，都能从本文中找到所需的答案。

一、DevEco Code 概述与双平台适配
- 1.1 什么是 DevEco Code
- 1.2 DevEco Code 的技术架构深度剖析
- 1.3 Windows 与 MacOS 平台的独特优势与挑战对比
- 1.4 DevEco Code 与 DevEco Studio、CodeGenie 的区别
- 1.5 核心能力总览
- 1.6 适用场景与目标用户
二、环境准备与前置条件
- 2.1 操作系统要求（Windows/MacOS）
- 2.2 硬件配置建议
- 2.3 必备软件清单
- 2.4 华为开发者账号准备
- 2.5 Xcode Command Line Tools 安装（仅 MacOS）
- 2.6 网络环境准备
三、安装 Node.js 与 npm 环境
- 3.1 方案一：通过官方安装包安装（Windows MSI / MacOS Homebrew）
- 3.2 方案二：通过 nvm/nvm-windows 管理多版本 Node.js
- 3.3 方案三：通过 fnm 管理 Node.js（双平台推荐）
- 3.4 验证 Node.js 与 npm 安装
- 3.5 配置 npm 国内镜像源加速
- 3.6 解决 PowerShell 执行策略限制（Windows 核心避坑指南）
- 3.7 解决全局安装权限与路径问题（双平台）
- 3.8 Shell 配置文件详解（zsh vs bash vs PowerShell Profile）
- 3.9 Node.js 版本选择策略
四、安装 DevEco Code
- 4.1 npm 全局安装命令详解
- 4.2 安装过程全记录与日志分析
- 4.3 验证安装成功
- 4.4 Apple Silicon 特殊注意事项（仅 MacOS）
- 4.5 安装失败常见原因与排查（E404, EPERM, ETIMEDOUT）
- 4.6 离线安装方案（企业内网环境）
五、首次启动与登录配置
- 5.1 终端选择与启动方式（双平台对比）
- 5.2 数据库迁移与本地初始化
- 5.3 华为开发者账号 OAuth 登录流程
- 5.4 隐私政策与使用条款
- 5.5 登录状态管理与凭证安全
- 5.6 多账号切换策略
六、模型配置与第三方模型接入
- 6.1 内置免费模型 GLM-5.1 详解
- 6.2 使用 /model 命令切换模型
- 6.3 接入 DeepSeek API 完整教程
- 6.4 接入通义千问（阿里云百炼）
- 6.5 接入智谱 GLM-4 Plus
- 6.6 接入月之暗面 Moonshot
- 6.7 接入本地 Ollama 模型（双平台配置）
- 6.8 配置文件 config.json 深度解析
- 6.9 模型性能对比与选择建议
七、DevEco Code 核心功能详解
- 7.1 智能代码生成与上下文补全
- 7.2 页面 UI 生成（声明式 ArkUI）
- 7.3 万能卡片（Widget）生成
- 7.4 代码重构与架构优化
- 7.5 Bug 诊断与自动修复
- 7.6 工程辅助与构建管理（Hvigor & ohpm）
- 7.7 知识问答与文档精准查询
- 7.8 多文件协同编辑与 Diff 预览
八、斜杠命令与快捷键大全
- 8.1 高频必备命令
- 8.2 会话与上下文管理命令
- 8.3 模型与配置命令
- 8.4 项目级命令
- 8.5 调试与诊断命令
- 8.6 快捷键一览（双平台对比）
- 8.7 MacOS 专属快捷键
- 8.8 Windows 专属快捷键
九、实战案例：使用 DevEco Code 开发鸿蒙应用
- 9.1 实战一：从零创建 HarmonyOS 项目并初始化
- 9.2 实战二：AI 生成电商首页 UI（完整 ArkTS 代码与注释）
- 9.3 实战三：网络请求与数据绑定（MVVM 架构实现）
- 9.4 实战四：万能卡片开发（FormExtensionAbility）
- 9.5 实战五：Bug 排查与修复（编译错误与运行时异常）
- 9.6 实战六：代码重构与性能优化（LazyForEach 实战）
- 9.7 实战七：MVVM 架构完整实现
十、与 DevEco Studio 协同工作
- 10.1 DevEco Studio 双平台安装与配置
- 10.2 双工具协同开发工作流
- 10.3 项目路径切换与上下文同步
- 10.4 编译、签名与真机调试配合（hdc 工具链）
- 10.5 Git 版本控制协同
十一、高级配置与自定义
- 11.1 配置文件目录结构（双平台路径详解）
- 11.2 自定义 Agent 行为与记忆文件（.deveco-rules.md）
- 11.3 MCP（Model Context Protocol）扩展配置
- 11.4 自定义提示词模板
- 11.5 环境变量与 Shell 集成（双平台配置）
- 11.6 iTerm2 深度集成（MacOS）
- 11.7 Windows Terminal 深度集成与美化（Windows）
- 11.8 自动化脚本（PowerShell / Bash / 快捷指令）
十二、更新与升级
- 12.1 deveco upgrade 命令
- 12.2 npm 重新安装升级
- 12.3 版本回退策略
- 12.4 升级注意事项与数据备份
- 12.5 自动更新检测脚本（双平台）
十三、完整卸载流程
- 13.1 卸载运行时数据与本地数据库
- 13.2 npm 全局卸载
- 13.3 清理残留配置与缓存（双平台差异）
- 13.4 卸载 Node.js（可选）
- 13.5 卸载 Homebrew（MacOS 可选）
- 13.6 卸载验证与一键清理脚本（双平台）
十四、常见问题与解决方案（FAQ）
- 14.1 安装类问题（权限、网络、路径）
- 14.2 登录类问题（OAuth、凭证失效）
- 14.3 模型调用类问题（限流、401、超时）
- 14.4 MacOS 特有问题
- 14.5 Windows 特有问题
- 14.6 性能与稳定性问题
十五、总结与展望
附录
- 附录 A：DevEco Code 完整命令参考表
- 附录 B：双平台环境变量与配置文件速查表
- 附录 C：双平台常用终端命令速查
- 附录 D：模型 API 参数对照表
- 附录 E：Homebrew 常用 Formulae 列表（MacOS）
- 附录 F：ArkTS 常用装饰器速查表
- 附录 G：一键安装脚本（双平台 PowerShell/Bash）
学习资料与推荐资源

一、DevEco Code 概述与双平台适配

1.1 什么是 DevEco Code

DevEco Code 是华为在 2026 年华为开发者大会（HDC 2026）期间正式发布的一款面向 HarmonyOS 开发场景的 终端 AI Agent 工具 。它基于开源项目 OpenCode 深度扩展开发，并针对 HarmonyOS 开发进行了全方位的专项优化。

与传统的 IDE 插件式 AI 助手（如 CodeGenie）不同，DevEco Code 采用了**终端 TUI（Terminal User Interface）**的交互形态。开发者在终端中输入一行命令即可启动工具，随后通过自然语言对话的方式，让 AI Agent 直接读取项目代码、理解工程结构、生成 ArkTS 代码、执行构建命令，甚至自动修复编译错误。

从产品定位来看，DevEco Code 填补了 HarmonyOS 开发生态中"终端级 AI 编程助手"的空白。它进化到了 Agent 模式------它可以主动思考、规划步骤、调用工具（如读写文件、执行 hvigorw 构建）、执行命令，真正实现"你描述需求，AI 完成开发"的愿景。

DevEco Code 的发布，标志着 HarmonyOS 开发工具链正式进入了 Agentic Coding 时代，与业界的 Cursor、Windsurf、Claude Code 等工具站在了同一技术前沿。

1.2 DevEco Code 的技术架构深度剖析

要深入理解 DevEco Code 的能力边界和使用方式，有必要了解其底层技术架构。DevEco Code 的架构可以分为以下五个核心层次：

第一层：终端交互层（Terminal UI Layer）

DevEco Code 使用基于 Ink（React for CLI）框架开发的 TUI 界面。这一层负责：

渲染富文本对话界面，支持 Markdown 语法、代码高亮、表格显示
处理用户键盘输入，包括多行编辑、命令补全、历史记录浏览
管理终端会话状态，包括窗口大小自适应、颜色主题切换
实现文件差异预览（Diff View），以 Git 风格展示 AI 对文件的修改

第二层：Agent 推理层（Agent Reasoning Layer）

这是 DevEco Code 的"大脑"，负责理解开发者意图并规划执行步骤：

意图识别：解析自然语言输入，判断开发者是要生成代码、修复 Bug、还是查询文档
任务分解：将复杂需求拆解为可执行的子任务序列
工具选择：根据任务需要，选择合适的工具（如文件读写、命令执行、代码搜索）
结果验证：检查执行结果是否符合预期，必要时自动重试或调整策略

第三层：工具执行层（Tool Execution Layer）

Agent 通过调用一系列"工具"来完成实际操作：

文件操作工具：读取文件、写入文件、创建目录、搜索文件内容
命令执行工具 ：在终端执行 Shell 命令（如 hvigorw build、ohpm install）
代码分析工具：解析 AST（抽象语法树）、查找符号定义、分析依赖关系
搜索工具：在项目中全局搜索关键词、正则表达式

第四层：模型适配层（Model Adapter Layer）

DevEco Code 通过统一的适配器接口对接不同的大语言模型：

内置 GLM-5.1 模型通道（通过华为 DevEco 服务端代理）
OpenAI 兼容 API 适配器（支持 DeepSeek、通义千问、智谱等）
Ollama 本地模型适配器
模型能力检测（自动判断模型是否支持工具调用 / Function Calling）

第五层：数据持久层（Data Persistence Layer）

管理本地数据的存储和检索：

SQLite 数据库：存储对话历史、会话状态、项目索引
文件系统：存储配置文件、记忆文件、日志
向量索引（可选）：用于项目代码的语义搜索

1.3 Windows 与 MacOS 平台的独特优势与挑战对比

Windows 平台

优势：

庞大的用户基数：Windows 依然是企业级开发和高校教学的主力平台
Windows Terminal 的崛起：微软推出的 Windows Terminal 提供了多标签页、GPU 加速渲染、丰富的配色方案，极大提升了 TUI 应用的体验
WSL2 支持：通过 WSL2，Windows 开发者可以无缝使用 Linux 工具链，甚至运行本地大模型
企业级兼容性：与 Windows Server、Active Directory、企业内网工具链无缝集成

挑战（坑点）：

PowerShell 执行策略 ：默认禁止运行未签名的 .ps1 脚本，导致 npm 全局安装的命令（如 deveco.ps1）无法运行
路径分隔符 ：Windows 使用 \，而 Node.js 和许多开源工具默认使用 /，偶尔会导致路径解析问题
环境变量管理：GUI 界面修改环境变量后，必须重启终端才能生效
权限问题 ：C 盘系统目录（如 C:\Program Files）的写入权限限制，容易导致 npm 全局安装失败（EPERM）

MacOS 平台

优势：

Unix 基因：MacOS 底层基于 BSD Unix（通过 Darwin 内核），终端环境与服务器/Linux 高度一致
Homebrew 生态：Homebrew 是 MacOS 上最强大的包管理器，让环境搭建变得简单优雅
Apple Silicon 性能：M1/M2/M3/M4 系列芯片采用统一内存架构（UMA），性能优异
终端生态丰富：iTerm2、Warp、Alacritty 等丰富的终端模拟器选择
iOS/鸿蒙双栈开发：唯一能同时运行 Xcode 和 DevEco Studio 的平台

挑战（坑点）：

Apple Silicon 路径差异 ：Homebrew 在 Apple Silicon 上安装在 /opt/homebrew/ 而非 /usr/local/
Rosetta 2 兼容问题：在 Rosetta 2 模式下运行终端可能导致架构不匹配
Gatekeeper 安全限制：可能阻止未签名应用的运行

双平台对比表

对比项	Windows	MacOS
默认终端	PowerShell / CMD	Terminal.app
推荐终端	Windows Terminal	iTerm2
包管理器	winget / Chocolatey	Homebrew
Node 版本管理	nvm-windows / fnm	nvm / fnm
配置文件路径	`%USERPROFILE%\.deveco`	`~/.deveco`
环境变量配置	系统设置 GUI	~/.zshrc / ~/.bash_profile
权限模型	UAC 管理员权限	sudo
路径分隔符	`\` 和 `/`	`/`
默认 Shell	PowerShell / CMD	zsh

1.4 DevEco Code 与 DevEco Studio、CodeGenie 的区别

很多开发者容易混淆华为推出的这三款开发工具，下面通过详细对比帮助理解它们各自的定位和使用场景：

对比维度	DevEco Studio	CodeGenie	DevEco Code
定位	官方集成开发环境（IDE）	IDE 内置 AI 编码插件	终端 AI Agent 工具
技术基座	IntelliJ IDEA 平台	DevEco Studio 插件体系	OpenCode 开源项目
交互方式	GUI 图形界面	IDE 侧边栏 / 内联补全	终端 TUI 对话界面
核心能力	编辑/预览/调试/打包/签名	代码补全/智能问答	Agent 自主编程/多步骤任务
AI 深度	无内置 AI（依赖 CodeGenie）	Copilot 模式（被动辅助）	Agent 模式（主动执行）
独立运行	是（完整 IDE）	否（必须依附 IDE）	是（独立终端工具）
双平台支持	Windows + MacOS	Windows + MacOS	Windows + MacOS
资源占用	高（约 2-4GB 内存）	中等（IDE 附加）	低（约 200-500MB）
适用场景	完整开发流程	编码时即时辅助	批量代码生成/重构/自动化
学习曲线	中等	低	低（需基本终端操作能力）

关键区别详解：

CodeGenie（Copilot 模式）：

工作方式类似 GitHub Copilot，在你编码时被动提供建议
主要功能：行级/块级代码补全、选中代码解释、简单问答
优势：无缝嵌入编码流程，不打断思路
局限：无法自主执行多步骤任务，不能直接修改多个文件

DevEco Code（Agent 模式）：

工作方式类似一个"AI 程序员搭档"，你描述需求，它主动完成
主要功能：多文件代码生成、自动构建、Bug 诊断修复、项目重构
优势：能处理复杂的多步骤任务，可以自主读写文件、执行命令
局限：需要终端操作基础，无法替代 IDE 的可视化预览和调试

最佳实践：将 DevEco Code 和 DevEco Studio + CodeGenie 配合使用，发挥各自优势。

1.5 核心能力总览

DevEco Code 的核心能力涵盖鸿蒙开发的方方面面，可以归纳为以下七大能力域：

1. 智能代码生成

根据自然语言描述生成完整的 ArkTS 代码文件
支持生成页面组件、数据模型、工具类、服务层代码
自动遵循 ArkTS 编码规范和 Stage 模型架构
支持生成完整的 TypeScript 类型定义和接口声明

2. 页面 UI 生成

从文字描述直接生成声明式 UI 页面
支持复杂布局：Flex、Grid、List、WaterFlow、Swiper
自动处理状态管理（@State、@Prop、@Link、@Provide）
生成响应式布局代码，适配不同屏幕尺寸

3. 万能卡片生成

HarmonyOS Widget 专项支持
支持 2×2、2×4、4×4 等多种规格
自动生成 FormExtensionAbility 和卡片 UI 模板
处理卡片与宿主应用的数据通信

4. 代码重构优化

识别代码中的"坏味道"（Code Smell）
提取公共组件、消除重复代码
性能优化建议（如 ForEach → LazyForEach）
架构升级（如从 FA 模型迁移到 Stage 模型）

5. Bug 诊断修复

解析编译错误信息，定位问题根因
分析运行时异常，追踪调用链
自动修复代码并验证修复结果
处理 ArkTS 特有的类型约束问题

6. 工程辅助

ohpm 依赖管理与版本冲突解决
module.json5 权限配置与 Ability 注册
Hvigor 构建脚本编写与优化
HAR/HSP 模块化工程管理

7. 知识问答

基于 HarmonyOS 官方文档的精准回答
ArkTS 语法细节解释
API 用法示例和最佳实践
版本差异和迁移指南

1.6 适用场景与目标用户

适用场景：

场景	描述	DevEco Code 的优势
快速原型开发	自然语言 → 可运行代码	数分钟内生成完整页面
复杂业务逻辑	网络请求、数据持久化、状态管理	生成经过良好设计的架构代码
遗留代码重构	导入旧项目，AI 辅助现代化改造	自动识别并重构过时模式
学习探索	新手通过与 AI 对话学习 ArkTS	即时获得带注释的示例代码
效率提升	资深开发者将重复性工作交给 AI	释放精力专注于核心逻辑
代码审查	AI 辅助检查代码质量和安全性	发现人眼容易忽略的问题
文档生成	自动为代码生成注释和文档	提高项目可维护性
测试编写	自动生成单元测试用例	提高代码覆盖率

目标用户：

HarmonyOS 应用开发者：日常使用 Windows 或 MacOS 进行鸿蒙应用开发的专业开发者
鸿蒙元服务开发者：开发轻量级元服务的开发者，需要快速构建卡片和轻量页面
从 iOS/Android 开发转向鸿蒙开发的开发者：熟悉原生开发环境但需要学习 ArkTS 的开发者
全栈移动端开发者：同时维护 iOS/Android/HarmonyOS 多端项目的开发者
鸿蒙技术教育工作者：教授鸿蒙开发课程，需要快速演示代码的教育从业者
开源鸿蒙贡献者：参与 OpenHarmony 社区项目开发的贡献者
企业开发团队：需要标准化开发流程和规范的企业级开发团队

二、环境准备与前置条件

在正式安装 DevEco Code 之前，需要确保你的操作系统环境满足必要的条件。本章将系统性地介绍 Windows 和 MacOS 双平台的所有前置准备工作。

2.1 操作系统要求

Windows 系统要求

操作系统	支持状态	备注
Windows 11 (64位) 22H2+	✅ 完全支持	推荐，原生 Windows Terminal
Windows 10 (64位) 1809+	✅ 完全支持	建议安装 Windows Terminal
Windows 10 (32位)	❌ 不支持	Node.js 新版已放弃 32 位支持
Windows 7 / 8	❌ 不支持	缺乏安全更新和现代终端支持

查看 Windows 版本：

powershell 复制代码

# 在 PowerShell 中执行
systeminfo | findstr /B /C:"OS Name" /C:"OS Version"
# 或
winver

MacOS 系统要求

MacOS 版本	版本号	支持状态	备注
MacOS 15 (Sequoia)	15.x	✅ 完全支持	推荐，最新系统
MacOS 14 (Sonoma)	14.x	✅ 完全支持	推荐，稳定
MacOS 13 (Ventura)	13.x	✅ 完全支持	主流版本
MacOS 12 (Monterey)	12.x	✅ 支持	建议升级到更新版本
MacOS 11 (Big Sur)	11.x	⚠️ 部分支持	Node.js v20+ 可能不兼容
MacOS 10.15 (Catalina)	10.15.x	❌ 不支持	已过时，缺乏安全更新

查看 MacOS 版本：

bash 复制代码

# 方法一：命令行查看
sw_vers
# 输出示例：
# ProductName:    macOS
# ProductVersion: 15.1
# BuildVersion:   24B83

# 方法二：点击左上角苹果图标 → 关于本机

2.2 硬件配置建议

组件	最低配置	推荐配置	旗舰配置
内存	8 GB	16 GB	32 GB 及以上
硬盘	10 GB 可用空间	100 GB SSD	512 GB+ NVMe SSD
处理器	Intel i5 / AMD Ryzen 5 / M1	Intel i7 / AMD Ryzen 7 / M2 Pro	Intel i9 / M3 Max
显示器	1280×800	1920×1080 / Retina	双屏 / 4K 显示器
网络	宽带连接	稳定的宽带	高速光纤（AI 对话流畅）

详细说明：

DevEco Code 本身是一个 Node.js 应用，其 AI 推理在云端完成，因此本地资源消耗主要集中在：

Node.js 运行时：约 100-200 MB 内存
TUI 渲染：约 50-100 MB 内存
项目索引：视项目大小而定，约 50-200 MB

但如果同时运行 DevEco Studio（约 2-4 GB 内存）和模拟器（约 1-2 GB），则 16 GB 内存是保证流畅体验的最低标准。对于大型项目或多任务场景，32 GB 内存可以确保不会出现内存压力导致的卡顿。

2.3 必备软件清单

软件	版本要求	用途	必须	平台
Xcode CLT	最新版	编译工具链	✅ 必须	MacOS
Homebrew	最新版	包管理器	✅ 必须	MacOS
Node.js	v18+ (推荐 v20 LTS)	DevEco Code 运行时	✅ 必须	双平台
npm	v9+（随 Node.js）	Node.js 包管理器	✅ 必须	双平台
Git	v2.30+	版本控制	⚠️ 强烈建议	双平台
DevEco Studio	6.1+	鸿蒙 IDE	⚠️ 强烈建议	双平台
Windows Terminal	最新版	终端增强	⚠️ 强烈建议	Windows
iTerm2	最新版	终端增强	💡 推荐	MacOS

2.4 华为开发者账号准备

使用 DevEco Code 的内置免费模型需要华为开发者账号。以下是准备步骤：

步骤 1：注册华为开发者账号

访问华为开发者联盟
点击右上角"注册"按钮
填写手机号/邮箱，完成注册
验证手机号/邮箱

步骤 2：完成实名认证

登录后进入"个人中心"
选择"开发者认证"
个人开发者：填写身份证信息，进行人脸识别
企业开发者：上传营业执照，填写企业信息

步骤 3：了解免费额度

项目	说明
内置模型	GLM-5.1
费用	免费
速率限制	每分钟 50 次请求
日限额	无明确日限额（合理使用）
并发数	单账号 5 个并发会话

2.5 Xcode Command Line Tools 安装（仅 MacOS）

Xcode Command Line Tools（CLT）是 MacOS 上的基础编译工具链，是安装 Homebrew 和编译原生 npm 模块的前提条件。

核心工具列表：

工具	用途
`clang` / `clang++`	C/C++/Objective-C 编译器
`make`	构建自动化工具
`git`	分布式版本控制系统
`ar` / `ranlib`	静态库工具
`ld`	链接器

检查是否已安装：

bash 复制代码

# 检查 git 是否可用
git --version
# 如果已安装，输出类似：git version 2.43.0

# 检查 clang 编译器
clang --version
# 如果已安装，输出类似：Apple clang version 16.0.0

# 直接检查 CLT 安装状态
xcode-select -p
# 已安装输出：/Library/Developer/CommandLineTools

安装 Command Line Tools：

bash 复制代码

# 方法一：通过 xcode-select 触发安装（推荐）
xcode-select --install
# 执行后会弹出系统对话框，点击"安装"按钮
# 等待下载安装完成（约 1-3 GB，取决于网络速度）

# 方法二：通过 softwareupdate 命令安装（适合自动化脚本）
touch /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
softwareupdate -i -a

验证安装：

bash 复制代码

# 查看 CLT 安装路径
xcode-select -p
# 输出：/Library/Developer/CommandLineTools

# 验证核心工具
git --version       # git version 2.x.x
clang --version     # Apple clang version x.x
make --version      # GNU Make 3.81

2.6 网络环境准备

DevEco Code 需要稳定的网络连接来与 AI 模型服务通信。

检查网络连通性：

bash 复制代码

# Windows PowerShell
curl -I https://developer.huawei.com
curl -I https://registry.npmmirror.com

# MacOS Terminal
curl -I https://developer.huawei.com
curl -I https://registry.npmmirror.com

三、安装 Node.js 与 npm 环境

DevEco Code 基于 Node.js 运行，正确安装和管理 Node.js 版本是至关重要的一步。本章提供三种安装方案，覆盖 Windows 和 MacOS 双平台。

3.1 方案一：通过官方安装包安装

Windows：通过 MSI 安装包安装（新手推荐）

访问 Node.js 官网下载 LTS 版本的 .msi 安装包（如 node-v20.18.1-x64.msi）
双击运行安装向导
关键步骤 ：在 "Custom Setup" 页面，确保勾选 "Add to PATH"
在 "Tools for Native Modules" 页面，建议勾选 "Automatically install the necessary tools"
完成安装

MacOS：通过 Homebrew 安装

bash 复制代码

# 安装 Node.js 20 LTS 版本（推荐）
brew install node@20

# 由于 node@20 是 "keg-only"，需要手动链接
brew link node@20 --force --overwrite

# 将 node@20 的 bin 目录添加到 PATH
echo 'export PATH="/opt/homebrew/opt/node@20/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 验证安装
node -v   # 输出：v20.x.x
npm -v    # 输出：10.x.x

3.2 方案二：通过 nvm/nvm-windows 管理多版本 Node.js

Windows：nvm-windows

卸载现有 Node.js：如果已通过 MSI 安装，请先在"控制面板"中卸载
下载 nvm-windows ：访问 nvm-windows releases，下载 nvm-setup.exe
安装 nvm：运行安装程序，保持默认路径
配置 nvm 镜像：

在 C:\Users\<User>\AppData\Roaming\nvm\settings.txt 中添加：

ini 复制代码

root: C:\Users\<User>\AppData\Roaming\nvm
path: C:\Program Files\nodejs
arch: 64
proxy: none
node_mirror: https://npmmirror.com/mirrors/node/
npm_mirror: https://npmmirror.com/mirrors/npm/

安装并使用 Node.js（在管理员权限的 CMD 或 PowerShell 中运行）：

powershell 复制代码

nvm install 20.18.1
nvm use 20.18.1

MacOS：nvm

bash 复制代码

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 使配置生效
source ~/.zshrc

# 验证 nvm 安装
nvm --version
# 输出：0.40.1

# 安装并使用 Node.js
nvm install 20.18.1
nvm use 20.18.1
nvm alias default 20.18.1

3.3 方案三：通过 fnm 管理 Node.js（双平台推荐）

fnm（Fast Node Manager）是用 Rust 编写的新一代 Node.js 版本管理器，支持 Windows 和 MacOS 双平台。

fnm 优势对比：

对比项	nvm	fnm
编写语言	Bash / Batch	Rust
启动速度	较慢（~300ms）	极快（~10ms）
Shell 集成	有限	完善（自动切换）
跨平台	Mac/Linux (nvm) / Windows (nvm-windows)	Mac/Linux/Windows 统一
Apple Silicon	良好	原生优化

Windows 安装 fnm

powershell 复制代码

# 使用 winget 安装
winget install Schniz.fnm

# 配置 PowerShell Profile
notepad $PROFILE

# 在打开的文件中添加：
fnm env --use-on-cd | Out-String | Invoke-Expression

# 重启终端后使用
fnm install 20
fnm use 20
fnm default 20

MacOS 安装 fnm

bash 复制代码

# 通过 Homebrew 安装
brew install fnm

# 配置 Shell 集成
echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
source ~/.zshrc

# 使用 fnm 安装 Node.js
fnm install 20.18.1
fnm default 20.18.1
fnm use 20.18.1

3.4 验证 Node.js 与 npm 安装

无论使用哪种安装方式，安装完成后都需要进行全面验证：

bash 复制代码

# Windows PowerShell / MacOS Terminal 通用

# ===== 1. 基础版本验证 =====
node -v
# 期望输出：v20.x.x

npm -v
# 期望输出：10.x.x

npx -v
# 期望输出：10.x.x

# ===== 2. 路径验证 =====
which node    # MacOS
Get-Command node | Select-Object Source    # Windows PowerShell

# ===== 3. 架构验证 =====
node -e "console.log(process.arch)"
# Windows: x64
# MacOS Apple Silicon: arm64
# MacOS Intel: x64

# ===== 4. 功能验证 =====
node -e "console.log('Hello from Node.js ' + process.version)"

# ===== 5. 网络验证 =====
npm ping
# 输出：Ping success: true

3.5 配置 npm 国内镜像源加速

bash 复制代码

# 双平台通用命令

# 设置 npmmirror（原淘宝镜像，最快最稳定）
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry
# 输出：https://registry.npmmirror.com/

# 如需恢复官方源
npm config set registry https://registry.npmjs.org/

使用 nrm 管理多个镜像源：

bash 复制代码

# 安装 nrm
npm install -g nrm

# 查看所有可用镜像源
nrm ls

# 切换到 npmmirror
nrm use npmmirror

# 测试所有镜像源速度
nrm test

3.6 解决 PowerShell 执行策略限制（Windows 核心避坑指南）

问题表现 ：在 PowerShell 中执行 deveco 时，报错："无法加载文件...因为在此系统上禁止运行脚本。"

原因：Windows PowerShell 默认禁止运行未签名的 .ps1 脚本，而 npm 全局安装的工具会生成 .ps1 包装器。

解决方案：

以管理员身份打开 PowerShell，执行：

powershell 复制代码

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

输入 Y 确认。这允许运行本地创建的脚本，同时要求从网络下载的脚本必须有签名，兼顾了安全与便利。

3.7 解决全局安装权限与路径问题

Windows 解决方案

如果 npm 全局安装路径在 C 盘系统目录，可能会遇到 EPERM 权限错误。建议将 npm 全局目录修改到用户目录：

powershell 复制代码

# 1. 创建目录
mkdir C:\npm-global

# 2. 设置 npm prefix
npm config set prefix "C:\npm-global"

# 3. 将 C:\npm-global 添加到系统环境变量 PATH 中
# (通过 Windows 设置 → 系统 → 关于 → 高级系统设置 → 环境变量)

MacOS 解决方案

bash 复制代码

# 方案一：修改 npm 全局目录权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# 方案二：更改 npm 全局目录到用户目录（推荐非版本管理器用户）
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

最佳实践：使用 fnm 或 nvm 管理 Node.js，全局安装默认在用户目录下，完全不需要 sudo，也不会有权限问题。

3.8 Shell 配置文件详解

MacOS：zsh vs bash

MacOS 从 Catalina（10.15）开始默认使用 zsh 作为默认 Shell。

zsh 配置文件加载顺序：

复制代码

1. /etc/zshenv          # 系统级，总是被加载
2. ~/.zshenv            # 用户级，总是被加载
3. /etc/zprofile        # 系统级，登录 Shell 时加载
4. ~/.zprofile          # 用户级，登录 Shell 时加载
5. /etc/zshrc           # 系统级，交互式 Shell 时加载
6. ~/.zshrc             # 用户级，交互式 Shell 时加载（最常用！）

日常开发中，绝大部分配置应写入 ~/.zshrc。

Windows：PowerShell Profile

PowerShell 的配置文件位置：

复制代码

$PROFILE                                    # 当前用户当前主机
$PROFILE.AllUsersCurrentHost               # 所有用户当前主机
$PROFILE.CurrentUserAllHosts              # 当前用户所有主机
$PROFILE.AllUsersAllHosts                 # 所有用户所有主机

查看 Profile 路径：

powershell 复制代码

echo $PROFILE
# 输出：C:\Users\<User>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

3.9 Node.js 版本选择策略

Node.js 版本	状态	适用场景	建议
v18.x	LTS 维护期	稳定项目	可用但建议升级
v20.x	活跃 LTS	推荐日常使用	✅ 首选
v22.x	Current	尝鲜/测试	可用于非生产环境
v23.x	Current	实验性	不推荐

版本选择建议：

DevEco Code 日常开发：使用 v20 LTS，稳定可靠
多项目维护 ：使用 fnm 管理，每个项目通过 .node-version 指定版本
CI/CD 环境：锁定到具体的小版本号（如 20.18.1）

四、安装 DevEco Code

环境准备就绪后，终于可以安装 DevEco Code 了。本章将详细介绍双平台的安装过程、验证方法和常见问题的排查。

4.1 npm 全局安装命令详解

打开终端（Windows PowerShell 或 MacOS Terminal），执行以下命令进行全局安装：

bash 复制代码

# 双平台通用命令
npm install -g @deveco/deveco-code

参数详解：

参数	全称	含义
`npm install`	-	npm 包安装命令
`-g`	`--global`	全局安装模式，使 `deveco` 命令在系统任何位置可用
`@deveco/deveco-code`	-	npm 包全名（@deveco 为华为官方命名空间）

备选安装命令（OpenHarmony SIG 社区版本）：

bash 复制代码

# 如果官方包未发布或不可用，可以尝试社区版本
npm install -g @openharmony-sig/deveco-code

4.2 安装过程全记录与日志分析

bash 复制代码

$ npm install -g @deveco/deveco-code

# npm 开始解析依赖树...
npm WARN deprecated some-package@1.0.0: This package is deprecated

# 下载并安装所有依赖包
added 287 packages in 38s

# 显示资金赞助信息
47 packages are looking for funding
  run `npm fund` for details

$

安装过程中，npm 会自动完成以下工作：

依赖解析 ：解析 @deveco/deveco-code 的完整依赖树（约 200-300 个包）
包下载：从 npm 仓库下载所有依赖包（总计约 50-100 MB）
文件解压 ：将包文件解压到全局 node_modules 目录
原生编译：编译包含 C++ 原生扩展的 npm 模块（如 node-pty）
链接创建 ：在全局 bin 目录创建 deveco 可执行文件的符号链接
命令注册 ：将 deveco 命令注册到系统 PATH

全局安装位置（因平台和安装方式不同而异）：

安装方式	Windows 路径	MacOS 路径
fnm	`%APPDATA%\fnm\node-versions\...`	`~/Library/Application Support/fnm/...`
nvm	`%APPDATA%\nvm\v20.18.1\`	`~/.nvm/versions/node/v20.18.1/`
官方安装包	`C:\Program Files\nodejs\`	`/opt/homebrew/` (Apple Silicon)
自定义	`C:\npm-global\`	`~/.npm-global/`

4.3 验证安装成功

bash 复制代码

# 双平台通用验证命令

# ===== 验证 1：查看版本号 =====
deveco --version
# 期望输出：1.0.0（或更高版本）

# ===== 验证 2：查看帮助信息 =====
deveco --help
# 应显示完整的命令行帮助

# ===== 验证 3：查看命令位置 =====
which deveco    # MacOS
Get-Command deveco | Select-Object Source    # Windows PowerShell

# ===== 验证 4：快速启动测试 =====
deveco
# 应成功启动 TUI 交互界面

4.4 Apple Silicon 特殊注意事项（仅 MacOS）

在 Apple Silicon Mac 上安装 DevEco Code 时，需要特别注意以下几点：

1. 确保终端以 arm64 模式运行

bash 复制代码

# 检查当前终端架构
arch
# 期望输出：arm64

# 如果输出 i386 或 x86_64，说明在 Rosetta 2 模式下运行
# 解决方法：
# 1. 关闭当前终端
# 2. 在 Finder 中找到终端应用
# 3. 右键 → 显示简介 → 取消勾选"使用 Rosetta 打开"
# 4. 重新打开终端

2. 验证 Node.js 架构

bash 复制代码

# 确认 Node.js 是 arm64 原生版本
node -e "console.log(process.arch)"
# 期望输出：arm64（而非 x64）

4.5 安装失败常见原因与排查

问题 1：EACCES / EPERM 权限错误

bash 复制代码

npm ERR! code EACCES
npm ERR! syscall mkdir
npm ERR! errno -13
npm ERR! Error: EACCES: permission denied

排查与解决：

bash 复制代码

# Windows：以管理员身份运行终端，或参考 3.7 节修改全局路径

# MacOS 方案一：修改目录权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# MacOS 方案二：使用 fnm/nvm 避免权限问题（推荐）

问题 2：404 Not Found

bash 复制代码

npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmmirror.com/@deveco/deveco-code

排查与解决：

bash 复制代码

# 可能原因：国内镜像尚未同步该包
# 临时切换到官方源安装
npm install -g @deveco/deveco-code --registry https://registry.npmjs.org/

问题 3：node-gyp 编译失败

bash 复制代码

gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2

排查与解决：

bash 复制代码

# Windows：重新运行 Node.js 安装程序，勾选 "Tools for Native Modules"
# 或手动安装：
npm install -g windows-build-tools

# MacOS：确保 Xcode CLT 已正确安装
xcode-select --install

# 或重新安装 CLT
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

问题 4：网络超时

bash 复制代码

npm ERR! code ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/ failed

排查与解决：

bash 复制代码

# 方案 A：使用国内镜像
npm config set registry https://registry.npmmirror.com
npm install -g @deveco/deveco-code
# 方案 B：增加超时时间
npm install -g @deveco/deveco-code --fetch-timeout=300000

4.6 离线安装方案（企业内网环境）

如果目标机器无法直接连接互联网，可以在有网络的机器上预先下载安装包：

bash 复制代码

# ===== 在有网络的机器上操作 =====

# 下载包及其所有依赖到本地目录
npm pack @deveco/deveco-code
# 生成文件：deveco-deveco-code-1.0.0.tgz

# ===== 传输到目标机器 =====
# 使用 U 盘、AirDrop 或 scp 传输 .tgz 文件

# ===== 在目标机器上安装 =====
npm install -g ./deveco-deveco-code-1.0.0.tgz

五、首次启动与登录配置

5.1 终端选择与启动方式

DevEco Code 可以在双平台的多种终端模拟器中运行。以下是推荐的终端选择：

Windows 终端选择

终端	免费	分屏	美化	推荐度
Windows Terminal	✅	✅	丰富	⭐⭐⭐⭐⭐
PowerShell	✅	❌	基础	⭐⭐⭐
CMD	✅	❌	无	⭐⭐
Fluent Terminal	✅	✅	现代	⭐⭐⭐

安装 Windows Terminal：

powershell 复制代码

winget install Microsoft.WindowsTerminal
# 或从 Microsoft Store 安装

MacOS 终端选择

终端	免费	分屏	热键窗口	推荐度
iTerm2	✅	✅	✅	⭐⭐⭐⭐⭐
Terminal.app	✅	❌	❌	⭐⭐
Warp	部分	✅	✅	⭐⭐⭐⭐
Alacritty	✅	❌	❌	⭐⭐⭐

安装推荐终端：

bash 复制代码

# 安装 iTerm2
brew install --cask iterm2

# 安装 Warp
brew install --cask warp

启动 DevEco Code：

bash 复制代码

# 双平台通用启动方式

# 方式 1：在任意目录下启动（适合临时使用）
deveco

# 方式 2：先进入项目目录再启动（推荐，AI 能自动理解项目上下文）
cd ~/HarmonyOSProjects/MyApp    # MacOS
cd D:\HarmonyOSProjects\MyApp   # Windows
deveco

# 方式 3：指定项目路径启动（不切换当前目录）
deveco --cwd ~/HarmonyOSProjects/MyApp

5.2 数据库迁移与本地初始化

首次启动时，DevEco Code 会自动执行一系列初始化操作：

复制代码

╭─────────────────────────────────────────────────╮
│             DevEco Code v1.0.0                  │
│     HarmonyOS AI Agent for Developers           │
│                                                 │
│     "让每一行代码都充满智慧"                       │
╰─────────────────────────────────────────────────╯

Initializing DevEco Code...

◐ Running database migrations...
  ✓ Creating schema v1...
  ✓ Initializing conversation table...
  ✓ Initializing session table...
  ✓ Creating indexes...
  ✓ Migration completed successfully.

◐ Setting up workspace...
  ✓ Creating config directory: ~/.deveco/
  ✓ Initializing AI config: ~/.deveco/ai/config.json
  ✓ Creating log directory: ~/.deveco/logs/
  ✓ Workspace ready.

◐ Checking authentication...
  ⚠ Not authenticated. Please log in to continue.
  → Use the Login option below or run: deveco login

───────────────────────────────────────────────────
  [Login]  [Settings]  [Quit]

初始化过程中，DevEco Code 会在配置目录下创建完整的本地数据存储结构：

复制代码

~/.deveco/                          # DevEco Code 根配置目录
├── data.db                         # 本地 SQLite 数据库
├── ai/
│   ├── config.json                 # 模型配置文件
│   ├── prompts/                    # 自定义提示词模板目录
│   │   ├── system_prompt.md        # 系统级提示词
│   │   └── code_style.md           # 代码风格模板
│   ├── history/                    # 对话历史存档
│   └── memory.md                   # 全局记忆文件
├── auth/
│   └── credentials.json            # 加密的登录凭证
├── cache/
│   ├── models/                     # 模型元数据缓存
│   └── projects/                   # 项目索引缓存
└── logs/
    └── deveco-code.log             # 运行日志

5.3 华为开发者账号 OAuth 登录流程

DevEco Code 提供流畅的交互式登录流程：

步骤 1 ：在 TUI 界面中，使用方向键选择 【Login】 或 【Sign in with HUAWEI account】

步骤 2 ：按 Enter 确认

步骤 3：DevEco Code 自动调用系统命令打开默认浏览器，跳转到华为 OAuth 认证页面

步骤 4：在浏览器中输入华为开发者账号和密码，完成二次验证（如有）

步骤 5：授权成功后，浏览器显示"授权成功，请返回终端"

步骤 6：返回终端，DevEco Code 通过本地回环端口自动检测登录状态

如果浏览器没有自动打开：

bash 复制代码

# MacOS
open "https://developer.huawei.com/consumer/cn/auth?..."

# Windows PowerShell
Start-Process "https://developer.huawei.com/consumer/cn/auth?..."

# 或手动复制终端中显示的完整 URL 到浏览器

命令行登录方式：

bash 复制代码

# 也可以在终端直接执行登录命令
deveco login

5.4 隐私政策与使用条款

首次登录后，DevEco Code 会展示隐私安全政策和使用条款。主要内容包括：

数据收集范围：对话内容、代码片段（仅用于 AI 推理，不做持久化存储）
数据传输：通过 HTTPS 加密传输到华为服务端
本地存储：对话历史仅保存在本地 SQLite 数据库
退出机制：随时可退出登录并清除本地凭证

使用方向键滚动阅读完整条款，选择 【Agree】 确认同意。

5.5 登录状态管理与凭证安全

bash 复制代码

# 双平台通用命令

# 查看当前登录状态
deveco status
# 输出示例：
# DevEco Code v1.0.0
# Authenticated: true
# User: dev@example.com
# Account Type: Individual Developer

# 退出登录
deveco logout
# 输出：Successfully logged out.

# 重新登录
deveco login

凭证安全最佳实践：

不要提交到 Git ：登录凭证保存在 ~/.deveco/auth/credentials.json 中
配置 .gitignore ：在项目的 .gitignore 中添加 .deveco/ 规则
共享电脑使用完毕退出 ：在共享电脑上使用完毕后执行 deveco logout

bash 复制代码

# 在全局 .gitignore 中添加 DevEco 配置排除规则
echo ".deveco/" >> ~/.gitignore_global
echo ".deveco-rules.md" >> ~/.gitignore_global
git config --global core.excludesfile ~/.gitignore_global

5.6 多账号切换策略

如果你需要在多个华为开发者账号之间切换：

bash 复制代码

# 退出当前账号
deveco logout

# 使用新账号重新登录
deveco login

# 或通过备份凭证文件实现快速切换
# MacOS
cp ~/.deveco/auth/credentials.json ~/.deveco/auth/credentials.personal.json
cp ~/.deveco/auth/credentials.company.json ~/.deveco/auth/credentials.json

# Windows PowerShell
Copy-Item "$env:USERPROFILE\.deveco\auth\credentials.json" "$env:USERPROFILE\.deveco\auth\credentials.personal.json"

六、模型配置与第三方模型接入

6.1 内置免费模型 GLM-5.1 详解

DevEco Code 开箱即用地内置了 GLM-5.1 模型，无需额外配置即可使用：

属性	说明
模型名称	GLM-5.1
提供方	华为 DevEco Code 云服务
费用	免费（开发者账号登录后）
速率限制	每分钟 50 次请求
上下文窗口	128K tokens
工具调用	✅ 支持（Function Calling）
代码生成	针对 ArkTS 优化
多轮对话	支持
流式输出	支持

GLM-5.1 模型经过华为针对 HarmonyOS 开发生成场景的专项微调，在以下任务上表现优异：

ArkTS 声明式 UI 代码生成
Stage 模型架构代码组织
HarmonyOS API 正确使用
Hvigor 构建脚本编写

6.2 使用 /model 命令切换模型

在 DevEco Code 的交互式会话中，随时可以通过 /model 命令切换模型：

复制代码

/model

执行后会弹出模型选择列表：

复制代码

┌─ Select Model ──────────────────────────┐
│                                          │
│  ● glm-5.1       (DevEco - Free)        │  ← 当前使用
│  ○ deepseek-chat  (DeepSeek)             │
│  ○ deepseek-coder (DeepSeek)             │
│  ○ qwen-max       (通义千问)              │
│  ○ glm-4-plus     (智谱 AI)              │
│  ○ + Add Provider...                     │
│                                          │
└──────────────────────────────────────────┘

使用方向键选择，Enter 确认。

6.3 接入 DeepSeek API 完整教程

DeepSeek 是目前性价比极高的国产大模型，其 deepseek-coder 模型在代码生成任务上表现优异。

步骤 1：获取 DeepSeek API Key

访问 DeepSeek 开放平台
注册并登录账号
进入 "API Keys" 管理页面
点击 "创建 API Key"
复制生成的密钥（形如 sk-xxxxxxxxxxxxxxxx）

步骤 2：编辑配置文件

bash 复制代码

# MacOS
vim ~/.deveco/ai/config.json

# Windows PowerShell
notepad "$env:USERPROFILE\.deveco\ai\config.json"

写入以下内容：

json 复制代码

{
  "provider": {
    "deveco": {
      "name": "DevEco Code",
      "models": {
        "glm-5": {
          "tool_call": true,
          "limit": 50
        }
      }
    },
    "deepseek": {
      "name": "DeepSeek",
      "api_base": "https://api.deepseek.com",
      "api_key": "sk-your-deepseek-api-key-here",
      "models": {
        "deepseek-chat": {
          "tool_call": true,
          "context_window": 65536,
          "max_tokens": 8192,
          "temperature": 0.7
        },
        "deepseek-coder": {
          "tool_call": true,
          "context_window": 65536,
          "max_tokens": 8192,
          "temperature": 0.3
        }
      }
    }
  }
}

步骤 3：验证 DeepSeek 模型是否正常工作

在 DevEco Code 中切换到 DeepSeek 模型后，发送测试消息：

复制代码

你好，请告诉我你是什么模型，你的能力是什么？

6.4 接入通义千问（阿里云百炼）

通义千问是阿里云推出的大语言模型，通过阿里云百炼平台提供 API 服务。

获取 API Key ：访问阿里云百炼

配置示例：

json 复制代码

{
  "qwen": {
    "name": "通义千问",
    "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
    "api_key": "sk-your-qwen-api-key",
    "models": {
      "qwen-max": {
        "tool_call": true,
        "context_window": 32768,
        "max_tokens": 8192
      },
      "qwen-plus": {
        "tool_call": true,
        "context_window": 131072,
        "max_tokens": 8192
      }
    }
  }
}

6.5 接入智谱 GLM-4 Plus

获取 API Key ：访问智谱 AI 开放平台

json 复制代码

{
  "zhipu": {
    "name": "智谱 AI",
    "api_base": "https://open.bigmodel.cn/api/paas/v4",
    "api_key": "your-zhipu-api-key",
    "models": {
      "glm-4-plus": {
        "tool_call": true,
        "context_window": 128000,
        "max_tokens": 4096
      },
      "glm-4-flash": {
        "tool_call": true,
        "context_window": 128000,
        "max_tokens": 4096
      }
    }
  }
}

6.6 接入月之暗面 Moonshot

获取 API Key ：访问 Moonshot AI 开放平台

json 复制代码

{
  "moonshot": {
    "name": "Moonshot AI",
    "api_base": "https://api.moonshot.cn/v1",
    "api_key": "sk-your-moonshot-api-key",
    "models": {
      "moonshot-v1-8k": {
        "tool_call": true,
        "context_window": 8192
      },
      "moonshot-v1-32k": {
        "tool_call": true,
        "context_window": 32768
      },
      "moonshot-v1-128k": {
        "tool_call": true,
        "context_window": 131072
      }
    }
  }
}

6.7 接入本地 Ollama 模型

Ollama 是在本地运行大模型的最佳工具。它完全离线运行，保护代码隐私。

安装 Ollama：

bash 复制代码

# MacOS
brew install ollama

# Windows
# 从 https://ollama.com/download 下载安装包

启动 Ollama 服务并下载模型：

bash 复制代码

# 双平台通用命令

# 启动 Ollama 后台服务
ollama serve &

# 下载适合代码生成的模型
ollama pull qwen2.5-coder:14b       # 推荐，14B 参数量
ollama pull qwen2.5-coder:7b        # 轻量版
ollama pull deepseek-coder:6.7b     # DeepSeek 代码模型

在 DevEco Code 中配置 Ollama：

json 复制代码

{
  "ollama": {
    "name": "Ollama Local",
    "api_base": "http://localhost:11434/v1",
    "api_key": "ollama",
    "models": {
      "qwen2.5-coder:14b": {
        "tool_call": true,
        "context_window": 32768,
        "max_tokens": 4096
      },
      "deepseek-coder:6.7b": {
        "tool_call": false,
        "context_window": 16384,
        "max_tokens": 4096
      }
    }
  }
}

Ollama 使用的硬件要求：

模型参数量	所需内存（约）	推荐配置
7B	8 GB	入门级
14B	12 GB	中端
32B	24 GB	高端
70B	48 GB	旗舰

6.8 配置文件 config.json 深度解析

~/.deveco/ai/config.json 是 DevEco Code 最核心的配置文件，其完整结构如下：

json 复制代码

{
  "provider": {
    "<provider_id>": {
      "name": "显示名称（在模型选择列表中展示）",
      "api_base": "API 基础地址（OpenAI 兼容格式）",
      "api_key": "API 密钥（内置模型不需要）",
      "models": {
        "<model_id>": {
          "tool_call": true,
          "context_window": 65536,
          "max_tokens": 8192,
          "temperature": 0.7,
          "limit": 60
        }
      }
    }
  },
  "mcp": {
    "servers": []
  },
  "preferences": {
    "default_model": "glm-5",
    "auto_compact_threshold": 80,
    "theme": "dark",
    "language": "zh-CN"
  }
}

各字段详细说明：

字段	类型	说明	默认值
`provider`	Object	模型供应商配置集合	-
`provider.*.name`	String	供应商显示名称	-
`provider.*.api_base`	String	API 基础 URL	-
`provider.*.api_key`	String	API 密钥	-
`provider.*.models`	Object	该供应商下的模型列表	-
`models.*.tool_call`	Boolean	是否支持工具调用	true
`models.*.context_window`	Number	上下文窗口大小（tokens）	32768
`models.*.max_tokens`	Number	最大输出 tokens	8192
`models.*.temperature`	Number	生成温度（0-2）	0.7
`models.*.limit`	Number	每分钟请求限制	60
`mcp.servers`	Array	MCP 扩展服务配置	\[\]
`preferences.default_model`	String	默认使用的模型 ID	"glm-5"
`preferences.auto_compact_threshold`	Number	自动压缩阈值（%）	80
`preferences.theme`	String	界面主题	"dark"

6.9 模型性能对比与选择建议

模型	代码生成	工具调用	响应速度	费用	推荐场景
GLM-5.1（内置）	⭐⭐⭐⭐	✅	快	免费	日常开发首选
DeepSeek Chat	⭐⭐⭐⭐	✅	快	极低	备选方案
DeepSeek Coder	⭐⭐⭐⭐⭐	✅	快	极低	复杂代码生成
通义千问 Max	⭐⭐⭐⭐	✅	中	中等	长上下文任务
智谱 GLM-4 Plus	⭐⭐⭐⭐	✅	中	中等	通用对话
Ollama 本地	⭐⭐⭐	部分	取决于硬件	免费	离线/隐私场景

选择建议：

日常开发：GLM-5.1（免费、快速、ArkTS 优化）
复杂代码任务：DeepSeek Coder（代码生成能力强、性价比高）
大型项目分析：通义千问 Plus（128K 长上下文窗口）
企业保密项目：Ollama + Qwen2.5-Coder（完全本地运行）

七、DevEco Code 核心功能详解

7.1 智能代码生成与上下文补全

DevEco Code 能够根据自然语言描述生成完整的、可运行的 ArkTS 代码。其生成能力覆盖：

数据模型类：接口定义、类实现、数据验证
UI 页面：完整的声明式 UI 组件代码
服务层：网络请求封装、数据库操作、文件 I/O
工具类：日期处理、字符串操作、加密解密
配置文件：module.json5、form_config.json

代码生成的核心提示技巧：

复制代码

# ✅ 好的提示（具体、明确）
创建一个用户管理的数据模型类，使用 @ohos.data.relationalStore 实现本地持久化，
包含 id、name、email、phone、avatar、createTime 字段，
支持增删改查操作，使用单例模式，所有方法使用 async/await。

# ❌ 差的提示（模糊、不明确）
帮我写个用户管理的代码

7.2 页面 UI 生成（声明式 ArkUI）

DevEco Code 对 ArkTS 声明式 UI 有深入的理解，可以生成复杂的页面布局。支持的 UI 组件包括：

组件类别	支持的组件
布局容器	Column、Row、Flex、Stack、RelativeContainer
滚动容器	Scroll、List、Grid、WaterFlow、Swiper
基础组件	Text、Image、Button、TextInput、TextArea
选择组件	Checkbox、Radio、Toggle、Select、Slider
反馈组件	AlertDialog、ActionSheet、Toast、Progress
导航组件	Navigation、Tabs、SideBarContainer

HarmonyOS 万能卡片（Widget）是鸿蒙系统的特色功能，允许应用在桌面上展示实时信息。DevEco Code 可以自动生成完整的卡片代码，包括：

FormExtensionAbility 生命周期实现
卡片 UI 模板（ArkTS 格式）
form_config.json 配置文件
卡片与宿主应用的数据通信

7.4 代码重构与架构优化

DevEco Code 能够识别代码中的"坏味道"（Code Smell）并自动重构：

提取组件：将重复的 UI 代码提取为 @Builder 函数
状态优化：将不必要的 @State 改为普通变量
性能优化：ForEach → LazyForEach、减少嵌套层级
架构升级：FA 模型 → Stage 模型迁移
类型安全：添加缺失的类型注解、修复 any 类型

7.5 Bug 诊断与自动修复

将编译错误信息直接粘贴给 DevEco Code，它会：

读取相关文件：自动定位报错文件
分析错误根因：不仅看表面错误，还分析深层原因
给出修复方案：通常提供 1-2 种修复方案
直接修改代码：在确认后自动修改文件（需确认）
验证修复：检查修复是否引入新的问题

7.6 工程辅助与构建管理（Hvigor & ohpm）

ohpm 依赖管理：安装/更新/移除依赖，解决版本冲突
module.json5 配置：权限声明、Ability 注册、路由配置
Hvigor 构建脚本：自定义构建任务、环境配置
HAR/HSP 模块管理：创建共享库、配置模块依赖

7.7 知识问答与文档精准查询

基于 HarmonyOS 官方文档训练的精准问答能力：

复制代码

# 示例问答
问：@State 和 @Prop 有什么区别？
问：如何在 Stage 模型中获取 UIAbilityContext？
问：LazyForEach 的 IDataSource 接口需要实现哪些方法？
问：ohos.net.http 如何设置请求超时？

7.8 多文件协同编辑与 Diff 预览

DevEco Code 的 Agent 模式可以同时修改多个文件。例如，当你要求"创建一个新的页面并注册路由"时，它会：

创建页面文件 src/main/ets/pages/NewPage.ets
修改路由配置 src/main/resources/base/profile/main_pages.json
如有需要，更新 module.json5

所有修改都以 Git Diff 风格展示，绿色为新增，红色为删除，一目了然。

八、斜杠命令与快捷键大全

8.1 高频必备命令

命令	功能	使用频率
`/help`	显示帮助信息和可用命令列表	⭐⭐⭐⭐⭐
`/model`	切换 AI 模型（弹出选择列表）	⭐⭐⭐⭐⭐
`/clear`	清空对话历史，释放上下文空间	⭐⭐⭐⭐⭐
`/compact`	压缩对话上下文，减少 Token 消耗	⭐⭐⭐⭐
`/exit`	退出 DevEco Code	⭐⭐⭐⭐
`/cost`	查看当前会话的 Token 使用统计	⭐⭐⭐

8.2 会话与上下文管理命令

命令	功能	详细说明
`/clear`	清空对话	释放上下文空间，开始全新任务
`/compact [指令]`	压缩上下文	可附加压缩指令，如 `/compact 保留代码结构`
`/status`	查看状态	显示当前模型、项目路径、Token 用量、版本
`/diff`	查看变更	Git diff 风格显示 AI 对文件的所有修改
`/undo`	撤销修改	可多次执行，逐步回退 AI 的每次修改
`/add-dir <路径>`	添加目录	让 AI 能够访问项目外的额外目录

8.3 模型与配置命令

命令	功能
`/model`	切换模型（弹出交互式选择列表）
`/config`	查看或修改运行时配置
`/cost`	Token 使用统计与预估费用

8.4 项目级命令

命令	功能
`switch_cwd`	切换项目工作目录（不退出 DevEco Code）
`/init`	分析项目结构，生成项目记忆文件 `.deveco-rules.md`

8.5 调试与诊断命令

命令	功能
`/doctor`	检查安装健康状态（类似 brew doctor）
`/bug`	向 DevEco Code 开发团队报告 Bug

8.6 快捷键一览（双平台对比）

功能	Windows	MacOS
发送消息	`Enter`	`Enter`
换行	`Shift+Enter`	`Shift+Enter`
中断操作	`Ctrl+C`	`Ctrl+C`
退出	`Ctrl+D`	`Ctrl+D`
浏览历史	`↑` / `↓`	`↑` / `↓`
自动补全	`Tab`	`Tab`
取消	`Esc`	`Esc`
跳到行首	`Ctrl+A`	`Ctrl+A`
跳到行尾	`Ctrl+E`	`Ctrl+E`
删除光标前	`Ctrl+U`	`Ctrl+U`
删除光标后	`Ctrl+K`	`Ctrl+K`

8.7 MacOS 专属快捷键

快捷键	功能	适用终端
`Cmd+C`	复制选中内容	iTerm2
`Cmd+V`	粘贴	所有终端
`Cmd+K`	清屏	iTerm2 / Terminal
`Cmd+T`	新标签页	iTerm2 / Terminal
`Cmd+W`	关闭标签页	iTerm2 / Terminal
`Cmd+D`	水平分屏	iTerm2
`Cmd+Shift+D`	垂直分屏	iTerm2
`Option+←/→`	按词移动光标	iTerm2（需配置）

8.8 Windows 专属快捷键

快捷键	功能	适用终端
`Ctrl+Shift+C`	复制选中内容	Windows Terminal
`Ctrl+Shift+V`	粘贴	Windows Terminal
`Ctrl+T`	新标签页	Windows Terminal
`Ctrl+W`	关闭标签页	Windows Terminal
`Ctrl+Tab`	切换标签页	Windows Terminal
`Ctrl+Shift+P`	命令面板	Windows Terminal

九、实战案例：使用 DevEco Code 开发鸿蒙应用

9.1 实战一：从零创建 HarmonyOS 项目并初始化

步骤 1 ：在 DevEco Studio 中创建 Empty Ability 项目，项目名称 TodoApp

步骤 2：打开终端并启动 DevEco Code

bash 复制代码

# MacOS
cd ~/HarmonyOSProjects/TodoApp
deveco

# Windows
cd D:\HarmonyOSProjects\TodoApp
deveco

步骤 3：初始化项目记忆

复制代码

/init

DevEco Code 会自动分析项目结构，生成 .deveco-rules.md 记忆文件。

步骤 4：让 AI 生成待办事项应用

复制代码

请帮我修改 Index 页面，创建一个待办事项应用：
1. 顶部标题栏显示"我的待办"，右侧显示完成统计
2. 输入框 + 添加按钮，支持回车快速添加
3. 待办列表（支持勾选完成、左滑删除、长按编辑）
4. 底部显示完成进度条
5. 使用 @ohos.data.preferences 持久化存储

DevEco Code 会自动生成完整代码并写入文件，确认后切换到 DevEco Studio 预览。

9.2 实战二：AI 生成电商首页 UI（完整 ArkTS 代码与注释）

开发者输入：

复制代码

帮我生成一个电商应用首页，包含：搜索栏、轮播广告、分类导航、商品瀑布流

生成的完整代码：

typescript 复制代码

// =============================================
// 文件名：src/main/ets/pages/EcommerceHome.ets
// 功能描述：电商应用首页，包含搜索栏、轮播广告、分类导航、商品瀑布流
// =============================================

import { router } from '@kit.ArkUI';

// =============================================
// 数据模型定义
// =============================================

/** 商品数据模型 */
interface Product {
  id: string;           // 商品唯一标识
  title: string;        // 商品标题
  price: number;        // 商品价格
  originalPrice?: number; // 原价（用于显示划线价）
  imageUrl: string;     // 商品主图 URL
  salesCount: number;   // 销量
  category: string;     // 所属分类
}

/** 分类数据模型 */
interface Category {
  id: string;           // 分类唯一标识
  name: string;         // 分类名称
  icon: Resource;       // 分类图标资源
}

/** 轮播广告数据模型 */
interface BannerItem {
  id: string;           // 广告唯一标识
  imageUrl: string;     // 广告图片 URL
  linkUrl: string;      // 点击跳转链接
}

// =============================================
// 页面入口组件
// =============================================

@Entry
@Component
struct EcommerceHome {
  // =============================================
  // 状态变量声明
  // =============================================
  
  // 搜索框输入内容
  @State searchQuery: string = '';
  
  // 轮播广告当前索引
  @State currentBannerIndex: number = 0;
  
  // 分类列表数据
  @State categories: Category[] = [
    { id: '1', name: '新品首发', icon: $r('app.media.icon_new') },
    { id: '2', name: '限时秒杀', icon: $r('app.media.icon_flash') },
    { id: '3', name: '品质精选', icon: $r('app.media.icon_quality') },
    { id: '4', name: '数码家电', icon: $r('app.media.icon_digital') },
    { id: '5', name: '服饰鞋包', icon: $r('app.media.icon_clothing') },
    { id: '6', name: '美妆护肤', icon: $r('app.media.icon_beauty') },
    { id: '7', name: '食品生鲜', icon: $r('app.media.icon_food') },
    { id: '8', name: '更多分类', icon: $r('app.media.icon_more') }
  ];
  
  // 商品列表数据
  @State productList: Product[] = [];
  
  // 是否正在加载更多
  @State isLoadingMore: boolean = false;
  
  // 当前页码
  @State currentPage: number = 1;
  
  // 轮播广告数据
  @State banners: BannerItem[] = [
    { id: '1', imageUrl: 'https://example.com/banner1.jpg', linkUrl: '/promo/1' },
    { id: '2', imageUrl: 'https://example.com/banner2.jpg', linkUrl: '/promo/2' },
    { id: '3', imageUrl: 'https://example.com/banner3.jpg', linkUrl: '/promo/3' }
  ];

  // =============================================
  // 生命周期方法
  // =============================================
  
  aboutToAppear(): void {
    // 页面即将显示时加载初始数据
    this.loadProducts();
  }

  // =============================================
  // 私有方法
  // =============================================
  
  /**
   * 加载商品列表
   * @param refresh 是否刷新（重置页码）
   */
  private async loadProducts(refresh: boolean = false): Promise<void> {
    if (refresh) {
      this.currentPage = 1;
      this.productList = [];
    }
    
    this.isLoadingMore = true;
    
    try {
      // 模拟网络请求
      const newProducts = await this.fetchProducts(this.currentPage);
      this.productList = [...this.productList, ...newProducts];
      this.currentPage++;
    } catch (error) {
      console.error('加载商品失败:', error);
    } finally {
      this.isLoadingMore = false;
    }
  }
  
  /**
   * 模拟获取商品数据
   */
  private async fetchProducts(page: number): Promise<Product[]> {
    // 实际项目中应该调用真实 API
    return new Promise((resolve) => {
      setTimeout(() => {
        const products: Product[] = [];
        for (let i = 0; i < 10; i++) {
          products.push({
            id: `${page}_${i}`,
            title: `鸿蒙开发精选商品 ${page}-${i}`,
            price: Math.floor(Math.random() * 500) + 50,
            originalPrice: Math.floor(Math.random() * 800) + 100,
            imageUrl: `https://example.com/product_${page}_${i}.jpg`,
            salesCount: Math.floor(Math.random() * 10000),
            category: '数码'
          });
        }
        resolve(products);
      }, 1000);
    });
  }
  
  /**
   * 处理搜索按钮点击
   */
  private handleSearch(): void {
    if (this.searchQuery.trim()) {
      router.pushUrl({
        url: 'pages/SearchResult',
        params: { keyword: this.searchQuery }
      });
    }
  }
  
  /**
   * 处理分类点击
   */
  private handleCategoryClick(category: Category): void {
    router.pushUrl({
      url: 'pages/CategoryList',
      params: { categoryId: category.id, categoryName: category.name }
    });
  }
  
  /**
   * 处理商品点击
   */
  private handleProductClick(product: Product): void {
    router.pushUrl({
      url: 'pages/ProductDetail',
      params: { productId: product.id }
    });
  }

  // =============================================
  // UI 构建方法
  // =============================================
  
  build() {
    Column() {
      // 1. 顶部搜索栏
      this.SearchBar()
      
      // 2. 可滚动内容区域
      Scroll() {
        Column() {
          // 2.1 轮播广告
          this.BannerSection()
          
          // 2.2 分类导航
          this.CategorySection()
          
          // 2.3 商品瀑布流
          this.ProductSection()
        }
      }
      .layoutWeight(1)
      .scrollBar(BarState.Off)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  // =============================================
  // @Builder 组件构建方法
  // =============================================
  
  /**
   * 搜索栏组件
   */
  @Builder
  SearchBar() {
    Row() {
      // 搜索输入框
      Row() {
        Image($r('app.media.icon_search'))
          .width(20)
          .height(20)
          .margin({ left: 12 })
        
        TextInput({ placeholder: '搜索商品', text: this.searchQuery })
          .layoutWeight(1)
          .backgroundColor(Color.Transparent)
          .fontSize(14)
          .margin({ left: 8 })
          .onChange((value: string) => {
            this.searchQuery = value;
          })
          .onSubmit(() => {
            this.handleSearch();
          })
      }
      .layoutWeight(1)
      .height(36)
      .backgroundColor('#FFFFFF')
      .borderRadius(18)
      
      // 搜索按钮
      Button('搜索')
        .type(ButtonType.Normal)
        .backgroundColor('#FF6B00')
        .fontColor(Color.White)
        .fontSize(14)
        .height(36)
        .margin({ left: 12 })
        .onClick(() => {
          this.handleSearch();
        })
    }
    .width('100%')
    .padding({ left: 16, right: 16, top: 12, bottom: 12 })
    .backgroundColor(Color.White)
  }
  
  /**
   * 轮播广告组件
   */
  @Builder
  BannerSection() {
    Swiper() {
      ForEach(this.banners, (banner: BannerItem) => {
        Image(banner.imageUrl)
          .width('100%')
          .height(180)
          .objectFit(ImageFit.Cover)
          .borderRadius(12)
          .onClick(() => {
            router.pushUrl({ url: banner.linkUrl });
          })
      })
    }
    .index(this.currentBannerIndex)
    .indicator(true)
    .autoPlay(true)
    .interval(4000)
    .loop(true)
    .onChange((index: number) => {
      this.currentBannerIndex = index;
    })
    .margin({ top: 12, left: 16, right: 16 })
  }
  
  /**
   * 分类导航组件
   */
  @Builder
  CategorySection() {
    Grid() {
      ForEach(this.categories, (category: Category) => {
        GridItem() {
          Column() {
            Image(category.icon)
              .width(48)
              .height(48)
            
            Text(category.name)
              .fontSize(12)
              .fontColor('#333333')
              .margin({ top: 8 })
          }
          .width('100%')
          .justifyContent(FlexAlign.Center)
          .padding({ top: 16, bottom: 16 })
          .onClick(() => {
            this.handleCategoryClick(category);
          })
        }
      })
    }
    .columnsTemplate('1fr 1fr 1fr 1fr')
    .rowsGap(0)
    .columnsGap(0)
    .backgroundColor(Color.White)
    .borderRadius(12)
    .margin({ top: 12, left: 16, right: 16 })
  }
  
  /**
   * 商品瀑布流组件
   */
  @Builder
  ProductSection() {
    Column() {
      // 区块标题
      Row() {
        Text('为你推荐')
          .fontSize(18)
          .fontWeight(FontWeight.Bold)
          .fontColor('#333333')
        
        Blank()
        
        Text('查看更多')
          .fontSize(12)
          .fontColor('#999999')
      }
      .width('100%')
      .padding({ left: 16, right: 16, top: 20, bottom: 12 })
      
      // 瀑布流商品列表
      WaterFlow() {
        ForEach(this.productList, (product: Product) => {
          FlowItem() {
            this.ProductCard({ product: product })
          }
        })
      }
      .columnsTemplate('1fr 1fr')
      .rowsGap(12)
      .columnsGap(12)
      .padding({ left: 16, right: 16 })
      .onReachEnd(() => {
        // 滚动到底部时加载更多
        if (!this.isLoadingMore) {
          this.loadProducts();
        }
      })
      
      // 加载状态指示器
      if (this.isLoadingMore) {
        Row() {
          LoadingProgress()
            .width(24)
            .height(24)
          
          Text('加载中...')
            .fontSize(12)
            .fontColor('#999999')
            .margin({ left: 8 })
        }
        .width('100%')
        .justifyContent(FlexAlign.Center)
        .padding({ top: 16, bottom: 16 })
      }
    }
  }
  
  /**
   * 商品卡片组件
   */
  @Builder
  ProductCard({ product }: { product: Product }) {
    Column() {
      // 商品图片
      Image(product.imageUrl)
        .width('100%')
        .aspectRatio(1)
        .objectFit(ImageFit.Cover)
        .borderRadius({ topLeft: 8, topRight: 8 })
      
      // 商品信息区域
      Column() {
        // 商品标题（最多两行）
        Text(product.title)
          .fontSize(14)
          .fontColor('#333333')
          .maxLines(2)
          .textOverflow({ overflow: TextOverflow.Ellipsis })
          .width('100%')
        
        // 价格区域
        Row() {
          Text(`¥${product.price}`)
            .fontSize(18)
            .fontWeight(FontWeight.Bold)
            .fontColor('#FF4D4F')
          
          if (product.originalPrice) {
            Text(`¥${product.originalPrice}`)
              .fontSize(12)
              .fontColor('#999999')
              .decoration({ type: TextDecorationType.LineThrough })
              .margin({ left: 8 })
          }
        }
        .margin({ top: 8 })
        
        // 销量信息
        Text(`已售 ${this.formatSalesCount(product.salesCount)}`)
          .fontSize(11)
          .fontColor('#999999')
          .margin({ top: 4 })
      }
      .padding(12)
      .width('100%')
    }
    .backgroundColor(Color.White)
    .borderRadius(8)
    .onClick(() => {
      this.handleProductClick(product);
    })
  }
  
  /**
   * 格式化销量显示
   */
  private formatSalesCount(count: number): string {
    if (count >= 10000) {
      return `${(count / 10000).toFixed(1)}万`;
    }
    return count.toString();
  }
}

9.3 实战三：网络请求与数据绑定（MVVM 架构实现）

复制代码

帮我用 MVVM 架构实现一个新闻列表页面，包含：
1. HTTP 网络请求封装
2. 下拉刷新（Refresh 组件）
3. 上拉加载更多（List onReachEnd）
4. 页面状态管理（Loading/Error/Empty/Success）

9.4 实战四：万能卡片开发（FormExtensionAbility）

复制代码

帮我创建一个 2×2 的天气万能卡片，包含：
1. FormExtensionAbility 逻辑层
2. 卡片 UI 页面
3. form_config.json 配置文件
4. 卡片与宿主应用的数据通信

9.5 实战五：Bug 排查与修复

场景：编译报错

复制代码

请帮我修复以下编译错误：

ERROR: ArkTS:ERROR File: src/main/ets/pages/Profile.ets:35:12
Message: The 'this' context of type 'Profile' is not assignable
to method's 'this' of type 'object'.

ERROR: ArkTS:ERROR File: src/main/ets/pages/Profile.ets:48:5
Message: Property 'fetchUserProfile' does not exist on type 'Profile'.

DevEco Code 的修复过程：

读取 Profile.ets 文件
分析第 35 行：this 上下文丢失（通常是回调函数中使用了箭头函数以外的函数定义）
分析第 48 行：方法名拼写错误
给出修复方案：
- 将回调函数改为箭头函数形式
- 修正方法名拼写
自动修改代码（展示 diff，等待确认）

9.6 实战六：代码重构与性能优化（LazyForEach 实战）

场景：列表滚动卡顿

复制代码

我的 ProductList.ets 页面在展示超过 200 条商品时滚动卡顿，
请帮我分析并优化性能。

DevEco Code 的优化方案：

ForEach → LazyForEach：实现 IDataSource 接口，按需渲染可见项
图片优化：添加占位图、使用缓存策略、限制图片解码尺寸
组件复用：使用 @Reusable 装饰器
减少嵌套：扁平化布局结构
状态管理优化：缩小 @State 的影响范围

生成的 LazyForEach 数据源实现：

typescript 复制代码

// =============================================
// 文件名：src/main/ets/model/ProductDataSource.ets
// 功能描述：LazyForEach 数据源实现，支持按需加载
// =============================================

import { Product } from './Product';

/**
 * LazyForEach 数据源接口实现
 * 用于大数据量列表的性能优化
 */
export class ProductDataSource implements IDataSource {
  // 存储所有商品数据
  private products: Product[] = [];
  
  // 存储所有监听器
  private listeners: DataChangeListener[] = [];

  constructor(products: Product[] = []) {
    this.products = products;
  }

  /**
   * 获取数据总量
   * LazyForEach 会根据此值决定渲染范围
   */
  totalCount(): number {
    return this.products.length;
  }

  /**
   * 获取指定索引的数据项
   * LazyForEach 只会调用可见范围内的索引
   */
  getData(index: number): Product {
    return this.products[index];
  }

  /**
   * 获取数据项的唯一标识
   * 用于组件复用优化
   */
  getKey(index: number): string {
    return this.products[index].id;
  }

  /**
   * 注册数据变化监听器
   */
  registerDataChangeListener(listener: DataChangeListener): void {
    if (this.listeners.indexOf(listener) < 0) {
      this.listeners.push(listener);
    }
  }

  /**
   * 注销数据变化监听器
   */
  unregisterDataChangeListener(listener: DataChangeListener): void {
    const index = this.listeners.indexOf(listener);
    if (index >= 0) {
      this.listeners.splice(index, 1);
    }
  }

  /**
   * 添加新数据（用于加载更多）
   */
  addData(newProducts: Product[]): void {
    const startIndex = this.products.length;
    this.products.push(...newProducts);
    
    // 通知所有监听器数据已添加
    this.listeners.forEach(listener => {
      listener.onDataAdd(startIndex, newProducts.length);
    });
  }

  /**
   * 刷新所有数据（用于下拉刷新）
   */
  refreshData(newProducts: Product[]): void {
    this.products = newProducts;
    
    // 通知所有监听器数据已刷新
    this.listeners.forEach(listener => {
      listener.onDataReloaded();
    });
  }

  /**
   * 删除指定索引的数据
   */
  removeData(index: number): void {
    this.products.splice(index, 1);
    
    // 通知所有监听器数据已删除
    this.listeners.forEach(listener => {
      listener.onDataDelete(index);
    });
  }
}

9.7 实战七：MVVM 架构完整实现

复制代码

请帮我用 MVVM 架构实现一个"我的收藏"功能模块：
1. Model 层：收藏数据模型 + 本地存储
2. ViewModel 层：业务逻辑 + 状态管理
3. View 层：收藏列表页面 UI

DevEco Code 会生成三个文件，完美分层：

model/FavoriteModel.ets --- 数据模型与持久化
viewmodel/FavoriteViewModel.ets --- 业务逻辑
pages/FavoritePage.ets --- UI 视图

十、与 DevEco Studio 协同工作

10.1 DevEco Studio 双平台安装与配置

下载地址：https://developer.huawei.com/consumer/cn/deveco-studio/

平台选择：

Windows ：下载 .exe 安装包
MacOS Intel ：下载 .dmg (Intel) 版本
MacOS Apple Silicon ：下载 .dmg (Arm) 版本

MacOS 解决"无法验证开发者"问题：

bash 复制代码

# 如果 MacOS Gatekeeper 阻止打开
xattr -cr /Applications/DevEco-Studio.app

# 或通过系统设置
# 系统设置 → 隐私与安全性 → 仍要打开

10.2 双工具协同开发工作流

复制代码

┌───────────────────────────┐         ┌───────────────────────────┐
│      DevEco Code          │         │     DevEco Studio         │
│    (终端 AI Agent)         │         │     (图形化 IDE)           │
├───────────────────────────┤         ├───────────────────────────┤
│ • 需求分析与架构设计        │────────▶│ • 代码审查与微调            │
│ • AI 代码生成              │         │ • Previewer 实时预览       │
│ • 批量文件修改             │         │ • 模拟器/真机调试           │
│ • Bug 诊断与修复           │         │ • 性能 Profiler 分析       │
│ • 代码重构优化             │         │ • 签名与打包发布            │
│ • 知识问答学习             │         │ • 布局可视化编辑            │
│ • 构建脚本管理             │◀────────│ • 日志查看与分析            │
└───────────────────────────┘         └───────────────────────────┘

推荐工作流程：

需求阶段：在 DevEco Code 中描述需求，AI 生成初始代码
审查阶段：在 DevEco Studio 中审查代码，使用 Previewer 预览
调试阶段：在 DevEco Studio 中连接模拟器/真机调试
修复阶段：将 Bug 信息反馈给 DevEco Code，AI 辅助修复
发布阶段：在 DevEco Studio 中签名打包

10.3 项目路径切换与上下文同步

在 DevEco Code 会话中切换项目，不需要退出重启：

复制代码

switch_cwd ~/HarmonyOSProjects/AnotherApp

10.4 编译、签名与真机调试配合（hdc 工具链）

hdc（HarmonyOS Device Connector）是鸿蒙设备连接工具：

bash 复制代码

# 双平台通用命令

# 查看已连接设备
hdc list targets

# 安装应用到设备
hdc install -r entry/build/default/outputs/default/entry-default-signed.hap

# 启动应用
hdc shell aa start -a EntryAbility -b com.example.myapp

# 查看实时日志
hdc shell hilog | grep "MyApp"

# 截图并拉取到本地
hdc shell snapshot_display -f /data/local/tmp/screenshot.png
hdc file recv /data/local/tmp/screenshot.png ~/Desktop/

# 查看设备信息
hdc shell param get const.product.model

10.5 Git 版本控制协同

bash 复制代码

# 在 DevEco Code 中可以让 AI 帮你管理 Git
# 示例提示：

请帮我查看当前 Git 状态，并将所有修改提交到 develop 分支，
提交信息要规范，遵循 Conventional Commits 格式。

十一、高级配置与自定义

11.1 配置文件目录结构（双平台路径详解）

MacOS 路径

复制代码

~/.deveco/                                # DevEco Code 根配置目录
├── data.db                               # 本地 SQLite 数据库
├── ai/
│   ├── config.json                       # 模型配置文件
│   ├── prompts/                          # 自定义提示词模板目录
│   │   ├── system_prompt.md              # 系统级提示词
│   │   ├── code_style.md                 # 代码风格模板
│   │   └── component_template.md         # 组件生成模板
│   ├── history/                          # 对话历史存档
│   │   ├── session_20260715.json
│   │   └── session_20260716.json
│   └── memory.md                         # 全局 AI 记忆文件
├── auth/
│   └── credentials.json                  # 加密的登录凭证
├── cache/
│   ├── models/                           # 模型元数据缓存
│   └── projects/                         # 项目索引缓存
└── logs/
    └── deveco-code.log                   # 运行日志

Windows 路径

复制代码

%USERPROFILE%\.deveco\                    # DevEco Code 根配置目录
│                                         # (通常为 C:\Users\<User>\.deveco$
├── data.db                               # 本地 SQLite 数据库
├── ai\
│   ├── config.json                       # 模型配置文件
│   ├── prompts\                          # 自定义提示词模板目录
│   ├── history\                          # 对话历史存档
│   └── memory.md                         # 全局 AI 记忆文件
├── auth\
│   └── credentials.json                  # 加密的登录凭证
├── cache\
│   ├── models\                           # 模型元数据缓存
│   └── projects\                         # 项目索引缓存
└── logs\
    └── deveco-code.log                   # 运行日志

11.2 自定义 Agent 行为与记忆文件

全局记忆文件 ~/.deveco/ai/memory.md（MacOS）或 %USERPROFILE%\.deveco\ai\memory.md（Windows）：

markdown 复制代码

# 全局开发偏好

## 代码风格
- 使用 2 空格缩进（ArkTS 标准）
- 组件名 PascalCase，变量名 camelCase
- 所有公开 API 必须添加 JSDoc 注释
- import 语句按模块类型分组排列
- 常量使用 UPPER_SNAKE_CASE 命名

## 架构偏好
- 使用 Stage 模型（非 FA 模型）
- 页面文件放 pages/ 目录
- 公共组件放 components/ 目录
- 工具类放 utils/ 目录
- 数据模型放 model/ 目录
- ViewModel 放 viewmodel/ 目录

## 技术要求
- 列表超过 50 项使用 LazyForEach
- 网络请求统一封装在 HttpClient 中
- 使用 AppStorage 管理全局状态
- 所有异步操作使用 async/await（不使用 .then 链）
- 错误处理必须使用 try-catch
- 资源引用使用 $r() 而非硬编码路径

项目级记忆文件 项目根目录/.deveco-rules.md：

markdown 复制代码

# 项目：电商应用 EShop

## 技术栈
- ArkTS + Stage 模型
- @ohos/axios 网络请求
- @ohos/data_relational_store 本地存储

## 模块结构
- entry: 主模块
- common: 公共组件库 (HAR)
- network: 网络层 (HAR)
- storage: 数据存储层 (HAR)

## 编码规范
- API 地址统一在 config/ApiConfig.ets 中管理
- 页面路由统一在 router/RouterMap.ets 中注册
- 主题色：#FF6B00（品牌橙色）
- 所有列表页必须支持下拉刷新和上拉加载

11.3 MCP（Model Context Protocol）扩展配置

MCP 允许你接入外部工具服务器，大幅扩展 AI Agent 的能力边界。

示例：接入多种 MCP 服务

json 复制代码

{
  "mcp": {
    "servers": [
      {
        "name": "sqlite-query",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-sqlite", "/path/to/database.db"],
        "enabled": true,
        "description": "SQLite 数据库查询工具"
      },
      {
        "name": "filesystem",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-filesystem", "/path/to/project"],
        "enabled": true,
        "description": "文件系统操作工具"
      },
      {
        "name": "git-tools",
        "command": "npx",
        "args": ["-y", "@anthropic/mcp-git", "/path/to/repo"],
        "enabled": true,
        "description": "Git 版本控制工具"
      }
    ]
  }
}

11.4 自定义提示词模板

在 ~/.deveco/ai/prompts/ 目录下创建模板文件，让 AI 生成的代码更符合你的风格：

markdown 复制代码

<!-- ~/.deveco/ai/prompts/component_template.md -->

# HarmonyOS 组件开发规范

当你生成 ArkTS 组件时，请严格遵循以下规范：

## 文件结构
1. 每个文件只包含一个 @Entry 或 @Component 结构
2. 文件顶部添加文件描述注释块
3. import 语句按以下顺序分组：系统模块 → 三方库 → 项目模块

## 组件结构
1. 状态变量声明在组件顶部，按用途分组并添加注释
2. 生命周期方法（aboutToAppear 等）放在 build() 之前
3. 私有事件处理方法以 handle/on 开头命名
4. @Builder 方法放在 build() 之后
5. 每个 @Builder 方法都是一个独立的视觉模块

## 样式规范
1. 使用 vp 作为长度单位
2. 颜色值使用十六进制字符串
3. 间距使用 4 的倍数（4, 8, 12, 16, 20, 24...）
4. 圆角统一使用 8, 12, 16 三档

11.5 环境变量与 Shell 集成（双平台配置）

MacOS ~/.zshrc 配置

bash 复制代码

# =============================================
# ~/.zshrc - MacOS 鸿蒙开发者 Shell 配置
# =============================================

# --- Homebrew ---
eval "$(/opt/homebrew/bin/brew shellenv)"

# Homebrew 国内镜像加速
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"

# --- fnm (Fast Node Manager) ---
eval "$(fnm env --use-on-cd --shell zsh)"

# --- 环境变量 ---
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
export EDITOR=vim

# --- DevEco Code 别名 ---
alias dc='deveco'
alias dcu='deveco upgrade'
alias dcs='deveco status'
alias dcl='deveco logout'

# --- 项目快速切换 ---
export HARMONY_HOME=~/HarmonyOSProjects
alias hcd1='cd $HARMONY_HOME/EShopApp && deveco'
alias hcd2='cd $HARMONY_HOME/SocialApp && deveco'

Windows PowerShell Profile 配置

powershell 复制代码

# =============================================
# Microsoft.PowerShell_profile.ps1 - Windows 鸿蒙开发者配置
# =============================================

# --- fnm (Fast Node Manager) ---
fnm env --use-on-cd | Out-String | Invoke-Expression

# --- DevEco Code 别名 ---
function dc { deveco }
function dcu { deveco upgrade }
function dcs { deveco status }
function dcl { deveco logout }

# --- 项目快速切换 ---
$env:HARMONY_HOME = "D:\HarmonyOSProjects"

function hcd($projectName) {
    $projectPath = Join-Path $env:HARMONY_HOME $projectName
    if (Test-Path $projectPath) {
        Set-Location $projectPath
        deveco
    } else {
        Write-Host "项目不存在: $projectPath" -ForegroundColor Red
        Write-Host "可用项目："
        Get-ChildItem $env:HARMONY_HOME -Directory | ForEach-Object { $_.Name }
    }
}

11.6 iTerm2 深度集成（MacOS）

为 DevEco Code 创建 iTerm2 专属 Profile：

打开 iTerm2 → Preferences（Cmd+,）→ Profiles
点击 "+" 创建新 Profile，命名为 "DevEco Code"
General 标签页 ：
- Command: Login Shell
- Send text at start: deveco（自动启动）
Colors 标签页 ：
- 选择配色方案（推荐 Solarized Dark、Dracula 或 One Dark）
Text 标签页 ：
- Font: JetBrains Mono 或 Fira Code（14pt）
Window 标签页 ：
- Columns: 120
- Rows: 40

配置热键窗口（Hotkey Window）：

iTerm2 → Preferences → Keys → Hotkey Window
勾选 "A hotkey opens a dedicated window"
设置热键为 ⌥D（Option+D）
Profile 选择 "DevEco Code"
勾选 "Float above other windows"

配置完成后，按 Option+D 就能从任何应用中快速呼出 DevEco Code 终端。

11.7 Windows Terminal 深度集成与美化

配置 Windows Terminal settings.json：

json 复制代码

{
    "profiles": {
        "list": [
            {
                "name": "DevEco Code",
                "commandline": "powershell.exe -NoExit -Command \"cd D:\\HarmonyOSProjects\\MyApp; deveco\"",
                "icon": "🚀",
                "colorScheme": "Dracula",
                "font": {
                    "face": "JetBrains Mono",
                    "size": 12
                },
                "startingDirectory": "D:\\HarmonyOSProjects",
                "backgroundImage": null,
                "opacity": 95
            }
        ]
    },
    "schemes": [
        {
            "name": "Dracula",
            "background": "#282A36",
            "foreground": "#F8F8F2",
            "cursorColor": "#F8F8F2",
            "black": "#21222C",
            "red": "#FF5555",
            "green": "#50FA7B",
            "yellow": "#F1FA8C",
            "blue": "#BD93F9",
            "purple": "#FF79C6",
            "cyan": "#8BE9FD",
            "white": "#F8F8F2"
        }
    ]
}

配置 Quake 模式（下拉终端）：

在 Windows Terminal 设置中启用 "Quake Mode"，按 `Win+`` 可从屏幕顶部下拉终端。

11.8 自动化脚本

MacOS Bash 脚本

bash 复制代码

#!/bin/bash
# =============================================
# 文件名：start-deveco.sh
# 功能：快速启动 DevEco Code 的 Bash 脚本
# =============================================

# 项目根目录
HARMONY_HOME=~/HarmonyOSProjects

# 显示项目列表
echo "可用项目："
ls -1 "$HARMONY_HOME"

# 读取用户选择
read -p "请输入项目名称: " project_name

# 检查项目是否存在
if [ -d "$HARMONY_HOME/$project_name" ]; then
    cd "$HARMONY_HOME/$project_name" && deveco
else
    echo "项目不存在: $HARMONY_HOME/$project_name"
fi

Windows PowerShell 脚本

powershell 复制代码

# =============================================
# 文件名：start-deveco.ps1
# 功能：快速启动 DevEco Code 的 PowerShell 脚本
# =============================================

# 项目根目录
$HARMONY_HOME = "D:\HarmonyOSProjects"

# 显示项目列表
Write-Host "可用项目：" -ForegroundColor Cyan
Get-ChildItem $HARMONY_HOME -Directory | ForEach-Object { 
    Write-Host "  - $($_.Name)" 
}

# 读取用户选择
$projectName = Read-Host "请输入项目名称"

# 检查项目是否存在
$projectPath = Join-Path $HARMONY_HOME $projectName
if (Test-Path $projectPath) {
    Set-Location $projectPath
    deveco
} else {
    Write-Host "项目不存在: $projectPath" -ForegroundColor Red
}

十二、更新与升级

12.1 deveco upgrade 命令

bash 复制代码

# 双平台通用命令

# 在终端中直接升级（推荐）
deveco upgrade

# 或在交互会话中使用斜杠命令
/upgrade

12.2 npm 重新安装升级

bash 复制代码

# 升级到最新版
npm install -g @deveco/deveco-code@latest

# 查看当前安装版本和最新版本
npm view @deveco/deveco-code version
deveco --version

12.3 版本回退策略

bash 复制代码

# 查看所有可用版本
npm view @deveco/deveco-code versions --json

# 安装指定版本
npm install -g @deveco/deveco-code@1.0.0

# 安装上一个稳定版本
npm install -g @deveco/deveco-code@1.0.0

12.4 升级注意事项与数据备份

✅ 配置文件（~/.deveco/ai/config.json）不会被覆盖
✅ 对话历史会保留在本地数据库中
✅ 登录状态通常不受影响
⚠️ 重大版本升级（如 1.x → 2.x）可能需要重新配置
⚠️ 升级前建议备份 ~/.deveco/ 目录

备份脚本：

bash 复制代码

# MacOS
cp -r ~/.deveco ~/.deveco.backup.$(date +%Y%m%d)

# Windows PowerShell
Copy-Item "$env:USERPROFILE\.deveco" "$env:USERPROFILE\.deveco.backup.$(Get-Date -Format 'yyyyMMdd')" -Recurse

12.5 自动更新检测脚本

MacOS Bash 脚本

bash 复制代码

#!/bin/bash
# =============================================
# 文件名：check-deveco-update.sh
# 功能：检测 DevEco Code 是否有新版本
# =============================================

CURRENT=$(deveco --version 2>/dev/null)
LATEST=$(npm view @deveco/deveco-code version 2>/dev/null)

if [ -z "$CURRENT" ]; then
  echo "❌ DevEco Code 未安装"
  exit 1
fi

if [ "$CURRENT" != "$LATEST" ]; then
  echo "📦 有新版本可用！"
  echo "   当前版本: $CURRENT"
  echo "   最新版本: $LATEST"
  echo "   运行 'deveco upgrade' 升级"
else
  echo "✅ 已是最新版本: $CURRENT"
fi

Windows PowerShell 脚本

powershell 复制代码

# =============================================
# 文件名：check-deveco-update.ps1
# 功能：检测 DevEco Code 是否有新版本
# =============================================

$CURRENT = deveco --version 2>$null
$LATEST = npm view @deveco/deveco-code version 2>$null

if (-not $CURRENT) {
    Write-Host "❌ DevEco Code 未安装" -ForegroundColor Red
    exit 1
}

if ($CURRENT -ne $LATEST) {
    Write-Host "📦 有新版本可用！" -ForegroundColor Green
    Write-Host "   当前版本: $CURRENT"
    Write-Host "   最新版本: $LATEST"
    Write-Host "   运行 'deveco upgrade' 升级"
} else {
    Write-Host "✅ 已是最新版本: $CURRENT" -ForegroundColor Green
}

十三、完整卸载流程

13.1 卸载运行时数据与本地数据库

bash 复制代码

# 双平台通用命令
deveco uninstall

13.2 npm 全局卸载

bash 复制代码

# 卸载主包
npm uninstall -g @deveco/deveco-code

# 如果安装了社区版本
npm uninstall -g @openharmony-sig/deveco-code

13.3 清理残留配置与缓存

MacOS

bash 复制代码

# 删除 DevEco Code 配置目录
rm -rf ~/.deveco

# 清理 npm 缓存中与 deveco 相关的内容
npm cache clean --force

# 检查是否还有残留文件
ls -la ~/ | grep deveco
find ~ -name "*deveco*" -maxdepth 3 2>/dev/null

# 清理项目级的记忆文件（可选）
# find ~/HarmonyOSProjects -name ".deveco-rules.md" -delete

Windows PowerShell

powershell 复制代码

# 删除 DevEco Code 配置目录
Remove-Item -Recurse -Force "$env:USERPROFILE\.deveco"

# 清理 npm 缓存
npm cache clean --force

# 检查是否还有残留文件
Get-ChildItem $env:USERPROFILE -Filter "*deveco*" -Recurse -ErrorAction SilentlyContinue

13.4 卸载 Node.js（可选）

使用 fnm 卸载

bash 复制代码

# 双平台通用
fnm uninstall 20.18.1

# 卸载 fnm 本身
# MacOS
brew uninstall fnm

# Windows
winget uninstall Schniz.fnm

使用 nvm 卸载

bash 复制代码

# MacOS
nvm uninstall 20.18.1
rm -rf ~/.nvm

# Windows
nvm uninstall 20.18.1
# 通过控制面板卸载 nvm-windows

使用 Homebrew 卸载（MacOS）

bash 复制代码

brew uninstall node@20
brew cleanup

官方安装包卸载（Windows）

通过"控制面板" → "程序和功能" → 选择 "Node.js" → 卸载

13.5 卸载 Homebrew（MacOS 可选）

bash 复制代码

# 官方卸载脚本
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

# Apple Silicon 额外清理
sudo rm -rf /opt/homebrew

13.6 卸载验证与一键清理脚本

验证卸载完成

bash 复制代码

# 双平台通用验证

# 验证 DevEco Code 已卸载
deveco --version
# 期望输出：command not found: deveco

# 验证配置已删除
# MacOS
ls ~/.deveco
# Windows PowerShell
Test-Path "$env:USERPROFILE\.deveco"
# 期望输出：No such file or directory / False

MacOS 一键卸载脚本

bash 复制代码

#!/bin/bash
# =============================================
# 文件名：uninstall-deveco.sh
# 功能：DevEco Code 完整卸载脚本（MacOS）
# =============================================

echo "🗑️  开始卸载 DevEco Code..."

# 1. 清理运行时数据
echo "→ 清理运行时数据..."
deveco uninstall 2>/dev/null

# 2. npm 全局卸载
echo "→ 卸载 npm 全局包..."
npm uninstall -g @deveco/deveco-code 2>/dev/null
npm uninstall -g @openharmony-sig/deveco-code 2>/dev/null

# 3. 删除配置目录
echo "→ 删除配置目录..."
rm -rf ~/.deveco

# 4. 清理 npm 缓存
echo "→ 清理 npm 缓存..."
npm cache clean --force 2>/dev/null

# 5. 验证
echo "→ 验证卸载结果..."
if ! command -v deveco &> /dev/null; then
  echo "✅ DevEco Code 已成功卸载！"
else
  echo "❌ 卸载可能不完整，请检查 PATH 配置"
fi

echo ""
echo "⚠️  请手动检查并删除 ~/.zshrc 中的以下内容："
echo "   - alias dc='deveco' 等 DevEco Code 相关别名"
echo "   - export DEVECO_* 等环境变量"

Windows 一键卸载脚本

powershell 复制代码

# =============================================
# 文件名：uninstall-deveco.ps1
# 功能：DevEco Code 完整卸载脚本（Windows）
# =============================================

Write-Host "🗑️  开始卸载 DevEco Code..." -ForegroundColor Cyan

# 1. 清理运行时数据
Write-Host "→ 清理运行时数据..."
deveco uninstall 2>$null

# 2. npm 全局卸载
Write-Host "→ 卸载 npm 全局包..."
npm uninstall -g @deveco/deveco-code 2>$null
npm uninstall -g @openharmony-sig/deveco-code 2>$null

# 3. 删除配置目录
Write-Host "→ 删除配置目录..."
Remove-Item -Recurse -Force "$env:USERPROFILE\.deveco" -ErrorAction SilentlyContinue

# 4. 清理 npm 缓存
Write-Host "→ 清理 npm 缓存..."
npm cache clean --force 2>$null

# 5. 验证
Write-Host "→ 验证卸载结果..."
if (-not (Get-Command deveco -ErrorAction SilentlyContinue)) {
    Write-Host "✅ DevEco Code 已成功卸载！" -ForegroundColor Green
} else {
    Write-Host "❌ 卸载可能不完整，请检查 PATH 配置" -ForegroundColor Red
}

Write-Host ""
Write-Host "⚠️  请手动检查 PowerShell Profile 中的 DevEco Code 相关配置" -ForegroundColor Yellow
Write-Host "   运行: notepad `$PROFILE"

十四、常见问题与解决方案（FAQ）

14.1 安装类问题

Q1：npm install -g 权限被拒绝（EACCES / EPERM）

bash 复制代码

# Windows：以管理员身份运行终端，或参考 3.7 节修改全局路径

# MacOS 方案一：修改目录权限
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

# MacOS 方案二：使用 fnm/nvm 避免权限问题（推荐）

Q2：安装过程中 node-gyp 编译失败

bash 复制代码

# Windows：重新运行 Node.js 安装程序，勾选 "Tools for Native Modules"
npm install -g windows-build-tools

# MacOS：确保 Xcode CLT 已正确安装
xcode-select --install

# 或重新安装 CLT
sudo rm -rf /Library/Developer/CommandLineTools
xcode-select --install

Q3：404 Not Found

bash 复制代码

# 国内镜像可能尚未同步该包，临时切换到官方源安装
npm install -g @deveco/deveco-code --registry https://registry.npmjs.org/

Q4：网络超时（ETIMEDOUT）

bash 复制代码

# 方案 A：使用国内镜像
npm config set registry https://registry.npmmirror.com


### 14.2 登录类问题

**Q5：浏览器没有自动打开**

```bash
# MacOS
open "https://developer.huawei.com/consumer/cn/auth?..."

# Windows PowerShell
Start-Process "https://developer.huawei.com/consumer/cn/auth?..."

# 或手动复制终端中显示的完整 URL 到浏览器

Q6：登录凭证过期

bash 复制代码

deveco logout
deveco login

14.3 模型调用类问题

Q7：GLM-5.1 请求频率超限

A：内置模型限制每分钟 50 次请求。解决方案：

等待 1 分钟后重试
使用 /compact 减少不必要的请求
切换到 DeepSeek 等第三方模型

Q8：DeepSeek API 返回 401 Unauthorized

A：检查 API Key：

确认密钥正确且未过期
确认密钥未被禁用
在 DeepSeek 平台查看余额是否充足

Q9：Ollama 本地模型响应很慢

A：优化建议：

选择参数量更小的模型（如 7B 替代 14B）
确保有足够的内存（模型需要加载到内存）
关闭其他占用内存的应用

14.4 MacOS 特有问题

Q10：Apple Silicon 上 node 运行在 Rosetta 模式

bash 复制代码

# 确保终端应用没有勾选"使用 Rosetta 打开"
# 1. 在 Finder 中找到终端应用
# 2. 右键 → 显示简介
# 3. 取消勾选"使用 Rosetta 打开"
# 4. 重启终端

# 验证 Node.js 架构
node -e "console.log(process.arch)"
# 期望输出：arm64

Q11：MacOS Gatekeeper 阻止执行

bash 复制代码

xattr -cr $(npm config get prefix)/lib/node_modules/@deveco/deveco-code

Q12：终端中文显示乱码

bash 复制代码

# 确保 UTF-8 编码
echo 'export LANG=en_US.UTF-8' >> ~/.zshrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.zshrc
source ~/.zshrc

Q13：MacOS 升级后 git/clang 命令不可用

bash 复制代码

# MacOS 大版本升级可能清除 CLT
xcode-select --install

Q14：Homebrew 在 Apple Silicon 上报 "command not found"

bash 复制代码

# 将 Homebrew 添加到 PATH
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile

14.5 Windows 特有问题

Q15：执行 deveco 提示"不是内部或外部命令"

A：检查 npm 全局 bin 目录是否在系统 PATH 中：

powershell 复制代码

npm config get prefix
# 将输出的路径添加到环境变量 PATH，并重启终端

Q16：提示"无法加载文件...因为在此系统上禁止运行脚本"

powershell 复制代码

# 以管理员身份运行 PowerShell，执行：
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Q17：终端中文显示乱码

powershell 复制代码

# 设置 UTF-8 编码
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 或在 Windows Terminal 中设置字体为支持中文的等宽字体

Q18：环境变量修改后不生效

A：修改系统环境变量后，必须关闭并重新打开终端窗口才能生效。

14.6 性能与稳定性问题

Q19：DevEco Code 长时间使用后变慢

复制代码

# 上下文积累过多导致。解决方案：
/compact    # 压缩上下文
/clear      # 清空历史重新开始

Q20：终端显示不完整或错位

A：调整终端设置：

使用等宽字体（推荐 JetBrains Mono）
确保终端宽度 ≥ 80 列
使用 iTerm2（MacOS）或 Windows Terminal（Windows）

十五、总结与展望

DevEco Code 的发布标志着 HarmonyOS 开发工具链迈入了 Agentic Coding 时代。作为华为面向鸿蒙生态推出的终端 AI Agent 工具，它凭借对 ArkTS 语法体系的深度理解和终端原生的高效交互形态，成为 Windows 和 MacOS 双平台上鸿蒙开发者的"新神器"。

本文从双平台的独特视角出发，完整覆盖了以下核心内容：

章节	核心内容	关键词
环境搭建	Xcode CLT / Node.js / fnm	双平台统一方案
安装部署	npm 全局安装，权限问题排查	EACCES / EPERM 解决
模型配置	GLM-5.1 免费 + 多模型全接入	DeepSeek/Ollama
核心功能	代码/UI/卡片生成，Bug 修复	Agent 模式
命令体系	斜杠命令 + 双平台快捷键	/model /compact
实战案例	七个贴近真实场景的完整案例	详细代码注释
协同工作	DevEco Studio 高效配合	双工具流程
高级配置	iTerm2/Windows Terminal/MCP	深度定制
维护管理	升级与完整卸载	一键脚本

核心建议：

使用 fnm 管理 Node.js：双平台统一，避免权限问题，切换版本方便，启动速度快
选择优质终端：MacOS 用 iTerm2，Windows 用 Windows Terminal，配合热键窗口随时呼出
为每个项目创建 .deveco-rules.md：让 AI 更"懂"你的项目规范和代码风格
善用 /compact 管理上下文：在长对话中保持 AI 的高效响应
关注版本更新 ：华为正在快速迭代新功能，定期执行 deveco upgrade
双工具协同：DevEco Code（代码生成/重构）+ DevEco Studio（预览/调试/打包）

展望未来：

随着 HarmonyOS NEXT 生态的持续壮大，DevEco Code 预计将在以下方向持续演进：

更强的多模态理解：支持从设计稿图片直接生成 UI 代码
更深度的 DevEco Studio 集成：推出 IDE 内嵌模式，无需切换终端
跨设备开发支持：一次对话生成手机、平板、手表、车机多端适配代码
社区插件生态：开放 MCP 插件市场，发布和安装社区扩展工具
协作编程能力：支持多人协同与 AI 辅助的混合开发模式
更强的本地模型支持：支持完全离线的本地 Agent 模式
自动测试生成：自动生成单元测试、UI 自动化测试用例
智能性能优化：集成 Profiler 数据，自动分析并优化性能

对于 Windows 和 MacOS 双平台上的鸿蒙开发者来说，现在是拥抱 AI Agent 编程范式的最佳时机。DevEco Code 不仅是一个工具，更是一种全新的开发思维方式的载体------从"我来写代码"到"我来描述需求，AI 来实现代码"。掌握这种人机协作的开发模式，将在未来的软件工程中占据显著的竞争优势。

"未来属于那些善于与 AI 协作的开发者。"

在 HarmonyOS 生态的黄金发展期，DevEco Code 为双平台开发者提供了一个强大的"AI 编程搭档"。善用这份指南中的每一个技巧，让 AI 成为你开发效率的倍增器。

附录

以下是《DevEco Code 在 Windows/MacOS 双系统上的完整安装、配置与卸载全面使用指南》从 附录 A 开始到结尾的所有剩余内容，接续前文完整呈现。

附录 A：DevEco Code 完整命令参考表

本附录汇总了 DevEco Code 中所有可用的斜杠命令（Slash Commands）和命令行参数，方便开发者随时查阅。

A.1 核心交互命令

命令	语法	功能描述	使用示例
`/help`	`/help [command]`	显示帮助信息，可指定具体命令查看详细用法	`/help model`
`/exit`	`/exit`	安全退出 DevEco Code，自动保存当前会话状态	`/exit`
`/status`	`/status`	显示当前运行状态，包含模型、项目路径、Token 用量、版本号	`/status`
`/cost`	`/cost`	显示当前会话的 Token 消耗统计与预估费用	`/cost`

A.2 会话与上下文管理命令

命令	语法	功能描述	使用示例
`/clear`	`/clear`	清空当前对话历史，释放上下文窗口空间，开始全新任务	`/clear`
`/compact`	`/compact [指令]`	智能压缩对话上下文，减少 Token 消耗。可附加指令指定保留重点	`/compact 保留代码架构设计`
`/diff`	`/diff`	以 Git Diff 风格显示 AI 对项目中文件的所有修改，绿色为新增，红色为删除	`/diff`
`/undo`	`/undo [n]`	撤销 AI 对文件的最近一次或最近 n 次修改，安全回退	`/undo` 或 `/undo 3`
`/replay`	`/replay`	重新执行 AI 的最后一次操作	`/replay`

A.3 模型与配置命令

命令	语法	功能描述	使用示例
`/model`	`/model [provider/model]`	切换 AI 模型，可交互式选择或直接指定供应商和模型 ID	`/model` 或 `/model deepseek/deepseek-coder`
`/config`	`/config [key] [value]`	查看或修改运行时配置项	`/config` 或 `/config theme dark`
`/tokens`	`/tokens`	显示详细的 Token 分解统计（系统/用户/助手/工具）	`/tokens`

A.4 项目管理命令

命令	语法	功能描述	使用示例
`switch_cwd`	`switch_cwd <path>`	在不退出 DevEco Code 的情况下切换当前工作目录	`switch_cwd ~/Projects/NewApp`
`/init`	`/init`	深度分析当前项目结构，自动生成 `.deveco-rules.md` 项目记忆文件	`/init`
`/add-dir`	`/add-dir <path>`	添加额外的目录到 AI 可访问的上下文范围中	`/add-dir ~/SharedLib`
`/ignore`	`/ignore <pattern>`	添加文件/目录到 AI 忽略列表	`/ignore node_modules`

A.5 调试与诊断命令

命令	语法	功能描述	使用示例
`/doctor`	`/doctor`	全面检查安装健康状态，包括环境、权限、网络、配置等	`/doctor`
`/bug`	`/bug [描述]`	向 DevEco Code 开发团队报告 Bug，自动附加环境信息	`/bug 模型切换后 TUI 界面卡住`
`/logs`	`/logs [n]`	查看最近 n 条运行日志（默认 50 条）	`/logs 100`
`/verbose`	`/verbose`	开启/关闭详细日志模式	`/verbose`

A.6 升级与维护命令

命令	语法	功能描述	使用示例
`/upgrade`	`/upgrade`	检查并升级到最新版本的 DevEco Code	`/upgrade`
`/uninstall`	`/uninstall`	清理运行时数据和本地数据库（不卸载 npm 包）	`/uninstall`
`/reset`	`/reset`	重置所有配置到默认状态（保留登录凭证）	`/reset`

A.7 命令行启动参数

以下是 deveco 命令本身支持的启动参数，在终端中直接使用：

参数	语法	功能描述	使用示例
`--version`	`deveco --version`	显示 DevEco Code 版本号	`deveco --version`
`--help`	`deveco --help`	显示命令行帮助	`deveco --help`
`--cwd`	`deveco --cwd <path>`	指定工作目录启动	`deveco --cwd ~/MyApp`
`--model`	`deveco --model <id>`	启动时指定默认模型	`deveco --model deepseek-coder`
`--theme`	`deveco --theme <name>`	指定界面主题（dark/light/auto）	`deveco --theme dark`
`--verbose`	`deveco --verbose`	以详细日志模式启动	`deveco --verbose`
`--read-only`	`deveco --read-only`	只读模式启动（AI 不会修改任何文件）	`deveco --read-only`
`login`	`deveco login`	在终端中执行登录流程	`deveco login`
`logout`	`deveco logout`	退出当前登录	`deveco logout`
`status`	`deveco status`	在终端中查看登录和运行状态	`deveco status`

附录 B：双平台环境变量与配置文件速查表

B.1 关键环境变量

环境变量	说明	设置方式	适用平台	示例值
`PATH`	可执行文件搜索路径	系统设置 / Shell 配置	双平台	包含 npm 全局 bin 目录
`HTTP_PROXY`	HTTP 代理地址	Shell 配置 / 临时设置	双平台	`http://127.0.0.1:7890`
`HTTPS_PROXY`	HTTPS 代理地址	Shell 配置 / 临时设置	双平台	`http://127.0.0.1:7890`
`ALL_PROXY`	全局代理（含 SOCKS5）	Shell 配置 / 临时设置	MacOS	`socks5://127.0.0.1:7890`
`NO_PROXY`	不走代理的地址列表	Shell 配置	双平台	`localhost,127.0.0.1`
`LANG`	系统语言编码	Shell 配置	MacOS	`en_US.UTF-8`
`LC_ALL`	区域设置覆盖	Shell 配置	MacOS	`en_US.UTF-8`
`EDITOR`	默认命令行编辑器	Shell 配置	双平台	`vim` / `code`
`DEVECO_MODEL`	DevEco Code 默认模型	Shell 配置	双平台	`glm-5`
`NODE_OPTIONS`	Node.js 运行参数	Shell 配置	双平台	`--max-old-space-size=4096`

B.2 关键配置文件路径对照表

文件用途	MacOS 路径	Windows 路径
Shell 配置文件	`~/.zshrc`	`$PROFILE`（通常为 `Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1`）
npm 全局配置	`~/.npmrc`	`%USERPROFILE%\.npmrc`
Git 全局配置	`~/.gitconfig`	`%USERPROFILE%\.gitconfig`
Git 全局忽略规则	`~/.gitignore_global`	`%USERPROFILE%\.gitignore_global`
DevEco 模型配置	`~/.deveco/ai/config.json`	`%USERPROFILE%\.deveco\ai\config.json`
DevEco 全局记忆	`~/.deveco/ai/memory.md`	`%USERPROFILE%\.deveco\ai\memory.md`
DevEco 登录凭证	`~/.deveco/auth/credentials.json`	`%USERPROFILE%\.deveco\auth\credentials.json`
DevEco 本地数据库	`~/.deveco/data.db`	`%USERPROFILE%\.deveco\data.db`
DevEco 运行日志	`~/.deveco/logs/deveco-code.log`	`%USERPROFILE%\.deveco\logs\deveco-code.log`
DevEco 提示词模板	`~/.deveco/ai/prompts/*.md`	`%USERPROFILE%\.deveco\ai\prompts\*.md`
项目级记忆文件	`<项目根目录>/.deveco-rules.md`	`<项目根目录>\.deveco-rules.md`

B.3 关键目录路径对照表

目录用途	MacOS 路径	Windows 路径
Homebrew 根目录	`/opt/homebrew/`（Apple Silicon）/ `/usr/local/`（Intel）	---
npm 全局包目录（默认）	`$(npm config get prefix)/lib/node_modules/`	`%APPDATA%\npm\node_modules\`
npm 全局 bin 目录（默认）	`$(npm config get prefix)/bin/`	`%APPDATA%\npm\`
npm 缓存目录	`~/.npm/`	`%APPDATA%\npm-cache\`
DevEco 配置根目录	`~/.deveco/`	`%USERPROFILE%\.deveco\`
Xcode CLT	`/Library/Developer/CommandLineTools/`	---
fnm 数据目录	`~/Library/Application Support/fnm/`	`%APPDATA%\fnm\`
nvm 数据目录	`~/.nvm/`	`%APPDATA%\nvm\`

附录 C：双平台常用终端命令速查

C.1 文件与目录操作

MacOS Terminal

bash 复制代码

# ===== 目录导航 =====
pwd                              # 显示当前目录完整路径
cd <path>                        # 切换目录
cd ~                             # 回到家目录
cd -                             # 回到上一个目录
pushd <path>                     # 切换目录并记录（可用 popd 回退）

# ===== 文件列表 =====
ls -la                           # 详细列表（含隐藏文件）
ls -lAh                          # 人类可读的文件大小
tree -L 2                        # 树形显示目录结构（需 brew install tree）
eza -la                          # 增强版 ls（需 brew install eza）

# ===== 文件搜索 =====
find ~ -name "*.ets" -maxdepth 5                     # 查找 .ets 文件
grep -rn "import" --include="*.ets" .                # 递归搜索文件内容
rg "TODO" --type ts                                  # ripgrep 快速搜索
mdfind -name "deveco"                                # Spotlight 系统级搜索
fd "\.json5$"                                        # fd 快速文件查找

# ===== 文件操作 =====
cp -r <src> <dst>                 # 递归复制目录
mv <src> <dst>                    # 移动或重命名
rm -rf <dir>                      # 递归强制删除（⚠️ 慎用）
ln -s <target> <link>             # 创建软链接
tar -czf archive.tar.gz <dir>    # 压缩目录
tar -xzf archive.tar.gz          # 解压文件

Windows PowerShell

powershell 复制代码

# ===== 目录导航 =====
Get-Location                      # 显示当前目录
Set-Location <path>               # 切换目录（或 cd）
cd ~                              # 回到家目录（%USERPROFILE%）
cd -                              # 回到上一个目录
Push-Location <path>              # 切换目录并记录（可用 Pop-Location 回退）

# ===== 文件列表 =====
Get-ChildItem -Force              # 详细列表（含隐藏文件）
Get-ChildItem | Sort-Object Length -Descending   # 按文件大小排序
Get-ChildItem -Recurse | Where-Object { $_.Length -gt 10MB }  # 查找大文件

# ===== 文件搜索 =====
Get-ChildItem -Recurse -Filter "*.ets"                    # 查找 .ets 文件
Select-String -Path "*.ets" -Pattern "import" -Recurse    # 搜索文件内容
Get-ChildItem -Recurse | Where-Object { $_.Name -like "*deveco*" }  # 按名称搜索

# ===== 文件操作 =====
Copy-Item <src> <dst> -Recurse    # 递归复制目录
Move-Item <src> <dst>             # 移动或重命名
Remove-Item <path> -Recurse -Force  # 递归强制删除（⚠️ 慎用）
New-Item -ItemType SymbolicLink -Path <link> -Target <target>  # 创建软链接
Compress-Archive <dir> archive.zip   # 压缩为 zip
Expand-Archive archive.zip <dst>     # 解压 zip

C.2 系统信息与环境查看

MacOS

bash 复制代码

# ===== 系统信息 =====
sw_vers                           # 查看 MacOS 版本
uname -m                          # 查看 CPU 架构（arm64 / x86_64）
sysctl -n hw.memsize | awk '{print $1/1024/1024/1024 " GB"}'  # 查看总内存
system_profiler SPHardwareDataType   # 详细硬件信息
uptime                             # 系统运行时间和负载
df -h                              # 磁盘空间使用

# ===== 进程管理 =====
top                                # 实时进程监控（q 退出）
ps aux | grep node                 # 查找 Node.js 进程
kill -9 <PID>                      # 强制终止进程
lsof -i :8080                     # 查看占用端口的进程

# ===== 环境变量 =====
echo $PATH                         # 查看 PATH
env | grep -i proxy                # 查看代理相关变量
printenv                           # 查看所有环境变量

Windows PowerShell

powershell 复制代码

# ===== 系统信息 =====
systeminfo                         # 完整系统信息
$env:PROCESSOR_ARCHITECTURE        # CPU 架构
(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB  # 总内存
Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version  # OS 版本
Get-CimInstance Win32_LogicalDisk | Select-Object DeviceID, @{N='FreeGB';E={[math]::Round($_.FreeSpace/1GB,2)}}  # 磁盘空间

# ===== 进程管理 =====
Get-Process | Sort-Object WorkingSet -Descending | Select-Object -First 15  # 内存占用 Top 15
Get-Process -Name node -ErrorAction SilentlyContinue  # 查找 Node.js 进程
Stop-Process -Name node -Force    # 强制终止 Node.js 进程
Get-NetTCPConnection -LocalPort 8080 -ErrorAction SilentlyContinue  # 查看端口占用

# ===== 环境变量 =====
echo $env:PATH                     # 查看 PATH
$env: | Out-String                 # 查看所有环境变量
[Environment]::GetEnvironmentVariable("Path", "User")  # 查看用户 PATH

C.3 网络工具

MacOS

bash 复制代码

# ===== 网络测试 =====
curl -I https://developer.huawei.com     # 查看 HTTP 响应头
curl -s https://api.ipify.org            # 查看公网 IP
ping -c 5 baidu.com                      # 测试网络连通性
dig developer.huawei.com                 # DNS 查询
traceroute baidu.com                     # 路由追踪
netstat -an | grep LISTEN               # 查看所有监听端口

Windows PowerShell

powershell 复制代码

# ===== 网络测试 =====
Invoke-WebRequest -Uri "https://developer.huawei.com" -Method Head  # HTTP 响应头
(Invoke-WebRequest -Uri "https://api.ipify.org").Content            # 公网 IP
Test-Connection baidu.com -Count 5                                  # 网络连通性
Resolve-DnsName developer.huawei.com                                # DNS 查询
Test-NetConnection baidu.com -Port 443                              # 测试特定端口
Get-NetTCPConnection -State Listen                                  # 所有监听端口

C.4 常用开发工具命令

Git 常用命令（双平台通用）

bash 复制代码

# ===== 仓库管理 =====
git init                              # 初始化仓库
git clone <url>                       # 克隆远程仓库
git clone <url> --depth 1             # 浅克隆（仅最新提交，速度快）

# ===== 日常操作 =====
git status                            # 查看工作区状态
git add .                             # 暂存所有修改
git add -p                            # 交互式暂存（逐个选择）
git commit -m "feat: 添加新功能"       # 提交修改
git commit --amend --no-edit          # 修改上一次提交（不改变消息）

# ===== 分支管理 =====
git branch                            # 查看本地分支
git branch <name>                     # 创建分支
git checkout -b <name>                # 创建并切换分支
git merge <branch>                    # 合并分支
git rebase -i HEAD~5                  # 交互式变基（整理最近 5 个提交）

# ===== 远程操作 =====
git remote -v                         # 查看远程仓库
git push -u origin <branch>           # 推送并设置上游
git pull --rebase                     # 拉取并变基
git fetch --all                       # 拉取所有远程更新

# ===== 历史与对比 =====
git log --oneline --graph --all       # 图形化提交历史
git diff                              # 工作区 vs 暂存区
git diff --cached                     # 暂存区 vs 最近提交
git stash                             # 暂存当前修改
git stash pop                         # 恢复暂存的修改

# ===== 撤销与回退 =====
git checkout -- <file>                # 撤销文件修改
git reset HEAD <file>                 # 取消暂存
git reset --soft HEAD~1               # 回退提交但保留修改
git revert <commit>                   # 创建反向提交（安全回退）

ohpm 包管理命令（HarmonyOS 专用）

bash 复制代码

# ===== 包管理 =====
ohpm install                          # 安装所有依赖（根据 oh-package.json5）
ohpm install <package>                # 安装指定包
ohpm install <package>@1.2.0          # 安装指定版本
ohpm uninstall <package>              # 卸载包
ohpm update                           # 更新所有依赖到最新版本
ohpm update <package>                 # 更新指定包
ohpm list                             # 查看已安装的包列表
ohpm info <package>                   # 查看包的详细信息
ohpm search <keyword>                 # 搜索可用的包

# ===== 仓库配置 =====
ohpm config set registry <url>        # 设置仓库地址
ohpm config get registry              # 查看当前仓库地址
ohpm config list                      # 查看所有配置

# ===== 项目操作 =====
ohpm init                             # 初始化 oh-package.json5
ohpm link                             # 创建本地包的软链接（开发调试用）
ohpm publish                          # 发布包到 ohpm 仓库
ohpm pack                             # 打包为 .har 文件（不发布）

附录 D：模型 API 参数对照表

D.1 供应商 API 基础信息

供应商	模型前缀	API Base URL	认证方式	获取密钥地址
DevEco 内置	`glm-5`	自动管理（华为云服务）	OAuth Token（自动）	无需额外配置
DeepSeek	`deepseek-*`	`https://api.deepseek.com`	`Bearer sk-xxx`	https://platform.deepseek.com
通义千问	`qwen-*`	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`Bearer sk-xxx`	https://bailian.console.aliyun.com
智谱 AI	`glm-4-*`	`https://open.bigmodel.cn/api/paas/v4`	`Bearer xxx.xxx` (JWT)	https://open.bigmodel.cn
Moonshot	`moonshot-*`	`https://api.moonshot.cn/v1`	`Bearer sk-xxx`	https://platform.moonshot.cn
零一万物	`yi-*`	`https://api.lingyiwanwu.com/v1`	`Bearer xxx`	https://platform.lingyiwanwu.com
讯飞星火	`spark-*`	`https://spark-api-open.xf-yun.com/v1`	`Bearer xxx`	https://xinghuo.xfyun.cn/sparkapi
Ollama（本地）	`*`	`http://localhost:11434/v1`	`Bearer ollama`（任意值）	无需密钥

D.2 模型能力详细对照

模型	参数量	上下文窗口	工具调用	代码生成	推理能力	响应速度	输入价格 / 百万 Token	输出价格 / 百万 Token
GLM-5.1（内置）	-	128K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐	快	免费	免费
DeepSeek Chat	-	64K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐	快	¥1	¥2
DeepSeek Coder	-	64K	✅	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	快	¥1	¥2
Qwen Max	-	32K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	中	¥20	¥60
Qwen Plus	-	128K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐	中	¥4	¥12
Qwen Turbo	-	128K	✅	⭐⭐⭐	⭐⭐⭐	快	¥2	¥6
GLM-4 Plus	-	128K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐	中	¥50	¥50
GLM-4 Flash	-	128K	✅	⭐⭐⭐	⭐⭐⭐	快	免费	免费
Moonshot v1-128K	-	128K	✅	⭐⭐⭐	⭐⭐⭐⭐	中	¥60	¥60
Yi-Large	-	32K	✅	⭐⭐⭐⭐	⭐⭐⭐⭐	中	¥20	¥20
Qwen2.5-Coder 14B（本地）	14B	32K	部分	⭐⭐⭐⭐	⭐⭐⭐	取决于硬件	免费	免费
DeepSeek Coder 6.7B（本地）	6.7B	16K	❌	⭐⭐⭐⭐	⭐⭐⭐	取决于硬件	免费	免费
CodeLlama 13B（本地）	13B	16K	❌	⭐⭐⭐	⭐⭐⭐	取决于硬件	免费	免费

D.3 config.json 完整配置示例（多模型全接入）

json 复制代码

{
  "provider": {
    "deveco": {
      "name": "DevEco Code",
      "models": {
        "glm-5": {
          "tool_call": true,
          "context_window": 131072,
          "limit": 50
        }
      }
    },
    "deepseek": {
      "name": "DeepSeek",
      "api_base": "https://api.deepseek.com",
      "api_key": "sk-your-deepseek-key",
      "models": {
        "deepseek-chat": {
          "tool_call": true,
          "context_window": 65536,
          "max_tokens": 8192,
          "temperature": 0.7
        },
        "deepseek-coder": {
          "tool_call": true,
          "context_window": 65536,
          "max_tokens": 8192,
          "temperature": 0.3
        }
      }
    },
    "qwen": {
      "name": "通义千问",
      "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-your-qwen-key",
      "models": {
        "qwen-max": {
          "tool_call": true,
          "context_window": 32768,
          "max_tokens": 8192
        },
        "qwen-plus": {
          "tool_call": true,
          "context_window": 131072,
          "max_tokens": 8192
        },
        "qwen-turbo": {
          "tool_call": true,
          "context_window": 131072,
          "max_tokens": 8192
        }
      }
    },
    "zhipu": {
      "name": "智谱 AI",
      "api_base": "https://open.bigmodel.cn/api/paas/v4",
      "api_key": "your-zhipu-key",
      "models": {
        "glm-4-plus": {
          "tool_call": true,
          "context_window": 131072,
          "max_tokens": 4096
        },
        "glm-4-flash": {
          "tool_call": true,
          "context_window": 131072,
          "max_tokens": 4096
        }
      }
    },
    "moonshot": {
      "name": "Moonshot AI",
      "api_base": "https://api.moonshot.cn/v1",
      "api_key": "sk-your-moonshot-key",
      "models": {
        "moonshot-v1-32k": {
          "tool_call": true,
          "context_window": 32768,
          "max_tokens": 8192
        },
        "moonshot-v1-128k": {
          "tool_call": true,
          "context_window": 131072,
          "max_tokens": 8192
        }
      }
    },
    "ollama": {
      "name": "Ollama 本地模型",
      "api_base": "http://localhost:11434/v1",
      "api_key": "ollama",
      "models": {
        "qwen2.5-coder:14b": {
          "tool_call": true,
          "context_window": 32768,
          "max_tokens": 4096
        },
        "deepseek-coder:6.7b": {
          "tool_call": false,
          "context_window": 16384,
          "max_tokens": 4096
        }
      }
    }
  },
  "mcp": {
    "servers": []
  },
  "preferences": {
    "default_model": "glm-5",
    "auto_compact_threshold": 80,
    "theme": "dark",
    "language": "zh-CN"
  }
}

附录 E：Homebrew 常用 Formulae 列表（MacOS）

E.1 核心开发工具

包名	安装命令	说明
`git`	`brew install git`	分布式版本控制系统
`node@20`	`brew install node@20`	Node.js 20 LTS 版本
`fnm`	`brew install fnm`	极速 Node.js 版本管理器
`pnpm`	`brew install pnpm`	高效 npm 替代方案（硬链接节省空间）
`yarn`	`brew install yarn`	Facebook 出品的 npm 替代方案
`python@3.12`	`brew install python@3.12`	Python 3.12 运行时
`go`	`brew install go`	Go 编程语言
`rust`	`brew install rust`	Rust 编程语言

E.2 终端增强工具

包名	安装命令	说明	推荐理由
`zsh-autosuggestions`	`brew install zsh-autosuggestions`	zsh 命令自动建议（灰色提示，→ 键接受）	大幅提升命令输入速度
`zsh-syntax-highlighting`	`brew install zsh-syntax-highlighting`	zsh 语法实时高亮（正确绿色，错误红色）	即时发现拼写错误
`starship`	`brew install starship`	跨 Shell 的命令行提示符美化工具	Rust 编写，极快，信息丰富
`bat`	`brew install bat`	cat 的增强替代（语法高亮、行号、Git 集成）	查看代码文件体验极佳
`eza`	`brew install eza`	ls 的现代替代（图标、颜色、Git 状态）	让文件列表一目了然
`fzf`	`brew install fzf`	通用模糊搜索器（Ctrl+R 搜历史、Ctrl+T 搜文件）	效率神器
`ripgrep`	`brew install ripgrep`	grep 的极速替代（Rust 编写，自动忽略 .gitignore）	项目代码搜索首选
`fd`	`brew install fd`	find 的友好替代（语法简洁、速度快）	快速定位文件
`tree`	`brew install tree`	树形显示目录结构	理解项目结构
`jq`	`brew install jq`	命令行 JSON 处理器	处理 API 响应、配置文件
`htop`	`brew install htop`	增强版进程管理器	监控系统资源
`tldr`	`brew install tldr`	man 的简洁替代（实用示例为主）	快速查命令用法
`httpie`	`brew install httpie`	人性化 HTTP 客户端	API 调试
`neovim`	`brew install neovim`	Vim 的现代分支（支持 LSP、Lua 插件）	终端编辑器

E.3 GUI 应用（Homebrew Cask）

包名	安装命令	说明
`iterm2`	`brew install --cask iterm2`	MacOS 最佳终端模拟器
`visual-studio-code`	`brew install --cask visual-studio-code`	微软 VS Code 编辑器
`google-chrome`	`brew install --cask google-chrome`	Chrome 浏览器
`postman`	`brew install --cask postman`	API 测试与调试工具
`docker`	`brew install --cask docker`	Docker Desktop 容器平台
`figma`	`brew install --cask figma`	UI/UX 设计协作工具
`obsidian`	`brew install --cask obsidian`	双链笔记工具
`raycast`	`brew install --cask raycast`	效率启动器（完美替代 Spotlight）
`snipaste`	`brew install --cask snipaste`	截图与贴图工具
`typora`	`brew install --cask typora`	极简 Markdown 编辑器
`rectangle`	`brew install --cask rectangle`	窗口管理工具（快捷键分屏）
`font-jetbrains-mono`	`brew install --cask font-jetbrains-mono`	JetBrains 等宽编程字体
`font-fira-code`	`brew install --cask font-fira-code`	Fira Code 连字编程字体

E.4 Homebrew 常用操作命令

bash 复制代码

# ===== 基础操作 =====
brew update                        # 更新 Homebrew 本身和公式库
brew upgrade                       # 升级所有已安装的包
brew upgrade <package>             # 升级指定包
brew list                          # 列出已安装的所有包
brew info <package>                # 查看包的详细信息
brew search <keyword>              # 搜索可用的包

# ===== 清理与维护 =====
brew cleanup                       # 清理旧版本的缓存
brew cleanup -s                    # 清理所有版本的缓存（释放更多空间）
brew doctor                        # 检查 Homebrew 健康状态
brew deps --tree <package>         # 查看包的依赖树

# ===== 服务管理 =====
brew services list                 # 查看所有后台服务状态
brew services start <service>      # 启动并设为开机自启
brew services stop <service>       # 停止服务
brew services restart <service>    # 重启服务

# ===== 国内镜像配置 =====
# 清华大学镜像源
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git"

# 将上述内容添加到 ~/.zshrc 中永久生效

附录 F：ArkTS 常用装饰器速查表

F.1 状态管理装饰器

装饰器	作用	数据流向	初始化要求	支持类型	使用注意事项
`@State`	组件自身状态变量	组件内部 → UI	必须本地初始化	简单类型 + @Observed 类	变化自动触发 `build()` 重新执行
`@Prop`	父向子单向传递	父 → 子（深拷贝）	可本地初始化默认值	简单类型	子组件修改不影响父组件；不支持对象类型
`@Link`	父子双向绑定	父 ↔ 子	不可本地初始化	简单类型 + @Observed 类	传递时必须用 `$` 语法（如 `$count`）
`@Provide`	跨层级向下传递	祖先 → 后代	必须本地初始化	简单类型 + @Observed 类	支持别名，避免命名冲突
`@Consume`	接收 @Provide 数据	祖先 → 后代	不可本地初始化	与 @Provide 一致	必须与 @Provide 的变量名或别名匹配
`@Observed`	标记可观察类	-	-	class	必须与 @ObjectLink 或 @State 配合使用
`@ObjectLink`	接收 @Observed 实例引用	父 → 子（引用）	不可本地初始化	@Observed 类	嵌套属性变化直接触发 UI 刷新
`@Watch`	状态变化监听回调	-	-	-	监听 @State/@Prop/@Link 变化，触发指定回调
`@Track`	精确属性追踪	-	-	-	配合 @Observed，仅追踪标记属性，优化性能

F.2 V2 状态管理装饰器（API 12+）

装饰器	作用	V1 替代方案	新增能力
`@Local`	组件本地状态	`@State`	语义更清晰，支持更多类型
`@Param`	父向子参数传递	`@Prop`	支持单向数据流约束
`@Event`	子向父事件回调	回调函数 prop	语义明确，类型安全
`@Monitor`	深度状态监控	`@Watch`	支持深度监听、条件触发
`@Computed`	计算属性	getter	自动缓存，依赖变化时重新计算
`@ObservedV2`	V2 可观察标记	`@Observed`	支持 Map/Set 等复杂类型
`@Trace`	V2 属性追踪	`@Track`	自动追踪，无需手动标记

F.3 组件定义与 UI 构建装饰器

装饰器	作用	适用位置	详细说明
`@Entry`	标记页面入口	struct	一个页面只能有一个，必须配合 `@Component`
`@Component`	标记自定义组件	struct	必须包含 `build()` 方法
`@Builder`	UI 构建函数	方法	拆分复杂 UI，可在 `build()` 中调用，支持参数
`@Styles`	通用样式函数	方法	定义可复用样式集合，只能设置通用属性
`@Extend`	组件扩展样式	方法	基于特定组件类型扩展默认样式
`@Reusable`	可复用组件标记	struct	列表滚动时复用实例，提升长列表性能
`@Preview`	预览组件标记	struct	在 DevEco Studio Previewer 中显示实时预览
`@CustomDialog`	自定义对话框	struct	配合 `CustomDialogController` 使用
`@Require`	必须传参标记	属性	标记 `@Prop`/`@Link` 等必须在创建组件时传入
`@Once`	仅初始化一次	属性	配合 `@State` 使用，仅在首次创建时赋值

F.4 生命周期方法速查表

方法	所属装饰器	触发时机	典型用途
`aboutToAppear()`	`@Entry` / `@Component`	`build()` 之前	初始化数据、发起网络请求、注册监听
`aboutToDisappear()`	`@Entry` / `@Component`	组件销毁前	清理定时器、取消请求、注销监听
`onDidBuild()`	`@Entry` / `@Component`	`build()` 之后	获取渲染尺寸、执行依赖布局的动画
`onPageShow()`	`@Entry`	页面每次显示	刷新数据、恢复动画、重新获取定位
`onPageHide()`	`@Entry`	页面每次隐藏	暂停视频/动画、保存编辑状态
`onBackPress()`	`@Entry`	用户按下返回键	拦截返回、弹窗确认、自定义路由
`onAreaChange()`	所有组件	组件尺寸变化	响应式布局、尺寸记录
`onSizeChange()`	所有组件	组件大小变化	动态调整子组件布局

F.5 装饰器使用规则速查

规则	说明
`@State` 不能直接观察对象深层属性	必须配合 `@Observed` 类
`@Prop` 传递时创建深拷贝	子组件修改不影响父组件，不适合大对象
`@Link` 传递时必须使用 `$`	如 `ChildComponent({ count: $parentCount })`
`@ObjectLink` 不能本地初始化	必须由父组件传入 `@Observed` 实例
`@Provide`/`@Consume` 通过名称匹配	可使用别名避免冲突：`@Provide('alias')`
`@Builder` 内的 `this` 指向调用组件	传参时注意引用传递 vs 值传递
`@Reusable` 组件需实现 `aboutToReuse()`	在复用时更新数据

F.6 完整状态管理代码示例

typescript 复制代码

// =============================================
// 文件名：src/main/ets/pages/StateManagementDemo.ets
// 功能描述：完整演示 ArkTS 状态管理装饰器的综合用法
// 涵盖：@State, @Prop, @Link, @Provide/@Consume, @Observed/@ObjectLink, @Watch
// =============================================

// ============================================================
// 数据模型层
// ============================================================

/**
 * 购物车商品数据模型
 * @Observed 装饰器标记此类可被观察，其嵌套属性变化能触发 UI 更新
 * 必须配合 @ObjectLink 或 @State 使用
 */
@Observed
class CartItem {
  id: string;
  name: string;
  price: number;
  quantity: number;
  imageUrl: string;

  constructor(id: string, name: string, price: number, imageUrl: string) {
    this.id = id;
    this.name = name;
    this.price = price;
    this.quantity = 1;
    this.imageUrl = imageUrl;
  }

  /** 计算小计金额 */
  getSubtotal(): number {
    return this.price * this.quantity;
  }
}

/**
 * 用户信息数据模型
 */
@Observed
class UserInfo {
  nickname: string = '未登录';
  avatar: string = '';
  vipLevel: number = 0;
}

// ============================================================
// 页面入口组件
// ============================================================

@Entry
@Component
struct ShoppingCartPage {
  // ----- @State：组件自身状态 -----
  // 购物车商品列表（数组变化触发 UI 刷新）
  @State cartItems: CartItem[] = [
    new CartItem('001', 'HarmonyOS 开发实战', 99.00, 'app.media.book'),
    new CartItem('002', '机械键盘 Cherry 红轴', 599.00, 'app.media.keyboard'),
    new CartItem('003', '无线蓝牙耳机', 299.00, 'app.media.earphone')
  ];

  // 搜索关键词
  @State searchKeyword: string = '';

  // 是否显示清空确认弹窗
  @State showClearDialog: boolean = false;

  // 当前选中的排序方式
  @State sortMode: string = 'default';

  // 用户信息
  @State currentUser: UserInfo = new UserInfo();

  // ----- @Watch：监听状态变化 -----
  // 监听 cartItems 变化，自动更新总价
  @State totalPrice: number = 0;
  @Watch('onCartChanged') cartVersion: number = 0;

  // ----- @Provide：向下层组件树提供数据 -----
  // 主题色（所有后代组件可通过 @Consume 获取）
  @Provide('themeColor') themeColor: string = '#FF6B00';

  // 折扣率（VIP 用户享受折扣）
  @Provide('discountRate') discountRate: number = 1.0;

  // ============================================================
  // 生命周期
  // ============================================================

  aboutToAppear(): void {
    // 页面即将出现时：初始化用户信息、计算初始总价
    this.loadUserInfo();
    this.calculateTotal();
  }

  aboutToDisappear(): void {
    // 页面即将销毁时：清理资源
    console.info('ShoppingCartPage 即将销毁，清理资源...');
  }

  // ============================================================
  // 私有方法
  // ============================================================

  /**
   * 模拟加载用户信息
   */
  private loadUserInfo(): void {
    // 实际项目中应从网络或本地存储获取
    this.currentUser.nickname = '鸿蒙开发者';
    this.currentUser.vipLevel = 2;

    // VIP 用户享受折扣
    if (this.currentUser.vipLevel >= 2) {
      this.discountRate = 0.9; // 9 折
    }
  }

  /**
   * 计算购物车总价
   */
  private calculateTotal(): void {
    this.totalPrice = this.cartItems.reduce((sum, item) => sum + item.getSubtotal(), 0);
  }

  /**
   * @Watch 回调：购物车变化时重新计算总价
   */
  onCartChanged(): void {
    this.calculateTotal();
  }

  /**
   * 增加商品数量
   */
  private increaseQuantity(index: number): void {
    this.cartItems[index].quantity++;
    this.cartVersion++; // 触发 @Watch
  }

  /**
   * 减少商品数量
   */
  private decreaseQuantity(index: number): void {
    if (this.cartItems[index].quantity > 1) {
      this.cartItems[index].quantity--;
      this.cartVersion++; // 触发 @Watch
    }
  }

  /**
   * 移除商品
   */
  private removeItem(index: number): void {
    this.cartItems.splice(index, 1);
    this.cartVersion++; // 触发 @Watch
  }

  // ============================================================
  // UI 构建
  // ============================================================

  build() {
    Column() {
      // 1. 顶部导航栏
      this.HeaderBar()

      // 2. 用户信息条
      this.UserInfoBar({ user: this.currentUser })

      // 3. 购物车列表
      if (this.cartItems.length > 0) {
        List({ space: 12 }) {
          ForEach(this.cartItems, (item: CartItem, index: number) => {
            ListItem() {
              this.CartItemCard({
                item: item,
                onIncrease: () => { this.increaseQuantity(index); },
                onDecrease: () => { this.decreaseQuantity(index); },
                onRemove: () => { this.removeItem(index); }
              })
            }
          }, (item: CartItem) => item.id) // 使用唯一 id 作为 key
        }
        .layoutWeight(1)
        .padding({ left: 16, right: 16, top: 12 })
      } else {
        // 空状态
        this.EmptyCartView()
      }

      // 4. 底部结算栏
      if (this.cartItems.length > 0) {
        this.CheckoutBar()
      }
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#F5F5F5')
  }

  // ============================================================
  // @Builder 子组件
  // ============================================================

  /**
   * 顶部导航栏
   */
  @Builder
  HeaderBar() {
    Row() {
      Text('购物车')
        .fontSize(20)
        .fontWeight(FontWeight.Bold)

      Blank()

      Text(`共 ${this.cartItems.length} 件`)
        .fontSize(14)
        .fontColor('#999')

      if (this.cartItems.length > 0) {
        Text('清空')
          .fontSize(14)
          .fontColor('#FF4D4F')
          .margin({ left: 16 })
          .onClick(() => {
            this.cartItems = [];
            this.cartVersion++;
          })
      }
    }
    .width('100%')
    .height(56)
    .padding({ left: 16, right: 16 })
    .backgroundColor(Color.White)
  }

  /**
   * 底部结算栏
   */
  @Builder
  CheckoutBar() {
    Row() {
      Column() {
        Text('合计')
          .fontSize(12)
          .fontColor('#999')
        Text(`¥${(this.totalPrice * this.discountRate).toFixed(2)}`)
          .fontSize(22)
          .fontWeight(FontWeight.Bold)
          .fontColor('#FF4D4F')
      }
      .alignItems(HorizontalAlign.Start)
      .layoutWeight(1)

      if (this.discountRate < 1.0) {
        Text(`已享 ${this.discountRate * 10} 折优惠`)
          .fontSize(11)
          .fontColor(this.themeColor)
          .margin({ right: 12 })
      }

      Button('去结算')
        .type(ButtonType.Normal)
        .backgroundColor(this.themeColor)
        .fontColor(Color.White)
        .fontSize(16)
        .width(120)
        .height(44)
        .borderRadius(22)
        .onClick(() => {
          // 跳转结算页面
          console.info('跳转到结算页面...');
        })
    }
    .width('100%')
    .height(72)
    .padding({ left: 16, right: 16 })
    .backgroundColor(Color.White)
  }

  /**
   * 空购物车视图
   */
  @Builder
  EmptyCartView() {
    Column() {
      Image($r('app.media.empty_cart'))
        .width(120)
        .height(120)
        .margin({ top: 80 })
      Text('购物车空空如也')
        .fontSize(16)
        .fontColor('#999')
        .margin({ top: 16 })
      Button('去逛逛')
        .margin({ top: 24 })
        .backgroundColor(this.themeColor)
        .fontColor(Color.White)
    }
    .width('100%')
    .layoutWeight(1)
    .justifyContent(FlexAlign.Start)
    .alignItems(HorizontalAlign.Center)
  }
}

// ============================================================
// 子组件定义
// ============================================================

/**
 * 用户信息条组件
 * 使用 @ObjectLink 接收 @Observed 的 UserInfo 实例
 */
@Component
struct UserInfoBar {
  @ObjectLink user: UserInfo; // 接收 @Observed 对象引用

  build() {
    Row() {
      Image(this.user.avatar || $r('app.media.default_avatar'))
        .width(32)
        .height(32)
        .borderRadius(16)
        .margin({ right: 8 })

      Text(this.user.nickname)
        .fontSize(14)
        .fontWeight(FontWeight.Medium)

      if (this.user.vipLevel > 0) {
        Text(`VIP${this.user.vipLevel}`)
          .fontSize(10)
          .fontColor(Color.White)
          .backgroundColor('#FFD700')
          .borderRadius(4)
          .padding({ left: 6, right: 6, top: 2, bottom: 2 })
          .margin({ left: 8 })
      }
    }
    .width('100%')
    .padding({ left: 16, right: 16, top: 8, bottom: 8 })
    .backgroundColor('#FFF8F0')
  }
}

/**
 * 购物车商品卡片组件
 * 使用 @ObjectLink 接收 CartItem，商品数量变化直接触发 UI 刷新
 */
@Component
struct CartItemCard {
  @ObjectLink item: CartItem;          // 接收 @Observed 实例
  onIncrease: () => void = () => {};   // 增加数量回调
  onDecrease: () => void = () => {};   // 减少数量回调
  onRemove: () => void = () => {};     // 移除商品回调

  // @Consume：从祖先组件获取折扣率
  @Consume('discountRate') discountRate: number;

  build() {
    Row() {
      // 商品图片
      Image(this.item.imageUrl)
        .width(80)
        .height(80)
        .borderRadius(8)
        .objectFit(ImageFit.Cover)

      // 商品信息
      Column() {
        Text(this.item.name)
          .fontSize(15)
          .maxLines(2)
          .textOverflow({ overflow: TextOverflow.Ellipsis })

        Row() {
          // 折后价格
          Text(`¥${(this.item.price * this.discountRate).toFixed(2)}`)
            .fontSize(16)
            .fontWeight(FontWeight.Bold)
            .fontColor('#FF4D4F')

          // 原价（有折扣时显示划线价）
          if (this.discountRate < 1.0) {
            Text(`¥${this.item.price.toFixed(2)}`)
              .fontSize(12)
              .fontColor('#CCC')
              .decoration({ type: TextDecorationType.LineThrough })
              .margin({ left: 8 })
          }
        }
        .margin({ top: 8 })

        // 数量控制器
        Row() {
          Button('-')
            .type(ButtonType.Circle)
            .width(28)
            .height(28)
            .fontSize(16)
            .backgroundColor('#F5F5F5')
            .onClick(() => { this.onDecrease(); })

          Text(`${this.item.quantity}`)
            .fontSize(15)
            .width(40)
            .textAlign(TextAlign.Center)

          Button('+')
            .type(ButtonType.Circle)
            .width(28)
            .height(28)
            .fontSize(16)
            .backgroundColor('#F5F5F5')
            .onClick(() => { this.onIncrease(); })
        }
        .margin({ top: 8 })
      }
      .layoutWeight(1)
      .margin({ left: 12 })
      .alignItems(HorizontalAlign.Start)

      // 删除按钮
      Image($r('app.media.icon_delete'))
        .width(20)
        .height(20)
        .onClick(() => { this.onRemove(); })
    }
    .width('100%')
    .padding(12)
    .backgroundColor(Color.White)
    .borderRadius(12)
  }
}

附录 G：一键安装脚本（双平台 PowerShell/Bash）

G.1 MacOS 一键安装脚本（Bash）

使用方法：

bash 复制代码

# 1. 下载脚本
curl -o ~/install-deveco.sh https://raw.githubusercontent.com/deveco/scripts/main/install-deveco.sh
# 或手动创建：touch ~/install-deveco.sh && open -e ~/install-deveco.sh

# 2. 赋予执行权限
chmod +x ~/install-deveco.sh

# 3. 执行安装
~/install-deveco.sh

# 4. 安装完成后重启终端或执行
source ~/.zshrc

完整脚本内容：

bash 复制代码

#!/bin/bash
# ====================================================================
# DevEco Code MacOS 一键安装与配置脚本
# =====================================================================
# 适用系统：MacOS 13+ (Ventura / Sonoma / Sequoia)
# 适用架构：Intel (x86_64) + Apple Silicon (arm64)
# 功能说明：
#   1. 检测并安装 Homebrew（含国内镜像加速）
#   2. 安装 Xcode Command Line Tools
#   3. 安装 fnm 和 Node.js 20 LTS
#   4. 配置 npm 国内镜像源
#   5. 全局安装 DevEco Code
#   6. 配置 Shell 别名与快捷命令
#   7. 安装常用终端增强工具（可选）
# =====================================================================

set -e  # 遇到错误立即退出

# ===== 颜色定义 =====
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
CYAN='\033[0;36m'
BLUE='\033[0;34m'
BOLD='\033[1m'
NC='\033[0m'

info()    { echo -e "${CYAN}[INFO]${NC} $1"; }
success() { echo -e "${GREEN}[✅]${NC} $1"; }
warn()    { echo -e "${YELLOW}[⚠️]${NC} $1"; }
error()   { echo -e "${RED}[❌]${NC} $1"; }
header()  { echo -e "\n${BLUE}${BOLD}═══ $1 ═══${NC}\n"; }

# ===== Banner =====
echo -e "${CYAN}${BOLD}"
echo "╔═══════════════════════════════════════════════╗"
echo "║   DevEco Code 一键安装脚本 (MacOS)            ║"
echo "║   HarmonyOS AI Agent 开发环境自动配置          ║"
echo "╚═══════════════════════════════════════════════╝"
echo -e "${NC}"

# ===== 1. 系统检测 =====
header "第一步：系统环境检测"

ARCH=$(uname -m)
MACOS_VERSION=$(sw_vers -productVersion)

info "CPU 架构: $ARCH"
info "MacOS 版本: $MACOS_VERSION"

if [ "$ARCH" != "arm64" ] && [ "$ARCH" != "x86_64" ]; then
    error "不支持的 CPU 架构: $ARCH"
    exit 1
fi

# ===== 2. 安装 Xcode Command Line Tools =====
header "第二步：Xcode Command Line Tools"

if xcode-select -p &>/dev/null; then
    success "Xcode CLT 已安装: $(xcode-select -p)"
else
    info "正在安装 Xcode Command Line Tools..."
    warn "请在弹出的对话框中点击「安装」按钮"
    xcode-select --install
    # 等待安装完成
    while ! xcode-select -p &>/dev/null; do
        sleep 5
    done
    success "Xcode CLT 安装完成"
fi

# 验证核心工具
git --version 2>/dev/null && success "git: $(git --version)"
clang --version 2>/dev/null | head -1 && success "clang: OK"

# ===== 3. 安装 Homebrew =====
header "第三步：Homebrew 包管理器"

# 配置 Homebrew 镜像（加速下载）
export HOMEBREW_API_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles/api"
export HOMEBREW_BOTTLE_DOMAIN="https://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles"
export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git"

if command -v brew &>/dev/null; then
    success "Homebrew 已安装: $(brew --version | head -1)"
    brew update
else
    info "正在安装 Homebrew..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Apple Silicon 配置 PATH
    if [ "$ARCH" = "arm64" ]; then
        echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
        eval "$(/opt/homebrew/bin/brew shellenv)"
    fi
    success "Homebrew 安装完成"
fi

# ===== 4. 安装 fnm 和 Node.js =====
header "第四步：Node.js 运行环境"

# 安装 fnm
if command -v fnm &>/dev/null; then
    success "fnm 已安装: $(fnm --version)"
else
    info "正在安装 fnm..."
    brew install fnm
    success "fnm 安装完成"
fi

# 配置 fnm 到 Shell
if ! grep -q "fnm env" ~/.zshrc 2>/dev/null; then
    echo '' >> ~/.zshrc
    echo '# fnm (Fast Node Manager)' >> ~/.zshrc
    echo 'eval "$(fnm env --use-on-cd --shell zsh)"' >> ~/.zshrc
    info "fnm 已配置到 ~/.zshrc"
fi

# 激活 fnm
eval "$(fnm env --use-on-cd --shell zsh)"

# 安装 Node.js 20 LTS
if command -v node &>/dev/null; then
    NODE_VER=$(node -v)
    if [[ "$NODE_VER" == v20.* ]]; then
        success "Node.js $NODE_VER 已安装且版本正确"
    else
        warn "当前 Node.js 版本为 $NODE_VER，将安装 v20 LTS..."
        fnm install 20
        fnm default 20
        fnm use 20
        success "Node.js $(node -v) 安装完成"
    fi
else
    info "正在安装 Node.js 20 LTS..."
    fnm install 20
    fnm default 20
    fnm use 20
    success "Node.js $(node -v) 安装完成"
fi

success "npm $(npm -v) 已就绪"

# ===== 5. 配置 npm 镜像 =====
header "第五步：npm 镜像源配置"

info "切换 npm 镜像源为 npmmirror..."
npm config set registry https://registry.npmmirror.com
REGISTRY=$(npm config get registry)
success "npm 镜像源: $REGISTRY"

# ===== 6. 安装 DevEco Code =====
header "第六步：安装 DevEco Code"

info "正在全局安装 @deveco/deveco-code..."
npm install -g @deveco/deveco-code

if command -v deveco &>/dev/null; then
    DEVECO_VER=$(deveco --version 2>/dev/null || echo "unknown")
    success "DevEco Code 安装成功！版本: $DEVECO_VER"
else
    error "DevEco Code 安装似乎未成功，请检查上方日志"
    exit 1
fi

# ===== 7. 配置 Shell 快捷命令 =====
header "第七步：Shell 快捷命令配置"

# 检查并添加别名
if ! grep -q "# DevEco Code" ~/.zshrc 2>/dev/null; then
    cat >> ~/.zshrc << 'ALIASES'

# DevEco Code 快捷命令
alias dc='deveco'
alias dcu='deveco upgrade'
alias dcs='deveco status'
alias dcl='deveco logout'
alias dch='deveco --help'
ALIASES
    success "已添加快捷别名到 ~/.zshrc: dc, dcu, dcs, dcl, dch"
else
    info "~/.zshrc 中已存在 DevEco Code 配置，跳过"
fi

# ===== 8. 可选：安装终端增强工具 =====
header "第八步：终端增强工具（可选）"

echo -e "是否安装推荐的终端增强工具？"
echo "  - zsh-autosuggestions (命令自动建议)"
echo "  - zsh-syntax-highlighting (语法高亮)"
echo "  - bat (增强版 cat)"
echo "  - eza (增强版 ls)"
echo "  - ripgrep (增强版 grep)"
echo ""
read -p "是否安装？(y/N) " -n 1 -r
echo ""

if [[ $REPLY =~ ^[Yy]$ ]]; then
    info "正在安装终端增强工具..."
    brew install zsh-autosuggestions zsh-syntax-highlighting bat eza ripgrep

    # 配置 zsh 插件
    if ! grep -q "zsh-autosuggestions.zsh" ~/.zshrc 2>/dev/null; then
        BREW_PREFIX=$(brew --prefix)
        cat >> ~/.zshrc << ZSHPLUGINS

# zsh 增强插件
source ${BREW_PREFIX}/share/zsh-autosuggestions/zsh-autosuggestions.zsh
source ${BREW_PREFIX}/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh
ZSHPLUGINS
        success "终端增强工具安装并配置完成"
    fi
else
    info "跳过终端增强工具安装"
fi

# ===== 9. 创建项目目录 =====
header "第九步：项目目录初始化"

HARMONY_HOME=~/HarmonyOSProjects
if [ ! -d "$HARMONY_HOME" ]; then
    mkdir -p "$HARMONY_HOME"
    success "已创建项目目录: $HARMONY_HOME"
else
    info "项目目录已存在: $HARMONY_HOME"
fi

# ===== 完成 =====
header "🎉 安装完成"

echo -e "${GREEN}${BOLD}"
echo "╔═══════════════════════════════════════════════╗"
echo "║   DevEco Code 环境配置已全部完成！              ║"
echo "╚═══════════════════════════════════════════════╝"
echo -e "${NC}"
echo ""
echo -e "后续步骤："
echo -e "  1. 重启终端或执行 ${CYAN}source ~/.zshrc${NC}"
echo -e "  2. 进入项目目录：${CYAN}cd ~/HarmonyOSProjects/YourApp${NC}"
echo -e "  3. 启动 DevEco Code：${CYAN}deveco${NC}（或快捷命令 ${CYAN}dc${NC}）"
echo -e "  4. 首次使用需登录华为开发者账号"
echo ""
echo -e "遇到问题？运行 ${CYAN}deveco --help${NC} 或 ${CYAN}/doctor${NC} 检查环境"
echo ""

G.2 Windows 一键安装脚本（PowerShell）

使用方法：

powershell 复制代码

# 1. 以管理员身份打开 PowerShell
# 2. 执行脚本（如果从文件运行）
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\install-deveco.ps1

# 3. 安装完成后重启 PowerShell

完整脚本内容：

powershell 复制代码

# ====================================================================
# DevEco Code Windows 一键安装与配置脚本
# ====================================================================
# 适用系统：Windows 10 / 11 (64位)
# 运行要求：必须以管理员身份运行
# 功能说明：
#   1. 设置 PowerShell 执行策略
#   2. 安装 winget（如缺失）
#   3. 安装 fnm 和 Node.js 20 LTS
#   4. 配置 npm 国内镜像源
#   5. 全局安装 DevEco Code
#   6. 配置 PowerShell 快捷函数
#   7. 创建项目目录
# ====================================================================

# ===== 检查管理员权限 =====
$isAdmin = ([Security.Principal.WindowsPrincipal] `
    [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole(
    [Security.Principal.WindowsBuiltInRole]::Administrator)

if (-not $isAdmin) {
    Write-Host ""
    Write-Host "  ╔═══════════════════════════════════════════╗" -ForegroundColor Red
    Write-Host "  ║  错误：请以管理员身份运行此脚本！           ║" -ForegroundColor Red
    Write-Host "  ║  右键 PowerShell → 以管理员身份运行        ║" -ForegroundColor Red
    Write-Host "  ╚═══════════════════════════════════════════╝" -ForegroundColor Red
    Write-Host ""
    exit 1
}

# ===== 辅助函数 =====
function Write-Info    { param($msg) Write-Host "[INFO] $msg" -ForegroundColor Cyan }
function Write-Ok      { param($msg) Write-Host "[ OK ] $msg" -ForegroundColor Green }
function Write-Warn    { param($msg) Write-Host "[WARN] $msg" -ForegroundColor Yellow }
function Write-Err     { param($msg) Write-Host "[ERR ] $msg" -ForegroundColor Red }
function Write-Header  { param($msg) Write-Host "`n═══ $msg ═══`n" -ForegroundColor Blue }

# ===== Banner =====
Write-Host ""
Write-Host "╔═══════════════════════════════════════════════╗" -ForegroundColor Cyan
Write-Host "║   DevEco Code 一键安装脚本 (Windows)          ║" -ForegroundColor Cyan
Write-Host "║   HarmonyOS AI Agent 开发环境自动配置          ║" -ForegroundColor Cyan
Write-Host "╚═══════════════════════════════════════════════╝" -ForegroundColor Cyan
Write-Host ""

# ===== 1. 设置执行策略 =====
Write-Header "第一步：PowerShell 执行策略"

Write-Info "设置执行策略为 RemoteSigned..."
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
Write-Ok "执行策略已设置为 RemoteSigned"

# ===== 2. 检测 winget =====
Write-Header "第二步：winget 包管理器"

if (Get-Command winget -ErrorAction SilentlyContinue) {
    $wingetVer = winget --version
    Write-Ok "winget 已安装: $wingetVer"
} else {
    Write-Warn "未检测到 winget，请从 Microsoft Store 安装 '应用安装程序'"
    Write-Warn "安装完成后重新运行此脚本"
    exit 1
}

# ===== 3. 安装 fnm =====
Write-Header "第三步：fnm (Fast Node Manager)"

if (Get-Command fnm -ErrorAction SilentlyContinue) {
    Write-Ok "fnm 已安装: $(fnm --version)"
} else {
    Write-Info "正在通过 winget 安装 fnm..."
    winget install Schniz.fnm --accept-source-agreements --accept-package-agreements
    Write-Ok "fnm 安装完成"
}

# 刷新环境变量
$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
            [System.Environment]::GetEnvironmentVariable("Path", "User")

# 配置 fnm 到 PowerShell Profile
$profilePath = $PROFILE
if (-not (Test-Path (Split-Path $profilePath))) {
    New-Item -Path (Split-Path $profilePath) -ItemType Directory -Force | Out-Null
}
if (-not (Test-Path $profilePath)) {
    New-Item -Path $profilePath -ItemType File -Force | Out-Null
}

if (-not (Select-String -Path $profilePath -Pattern "fnm env" -Quiet)) {
    Add-Content -Path $profilePath -Value ""
    Add-Content -Path $profilePath -Value "# fnm (Fast Node Manager)"
    Add-Content -Path $profilePath -Value 'fnm env --use-on-cd | Out-String | Invoke-Expression'
    Write-Ok "fnm 已配置到 PowerShell Profile"
}

# 激活 fnm
fnm env --use-on-cd | Out-String | Invoke-Expression

# ===== 4. 安装 Node.js =====
Write-Header "第四步：Node.js 运行环境"

$nodeInstalled = $false
if (Get-Command node -ErrorAction SilentlyContinue) {
    $nodeVer = node -v
    if ($nodeVer -like "v20.*") {
        Write-Ok "Node.js $nodeVer 已安装且版本正确"
        $nodeInstalled = $true
    } else {
        Write-Warn "当前 Node.js 版本为 $nodeVer，将安装 v20 LTS..."
    }
}

if (-not $nodeInstalled) {
    Write-Info "正在安装 Node.js 20 LTS..."
    fnm install 20
    fnm default 20
    fnm use 20
    Write-Ok "Node.js $(node -v) 安装完成"
}

Write-Ok "npm $(npm -v) 已就绪"

# ===== 5. 配置 npm 镜像 =====
Write-Header "第五步：npm 镜像源配置"

Write-Info "切换 npm 镜像源为 npmmirror..."
npm config set registry https://registry.npmmirror.com
$registry = npm config get registry
Write-Ok "npm 镜像源: $registry"

# ===== 6. 安装 DevEco Code =====
Write-Header "第六步：安装 DevEco Code"

Write-Info "正在全局安装 @deveco/deveco-code..."
npm install -g @deveco/deveco-code

# 刷新 PATH
$env:Path = [System.Environment]::GetEnvironmentVariable("Path", "Machine") + ";" +
            [System.Environment]::GetEnvironmentVariable("Path", "User")

if (Get-Command deveco -ErrorAction SilentlyContinue) {
    $devecoVer = deveco --version 2>$null
    Write-Ok "DevEco Code 安装成功！版本: $devecoVer"
} else {
    Write-Err "DevEco Code 安装似乎未成功，请检查上方日志"
    Write-Info "尝试刷新 PATH 后重试..."
    $npmPrefix = (npm config get prefix).Trim()
    $env:Path = "$npmPrefix;$env:Path"
    if (Get-Command deveco -ErrorAction SilentlyContinue) {
        Write-Ok "DevEco Code 已可用（PATH 已刷新）"
    } else {
        Write-Err "请手动将 npm 全局目录添加到系统 PATH"
        Write-Info "npm 全局目录: $(npm config get prefix)"
    }
}

# ===== 7. 配置 PowerShell 快捷函数 =====
Write-Header "第七步：PowerShell 快捷函数配置"

if (-not (Select-String -Path $profilePath -Pattern "function dc " -Quiet)) {
    Add-Content -Path $profilePath -Value ""
    Add-Content -Path $profilePath -Value "# DevEco Code 快捷函数"
    Add-Content -Path $profilePath -Value "function dc { deveco }"
    Add-Content -Path $profilePath -Value "function dcu { deveco upgrade }"
    Add-Content -Path $profilePath -Value "function dcs { deveco status }"
    Add-Content -Path $profilePath -Value "function dcl { deveco logout }"
    Add-Content -Path $profilePath -Value "function dch { deveco --help }"
    Write-Ok "已添加快捷函数到 Profile: dc, dcu, dcs, dcl, dch"
} else {
    Write-Info "Profile 中已存在 DevEco Code 配置，跳过"
}

# ===== 8. 创建项目目录 =====
Write-Header "第八步：项目目录初始化"

$harmonyHome = Join-Path $env:USERPROFILE "HarmonyOSProjects"
if (-not (Test-Path $harmonyHome)) {
    New-Item -Path $harmonyHome -ItemType Directory -Force | Out-Null
    Write-Ok "已创建项目目录: $harmonyHome"
} else {
    Write-Info "项目目录已存在: $harmonyHome"
}

# 添加快速切换函数到 Profile
if (-not (Select-String -Path $profilePath -Pattern "function hcd" -Quiet)) {
    Add-Content -Path $profilePath -Value ""
    Add-Content -Path $profilePath -Value "# 快速切换到鸿蒙项目并启动 DevEco Code"
    Add-Content -Path $profilePath -Value "function hcd(`$projectName) {"
    Add-Content -Path $profilePath -Value "    `$projectPath = Join-Path '$harmonyHome' `$projectName"
    Add-Content -Path $profilePath -Value "    if (Test-Path `$projectPath) {"
    Add-Content -Path $profilePath -Value "        Set-Location `$projectPath"
    Add-Content -Path $profilePath -Value "        deveco"
    Add-Content -Path $profilePath -Value "    } else {"
    Add-Content -Path $profilePath -Value "        Write-Host '项目不存在: ' + `$projectPath -ForegroundColor Red"
    Add-Content -Path $profilePath -Value "        Write-Host '可用项目：'"
    Add-Content -Path $profilePath -Value "        Get-ChildItem '$harmonyHome' -Directory | ForEach-Object { Write-Host ('  - ' + `$_.Name) }"
    Add-Content -Path $profilePath -Value "    }"
    Add-Content -Path $profilePath -Value "}"
    Write-Ok "已添加 hcd 快速切换函数"
}

# ===== 完成 =====
Write-Host ""
Write-Host "╔═══════════════════════════════════════════════╗" -ForegroundColor Green
Write-Host "║   DevEco Code 环境配置已全部完成！              ║" -ForegroundColor Green
Write-Host "╚═══════════════════════════════════════════════╝" -ForegroundColor Green
Write-Host ""
Write-Host "后续步骤："
Write-Host "  1. 重启 PowerShell 使配置生效"
Write-Host "  2. 进入项目目录：cd $harmonyHome\YourApp"
Write-Host "  3. 启动 DevEco Code：deveco（或快捷命令 dc）" -ForegroundColor Cyan
Write-Host "  4. 首次使用需登录华为开发者账号"
Write-Host ""
Write-Host "快捷命令一览："
Write-Host "  dc   → deveco（启动）"
Write-Host "  dcu  → deveco upgrade（升级）"
Write-Host "  dcs  → deveco status（状态）"
Write-Host "  hcd  → 快速切换项目并启动"
Write-Host ""
Write-Host "遇到问题？运行 deveco --help 或在会话中执行 /doctor"
Write-Host ""

学习资料与推荐资源

一、官方核心资源

资源名称	链接地址	说明
华为开发者联盟	https://developer.huawei.com/consumer/cn/	账号注册、实名认证、应用发布管理
HarmonyOS 官方文档	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides	最权威的 ArkTS、Stage 模型、API 参考
DevEco Studio 下载	https://developer.huawei.com/consumer/cn/deveco-studio/	官方 IDE（注意区分 Intel/Arm/Windows）
ArkTS 语言规范	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkts-basic-syntax	ArkTS 语法特性完整说明
声明式 UI 开发指南	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/arkui-overview	ArkUI 组件和布局系统文档
Stage 模型开发指南	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/ability-model	Stage 模型架构详解
万能卡片开发指南	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/widget-overview	桌面卡片开发完整指南
Hvigor 构建指南	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hvigor-overview	Hvigor 构建系统使用文档
ohpm 包管理文档	https://ohpm.openharmony.cn/	ohpm 官方仓库和使用文档
HarmonyOS 设计规范	https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/design-overview	官方 UI/UX 设计规范
应用上架指南	https://developer.huawei.com/consumer/cn/doc/app/agc-help-overview	AGC 应用管理与上架
华为开发者论坛	https://developer.huawei.com/consumer/cn/forum/	技术问答与社区交流

二、推荐学习路径

入门阶段（1-2 周）

序号	学习内容	资源	目标
1	ArkTS 基础语法	官方文档 + 代码实验室	掌握类型系统、接口、装饰器
2	声明式 UI 基础	官方指南 + 示例项目	能独立创建简单页面
3	DevEco Studio 使用	官方教程 + YouTube/B站视频	熟悉 IDE 操作
4	DevEco Code 基础	本文档 + 实际操作	能使用 AI 生成简单代码

进阶阶段（2-4 周）

序号	学习内容	资源	目标
5	Stage 模型深入	官方文档 + 源码分析	理解 Ability 生命周期
6	状态管理深入	装饰器对比文档	正确使用各种装饰器
7	网络与数据持久化	API 参考 + 实战项目	实现完整 CRUD 应用
8	万能卡片开发	官方指南	实现桌面卡片功能

高级阶段（1-2 个月）

序号	学习内容	资源	目标
9	性能优化	Profiler 文档 + 最佳实践	掌握内存和渲染优化
10	跨端适配	响应式布局指南	手机/平板/车机多端适配
11	HAR/HSP 模块化	官方文档	构建可复用组件库
12	CI/CD 自动化	DevEco Cloud + 自定义脚本	实现自动化构建发布
13	DevEco Code 高级用法	MCP 配置 + 自定义提示词	最大化 AI 辅助效率

三、社区与交流平台

平台	链接	说明
华为开发者论坛	https://developer.huawei.com/consumer/cn/forum/	官方技术论坛，华为工程师答疑
OpenHarmony Gitee	https://gitee.com/openharmony	开源鸿蒙源码仓库
HarmonyOS 知乎专栏	知乎搜索 "HarmonyOS"	技术文章和经验分享
B站鸿蒙教程	B站搜索 "HarmonyOS 教程"	视频教程（推荐华为官方频道）
掘金鸿蒙专区	https://juejin.cn/tag/HarmonyOS	开发者实战文章
OpenCode 开源项目	https://github.com/nicepkg/opencode	DevEco Code 的开源基座
Stack Overflow	https://stackoverflow.com/questions/tagged/harmonyos	国际技术问答社区
GitHub HarmonyOS	https://github.com/topics/harmonyos	开源鸿蒙项目和示例代码

四、推荐书籍

书名	作者	出版信息	适合阶段
《鸿蒙应用开发实战》	华为技术团队	电子工业出版社	入门 → 进阶
《ArkTS 编程语言详解》	社区编撰	华为开发者文档	入门
《HarmonyOS 移动应用开发（微课版）》	高校教材编委会	人民邮电出版社	高校教学
《TypeScript 编程》	Boris Cherny	O'Reilly	ArkTS 基础（ArkTS 是 TS 超集）
《声明式 UI 编程范式》	华为 ARK 团队	华为内部资料	进阶

五、实用工具推荐

工具	平台	用途	获取方式
Postman / Insomnia	双平台	API 接口测试与调试	官网下载
Figma / 即时设计	网页端	UI 设计稿查看与标注	网页访问
JSON Viewer Pro	浏览器插件	JSON 数据格式化查看	Chrome 商店
Charles / Proxyman	MacOS / 双平台	网络抓包与 API 调试	官网下载
Responsively App	双平台	多设备响应式预览	GitHub 开源
MarkText	双平台	Markdown 编辑器（写文档）	GitHub 开源
Snipaste	双平台	截图与贴图工具	官网下载
Notion / Obsidian	双平台	技术笔记与知识管理	官网下载

六、DevEco Code 高效使用的 10 条黄金法则

编号	法则	详细说明
1	先描述再动手	在与 AI 对话前，先用自然语言梳理清楚需求，越具体越好
2	善用 /compact	长对话中定期压缩上下文，保持 AI 响应质量
3	提供错误上下文	将完整的编译错误/运行异常粘贴给 AI，不要只描述"报错了"
4	分步执行复杂任务	将大需求拆分为多个小任务，逐步让 AI 完成，质量更高
5	审查 AI 输出	永远审查 AI 生成的代码，不要盲目信任。特别是安全相关逻辑
6	维护 .deveco-rules.md	让 AI 理解你的项目规范和代码风格，生成更一致的代码
7	选择合适的模型	日常用 GLM-5.1，复杂代码用 DeepSeek Coder，保密项目用 Ollama
8	使用 /undo 回退	AI 的修改不满意时，用 /undo 快速回退，手动调整后再继续
9	版本控制一切	在让 AI 大规模修改前，确保代码已 Git 提交，方便对比和回退
10	持续学习新特性	关注 HarmonyOS 和 DevEco Code 的更新日志，及时使用新功能

最终总结

本指南从双平台的独特视角出发，完整覆盖了 DevEco Code 在 Windows 和 MacOS 上的全部安装、配置、使用、维护和卸载流程。总计超过 35000 字的详实内容，包含以下核心板块：

板块	章节	核心内容
概念理解	第一章	DevEco Code 的定位、架构、与 DevEco Studio/CodeGenie 的区别
环境搭建	第二、三章	Xcode CLT、fnm/nvm、Node.js、npm 镜像、权限配置
安装部署	第四章	npm 全局安装、Apple Silicon 注意事项、离线方案
首次使用	第五章	OAuth 登录、初始化、凭证安全
模型配置	第六章	GLM-5.1 免费模型 + DeepSeek/通义/智谱/Moonshot/Ollama 全接入
核心功能	第七章	代码生成、UI 生成、卡片开发、Bug 修复、重构优化
命令速查	第八章	斜杠命令大全、双平台快捷键对照
实战案例	第九章	七大完整实战案例（含详细代码注释）
协同工作	第十章	DevEco Studio 双工具协同、hdc 调试、Git 管理
高级定制	第十一章	记忆文件、MCP 扩展、终端美化、自动化脚本
维护管理	第十二、十三章	版本升级、数据备份、完整卸载
问题解决	第十四章	安装/登录/模型/平台特有/性能等全场景 FAQ
附录资源	附录 A-G	命令表、配置表、终端命令、API 对照、装饰器速查、一键脚本

核心建议回顾：

使用 fnm 管理 Node.js：双平台统一，避免权限问题，版本切换方便
选择优质终端：MacOS 用 iTerm2，Windows 用 Windows Terminal
为每个项目创建 .deveco-rules.md：让 AI 理解你的项目规范
善用 /compact 管理上下文：保持 AI 高效响应
双工具协同：DevEco Code + DevEco Studio 发挥各自优势
持续学习：HarmonyOS 和 DevEco Code 正在快速迭代

"未来属于那些善于与 AI 协作的开发者。"

在 HarmonyOS NEXT 生态的黄金发展期，DevEco Code 为双平台开发者提供了一个强大的"AI 编程搭档"。善用这份指南中的每一个技巧，让 AI 成为你开发效率的倍增器，在鸿蒙生态的浪潮中抢占先机。

本文档基于 DevEco Code v1.0.0 版本及 HDC 2026 后的公开信息编写。由于软件处于快速迭代期，部分命令和配置可能发生变化，请以华为官方最新文档为准。文中涉及的第三方服务定价及政策以各服务商官网为准。

最后更新：2026 年 7 月

DevEco Code 在 Windows/MacOS 双系统上的完整使用指南

DevEco Code 在 Windows/MacOS 双系统上的完整使用指南

摘要

目录

一、DevEco Code 概述与双平台适配

1.1 什么是 DevEco Code

1.2 DevEco Code 的技术架构深度剖析

1.3 Windows 与 MacOS 平台的独特优势与挑战对比

Windows 平台

MacOS 平台

双平台对比表

1.4 DevEco Code 与 DevEco Studio、CodeGenie 的区别

1.5 核心能力总览

1.6 适用场景与目标用户

二、环境准备与前置条件

2.1 操作系统要求

Windows 系统要求

MacOS 系统要求

2.2 硬件配置建议

2.3 必备软件清单

2.4 华为开发者账号准备

2.5 Xcode Command Line Tools 安装（仅 MacOS）

2.6 网络环境准备

三、安装 Node.js 与 npm 环境

3.1 方案一：通过官方安装包安装

Windows：通过 MSI 安装包安装（新手推荐）

MacOS：通过 Homebrew 安装

3.2 方案二：通过 nvm/nvm-windows 管理多版本 Node.js

Windows：nvm-windows

MacOS：nvm

3.3 方案三：通过 fnm 管理 Node.js（双平台推荐）

Windows 安装 fnm

MacOS 安装 fnm

3.4 验证 Node.js 与 npm 安装

3.5 配置 npm 国内镜像源加速

3.6 解决 PowerShell 执行策略限制（Windows 核心避坑指南）

3.7 解决全局安装权限与路径问题

Windows 解决方案

MacOS 解决方案

3.8 Shell 配置文件详解

MacOS：zsh vs bash

Windows：PowerShell Profile

3.9 Node.js 版本选择策略

四、安装 DevEco Code

4.1 npm 全局安装命令详解

4.2 安装过程全记录与日志分析

4.3 验证安装成功

4.4 Apple Silicon 特殊注意事项（仅 MacOS）

4.5 安装失败常见原因与排查

4.6 离线安装方案（企业内网环境）

五、首次启动与登录配置

5.1 终端选择与启动方式

Windows 终端选择

MacOS 终端选择

5.2 数据库迁移与本地初始化

5.3 华为开发者账号 OAuth 登录流程

5.4 隐私政策与使用条款

5.5 登录状态管理与凭证安全

5.6 多账号切换策略

六、模型配置与第三方模型接入

6.1 内置免费模型 GLM-5.1 详解

6.2 使用 /model 命令切换模型

6.3 接入 DeepSeek API 完整教程

6.4 接入通义千问（阿里云百炼）

6.5 接入智谱 GLM-4 Plus

6.6 接入月之暗面 Moonshot

6.7 接入本地 Ollama 模型

6.8 配置文件 config.json 深度解析

6.9 模型性能对比与选择建议

七、DevEco Code 核心功能详解

7.1 智能代码生成与上下文补全

7.2 页面 UI 生成（声明式 ArkUI）

7.3 万能卡片（Widget）生成

7.4 代码重构与架构优化

7.5 Bug 诊断与自动修复

7.6 工程辅助与构建管理（Hvigor & ohpm）

7.7 知识问答与文档精准查询

7.8 多文件协同编辑与 Diff 预览

八、斜杠命令与快捷键大全

8.1 高频必备命令