5.6 KiB
实验踩坑记录
课程：《软件演化与运维》进阶任务 — 子任务二：编写和丰富 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
现象：
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 看着合理」≠「实际能跑」。必须真机验证。