@namewta/speculo 2.0.5 → 2.1.0

package/skills-hub/coding/gitea-repo/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: gitea-repo
+description: 管理已确认 Gitea/Forgejo 实例的 issue、PR、标签、里程碑和 Release。用于该平台的仓库查询、具名变更和 API 排错；不处理 GitHub/GitLab 或普通 Git 提交。
+license: MIT
+compatibility: Requires Python 3.10+, confirmed Gitea/Forgejo host and scoped credentials; API operations need network access.
+metadata:
+  author: NAMEWTA
+  wta-format-reviewed: '2026-10-06'
+---
+# Gitea / Forgejo 仓库 API
+
+## 输入与输出契约
+
+定位 host、owner/repo、操作、具名对象与授权范围；可从已确认的上下文复用，不重复索取。只有 remote、还未确认平台时先做只读辨认；没有目标 host 就不读取令牌。
+
+查询返回对象编号、筛选条件、页数/覆盖和失败页；写操作另给请求动作、返回 ID 与独立读回状态。未取得响应与明确失败分开，输出中不含令牌。
+
+示例：“列出这台 Forgejo 的 owner/repo 所有关闭 issue，不做修改。”应进入本技能；“给 GitHub 项目提交一个修复 PR。”不应由本技能接管。
+
+需要 Python 3.10+、目标实例网络和相应权限。技能目录以本文件位置为准；Windows 检查 python / py -3，macOS/Linux 检查 python3，路径参数始终作为独立参数传入，不用 shell 字符串拼接。
+
+```bash
+python3 "$SKILL_DIR/scripts/gitea_api.py" --host https://gitea.example.com --repo owner/repo issue list
+```
+
+## 定位与信任
+
+实例按显式 --host、GITEA_HOST、已确认 remote 定位；仓库按 --repo、GITEA_REPO、remote 定位。非 GitHub remote 不证明它是 Gitea；SSH 端口也不等于 API 端口。凭据必须绑定确认的 host，不能从一个实例转发到另一个实例或重定向目标。
+
+令牌优先 GITEA_TOKEN 或凭据工具，不在命令行、日志、快照或回复打印。--token 兼容接口不是推荐用法。认证失败不关闭 TLS；--insecure 只有对具体实例的明确证书例外授权才可使用。缺权限不绕过服务端限制。
+
+## 按需参考
+
+| 任务 | 入口 |
+|---|---|
+| issue/PR/标签/里程碑/Release | [端点与命令](references/endpoint-map.md) |
+| 401/403、令牌来源 | [认证与 scopes](references/auth-and-scopes.md) |
+| 全量列表、分页和状态码 | [分页与错误](references/pagination-and-errors.md) |
+
+先读脚本 --help；--json 是全局参数，放在子命令前。实例当前 swagger 才是该版本字段依据；脚本不支持的字段不能编造成已执行。原生 PowerShell 编码和管道按本机版本验证，传 JSON 文件优于多层 shell 转义。
+
+## 操作与停止条件
+
+读取不扩大成写入。issue/PR 共用编号，普通 issue 列表使用 type=issues；标签 ID 按全量分页解析。合并字段 Do 区分大小写。列表失败、重复页或权限不足时标记部分覆盖，不假定不足一页即全部。
+
+缺 read:user 不代表令牌整体失效；对已指定仓库做只读查询，不能推断写权限。创建、评论、合并发生超时或不确定响应时先查状态，不盲重试；不能为了诊断创建资源。删除/合并须有具体对象和动作授权，“关闭”不是“删除”。
+
+## 交付
+
+报告实例、仓库、对象编号/链接、分页覆盖、实际动作、读回结果和失败原因。保留未完成项；不以请求发送成功代替资源状态验收。

package/skills-hub/coding/gitea-repo/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Gitea / Forgejo 仓库"
+  short_description: "管理 Gitea 与 Forgejo 的仓库对象、完整分页和具名变更验收"
+  default_prompt: "请使用 $gitea-repo：列出这台 Forgejo 的 owner/repo 所有关闭 issue，不做修改。"

