Mcd Desktop Pet

便利贴桌面宠物 Agent 技能规范 (mcd-desktop-pet)

本技能赋予 AI Agent（Claude Code、Cursor、Antigravity、Codex 等）通过标准化统一命令行工具 (mcd-desktop-pet) 操控本地桌面宠物与管理桌面便利贴系统的能力。

一、 核心交互规范

1. 统一小写命令行：CLI 命令严格采用全小写 mcd-desktop-pet（Windows 下为 mcd-desktop-pet.exe 或 mcd-desktop-pet.cmd），无任何短别名，保持标志唯一确定。
2. 默认 JSON 输出：所有 CLI 命令的结果均默认输出为纯 JSON，标准输出（stdout）严格保留给 JSON 结果，诊断日志统一输出至标准错误（stderr）。AI Agent 无需追加 --json 即可直接解析。
3. 确定性退出码：
   • 成功：退出码为 0，标准输出输出有效 JSON 对象或数组。
   • 失败：非零退出码，标准输出输出统一错误结构 {"error": "错误原因说明"}。
4. 统一入口与复用：无参数运行主程序严格等同于 mcd-desktop-pet start。若服务或桌宠已在运行中，start 会自动复用已有实例，避免重复创建。

二、 自然语言意图到 CLI 命令映射表

1. 便利贴生命周期管理 (Note Operations)

2. 系统生命周期与控制台 (System & Web)

三、 Agent 场景演练与调用范式

场景 1：用户让 Agent 记录灵感或待办

用户输入：“帮我记一张便签：周五前要完成文档评审” Agent 执行：

bashCopy code
mcd-desktop-pet note create --text "周五前要完成文档评审"

CLI 输出 (stdout)：

jsonCopy code
{
  "id": "note_5fa21d9b",
  "summary": "周五前要完成文档评审",
  "status": "active"
}

Agent 回复：“已经帮您在桌面上贴好新便签：‘周五前要完成文档评审’（流水号 note_5fa21d9b）📝✨”

场景 2：用户让 Agent 查看当前便签并归档完成项

用户输入：“看看我桌面上有什么便签，把刚才评审文档的那张归档了” Agent 执行 1：

bashCopy code
mcd-desktop-pet note list --status active

CLI 输出 1：

jsonCopy code
[
  {
    "id": "note_5fa21d9b",
    "summary": "周五前要完成文档评审",
    "status": "active"
  }
]

Agent 执行 2：

bashCopy code
mcd-desktop-pet note archive note_5fa21d9b

CLI 输出 2：

jsonCopy code
{
  "id": "note_5fa21d9b",
  "summary": "周五前要完成文档评审",
  "status": "archived"
}

Agent 回复：“查找到桌面上有一张便签‘周五前要完成文档评审’，已为您盖章出餐并安全归档至历史便签盒！🍟✓”

场景 3：快速检查运行状态与打开大屏

用户输入：“桌宠还在跑吗？帮我打开便签大屏” Agent 执行 1：

bashCopy code
mcd-desktop-pet status

Agent 执行 2：

bashCopy code
mcd-desktop-pet web

Agent 回复：“当前中枢服务正常运行中。已在您的浏览器中打开历史便签盒大屏，您可以在瀑布流中浏览所有历史备忘与出餐记录！🌐”

四、 交付形态与直接调用指引 (Delivery & Invocation)

本项目交付物为完全自包含的独立预编译二进制与应用包，无需执行任何安装、配置或卸载脚本，下载即用：

• macOS：交付单应用包 mcd-desktop-pet.app。双击直接启动桌宠；AI Agent 或终端可直接带参数调用包内主程序：

  bashCopy code
  # 直接调用应用包内主程序（默认输出 JSON）
  /Applications/mcd-desktop-pet.app/Contents/MacOS/mcd-desktop-pet note create --text "待办事项"
  /Applications/mcd-desktop-pet.app/Contents/MacOS/mcd-desktop-pet note list --status active
  /Applications/mcd-desktop-pet.app/Contents/MacOS/mcd-desktop-pet status
  

  (若已将应用包主程序创建符号链接至 /usr/local/bin 或系统 PATH，可简写为 mcd-desktop-pet)

• Windows：交付单可执行文件 mcd-desktop-pet.exe。双击直接启动桌宠；AI Agent 或终端可直接在命令行调用：

  powershellCopy code
  # 直接调用可执行文件（默认输出 JSON）
  .\mcd-desktop-pet.exe note create --text "待办事项"
  .\mcd-desktop-pet.exe note list --status active
  .\mcd-desktop-pet.exe status
  

五、 错误处理与规范约定

1. 退出码机制：所有命令成功时返回退出码 0，失败时返回非零退出码。
2. 错误响应格式：当命令执行遇到错误时，标准输出均返回标准的 JSON 错误结构，便于 Agent 准确捕获：

   jsonCopy code
   {
     "error": "note not found: note_xxx"
   }
   

3. 静默与纯粹性：Go 主程序在 CLI 模式下，标准输出（stdout）严格保留给机器可解析的 JSON 结果，任何运维诊断日志统一打到标准错误（stderr），AI Agent 可直接使用 JSON.parse() 解析结果。