From 5e62842cfae248e6fe4bc79a1c6865ca7784e6a4 Mon Sep 17 00:00:00 2001 From: cruldra Date: Mon, 19 Oct 2026 08:27:26 +1100 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(vscode):=20README=20?= =?UTF-8?q?=E6=94=B9=E6=88=90=20GitHub=E3=80=81Gitea=20=E4=B8=A4=E7=A7=8D?= =?UTF-8?q?=E4=BB=93=E5=BA=93=E9=80=9A=E7=94=A8=EF=BC=8C=E8=A1=A5=20spx=20?= =?UTF-8?q?=E6=96=B0=E5=91=BD=E4=BB=A4=E5=92=8C=20webhook=20=E9=85=8D?= =?UTF-8?q?=E7=BD=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- vscode/README.md | 48 +++++++++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/vscode/README.md b/vscode/README.md index d30d407..5ea0704 100644 --- a/vscode/README.md +++ b/vscode/README.md @@ -1,11 +1,11 @@ # Superpowers-clurdra -把 Gitea 工单变成 VS Code 里的看板，每张卡片背后挂着一组 AI 会话（头脑风暴 → 实施 → 审查 → 测试），从建工单到合并 PR 全程在编辑器里完成。 +把 GitHub 或 Gitea 仓库的工单变成 VS Code 里的看板，每张卡片背后挂着一组 AI 会话（头脑风暴 → 实施 → 审查 → 测试），从建工单到合并 PR 全程在编辑器里完成。 -- 数据源：**Gitea** 工单（主）+ **YouTrack** 工单（可选镜像） +- 数据源：**GitHub / Gitea** 仓库工单（主，按工作区 git origin 的 host 区分：`github.com` 是 GitHub，其余都按 Gitea）+ **YouTrack** 工单（可选镜像） - 执行者：`claude` CLI 负责规划 / 实施 / 测试 / 提交，`codex` 负责审查 -- 状态存放：工单评论里的一段 state JSON，多人、多机共享；本机专属字段（会话 id、worktree 路径等）留在本机 -- 联动：Gitea webhook 推回本机，PR 开了自动审查、审查意见自动注入实施终端、合并后自动清 worktree 和分支 +- 状态存放：工单评论里的一段 state JSON（隐藏注释格式，网页上看不到），多人、多机共享；本机专属字段（会话 id、worktree 路径等）留在本机 +- 联动：仓库 webhook 推回本机，PR 开了自动审查、审查意见自动注入实施终端、合并后自动清 worktree 和分支 ## 工作流 @@ -43,39 +43,49 @@ | `claude` | 规划、实施、测试、冲突解决、提交、PR 摘要（找不到时会提示常见位置 `~/.local/bin`） | | ECC 插件（`ecc@ecc`） | Claude Code 插件，头脑风暴 / 实施会话用它的 `/ecc:grilling` `/ecc:spec` `/ecc:plan` `/ecc:tdd` 和审查子代理 | | `codex` | 审查会话（开启自动审查时必需） | -| `tea` | `spx` 从 `~/.config/tea/config.yml` 读取 Gitea host + token；审查 prompt 也用 `tea pulls` 看 PR | -| `spx` | 本仓库 `cli/` 里的 Go CLI，见下文 | +| `gh` | GitHub 仓库必需：插件和 `spx` 都现取 `gh auth token` 当凭据，先在终端 `gh auth login` | +| `tea` | Gitea 仓库：`spx` 从 tea 配置（`~/.config/tea/config.yml`，先 `tea login add`）里 host 匹配的 login 取 token | +| `spx` | 本仓库 `cli/` 里的 Go CLI，提示词里查工单、查 PR、发起 PR、写状态都用它，见下文 | | `opencli` | prompts 里统一以 `opencli spx ...` 调用 spx | | `tar` | 移交时打包 / 解包会话文件 | | `bash` | 执行钩子脚本 | -- 仅支持 Gitea（`https:///api/v1`），不支持 GitHub。 +- 支持 github.com 和自建 Gitea（`https:///api/v1`）；不支持 GitHub Enterprise，`github.com` 以外的 host 一律按 Gitea 处理。 - POSIX 环境。删 worktree 前扫 `/proc` 杀占用进程只在 Linux 生效，macOS 上降级为直接删。 - 依赖内置 `vscode.git` 扩展检测工作区改动（提交按钮）。 ### 安装 spx ```bash -cd cli && make install # 编译到 bin/spx 并安装到 ~/.local/bin/ +cd cli && make install # 编译到 bin/spx 并安装到 ~/.local/bin/（这个目录要在 PATH 里） ``` -`spx` 命令： +`spx` 按当前目录 git origin 的 host 选仓库：`github.com` 走 GitHub，凭据取 `gh auth token`；其余走 Gitea，凭据取 tea 配置里 host 匹配的 login，没有时回退环境变量 `GITEA_TOKEN`（tea 把 token 存在系统钥匙串里时就要设它）。 | 命令 | 作用 | |---|---| -| `spx issue create --title ... [--body-file F] [--spec P] [--plan P] [--state-json J]` | 建工单并认领；spec / plan 同时写 body marker 和 state JSON | -| `spx issue marker --issue N --type spec\|plan --value P` | 更新 body 里的 `` / `` 并同步 state | +| `spx issue create --title T (--body B\|--body-file F) [--spec P] [--plan P] [--state-json J\|--state-file F]` | 建工单；spec / plan 同时写 body marker 和 state JSON | +| `spx issue view --issue N [--comments]` | 看工单标题、正文、状态、作者、指派人、链接；`--comments` 附带评论（不含 state 评论） | +| `spx issue marker --issue N --type spec\|plan\|prototype --value P` | 更新 body 里的 `` 等 marker 并同步 state | | `spx issue state get --issue N` | 读 state JSON | -| `spx issue state merge --issue N --state-json J` | 浅合并写回（按 schema 校验） | -| `spx pr review-comment --pr N --body-file F` | 发审查评论，自动加 `` 标记 | +| `spx issue state merge --issue N (--state-json J\|--state-file F)` | 浅合并写回（按 schema 校验） | +| `spx pr view --pr N` | 看 PR 标题、正文、状态、是否已合并、head / base 分支与 SHA、作者、链接 | +| `spx pr create --title T (--body B\|--body-file F) --head BRANCH [--base BRANCH]` | 发起 PR，`--base` 缺省为仓库默认分支；描述里写 `Closes #N` 看板才能把 PR 关联到工单 | +| `spx pr review-comment --pr N (--body B\|--body-file F)` | 发审查评论，自动加 `` 标记 | -全局 flag：`--repo OWNER/REPO`（默认从 origin 推断）、`--host`、`--json`、`--cwd`。tea 用 keyring 存 token 时需设 `GITEA_TOKEN` 环境变量。 +全局 flag：`--repo OWNER/REPO`、`--host`（默认都从 origin 推断）、`--json`、`--cwd`。 -### Gitea 配置 +### 仓库与 webhook 配置 -1. 打开看板 → 设置 → 认证，填 Gitea host 和 Personal Access Token（存 VS Code SecretStorage）。状态栏会常驻显示当前身份 `spx: `，token 失效变红；Gitea 邮箱和 `git config user.email` 不一致时会警告。 -2. 在仓库上配一个 webhook 指向本机的 `http://<公网地址>/webhook`（本机默认监听 `17421`，通常经 frp 之类反代暴露），事件至少勾选 **Issues、Issue Comment、Pull Request、Push**。建议设置 secret 并在插件设置里同填，否则不校验签名。 -3. webhook 会广播到每个开发者的机器，只有工单 assignee 所在的机器执行副作用（写状态、触发审查、注入终端），其他机器只刷新 UI。实施即认领，所以正常情况下不用手动指派。 +1. 认证： + - GitHub 仓库：终端里 `gh auth login` 即可，插件每次现取 `gh auth token`，自己不存 GitHub token。 + - Gitea 仓库：打开看板 → 设置 → 认证，填 Personal Access Token（存 VS Code SecretStorage）。Gitea 邮箱和 `git config user.email` 不一致时会警告。 + - 状态栏常驻显示当前身份 `spx: `，凭据失效变红。 +2. 在仓库上配一个 webhook 指向本机的 `http://<公网地址>/webhook`（本机默认监听 `17421`，通常经 frp 之类反代暴露）。Content type 必须选 **application/json**，表单编码的请求会被拒收（返回 415，日志里有提示）。建议设置 Secret 并在插件设置的 `webhookSecret` 里同填，插件按 `X-Hub-Signature-256: sha256=` 校验，不填则不校验签名。 + - **GitHub**：仓库 Settings → Webhooks → Add webhook。Payload URL 填上面的地址，Content type 选 `application/json`，Secret 同插件设置；事件选「Let me select individual events」，勾 **Issues、Issue comments、Pull requests、Pushes**。保存后 GitHub 发一个 `ping`，Recent Deliveries 里是 200 就通了。 + - **Gitea**：仓库设置 → Web 钩子 → 添加 Gitea 钩子。目标 URL 填上面的地址，HTTP 方法 `POST`，POST Content Type 选 `application/json`，密钥文本同插件设置（Gitea 同样发 `X-GitHub-Event` 和 `X-Hub-Signature-256`）；触发条件选自定义事件，勾 **Issues、Issue Comment、Pull Request、Push**。 +3. 一个公网地址可以给多个仓库共用。本机开着多个 VS Code 窗口时只有一个窗口占得到端口，它把验过签的事件转给其余窗口，每个窗口只处理自己工作区 origin 对应仓库的事件；占端口的窗口关掉后，其余窗口几秒内接手端口。 +4. webhook 会广播到每个开发者的机器，只有工单 assignee 所在的机器执行副作用（写状态、触发审查、注入终端），其他机器只刷新 UI。实施即认领，所以正常情况下不用手动指派。 ### YouTrack（可选） @@ -142,7 +152,7 @@ prompts 在 `prompts/*.md`，随 VSIX 一起安装，改完即生效，也可在 | | `prDiffSummaryProfilePath` | `deepseek-v4-pro` | 「改动」说明 / PR 变更摘要用的 profile；未配置时生成失败 | | | `codexModel` / `codexReasoningEffort` | 空 | 审查会话的 codex `-c` 覆盖；空 = 用 codex 自己的 config | | 网络 | `webhookPort` | `17421` | 本机 webhook 端口 | -| | `webhookSecret` | 空 | Gitea webhook secret，空 = 不校验签名 | +| | `webhookSecret` | 空 | 仓库 webhook 的 Secret（GitHub / Gitea 通用，校验 `X-Hub-Signature-256`），空 = 不校验签名 | | | `autoReview` | `true` | 全局自动审查；工单级 `autoReview` 可覆盖 | | | `profilesDirectory` | 空 | Claude profiles 目录，空 = 自动探测 | | YouTrack | `youtrackBaseUrl` / `youtrackProjectShortName` / `youtrackCloseCommand` | 空 | 见上文 |