WinClaw CLI 工具设计指南：为 AI Agent 构建标准化能力接口

你可以给 AI 一个工具。但更好的做法是：告诉它怎么发现工具、怎么理解工具、怎么组合工具。 WinClaw 的 CLI 工具体系，就是为此而设计的。

---

一、AI 时代，工具开发的逻辑变了

过去做 CLI 工具，用户是人。帮助文档写给人看，参数设计按人的习惯来，输出格式怎么好看怎么来。

但在 WinClaw 的世界里，工具的第一用户是 AI Agent。

AI 不看 README，不逛 Stack Overflow，不读博客教程。它拿到一个工具，做三件事：

1. 读 --help，知道这个工具能干什么、有哪些参数
2. 读 --skill，理解在什么场景下、按什么流程使用这个工具
3. 解析 JSON 输出，把结果传给下一个工具或直接呈现给用户

如果你的工具不支持这三步，AI 就用不好它——不是 AI 笨，是你的工具没为它设计过。WinClaw 的 CLI 工具开发体系，把这个问题彻底标准化了。

---

二、先搞清楚你要写哪种工具

不是所有工具都一样。根据运行方式和状态需求，WinClaw 把 CLI 工具分成三种类型：

类型	一句话描述	典型场景	代表工具
普通 CLI	跑一下就退出，无状态	发消息、转格式、导数据	agent_feishu, agent_excel, markdown2word
Daemon CLI	后台常驻，维持连接	微信代理、定时调度	wechat_agent, agent_cron
Session CLI	跨调用记住上下文	多轮对话、增量操作	agent_cursor

怎么选？一个简单的决策树：

你的工具需要后台持续运行吗？
  ├── 是 → Daemon CLI
  └── 否 → 多次调用之间需要记住上下文吗？
            ├── 是 → Session CLI
            └── 否 → 普通 CLI ✓（80% 的情况选这个）

优先选普通 CLI。 它最简单、最好测、最容易和别的工具组合。只有当普通 CLI 明确搞不定时，才升级到 Daemon 或 Session。

---

三、所有工具的共同基因：渐进式披露 + 统一输出

不管你选了哪种类型，有两件事是必须做的。这是 WinClaw 工具生态的基石。

渐进式披露：让 AI 按需获取信息

WinClaw 设计了一套三层信息架构，AI 可以从浅到深逐层理解你的工具：

第一层: tool --help         → 功能概览、命令列表、快速入门
第二层: tool <cmd> --help   → 某个子命令的参数详情
第三层: tool --skill        → 完整最佳实践、工作流、场景指南

--help 回答「能做什么」，--skill 回答「该怎么用」。 这个区分至关重要。

拿 agent_feishu 举例。AI 第一次碰到这个工具时，先看 --help：

agent_feishu is a command-line tool that provides Feishu (Lark) bot operations
through a set of composable commands, designed for AI agent workflows.

Quick Start:
  agent_feishu initapi --app-id "cli_xxx" --app-secret "xxx"
  agent_feishu send-text --receive-id "ou_xxx" --text "Hello!"

Use 'agent_feishu --skill' for detailed command specifications.

够了。AI 知道这是个飞书工具，能发消息，需要先 initapi。但如果任务更复杂——比如“查找张三的飞书 ID 然后给他发条消息”——AI 会进一步看 --skill，里面写着完整的用户查找流程：

User Management Workflow:
  1. Search local cache first (fast): agent_feishu search-users --query "name"
  2. If not found, sync from Feishu: agent_feishu sync-users --force
  3. Retry search after sync

--skill 不是给人看的文档，是给 AI 看的操作手册。 它告诉 AI 在什么场景下、按什么顺序、调什么命令。

统一 JSON 输出：工具之间的通用语言

所有工具的输出都遵循同一个格式：

// 成功
{
  "success": true,
  "data": {
    "message": "Text message sent successfully",
    "message_id": "om_xxx"
  }
}

// 失败
{
  "success": false,
  "error": "API credentials not configured. Run 'agent_feishu initapi' first"
}

三个字段：success、data、error。没了。

这意味着 AI 可以把任意两个工具串起来用。查到的飞书用户 ID，直接传给发消息命令；导出的 Excel 数据，直接交给下一个工具处理。工具之间不需要互相 import，一个 JSON 管道就串通了。

而且注意看失败时的 error 信息：“Run 'agent_feishu initapi' first”——直接告诉 AI 下一步该执行什么命令。AI 不需要查文档就知道怎么修复。

---

四、普通 CLI：最常见的 80%

大多数工具是普通 CLI——接收参数，执行操作，返回结果，退出。没有后台进程，没有状态文件，干干净净。

开发一个普通 CLI 工具，核心就是做好以下几件事：

1. 根命令 --help：功能概述 + Quick Start + 命令列表
2. --skill 标志和 skill 子命令：完整的场景操作指南
3. 子命令 --help：每个子命令的参数描述和示例
4. 全局 --json 标志：统一 JSON 输出
5. version 命令：版本信息

