✨ feat: 添加微信小程序调试工具和完整参数参考文档

.codex/skills/shz-full-development/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: shz-full-development
+description: 仅当用户在当前请求中明确授权完成 SHZ 全流程开发时使用。支持代码实现、本地验证、测试环境 SQL 执行、测试环境部署、Chrome DevTools/日志/只读数据库调试、功能验收、代码提交以及测试通过后的正式 SQL 生成和执行状态记录。没有当前请求中的明确全流程授权时，不得使用此 skill 执行提交、写入 SQL、远程部署或服务重启。
+---
+
+# SHZ 全流程开发
+
+## 授权门槛
+
+只有当用户在**当前请求**中明确要求完成全流程开发，并明确允许相应远程操作时，才能使用此 skill。以下表述才算明确授权：允许提交代码、执行测试环境 SQL、部署测试环境、调试验证，或明确要求执行完整开发流程。
+
+以下表述不构成全流程授权：修复问题、完成开发、测试一下、准备上线、给出部署命令、描述 SQL、验证修复或“继续处理”。没有明确授权时，使用 `$shz-pc-debug`、`$query-shz-highgo` 和 `$inspect-shz-logs` 完成只读诊断、本地修改和验证。
+
+授权范围必须逐项确认：
+
+- 代码修改：允许修改哪些仓库和模块；
+- 测试 SQL：允许在测试环境写入哪些数据库和 SQL 文件；
+- 测试部署：允许部署后端、PC 前端或两者；
+- 测试调试：允许使用哪个测试角色和页面；
+- 正式 SQL：是否只生成正式 SQL，还是额外允许执行正式环境 SQL。
+
+正式环境 SQL 执行和生产部署不从“全流程开发”自动推断。它们必须有当前请求中的单独明确授权，并且必须提供目标和精确执行命令或批准的项目流程。
+
+## 硬性安全规则
+
+1. 默认使用测试环境，生产环境保持只读。
+2. 不得读取、复制、打印、提交或报告密码、Token、cookies、授权请求头或无关个人数据。
+3. 远程写入操作必须使用项目已有的受保护流程，不得临时拼接绕过安全检查的 SSH、psql 或部署命令。
+4. 每个远程操作前确认目标环境、目标组件、SQL 文件、角色和授权范围。
+5. 任一 SQL、构建、部署或功能验证失败时立即停止后续晋级，不得生成“已通过”或“已执行”的状态标记。
+6. 不得把测试环境执行成功推断为正式环境执行成功。
+7. 不得把正式 SQL 已生成推断为正式 SQL 已执行。
+
+## 全流程顺序
+
+严格按以下顺序执行：
+
+1. **确认范围和授权**：确认角色、环境、页面/接口、代码仓库、SQL 文件、目标组件和允许的远程操作。阅读 [references/deployment.md](references/deployment.md) 和 [references/sql-workflow.md](references/sql-workflow.md)。
+2. **检查工作区**：分别检查 `shz-backend` 和涉及的 `shz-admin` 工作树、`git status` 和 diff，保留用户已有改动。按 [shz-pc-debug 的项目结构参考](../shz-pc-debug/references/project-topology.md) 选择最小范围。
+3. **调查和实现**：使用 CodeGraph 定位代码；没有可用索引时使用 `rg`。按需调用 `$shz-pc-debug` 复现和定位、`$query-shz-highgo` 查询只读数据、`$inspect-shz-logs` 检查日志。实施最小代码修改。
+4. **本地验证**：运行变更模块适用的测试、构建、类型检查、lint 或其他静态检查。未通过时先修复，不得执行远程写操作。
+5. **测试 SQL 执行**：按照 [references/sql-workflow.md](references/sql-workflow.md) 检查 SQL、记录执行目标，并且只在测试环境执行。成功后将 SQL 文件标记为测试已执行，但不得标记为正式已执行。
+6. **中文代码提交**：本地代码和测试 SQL 验证通过后，检查 diff，使用中文提交信息创建聚焦 commit。提交规则见“代码提交规则”。除非用户明确要求 push，否则不得推送。
+7. **部署测试环境**：只部署当前请求明确授权的组件。部署命令和授权条件见 [references/deployment.md](references/deployment.md)。
+8. **测试环境调试和验收**：使用隔离 Chrome 会话复现目标流程，检查 DOM、控制台、网络、截图、日志和必要的只读数据库状态。测试失败时停止，不得生成正式 SQL。
+9. **生成正式 SQL**：只有当所有约定功能和回归检查通过后，才从已测试 SQL 生成正式执行 SQL，并按 [references/sql-workflow.md](references/sql-workflow.md) 更新内容和文件名。此时只能标记为 `test-verified-production-ready`，不能标记为正式已执行。
+10. **正式环境 SQL（可选）**：只有当前请求单独明确授权正式 SQL 执行时，才执行正式环境 SQL。执行成功后更新 SQL 状态注释和文件名为 `test-and-production-executed`。未获授权时保留正式 SQL 供人工审批，不得执行。
+11. **最终报告**：报告测试环境、提交 hash、测试 SQL 执行结果、部署组件、浏览器验证结果、正式 SQL 文件状态以及未执行的正式环境操作。
+
+## 代码提交规则
+
+代码提交必须使用中文。提交前检查以下要求：
+
+- commit subject 的实际说明必须是中文；
+- commit body（如有）必须使用中文；
+- 可以保留 `feat:`、`fix:`、`refactor:`、`chore:` 等固定类型前缀，但冒号后的说明必须是中文；
+- 禁止使用纯英文提交信息；
+- 每次提交只包含当前任务相关文件，不得提交密码、Token、日志、截图、临时构建产物或无关改动；
+- 未经用户明确要求不得 push。
+
+推荐格式：
+
+```text
+feat: 新增户外招聘会小程序二维码接口
+fix: 修复企业招聘会图片地址处理
+chore: 更新测试环境迁移状态
+```
+
+## 失败和回滚处理
+
+- 本地验证失败：不执行测试 SQL、不提交、不部署。
+- 测试 SQL 失败：停止部署，保留失败证据；只有修复 SQL 并重新通过测试执行后，才更新 SQL 状态。
+- 测试部署失败：检查有界测试日志，修复并重新本地验证；不得生成正式 SQL。
+- 浏览器功能验证失败：保留控制台、网络、DOM、截图和日志证据；不得标记为 `test-verified-production-ready`。
+- 正式 SQL 执行失败：立即停止，不得标记 `test-and-production-executed`；保留正式环境错误证据并等待用户决定回滚或修复。
+
+任何回滚或反向 SQL 都属于写入操作，必须在当前请求中获得明确授权，并单独记录目标环境和执行结果。

