fast-ship

Files (3)

• SKILL.md
• api.md · references/
• fast-ship-api.mjs · scripts/

SKILL.md (first lines)

# Fast Ship API

| 想做什么 | 实际调用 |
|---|---|
| 在 issue 上留言/发评论/写完成总结 | `PUT /api/issues/:iid/collab/summary`（API Key 发评论必 40301） |
| 标记完成 | `PUT /api/issues/:iid/internal-meta` 置 `workflow_status=done`（不是 `state`） |
| 关闭 issue | 不可——仅 JWT，API Key 传 `state` 必 40301 |
| 开始做了 | `PUT /api/issues/:iid/internal-meta` 置 `in_progress` |
| 记录共识/决策 | `PUT /api/issues/:iid/collab/consensus` |
| 按 `INT-xxx` 找 issue | `GET /api/projects/:pid/issues?q=INT-56` 换 UUID（路径参数只认 UUID） |
| 查 Fast Ship 自身日志 | `GET /api/self-logs`（列表）、`/aggregate`、`/trace`（`request_id` 或 `run_id` 二选一）；与项目日志 `/projects/:id/logs` 无关；fsr_ 令牌 40301 |
| 把 PR 挂到 issue | `POST /api/issues/:iid/pull-requests`，body `{"url":"<PR链接>"}` |
| 刷新 PR 状态 | `POST /api/issues/:iid/pull-requests/sync`（合并后调，逐行失败看 `failures[]`） |
| 摘掉某个 PR | `DELETE /api/issues/:iid/pull-requests/:lid`（`:lid` 是关联行 id，即 api.md 里的 `{id}`） |

**调用任何写接口前先读 `references/api.md` 对应小节，不要凭记忆构造请求体。**

## Fast Ship 附加块（提示词尾部的引用块）

Fast Ship「启动线程」生成的提示词 = 用户模板正文 + 结尾的 `>` 引用块。看到引用块里带
`项目ID` / `问题ID`，就按这两个 ID 用技能查询并处理该问题，不需要再追问是哪条 issue：

```
> 以下信息由 Fast Ship 附加。请使用 fast-ship 技能查询并处理该问题。
> 若当前环境未安装 fast-ship 技能，先征得用户同意，再执行：
> `npx skills add https://github.com/gitbobobo/fast_ship --skill fast-ship`
> 项目ID：<project_id>
> 问题ID：<issue_id>
> 推荐理由：<reason>   ← 可能出现
```

当前环境未安装本技能时，先征得用户同意，再执行 `npx skills add https://github.com/gitbobobo/fast_ship --skill fast-ship`。

## T3 绑定（Agent 辅助配置）

Fast Ship 项目与 T3 项目是显式绑定，Agent 可辅助完成「发现 → 比对 → 绑定」：

1. `GET /api/environments/t3-projects`：列出各环境及其 T3 项目（含 `workspace_root`）。
2. 用自身仓库路径比对各项目的 `workspace_root`，确定自己对应哪个 T3 项目。
3. `PUT /api/projects/{id}/t3-bindings/{environmentId}`，body `{"t3_project_id":"..."}` 完成绑定；解绑用 `DELETE` 同路径。

这四个接口是对 API Key 开放的 T3 只读面（不含凭证、不含线程内容）；线程相关端点仍仅 JWT。字段细节见 `references/api.md`。

上表的 `:pid` 在 api.md 里是 `{id}`，`:iid` 是 `{iid}`；`:lid` 是 PR 关联行 id（api.md 里 `pull-requests` 路径下的 `{id}`）。

## 认证配置

Fast Ship 使用 **API Key** 进行程序化认证。Key 格式为 `fsk_` 开头的随机字符串。

### 请求方式（硬性规则）

- **禁止**把 API Key 读出来写进命令、参数、环境变量赋值或任何输出——`curl -H "Authorization: Bearer fsk_..."` 这类写法会把 Key 留在会话记录和进程列表里。
- 所有请求一律走技能自带脚本。脚本自行读取 config 并附加认证头，Key 不出现在命令行：

```bash
node <技能目录>/scripts/fast-ship-api.mjs <METHOD> <path> [body.json] [--verify [读回路径]]
```

