连珠｜把五道工序串成开发闭环的 Skill

概述

连珠

你可以直接这样说

• 我有一个 Skill 点子，帮我一路做到能发布。
• 这个 Skill 做到一半卡住了，不知道下一步。
• 把机会、体验、验收、打磨和反馈串成一个流程。

当前版本：v1.2.10。

版权与许可：Source-Available，不是开源软件。

Copyright © 2026 相光域 / CHROMATIC。保留所有权利。允许查看源码、下载未修改副本、在私有环境运行并提交审核意见；未经书面授权，不得复制传播、再发布、转授权、销售、商业使用、公开部署，或制作并分发衍生版本。完整条款见本包 [LICENSE](LICENSE)。

连珠现在连接完整主链：

泉眼（水）→ 榫卯（木）→ 淬炉（火）→ 沙盘（土）→ 铎声（金）→ 泉眼（水）

铜镜仍是链外独立体检工具；日晷等产品是链的产物，不是环节。

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

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

免责声明与数据来源

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

为什么分成 prepare 与 cycle

泉眼把方向交给榫卯后，目标 Skill 必须真正实现。这个实现过程不能由编排器伪装成已经完成，所以连珠保留一个明确停点：

1. prepare：水→木，生成路线简报和可编辑验收标准。
2. 实现目标 Skill，补齐真实命令与负向路径。
3. cycle：木验收→火门→发布→土模拟→金入口；可选继续自动检索和十秒监测。公开证据形成后，检查点停在 awaiting_user，不替用户选择改什么。
4. resume：从原子检查点继续，已经完成且哈希未变的阶段不会重跑。
5. rerun：从指定阶段重新运行，并自动作废全部下游阶段；上游哈希稳定的证据继续保留。
6. return-water：用户从金阶段排序队列明确选择证据后，验证来源并生成水种，再由泉眼校验接收，真正闭合金→水。

这两条命令共同打通全链，同时保留无法自动越过的实现责任。

独立运行与内部能力

连珠发布包已经内置五阶段运行时：

• prepare 内部运行泉眼与榫卯阶段能力；
• release 内部运行榫卯与淬炉阶段能力；
• experience 内部运行沙盘与铎声阶段能力；
• cycle 依次运行木、火、土、金并保留检查点。

用户只安装或购买连珠即可运行完整主链，不需要再安装五个兄弟 Skill。内置运行时位于 runtime/<stage>/，不带独立 SKILL.md，不会向 Agent 注册为五个额外 Skill，也不等于发放五个高级 Skill 的独立调用权益。

开发者只有在做兼容回归时才可显式设置 LIANZHU_STAGE_RUNTIME=external，改用 ${CODEX_HOME}/skills/<skill>/scripts/；默认始终使用包内运行时，缺失即报错，不静默降级。

完整用法

CHAIN="${CODEX_HOME:-$HOME/.codex}/skills/lianzhu/scripts/lianzhu.py"
TARGET=/absolute/path/to/my-skill
WORK=/absolute/path/to/development-records

# 水→木：用户已在泉眼选择路线。
python "$CHAIN" prepare 
  --route-map /absolute/path/to/quanyan-map.json 
  --source-checks /absolute/path/to/quanyan-source-checks.json 
  --route chosen-route 
  --target-skill "$TARGET" 
  --work-dir "$WORK"

# 此处真正实现目标 Skill，并把 sunmao-acceptance.json 的占位命令替换为真实场景。

# 木→火→发布→土→金入口。
python "$CHAIN" cycle 
  --target-skill "${TARGET}" 
  --acceptance-standard "$TARGET/sunmao-acceptance.json" 
  --review-dir "$WORK/review" 
  --out-dir "$WORK/release" 
  --archive-name my-skill.zip 
  --experience-dir "$WORK/soil" 
  --metal-dir "$WORK/metal" 
  --auto-search 
  --search-provider github 
  --search-provider stackexchange 
  --search-provider crossref 
  --watch-cycles 6 
  --watch-interval 10

# 中断后继续；已完成阶段会核验哈希后跳过。
python "$CHAIN" resume 
  --checkpoint "$WORK/review/lianzhu-cycle-checkpoint.json"

# 只重跑土阶段及其下游；木火发布证据保持不动。
python "$CHAIN" rerun 
  --checkpoint "$WORK/review/lianzhu-cycle-checkpoint.json" 
  --from-stage experience 
  --reason "补充移动端体验场景"

# 查看金阶段排序计划后，由用户明确选择证据，再闭合金→水。
python "$CHAIN" return-water 
  --checkpoint "$WORK/review/lianzhu-cycle-checkpoint.json" 
  --selected-id feedback-001 
  --reason "用户确认优先解决首次使用路径"

# 查看当前实际使用的五阶段运行时；默认全部来自连珠包内部。
python "$CHAIN" runtime-status

已有发布 ZIP 时，可改用 experience，提供目标目录、发布 ZIP、验收标准、土输出目录和金输出目录，不重复运行榫卯发布与淬炉。

阶段交接件

