From 08ed396444d192818c1920e6a476db298c882bee Mon Sep 17 00:00:00 2001 From: kuaifan Date: Tue, 2 Jun 2026 02:14:36 +0000 Subject: [PATCH] =?UTF-8?q?feat(skill):=20=E6=96=B0=E5=A2=9E=E5=AE=89?= =?UTF-8?q?=E8=A3=85/=E6=9B=B4=E6=96=B0/=E4=BF=AE=E5=A4=8D=E6=9D=83?= =?UTF-8?q?=E9=99=90=E6=8A=80=E8=83=BD=EF=BC=8C=E5=9B=9B=E6=8A=80=E8=83=BD?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E7=B2=BE=E7=AE=80=E4=B8=BA=E5=91=BD=E4=BB=A4?= =?UTF-8?q?=E8=A7=A6=E5=8F=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - dootask-install：前置检查 + sudo ./cmd install（建库 + migrate --seed） - dootask-update：前置检查 + sudo ./cmd update，本地改动停下交用户决定 - dootask-fix-permission：对齐 install 赋权逻辑，chown + chmod 775，赋权不删数据 - 四个技能均为命令显式触发，description 去掉关键词堆砌，精简为一句功能说明 Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/dootask-fix-permission/SKILL.md | 76 +++++++++++++++++ .claude/skills/dootask-install/SKILL.md | 74 +++++++++++++++++ .claude/skills/dootask-release/SKILL.md | 2 +- .claude/skills/dootask-update/SKILL.md | 83 +++++++++++++++++++ 4 files changed, 234 insertions(+), 1 deletion(-) create mode 100644 .claude/skills/dootask-fix-permission/SKILL.md create mode 100644 .claude/skills/dootask-install/SKILL.md create mode 100644 .claude/skills/dootask-update/SKILL.md diff --git a/.claude/skills/dootask-fix-permission/SKILL.md b/.claude/skills/dootask-fix-permission/SKILL.md new file mode 100644 index 000000000..385fb7272 --- /dev/null +++ b/.claude/skills/dootask-fix-permission/SKILL.md @@ -0,0 +1,76 @@ +--- +name: dootask-fix-permission +description: 修复 DooTask 可写目录（bootstrap/cache、docker、public、storage）的属主/权限：chown 回当前用户 + 目录 chmod 775，对齐 install 的赋权逻辑，赋权不删数据。 +--- + +# DooTask 目录权限修复 + +容器内进程常以 **root** 写入挂载目录（`storage`、`public/uploads`、`bootstrap/cache` 等），导致宿主机当前用户对这些文件**没有写权限**，进而触发： + +- `./cmd install` 报「目录【xxx】权限不足」/ 目录权限检测失败 +- `./cmd build`（vite）报 `EACCES: permission denied, copyfile`（复制 `public/uploads/...` 时） +- Laravel 运行时写 `storage`/`bootstrap/cache` 失败 + +本技能**对齐 `./cmd install` 的目录赋权逻辑**：对四个可写目录做 `chmod 775`（目录）+ `chown` 回当前用户。 + +## 适用目录 + +与 install 一致的四个： + +``` +bootstrap/cache +docker +public # 含 public/uploads（真实上传数据） +storage +``` + +## 核心原则：赋权，不删数据 + +`public/uploads` 含真实上传文件（头像、附件等）。**永远优先 `chown` 改属主，不要删数据。** 即便用户说"清理一下"，也只允许清临时目录 `public/uploads/tmp`，**切勿**删 uploads 下其他内容。 + +## 前置检查 + +1. **工作目录**：在项目根（存在 `cmd` 且这四个目录在） +2. **sudo**：改属主需 root（当前文件多为 root 属主）。本机一般可免密 sudo；不行则经 docker 以 root 改权限 +3. 确认要修的范围：默认四个目录全修；若用户只想解 build 报错，也可只针对 `public`（含 `public/uploads`） + +检查通过后汇报将执行的命令，**向用户确认一次**再执行。 + +## 执行 + +确认后执行（属主修回当前用户，目录权限 775）： + +```shell +# 1) 属主修回当前用户（递归） +sudo chown -R "$(id -u):$(id -g)" bootstrap/cache docker public storage + +# 2) 目录权限 775（仅目录，对齐 install 的 `find -type d -exec chmod 775`） +find bootstrap/cache docker public storage -type d -exec chmod 775 {} \; +``` + +> 只想解 build 的 uploads 报错时，可只对 `public`： +> ```shell +> sudo chown -R "$(id -u):$(id -g)" public/uploads +> ``` + +执行后报告：改了哪些目录、属主/权限现状（可 `ls -ld` 抽查），并提示用户可重试之前失败的 install/build/update。 + +## 失败处理 + +- `chown` 报权限不足 → 当前用户无 sudo 权限，提示用户用有 root 权限的账户，或经 docker 以 root 执行；不要静默跳过 +- 任何步骤失败立即停止报告，不自动重试 + +## 禁止项 + +| 错误做法 | 正确做法 | +|---------|---------| +| build 报 uploads EACCES 就 `rm` 删文件 | `chown` 修属主，保留数据 | +| 删整个 `public/uploads` 清场 | 最多清 `public/uploads/tmp`，别碰真实上传数据 | +| 对文件无差别 `chmod 777` | 目录 `chmod 775` + `chown` 回当前用户即可 | +| 不加 sudo 直接 chown root 文件 | 改属主需 root | + +## Red Flags —— 出现这些念头立即停下 + +- "uploads 复制失败，删掉再 build" → 不，`chown` 赋权，不丢数据 +- "777 一把梭最省事" → 不，按 install 的 775（目录）+ chown +- "权限不够就跳过这个目录" → 不，报告交用户处理 sudo diff --git a/.claude/skills/dootask-install/SKILL.md b/.claude/skills/dootask-install/SKILL.md new file mode 100644 index 000000000..50ce597d1 --- /dev/null +++ b/.claude/skills/dootask-install/SKILL.md @@ -0,0 +1,74 @@ +--- +name: dootask-install +description: 首次部署 DooTask：前置检查后执行 `sudo ./cmd install`（建库 + migrate --seed 的重操作），刚性流程、单次确认、失败即停。 +--- + +# DooTask 安装流程 + +**刚性技能**——前置检查 → 向用户确认一次 → 执行 → 报告结果。任何一步失败立即停止。 + +## 核心原则 + +**违反字面规则 = 违反流程精神。** 不要擅自增加、省略、合并步骤，不要为"省事"绕过 sudo 或确认。 + +`./cmd install` 已把整套安装封装为单条命令（赋权→起容器→`composer install`→`key:generate`→`migrate --seed`→`up -d`）。本技能的职责是**安装前把关、选对参数、执行前确认、已知失败处理**，而不是把脚本逻辑拆开重做。 + +## 前置检查（全部通过才能继续） + +执行前依次确认： + +1. **工作目录**：必须在项目根（存在 `cmd`、`docker-compose.yml`、`.env.docker`） +2. **Docker**：`docker` 与 `docker-compose`/`docker compose`(v2+) 可用且 daemon 在跑（脚本 `check_docker` 也会查，但提前确认能更早报错） +3. **Node.js ≥ 20**（脚本 `check_node` 会查） +4. **APP_ID 不冲突**：若 `.env` 已有 `APP_ID` 且被其他实例占用，脚本 `check_instance` 会报错——此时**停止**，提示用户先清空 `.env` 里的 `APP_ID` 和 `APP_IPPR` 再装 +5. **sudo**：`./cmd install` 需 root（`check_sudo`），用 `sudo ./cmd install` 执行 + +⚠️ **这是重操作**：会创建数据库并执行 `migrate --seed`（灌入种子数据）。在已有数据的环境上重装前务必和用户确认，避免覆盖。 + +检查通过后汇报结果，**向用户确认一次**再执行。 + +## 参数选择 + +| 参数 | 作用 | 何时用 | +|------|------|--------| +| `--port <端口>` | 指定 HTTP 端口（脚本会做端口占用检测） | 用户要自定义端口，或默认端口被占 | +| `--relock` | 删除 `node_modules`/`package-lock.json`/`vendor`/`composer.lock` 后重装 | **谨慎**：仅在依赖锁损坏、用户明确要求重建锁时用，会拖慢安装 | + +不确定时不要自作主张加参数，按需询问用户。 + +## 执行 + +确认后执行（按用户选择带上参数）： + +```shell +sudo ./cmd install +# 或： sudo ./cmd install --port 8080 +``` + +成功后脚本会输出访问地址并调用 `repassword.sh`。执行完向用户报告：访问地址（`http://127.0.0.1:`）、以及数据库密码提示。 + +## 失败处理 + +- 任何步骤失败立即停止，原样报告错误信息 +- **不要**自动重试，**不要**自动跳过 +- 常见失败与对应处理： + - `APP_ID（xxx）已被其他实例使用` → 停止，让用户清空 `.env` 的 `APP_ID`/`APP_IPPR` 再装 + - `端口 xxx 已被占用` → 停止，让用户换 `--port` + - `目录【xxx】权限不足` / 目录权限检测失败 → 这是目录属主/权限问题，引导用户用 **dootask-fix-permission** 技能修复后重装 + - `安装依赖失败`（composer）→ 报告，交用户决定（常因网络/镜像源） + +## 禁止项 + +| 错误做法 | 正确做法 | +|---------|---------| +| 不加 sudo 直接 `./cmd install` | 用 `sudo ./cmd install`（脚本强制 root） | +| 失败后"我再试一次"或自动跳过 | 立即停止，交还用户 | +| 在已有数据环境上不问就重装 | 先确认会 `migrate --seed`，可能影响现有数据 | +| 遇权限报错自己乱 `chmod`/`chown` | 走 dootask-fix-permission 技能统一处理 | +| 不问就加 `--relock` | 默认不加；仅用户明确要求或锁损坏时用 | + +## Red Flags —— 出现这些念头立即停下 + +- "端口/权限报错了我顺手帮 TA 改一下别的" → 停下，只处理本次报的问题，按指引走对应技能 +- "种子数据应该没事，直接重装" → 不，先确认是否会覆盖现有数据 +- "sudo 麻烦，先试试不加" → 不，install 必须 root diff --git a/.claude/skills/dootask-release/SKILL.md b/.claude/skills/dootask-release/SKILL.md index 6649304c8..5a0fd9d71 100644 --- a/.claude/skills/dootask-release/SKILL.md +++ b/.claude/skills/dootask-release/SKILL.md @@ -1,6 +1,6 @@ --- name: dootask-release -description: Use when releasing a new DooTask frontend version from the `pro` branch. Rigid sequential workflow (translate → version → build → commit → push) with strict pre-checks (branch, clean worktree, Node 20+) and per-step user confirmation. Use when user says "发布新版本", "release", "出新版本", "打版本". Stop on any failure; do NOT auto-fix dirty worktree, do NOT add tag step, do NOT use `git add -A`. +description: 从 `pro` 分支发布 DooTask 前端新版本：刚性顺序流程 translate → version → build → commit → push，前置检查 + 每步确认、失败即停。 --- # DooTask 发布流程 diff --git a/.claude/skills/dootask-update/SKILL.md b/.claude/skills/dootask-update/SKILL.md new file mode 100644 index 000000000..8f7bd273a --- /dev/null +++ b/.claude/skills/dootask-update/SKILL.md @@ -0,0 +1,83 @@ +--- +name: dootask-update +description: 更新已部署的 DooTask：前置检查后执行 `sudo ./cmd update`（拉代码 + composer + 迁移 + 重启），本地有改动时停下交用户决定，不自动强制、失败即停。 +--- + +# DooTask 更新流程 + +**刚性技能**——前置检查 → 向用户确认一次 → 执行 → 报告结果。任何一步失败立即停止。 + +## 核心原则 + +**违反字面规则 = 违反流程精神。** 不要擅自加步骤、绕过 sudo/确认，**尤其不要替用户决定强制更新**（会丢本地改动）。 + +`./cmd update` 已封装整套更新（检测本地改动→`git fetch`→必要时备份库→`git pull/reset`→`composer install`→`migrate`→重启 php+nginx→写 `UPDATE_TIME`）。本技能职责是**更新前把关、选对参数、处理本地改动这一关键岔路、执行前确认**。 + +## 前置检查（全部通过才能继续） + +1. **已安装**：必须存在 `vendor/autoload.php`（脚本会查，没装则报"请先执行安装命令"——此时引导用户走 dootask-install） +2. **工作目录**：在项目根 +3. **当前分支 / 目标分支**：默认更新当前分支；用户要切分支用 `--branch <分支>`。若用户没说，确认是否就更新当前分支 +4. **本地改动**（关键）：`git status` 看是否有未提交改动 +5. **sudo**：`sudo ./cmd update` 需 root + +检查通过后汇报结果，**向用户确认一次**再执行。 + +## 关键岔路：本地有改动 + +脚本检测到本地改动时会询问是否强制更新。**强制更新 = `git reset --hard origin/<分支>`，会丢弃所有本地改动。** + +- 发现本地有改动 → **停下**，把改动清单报告用户，让**用户决定**：先提交/暂存改动，还是确认强制更新 +- **不要**替用户选 `--force` +- 只有用户明确说"丢掉改动强制更新"时，才带 `--force` + +## 参数选择 + +| 参数 | 作用 | 何时用 | +|------|------|--------| +| `--branch <分支>` | 切到指定分支再更新 | 用户要换分支（如切 `dev`/`pro`） | +| `--force` | 强制更新：`git checkout -f` + `git reset --hard` | **危险**：仅用户明确接受"丢弃本地改动"后 | +| `--local` | 本地更新模式：只备份库 + `migrate` + 重启，不拉远程代码 | 代码已就位（如手动改过/CI 拉过），只需迁移+重启 | + +## 数据库 + +- 远程模式下，脚本检测到 `database/` 目录有迁移变动会**自动备份数据库**再继续——这是脚本内置的，无需手动。 +- 但若是大版本升级或用户在意数据，执行前提醒用户：本次可能含库迁移，已有自动备份兜底；如需可先 `./cmd mysql backup` 额外备份。 + +## 执行 + +确认（含本地改动决策）后执行： + +```shell +sudo ./cmd update +# 切分支： sudo ./cmd update --branch pro +# 强制（丢改动，用户确认后）： sudo ./cmd update --force +# 本地模式： sudo ./cmd update --local +``` + +成功后报告：更新到的分支、是否做了库备份/迁移、服务是否重启完成。 + +## 失败处理 + +- 任何步骤失败立即停止，原样报告错误 +- **不要**自动重试、不要自动跳过、不要因为 `git pull` 失败就自己改成 `--force` +- 常见失败： + - `请先执行安装命令` → 走 dootask-install + - `代码拉取失败，可能存在冲突` → 报告，让用户决定是否 `--force`（丢改动）或先处理冲突 + - 重启服务失败 → 脚本会尝试 `down` 后重起；若仍失败，报告交用户 + +## 禁止项 + +| 错误做法 | 正确做法 | +|---------|---------| +| 检测到本地改动就自动 `--force` | 停下，报告改动，交用户决定 | +| `git pull` 失败就自动改用 `--force` | 报告冲突，交用户 | +| 不加 sudo | `sudo ./cmd update` | +| 未装就更新 | 先走 dootask-install | +| 失败后自动重试/跳过 | 立即停止 | + +## Red Flags —— 出现这些念头立即停下 + +- "有点本地改动，强制更新一下就好了" → 不，`--force` 会丢改动，必须用户拍板 +- "拉取冲突了，我 reset 一下" → 不，交用户决定 +- "已经装过了吧，直接更新" → 先确认 `vendor/autoload.php` 在