企业官网建设流程全解析

• 开发工具
• CLI
• OpenHarmony
• MCP 服务
• 移动开发

deveco-cli（HarmonyOS 应用开发命令行工具）在仓库内为 AI 编码助手沉淀了一套标准化的代码变更/MR 审查工作流，本指南以 .agents/skills/deveco-code-review/SKILL.md 为核心，结合仓库源码与配套 Skill 展开讲解。读完本文，你将掌握在 deveco-cli 仓库中审查 CLI 与 MCP 变更时需要执行的完整检查清单——包括接口行为、职责归属、进程生命周期、边界安全、真实入口验证与回归证据的收集方法，并理解每一条规则背后的源码依据。

一、审查 Skill 在仓库开发工作流中的定位

deveco-cli 是一个 npm workspace 仓库，包含 4 个包：cli（发布为@deveco/deveco-cli）、docs-engine（私有，搜索/读取运行时）、docs-index-builder（私有，索引构建）、docs-zh（发布为@deveco/deveco-cli-knowledgebase）。仓库的常设规则（conventions、领域模块范式、环境变量、架构说明）统一沉淀在根目录 AGENTS.md 中，而开发工作流则按任务拆分为.agents/skills/下的多个 Skill：

从源码结构看，这套 Skill 体系与根 AGENTS.md 的分工是明确的：根 AGENTS.md 拥有常设仓库规则，各开发 Skill 只负责各自的工作流步骤。审查 Skill 的适用场景集中在四个方面：CLI 与 MCP 消费者（谁在调用命令与协议）、共享解析逻辑（JSON5 配置解析等）、外部进程生命周期（ohpm/hvigor/hdc/emulator 子进程）、以及回归证据（测试能否真实捕获原始缺陷）。

一个贯穿全文的核心原则是：发现结论必须基于当前代码、测试和实际运行的命令，作者或 Agent 的口头描述不构成证据。

二、审查前准备（Before reviewing）

审查 Skill 要求在执行任何检查前完成三项准备工作：

1. 确认审查基线。必须先确认 base 提交、target 提交与 worktree 状态，读取完整 diff 以及足够的上下文；当基线变更（amend、rebase、换 base）或 retarget 之后，必须重新核对 diff，避免基于过时内容下结论。

2. 阅读配套 Skill。每次审查都应先读 deveco-check-changes 来选择最小可信检查集；当变更涉及异步资源（子进程、锁、取消、MCP 初始化、共享状态）时，还必须读 deveco-test-reliability；当变更涉及文档或用户可见文本时，读 deveco-docs-and-prose。

3. 明确变更要素。识别具体的输入、预期结果、失败行为、变更范围与真实入口点。范围之外发现的问题应单独记录，而不是塞进当前修复里——这保证了 diff 的聚焦性，与 AGENTS.md 中"渐进迁移、一次一触、不让 diff 超出变更所需"的原则一致。

三、必查清单（Required checks）逐项拆解

3.1 接口与行为：双向追踪每一个变更接口

对每个被修改的接口，必须同时追踪接口两侧（定义方与消费方）以及所有生产调用者，逐一核对：

• 参数、返回值、默认值；
• 错误类型与错误信息；
• 退出码、stdout/stderr 输出；
• 兼容性行为（新老版本切换时的表现）。

这条规则的仓库背景是：deveco-cli 的 CLI 与 MCP 是两套对外契约。CLI 侧，packages/cli/src/cli.ts 通过 commander 注册build/run/update/device/emulator/auth/skills/log/create/init/serve/doc/ui/check/signature/verify全部子命令，命令参数、flag 与输出格式都是用户可见行为；MCP 侧，packages/cli/mcp/src-server/通过@modelcontextprotocol/sdk暴露check等工具，工具名、输入 schema、返回文本都是协议级契约。审查时任何一侧的改动都要顺藤摸瓜到另一侧。

3.2 职责与重复：每条共享规则只有一个 owner

Skill 明确要求：每条共享规则只能有一个属主（owner）。仓库内的两个典型所有权归属是：

