[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-photon-hq--imessage-kit":3,"tool-photon-hq--imessage-kit":64},[4,17,27,35,43,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":16},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,3,"2026-04-05T11:01:52",[13,14,15],"开发框架","图像","Agent","ready",{"id":18,"name":19,"github_repo":20,"description_zh":21,"stars":22,"difficulty_score":23,"last_commit_at":24,"category_tags":25,"status":16},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",138956,2,"2026-04-05T11:33:21",[13,15,26],"语言模型",{"id":28,"name":29,"github_repo":30,"description_zh":31,"stars":32,"difficulty_score":23,"last_commit_at":33,"category_tags":34,"status":16},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107662,"2026-04-03T11:11:01",[13,14,15],{"id":36,"name":37,"github_repo":38,"description_zh":39,"stars":40,"difficulty_score":23,"last_commit_at":41,"category_tags":42,"status":16},3704,"NextChat","ChatGPTNextWeb\u002FNextChat","NextChat 是一款轻量且极速的 AI 助手，旨在为用户提供流畅、跨平台的大模型交互体验。它完美解决了用户在多设备间切换时难以保持对话连续性，以及面对众多 AI 模型不知如何统一管理的痛点。无论是日常办公、学习辅助还是创意激发，NextChat 都能让用户随时随地通过网页、iOS、Android、Windows、MacOS 或 Linux 端无缝接入智能服务。\n\n这款工具非常适合普通用户、学生、职场人士以及需要私有化部署的企业团队使用。对于开发者而言，它也提供了便捷的自托管方案，支持一键部署到 Vercel 或 Zeabur 等平台。\n\nNextChat 的核心亮点在于其广泛的模型兼容性，原生支持 Claude、DeepSeek、GPT-4 及 Gemini Pro 等主流大模型，让用户在一个界面即可自由切换不同 AI 能力。此外，它还率先支持 MCP（Model Context Protocol）协议，增强了上下文处理能力。针对企业用户，NextChat 提供专业版解决方案，具备品牌定制、细粒度权限控制、内部知识库整合及安全审计等功能，满足公司对数据隐私和个性化管理的高标准要求。",87618,"2026-04-05T07:20:52",[13,26],{"id":44,"name":45,"github_repo":46,"description_zh":47,"stars":48,"difficulty_score":23,"last_commit_at":49,"category_tags":50,"status":16},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,"2026-04-05T10:45:23",[14,51,52,53,15,54,26,13,55],"数据工具","视频","插件","其他","音频",{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":16},3128,"ragflow","infiniflow\u002Fragflow","RAGFlow 是一款领先的开源检索增强生成（RAG）引擎，旨在为大语言模型构建更精准、可靠的上下文层。它巧妙地将前沿的 RAG 技术与智能体（Agent）能力相结合，不仅支持从各类文档中高效提取知识，还能让模型基于这些知识进行逻辑推理和任务执行。\n\n在大模型应用中，幻觉问题和知识滞后是常见痛点。RAGFlow 通过深度解析复杂文档结构（如表格、图表及混合排版），显著提升了信息检索的准确度，从而有效减少模型“胡编乱造”的现象，确保回答既有据可依又具备时效性。其内置的智能体机制更进一步，使系统不仅能回答问题，还能自主规划步骤解决复杂问题。\n\n这款工具特别适合开发者、企业技术团队以及 AI 研究人员使用。无论是希望快速搭建私有知识库问答系统，还是致力于探索大模型在垂直领域落地的创新者，都能从中受益。RAGFlow 提供了可视化的工作流编排界面和灵活的 API 接口，既降低了非算法背景用户的上手门槛，也满足了专业开发者对系统深度定制的需求。作为基于 Apache 2.0 协议开源的项目，它正成为连接通用大模型与行业专有知识之间的重要桥梁。",77062,"2026-04-04T04:44:48",[15,14,13,26,54],{"id":65,"github_repo":66,"name":67,"description_en":68,"description_zh":69,"ai_summary_zh":69,"readme_en":70,"readme_zh":71,"quickstart_zh":72,"use_case_zh":73,"hero_image_url":74,"owner_login":75,"owner_name":76,"owner_avatar_url":77,"owner_bio":78,"owner_company":79,"owner_location":79,"owner_email":80,"owner_twitter":81,"owner_website":82,"owner_url":83,"languages":84,"stars":89,"forks":90,"last_commit_at":91,"license":92,"difficulty_score":23,"env_os":93,"env_gpu":94,"env_ram":94,"env_deps":95,"category_tags":101,"github_topics":102,"view_count":10,"oss_zip_url":79,"oss_zip_packed_at":79,"status":16,"created_at":109,"updated_at":110,"faqs":111,"releases":139},549,"photon-hq\u002Fimessage-kit","imessage-kit","A type-safe, elegant iMessage SDK for macOS with zero dependencies","imessage-kit 是一款专为 macOS 打造的开源 iMessage SDK，旨在让开发者能够以编程方式读取、发送及自动化管理 iMessage 对话。过去，在 Mac 上实现消息自动化往往涉及复杂的脚本编写或底层数据库操作，而 imessage-kit 通过提供简洁优雅的 API 解决了这一痛点，大幅降低了构建 AI 智能体或聊天应用的门槛。\n\nimessage-kit 主要面向 TypeScript 开发者、AI 研究人员以及自动化爱好者。imessage-kit 的技术亮点十分突出：不仅支持类型安全，在使用 Bun 运行时还能实现零依赖安装。此外，imessage-kit 还具备实时监听消息、自动回复、批量发送、插件扩展以及定时提醒等丰富功能。需要注意的是，为了读取聊天记录和执行自动化任务，macOS 系统需授予其完全磁盘访问权限。如果你希望在 Mac 生态中快速集成强大的消息处理能力，imessage-kit 是一个非常值得尝试的选择。","\u003Cdiv align=\"center\">\n  \n![Banner](.\u002F.github\u002Fassets\u002Fbanner.png)\n\n# @photon-ai\u002Fimessage-kit\n\n> A type-safe, elegant iMessage SDK for macOS with cross-runtime support\n\n\u003C\u002Fdiv>\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@photon-ai\u002Fimessage-kit.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@photon-ai\u002Fimessage-kit)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.3-blue.svg)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)](.\u002FLICENSE)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join-5865F2.svg?logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.gg\u002FbZd4CMd2H5)\n\nA full-featured iMessage SDK for **reading**, **sending**, and **automating** iMessage conversations on macOS. Perfect for building AI agents, automation tools, and chat-first applications.\n\n> [!NOTE]\n> **✨ Looking for advanced features like threaded replies, tapbacks, message editing, unsending, live typing indicators? Check out [Advanced iMessage Kit](https:\u002F\u002Fgithub.com\u002Fphoton-hq\u002Fadvanced-imessage-kit) and contact us at daniel@photon.codes.**\n\n---\n\n## Features\n\n| Feature | Method | Example |\n|---------|--------|---------|\n| [Send Messages](#send-messages) | `sdk.send()` | [01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) |\n| [Send Images](#send-images) | `sdk.send()` | [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) |\n| [Send Files](#send-files) | `sdk.sendFile()` | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) |\n| [Send to Groups](#send-to-groups) | `sdk.send()` | [04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) |\n| [Query Messages](#query-messages) | `sdk.getMessages()` | [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts) |\n| [List Chats](#list-chats) | `sdk.listChats()` | [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts) |\n| [Real-time Watching](#real-time-watching) | `sdk.startWatching()` | [07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) |\n| [Auto Reply](#auto-reply) | `sdk.message()` | [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) |\n| Batch Send | `sdk.sendBatch()` | [09-batch-send.ts](.\u002Fexamples\u002F09-batch-send.ts) |\n| Get Sent Message | `sdk.send()` | [10-get-sent-message.ts](.\u002Fexamples\u002F10-get-sent-message.ts) |\n| [Plugin System](#plugin-system) | `sdk.use()` | [11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts) |\n| [Error Handling](#error-handling) | `SendError` | [12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts) |\n| Watch Own Messages | `sdk.startWatching()` | [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts) |\n| [Scheduled Messages](#scheduled-messages) | `MessageScheduler` | [14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) |\n| [Smart Reminders](#smart-reminders) | `Reminders` | [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts) |\n\n---\n\n## Quick Start\n\n### Installation\n\n```bash\n# For Bun (zero dependencies)\nbun add @photon-ai\u002Fimessage-kit\n\n# For Node.js (requires better-sqlite3)\nnpm install @photon-ai\u002Fimessage-kit better-sqlite3\n```\n\n### Basic Usage\n\n```typescript\nimport { IMessageSDK } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\n\n\u002F\u002F Send a message\nawait sdk.send('+1234567890', 'Hello from iMessage Kit!')\n\n\u002F\u002F Clean up\nawait sdk.close()\n```\n\n### Configuration\n\n```typescript\ninterface IMessageConfig {\n    debug?: boolean              \u002F\u002F Enable debug logging\n    maxConcurrent?: number       \u002F\u002F Max concurrent sends (default: 5)\n    scriptTimeout?: number       \u002F\u002F AppleScript timeout in ms\n    databasePath?: string        \u002F\u002F Custom database path\n    plugins?: Plugin[]           \u002F\u002F Plugins\n    watcher?: {\n        pollInterval?: number    \u002F\u002F Polling interval (default: 2000)\n        unreadOnly?: boolean     \u002F\u002F Only watch unread (default: false)\n        excludeOwnMessages?: boolean  \u002F\u002F Exclude own messages (default: true)\n    }\n    webhook?: {\n        url: string\n        headers?: Record\u003Cstring, string>\n    }\n}\n```\n\n### Granting Permission\n\n`IMessageKit` requires **Full Disk Access** to read your chat history and perform automation tasks.\n\n1. Open **System Settings → Privacy & Security → Full Disk Access**\n2. Click **\"+\"** and add your IDE or terminal (e.g., Cursor, VS Code, Terminal, Warp)\n\n---\n\n## Messages\n\n> Examples: [01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) | [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) | [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts)\n\n### Send Messages\n\n```typescript\n\u002F\u002F Send text\nawait sdk.send('+1234567890', 'Hello World!')\n\n\u002F\u002F Send to email\nawait sdk.send('user@example.com', 'Hello!')\n```\n\n### Send Images\n\n```typescript\n\u002F\u002F Send local images\nawait sdk.send('+1234567890', { \n    images: ['image1.jpg', 'image2.png'] \n})\n\n\u002F\u002F Send network images (auto-download)\nawait sdk.send('+1234567890', { \n    images: ['https:\u002F\u002Fexample.com\u002Fimage.jpg'] \n})\n\n\u002F\u002F Text with images\nawait sdk.send('+1234567890', { \n    text: 'Check this out!',\n    images: ['photo.jpg']\n})\n```\n\n### Send Files\n\n```typescript\n\u002F\u002F Send files (PDF, CSV, VCF, etc.)\nawait sdk.send('+1234567890', { \n    files: ['document.pdf', 'data.csv', 'contact.vcf'] \n})\n\n\u002F\u002F Convenience methods\nawait sdk.sendFile('+1234567890', '\u002Fpath\u002Fto\u002Fdocument.pdf')\nawait sdk.sendFiles('+1234567890', ['file1.pdf', 'file2.csv'], 'Multiple files')\n```\n\n### Query Messages\n\n```typescript\n\u002F\u002F Get messages with filters\nconst result = await sdk.getMessages({\n    sender: '+1234567890',\n    unreadOnly: true,\n    limit: 20,\n    since: new Date('2025-01-01'),\n    search: 'meeting'\n})\n\n\u002F\u002F Get unread messages grouped by sender\nconst unread = await sdk.getUnreadMessages()\nconsole.log(`${unread.total} unread from ${unread.senderCount} senders`)\n```\n\n---\n\n## Chats\n\n> Examples: [04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) | [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts)\n\n### List Chats\n\n```typescript\n\u002F\u002F Get all chats\nconst all = await sdk.listChats()\n\n\u002F\u002F Filter chats\nconst groups = await sdk.listChats({\n    type: 'group',\n    hasUnread: true,\n    sortBy: 'recent',\n    search: 'Project',\n    limit: 20\n})\n\n\u002F\u002F Each chat includes\nfor (const chat of groups) {\n    console.log({\n        chatId: chat.chatId,\n        name: chat.displayName,\n        isGroup: chat.isGroup,\n        unread: chat.unreadCount\n    })\n}\n```\n\n### Send to Groups\n\n```typescript\n\u002F\u002F Get group chatId from listChats()\nconst groups = await sdk.listChats({ type: 'group' })\nconst chatId = groups[0].chatId  \u002F\u002F e.g., 'chat45e2b868...'\n\n\u002F\u002F Send to group\nawait sdk.send(chatId, 'Hello group!')\nawait sdk.send(chatId, {\n    text: 'Check these files',\n    files: ['report.pdf']\n})\n```\n\n---\n\n## Real-time Events\n\n> Examples: [07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) | [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) | [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts)\n\n### Real-time Watching\n\n```typescript\nawait sdk.startWatching({\n    \u002F\u002F All messages\n    onMessage: (msg) => {\n        console.log(`New: ${msg.text}`)\n    },\n    \n    \u002F\u002F DMs only\n    onDirectMessage: (msg) => {\n        console.log(`DM from ${msg.sender}`)\n    },\n    \n    \u002F\u002F Groups only\n    onGroupMessage: (msg) => {\n        console.log(`Group: ${msg.chatId}`)\n    },\n    \n    onError: (error) => {\n        console.error(error)\n    }\n})\n\n\u002F\u002F Stop watching\nsdk.stopWatching()\n```\n\n### Auto Reply\n\n```typescript\nawait sdk.startWatching({\n    onDirectMessage: async (msg) => {\n        await sdk.message(msg)\n            .ifFromOthers()\n            .matchText(\u002Fhello\u002Fi)\n            .replyText('Hi there!')\n            .execute()\n    }\n})\n```\n\n### Message Chain API\n\n```typescript\nawait sdk.message(msg)\n    .ifUnread()\n    .ifNotReaction()   \u002F\u002F Skip tapback reactions\n    .ifGroupChat()\n    .when(m => m.sender.startsWith('+1'))\n    .matchText(\u002Fphoto\u002Fi)\n    .replyImage(['photo.jpg'])\n    .execute()\n```\n\n---\n\n## Attachments\n\n> Examples: [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts)\n\n### Attachment Helpers\n\n```typescript\nimport {\n    attachmentExists,\n    downloadAttachment,\n    getAttachmentSize,\n    isImageAttachment,\n    isVideoAttachment,\n    isAudioAttachment\n} from '@photon-ai\u002Fimessage-kit'\n\nconst msg = await sdk.getMessages({ hasAttachments: true, limit: 1 })\nconst attachment = msg.messages[0].attachments[0]\n\nif (await attachmentExists(attachment)) {\n    const size = await getAttachmentSize(attachment)\n    \n    if (isImageAttachment(attachment)) {\n        await downloadAttachment(attachment, '\u002Fpath\u002Fto\u002Fsave.jpg')\n    }\n}\n```\n\n### Supported File Types\n\n- **Documents**: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, RTF\n- **Images**: JPG, PNG, GIF, HEIC, WEBP, AVIF\n- **Contact Cards**: VCF (vCard)\n- **Data Files**: CSV, JSON, XML\n- **Archives**: ZIP, RAR, 7Z\n- **Media**: MP4, MOV, MP3, M4A\n\n---\n\n## Scheduling\n\n> Examples: [14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) | [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts)\n\n### Scheduled Messages\n\n```typescript\nimport { IMessageSDK, MessageScheduler } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\nconst scheduler = new MessageScheduler(sdk, { debug: true }, {\n    onSent: (msg, result) => console.log(`✅ Sent: ${msg.id}`),\n    onError: (msg, error) => console.error(`❌ Failed: ${error.message}`),\n    onComplete: (msg) => console.log(`🏁 Completed: ${msg.id}`)\n})\n\n\u002F\u002F One-time message\nconst id = scheduler.schedule({\n    to: '+1234567890',\n    content: 'Reminder!',\n    sendAt: new Date(Date.now() + 5 * 60 * 1000)  \u002F\u002F 5 minutes\n})\n\n\u002F\u002F Recurring daily\nscheduler.scheduleRecurring({\n    to: '+1234567890',\n    content: 'Good morning! ☀️',\n    startAt: new Date('2025-01-01T08:00:00'),\n    interval: 'daily',  \u002F\u002F 'hourly' | 'daily' | 'weekly' | 'monthly' | number\n    endAt: new Date('2025-12-31')\n})\n\n\u002F\u002F Manage\nscheduler.reschedule(id, newDate)\nscheduler.cancel(id)\nscheduler.getPending()\n\n\u002F\u002F Persistence\nconst data = scheduler.export()\nscheduler.import(data)\n\n\u002F\u002F Cleanup\nscheduler.destroy()\n```\n\n### Smart Reminders\n\nA human-friendly wrapper for scheduling with natural language:\n\n```typescript\nimport { IMessageSDK, Reminders } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\nconst reminders = new Reminders(sdk)\n\n\u002F\u002F Relative time\nreminders.in('5 minutes', '+1234567890', 'Take a break!')\nreminders.in('2 hours', '+1234567890', 'Call the client')\nreminders.in('1 day', '+1234567890', 'Follow up')\n\n\u002F\u002F Specific time\nreminders.at('5pm', '+1234567890', 'End of day review')\nreminders.at('tomorrow 9am', '+1234567890', 'Morning standup')\nreminders.at('friday 2pm', '+1234567890', 'Weekly sync')\n\n\u002F\u002F Exact date\nreminders.exact(new Date('2025-12-25T10:00:00'), '+1234567890', 'Merry Christmas!')\n\n\u002F\u002F Manage\nreminders.list()    \u002F\u002F List pending\nreminders.count()   \u002F\u002F Count pending\nreminders.cancel(id)\nreminders.destroy()\n```\n\n**Supported formats:**\n- Duration: `\"5 minutes\"`, `\"2 hours\"`, `\"1 day\"`, `\"30 seconds\"`, `\"1 week\"`\n- Time: `\"5pm\"`, `\"5:30pm\"`, `\"17:30\"`\n- Day + Time: `\"tomorrow 9am\"`, `\"friday 2pm\"`\n\n---\n\n## Plugin System\n\n> Example: [11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts)\n\n```typescript\nimport { loggerPlugin } from '@photon-ai\u002Fimessage-kit'\n\n\u002F\u002F Built-in logger\nsdk.use(loggerPlugin({\n    level: 'info',\n    colored: true\n}))\n\n\u002F\u002F Custom plugin\nsdk.use({\n    name: 'my-plugin',\n    onInit: async () => console.log('Initialized'),\n    onBeforeSend: async (to, content) => {\n        console.log('Sending to:', to)\n        return { to, content }\n    },\n    onAfterSend: async (result) => {\n        console.log('Sent:', result)\n    },\n    onDestroy: async () => console.log('Destroyed')\n})\n```\n\n---\n\n## Error Handling\n\n> Example: [12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts)\n\n```typescript\nimport { SendError, DatabaseError, PlatformError } from '@photon-ai\u002Fimessage-kit'\n\ntry {\n    await sdk.send('+1234567890', 'Hello')\n} catch (error) {\n    if (error instanceof SendError) {\n        console.error('Send failed:', error.message)\n    } else if (error instanceof DatabaseError) {\n        console.error('Database error:', error.message)\n    } else if (error instanceof PlatformError) {\n        console.error('Platform error:', error.message)\n    }\n}\n```\n\n---\n\n## Examples\n\nRun any example with Bun:\n\n```bash\nbun run examples\u002F\u003Cfilename>.ts\n```\n\n### Getting Started\n- [01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) - Basic text message\n- [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) - Send images\n- [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) - Send files\n\n### Message Operations\n- [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts) - Query messages\n- [09-batch-send.ts](.\u002Fexamples\u002F09-batch-send.ts) - Batch sending\n- [10-get-sent-message.ts](.\u002Fexamples\u002F10-get-sent-message.ts) - Get sent message\n\n### Chats & Groups\n- [04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) - Send to group\n- [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts) - List chats\n\n### Real-time & Automation\n- [07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) - Watch messages\n- [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) - Auto-reply bot\n- [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts) - Watch own messages\n\n### Scheduling\n- [14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) - Scheduled messages\n- [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts) - Smart reminders\n\n### Advanced\n- [11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts) - Custom plugin\n- [12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts) - Error handling\n\n---\n\n## API Reference\n\n### Core Methods\n\n| Method | Description |\n|--------|-------------|\n| `getMessages(filter?)` | Query messages with filters |\n| `getUnreadMessages()` | Get unread messages grouped by sender |\n| `listChats(options?)` | List chats with filtering\u002Fsorting |\n| `send(to, content)` | Send text, images, and\u002For files |\n| `sendFile(to, path, text?)` | Send a single file |\n| `sendFiles(to, paths, text?)` | Send multiple files |\n| `sendBatch(messages)` | Send multiple messages concurrently |\n| `message(msg)` | Create message processing chain |\n| `startWatching(events?)` | Start monitoring new messages |\n| `stopWatching()` | Stop monitoring |\n| `use(plugin)` | Register plugin |\n| `close()` | Close SDK and release resources |\n\n### Types\n\n```typescript\ninterface Message {\n    id: string\n    guid: string\n    text: string | null\n    sender: string\n    senderName: string | null\n    chatId: string\n    isGroupChat: boolean\n    isFromMe: boolean\n    isRead: boolean\n    service: 'iMessage' | 'SMS' | 'RCS'\n    attachments: Attachment[]\n    date: Date\n    \u002F\u002F Reaction fields\n    isReaction: boolean\n    reactionType: 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | null\n    isReactionRemoval: boolean\n    associatedMessageGuid: string | null\n}\n\ninterface SendResult {\n    sentAt: Date\n    message?: Message  \u002F\u002F Available if watcher is running\n}\n```\n\n---\n\n## Requirements\n\n- **OS**: macOS only\n- **Runtime**: Node.js >= 18.0.0 or Bun >= 1.0.0\n- **Permissions**: Full Disk Access\n\n---\n\n## LLMs\n\nDownload `llms.txt` for language model context:\n\n- [Download llms.txt](.\u002Fllms.txt)\n\n### Context7 MCP\n\n- [Context7 Docs](https:\u002F\u002Fcontext7.com\u002Fphoton-hq\u002Fimessage-kit)\n\nAdd [Context7 MCP](https:\u002F\u002Fcontext7.com\u002Fdocs\u002Finstallation) to your IDE, then use:\n\n```\nuse context7: photon-hq\u002Fimessage-kit\n```\n\n---\n\n## License\n\n[MIT License](.\u002FLICENSE)\n\n---\n\n**Note**: This SDK is for educational and development purposes. Always respect user privacy and follow Apple's terms of service.\n","\u003Cdiv align=\"center\">\n  \n![Banner](.\u002F.github\u002Fassets\u002Fbanner.png)\n\n# @photon-ai\u002Fimessage-kit\n\n> 一个适用于 macOS 的、类型安全且优雅的 iMessage SDK（软件开发工具包），支持跨运行时环境\n\n\u003C\u002Fdiv>\n\n[![npm version](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@photon-ai\u002Fimessage-kit.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@photon-ai\u002Fimessage-kit)\n[![TypeScript](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FTypeScript-5.3-blue.svg)](https:\u002F\u002Fwww.typescriptlang.org\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)](.\u002FLICENSE)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join-5865F2.svg?logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.gg\u002FbZd4CMd2H5)\n\n一个功能齐全的 iMessage SDK，用于在 macOS 上**读取**、**发送**和**自动化** iMessage 对话。非常适合构建 AI 智能体、自动化工具以及以聊天为首要的应用程序。\n\n> [!NOTE]\n> **✨ 正在寻找高级功能，如线程回复、tapback（点赞反馈）、消息编辑、撤回、实时输入指示器？请查看 [Advanced iMessage Kit](https:\u002F\u002Fgithub.com\u002Fphoton-hq\u002Fadvanced-imessage-kit) 并联系 daniel@photon.codes。**\n\n---\n\n## 功能\n\n| 功能 | 方法 | 示例 |\n|---------|--------|---------|\n| [发送消息](#send-messages) | `sdk.send()` | [01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) |\n| [发送图片](#send-images) | `sdk.send()` | [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) |\n| [发送文件](#send-files) | `sdk.sendFile()` | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) |\n| [发送给群组](#send-to-groups) | `sdk.send()` | [04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) |\n| [查询消息](#query-messages) | `sdk.getMessages()` | [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts) |\n| [列出聊天](#list-chats) | `sdk.listChats()` | [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts) |\n| [实时监听](#real-time-watching) | `sdk.startWatching()` | [07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) |\n| [自动回复](#auto-reply) | `sdk.message()` | [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) |\n| 批量发送 | `sdk.sendBatch()` | [09-batch-send.ts](.\u002Fexamples\u002F09-batch-send.ts) |\n| 获取已发送消息 | `sdk.send()` | [10-get-sent-message.ts](.\u002Fexamples\u002F10-get-sent-message.ts) |\n| [插件系统](#plugin-system) | `sdk.use()` | [11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts) |\n| [错误处理](#error-handling) | `SendError` | [12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts) |\n| 监听自己的消息 | `sdk.startWatching()` | [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts) |\n| [定时消息](#scheduled-messages) | `MessageScheduler` | [14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) |\n| [智能提醒](#smart-reminders) | `Reminders` | [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts) |\n\n---\n\n## 快速开始\n\n### 安装\n\n```bash\n# For Bun (zero dependencies)\nbun add @photon-ai\u002Fimessage-kit\n\n# For Node.js (requires better-sqlite3)\nnpm install @photon-ai\u002Fimessage-kit better-sqlite3\n```\n\n### 基本用法\n\n```typescript\nimport { IMessageSDK } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\n\n\u002F\u002F Send a message\nawait sdk.send('+1234567890', 'Hello from iMessage Kit!')\n\n\u002F\u002F Clean up\nawait sdk.close()\n```\n\n### 配置\n\n```typescript\ninterface IMessageConfig {\n    debug?: boolean              \u002F\u002F Enable debug logging\n    maxConcurrent?: number       \u002F\u002F Max concurrent sends (default: 5)\n    scriptTimeout?: number       \u002F\u002F AppleScript timeout in ms\n    databasePath?: string        \u002F\u002F Custom database path\n    plugins?: Plugin[]           \u002F\u002F Plugins\n    watcher?: {\n        pollInterval?: number    \u002F\u002F Polling interval (default: 2000)\n        unreadOnly?: boolean     \u002F\u002F Only watch unread (default: false)\n        excludeOwnMessages?: boolean  \u002F\u002F Exclude own messages (default: true)\n    }\n    webhook?: {\n        url: string\n        headers?: Record\u003Cstring, string>\n    }\n}\n```\n\n### 授予权限\n\n`IMessageKit` 需要**完全磁盘访问权限**才能读取您的聊天记录并执行自动化任务。\n\n1. 打开 **系统设置 → 隐私与安全性 → 完全磁盘访问**\n2. 点击 **\"+\"** 并添加您的 IDE 或终端（例如 Cursor, VS Code, Terminal, Warp）\n\n---\n\n## 消息\n\n> 示例：[01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) | [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) | [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts)\n\n### 发送消息\n\n```typescript\n\u002F\u002F Send text\nawait sdk.send('+1234567890', 'Hello World!')\n\n\u002F\u002F Send to email\nawait sdk.send('user@example.com', 'Hello!')\n```\n\n### 发送图片\n\n```typescript\n\u002F\u002F Send local images\nawait sdk.send('+1234567890', { \n    images: ['image1.jpg', 'image2.png'] \n})\n\n\u002F\u002F Send network images (auto-download)\nawait sdk.send('+1234567890', { \n    images: ['https:\u002F\u002Fexample.com\u002Fimage.jpg'] \n})\n\n\u002F\u002F Text with images\nawait sdk.send('+1234567890', { \n    text: 'Check this out!',\n    images: ['photo.jpg']\n})\n```\n\n### 发送文件\n\n```typescript\n\u002F\u002F Send files (PDF, CSV, VCF, etc.)\nawait sdk.send('+1234567890', { \n    files: ['document.pdf', 'data.csv', 'contact.vcf'] \n})\n\n\u002F\u002F Convenience methods\nawait sdk.sendFile('+1234567890', '\u002Fpath\u002Fto\u002Fdocument.pdf')\nawait sdk.sendFiles('+1234567890', ['file1.pdf', 'file2.csv'], 'Multiple files')\n```\n\n### 查询消息\n\n```typescript\n\u002F\u002F Get messages with filters\nconst result = await sdk.getMessages({\n    sender: '+1234567890',\n    unreadOnly: true,\n    limit: 20,\n    since: new Date('2025-01-01'),\n    search: 'meeting'\n})\n\n\u002F\u002F Get unread messages grouped by sender\nconst unread = await sdk.getUnreadMessages()\nconsole.log(`${unread.total} unread from ${unread.senderCount} senders`)\n```\n\n---\n\n## 聊天\n\n> 示例：[04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) | [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts)\n\n### 列出聊天\n\n```typescript\n\u002F\u002F Get all chats\nconst all = await sdk.listChats()\n\n\u002F\u002F Filter chats\nconst groups = await sdk.listChats({\n    type: 'group',\n    hasUnread: true,\n    sortBy: 'recent',\n    search: 'Project',\n    limit: 20\n})\n\n\u002F\u002F Each chat includes\nfor (const chat of groups) {\n    console.log({\n        chatId: chat.chatId,\n        name: chat.displayName,\n        isGroup: chat.isGroup,\n        unread: chat.unreadCount\n    })\n}\n```\n\n### 发送给群组\n\n```typescript\n\u002F\u002F Get group chatId from listChats()\nconst groups = await sdk.listChats({ type: 'group' })\nconst chatId = groups[0].chatId  \u002F\u002F e.g., 'chat45e2b868...'\n\n\u002F\u002F Send to group\nawait sdk.send(chatId, 'Hello group!')\nawait sdk.send(chatId, {\n    text: 'Check these files',\n    files: ['report.pdf']\n})\n```\n\n---\n\n## 实时事件\n\n> 示例：[07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) | [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) | [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts)\n\n### 实时监听\n\n```typescript\nawait sdk.startWatching({\n    \u002F\u002F All messages\n    onMessage: (msg) => {\n        console.log(`New: ${msg.text}`)\n    },\n    \n    \u002F\u002F DMs only\n    onDirectMessage: (msg) => {\n        console.log(`DM from ${msg.sender}`)\n    },\n    \n    \u002F\u002F Groups only\n    onGroupMessage: (msg) => {\n        console.log(`Group: ${msg.chatId}`)\n    },\n    \n    onError: (error) => {\n        console.error(error)\n    }\n})\n\n\u002F\u002F Stop watching\nsdk.stopWatching()\n```\n\n### 自动回复\n\n```typescript\nawait sdk.startWatching({\n    onDirectMessage: async (msg) => {\n        await sdk.message(msg)\n            .ifFromOthers()\n            .matchText(\u002Fhello\u002Fi)\n            .replyText('Hi there!')\n            .execute()\n    }\n})\n```\n\n### 消息链式 API\n\n```typescript\nawait sdk.message(msg)\n    .ifUnread()\n    .ifNotReaction()   \u002F\u002F Skip tapback reactions\n    .ifGroupChat()\n    .when(m => m.sender.startsWith('+1'))\n    .matchText(\u002Fphoto\u002Fi)\n    .replyImage(['photo.jpg'])\n    .execute()\n```\n\n---\n\n## 附件\n\n> 示例：[02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) | [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts)\n\n### 附件辅助函数\n\n```typescript\nimport {\n    attachmentExists,\n    downloadAttachment,\n    getAttachmentSize,\n    isImageAttachment,\n    isVideoAttachment,\n    isAudioAttachment\n} from '@photon-ai\u002Fimessage-kit'\n\nconst msg = await sdk.getMessages({ hasAttachments: true, limit: 1 })\nconst attachment = msg.messages[0].attachments[0]\n\nif (await attachmentExists(attachment)) {\n    const size = await getAttachmentSize(attachment)\n    \n    if (isImageAttachment(attachment)) {\n        await downloadAttachment(attachment, '\u002Fpath\u002Fto\u002Fsave.jpg')\n    }\n}\n```\n\n### 支持的文件类型\n\n- **文档**：PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, RTF\n- **图片**：JPG, PNG, GIF, HEIC, WEBP, AVIF\n- **联系人卡片**：VCF (vCard)\n- **数据文件**：CSV, JSON, XML\n- **压缩包**：ZIP, RAR, 7Z\n- **媒体**：MP4, MOV, MP3, M4A\n\n---\n\n## 定时发送\n\n> 示例：[14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) | [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts)\n\n### 定时消息\n\n```typescript\nimport { IMessageSDK, MessageScheduler } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\nconst scheduler = new MessageScheduler(sdk, { debug: true }, {\n    onSent: (msg, result) => console.log(`✅ Sent: ${msg.id}`),\n    onError: (msg, error) => console.error(`❌ Failed: ${error.message}`),\n    onComplete: (msg) => console.log(`🏁 Completed: ${msg.id}`)\n})\n\n\u002F\u002F One-time message\nconst id = scheduler.schedule({\n    to: '+1234567890',\n    content: 'Reminder!',\n    sendAt: new Date(Date.now() + 5 * 60 * 1000)  \u002F\u002F 5 minutes\n})\n\n\u002F\u002F Recurring daily\nscheduler.scheduleRecurring({\n    to: '+1234567890',\n    content: 'Good morning! ☀️',\n    startAt: new Date('2025-01-01T08:00:00'),\n    interval: 'daily',  \u002F\u002F 'hourly' | 'daily' | 'weekly' | 'monthly' | number\n    endAt: new Date('2025-12-31')\n})\n\n\u002F\u002F Manage\nscheduler.reschedule(id, newDate)\nscheduler.cancel(id)\nscheduler.getPending()\n\n\u002F\u002F Persistence\nconst data = scheduler.export()\nscheduler.import(data)\n\n\u002F\u002F Cleanup\nscheduler.destroy()\n```\n\n### 智能提醒\n\n一个支持自然语言的人类友好定时调度封装：\n\n```typescript\nimport { IMessageSDK, Reminders } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\nconst reminders = new Reminders(sdk)\n\n\u002F\u002F Relative time\nreminders.in('5 minutes', '+1234567890', 'Take a break!')\nreminders.in('2 hours', '+1234567890', 'Call the client')\nreminders.in('1 day', '+1234567890', 'Follow up')\n\n\u002F\u002F Specific time\nreminders.at('5pm', '+1234567890', 'End of day review')\nreminders.at('tomorrow 9am', '+1234567890', 'Morning standup')\nreminders.at('friday 2pm', '+1234567890', 'Weekly sync')\n\n\u002F\u002F Exact date\nreminders.exact(new Date('2025-12-25T10:00:00'), '+1234567890', 'Merry Christmas!')\n\n\u002F\u002F Manage\nreminders.list()    \u002F\u002F List pending\nreminders.count()   \u002F\u002F Count pending\nreminders.cancel(id)\nreminders.destroy()\n```\n\n**支持的格式：**\n- 时长：`\"5 minutes\"`, `\"2 hours\"`, `\"1 day\"`, `\"30 seconds\"`, `\"1 week\"`\n- 时间：`\"5pm\"`, `\"5:30pm\"`, `\"17:30\"`\n- 日期 + 时间：`\"tomorrow 9am\"`, `\"friday 2pm\"`\n\n---\n\n## 插件系统\n\n> 示例：[11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts)\n\n```typescript\nimport { loggerPlugin } from '@photon-ai\u002Fimessage-kit'\n\n\u002F\u002F Built-in logger\nsdk.use(loggerPlugin({\n    level: 'info',\n    colored: true\n}))\n\n\u002F\u002F Custom plugin\nsdk.use({\n    name: 'my-plugin',\n    onInit: async () => console.log('Initialized'),\n    onBeforeSend: async (to, content) => {\n        console.log('Sending to:', to)\n        return { to, content }\n    },\n    onAfterSend: async (result) => {\n        console.log('Sent:', result)\n    },\n    onDestroy: async () => console.log('Destroyed')\n})\n```\n\n---\n\n## 错误处理\n\n> 示例：[12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts)\n\n```typescript\nimport { SendError, DatabaseError, PlatformError } from '@photon-ai\u002Fimessage-kit'\n\ntry {\n    await sdk.send('+1234567890', 'Hello')\n} catch (error) {\n    if (error instanceof SendError) {\n        console.error('Send failed:', error.message)\n    } else if (error instanceof DatabaseError) {\n        console.error('Database error:', error.message)\n    } else if (error instanceof PlatformError) {\n        console.error('Platform error:', error.message)\n    }\n}\n```\n\n---\n\n## 示例\n\n使用 Bun 运行任意示例：\n\n```bash\nbun run examples\u002F\u003Cfilename>.ts\n```\n\n### 入门\n- [01-send-text.ts](.\u002Fexamples\u002F01-send-text.ts) - 基础文本消息\n- [02-send-image.ts](.\u002Fexamples\u002F02-send-image.ts) - 发送图片\n- [03-send-file.ts](.\u002Fexamples\u002F03-send-file.ts) - 发送文件\n\n### 消息操作\n- [05-query-messages.ts](.\u002Fexamples\u002F05-query-messages.ts) - 查询消息\n- [09-batch-send.ts](.\u002Fexamples\u002F09-batch-send.ts) - 批量发送\n- [10-get-sent-message.ts](.\u002Fexamples\u002F10-get-sent-message.ts) - 获取已发送消息\n\n### 聊天与群组\n- [04-send-group.ts](.\u002Fexamples\u002F04-send-group.ts) - 发送到群组\n- [06-list-chats.ts](.\u002Fexamples\u002F06-list-chats.ts) - 列出聊天\n\n### 实时与自动化\n- [07-watch-messages.ts](.\u002Fexamples\u002F07-watch-messages.ts) - 监听消息\n- [08-auto-reply.ts](.\u002Fexamples\u002F08-auto-reply.ts) - 自动回复机器人\n- [13-watch-own-messages.ts](.\u002Fexamples\u002F13-watch-own-messages.ts) - 监听自己的消息\n\n### 定时任务\n- [14-scheduled-messages.ts](.\u002Fexamples\u002F14-scheduled-messages.ts) - 定时消息\n- [15-smart-reminders.ts](.\u002Fexamples\u002F15-smart-reminders.ts) - 智能提醒\n\n### 高级功能\n- [11-plugin.ts](.\u002Fexamples\u002F11-plugin.ts) - 自定义插件\n- [12-error-handling.ts](.\u002Fexamples\u002F12-error-handling.ts) - 错误处理\n\n---\n\n## API 参考\n\n### 核心方法\n\n| 方法 | 描述 |\n|--------|-------------|\n| `getMessages(filter?)` | 使用过滤器查询消息 |\n| `getUnreadMessages()` | 按发送者分组获取未读消息 |\n| `listChats(options?)` | 列出聊天（支持过滤\u002F排序） |\n| `send(to, content)` | 发送文本、图片及\u002F或文件 |\n| `sendFile(to, path, text?)` | 发送单个文件 |\n| `sendFiles(to, paths, text?)` | 发送多个文件 |\n| `sendBatch(messages)` | 并发发送多条消息 |\n| `message(msg)` | 创建消息处理链 |\n| `startWatching(events?)` | 开始监控新消息 |\n| `stopWatching()` | 停止监控 |\n| `use(plugin)` | 注册插件 |\n| `close()` | 关闭 SDK（软件开发工具包）并释放资源 |\n\n### 类型\n\n```typescript\ninterface Message {\n    id: string\n    guid: string\n    text: string | null\n    sender: string\n    senderName: string | null\n    chatId: string\n    isGroupChat: boolean\n    isFromMe: boolean\n    isRead: boolean\n    service: 'iMessage' | 'SMS' | 'RCS'\n    attachments: Attachment[]\n    date: Date\n    \u002F\u002F Reaction fields\n    isReaction: boolean\n    reactionType: 'love' | 'like' | 'dislike' | 'laugh' | 'emphasize' | 'question' | null\n    isReactionRemoval: boolean\n    associatedMessageGuid: string | null\n}\n\ninterface SendResult {\n    sentAt: Date\n    message?: Message  \u002F\u002F Available if watcher is running\n}\n```\n\n---\n\n## 要求\n\n- **操作系统**：仅限 macOS\n- **运行环境**：Node.js >= 18.0.0 或 Bun >= 1.0.0\n- **权限**：完全磁盘访问权限\n\n---\n\n## 大语言模型 (LLMs)\n\n下载 `llms.txt` 以获取语言模型上下文：\n\n- [Download llms.txt](.\u002Fllms.txt)\n\n### Context7 MCP\n\n- [Context7 Docs](https:\u002F\u002Fcontext7.com\u002Fphoton-hq\u002Fimessage-kit)\n\n将 [Context7 MCP](https:\u002F\u002Fcontext7.com\u002Fdocs\u002Finstallation) 添加到您的集成开发环境 (IDE)，然后使用：\n\n```\nuse context7: photon-hq\u002Fimessage-kit\n```\n\n---\n\n## 许可证\n\n[MIT License](.\u002FLICENSE)\n\n---\n\n**注意**：本 SDK（软件开发工具包）仅供教育和开发用途。请始终尊重用户隐私并遵守 Apple 的服务条款。","# imessage-kit 快速上手指南\n\n`@photon-ai\u002Fimessage-kit` 是一个专为 **macOS** 设计的类型安全、优雅的 iMessage SDK。支持读取、发送和自动化处理 iMessage 对话，适用于构建 AI Agent、自动化工具及聊天优先的应用程序。\n\n> **注意**：本工具仅支持 macOS 系统。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n1.  **操作系统**：macOS\n2.  **运行环境**：Node.js 或 Bun\n3.  **关键权限**：必须授予 IDE 或终端 **完全磁盘访问权限 (Full Disk Access)**，以便读取聊天记录和执行自动化任务。\n\n### 配置完全磁盘访问权限\n\n1.  打开 **系统设置 → 隐私与安全性 → 完全磁盘访问权限**。\n2.  点击 **\"+\"** 按钮。\n3.  添加您的开发工具（例如 Cursor, VS Code, Terminal, Warp 等）。\n\n## 安装步骤\n\n根据您的包管理器选择以下命令进行安装：\n\n```bash\n# 使用 Bun 安装（零依赖）\nbun add @photon-ai\u002Fimessage-kit\n\n# 使用 Node.js 安装（需要 better-sqlite3）\nnpm install @photon-ai\u002Fimessage-kit better-sqlite3\n```\n\n## 基本使用\n\n初始化 SDK 后即可发送消息或查询历史记录。以下是发送文本消息的最简示例：\n\n```typescript\nimport { IMessageSDK } from '@photon-ai\u002Fimessage-kit'\n\nconst sdk = new IMessageSDK()\n\n\u002F\u002F 发送消息\nawait sdk.send('+1234567890', 'Hello from iMessage Kit!')\n\n\u002F\u002F 清理资源\nawait sdk.close()\n```\n\n### 进阶配置\n\n如需启用调试日志或自定义数据库路径，可在初始化时传入配置对象：\n\n```typescript\nconst sdk = new IMessageSDK({\n    debug: true,\n    databasePath: '\u002Fcustom\u002Fpath\u002Fdatabase.db'\n})\n```\n\n更多功能（如发送图片、文件、实时监听、定时消息等）请参考官方文档中的详细示例。","某电商运营团队希望构建一个自动化系统，在订单发货后即时通过 iMessage 通知客户，并能自动处理客户的确认回复与售后咨询。\n\n### 没有 imessage-kit 时\n- 客服人员需手动登录手机或 Mac 客户端，逐条复制订单信息发送，耗时且极易出现错发漏发。\n- 无法实时监控客户回复，导致大量“收到货了吗”等咨询被淹没在聊天记录中，响应滞后。\n- 若要编写脚本控制，需深入理解 AppleScript 底层逻辑，配置环境复杂且依赖库经常冲突。\n- 缺乏统一接口管理发送状态，难以追踪哪些消息已成功送达、已读或发送失败。\n\n### 使用 imessage-kit 后\n- 利用批量发送功能，系统可一次性调用 API 向数百个客户推送包含物流单号的图文消息，效率提升百倍。\n- 通过实时监听机制自动捕获新消息，直接触发预设的自动回复逻辑，无需人工介入即可闭环处理。\n- 类型安全的 TypeScript 接口简化了开发，轻松查询历史对话并同步至内部 CRM 系统，数据更规范。\n- 零依赖架构降低了部署难度，配合内置的错误处理插件确保消息发送失败时能自动重试，稳定性更强。\n\nimessage-kit 将原本依赖人工值守的沟通工作转变为稳定可靠的代码驱动自动化流程。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fphoton-hq_imessage-kit_8b4e3b1e.png","photon-hq","Photon","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fphoton-hq_9ca8205f.png","We bring agents to millions of lives.",null,"hi@something.surf","photon_hq","https:\u002F\u002Fphoton.codes","https:\u002F\u002Fgithub.com\u002Fphoton-hq",[85],{"name":86,"color":87,"percentage":88},"TypeScript","#3178c6",100,1231,116,"2026-04-04T20:25:33","MIT","macOS","未说明",{"notes":96,"python":94,"dependencies":97},"仅支持 macOS 操作系统（iMessage 为苹果专有协议）；首次运行需在系统隐私设置中授予 IDE 或终端‘完全磁盘访问权限’；依赖 Node.js 或 Bun 作为运行时环境；项目基于 TypeScript 开发。",[98,86,99,100],"better-sqlite3","Node.js","Bun",[14,15,13],[103,104,105,106,107,108],"ai","apple","imessage","typescript","agent","sms","2026-03-27T02:49:30.150509","2026-04-06T07:05:51.849222",[112,117,121,126,130,135],{"id":113,"question_zh":114,"answer_zh":115,"source_url":116},2222,"为什么使用 SDK 获取的消息中 `text` 字段有时为 null？","SDK 优先读取 `message.text`，若该字段为空，则会尝试解码 `attributedBody` BLOB 以提取可读文本。出现 null 通常是因为解码逻辑与当前 macOS 版本或数据库结构不匹配。此问题已在 PR#18 中修复。","https:\u002F\u002Fgithub.com\u002Fphoton-hq\u002Fimessage-kit\u002Fissues\u002F16",{"id":118,"question_zh":119,"answer_zh":120,"source_url":116},2223,"如何排查和验证本地 iMessage 数据库的消息解码问题？","可以通过运行项目提供的调试脚本来验证。首先运行 `npx tsx check-db.ts` 检查 SDK 行为，然后运行 `npx tsx test-db-wo-sdk.ts` 对比手动解码结果（使用 `decodeAttributeBodyHeuristic` 函数）。这有助于确认是 SDK 问题还是本地数据库配置问题。",{"id":122,"question_zh":123,"answer_zh":124,"source_url":125},2224,"SDK 如何防止通过文件路径注入 AppleScript？","SDK 在生成 AppleScript 代码发送附件前，会使用 `escapeAppleScriptString()` 函数对文件路径、文件名、收件人及 Chat ID 进行转义。这确保了特殊字符（如引号、换行符、控制字符）被正确处理，防止突破字符串上下文导致命令注入。","https:\u002F\u002Fgithub.com\u002Fphoton-hq\u002Fimessage-kit\u002Fissues\u002F23",{"id":127,"question_zh":128,"answer_zh":129,"source_url":125},2225,"SDK 在处理附件图片转换时如何避免 Shell 插值风险？","为了消除 Shell 插值风险，SDK 已将 `sips` 等工具的调用从 `exec` 替换为 `execFile`。这避免了将用户输入直接拼接到 Shell 命令字符串中，从而防止恶意输入导致任意命令执行。",{"id":131,"question_zh":132,"answer_zh":133,"source_url":134},2226,"SDK 如何解决临时文件目录下的符号链接（Symlink）攻击风险？","SDK 不再使用可预测的临时文件名（如 `imsg_temp_\u003Ctimestamp>`），并改进了文件复制逻辑。这防止了攻击者在 `~\u002FPictures` 目录下创建同名符号链接，从而避免覆盖敏感文件或绕过沙盒限制。","https:\u002F\u002Fgithub.com\u002Fphoton-hq\u002Fimessage-kit\u002Fissues\u002F31",{"id":136,"question_zh":137,"answer_zh":138,"source_url":134},2227,"SDK 在清理临时文件时采取了哪些安全措施？","之前的清理逻辑可能使用 `unlinkSync` 删除任何匹配名称的文件，存在误删风险。修复后的代码优化了清理行为，确保仅删除预期的临时文件，避免因竞争条件（TOCTOU）导致的意外文件操作。",[140,145,150,155,160,165,170,175,180,185,190],{"id":141,"version":142,"summary_zh":143,"released_at":144},101746,"v2.1.2","## Changes since v2.1.1\n\n- 2.1.2 (63fe172)\n- Merge pull request #37 from photon-hq\u002Ffix\u002Fremove-os-restriction-for-ci (1ba113e)\n- fix 🐛: remove os restriction to allow installation on non-macOS for type checking (691bd4a)\n- Merge pull request #36 from photon-hq\u002Frelease\u002Fv2.1.1 (28c9dda)\n**Build Info:**\n- Version: v2.1.2\n- Build Date: 2026-01-22 11:55:48 UTC\n- Git Hash: 63fe172\n","2026-01-22T11:56:02",{"id":146,"version":147,"summary_zh":148,"released_at":149},101747,"v2.1.1","## Changes since v2.1.0\n\n- 2.1.1 (2c8590e)\n- Merge pull request #35 from xoba\u002Fmain (f9ef56e)\n- docs: add detailed docstring for buildTempFilenameTemplate (7a592b4)\n- style: format chain methods per biome rules (15fb60d)\n- test: update expectations for sanitized temp filename template (c5f809d)\n- Preserve attachment extension in temp files (fixes photon-hq\u002Fimessage-kit#34) (ae53efc)\n- Merge pull request #32 from photon-hq\u002Ffix\u002Feng-461-symlink-toctou-security (be47805)\n- refactor(security) ♻️: enhance mktemp entropy and simplify file type checks (3a3f209)\n- fix(security) 🐛: prevent symlink\u002FTOCTOU attacks on temp files (4b5b876)\n- Merge pull request #30 from photon-hq\u002Frelease\u002Fv2.1.0 (77e218e)\n**Build Info:**\n- Version: v2.1.1\n- Build Date: 2026-01-13 03:48:53 UTC\n- Git Hash: 2c8590e\n","2026-01-13T03:49:08",{"id":151,"version":152,"summary_zh":153,"released_at":154},101748,"v2.1.0","## Changes since v2.0.2\n\n- 2.1.0 (9bd1e28)\n- Merge pull request #29 from photon-hq\u002Ffeat\u002Feng-433-reaction-detection (6715e84)\n- refactor ♻️: improve mapReactionType validation and add tests (dee3601)\n- feat ✨: add tapback reaction detection support (41a34d0)\n- Merge pull request #28 from photon-hq\u002Ffeat\u002Feng-441-github-templates-and-workflows (881c228)\n- feat ✨: add close information (91e9b09)\n- feat ✨: add GitHub issue templates and security workflows (4e04b27)\n- Merge pull request #25 from photon-hq\u002Frelease\u002Fv2.0.2 (f0b99c4)\n**Build Info:**\n- Version: v2.1.0\n- Build Date: 2025-12-18 10:13:09 UTC\n- Git Hash: 9bd1e28\n","2025-12-18T10:13:28",{"id":156,"version":157,"summary_zh":158,"released_at":159},101749,"v2.0.2","## Changes since v2.0.1\n\n- 2.0.2 (a911bf3)\n- Merge pull request #24 from photon-hq\u002Ffix\u002Feng-423-apple-shell-injection (b47c689)\n- fix 🐛: lint in security injection tests (a995d19)\n- fix 🐛: AppleScript and shell injection vulnerabilities (c00a98f)\n- Merge pull request #22 from photon-hq\u002Ffix\u002Ftruncated-imessage-text (c7ecd0c)\n- chore 🔥: sync package-lock for better-sqlite3 12.5.0 (b33724a)\n- fix 🐛:truncated iMessage history text by preferring attributedBody (fcaf84a)\n- Merge pull request #21 from photon-hq\u002Fdocs\u002Freadme-context7 (11584ce)\n- feat ✨: add context7 docs link (66cd01d)\n- 📝 docs: add Context7 MCP usage (e199425)\n- Merge pull request #20 from photon-hq\u002Fdocs\u002Freadme-llms-guide (7718712)\n- docs 📝: refresh README and add llms.txt for LLMs (536680f)\n- Merge pull request #19 from photon-hq\u002Ffeature\u002Fmessage-scheduler-hardening (3fbd1d9)\n- fix 🐛:demo lint (af87417)\n- chore 🔥: polish reminders helpers and scheduler examples (b2a1ff0)\n- fix 🐛: prevent lost scheduled messages and reminders leaks (3958a10)\n- Merge pull request #18 from photon-hq\u002Ffix\u002Fattributed-body-node-typedstream (99b49b9)\n- fix 🐛: update package-lock.json with node-typedstream (2534192)\n- feat ✨:update test (55ec1e0)\n- fix 🐛: decode attributedBody via node-typedstream (f2396de)\n- Completed message scheduler impl. (c1de570)\n- Merge pull request #15 from photon-hq\u002Frelease\u002Fv2.0.1 (c7650d3)\n**Build Info:**\n- Version: v2.0.2\n- Build Date: 2025-12-15 02:26:47 UTC\n- Git Hash: a911bf3\n","2025-12-15T02:27:02",{"id":161,"version":162,"summary_zh":163,"released_at":164},101750,"v2.0.1","## Changes since v2.0.0\n\n- 2.0.1 (0130977)\n- Merge pull request #14 from photon-hq\u002Ffix\u002Fsmart-quotes-short-messages (2f42619)\n- fix 🐛:update regular expressions to be stricter (5e72ff3)\n- fix 🐛: attributedBody text extraction for smart quotes and short messages (2644d06)\n- Merge pull request #12 from photon-hq\u002Fcopilot\u002Fchange-sspl-to-mit-license (e52456a)\n- Minimize package-lock.json changes to only security-related updates (3ba07b9)\n- Fix security audit issue by adding glob override (ab59c4f)\n- Change license from SSPL to MIT (1a54281)\n- Initial plan for license change from SSPL to MIT (0bd5b3b)\n- Initial plan (558b7ec)\n- Merge pull request #11 from photon-hq\u002Fdanieltyx-patch-2 (b8a9a9e)\n- Fix contact email in README for advanced features (333efd1)\n- Merge pull request #10 from photon-hq\u002Frelease\u002Fv2.0.0 (312201e)\n**Build Info:**\n- Version: v2.0.1\n- Build Date: 2025-11-28 11:18:48 UTC\n- Git Hash: 0130977\n","2025-11-28T11:19:00",{"id":166,"version":167,"summary_zh":168,"released_at":169},101751,"v2.0.0","## Changes since v1.1.3\n\n- 2.0.0 (8b2489b)\n- Merge pull request #9 from photon-hq\u002Ffeat\u002Fintuitive-api-design (d752c14)\n- fix : improve type safety and add configurable options (ce95888)\n- feat: implement reliable message sending with database confirmation (5116f7b)\n- feat: add message search and attachment helpers (fbf730e)\n- feat: enhance listChats with filtering and sorting options (26ce4bb)\n- perf: optimize getUnreadMessages to avoid redundant total calculation (4c5bb3b)\n- refactor: improve watcher callback naming for clarity (3959f96)\n- refactor: simplify sender logic and improve error handling (be9998f)\n- Merge pull request #6 from photon-hq\u002Fcopilot\u002Ffix-readme-syntax-issue (c9afc94)\n- Merge remote-tracking branch 'origin\u002Fmain' into copilot\u002Ffix-readme-syntax-issue (feb2db9)\n- Merge pull request #8 from photon-hq\u002Funderthestars-zhy-patch-1 (717317e)\n- Import promisify for async execution of commands (6443e3d)\n- Fix README markdown syntax errors (1c96e6f)\n- Initial plan (5d38ad9)\n- Merge pull request #4 from photon-hq\u002Ffix\u002Fgroup-chat-response-behavior (ed0821f)\n- Merge branch 'main' into fix\u002Fgroup-chat-response-behavior (81497ba)\n- Merge pull request #5 from photon-hq\u002Ffix\u002Fattributed-body-text-null (f7df561)\n- test : add attributedBody column to mock database (7ae855b)\n- fix 🐛: extract text from attributedBody when text field is null (0db63fd)\n- fix 🐛: improve group chatId validation for AppleScript format (07199a8)\n- fix 🐛: group chat response routing; codify chatId rules (5a32a88)\n- chore(release) 🔥: upload single npm tarball via npm pack (343f6aa)\n**Build Info:**\n- Version: v2.0.0\n- Build Date: 2025-11-11 05:33:08 UTC\n- Git Hash: 8b2489b\n","2025-11-11T05:33:27",{"id":171,"version":172,"summary_zh":173,"released_at":174},101752,"v1.1.3","## Changes since v1.1.2\n\n- 1.1.3 (c689508)\n- docs(readme) 📝: add Discord community badge (153ff31)\n- Revise README for advanced features and contact info (58f15ac)\n**Build Info:**\n- Version: v1.1.3\n- Build Date: 2025-11-05 11:18:15 UTC\n- Git Hash: c689508\n","2025-11-05T11:18:26",{"id":176,"version":177,"summary_zh":178,"released_at":179},101753,"v1.1.2","## Changes since v1.1.1\n\n- 1.1.2 (575b09e)\n- fix(package) 🐛: correct repository URL in package.json (0028bec)\n**Build Info:**\n- Version: v1.1.2\n- Build Date: 2025-11-03 07:17:05 UTC\n- Git Hash: 575b09e\n","2025-11-03T07:17:19",{"id":181,"version":182,"summary_zh":183,"released_at":184},101754,"v1.1.0","## 🎉 What's New\r\n\r\nAdded comprehensive file sending capabilities to send any file type through iMessage, including PDFs, contact cards, spreadsheets, and more.\r\n\r\n### ✨ New Features\r\n\r\n- **File Sending API**: Send any file type with `files` parameter\r\n- **Convenience Methods**: `sendFile()` and `sendFiles()` for quick file sharing\r\n- **Mix Files & Images**: Combine images and files in a single message\r\n- **Universal Support**: PDF, VCF, CSV, DOC, ZIP, and all macOS Messages-supported formats\r\n\r\n### 📝 Examples\r\n\r\n```typescript\r\n\u002F\u002F Send files\r\nawait sdk.send('+1234567890', { \r\n  files: ['document.pdf', 'contact.vcf', 'data.csv'] \r\n})\r\n\r\n\u002F\u002F Convenience methods\r\nawait sdk.sendFile('+1234567890', '\u002Fpath\u002Fto\u002Ffile.pdf', 'Here is the document')\r\nawait sdk.sendFiles('+1234567890', ['\u002Ffile1.pdf', '\u002Ffile2.csv'])\r\n\r\n\u002F\u002F Mix images and files\r\nawait sdk.send('+1234567890', {\r\n  text: 'Project files',\r\n  images: ['screenshot.png'],\r\n  files: ['report.pdf']\r\n})\r\n```\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fsg-hq\u002Fimessage-kit\u002Fcompare\u002Fv1.0.7...v1.1.0","2025-10-30T07:28:46",{"id":186,"version":187,"summary_zh":188,"released_at":189},101755,"1.0.7","Refactored type system to use `IMessage` namespace for better organization and IDE support. \r\nAll types (Config, Message, Attachment, etc.) are now accessed via `IMessage.*` instead of direct exports. \r\nUpdated documentation and optimized banner image.","2025-10-28T00:57:54",{"id":191,"version":192,"summary_zh":193,"released_at":194},101756,"v1.0.5","## 🎉 What's New\r\n\r\n### ✨ Features\r\n- **Message Type Separation**: Split individual messages and group messages for better handling\r\n  - `onNewMessage` callback now receives only 1-on-1 direct messages\r\n  - `onGroupMessage` callback for dedicated group chat message handling\r\n  - Improved message routing logic for different chat types\r\n\r\n### 🐛 Bug Fixes\r\n- **DND Mode Fix**: Fixed critical issue where messages were lost when device was in Do Not Disturb mode\r\n  - Watcher now uses timestamp-based detection instead of read status\r\n  - Ensures all messages are captured regardless of notification settings\r\n\r\n---\r\n\r\n## 📦 Installation\r\n\r\n```bash\r\n# For Bun\r\nbun add @photon-ai\u002Fimessage-kit\r\n\r\n# For Node.js\r\nnpm install @photon-ai\u002Fimessage-kit better-sqlite3\r\n```\r\n\r\n## 🔗 Links\r\n- [npm Package](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@photon-ai\u002Fimessage-kit)\r\n- [Documentation](https:\u002F\u002Fgithub.com\u002Fsg-hq\u002Fimessage-kit#readme)\r\n- [Report Issues](https:\u002F\u002Fgithub.com\u002Fsg-hq\u002Fimessage-kit\u002Fissues)","2025-10-25T07:41:02"]