- 需要请求体时，把 JSON 写成 UTF-8 文件，以 `body.json` 位置参数传入。
- `--verify [读回路径]`：写请求成功（2xx）后再发一次 GET，输出 `{ "response": …, "verify": … }`，用于写后读回校验。缺省对同一路径 GET；没有对应 GET 路由的写端点（如 `internal-meta`、`recommendation`、`collab` 的 PUT；批量 `PUT /api/issues/internal-meta` 的缺省读回会命中 `GET /issues/:iid` 而 404）必须显式给出读回路径（如对 Issue 本身 `GET /api/issues/:iid`）。对 DELETE，读回 404 视为确认删除。
- 脚本不可用时的兜底：把 `Authorization: Bearer <api_key>` 整行写入临时头文件，用 `curl -H @<header文件>` 引用，用完**立即删除**该文件。

### 首次使用（配置持久化）

如果 `~/.config/fast-ship/config.yaml` 不存在，**必须**向用户询问以下信息：

1. **Base URL**：Fast Ship 服务地址，例如 `http://localhost:8080` 或 `https://fast-ship.example.com`
2. **API Key**：从 Fast Ship Web 界面「设置 → API Key」创建的密钥（`fsk_` 开头）

然后将配置写入文件：

```yaml
# ~/.config/fast-ship/config.yaml
base_url: "https://fast-ship.example.com"
api_key: "fsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

> 注意：`~/.config` 目录在 macOS/Linux 上通常已存在；如果不存在，请先创建目录。

### 后续使用

脚本会自行读取 `~/.config/fast-ship/config.yaml` 中的 `base_url` 和 `api_key`，**不再询问用户**。Agent **不要**把 Key 读出来写进命令或输出。

### 请求头

脚本自动为所有请求携带以下请求头（无需手工添加）：

```
Authorization: Bearer <api_key>
Content-Type: application/json; charset=utf-8
```

## 核心工作流

未说明来源时创建 `source: "internal"`。只有用户明确要求同步 GitHub 时才用 `source: "github"`。API Key 只能建 internal。

字段一律见 `references/api.md`，这里只留端点。

1. `GET /api/projects`，确定 `project_id`。
2. 打标前先 `GET /api/projects/{id}/issues/repo-labels`。项目没配 GitHub 仓库或标签为空时，改 `GET /api/projects/{id}/issues/filter-options`。
3. `POST /api/projects/{id}/issues` 创建。后续路径只用响应里的 `id`（UUID）。给用户的页面是 `{base_url}/projects/{project_id}/issues/{id}`。
4. 要打标就 `PUT /api/issues/{iid}`，标签名必须已经存在。不要靠创建请求里的 `workflow_status` 推进进度。
5. 推进用 `PUT /api/issues/{iid}/internal-meta`，值为 `todo`、`in_progress` 或 `done`。
6. 查一条用 `GET /api/issues/{iid}`。列表用 `GET /api/projects/{id}/issues`。

## 截图标注（AI 评审闭环）

截图页画布上的矩形框选标注挂在**具体截图**上，供人/AI 交换评审意见。API Key 可读全部标注、拉裁剪图、标为已解决；不能创建/删除标注或批量处理（40301），改文字/关联 Issue/重开也要 JWT。

- 列表：`GET /api/projects/{id}/screenshot-annotations` → `{items:[...]}`，query 可按 `status`（open/resolved）、`outdated`（true/false）、`issue_id`、`screen_id`、`platform`/`locale`/`theme`（逗号多值，`__none__` = 未标注桶）过滤。
- Issue 维度：`GET /api/issues/{iid}` 的 `screenshot_annotations[]` 内嵌关联到该 Issue 的标注（无则缺省）。
- 每条标注带：`image_url`（所在截图原图）、`crop_url`（框选区域裁剪图，PNG，四周带外边距）、比例坐标 `x/y/width/height`（0~1）、像素坐标 `pixel_rect`（尺寸未知时为 null）、`screen_key`/`screen_title`/`screen_platform`/`screen_locale`/`screen_theme`、`outdated`（截图被覆盖更新后待确认）、`status`。
- `crop_url`/`image_url` 是 `<img>` 直链路径：脚本调用带 Authorization 头即可，Web 端 `<img>` 才需要 `?token=<jwt>`。
- 标已解决：`PUT /api/screenshot-annotations/{aid}`，body 整包只传 `{"status":"resolved"}`——带其他字段或 `open` 会被 40301。
- 原图超过解码像素上限（约 64MP）时 crop 返回 40004（`尺寸超出可处理范围`），此时用 `image_url` 拉原图自行缩放。

AI 评审闭环（字段细节见 api.md screenshots 章）：

1. `GET /api/issues/{iid}` 读 `screenshot_annotations`，或按维度过滤 + `status=open` 拉项目标注。

From gitbobobo/skills, MIT.

More from gitbobobo/skills