RSP

简体中文

English

简体中文

English

外观

CLI 参考 ​

环境中已经可以直接调用 RSP 时使用 rsp <command>。接入和维护时通过 npx -y @oevery/rsp@latest <command> 调用当前稳定包。

接入与 Skills ​

text
rsp init --agents-mode <mode>   搭建 .rsp/ 并确保 AGENTS.md 中有 RSP 入口
rsp init --with-project-setup   同时创建 .rsp/changes/project-setup.md
rsp update                      刷新受管项目文件，不更新随包 Skills
rsp doctor [--fix]              检查接入健康；只修复安全且结果确定的问题
rsp skills                      在双 TTY 中打开项目 Skill 管理器
rsp skills list [--json]        列出随包 Skills 与精确安装状态
rsp skills install [name] [--dry-run] [--force]
                                安装默认套件或一个指定的可选 Skill

rsp update 不刷新已安装且归属软件包的 Skills；需要单独运行 rsp skills install。替换内容不同的选定 Skill 目录，或移除已识别的过时软件包自有标识时，必须显式使用 --force。

rsp doctor --fix 只报告真实的文件系统修改；健康项目会返回 fixed: []，并说明无需安全修复。

在生成索引兼容迁移中，rsp update 只会移除根 .rsp/specs/INDEX.md，或任意 .rsp/specs/**/00-index.md 中元数据明确标识为 RSP 生成 Specs 索引、且 source_dir 与所在目录精确一致的文件。它会在修改前预检全部候选；如果迁移后的直接 Specs 检查失败，则回滚所有隔离文件。项目自有、不可读或被并发替换的保留路径会让 update 停止，不覆盖也不删除内容。全新初始化与 rsp add spec 永远不会创建生成索引。

除非显式使用 --fix，rsp doctor 始终只读。它会报告接入和文件系统问题，包括仍需 rsp update 的可识别索引，并且不会创建隐藏工作流状态。

Specs 与工作创建 ​

text
rsp specs [path] [--json [--compact]]
                                派生当前树，或查看一个精确的已返回路径
rsp specs --search <literal> [--limit 1..100] [--excerpt 40..1000]
                                以有界摘录搜索当前 Specs 与 Decision Records
rsp add spec <name>             创建供当前文件直接查询的 Spec
rsp create <name> [summary]     创建按 kind 提示的 Change
rsp group create <name> [goal] 创建不进入聚焦状态的 Group Brief
rsp group close <name>         归档已完成的 Group Brief
rsp group reopen <name> --reason <text>
                                把一份保留的 Group Brief 恢复为未完成工作

rsp specs 直接读取当前常规 Markdown，不依赖 daemon、数据库或生成导航文件。树、详情与搜索 JSON 会标识 checkout、精确项目相对源路径、文档种类、限制与诊断。搜索采用不区分大小写的字面匹配，默认最多返回 20 条、摘录上限为 240 个 Unicode code points；Specs 树无效或保留索引路径包含项目自有内容时会安全失败。迁移后，该命令就是生成索引的受支持导航替代。进行实质决策或修改前，仍需重新读取返回的源文件。

在下一次兼容发布的一个兼容周期内，rsp create --lite、--lite=true 与 --lite=false 仍会被接受。每种形式都会输出有界弃用提示，并创建同一套标准 kind-aware 六章节 Change；其他 --lite= 值会在修改前失败，且不存在单独的 lite 模板。

聚焦、就绪与生命周期 ​

text
rsp focus <name> [--capsule-file <path|->]
                                把 Change 标记为当前工作，并可选替换 capsule
rsp unfocus <name>              从聚焦集合移除未完成的 Change
rsp show <name|--focused> [--json [--compact]] [--verbose]
rsp ready <name> [--json [--compact]] [--verbose]
rsp archive <name>              把已完成 Change 移入归档目录
rsp reopen <name> --reason <text> [--from <archive-path>]
                                恢复未满足验收条件的已归档 Change

rsp focus --capsule-file 接受常规文件或标准输入（-）。空输入保留有效的空 marker。每次新的非空写入都必须是严格 Focus Capsule v1：一个位于开头的 <!-- rsp-focus:v1 -->、空行、恰好一个非空单行 Current、Evidence、Next，以及至多一个非空单行 Resume check。未知非空行或字段、重复或缺失字段、无效 UTF-8、不安全输入及超过 4096 UTF-8 bytes 的内容都会在原子替换前被拒绝，并保留原 marker。

