superwork/vscode/cli/README.md

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 用 keyring 存 token（v0.10+ 默认行为）时，可以设 GITEA_TOKEN 作为回退：

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 格式（<!--spx-state--> 后接 JSON）、旧的裸 JSON 对象。内容必须是 JSON 对象，且至少带一个 schema 里声明的字段。