75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# 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`](https://gitea.com/gitea/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`](../schemas/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 里声明的字段。
|