• ToolProvider 拥有工具链路径：Studio/CLT 发现与ohpm/hvigor/hdc/emulator/bundled node 等组件路径的解析集中在 packages/cli/src/toolchain/tool-provider.ts，CLI 与 MCP 都消费它，而不应各自实现安装布局探测；
• 既有解析器拥有项目 JSON5：HarmonyOS 配置（build-profile.json5、module.json5、oh-package.json5、app.json5）的统一解析由既有 parser 承担，AGENTS.md 还特别强调这些文件要用json5解析而非原生JSON.parse。

命令层则应保持"编排与渲染"的单一职责，不得复制安装布局、配置优先级或业务规则。这与 AGENTS.md 的领域模块范式一脉相承：src/<domain>/index.ts是唯一 barrel，能力内部按types.ts → 纯函数 → adapter三层拆分，adapter 是唯一做 IO 的层，命令保持瘦身（Options 接口 + commander option 链 +handle*异步函数：spinner → 调 adapter → 格式化输出）。

3.3 生命周期与并发：信号要追踪到最终进程

对于锁、取消、超时、watch、重启或子进程相关变更，审查必须把信号追踪到最终进程，验证：

• 退出与锁释放是否可靠；
• 监听器是否正确移除；
• 旧任务完成后进程处于什么状态；
• 错误是否独立上报、互不干扰。

仓库中有大量此类场景可作参照：devecocli run --hotreload会作为后台进程持有到 hvigor daemon 的持久 socket，需要显式 kill；MCP 服务器在 packages/cli/mcp/src-server/server.ts 中维护 ArkTS 与 C++ 两套独立生命周期状态机（IDLE → DISCOVERING → SYNCING → INITIALIZING → READY/ERROR），并设有MAX_INIT_RETRY = 3、SYNC_SKIP_TIMEOUT_MS与MAX_CHECK_FILES = 100等边界常量。审查涉及生命周期变更时，应检查这些状态机是否存在新路径绕开就绪/错误处理。

3.4 边界与安全：拒绝路径与替代调用者都不能绕过约束

审查要在文件、JSON5、网络、外部命令与 MCP 协议五类边界上检查解析、路径、cwd、环境变量、argv、超时与失败传播：

• 路径类输入是否有 containment 校验（仓库已有 packages/cli/src/utils/path-containment.ts 实现resolveCanonicalPath/resolvePathInsideRoot）；
• 从 JSON5、CLI argv、设备输出、文件、网络、协议进入的数据必须与同进程内已被 TypeScript 保证的值区分对待，不得盲目删除防御性校验；
• 验证"既不存在拒绝路径（denial path），也没有替代调用者能绕过约束"——即约束必须在真实入口生效，而不只是某一条调用链上生效。

3.5 真实入口验证：Handler 单测不等于发布入口可用

这是审查 Skill 强调得最重的一条：

• CLI 变更必须通过构建产物packages/cli/dist/cli.js验证用户可见行为。src/下的编辑在npm run build（tsup 打包为单个 minified ESM bundle，bin 为devecocli）之前不会进入产物，因此"成功编译"不等于"用户入口可用"；
• MCP 变更必须通过真实的devecocli serve mcp入口或等价的打包协议路径验证。packages/cli/src/commands/serve.ts中的startStdioMcpServer从ToolProvider一次性解析 sdk/arkts-lsp/node/ohpm/hvigor/clangd 路径后调用createMcpServer，接管 stdin/stdout 作为 stdio 通信通道，并注册 SIGINT/SIGTERM/SIGBREAK 关闭信号；仅做 handler 级别的单元测试不足以证明这个打包后的入口真正可用。

同理，devecocli serve lsp（--arkts走 ace-server、--cpp走 clangd）是长期运行的 stdio 服务器，审查此类变更时应关注--project-path/--auto-detect的解析语义，而不是把它当作一次性 shell 命令验证。

3.6 回归证据：测试要观察外部行为并为原始缺陷失败

回归测试必须满足两个硬条件：

1. 观察外部行为——例如包名、工具 argv、文件结果、状态转换或协议响应，而不是"函数被调用""成功提示"这类内部信号；
2. 为原始缺陷失败——用旧的有缺陷实现或定向负向对照，证明该测试确实能捕获回归。

