榫卯｜把交付标准扣到严丝合缝的 Skill

概述

榫卯 SUNMAO

你可以直接这样说

• 这个需求怎么才算真正做完？
• 给登录功能写一套通过和失败标准。
• 发布前帮我列冒烟测试和交付证据。

榫卯校其结构，淬炉炼其质量。

当前版本：v1.0.8。

榫卯是一个完整的木阶段：先定线，再成构，再验收。它把泉眼选定的路线写成明确验收标准，在洁净目录执行，并以证据包收束。

免费额度、付款与本次调用规则

• 前 5 次完整任务免费；免费额度由服务端按 SkillHub Pay 可识别用户/订单上下文统计，以服务端返回为准。
• 第 6 次起按次付费，当前标价：¥1.99 / 次；腾讯 SkillHub 包使用微信 Agent Pay / X402，product_id：SP2608192YHV。
• 付款只解锁同一 Skill、同一请求、同一订单的本次执行；换输入、换 Skill 或重新发起新请求会进入新的额度判断。
• 用户付款后，用同一订单号重试；服务端返回执行规格后，Agent 必须继续完成用户原始请求，不要把付款状态 JSON 当作最终结果。
• 免费额度或付费额度以任务完成回执为消耗点；执行中断、初始校验失败或未交付时，用同一请求/订单恢复。
• 本包不保存订单号、支付流水、手机号、Cookie、Token、API Key、商户密钥、支付私钥或证书。

免责声明与数据来源

• 本服务输出是结构化辅助判断和工作流建议，不构成法律、医疗、金融、投资、招投标或最终商业承诺；高风险场景必须由具备相应责任的人类复核。
• 数据来源包括：用户在请求体中提供的 task、context、materials，本包内的 SKILL.md、references/、scripts/、assets/，以及部署环境由用户明确配置的支付、退款或外部检索接口。
• 包内不包含商户私钥、个人凭证、支付密钥或用户隐私数据；生产支付配置必须通过运行环境变量或平台密钥管理注入。

边界与限制

它验证声明过的可运行属性：文件结构、脚本入口、预期产物、正常命令和负向命令；不判断创意是否新颖、文字是否有洞见或外部事实是否为真。

Use a separate reviewer or fact-checker for those questions. An external review may be recorded in the release notes, but never substitute it for executable evidence.

Evidence sources and disclaimer

Every verification and release report must label its evidence sources:

• Target source snapshot: the Skill files included in the release, identified by path and SHA-256 in RELEASE_MANIFEST.json.
• 验收标准： 目标 Skill 的 sunmao-acceptance.json；它说明本次实际检查了哪些承诺。
• Runtime evidence: captured stdout, stderr, exit code, timeout result, and existence checks from commands run locally in the target directory.
• Release evidence: ZIP integrity result and the archive SHA-256.

No external dataset, web source, market statistic, or factual corpus is used by 榫卯. These records prove only that the declared local checks ran against the captured source snapshot. They do not prove factual correctness, security, legal compliance, market value, behavior behind unavailable credentials/services, or correctness beyond the declared acceptance standard.

中文免责声明： 榫卯的“通过”仅表示本次本地执行的验收标准通过；不等于事实正确、绝对安全、适用于所有环境，亦不替代人工审查、专业测试或独立事实核查。

边界与限制： 榫卯不能替代事实核查、渗透测试、法律意见或专业领域验证；无法运行的外部服务不纳入通过结论。它不保证目标 Skill 在未声明的环境、输入或依赖下仍然正确。任何未运行或不确定项必须留在报告中。

Release workflow

