appship 0.1.0 → 0.2.0

data/lib/appship/cli.rb

@@ -13,13 +13,17 @@ module Appship
     end
 
     def start(argv)
+      @notification_options = nil
       args = argv.dup
       global = extract_global_options!(args)
       command = args.shift
+      @notification_options = {} if %w[build package upload pgyer fir].include?(command)
 
       case command
       when "init"
         init(args)
+      when "webhook"
+        webhook(args)
       when "doctor"
         doctor
       when "build"
@@ -39,10 +43,45 @@ module Appship
       else
         raise ConfigurationError, "未知命令: #{command}\n\n#{help}"
       end
+    rescue StandardError, Interrupt => e
+      notify_failure(e)
+      raise
     end
 
     private
 
+    def notify_failure(error)
+      return unless @notification_options
+
+      options = @notification_options.dup
+      unless options.values_at(*Webhook::URL_FIELDS).any? { |url| !url.to_s.strip.empty? }
+        path = File.expand_path(options[:env_file] || ENV.fetch("APPSHIP_ENV_FILE", Cache::DEFAULT_PATH))
+        directory = File.expand_path(options[:project_dir] || Dir.pwd)
+        local_path = ProjectConfig.path(directory)
+        return unless File.file?(path) || File.exist?(local_path) || File.symlink?(local_path)
+
+        if options[:project_name].to_s.empty? && !File.file?(local_path) && Dir[File.join(directory, "*.xcodeproj"), File.join(directory, "*.xcworkspace")].empty?
+          return
+        end
+        begin
+          profile = ProjectConfig.load(path, project_dir: directory, interactive: false)
+                                 .resolve(project_name: options[:project_name], project_dir: directory,
+                                          interactive: false, credentials: false)
+        rescue Error, SystemCallError
+          return
+        end
+        options = {
+          app_name: profile["app_name"], project_name: profile["project_name"],
+          api_key: profile["pgyer_api_key"], password: profile["pgyer_password"],
+          fir_api_token: profile["fir_api_key"], fir_password: profile["fir_password"]
+        }.merge(options.compact)
+        Webhook::OPTION_FIELDS.each { |key| options[key] = profile[key.to_s] }
+      end
+      Webhook.new(options).failure(error)
+    rescue StandardError => e
+      warn "⚠️ 失败通知未能发送（#{e.class}），保留原始错误"
+    end
+
     def extract_global_options!(args)
       config_path = nil
       verbose = false
@@ -79,16 +118,47 @@ module Appship
     end
 
     def init(args)
-      path = File.join(Dir.pwd, ".appship.yml")
-      force = false
+      project_dir = Dir.pwd
       parser = OptionParser.new do |opts|
         opts.banner = "用法: appship init [选项]"
-        opts.on("--path PATH", "配置文件路径（默认 .appship.yml）") { |value| path = value }
-        opts.on("--force", "覆盖已有配置文件") { force = true }
+        opts.on("--project-dir PATH", "工程目录（默认当前目录）") { |value| project_dir = value }
         opts.on("-h", "--help", "显示帮助") { puts opts; exit 0 }
       end
       parser.parse!(args)