.codex/skills/shz-full-development/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "执行 SHZ 全流程开发"
+  short_description: "在明确授权后完成代码、测试SQL、测试部署与浏览器验证"
+  default_prompt: "使用 $shz-full-development 完成已明确授权的 SHZ 全流程开发，并先在测试环境验证。"

.codex/skills/shz-full-development/references/deployment.md

@@ -0,0 +1,39 @@
+# SHZ 全流程开发的部署规则
+
+## 测试部署授权
+
+只有当前请求明确授权全流程开发，并指出要部署的组件和测试环境时，才能执行测试部署。执行前检查相关仓库的 `git status` 和 diff，确认本地验证通过，确认没有密钥或无关改动。
+
+## 后端测试部署
+
+仅用于明确授权的 `shz-backend` 测试环境部署：
+
+```bash
+ssh root@47.111.103.66 sh /data/code/shz-backend/buildAndStart-test.sh
+```
+
+该命令会修改远程测试环境，并可能重启后端服务。完成后使用 Chrome DevTools 验证请求的测试路由；失败时使用 `$inspect-shz-logs` 读取有界的测试日志窗口。
+
+## PC 前端测试部署
+
+仅用于明确授权的 `shz-admin` PC 前端测试部署：
+
+```bash
+sh /Users/lapuda/code/shz-admin/scripts/deploy-frontend.sh
+```
+
+命令完成后使用 Chrome DevTools 重新加载并验证请求的 PC 测试路由。
+
+## 生产部署
+
+此 skill 不配置生产部署命令。生产基地址不是部署授权。除非当前请求明确授权生产部署、明确目标组件并提供精确命令，否则不得执行生产部署。
+
+## 部署后记录
+
+记录以下信息：
+
+1. 部署仓库和 commit SHA；
+2. 部署的组件；
+3. 测试环境和路由；
+4. 部署时间和结果；
+5. 失败时的日志位置和未完成的验证步骤。

