agent-space-manager 0.0.0-stage → 1.0.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/CHANGELOG.md +58 -0
- package/LICENSE +22 -0
- package/README.md +157 -2
- package/README.zh-CN.md +158 -0
- package/adapters.mjs +1228 -0
- package/agents.mjs +653 -0
- package/index.mjs +292 -0
- package/manager.mjs +4428 -0
- package/package.json +71 -4
- package/page/app.js +4207 -0
- package/page/icon.svg +9 -0
- package/page/index.html +467 -0
- package/page/style.css +1032 -0
- package/server.mjs +1165 -0
- package/smart-tools.middleware.js +188 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to the Agent Space Manager plugin and its integrated components will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## [1.0.1] - 2026-11-12
|
|
10
|
+
|
|
11
|
+
### Changed
|
|
12
|
+
- **Copy Prompt Duplicate Naming Rule (`page/app.js`)**: Updated the Copy Prompt specification and Rule Invariant 1 to disambiguate coincidental duplicate component names by appending `-1`, `-2`, etc. sequentially (`<name>-1`, `<name>-2`).
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
## [1.0.0] - 2026-11-12
|
|
17
|
+
|
|
18
|
+
### Added
|
|
19
|
+
- **Unified Single-Folder Component Management**: Centralized management for all AI component types (**Plugins, MCP Servers, Hooks, Skills, Subagents, and Rules**) in a single Components Storage Path (`~/AI-Agent-Space` or custom directory), with zero file duplication into agent default config folders.
|
|
20
|
+
- **Universal Multi-Agent Bridging (13 Built-In Profiles + Custom)**: Native format adaptation and OS junction/symlink linking for Antigravity, Claude Code, Codex CLI, OpenCode, VS Code / GitHub Copilot, Cursor AI, Windsurf, Gemini CLI, Cline, Roo Code, Kiro, Universal (`~/.agents/skills`), and Custom agents.
|
|
21
|
+
- **Auto-Detection & Per-Component Target Overrides**: Automatic config path discovery via filesystem probes, executables/shortcuts, environment variables, and CLI tools, plus customizable destination paths for Bundles, Skills, Slash Commands, MCPs, Rules, Subagents, and Hooks.
|
|
22
|
+
- **Expandable Discovered Components Registry**: 7-tab category browser (`All`, `Plugins`, `MCPs`, `Hooks`, `Skills`, `Agents`, `Rules`) with live search and 6-type component metrics tiles.
|
|
23
|
+
- **Per-Agent & Per-Project Overrides**: Drag-and-drop IDE/project reordering, project `Clone / Fork`, `.git/info/exclude` protection, `Expand All Files`, live `Rescan Hub` & `Connect` progress modals, and `● Agent Status` workability indicators with slash command (`/`) and `@` mention detection.
|
|
24
|
+
- **Foreign Components Detection & Cleanup**: Scans connected agent default directories for unmanaged components and provides interactive keep/delete cleanup.
|
|
25
|
+
- **Startup Snapshot Fingerprinting & Auto-Reconnect**: SHA-256 canonical storage hashing to detect external changes on startup and automatically re-sync connected agents.
|
|
26
|
+
- **Centralized Weekly Upstream Checking**: Monday startup upstream update checks and automatic pruning of decentralized update scripts (`update_checker.mjs`, `update_check_state.json`).
|
|
27
|
+
- **Smart Middleware Tool Gateway & OmniRoute Integration**: Intent-based tool filtering (`smart-tools.middleware.js`) with configurable tool cap (`10–256`, default `96`), failure diagnostics (`error.log`, `LAST_ERROR.json`, `STATUS.md`), and OmniRoute port `20128` status capsule.
|
|
28
|
+
- **Non-Destructive Ownership & Safety Invariants**: `.asm-owned.json` markers, `~/.agent-space-manager/state/<id>.json` tracking, atomic `.asm-bak` backups, 0-byte/`{}` config sanitization, GUI editor process protection, and WebView2-safe two-step inline confirmations.
|
|
29
|
+
- **Plugin Version Badge & Marketplace Publishing**: Displayed `V1.0.0` badge beside the plugin title and added GitHub Actions workflow (`.github/workflows/publish.yml`) for automated testing and npm marketplace publishing.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
# Prompt Text Changelog
|
|
34
|
+
|
|
35
|
+
This section tracks all revisions to the standardized instructions copied via the **Copy Prompt** button in the Agent Space Manager dashboard.
|
|
36
|
+
|
|
37
|
+
## [V1.0] - 2026-10-31
|
|
38
|
+
|
|
39
|
+
### Features & Invariants
|
|
40
|
+
- **Version Identifier**: Added explicit version tag `[Components Storage Specification & Upstream Rules Prompt V1.0]` at the header of the copied prompt text.
|
|
41
|
+
- **Standard Plugin Directory Structure**: Defined standard directory layout:
|
|
42
|
+
```
|
|
43
|
+
plugins/<plugin-name>/
|
|
44
|
+
├── plugin.json # Required manifest (must contain "upstream" URL)
|
|
45
|
+
├── mcp_config.json # Optional MCP server definitions
|
|
46
|
+
├── hooks.json # Optional hooks definition
|
|
47
|
+
├── skills/ # Optional skills directory
|
|
48
|
+
├── agents/ # Optional subagent definitions
|
|
49
|
+
└── rules/ # Optional rules directory
|
|
50
|
+
```
|
|
51
|
+
- **Mandatory Upstream Source Links**: Enforced that all components record the official upstream source repository or registry URL:
|
|
52
|
+
- `plugin.json`: `"upstream": "https://github.com/<owner>/<repo>"`
|
|
53
|
+
- `SKILL.md`: `upstream: "https://github.com/<owner>/<repo>"` in YAML frontmatter
|
|
54
|
+
- Rules (`*.md`): `upstream: "https://github.com/<owner>/<repo>"` in YAML frontmatter
|
|
55
|
+
- Agents (`*.md`): `upstream: "https://github.com/<owner>/<repo>"` in YAML frontmatter
|
|
56
|
+
- **Centralized Weekly Monday Checking**: Directed the agent to remove and prohibit local, decentralized update checking scripts (`update_checker.mjs`, `update_check_state.json`), relying on Agent Space Manager's centralized Monday startup update cycle.
|
|
57
|
+
- **Persistent Rule Installation**: Instructed the user's AI agent to persist a dedicated rule (`.agents/rules/components-storage-upstream-rule.md` or `.cursor/rules/components-storage-upstream-rule.mdc`) triggered whenever an addendum or edit is performed in the Components Storage Path.
|
|
58
|
+
- **Dashboard UI Display**: Updated the dashboard copy button to display `Copy Prompt (V1.0)`.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Terence Ooi Teng Wei
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
package/README.md
CHANGED
|
@@ -1,3 +1,158 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Smart Middleware & Agent Space Manager
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Universal Multi-IDE & Multi-Agent Component Orchestrator with Dynamic Intent-Based Tool Gateway for [Magpie](https://usemagpie.ai).**
|
|
4
|
+
|
|
5
|
+
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Core Purpose & Design Philosophy
|
|
10
|
+
|
|
11
|
+
Agent Space Manager is a centralized control plane that **universally manages every type of AI component in one single folder**—**Plugins, MCP Servers, Hooks, Skills, Subagents, and Rules**—and lets you **connect any AI coding agent or project repository** so enabled components become immediately usable **without duplicating files into each agent's default configuration directory**.
|
|
12
|
+
|
|
13
|
+
As developers work across multiple AI environments (Antigravity, Claude Code, Codex CLI, OpenCode, VS Code Copilot, Cursor, Windsurf, Gemini CLI, Cline, Roo Code, Kiro), component files normally get copied and fragmented across dozens of agent-specific folders. Agent Space Manager eliminates that duplication:
|
|
14
|
+
|
|
15
|
+
1. **One Unified Storage Folder (Single Source of Truth)**: Store all plugins, MCP configs, hooks, skills, subagent templates, and rules in a single **Components Storage Path** (Hub Root, defaulting to `~/AI-Agent-Space`).
|
|
16
|
+
2. **Zero File Duplication to Agent Default Config**: Connected agents receive **non-destructive OS links** (NTFS directory junctions on Windows, symlinks on macOS/Linux) pointing back to your central storage folder—never full redundant copies of your component repositories. Where a runtime requires native file adaptation (such as Go `os.ReadDir` on Windows for Antigravity, or single-file JSON/TOML/Markdown configs for MCPs and rules), Agent Space Manager materializes lightweight `.asm-owned.json`-tracked wrappers with child junctions and isolated config blocks.
|
|
17
|
+
3. **Toggle & Use Immediately**: Enable or disable any component per connected agent (Global) or per project repository (Override). Enabled components are linked into the agent's native discovery path and become immediately usable via hot-reload; disabled components are cleanly unlinked without touching the original source files.
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Detailed Feature Breakdown
|
|
22
|
+
|
|
23
|
+
### 1. Centralized Components Storage & Universal Discovery
|
|
24
|
+
- **Universal Path Resolution (`Components Storage Path`)**: Point to any directory—whether a full multi-plugin hub (`<hub>/plugins/<name>`), a standalone skills folder, a single plugin directory, or leave blank to use the default Hub (`~/AI-Agent-Space`). Handles quoted paths and trailing slashes automatically.
|
|
25
|
+
- **Expandable Discovered Components Registry**: Click **Expand Components List** to browse every discovered asset across **7 filter tabs** (`All`, `Plugins`, `MCPs`, `Hooks`, `Skills`, `Agents`, `Rules`) with instant keyword search by name, skill, MCP, or file path.
|
|
26
|
+
- **Live Metrics Tiles**: Displays real-time counts for all 6 component types (`Plugins`, `MCPs`, `Hooks`, `Skills`, `Agents`, `Rules`), plus counts of **Connected IDEs** and **Registered Projects**.
|
|
27
|
+
|
|
28
|
+
### 2. Multi-Agent Connection, Auto-Detection & Native Format Adaptation
|
|
29
|
+
Agent Space Manager includes **13 built-in Agent Profiles** (`agents.mjs` & `adapters.mjs`) plus **Custom Agent** support:
|
|
30
|
+
- **Auto-Detect Configuration Link Directory**: Toggleable **Auto-detect** probes the filesystem, executable/shortcut (`.exe` / `.lnk`), environment variables (`$AGENT_TOOLS_ROOT`, `$AI_WORKSPACE_DIR`), and IDE CLI tools (e.g., `opencode debug paths`) to locate each agent's native config directory.
|
|
31
|
+
- **Custom Component Target Path Overrides**: Expand **Component Target Paths** in the Add/Edit IDE modal to customize destination paths per component type:
|
|
32
|
+
- Bundle Path (Antigravity Plugins)
|
|
33
|
+
- Skills Directory
|
|
34
|
+
- Slash Commands Directory (`/` quick actions)
|
|
35
|
+
- MCP Configuration File
|
|
36
|
+
- Rules File or Folder
|
|
37
|
+
- Subagents Directory (`@` mentions)
|
|
38
|
+
- Hooks Configuration File
|
|
39
|
+
- **Cross-Agent Native Format Conversion**: Automatically adapts components to each agent's required schema without manual editing:
|
|
40
|
+
- **MCP Schemas**: Normalizes root keys (`mcpServers` for Claude/Cursor/Windsurf/Gemini/Cline/Roo/Kiro, `servers` for VS Code Copilot, `mcp` with `type: "local" | "remote"` and `environment` for OpenCode, and `[mcp_servers.*]` TOML tables for Codex CLI).
|
|
41
|
+
- **Rule Normalization**: Injects valid YAML frontmatter (`trigger: always_on` for Antigravity Cortex, `.mdc` for Cursor) or isolated delimiter blocks (`<!-- agent-space-manager:start -->` / `# >>> agent-space-manager`) into monolithic rule files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `global_rules.md`).
|
|
42
|
+
- **OpenCode Subagent Schema**: Automatically ensures `mode: subagent` in `.opencode/agents/*.md` frontmatter.
|
|
43
|
+
|
|
44
|
+
### 3. Per-Agent & Per-Project Toggle Matrix & Live Status
|
|
45
|
+
- **Connected IDEs & Project Repositories**:
|
|
46
|
+
- Drag and drop to reorder Connected IDEs (the 1st IDE acts as the default storage fallback) and Project Repositories.
|
|
47
|
+
- **Clone / Fork Project**: Duplicate a project entry's configuration to quickly associate the same repository with another IDE.
|
|
48
|
+
- **Project-Level Overrides**: Register repositories to override global defaults; unregistered projects inherit global IDE settings. Bridged paths inside a repository are automatically added to `<repo>/.git/info/exclude` so links are never committed to Git.
|
|
49
|
+
- **Components & Plugins Matrix**:
|
|
50
|
+
- Toggle **Active** switches per target agent or project, expand individual or all file trees (**Expand All Files**), **Rescan Hub**, and **Connect** to synchronize.
|
|
51
|
+
- **Hub Rescan & Live Linking Progress Modal**: Shows step-by-step progress and per-IDE/per-repository linking status cards.
|
|
52
|
+
- **Workability Status Dots (`● Agent Status`) & Quick Actions**: Verifies on-disk physical readiness (`🟢` workable / `🔴` connection failed) and auto-detects available slash commands (`/`) and `@` mentions for enabled components, backed by a **Status Checking Progress Modal** that can also run in the background.
|
|
53
|
+
|
|
54
|
+
### 4. Foreign Components Detection & Cleanup
|
|
55
|
+
- **Unmanaged Component Scanner**: Detects pre-existing or external ("foreign") components inside a connected agent's default config directory that did not originate from your Components Storage Path (`/api/agent/scan-foreign`).
|
|
56
|
+
- **Interactive Cleanup Modal**: Lists detected foreign components and lets you choose **Cancel / Keep Existing** or **Delete Foreign Components** (`/api/agent/clean-foreign`) to keep connected agents strictly synchronized with your central Hub.
|
|
57
|
+
|
|
58
|
+
### 5. Startup Snapshot Fingerprinting & Auto-Reconnect
|
|
59
|
+
- **SHA-256 Storage Fingerprinting**: Computes a deterministic canonical snapshot of your Components Storage directory (`getComponentsStorageSnapshot`).
|
|
60
|
+
- **Auto-Reconnect on External Changes**: On startup, if files were added, edited, or removed externally in Components Storage, Agent Space Manager automatically re-synchronizes configured agents and displays a dismissible **Auto-reconnected Connected Agents** banner.
|
|
61
|
+
|
|
62
|
+
### 6. Centralized Weekly Upstream Checking & Storage Rules Prompt
|
|
63
|
+
- **Centralized Monday Update Check**: Checks upstream repository links for all stored components once per week on Monday startup (`/api/central-update-check`), and automatically prunes legacy decentralized update scripts (`update_checker.mjs`, `update_check_state.json`).
|
|
64
|
+
- **Copy Prompt (`V1.4`)**: One-click button in the **Storage & Upstream Rules** tile that copies standardized instructions for your AI agent to enforce the Hub layout, record mandatory `upstream` URLs, perform complete plugin removal cleanup, save manifests in strict UTF-8 without BOM, respect one-time rearrangement stability, and preserve the `shared/` cross-agent IPC/handoff directory.
|
|
65
|
+
|
|
66
|
+
### 7. Smart Middleware Tool Gateway & OmniRoute Integration
|
|
67
|
+
- **Dynamic Intent-Based Tool Filtering (`smart-tools.middleware.js`)**:
|
|
68
|
+
- Hooks into Magpie's `onRequest` / `onResponse` lifecycle to prevent LLM context bloat and API `400` errors caused by exceeding model tool limits (e.g., 128 tools in Claude/GPT models).
|
|
69
|
+
- Always preserves core file, shell, and web tools, scores remaining tools against the user's recent messages, and caps the forwarded tool list.
|
|
70
|
+
- **UI Controls**: Toggle **Smart Middleware: Active / Bypassed** in the top bar and adjust **Gateway Tool Optimization** cap (`10–256`, default `96` with one-click **Default** reset).
|
|
71
|
+
- **Failure Diagnostics**: Records middleware errors to `error.log`, `LAST_ERROR.json`, and `STATUS.md`.
|
|
72
|
+
- **OmniRoute AI Gateway Capsule**: Top-bar widget displaying the OmniRoute port (`20128`, click to copy), live health status dot (Green/Red/Gray), and backend lifecycle endpoints (`/api/omniroute/status`, `start`, `stop`, `open`).
|
|
73
|
+
|
|
74
|
+
### 8. Non-Destructive Ownership & Safety Guarantees
|
|
75
|
+
- **Ownership Manifests (`.asm-owned.json` & `~/.agent-space-manager/state/<id>.json`)**: Every link, materialized wrapper, JSON key, and delimited block created by Agent Space Manager is explicitly tracked. Unlinking or disabling only removes ASM-owned items—user-created files, foreign symlinks, and manual MCP servers are never deleted without consent.
|
|
76
|
+
- **Automatic `.asm-bak` Backups**: Before modifying any existing user configuration file (`~/.claude.json`, `~/.codex/config.toml`, `opencode.json`, `mcp.json`, `CLAUDE.md`, `AGENTS.md`), an atomic `.asm-bak` backup is created once and preserved.
|
|
77
|
+
- **Config Sanitization**: Automatically prunes 0-byte JSON files and empty `{}` stubs lacking `"id"` fields to prevent IDE Language Server crash loops.
|
|
78
|
+
- **GUI Editor Process Protection & WebView2 Safety**: Never force-kills running GUI editors (`antigravity.exe`, `cursor.exe`, `windsurf.exe`, `code.exe`, `opencode.exe`), relying on disk hot-reload; uses non-blocking two-step inline confirmations in the UI instead of `window.confirm`/`alert`/`prompt`.
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## Supported IDEs & Multi-Agent Native Adapter Matrix
|
|
83
|
+
|
|
84
|
+
| Agent Profile (`agentType`) | Mode | Skills Target | MCP Servers Target | Rules / Instructions Target | Subagents Target |
|
|
85
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
86
|
+
| **Antigravity (`antigravity`)** | `bundle` | `~/.gemini/config/plugins/<id>` | Inside bundle (`mcp_config.json`) | Inside bundle (`rules/*.md`) | Inside bundle (`agents/*.md`) |
|
|
87
|
+
| **Claude Code (`claude-code`)** | `convert` | `~/.claude/skills/<skill>` | `~/.claude.json` (`mcpServers`) | `~/.claude/CLAUDE.md` (`@path` block) | `~/.claude/agents/*.md` |
|
|
88
|
+
| **Codex CLI (`codex`)** | `convert` | `~/.codex/skills/<skill>` | `~/.codex/config.toml` (`[mcp_servers.*]`) | `~/.codex/AGENTS.md` (managed block) | — |
|
|
89
|
+
| **OpenCode (`opencode`)** | `convert` | `~/.config/opencode/skills/<skill>` | `~/.config/opencode/opencode.json` (`mcp`) | `~/.config/opencode/AGENTS.md` | `~/.config/opencode/agents/*.md` |
|
|
90
|
+
| **VS Code / Copilot (`vscode-copilot`)** | `convert` | `~/.copilot/skills/<skill>` | `<AppData>/Code/User/mcp.json` (`servers`) | `Code/User/prompts/*.instructions.md` | `Code/User/prompts/*.agent.md` |
|
|
91
|
+
| **Cursor AI (`cursor`)** | `convert` | `~/.cursor/skills/<skill>` | `~/.cursor/mcp.json` (`mcpServers`) | Workspace `.cursor/rules` | — |
|
|
92
|
+
| **Windsurf (`windsurf`)** | `convert` | `~/.codeium/windsurf/skills/<skill>` | `~/.codeium/windsurf/mcp_config.json` | `~/.codeium/windsurf/memories/global_rules.md` | — |
|
|
93
|
+
| **Gemini CLI (`gemini-cli`)** | `convert` | `~/.gemini/skills/<skill>` | `~/.gemini/settings.json` (`mcpServers`) | `~/.gemini/GEMINI.md` | — |
|
|
94
|
+
| **Cline (`cline`)** | `convert` | `~/.cline/skills/<skill>` | `globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `~/Documents/Cline/Rules/*.md` | — |
|
|
95
|
+
| **Roo Code (`roo-code`)** | `convert` | `~/.roo/skills/<skill>` | `globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` | `~/.roo/rules/*.md` | — |
|
|
96
|
+
| **Kiro (`kiro`)** | `convert` | `~/.kiro/skills/<skill>` | `~/.kiro/settings/mcp.json` | `~/.kiro/steering/*.md` | — |
|
|
97
|
+
| **Universal (`agents-universal`)** | `convert` | `~/.agents/skills/<skill>` | — | — | — |
|
|
98
|
+
| **Custom (`custom`)** | `convert` | `<custom-dir>/<skill>` | Optional custom overrides | Optional custom overrides | Optional custom overrides |
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Architecture & Standard Storage Layout
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
[ Magpie Host (Bun / WebView2) ]
|
|
106
|
+
│
|
|
107
|
+
├── IPC: globalThis.magpie.api (getPlugins, saveConfig, connectAgent, etc.)
|
|
108
|
+
└── HTTP / REST API: http://127.0.0.1:41789/api/* (server.mjs)
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
[ manager.mjs + adapters.mjs + agents.mjs ]
|
|
112
|
+
├── scanPlugins(hubRoot) & buildCategoriesRegistry()
|
|
113
|
+
├── Smart Middleware (smart-tools.middleware.js: onRequest / onResponse)
|
|
114
|
+
└── connectAgent / syncAllIdes ──> OS Junctions/Symlinks & Native Config Blocks
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Standard Components Storage layout:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
<Components Storage Path>/
|
|
121
|
+
├── plugins/<plugin-name>/
|
|
122
|
+
│ ├── plugin.json # Required manifest (name, version, description, upstream)
|
|
123
|
+
│ ├── mcp_config.json # Optional MCP server definitions
|
|
124
|
+
│ ├── hooks.json # Optional hooks definition
|
|
125
|
+
│ ├── skills/ # Optional skills (<skill-name>/SKILL.md)
|
|
126
|
+
│ ├── agents/ # Optional subagent templates (<agent-name>.md)
|
|
127
|
+
│ └── rules/ # Optional prompt rules (<rule-name>.md)
|
|
128
|
+
├── skills/ # Optional standalone skills
|
|
129
|
+
├── shared/ # Cross-agent IPC, handoff/, _upstream_backups/, shared tooling
|
|
130
|
+
├── hub-config.json # Hub configuration
|
|
131
|
+
├── plugins.json # Discovered plugins index
|
|
132
|
+
└── skills.json # Discovered skills index
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Automated Test Suite
|
|
138
|
+
|
|
139
|
+
Run the sandboxed test suite (runs in an isolated temp `HOME` with `ASM_TEST=1` / `NODE_ENV=test`):
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
npm test
|
|
143
|
+
npm run test:report
|
|
144
|
+
npm run test:universal
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## Support & Sponsorship
|
|
150
|
+
|
|
151
|
+
If you find Agent Space Manager valuable for your workflow, you can support development via:
|
|
152
|
+
- [Wise - Terence Ooi Teng Wei @terenceooit](https://wise.com/pay/me/terenceooit)
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## License
|
|
157
|
+
|
|
158
|
+
MIT © Terence Ooi
|
package/README.zh-CN.md
ADDED
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# 智能中间件与 Agent Space Manager
|
|
2
|
+
|
|
3
|
+
**面向 [Magpie](https://usemagpie.ai) 的通用多 IDE 与多 Agent 组件编排器,内置基于意图的动态工具网关**。
|
|
4
|
+
|
|
5
|
+
[English](README.md) | [简体中文](README.zh-CN.md)
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 核心定位与设计理念
|
|
10
|
+
|
|
11
|
+
Agent Space Manager 是一个集中式控制平面,旨在**在同一个文件夹中统一管理所有类型的 AI 组件**——包括 **Plugins(插件)、MCP Servers(MCP 服务)、Hooks(钩子)、Skills(技能)、Subagents(子智能体)与 Rules(规则)**,并支持**连接任意 AI 编码 Agent 或项目代码仓库**,让已启用的组件**直接被已连接的 Agent 识别与使用,而无需将文件重复复制到各个 Agent 的默认配置目录中**。
|
|
12
|
+
|
|
13
|
+
当开发者同时使用多个 AI 编码环境(Antigravity、Claude Code、Codex CLI、OpenCode、VS Code Copilot、Cursor、Windsurf、Gemini CLI、Cline、Roo Code、Kiro)时,组件文件往往会被重复拷贝并分散在数十个互不兼容的配置目录中。Agent Space Manager 彻底解决了这一痛点:
|
|
14
|
+
|
|
15
|
+
1. **单一文件夹统一管理(唯一事实来源)**:将所有插件、MCP 配置、Hooks、技能、子智能体模板和规则统一存放在一个 **Components Storage Path**(Hub 根目录,默认为 `~/AI-Agent-Space`)。
|
|
16
|
+
2. **零文件重复复制到 Agent 默认配置**:向已连接的 Agent 分发组件时,通过**非破坏性操作系统链接**(Windows 下为 NTFS 目录联接 Junction,macOS/Linux 下为软链接 Symlink)直接指向中央存储目录,绝不将整个组件仓库重复拷贝到各个 Agent 的默认配置文件夹。对于 Windows 上受 Go `os.ReadDir` 机制限制的运行时(如 Antigravity)或要求单文件格式的 Agent(如 MCP JSON/TOML、`CLAUDE.md`、`AGENTS.md`),系统仅生成带有 `.asm-owned.json` 归属标记的轻量目录(子目录仍使用 Junction 联接)或受控分隔块。
|
|
17
|
+
3. **按需启用、即时可用**:支持按单个已连接 Agent(全局)或按具体项目仓库(覆盖)开关组件。启用后即可通过热重载立即在目标 Agent 中使用;停用后即时解除链接,绝不删除中央存储中的源文件。
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 插件功能详解
|
|
22
|
+
|
|
23
|
+
### 1. 集中式组件存储与通用自动发现
|
|
24
|
+
- **通用路径解析 (`Components Storage Path`)**:支持指向完整的多插件 Hub(`<hub>/plugins/<name>`)、独立 Skills 文件夹、单个插件目录,或留空自动使用默认 Hub(`~/AI-Agent-Space`)。自动兼容带引号的路径与末尾斜杠。
|
|
25
|
+
- **可展开的已发现组件注册表 (`Discovered Components Registry`)**:点击 **Expand Components List**,即可按 **7 个分类标签页**(`All`、`Plugins`、`MCPs`、`Hooks`、`Skills`、`Agents`、`Rules`)浏览所有已发现组件,并支持按名称、技能、MCP 或文件路径实时搜索过滤。
|
|
26
|
+
- **实时统计磁贴**:直观展示 6 类组件的数量统计,以及**已连接 IDE(Connected IDEs)**和**已注册项目(Registered Projects)**数量。
|
|
27
|
+
|
|
28
|
+
### 2. 多 Agent 连接、自动探测与原生格式适配
|
|
29
|
+
内置 **13 种主流 Agent 预设配置**(`agents.mjs` & `adapters.mjs`)以及 **Custom 自定义 Agent** 支持:
|
|
30
|
+
- **配置链接目录自动探测 (`Auto-detect`)**:开启后可自动探测文件系统、可执行文件/快捷方式(`.exe` / `.lnk`)、环境变量(`$AGENT_TOOLS_ROOT`、`$AI_WORKSPACE_DIR`)以及 IDE CLI 工具(如 `opencode debug paths`),精准定位目标 Agent 的原生配置路径。
|
|
31
|
+
- **组件目标路径自定义覆盖 (`Component Target Paths`)**:在添加/编辑 IDE 弹窗中可展开自定义各类组件的目标路径:
|
|
32
|
+
- Bundle Path(Antigravity 插件包目录)
|
|
33
|
+
- Skills Directory(技能目录)
|
|
34
|
+
- Slash Commands Directory(`/` 斜杠快捷指令目录)
|
|
35
|
+
- MCP Configuration File(MCP 配置文件)
|
|
36
|
+
- Rules File or Folder(规则文件或目录)
|
|
37
|
+
- Subagents Directory(`@` 提及子智能体目录)
|
|
38
|
+
- Hooks Configuration File(Hooks 配置文件)
|
|
39
|
+
- **跨 Agent 原生格式自动转换**:无需手动修改源文件,自动适配各 Agent 的原生规范:
|
|
40
|
+
- **MCP 架构归一化**:自动适配不同根键与结构(Claude/Cursor/Windsurf/Gemini/Cline/Roo/Kiro 使用 `mcpServers`;VS Code Copilot 使用 `servers`;OpenCode 转换为包含 `type: "local" | "remote"` 与 `environment` 的 `mcp` 结构;Codex CLI 写入 `[mcp_servers.*]` TOML 托管块)。
|
|
41
|
+
- **规则元数据与分隔块**:为 Antigravity Cortex 规则自动补全 `trigger: always_on` YAML Frontmatter,为 Cursor 生成 `.mdc` 规则,为 `CLAUDE.md`、`AGENTS.md`、`GEMINI.md`、`global_rules.md` 写入带边界注释的托管块(`<!-- agent-space-manager:start -->` / `# >>> agent-space-manager`)。
|
|
42
|
+
- **OpenCode 子智能体校验**:自动为 `.opencode/agents/*.md` 补全 `mode: subagent` 字段。
|
|
43
|
+
|
|
44
|
+
### 3. 按 Agent 与项目仓库的细粒度开关矩阵与实时状态
|
|
45
|
+
- **已连接 IDE 与项目仓库管理**:
|
|
46
|
+
- 支持拖拽排序(第 1 个 IDE 作为默认存储回退目标)。
|
|
47
|
+
- **Clone / Fork Project**:一键克隆项目配置,快速将同一代码仓库关联到另一个 IDE。
|
|
48
|
+
- **项目级覆盖与 Git 保护**:为特定仓库单独启用/禁用组件(未注册项目自动继承全局设置)。项目内的托管链接路径会自动写入 `<repo>/.git/info/exclude`,防止被误提交到 Git。
|
|
49
|
+
- **组件矩阵 (`Components & Plugins`)**:
|
|
50
|
+
- 按当前选中的 IDE(全局)或项目仓库切换 **Active** 开关,支持 **Expand All Files** 展开查看组件内所有文件树,支持 **Rescan Hub** 与 **Connect** 一键同步。
|
|
51
|
+
- **Hub 重扫与实时链接进度弹窗**:展示扫描进度条及每个已连接 IDE / 仓库的实时链接状态卡片。
|
|
52
|
+
- **可用性状态指示灯 (`● Agent Status`) 与快捷指令识别**:通过绿色(`🟢` 可用)/ 红色(`🔴` 连接异常)状态点校验磁盘物理就绪状态,并自动识别已启用组件提供的 `/` 斜杠指令与 `@` 提及;支持在后台运行状态检查进度弹窗。
|
|
53
|
+
|
|
54
|
+
### 4. 外部(Foreign)组件检测与清理
|
|
55
|
+
- **外部未托管组件扫描**:自动检测已连接 Agent 默认配置目录中非源自 Components Storage Path 的外部组件(`/api/agent/scan-foreign`)。
|
|
56
|
+
- **交互式清理弹窗**:列出检测到的外部组件,支持选择 **Cancel / Keep Existing(保留现有)** 或 **Delete Foreign Components(删除外部组件)**(`/api/agent/clean-foreign`),确保 Agent 环境与中央 Hub 保持一致。
|
|
57
|
+
|
|
58
|
+
### 5. 启动变更指纹检测与自动重连
|
|
59
|
+
- **SHA-256 存储快照指纹**:对 Components Storage 目录计算确定性规范快照(`getComponentsStorageSnapshot`)。
|
|
60
|
+
- **外部变更自动重连**:启动时若检测到存储目录中存在外部新增、修改或删除,系统将自动重新同步已配置的 Agent,并在顶部展示可关闭的 **Auto-reconnected Connected Agents** 提示横幅。
|
|
61
|
+
|
|
62
|
+
### 6. 集中式每周上游更新检查与规范提示词 (`Copy Prompt V1.4`)
|
|
63
|
+
- **集中式每周一更新检查**:每周一启动 Magpie 时集中检查所有已安装组件的上游仓库更新(`/api/central-update-check`),并自动清理分散的本地更新脚本(`update_checker.mjs`、`update_check_state.json`)。
|
|
64
|
+
- **一键复制规范提示词 (`Copy Prompt (V1.4)`)**:在 **Storage & Upstream Rules** 磁贴中一键复制标准化指令,引导你的 AI 助手严格遵守 Hub 目录规范、记录 `upstream` 上游链接、执行完整的插件卸载清理、使用无 BOM 的 UTF-8 编码、保持一次性目录整理稳定性,并保护 `shared/` 跨 Agent 通信目录。
|
|
65
|
+
|
|
66
|
+
### 7. 智能中间件工具网关与 OmniRoute 集成
|
|
67
|
+
- **基于意图的动态工具过滤 (`smart-tools.middleware.js`)**:
|
|
68
|
+
- 挂载于 Magpie 的 `onRequest` / `onResponse` 生命周期,防止因超出模型工具上限(例如 Claude/GPT 系列的 128 个工具限制)导致上下文溢出或 API `400` 报错。
|
|
69
|
+
- 始终保留核心文件、终端与网络工具,并根据近期对话内容匹配相关领域工具,裁剪其余工具。
|
|
70
|
+
- **UI 控制**:支持顶部栏一键切换 **Smart Middleware: Active / Bypassed**,并在 **Gateway Tool Optimization** 磁贴中自定义工具上限(`10–256`,默认 `96`,支持一键 **Default** 重置)。
|
|
71
|
+
- **故障诊断日志**:异常自动记录至 `error.log`、`LAST_ERROR.json` 与 `STATUS.md`。
|
|
72
|
+
- **OmniRoute AI 网关胶囊**:顶部栏集成 OmniRoute 端口显示(`20128`,点击复制)、健康状态灯(绿/红/灰)及启停控制接口(`/api/omniroute/status`、`start`、`stop`、`open`)。
|
|
73
|
+
|
|
74
|
+
### 8. 非破坏性归属追踪与安全保障机制
|
|
75
|
+
- **归属清单追踪 (`.asm-owned.json` 与 `~/.agent-space-manager/state/<id>.json`)**:精确记录由 Agent Space Manager 创建的每一条链接、包装目录、JSON 键与文本托管块。卸载或停用时仅清理归属项,绝不误删用户自建文件、外部软链接或手动配置的 MCP 服务。
|
|
76
|
+
- **自动 `.asm-bak` 备份**:修改任何现有用户配置文件(`~/.claude.json`、`~/.codex/config.toml`、`opencode.json`、`mcp.json`、`CLAUDE.md`、`AGENTS.md`)前,自动生成 `.asm-bak` 原始备份。
|
|
77
|
+
- **配置目录清理**:自动清除 0 字节 JSON 文件及缺少 `"id"` 字段的空 `{}` 存根,避免 IDE 语言服务器崩溃重启。
|
|
78
|
+
- **GUI 编辑器进程保护与 WebView2 兼容性**:绝不强杀正在运行的 GUI 编辑器(`antigravity.exe`、`cursor.exe`、`windsurf.exe`、`code.exe`、`opencode.exe`),完全依赖磁盘热重载;前端破坏性操作全部采用两步内联确认按钮,禁用同步阻塞的 `window.confirm`/`alert`/`prompt`。
|
|
79
|
+
|
|
80
|
+
---
|
|
81
|
+
|
|
82
|
+
## 支持的 IDE 与多 Agent 原生适配矩阵
|
|
83
|
+
|
|
84
|
+
| Agent 配置文件 (`agentType`) | 适配模式 | Skills 目标目录 | MCP 服务目标配置 | 规则 / 指令目标文件 | Subagents 模板目标目录 |
|
|
85
|
+
| :--- | :--- | :--- | :--- | :--- | :--- |
|
|
86
|
+
| **Antigravity (`antigravity`)** | `bundle` | `~/.gemini/config/plugins/<id>` | 插件包内 (`mcp_config.json`) | 插件包内 (`rules/*.md`) | 插件包内 (`agents/*.md`) |
|
|
87
|
+
| **Claude Code (`claude-code`)** | `convert` | `~/.claude/skills/<skill>` | `~/.claude.json` (`mcpServers`) | `~/.claude/CLAUDE.md` (`@path` 隔离块) | `~/.claude/agents/*.md` |
|
|
88
|
+
| **Codex CLI (`codex`)** | `convert` | `~/.codex/skills/<skill>` | `~/.codex/config.toml` (`[mcp_servers.*]`) | `~/.codex/AGENTS.md` (托管隔离块) | — |
|
|
89
|
+
| **OpenCode (`opencode`)** | `convert` | `~/.config/opencode/skills/<skill>` | `~/.config/opencode/opencode.json` (`mcp`) | `~/.config/opencode/AGENTS.md` | `~/.config/opencode/agents/*.md` |
|
|
90
|
+
| **VS Code / Copilot (`vscode-copilot`)** | `convert` | `~/.copilot/skills/<skill>` | `<AppData>/Code/User/mcp.json` (`servers`) | `Code/User/prompts/*.instructions.md` | `Code/User/prompts/*.agent.md` |
|
|
91
|
+
| **Cursor AI (`cursor`)** | `convert` | `~/.cursor/skills/<skill>` | `~/.cursor/mcp.json` (`mcpServers`) | 工作区 `.cursor/rules` | — |
|
|
92
|
+
| **Windsurf (`windsurf`)** | `convert` | `~/.codeium/windsurf/skills/<skill>` | `~/.codeium/windsurf/mcp_config.json` | `~/.codeium/windsurf/memories/global_rules.md` | — |
|
|
93
|
+
| **Gemini CLI (`gemini-cli`)** | `convert` | `~/.gemini/skills/<skill>` | `~/.gemini/settings.json` (`mcpServers`) | `~/.gemini/GEMINI.md` | — |
|
|
94
|
+
| **Cline (`cline`)** | `convert` | `~/.cline/skills/<skill>` | `globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `~/Documents/Cline/Rules/*.md` | — |
|
|
95
|
+
| **Roo Code (`roo-code`)** | `convert` | `~/.roo/skills/<skill>` | `globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json` | `~/.roo/rules/*.md` | — |
|
|
96
|
+
| **Kiro (`kiro`)** | `convert` | `~/.kiro/skills/<skill>` | `~/.kiro/settings/mcp.json` | `~/.kiro/steering/*.md` | — |
|
|
97
|
+
| **Universal (`agents-universal`)** | `convert` | `~/.agents/skills/<skill>` | — | — | — |
|
|
98
|
+
| **Custom (`custom`)** | `convert` | `<custom-dir>/<skill>` | 支持自定义路径覆盖 | 支持自定义路径覆盖 | 支持自定义路径覆盖 |
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## 架构与标准存储目录规范
|
|
103
|
+
|
|
104
|
+
```text
|
|
105
|
+
[ Magpie 宿主环境 (Bun / WebView2) ]
|
|
106
|
+
│
|
|
107
|
+
├── IPC 通信: globalThis.magpie.api (getPlugins, saveConfig, connectAgent 等)
|
|
108
|
+
└── HTTP / REST 接口: http://127.0.0.1:41789/api/* (server.mjs)
|
|
109
|
+
│
|
|
110
|
+
▼
|
|
111
|
+
[ manager.mjs + adapters.mjs + agents.mjs ]
|
|
112
|
+
├── scanPlugins(hubRoot) 与 buildCategoriesRegistry()
|
|
113
|
+
├── 智能中间件 (smart-tools.middleware.js: onRequest / onResponse)
|
|
114
|
+
└── connectAgent / syncAllIdes ──> 操作系统 Junction/Symlink 与原生配置托管块
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Components Storage 标准目录结构:
|
|
118
|
+
|
|
119
|
+
```text
|
|
120
|
+
<Components Storage Path>/
|
|
121
|
+
├── plugins/<plugin-name>/
|
|
122
|
+
│ ├── plugin.json # 必需清单文件 (name, version, description, upstream)
|
|
123
|
+
│ ├── mcp_config.json # 可选 MCP 服务定义
|
|
124
|
+
│ ├── hooks.json # 可选生命周期 Hooks 定义
|
|
125
|
+
│ ├── skills/ # 可选 Skills 技能目录 (<skill-name>/SKILL.md)
|
|
126
|
+
│ ├── agents/ # 可选 Subagent 智能体模板 (<agent-name>.md)
|
|
127
|
+
│ └── rules/ # 可选规则指令目录 (<rule-name>.md)
|
|
128
|
+
├── skills/ # 可选独立技能目录
|
|
129
|
+
├── shared/ # 跨 Agent IPC、handoff/、_upstream_backups/ 与共享工具目录
|
|
130
|
+
├── hub-config.json # Hub 配置文件
|
|
131
|
+
├── plugins.json # 已发现插件索引
|
|
132
|
+
└── skills.json # 已发现技能索引
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 自动化测试套件
|
|
138
|
+
|
|
139
|
+
在隔离的临时 `HOME` 沙箱环境下运行测试套件(`ASM_TEST=1` / `NODE_ENV=test`):
|
|
140
|
+
|
|
141
|
+
```bash
|
|
142
|
+
npm test
|
|
143
|
+
npm run test:report
|
|
144
|
+
npm run test:universal
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
---
|
|
148
|
+
|
|
149
|
+
## 支持与赞助
|
|
150
|
+
|
|
151
|
+
如果 Agent Space Manager 对您的日常开发工作流有所帮助,欢迎通过以下渠道支持开发:
|
|
152
|
+
- [Wise - Terence Ooi Teng Wei @terenceooit](https://wise.com/pay/me/terenceooit)
|
|
153
|
+
|
|
154
|
+
---
|
|
155
|
+
|
|
156
|
+
## 开源协议
|
|
157
|
+
|
|
158
|
+
MIT © Terence Ooi
|