-      puts "✅ 已创建配置文件: #{Config.write_template(path, force: force)}"
+      raise ConfigurationError, "init 不接受多余参数: #{args.join(" ")}" unless args.empty?
+
+      ProjectConfig.init!(project_dir: File.expand_path(project_dir)).each do |path|
+        puts "✅ 项目示例已就绪（已有内容不会覆盖）: #{path}"
+      end
+      puts "复制为 appship/config.yml 和 appship/message.yml 后编辑，示例文件不会参与运行。"
+    end
+
+    def webhook(args)
+      options = { project_dir: Dir.pwd, env_file: ENV.fetch("APPSHIP_ENV_FILE", Cache::DEFAULT_PATH), project_name: nil }
+      parser = OptionParser.new do |opts|
+        opts.banner = '用法: appship webhook wechat|dingtalk|feishu URL [选项]（URL 传 "" 可关闭通知）'
+        opts.on("--project-dir PATH", "项目目录（默认当前目录）") { |value| options[:project_dir] = value }
+        opts.on("--env-file PATH", "本机缓存文件（默认 ~/.appship/.config）") { |value| options[:env_file] = value }
+        opts.on("--project-name NAME", "配置中的 project_name") { |value| options[:project_name] = value }
+        opts.on("-h", "--help", "显示帮助") { puts opts; return }
+      end
+      parser.parse!(args)
+      return puts(parser) if args.empty?
+      unless args.length == 2 && Webhook::PLATFORMS.key?(args.first)
+        raise ConfigurationError, "请指定 wechat、dingtalk 或 feishu，以及完整的 Webhook URL\n#{parser}"
+      end
+
+      platform, url = args
+      url = url.strip
+      Webhook.parse_url!(url) unless url.empty?
+      project_dir = File.expand_path(options[:project_dir])
+      raise ConfigurationError, "项目目录不存在: #{project_dir}" unless File.directory?(project_dir)
+
+      cache = ProjectConfig.load(options[:env_file], project_dir: project_dir, interactive: false)
+      profile = cache.resolve(project_name: options[:project_name], project_dir: project_dir, interactive: false, credentials: false)
+      cache.update_profile!(profile, "#{platform}_webhook" => url)
+      action = url.empty? ? "已关闭" : "已保存"
+      puts "✅ #{Webhook::PLATFORMS.fetch(platform)}通知#{action}（#{profile["project_name"]}）: #{cache.path}"
     end
 
     def doctor
@@ -112,14 +182,16 @@ module Appship
         puts "#{available ? "✅" : "⚠️"} #{command.ljust(16)} #{available || "未安装"} - #{purpose}"
       end
       config = Config.find
-      puts "#{config.path ? "✅" : "ℹ️"} 配置文件       #{config.path || "当前目录没有 .appship.yml"}"
+      puts "#{config.path ? "✅" : "ℹ️"} 配置文件       #{config.path || "当前目录没有 appship/config.yml 或 .appship.yml"}"
     end
 
     def build(args, global)
       config = Config.find(global[:config_path])
       options = build_options(config)
+      @notification_options = options
       parser = build_parser(options)
       parser.parse!(args)
+      apply_badge_config!(options, config.data)
       Builder.new(runner: Runner.new(verbose: global[:verbose])).build!(options)
     end
 
@@ -128,18 +200,21 @@ module Appship
       options = upload_options(config).merge(
         app: nil,
         output: nil,
-        badge: config.get("badge"),
+        configuration: config.get("configuration"),
         assets: config.get("assets"),
         app_icon: config.get("app_icon", default: "AppIcon")
       )
+      @notification_options = options
       parser = package_parser(options)
       parser.parse!(args)
+      apply_badge_config!(options, config.data)
       Builder.new(runner: Runner.new(verbose: global[:verbose])).package!(options)
     end
 
     def upload(args, global)
       config = Config.find(global[:config_path])
       options = upload_options(config).merge(file: nil)
+      @notification_options = options
       parser = upload_parser(options)
       parser.parse!(args)
       options[:file] ||= args.shift
@@ -190,6 +265,7 @@ module Appship
         skip_package_plugin_validation: true,
         skip_macro_validation: true
       }
+      @notification_options = options
       parser = pgyer_parser(options)
       normalize_provider_short_options!(args, "pgyer")
       parser.parse!(args)
@@ -200,7 +276,7 @@ module Appship
       env_file = File.expand_path(options[:env_file], Dir.pwd)
 
       Dir.chdir(project_dir) do
-        cache = Cache.load(env_file, project_dir: project_dir, interactive: true, provider: "pgyer")
+        cache = ProjectConfig.load(env_file, project_dir: project_dir, interactive: true, provider: "pgyer")
         profile = cache.resolve(
           project_name: options[:project_name],
           project_dir: project_dir,
@@ -213,7 +289,7 @@ module Appship
 
         runner = Runner.new(verbose: global[:verbose])
         builder = Builder.new(runner: runner)
-        prepare_pgyer_flow!(options, builder)
+        prepare_pgyer_flow!(options, builder, profile)
         if options[:build_mode] == "cache"
           options[:app] ||= builder.find_cached_app!(options)
           builder.package!(options)
@@ -267,6 +343,7 @@ module Appship
         skip_package_plugin_validation: true,
         skip_macro_validation: true
       }
