@coralai/sps-cli 0.65.20 → 0.65.21

package/README-CN.md

@@ -41,20 +41,53 @@ SPS（Smart Pipeline System）驱动 Claude Code worker 走完任务卡 — 写
 ## 安装与初始化
 
 ```bash
-npm install -g @coralai/sps-cli      # 最新 0.57.x
+npm install -g @coralai/sps-cli      # 最新 0.65.x
 sps setup                            # 交互式向导（首次必跑）
 ```
 
 `sps setup` 做的事：
-1. 创建 `~/.coral/` 目录树（`projects/`、`memory/{user,agents}/`）。
-2. 把 bundled skills 复制到 `~/.coral/skills/`。
-3. 询问 `GITLAB_URL` / `GITLAB_TOKEN` / `MATRIX_*`（可跳过），写到 `~/.coral/env`。
-4. 把 user skill symlink 到 `~/.claude/skills/`。
-5. 全局安装 `@agentclientprotocol/claude-agent-acp`。
+1. 创建 `~/.coral/` 目录树（`projects/`、`memory/` 等）。
+2. 把随包分发的 bundled skills 复制到 `~/.coral/skills/`（技能单真源；`~/.claude/skills` 全局目录已不再使用，setup 会顺带清理历史遗留的全量软链）。
+3. 询问 `GITLAB_URL` / `GITLAB_TOKEN` / `MATRIX_*`（可跳过），写到 `~/.coral/env`——文件尾部附**可选配置注释参考**（记忆 / 语音 TTS / daemon 沙箱与并发总闸），与 Console 系统页可视化编辑的是同一个文件。
+4. 钉住代码工作区根 `SPS_WORKSPACES_ROOT`（默认 `~/coral-workspaces`）。
 
-`sps setup --force` 重跑（保留旧值作默认）。**升级 sps-cli 后必须跑 `sps skill sync --force`** 才能拉新版 skill SOP（默认 sync 是非破坏性的，不会覆盖已有 skill）。
+`sps setup --force` 重跑（保留旧值作默认）。
 
-**前置条件**：Node ≥ 18（**建议 ≥ 22** —— 代码图谱功能用了 `node:sqlite`,只有 Node 22+ 才有）；Anthropic API key（或 Claude Pro / Max 订阅）；`claude` CLI 在 PATH。
+**前置条件**：Node ≥ 18（**建议 ≥ 22** —— 代码图谱/记忆索引用了 `node:sqlite`）；claude 后端需 `claude` CLI 登录（或 API key / 订阅）；openai 后端需 `codex login`（订阅）或 `~/.coral/agent-providers.json` 注册表配端点。
+
+### 老旧版本升级：建议清理后重装
+
+跨多个版本的旧安装（尤其 0.6x 之前 / ACP 时代）积累的过期配置键、旧 schema 状态文件、历史软链会带来难排查的怪病，**建议完整清理后重装**，而不是原地升级：
+
+```bash
+# 1) 停干净（顺序：先应用后引擎）
+pm2 delete all 2>/dev/null            # 若曾用 pm2 托管
+sps console --kill 2>/dev/null
+sps agent daemon stop 2>/dev/null
+npm rm -g @coralai/sps-cli
+
+# 2) 状态根整体挪走（= 备份 + 清空一步完成）
+mv ~/.coral ~/.coral.bak-$(date +%m%d)
+rm -rf ~/coral-workspaces              # 自动建的会话工作区（有要保留的项目先自行迁出）
+
+# 3) ~/.claude 只清 sps 塞入的部分，别整目录删（那是 claude CLI 的登录凭据和个人配置）
+rm -rf ~/.claude/skills                # 旧版本的全量软链污染
+
+# 4) 重装
+npm i -g @coralai/sps-cli && sps setup
+```
+
+**清理前的保留清单**（有价值就从备份里拷回）：
+
+| 内容 | 位置 | 说明 |
+|---|---|---|
+| claude CLI 登录态 | `~/.claude/`（凭据/个人配置） | 不要删整目录 |
+| codex 订阅授权 | `~/.codex/auth.json` | 过期需重新 `codex login` |
+| 记忆库 | 备份中的 `memory/` | 数据资产，按需拷回 `~/.coral/memory/` |
+| 自定义技能 | 备份中的 `skills/` 里非内建部分 | sps 内建技能随包自动重装，无需拷回 |
+| 全局 env 里手填的密钥 | 备份中的 `env` | 对照新模板把有效键誊回（旧模板含已废弃键，勿整文件拷回） |
+
+**版本纪律（升级后必做）**：CLI / console / daemon 三者必须同版本——升级 npm 包不会重启运行中的进程，需 `sps agent daemon restart`（先确认无在飞任务）+ 重启 console + 浏览器硬刷新。嵌入 sps 的上层平台（如 coral-platform）需各自升级依赖并重启自己的进程。
 
 ---
 