.codex/skills/shz-full-development/references/sql-workflow.md

@@ -0,0 +1,111 @@
+# SHZ SQL 执行和状态管理
+
+## 适用范围
+
+此流程只适用于当前请求明确授权的全流程开发。`$query-shz-highgo` 仍然只用于只读查询；不得把只读查询脚本改造成写入脚本。写入 SQL 必须使用项目已有的、目标环境明确的受保护执行流程。
+
+## 执行前检查
+
+1. 确认 SQL 文件属于当前任务，并检查 `git status` 和 diff。
+2. 阅读 SQL 全文，确认目标 schema、表、权限、事务边界、依赖顺序和是否可重复执行。
+3. 优先使用事务、`ON_ERROR_STOP=1`、明确的 `search_path` 和项目已有的连接配置。
+4. 对 `DROP`、批量 `UPDATE`、批量 `DELETE`、权限变更和不可逆操作，先做最小只读检查；发现范围不明确时停止并要求用户确认。
+5. 不得把密码写入 SQL、命令行、日志或提交。
+
+## 测试环境执行阶段
+
+先在测试环境执行 SQL。对通用 SQL 文件，使用新 skill 的测试执行脚本，并保留显式确认开关：
+
+```bash
+CONFIRM_TEST_SQL=yes \
+.codex/skills/shz-full-development/scripts/execute-test-sql.sh \
+sql/migration_<feature>.sql
+```
+
+项目已有针对特定迁移的测试脚本时，优先使用该脚本。执行时记录但不泄露凭据：
+
+- SQL 文件路径和 commit（如果已经提交）；
+- 目标环境、数据库和 schema；
+- 执行时间；
+- 执行命令或受保护流程名称；
+- 成功/失败状态和简短响应摘要；
+- 执行后的只读验证查询。
+
+测试 SQL 成功后，将 SQL 文件头部状态更新为中文，例如：
+
+```sql
+-- 执行状态：测试环境已执行
+-- 测试环境：test
+-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
+-- 正式环境：未执行
+```
+
+然后将文件名标记为：
+
+```text
+migration_<feature>.test-executed.sql
+```
+
+不得在此阶段使用 `test-and-production-executed`，也不得声称正式环境已执行。
+
+## 功能测试通过后的正式 SQL 生成
+
+只有以下条件全部满足，才生成正式 SQL：
+
+1. 测试环境 SQL 执行成功；
+2. 后端或前端测试、构建和静态检查通过；
+3. 测试环境部署成功；
+4. 目标功能已通过 Chrome DevTools 流程验证；
+5. 相关控制台、网络、日志和只读数据库验证没有未解释的失败；
+6. 用户要求的回归范围已经完成。
+
+从测试 SQL 生成正式 SQL 时，保留业务语句和必要的中文状态说明，清除测试环境专属的临时数据、测试账号、测试地址和测试标识。正式 SQL 生成后，将状态更新为：
+
+```sql
+-- 执行状态：测试环境已执行，功能验证已通过，正式环境待执行
+-- 测试环境：test
+-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
+-- 功能验证时间：YYYY-MM-DD HH:MM:SS +0800
+-- 正式环境：待明确授权后执行
+```
+
+此时文件名使用：
+
+```text
+migration_<feature>.test-verified-production-ready.sql
+```
+
+该文件名表示“测试已执行且功能已验证，正式 SQL 已准备好”，不表示正式环境已经执行。
+
+## 正式环境执行后的最终状态
+
+正式环境 SQL 只有在当前请求单独明确授权后才能执行。执行成功后：
+
+1. 使用正式环境批准的执行流程，不得从测试命令或测试地址推导正式命令；
+2. 做最小只读验证，确认对象、字段、权限或数据状态符合预期；
+3. 在 SQL 文件头部补充正式执行环境和时间；
+4. 将文件名改为：
+
+   ```text
+   migration_<feature>.test-and-production-executed.sql
+   ```
+
+5. 只有在有成功执行证据时，才允许使用 `test-and-production-executed` 文件名。
+
+最终状态示例：
+
+```sql
+-- 执行状态：测试环境和正式环境均已执行
+-- 测试环境：test
+-- 测试执行时间：YYYY-MM-DD HH:MM:SS +0800
+-- 功能验证时间：YYYY-MM-DD HH:MM:SS +0800
+-- 正式环境：production
+-- 正式执行时间：YYYY-MM-DD HH:MM:SS +0800
+```
+
+## 失败时的文件状态
+
+- 测试执行失败：保留原文件名和失败记录，不得标记为测试已执行；
+- 测试成功但功能失败：最多保留 `test-executed`，不得生成 `test-verified-production-ready`；
+- 正式 SQL 已生成但未获正式执行授权：保留 `test-verified-production-ready`；
+- 正式执行失败：不得改名为 `test-and-production-executed`，保留失败证据并等待用户决定。

