forked from Gitlink/gitlink-cli
143 lines
5.6 KiB
Markdown
143 lines
5.6 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
|
||
**影响范围**：所有使用 `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`）内部自行构建路径所以不受影响。
|
||
**影响**：
|
||
- 所有 `api GET` 返回 HTML（GitLink 首页）而非 JSON
|
||
- 所有 `api POST` 返回 404
|
||
- journals API、compare API、Issue 更新 API 全部不可用
|
||
**临时方案**：在 Skill 中标注 `api` 命令不可用，改用 shortcut 命令或引导用户网页操作
|
||
**永久修复**：需修复 CLI 的 api 子命令 URL 构建逻辑
|
||
|
||
---
|
||
|
||
### 🔴 坑 2：`issue +update` 不支持标签/责任人/优先级（严重）
|
||
|
||
**发现时间**：2026-06-09
|
||
**现象**：`issue +update` 只有 `--title`、`--body`、`--state` 三个参数，不支持 `--tags`、`--assignee`、`--priority`
|
||
**影响**：triage Skill 的核心写入操作（打标签、分配责任人）无法通过 CLI 执行
|
||
**临时方案**：Skill 改为"AI 生成分拣建议 → 用户在网页手动操作"
|
||
**永久修复**：需扩展 `issue +update` 命令，添加 `--tags`、`--assignee`、`--priority-id` 参数
|
||
|
||
---
|
||
|
||
### 🟡 坑 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 看着合理」≠「实际能跑」。必须真机验证。
|