+      @notification_options = options
       parser = fir_parser(options)
       normalize_provider_short_options!(args, "fir")
       parser.parse!(args)
@@ -277,7 +354,7 @@ module Appship
       env_file = File.expand_path(options[:env_file], Dir.pwd)
 
       Dir.chdir(project_dir) do
-        cache = Cache.load(env_file, project_dir: project_dir, interactive: true, provider: "fir")
+        cache = ProjectConfig.load(env_file, project_dir: project_dir, interactive: true, provider: "fir")
         profile = cache.resolve(
           project_name: options[:project_name],
           project_dir: project_dir,
@@ -290,7 +367,7 @@ module Appship
 
         runner = Runner.new(verbose: global[:verbose])
         builder = Builder.new(runner: runner)
-        prepare_pgyer_flow!(options, builder)
+        prepare_pgyer_flow!(options, builder, profile)
         if options[:build_mode] == "cache"
           options[:app] ||= builder.find_cached_app!(options)
           builder.package!(options)
@@ -321,7 +398,7 @@ module Appship
       options[:configuration] ||= profile["configuration"] || "Debug"
       options[:assets] ||= profile["assets"]
       options[:app_icon] ||= profile["app_icon"] || "AppIcon"
-      options[:badge] ||= profile["badge"]
+      Webhook::OPTION_FIELDS.each { |key| options[key] = profile[key.to_s] }
       if provider.to_s != "fir"
         options[:password_env] ||= profile["pgyer_password_env"]
         options[:password] ||= profile["pgyer_password"]
@@ -349,12 +426,16 @@ module Appship
       elsif File.exist?(project)
         options[:project] = project
       else
-        candidates = Dir["*.xcworkspace", "*.xcodeproj"]
-        if candidates.length == 1
-          options[File.extname(candidates.first) == ".xcworkspace" ? :workspace : :project] = candidates.first
-        else
-          raise ConfigurationError, "找不到 #{options[:project_name]}.xcworkspace 或 #{options[:project_name]}.xcodeproj"
-        end
+        names = Dir["*.xcworkspace", "*.xcodeproj"].select { |path| File.directory?(path) }
+                                                .map { |path| File.basename(path, File.extname(path)) }.uniq
+        config_path = File.expand_path(options[:env_file] || Cache::DEFAULT_PATH)
+        hint = if names.empty?
+                 "请先 cd 到包含 .xcodeproj/.xcworkspace 的项目目录，或使用 --project-dir 指定目录。"
+               else
+                 "当前目录可配置的 project_name: #{names.join(", ")}（不含文件后缀）"
+               end
+        raise ConfigurationError, "找不到 #{workspace} 或 #{project}\n当前目录: #{Dir.pwd}\n" \
+                                  "请在 #{config_path} 的配置数组中增加当前项目配置，设置正确的 project_name。\n#{hint}"
       end
 
       if options[:assets].to_s.empty?
@@ -370,7 +451,7 @@ module Appship
       "自动编译打包 | 分支：#{branch} | 构建人：#{user} | 配置：#{options[:configuration]} | 更新内容：#{content}"
     end
 
-    def prepare_pgyer_flow!(options, builder)
+    def prepare_pgyer_flow!(options, builder, profile)
       interactive = $stdin.tty? && $stdout.tty?
       unless options[:build_mode_explicit]
         options[:build_mode] = choose_build_mode if interactive
@@ -380,10 +461,8 @@ module Appship
         options[:configuration] = choose_configuration
       end
 
-      if options[:build_mode] == "cache"
-        options[:badge] ||= badge_text(options[:configuration]) unless options[:badge_explicit]
-      elsif !options[:badge_explicit] && interactive
-        options[:badge] = choose_badge ? badge_text(options[:configuration]) : nil
+      if options[:build_mode] != "cache"
+        apply_badge_config!(options, profile) { interactive && choose_badge }
       end
 
       unless options[:description_explicit] || !interactive
@@ -393,18 +472,13 @@ module Appship
       end
 
       if options[:build_mode] == "cache"
-        begin
-          puts ""
-          puts "📦 使用缓存模式"
-          options[:app] ||= with_spinner("正在查找编译缓存中的 .app 文件") do
-            builder.find_cached_app!(options)
-          end
-          puts "✅ 找到缓存 App: #{options[:app]}"
-        rescue CommandError => e
-          puts "⚠️ #{e.message}，将切换到重新构建模式"
-          options[:build_mode] = "rebuild"
-          options[:app] = nil
+        puts ""
+        puts "📦 使用缓存模式"
+        options[:app] ||= with_spinner("正在查找编译缓存中的 .app 文件") do
+          builder.find_cached_app!(options)
         end
+        puts "✅ 找到缓存 App: #{options[:app]}"
+        apply_badge_config!(options, profile) { true }
       end
 
       options[:description] ||= default_description(options)
@@ -539,6 +613,22 @@ module Appship
       nil
     end
 
+    def apply_badge_config!(options, profile)
+      return if options[:badge_explicit]
+
+      %w[app_icon_badge app_icon_badge_environment].each do |key|
+        next if [nil, true, false].include?(profile[key])
+
+        raise ConfigurationError, "#{key} 必须是布尔值 true 或 false"
+      end
+      enabled = profile["app_icon_badge"]
+      environment = profile["app_icon_badge_environment"]
+      options[:badge] = enabled == false ? nil : profile["badge"]
+      return if enabled == false || environment == false || options[:badge]
+
+      options[:badge] = badge_text(options[:configuration]) if enabled || environment || (block_given? && yield)
+    end
+
     def badge_text(configuration)
       configuration.to_s.casecmp("release").zero? ? "RELEASE" : "DEBUG"
     end
@@ -562,7 +652,6 @@ module Appship
         export_method: config.get("export_method", default: "development"),
         signing_style: config.get("signing_style", default: "automatic"),
         team_id: config.get("team_id"),
-        badge: config.get("badge"),
         assets: config.get("assets"),
         app_icon: config.get("app_icon", default: "AppIcon"),
         upload: false,
@@ -576,27 +665,28 @@ module Appship
 
     def upload_options(config)
       {
-        provider: config.get("upload", "provider", default: "pgyer"),
-        api_key: nil,
+        provider: config.get("upload", "provider", default: config.get("provider", default: "pgyer")),
+        api_key: config.get("pgyer_api_key"),
         api_key_env: config.get("upload", "api_key_env", default: "PGYER_API_KEY"),
-        fir_api_token: nil,
+        fir_api_token: config.get("fir_api_key"),
         fir_api_token_env: config.get("upload", "fir_api_token_env", default: "FIR_API_TOKEN"),
-        fir_password: config.get("upload", "fir_password"),
+        fir_password: config.get("upload", "fir_password", default: config.get("fir_password")),
         fir_password_env: config.get("upload", "fir_password_env", default: "FIR_PASSWORD"),
-        bundle_id: config.get("upload", "bundle_id"),
-        app_name: config.get("upload", "app_name"),
-        app_version: config.get("upload", "app_version"),
-        build_number: config.get("upload", "build_number"),
+        bundle_id: config.get("upload", "bundle_id", default: config.get("bundle_id")),
+        app_name: config.get("upload", "app_name", default: config.get("app_name")),
+        app_version: config.get("upload", "app_version", default: config.get("app_version")),
+        build_number: config.get("upload", "build_number", default: config.get("build_number")),
         release_type: config.get("upload", "release_type"),
         icon: config.get("upload", "icon"),
-        install_type: config.get("upload", "install_type", default: 1),
-        password: nil,
+        install_type: config.get("upload", "install_type", default: config.get("pgyer_install_type", default: config.get("pgyer_password", default: "").to_s.empty? ? 1 : 2)),
+        password: config.get("pgyer_password"),
         password_env: config.get("upload", "password_env"),
         description: config.get("upload", "description"),
         install_date: config.get("upload", "install_date"),
         start_date: config.get("upload", "start_date"),
         end_date: config.get("upload", "end_date"),
         channel: config.get("upload", "channel"),
+        **Webhook::OPTION_FIELDS.to_h { |key| [key, config.get("upload", key, default: config.get(key))] },
         poll_attempts: config.get("upload", "poll_attempts", default: 60),
         upload: false
       }
@@ -623,8 +713,8 @@ module Appship
         opts.on("--no-allow-provisioning-updates", "不允许 xcodebuild 自动更新签名") { options[:allow_provisioning_updates] = false }
         opts.separator ""
         opts.separator "图标角标"
-        opts.on("--badge TEXT", "添加角标，例如 DEBUG 或 RELEASE") { |value| options[:badge] = value }
-        opts.on("--no-badge", "禁用配置文件里的角标") { options[:badge] = nil }
+        opts.on("--badge TEXT", "添加角标，例如 DEBUG 或 RELEASE") { |value| options[:badge] = value; options[:badge_explicit] = true }
+        opts.on("--no-badge", "禁用配置文件里的角标") { options[:badge] = nil; options[:badge_explicit] = true }
         opts.on("--assets PATH", "Assets.xcassets 路径") { |value| options[:assets] = value }
         opts.on("--app-icon NAME", "AppIcon 名称（默认 AppIcon）") { |value| options[:app_icon] = value }
         opts.separator ""
@@ -638,8 +728,8 @@ module Appship
         opts.banner = "用法: appship [--config FILE] package [选项]"
         opts.on("--app PATH", "已编译 .app 路径") { |value| options[:app] = value }
         opts.on("--output PATH", "最终 IPA 路径") { |value| options[:output] = value }
-        opts.on("--badge TEXT", "添加角标") { |value| options[:badge] = value }
-        opts.on("--no-badge", "禁用角标") { options[:badge] = nil }
+        opts.on("--badge TEXT", "添加角标") { |value| options[:badge] = value; options[:badge_explicit] = true }
+        opts.on("--no-badge", "禁用角标") { options[:badge] = nil; options[:badge_explicit] = true }
         opts.on("--assets PATH", "Assets.xcassets 路径") { |value| options[:assets] = value }
         opts.on("--app-icon NAME", "AppIcon 名称") { |value| options[:app_icon] = value }
         add_upload_options(opts, options)
@@ -773,7 +863,10 @@ module Appship
         appship #{VERSION} - 通用移动应用构建、打包和分发工具
 
         用法:
-          appship init [--path .appship.yml]
+          appship init [--project-dir PATH]
+          appship webhook wechat "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
+          appship webhook dingtalk "https://oapi.dingtalk.com/robot/send?access_token=xxx"
+          appship webhook feishu "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
           appship doctor
           appship pgyer
           appship fir

data/lib/appship/config.rb

@@ -29,9 +29,11 @@ module Appship
 
     attr_reader :path, :data
 
-    def initialize(path = nil)
+    def initialize(path = nil, data: nil)
       @path = path && File.expand_path(path)
-      @data = if @path && File.file?(@path)
+      @data = if data
+                data
+              elsif @path && File.file?(@path)
                 YAML.safe_load(File.read(@path), permitted_classes: [], aliases: false) || {}
               else
                 {}
@@ -51,6 +53,20 @@ module Appship
     def self.find(path = nil)
       return new(path) if path
 
+      local_path = ProjectConfig.path
+      if File.exist?(local_path) || File.symlink?(local_path)
+        profile = ProjectConfig.load(ENV.fetch("APPSHIP_ENV_FILE", Cache::DEFAULT_PATH), interactive: false)
+                               .resolve(interactive: false, credentials: false)
+        profile["scheme"] ||= profile["project_name"]
+        unless profile["workspace"] || profile["project"]
+          workspace = "#{profile["project_name"]}.xcworkspace"
+          project = "#{profile["project_name"]}.xcodeproj"
+          profile["workspace"] = workspace if File.directory?(workspace)
+          profile["project"] = project if !profile["workspace"] && File.directory?(project)
+        end
+        return new(local_path, data: profile)
+      end
+
       candidates = [
         File.join(Dir.pwd, ".appship.yml"),
         File.join(Dir.pwd, ".appship.yaml"),

data/lib/appship/default_message

@@ -0,0 +1,9 @@
+应用名称: %{name}
+应用类型: %{build_type_name}
+版本信息: %{version_info}
+构建模式: %{configuration}
+应用大小: %{build_size_mb}
+更新时间: %{build_updated}
+更新描述: %{description}
+安装密码: %{password}
+下载链接: %{url}

data/lib/appship/message.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Appship
+  module Message
+    VARIABLES = %w[name build_type_name version_info configuration build_size_mb build_updated description password url].freeze
+    PLACEHOLDER = /%\{([^}]*)\}/
+    CONTENT_FIELDS = %w[
+      cli_content
+      wechat_webhook_success_content dingtalk_webhook_success_content feishu_webhook_success_content
+      wechat_webhook_content dingtalk_webhook_content feishu_webhook_content
+    ].freeze
+    FAILURE_FIELDS = %w[wechat_webhook_failure_content dingtalk_webhook_failure_content feishu_webhook_failure_content].freeze
+    FAILURE_VARIABLES = %w[name provider configuration error_type error_message].freeze
+    FORMATS = {
+      "wechat_webhook_format" => %w[text markdown].freeze,
+      "feishu_webhook_format" => %w[text post].freeze
+    }.freeze
+    INSTRUCTIONS = <<~TEXT.freeze
+      # Appship 发布消息模板
+      # 复制为 appship/message.yml 后编辑。用 | 开始多行文本，正文缩进两个空格。
+      # 成功文案留空则沿用 cli_content；失败文案留空则使用内置失败文案。
+      # 失败文案可用变量：name、provider、configuration、error_type、error_message。
+      # %{变量名} 会替换为实际数据。缺少可选数据时，会省略对应行。
+      #
+      # 可用变量：
+      # name            : 应用名称
+      # build_type_name : 应用类型，例如 iOS、Android
+      # version_info    : 版本信息，例如 1.0.0(42)
+      # configuration   : 构建配置，例如 Debug、Release
+      # build_size_mb   : 应用大小，例如 39.5MB
+      # build_updated   : 更新时间
+      # description     : 本次更新内容
+      # password        : 安装密码或密码设置状态
+      # url             : 应用下载链接
+    TEXT
+
+    module_function
+
+    def path(project_dir = Dir.pwd)
+      File.join(File.expand_path(project_dir), "appship", "message.yml")
+    end
+
+    def default_path
+      File.join(__dir__, "default_message")
+    end
+
+    def init!(project_dir: Dir.pwd)
+      content = INSTRUCTIONS + <<~YAML
+
+        # 自定义终端文案时，去掉下面整段每行前的 "# "，保留正文缩进。
+        # cli_content: |
+        #   🚀 %{name} 发布成功
+        #   版本：%{version_info}
+        #   更新内容：%{description}
+        #   下载地址：%{url}
+
+        # wechat_webhook_success_content: ""    # 企微成功文案
+        # wechat_webhook_failure_content: ""    # 企微失败文案
+
+        # dingtalk_webhook_success_content: ""  # 钉钉成功文案
+        # dingtalk_webhook_failure_content: ""  # 钉钉失败文案
+
+        # feishu_webhook_success_content: ""    # 飞书成功文案
+        # feishu_webhook_failure_content: ""    # 飞书失败文案
+
+        # 默认发送纯文本；成功通知可按平台切换消息格式。
+        # wechat_webhook_format: markdown  # 企微：text 或 markdown
+        # feishu_webhook_format: post      # 飞书：text 或 post（富文本）
+      YAML
+      selected = "#{path(project_dir)}.sample"
+      FileUtils.mkdir_p(File.dirname(selected), mode: 0o700)
+      File.open(selected, "wx", 0o600) { |file| file.write(content) }
+      selected
+    rescue Errno::EEXIST
+      regular_file!(selected)
+      selected
+    rescue SystemCallError => e
+      raise ConfigurationError, "消息模板初始化失败: #{e.message}"
+    end
+
+    def template
+      templates.fetch("cli_content")
+    end
+
+    def templates
+      selected = path
+      unless File.exist?(selected) || File.symlink?(selected)
+        legacy = File.join(File.dirname(selected), "message")
+        selected = File.exist?(legacy) || File.symlink?(legacy) ? legacy : default_path
+        regular_file!(selected)
+        return { "cli_content" => parse(File.read(selected, encoding: "UTF-8"), selected, legacy: true) }
+      end
+
+      data = load_yaml(selected)
+      unless (data.keys - CONTENT_FIELDS - FAILURE_FIELDS - FORMATS.keys).empty?
+        raise ConfigurationError, "消息模板包含未知字段: #{selected}"
+      end
+
+      data = data.slice(*CONTENT_FIELDS, *FORMATS.keys).reject do |key, value|
+        next true if value.nil?
+        raise ConfigurationError, "消息模板 #{key} 必须是字符串: #{selected}" unless value.is_a?(String)
+
+        value.strip.empty?
+      end
+      FORMATS.each do |key, formats|
+        next unless data.key?(key) && !formats.include?(data[key])
+
+        raise ConfigurationError, "#{key} 仅支持 #{formats.join(" 或 ")}: #{selected}"
+      end
+      data["cli_content"] ||= File.read(default_path, encoding: "UTF-8")
+      CONTENT_FIELDS.each do |key|
+        parse(data[key], "#{selected} (#{key})") if data.key?(key)
+      end
+      data
+    rescue SystemCallError => e
+      raise ConfigurationError, "消息模板读取失败: #{e.message}"
+    end
+
+    def failure_templates(project_dir: Dir.pwd)
+      selected = path(project_dir)
+      return {} unless File.exist?(selected) || File.symlink?(selected)
+
+      load_yaml(selected).slice(*FAILURE_FIELDS).each_with_object({}) do |(key, body), templates|
+        next if body.nil? || (body.is_a?(String) && body.strip.empty?)
+        raise ConfigurationError unless body.is_a?(String)
+
+        templates[key] = parse(body, selected, variables: FAILURE_VARIABLES)
+      rescue ConfigurationError
+        warn "⚠️ #{key} 无效，使用内置失败文案"
+      end
+    rescue ConfigurationError
+      warn "⚠️ 无法读取失败消息模板，使用内置失败文案"
+      {}
+    end
+
+    def load_yaml(selected)
+      regular_file!(selected)
+      content = File.read(selected, encoding: "UTF-8")
+      raise ConfigurationError, "消息模板必须使用 UTF-8 编码: #{selected}" unless content.valid_encoding?
+
+      data = YAML.safe_load(content, permitted_classes: [], aliases: false)
+      return {} if data.nil?
+      raise ConfigurationError, "消息模板必须是 YAML 对象: #{selected}" unless data.is_a?(Hash)
+
+      data
+    rescue Psych::Exception
+      raise ConfigurationError, "消息模板 YAML 格式无效: #{selected}"
+    rescue SystemCallError => e
+      raise ConfigurationError, "消息模板读取失败: #{e.message}"
+    end
+
+    def parse(content, source, legacy: false, variables: VARIABLES)
+      raise ConfigurationError, "消息模板必须使用 UTF-8 编码: #{source}" unless content.valid_encoding?
+
+      body = content.delete_prefix("\uFEFF")
+      if legacy && body.lstrip.start_with?("/*")
+        comment_end = body.index("*/")
+        raise ConfigurationError, "消息模板备注缺少 */: #{source}" unless comment_end
+
+        body = body[(comment_end + 2)..].sub(/\A[ \t]*\r?\n/, "")
+      end
+      raise ConfigurationError, "消息模板正文不能为空: #{source}" if body.strip.empty?
+
+      unknown = body.scan(PLACEHOLDER).flatten.uniq - variables
+      unless unknown.empty?
+        raise ConfigurationError, "消息模板包含未知变量 #{unknown.join(", ")}: #{source}\n可用变量: #{variables.join(", ")}"
+      end
+      if body.gsub(PLACEHOLDER, "").include?("%{")
+        raise ConfigurationError, "消息模板变量缺少右花括号 }: #{source}"
+      end
+      body
+    end
+
+    def render(values)
+      render_text(template, values)
+    end
+
+    def render_text(body, values)
+      body.lines.filter_map do |line|
+        keys = line.scan(PLACEHOLDER).flatten
+        next if keys.any? { |key| values.fetch(key.to_sym).nil? }
+
+        line.gsub(PLACEHOLDER) { values.fetch(Regexp.last_match(1).to_sym).to_s }
+      end.join
+    end
+
+    def regular_file!(file)
+      unless File.file?(file) && !File.symlink?(file)
+        raise ConfigurationError, "消息模板必须是普通文件: #{file}"
+      end
+    end
+  end
+end