前言¶
采购、外包、供应商协议一旦签完，真正费精力的是履约：付款节点、交付截止、合同到期日分散在 PDF 里，日历和表格往往对不上。人工抄条款容易漏字段，临近节点才想起来核对也常见。
Contract Tracker Pro 是 SkillHub 上的 community Skill（business-ops），把「上传合同 → 抽取节点 → 本地台账 → 飞书提醒」串成一条可复用流程。下面介绍它做什么、怎么装、以及和 Agent 配合时的注意点。
这是什么¶
一句话定位： 上传合同 PDF（或粘贴文本），用你自配的 OpenAI 兼容模型抽取付款、交期、到期等节点，写入本地 JSON 台账，并按规则向飞书推送提醒。
- 坐标：
@user_26bdbd50/contract-tracker-pro - 版本： 1.0.0（SkillHub 页面与 CLI 检索一致）
- 发布者：
user_26bdbd50，来源为 community - 标签：
requires_api_key=true（需配置 Token 与 AI API Key）
SkillHub 统计（页面元数据）：评分 100000，下载 893，安装 0。
核心功能¶
以下能力来自技能包内的 SKILL.md / README.md，安装后可对照核对。
-
输入
- PDF 上传：全文解析后由 AI 抽字段
- 文本输入：粘贴关键条款，可人工补全
- 历史记录：查询已有合同、标记节点完成 -
抽取字段（AI）
合同名称/编号、签署日期、付款节点、交期或交付节点、合同到期日、违约金条款等；README 还列出验收节点、质保节点（如有）。 -
履约台账
本地 JSON（默认contract_ledger.json，可用环境变量CONTRACT_TRACKER_LEDGER改路径）；较高套餐支持导出 CSV。 -
状态
待执行（未到截止日）、已完成（手动标记）、已逾期（过截止未完成）。 -
飞书提醒规则
- 截止日前 3 天
- 截止日当天
- 逾期后每天，直到标记完成 -
Token 与套餐
调用POST https://api.yk-global.com/v1/verify，Authorization: Bearer {api_key}，请求体{}，以响应中的valid判断；验证结果本地缓存 5 分钟。网络错误时降级为 Free 档，不阻断使用。
套餐档位（技能文档记载）：Free（3 合同/月）、Standard（¥29/月，20 合同）、Pro（¥99/月，100 合同）、Max（¥299/月，不限量）；具体权益以文档表格为准。 -
技术边界
Python 3.8+；PDF 依赖pdfplumber或PyPDF2；AI 不绑定厂商，需自行提供ai_api_key与可选ai_base_url、ai_model（默认示例为gpt-4o-mini）。
安装与启用¶
SkillHub 官方页面给出的方式是：让 Agent 按 SkillHub 安装说明 安装 @user_26bdbd50/contract-tracker-pro。
若本机已有 skillhub CLI，可先确认版本，再装到当前 Agent 的 skills 目录（未指定 --dir 时默认 ./skills/，Agent 可能识别不到）：
command -v skillhub && skillhub --version
skillhub install contract-tracker-pro --namespace user_26bdbd50 --dir ~/.cursor/skills/
常见路径（摘自 SkillHub 安装文档，按你实际使用的客户端选择）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或项目下的.agents/skills/
未安装 CLI 时，安装文档提供一键脚本（需联网）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
安装技能包后，按 README 安装 Python 依赖（例如 pdfplumber>=0.10.0 或 PyPDF2>=3.0.0）。
配置项（使用前准备）：
| 参数 | 说明 |
|---|---|
api_key |
Token，格式 CONT-TRACK-* |
ai_api_key |
OpenAI 兼容模型的 API Key |
ai_base_url |
模型 API 地址（可选） |
ai_model |
模型名（可选，示例默认 gpt-4o-mini） |
feishu_webhook |
飞书机器人 Webhook（可选，用于推送） |
典型用法¶
技能包 scripts/main.py 提供可直接调用的入口。在技能目录下、依赖已安装的前提下，可按 README 示例操作。
从 PDF 添加合同：
from scripts.main import add_contract_from_pdf
result = add_contract_from_pdf(
pdf_path="/path/to/contract.pdf",
api_key="CONT-TRACK-xxxxx",
ai_api_key="sk-xxxxx",
ai_base_url="https://api.openai.com/v1",
ai_model="gpt-4o-mini",
)
if result["success"]:
contract = result["contract"]
print(f"合同已添加：{contract['name']}，共 {len(contract['nodes'])} 个节点")
检查并生成提醒（可配合飞书发送）：
from scripts.main import check_and_notify
result = check_and_notify(
api_key="CONT-TRACK-xxxxx",
contract_id=None,
)
for n in result["notifications"]:
print(n["card"]["header"]["title"]["content"])
标记节点完成、导出台账：
from scripts.main import mark_node_done, export_contracts
mark_node_done(contract_id="abc12345", node_id="node-1")
export_result = export_contracts(api_key="CONT-TRACK-xxxxx", format="csv")
print(export_result["data"])
在 Cursor 等 Agent 场景中，更常见的做法是把 SKILL.md 作为技能说明交给模型：用户上传 PDF 或粘贴条款，由 Agent 按技能流程调用上述脚本或等价步骤，而不是手写台账。
台账 JSON 结构示例（字段含义见 SKILL.md）：
{
"contracts": [
{
"id": "uuid",
"name": "采购合同-供应商A",
"number": "PO-2026-001",
"sign_date": "2026-01-15",
"expiry_date": "2026-12-31",
"nodes": [
{
"id": "node-1",
"type": "payment",
"description": "首付款 30%",
"amount": 30000,
"due_date": "2026-04-30",
"status": "pending"
}
],
"created_at": "2026-04-22T00:00:00Z"
}
]
}
适用场景与注意¶
适合谁
- 中小团队法务、采购、运营：合同份数可控，希望把节点从 PDF 落到可查询台账
- 已使用飞书机器人做内部通知，希望到期前自动催办
- 愿意自备 AI API Key，并接受本地 JSON 存储（非多租户 SaaS）
限制与坑
- 扫描版 PDF： README 写明需先 OCR，纯文本 PDF 抽取才可靠。
- 密钥与合规：
requires_api_key=true；Token 走外网验证，内网或离线环境会走 Free 降级逻辑，套餐上限以验证结果为准。 - 提醒落地： 需配置
feishu_webhook（或按代码注释使用飞书 IM 能力发送card_json）；未配置则只能生成提醒内容，不会自动推送。 - 收费套餐： 文档指向 YK-Global.com 购买更高档位；本文不展开定价策略，以技能内表格为准。
- 数据位置： 台账在本地文件，备份与权限需自行管理；换机器要同步
contract_ledger.json或CONTRACT_TRACKER_LEDGER指向的路径。
结尾¶
Contract Tracker Pro 把合同履约从「翻 PDF + 记日历」收成一条 Agent Skill 流程：解析、台账、提醒规则都在包内脚本与 SKILL.md 里写清，适合作为 business-ops 类技能接入 Cursor 等环境。
- SkillHub 页面：https://www.skillhub.cn/skills/user_26bdbd50/contract-tracker-pro
- API 条目：https://api.skillhub.cn/user_26bdbd50/contract-tracker-pro
