YSC绩效 — 纯本地规范 + 云端支付服务 · 月度绩效考核表 Excel 生成器（Pay Skill）

关键架构声明（v1.0.0 · 对齐平台修复指南）

本 Skill 不调用任何远程云端"代码拉取"接口。所有核心规范（设计规范 Markdown、Excel 生成代码模板、指标数据结构参考）随 Skill 包本地分发，运行期通过 assets/specs_hashes.txt 做 SHA-256 完整性校验，确保规范未被篡改。

CloudBase SCF 的角色：仅作为 Pay Skill 必要的 支付服务端。SCF 严格返回：
- 不可执行的 JSON schema（仅含版本号、价格、状态机定义等元数据）
- 订单状态机数据（order.status / payment_code / out_trade_no）
- 调用审计记录

SCF 绝不返回任何 Python 代码、Markdown 规范全文或可执行内容；Excel 完全由 Agent 在本地依据随包规范与模板生成。

密钥管理：不随包分发任何明文密钥。微信支付商户证书私钥与 SkillHub 开发者签名私钥仅存放在 CloudBase 函数环境变量（WXPAY_* / SKILLHUB_*），由发布方在云端配置，包内与仓库内均无密钥。

支付服务端入口（Pay Skill 必备）

本 Skill 为按调用量计费的付费技能（Pay Skill），通过 CloudBase SCF（云函数 ysc-jx-engine） 作为支付服务端入口。

服务端入口：
- HTTPS URL：https://ysc-cloud-d8ge1wodk63983d9a-1303626442.ap-shanghai.app.tcloudbase.com/ysc-jx-engine
- CloudBase 函数名：ysc-jx-engine
- 环境 ID：ysc-cloud-d8ge1wodk63983d9a（上海区域）
- CloudBase CLI 调用命令：tcb fn invoke ysc-jx-engine --params '{...}' -e "ysc-cloud-d8ge1wodk63983d9a" --json

平台审核入口（Pay Skill 平台审核时会访问）：
- POST {HTTPS_URL} （HTTP 触发器）或
- tcb fn invoke ysc-jx-engine --params '{"action":"health"}' -e "ysc-cloud-d8ge1wodk63983d9a"

SCF v1.0.0 支持的操作（全部免引入代码/规范，密钥仅存服务端环境变量）：
| 操作 | 用途 |
|------|------|
| health | 平台审核探活 + 配置自检（免鉴权，返回 config_ready / missing_env 变量名）|
| get-config-schema | 下发不可执行的 JSON schema（版本、价格、状态机等元数据）|
| invoke | 支付闸门：首次调用 → 微信支付 Native 下单 + X402 AI 预下单 → HTTP 402；支付后携带 X-Out-Trade-No 重试 → 查单核验 → 放行（fulfillment_granted:true）|
| query-order | 查询订单状态（out_trade_no）|
| log-call | 服务调用审计上报（不含岗位指标明细）|

支付状态机：INIT（已预下单）→ PAID（已支付）→ FULFILLED（已履约）→ REFUNDED（已退款）/ EXPIRED（已过期）

规范版本与完整性校验声明

本 Skill 的核心资产存储在 references/ 与 assets/ 目录，随 Skill 包一起分发：

校验规则：
1. 阶段1.6（运行期）：用 SHA-256 逐文件校验，对比 assets/specs_hashes.txt
2. 校验失败 → fail-closed：拒绝执行核心流程
3. SCF 不可达不影响本地执行；本地规范是唯一可信源

付费说明（Pay Skill · X402 协议）

本技能为按调用量计费的付费技能（Pay Skill），遵循 X402 支付协议（HTTP 402 Payment Required 的机器可协商支付流程），通过 SkillHub SkillPay 平台 + 微信支付 AI 专属卡完成支付。

X402 协议要点：
- HTTP 状态码 402 "Payment Required" 作为支付触发信号
- 支付触发响应头：WeixinPay-Required（值即 payment_code，交给 weixinpay_pay 申请授权）+ X-Out-Trade-No（订单号）
- 幂等键 out_trade_no：整个调用链路以订单号作为幂等与重试依据，已履约订单绝不重复扣款/重复交付
- 支付模式 pay_mode：AUTH_AND_PAY（授权并支付）
- 签名机制：微信支付 API v3 WECHATPAY2-SHA256-RSA2048 + SkillHub X402 SKILLHUB-SHA256-RSA2048（全部在服务端完成）
- fail-closed 原则：支付链路异常时拒绝放行，不自动降级为免费服务
- 密钥零分发：所有私钥只存在于 CloudBase 函数环境变量，不随包分发、不写入任何文件

