@ganglion/xacpx 0.8.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +264 -246
- package/dist/cli.js +3 -1
- package/package.json +6 -3
package/README.md
CHANGED
|
@@ -1,144 +1,144 @@
|
|
|
1
1
|
# xacpx
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> Remotely drive Codex, Claude Code, and other acpx sessions from WeChat, Feishu, or Yuanbao.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@ganglion/xacpx)
|
|
6
6
|
[](https://nodejs.org)
|
|
7
7
|
[](https://zread.ai/gadzan/weacpx)
|
|
8
8
|
[](./LICENSE)
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
English · **[中文](./docs/zh/README_zh.md)**
|
|
11
11
|
|
|
12
|
-
##
|
|
12
|
+
## What is this
|
|
13
13
|
|
|
14
|
-
`xacpx`
|
|
14
|
+
`xacpx` is a tool that lets you control ACP agents such as Codex / Claude Code / Gemini / OpenCode directly from WeChat, Feishu, or Yuanbao. It connects chat messages to your agent CLI sessions through `acpx`, so you can, right from your phone:
|
|
15
15
|
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
16
|
+
- Create and switch between sessions
|
|
17
|
+
- Have the agent keep working in a specific project directory
|
|
18
|
+
- View streaming replies, final results, and tool-call summaries
|
|
19
|
+
- Adjust permission policies
|
|
20
|
+
- Orchestrate multiple agents when needed
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
If you need to code or work remotely on a temporary basis, `xacpx` gives you a fast, convenient **remote entry point** so you can get things done from WeChat or Feishu anytime, anywhere.
|
|
23
23
|
|
|
24
|
-
##
|
|
24
|
+
## Who it's for
|
|
25
25
|
|
|
26
|
-
`xacpx`
|
|
26
|
+
`xacpx` suits users who want lightweight, on-demand multi-agent work. You can watch tasks, send commands, and view results from WeChat, Feishu, or Yuanbao, and manage multiple sessions within the same chat.
|
|
27
27
|
|
|
28
|
-
>
|
|
28
|
+
> For everyday use, remember `/ss` first: it creates or reuses an xacpx logical session. If you want to attach to an existing native session of a local agent such as Codex, use `/ssn`; see [docs/native-sessions.md](./docs/native-sessions.md) for advanced details.
|
|
29
29
|
|
|
30
|
-
## 5
|
|
30
|
+
## 5-minute quick start
|
|
31
31
|
|
|
32
|
-
###
|
|
32
|
+
### Prerequisites
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Before you start, you need at least:
|
|
35
35
|
|
|
36
|
-
- Node.js 22+
|
|
37
|
-
-
|
|
38
|
-
-
|
|
36
|
+
- Node.js 22+ or Bun
|
|
37
|
+
- A working agent CLI you intend to use, such as Codex / Claude Code / Gemini / OpenCode
|
|
38
|
+
- A phone with WeChat, Feishu, or Yuanbao installed
|
|
39
39
|
|
|
40
|
-
>
|
|
40
|
+
> The WeChat channel works on top of `weixin-agent-sdk`, the Feishu channel uses Feishu custom-app credentials, and the Yuanbao channel uses `appKey` / `appSecret`; the underlying agent sessions are driven by `acpx`. Normally you don't need to install `acpx` globally.
|
|
41
41
|
|
|
42
|
-
###
|
|
42
|
+
### Install
|
|
43
43
|
|
|
44
44
|
```bash
|
|
45
45
|
npm install -g @ganglion/xacpx --registry=https://registry.npmjs.org
|
|
46
|
-
#
|
|
46
|
+
# or
|
|
47
47
|
bun add -g @ganglion/xacpx
|
|
48
48
|
```
|
|
49
49
|
|
|
50
|
-
###
|
|
50
|
+
### Log in to WeChat
|
|
51
51
|
|
|
52
52
|
```bash
|
|
53
53
|
xacpx login
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
-
|
|
56
|
+
The terminal will show a QR code; scan it with WeChat to log in.
|
|
57
57
|
|
|
58
|
-
|
|
58
|
+
If you want to use Feishu or Yuanbao instead of WeChat, see "Switch / add other channels" below first.
|
|
59
59
|
|
|
60
|
-
###
|
|
60
|
+
### Start the service
|
|
61
61
|
|
|
62
62
|
```bash
|
|
63
63
|
xacpx start
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
###
|
|
66
|
+
### Create your first session in WeChat
|
|
67
67
|
|
|
68
|
-
|
|
68
|
+
Send these two messages in WeChat:
|
|
69
69
|
|
|
70
70
|
```text
|
|
71
71
|
/ss codex -d /absolute/path/to/your/repo
|
|
72
72
|
/help
|
|
73
73
|
```
|
|
74
74
|
|
|
75
|
-
|
|
75
|
+
Then just send plain text, for example:
|
|
76
76
|
|
|
77
77
|
```text
|
|
78
78
|
hello
|
|
79
79
|
```
|
|
80
80
|
|
|
81
|
-
|
|
81
|
+
If everything works, plain text goes into the current session and the agent's reply comes back to WeChat.
|
|
82
82
|
|
|
83
|
-
###
|
|
83
|
+
### Switch / add other channels
|
|
84
84
|
|
|
85
|
-
|
|
85
|
+
WeChat is the built-in default channel. Feishu and Yuanbao are distributed as official plugin packages, and third-party channels follow the same plugin flow. If you can't remember the package names, check the official plugin list first:
|
|
86
86
|
|
|
87
87
|
```bash
|
|
88
88
|
xacpx plugin known
|
|
89
|
-
#
|
|
89
|
+
# Install: xacpx plugin add <package>
|
|
90
90
|
```
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
#
|
|
93
|
+
# Feishu
|
|
94
94
|
xacpx plugin add @ganglion/xacpx-channel-feishu
|
|
95
|
-
xacpx channel add feishu #
|
|
95
|
+
xacpx channel add feishu # enter appId/appSecret when prompted
|
|
96
96
|
xacpx restart
|
|
97
97
|
|
|
98
|
-
#
|
|
98
|
+
# Yuanbao
|
|
99
99
|
xacpx plugin add @ganglion/xacpx-channel-yuanbao
|
|
100
|
-
xacpx channel add yuanbao #
|
|
100
|
+
xacpx channel add yuanbao # enter appKey/appSecret when prompted
|
|
101
101
|
xacpx restart
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
For full credential configuration, parameters, and management commands such as `enable/disable/rm`, see [docs/channel-management.md](./docs/channel-management.md). If you want to write your own channel plugin, see [docs/plugin-development.md](./docs/plugin-development.md).
|
|
105
105
|
|
|
106
|
-
##
|
|
106
|
+
## Your everyday workflow
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
The most common sequence is just four steps:
|
|
109
109
|
|
|
110
|
-
1.
|
|
111
|
-
2.
|
|
112
|
-
3.
|
|
113
|
-
4.
|
|
110
|
+
1. **Start the background service**: `xacpx start`
|
|
111
|
+
2. **Create or switch sessions**: `/ss ...`, `/use ...`
|
|
112
|
+
3. **Send plain text directly**: let the current session keep working
|
|
113
|
+
4. **Check status or cancel the current task when needed**: `/status`, `/cancel`
|
|
114
114
|
|
|
115
|
-
### 1)
|
|
115
|
+
### 1) Create a session
|
|
116
116
|
|
|
117
|
-
|
|
117
|
+
The most common command:
|
|
118
118
|
|
|
119
119
|
```text
|
|
120
120
|
/ss codex -d /absolute/path/to/your/repo
|
|
121
121
|
```
|
|
122
122
|
|
|
123
|
-
|
|
123
|
+
It uses `codex`, binds this working directory, and automatically switches to the new session.
|
|
124
124
|
|
|
125
|
-
### 2)
|
|
125
|
+
### 2) Send plain messages
|
|
126
126
|
|
|
127
|
-
|
|
127
|
+
Any text not starting with `/` is sent to the current session.
|
|
128
128
|
|
|
129
129
|
```text
|
|
130
|
-
|
|
130
|
+
Fix this recent API timeout issue
|
|
131
131
|
```
|
|
132
132
|
|
|
133
|
-
### 3)
|
|
133
|
+
### 3) View replies
|
|
134
134
|
|
|
135
|
-
`xacpx`
|
|
135
|
+
`xacpx` supports three common reply modes:
|
|
136
136
|
|
|
137
|
-
- `stream
|
|
138
|
-
- `final
|
|
139
|
-
- `verbose
|
|
137
|
+
- `stream`: stream back intermediate text
|
|
138
|
+
- `final`: return only the final result
|
|
139
|
+
- `verbose`: the default; in addition to streaming text, also shows tool-call summaries
|
|
140
140
|
|
|
141
|
-
|
|
141
|
+
For example, in `verbose` mode you'll see:
|
|
142
142
|
|
|
143
143
|
```text
|
|
144
144
|
📖 sed -n '1,220p' README.md
|
|
@@ -147,47 +147,47 @@ xacpx restart
|
|
|
147
147
|
✏️ Edit parse-command.ts
|
|
148
148
|
```
|
|
149
149
|
|
|
150
|
-
### 4)
|
|
150
|
+
### 4) Switch sessions
|
|
151
151
|
|
|
152
152
|
```text
|
|
153
153
|
/ss
|
|
154
154
|
/use backend:codex
|
|
155
155
|
```
|
|
156
156
|
|
|
157
|
-
|
|
157
|
+
This lets you switch between sessions for different projects and different agents within the same WeChat chat.
|
|
158
158
|
|
|
159
|
-
##
|
|
159
|
+
## Common CLI commands
|
|
160
160
|
|
|
161
|
-
|
|
161
|
+
These commands run in a terminal on your computer.
|
|
162
162
|
|
|
163
|
-
|
|
|
163
|
+
| Command | Description |
|
|
164
164
|
|------|------|
|
|
165
|
-
| `xacpx login` |
|
|
166
|
-
| `xacpx logout` |
|
|
167
|
-
| `xacpx run` |
|
|
168
|
-
| `xacpx start` |
|
|
169
|
-
| `xacpx status` |
|
|
170
|
-
| `xacpx stop` |
|
|
171
|
-
| `xacpx restart` |
|
|
172
|
-
| `xacpx update [--all\|<name>]` |
|
|
173
|
-
| `xacpx channel list` |
|
|
174
|
-
| `xacpx plugin known` |
|
|
175
|
-
| `xacpx plugin add @ganglion/xacpx-channel-feishu && xacpx channel add feishu` |
|
|
176
|
-
| `xacpx plugin add @ganglion/xacpx-channel-yuanbao && xacpx channel add yuanbao` |
|
|
177
|
-
| `xacpx doctor` |
|
|
178
|
-
| `xacpx version` |
|
|
179
|
-
| `xacpx agent list` |
|
|
180
|
-
| `xacpx agent add <name>` |
|
|
181
|
-
| `xacpx agent rm <name>` |
|
|
182
|
-
| `xacpx workspace list` |
|
|
183
|
-
| `xacpx workspace add [name] [--raw]` |
|
|
184
|
-
| `xacpx workspace rm <name>` |
|
|
185
|
-
| `xacpx later list` / `xacpx lt list` |
|
|
186
|
-
| `xacpx later cancel <id>` / `xacpx lt cancel <id>` |
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
`workspace`
|
|
165
|
+
| `xacpx login` | Log in to WeChat |
|
|
166
|
+
| `xacpx logout` | Clear the WeChat login credentials saved on this machine |
|
|
167
|
+
| `xacpx run` | Run in the foreground, useful for debugging |
|
|
168
|
+
| `xacpx start` | Start the service in the background |
|
|
169
|
+
| `xacpx status` | Show background status, PID, config path, and log path |
|
|
170
|
+
| `xacpx stop` | Stop the background instance |
|
|
171
|
+
| `xacpx restart` | Restart the background instance so channel config changes take effect |
|
|
172
|
+
| `xacpx update [--all\|<name>]` | Check and update xacpx and installed plugins; when plugins are installed, it interactively lets you choose what to update |
|
|
173
|
+
| `xacpx channel list\|show\|add\|rm\|enable\|disable [--account <id>]` | Manage message channels; `--account <id>` targets one bot when several share a channel (multi-bot) |
|
|
174
|
+
| `xacpx plugin list\|add\|update\|remove\|enable\|disable\|doctor\|known` | Manage plugins: list/install/update/remove, toggle, run `doctor`, or list official packages with `known` |
|
|
175
|
+
| `xacpx plugin add @ganglion/xacpx-channel-feishu && xacpx channel add feishu` | Install and add the Feishu channel; prompts for Feishu app credentials |
|
|
176
|
+
| `xacpx plugin add @ganglion/xacpx-channel-yuanbao && xacpx channel add yuanbao` | Install and add the Yuanbao channel; prompts for Yuanbao appKey/appSecret |
|
|
177
|
+
| `xacpx doctor` | Run environment diagnostics |
|
|
178
|
+
| `xacpx version` | Show the current version |
|
|
179
|
+
| `xacpx agent list` | List agents registered on this machine |
|
|
180
|
+
| `xacpx agent add <name>` | Add an agent from a built-in template; an existing agent of the same name with a different config is not overwritten |
|
|
181
|
+
| `xacpx agent rm <name>` | Remove an agent |
|
|
182
|
+
| `xacpx workspace list` | List workspaces registered on this machine |
|
|
183
|
+
| `xacpx workspace add [name] [--raw]` | Register the current directory as a workspace; without `name`, uses the current directory name, and names with special characters are normalized automatically |
|
|
184
|
+
| `xacpx workspace rm <name>` | Remove a workspace |
|
|
185
|
+
| `xacpx later list` / `xacpx lt list` | List this machine's pending scheduled tasks in the terminal |
|
|
186
|
+
| `xacpx later cancel <id>` / `xacpx lt cancel <id>` | Cancel a pending scheduled task in the terminal |
|
|
187
|
+
|
|
188
|
+
The first time you run `xacpx start` or `xacpx run`, if there are no sessions, workspaces, or plugins, the CLI asks whether to register the current directory as a workspace and lets you choose a built-in agent template; after the service starts, it creates the initial acpx session through the normal session-creation flow.
|
|
189
|
+
|
|
190
|
+
`workspace` can also be abbreviated as `ws`:
|
|
191
191
|
|
|
192
192
|
```bash
|
|
193
193
|
xacpx ws add
|
|
@@ -195,19 +195,19 @@ xacpx ws list
|
|
|
195
195
|
xacpx ws rm backend
|
|
196
196
|
```
|
|
197
197
|
|
|
198
|
-
### `workspace` CLI
|
|
198
|
+
### How to use the `workspace` CLI
|
|
199
199
|
|
|
200
|
-
`xacpx workspace`
|
|
200
|
+
`xacpx workspace` maintains the `workspaces` config in `~/.xacpx/config.json` on your local machine. It's good for registering frequently used project directories in the terminal first, then referencing them directly in WeChat with `--ws <name>`.
|
|
201
201
|
|
|
202
|
-
|
|
|
202
|
+
| Command | Description |
|
|
203
203
|
|------|------|
|
|
204
|
-
| `xacpx workspace list` |
|
|
205
|
-
| `xacpx workspace add` |
|
|
206
|
-
| `xacpx workspace add <name>` |
|
|
207
|
-
| `xacpx workspace add [name] --raw` |
|
|
208
|
-
| `xacpx workspace rm <name>` |
|
|
204
|
+
| `xacpx workspace list` | List registered workspaces and their paths |
|
|
205
|
+
| `xacpx workspace add` | Register the current directory as a workspace, defaulting the name to the current directory name (normalized automatically) |
|
|
206
|
+
| `xacpx workspace add <name>` | Register the current directory under a specific name (normalized if it contains special characters) |
|
|
207
|
+
| `xacpx workspace add [name] --raw` | Keep the original name (including spaces, etc.); later commands must quote it |
|
|
208
|
+
| `xacpx workspace rm <name>` | Remove a specific workspace |
|
|
209
209
|
|
|
210
|
-
|
|
210
|
+
Common usage:
|
|
211
211
|
|
|
212
212
|
```bash
|
|
213
213
|
cd /absolute/path/to/backend
|
|
@@ -220,27 +220,27 @@ xacpx ws list
|
|
|
220
220
|
xacpx ws rm frontend
|
|
221
221
|
```
|
|
222
222
|
|
|
223
|
-
|
|
223
|
+
Once registered, you can use it directly in WeChat:
|
|
224
224
|
|
|
225
225
|
```text
|
|
226
226
|
/ss codex --ws backend
|
|
227
227
|
/ss new claude --ws frontend
|
|
228
228
|
```
|
|
229
229
|
|
|
230
|
-
|
|
230
|
+
Note: `workspace add` always registers the **directory the terminal is currently in**. Without a name, it uses the current directory name as the workspace name. Names containing spaces, Chinese characters, etc. are normalized automatically to `[a-zA-Z0-9._-]+` (for example, the directory `My Project` is saved as `My-Project`), with `-2`, `-3` appended on collisions. To keep the original name, add `--raw`; afterwards `xacpx workspace rm`, `/ws rm`, and `--ws <name>` all need quoting, for example `xacpx workspace rm "My Project"`.
|
|
231
231
|
|
|
232
|
-
### `agent` CLI
|
|
232
|
+
### How to use the `agent` CLI
|
|
233
233
|
|
|
234
|
-
`xacpx agent`
|
|
234
|
+
`xacpx agent` maintains the `agents` config in `~/.xacpx/config.json` on your local machine; `agents` is an equivalent alias.
|
|
235
235
|
|
|
236
|
-
|
|
|
236
|
+
| Command | Description |
|
|
237
237
|
|------|------|
|
|
238
|
-
| `xacpx agent list` |
|
|
239
|
-
| `xacpx agent templates` |
|
|
240
|
-
| `xacpx agent add <name>` |
|
|
241
|
-
| `xacpx agent rm <name>` |
|
|
238
|
+
| `xacpx agent list` | List registered agents |
|
|
239
|
+
| `xacpx agent templates` | List the built-in templates you can add |
|
|
240
|
+
| `xacpx agent add <name>` | Add an agent from a built-in template, e.g. `kimi`, `opencode` |
|
|
241
|
+
| `xacpx agent rm <name>` | Remove a specific agent |
|
|
242
242
|
|
|
243
|
-
|
|
243
|
+
Common usage:
|
|
244
244
|
|
|
245
245
|
```bash
|
|
246
246
|
xacpx agent templates
|
|
@@ -249,7 +249,7 @@ xacpx agents list
|
|
|
249
249
|
xacpx agent rm kimi
|
|
250
250
|
```
|
|
251
251
|
|
|
252
|
-
### `doctor`
|
|
252
|
+
### How to use `doctor`
|
|
253
253
|
|
|
254
254
|
```bash
|
|
255
255
|
xacpx doctor
|
|
@@ -258,29 +258,47 @@ xacpx doctor --smoke
|
|
|
258
258
|
xacpx doctor --smoke --agent codex --workspace backend
|
|
259
259
|
```
|
|
260
260
|
|
|
261
|
-
|
|
261
|
+
Notes:
|
|
262
262
|
|
|
263
|
-
- `--verbose`
|
|
264
|
-
- `--smoke`
|
|
265
|
-
- `--agent` / `--workspace`
|
|
266
|
-
-
|
|
263
|
+
- `--verbose` expands the details of each check
|
|
264
|
+
- `--smoke` additionally runs a minimal real transport-level prompt check
|
|
265
|
+
- `--agent` / `--workspace` only affect `--smoke`
|
|
266
|
+
- Without `--smoke`, the related checks show as `SKIP`
|
|
267
267
|
|
|
268
|
-
|
|
268
|
+
### How to use `update`
|
|
269
269
|
|
|
270
|
-
|
|
270
|
+
`xacpx update` checks for and installs new versions of xacpx itself and your installed channel plugins.
|
|
271
271
|
|
|
272
|
-
|
|
272
|
+
```bash
|
|
273
|
+
xacpx update # interactive: pick what to update
|
|
274
|
+
xacpx update --all # update everything (core + all plugins) non-interactively
|
|
275
|
+
xacpx update <name> # update a single target (the core, or a specific plugin package)
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
Notes:
|
|
279
|
+
|
|
280
|
+
- When plugins are installed, the bare `xacpx update` is interactive and lets you choose which targets to update.
|
|
281
|
+
- In a non-interactive environment, updating the core or plugins needs explicit confirmation: use `xacpx update --all`, or name the target with `xacpx update <name>`.
|
|
282
|
+
- `update` covers the core package and channel plugins; to manage a single plugin's version directly, see `xacpx plugin update <name>` ([docs/plugin-development.md](./docs/plugin-development.md)).
|
|
283
|
+
- After updating, run `xacpx restart` so a running daemon loads the new version.
|
|
284
|
+
- Cross-package rename migration: once the project's renamed successor package is published, running `weacpx update` will offer to migrate you across to it automatically (you confirm the switch). Until then this is dormant and `update` behaves as a normal self-update.
|
|
285
|
+
|
|
286
|
+
## Common chat commands
|
|
287
|
+
|
|
288
|
+
These commands are sent in a WeChat or Feishu chat. For the full command reference, see [docs/commands.md](./docs/commands.md).
|
|
289
|
+
|
|
290
|
+
### Agent management
|
|
273
291
|
|
|
274
|
-
|
|
292
|
+
The default config usually already includes `codex` and `claude`. If you want to use another acpx-supported agent, you can add it from a built-in template with `/agent add <name>`.
|
|
275
293
|
|
|
276
|
-
|
|
|
294
|
+
| Command | Description |
|
|
277
295
|
|------|------|
|
|
278
|
-
| `/agents` |
|
|
279
|
-
| `/agent add gemini` |
|
|
280
|
-
| `/agent add opencode` |
|
|
281
|
-
| `/agent rm <name>` |
|
|
296
|
+
| `/agents` | List agents |
|
|
297
|
+
| `/agent add gemini` | Add the `Gemini` agent |
|
|
298
|
+
| `/agent add opencode` | Add the `OpenCode` agent |
|
|
299
|
+
| `/agent rm <name>` | Remove an agent |
|
|
282
300
|
|
|
283
|
-
|
|
301
|
+
The current built-in templates align with acpx's built-in agents:
|
|
284
302
|
|
|
285
303
|
```text
|
|
286
304
|
codex, claude, pi, openclaw, gemini, cursor, copilot, droid,
|
|
@@ -288,37 +306,37 @@ factory-droid, factorydroid, iflow, kilocode, kimi, kiro,
|
|
|
288
306
|
opencode, qoder, qwen, trae
|
|
289
307
|
```
|
|
290
308
|
|
|
291
|
-
|
|
309
|
+
These templates only write `driver`; the actual launch command is resolved by acpx. For example, `/agent add kimi` saves `{ "driver": "kimi" }`. For full command docs see [docs/commands.md](./docs/commands.md), and for config fields see [docs/config-reference.md](./docs/config-reference.md).
|
|
292
310
|
|
|
293
|
-
### Workspace
|
|
311
|
+
### Workspace management
|
|
294
312
|
|
|
295
|
-
|
|
|
313
|
+
| Command | Description |
|
|
296
314
|
|------|------|
|
|
297
|
-
| `/workspaces` / `/workspace` / `/ws` |
|
|
298
|
-
| `/ws new <name> -d <path> [--raw]` |
|
|
299
|
-
| `/workspace rm <name>` |
|
|
315
|
+
| `/workspaces` / `/workspace` / `/ws` | List workspaces |
|
|
316
|
+
| `/ws new <name> -d <path> [--raw]` | Add a workspace; `path` is an absolute path on your computer, and Windows does not distinguish forward/back slashes; names with special characters such as spaces/Chinese are normalized automatically, and --raw keeps the original name |
|
|
317
|
+
| `/workspace rm <name>` | Remove a workspace |
|
|
300
318
|
|
|
301
|
-
###
|
|
319
|
+
### Sessions
|
|
302
320
|
|
|
303
|
-
|
|
|
321
|
+
| Command | Description |
|
|
304
322
|
|------|------|
|
|
305
|
-
| `/sessions` / `/session` / `/ss` |
|
|
306
|
-
| `/ss <agent> (-d <path> \| --ws <name>)` |
|
|
307
|
-
| `/ss new <agent> (-d <path> \| --ws <name>)` |
|
|
308
|
-
| `/ssn <agent> (-d <path> \| --ws <name>)` |
|
|
309
|
-
| `/use <alias>` |
|
|
310
|
-
| `/status` |
|
|
311
|
-
| `/mode` / `/mode <id>` |
|
|
312
|
-
| `/replymode` |
|
|
313
|
-
| `/replymode stream` |
|
|
314
|
-
| `/replymode verbose` |
|
|
315
|
-
| `/replymode final` |
|
|
316
|
-
| `/replymode reset` |
|
|
317
|
-
| `/session reset` |
|
|
318
|
-
| `/clear` | `/session reset`
|
|
319
|
-
| `/cancel` / `/stop` |
|
|
320
|
-
|
|
321
|
-
|
|
323
|
+
| `/sessions` / `/session` / `/ss` | List sessions |
|
|
324
|
+
| `/ss <agent> (-d <path> \| --ws <name>)` | Create or reuse your current most-used session |
|
|
325
|
+
| `/ss new <agent> (-d <path> \| --ws <name>)` | Force-create a new session |
|
|
326
|
+
| `/ssn <agent> (-d <path> \| --ws <name>)` | Attach to an existing native session of a local agent; see [native sessions](./docs/native-sessions.md) |
|
|
327
|
+
| `/use <alias>` | Switch the current session |
|
|
328
|
+
| `/status` | Show the current session status |
|
|
329
|
+
| `/mode` / `/mode <id>` | View or set the underlying `acpx` mode |
|
|
330
|
+
| `/replymode` | Show the current reply mode |
|
|
331
|
+
| `/replymode stream` | Streaming replies |
|
|
332
|
+
| `/replymode verbose` | Streaming + tool-call summaries |
|
|
333
|
+
| `/replymode final` | Return only the final result |
|
|
334
|
+
| `/replymode reset` | Fall back to the global default reply mode |
|
|
335
|
+
| `/session reset` | Reset the current session context |
|
|
336
|
+
| `/clear` | Shortcut alias for `/session reset` |
|
|
337
|
+
| `/cancel` / `/stop` | Stop the current task |
|
|
338
|
+
|
|
339
|
+
We suggest remembering these three first:
|
|
322
340
|
|
|
323
341
|
```text
|
|
324
342
|
/ss codex -d /absolute/path/to/repo
|
|
@@ -326,51 +344,51 @@ opencode, qoder, qwen, trae
|
|
|
326
344
|
/cancel
|
|
327
345
|
```
|
|
328
346
|
|
|
329
|
-
|
|
347
|
+
To attach to an existing native session of a local agent such as Codex, use `/ssn codex -d /absolute/path/to/repo`; for full semantics see [docs/native-sessions.md](./docs/native-sessions.md).
|
|
330
348
|
|
|
331
|
-
###
|
|
349
|
+
### Scheduled tasks (/later)
|
|
332
350
|
|
|
333
|
-
|
|
351
|
+
Have the agent automatically receive a message at some point in the future. **By default it runs in a temporary session created just for that task** (inheriting the agent and workspace of the current session at creation time, with a fresh conversation history, destroyed once finished); adding `--bind` sends it to the current session bound at creation time. When the time comes, the message is delivered as a normal prompt and the result is pushed back to the original chat.
|
|
334
352
|
|
|
335
|
-
|
|
|
353
|
+
| Command | Description |
|
|
336
354
|
|------|------|
|
|
337
|
-
| `/lt
|
|
338
|
-
| `/lt --bind
|
|
339
|
-
| `/lt list` |
|
|
340
|
-
| `/lt cancel <id>` |
|
|
355
|
+
| `/lt <time> <message>` | Create a scheduled task (runs in a temporary session by default; `/later` is a synonym) |
|
|
356
|
+
| `/lt --bind <time> <message>` | Send to the current session instead |
|
|
357
|
+
| `/lt list` | List globally pending tasks |
|
|
358
|
+
| `/lt cancel <id>` | Cancel a pending task |
|
|
341
359
|
|
|
342
|
-
|
|
360
|
+
The most common examples:
|
|
343
361
|
|
|
344
362
|
```text
|
|
345
|
-
/lt in 2h
|
|
346
|
-
/lt --bind
|
|
363
|
+
/lt in 2h check whether CI passes # temporary session (default)
|
|
364
|
+
/lt --bind tomorrow 09:00 review the PR # bound to the current session
|
|
347
365
|
/lt list
|
|
348
366
|
```
|
|
349
367
|
|
|
350
|
-
|
|
368
|
+
Notes:
|
|
351
369
|
|
|
352
|
-
-
|
|
353
|
-
-
|
|
354
|
-
-
|
|
355
|
-
-
|
|
356
|
-
-
|
|
357
|
-
-
|
|
370
|
+
- Runs in a temporary session by default; `--bind` binds to the current session. The default mode can be changed via the config `later.defaultMode` (`temp` / `bind`, default `temp`)
|
|
371
|
+
- Only one-time tasks are supported; the time must be more than 10 seconds and within 7 days from now
|
|
372
|
+
- The time format is a fixed whitelist (relative time / today·tomorrow·day-after-tomorrow / weekday + time); natural language is not supported
|
|
373
|
+
- In normal conversation, the agent can also create, list, and cancel scheduled tasks via the current session's internal tools (`scheduled_create` / `scheduled_list` / `scheduled_cancel`); routing and permissions are resolved by the daemon from the current chat session, and the external `mcp-stdio` does not expose these tools
|
|
374
|
+
- You can also manage pending tasks from the terminal with `xacpx later list` / `xacpx later cancel <id>`; the CLI only lists and cancels, it does not create scheduled tasks
|
|
375
|
+
- For full time formats, temporary/bound modes, task status, and limits, see [docs/later-command.md](./docs/later-command.md)
|
|
358
376
|
|
|
359
|
-
###
|
|
377
|
+
### Config and permissions
|
|
360
378
|
|
|
361
|
-
|
|
|
379
|
+
| Command | Description |
|
|
362
380
|
|------|------|
|
|
363
|
-
| `/config` |
|
|
364
|
-
| `/config set <path> <value>` |
|
|
365
|
-
| `/pm` / `/permission` |
|
|
366
|
-
| `/pm set allow` |
|
|
367
|
-
| `/pm set read` |
|
|
368
|
-
| `/pm set deny` |
|
|
369
|
-
| `/pm auto` |
|
|
370
|
-
| `/pm auto deny` |
|
|
371
|
-
| `/pm auto fail` |
|
|
372
|
-
|
|
373
|
-
|
|
381
|
+
| `/config` | Show the config paths that can be changed via chat commands |
|
|
382
|
+
| `/config set <path> <value>` | Change a whitelisted config item |
|
|
383
|
+
| `/pm` / `/permission` | Show the current permission mode |
|
|
384
|
+
| `/pm set allow` | Switch to `approve-all` |
|
|
385
|
+
| `/pm set read` | Switch to `approve-reads` |
|
|
386
|
+
| `/pm set deny` | Switch to `deny-all` |
|
|
387
|
+
| `/pm auto` | Show the current non-interactive permission policy |
|
|
388
|
+
| `/pm auto deny` | Switch to `deny` |
|
|
389
|
+
| `/pm auto fail` | Switch to `fail` |
|
|
390
|
+
|
|
391
|
+
The most common examples:
|
|
374
392
|
|
|
375
393
|
```text
|
|
376
394
|
/config set wechat.replyMode final
|
|
@@ -378,53 +396,53 @@ opencode, qoder, qwen, trae
|
|
|
378
396
|
/pm auto deny
|
|
379
397
|
```
|
|
380
398
|
|
|
381
|
-
###
|
|
399
|
+
### Multi-agent orchestration
|
|
382
400
|
|
|
383
|
-
README
|
|
401
|
+
The README keeps only the most common user-facing commands.
|
|
384
402
|
|
|
385
|
-
|
|
|
403
|
+
| Command | Description |
|
|
386
404
|
|------|------|
|
|
387
|
-
| `/dg <agent> <task>` |
|
|
388
|
-
| `/tasks` |
|
|
389
|
-
| `/task <id>` |
|
|
390
|
-
| `/task approve <id>` |
|
|
391
|
-
| `/task cancel <id>` |
|
|
405
|
+
| `/dg <agent> <task>` | Quickly delegate a subtask |
|
|
406
|
+
| `/tasks` | List tasks under the current main line |
|
|
407
|
+
| `/task <id>` | Show details of a single task |
|
|
408
|
+
| `/task approve <id>` | Approve a `needs_confirmation` task |
|
|
409
|
+
| `/task cancel <id>` | Cancel a task; cancelling a not-yet-approved task is equivalent to rejecting it |
|
|
392
410
|
|
|
393
|
-
|
|
411
|
+
The most common examples:
|
|
394
412
|
|
|
395
413
|
```text
|
|
396
|
-
/dg claude
|
|
414
|
+
/dg claude review the 3 high-risk points of the current plan
|
|
397
415
|
/tasks
|
|
398
416
|
/task approve task_123
|
|
399
417
|
```
|
|
400
418
|
|
|
401
|
-
|
|
419
|
+
Notes:
|
|
402
420
|
|
|
403
|
-
-
|
|
404
|
-
-
|
|
405
|
-
- agent
|
|
406
|
-
-
|
|
421
|
+
- The current session is the coordinator session
|
|
422
|
+
- What gets delegated out are independent subtask sessions
|
|
423
|
+
- Delegation requests initiated by the agent require human confirmation by default
|
|
424
|
+
- If you're using an external MCP host (Codex / Claude Code), use `delegate_batch` to dispatch multiple parallel subtasks at once: pass a `tasks` array, a group is created automatically under the hood, and all results are injected back at once with no need to maintain a groupId manually
|
|
407
425
|
|
|
408
|
-
|
|
426
|
+
If you want to first understand when to delegate and when to dispatch multiple subtasks in parallel, see:
|
|
409
427
|
|
|
410
428
|
- [docs/weacpx-group-usage-guide.md](./docs/weacpx-group-usage-guide.md)
|
|
411
429
|
|
|
412
430
|
|
|
413
|
-
### MCP
|
|
431
|
+
### MCP integration: external coordinator
|
|
414
432
|
|
|
415
|
-
|
|
433
|
+
If you want external MCP hosts such as Codex or Claude Code to use xacpx's multi-agent orchestration directly, you can configure `xacpx mcp-stdio` as a stdio MCP server.
|
|
416
434
|
|
|
417
|
-
`delegate_request`
|
|
435
|
+
`delegate_request` supports MCP Tasks: a host that supports this capability can make the delegation request return a native task handle immediately, then get status, results, or cancel the task via `tasks/get` / `tasks/result` / `tasks/cancel`; the worker's `[PROGRESS] ...` output shows up in the `statusMessage` of `tasks/get` / `tasks/list`; in the `input_required` state, `tasks/result` returns a next-step hint and ends this result stream rather than blocking for a long time; after the client calls tools such as `task_get` / `task_approve` / `coordinator_answer_question` per the hint, it continues polling `tasks/get` / `tasks/result`. A host that does not support MCP Tasks can still use the compatibility tools `task_get` / `task_list` / `task_watch` / `task_cancel`.
|
|
418
436
|
|
|
419
|
-
|
|
437
|
+
The natural-language creation tool for scheduled tasks is an internal capability of the xacpx current session and does not appear in the external `xacpx mcp-stdio` tool list.
|
|
420
438
|
|
|
421
|
-
|
|
439
|
+
Start the daemon first:
|
|
422
440
|
|
|
423
441
|
```bash
|
|
424
442
|
xacpx start
|
|
425
443
|
```
|
|
426
444
|
|
|
427
|
-
MCP
|
|
445
|
+
We recommend keeping the MCP config simple and not binding a workspace in the launch arguments:
|
|
428
446
|
|
|
429
447
|
```json
|
|
430
448
|
{
|
|
@@ -437,17 +455,17 @@ MCP 配置推荐保持简单，不要在启动参数里绑定 workspace：
|
|
|
437
455
|
}
|
|
438
456
|
```
|
|
439
457
|
|
|
440
|
-
|
|
458
|
+
When an external host calls `delegate_request`, pass `workingDirectory`, and xacpx will make the delegated worker work in that directory:
|
|
441
459
|
|
|
442
460
|
```json
|
|
443
461
|
{
|
|
444
462
|
"targetAgent": "claude",
|
|
445
|
-
"task": "
|
|
463
|
+
"task": "review the risks of this change",
|
|
446
464
|
"workingDirectory": "/absolute/path/to/your/repo"
|
|
447
465
|
}
|
|
448
466
|
```
|
|
449
467
|
|
|
450
|
-
Windows
|
|
468
|
+
On Windows, if the MCP host won't resolve a `command` with arguments for you, put `node.exe` in `command` and the xacpx script and arguments in `args`:
|
|
451
469
|
|
|
452
470
|
```json
|
|
453
471
|
{
|
|
@@ -460,18 +478,18 @@ Windows 上如果 MCP host 不会帮你解析带参数的 `command`，把 `node.
|
|
|
460
478
|
}
|
|
461
479
|
```
|
|
462
480
|
|
|
463
|
-
|
|
481
|
+
For more identity rules, `workingDirectory` semantics, the tool list, flow diagrams, and troubleshooting, see [docs/external-mcp.md](./docs/external-mcp.md).
|
|
464
482
|
|
|
465
|
-
##
|
|
483
|
+
## Common scenarios
|
|
466
484
|
|
|
467
|
-
###
|
|
485
|
+
### Keep watching a local project from your phone
|
|
468
486
|
|
|
469
487
|
```text
|
|
470
488
|
/ss codex -d /absolute/path/to/backend
|
|
471
|
-
|
|
489
|
+
take a look at today's API timeout issue
|
|
472
490
|
```
|
|
473
491
|
|
|
474
|
-
###
|
|
492
|
+
### Switch between two projects in the same chat
|
|
475
493
|
|
|
476
494
|
```text
|
|
477
495
|
/ss codex -d /absolute/path/to/backend
|
|
@@ -481,62 +499,62 @@ Windows 上如果 MCP host 不会帮你解析带参数的 `command`，把 `node.
|
|
|
481
499
|
/use frontend:codex
|
|
482
500
|
```
|
|
483
501
|
|
|
484
|
-
###
|
|
502
|
+
### Attach to an existing local Codex native session
|
|
485
503
|
|
|
486
504
|
```text
|
|
487
505
|
/ssn codex -d /absolute/path/to/backend
|
|
488
506
|
/ssn 1
|
|
489
507
|
```
|
|
490
508
|
|
|
491
|
-
|
|
509
|
+
For more filtering, aliases, and troubleshooting, see [docs/native-sessions.md](./docs/native-sessions.md).
|
|
492
510
|
|
|
493
|
-
##
|
|
511
|
+
## Config and runtime files
|
|
494
512
|
|
|
495
|
-
|
|
513
|
+
Default file locations:
|
|
496
514
|
|
|
497
|
-
-
|
|
498
|
-
-
|
|
499
|
-
-
|
|
515
|
+
- Config file: `~/.xacpx/config.json`
|
|
516
|
+
- State file: `~/.xacpx/state.json`
|
|
517
|
+
- Runtime log: `~/.xacpx/runtime/app.log`
|
|
500
518
|
|
|
501
|
-
|
|
519
|
+
More runtime files are placed under `~/.xacpx/runtime/`.
|
|
502
520
|
|
|
503
|
-
##
|
|
521
|
+
## FAQ
|
|
504
522
|
|
|
505
|
-
### `/ss new`
|
|
523
|
+
### What if `/ss new` fails?
|
|
506
524
|
|
|
507
|
-
|
|
525
|
+
If session creation fails in WeChat, the most common cause is not a wrong `xacpx` command format, but that the underlying session was not created successfully.
|
|
508
526
|
|
|
509
|
-
|
|
527
|
+
You can try these two steps first:
|
|
510
528
|
|
|
511
|
-
1.
|
|
512
|
-
2.
|
|
529
|
+
1. Confirm in the terminal that the current project directory and the agent itself work
|
|
530
|
+
2. If you're familiar with `acpx`, manually create a session first, then attach to it from WeChat
|
|
513
531
|
|
|
514
|
-
|
|
532
|
+
For example, you can create a session locally first:
|
|
515
533
|
|
|
516
534
|
```bash
|
|
517
535
|
./node_modules/.bin/acpx --verbose --cwd /absolute/workspace/path codex sessions new --name existing-demo
|
|
518
536
|
```
|
|
519
537
|
|
|
520
|
-
|
|
538
|
+
Then attach to it from WeChat:
|
|
521
539
|
|
|
522
540
|
```text
|
|
523
541
|
/ss attach demo -a codex --ws backend --name existing-demo
|
|
524
542
|
```
|
|
525
543
|
|
|
526
|
-
###
|
|
544
|
+
### What is the `<id>` in `/mode <id>`?
|
|
527
545
|
|
|
528
|
-
`/mode`
|
|
546
|
+
The valid values for `/mode` depend on the agent you're currently using; `xacpx` does not normalize these values for you.
|
|
529
547
|
|
|
530
|
-
|
|
548
|
+
Currently the more clearly known values are:
|
|
531
549
|
|
|
532
550
|
- `codex`: `plan`
|
|
533
|
-
- `cursor`: `agent
|
|
551
|
+
- `cursor`: `agent`, `plan`, `ask`
|
|
534
552
|
|
|
535
|
-
|
|
553
|
+
If you're unsure whether a value works, check the corresponding agent's docs first; if you get it wrong, you'll usually get an error such as an invalid argument.
|
|
536
554
|
|
|
537
|
-
##
|
|
555
|
+
## Running from source
|
|
538
556
|
|
|
539
|
-
|
|
557
|
+
If you're using the repo source directly:
|
|
540
558
|
|
|
541
559
|
```bash
|
|
542
560
|
bun install
|
|
@@ -544,27 +562,27 @@ bun run login
|
|
|
544
562
|
bun run dev
|
|
545
563
|
```
|
|
546
564
|
|
|
547
|
-
##
|
|
565
|
+
## More docs
|
|
548
566
|
|
|
549
|
-
|
|
567
|
+
If what you're about to do is one of the following, you can continue from here:
|
|
550
568
|
|
|
551
|
-
###
|
|
569
|
+
### Installation and configuration
|
|
552
570
|
|
|
553
|
-
-
|
|
554
|
-
-
|
|
555
|
-
-
|
|
556
|
-
-
|
|
571
|
+
- Want to configure WeChat, Feishu, Yuanbao, or a third-party plugin channel: [docs/channel-management.md](./docs/channel-management.md)
|
|
572
|
+
- Want to write your own channel plugin: [docs/plugin-development.md](./docs/plugin-development.md)
|
|
573
|
+
- Want the full config field reference: [docs/config-reference.md](./docs/config-reference.md)
|
|
574
|
+
- Want to change config from WeChat: [docs/config-command.md](./docs/config-command.md)
|
|
557
575
|
|
|
558
|
-
###
|
|
576
|
+
### Everyday use
|
|
559
577
|
|
|
560
|
-
-
|
|
561
|
-
-
|
|
562
|
-
-
|
|
578
|
+
- Want the full chat-command reference: [docs/commands.md](./docs/commands.md)
|
|
579
|
+
- Want to schedule a one-time future message with scheduled tasks (`/later`): [docs/later-command.md](./docs/later-command.md)
|
|
580
|
+
- Want to understand when to delegate and when to open a group: [docs/weacpx-group-usage-guide.md](./docs/weacpx-group-usage-guide.md)
|
|
563
581
|
|
|
564
|
-
###
|
|
582
|
+
### Troubleshooting and verification
|
|
565
583
|
|
|
566
|
-
-
|
|
584
|
+
- Want to run tests or understand the test layout: [docs/testing.md](./docs/testing.md)
|
|
567
585
|
|
|
568
|
-
###
|
|
586
|
+
### Development and contribution
|
|
569
587
|
|
|
570
|
-
-
|
|
588
|
+
- Want to develop, debug, or contribute from source: [docs/developments.md](./docs/developments.md)
|
package/dist/cli.js
CHANGED
|
@@ -1811,7 +1811,7 @@ var require_cjs = __commonJS((exports) => {
|
|
|
1811
1811
|
|
|
1812
1812
|
// node_modules/write-file-atomic/lib/index.js
|
|
1813
1813
|
var require_lib = __commonJS((exports, module) => {
|
|
1814
|
-
var __filename = "/home/runner/work/
|
|
1814
|
+
var __filename = "/home/runner/work/xacpx/xacpx/node_modules/write-file-atomic/lib/index.js";
|
|
1815
1815
|
module.exports = writeFile;
|
|
1816
1816
|
module.exports.sync = writeFileSync;
|
|
1817
1817
|
module.exports._getTmpname = getTmpname;
|
|
@@ -46358,6 +46358,7 @@ async function addPlugin(packageSpec, rawArgs, deps) {
|
|
|
46358
46358
|
});
|
|
46359
46359
|
try {
|
|
46360
46360
|
await install(installInput);
|
|
46361
|
+
await ensurePluginHome(pluginHome);
|
|
46361
46362
|
} catch (error2) {
|
|
46362
46363
|
deps.print(`插件 ${packageSpec} 安装失败：${describeError(error2)}`);
|
|
46363
46364
|
return 1;
|
|
@@ -46468,6 +46469,7 @@ async function updatePlugins(args, deps) {
|
|
|
46468
46469
|
const updateInput = nextVersion ? { packageName: existing.name, version: nextVersion } : { packageName: existing.name };
|
|
46469
46470
|
try {
|
|
46470
46471
|
await update(updateInput);
|
|
46472
|
+
await ensurePluginHome(pluginHome);
|
|
46471
46473
|
} catch (error2) {
|
|
46472
46474
|
deps.print(`插件 ${existing.name} 更新失败：${describeError(error2)}`);
|
|
46473
46475
|
return 1;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ganglion/xacpx",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.1",
|
|
4
4
|
"description": "随时随地通过聊天频道（微信 / 飞书 / 元宝等）远程控制 `acpx` 上的 Claude Code、Codex 等 Agents。",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"acpx",
|
|
@@ -14,11 +14,11 @@
|
|
|
14
14
|
"author": "gadzan",
|
|
15
15
|
"license": "MIT",
|
|
16
16
|
"bugs": {
|
|
17
|
-
"url": "https://github.com/gadzan/
|
|
17
|
+
"url": "https://github.com/gadzan/xacpx/issues"
|
|
18
18
|
},
|
|
19
19
|
"repository": {
|
|
20
20
|
"type": "git",
|
|
21
|
-
"url": "git+https://github.com/gadzan/
|
|
21
|
+
"url": "git+https://github.com/gadzan/xacpx.git"
|
|
22
22
|
},
|
|
23
23
|
"type": "module",
|
|
24
24
|
"bin": {
|
|
@@ -53,6 +53,9 @@
|
|
|
53
53
|
"publish:channel-feishu": "bun publish --cwd packages/channel-feishu --access public",
|
|
54
54
|
"publish:channel-yuanbao": "bun publish --cwd packages/channel-yuanbao --access public",
|
|
55
55
|
"publish:plugins": "bun run publish:channel-yuanbao && bun run publish:channel-feishu",
|
|
56
|
+
"docs:dev": "bun run --cwd packages/docs dev",
|
|
57
|
+
"docs:build": "bun run --cwd packages/docs build",
|
|
58
|
+
"docs:preview": "bun run --cwd packages/docs preview",
|
|
56
59
|
"dev": "bun run ./src/cli.ts run",
|
|
57
60
|
"dry-run": "bun run ./src/dry-run.ts",
|
|
58
61
|
"login": "bun run ./src/cli.ts login",
|