pikiclaw 0.3.35 → 0.3.37
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 +176 -173
- package/README.zh-CN.md +350 -0
- package/dist/agent/mcp/bridge.js +33 -17
- package/dist/agent/mcp/extensions.js +4 -2
- package/dist/catalog/mcp-servers.js +13 -0
- package/dist/channels/feishu/bot.js +54 -1
- package/dist/dashboard/routes/extensions.js +6 -3
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
##### *The open Agent orchestrator for the era when creators no longer need to read code.*
|
|
8
8
|
|
|
9
|
-
*Plug in any agent (Claude · Codex · Gemini · Hermes · …), any model (Claude · GPT · Gemini · DeepSeek ·
|
|
9
|
+
*Plug in any agent (Claude · Codex · Gemini · Hermes · …), any model (Claude · GPT · Gemini · DeepSeek · Doubao · MiMo · MiniMax · OpenRouter · or any third-party proxy), and any tool (Skills · MCP · CLI). Drive them seamlessly from your favorite terminal—whether it's an IM, Web Dashboard, or future interfaces. pikiclaw is built using pikiclaw.*
|
|
10
10
|
|
|
11
11
|
```bash
|
|
12
12
|
npx pikiclaw@latest
|
|
@@ -17,7 +17,11 @@ npx pikiclaw@latest
|
|
|
17
17
|
<a href="https://www.npmjs.com/package/pikiclaw"><img src="https://img.shields.io/npm/dm/pikiclaw?label=downloads&color=success" alt="npm downloads"></a>
|
|
18
18
|
<a href="https://github.com/xiaotonng/pikiclaw/stargazers"><img src="https://img.shields.io/github/stars/xiaotonng/pikiclaw?style=flat&color=yellow" alt="GitHub stars"></a>
|
|
19
19
|
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
|
|
20
|
-
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%
|
|
20
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-green.svg" alt="Node 20+"></a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
<p>
|
|
24
|
+
<b>English</b> | <a href="README.zh-CN.md">简体中文</a>
|
|
21
25
|
</p>
|
|
22
26
|
|
|
23
27
|
<img src="docs/workspace.png" alt="Workspace" width="780">
|
|
@@ -28,100 +32,102 @@ npx pikiclaw@latest
|
|
|
28
32
|
|
|
29
33
|
## What is pikiclaw?
|
|
30
34
|
|
|
31
|
-
**Most "AI dev
|
|
32
|
-
|
|
33
|
-
The product is the orchestrator. Everything else plugs in. **And
|
|
34
|
-
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
\
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
v
|
|
45
|
-
|
|
46
|
-
Claude Code · Codex · Gemini Claude · GPT · Gemini · DeepSeek
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
35
|
+
**Most "AI dev tools" settle for a narrow slice of the pie—binding you to a single IDE, a specific agent, or a closed model ecosystem.** pikiclaw is built on a fundamentally different premise: the next era of software creation won't be confined to a single code editor. It happens within an **Orchestrator** that empowers a creator to drive a *swarm* of agents—in parallel, from one console—running on the best models available, through whichever terminal is closest at hand. And you might never need to open a code file.
|
|
36
|
+
|
|
37
|
+
The product is the orchestrator itself. Everything else simply plugs in. **And what's cooler is that this orchestrator is entirely self-bootstrapped**—pikiclaw is what we use to build pikiclaw.
|
|
38
|
+
|
|
39
|
+
```text
|
|
40
|
+
Terminal Layer Telegram · Feishu · WeChat · Slack · Discord · DingTalk · WeCom · Web Dashboard
|
|
41
|
+
\__________________________|__________________________/
|
|
42
|
+
v
|
|
43
|
+
┌──────────────────────────────┐
|
|
44
|
+
│ pikiclaw orchestrator │
|
|
45
|
+
└──────────────────────────────┘
|
|
46
|
+
|
|
|
47
|
+
┌────────────────────────────────────────┼────────────────────────────────────────┐
|
|
48
|
+
v v v
|
|
49
|
+
Agent Layer Model Layer Tool Layer
|
|
50
|
+
Claude Code · Codex · Gemini · Hermes Claude · GPT · Gemini · DeepSeek Skills · MCP · CLI
|
|
51
|
+
(driver registry · ACP · any agent) Doubao · MiMo · MiniMax · OpenRouter (global × workspace)
|
|
52
|
+
· any OpenAI-compatible proxy · …
|
|
53
|
+
|
|
|
54
|
+
v
|
|
55
|
+
Your Machine
|
|
52
56
|
```
|
|
53
57
|
|
|
54
|
-
- **Terminal
|
|
55
|
-
- **Agent
|
|
56
|
-
- **Model
|
|
57
|
-
- **Tool
|
|
58
|
+
- **Terminal Layer** — Telegram, Feishu, WeChat, Slack, Discord, DingTalk, WeCom, and the Web Dashboard are all first-class, co-equal entry points. New terminals plug right in.
|
|
59
|
+
- **Agent Layer** — We use the official Claude Code, Codex, Gemini, and Hermes CLIs as underlying drivers. Hermes communicates via ACP (Agent Client Protocol); our flexible registry can accommodate virtually any agent.
|
|
60
|
+
- **Model Layer** — Access Claude, GPT, Gemini, leading Chinese domestic models (DeepSeek, Doubao, MiMo, MiniMax), plus OpenRouter and any OpenAI-compatible proxy. Providers and Profiles are treated as a first-class layer with their own credential vault, a read-only models.dev catalog, and per-agent environment injection.
|
|
61
|
+
- **Tool Layer** — Skills, MCP servers, and CLI tools are intelligently merged across global and workspace scopes, automatically injected into every session.
|
|
58
62
|
|
|
59
63
|
---
|
|
60
64
|
|
|
61
|
-
## Built with
|
|
65
|
+
## Built with Itself
|
|
62
66
|
|
|
63
|
-
> The most credible test of an Agent orchestrator is whether it can build itself. pikiclaw can. We use pikiclaw to develop, test, release, and operate pikiclaw
|
|
67
|
+
> The most credible test of an Agent orchestrator is whether it can build itself. pikiclaw can. We use pikiclaw to develop, test, release, and operate pikiclaw—driving every commit and every release.
|
|
64
68
|
|
|
65
|
-
A typical day
|
|
69
|
+
A typical day of development inside pikiclaw:
|
|
66
70
|
|
|
67
|
-
- A Claude Code session in
|
|
68
|
-
- A Codex session in
|
|
69
|
-
- A Gemini session in
|
|
70
|
-
-
|
|
71
|
-
- All four streams run in parallel;
|
|
71
|
+
- A Claude Code session in pane 1 implements a new dashboard route.
|
|
72
|
+
- A Codex session in pane 2 writes the matching unit tests against the same workspace.
|
|
73
|
+
- A Gemini session in pane 3 reviews the diffs and drafts the changelog.
|
|
74
|
+
- Meanwhile, a background skill (`/sk_promote`) sweeps GitHub for relevant issues and automatically drafts replies in a fourth thread.
|
|
75
|
+
- All four streams run entirely in parallel; a single human steers them all from a phone in a coffee shop.
|
|
72
76
|
|
|
73
|
-
The orchestrator is the product. It also happens to be the IDE the orchestrator is built
|
|
77
|
+
The orchestrator is the product. It also happens to be the ultimate IDE in which the orchestrator itself is built.
|
|
74
78
|
|
|
75
79
|
---
|
|
76
80
|
|
|
77
|
-
## A
|
|
81
|
+
## A Swarm by Default
|
|
78
82
|
|
|
79
|
-
Most "AI dev tools" assume one user, one agent, one task at a time. pikiclaw assumes the opposite: **N agents, N windows, one operator, one toolkit.**
|
|
83
|
+
Most "AI dev tools" assume a 1:1:1 ratio: one user, one agent, one task at a time. pikiclaw assumes the exact opposite: **N agents, N windows, one operator, one unified toolkit.**
|
|
80
84
|
|
|
81
|
-
- **N
|
|
82
|
-
- **Mix-and-
|
|
83
|
-
- **One
|
|
84
|
-
- **Steer
|
|
85
|
-
- **Group
|
|
85
|
+
- **N Parallel Sessions** — Every dashboard pane represents an independent agent stream tied to an independent session workspace. Add IM threads, and you scale effortlessly.
|
|
86
|
+
- **Mix-and-Match Agents** — Run Claude Code in pane 1, Codex in pane 2, and Gemini in pane 3, all working simultaneously on different repositories or workspaces.
|
|
87
|
+
- **One Unified Toolkit** — Global skills, global MCP servers, and per-workspace overrides apply uniformly. Configure it once, and every session inherits the power.
|
|
88
|
+
- **Steer from Anywhere** — Interrupt any running stream, queue a follow-up instruction, or hand over control to the next agent in line seamlessly.
|
|
89
|
+
- **Group Collaboration Mode** — Drop the orchestrator into a Feishu, Slack, Discord, or WeCom group, and let your entire team share and steer the same agent swarm.
|
|
86
90
|
|
|
87
|
-
This is the shape that matters: one creator, with a swarm at their fingertips.
|
|
91
|
+
This is the shape that matters: one creator, with a swarm of AI agents at their fingertips.
|
|
88
92
|
|
|
89
93
|
---
|
|
90
94
|
|
|
91
|
-
## See
|
|
95
|
+
## See It in Action
|
|
92
96
|
|
|
93
|
-
> **Real
|
|
97
|
+
> **Real-world Task** — Ask pikiclaw to gather and summarize today's AI news; the agent reads, writes, and ships the results back through Telegram, all controlled from your phone.
|
|
94
98
|
|
|
95
|
-
<p align="center"><img src="docs/promo-demo.gif" alt="Demo:
|
|
99
|
+
<p align="center"><img src="docs/promo-demo.gif" alt="Demo: Ask Telegram, agent works locally, result returns to chat" width="780"></p>
|
|
96
100
|
|
|
97
|
-
> **Web Dashboard** — multi-pane workspace
|
|
101
|
+
> **Web Dashboard** — A multi-pane workspace featuring a session list, conversation threads, tool-use traces, and an input composer (supporting 1, 2, 3, or 6-pane layouts).
|
|
98
102
|
|
|
99
103
|
<p align="center"><img src="docs/promo-dashboard-workspace.png" alt="Web Dashboard workspace" width="780"></p>
|
|
100
104
|
|
|
101
105
|
<details>
|
|
102
|
-
<summary><b>More:
|
|
106
|
+
<summary><b>More: Basic Ops · IM Access · Agents · Models · Extensions · Permissions · System Info</b></summary>
|
|
103
107
|
|
|
104
|
-
> Send a message, watch the agent stream, receive files back.
|
|
108
|
+
> Send a message, watch the agent stream its thoughts, and receive files back instantly.
|
|
105
109
|
|
|
106
110
|
<img src="docs/promo-basic-ops.gif" alt="Basic operations" width="780">
|
|
107
111
|
|
|
108
|
-
> **IM Access** — Telegram, Feishu, WeChat
|
|
112
|
+
> **IM Access** — Check and configure connection statuses for Telegram, Feishu, WeChat, Slack, Discord, DingTalk, and WeCom.
|
|
109
113
|
|
|
110
114
|
<img src="docs/promo-dashboard-im.png" alt="IM Access" width="780">
|
|
111
115
|
|
|
112
|
-
> **
|
|
116
|
+
> **Agents** — Manage installed agent CLIs, set your default agent, and configure per-agent models and reasoning effort levels.
|
|
117
|
+
|
|
118
|
+
<img src="docs/promo-dashboard-agents.png" alt="Agents" width="780">
|
|
113
119
|
|
|
114
|
-
|
|
120
|
+
> **Models** — A secure Providers + Profiles vault (supporting Claude, GPT, Gemini, DeepSeek, Doubao, MiMo, MiniMax, OpenRouter, and any OpenAI-compatible proxy), validated against the models.dev catalog and injected directly per agent.
|
|
115
121
|
|
|
116
|
-
> **Extensions** — global MCP servers, community skills,
|
|
122
|
+
> **Extensions** — Manage global MCP servers, community skills, and built-in automation for headless browsers and macOS desktop (Peekaboo).
|
|
117
123
|
|
|
118
124
|
<img src="docs/promo-dashboard-extensions.png" alt="Extensions" width="780">
|
|
119
125
|
|
|
120
|
-
> **System Permissions** — macOS
|
|
126
|
+
> **System Permissions** — Handle macOS Accessibility, Screen Recording, and Disk Access permissions seamlessly.
|
|
121
127
|
|
|
122
128
|
<img src="docs/promo-dashboard-permissions.png" alt="Permissions" width="780">
|
|
123
129
|
|
|
124
|
-
> **System Info** — working directory
|
|
130
|
+
> **System Info** — Monitor your working directory alongside real-time CPU, memory, and disk usage.
|
|
125
131
|
|
|
126
132
|
<img src="docs/promo-dashboard-system.png" alt="System Info" width="780">
|
|
127
133
|
|
|
@@ -129,13 +135,14 @@ This is the shape that matters: one creator, with a swarm at their fingertips.
|
|
|
129
135
|
|
|
130
136
|
---
|
|
131
137
|
|
|
132
|
-
## Quick
|
|
138
|
+
## Quick Start
|
|
133
139
|
|
|
134
|
-
**
|
|
140
|
+
**Prerequisites:** Node.js 20+, plus at least one official Agent CLI installed and authenticated on your system:
|
|
135
141
|
|
|
136
142
|
- [`claude`](https://docs.anthropic.com/en/docs/claude-code) (Claude Code)
|
|
137
143
|
- [`codex`](https://github.com/openai/codex) (Codex CLI)
|
|
138
144
|
- [`gemini`](https://github.com/google-gemini/gemini-cli) (Gemini CLI)
|
|
145
|
+
- `hermes` (Hermes — via ACP / Agent Client Protocol)
|
|
139
146
|
|
|
140
147
|
**Launch:**
|
|
141
148
|
|
|
@@ -146,152 +153,147 @@ npx pikiclaw@latest
|
|
|
146
153
|
|
|
147
154
|
<p align="center"><img src="docs/promo-install.gif" alt="One-command install" width="780"></p>
|
|
148
155
|
|
|
149
|
-
|
|
156
|
+
This instantly opens the **Web Dashboard** at `http://localhost:3939`. From there, you can drive sessions in the browser, connect IM channels, configure agents and models, install MCP servers and skills, and manage system permissions. Everything else is just one click away.
|
|
150
157
|
|
|
151
158
|
<details>
|
|
152
|
-
<summary><b>Prefer the terminal?
|
|
159
|
+
<summary><b>Prefer the terminal? We have a setup wizard.</b></summary>
|
|
153
160
|
|
|
154
161
|
```bash
|
|
155
|
-
npx pikiclaw@latest --setup #
|
|
156
|
-
npx pikiclaw@latest --doctor #
|
|
162
|
+
npx pikiclaw@latest --setup # Interactive terminal setup wizard
|
|
163
|
+
npx pikiclaw@latest --doctor # Environment health check only
|
|
157
164
|
```
|
|
158
165
|
|
|
159
166
|
</details>
|
|
160
167
|
|
|
161
168
|
---
|
|
162
169
|
|
|
163
|
-
##
|
|
170
|
+
## How People Are Using It
|
|
164
171
|
|
|
165
|
-
- **Run a
|
|
166
|
-
- **Self-
|
|
167
|
-
- **Walk-
|
|
168
|
-
- **Multi-
|
|
169
|
-
- **Domestic
|
|
170
|
-
- **Group
|
|
171
|
-
- **
|
|
172
|
-
- **Skill-
|
|
172
|
+
- **Run a Swarm in Parallel** — Open N sessions in N dashboard panes (or N IM threads), each running a different agent on a different workspace, all executing simultaneously. One person, many agents, one unified cockpit. Steer any of them at any moment.
|
|
173
|
+
- **Self-Hosted Dev Loop** — pikiclaw was built using pikiclaw. The dev workflow *is* the product: drive the orchestrator from your phone, write code, ship a release, and iterate.
|
|
174
|
+
- **Walk-Away Coding** — Kick off a massive refactoring task, close your laptop, and monitor/steer it from your phone over Telegram. The agent continues running locally, streaming results back to your chat.
|
|
175
|
+
- **Multi-Agent Tag Team** — Let Claude Code draft an initial implementation, switch to Codex for an in-depth review, and finally hand it over to Gemini for a fresh perspective. Same files, same continuous session history.
|
|
176
|
+
- **Domestic Model Routing** — When latency, cost, or compliance demands a non-frontier model, use a wrapper driver to run Claude Code effortlessly on DeepSeek or Doubao.
|
|
177
|
+
- **The Group Chat Agent** — Drop pikiclaw into a Feishu, Slack, Discord, or WeCom workgroup. The entire team shares one orchestrator, one project workspace, and a unified set of powerful skills.
|
|
178
|
+
- **Computer-Use, Controlled by You** — Enable the managed Chrome (Playwright) and macOS desktop (Peekaboo, via Accessibility + ScreenCaptureKit) capabilities. The agent can suddenly `see` the screen, click, type, and manage windows, menus, and the Dock—while you steer it from your phone. Book a meeting, scrape a complex dashboard, run end-to-end tests, or drive any native macOS application.
|
|
179
|
+
- **Skill-Driven Workflows** — Install community skills (`promote`, `snipe`, `review`, `security-review`, etc.) once, and trigger them instantly from any connected terminal using `/sk_<name>`.
|
|
173
180
|
|
|
174
181
|
---
|
|
175
182
|
|
|
176
|
-
## Features
|
|
183
|
+
## Core Features
|
|
177
184
|
|
|
178
|
-
### Terminal
|
|
185
|
+
### Terminal Layer
|
|
179
186
|
|
|
180
|
-
- **Telegram, Feishu, WeChat
|
|
181
|
-
- **Web Dashboard** —
|
|
182
|
-
- **Live
|
|
187
|
+
- **Seven Native IM Channels** — Telegram, Feishu, WeChat (personal), Slack, Discord, DingTalk, and WeCom. Run one, several, or all of them simultaneously. Each channel is strictly isolated at the code level; adding a new one (like WhatsApp or a mobile app) requires zero changes to the others.
|
|
188
|
+
- **Web Dashboard** — Drive sessions directly from your browser with the exact same conversational flow, tool-use tracing, and streaming experience as IM. Enjoy a multi-pane workspace (1/2/3/6 panes), light/dark themes, and full EN/中文 i18n support.
|
|
189
|
+
- **Live Streaming Preview** — Watch messages update in place as the agent thinks. Long text auto-splits beautifully; images and files stream back to the UI in real time.
|
|
183
190
|
|
|
184
|
-
### Agent
|
|
191
|
+
### Agent Layer
|
|
185
192
|
|
|
186
|
-
- **Official CLIs as
|
|
187
|
-
- **
|
|
188
|
-
- **
|
|
189
|
-
- **
|
|
190
|
-
- **
|
|
193
|
+
- **Official CLIs as Drivers** — Powered directly by Claude Code, Codex CLI, Gemini CLI, and Hermes (via ACP). We don't rewrite the agent core—you inherit upstream capabilities and Day-0 updates automatically.
|
|
194
|
+
- **ACP-Native Architecture** — Hermes integrates natively through the [Agent Client Protocol](https://agentclientprotocol.com), spawning `hermes acp` over JSON-RPC stdio. Any future ACP-compatible agent plugs in the exact same way.
|
|
195
|
+
- **Pluggable Driver Registry** — The only contract is `src/agent/driver.ts`. New CLI- or ACP-based agents can drop right in alongside our four built-in drivers.
|
|
196
|
+
- **Per-Session Agent Switching** — Swap the "brain" on the fly without leaving your workspace.
|
|
197
|
+
- **Steer & Interrupt** — Interrupt a heavy running task and force a queued message to the front of the line.
|
|
198
|
+
- **Codex Human-in-the-Loop** — When Codex pauses to ask you a question, it forwards the prompt interactively to your IM. Reply directly in the chat, and the task resumes seamlessly.
|
|
199
|
+
- **Persistent Goals** — Use `/goal` to set a long-running, session-scoped objective complete with a token budget. Supports pause/resume, and the agent will autonomously self-terminate only when it verifies the goal is complete.
|
|
191
200
|
|
|
192
|
-
### Model
|
|
201
|
+
### Model Layer
|
|
193
202
|
|
|
194
|
-
- **Frontier +
|
|
195
|
-
- **
|
|
196
|
-
- **
|
|
203
|
+
- **Frontier + Domestic + Proxies** — Supports the Claude 4 family, GPT-5 / Codex, Gemini, DeepSeek, Doubao, MiMo, MiniMax, OpenRouter, and any custom OpenAI-compatible proxy endpoint.
|
|
204
|
+
- **Providers & Profiles Vault** — A first-class data model that securely isolates credentials in `~/.pikiclaw/setting.json`. Browse a read-only models.dev catalog, validate keys with real provider probes, and bind a profile to an agent for automatic environment injection at spawn-time.
|
|
205
|
+
- **Per-Session Model & Reasoning Effort** — Switch models or adjust reasoning capabilities dynamically via the Dashboard, `/models`, or `/mode`.
|
|
206
|
+
- **Per-Agent Deep Injection** — `resolveAgentInjection(agentId)` forces the active profile's environment variables down at spawn time. This means you can run Claude Code on top of DeepSeek or Doubao without ever touching the upstream client's config.
|
|
197
207
|
|
|
198
|
-
### Tool
|
|
208
|
+
### Tool Layer
|
|
199
209
|
|
|
200
|
-
- **Skills** —
|
|
201
|
-
- **MCP
|
|
202
|
-
- **CLI
|
|
203
|
-
- **
|
|
210
|
+
- **Robust Skills System** — Project-specific skills live safely in `.pikiclaw/skills/*/SKILL.md` (and we fully support legacy `.claude/commands/*.md` formats). Install community packages with one click from GitHub (`owner/repo`) or browse our curated packs (like Anthropic Official, Vercel Agent Skills, etc.). Trigger them anywhere with `/skills` and `/sk_<name>`.
|
|
211
|
+
- **Massive MCP Server Ecosystem** — Browse the [MCP Registry](https://registry.modelcontextprotocol.io), add custom stdio or HTTP servers, enforce real handshake health-checks, and utilize OAuth 2.1 with Dynamic Client Registration. Our recommended catalog flawlessly covers GitHub, Atlassian, Notion, Linear, Sentry, Cloudflare, Slack, Feishu/Lark, Stripe, Hugging Face, Gamma, Brave Search, Perplexity, Filesystem, SQLite, and PostgreSQL. Furthermore, we ship with two built-in, hyper-powerful computer-use servers: `pikiclaw-browser` (driving Chrome via Playwright) and `peekaboo` (driving the macOS GUI via Peekaboo).
|
|
212
|
+
- **Seamless CLI Tool Integration** — Auto-detects versions and authentication states for popular CLIs. We natively support OAuth-web login handoffs for browser-based authentications, routing everything smoothly through the agent's standard tool surface.
|
|
213
|
+
- **Session-Scoped MCP Bridge** — Foundational tools like `im_list_files`, `im_send_file`, `im_ask_user`, alongside the managed browser and macOS desktop tools (when enabled), are automatically injected deep into every single session you launch.
|
|
214
|
+
- **Two-Tier Merge Resolution** — Tool scopes follow a simple rule: `global < workspace < built-in`. The engine automatically resolves and merges these, applying them silently to every session.
|
|
204
215
|
|
|
205
216
|
<p align="center"><img src="docs/promo-dashboard-extensions-add.png" alt="Add MCP server" width="780"></p>
|
|
206
217
|
|
|
207
|
-
### Runtime &
|
|
218
|
+
### Runtime & Developer Experience
|
|
208
219
|
|
|
209
|
-
- **Session
|
|
210
|
-
- **Resume,
|
|
211
|
-
- **
|
|
212
|
-
- **
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
- **Long-task hardening** — sleep prevention, watchdog, auto-restart, daemon mode.
|
|
220
|
+
- **Dedicated Session Workspaces** — Every session gets its own isolated directory; file attachments and generated assets drop there automatically.
|
|
221
|
+
- **Resume, Switch, and Classify** — Flawless multi-turn conversation support with smart session classification (identifying answers, proposals, implementations, or blocked states).
|
|
222
|
+
- **Auto-Injected Base Tools** — Core MCP tools like file listing, sending, user prompting, and goal tracking are hard-wired into every stream.
|
|
223
|
+
- **Computer-Use (Browser Engine)** — The built-in `pikiclaw-browser` MCP is a hyper-charged wrapper over `@playwright/mcp`. It includes a process-level supervisor and shares an isolated Chrome profile. Log in to your tools once, and reuse those authenticated sessions across all future tasks!
|
|
224
|
+
- **Computer-Use (macOS Desktop)** — Enable the `peekaboo` MCP built-in server (macOS only) to unleash the [Peekaboo](https://peekaboo.sh/) framework over Accessibility and ScreenCaptureKit APIs. It exposes a god-mode suite of tools: `see`, `click`, `type`, `scroll`, `window`, `menu`, `app`, and `dock`. Requires explicit OS-level permissions but grants unprecedented control.
|
|
225
|
+
- **Hardened for Long Tasks** — Built with sleep prevention, watchdog timers, auto-restarts, daemon modes, and a robust channel supervisor. You can walk away knowing your marathon tasks are protected by an ironclad runtime.
|
|
216
226
|
|
|
217
227
|
---
|
|
218
228
|
|
|
219
|
-
## How
|
|
229
|
+
## How Is This Different?
|
|
220
230
|
|
|
221
|
-
| | pikiclaw | IDE
|
|
231
|
+
| Feature | pikiclaw | IDE Assistants<br>(Cursor / Windsurf / Aider) | Cloud Agents<br>(Devin / Web Claude) | Single-Agent IM Bots |
|
|
222
232
|
|---|---|---|---|---|
|
|
223
|
-
| **Terminal** | IM + Web +
|
|
224
|
-
| **
|
|
225
|
-
| **Agent
|
|
226
|
-
| **Model
|
|
227
|
-
| **
|
|
228
|
-
| **Files
|
|
229
|
-
| **
|
|
230
|
-
| **
|
|
231
|
-
| **Self-
|
|
232
|
-
|
|
233
|
-
The shape that matters: **
|
|
233
|
+
| **Terminal Access** | 7 IM channels + Web + Extensible | Locked inside the IDE | Confined to a Web app | One specific IM app |
|
|
234
|
+
| **Execution Environment** | Your local machine | Your local machine | Vendor's remote sandbox | Usually vendor servers |
|
|
235
|
+
| **Agent Flexibility** | Claude Code, Codex, Gemini, Hermes (ACP), etc. | Locked in | Single | Single |
|
|
236
|
+
| **Model Freedom** | Frontier models, domestic giants, OpenAI-proxies | Controlled by the platform | Controlled by the vendor | Single, hardcoded |
|
|
237
|
+
| **Concurrency Power** | **N Agents × N Windows × N Workspaces** | One agent per IDE window | Strictly sequential | Single thread |
|
|
238
|
+
| **Files & Tools Access** | Your entire local disk, your MCPs, your CLIs | Local project files | Heavily sandboxed | None or extremely limited |
|
|
239
|
+
| **Add a New Terminal** | Drop in a simple `Channel` class | Impossible | Impossible | Requires a hard fork |
|
|
240
|
+
| **Add a New Agent** | Implement a simple `AgentDriver` (CLI or ACP) | Impossible | Impossible | Requires a hard fork |
|
|
241
|
+
| **Self-Bootstrapping** | **Yes — completely built using itself** | No | No | No |
|
|
242
|
+
|
|
243
|
+
The shape that truly matters: **You never have to leave your preferred environment, you retain total choice over the "brain", you can drive a massive swarm in parallel, and the orchestrator is the exact same tool we use to build the orchestrator.**
|
|
234
244
|
|
|
235
245
|
---
|
|
236
246
|
|
|
237
|
-
##
|
|
247
|
+
## Command Reference
|
|
238
248
|
|
|
239
249
|
| Command | Description |
|
|
240
250
|
|---|---|
|
|
241
|
-
| `/start` |
|
|
242
|
-
| `/sessions` | View, switch, or create sessions |
|
|
243
|
-
| `/agents` | Switch
|
|
244
|
-
| `/models` | View and switch model
|
|
245
|
-
| `/mode` | Toggle plan mode
|
|
246
|
-
| `/switch` | Browse and switch working directory |
|
|
247
|
-
| `/
|
|
248
|
-
| `/
|
|
249
|
-
| `/
|
|
250
|
-
| `/
|
|
251
|
-
| `/
|
|
252
|
-
| `/
|
|
253
|
-
| `/
|
|
254
|
-
|
|
255
|
-
|
|
251
|
+
| `/start` | View entry info, the active agent, and your working directory |
|
|
252
|
+
| `/sessions` | View, switch, or create new sessions |
|
|
253
|
+
| `/agents` | Switch the active Agent (Claude · Codex · Gemini · Hermes) |
|
|
254
|
+
| `/models` | View and switch the model or reasoning effort for the session |
|
|
255
|
+
| `/mode` | Toggle plan mode / reasoning effort |
|
|
256
|
+
| `/switch` | Browse and switch the working directory |
|
|
257
|
+
| `/workspaces` | Pick a saved workspace from the Dashboard's quick-pick list |
|
|
258
|
+
| `/goal` | Set or inspect a long-running, self-terminating session goal |
|
|
259
|
+
| `/stop` | Force-stop the current session |
|
|
260
|
+
| `/status` | Check runtime status, token usage, resource consumption, and session info |
|
|
261
|
+
| `/host` | Monitor host CPU, memory, disk, and battery levels |
|
|
262
|
+
| `/skills` | Browse available project skills |
|
|
263
|
+
| `/ext` | View the extensions overview |
|
|
264
|
+
| `/restart` | Restart and re-launch the underlying Bot service |
|
|
265
|
+
| `/sk_<name>` | Instantly run a specific project skill |
|
|
266
|
+
|
|
267
|
+
*Note: Plain text without a slash is forwarded directly to the current agent.*
|
|
256
268
|
|
|
257
269
|
---
|
|
258
270
|
|
|
259
271
|
## Configuration
|
|
260
272
|
|
|
261
|
-
- Persistent
|
|
262
|
-
- The Dashboard is the primary configuration
|
|
263
|
-
- Global MCP extensions
|
|
264
|
-
- Workspace MCP extensions
|
|
265
|
-
|
|
266
|
-
<details>
|
|
267
|
-
<summary><b>GUI automation setup (browser + macOS desktop)</b></summary>
|
|
268
|
-
|
|
269
|
-
**Browser** is fully managed by the dashboard — a dedicated Chrome profile is created and reused. Log in to the sites you need once, every future agent session reuses those credentials.
|
|
270
|
-
|
|
271
|
-
**macOS desktop** needs Appium Mac2:
|
|
272
|
-
|
|
273
|
-
```bash
|
|
274
|
-
npm install -g appium
|
|
275
|
-
appium driver install mac2
|
|
276
|
-
appium
|
|
277
|
-
```
|
|
273
|
+
- **Persistent Configuration:** `~/.pikiclaw/setting.json` stores your channels, agents, Providers/Profiles, workspaces, and MCP extensions.
|
|
274
|
+
- The **Dashboard** is the primary UI for configuration. The terminal wizard (`--setup`) and the doctor script (`--doctor`) are available for headless or CLI-first users.
|
|
275
|
+
- Global MCP extensions are stored under the `extensions.mcp` key in the setting file.
|
|
276
|
+
- Workspace MCP extensions follow standard conventions and are read from `.mcp.json` in the project root.
|
|
277
|
+
- Project skills are loaded automatically from `.pikiclaw/skills/*/SKILL.md` (and we also support legacy `.claude/commands/*.md` formats).
|
|
278
278
|
|
|
279
|
-
|
|
279
|
+
**Computer-Use Toggles** (managed via the Extensions dashboard):
|
|
280
280
|
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
</details>
|
|
281
|
+
- `browserEnabled` — Enables managed Chrome (Playwright). Upon first use, pikiclaw creates a dedicated profile in `~/.pikiclaw` and reuses it for subsequent sessions. Log in once, and never scan a QR code or enter a password for those tools again.
|
|
282
|
+
- `peekabooEnabled` — Enables macOS desktop automation (Peekaboo). Available on macOS only. Activating this launches `@steipete/peekaboo`'s `peekaboo-mcp` binary and injects its UI-controlling tools. *Note: You must grant your terminal **Accessibility** and **Screen Recording** permissions in System Settings → Privacy & Security before enabling this.*
|
|
284
283
|
|
|
285
284
|
---
|
|
286
285
|
|
|
287
286
|
## Roadmap
|
|
288
287
|
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
- **More
|
|
292
|
-
- **
|
|
293
|
-
- **
|
|
294
|
-
- **
|
|
288
|
+
**Already Shipped:** Hermes driver integration · ACP (Agent Client Protocol) · Secure Provider/Profile vault · Seven native IM channels · Computer-use via Playwright and Peekaboo (macOS).
|
|
289
|
+
|
|
290
|
+
- **More ACP Agents** — Ensuring any new ACP-compatible agent can drop in with zero code changes.
|
|
291
|
+
- **Broader Terminal Ecosystem** — Adding support for WhatsApp, a dedicated mobile app, and voice interfaces.
|
|
292
|
+
- **Deeper Model Wrapping** — Building agent-on-arbitrary-model wrappers to support a wider array of domestic and open-source models seamlessly.
|
|
293
|
+
- **Richer Tool Ecosystem** — Releasing official MCP packs, skill templates, and a community marketplace.
|
|
294
|
+
- **Cross-Platform Computer-Use** — Extending desktop control drivers beyond macOS to support Windows and Linux.
|
|
295
|
+
|
|
296
|
+
For protocol-level insights, see our [ACP Migration Plan](docs/acp-migration.md).
|
|
295
297
|
|
|
296
298
|
---
|
|
297
299
|
|
|
@@ -306,42 +308,43 @@ npm test
|
|
|
306
308
|
```
|
|
307
309
|
|
|
308
310
|
```bash
|
|
309
|
-
npm run dev # local dev (--no-daemon, logs to ~/.pikiclaw/dev/dev.log)
|
|
310
|
-
npm run build #
|
|
311
|
-
npm test #
|
|
312
|
-
|
|
313
|
-
npx pikiclaw@latest --doctor # environment check
|
|
311
|
+
npm run dev # Start local dev server (--no-daemon, logs to ~/.pikiclaw/dev/dev.log)
|
|
312
|
+
npm run build # Production build (Dashboard + tsc)
|
|
313
|
+
npm test # Run Vitest suite
|
|
314
|
+
npx pikiclaw@latest --doctor # Environment health check
|
|
314
315
|
```
|
|
315
316
|
|
|
316
|
-
|
|
317
|
+
For deep dives into the architecture and integration, see: [ARCHITECTURE.md](ARCHITECTURE.md) · [INTEGRATION.md](INTEGRATION.md) · [TESTING.md](TESTING.md).
|
|
317
318
|
|
|
318
319
|
---
|
|
319
320
|
|
|
320
321
|
## Contributing
|
|
321
322
|
|
|
322
|
-
|
|
323
|
+
Every layer of this project was designed from the ground up to be **extended**. Adding a new terminal, writing a new agent driver, wrapping a new model, or building a killer MCP tool—these are all first-class contributions.
|
|
323
324
|
|
|
324
|
-
- Read the **[Contributing Guide](CONTRIBUTING.md)** to get started
|
|
325
|
-
-
|
|
326
|
-
-
|
|
325
|
+
- Read the **[Contributing Guide](CONTRIBUTING.md)** to get started.
|
|
326
|
+
- Check out issues tagged with [`good first issue`](https://github.com/xiaotonng/pikiclaw/labels/good%20first%20issue) and [`help wanted`](https://github.com/xiaotonng/pikiclaw/labels/help%20wanted).
|
|
327
|
+
- For major architectural changes, please open an issue first to align on the technical approach.
|
|
327
328
|
|
|
328
|
-
|
|
|
329
|
+
| Module | What You Can Extend |
|
|
329
330
|
|---|---|
|
|
330
|
-
| `src/agent/driver.ts`, `src/agent/drivers/*.ts` |
|
|
331
|
-
| `src/channels/base.ts`, `src/channels/*/` |
|
|
332
|
-
| `src/
|
|
333
|
-
| `src/
|
|
331
|
+
| `src/agent/driver.ts`, `src/agent/drivers/*.ts`, `src/agent/acp-client.ts` | Add a new Agent Driver (CLI-based or ACP-compatible) |
|
|
332
|
+
| `src/channels/base.ts`, `src/channels/*/` | Integrate a new Terminal or IM channel |
|
|
333
|
+
| `src/model/`, `src/model/injector.ts` | Add a new model provider or customize agent environment injection rules |
|
|
334
|
+
| `src/dashboard/routes/*.ts` | Expand the Dashboard backend API |
|
|
335
|
+
| `src/agent/mcp/tools/*.ts`, `src/agent/mcp/bridge.ts` | Add new session-scoped MCP tools |
|
|
336
|
+
| `src/catalog/*.ts` | Recommend high-quality MCP servers, CLI tools, or Skill repositories |
|
|
334
337
|
|
|
335
338
|
---
|
|
336
339
|
|
|
337
|
-
## Star
|
|
340
|
+
## Star History
|
|
338
341
|
|
|
339
342
|
<a href="https://www.star-history.com/#xiaotonng/pikiclaw&Date">
|
|
340
|
-
<img src="https://api.star-history.com/svg?repos=xiaotonng/pikiclaw&type=Date" alt="Star
|
|
343
|
+
<img src="https://api.star-history.com/svg?repos=xiaotonng/pikiclaw&type=Date" alt="Star History" width="640">
|
|
341
344
|
</a>
|
|
342
345
|
|
|
343
346
|
---
|
|
344
347
|
|
|
345
348
|
## License
|
|
346
349
|
|
|
347
|
-
[MIT](LICENSE) —
|
|
350
|
+
[MIT](LICENSE) — Built in the open. Use it, fork it, and plug in your own layers.
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,350 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# pikiclaw
|
|
4
|
+
|
|
5
|
+
## 把全世界最聪明的 AI Agent 装进你的口袋。
|
|
6
|
+
|
|
7
|
+
##### *面向「创作者不再需要看代码」时代的开放式 Agent 编排器。*
|
|
8
|
+
|
|
9
|
+
*接入任何 Agent（Claude · Codex · Gemini · Hermes · …），任何模型（Claude · GPT · Gemini · DeepSeek · 豆包 · MiMo · MiniMax · OpenRouter · 甚至是任意第三方代理），以及任何工具（Skills · MCP · CLI）。通过你最顺手的终端（IM、Web 或未来形态）来驱动它们。pikiclaw 本身就是用 pikiclaw 构建的。*
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npx pikiclaw@latest
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
<p>
|
|
16
|
+
<a href="https://www.npmjs.com/package/pikiclaw"><img src="https://img.shields.io/npm/v/pikiclaw?label=npm&color=cb3837" alt="npm"></a>
|
|
17
|
+
<a href="https://www.npmjs.com/package/pikiclaw"><img src="https://img.shields.io/npm/dm/pikiclaw?label=downloads&color=success" alt="npm downloads"></a>
|
|
18
|
+
<a href="https://github.com/xiaotonng/pikiclaw/stargazers"><img src="https://img.shields.io/github/stars/xiaotonng/pikiclaw?style=flat&color=yellow" alt="GitHub stars"></a>
|
|
19
|
+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
|
|
20
|
+
<a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%E2%89%A520-green.svg" alt="Node 20+"></a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
<p>
|
|
24
|
+
<a href="README.md">English</a> | <b>简体中文</b>
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
<img src="docs/workspace.png" alt="工作区" width="780">
|
|
28
|
+
|
|
29
|
+
</div>
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## pikiclaw 是什么？
|
|
34
|
+
|
|
35
|
+
**大多数「AI 开发工具」往往只做局部的创新 —— 绑定一款 IDE、单一 Agent 或某家模型厂商，然后便止步于此。** pikiclaw 则建立在一个截然不同的判断之上：下一代「创造」的过程，不会局限在某个单一的编辑器内部。它会发生在一个**编排器 (Orchestrator)** 中。在这里，创作者可以并发出一个 Agent **集群 (Swarm)**，让它们跑在当前最强大的模型上，并通过手边最方便的终端来掌控全局——而且，你甚至不需要打开任何代码文件。
|
|
36
|
+
|
|
37
|
+
核心产品就是这个编排器，其它所有组件都可拔插。**更酷的是，这个编排器是由它自己构建出来的** —— pikiclaw 就是我们用来开发 pikiclaw 的工具。
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
终端层 Telegram · 飞书 · 微信 · Slack · Discord · 钉钉 · 企业微信 · Web Dashboard
|
|
41
|
+
\__________________________|__________________________/
|
|
42
|
+
v
|
|
43
|
+
┌──────────────────────────────┐
|
|
44
|
+
│ pikiclaw 编排器 │
|
|
45
|
+
└──────────────────────────────┘
|
|
46
|
+
|
|
|
47
|
+
┌────────────────────────────────────────┼────────────────────────────────────────┐
|
|
48
|
+
v v v
|
|
49
|
+
Agent 层 模型层 工具层
|
|
50
|
+
Claude Code · Codex · Gemini · Hermes Claude · GPT · Gemini · DeepSeek Skills · MCP · CLI
|
|
51
|
+
(driver registry · ACP · 任意 Agent) 豆包 · MiMo · MiniMax · OpenRouter (全局 × 工作区)
|
|
52
|
+
· 任意 OpenAI 兼容代理 · …
|
|
53
|
+
|
|
|
54
|
+
v
|
|
55
|
+
你的电脑
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
- **终端层 (Terminal)** —— Telegram、飞书、微信、Slack、Discord、钉钉、企业微信以及 Web Dashboard 都是一等公民入口。新的终端形态可以随时接入。
|
|
59
|
+
- **Agent 层** —— 官方的 Claude Code / Codex / Gemini / Hermes CLI 作为底层驱动 (driver)。其中 Hermes 使用 ACP (Agent Client Protocol，客户端协议)；注册表机制允许无缝接入任何其他的 Agent。
|
|
60
|
+
- **模型层 (Model)** —— Claude / GPT / Gemini、国产系列 (DeepSeek、豆包、MiMo、MiniMax)，外加 OpenRouter 以及任何兼容 OpenAI 接口的代理服务。提供商 (Providers) 与配置项 (Profiles) 是一等公民模块，自带凭据保险箱、models.dev 目录以及面向各个 Agent 专属的环境变量注入能力。
|
|
61
|
+
- **工具层 (Tool)** —— Skills、MCP 服务器和 CLI 工具。它们会在全局和工作区两个层级进行智能合并，并被自动注入到每一次会话之中。
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## 自举：用自己构建自己
|
|
66
|
+
|
|
67
|
+
> 检验一个 Agent 编排器是否靠谱，最硬核的标准就是看它能不能自举（构建自己）。pikiclaw 做到了。我们日常使用 pikiclaw 来开发、测试、发布和运维 pikiclaw —— 覆盖了每一次 Commit 和每一次版本发布。
|
|
68
|
+
|
|
69
|
+
在 pikiclaw 里的典型开发日常是这样的：
|
|
70
|
+
|
|
71
|
+
- 窗口 1 里的 Claude Code 会话正在实现一个全新的 dashboard 路由。
|
|
72
|
+
- 窗口 2 里的 Codex 会话正在为它编写配套的单元测试，并在同一个工作区下运行。
|
|
73
|
+
- 窗口 3 里的 Gemini 会话在 Review Diff，并起草更新日志。
|
|
74
|
+
- 与此同时，第四条线程中的技能 (`/sk_promote`) 正在自动扫描 GitHub 的相关 Issue 并尝试回复。
|
|
75
|
+
- 这四个进程完全并行运作；而掌控它们的人，可能只是坐在咖啡馆里用一部手机进行统筹安排。
|
|
76
|
+
|
|
77
|
+
这个编排器就是产品本身，同时，它也恰好是我们用来构建它的 IDE。
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 默认并发集群 (Swarm)
|
|
82
|
+
|
|
83
|
+
大多数「AI 开发工具」的基本假设是：一个用户，一次只让一个 Agent 做一件事。pikiclaw 的假设则完全相反：**N 个 Agent，N 个窗口，一位指挥官，一套工具箱。**
|
|
84
|
+
|
|
85
|
+
- **N 路并行会话** —— Dashboard 上的每一个面板都是一条独立的 Agent 流，对应着一个独立的会话工作区；如果接入 IM，还能随时开辟出更多的工作线程。
|
|
86
|
+
- **Agent 随意混搭** —— 面板 1 跑 Claude Code，面板 2 跑 Codex，面板 3 跑 Gemini，它们可以在不同的代码仓库和工作区中各司其职。
|
|
87
|
+
- **统一的工具箱** —— 全局的 Skills、全局 MCP 服务器以及工作区专属的覆盖配置都会进行统一管理。只需配置一次，后续所有会话即可自动继承。
|
|
88
|
+
- **随时随地介入** —— 你可以随时打断运行中的数据流，将新指令插队，或者把控制权顺滑交接给下一个 Agent。
|
|
89
|
+
- **群组协作模式** —— 把编排器拉进飞书 / Slack / Discord / 企业微信的聊天群中，团队成员便能集体共享这同一个 Agent 集群。
|
|
90
|
+
|
|
91
|
+
这正是我们认为最关键的形态：让每个创作者的指尖，都掌控着一支全天候待命的 AI 军队。
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## 实际演示
|
|
96
|
+
|
|
97
|
+
> **真实任务** —— 让 pikiclaw 收集并总结今天的 AI 新闻；Agent 自动阅读、撰写，最后通过 Telegram 将结果推送到你的手机上。
|
|
98
|
+
|
|
99
|
+
<p align="center"><img src="docs/promo-demo.gif" alt="演示：从 Telegram 发起任务，Agent 在本地执行，结果回到聊天" width="780"></p>
|
|
100
|
+
|
|
101
|
+
> **Web Dashboard** —— 多面板工作区，包含会话列表、对话流、工具调用轨迹以及输入区域（支持 1 / 2 / 3 / 6 面板布局）。
|
|
102
|
+
|
|
103
|
+
<p align="center"><img src="docs/promo-dashboard-workspace.png" alt="Web Dashboard 工作区" width="780"></p>
|
|
104
|
+
|
|
105
|
+
<details>
|
|
106
|
+
<summary><b>更多细节：基础操作 · IM 接入 · Agent 管理 · 模型配置 · 扩展工具 · 权限 · 系统信息</b></summary>
|
|
107
|
+
|
|
108
|
+
> 发送消息，观察 Agent 的流式输出，接收返回的文件附件。
|
|
109
|
+
|
|
110
|
+
<img src="docs/promo-basic-ops.gif" alt="基础操作" width="780">
|
|
111
|
+
|
|
112
|
+
> **IM 接入** —— Telegram、飞书、微信、Slack、Discord、钉钉、企业微信的频道连接状态与参数配置。
|
|
113
|
+
|
|
114
|
+
<img src="docs/promo-dashboard-im.png" alt="IM 接入" width="780">
|
|
115
|
+
|
|
116
|
+
> **Agent 管理** —— 已安装的 Agent CLI 列表、默认 Agent 设定，以及各自独立的模型 / 推理强度配置。
|
|
117
|
+
|
|
118
|
+
<img src="docs/promo-dashboard-agents.png" alt="Agent" width="780">
|
|
119
|
+
|
|
120
|
+
> **模型配置** —— 整合了 Provider + Profile 的凭据库（涵盖 Claude、GPT、Gemini、DeepSeek、豆包、MiMo、MiniMax、OpenRouter 及任何兼容 OpenAI 接口的代理），支持通过 models.dev 目录进行验证，并为指定的 Agent 独立进行底层环境变量注入。
|
|
121
|
+
|
|
122
|
+
> **扩展工具** —— 统一管理全局 MCP 服务器、社区版 Skills、内置托管的浏览器环境及 macOS 桌面（Peekaboo）自动化能力。
|
|
123
|
+
|
|
124
|
+
<img src="docs/promo-dashboard-extensions.png" alt="扩展" width="780">
|
|
125
|
+
|
|
126
|
+
> **系统权限** —— macOS 辅助功能、屏幕录制及磁盘访问权限管理。
|
|
127
|
+
|
|
128
|
+
<img src="docs/promo-dashboard-permissions.png" alt="权限" width="780">
|
|
129
|
+
|
|
130
|
+
> **系统信息** —— 当前工作目录详情，以及 CPU / 内存 / 磁盘使用率的全天候监控。
|
|
131
|
+
|
|
132
|
+
<img src="docs/promo-dashboard-system.png" alt="系统信息" width="780">
|
|
133
|
+
|
|
134
|
+
</details>
|
|
135
|
+
|
|
136
|
+
---
|
|
137
|
+
|
|
138
|
+
## 快速开始
|
|
139
|
+
|
|
140
|
+
**前置要求：** 环境须具备 Node.js 20+，并且在系统中至少登录过一款官方的 Agent CLI：
|
|
141
|
+
|
|
142
|
+
- [`claude`](https://docs.anthropic.com/en/docs/claude-code) (Claude Code)
|
|
143
|
+
- [`codex`](https://github.com/openai/codex) (Codex CLI)
|
|
144
|
+
- [`gemini`](https://github.com/google-gemini/gemini-cli) (Gemini CLI)
|
|
145
|
+
- `hermes` (Hermes —— 基于 ACP / Agent Client Protocol 协议)
|
|
146
|
+
|
|
147
|
+
**启动命令：**
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
cd your-workspace
|
|
151
|
+
npx pikiclaw@latest
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
<p align="center"><img src="docs/promo-install.gif" alt="一行命令安装" width="780"></p>
|
|
155
|
+
|
|
156
|
+
这条命令会在 `http://localhost:3939` 自动唤起 **Web Dashboard**。随后，你就可以在浏览器里驱动任何会话、接入需要的 IM 渠道、灵活配置 Agent 和模型、快速安装 MCP 服务器与技能 (Skills)，并统筹所有的系统权限。其他一切功能，尽在一键之遥。
|
|
157
|
+
|
|
158
|
+
<details>
|
|
159
|
+
<summary><b>更喜欢传统的纯命令行配置？我们准备了专用的配置向导。</b></summary>
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npx pikiclaw@latest --setup # 开启交互式终端配置向导
|
|
163
|
+
npx pikiclaw@latest --doctor # 仅检查并诊断当前环境
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
</details>
|
|
167
|
+
|
|
168
|
+
---
|
|
169
|
+
|
|
170
|
+
## 典型的应用场景
|
|
171
|
+
|
|
172
|
+
- **并发运行集群** —— 在 Dashboard 里打开 N 个面板（或者开辟 N 个 IM 线程），每个面板运行不同的 Agent 负责不同的工作区，完全并行运作。一个人，多个 Agent，同一个全局驾驶舱。你可以随时强力介入任何一个工作流。
|
|
173
|
+
- **自包含的闭环开发** —— pikiclaw 就是用 pikiclaw 自己开发出来的。这套开发流本身就是这款产品最原始的面貌：甚至可以在外用手机操作编排器，让 Agent 写代码、发布版本并不断迭代。
|
|
174
|
+
- **挂机式编程 (Walk-away coding)** —— 发起一个耗时极长的大型重构任务，合上笔记本，外出时直接用手机通过 Telegram 进行监控和控制。Agent 始终在本地机器上运行，结果则会流式实时推回聊天界面中。
|
|
175
|
+
- **同工作区多 Agent 接力** —— 先让 Claude Code 写一版功能草稿，无缝切给 Codex 去做深度 Review，最后再交给 Gemini 提供截然不同视角的优化建议。所有这些操作都在同一份代码目录和相同的历史会话中完成。
|
|
176
|
+
- **灵活的国产模型路由方案** —— 当你的任务对延迟、成本或合规有硬性要求时，通过模型驱动包装层，可以直接让 Claude Code 跑在实惠又快速的 DeepSeek 或豆包模型之上。
|
|
177
|
+
- **群聊协作级 Agent** —— 把 pikiclaw 拉入飞书 / Slack / Discord / 企业微信群聊内；整个团队可以共享这同一个编排器、统一的项目工作区和一系列团队专属技能。
|
|
178
|
+
- **完全受控的 Computer-use 能力** —— 开启内置的 Chrome 浏览器托管（基于 Playwright）和 macOS 桌面环境托管（基于 Peekaboo，通过辅助功能和 ScreenCaptureKit）。Agent 瞬间获得「视力」(`see`)、可以自由点击、打字，并管理窗口、菜单栏和 Dock，而你依然可以通过手机远程精准操控它。无论是帮你预定一场会议、抓取某个数据面板信息、跑一通端到端自动测试，还是驱动任何原生的 macOS 本地应用，全都不在话下。
|
|
179
|
+
- **基于 Skill 体系的自动化工作流** —— 一次性安装好社区提供的常用技能（例如 `promote`、`snipe`、`review`、`security-review` 等），往后只需在任何连接的终端里输入 `/sk_<name>` 即可实现一键触发。
|
|
180
|
+
|
|
181
|
+
---
|
|
182
|
+
|
|
183
|
+
## 核心特性
|
|
184
|
+
|
|
185
|
+
### 终端层 (Terminal)
|
|
186
|
+
|
|
187
|
+
- **支持七大主流 IM** —— 全面集成 Telegram、飞书、微信（个人号）、Slack、Discord、钉钉和企业微信。你可以只开启其中一个，也可以多开齐上。底层代码中每个渠道都做到绝对隔离；即使后续再添加新渠道（如 WhatsApp、自有移动 App 等），也丝毫不会影响现有逻辑的稳定性。
|
|
188
|
+
- **Web Dashboard 面板** —— 直接在网页浏览器中驱动所有会话，获得与 IM 完全一致的自然对话、工具调用轨迹跟踪和极速的流式反馈体验。面板提供 1 / 2 / 3 / 6 多窗口并发布局、深色/浅色自适应主题，以及纯正的中英文 (i18n) 双语支持。
|
|
189
|
+
- **实时流式预览** —— 每当 Agent 开始思考，消息都会实时在原地进行刷新；遇到超长文本能自动进行友好分段；生成的图片与文件也会即刻原样推回前端界面。
|
|
190
|
+
|
|
191
|
+
### Agent 层
|
|
192
|
+
|
|
193
|
+
- **官方 CLI 作为原生底层驱动** —— 内置接入 Claude Code、Codex CLI、Gemini CLI 以及 Hermes (通过 ACP 协议)。我们坚决拒绝自己「造一套套壳的 Agent 引擎」——只要上游核心推出了任何更新功能，你就可以在第一时间无损享用。
|
|
194
|
+
- **原生拥抱 ACP 协议** —— Hermes 的接入完全基于 [Agent Client Protocol](https://agentclientprotocol.com) 协议，通过系统标准的 JSON-RPC (输入/输出流) 唤起 `hermes acp`。这意味着在未来，任何兼容 ACP 协议的新 Agent 也能立刻无缝空降至平台。
|
|
195
|
+
- **自由可插拔的注册表机制** —— 在整套代码库中，这部分唯一的强制契约只有 `src/agent/driver.ts`。不论是基于传统 CLI 还是新兴 ACP 协议开发的各类新 Agent，都能随时加入注册表，与现有的四大核心内置引擎并肩作战。
|
|
196
|
+
- **无感会话级 Agent 切换** —— 你甚至不用离开当前代码工作区，就能在会话途中随时顺畅地帮 AI 更换一颗不同特性的「大脑」。
|
|
197
|
+
- **接管与干预 (Steer) 控制** —— 你可以随心所欲中断正在执行的繁重任务，让排队的紧急新消息直接插队至最前方处理。
|
|
198
|
+
- **Codex 人机协同机制 (Human-in-the-loop)** —— 当 Codex 需要你确认操作细节时，这些提示请求会自动转化发送为 IM 中的互动询问消息。你只需在平常用的聊天框内简单答复，暂停的任务就会完美接续运作。
|
|
199
|
+
- **长效目标系统 (Persistent goals)** —— 允许使用 `/goal` 指令，为指定的会话设定出伴有明确 Token 预算的长效终止目标。任务支持智能暂停/恢复，只有当 Agent 靠自行审计判定达到目标要求后，它才会结束自身当前进程。
|
|
200
|
+
|
|
201
|
+
### 模型层
|
|
202
|
+
|
|
203
|
+
- **全面涵盖前沿顶流、国产之光与各类代理** —— 囊括 Claude 家族系列、强大的 GPT-5 / Codex 以及 Gemini；国内优秀梯队的 DeepSeek、豆包 (Doubao)、MiMo 与 MiniMax；同时原生兼容 OpenRouter 和任意支持 OpenAI 通用接口格式的第三方代理服务。
|
|
204
|
+
- **Providers & Profiles 凭据专属保险箱** —— 构建了高标准隔离的数据保护模型，API 凭据会被单独加密存放在 `~/.pikiclaw/setting.json` 专属区域。你能在只读的 models.dev 目录进行便捷浏览、调用最真实的 API 探针来严谨验证密钥的有效性，最终再把这份 Profile 与指定的任意 Agent 相绑定，从而实现运行阶段环境变量参数的自动隔离注入。
|
|
205
|
+
- **极度自由的会话级配置选取** —— 无论是模型本体还是针对特定高难度任务的推理强度，你都能在友好的 Dashboard 界面中，或者直接发送指令 `/models` 与 `/mode` 来即时动态切选。
|
|
206
|
+
- **Agent 级别底层强制注入** —— 核心流函数 `resolveAgentInjection(agentId)` 在启动的最初阶段就会将对应的环境变量强行覆盖进去。这意味着，你竟然可以直接指令 Claude Code，让它全程跑在超高性价比的 DeepSeek 或是豆包核心大模型上，并且全程无需去改动其原本上游客户端里任何一行深层配置代码。
|
|
207
|
+
|
|
208
|
+
### 工具层
|
|
209
|
+
|
|
210
|
+
- **强大的技能系统 (Skills)** —— 这个系统让每一个工程专属技能被稳稳地存放在 `.pikiclaw/skills/*/SKILL.md` 内（同时也全面向下兼容标准的 `.claude/commands/*.md` 描述格式）。支持快速指定从 GitHub 的公开仓库（`owner/repo`）中实现极速的一键远程拉取并安装；或者去随便逛逛我们收录整理的精选套件包（比如备受好评的 Anthropic 官方包、或是好用的 Vercel Agent Skills 包等）。平时直接发个 `/skills` 探查当前载入的所有技能，挑准目标直接用 `/sk_<name>` 便可秒速触发。
|
|
211
|
+
- **最广泛主流的 MCP 服务器加持** —— 可以直接浏览接入 [MCP Registry](https://registry.modelcontextprotocol.io) 全球库或者自由手工增加本地 stdio 和网端 HTTP 服务；框架严格支持实机硬核握手健康侦测机制与 OAuth 2.1 高级动态客户端安全注册，且能精细拆分控制启用哪些作用域范围。目前精选优化的目录已毫无压力地涵盖 GitHub、Atlassian、Notion、Linear、Sentry、Cloudflare、Slack、飞书/Lark、Stripe、Hugging Face、Gamma、Brave Search、Perplexity、本地系统深度文件探测、SQLite 甚至专业的 PostgreSQL。此外，系统更逆天地内置附赠了两个重磅级的强力 Computer-use 级别核心服务（一个是基于大名鼎鼎的 Playwright 来暴躁驱动底层 Chrome 浏览器的 `pikiclaw-browser`；另一个则是依托极客向 Peekaboo 纯正血统，操控整个底层 macOS GUI 交互视窗的超级 `peekaboo` 工具）。
|
|
212
|
+
- **无缝衔接各类流行 CLI 神器** —— 底层逻辑强悍地支持自动探测各类版本兼容性并精准校验出授权登入状态。特别是遇到基于浏览器鉴权登录判定的 CLI，我们底层支持 OAuth-web 授权无缝接力。最后统统由 Agent 最原生的调用接口无缝唤起执行操作。
|
|
213
|
+
- **全局会话级的 MCP 底层桥接** —— `im_list_files`、`im_send_file`、`im_ask_user` 这些基建指令，再叠加前述的内置浏览器与 macOS 桌面自动化控制工具包（只要一旦开启安全开关），统统都会被全面自动注入进你的每一场会话里。
|
|
214
|
+
- **双域极简权限合并机制** —— 所有工具作用范围授权，永远只需遵循这条策略：`全局 (global) < 当前工作区 (workspace) < 内建 (built-in)`。底层引擎每次都能自动执行合并，并丝滑生效进后续发起的对话之中。
|
|
215
|
+
|
|
216
|
+
<p align="center"><img src="docs/promo-dashboard-extensions-add.png" alt="添加 MCP server" width="780"></p>
|
|
217
|
+
|
|
218
|
+
### 运行环境与开发者体验 (Runtime & DX)
|
|
219
|
+
|
|
220
|
+
- **独享会话级项目工作区** —— 每开启一次新的交锋会话，底层引擎都会为它开辟出单独专属的实体文件隔离目录，附件直接落在那里。
|
|
221
|
+
- **多轮会话回溯管控** —— 随便怎么恢复、切换，还配上了贴心的语义会话分类体系（快速分为解答、提案、实现，阻塞等清晰状态标识归类）。
|
|
222
|
+
- **基建工具流自注入** —— 强悍的 `im_list_files`、`im_send_file`、以及 `im_ask_user`，加上目标追踪管理工具等，会在启动前夕自动挂载。
|
|
223
|
+
- **Computer-use (浏览器引擎层)** —— 系统底层内置了 `pikiclaw-browser` MCP。这是二次封装了 `@playwright/mcp` 实现的，使其拥有进程级 Supervisor 监管机制，且达成了跨任务进程共享独立 Chrome 配置。只需要登录认证一次常用网站；在未来的任何任务里，这个工具将直接一键继承数据免签直连！
|
|
224
|
+
- **Computer-use (macOS 桌面控制层)** —— 当你在扩展面板启用 `peekaboo` MCP 并在系统设置授予终端“辅助功能”与“屏幕录制”权限后（仅限 macOS）；你即可借助 [Peekaboo](https://peekaboo.sh/) 框架的加持瞬间获得暴露在外的各种工具：视力 (`see`)；精准点击 (`click`)；虚空打字输入 (`type`)；操作滚轮 (`scroll`)；以及操作全系统窗口 (`window`)；主菜单 (`menu`)；程序生命周期 (`app`)；甚至是 Dock (`dock`) 等这一整套系统控制工具集。
|
|
225
|
+
- **长效任务坚固防线** —— 核心内置了防休眠系统、看门狗守护模块、异常自动重启涅槃机制、守护进程模式；还有渠道 Supervisor 督军服务。这豪华阵容保证你哪怕挂机跑极其漫长的任务，也能极度稳如磐石！
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 到底有什么不同？
|
|
230
|
+
|
|
231
|
+
| | pikiclaw | IDE 级智能助手<br>(Cursor / Windsurf / Aider) | 云端 Agent<br>(Devin / 网页版 Claude) | 单体 IM 机器人 |
|
|
232
|
+
|---|---|---|---|---|
|
|
233
|
+
| **操作终端** | 7 大 IM + Web + 持续扩展 | 仅限 IDE 内部 | 局限在专属网页端 | 死绑在单个 IM 内的单个 Bot |
|
|
234
|
+
| **Agent 运行地** | 完全在你自己的本地机器上 | 你的本地机器 | 厂商分配的云端沙盒里 | 往往在厂商服务器端 |
|
|
235
|
+
| **Agent 的选择** | Claude Code · Codex · Gemini · Hermes (ACP) · …（任你选） | 深度绑定没得选 | 单一 | 单一 |
|
|
236
|
+
| **底层模型抉择** | 国外前沿大模型 + 国产全系 + 任何兼容 OpenAI 接口的模型 | 平台控制 | 厂商绑定 | 单一无脑没得换 |
|
|
237
|
+
| **并发能力** | **N 个 Agent × N 个窗口 × N 个工作区** | 每个 IDE 窗口只能同时运行一个 | 串行排队 | 单一线程 |
|
|
238
|
+
| **文件与工具掌控** | 你主机上的所有本地文件、MCP 资源库、以及本地 CLI 系统 | 本地文件 | 沙盒受限环境 | 极度受限 |
|
|
239
|
+
| **接入新终端渠道** | 随便写个 `Channel` 基础实现类就能打通 | 无法实现 | 无法实现 | 需要 Fork 整个项目 |
|
|
240
|
+
| **接入新 Agent** | 实现一个简单的 `AgentDriver` 接口（CLI 或 ACP 均可）极速完成 | 无法实现 | 无法实现 | 需要 Fork 整个项目 |
|
|
241
|
+
| **能否自举开发** | **能！完全是由它自己一砖一瓦开发出来的！** | 不能 | 不能 | 不能 |
|
|
242
|
+
|
|
243
|
+
这个表格揭示了最核心的形态差异：**你不需要离开习惯的工作环境，你可以自由选择用哪颗「大脑」，你甚至可以并发操作一整支 AI 军队；而这个编排器本身，就是我们打造它的最佳工具。**
|
|
244
|
+
|
|
245
|
+
---
|
|
246
|
+
|
|
247
|
+
## 常用指令
|
|
248
|
+
|
|
249
|
+
| 指令 | 描述 |
|
|
250
|
+
|---|---|
|
|
251
|
+
| `/start` | 查看入口信息、当前 Agent 及工作目录 |
|
|
252
|
+
| `/sessions` | 查看、切换或新建会话 |
|
|
253
|
+
| `/agents` | 切换 Agent（Claude · Codex · Gemini · Hermes） |
|
|
254
|
+
| `/models` | 查看并切换当前会话的模型及推理强度 |
|
|
255
|
+
| `/mode` | 快捷切换计划模式 (推理强度) |
|
|
256
|
+
| `/switch` | 浏览并快速切换工作目录 |
|
|
257
|
+
| `/workspaces` | 从 Dashboard 收藏的快捷列表中选择工作区 |
|
|
258
|
+
| `/goal` | 设置或检视会话的长效目标（达成后 Agent 自动终止） |
|
|
259
|
+
| `/stop` | 强制停止当前会话 |
|
|
260
|
+
| `/status` | 检查运行状态、Token 消耗、资源使用及会话摘要 |
|
|
261
|
+
| `/host` | 监控主机的 CPU / 内存 / 磁盘 / 电池状态 |
|
|
262
|
+
| `/skills` | 浏览当前项目可用的所有技能 (Skills) |
|
|
263
|
+
| `/ext` | 快速查看扩展状态 |
|
|
264
|
+
| `/restart` | 重启并重新加载 Bot 服务 |
|
|
265
|
+
| `/sk_<name>` | 快速触发某个指定的项目技能 |
|
|
266
|
+
|
|
267
|
+
*注：不带斜杠的纯文本将作为普通消息直接发送给当前的 Agent。*
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## 配置管理
|
|
272
|
+
|
|
273
|
+
- 核心持久化配置文件：`~/.pikiclaw/setting.json` —— 负责存储渠道、Agent、Providers/Profiles、工作区历史及 MCP 扩展等信息。
|
|
274
|
+
- Dashboard 是主要的配置入口；交互式的终端向导 (`--setup`) 与体检脚本 (`--doctor`) 主要为无 UI (headless) 环境准备。
|
|
275
|
+
- 全局 MCP 扩展配置存放于 `setting.json` 的 `extensions.mcp` 字段下。
|
|
276
|
+
- 工作区 MCP 扩展：遵循标准约定，存放于项目根目录的 `.mcp.json` 中。
|
|
277
|
+
- 项目专属技能：统一保存在 `.pikiclaw/skills/*/SKILL.md` 中（同时也兼容和加载 `.claude/commands/*.md` 格式）。
|
|
278
|
+
|
|
279
|
+
**Computer-use 的权限开关**需要在扩展面板独立控制：
|
|
280
|
+
|
|
281
|
+
- `browserEnabled` —— 开启后启用托管 Chrome（Playwright）。当 Agent 首次调用 Chrome 时，pikiclaw 会在 `~/.pikiclaw` 下生成专属配置文件，供后续会话跨任务复用。只需登录一次常用站点，今后即可免扫码直连。
|
|
282
|
+
- `peekabooEnabled` —— 开启后启用 macOS 桌面控制（Peekaboo）。该功能仅支持 macOS，开启后 pikiclaw 会拉起 `@steipete/peekaboo` 的 `peekaboo-mcp` 进程并挂载相关工具。*开启前，请务必前往 macOS 的「系统设置 → 隐私与安全性」，为启动 pikiclaw 的终端授予**辅助功能**和**屏幕录制**权限。*
|
|
283
|
+
|
|
284
|
+
---
|
|
285
|
+
|
|
286
|
+
## 产品路线图 (Roadmap)
|
|
287
|
+
|
|
288
|
+
我们已交付：Hermes 驱动支持 · ACP (Agent Client Protocol) 协议底层集成 · Provider/Profile 模型保险箱机制 · 七大 IM 渠道打通 · Computer-use 的落地（Playwright 浏览器托管 + Peekaboo macOS 桌面托管）。
|
|
289
|
+
|
|
290
|
+
- **接入更多 ACP Agent** —— 确保任何新的兼容 ACP 协议的 Agent 都能免代码零配置顺滑接入。
|
|
291
|
+
- **拓展终端生态** —— 将支持 WhatsApp、独立的移动端 App 以及语音交互模块。
|
|
292
|
+
- **深化模型层包装** —— 构建基于任意模型的通用 Agent Wrapper，以便无缝驱动更多优秀的国产模型。
|
|
293
|
+
- **完善工具生态** —— 推出官方推荐的 MCP 插件合集、Skill 模版库及社区应用市场。
|
|
294
|
+
- **全平台的 Computer-use** —— 在已有的 macOS Peekaboo 驱动之外，加入适配 Windows / Linux 操作系统的桌面控制支持。
|
|
295
|
+
|
|
296
|
+
想了解协议层的下一步动作，请参阅 [ACP 迁移计划](docs/acp-migration.md)。
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## 本地开发
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
git clone https://github.com/xiaotonng/pikiclaw.git
|
|
304
|
+
cd pikiclaw
|
|
305
|
+
npm install
|
|
306
|
+
npm run build
|
|
307
|
+
npm test
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
npm run dev # 启动本地开发服务（--no-daemon，实时日志输出到 ~/.pikiclaw/dev/dev.log）
|
|
312
|
+
npm run build # 生产环境编译（Dashboard 构建 + tsc）
|
|
313
|
+
npm test # 运行 Vitest 测试套件
|
|
314
|
+
npx pikiclaw@latest --doctor # 检测本机环境健康度
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
想要深度了解架构与集成细节，请参阅：[ARCHITECTURE.md](ARCHITECTURE.md) · [INTEGRATION.md](INTEGRATION.md) · [TESTING.md](TESTING.md)。
|
|
318
|
+
|
|
319
|
+
---
|
|
320
|
+
|
|
321
|
+
## 参与贡献
|
|
322
|
+
|
|
323
|
+
这个项目架构中的每一个分层，生来就是为了被**扩展**的。接入一个新终端、编写一个新 Agent、打造一款模型 Wrapper 或是增加实用的 MCP 工具 —— 这些全都是一等公民级别的贡献。
|
|
324
|
+
|
|
325
|
+
- 请先阅读 **[贡献指南](CONTRIBUTING.md)** 开始你的第一步。
|
|
326
|
+
- 欢迎关注贴有 [`good first issue`](https://github.com/xiaotonng/pikiclaw/labels/good%20first%20issue) 和 [`help wanted`](https://github.com/xiaotonng/pikiclaw/labels/help%20wanted) 标签的任务。
|
|
327
|
+
- 如果打算进行较大幅度的修改，请先提交 Issue 以便大家确认技术方案。
|
|
328
|
+
|
|
329
|
+
| 模块位置 | 你能拓展什么 |
|
|
330
|
+
|---|---|
|
|
331
|
+
| `src/agent/driver.ts`, `src/agent/drivers/*.ts`, `src/agent/acp-client.ts` | 增加一个新的 Agent Driver（基于 CLI 或是 ACP 协议） |
|
|
332
|
+
| `src/channels/base.ts`, `src/channels/*/` | 对接一个新的终端或 IM 渠道 |
|
|
333
|
+
| `src/model/`, `src/model/injector.ts` | 新增模型提供商，或者定制 Agent 环境的注入规则 |
|
|
334
|
+
| `src/dashboard/routes/*.ts` | 扩充 Dashboard 后端的 API 接口 |
|
|
335
|
+
| `src/agent/mcp/tools/*.ts`, `src/agent/mcp/bridge.ts` | 添加供单个会话专用的 MCP 工具 |
|
|
336
|
+
| `src/catalog/*.ts` | 向我们推荐优秀的 MCP Server、CLI 实用工具或优质技能仓库 |
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Star 历史趋势
|
|
341
|
+
|
|
342
|
+
<a href="https://www.star-history.com/#xiaotonng/pikiclaw&Date">
|
|
343
|
+
<img src="https://api.star-history.com/svg?repos=xiaotonng/pikiclaw&type=Date" alt="Star 历史" width="640">
|
|
344
|
+
</a>
|
|
345
|
+
|
|
346
|
+
---
|
|
347
|
+
|
|
348
|
+
## 许可证
|
|
349
|
+
|
|
350
|
+
[MIT](LICENSE) —— 坚持开放构建。尽情使用、Fork 它，或者插入你自己开发的任意图层吧！
|
package/dist/agent/mcp/bridge.js
CHANGED
|
@@ -82,33 +82,49 @@ function boolFromConfigEnv(configValue, envValue, fallback) {
|
|
|
82
82
|
}
|
|
83
83
|
export function resolveGuiIntegrationConfig(config = loadUserConfig(), env = process.env) {
|
|
84
84
|
const browserEnabled = boolFromConfigEnv(typeof config.browserEnabled === 'boolean' ? config.browserEnabled : config.browserUseProfile, env.PIKICLAW_BROWSER_ENABLED ?? env.PIKICLAW_BROWSER_USE_PROFILE, false);
|
|
85
|
+
const peekabooEnabled = boolFromConfigEnv(config.peekabooEnabled, env.PIKICLAW_PEEKABOO_ENABLED, false);
|
|
85
86
|
return {
|
|
86
87
|
browserEnabled,
|
|
87
88
|
browserProfileDir: getManagedBrowserProfileDir(),
|
|
88
89
|
browserHeadless: boolFromConfigEnv(config.browserHeadless, env.PIKICLAW_BROWSER_HEADLESS, false),
|
|
90
|
+
peekabooEnabled,
|
|
89
91
|
};
|
|
90
92
|
}
|
|
91
93
|
export function buildSupplementalMcpServers(gui = resolveGuiIntegrationConfig(), endpoints = {}) {
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
94
|
+
const servers = [];
|
|
95
|
+
if (gui.browserEnabled) {
|
|
96
|
+
const profileDir = gui.browserProfileDir || getManagedBrowserProfileDir();
|
|
97
|
+
const cdpEndpoint = (endpoints.cdpEndpoint || '').trim() || null;
|
|
98
|
+
const browserServer = resolveManagedBrowserMcpCommand(profileDir, {
|
|
99
|
+
headless: gui.browserHeadless,
|
|
100
|
+
cdpEndpoint,
|
|
101
|
+
});
|
|
102
|
+
servers.push({
|
|
101
103
|
name: 'pikiclaw-browser',
|
|
102
104
|
command: browserServer.command,
|
|
103
105
|
args: browserServer.args,
|
|
104
|
-
}
|
|
106
|
+
});
|
|
107
|
+
}
|
|
108
|
+
if (gui.peekabooEnabled && process.platform === 'darwin') {
|
|
109
|
+
// Peekaboo — native macOS GUI automation via Accessibility + ScreenCaptureKit.
|
|
110
|
+
// Run the dedicated MCP bin from the multi-bin @steipete/peekaboo package.
|
|
111
|
+
servers.push({
|
|
112
|
+
name: 'peekaboo',
|
|
113
|
+
command: 'npx',
|
|
114
|
+
args: ['-y', '-p', '@steipete/peekaboo', 'peekaboo-mcp'],
|
|
115
|
+
});
|
|
116
|
+
}
|
|
117
|
+
return servers;
|
|
105
118
|
}
|
|
106
119
|
export function buildGuiSetupHints(gui = resolveGuiIntegrationConfig()) {
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
120
|
+
const hints = [];
|
|
121
|
+
if (gui.browserEnabled) {
|
|
122
|
+
hints.push(`managed browser profile mode enabled; runtime sessions reuse ${gui.browserProfileDir || getManagedBrowserProfileDir()}; configured MCP browser mode=${gui.browserHeadless ? 'headless' : 'headed'}. This mode keeps automation isolated from your everyday browser. If the managed browser is already open, pikiclaw will try to attach to it first. When using browser_tabs, use action="new" to open a tab, not "create".`);
|
|
123
|
+
}
|
|
124
|
+
if (gui.peekabooEnabled && process.platform === 'darwin') {
|
|
125
|
+
hints.push('Peekaboo enabled — native macOS GUI tools (see / click / type / scroll / window / menu / app / dock) via Accessibility + ScreenCaptureKit. Prefer element-ID interactions (call `see` first) over raw coordinates.');
|
|
126
|
+
}
|
|
127
|
+
return hints;
|
|
112
128
|
}
|
|
113
129
|
function buildClaudeMcpConfig(servers) {
|
|
114
130
|
return {
|
|
@@ -240,10 +256,10 @@ export async function startMcpBridge(opts) {
|
|
|
240
256
|
// supervisor singleton in `browser-supervisor.ts` caches the result so
|
|
241
257
|
// concurrent streams reuse the same long-lived Chrome instance; if the
|
|
242
258
|
// managed Chrome is unreachable we fall back to upstream-managed launch.
|
|
259
|
+
for (const hint of buildGuiSetupHints(gui))
|
|
260
|
+
opts.onLog?.(hint);
|
|
243
261
|
let browserCdpEndpoint = null;
|
|
244
262
|
if (gui.browserEnabled) {
|
|
245
|
-
for (const hint of buildGuiSetupHints(gui))
|
|
246
|
-
opts.onLog?.(hint);
|
|
247
263
|
try {
|
|
248
264
|
const snapshot = await ensureManagedBrowser({ headless: gui.browserHeadless });
|
|
249
265
|
browserCdpEndpoint = snapshot.cdpEndpoint;
|
|
@@ -240,12 +240,14 @@ export function getCatalogItems(opts = {}) {
|
|
|
240
240
|
};
|
|
241
241
|
const items = [];
|
|
242
242
|
// Builtin items derive their installed/state from a top-level config flag
|
|
243
|
-
// rather than `extensions.mcp`.
|
|
244
|
-
//
|
|
243
|
+
// rather than `extensions.mcp`. Each catalogId maps to one flag — extend the
|
|
244
|
+
// switch when adding a new builtin.
|
|
245
245
|
const userConfig = loadUserConfig();
|
|
246
246
|
const builtinInstalled = (catalogId) => {
|
|
247
247
|
if (catalogId === 'pikiclaw-browser')
|
|
248
248
|
return userConfig.browserEnabled === true;
|
|
249
|
+
if (catalogId === 'peekaboo')
|
|
250
|
+
return userConfig.peekabooEnabled === true;
|
|
249
251
|
return false;
|
|
250
252
|
};
|
|
251
253
|
// 1. Registry entries — preserve registry ordering.
|
|
@@ -42,6 +42,19 @@ export const MCP_SERVERS = [
|
|
|
42
42
|
homepage: 'https://github.com/microsoft/playwright-mcp',
|
|
43
43
|
isBuiltin: true,
|
|
44
44
|
},
|
|
45
|
+
{
|
|
46
|
+
id: 'peekaboo',
|
|
47
|
+
name: 'Peekaboo',
|
|
48
|
+
description: 'Native macOS GUI control via Accessibility API + ScreenCaptureKit (click, type, scroll, windows, menus, Dock). Requires Screen Recording + Accessibility permissions. macOS only.',
|
|
49
|
+
descriptionZh: '通过 macOS Accessibility 与 ScreenCaptureKit 实现原生 GUI 控制（点击、输入、滚动、窗口、菜单、Dock）。需要"屏幕录制"与"辅助功能"两项系统权限，仅支持 macOS。',
|
|
50
|
+
category: 'utility',
|
|
51
|
+
recommendedScope: 'global',
|
|
52
|
+
transport: { type: 'stdio', command: 'npx', args: ['-y', '-p', '@steipete/peekaboo', 'peekaboo-mcp'] },
|
|
53
|
+
auth: { type: 'none' },
|
|
54
|
+
iconSlug: 'apple',
|
|
55
|
+
homepage: 'https://peekaboo.sh/',
|
|
56
|
+
isBuiltin: true,
|
|
57
|
+
},
|
|
45
58
|
// ── Local filesystems / databases (workspace scope) ────────────────────────
|
|
46
59
|
{
|
|
47
60
|
id: 'filesystem',
|
|
@@ -529,6 +529,10 @@ export class FeishuBot extends Bot {
|
|
|
529
529
|
const session = this.resolveIncomingSession(ctx, text, msg.files);
|
|
530
530
|
const cs = this.chat(ctx.chatId);
|
|
531
531
|
this.applySessionSelection(cs, session);
|
|
532
|
+
// Tie the user's own message to its session so a future Feishu reply to it
|
|
533
|
+
// (their own message, or a quote-chain rooted at it) resolves back to this
|
|
534
|
+
// session instead of falling through to the chat's current default.
|
|
535
|
+
this.registerSessionMessage(ctx.chatId, ctx.messageId, session);
|
|
532
536
|
// File-only message: stage files
|
|
533
537
|
if (!text && msg.files.length) {
|
|
534
538
|
const hadPendingWork = this.sessionHasPendingWork(session);
|
|
@@ -639,7 +643,7 @@ export class FeishuBot extends Bot {
|
|
|
639
643
|
keyboard: runningKeyboard,
|
|
640
644
|
model,
|
|
641
645
|
effort,
|
|
642
|
-
log: (message) => this.debug(message),
|
|
646
|
+
log: (message) => this.debug(`[live-preview task=${taskId} placeholder=${placeholderId}] ${message}`),
|
|
643
647
|
});
|
|
644
648
|
livePreview.start();
|
|
645
649
|
}
|
|
@@ -665,6 +669,7 @@ export class FeishuBot extends Bot {
|
|
|
665
669
|
this.debug(`[handleMessage] end chat=${ctx.chatId} agent=${session.agent} ok=${result.ok} session=${result.sessionId || session.sessionId || '(new)'} ` +
|
|
666
670
|
`elapsed=${result.elapsedS.toFixed(1)}s tokens=in:${fmtTokens(result.inputTokens)}/out:${fmtTokens(result.outputTokens)} ` +
|
|
667
671
|
`tools=${formatToolLog(result.activity)}`);
|
|
672
|
+
await this.notifyBackgroundCompletion(ctx, session, taskId, { result });
|
|
668
673
|
}
|
|
669
674
|
catch (e) {
|
|
670
675
|
if (task?.freezePreviewOnAbort && abortController.signal.aborted) {
|
|
@@ -688,6 +693,7 @@ export class FeishuBot extends Bot {
|
|
|
688
693
|
else {
|
|
689
694
|
await this.channel.send(ctx.chatId, errorText).catch(() => null);
|
|
690
695
|
}
|
|
696
|
+
await this.notifyBackgroundCompletion(ctx, session, taskId, { errorMessage: msgText, elapsedMs: Date.now() - start });
|
|
691
697
|
}
|
|
692
698
|
finally {
|
|
693
699
|
livePreview?.dispose();
|
|
@@ -699,6 +705,53 @@ export class FeishuBot extends Bot {
|
|
|
699
705
|
this.finishTask(taskId);
|
|
700
706
|
});
|
|
701
707
|
}
|
|
708
|
+
/**
|
|
709
|
+
* When a task finishes (or errors) in a session that is no longer the chat's
|
|
710
|
+
* current active session, the user has likely moved on and won't see the
|
|
711
|
+
* placeholder card being edited in place. Surface a small fresh notice card
|
|
712
|
+
* so the completion bubbles to the bottom of the chat. Registered to the
|
|
713
|
+
* task's session so a reply to it resumes the right thread.
|
|
714
|
+
*/
|
|
715
|
+
async notifyBackgroundCompletion(ctx, session, taskId, payload) {
|
|
716
|
+
const currentCs = this.chat(ctx.chatId);
|
|
717
|
+
if (currentCs.activeSessionKey === session.key)
|
|
718
|
+
return;
|
|
719
|
+
try {
|
|
720
|
+
const shortId = (session.sessionId || '').slice(0, 8) || '(new)';
|
|
721
|
+
let header;
|
|
722
|
+
let detail = '';
|
|
723
|
+
if (payload.result) {
|
|
724
|
+
const r = payload.result;
|
|
725
|
+
if (r.ok && !r.incomplete)
|
|
726
|
+
header = '✓ Background task done';
|
|
727
|
+
else if (r.incomplete)
|
|
728
|
+
header = '⊘ Background task interrupted';
|
|
729
|
+
else
|
|
730
|
+
header = '⚠ Background task failed';
|
|
731
|
+
const elapsed = `${r.elapsedS.toFixed(1)}s`;
|
|
732
|
+
detail = `elapsed ${elapsed} · in ${fmtTokens(r.inputTokens)} / out ${fmtTokens(r.outputTokens)}`;
|
|
733
|
+
}
|
|
734
|
+
else {
|
|
735
|
+
header = '⚠ Background task failed';
|
|
736
|
+
const elapsed = payload.elapsedMs != null ? `${(payload.elapsedMs / 1000).toFixed(1)}s` : '';
|
|
737
|
+
const errSnippet = (payload.errorMessage || 'Unknown error').slice(0, 160);
|
|
738
|
+
detail = [elapsed && `elapsed ${elapsed}`, `error: ${errSnippet}`].filter(Boolean).join(' · ');
|
|
739
|
+
}
|
|
740
|
+
const lines = [
|
|
741
|
+
`${header} · \`${session.agent}:${shortId}\``,
|
|
742
|
+
detail,
|
|
743
|
+
'_Reply this card to continue this session._',
|
|
744
|
+
].filter(Boolean);
|
|
745
|
+
const sent = await this.channel.send(ctx.chatId, lines.join('\n'));
|
|
746
|
+
if (sent) {
|
|
747
|
+
this.registerSessionMessage(ctx.chatId, sent, session);
|
|
748
|
+
this.debug(`[bg-completion] surfaced task=${taskId} session=${session.key} chat=${ctx.chatId} msg=${sent}`);
|
|
749
|
+
}
|
|
750
|
+
}
|
|
751
|
+
catch (e) {
|
|
752
|
+
this.debug(`[bg-completion] ping failed task=${taskId} chat=${ctx.chatId}: ${e?.message || e}`);
|
|
753
|
+
}
|
|
754
|
+
}
|
|
702
755
|
async freezeSteerHandoffPreview(ctx, placeholderId, livePreview) {
|
|
703
756
|
if (!placeholderId)
|
|
704
757
|
return [];
|
|
@@ -20,15 +20,18 @@ import path from 'node:path';
|
|
|
20
20
|
import fs from 'node:fs';
|
|
21
21
|
/**
|
|
22
22
|
* Builtin catalog entries don't live in `extensions.mcp` — they're toggled by
|
|
23
|
-
* a top-level config flag.
|
|
24
|
-
*
|
|
25
|
-
* remove routing so adding more builtins later is a one-line change.
|
|
23
|
+
* a top-level config flag. Each catalogId maps to one flag; add a branch when
|
|
24
|
+
* registering a new builtin.
|
|
26
25
|
*/
|
|
27
26
|
function setBuiltinEnabled(catalogId, enabled) {
|
|
28
27
|
if (catalogId === 'pikiclaw-browser') {
|
|
29
28
|
saveUserConfig({ ...loadUserConfig(), browserEnabled: enabled });
|
|
30
29
|
return true;
|
|
31
30
|
}
|
|
31
|
+
if (catalogId === 'peekaboo') {
|
|
32
|
+
saveUserConfig({ ...loadUserConfig(), peekabooEnabled: enabled });
|
|
33
|
+
return true;
|
|
34
|
+
}
|
|
32
35
|
return false;
|
|
33
36
|
}
|
|
34
37
|
const app = new Hono();
|
package/package.json
CHANGED