同时要确认当前配置能够发现这些测试：vitest 的 include 配置在 vitest.config.ts 中为packages/*/src/**/*.test.ts与packages/cli/mcp/src-server/**/*.test.ts；eslint 在 eslint.config.js 中覆盖packages/*/src/**/*.ts与.plugin的 TS/MJS，且对生产代码强制max-lines-per-function: 50、max-depth: 4。若测试发现配置变更，应先用一个临时失败用例证明 runner 会执行并报告失败，再移除该用例。检查集的选择交给 deveco-check-changes——它按 diff 影响面路由，禁止"因为提交了就重复跑全量检查"。

3.7 测试可靠性：私有资源、真实同步点、完整清理

涉及测试的审查要核对：

• 每个测试使用私有临时目录，显式设置子进程 cwd 与所需环境变量，避免读取用户真实项目、凭据或默认数据目录；
• 使用listen(0)读取系统分配的地址，文件/数据库/socket/输出路径使用唯一名称或排他创建，禁止"先扫描可用性再认领资源"；
• 用真实同步点（就绪信号、ack、受控阻塞）替代固定 sleep 等待；超时只用于界定失败等待，不能用于证明同步；
• 用try/finally围绕最小变更范围恢复共享可变状态（process.env、cwd、timers、locale、全局 mock、fetch 拦截）；
• 区分"启动前取消""执行中取消""正常非零退出"，锁测试要观察到后续任务真正获取到锁；
• 超时/失败后，终止测试拥有的进程并等待进程、监听器、异步任务全部停止再删除临时目录——kill()/release()调用本身不证明清理完成；
• Windows 与 POSIX 在环境变量大小写、文件句柄释放、信号、权限上存在差异，优先选择跨平台成立的观察方式；需要 Studio/CLT/设备的测试要分别列出前置条件与平台，单机通过不构成跨平台覆盖。

3.8 文档同步：同一 diff 内更新 README、SKILL.md 与 JSDoc

命令、flag、错误、发布资源或公开行为发生变更时，必须在同一个 diff内同步更新：

• 面向用户/Agent 的调用指南 SKILL.md 与 README.md（命令名、默认值、互斥条件、失败条件、平台能力）；
• 公开 JSDoc（返回值区别、异常、变更、所有权、时序、取消、持久化承诺）；
• 模块/内部注释（职责、竞态、资源所有权、安全边界、兼容性承诺）。

这是"契约归属其位"原则：命令指南的契约属于产品 Skill 与 README，代码内部契约属于注释，测试注释只解释非显然的 fixture、平台迁就、真实入口路径与间接观察理由。

3.9 设计质量：新抽象必须有生产调用者

审查设计质量时重点检查：

• 新抽象是否已有当前生产调用者，是否减少了需要手工保持同步的规则（而不是新增分支）；
• 是否存在硬编码的可变配置、无证据的默认值、重复的防御逻辑；
• 是否存在与任务无关的扩展（speculative generality，为想象中的未来预留接口）。

这条规则在 deveco-find-simplifications 中有更完整的展开：没有生产消费者的 symbol/参数/配置/事件/缓存/测试产物、两处维护同一业务事实的实现、仅为测试或示例服务的抽象，都是强简化候选；但零引用本身不构成删除理由——外部脚本可能依赖 CLI 参数、输出与文件格式，必须核实外部消费者。

四、报告发现（Report findings）的规范

审查报告的每条缺陷必须包含四要素：位置、触发条件、影响、证据。优先级排序为：错误行为 > 数据损坏 > 资源泄漏 > 兼容性回归 > 无效的质量检查。同时遵守：

• 建议与阻塞分离：建议（suggestion）与阻塞（blocker）分开陈述，不要混为一谈；
• 验证缺口显式标注：未运行的路径要标记为 validation gap，不能用"应该没问题"替代；
• 不重复已覆盖的发现：已被通过的自动化检查覆盖的问题，不再列出；
• 权限边界：一次审查任务本身不授权代码编辑、发布审查评论或合并请求。

