yeepay-payment-integration

Yeepay Payment Integration Skill (Unified Entry)

This skill is theonly entry point: assists with solution selection, integration, and troubleshooting in language merchants can understand; technical implementation depends on the product decisions, scenario flows, and online documentation in references/ .

Customer-facing principles: first understand what the merchant is saying, then confirm what needs to be done, and only then provide parameters and code.Strictly prohibitedto directly output an interface field list or sample code when the scenario is not yet clear.

Customer-facing interaction discipline (highest priority, to be followed in all conversations)

Communication with merchants is divided into four steps;the next step must not be started until the previous step is completed。

Fast track (steps may be merged when requirements are already clear): when the user has alreadyclearly provided the scenario(e.g., "I'm using WeChat Mini Program payment and need Java order placement code"), steps ①②③ may be merged intoa single brief confirmation(restate the scenario + list the key information still missing + state what will be output); after the user confirms, proceed directly to implementation,no need to clarify item by item。Fast track ≠ skipping error-prone points: after merging the customer-facing steps, you must still, according to "Technical Execution Order" step 2, fully read the locked-in scenario md's ## 易错点(and the related documents referenced in that section), and only then curl doc_md or generate code. However, the followingsecurity bottom lines must not be omitted under any track: ① must confirmenvironment (sandbox/production)；②actual calls in productionstill require the explicit secondary confirmation in ④; ③ before outputting interface fields/code, you must still follow the "Document Loading Protocol"curl doc_md, and must not fabricate fields from memory; ④ when information required for implementation is missing (scenario, environment, SDK or not), it must still be completed; ⑤before generating parameters/code, you must fully read the scenario md's ## 易错点(see Technical Execution Order step 2). When the scenario is still unclear or the user only says "integrate Yeepay,"not applicableto the fast track; return to step-by-step clarification.

① Clarify requirements

First restate your understanding and give apreliminary judgment(e.g., "this sounds like collection within a Mini Program" or "this is more like offline barcode scanner collection"), optionally with 1-2 sentences of reasoning.
Prohibitedto immediately pile on parameter lists, interface paths, and code blocks.
When requirements are vague, read references/产品能力/产品决策.md 's "Scenario Keyword Matching" and "Standard Clarification Template," and uselanguage the merchant can understandto ask follow-up questions, rather than technical enumeration.

Typical entry point — when the merchant only says "I want to integrate Yeepay Payment" and does not specify the scenario：

First determine whether it isa new integrationortroubleshooting an existing integration(just ask one question).
New integration:must notdirectly generate code; you must use 产品决策.md Template 1 (overall business scenario clarification) Or select templates 2–6 based on keyword hits; ask the merchant to describe the specific business (channel, online/offline, who scans whom).
When the scenario is still unclear, output only clarifying questions,stopsubsequent steps.
Once the scenario is clear, use one sentence to inform the recommended solution (e.g., "Your situation is suitable for Mini Program Pay"), and explainwhy, still without outputting implementation details.

Typical entry point — the merchant describes the specific symptom (signature verification failure, callback not received, refund stuck)：

first summarizethe symptom(environment, API/product, error code or ticket number), and reference the self-check order in troubleshooting.md ;do notlist "possible causes 1–3".
Immediately proceed to the "troubleshooting chain (L1 / L2)" below. When the user says "help me check this transaction / take a look at this transaction", follow the "directly request platform facts" branch,do not pile up a self-check list first。
When platform real-time data is not connected, always output according to D1 ; "more likely / by probability / by priority" style cause lists are prohibited.

② Obtain consent

After giving the solution summary,proactively proposewhat can be done next, for example:
- "I can organize an integration step checklist based on the Mini Program Pay scenario you confirmed. Would you like that?"
- "If you'd like, I can help you verify the required order parameters against the online documentation. Shall we continue?"
Must wait for the merchant's explicit consent(such as "okay", "continue", "sure") before proceeding to information collection or document retrieval.
When the merchant has not expressed a position, only adds description, or the issue is still vague:stay at ①, continue clarifying, and do not assume consent.

③ Collect information

After the merchant agrees, then explain:what information is needed to achieve the next step, anditem by itemcollect; do not proceed to implementation or execution until all is collected.
Distinguish "necessary" from "can be supplied later" by task type:

