[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-mihaelamj--cupertino":3,"tool-mihaelamj--cupertino":64},[4,23,32,40,48,56],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":22},2268,"ML-For-Beginners","microsoft\u002FML-For-Beginners","ML-For-Beginners 是由微软推出的一套系统化机器学习入门课程，旨在帮助零基础用户轻松掌握经典机器学习知识。这套课程将学习路径规划为 12 周，包含 26 节精炼课程和 52 道配套测验，内容涵盖从基础概念到实际应用的完整流程，有效解决了初学者面对庞大知识体系时无从下手、缺乏结构化指导的痛点。\n\n无论是希望转型的开发者、需要补充算法背景的研究人员，还是对人工智能充满好奇的普通爱好者，都能从中受益。课程不仅提供了清晰的理论讲解，还强调动手实践，让用户在循序渐进中建立扎实的技能基础。其独特的亮点在于强大的多语言支持，通过自动化机制提供了包括简体中文在内的 50 多种语言版本，极大地降低了全球不同背景用户的学习门槛。此外，项目采用开源协作模式，社区活跃且内容持续更新，确保学习者能获取前沿且准确的技术资讯。如果你正寻找一条清晰、友好且专业的机器学习入门之路，ML-For-Beginners 将是理想的起点。",84991,2,"2026-04-05T10:45:23",[13,14,15,16,17,18,19,20,21],"图像","数据工具","视频","插件","Agent","其他","语言模型","开发框架","音频","ready",{"id":24,"name":25,"github_repo":26,"description_zh":27,"stars":28,"difficulty_score":29,"last_commit_at":30,"category_tags":31,"status":22},2181,"OpenHands","OpenHands\u002FOpenHands","OpenHands 是一个专注于 AI 驱动开发的开源平台，旨在让智能体（Agent）像人类开发者一样理解、编写和调试代码。它解决了传统编程中重复性劳动多、环境配置复杂以及人机协作效率低等痛点，通过自动化流程显著提升开发速度。\n\n无论是希望提升编码效率的软件工程师、探索智能体技术的研究人员，还是需要快速原型验证的技术团队，都能从中受益。OpenHands 提供了灵活多样的使用方式：既可以通过命令行（CLI）或本地图形界面在个人电脑上轻松上手，体验类似 Devin 的流畅交互；也能利用其强大的 Python SDK 自定义智能体逻辑，甚至在云端大规模部署上千个智能体并行工作。\n\n其核心技术亮点在于模块化的软件智能体 SDK，这不仅构成了平台的引擎，还支持高度可组合的开发模式。此外，OpenHands 在 SWE-bench 基准测试中取得了 77.6% 的优异成绩，证明了其解决真实世界软件工程问题的能力。平台还具备完善的企业级功能，支持与 Slack、Jira 等工具集成，并提供细粒度的权限管理，适合从个人开发者到大型企业的各类用户场景。",70612,3,"2026-04-05T11:12:22",[19,17,20,16],{"id":33,"name":34,"github_repo":35,"description_zh":36,"stars":37,"difficulty_score":10,"last_commit_at":38,"category_tags":39,"status":22},3074,"gpt4free","xtekky\u002Fgpt4free","gpt4free 是一个由社区驱动的开源项目，旨在聚合多种可访问的大型语言模型（LLM）和媒体生成接口，让用户能更灵活、便捷地使用前沿 AI 能力。它解决了直接调用各类模型时面临的接口分散、门槛高或成本昂贵等痛点，通过统一的标准将不同提供商的资源整合在一起。\n\n无论是希望快速集成 AI 功能的开发者、需要多模型对比测试的研究人员，还是想免费体验最新技术的普通用户，都能从中受益。gpt4free 提供了丰富的使用方式：既包含易于上手的 Python 和 JavaScript 客户端库，也支持部署本地图形界面（GUI），更提供了兼容 OpenAI 标准的 REST API，方便无缝替换现有应用后端。\n\n其技术亮点在于强大的多提供商支持架构，能够动态调度包括 Opus、Gemini、DeepSeek 等多种主流模型资源，并支持 Docker 一键部署及本地推理。项目秉持社区优先原则，在降低使用门槛的同时，也为贡献者提供了扩展新接口的便利框架，是探索和利用多样化 AI 资源的实用工具。",65970,"2026-04-04T01:02:03",[16,19,17],{"id":41,"name":42,"github_repo":43,"description_zh":44,"stars":45,"difficulty_score":10,"last_commit_at":46,"category_tags":47,"status":22},51,"gstack","garrytan\u002Fgstack","gstack 是 Y Combinator CEO Garry Tan 亲自开源的一套 AI 工程化配置，旨在将 Claude Code 升级为你的虚拟工程团队。面对单人开发难以兼顾产品战略、架构设计、代码审查及质量测试的挑战，gstack 提供了一套标准化解决方案，帮助开发者实现堪比二十人团队的高效产出。\n\n这套配置特别适合希望提升交付效率的创始人、技术负责人，以及初次尝试 Claude Code 的开发者。gstack 的核心亮点在于内置了 15 个具有明确职责的 AI 角色工具，涵盖 CEO、设计师、工程经理、QA 等职能。用户只需通过简单的斜杠命令（如 `\u002Freview` 进行代码审查、`\u002Fqa` 执行测试、`\u002Fplan-ceo-review` 规划功能），即可自动化处理从需求分析到部署上线的全链路任务。\n\n所有操作基于 Markdown 和斜杠命令，无需复杂配置，完全免费且遵循 MIT 协议。gstack 不仅是一套工具集，更是一种现代化的软件工厂实践，让单人开发者也能拥有严谨的工程流程。",64261,"2026-04-05T11:08:43",[17,16],{"id":49,"name":50,"github_repo":51,"description_zh":52,"stars":53,"difficulty_score":10,"last_commit_at":54,"category_tags":55,"status":22},193,"meilisearch","meilisearch\u002Fmeilisearch","Meilisearch 是一个开源的极速搜索服务，专为现代应用和网站打造，开箱即用。它能帮助开发者快速集成高质量的搜索功能，无需复杂的配置或额外的数据预处理。传统搜索方案往往需要大量调优才能实现准确结果，而 Meilisearch 内置了拼写容错、同义词识别、即时响应等实用特性，并支持 AI 驱动的混合搜索（结合关键词与语义理解），显著提升用户查找信息的体验。\n\nMeilisearch 特别适合 Web 开发者、产品团队或初创公司使用，尤其适用于需要快速上线搜索功能的场景，如电商网站、内容平台或 SaaS 应用。它提供简洁的 RESTful API 和多种语言 SDK，部署简单，资源占用低，本地开发或生产环境均可轻松运行。对于希望在不依赖大型云服务的前提下，为用户提供流畅、智能搜索体验的团队来说，Meilisearch 是一个高效且友好的选择。",56964,"2026-04-05T08:19:14",[13,17,14,20,16,18],{"id":57,"name":58,"github_repo":59,"description_zh":60,"stars":61,"difficulty_score":10,"last_commit_at":62,"category_tags":63,"status":22},4022,"awesome-claude-skills","ComposioHQ\u002Fawesome-claude-skills","awesome-claude-skills 是一个精心整理的开源资源库，旨在帮助用户挖掘和扩展 Claude AI 的潜力。它不仅仅是一份列表，更提供了实用的“技能（Skills）”模块，让 Claude 从单纯的文本生成助手，进化为能执行复杂工作流的智能代理。\n\n许多用户在使用 AI 时，常受限于其无法直接操作外部软件或处理特定格式文件的痛点。awesome-claude-skills 通过预设的工作流解决了这一问题：它不仅能教会 Claude 专业地处理 Word、PDF 等文档，进行代码开发与数据分析，还能借助 Composio 插件连接 Slack、邮箱及数百种常用应用，实现发送邮件、创建任务等自动化操作。这使得重复性任务变得标准化且可复用，极大提升了工作效率。\n\n无论是希望优化日常办公流程的普通用户、需要处理复杂文档的研究人员，还是寻求将 AI 深度集成到开发管线中的开发者，都能从中找到适合的解决方案。其独特的技术亮点在于“技能”的可定制性与强大的应用连接能力，让用户无需编写复杂代码，即可通过简单的配置让 Claude 具备跨平台执行真实任务的能力。如果你希望让 Claude",51312,"2026-04-05T19:04:23",[17,16],{"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":80,"owner_email":81,"owner_twitter":79,"owner_website":82,"owner_url":83,"languages":84,"stars":97,"forks":98,"last_commit_at":99,"license":100,"difficulty_score":10,"env_os":101,"env_gpu":102,"env_ram":103,"env_deps":104,"category_tags":111,"github_topics":112,"view_count":10,"oss_zip_url":79,"oss_zip_packed_at":79,"status":22,"created_at":125,"updated_at":126,"faqs":127,"releases":159},2711,"mihaelamj\u002Fcupertino","cupertino","A local Apple Documentation crawler and MCP server. Written in Swift.","Cupertino 是一款专为苹果生态打造的本地文档爬虫与 MCP 服务器，由 Swift 语言编写。它能自动抓取并索引 Apple Developer 官方文档、Swift 演进提案、人机交互指南及各类代码示例，将其整合为可离线访问的结构化知识库。\n\n这款工具主要解决了 AI 助手在回答苹果技术问题时容易“产生幻觉”或提供过时信息的痛点。通过为 AI 代理提供准确、实时且本地的权威文档源，Cupertino 确保了开发建议的可靠性。同时，它支持完全离线运行，让开发者在无网络环境下也能拥有完整的文档查询能力，并实现了搜索结果的高度确定性。\n\nCupertino 特别适合 iOS、macOS 等苹果平台的开发者，以及希望将精准苹果文档集成到本地 AI 工作流中的研究人员。其核心技术亮点在于构建了基于 SQLite FTS5 和 BM25 算法的高速搜索引擎，并通过模型上下文协议（MCP）无缝对接 Claude 等主流 AI 助手。用户只需简单配置，即可让 AI 直接读取超过 30 万个文档页面，涵盖 300 多个框架，从而大幅提升编码效率与技术查询的准确度。","# 🍎📚 Cupertino\n\n**Apple Documentation Crawler & MCP Server**\n\nA Swift-based tool to crawl, index, and serve Apple's developer documentation to AI agents via the Model Context Protocol (MCP).\n\n[![Swift 6.2+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSwift-6.2+-orange.svg)](https:\u002F\u002Fswift.org)\n[![macOS 15+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FmacOS-15+-blue.svg)](https:\u002F\u002Fwww.apple.com\u002Fmacos)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green.svg)](LICENSE)\n[![PulseMCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPulseMCP-listed-blue)](https:\u002F\u002Fwww.pulsemcp.com\u002Fservers\u002Fmihaelamj-cupertino)\n[![LobeHub](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLobeHub-listed-purple)](https:\u002F\u002Flobehub.com\u002Fmcp\u002Fmihaelamj-cupertino)\n\n![Cupertino Demo](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmihaelamj_cupertino_readme_3c05ed6560ff.gif)\n\n## What is Cupertino?\n\nCupertino is a local, structured, AI-ready documentation system for Apple platforms. It:\n\n- **Crawls** Apple Developer documentation, Swift.org, Swift Evolution proposals, Human Interface Guidelines, Apple Archive legacy guides, and Swift package metadata\n- **Indexes** everything into a fast, searchable SQLite FTS5 database with BM25 ranking\n- **Serves** documentation to AI agents like Claude via the Model Context Protocol\n- **Provides** offline access to 302,424+ documentation pages across 307 frameworks\n\n### Why Build This?\n\n- **No more hallucinations**: AI agents get accurate, up-to-date Apple API documentation\n- **Offline development**: Work with full documentation without internet access\n- **Deterministic search**: Same query always returns same results\n- **Local control**: Own your documentation, inspect the database, script workflows\n- **AI-first design**: Built specifically for AI agent integration via MCP\n\n## Quick Start\n\n> **Note:** When building from source, commands must be run from the `Packages` directory. The one-command install works from anywhere.\n\n### Requirements\n\n- macOS 15+ (Sequoia)\n- ~2-3 GB disk space for full documentation\n\n*Building from source additionally requires Swift 6.2+ and Xcode 16.0+*\n\n### Installation\n\n**One-command install (recommended):**\n\n```bash\nbash \u003C(curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmihaelamj\u002Fcupertino\u002Fmain\u002Finstall.sh)\n```\n\nThis downloads a pre-built, signed, and notarized universal binary, installs it to `\u002Fusr\u002Flocal\u002Fbin`, and downloads the documentation databases.\n\n**Or with Homebrew:**\n\n```bash\nbrew tap mihaelamj\u002Ftap\nbrew install cupertino\ncupertino setup\n```\n\n**Or build from source:**\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\ncd cupertino\n\n# Using Makefile (recommended)\nmake build                       # Build release binary\nsudo make install                # Install to \u002Fusr\u002Flocal\u002Fbin\n\n# Or using Swift Package Manager directly\ncd Packages\nswift build -c release\nsudo ln -sf \"$(pwd)\u002F.build\u002Frelease\u002Fcupertino\" \u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\n```\n\n**Demo Video:** [Watch on YouTube](https:\u002F\u002Fyoutu.be\u002FB-mRdainTMA)\n\n### Quick Reference\n\n```bash\n# Quick Setup (Recommended) - download pre-built databases (~30 seconds)\ncupertino setup                      # Download databases from GitHub\ncupertino serve                      # Start MCP server\n\n# Alternative: Build from GitHub (~45 minutes)\ncupertino save --remote              # Stream and build locally\n\n# Or fetch documentation yourself\ncupertino fetch --type docs          # Apple Developer Documentation\ncupertino fetch --type swift         # Swift.org documentation\ncupertino fetch --type evolution     # Swift Evolution proposals\ncupertino fetch --type packages      # Swift package metadata\ncupertino fetch --type package-docs  # Swift package READMEs\ncupertino fetch --type code          # Sample code from Apple (requires auth)\ncupertino fetch --type samples       # Sample code from GitHub (recommended)\ncupertino fetch --type archive       # Apple Archive programming guides\ncupertino fetch --type hig           # Human Interface Guidelines\ncupertino fetch --type availability  # Platform availability data\ncupertino fetch --type all           # All types in parallel\n\n# Build indexes\ncupertino save                       # Build documentation search index (from local files)\ncupertino save --remote              # Build from GitHub (no local files needed)\ncupertino index                      # Index sample code for search\n\n# Start server\ncupertino                            # Start MCP server (default command)\ncupertino serve                      # Start MCP server (explicit)\n```\n\n### Instant Setup (Recommended)\n\n```bash\n# Download pre-built databases from GitHub (~30 seconds)\ncupertino setup\n\n# Start MCP server\ncupertino serve\n```\n\n### Alternative: Build from GitHub\n\n```bash\n# Stream and build locally (~45 minutes)\n# Use this if you want to build the database yourself\ncupertino save --remote\n\n# Start MCP server\ncupertino serve\n```\n\n### Manual Setup (Advanced)\n\n```bash\n# Download Apple documentation (~12+ days for 301,000+ pages)\n# Takes time due to 0.05s default delay between requests\ncupertino fetch --type docs --max-pages 15000\n\n# Download Swift Evolution proposals (~2-5 minutes)\ncupertino fetch --type evolution\n\n# Download sample code from GitHub (~4 minutes, 606 projects)\ncupertino fetch --type samples\n\n# Build search index (~2-5 minutes)\ncupertino save\n```\n\n### Use with Claude Desktop\n\n1. **Configure Claude Desktop** - Edit `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n> **Note:** Use `\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino` for Homebrew on Apple Silicon, `\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino` for Intel or manual install. Run `which cupertino` to find your path.\n\n2. **Restart Claude Desktop**\n\n3. **Ask Claude about Apple APIs:**\n   - \"Search for SwiftUI documentation\"\n   - \"What does Swift Evolution proposal SE-0001 propose?\"\n   - \"List available frameworks\"\n\n### Use with Claude Code\n\nIf you're using [Claude Code](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Foverview), you can add Cupertino as an MCP server with a single command:\n\n```bash\nclaude mcp add cupertino --scope user -- $(which cupertino)\n```\n\nThis registers Cupertino globally for all your projects. Claude Code will automatically have access to Apple documentation search.\n\n### Use with OpenAI Codex\n\nIf you're using [OpenAI Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex), add Cupertino with:\n\n```bash\ncodex mcp add cupertino -- $(which cupertino) serve\n```\n\nOr add directly to `~\u002F.codex\u002Fconfig.toml`:\n\n```toml\n[mcp_servers.cupertino]\ncommand = \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\"  # Homebrew on Apple Silicon\n# command = \"\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\"   # Intel Mac or manual install\nargs = [\"serve\"]\n```\n\n> **Tip:** Run `which cupertino` to find your installation path.\n\n### Use with Cursor\n\nAdd to `.cursor\u002Fmcp.json` in your project (or `~\u002F.cursor\u002Fmcp.json` for global access):\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Use with VS Code (GitHub Copilot)\n\nAdd to `.vscode\u002Fmcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"cupertino\": {\n      \"type\": \"stdio\",\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Use with Zed\n\nAdd to your Zed `settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Use with Windsurf\n\nAdd to `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### Use with opencode\n\nAdd to `opencode.jsonc`:\n\n```json\n{\n  \"mcp\": {\n    \"cupertino\": {\n      \"type\": \"local\",\n      \"command\": [\"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\", \"serve\"]\n    }\n  }\n}\n```\n\n> **Note:** All examples use `\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino` (Homebrew on Apple Silicon). Use `\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino` for Intel Macs or manual installs. Run `which cupertino` to find your path.\n\n### Use as an Agent Skill (No Server Required)\n\nCupertino can also be used as a stateless CLI skill without running an MCP server. This is useful for agents that support the [Agent Skills](https:\u002F\u002Fagentskills.io) specification.\n\n**Prerequisites:**\n\nInstall cupertino and download the databases first:\n```bash\n# Install via Homebrew or from source (see Installation above)\ncupertino setup\n```\n\n**Option A: Install with OpenSkills (Recommended)**\n\n[OpenSkills](https:\u002F\u002Fgithub.com\u002Fnumman-ali\u002Fopenskills) is a universal skills loader that works with Claude Code, Cursor, Windsurf, Aider, and other AI coding agents.\n\n```bash\n# Install the cupertino skill from GitHub\nnpx openskills install mihaelamj\u002Fcupertino\n\n# Sync to update AGENTS.md\nnpx openskills sync\n```\n\nFor global installation (available in all projects):\n```bash\nnpx openskills install mihaelamj\u002Fcupertino --global\n```\n\nFor multi-agent setups (installs to `.agent\u002Fskills\u002F` instead of `.claude\u002Fskills\u002F`):\n```bash\nnpx openskills install mihaelamj\u002Fcupertino --universal\n```\n\n**Option B: Install as a Claude Code Plugin**\n\nInside a Claude Code session, add the cupertino marketplace:\n```\n\u002Fplugin marketplace add mihaelamj\u002Fcupertino\n```\n\nThen enable the plugin from the marketplace.\n\n**Option C: Manual Installation**\n\nCopy the skill definition to your project or global skills directory:\n```bash\n# Clone this repo\ngit clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\n\n# For a single project\nmkdir -p .claude\u002Fskills\u002Fcupertino\ncp cupertino\u002Fskills\u002Fcupertino\u002FSKILL.md .claude\u002Fskills\u002Fcupertino\u002F\n\n# Or for global use with Claude Code\nmkdir -p ~\u002F.claude\u002Fskills\u002Fcupertino\ncp cupertino\u002Fskills\u002Fcupertino\u002FSKILL.md ~\u002F.claude\u002Fskills\u002Fcupertino\u002F\n```\n\n**How It Works:**\n\nThe skill uses the CLI directly with JSON output, no server process needed:\n\n```bash\n# Search documentation\ncupertino search \"SwiftUI View\" --format json\n\n# Filter by source\ncupertino search \"NavigationStack\" --source apple-docs --format json\ncupertino search \"button styles\" --source samples --format json\n\n# Read a document\ncupertino read \"apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_view\" --format json\n\n# List frameworks\ncupertino list-frameworks --format json\n\n# List sample projects\ncupertino list-samples --framework swiftui --format json\n```\n\nAll commands support `--format json` for structured output that agents can parse.\n\n**Available Sources:**\n- `apple-docs` - Official Apple documentation (301,000+ pages)\n- `samples` - Apple sample code projects\n- `hig` - Human Interface Guidelines\n- `swift-evolution` - Swift Evolution proposals\n- `swift-org` - Swift.org documentation\n- `swift-book` - The Swift Programming Language book\n- `apple-archive` - Legacy programming guides\n- `packages` - Swift package documentation\n\n### What You Get\n\nOnce configured, Claude Desktop can search your local documentation:\n\n**Search Results Example:**\n```\n# Search Results for \"SwiftUI\"\n\nFound **20** results:\n\n## 1. NSHostingView | Apple Developer Documentation\n- **Framework:** `swiftui`\n- **URI:** `apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_nshostingview`\n- **Score:** 1.82\n\nAn AppKit view that hosts a SwiftUI view hierarchy.\n\n## 2. UIHostingController | Apple Developer Documentation\n- **Framework:** `swiftui`\n- **URI:** `apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_uihostingcontroller`\n\nA UIKit view controller that manages a SwiftUI view hierarchy.\n...\n```\n\n**Framework Statistics:**\n| Framework | Documents |\n|-----------|----------:|\n| Kernel | 39,396 |\n| Matter | 24,320 |\n| Swift | 17,466 |\n| AppKit | 12,443 |\n| Foundation | 12,423 |\n| UIKit | 11,158 |\n| Accelerate | 9,114 |\n| SwiftUI | 7,062 |\n| ... | ... |\n| **307 Frameworks** | **302,424** |\n\n## Core Features\n\n### 1. Multi-Source Documentation Fetching\n\n- **Apple Developer Documentation** (301,000+ pages)\n  - JavaScript-aware rendering via WKWebView\n  - HTML to Markdown conversion\n  - Smart change detection\n\n- **Swift Evolution Proposals** (~400 proposals)\n  - GitHub-based fetching\n  - Markdown format\n  - Fast downloads\n\n- **Swift.org Documentation**\n  - Official Swift language docs\n  - Clean HTML structure\n\n- **Swift Package Metadata**\n  - Priority package catalogs\n  - README files\n\n- **Apple Sample Code** (606 projects)\n  - Two fetch methods: GitHub (recommended) or Apple website\n  - Full-text search across all source files\n  - 18,000+ indexed Swift files\n\n- **Apple Archive Legacy Guides** (~75 pages)\n  - Pre-2016 programming guides (Core Animation, Quartz 2D, Core Text, etc.)\n  - Deep conceptual knowledge not in modern docs\n  - Excluded from search by default (use `--include-archive`)\n\n- **Human Interface Guidelines**\n  - Apple's official design guidelines for all platforms\n  - Covers iOS, macOS, watchOS, visionOS, and tvOS\n  - Design patterns, components, foundations, and best practices\n\n### 2. Bundled Resources\n\nCupertino includes pre-indexed catalog data bundled directly into the application:\n\n- **Swift Packages Catalog** (9,699 packages)\n  - Manually curated from Swift Package Index + GitHub API\n  - Includes package metadata, stars, licenses, descriptions\n  - Updated periodically by maintainers\n\n- **Sample Code Catalog** (606 entries)\n  - Apple's official sample code projects\n  - Includes titles, descriptions, frameworks, download URLs\n  - Bundled because Apple's catalog doesn't change frequently\n\n- **Priority Packages** (36 curated packages)\n  - Apple official packages (31) + essential ecosystem packages (5)\n  - High-priority Swift packages for quick access\n\nThese catalogs are indexed during `cupertino save` and enable instant search without requiring multi-hour downloads. You can still fetch package READMEs and sample code separately via `cupertino fetch` if needed.\n\n### 3. Full-Text Search Engine\n\n- **Technology**: SQLite FTS5 with BM25 ranking\n- **Features**:\n  - Porter stemming (e.g., \"running\" matches \"run\")\n  - Framework filtering\n  - Platform availability filtering (iOS\u002FmacOS version)\n  - Snippet generation\n  - Sub-100ms query performance\n- **Size**: ~2.4GB index for full documentation (302,000+ documents across 307 frameworks)\n- **Storage**: Database must be on local filesystem - SQLite does not work reliably on network drives (NFS\u002FSMB)\n\n### 4. Model Context Protocol Server\n\n- **Resources**: Direct access to documentation pages\n  - `apple-docs:\u002F\u002F{framework}\u002F{page}`\n  - `swift-evolution:\u002F\u002F{proposal-id}`\n  - `hig:\u002F\u002F{category}\u002F{page}`\n- **Tools**: Search and read capabilities for AI agents\n  - **Documentation Tools** (requires `cupertino save`):\n    - `search_docs` - Full-text search across all documentation\n      - Parameters: `query` (required), `source`, `framework`, `min_ios`, `min_macos`, `include_archive`, `limit` (all optional)\n    - `search_hig` - Search Human Interface Guidelines\n      - Parameters: `query` (required), `platform` (optional), `category` (optional), `limit` (optional)\n    - `list_frameworks` - List available frameworks\n    - `read_document` - Read document by URI with format option\n      - Parameters: `uri` (required), `format` (optional: `json` or `markdown`, default: `json`)\n      - JSON format returns the full structured document data (recommended for AI)\n      - Markdown format returns rendered content for human reading\n  - **Sample Code Tools** (requires `cupertino index`):\n    - `search_samples` - Search sample code projects and files\n    - `list_samples` - List all indexed sample projects\n    - `read_sample` - Read sample project README and metadata\n    - `read_sample_file` - Read specific source file from a sample\n\n### 5. Intelligent Crawling\n\n- **Resumable**: Continue interrupted crawls from saved state\n- **Change Detection**: Skip unchanged pages on updates\n- **Respectful**: 0.05s default delay between requests (configurable)\n- **Deduplication**: Automatic URL queue management\n- **Priority Queues**: Important content fetched first\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `cupertino` | Start MCP server (default) |\n| `cupertino setup` | Download pre-built databases from GitHub |\n| `cupertino serve` | Start MCP server |\n| `cupertino fetch` | Download documentation |\n| `cupertino save` | Build search index |\n| `cupertino search` | Search documentation from CLI |\n| `cupertino read` | Read full document by URI |\n| `cupertino doctor` | Check server health |\n| `cupertino index` | Index sample code for search |\n| `cupertino cleanup` | Clean up sample code archives |\n\nSee [docs\u002Fcommands\u002F](docs\u002Fcommands\u002F) for detailed usage and options.\n\n## Architecture\n\nCupertino uses an **[ExtremePackaging](https:\u002F\u002Faleahim.com\u002Fblog\u002Fextreme-packaging\u002F)** architecture with 9 consolidated packages:\n\n```\nFoundation Layer:\n  ├─ MCP                    # Consolidated MCP framework (Protocol + Transport + Server)\n  ├─ Logging                # os.log infrastructure\n  └─ Shared                 # Configuration & models\n\nInfrastructure Layer:\n  ├─ Core                   # Crawler & downloaders\n  └─ Search                 # SQLite FTS5 search\n\nApplication Layer:\n  ├─ MCPSupport             # Resource providers\n  ├─ SearchToolProvider     # Search tool implementations\n  └─ Resources              # Embedded resources\n\nExecutables:\n  ├─ CLI                    # Unified cupertino binary\n  ├─ TUI                    # Terminal UI (cupertino-tui)\n  └─ MockAIAgent            # Testing tool (mock-ai-agent)\n```\n\n### Data Flow\n\n```\n1. Fetch:  cupertino fetch --type docs\n   ↓\n   WKWebView → HTML → Markdown → disk (~\u002F.cupertino\u002Fdocs\u002F)\n\n2. Save:   cupertino save\n   ↓\n   Markdown files → SQLite FTS5 index (~\u002F.cupertino\u002Fsearch.db)\n\n3. Serve:  cupertino serve\n   ↓\n   MCP Server (stdio) ← JSON-RPC ← Claude Desktop\n   ↓\n   DocsResourceProvider + CupertinoSearchToolProvider\n```\n\n### Key Design Principles\n\n- **Swift 6.2 Concurrency**: 100% strict concurrency checking with actors and async\u002Fawait\n- **Value Semantics**: Immutable structs by default, Sendable conformance\n- **Actor Isolation**: @MainActor for WKWebView, actors for shared state\n- **Explicit Dependencies**: No singletons, clear dependency injection\n- **Separation of Concerns**: Crawling → Indexing → Serving as distinct phases\n\n## Development\n\n### Build System\n\n```bash\n# Show all available commands\nmake help\n\n# Common tasks\nmake build                  # Build release binaries\nsudo make install           # Install to \u002Fusr\u002Flocal\u002Fbin\nsudo make update            # Rebuild and reinstall\nmake test                   # Run all tests\nmake clean                  # Clean build artifacts\n\n# Development workflow\nmake test-unit              # Fast unit tests only\nmake test-integration       # All tests (includes network calls)\nmake format                 # Format code with SwiftFormat\nmake lint                   # Lint with SwiftLint\n```\n\n### Testing\n\n**Test Suite:**\n- 698 tests across 73 test suites\n- ~35 seconds duration\n- Includes unit tests, integration tests, and formatter tests\n\n**Test Categories:**\n- Web Crawl Tests - Real Apple documentation fetching\n- Fetch Command Tests - Package\u002Fcode downloading\n- Save Command Tests - Search index building\n- MCP Tests - Server health, tool\u002Fresource providers\n- Core Tests - Search, logging, state management\n\n### Logging\n\nCupertino uses **os.log** for structured logging:\n\n```bash\n# View all logs\nlog show --predicate 'subsystem == \"com.cupertino\"' --last 1h\n\n# View specific category\nlog show --predicate 'subsystem == \"com.cupertino\" AND category == \"crawler\"' --last 1h\n\n# Stream live logs\nlog stream --predicate 'subsystem == \"com.cupertino\"'\n```\n\n**Categories**: crawler, mcp, search, cli, transport, pdf, evolution, samples\n\n## Performance\n\n| Operation | Time | Size |\n|-----------|------|------|\n| Build CLI | 10-15s | 4.3MB |\n| Crawl 301,000+ pages | 12+ days | 2-3GB |\n| Swift Evolution | 2-5 min | 429 proposals |\n| Swift.org docs | 5-10 min | 501 pages |\n| Build search index | 2-5 min | ~160MB |\n| Search query | \u003C100ms | - |\n\n### Why Crawling Takes 12+ Days\n\nThe crawler uses a **0.05 second default delay between each request** (configurable):\n- 301,000 pages × 0.05s = ~4.2 hours minimum\n- Plus page rendering, parsing, and saving time\n- Crawl must reach depth 21+ to get all documentation\n- **Total: ~12+ days for initial full crawl**\n\nUse `cupertino setup` to download pre-built databases instead (~30 seconds).\n\nThis is a **one-time operation**. Incremental updates use change detection to skip unchanged pages and complete much faster.\n\n## Example Use Cases\n\n### 1. Offline Documentation Archive\n\n```bash\n# Download everything for offline access\ncupertino fetch --type docs --max-pages 15000\ncupertino fetch --type evolution\ncupertino save\n```\n\n### 2. Framework-Specific Research\n\n```bash\n# Just SwiftUI documentation\ncupertino fetch --type docs \\\n  --start-url \"https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Fswiftui\" \\\n  --max-pages 500\n```\n\n### 3. AI-Assisted Development\n\n```bash\n# Serve documentation to Claude\ncupertino serve\n\n# Then ask Claude: \"How do I use @Observable in SwiftUI?\"\n```\n\n### 4. Custom Documentation Workflows\n\n```bash\n# Multiple sources with custom paths\ncupertino fetch --type docs --output-dir ~\u002Fdocs\u002Fapple\ncupertino fetch --type evolution --output-dir ~\u002Fdocs\u002Fevolution\ncupertino save --base-dir ~\u002Fdocs --search-db ~\u002Fdocs\u002Fsearch.db\ncupertino serve --docs-dir ~\u002Fdocs\u002Fapple --search-db ~\u002Fdocs\u002Fsearch.db\n```\n\n## Documentation\n\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** - Build, test, contribute, and release workflow\n- **[docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md)** - Technical deep-dives (Concurrency, MCP, WKWebView testing)\n- **[docs\u002FDEPLOYMENT.md](docs\u002FDEPLOYMENT.md)** - Homebrew distribution and CI\u002FCD setup\n- **[docs\u002Fcommands\u002F](docs\u002Fcommands\u002F)** - Command-specific documentation\n\n### Command Documentation\n\nEach command has detailed documentation:\n- [docs\u002Fcommands\u002Ffetch\u002F](docs\u002Fcommands\u002Ffetch\u002F) - Download documentation\n- [docs\u002Fcommands\u002Fsave\u002F](docs\u002Fcommands\u002Fsave\u002F) - Build search indexes\n- [docs\u002Fcommands\u002Fserve\u002F](docs\u002Fcommands\u002Fserve\u002F) - Start MCP server\n- [docs\u002Fcommands\u002Fsearch\u002F](docs\u002Fcommands\u002Fsearch\u002F) - Search documentation from CLI\n- [docs\u002Fcommands\u002Fdoctor\u002F](docs\u002Fcommands\u002Fdoctor\u002F) - Check server health\n\n## Contributing\n\nIssues and pull requests are welcome! I'd love to hear how you're using Cupertino with your AI workflow.\n\nFor questions and discussion, use [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fdiscussions).\n\nI prefer collaboration over competition — if you're working on something similar, let's find ways to work together.\n\nDon't hesitate to submit a PR because of code style. I'd rather have your contribution than perfect formatting.\n\nBy participating in this project you agree to abide by the [Contributor Covenant Code of Conduct](https:\u002F\u002Fwww.contributor-covenant.org\u002F).\n\nFor development setup, see [DEVELOPMENT.md](DEVELOPMENT.md).\n\n## Project Status\n\n**Version:** 0.10.0\n**Status:** 🚧 Active Development\n\n- ✅ All core functionality working\n- ✅ 93 tests passing (100% pass rate)\n- ✅ 0 lint violations\n- ✅ Swift 6.2 compliant with 100% strict concurrency checking\n- ✅ All production bugs resolved\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## Acknowledgments\n\n- Built with Swift 6.2 and Swift Package Manager\n- Uses [swift-argument-parser](https:\u002F\u002Fgithub.com\u002Fapple\u002Fswift-argument-parser) for CLI\n- Implements [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) specification\n- Inspired by the need for offline Apple documentation access\n\n## Related Repositories\n\n- **[cupertino-desktop](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-desktop)** - Native macOS desktop app with graphical interface\n- **[cupertino-docs](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-docs)** - Pre-built documentation archive for quick installation\n- **[cupertino-sample-code](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-sample-code)** - Apple sample code repository mirror\n\nThe docs and sample-code repositories will be used by the planned `make install (full)` command (see [#52](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues\u002F52)), providing pre-built documentation and sample code to avoid the initial 20+ hour crawl.\n\n## Support\n\n- **Issues:** [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues)\n- **Discussions:** [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fdiscussions)\n\n---\n\n**Note:** This tool is for educational and development purposes. Respect Apple's Terms of Service when using their documentation.\n","# 🍎📚 库比蒂诺\n\n**苹果文档爬虫与 MCP 服务器**\n\n一款基于 Swift 的工具，用于抓取、索引并经由模型上下文协议 (MCP) 向 AI 代理提供苹果开发者文档。\n\n[![Swift 6.2+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSwift-6.2+-orange.svg)](https:\u002F\u002Fswift.org)\n[![macOS 15+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FmacOS-15+-blue.svg)](https:\u002F\u002Fwww.apple.com\u002Fmacos)\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-green.svg)](LICENSE)\n[![PulseMCP](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPulseMCP-listed-blue)](https:\u002F\u002Fwww.pulsemcp.com\u002Fservers\u002Fmihaelamj-cupertino)\n[![LobeHub](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLobeHub-listed-purple)](https:\u002F\u002Flobehub.com\u002Fmcp\u002Fmihaelamj-cupertino)\n\n![库比蒂诺演示](https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmihaelamj_cupertino_readme_3c05ed6560ff.gif)\n\n## 什么是库比蒂诺？\n\n库比蒂诺是一个本地化、结构化的、面向 AI 的苹果平台文档系统。它能够：\n\n- **抓取** 苹果开发者文档、Swift.org、Swift 演进提案、人机界面指南、苹果档案中的历史文档以及 Swift 包元数据。\n- **索引** 所有内容到一个快速可搜索的 SQLite FTS5 数据库中，并使用 BM25 排序算法进行排序。\n- **提供** 文档给像 Claude 这样的 AI 代理，通过模型上下文协议实现。\n- **支持** 离线访问，涵盖 307 个框架下的 302,424+ 页文档。\n\n### 为什么要构建这个项目？\n\n- **不再出现幻觉**：AI 代理可以获取准确且最新的苹果 API 文档。\n- **离线开发**：无需互联网连接即可使用完整文档。\n- **确定性搜索**：相同的查询始终返回相同的结果。\n- **本地控制**：完全掌控你的文档，检查数据库，编写自动化脚本。\n- **面向 AI 的设计**：专为通过 MCP 集成 AI 代理而构建。\n\n## 快速入门\n\n> **注意**：从源码构建时，命令必须在 `Packages` 目录下执行。而单命令安装则可在任何位置运行。\n\n### 系统要求\n\n- macOS 15+（Sequoia）\n- 大约 2–3 GB 的磁盘空间用于存储完整文档。\n\n*从源码构建还需要 Swift 6.2+ 和 Xcode 16.0+*\n\n### 安装方法\n\n**推荐的单命令安装：**\n\n```bash\nbash \u003C(curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmihaelamj\u002Fcupertino\u002Fmain\u002Finstall.sh)\n```\n\n此命令会下载一个预编译、已签名且经过公证的通用二进制文件，将其安装到 `\u002Fusr\u002Flocal\u002Fbin`，并同时下载文档数据库。\n\n**或使用 Homebrew：**\n\n```bash\nbrew tap mihaelamj\u002Ftap\nbrew install cupertino\ncupertino setup\n```\n\n**或从源码构建：**\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\ncd cupertino\n\n# 使用 Makefile（推荐）\nmake build                       # 构建发布版二进制文件\nsudo make install                # 安装到 \u002Fusr\u002Flocal\u002Fbin\n\n# 或直接使用 Swift 包管理器\ncd Packages\nswift build -c release\nsudo ln -sf \"$(pwd)\u002F.build\u002Frelease\u002Fcupertino\" \u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\n```\n\n**演示视频**：[观看 YouTube](https:\u002F\u002Fyoutu.be\u002FB-mRdainTMA)\n\n### 快速参考\n\n```bash\n# 推荐的快速设置——下载预构建的数据库（约30秒）\ncupertino setup                      # 从 GitHub 下载数据库\ncupertino serve                      # 启动 MCP 服务器\n\n# 另一种方式：从 GitHub 构建（约45分钟）\ncupertino save --remote              # 流式传输并本地构建\n\n# 或者自行获取文档\ncupertino fetch --type docs          # 苹果开发者文档\ncupertino fetch --type swift         # Swift.org 文档\ncupertino fetch --type evolution     # Swift 演进提案\ncupertino fetch --type packages      # Swift 包元数据\ncupertino fetch --type package-docs  # Swift 包的 README 文件\ncupertino fetch --type code          # 来自苹果的示例代码（需要认证）\ncupertino fetch --type samples       # 来自 GitHub 的示例代码（推荐）\ncupertino fetch --type archive       # 苹果档案中的编程指南\ncupertino fetch --type hig           # 人机界面指南\ncupertino fetch --type availability  # 平台可用性数据\ncupertino fetch --type all           # 并行获取所有类型的数据\n\n# 构建索引\ncupertino save                       # 构建文档搜索索引（基于本地文件）\ncupertino save --remote              # 从 GitHub 构建（无需本地文件）\ncupertino index                      # 对示例代码建立搜索索引\n\n# 启动服务器\ncupertino                            # 启动 MCP 服务器（默认命令）\ncupertino serve                      # 显式启动 MCP 服务器\n```\n\n### 即时设置（推荐）\n\n```bash\n# 从 GitHub 下载预构建的数据库（约30秒）\ncupertino setup\n\n# 启动 MCP 服务器\ncupertino serve\n```\n\n### 替代方案：从 GitHub 构建\n\n```bash\n# 流式传输并本地构建（约45分钟）\n# 如果你想自己构建数据库，可以使用此方法\ncupertino save --remote\n\n# 启动 MCP 服务器\ncupertino serve\n```\n\n### 手动设置（进阶）\n\n```bash\n# 下载苹果文档（对于超过30万页的内容，可能需要12天以上）\n# 由于每次请求之间有0.05秒的默认延迟，因此耗时较长\ncupertino fetch --type docs --max-pages 15000\n\n# 下载 Swift 演进提案（约2–5分钟）\ncupertino fetch --type evolution\n\n# 下载来自 GitHub 的示例代码（约4分钟，共606个项目）\ncupertino fetch --type samples\n\n# 构建搜索索引（约2–5分钟）\ncupertino save\n```\n\n### 与 Claude Desktop 配合使用\n\n1. **配置 Claude Desktop** — 编辑 `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n> **注意**：如果使用 Homebrew 安装在 Apple Silicon 上，请使用 `\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino`；如果是 Intel Mac 或手动安装，则使用 `\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino`。运行 `which cupertino` 查看具体路径。\n\n2. **重启 Claude Desktop**\n\n3. **向 Claude 提问关于苹果 API 的问题：**\n   - “搜索 SwiftUI 文档”\n   - “Swift 演进提案 SE-0001 提出了什么？”\n   - “列出可用的框架”\n\n### 与 Claude Code 配合使用\n\n如果你正在使用 [Claude Code](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Foverview)，只需一条命令即可将库比蒂诺添加为 MCP 服务器：\n\n```bash\nclaude mcp add cupertino --scope user -- $(which cupertino)\n```\n\n这会将库比蒂诺全局注册到你所有的项目中。Claude Code 将自动获得对苹果文档搜索的权限。\n\n### 与 OpenAI Codex 配合使用\n\n如果你正在使用 [OpenAI Codex](https:\u002F\u002Fgithub.com\u002Fopenai\u002Fcodex)，可以通过以下命令添加库比蒂诺：\n\n```bash\ncodex mcp add cupertino -- $(which cupertino) serve\n```\n\n或者直接添加到 `~\u002F.codex\u002Fconfig.toml` 中：\n\n```toml\n[mcp_servers.cupertino]\ncommand = \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\"  # Homebrew on Apple Silicon\n# command = \"\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\"   # Intel Mac 或手动安装\nargs = [\"serve\"]\n```\n\n> **提示**：运行 `which cupertino` 查看你的安装路径。\n\n### 与 Cursor 配合使用\n\n将以下内容添加到你项目的 `.cursor\u002Fmcp.json` 文件中（或全局的 `~\u002F.cursor\u002Fmcp.json`）：\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### 与 VS Code（GitHub Copilot）配合使用\n\n在工作区的 `.vscode\u002Fmcp.json` 中添加以下内容：\n\n```json\n{\n  \"servers\": {\n    \"cupertino\": {\n      \"type\": \"stdio\",\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### 与 Zed 配合使用\n\n在 Zed 的 `settings.json` 中添加以下内容：\n\n```json\n{\n  \"context_servers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### 与 Windsurf 配合使用\n\n在 `~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json` 中添加以下内容：\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n### 与 opencode 配合使用\n\n在 `opencode.jsonc` 中添加以下内容：\n\n```json\n{\n  \"mcp\": {\n    \"cupertino\": {\n      \"type\": \"local\",\n      \"command\": [\"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\", \"serve\"]\n    }\n  }\n}\n```\n\n> **注意：** 所有示例均使用 `\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino`（Apple Silicon 上的 Homebrew）。对于 Intel Mac 或手动安装，请使用 `\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino`。运行 `which cupertino` 可以找到您的路径。\n\n### 作为代理技能使用（无需服务器）\n\nCupertino 也可以作为无状态的 CLI 技能使用，而无需运行 MCP 服务器。这对于支持 [Agent Skills](https:\u002F\u002Fagentskills.io) 规范的代理非常有用。\n\n**先决条件：**\n\n首先安装 cupertino 并下载数据库：\n```bash\n# 通过 Homebrew 或源码安装（参见上文的安装部分）\ncupertino setup\n```\n\n**选项 A：使用 OpenSkills 安装（推荐）**\n\n[OpenSkills](https:\u002F\u002Fgithub.com\u002Fnumman-ali\u002Fopenskills) 是一个通用的技能加载器，可与 Claude Code、Cursor、Windsurf、Aider 等 AI 编程代理配合使用。\n\n```bash\n# 从 GitHub 安装 cupertino 技能\nnpx openskills install mihaelamj\u002Fcupertino\n\n# 同步以更新 AGENTS.md\nnpx openskills sync\n```\n\n对于全局安装（在所有项目中可用）：\n```bash\nnpx openskills install mihaelamj\u002Fcupertino --global\n```\n\n对于多代理设置（安装到 `.agent\u002Fskills\u002F` 而不是 `.claude\u002Fskills\u002F`）：\n```bash\nnpx openskills install mihaelamj\u002Fcupertino --universal\n```\n\n**选项 B：作为 Claude Code 插件安装**\n\n在 Claude Code 会话中，添加 cupertino 市场：\n```\n\u002Fplugin marketplace add mihaelamj\u002Fcupertino\n```\n\n然后从市场启用该插件。\n\n**选项 C：手动安装**\n\n将技能定义复制到您的项目或全局技能目录中：\n```bash\n# 克隆此仓库\ngit clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\n\n# 对于单个项目\nmkdir -p .claude\u002Fskills\u002Fcupertino\ncp cupertino\u002Fskills\u002Fcupertino\u002FSKILL.md .claude\u002Fskills\u002Fcupertino\u002F\n\n# 或者用于 Claude Code 的全局使用\nmkdir -p ~\u002F.claude\u002Fskills\u002Fcupertino\ncp cupertino\u002Fskills\u002Fcupertino\u002FSKILL.md ~\u002F.claude\u002Fskills\u002Fcupertino\u002F\n```\n\n**工作原理：**\n\n该技能直接使用 CLI 并输出 JSON 格式，无需任何服务器进程：\n\n```bash\n# 搜索文档\ncupertino search \"SwiftUI View\" --format json\n\n# 按来源筛选\ncupertino search \"NavigationStack\" --source apple-docs --format json\ncupertino search \"button styles\" --source samples --format json\n\n# 阅读文档\ncupertino read \"apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_view\" --format json\n\n# 列出框架\ncupertino list-frameworks --format json\n\n# 列出示例项目\ncupertino list-samples --framework swiftui --format json\n```\n\n所有命令都支持 `--format json`，以便代理可以解析结构化输出。\n\n**可用来源：**\n- `apple-docs` - 苹果官方文档（301,000+ 页）\n- `samples` - 苹果示例代码项目\n- `hig` - 人机界面指南\n- `swift-evolution` - Swift 进化提案\n- `swift-org` - Swift.org 文档\n- `swift-book` - Swift 编程语言书\n- `apple-archive` - 旧版编程指南\n- `packages` - Swift 包文档\n\n### 您将获得的内容\n\n配置完成后，Claude Desktop 就可以搜索您本地的文档了：\n\n**搜索结果示例：**\n```\n# “SwiftUI”的搜索结果\n\n找到 **20** 条结果：\n\n## 1. NSHostingView | 苹果开发者文档\n- **框架:** `swiftui`\n- **URI:** `apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_nshostingview`\n- **得分:** 1.82\n\n一个托管 SwiftUI 视图层次结构的 AppKit 视图。\n\n## 2. UIHostingController | 苹果开发者文档\n- **框架:** `swiftui`\n- **URI:** `apple-docs:\u002F\u002Fswiftui\u002Fdocumentation_swiftui_uihostingcontroller`\n\n一个管理 SwiftUI 视图层次结构的 UIKit 视图控制器。\n...\n```\n\n**框架统计：**\n| 框架       | 文档数 |\n|------------|-------:|\n| Kernel     | 39,396 |\n| Matter     | 24,320 |\n| Swift      | 17,466 |\n| AppKit     | 12,443 |\n| Foundation | 12,423 |\n| UIKit      | 11,158 |\n| Accelerate | 9,114 |\n| SwiftUI    | 7,062 |\n| ...        | ...    |\n| **307 个框架** | **302,424** |\n\n## 核心功能\n\n### 1. 多源文档获取\n\n- **苹果开发者文档**（301,000+ 页）\n  - 通过 WKWebView 实现 JavaScript 可感知的渲染\n  - HTML 到 Markdown 的转换\n  - 智能变更检测\n\n- **Swift 进化提案**（约 400 个提案）\n  - 基于 GitHub 获取\n  - Markdown 格式\n  - 快速下载\n\n- **Swift.org 文档**\n  - 官方 Swift 语言文档\n  - 清洁的 HTML 结构\n\n- **Swift 包元数据**\n  - 优先包目录\n  - README 文件\n\n- **苹果示例代码**（606 个项目）\n  - 提供两种获取方式：GitHub（推荐）或苹果官网\n  - 在所有源文件中进行全文搜索\n  - 索引了超过 18,000 个 Swift 文件\n\n- **苹果档案遗留指南**（约 75 页）\n  - 2016 年之前的编程指南（Core Animation、Quartz 2D、Core Text 等）\n  - 深入的概念知识，现代文档中未涵盖\n  - 默认情况下不包含在搜索中（可使用 `--include-archive` 参数）\n\n- **人机界面指南**\n  - 苹果所有平台的官方设计指南\n  - 涵盖 iOS、macOS、watchOS、visionOS 和 tvOS\n  - 设计模式、组件、基础和最佳实践\n\n### 2. 捆绑资源\n\nCupertino 包含预先索引的目录数据，直接捆绑在应用程序中：\n\n- **Swift 包目录**（9,699 个包）\n  - 由 Swift Package Index 和 GitHub API 手动整理\n  - 包括包元数据、星标、许可证、描述\n  - 维护人员定期更新\n\n- **示例代码目录**（606 条目）\n  - 苹果官方示例代码项目\n  - 包括标题、描述、框架、下载链接\n  - 由于苹果的目录不常变化，因此被捆绑在一起\n\n- **优先包**（36 个精选包）\n  - 苹果官方包（31 个）加上生态系统中的重要包（5 个）\n  - 高优先级的 Swift 包，便于快速访问\n\n这些目录在执行 `cupertino save` 时被索引，从而实现即时搜索，而无需花费数小时下载。如果需要，您仍然可以通过 `cupertino fetch` 单独获取包的 README 和示例代码。\n\n### 3. 全文搜索引擎\n\n- **技术**：SQLite FTS5，采用BM25排序算法\n- **特性**：\n  - Porter词干提取（例如，“running”会匹配“run”）\n  - 框架过滤\n  - 平台可用性过滤（iOS\u002FmacOS版本）\n  - 片段生成\n  - 查询性能低于100毫秒\n- **大小**：完整文档索引约2.4GB（涵盖307个框架的302,000余篇文档）\n- **存储**：数据库必须位于本地文件系统——SQLite在网络驱动器（NFS\u002FSMB）上无法可靠运行\n\n### 4. 模型上下文协议服务器\n\n- **资源**：直接访问文档页面\n  - `apple-docs:\u002F\u002F{framework}\u002F{page}`\n  - `swift-evolution:\u002F\u002F{proposal-id}`\n  - `hig:\u002F\u002F{category}\u002F{page}`\n- **工具**：供AI智能体使用的搜索与阅读功能\n  - **文档工具**（需先执行`cupertino save`）：\n    - `search_docs`——全文档库全文检索\n      - 参数：`query`（必填）、`source`、`framework`、`min_ios`、`min_macos`、`include_archive`、`limit`（均为可选）\n    - `search_hig`——人机界面指南检索\n      - 参数：`query`（必填）、`platform`（可选）、`category`（可选）、`limit`（可选）\n    - `list_frameworks`——列出所有可用框架\n    - `read_document`——按URI读取文档，并可选择格式\n      - 参数：`uri`（必填）、`format`（可选：`json`或`markdown`，默认为`json`）\n      - JSON格式返回完整的结构化文档数据（推荐用于AI）\n      - Markdown格式则以渲染后的内容呈现，便于人类阅读\n  - **示例代码工具**（需先执行`cupertino index`）：\n    - `search_samples`——搜索示例代码项目及文件\n    - `list_samples`——列出所有已索引的示例项目\n    - `read_sample`——读取示例项目的README及元数据\n    - `read_sample_file`——读取示例中的特定源代码文件\n\n### 5. 智能爬虫\n\n- **可续爬**：从保存的状态继续中断的爬取任务\n- **变更检测**：更新时跳过未发生变化的页面\n- **礼貌性**：默认请求间隔0.05秒（可配置）\n- **去重**：自动管理URL队列\n- **优先级队列**：重要内容优先抓取\n\n## 命令列表\n\n| 命令 | 描述 |\n|------|------|\n| `cupertino` | 启动MCP服务器（默认） |\n| `cupertino setup` | 从GitHub下载预构建数据库 |\n| `cupertino serve` | 启动MCP服务器 |\n| `cupertino fetch` | 下载文档 |\n| `cupertino save` | 构建搜索索引 |\n| `cupertino search` | 通过命令行搜索文档 |\n| `cupertino read` | 按URI读取完整文档 |\n| `cupertino doctor` | 检查服务器健康状况 |\n| `cupertino index` | 索引示例代码以便搜索 |\n| `cupertino cleanup` | 清理示例代码存档 |\n\n详细用法及选项请参阅[docs\u002Fcommands\u002F](docs\u002Fcommands\u002F)。\n\n## 架构设计\n\nCupertino采用了**ExtremePackaging**架构，整合了9个模块：\n\n```\n基础层：\n  ├─ MCP                    # 整合的MCP框架（协议+传输+服务器）\n  ├─ Logging                # os.log基础设施\n  └─ Shared                 # 配置与模型\n\n基础设施层：\n  ├─ Core                   # 爬虫与下载组件\n  └─ Search                 # SQLite FTS5搜索\n\n应用层：\n  ├─ MCPSupport             # 资源提供者\n  ├─ SearchToolProvider     # 搜索工具实现\n  └─ Resources              # 内嵌资源\n\n可执行文件：\n  ├─ CLI                    # 统一的cupertino二进制文件\n  ├─ TUI                    # 终端用户界面（cupertino-tui）\n  └─ MockAIAgent            # 测试工具（mock-ai-agent）\n```\n\n### 数据流\n\n```\n1. 抓取： cupertino fetch --type docs\n   ↓\n   WKWebView → HTML → Markdown → 磁盘（~\u002F.cupertino\u002Fdocs\u002F）\n\n2. 保存： cupertino save\n   ↓\n   Markdown文件 → SQLite FTS5索引（~\u002F.cupertino\u002Fsearch.db）\n\n3. 服务： cupertino serve\n   ↓\n   MCP服务器（标准输入输出）← JSON-RPC ← Claude Desktop\n   ↓\n   DocsResourceProvider + CupertinoSearchToolProvider\n```\n\n### 核心设计原则\n\n- **Swift 6.2并发编程**：100%严格遵循并发检查，使用actor和async\u002Fawait\n- **值语义**：默认使用不可变结构体，并符合Sendable协议\n- **Actor隔离**：WKWebView使用@MainActor，共享状态由actor管理\n- **显式依赖**：不使用单例，采用清晰的依赖注入\n- **关注点分离**：爬取→索引→服务作为独立阶段\n\n## 开发流程\n\n### 构建系统\n\n```bash\n# 显示所有可用命令\nmake help\n\n# 常用任务\nmake build                  # 构建发布版二进制文件\nsudo make install           # 安装至\u002Fusr\u002Flocal\u002Fbin\nsudo make update            # 重新构建并重新安装\nmake test                   # 运行所有测试\nmake clean                  # 清理构建产物\n\n# 开发工作流程\nmake test-unit              # 仅运行快速单元测试\nmake test-integration       # 运行全部测试（包括网络请求）\nmake format                 # 使用SwiftFormat格式化代码\nmake lint                   # 使用SwiftLint进行代码检查\n```\n\n### 测试\n\n**测试套件**：\n- 73个测试套件，共698个测试用例\n- 总耗时约35秒\n- 包括单元测试、集成测试和格式化测试\n\n**测试类别**：\n- Web爬虫测试——真实苹果文档抓取\n- Fetch命令测试——软件包\u002F代码下载\n- Save命令测试——搜索索引构建\n- MCP测试——服务器健康、工具\u002F资源提供者\n- Core测试——搜索、日志记录、状态管理\n\n### 日志记录\n\nCupertino使用**os.log**进行结构化日志记录：\n\n```bash\n# 查看所有日志\nlog show --predicate 'subsystem == \"com.cupertino\"' --last 1h\n\n# 查看特定类别\nlog show --predicate 'subsystem == \"com.cupertino\" AND category == \"crawler\"' --last 1h\n\n# 实时查看日志\nlog stream --predicate 'subsystem == \"com.cupertino\"'\n```\n\n**类别**：爬虫、MCP、搜索、CLI、传输、PDF、evolution、samples\n\n## 性能指标\n\n| 操作 | 时间 | 大小 |\n|-------|------|------|\n| 构建CLI | 10–15秒 | 4.3MB |\n| 爬取301,000+页 | 12天以上 | 2–3GB |\n| Swift Evolution | 2–5分钟 | 429项提案 |\n| Swift.org文档 | 5–10分钟 | 501页 |\n| 构建搜索索引 | 2–5分钟 | 约160MB |\n| 搜索查询 | \u003C100毫秒 | — |\n\n### 为什么爬取需要12天以上？\n\n爬虫默认每次请求之间有0.05秒的延迟（可配置）：\n- 301,000页 × 0.05秒 = 最低约4.2小时\n- 加上页面渲染、解析和保存的时间\n- 爬取必须达到深度21才能获取全部文档\n- **总计：首次完整爬取需12天以上**\n\n可使用`cupertino setup`下载预构建数据库，耗时约30秒。\n\n这是一次性操作。后续增量更新会利用变更检测跳过未变化的页面，从而大大缩短时间。\n\n## 示例用法\n\n### 1. 离线文档存档\n\n```bash\n# 下载所有内容以供离线使用\ncupertino fetch --type docs --max-pages 15000\ncupertino fetch --type evolution\ncupertino save\n```\n\n### 2. 框架特定研究\n\n```bash\ncupertino search --framework UIKit --query \"Auto Layout\"\n\n# 仅 SwiftUI 文档\ncupertino fetch --type docs \\\n  --start-url \"https:\u002F\u002Fdeveloper.apple.com\u002Fdocumentation\u002Fswiftui\" \\\n  --max-pages 500\n```\n\n### 3. AI 辅助开发\n\n```bash\n# 向 Claude 提供文档服务\ncupertino serve\n\n# 然后向 Claude 提问：“如何在 SwiftUI 中使用 @Observable？”\n```\n\n### 4. 自定义文档工作流\n\n```bash\n# 多个来源，自定义路径\ncupertino fetch --type docs --output-dir ~\u002Fdocs\u002Fapple\ncupertino fetch --type evolution --output-dir ~\u002Fdocs\u002Fevolution\ncupertino save --base-dir ~\u002Fdocs --search-db ~\u002Fdocs\u002Fsearch.db\ncupertino serve --docs-dir ~\u002Fdocs\u002Fapple --search-db ~\u002Fdocs\u002Fsearch.db\n```\n\n## 文档\n\n- **[DEVELOPMENT.md](DEVELOPMENT.md)** - 构建、测试、贡献及发布流程\n- **[docs\u002FARCHITECTURE.md](docs\u002FARCHITECTURE.md)** - 技术深度解析（并发、MCP、WKWebView 测试）\n- **[docs\u002FDEPLOYMENT.md](docs\u002FDEPLOYMENT.md)** - Homebrew 分发与 CI\u002FCD 设置\n- **[docs\u002Fcommands\u002F](docs\u002Fcommands\u002F)** - 命令专用文档\n\n### 命令文档\n\n每个命令都有详细的文档说明：\n- [docs\u002Fcommands\u002Ffetch\u002F](docs\u002Fcommands\u002Ffetch\u002F) - 下载文档\n- [docs\u002Fcommands\u002Fsave\u002F](docs\u002Fcommands\u002Fsave\u002F) - 构建搜索索引\n- [docs\u002Fcommands\u002Fserve\u002F](docs\u002Fcommands\u002Fserve\u002F) - 启动 MCP 服务器\n- [docs\u002Fcommands\u002Fsearch\u002F](docs\u002Fcommands\u002Fsearch\u002F) - 从 CLI 搜索文档\n- [docs\u002Fcommands\u002Fdoctor\u002F](docs\u002Fcommands\u002Fdoctor\u002F) - 检查服务器健康状况\n\n## 贡献\n\n欢迎提交问题和拉取请求！我很想听听您是如何将 Cupertino 应用于自己的 AI 工作流的。\n\n如有任何疑问或讨论，请使用 [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fdiscussions)。\n\n我更倾向于协作而非竞争——如果您正在做类似的事情，让我们一起探讨合作的可能性吧。\n\n请不要因为代码风格而犹豫提交 PR。比起完美的格式，我更希望看到您的贡献。\n\n参与本项目即表示您同意遵守 [Contributor Covenant 行为准则](https:\u002F\u002Fwww.contributor-covenant.org\u002F)。\n\n有关开发环境的搭建，请参阅 [DEVELOPMENT.md](DEVELOPMENT.md)。\n\n## 项目状态\n\n**版本：** 0.10.0  \n**状态：** 🚧 正在开发中\n\n- ✅ 所有核心功能正常运行\n- ✅ 93 个测试通过（100% 通过率）\n- ✅ 无 lint 违规\n- ✅ 符合 Swift 6.2 标准，并实现 100% 的严格并发检查\n- ✅ 所有生产环境中的 Bug 已修复\n\n## 许可证\n\nMIT 许可证 - 详情请参阅 [LICENSE](LICENSE)\n\n## 致谢\n\n- 使用 Swift 6.2 和 Swift Package Manager 构建\n- 使用 [swift-argument-parser](https:\u002F\u002Fgithub.com\u002Fapple\u002Fswift-argument-parser) 实现 CLI\n- 遵循 [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) 规范\n- 受到对离线访问 Apple 文档需求的启发\n\n## 相关仓库\n\n- **[cupertino-desktop](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-desktop)** - 原生 macOS 桌面应用，带有图形界面\n- **[cupertino-docs](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-docs)** - 预构建的文档存档，便于快速安装\n- **[cupertino-sample-code](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino-sample-code)** - Apple 示例代码库镜像\n\n这些文档和示例代码仓库将被计划中的 `make install (full)` 命令所使用（详见 [#52](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues\u002F52)），从而提供预构建的文档和示例代码，以避免最初的 20 多小时爬取过程。\n\n## 支持\n\n- **问题：** [GitHub Issues](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues)\n- **讨论：** [GitHub Discussions](https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fdiscussions)\n\n---\n\n**注：** 本工具仅供教育和开发用途。使用 Apple 文档时，请务必遵守其服务条款。","# Cupertino 快速上手指南\n\nCupertino 是一个基于 Swift 开发的本地工具，用于抓取、索引并通过模型上下文协议（MCP）向 AI 代理提供 Apple 开发者文档。它能有效减少 AI 幻觉，支持离线开发，并提供确定性的搜索结果。\n\n## 环境准备\n\n在开始之前，请确保您的开发环境满足以下要求：\n\n*   **操作系统**：macOS 15 (Sequoia) 或更高版本。\n*   **磁盘空间**：预留约 2-3 GB 空间用于存储完整的文档数据库。\n*   **构建依赖**（仅当需要从源码编译时）：\n    *   Swift 6.2+\n    *   Xcode 16.0+\n\n> **注意**：如果您使用推荐的“一键安装”或 Homebrew 安装方式，无需手动安装 Swift 或 Xcode。\n\n## 安装步骤\n\n您可以选择以下任意一种方式进行安装。推荐优先使用一键安装脚本或 Homebrew。\n\n### 方式一：一键安装（推荐）\n\n此方法会下载预构建的二进制文件并自动配置数据库，速度最快。\n\n```bash\nbash \u003C(curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmihaelamj\u002Fcupertino\u002Fmain\u002Finstall.sh)\n```\n\n### 方式二：使用 Homebrew 安装\n\n如果您已安装 Homebrew，可以使用以下命令：\n\n```bash\nbrew tap mihaelamj\u002Ftap\nbrew install cupertino\ncupertino setup\n```\n\n### 方式三：从源码构建（高级用户）\n\n仅当您想自定义构建或贡献代码时使用此方法。\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\ncd cupertino\n\n# 使用 Makefile 构建并安装\nmake build\nsudo make install\n```\n\n## 基本使用\n\n安装完成后，只需两个步骤即可让 AI 助手访问 Apple 官方文档。\n\n### 1. 初始化数据库\n\n运行以下命令下载预构建的文档数据库（包含 30 万 + 页面，耗时约 30 秒）：\n\n```bash\ncupertino setup\n```\n\n> 若需自行从头抓取最新文档（耗时较长），可运行 `cupertino save --remote`。\n\n### 2. 启动 MCP 服务\n\n在终端运行以下命令启动服务器：\n\n```bash\ncupertino serve\n```\n\n保持该终端窗口开启，或者将其配置为 AI 编辑器的后台服务。\n\n### 3. 集成到 AI 编辑器\n\n根据您的开发工具，添加以下配置以启用 Cupertino：\n\n#### Claude Desktop\n编辑配置文件 `~\u002FLibrary\u002FApplication Support\u002FClaude\u002Fclaude_desktop_config.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fusr\u002Flocal\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n*注：Apple Silicon 芯片用户使用 Homebrew 安装时，command 路径通常为 `\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino`。可通过运行 `which cupertino` 确认具体路径。*\n\n#### Cursor\n在项目根目录创建 `.cursor\u002Fmcp.json` 或在用户目录创建全局配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"cupertino\": {\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n#### VS Code (GitHub Copilot)\n在工作区创建 `.vscode\u002Fmcp.json`：\n\n```json\n{\n  \"servers\": {\n    \"cupertino\": {\n      \"type\": \"stdio\",\n      \"command\": \"\u002Fopt\u002Fhomebrew\u002Fbin\u002Fcupertino\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n#### Claude Code (命令行)\n直接运行以下命令注册全局服务：\n\n```bash\nclaude mcp add cupertino --scope user -- $(which cupertino)\n```\n\n### 验证效果\n\n配置完成后，重启您的 AI 编辑器或对话窗口，尝试询问以下问题：\n\n*   \"搜索 SwiftUI 的相关文档\"\n*   \"Swift Evolution 提案 SE-0001 的内容是什么？\"\n*   \"列出可用的框架及其文档数量\"\n\nCupertino 将直接从本地 SQLite 数据库检索准确的 Apple 官方文档并返回给 AI。","一位 iOS 开发者正在离线环境下重构旧项目，需要让 AI 助手准确理解最新的 Swift 并发模型和 Apple 人机交互指南。\n\n### 没有 cupertino 时\n- **幻觉频发**：AI 因缺乏最新官方文档支持，常编造不存在的 API 参数或过时的回调写法，导致代码无法编译。\n- **网络依赖强**：在飞机或网络不稳定时，AI 无法实时检索 Apple 开发者网站，开发工作被迫中断。\n- **搜索结果随机**：同一技术问题多次询问，AI 给出的答案不一致，甚至引用已废弃的 Objective-C 方案。\n- **上下文缺失**：AI 难以同时关联 Swift 演化提案（Swift Evolution）与具体框架文档，无法提供深度的架构建议。\n\n### 使用 cupertino 后\n- **零幻觉引用**：cupertino 将 30 万 + 页官方文档索引至本地 SQLite，AI 基于真实数据回答，精准提供 Swift 6.2 的最新语法。\n- **完全离线可用**：文档数据库已预下载至本地，即便在无网环境中，AI 也能瞬间调用完整的 Apple 开发知识库。\n- **结果确定性高**：基于 BM25 算法的本地检索确保每次查询返回一致、可验证的文档片段，消除回答的随机性。\n- **深度知识关联**：cupertino 自动串联人机交互指南与代码示例，使 AI 能同时从规范层面和实现层面给出重构方案。\n\ncupertino 通过将权威苹果文档转化为本地可控的 AI 上下文，彻底解决了开发中因信息滞后和网络限制导致的信任危机。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fmihaelamj_cupertino_e1dd723d.png","mihaelamj","Mihaela Mihaljevic","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fmihaelamj_9a73d766.jpg","Senior iOS\u002FmacOS Engineer · Swift · OpenAPI · Modular Architectures · Lover of clean code and real concurrency\r\n",null,"Zagreb, Croatia","mihaelamj@me.com","aleahim.com","https:\u002F\u002Fgithub.com\u002Fmihaelamj",[85,89,93],{"name":86,"color":87,"percentage":88},"Swift","#F05138",98.9,{"name":90,"color":91,"percentage":92},"Makefile","#427819",0.7,{"name":94,"color":95,"percentage":96},"Shell","#89e051",0.4,630,23,"2026-03-31T07:39:12","MIT","macOS","未说明","未说明 (需约 2-3 GB 磁盘空间存储文档数据库)",{"notes":105,"python":106,"dependencies":107},"该工具基于 Swift 开发，仅支持 macOS 15+ (Sequoia)。无需 Python 环境。若从源码构建，需要安装 Swift 6.2+ 和 Xcode 16.0+。推荐使用预编译二进制或通过 Homebrew 安装。运行时需要下载或构建包含 30 万 + 页面的 SQLite 文档数据库（约 2-3 GB）。主要通过 MCP 协议与 Claude、Cursor 等 AI 代理集成，也可作为无状态 CLI 技能使用。","不需要",[108,109,110],"Swift 6.2+","Xcode 16.0+","SQLite FTS5",[16],[113,114,115,116,117,118,119,120,121,122,123,124],"apple-documentation","command-line-tool","developer-tools","documentation-tools","local-server","offline-docs","mcp","mcp-server","swift","swiftpm","cli","model-context-protocol","2026-03-27T02:49:30.150509","2026-04-06T05:44:23.463910",[128,133,138,142,147,151,155],{"id":129,"question_zh":130,"answer_zh":131,"source_url":132},12554,"为什么爬虫会遗漏某些框架（如 DeviceCheck），如何确保完整的框架覆盖率？","这是因为根页面使用了不同的 JSON 架构（kind: \"root\"），且框架之间缺乏交叉链接。解决方案是使用 `technologies.json` 作为种子源来引导爬虫。具体修复包括：1. 应用会话恢复验证，使 `--start-url` 正常工作；2. 为未来的爬取添加 `technologies.json` 种子源；3. 修复大小写不敏感的 URL 前缀匹配问题；4. 将请求延迟从 0.5 秒减少到 0.05 秒以提高效率。运行命令示例：并行运行 20 个任务，使用 `--allowed-prefixes` 指定框架，配合 `--max-pages 1000000 --use-json-api --force` 参数。","https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues\u002F160",{"id":134,"question_zh":135,"answer_zh":136,"source_url":137},12555,"如何让 AI 代理自动发现并搜索 Apple Archive 中的遗留指南内容？","目前归档内容需要显式选择（如 `include_archive: true` 或 `source: \"apple-archive\"`），导致 AI 容易遗漏。建议的解决方案包括：1. 添加专用的 `search_archive` 工具，使其成为一等公民；2. 默认包含归档内容，移除手动选择的要求；3. 优化工具描述，突出归档搜索能力；4. 当搜索结果稀疏时，自动建议搜索归档库。这样可以确保像 Core Animation Programming Guide 这样的重要概念性文档能被自动检索到。","https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues\u002F97",{"id":139,"question_zh":140,"answer_zh":141,"source_url":137},12556,"如何查询在特定 iOS\u002FmacOS 版本之前已被弃用或移除的 API？","可以通过添加 `max_*` 系列过滤器来实现。除了现有的 `min_*` 过滤器外，现在支持 `max_ios`, `max_macos`, `max_tvos`, `max_watchos`, `max_visionos` 参数。例如，使用 `--max-ios 14.0` 可以查找在 iOS 14.0 之前被弃用或移除的 API。这有助于开发者识别特定版本范围内的兼容性变化。",{"id":143,"question_zh":144,"answer_zh":145,"source_url":146},12557,"如何统一管理和定义不同的搜索源（如 Apple Docs, WWDC Transcripts 等）？","为了解决源定义分散在多个文件中的问题，应创建一个统一的 `SourceDefinition` 结构体。该结构体包含 `id`（如 \"apple-docs\"）、`displayName`（显示名称）、`emoji`（图标）、`properties`（属性）、`intents`（意图集合）以及可选的 `baseURL` 和 `localDirectory`。通过 `SourceRegistry` 进行集中管理，取代原本分散在 `ComposableResult.swift` 和 `Constants.swift` 中的枚举和常量定义，从而简化架构并提高可维护性。","https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fissues\u002F81",{"id":148,"question_zh":149,"answer_zh":150,"source_url":146},12558,"如何实现基于查询意图（Query Intent）的智能搜索结果排序？","通过集成 `QueryIntent` 检测和基于 `SourceProperties` 的评分机制来实现。系统会分析查询意图（如 `apiReference`, `howTo`, `designGuidance`, `languageFeature`, `legacy`），并根据意图提升相应源的排名。例如，检测到 `legacy` 意图时，会优先提升 `apple-archive` 的权重。同时，利用经验质量数据（`searchQuality` 0.0-1.0）影响基础排名，并针对框架名称查询实施直接 URI 查找以绕过 BM25 限制，确保框架页面排名第一。",{"id":152,"question_zh":153,"answer_zh":154,"source_url":146},12559,"系统如何识别和处理关于 Objective-C 或旧版框架的“遗留”查询？","系统新增了 `QueryIntent.legacy` 意图，通过检测特定关键词和框架名来识别。关键词包括 `objective-c`, `objc`, `autorelease`, `selector`, `nib` 等；框架名包括 `carbon`, `cocoa`, `core foundation` 等；以及非 Swift 上下文中的 NS 前缀类（如 `NSObject`, `NSArray`）。一旦识别为遗留查询，系统会优先提升 `apple-archive`（包含 2013-2016 年的旧指南）和 `apple-docs` 的搜索权重，确保用户能找到相关的旧版文档。",{"id":156,"question_zh":157,"answer_zh":158,"source_url":132},12560,"完成文档爬取后，如何更新并发布最新的搜索数据库？","在所有缺失框架抓取完成并重建数据库后，需执行以下步骤：1. 运行 `cupertino save --base-dir ~\u002F.cupertino` 重建搜索数据库；2. 将更新后的文档\u002F数据库发布到指定的 GitHub 仓库（如 `mihaelamj\u002Fcupertino-docs`）；3. 如有必要，更新版本号。此外，还可以按需刷新其他文档源，如 Swift Book、Swift.org 文档和 Swift Evolution 提案。",[160,165,170,175,180,185,190,195,200,204,209,213,217,221,225,229,233,237,242,247],{"id":161,"version":162,"summary_zh":163,"released_at":164},62917,"v0.2.7","## 修复\r\n\r\n  - **搜索排名**：在搜索结果中对发布说明进行降权处理（乘以 2.5 倍），以防止其污染无关查询 (#57)\r\n  - **Swift Evolution 索引**：修正文件名匹配模式，使其符合 `SE-0001.md` 格式 (#61)\r\n  - **数据库重新索引**：在重新索引前先删除数据库，以避免 FTS5 重复行导致数据库体积翻倍 (#62)\r\n  - **服务输出**：简化启动消息，仅显示数据库路径；服务器现在至少需要一个数据库才能启动 (#60)","2025-12-04T13:05:16",{"id":166,"version":167,"summary_zh":168,"released_at":169},62918,"v0.2.6","## 修复\n\n  ### MCP 服务器工具注册 (#55)\n  修复了一个严重 bug：MCP 服务器仅暴露示例代码工具，而未提供文档搜索工具。\n\n  **问题描述：**\n  - 只有 4 个示例代码工具可用（`search_samples`、`list_samples`、`read_sample`、`read_sample_file`）\n  - 缺少 3 个文档工具（`search_docs`、`list_frameworks`、`read_document`）\n\n  **修复内容：**\n  - 使用 `CompositeToolProvider` 实现了组合模式，正确地将请求委派给两个工具提供者\n  - 现在所有 7 个 MCP 工具都已正确暴露给 Claude Desktop 等 AI 客户端\n  - 遵循了良好的关注点分离原则，分别使用了 `DocumentationToolProvider` 和 `SampleCodeToolProvider`\n\n  **影响：**\n  - AI 代理现在可以同时搜索文档数据库和示例代码\n  - Claude Desktop 集成现已获得对所有搜索功能的完全访问权限\n\n  ——\n\n  **完整变更日志：** https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fblob\u002Fmain\u002FCHANGELOG.md#026","2025-12-03T11:51:11",{"id":171,"version":172,"summary_zh":173,"released_at":174},62919,"v0.2.5","## 新增功能\n\n  示例代码访问的 CLI 与 MCP 完全对齐——所有 MCP 工具现在都有对应的 CLI 命令。\n\n  ## 新增 CLI 命令\n\n  | 命令 | 描述 |\n  |---------|-------------|\n  | `list-frameworks` | 列出可用框架及其文档数量 |\n  | `list-samples` | 列出已索引的 Apple 示例代码项目 |\n  | `search-samples` | 搜索示例代码项目和文件 |\n  | `read-sample` | 查看示例项目的 README 和元数据 |\n  | `read-sample-file` | 查看示例项目中的源文件 |\n\n  所有命令均支持 `--format text|json|markdown` 输出格式。\n\n  ## 示例代码索引（自 v0.2.4 起）\n\n  - `cupertino fetch --type samples` - 从 GitHub 克隆 606 个项目（约 4 分钟）\n  - `cupertino index` - 构建 FTS5 搜索索引（18,000 多个文件，192MB 数据库）\n\n  ## 快速入门\n\n  ```bash\n  # 获取并索引示例代码\n  cupertino fetch --type samples\n  cupertino index\n\n  # 搜索和阅读示例\n  cupertino search-samples \"SwiftUI animation\"\n  cupertino read-sample swiftui-building-a-great-mac-app-with-swiftui\n  cupertino read-sample-file swiftui-backyard-birds-sample BackyardBirdsData\u002FAccount\u002FAccount.swift\n\n  关闭了：\n\n  - #36 - 为示例代码建立搜索索引\n  - #51 - 添加用于示例代码搜索的 CLI 命令","2025-12-03T00:50:47",{"id":176,"version":177,"summary_zh":178,"released_at":179},62920,"v0.2.3","## 新增内容\n\n  Cupertino 现在支持 Apple Archive 旧版编程指南——即 2016 年之前的文档，其中包含现代文档中未提供的基础知识。\n\n  ### 新特性\n\n  - **Archive Crawler** —— 获取 Core Animation、Quartz 2D、Core Text、Core Image 等旧版编程指南\n  - **搜索集成** —— Archive 文档已建立索引，并支持框架别名（QuartzCore↔CoreAnimation、CoreGraphics↔Quartz2D）\n  - **智能排序** —— 优先显示现代文档；默认排除 Archive 内容，但可通过标志位访问\n\n  ### 使用方法\n\n  ```bash\n  # 获取 Archive 指南\n  cupertino fetch --type archive\n\n  # 包含 Archive 的搜索\n  cupertino search \"Core Animation\" --include-archive\n\n  # 仅搜索 Archive\n  cupertino search \"CALayer\" --source apple-archive\n\n  MCP 工具\n\n  AI 代理现在可以通过 search_docs 中的 include_archive 参数访问 Archive 文档。\n\n  ---\n  关闭 #41","2025-12-02T21:56:03",{"id":181,"version":182,"summary_zh":183,"released_at":184},62921,"v0.2.2","Cupertino 0.2.2 — 智能类型推断与爬虫恢复修复\n\n> 和描述 \n\n⏺ 通过利用 URL 深度、标题模式和词数等信号，在 type=unknown 时推断文档类型，从而提升搜索排名。核心类型现在即使没有显式类型元数据，也能获得更高的排名。\n\n新增：\n- 智能类型推断启发式规则，以提升搜索排名\n- URL 深度分析（浅层 = 核心类型，深层 = 成员）\n- 标题模式检测（括号 → 方法，驼峰命名 → 类型）\n- 操作符和协议后缀检测\n\n修复：\n- 恢复爬虫会话时的 URL 方案错误 (#47)","2025-12-02T16:17:46",{"id":186,"version":187,"summary_zh":188,"released_at":189},62922,"v0.2.1","---  \n🚀 搜索排名优化 + 重大 Bug 修复  \n\n搜索排名增强功能  \n\n已实现 8 种排名启发式规则，确保核心类型优先排序 (#28)：  \n1. ✅ 标题完全匹配 —— 对于与类型名称完全一致的查询，权重提升 20 倍  \n2. ✅ 以查询开头 —— 当标题以查询词开头时，权重提升 6–7 倍  \n3. ✅ 嵌套类型惩罚 —— 嵌套类型（如 Text.Scale 排在 Text 之后）权重降低 2 倍  \n4. ✅ 按种类加权 —— 核心类型（协议、结构体）权重提升 0.5 倍，成员则权重降低 2.0 倍  \n5. ✅ 查询模式分析 —— 当查询包含“protocol”“class”或“struct”时，相应类型权重提升  \n6. ✅ 上下文感知加权 —— 单词查询命中核心类型时，额外提升 2 倍  \n7. ✅ 长标题惩罚 —— 短查询情况下，对过长标题进行惩罚  \n8. ✅ 内容提取优化 —— 将内容长度从 36K 字符缩减至 2K 字符，以提升 BM25 相关性  \n\n效果：View、Image、List、Form、Picker 现在都能正确排序了！✅  \n\n重大 Bug 修复  \n\n修复了爬虫文件名冲突问题，该问题导致父级文档页面被覆盖 (#45)  \n\n问题描述：  \n- ...\u002FSwiftUI\u002FText → documentation_swiftui_text.json  \n- ...\u002FSwiftUI\u002FText\u002F+(_:_:) → documentation_swiftui_text.json ❌  \n\n因此，Text、Color、Date、String 等核心类型未能收录到搜索索引中。  \n\n解决方案：  \n- ...\u002FSwiftUI\u002FText → documentation_swiftui_text.json ✅  \n- ...\u002FSwiftUI\u002FText\u002F+(_:_:) → documentation_swiftui_text_a1b2c3d4.json ✅  \n\n变更内容  \n\n- @mihaelamj 在 #28 中实现了全面的搜索排名优化  \n- @mihaelamj 在 #45 中修复了爬虫文件名冲突问题  \n- 添加了更友好的元数据 JSON 解码逻辑  \n- 优化了内容索引流程，以提升搜索相关性  \n\n下一步计划  \n\n重新抓取以恢复缺失的父级页面：  \ncupertino crawl --framework swiftui --max-pages 10000  \nrm ~\u002F.cupertino\u002Fsearch.db && cupertino save  \n\n完成重新抓取后，所有优化将生效，搜索排名将完美运行！🎯  \n\n相关 Issue  \n\n- 实现 #28（搜索排名优化）  \n- 修复 #45（文件名冲突 Bug）  \n- 关联 #44（重新抓取任务）  \n\n完整变更日志：https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fcompare\u002Fv0.2.0...v0.2.1","2025-12-02T15:14:31",{"id":191,"version":192,"summary_zh":193,"released_at":194},62923,"v0.2.0","⏺ ## 🚨 Critical Bug Fix\r\n\r\n  Fixes critical bug where `cupertino cleanup` deleted all source code instead of just .git folders (#40).\r\n\r\n  ### What Was Fixed\r\n\r\n  **Problem**: Cleanup was leaving only 981-byte config files and discarding all Swift\u002FObjective-C source code.\r\n\r\n  **Cause**: `compressDirectory()` was compressing only the .git folder due to incorrect directory selection logic.\r\n\r\n  **Solution**: Simplified compression to preserve Apple's flat ZIP structure and all source files.\r\n\r\n  ### Verification\r\n\r\n  ✅ 606\u002F607 sample ZIPs verified with intact source code (99.8%)\r\n  ✅ Space savings: 27GB → 15GB (44% reduction)\r\n  ✅ All code preserved: Swift, Objective-C, C\u002FC++, Metal, JS, Python, Java\r\n\r\n  ### For Affected Users\r\n\r\n  If cleanup deleted your source code, restore from backup or re-download:\r\n  ```bash\r\n  cupertino fetch --type code\r\n  cupertino cleanup  # Now safe\r\n\r\n  Installation\r\n\r\n  git clone https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino.git\r\n  cd cupertino\r\n  git checkout v0.2.0\r\n  make install\r\n\r\n  Full details: https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fblob\u002Fv0.2.0\u002FCHANGELOG.md","2025-12-02T11:59:55",{"id":196,"version":197,"summary_zh":198,"released_at":199},62924,"v0.1.9","Filter search results by programming language (Swift\u002FObj-C) via CLI and MCP. Also adds missing source parameter to MCP search_docs\r\n  tool.\r\n\r\n  ⚠️ Breaking Change: Database schema v5 requires rebuild:\r\n  rm ~\u002F.cupertino\u002Fsearch.db && cupertino save","2025-12-01T22:13:04",{"id":201,"version":202,"summary_zh":79,"released_at":203},62905,"v0.10.0","2026-03-13T15:23:10",{"id":205,"version":206,"summary_zh":207,"released_at":208},62906,"v0.9.1","## 0.9.1 (2026-01-25)\n\n### 新增\n- **MCP 客户端配置文档** - 增加了多个 AI 工具的设置指南 (#134, #137)\n  - OpenAI Codex（CLI 和 ~\u002F.codex\u002Fconfig.toml）\n  - Cursor（.cursor\u002Fmcp.json）\n  - VS Code 配合 GitHub Copilot（.vscode\u002Fmcp.json）\n  - Zed（settings.json）\n  - Windsurf（~\u002F.codeium\u002Fwindsurf\u002Fmcp_config.json）\n  - opencode（opencode.jsonc）\n- **二进制文件文档** - 为更多可执行文件提供了完整文档 (#137)\n  - cupertino-tui：带有 5 种视图的终端 UI，并附有详细文档\n  - mock-ai-agent：MCP 测试工具，参数说明已完善\n  - cupertino-rel：发布工具，包含 6 个子命令及所有选项\n  - docs\u002Fbinaries\u002F 目录下新增 48 份文档文件\n- **mock-ai-agent --version** - 增加了版本标志支持 (#137)","2026-01-25T13:18:04",{"id":210,"version":211,"summary_zh":79,"released_at":212},62907,"v0.9.0","2025-12-31T16:58:07",{"id":214,"version":215,"summary_zh":79,"released_at":216},62908,"v0.8.2","2025-12-28T12:22:56",{"id":218,"version":219,"summary_zh":79,"released_at":220},62909,"v0.8.1","2025-12-28T10:52:15",{"id":222,"version":223,"summary_zh":79,"released_at":224},62910,"v0.8.0","2025-12-20T00:49:01",{"id":226,"version":227,"summary_zh":79,"released_at":228},62911,"v0.7.0","2025-12-15T01:32:35",{"id":230,"version":231,"summary_zh":79,"released_at":232},62912,"v0.6.0","2025-12-12T02:04:29",{"id":234,"version":235,"summary_zh":79,"released_at":236},62913,"v0.5.0","2025-12-11T00:51:47",{"id":238,"version":239,"summary_zh":240,"released_at":241},62914,"v0.4.0","## 新增功能\n\n  ### 人机界面指南支持\n  - `cupertino fetch --type hig` - 爬取 Apple 的 HIG 文档\n  - `search_hig`：用于搜索设计指南的 MCP 工具\n  - 可按平台（iOS、macOS、watchOS、visionOS、tvOS）和类别进行筛选\n  - 新增 `hig:\u002F\u002F` URI 方案，用于访问文档\n\n  ### 框架别名搜索\n  - 搜索支持所有框架名称变体：`QuartzCore`、`CoreAnimation` 或 `Core Animation`\n  - 已索引 249 个框架别名，提升可发现性\n\n  ### 修复\n  - 修复 Swift.org 基础 URL（`docs.swift.org` → `www.swift.org\u002Fdocumentation\u002F`）\n  - Swift.org 索引器现能正确处理 JSON 文件\n  - Swift Evolution 默认仅显示已接受或已实现的提案\n  - 简化了爬虫进度显示\n\n  ## 已关闭的问题\n  #69、#91、#92、#93、#94","2025-12-09T02:12:30",{"id":243,"version":244,"summary_zh":245,"released_at":246},62915,"v0.3.4","## 一键安装 🚀\n\n只需一条命令即可安装 Cupertino：\n\n```bash\nbash \u003C(curl -sSL https:\u002F\u002Fraw.githubusercontent.com\u002Fmihaelamj\u002Fcupertino\u002Fmain\u002Finstall.sh)\n```\n\n新功能\n\n- 一键安装程序：自动下载二进制文件和数据库\n- 预编译的通用二进制文件（arm64 + x86_64）\n- 使用开发者 ID 应用程序证书进行代码签名\n- 已通过 Apple 的公证流程，可获得 Gatekeeper 的批准\n- 包含资源包，用于 `cupertino save` 命令\n\n关闭 #79、#82","2025-12-05T22:29:06",{"id":248,"version":249,"summary_zh":250,"released_at":251},62916,"v0.3.0","  ## 亮点\n\n  - **`cupertino setup`** - 在约30秒内下载预构建的数据库\n  - **`cupertino release`** - 自动化数据库发布（仅限维护者）\n  - CLI与数据库版本保持一致\n\n  ## 快速入门\n\n  ```bash\n  cupertino setup\n  cupertino serve\n\n  新增内容\n\n  - `setup` 命令 - 从 GitHub Releases 下载预构建的数据库\n  - `release` 命令 - 将数据库打包并上传至 GitHub\n  - 下载过程中显示带有旋转动画的进度条\n  - 版本一致性 - CLI 版本与发布标签一致，确保模式兼容性\n\n  变更内容\n\n  - 更新了 README 中的快速入门流程\n  - 现已记录 `--remote` 标志作为替代方案（约需45分钟构建）\n\n  完整变更日志\n\n  请参阅：https:\u002F\u002Fgithub.com\u002Fmihaelamj\u002Fcupertino\u002Fblob\u002Fmain\u002FCHANGELOG.md\n\n  关闭了\n\n  #52、#65、#66","2025-12-05T01:41:22"]