@ranger1/dx 0.1.65 → 0.1.67

package/codex/skills/doctor/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: doctor
+description: Use when 需要在本机一次性体检并修复 Codex 开发环境，包括 python3/python 别名、dx 初始化、agent-browser+Chromium、ripgrep 与 multi_agent 特性状态。
+---
+
+# Doctor
+
+## 概览
+
+执行本技能时，优先运行 `scripts/doctor.sh`，由脚本完成并行检测、自动修复、最多三轮重试与最终报告。
+
+## 适用场景
+
+- 新机器初始化 Codex 开发环境。
+- 发现命令缺失或版本漂移，希望一次性修复。
+- 需要确认 `codex features list` 中 `multi_agent` 为 `experimental true`。
+
+## 执行步骤
+
+1. 直接运行：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+bash "$CODEX_HOME/skills/doctor/scripts/doctor.sh"
+```
+
+2. 若需限制轮次（默认 3）：
+
+```bash
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+bash "$CODEX_HOME/skills/doctor/scripts/doctor.sh" --max-rounds 3
+```
+
+## 脚本职责
+
+- 并行检测：`python3`、`python` 别名、`pnpm`、`dx`、`agent-browser`、`rg`、`multi_agent`。
+- 自动修复：按平台选择安装器修复缺失项。
+- 强制执行：每轮都运行 `pnpm add -g @ranger1/dx@latest && dx initial`。
+- agent-browser：安装/升级并执行 Chromium 安装。
+- 结果输出：展示每项状态、版本、关键信息；全部通过则退出 0，否则最多三轮后退出 1。
+
+## 注意
+
+- 某些安装步骤可能需要管理员权限（例如 `sudo` 或 Homebrew 写权限）。
+- 若系统缺少包管理器，脚本会给出明确失败原因。

package/codex/skills/doctor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Doctor"
+  short_description: "并行检测并自动修复 Codex 开发环境关键依赖与特性开关"
+  default_prompt: "使用 $doctor 对当前系统执行并行体检、自动修复与三轮内收敛验证，并输出最终版本报告。"

package/codex/skills/doctor/scripts/doctor.sh

@@ -0,0 +1,386 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+MAX_ROUNDS=3
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --max-rounds)
+      MAX_ROUNDS="${2:-3}"
+      shift 2
+      ;;
+    *)
+      shift
+      ;;
+  esac
+done
+
+if ! [[ "$MAX_ROUNDS" =~ ^[0-9]+$ ]] || [[ "$MAX_ROUNDS" -lt 1 ]]; then
+  echo "[doctor] --max-rounds 必须是正整数" >&2
+  exit 2
+fi
+
+CACHE_ROOT="${PWD}/.cache/doctor"
+mkdir -p "$CACHE_ROOT"
+
+LAST_CHECK_DIR=""
+DX_FORCE_OK=0
+DX_FORCE_MSG=""
+
+run_silent() {
+  "$@" >/dev/null 2>&1
+}
+
+detect_pkg_manager() {
+  if command -v brew >/dev/null 2>&1; then echo "brew"; return; fi
+  if command -v apt-get >/dev/null 2>&1; then echo "apt"; return; fi
+  if command -v dnf >/dev/null 2>&1; then echo "dnf"; return; fi
+  if command -v yum >/dev/null 2>&1; then echo "yum"; return; fi
+  if command -v pacman >/dev/null 2>&1; then echo "pacman"; return; fi
+  echo "none"
+}
+
+install_python3() {
+  local pm
+  pm="$(detect_pkg_manager)"
+  case "$pm" in
+    brew)
+      brew install python
+      ;;
+    apt)
+      sudo apt-get update && sudo apt-get install -y python3 python3-venv python3-pip
+      ;;
+    dnf)
+      sudo dnf install -y python3 python3-pip
+      ;;
+    yum)
+      sudo yum install -y python3 python3-pip
+      ;;
+    pacman)
+      sudo pacman -Sy --noconfirm python
+      ;;
+    *)
+      echo "未检测到可用包管理器，无法安装 python3" >&2
+      return 1
+      ;;
+  esac
+}
+
+ensure_python_alias() {
+  local py3 py3_dir target_dir target
+  py3="$(command -v python3 || true)"
+  if [[ -z "$py3" ]]; then
+    echo "python3 不存在，无法创建 python 别名" >&2
+    return 1
+  fi
+
+  if command -v python >/dev/null 2>&1; then
+    return 0
+  fi
+
+  py3_dir="$(dirname "$py3")"
+  if [[ -w "$py3_dir" ]]; then
+    target_dir="$py3_dir"
+  elif [[ -w "/usr/local/bin" ]]; then
+    target_dir="/usr/local/bin"
+  elif [[ -w "/opt/homebrew/bin" ]]; then
+    target_dir="/opt/homebrew/bin"
+  else
+    target_dir="$HOME/.local/bin"
+    mkdir -p "$target_dir"
+  fi
+
+  target="$target_dir/python"
+  ln -sf "$py3" "$target"
+
+  if [[ "$target_dir" == "$HOME/.local/bin" ]]; then
+    export PATH="$HOME/.local/bin:$PATH"
+  fi
+
+  command -v python >/dev/null 2>&1
+}
+
+install_rg() {
+  local pm
+  pm="$(detect_pkg_manager)"
+  case "$pm" in
+    brew)
+      brew install ripgrep
+      ;;
+    apt)
+      sudo apt-get update && sudo apt-get install -y ripgrep
+      ;;
+    dnf)
+      sudo dnf install -y ripgrep
+      ;;
+    yum)
+      sudo yum install -y ripgrep
+      ;;
+    pacman)
+      sudo pacman -Sy --noconfirm ripgrep
+      ;;
+    *)
+      echo "未检测到可用包管理器，无法安装 rg" >&2
+      return 1
+      ;;
+  esac
+}
+
+install_pnpm() {
+  if command -v pnpm >/dev/null 2>&1; then
+    return 0
+  fi
+
+  if command -v npm >/dev/null 2>&1; then
+    npm install -g pnpm@latest
+  elif command -v brew >/dev/null 2>&1; then
+    brew install pnpm
+  else
+    echo "缺少 npm/brew，无法安装 pnpm" >&2
+    return 1
+  fi
+}
+
+ensure_agent_browser() {
+  if command -v npm >/dev/null 2>&1; then
+    npm install -g agent-browser@latest
+  elif command -v pnpm >/dev/null 2>&1; then
+    pnpm add -g agent-browser@latest
+  elif command -v brew >/dev/null 2>&1; then
+    brew install agent-browser
+  else
+    echo "缺少 npm/pnpm/brew，无法安装 agent-browser" >&2
+    return 1
+  fi
+
+  if ! command -v agent-browser >/dev/null 2>&1; then
+    echo "agent-browser 安装后仍不可用" >&2
+    return 1
+  fi
+
+  if ! run_silent agent-browser install; then
+    run_silent agent-browser install --with-deps || {
+      echo "agent-browser Chromium 安装失败" >&2
+      return 1
+    }
+  fi
+}
+
+ensure_multi_agent() {
+  if ! command -v codex >/dev/null 2>&1; then
+    echo "codex 命令不存在" >&2
+    return 1
+  fi
+  codex features enable multi_agent >/dev/null 2>&1 || true
+  local line
+  line="$(codex features list 2>/dev/null | awk '$1=="multi_agent" {print $0}')"
+  [[ -n "$line" ]] || return 1
+  echo "$line" | grep -E "experimental[[:space:]]+true" >/dev/null 2>&1
+}
+
+force_dx() {
+  if ! install_pnpm; then
+    DX_FORCE_OK=0
+    DX_FORCE_MSG="pnpm 不可用，无法执行 dx 强制初始化"
+    return 1
+  fi
+
+  if pnpm add -g @ranger1/dx@latest >/dev/null 2>&1 && dx initial >/dev/null 2>&1; then
+    DX_FORCE_OK=1
+    DX_FORCE_MSG="已执行 pnpm add -g @ranger1/dx@latest && dx initial"
+    return 0
+  fi
+
+  DX_FORCE_OK=0
+  DX_FORCE_MSG="强制命令执行失败：pnpm add -g @ranger1/dx@latest && dx initial"
+  return 1
+}
+
+write_check_file() {
+  local key="$1" ok="$2" ver="$3" msg="$4" file="$5"
+  printf '%s|%s|%s|%s\n' "$key" "$ok" "$ver" "$msg" >"$file"
+}
+
+read_field() {
+  local key="$1" field="$2"
+  local f="$LAST_CHECK_DIR/${key}.res"
+  if [[ ! -f "$f" ]]; then
+    echo ""
+    return 0
+  fi
+  awk -F'|' -v idx="$field" '{print $idx}' "$f"
+}
+
+check_ok() {
+  local key="$1"
+  [[ "$(read_field "$key" 2)" == "1" ]]
+}
+
+run_parallel_checks() {
+  local round="$1"
+  local dir="$CACHE_ROOT/round-${round}"
+  mkdir -p "$dir"
+
+  (
+    if command -v python3 >/dev/null 2>&1; then
+      write_check_file "python3" "1" "$(python3 --version 2>&1 | head -n1)" "ok" "$dir/python3.res"
+    else
+      write_check_file "python3" "0" "" "python3 未安装" "$dir/python3.res"
+    fi
+  ) &
+
+  (
+    if command -v python >/dev/null 2>&1; then
+      write_check_file "python_alias" "1" "$(python --version 2>&1 | head -n1)" "ok" "$dir/python_alias.res"
+    else
+      write_check_file "python_alias" "0" "" "python 别名不可用" "$dir/python_alias.res"
+    fi
+  ) &
+
+  (
+    if command -v pnpm >/dev/null 2>&1; then
+      write_check_file "pnpm" "1" "pnpm $(pnpm --version 2>/dev/null | head -n1)" "ok" "$dir/pnpm.res"
+    else
+      write_check_file "pnpm" "0" "" "pnpm 未安装" "$dir/pnpm.res"
+    fi
+  ) &
+
+  (
+    if command -v dx >/dev/null 2>&1; then
+      local v
+      v="$(dx --version 2>/dev/null | head -n1 || true)"
+      if [[ -z "$v" ]]; then
+        v="$(dx -v 2>/dev/null | head -n1 || true)"
+      fi
+      write_check_file "dx" "1" "${v:-dx (版本未知)}" "ok" "$dir/dx.res"
+    else
+      write_check_file "dx" "0" "" "dx 未安装" "$dir/dx.res"
+    fi
+  ) &
+
+  (
+    if command -v agent-browser >/dev/null 2>&1; then
+      write_check_file "agent_browser" "1" "$(agent-browser --version 2>/dev/null | head -n1)" "ok" "$dir/agent_browser.res"
+    else
+      write_check_file "agent_browser" "0" "" "agent-browser 未安装" "$dir/agent_browser.res"
+    fi
+  ) &
+
+  (
+    if command -v rg >/dev/null 2>&1; then
+      write_check_file "rg" "1" "$(rg --version 2>/dev/null | head -n1)" "ok" "$dir/rg.res"
+    else
+      write_check_file "rg" "0" "" "rg 未安装" "$dir/rg.res"
+    fi
+  ) &
+
+  (
+    if command -v codex >/dev/null 2>&1; then
+      local line
+      line="$(codex features list 2>/dev/null | awk '$1=="multi_agent" {print $0}')"
+      if [[ -n "$line" ]] && echo "$line" | grep -E "experimental[[:space:]]+true" >/dev/null 2>&1; then
+        write_check_file "multi_agent" "1" "$line" "ok" "$dir/multi_agent.res"
+      else
+        write_check_file "multi_agent" "0" "${line:-missing}" "multi_agent 不是 experimental true" "$dir/multi_agent.res"
+      fi
+    else
+      write_check_file "multi_agent" "0" "" "codex 命令不存在" "$dir/multi_agent.res"
+    fi
+  ) &
+
+  wait
+  LAST_CHECK_DIR="$dir"
+}
+
+all_good() {
+  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent"
+  local k
+  for k in $keys; do
+    if ! check_ok "$k"; then
+      return 1
+    fi
+  done
+  [[ "$DX_FORCE_OK" == "1" ]]
+}
+
+print_report() {
+  local round="$1"
+  echo
+  echo "===== Doctor 报告（第 ${round} 轮）====="
+  printf '%-14s | %-4s | %-40s | %s\n' "检查项" "状态" "版本" "说明"
+  printf '%-14s-+-%-4s-+-%-40s-+-%s\n' "--------------" "----" "----------------------------------------" "------------------------------"
+
+  local keys="python3 python_alias pnpm dx agent_browser rg multi_agent"
+  local k ok txt ver msg
+  for k in $keys; do
+    ok="$(read_field "$k" 2)"
+    txt="FAIL"
+    [[ "$ok" == "1" ]] && txt="PASS"
+    ver="$(read_field "$k" 3)"
+    msg="$(read_field "$k" 4)"
+    printf '%-14s | %-4s | %-40s | %s\n' "$k" "$txt" "$ver" "$msg"
+  done
+
+  if [[ "$DX_FORCE_OK" == "1" ]]; then
+    printf '%-14s | %-4s | %-40s | %s\n' "dx_force" "PASS" "@ranger1/dx@latest" "$DX_FORCE_MSG"
+  else
+    printf '%-14s | %-4s | %-40s | %s\n' "dx_force" "FAIL" "@ranger1/dx@latest" "$DX_FORCE_MSG"
+  fi
+
+  if command -v node >/dev/null 2>&1; then
+    echo "node: $(node -v 2>/dev/null | head -n1)"
+  fi
+  if command -v npm >/dev/null 2>&1; then
+    echo "npm: $(npm -v 2>/dev/null | head -n1)"
+  fi
+}
+
+for round in $(seq 1 "$MAX_ROUNDS"); do
+  echo "[doctor] 第 ${round}/${MAX_ROUNDS} 轮：并行检测"
+  run_parallel_checks "$round"
+
+  echo "[doctor] 第 ${round}/${MAX_ROUNDS} 轮：修复阶段"
+
+  if ! check_ok "python3"; then
+    echo "[doctor] 安装 python3"
+    install_python3 || true
+  fi
+
+  if ! check_ok "python_alias"; then
+    echo "[doctor] 建立 python -> python3 调用能力"
+    ensure_python_alias || true
+  fi
+
+  if ! check_ok "rg"; then
+    echo "[doctor] 安装 rg"
+    install_rg || true
+  fi
+
+  if ! check_ok "agent_browser"; then
+    echo "[doctor] 安装/升级 agent-browser 并安装 Chromium"
+    ensure_agent_browser || true
+  else
+    echo "[doctor] agent-browser 已存在，执行升级与 Chromium 安装"
+    ensure_agent_browser || true
+  fi
+
+  if ! check_ok "multi_agent"; then
+    echo "[doctor] 修正 multi_agent 特性开关"
+    ensure_multi_agent || true
+  fi
+
+  echo "[doctor] 强制执行 dx 安装与初始化"
+  force_dx || true
+
+  echo "[doctor] 第 ${round}/${MAX_ROUNDS} 轮：复检"
+  run_parallel_checks "${round}-post"
+  print_report "$round"
+
+  if all_good; then
+    echo "[doctor] 全部检查通过"
+    exit 0
+  fi
+
+done
+
+echo "[doctor] 达到最大轮次 ${MAX_ROUNDS}，仍有未通过项"
+exit 1

package/codex/skills/git-release/SKILL.md

@@ -7,7 +7,7 @@ description: 在 Git 仓库中执行标准化版本发布流程并自动生成
 
 ## 目标
 
-在 `release/vX.Y.Z` 或 `release/vX.Y.Z-<prerelease>.N` 分支上，完成从发布前检查到 GitHub Release 创建的全流程。
+在 `release/vX.Y.Z` 或 `release/vX.Y.Z-<prerelease>.N` 分支上，完成从发布前检查到 GitHub Release 创建的全流程；若当前不在 release 分支，则先从最新 `main` 自动创建目标 release 分支。
 
 ## 执行原则
 
@@ -23,12 +23,17 @@ description: 在 Git 仓库中执行标准化版本发布流程并自动生成
 1. 检查工作区是否干净：`git status --porcelain`。
 2. 若存在未提交变更，列出文件并终止流程。
 3. 检查当前分支：`git branch --show-current`。
-4. 仅接受以下正则：`^release/v\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$`。
-5. 从分支名提取版本号，例如：
+4. 若当前分支不匹配 `^release/v\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$`，执行以下自动建分支流程（仅此场景执行）：
+- 同步远程与本地 `main`：`git fetch origin main --tags && git checkout main && git pull --ff-only origin main`。
+- 获取上一个已发布版本（优先）：`gh release list --limit 1 --json tagName,publishedAt --jq '.[0].tagName'`；若为空则回退 `git describe --tags --abbrev=0`。
+- 解析版本号并将最后一位加一（例如 `v1.2.3 -> v1.2.4`），得到新分支版本 `<NEXT_VERSION>`。
+- 创建并切换分支：`git checkout -b release/v<NEXT_VERSION>`。
+5. 再次检查当前分支，必须匹配：`^release/v\d+\.\d+\.\d+(-(alpha|beta|rc)\.\d+)?$`。
+6. 从分支名提取版本号，例如：
 - `release/v1.2.3` -> `v1.2.3` -> `1.2.3`
 - `release/v1.2.3-beta.2` -> `v1.2.3-beta.2` -> `1.2.3-beta.2`
-6. 检查目标 tag 是否已存在：`git tag -l "v<VERSION>"`。
-7. 向用户确认版本号；若用户修改版本号，重新校验格式与 tag 冲突。
+7. 检查目标 tag 是否已存在：`git tag -l "v<VERSION>"`。
+8. 向用户确认版本号；若用户修改版本号，重新校验格式与 tag 冲突。
 
 ### 二、更新版本号
 
@@ -156,7 +161,7 @@ EOF
 以下任一情况出现时终止流程并给出明确原因：
 
 - 工作区存在未提交修改。
-- 当前分支不符合 release 分支命名规则。
+- 当前分支不符合 release 分支命名规则，且无法从 `main` 自动创建 release 分支。
 - 版本号格式非法或与现有 tag 冲突。
 - 自上次发布以来无新提交。
 

package/codex/skills/online-debug-guard/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: online-debug-guard
+description: 在线调试安全护栏技能。用于排查数据库、Redis、服务配置等线上或准线上问题时，强制执行环境识别、模式校验和本地环境文件存在性检查，防止误连误操作。触发场景：用户提到在线调试、连库排查、查 Redis、生产环境排障、按指定环境排查问题。
+---
+
+# 在线调试安全护栏
+
+## 概览
+
+执行在线调试前先做硬性门禁，未通过即停止。仅在门禁通过后再进行排查动作，默认使用只读方式获取信息。
+
+## 执行流程（必须按顺序）
+
+1. 识别目标环境
+2. 校验协作模式与环境文件
+3. 门禁通过后执行调试
+
+任一步失败都必须立即终止，不得继续后续步骤。
+
+## 步骤 1：识别目标环境
+
+只接受 `development`、`staging`、`production` 三种值。
+
+如果用户调用技能时未显式给出环境：
+- 先询问用户当前环境（只给这三个选项）。
+- 若用户未回复或信息仍不明确，则默认 `development`，并明确告知本次按 `development` 执行。
+
+如果用户给了其他环境名（例如 `prod1`、`test`）：
+- 立即终止。
+- 明确提示“环境无效，仅支持 development/staging/production”。
+
+## 步骤 2：门禁校验
+
+### 2.1 production 环境的模式限制
+
+当环境是 `production` 时，必须先确认当前处于 `Plan` 模式。
+
+如果不是 `Plan` 模式：
+- 立即终止。
+- 使用如下提示：
+
+```text
+已终止：当前为 production 环境，但会话不在 Plan 模式。
+请切换到 Plan 模式后再继续在线调试。
+```
+
+### 2.2 环境文件存在性校验
+
+将项目根目录作为基准，检查以下文件：
+- `.env.${ENV_NAME}`
+- `.env.${ENV_NAME}.local`
+
+校验规则：
+- 两个文件都必须存在。
+- 若 `.env.${ENV_NAME}.local` 不存在，视为环境指定有误，立即终止。
+
+终止提示模板：
+
+```text
+已终止：未找到 .env.${ENV_NAME}.local，判定环境指定有误。
+请确认环境仅为 development/staging/production，且对应本地覆盖文件存在。
+```
+
+## 步骤 3：在线调试执行规范
+
+门禁通过后，才允许执行调试。
+
+调试时遵循：
+- 默认只读：优先使用查询、检查、对比，不做写入。
+- 允许使用环境文件中的连接信息访问数据库、Redis 等依赖来定位问题。
+- 在未获用户明确授权前，禁止执行会改变状态的操作（例如写库、删键、迁移、重启、发布）。
+- 输出结论时必须包含：目标环境、已通过的门禁项、关键证据、下一步建议。
+
+## 标准开场模板
+
+```text
+开始在线调试前先执行安全门禁：
+1) 确认环境（development/staging/production）
+2) production 场景校验是否为 Plan 模式
+3) 校验 .env.${ENV_NAME} 与 .env.${ENV_NAME}.local 是否存在
+任一失败将立即终止，避免误操作。
+```

package/codex/skills/online-debug-guard/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Online Debug Guard"
+  short_description: "Guarded workflow for environment-aware online debugging"
+  default_prompt: "执行安全的在线调试流程，先判定环境与模式，再执行只读排查。"

package/lib/vercel-deploy.js

@@ -169,8 +169,13 @@ function readLinkedProjectContext(contextRoot) {
 }
 
 function clearLinkedProjectContext(contextRoot) {
-  const path = join(contextRoot, VERCEL_PROJECT_LINK_PATH)
-  rmSync(path, { force: true })
+  const linkDir = join(contextRoot, '.vercel')
+  rmSync(linkDir, { force: true, recursive: true })
+}
+
+function clearVercelBuildOutput(contextRoot) {
+  const outputDir = join(contextRoot, '.vercel', 'output')
+  rmSync(outputDir, { force: true, recursive: true })
 }
 
 async function runVercel(args, options = {}) {
@@ -376,9 +381,8 @@ export async function deployToVercel(target, options = {}) {
         `检测到 ${VERCEL_PROJECT_LINK_PATH} 但解析失败: ${linkedContext.parseError.message}`
       )
       if (strictContext) {
-        logger.error('strictContext 已开启，已阻止继续部署以避免回退污染')
-        process.exitCode = 1
-        return
+        logger.warn('strictContext 已开启：自动清理 .vercel 后继续部署')
+        clearLinkedProjectContext(prebuiltCwd)
       }
     }
 
@@ -389,11 +393,11 @@ export async function deployToVercel(target, options = {}) {
         `  本地链接: org=${maskIdentifier(linkedContext.orgId)} project=${maskIdentifier(linkedContext.projectId)}`
       )
       if (strictContext) {
-        logger.error('strictContext 已开启，已阻止部署（请清理 .vercel 或修正环境变量）')
-        process.exitCode = 1
-        return
+        logger.warn('strictContext 已开启：检测到冲突，自动清理 .vercel 后继续部署')
+        clearLinkedProjectContext(prebuiltCwd)
+      } else {
+        logger.warn('strictContext 已关闭，继续执行（可能存在误部署风险）')
       }
-      logger.warn('strictContext 已关闭，继续执行（可能存在误部署风险）')
     }
 
     logger.info(
@@ -432,6 +436,8 @@ export async function deployToVercel(target, options = {}) {
       if (strictContext && process.env.DX_VERCEL_KEEP_LINK !== '1') {
         clearLinkedProjectContext(prebuiltCwd)
       }
+      // 避免 Vercel 本地预构建产物残留导致 EEXIST（如 _global-error.func 符号链接冲突）
+      clearVercelBuildOutput(prebuiltCwd)
 
       // 第一步：本地构建
       logger.step(`本地构建 ${t} (${environment})`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "type": "module",
   "license": "MIT",
   "repository": {