@coralai/sps-cli 0.89.13 → 0.89.15

package/docs/help/05-api.md

@@ -0,0 +1,388 @@
+---
+title: 开放 API
+generated: true
+source: src/console/routes/*.ts
+version: 0.89.15
+---
+
+# 开放 API
+
+> ⚠️ **本页由 `scripts/gen-help-api.mjs` 从路由代码扫出,不要手改。**
+> 门禁 `check:help` 会在代码与本页不一致时报红。
+
+共 **177** 条路由(其中 110 条尚无说明)。版本 `0.89.15`。
+
+> ℹ️ 口径:这里**逐条列**(同一路径的不同方法算两条)。门禁 `check:api-docs` 报的是
+> **归一去重后的唯一路径数**,两个数字不相等是正常的 —— 别拿它们互相"对账"。
+
+## 鉴权:两条通道,互不替代
+
+| 通道 | 用法 | 给谁 |
+|---|---|---|
+| **service key** | `X-Sps-Caller: <服务名>` + `Authorization: Bearer <key>` | **平台/服务对接走这条** |
+| console token | `?token=<token>` 或 `Authorization: Bearer <console token>` | 浏览器里的人 |
+
+⚠️ 两条通道的 401 响应体不同(`bad service key` vs `Unauthorized`)——
+排查时据此判断走的是哪条。**服务间调用不要长期借用人的 console token。**
+
+### /api/art · art
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/art/chroma-key` | — |
+| `POST` | `/api/art/rembg` | — |
+| `POST` | `/api/art/clean-alpha` | — |
+| `POST` | `/api/art/residue` | 只读判据:这张图值不值得交给模型(不是"抠得干不干净")。 |
+| `POST` | `/api/art/inspect` | — |
+| `POST` | `/api/art/slice-sheet` | — |
+| `POST` | `/api/art/pack-atlas` | — |
+| `POST` | `/api/art/normalize-sheet` | 🔴 两种 normalize 拆成两个端点(CLI 是 `--mode`): sheet 收单个 `in`,frames 收 `in: string[]` —— 同名字段两种类型正是我们刚在 `pack-atlas` 的 `id` 上踩过 |
+| `POST` | `/api/art/normalize-frames` | — |
+| `POST` | `/api/art/resize` | 🔴 不适用于图集!图集必须走 pack-atlas 的 frameMaxHeight(见上)。 |
+
+### /api/art/pipeline · artPipeline
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/art/pipeline/runs` | — |
+| `GET` | `/api/art/pipeline/runs/:id` | — |
+| `POST` | `/api/art/pipeline/runs/:id/cancel` | — |
+
+### /api/audit · audit
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/audit` | — |
+
+### /api/projects · capabilities
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:project/capabilities` | — |
+
+### /api/projects · cards
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:project/cards` | — |
+| `GET` | `/api/projects/:project/cards/:seq` | — |
+| `GET` | `/api/projects/:project/cards/:seq/prompt` | * 查看 worker 提示词。优先返回**派发时落盘的真实那份**(source=actual,含派发时间); * 该卡还没派过 → 回退到按当前状态**重建的预览**(source=preview)。 |
+| `POST` | `/api/projects/:project/cards` | — |
+| `PATCH` | `/api/projects/:project/cards/:seq` | — |
+| `DELETE` | `/api/projects/:project/cards/:seq` | — |
+| `POST` | `/api/projects/:project/cards/:seq/restore` | 从回收站还原(撤销删除,原号原内容)。 |
+| `GET` | `/api/projects/:project/cards/:seq/rerun-impact` | * 重跑的**波及面**(只读预览)——「从这张卡开始重跑,还会连带哪些卡」 |
+| `POST` | `/api/projects/:project/cards/:seq/reset` | — |
+| `POST` | `/api/projects/:project/cards/:seq/launch` | — |
+
+### /api/channels · channels
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/channels` | 读全量频道配置(console 桥 + adapters)。 |
+| `PUT` | `/api/channels` | 写全量频道配置(前端主从编辑后整存)。 |
+
+### /api/chat · chat
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/chat/sessions` | — |
+| `POST` | `/api/chat/sessions` | — |
+| `GET` | `/api/chat/sessions/:id` | — |
+| `GET` | `/api/chat/sessions/:id/messages` | — |
+| `DELETE` | `/api/chat/sessions/:id` | — |
+| `POST` | `/api/chat/sessions/:id/interactions/push` | * 服务端注入一个交互块 —— **不经模型** |
+| `POST` | `/api/chat/sessions/:id/interactions/:interactionId` | — |
+| `POST` | `/api/chat/sessions/:id/interrupt` | — |
+| `POST` | `/api/chat/sessions/:id/messages` | * POST messages —— 非阻塞发送。ChatService 只管持久化；streamAssistantResponse * 由 Delivery 层起 goroutine，通过 chatBus 广播给 SSE 订阅者。 |
+| `GET` | `/api/chat/:id` | — |
+
+### /api/projects · flow
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:project/flow` | 读项目卡图元数据。无 flow.json → 空(项目还没排布)。 |
+| `PUT` | `/api/projects/:project/flow` | 覆盖式保存。要求项目目录已存在(sps 注册过的项目),避免写出游离目录。 |
+
+### /api/fs · fs
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/fs/browse` | — |
+| `POST` | `/api/fs/mkdir` | ─── POST /mkdir — 在指定目录下新建子目录 ────────────────────────── body（JSON）：{ path: string(绝对路径,须已存在的目录), name: string(单段目录名) }  |
+| `POST` | `/api/fs/upload` | ─── POST /upload — 附件上传 ──────────────────────────────────────── multipart/form-data 字段： - sessionId: string (必)  —— 用于落 |
+| `GET` | `/api/fs/file` | ─── GET /file — 读取附件内容（用于预览） ─────────────────────────── Query： - path:  绝对路径 - sessionId:  关联 session id（用于校验路径是该 sessi |
+
+### /api/gen · gen
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/gen/jobs` | 当前生成任务(running + 最近完成的)。 |
+
+### /api/projects · graph
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:name/graph/status` | 建图状态(节点/边/文件数);未建图 data=null。 |
+| `GET` | `/api/projects/:name/graph/data` | 文件级依赖图数据(渲染用);未建图 data=null。 |
+| `POST` | `/api/projects/:name/graph/build` | 手动全量建图(同步,~秒级;完成回传状态)。 |
+| `POST` | `/api/projects/:name/graph/sync` | 增量同步(只更新变化的文件;未建图则回 409,提示先 build)。 |
+
+### /api · health
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/health` | — |
+| `GET` | `/api/capacity` | — |
+
+### /api/help · help
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/help` | 帮助目录:有哪些篇、各自标题与是否自动生成。 |
+| `GET` | `/api/help/:doc` | 单篇内容(原始 markdown,由前端排版渲染)。 |
+
+### /api/logs · logs
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/logs` | — |
+| `GET` | `/api/logs/sources` | 可切换的日志源列表(固定类 + 每 worker),worker 附运行态状态点。 |
+| `GET` | `/api/logs` | — |
+
+### /api/mcp-tools · mcpTools
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/mcp-tools` | — |
+
+### /api/media-providers · mediaProviders
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/media-providers` | 列 provider(可按 ?capability= 过滤)+ 当前每能力默认。apiKey 脱敏。 |
+| `PUT` | `/api/media-providers` | 新增/编辑。apiKey 留空 = 保留原 key(前端不回传脱敏 key)。 |
+| `DELETE` | `/api/media-providers/:id` | — |
+| `PUT` | `/api/media-providers/default/:capability` | 设某能力的默认 provider/model。 |
+
+### /api/memory · memory
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/memory/scopes` | — |
+| `GET` | `/api/memory/entries` | — |
+| `GET` | `/api/memory/recall` | — |
+| `GET` | `/api/memory/digest` | — |
+| `GET` | `/api/memory/external` | 外部派生智能(agentmemory profile + graph);external 未启用返 {profile:null,graph:null}。 |
+| `GET` | `/api/memory/entries/:id` | — |
+| `POST` | `/api/memory/entries` | — |
+| `DELETE` | `/api/memory/entries/:id` | — |
+| `POST` | `/api/memory/promote` | — |
+| `POST` | `/api/memory/gc` | — |
+
+### /api/model-config · modelConfig
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/model-config/export` | — |
+| `POST` | `/api/model-config/import` | — |
+
+### /api/projects · pipeline
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/projects/:project/pipeline/start` | — |
+| `POST` | `/api/projects/:project/pipeline/stop` | — |
+| `POST` | `/api/projects/:project/pipeline/reset` | — |
+| `GET` | `/api/projects/:project/pipeline/status` | — |
+
+### /serve · play
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/serve/:project/*` | — |
+
+### /preview · preview
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/preview/:sessionId` | 无尾斜杠 → 重定向;否则 `base:'./'` 的相对资源会按上一级解析(丢 sessionId)导致空白页。 |
+| `GET` | `/preview/:sessionId/*` | — |
+
+### /api/processes · processes
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/processes` | — |
+| `GET` | `/api/processes/reclaim` | v0.57 自动回收设置:空闲多少分钟自动停掉 warm 会话(下次发消息 durable resume 续上)。 |
+| `PUT` | `/api/processes/reclaim` | — |
+| `POST` | `/api/processes/:pid/kill` | — |
+
+### /api/projects · projectConfig
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:project/agent` | * `configureProjectAgent` 的**读侧** —— 回报项目当前的 agent 端点/模型(**脱敏**) |
+| `PUT` | `/api/projects/:project/agent` | — |
+| `PUT` | `/api/projects/:project/skills` | — |
+| `PUT` | `/api/projects/:project/media-providers` | * 项目级媒体 provider 注入(`<cwd>/.sps/media-providers.json`,**整体替换**) |
+| `PUT` | `/api/projects/:project/media-providers/gateway` | * 同一份文件的**网关形状**入口:给一把网关 token + 基址,sps **自己**展开成整套条目 |
+| `PUT` | `/api/projects/:project/persona` | * 项目级人设注入(服务化分层 P4·A)—— 人设三件**一次调用给全** |
+| `PUT` | `/api/projects/:project/base-rules` | 存在的理由:消费方(studio)今天**直写**这个文件,而第二步要让 studio 与 sps * **可以不共享文件系统**。写入方换成 sps 之后,工作区退化成 sps 独写 |
+
+### /api/projects · projects
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects` | — |
+| `GET` | `/api/projects/:name` | — |
+| `POST` | `/api/projects` | — |
+| `POST` | `/api/projects/register` | * `POST /api/projects/register` —— **纯登记(认领一棵已存在的项目树)** |
+| `POST` | `/api/projects/:name/scaffold` | * `POST /api/projects/:name/scaffold` —— 把已注册模板落进项目目录 |
+| `DELETE` | `/api/projects/:name/registration` | — |
+| `DELETE` | `/api/projects/:name` | — |
+| `POST` | `/api/projects/:name/relocate` | 迁移工作区到新目录 + 同步所有记着旧 cwd 的地方(gameforge 存量迁移用)。 |
+| `GET` | `/api/projects/:name/conf` | — |
+| `PUT` | `/api/projects/:name/conf` | — |
+| `PATCH` | `/api/projects/:name/conf` | — |
+| `GET` | `/api/projects/:name/pipelines` | — |
+| `GET` | `/api/projects/:name/pipelines/:file` | — |
+| `PATCH` | `/api/projects/:name/pipelines/:file` | — |
+| `POST` | `/api/projects/:name/pipelines` | — |
+| `DELETE` | `/api/projects/:name/pipelines/:file` | — |
+| `PUT` | `/api/projects/:name/pipeline` | — |
+
+### /api/prompts · prompts
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/prompts/generate` | AI 生成提示词:body = { intent }。**异步**:立即返回 { jobId },经 /api/gen/jobs 轮询。 |
+| `GET` | `/api/prompts` | 列表(可选 ?q=关键词 搜索)。 |
+| `GET` | `/api/prompts/:name` | — |
+| `POST` | `/api/prompts` | 新建(body = PromptInput,重名 409)。 |
+| `PUT` | `/api/prompts/:name` | 更新(必须已存在)。 |
+| `DELETE` | `/api/prompts/:name` | — |
+
+### /api/providers · providers
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/providers` | 列两类 provider;apiKey 脱敏(只回 hasKey + 末4位),绝不出全 key。 验证通过的本地官方订阅(claude / codex)作为 builtin 置顶,不可编辑/删除。 |
+| `PUT` | `/api/providers` | 新增/编辑。apiKey 留空 = 保留已有(前端不回传脱敏 key)。 |
+| `DELETE` | `/api/providers/:kind/:id` | — |
+
+### /api/rules · rules
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/rules/:project` | 读项目 repo 根的 AGENTS.md / CLAUDE.md(只读)。 |
+
+### /api/skills · skills
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/skills/create` | AI 创建 skill:body = { name, intent }。**异步**:立即返回 { jobId },经 /api/gen/jobs 轮询。 |
+| `GET` | `/api/skills` | — |
+| `GET` | `/api/skills/updates` | bundled↔HQ 更新检测(静态路径,须在 /:name 前)。 |
+| `POST` | `/api/skills/import` | 导入 skill 到 HQ:body = { name, files: {relPath: content}, overwrite? }。 |
+| `GET` | `/api/skills/:name` | — |
+| `PUT` | `/api/skills/:name` | 编辑保存 skill 正文(整份 SKILL.md 覆盖)。body = { content }。 |
+| `DELETE` | `/api/skills/:name` | 从 HQ 库删除 skill。 |
+| `POST` | `/api/skills/:name/translate` | 中英转换 skill 正文(LLM,frontmatter 不动)。返回 { content } 译文,不落库,前端预览后再 PUT 保存。 |
+| `GET` | `/api/skills/:name/export` | 导出 skill 目录树。 |
+| `GET` | `/api/skills/policy/:project` | 项目 skill 白名单:读当前 policy + 合格宇宙 + 全部 skill(供项目页选择 UI)。 |
+| `PUT` | `/api/skills/policy/:project` | * 写项目 skill 白名单并重投影。body = `{ allow?, deny?, tags? }` |
+| `GET` | `/api/skills/:name/references/:file` | * reference 文件读取保留在 Delivery —— 不进 service，因为这是原始字节的透传，不是 * 领域行为。Phase 3 这里直接读 userSkillsDir 下的文件。 |
+| `POST` | `/api/skills/:name/link` | — |
+| `DELETE` | `/api/skills/:name/link` | — |
+| `POST` | `/api/skills/:name/freeze` | — |
+| `POST` | `/api/skills/:name/unfreeze` | — |
+| `POST` | `/api/skills/sync` | — |
+| `GET` | `/api/skills/links/:project` | — |
+
+### /api/storage · storage
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/storage` | * 当前配置(**脱敏**) |
+| `PUT` | `/api/storage` | 整体替换。缺字段即非法 —— 不做"沿用旧值"的合并,理由见模块头。 |
+| `GET` | `/api/storage/active` | * 同步路径今天生效吗 —— 给运维/自检用的**一个字段**,免得从三种状态自己推 |
+| `GET` | `/api/storage/scope` | * 同步范围声明(**按产品**)。内容由平台写入,sps 只执行 —— * 🔴 这不违反"配置里不放同步什么":那一条禁的是 **sps 把产品知识写死在代码里**, * 而这里是**数据**。反面教材是 coral sidecar 用 |
+| `PUT` | `/api/storage/scope` | 整体替换。缺声明的产品走窄兜底(只同步 `assets/`),而**用了兜底这件事会进日志**。 |
+
+### /api/subagent · subagent
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/subagent/run` | — |
+| `GET` | `/api/subagent/runs/:id` | — |
+| `GET` | `/api/subagent/runs` | — |
+| `POST` | `/api/subagent/runs/:id/abort` | — |
+
+### /api/system · system
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/system/info` | — |
+| `GET` | `/api/system/env` | — |
+| `GET` | `/api/system/env/raw` | — |
+| `PATCH` | `/api/system/env` | — |
+| `GET` | `/api/system/memory` | — |
+| `PUT` | `/api/system/memory` | — |
+| `GET` | `/api/system/agents` | — |
+| `PUT` | `/api/system/agents` | — |
+| `GET` | `/api/system/latest-version` | — |
+| `POST` | `/api/system/upgrade` | — |
+| `POST` | `/api/system/doctor/:project` | v0.50.17：删 shallow /doctor/all，只保留真实的单项目 doctor。 warm-load 项目列表前端走 /api/projects。 |
+| `POST` | `/api/system/client-errors` | 前端错误日志：服务 stderr only，不进 Service |
+
+### /api/templates · templates
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/templates/:id` | 已注册就 200(调用方据此跳过上传),没有就 404 —— 这条是"注册一次、长期命中"的入口。 |
+| `POST` | `/api/templates` | — |
+| `POST` | `/api/templates/register` | * 注册模板 —— **拉取式**:调用方把包传到自己的存储,给 sps 一个**能拉到字节的 URL** |
+| `GET` | `/api/templates` | 上限对外可见 —— 调用方不必靠试错去猜。 |
+
+### /api/tts · tts
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `POST` | `/api/tts` | — |
+
+### /api/projects · workers
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/projects/:project/workers` | — |
+| `GET` | `/api/projects/:project/activity` | * 后端无关的 worker 活动流(claude / openai 归一) |
+| `GET` | `/api/projects/:project/workers/:slot` | — |
+| `POST` | `/api/projects/:project/workers/:slot/kill` | — |
+| `POST` | `/api/projects/:project/workers/:slot/launch` | — |
+| `GET` | `/api/projects/all` | — |
+
+### /stream/projects · sse/projectStream
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/stream/projects/:project` | — |
+
+### /stream/workspace · sse/workspaceStream
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/stream/workspace` | — |
+
+### console/index.ts
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/api/memory-cfg` | 记忆 viewer 配置:设了 SPS_CONSOLE_MEMORY_VIEWER_URL(如 https://mem.coralbot.top,反代 agentmemory 仪表板 :3113)→ 前端 iframe 内嵌该仪表板;没设  |
+| `GET` | `/docs` | — |
+| `GET` | `/docs/*` | 命不中静态文件 → 回 docs 的 404 页(而不是落到 console SPA)。 |
+| `GET` | `/` | — |
+| `GET` | `/*` | — |
+| `GET` | `/` | — |
+| `GET` | `/` | — |
+| `GET` | `/` | — |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coralai/sps-cli",
-  "version": "0.89.13",
+  "version": "0.89.15",
   "description": "SPS CLI — AI-driven development pipeline orchestrator",
   "type": "module",
   "main": "dist/main.js",
@@ -20,12 +20,14 @@
     "test:coverage": "vitest run --coverage",
     "test:e2e": "playwright test",
     "prepublishOnly": "npm run check && npm run build",
-    "check": "npm run build:packages && npm run build:seam-clients && npm run typecheck && npm run typecheck:test && npm run check:api-docs",
+    "check": "npm run build:packages && npm run build:seam-clients && npm run typecheck && npm run typecheck:test && npm run check:api-docs && npm run check:help",
     "dev:selflink": "node scripts/dev-selflink.mjs",
     "smoke:assembly": "node scripts/assembly-smoke.mjs",
     "prepare": "lefthook install || true",
     "build:packages": "for d in packages/*/; do (cd \"$d\" && npx tsc -p tsconfig.json) || exit 1; done",
-    "build:seam-clients": "node scripts/build-seam-clients.mjs"
+    "build:seam-clients": "node scripts/build-seam-clients.mjs",
+    "gen:help": "node scripts/gen-help-commands.mjs && node scripts/gen-help-api.mjs",
+    "check:help": "node scripts/gen-help-commands.mjs --check && node scripts/gen-help-api.mjs --check"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -53,6 +55,7 @@
     "README.md",
     "README-CN.md",
     "CHANGELOG.md",
+    "docs/help",
     "docs/openai-daemon-agent.md"
   ],
   "keywords": [