@alipay/alipay-aipay 1.2.2 → 1.4.9

package/skill/references/normal/self-update.md

@@ -1,59 +1,26 @@
-# Skill 启动自更新检查
+# Skill 启动器自更新契约
 
-本文件定义 `alipay-aipay` Skill 启动时的自更新检查。该检查用于降低用户继续使用旧版 Skill 的概率，但不得阻断支付集成或签约入驻主流程。
+根 `SKILL.md` 是跨 Agent 的最小启动器。本次 Agent 对话首次使用 `alipay-aipay` 时，必须在读取 `references/runtime-entry.md`、flow、模块、消息目录或业务脚本前只检查一次版本。执行前把根 `SKILL.md` 所在目录解析为规范化绝对路径 `<SKILL_DIR>`，并在当前 Agent 上下文记录一次性事实 `ALIPAY_AIPAY_SELF_UPDATE_CHECKED=true`；不写文件、不跨对话保存，也不是业务进度。同一对话内后续根流程、确认、补材料、候选选择、错误恢复、中断后继续、重复读取本 Skill 和 Full Process 子流程衔接均不重查。`<SKILL_DIR>` 是执行时替换的路径占位符，固定命令为：
 
-## 执行原则
-
-- 每次触发本 Skill 时，先执行本检查。
-- 如果本轮对话中刚成功执行过 `npx -y @alipay/alipay-aipay@latest install`，或等价的 `@latest install --target ...` 命令，则视为自更新检查已完成，直接继续当前业务流程，不再查询 npm latest，也不再重复执行安装。
-- 本检查不作为业务阻塞确认点，不单独询问用户是否更新。
-- 若当前 Agent 环境要求联网或写入用户 Skill 目录授权，则按环境权限机制处理；不得在 Skill 内另设业务确认点。
-- 任何读取版本、查询 npm、执行更新失败的情况，都只输出简短提示并继续当前业务流程。
-- 更新命令必须使用 `--skip-tools`，只更新 Skill 文件，不重新检查或安装 GPG、alipay-cli、jq。
-
-## 版本读取
-
-1. 读取当前 `SKILL.md` 所在目录下的 `VERSION` 文件作为本地版本。
-2. 如果 `VERSION` 不存在，或内容不是合法 SemVer 版本号（例如 `latest` 或 `v1`），将当前安装视为“未知版本/旧版安装”，直接进入「未知版本更新规则」，不要再猜测其他安装记录文件。
-3. 如果成功读取本地版本，执行以下命令查询 npm latest：
-   ```bash
-   npm view @alipay/alipay-aipay version --json
-   ```
-4. 如果无法获取 npm latest，跳过更新并继续当前业务流程。
-
-## 更新规则
-
-如果本地版本低于 npm latest，自动执行 Skill 更新。
-
-更新命令必须覆盖当前正在使用的 Skill 目录。取当前 `SKILL.md` 所在目录的父目录作为 `<当前Skill父目录>`，执行：
-
-```bash
-ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
+```text
+node "<SKILL_DIR>/references/normal/scripts/self_update.mjs" check --skill-dir "<SKILL_DIR>"
 ```
 
-说明：
-- `ALIPAY_AIPAY_EXTRA_SKILL_DIRS` 确保当前正在使用的 Skill 父目录会被纳入更新目标，避免只更新当前项目目录下的 `.agents/.codex/.claude`。
-- `--target all` 继续覆盖安装器解析到的全部目标目录。
-- `--skip-tools` 避免在启动检查中触发 GPG、alipay-cli、jq 的检查或安装。
-
-## 未知版本更新规则
-
-如果当前 Skill 目录没有 `VERSION`，或 `VERSION` 内容不是合法 SemVer 版本号，不做不可靠的版本推断，直接执行同一条更新命令：
-
-```bash
-ALIPAY_AIPAY_EXTRA_SKILL_DIRS="<当前Skill父目录>" npx -y @alipay/alipay-aipay@latest install --target all --skip-tools
-```
+`<SKILL_DIR>` 必须是刚触发的本份 `SKILL.md` 所在目录，且该目录包含 `SKILL.md`、`VERSION` 和 `references/runtime-entry.md`；不得换成 Agent 启动目录、用户项目目录、用户 Home、npm 包源码根或另一份 Skill 副本。禁止把固定命令改写成 shell 变量赋值、命令替换或依赖 Bash、PowerShell、CMD 的专属语法。若执行器支持设置 workdir，也可以从本文所在目录 `references/normal/` 执行 `node scripts/self_update.mjs check`；两种写法必须绑定同一份当前 Skill。
 
-说明：
-- 这是对旧版安装的确定性兼容路径；更新成功后，新安装器会写入 `VERSION`，后续启动即可走正常版本比较。
-- 如果该命令因网络、npm、权限或执行环境限制失败，输出简短提示并继续当前业务流程。
+结果与规则：
 
-## 输出要求
+- 脚本正常结束时，stderr 必须恰好包含下表一个 `SELF_UPDATE:*` 终态 marker；所有 marker 都是内部事实，不对客，不得补充或透传 npm/npx 原始 stdout、stderr。
 
-- 已是最新：输出一句简短提示即可。
-- 发现新版本并开始更新：输出本地版本、npm latest 和更新目标摘要。
-- 未知版本并开始更新：输出“未检测到 VERSION，尝试安装 latest”及更新目标摘要。
-- 更新成功：提示更新已完成，并继续当前业务流程。
-- 更新失败或权限受限：提示本次自更新未完成，继续使用当前已加载版本执行流程。
+| marker | 含义与动作 |
+|---|---|
+| `SELF_UPDATE:CURRENT=<合法 SemVer>` | 已确认当前版本不低于 npm latest；读取当前 `references/runtime-entry.md`。 |
+| `SELF_UPDATE:UPDATED=<合法 SemVer>` | 已确认当前 Skill 达到目标版本；停止读取更新前版本，直接读取同一 Skill 根目录下新版 `references/runtime-entry.md`。 |
+| `SELF_UPDATE:CHECK_FAILED` | npm latest 查询、解析或脚本入口检查失败；读取当前可用版本的 `references/runtime-entry.md`。 |
+| `SELF_UPDATE:INSTALL_FAILED` | 安装命令失败或超时，且未验证到目标版本；读取当前可用版本的 `references/runtime-entry.md`。 |
+| `SELF_UPDATE:VERIFY_FAILED` | 安装命令返回成功，但安装后版本未达到目标或仍不合法；读取当前可用版本的 `references/runtime-entry.md`。 |
 
-不得输出长篇安装日志；如需日志，以命令输出或工具环境记录为准。
+- 五类终态都保留 `ALIPAY_AIPAY_SELF_UPDATE_CHECKED=true`，不得再次检查；差别仅在 `UPDATED` 使用原子替换后的新版，其余终态使用当前可用版本。marker 缺失、重复或无法唯一解析时也只表示当前执行环境无法确认结果，不得解释成“已是最新”或“更新成功”，并继续读取当前 `references/runtime-entry.md`。
+- `VERSION` 合法时只查一次 npm latest（最多 5 秒）；缺失、不合法或落后时只运行一次 `npx -y @alipay/alipay-aipay@latest install --target all --skip-tools`（最多 60 秒）。
+- 安装通过两个登记环境变量只绑定当前 Skill，不更新其他副本；结束后重读 `VERSION`，达到目标版本才输出 `UPDATED`，并发安装已达到同一版本也按实际成功处理。
+- 失败终态保持 fail-open 且对客静默。本次对话不再检查、不重试、不申请权限、不使用 `sudo`、不要求用户操作，也不写任何自更新缓存或状态文件。版本确定后才允许初始化根意图遥测、平台门禁和业务流程。