面向 HarmonyOS 开发场景的 AI Agent 工具 · Windows 桌面安装版
English · 简体中文
本仓库是 DevEco Code 的个人定制版本：基于 opencode 构建的 Windows 桌面安装版（便携式，非 npm CLI 版），在原版基础上新增了手机配对系统、任务进度可视化、环境自检 等一系列体验增强，适合日常本地开发使用。
官方原版（npm CLI 版）请见文末「官方项目」。
| 能力 | 说明 |
|---|---|
| 📊 任务进度可视化 | TRAE Work 风格任务面板，将「待办」与「上下文占用」合并为单一面板，实时展示任务进度、状态流转与上下文分布，开发过程一目了然 |
| 📱 手机配对系统 | 桌面端生成本地二维码，鸿蒙手机端（Mate 80 Pro 等）扫码即可配对；配对后可在手机上查看电脑端会话、收发消息 |
| 🔍 环境自检（env-doctor） | 启动时自动检测开发环境（DevEco Studio / HDC / Hvigor / Node 等），给出缺失项与修复指引 |
| 🎨 UI 精修 | 任务面板采用玻璃拟态卡片、语义化配色、精确字重排版，明暗主题自适应 |
| 🛠 体验修复 | 修复待办状态不同步、上下文恒显示 0%、模型图片不可见、手机端全屏布局遮挡等多项问题 |
在 AI Agent 工具中，任务过程往往是黑盒：用户看不到 Agent 正在做什么、做到了哪一步、上下文还剩多少。本项目将「任务面板」从辅助信息提升为主交互视图，让 Agent 的工作过程可视化、可追踪、可掌控。
- 单一面板合并视图：将原本分散的「待办列表」与「上下文占用」合并为同一面板，左侧展示当前任务流，右侧展示上下文消耗情况，避免在多个面板间来回切换。
- 实时任务进度：任务以卡片形式列出，状态以颜色与图标语义化区分（待开始 / 进行中 / 已完成 / 已阻塞），点击可展开子任务树。
- 上下文占用可视化：以进度条 + 百分比形式展示当前会话上下文使用率，并对接近上限时给出红色预警，避免突发截断。
- 玻璃拟态卡片：面板整体采用 frosted glass 效果，配合语义化配色与精确字重排版，明暗主题自动适配，长时间观看不易疲劳。
- 状态同步修复：修复了原版「待办状态不同步」「上下文恒显示 0%」等问题，面板数据与真实执行状态保持一致。
- 长会话任务管理：清晰看到每一步 Agent 的执行结果与待办剩余项
- 多任务并行：快速切换不同任务上下文，避免混淆
- 上下文预算管理：在逼近模型上下文上限前主动拆分会话
将「电脑端 AI Agent」延伸到「口袋里的鸿蒙手机」。配对完成后，可在手机端实时查看电脑端会话、收发消息，离开工位也能继续跟进 Agent 的工作。
- 桌面端生成二维码：在 DevEco Code 设置面板中开启手机配对，桌面端自动生成包含本地配对信息的二维码。
- 鸿蒙手机扫码配对：使用搭载 HarmonyOS 的手机（已验证 Mate 80 Pro 等）扫描二维码，完成设备配对。
- 手机端查看与交互：配对后，手机端可：
- 实时查看电脑端会话内容
- 在手机上向 Agent 发送新消息
- 接收 Agent 的回复与任务完成通知
- 配对协议详见 REMOTE-BRIDGE-PROTOCOL.md
- 仅在本地局域网内通信，不经过外部服务器，数据隐私可控
- 鸿蒙手机端应用源码位于独立仓库
deveco-code-mobile
- 修复手机端全屏布局被状态栏 / 导航栏遮挡问题
- 修复模型图片在手机端不可见问题
- 优化手机端长会话滚动性能
启动时自动扫描本地开发环境，给出缺失项清单与修复指引，避免因环境问题导致构建、调试失败。
| 检测项 | 说明 |
|---|---|
| DevEco Studio | 检测安装路径、版本号，校验是否 ≥ 6.1 |
| HDC | HarmonyOS Device Connector，用于真机调试与日志收集 |
| Hvigor | HarmonyOS 构建工具链 |
| Node.js | 校验版本是否 ≥ 22 |
DEVECO_HOME |
环境变量是否已正确配置 |
✓ Node.js v22.11.0
✓ DevEco Studio 6.1.0
✗ HDC 未检测到，请检查 DevEco Studio 安装
✗ DEVECO_HOME 未配置，请设置指向 DevEco Studio 安装目录
- 玻璃拟态卡片：frosted glass + 模糊背景，层级清晰
- 语义化配色：成功 / 警告 / 错误 / 信息四态配色统一
- 精确字重排版：标题、正文、辅助文字字重分明
- 明暗主题自适应：跟随系统主题自动切换
| # | 问题 | 修复 |
|---|---|---|
| 1 | 待办状态不同步 | 重构任务状态同步机制，面板与执行状态强一致 |
| 2 | 上下文恒显示 0% | 修复上下文计算逻辑，实时反映真实占用 |
| 3 | 模型图片不可见 | 修复图片资源加载路径 |
| 4 | 手机端全屏布局遮挡 | 适配安全区，状态栏 / 导航栏不再遮挡内容 |
| 5 | 长会话滚动卡顿 | 虚拟列表优化，万条消息流畅滚动 |
# 修改源码后重新编译并覆盖到便携版安装目录（E:\finish\DevEco Code）
cd packages/desktop && bun run install:local配对协议说明见 REMOTE-BRIDGE-PROTOCOL.md。
当前个人增强版的跨平台支持情况：
| 平台 | 状态 | 说明 |
|---|---|---|
| Windows | ✅ 已发布 | 当前主力维护版本 |
| macOS | ✅ 已支持 | 复用 Electron 跨平台架构，原生模块（node-pty / @parcel/watcher）已为 darwin-arm64 与 darwin-x64 准备；环境自检已适配 /Applications/DevEco-Studio.app/Contents 路径 |
| Linux | 🚧 开发中 | 基于 Electron 跨平台方案，适配主流发行版（Ubuntu / Debian / Arch 等） |
- 打包：
electron-builder配置mac.target: ["dmg", "zip"]，已开启hardenedRuntime与notarize，entitlements 见 resources/entitlements.plist - 原生模块：
@lydell/node-pty-darwin-arm64/@lydell/node-pty-darwin-x64/@parcel/watcher-darwin-*均在 packages/desktop/package.json 的optionalDependencies中 - 窗口：windows.ts 已为 darwin 启用
titleBarStyle: "hidden"+trafficLightPosition，与系统红绿灯按钮对齐 - 菜单：menu.ts 已为 darwin 注册原生菜单
- 环境自检：env-doctor 已适配 macOS DevEco Studio 安装路径（
.app/Contents），DEVECO_HOME指向Contents目录 - 本地开发：
bun run install:local在 macOS 上会覆盖到/Applications/DevEco Code.app/Contents/Resources/app/out/，并通过osascript优雅退出已运行实例
cd packages/desktop
bun run build
bun run package:mac # 产出 dist/opencode-desktop-mac-${arch}.dmg 与 .zip
⚠️ macOS 公证（notarize）需要 Apple 开发者证书与 App Store Connect API Key，配置以下环境变量后才会执行公证步骤：
CSC_LINK/CSC_KEY_PASSWORD：p12 证书与密码APPLE_API_KEY/APPLE_API_KEY_ID/APPLE_API_ISSUER：API Key 文件路径与凭据
推 tag 或手动触发 .github/workflows/build-mac.yml 即可在 GitHub 托管的 macOS runner 上构建 arm64 + x64 双架构 dmg，并自动上传到 Release。
# 触发自动构建（推 tag）
git tag v1.0.0
git push origin v1.0.0
# 或手动触发
# GitHub 仓库 → Actions → build-mac → Run workflow代码签名 / 公证为可选项，需在仓库 Settings → Secrets and variables → Actions 中配置：
- Variables：
APPLE_CODESIGN_ENABLED=true（启用开关） - Secrets：
APPLE_CERTIFICATE/APPLE_CERTIFICATE_PASSWORD/APPLE_API_KEY_ID/APPLE_API_ISSUER/APPLE_API_KEY_P8
未配置时 workflow 仍会产出未签名版本，用户首次打开需右键 → 打开。
- 跨平台框架：采用 Electron 作为桌面壳层，复用现有 Web 前端代码，最大化跨平台一致性
- 原生模块迁移：手机配对、环境自检等涉及系统调用的模块将针对各平台单独适配
- 鸿蒙生态约束：HarmonyOS 编译构建、模拟器与真机调试依赖 DevEco Studio，目前 DevEco Studio 仅提供 Windows 与 macOS 版本；Linux 版将聚焦「代码生成 / 代码审查 / 知识检索」等不依赖 DevEco Studio 的能力
Mac 版与 Linux 版的开发进度将在本仓库的 Issues 与 Projects 中跟踪，欢迎关注与反馈。
本仓库基于官方 DevEco Code 扩展开发。以下为官方原版（npm CLI 版）的相关信息：
- 官方仓库：openharmony-sig/deveco-code
- 官方文档：README (官方原版) · FAQ · OpenCode TUI 文档
- 官方安装：
npm install -g @deveco/deveco-code（NPM 包） - 官方支持平台：Windows x64 · macOS arm64 · macOS x64（暂不支持 Linux）
- 问题反馈：官方原版问题请到 GitCode Issue 反馈；本个人增强版的问题请在本仓库 Issue 反馈
DevEco Code 基于 OpenCode 扩展开发，但并非 OpenCode 团队出品，与 OpenCode 团队无任何附属或关联关系。
欢迎贡献！请在提交 Pull Request 前阅读 CONTRIBUTING.md。