contact-vcard-extractor

name

contact-vcard-extractor

description

Extract contact info from text, chat history, web pages, screenshots, business card photos, QR codes/OCR results, clean name/phone/email/company/title/address/website, generate vCard/.vcf files, and guide user to import into iOS Contacts or share with others. Trigger words include: extract contact, save to contacts, generate vCard/vcf, business card recognition, add contact from image/screenshot/text, share contact, export contact.

Contact vCard Extractor

Goal

Convert contact info from user-provided text or images into a previewable, importable, shareable .vcf vCard file. Prioritize real usage experience: extract and let user confirm first, then generate file; mark uncertain fields, do not silently fill incorrect values.

Typical Flow

1. Receive Input
   • Text: directly parse user message, pasted text, web page extraction results.
   • Image: business card photo, screenshot, poster, chat screenshot. Use apple-vision ocr first for text recognition; if QR code suspected, use apple-vision barcode.
   • File: check /var/minis/attachments/, /var/minis/workspace/, /var/minis/mounts/ first.
2. Extract Fields
   • Name FN/N
   • Phone TEL, multiple numbers must be separate TEL entries; only put number itself in phone field, do not append labels like "reception/mobile/WeChat" to the number. Export all phones as TEL;TYPE=CELL, user can change type if needed. Labels can be shown in summary or placed in NOTE if necessary.
   • Email EMAIL
   • Company ORG
   • Title TITLE
   • Address ADR
   • Website URL
   • Note NOTE: source, WeChat ID, uncategorized but useful info, uncertain identifications. Do not include temporary todos/reminders/follow-up items.
3. User Confirmation
   • List fields concisely, highlight potentially misidentified content.
   • If name or phone/email is missing, ask if user wants to supplement; if user is in a hurry, generate "unnamed contact".
4. Generate vCard
   • Use bundled script: /var/minis/skills/contact-vcard-extractor/scripts/contact_to_vcard.py
   • Output to /var/minis/workspace/contact_name.vcf, remove special characters from filename; use contact.vcf if needed.
5. Present & Import/Share
   • Provide Markdown file link: [Import Contact](minis://workspace/xxx.vcf).
   • Can use minis-open /var/minis/workspace/xxx.vcf to preview/share in-app.
   • If user explicitly wants import screen, can run apple-open /var/minis/workspace/xxx.vcf or minis-open; usually prefer minis-open to stay in chat.

Image/OCR Command Mode

apple-vision ocr /var/minis/attachments/card.jpg --lang zh-Hans,en --level accurate --compact
apple-vision barcode /var/minis/attachments/card.jpg --compact

Save OCR output as text file, then call parse script.

Text to vCard Command

python3 /var/minis/skills/contact-vcard-extractor/scripts/contact_to_vcard.py \
  --text-file /var/minis/workspace/contact_ocr.txt \
  --out /var/minis/workspace/contact.vcf \
  --json

Can also pass text via stdin. Do not inline long text in shell command; use file_write to write file first.

Experience Details

• No temporary info in contact notes: Items like "send quote next Tuesday" "call back tomorrow" "follow up end of month" should be excluded from vCard NOTE, and separately prompt "Would you like me to create a reminder/todo?". If user confirms, use apple-reminders create to create reminder.
• Phone fields must be clean and uniform CELL: TEL should only contain the number, e.g., 010-66668888, 13344445555. When encountering "010-66668888 (reception), mobile [phone]", split into two phone entries; "reception/mobile" only as display labels or NOTE, not appended to number. Export all phones as TEL;TYPE=CELL, do not use VOICE/HOME/WORK types unless user explicitly specifies.
• Do not import directly to Contacts unless user explicitly confirms; generate vcf first and let user tap to confirm.
• Lightweight privacy reminder: Contact info is personal; only remind user to confirm authorization and content when sharing/batch processing.
• Multiple contacts: If text/image clearly contains multiple people, generate separate .vcf files, or merge into one contacts.vcf containing multiple vCards. Present each person in a table.
• QR codes: If QR content is MECARD:, BEGIN:VCARD, tel:, mailto:, WeChat/URL, parse accordingly; raw vCard can be saved directly as .vcf, MECARD needs conversion.
• Chinese names: For vCard N field, first character can be surname and rest given name; when uncertain, prioritize FN for correct display.
• International numbers: Keep +country code, extension, spaces; do not force rewrite.
• File naming: Prefer name.vcf; if name empty use contact-YYYYMMDD-HHMM.vcf.
• Final reply format:
  1. One sentence stating it's been generated.
  2. Field summary.
  3. File link.
  4. "Tap to add to Contacts, or use share button to send to others."

Example Reply

Card ready:

Field	Content
Name	Zhang San
Phone	[phone]
Email	[e-mail]
Company	Example Tech

Import/Share Contact

Tap to add to Contacts, or share directly with others.

Bundled Script Notes

contact_to_vcard.py performs basic rule-based extraction and vCard escaping. It is not the only approach: for complex, low-quality OCR or messy layout, combine model judgment to manually correct fields before generating vCard.