package/README.md

@@ -41,20 +41,45 @@ The headline of **v0.59** is a redesigned **Console**: a voice-first home (speak
 ## Install & setup
 
 ```bash
-npm install -g @coralai/sps-cli      # latest 0.59.x
+npm install -g @coralai/sps-cli      # latest 0.65.x
 sps setup                            # interactive wizard (must run once)
 ```
 
 `sps setup`:
-1. Creates `~/.coral/` directory tree (`projects/`, `memory/{user,agents}/`).
-2. Copies bundled skills → `~/.coral/skills/`.
-3. Asks for `GITLAB_URL` / `GITLAB_TOKEN` / `MATRIX_*` (optional) → writes `~/.coral/env`.
-4. Symlinks user skills → `~/.claude/skills/`.
-5. Installs `@agentclientprotocol/claude-agent-acp` globally.
+1. Creates the `~/.coral/` directory tree (`projects/`, `memory/`, …).
+2. Copies bundled skills → `~/.coral/skills/` (the single skills source; the global `~/.claude/skills` dir is no longer used — setup also prunes legacy link pollution there).
+3. Asks for `GITLAB_URL` / `GITLAB_TOKEN` / `MATRIX_*` (optional) → writes `~/.coral/env`, with a commented reference of optional keys (memory / voice TTS / daemon sandbox & concurrency gate) at the end — the same file the Console System page edits visually.
+4. Pins the workspaces root `SPS_WORKSPACES_ROOT` (default `~/coral-workspaces`).
 
-Re-run safe with `sps setup --force` (keeps existing values as defaults). After upgrading sps-cli later, run **`sps skill sync --force`** to pull updated skill SOPs (default sync is non-destructive — won't overwrite existing skills).
+Re-run safe with `sps setup --force` (keeps existing values as defaults).
 
-**Prerequisites**: Node ≥ 18 (**≥ 22 recommended** — the code-graph feature uses `node:sqlite`, only available in Node 22+); an Anthropic API key (or Claude Pro / Max subscription); `claude` CLI in PATH.
+**Prerequisites**: Node ≥ 18 (**≥ 22 recommended** — code-graph & memory index use `node:sqlite`); for the claude backend a logged-in `claude` CLI (or API key / subscription); for the openai backend `codex login` (subscription) or endpoints registered in `~/.coral/agent-providers.json`.
+
+### Upgrading a stale install: clean reinstall recommended
+
+Installs that are many versions behind (especially pre-0.6x / ACP-era) accumulate retired config keys, old-schema state files, and legacy symlinks that cause hard-to-debug oddities. Prefer a full clean reinstall over an in-place upgrade:
+
+```bash
+# 1) Stop everything (apps first, then the engine)
+pm2 delete all 2>/dev/null            # if you used pm2
+sps console --kill 2>/dev/null
+sps agent daemon stop 2>/dev/null
+npm rm -g @coralai/sps-cli
+
+# 2) Move the state root aside (backup + wipe in one step)
+mv ~/.coral ~/.coral.bak-$(date +%m%d)
+rm -rf ~/coral-workspaces              # auto-created session workspaces (move out anything you keep first)
+
+# 3) In ~/.claude only remove what sps put there — never the whole dir
+rm -rf ~/.claude/skills                # legacy full-link pollution from old versions
+
+# 4) Reinstall
+npm i -g @coralai/sps-cli && sps setup
+```
+
+**Keep-list before wiping** (copy back from the backup as needed): claude CLI credentials (`~/.claude/`, don't delete the dir), codex subscription auth (`~/.codex/auth.json`; re-run `codex login` if expired), your memory store (`memory/` → `~/.coral/memory/`), custom skills (bundled ones reinstall automatically), and any hand-filled secrets from the old `env` — transcribe valid keys into the new template rather than copying the whole file (old templates contain retired keys).
+
+**Version discipline after any upgrade**: CLI / console / daemon must run the same version — upgrading the npm package does not restart running processes. Run `sps agent daemon restart` (check for in-flight work first), restart the console, and hard-refresh the browser. Platforms embedding sps (e.g. coral-platform) upgrade their own dependency and restart their own process.
 
 ---
 

package/dist/console-assets/assets/{ShowcasePage-lGZ30wQv.js → ShowcasePage-BAs5NC0m.js}

@@ -1,4 +1,4 @@
-import{c as st,r as Te,j as u,u as _n,S as fs,P as hs,C as ps,E as ms,L as Yt,A as gn,a as yn}from"./index-j79_HSyU.js";/**
+import{c as st,r as Te,j as u,u as _n,S as fs,P as hs,C as ps,E as ms,L as Yt,A as gn,a as yn}from"./index-BVd14n7I.js";/**
  * @license lucide-react v0.544.0 - ISC
  *
  * This source code is licensed under the ISC license.