@coralai/sps-cli 0.58.0 → 0.58.2
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-CN.md +23 -0
- package/README.md +23 -0
- package/dist/commands/pipelineTick.js +9 -9
- package/dist/commands/pipelineTick.js.map +1 -1
- package/dist/commands/tick.d.ts.map +1 -1
- package/dist/commands/tick.js +11 -9
- package/dist/commands/tick.js.map +1 -1
- package/dist/console/routes/chat.d.ts.map +1 -1
- package/dist/console/routes/chat.js +12 -27
- package/dist/console/routes/chat.js.map +1 -1
- package/dist/core/agents/sidecar/CodexProxyManager.d.ts +7 -3
- package/dist/core/agents/sidecar/CodexProxyManager.d.ts.map +1 -1
- package/dist/core/agents/sidecar/CodexProxyManager.js +19 -6
- package/dist/core/agents/sidecar/CodexProxyManager.js.map +1 -1
- package/dist/manager/makeBackendFactory.d.ts.map +1 -1
- package/dist/manager/makeBackendFactory.js +2 -4
- package/dist/manager/makeBackendFactory.js.map +1 -1
- package/dist/shared/runtimeSchemas.d.ts +0 -2
- package/dist/shared/runtimeSchemas.d.ts.map +1 -1
- package/dist/shared/runtimeSchemas.js +3 -1
- package/dist/shared/runtimeSchemas.js.map +1 -1
- package/package.json +3 -1
- package/skills/sps-memory/SKILL.md +51 -0
- package/skills/sps-pipeline/SKILL.md +476 -0
- package/dist/core/agents/workerAnthropicEnv.d.ts +0 -23
- package/dist/core/agents/workerAnthropicEnv.d.ts.map +0 -1
- package/dist/core/agents/workerAnthropicEnv.js +0 -22
- package/dist/core/agents/workerAnthropicEnv.js.map +0 -1
|
@@ -0,0 +1,476 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sps-pipeline
|
|
3
|
+
description: |
|
|
4
|
+
SPS pipeline & project management — set up projects, configure YAML pipelines, manage
|
|
5
|
+
task cards, drive worker lifecycle, run web console, monitor health. Use when the user
|
|
6
|
+
asks to "create a pipeline", "set up a project", "add tasks", "start the pipeline",
|
|
7
|
+
"open console", "check status", or anything in the SPS workflow. (🪸 Coral SPS)
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# SPS Pipeline (v0.51.x — Single-Worker Card Pipeline + Web Console + Wiki)
|
|
11
|
+
|
|
12
|
+
SPS drives an AI worker through task cards. **One worker, one card at a time, serial
|
|
13
|
+
execution.** Each card walks one or more YAML-defined stages (e.g. `develop → review →
|
|
14
|
+
Done`); failure halts until the user resolves it. v0.50 added a 4-layer service
|
|
15
|
+
architecture; v0.51 added per-project Wiki knowledge base injection.
|
|
16
|
+
|
|
17
|
+
## Two ways to operate
|
|
18
|
+
|
|
19
|
+
| Mode | Command | Use when |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| **Web Console** (preferred) | `sps console` | Daily work — kanban, logs, worker dashboard, project create, conf editor, pipeline editor, chat with agent, all in one UI |
|
|
22
|
+
| **CLI** | `sps tick / card / worker / wiki / …` | Scripting, troubleshooting, headless servers |
|
|
23
|
+
|
|
24
|
+
Console listens on `127.0.0.1:4311` by default; opens browser auto. Single-instance
|
|
25
|
+
guard via `~/.coral/console.lock`.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## 1. First-time setup
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npm install -g @coralai/sps-cli # latest (currently 0.51.x)
|
|
33
|
+
sps setup # ⭐ MUST RUN: interactive wizard
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
`sps setup` does:
|
|
37
|
+
1. Creates `~/.coral/` directory tree (`projects/`, `memory/user/`, `memory/agents/`).
|
|
38
|
+
2. Copies bundled skills → `~/.coral/skills/`.
|
|
39
|
+
3. Interactively writes `~/.coral/env` (Git remote token, Matrix credentials, etc.).
|
|
40
|
+
4. Symlinks user skills → `~/.coral/.claude/skills/` and `~/.claude/skills/`.
|
|
41
|
+
5. Installs `@agentclientprotocol/claude-agent-acp` globally if missing.
|
|
42
|
+
|
|
43
|
+
Re-run safe: `sps setup --force` keeps existing values as defaults.
|
|
44
|
+
|
|
45
|
+
**No separate console config**. Console reads `~/.coral/env` + per-project conf.
|
|
46
|
+
|
|
47
|
+
---
|
|
48
|
+
|
|
49
|
+
## 2. Create a project
|
|
50
|
+
|
|
51
|
+
### Option A — Console (recommended)
|
|
52
|
+
Open `sps console` → `/projects/new` → fill form → submit. Form provides:
|
|
53
|
+
- Project name + repo path
|
|
54
|
+
- Git toggle (worker commits + pushes? off for non-code projects)
|
|
55
|
+
- **Wiki toggle** (v0.51+): scaffolds `wiki/` + writes `WIKI_ENABLED=true` to conf
|
|
56
|
+
- Merge branch, max workers, ACK timeout, Matrix room
|
|
57
|
+
|
|
58
|
+
### Option B — Interactive CLI
|
|
59
|
+
```bash
|
|
60
|
+
sps project init <name> # asks the same questions on tty
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### What gets created
|
|
64
|
+
|
|
65
|
+
```
|
|
66
|
+
~/.coral/projects/<name>/
|
|
67
|
+
├── conf # your active settings (private, mode 600)
|
|
68
|
+
├── conf.example # full reference with comments (read-only docs)
|
|
69
|
+
├── pipelines/
|
|
70
|
+
│ ├── project.yaml # default 1-stage pipeline (develop → Done)
|
|
71
|
+
│ └── sample.yaml.example # heavily-commented YAML reference
|
|
72
|
+
├── pipeline_order.json # active pipeline pointer
|
|
73
|
+
├── runtime/
|
|
74
|
+
│ ├── state.json # worker slot + active card state (machine-managed)
|
|
75
|
+
│ └── tick.lock # lock file
|
|
76
|
+
├── logs/ # per-tick logs
|
|
77
|
+
├── pm_meta/ # markdown card backend metadata
|
|
78
|
+
└── cards/ # state subdirs created on first use
|
|
79
|
+
└── seq.txt
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Plus, in the **target repo** (PROJECT_DIR):
|
|
83
|
+
- `.claude/CLAUDE.md` — worker rules + (if wiki=on) wiki SOP block
|
|
84
|
+
- `.claude/skills/` — symlinked from `~/.coral/skills/`
|
|
85
|
+
- `.claude/settings.local.json` — Claude Code local config
|
|
86
|
+
- `wiki/` (if wiki=on) — knowledge base scaffold
|
|
87
|
+
- `ATTRIBUTION.md` (if wiki=on) — borrows declaration
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 3. Pipeline YAML
|
|
92
|
+
|
|
93
|
+
**Location**: `~/.coral/projects/<name>/pipelines/project.yaml`
|
|
94
|
+
|
|
95
|
+
**Single source of truth** for stages, profiles, transitions. Edit this file (or in
|
|
96
|
+
console at `/projects/<name>` pipeline editor) to customize.
|
|
97
|
+
|
|
98
|
+
### Critical YAML rules
|
|
99
|
+
|
|
100
|
+
1. **`mode: project`** — orchestrate cards through states. (`mode: steps` is for
|
|
101
|
+
one-shot custom pipelines via `sps pipeline run <name>`.)
|
|
102
|
+
2. **`on_complete` of each stage points to the next stage's target state.** No
|
|
103
|
+
skipping, no looping.
|
|
104
|
+
3. **Last stage's `on_complete: "move_card Done"`.**
|
|
105
|
+
4. **Don't write `agent:` field** — it's accepted for back-compat but ignored.
|
|
106
|
+
Claude (via ACP) is the only supported worker as of v0.38.0.
|
|
107
|
+
5. **Single worker, serial execution** — set `MAX_CONCURRENT_WORKERS` in conf if
|
|
108
|
+
you want >1 slot reserved, but cards still run one at a time.
|
|
109
|
+
6. **Failure halts pipeline** by default (`on_fail.halt: true`). Worker labels card
|
|
110
|
+
`NEEDS-FIX`; user must resolve before next card runs.
|
|
111
|
+
|
|
112
|
+
### Templates
|
|
113
|
+
|
|
114
|
+
**Simple (1 stage):**
|
|
115
|
+
```yaml
|
|
116
|
+
mode: project
|
|
117
|
+
git: true
|
|
118
|
+
stages:
|
|
119
|
+
- name: develop
|
|
120
|
+
on_complete: "move_card Done"
|
|
121
|
+
on_fail:
|
|
122
|
+
action: "label NEEDS-FIX"
|
|
123
|
+
halt: true
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
**With review (2 stages):**
|
|
127
|
+
```yaml
|
|
128
|
+
mode: project
|
|
129
|
+
git: true
|
|
130
|
+
stages:
|
|
131
|
+
- name: develop
|
|
132
|
+
profile: fullstack
|
|
133
|
+
on_complete: "move_card Review"
|
|
134
|
+
on_fail: { action: "label NEEDS-FIX", halt: true }
|
|
135
|
+
- name: review
|
|
136
|
+
profile: reviewer
|
|
137
|
+
on_complete: "move_card Done"
|
|
138
|
+
on_fail: { action: "label REVIEW-FAILED", halt: true }
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
**Non-git (data / docs project):**
|
|
142
|
+
```yaml
|
|
143
|
+
mode: project
|
|
144
|
+
git: false
|
|
145
|
+
stages:
|
|
146
|
+
- name: process
|
|
147
|
+
profile: tax-worker
|
|
148
|
+
on_complete: "move_card Done"
|
|
149
|
+
on_fail: { action: "label PROCESS-FAILED", halt: true }
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
### YAML field reference
|
|
153
|
+
|
|
154
|
+
| Field | Required | Notes |
|
|
155
|
+
|---|---|---|
|
|
156
|
+
| `mode` | yes | `project` (state machine) or `steps` (one-shot, run via `sps pipeline run`) |
|
|
157
|
+
| `git` | no | `true` (default) — worker commits + pushes / `false` — no git ops |
|
|
158
|
+
| `stages` | yes | Array |
|
|
159
|
+
| `stages[].name` | yes | Unique within file |
|
|
160
|
+
| `stages[].profile` | no | Skill profile (e.g. `fullstack` / `reviewer` / `tax-worker`); falls back to `DEFAULT_WORKER_SKILLS` in conf |
|
|
161
|
+
| `stages[].on_complete` | yes | `"move_card <NextState>"` |
|
|
162
|
+
| `stages[].on_fail.action` | no | `"label NEEDS-FIX"` etc. |
|
|
163
|
+
| `stages[].on_fail.halt` | no | default `true` |
|
|
164
|
+
| `stages[].on_fail.comment` | no | Comment text |
|
|
165
|
+
| `stages[].timeout` | no | `30s` / `5m` / `2h` (rare) |
|
|
166
|
+
|
|
167
|
+
`trigger` and `card_state` are auto-derived per stage from the position. Don't set
|
|
168
|
+
manually.
|
|
169
|
+
|
|
170
|
+
### Custom pipelines (mode: steps)
|
|
171
|
+
|
|
172
|
+
For one-shot scripted runs (e.g. canary deploy, bulk ingest), use `mode: steps` and
|
|
173
|
+
invoke via `sps pipeline run <pipeline-name> "<prompt>"`. Out of scope for normal
|
|
174
|
+
card pipelines; see `sample.yaml.example` for syntax.
|
|
175
|
+
|
|
176
|
+
---
|
|
177
|
+
|
|
178
|
+
## 4. Card state machine
|
|
179
|
+
|
|
180
|
+
```
|
|
181
|
+
v0.51.9 起:
|
|
182
|
+
|
|
183
|
+
Backlog → Todo → Inprogress → [QA / Review] → Done
|
|
184
|
+
↑↓
|
|
185
|
+
Planning(用户手动暂存;不自动派发)
|
|
186
|
+
↓ fail
|
|
187
|
+
NEEDS-FIX (halt)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Default states (configurable in YAML `pm.card_states`):
|
|
191
|
+
- **Planning** — v0.51.10+:人工暂存 / 草稿。**console "新卡片" 表单**默认入此状态;用户拖到 Backlog 才会跑。
|
|
192
|
+
- **Backlog** — **`sps card add`(CLI / agent)**默认入此状态;StageEngine 抢卡执行。
|
|
193
|
+
- **Todo** — StageEngine 已 prep(建分支 / worktree),下次 tick 派 worker
|
|
194
|
+
- **Inprogress** — worker active
|
|
195
|
+
- **QA** (or **Review**) — code complete, awaiting human/auto verification
|
|
196
|
+
- **Done** — finished
|
|
197
|
+
- **Canceled** — folded into Done view (rare state)
|
|
198
|
+
|
|
199
|
+
Engines walk this graph each tick. The **active stage** writes a per-slot marker
|
|
200
|
+
file at `~/.coral/projects/<p>/runtime/worker-<slot>-current.json` (v0.50.21+).
|
|
201
|
+
Stop hook reads this to detect which card the worker just finished.
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 5. Card management
|
|
206
|
+
|
|
207
|
+
### Where new cards land — depends on caller (v0.51.10+)
|
|
208
|
+
|
|
209
|
+
| 调用方 | 默认入场 state | 行为 |
|
|
210
|
+
|---|---|---|
|
|
211
|
+
| **`sps card add`** (CLI / Worker / agent) | **Backlog** | 下次 tick 立即被 StageEngine 抢卡跑 |
|
|
212
|
+
| **Console "新卡片" 表单** | **Planning** | 暂存;用户在看板拖到 Backlog 才会跑 |
|
|
213
|
+
| **`POST /api/projects/<p>/cards`** 直接调 API | **Planning** | 默认人工语义;body 传 `initialState: 'Backlog'` 立即跑 |
|
|
214
|
+
|
|
215
|
+
**Agent 调 `sps card add` → 卡进 Backlog → 自动跑。** 这是 SPS 的主路径。Worker 在某个卡里需要"派生子任务"时用 `sps card add`,子任务会被下一个 tick 自动 pickup。
|
|
216
|
+
|
|
217
|
+
```bash
|
|
218
|
+
# Agent / Worker 主路径 — 直接进 Backlog 自动跑
|
|
219
|
+
sps card add <project> "Title" "Description"
|
|
220
|
+
sps card add <project> "T" "D" --skill python,backend
|
|
221
|
+
|
|
222
|
+
# 想暂存(让用户审核 / 自己稍后拖派发)
|
|
223
|
+
sps card add <project> "Title" "Description" --draft
|
|
224
|
+
# → 卡进 Planning,等手动拖到 Backlog
|
|
225
|
+
```
|
|
226
|
+
|
|
227
|
+
### View
|
|
228
|
+
|
|
229
|
+
```bash
|
|
230
|
+
sps card dashboard <project> # CLI table
|
|
231
|
+
# console: /board?project=<name>
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Lifecycle (machine-managed, but you can intervene)
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
sps card mark-started <p> <seq> # called by Claude Code UserPromptSubmit hook
|
|
238
|
+
sps card mark-complete <p> <seq> # called by Claude Code Stop hook
|
|
239
|
+
sps reset <p> # reset all non-Done
|
|
240
|
+
sps reset <p> --card 5,6,7 # reset specific seq
|
|
241
|
+
sps reset <p> --all # full reset incl. Done
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
注:`sps reset` 把卡退回 **Planning**(不是 Backlog) — 重置 = 退回人工控制,需手动拖回 Backlog 才会再跑。这是 v0.51.9 起的语义。
|
|
245
|
+
|
|
246
|
+
### Card label vocabulary
|
|
247
|
+
|
|
248
|
+
| Label | Meaning | Who sets |
|
|
249
|
+
|---|---|---|
|
|
250
|
+
| `AI-PIPELINE` | "SPS pipeline 卡" 的标记(v0.51.9+ 不再触发任何自动行为,仅识别) | `sps card add` 自动加 |
|
|
251
|
+
| `STARTED-<stage>` | ACK signal — Claude received the prompt | UserPromptSubmit hook |
|
|
252
|
+
| `COMPLETED-<stage>` | Worker finished a stage | Stop hook |
|
|
253
|
+
| `CLAIMED` | StageEngine reserved a worker slot | Engine |
|
|
254
|
+
| `NEEDS-FIX` | Worker failed; pipeline halted | Engine |
|
|
255
|
+
| `BLOCKED` | External dep; pipeline skips | User |
|
|
256
|
+
| `WAITING-CONFIRMATION` | Worker waiting on user input | Engine |
|
|
257
|
+
| `STALE-RUNTIME` | Inprogress > timeout | MonitorEngine |
|
|
258
|
+
| `ACK-TIMEOUT` | Claude never ACK'd within `WORKER_ACK_TIMEOUT_S` | MonitorEngine |
|
|
259
|
+
| `skill:<name>` | Force-load specific skill | User on card |
|
|
260
|
+
| `conflict:<domain>` | Serial-with-others-in-same-domain | User |
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## 6. Pipeline lifecycle commands
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
# Run continuously (one tick spawns next via cron-like loop)
|
|
268
|
+
sps tick <project> # foreground tick(s) — Ctrl+C to stop
|
|
269
|
+
sps pipeline start <project> # alias for tick
|
|
270
|
+
sps pipeline stop <project> # graceful stop
|
|
271
|
+
sps stop <project> # CLI alias for stop
|
|
272
|
+
sps stop --all # stop all running ticks
|
|
273
|
+
|
|
274
|
+
# Status
|
|
275
|
+
sps status # all projects
|
|
276
|
+
sps pipeline status # alias
|
|
277
|
+
sps doctor <project> # health check
|
|
278
|
+
sps doctor <project> --fix # auto-repair drift
|
|
279
|
+
|
|
280
|
+
# One-off ticks (each engine separately, useful for cron / debugging)
|
|
281
|
+
sps scheduler tick <p> # v0.51.9 起为 no-op(dormant,保留接口)
|
|
282
|
+
sps pipeline tick <p> # full StageEngine pass
|
|
283
|
+
sps qa tick <p> # QA → Done finalization
|
|
284
|
+
sps monitor tick <p> # health probe (ACK timeout, stale runtime)
|
|
285
|
+
sps pm scan <p> # rebuild card index from disk
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Worker control
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
sps worker ps <project> # list slots + PIDs
|
|
292
|
+
sps worker dashboard <project> # rich UI (also in console)
|
|
293
|
+
sps worker kill <project> <seq> # SIGKILL one slot
|
|
294
|
+
sps worker launch <project> <seq> # manual spawn (debugging)
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
### Logs
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
sps logs <project> # follow mode (default)
|
|
301
|
+
sps logs <project> --err # stderr only
|
|
302
|
+
sps logs <project> --lines 50 --no-follow
|
|
303
|
+
# console: /logs?project=<name> (live SSE)
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
---
|
|
307
|
+
|
|
308
|
+
## 7. Web Console (`sps console`)
|
|
309
|
+
|
|
310
|
+
Single binary launches the web UI:
|
|
311
|
+
|
|
312
|
+
```bash
|
|
313
|
+
sps console # opens http://127.0.0.1:4311
|
|
314
|
+
sps console --port 5000
|
|
315
|
+
sps console --no-open
|
|
316
|
+
sps console --kill # stop running console
|
|
317
|
+
sps console --dev # vite dev server (development)
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
Pages:
|
|
321
|
+
- `/projects` — list, summary cards
|
|
322
|
+
- `/projects/new` — create project (with Wiki toggle, v0.51)
|
|
323
|
+
- `/projects/<n>` — pipeline editor + conf editor + delete
|
|
324
|
+
- `/board` — kanban (with **per-column scrolling**, v0.51.1+)
|
|
325
|
+
- `/workers` — aggregate worker dashboard (all projects)
|
|
326
|
+
- `/logs` — live SSE log viewer
|
|
327
|
+
- `/skills` — user-level skill management
|
|
328
|
+
- `/system` — global settings, daemon status
|
|
329
|
+
- `/chat` — agent chat (multi-session, persistent)
|
|
330
|
+
|
|
331
|
+
---
|
|
332
|
+
|
|
333
|
+
## 8. Memory & Wiki (auto-injected into Worker prompts)
|
|
334
|
+
|
|
335
|
+
| | **Memory** (`sps-memory` skill) | **Wiki** (`wiki-update` skill) |
|
|
336
|
+
|---|---|---|
|
|
337
|
+
| Purpose | Ad-hoc facts, user prefs, decisions, gotchas | Structured project knowledge: modules, concepts, decisions, lessons |
|
|
338
|
+
| Path | `~/.coral/memory/{user,agents,projects/<p>}/` | `<repo>/wiki/` (per-project, in repo) |
|
|
339
|
+
| Schema | Markdown + YAML frontmatter (`type: convention/decision/lesson/reference`) | 5 page types with zod-validated frontmatter |
|
|
340
|
+
| Cross-link | None (flat index) | `[[type/Title]]` wikilinks |
|
|
341
|
+
| Auto-inject | `buildFullMemoryContext` → prompt's `knowledge` section | `wikiRead` 5-layer → prompt's `wikiContext` section (only when `WIKI_ENABLED=true`) |
|
|
342
|
+
| When to use | Personal style notes, "remember X" requests | Project knowledge that benefits future cards |
|
|
343
|
+
|
|
344
|
+
If you're configuring a project that needs structured knowledge accumulation,
|
|
345
|
+
**enable Wiki** at create time. For ad-hoc facts only, memory alone is enough.
|
|
346
|
+
|
|
347
|
+
CLI helpers:
|
|
348
|
+
```bash
|
|
349
|
+
sps memory list <p>
|
|
350
|
+
sps memory context <p> # preview what gets injected
|
|
351
|
+
sps memory add <p> --type convention --name "title" --body "content"
|
|
352
|
+
|
|
353
|
+
sps wiki init <p> # scaffold (auto when WIKI_ENABLED=true)
|
|
354
|
+
sps wiki update <p> # source diff
|
|
355
|
+
sps wiki update <p> --finalize # flush manifest after pages written
|
|
356
|
+
sps wiki check <p> # lint
|
|
357
|
+
sps wiki read <p> "<query>" # preview prompt injection
|
|
358
|
+
sps wiki list/get/add/status # browse / inspect
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
---
|
|
362
|
+
|
|
363
|
+
## 9. Conf reference (essentials)
|
|
364
|
+
|
|
365
|
+
Live at `~/.coral/projects/<name>/conf` (shell `export VAR="value"` syntax).
|
|
366
|
+
|
|
367
|
+
| Field | Default | Notes |
|
|
368
|
+
|---|---|---|
|
|
369
|
+
| `PROJECT_NAME` | (required) | Internal id |
|
|
370
|
+
| `PROJECT_DIR` | (required) | Repo absolute path |
|
|
371
|
+
| `GITLAB_PROJECT` | — | `user/repo` (optional, for GitLab API) |
|
|
372
|
+
| `GITLAB_MERGE_BRANCH` | `main` | Worker pushes here |
|
|
373
|
+
| `PM_TOOL` | `markdown` | **Only `markdown` supported as of v0.42.0**. Plane/Trello removed. Cards live in `~/.coral/projects/<n>/cards/<state>/<seq>.md` |
|
|
374
|
+
| `PIPELINE_LABEL` | `AI-PIPELINE` | Marker label auto-added by `sps card add` — identifies SPS-managed cards. v0.51.9+ 不再触发自动状态提升(卡按入场 state 决定是否跑) |
|
|
375
|
+
| `MR_MODE` | `none` | `none` (push direct) / `create` (open MR; needs `GITLAB_PROJECT_ID`) |
|
|
376
|
+
| `WORKER_TRANSPORT` | `acp-sdk` | Fixed; do not change |
|
|
377
|
+
| `MAX_CONCURRENT_WORKERS` | `1` | Slot count; cards still serial within a project |
|
|
378
|
+
| `MAX_ACTIONS_PER_TICK` | `3` | New tasks claimable per tick |
|
|
379
|
+
| `INPROGRESS_TIMEOUT_HOURS` | `2` | After this, MonitorEngine flags STALE-RUNTIME |
|
|
380
|
+
| `WORKER_ACK_TIMEOUT_S` | `300` | Wait for STARTED-<stage> label after dispatch (5min, raised in v0.50.24) |
|
|
381
|
+
| `WORKER_ACK_MAX_RETRIES` | `1` | ACK timeout retry count |
|
|
382
|
+
| `MONITOR_AUTO_QA` | `true` | Auto-advance to QA on stale runtime |
|
|
383
|
+
| `CONFLICT_DEFAULT` | `serial` | Fallback for cards without `conflict:` label |
|
|
384
|
+
| `MATRIX_ROOM_ID` | — | Project-level Matrix override |
|
|
385
|
+
| `WORKTREE_DIR` | `~/.coral/worktrees/<p>` | Worker scratch space |
|
|
386
|
+
| `DEFAULT_WORKER_SKILLS` | — | Comma-separated skill list when no `profile:` and no `card.skills` |
|
|
387
|
+
| `ENABLE_MEMORY` | `true` | Set `false` to skip memory write instructions in prompt |
|
|
388
|
+
| **`WIKI_ENABLED`** | unset (off) | **v0.51+**: `true` enables wiki context injection + reminder block |
|
|
389
|
+
| `COMPLETION_SIGNAL` | `done` | Word the Stop hook listens for |
|
|
390
|
+
|
|
391
|
+
Full reference: `~/.coral/projects/<n>/conf.example` (auto-generated, comment-rich).
|
|
392
|
+
|
|
393
|
+
---
|
|
394
|
+
|
|
395
|
+
## 10. Architecture (4-layer, v0.50+)
|
|
396
|
+
|
|
397
|
+
```
|
|
398
|
+
Delivery (commands/, console/routes/)
|
|
399
|
+
→ execute* / HTTP routes; thin
|
|
400
|
+
Service (services/)
|
|
401
|
+
→ ProjectService / ChatService / PipelineService / SkillService — Result<T> + DomainEvent
|
|
402
|
+
Domain (engines/)
|
|
403
|
+
→ SchedulerEngine / StageEngine / MonitorEngine / EventHandler
|
|
404
|
+
Infrastructure (manager/, providers/, daemon/)
|
|
405
|
+
→ WorkerManager (single worker), ACPWorkerRuntime, sessionDaemon
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
### Engines
|
|
409
|
+
|
|
410
|
+
- **SchedulerEngine** — v0.51.9 起 dormant(卡 add 直接进 Backlog,无需提升)
|
|
411
|
+
- **StageEngine** — drives card through stages; builds prompt (skill + projectRules
|
|
412
|
+
+ memory + **wikiContext** + task description + **wikiUpdateReminder**); kicks
|
|
413
|
+
Worker via ACP
|
|
414
|
+
- **MonitorEngine** — ACK timeout detection, stale runtime, auto-QA promotion
|
|
415
|
+
- **CloseoutEngine / EventHandler** — finalize completed cards
|
|
416
|
+
|
|
417
|
+
### Single worker is intentional
|
|
418
|
+
|
|
419
|
+
v0.37.2 deleted multi-worker concurrency code by design. Don't propose "add a
|
|
420
|
+
parallel mode" — the architecture relies on serial execution for state coherence.
|
|
421
|
+
For higher throughput, run multiple projects in parallel (each its own tick loop).
|
|
422
|
+
|
|
423
|
+
---
|
|
424
|
+
|
|
425
|
+
## 11. Troubleshooting
|
|
426
|
+
|
|
427
|
+
```bash
|
|
428
|
+
sps doctor <project> --fix # ★ first thing to try
|
|
429
|
+
sps logs <project> --err # stderr / errors
|
|
430
|
+
sps reset <project> --card <seq> # nuke a stuck card
|
|
431
|
+
sps reset <project> --all # full project reset (worktrees, branches, state)
|
|
432
|
+
|
|
433
|
+
# Worker / daemon issues
|
|
434
|
+
sps worker ps <project>
|
|
435
|
+
sps agent daemon status # is the chat daemon up?
|
|
436
|
+
sps agent daemon stop && sps agent daemon start # restart daemon (clears stale cwd)
|
|
437
|
+
|
|
438
|
+
# Wiki issues (v0.51+)
|
|
439
|
+
sps wiki check <project> # lint
|
|
440
|
+
sps wiki status <project> # source / manifest / pages diff
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
Common issues:
|
|
444
|
+
|
|
445
|
+
- **Pipeline halted with NEEDS-FIX** — open the failed card, fix the issue, remove
|
|
446
|
+
the label. Console makes this 2 clicks.
|
|
447
|
+
- **Worker not starting** — `sps worker ps`, then check `sps logs --err`. Often
|
|
448
|
+
Claude API key missing or `claude-agent-acp` adapter not installed (`sps setup`
|
|
449
|
+
reinstalls it).
|
|
450
|
+
- **Cards stuck in Planning (v0.51.9+)** — Planning 是人工暂存。**Console 表单建卡默认到这里**,需手动拖到 Backlog 派发。Agent / `sps card add` 默认进 Backlog 自动跑(不会卡在 Planning)。
|
|
451
|
+
- **ACK timeout on every card** — Claude cold-start is slow with many skills/memory
|
|
452
|
+
files. Raise `WORKER_ACK_TIMEOUT_S` in conf (default 300s as of v0.50.24).
|
|
453
|
+
- **Console shows stale data** — SSE may have dropped; reload page; if persistent,
|
|
454
|
+
`sps console --kill && sps console`.
|
|
455
|
+
- **Wiki context not injecting** — verify `WIKI_ENABLED=true` in conf and
|
|
456
|
+
`wiki/WIKI.md` exists. StageEngine logs a warning if conf says yes but scaffold
|
|
457
|
+
is missing.
|
|
458
|
+
|
|
459
|
+
---
|
|
460
|
+
|
|
461
|
+
## 12. Skill ↔ project linkage
|
|
462
|
+
|
|
463
|
+
User-level skills live in `~/.coral/skills/`. To use one in a specific project:
|
|
464
|
+
|
|
465
|
+
```bash
|
|
466
|
+
sps skill list # what's available + project status
|
|
467
|
+
sps skill add <name> --project <p> # symlink into <repo>/.claude/skills/
|
|
468
|
+
sps skill remove <name> --project <p>
|
|
469
|
+
sps skill freeze <name> --project <p> # symlink → real copy (allow project edits)
|
|
470
|
+
sps skill unfreeze <name> --project <p> # back to symlink
|
|
471
|
+
sps skill sync # ① bundled (npm pkg) → ~/.coral/skills/
|
|
472
|
+
# ② ~/.coral/skills/ → ~/.claude/skills/
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
**After upgrading sps-cli**, run `sps skill sync` to pick up new bundled skills
|
|
476
|
+
(e.g. `wiki-update` added in v0.51.0).
|
|
@@ -1,23 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* @module core/agents/workerAnthropicEnv
|
|
3
|
-
* @description worker(claude-ACP)的第三方 Anthropic 端点 env 解析。P0:仅 codex-proxy
|
|
4
|
-
* (ChatGPT 订阅经本地 claude-code-proxy 翻译)时注入 ANTHROPIC_BASE_URL/AUTH_TOKEN,
|
|
5
|
-
* 把 worker 指向本地 proxy(出 GPT)。其他 provider(官方订阅 / 真·Anthropic 兼容三方)
|
|
6
|
-
* 返回空 —— 各走老路(settings.local.json / 官方),不受影响。
|
|
7
|
-
* @layer core
|
|
8
|
-
* @boundedContext worker-lifecycle
|
|
9
|
-
*
|
|
10
|
-
* 红线:只按 worker 逐进程注入(经 acpExtraEnv),**永不写全局 env**;否则会把真 Claude 订阅的
|
|
11
|
-
* worker 一起劫持到 proxy 上。sidecar 生命周期 = P1(CodexProxyManager),此处只解析端点。
|
|
12
|
-
*/
|
|
13
|
-
import type { WorkerAgentConfig } from '../intel/types.js';
|
|
14
|
-
import { CODEX_PROXY_ID } from './sidecar/CodexProxyManager.js';
|
|
15
|
-
export { CODEX_PROXY_ID };
|
|
16
|
-
/**
|
|
17
|
-
* 解析 worker 的 Anthropic 端点 env。
|
|
18
|
-
* @returns codex-proxy → `{ ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL? }`;其余 → `{}`。
|
|
19
|
-
* ANTHROPIC_MODEL=worker.model,让控制台点选的 gpt 型号真到 proxy(否则 proxy 收到 claude 默认名)。
|
|
20
|
-
* 合并处 `{ ...本函数, ...o.extraEnv }` 里项目 conf 的 WORKER_MODEL(在 o.extraEnv)仍可覆盖。
|
|
21
|
-
*/
|
|
22
|
-
export declare function workerAnthropicEndpointEnv(worker: WorkerAgentConfig): Record<string, string>;
|
|
23
|
-
//# sourceMappingURL=workerAnthropicEnv.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"workerAnthropicEnv.d.ts","sourceRoot":"","sources":["../../../src/core/agents/workerAnthropicEnv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,EAAE,cAAc,EAAqB,MAAM,gCAAgC,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAS5F"}
|
|
@@ -1,22 +0,0 @@
|
|
|
1
|
-
import { getProvider } from '../../providers/llm/providers.js';
|
|
2
|
-
import { CODEX_PROXY_ID, codexProxyBaseUrl } from './sidecar/CodexProxyManager.js';
|
|
3
|
-
export { CODEX_PROXY_ID };
|
|
4
|
-
/**
|
|
5
|
-
* 解析 worker 的 Anthropic 端点 env。
|
|
6
|
-
* @returns codex-proxy → `{ ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_MODEL? }`;其余 → `{}`。
|
|
7
|
-
* ANTHROPIC_MODEL=worker.model,让控制台点选的 gpt 型号真到 proxy(否则 proxy 收到 claude 默认名)。
|
|
8
|
-
* 合并处 `{ ...本函数, ...o.extraEnv }` 里项目 conf 的 WORKER_MODEL(在 o.extraEnv)仍可覆盖。
|
|
9
|
-
*/
|
|
10
|
-
export function workerAnthropicEndpointEnv(worker) {
|
|
11
|
-
if (worker.providerId !== CODEX_PROXY_ID)
|
|
12
|
-
return {};
|
|
13
|
-
const p = getProvider(CODEX_PROXY_ID);
|
|
14
|
-
const baseUrl = worker.baseUrl ?? p?.baseUrl ?? codexProxyBaseUrl();
|
|
15
|
-
// 本地环回,proxy 只绑 127.0.0.1;占位即可(claude-code-proxy 不校验客户端 key)。
|
|
16
|
-
const token = worker.authToken ?? p?.apiKey ?? 'sps-local';
|
|
17
|
-
const env = { ANTHROPIC_BASE_URL: baseUrl, ANTHROPIC_AUTH_TOKEN: token };
|
|
18
|
-
if (worker.model?.trim())
|
|
19
|
-
env.ANTHROPIC_MODEL = worker.model.trim();
|
|
20
|
-
return env;
|
|
21
|
-
}
|
|
22
|
-
//# sourceMappingURL=workerAnthropicEnv.js.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"workerAnthropicEnv.js","sourceRoot":"","sources":["../../../src/core/agents/workerAnthropicEnv.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,WAAW,EAAE,MAAM,kCAAkC,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAEnF,OAAO,EAAE,cAAc,EAAE,CAAC;AAE1B;;;;;GAKG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAyB;IAClE,IAAI,MAAM,CAAC,UAAU,KAAK,cAAc;QAAE,OAAO,EAAE,CAAC;IACpD,MAAM,CAAC,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,IAAI,CAAC,EAAE,OAAO,IAAI,iBAAiB,EAAE,CAAC;IACpE,8DAA8D;IAC9D,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,IAAI,CAAC,EAAE,MAAM,IAAI,WAAW,CAAC;IAC3D,MAAM,GAAG,GAA2B,EAAE,kBAAkB,EAAE,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;IACjG,IAAI,MAAM,CAAC,KAAK,EAAE,IAAI,EAAE;QAAE,GAAG,CAAC,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;IACpE,OAAO,GAAG,CAAC;AACb,CAAC"}
|