esign-contract

e签宝电子签名技能 — 支持 AI 生成任意类型的合同/协议并排版为 PDF， 上传已有文件发起电子签署，返回签署链接。 触发场景：用户要求生成、起草、撰写任何类型的合同或协议（如"写个借款合同"、 "帮我拟一份保密协议"、"起草租赁合同"），或要求对已有合同文件发起签署、 查询签署进度、撤销签署、下载签署文件、...

Security Scan

The skill largely does what its name describes (generate/format/upload contracts and call eSign APIs) but has several inconsistencies around credential handling and runtime instructions that warrant caution before installing or running it.

Purpose & Capability

The code and SKILL.md implement e-signature lifecycle (contract generation, PDF formatting, upload, signature flow management) and match the skill name and description. However the skill metadata only declares ESIGN_APP_ID as the primary credential while the code and instructions require ESIGN_APP_SECRET (and optionally ESIGN_BASE_URL). This mismatch between declared requirements and actual needs is an incoherence.

Instruction Scope

Runtime instructions direct the agent to collect and write credentials to ~/.config/esign-contract/.env and to create/modify files in the user home (token_cache.json, fonts, venv). The references also instruct the agent to auto-edit project settings.json to add allowedTools for 'Claude Code' (i.e., modify other agent/project config). The SKILL.md also instructs the agent to request credentials interactively in chat and to write them using Bash heredoc—both expand the agent's scope to handling sensitive secrets and modifying unrelated project settings, which is beyond the core purpose of formatting/uploading contracts.

Install Mechanism

No remote download/install spec in skill registry, but SKILL.md requires creating a Python virtualenv and installing requirements (weasyprint, pdfplumber, python-docx, etc.). These are normal but weasyprint requires native libraries (pango/cairo) and the requirements include pytest (odd for runtime). No arbitrary external URLs or extract-from-URL installs were found.

Credentials

The skill's runtime and code require ESIGN_APP_ID and ESIGN_APP_SECRET (and may use ESIGN_BASE_URL), but only ESIGN_APP_ID is declared as the primary credential and requires.env is empty. The SKILL.md instructs asking the user to paste secrets into chat (format 'appId;appSecret') and then writes them to disk—this risks secret exposure in chat history and gives the agent access to credentials beyond what the registry metadata advertises. The skill will also create and cache tokens in the user's config directory (token_cache.json).

Persistence & Privilege

The skill will create persistent files in the user's home (~/.config/esign-contract/.env, token_cache.json, fonts, and a scripts/.venv inside the skill directory). More concerning: the signing guide instructs automatically modifying project settings.json to add allowedTools for Claude Code (i.e., altering other agent/project configuration). Modification of other projects' settings is out-of-scope for a signing helper and is a notable privilege escalation.

What to consider before installing

What to consider before installing or running this skill: - Credentials: The code requires both ESIGN_APP_ID and ESIGN_APP_SECRET (and may use ESIGN_BASE_URL), but the registry only lists ESIGN_APP_ID. Do not paste secrets into chat unless you trust the skill and agent environment. Prefer to manually create ~/.config/esign-contract/.env and populate ESIGN_APP_ID and ESIGN_APP_SECRET yourself. - Files written to your system: The skill creates ~/.config/esign-contract/, token_cache.json, may store fonts there, and creates a Python venv under scripts/.venv and installs packages. Expect native system libraries to be required for weasyprint (Pango/Cairo). - Project config modification: The signing guide includes an instruction to auto-edit ~/.claude/projects/.../settings.json to add allowedTools. This modifies other agent/project settings and is out-of-scope for an e-sign helper — decline or review that step and perform it manually if you understand the ramifications. - Sensitive prompts & chat history: SKILL.md suggests asking users to provide credentials in chat. This can expose secrets in chat logs. If you must provide credentials, use secure out-of-band methods (manual file creation, environment variables in an isolated environment) rather than chat. - Review the code: If you plan to use the skill, inspect the included Python scripts (esign_api.py, format_contract.py, extract_text.py) yourself. Confirm endpoints (they appear to target eSign's documented endpoints), and verify there are no hidden external endpoints. - Run in isolation: Consider running this skill in a sandboxed account or VM, and create the .env manually. Deny any automatic modification of other projects' settings and do not allow the agent to auto-write secrets. If you want, I can: list the exact lines that reference ESIGN_APP_SECRET and the settings.json modification, or provide step-by-step safe setup instructions (how to create the .env, create venv, and run a single command) so you don't have to give secrets in chat.

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 中的凭证切勿泄露或提交到代码仓库