@coralai/sps-cli 0.89.14 → 0.89.15
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/dist/console/index.d.ts.map +1 -1
- package/dist/console/index.js +2 -0
- package/dist/console/index.js.map +1 -1
- package/dist/console/routes/help.d.ts +3 -0
- package/dist/console/routes/help.d.ts.map +1 -0
- package/dist/console/routes/help.js +99 -0
- package/dist/console/routes/help.js.map +1 -0
- package/dist/console-assets/assets/{ShowcasePage-U8YSqMkw.js → ShowcasePage-DBSqP7-O.js} +1 -1
- package/dist/console-assets/assets/{index-BN0kx67J.css → index-CfPC9qFe.css} +1 -1
- package/dist/console-assets/assets/{index-_my94-Yq.js → index-DQkAZkNG.js} +1794 -1792
- package/dist/console-assets/index.html +2 -2
- package/docs/help/01-install.md +95 -0
- package/docs/help/02-commands.md +230 -0
- package/docs/help/03-console.md +75 -0
- package/docs/help/04-plugins.md +106 -0
- package/docs/help/05-api.md +388 -0
- package/package.json +6 -3
|
@@ -8,8 +8,8 @@
|
|
|
8
8
|
<link rel="preconnect" href="https://fonts.googleapis.com">
|
|
9
9
|
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
|
10
10
|
<link href="https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
|
|
11
|
-
<script type="module" crossorigin src="/assets/index-
|
|
12
|
-
<link rel="stylesheet" crossorigin href="/assets/index-
|
|
11
|
+
<script type="module" crossorigin src="/assets/index-DQkAZkNG.js"></script>
|
|
12
|
+
<link rel="stylesheet" crossorigin href="/assets/index-CfPC9qFe.css">
|
|
13
13
|
</head>
|
|
14
14
|
<body>
|
|
15
15
|
<div id="root"></div>
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 安装与部署
|
|
3
|
+
order: 1
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 安装与部署
|
|
7
|
+
|
|
8
|
+
## 环境要求
|
|
9
|
+
|
|
10
|
+
| 项 | 要求 | 备注 |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| Node.js | `>=18.0.0` | 生产实测跑在 v22 |
|
|
13
|
+
| 包名 | `@coralai/sps-cli` | 公共 npm |
|
|
14
|
+
| 命令 | `sps` | 全局安装后可用 |
|
|
15
|
+
|
|
16
|
+
## 安装
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm i -g @coralai/sps-cli
|
|
20
|
+
sps --version
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
升级同一条命令带版本号:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm i -g @coralai/sps-cli@0.89.14
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
> 🔴 **升级不会冲掉插件和装配档。** 它们在包目录**外面**:
|
|
30
|
+
> 插件在 `~/.coral/plugins/`、装配档在 `~/.coral/assembly/`。
|
|
31
|
+
> (早期设计曾把插件放在包内 `node_modules`,那时升级确实会丢 —— 那条已作废。)
|
|
32
|
+
|
|
33
|
+
## 初始化
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
sps setup # 凭据、目录、全局配置；已存在时用 --force 覆盖
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
它写的是**用户级**配置,全部落在 `~/.coral/` 下:
|
|
40
|
+
|
|
41
|
+
| 路径 | 装什么 |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `~/.coral/env` | 凭据(API key 等),**含密,权限 0600** |
|
|
44
|
+
| `~/.coral/projects/<项目>/` | 项目元数据:conf、卡片、日志、runtime |
|
|
45
|
+
| `~/.coral/plugins/` | 装好的插件包(`node_modules/`) |
|
|
46
|
+
| `~/.coral/assembly/base.yml` | 装配档:挂哪些插件 |
|
|
47
|
+
| `~/.coral/skills/` | 技能 HQ |
|
|
48
|
+
| `~/.coral/media-providers.json` · `media-defaults.json` | 媒体 provider 注册表与各能力默认 |
|
|
49
|
+
|
|
50
|
+
## 服务化部署(生产)
|
|
51
|
+
|
|
52
|
+
生产上跑两个常驻进程,用 systemd 管:
|
|
53
|
+
|
|
54
|
+
| 服务 | 进程 | 说明 |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `sps-console` | `sps console --port 4321 --no-open` | HTTP API + 控制台 |
|
|
57
|
+
| `sps-daemon` | `sps daemon`(会话宿主) | worker 会话 |
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
systemctl restart sps-daemon sps-console
|
|
61
|
+
systemctl is-active sps-daemon sps-console
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
⚠️ **重启前先看有没有在飞的活**:
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
sps status | grep "projects running" # 期望 0/N
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
重启会打断正在跑的 worker。**"有 claude 进程"不等于"有活在跑"** ——
|
|
71
|
+
以 `sps status` 的读数为准,不要靠 `ps`。
|
|
72
|
+
|
|
73
|
+
## 升级流程(线上)
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
sps status # 1. 确认 0 在飞
|
|
77
|
+
npm i -g @coralai/sps-cli@<新版本> # 2. 升级
|
|
78
|
+
systemctl restart sps-daemon sps-console # 3. 重启
|
|
79
|
+
curl -s localhost:4321/api/health # 4. 验收：HTTP 200
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
⚠️ 第 4 步之后还要确认**插件仍挂着** —— 升级本身不动插件,但版本变了可能有兼容问题:
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
curl -s "localhost:4321/api/plugins?token=<token>" # 各插件 mounted 应为 true
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## 常见排查
|
|
89
|
+
|
|
90
|
+
| 现象 | 先查 |
|
|
91
|
+
|---|---|
|
|
92
|
+
| `sps` 命令找不到 | npm 全局 bin 是否在 `PATH` 里 |
|
|
93
|
+
| 控制台 401 | token 是否过期。console 重启会换 token,在启动日志里 |
|
|
94
|
+
| 插件没生效 | `~/.coral/assembly/base.yml` 里有没有它;`GET /api/plugins` 看 `mounted` |
|
|
95
|
+
| 改了配置没反应 | 长驻进程(console/daemon)要重启;一次性命令下一条就带上了 |
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 命令说明
|
|
3
|
+
generated: true
|
|
4
|
+
source: sps --help
|
|
5
|
+
version: 0.89.15
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# 命令说明
|
|
9
|
+
|
|
10
|
+
> ⚠️ **本页由 `scripts/gen-help-commands.mjs` 从 CLI 的 `--help` 生成,不要手改。**
|
|
11
|
+
> 改命令说明请改命令自己的 help 文本,然后跑 `npm run gen:help`。
|
|
12
|
+
> 门禁 `check:help` 会在两者不一致时报红。
|
|
13
|
+
|
|
14
|
+
当前版本 `0.89.15` 共 **27** 个命令。
|
|
15
|
+
|
|
16
|
+
### `sps agent`
|
|
17
|
+
|
|
18
|
+
Interact with the agent (zero-config, multi-turn chat)
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
Usage: sps agent "<prompt>" | sps agent --chat
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
### `sps setup`
|
|
25
|
+
|
|
26
|
+
Initial environment setup (credentials, dirs, config)
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
Usage: sps setup [--force]
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
### `sps init`
|
|
33
|
+
|
|
34
|
+
Create/register a project (workspace, conf, hooks)
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
Usage: sps init <project> [--dir <path>] [--yes] [--origin <origin>] [--force]
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
### `sps plugin`
|
|
41
|
+
|
|
42
|
+
Manage which plugins each assembly mounts
|
|
43
|
+
|
|
44
|
+
```
|
|
45
|
+
Usage: sps plugin <add|remove|list> <包名|id> [--assembly base|cli|console|daemon]
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
### `sps im`
|
|
49
|
+
|
|
50
|
+
IM gateway (bind channels, run bridge)
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
Usage: sps im
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### `sps prune`
|
|
57
|
+
|
|
58
|
+
Reclaim orphan project metadata whose workspace is gone (dry-run unless --force)
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
Usage: sps prune [--force]
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
### `sps tick`
|
|
65
|
+
|
|
66
|
+
Run the continuous pipeline
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
Usage: sps tick <project> [--json]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### `sps card`
|
|
73
|
+
|
|
74
|
+
Manage cards (create, board, mark started/complete)
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
Usage: sps card <subcommand> <project> [args]
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### `sps doctor`
|
|
81
|
+
|
|
82
|
+
Project health check and state repair
|
|
83
|
+
|
|
84
|
+
```
|
|
85
|
+
Usage: sps doctor <project> [--json] [--fix] [--reset-state] [--skip-remote]
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
### `sps scheduler`
|
|
89
|
+
|
|
90
|
+
Scheduler: promote Planning → Backlog
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
Usage: sps scheduler <subcommand> <project>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
### `sps pipeline`
|
|
97
|
+
|
|
98
|
+
Pipeline management (start/stop/status/board/custom)
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
Usage: sps pipeline <subcommand> [args]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### `sps worker`
|
|
105
|
+
|
|
106
|
+
Worker lifecycle management
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
Usage: sps worker <subcommand> <project> [seq]
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### `sps pm`
|
|
113
|
+
|
|
114
|
+
PM backend operations (scan/move/comment/label)
|
|
115
|
+
|
|
116
|
+
```
|
|
117
|
+
Usage: sps pm <subcommand> <project> [args...]
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
### `sps qa`
|
|
121
|
+
|
|
122
|
+
QA closeout: QA → merge → Done
|
|
123
|
+
|
|
124
|
+
```
|
|
125
|
+
Usage: sps qa <subcommand> <project>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
### `sps monitor`
|
|
129
|
+
|
|
130
|
+
Anomaly detection and diagnostics
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
Usage: sps monitor <subcommand> <project>
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
### `sps project`
|
|
137
|
+
|
|
138
|
+
Project initialization and validation
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
Usage: sps project <subcommand> <project>
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
### `sps logs`
|
|
145
|
+
|
|
146
|
+
Live log viewer
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
Usage: sps logs [project] [--err] [--lines N] [--no-follow]
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### `sps stop`
|
|
153
|
+
|
|
154
|
+
Stop running tick processes
|
|
155
|
+
|
|
156
|
+
```
|
|
157
|
+
Usage: sps stop <project> [--all]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### `sps reset`
|
|
161
|
+
|
|
162
|
+
Reset card state; clean worktree and branch for re-run
|
|
163
|
+
|
|
164
|
+
```
|
|
165
|
+
Usage: sps reset <project> [--all] [--card N,N,N]
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### `sps skill`
|
|
169
|
+
|
|
170
|
+
Skill management (HQ: ~/.coral/skills + 项目 .sps/skills;claude 走 .claude/skills 投影)
|
|
171
|
+
|
|
172
|
+
```
|
|
173
|
+
Usage: sps skill <subcommand> [name] [--project <name>]
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
### `sps console`
|
|
177
|
+
|
|
178
|
+
Launch the SPS Console web UI (local browser)
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
Usage: sps console [--port 4311] [--host 127.0.0.1] [--no-open] [--dev] [--detach] [--stop] [--restart]
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### `sps model`
|
|
185
|
+
|
|
186
|
+
Configure the worker model source (multi-platform + local auth)
|
|
187
|
+
|
|
188
|
+
```
|
|
189
|
+
Usage: sps model <subcommand> [args]
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### `sps memory`
|
|
193
|
+
|
|
194
|
+
本地记忆 v2(存/查/读/列/重建/提升/收敛/迁移)
|
|
195
|
+
|
|
196
|
+
```
|
|
197
|
+
Usage: sps memory <save|recall|search|read|list|reindex|promote|gc|migrate> <project> [args]
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
### `sps art`
|
|
201
|
+
|
|
202
|
+
美术资源链的确定性运算(抠图/切帧/图集/尺寸;供 art-chain skill 调用)
|
|
203
|
+
|
|
204
|
+
```
|
|
205
|
+
Usage: sps art <chroma-key|rembg|clean-alpha|residue|slice-sheet|pack-atlas|normalize|resize|inspect> [args]
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### `sps graph`
|
|
209
|
+
|
|
210
|
+
项目级代码图谱(建图/查询,底层 codegraph)
|
|
211
|
+
|
|
212
|
+
```
|
|
213
|
+
Usage: sps graph <build|sync|status|explore|node|query|callers|callees|impact> [args]
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### `sps status`
|
|
217
|
+
|
|
218
|
+
Show running status of all projects
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
Usage: sps status [--json]
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### `sps hook`
|
|
225
|
+
|
|
226
|
+
Claude Code hook event wrapper (called by .claude/settings.json)
|
|
227
|
+
|
|
228
|
+
```
|
|
229
|
+
Usage: sps hook <event>
|
|
230
|
+
```
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 控制台使用
|
|
3
|
+
order: 3
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 控制台使用
|
|
7
|
+
|
|
8
|
+
启动:
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
sps console --port 4321
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
生产上它由 systemd 常驻(`sps-console`)。首次访问要带 token —— **token 在启动日志里**,
|
|
15
|
+
console 每次重启会换一个。
|
|
16
|
+
|
|
17
|
+
## 九个页面各管什么
|
|
18
|
+
|
|
19
|
+
| 页面 | 路径 | 用它做什么 | 什么时候来这儿 |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| **首页** | `/` | 与 agent 对话、发起任务 | 日常入口;也是会话的唯一入口(独立 chat 页已退休) |
|
|
22
|
+
| **项目** | `/projects` | 项目列表、新建、配置(conf / pipeline / 技能白名单) | 建项目、改项目参数 |
|
|
23
|
+
| **看板** | `/board` | 卡片的状态流转 | 看某个项目跑到哪了 |
|
|
24
|
+
| **编排** | `/arrange` | 卡片依赖与波次的可视化画布 | 想知道"为什么这张卡还没开始" |
|
|
25
|
+
| **技能** | `/skills` | 技能 HQ:列表、导入、编辑、挂到项目 | 给项目加能力 |
|
|
26
|
+
| **提示词** | `/prompts` | 提示词库 | 复用写好的提示 |
|
|
27
|
+
| **插件** | `/plugins` | 装/停/配置插件,媒体 provider | 扩展 sps 的能力 |
|
|
28
|
+
| **系统** | `/system` | 运行状态、模型配置、凭据 | 排查环境问题 |
|
|
29
|
+
| **记忆** | `/memory` | 本地记忆库 | 查 agent 记住了什么 |
|
|
30
|
+
|
|
31
|
+
## 看板:卡片状态怎么读
|
|
32
|
+
|
|
33
|
+
卡片会经过这些状态,**每个状态是磁盘上的一个目录**(`~/.coral/projects/<项目>/cards/<状态>/`):
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
Planning → Backlog → Todo → Inprogress → (Review) → QA → Done
|
|
37
|
+
↘ Canceled
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
| 状态 | 含义 |
|
|
41
|
+
|---|---|
|
|
42
|
+
| `Planning` | 人工暂存,不参与执行 |
|
|
43
|
+
| `Backlog` | 待派发 |
|
|
44
|
+
| `Todo` | 已抢到名额,准备启动 |
|
|
45
|
+
| `Inprogress` | 正在跑 |
|
|
46
|
+
| `QA` | 待验收 |
|
|
47
|
+
| `Done` | 完成 |
|
|
48
|
+
| `Canceled` | **终止** —— 能力失败且声明了 `onFailure:'skip'` 时落这里 |
|
|
49
|
+
|
|
50
|
+
🔴 **`Canceled` 的卡曾经在所有界面上都看不见**(读取面漏扫了那个目录,线上 5 个项目 14 张卡从未显示过)。
|
|
51
|
+
0.89.14 修好了。如果你在旧版本上看到"构建成功但产物不对",去磁盘上翻一眼 `cards/canceled/`。
|
|
52
|
+
|
|
53
|
+
## 波次:为什么这张卡还没开始
|
|
54
|
+
|
|
55
|
+
卡片有 `order`(波次号)。**波次之间是硬屏障**:存在任何一张更小 `order` 的卡还没结束,
|
|
56
|
+
后面的卡就不会派 —— 无论有没有空闲名额。
|
|
57
|
+
|
|
58
|
+
- 同一个 `order` 的卡**并行**跑(这是"开发与美术并行"的实现方式)。
|
|
59
|
+
- 卡没有显式 `order` 时,回落成它的 `seq`。
|
|
60
|
+
- `Canceled` / `Planning` 的卡**不挡**后面的波次。
|
|
61
|
+
|
|
62
|
+
⚠️ **`order` 不要用 `0`** —— 它是 falsy,链路上任何一处 `x || 默认值` 都会吃掉它,
|
|
63
|
+
而回落值(`seq`)对首张卡恰好也是 1,**两个错误互相掩护、数字看起来完全合理**。
|
|
64
|
+
|
|
65
|
+
## 排查时最有用的三条
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
sps status # 哪些项目在跑、几个 worker 活着
|
|
69
|
+
curl -s localhost:4321/api/health # console 活着吗
|
|
70
|
+
curl -s "localhost:4321/api/plugins?token=<token>" # 插件挂上了吗（看 mounted）
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
⚠️ **界面上没有红卡 ≠ 没有失败。** `onFailure:'skip'` 的能力失败会落进 `Canceled`
|
|
74
|
+
(代码注释记着"实测生图 10.3% 的构建会遇到")。要确认产物对不对,看产物本身
|
|
75
|
+
(比如 `docs/placeholder-assets.json` 里还剩哪些是占位),不要只看卡片状态。
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: 插件系统
|
|
3
|
+
order: 4
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 插件系统
|
|
7
|
+
|
|
8
|
+
sps 的能力扩展走插件。**领域知识归插件,机制归 sps 本体** —— 这条边界有一道可执行的闸
|
|
9
|
+
(`src/productBoundary.ts`):会执行的代码里出现上层产品的名字当场红。
|
|
10
|
+
|
|
11
|
+
> 📖 **要写插件** → 看 [`docs/guides/writing-plugins.md`](../guides/writing-plugins.md)(seam 清单、
|
|
12
|
+
> 注册方式、契约包)。本页只讲**装、看、换、排查**。
|
|
13
|
+
|
|
14
|
+
## 插件能挂在哪些点上(seam)
|
|
15
|
+
|
|
16
|
+
| seam | 插件能做什么 |
|
|
17
|
+
|---|---|
|
|
18
|
+
| `sps.tools` | 注册 MCP 工具 —— agent 能调 |
|
|
19
|
+
| `sps.capabilities` | 注册能力 —— **卡片**能调(`kind:'tool'` 的卡) |
|
|
20
|
+
| `sps.cards` | 建卡 |
|
|
21
|
+
| `sps.media` | 生图/生音/生视频的 provider |
|
|
22
|
+
| `sps.storage` · `sps.repo` · `sps.notifier` · `sps.llm` · `sps.memory` | 对象存储 / 代码托管 / 通知 / 模型 / 记忆 |
|
|
23
|
+
|
|
24
|
+
🔴 **`tools` 与 `capabilities` 的区别是"谁按按钮"**:
|
|
25
|
+
工具由 **agent** 调(它自己决定要不要用);能力由**引擎**调(排一张卡,到点就跑)。
|
|
26
|
+
需要确定性触发的东西必须做成能力 —— 做成工具就变成"agent 大概会调"。
|
|
27
|
+
两者可以共用同一个函数,**但别抄成两份**。
|
|
28
|
+
|
|
29
|
+
## 装插件
|
|
30
|
+
|
|
31
|
+
**插件页(推荐)** —— 它真的会装包:
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
控制台 → 插件 → 「装一个插件」→ 填 npm 包名 / 本地目录 / tarball
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
底下跑 `npm install --ignore-scripts` 装到 `~/.coral/plugins/`,然后写装配档、热挂载。
|
|
38
|
+
|
|
39
|
+
⚠️ `--ignore-scripts` 是有意的:装一个包不该等于先执行它(那时还没验它是不是插件)。
|
|
40
|
+
**代价是需要构建才能用的包装不了** —— 那种包应当先发布再装。
|
|
41
|
+
|
|
42
|
+
**CLI** —— 它**只登记,不装包**:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
sps plugin add <包名> [--assembly base|cli|console|daemon]
|
|
46
|
+
sps plugin list
|
|
47
|
+
sps plugin remove <id|包名>
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
⇒ 包必须**已经装在** `~/.coral/plugins/`。一个命令做两件事,失败时"哪一半没成"要靠猜,
|
|
51
|
+
所以 CLI 这条故意只做登记。解析不到会当场拒,**装配档一个字不改**。
|
|
52
|
+
|
|
53
|
+
## 装配档:决定挂哪些插件
|
|
54
|
+
|
|
55
|
+
`~/.coral/assembly/base.yml`(用户层,叠在包内出厂档之上):
|
|
56
|
+
|
|
57
|
+
```yaml
|
|
58
|
+
- id: my-plugin
|
|
59
|
+
name: file:///home/sps/.coral/plugins/node_modules/my-plugin/index.mjs
|
|
60
|
+
pkg: my-plugin
|
|
61
|
+
version: 1.0.0
|
|
62
|
+
config:
|
|
63
|
+
someOption: value
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
🔴 **`name` 要写 `file://` 绝对路径,不要写裸包名。** 裸包名是从 **loader 自己所在的包**
|
|
67
|
+
解析的(跟 baseUrl 无关)⇒ 装在用户目录的包永远找不到。线上现存条目全是 `file://` 且都在跑,
|
|
68
|
+
那是已验证有效的形状。
|
|
69
|
+
|
|
70
|
+
## 换一个插件版本
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
# 1. 备份当前版本（这是回滚点，不是可选的）
|
|
74
|
+
cp -a ~/.coral/plugins/node_modules/<包> ~/.coral/plugins/.rollback
|
|
75
|
+
|
|
76
|
+
# 2. 装新包
|
|
77
|
+
cd ~/.coral/plugins && npm install --ignore-scripts --save-exact <tgz或包名@版本>
|
|
78
|
+
|
|
79
|
+
# 3. 改装配档之前，先单独验三个入口能不能 import —— 失败就不用改装配档了
|
|
80
|
+
node -e "import('file:///home/sps/.coral/plugins/node_modules/<包>/index.mjs').then(()=>console.log('ok'))"
|
|
81
|
+
|
|
82
|
+
# 4. 重启（先确认 sps status 是 0 在飞）
|
|
83
|
+
systemctl restart sps-daemon sps-console
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**换完怎么确认真的换了:**
|
|
87
|
+
|
|
88
|
+
| 判据 | 说明 |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `GET /api/plugins` 里 `mounted=true` | 插件真的挂上了 |
|
|
91
|
+
| `name` 指向新路径 | 装配档生效了 |
|
|
92
|
+
| 进程里的原生库路径(`/proc/<pid>/map_files`) | **物理证据** —— 如果插件依赖原生模块(如 sharp) |
|
|
93
|
+
|
|
94
|
+
⚠️ **版本号相同不代表内容相同,内容哈希相同也不代表换成功** ——
|
|
95
|
+
如果新旧包字节同构,哈希一致在"换成了"和"根本没换"两种情况下**都成立**。
|
|
96
|
+
要判断换没换成,问**运行中的进程**,别只比对文件。
|
|
97
|
+
|
|
98
|
+
## 常见问题
|
|
99
|
+
|
|
100
|
+
| 现象 | 原因 |
|
|
101
|
+
|---|---|
|
|
102
|
+
| 插件装了但没生效 | 装配档里没有它;或长驻进程没重启 |
|
|
103
|
+
| 整个插件静默不挂 | 漏了 `inject` 声明。`GET /api/plugins` 看 `mounted` |
|
|
104
|
+
| `plugin add` 报"解析不到这个包" | 包还没装到 `~/.coral/plugins/`;CLI 只登记不装包 |
|
|
105
|
+
| 多入口包装不上 | `plugin add` 要求单入口。多入口(一个包三个插件)只能手工改装配档 |
|
|
106
|
+
| 改了插件源码线上没变 | 装的是包的快照。要么重新 pack+装,要么装配档指向开发树(**那样就没有版本了**) |
|