用途
zod-migration 用于把 CLI for Microsoft 365 的命令从旧版 #initOptions()、#initValidators()、#initTelemetry() 模式迁移到基于 Zod schema 的校验。当命令仍带有这些旧方法,或没有 schema getter、没有导出的 options Zod schema 时,适合使用该技能。
主要流程
迁移前先阅读命令源文件(.ts)及其测试文件(.spec.ts),识别选项、别名、校验器、遥测、选项集和类型,并检查是否有自动补全值,以及表示 GUID 或 UPN 的选项是否接受运行时令牌 @meid 或 @meusername。
迁移步骤如下:
- 在命令 .ts 文件中定义 Zod schema,替换导入,并导出
options。 - 为类添加 schema getter:
public get schema(): z.ZodType | undefined { return options; }。 - 删除旧的初始化方法,包括构造函数(若其仅调用初始化方法)、
#initOptions()、#initValidators()、#initTelemetry()、#initTypes()、#initOptionSets()。 - 对跨字段校验使用
getRefinedSchema(),例如选项集(互斥或“二选一”)、条件必填、set 命令的“至少更新一项”模式。 - 把必须保留的校验器(文件系统检查、URL 校验等)移入
.refine(),因为命令定义 schema 后 CLI 不再运行this.validators。 - 对接受未知选项的宽松命令(如 user-set、user-add、groupsetting-set),使用
z.object()配合.catchall(z.unknown())。 - 迁移测试文件,更新导入、声明
commandOptionsSchema、用safeParse重写校验测试、用commandOptionsSchema.parse()重写动作测试,删除旧“supports specifying”测试,并补充未知选项失败和无可选选项时通过的测试。
关键规则
- 始终使用
z.strictObject(),除非命令接受未知选项;仅含全局选项时使用globalOptionsZod.strict()。 - 始终展开
...globalOptionsZod.shape,并始终导出options。 - 不要对接受
@meid的字段使用z.uuid(),改用.refine()自定义 GUID 校验。 - 保持选项名称不变,保留大小写不敏感行为,固定自动补全值优先用
z.enum()。 - 逗号分隔的 GUID/UPN 校验错误只报告无效值,而非整个输入。
- CLI 参数是字符串;数值转换在
commandAction中显式处理。
适用场景与限制
适用于需要批量迁移 CLI for Microsoft 365 命令的项目。技能强调测试文件必须全部更新,动作测试必须使用 commandOptionsSchema.parse() 而不是 options.parse(),使用 @meid/@meusername 的测试保留 as any。文档未说明该技能自身的安装方式、收费、价格或平台信息。