e签宝电子签名技能

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

凭证配置

配置文件路径：~/.config/esign-contract/.env

ESIGN_APP_ID=your_app_id
ESIGN_APP_SECRET=your_app_secret
ESIGN_BASE_URL=base_url

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

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
   

2. 手动配置：登录 e签宝开放平台 获取凭证，手动编辑 ~/.config/esign-contract/.env

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

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

环境初始化

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

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

cd <SKILL目录> && (test -d scripts/.venv || python3 -m venv scripts/.venv) && scripts/.venv/bin/pip install -q -r scripts/requirements.txt

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

• macOS/Linux：scripts/.venv/bin/python3
• Windows：scripts/.venv/Scripts/python.exe

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

输出规范

• 脚本返回值、JSON 配置、执行命令等技术细节禁止展示给用户 — 包括但不限于：脚本路径、命令行参数、JSON 响应体、fileId、坐标值。用户只需看到进度提示和最终结果
• 内部流程名称（流程 A/B/C/D/E/F）、步骤编号不展示给用户
• 每执行一个实际操作前，给出对应的进度提示。只提示实际执行的步骤，不套用固定模板。可选提示：
  • 📋 正在提取签署人信息...（仅上传文件流程）
  • 📄 正在排版合同...（仅 AI 生成合同流程）
  • 📤 正在上传...
  • 🔍 正在定位签章位置...
  • ✍️ 正在创建签署流程...
• 最终输出（签署流程发起成功）：

  ✅ 签署流程已发起 — 合同名称
  
  ---
  
  **甲方** 姓名（手机号）
  🔗 签署链接
  
  ---
  
  **乙方** 姓名（手机号）
  🔗 签署链接
  
  ---
  
  ⏳ 请将对应链接发送给签署方，点击即可完成签署
  

• 查询流程输出：

  📋 签署进度 — 合同名称
  
  状态：● 签署中　　创建时间：2026年3月27日 14:30
  
  **甲方** 姓名　✅已签署
  **乙方** 姓名　⏳待签署
  

• 撤销流程输出：

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

• 下载文件输出：

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

• 出错时参考 references/error-handling.md
• 多步骤用 && 串联，减少交互轮次

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

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

   用户确认合同内容时须确保所有字段已填充，不可带空字段进入排版

2. 排版生成 PDF：run.py format <实际md路径> <对应pdf路径>
   • 失败时检查 Markdown 是否含非法字符、字体是否缺失；告知用户错误原因并停止
3. 参考 references/signing-guide.md 执行签署（上传实际生成的 PDF → 定位签章 → 发起流程 → 获取链接）
   • 上传失败：提示网络或凭证问题，建议检查 ~/.config/esign-contract/.env 配置
   • 签章定位失败：提示关键字未找到，请用户确认合同中签章关键字
   • 发起流程失败：展示错误码，参考 references/error-handling.md

流程 B：上传文件 → 签署

1. 提取文本：run.py extract_text text "<文件路径>"，识别签署方信息和签章关键字
   • 失败时检查文件格式是否为 PDF/Word，或文件路径是否正确
2. 展示签署方信息让用户确认，缺失必填项要求补充
3. 参考 references/signing-guide.md 执行签署（上传 → 关键字定位 → 发起流程 → 获取链接）
   • 上传失败：提示网络或凭证问题，建议检查 ~/.config/esign-contract/.env 配置
   • 签章定位失败：提示关键字未找到，请用户确认文件中签章关键字
   • 发起流程失败：展示错误码，参考 references/error-handling.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 格式，便于解析
• ~/.config/esign-contract/.env 中的凭证切勿泄露或提交到代码仓库