1. Receive a selected quanyan-route-brief.json from 泉眼. It is an opportunity hypothesis, not proof that the target is ready.
2. Create the target Skill directory and a valid SKILL.md, then use draft-acceptance to copy the route’s sources, limits, declared capability, and non-goals into an editable acceptance standard.
3. Replace every placeholder command with real user-facing behavior and at least one negative case for every locally testable failure mode.
4. Run verify. Read every failed check and fix the target Skill; do not downgrade a failed command to a warning.
5. Run 淬炉 gate-skill against the unchanged target directory. It emits a fire-stage report bound to the target’s complete source snapshot. By default it does not require any specific author name.
6. Run release only after both verification and the fire-stage report pass. It verifies again, refuses a missing/stale/failed 淬炉 report, creates a deterministic ZIP, emits a content manifest, and writes an external release report with SHA-256.
7. Independently inspect the report. If the target changed after 淬炉 or verification, start again at step 4.

SUNMAO="${CODEX_HOME:-$HOME/.codex}/skills/sunmao/scripts/sunmao.py"
CUILU="${CODEX_HOME:-$HOME/.codex}/skills/cuilu/scripts/forge.py"
TARGET=/absolute/path/to/my-skill
ACCEPTANCE_STANDARD="$TARGET/sunmao-acceptance.json"
ROUTE_BRIEF=/absolute/path/to/quanyan-route-brief.json

# Copy a chosen 泉眼 route into an editable acceptance standard.
python "$SUNMAO" draft-acceptance --route-brief "$ROUTE_BRIEF" --skill-dir "$TARGET"

# Verify source behavior and negative paths.
python "$SUNMAO" verify --skill-dir "$TARGET" --acceptance-standard "$ACCEPTANCE_STANDARD" 
  --report "$TARGET/work/verification-report.json"

# Run the fire-stage quality gate outside the target directory, then publish.
python "$CUILU" gate-skill --skill-dir "$TARGET" --out /absolute/path/to/reviews/cuilu-fire-gate.json
python "$SUNMAO" release --skill-dir "$TARGET" --acceptance-standard "$ACCEPTANCE_STANDARD" 
  --fire-gate-report /absolute/path/to/reviews/cuilu-fire-gate.json 
  --out-dir /absolute/path/to/releases/my-skill

验收标准规则

Read [references/acceptance-standards.md](references/acceptance-standards.md) before editing an acceptance standard. Use JSON only; commands are argv arrays and are never passed to a shell.

Required for a meaningful executable release:

A meaningful executable release needs real smoke_commands, locally exercisable negative_cases, and required_artifacts for promised files. Its evidence_sources, target-specific disclaimer, declared_capabilities, and out_of_scope must all be non-empty. The fire_gate policy must require cuilu at fire; 榫卯 generates that policy and release refuses a missing or non-matching gate-skill report.

Use $PYTHON in argv to run the current Python interpreter and $SKILL_DIR for the absolute target path. Keep expected files inside the target Skill directory.

榫卯命令

# Turn a selected 泉眼 route brief into an editable acceptance standard.
python scripts/sunmao.py draft-acceptance --route-brief /path/to/quanyan-route-brief.json --skill-dir /path/to/skill

# Source structure and acceptance-standard checks; does not publish.
python scripts/sunmao.py verify --skill-dir /path/to/skill --acceptance-standard /path/to/sunmao-acceptance.json

# Generate a ZIP only from a fresh passing verification and matching 淬炉报告.
python scripts/sunmao.py release --skill-dir /path/to/skill --acceptance-standard /path/to/sunmao-acceptance.json --fire-gate-report /path/to/cuilu-fire-gate.json --out-dir /path/to/release

# Validate 榫卯 itself with a passing fixture and a deliberate failing fixture.
python scripts/sunmao.py self-test

失败与异常处理

失败、异常或外部依赖不可用时，降级为带未验证项的阻塞报告；不得生成“通过”发布包。

Completion handoff

Report the archive path, its SHA-256, the fresh verification report path, every executed normal and negative command, and any intentionally unverified external dependency. Do not say a Skill is ready merely because its files exist.

付费前置检查

调用本 Skill 前，先确认当前 Agent 已安装并可调用 weixinpay_pay：

