weapp-ide-cli-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

weapp-ide-cli-best-practices

weapp-ide-cli 最佳实践

Purpose

目的

Design and evolve

weapp-ide-cli

with deterministic command behavior, automation-friendly UX, and stable integration contracts for other CLIs (especially

weapp-vite

设计并迭代

weapp-ide-cli

，使其具备确定性的命令行为、对自动化友好的用户体验，以及可供其他CLI（尤其是

weapp-vite

）使用的稳定集成契约。

Trigger Signals

触发信号

User asks to add/refactor
```
weapp-ide-cli
```
commands or argument validation.
User asks to expose command metadata for external CLI dispatch.
User asks to improve DevTools automation, screenshot, or automator subcommands.
User asks to add language switching or config persistence behavior.
User asks how
```
weapp-vite
```
should delegate to
```
weapp-ide-cli
```
.

用户要求新增/重构
```
weapp-ide-cli
```
命令或参数校验逻辑
用户要求暴露命令元数据供外部CLI调度使用
用户要求优化DevTools自动化、截图或automator子命令
用户要求新增语言切换或配置持久化能力
用户询问
```
weapp-vite
```
应如何委托调用
```
weapp-ide-cli
```

Scope Boundary

适用范围边界

Use this skill when the center of gravity is command routing, CLI UX, config persistence, and cross-package CLI contracts.

Do not use this as the primary skill when:

The issue is mainly
```
weapp-vite
```
project build/subpackage architecture. Use
```
weapp-vite-best-practices
```
.
The issue is mainly Vue SFC syntax/macro compatibility. Use
```
weapp-vite-vue-sfc-best-practices
```
.
The issue is runtime lifecycle/state architecture in components/pages. Use
```
wevu-best-practices
```
.

当问题核心为命令路由、CLI用户体验、配置持久化、跨包CLI契约时，使用本规范。

以下场景不优先使用本规范：

问题主要涉及
```
weapp-vite
```
项目构建/分包架构，请使用
```
weapp-vite-best-practices
```
问题主要涉及Vue SFC语法/宏兼容性，请使用
```
weapp-vite-vue-sfc-best-practices
```
问题主要涉及组件/页面的运行时生命周期/状态架构，请使用
```
wevu-best-practices
```

Quick Start

快速开始

Classify change type: command addition, validation, i18n/config, or dispatch contract.
Update command source-of-truth first, then update parser/dispatcher.
Add/adjust tests around routing and error behavior.
Sync docs in package README and website package page.

归类变更类型：命令新增、校验逻辑、国际化/配置、调度契约
优先更新命令权威定义，再更新解析器/调度器
针对路由和错误行为新增/调整测试用例
同步更新包README和官网包页面的文档

Execution Protocol

执行规范

Keep command taxonomy explicit

Maintain command groups as separate layers:
- WeChat official passthrough commands
- automator enhanced commands
- config commands
- minidev namespace passthrough
Export top-level command catalog from
```
weapp-ide-cli
```
for external reuse.
Provide a direct predicate function to check command support.

Enforce dispatch invariants

Parse global language option before command routing.
Route minidev namespace and automator commands before generic WeChat CLI passthrough.
Keep
```
help <automator-command>
```
behavior explicit and deterministic.
Validate critical arguments before invoking external CLI.

Keep i18n + config predictable

Default language is Chinese.
Support command-level temporary language override and persistent config language.
Persist config to user directory config file and expose
```
config
```
subcommands for read/write/export/import.
Prefer Chinese user-facing messages, with switchable English fallback.

Establish integration contract for upstream CLI

Upstream CLI (e.g.
```
weapp-vite
```
) should:
- execute its native command table first
- delegate only when
```
isWeappIdeTopLevelCommand(command)
```
  is true
- avoid blind passthrough for unknown commands
Keep this rule documented and tested on both sides.

Verify narrowly

Prefer targeted tests in:

```
packages/weapp-ide-cli/test/*.test.ts
```
related
```
packages/weapp-vite/src/cli/*.test.ts
```
when dispatch contract changes

Run lint on touched docs and source files only.

保持命令分类清晰明确

将命令组按分层维护：
- 微信官方透传命令
- automator增强命令
- 配置命令
- minidev命名空间透传
从
```
weapp-ide-cli
```
导出顶层命令目录供外部复用
提供直接的判断函数来检查命令是否支持

强制调度不变性

在命令路由前先解析全局语言选项
优先路由minidev命名空间和automator命令，再处理通用微信CLI透传
保持
```
help <automator-command>
```
行为清晰且确定
在调用外部CLI前校验关键参数

保持国际化+配置行为可预测

默认语言为中文
支持命令级临时语言覆盖和持久化配置语言
将配置持久化到用户目录配置文件，并暴露
```
config
```
子命令支持读写/导出/导入
用户提示信息优先使用中文，支持切换为英文备选

为上游CLI建立集成契约

上游CLI（例如
```
weapp-vite
```
）应当：
- 优先执行自身的原生命令表
- 仅当
```
isWeappIdeTopLevelCommand(command)
```
  为真时才委托调用
- 避免对未知命令盲目透传
该规则需要在双方文档中明确说明并覆盖测试

针对性验证

优先在以下位置编写针对性测试：
- ```
packages/weapp-ide-cli/test/*.test.ts
```
- 调度契约变更时，补充相关
```
packages/weapp-vite/src/cli/*.test.ts
```
  测试
仅对修改过的文档和源文件执行lint检查

Guardrails

约束规则

Do not duplicate command lists in multiple packages as independent sources of truth.
Do not add user-facing text without i18n wrapping.
Do not couple command parsing with business side effects before validation.
Do not let unknown commands silently passthrough when integrating with another CLI.

不要在多个包中重复维护命令列表作为独立的权威定义
新增用户可见文本时必须包裹国际化逻辑
校验完成前不要将命令解析与业务副作用耦合
与其他CLI集成时，不要让未知命令静默透传

Output Contract

输出规范

When applying this skill, return:

Command-level design summary (what changed and why).
Concrete file edits for catalog/routing/validation/docs/tests.
Verification commands and expected outcomes.
Cross-package contract notes when
```
weapp-vite
```
integration is touched.

应用本规范时，需要返回：

命令级设计摘要（变更内容及原因）
目录/路由/校验/文档/测试对应的具体文件修改
验证命令及预期结果
涉及
```
weapp-vite
```
集成时，需提供跨包契约说明

Completion Checklist

完成检查清单

Top-level command catalog and predicate are exported from
```
weapp-ide-cli
```
.
Dispatch priority is deterministic and covered by tests.
New/changed user-facing messages support Chinese default and English switch.
Config persistence and command behavior are documented.
If integration changed,
```
weapp-vite
```
uses exported catalog instead of duplicated lists.

```
weapp-ide-cli
```
已导出顶层命令目录和判断函数
调度优先级逻辑确定且已覆盖测试
新增/变更的用户可见信息默认支持中文，可切换为英文
配置持久化和命令行为已文档化
若集成逻辑变更，
```
weapp-vite
```
需使用导出的命令目录而非重复维护的列表

References

参考文档

references/command-catalog-and-dispatch.md

```
references/i18n-config-playbook.md
```

references/command-catalog-and-dispatch.md

```
references/i18n-config-playbook.md
```