M1K3

M1K3 for macOS — 从源代码构建

旗舰体验：原生 Mac SwiftUI 应用 — 设备端 MLX 推理、实时语音（Kokoro TTS + WhisperKit STT）、支持 RAG 的个人知识图谱、内嵌 Agent、3D 助手，以及可供其他 Agent 调用的本地 MCP 服务。

隐私融入设计。 M1K3 在你的 Mac 上运行。模型从 Hugging Face 下载一次；此后，网络仅用于网页搜索。网页搜索默认开启，以便回答及时更新；你可以在“设置”中通过一个开关将其关闭。（后续版本将加入可选启用的 Apple Private Cloud Compute 选项；1.0 版本不使用云端。）

要求

• macOS 26（Tahoe），运行于 Apple Silicon — 必要条件：应用使用 Liquid Glass、设备端 Foundation Models，以及通过 MLX 使用 Metal。
• Xcode 26.x（Swift 6.2 工具链）。
• XcodeGen 和（可选，日志更易读）xcbeautify： brew install xcodegen xcbeautify
• 磁盘空间：默认大脑无需下载任何内容（Mini 使用 Apple 的设备端模型）。只有选择更大的 Lil / Big 大脑时，才需额外预留约 2–7 GB。

构建和运行

git clone https://github.com/Round-Tower/M1K3.git
cd m1k3/macos

# project.yml is the source of truth — M1K3.xcodeproj is generated, not tracked
xcodegen generate

open M1K3.xcodeproj    # then ⌘R (set your own dev team for local signing)

或者从命令行运行：

xcodebuild -scheme M1K3 -destination 'platform=macOS' build | xcbeautify
# The same package graph also drives the iOS + visionOS shell (M1K3iOSApp/):
xcodebuild -scheme M1K3iOS       -destination 'generic/platform=iOS Simulator'      build | xcbeautify
xcodebuild -scheme M1K3visionOS  -destination 'generic/platform=visionOS Simulator' build | xcbeautify

首次启动只需一个界面：打个招呼（姓名可选），就能开始对话 — M1K3 默认使用 Mini，也就是 Apple 内置的设备端模型，因此无需下载任何内容。你可以在“设置”中一键切换到能力更强的本地大脑（Lil / Big），也可以在首次回答后通过聊天中的提示切换；只有在你提出请求时才会下载模型权重。

**签名说明：**使用你的个人开发团队运行。使用 CODE_SIGNING_ALLOWED=NO 构建虽然可以成功（CI 会这样做），但应用随后运行时将没有沙盒容器，并会在错误的数据位置读写。

测试

业务逻辑位于 SwiftPM 包中，无需 Xcode 即可测试：

swift test --parallel --disable-xctest   # the full fast suite (CI runs it without the flag)
tools/dev/tdd.sh M1K3KnowledgeTests     # one test target, rebuilt and run alone

测试使用 swift-testing（import Testing、@Test），而不是 XCTest。

重量级的 MLX/Metal 集成测试默认由环境变量控制并关闭 — 运行 M1K3_MLX_INTEGRATION=1 swift test 可启用（会下载真实模型并生成内容；仅限 Apple Silicon）。

目录说明

M1K3App/	macOS 应用外壳：SwiftUI 视图、AppEnvironment、设置
M1K3iOSApp/	基于共享 Sources/ 图谱的 iOS + visionOS SwiftUI 外壳（M1K3iOS/M1K3visionOS schemes）
Sources/	SwiftPM 模块：Agent、推理、知识/RAG、语音、MCP
Tests/	各模块的 swift-testing 测试套件
project.yml	XcodeGen 配置（.xcodeproj 是构建产物）
ROADMAP.md	后续计划 — 持续更新
PLAN.md	历史构建日志 / 决策记录（仅追加，已签名）
docs/	ADR、模型选择、MCP 配置、发布流程

MCP 服务

运行中的应用通过 HTTP 在 http://127.0.0.1:4242/mcp 提供 MCP 服务 — 支持知识搜索、文档、语音，以及 ask_m1k3（向驻留 AI 提问）。 请参阅 docs/MCP_SETUP.md，了解如何将其接入 Claude Code 或任何 MCP 客户端。

参与贡献

请参阅仓库根目录中的 CONTRIBUTING.md。发现 Bug？ 在应用中选择：设置 → 报告问题…，即可生成经过隐私处理的诊断信息，你可以将其附加到 GitHub issue。