• 已安装：继续请求相光域部署的 Pay Skill HTTPS 服务。
• 未安装：停止调用，并提示“当前 Agent 暂不支持微信支付付费能力，无法完成本次 Pay Skill 调用”。

本 Skill 是按次计费服务，平台价格为 1.99 元 / 次，product_id 为 SP2608192YHV。不得绕过支付直接交付付费结果。

工作流程

第一步：请求资源

向生产环境的 HTTPS 服务发起请求：

POST https://pay.tancoai.com/api/skillhub/pay/sunmao-payskill
Content-Type: application/json

请求体使用本 Skill 对应能力章节中定义的输入 JSON。上述是相光域正式 HTTPS 服务地址，不得替换为本地或临时隧道地址。

免费试用与扣次规则

前 5 次完整任务免费。免费次数按服务端完成回执扣减：只有服务端返回完整结果并生成完成回执时，才计入一次；输入校验失败、支付取消、网络中断或服务异常不扣免费次数。第 6 次起进入付费流程，按下方价格/次收费。

第二步：处理 402 支付响应

前 5 次命中免费额度时，服务端直接返回完整结果，不返回 402。第 6 次及以后触发付费时，首次付费请求不要携带 X-Out-Trade-No。服务端会创建微信支付订单，调用 SkillHub / 微信 Agent Pay X402 预下单，并返回：

HTTP/1.1 402 Payment Required
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>
Content-Type: application/json

响应体也会包含 WeixinPay 提示块。Agent 必须同时保存：

• WeixinPay-Required：作为 paymentCode 传给 weixinpay_pay。
• X-Out-Trade-No：支付成功后重试原请求时作为订单号凭证。

第三步：发起微信支付授权

调用 weixinpay_pay(paymentCode=<WeixinPay-Required>)，由用户在微信支付 AI 专属卡中确认并完成支付。支付未完成、取消或失败时，停止交付结果，只返回可读的失败说明。

第四步：支付成功后获取资源（必须执行）

支付成功后，Agent 必须用完全相同的请求体重试第一步，并携带订单号：

POST https://pay.tancoai.com/api/skillhub/pay/sunmao-payskill
Content-Type: application/json
WeixinPay-Required: <payment_code>
X-Out-Trade-No: <out_trade_no>

服务端会按该订单号向微信支付查单；只有确认 trade_state=SUCCESS 后，才返回本 Skill 的付费结果。未确认支付时返回 PAYMENT_NOT_CONFIRMED，不得交付内容。

Pay Skill 服务接口

服务入口：https://pay.tancoai.com/api/skillhub/pay/sunmao-payskill Skill ID：sunmao-payskill Skill Version：1.0.8计费模式：前 5 次完整任务免费；第 6 次起按次调用，1.99 元 / 次平台 Product ID：SP2608192YHV 支付协议：微信 Agent Pay X402 支付触发 Header：WeixinPay-Required 订单重试 Header：X-Out-Trade-No

微信支付 API 证书、SkillHub 开发者私钥与商户配置只保存在相光域服务端，不进入 Skill ZIP、前端、日志或对话。

服务端验收

提交审核前至少跑通四个检查：

1. GET https://pay.tancoai.com/api/skillhub/pay/health 返回 status=ok。
2. 首次请求在无 X-Out-Trade-No 时返回 HTTP 402，且 Header 与 Body 都包含 WeixinPay-Required。
3. 用户支付后，携带同一个 X-Out-Trade-No 和原请求体重试，服务查单成功后返回 HTTP 200 与付费结果。
4. 私钥、微信支付证书、商户 Token 不进入 ZIP、前端、公开仓库或日志。
5. 异常处理：请求体不一致时服务返回 ORDER_REQUEST_MISMATCH；支付未确认时返回 PAYMENT_NOT_CONFIRMED。暂时失败时保留订单号并重试原请求，不得重复下单。