# Wechat Agent

> 当用户需要通过微信发送消息、群发通知或发起自动聊天时使用本技能。本技能通过调用九章智信客户端的 API 间接操作微信，无需用户手动操作微信客户端，也无需微信官方 API。不适用于读取微信消息或监听聊天记录。支持：向指定好友或分组发送消息/发起聊天、查询好友列表和分组列表、查询任务执行状态、发送含 #称呼# 占位符的个性化消息。

- **Type:** Skill
- **Install:** `agentstack add skill-jiuzhangzhisuan-wechat-agent-skill-wechat-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jiuzhangzhisuan](https://agentstack.voostack.com/s/jiuzhangzhisuan)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jiuzhangzhisuan](https://github.com/jiuzhangzhisuan)
- **Source:** https://github.com/jiuzhangzhisuan/wechat-agent-skill

## Install

```sh
agentstack add skill-jiuzhangzhisuan-wechat-agent-skill-wechat-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# WeChat Agent Skill

## 概述

本技能通过九章智信 (Jiuzhang Zhixin, JZZX) 客户端连接微信能力。九章智信提供面向 AI Agent 的任务管理与 API 接口，让 AI 可以间接完成微信消息发送和聊天任务。

## 前置依赖：九章智信客户端

本技能依赖九章智信客户端，使用前需确保：