五、配套 Skill 协作全景：四个 Skill 如何支撑一次完整审查

deveco-code-review 不是孤立的，它与其余四个开发 Skill 形成闭环：

deveco-check-changes（选择检查集）负责在提交/推送/报告验证结果前，从实际 diff 建立基线并路由证据：TypeScript 实现/类型走npm run lint+npm test -- <相关路径>；不在自动覆盖内或涉及 CLI 注册/输出/入口/发布资源的代码要npm run build后经真实入口验证；CI/依赖/package 脚本按受影响范围跑lint/test/build；纯文案变更只需git diff --check+ 手工核对元数据与本地引用。它还强调：超时、跳过、未运行的检查都不是通过；fake hdc/hvigor/ohpm 测试不能建立与真实 Studio 安装、CLT 或设备的兼容性；本地通过也不等于 GitCode pipeline 或分支保护已验证。

deveco-test-reliability（测试可靠性）提供隔离、同步、取消、清理的完整决策框架（见 3.7），并明确"在安静的机器上单机通过"不足以证明可重复性。

deveco-docs-and-prose（文档与散文）要求先识别文段中的每一个命题（actor、动作、条件、时序、must/may/never 模态、异常、所有权、副作用、失败模式、后果），再决定保留/增删/重构；编辑前需对照当前代码、help 输出与实际运行验证事实，验证命令名、相对 Markdown 链接与代码-文档一致性后运行git diff --check。

deveco-find-simplifications（简化候选）在审查之外提供"把表象复杂度转化为可评审的简化候选"的方法论：先用rg搜索精确符号/命令名/配置键/方法名/线串/动态加载入口，再读调用者、公共接口、测试、README、脚本与配置，将消费者分类为生产代码/测试文档/角色不确定的示例脚本。

六、实战演练：一次典型变更的审查路径

以"修改某个 CLI 子命令的 flag 与输出格式"为例，把上述规则串成一条可执行路径：

1. 确认基线：记录 base 与 target commit、worktree 状态，读取完整 diff；
2. 路由检查：按 deveco-check-changes 的表格，该变更落在"CLI 注册、输出、入口"行——先跑npm run lint，再npm run build，然后用构建产物packages/cli/dist/cli.js实际执行该子命令验证 flag、默认值、退出码与 stdout/stderr；
3. 回归证据：确认相关测试观察外部行为（输出文本、退出码）而非内部函数调用，且对原始缺陷会失败；用 vitest.config.ts 的 include 范围确认测试会被发现；
4. 文档同步：在同一 diff 内更新 SKILL.md 与 README.md 中对应命令/flag 的说明，必要时更新 JSDoc；
5. 生命周期检查：若变更涉及子进程或锁（如run --apply、--hotreload、MCP 重启），按 3.3 追踪信号到最终进程并核对清理路径；
6. 输出报告：按"位置、触发、影响、证据"逐条列出，建议与阻塞分开，未运行路径标为验证缺口。

七、审查底线与常见误区

最后重申几条不容妥协的底线，它们也是本 Skill 与 AGENTS.md 反复强调的：

• 口头描述不是证据：结论必须能落到当前代码、测试或实际运行的命令上；
• 静默通过不是通过：超时、跳过、未运行的检查都不能算验证通过；检查失败必须停下修复或明确声明阻塞；
• 构建成功不等于入口可用：npm run build只证明能编译，用户入口必须通过构建产物真实执行验证；
• fake 工具测试不等于真实兼容：mock hdc/hvigor/ohpm 的测试不能证明与真实 Studio 安装、CLT 或设备的兼容性；
• 本地通过不等于远端验证：本地测试通过不能证明 GitCode pipeline 或分支保护已验证，推送/重写历史需要用户授权；
• 审查不等于修改授权：一次代码审查任务不授权编辑代码、发布审查评论或合并请求。

遵循以上流程，开发者与 AI 编码助手即可在 deveco-cli 仓库中产出证据充分、范围聚焦、可被复核的代码审查结论，为 CLI 与 MCP 这两条对外契约线守住质量底线。

• 开发工具
• CLI
• OpenHarmony
• MCP 服务
• 移动开发