计费方式：
- 按调用量计费（per_call），单次价格由发布方在 SkillHub 发布页设置（元/次）
- 每次完整调用（一次岗位月度绩效考核表 Excel 生成）扣 1 次费用

用户视角流程（使用和操作保持不变）：
1. 用户提供公司/岗位/JD/职责 → Agent 完成输入清点
2. Agent 在对话中展示价格 + 弹出支付授权（微信 AI 专属卡）
3. 用户在对话内确认付款 → 自动继续执行考核表生成
4. 用户拒绝/取消/超时 → 终止流程，不重试

架构概览

用户输入 → 输入清点 → X402 支付流程 → 岗位调研 → 本地加载核心规范（SHA-256 校验）→ 设计指标 → 生成考核表 Excel → 台账与说明
                          ↑                                ↑
                   402 + WeixinPay-Required            references/ + assets/
                   X-Out-Trade-No 幂等重试             随包分发 + SHA-256 校验

核心资产（设计规范、指标结构参考、Excel 生成模板）随 Skill 包一起分发，保存在 references/ 与 assets/ 目录中。SCF 仅承担支付服务角色，不参与规范下发。SHA-256 完整性校验确保运行期使用规范与发布版本一致。

阶段0：输入清点与补齐

启动后先盘点用户已提供的信息，按下表补齐缺失项。除"岗位名称用户未提供且无法推断"外，不因信息缺失而中断流程。

阶段0.5：X402 支付流程（Pay Skill 必做，含 5 大必备改造项）

本技能为基于 X402 协议的付费技能（Pay Skill）。用户输入信息清点完成后、进入阶段1调研之前，必须严格按 X402 流程完成支付。 整个支付流程对外表现为一次简单的"展示价格 → 用户确认 → 继续执行"，内部严格遵循 5 个必备改造项：前置检查、支付触发、重试机制、订单号传递、异常处理。

0.5.1 前置检查（Pre-check，X402 必备改造项 1）

执行 X402 支付前必须完成的检查项：

1. 检查 weixinpay 插件是否已安装（官方 Skill Prompt 前置要求）：确认当前 Agent 环境已安装微信支付插件（weixinpay_pay 能力可用）；
   - 已安装 → 可继续提供付费服务；
   - 未安装 → 提示"当前 Agent 暂不支持微信支付付费能力"，终止流程；
2. 调用支付服务探活：请求 SCF health，检查 config_ready；若 config_ready:false 则拒绝放行（fail-closed），提示"支付通道未就绪，请联系 Skill 发布方"；
3. 检查 SkillPay 配置完整性：确认 SkillHub 微信支付商户号、AI 专属卡支付通道、SkillPay 入驻状态均已就绪；任一缺失则拒绝放行；
4. SpendingPolicy 预算检查：检查本会话累计消费是否超出 per_session_budget、单次调用是否超出 per_task_budget，超出则提示用户并终止；
5. 检查历史订单状态（幂等防重）：若本会话/本请求已存在订单号（X-Out-Trade-No），先 query-order 查询：
   - FULFILLED → 直接复用历史履约结果（幂等命中，绝不复执行、不重复扣款）
   - INIT / 未支付 → 走 0.5.2 继续支付
   - EXPIRED → 走 0.5.2 重新发起

0.5.2 支付触发（Payment Trigger，X402 必备改造项 2）

执行 X402 协议的支付触发（场景一：首次请求，无订单号）：

1. 调用 SCF invoke 发起预下单（preorder）（服务端自动完成：微信支付 Native 下单 → code_url → SkillHub X402 AI 预下单 → payment_code）：

bash curl -s -i -X POST "https://ysc-cloud-d8ge1wodk63983d9a-1303626442.ap-shanghai.app.tcloudbase.com/ysc-jx-engine" \ -H "Content-Type: application/json" \ -d '{"action":"invoke","skill_id":"ysc-performance-table-builder","skill_version":"1.0.0","query":"<企业> <岗位> <月度>"}'

或 CLI：
bash tcb fn invoke ysc-jx-engine --params '{"action":"invoke","query":"<企业> <岗位>"}' -e "ysc-cloud-d8ge1wodk63983d9a" --json

