@alipay/alipay-aipay 1.2.2 → 1.5.0

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`、不要求用户操作，也不写任何自更新缓存或状态文件。版本确定后才允许初始化根意图遥测、平台门禁和业务流程。

package/skill/references/normal/telemetry.md

@@ -0,0 +1,26 @@
+# 遥测维护参考
+
+本文件只供维护、测试和故障排查按需读取；业务运行默认只执行 `runtime-entry.md` 与动作 runner/script 登记的入口。
+
+## 运行契约
+
+- 固定 stage 枚举、Yuyan 字段和低敏维度以 `scripts/telemetry.mjs` 的 `approvedStages`、事件构造器和测试为准。
+- `start-run` 创建或复用 `run_id`；动作 runner/script 使用异步子进程记录 stage。缺少 run、遥测关闭、落盘失败、网络失败和非 2xx 都不得改变业务 stdout、退出语义或 flow 转移。
+- 前台只写用户系统临时目录下带 `alipay-aipay` 标识的私有 outbox，并启动后台补传；collector 返回 HTTP 2xx 后才删除记录。维护/测试进程不复用默认 run state，默认不远端上传。
+- `PLATFORM_ID` 必须等于当前 `run_id`；模型维度只读 `AIPAY_MODEL`，禁止读取用户项目通用 `MODEL` 推断。
+- 遥测内部行统一使用 `ALIPAY_AIPAY_INTERNAL:` 前缀，禁止对客。
+
+## Run 生命周期
+
+- 根入口用 `root_intent + product_type` 判定复用或新建；组合不变时不按经过时长失效，`UNKNOWN` 补全为明确产品仍复用同一 `run_id`。只有明确换产品、切换根意图或已有 run 终态才重建；用户只说“重新开始/重新走流程/作废本轮流程”但组合没有变化时继续复用。
+- 若宿主提供 `COZE_PROJECT_ID`、`MEOO_PROJECT_ID`，或 `MIAODA` 环境下的 `VITE_APP_ID`/`PLATFORM_ID`，新建 run 直接使用该项目 ID。当前宿主项目 ID 与已有状态不兼容时静默跳过不兼容事件且不改写 run state。
+- `integration_only` 由 checklist 最终消息终止；`full_process` 的 Integration 收口不终止，和 `onboarding_only` 一样由 Onboarding closeout 终止。
+- 查看当前主键只使用 `current-run-id`，不得为查看而新建 run。业务脚本继续继承 `PLATFORM_ID=<run_id>`；Agent 不手写环境变量前缀或改写 MCP payload。
+
+## 诊断与补传
+
+`node scripts/telemetry.mjs upload-status` 只读取内部诊断状态。网络类失败且 outbox 有积压时，先执行 `node scripts/telemetry.mjs permissioned-flush-needed`；只有内部事实为 `PERMISSIONED_FLUSH_NEEDED=true` 时才申请一次可复用联网权限运行 `node scripts/telemetry.mjs flush-outbox`。同一 Agent 会话只请求一次；已取得权限后可在后续阶段旁路触发同一异步命令。`flush-outbox` 只启动后台补传并立即返回；用户拒绝、后台失败或非 2xx 都保留 outbox 并继续业务。collector HTTP 结果、失败或待重试结果不得作为业务转移或完成条件。
+
+## 修改要求
+
+修改 stage、run 生命周期、outbox 或上传逻辑时，必须覆盖遥测关闭、缺少 run、写盘失败、无网络、非 2xx、并发 claim、终态 run 和 `PLATFORM_ID` 继承测试。不得把实现细节复制回 `runtime-entry.md` 或两个主 flow。