开发工具CLIOpenHarmonyMCP 服务移动开发【免费下载链接】deveco-cli集成HarmonyOS应用开发工具集提供知识文档和精品Skills支持多种智能体助力开发者使用AI辅助高效开发HarmonyOS应用。项目地址https://gitcode.com/openharmony-sig/deveco-cli点击查看免费下载deveco-cli 仓库内置了一组供 AI 编码助手使用的开发技能development skills其中deveco-docs-and-prose专门负责撰写与审阅文档、注释与诊断信息确保文案与 CLI 的真实行为保持一致并去除重复与流程化叙述。本文以 deveco-docs-and-prose 技能定义 为主线结合仓库中的命令实现doc.ts、docs-update.ts、docs-loader.ts、init.ts与仓库规范AGENTS.md完整讲解如何在修改 deveco-cli 文档时保全事实、按载体维护契约并借助真实入口点完成校验。读完本文你将掌握一套可直接套用的文档改动工作流识别范围 → 分解命题 → 分类维护 → 源码验证 →git diff --check收尾。一、技能定位它解决什么问题deveco-docs-and-prose的前置元信息frontmatter给出了明确的使用条件Use when writing or reviewing deveco-cli documentation, comments, or diagnostics to align prose and command guides with current behavior and remove repetition and process narration.也就是说凡是涉及以下三类产物的改动都应调用该技能面向用户的文档产品SKILL.md、README.md中的命令指南源码中的注释JSDoc 与内部注释诊断信息错误消息、CLI / MCP 输出文案。技能的核心方法论是以行为对齐文案先对照真实代码、真实帮助输出、真实运行的操作核验事实再决定文案怎么写。同时它把开发规则与使用指南做了明确的所有权划分开发规则归根目录 AGENTS.md 所有产品使用指南归 SKILL.md 与 README.md 所有本技能负责的是如何把文案写准。该技能还与其姊妹技能形成了协作链选择验证手段时调用 deveco-check-changes仓库中另有 deveco-code-review、deveco-test-reliability、deveco-find-simplifications 分别覆盖代码评审、测试可靠性、简化候选审计见 AGENTS.md 的 Agent workflows 表。二、第一步确立范围并保全事实技能要求在任何编辑动作之前先回答两个问题任务范围是什么影响哪些入口点entry points2.1 识别衍生物先改源仓库中由构建或发布流程生成的目录、索引、快照、fixture如docs-zh/dist/engine/、docs-zh/index.zip、检索索引等都被视为衍生物derivatives。规则是Treat generated catalogs, indexes, snapshots, and fixtures as derivatives: edit the owning source before regenerating them through the repository workflow.即先编辑拥有者源如packages/docs-engine/src/下的源码再通过仓库工作流重新生成而不是直接手改产物。这正好对应仓库的真实结构——docs-engine构建后会把dist拷贝到docs-zh/dist/engine/索引由npm run build:index调用packages/docs-index-builder/生成见 AGENTS.md 的 Docs index 小节。另外一条硬约束是文档中的操作步骤不得依赖不存在的脚本或依赖另一个本地仓库。换句话说文档里写到的每个命令都必须在当前仓库中真实存在、可执行。2.2 命题分解与事实元素保全编辑前技能要求逐条识别段落中的每个命题proposition并保全以下全部事实元素事实元素含义示例以devecocli docs update为例主体actor谁执行操作用户 / Agent / CLI 自身动作action做什么下载、校验、切换、回退条件conditions前置条件已安装 CLI、网络可用时序timing何时发生首次使用时 / 每次升级后情态modalitymust / may / never必须运行 X / 可选参数 / 绝不自动重试例外exceptions允许的偏差某些 Agent 不支持 MCP所有权ownership事实归谁管命令行为归产品文档开发规则归 AGENTS.md副作用side effects会产生什么影响写入doc-data/、创建软链接失败模式failure modes出错表现网络失败、版本不兼容后果consequences失败后怎么办回退到内置基线文档处理原则是去除重复、形容词与过程叙述process narration但只有在每个事实仍然清晰的前提下才允许缩短。所谓过程叙述指的是后来改成了……我尝试了……这类流水账式表述。每个事实应有唯一所有权one owner必要的地方用本地契约local contracts链接回源文档。三、第二步按载体维护契约Contracts技能把契约按承载位置分成四类每类的维护要点各不相同。这是全文最核心的实操章节。3.1 命令指南Command guides当命令或参数发生变化时必须同时更新产品 SKILL.md 与 README.md——这一点在 AGENTS.md 规则 13 中被硬性规定Adding a flag or command? Update the matching prose in bothSKILL.mdandREADME.md.需要核验的事实清单包括命令名与参数名kebab-case如--no-prompt、--output-path默认值如docs search的--limit默认为 10、--catalog默认为all互斥关系如--skill与--mcp互斥、--format与--details互斥失败条件如非交互终端下emulator license会报错需改用emulator license accept文件与设备副作用如--apply写入.hvigor/fileName、签名材料写入~/.ohos/config/平台能力差异区分 DevEco Studio、Command Line ToolsCLT与各独立组件Linux 必须依赖 CLT。以devecocli docs系列为例源码 doc.ts 中的 commander 定义与产品文档完全对应search keywords...支持--catalog name默认all、--format fmtdefault/json默认default、--limit n默认 10read documentIdcatalog以及update见 docs-update.ts 中--force与--check两个选项。校验命令名时最直接的手段就是阅读 cli.ts 中program.addCommand(...)的注册列表与对应命令文件的 commander 链。3.2 JSDoc 与内部注释公开 JSDoc面向调用者必须记录返回值的区分如成功/失败/空、抛出的异常、对入参的修改mutation、所有权、时序、取消语义与持久化行为。仓库中的典型范例可见 login-service.tsparam/returns/throws齐全与 install-hqf.tsparam target - 设备序列号如 127.0.0.1:5555等中文注释规范。模块与内部注释解释代码本身无法表达的职责、竞态races、资源所有权、安全边界与兼容性承诺。例如 docs-loader.ts 中getCurrentDocsVersion与getInstalledDocsVersion的注释明确区分了两者语义does NOT fall back to the bundled copy——前者为更新通知器判断是否有更新可用后者为安装器判断是否已安装过这种为什么存在两个相似函数的说明正是内部注释该承担的责任。3.3 测试注释测试注释的纪律最严格Delete line-by-line restatements, test walkthroughs, review dialogue, temporary proposal numbers, and process history such as later changed to.即只解释非显而易见的 fixture、平台适配、真实入口路径、间接观察的原因逐行复述、测试走查、评审对话、临时提案编号与后来改成了……这类过程历史一律删除。这与 deveco-test-reliability 中测试必须在真实 runner / 子进程 / 平台拓扑下可重复的要求形成互补注释聚焦为什么这样测技能保证怎么测才可靠。3.4 README 与诊断信息README描述配置、语义、失败、限制、扩展点与真实验证方法而不是罗列命令。仓库 README.md 的常用命令表与各命令的参数表即是对照物。诊断信息diagnostics必须指明失败主体、被违反的规则、修正方法三要素。例如 doc.ts 的formatDocCommandError当错误消息命中EACCES|EPERM|ENOSPC|ENOTDIR|ELOOP时输出统一的诊断文案Documentation data directory is unavailable. Check DEVECO_CLI_DATA_DIR and retry.——先指认失败主体数据目录不可用再给出修正动作检查DEVECO_CLI_DATA_DIR并重试。输出即行为可见的 CLI / MCP 输出属于行为范畴必须核对稳定字段、协议帧与错误措辞是否与真实入口点一致。例如docs search --format json的输出字段来自 doc.ts 定义的SearchResulttitle、documentId、snippet、sectionTitle写文档示例时不能臆造字段名。四、第三步编辑与验证Edit and Validate4.1 四种处置决策与验证缺口对编辑前识别出的每个命题决定是保留keep、新增add、精简trim还是重构restructure。关键规则不得为了达成缩短目标而人为制造编辑Do not set a shortening goal and manufacture edits to meet it——精简是保全事实后的自然结果不是目的当证据不足以验证某个命题时推迟决策并记录验证缺口validation gap而不是凭印象改写。4.2 三项必查项与收尾检查技能明确列出编辑后必须验证的三件事命令名——与 commander 注册一致相对 Markdown 链接——仓库内部链接必须解析成功下文第五节详述代码与文档的一致性——文档所述行为与源码实现相符。最后运行git diff --check检查空白错误等 diff 卫生问题。同时强调文案清理本身不授权任何产品行为变更Prose cleanup does not itself authorize product behavior changes——如果发现文案与实现不符正确的做法是修正文案或单独提交行为变更而不是借文档任务偷偷改行为。值得注意的是deveco-check-changes 也给出了同样的收尾纯文案改动Prose-only changes通常只需git diff --check加人工核验元数据与本地引用而真正的行为改动则需按覆盖范围跑最小的测试集不能以跟着提交跑一遍全量来敷衍。五、链接与所有权仓库内相对路径的转换规则技能原文中出现了三处指向其他文件的相对链接按以仓库根为起点的转换规则它们的正确形态是原文档中的写法转换后的仓库根相对路径说明[deveco-check-changes](https://link.gitcode.com/i/1d4b3881950ae2823ed28d588275bbbd)deveco-check-changes兄弟技能[SKILL.md](https://link.gitcode.com/i/1d4b3881950ae2823ed28d588275bbbd)SKILL.md产品使用指南[README.md](https://link.gitcode.com/i/a7fa0a59bf8ee7d725aa009e4918ac4e)README.md产品使用指南AGENTS.md文本提及AGENTS.md开发规则归属方这是一条通用纪律任何相对链接都必须从文档自身位置换算到仓库根目录否则在仓库外打开文档如 GitCode 网页端时链接会 404。写作与审阅 deveco-cli 文档时应把链接可解析纳入校验清单。六、源码级佐证文档背后的真实行为为了让文案对齐行为落地以下结合仓库源码展示几个高频命令的真实实现供写文档时对照。6.1docs search/read/catalog的实现骨架doc.ts 中输入校验validateOneOf(json, default)L94-L103限定--format取值validatePositiveIntL105-L111要求--limit为正整数resolveSearchInputL122-L130会 trim 关键词并拒绝空关键词——文档中关键词不能为空的约束即源于此。分类校验当--catalog非all时通过engineModule.CATALOG_NAMES校验取值非法值报Invalid catalog ...L175-L178。错误分类CacheDirError、DocPathSafetyError原样输出EACCES等文件系统错误统一改写为数据目录不可用提示L70-L92。遥测打点每次search/read/catalog都会经trackDocOperation记录耗时、成败与错误码L36-L53——这解释了 README 中数据采集与隐私见 PRIVACY.md的由来。6.2docs update的版本兼容语义docs-update.ts 中runDocsUpdateL59-L96的流程是读取 CLI 支持的apiVersiongetSupportedDocsApi()resolveDocsVersions(supportedApi)得到最新版本与兼容版本无兼容版本时提示先升级 CLIreportNoCompatible--check只报告不安装无--force且已最新则跳过实际安装落到dataDir/doc-data/。配套的 docs-loader.ts 揭示了更新后优先、内置兜底的双候选机制collectDocsCandidatesL67-L72按版本倒序合并findUpdatedDocs()与findBundledDocs()loadDocsEngineModuleL105-L133逐一尝试加载并在apiVersion超限时跳过。因此文档中缺失或损坏时回退到内置基线文档的描述是真实可验证的。6.3init --skill/--mcp的互斥与能力边界init.ts 印证了产品文档中的多条约束--skill与--mcp互斥同时传入直接报错L268-L270MCP 能力存在 Agent 边界qoder、dsh被列为不支持 MCP 的 AgentL190-L198显式指定时报错并建议改用--skill--path与--project、--agent互斥validatePathMutexSkill 安装按并发上限 5 分批执行L64-L70。6.4 调试输出的真实触发条件AGENTS.md 提到DEVECO_CLI_DEBUG1可查看底层命令调用其实现位于 logger.tsdebugLog仅在环境变量存在时输出[DEBUG] ...且支持传入 supplier 延迟构造字符串。文档中凡是写设置DEVECO_CLI_DEBUG1可查看底层命令映射如 emulator 场景控制的表述都应以这个实现为准。七、一套可复用的 deveco-cli 文档改动清单综合技能原文与仓库实际一次合格的文档改动应依次完成定范围确认受影响命令与入口点对照cli.ts注册表与各命令文件的 commander 链分载体判断改动属于命令指南 / JSDoc / 测试注释 / README-诊断中的哪一类套用对应契约分解命题逐条列出事实元素主体、动作、条件、时序、情态、例外、所有权、副作用、失败模式、后果去除重复与过程叙述源码核验命令名、默认值、互斥、失败条件、副作用、平台差异逐一与源码对照涉及可见输出时核对稳定字段与错误措辞双处同步命令或参数变更时产品 SKILL.md 与 README.md 必须同步更新链接检查所有内部相对链接换算为仓库根相对路径并确认目标存在收尾验证运行git diff --check纯文案改动到此为止行为改动另按 deveco-check-changes 选择最小验证集不越界文案清理不改变产品行为证据不足的命题记录验证缺口不臆造。这套清单同样适用于审阅他人提交的文档改动——逐项核对即可快速发现文档与实现不符链接失效夹带过程叙述三类最常见问题。赞分享开发工具CLIOpenHarmonyMCP 服务移动开发【免费下载链接】deveco-cli集成HarmonyOS应用开发工具集提供知识文档和精品Skills支持多种智能体助力开发者使用AI辅助高效开发HarmonyOS应用。项目地址https://gitcode.com/openharmony-sig/deveco-cli点击查看免费下载相关推荐TigerBeetle 技术文档写作规范Docs Style Guide全解析从文档分层到微观写作守则TigerBeetle 技术文档写作规范Docs Style Guide全解析从文档分层到微观写作守则 本文以 TigerBeetle 仓库中的内部文档数据库分布式数据库金融科技存储TablePro 文档编写规范一篇技术文档如何通过源码级校验TablePro 文档编写规范一篇技术文档如何通过源码级校验 导读 本文解析 TablePro 开源仓库中驱动全部文档产出的编写规范 docs/STYLE.mHomebrew 文档写作体系Prose Style Guidelines 与 Vale 自动化风格校验实战指南Homebrew 文档写作体系Prose Style Guidelines 与 Vale 自动化风格校验实战指南 本文以 brew 仓库的 Prose StyCLI包管理器上一篇WindowsCommunityToolkit缓存与存储ApplicationDataStorageHelper的最佳实践指南下一篇web.py WSGI部署完全手册从开发到生产的完整流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考