WinClaw CLI 工具开发指南

你可以给 AI 一个工具。但更好的做法是告诉它怎么发现工具、怎么理解工具、怎么组合工具。WinClaw 的 CLI 工具体系就是为此而设计的。一、AI 时代工具开发的逻辑变了过去做 CLI 工具用户是人。帮助文档写给人看参数设计按人的习惯来输出格式怎么好看怎么来。但在 WinClaw 的世界里工具的第一用户是 AI Agent。AI 不看 README不逛 Stack Overflow不读博客教程。它拿到一个工具做三件事读--help知道这个工具能干什么、有哪些参数读--skill理解在什么场景下、按什么流程使用这个工具解析 JSON 输出把结果传给下一个工具或直接呈现给用户如果你的工具不支持这三步AI 就用不好它——不是 AI 笨是你的工具没为它设计过。WinClaw 的 CLI 工具开发体系把这个问题彻底标准化了。二、先搞清楚你要写哪种工具不是所有工具都一样。根据运行方式和状态需求WinClaw 把 CLI 工具分成三种类型类型一句话描述典型场景代表工具普通 CLI跑一下就退出无状态发消息、转格式、导数据agent_feishu, agent_excel, markdown2wordDaemon CLI后台常驻维持连接微信代理、定时调度wechat_agent, agent_cronSession 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 第一次碰到这个工具时先看--helpagent_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 工具核心就是做好以下几件事根命令--help功能概述 Quick Start 命令列表--skill标志和skill子命令完整的场景操作指南子命令--help每个子命令的参数描述和示例全局--json标志统一 JSON 输出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.1HTTP 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 rmSession 数据存在~/.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 }七、三种类型的对比维度普通 CLIDaemon CLISession 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 用上你写的能力。WinClaw CLI 工具开发文档已上线。 完整文档https://docs.winclaw.cc/docs/cli-tool-development好的工具不需要解释自己——但它必须能解释给 AI 听。