forked from chroe/gitlink-cli
154 lines
6.8 KiB
Markdown
154 lines
6.8 KiB
Markdown
# 实验踩坑记录
|
||
|
||
> 课程：《软件演化与运维》进阶任务 — 子任务二：编写和丰富 GitLink Skills
|
||
> 记录时间：2026-06-09 ~
|
||
> 截止日期：2026-06-18
|
||
|
||
---
|
||
|
||
## 一、开发环境信息
|
||
|
||
| 项目 | 信息 |
|
||
|------|------|
|
||
| OS | Windows 11 Home China 10.0.26200 |
|
||
| Go | 1.26.1 |
|
||
| gitlink-cli | dev 版（本地构建） |
|
||
| Git 安装路径 | `D:/自用/奇奇怪怪的软件/Git/` |
|
||
| 认证方式 | cookie (auth login) |
|
||
| 测试项目 | chroe/gitlink-cli |
|
||
|
||
---
|
||
|
||
## 二、踩坑记录
|
||
|
||
### ✅ 坑 1：`api` 子命令 URL 污染（已修复）
|
||
|
||
**发现时间**：2026-06-09，**修复时间**：2026-06-13
|
||
**影响范围**：所有使用 `gitlink-cli api GET/POST` 的 Skill
|
||
**现象**：
|
||
```bash
|
||
gitlink-cli --debug api GET /v1/chroe/gitlink-cli/issues/1 --format json
|
||
# 实际请求 URL：
|
||
# https://www.gitlink.org.cn/api/D:/自用/奇奇怪怪的软件/Git/v1/chroe/gitlink-cli/issues/1.json
|
||
# ^^^^^^^^^^^^^^^^^^^^^^^^
|
||
# git exec-path 被注入！
|
||
```
|
||
**根因**：CLI 的 `api` 子命令在构建 URL 时，错误地把 `git --exec-path` 的输出拼入了 API 路径。Shortcut 命令（如 `issue +list`）内部自行构建路径所以不受影响。
|
||
**根因**：Windows Git Bash (MSYS2) 的路径自动转换。用户输入 `/v1/owner/repo`，MSYS2 把以 `/` 开头的参数当成 Unix 绝对路径，自动转换成 git 安装目录 `D:/自用/奇奇怪怪的软件/Git/v1/owner/repo`。
|
||
**修复**：在 `cmd/api/api.go` 的 `runAPI` 中加 MSYS2 路径检测——如果 path 以 Windows 盘符开头（如 `D:/`），则查找 `/v1/`、`/api/` 等常见 API 前缀并截断还原。已修复，`api` 命令现在正常工作。
|
||
**额外发现**：Issue 更新接口要用 **PATCH** 方法，POST 返回 404。
|
||
|
||
---
|
||
|
||
### ✅ 坑 2：`issue +update` 不支持标签/责任人/优先级（已有替代方案）
|
||
|
||
**发现时间**：2026-06-09，**修复时间**：2026-06-13
|
||
|
||
**发现时间**：2026-06-09
|
||
**现象**：`issue +update` 只有 `--title`、`--body`、`--state` 三个参数，不支持 `--tags`、`--assignee`、`--priority`
|
||
**影响**：triage Skill 的核心写入操作（打标签、分配责任人）无法通过 shortcut 执行
|
||
**替代方案**（已验证可用）：用 `api PATCH /v1/<owner>/<repo>/issues/<num>` 配合 `--body` 传递 JSON，可同时打标签/分配责任人/设置优先级。坑 1 修复后此方案完全可用。
|
||
**实测**：对 chroe/gitlink-cli Issue #7 执行 `api PATCH` 成功打标签「缺陷」+ 分配 chroe + 优先级「高」。
|
||
**永久修复（可选）**：扩展 `issue +update` 命令添加 `--tags`、`--assignee`、`--priority-id` 参数更易用。
|
||
|
||
---
|
||
|
||
### ✅ 坑 2.5：责任人字段名是 `assigner_ids` 不是 `assigned_to_id`（关键发现）
|
||
|
||
**发现时间**：2026-06-14
|
||
**现象**：项目记录里写"GitLink API 不支持 assign"，实测发现是**字段名错了**：
|
||
- ❌ `assigned_to_id`（单个数字）→ PATCH 返回 ok=true 但 assigners 仍为空
|
||
- ✅ `assigner_ids`（数组）→ PATCH 后 assigners 立即生效
|
||
**教训**：之前因为旧记录说"不支持"就放弃了，没深入测试。GitLink 其实完全支持分配责任人，只是字段名跟常见 REST API 不同。
|
||
**修复**：triage Skill 中所有 `assigned_to_id` 改为 `assigner_ids`。
|
||
|
||
---
|
||
|
||
### 🟡 坑 3：`issue +list --state open` 过滤不生效
|
||
|
||
**发现时间**：2026-06-09
|
||
**现象**：`--state open` 返回的 `issues` 列表包含已关闭的 Issue（status_id=5），但 `opened_count` 字段是准确的
|
||
**影响**：AI 执行 triage 时可能处理已关闭的 Issue
|
||
**解决方案**：客户端过滤 `status.id !== 5`（status_id=5 是关闭状态）
|
||
|
||
---
|
||
|
||
### 🟡 坑 4：compare API 全面返回 HTML
|
||
|
||
**发现时间**：2026-06-09
|
||
**现象**：不仅是部分项目，所有项目的 compare API 都返回 HTML 而非 JSON
|
||
**影响**：changelog Skill 无法使用 compare API 对比版本差异
|
||
**解决方案**：改用 `commit +list` 按时间戳筛选版本区间内的提交
|
||
|
||
---
|
||
|
||
### 🟡 坑 5：journals API 全面返回 HTML
|
||
|
||
**发现时间**：2026-06-09（之前以为是"部分项目"）
|
||
**现象**：所有项目的 journals API（`/v1/:owner/:repo/issues/:number/journals`）都返回 HTML
|
||
**影响**：无法获取 Issue 评论的详细内容和时间
|
||
**解决方案**：统一使用 `comment_journals_count` 字段判断是否有响应（>0 表示有人响应）
|
||
|
||
---
|
||
|
||
### 🟢 坑 6：changelog 样式分类与输出格式不一致
|
||
|
||
**发现时间**：2026-06-09
|
||
**现象**：SKILL.md 分类规则表有"💄 样式"类，但 Release Notes 输出模板没有样式节
|
||
**解决方案**：标注样式类 commit 归入"改进优化"分类
|
||
|
||
---
|
||
|
||
## 三、验证记录
|
||
|
||
### gitlink-changelog 验证（2026-06-09 二次复测）
|
||
|
||
| # | 命令 | 结果 | 备注 |
|
||
|---|------|------|------|
|
||
| 1 | `release +list --format json` | ✅ | 1 个版本 v0.1.13-freebsd |
|
||
| 2 | `commit +list --format json` | ✅ | 20 条，基线后 20 条 |
|
||
| 3 | `pr +list --state merged` | ✅ | 0 个（Fork 仓库） |
|
||
| 4 | `issue +list --state closed` | ✅ | 6 个已关闭 |
|
||
| 5 | `release +view --id 1986` | ✅ | 正常返回 |
|
||
| 6 | `release +create --help` | ✅ | 参数完整可用 |
|
||
| 7 | ~~`api GET /compare/...`~~ | ❌ 返回 HTML | 已在 SKILL.md 标注不可用 |
|
||
| 8 | Commit 分类 20 条 | ✅ 20/20 正确 | 含 4 条正确跳过 |
|
||
| 9 | Release Notes 生成 | ✅ | 格式完整，含真实数据 |
|
||
|
||
### gitlink-triage 验证（2026-06-09 二次复测，上游仓库）
|
||
|
||
| # | 命令 | 结果 | 备注 |
|
||
|---|------|------|------|
|
||
| 1 | `issue +list --state open`（上游 gitlink/gitlink-cli） | ⚠️ | 列表 18 条含已关闭，需客户端过滤 |
|
||
| 2 | `issue +view --number N`（6 个 Issue） | ✅ | 全部返回详情 |
|
||
| 3 | `label +list`（上游） | ✅ | 10 个中文标签 |
|
||
| 4 | `member +list`（上游） | ✅ | 46 个成员 |
|
||
| 5 | `label +create --help` | ✅ | 可用 |
|
||
| 6 | `label +update --help` | ✅ | 可用 |
|
||
| 7 | `issue +comment --help` | ✅ | 可用 |
|
||
| 8 | `issue +update --state` | ✅ | 仅 title/body/state |
|
||
| 9 | ~~`api GET /journals`~~ | ❌ 返回 HTML | 已在 SKILL.md 标注 |
|
||
| 10 | ~~`api POST /issues/N`~~ | ❌ 404 | URL 污染 bug，已标注 |
|
||
| 11 | Issue 分类 6 条 | ✅ 6/6 正确 | 上游真实 Issue |
|
||
| 12 | Good First Issue 评估 | ✅ | 识别出 2 个 GFI（#14, #18） |
|
||
|
||
---
|
||
|
||
## 四、开发 Skill 的正确流程（血的教训）
|
||
|
||
```
|
||
1. 确定 Skill 场景
|
||
2. 写 SKILL.md
|
||
3. ⚠️ 在终端中逐条执行 SKILL.md 中的每一条命令
|
||
- 确认返回 JSON 而非 HTML
|
||
- 确认写入操作 API 路径正确
|
||
- 确认 Raw API URL 不被 git 路径污染
|
||
4. 修复发现的问题
|
||
5. 写 REFERENCE.md
|
||
6. 写 examples（用真实数据）
|
||
7. 在 Claude Code 中运行验证
|
||
8. 写 VERIFICATION.md
|
||
```
|
||
|
||
> **核心原则**：「AI 看着合理」≠「实际能跑」。必须真机验证。
|