@coralai/sps-cli 0.51.11 → 0.52.0

package/README-CN.md

@@ -1,544 +1,218 @@
-# SPS CLI — AI Agent 流水线编排器
+# SPS CLI
 
-[![npm](https://img.shields.io/npm/v/@coralai/sps-cli)](https://www.npmjs.com/package/@coralai/sps-cli) [![license](https://img.shields.io/npm/l/@coralai/sps-cli)](../../LICENSE)
+[![npm](https://img.shields.io/npm/v/@coralai/sps-cli)](https://www.npmjs.com/package/@coralai/sps-cli) [![license](https://img.shields.io/npm/l/@coralai/sps-cli)](./LICENSE)
 
-> **English**：[README.md](./README.md)
+> English docs: [README.md](./README.md)
 
-**v0.51.3**
+## 1. 简介
 
-SPS（Smart Pipeline System）驱动 Claude Code worker 走完任务卡 — 写代码、commit、push、QA、合并，全自动。三种模式：
+SPS（Smart Pipeline System）是一个开源的 **AI Agent Harness**（智能体执行壳），把"一句话需求"自动驱动到"已审、已提交、可部署的产出"。任务以卡片形式经过多阶段流水线 —— 计划、执行、审核、交付 —— 每个 prompt 都自动注入项目级知识库。
 
-| 模式 | 命令 | 适用场景 |
-|---|---|---|
-| **Harness** | `sps agent` | 零配置 — 与 Claude 一次性对话或多轮 chat。无需建项目、无需 PM。 |
-| **Pipeline** | `sps tick <project>` | 自动化 — 卡片按 YAML 走完 stage 直到 Done。 |
-| **Console** | `sps console` | Web UI — 看板、日志、worker、项目、聊天（v0.44+）。 |
-
-v0.51 头条特性是 **Wiki 知识库** — per-project 可选，结构化互链 page（modules / concepts / decisions / lessons / sources），自动注入 worker prompt 的 5 层检索结果。详见 [doc-28](../../docs/design/28-wiki-system.md) 和 [`ATTRIBUTION.md`](./ATTRIBUTION.md)。
-
----
-
-## 目录
+### 7×24 小时无人值守开发
 
-- [安装与初始化](#安装与初始化)
-- [Harness 模式（`sps agent`）](#harness-模式sps-agent)
-- [Console 模式（`sps console`）](#console-模式sps-console)
-- [Pipeline 模式（`sps tick`）](#pipeline-模式sps-tick)
-- [卡片生命周期](#卡片生命周期)
-- [Memory + Wiki](#memory--wiki)
-- [Skills](#skills)
-- [命令参考](#命令参考)
-- [项目配置（conf）](#项目配置conf)
-- [目录布局](#目录布局)
-- [架构](#架构)
-- [Troubleshooting](#troubleshooting)
+把任务丢进 Backlog，Harness 全天候不间断推进 —— 计划、编码、测试、提交、开 MR，只在真的卡住时才升级人工。你睡觉时流水线在 tick；第二天早会看到的是已合并的 commit。SPS 存在的意义是：一个人能在不守在聊天窗口前的情况下，跑出一个研发团队的工作量。
 
----
+### 不止软件 —— 通过 skill 扩展到任何行业
 
-## 安装与初始化
+Pipeline、Skills、知识层是刻意做成通用的。任何能表达成"任务进 → 已审输出出"的流程，换一套 skill bundle 就能跑：
 
-```bash
-npm install -g @coralai/sps-cli      # 最新 0.51.x
-sps setup                            # 交互式向导（首次必跑）
-```
+- **会计** —— 发票录入 → 归类 → 账务对账 → 期末结账
+- **自媒体** —— 选题调研 → 起草 → 审核 → 发布
+- **AI 视频生成** —— 脚本 → 分镜 → 渲染 → 剪辑 → 审核
+- **写作** —— 调研 → 提纲 → 初稿 → 修订 → 发布
+- **其他工作流** —— 阶段在 YAML 里定义，skill 在 markdown 里写，Harness 运行它们
 
-`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`。
+一个 CLI、一套控制台、一个基于文件系统的工作流。不绑死任何 AI 厂商。
 
-`sps setup --force` 重跑（保留旧值作默认）。**升级 sps-cli 后必须跑 `sps skill sync --force`** 才能拉新版 skill SOP（默认 sync 是非破坏性的，不会覆盖已有 skill）。
+![CLI](docs/screenshots/01-cli-banner.png)
 
-**前置条件**：Node ≥ 18；Anthropic API key（或 Claude Pro / Max 订阅）；`claude` CLI 在 PATH。
+## 2. 核心概念
 
----
+### Harness（执行壳）
+围绕 AI Agent 的长生命进程外壳：daemon、supervisor、传输层、profile 管理、文件系统任务生命周期。Agent 只关心写代码，基础设施由 Harness 接管。
 
-## Harness 模式（`sps agent`）
+### Pipeline（流水线）
+每个任务是一张**卡片**，流经 `Backlog → Planning → Todo → Inprogress → QA → Done` 各阶段。每阶段有独立 prompt、工具白名单、出场条件 —— 全部 YAML 可配。
 
-直接和 Claude 对话，单次或多轮。无项目、无 PM、无 git。
+### Skills（技能指派）
+阶段按需分派**原子 skill** 来驱动每个任务执行 —— 内建 `sps-pipeline`、`wiki-update`、`git-commit`，加 24 个开发 skill 与 persona skill。Skill 可组合而不会撑爆 system prompt，Harness 只加载当前阶段需要的部分。
 
-```bash
-# 一次性
-sps agent "解释这个 repo"
-sps agent --output summary.md "总结架构"
-
-# 多轮（daemon 后端，会话持久化）
-sps agent --chat                              # 交互 REPL
-sps agent --chat --name reviewer              # 命名会话，下次可继续
-sps agent status                              # 列活跃会话
-sps agent close --name reviewer
-
-# Profile + 上下文文件
-sps agent --profile reviewer "审这个模块" --context src/auth.ts --context src/auth.test.ts
-sps agent --system "你是发布工程师" "规划 v0.52 切版"
-
-# Verbose
-sps agent --verbose "为什么构建失败"
-```
+### Memory（记忆系统）
+跨会话持久化"非显然、可复用"事实的三层 markdown 文件库。全部在 `~/.coral/memory/`，Pipeline 模式下由 `StageEngine` 自动注入到每个 Worker prompt。
 
-**`--profile <name>`**：查 `~/.coral/skills/dev-worker/references/<name>.md`，作为 system prompt 注入。（注意区别 `sps skill add` — 那是项目级 skill 链接。）
-
-**Built-in agent**：仅 `claude`（Codex / Gemini 支持已在 v0.38 移除）。Worker 通过 ACP JSON-RPC over stdio 与 `claude-agent-acp` 通信。
+| 层 | 路径 | 作用域 |
+|---|---|---|
+| **User** | `~/.coral/memory/user/` | 跨项目用户偏好（编码风格、语言、工作习惯） |
+| **Agent** | `~/.coral/memory/agents/<id>/` | 单个 Agent 实例观察到的人机交互模式 |
+| **Project** | `~/.coral/memory/projects/<name>/` | 项目级约定、架构决策、教训、外部资源指针 |
 
-**Agent skill 由 Claude Code 自己加载**：`~/.claude/skills/` 是 `claude` 自己扫的目录 — 含 `sps-pipeline`、`sps-memory`、`wiki-update`、以及 24 个 dev / persona skill。Skill description 触发懒加载，harness 模式不需要 SPS 主动注入。
+四种条目类型 —— `convention`（永不衰减）、`decision`（缓慢衰减）、`lesson`（30 天衰减）、`reference`（永不衰减）。每层一个扁平目录装 `*.md` + 一份 `MEMORY.md` 索引。Agent 按需读、有发现时回写 —— 稀疏的私有飘移；与下文密集的团队共享 Wiki 互补。
 
-**Daemon cwd 注意**：`sps console` 和 `sps agent --chat` 启动 session daemon（`~/.coral/sessions/daemon.sock`），daemon 启动时捕获 `process.cwd()` 作为所有 chat worker 的默认工作目录。要切目录必须重启 daemon：`sps agent daemon stop && sps agent daemon start`，从目标目录发起。
+### Knowledge Base（知识库）—— LLM Wiki
 
----
+借鉴 Andrej Karpathy 的 "LLM Wiki" 思路：让 Agent 把项目知识**提炼**成持久化的结构化 wiki，而不是每次会话都重新读源码、重新踩坑、重新发现已有抽象。
 
-## Console 模式（`sps console`）
+**问题**：AI Agent 每次从零探索代码库会烧 token、漏掉非显然的决策、反复撞同一个坑。代码里的知识大多是**隐式的** —— 藏在 commit 上下文里、藏在设计权衡里、藏在没有回写到源码的事故复盘里。
 
-本机 web UI，打包进二进制。`~/.coral/console.lock` 单实例保证。
+**Wiki 方案**：Worker 把代码、设计文档、完成的卡片持续提炼成原子化、互相 wikilink 的页：
 
-```bash
-sps console                          # 打开 http://127.0.0.1:4311
-sps console --port 5000
-sps console --no-open                # 不自动开浏览器
-sps console --kill                   # 停止运行中的 console
-sps console --dev                    # vite dev 模式（开发用）
-```
-
-页面：
-
-| 路径 | 用途 |
+| 页类型 | 装什么 |
 |---|---|
-| `/projects` | 项目列表 + 状态摘要 |
-| `/projects/new` | 新建项目（含 Wiki 开关，v0.51+） |
-| `/projects/<n>` | Pipeline 编辑器 + conf 编辑器 + 删除 |
-| `/board` | 看板（列内独立滚动，v0.51.1+） |
-| `/workers` | 跨项目聚合 worker 仪表板 |
-| `/logs` | 实时 SSE 日志查看器 |
-| `/skills` | User-level skill 管理 |
-| `/system` | 全局设置 + daemon 状态 |
-| `/chat` | Agent 聊天（多会话，持久化） |
-
-技术栈：Hono server on `127.0.0.1:4311`、chokidar 推 SSE 给 React 19 + Vite + Tailwind v4 + shadcn/ui 前端。设计系统：Pastel Neubrutalism，规范在 [`console/DESIGN.md`](./console/DESIGN.md)。
+| `modules/` | 每个模块做什么、怎么被使用 |
+| `concepts/` | 反复出现的模式与架构原语 |
+| `decisions/` | 某个选择背后的原因（带版本锚定） |
+| `lessons/` | 事故中浮现的非显然教训 |
+| `sources/` | 用户拖入 `.raw/` 的外部材料（PDF/文章/转录）的密集摘要 |
 
----
+**自维护**：每张卡完成后，Worker 自动回写新增 lessons / module 变更，无需人工维护。SOP 在 `skills/wiki-update/`，按 4 问题判定（改了模块？做了决策？踩了坑？看到模式？）—— 四个 NO 就不写。
 
-## Pipeline 模式（`sps tick`）
+**自检索**：每张新卡的 prompt 自动注入 5 层（~2K token），Worker 启动即带知识：
 
-全自动卡片驱动。**单 worker，单卡，串行**。每卡走 YAML 定义的若干 stage（如 `develop → review → Done`）；失败 → halt pipeline 直到你移除 `NEEDS-FIX` 标签。
+- **L1** `hot.md` —— 最近上下文（~500 token）
+- **L2** `index.md` 节选 —— top-30 页 TL;DR（~500 token）
+- **L3** pinned 页 —— 卡片 frontmatter 显式引用
+- **L4** skill-tag 匹配 —— 与卡片激活 skill 相符的页
+- **L5** BM25F 关键词回退 —— title/desc top-3
 
-### 建项目
+**复利效应**：每张完成的卡都在累加知识。项目跑得越久，Worker 越懂这个项目，不再需要重读原代码。老 Worker 留下的 lesson 是新 Worker 的免费先验 —— Wiki 就是项目的**机构记忆**。
 
-```bash
-sps project init my-app
-# 或用 Console /projects/new — 表单含 Wiki 开关（v0.51+）
-```
-
-会问：项目目录、合并分支、最大 worker 数、ACK 超时、可选 GitLab 远程、可选 Matrix 房间。
-
-生成：
+**Obsidian 兼容**：存在 `<repo>/wiki/`，用 `[[wikilink]]` 语法 + 扁平 YAML frontmatter —— 把目录用 Obsidian 打开就有 graph view、双向链接、全文搜索。
 
-```
-~/.coral/projects/my-app/
-├── conf                              # mode 600 — 当前活动配置
-├── conf.example                      # 字段全参考（自动生成）
-├── pipelines/
-│   ├── project.yaml                  # 默认 1-stage（develop → Done）
-│   └── sample.yaml.example           # YAML 完整带注释参考
-└── pipeline_order.json               # 当前 active pipeline 指针
-```
+### Agent Mode（代理接入）
+SPS 是**代理无关**的。任何能读 skill + 执行 shell 的编码代理 —— Claude Code、Codex、OpenClaw、你自己写的 —— 都可以通过内置 `sps-pipeline` skill 来驱动 SPS。Harness 适配代理，不是反过来。接入新代理只需扔一个 skill 文件，SPS 代码无需改动。见 [§6](#6-支持列表) 接入矩阵。
 
-在目标 repo（PROJECT_DIR）下：
+## 3. 控制台
 
-```
-.claude/CLAUDE.md                     # Worker 规则（自动安装）
-.claude/skills/                       # 从 ~/.coral/skills/ symlink
-.claude/settings.local.json           # Claude Code 本地配置
-wiki/                                 # 若 WIKI_ENABLED — 见 doc-28
-ATTRIBUTION.md                        # 若 WIKI_ENABLED
-```
-
-### 运行
+启动本地 Web UI：
 
 ```bash
-sps tick my-app                      # 前台 tick 循环
-sps pipeline start my-app            # 别名
-sps pipeline stop my-app             # 优雅停（别名 sps stop my-app）
-sps stop --all                       # 停所有运行中的 tick
-sps status                           # 看所有项目
+sps console                      # 打开 http://127.0.0.1:4311
+sps console --port 5000          # 自定义端口
+sps console --no-open            # 不自动开浏览器
+sps console --kill               # 停掉运行中的 console
 ```
 
-### Pipeline YAML
-
-`~/.coral/projects/<n>/pipelines/project.yaml` — stage 单一来源。
-
-```yaml
-mode: project
-git: true                            # false = 非代码项目，无 git 操作
-stages:
-  - name: develop
-    profile: fullstack
-    on_complete: "move_card Review"
-    on_fail: { action: "label NEEDS-FIX", halt: true }
-  - name: review
-    profile: reviewer
-    on_complete: "move_card Done"
-    on_fail: { action: "label REVIEW-FAILED", halt: true }
-```
+一条命令，无需额外服务 —— 看板、Chat、Skills、Workers、日志、项目全在一处。
 
-关键规则：
-1. `mode: project` 是状态机式 pipeline；`mode: steps` 是一次性脚本，用 `sps pipeline run <name>` 触发。
-2. 每个 stage 的 `on_complete` 必须指向**下一个** stage 的目标 state。
-3. 最后一个 stage `on_complete: "move_card Done"`。
-4. 别写 `agent:` 字段 — v0.38+ 起被静默忽略（Claude 是唯一 worker）。
-5. `trigger` 和 `card_state` 按 stage 位置自动推导。
+**看板 —— 卡片流转一目了然**
 
-字段全集见 `~/.coral/projects/<n>/pipelines/sample.yaml.example`（自动生成，注释丰富）或 [doc-17](../../docs/design/17-pipeline-configuration-design.md)。
+![控制台 — 看板](docs/screenshots/02-kanban.png)
 
----
+**Chat —— 多轮对话 + 工具调用流式渲染**
 
-## 卡片生命周期
+![控制台 — Chat](docs/screenshots/03-chat.png)
 
-```
-Backlog → Todo → Inprogress → [QA / Review] → Done
-   ↑↓                  ↓ 失败
-Planning           NEEDS-FIX (halt)
-(人工暂存，v0.51.9+)
-```
+**Skills —— 内置与项目级 skill 管理**
 
-**v0.51.10**：按调用方区分默认入场状态。
-- **`sps card add`（CLI / agent / 直接调 API）** → **Backlog**（自动跑）
-- **Console "新卡片" 表单（人在 UI 操作）** → **Planning**（暂存，等用户拖到 Backlog 派发）
+![控制台 — Skills](docs/screenshots/04-skills.png)
 
-CLI 用户想暂存：`sps card add ... --draft`。Console 用户想立即跑：勾"立即派发执行"。
-卡片严格按 seq 排序；不再有 pipeline_order.json。
-
-默认状态（可在 YAML `pm.card_states` 自定义）。
-
-```bash
-sps card add <p> "标题" "描述"
-sps card add <p> "T" "D" --skills python,backend --labels feature
+**Workers —— 容量、运行时、按阶段日志**
 
-sps card dashboard <p>               # CLI 表格
-                                     # console: /board?project=<n>
+![控制台 — Workers](docs/screenshots/05-workers.png)
 
-sps card mark-started <p> <seq>     # 由 Claude Code UserPromptSubmit hook 调用
-sps card mark-complete <p> <seq>    # 由 Claude Code Stop hook 调用
-
-sps reset <p>                        # 重置非 Done 卡
-sps reset <p> --card 5,6,7
-sps reset <p> --all                  # 全重置含 Done + worktree + branch
-```
-
-### 卡片标签词典
-
-| 标签 | 含义 | 设置者 |
-|---|---|---|
-| `AI-PIPELINE` | 进入 pipeline 的必备标签 | 创建时由用户加 |
-| `STARTED-<stage>` | ACK 信号 — Claude 收到了 prompt | UserPromptSubmit hook |
-| `COMPLETED-<stage>` | Worker 完成了某 stage | Stop hook |
-| `CLAIMED` | StageEngine 占了 worker slot | Engine |
-| `NEEDS-FIX` | Worker 失败；pipeline halt | Engine |
-| `BLOCKED` | 外部依赖阻塞；pipeline 跳过 | 用户 |
-| `WAITING-CONFIRMATION` | Worker 等用户输入 | Engine |
-| `STALE-RUNTIME` | Inprogress 超时 | MonitorEngine |
-| `ACK-TIMEOUT` | Claude 在 `WORKER_ACK_TIMEOUT_S` 内没 ACK | MonitorEngine |
-| `skill:<name>` | 强制加载某 skill | 用户 |
-| `conflict:<domain>` | 同 domain 内串行 | 用户 |
-
-活动 stage 会在 `~/.coral/projects/<p>/runtime/worker-<slot>-current.json` 写 marker 文件（v0.50.21+），Stop hook 读它判断 worker 刚刚做完哪张卡。
-
----
-
-## Memory + Wiki
-
-两套互补的持久化系统，都自动注入 worker prompt。
-
-| | **Memory** | **Wiki**（v0.51+） |
-|---|---|---|
-| 路径 | `~/.coral/memory/{user,agents,projects/<p>}/` | `<repo>/wiki/`（per-project，进 repo） |
-| 格式 | 平铺 markdown + YAML frontmatter | 5 类 page，zod 校验的 frontmatter |
-| 互链 | 无（平铺索引） | `[[type/Title]]` wikilink |
-| 自动注入 | prompt 的 `knowledge` 段 | `wikiContext` 段（5 层检索） |
-| 开关 | 默认开（`ENABLE_MEMORY=false` 关） | per-project（`WIKI_ENABLED=true` 开） |
-| 适合 | 个人偏好、零散决策、坑 | 结构化项目知识：modules、concepts、decisions、lessons |
-
-### Memory CLI
+## 4. 安装
 
 ```bash
-sps memory list <p>                            # 看项目 memory 索引
-sps memory list                                # 看全局 user + agents
-sps memory context <p> --card <seq>            # 预览注入内容
+# 安装
+npm install -g @coralai/sps-cli
+sps setup                       # 一次性交互向导
 
-sps memory add <p> --type convention --name "API 用 camelCase" \
-  --description "REST 接口用 camelCase" --body "..."
+# 更新
+npm update -g @coralai/sps-cli
+sps skill sync --force          # 升级后拉最新 skill SOP
 ```
 
-类型：`convention`（不衰减）、`decision`（缓慢衰减）、`lesson`（30 天衰减）、`reference`（不衰减）。
-
-### Wiki CLI（`WIKI_ENABLED=true` 时）
+### 本地编译
 
 ```bash
-sps wiki init <p>                              # scaffold wiki/（开了 toggle 时建项目自动跑）
-sps wiki update <p>                            # 看 source diff
-sps wiki update <p> --finalize                 # worker 写完 page 后刷新 manifest
-sps wiki check <p>                             # lint：orphan / dead-link / fm-gap / stale
-sps wiki list <p> --type lesson --tag pipeline
-sps wiki get <p> lessons/Stop-Hook-Race
-sps wiki status <p>                            # source ↔ manifest ↔ pages 差异
-sps wiki add <p> ~/notes.md --category transcripts
-sps wiki read <p> "<query>"                    # 预览 5 层检索
+git clone https://github.com/edwardZhang/sps-cli.git
+cd sps-cli
+npm install
+npm run build                   # tsc + console 静态资源
+npm link                        # `sps` 命令指向本地编译版
 ```
 
-5 层检索：hot.md / index 节选 / pinned / skill-tag / BM25F keyword。类型优先级：lesson = 3、decision = 3、concept = 2、module = 1、source = 1。Token 预算硬上限 ~2000。
+### 前置要求
 
-Worker SOP：[`skills/wiki-update/SKILL.md`](./skills/wiki-update/SKILL.md)（300 行，单一来源）。
+- **Node.js ≥ 18**
+- **本地已经能正常运行的 Claude Code。** 先跑一下 `claude --help`，能跑通就 OK。SPS **不限制**你 Claude Code 怎么登录：
+  - Anthropic API key（`ANTHROPIC_API_KEY`）
+  - Claude Pro / Max 订阅
+  - 第三方 API gateway / 代理
+  - 任何其他 Claude Code 支持的鉴权方式
 
----
+  SPS 通过 Agent Client Protocol 启动 `claude`，继承你已配的凭证。SPS 这边不需要再单独配 API key。
 
-## Skills
+## 5. 快速运行
 
-User-level skill 在 `~/.coral/skills/`（28 个 bundled，`sps setup` 时从 npm 包拷贝）。Symlink 到 `~/.claude/skills/`，Claude Code 自动加载。
+### Step 1 —— 跑一次安装向导（只需一次）
 
 ```bash
-sps skill list                                 # 列可用 + 项目链接状态
-sps skill add <name> --project <p>             # symlink 到 <repo>/.claude/skills/
-sps skill remove <name> --project <p>
-sps skill freeze <name> --project <p>          # symlink → 真实副本（项目可定制）
-sps skill unfreeze <name> --project <p>        # 改回 symlink
-sps skill sync                                 # ① bundled (npm 包) → ~/.coral/skills/
-                                               # ② ~/.coral/skills/ → ~/.claude/skills/
-sps skill sync --force                         # ⭐ 覆盖已存在的 user skill（升级 sps-cli 后用）
+sps setup
 ```
 
-Bundled skill 列表（v0.51.3）：
-
-- **开发类（23 个）**：`frontend`、`frontend-developer`、`backend`、`backend-architect`、`typescript`、`golang`、`rust`、`python`、`java`、`kotlin`、`swift`、`mobile`、`database`、`database-optimizer`、`qa-tester`、`security-engineer`、`architecture-decision-records`、`coding-standards`、`debugging-workflow`、`devops`、`devops-automator`、`git-workflow`、`code-reviewer`
-- **Worker profile（3 个）**：`dev-worker`、`tax-worker`、`reviewer`（通过 `--profile` 引用）
-- **SPS 专用（5 个）**：`sps-pipeline`、`sps-memory`、`wiki-update`
+向导会做：
+- 创建 `~/.coral/{projects,memory,sessions,skills}/` 目录树
+- 把内置 skill 复制到 `~/.coral/skills/`，并软链到 `~/.claude/skills/` 让 Claude Code 能看到
+- 全局安装 `@agentclientprotocol/claude-agent-acp`，让 `claude` 能走 ACP 被驱动
+- 可选写 `~/.coral/env`（GitLab token、Matrix 通知等 —— 全部可选）
 
----
+可重复运行：`sps setup --force` 把已有值作为默认值。升级 sps-cli 后，跑 **`sps skill sync --force`** 拉最新 skill SOP。
 
-## 命令参考
+### Step 2 —— 用 agent 冒烟测试（不需要项目）
 
 ```bash
-# Setup & 项目
-sps setup [--force]
-sps project init <name>
-sps project doctor <name> [--fix] [--json] [--reset-state] [--skip-remote]
-sps doctor <name> --fix              # 别名
-
-# Pipeline
-sps tick <project> [--json]
-sps pipeline start|stop|status|reset|workers|board|card|logs|list|run|use [project] [args]
-sps pipeline run <name> "<prompt>"   # 用于 mode: steps pipeline
-sps pipeline tick <project>          # 单次 StageEngine pass
-sps scheduler tick <project>         # v0.51.9 起 dormant（保留接口给 tick 编排器）
-sps qa tick <project>                # QA → Done 收尾
-sps monitor tick <project>           # 健康探测（ACK timeout、stale）
-sps pm scan <project>                # 从磁盘重建卡片索引
-
-# 卡片
-sps card add <p> "title" ["description"] [--skills a,b] [--labels x,y]
-sps card dashboard <p>
-sps card mark-started <p> [seq] [--stage <name>]
-sps card mark-complete <p> <seq> [--stage <name>]
-
-# Worker
-sps worker ps <project>
-sps worker dashboard <project>
-sps worker kill <project> <seq>
-sps worker launch <project> <seq>
-
-# 状态 / 日志
-sps status [--json]
-sps stop <project> [--all]
-sps reset <project> [--all] [--card N,N,N]
-sps logs [project] [--err] [--lines N] [--no-follow]
-
-# Memory
-sps memory list [project] [--agent <id>]
-sps memory context <project> [--card <seq>] [--agent <id>]
-sps memory add <project> --type <T> --name "title" [--body "content"]
-
-# Wiki（v0.51+）
-sps wiki init <p>
-sps wiki update <p> [--finalize] [--json]
-sps wiki read <p> "<query>" [--skills a,b] [--pinned id1,id2] [--budget N]
-sps wiki check <p> [--json] [--fix]
-sps wiki add <p> <file> [--category <name>] [--no-ingest]
-sps wiki list <p> [--type T] [--tag T] [--json]
-sps wiki get <p> <pageId> [--json]
-sps wiki status <p> [--json]
-
-# Skill
-sps skill list [--project <p>]
-sps skill add <name> [--project <p>]
-sps skill remove <name> [--project <p>]
-sps skill freeze <name> [--project <p>]
-sps skill unfreeze <name> [--project <p>]
-sps skill sync [--force]
-
-# Console
-sps console [--port N] [--host H] [--no-open] [--dev] [--kill]
-
-# Agent
-sps agent "<prompt>" [--profile <p>] [--system "..."] [--context file] [--output file] [--verbose]
-sps agent --chat [--name <session>]
-sps agent status|close|list|add [args]
-sps agent daemon start|stop|status
-
-# Hook（由 Claude Code 调用，不是用户）
-sps hook stop
-sps hook user-prompt-submit
-
-# ACP 控制（高级 debug 用）
-sps acp <ensure|run|prompt|status|stop|pending|respond> <project> [args]
+sps agent "解释这个仓库"          # 单次问答
+sps agent --chat                # 多轮 REPL，会话持久化
 ```
 
-任何命令后加 `--help` 看具体用法；支持的命令加 `--json` 输出结构化结果。
-
----
+跑通这一步说明 Claude Code 鉴权 OK，SPS 也接好了。
 
-## 项目配置（conf）
+### Step 3 —— 启动控制台
 
-文件位置 `~/.coral/projects/<name>/conf`（shell `export VAR="value"` 语法，mode 600）。完整字段参考自动生成在 `~/.coral/projects/<name>/conf.example`。
-
-| 字段 | 默认 | 说明 |
-|---|---|---|
-| `PROJECT_NAME` | （必填） | 内部 id |
-| `PROJECT_DIR` | （必填） | repo 绝对路径 |
-| `GITLAB_PROJECT` | — | `user/repo`（可选，用 GitLab API 时必填） |
-| `GITLAB_PROJECT_ID` | — | 数字 ID（GitLab 才需，按路径首次 MR 时自动解析） |
-| `GITLAB_MERGE_BRANCH` | `main` | Worker push 的目标分支 |
-| `PM_TOOL` | `markdown` | **v0.42 起只支持 `markdown`**。卡片在 `~/.coral/projects/<n>/cards/<state>/<seq>.md` |
-| `PIPELINE_LABEL` | `AI-PIPELINE` | 卡片进入 pipeline 必备标签 |
-| `MR_MODE` | `none` | `none`（直接 push）/ `create`（开 MR，需要 `GITLAB_PROJECT_ID`） |
-| `WORKER_TRANSPORT` | `acp-sdk` | 固定，不要改 |
-| `MAX_CONCURRENT_WORKERS` | `1` | Slot 数；同一项目内卡仍是串行 |
-| `MAX_ACTIONS_PER_TICK` | `3` | 单次 tick 可领多少新任务 |
-| `INPROGRESS_TIMEOUT_HOURS` | `2` | 超时后 MonitorEngine 标 STALE-RUNTIME |
-| `WORKER_ACK_TIMEOUT_S` | `300` | 派发后等 STARTED-<stage> 标签的最长时间（v0.50.24 提到 5min） |
-| `WORKER_ACK_MAX_RETRIES` | `1` | ACK 超时后最多重试次数 |
-| `MONITOR_AUTO_QA` | `true` | 检测到 stale runtime 时自动迁到 QA |
-| `CONFLICT_DEFAULT` | `serial` | 卡上无 `conflict:` 标签时的兜底策略 |
-| `MATRIX_ROOM_ID` | — | 项目级 Matrix 覆盖 |
-| `WORKTREE_DIR` | `~/.coral/worktrees/<p>` | Worker 工作树根 |
-| `DEFAULT_WORKER_SKILLS` | — | 逗号分隔；卡上无 `profile:` 也无 `card.skills` 时兜底 |
-| `ENABLE_MEMORY` | `true` | `false` 跳过 prompt 里的 memory 写指引 |
-| **`WIKI_ENABLED`** | 未设（关） | **v0.51+**：`true` 启用 wiki context 注入 + reminder |
-| `COMPLETION_SIGNAL` | `done` | Stop hook 监听的完成关键词 |
-
-全局凭证 `~/.coral/env`：`GITLAB_URL`、`GITLAB_TOKEN`、`GITLAB_SSH_HOST`、`GITLAB_SSH_PORT`、`MATRIX_HOMESERVER`、`MATRIX_ACCESS_TOKEN`、`MATRIX_ROOM_ID`。`sps setup` 写或 `vim` 改。
-
----
-
-## 目录布局
-
-```
-~/.coral/                              # 用户全局状态
-├── env                                # 全局凭证（mode 600）
-├── skills/                            # User-level skill（从 npm 同步）
-├── memory/{user,agents,projects}/     # 3 层 memory 存储
-├── projects/<name>/                   # 项目状态
-│   ├── conf                           # 项目配置（mode 600）
-│   ├── conf.example                   # 字段全参考（自动生成）
-│   ├── pipelines/{project,*}.yaml     # Pipeline 定义
-│   ├── pipeline_order.json            # 当前 active pipeline 指针
-│   ├── runtime/state.json             # Worker slot + 当前卡状态
-│   ├── runtime/worker-<slot>-current.json   # Per-slot 卡 marker（v0.50.21+）
-│   ├── runtime/tick.lock              # tick 锁
-│   ├── runtime/acp-state.json         # ACP 会话状态
-│   ├── cards/<state>/<seq>.md         # 卡片文件（markdown PM 后端）
-│   ├── cards/seq.txt                  # 序列号
-│   ├── logs/                          # 每次 tick 的日志
-│   └── pm_meta/                       # 卡片索引
-├── sessions/                          # Agent daemon（chat 会话）
-│   ├── daemon.sock daemon.pid
-│   └── chat-sessions/<id>.json        # 持久化 chat 会话
-├── console.lock                       # console 单实例 guard
-└── worktrees/<project>/<seq>/         # 每张活动卡一个 worktree
-
-<目标 repo>/                           # 你的项目 repo
-├── .claude/
-│   ├── CLAUDE.md                      # Worker 规则（项目相关 + SPS 注入）
-│   ├── settings.local.json            # Claude Code 本地配置
-│   ├── skills/                        # 从 ~/.coral/skills/ symlink
-│   └── hooks/{start,stop}.sh          # 生命周期 hook（call sps）
-├── wiki/                              # 若 WIKI_ENABLED — 见 doc-28
-└── ATTRIBUTION.md                     # 若 WIKI_ENABLED
+```bash
+sps console                     # http://127.0.0.1:4311
 ```
 
----
-
-## 架构
-
-4 层服务架构（v0.50+）：
+### Step 4 —— 跑一条 pipeline
 
-```
-Delivery (commands/, console/routes/)        参数解析 + I/O 编排（薄）
-  ↓
-Service (services/)                          ProjectService / ChatService / PipelineService /
-                                             SkillService / WikiService — Result<T> + DomainEvent
-  ↓
-Domain (engines/)                            SchedulerEngine / StageEngine / MonitorEngine /
-                                             CloseoutEngine / EventHandler — pipeline 逻辑
-  ↓
-Infrastructure                               WorkerManager（单 worker）、ACPWorkerRuntime、
-  (manager/, providers/, daemon/)            sessionDaemon、TaskBackend、RepoBackend
+```bash
+sps project init my-app --repo /path/to/repo    # 初始化项目
+sps card add my-app "加一个登录按钮"               # 加一张卡
+sps tick my-app                                 # 推进活跃卡片一个阶段
 ```
 
-引擎职责：
+**TUI Dashboard** —— 跨项目紧凑视图（`sps status`）：
 
-- **SchedulerEngine** — v0.51.9 起 dormant（卡 add 直接进 Backlog；Planning 是人工暂存）。class 保留为 no-op，给 tick 编排器接口稳定。
-- **StageEngine** — 驱动卡走 stage；构造 prompt（skill + projectRules + memory + **wikiContext** + task description + **wikiUpdateReminder**）；通过 ACP 拉起 worker。
-- **MonitorEngine** — ACK 超时检测、stale runtime、自动 QA 提升。
-- **CloseoutEngine** + **EventHandler** — 完成卡的收尾。
+![Card Dashboard](docs/screenshots/06-dashboard.png)
 
-**单 worker 是刻意设计**：v0.37.2 已删除多 worker 并发代码。不要提议"加并行模式" — 架构依赖串行执行保证状态一致。要更高吞吐，跑多个项目并行。
+## 6. 支持列表
 
-深入阅读：
-- [doc-27：Service Layer Architecture](../../docs/design/27-service-layer-architecture.md) — 当前架构
-- [doc-26：Console Architecture](../../docs/design/26-console-architecture.md) — Console 内部
-- [doc-28：Wiki System](../../docs/design/28-wiki-system.md) — Wiki 设计
-- [doc-13：Development Guardrails](../../docs/design/13-development-guardrails.md) — 贡献者硬规则
-- [doc-17：Pipeline Configuration](../../docs/design/17-pipeline-configuration-design.md) — YAML 字段语义
-- [docs/design/](../../docs/design/) — 完整设计树（v0.15-v0.32 时代的多数文档已标 HISTORICAL）
+SPS-CLI 是 shell 驱动的，任何能读 skill + 执行命令的编码代理都可以把它当任务 harness 用。我们随仓库发 `skills/sps-pipeline/` —— 把它放进代理的 skill 目录，代理就立即学会了 SPS 完整命令面（cards、pipeline tick、wiki、项目初始化、daemon 生命周期）。
 
----
+| 代理 | 接入方式 |
+|---|---|
+| **Claude Code** | ✅ `sps skill sync` 把 `sps-pipeline` 软链到 `~/.claude/skills/`；按描述匹配自动加载 |
+| **Codex** | ✅ 把 `skills/sps-pipeline/SKILL.md` 放进 Codex 的 skill 目录 |
+| **OpenClaw** | ✅ 一样 —— 让它的 skill loader 指向 `skills/sps-pipeline/` |
+| **Harness Agent** | ✅ 同模式 —— skill 内容代理无关 |
+| **其他任何编码代理** | ✅ 只要能读指令 + 执行 shell，就能驱动 SPS |
 
-## Troubleshooting
+skill 是纯 markdown —— 抄它、改它、fork 它。SPS 管编排，代理管意图。
 
-```bash
-sps doctor <project> --fix           # ★ 第一招
-sps logs <project> --err             # 只看 stderr / 错误
-sps reset <project> --card <seq>     # 重置卡死的卡
-sps reset <project> --all            # 全项目重置
-
-# Worker / daemon 问题
-sps worker ps <project>
-sps agent daemon status              # chat daemon 还在不？
-sps agent daemon stop && sps agent daemon start    # 重启（清旧 cwd）
-
-# Wiki 问题
-sps wiki check <project>
-sps wiki status <project>
-```
-
-常见问题：
+## 7. 致谢
 
-| 现象 | 原因 / 修复 |
-|---|---|
-| Pipeline halt 在 `NEEDS-FIX` | 打开失败的卡，修问题，移除标签。Console 上 2 步搞定。 |
-| Worker 启动不了 | 先 `sps worker ps`，再 `sps logs --err`。多半是 Claude API key 缺、或 `claude-agent-acp` adapter 没装（`sps setup` 重装它）。 |
-| 卡片卡在 Planning | 缺 `AI-PIPELINE` 标签。`sps card add` 自动加；外部加的需手动补。 |
-| 每张卡都 ACK timeout | Claude 冷启动慢（skill / memory 多）。conf 里调高 `WORKER_ACK_TIMEOUT_S`（v0.50.24 起默认 300s）。 |
-| Console 数据陈旧 | SSE 可能掉了；刷新页面；不行就 `sps console --kill && sps console`。 |
-| Wiki context 不注入 | 检查 `WIKI_ENABLED=true` 在 conf 里、`wiki/WIKI.md` 存在。conf 开了但 scaffold 缺时 StageEngine 会 warn。 |
-| 升级后 skill SOP 不更新 | `sps skill sync --force`（默认 sync 会跳过已存在的）。 |
-| Daemon chat 用了错的 cwd | Daemon 启动时锁 cwd。`sps agent daemon stop && cd <repo> && sps agent daemon start`。 |
+SPS 站在以下开源项目肩上：
 
----
+- **Andrej Karpathy** —— ["LLM Wiki"](https://gist.github.com/karpathy) 心智模型，是 SPS 知识层的根基
+- **Anthropic Claude Agent SDK** —— ACP 传输层、子代理基础设施
+- **kepano / claude-obsidian**（MIT）—— Wiki 架构、manifest、hot cache。完整归属见 [ATTRIBUTION.md](./ATTRIBUTION.md)
+- **hono · chokidar · zod · yaml · vitest · biome** —— 运行时与工具链
 
-## 许可证 & 致谢
+## 8. 开源协议
 
-MIT，见 [`LICENSE`](../../LICENSE)。
+[MIT](./LICENSE)
 
-Wiki 系统（v0.51+）~70% 借鉴 [claude-obsidian](https://github.com/kepano/claude-obsidian)（MIT）— 三层架构、manifest 增量、hot cache、ingest 流程、contradiction callout、wikilink。SPS 专属 30%：5 类 page、`sources={card,commit,path}`、5 层 reader、`sps wiki check` exit gate。心智模型来自 Karpathy "LLM Wiki" gist。
+## 9. Copyright
 
-完整归属见 [`ATTRIBUTION.md`](./ATTRIBUTION.md)。
+Copyright (c) 2026 Coral AI