2. 服务端返回 HTTP 402 + 响应头：
   - WeixinPay-Required: <payment_code>（AI 支付授权码）
   - X-Out-Trade-No: <out_trade_no>（订单号）
   - Body 含 code: PAYMENT_REQUIRED、amount、status: INIT
3. 展示价格并申请支付授权：向用户明确展示本次调用价格（以服务端 402 响应 Body 的 amount 字段为准，本次月度绩效考核表生成服务费用为 ¥{amount}，按次计费），将 WeixinPay-Required 的值作为 paymentCode 调用 weixinpay_pay 向用户申请支付授权（平台在对话内弹出微信支付 AI 专属卡，用户点击确认后扣款）；
4. 用户确认支付后，继续 0.5.3 的履约重试。

0.5.3 重试机制（Retry Mechanism，X402 必备改造项 3）

支付链路任何环节失败/超时，按以下重试策略处理：

1. 预下单失败重试（最多 3 次，指数退避 1s/2s/4s）：
   - 3 次后仍失败 → 0.5.5 异常处理；
2. 支付授权重试（最多 2 次，间隔 5s）：
   - 用户超过 15 分钟未授权 → 订单状态机置为 EXPIRED，提示用户重新发起；
3. 履约确认重试（场景二：支付成功后携带订单号重试，⚠️ 必做）：

> ⚠️ 支付成功后必须携带 X-Out-Trade-No 请求头重新请求本接口（body 与首次请求完全一致，仅通过 Header 传递订单号）；不携带该头重试将永远拿不到履约放行，并会重复创建新订单。这是官方提示中最易被遗漏的一步。

bash curl -s -i -X POST "https://ysc-cloud-d8ge1wodk63983d9a-1303626442.ap-shanghai.app.tcloudbase.com/ysc-jx-engine" \ -H "Content-Type: application/json" \ -H "X-Out-Trade-No: <0.5.2 返回的订单号>" \ -d '{"action":"invoke","query":"<企业> <岗位>"}'

• SCF 以 out_trade_no 查库 → 查微信支付单核验 trade_state=SUCCESS → 状态机置 FULFILLED → 返回 HTTP 200 + fulfillment_granted:true（此时才可执行阶段1及后续本地生成）；
• 幂等防重：若订单已是 FULFILLED → 直接返回 already_fulfilled:true，绝不复执行、绝不二次扣款；
• 状态异常（如 EXPIRED → 410）→ 按 0.5.5 处理；
  4. 禁止无限重试：所有重试都有上限 + 退避策略，禁止静默失败也禁止无限循环。

0.5.4 订单号传递（Order Number Transmission，X402 必备改造项 4）

out_trade_no 必须在整个调用链路中全程传递，作为 X402 协议幂等键与平台计费对账凭证：

1. 获取（0.5.2）：首次 invoke 时由 SCF 生成，通过响应头 X-Out-Trade-No 返回；
2. 传递至履约（0.5.3）：重试请求以请求头 X-Out-Trade-No 带回；
3. 记录至服务台账（阶段4）：生成的 Excel 旁附《服务记录》时写入订单号；订单号同时随阶段4的 log-call 上报审计；
4. 传递至异常处理（0.5.5）：退款/对账时用作状态机标识键。

0.5.5 异常处理（Exception Handling，X402 必备改造项 5）

X402 协议 fail-closed 原则：支付链路任何异常，必须明确拒绝，禁止自动降级为免费服务。

禁止行为清单：
- ❌ 支付失败/超时/取消后继续执行阶段1及后续
- ❌ SCF 不可达时静默跳过支付直接生成（本技能核心规范虽在本地，但未支付不得生成交付物）
- ❌ 预下单失败后多次自动重试而不告知用户
- ❌ 跳过订单号直接请求履约
- ❌ 履约失败后不退款而再次扣款
- ❌ 将密钥字符串持久化到任何文件 / manifest / SKILL.md

阶段1：岗位调研（职责/JD 不足时补充）

JD 与职责已充分时跳过调研，直接进入阶段1.6。

JD 缺失或不完整时，使用网络搜索补充岗位画像（搜索建议关键词：{岗位名} 岗位职责 任职要求、{企业名} {岗位名} 招聘 JD），综合行业通识判定：
- 岗位核心职责（3-6条，按重要性排序）
- 所属部门（按岗位族群推断，见阶段0）
- 行业特点：业务模式、上下游、关键利益相关方
- 可量化考核口径：该岗位最核心的经营结果（如销售岗=签约额/回款，生产岗=产量/良率/交期）

