Contract Ledger

Upload contract PDFs, extract key contract fields offline, manage a local ledger with expiry reminders and optional Feishu notifications.

Security Scan

The skill mostly does what it claims (offline PDF parsing + local ledger) but its registry metadata, documentation, and code disagree about billing/network and environment requirements — and it will call a third‑party billing endpoint if an API key is present.

Purpose & Capability

The skill's stated purpose (offline PDF extraction and local ledger) aligns with most of the code (PyMuPDF parsing, JSON storage under /tmp). However the SKILL.md and code include a SkillPay billing integration that triggers network calls to https://skillpay.me. The registry metadata listed no required environment variables, but the code and SKILL.md expect SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID — this mismatch is unexplained and concerning.

Instruction Scope

SKILL.md repeatedly states 'PDF parsing is fully offline' and 'data stored locally', which is true for the parsing and storage functions. But most runtime flows in scripts/main (upload, check, etc.) call billing.charge_user which performs network requests to skillpay.me; those network calls are not obvious in the headline description. SKILL.md also says a Feishu User ID 'may be transmitted to skillpay.me', but the included code does not send any Feishu user ID — instead charge_user accepts a user_id parameter and main currently passes static IDs like 'cli_upload'. The documentation and code disagree about what is transmitted.

Install Mechanism

There is no install spec (instruction-only install) and dependencies are standard (PyMuPDF, requests). No arbitrary downloads or obscure install URLs are used. This is the lower-risk install pattern.

Credentials

The code reads SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID from environment and will include the API key in an X-API-Key header when talking to skillpay.me. SKILL.md lists these env vars, but the registry metadata did not — an inconsistency. Requiring a billing API key is proportionate for a paid skill, but you must understand that providing the key causes network calls to a third party and transmits that key to skillpay.me. The skill does not request unrelated credentials, but the absence of declared env vars in the registry is misleading.

Persistence & Privilege

The skill does not request always: true, does not modify other skills, and stores data in /tmp/contract-ledger (no home directory writes as claimed). Note: /tmp is world-readable on many systems and data is stored unencrypted in plain JSON; this is an operational privacy risk (other local users may read the files).

What to consider before installing

Key things to consider before installing: - Billing/network behavior: If SKILL_BILLING_API_KEY is set, the skill will make HTTP requests to https://skillpay.me to check balance/charge per operation and will send an X-API-Key header. If you don't trust that domain or don't want outbound calls, leave the env var unset (the code treats empty/'dev'/'test' as dev mode and skips real charges). - Registry/documentation mismatch: The registry metadata says no env vars required, but SKILL.md and the code require SKILL_BILLING_API_KEY and SKILL_BILLING_SKILL_ID for PRO billing. Ask the author to explain the discrepancy before trusting the package. - Data storage and privacy: Contracts are stored unencrypted in /tmp/contract-ledger/contracts.json. /tmp is typically world-readable and ephemeral — do not use this for highly sensitive contracts unless you accept that risk or change the storage path/permissions. - Feishu behavior: The code only builds Feishu card payloads and prints them; there is no code here that sends messages to Feishu. If you expect push notifications, confirm how Feishu tokens are configured and whether any additional code will be added to perform outbound requests. - Billing claims vs. implementation: SKILL.md states 'Your Feishu User ID may be transmitted to skillpay.me for billing', but the included code does not transmit a Feishu user ID today. This inconsistency should be clarified. Recommended actions: 1) Ask the publisher to fix registry metadata (declare required env vars) and clarify what is sent to skillpay.me and when. 2) If you want to try the skill offline, run it with SKILL_BILLING_API_KEY unset (dev mode) in an isolated environment to avoid network calls and charges. 3) If you enable billing, provide the API key only if you trust skillpay.me; consider using a scoped/rotateable key and monitor network traffic. 4) If handling sensitive contracts, change storage to a safer location with appropriate permissions or encrypt the ledger before use. Overall: the code appears functional and not overtly malicious, but the mismatches between declared requirements, documentation, and network behavior are concerning and merit clarification before trusting the skill with real data or credentials.

Upload contract PDFs → AI extracts key fields → Manage ledger → Expiry reminders + Feishu push

---

Trigger Phrases

contract ledger contract management contract tracker pdf contract contract reminder 合同台账

---

Usage

Command Line

# Upload a contract PDF
python -m scripts.main upload /path/to/contract.pdf

# List all contracts
python -m scripts.main list

# List contracts expiring within 30 days
python -m scripts.main list --status "Active" --sort end_date

# Get contract details
python -m scripts.main get <contract_id>

# Update a contract
python -m scripts.main update <contract_id> --name "New Name" --status "Terminated"

# Delete a contract
python -m scripts.main delete <contract_id>

# Add expiry reminder
python -m scripts.main reminder <contract_id> add --days 30

# Check expiring contracts
python -m scripts.main check --days 30

# Export contracts
python -m scripts.main export --format csv -o contracts.csv

Python API

from scripts import extract_text_from_pdf, extract_contract_fields
from scripts import add_contract, get_contracts, get_contract
from scripts import update_contract, delete_contract

# Extract fields from PDF
text = extract_text_from_pdf("/path/to/contract.pdf")
fields = extract_contract_fields(text, "contract.pdf")
contract = add_contract(fields)

# List contracts
all_contracts = get_contracts(status="Active")

---

Contract Fields Extracted

• Contract Name — from PDF title
• Amount — RMB amount via regex
• Sign Date — contract signing date
• Start Date — effective start date
• End Date — expiry date
• Counterparty — other party name (乙方/供应商/委托方)
• Key Nodes — payment terms, renewal clauses (up to 5)
• Status — Active / Expired (auto-calculated)

---

Supported Formats

Format	Extension	Notes
PDF	.pdf	Text extraction via PyMuPDF

---

Tech Stack

• Parsing: PyMuPDF (fitz)
• AI Field Extraction: Regex + heuristic pattern matching (no external AI API needed)
• Storage: JSON file in /tmp/contract-ledger/ (fully offline)
• Notifications: Feishu IM card format

---

Tiered Features

Feature	FREE	PRO
Max Contracts	5	Unlimited
Max Reminders	1	Unlimited
Export Formats	CSV	CSV, XLSX, PDF
Feishu Reminders	No	Yes
Priority Support	No	Yes

---

Billing

$0.01 USDT per call — billed via SkillPay at https://skillpay.me/contract-ledger

Privacy Note: Your Feishu User ID (Open ID) may be transmitted to skillpay.me for billing purposes only.

| Price | $0 (FREE tier) | $0.01 / call (PRO tier) |

For paid use, visit https://skillpay.me/contract-ledger

---

Required Environment Variables

Variable	Description
SKILL_BILLING_API_KEY	SkillPay Builder API Key (from skillpay.me)
SKILL_BILLING_SKILL_ID	Skill ID on SkillPay (default: contract-ledger)

---

Security Notes

• All contract data is stored locally in /tmp/contract-ledger/ — no home directory writes
• PDF parsing is fully offline — no external network calls during extraction
• Feishu card push requires a Feishu bot token (configure separately)
• Token validation is handled by SkillPay billing system, not by the skill itself

---

API Key Format

Any non-empty string works as an API key. Tier is determined automatically:

• No API key → FREE tier
• Any API key → PRO tier

---

Slug

contract-ledger