已有的有界、无版本 UTF-8 内容继续按兼容模式读取。rsp check 发出稳定的 focus_capsule_legacy warning，且不会把这些文本声明为结构化 recovery。对于 focused Change，rsp show --json 对空内容或 legacy 内容返回 recovery: null，对 legacy 内容在 warnings 中返回稳定条目，并把有效 v1 投影为 { version, current, evidence, next, resumeCheck, authoritative: false }。该投影只读，不授予权限，也不声明证据新鲜度。

rsp ready 和 rsp show 还会提供必须完成门禁、可选覆盖警告与语义审查信号。未完成的 Tasks、Required Verify 或 blocker 会产生 archiveReady: no；未完成的 Optional 验证只保留警告。完成门禁被阻断时，rsp archive 会失败且不移动 Change。rsp archive --dry-run 作为 rsp ready 已弃用的兼容别名保留，不会移动 Change。

本地 Git 交付 ​

text
rsp commit --message-file <path> [--json]

rsp commit 基于当前已经暂存的边界创建一个本地 commit。存在进行中的 merge、cherry-pick、revert、rebase 或 sequencer 操作时会拒绝提交。它不会主动 stage、push、tag、发布、amend、创建修复提交或执行跨分支集成。消息文件必须包含真实换行；字面量 \n 会被拒绝。Git 通过直接子进程的 stdin 路径接收消息，并使用 --cleanup=verbatim。提交完成后，RSP 会核对完整存储消息和实际提交路径，并返回提交前后 HEAD、存储消息、已提交路径与工作树剩余路径。如果提交后的消息或路径不匹配，命令会报告失败，但保留已经创建的 commit，后续历史修复仍需单独授权。

检查与查询 ​

text
rsp ui [--lang auto|en|zh-CN]   打开只读交互式面板
rsp status [--focused|--blocked|--stale <days>] [--json [--compact]] [--verbose]
rsp check [--focused] [--json [--compact]] [--verbose]
rsp specs [path|--search <literal>] [--json [--compact]]
rsp history [filters] [--json [--compact]]
rsp history <work-ref> [--json [--compact]]

在真实的交互式终端中，不带子命令的 RSP 会打开与 rsp ui 相同的面板。CI、管道、重定向流与 TERM=dumb 接收静态命令输出。

普通 rsp status 是人类和 AI 的默认语义视图：以紧凑形式保留当前聚焦、Change 与 Group 摘要、进度、阻塞项和派生的下一步。在交互式终端中，使用 rsp 或 rsp ui 打开面板。只有需要精确机器字段时才使用 rsp status --json；默认投影保留当前工作、摘要、依赖、波次和结构化诊断。使用 rsp status --json --verbose 可补回过滤器、下一步、归档趋势和运行时诊断。有效项目配置请使用 rsp config 或 rsp config --json。

status 从完整工作树派生精确的依赖、就绪工作、阻塞项与稳定波次。check 校验 Change 结构，并警告未完成的占位符或待澄清标记。history 直接读取保留的归档文件，默认返回 20 条、最多 100 条；筛选参数包括 --limit、--since、--until、--kind、--group 与 --search。

产生 JSON 的命令——status、show、ready、check、doctor、specs 和 history——支持 --json --compact，把相同投影序列化成一行并以 LF 结尾。对 status，--json --verbose 会恢复辅助展示字段和运行时诊断。不带 --json 使用 --compact 无效。

面板快捷键 ​

  • Tab：切换“工作”“Specs”与“历史”视图；“工作”用明确类型标签合并展示 Change 和 Group。
  • 在 Specs 中按 s 提交有界字面正文搜索；Enter 打开经过安全终端渲染的 Markdown 详情，↑/↓ 或 k/j 按渲染后的行滚动。Frontmatter 会隐藏，raw HTML 不会执行。
  • 在 Work 或 History 详情中按 v，可在语义化的 Status/Summary 与精确有界 Markdown 文档之间切换。表格会适配终端宽度，严格 RSP metavariable 保持惰性展示。
  • 方向键或 j/k：移动选择。
  • /：筛选当前范围。
  • Enter：打开全宽详情。
  • r：刷新当前范围。
  • ?：帮助。
  • q、Ctrl-C 或顶层 Esc：退出。

面板只本地化自身标签，不会本地化 CLI 帮助、文本输出、JSON、路径、命令、Skills 或已有产物。