项目结构清晰明了：

agent_feishu/
├── main.go
├── go.mod
├── cmd/
│   ├── root.go           # 根命令
│   ├── skill.go          # --skill 输出
│   ├── send_text.go      # 发送文本
│   ├── send_image.go     # 发送图片
│   └── initapi.go        # 初始化凭证
└── internal/
    └── output/
        └── output.go     # 统一输出

如果你是第一次给 WinClaw 写工具，从普通 CLI 开始。 一个下午就能搞定。

---

五、Daemon CLI：当工具需要“一直活着”

有些事情，调用即退出搞不定。

微信消息代理需要维持一个长连接才能收发消息——每次都重新登录？扫码都来不及。定时调度需要在后台按计划执行任务——终端一关就没了？那还定什么时。

这些场景需要 Daemon CLI：后台常驻一个进程，CLI 命令通过本地 HTTP API 和它通信。

┌──────────────────┐          HTTP API          ┌───────────────────┐
│   CLI 命令       │  ─────────────────────►   │   Daemon 进程     │
│                  │                             │                   │
│  tool start      │  启动 daemon                │  常驻后台运行     │
│  tool status     │  查询状态                   │  提供 HTTP API    │
│  tool stop       │  停止 daemon                │  管理会话/心跳    │
│  tool send       │  业务操作 ──────────────►  │                   │
└──────────────────┘          ◄────────────────  └───────────────────┘
                               JSON 响应

用户和 AI 感知到的还是 CLI 命令，体验和普通工具一样。区别在于命令不再直接执行业务逻辑，而是把请求转发给后台 Daemon。

Daemon CLI 有几个关键设计：

• 自启动：tool start 启动自身的一个子进程并分离，用户终端不会被阻塞
• 状态文件：通过 PID 文件和端口文件让 CLI 找到正在运行的 Daemon
• 仅监听 127.0.0.1：HTTP API 只在本地可访问，不暴露到网络
• 心跳保活：连接断了自动重连，异常不终止进程
• 优雅停止：清理资源、删除状态文件

什么时候用 Daemon？记住四个条件，满足任一即可：

• 需要维持长连接（微信、WebSocket）
• 初始化成本高，需要复用（大型 SDK、连接池）
• 需要后台持续执行（定时任务）
• 多次调用共享状态（登录会话、联系人缓存）

---

六、Session CLI：记住上一次聊到哪了

Session CLI 解决的问题很直观：多轮操作之间保持上下文。

agent_cursor 是典型例子。你让 AI 分析代码架构，然后基于分析结果重构某个模块——这是两次调用，但第二次必须知道第一次的结果。

# 第一轮：分析
agent_cursor run “分析这个项目的架构” --session main

# 第二轮：基于分析继续
agent_cursor run “基于刚才的分析，重构 auth 模块” --session main
# AI 自动恢复上下文，知道“刚才的分析”是什么

Session 和 Daemon 的区别是：Session 不需要后台常驻进程。工具还是“调用即退出”的，只是在调用之间通过文件保存上下文标识（比如一个 session_id）。

实现上也很简单：

• 全局 --session 标志：指定会话别名
• 自动恢复：执行前检查是否有同名 Session，有就自动 resume
• 自动保存：执行后把新的 session_id 写入文件
• 管理子命令：session ls / session show / session rm

Session 数据存在 ~/.agent_cursor/sessions/main.json 这样的文件里，结构很轻量：

{
  "name": "main",
  "sessionId": "abc123",
  "cwd": "/Users/me/project",
  "createdAt": "2026-03-14T10:00:00Z",
  "updatedAt": "2026-03-14T10:30:00Z"
}

---

七、三种类型的对比

维度	普通 CLI	Daemon CLI	Session CLI
运行模式	执行即退出	后台常驻	执行即退出
状态管理	无	Daemon 进程内	文件持久化
进程数	0（用完即走）	1（常驻）	0（用完即走）
复杂度	★	★★★	★★
适用比例	~80%	~10%	~10%
核心要求	--help, --skill, --json	+ start/stop/status, HTTP API	+ --session, 自动 resume

---

八、写在最后

给 AI 写工具，和给人写工具，是两件完全不同的事。

人可以看文档、搜社区、试错纠正。AI 需要的是结构化的自描述——--help 让它快速了解能力边界，--skill 让它掌握操作流程，统一 JSON 让它无缝串联多个工具。

WinClaw 的 CLI 工具体系，本质上做了一件事：定义了 AI 和工具之间的沟通协议。

你不需要写一个“聪明”的工具——你需要写一个“说得清楚”的工具。AI 自己够聪明，它只需要你把话说明白。

三种类型、三层披露、一套 JSON 格式。掌握这些，你就能给 WinClaw 的工具商店贡献工具，让全世界的 AI Agent 用上你写的能力。想了解更多类似的开源项目实战经验，欢迎来云栈社区交流探讨。

好的工具不需要解释自己——但它必须能解释给 AI 听。