1. quanyan-route-brief.json：用户确认的路线与来源边界。
2. sunmao-acceptance.json：目标能力、正常场景、失败场景和发布要求。
3. cuilu-fire-gate.json：绑定源快照的发布前质量门。
4. 发布 ZIP 与 RELEASE_MANIFEST.json：土阶段唯一允许体验的精确产物。
5. shapan-experience-report.json：真实执行痕迹和规则推断，证据类型固定为模拟。
6. shapan-soil-handoff.json：绑定沙盘报告哈希的土→金信号。
7. jing-search-brief.json：铎声准备搜索真实反馈与技术资料的金阶段入口。
8. jing-public-results.json 与 jing-evidence-ledger.json：可选自动检索后的标准化结果和来源台账。
9. jing-watch-checkpoint.json：每十秒评估全部已选 provider 状态的断点；真正的外部请求仍遵守各 provider 最小间隔和退避。
10. jing-refinement-plan.json、jing-user-selection.json、jing-water-seeds.json：排序队列、用户选择和来源检查绑定的金→水种子。
11. quanyan-water-intake.json：泉眼对回流水种的实际校验与接收记录。
12. lianzhu-cycle-checkpoint.json：每阶段状态、尝试次数、定向重跑历史、产物路径和 SHA-256；使用临时文件加原子替换写入。

强制规则

• prepare 必须使用与路线图哈希匹配的泉眼来源检查报告。
• 榫卯验收报告与淬炉火门必须写在目标目录之外，避免改变被核验源快照。
• 任一目标文件变化都会让旧火门失效，必须重新运行 cycle。
• 沙盘只运行发布 ZIP；发布清单不匹配或 ZIP 不安全时阻断。
• 连珠只应把自己构建或已经人工审查的发布包交给沙盘；临时 HOME 不是恶意代码安全沙箱。
• 沙盘发现产品 P0 时仍完成报告并交给铎声；基础设施、规格或包完整性错误才阻断链。
• 铎声只能把沙盘信号变成搜索假设，不能改写成网上评论。
• cycle --auto-search 才会访问所选公开 provider；默认不产生网络请求。
• --watch-interval 固定为十秒。十秒是状态刷新节拍，不表示每十秒强行请求第三方 API；速率限制和退避优先。
• resume 会校验验收标准、目标快照和发布 ZIP 哈希；检测到漂移就要求新开一次 cycle。
• rerun 只允许从 release、experience、public_search 或 watch 开始；指定阶段以及所有下游证据一起失效，上游证据必须先通过哈希复核。
• 金→水不能自动替用户做产品决定。return-water 必须提供一个或多个排序队列里的 --selected-id 以及明确理由；来源检查、选择件和水种的哈希全部进入检查点。
• 由连珠执行器捕获并报告的链路阻断统一输出稳定的 error_code；参数解析器自身的用法错误仍沿用 argparse 标准格式。运行 error-codes 可读取机器可判定的错误码表。

失败、异常与降级

• 任一阶段启动前写入 running，异常时写入 failed 和错误信息；进程中断后使用 resume，不靠人工猜测跑到了哪一步。
• 验收标准、目标快照或发布 ZIP 哈希漂移时阻断恢复，必须新开 cycle。
• 铎声检索正常执行但公开证据不足时标为 partial，保留结果和限制，不伪造数据补成 completed。
• provider 触发配额或退避时，十秒 tick 继续刷新本地状态，但网络请求延后；不以高频重试绕过第三方规则。
• 内置阶段运行时缺失时明确失败，不会静默改用外部 Skill；只有显式设置 LIANZHU_STAGE_RUNTIME=external 才测试外部安装版本。
• 定向重跑不会靠人工删除检查点。每次作废都会保留原状态、时间、理由和累计尝试次数。

数据来源与免责声明

全链证据来自泉眼路线与来源检查、榫卯验收命令、淬炉源快照门、发布清单、沙盘执行矩阵和铎声土交接验证。每个交接件都必须保留路径、哈希、证据类型和限制。

全链运行通过只证明这些自动化步骤对声明的文件和场景运行过。它不证明外部来源真实、产品正确、安全合规、真人满意、无障碍合规、市场需求或商业结果。沙盘是模拟体验，真实用户证据仍应由铎声在公开来源和后续研究中独立收集。

不确定性与限制

• 目标实现是否满足真实业务需求，无法由编排顺序证明。
• 沙盘用户透镜是规则化测试角度，不是人口抽样或真人行为模型。
• 沙盘会从多人格透镜、正常与负向场景评估精确发布包，但探索空间仍受验收标准和体验规格约束；它不是能够发现所有未知路径的真人探索测试。
• 铎声金阶段入口只准备搜索，不保证互联网存在足够、可信或有代表性的反馈；当前自动 provider 偏公开技术与研究来源，未直接覆盖需要登录或受平台限制的国内内容渠道。
• 自动检索可能因为配额、网络、索引缺失或没有结果而处于 partial；partial 不是伪造证据的理由。
• 运行环境、权限、网络和未声明依赖变化可能使另一台机器得到不同结果。

完整字段和阻断关系见 [chain-protocol.md](references/chain-protocol.md)。

付费前置检查

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

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

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

工作流程

第一步：请求资源

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

POST https://pay.tancoai.com/api/skillhub/pay/lianzhu-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/lianzhu-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/lianzhu-payskill Skill ID：lianzhu-payskill Skill Version：1.2.9计费模式：前 5 次完整任务免费；第 6 次起按次调用，4.99 元 / 次平台 Product ID：SP2608192S3D 支付协议：微信 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。暂时失败时保留订单号并重试原请求，不得重复下单。