Calendar Agent

00 · PROJECT OVERVIEW

我到底做了什么？

用户提交自然语言会话请求，AgentRuntime 管理任务和参数，Tool Execution Layer 把受约束的操作交给 MacAgentHost，EventKit 产生真实 Calendar 状态，Verification 再决定最终响应。

当前能力状态

01 · FROM IDEA TO PROTOTYPE

从 Idea 到第一个 Agent Prototype

最初的问题是：如果我对 Siri 说一句自然语言，能不能让自己的 Agent 真正理解并操作 Calendar？最早的抽象只有三层：Natural Language → Agent → Calendar Action。

UserRequest
    ↓
AgentRuntime
    ↓
LLM / Semantic Analysis
    ↓
Planner
    ↓
Mock Tool
    ↓
Final

先使用 Mock Tool，是为了验证 Agent Core、Task、Parameter、Planner 和 Tool Contract，而不是一开始就同时处理 macOS 权限、EventKit、网络和 Siri。

02 · BUILDING THE AGENT CORE

Agent 到底比普通 API 多了什么？

“明天下午三点开一个小时会议”不能直接变成 API 参数，而要经过语义分析、任务状态和规划。参数拥有 value、source、status；任务拥有 conversation、task、step 等关联。

User Request
    ↓
Semantic Analysis
    intent = create
    object = calendar_event
    date = tomorrow
    start = 15:00
    duration = 60
    ↓
Task / Parameter State
    ↓
Planner → Tool Contract

03 · CONNECTING TO THE REAL WORLD

从 Mock Tool 到真实 macOS Calendar

Mock Tool 只能证明 Agent 认为自己执行了操作，不能证明 Calendar 真的发生了变化。于是执行边界进入一个拥有 macOS 权限的原生 Host。

AgentRuntime → Tool Request
             → MacAgentHost.app
             → EventKit
             → macOS Calendar
             → query_calendar / Verification

Python Runtime 与 macOS Calendar Permission Boundary 不是同一个边界，所以使用 MacAgentHost、EventKit 和 JSON-lines contract 连接两侧。

04 · FROM MAC TO IPHONE & SIRI

从 Mac localhost 到 Siri / iPhone

Mac 上能运行只是开始。Personal Agent 需要从 Terminal 走向 iPhone、Shortcut 和 Siri。

localhost 127.0.0.1:8000
        ↓
LAN access
        ↓
DHCP address changed
        ↓
stable HTTPS endpoint
        ↓
Cloudflare Named Tunnel → 127.0.0.1:8000

这条链路带来了鉴权、Bearer Token、HTTPS、localhost-only Agent Server 和不暴露公网 8000 端口等安全边界。公网与真机连接仍需单独验收。

05 · MULTI-TURN AGENT

从单轮命令到真正的多轮 Agent

用户说“明天开会”时，Agent 不能猜开始时间和时长。它应该进入 waiting_clarification，向用户提问，再用同一个 conversation 找回原来的 task。

same conversation → find waiting task
        ↓
same task_id → analyzing_clarification
        ↓
parameter merge → planning → tool → verification

Clarification Resume 已在代码中实现，但真实 iPhone/Siri 多轮回归仍在进行，因此标记为“实现中 / 真机验证中”。

06 · ARCHITECTURE EVOLUTION: V1 → V2

从 Protocol V1 到 V2：一次真实的 Architecture Reconciliation

Client → Agent → Tool Request
       → Client executes Tool
       → Tool Result → Agent

Client → AgentRuntime
       → Tool Execution Layer
       → MacAgentHost → EventKit

真实实现逐渐形成后，Specification ≠ Implementation，Architecture Drift 暴露出来。之后才有 Audit、Conflict Discovery、Reconciliation、ADR 和 Protocol V2。V1 没有被删除，而是作为历史版本保留。

07 · RELIABILITY & VERIFICATION

Agent 怎么证明自己真的完成了任务？

核心原则是：Tool Success ≠ Task Success。只有真实状态经过 Verification，Agent 才能返回 Final.success。

Tool Execution → Tool Result
              ↓
       query_calendar / verify_state
              ↓
 compare event_id · title · start · end
              ↓
Verified → success | mismatch → failure | unknown → unknown

这一章还要处理 operation_id、重复防护、Retry、Unknown、Pre-execution safety 和 EventKit 的真实状态。系统不宣称 exactly-once。

08 · AGENT QA & EVALUATION

做完 Agent 以后，我到底怎么测它？

Agent QA 不是最后跑一遍测试，而是贯穿 Agent 构建过程：确定性测试、Agent Evaluation、Observability、Integration、E2E 和 Regression。

09 · WHAT BROKE ALONG THE WAY

真实故障时间线

NEXT · PERSONAL AGENT

Calendar 只是第一个 Capability

下一步是 Production LLM、Agent Eval Dataset、Automated Evaluation 和 Continuous Evaluation；更远的路线才是 Reminder、Mail、Files、Obsidian、Browser、Computer Use，最终走向 Personal Agent。