DevEco Code 分析报告：与 OpenCode 的差异与增强

项目地址：https://gitcode.com/openharmony-sig/deveco-code
上游基线：OpenCode v1.15.5（记录在 .agents/upstream-sync/BASELINE.md）
本仓库是 OpenCode（ https://github.com/anomalyco/opencode ）的深度定制分支

概述
品牌标识与 CLI 重命名
HarmonyOS 开发工具（核心增强）
HarmonyOS 内置技能包
三模式 Agent 系统（Build/Plan/Goal）
DevEco Studio 集成
华为账号认证体系
构建与平台分发
默认技能提取机制
Claude 配置默认禁用
文档校验工具
上游同步体系
未被改动的 OpenCode 能力
总结：DevEco Code 能力增强全景

1. 概述

DevEco Code 是华为面向 HarmonyOS 开发场景的 AI Agent 终端工具，基于开源项目 OpenCode 扩展开发。它保留了 OpenCode 的核心架构——终端交互 TUI、Effect 运行时、Provider/MCP/Skill/Plugin 扩展体系、AI SDK 等——并在其之上增加了 HarmonyOS/ArkTS/ArkUI 领域所需的完整工具链、知识库和开发工作流支持。

对比策略

DevEco Code 采用了 fork + 上游同步 策略：基于 OpenCode 创建分支，每次上游发布新版本时通过 git merge --no-ff 方式合并，将冲突按优先级解决（本地自定义功能优先、上游改动次之、配置合并），最后 squash 为单父提交。

2. 品牌标识与 CLI 重命名

2.1 核心映射表

项目	OpenCode（上游）	DevEco Code	位置
包名	`opencode`	`deveco`	`packages/opencode/package.json`
CLI 命令	`opencode`	`deveco`	同上 `bin` 字段
数据库文件	`opencode.db`	`deveco.db`	`packages/opencode/src/storage/db.ts`
配置搜索	`/.opencode/`	`/.deveco/`	`config/agent.ts`, `config/command.ts`
环境变量前缀	`OPENCODE_*`	`DEVECO_*`	全局 env var
XDG 基础目录	`opencode`	`deveco`	`packages/core/src/global.ts`
macOS 托管配置	`ai.opencode.managed`	`ai.deveco.managed`	`config/managed.ts`
macOS 托管路径	`/Library/Application Support/opencode`	`/Library/Application Support/deveco`	同上
平台包名	`opencode-${platform}-${arch}`	`@deveco/deveco-code-${platform}-${arch}`	`postinstall.mjs`
User-Agent	`opencode/${version}`	`deveco/${version}`	`session/llm.ts`

2.2 保留 opencode 标识的部分（不改动）