.codex/skills/shz-full-development/scripts/execute-test-sql.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# 在 SHZ 测试 HighGo 数据库执行指定 SQL 文件。
+# 仅支持测试环境；必须显式设置 CONFIRM_TEST_SQL=yes。
+set -Eeuo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P)"
+PROJECT_DIR="$(cd -- "$SCRIPT_DIR/../../../.." && pwd -P)"
+
+MIGRATION_FILE="${1:-}"
+PASSWORD_FILE="${HIGHGO_TEST_PASSWORD_FILE:-${HIGHGO_PASSWORD_FILE:-$PROJECT_DIR/.codex/skills/query-shz-highgo/.password}}"
+TEST_SSH_HOST="${HIGHGO_TEST_SSH_HOST:-root@47.111.103.66}"
+TEST_SSH_PORT="${HIGHGO_TEST_SSH_PORT:-22}"
+TEST_PSQL_PATH="${HIGHGO_TEST_PSQL_PATH:-/opt/HighGo4.5.7-see/bin/psql}"
+TEST_DB_HOST="${HIGHGO_TEST_DB_HOST:-127.0.0.1}"
+TEST_DB_PORT="${HIGHGO_TEST_DB_PORT:-5866}"
+TEST_DB_NAME="${HIGHGO_TEST_DB_NAME:-highgo}"
+TEST_DB_USER="${HIGHGO_TEST_DB_USER:-sysdba}"
+
+if [[ "${CONFIRM_TEST_SQL:-}" != "yes" ]]; then
+  echo '为防止误写测试数据库，请使用 CONFIRM_TEST_SQL=yes 执行。' >&2
+  exit 2
+fi
+
+if [[ -z "$MIGRATION_FILE" ]]; then
+  echo "用法：CONFIRM_TEST_SQL=yes $0 <sql-file>" >&2
+  exit 2
+fi
+
+if [[ ! -r "$MIGRATION_FILE" ]]; then
+  echo "SQL 文件不可读：$MIGRATION_FILE" >&2
+  exit 2
+fi
+
+if [[ ! -r "$PASSWORD_FILE" ]]; then
+  echo '测试数据库密码文件不可读。' >&2
+  exit 2
+fi
+
+command -v ssh >/dev/null 2>&1 || {
+  echo '缺少必要命令：ssh' >&2
+  exit 2
+}
+
+printf '执行测试数据库 SQL：%s\n' "$(basename "$MIGRATION_FILE")"
+{
+  cat "$PASSWORD_FILE"
+  printf '\n'
+  cat "$MIGRATION_FILE"
+} | ssh -o BatchMode=yes -o ConnectTimeout=20 -p "$TEST_SSH_PORT" "$TEST_SSH_HOST" \
+  "IFS= read -r PGPASSWORD; export PGPASSWORD; export PGOPTIONS='-c search_path=shz,public -c statement_timeout=30000'; exec '$TEST_PSQL_PATH' -X --no-psqlrc -h '$TEST_DB_HOST' -p '$TEST_DB_PORT' -U '$TEST_DB_USER' -d '$TEST_DB_NAME' -v ON_ERROR_STOP=1 -f -"
+
+printf '测试数据库 SQL 执行成功：%s\n' "$(basename "$MIGRATION_FILE")"