信息兜底规则：企业查不到公开信息（小微企业、新公司）时，以行业通识为主推断，并在对话中标注"⚠️ 基于行业一般情况推断，未经公司信息验证"。禁止编造具体公司事实。

阶段1.6：本地加载核心规范（SHA-256 完整性校验 · 无远程拉取）

v1.0.0 关键设计：本 Skill 不通过 SCF 拉取任何核心规范。所有规范在 references/ 与 assets/ 目录中随包本地分发，运行期用 SHA-256 完整性校验确保未被篡改。

SHA-256 校验步骤

import hashlib, os

EXPECTED = {}
with open('assets/specs_hashes.txt', 'r', encoding='utf-8') as f:
    for line in f:
        line = line.strip()
        if not line or line.startswith('#'): continue
        parts = line.split()
        if len(parts) >= 2:
            EXPECTED[parts[0]] = parts[1]

FILES = [
    'references/performance-review-spec.md',
    'references/template.json',
    'assets/generate_template.py'
]

for f in FILES:
    if not os.path.exists(f):
        raise Exception(f"规范文件缺失：{f}")
    actual = hashlib.sha256(open(f, 'rb').read()).hexdigest()
    expected = EXPECTED.get(f)
    if actual != expected:
        raise Exception(f"完整性校验失败：{f}\n期望: {expected}\n实际: {actual}")

print("[OK] 全部规范完整性校验通过")

校验失败 → fail-closed：拒绝执行核心流程，绝不静默继续。

规范文件使用方式（阶段2/3）

• 读取 references/performance-review-spec.md 全文作为设计依据（14 条固化标准、8 列表格结构、指标分类规则、评分原则、JSON Schema）；
• 读取 references/template.json 作为指标数据 JSON 结构参考；
• 复制 assets/generate_template.py 为当前工作目录临时脚本 generate.py（Python + openpyxl），构造 indicators.json 后执行。

所有规范引用为本地静态文件读取，SCF 不参与此过程。

SCF 仅下发不可执行的 JSON schema（可选 · 用于版本/价格核对）

如需核对 SCF 返回的 schema 与本地 manifest 是否一致（版本号、价格），可调用 get-config-schema：

tcb fn invoke ysc-jx-engine --params '{"action":"get-config-schema"}' -e "ysc-cloud-d8ge1wodk63983d9a" --json

SCF 返回的 schema 仅含价格、版本、状态机定义、TTL 等元数据，不包含任何代码或规范全文。

阶段2：设计指标数据（JSON）

阅读并严格遵循阶段1.6 校验通过的 references/performance-review-spec.md 规范全文。 执行要点：

1. 固化标准 14 条不可违背：权重指标 7-9 个、权重为 5% 整数倍且合计 100%、仅经营结果类指标可加 20 分、全部指标符合 SMART；
2. KPI（4-5项）：2 个经营结果（如营业收入/销量/毛利）+ 1-2 个过程效率指标；
3. 重点任务（3-4项）：聚焦"最容易出问题"的 3-4 个环节，进度+质量双维度评分；
4. 基础指标（8-11项）：含规章制度、企业文化行为规范、HSE事故数、差错整改完成率、工作责任心等，目标值用次数/违规数量化，评分按低梯度扣分（0.3-2分/次），严重问题（安全/泄密/造假）从重（10-20分/一票否决）；
5. 构造 indicators.json：严格按 references/performance-review-spec.md 第 5 节 JSON Schema + references/template.json 结构，中文全角标点；
6. 质量自检：权重合计=100%、权重指标数 7-9、每条评分标准含"得100分/扣分/上限"三要素。

阶段3：生成考核表 Excel

执行要点：
1. 复制 assets/generate_template.py 为工作目录临时脚本 generate.py；
2. 执行：

bash python3 generate.py --json indicators.json --output "{公司简称}-{岗位名称}月度绩效考核表.xlsx"

3. 用 openpyxl 复检产物（能正常 load_workbook、Sheet 名为"月度绩效考核表"、含 F 列数据验证 0-120）；
4. 输出文件：{公司简称}-{岗位名称}月度绩效考核表.xlsx，保存到当前工作目录；
5. 生成后必须展示：调用 present_files 展示生成的 .xlsx 文件；完成后删除临时 generate.py（保留或删除 indicators.json 均可）。

阶段4：服务台账（含订单号，便于对账）

