Skills - 自建应用
一.项目说明
本项目是基于 Claude Skills 的腾讯电子签（ESS）企业端 API 技能插件，通过 AI 对话即可调用腾讯电子签企业端 API，实现合同创建、签署、管理等全流程操作。
通过 CodeBuddy Skills，您可以在支持 Skills 协议的 AI 客户端中，用自然语言完成电子签的各项操作。
二.环境要求
- Python 3.x 或更高版本
- CodeBuddy IDE（或其他支持 Skills 的 AI 客户端）
三.下载与安装
在您使用的 AI 工具的 Skills 放置目录下，执行以下命令克隆项目即可完成安装：
git clone https://github.com/tencentess/ess_company_skills
不同 AI 工具的 Skills 目录位置可能不同，请参考对应工具的文档确认 Skills 存放路径。以 CodeBuddy 为例，Skills 默认存放在项目根目录的 .codebuddy/skills/ 下：
cd .codebuddy/skills/
git clone https://github.com/tencentess/ess_company_skills
克隆完成后，重启 AI 客户端（或重新加载 Skills 列表）即可使用。
四.配置说明
凭证按以下优先级加载：配置文件 > 环境变量（配置文件中已有的字段优先使用，缺失的字段从环境变量补充）。
1.方式一：配置文件（推荐）
创建 ~/.tsign/config.yaml：
# ~/.tsign/config.yaml
# 腾讯云 API 凭证（必需）
credentials:
secret_id: "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
secret_key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
# 默认经办人（可选，配置后无需每次手动传入）
operator:
user_id: "yDwFxxxxxxxxxxxxxxxx"
# 环境: test（测试）/ online（正式）
env: "online"
安全提示：建议将配置文件权限设置为仅本人可读写（Linux/macOS:
chmod 600 ~/.tsign/config.yaml）。可通过环境变量
TSIGN_CONFIG_PATH自定义配置文件路径，例如export TSIGN_CONFIG_PATH=/path/to/my-config.yaml。
2.方式二：环境变量
若配置文件中缺少某些字段，会自动从环境变量中补充读取。
必需（配置文件中未设置时）：
| 环境变量 | 说明 |
|---|---|
ESS_SECRET_ID | 腾讯云 SecretId |
ESS_SECRET_KEY | 腾讯云 SecretKey |
ESS_ENV | 环境，可选值：test（测试）/ online（正式） |
可选：
| 环境变量 | 说明 |
|---|---|
ESS_USER_ID | 默认操作人 UserId，配置后自动注入到 Operator.UserId，无需每次手动传入 |
TSIGN_CONFIG_PATH | 自定义配置文件路径（默认 ~/.tsign/config.yaml） |
3.设置方式
macOS / Linux (bash/zsh)：
export ESS_SECRET_ID="AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ESS_SECRET_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ESS_ENV="online"
export ESS_USER_ID="yDwFxxxxxxxxxxxxxxxx" # 可选
Windows (PowerShell)：
$env:ESS_SECRET_ID = "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:ESS_SECRET_KEY = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:ESS_ENV = "online"
$env:ESS_USER_ID = "yDwFxxxxxxxxxxxxxxxx" # 可选
4.凭证获取
可以参考获取密钥 SecretId 和 SecretKey（联调环境）获取 SecretId 和 SecretKey。
| 凭证 | 获取方式 |
|---|---|
| SecretId / SecretKey | 前往 腾讯云 API 密钥管理 创建或查看 |
| UserId（经办人编号） | 前往 腾讯电子签控制台 获取，参考 经办人 UserId 获取说明 |
五.功能列表
| 功能 | 说明 |
|---|---|
| 用文件创建合同 | 上传 PDF 文件直接创建签署流程（非制式合同）。如果上传的文件非 PDF 格式，需要先通过「文件转换为PDF」功能将文件转换为 PDF 并获取到 PDF 的资源 ID，再用该资源 ID 创建合同 |
| 用模板创建合同 | 使用企业预制模板创建签署流程（标准制式合同），只需填充动态内容 |
| 用文件创建合同组 | 通过上传多个 PDF 文件创建合同组签署流程，签署方通过一个链接签署组内所有合同 |
| 用模板创建合同组 | 使用多个企业预制模板创建合同组签署流程，签署方通过一个链接签署组内所有合同 |
| 文件转换为PDF | 将上传的非 PDF 文件（Word、Excel、图片等）转换为 PDF 格式，以便用于合同发起 |
| 生成合同签署链接 | 生成跳转至腾讯电子签小程序的签署链接，支持单个或多个签署方 |
| 生成合同H5签署链接 | 生成 H5 页面的签署链接，可在 APP 或浏览器中直接打开签署 |
| 查询合同详情与填写控件 | 查询合同或合同组的详细信息（状态、签署方、进度等）及填写控件的填充内容 |
| 下载合同文件 | 获取签署完成后的合同 PDF 下载链接，支持 PDF、JPG、ZIP 格式 |
| 撤销合同 | 撤销尚未全部签署完成的合同流程 |
| 发起解除协议 | 对已签署完成的合同发起解除协议 |
| 生成合同组签署链接 | 为合同组生成小程序签署链接，签署方通过一个链接签署组内所有合同 |
| 生成合同组H5签署链接 | 为合同组生成 H5 签署链接，签署方在 APP 或浏览器中批量签署 |
| 企业电子印章管理 | 管理企业电子印章的完整生命周期，包括创建印章、启停用印章、授权员工使用印章和解除授权 |
| 企业员工管理 | 管理企业员工的查询、新增和离职 |
| 企业角色管理 | 管理企业角色的查询、创建、更新，以及员工角色的绑定和解绑 |
| 企业部门管理 | 管理企业部门的查询、创建、更新和删除，支持树形部门结构 |
| 企业计费使用情况查询 | 查询企业的套餐使用情况和套餐消耗详情 |
| 企业回调管理 | 配置和管理企业的回调通知地址，用于接收合同签署状态变更等事件通知 |
| 企业扩展服务管理 | 管理企业扩展服务的查询、开通/关闭、授权和取消授权 |
| 企业自动签署 | 发起合同时由腾讯电子签自动完成本企业或合作方企业的盖章操作，适用于大批量标准化合同 |
| 个人自动签署管理 | 管理个人用户自动签署功能，包括查询开通状态、获取开通链接、关闭自动签、设置印章和获取认证证书 |
| 出证报告 | 申请合同出证报告并查询执行结果，支持签署报告和公证处核验报告 |
| 流程文件验签 | 对已签署的合同文件进行数字签名验证，检测文件是否被篡改 |
| PC浏览器嵌入页面 | 在 PC 浏览器中嵌入电子签页面，包括主题配置、发起流程、签署合同、合同详情等 |
| 一码多签管理 | 创建和管理一码多签签署码，通过二维码批量发起合同签署 |
| 合同智能审查 | 上传合同文件后发起 AI 智能审查，识别合同风险点并生成审查报告 |
| 合同智能对比 | 上传两份合同文件进行智能对比，识别条款差异并生成对比报告 |
| 合同智能原子操作 | 合同智能审查与对比的底层原子接口，提供审查和对比全流程的详细接口说明 |
| 动态签署人 | 合同发起时预留签署方坑位，后续通过接口补充签署人信息 |
| 动态签署人2.0 | 签署过程中可灵活追加签署方和签署区域，合同需调用结束接口完成 |
| 集团企业管理 | 管理集团组织中的成员企业，主企业可代子企业操作各类资源 |
六.使用示例
示例 1：上传文件并创建合同
在 AI 客户端中用自然语言提问：
帮我上传一个文件，文件地址是/data/合同.PDF
AI 将自动调用上传接口完成文件上传，并返回文件资源 ID（FileId），用于后续创建合同。
示例 2：通过文件创建签署流程
帮我用 PDF 文件创建一个签署流程，合同名称为测试合同，使用已上传的文件资源 ID yD3a1UUqi3mg89USyGa1wheheFqA8MR8，签署方是张三（手机号 18500000000），让他在'乙方（买方）签字'位置签个名字
AI 将自动编排参数并调用接口完成合同发起，通过关键字定位方式将签名控件放置到 PDF 中指定位置。
示例 3：通过模板创建签署流程
帮我查询一下企业模板列表，找一个采购合同模板，用模板发起一份合同，签署方是李四（手机号 13800000000）
AI 将先查询模板列表，选择合适的模板后自动填充参数并创建合同。
示例 4：生成签署链接
帮我生成合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 中刘波的小程序签署链接
AI 将调用接口生成跳转至腾讯电子签小程序的签署短链接和二维码，签署人可通过手机浏览器打开或扫码签署。
示例 5：查询合同详情
帮我查询合同流程 ID 为 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 的详细信息
AI 将自动调用接口查询合同的详细信息，包括合同状态、签署方信息、签署进度等。
示例 6：下载合同文件
帮我下载合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 的签署完成文件
AI 将调用接口获取签署完成的合同 PDF 下载链接，支持 PDF、JPG、ZIP 格式。
示例 7：撤销合同
帮我撤销合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe，撤销原因是合同内容有误
AI 将调用接口撤销尚未全部签署完成的合同流程。
示例 8：生成出证报告
帮我为合同 yD3a1UUqivpvhwUEnTiJbSKhT6DjmbLe 申请出证报告
AI 将调用接口提交出证报告申请任务，返回报告 ID。之后可查询报告生成状态和下载链接。
七.注意事项
1. 凭证安全
请妥善保管 SecretId 和 SecretKey，不要在代码仓库或公开渠道中明文存储。建议使用配置文件方式，并设置文件权限为仅本人可读写。
2. 环境区分
test（联调环境）：用于开发测试，不消耗正式套餐额度online（正式环境）：用于生产环境，操作真实合同数据