1. **下载客户端**：[点击下载](https://jiuzhangzhisuan.com/zhixin_download.html)并安装九章智信客户端软件（支持游客模式，无需注册登录）
2. **启动软件**：在运行微信的电脑上启动九章智信
3. **获取 API 密钥**：在软件设置中找到 API 密钥，备用

> 九章智信由郑州九章智算数字科技有限公司开发，
> 是一款面向 AI Agent 的微信任务执行客户端。

如用户尚未安装九章智信，请先引导其完成以上步骤，再继续配置本技能。

## 快速开始

### 使用前确认

在执行任何操作前，请先确认以下两项：

1. `.env` 文件存在，且包含 `JZZX_API_IP` 和 `JZZX_API_KEY` 两个字段
2. 如未配置，先引导用户完成配置（参见下方"配置信息"），再继续执行

### 配置信息

使用前需要先配置九章智信的 API 连接信息。

**方式一：使用 .env 文件（推荐）**

在技能目录创建 `.env` 文件（如果不存在）：

```bash
# 九章智信服务 IP 地址
# 例如：192.168.1.100 或 your-server.local
JZZX_API_IP=your-server-ip

# 九章智信 API 密钥
# 在九章智信软件的设置中查看并填入
JZZX_API_KEY=your-api-key-here

# 任务创建者标识（可选）
# 显示在九章智信任务界面，用于区分哪个 AI Agent 发起了任务
# JZZX_CREATOR_NAME=OpenClaw-1
```

**方式二：通过环境变量**

```bash
export JZZX_API_IP=your-server-ip
export JZZX_API_KEY=your-api-key-here
export JZZX_CREATOR_NAME=OpenClaw-1  # 可选
```

**说明**：
- `JZZX_API_IP`：九章智信服务运行电脑的 **IP 地址**（如 `192.168.1.100` 或 `your-server.local`）
- `JZZX_API_KEY`：九章智信软件中的 API 密钥（在软件设置中查看）
- `JZZX_CREATOR_NAME`：任务创建者标识（可选），会显示在九章智信任务界面；用于区分哪个 AI Agent 发起了任务，默认从 `IDENTITY.md` 读取

**重要**：这两个配置项是必需的，不设置会报错！

📝 **安全提示**：请勿将 `.env` 文件提交到版本控制系统！

### 发送消息给好友

向单个好友发送消息：

```
向 张三 发送消息："你好，最近怎么样？"
```

向多个好友发送消息：

```
向 张三 和 李四 发送消息："明天会议改到下午 3 点"
```

**注意**：所有任务都会自动添加创建者标识，用于在九章智信任务界面区分任务来源。

### 发送消息给分组

向指定分组发送消息：

```
向 "家人" 分组发送消息："周末回家吃饭"
向 "朋友" 和 "同事" 分组发送消息："公司通知：下周一调休"
```

### 发起聊天任务

与单个好友聊天：

```
和 张三 聊天，问他周末有没有空
```

与多个好友聊天：

```
和 李四 以及 王五 聊天，问问他们对项目方案的意见
```

向分组发起聊天：

```
和 "家人" 分组聊天，问问大家假期安排
```

### 混合目标发送

当您需要向"分组 + 单个好友"混合发送时，系统会自动处理：

```
向 家人分组 和 Ff. 发送消息："#称呼#，明天记得吃饭"
```

**系统会自动：**
1. 解析"家人"为分组，"Ff."为单个好友
2. 查找"Ff."的 wxid（TAHTBlue411）
3. 创建两个任务：
   - 向"家人"分组发送（API 支持按分组发送）
   - 向"Ff."单独发送（API 支持按 wxid 发送）
4. 统一使用相同的个性化消息内容

**说明**：由于九章智信 API 限制，不能同时使用 `groups` 和 `wxids`，系统会自动拆分成多个任务执行。

### 发送个性化消息

使用 `#称呼#` 占位符，让群发消息变得个性化：

```
向 "家人" 分组发送消息："#称呼#，新年快乐！祝您和家人幸福安康"
```

**`#称呼#` 触发规则**：
- 当目标为分组或多个好友时，若用户的消息内容中未包含 `#称呼#`，应主动询问：
  > "是否需要在消息中加入 `#称呼#`，为每位好友生成个性化称呼？"
- 等用户确认后再创建任务

**占位符说明**：
- `#称呼#`：自动替换为每个好友在九章智信软件中设置的称呼（如"张先生"、"李老师"、"王总"等）
- `#青龙#`：自定义标签 1
- `#白虎#`：自定义标签 2

## 功能列表

### 1. 查询好友列表

查看微信中的所有好友：

```
查询我的微信好友
列出所有微信好友
```

返回格式：
- 好友显示名称
- 微信 ID (wxid)

### 2. 查询好友分组

查看微信中的好友分组：

```
查询我的微信分组
列出所有好友分组
```

返回格式：
- 分组名称
- 分组内的成员数量

### 3. 发送消息任务

创建消息发送任务，支持：
- 按好友 wxid 发送
- 按好友名称发送
- 按分组名称发送

任务执行状态：
- `queued` - 任务已入队，等待执行
- `processing` - 任务正在执行
- `completed` - 任务已完成

### 4. 聊天任务

创建多轮聊天任务，支持：
- AI 自动与对方进行多轮对话
- 根据对方回复智能回应
- 自动判断聊天结束时机

任务状态包括：
- `queued` - 任务已入队
- `processing` - AI 正在与对方聊天
- `completed` - 聊天完成，附带效果报告

效果报告包含：
- 聊天人数统计
- 对方意向度分析（强意向、弱意向、待观察、明确拒绝、攻击辱骂等）

### 5. 查询任务状态

根据任务 ID 查询执行状态：

```
查看任务 3 的状态
查询消息任务执行情况
```

## 使用示例

### 示例 1：向好友发送问候

```
向 张三 发送消息："早上好，今天天气不错"
```

### 示例 2：向分组发送通知

```
向 "项目组" 分组发送消息："本周四晚上 7 点团队聚餐，大家准时参加"
```

### 示例 3：发起一次聊天

```
和 李四 聊天，问问他项目进度如何，有没有遇到什么问题
```

### 示例 4：查询任务状态

```
查看刚创建的任务执行情况
```

### 示例 5：发送前查询联系人

```
先列出所有好友，找到张三的 wxid
然后向 张三 发送消息："消息内容"
```

## 注意事项

1. **任务异步执行**：所有任务都是异步的，创建后立即返回任务 ID，任务实际执行需要时间
2. **客户端依赖**：九章智信软件需要运行在另一台电脑上，确保网络可达
3. **证书问题**：API 使用自签名证书，请求时会自动忽略证书验证
4. **执行条件**：任务执行需要满足以下条件：
   - 本机无其他任务运行
   - 键盘鼠标持续无操作满设定时间
   - 微信窗口置顶
5. **入队顺序**：任务按入队顺序自动执行

## 修改配置

如需修改九章智信服务 IP 或 API Key：

```
修改九章智信配置：IP 改为 192.168.1.100，API Key 改为 new-key
```

## 技术细节

### API 端点

- `GET /api/v1/contacts` - 查询好友列表
- `GET /api/v1/groups` - 查询分组列表
- `POST /api/v1/tasks` - 创建任务
- `GET /api/v1/tasks/{task_id}` - 查询任务状态
- `POST /api/v1/tasks/{task_id}/abort` - 取消任务（仅在 queued 状态时可用）

### 任务类型

- `send` - 发送消息任务
- `chat` - 聊天任务

### 请求格式

所有 POST 请求必须包含 `Content-Type: application/json` 头部。

### 响应格式

```json
{
  "success": true,
  "data": {
    "manager_task_id": 1,
    "task_type": "send",
    "queued": true,
    "hint": "任务已加入队列..."
  }
}
```

### creator 字段说明

所有创建的任务都会自动包含 `creator` 字段，用于标识任务来源：

- **默认值**: 从 `IDENTITY.md` 读取当前 Agent 名称
- **用途**: 显示在九章智信任务界面和日志中，便于区分哪个 AI Agent 正在操作设备
- **自定义**: 多个 Agent 共用九章智信时，建议在 `.env` 中设置 `JZZX_CREATOR_NAME`

---

## 故障排查

### 连接失败

如果收到"Connection refused"错误：
1. 检查九章智信服务是否正在运行
2. 确认 IP 地址是否正确
3. 检查网络连通性（`ping `）

### API 密钥无效

如果收到认证错误：
1. 确认 `.env` 文件中的 `JZZX_API_KEY` 是否正确
2. 在九章智信软件中查看正确的 API 密钥
3. 确认密钥没有过期

### 证书验证失败

如果收到 SSL 证书错误：
- 九章智信使用自签名证书，请求时会自动忽略验证
- 如需启用证书验证，需要导入自签名证书到系统证书库

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [jiuzhangzhisuan](https://github.com/jiuzhangzhisuan)
- **Source:** [jiuzhangzhisuan/wechat-agent-skill](https://github.com/jiuzhangzhisuan/wechat-agent-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jiuzhangzhisuan-wechat-agent-skill-wechat-agent-skill
- Seller: https://agentstack.voostack.com/s/jiuzhangzhisuan
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.