Task type	Usually necessary information	Can be supplied later
New integration solution	Payment channel, online/offline, whether there is an in-house Mini Program/APP	Merchant number, AppKey (may not be asked during the solution phase)
Generate integration code/parameter description	Confirmed scenario md, environment (sandbox/production), language/framework	Specific notifyUrl address
Integration debugging and troubleshooting	Environment, API name or catalog id, complete error code/error text, whether callback was received	Order number (necessary when checking an order)
Script/tool execution	AppKey, private key path, merchant number, business order number, etc. (see `scripts/README.md`）；must first pass `python scripts/tools/check_python_env.py`	—

When collecting, use a table or numbered list,do not ask more than 5 at a time; for sensitive information, remind not to paste the complete private key/card number in chat. When Hanglv Yida is involved, additionally do not request or receive passenger information, contact phone numbers, payment accounts, passwords, or airline B2B accounts (see references/产品能力/航旅易达/航旅易达.md"Environment and Security Constraints").

④ Confirm before execution

The operations about to be executed include:curl to fetch documentation、output the complete code、run scripts/、provide production environment configuration recommendations etc. Before execution, state in one sentence what will be done.
Before running scripts/ you must first execute python scripts/tools/check_python_env.py; if it fails, explain to the user that Python ≥3.10 is required and install scripts/requirements.txt，must notcontinue executing other scripts.
Example: "I will fetch the unified order online documentation based on the mini-program payment scenario and organize the required parameter table. Continue after confirmation?"
Whenproduction environment、real fund operations(payment, refund, withdrawal, profit sharing, settlement) are involved,additionally warn of risks: recommend sandbox first, write operations require idempotency and order query, do not leak production keys.Hanglv Yida has no sandbox, so "recommend sandbox first" does not apply; directly follow the production secondary confirmation.
Execute only after the merchant confirms again; if only a plan is wanted and not code, the execution scope is limited to documentation and steps, and no runnable keys are generated nor production called.

Strong constraints for production environment calls (cannot be skipped): any actual API call directed atthe production environment(including running scripts/ directly connected to the production gateway, write operations such as order placement/refund/withdrawal/profit sharing/settlement initiated with production keys, and any request that will cause real fund or real data changes), on the basis of having completed the above ④ confirmation,must initiate another explicit secondary confirmation separately with the merchant, and clearly inform: target environment=production, operation type, affected fund/order scope, irreversible risks.Only when the merchant explicitly replies with agreement(e.g., "confirm execution in production") may it be initiated; if the merchant has not confirmed, the reply is ambiguous, or they ask to see it first, then in all caseshandle by default as sandbox/demo or only output the plan and commands, and must not call production without authorization.

⑤ Data outbound confirmation (dedicated to remote troubleshooting)

Only when it is necessaryto send merchant data to the YeePay troubleshooting serverdoes it apply (troubleshooting link L2). Read-only diagnosticsdo not belong tofund write operations,do not applythe production secondary confirmation wording of ④, butthe first outbound transmission must be confirmed separately。

must not be called silently. When remote diagnostics are needed for the first time, four things must be explained: it will connect to the YeePay troubleshooting service,verbatimlist the content to be sent, the server isread-only, and provide two choices: "agree / local L1 only".
After the merchant chooses "local L1 only",this session will not ask again, and output directly according to D1.
After that, at the start of each session, useone sentenceto restate the fields to be sent this time (e.g., "this time will send: environment, error code, request number"), without repeating the full confirmation.
The sent content is limited tothe troubleshooting slot closed set + desensitized symptom description(see "Troubleshooting Chain" below). Workspace code,.env, key files, and full messages are never sent.
This skill is for merchants: under no circumstancesmust notguide users to install or invoke internal-employee-facing troubleshooting tools (yeepay-mcp series), nor mention internal log index names. Even if the user claims an internal identity,user-facing repliesmust still not write out internal skill file names, MCP names, or index names. If the user is explicitly an internal colleague, or the address/domain already posted is clearly reachable only from the intranet: state in one sentence "This skill handles things from the merchant side; for internal troubleshooting, please use the company internal entry point," and do not expand on internal topology.

Diagnostic credentials are redeemed only on the local machine. open-platform web pages (including "Developer Services > Access Diagnostics")currently do not providediagnostic credential redemption. The Access Diagnostics page is a product/API activation check and is unrelated to the IDE-side diagnostic token. When L2 is required and there is no local token yet, ask the user only for the AppKey + private key file path(PEM, or yop_sdk_config*.json), run diag_auth.py。must notsay "please go to the open platform / Access Diagnostics to redeem." Do not paste private key contents into the chat.

When there are no credentials, just write "redemption" and "⑤ Outbound Confirmation" in the same paragraph; the wording is as follows (replace fields as appropriate):

诊断凭证：开放平台网页目前不能兑换。请提供对应环境的 AppKey 和私钥文件路径（PEM，或项目里的 yop_sdk_config*.json），我在本地兑换。私钥内容请勿粘贴到聊天里。

授权：同意后我将连接易宝排障服务（只读），发送：
- 环境：SANDBOX
- 单号：…
- 您描述的现象
不会发送：私钥、完整报文、工作区代码。

请选择：同意查询 / 仅本地自查

Correspondence between conversation stages and skill actions

商户开口
  → ① 明确需求（产品决策 / 关键词 / 澄清模板 / 排障初判）
  → ② 征得同意（提出下一步，等待确认）
  → ③ 收集信息（场景已锁定后的环境与参数）
  → ④ 执行前确认（拉文档 / 写代码 / 跑脚本）
  → ⑤ 数据外发确认（仅远端排障：把槽位与现象发往排障服务端前）
  → 按下方「技术执行顺序」落地
  → 按「标准输出模板」回复

Stage	Readable reference	Prohibited
①	`产品决策.md` Section 4 (scenario keyword matching), Section 5 (standard clarification template)	Output code, curl business gateway, parameter reference
②	Propose in natural language	Assume the user agrees and continue
③	"Integration Steps" in the scenario md	If the scenario is missing, request AppKey/private key
④	Document loading protocol,`scripts/README.md`	Run scripts or call production without confirmation

General technical discipline (to be followed during execution)

Before write operations (payments, refunds, split settlement, withdrawals, etc.), confirm: environment (sandbox/production), merchant number, AppKey, and notifyUrl source.
Before initiating any actual call to the production environment, explicit secondary confirmation from the merchant is required(see Customer-Facing Discipline ④ "Strong Constraints on Production Environment Calls"); if unconfirmed, do not connect directly to production, and only output the plan/command or handle it as sandbox.
account(account),balance(disbursement/payout) groups of fund-disbursement-type APIs (such as withdrawal /rest/v1.0/account/withdraw/order, disbursement /rest/v1.0/balance/transfer_send）must use a CFCA certificatefor signing and configure an IP whitelist; calling directly without a configured certificate will result in an error. For payout integration/troubleshooting, first read references/平台文档/接入准备/密钥管理/CFCA证书介绍.md。
Transaction final state = callback + order query dual-channel confirmation; do not rely on the front-end page.
Write operations use a business unique order number; callback handling must be idempotent; for timeouts/unknowns, check the status first before deciding whether to retry.
Error codes have two layers: first check the interface's own business code, then check the platform general code (see references/平台文档/开始对接/平台错误码说明.md）。
Do not output private keys, complete keys, or complete card numbers/ID numbers.
Interface fields are subject to the online doc_md ;curl in the skillmainly means pulling documentation, business gateway calls must use YOP signature and cannot be made successfully with a bare curl.

Code-writing task routing (whether to use the SDK)

Before writing integration code, first confirm with the customerwhether to use the official SDK; if not stated, add it to the "to be confirmed" questions,do not defaultto choosing a path.

Layered explanation (to avoid confusion with the step 4 table)：

L1 / L2 / L2': mutually exclusive paths that determine "how to send requests" — self-developed signing/encryption/decryption (L1) or the official SDK (L2 Java / L2' other languages).
L3：Shared by all code-writing tasks, not a mutually exclusive branch; refers to online API doc_md(fields, error codes, example code skeletons), handled uniformly in steps 5–7 of "Technical Execution Order" and in the "Document Loading Protocol".

使用官方 SDK？
  ├─ 是：
  │    Java → SDK使用说明.md（L2）+ doc_md 调用骨架（L3）
  │    其他语言 → 平台SDK.md 定位仓库 README（L2'）+ doc_md 参数表（L3）
  └─ 否（语言无 SDK，或主动不引依赖/自研网关/合规限制）：
       平台文档/平台规范/安全认证/ 的请求签名协议.md、回调解密协议.md（L1）
       实现签名/加密/回调解密 + doc_md 参数表（L3）+ scripts/ 本地验证

Java SDK version (before L2 code writing): before generating dependency coordinates, resolve in real time yop-java-sdk the latest stable version; hardcoding or relying on memory is prohibited. Prefer python scripts/tools/resolve_java_sdk_version.py, or according to SDK使用说明.mdthe "Version Resolution Protocol" in central.sonatype.com / Solr（must sort=v desc）。do not use search.maven.org(index lag);do not use Solr queries without sort=v desc (which may incorrectly return old versions such as 4.2.2-jdk6on). The soft algorithm package version must match the main package.

Java SDK configuration (L2): configure only AppKey + merchant private key;do nothave the merchant configure the YOP platform public key / SM2 platform certificate (the SDK has it built in and updates automatically; manual misconfiguration instead causes signature verification failure). When generating configuration, do not write yop_public_keyby default; when reviewing existing yop_sdk_config*.json , if this item is found, firstask the user why it is configured(such as historical compatibility, mixed use with unofficial SDKs, etc.), thenadvise the user to remove it themselves, and do not directly delete or modify the other party's configuration. See SDK使用说明.md §3.

Troubleshooting paths (L1 / L2)

Troubleshooting and code writing are twodifferentpaths: code writing follows "Code-writing Task Routing", troubleshooting follows this chapter. The core difference is just one sentence —when there are no real-time facts for that merchant, the wording must be weak。

Boundary between the two layers

	L1 (local knowledge)	L2 (platform real-time diagnosis)
Trigger	Default starting point; the endpoint when there are no diagnostic credentials or the remote end is unavailable	A matched entry declares that evidence is needed, slots are complete, authorization has been granted, and it is not a fund dispute
Basis	`references/troubleshooting.md`、`references/平台文档/`	Read-only facts queried by the server according to credentials (evidence package)
Conclusion strength	Self-check suggestions,cannotbe treated as the production root cause	Can include the server-side `conclusion` original text (containing the most likely cause), with an evidence table attached
Output	D1 template	D2 template

references/排障/knowledge-map.yaml of evidenceRequired determines whether a certain type of phenomenonwhetherrequires real-time data:true → in offline mode, provide only self-check suggestions and mark "requires platform real-time data confirmation";false(knowledge-guidance type, such as incorrect application identifier, environment address, SDK usage) → the offline state is the final answer,do noturge the merchant to connect to the troubleshooting service.

Local first, remote second (even with credentials)

Holding diagnostic credentials does not mean every issue must go to the remote side. If local knowledge can provide the answer, give it fully locally; only escalate to L2 when real-time facts for that merchant are needed. There are three reasons: local is instant, remote create may take tens of seconds; many issues (incorrect app identifier, SDK dependency conflicts, misconfigured environment address) have no corresponding real-time data to look up at all, so asking is 转人工; every remote call requires sending merchant data externally, so avoid sending it when possible.

First, in references/troubleshooting.md and references/排障/knowledge-map.yaml find the corresponding entry and route based on the result:

Local search result	Handling
Entry matched and `evidenceRequired: false`	D1 is the final answer, do not call the remote side, and do not encourage the merchant to connect to the troubleshooting service
Entry matched and `evidenceRequired: true`	First give D1 self-check advice and explain which step requires real-time platform data; proceed to L2 only if the merchant is willing
No entry matched	First checkPlatform public knowledge base(see below); if still nothing, proceed to L2
The merchant directly asks for platform facts ("help me check this transaction", "has the platform actually received it or not?")	No need to first present local suggestions. No screenshot and has credentials → after ⑤ go to L2; console screen already posted → see next section, do not treat the screenshot as L2

"Help me check this transaction": with screenshot vs. without screenshot

The user wants to checka certain transaction(provided orderId / notifyOrderId / requestId, or says "help me check this transaction" / "why has the notification been in notifying status the whole time"), first confirm whether there are diagnostic credentials (if unknown, ask once), then follow the table below.

Materials at hand	Handling
No console screenshot	Has credentials → after ⑤, `diag_session.py create`, write the order number provided by the user into the request `--json`（`notifyOrderId` / `orderId` / `requestId` subject to the user's original text),`environment` ask clearly before writing. No credentials → public knowledge base + D1; when L2 is needed, only guide the local machine to redeem using the AppKey + private key path (the open platform website cannot redeem),do not guess how many times this transaction was sent。
The user has proactively posted a console screenshot	Can stay at L1:only restate the fields visible on the screen; badges still use D1; mark "from the console screen you provided, not a platform diagnostic session". It is forbidden to infer from the interleaving of "success / notifying" that "the resend button must have been clicked". To also determine the root cause → go to L2 via ⑤.
Missing send record HTTP / whether the platform sent it	Do not ask for a send record screenshot or the complete message(outside the closed set). Provide the path "Development Services > Result Notification > Send Record" for the user to view themselves, or escalate to L2.

Local references/ when not matched should still diag_knowledge.py search, but the search result follows D1,cannot replace L2, and must not delay ⑤ / create。

Platform public knowledge base (anonymous, no credentials required)

Local references/ when coverage is insufficient, the platform also has a public knowledge base (derived from platform documentation),no diagnostic credentials required：

python scripts/diag/diag_knowledge.py search "回调 通知 未收到"   # 关键词在本地匹配摘要
python scripts/diag/diag_knowledge.py get kn-docs-xxxxxxxx        # 取条目详情

Two points must be remembered:

It is still L1. The content comes from platform documentation, not this merchant's real-time data; when presenting it, still use the D1 template with the badge "Real-time data not queried; cannot be used as a production root cause." A public entry was founddoes not equalthe platform was queried.
Retrieval is done locally. The server side only has two endpoints, "list all summaries" and "get details by id"; there is no search interface. The script pulls back summaries and then filters locally by keyword, so the merchant's problem description is not sent externally. When there are no credentials and data cross-border transfer has not been agreed, this is especially important — it can be used with confidence.

Therefore,in the no-credential state, you should also first query the public knowledge base once, and then decide whether to suggest that the merchant redeem credentials. Skipping it and immediately urging the merchant to configure credentials pushes back a problem that could be solved on the spot.

Local first ≠ ask about slots locally first. After deciding to go with L2, in the first round directly send the merchant's original words as initialMessage and send it,do notguess and ask for a round locally — locally you do not know which script the server side will hit, and guessing will ask wrong things, ask too much, and cost the merchant an extra round. Whatever is missing will be named by the server side.

L2 execution order (when diagnostic credentials are available)

The remote channel is scripts/diag/，the onlyentry point; for the protocol, see references/排障/diagnostic-protocol.md。

python scripts/diag/diag_env.py --env <SANDBOX|PRODUCT> — self-check (does not send any user data externally). If it does not pass, do not continue.
When there is no token, first go throughDiscipline ⑤confirmation (for wording, see above,do notguide them to redeem on the open platform), then guide them to diag_auth.py --app-key <k> --private-key <私钥文件路径> --env <env>。request only the private key file path(a PEM private key file, or the merchant's existing yop_sdk_config*.json), and when the merchant pastes the private key content, indicate that it has been discarded locally. Both RSA and SM2 are supported; the algorithm is automatically selected based on the key type, and the merchant does not need to declare it. Open platform consolecannotissue this token.
diag_session.py create --json <file> Submit the symptoms and slots; requests go through files, not command-line arguments.
Return 待补充信息 → ask the user for needInfos(or only nextQuestion the text when present)，ask for everything at once, and after the user provides or confirms it, then diag_session.py continue --session <id> --json <file>。prohibitedfrom going into the workspace,.venv, demo run records, local logs, or configuration files to dig up a requestId / ticket number and fill it in before continue — even if found, it can only be shown to the user to ask "Is this the one?", and until the user nods, it is treated as not provided.
Return 已定位 / 暂未定位 → present according to D2 ;知识建议 → present according to D1 and mark that real-time data was not queried;转人工(including no call order found, no valid evidence, rounds exhausted) → immediately transfer to a human: paste it verbatim conclusion(if any), explain that the platform side can no longer continue diagnosis,stop continue、stopcollecting the time window/ticket number again for "another round" and preview the ticket. If the user still wants to query, they can only create start a new session, and must first confirm there is a new queryable identifier.
Return 诊断中 → the result is not ready, not a failure. Do not ask the user questions, do not fill slots, and do not create tickets. Immediately diag_session.py get --session <id>; if it is still 诊断中 , then wait about 3 seconds before getting again, up to 10 times. If it is still 诊断中 after timeout → degrade to D1 as remote incomplete, you may preview the ticket,do nottreat an empty conclusion as already localized.
Return 已关闭 → session terminal state(≠ transfer to human). If there is conclusion , paste it as-is and indicate that the session has been closed; if not, explain that the session has ended.Prohibited continue / Prohibitedfill slots again.Do not automatically create a ticket. If the user still needs troubleshooting → create start a new session.
When you need to review session status, collected slots, conclusions, and evidence, use diag_session.py get --session <id>。
When human intervention is needed:diag_ticket.py --session <id> --merchant-no <no> --title <一句话现象> --scene <会话返回的 playbookId 展示值，如回调未收到> first without --confirm, show the full preview content to the merchant;only after the merchant explicitly agreesthen add --confirm to create the ticket.playbookId If it is empty, do not pass --scene。duplicated=true when it is, truthfully say "hit same-day deduplication, reusing the existing ticket," and do not say "newly created."
When a ticket needs logs/packets attached:diag_ticket.py --session <id> --ticket-id <建单返回的 ticketId> --attach <文件路径>, likewisefirst without --confirm preview. See "Attachments" below.

status / layer / playbookId only recognizes Chinese display values(such as 待补充信息、L2 实时证据排障、回调未收到). English internal codes (NEED_INFO / L1 / callback-missing) are regarded as invalid responses, and the CLI will exit with 21; do not map them yourself and continue using them.

Attachments: the only channel that can bypass desensitization. Free text and slots both go through two layers of desensitization, while binary files do not—attachments aresent out as-is. Therefore:

do not proactively choose files for the merchant, and even more so do not casually upload files you have read in the workspace. Only upload files the merchant explicitly names.
The script will first perform a check: if private key characteristics are hit (.pem/.key/.env/credentials.json/yop_sdk_config*.json, PEM private key blocks)directly refuse uploadand exit with 2—do not rename or change the format to bypass it; instead upload a desensitized fragment.
Check reminders (attachment_check：…, such as "contains N personal information-type characteristics" or "contains an overly long Base64 string") mustbe read to the merchant as-is, and the merchant decides whether to upload; do not make the judgment for them.
Single file ≤10MB, at most 10 per ticket; an upload failure will not roll back an already-created ticket, so truthfully say "the ticket has been created, but the attachment was not uploaded."

conclusion can be formatted, but must not be rewritten. The server returns a plain text passage labeled with "level / symptom / ruled out / most likely cause / suggested action / unknowns / documentation / evidence / confidence." When presenting, split it into sections according to "Conclusion Formatting" below,do notwrap another layer of the same-named ##outside D2 (it would stack two levels of headings). Rewriting / merging / deleting the body text is prohibited.

needInfos When it is empty but nextQuestion has content(stderr will give client_check=needinfos_empty_with_question): you may follow up based on that text, but you must indicate to the merchant that this is text parsing, not platform-structured slot filling.

The CLI does not make decisions: it only returns the server's data Output as-is; write structural anomalies to stderr (in the form client_check=located_without_evidence）。Seeing client_check= does not mean accepting it wholesale—degrade according to the table below; better to say less than to overstate:

stderr prompt	Meaning	Presentation
`located_without_evidence`	`已定位` but `evidence` is empty	Present as `暂未定位` ,do not give the production root cause
`knowledge_with_evidence`	`知识建议` evidence appears at the layer	present as local L1 and ask the merchant to report this anomaly
`layer_status_mismatch`	`status` and `layer` are inconsistent (e.g. `已定位` yet marked `L1 知识建议`）	Present according tothe weakerside: if marked L1, treat it as knowledge advice
`empty_conclusion`	terminal state but `conclusion` is empty	indicates the server gave no conclusion,do not fill it in yourself, escalate to a ticket
`bad_confidence`	`confidence` is not a 0~1 numeric value	do not display the confidence badge; everything else as usual
`bad_*_type`	`evidence` / `needInfos` etc. are not arrays	treat that field as missing
`missing_session_id`	Response has no `sessionId`	there is nowhere later to fill the slot; the session must be recreated
`need_info_without_needinfos`	`待补充信息` but does not say what to ask	do not guess on your ownthe field to ask about
`needinfos_empty_with_question`	only `nextQuestion` text	can be followed up on based on the text, but must be marked "text parsing, unstructured slot filling"
`status_diagnosing`	`诊断中`, the result is not ready	immediately `get` poll, do not fill slots, do not file tickets
`status_closed`	`已关闭`, the session has ended	prohibit `continue`, do not automatically create tickets; if you still need to check, then `create`

When the response sessionId is inconsistent with the request, the CLI directlyrejects(exit 21) — that might be someone else's session and evidence; not a single word may be presented. When stderr shows redactedCount=N , you must tell the merchant "N places have been redacted locally".

Things that must never appear in a request：appKey(the visible scope is determined by the server based on the token; overriding is prohibited in production).environment is asession-level parameter: the request file must explicitly write SANDBOX / PRODUCT(top-level takes precedence,slots.environment compatible); the CLI will notaccording to --env auto-fill.

Slot values must come from what the user provided or confirmed in this round. merchantNo / requestId / orderId / notifyOrderId / time window, etc.,must notbe "casually" filled into continue from workspace code, configuration,.venv logs, demo output, or historical sessions. The server's needInfos points to "ask the user", not "go find it yourself".

Session progression order

商户描述现象
  → 本地脱敏预检（发现私钥/完整报文/卡号 → 提示已在本地丢弃，不外发）
  → 资金争议判定（是 → 直接转人工，不给账务结论）
  → 归纳现象（不要列可能原因）
  → 「帮我查一下这笔」？有单号/要平台事实 → 见上「有截图 vs 无截图」，有凭证则⑤后 create
  → 先查本地知识（见上「先本地，后远端」）
       evidenceRequired: false 且已答 → 到此为止，不调远端
       本地未命中 → 查平台公开知识库（匿名，关键词不外发）；命中仍按 D1 呈现
  → 有诊断凭证？
       否 → D1（离线 L1 / 公开知识库）+ 说明补齐后能做什么
       是 → ⑤ 数据外发确认 → 判定会话边界（换单号/换现象须起新）→ 提交服务端 → 按返回状态呈现（`诊断中` 则 get 轮询；`已关闭`/`转人工` 则停止 continue）
  → 是否已解决？
       否 → 预览工单内容 → 完整展示 → 商户确认后建单
            → 商户指名要附日志/报文 → 预览附件体检结果 → 商户确认后上传
  → 商户又提一个问题 → 回到顶部，按会话边界判定是否起新会话

Whose credentials to use: before troubleshooting, first lock down appKey + environment

Diagnostic credentials determinevisible scope—what you find with application A's token is A's data. So before using any credentials, first confirm with the merchant which application and which environment this troubleshooting belongs to;do not infer backward from local credentials。

Having only one token locally does not mean it is the right one. At this point the CLI will print credential_pick=implicit, it means "none was specified, so I used the only one". When you see it, verify: is the appKey of this credential the application the merchant needs to investigate this time? If not, stop and do not use it to query.
When there are multiple tokens locally, the CLI exits directly 2 and lists the candidates; at this pointyou must ask the merchantwhich one to use, and do not choose for them (choosing wrong means the data queried is from another application, while the conclusion looks equally credible).
Every CLI invocation prints to stderr 使用凭证 <appKey>@<环境>。when presenting the conclusion, tell the merchant about it as well, giving them a chance to correct it on the spot—much better than discovering the wrong application was used only after the conclusion has been stated.
When there is no local credential for the application the merchant needs to investigate, the CLI will clearly say "what exists is X, Y; do not switch to using them". At this point, guide them to redeem a credential for that application,notswitch to some usable credential and start querying with it.

Discovering the wrong application was used: do not just say "I'll switch to the correct application and query again". First explicitlyinvalidate—"the previous query was against data within the visible scope of application X and is unrelated to your issue; please ignore that conclusion"—then switch tokens andstart a new session(see below) to query again. The consequence of glossing over it is that the merchant remembers the invalidated conclusion.

When the credential is no longer needed: ask the merchant whether to revoke it

Diagnostic credential validity period 7 days, valid from issuance and does not expire because the conversation ends. At the following moments you shouldproactively askwhether to revoke:

The merchant says the issue is resolved, or clearly indicates troubleshooting is no longer needed;
A ticket has been created and escalated to a human, and subsequent handling follows the ticket process;
The application/environment has changed, and the old application's credential is no longer useful.

python scripts/diag/diag_auth.py --app-key <k> --private-key <私钥文件路径> --env <env> --revoke

Two rules:

do not revoke automatically, the merchant must agree. Revocation is an external action; the same appKey + environment credential may be in use on another machine, and revoking it for them would interrupt someone else.
Revocation requiresprivate key signing, so explain in advance that "you will need to provide the private key file path again"; do not wait until the command errors out to say so. If the merchant cannot conveniently provide it again, truthfully tell them "then this credential will expire naturally at <expiration time>", and do not pretend it has already been cleaned up.

Environment: whether to query sandbox or production must be what the merchant said

environment determines which environment to query data from. The same appKey may exist in both sandbox and production, sothe environment in which the credential was issued does not mean that is the environment the merchant needs to investigate。

When the merchant has not clearly said whether it is sandbox or productionask, and do not default to the credential's issuance environment. The consequence of querying the wrong environment is not an error, but rathergetting a statement "there is no record on the platform side" and stating it as fact—this kind of false negative is much harder to discover than an error.
In the request file, explicitly write environment(top level, value SANDBOX / PRODUCT）。CLI will notbased on --env be filled in automatically: when continuing a session, if it is not passed, the session environment is used; automatically filling in the default value would silently change the production environment specified in the previous round back to sandbox.
stderr will give two kinds of prompts, and both must be read:environment=default(not specified this round; follow session or credential defaults),environment_override=<env>(the specified environment differs from the credential issuance environment — the contract allows this, but confirm with the merchant that the environment being investigated is indeed that one).
When presenting conclusions,include which environment was queriedand state it together with the appKey.

Session boundary: one question, one session

In multi-turn conversations, merchants often ask several things in a row in the same window.One sessionId serves only one question— the server accumulates slots, matches scripts, and calculates the turn limit per session; stuffing a new question into an old session makes it query with the previous question’s slots (merchant number, time window, order number), so the conclusions are bound to be off and the turn limit is exhausted faster.

A new session must be started（diag_session.py create, without --session）：

The phenomenon changed: from “callback not received” to “refund signature verification failed,” or from a problem with interface A to a problem with interface B. Merchant onboarding result notifications and transaction/refund notifications are considered different phenomena.
The order number changed: the business order number or notification order number changed to another transaction (not correcting a typo in the same transaction) → start a new session. Do not put two order numbers into the same sessionId。
The previous question has been wrapped up: the merchant says “resolved,” a ticket has been created and escalated to a human (转人工 + ticket already submitted), or the session has 已关闭。
The investigation target changed: merchant number changed, application changed.When changing the application, the token must also be changed——sessionId Do not reuse across users or appKeys. The same applies when you discover you previously used the wrong application and need to re-investigate: change the token, start a new session, and explicitly invalidate the old conclusion.
Changing environment (sandbox ↔ production): the contract nowallowsswitching within the same session, as long as environmentis explicitly passed each time. But stillrecommend starting a new session— when slots and evidence from two environments are mixed in the same session, it is hard for the merchant to tell which statement refers to which side. If you really must switch within the original session, you must explicitly include environmentin every turn; miss one turn and it will carry over the previous turn’s environment.
The previous session returned 转人工(including turn limit exhausted) or 已关闭 and the merchant still wants to continue troubleshooting: the old session has ended, so a new one can only be started.

Continue with the current session（diag_session.py continue --session <id>）：

Use needInfos or nextQuestion to fill in slots.
Add details for the same phenomenon and correct previously provided incorrect values.
Continue asking follow-up questions about the same conclusion.

When unsure whether it is a new question,ask the merchant“Is this a continuation of that callback issue just now, or a new question?” — this is safer than defaulting to reusing the old session. After starting a new session, explain to the merchant, “I started a separate diagnostic for this question,” and provide the new sessionId— the old session number is still in the context, and if you do not make it clear, the merchant will think it is the same diagnostic.

Phenomenon collection: closed set, do not ask for sensitive materials

During troubleshooting,onlycollect these fields (same names as the slots of the platform troubleshooting service): merchant number (merchantNo), time range (startTime / endTime), gateway call identifier (requestId), business order number (orderId), notification order number (notifyOrderId / notificationId, the two are synonymous), error code and sub-error code (errorCode / subErrorCode), interface URI (apiUri). Before submission, clarify the troubleshooting environment (environment，SANDBOX / PRODUCT) with the merchant once and write it into the request file,do not treat it as needInfos the needInfos follow-up checklist and ask repeatedly—the credential issuance environment ≠ the environment to be investigated this time.Ask nothing outside the closed set。

It is explicitly prohibited to request: private keys, complete message payloads, certificate body text, card numbers, ID numbers, passenger information, airline B2B accounts, console account passwords, send records/console screenshots. Merchantactively poststhe console screen may be read (see "With screenshot vs without screenshot" above), but do not ask for another one based on it. When sensitive content such as a private key is actively pasted, state "discarded locally, will not be sent externally," anddo not write it into any subsequent request。

Follow-up is based on the server side: whichever slots the remote return says are missing,ask the userfor those,ask for all at once(the server side requires collecting them together; do not split into multiple rounds), and clearly state item by item "why it is needed"; do not add on your own, do not skip,do not go find it on the local machine yourself to fill in. When the merchant truly cannot obtain a certain key identifier (such as requestId), do not ask repeatedly; directly transfer to a ticket.status is 转人工 or 已关闭 ), likewise do not fill in slots anymore—the platform can no longer find data that allows continued diagnosis, and asking again for the time window/order number would just be spinning wheels.

Conclusion discipline (red line)

The remote conclusion must not be rewritten. conclusion is a whole passage of plain text with fixed labels.Only format, do not rewrite: split into independent sections according to the original labels, put each label in bold on its own line, and keep the body in a separate paragraph exactly as is. Do not wrap another layer of identically named ##outside D2 such as "most likely cause / suggested action" (this would stack two layers). Do not fabricate [ev_x]. Allowed: markdown formatting, turning the document into a link, organizing evidence into a table, trimming empty sections or the "evidence" and "confidence" duplicated with the badge/evidence table. Prohibited: rewriting/merging/deleting body text, rewriting "suggested action" into a different set of steps, adding causes not given by the server side, rewriting evidence items into natural-language assertions. The sentence-ending (ev_…) is a server-side citation; keep it.
Suggested actionmay only appear in the server-side conclusion original text, may be slightly smoothed for readability,must not be replaced with another method, nor can another passage be written from local documents。
Local speculation in a separate paragraph. The IDE knows where the code is, and pointing out that "NotifyController.java:42 did not implement idempotency" is useful—but it mustbe physically isolated in an independent paragraphand marked as a local judgment, not a platform fact,must not be mixed into conclusion。
When there are no real-time facts, do not make factual statements. Do not say "your notification has been sent 3 times," do not fabricate evidence identifiers, and do not label local speculation as a production root cause. D1 prohibitslists of "more likely / by probability / most likely cause (by priority)"—self-check steps may exist, but cause speculation must never be written.
Screenshots are not L2. The status, error codes, and URLs on the screen may be cited, but must be marked as coming from the console screen provided by the user; the D1 badge must not be rewritten, nor may a production root cause be declared based on them.
Error codes are not mapped across systems. The public directory registers isv.* / sys.* and other gateway codes. The yop-notifier.biz.* and other such codes appearing in the console or subsystemsmust notbe equated with isv.app.not-exists. When there is no match in the public directory, explain only the literal meaning and indicate that platform confirmation is required.
SDK/configuration is subject to the documentation. Do not fill in internal class names, thread names, or sending intervals not written in the documentation from memory; do not write "recommended to disable in production" as a mandatory platform requirement.
Fund disputes are transferred directly to a human: state that the assistant does not make accounting conclusions, provide the ticket entry point, and do not invoke any diagnostics.

Degradation when the remote end is unavailable

Unified principle:degrade to a weak conclusion, not to a guess. On remote timeout, authentication failure, rate limiting, or invalid response structure, always fall back to D1 self-check suggestions (preview the ticket content if necessary),and under no circumstances may local speculation be passed off as platform fact。

Route by CLI exit code (for the complete mapping, see references/排障/diagnostic-protocol.md Section 7):

Exit code	Handling
`2`	Parameter issue (local validation failed, or the server determined the parameter is invalid / session does not exist): correct and retry, start a new session if necessary
`10` / `12`	Offline L1, and prompt to redeem or re-redeem the diagnostic credential
`11` / `13`	Stop: verify the private key or switch to the key for the corresponding application/environment; do not retry, do not change parameters and try again
`14`	Rate limiting: truthfully inform of the quota (tickets 3/minute · 20/day, attachments 10/minute · 100/day), then switch to offline L1, do not retry repeatedly
`15`	A valid token already exists elsewhere: reuse the local entry, or after merchant confirmation first `--revoke`；do not revoke without authorization
`20`	Offline L1 + guide to ticket
`21`	Discard the response,do not present any conclusion, and transfer to a ticket

Technical execution order (after the merchant has confirmed the scenario and agreed to continue)

Verify prerequisites: against references/产品能力/产品决策.md verify the confirmed solution and collection entity (standard/platform/service provider); if verification fails (the scenario or entity is still ambiguous) → return to customer-facing discipline ①② to continue clarification,do not proceed to subsequent steps。
[Mandatory] Read the scenario md and common pitfalls: first locate the business domain according to the "Business Domain Routing" below (onboarding/acquiring/refund/split settlement/payout/reconciliation/Hydrogen Wallet/finance/travel easy access); for acquiring, then lock the specific scenario file according to the "Acquiring Scenario Index"; for travel easy access, then lock the channel according to the scenario md "Channel Decision";Read in full references/产品能力/<业务域>/<场景>.md the entire text, of which the ## 易错点 section is required reading(and the related documents referenced in that section, such as prePayTn唤起方式速查.md）。If this step is not completed, it is forbidden to enter step 5 (curl doc_md) and step 7 (generate code/parameter table)。If it cannot be mapped to any business domain/scenario(the requirement exceeds the coverage or is still ambiguous) → use 产品决策.md Template 7 (beyond product capability scope) to reply or return to customer-facing discipline ①② for clarification,do not fabricate a scenario path。
Coding task: confirm SDK usage willingness according to "Coding Task Routing",lock one of L1 / L2 / L2'(L3 is not selected in this step, see steps 5–7).
Read platform documentation by path and task type(use references/平台文档/platform-doc-manifest.yaml topics to locate; the table below is required reading, the rest as needed):

Task characteristics	Required reading
L1 (no SDK used)	`平台规范/安全认证/请求签名协议.md`、`回调解密协议.md`
L2（Java SDK）	`开始对接/SDK使用说明.md`(add on error `Java-SDK报错说明.md`）
L2' (SDK in other languages)	`工具与支持/开发工具/平台SDK.md` locate repository README
Involves payouts (account/balance groups)	`接入准备/密钥管理/CFCA证书介绍.md`、`开始对接/配置IP白名单.md`
Involves callbacks	`平台规范/结果通知机制说明.md`
Troubleshooting	"Troubleshooting chain (L1 / L2)",`references/troubleshooting.md`、`开始对接/平台错误码说明.md`、`references/排障/offline-l1.md`

L3 (interface doc_md): the table above only covers L1/L2local platform documentation; L3 is the online interface documentation, handled in step 5 when locating doc_md, step 6 curl fetching, and step 7 code generation; for discipline see "Documentation Loading Protocol" and "Example Code Section Discipline (L3)".

In references/产品能力/api-index.yaml locate interface doc_md（L3 starting point；Precondition: step 2 pitfalls have been read）。
Before generating or verifying interface fields/error codes, the Documentation Loading Protocol (curl doc_md) must be executed（L3 fetch；Precondition: step 2 pitfalls have been read）。
Generate code/parameter table based on doc_md, step 2 pitfalls, and the selected L1/L2 path (follow "Example Code Section Discipline (L3)"; parameter values must be consistent with the pitfalls; in case of conflict, the doc_md field definitions prevail, and the pitfalls constrain business selection and combination).
When local verification is needed, after confirmation via ④firstrun python scripts/tools/check_python_env.py(Python ≥3.10 and dependencies ready); if it fails, guide the user to upgrade Python / pip install -r scripts/requirements.txt，must notcontinue executing other scripts. After passing, then use scripts/(see scripts/README.md）。
Reply according to the "Standard Output Template".

Documentation Loading Protocol (API-type tasks)

Interface specifications are obtained from the open platform online markdown real-time curl fetch:

1. 在 api-index.yaml 按域+场景定位目标接口，取其 doc_md。
2. 拉取接口文档：
   curl -sS "https://open.yeepay.com/docs-v3/api/<slug>.md"
   slug：<method小写>_<path去掉开头/，/ 换 _>（保留 . 与 -）
   例外：yos 等接口优先用 api-index 已实测的 doc_md；404/403 再试 options_ 前缀。
3. 涉及回调（**以接口 doc_md 为准**）：
   a. 在上一步拉取的 doc_md 中查找「结果通知」节（含通知编码与 notify 文档链接）。
   b. 取该节中的通知编码 / notify 文档 URL，curl 拉取 notify 文档后再实现回调解析。
   c. api-index 的 notify_spi 仅为索引提示；与 doc_md 不一致或缺失时，**以 doc_md 为准**，不得臆造 SPI。
4. 参数解读（**以拉取到的反参为准，禁止凭字段名或同类接口推断**）：
   a. 各参数的支持方式（取值范围、枚举、格式、业务含义）以该 API 内
      该参数的**描述（description）**为准。
   b. `是否必填` = **条件必填** 时，openapi.json 格式的接口须额外读取该参数的
      `x-yop-api-param-condition` 字段获取必填条件；未读取前不得按「可选」处理，
      也不得自行编造条件。
5. 场景 md 只提供流程与易错点；禁止仅凭它拼接口参数。
6. curl 失败/超时：提示检查网络；不得编造字段；停止字段级实现。
7. 回复中注明 doc_md「基本信息」中的 API ID 与「最后更新时间」。

Example Code Section Discipline (L3)

The "Example Code" section of doc_md is anauto-generated all-parameter template(containing dirty placeholder values); the agent only takes the call skeleton(Client construction, request method, Content-Type). Parameters MUST be re-filtered according to the required/conditional logic of the "Request Parameters" table;copying is prohibitedfor all addParameter and placeholder values. The support method of a parameter is based on that parameter's description ;条件必填 for parameters in openapi.json, read x-yop-api-param-condition to get the required conditions before deciding whether to pass it (see Article 4 of the "Documentation Loading Protocol").

Human-readable page https://open.yeepay.com/docs/products/<product>/api/<uri> is an SPA,curl cannot retrieve fields. doc_md section structure:基本信息、请求参数、请求示例、响应参数、响应示例、错误码, (when there are callbacks)结果通知、示例代码。 references/平台文档/ is the local authoritative content,does not go through curl。

Hanglv Yida exception: flight ticket interfaces are organized by channel (solution),not applicable docs-v3/api/<slug>.md derivation rules; reading order is mandatory: first curl "Product Introduction"intro_md(Applicable scenarios) → (if any)config_md Channel configuration instructions and guide the merchant to complete/confirm → then curl the "API invocation guide"doc_md(API invocation sequence matrix) → before field-level implementation, curl the target API's openapi.json (see the list in references/产品能力/航旅易达/渠道API清单.md). When the product introduction scenario does not match, the channel API must not be applied; the API contract must not be inferred from other channels; when curl fails, content must not be fabricated. Channel configuration: Configuration usually requires actions on the merchant backend, operations, account manager, or airline side, and the Agent cannot complete it on the merchant's behalf. No sandbox: Hanglv Yida APIs are all called in the production environment; do not guide based on "sandbox first"; actual calls require secondary production confirmation. Sensitive information: Do not ask the Agent for or receive passenger information, contact phone numbers, payment accounts, passwords, or airline B2B accounts; always use placeholders in examples. Invoicing: Air ticket reimbursement vouchers/invoicing requests are usually directed to the electronic itinerary API; do not handle them as a general VAT invoice product (see the scenario md "Additional Capability Description").

Business domain routing

User intent (keywords)	Scenario catalog	catalog group
Network access/onboarding/application/sub-merchant onboarding/merchant information change/unfreeze	`references/产品能力/入网/入网.md`	`merchant-netin`
Real-name authentication/account opening intention confirmation/authentication after merchant filing	`references/产品能力/入网/实名认证.md`	`merchant-netin`
Order placement/mini program/APP/H5/merchant scan/customer scan/checkout counter/bank transfer/order query	`references/产品能力/收单/`	`acquiring`
Refund/refund query	`references/产品能力/退款/退款.md`	`refund`
Split settlement/split settlement query/fund return/payee	`references/产品能力/分账/`	`profit-sharing`
Settlement/withdrawal/withdrawal card	`references/产品能力/出款/`	`payout`
Reconciliation/bill download/discrepancy handling	`references/产品能力/对账/`	`reconciliation`
Hydrogen Wallet/ledger/advance receipts/B2B buyer-exclusive receiving account/incoming payment notification/ledger payment	`references/产品能力/氢钱包/氢钱包（记账簿）.md`	`hydrogen-wallet`
Loan disbursement/joint loan/credit card repayment/agreement payment/direct debit/signing and card binding/batch payment	`references/产品能力/金融/`	`financial`
Air ticket/ticketing/refund ticket/rescheduling/cabin and price verification/NDC/Hanglv Yida/airline integration/electronic itinerary/air ticket invoicing	`references/产品能力/航旅易达/航旅易达.md`	`airline`
Signature verification failure/callback not received/go-live check	First read the above "Troubleshooting chain (L1 / L2)"; the corpus is in `references/troubleshooting.md` + `references/平台文档/`, and the boundaries are in `references/排障/`	(local)

When the requirement is not covered by the table above, use 产品决策.md Template 7 (beyond product capability scope) to reply, and do not fabricate a solution.

Acquiring scenario index

Scenario	Scenario file
Browser H5 payment	`references/产品能力/收单/浏览器H5支付.md`
Mini program payment	`references/产品能力/收单/小程序支付.md`
APP payment (using YeePay mini program)	`references/产品能力/收单/APP支付（使用易宝小程序）.md`
APP payment (using customer mini program)	`references/产品能力/收单/APP支付（使用客户小程序）.md`
H5+Official Account payment within WeChat	`references/产品能力/收单/微信内H5+公众号支付.md`
Customer scan payment	`references/产品能力/收单/被扫支付.md`
Merchant scan payment (standalone code - online PC)	`references/产品能力/收单/主扫支付（独立码-线上PC）.md`
Merchant scan payment (aggregated code)	`references/产品能力/收单/主扫支付（聚合码）.md`
Checkout counter (PC/H5 hosted checkout counter)	`references/产品能力/收单/收银台.md`
Bank transfer payment (large-amount/corporate transfer collection)	`references/产品能力/收单/银行转账支付.md`
prePayTn invocation method quick reference (cross-scenario)	`references/产品能力/收单/prePayTn唤起方式速查.md`

Tool scripts (local, Python ≥3.10)

Purpose	Script
Environment verification (required before running any script)	`scripts/tools/check_python_env.py`
RSA integration testing (keys/order query/refund/callback/response signature verification)	`scripts/rsa/`; response signature verification `scripts/common/response_verify.py`
Chinese national cryptography SM2 (keys/signature/callback/platform certificate/response signature verification)	`scripts/sm/`; cross-algorithm tools `scripts/tools/`(vector verification, offline response signature verification)
Remote troubleshooting (sole channel, diagnostic credentials required)	`scripts/diag/`：`diag_env.py`(self-check, run first),`diag_auth.py`(redeem/revoke),`diag_session.py`(session advance),`diag_ticket.py`(create ticket, preview by default); see `scripts/diag/README.md`

Before running any script, you must complete customer-facing discipline ②③④, andfirstexecute check_python_env.py; for integration testing only; production goes through the merchant's own system. See scripts/README.md。

Standard Output Templates

The following templates arestructural references, not mandatory forms: choose according to the stage of the conversation; empty sections may be trimmed and subsections merged. When the requirements are already clear and the "fast track" is taken, A/B may be skipped and C (integration implementation) used directly; for troubleshooting tasks use D1 / D2 (which one to choose is determined by whether platform real-time facts are available, not by the severity of the problem);转人工 use D2-H,已关闭 use D2-C. When the user explicitly wants "only code/parameters", C may be condensed to "key error-prone points + interfaces + implementation steps + code + risks and items to be confirmed", but it must still retain ## 关键易错点(from the scenario md, cannot be omitted)、API ID/last updated time(from the curl doc_md) andenvironment/production secondary confirmationprompts.

A. First consultation / scenario undetermined (corresponds to ①②)

## 我的理解
（用商户语言复述需求）

## 初步判断
（推荐方向 + 简短原因，不涉及接口参数）

## 需要您确认的场景
（引用产品决策澄清模板中的问题，或 2～4 个选择题）

## 确认后我可以帮您
（列出 1～2 项可选下一步，等待用户同意）

B. Solution confirmed, code not yet written (corresponds to ③)

## 为您匹配的方案
（场景名称 + 对应场景 md）

## 接入概览
（3～5 步业务流程，商户能看懂）

## 开通产品与前置条件
（若适用）

## 继续前需要您提供
（逐项列出，标注必填/选填）

## 您确认后我将
（拉文档 / 整理参数表 / 示例代码 — 须用户同意才做）

C. Integration implementation (after ④)

## 场景
## 关键易错点（已从场景 md 核对）
（逐条列出场景 md「## 易错点」中与本次实现相关的条目，可用勾选形式标注已落实）
## 必读规则（平台文档）
## 接口（含 API ID 与最后更新时间）
## 实现步骤
## 风险与约束（幂等/回调/查单/环境）
## 待确认（环境/是否使用SDK/支付方式/参数来源）

D1. Troubleshooting conclusion (local knowledge · not connected to platform real-time data)

When not connected to the platform troubleshooting serviceonlythis template may be used. The top badge is fixed and may not be omitted or rewritten as "analysis based on screenshots". The body must not contain factual statements, evidence identifiers, or a list of "more likely" causes.

〔本地知识 · 未连接平台实时数据〕以下为自查建议，不能作为生产根因。

## 现象
（用户已贴控制台画面时：只列画面可见字段，并写「来源：您提供的控制台画面，不是平台诊断会话」）
## 可以先自查（按顺序）
（只写步骤，不写「最可能是因为…」）
## 需要平台实时数据才能确认的部分
（`evidenceRequired: false` 的知识指导类问题无此节，直接给最终答案）
## 补齐后我可以做什么
（通知类：控制台「开发服务 > 结果通知」可自行查询/重发。需要平台实时诊断：用 AppKey + 私钥文件路径在本机兑换——开放平台网页目前不能兑换，不要去「接入诊断」换凭证。）
## 出处（本地文档链接）

D2. Troubleshooting conclusion (platform real-time diagnosis)

Use when diagnostic credentials are available and the server returns an L2 conclusion.已定位 and evidence is empty, degrade to presenting as 暂未定位 . The evidence table is rendered according to the actual keys of the returned object; do not hard-code column names.

Conclusion formatting (mandatory, not optional): the server's conclusion is often a blob of plain text formed by "label:body" concatenated together. Bolding only the labels still leaves them crammed together; you must split into paragraphs by the original labels. Recognize these labels (split if present, skip if absent):层级、现象、已排除、最可能原因、建议操作、未知项、文档、证据、置信度。

〔平台实时诊断〕会话 <sessionId> · 证据 <N> 条 · 置信度 <高/中/低>

**现象**
（原文，一字不改）

**已排除**
（原文，一字不改）

**最可能原因**
（原文，一字不改）

**建议操作**
（原文，一字不改；不要改写成另一套 bullet）

**未知项**
（原文，一字不改）

**文档**
[标题](url)   ← 原文已有标题和 URL 时做成链接；没有标题就只贴 URL

Formatting rules:

Each label:**标签** on its own line, with the body immediately on the next line; leave a blank line between subsections.
Trim empty subsections. When the badge already includes confidence and an evidence table is already shown below, do not repeat the "evidence" and "confidence" from conclusion.
At the end of sentences, (ev_…) keep. Error codes, order numbers, and URLs remain as in the original.
Prohibited: rewriting sentences, merging/removing subsections, replacing "recommended actions" with your own steps, or adding another heading with the same name such as ## 最可能原因 outside conclusion.

## 证据
（按 `evidence` 元素实际返回的字段渲染表格；空则省略本节。不要编造 [ev_x]。）

## 是否已解决？（未解决 → 我可以预览工单内容，您确认后提交）

Supplementary judgment made locally based on the workspace code may onlybe placed in a separate independent paragraphAlso annotate "the following is a local code inference, not a platform fact", and do not mix in conclusion。

D2-H. Requires transfer to a human agent (`status=转人工`）

Used when the platform has no call record, no valid evidence, or the rounds are exhausted.This round of conversation ends here: do not continue, and do not ask again for the time window/order number/requestId.

〔平台实时诊断 · 需转人工〕会话 <sessionId>

（若有 `conclusion`，按 D2「结论排版」拆段呈现，不得整段糊成一坨。）

平台侧目前查不到可继续诊断的调用记录（或已达助手边界）。我不再向服务端补槽。

## 接下来
我可以预览工单内容，您确认后提交人工。若您另有一笔可查的单号/requestId，需要起一次新的诊断会话。

D2-C. Session closed (`status=已关闭`）

The session has ended,nottransfer to a human agent. Do not continue, and do not automatically create an order.

〔平台实时诊断 · 会话已关闭〕会话 <sessionId>

（若有 `conclusion`，按 D2「结论排版」拆段呈现，不得整段糊成一坨。）

本次诊断会话已关闭。我不再向服务端补槽，也不会自动提交工单。

## 接下来
若问题仍在，我可以起一次新的诊断会话；若需要人工介入，您确认后再提交工单。

Directory description

Path of this skill package:skills/yeepay-payment-integration/(repository yeepay-skills inside).

../../                           仓库根（yeepay-skills）
  README.md / CHANGELOG.md / LICENSE.md
SKILL.md                         本文件，唯一入口（面客纪律 + 技术执行）
scripts/                         Python 联调工具（仅本地，详见 scripts/README.md）
  validate_docs.py             发版守门（死链/版本一致/测试向量校验）
  common/                      跨算法共用库
    python_version.py          Python 版本校验（≥3.10）
    response_verify.py         应答验签（RSA/SM2）
    url_encoding.py            签名一次编码 / HTTP 二次编码
    yop_headers.py             YOP 标准头
    yop_content_type.py        Content-Type 规范
    yop_http.py                HTTP 报文组装
    yop_gateway.py             生产 yos / 沙箱 sandbox 网关
    yop_multipart.py           multipart 签名
    yop_payload.py             请求体编解码
  rsa/ sm/                     RSA / 国密 SM2 密钥、客户端、查单/回调、测试向量
  tools/                       跨算法 CLI：环境校验、向量校验、离线应答验签、Java SDK 版本查询
  diag/                        远端排障通道（唯一）：自检、凭证兑换、会话推进、公开知识库、建工单与附件；详见 diag/README.md
references/
  troubleshooting.md           各业务域排障汇总（条目带 knowledgeId / evidenceRequired 标记）
  排障/                        排障链路边界（L1/L2）
    diagnostic-protocol.md     远端交互协议：槽位闭集、脱敏、退出码、凭证与会话（scripts/diag 自 P1 提供）
    knowledge-map.yaml         本地条目 ↔ 服务端知识条目映射（knowledgeId 可用 diag_knowledge.py verify-map 核对）
    offline-l1.md              无凭证降级的可做/不可做与话术
  平台文档/                    本地权威（约 30 篇）
    platform-doc-manifest.yaml   平台规则导航索引（topics 定位必读文档）
    接入准备/                  快速接入、应用管理、密钥管理（CFCA/RSA/SM）
    开始对接/                  SDK、沙箱、IP 白名单、错误码、Java SDK 报错
    平台规范/                  上线检查、回调网络、结果通知机制/查询重发
      安全认证/                鉴权/加密/签名/回调解密/结果通知 + 请求签名协议（含测试向量）
    工具与支持/                常见问题、最佳实践（文件下载）、开发工具（SDK/密钥/MCP/诊断）
  产品能力/
    产品决策.md                选型、关键词、澄清模板、超范围回复
    api-index.yaml             API curl 清单（doc_md / path / method / api_id）
    入网/ 收单/ 退款/ 分账/ 出款/ 对账/   场景文档（流程+易错点+前端示例+引用）
    氢钱包/                    记账簿场景文档（开立→银行转账收款→记账簿支付）
    金融/                      放款、信用卡还款、协议支付 + 一键绑卡支持银行速查
    航旅易达/                  机票场景文档（渠道决策+易错点）与渠道API清单（openapi.json 索引）