package/skills-hub/coding/gitea-repo/references/auth-and-scopes.md

@@ -0,0 +1,58 @@
+# Gitea 认证与 Scope
+
+权威说明：[API Usage](https://docs.gitea.com/development/api-usage)、[OAuth2 / PAT scopes](https://docs.gitea.com/development/oauth2-provider/)。以当前实例 Swagger 为准（`$HOST/api/swagger`）。
+
+## 认证方式
+
+| 方式 | 用法 | 本技能 |
+|------|------|--------|
+| AuthorizationHeaderToken | `Authorization: token <PAT>` | **默认，必须用这个** |
+| Bearer（OAuth2 access token） | `Authorization: bearer <JWT>` | 仅当凭据是 JWT 时 |
+| HTTP Basic | `username:password` 或 `username:PAT` | 只用于 `/users/:name/tokens` 管理令牌 |
+| `?token=` / `?access_token=` | 查询串 | **禁止**。官方在 1.23 移除 |
+| `X-GITEA-OTP` | 与 Basic + 2FA 一起 | PAT 流程不需要 |
+| `Sudo` 头或 `sudo=` | 管理员冒充其他用户 | 仅管理员，默认不用 |
+
+创建/列出 PAT 本身：`POST/GET /api/v1/users/{username}/tokens`，必须 Basic + 登录密码（不能用 PAT 自己管自己）。`sha1` 明文只在创建响应里出现一次。
+
+## 令牌从哪来
+
+优先级：`--token` → `GITEA_TOKEN` → `git credential fill`（`protocol` + `host`，host 含端口，例如 `gitea.example.com:3000`）。
+
+不要把 PAT 写进仓库、技能或脚本常量，也不要打印。
+
+## Scope
+
+无 scope 的令牌**不能**访问 API（含公开仓）。`write:*` 包含对应 `read:*`。
+
+| Scope | 覆盖的路由 | 典型能力 |
+|-------|------------|----------|
+| `issue` | issues / labels / milestones 及相关评论附件 | 列/建/改 issue、评论、标签、里程碑 |
+| `repository` | `/repos/*` **不含** `/repos/.../issues/*` | PR、文件、分支、Release、协作者 |
+| `user` | `/user/*`、`/users/*` | `GET /user`、关注、星标 |
+| `organization` | orgs / teams | 组织与团队 |
+| `notification` | `/notifications` | 通知 |
+| `package` | `/packages/*` | 包 |
+| `admin` | `/admin/*` | 站点管理（非管理员账号看不到） |
+| `activitypub` / `misc` | 很少用 | 日常可忽略 |
+| `all` | 全部读写 | 仅在用户明确要求时创建 |
+
+关键分裂：
+
+- 列 issue 要 `read:issue` 或 `write:issue`
+- 建 PR / 合 PR 要 `write:repository`
+- `GET /user` 要 `read:user`。缺它时 **403**，body 类似：`token does not have at least one of required scope(s), required=[read:user]`
+- `whoami` 遇到这次 403 时改为探测 `GET /repos/{owner}/{repo}`，不要判断令牌整体无效
+
+## 状态码
+
+| 码 | 含义 | 处理 |
+|----|------|------|
+| 401 | 令牌无效/过期/未带 | 检查凭据，不要当缺 scope |
+| 403 | 已认证但缺 scope 或无权限 | 读 `message`，告知用户补 scope，不要死循环 |
+| 404 | 仓库/编号不存在，或无可见性 | 先确认 owner/repo/index |
+| 409 | PR 冲突等 | 停下来报告 |
+| 412 | 前置条件失败（如已合并 PR 改 state） | 停下来报告 |
+| 422 | 校验失败 | 读 `message` / `errors` |
+
+管理员 sudo：请求头 `Sudo: <username>` 或查询参数 `sudo=`。

package/skills-hub/coding/gitea-repo/references/endpoint-map.md

@@ -0,0 +1,80 @@
+# Gitea /api/v1 端点图
+
+`basePath=/api/v1`。实时契约（优先于本文件）：
+
+- UI：`$HOST/api/swagger`
+- JSON：`$HOST/swagger.v1.json`
+- 官方分类（可能新于实例）：https://docs.gitea.com/api/
+
+脚本没有的能力，用：
+
+```bash
+python3 "$SKILL_DIR/scripts/gitea_api.py" api GET /repos/{owner}/{repo}/issues/1/timeline
+```
+
+路径占位 `{owner}` `{repo}` 由脚本按当前仓替换。Forgejo 同源 `/api/v1` 同样适用。
+
+## gh → Gitea
+
+| gh | Gitea |
+|----|-------|
+| `gh issue list` | `GET /repos/{owner}/{repo}/issues?type=issues` |
+| `gh issue view N` | `GET /repos/{owner}/{repo}/issues/{index}` |
+| `gh issue create` | `POST /repos/{owner}/{repo}/issues` |
+| `gh issue close` | `PATCH /repos/{owner}/{repo}/issues/{index}` `{"state":"closed"}` |
+| `gh issue comment` | `POST /repos/{owner}/{repo}/issues/{index}/comments` |
+| `gh pr list` | `GET /repos/{owner}/{repo}/pulls` |
+| `gh pr view N` | `GET /repos/{owner}/{repo}/pulls/{index}` |
+| `gh pr create` | `POST /repos/{owner}/{repo}/pulls` `{"head","base","title","body"}` |
+| `gh pr merge` | `POST /repos/{owner}/{repo}/pulls/{index}/merge` `{"Do":"merge"}` |
+| `gh pr diff` | `GET /repos/{owner}/{repo}/pulls/{index}.diff` |
+| `gh release list` | `GET /repos/{owner}/{repo}/releases` |
+| `gh api user` | `GET /user` |
+| `gh search issues` | `GET /repos/issues/search` |
+| `gh repo view` | `GET /repos/{owner}/{repo}` |
+
+同仓 issue 与 PR **共用 number/index**。判断 PR：对象带 `pull_request` 字段，或走 `/pulls`。
+
+## 按资源（高频）
+
+### Issue（tag: issue）
+
+- `GET/POST /repos/{owner}/{repo}/issues`
+- `GET/PATCH/DELETE /repos/{owner}/{repo}/issues/{index}`
+- `GET/POST /repos/{owner}/{repo}/issues/{index}/comments`
+- `GET /repos/{owner}/{repo}/issues/{index}/timeline`
+- `GET/POST/PUT/DELETE /repos/{owner}/{repo}/issues/{index}/labels`
+- `GET/POST /repos/{owner}/{repo}/labels` 与 `/labels/{id}`
+- `GET/POST /repos/{owner}/{repo}/milestones` 与 `/milestones/{id}`
+- `GET /repos/issues/search` 跨仓搜索；`type=issues|pulls`
+
+`POST /issues` 体：`title`（必填）、`body`、`assignees`（用户名数组）、`labels`（**ID 数组**）、`milestone`（ID）、`due_date`、`closed`、`ref`。
+
+### Pull request（tag: repository）
+
+- `GET/POST /repos/{owner}/{repo}/pulls`
+- `GET/PATCH /repos/{owner}/{repo}/pulls/{index}`
+- `GET /repos/{owner}/{repo}/pulls/{index}/commits`
+- `GET /repos/{owner}/{repo}/pulls/{index}/files`
+- `GET/POST/DELETE /repos/{owner}/{repo}/pulls/{index}/merge`
+- `GET/POST /repos/{owner}/{repo}/pulls/{index}/reviews`
+- `POST /repos/{owner}/{repo}/pulls/{index}/update`（把 base 合进 head）
+
+同仓 PR 的 `head` 用分支名即可；fork 用 `"owner:branch"`。
+
+### 仓库 / 内容 / 发布
+
+- `GET /repos/{owner}/{repo}`
+- `GET /repos/search?q=`
+- `GET /repos/{owner}/{repo}/branches`、`/tags`、`/commits`
+- `GET/POST/PUT/DELETE /repos/{owner}/{repo}/contents/{filepath}`
+- `GET/POST /repos/{owner}/{repo}/releases`、`/releases/latest`
+
+### 用户 / 通知 / 杂项
+
+- `GET /user`（需 `read:user`）、`GET/POST /user/repos`
+- `GET /version`（缺 `read:misc` 时也可能 403，以实测为准）
+- `GET /notifications`
+- `GET /settings/api` → `max_response_items`（常见 50）、`default_paging_num`
+
+没有仓库 Projects 看板 API（上游仍在讨论）。不要假装能用 API 管 Gitea Project board。

package/skills-hub/coding/gitea-repo/references/pagination-and-errors.md

@@ -0,0 +1,34 @@
+# 分页、错误与字段陷阱
+
+## 分页
+
+- 查询参数：`page`（从 1 开始）、`limit`
+- 实例限额见 `GET /settings/api`：常见 `max_response_items=50`，`default_paging_num=30`
+- 超过上限会被服务端截断；脚本 `--all` 按页继续直到空页，不能以本页少于请求的 `limit`（默认 50）判断结束；服务端可设置更小上限。重复非空页或意外响应格式时报错，不静默返回“全量”；不再用 200 页上限静默截断
+- 响应头：
+  - `x-total-count`：总数
+  - `Link`：`rel="next"` / `rel="last"`
+- 列表接口默认 `state=open`。要全部必须显式 `state=all`
+
+## 错误体
+
+Gitea 常见 JSON：
+
+```json
+{"message":"...","url":"https://gitea.example.com/api/swagger"}
+```
+
+把 `message` 原样告诉用户。缺 scope 的 403 会写出 `required=[read:user], token scope=...`，据此判断是令牌权限问题还是仓库权限问题。
+
+## 字段陷阱
+
+1. **合并 PR 用 `Do`**：`POST .../pulls/{index}/merge` 体为 `{"Do":"merge"}`。小写 `do` 会被忽略。可选值：`merge`、`squash`、`rebase`、`rebase-merge`。删除源分支需显式 `delete_branch_after_merge`；API 不会自动套用仓库「合并后删分支」的 UI 默认值。
+2. **创建 issue 的 labels 是 ID**：`{"labels":[1,2]}`。名字必须先 `GET .../labels` 再替换。`assignees` 才是用户名数组。
+3. **issue 列表混有 PR**：不带 `type=issues` 时，PR 也会出现在 `/issues` 里，且带 `pull_request` 字段。
+4. **`/user` 与 `/version` 可能 403**：与 PAT 是否包含 `read:user` / `read:misc` 有关，不代表令牌整体无效。先用 `GET /repos/{owner}/{repo}/issues` 验证。
+5. **Basic 用户名可任意、PAT 作密码**：git HTTP 如此；API 的 `Authorization: token` 不需要用户名。
+6. **deadline 只取日期**：issue/PR 的 `due_date` 忽略时刻。
+7. **已合并 PR 不能再改 state**：返回 412。
+8. **删除 issue 是永久删除**，不是 close。默认只 PATCH `state=closed`。
+9. **不要把令牌放进 URL**。日志、代理、浏览器历史都会留下查询串。
+10. **方案跟随 `GITEA_HOST` / remote**。SSH remote 只提供待确认主机：统一以 HTTPS 作为候选，不复制 SSH 端口、不推断 HTTP。实例使用其他 API 地址时要求明确 --host；自签证书先采用受信 CA 配置，不能自动加 --insecure。