个人助手 Agent —— 产品与技术方案

基于 Pi Agent 的三层架构思想，从零实现一个跑在 Mac 上、接 DeepSeek、能操作你个人事务的助手 agent。

第一部分 · 产品方案

1. 产品定位

一句话：一个运行在你自己 Mac 上、接 DeepSeek、能通过自然语言操作「提醒事项 / 备忘录 / iMessage / 邮件 / 日历 / 搜索」的个人助手 agent。

关键属性：

2. 核心价值

3. 目标用户

• 你自己（贺培文），个人生产力场景，非团队协作。

4. 功能清单

MVP（第一版，先跑通闭环）

进阶（第二阶段）

5. 典型使用场景（对话式）

6. 与现有工具的关系（为什么还要做）

核心动机：不是替代 Hermes/Codex，而是用 Pi 的架构思想亲手做一个完全属于自己的 agent，既是学习 Pi 内核，也是拿到一个可无限定制的个人生产力底座。

第二部分 · 技术方案

7. 技术选型（对抗式审查）

8. 架构设计（复用 Pi 三层）

┌────────────────────────────────────────────────┐
│  产品层（CLI 常驻对话）                          │
│  · 会话 JSONL + memory.md + 工具注册 + 权限审批    │
├────────────────────────────────────────────────┤
│  内核层：Agent 状态机 + runAgentLoop + hooks      │
│  · beforeToolCall（危险工具→确认）/ afterToolCall │
├────────────────────────────────────────────────┤
│  适配层：Message/Tool/Event 协议 + DeepSeekProvider│
└────────────────────────────────────────────────┘

Pi 三层分工（本方案完整复用）：

两个边界（个人助手的安全地基）：

1. LLM 边界：进模型前把内部消息转成 DeepSeek 格式，出模型后统一成自己的事件协议——上层循环永远不感知供应商差异。
2. 副作用边界：模型不能直接发消息/改日程，只能提 tool call；副作用在本地工具执行，被 beforeToolCall 拦住审批。

9. 核心模块

Agent Loop 骨架（所有框架绕不开的，照 Pi 极简版）：

async function runAgentLoop(context, config) {
  while (true) {
    const assistant = await streamAssistantResponse(context, config);
    context.messages.push(assistant);
    const toolCalls = assistant.content.filter(b => b.type === "toolCall");
    if (toolCalls.length === 0) return;          // 无工具调用 = 结束
    for (const call of toolCalls) {
      const tool = context.tools.find(t => t.name === call.name);
      const result = await tool.execute(call.arguments);
      context.messages.push(toToolResultMessage(call, result)); // 结果写回再循环
    }
  }
}

10. 工具底座（真实可落地）

工具 = JSON Schema（给模型看参数）+ execute 函数（包装 CLI）。

工具 schema 示例：

// 把 remindctl 包成 agent 工具
{
  name: "add_reminder",
  description: "在 Apple 提醒事项新建提醒，可设到期时间和列表",
  parameters: {
    type: "object",
    properties: {
      title: { type: "string", description: "提醒内容" },
      due:  { type: "string", description: "到期时间，如 'tomorrow' 或 '2026-09-20 14:00'" },
      list: { type: "string", description: "列表名，如 工作/个人" },
    },
    required: ["title"],
  },
  execute: async (args) =>
    exec(`remindctl add --title "${args.title}" --due "${args.due ?? "today"}"`),
}

11. 安全边界（个人助手比 coding agent 更敏感）

一次对话链路（比 coding agent 多两处：记忆注入 + 审批）：

用户输入 → 构造上下文（注入 memory.md + 会话历史 + 工具 schema）
  → runAgentLoop → DeepSeek 返回 toolCall
  → beforeToolCall：danger? 弹确认 : 放行
  → 执行工具 → 结果写回 → 再请求模型
  → 无工具调用 → 返回答案 → 持久化会话

12. 落地步骤（7 步，每步可验收）

先做 MVP：提醒 + 笔记 + 搜索三个工具跑通全链路（工具 → 审批 → 记忆 → 对话），再逐步加消息/邮件。

不要一开始就做（Pi 的反模式）：接真模型前先跑通 Mock、别做多 session UI、别做完整权限审批（先路径限制 + 工具白名单）、别做漂亮动画。

13. 风险与对策

第三部分 · 落地计划

下一步：确认方案后，从「装工具底座 + 起项目骨架 + 写 shared 协议」开始动手。

方案基于 Pi Agent（pi.dev / how-pi-agent-works）三层架构思想，工具底座复用本机 macOS CLI（steipete/tap 系列）。