完成后向当前工作目录的 YSC绩效_服务记录.csv 追加一行。文件不存在则先创建并写入表头：

日期,公司名称,岗位名称,所属部门,产出文件,订单号,skill_version,备注

• 日期格式：YYYY-MM-DD；产出文件列填生成的 xlsx 文件名；
• 订单号列（X402 必传）：填写阶段0.5.2 返回的 out_trade_no，便于与平台计费对账；
• 写入前先查重：若台账中已存在同订单号的记录，直接跳过写入（X402 幂等防重）；
• 台账仅记录上述必要字段，不写入任何敏感信息。

随后调用 SCF log-call 上报审计（仅传订单号/岗位/要素数量，不含指标明细）：

tcb fn invoke ysc-jx-engine --params '{
  "action": "log-call",
  "out_trade_no": "<订单号>",
  "industry": "<行业>",
  "position": "<岗位>",
  "item_count": <权重指标项数>
}' -e "ysc-cloud-d8ge1wodk63983d9a" --json

通用性保障

本技能适用于任意行业、规模、岗位，依赖以下设计：

1. 行业无关：调研步骤对任何行业生效；信息不足时回退到"岗位族群通识"（销售/技术/项目/职能四大类）；
2. 企业规模无关：上市公司到小微企业的处理路径一致，仅信息置信度不同（标注推断假设即可）；
3. 岗位类型无关：指标设计按岗位族群差异化（经营结果口径、重点任务环节不同）；
4. 职级无关：考核表面向岗位本身，不依赖职级框架；
5. 本地规范：所有核心资产随包分发，运行期用 SHA-256 完整性校验；SCF 不下发可执行内容。

注意事项

1. 规范不可更改：references/performance-review-spec.md 的 14 条固化标准是格式红线，只允许按岗位做情境化设计，不允许增删或调整；
2. 输出格式必须是 Excel（.xlsx）：使用 Python + openpyxl 生成，禁止以 Markdown 表格或其他文本格式交付；
3. 完整性校验优先：阶段1.6 必须先完成 SHA-256 校验（对比 assets/specs_hashes.txt），校验失败立即终止流程，禁止跳过校验或使用被篡改的规范；
4. X402 协议严守：本技能为基于 X402 协议的 Pay Skill，任何阶段都必须严格遵守 5 大必备改造项（前置检查 / 支付触发 / 重试机制 / 订单号传递 / 异常处理），禁止跳过任何一项；
5. fail-closed 原则：支付链路任何异常（配置缺失/预下单失败/支付超时/支付失败/履约异常）必须明确拒绝放行，禁止自动降级为免费服务或静默失败；
6. 订单号全链路传递：out_trade_no 必须从 0.5.2 获取 → 0.5.3 履约 → 阶段4 台账 全程传递，作为幂等键；
7. 付费优先：支付履约确认（fulfillment_granted:true）必须先于阶段1执行；未支付不得生成交付物；
8. 随包分发，无远程代码拉取：本 Skill 不包含任何远程云端拉取代码逻辑，所有规范来自本地 references/ 与 assets/ 目录；SCF 仅承担支付服务角色；发布者无法在包外注入或篡改运行期使用的核心代码/规范；
9. 密钥零持久化：任何密钥字符串不得写入文件、manifest 或 SKILL.md；签名全部在 SCF 服务端完成；
10. 指标设计要有区分度：避免所有指标评分标准雷同；定义必须具体（如"实际营业收入÷目标营业收入×100%，以财务入账为准"而非"完成业绩目标"）；
11. 权重指标总数与权重合法：7-9 个（≤12），权重为 5% 整数倍（5-45%），合计 100%；生成前自检，非法则修正后再生；
12. 诚实标注推断：凡属推断的信息（参考 JD、企业画像、行业假设）必须明确标注，不得伪装成事实；
13. 文件名使用中文，保存在当前工作目录；
14. 全部产出物生成后，调用 present_files 统一展示。

依赖环境

• Python 3.10+
• openpyxl（生成绩效考核表 Excel）

pip install openpyxl

文件清单

> 核心资产全部随 Skill 包一起分发，版本与 Skill 版本（v1.0.0）绑定，运行期通过 assets/specs_hashes.txt 执行 SHA-256 校验，确保规范未被篡改。本 Skill 不通过远程云端接口拉取任何代码或规范全文，SCF 仅作为 Pay Skill 必要的支付服务端。