TBox 支付宝小程序集成 Skill

将 TBox 智能体 H5 的 WebView 页面和开放源码桥接层集成到已有的原生支付宝小程序。

本 npm 包包含面向 AI Coding Agent 的集成 Skill，以及 Skill 完成接入所需的执行器和源码模板。用户只需向 Agent 描述接入目标，不需要手动执行命令。

安装完成后，协议、消息解析、JSAPI 执行、媒体和录音代码都会直接写入客户项目，不引入运行时黑盒 SDK。

用户使用方式

在支持 Codex Skill 的 AI Coding 环境中安装或启用包内的 tbox-agent-alipay-skill Skill，然后对 Agent 提出目标。例如：

使用 $tbox-agent-alipay-skill，将
https://example.com/
接入当前原生支付宝小程序。

项目不在当前目录时，直接在请求中提供路径：

使用 $tbox-agent-alipay-skill，将智能体 H5 接入 ./miniapp，
H5 地址是 https://example.com/。

用户只需提供：

• 原生支付宝小程序目录，当前目录就是项目根目录时可以省略。
• 智能体 H5 HTTPS 地址。
• 可选的页面路径、桥接目录、源码语言或样式语言要求。

通过 npm 安装 Skill

发布到 npm 后，可在目标项目根目录执行：

npx @tbox.cn/tbox-agent-alipay-skill install

该命令只复制包内完整的 Skill 到当前项目的 .agents/skills/tbox-agent-alipay-skill/，不会修改支付宝小程序源码。也可明确指定 目标项目和 Agent：

npx @tbox.cn/tbox-agent-alipay-skill install \
  --path ./miniapp \
  --agent codex

支持 codex（默认）和 claude-code；后者安装到 .claude/skills/。同名 Skill 已存在时命令会停止，不会覆盖；仅在确认替换时传入 --force。使用 --dry-run 可先查看目标路径。

Skill 会自动识别平铺项目和 src → dist 等源码/产物分离项目，并在 H5 地址中补齐 container=alipay-miniapp；地址已有其他 query 或 hash 时会保留，已有同名参数时会覆盖为正确值。

Skill 会完成什么

Skill 会自行编排 CLI，不把终端命令转交给用户：

1. 综合 app.json、应用入口、TypeScript 配置、小程序配置和源码分布，识别项目工作区、源码目录、只读构建产物目录、语言及样式，并保留已有 Git 改动。
2. 先执行零写入预览，检查文件冲突和错误诊断。
3. 变更安全且目标明确时执行正式安装。
4. 检查 Git 差异并运行安装诊断。
5. 必要时比较客户源码与当前开放源码模板。
6. 汇报新增和修改的文件，以及支付宝后台仍需人工完成的配置。

默认安装位置（均相对识别到的源码目录，而非 dist 等构建产物目录）：

pages/tbox-agent/index
tbox-agent-bridge/
.tbox-agent-alipay/manifest.json

第一版只支持原生支付宝小程序，不支持 Taro、uni-app 等跨端工程。CLI 不会强制覆盖客户文件；已被客户修改的源码会报告冲突并停止写入。

需要更新 H5 地址或检查现有安装时，用户仍然通过同一个 Skill 提出目标，例如：

使用 $tbox-agent-alipay-skill，将当前项目的智能体 H5 地址更新为 https://new.example.com/。

使用 $tbox-agent-alipay-skill，检查当前支付宝小程序的 TBox 集成状态。

安装后仍需人工完成

• 在支付宝小程序后台配置 H5 业务域名。
• 配置实际使用的 JSAPI 权限、应用类目和隐私声明。
• 真机验证授权、定位、选图和录音。

H5 被视为可信代码，因为桥接层采用宽松 JSAPI 代理。只应配置由业务方控制的 HTTPS 地址，不应通过页面 query 传递 token、密钥等敏感凭证。

仓库开发

仓库按自包含 Skill 组织：

skills/tbox-agent-alipay-skill/
  SKILL.md                           用户入口和编排规则
  agents/                            Agent 展示配置
  references/                        接入契约
  assets/native-alipay/              写入小程序的开放源码模板
  scripts/run-cli.mjs                Skill 调用入口
  scripts/cli.cjs                    自包含执行器（构建产物）
  scripts/cli-src/                   执行器源码（不进入 npm 包）
tests/                               CLI、Skill 边界和端到端测试
scripts/                             仓库构建与校验脚本

以下命令仅供本仓库开发和发布维护使用：

npm install
npm run check
npm pack
node scripts/verify-package.mjs \
  tbox.cn-tbox-agent-alipay-skill-0.2.0.tgz \
  tbox-agent-alipay-skill-0.2.0.zip

npm run build 会预生成 JavaScript 模板、校验支付宝小程序兼容语法，并把执行器及其依赖打成单个 scripts/cli.cjs。模板出现 catch {}、可选链、空值合并、代码解析错误或基础 AXML/样式结构异常时构建会失败。npm run check 会依次执行类型检查、构建、自动化测试和 Skill 结构校验；自动化测试还会用严格的支付宝 TypeScript 配置（仅 ES2020 lib、noUncheckedIndexedAccess 等）实际编译生成源码。

npm pack 生成 npm 安装包；verify-package.mjs 会从该包中只提取 Skill 子目录，在隔离环境分别验证平铺 JavaScript/ACSS 项目和 src → dist TypeScript 项目，并校验 AXML、ACSS、JSON、兼容语法及写入位置，随后生成可供 CC Switch 导入的 ZIP。为避免误覆盖已有测试包，目标 ZIP 已存在时脚本会停止。

安装器本身位于 bin/install-skill.mjs，仅复制包内的完整 Skill；普通 npm install 不会触发写入，也没有 postinstall 钩子。

发布包中的 skills/tbox-agent-alipay-skill 目录是完整、可独立复制的 Skill：scripts/run-cli.mjs 只访问该目录内的 scripts/cli.cjs 和 assets/，不依赖同包的兄弟目录、全局依赖或运行时下载。内部执行契约位于 references/integration-contract.md。