e签宝电子签名技能

编排型 Skill：本 Skill 统一编排 e签宝电子合同的完整生命周期，涵盖合同生成、文件上传、签署发起、进度查询、撤销、下载及验签六个子流程（流程 A–F）。Agent 根据用户意图选择对应流程执行，各流程间可按需串联。

凭证配置

配置文件路径：INLINECODE0

CODEBLOCK0

凭证预检（必须在首次调用 API 前执行）：调用任何 e签宝 API 之前，先检查 ~/.config/esign-contract/.env 是否存在且包含 ESIGN_APP_ID。若文件不存在或缺少必要字段，提示用户两种方式：

1. 1. 直接输入（推荐）：请用户在对话中提供 App ID 和 App Secret（格式如 appId;appSecret），由 Agent 用 Bash 自动写入配置文件，默认使用正式环境：

   mkdir -p ~/.config/esign-contract && cat > ~/.config/esign-contract/.env << 'EOF'
   ESIGN_APP_ID=用户提供的appId
   ESIGN_APP_SECRET=用户提供的appSecret
   ESIGN_BASE_URL=https://openapi.esign.cn
   EOF
   

1. 2. 手动配置：登录 e签宝开放平台 获取凭证，手动编辑 INLINECODE4

环境策略：默认使用正式环境（https://openapi.esign.cn）。若 API 调用返回认证错误或连接失败，询问用户是否为沙箱环境，是则将 ESIGN_BASE_URL 改为 INLINECODE7

凭证文件存放于用户主目录，不随 Skill 目录变动，不会被意外提交到代码仓库。

环境初始化

脚本位于 SKILL.md 所在目录的 scripts/ 子目录下，执行时使用脚本的完整绝对路径。

首次执行任何脚本前，必须先确保虚拟环境就绪（一条命令完成检查与初始化）：
CODEBLOCK2

Python 解释器：始终使用虚拟环境解释器：

• - macOS/Linux：INLINECODE9
• Windows：INLINECODE10

中文 PDF 显示异常时安装 Noto CJK 字体，或放入 ~/.config/esign-contract/（相对 SKILL.md 目录）。

输出规范

• - 脚本返回值、JSON 配置、执行命令等技术细节禁止展示给用户 — 包括但不限于：脚本路径、命令行参数、JSON 响应体、fileId、坐标值。用户只需看到进度提示和最终结果
• 内部流程名称（流程 A/B/C/D/E/F）、步骤编号不展示给用户
• 每执行一个实际操作前，给出对应的进度提示。只提示实际执行的步骤，不套用固定模板。可选提示：

• - 最终输出（签署流程发起成功）：

  ✅ 签署流程已发起 — 合同名称

  ---

  **甲方** 姓名（手机号）
  🔗 签署链接

  ---

  **乙方** 姓名（手机号）
  🔗 签署链接

  ---

  ⏳ 请将对应链接发送给签署方，点击即可完成签署
  

• - 查询流程输出：

  📋 签署进度 — 合同名称

  状态：● 签署中　　创建时间：2026年3月27日 14:30

  **甲方** 姓名　✅已签署
  **乙方** 姓名　⏳待签署
  

• - 撤销流程输出：

  ⚠️ 签署流程已撤销 — 合同名称
  

• - 下载文件输出：

  📥 签署文件已下载 — 合同名称
  📂 保存路径
  

• - 出错时参考 INLINECODE17
• 多步骤用 && 串联，减少交互轮次

流程 A：AI 生成合同 → 签署

1. 1. 参考 references/contract-generation.md 收集信息并生成合同，记住实际写入的文件路径（写入系统临时目录，如 /tmp/contract.md（macOS/Linux）或 %TEMP%\contract.md（Windows），可能追加序号）

1. 2. 排版生成 PDF：INLINECODE22

1. 3. 参考 references/signing-guide.md 执行签署（上传实际生成的 PDF → 定位签章 → 发起流程 → 获取链接）

流程 B：上传文件 → 签署

1. 1. 提取文本：run.py extract_text text "<文件路径>"，识别签署方信息和签章关键字

1. 2. 展示签署方信息让用户确认，缺失必填项要求补充
2. 参考 references/signing-guide.md 执行签署（上传 → 关键字定位 → 发起流程 → 获取链接）

签署主体判断规则详见 references/signing-guide.md。

流程 C：查询签署进度

不知道 flowId 时先执行 run.py list_flows，再执行 run.py query_flow "<signFlowId>"。展示：流程状态、各签署方状态、创建时间。

签署方信息补全：API 返回的签署方姓名可能为空（如沙箱环境未注册的手机号）。展示前先用 run.py list_flows 读取本地 flow_history.json，按手机号匹配补全姓名和角色。

• - 查询失败：提示 flowId 不存在或无权限，建议用户确认流程 ID 是否正确。

流程 D：撤销签署流程

⚠️ 不可逆操作，必须用户确认。

确认后：run.py revoke_flow "<signFlowId>" "撤销原因"

• - 失败时检查流程是否已完成或已撤销（已终态不可再撤销），展示错误码并告知用户。

流程 E：下载签署完成文件

前提：流程状态为已完成。run.py download_docs "<signFlowId>"（不传输出目录时自动使用系统临时目录）

• - 失败时检查流程是否尚未完成，或下载路径是否有写权限；提示用户实际原因。

流程 F：验证电子签名

参考 references/signing-guide.md 中的验签步骤。两种方式：提供本地 PDF 文件路径，或指定签署流程获取 fileId。

• - 失败时检查文件是否为有效 PDF、flowId 是否存在；若证书过期或签名无效，如实展示结果，不做额外推断。

展示格式：

🔍 电子签名验证结果 — 合同名称

📄 文件完整性：✅ 未被篡改 / ❌ 已被修改

签署人：
  1. 名称 — ✅ 签名有效 / ❌ 签名无效
     证书：xxx | 签署时间：xxxx年xx月xx日 xx:xx

> 总结性结论

注意事项

• - 发起签署和撤销签署是不可逆操作，必须用户确认
• 所有脚本输出 JSON 格式，便于解析
• INLINECODE38 中的凭证切勿泄露或提交到代码仓库