spx

superpowers-vscode 工作流 CLI 工具，给 cc/codex agent 用的工单 / PR 操作薄包装，Gitea 和 GitHub 仓库用同一套命令。

安装

make install
# 把 $HOME/.local/bin 加进 PATH

仓库与凭据

spx 读 git remote get-url origin，按 host 决定连哪种仓库（--host / --repo 可覆盖）：

origin host	仓库	token 来源
`github.com`	GitHub（API `https://api.github.com`）	`gh auth token --hostname github.com`；取不到就先运行 `gh auth login`
其它任何 host	Gitea（API `<host>/api/v1`）	`tea` 配置 `~/.config/tea/config.yml` 里 URL 与 origin 同 host 的 login；该 login 的 token 为空时用环境变量 `GITEA_TOKEN` 补上；tea 里没有这个 host 的 login 就报错，要先运行 `tea login add`

tea 用 keyring 存 token（v0.10+ 默认行为）时，配置文件里的 login 没有 token，可以设 GITEA_TOKEN 补上。GITEA_TOKEN 只会发给 tea 里登录过的 host，origin 指向别的 host 时 spx 直接报错，不会把它发出去：

export GITEA_TOKEN=...

用法

spx issue create --title "新功能 X" --spec docs/specs/x.md --plan docs/plans/x.md
spx issue marker --issue 79 --type plan --value docs/plans/issue-79/plan.md
spx issue view --issue 79 --comments
spx issue state get --issue 79
spx issue state merge --issue 79 --state-json '{"column":"review"}'
spx pr view --pr 73
spx pr create --title "修复 X" --body-file /tmp/pr.md --head feature/x [--base main]
spx pr review-comment --pr 73 --body "审查意见: ..."

issue view 输出编号、标题、正文、状态、作者、指派人、链接；--comments 附带评论，但不含 state 评论。
pr view 输出编号、标题、正文、状态、是否已合并、head/base 的分支与 SHA、作者、链接。
pr create 的 --body / --body-file 必须给一个；不给 --base 时取仓库默认分支。输出新 PR 的编号和链接。
pr review-comment 在两种仓库上都走 issue 评论接口（PR 与工单共用编号）。

全局 flag：

--repo OWNER/REPO 默认从当前 git origin 推断
--host HOST 如 github.com 或 https://gitea.example.com，默认从当前 git origin 推断；同时给 --host 和 --repo 时不需要 git 仓库
--json JSON 输出
--cwd PATH repo 探测的工作目录，默认 .

Marker 约定

issue/PR body 里用 HTML 注释行携带 spx 元数据：

<!-- spx:spec=docs/specs/foo.md -->
<!-- spx:plan=docs/plans/foo.md -->
<!-- spx:review=1 -->

spx issue marker 会做增量更新（已存在则替换那一行，不存在则追加），其他类型的 marker 不会被动到。

State 评论约定

工单的 state JSON（字段见 state-json.schema.json）存在评论里，每次合并追加一条新评论。写出格式是网页上不可见的 HTML 注释，JSON 紧凑一行，< > & 转义成 \u003c \u003e \u0026，保证正文里不会出现 -->：

<!-- spx-state
{"column":"review","specFile":"docs/specs/foo.md"}
-->

读取时从最新一条评论往前找，第一条有效的胜出。兼容三种形式：上面的隐藏格式、旧 YouTrack 格式（ 后接 JSON）、旧的裸 JSON 对象。内容必须是 JSON 对象，且至少带一个 schema 里声明的字段。

README.md Unescape Escape

spx

安装

仓库与凭据

用法

Marker 约定

State 评论约定

README.md