第三方 API User-Agent（认证依赖）：GitHub Copilot、DigitalOcean、Cloudflare、OpenRouter 等
Provider HTTP Headers（外部 API 校验）：X-Title, Referer 等
内部 Effect service tags：@opencode/Session、@opencode/Storage 等
Import 路径：@opencode-ai/* workspace 包名
Schema URL：https://opencode.ai/config.json
GitHub Actions：opencode.yml
Nix 包：opencode.nix
Docker 镜像：ghcr.io/anomalyco/opencode

3. HarmonyOS 开发工具（核心增强）

DevEco Code 在 OpenCode 基础上注入了 HarmonyOS 专属工具，实现在两个层面：TypeScript 工具层（通过 tool/registry.ts 注册为内置工具）和 NAPI Bridge 动态工具层（通过 @deveco-codegenie/mcp-bridge 原生插件 + plugin/harmony-napi-dynamic-tools.ts 插件动态注册，工具定义见 tool/lib/emulator_tools.json）。

3.1 工具清单

TypeScript 工具（registry.ts 内置注册）

工具 ID	源文件	功能	依赖
`hdc_log`	`tool/hdc_log.ts`	HDC 设备日志收集/清理/设备列表	DevEco Studio (`DEVECO_HOME`)
`switch_cwd`	`tool/switch-cwd.ts`	切换构建项目路径（检测 HarmonyOS 工程根目录）	无
`arkts_knowledge_search`	`tool/oh_knowledge.ts`	HarmonyOS 官方知识库搜索	华为 OAuth 认证
`check_ets_files`	`tool/arkts_check.ts`	ArkTS 静态语法检查	DevEco Studio Node.js

NAPI Bridge 动态工具（通过 `@deveco-codegenie/mcp-bridge` 原生插件注册）

工具 ID	定义来源	功能	依赖
`build_project`	`emulator_tools.json`	Hvigor 编译构建（支持 build_mode/clean/module/product 参数）	DevEco Studio
`start_app`	`emulator_tools.json`	模拟器/真机运行应用（自动检测启动设备）	DevEco Studio + HDC
`verify_ui`	`emulator_tools.json`	UI 操作验证（自然语言描述测试用例→自动执行截图验证）	Qwen3-VL 多模态模型
`save_ui_screenshot`	`emulator_tools.json`	根据校验 ID 保存每一步截图	依赖 verify_ui 返回的 ID
`get_ui_verification_log`	`emulator_tools.json`	根据校验 ID 获取设备运行日志	依赖 verify_ui 返回的 ID
`check_ets_files`	`emulator_tools.json`	（同上功能）ArkTS 静态语法检查的 NAPI 桥接版本	DevEco Studio

注：check_ets_files 在 TypeScript 和 NAPI Bridge 两层都有实现，NAPI 桥接版通过 @deveco-codegenie/mcp-bridge 原生模块执行。jscrash_report.ts 文件存在但未注册为 AI 可调用的工具，仅作为 arkts-runtime-fix 技能的内部脚本使用。

3.2 工具实现细节

`hdc_log` — HDC 设备工具

三种 action：collect（收集）、clear（清除）、list_devices（列出设备）
使用 hilog -x 获取日志流
支持 -t <device_id> 指定目标设备
通过 DEVECO_HOME 环境变量定位 DevEco Studio 中的 HDC 二进制
日志前缀过滤（默认 [VCODER_DEBUG]），最多返回 5000 行

`switch_cwd` — 项目切换

支持绝对路径和相对路径
检测目标是否为 HarmonyOS 工程根目录：通过 AppScope/app.json5 或 build-profile.json5 + oh-package.json5 两个条件判断
非 HarmonyOS 工程也能切换，但会提示
实现 setSessionCwd 持久化会话目录

`oh_knowledge` — HarmonyOS 知识搜索

调用华为知识库 API：https://cn.devecostudio.huawei.com/codeGenie/bigSearch
OAuth 门控：仅在用户通过 deveco OAuth 认证时注册到内置工具列表
OAuth 未认证用户看不到此工具
每次调用前需验证 token 有效性

`arkts_check` — ArkTS 语法检查

内置了完整的 ArkTS check 脚本（arkts-check.cjs），作为纯文本导入
运行时写入临时目录，用 DevEco Studio 内置的 Node.js 执行
输出 JSON 格式的诊断结果（file, line, column, severity, message, rule）
区分 error 和 warning

3.3 工具注册的 OAuth 门控逻辑

// 关键代码（registry.ts）
const authInfo = yield* auth.get("deveco").pipe(Effect.orElseSucceed(() => undefined))
const ohknowledgeEnabled = authInfo !== undefined && authInfo.type === "oauth"

// builtin 列表条件展开
tool.hdclog,       // 始终可用
tool.switchcwd,    // 始终可用
tool.arktscheck,   // 始终可用
...(ohknowledgeEnabled ? [tool.ohknowledge] : []),  // 仅 OAuth 用户

4. HarmonyOS 内置技能包

DevEco Code 打包了 5 个 HarmonyOS 领域的内置 skill（位于 packages/opencode/resources/skills/）：

技能名称	目录	功能范围	核心参考文件
arkui-knowledge	`arkui-knowledge/`	ArkUI 组件、布局、状态管理、导航、动画、渲染控制	`references/component-cookbook.md`, `references/common-mistakes.md`, `references/api-guardrails.md`, `references/ui-quality-checklist.md`
arkts-grammar-standards	`arkts-grammar-standards/`	ArkTS 语法限制（与 TypeScript 的差异）、装饰器规则	`references/basic-syntax.md`, `references/restrictions.md`, `references/ts-diff.md`
arkts-error-fixes	`arkts-error-fixes/`	30+ 常见 ArkTS 编译错误修复，每个错误有独立示例 .ets 文件	`assets/` 下 30 个 .ets 示例；`reference/` 下 30+ 篇修复指南
arkts-runtime-fix	`arkts-runtime-fix/`	运行时崩溃排查、JS Crash 日志解析、faultlogger 探测	`scripts/` 下 hilog 收集、jscrash 解析、faultlogger 探测脚本
deveco-create-project	`deveco-create-project/`	新 HarmonyOS 工程模板生成、SDK 路径检测	`scripts/copy-template.mjs`, `scripts/detect-sdk.mjs`；`application/` 完整工程模板

4.1 arkts-error-fixes 覆盖的错误模式

覆盖 30+ 种常见编译错误，例如：AnyTypeError、AppStorageError、ArrowFunctionConversionError、DecoratorStateError、ESObjectTypeError、FunctionReturnTypeError、ObjectLiteralTypeError、PossiblyNullError、ResourceConversionError、StandaloneFunctionError、UnusedVariableWarning、UtilityTypeError 等。每个错误类型有独立的 .ets 示例文件 + 修复指南 reference。

4.2 arkts-runtime-fix 的调试工具链

提供端到端运行时问题排查脚本链：

collect-hilog.mjs/ts — 从设备收集日志
fetch-faultlog.mjs/ts — 拉取 faultlogger 记录
parse-jscrash-log.mjs/ts — 解析 JS Crash 日志
probe-faultlogger.mjs/ts — 探测 faultlogger 状态
jscrash-report.mjs/ts — 报告生成

5. 三模式 Agent 系统（Build/Plan/Goal）

DevEco Code 在 OpenCode 的 Agent 基础上，实现了三个工作模式，可通过 Tab 键切换：

5.1 Agent 模式对比

模式	系统提示词	适用场景	权限特点
Build	`build.txt`	工程生成、代码生成、配置修正、测试执行、推包运行	`plan_enter: "ask"`, `plan_write: "deny"`
Plan	`plan.txt`	需求拆解、技术方案、测试规划、文档生成	`plan_exit: "ask"`, `plan_write: "allow"`, `edit: "deny"`，9 个 HarmonyOS 工具 deny
Goal	`goal.txt`	SDD 五阶段：需求→设计→实现→构建→验证	端到端全权限

5.2 Plan 工具组

OpenCode 上游只有 plan_exit，DevEco Code 新增了 plan_enter 和 plan_write：

plan_enter：从 Build 模式切换到 Plan 模式，不依赖 experimentalPlanMode flag
plan_write：写入计划内容到 .hermes/plans/ 目录（Plan 模式下 allow，Build 模式下 deny）
plan_exit：计划完成，询问是否切换回 Build 模式实现

5.3 Plan 工具门控

上游 v1.15.0 引入了 experimentalPlanMode flag 控制 plan 工具注册，DevEco Code 去除了此条件——Plan 模式是已发布的核心功能，不允许被视为"实验性"：

// DevEco Code（正确）
...(flags.client === "cli" ? [tool.plan, tool.planwrite, tool.planenter] : [])

// 上游 OpenCode（错误——已被 deveco 移除）
...(flags.experimentalPlanMode && flags.client === "cli" ? ...)

5.4 Agent 权限配置

packages/opencode/src/agent/agent.ts 中自定义权限规则，在每次上游同步后会丢失并被重新添加：

Build agent：plan_enter: "ask", plan_write: "deny"
Plan agent：plan_exit: "ask", plan_write: "allow", edit: "deny"，
HarmonyOS 工具 deny：bash, build_project, check_ets_files, perform_ui_action, get_app_ui_tree, start_app, hdc_log, switch_cwd, arkts_knowledge_search

6. DevEco Studio 集成

6.1 NAPI Bridge 架构

packages/opencode/src/tool/lib/harmony_napi.ts 通过 @deveco-codegenie/mcp-bridge 原生 Node.js addon 与 DevEco Studio 的底层工具链交互。这个 NAPI 桥接层使 DevEco Code 能直接调用 DevEco Studio 的原生能力（Hvigor 编译、设备管理、UI 验证等），避免通过 shell 命令间接拼装。

组件	作用	源码位置
`harmony_napi.ts`	NAPI bridge 加载、初始化、调用包装	`tool/lib/harmony_napi.ts`
`harmony-napi-dynamic-tools.ts`	Plugin 注册、参数校验、MCP 路由	`plugin/harmony-napi-dynamic-tools.ts`
`emulator_tools.json`	5 个工具的定义元数据（build_project, start_app, verify_ui 等）	`tool/lib/emulator_tools.json`

6.2 环境检测（`tool/lib/env.ts`）

完整的 DevEco Studio 安装检测逻辑：

从 DEVECO_HOME 环境变量读取
平台默认搜索路径：
- macOS → /Applications/DevEco-Studio.app
- Windows → D:\\DevEco Studio / C:\\Program Files\\Huawei\\DevEco Studio / C:\\Program Files\\DevEco Studio / ~\\DevEco Studio
- Linux → ~/devecostudio / ~/DevEco-Studio（路径检测存在但暂不支持 Linux 平台）
从 product-info.json 解析版本号，要求 >= 6.0.0
缓存已检测到的路径到 ${state}/deveco-home.json

6.3 工具链路径

路径函数	定位内容	用途
`nodePath(home)`	`tools/node/bin/node` / `tools/node/node.exe`	运行 ArkTS check 脚本
`hvigorPath(home)`	`tools/hvigor/bin/hvigorw.js`	编译构建
`sdkPath(home)`	`sdk/`	SDK 路径
`hdcPath(home)`	`sdk/default/openharmony/toolchains/hdc`	设备调试

6.4 构建环境（`buildEnv()`）

合并 DevEco Studio 工具链到 PATH：

tools/node/bin
tools/ohpm/bin
tools/hvigor/bin

7. 华为账号认证体系

7.1 认证流程

OAuth 认证通过华为账号登录（plugin/deveco.ts）
认证信息加密存储于 auth.json，使用 LocalCrypto 加解密
OAuth token 管理（access token / refresh token）
ACCESS_TOKEN_EXPIRES_MS 控制 token 刷新周期

7.2 隐私协议

deveco-agreement.ts — 与华为 TMS 后台交互，签署隐私协议
deveco-legal.ts — 解析协议配置
deveco-links.ts — 华为法律链接
首次启动引导用户签署 AI 使用条款和隐私政策

7.3 Onboarding UI

cli/cmd/tui/component/deveco-onboarding.tsx — 完整的首次引导 TUI 组件：

步骤流：privacy → entry → auth → providers → key
协议签署状态检查
网络异常时本地缓存 pending，下次启动重试

8. 构建与平台分发

8.1 平台包

参考 packages/opencode/package.json 的依赖：

包名	平台
`@deveco-codegenie/mcp-bridge`	通用（主包）
`@deveco-codegenie/mcp-bridge-darwin-arm64`	macOS Apple Silicon
`@deveco-codegenie/mcp-bridge-darwin-x64`	macOS Intel
`@deveco-codegenie/mcp-bridge-win32-x64`	Windows x64

8.2 Vendor 拷贝

postinstall.mjs 在安装后从平台包中拷贝 vendor/ 目录到安装目录，详见 copyVendor() 函数。这用于部署 HarmonyOS 原生工具二进制。

8.3 安装方式

仅通过 npm registry 分发（不支持 brew/choco/scoop/curl）：

npm install -g @deveco/deveco-code

9. 默认技能提取机制

新增 packages/opencode/src/skill/defaults.ts 模块：

DEVECO_DEFAULT_SKILLS 在构建时通过 esbuild define 注入
首次运行时将嵌入的 skills 提取到 {Global.Path.data}/skills/
版本比较（InstallationVersion）决定是否需要重新提取
用户安装的 skill（在 config 目录中）会被备份保留，内置 skill 会被覆盖

10. Claude 配置默认禁用

在 packages/opencode/src/effect/runtime-flags.ts 中：

// DevEco Code 使用 boolTrue（默认 true），上游使用 bool（默认 false）
const boolTrue = Config.boolean(name).pipe(Config.withDefault(true))

disableClaudeCodePrompt    // DEVECO_DISABLE_CLAUDE_CODE → 默认 true
disableClaudeCodeSkills    // DEVECO_DISABLE_CLAUDE_CODE_SKILLS → 默认 true

效果：

默认不扫描用户 .claude/skills/ 目录
默认不注入 Claude prompt 配置
移除了上游内置的 customize-opencode skill（DevEco Code 中不需要）

11. 文档校验工具

packages/opencode/src/tool/document-validation/ 模块提供结构化文档校验能力：

组件	功能
`document-validate-tool.ts`	文档校验入口工具
`markdown-parser.ts`	Markdown 解析
`section-normalizer.ts`	章节结构归一化
`config.ts`	校验规则配置
`models.ts`	数据模型定义

12. 上游同步体系

DevEco Code 的持续同步能力通过 .agents/upstream-sync/ 目录维护：

12.1 文件结构

文件	作用
`BASELINE.md`	当前上游版本（如 `v1.15.5`）
`LESSONS.md`	版本特定的同步历史教训
`SKILL.md`	完整的同步工作流（9 步流程）
`references/brand-mapping.md`	品牌标识映射表（什么改什么不改）
`references/custom-features-checklist.md`	自定义功能校验清单（12 项）
`references/pitfalls.md`	已知陷阱（Critical/Moderate/Advisory 三级）

12.2 同步策略

从上游 release tag 同步（非分支）
使用 git replace --graft 修复历史嫁接
git merge --no-ff 执行合并
squash 为单父提交保持历史干净
同步后运行 review subagent 做全面审计

13. 未被改动的 OpenCode 能力

DevEco Code 完整保留了 OpenCode 的以下核心能力，未做改动：

TUI 交互系统 — OpenTUI 驱动的终端 UI（路由、对话框、提示符、主题系统）
Effect 运行时 — Effect TS 的结构化并发、依赖注入、错误处理
Provider 系统 — 所有第三方 AI 模型提供商（OpenAI、Anthropic、Google、OpenRouter 等）
MCP 协议 — Model Context Protocol 服务器集成
Plugin 系统 — 插件注册、生命周期、插槽渲染
Skill 系统 — 技能加载、描述、发现（除了 Claude 禁用和 customize-opencode 移除）
AI SDK — @opencode-ai/sdk 客户端 SDK
核心工具 — shell, read, write, edit, grep, glob, patch, task, question, todo, web_search, web_fetch, spec_write 等
会话管理 — 会话持久化、消息版本、历史记录
配置系统 — JSON schema、配置文件层级、环境变量覆盖
LSP 集成 — Language Server Protocol 支持
Web App — SolidJS 前端 Web 界面
云服务 — SST/AWS 基础设施、Console SaaS

14. 总结：DevEco Code 能力增强全景

新增工具（4 个 TypeScript + 5 个 NAPI Bridge 动态工具）

工具	层级	核心价值	OpenCode 是否具备
`hdc_log`	TypeScript	设备日志	否
`switch_cwd`	TypeScript	项目路径切换	否
`oh_knowledge`	TypeScript	官方知识搜索（OAuth 门控）	否
`check_ets_files`	TypeScript + NAPI	ArkTS 静态检查	否
`build_project`	NAPI Bridge	Hvigor 编译构建	否
`start_app`	NAPI Bridge	设备运行	否
`verify_ui`	NAPI Bridge	UI 视觉验证	否
`save_ui_screenshot`	NAPI Bridge	校验截图保存	否
`get_ui_verification_log`	NAPI Bridge	运行日志检索	否

新增技能包（5 个）

arkui-knowledge（ArkUI 组件知识）
arkts-grammar-standards（语法标准）
arkts-error-fixes（30+ 编译错误修复指南）
arkts-runtime-fix（运行时调试工具链）
deveco-create-project（工程模板生成）

架构级增强

三模式 Agent 系统（Build/Plan/Goal）替代单一对话模式
华为账号 OAuth 认证 + 隐私协议签署
DevEco Studio 自动检测与 NAPI Bridge 原生工具链集成
上游同步体系保障可持续演进
默认技能内置 + 版本化提取

技术债评估

维度	评价
代码质量	自定义代码遵循 OpenCode 的 Effect TS 风格、Schema 定义、工具注册模式，代码质量高
维护成本	上游同步体系完善（brand-mapping + checklist + pitfalls），但每次合并需手工处理 8+ 个关键冲突点
测试覆盖	存在 `deveco-builtin-tools.test.ts` 和 `env.test.ts`，但自定义工具（hdc_log, oh_knowledge, jscrash_report）缺乏单元测试
演进风险	LLM 模块（`session/llm.ts`）是上游高频重构区域，每次同步都有高冲突概率

posted @ 2026-06-17 16:59 getmoon 阅读(71) 评论(0) 收藏举报

刷新页面返回顶部

get_moon