forked from Gitlink/gitlink-cli
Compare commits
10 Commits
| Author | SHA1 | Date |
|---|---|---|
 yetja
|
c6ebe659bc | |
|
yetja
|
43eb36cb33 | |
|
yetja
|
8eaeced2e8 | |
|
yetja
|
04a990da31 | |
|
yetja
|
ca616101c7 | |
|
yetja
|
aa5e1ff6b9 | |
|
yetja
|
c60c30676f | |
|
yetja
|
25e1915579 | |
|
yetja
|
4e4438eed6 | |
|
yetja
|
cb2e401a83 |
|
|
@ -21,7 +21,7 @@ workflow:
|
|||
ssh_port: '"22"'
|
||||
ssh_user: '"root"'
|
||||
ssh_cmd: >-
|
||||
"git config --global --add safe.directory /opt/gitlink-cli && cd /opt/gitlink-cli && git fetch origin && git reset --hard origin/master && DOCKER_BUILDKIT=1 docker build -f showcase/Dockerfile -t gitlink-cli-showcase . && docker stop gitlink-cli-showcase || true && docker rm gitlink-cli-showcase || true && docker run -d -p 9090:9090 --name gitlink-cli-showcase --restart unless-stopped -e GITLINK_TOKEN='cookie:autologin_trustie=56c6d2b4378588465c97d48679eed7bd2495ff1a' gitlink-cli-showcase"
|
||||
"cd /opt/gitlink-cli && git fetch origin && git reset --hard origin/master && docker build -f showcase/Dockerfile -t gitlink-cli-showcase . && docker stop gitlink-cli-showcase || true && docker rm gitlink-cli-showcase || true && docker run -d -p 9090:9090 --name gitlink-cli-showcase --restart unless-stopped -e GITLINK_TOKEN='cookie:autologin_trustie=56c6d2b4378588465c97d48679eed7bd2495ff1a' gitlink-cli-showcase"
|
||||
needs:
|
||||
- start
|
||||
- ref: end
|
||||
|
|
|
|||
|
|
@ -1,37 +0,0 @@
|
|||
# Binaries
|
||||
*.exe
|
||||
*.exe~
|
||||
*.dll
|
||||
*.so
|
||||
*.dylib
|
||||
bin/
|
||||
dist/
|
||||
|
||||
# Showcase build outputs（由 Dockerfile / deploy 脚本编译，不入库）
|
||||
showcase/showcase-linux
|
||||
showcase/showcase-server-linux
|
||||
showcase/showcase-server
|
||||
showcase/showcase
|
||||
|
||||
# Test binary
|
||||
*.test
|
||||
|
||||
# Output of go coverage
|
||||
*.out
|
||||
|
||||
# Go workspace
|
||||
go.work
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Env
|
||||
.env
|
||||
.env.local
|
||||
|
|
@ -0,0 +1,153 @@
|
|||
# 实验踩坑记录
|
||||
|
||||
> 课程：《软件演化与运维》进阶任务 — 子任务二：编写和丰富 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 看着合理」≠「实际能跑」。必须真机验证。
|
||||
|
|
@ -0,0 +1,404 @@
|
|||
# GitLink-CLI 项目状态总结
|
||||
|
||||
> 最后更新：2026-06-08
|
||||
> 仓库：`D:\自用\self\word\大三下\软件演化\gitlink-cli`
|
||||
> 远程：`https://gitlink.org.cn/chroe/gitlink-cli.git`
|
||||
|
||||
---
|
||||
|
||||
## 一、课程任务背景
|
||||
|
||||
**课程**：《软件演化与运维》课程实践
|
||||
**进阶任务**：GitLink 智能化能力提升项目
|
||||
**当前阶段**：子任务二 — 编写和丰富 GitLink Skills（20%，截止 6月18日）
|
||||
|
||||
### 子任务一交付要求（已完成）
|
||||
- 向 gitlink-cli 主仓库提交 PR（可多个）
|
||||
- 每个 PR 包含：功能代码 + 单元测试 + 命令帮助文档更新
|
||||
- 提供变更说明文档
|
||||
- 撰写《软件分析及建模报告》、《新需求构思报告》、《变更影响分析及测试报告》
|
||||
|
||||
### 子任务二交付要求（进行中）
|
||||
- 遵循 gitlink-cli Skills 规范（参考 `skills/README.md`）
|
||||
- 每个 Skill 包含：SKILL.md + 使用示例 + 至少在一个 Agent 平台上验证通过
|
||||
- 兼容至少一个主流 AI Agent（如 Claude Code、OpenClaw、Cursor 等）
|
||||
- 撰写《新需求构思报告》和《变更影响分析及测试报告》
|
||||
|
||||
---
|
||||
|
||||
## 二、技术栈与架构
|
||||
|
||||
- **语言**：Go 1.26.1
|
||||
- **CLI 框架**：spf13/cobra
|
||||
- **密钥存储**：zalando/go-keyring（OS keychain + 文件 fallback）
|
||||
- **配置**：gopkg.in/yaml.v3，存放于 `~/.config/gitlink-cli/config.yaml`
|
||||
- **三层命令架构**：
|
||||
1. **基础命令**（cmd/）：`auth`, `api`, `config`, `version`
|
||||
2. **Shortcut 命令**（shortcuts/）：`repo +list`, `issue +create` 等 94 个命令
|
||||
3. **Raw API**：`api GET /path`
|
||||
|
||||
### Shortcut 模块开发模式
|
||||
|
||||
每个模块位于 `shortcuts/<name>/<name>.go`，结构固定：
|
||||
|
||||
```go
|
||||
package <name>
|
||||
|
||||
import "github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
|
||||
func Shortcuts() []*common.Shortcut {
|
||||
return []*common.Shortcut{
|
||||
{
|
||||
Name: "list",
|
||||
Description: "Description here",
|
||||
Flags: []common.Flag{
|
||||
{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil { return err }
|
||||
env, err := ctx.CallAPI("GET", ctx.RepoPath()+"/something", nil)
|
||||
if err != nil { return err }
|
||||
return ctx.Output(env)
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
注册到 `shortcuts/register.go`：
|
||||
```go
|
||||
import "github.com/gitlink-org/gitlink-cli/shortcuts/<name>"
|
||||
// 在 RegisterAll() 中添加:
|
||||
// "<name>": <name>.Shortcuts(),
|
||||
// descriptions["<name>"] = "Description",
|
||||
```
|
||||
|
||||
### 单元测试模式（httptest mock）
|
||||
|
||||
```go
|
||||
func TestXxx(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// 校验 method/path/query，返回 mock JSON
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := &common.RuntimeContext{
|
||||
Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
|
||||
Owner: "owner", Repo: "repo", Format: "json", Args: args,
|
||||
}
|
||||
err := findShortcut(t, "list").Run(ctx)
|
||||
// 断言
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、已实现的 18 个 Shortcut 模块（94 个命令）
|
||||
|
||||
| 模块 | 命令数 | 文件 | 测试 |
|
||||
|------|--------|------|------|
|
||||
| repo | 9（含 batch-delete/fork） | shortcuts/repo/ | ✅ |
|
||||
| issue | 12（含 batch-close/assign/label/milestone） | shortcuts/issue/ | ✅ |
|
||||
| pr | 9 | shortcuts/pr/ | ✅ |
|
||||
| release | 5 | shortcuts/release/ | ✅ |
|
||||
| branch | 5 | shortcuts/branch/ | ✅ |
|
||||
| ci | 4 | shortcuts/ci/ | ✅ |
|
||||
| commit | 4 | shortcuts/commit/ | ✅ |
|
||||
| file | 5 | shortcuts/file/ | ✅ |
|
||||
| member | 4 | shortcuts/member/ | ✅ |
|
||||
| star | 3 | shortcuts/star/ | ✅ |
|
||||
| watch | 3 | shortcuts/watch/ | ✅ |
|
||||
| label | 4 | shortcuts/label/ | ✅ |
|
||||
| milestone | 6 | shortcuts/milestone/ | ✅ |
|
||||
| webhook | 6 | shortcuts/webhook/ | ✅ |
|
||||
| org | 5（含 batch-invite） | shortcuts/org/ | ✅ |
|
||||
| search | 3 | shortcuts/search/ | ✅ |
|
||||
| user | 2 | shortcuts/user/ | ✅ |
|
||||
| wiki 🆕 | 5 | shortcuts/wiki/ | ✅ 12个测试 |
|
||||
|
||||
### 批量操作汇总（7个）
|
||||
|
||||
| 批量命令 | 所属模块 | 输入方式 | 预览模式 |
|
||||
|----------|----------|----------|----------|
|
||||
| batch-close | issue | --numbers 逗号 / --from CSV | --dry-run |
|
||||
| batch-assign | issue | 同上 | --dry-run |
|
||||
| batch-label | issue | 同上 | --dry-run |
|
||||
| batch-milestone | issue | 同上 | --dry-run |
|
||||
| batch-delete | repo | --repos owner/repo 列表 / --from CSV | --dry-run |
|
||||
| batch-fork | repo | 同上 | --dry-run |
|
||||
| batch-invite | org | --users 用户名列表 / --from CSV | --dry-run |
|
||||
|
||||
---
|
||||
|
||||
## 四、Wiki 模块开发记录
|
||||
|
||||
### Wiki API 关键发现
|
||||
|
||||
| 发现 | 说明 |
|
||||
|------|------|
|
||||
| API 域名 | `gateway.gitlink.org.cn` 而非 `www.gitlink.org.cn` |
|
||||
| API 路径 | `/wiki/open/...`（有 `/open/` 中间段） |
|
||||
| 无 `.json` 后缀 | Gateway 不接受 `.json`，需要 `client.DoRaw()` |
|
||||
| Sidebar 名称 | `_Sidebar`（大写 S），非小写 `_sidebar` |
|
||||
| projectId 字段 | 仓库返回 `project_id` 而非 `id` |
|
||||
| create/update 需要 `title` | API 必填字段 |
|
||||
| delete 异步重建 sidebar | 需延迟 2 秒后再清理 sidebar |
|
||||
| `data.data` 格式 | `DoRaw` 返回 dict 而非 string，解析需兼容 |
|
||||
|
||||
### delete 命令的 sidebar 自动清理流程
|
||||
1. 删除 wiki 页面（DELETE）
|
||||
2. 等待 2 秒（让 GitLink 完成异步 sidebar 重建）
|
||||
3. 获取 `_Sidebar` 内容
|
||||
4. 移除已删页面的 `[[PageName]]` 链接
|
||||
5. 更新 `_Sidebar`
|
||||
|
||||
---
|
||||
|
||||
## 五、开发踩坑记录
|
||||
|
||||
### 修改 CLI 代码后必须同时重建 showcase
|
||||
showcase 通过 `findCLIBinary()` 在运行时查找 `gitlink-cli.exe`。每次修改 CLI 代码后需要：
|
||||
```bash
|
||||
cd gitlink-cli
|
||||
go build -o gitlink-cli.exe . # 重建 CLI
|
||||
cd showcase && go build -o showcase.exe . # 重建 showcase（更新嵌入的 HTML）
|
||||
# 然后重启 showcase.exe
|
||||
```
|
||||
如果只重建 showcase 不重建 CLI，showcase 用的还是旧版二进制。
|
||||
|
||||
### Showcase 参数传递坑
|
||||
showcase 后端曾用 `strings.Split(args, " ")` 按空格切割参数，导致 `"Hello Wiki!"` 被截断为 `"Hello"`。
|
||||
修复：前端给含空格的值加引号，后端用支持引号解析的 `parseShellArgs()` 替代简单 Split。
|
||||
|
||||
### Showcase 布尔参数坑（已修复）
|
||||
Cobra 的 BoolP 标志：`--dry-run false`（空格分隔）会被解析为 `--dry-run=true` + 多余参数 "false"。
|
||||
所以批量操作 `--dry-run false` 实际上是在预览模式下运行，不会真正执行。
|
||||
修复：布尔参数改用 `<select>` 下拉框，JS 只在选"是"时才传 `--flag`，选"否"时不传。
|
||||
|
||||
### Showcase 重复参数坑（已修复）
|
||||
服务器后端自动添加 `--owner chroe --repo gitlink-cli`。如果前端卡片也传 `--owner`/`--repo`，
|
||||
会导致参数重复。修复：watch +watchers 和 star +stars 移除了多余的 owner/repo 输入框。
|
||||
|
||||
### Showcase null 显示（已修复）
|
||||
CLI 命令返回空数据时，前端显示 "null"。修复：JS 层对 null/空对象/空字符串统一显示"操作完成，无返回数据"。
|
||||
|
||||
---
|
||||
|
||||
## 六、CI/CD 流水线
|
||||
|
||||
### 部署架构
|
||||
```
|
||||
代码 push → GitLink 触发流水线 → SSH 到服务器 → git fetch + reset → docker build → 重启容器
|
||||
```
|
||||
|
||||
### 流水线文件
|
||||
- `.devops/构建部署Showcase.yml` — GitLink DevOps 流水线（push 自动触发）
|
||||
|
||||
### 流水线关键配置
|
||||
- 使用 `git fetch + git reset --hard origin/master` 避免 git pull 的本地修改冲突
|
||||
- 使用 `docker build --no-cache` 确保每次用最新代码构建
|
||||
- 容器启动时注入 `-e GITLINK_TOKEN=cookie:autologin_trustie=...` 解决认证问题
|
||||
- GitLink 密钥管理：`deploy_server.server_password` = 服务器密码
|
||||
|
||||
### 服务器信息
|
||||
- **IP**: 118.31.4.168
|
||||
- **用户**: root
|
||||
- **部署路径**: /opt/gitlink-cli
|
||||
- **容器名**: gitlink-cli-showcase
|
||||
- **端口**: 9090
|
||||
- **访问地址**: http://118.31.4.168:9090
|
||||
- **Showcase 展示模块数**: 12 个模块卡片（milestone/webhook/label/commit/wiki/file/member/watch/star/issue批量/repo批量/org批量）
|
||||
|
||||
### Docker 构建注意
|
||||
Dockerfile 已配置 `ENV GOPROXY=https://goproxy.cn,direct`，解决国内网络 Go 模块下载问题。
|
||||
服务器 Docker daemon 已配置国内镜像加速器（`/etc/docker/daemon.json`）。
|
||||
|
||||
---
|
||||
|
||||
## 七、已完成工作
|
||||
|
||||
### ✅ 子任务一完成项
|
||||
- [x] 基础命令框架（auth/api/config/version）
|
||||
- [x] 18 个 Shortcut 模块（94 个命令），其中 wiki 为新增
|
||||
- [x] 7 个批量操作命令（batch-close/assign/label/milestone/delete/fork/invite）
|
||||
- [x] 12 个 AI Agent Skills（基础版，部分需要丰富）
|
||||
- [x] Showcase Dashboard 在线展示（12 个模块卡片，支持真实运行）
|
||||
- [x] GitHub CI/CD（release + npm publish + FreeBSD 支持）
|
||||
- [x] GitLink DevOps 流水线（push 自动部署，已配置密钥，正常运行）
|
||||
- [x] 单元测试（wiki 12个 + 其他模块 47+）
|
||||
- [x] client.DoRaw 方法（不带 .json 后缀的原始 API 调用）
|
||||
- [x] Showcase 布尔参数/重复参数/null显示 修复
|
||||
|
||||
---
|
||||
|
||||
## 七-A、子任务二：编写和丰富 GitLink Skills
|
||||
|
||||
### 📋 总体策略
|
||||
1. **先做新 Skill**：开发课程建议的新场景 Skill
|
||||
2. **后完善老 Skill**：丰富已有的 12 个 Skill，补充 REFERENCE.md、examples、验证记录
|
||||
|
||||
### 新 Skill 开发进度
|
||||
|
||||
| 优先级 | Skill 名称 | 场景 | 状态 | 说明 |
|
||||
|--------|-----------|------|------|------|
|
||||
| 🥇 | `gitlink-health` | 项目健康度报告 | ✅ 已完成 | 评分算法验证通过，含 fallback 策略 |
|
||||
| 🥈 | `gitlink-changelog` | Release Notes 自动生成 | ✅ 已完成 | commit 分类规则完整，含 PR 过滤注意事项 |
|
||||
| 🥉 | `gitlink-triage` | Issue 智能分拣 + 新人引导 | ✅ 已完成 | 含 subject/description 保留警告、标签映射说明 |
|
||||
|
||||
### Skill 开发指南（给队友看的）
|
||||
|
||||
> 完整踩坑记录见 `EXPERIMENT_LOG.md`，这里只写怎么动手。
|
||||
|
||||
#### 每个 Skill 的标准交付物（3 个文件）
|
||||
|
||||
```
|
||||
skills/gitlink-<name>/
|
||||
├── SKILL.md # 主文件：触发条件、数据采集命令、输出格式、使用场景
|
||||
├── REFERENCE.md # 技术参考：字段映射、API 注意事项、Q&A
|
||||
└── examples/
|
||||
└── <scenario>.md # 使用示例（= Agent 验证证明）
|
||||
```
|
||||
|
||||
**不需要** VERIFICATION.md — example 里放真实命令输出，本身就是验证记录。
|
||||
|
||||
#### 开发步骤（按顺序做）
|
||||
|
||||
```
|
||||
第一步：确定场景
|
||||
- 这个 Skill 解决什么问题？什么时候触发？
|
||||
|
||||
第二步：写 SKILL.md
|
||||
- 照着已有的 Skill 抄格式（推荐抄 gitlink-issue/SKILL.md）
|
||||
- 必须有的内容：
|
||||
· frontmatter（name/version/description/metadata）
|
||||
· CRITICAL 块引用 gitlink-shared/SKILL.md
|
||||
· 数据采集命令（分步骤，每步一个代码块）
|
||||
· 输出格式模板
|
||||
· 2-3 个使用场景
|
||||
· 最佳实践
|
||||
|
||||
第三步：⚠️ 在终端里逐条跑 SKILL.md 中的命令（最重要！）
|
||||
- 每条命令都要跑，看返回的是 JSON 还是 HTML
|
||||
- 写入命令确认参数完整、能执行
|
||||
- 记录每条命令的真实输出（后面写 example 要用）
|
||||
|
||||
第四步：写 REFERENCE.md
|
||||
- API 字段映射（命令返回的 JSON 长什么样）
|
||||
- 注意事项和限制
|
||||
- 常见问题 Q&A
|
||||
|
||||
第五步：写 examples/
|
||||
- 用第三步记录的真实输出
|
||||
- 格式：命令序列 + 真实返回数据 + AI 生成的结果
|
||||
- 不准编造数据！
|
||||
```
|
||||
|
||||
#### ⚠️ 绝对不能踩的坑
|
||||
|
||||
| 坑 | 说明 | 怎么避 |
|
||||
|----|------|--------|
|
||||
| `api` 子命令不可用 | `gitlink-cli api GET/POST` 存在 URL 污染 bug，会把 git 安装路径拼进 URL | **不要用** `api` 子命令，只用 shortcut 命令（如 `issue +list`、`repo +info`） |
|
||||
| `--state open` 过滤不准 | `issue +list --state open` 可能返回已关闭的 Issue | 客户端检查 `status_id`，`5` = 关闭 |
|
||||
| journals API 返回 HTML | `/v1/:owner/:repo/issues/:number/journals` 返回网页 | 用 `issue +view` 的 `comment_journals_count` 字段代替 |
|
||||
| compare API 返回 HTML | `/owner/:repo/compare/...` 返回网页 | 用 `commit +list` 按时间筛选代替 |
|
||||
| Issue 更新会清空字段 | 更新时不带 subject/description 会导致标题和描述被清空 | 先 `issue +view` 获取当前内容，更新时一并提交 |
|
||||
| 标签名是中文 | 项目已有标签是"缺陷/功能/疑问"，不是英文 | 用 `label +list` 获取已有标签，优先匹配 |
|
||||
| `issue +update` 不支持打标签/分配 | 只有 title/body/state 三个参数 | 写入 CRITICAL 警告，引导用户网页操作 |
|
||||
|
||||
#### 已有 Skill 完善任务分配
|
||||
|
||||
| Skill | 当前状态 | 要做的事 | 分配给 |
|
||||
|-------|---------|---------|--------|
|
||||
| **gitlink-issue** | 有 SKILL.md + references/(7个文件) | 补 examples/（用 chroe/gitlink-cli 真实数据） | — |
|
||||
| **gitlink-pr** | 有 SKILL.md + references/(6个文件) | 补 examples/ | — |
|
||||
| **gitlink-release** | 有 SKILL.md + references/(4个文件) | 补 examples/ | — |
|
||||
| **gitlink-workflow** | 仅有空壳 SKILL.md | 重写 SKILL.md + 补 REFERENCE.md + examples | — |
|
||||
| **gitlink-ci** | 仅有 SKILL.md | 补 REFERENCE.md + examples | — |
|
||||
| **gitlink-pm** | 仅有 SKILL.md | 补 REFERENCE.md + examples | — |
|
||||
| **gitlink-repo** | 有 SKILL.md + references/(9个文件) | 补 examples/ | — |
|
||||
| **gitlink-search** | 有 SKILL.md + references/(2个文件) | 补 examples/ | — |
|
||||
| **gitlink-user** | 有 SKILL.md + references/(2个文件) | 补 examples/ | — |
|
||||
| **gitlink-org** | 有 SKILL.md + references/(3个文件) | 补 examples/ | — |
|
||||
| **gitlink-branch** | 有 SKILL.md + examples/(1个文件) | 补 REFERENCE.md | — |
|
||||
|
||||
> **完善标准**：每个 Skill 至少有 SKILL.md + examples/(含真实命令输出)。REFERENCE.md 如果已有 references/ 目录可以不写。
|
||||
|
||||
### 待写文档 📄
|
||||
- [ ] 《新需求构思报告》（子任务一 + 子任务二共用）
|
||||
- [ ] 《变更影响分析及测试报告》（子任务一 + 子任务二共用）
|
||||
|
||||
---
|
||||
|
||||
## 八、小组分工
|
||||
|
||||
| 角色 | 负责人 | 负责内容 |
|
||||
|------|--------|----------|
|
||||
| 组长 A | — | commit(4命令)、milestone(6)、webhook(6)、label(4)、Showcase |
|
||||
| 同学 B | — | file(5)、member(4)、watch(3)、star(3) |
|
||||
| 同学 C | — | 批量操作增强(batch-assign/label/milestone/delete/fork/invite)、table 输出优化、测试覆盖、FreeBSD构建 |
|
||||
| 全员 | — | wiki(5命令)、流水线部署 |
|
||||
|
||||
---
|
||||
|
||||
## 九、快速开始
|
||||
|
||||
```bash
|
||||
# 构建
|
||||
cd gitlink-cli && make build
|
||||
|
||||
# 运行测试
|
||||
go test ./shortcuts/... -v
|
||||
|
||||
# 登录
|
||||
./gitlink-cli auth login
|
||||
|
||||
# 使用示例
|
||||
./gitlink-cli repo +list --owner gitlink
|
||||
./gitlink-cli issue +list --owner gitlink --repo gitlink-cli
|
||||
./gitlink-cli wiki +list --owner chroe --repo gitlink_help_center
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 十、当前进度 & 下一步
|
||||
|
||||
### 子任务一 ✅ 已完成
|
||||
1. 全部 18 个 Shortcut 模块 + 94 个命令
|
||||
2. 7 个批量操作命令
|
||||
3. Showcase 展示页（12 个模块，可在线运行）
|
||||
4. GitLink DevOps 流水线（push 自动部署）
|
||||
5. 单元测试 47+ 个
|
||||
6. Showcase 各种 bug 修复（布尔参数、null 显示、重复参数、member ID 提示）
|
||||
7. 12 个 AI Agent Skills（基础版）
|
||||
|
||||
### 子任务二 🔄 进行中（截止 6月18日）
|
||||
|
||||
#### 第一步：开发新 Skill ✅ 已完成
|
||||
- [x] `gitlink-health` — 项目健康度报告 Skill
|
||||
- [x] SKILL.md（主文件 + CRITICAL 读 REFERENCE）
|
||||
- [x] REFERENCE.md（评分算法 + fallback 策略 + 社区关注度标准）
|
||||
- [x] examples/（健康度报告 + 周报，2026-06-08 真实数据）
|
||||
- [x] VERIFICATION.md（Claude Code 验证通过）
|
||||
- [x] 公平评分验证：77/100（严格按公式计算）
|
||||
- [x] `gitlink-changelog` — Release Notes 自动生成 Skill
|
||||
- [x] SKILL.md（CRITICAL 读 REFERENCE + 完整分类规则）
|
||||
- [x] REFERENCE.md（API 路径修正 + PR 过滤注意事项）
|
||||
- [x] examples/（changelog 生成示例，真实数据）
|
||||
- [x] VERIFICATION.md（Claude Code 验证通过）
|
||||
- [x] `gitlink-triage` — Issue 智能分拣 + 新人引导 Skill
|
||||
- [x] SKILL.md（CRITICAL 读 REFERENCE + subject 保留警告）
|
||||
- [x] REFERENCE.md（颜色码修正 + 标签映射说明）
|
||||
- [x] examples/（6 Issue 批量分拣示例，真实数据）
|
||||
- [x] VERIFICATION.md（Claude Code 验证通过）
|
||||
|
||||
#### 第二步：完善已有 Skill
|
||||
- [ ] gitlink-workflow 升级为独立完整 Skill（当前仅为简单骨架）
|
||||
- [ ] 补充 gitlink-ci、gitlink-pm 的 REFERENCE.md + examples
|
||||
- [ ] 为所有 Skill 补充 VERIFICATION.md
|
||||
|
||||
#### 第三步：文档撰写
|
||||
- [ ] 向 gitlink-cli 主仓库提交 Skills PR
|
||||
- [ ] 撰写《软件分析及建模报告》
|
||||
- [ ] 撰写《新需求构思报告》
|
||||
- [ ] 撰写《变更影响分析及测试报告》
|
||||
- [ ] 变更说明文档
|
||||
512
README.md
512
README.md
|
|
@ -1,183 +1,433 @@
|
|||
# GitLink CLI · 智能化能力提升
|
||||
# gitlink-cli
|
||||
|
||||
> 让 AI 智能体和开发者都能在终端高效操控 GitLink 平台，把仓库管理、Issue/PR 协作、CI/CD 变成可自动化、可复现的流程。
|
||||
[](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
|
||||
[](https://license.coscl.org.cn/MulanPSL2)
|
||||
[](https://golang.org)
|
||||
[](https://www.npmjs.com/package/@gitlink-ai/cli)
|
||||
|
||||
**第八届 CCF 开源创新大赛 · track1 GitLink-CLI 贡献赛**参赛作品。
|
||||
The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans and AI Agents. Supports **macOS, Linux, and Windows**. Covers repository management, issue tracking, pull requests, CI/CD, and AI-powered workflows, with 40+ commands and 12 AI Agent [Skills](./skills/).
|
||||
|
||||
---
|
||||
**[中文文档](./README.zh-CN.md)**
|
||||
|
||||
## 项目简介
|
||||
[Install](#installation--quick-start) · [AI Agent Skills](#ai-agent-skills) · [Auth](#configure--use) · [Commands](#usage-examples) · [Contributing](#related-projects)
|
||||
|
||||
随着 Claude Code、Cursor 等 AI 编程智能体兴起，开发者正从"手动操作平台"转向"Agent 驱动开发"。但 GitLink 平台的能力长期锁在网页 GUI 里——AI 看不到、调不动，开发者也得在终端和浏览器间反复切换。
|
||||
## Why gitlink-cli?
|
||||
|
||||
本项目围绕 [gitlink-cli](https://gitlink.org.cn/gitlink/gitlink-cli) 做了四件事：
|
||||
- **Agent-Native Design** — 12 structured [Skills](./skills/) out of the box, compatible with Claude Code, OpenClaw, and other AI platforms — Agents can operate GitLink with zero extra setup
|
||||
- **Wide Coverage** — Repository, Issue, PR, Branch, Release, CI, Org, Search, User — all core domains covered
|
||||
- **AI-Friendly & Optimized** — Every command is tested with real Agents, featuring concise parameters, smart defaults, and structured output
|
||||
- **Cross-Platform** — Runs on macOS, Linux, and Windows (x64/arm64), install via `npm install -g @gitlink-ai/cli` in one command, binary auto-downloaded
|
||||
- **Open Source, Zero Barriers** — MulanPSL-2.0 license, ready to use, just `npm install`
|
||||
- **Up and Running in 3 Minutes** — Interactive login or `GITLINK_TOKEN` env var, from install to first API call in just 3 steps
|
||||
- **Secure & Controllable** — OS-native keychain credential storage, `GITLINK_TOKEN` env var for CI/CD & non-interactive environments, auto git remote context resolution
|
||||
- **Scriptable Output** — Designed for repeatable terminal workflows and automation pipelines
|
||||
- **Three-Layer Architecture** — Shortcuts (human & AI friendly) → Raw API (full coverage) → Config (configuration management)
|
||||
|
||||
1. **把平台能力命令化**——新增 19 个命令模块、110 条命令，让每类操作都能在终端一行命令完成
|
||||
2. **给 AI 写使用说明书**——23 个 Skill，让 Claude Code 等智能体直接会操控 GitLink
|
||||
3. **串成端到端工作流**——自研工作流引擎，一行命令把多个 Skill 串成自动化流水线
|
||||
4. **延伸到科研场景**——科研项目洞悉、FAIR 合规检查、贡献者画像
|
||||
## Features
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 命令模块 | 19 个（110 条命令） |
|
||||
| 批量操作 | 11 条（全部支持 `--dry-run` 预演） |
|
||||
| AI Agent Skill | 23 个 |
|
||||
| 预置工作流 | 5 个 |
|
||||
| 单元测试 | 187 个 |
|
||||
| 交叉编译平台 | 8 个（Win/Linux/macOS/FreeBSD × amd64/arm64） |
|
||||
| Category | Capabilities |
|
||||
|----------|-------------|
|
||||
| 📦 Repo | List, create, fork, delete repositories, view repo info |
|
||||
| 🐛 Issue | Create, update, close, batch close, comment on issues |
|
||||
| 🔀 PR | Create, merge, review pull requests, view changed files |
|
||||
| 🌿 Branch | Create, delete, list, protect, unprotect branches |
|
||||
| 🏷️ Release | Create, view, delete releases |
|
||||
| 🏢 Org | Manage organizations, members, teams |
|
||||
| 🔧 CI | View builds, logs, CI/CD operations |
|
||||
| 🔍 Search | Search repositories, users |
|
||||
| 👤 User | View user profiles and info |
|
||||
| 📋 PM | Sprint management, kanban boards, weekly reports |
|
||||
| 🤖 Workflow | AI-powered issue triage, PR review, release notes |
|
||||
|
||||
---
|
||||
## Installation & Quick Start
|
||||
|
||||
## 四大子赛题成果
|
||||
### Requirements
|
||||
|
||||
### 子赛题一 · 增加 CLI 能力
|
||||
新增 19 个 Shortcut 模块（仓库/Issue/PR/Release/CI/Webhook/标签/里程碑/Wiki/工作流…），11 条批量操作，修复跨平台兼容性（Windows/Linux/macOS/FreeBSD）。已向主仓库提交 PR。
|
||||
- 代码：[`shortcuts/`](shortcuts/)、[`internal/`](internal/)、[`cmd/`](cmd/)
|
||||
- 提交材料：[`提交材料/子赛题一-CLI能力/`](提交材料/子赛题一-CLI能力/)
|
||||
- Node.js 14+ (`npm`/`npx`) — for npm installation
|
||||
- Supported platforms: macOS, Linux, Windows (x64/arm64)
|
||||
- Go 1.26+ — only required for building from source
|
||||
|
||||
### 子赛题二 · 编写 Skills
|
||||
23 个 Skill（命令操作类 + 智能分析型），覆盖健康度报告、Release Notes 生成、Issue 智能分拣、智能代码审查、许可证合规、科研辅助等。一键 `setup-skills.sh` 装进 Claude Code 即可用 `/gitlink-xxx` 调用。
|
||||
- 代码：[`skills/`](skills/)
|
||||
- 演示录屏：[`提交材料/子赛题二-Skills/demos/`](提交材料/子赛题二-Skills/demos/)
|
||||
### Quick Start (Human Users)
|
||||
|
||||
### 子赛题三 · 端到端工作流
|
||||
自研工作流引擎（`shortcuts/workflow/`），AI/规则双模式，5 个预置工作流（代码质量看门人/社区运营自动化/贡献者成长/多仓库协同/项目一键初始化），支持手动/轮询/定时触发，systemd 7×24 自动运行。
|
||||
- 代码：[`shortcuts/workflow/`](shortcuts/workflow/)
|
||||
- 提交材料：[`提交材料/子赛题三-工作流/`](提交材料/子赛题三-工作流/)
|
||||
> **Note for AI assistants:** If you are an AI Agent helping the user with installation, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent), which contains all the steps you need to complete.
|
||||
|
||||
### 子赛题四 · 辅助科研
|
||||
gitlink-spark（科研软件 X 光）、gitlink-research-fair（FAIR 合规检查）、gitlink-contributor-ranking（贡献者画像），面向科研项目洞悉、合规校验、协作匹配。
|
||||
- 代码：[`skills/gitlink-spark`](skills/gitlink-spark)、[`skills/gitlink-research-fair`](skills/gitlink-research-fair)
|
||||
- 提交材料：[`提交材料/子赛题四-科研/`](提交材料/子赛题四-科研/)
|
||||
#### Install
|
||||
|
||||
> 📁 所有变更说明、演示录屏/截图集中在 [`提交材料/`](提交材料/) 目录。
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 安装
|
||||
**From npm (recommended):**
|
||||
|
||||
```bash
|
||||
# 方式一：go install（需 Go 1.26+）
|
||||
go install github.com/gitlink-org/gitlink-cli@latest
|
||||
|
||||
# 方式二：npm
|
||||
# One command: installs CLI binary + all 12 AI Agent Skills
|
||||
npm install -g @gitlink-ai/cli
|
||||
|
||||
# 方式三：下载预编译包（8 平台）
|
||||
# 见 Release 页面
|
||||
```
|
||||
|
||||
### 认证
|
||||
The binary is auto-downloaded for your platform during `postinstall`. No extra steps needed.
|
||||
|
||||
**From source:**
|
||||
|
||||
Requires Go 1.26+.
|
||||
|
||||
```bash
|
||||
gitlink-cli auth login # 浏览器登录，cookie 自动保存
|
||||
gitlink-cli auth status # 查看登录状态
|
||||
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
|
||||
cd gitlink-cli
|
||||
make install
|
||||
```
|
||||
|
||||
### 使用示例
|
||||
> **Windows users:** Run `npm install -g @gitlink-ai/cli` in PowerShell or CMD. For building from source, use `go install .` instead of `make install`.
|
||||
|
||||
#### Configure & Use
|
||||
|
||||
```bash
|
||||
# 列出仓库的 Issue
|
||||
gitlink-cli issue +list --owner gitlink --repo gitlink-cli
|
||||
# 1. Configure (one-time, interactive guided setup)
|
||||
gitlink-cli config init
|
||||
|
||||
# 批量关闭（先预演）
|
||||
gitlink-cli issue +batch-close --numbers 1,2,3 --dry-run
|
||||
# 2. Log in (choose one)
|
||||
gitlink-cli auth login # Username/password (recommended)
|
||||
gitlink-cli auth login --token # Or paste a private token
|
||||
export GITLINK_TOKEN="your-token" # Or set env var (for CI/CD, non-interactive environments)
|
||||
|
||||
# 在 Claude Code 里一句话调用 Skill
|
||||
/gitlink-triage 帮我分拣所有未分类的 Issue
|
||||
# 3. Start using
|
||||
gitlink-cli repo +list
|
||||
```
|
||||
|
||||
### 一键启用 Skills（Claude Code）
|
||||
### Quick Start (AI Agent)
|
||||
|
||||
> The following steps are for AI Agents. Some steps require the user to complete actions in a browser.
|
||||
|
||||
**Step 1 — Install**
|
||||
|
||||
```bash
|
||||
bash scripts/setup-skills.sh # 把 skills/ 链接到 ~/.claude/skills/
|
||||
# 之后在 Claude Code 里就能 /gitlink-xxx 调用
|
||||
# One command: CLI binary + all Skills auto-installed
|
||||
npm install -g @gitlink-ai/cli
|
||||
```
|
||||
|
||||
### 在线演示
|
||||
**Step 2 — Configure**
|
||||
|
||||
Showcase Dashboard：<http://118.31.4.168:9090> —— 浏览器里点卡片就能跑命令，无需安装。
|
||||
|
||||
---
|
||||
|
||||
## 架构说明
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 入口层 cmd/ main.go → root.go (cobra root) │
|
||||
│ 4 个基础命令: auth / api / config / version │
|
||||
│ 全局 flag: --owner/--repo/--format/--debug │
|
||||
└───────────────┬──────────────────────────────────────────┘
|
||||
│ shortcuts.RegisterAll(rootCmd)
|
||||
┌───────────────▼──────────────────────────────────────────┐
|
||||
│ 业务层 shortcuts/ 19 组 × 100+ 命令 + 工作流引擎 │
|
||||
│ register.go 命令注册中枢 │
|
||||
│ common/ RuntimeContext 业务统一上下文 │
|
||||
│ workflow/ 工作流引擎（AI/规则双模式 + 5 预置流） │
|
||||
└───────────────┬──────────────────────────────────────────┘
|
||||
│ RuntimeContext.CallAPI / Output
|
||||
┌───────────────▼──────────────────────────────────────────┐
|
||||
│ 基础层 internal/ Go 内部包，不对外暴露 │
|
||||
│ client/ HTTP 客户端 + .json 后缀 + 错误检测 │
|
||||
│ auth/ Transport 自动注入 Cookie/access_token │
|
||||
│ config/ YAML 配置 + 跨平台路径 │
|
||||
│ output/ Envelope(ok/data/meta) + json/yaml/table │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
|
||||
独立的 AI 层 skills/ 23 个 SKILL.md，面向 AI Agent 的自然语言说明书
|
||||
（非编译期依赖，指导 Agent 调用编译好的二进制）
|
||||
```bash
|
||||
gitlink-cli config init
|
||||
```
|
||||
|
||||
**核心设计**：业务命令只依赖 `RuntimeContext`，绝不直接接触 cobra/HTTP 细节——新增模块只挂一个 `shortcuts/` 子包，不动入口与基础层。这是 19 模块 100+ 命令仍保持可测试性的根本。
|
||||
**Step 3 — Login**
|
||||
|
||||
---
|
||||
For interactive environments:
|
||||
```bash
|
||||
gitlink-cli auth login
|
||||
```
|
||||
|
||||
## 目录结构
|
||||
For non-interactive environments (CI/CD, Trae sandbox, MCP, etc.):
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
```
|
||||
|
||||
> To get a private token, go to GitLink web → Settings → Private Tokens.
|
||||
|
||||
**Step 4 — Verify**
|
||||
|
||||
```bash
|
||||
gitlink-cli user +me
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Repository Operations
|
||||
|
||||
```bash
|
||||
# List repositories
|
||||
gitlink-cli repo +list
|
||||
|
||||
# View repository info
|
||||
gitlink-cli repo +info --owner Gitlink --repo forgeplus
|
||||
|
||||
# Create a repository
|
||||
gitlink-cli repo +create -n my-project -d "Project description"
|
||||
|
||||
# Fork a repository
|
||||
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
|
||||
```
|
||||
|
||||
### Issue Management
|
||||
|
||||
```bash
|
||||
# List issues
|
||||
gitlink-cli issue +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# Create an issue
|
||||
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" -b "Steps to reproduce..."
|
||||
|
||||
# View an issue
|
||||
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
|
||||
|
||||
# Close an issue
|
||||
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
|
||||
|
||||
# Preview batch close without changing data
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,124 --dry-run
|
||||
|
||||
# Batch close issues from a CSV file
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv
|
||||
|
||||
# Add a comment
|
||||
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "Fixed"
|
||||
```
|
||||
|
||||
### Pull Requests
|
||||
|
||||
```bash
|
||||
# List PRs
|
||||
gitlink-cli pr +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# Create a PR (same-repo branch)
|
||||
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: Search feature" --head feature/search --base master
|
||||
|
||||
# Create a PR (from a fork)
|
||||
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: New feature" --head your_username/forgeplus:feature/my-feature --base master
|
||||
|
||||
# View a PR
|
||||
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42
|
||||
|
||||
# Merge a PR
|
||||
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
|
||||
|
||||
# View changed files
|
||||
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
|
||||
```
|
||||
|
||||
### Branch Management
|
||||
|
||||
```bash
|
||||
# List branches
|
||||
gitlink-cli branch +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# Create a branch
|
||||
gitlink-cli branch +create --name feature/new-feature
|
||||
|
||||
# Delete a branch
|
||||
gitlink-cli branch +delete --name feature/old-feature
|
||||
|
||||
# Protect a branch
|
||||
gitlink-cli branch +protect --name main
|
||||
|
||||
# Remove branch protection
|
||||
gitlink-cli branch +unprotect --name main
|
||||
```
|
||||
|
||||
### Release Management
|
||||
|
||||
```bash
|
||||
# List releases
|
||||
gitlink-cli release +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# Create a release
|
||||
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..."
|
||||
|
||||
# View a release
|
||||
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
|
||||
```
|
||||
|
||||
### CI/CD Operations
|
||||
|
||||
```bash
|
||||
# List builds
|
||||
gitlink-cli ci +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# View build log
|
||||
gitlink-cli ci +log --owner Gitlink --repo forgeplus -i <build_id>
|
||||
|
||||
# Restart a build
|
||||
gitlink-cli ci +restart --owner Gitlink --repo forgeplus -i <build_id>
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```bash
|
||||
# Search repositories
|
||||
gitlink-cli search +repos -k "machine learning"
|
||||
|
||||
# Search users
|
||||
gitlink-cli search +users -k "zhangsan"
|
||||
```
|
||||
|
||||
### Raw API
|
||||
|
||||
For endpoints not covered by shortcuts, use the Raw API directly:
|
||||
|
||||
```bash
|
||||
# GET request
|
||||
gitlink-cli api GET /users/me
|
||||
|
||||
# POST request
|
||||
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
|
||||
|
||||
# With query parameters
|
||||
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
|
||||
```
|
||||
|
||||
## Global Parameters
|
||||
|
||||
| Parameter | Description | Example |
|
||||
|-----------|-------------|---------|
|
||||
| `--owner` | Repository owner | `--owner Gitlink` |
|
||||
| `--repo` | Repository name | `--repo forgeplus` |
|
||||
| `--format` | Output format (json/table/yaml) | `--format json` |
|
||||
| `--debug` | Enable debug output | `--debug` |
|
||||
|
||||
**Automatic context resolution:** When running inside a git repository, `--owner` and `--repo` are automatically resolved from `git remote origin`.
|
||||
|
||||
## Branch Conventions
|
||||
|
||||
gitlink-cli supports bidirectional code sync between GitHub and GitLink:
|
||||
|
||||
| Platform | Default Branch |
|
||||
|----------|---------------|
|
||||
| GitHub | `main` |
|
||||
| GitLink | `master` |
|
||||
|
||||
**Push to GitLink from local:**
|
||||
|
||||
```bash
|
||||
# Method 1: Use git command directly
|
||||
git push gitlink main:master
|
||||
|
||||
# Method 2: Configure git remote
|
||||
git config remote.gitlink.push refs/heads/main:refs/heads/master
|
||||
git push gitlink
|
||||
```
|
||||
|
||||
## AI Agent Skills
|
||||
|
||||
The `skills/` directory contains 12 Agent Skill files for AI-automated GitLink operations.
|
||||
|
||||
See [skills/README.md](skills/README.md) for details.
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `gitlink-shared` | Authentication, global parameters, safety rules, API notes |
|
||||
| `gitlink-repo` | Repository operations (create, view, delete, fork, etc.) |
|
||||
| `gitlink-issue` | Issue operations (create, update, close, comment, etc.) |
|
||||
| `gitlink-pr` | Pull request operations (create, merge, review, etc.) |
|
||||
| `gitlink-branch` | Branch management (create, delete, list, protect, unprotect) |
|
||||
| `gitlink-release` | Release management (create, view, delete, etc.) |
|
||||
| `gitlink-ci` | CI/CD operations (builds, logs, etc.) |
|
||||
| `gitlink-search` | Search (repositories, users, etc.) |
|
||||
| `gitlink-org` | Organization management (members, teams, etc.) |
|
||||
| `gitlink-user` | User management (profile info, etc.) |
|
||||
| `gitlink-pm` | Project management (sprints, kanban, weekly reports, etc.) |
|
||||
| `gitlink-workflow` | AI-powered workflows (issue triage, PR review, release notes, etc.) |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
gitlink-cli/
|
||||
├── README.md # 本文件
|
||||
├── cmd/ # 入口层（auth/api/config/version）
|
||||
├── shortcuts/ # 业务层（19 命令模块 + workflow 工作流引擎）
|
||||
├── internal/ # 基础层（client/auth/config/output/context/errors）
|
||||
├── skills/ # 23 个 AI Agent Skill
|
||||
├── showcase/ # 在线演示 Dashboard（Go 单二进制）
|
||||
├── scripts/ # 脚本（setup-skills.sh 等）
|
||||
├── docs/ # 设计文档、API 参考
|
||||
└── 提交材料/ # ★ 比赛提交材料（变更说明 + 演示录屏/截图）
|
||||
├── 子赛题一-CLI能力/
|
||||
├── 子赛题二-Skills/
|
||||
├── 子赛题三-工作流/
|
||||
└── 子赛题四-科研/
|
||||
├── cmd/ # Cobra command definitions
|
||||
│ ├── root.go # Root command + global flags
|
||||
│ ├── auth/ # Authentication commands
|
||||
│ ├── api/ # Raw API commands
|
||||
│ ├── config/ # Configuration commands
|
||||
│ └── cmdutil/ # Global utilities
|
||||
├── internal/ # Internal packages
|
||||
│ ├── auth/ # Login, token storage, transport
|
||||
│ ├── client/ # HTTP client + pagination
|
||||
│ ├── config/ # Config file management
|
||||
│ ├── context/ # Git remote resolution
|
||||
│ └── output/ # Envelope + formatter
|
||||
├── shortcuts/ # Shortcut implementations
|
||||
│ ├── common/ # Framework (types, runner)
|
||||
│ ├── repo/ # Repository shortcuts
|
||||
│ ├── issue/ # Issue shortcuts
|
||||
│ ├── pr/ # PR shortcuts
|
||||
│ ├── branch/ # Branch shortcuts
|
||||
│ ├── release/ # Release shortcuts
|
||||
│ ├── org/ # Organization shortcuts
|
||||
│ ├── ci/ # CI shortcuts
|
||||
│ ├── search/ # Search shortcuts
|
||||
│ ├── user/ # User shortcuts
|
||||
│ └── register.go # Registration entry point
|
||||
├── skills/ # AI Agent Skills
|
||||
│ ├── README.md # Skills guide
|
||||
│ ├── gitlink-shared/ # Shared rules
|
||||
│ ├── gitlink-repo/ # Repository skill
|
||||
│ ├── gitlink-issue/ # Issue skill
|
||||
│ ├── gitlink-pr/ # PR skill
|
||||
│ ├── gitlink-pm/ # Project management skill
|
||||
│ └── ...
|
||||
├── doc/ # Design documents
|
||||
│ ├── Design.md
|
||||
│ ├── CODE_SYNC_STRATEGY_FINAL.md
|
||||
│ └── ...
|
||||
├── main.go
|
||||
├── Makefile
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
---
|
||||
## Documentation
|
||||
|
||||
## 技术栈
|
||||
- [Skills Guide](skills/README.md) — AI Agent Skills detailed documentation
|
||||
- [Design Document](doc/design.md) — Architecture design and development plan
|
||||
|
||||
- **语言**：Go 1.26（子赛题一）；Markdown/Shell（子赛题二三四）
|
||||
- **CLI 框架**：spf13/cobra
|
||||
- **密钥存储**：zalando/go-keyring（OS keychain + 文件 fallback）
|
||||
- **配置**：gopkg.in/yaml.v3
|
||||
- **CI/CD**：GitLink DevOps（建木引擎）自动部署 + GitHub Actions 8 平台发版
|
||||
## FAQ
|
||||
|
||||
---
|
||||
### Q: How do I use gitlink-cli in scripts?
|
||||
|
||||
## 团队
|
||||
Use the `GITLINK_TOKEN` environment variable + `--format json` for structured output:
|
||||
|
||||
| 成员 | 负责 |
|
||||
|------|------|
|
||||
| chroe | CLI 核心模块、Showcase、CI/CD、health/changelog/triage Skill、工作流引擎 |
|
||||
| yetja | 批量操作、单元测试、license/repo/org Skill、工作流规则引擎 |
|
||||
| caoweiqiong | file/member/watch/star 模块、review Skill、FreeBSD 支持 |
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
gitlink-cli repo +list --format json | jq '.data.projects[] | .name'
|
||||
```
|
||||
|
||||
---
|
||||
### Q: How does automatic owner/repo resolution work?
|
||||
|
||||
## 相关链接
|
||||
When running inside a git repository, the CLI automatically resolves `--owner` and `--repo` from `git remote origin`:
|
||||
|
||||
- 上游仓库：<https://gitlink.org.cn/gitlink/gitlink-cli>
|
||||
- 本项目（Fork）：<https://gitlink.org.cn/chroe/gitlink-cli>
|
||||
- 在线 Showcase：<http://118.31.4.168:9090>
|
||||
- Skills 开发指南：[`skills/README.md`](skills/README.md)
|
||||
```bash
|
||||
cd ~/my-gitlink-project
|
||||
gitlink-cli issue +list # Automatically uses the current repository
|
||||
```
|
||||
|
||||
### Q: What if my token expires?
|
||||
|
||||
Re-authenticate:
|
||||
|
||||
```bash
|
||||
# Username/password login
|
||||
gitlink-cli auth login
|
||||
|
||||
# Or use a private token (generate at GitLink web → Settings → Private Tokens)
|
||||
gitlink-cli auth login --token
|
||||
```
|
||||
|
||||
### Q: How do I use gitlink-cli in CI/CD or non-interactive environments (e.g. Trae sandbox)?
|
||||
|
||||
Set the `GITLINK_TOKEN` environment variable — no `auth login` needed:
|
||||
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
gitlink-cli repo +list # Ready to use
|
||||
gitlink-cli auth status # Shows "✓ Logged in via GITLINK_TOKEN environment variable"
|
||||
```
|
||||
|
||||
Priority: `GITLINK_TOKEN` env var > keyring/file stored token. When the env var is not set, the original interactive login flow works as before.
|
||||
|
||||
### Q: What if npm installs successfully but `gitlink-cli` reports a missing binary?
|
||||
|
||||
Reinstall first:
|
||||
|
||||
```bash
|
||||
npm install -g @gitlink-ai/cli
|
||||
```
|
||||
|
||||
If the error persists, check whether the release page contains the asset for your platform, for example `gitlink-cli_<version>_windows_amd64.zip` on Windows x64. You can also download the binary manually from the release page or build from source with `go install .`.
|
||||
|
||||
### Q: Where are credentials stored on Windows?
|
||||
|
||||
gitlink-cli uses Windows Credential Manager for secure token storage. If Credential Manager is unavailable, it automatically falls back to file storage (`~/.config/gitlink-cli/credentials`).
|
||||
|
||||
### Q: Where can I find the full API reference?
|
||||
|
||||
See [skills/gitlink-shared/REFERENCE.md](skills/gitlink-shared/REFERENCE.md).
|
||||
|
||||
## License
|
||||
|
||||
[MulanPSL-2.0](https://license.coscl.org.cn/MulanPSL2)
|
||||
|
||||
> This line is for PR workflow testing, can be reverted after merge.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,409 @@
|
|||
# gitlink-cli
|
||||
|
||||
[](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
|
||||
[](https://license.coscl.org.cn/MulanPSL2)
|
||||
[](https://golang.org)
|
||||
[](https://www.npmjs.com/package/@gitlink-ai/cli)
|
||||
|
||||
[GitLink（确实开源）](https://www.gitlink.org.cn) 官方 CLI 工具 — 为人类和 AI Agent 双重设计。支持 **macOS、Linux、Windows**，覆盖仓库管理、Issue 追踪、Pull Request、CI/CD 和 AI 自动化工作流，包含 40+ 命令和 11 个 AI Agent [Skills](./skills/)。
|
||||
|
||||
**[English](./README.md)**
|
||||
|
||||
[安装](#安装与快速上手) · [AI Agent Skills](#ai-agent-skills) · [认证](#配置与使用) · [命令](#使用示例) · [贡献](#相关项目)
|
||||
|
||||
## 为什么选择 gitlink-cli？
|
||||
|
||||
- **Agent-Native 设计** — 开箱即用 11 个结构化 [Skills](./skills/)，兼容 Claude Code — Agent 零配置即可操作 GitLink
|
||||
- **广泛覆盖** — 仓库、Issue、PR、分支、Release、CI、组织、搜索、用户 — 核心功能全覆盖
|
||||
- **AI 友好 & 优化** — 每条命令都经过真实 Agent 测试，简洁参数、智能默认值、结构化输出
|
||||
- **跨平台** — macOS、Linux、Windows (x64/arm64) 全支持，`npm` 一条命令安装
|
||||
- **开源零门槛** — 木兰宽松许可证第2版（MulanPSL-2.0），`npm install` 即用
|
||||
- **3 分钟上手** — 交互式登录或 `GITLINK_TOKEN` 环境变量，从安装到首次 API 调用仅需 3 步
|
||||
- **安全可控** — OS 原生 keychain 凭证存储，`GITLINK_TOKEN` 环境变量支持 CI/CD 和非交互环境，自动 git remote 上下文解析
|
||||
- **三层架构** — Shortcuts（人+AI友好）→ Raw API（全覆盖）→ Config（配置管理）
|
||||
|
||||
## 功能一览
|
||||
|
||||
| 分类 | 能力 |
|
||||
|------|------|
|
||||
| 📦 仓库 | 列出、创建、Fork、删除仓库，查看仓库信息 |
|
||||
| 🐛 Issue | 创建、更新、关闭、批量关闭、评论 Issue |
|
||||
| 🔀 PR | 创建、合并、Review Pull Request，查看变更文件 |
|
||||
| 🌿 分支 | 创建、删除、保护分支 |
|
||||
| 🏷️ 发布 | 创建、查看、删除 Release |
|
||||
| 🏢 组织 | 管理组织、成员、团队 |
|
||||
| 🔧 CI | 查看构建、日志、CI/CD 操作 |
|
||||
| 🔍 搜索 | 搜索仓库、用户 |
|
||||
| 👤 用户 | 查看用户资料和信息 |
|
||||
| 📋 项目管理 | Sprint 管理、看板、周报 |
|
||||
| 🤖 工作流 | AI 驱动的 Issue 分类、PR Review、Release Notes |
|
||||
|
||||
## 安装与快速上手
|
||||
|
||||
### 前置条件
|
||||
|
||||
- Node.js 14+（`npm`/`npx`）— 用于 npm 安装
|
||||
- 支持平台：macOS、Linux、Windows（x64/arm64）
|
||||
- Go 1.26+ — 仅从源码构建时需要
|
||||
|
||||
### 快速上手（人类用户）
|
||||
|
||||
> **AI 助手请注意：** 如果你是帮助用户安装的 AI Agent，请直接跳到 [快速上手（AI Agent）](#快速上手ai-agent)，其中包含你需要完成的所有步骤。
|
||||
|
||||
#### 安装
|
||||
|
||||
选择以下**任一**方式：
|
||||
|
||||
**方式 1 — 从 npm 安装（推荐）：**
|
||||
|
||||
```bash
|
||||
# 安装 CLI
|
||||
npm install -g @gitlink-ai/cli
|
||||
|
||||
# 安装 CLI Skill（必须，全平台通用）
|
||||
gitlink-cli-install-skills
|
||||
|
||||
# 也可使用 npx 安装 Skill
|
||||
npx skills add ccfos/gitlink-cli/skills -y -g
|
||||
```
|
||||
|
||||
**方式 2 — 从源码构建：**
|
||||
|
||||
需要 Go 1.26+。
|
||||
|
||||
```bash
|
||||
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
|
||||
cd gitlink-cli
|
||||
make install
|
||||
|
||||
# 安装 CLI Skill（必须）
|
||||
npx skills add ./skills -y -g
|
||||
```
|
||||
|
||||
> **Windows 用户注意：** 请在 PowerShell 或 CMD 中运行 `npm install -g @gitlink-ai/cli`。从源码构建请使用 `go install .` 代替 `make install`。
|
||||
|
||||
#### 配置与使用
|
||||
|
||||
```bash
|
||||
# 1. 配置（首次使用，交互式引导）
|
||||
gitlink-cli config init
|
||||
|
||||
# 2. 登录（任选其一）
|
||||
gitlink-cli auth login # 用户名密码（推荐）
|
||||
gitlink-cli auth login --token # 或粘贴私人令牌
|
||||
export GITLINK_TOKEN="your-token" # 或设置环境变量（适用于 CI/CD、非交互环境）
|
||||
|
||||
# 3. 开始使用
|
||||
gitlink-cli repo +list
|
||||
```
|
||||
|
||||
### 快速上手（AI Agent）
|
||||
|
||||
> 以下步骤面向 AI Agent。部分步骤需要用户在浏览器中完成操作。
|
||||
|
||||
**第 1 步 — 安装**
|
||||
|
||||
```bash
|
||||
# 安装 CLI
|
||||
npm install -g @gitlink-ai/cli
|
||||
|
||||
# 安装 CLI Skill（必须，全平台通用）
|
||||
gitlink-cli-install-skills
|
||||
```
|
||||
|
||||
**第 2 步 — 配置**
|
||||
|
||||
```bash
|
||||
gitlink-cli config init
|
||||
```
|
||||
|
||||
**第 3 步 — 登录**
|
||||
|
||||
交互环境：
|
||||
```bash
|
||||
gitlink-cli auth login
|
||||
```
|
||||
|
||||
非交互环境（CI/CD、Trae 沙箱、MCP 等）：
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
```
|
||||
|
||||
> 获取私人令牌：GitLink 网页端 → 个人设置 → 私人令牌。
|
||||
|
||||
**第 4 步 — 验证**
|
||||
|
||||
```bash
|
||||
gitlink-cli user +me
|
||||
```
|
||||
|
||||
## 使用示例
|
||||
|
||||
### 仓库操作
|
||||
|
||||
```bash
|
||||
# 列出仓库
|
||||
gitlink-cli repo +list
|
||||
|
||||
# 查看仓库信息
|
||||
gitlink-cli repo +info --owner Gitlink --repo forgeplus
|
||||
|
||||
# 创建仓库
|
||||
gitlink-cli repo +create -n my-project -d "项目描述"
|
||||
|
||||
# Fork 仓库
|
||||
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
|
||||
```
|
||||
|
||||
### Issue 管理
|
||||
|
||||
```bash
|
||||
# 列出 Issue
|
||||
gitlink-cli issue +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# 创建 Issue
|
||||
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" -b "复现步骤..."
|
||||
|
||||
# 查看 Issue
|
||||
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
|
||||
|
||||
# 关闭 Issue
|
||||
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
|
||||
|
||||
# 预览批量关闭，不修改数据
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --numbers 123,124 --dry-run
|
||||
|
||||
# 从 CSV 文件批量关闭 Issue
|
||||
gitlink-cli issue +batch-close --owner Gitlink --repo forgeplus --from issues.csv
|
||||
|
||||
# 添加评论
|
||||
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "已修复"
|
||||
```
|
||||
|
||||
### Pull Request
|
||||
|
||||
```bash
|
||||
# 列出 PR
|
||||
gitlink-cli pr +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# 创建 PR（同仓库分支）
|
||||
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 搜索功能" --head feature/search --base master
|
||||
|
||||
# 创建 PR（从 Fork 仓库）
|
||||
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 新功能" --head your_username/forgeplus:feature/my-feature --base master
|
||||
|
||||
# 查看 PR
|
||||
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42
|
||||
|
||||
# 合并 PR
|
||||
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
|
||||
|
||||
# 查看 PR 变更文件
|
||||
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
|
||||
```
|
||||
|
||||
### 发布管理
|
||||
|
||||
```bash
|
||||
# 列出 Release
|
||||
gitlink-cli release +list --owner Gitlink --repo forgeplus
|
||||
|
||||
# 创建 Release
|
||||
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."
|
||||
|
||||
# 查看 Release
|
||||
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
|
||||
```
|
||||
|
||||
### 搜索
|
||||
|
||||
```bash
|
||||
# 搜索仓库
|
||||
gitlink-cli search +repos -k "machine learning"
|
||||
|
||||
# 搜索用户
|
||||
gitlink-cli search +users -k "zhangsan"
|
||||
```
|
||||
|
||||
### Raw API
|
||||
|
||||
Shortcuts 未覆盖的接口可通过 Raw API 直接调用：
|
||||
|
||||
```bash
|
||||
# GET 请求
|
||||
gitlink-cli api GET /users/me
|
||||
|
||||
# POST 请求
|
||||
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
|
||||
|
||||
# 带查询参数
|
||||
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
|
||||
```
|
||||
|
||||
## 全局参数
|
||||
|
||||
| 参数 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `--owner` | 仓库所有者 | `--owner Gitlink` |
|
||||
| `--repo` | 仓库名称 | `--repo forgeplus` |
|
||||
| `--format` | 输出格式（json/table/yaml） | `--format json` |
|
||||
| `--debug` | 启用调试输出 | `--debug` |
|
||||
|
||||
**自动上下文解析**：在 git 仓库目录下，`--owner` 和 `--repo` 会自动从 `git remote origin` 解析。
|
||||
|
||||
## 分支约定
|
||||
|
||||
gitlink-cli 支持 GitHub 和 GitLink 的代码双向同步：
|
||||
|
||||
| 平台 | 主分支 |
|
||||
|------|--------|
|
||||
| GitHub | `main` |
|
||||
| GitLink | `master` |
|
||||
|
||||
**本地 push 到 GitLink**：
|
||||
|
||||
```bash
|
||||
# 方式 1：使用 git 命令
|
||||
git push gitlink main:master
|
||||
|
||||
# 方式 2：配置 git remote
|
||||
git config remote.gitlink.push refs/heads/main:refs/heads/master
|
||||
git push gitlink
|
||||
```
|
||||
|
||||
## AI Agent Skills
|
||||
|
||||
`skills/` 目录包含 11 个 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台。
|
||||
|
||||
详见 [skills/README.md](skills/README.md)
|
||||
|
||||
| Skill | 说明 |
|
||||
|-------|------|
|
||||
| `gitlink-shared` | 认证、全局参数、安全规则、API 注意事项 |
|
||||
| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork 等） |
|
||||
| `gitlink-issue` | Issue 操作（创建、更新、关闭、评论等） |
|
||||
| `gitlink-pr` | Pull Request 操作（创建、合并、Review 等） |
|
||||
| `gitlink-release` | 发布管理（创建、查看、删除等） |
|
||||
| `gitlink-org` | 组织管理（成员、团队等） |
|
||||
| `gitlink-ci` | CI/CD 操作（构建、日志等） |
|
||||
| `gitlink-search` | 搜索功能（仓库、用户等） |
|
||||
| `gitlink-user` | 用户管理（个人信息等） |
|
||||
| `gitlink-pm` | 项目管理（Sprint、看板、周报等） |
|
||||
| `gitlink-workflow` | AI 自动化工作流（Issue 分类、PR Review、Release Notes 等） |
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
gitlink-cli/
|
||||
├── cmd/ # Cobra 命令定义
|
||||
│ ├── root.go # 根命令 + 全局 flags
|
||||
│ ├── auth/ # 认证命令
|
||||
│ ├── api/ # Raw API 命令
|
||||
│ ├── config/ # 配置命令
|
||||
│ └── cmdutil/ # 全局工具
|
||||
├── internal/ # 内部包
|
||||
│ ├── auth/ # 登录、Token 存储、Transport
|
||||
│ ├── client/ # HTTP 客户端 + 分页
|
||||
│ ├── config/ # 配置文件管理
|
||||
│ ├── context/ # git remote 解析
|
||||
│ └── output/ # Envelope + Formatter
|
||||
├── shortcuts/ # Shortcut 实现
|
||||
│ ├── common/ # 框架（types, runner）
|
||||
│ ├── repo/ # 仓库 shortcuts
|
||||
│ ├── issue/ # Issue shortcuts
|
||||
│ ├── pr/ # PR shortcuts
|
||||
│ ├── branch/ # 分支 shortcuts
|
||||
│ ├── release/ # Release shortcuts
|
||||
│ ├── org/ # 组织 shortcuts
|
||||
│ ├── ci/ # CI shortcuts
|
||||
│ ├── search/ # 搜索 shortcuts
|
||||
│ ├── user/ # 用户 shortcuts
|
||||
│ └── register.go # 注册入口
|
||||
├── skills/ # AI Agent Skills
|
||||
│ ├── README.md # Skills 使用指南
|
||||
│ ├── gitlink-shared/ # 共享规则
|
||||
│ ├── gitlink-repo/ # 仓库 Skill
|
||||
│ ├── gitlink-issue/ # Issue Skill
|
||||
│ ├── gitlink-pr/ # PR Skill
|
||||
│ ├── gitlink-pm/ # 项目管理 Skill
|
||||
│ └── ...
|
||||
├── doc/ # 设计文档
|
||||
│ ├── Design.md
|
||||
│ ├── CODE_SYNC_STRATEGY_FINAL.md
|
||||
│ └── ...
|
||||
├── main.go
|
||||
├── Makefile
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## 文档
|
||||
|
||||
- [Skills 使用指南](skills/README.md) — AI Agent Skills 详细说明
|
||||
- [设计文档](doc/design.md) — 架构设计和开发计划
|
||||
|
||||
## 常见问题
|
||||
|
||||
### Q: 如何在脚本中使用 gitlink-cli？
|
||||
|
||||
使用 `GITLINK_TOKEN` 环境变量 + `--format json` 获取结构化输出：
|
||||
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
gitlink-cli repo +list --format json | jq '.data.projects[] | .name'
|
||||
```
|
||||
|
||||
### Q: 如何自动解析 owner/repo？
|
||||
|
||||
在 git 仓库目录下运行命令，CLI 会自动从 `git remote origin` 解析：
|
||||
|
||||
```bash
|
||||
cd ~/my-gitlink-project
|
||||
gitlink-cli issue +list # 自动使用当前仓库
|
||||
```
|
||||
|
||||
### Q: Token 过期了怎么办？
|
||||
|
||||
重新登录：
|
||||
|
||||
```bash
|
||||
# 用户名密码登录
|
||||
gitlink-cli auth login
|
||||
|
||||
# 或使用私人令牌（在 GitLink 网页端 个人设置 → 私人令牌 中生成）
|
||||
gitlink-cli auth login --token
|
||||
```
|
||||
|
||||
### Q: 如何在 CI/CD 或非交互环境（Trae 沙箱等）中使用？
|
||||
|
||||
设置 `GITLINK_TOKEN` 环境变量即可，无需 `auth login`：
|
||||
|
||||
```bash
|
||||
export GITLINK_TOKEN="your-private-token"
|
||||
gitlink-cli repo +list # 直接可用
|
||||
gitlink-cli auth status # 显示 "✓ Logged in via GITLINK_TOKEN environment variable"
|
||||
```
|
||||
|
||||
Token 优先级：`GITLINK_TOKEN` 环境变量 > keyring/文件存储的 token。不设置环境变量时完全兼容原有交互式登录。
|
||||
|
||||
### Q: npm 安装成功但 `gitlink-cli` 提示缺少二进制怎么办？
|
||||
|
||||
先尝试重新安装：
|
||||
|
||||
```bash
|
||||
npm install -g @gitlink-ai/cli
|
||||
```
|
||||
|
||||
如果仍然失败，请检查 Release 页面是否包含当前平台的资产，例如 Windows x64 对应 `gitlink-cli_<version>_windows_amd64.zip`。也可以从 Release 页面手动下载二进制，或使用 `go install .` 从源码构建。
|
||||
|
||||
### Q: Windows 上凭证存储在哪里？
|
||||
|
||||
gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Credential Manager 不可用，会自动降级到文件存储（`~/.config/gitlink-cli/credentials`）。
|
||||
|
||||
### Q: 如何查看完整的 API 参考？
|
||||
|
||||
查看 [skills/gitlink-shared/REFERENCE.md](skills/gitlink-shared/REFERENCE.md)
|
||||
|
||||
## 许可证
|
||||
|
||||
[MulanPSL-2.0](https://license.coscl.org.cn/MulanPSL2)
|
||||
|
|
@ -0,0 +1,335 @@
|
|||
# gitlink-cli 新增功能使用指南
|
||||
|
||||
> 任务B — file / member / watch / star 四大模块，15 个新命令
|
||||
|
||||
---
|
||||
|
||||
## 一、file — 仓库文件操作
|
||||
|
||||
### file +list — 列出仓库文件
|
||||
|
||||
```bash
|
||||
gitlink-cli file +list --owner <owner> --repo <repo> [--ref <分支>] [--search <关键词>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner` | 否* | 仓库拥有者 |
|
||||
| `--repo` | 否* | 仓库名 |
|
||||
| `--ref`, `-r` | 否 | 分支/标签/commit SHA |
|
||||
| `--search`, `-s` | 否 | 搜索关键词 |
|
||||
|
||||
\* 在 git 仓库目录下运行时自动解析，无需手动指定
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 列出根目录文件
|
||||
gitlink-cli file +list --owner chroe --repo gitlink-cli
|
||||
|
||||
# 列出 dev 分支的文件
|
||||
gitlink-cli file +list --owner chroe --repo gitlink-cli --ref dev
|
||||
|
||||
# 搜索包含 "test" 的文件
|
||||
gitlink-cli file +list --owner chroe --repo gitlink-cli --search test
|
||||
```
|
||||
|
||||
### file +tree — 查看文件树
|
||||
|
||||
```bash
|
||||
gitlink-cli file +tree --owner <owner> --repo <repo> [--sha <分支>] [--recursive] [--page <n>] [--limit <n>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--sha`, `-s` | 否 | 分支/标签/commit，默认 `master` |
|
||||
| `--recursive` | 否 | 递归展开所有子目录（`true`/`false`） |
|
||||
| `--page`, `-p` | 否 | 页码，默认 `1` |
|
||||
| `--limit`, `-l` | 否 | 每页条数，默认 `20` |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 默认 tree 输出（table 格式）
|
||||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master
|
||||
|
||||
# 递归列出所有文件（JSON 格式）
|
||||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master --recursive true --format json
|
||||
```
|
||||
|
||||
### file +get — 查看文件/目录内容
|
||||
|
||||
```bash
|
||||
gitlink-cli file +get --owner <owner> --repo <repo> --path <路径> [--ref <分支>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--path`, `-p` | **是** | 文件或目录路径 |
|
||||
| `--ref`, `-r` | 否 | 分支/标签/commit，默认 `master` |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 查看 README.md 内容
|
||||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path README.md
|
||||
|
||||
# 查看 src 目录的子条目
|
||||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path src
|
||||
|
||||
# 查看 dev 分支上的文件
|
||||
gitlink-cli file +get --owner chroe --repo gitlink-cli --path main.go --ref dev
|
||||
```
|
||||
|
||||
### file +create — 新建文件
|
||||
|
||||
```bash
|
||||
gitlink-cli file +create --owner <owner> --repo <repo> --path <路径> --content <内容> --message <提交信息> [--branch <分支>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--path`, `-p` | **是** | 文件路径（含文件名） |
|
||||
| `--content`, `-c` | **是** | 文件内容（明文，自动 Base64 编码） |
|
||||
| `--message`, `-m` | **是** | Git 提交信息 |
|
||||
| `--branch`, `-b` | 否 | 目标分支，默认 `master` |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli file +create \
|
||||
--owner caoweiqiong --repo Aether \
|
||||
--path docs/readme.txt \
|
||||
--content "Hello GitLink!" \
|
||||
--message "添加文档" \
|
||||
--branch master
|
||||
```
|
||||
|
||||
### file +delete — 删除文件
|
||||
|
||||
```bash
|
||||
gitlink-cli file +delete --owner <owner> --repo <repo> --path <路径> --sha <BlobSHA> --message <提交信息> [--branch <分支>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--path`, `-p` | **是** | 要删除的文件路径 |
|
||||
| `--sha`, `-s` | **是** | 文件的 blob SHA（从 `file +list` 获取） |
|
||||
| `--message`, `-m` | **是** | Git 提交信息 |
|
||||
| `--branch`, `-b` | 否 | 目标分支，默认 `master` |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 先列出文件获取 SHA
|
||||
gitlink-cli file +list --owner caoweiqiong --repo Aether
|
||||
|
||||
# 然后删除指定文件
|
||||
gitlink-cli file +delete \
|
||||
--owner caoweiqiong --repo Aether \
|
||||
--path docs/old.txt \
|
||||
--sha abc123def456 \
|
||||
--message "删除过期文档"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二、member — 项目成员管理
|
||||
|
||||
### member +list — 列出成员
|
||||
|
||||
```bash
|
||||
gitlink-cli member +list --owner <owner> --repo <repo> [--keyword <搜索>]
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--keyword`, `-k` | 否 | 按用户名搜索成员 |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli member +list --owner chroe --repo gitlink-cli --format table
|
||||
|
||||
# 搜索特定成员
|
||||
gitlink-cli member +list --owner chroe --repo gitlink-cli --keyword caoweiqiong
|
||||
```
|
||||
|
||||
输出示例：
|
||||
|
||||
```
|
||||
id login role_name
|
||||
-- ----- ---------
|
||||
149027 chroe Manager
|
||||
141645 caoweiqiong Developer
|
||||
148915 yetja Developer
|
||||
```
|
||||
|
||||
### member +add — 添加成员
|
||||
|
||||
```bash
|
||||
gitlink-cli member +add --owner <owner> --repo <repo> --user-id <数字ID>
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--user-id`, `-u` | **是** | 用户的数字 ID（从 `user +info` 获取） |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
# 先查到目标用户的 user_id
|
||||
gitlink-cli user +info --login zhangsan
|
||||
|
||||
# 然后添加
|
||||
gitlink-cli member +add --owner caoweiqiong --repo Aether --user-id 123456
|
||||
```
|
||||
|
||||
### member +remove — 移除成员
|
||||
|
||||
```bash
|
||||
gitlink-cli member +remove --owner <owner> --repo <repo> --user-id <数字ID>
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli member +remove --owner caoweiqiong --repo Aether --user-id 123456
|
||||
```
|
||||
|
||||
### member +update — 修改成员角色
|
||||
|
||||
```bash
|
||||
gitlink-cli member +update --owner <owner> --repo <repo> --user-id <数字ID> --role <角色>
|
||||
```
|
||||
|
||||
| 参数 | 必需 | 说明 |
|
||||
|------|------|------|
|
||||
| `--user-id`, `-u` | **是** | 用户数字 ID |
|
||||
| `--role`, `-r` | **是** | 三种角色之一：`Manager` / `Developer` / `Reporter` |
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli member +update --owner caoweiqiong --repo Aether --user-id 123456 --role Developer
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 三、watch — 关注仓库
|
||||
|
||||
### watch +watch — 关注仓库
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +watch --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
无需手动传 project-id，命令内部自动解析。
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +watch --owner chroe --repo gitlink-cli
|
||||
# → 返回 {"watched": true}
|
||||
```
|
||||
|
||||
### watch +unwatch — 取消关注
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +unwatch --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +unwatch --owner chroe --repo gitlink-cli
|
||||
# → 返回 {"watched": false}
|
||||
```
|
||||
|
||||
### watch +watchers — 查看关注者列表
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +watchers --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli watch +watchers --owner chroe --repo gitlink-cli --format table
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、star — 点赞仓库
|
||||
|
||||
### star +star — 点赞仓库
|
||||
|
||||
```bash
|
||||
gitlink-cli star +star --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
无需手动传 project-id，命令内部自动解析。
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli star +star --owner chroe --repo gitlink-cli
|
||||
```
|
||||
|
||||
### star +unstar — 取消点赞
|
||||
|
||||
```bash
|
||||
gitlink-cli star +unstar --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli star +unstar --owner chroe --repo gitlink-cli
|
||||
```
|
||||
|
||||
### star +stars — 查看点赞者列表
|
||||
|
||||
```bash
|
||||
gitlink-cli star +stars --owner <owner> --repo <repo>
|
||||
```
|
||||
|
||||
**示例：**
|
||||
|
||||
```bash
|
||||
gitlink-cli star +stars --owner chroe --repo gitlink-cli --format table
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 全局参数
|
||||
|
||||
所有命令都支持以下全局参数：
|
||||
|
||||
| 参数 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `--owner` | 仓库拥有者（git 目录下自动解析） | `--owner chroe` |
|
||||
| `--repo` | 仓库名（git 目录下自动解析） | `--repo gitlink-cli` |
|
||||
| `--format` | 输出格式：`json` / `table` / `yaml` | `--format table` |
|
||||
| `--debug` | 开启调试输出 | `--debug` |
|
||||
|
||||
## 使用技巧
|
||||
|
||||
1. **利用自动解析**：在 git 克隆的目录下直接运行，无需写 `--owner` 和 `--repo`：
|
||||
|
||||
```bash
|
||||
cd my-project
|
||||
gitlink-cli file +list # 自动识别当前仓库
|
||||
gitlink-cli member +list # 同上
|
||||
```
|
||||
|
||||
2. **JSON 输出用于脚本**：
|
||||
|
||||
```bash
|
||||
gitlink-cli file +tree --owner chroe --repo gitlink-cli --sha master --format json | jq '.data.entries[] | .name'
|
||||
```
|
||||
|
||||
3. **file 创建自动 Base64**：传 `--content` 时直接写明文，命令会自动转为 Base64，不用自己编码。
|
||||
|
||||
4. **watch/star 透明化**：`watch` 和 `star` 命令会自动查 project-id，你只需关心 owner/repo，与其他命令体验一致。
|
||||
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"github.com/gitlink-org/gitlink-cli/internal/config"
|
||||
)
|
||||
|
||||
func main() {
|
||||
cfg, _ := config.Load()
|
||||
fmt.Printf("BaseURL: [%s]\n", cfg.BaseURL)
|
||||
fmt.Printf("len: %d\n", len(cfg.BaseURL))
|
||||
path := "/v1/chroe/gitlink-cli/issues/1"
|
||||
fmt.Printf("fullURL: [%s]\n", cfg.BaseURL + path)
|
||||
}
|
||||
|
|
@ -1,846 +0,0 @@
|
|||
# gitlink-spark Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Build a `gitlink-spark` Skill + runnable `spark.py` that mines "literature↔code semantic gaps" across arXiv × GitLink × GitHub and outputs an opportunity report with optional fork+issue kickoff.
|
||||
|
||||
**Architecture:** `scripts/spark.py` is a standalone data-fusion script (fetches real data → JSON). `SKILL.md` orchestrates an LLM that reads the JSON, semantically matches two gap types (theory-no-impl / demand-no-solution) with evidence triples, renders an opportunity report, and optionally forks+issues to kickoff. Pure functions are unit-tested; the live GNN run is integration validation.
|
||||
|
||||
**Tech Stack:** Python 3.11 stdlib only (urllib, subprocess, xml.etree, json, argparse) — no pip deps. gitlink-cli. arXiv Atom API + GitHub Search REST.
|
||||
|
||||
**Source of truth:** `docs/superpowers/specs/2026-07-01-gitlink-spark-design.md` (read it first).
|
||||
|
||||
---
|
||||
|
||||
## Environment & Gotchas (engineer must know)
|
||||
|
||||
- **Branch:** on `feat/gitlink-research-fair` (spark is 子任务四第二部分, shares PR #5). Commit only your own files; leave pre-existing `D README_TASKB.md` / `D gitlink-cli.exe` / `?? dist/` / `?? _edge_prescription/` untouched.
|
||||
- **Encoding:** all python that touches Chinese gitlink-cli output MUST run with `PYTHONUTF8=1 PYTHONIOENCODING=utf-8`. Never inline Chinese in `python -c` — write a `.py` file.
|
||||
- **arXiv must be HTTPS** (`https://export.arxiv.org`); plain HTTP is sandbox-blocked (returns 0 bytes).
|
||||
- **GitHub unauthenticated = 10 req/min** → `fetch_github_count` sleeps ~7s between calls. Set `GITHUB_TOKEN` env to raise to 5000/h. Cache by query key.
|
||||
- **`gitlink-cli search +issues` returns HTML (broken)** — never use it. Use per-repo `gitlink-cli issue +list --owner X --repo Y --state open` (returns JSON).
|
||||
- **`--repo` uses identifier** (ASCII slug), not Chinese display name.
|
||||
- **No `pip install`** — spark.py uses stdlib only. Tests run via `python test_spark.py` (assert-based, no pytest).
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Responsibility |
|
||||
|------|----------------|
|
||||
| `skills/gitlink-spark/scripts/spark.py` | Standalone data fusion: arXiv + gitlink-cli + GitHub → JSON on stdout. Pure parsers + network fetchers + main() |
|
||||
| `skills/gitlink-spark/scripts/test_spark.py` | Assert-based unit tests for pure parsers (parse_arxiv_atom, parse_github_search, extract_method_keywords) |
|
||||
| `skills/gitlink-spark/SKILL.md` | 4-stage orchestration, gap taxonomy, GitHub threshold rule, report template, kickoff guardrails, error table |
|
||||
| `skills/gitlink-spark/REFERENCE.md` | Gap taxonomy detail, GitHub tiers, LLM prompt template, data-source findings, honesty caveats |
|
||||
| `skills/gitlink-spark/examples/spark-图神经网络.md` | Real GNN run: 2-3 gap cards + kickoff screenshot |
|
||||
| `skills/README.md` | Add gitlink-spark row |
|
||||
| `skills/gitlink-workflow/SKILL.md` | Optional cross-link |
|
||||
|
||||
---
|
||||
|
||||
## Task 1: Scaffold SKILL.md (frontmatter + CRITICAL + pipeline + command interface)
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-spark/SKILL.md`
|
||||
|
||||
- [ ] **Step 1: Create SKILL.md with frontmatter, CRITICAL headers, 概述, 命令接口, 4-stage pipeline**
|
||||
|
||||
Content (exact):
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: gitlink-spark
|
||||
version: 1.0.0
|
||||
description: "文献-代码语义缺口挖掘机：给一个研究领域，跨 arXiv × GitLink × GitHub 三源挖'有理论无实现/有需求无解答'语义缺口，输出空白学术机会报告，可一键 fork+issue 起跑。当用户需要找研究点、发现论文-代码空白、科研选题启发时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "python skills/gitlink-spark/scripts/spark.py --help"
|
||||
---
|
||||
|
||||
# gitlink-spark（文献-代码语义缺口挖掘机）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 缺口由 LLM 揨断，但每条必须带实证三件套（论文 id / GitLink 查询+命中数 / GitHub total_count）；无实证的缺口必须丢弃。**
|
||||
**CRITICAL — 起跑（fork+issue）默认预览确认；绝不自动 merge、绝不 force-push、绝不碰原仓库。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；缺口分类法、GitHub 阈值、LLM prompt 模板见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
## 概述
|
||||
|
||||
给一个研究领域，跨 **arXiv（学术）× GitLink（中文生态）× GitHub（全球）** 三源挖两类语义缺口，输出**空白学术机会报告**。`scripts/spark.py` 抓真实数据（JSON），LLM 做语义匹配并附实证三件套。与 `gitlink-research-fair`（评估已有）组成"科研辅助双联装"——本 skill 负责**发现空白**。
|
||||
|
||||
## 命令接口
|
||||
|
||||
数据融合脚本（可独立运行）：
|
||||
|
||||
```bash
|
||||
python skills/gitlink-spark/scripts/spark.py --field "图神经网络" [--max-papers 10] [--gap-type both|theory|demand] [--github-token $GITHUB_TOKEN]
|
||||
# → stdout: 融合 JSON {papers, gitlink_repos, gitlink_issues, github_counts}
|
||||
```
|
||||
|
||||
skill 约定参数（非 CLI flag）：
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--field` | 必填 | 研究领域 |
|
||||
| `--gap-type` | `both` | `theory` / `demand` / `both` |
|
||||
| `--max-papers` | 10 | arXiv 抓取上限（控 GitHub 调用） |
|
||||
| `--auto` | 关 | 跳过预览直接起跑（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出报告，不起跑 |
|
||||
|
||||
## 管道（4 阶段）
|
||||
|
||||
### ① 学术采
|
||||
`spark.py` 调 arXiv HTTPS API 抓领域近 90 天论文（标题/摘要/arxiv id/方法关键词）
|
||||
|
||||
### ② GitLink 采
|
||||
`spark.py` 调 `gitlink-cli search +repos` 抓领域仓库；对每个仓库 `issue +list --state open` 抓 open issue（**不用 search +issues**，它返回 HTML）
|
||||
|
||||
### ③ 全球对照
|
||||
`spark.py` 调 GitHub Search API 对每个论文方法查 `total_count` + Top3 仓库（限流+缓存）
|
||||
|
||||
### ④ 缺口匹配（LLM）+ 报告 + 起跑
|
||||
读 spark.py 的 JSON → 语义匹配两类缺口（每张带实证三件套）→ 渲染机会报告 → 可选 fork+issue 起跑
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify**
|
||||
|
||||
Run: `head -30 skills/gitlink-spark/SKILL.md | grep -c -e "name: gitlink-spark" -e "description:" -e "CRITICAL" -e "管道（4 阶段）"`
|
||||
Expected: `6`
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/SKILL.md
|
||||
git commit -m "feat(spark): scaffold SKILL.md（frontmatter+CRITICAL+4阶段管道）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: SKILL.md — gap taxonomy + evidence triples + GitHub thresholds + report + guardrails
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-spark/SKILL.md` (append after 管道)
|
||||
|
||||
- [ ] **Step 1: Append gap taxonomy, thresholds, report template, kickoff, error table**
|
||||
|
||||
Append (exact):
|
||||
|
||||
```markdown
|
||||
## 两类缺口 + 实证三件套（信服核心）
|
||||
|
||||
每张缺口卡**必须**带齐三件套，否则丢弃（防 LLM 编造）：
|
||||
|
||||
### 类型 A：有理论无实现（paper → code gap）
|
||||
- **三件套**：① 论文 arxiv id + 标题 + 发表日期 ② GitLink 搜索查询串 + 命中数（0/极少） ③ GitHub total_count + Top 仓库
|
||||
- LLM 判定：论文提出方法 M；GitLink 实现 0/极少；GitHub 按下方阈值分级
|
||||
|
||||
### 类型 B：有需求无解答（open issue → applied gap）
|
||||
- **三件套**：① issue URL + 主题 + 讨论人数/状态 ② GitLink 无现成实现解此痛点 ③ GitHub 是否有成熟开源解
|
||||
- 降噪：LLM 只挑"研究性痛点"（性能/可扩展/新场景），排除"安装报错"等使用问题
|
||||
|
||||
## GitHub 全球对照阈值（诚实核心，硬需求）
|
||||
|
||||
防止"GitLink 0 ≠ 全球空白"误导。对每个"理论无实现"候选按 GitHub total_count 分级：
|
||||
|
||||
| GitHub total_count | 分级 | 报告行为 |
|
||||
|--------------------|------|----------|
|
||||
| `< 10` | 全球稀缺（真空白） | 报为高价值缺口 |
|
||||
| `10–50` | 新兴（部分空白） | 报为中等缺口（"GitLink 空白，全球新兴"） |
|
||||
| `≥ 50` | 全球已成熟 | **不报为空白**，列入"✅ 已诚实排除" |
|
||||
|
||||
宁可少报，不误报机会。
|
||||
|
||||
## 机会报告格式（hero）
|
||||
|
||||
````markdown
|
||||
⚡ **gitlink-spark 机会报告：<field>**
|
||||
|
||||
学术采：arXiv 近 90 天 N 篇 ｜ GitLink 仓库 M 个 ｜ GitHub 全球基线已对照
|
||||
生成时间：YYYY-MM-DD
|
||||
|
||||
### 🧩 缺口 1 · 有理论无实现 [全球稀缺·高价值]
|
||||
**论文**：[arxiv:<id>] "<title>" (<date>)
|
||||
**方法关键词**：<...>
|
||||
**GitLink**：search "<query>" → **0 命中**（查询串留底）
|
||||
**GitHub 全球**：total_count = **N**（Top: <repo> <stars>⭐）→ 稀缺
|
||||
**机会建议**：<LLM 一句话>
|
||||
**起跑**：[按钮] fork 基准 <repo> → 创建 issue 粘论文伪代码
|
||||
|
||||
### 🧩 缺口 2 · 有需求无解答 [应用机会]
|
||||
**Issue**：<repo>#<n> "<subject>"（N 人讨论, open）
|
||||
**痛点**：<LLM 归纳>
|
||||
**GitLink / GitHub**：均无成熟解
|
||||
**机会建议**：<LLM 一句话>
|
||||
|
||||
### ✅ 已诚实排除（非空白）
|
||||
- 论文 Y：GitLink 虽 0，但 GitHub 已 N 个 → 全球已成熟，不报
|
||||
|
||||
---
|
||||
<!-- gitlink-spark v1 | field:<field> | gaps:<N> | date:<YYYY-MM-DD> -->
|
||||
*由 gitlink-spark skill 生成。*
|
||||
````
|
||||
|
||||
## 起跑动作 + 护栏
|
||||
|
||||
选定一张"理论无实现"缺口卡 → 确认 →
|
||||
1. `gitlink-cli repo +fork` 最近基准（GitHub Top 仓库或 GitLink 最近实现）
|
||||
2. LLM 从 arXiv 论文抓 Algorithm/Pseudocode 节
|
||||
3. `gitlink-cli issue +create` 在 fork 建复现 todo issue（body 粘伪代码 + 报告卡摘要）
|
||||
|
||||
**护栏**：默认预览；`--auto` 跳过但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 只出报告。
|
||||
|
||||
## 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| arXiv 空/超时 | HTTPS 重试；仍空降级用既有论文 |
|
||||
| `search +issues` 返回 HTML | 不用，改逐仓库 `issue +list` |
|
||||
| GitHub 未认证限流(10/min) | spark.py sleep ~7s；建议设 `GITHUB_TOKEN` |
|
||||
| GitHub 查询失败 | 该论文标"对照失败"，不进缺口判定 |
|
||||
| OpenAlex 503 | 跳过引用富集 |
|
||||
| LLM 缺口无三件套 | 置信度门控丢弃 |
|
||||
| fork/issue 起跑失败 | 输出 fork 目标 + 伪代码文本供手动起跑 |
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify**
|
||||
|
||||
Run: `grep -c -e "三件套" -e "GitHub total_count" -e "已诚实排除" -e "起跑动作" skills/gitlink-spark/SKILL.md`
|
||||
Expected: `4`
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/SKILL.md
|
||||
git commit -m "feat(spark): SKILL 缺口分类法+GitHub阈值+报告模板+起跑护栏+降级"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: spark.py — parse_arxiv_atom + test (TDD)
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-spark/scripts/spark.py`
|
||||
- Create: `skills/gitlink-spark/scripts/test_spark.py`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
`test_spark.py` (exact):
|
||||
|
||||
```python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Assert-based unit tests for spark.py pure parsers. Run: python test_spark.py"""
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(__file__))
|
||||
from spark import parse_arxiv_atom, parse_github_search, extract_method_keywords
|
||||
|
||||
SAMPLE_ARXIV = """<?xml version="1.0" encoding="UTF-8"?>
|
||||
<feed xmlns="http://www.w3.org/2005/Atom">
|
||||
<entry>
|
||||
<id>http://arxiv.org/abs/2403.12345v1</id>
|
||||
<title>Graph Attention Networks with Sparse Transformers</title>
|
||||
<summary>We propose a new graph attention mechanism using sparse attention.</summary>
|
||||
<published>2024-03-15T00:00:00Z</published>
|
||||
</entry>
|
||||
<entry>
|
||||
<id>http://arxiv.org/abs/2404.99999v2</id>
|
||||
<title>Federated Learning on Heterogeneous Graphs</title>
|
||||
<summary>A federated approach for heterogeneous graph neural networks.</summary>
|
||||
<published>2024-04-20T00:00:00Z</published>
|
||||
</entry>
|
||||
</feed>"""
|
||||
|
||||
def test_parse_arxiv_atom():
|
||||
papers = parse_arxiv_atom(SAMPLE_ARXIV)
|
||||
assert len(papers) == 2, f"expected 2 papers, got {len(papers)}"
|
||||
assert papers[0]["arxiv_id"] == "2403.12345v1", papers[0]["arxiv_id"]
|
||||
assert "Graph Attention" in papers[0]["title"]
|
||||
assert papers[0]["published"] == "2024-03-15"
|
||||
assert "sparse" in papers[0]["abstract"].lower()
|
||||
print("test_parse_arxiv_atom OK")
|
||||
|
||||
def test_parse_github_search():
|
||||
import json as _j
|
||||
sample = _j.dumps({"total_count": 1543, "items": [{"full_name": "a/b", "stargazers_count": 3534}]})
|
||||
res = parse_github_search(sample)
|
||||
assert res["total_count"] == 1543
|
||||
assert res["top"][0]["full_name"] == "a/b"
|
||||
assert res["top"][0]["stars"] == 3534
|
||||
print("test_parse_github_search OK")
|
||||
|
||||
def test_extract_method_keywords():
|
||||
kws = extract_method_keywords("Graph Attention Networks", "We propose a sparse attention mechanism for graphs.", max_k=5)
|
||||
assert "graph" in kws and "attention" in kws
|
||||
assert "propose" not in kws # 'propose' is in the stop set, filtered out
|
||||
print("test_extract_method_keywords OK")
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_parse_arxiv_atom()
|
||||
test_parse_github_search()
|
||||
test_extract_method_keywords()
|
||||
print("ALL TESTS PASSED")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd skills/gitlink-spark/scripts && python test_spark.py`
|
||||
Expected: FAIL with `ModuleNotFoundError: No module named 'spark'`
|
||||
|
||||
- [ ] **Step 3: Write minimal spark.py with parse_arxiv_atom (+ stubs for the other two so import works)**
|
||||
|
||||
`spark.py` (exact):
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""gitlink-spark data fusion: arXiv x GitLink x GitHub -> JSON on stdout. Stdlib only."""
|
||||
import argparse, json, os, sys, time, subprocess, urllib.request, urllib.parse, re
|
||||
from xml.etree import ElementTree as ET
|
||||
|
||||
ARXIV_ENDPOINT = "https://export.arxiv.org/api/query"
|
||||
GITHUB_ENDPOINT = "https://api.github.com/search/repositories"
|
||||
|
||||
_NS = {"a": "http://www.w3.org/2005/Atom"}
|
||||
|
||||
def parse_arxiv_atom(xml_text):
|
||||
"""Parse arXiv Atom feed -> list of {arxiv_id, title, abstract, published}."""
|
||||
root = ET.fromstring(xml_text)
|
||||
papers = []
|
||||
for e in root.findall("a:entry", _NS):
|
||||
aid = (e.find("a:id", _NS).text or "").strip().split("/")[-1]
|
||||
title = re.sub(r"\s+", " ", (e.find("a:title", _NS).text or "").strip())
|
||||
summary = re.sub(r"\s+", " ", (e.find("a:summary", _NS).text or "").strip())
|
||||
pub = (e.find("a:published", _NS).text or "")[:10]
|
||||
papers.append({"arxiv_id": aid, "title": title, "abstract": summary, "published": pub})
|
||||
return papers
|
||||
|
||||
def parse_github_search(json_text):
|
||||
return {"total_count": 0, "top": []} # stub — implemented in Task 4
|
||||
|
||||
def extract_method_keywords(title, abstract, max_k=5):
|
||||
return [] # stub — implemented in Task 4
|
||||
|
||||
def main():
|
||||
pass # implemented in Task 7
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test — arxiv test passes, others fail on stubs**
|
||||
|
||||
Run: `cd skills/gitlink-spark/scripts && python test_spark.py`
|
||||
Expected: `test_parse_arxiv_atom OK`, then FAIL on `test_parse_github_search` (top[0] index error on empty). This confirms arxiv parser works; stubs next.
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/scripts/spark.py skills/gitlink-spark/scripts/test_spark.py
|
||||
git commit -m "feat(spark): spark.py parse_arxiv_atom + test（TDD）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: spark.py — parse_github_search + extract_method_keywords (real impl)
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-spark/scripts/spark.py` (replace the two stubs)
|
||||
|
||||
- [ ] **Step 1: Replace the two stub functions with real implementations**
|
||||
|
||||
Replace `def parse_github_search(json_text): ...` and `def extract_method_keywords(...): ...` with:
|
||||
|
||||
```python
|
||||
def parse_github_search(json_text):
|
||||
"""Parse GitHub search JSON -> {total_count, top:[{full_name, stars}]}."""
|
||||
d = json.loads(json_text)
|
||||
return {
|
||||
"total_count": d.get("total_count", 0),
|
||||
"top": [{"full_name": r.get("full_name"), "stars": r.get("stargazers_count")}
|
||||
for r in (d.get("items") or [])[:3]],
|
||||
}
|
||||
|
||||
def extract_method_keywords(title, abstract, max_k=5):
|
||||
"""Crude keyword extraction for GitHub/arXiv query."""
|
||||
text = (title + " " + abstract).lower()
|
||||
stop = {"the", "a", "an", "of", "for", "and", "to", "in", "on", "with", "via",
|
||||
"based", "using", "by", "from", "as", "is", "are", "we", "our", "this",
|
||||
"that", "propose", "proposed", "paper", "method", "approach", "novel", "new"}
|
||||
tokens = re.findall(r"[a-z][a-z0-9-]+", text)
|
||||
seen = set(); out = []
|
||||
for t in tokens:
|
||||
if t in stop or len(t) < 3 or t in seen:
|
||||
continue
|
||||
seen.add(t); out.append(t)
|
||||
if len(out) >= max_k:
|
||||
break
|
||||
return out
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run all tests — expect ALL PASS**
|
||||
|
||||
Run: `cd skills/gitlink-spark/scripts && python test_spark.py`
|
||||
Expected: `ALL TESTS PASSED` (all 3 tests)
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/scripts/spark.py
|
||||
git commit -m "feat(spark): parse_github_search + extract_method_keywords 实现（3 测试全过）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: spark.py — fetch_arxiv (network)
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-spark/scripts/spark.py` (add fetch_arxiv before main)
|
||||
|
||||
- [ ] **Step 1: Add fetch_arxiv**
|
||||
|
||||
Insert before `def main()`:
|
||||
|
||||
```python
|
||||
def fetch_arxiv(field, max_papers=10):
|
||||
"""Search arXiv (HTTPS) for recent papers in field. Returns list of paper dicts."""
|
||||
q = urllib.parse.quote(f'abs:"{field}"')
|
||||
url = (f"{ARXIV_ENDPOINT}?search_query={q}&max_results={max_papers}"
|
||||
f"&sortBy=submittedDate&sortOrder=descending")
|
||||
with urllib.request.urlopen(url, timeout=30) as r:
|
||||
papers = parse_arxiv_atom(r.read().decode("utf-8", "replace"))
|
||||
for p in papers:
|
||||
p["method_keywords"] = extract_method_keywords(p["title"], p["abstract"])
|
||||
return papers
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Smoke test fetch_arxiv (live network)**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd skills/gitlink-spark/scripts && PYTHONUTF8=1 python -c "
|
||||
from spark import fetch_arxiv
|
||||
ps = fetch_arxiv('graph neural network', max_papers=2)
|
||||
assert len(ps) >= 1, 'no papers'
|
||||
p = ps[0]
|
||||
assert p['arxiv_id'] and p['title'] and p['published']
|
||||
assert isinstance(p['method_keywords'], list)
|
||||
print('OK', p['arxiv_id'], '|', p['title'][:50])
|
||||
"
|
||||
```
|
||||
Expected: `OK 2504.xxxxx | <recent GNN paper title>` (a real recent arxiv id). If 0 bytes, confirm HTTPS (not HTTP).
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/scripts/spark.py
|
||||
git commit -m "feat(spark): fetch_arxiv（arXiv HTTPS 网络层）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: spark.py — fetch_gitlink_repos + fetch_gitlink_issues
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-spark/scripts/spark.py`
|
||||
|
||||
- [ ] **Step 1: Add _gitlink helper + the two fetchers**
|
||||
|
||||
Insert before `def main()`:
|
||||
|
||||
```python
|
||||
def _gitlink(*args):
|
||||
"""Run gitlink-cli with json output; return parsed dict (UTF-8 safe)."""
|
||||
r = subprocess.run(["gitlink-cli"] + list(args) + ["--format", "json"],
|
||||
capture_output=True, text=True, encoding="utf-8",
|
||||
errors="replace", timeout=60)
|
||||
raw = r.stdout
|
||||
i = raw.find("{")
|
||||
return json.loads(raw[i:]) if i >= 0 else {}
|
||||
|
||||
def fetch_gitlink_repos(field):
|
||||
"""gitlink-cli search +repos -> list of {owner, repo(identifier), name, desc, topics}."""
|
||||
d = _gitlink("search", "+repos", "-k", field)
|
||||
projs = d.get("data", {}).get("projects", []) or []
|
||||
out = []
|
||||
for p in projs:
|
||||
out.append({
|
||||
"owner": (p.get("author") or {}).get("login"),
|
||||
"repo": p.get("identifier"),
|
||||
"name": p.get("name"),
|
||||
"desc": p.get("description"),
|
||||
"topics": [t.get("name") if isinstance(t, dict) else t for t in (p.get("topics") or [])],
|
||||
})
|
||||
return out
|
||||
|
||||
def fetch_gitlink_issues(repos, max_per_repo=10):
|
||||
"""Per-repo issue +list (open) -> list of {repo, number, subject, status, participants}.
|
||||
Works around search +issues returning HTML."""
|
||||
out = []
|
||||
for r in repos:
|
||||
if not (r.get("owner") and r.get("repo")):
|
||||
continue
|
||||
d = _gitlink("issue", "+list", "--owner", r["owner"], "--repo", r["repo"], "--state", "open")
|
||||
data = d.get("data", {}) or {}
|
||||
issues = data.get("issues") or []
|
||||
for it in issues[:max_per_repo]:
|
||||
st = (it.get("status") or {})
|
||||
if st.get("name") == "关闭":
|
||||
continue
|
||||
out.append({
|
||||
"repo": f'{r["owner"]}/{r["repo"]}',
|
||||
"number": it.get("project_issues_index") or it.get("number"),
|
||||
"subject": it.get("subject"),
|
||||
"status": st.get("name"),
|
||||
"participants": it.get("participants_count") or 0,
|
||||
})
|
||||
return out
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Smoke test (live)**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd skills/gitlink-spark/scripts && PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python -c "
|
||||
from spark import fetch_gitlink_repos, fetch_gitlink_issues
|
||||
repos = fetch_gitlink_repos('图神经网络')
|
||||
print('repos:', len(repos))
|
||||
if repos: print(' sample:', repos[0]['owner'], '/', repos[0]['repo'])
|
||||
iss = fetch_gitlink_issues(repos[:2])
|
||||
print('issues(from first 2 repos):', len(iss))
|
||||
"
|
||||
```
|
||||
Expected: `repos: N` (N≥1, includes GraphGallery-class), `issues: M`. If `repos: 0`, the field keyword missed — retry with `'graph neural'`. If issues JSON parse fails, inspect gitlink-cli `issue +list` structure and adapt field names.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/scripts/spark.py
|
||||
git commit -m "feat(spark): fetch_gitlink_repos + fetch_gitlink_issues（逐仓库，绕开 search+issues HTML）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 7: spark.py — fetch_github_count + main() + end-to-end smoke
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-spark/scripts/spark.py`
|
||||
|
||||
- [ ] **Step 1: Add fetch_github_count (cache+throttle) and implement main()**
|
||||
|
||||
Replace `def main(): pass` and add fetch_github_count before it:
|
||||
|
||||
```python
|
||||
_GH_CACHE = {}
|
||||
|
||||
def fetch_github_count(query, token=None, throttle=True):
|
||||
"""GitHub search total_count + top3 for a query. Caches + throttles (10/min unauth)."""
|
||||
if query in _GH_CACHE:
|
||||
return _GH_CACHE[query]
|
||||
url = f"{GITHUB_ENDPOINT}?q={urllib.parse.quote(query)}&per_page=3&sort=stars"
|
||||
req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json",
|
||||
"User-Agent": "gitlink-spark/1.0"})
|
||||
if token:
|
||||
req.add_header("Authorization", f"Bearer {token}")
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=25) as r:
|
||||
res = parse_github_search(r.read().decode("utf-8", "replace"))
|
||||
except Exception as e:
|
||||
res = {"total_count": None, "top": [], "error": str(e)[:80]}
|
||||
if throttle and not token:
|
||||
time.sleep(7) # unauthenticated = 10 req/min
|
||||
_GH_CACHE[query] = res
|
||||
return res
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description="gitlink-spark data fusion")
|
||||
ap.add_argument("--field", required=True)
|
||||
ap.add_argument("--max-papers", type=int, default=10)
|
||||
ap.add_argument("--gap-type", default="both", choices=["both", "theory", "demand"])
|
||||
ap.add_argument("--github-token", default=os.environ.get("GITHUB_TOKEN"))
|
||||
args = ap.parse_args()
|
||||
|
||||
papers = fetch_arxiv(args.field, args.max_papers)
|
||||
grepos = fetch_gitlink_repos(args.field)
|
||||
gissues = fetch_gitlink_issues(grepos) if args.gap_type in ("both", "demand") else []
|
||||
gh_counts = {}
|
||||
if args.gap_type in ("both", "theory"):
|
||||
for p in papers:
|
||||
q = p["title"][:60] # primary query = paper title (truncated)
|
||||
gh_counts[q] = fetch_github_count(q, args.github_token)
|
||||
|
||||
out = {
|
||||
"field": args.field,
|
||||
"papers": papers,
|
||||
"gitlink_repos": grepos,
|
||||
"gitlink_issues": gissues,
|
||||
"github_counts": gh_counts,
|
||||
}
|
||||
json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
|
||||
sys.stdout.write("\n")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: End-to-end smoke (tiny, live)**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd skills/gitlink-spark/scripts && PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python spark.py --field "graph neural network" --max-papers 3 --gap-type theory > _smoke.json 2>&1
|
||||
PYTHONUTF8=1 python -c "
|
||||
import json
|
||||
d=json.load(open('_smoke.json',encoding='utf-8'))
|
||||
print('field:', d['field'])
|
||||
print('papers:', len(d['papers']), '| gitlink_repos:', len(d['gitlink_repos']))
|
||||
print('github_counts keys:', len(d['github_counts']))
|
||||
g=d['github_counts']
|
||||
for k,v in list(g.items())[:1]: print(' sample gh:', k[:30], '-> total', v.get('total_count'))
|
||||
"
|
||||
rm -f _smoke.json
|
||||
```
|
||||
Expected: papers=3, gitlink_repos≥1, github_counts has 3 entries with real total_count ints. Takes ~25s (3 GitHub calls × 7s throttle). If GitHub 403 rate-limit, set `GITHUB_TOKEN` env or wait 60s.
|
||||
|
||||
- [ ] **Step 3: Re-run unit tests (regression)**
|
||||
|
||||
Run: `cd skills/gitlink-spark/scripts && python test_spark.py`
|
||||
Expected: `ALL TESTS PASSED`
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/scripts/spark.py
|
||||
git commit -m "feat(spark): fetch_github_count + main() 编排 → JSON（端到端 smoke 通过）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 8: REFERENCE.md — gap taxonomy detail + GitHub tiers + LLM prompt + data sources
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-spark/REFERENCE.md`
|
||||
|
||||
- [ ] **Step 1: Create REFERENCE.md**
|
||||
|
||||
Content (exact):
|
||||
|
||||
```markdown
|
||||
# gitlink-spark 参考文档
|
||||
|
||||
> SKILL.md 的深度参考：缺口分类细则、GitHub 阈值、LLM prompt 模板、数据源实测、诚实边界。
|
||||
|
||||
## 一、缺口分类法细则
|
||||
|
||||
### 类型 A 有理论无实现
|
||||
- 输入：arXiv 论文方法 M（title + method_keywords）
|
||||
- GitLink 侧：`search +repos -k <M>` 命中数（0 或极少，如 ≤2）
|
||||
- GitHub 侧：`total_count`（按 §二阈值分级）
|
||||
- 判定为"缺口"条件：GitLink ≤2 **且** GitHub < 50（全球稀缺或新兴）
|
||||
|
||||
### 类型 B 有需求无解答
|
||||
- 输入：领域仓库的 open issue（`issue +list`，排除关闭）
|
||||
- LLM 筛"研究性痛点"：含性能/可扩展性/新场景/新数据集，排除安装报错/使用咨询
|
||||
- 判定：GitLink 无现成实现解此痛点 **且** GitHub 无成熟开源方案
|
||||
|
||||
## 二、GitHub 全球对照阈值
|
||||
|
||||
| total_count | 分级 | 报告 |
|
||||
|---|---|---|
|
||||
| < 10 | 全球稀缺 | 高价值缺口 |
|
||||
| 10–50 | 新兴 | 中等缺口 |
|
||||
| ≥ 50 | 已成熟 | **不报为空白**，列入"已诚实排除" |
|
||||
|
||||
spark.py 缓存 GitHub 结果（按 query key），避免重复调用。
|
||||
|
||||
## 三、LLM 缺口匹配 prompt 模板
|
||||
|
||||
```
|
||||
你是科研机会发现助手。下面是 spark.py 抓取的真实数据（JSON）。
|
||||
请跨"arXiv 论文 × GitLink 仓库/issues × GitHub 全球计数"找出语义缺口，输出机会报告。
|
||||
|
||||
规则：
|
||||
1. 只输出可溯源到下列数据的缺口；每张缺口卡带"实证三件套"。
|
||||
2. 类型A（理论无实现）：论文 M 的 GitLink 命中≤2 且 GitHub total_count<50 才报；
|
||||
GitHub ≥50 的论文列入"已诚实排除"，不报为空白。
|
||||
3. 类型B（需求无解答）：只挑研究性痛点 issue，排除使用/安装类。
|
||||
4. 每张卡给一句"机会建议"（主观），但证据必须客观可查。
|
||||
5. 宁可少报，不误报。
|
||||
|
||||
数据：
|
||||
{spark.py 的 JSON}
|
||||
```
|
||||
|
||||
## 四、数据源实测结论（2026-07-01）
|
||||
|
||||
| 源 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| arXiv API | ✅ 必须 HTTPS | HTTP 被沙箱阻断返回 0 字节 |
|
||||
| gitlink-cli search +repos | ✅ | 用 identifier/关键词 |
|
||||
| gitlink-cli issue +list | ✅ | 逐仓库，绕开 search+issues |
|
||||
| gitlink-cli search +issues | ❌ 返回 HTML | 不可用，勿用 |
|
||||
| GitHub Search API | ✅ | 未认证 10/min；GITHUB_TOKEN 提额 |
|
||||
| OpenAlex | ⚠ 间歇 503 | best-effort 富集，降级跳过 |
|
||||
|
||||
## 五、诚实边界
|
||||
|
||||
1. **GitLink 覆盖薄**：缺口卡明确标 "GitLink 0 / GitHub N"；GitHub ≥50 不报为空白。
|
||||
2. LLM 缺口必须可溯源实证三件套，否则丢弃。
|
||||
3. arXiv 仅覆盖 CS/物理等，报告标注学科范围。
|
||||
4. GitHub 未认证 10/min：spark.py sleep 7s + 缓存；建议 demo 设 GITHUB_TOKEN。
|
||||
5. "机会建议"为主观启发，标注"需研究者自行判断"。
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify**
|
||||
|
||||
Run: `grep -c -e "类型 A 有理论无实现" -e "GitHub ≥50 不报为空白" -e "search +issues.*HTML" -e "LLM 缺口匹配 prompt" skills/gitlink-spark/REFERENCE.md`
|
||||
Expected: `4`
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-spark/REFERENCE.md
|
||||
git commit -m "feat(spark): REFERENCE（缺口分类法+GitHub阈值+LLM prompt+数据源实测）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 9: Live GNN run — produce 2-3 gap cards + ≥1 kickoff
|
||||
|
||||
**Files:**
|
||||
- (no committed code; produces real data feeding Task 10's examples doc)
|
||||
|
||||
- [ ] **Step 1: Run spark.py on GNN (full)**
|
||||
|
||||
```bash
|
||||
cd skills/gitlink-spark/scripts
|
||||
PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python spark.py --field "graph neural network" --max-papers 8 --gap-type both > _gnn.json 2>&1
|
||||
PYTHONUTF8=1 python -c "
|
||||
import json
|
||||
d=json.load(open('_gnn.json',encoding='utf-8'))
|
||||
print('papers:',len(d['papers']),'| repos:',len(d['gitlink_repos']),'| issues:',len(d['gitlink_issues']))
|
||||
# 列出 GitHub 稀缺(<10) 的论文 = 理论缺口候选
|
||||
for p in d['papers']:
|
||||
q=p['title'][:60]; gh=d['github_counts'].get(q,{})
|
||||
tc=gh.get('total_count')
|
||||
if tc is not None and tc < 10:
|
||||
print(' THEORY gap cand:', p['arxiv_id'], '|', p['title'][:45], '| GitHub', tc)
|
||||
"
|
||||
```
|
||||
Expected: papers=8, repos≥1, and ≥1 THEORY gap candidate (GitHub <10). Note the candidate arxiv_ids + GitHub counts. Keep `_gnn.json` for the examples doc.
|
||||
|
||||
- [ ] **Step 2: LLM-match gap cards from _gnn.json**
|
||||
|
||||
Following REFERENCE §三 prompt, produce the opportunity report from `_gnn.json`:
|
||||
- ≥1 "理论无实现" gap card (from Step 1 candidates) — with evidence triple
|
||||
- ≥1 "需求无解答" gap card (from gitlink_issues, if any research-pain issue; if issues empty/none research-y, note honestly and lean on theory gaps + lower the demand bar OR widen field keyword)
|
||||
- ≥1 "已诚实排除" entry (a paper with GitHub ≥50)
|
||||
Save the report text (will go into Task 10 examples). If no demand-side issue exists, be honest: report 2 theory gaps + 1 排除, note demand-side sparse for GNN on GitLink.
|
||||
|
||||
- [ ] **Step 3: Kickoff (fork + issue) on ONE theory gap**
|
||||
|
||||
Pick the best theory gap (GitHub <10). Fork its GitHub top repo's nearest GitLink equivalent OR the GitHub top repo isn't forkable via gitlink-cli (cross-platform) — instead: if a GitLink baseline exists, `gitlink-cli repo +fork` it; else create a todo issue on an existing GitLink GNN repo (e.g. GraphGallery) describing the reproduction plan with the paper's pseudocode.
|
||||
|
||||
```bash
|
||||
# 若有 GitLink 基准仓库，fork 它；否则在 leejt/GraphGallery 开个复现 todo issue
|
||||
gitlink-cli issue +create --owner leejt --repo GraphGallery \
|
||||
--title "Reproduction todo: <paper title> (gitlink-spark 机会)" \
|
||||
--body "<论文 arxiv 链接 + Algorithm 伪代码摘要 + 机会报告卡>"
|
||||
```
|
||||
Capture the issue URL/number. If write fails (no permission on leejt/GraphGallery), fall back: create the issue on your own fork (fork first) OR output the todo text for manual creation. Note the actual outcome.
|
||||
|
||||
- [ ] **Step 4: No commit (data-gathering)** — proceed to Task 10.
|
||||
|
||||
---
|
||||
|
||||
## Task 10: examples/spark-图神经网络.md — real walkthrough
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-spark/examples/spark-图神经网络.md`
|
||||
|
||||
- [ ] **Step 1: Write the real walkthrough using Task 9 outputs**
|
||||
|
||||
Content skeleton (fill with REAL data from `_gnn.json` + Task 9 report/kickoff — no placeholders):
|
||||
|
||||
```markdown
|
||||
# 示例：gitlink-spark GNN 缺口挖掘（真实数据）
|
||||
|
||||
> 基于 `spark.py --field "graph neural network" --max-papers 8` 于 2026-07-XX 实跑。
|
||||
|
||||
## 数据采集（真实）
|
||||
- arXiv 论文：N 篇（近 90 天）
|
||||
- GitLink 仓库：M 个（含 <列举>）
|
||||
- GitLink open issues：K 条
|
||||
- GitHub 全球对照：8 个查询
|
||||
|
||||
## 机会报告（真实全文）
|
||||
<贴 Task 9 §2 的报告全文，含 ≥1 理论缺口 + ≥1 排除，每张带实证三件套>
|
||||
|
||||
## 起跑（真实）
|
||||
<fork/issue 链接或降级说明>
|
||||
|
||||
## 关键结论
|
||||
- 三源融合真实可跑
|
||||
- GitHub 阈值生效（≥50 不报为空白）
|
||||
- 每条缺口可溯源到 spark.py JSON
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify no placeholders**
|
||||
|
||||
Run: `grep -E "TBD|TODO|<论文|<列举|<贴 Task" skills/gitlink-spark/examples/spark-图神经网络.md`
|
||||
Expected: no matches. If any, fill from Task 9 outputs.
|
||||
|
||||
- [ ] **Step 3: Clean temp + commit**
|
||||
|
||||
```bash
|
||||
rm -f skills/gitlink-spark/scripts/_gnn.json
|
||||
git add skills/gitlink-spark/examples/spark-图神经网络.md
|
||||
git commit -m "feat(spark): examples GNN 真实走查（2-3缺口卡+起跑）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 11: README + workflow link + register + acceptance
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/README.md`
|
||||
- Modify: `skills/gitlink-workflow/SKILL.md`
|
||||
|
||||
- [ ] **Step 1: Register the skill**
|
||||
|
||||
Run: `bash scripts/setup-skills.sh` then `ls ~/.claude/skills/ | grep gitlink-spark`
|
||||
Expected: `gitlink-spark` listed.
|
||||
|
||||
- [ ] **Step 2: Add README row**
|
||||
|
||||
In `skills/README.md` 智能 Skills table, after the gitlink-research-fair row add:
|
||||
|
||||
```markdown
|
||||
| **gitlink-spark** | 文献-代码语义缺口挖掘机 | arXiv×GitLink×GitHub 三源挖"理论无实现/需求无解答"缺口，出机会报告，一键 fork+issue 起跑 |
|
||||
```
|
||||
|
||||
Verify: `grep -c gitlink-spark skills/README.md` → `≥1`.
|
||||
|
||||
- [ ] **Step 3: workflow cross-link**
|
||||
|
||||
In `skills/gitlink-workflow/SKILL.md` 专项 Skill list, add:
|
||||
```markdown
|
||||
> - 科研机会发现（缺口挖掘） → [`../gitlink-spark/SKILL.md`](../gitlink-spark/SKILL.md)
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Acceptance (spec §15)**
|
||||
|
||||
Verify:
|
||||
- [ ] 四件套齐全（SKILL.md + spark.py + REFERENCE.md + examples/）
|
||||
- [ ] `python spark.py --field 图神经网络` 输出合法 JSON
|
||||
- [ ] GNN 跑出 ≥1 理论 + ≥1 demand（或诚实标注 demand 稀疏）缺口卡，三件套可查
|
||||
- [ ] GitHub 阈值生效（≥1 "已诚实排除"）
|
||||
- [ ] ≥1 理论缺口走完起跑
|
||||
- [ ] 每条缺口可溯源 spark.py JSON
|
||||
- [ ] REFERENCE 含分类法+数据源实测+诚实边界
|
||||
- [ ] README 登记
|
||||
|
||||
- [ ] **Step 5: Commit + push (updates PR #5)**
|
||||
|
||||
```bash
|
||||
git add skills/README.md skills/gitlink-workflow/SKILL.md
|
||||
git commit -m "docs(spark): README 登记 + workflow 链接 + 注册"
|
||||
git push myfork feat/gitlink-research-fair
|
||||
```
|
||||
|
|
@ -1,759 +0,0 @@
|
|||
# gitlink-research-fair v2 Implementation Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Upgrade `gitlink-research-fair` from "5-axis FAIR card" to **科研软件 X 光 (Research Software X-Ray)** — a runnable `fair.py` extracts a real research profile (paper/datasets/repro/citation), LLM renders a varied per-repo report (verdict line + real Mermaid knowledge graph + repo-specific findings) with optional prescription.
|
||||
|
||||
**Architecture:** `scripts/fair.py` = stdlib-only deterministic extractor (README regex + file scan → research-profile JSON). `SKILL.md` orchestrates the LLM: 4-dimension verdicts (each citing fair.py evidence) → real knowledge graph → hybrid report → optional fork+PR prescription. Pure extractors are unit-tested; Feature_Critic + Edge live runs are integration validation.
|
||||
|
||||
**Tech Stack:** Python 3.11 stdlib only (argparse/json/subprocess/re). gitlink-cli (file +get/+list, repo +info, commit +list). Mermaid for the graph.
|
||||
|
||||
**Source of truth:** `docs/superpowers/specs/2026-07-07-gitlink-research-fair-v2-design.md` (read it first).
|
||||
|
||||
---
|
||||
|
||||
## Environment & Gotchas (engineer must know)
|
||||
|
||||
- **Branch:** `feat/gitlink-research-fair` (v2 升级与 v1/spark 同 PR #5). Commit only your own files; leave pre-existing `D README_TASKB.md` / `D gitlink-cli.exe` / `?? dist/` / `?? _edge_prescription/` / `?? report-cards/` untouched.
|
||||
- **Encoding:** python touching gitlink-cli output MUST run `PYTHONUTF8=1 PYTHONIOENCODING=utf-8`. Never inline Chinese in `python -c` — write a `.py` file.
|
||||
- **`file +list` returns `data` as a stringified JSON** → `json.loads` it (known structure, see Task 3).
|
||||
- **`file +get` content lives at `data.entries.content`** (plain text, not base64).
|
||||
- **`--repo` uses identifier** (ASCII slug, e.g. `Feature_Critic`), not Chinese display name.
|
||||
- **stdlib only** — no pip. Tests run via `python test_fair.py` (assert-based, no pytest).
|
||||
- **v1 to remove:** the old `examples/research-fair-workflow.md` (songhui18 v1 report card) is replaced by v2 examples (Task 8 `git rm`s it).
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
| File | Responsibility |
|
||||
|------|----------------|
|
||||
| `skills/gitlink-research-fair/scripts/fair.py` | Stdlib extractor: README regex + file scan → research-profile JSON. Pure extractors + gitlink-cli fetchers + main() |
|
||||
| `skills/gitlink-research-fair/scripts/test_fair.py` | Assert-based unit tests for pure extractors (extract_paper, extract_datasets, assess_repro, assess_citation, extract_methods_frameworks) |
|
||||
| `skills/gitlink-research-fair/SKILL.md` | REWRITE: X-ray pipeline, 4-dim verdict table, hybrid report template, real KG section, prescription guardrails, degradation table |
|
||||
| `skills/gitlink-research-fair/REFERENCE.md` | REWRITE: 4-dim verdict rules, real KG schema, extraction rules, data-source findings, FAIR4RS anchor |
|
||||
| `skills/gitlink-research-fair/examples/feature-critic-xray.md` | Real Feature_Critic X-ray (live-demo script) |
|
||||
| `skills/gitlink-research-fair/examples/edge-xray.md` | Real Edge X-ray (engine-class contrast: license-conflict finding) |
|
||||
| `skills/README.md` + `skills/gitlink-workflow/SKILL.md` | Update fair description → "科研软件 X 光" |
|
||||
|
||||
---
|
||||
|
||||
## Task 1: fair.py — extract_paper + extract_datasets + tests (TDD)
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-research-fair/scripts/fair.py`
|
||||
- Create: `skills/gitlink-research-fair/scripts/test_fair.py`
|
||||
|
||||
- [ ] **Step 1: Write the failing test**
|
||||
|
||||
`test_fair.py` (exact):
|
||||
|
||||
```python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""Assert-based unit tests for fair.py pure extractors. Run: python test_fair.py"""
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(__file__))
|
||||
from fair import extract_paper, extract_datasets, assess_repro, assess_citation, extract_methods_frameworks
|
||||
|
||||
SAMPLE_README = """# Feature_Critic
|
||||
Demo code for 'Feature-Critic Networks for Heterogeneous Domain Generalisation'.
|
||||
This paper is located at https://arxiv.org/abs/1901.11448 and will appear in ICML 2019.
|
||||
Evaluated on PACS and Visual Decathlon.
|
||||
|
||||
@inproceedings{li2019feature,
|
||||
title={Feature-Critic Networks},
|
||||
booktitle={ICML}}
|
||||
"""
|
||||
|
||||
SAMPLE_FILES = ["README.md", "main_Feature_Critic.py", "main_baseline.py", "model_PACS.py",
|
||||
"alexnet.py", "resnet.py", "vggnet.py", "data_gen_PACS.py", "get_model_dataset.sh", "utils.py"]
|
||||
|
||||
def test_extract_paper():
|
||||
p = extract_paper(SAMPLE_README)
|
||||
assert p["arxiv_id"] == "1901.11448", p["arxiv_id"]
|
||||
assert p["arxiv_url"] == "https://arxiv.org/abs/1901.11448"
|
||||
assert p["venue"] == "ICML"
|
||||
assert p["in_readme"] is True
|
||||
print("test_extract_paper OK")
|
||||
|
||||
def test_extract_paper_none():
|
||||
p = extract_paper("# Hello\nA normal project with no paper.")
|
||||
assert p["in_readme"] in (False, True) # title-only may set in_readme; arxiv must be None
|
||||
assert p["arxiv_id"] is None
|
||||
print("test_extract_paper_none OK")
|
||||
|
||||
def test_extract_datasets():
|
||||
ds = extract_datasets(SAMPLE_README, SAMPLE_FILES)
|
||||
names = [d["name"] for d in ds]
|
||||
assert "PACS" in names and "Visual Decathlon" in names
|
||||
pacs = [d for d in ds if d["name"] == "PACS"][0]
|
||||
assert pacs["download_script"] and "data_gen_PACS.py" in pacs["download_script"]
|
||||
print("test_extract_datasets OK")
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_extract_paper(); test_extract_paper_none(); test_extract_datasets()
|
||||
print("PART 1 OK (run all after Task 2)")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify it fails**
|
||||
|
||||
Run: `cd skills/gitlink-research-fair/scripts && python test_fair.py`
|
||||
Expected: FAIL with `ModuleNotFoundError: No module named 'fair'`
|
||||
|
||||
- [ ] **Step 3: Write fair.py with extract_paper + extract_datasets (+ stubs for Task 2 functions so import works)**
|
||||
|
||||
`fair.py` (exact):
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""gitlink-research-fair v2: research software X-ray. Extract a research profile from a GitLink repo. Stdlib only."""
|
||||
import argparse, json, os, sys, subprocess, re
|
||||
|
||||
_ARXIV_PATS = [
|
||||
r'https?://arxiv\.org/(?:abs|pdf)/(\d{4}\.\d{4,5})',
|
||||
r'arXiv:(\d{4}\.\d{4,5})',
|
||||
r'\b(\d{4}\.\d{4,5})\b',
|
||||
]
|
||||
_DOI_PAT = r'10\.\d{4,9}/\S+'
|
||||
_VENUES = ["ICML", "NeurIPS", "NIPS", "ICLR", "CVPR", "ICCV", "ECCV", "ACL", "EMNLP",
|
||||
"NAACL", "KDD", "WWW", "AAAI", "IJCAI", "SIGGRAPH", "Nature", "Science"]
|
||||
_KNOWN_DATASETS = ["Visual Decathlon", "PACS", "ImageNet", "CIFAR-10", "CIFAR-100", "CIFAR",
|
||||
"Cora", "Citeseer", "Pubmed", "MNIST", "COCO", "QM9", "ZINC", "OGB", "ogbn",
|
||||
"Wikipedia", "PPI", "Reddit", "Amazon", "Yelp", "MUTAG"]
|
||||
|
||||
def extract_paper(readme):
|
||||
"""Extract paper provenance (arxiv/doi/title/venue) from README text."""
|
||||
if not readme:
|
||||
return {"in_readme": False, "arxiv_id": None, "arxiv_url": None, "doi": None,
|
||||
"title": None, "authors": [], "venue": None}
|
||||
arxiv_id = arxiv_url = None
|
||||
for pat in _ARXIV_PATS:
|
||||
m = re.search(pat, readme)
|
||||
if m:
|
||||
arxiv_id = m.group(1); arxiv_url = f"https://arxiv.org/abs/{m.group(1)}"; break
|
||||
doi = None
|
||||
m = re.search(_DOI_PAT, readme)
|
||||
if m:
|
||||
doi = m.group(0).rstrip(").,;]")
|
||||
venue = None
|
||||
for v in _VENUES:
|
||||
if re.search(rf"\b{re.escape(v)}\b", readme):
|
||||
venue = v; break
|
||||
title = None
|
||||
m2 = (re.search(r"[Cc]ode (?:for|of)\s+'([^']+)'", readme)
|
||||
or re.search(r'[Cc]ode (?:for|of)\s+"([^"]+)"', readme)
|
||||
or re.search(r"^\s*#\s+(.+)$", readme, re.M))
|
||||
if m2:
|
||||
title = m2.group(1).strip()
|
||||
return {"in_readme": bool(arxiv_id or doi or title), "arxiv_id": arxiv_id,
|
||||
"arxiv_url": arxiv_url, "doi": doi, "title": title, "authors": [], "venue": venue}
|
||||
|
||||
def extract_datasets(readme, files):
|
||||
"""Identify referenced datasets (known-name match + data scripts)."""
|
||||
text = readme or ""
|
||||
found = []
|
||||
for ds in _KNOWN_DATASETS:
|
||||
if re.search(rf"\b{re.escape(ds)}\b", text, re.I):
|
||||
found.append(ds)
|
||||
scripts = [f for f in files if any(k in (f or "").lower()
|
||||
for k in ["data_gen", "get_data", "download", "prepare_data", "data_load"])]
|
||||
return [{"name": ds, "evidence": "mentioned in README",
|
||||
"download_script": scripts[:2] or None, "license": None} for ds in found]
|
||||
|
||||
def assess_repro(files, readme): # implemented in Task 2
|
||||
return {"deps_files": [], "deps_pinned": False, "entry_points": [], "expected_results": False, "env_spec": False}
|
||||
|
||||
def assess_citation(files, readme): # implemented in Task 2
|
||||
return {"cff": False, "codemeta": False, "zenodo": False, "readme_bibtex": None}
|
||||
|
||||
def extract_methods_frameworks(files, readme): # implemented in Task 2
|
||||
return {"methods": [], "frameworks": []}
|
||||
|
||||
def main(): # implemented in Task 3
|
||||
pass
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run test to verify Task-1 tests pass**
|
||||
|
||||
Run: `cd skills/gitlink-research-fair/scripts && python test_fair.py`
|
||||
Expected: `test_extract_paper OK` / `test_extract_paper_none OK` / `test_extract_datasets OK` / `PART 1 OK`
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-research-fair/scripts/fair.py skills/gitlink-research-fair/scripts/test_fair.py
|
||||
git commit -m "feat(fair-v2): fair.py extract_paper + extract_datasets + test（TDD）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 2: fair.py — assess_repro + assess_citation + extract_methods_frameworks (real impl + tests)
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-research-fair/scripts/fair.py` (replace the 3 stubs)
|
||||
- Modify: `skills/gitlink-research-fair/scripts/test_fair.py` (add tests)
|
||||
|
||||
- [ ] **Step 1: Add tests for the 3 functions**
|
||||
|
||||
Append to `test_fair.py` (before the `if __name__` block):
|
||||
|
||||
```python
|
||||
def test_assess_repro():
|
||||
files = ["README.md", "main_Feature_Critic.py", "requirements.txt", "model_PACS.py"]
|
||||
r = assess_repro(files, SAMPLE_README)
|
||||
assert "requirements.txt" in r["deps_files"]
|
||||
assert r["deps_pinned"] is True
|
||||
assert "main_Feature_Critic.py" in r["entry_points"]
|
||||
assert r["expected_results"] is False # SAMPLE_README has no accuracy/results table
|
||||
print("test_assess_repro OK")
|
||||
|
||||
def test_assess_citation():
|
||||
c = assess_citation(SAMPLE_FILES, SAMPLE_README)
|
||||
assert c["cff"] is False and c["codemeta"] is False
|
||||
assert c["readme_bibtex"] and "@inproceedings" in c["readme_bibtex"]
|
||||
print("test_assess_citation OK")
|
||||
|
||||
def test_extract_methods_frameworks():
|
||||
mf = extract_methods_frameworks(SAMPLE_FILES, SAMPLE_README)
|
||||
assert "domain generalisation" in mf["methods"], mf["methods"] # SAMPLE_README 提到 Domain Generalisation
|
||||
assert isinstance(mf["frameworks"], list)
|
||||
print("test_extract_methods_frameworks OK")
|
||||
```
|
||||
|
||||
And replace the `if __name__ == "__main__":` block with:
|
||||
|
||||
```python
|
||||
if __name__ == "__main__":
|
||||
test_extract_paper(); test_extract_paper_none(); test_extract_datasets()
|
||||
test_assess_repro(); test_assess_citation(); test_extract_methods_frameworks()
|
||||
print("ALL TESTS PASSED")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Run test to verify the 3 new ones fail**
|
||||
|
||||
Run: `cd skills/gitlink-research-fair/scripts && python test_fair.py`
|
||||
Expected: `test_assess_repro OK` may print then FAIL on assert (stubs return empty deps_files → `"requirements.txt" in []` is False → assert fails). Confirms stubs need replacing.
|
||||
|
||||
- [ ] **Step 3: Replace the 3 stubs with real implementations**
|
||||
|
||||
Replace `def assess_repro(...) ...` / `def assess_citation(...) ...` / `def extract_methods_frameworks(...) ...` with:
|
||||
|
||||
```python
|
||||
def assess_repro(files, readme):
|
||||
"""Static reproducibility readiness: deps + entry + env + expected results."""
|
||||
name_set = {(f or "") for f in files}
|
||||
deps_candidates = ["requirements.txt", "environment.yml", "go.mod", "package.json",
|
||||
"Dockerfile", "setup.py", "pyproject.toml"]
|
||||
deps_files = [f for f in deps_candidates if f in name_set]
|
||||
entry_points = sorted([f for f in name_set if re.match(r"(main|train|run|demo)_?\w*\.py$", f, re.I)])
|
||||
env_spec = any(f in ("Dockerfile", "environment.yml") for f in deps_files)
|
||||
expected = bool(re.search(r"(accuracy|f1\b|bleu|rouge|results?\s*(table|in section)|table\s*\d)",
|
||||
readme or "", re.I))
|
||||
return {"deps_files": deps_files, "deps_pinned": bool(deps_files),
|
||||
"entry_points": entry_points[:5], "expected_results": expected, "env_spec": env_spec}
|
||||
|
||||
def assess_citation(files, readme):
|
||||
"""Citation readiness: CITATION.cff / codemeta / zenodo + README bibtex."""
|
||||
name_set = {(f or "") for f in files}
|
||||
m = re.search(r"@(inproceedings|article|misc|book)\{[^}]+\}", readme or "", re.S | re.I)
|
||||
return {"cff": "CITATION.cff" in name_set,
|
||||
"codemeta": "codemeta.json" in name_set,
|
||||
"zenodo": ".zenodo.json" in name_set,
|
||||
"readme_bibtex": (m.group(0)[:200] if m else None)}
|
||||
|
||||
def extract_methods_frameworks(files, readme):
|
||||
"""Infer methods + frameworks from filenames + README."""
|
||||
text = " ".join(files) + " " + (readme or "")
|
||||
frameworks = []
|
||||
if re.search(r"\b(torch|pytorch|nn\.module)\b", text, re.I): frameworks.append("PyTorch")
|
||||
if re.search(r"\b(tensorflow|tf\.|keras)\b", text, re.I): frameworks.append("TensorFlow")
|
||||
if re.search(r"\b(jax|flax|haiku)\b", text, re.I): frameworks.append("JAX")
|
||||
if re.search(r"\b(sklearn|scikit-learn)\b", text, re.I): frameworks.append("scikit-learn")
|
||||
methods = []
|
||||
for kw in ["attention", "transformer", "contrastive", "meta-learning", "federated",
|
||||
"graph", "convolution", "resnet", "gan", "diffusion", "reinforcement",
|
||||
"domain generalisation", "domain generalization"]:
|
||||
if re.search(rf"\b{kw}", text, re.I):
|
||||
methods.append(kw)
|
||||
return {"methods": methods[:6],
|
||||
"frameworks": frameworks or ["unknown (infer from filenames; verify imports)"]}
|
||||
```
|
||||
|
||||
- [ ] **Step 4: Run all tests — expect ALL PASS**
|
||||
|
||||
Run: `cd skills/gitlink-research-fair/scripts && python test_fair.py`
|
||||
Expected: `ALL TESTS PASSED` (6 tests)
|
||||
|
||||
- [ ] **Step 5: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-research-fair/scripts/fair.py skills/gitlink-research-fair/scripts/test_fair.py
|
||||
git commit -m "feat(fair-v2): assess_repro + assess_citation + extract_methods_frameworks（6 测试全过）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 3: fair.py — gitlink-cli fetchers + main + end-to-end smoke
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/gitlink-research-fair/scripts/fair.py` (add network layer + replace main stub)
|
||||
|
||||
- [ ] **Step 1: Add gitlink-cli fetchers + implement main()**
|
||||
|
||||
Insert before `def main():` and replace the `def main(): pass` stub:
|
||||
|
||||
```python
|
||||
def _gitlink(*args):
|
||||
"""Run gitlink-cli with json output; return parsed dict (UTF-8 safe)."""
|
||||
r = subprocess.run(["gitlink-cli"] + list(args) + ["--format", "json"],
|
||||
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=60)
|
||||
raw = r.stdout
|
||||
i = raw.find("{")
|
||||
return json.loads(raw[i:]) if i >= 0 else {}
|
||||
|
||||
def fetch_readme(owner, repo):
|
||||
d = _gitlink("file", "+get", "--owner", owner, "--repo", repo, "--path", "README.md")
|
||||
ent = (d.get("data", {}) or {}).get("entries", {}) or {}
|
||||
return ent.get("content", "") if isinstance(ent, dict) else ""
|
||||
|
||||
def fetch_file_list(owner, repo):
|
||||
d = _gitlink("file", "+list", "--owner", owner, "--repo", repo)
|
||||
fd = d.get("data", "[]")
|
||||
if isinstance(fd, str):
|
||||
fd = json.loads(fd)
|
||||
return [f.get("name") for f in fd if isinstance(f, dict)] if isinstance(fd, list) else []
|
||||
|
||||
def fetch_repo_meta(owner, repo):
|
||||
info = _gitlink("repo", "+info", "--owner", owner, "--repo", repo)
|
||||
comm = _gitlink("commit", "+list", "--owner", owner, "--repo", repo, "--page", "1")
|
||||
cd = comm.get("data", {})
|
||||
cl = cd.get("commits") if isinstance(cd, dict) else None
|
||||
head = (cl[0].get("sha") if cl and isinstance(cl, list) and cl else None)
|
||||
d = info.get("data", {}) or {}
|
||||
return {"identifier": d.get("identifier"), "license_id": d.get("license_id"),
|
||||
"has_dataset": d.get("has_dataset"), "head_sha": head}
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description="gitlink-research-fair v2: research software X-ray")
|
||||
ap.add_argument("--owner", required=True)
|
||||
ap.add_argument("--repo", required=True)
|
||||
args = ap.parse_args()
|
||||
|
||||
readme = fetch_readme(args.owner, args.repo)
|
||||
files = fetch_file_list(args.owner, args.repo)
|
||||
meta = fetch_repo_meta(args.owner, args.repo)
|
||||
mf = extract_methods_frameworks(files, readme)
|
||||
profile = {
|
||||
"repo": f"{args.owner}/{args.repo}",
|
||||
"head_sha": meta.get("head_sha"),
|
||||
"paper": extract_paper(readme),
|
||||
"datasets": extract_datasets(readme, files),
|
||||
"repro": assess_repro(files, readme),
|
||||
"citation": assess_citation(files, readme),
|
||||
"methods": mf["methods"],
|
||||
"frameworks": mf["frameworks"],
|
||||
"license": {"file": any("LICENSE" in (f or "") for f in files),
|
||||
"license_id": meta.get("license_id")},
|
||||
"files_count": len(files),
|
||||
}
|
||||
json.dump(profile, sys.stdout, ensure_ascii=False, indent=2)
|
||||
sys.stdout.write("\n")
|
||||
```
|
||||
|
||||
- [ ] **Step 2: End-to-end smoke (live, Feature_Critic)**
|
||||
|
||||
Run:
|
||||
```bash
|
||||
cd skills/gitlink-research-fair/scripts
|
||||
PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python fair.py --owner liyiying10 --repo Feature_Critic > _xray.json 2>&1
|
||||
PYTHONUTF8=1 python -c "
|
||||
import json
|
||||
d=json.load(open('_xray.json',encoding='utf-8'))
|
||||
print('repo:', d['repo'], '| head:', (d.get('head_sha') or '')[:7])
|
||||
print('paper arxiv:', d['paper']['arxiv_id'], '| venue:', d['paper']['venue'], '| in_readme:', d['paper']['in_readme'])
|
||||
print('datasets:', [x['name'] for x in d['datasets']])
|
||||
print('repro deps:', d['repro']['deps_files'], '| entry:', d['repro']['entry_points'], '| env:', d['repro']['env_spec'])
|
||||
print('citation cff:', d['citation']['cff'], '| bibtex?', bool(d['citation']['readme_bibtex']))
|
||||
print('files:', d['files_count'])
|
||||
"
|
||||
rm -f _xray.json
|
||||
```
|
||||
Expected: arxiv `1901.11448` + venue `ICML` + datasets incl `PACS`/`Visual Decathlon` + entry `main_Feature_Critic.py` + cff False + bibtex True + files 15. If arxiv None, inspect README (the repo may have changed; adapt regex). If `file +list` parse fails, confirm data is stringified-JSON and json.loads handles it.
|
||||
|
||||
- [ ] **Step 3: Re-run unit tests (regression)**
|
||||
|
||||
Run: `cd skills/gitlink-research-fair/scripts && python test_fair.py`
|
||||
Expected: `ALL TESTS PASSED`
|
||||
|
||||
- [ ] **Step 4: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-research-fair/scripts/fair.py
|
||||
git commit -m "feat(fair-v2): gitlink-cli fetchers + main() 编排 → 科研画像 JSON（Feature_Critic smoke 通过）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 4: Rewrite SKILL.md (X-ray pipeline + 4-dim + hybrid report + real KG + prescription + degradation)
|
||||
|
||||
**Files:**
|
||||
- Modify (overwrite): `skills/gitlink-research-fair/SKILL.md`
|
||||
|
||||
- [ ] **Step 1: Overwrite SKILL.md with the v2 content**
|
||||
|
||||
New `SKILL.md` (exact — this replaces the v1 5-axis content entirely):
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: gitlink-research-fair
|
||||
version: 2.0.0
|
||||
description: "科研软件 X 光：用 fair.py 真抽取 GitLink 科研仓库的论文/数据/复现/引用画像，LLM 四维裁决，输出含真科研图谱与特有关键发现的洞察报告，可选处方 PR。当用户需要深挖科研仓库的科研产物、评估可复现/可引用性时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "python skills/gitlink-research-fair/scripts/fair.py --help"
|
||||
---
|
||||
|
||||
# gitlink-research-fair v2（科研软件 X 光）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 裁决由 LLM 做出，但每条必须引用 `fair.py` 抽到的实证（arxiv id / 文件名 / deps 状态）；无实证的判断丢弃。**
|
||||
**CRITICAL — 处方（开 PR）默认预览确认；绝不自动 merge、绝不 force-push、绝不碰原仓库。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；四维裁决细则、真 KG schema、抽取规则见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
## 概述
|
||||
|
||||
**科研软件 X 光**：`scripts/fair.py` 真抽取仓库内容（README/文件/依赖）→ 科研画像 JSON；LLM 对 4 个科研专属维度裁决（论文溯源/数据链/复现就绪/引用就绪），渲染**每 repo 特有的洞察报告**（裁决总览 + 真科研图谱 + 关键发现），可选处方 PR。与 `gitlink-health`（项目过程健康）正交，与 `gitlink-spark`（跨仓挖缺口）互补——本 skill **单仓深挖科研产物**。
|
||||
|
||||
## 命令接口
|
||||
|
||||
```bash
|
||||
python skills/gitlink-research-fair/scripts/fair.py --owner <owner> --repo <identifier>
|
||||
# → stdout: 科研画像 JSON {paper, datasets, repro, citation, methods, frameworks, license, head_sha, files_count}
|
||||
```
|
||||
|
||||
skill 约定参数（非 CLI flag）：
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库（用 identifier） |
|
||||
| `--auto` | 关 | 跳过预览直接开处方 PR（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出 X 光报告，不开 PR |
|
||||
| `--refresh` | 关 | 即使有旧哨兵也重评 |
|
||||
|
||||
## 管道
|
||||
|
||||
### ① 抽取（fair.py，确定性）
|
||||
`fetch_readme`（file +get）+ `fetch_file_list`（file +list）+ `fetch_repo_meta`（repo +info + commit +list 取 HEAD sha）→ `extract_paper` / `extract_datasets` / `assess_repro` / `assess_citation` / `extract_methods_frameworks` → 科研画像 JSON
|
||||
|
||||
### ② 四维裁决（LLM，读 JSON）
|
||||
论文溯源 / 数据链 / 复现就绪 / 引用就绪。每维 `✅/⚠️/❌` + **引用画像字段的具体证据**。规则见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
### ③ 真科研图谱（从画像生成 Mermaid）
|
||||
节点 `Paper↔Method↔Code↔Dataset↔Framework↔Citation`，带状态色（✅绿/⚠️黄/❌红）。schema 见 REFERENCE。
|
||||
|
||||
### ④ 渲染 X 光报告（hero）并落盘
|
||||
裁决一行 + 真图谱 + **本 repo 特有关键发现** + 处方摘要 + 双裁决证书。**始终保存** `report-cards/<owner>-<repo>-xray.md`（绝不只在终端）。
|
||||
|
||||
### ⑤ 处方（可选）
|
||||
对 ❌/⚠️ 项生成 CITATION.cff（从 README 抽的引用）/ requirements.txt（从 import 扫）/ Dockerfile → fork → PR（默认预览）。
|
||||
|
||||
## 四维裁决（速览，细则见 REFERENCE）
|
||||
|
||||
| 维度 | ✅ | ⚠️ | ❌ |
|
||||
|------|---|----|----|
|
||||
| 论文溯源 | arxiv/DOI + 元数据全 | 仅 README 文字，无稳定链接 | 无论文线索 |
|
||||
| 数据链 | 命名 + 下载脚本 + license | 命名但无脚本/无 license | 未提及数据集 |
|
||||
| 复现就绪 | 依赖锁+入口+环境+期望结果齐全 | 有入口但缺依赖锁/环境/期望结果 | 无入口/无依赖 |
|
||||
| 引用就绪 | CITATION.cff/codemeta + DOI + 版本 | 仅 README 引用文本 | 无引用信息 |
|
||||
|
||||
## 报告格式（混合主视觉，hero）
|
||||
|
||||
````markdown
|
||||
🔬 **科研软件 X 光 — <owner>/<repo>**
|
||||
|
||||
═══════════════════════════════════════
|
||||
论文溯源 <V> ｜ 数据链 <V> ｜ 复现就绪 <V> ｜ 引用就绪 <V>
|
||||
═══════════════════════════════════════
|
||||
|
||||
### 🧬 真科研图谱
|
||||
```mermaid
|
||||
graph LR
|
||||
P[<paper venue+arxiv>]:::ok -->|proposes| M[<method>]
|
||||
M -->|implements| C[<entry file>]:::ok
|
||||
C -->|uses| D[<datasets>]:::warn
|
||||
C -->|depends| F[<framework>]:::warn
|
||||
P -->|cited-via| Ci[<CITATION? or 无>]:::bad
|
||||
classDef ok fill:#cfe,stroke:#3a3; classDef warn fill:#ffe,stroke:#cc3; classDef bad fill:#fee,stroke:#c33;
|
||||
```
|
||||
|
||||
### 🔍 关键发现（本 repo 特有）
|
||||
- <LLM 从画像抽出的 ≥3 条具体发现，每条引用 fair.py 字段>
|
||||
|
||||
### 🔧 处方（可选）
|
||||
- <对 ❌/⚠️ 项的修复建议>
|
||||
|
||||
### 📜 双裁决证书
|
||||
复现就绪 <V> ｜ 引用就绪 <V> ｜ 锚定 commit `<sha>`
|
||||
|
||||
---
|
||||
<!-- gitlink-research-fair v2 | repo:<owner>/<repo> | paper:<✅/⚠️/❌> | repro:<V> | cite:<V> | sha:<head> -->
|
||||
*由 gitlink-research-fair v2（科研软件 X 光）生成。*
|
||||
````
|
||||
|
||||
## 处方闭环 + 护栏
|
||||
|
||||
对 ❌/⚠️ 项生成修复：`CITATION.cff`（从 README 抽的引用文本构造）+ `requirements.txt`（从代码 import 扫）+ `Dockerfile`（模板）→ `repo +fork` → `pr +create`（PR body 带报告摘要）。**护栏**：默认预览；`--auto` 跳过但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 报告已落盘（④），不开 PR。
|
||||
|
||||
## 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| README 读失败 | 降级用 file list + 元数据，标注"README 不可读，结论受限" |
|
||||
| `file +list` data 为字符串 | json.loads 解套 |
|
||||
| arxiv/DOI 抽不到 | 论文溯源判 ⚠️/❌，据实 |
|
||||
| 框架无法推断 | frameworks 标"未知"，不编造 |
|
||||
| `--repo` 用中文显示名 404 | 提示用 identifier |
|
||||
| fork/PR 失败 | 处方物料落本地，告知路径 |
|
||||
| 报告/PR 发布失败 | 报告已在 ④ 落盘，告知路径 |
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify the rewrite removed v1 content**
|
||||
|
||||
Run: `grep -c -e "5 轴评分 Rubric" -e "Repro 可复现" -e "五轴雷达" skills/gitlink-research-fair/SKILL.md`
|
||||
Expected: `0` (v1 5-axis content gone). Then `grep -c -e "科研软件 X 光" -e "四维裁决" -e "真科研图谱" skills/gitlink-research-fair/SKILL.md` → expect `≥3`.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-research-fair/SKILL.md
|
||||
git commit -m "feat(fair-v2): 重写 SKILL.md（X光管道+四维裁决+混合报告+真图谱+处方），移除v1五轴"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 5: Rewrite REFERENCE.md (4-dim rules + KG schema + extraction rules + FAIR4RS anchor)
|
||||
|
||||
**Files:**
|
||||
- Modify (overwrite): `skills/gitlink-research-fair/REFERENCE.md`
|
||||
|
||||
- [ ] **Step 1: Overwrite REFERENCE.md with v2 content**
|
||||
|
||||
New `REFERENCE.md` (exact — replaces v1):
|
||||
|
||||
```markdown
|
||||
# gitlink-research-fair v2 参考文档（科研软件 X 光）
|
||||
|
||||
> SKILL.md 的深度参考：四维裁决细则、真 KG schema、fair.py 抽取规则、数据源实测、学术锚。
|
||||
|
||||
## 一、四维裁决细则
|
||||
|
||||
每维 `✅/⚠️/❌`，**必须引用 fair.py 画像字段作证据**。
|
||||
|
||||
### 论文溯源（F2/R1.2）
|
||||
- ✅ `paper.arxiv_id` 或 `paper.doi` 非空 + `paper.title`/`venue` 抽到
|
||||
- ⚠️ 仅 `paper.title` 抽到（"Code for..." 句式），无 arxiv/DOI
|
||||
- ❌ `paper.in_readme` = False
|
||||
|
||||
### 数据链（FAIR 数据维度）
|
||||
- ✅ `datasets` 非空 + 至少一个有 `download_script` + 数据 license 可考
|
||||
- ⚠️ `datasets` 非空（命名）但无 download_script 或无 license
|
||||
- ❌ `datasets` 为空
|
||||
|
||||
### 复现就绪（独立于 FAIR）
|
||||
- ✅ `repro.deps_pinned`=True + `entry_points` 非空 + `env_spec`=True + `expected_results`=True（四件齐全）
|
||||
- ⚠️ 有 `entry_points` 但缺依赖锁/环境/期望结果中任一
|
||||
- ❌ 无 `entry_points` 或无 `deps_files`
|
||||
|
||||
### 引用就绪（R1.1/R2）
|
||||
- ✅ `citation.cff` 或 `citation.codemeta` 为 True + 有版本/DOI
|
||||
- ⚠️ 仅 `citation.readme_bibtex` 非空（README 有引用文本，无机器可读文件）
|
||||
- ❌ 三者皆 False
|
||||
|
||||
## 二、真科研图谱 schema（Mermaid）
|
||||
|
||||
节点：`Paper(venue+arxiv)` / `Method` / `Code(entry file)` / `Dataset` / `Framework` / `Citation`
|
||||
边：`Paper —proposes→ Method`、`Method —implements→ Code`、`Code —uses→ Dataset`、`Code —depends→ Framework`、`Paper —cited-via→ Citation`
|
||||
状态色（按对应维度裁决）：✅ `classDef ok fill:#cfe` / ⚠️ `classDef warn fill:#ffe` / ❌ `classDef bad fill:#fee`
|
||||
|
||||
## 三、fair.py 抽取规则
|
||||
|
||||
- **arxiv**：三路正则（arxiv URL / `arXiv:id` / 裸 `\d{4}.\d{4,5}`），取首个命中
|
||||
- **venue**：白名单（ICML/NeurIPS/ICLR/CVPR/ACL/...）正则
|
||||
- **datasets**：已知名白名单（PACS/Visual Decathlon/Cora/ImageNet/...）+ 数据脚本（data_gen/get_data/download）
|
||||
- **repro**：依赖文件名匹配（requirements/go.mod/environment.yml/Dockerfile/setup.py）+ 入口（main/train/run*.py）+ 期望结果（accuracy/f1/results table 正则）
|
||||
- **citation**：CITATION.cff/codemeta.json/.zenodo.json 文件存在 + README `@inproceedings/@article` bibtex
|
||||
- **frameworks**：torch/tensorflow/jax/sklearn 关键词（文件名+README），无则标"未知，verify imports"
|
||||
|
||||
## 四、数据源实测（2026-07）
|
||||
|
||||
| 源 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| `gitlink-cli file +get` | ✅ | content 在 `data.entries.content`（纯文本） |
|
||||
| `gitlink-cli file +list` | ✅ | `data` 是字符串化 JSON，需 json.loads |
|
||||
| `gitlink-cli repo +info` | ✅ | license_id/identifier/has_dataset |
|
||||
| `gitlink-cli commit +list` | ✅ | HEAD sha |
|
||||
| OpenAlex | ❌ 已砍 | v1 弱环节（间歇 503），v2 不依赖 |
|
||||
|
||||
## 五、学术锚（FAIR4RS）
|
||||
|
||||
四维裁决对标 **FAIR4RS**（Barker et al. 2022, Nature Sci Data）：论文溯源→F2/R1.2、数据链→FAIR-Data、复现就绪→（独立轴，FAIR 必要非充分）、引用就绪→R1.1/R2。诚实声明：这是适配版评分（社区尚无认证级自动校验器），非官方认证。
|
||||
|
||||
## 六、诚实边界
|
||||
|
||||
1. fair.py 抽取覆盖度受 README 写法影响；非标准 README 可能漏（同时匹配多句式兜底）。
|
||||
2. 框架/方法为推断，标"推断"/"未知"，不肯定。
|
||||
3. 复现就绪是**静态**判断（依赖/入口/环境/期望结果四件套），不实际跑代码。
|
||||
4. v1 的 OpenAlex 溯源已砍（避免 503 弱环节）。
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Verify**
|
||||
|
||||
Run: `grep -c -e "四维裁决细则" -e "真科研图谱 schema" -e "fair.py 抽取规则" -e "FAIR4RS" skills/gitlink-research-fair/REFERENCE.md`
|
||||
Expected: `4`. And `grep -c -e "5 轴" -e "OpenAlex 字段" skills/gitlink-research-fair/REFERENCE.md` → `0`.
|
||||
|
||||
- [ ] **Step 3: Commit**
|
||||
|
||||
```bash
|
||||
git add skills/gitlink-research-fair/REFERENCE.md
|
||||
git commit -m "feat(fair-v2): 重写 REFERENCE（四维裁决细则+真KG schema+抽取规则+FAIR4RS锚）"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 6: Live run — Feature_Critic X-ray (live-demo) + 落盘
|
||||
|
||||
**Files:**
|
||||
- (produces `report-cards/liyiying10-Feature_Critic-xray.md`; data feeds Task 8 example)
|
||||
|
||||
- [ ] **Step 1: Run fair.py on Feature_Critic**
|
||||
|
||||
```bash
|
||||
cd skills/gitlink-research-fair/scripts
|
||||
PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python fair.py --owner liyiying10 --repo Feature_Critic > _fc.json 2>&1
|
||||
PYTHONUTF8=1 python -c "
|
||||
import json
|
||||
d=json.load(open('_fc.json',encoding='utf-8'))
|
||||
assert d['paper']['arxiv_id']=='1901.11448', 'arxiv 抽取失败'
|
||||
assert d['paper']['venue']=='ICML'
|
||||
assert any(x['name']=='PACS' for x in d['datasets'])
|
||||
assert 'main_Feature_Critic.py' in d['repro']['entry_points']
|
||||
assert d['citation']['cff'] is False
|
||||
print('Feature_Critic 画像 OK | head:', (d.get('head_sha') or '')[:7])
|
||||
"
|
||||
```
|
||||
Expected: assertions pass. Keep `_fc.json` for the report.
|
||||
|
||||
- [ ] **Step 2: LLM-render the X-ray report (controller)**
|
||||
|
||||
Read `_fc.json`, apply REFERENCE §一 verdict rules, render the full hybrid report (verdict line + Mermaid graph + ≥3 repo-specific findings + prescription + dual-verdict certificate) per SKILL.md §报告格式. Expected verdicts: 论文溯源 ✅ / 数据链 ⚠️ / 复现就绪 ⚠️ / 引用就绪 ❌.
|
||||
|
||||
- [ ] **Step 3: Save report to report-cards/**
|
||||
|
||||
Save the rendered report to `report-cards/liyiying10-Feature_Critic-xray.md` (with sentinel). This is the live-demo artifact.
|
||||
|
||||
- [ ] **Step 4: No commit (data-gathering)** — proceed to Task 8.
|
||||
|
||||
---
|
||||
|
||||
## Task 7: Live run — Edge X-ray (contrast) + 落盘
|
||||
|
||||
**Files:**
|
||||
- (produces `report-cards/Edgedev-Edge-Computing-Engine-xray.md`; data feeds Task 8 example)
|
||||
|
||||
- [ ] **Step 1: Run fair.py on Edge**
|
||||
|
||||
```bash
|
||||
cd skills/gitlink-research-fair/scripts
|
||||
PYTHONUTF8=1 PYTHONIOENCODING=utf-8 python fair.py --owner Edgedev --repo Edge-Computing-Engine > _edge.json 2>&1
|
||||
PYTHONUTF8=1 python -c "
|
||||
import json
|
||||
d=json.load(open('_edge.json',encoding='utf-8'))
|
||||
print('Edge | paper:', d['paper'].get('arxiv_id'), '| methods:', d['methods'][:3], '| frameworks:', d['frameworks'][:2])
|
||||
print('license file:', d['license']['file'], '| files:', d['files_count'])
|
||||
"
|
||||
```
|
||||
Expected: paper arxiv likely None (Edge has no arxiv), methods incl autodiff/CNN-ish, license file True. Keep `_edge.json`.
|
||||
|
||||
- [ ] **Step 2: LLM-render Edge X-ray + save**
|
||||
|
||||
Render the Edge X-ray (controller). The **license-conflict finding** (README "禁止闭源商用" vs Apache LICENSE — note: fair.py detects `license.file=True`; the conflict is read from README content during rendering) must appear as a key finding. Verdicts will differ from Feature_Critic (e.g., 论文溯源 ❌, no paper). Save to `report-cards/Edgedev-Edge-Computing-Engine-xray.md`. The two reports must look visibly different (proves not 千篇一律).
|
||||
|
||||
- [ ] **Step 3: No commit** — proceed to Task 8.
|
||||
|
||||
---
|
||||
|
||||
## Task 8: examples (2 docs) + remove v1 example
|
||||
|
||||
**Files:**
|
||||
- Create: `skills/gitlink-research-fair/examples/feature-critic-xray.md`
|
||||
- Create: `skills/gitlink-research-fair/examples/edge-xray.md`
|
||||
- Remove: `skills/gitlink-research-fair/examples/research-fair-workflow.md` (v1 songhui18)
|
||||
|
||||
- [ ] **Step 1: Write feature-critic-xray.md (using Task 6 outputs)**
|
||||
|
||||
Real walkthrough: the fair.py command + the画像摘要 + the full X-ray report (from `report-cards/liyiying10-Feature_Critic-xray.md`) + a "答辩演示脚本" section (what to say when demoing live). No placeholders — all real values (arxiv 1901.11448, PACS/Visual Decathlon, etc.).
|
||||
|
||||
- [ ] **Step 2: Write edge-xray.md (using Task 7 outputs)**
|
||||
|
||||
Real walkthrough: fair.py command + 画像 + X-ray report (license-conflict finding). Emphasize the contrast with Feature_Critic (different profile → different report).
|
||||
|
||||
- [ ] **Step 3: Remove v1 example + clean temp + commit**
|
||||
|
||||
```bash
|
||||
cd "C:\Users\CWQ98\Desktop\演化与运维\gitlink-cli"
|
||||
git rm skills/gitlink-research-fair/examples/research-fair-workflow.md
|
||||
rm -f skills/gitlink-research-fair/scripts/_fc.json skills/gitlink-research-fair/scripts/_edge.json
|
||||
rm -rf skills/gitlink-research-fair/scripts/__pycache__
|
||||
git add skills/gitlink-research-fair/examples/feature-critic-xray.md skills/gitlink-research-fair/examples/edge-xray.md
|
||||
git commit -m "feat(fair-v2): examples Feature_Critic+Edge 真实X光走查；移除 v1 songhui18 示例"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Task 9: README + workflow update + register + acceptance + push
|
||||
|
||||
**Files:**
|
||||
- Modify: `skills/README.md`
|
||||
- Modify: `skills/gitlink-workflow/SKILL.md`
|
||||
|
||||
- [ ] **Step 1: Update README fair row**
|
||||
|
||||
In `skills/README.md`, change the gitlink-research-fair row to:
|
||||
```markdown
|
||||
| **gitlink-research-fair** | 科研软件 X 光 | fair.py 抽论文/数据/复现/引用画像，四维裁决 + 真科研图谱 + 特有关键发现报告，可选处方 PR |
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Update workflow link text**
|
||||
|
||||
In `skills/gitlink-workflow/SKILL.md`, change "科研软件 FAIR 体检" → "科研软件 X 光（fair v2）".
|
||||
|
||||
- [ ] **Step 3: Re-register + acceptance (spec §16)**
|
||||
|
||||
```bash
|
||||
bash scripts/setup-skills.sh # re-link (no-op if already linked)
|
||||
ls ~/.claude/skills/ | grep gitlink-research-fair
|
||||
```
|
||||
Verify spec §16:
|
||||
- [ ] SKILL.md（重写）+ fair.py + test_fair.py + REFERENCE.md（重写）+ 2 examples 齐全
|
||||
- [ ] `python fair.py --owner liyiying10 --repo Feature_Critic` 出合法画像 JSON（arxiv 1901.11448）
|
||||
- [ ] test_fair.py 6 测试全过
|
||||
- [ ] Feature_Critic X 光：论文✅/数据⚠️/复现⚠️/引用❌ + 真图谱 ≥6 节点 + 关键发现 ≥3
|
||||
- [ ] Edge X 光：license 冲突作为发现；与 Feature_Critic 报告明显不同
|
||||
- [ ] 报告落盘 report-cards/
|
||||
- [ ] v1 五轴雷达/假 KG 已从 SKILL.md 移除（grep 0）
|
||||
- [ ] README/workflow 描述更新
|
||||
|
||||
- [ ] **Step 4: Commit + push (updates PR #5)**
|
||||
|
||||
```bash
|
||||
git add skills/README.md skills/gitlink-workflow/SKILL.md
|
||||
git commit -m "docs(fair-v2): README/workflow 更新为「科研软件 X 光」+ 注册"
|
||||
git push myfork feat/gitlink-research-fair
|
||||
```
|
||||
|
|
@ -1,212 +0,0 @@
|
|||
# 文献-代码语义缺口挖掘机 Skill（gitlink-spark）设计
|
||||
|
||||
- **日期**：2026-07-01
|
||||
- **状态**：已批准，待编写实现计划
|
||||
- **作者**：CWQ + Claude
|
||||
- **定位**：子任务四（应用 GitLink 辅助科研）的**第二部分**——与 `gitlink-research-fair`（评估已有）组成"科研辅助双联装"；本 skill 负责"**发现空白**"。
|
||||
- **形态**：skill + **可运行 python 脚本**（非纯 Markdown）；不写 Go。
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
`gitlink-research-fair` 解决"已有科研软件合不合格"。研究者还有个更核心的痛点：**找新的研究点**。他们读大量论文找灵感，却很难发现"**学术界的最新理论**"与"**开源社区的实际落地**"之间有哪些未被填补的空白——而这往往是低成本发论文/出成果的黄金地带。
|
||||
|
||||
本 skill 填补该缺口：给一个研究领域，跨 **arXiv（学术）× GitLink（中文生态）× GitHub（全球）** 三源，挖出两类语义缺口，输出**空白学术机会报告**，并可一键 **fork+issue 起跑**。
|
||||
|
||||
**实用性目标**（demo 级，非生产级全场景通用）：在 GNN 领域跑出 **2-3 个漂亮真实例子**供答辩展示；每条缺口带可查实证。
|
||||
|
||||
**创意性目标**：从"paper→code gap"角度启发创新，区别于 Papers With Code（只链接、不挖缺口）/ OpenAlex（只文献）/ GitHub Archive（只存档）。
|
||||
|
||||
## 2. 非目标（YAGNI）
|
||||
|
||||
- **不做生产级全领域通用**——demo 级，GNN 跑通 2-3 例即可，不追求任意领域鲁棒
|
||||
- 不做实时订阅/webhook——按需 agent 调用
|
||||
- 不自动撰写论文/实现代码——只"提议机会 + 起跑 scaffold"
|
||||
- **绝不自动 merge**；起跑（fork+issue）默认预览，`--auto` 跳过预览
|
||||
- 不修改 gitlink-cli 的 Go 代码——skill + python 脚本
|
||||
- 不重复 `gitlink-research-fair`——fair 评估单仓 FAIR，spark 跨仓跨源挖缺口
|
||||
|
||||
## 3. 关键决策（用户确认）
|
||||
|
||||
| 决策点 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| v1 缺口类型 | **两种都做**（有理论无实现 + 有需求无解答） | 完整愿景；demo 级 2-3 例即可 |
|
||||
| 验证领域 | **图神经网络 GNN** | 三源最均衡：arXiv 海量、GitLink 少量（缺口真实）、GitHub 海量（对照鲜明） |
|
||||
| GitHub 全球对照 | **硬需求**，做 | 避免"GitLink 0 ≠ 全球空白"误导；含阈值过滤 |
|
||||
| 缺口匹配引擎 | **A. LLM 语义匹配为主** | 脚本抓真实数据，LLM 提缺口假设+附实证三件套；demo 级最轻最灵活 |
|
||||
| 起跑动作 | fork 最近基准 + issue 粘伪代码 todo | 对称 fair 处方 PR；强 demo 闭环 |
|
||||
| 交付方式 | 与 fair 同 PR #5（子任务四双联装） | 统一叙事 |
|
||||
|
||||
## 4. 数据源与可行性（实测 2026-07-01）
|
||||
|
||||
| 数据源 | 状态 | 用途 | 备注 |
|
||||
|--------|------|------|------|
|
||||
| arXiv API（HTTPS） | ✅ HTTP 200，返回论文条目 | ① 学术采：领域近 N 天论文 | 必须 HTTPS（HTTP 被沙箱阻断） |
|
||||
| `gitlink-cli search +repos` | ✅ | ② GitLink 仓库 | 用 identifier/关键词 |
|
||||
| `gitlink-cli issue +list`（逐仓库） | ✅ | ② GitLink open issue | 绕开 `search +issues`（返回 HTML 的坑） |
|
||||
| GitHub Search API | ✅ HTTP 200（total_count + items） | ③ 全球对照 | 未认证 10 req/min；用 `GITHUB_TOKEN` 提至 5000/h |
|
||||
| OpenAlex | ⚠ 间歇 503 | 引用计数（可选富集） | best-effort，降级跳过 |
|
||||
|
||||
## 5. 文件清单
|
||||
|
||||
| 文件 | 动作 | 内容 |
|
||||
|------|------|------|
|
||||
| `skills/gitlink-spark/SKILL.md` | 新增 | 4 阶段管道编排、缺口分类法、报告模板、GitHub 阈值规则、起跑护栏、错误降级、命令接口 |
|
||||
| `skills/gitlink-spark/scripts/spark.py` | 新增 | **可独立运行的数据融合脚本**：arXiv + gitlink-cli + GitHub API → 输出 JSON 给 LLM；含缓存与限流 |
|
||||
| `skills/gitlink-spark/REFERENCE.md` | 新增 | 缺口分类法细则、GitHub 阈值与分级、LLM prompt 模板、数据源实测结论、诚实边界 |
|
||||
| `skills/gitlink-spark/examples/spark-图神经网络.md` | 新增 | GNN 真实跑出的 2-3 缺口卡（含起跑截图） |
|
||||
| `skills/README.md` | 修改 | 智能技能表加 gitlink-spark |
|
||||
| `skills/gitlink-workflow/SKILL.md` | 修改（可选） | 专项 skill 链表加 gitlink-spark |
|
||||
|
||||
## 6. 命令接口
|
||||
|
||||
### spark.py（独立可运行）
|
||||
```bash
|
||||
python skills/gitlink-spark/scripts/spark.py \
|
||||
--field "图神经网络" \
|
||||
[--max-papers 10] \
|
||||
[--gap-type both|theory|demand] \
|
||||
[--github-token $GITHUB_TOKEN] # 可选，未设则按 10/min 限流
|
||||
# → stdout 输出融合 JSON：{papers, gitlink_repos, gitlink_issues, github_counts}
|
||||
```
|
||||
|
||||
### skill 约定参数（SKILL.md，非 CLI flag）
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--field` | 必填 | 研究领域（如 `图神经网络`、`federated learning`） |
|
||||
| `--gap-type` | `both` | `theory` / `demand` / `both` |
|
||||
| `--max-papers` | 10 | arXiv 抓取论文上限（控制 GitHub 调用） |
|
||||
| `--auto` | 关 | 跳过预览直接起跑（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出报告，不起跑 |
|
||||
|
||||
## 7. 数据流（4 阶段管道）
|
||||
|
||||
```
|
||||
① 学术采 spark.py: arXiv HTTPS 抓领域近 90 天论文（标题/摘要/arxiv id/方法关键词）
|
||||
② GitLink spark.py: gitlink-cli search +repos 抓领域仓库；
|
||||
对每个仓库 issue +list 抓 open issue（绕开 search+issues HTML）
|
||||
③ 全球对照 spark.py: GitHub Search API 对每个论文方法查 total_count + Top3 仓库
|
||||
④ 缺口匹配（LLM，SKILL.md 编排）
|
||||
读 spark.py 输出的 JSON → 语义匹配两类缺口 → 每张带实证三件套 → 渲染机会报告
|
||||
⑤ 起跑（可选） 选定缺口 → repo +fork 基准 → issue +create 粘论文伪代码 todo
|
||||
```
|
||||
|
||||
**职责切分**：`spark.py` 只抓**真实数据**（确定性、可复现）；**缺口发现**交给 LLM（语义判断），但必须附实证，受置信度门控。
|
||||
|
||||
spark.py 输出 JSON schema：
|
||||
```json
|
||||
{
|
||||
"field": "图神经网络",
|
||||
"papers": [{"arxiv_id":"2403.xxxxx","title":"...","abstract":"...","published":"2024-03-15","method_keywords":[...]}],
|
||||
"gitlink_repos": [{"owner":"leejt","repo":"GraphGallery","desc":"...","topics":[...]}],
|
||||
"gitlink_issues": [{"repo":"leejt/GraphGallery","number":12,"subject":"...","status":"open","participants":3}],
|
||||
"github_counts": [{"method":"graph attention XXX","total_count":2,"top":[{"full_name":"...","stars":3534}]}]
|
||||
}
|
||||
```
|
||||
|
||||
## 8. 两类缺口分类法 + 实证三件套
|
||||
|
||||
每张缺口卡**必须**带齐三件套，否则被置信度门控丢弃（防 LLM 编造）：
|
||||
|
||||
### 类型 A：有理论无实现（paper → code gap）
|
||||
- **三件套**：① 论文 arxiv id + 标题 + 发表日期 ② GitLink 搜索查询串 + 命中数（0 或极少） ③ GitHub total_count + Top 仓库（参考基准）
|
||||
- **判定**：论文提出方法 M；GitLink 实现 0/极少；GitHub 按下面阈值分级。
|
||||
|
||||
### 类型 B：有需求无解答（open issue → applied research gap）
|
||||
- **三件套**：① issue URL + 主题 + 讨论人数/状态 ② GitLink 无现成实现解此痛点 ③ GitHub 是否有成熟开源解（对照）
|
||||
- **判定**：领域仓库中存在"研究性痛点"open issue（排除"安装报错"类使用问题）；学术/GitHub 无现成解。
|
||||
- **降噪**：LLM 筛"研究性痛点"（含性能/可扩展性/新场景），排除使用/部署类。
|
||||
|
||||
## 9. GitHub 全球对照与阈值（诚实核心，硬需求落地）
|
||||
|
||||
防止"GitLink 0 ≠ 全球空白"误导。对每个"理论无实现"候选，按 GitHub total_count 分级：
|
||||
|
||||
| GitHub total_count | 分级 | 报告行为 |
|
||||
|--------------------|------|----------|
|
||||
| `< 10` | **全球稀缺（真空白）** | 报为高价值缺口："GitLink 生态空白 × 全球稀缺 → 复现并开源到 GitLink，易成本平台标杆" |
|
||||
| `10–50` | **新兴（部分空白）** | 报为中等缺口："GitLink 空白，全球新兴（N 个），可做中文生态首个完整实现" |
|
||||
| `≥ 50` | **全球已成熟** | **不报为空白**，列入"✅ 已诚实排除"区："GitLink 虽 0，但 GitHub 已 N 个（含官方）→ 全球已成熟，非空白" |
|
||||
|
||||
> 这个分级是本 skill 的诚实命门：宁可少报，不误报机会。GitHub 计数缓存（spark.py 按 method key 缓存去重）。
|
||||
|
||||
## 10. 机会报告格式（hero）
|
||||
|
||||
````markdown
|
||||
⚡ **gitlink-spark 机会报告：<field>**
|
||||
|
||||
学术采：arXiv 近 90 天 N 篇 ｜ GitLink 仓库 M 个 ｜ GitHub 全球基线已对照
|
||||
生成时间：YYYY-MM-DD
|
||||
|
||||
### 🧩 缺口 1 · 有理论无实现 [全球稀缺·高价值]
|
||||
**论文**：[arxiv:<id>] "<title>" (<venue/date>)
|
||||
**方法关键词**：<...>
|
||||
**GitLink**：search "<query>" → **0 命中**（查询串留底可复现）
|
||||
**GitHub 全球**：total_count = **2**（Top: <repo> <stars>⭐）→ 全球稀缺
|
||||
**机会建议**：<LLM 一句话：为何值得复现 + 开源到 GitLink>
|
||||
**起跑**：[按钮] fork 基准 <repo> → 创建 issue 粘论文 Algorithm 1 伪代码
|
||||
|
||||
### 🧩 缺口 2 · 有需求无解答 [应用机会]
|
||||
**Issue**：<repo>#<n> "<subject>"（N 人讨论, open, <date>）
|
||||
**痛点**：<LLM 一句话研究性痛点归纳>
|
||||
**GitLink / GitHub**：均无成熟开源解
|
||||
**机会建议**：<LLM 一句话：可写应用级论文 + GitLink 落地>
|
||||
|
||||
### ✅ 已诚实排除（非空白）
|
||||
- 论文 Y：GitLink 虽 0，但 GitHub 已 47 个实现（含官方）→ 全球已成熟，不报
|
||||
|
||||
---
|
||||
<!-- gitlink-spark v1 | field:<field> | gaps:<N> | date:<YYYY-MM-DD> -->
|
||||
*由 gitlink-spark skill 生成。*
|
||||
````
|
||||
|
||||
## 11. 起跑动作（M5）+ 安全护栏
|
||||
|
||||
选定一张"理论无实现"缺口卡 → 用户确认 →
|
||||
1. `gitlink-cli repo +fork` 最近基准（GitHub Top 仓库 或 GitLink 最近实现）
|
||||
2. LLM 从 arXiv 论文抓取 Algorithm/Pseudocode 节
|
||||
3. `gitlink-cli issue +create` 在 fork 上建一个复现 todo issue，body 粘入论文伪代码 + 报告卡摘要
|
||||
|
||||
**护栏**（沿用既有偏好）：默认预览确认；`--auto` 跳过预览但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 只出报告。
|
||||
|
||||
## 12. 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| arXiv 返回空/超时 | 改 HTTPS 重试；仍空则报告"学术采失败"，降级用既有论文 |
|
||||
| `search +issues` 返回 HTML（已知坑） | 不用它；用 `issue +list` 逐仓库枚举 |
|
||||
| GitHub 未认证限流（10/min） | spark.py sleep ~7s 限速；建议设 `GITHUB_TOKEN` |
|
||||
| GitHub total_count 查询失败 | 该论文标注"GitHub 对照失败"，不进缺口判定 |
|
||||
| OpenAlex 503 | 跳过引用富集，不影响主报告 |
|
||||
| LLM 缺口无实证三件套 | 置信度门控丢弃 |
|
||||
| fork/issue 起跑失败 | 输出 fork 目标 + 伪代码文本供手动起跑 |
|
||||
| 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或 `go build` |
|
||||
|
||||
## 13. 验证计划（demo 2-3 例，GNN 领域）
|
||||
|
||||
实跑 `spark.py --field "图神经网络"` + LLM 匹配，产出：
|
||||
- [ ] **≥1 张"理论无实现"缺口卡**（GitHub total_count < 10，全球稀缺），三件套可查
|
||||
- [ ] **≥1 张"需求无解答"缺口卡**（真实 open issue + 研究性痛点），三件套可查
|
||||
- [ ] **≥1 张"理论无实现"缺口卡走完 fork+issue 起跑**（截图/链接；demand 卡为写论文方向、无 fork 起跑）
|
||||
- [ ] "✅ 已诚实排除"区至少 1 条（GitHub ≥50 的非空白），证明阈值生效
|
||||
- [ ] 全报告无 LLM 编造（每条可溯源到 spark.py JSON）
|
||||
|
||||
结果写入 `examples/spark-图神经网络.md`。
|
||||
|
||||
## 14. 风险与未决
|
||||
|
||||
- **arXiv 方法抽取**：从论文摘要自动抽"方法关键词"供 GitHub 查询，LLM 抽取有噪声 → spark.py 同时用论文标题关键词 + LLM 抽取双路查询 GitHub，取 total_count。
|
||||
- **GitLink GNN 仓库数量**：可能很少（之前扫到 GraphGallery 等）；需求侧缺口（issue）依赖仓库数，若太少则 demand 缺口样本不足 → 必要时放宽领域关键词（如含 `图`/`GNN`/`graph neural`）。
|
||||
- **GitHub 限流**：demo 一次 10 篇论文 × 1 查询 = 10 次，刚好未认证上限；建议跑 demo 时设 `GITHUB_TOKEN`。
|
||||
- **缺口"机会建议"主观**：靠实证三件套兜底；建议标注"机会仅为启发，需研究者自行判断"。
|
||||
|
||||
## 15. 验收标准
|
||||
|
||||
1. `skills/gitlink-spark/` 四件套齐全（SKILL.md + scripts/spark.py + REFERENCE.md + examples/）
|
||||
2. `spark.py` 可独立运行：`python spark.py --field 图神经网络` 输出合法融合 JSON
|
||||
3. GNN 跑出 2-3 张真实缺口卡（≥1 theory + ≥1 demand），每张三件套可查
|
||||
4. GitHub 阈值生效："已诚实排除"区至少 1 条
|
||||
5. ≥1 张缺口卡走完 fork+issue 起跑，有截图/链接
|
||||
6. 全报告每条缺口可溯源到 spark.py JSON（无 LLM 编造）
|
||||
7. REFERENCE.md 含缺口分类法 + 数据源实测结论 + 诚实边界
|
||||
8. README 登记 gitlink-spark
|
||||
|
|
@ -1,234 +0,0 @@
|
|||
# gitlink-research-fair v2 设计（科研软件 X 光 / Research Software X-Ray）
|
||||
|
||||
- **日期**：2026-07-07
|
||||
- **状态**：已批准，待编写实现计划
|
||||
- **作者**：CWQ + Claude
|
||||
- **定位**：对 v1（5 轴 FAIR 体检卡）的**重大升级**，回应"与 health 重合 / 报告千篇一律 / 假科研图谱 / 纯 Markdown 无脚本"四条批评。同一 skill 演进（保留 fair 名 + FAIR4RS 学术锚 + PR #5），重构内部。
|
||||
- **形态**：skill + **可运行 `scripts/fair.py`**（stdlib only），内容感知的科研分析工作流。
|
||||
|
||||
---
|
||||
|
||||
## 1. 背景与目标
|
||||
|
||||
v1 的 fair 是"5 轴 FAIR 打分 + 报告卡"，存在四个真问题：
|
||||
1. 与 `gitlink-health` 形态重合（都是"聚合 gitlink-cli → AI → 打分报告"），且不够科研专属。
|
||||
2. 报告千篇一律（每仓库都是同一组 ✓/✗）；五轴 ASCII 雷达呈现烂；"科研关系图"是假的（只画作者/license/dataset?）。
|
||||
3. 纯 Markdown，无脚本，分析靠 LLM"看一眼"，不可复现。
|
||||
4. 缺真实科研洞察。
|
||||
|
||||
v2 升级为**科研软件 X 光**：`fair.py` **真抽取** repo 内容（README/文件/依赖）→ 科研画像 JSON → LLM 对 4 个科研专属维度做裁决（每条带实证）→ **每 repo 特有的洞察报告**（裁决总览 + 真科研图谱 + 关键发现）+ 可选处方闭环。
|
||||
|
||||
**目标**：内容感知（每份报告说本 repo 特有的东西）、科研专属（论文/数据/复现/引用，非通用软件质量）、可执行（fair.py 脚本）、demo 级（1-2 示例 + 1 答辩演示，非全场景覆盖）。
|
||||
|
||||
## 2. 非目标（YAGNI）
|
||||
|
||||
- 不做"实际运行代码验证复现"（静态复现就绪度检查即可，跑代码超 demo 范围）
|
||||
- 不做全场景/全领域覆盖——Feature_Critic + Edge 两个场景跑通即可
|
||||
- 不重复 spark（spark 跨仓跨源挖缺口；fair v2 单仓深挖科研产物）
|
||||
- 不自动 merge；处方默认预览
|
||||
- 不写 Go——skill + python 脚本
|
||||
- **砍掉 v1 的**：5 轴雷达、假 KG、OpenAlex 溯源（弱环节）、与 health 重合的通用质量味
|
||||
|
||||
## 3. 关键决策（用户确认）
|
||||
|
||||
| 决策点 | 选择 | 理由 |
|
||||
|--------|------|------|
|
||||
| 主角定位 | **科研软件 X 光**（深挖科研产物 + 4 维裁决） | 替代 5 轴打分，科研专属，每 repo 特有 |
|
||||
| 报告主视觉 | **混合**（裁决一行 + 真 Mermaid 图谱 + 关键发现） | 扫读 + 视觉兼顾，回应雷达烂 + 假图谱 + 千篇一律三连批 |
|
||||
| 改造方式 | **演进式**（保留 fair 名/FAIR4RS 锚/PR #5） | 不浪费 v1 资产，重构内部 |
|
||||
| 演示仓库 | **liyiying10/Feature_Critic**（ICML2019 paper-code） | README 明含 arxiv 链接，X 光论文溯源能真抽，4 维有区分度 |
|
||||
| 第二示例 | **Edgedev/Edge-Computing-Engine**（引擎类） | 与 Feature_Critic 不同 profile（license 冲突发现），证明不千篇一律 |
|
||||
| 脚本 | **fair.py**（stdlib only，fair.py 抽数据 + LLM 裁决） | 内容感知、可复现，取代 LLM"看一眼" |
|
||||
|
||||
## 4. 与 v1 的差异 + 取舍
|
||||
|
||||
| 维度 | v1 | v2 |
|
||||
|------|----|----|
|
||||
| 评分对象 | 5 轴 FAIR（F/A/I/R/Repro）通用软件质量 | 4 维科研专属（论文溯源/数据链/复现就绪/引用就绪） |
|
||||
| 数据来源 | LLM 看 gitlink-cli 元数据 | fair.py 真抽取 README/文件/依赖 |
|
||||
| 图谱 | 假 KG（作者/license/dataset?） | 真 Mermaid：paper↔method↔code↔dataset↔framework↔citation |
|
||||
| 报告 | 千篇一律 ✓/✗ + ASCII 雷达 | 裁决一行 + 真图谱 + **本 repo 特有关键发现** |
|
||||
| 脚本 | 无（纯 Markdown） | fair.py（可独立运行） |
|
||||
| 处方 | 有（保留） | 保留升级（CITATION.cff 从 README 抽 / requirements 从 import 扫） |
|
||||
| OpenAlex 溯源 | 有（弱、易 503） | **砍**（去掉更自洽） |
|
||||
| 落盘 | 有（v1 已补） | 保留（report-cards/<owner>-<repo>-xray.md） |
|
||||
|
||||
## 5. 文件清单
|
||||
|
||||
| 文件 | 动作 | 内容 |
|
||||
|------|------|------|
|
||||
| `skills/gitlink-research-fair/SKILL.md` | 重写 | X 光管道（抽数→裁决→图谱→报告→处方）、4 维裁决表、报告模板、真图谱说明、处方护栏、降级 |
|
||||
| `skills/gitlink-research-fair/scripts/fair.py` | 新增 | 真抽取（README/文件/依赖）→ 科研画像 JSON；stdlib only |
|
||||
| `skills/gitlink-research-fair/scripts/test_fair.py` | 新增 | 抽取函数单测（arxiv 正则 / 依赖检测 / 数据集识别 / 引用检测） |
|
||||
| `skills/gitlink-research-fair/REFERENCE.md` | 重写 | 4 维裁决细则 + 真 KG schema + 抽取规则 + 数据源实测 + 学术锚（FAIR4RS） |
|
||||
| `skills/gitlink-research-fair/examples/feature-critic-xray.md` | 新增 | Feature_Critic 真实 X 光走查（答辩演示脚本） |
|
||||
| `skills/gitlink-research-fair/examples/edge-xray.md` | 新增 | Edge 引擎类对照（license 冲突发现） |
|
||||
| `skills/README.md` / `skills/gitlink-workflow/SKILL.md` | 微调 | fair 描述改为"科研软件 X 光" |
|
||||
|
||||
> v1 的旧 examples（songhui18 报告卡）替换为 v2 X 光示例。
|
||||
|
||||
## 6. 命令接口
|
||||
|
||||
### fair.py（可独立运行）
|
||||
```bash
|
||||
python skills/gitlink-research-fair/scripts/fair.py --owner liyiying10 --repo Feature_Critic
|
||||
# → stdout: 科研画像 JSON {paper, datasets, repro, citation, methods, frameworks, license, files, head_sha}
|
||||
```
|
||||
|
||||
### skill 约定参数（SKILL.md）
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库（用 identifier） |
|
||||
| `--auto` | 关 | 跳过预览直接开处方 PR（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出 X 光报告，不开 PR |
|
||||
| `--refresh` | 关 | 即使有旧哨兵也重评 |
|
||||
|
||||
## 7. 数据流（管道）
|
||||
|
||||
```
|
||||
① 抽取（fair.py，确定性）
|
||||
fetch readme (file +get) + file list (file +list) + repo +info + commit +list(HEAD sha)
|
||||
→ extract_paper / extract_datasets / assess_repro / assess_citation / extract_methods_frameworks
|
||||
→ 科研画像 JSON
|
||||
② 裁决（LLM，读 JSON）4 维 × (✅/⚠️/❌ + 具体证据)
|
||||
③ 真科研图谱（从画像生成 Mermaid）
|
||||
④ 渲染 X 光报告（hero：裁决一行 + 真图谱 + 关键发现 + 处方摘要 + 双裁决证书）→ 落盘
|
||||
⑤ 处方（可选）：fork → 建 CITATION.cff/requirements/Dockerfile → PR（默认预览）
|
||||
```
|
||||
|
||||
**职责切分**：fair.py 只做**确定性抽取**（可复现）；**裁决与"关键发现"叙述**交给 LLM（语义），但每条必须引用 fair.py 抽到的实证。
|
||||
|
||||
## 8. fair.py 抽取目标 + 科研画像 JSON schema
|
||||
|
||||
抽取函数（纯函数单测 + gitlink-cli 网络层）：
|
||||
- `extract_paper(readme)` → 正则抽 arxiv id/URL、DOI、OpenReview/aclanthology、标题/作者/会议、"Code for the paper" 句式
|
||||
- `extract_datasets(readme, files)` → 已知数据集名（PACS/Cora/ImageNet/Visual Decathlon/MNIST/CIFAR…）+ 数据脚本（data_gen/get_data/download.sh）+ 数据 license/DOI
|
||||
- `assess_repro(files, readme)` → 依赖文件（requirements/go.mod/environment.yml/Dockerfile）+ 锁版本？；入口（main/train/run/*.py）；期望结果（results.md/accuracy/表）；环境说明
|
||||
- `assess_citation(files, readme)` → CITATION.cff / codemeta.json / .zenodo.json 存在？+ README BibTeX/引用文本
|
||||
- `extract_methods_frameworks(files, readme)` → 方法词 + 框架（torch/tensorflow/jax，从 import/文件名推断）
|
||||
|
||||
科研画像 JSON：
|
||||
```json
|
||||
{
|
||||
"repo": "liyiying10/Feature_Critic", "head_sha": "<sha>",
|
||||
"paper": {"arxiv_id":"1901.11448","arxiv_url":"https://arxiv.org/abs/1901.11448","doi":null,
|
||||
"title":"Feature-Critic Networks for Heterogeneous Domain Generalisation",
|
||||
"authors":["Yiying Li","Yongxin Yang","Wei Zhou","Timothy M. Hospedales"],"venue":"ICML 2019","in_readme":true},
|
||||
"datasets": [{"name":"PACS","evidence":"data_gen_PACS.py + README","download_script":"get_model_dataset.sh","license":null},
|
||||
{"name":"Visual Decathlon","evidence":"data_gen_VD.py","download_script":null,"license":null}],
|
||||
"repro": {"deps_files":[],"deps_pinned":false,"entry_points":["main_Feature_Critic.py","main_baseline.py"],
|
||||
"expected_results":false,"env_spec":null},
|
||||
"citation": {"cff":false,"codemeta":false,"zenodo":false,
|
||||
"readme_bibtex":"Li, Yang, Zhou, Hospedales. Feature-Critic Networks... ICML 2019"},
|
||||
"methods": ["feature-critic","meta-learning","domain generalisation"],
|
||||
"frameworks": ["torch (inferred: alexnet/resnet/vggnet)"],
|
||||
"license": {"file":false,"type":null,"conflict":null},
|
||||
"files_count": 15
|
||||
}
|
||||
```
|
||||
|
||||
## 9. 4 维裁决规则（LLM 读画像，每维 ✅/⚠️/❌ + 证据）
|
||||
|
||||
| 维度 | ✅ | ⚠️ | ❌ |
|
||||
|------|---|----|----|
|
||||
| 论文溯源 | 有 arxiv/DOI + 元数据全 | 仅 README 文字提及，无稳定链接 | 无任何论文线索 |
|
||||
| 数据链 | 数据集命名 + 下载脚本 + license | 命名但无脚本/无 license | 未提及数据集 |
|
||||
| 复现就绪 | 依赖锁 + 入口 + 环境 + 期望结果四件齐全 | 有入口但缺依赖锁/环境/期望结果 | 无入口/无依赖 |
|
||||
| 引用就绪 | CITATION.cff/codemeta + DOI + 版本 | 仅 README 引用文本 | 无任何引用信息 |
|
||||
|
||||
每维裁决**必须引用画像里的具体字段**（如"arxiv 1901.11448 已抽""requirements.txt 缺失"），无实证的判断丢弃。
|
||||
|
||||
## 10. 真科研图谱 schema（Mermaid，从画像生成）
|
||||
|
||||
节点（带状态色）：`Paper(arxiv+venue)` / `Method` / `Code(file)` / `Dataset` / `Framework` / `Citation`
|
||||
边：`Paper —proposes→ Method`、`Method —implements→ Code`、`Code —uses→ Dataset`、`Code —depends→ Framework`、`Paper —cited-via→ Citation`
|
||||
状态色：✅绿 / ⚠️黄 / ❌红（缺失项）。
|
||||
|
||||
Feature_Critic 实例化：`ICML2019(1901.11448)✅ —proposes→ Feature-Critic方法 —implements→ main_Feature_Critic.py✅ —uses→ PACS⚠️/Visual Decathlon⚠️ —depends→ PyTorch(推断)⚠️；Paper —cited-via→ 无CITATION❌`。真有科研含义，非 v1 假图。
|
||||
|
||||
## 11. 报告格式（混合主视觉，hero）
|
||||
|
||||
````markdown
|
||||
🔬 **科研软件 X 光 — liyiying10/Feature_Critic**
|
||||
|
||||
═══════════════════════════════════════
|
||||
论文溯源 ✅ ｜ 数据链 ⚠️ ｜ 复现就绪 ⚠️ ｜ 引用就绪 ❌
|
||||
═══════════════════════════════════════
|
||||
|
||||
### 🧬 真科研图谱
|
||||
```mermaid
|
||||
graph LR
|
||||
P[ICML2019 arxiv:1901.11448]:::ok -->|proposes| M[Feature-Critic 方法]
|
||||
M -->|implements| C[main_Feature_Critic.py]:::ok
|
||||
C -->|uses| D1[PACS]:::warn
|
||||
C -->|uses| D2[Visual Decathlon]:::warn
|
||||
C -->|depends| F[PyTorch 推断]:::warn
|
||||
P -->|cited-via| Ci[无 CITATION.cff]:::bad
|
||||
classDef ok fill:#cfe,stroke:#3a3; classDef warn fill:#ffe,stroke:#cc3; classDef bad fill:#fee,stroke:#c33;
|
||||
```
|
||||
|
||||
### 🔍 关键发现（本 repo 特有）
|
||||
- 论文 ICML2019 arxiv:1901.11448 已溯源 ✓，但**无 CITATION.cff** → 机器不可引用
|
||||
- 数据集 PACS/Visual Decathlon 命名 + `get_model_dataset.sh`，但**无数据 license**
|
||||
- 入口 `main_Feature_Critic.py` 在，但**无 requirements.txt** → 依赖未锁，复现风险
|
||||
- 框架：alexnet/resnet/vggnet（疑似 PyTorch，**依赖未声明**）
|
||||
|
||||
### 🔧 处方（可选）
|
||||
补 `CITATION.cff`（从 README 抽的引用）+ `requirements.txt`（从 import 扫）+ `Dockerfile`
|
||||
|
||||
### 📜 双裁决证书
|
||||
复现就绪 ⚠️ 部分 ｜ 引用就绪 ❌ ｜ 锚定 commit `<sha>`
|
||||
|
||||
---
|
||||
<!-- gitlink-research-fair v2 | repo:<owner>/<repo> | paper:? | repro:? | cite:? | sha:<head> -->
|
||||
*由 gitlink-research-fair v2（科研软件 X 光）生成。*
|
||||
````
|
||||
|
||||
报告**始终落盘** `report-cards/<owner>-<repo>-xray.md`（沿用 v1 落盘原则）。
|
||||
|
||||
## 12. 处方闭环 + 护栏（保留 v1 升级）
|
||||
|
||||
对 ❌/⚠️ 项生成修复：`CITATION.cff`（从 README 抽的引用文本构造）+ `requirements.txt`（从代码 import 扫出依赖）+ `Dockerfile`（模板）。→ fork → PR（默认预览，`--auto` 跳过；永不 force-push/碰原仓库/自动 merge；`--no-fork` 报告已落盘）。
|
||||
|
||||
## 13. 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| README 读取失败 | 降级用 file list + 元数据，标注"README 不可读，结论受限" |
|
||||
| `file +list` data 为字符串 | json.loads 解套（已知结构） |
|
||||
| arxiv/DOI 抽不到 | 论文溯源维度判 ⚠️ 或 ❌，据实 |
|
||||
| 框架无法推断 | frameworks 标 "未知"，不编造 |
|
||||
| `--repo` 用了中文显示名 404 | 提示用 identifier（从 search 取） |
|
||||
| fork/PR 失败 | 处方物料落本地，告知路径 |
|
||||
| 报告/PR 发布失败 | 报告已在 ④ 落盘，告知路径 |
|
||||
|
||||
## 14. 验证计划（1-2 示例 + 答辩演示）
|
||||
|
||||
- **答辩现场演示 + 示例1**：`liyiying10/Feature_Critic`
|
||||
- [ ] fair.py 抽出 arxiv 1901.11448 + ICML2019 + PACS/VD 数据集 + 入口 + 无 CITATION/requirements
|
||||
- [ ] 4 维裁决：论文 ✅ / 数据 ⚠️ / 复现 ⚠️ / 引用 ❌
|
||||
- [ ] 真图谱画出 6 类节点 + 状态色
|
||||
- [ ] 关键发现 ≥3 条本 repo 特有
|
||||
- **示例2**：`Edgedev/Edge-Computing-Engine`
|
||||
- [ ] X 光发现 license 冲突（Apache vs README"禁商用"）作为关键发现
|
||||
- [ ] 与 Feature_Critic 报告内容明显不同（证明不千篇一律）
|
||||
- 两示例均落盘 report-cards/ + 写入 examples/。
|
||||
|
||||
## 15. 风险与未决
|
||||
|
||||
- **README 抽取覆盖度**：正则抽 arxiv/DOI 依赖 README 写法；对非标准 README 可能漏。fair.py 同时匹配多种句式（arxiv URL / arXiv:id / 裸 id）兜底。
|
||||
- **框架推断**：从文件名/import 推断 PyTorch/TF 有噪声 → 标"推断"，不肯定。
|
||||
- **数据集识别**：已知数据集名白名单有限；未知名标"unnamed dataset (mentioned)"。
|
||||
- **GitLink file +list data 字符串化**：fair.py 需 json.loads 解套（已知）。
|
||||
- **演示仓库稳定性**：Feature_Critic 是 1⭐ 小仓但 ICML2019 真实学术代码，内容稳定；演示前复跑一次确认 README/文件未变。
|
||||
|
||||
## 16. 验收标准
|
||||
|
||||
1. `skills/gitlink-research-fair/` 含 SKILL.md（重写）+ scripts/fair.py + test_fair.py + REFERENCE.md（重写）+ 2 个 examples
|
||||
2. `python fair.py --owner liyiying10 --repo Feature_Critic` 输出合法科研画像 JSON（含真实 arxiv 1901.11448）
|
||||
3. test_fair.py 抽取函数单测全过
|
||||
4. Feature_Critic X 光：4 维裁决正确（论文✅/数据⚠️/复现⚠️/引用❌）+ 真图谱 ≥6 节点 + 关键发现 ≥3 条
|
||||
5. Edge X 光：license 冲突作为关键发现，报告与 Feature_Critic 明显不同
|
||||
6. 报告落盘 report-cards/
|
||||
7. v1 的 5 轴雷达/假 KG 已从 SKILL.md 移除
|
||||
8. README/workflow 描述更新为"科研软件 X 光"
|
||||
Binary file not shown.
|
|
@ -0,0 +1 @@
|
|||
PR Test 2026年 4月 7日 星期二 11时45分56秒 CST
|
||||
|
|
@ -19,9 +19,9 @@ PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
|||
SRC="$PROJECT_DIR/skills"
|
||||
DST="$HOME/.claude/skills"
|
||||
|
||||
# --- collect gitlink-* skills (top-level skills/ + workflow-bundled skills) ---
|
||||
# --- collect gitlink-* skills ---
|
||||
shopt -s nullglob
|
||||
SKILLS=("$SRC"/gitlink-*/ "$PROJECT_DIR/shortcuts/workflow/skills"/gitlink-*/)
|
||||
SKILLS=("$SRC"/gitlink-*/)
|
||||
shopt -u nullglob
|
||||
if [ ${#SKILLS[@]} -eq 0 ]; then
|
||||
echo "No gitlink-* skills found under $SRC" >&2
|
||||
|
|
|
|||
|
|
@ -280,9 +280,9 @@ func assignIssue(ctx *common.RuntimeContext, number, user string) error {
|
|||
}
|
||||
|
||||
body := map[string]interface{}{
|
||||
"subject": current.Subject,
|
||||
"description": current.Description,
|
||||
"assigner_ids": []int64{int64(userID)},
|
||||
"subject": current.Subject,
|
||||
"description": current.Description,
|
||||
"assigned_to_id": userID,
|
||||
}
|
||||
if current.StatusID != nil {
|
||||
body["status_id"] = current.StatusID
|
||||
|
|
|
|||
|
|
@ -258,9 +258,9 @@ func Shortcuts() []*common.Shortcut {
|
|||
return fmt.Errorf("user 参数必须是数字 ID，而不是用户名")
|
||||
}
|
||||
body := map[string]interface{}{
|
||||
"subject": current.Subject,
|
||||
"description": current.Description,
|
||||
"assigner_ids": []int64{int64(userID)},
|
||||
"subject": current.Subject,
|
||||
"description": current.Description,
|
||||
"assigned_to_id": userID,
|
||||
}
|
||||
if current.StatusID != nil {
|
||||
body["status_id"] = current.StatusID
|
||||
|
|
|
|||
|
|
@ -281,17 +281,16 @@ func TestIssueComment(t *testing.T) {
|
|||
}
|
||||
|
||||
func TestIssueAssignSendsCorrectUser(t *testing.T) {
|
||||
var assignPath string
|
||||
var assignPayload map[string]interface{}
|
||||
server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
switch {
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/issues/42.json":
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"subject": "Existing title",
|
||||
"description": "Existing description",
|
||||
})
|
||||
case r.Method == "PATCH" && r.URL.Path == "/v1/owner/repo/issues/42.json":
|
||||
case r.Method == "PUT" && r.URL.Path == "/v1/owner/repo/issues/42/assignees.json":
|
||||
assignPath = r.URL.Path
|
||||
assignPayload = decodeJSON(t, r)
|
||||
writeJSON(t, w, map[string]interface{}{"message": "指派成功"})
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"message": "指派成功",
|
||||
})
|
||||
default:
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
|
|
@ -300,18 +299,16 @@ func TestIssueAssignSendsCorrectUser(t *testing.T) {
|
|||
|
||||
err := runIssueShortcut(t, server, "assign", map[string]string{
|
||||
"number": "42",
|
||||
"user": "42",
|
||||
"user": "zhangsan",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("assign shortcut failed: %v", err)
|
||||
}
|
||||
|
||||
// GitLink 责任人字段是 assigner_ids（数组），不是 assigned_to_id
|
||||
got, ok := assignPayload["assigner_ids"].([]interface{})
|
||||
if !ok || len(got) != 1 {
|
||||
t.Fatalf("expected assigner_ids [42], got %#v", assignPayload["assigner_ids"])
|
||||
if assignPath == "" {
|
||||
t.Fatal("assign endpoint was not called")
|
||||
}
|
||||
assertEqual(t, got[0], float64(42))
|
||||
assertEqual(t, assignPayload["assigned_to_id"], "zhangsan")
|
||||
}
|
||||
|
||||
func TestIssueAssignRequiresNumberAndUser(t *testing.T) {
|
||||
|
|
@ -389,15 +386,15 @@ func TestIssueLabelRemoveSendsDeleteRequests(t *testing.T) {
|
|||
}
|
||||
|
||||
func TestBatchAssign(t *testing.T) {
|
||||
var assignPath string
|
||||
var assignPayload map[string]interface{}
|
||||
server := newIssueTestServer(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
switch {
|
||||
case r.Method == "GET" && (r.URL.Path == "/v1/owner/repo/issues/1.json" || r.URL.Path == "/v1/owner/repo/issues/2.json"):
|
||||
writeJSON(t, w, map[string]interface{}{"subject": "title", "description": "desc"})
|
||||
case r.Method == "PATCH" && r.URL.Path == "/v1/owner/repo/issues/1.json":
|
||||
case r.Method == "PUT" && r.URL.Path == "/v1/owner/repo/issues/1/assignees.json":
|
||||
assignPath = r.URL.Path
|
||||
assignPayload = decodeJSON(t, r)
|
||||
writeJSON(t, w, map[string]interface{}{"message": "指派成功"})
|
||||
case r.Method == "PATCH" && r.URL.Path == "/v1/owner/repo/issues/2.json":
|
||||
case r.Method == "PUT" && r.URL.Path == "/v1/owner/repo/issues/2/assignees.json":
|
||||
writeJSON(t, w, map[string]interface{}{"message": "指派成功"})
|
||||
default:
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
|
|
@ -407,18 +404,17 @@ func TestBatchAssign(t *testing.T) {
|
|||
|
||||
err := runIssueShortcut(t, server, "batch-assign", map[string]string{
|
||||
"numbers": "1,2",
|
||||
"user": "42",
|
||||
"user": "zhangsan",
|
||||
"dry-run": "false",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("batch-assign failed: %v", err)
|
||||
}
|
||||
|
||||
got, ok := assignPayload["assigner_ids"].([]interface{})
|
||||
if !ok || len(got) != 1 {
|
||||
t.Fatalf("expected assigner_ids [42], got %#v", assignPayload["assigner_ids"])
|
||||
if assignPath == "" {
|
||||
t.Fatal("assign endpoint was not called")
|
||||
}
|
||||
assertEqual(t, got[0], float64(42))
|
||||
assertEqual(t, assignPayload["assigned_to_id"], "zhangsan")
|
||||
}
|
||||
|
||||
func TestBatchAssignDryRun(t *testing.T) {
|
||||
|
|
|
|||
|
|
@ -22,8 +22,7 @@ import (
|
|||
"github.com/gitlink-org/gitlink-cli/shortcuts/watch"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/webhook"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/wiki"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/cli"
|
||||
_ "github.com/gitlink-org/gitlink-cli/shortcuts/workflow/defs"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
_ "github.com/gitlink-org/gitlink-cli/shortcuts/workflow/rules"
|
||||
)
|
||||
|
||||
|
|
@ -48,7 +47,7 @@ func RegisterAll(root *cobra.Command) {
|
|||
"watch": watch.Shortcuts(),
|
||||
"star": star.Shortcuts(),
|
||||
"wiki": wiki.Shortcuts(),
|
||||
"workflow": cli.Shortcuts(),
|
||||
"workflow": workflow.Shortcuts(),
|
||||
}
|
||||
|
||||
descriptions := map[string]string{
|
||||
|
|
|
|||
|
|
@ -58,9 +58,24 @@ func Shortcuts() []*common.Shortcut {
|
|||
}
|
||||
targetDir := ctx.Arg("dir")
|
||||
|
||||
cloneURL, repoName, err := parseCloneTarget(rawURL, ctx.Client.BaseURL)
|
||||
if err != nil {
|
||||
return err
|
||||
var cloneURL string
|
||||
var repoName string
|
||||
|
||||
if strings.HasPrefix(rawURL, "http://") || strings.HasPrefix(rawURL, "https://") {
|
||||
cloneURL = rawURL
|
||||
if !strings.HasSuffix(cloneURL, ".git") {
|
||||
cloneURL += ".git"
|
||||
}
|
||||
parts := strings.Split(strings.TrimSuffix(rawURL, ".git"), "/")
|
||||
repoName = parts[len(parts)-1]
|
||||
} else {
|
||||
parts := strings.SplitN(rawURL, "/", 2)
|
||||
if len(parts) != 2 {
|
||||
return fmt.Errorf("无效的仓库格式 %q: 请使用 owner/repo 格式", rawURL)
|
||||
}
|
||||
webBase := strings.TrimSuffix(strings.TrimSuffix(ctx.Client.BaseURL, "/"), "/api")
|
||||
cloneURL = fmt.Sprintf("%s/%s/%s.git", webBase, parts[0], parts[1])
|
||||
repoName = parts[1]
|
||||
}
|
||||
|
||||
if targetDir == "" {
|
||||
|
|
@ -211,30 +226,3 @@ func Shortcuts() []*common.Shortcut {
|
|||
},
|
||||
}
|
||||
}
|
||||
|
||||
// parseCloneTarget 把用户输入的 --url 解析成可克隆的 cloneURL 和默认目录名 repoName。
|
||||
// 支持两种输入：
|
||||
// - 完整 URL：https://www.gitlink.org.cn/owner/repo[.git]
|
||||
// - 简写格式：owner/repo（会基于 BaseURL 拼成完整 URL）
|
||||
//
|
||||
// 抽成纯函数便于跨平台单元测试（不依赖 git / PATH）。
|
||||
func parseCloneTarget(rawURL, baseURL string) (cloneURL, repoName string, err error) {
|
||||
if strings.HasPrefix(rawURL, "http://") || strings.HasPrefix(rawURL, "https://") {
|
||||
cloneURL = rawURL
|
||||
if !strings.HasSuffix(cloneURL, ".git") {
|
||||
cloneURL += ".git"
|
||||
}
|
||||
parts := strings.Split(strings.TrimSuffix(rawURL, ".git"), "/")
|
||||
repoName = parts[len(parts)-1]
|
||||
return
|
||||
}
|
||||
parts := strings.SplitN(rawURL, "/", 2)
|
||||
if len(parts) != 2 {
|
||||
err = fmt.Errorf("无效的仓库格式 %q: 请使用 owner/repo 格式", rawURL)
|
||||
return
|
||||
}
|
||||
webBase := strings.TrimSuffix(strings.TrimSuffix(baseURL, "/"), "/api")
|
||||
cloneURL = fmt.Sprintf("%s/%s/%s.git", webBase, parts[0], parts[1])
|
||||
repoName = parts[1]
|
||||
return
|
||||
}
|
||||
|
|
|
|||
|
|
@ -5,6 +5,8 @@ import (
|
|||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
|
|
@ -217,38 +219,50 @@ func assertEqual(t *testing.T, got interface{}, want interface{}) {
|
|||
}
|
||||
}
|
||||
|
||||
// clone 测试直接验证 parseCloneTarget 的解析逻辑（纯函数，不依赖 git/PATH，全平台可跑）。
|
||||
const testCloneBaseURL = "https://www.gitlink.org.cn/api"
|
||||
|
||||
func TestRepoCloneParsesOwnerRepoFormat(t *testing.T) {
|
||||
cloneURL, repoName, err := parseCloneTarget("myorg/myrepo", testCloneBaseURL)
|
||||
tmpDir := t.TempDir()
|
||||
fakeGit := createFakeGit(t, tmpDir)
|
||||
|
||||
err := runRepoCloneShortcut(t, fakeGit, map[string]string{
|
||||
"url": "myorg/myrepo",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("parseCloneTarget failed: %v", err)
|
||||
}
|
||||
if cloneURL != "https://www.gitlink.org.cn/myorg/myrepo.git" {
|
||||
t.Errorf("cloneURL = %q, want .../myorg/myrepo.git", cloneURL)
|
||||
}
|
||||
if repoName != "myrepo" {
|
||||
t.Errorf("repoName = %q, want myrepo", repoName)
|
||||
t.Fatalf("clone shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRepoCloneParsesFullURL(t *testing.T) {
|
||||
cloneURL, repoName, err := parseCloneTarget("https://www.gitlink.org.cn/myorg/myrepo", testCloneBaseURL)
|
||||
tmpDir := t.TempDir()
|
||||
fakeGit := createFakeGit(t, tmpDir)
|
||||
|
||||
err := runRepoCloneShortcut(t, fakeGit, map[string]string{
|
||||
"url": "https://www.gitlink.org.cn/myorg/myrepo",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("parseCloneTarget failed: %v", err)
|
||||
t.Fatalf("clone shortcut failed: %v", err)
|
||||
}
|
||||
// 完整 URL 缺 .git 时应自动补上
|
||||
if cloneURL != "https://www.gitlink.org.cn/myorg/myrepo.git" {
|
||||
t.Errorf("cloneURL = %q, want .../myorg/myrepo.git", cloneURL)
|
||||
}
|
||||
if repoName != "myrepo" {
|
||||
t.Errorf("repoName = %q, want myrepo", repoName)
|
||||
}
|
||||
|
||||
func TestRepoCloneCustomTargetDir(t *testing.T) {
|
||||
tmpDir := t.TempDir()
|
||||
fakeGit := createFakeGit(t, tmpDir)
|
||||
|
||||
err := runRepoCloneShortcut(t, fakeGit, map[string]string{
|
||||
"url": "myorg/myrepo",
|
||||
"dir": "/custom/dir",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("clone shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRepoCloneInvalidFormat(t *testing.T) {
|
||||
_, _, err := parseCloneTarget("invalidformat", testCloneBaseURL)
|
||||
tmpDir := t.TempDir()
|
||||
fakeGit := createFakeGit(t, tmpDir)
|
||||
|
||||
err := runRepoCloneShortcut(t, fakeGit, map[string]string{
|
||||
"url": "invalidformat",
|
||||
})
|
||||
if err == nil {
|
||||
t.Fatal("expected error for invalid format, got nil")
|
||||
}
|
||||
|
|
@ -258,17 +272,52 @@ func TestRepoCloneInvalidFormat(t *testing.T) {
|
|||
}
|
||||
|
||||
func TestRepoCloneURLWithGitSuffix(t *testing.T) {
|
||||
cloneURL, repoName, err := parseCloneTarget("https://www.gitlink.org.cn/myorg/myrepo.git", testCloneBaseURL)
|
||||
tmpDir := t.TempDir()
|
||||
fakeGit := createFakeGit(t, tmpDir)
|
||||
|
||||
err := runRepoCloneShortcut(t, fakeGit, map[string]string{
|
||||
"url": "https://www.gitlink.org.cn/myorg/myrepo.git",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("parseCloneTarget failed: %v", err)
|
||||
t.Fatalf("clone shortcut failed: %v", err)
|
||||
}
|
||||
// 已带 .git 时不应重复追加
|
||||
if cloneURL != "https://www.gitlink.org.cn/myorg/myrepo.git" {
|
||||
t.Errorf("cloneURL = %q, want unchanged .../myorg/myrepo.git", cloneURL)
|
||||
}
|
||||
|
||||
func createFakeGit(t *testing.T, dir string) string {
|
||||
t.Helper()
|
||||
fakeGitPath := filepath.Join(dir, "git")
|
||||
script := `#!/bin/bash
|
||||
# Record arguments for test verification
|
||||
echo "git $@" > ` + filepath.Join(dir, "git_args.txt") + `
|
||||
exit 0
|
||||
`
|
||||
if err := os.WriteFile(fakeGitPath, []byte(script), 0755); err != nil {
|
||||
t.Fatalf("failed to create fake git: %v", err)
|
||||
}
|
||||
if repoName != "myrepo" {
|
||||
t.Errorf("repoName = %q, want myrepo", repoName)
|
||||
return fakeGitPath
|
||||
}
|
||||
|
||||
func runRepoCloneShortcut(t *testing.T, fakeGitPath string, args map[string]string) error {
|
||||
t.Helper()
|
||||
shortcut := findRepoShortcut(t, "clone")
|
||||
|
||||
// Set up PATH to include fake git
|
||||
origPath := os.Getenv("PATH")
|
||||
gitDir := filepath.Dir(fakeGitPath)
|
||||
os.Setenv("PATH", gitDir+":"+origPath)
|
||||
defer os.Setenv("PATH", origPath)
|
||||
|
||||
ctx := &common.RuntimeContext{
|
||||
Client: &client.Client{
|
||||
HTTP: nil,
|
||||
BaseURL: "https://www.gitlink.org.cn/api",
|
||||
},
|
||||
Owner: "owner",
|
||||
Repo: "repo",
|
||||
Format: "json",
|
||||
Args: args,
|
||||
}
|
||||
return shortcut.Run(ctx)
|
||||
}
|
||||
|
||||
func TestRepoListWithoutUser(t *testing.T) {
|
||||
|
|
|
|||
|
|
@ -1,4 +1,4 @@
|
|||
package ai
|
||||
package workflow
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
|
|
@ -11,7 +11,6 @@ import (
|
|||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/config"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
const deepseekBaseURL = "https://api.deepseek.com/v1/chat/completions"
|
||||
|
|
@ -24,6 +23,18 @@ type AIClient struct {
|
|||
http *http.Client
|
||||
}
|
||||
|
||||
// AIRequest bundles the data needed for an AI skill step call.
|
||||
type AIRequest struct {
|
||||
SystemPrompt string
|
||||
UserData string
|
||||
}
|
||||
|
||||
// AIResponse is the parsed structured output from an AI skill step.
|
||||
type AIResponse struct {
|
||||
Analysis interface{} `json:"analysis"`
|
||||
Actions []AIAction `json:"actions"`
|
||||
}
|
||||
|
||||
const jsonOutputInstruction = `
|
||||
|
||||
IMPORTANT: You MUST respond with a single JSON object in exactly this format:
|
||||
|
|
@ -53,7 +64,7 @@ func NewAIClient() *AIClient {
|
|||
}
|
||||
|
||||
// Analyze sends the skill prompt + upstream data to the DeepSeek API and parses the response.
|
||||
func (c *AIClient) Analyze(req *wf.AIRequest) (*wf.AIResponse, error) {
|
||||
func (c *AIClient) Analyze(req *AIRequest) (*AIResponse, error) {
|
||||
if c == nil {
|
||||
return nil, fmt.Errorf("AI client not configured: set DEEPSEEK_API_KEY or configure deepseek_api_key")
|
||||
}
|
||||
|
|
@ -114,6 +125,7 @@ func (c *AIClient) Analyze(req *wf.AIRequest) (*wf.AIResponse, error) {
|
|||
text := result.Choices[0].Message.Content
|
||||
aiResp, err := parseAIResponse(text)
|
||||
if err != nil {
|
||||
// Fallback: try to extract JSON from markdown code fences.
|
||||
if extracted := extractJSONFromMarkdown(text); extracted != "" {
|
||||
aiResp2, err2 := parseAIResponse(extracted)
|
||||
if err2 != nil {
|
||||
|
|
@ -129,7 +141,8 @@ func (c *AIClient) Analyze(req *wf.AIRequest) (*wf.AIResponse, error) {
|
|||
}
|
||||
|
||||
// parseAIResponse unmarshals the AI's JSON output, coercing numeric arg values to strings.
|
||||
func parseAIResponse(text string) (*wf.AIResponse, error) {
|
||||
func parseAIResponse(text string) (*AIResponse, error) {
|
||||
// First pass: unmarshal into a flexible structure that accepts numbers in args.
|
||||
raw := struct {
|
||||
Analysis json.RawMessage `json:"analysis"`
|
||||
Actions []struct {
|
||||
|
|
@ -146,8 +159,9 @@ func parseAIResponse(text string) (*wf.AIResponse, error) {
|
|||
return nil, err
|
||||
}
|
||||
|
||||
resp := &wf.AIResponse{}
|
||||
resp := &AIResponse{}
|
||||
if err := json.Unmarshal(raw.Analysis, &resp.Analysis); err != nil {
|
||||
// If it's not valid JSON, treat it as a plain string.
|
||||
resp.Analysis = string(raw.Analysis)
|
||||
}
|
||||
for _, a := range raw.Actions {
|
||||
|
|
@ -155,7 +169,7 @@ func parseAIResponse(text string) (*wf.AIResponse, error) {
|
|||
for k, v := range a.Args {
|
||||
args[k] = fmt.Sprint(v)
|
||||
}
|
||||
resp.Actions = append(resp.Actions, wf.AIAction{
|
||||
resp.Actions = append(resp.Actions, AIAction{
|
||||
Type: a.Type,
|
||||
Method: a.Method,
|
||||
Path: a.Path,
|
||||
|
|
@ -175,6 +189,7 @@ func (c *AIClient) HasKey() bool {
|
|||
|
||||
// extractJSONFromMarkdown tries to pull a JSON object out of a markdown code fence.
|
||||
func extractJSONFromMarkdown(text string) string {
|
||||
// Look for ```json ... ``` block.
|
||||
start := strings.Index(text, "```json")
|
||||
if start == -1 {
|
||||
start = strings.Index(text, "```")
|
||||
|
|
@ -182,6 +197,7 @@ func extractJSONFromMarkdown(text string) string {
|
|||
if start == -1 {
|
||||
return ""
|
||||
}
|
||||
// Find end of opening fence.
|
||||
nl := strings.Index(text[start:], "\n")
|
||||
if nl == -1 {
|
||||
return ""
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
package cli
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestShortcutsCount(t *testing.T) {
|
||||
sc := Shortcuts()
|
||||
if len(sc) != 10 {
|
||||
t.Fatalf("expected 10 shortcuts (list, info, run, watch, schedule, start, stop, status, logs, install-systemd), got %d", len(sc))
|
||||
}
|
||||
names := map[string]bool{
|
||||
"list": false, "info": false, "run": false, "watch": false,
|
||||
"schedule": false, "start": false, "stop": false, "status": false,
|
||||
"logs": false, "install-systemd": false,
|
||||
}
|
||||
for _, s := range sc {
|
||||
if _, ok := names[s.Name]; !ok {
|
||||
t.Fatalf("unexpected shortcut: %s", s.Name)
|
||||
}
|
||||
names[s.Name] = true
|
||||
}
|
||||
for n, found := range names {
|
||||
if !found {
|
||||
t.Fatalf("missing shortcut: %s", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
package workflow
|
||||
|
||||
func registerCodeQuality() {
|
||||
register(&WorkflowDef{
|
||||
Name: "code-quality",
|
||||
Category: "质量",
|
||||
Description: "代码质量看门人：PR 提交 → Review → CI 检查 → 结果汇总",
|
||||
Trigger: TriggerDef{
|
||||
Type: "poll",
|
||||
On: "pr.opened",
|
||||
Interval: "5m",
|
||||
},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "open-prs", Purpose: "获取开放 PR 列表", Target: "pr +list --state open --limit 20"},
|
||||
{Type: StepTypeCommand, Name: "ci-builds", Purpose: "获取 CI 构建状态", Target: "ci +builds --limit 10"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "获取仓库保护规则配置", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "获取最近提交供 CI 关联分析", Target: "commit +list --limit 30"},
|
||||
{Type: StepTypeCommand, Name: "branches", Purpose: "获取分支列表检查保护状态", Target: "branch +list"},
|
||||
{Type: StepTypeSkill, Name: "review", Purpose: "AI 审查 PR 代码质量", Target: "gitlink-review", DependsOn: []string{"open-prs"}},
|
||||
{Type: StepTypeSkill, Name: "ci-diagnosis", Purpose: "AI 诊断 CI 构建失败并给出建议", Target: "gitlink-ci", DependsOn: []string{"ci-builds", "commits"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ParseCommandTarget splits a CLI command string into tokens, respecting quoted arguments.
|
||||
func ParseCommandTarget(target string) []string {
|
||||
var parts []string
|
||||
var current strings.Builder
|
||||
inQuote := false
|
||||
quoteChar := byte(0)
|
||||
|
||||
for i := 0; i < len(target); i++ {
|
||||
c := target[i]
|
||||
switch {
|
||||
case c == '"' || c == '\'':
|
||||
if inQuote && c == quoteChar {
|
||||
inQuote = false
|
||||
quoteChar = 0
|
||||
} else if !inQuote {
|
||||
inQuote = true
|
||||
quoteChar = c
|
||||
} else {
|
||||
current.WriteByte(c)
|
||||
}
|
||||
case c == ' ' && !inQuote:
|
||||
if current.Len() > 0 {
|
||||
parts = append(parts, current.String())
|
||||
current.Reset()
|
||||
}
|
||||
default:
|
||||
current.WriteByte(c)
|
||||
}
|
||||
}
|
||||
if current.Len() > 0 {
|
||||
parts = append(parts, current.String())
|
||||
}
|
||||
return parts
|
||||
}
|
||||
|
||||
// ResolveCLIBinary finds the gitlink-cli binary for subprocess calls.
|
||||
func ResolveCLIBinary() string {
|
||||
if exe, err := os.Executable(); err == nil && exe != "" {
|
||||
return exe
|
||||
}
|
||||
for _, p := range []string{"./gitlink-cli", "./gitlink-cli.exe", "../gitlink-cli", "../gitlink-cli.exe"} {
|
||||
if _, err := os.Stat(p); err == nil {
|
||||
if abs, err := filepath.Abs(p); err == nil {
|
||||
return abs
|
||||
}
|
||||
return p
|
||||
}
|
||||
}
|
||||
return "gitlink-cli"
|
||||
}
|
||||
|
||||
// ResolvePath replaces template placeholders in a path string.
|
||||
func ResolvePath(template, owner, repo string) string {
|
||||
base := fmt.Sprintf("/%s/%s", owner, repo)
|
||||
v1 := fmt.Sprintf("/v1/%s/%s", owner, repo)
|
||||
s := strings.Replace(template, "{v1}", v1, 1)
|
||||
s = strings.Replace(s, "{base}", base, 1)
|
||||
return s
|
||||
}
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
package workflow
|
||||
|
||||
func registerCommunityOps() {
|
||||
register(&WorkflowDef{
|
||||
Name: "community-ops",
|
||||
Category: "运营",
|
||||
Description: "社区运营自动化：Issue 智能分拣 → 生成周报 → 生成 Release Notes",
|
||||
Trigger: TriggerDef{
|
||||
Type: "poll",
|
||||
On: "issue.created",
|
||||
Interval: "5m",
|
||||
},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "open-issues", Purpose: "获取所有开放 Issue 供 AI 分类", Target: "issue +list --state open --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "labels", Purpose: "获取标签库供 AI 匹配", Target: "label +list"},
|
||||
{Type: StepTypeCommand, Name: "members", Purpose: "获取成员列表供 AI 分配责任人", Target: "member +list"},
|
||||
{Type: StepTypeSkill, Name: "triage", Purpose: "AI 分析前三步数据，输出分拣表格并执行打标签/分配", Target: "gitlink-triage", DependsOn: []string{"open-issues", "labels", "members"}, RunWhen: RunAlways},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "获取项目基础信息", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "merged-prs", Purpose: "获取已合并 PR 计算合并效率", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "获取提交历史分析活跃度", Target: "commit +list --limit 50"},
|
||||
{Type: StepTypeSkill, Name: "health-report", Purpose: "AI 根据指标生成周报", Target: "gitlink-health", DependsOn: []string{"repo-info", "merged-prs", "commits", "open-issues"}, RunWhen: RunWeekly},
|
||||
{Type: StepTypeCommand, Name: "releases", Purpose: "获取版本发布记录", Target: "release +list"},
|
||||
{Type: StepTypeSkill, Name: "changelog", Purpose: "AI 分类 commit 生成 Release Notes", Target: "gitlink-changelog", DependsOn: []string{"commits", "releases", "merged-prs"}, RunWhen: RunOnChange},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -0,0 +1,23 @@
|
|||
package workflow
|
||||
|
||||
func registerContributorGrowth() {
|
||||
register(&WorkflowDef{
|
||||
Name: "contributor-growth",
|
||||
Category: "成长",
|
||||
Description: "贡献者成长体系：追踪贡献者活动 → 生成排行 → 识别活跃与流失",
|
||||
Trigger: TriggerDef{
|
||||
Type: "cron",
|
||||
On: "0 9 * * 1",
|
||||
Interval: "24h",
|
||||
},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "提交历史统计代码贡献", Target: "commit +list --limit 100"},
|
||||
{Type: StepTypeCommand, Name: "open-issues", Purpose: "开放 Issue 统计 Issue 贡献", Target: "issue +list --state open --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "closed-issues", Purpose: "已关闭 Issue 统计解决贡献", Target: "issue +list --state closed --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "merged-prs", Purpose: "已合并 PR 统计代码贡献", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "members", Purpose: "项目成员列表统计参与度", Target: "member +list"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "项目基础数据（Fork/Star/Watch）", Target: "repo +info"},
|
||||
{Type: StepTypeSkill, Name: "contributor-ranking", Purpose: "AI 分析贡献者排行并识别活跃与流失", Target: "gitlink-contributor-ranking", DependsOn: []string{"commits", "open-issues", "closed-issues", "merged-prs", "members"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
package daemon
|
||||
package workflow
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
|
|
@ -14,24 +14,22 @@ import (
|
|||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/config"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/engine"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/state"
|
||||
)
|
||||
|
||||
// StartDaemon launches a workflow as a background daemon process.
|
||||
func StartDaemon(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval time.Duration, aiMode string) error {
|
||||
func StartDaemon(ctx *common.RuntimeContext, wf *WorkflowDef, interval time.Duration, aiMode string) error {
|
||||
bin, err := os.Executable()
|
||||
if err != nil {
|
||||
return fmt.Errorf("cannot find executable: %w", err)
|
||||
}
|
||||
|
||||
args := BuildDaemonArgs(ctx, wfDef, interval, aiMode)
|
||||
args := buildDaemonArgs(ctx, wf, interval, aiMode)
|
||||
|
||||
cmd := exec.Command(bin, args...)
|
||||
applyDaemonAttrs(cmd)
|
||||
cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
|
||||
|
||||
logPath := daemonLogPath(wfDef.Name)
|
||||
// Redirect output to log file instead of discarding.
|
||||
logPath := daemonLogPath(wf.Name)
|
||||
logFile, err := os.OpenFile(logPath, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0600)
|
||||
if err != nil {
|
||||
return fmt.Errorf("create log file: %w", err)
|
||||
|
|
@ -44,25 +42,25 @@ func StartDaemon(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval tim
|
|||
logFile.Close()
|
||||
return fmt.Errorf("start daemon: %w", err)
|
||||
}
|
||||
// logFile is owned by child process; it will be closed when child exits.
|
||||
|
||||
pid := cmd.Process.Pid
|
||||
if err := savePID(wfDef.Name, pid); err != nil {
|
||||
if err := savePID(wf.Name, pid); err != nil {
|
||||
return fmt.Errorf("save pid: %w", err)
|
||||
}
|
||||
|
||||
fmt.Printf("Daemon started for %q (PID: %d)\n", wfDef.Name, pid)
|
||||
fmt.Printf("Daemon started for %q (PID: %d)\n", wf.Name, pid)
|
||||
fmt.Printf("Log: %s\n", logPath)
|
||||
return nil
|
||||
}
|
||||
|
||||
// BuildDaemonArgs constructs the CLI arguments for the daemon subprocess.
|
||||
func BuildDaemonArgs(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval time.Duration, aiMode string) []string {
|
||||
func buildDaemonArgs(ctx *common.RuntimeContext, wf *WorkflowDef, interval time.Duration, aiMode string) []string {
|
||||
args := []string{
|
||||
"workflow", "+run", "--name", wfDef.Name,
|
||||
"workflow", "+run", "--name", wf.Name,
|
||||
"--format", "json", "--daemon-loop",
|
||||
"--interval", interval.String(),
|
||||
}
|
||||
if !engine.IsExplicitMultiRepoRun(ctx, wfDef) {
|
||||
if !isExplicitMultiRepoRun(ctx, wf) {
|
||||
args = append(args, "--owner", ctx.Owner, "--repo", ctx.Repo)
|
||||
}
|
||||
if aiMode == "ai" {
|
||||
|
|
@ -96,6 +94,7 @@ func StopDaemon(name string) error {
|
|||
}
|
||||
|
||||
if err := proc.Signal(os.Interrupt); err != nil {
|
||||
// Process might already be dead; clean up pid file anyway.
|
||||
cleanPID(name)
|
||||
return fmt.Errorf("failed to stop daemon %q: %w", name, err)
|
||||
}
|
||||
|
|
@ -107,7 +106,7 @@ func StopDaemon(name string) error {
|
|||
|
||||
// StatusDaemon prints the current daemon status for a workflow.
|
||||
func StatusDaemon(name string) error {
|
||||
st, err := state.LoadState(name)
|
||||
state, err := LoadState(name)
|
||||
if err != nil {
|
||||
return fmt.Errorf("load state: %w", err)
|
||||
}
|
||||
|
|
@ -121,67 +120,72 @@ func StatusDaemon(name string) error {
|
|||
} else {
|
||||
fmt.Println("状态: 已停止")
|
||||
}
|
||||
if st.LastRun != "" {
|
||||
t, err := time.Parse(time.RFC3339, st.LastRun)
|
||||
if state.LastRun != "" {
|
||||
t, err := time.Parse(time.RFC3339, state.LastRun)
|
||||
if err == nil {
|
||||
fmt.Printf("上次运行: %s\n", t.Format("2006-01-02 15:04"))
|
||||
} else {
|
||||
fmt.Printf("上次运行: %s\n", st.LastRun)
|
||||
fmt.Printf("上次运行: %s\n", state.LastRun)
|
||||
}
|
||||
}
|
||||
fmt.Printf("累计运行: %d 次\n", st.TotalRuns)
|
||||
fmt.Printf("快照步骤: %d 个\n", len(st.Snapshots))
|
||||
fmt.Printf("累计运行: %d 次\n", state.TotalRuns)
|
||||
fmt.Printf("快照步骤: %d 个\n", len(state.Snapshots))
|
||||
fmt.Printf("日志文件: %s\n", daemonLogPath(name))
|
||||
return nil
|
||||
}
|
||||
|
||||
// DaemonLoop runs the workflow repeatedly in a loop.
|
||||
func DaemonLoop(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval time.Duration) error {
|
||||
// DaemonLoop runs the workflow repeatedly in a loop (used by the daemon subprocess).
|
||||
func DaemonLoop(ctx *common.RuntimeContext, wf *WorkflowDef, interval time.Duration) error {
|
||||
tick := time.NewTicker(interval)
|
||||
defer tick.Stop()
|
||||
|
||||
doDaemonCycle(ctx, wfDef)
|
||||
// Run immediately on start (dry-run to establish baseline).
|
||||
doDaemonCycle(ctx, wf)
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-tick.C:
|
||||
doDaemonCycle(ctx, wfDef)
|
||||
doDaemonCycle(ctx, wf)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func doDaemonCycle(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef) {
|
||||
st, _ := state.LoadState(wfDef.Name)
|
||||
func doDaemonCycle(ctx *common.RuntimeContext, wf *WorkflowDef) {
|
||||
state, _ := LoadState(wf.Name)
|
||||
|
||||
dryResult, err := engine.Run(ctx, wfDef, true)
|
||||
// Phase 1: cheap dry-run — collect data without AI.
|
||||
dryResult, err := Run(ctx, wf, true)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[%s] error: %v\n", time.Now().Format(time.RFC3339), err)
|
||||
return
|
||||
}
|
||||
|
||||
changed := st.Diff(dryResult.Steps)
|
||||
changed := state.Diff(dryResult.Steps)
|
||||
if len(changed) == 0 {
|
||||
if st.TotalRuns > 0 {
|
||||
if state.TotalRuns > 0 {
|
||||
fmt.Fprintf(os.Stderr, "[%s] 没有检测到变更\n", time.Now().Format(time.RFC3339))
|
||||
st.TotalRuns++
|
||||
st.Save()
|
||||
state.TotalRuns++
|
||||
state.Save()
|
||||
return
|
||||
}
|
||||
// First run: establish baseline snapshot, then proceed to full run.
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[%s] 🔔 检测到变更: %v\n", time.Now().Format(time.RFC3339), changed)
|
||||
}
|
||||
|
||||
fullResult, err := engine.Run(ctx, wfDef, false)
|
||||
// Phase 2: full run (AI or rules based on context.AIMode).
|
||||
fullResult, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[%s] run error: %v\n", time.Now().Format(time.RFC3339), err)
|
||||
return
|
||||
}
|
||||
|
||||
st, _ = state.LoadState(wfDef.Name)
|
||||
st.TotalRuns++
|
||||
st.Diff(fullResult.Steps)
|
||||
st.UpdateSnapshots(fullResult.Steps)
|
||||
st.Save()
|
||||
// Reload state — Run() may have updated ReviewedPRs fingerprints.
|
||||
state, _ = LoadState(wf.Name)
|
||||
state.TotalRuns++
|
||||
state.Diff(fullResult.Steps)
|
||||
state.UpdateSnapshots(fullResult.Steps)
|
||||
state.Save()
|
||||
|
||||
ok, total := 0, len(fullResult.Steps)
|
||||
for _, sr := range fullResult.Steps {
|
||||
|
|
@ -191,17 +195,19 @@ func doDaemonCycle(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef) {
|
|||
}
|
||||
fmt.Fprintf(os.Stderr, "[%s] ✅ %d/%d steps OK\n", time.Now().Format(time.RFC3339), ok, total)
|
||||
|
||||
// Log step-level details: failures and rule-engine findings.
|
||||
for _, sr := range fullResult.Steps {
|
||||
if !sr.OK {
|
||||
fmt.Fprintf(os.Stderr, "[%s] ❌ %s 失败: %s\n", time.Now().Format(time.RFC3339), sr.Step, sr.Error)
|
||||
}
|
||||
if sr.Type == wf.StepTypeSkill && sr.Data != nil {
|
||||
if sr.Type == StepTypeSkill && sr.Data != nil {
|
||||
logSkillFindings(sr)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func logSkillFindings(sr wf.StepResult) {
|
||||
// logSkillFindings prints rule-engine/AI analysis findings from a skill step to the daemon log.
|
||||
func logSkillFindings(sr StepResult) {
|
||||
m, ok := sr.Data.(map[string]interface{})
|
||||
if !ok {
|
||||
return
|
||||
|
|
@ -211,6 +217,7 @@ func logSkillFindings(sr wf.StepResult) {
|
|||
|
||||
fmt.Fprintf(os.Stderr, "[%s] ── %s 分析结果 ──\n", time.Now().Format(time.RFC3339), skill)
|
||||
|
||||
// AI mode returns analysis as a markdown string; print it directly.
|
||||
if s, ok := analysis.(string); ok && s != "" {
|
||||
for _, line := range strings.Split(s, "\n") {
|
||||
fmt.Fprintf(os.Stderr, "[%s] %s\n", time.Now().Format(time.RFC3339), line)
|
||||
|
|
@ -218,6 +225,7 @@ func logSkillFindings(sr wf.StepResult) {
|
|||
return
|
||||
}
|
||||
|
||||
// Rule engine returns analysis as a structured map.
|
||||
am, _ := analysis.(map[string]interface{})
|
||||
if am == nil {
|
||||
return
|
||||
|
|
@ -256,17 +264,13 @@ func logSkillFindings(sr wf.StepResult) {
|
|||
}
|
||||
}
|
||||
|
||||
// DaemonLogPath returns the log file path for a workflow daemon.
|
||||
func DaemonLogPath(name string) string {
|
||||
return daemonLogPath(name)
|
||||
}
|
||||
|
||||
// daemonLogPath returns the log file path for a workflow daemon.
|
||||
func daemonLogPath(name string) string {
|
||||
return filepath.Join(config.ConfigDir(), fmt.Sprintf("workflow-%s.log", name))
|
||||
}
|
||||
|
||||
// TailDaemonLog reads and optionally follows a daemon log file.
|
||||
func TailDaemonLog(name string, follow bool) error {
|
||||
// tailDaemonLog reads and optionally follows a daemon log file.
|
||||
func tailDaemonLog(name string, follow bool) error {
|
||||
path := daemonLogPath(name)
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
|
|
@ -311,8 +315,8 @@ func TailDaemonLog(name string, follow bool) error {
|
|||
}
|
||||
}
|
||||
|
||||
// InstallSystemdUnit generates a systemd service unit file for a workflow daemon.
|
||||
func InstallSystemdUnit(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval, aiMode string) error {
|
||||
// installSystemdUnit generates a systemd service unit file for a workflow daemon.
|
||||
func installSystemdUnit(ctx *common.RuntimeContext, wf *WorkflowDef, interval, aiMode string) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return fmt.Errorf("resolve repo: %w", err)
|
||||
}
|
||||
|
|
@ -340,12 +344,12 @@ StandardError=append:%s
|
|||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
`,
|
||||
wfDef.Name, ctx.Owner, ctx.Repo,
|
||||
bin, wfDef.Name, ctx.Owner, ctx.Repo, interval, extraArgs,
|
||||
daemonLogPath(wfDef.Name), daemonLogPath(wfDef.Name),
|
||||
wf.Name, ctx.Owner, ctx.Repo,
|
||||
bin, wf.Name, ctx.Owner, ctx.Repo, interval, extraArgs,
|
||||
daemonLogPath(wf.Name), daemonLogPath(wf.Name),
|
||||
)
|
||||
|
||||
unitPath := filepath.Join(config.ConfigDir(), fmt.Sprintf("workflow-%s.service", wfDef.Name))
|
||||
unitPath := filepath.Join(config.ConfigDir(), fmt.Sprintf("workflow-%s.service", wf.Name))
|
||||
if err := os.WriteFile(unitPath, []byte(unit), 0644); err != nil {
|
||||
return fmt.Errorf("写入 unit 文件: %w", err)
|
||||
}
|
||||
|
|
@ -354,10 +358,10 @@ WantedBy=multi-user.target
|
|||
fmt.Println("安装步骤:")
|
||||
fmt.Printf(" sudo cp %s /etc/systemd/system/\n", unitPath)
|
||||
fmt.Println(" sudo systemctl daemon-reload")
|
||||
fmt.Printf(" sudo systemctl enable workflow-%s\n", wfDef.Name)
|
||||
fmt.Printf(" sudo systemctl start workflow-%s\n", wfDef.Name)
|
||||
fmt.Printf(" sudo systemctl enable workflow-%s\n", wf.Name)
|
||||
fmt.Printf(" sudo systemctl start workflow-%s\n", wf.Name)
|
||||
fmt.Println()
|
||||
fmt.Printf("查看日志: journalctl -u workflow-%s -f\n", wfDef.Name)
|
||||
fmt.Printf("查看日志: journalctl -u workflow-%s -f\n", wf.Name)
|
||||
return nil
|
||||
}
|
||||
|
||||
|
|
@ -1,43 +0,0 @@
|
|||
package daemon
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
func TestBuildDaemonArgsSkipsOwnerRepoForExplicitMultiRepo(t *testing.T) {
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "multi-repo",
|
||||
}
|
||||
ctx := &common.RuntimeContext{
|
||||
Owner: "ignored",
|
||||
Repo: "ignored",
|
||||
Args: map[string]string{
|
||||
"repos": "org/backend,org/frontend",
|
||||
"release": "v1.4.0",
|
||||
},
|
||||
}
|
||||
|
||||
args := BuildDaemonArgs(ctx, wfDef, 24*time.Hour, "no-ai")
|
||||
if stringSliceContains(args, "--owner") || stringSliceContains(args, "--repo") {
|
||||
t.Fatalf("explicit multi-repo daemon args should not include owner/repo: %v", args)
|
||||
}
|
||||
if !stringSliceContains(args, "--repos") || !stringSliceContains(args, "org/backend,org/frontend") {
|
||||
t.Fatalf("daemon args missing repos: %v", args)
|
||||
}
|
||||
if !stringSliceContains(args, "--release") || !stringSliceContains(args, "v1.4.0") {
|
||||
t.Fatalf("daemon args missing release: %v", args)
|
||||
}
|
||||
}
|
||||
|
||||
func stringSliceContains(items []string, want string) bool {
|
||||
for _, item := range items {
|
||||
if item == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
//go:build !windows
|
||||
|
||||
package daemon
|
||||
|
||||
import (
|
||||
"os/exec"
|
||||
"syscall"
|
||||
)
|
||||
|
||||
func applyDaemonAttrs(cmd *exec.Cmd) {
|
||||
cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
|
||||
}
|
||||
|
|
@ -1,12 +0,0 @@
|
|||
//go:build windows
|
||||
|
||||
package daemon
|
||||
|
||||
import (
|
||||
"os/exec"
|
||||
"syscall"
|
||||
)
|
||||
|
||||
func applyDaemonAttrs(cmd *exec.Cmd) {
|
||||
cmd.SysProcAttr = &syscall.SysProcAttr{HideWindow: true}
|
||||
}
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
package daemon
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/engine"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/state"
|
||||
)
|
||||
|
||||
// Schedule runs the full workflow on a repeating interval. Blocks until Ctrl+C.
|
||||
func Schedule(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval time.Duration) error {
|
||||
fmt.Printf("⏰ Scheduled %q every %v on %s/%s\n", wfDef.Name, interval, ctx.Owner, ctx.Repo)
|
||||
fmt.Println(" Press Ctrl+C to stop")
|
||||
|
||||
sig := make(chan os.Signal, 1)
|
||||
signal.Notify(sig, os.Interrupt)
|
||||
tick := time.NewTicker(interval)
|
||||
defer tick.Stop()
|
||||
|
||||
st, _ := state.LoadState(wfDef.Name)
|
||||
dryResult, _ := engine.Run(ctx, wfDef, true)
|
||||
st.UpdateSnapshots(dryResult.Steps)
|
||||
st.TotalRuns++
|
||||
st.Save()
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-sig:
|
||||
fmt.Println("\n👋 schedule stopped")
|
||||
return nil
|
||||
case t := <-tick.C:
|
||||
dryResult, err := engine.Run(ctx, wfDef, true)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
changed := st.Diff(dryResult.Steps)
|
||||
st.UpdateSnapshots(dryResult.Steps)
|
||||
st.TotalRuns++
|
||||
st.Save()
|
||||
|
||||
if len(changed) == 0 {
|
||||
fmt.Printf("[%s] ✓ no changes, skipped AI run\n", t.Format("15:04:05"))
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("[%s] ⏳ changes detected, running %q with AI...\n", t.Format("15:04:05"), wfDef.Name)
|
||||
result, err := engine.Run(ctx, wfDef, false)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ error: %v\n", err)
|
||||
continue
|
||||
}
|
||||
ok, total := 0, len(result.Steps)
|
||||
for _, sr := range result.Steps {
|
||||
if sr.OK {
|
||||
ok++
|
||||
}
|
||||
}
|
||||
fmt.Printf("✅ %d/%d steps OK\n", ok, total)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,72 +0,0 @@
|
|||
package daemon
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/engine"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/state"
|
||||
)
|
||||
|
||||
// Watch polls the first step (or watchStep) every interval and triggers the
|
||||
// full workflow (with AI) only when data changes. Blocks until Ctrl+C.
|
||||
func Watch(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, interval time.Duration, watchStep string) error {
|
||||
if watchStep == "" && len(wfDef.Steps) > 0 {
|
||||
watchStep = wfDef.Steps[0].Name
|
||||
}
|
||||
|
||||
fmt.Printf("👀 Watching %s/%s for %q changes every %v\n", ctx.Owner, ctx.Repo, watchStep, interval)
|
||||
fmt.Printf(" Trigger: %s on %s\n", wfDef.Trigger.Type, wfDef.Trigger.On)
|
||||
fmt.Println(" Press Ctrl+C to stop")
|
||||
|
||||
sig := make(chan os.Signal, 1)
|
||||
signal.Notify(sig, os.Interrupt)
|
||||
|
||||
st, _ := state.LoadState(wfDef.Name)
|
||||
tick := time.NewTicker(interval)
|
||||
defer tick.Stop()
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-sig:
|
||||
fmt.Println("\n👋 watch stopped")
|
||||
return nil
|
||||
case t := <-tick.C:
|
||||
dryResult, err := engine.Run(ctx, wfDef, true)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
changed := st.Diff(dryResult.Steps)
|
||||
if len(changed) == 0 && st.TotalRuns > 0 {
|
||||
fmt.Printf("[%s] ✓ no changes\n", t.Format("15:04:05"))
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("[%s] 🔔 change detected: %v\n", t.Format("15:04:05"), changed)
|
||||
|
||||
result, err := engine.Run(ctx, wfDef, false)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ AI run error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
st.UpdateSnapshots(result.Steps)
|
||||
st.TotalRuns++
|
||||
st.Save()
|
||||
|
||||
for _, sr := range result.Steps {
|
||||
if sr.OK {
|
||||
fmt.Printf(" ✓ %s\n", sr.Step)
|
||||
} else {
|
||||
fmt.Printf(" ✗ %s: %s\n", sr.Step, sr.Error)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"testing"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
"github.com/gitlink-org/gitlink-cli/internal/client"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
)
|
||||
|
||||
func TestDaemonCycleTriageResult(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
// Return a simple issue list
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
w.Write([]byte(`{"ok":true,"data":{"issues":[{"project_issues_index":"1","title":"fix crash","body":"app crashes on startup"}]}}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := &common.RuntimeContext{
|
||||
Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
|
||||
Owner: "test", Repo: "test", Format: "json",
|
||||
Args: map[string]string{},
|
||||
}
|
||||
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-daemon-cycle",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "open-issues", Purpose: "issues", Target: "issue +list --state open"},
|
||||
{Type: StepTypeCommand, Name: "labels", Purpose: "labels", Target: "label +list"},
|
||||
{Type: StepTypeCommand, Name: "members", Purpose: "members", Target: "member +list"},
|
||||
{Type: StepTypeSkill, Name: "triage", Purpose: "triage", Target: "gitlink-triage", DependsOn: []string{"open-issues", "labels", "members"}},
|
||||
},
|
||||
}
|
||||
|
||||
// Simulate daemon cycle: dry-run then full run with same ctx
|
||||
t.Log("=== Dry run ===")
|
||||
dryResult, _ := Run(ctx, wf, true)
|
||||
for _, sr := range dryResult.Steps {
|
||||
t.Logf("dry %s: ok=%v data=%v", sr.Step, sr.OK, sr.Data)
|
||||
}
|
||||
|
||||
t.Log("=== Full run ===")
|
||||
fullResult, _ := Run(ctx, wf, false)
|
||||
for _, sr := range fullResult.Steps {
|
||||
t.Logf("full %s: ok=%v data=%v", sr.Step, sr.OK, sr.Data)
|
||||
if sr.Step == "triage" {
|
||||
d, ok := sr.Data.(map[string]interface{})
|
||||
if ok {
|
||||
a, _ := d["analysis"].(map[string]interface{})
|
||||
t.Logf("triage analysis: %v", a)
|
||||
if a != nil {
|
||||
t.Logf("classified: %v", a["classified"])
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
package defs
|
||||
|
||||
import wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
|
||||
// RegisterCodeQuality registers the code-quality workflow definition.
|
||||
func RegisterCodeQuality() {
|
||||
wf.Register(&wf.WorkflowDef{
|
||||
Name: "code-quality",
|
||||
Category: "质量",
|
||||
Description: "代码质量看门人：PR 提交 → Review → CI 检查 → 结果汇总",
|
||||
Trigger: wf.TriggerDef{
|
||||
Type: "poll",
|
||||
On: "pr.opened",
|
||||
Interval: "5m",
|
||||
},
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeCommand, Name: "open-prs", Purpose: "获取开放 PR 列表", Target: "pr +list --state open --limit 20"},
|
||||
{Type: wf.StepTypeCommand, Name: "ci-builds", Purpose: "获取 CI 构建状态", Target: "ci +builds --limit 10"},
|
||||
{Type: wf.StepTypeCommand, Name: "repo-info", Purpose: "获取仓库保护规则配置", Target: "repo +info"},
|
||||
{Type: wf.StepTypeCommand, Name: "commits", Purpose: "获取最近提交供 CI 关联分析", Target: "commit +list --limit 30"},
|
||||
{Type: wf.StepTypeCommand, Name: "branches", Purpose: "获取分支列表检查保护状态", Target: "branch +list"},
|
||||
{Type: wf.StepTypeSkill, Name: "review", Purpose: "AI 审查 PR 代码质量", Target: "gitlink-review", DependsOn: []string{"open-prs"}},
|
||||
{Type: wf.StepTypeSkill, Name: "ci-diagnosis", Purpose: "AI 诊断 CI 构建失败并给出建议", Target: "gitlink-ci", DependsOn: []string{"ci-builds", "commits"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
package defs
|
||||
|
||||
import wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
|
||||
// RegisterCommunityOps registers the community-ops workflow definition.
|
||||
func RegisterCommunityOps() {
|
||||
wf.Register(&wf.WorkflowDef{
|
||||
Name: "community-ops",
|
||||
Category: "运营",
|
||||
Description: "社区运营自动化：Issue 智能分拣 → 生成周报 → 生成 Release Notes",
|
||||
Trigger: wf.TriggerDef{
|
||||
Type: "poll",
|
||||
On: "issue.created",
|
||||
Interval: "5m",
|
||||
},
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeCommand, Name: "open-issues", Purpose: "获取所有开放 Issue 供 AI 分类", Target: "issue +list --state open --limit 50"},
|
||||
{Type: wf.StepTypeCommand, Name: "labels", Purpose: "获取标签库供 AI 匹配", Target: "label +list"},
|
||||
{Type: wf.StepTypeCommand, Name: "members", Purpose: "获取成员列表供 AI 分配责任人", Target: "member +list"},
|
||||
{Type: wf.StepTypeSkill, Name: "triage", Purpose: "AI 分析前三步数据，输出分拣表格并执行打标签/分配", Target: "gitlink-triage", DependsOn: []string{"open-issues", "labels", "members"}, RunWhen: wf.RunAlways},
|
||||
{Type: wf.StepTypeCommand, Name: "repo-info", Purpose: "获取项目基础信息", Target: "repo +info"},
|
||||
{Type: wf.StepTypeCommand, Name: "merged-prs", Purpose: "获取已合并 PR 计算合并效率", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: wf.StepTypeCommand, Name: "commits", Purpose: "获取提交历史分析活跃度", Target: "commit +list --limit 50"},
|
||||
{Type: wf.StepTypeSkill, Name: "health-report", Purpose: "AI 根据指标生成周报", Target: "gitlink-health", DependsOn: []string{"repo-info", "merged-prs", "commits", "open-issues"}, RunWhen: wf.RunWeekly},
|
||||
{Type: wf.StepTypeCommand, Name: "releases", Purpose: "获取版本发布记录", Target: "release +list"},
|
||||
{Type: wf.StepTypeSkill, Name: "changelog", Purpose: "AI 分类 commit 生成 Release Notes", Target: "gitlink-changelog", DependsOn: []string{"commits", "releases", "merged-prs"}, RunWhen: wf.RunOnChange},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,26 +0,0 @@
|
|||
package defs
|
||||
|
||||
import wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
|
||||
// RegisterContributorGrowth registers the contributor-growth workflow definition.
|
||||
func RegisterContributorGrowth() {
|
||||
wf.Register(&wf.WorkflowDef{
|
||||
Name: "contributor-growth",
|
||||
Category: "成长",
|
||||
Description: "贡献者成长体系：追踪贡献者活动 → 生成排行 → 识别活跃与流失",
|
||||
Trigger: wf.TriggerDef{
|
||||
Type: "cron",
|
||||
On: "0 9 * * 1",
|
||||
Interval: "24h",
|
||||
},
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeCommand, Name: "commits", Purpose: "提交历史统计代码贡献", Target: "commit +list --limit 100"},
|
||||
{Type: wf.StepTypeCommand, Name: "open-issues", Purpose: "开放 Issue 统计 Issue 贡献", Target: "issue +list --state open --limit 50"},
|
||||
{Type: wf.StepTypeCommand, Name: "closed-issues", Purpose: "已关闭 Issue 统计解决贡献", Target: "issue +list --state closed --limit 50"},
|
||||
{Type: wf.StepTypeCommand, Name: "merged-prs", Purpose: "已合并 PR 统计代码贡献", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: wf.StepTypeCommand, Name: "members", Purpose: "项目成员列表统计参与度", Target: "member +list"},
|
||||
{Type: wf.StepTypeCommand, Name: "repo-info", Purpose: "项目基础数据（Fork/Star/Watch）", Target: "repo +info"},
|
||||
{Type: wf.StepTypeSkill, Name: "contributor-ranking", Purpose: "AI 分析贡献者排行并识别活跃与流失", Target: "gitlink-contributor-ranking", DependsOn: []string{"commits", "open-issues", "closed-issues", "merged-prs", "members"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
package defs
|
||||
|
||||
func init() {
|
||||
RegisterCommunityOps()
|
||||
RegisterCodeQuality()
|
||||
RegisterProjectInit()
|
||||
RegisterMultiRepo()
|
||||
RegisterContributorGrowth()
|
||||
}
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
package defs
|
||||
|
||||
import wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
|
||||
// RegisterProjectInit registers the project-init workflow definition.
|
||||
func RegisterProjectInit() {
|
||||
wf.Register(&wf.WorkflowDef{
|
||||
Name: "project-init",
|
||||
Category: "初始化",
|
||||
Description: "项目一键初始化：创建仓库 → 脚手架文件 → 标签/里程碑/Issue → 许可证审计 → 健康报告",
|
||||
Trigger: wf.TriggerDef{
|
||||
Type: "manual",
|
||||
On: "manual",
|
||||
},
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeSkill, Name: "init-scaffold", Purpose: "根据描述创建仓库并初始化脚手架（README/LICENSE/.gitignore/标签/里程碑/Issue）", Target: "gitlink-init-scaffold"},
|
||||
{Type: wf.StepTypeCommand, Name: "repo-info", Purpose: "确认仓库已创建并获取基础信息", Target: "repo +info"},
|
||||
{Type: wf.StepTypeCommand, Name: "existing-files", Purpose: "验证 README/LICENSE 文件", Target: "file +list"},
|
||||
{Type: wf.StepTypeCommand, Name: "labels", Purpose: "验证标签库", Target: "label +list"},
|
||||
{Type: wf.StepTypeSkill, Name: "license-check", Purpose: "检查许可证合规并扫描敏感信息泄露", Target: "gitlink-license", DependsOn: []string{"existing-files"}},
|
||||
{Type: wf.StepTypeCommand, Name: "milestones", Purpose: "验证里程碑", Target: "milestone +list"},
|
||||
{Type: wf.StepTypeCommand, Name: "existing-issues", Purpose: "验证初始 Issue", Target: "issue +list --state all --limit 10"},
|
||||
{Type: wf.StepTypeCommand, Name: "branches", Purpose: "检查分支结构", Target: "branch +list"},
|
||||
{Type: wf.StepTypeSkill, Name: "repo-audit", Purpose: "综合审计仓库健康度", Target: "gitlink-repo", DependsOn: []string{"repo-info", "existing-files", "labels", "milestones", "branches"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -0,0 +1,181 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// WorkflowResult holds the outcome of a full workflow run.
|
||||
type WorkflowResult struct {
|
||||
Workflow string `json:"workflow"`
|
||||
Owner string `json:"owner"`
|
||||
Repo string `json:"repo"`
|
||||
Steps []StepResult `json:"steps"`
|
||||
}
|
||||
|
||||
// Run executes every step in a workflow sequentially.
|
||||
// Steps later in the sequence receive data from their DependsOn predecessors
|
||||
// via ctx.Args (keyed by step name, stored as JSON).
|
||||
// Set dryRun to true to skip AI API calls for skill steps.
|
||||
func Run(ctx *common.RuntimeContext, wf *WorkflowDef, dryRun bool) (*WorkflowResult, error) {
|
||||
return RunWithMode(ctx, wf, dryRun, "")
|
||||
}
|
||||
|
||||
// RunWithMode executes a workflow with explicit AI mode control.
|
||||
// aiMode must be "auto", "ai", "no-ai", or "" (equivalent to "auto").
|
||||
func RunWithMode(ctx *common.RuntimeContext, wf *WorkflowDef, dryRun bool, aiMode string) (*WorkflowResult, error) {
|
||||
if aiMode != "" {
|
||||
ctx.AIMode = aiMode
|
||||
}
|
||||
return run(ctx, wf, dryRun)
|
||||
}
|
||||
|
||||
func run(ctx *common.RuntimeContext, wf *WorkflowDef, dryRun bool) (*WorkflowResult, error) {
|
||||
if !shouldSkipOwnerRepoResolve(ctx, wf) {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return nil, fmt.Errorf("resolve repo: %w", err)
|
||||
}
|
||||
}
|
||||
|
||||
if ctx.Args == nil {
|
||||
ctx.Args = make(map[string]string)
|
||||
}
|
||||
if _, ok := ctx.Args["dry_run"]; !ok && dryRun {
|
||||
ctx.Args["dry_run"] = "true"
|
||||
}
|
||||
ctx.Args["__wf_name"] = wf.Name
|
||||
|
||||
// Make owner and repo available to skill rules as _owner / _repo.
|
||||
if ctx.Owner != "" {
|
||||
ctx.Args["_owner"] = ctx.Owner
|
||||
}
|
||||
if ctx.Repo != "" {
|
||||
ctx.Args["_repo"] = ctx.Repo
|
||||
}
|
||||
|
||||
// Load state for condition checks (only in non-dry-run mode).
|
||||
var state *WorkflowState
|
||||
if !dryRun {
|
||||
state, _ = LoadState(wf.Name)
|
||||
}
|
||||
|
||||
results := make([]StepResult, 0, len(wf.Steps))
|
||||
for _, step := range wf.Steps {
|
||||
// Compute upstream hash for condition checking and state tracking.
|
||||
var upstreamHash string
|
||||
if !dryRun && state != nil {
|
||||
upstream := collectUpstream(ctx, step)
|
||||
upstreamHash = hashData(upstream)
|
||||
}
|
||||
|
||||
// Check phase condition for non-dry-run, non-default steps.
|
||||
if !dryRun && state != nil && step.RunWhen != "" && step.RunWhen != RunAlways {
|
||||
shouldRun, skipReason := checkPhaseCondition(step, state, upstreamHash)
|
||||
if !shouldRun {
|
||||
fmt.Fprintf(os.Stderr, "[%s] 跳过 %s: %s\n", wf.Name, step.Name, skipReason)
|
||||
results = append(results, StepResult{
|
||||
Step: step.Name,
|
||||
Purpose: step.Purpose,
|
||||
Type: step.Type,
|
||||
OK: true,
|
||||
Skipped: true,
|
||||
SkipReason: skipReason,
|
||||
})
|
||||
continue
|
||||
}
|
||||
}
|
||||
|
||||
sr := ExecuteStep(ctx, step, dryRun)
|
||||
results = append(results, *sr)
|
||||
|
||||
// After successful step, update state for future condition checks.
|
||||
if !dryRun && state != nil && sr.OK && !sr.Skipped {
|
||||
if state.PhaseLastRun == nil {
|
||||
state.PhaseLastRun = make(map[string]string)
|
||||
}
|
||||
state.PhaseLastRun[step.Name] = time.Now().Format(time.RFC3339)
|
||||
if state.PhaseUpstream == nil {
|
||||
state.PhaseUpstream = make(map[string]string)
|
||||
}
|
||||
state.PhaseUpstream[step.Name] = upstreamHash
|
||||
}
|
||||
|
||||
// Feed output of this step as input to downstream steps via Args.
|
||||
if sr.Data != nil {
|
||||
raw, err := json.Marshal(sr.Data)
|
||||
if err == nil {
|
||||
ctx.Args[step.Name] = string(raw)
|
||||
} else {
|
||||
ctx.Args[step.Name] = fmt.Sprint(sr.Data)
|
||||
}
|
||||
} else if !sr.OK && sr.Error != "" {
|
||||
ctx.Args[step.Name] = fmt.Sprintf(`{"_error": true, "_message": %q}`, sr.Error)
|
||||
}
|
||||
}
|
||||
|
||||
if !dryRun && state != nil {
|
||||
state.Save()
|
||||
}
|
||||
|
||||
return &WorkflowResult{
|
||||
Workflow: wf.Name,
|
||||
Owner: ctx.Owner,
|
||||
Repo: ctx.Repo,
|
||||
Steps: results,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func shouldSkipOwnerRepoResolve(ctx *common.RuntimeContext, wf *WorkflowDef) bool {
|
||||
return isExplicitMultiRepoRun(ctx, wf)
|
||||
}
|
||||
|
||||
func isExplicitMultiRepoRun(ctx *common.RuntimeContext, wf *WorkflowDef) bool {
|
||||
if wf == nil || wf.Name != "multi-repo" {
|
||||
return false
|
||||
}
|
||||
return ctx.Arg("repos") != "" || ctx.Arg("from") != ""
|
||||
}
|
||||
|
||||
// checkPhaseCondition determines whether a step should run based on its RunWhen setting.
|
||||
func checkPhaseCondition(step StepDef, state *WorkflowState, upstreamHash string) (bool, string) {
|
||||
switch step.RunWhen {
|
||||
case RunWeekly:
|
||||
last := state.PhaseLastRun[step.Name]
|
||||
if last == "" {
|
||||
return true, "" // first run
|
||||
}
|
||||
t, err := time.Parse(time.RFC3339, last)
|
||||
if err != nil {
|
||||
return true, ""
|
||||
}
|
||||
if time.Since(t) >= 7*24*time.Hour {
|
||||
return true, "" // more than 7 days
|
||||
}
|
||||
next := t.Add(7 * 24 * time.Hour)
|
||||
return false, fmt.Sprintf("下次运行: %s", next.Format("01-02 15:04"))
|
||||
case RunOnChange:
|
||||
if prev, ok := state.PhaseUpstream[step.Name]; ok && prev == upstreamHash {
|
||||
return false, "数据无变化"
|
||||
}
|
||||
return true, ""
|
||||
default:
|
||||
return true, ""
|
||||
}
|
||||
}
|
||||
|
||||
// resolvePath replaces template placeholders in a path string.
|
||||
//
|
||||
// {base} → /owner/repo
|
||||
// {v1} → /v1/owner/repo
|
||||
func resolvePath(template, owner, repo string) string {
|
||||
base := fmt.Sprintf("/%s/%s", owner, repo)
|
||||
v1 := fmt.Sprintf("/v1/%s/%s", owner, repo)
|
||||
s := strings.Replace(template, "{v1}", v1, 1)
|
||||
s = strings.Replace(s, "{base}", base, 1)
|
||||
return s
|
||||
}
|
||||
|
|
@ -1,129 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"crypto/md5"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
func executeActions(ctx *common.RuntimeContext, actions []wf.AIAction) (int, []string) {
|
||||
executed := 0
|
||||
var errors []string
|
||||
seen := make(map[string]bool, len(actions))
|
||||
for _, action := range actions {
|
||||
key := actionKey(action)
|
||||
if seen[key] {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] skipped duplicate action: %s %s %s\n", action.Type, action.Module, action.Command)
|
||||
continue
|
||||
}
|
||||
seen[key] = true
|
||||
if !isActionAllowed(action) {
|
||||
msg := fmt.Sprintf("blocked action: %s %s +%s", action.Type, action.Module, action.Command)
|
||||
fmt.Fprintf(os.Stderr, "[workflow] %s\n", msg)
|
||||
errors = append(errors, msg)
|
||||
continue
|
||||
}
|
||||
if action.Type == "api" {
|
||||
path := wf.ResolvePath(action.Path, ctx.Owner, ctx.Repo)
|
||||
_, err := ctx.CallAPI(action.Method, path, action.Body)
|
||||
if err != nil {
|
||||
msg := fmt.Sprintf("api %s %s: %v", action.Method, path, err)
|
||||
fmt.Fprintf(os.Stderr, "[workflow] %s\n", msg)
|
||||
errors = append(errors, msg)
|
||||
continue
|
||||
}
|
||||
executed++
|
||||
} else if action.Type == "cli" {
|
||||
args := []string{action.Module, action.Command}
|
||||
for k, v := range action.Args {
|
||||
args = append(args, "--"+k, v)
|
||||
}
|
||||
if ctx.Owner != "" {
|
||||
args = append(args, "--owner", ctx.Owner)
|
||||
}
|
||||
if ctx.Repo != "" {
|
||||
args = append(args, "--repo", ctx.Repo)
|
||||
}
|
||||
bin := wf.ResolveCLIBinary()
|
||||
cmd := exec.Command(bin, args...)
|
||||
var cliStderr bytes.Buffer
|
||||
cmd.Stderr = &cliStderr
|
||||
err := cmd.Run()
|
||||
if err != nil {
|
||||
stderrStr := strings.TrimSpace(cliStderr.String())
|
||||
if action.Module == "repo" && action.Command == "+create" && strings.Contains(stderrStr, "已被使用") {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] repo %s already exists, reusing\n", action.Args["name"])
|
||||
executed++
|
||||
if name := action.Args["name"]; name != "" && ctx.Repo == "" {
|
||||
ctx.Repo = name
|
||||
}
|
||||
continue
|
||||
}
|
||||
msg := fmt.Sprintf("cli %s: %v", strings.Join(args, " "), err)
|
||||
if cliStderr.Len() > 0 {
|
||||
msg += " — " + stderrStr
|
||||
}
|
||||
fmt.Fprintf(os.Stderr, "[workflow] %s\n", msg)
|
||||
errors = append(errors, msg)
|
||||
continue
|
||||
}
|
||||
executed++
|
||||
if action.Module == "repo" && action.Command == "+create" {
|
||||
if name := action.Args["name"]; name != "" && ctx.Repo == "" {
|
||||
ctx.Repo = name
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return executed, errors
|
||||
}
|
||||
|
||||
func actionKey(action wf.AIAction) string {
|
||||
raw, err := json.Marshal(action)
|
||||
if err != nil {
|
||||
return fmt.Sprintf("%s:%s:%s:%v:%s:%s", action.Type, action.Module, action.Command, action.Args, action.Method, action.Path)
|
||||
}
|
||||
sum := md5.Sum(raw)
|
||||
return hex.EncodeToString(sum[:])
|
||||
}
|
||||
|
||||
var allowedAPIMethods = map[string]bool{
|
||||
"GET": true, "POST": true, "PATCH": true,
|
||||
}
|
||||
|
||||
var allowedCLIModules = map[string]bool{
|
||||
"issue": true, "pr": true, "release": true,
|
||||
"wiki": true, "member": true, "label": true,
|
||||
"milestone": true, "branch": true, "comment": true,
|
||||
"repo": true, "file": true,
|
||||
}
|
||||
|
||||
var blockedCLICommands = map[string]bool{
|
||||
"+delete": true, "+remove": true, "+batch-delete": true,
|
||||
"+fork": true, "+batch-fork": true,
|
||||
}
|
||||
|
||||
func isActionAllowed(action wf.AIAction) bool {
|
||||
if action.Type == "api" {
|
||||
if !allowedAPIMethods[action.Method] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
if action.Type == "cli" {
|
||||
if !allowedCLIModules[action.Module] {
|
||||
return false
|
||||
}
|
||||
if blockedCLICommands[action.Command] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
|
@ -1,31 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
func TestActionAllowed(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
action wf.AIAction
|
||||
allowed bool
|
||||
}{
|
||||
{"api GET", wf.AIAction{Type: "api", Method: "GET"}, true},
|
||||
{"api POST", wf.AIAction{Type: "api", Method: "POST"}, true},
|
||||
{"api PATCH", wf.AIAction{Type: "api", Method: "PATCH"}, true},
|
||||
{"api DELETE blocked", wf.AIAction{Type: "api", Method: "DELETE"}, false},
|
||||
{"cli issue comment", wf.AIAction{Type: "cli", Module: "issue", Command: "+comment"}, true},
|
||||
{"cli delete blocked", wf.AIAction{Type: "cli", Module: "repo", Command: "+delete"}, false},
|
||||
{"cli fork blocked", wf.AIAction{Type: "cli", Module: "repo", Command: "+fork"}, false},
|
||||
{"cli repo module blocked", wf.AIAction{Type: "cli", Module: "org", Command: "+list"}, false},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
if got := isActionAllowed(tc.action); got != tc.allowed {
|
||||
t.Errorf("isActionAllowed(%+v) = %v, want %v", tc.action, got, tc.allowed)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
|
@ -1,254 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/client"
|
||||
"github.com/gitlink-org/gitlink-cli/internal/output"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
func TestRunWithAPISteps(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
switch {
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/issues.json":
|
||||
writeJSON(t, w, output.SuccessEnvelope([]map[string]interface{}{
|
||||
{"id": 1, "subject": "bug"},
|
||||
{"id": 2, "subject": "feature"},
|
||||
}, nil))
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/labels.json":
|
||||
writeJSON(t, w, output.SuccessEnvelope([]map[string]interface{}{
|
||||
{"id": 10, "name": "bug"},
|
||||
{"id": 11, "name": "enhancement"},
|
||||
}, nil))
|
||||
default:
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-api",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeAPI, Name: "fetch-issues", Purpose: "get issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: wf.StepTypeAPI, Name: "fetch-labels", Purpose: "get labels", Method: "GET", Target: "{v1}/labels"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
if result.Owner != "owner" || result.Repo != "repo" {
|
||||
t.Fatalf("expected owner/repo = owner/repo, got %s/%s", result.Owner, result.Repo)
|
||||
}
|
||||
if len(result.Steps) != 2 {
|
||||
t.Fatalf("expected 2 step results, got %d", len(result.Steps))
|
||||
}
|
||||
for _, sr := range result.Steps {
|
||||
if !sr.OK {
|
||||
t.Fatalf("step %q: expected ok=true, got error=%q", sr.Step, sr.Error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestSkillStepReceivesUpstream(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path == "/v1/owner/repo/issues.json" {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{
|
||||
"issues": []map[string]interface{}{{"id": 1}},
|
||||
}, nil))
|
||||
} else if r.URL.Path == "/v1/owner/repo/labels.json" {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{
|
||||
"labels": []map[string]interface{}{{"name": "bug"}},
|
||||
}, nil))
|
||||
} else {
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-skill-upstream",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeAPI, Name: "get-issues", Purpose: "issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: wf.StepTypeAPI, Name: "get-labels", Purpose: "labels", Method: "GET", Target: "{v1}/labels"},
|
||||
{Type: wf.StepTypeSkill, Name: "ai-triage", Purpose: "triage", Target: "gitlink-triage"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, true) // dry-run to test upstream without AI
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[2].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
if v, _ := skillData["_dry_run"]; v != true {
|
||||
t.Fatal("skill step should have _dry_run=true")
|
||||
}
|
||||
upstream, ok := skillData["_upstream"].(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step missing _upstream map")
|
||||
}
|
||||
if _, hasIssues := upstream["get-issues"]; !hasIssues {
|
||||
t.Fatal("_upstream missing get-issues key")
|
||||
}
|
||||
if _, hasLabels := upstream["get-labels"]; !hasLabels {
|
||||
t.Fatal("_upstream missing get-labels key")
|
||||
}
|
||||
if skillData["_skill"] != "gitlink-triage" {
|
||||
t.Fatalf("_skill = %q, want %q", skillData["_skill"], "gitlink-triage")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSkillStepWithDependsOn(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{"ok": true}, nil))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-depends-on",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeAPI, Name: "open-issues", Purpose: "issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: wf.StepTypeAPI, Name: "labels", Purpose: "labels", Method: "GET", Target: "{v1}/labels"},
|
||||
{Type: wf.StepTypeAPI, Name: "members", Purpose: "members", Method: "GET", Target: "{v1}/members"},
|
||||
{Type: wf.StepTypeSkill, Name: "triage", Purpose: "triage", Target: "gitlink-triage",
|
||||
DependsOn: []string{"open-issues", "labels"}},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, true) // dry-run to test DependsOn filter without AI
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[3].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
upstream, ok := skillData["_upstream"].(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step missing _upstream map")
|
||||
}
|
||||
if _, hasIssues := upstream["open-issues"]; !hasIssues {
|
||||
t.Fatal("_upstream missing open-issues key")
|
||||
}
|
||||
if _, hasLabels := upstream["labels"]; !hasLabels {
|
||||
t.Fatal("_upstream missing labels key")
|
||||
}
|
||||
if _, hasMembers := upstream["members"]; hasMembers {
|
||||
t.Fatal("_upstream should NOT contain members (not in DependsOn)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunStepFailure(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(500)
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"ok": false, "error": "internal server error",
|
||||
})
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-fail",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeAPI, Name: "bad-step", Purpose: "will fail", Method: "GET", Target: "{v1}/bad"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() returned error: %v (steps should fail gracefully)", err)
|
||||
}
|
||||
if result.Steps[0].OK {
|
||||
t.Fatal("expected step to fail, but it passed")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunUnknownStepType(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
t.Fatalf("no request expected")
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-unknown",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepType("invalid"), Name: "bad", Purpose: "unknown", Target: "x"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() returned error: %v", err)
|
||||
}
|
||||
if result.Steps[0].OK {
|
||||
t.Fatal("unknown step type should fail")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSkillStepDryRun(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{"ok": true}, nil))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wfDef := &wf.WorkflowDef{
|
||||
Name: "test-dry-run",
|
||||
Steps: []wf.StepDef{
|
||||
{Type: wf.StepTypeAPI, Name: "get-data", Purpose: "data", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: wf.StepTypeSkill, Name: "ai-step", Purpose: "AI analysis", Target: "gitlink-triage",
|
||||
DependsOn: []string{"get-data"}},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wfDef, true)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() dry-run failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[1].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
if v, _ := skillData["_dry_run"]; v != true {
|
||||
t.Fatal("dry-run skill step should have _dry_run=true")
|
||||
}
|
||||
}
|
||||
|
||||
func newTestContext(t *testing.T, server *httptest.Server) *common.RuntimeContext {
|
||||
t.Helper()
|
||||
return &common.RuntimeContext{
|
||||
Client: &client.Client{
|
||||
HTTP: server.Client(),
|
||||
BaseURL: server.URL,
|
||||
},
|
||||
Owner: "owner",
|
||||
Repo: "repo",
|
||||
Format: "json",
|
||||
Args: map[string]string{},
|
||||
}
|
||||
}
|
||||
|
||||
func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
|
||||
t.Helper()
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
if err := json.NewEncoder(w).Encode(payload); err != nil {
|
||||
t.Fatalf("failed to write response: %v", err)
|
||||
}
|
||||
}
|
||||
|
|
@ -1,175 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/state"
|
||||
)
|
||||
|
||||
// Run executes every step in a workflow sequentially.
|
||||
func Run(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, dryRun bool) (*wf.WorkflowResult, error) {
|
||||
return RunWithMode(ctx, wfDef, dryRun, "")
|
||||
}
|
||||
|
||||
// RunWithMode executes a workflow with explicit AI mode control.
|
||||
func RunWithMode(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, dryRun bool, aiMode string) (*wf.WorkflowResult, error) {
|
||||
if aiMode != "" {
|
||||
ctx.AIMode = aiMode
|
||||
}
|
||||
return run(ctx, wfDef, dryRun)
|
||||
}
|
||||
|
||||
func run(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef, dryRun bool) (*wf.WorkflowResult, error) {
|
||||
if !shouldSkipOwnerRepoResolve(ctx, wfDef) {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return nil, fmt.Errorf("resolve repo: %w", err)
|
||||
}
|
||||
}
|
||||
|
||||
if ctx.Args == nil {
|
||||
ctx.Args = make(map[string]string)
|
||||
}
|
||||
if _, ok := ctx.Args["dry_run"]; !ok && dryRun {
|
||||
ctx.Args["dry_run"] = "true"
|
||||
}
|
||||
ctx.Args["__wf_name"] = wfDef.Name
|
||||
|
||||
if ctx.Owner != "" {
|
||||
ctx.Args["_owner"] = ctx.Owner
|
||||
}
|
||||
if ctx.Repo != "" {
|
||||
ctx.Args["_repo"] = ctx.Repo
|
||||
}
|
||||
|
||||
var workflowState *state.WorkflowState
|
||||
if !dryRun {
|
||||
workflowState, _ = state.LoadState(wfDef.Name)
|
||||
}
|
||||
|
||||
results := make([]wf.StepResult, 0, len(wfDef.Steps))
|
||||
for _, step := range wfDef.Steps {
|
||||
var upstreamHash string
|
||||
if !dryRun && workflowState != nil {
|
||||
upstream := collectUpstream(ctx, step)
|
||||
upstreamHash = state.HashData(upstream)
|
||||
}
|
||||
|
||||
isDaemon := ctx.Arg("daemon-loop") == "true"
|
||||
if isDaemon && !dryRun && workflowState != nil && step.RunWhen != "" && step.RunWhen != wf.RunAlways {
|
||||
shouldRun, skipReason := checkPhaseCondition(step, workflowState, upstreamHash)
|
||||
if !shouldRun {
|
||||
fmt.Fprintf(os.Stderr, "[%s] 跳过 %s: %s\n", wfDef.Name, step.Name, skipReason)
|
||||
results = append(results, wf.StepResult{
|
||||
Step: step.Name,
|
||||
Purpose: step.Purpose,
|
||||
Type: step.Type,
|
||||
OK: true,
|
||||
Skipped: true,
|
||||
SkipReason: skipReason,
|
||||
})
|
||||
continue
|
||||
}
|
||||
}
|
||||
|
||||
sr := ExecuteStep(ctx, step, dryRun)
|
||||
results = append(results, *sr)
|
||||
|
||||
if sr.OK && !sr.Skipped && step.Name == "init-scaffold" && ctx.Repo == "" {
|
||||
if m, ok := sr.Data.(map[string]interface{}); ok {
|
||||
if a, ok := m["analysis"].(map[string]interface{}); ok {
|
||||
if r, ok := a["repo"].(string); ok && r != "" {
|
||||
parts := strings.SplitN(r, "/", 2)
|
||||
if len(parts) == 2 {
|
||||
ctx.Repo = parts[1]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if !dryRun && workflowState != nil && sr.OK && !sr.Skipped {
|
||||
if workflowState.PhaseLastRun == nil {
|
||||
workflowState.PhaseLastRun = make(map[string]string)
|
||||
}
|
||||
workflowState.PhaseLastRun[step.Name] = time.Now().Format(time.RFC3339)
|
||||
if workflowState.PhaseUpstream == nil {
|
||||
workflowState.PhaseUpstream = make(map[string]string)
|
||||
}
|
||||
workflowState.PhaseUpstream[step.Name] = upstreamHash
|
||||
}
|
||||
|
||||
if sr.Data != nil {
|
||||
raw, err := json.Marshal(sr.Data)
|
||||
if err == nil {
|
||||
ctx.Args[step.Name] = string(raw)
|
||||
} else {
|
||||
ctx.Args[step.Name] = fmt.Sprint(sr.Data)
|
||||
}
|
||||
} else if !sr.OK && sr.Error != "" {
|
||||
ctx.Args[step.Name] = fmt.Sprintf(`{"_error": true, "_message": %q}`, sr.Error)
|
||||
}
|
||||
}
|
||||
|
||||
if !dryRun && workflowState != nil {
|
||||
workflowState.Save()
|
||||
}
|
||||
|
||||
return &wf.WorkflowResult{
|
||||
Workflow: wfDef.Name,
|
||||
Owner: ctx.Owner,
|
||||
Repo: ctx.Repo,
|
||||
Steps: results,
|
||||
}, nil
|
||||
}
|
||||
|
||||
func shouldSkipOwnerRepoResolve(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef) bool {
|
||||
if wfDef != nil && wfDef.Name == "project-init" {
|
||||
return true
|
||||
}
|
||||
return isExplicitMultiRepoRun(ctx, wfDef)
|
||||
}
|
||||
|
||||
// IsExplicitMultiRepoRun reports whether this is a multi-repo run with explicit
|
||||
// --repos or --from flags (as opposed to resolving from the current directory).
|
||||
func IsExplicitMultiRepoRun(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef) bool {
|
||||
return isExplicitMultiRepoRun(ctx, wfDef)
|
||||
}
|
||||
|
||||
func isExplicitMultiRepoRun(ctx *common.RuntimeContext, wfDef *wf.WorkflowDef) bool {
|
||||
if wfDef == nil || wfDef.Name != "multi-repo" {
|
||||
return false
|
||||
}
|
||||
return ctx.Arg("repos") != "" || ctx.Arg("from") != ""
|
||||
}
|
||||
|
||||
func checkPhaseCondition(step wf.StepDef, workflowState *state.WorkflowState, upstreamHash string) (bool, string) {
|
||||
switch step.RunWhen {
|
||||
case wf.RunWeekly:
|
||||
last := workflowState.PhaseLastRun[step.Name]
|
||||
if last == "" {
|
||||
return true, ""
|
||||
}
|
||||
t, err := time.Parse(time.RFC3339, last)
|
||||
if err != nil {
|
||||
return true, ""
|
||||
}
|
||||
if time.Since(t) >= 7*24*time.Hour {
|
||||
return true, ""
|
||||
}
|
||||
next := t.Add(7 * 24 * time.Hour)
|
||||
return false, fmt.Sprintf("下次运行: %s", next.Format("01-02 15:04"))
|
||||
case wf.RunOnChange:
|
||||
if prev, ok := workflowState.PhaseUpstream[step.Name]; ok && prev == upstreamHash {
|
||||
return false, "数据无变化"
|
||||
}
|
||||
return true, ""
|
||||
default:
|
||||
return true, ""
|
||||
}
|
||||
}
|
||||
|
|
@ -1,322 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/ai"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/state"
|
||||
)
|
||||
|
||||
func executeSkillStep(ctx *common.RuntimeContext, step wf.StepDef, sr *wf.StepResult, dryRun bool) {
|
||||
upstream := collectUpstream(ctx, step)
|
||||
|
||||
if step.Target == "gitlink-review" {
|
||||
state.EnrichWithPRDiffs(upstream, ctx.Owner, ctx.Repo)
|
||||
state.FilterReviewedPRs(upstream, ctx)
|
||||
}
|
||||
|
||||
if dryRun {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_dry_run": true,
|
||||
"_depends_on": step.DependsOn,
|
||||
"_upstream": upstream,
|
||||
"_hint": "预览模式：展示将要传给 AI/规则引擎 的上游数据，不实际执行。",
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
aiMode := resolveAIMode(ctx)
|
||||
client := ai.NewAIClient()
|
||||
var aiResp *wf.AIResponse
|
||||
var usedAI bool
|
||||
var aiAnalysis interface{}
|
||||
|
||||
switch aiMode {
|
||||
case wf.AIModeNoAI:
|
||||
resp, err := runRuleEngine(step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_needs_ai": true,
|
||||
"_upstream": upstream,
|
||||
"_error": fmt.Sprintf("rule engine failed: %v", err),
|
||||
}
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
|
||||
case wf.AIModeAI:
|
||||
if !client.HasKey() {
|
||||
sr.OK = false
|
||||
sr.Error = "AI 模式需要配置 API Key（设置 DEEPSEEK_API_KEY 环境变量或 config set deepseek_api_key）"
|
||||
return
|
||||
}
|
||||
resp, err := callAI(client, step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("AI 调用失败: %v", err)
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
usedAI = true
|
||||
|
||||
default:
|
||||
if client.HasKey() {
|
||||
resp, err := callAI(client, step, upstream)
|
||||
if err == nil {
|
||||
aiResp = resp
|
||||
usedAI = true
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] AI 调用失败，降级到规则引擎: %v\n", err)
|
||||
}
|
||||
}
|
||||
if aiResp == nil {
|
||||
resp, err := runRuleEngine(step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_needs_ai": true,
|
||||
"_upstream": upstream,
|
||||
"_error": fmt.Sprintf("AI 和规则引擎均失败: %v", err),
|
||||
}
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
}
|
||||
}
|
||||
|
||||
if usedAI && step.Target == "gitlink-triage" {
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil {
|
||||
aiAnalysis = aiResp.Analysis
|
||||
aiResp.Actions = ruleResp.Actions
|
||||
aiResp.Analysis = ruleResp.Analysis
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] triage rule action fallback failed: %v\n", err)
|
||||
}
|
||||
}
|
||||
|
||||
if usedAI && step.Target == "gitlink-init-scaffold" {
|
||||
if suggested := extractRepoNameFromAIAnalysis(aiResp.Analysis); suggested != "" {
|
||||
upstream["_repo"] = suggested
|
||||
}
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil {
|
||||
aiAnalysis = aiResp.Analysis
|
||||
aiResp.Actions = ruleResp.Actions
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] init-scaffold rule fallback failed: %v\n", err)
|
||||
}
|
||||
}
|
||||
|
||||
if usedAI && step.Name == "health-report" {
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil && len(ruleResp.Actions) > 0 {
|
||||
content := ""
|
||||
if s, ok := aiResp.Analysis.(string); ok && s != "" {
|
||||
content = s
|
||||
}
|
||||
if content == "" {
|
||||
if b, err := json.MarshalIndent(aiResp.Analysis, "", " "); err == nil {
|
||||
content = "# 项目健康度报告\n\n" + string(b) + "\n"
|
||||
}
|
||||
}
|
||||
for _, a := range ruleResp.Actions {
|
||||
if a.Module == "wiki" && a.Command == "+create" {
|
||||
if content != "" {
|
||||
a.Args["content"] = content
|
||||
}
|
||||
aiResp.Actions = append(aiResp.Actions, a)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
if usedAI && step.Name == "contributor-ranking" {
|
||||
content := ""
|
||||
if s, ok := aiResp.Analysis.(string); ok {
|
||||
content = s
|
||||
} else if b, err := json.MarshalIndent(aiResp.Analysis, "", " "); err == nil {
|
||||
content = "# 贡献者排行榜\n\n```json\n" + string(b) + "\n```\n"
|
||||
}
|
||||
if content != "" {
|
||||
pageName := "贡献者排行榜 " + time.Now().Format("2006-01-02")
|
||||
aiResp.Actions = append(aiResp.Actions,
|
||||
wf.AIAction{
|
||||
Type: "cli", Module: "wiki", Command: "+create",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": content,
|
||||
"message": "自动生成贡献者排行榜",
|
||||
},
|
||||
},
|
||||
wf.AIAction{
|
||||
Type: "cli", Module: "wiki", Command: "+update",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": content,
|
||||
"message": "自动更新贡献者排行榜",
|
||||
},
|
||||
},
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
if usedAI && step.Name == "multi-repo-coordination" {
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil && len(ruleResp.Actions) > 0 {
|
||||
content := ""
|
||||
if s, ok := aiResp.Analysis.(string); ok && s != "" {
|
||||
content = s
|
||||
}
|
||||
if content == "" {
|
||||
if b, err := json.MarshalIndent(aiResp.Analysis, "", " "); err == nil {
|
||||
content = "# 多仓库协同报告\n\n```json\n" + string(b) + "\n```\n"
|
||||
}
|
||||
}
|
||||
for _, a := range ruleResp.Actions {
|
||||
if a.Module == "wiki" && a.Command == "+create" {
|
||||
if content != "" {
|
||||
a.Args["content"] = content
|
||||
}
|
||||
aiResp.Actions = append(aiResp.Actions, a)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
executed, actionErrors := executeActions(ctx, aiResp.Actions)
|
||||
|
||||
if step.Target == "gitlink-review" && !dryRun {
|
||||
state.SaveReviewedPRFingerprints(upstream, ctx)
|
||||
}
|
||||
|
||||
sr.OK = executed > 0 || len(aiResp.Actions) == 0
|
||||
data := map[string]interface{}{
|
||||
"ok": sr.OK,
|
||||
"analysis": aiResp.Analysis,
|
||||
"executed": executed,
|
||||
"_ai_used": usedAI,
|
||||
"_skill": step.Target,
|
||||
}
|
||||
if len(actionErrors) > 0 {
|
||||
data["errors"] = actionErrors
|
||||
}
|
||||
if aiAnalysis != nil {
|
||||
data["ai_analysis"] = aiAnalysis
|
||||
}
|
||||
sr.Data = data
|
||||
}
|
||||
|
||||
func resolveAIMode(ctx *common.RuntimeContext) wf.AIMode {
|
||||
switch ctx.AIMode {
|
||||
case "ai":
|
||||
return wf.AIModeAI
|
||||
case "no-ai":
|
||||
return wf.AIModeNoAI
|
||||
default:
|
||||
return wf.AIModeAuto
|
||||
}
|
||||
}
|
||||
|
||||
func callAI(client *ai.AIClient, step wf.StepDef, upstream map[string]interface{}) (*wf.AIResponse, error) {
|
||||
skillMD := readSkillDoc(step.Target)
|
||||
upstreamJSON, _ := json.MarshalIndent(upstream, "", " ")
|
||||
return client.Analyze(&wf.AIRequest{
|
||||
SystemPrompt: skillMD,
|
||||
UserData: string(upstreamJSON),
|
||||
})
|
||||
}
|
||||
|
||||
func extractRepoNameFromAIAnalysis(analysis interface{}) string {
|
||||
m, ok := analysis.(map[string]interface{})
|
||||
if !ok {
|
||||
return ""
|
||||
}
|
||||
for _, key := range []string{"repo_name", "repo", "_repo", "name", "suggested_name"} {
|
||||
if v, ok := m[key].(string); ok && v != "" {
|
||||
v = strings.ToLower(strings.TrimSpace(v))
|
||||
v = regexp.MustCompile(`[^a-z0-9-]+`).ReplaceAllString(v, "-")
|
||||
v = regexp.MustCompile(`-+`).ReplaceAllString(v, "-")
|
||||
v = strings.Trim(v, "-")
|
||||
if len(v) >= 2 {
|
||||
return v
|
||||
}
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func runRuleEngine(step wf.StepDef, upstream map[string]interface{}) (*wf.AIResponse, error) {
|
||||
engine, ok := wf.RuleEngines[step.Target]
|
||||
if !ok {
|
||||
return nil, wf.ErrNoRuleEngine(step.Target)
|
||||
}
|
||||
return engine(upstream, step.Name)
|
||||
}
|
||||
|
||||
func collectUpstream(ctx *common.RuntimeContext, step wf.StepDef) map[string]interface{} {
|
||||
upstream := make(map[string]interface{})
|
||||
|
||||
for k, v := range ctx.Args {
|
||||
if strings.HasPrefix(k, "_") {
|
||||
upstream[k] = v
|
||||
}
|
||||
}
|
||||
|
||||
for _, dep := range step.DependsOn {
|
||||
if v, ok := ctx.Args[dep]; ok {
|
||||
var parsed interface{}
|
||||
if err := json.Unmarshal([]byte(v), &parsed); err == nil {
|
||||
upstream[dep] = parsed
|
||||
} else {
|
||||
upstream[dep] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
if len(step.DependsOn) == 0 {
|
||||
for k, v := range ctx.Args {
|
||||
var parsed interface{}
|
||||
if err := json.Unmarshal([]byte(v), &parsed); err == nil {
|
||||
upstream[k] = parsed
|
||||
} else {
|
||||
upstream[k] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
return upstream
|
||||
}
|
||||
|
||||
func readSkillDoc(target string) string {
|
||||
paths := []string{}
|
||||
if exe, err := os.Executable(); err == nil {
|
||||
exeDir := filepath.Dir(exe)
|
||||
paths = append(paths, filepath.Join(exeDir, "skills", target, "SKILL.md"))
|
||||
paths = append(paths, filepath.Join(exeDir, "shortcuts", "workflow", "skills", target, "SKILL.md"))
|
||||
}
|
||||
paths = append(paths,
|
||||
filepath.Join("skills", target, "SKILL.md"),
|
||||
filepath.Join("shortcuts", "workflow", "skills", target, "SKILL.md"),
|
||||
filepath.Join("/etc/gitlink-cli/skills", target, "SKILL.md"),
|
||||
)
|
||||
home, err := os.UserHomeDir()
|
||||
if err == nil {
|
||||
paths = append(paths, filepath.Join(home, ".config", "gitlink-cli", "skills", target, "SKILL.md"))
|
||||
}
|
||||
|
||||
for _, p := range paths {
|
||||
data, err := os.ReadFile(p)
|
||||
if err == nil {
|
||||
return string(data)
|
||||
}
|
||||
}
|
||||
return fmt.Sprintf("# %s\n\nSkill documentation not found.", target)
|
||||
}
|
||||
|
|
@ -1,106 +0,0 @@
|
|||
package engine
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os/exec"
|
||||
"strings"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/snapshot"
|
||||
)
|
||||
|
||||
// ExecuteStep dispatches a step to the right executor based on its Type.
|
||||
func ExecuteStep(ctx *common.RuntimeContext, step wf.StepDef, dryRun bool) *wf.StepResult {
|
||||
sr := &wf.StepResult{
|
||||
Step: step.Name,
|
||||
Purpose: step.Purpose,
|
||||
Type: step.Type,
|
||||
}
|
||||
|
||||
switch step.Type {
|
||||
case wf.StepTypeAPI:
|
||||
executeAPIStep(ctx, step, sr)
|
||||
case wf.StepTypeCommand:
|
||||
executeCommandStep(ctx, step, sr)
|
||||
case wf.StepTypeSkill:
|
||||
executeSkillStep(ctx, step, sr, dryRun)
|
||||
default:
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("unknown step type: %q", step.Type)
|
||||
}
|
||||
return sr
|
||||
}
|
||||
|
||||
func executeAPIStep(ctx *common.RuntimeContext, step wf.StepDef, sr *wf.StepResult) {
|
||||
path := wf.ResolvePath(step.Target, ctx.Owner, ctx.Repo)
|
||||
env, err := ctx.CallAPIWithQuery(step.Method, path, step.Query)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = err.Error()
|
||||
} else {
|
||||
sr.OK = env.OK
|
||||
sr.Data = env.Data
|
||||
}
|
||||
}
|
||||
|
||||
func executeCommandStep(ctx *common.RuntimeContext, step wf.StepDef, sr *wf.StepResult) {
|
||||
if strings.HasPrefix(step.Target, "workflow-internal:") {
|
||||
executeInternalCommandStep(ctx, step, sr)
|
||||
return
|
||||
}
|
||||
|
||||
parts := wf.ParseCommandTarget(step.Target)
|
||||
if len(parts) == 0 {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("empty command target: %q", step.Target)
|
||||
return
|
||||
}
|
||||
|
||||
bin := wf.ResolveCLIBinary()
|
||||
|
||||
args := append(parts, "--format", "json")
|
||||
if ctx.Owner != "" {
|
||||
args = append(args, "--owner", ctx.Owner)
|
||||
}
|
||||
if ctx.Repo != "" {
|
||||
args = append(args, "--repo", ctx.Repo)
|
||||
}
|
||||
|
||||
cmd := exec.Command(bin, args...)
|
||||
cmd.Stderr = nil
|
||||
|
||||
out, err := cmd.Output()
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("command failed: %v", err)
|
||||
return
|
||||
}
|
||||
|
||||
var data interface{}
|
||||
if err := json.Unmarshal(out, &data); err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = strings.TrimSpace(string(out))
|
||||
} else {
|
||||
sr.OK = true
|
||||
sr.Data = data
|
||||
}
|
||||
}
|
||||
|
||||
func executeInternalCommandStep(ctx *common.RuntimeContext, step wf.StepDef, sr *wf.StepResult) {
|
||||
switch strings.TrimPrefix(step.Target, "workflow-internal:") {
|
||||
case "multi-repo-snapshot":
|
||||
snap, err := snapshot.BuildMultiRepoSnapshot(ctx)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = err.Error()
|
||||
return
|
||||
}
|
||||
sr.OK = true
|
||||
sr.Data = snap
|
||||
default:
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("unknown internal workflow command: %q", step.Target)
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
package workflow
|
||||
|
||||
// manifest.go — registration center for all workflow definitions.
|
||||
// Each scenario file defines a register*() function; init() calls them all.
|
||||
// To add a new workflow:
|
||||
// 1. Create a new file in this package (e.g., my_scenario.go)
|
||||
// 2. Define func registerMyScenario() { register(&WorkflowDef{...}) }
|
||||
// 3. Add registerMyScenario() to the init() list below
|
||||
|
||||
func init() {
|
||||
registerCommunityOps()
|
||||
registerCodeQuality()
|
||||
registerProjectInit()
|
||||
registerMultiRepo()
|
||||
registerContributorGrowth()
|
||||
}
|
||||
|
|
@ -1,27 +1,24 @@
|
|||
package defs
|
||||
package workflow
|
||||
|
||||
import wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
|
||||
// RegisterMultiRepo registers the multi-repo workflow definition.
|
||||
func RegisterMultiRepo() {
|
||||
wf.Register(&wf.WorkflowDef{
|
||||
func registerMultiRepo() {
|
||||
register(&WorkflowDef{
|
||||
Name: "multi-repo",
|
||||
Category: "协同",
|
||||
Description: "多仓库协同：跨仓库 Issue/PR 状态看板、Release 协调发布",
|
||||
Trigger: wf.TriggerDef{
|
||||
Trigger: TriggerDef{
|
||||
Type: "cron",
|
||||
On: "0 9 * * 1",
|
||||
Interval: "24h",
|
||||
},
|
||||
Steps: []wf.StepDef{
|
||||
Steps: []StepDef{
|
||||
{
|
||||
Type: wf.StepTypeCommand,
|
||||
Type: StepTypeCommand,
|
||||
Name: "multi-repo-snapshot",
|
||||
Purpose: "采集多个仓库的 Issue/PR/Release/Milestone 状态",
|
||||
Target: "workflow-internal:multi-repo-snapshot",
|
||||
},
|
||||
{
|
||||
Type: wf.StepTypeSkill,
|
||||
Type: StepTypeSkill,
|
||||
Name: "multi-repo-coordination",
|
||||
Purpose: "生成统一 Issue 追踪、PR 看板、Release 协调报告",
|
||||
Target: "gitlink-multi-repo",
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
package snapshot
|
||||
package workflow
|
||||
|
||||
import (
|
||||
"encoding/csv"
|
||||
|
|
@ -11,7 +11,6 @@ import (
|
|||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// MultiRepoSnapshot is a cross-repository state snapshot.
|
||||
type MultiRepoSnapshot struct {
|
||||
Release string `json:"release,omitempty"`
|
||||
Repos []RepoSnapshot `json:"repos"`
|
||||
|
|
@ -19,7 +18,6 @@ type MultiRepoSnapshot struct {
|
|||
Generated string `json:"generated_at"`
|
||||
}
|
||||
|
||||
// RepoSnapshot holds collected data for a single repository.
|
||||
type RepoSnapshot struct {
|
||||
Owner string `json:"owner"`
|
||||
Repo string `json:"repo"`
|
||||
|
|
@ -30,7 +28,6 @@ type RepoSnapshot struct {
|
|||
Milestones interface{} `json:"milestones,omitempty"`
|
||||
}
|
||||
|
||||
// RepoError records an error encountered while collecting repo data.
|
||||
type RepoError struct {
|
||||
Owner string `json:"owner"`
|
||||
Repo string `json:"repo"`
|
||||
|
|
@ -38,9 +35,11 @@ type RepoError struct {
|
|||
Error string `json:"error"`
|
||||
}
|
||||
|
||||
type repoRef = RepoRef
|
||||
type repoRef struct {
|
||||
Owner string
|
||||
Repo string
|
||||
}
|
||||
|
||||
// BuildMultiRepoSnapshot collects Issue/PR/Release/Milestone data for multiple repos.
|
||||
func BuildMultiRepoSnapshot(ctx *common.RuntimeContext) (*MultiRepoSnapshot, error) {
|
||||
repos, err := parseMultiRepoRefs(ctx.Arg("repos"), ctx.Arg("from"))
|
||||
if err != nil {
|
||||
|
|
@ -114,30 +113,6 @@ func collectRepoSnapshot(ctx *common.RuntimeContext, ref repoRef, snap *RepoSnap
|
|||
snap.Milestones = call("milestones", "GET", v1+"/milestones", milestoneQ)
|
||||
}
|
||||
|
||||
// ParseRepoCSV reads repo references from a CSV file.
|
||||
func ParseRepoCSV(path string) ([]RepoRef, error) {
|
||||
refs, err := parseRepoCSV(path)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out := make([]RepoRef, len(refs))
|
||||
for i, r := range refs {
|
||||
out[i] = RepoRef(r)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// ParseMultiRepoRefs parses repo references from a comma-separated string and/or CSV file.
|
||||
func ParseMultiRepoRefs(reposArg, fromPath string) ([]RepoRef, error) {
|
||||
return parseMultiRepoRefs(reposArg, fromPath)
|
||||
}
|
||||
|
||||
// RepoRef is an owner/repo pair.
|
||||
type RepoRef struct {
|
||||
Owner string
|
||||
Repo string
|
||||
}
|
||||
|
||||
func parseMultiRepoRefs(reposArg, fromPath string) ([]repoRef, error) {
|
||||
var refs []repoRef
|
||||
if reposArg != "" {
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
package workflow
|
||||
|
||||
func registerProjectInit() {
|
||||
register(&WorkflowDef{
|
||||
Name: "project-init",
|
||||
Category: "初始化",
|
||||
Description: "项目一键初始化：创建仓库 → 脚手架文件 → 标签/里程碑/Issue → 许可证审计 → 健康报告",
|
||||
Trigger: TriggerDef{
|
||||
Type: "manual",
|
||||
On: "manual",
|
||||
},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeSkill, Name: "init-scaffold", Purpose: "根据描述创建仓库并初始化脚手架（README/LICENSE/.gitignore/标签/里程碑/Issue）", Target: "gitlink-init-scaffold"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "确认仓库已创建并获取基础信息", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "existing-files", Purpose: "验证 README/LICENSE 文件", Target: "file +list"},
|
||||
{Type: StepTypeCommand, Name: "labels", Purpose: "验证标签库", Target: "label +list"},
|
||||
{Type: StepTypeSkill, Name: "license-check", Purpose: "检查许可证合规并扫描敏感信息泄露", Target: "gitlink-license", DependsOn: []string{"existing-files"}},
|
||||
{Type: StepTypeCommand, Name: "milestones", Purpose: "验证里程碑", Target: "milestone +list"},
|
||||
{Type: StepTypeCommand, Name: "existing-issues", Purpose: "验证初始 Issue", Target: "issue +list --state all --limit 10"},
|
||||
{Type: StepTypeCommand, Name: "branches", Purpose: "检查分支结构", Target: "branch +list"},
|
||||
{Type: StepTypeSkill, Name: "repo-audit", Purpose: "综合审计仓库健康度", Target: "gitlink-repo", DependsOn: []string{"repo-info", "existing-files", "labels", "milestones", "branches"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
|
|
@ -1,29 +0,0 @@
|
|||
package workflow
|
||||
|
||||
import "sort"
|
||||
|
||||
var registry = map[string]*WorkflowDef{}
|
||||
|
||||
// Register adds a workflow definition to the global registry.
|
||||
func Register(wf *WorkflowDef) {
|
||||
registry[wf.Name] = wf
|
||||
}
|
||||
|
||||
// All returns all registered workflows sorted by name.
|
||||
func All() []*WorkflowDef {
|
||||
names := make([]string, 0, len(registry))
|
||||
for n := range registry {
|
||||
names = append(names, n)
|
||||
}
|
||||
sort.Strings(names)
|
||||
result := make([]*WorkflowDef, len(names))
|
||||
for i, n := range names {
|
||||
result[i] = registry[n]
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
// Get returns a workflow by name, or nil.
|
||||
func Get(name string) *WorkflowDef {
|
||||
return registry[name]
|
||||
}
|
||||
|
|
@ -298,8 +298,6 @@ func authorLogin(m map[string]interface{}) string {
|
|||
if s := str(a, "login", "username", "name"); s != "" {
|
||||
return s
|
||||
}
|
||||
} else if s, ok := m[key].(string); ok && s != "" {
|
||||
return s
|
||||
}
|
||||
}
|
||||
return ""
|
||||
|
|
|
|||
|
|
@ -93,8 +93,8 @@ func TestContributorOutputFormat(t *testing.T) {
|
|||
if resp.Analysis == nil {
|
||||
t.Fatal("expected non-nil Analysis")
|
||||
}
|
||||
if len(resp.Actions) < 1 {
|
||||
t.Fatal("expected at least 1 wiki action")
|
||||
if resp.Actions != nil {
|
||||
t.Fatal("expected nil Actions (read-only report)")
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -74,29 +74,16 @@ func HealthReportRule(upstream map[string]interface{}, stepName string) (*workfl
|
|||
}
|
||||
// Build wiki page action to publish the report.
|
||||
body := buildHealthReportMarkdown(analysis, upstream)
|
||||
pageName := fmt.Sprintf("健康度报告-%s", now.Format("2006-01-02"))
|
||||
actions := []workflow.AIAction{
|
||||
{
|
||||
Type: "cli",
|
||||
Module: "wiki",
|
||||
Command: "+create",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": body,
|
||||
"message": "自动生成项目健康度报告",
|
||||
},
|
||||
actions := []workflow.AIAction{{
|
||||
Type: "cli",
|
||||
Module: "wiki",
|
||||
Command: "+create",
|
||||
Args: map[string]string{
|
||||
"name": fmt.Sprintf("健康度报告-%s", now.Format("2006-01-02")),
|
||||
"content": body,
|
||||
"message": "自动生成项目健康度报告",
|
||||
},
|
||||
{
|
||||
Type: "cli",
|
||||
Module: "wiki",
|
||||
Command: "+update",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": body,
|
||||
"message": "自动更新项目健康度报告",
|
||||
},
|
||||
},
|
||||
}
|
||||
}}
|
||||
|
||||
return &workflow.AIResponse{Analysis: analysis, Actions: actions}, nil
|
||||
}
|
||||
|
|
|
|||
|
|
@ -58,8 +58,8 @@ func TestHealthReportScoring(t *testing.T) {
|
|||
}
|
||||
}
|
||||
}
|
||||
if len(resp.Actions) != 2 {
|
||||
t.Fatalf("expected 2 wiki actions (create + update), got %d", len(resp.Actions))
|
||||
if len(resp.Actions) != 1 {
|
||||
t.Fatalf("expected 1 wiki action, got %d", len(resp.Actions))
|
||||
}
|
||||
action := resp.Actions[0]
|
||||
if action.Type != "cli" || action.Module != "wiki" || action.Command != "+create" {
|
||||
|
|
|
|||
|
|
@ -1,7 +1,6 @@
|
|||
package rules
|
||||
|
||||
import (
|
||||
"crypto/md5"
|
||||
"encoding/base64"
|
||||
"fmt"
|
||||
"regexp"
|
||||
|
|
@ -238,41 +237,38 @@ func InitScaffoldRule(upstream map[string]interface{}, stepName string) (*workfl
|
|||
return &workflow.AIResponse{Analysis: analysis, Actions: actions}, nil
|
||||
}
|
||||
|
||||
// deriveRepoName generates a short ASCII repo name from a description.
|
||||
// GitLink only allows ASCII letters, digits, underscores, hyphens, and dots
|
||||
// in repo identifiers — Chinese characters are rejected by the API.
|
||||
// deriveRepoName generates a short repo name from a Chinese/English description.
|
||||
func deriveRepoName(desc string) string {
|
||||
// 1. Extract English words first (handles mixed Chinese-English descriptions).
|
||||
// Extract English words first.
|
||||
engWords := extractEnglishWords(desc)
|
||||
if len(engWords) >= 2 {
|
||||
return strings.ToLower(strings.Join(engWords[:min(3, len(engWords))], "-"))
|
||||
}
|
||||
if len(engWords) == 1 {
|
||||
return strings.ToLower(engWords[0])
|
||||
|
||||
// For pure Chinese: take the longest meaningful substring, up to ~20 chars.
|
||||
chinese := extractChinese(desc)
|
||||
if len([]rune(chinese)) > 0 {
|
||||
r := []rune(chinese)
|
||||
if len(r) > 5 {
|
||||
r = r[:5]
|
||||
}
|
||||
return string(r)
|
||||
}
|
||||
|
||||
// 2. Strip non-ASCII characters, then sanitize what remains.
|
||||
ascii := strings.Map(func(r rune) rune {
|
||||
if r < 128 {
|
||||
return r
|
||||
}
|
||||
return -1
|
||||
}, desc)
|
||||
ascii = strings.TrimSpace(ascii)
|
||||
ascii = strings.ToLower(ascii)
|
||||
ascii = regexp.MustCompile(`[^a-z0-9]+`).ReplaceAllString(ascii, "-")
|
||||
ascii = strings.Trim(ascii, "-")
|
||||
|
||||
if len(ascii) >= 2 {
|
||||
if len(ascii) > 30 {
|
||||
ascii = ascii[:30]
|
||||
}
|
||||
return ascii
|
||||
// Fallback: take first 20 chars, sanitize.
|
||||
name := desc
|
||||
if len(name) > 20 {
|
||||
name = name[:20]
|
||||
}
|
||||
|
||||
// 3. No usable ASCII content — use a stable hash-based name.
|
||||
h := md5.Sum([]byte(desc))
|
||||
return fmt.Sprintf("project-%x", h[:4])
|
||||
name = strings.TrimSpace(name)
|
||||
name = strings.ToLower(name)
|
||||
name = regexp.MustCompile(`[^a-z0-9一-鿿-]`).ReplaceAllString(name, "-")
|
||||
name = regexp.MustCompile(`-+`).ReplaceAllString(name, "-")
|
||||
name = strings.Trim(name, "-")
|
||||
if name == "" {
|
||||
return "new-project"
|
||||
}
|
||||
return name
|
||||
}
|
||||
|
||||
func extractEnglishWords(s string) []string {
|
||||
|
|
|
|||
|
|
@ -177,37 +177,7 @@ func MultiRepoCoordinationRule(upstream map[string]interface{}, stepName string)
|
|||
"recommendations": uniqueStrings(recommendations),
|
||||
}
|
||||
|
||||
var actions []workflow.AIAction
|
||||
wikiOwner := mrString(upstream["_wiki_owner"])
|
||||
wikiRepo := mrString(upstream["_wiki_repo"])
|
||||
if wikiOwner != "" && wikiRepo != "" {
|
||||
body := buildMultiRepoMarkdown(analysis)
|
||||
pageName := fmt.Sprintf("多仓库协同报告-%s", now.Format("2006-01-02"))
|
||||
actions = []workflow.AIAction{
|
||||
{
|
||||
Type: "cli", Module: "wiki", Command: "+create",
|
||||
Args: map[string]string{
|
||||
"owner": wikiOwner,
|
||||
"repo": wikiRepo,
|
||||
"name": pageName,
|
||||
"content": body,
|
||||
"message": "自动生成多仓库协同报告",
|
||||
},
|
||||
},
|
||||
{
|
||||
Type: "cli", Module: "wiki", Command: "+update",
|
||||
Args: map[string]string{
|
||||
"owner": wikiOwner,
|
||||
"repo": wikiRepo,
|
||||
"name": pageName,
|
||||
"content": body,
|
||||
"message": "自动更新多仓库协同报告",
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
return &workflow.AIResponse{Analysis: analysis, Actions: actions}, nil
|
||||
return &workflow.AIResponse{Analysis: analysis}, nil
|
||||
}
|
||||
|
||||
func extractMultiRepoSnapshot(upstream map[string]interface{}) (map[string]interface{}, error) {
|
||||
|
|
@ -487,147 +457,3 @@ func uniqueStrings(items []string) []string {
|
|||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func buildMultiRepoMarkdown(analysis map[string]interface{}) string {
|
||||
var b strings.Builder
|
||||
|
||||
title := "多仓库协同报告"
|
||||
if t, ok := analysis["title"].(string); ok && t != "" {
|
||||
title = t
|
||||
}
|
||||
b.WriteString("# ")
|
||||
b.WriteString(title)
|
||||
b.WriteString("\n\n")
|
||||
|
||||
// Summary
|
||||
if summary, ok := analysis["summary"].(map[string]interface{}); ok {
|
||||
target := mrString(summary["target_release"])
|
||||
b.WriteString("## 总览\n\n")
|
||||
b.WriteString("| 指标 | 数值 |\n")
|
||||
b.WriteString("|------|------|\n")
|
||||
fmt.Fprintf(&b, "| 仓库数 | %v |\n", summary["repos"])
|
||||
if target != "" {
|
||||
fmt.Fprintf(&b, "| 目标版本 | %s |\n", target)
|
||||
}
|
||||
fmt.Fprintf(&b, "| 开放 Issue | %v |\n", summary["open_issues"])
|
||||
fmt.Fprintf(&b, "| 阻塞 Issue | %v |\n", summary["blocker_issues"])
|
||||
fmt.Fprintf(&b, "| 超 7 天未更新 Issue | %v |\n", summary["stale_issues_7d"])
|
||||
fmt.Fprintf(&b, "| 高优先级 Issue | %v |\n", summary["high_priority"])
|
||||
fmt.Fprintf(&b, "| 开放 PR | %v |\n", summary["open_prs"])
|
||||
fmt.Fprintf(&b, "| 超 3 天未合并 PR | %v |\n", summary["stale_prs_3d"])
|
||||
fmt.Fprintf(&b, "| 冲突 PR | %v |\n", summary["conflict_prs"])
|
||||
fmt.Fprintf(&b, "| 采集错误 | %v |\n\n", summary["collection_errors"])
|
||||
}
|
||||
|
||||
// Issue tracking by repo
|
||||
if it, ok := analysis["issue_tracking"].(map[string]interface{}); ok {
|
||||
b.WriteString("## Issue 追踪\n\n")
|
||||
if rows, ok := it["by_repo"].([]map[string]interface{}); ok && len(rows) > 0 {
|
||||
b.WriteString("| 仓库 | 开放 | 阻塞 | 超7天 | 高优先级 |\n")
|
||||
b.WriteString("|------|------|------|------|----------|\n")
|
||||
for _, row := range rows {
|
||||
fmt.Fprintf(&b, "| %s | %v | %v | %v | %v |\n",
|
||||
mrString(row["repo"]), row["open"], row["blockers"], row["stale_7d"], row["high_priority"])
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
if details, ok := it["details"].([]map[string]interface{}); ok && len(details) > 0 {
|
||||
b.WriteString("### 需关注的 Issue\n\n")
|
||||
b.WriteString("| 仓库 | 编号 | 标题 | 负责人 | 陈旧(天) | 阻塞 | 高优先级 |\n")
|
||||
b.WriteString("|------|------|------|--------|-----------|------|----------|\n")
|
||||
for _, d := range details {
|
||||
blocker := "否"
|
||||
if v, _ := d["blocker"].(bool); v {
|
||||
blocker = "是"
|
||||
}
|
||||
high := "否"
|
||||
if v, _ := d["high"].(bool); v {
|
||||
high = "是"
|
||||
}
|
||||
fmt.Fprintf(&b, "| %s | %v | %s | %s | %v | %s | %s |\n",
|
||||
mrString(d["repo"]), d["number"], mrString(d["title"]),
|
||||
mrString(d["assignee"]), d["stale_days"], blocker, high)
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
}
|
||||
|
||||
// PR board by repo
|
||||
if pr, ok := analysis["pr_board"].(map[string]interface{}); ok {
|
||||
b.WriteString("## PR 看板\n\n")
|
||||
if rows, ok := pr["by_repo"].([]map[string]interface{}); ok && len(rows) > 0 {
|
||||
b.WriteString("| 仓库 | 开放 | 超3天 | 冲突 | 待审查 |\n")
|
||||
b.WriteString("|------|------|------|------|--------|\n")
|
||||
for _, row := range rows {
|
||||
fmt.Fprintf(&b, "| %s | %v | %v | %v | %v |\n",
|
||||
mrString(row["repo"]), row["open"], row["stale_3d"], row["conflicts"], row["needs_review"])
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
if details, ok := pr["details"].([]map[string]interface{}); ok && len(details) > 0 {
|
||||
b.WriteString("### 需关注的 PR\n\n")
|
||||
b.WriteString("| 仓库 | 编号 | 标题 | 负责人 | 陈旧(天) | 冲突 |\n")
|
||||
b.WriteString("|------|------|------|--------|-----------|------|\n")
|
||||
for _, d := range details {
|
||||
conflict := "否"
|
||||
if v, _ := d["conflict"].(bool); v {
|
||||
conflict = "是"
|
||||
}
|
||||
fmt.Fprintf(&b, "| %s | %v | %s | %s | %v | %s |\n",
|
||||
mrString(d["repo"]), d["number"], mrString(d["title"]),
|
||||
mrString(d["assignee"]), d["stale_days"], conflict)
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
}
|
||||
|
||||
// Release coordination
|
||||
if rc, ok := analysis["release_coordination"].(map[string]interface{}); ok {
|
||||
target := mrString(rc["target"])
|
||||
if target != "" {
|
||||
b.WriteString("## Release 协调\n\n")
|
||||
ready := false
|
||||
if v, ok := rc["ready_to_release"].(bool); ok {
|
||||
ready = v
|
||||
}
|
||||
if ready {
|
||||
b.WriteString("**状态：可以发布**\n\n")
|
||||
} else {
|
||||
b.WriteString("**状态：存在阻塞项**\n\n")
|
||||
}
|
||||
if rows, ok := rc["by_repo"].([]map[string]interface{}); ok && len(rows) > 0 {
|
||||
b.WriteString("| 仓库 | 目标版本 | 已发布 | 阻塞Issue | 冲突/陈旧PR |\n")
|
||||
b.WriteString("|------|----------|--------|-----------|-------------|\n")
|
||||
for _, row := range rows {
|
||||
released := "否"
|
||||
if v, _ := row["already_released"].(bool); v {
|
||||
released = "是"
|
||||
}
|
||||
fmt.Fprintf(&b, "| %s | %s | %s | %v | %v |\n",
|
||||
mrString(row["repo"]), mrString(row["target"]), released,
|
||||
row["blocker_issues"], row["stale_or_conflict_pr"])
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
if blockers, ok := rc["blockers"].([]map[string]interface{}); ok && len(blockers) > 0 {
|
||||
b.WriteString("### 阻塞项\n\n")
|
||||
for _, blk := range blockers {
|
||||
fmt.Fprintf(&b, "- %s\n", mrString(blk["reason"]))
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Recommendations
|
||||
if recs, ok := analysis["recommendations"].([]string); ok && len(recs) > 0 {
|
||||
b.WriteString("## 行动建议\n\n")
|
||||
for _, r := range recs {
|
||||
fmt.Fprintf(&b, "- %s\n", r)
|
||||
}
|
||||
b.WriteString("\n")
|
||||
}
|
||||
|
||||
b.WriteString("> 由 multi-repo 工作流自动生成\n")
|
||||
return b.String()
|
||||
}
|
||||
|
|
|
|||
|
|
@ -17,7 +17,6 @@ func TestRepoAuditComplete(t *testing.T) {
|
|||
},
|
||||
"existing-files": map[string]interface{}{
|
||||
"data": []interface{}{
|
||||
map[string]interface{}{"name": "README.md", "content": "# Project"},
|
||||
map[string]interface{}{"name": "LICENSE", "content": "MIT"},
|
||||
},
|
||||
},
|
||||
|
|
|
|||
|
|
@ -1,36 +0,0 @@
|
|||
# gitlink-init-scaffold
|
||||
|
||||
根据项目描述一键创建仓库并初始化脚手架。
|
||||
|
||||
## 输入
|
||||
|
||||
上游数据（`_desc`）包含项目的自然语言描述。
|
||||
|
||||
## 输出
|
||||
|
||||
```json
|
||||
{
|
||||
"analysis": {
|
||||
"repo": "owner/repo-name",
|
||||
"description": "项目描述",
|
||||
"created": true
|
||||
},
|
||||
"actions": [
|
||||
{"type": "cli", "module": "repo", "command": "+create", "args": {"name": "repo-name", "description": "..."}},
|
||||
{"type": "cli", "module": "file", "command": "+create", "args": {"path": "README.md", "content": "..."}},
|
||||
{"type": "cli", "module": "file", "command": "+create", "args": {"path": "LICENSE", "content": "MIT"}},
|
||||
{"type": "cli", "module": "file", "command": "+create", "args": {"path": ".gitignore", "content": "..."}},
|
||||
{"type": "cli", "module": "label", "command": "+create", "args": {"name": "bug", "color": "#d73a4a"}},
|
||||
{"type": "cli", "module": "milestone", "command": "+create", "args": {"title": "v0.1.0"}},
|
||||
{"type": "cli", "module": "issue", "command": "+create", "args": {"title": "项目初始化", "body": "..."}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 规则
|
||||
|
||||
1. 从 `_desc` 提取英文关键词生成仓库名；若无英文词则用 `_repo` 字段
|
||||
2. 创建 README（项目名 + 描述 + 快速开始）、MIT LICENSE、Go .gitignore
|
||||
3. 创建 7 个默认标签：bug/security/performance/enhancement/refactor/docs/question
|
||||
4. 创建 v0.1.0 里程碑
|
||||
5. 创建 3 个初始 Issue：项目初始化、CI/CD 配置、文档完善
|
||||
|
|
@ -1,38 +0,0 @@
|
|||
package snapshot
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestParseMultiRepoRefs(t *testing.T) {
|
||||
refs, err := ParseMultiRepoRefs("org/backend, org/frontend,org/backend", "")
|
||||
if err != nil {
|
||||
t.Fatalf("ParseMultiRepoRefs failed: %v", err)
|
||||
}
|
||||
if len(refs) != 2 {
|
||||
t.Fatalf("expected 2 deduped refs, got %d: %+v", len(refs), refs)
|
||||
}
|
||||
if refs[0].Owner != "org" || refs[0].Repo != "backend" {
|
||||
t.Fatalf("unexpected first ref: %+v", refs[0])
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseRepoCSV(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "repos.csv")
|
||||
if err := os.WriteFile(path, []byte("owner,repo\norg,backend\norg/frontend\n"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
refs, err := ParseRepoCSV(path)
|
||||
if err != nil {
|
||||
t.Fatalf("ParseRepoCSV failed: %v", err)
|
||||
}
|
||||
if len(refs) != 2 {
|
||||
t.Fatalf("expected 2 refs, got %d", len(refs))
|
||||
}
|
||||
if refs[1].Owner != "org" || refs[1].Repo != "frontend" {
|
||||
t.Fatalf("unexpected second ref: %+v", refs[1])
|
||||
}
|
||||
}
|
||||
|
|
@ -1,4 +1,4 @@
|
|||
package state
|
||||
package workflow
|
||||
|
||||
import (
|
||||
"crypto/md5"
|
||||
|
|
@ -9,20 +9,8 @@ import (
|
|||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/config"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
// WorkflowState tracks persistent run state and change detection snapshots.
|
||||
type WorkflowState struct {
|
||||
Workflow string `json:"workflow"`
|
||||
LastRun string `json:"last_run"`
|
||||
TotalRuns int `json:"total_runs"`
|
||||
Snapshots map[string]string `json:"snapshots"`
|
||||
PhaseLastRun map[string]string `json:"phase_last_run,omitempty"`
|
||||
PhaseUpstream map[string]string `json:"phase_upstream,omitempty"`
|
||||
ReviewedPRs map[string]string `json:"reviewed_prs,omitempty"`
|
||||
}
|
||||
|
||||
// LoadState reads the persisted workflow state from disk.
|
||||
func LoadState(name string) (*WorkflowState, error) {
|
||||
path := statePath(name)
|
||||
|
|
@ -30,9 +18,9 @@ func LoadState(name string) (*WorkflowState, error) {
|
|||
if err != nil {
|
||||
if os.IsNotExist(err) {
|
||||
return &WorkflowState{
|
||||
Workflow: name,
|
||||
Snapshots: make(map[string]string),
|
||||
PhaseLastRun: make(map[string]string),
|
||||
Workflow: name,
|
||||
Snapshots: make(map[string]string),
|
||||
PhaseLastRun: make(map[string]string),
|
||||
PhaseUpstream: make(map[string]string),
|
||||
}, nil
|
||||
}
|
||||
|
|
@ -70,13 +58,14 @@ func (s *WorkflowState) Save() error {
|
|||
}
|
||||
|
||||
// Diff compares current step results against stored snapshots.
|
||||
func (s *WorkflowState) Diff(results []wf.StepResult) []string {
|
||||
// Does NOT mutate snapshots — call UpdateSnapshots separately to persist.
|
||||
func (s *WorkflowState) Diff(results []StepResult) []string {
|
||||
changed := []string{}
|
||||
for _, sr := range results {
|
||||
if !sr.OK || sr.Data == nil {
|
||||
continue
|
||||
}
|
||||
hash := HashData(sr.Data)
|
||||
hash := hashData(sr.Data)
|
||||
if prev, ok := s.Snapshots[sr.Step]; ok && prev != hash {
|
||||
changed = append(changed, sr.Step)
|
||||
}
|
||||
|
|
@ -85,17 +74,17 @@ func (s *WorkflowState) Diff(results []wf.StepResult) []string {
|
|||
}
|
||||
|
||||
// UpdateSnapshots stores hashes of current step results for future diff.
|
||||
func (s *WorkflowState) UpdateSnapshots(results []wf.StepResult) {
|
||||
func (s *WorkflowState) UpdateSnapshots(results []StepResult) {
|
||||
for _, sr := range results {
|
||||
if !sr.OK || sr.Data == nil {
|
||||
continue
|
||||
}
|
||||
s.Snapshots[sr.Step] = HashData(sr.Data)
|
||||
s.Snapshots[sr.Step] = hashData(sr.Data)
|
||||
}
|
||||
}
|
||||
|
||||
// HashData computes an MD5 hash of the JSON-encoded data.
|
||||
func HashData(data interface{}) string {
|
||||
// hashData computes an MD5 hash of the JSON-encoded data.
|
||||
func hashData(data interface{}) string {
|
||||
b, err := json.Marshal(data)
|
||||
if err != nil {
|
||||
return ""
|
||||
|
|
@ -1,231 +0,0 @@
|
|||
package state
|
||||
|
||||
import (
|
||||
"crypto/md5"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"strings"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
// FilterReviewedPRs removes PRs from upstream that were already reviewed
|
||||
// with the same fingerprint, preventing re-review on every poll cycle.
|
||||
func FilterReviewedPRs(upstream map[string]interface{}, ctx *common.RuntimeContext) {
|
||||
wfName := ctx.Arg("__wf_name")
|
||||
if wfName == "" {
|
||||
return
|
||||
}
|
||||
state, err := LoadState(wfName)
|
||||
if err != nil || state == nil {
|
||||
return
|
||||
}
|
||||
if state.ReviewedPRs == nil {
|
||||
state.ReviewedPRs = make(map[string]string)
|
||||
}
|
||||
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
if len(prs) == 0 {
|
||||
return
|
||||
}
|
||||
|
||||
filtered := make([]interface{}, 0, len(prs))
|
||||
skipped := 0
|
||||
for _, pr := range prs {
|
||||
prNum := prNumberFromMap(pr)
|
||||
if prNum == "" {
|
||||
filtered = append(filtered, pr)
|
||||
continue
|
||||
}
|
||||
fp := prFingerprint(pr)
|
||||
if stored, ok := state.ReviewedPRs[prNum]; ok && stored == fp {
|
||||
skipped++
|
||||
continue
|
||||
}
|
||||
filtered = append(filtered, pr)
|
||||
}
|
||||
|
||||
if skipped > 0 {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] 跳过 %d 个已审查的 PR（无变化）\n", skipped)
|
||||
}
|
||||
|
||||
upstream["open-prs"] = map[string]interface{}{"data": filtered}
|
||||
}
|
||||
|
||||
// SaveReviewedPRFingerprints stores PR fingerprints after a successful review.
|
||||
func SaveReviewedPRFingerprints(upstream map[string]interface{}, ctx *common.RuntimeContext) {
|
||||
wfName := ctx.Arg("__wf_name")
|
||||
if wfName == "" {
|
||||
return
|
||||
}
|
||||
state, err := LoadState(wfName)
|
||||
if err != nil || state == nil {
|
||||
return
|
||||
}
|
||||
if state.ReviewedPRs == nil {
|
||||
state.ReviewedPRs = make(map[string]string)
|
||||
}
|
||||
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
for _, pr := range prs {
|
||||
prNum := prNumberFromMap(pr)
|
||||
if prNum == "" {
|
||||
continue
|
||||
}
|
||||
state.ReviewedPRs[prNum] = prFingerprint(pr)
|
||||
}
|
||||
state.Save()
|
||||
}
|
||||
|
||||
// EnrichWithPRDiffs fetches diffs for open PRs and stores them in upstream.
|
||||
func EnrichWithPRDiffs(upstream map[string]interface{}, owner, repo string) {
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
if len(prs) == 0 {
|
||||
return
|
||||
}
|
||||
diffs := make(map[string]string)
|
||||
for _, pr := range prs {
|
||||
status := ""
|
||||
switch v := pr["pull_request_status"].(type) {
|
||||
case string:
|
||||
status = v
|
||||
case float64:
|
||||
if v == 0 {
|
||||
status = "open"
|
||||
}
|
||||
}
|
||||
if status == "" {
|
||||
if s, ok := pr["pull_request_staus"].(string); ok {
|
||||
status = s
|
||||
}
|
||||
}
|
||||
if status != "" && status != "open" {
|
||||
continue
|
||||
}
|
||||
prNum := ""
|
||||
if n, ok := pr["pull_request_number"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["id"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["number"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["pull_request_id"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
}
|
||||
if prNum == "" {
|
||||
continue
|
||||
}
|
||||
bin := wf.ResolveCLIBinary()
|
||||
cmd := exec.Command(bin, "pr", "+diff", "--id", prNum, "--owner", owner, "--repo", repo, "--format", "json")
|
||||
out, err := cmd.Output()
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
var resp struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Files []struct {
|
||||
Sections []struct {
|
||||
Lines []struct {
|
||||
Content string `json:"content"`
|
||||
} `json:"lines"`
|
||||
} `json:"sections"`
|
||||
} `json:"files"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(out, &resp); err != nil || !resp.OK || len(resp.Data.Files) == 0 {
|
||||
continue
|
||||
}
|
||||
var sb strings.Builder
|
||||
for _, f := range resp.Data.Files {
|
||||
for _, sec := range f.Sections {
|
||||
for _, line := range sec.Lines {
|
||||
sb.WriteString(line.Content)
|
||||
sb.WriteString("\n")
|
||||
}
|
||||
}
|
||||
}
|
||||
diffText := sb.String()
|
||||
if diffText == "" {
|
||||
continue
|
||||
}
|
||||
diffs[prNum] = diffText
|
||||
}
|
||||
if len(diffs) > 0 {
|
||||
upstream["_pr_diffs"] = diffs
|
||||
}
|
||||
}
|
||||
|
||||
// prFingerprint returns an MD5 hash of key PR fields for change detection.
|
||||
func prFingerprint(pr map[string]interface{}) string {
|
||||
var parts []string
|
||||
if t := strFromMap(pr, "title", "name"); t != "" {
|
||||
parts = append(parts, "title:"+t)
|
||||
}
|
||||
if b := strFromMap(pr, "body", "description"); b != "" {
|
||||
parts = append(parts, "body:"+b)
|
||||
}
|
||||
if s := strFromMap(pr, "pull_request_status", "pull_request_staus", "status", "state"); s != "" {
|
||||
parts = append(parts, "status:"+s)
|
||||
}
|
||||
h := md5.Sum([]byte(strings.Join(parts, "|")))
|
||||
return hex.EncodeToString(h[:])
|
||||
}
|
||||
|
||||
// prNumberFromMap extracts a PR number string from a PR data map.
|
||||
func prNumberFromMap(pr map[string]interface{}) string {
|
||||
for _, k := range []string{"pull_request_number", "id", "number", "pull_request_id"} {
|
||||
if v := pr[k]; v != nil {
|
||||
s := fmt.Sprintf("%v", v)
|
||||
if s != "" && s != "0" && s != "<nil>" {
|
||||
return s
|
||||
}
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// strFromMap returns the first non-empty string value from the given keys.
|
||||
func strFromMap(m map[string]interface{}, keys ...string) string {
|
||||
for _, k := range keys {
|
||||
if v, ok := m[k].(string); ok && v != "" {
|
||||
return v
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// extractPRListFromUpstream extracts PR list from upstream data.
|
||||
func extractPRListFromUpstream(upstream map[string]interface{}, key string) []map[string]interface{} {
|
||||
raw, ok := upstream[key]
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
if m, ok := raw.(map[string]interface{}); ok {
|
||||
if data, ok := m["data"]; ok {
|
||||
raw = data
|
||||
}
|
||||
}
|
||||
if m, ok := raw.(map[string]interface{}); ok {
|
||||
for _, listKey := range []string{"issues", "pull_requests"} {
|
||||
if v, ok := m[listKey]; ok {
|
||||
if arr, ok := v.([]interface{}); ok {
|
||||
raw = arr
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
list, _ := raw.([]interface{})
|
||||
var out []map[string]interface{}
|
||||
for _, item := range list {
|
||||
if m, ok := item.(map[string]interface{}); ok {
|
||||
out = append(out, m)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
|
@ -1,80 +0,0 @@
|
|||
package state
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
)
|
||||
|
||||
func TestStateSaveLoad(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
t.Setenv("GITLINK_CONFIG_DIR", dir)
|
||||
|
||||
s := &WorkflowState{
|
||||
Workflow: "test-wf",
|
||||
TotalRuns: 5,
|
||||
Snapshots: map[string]string{"step1": "abc123"},
|
||||
}
|
||||
if err := s.Save(); err != nil {
|
||||
t.Fatalf("Save failed: %v", err)
|
||||
}
|
||||
|
||||
loaded, err := LoadState("test-wf")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadState failed: %v", err)
|
||||
}
|
||||
if loaded.TotalRuns != 5 {
|
||||
t.Fatalf("TotalRuns = %d, want 5", loaded.TotalRuns)
|
||||
}
|
||||
if loaded.Snapshots["step1"] != "abc123" {
|
||||
t.Fatalf("Snapshots[step1] = %q, want abc123", loaded.Snapshots["step1"])
|
||||
}
|
||||
|
||||
os.Remove(filepath.Join(dir, "workflow-test-wf-state.json"))
|
||||
}
|
||||
|
||||
func TestStateDiff(t *testing.T) {
|
||||
s := &WorkflowState{
|
||||
Workflow: "test-diff",
|
||||
Snapshots: map[string]string{"step1": "oldhash"},
|
||||
}
|
||||
|
||||
results := []wf.StepResult{
|
||||
{Step: "step1", OK: true, Data: "changed data"},
|
||||
{Step: "step2", OK: true, Data: "new step"},
|
||||
{Step: "step3", OK: false, Data: "ignored"},
|
||||
}
|
||||
|
||||
changed := s.Diff(results)
|
||||
if len(changed) != 1 {
|
||||
t.Fatalf("Diff: expected 1 changed step, got %d", len(changed))
|
||||
}
|
||||
if changed[0] != "step1" {
|
||||
t.Fatalf("Diff: expected 'step1' to change, got %q", changed[0])
|
||||
}
|
||||
s.UpdateSnapshots(results)
|
||||
if _, ok := s.Snapshots["step2"]; !ok {
|
||||
t.Fatal("step2 should be added to snapshots after UpdateSnapshots")
|
||||
}
|
||||
if _, ok := s.Snapshots["step3"]; ok {
|
||||
t.Fatal("step3 (failed) should NOT be added to snapshots")
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadStateNotExist(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
t.Setenv("GITLINK_CONFIG_DIR", dir)
|
||||
|
||||
s, err := LoadState("nonexistent")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadState should not error for missing file: %v", err)
|
||||
}
|
||||
if s.Workflow != "nonexistent" {
|
||||
t.Fatalf("Workflow = %q, want nonexistent", s.Workflow)
|
||||
}
|
||||
if s.Snapshots == nil {
|
||||
t.Fatal("Snapshots should be initialized as empty map")
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,741 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"crypto/md5"
|
||||
"encoding/hex"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// StepResult holds the outcome of executing one step.
|
||||
type StepResult struct {
|
||||
Step string `json:"step"`
|
||||
Purpose string `json:"purpose"`
|
||||
Type StepType `json:"type"`
|
||||
OK bool `json:"ok"`
|
||||
Data interface{} `json:"data,omitempty"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Skipped bool `json:"skipped,omitempty"`
|
||||
SkipReason string `json:"skip_reason,omitempty"`
|
||||
}
|
||||
|
||||
// ExecuteStep dispatches a step to the right executor based on its Type.
|
||||
func ExecuteStep(ctx *common.RuntimeContext, step StepDef, dryRun bool) *StepResult {
|
||||
sr := &StepResult{
|
||||
Step: step.Name,
|
||||
Purpose: step.Purpose,
|
||||
Type: step.Type,
|
||||
}
|
||||
|
||||
switch step.Type {
|
||||
case StepTypeAPI:
|
||||
executeAPIStep(ctx, step, sr)
|
||||
case StepTypeCommand:
|
||||
executeCommandStep(ctx, step, sr)
|
||||
case StepTypeSkill:
|
||||
executeSkillStep(ctx, step, sr, dryRun)
|
||||
default:
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("unknown step type: %q", step.Type)
|
||||
}
|
||||
return sr
|
||||
}
|
||||
|
||||
// executeAPIStep makes an HTTP call through the API client.
|
||||
func executeAPIStep(ctx *common.RuntimeContext, step StepDef, sr *StepResult) {
|
||||
path := resolvePath(step.Target, ctx.Owner, ctx.Repo)
|
||||
env, err := ctx.CallAPIWithQuery(step.Method, path, step.Query)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = err.Error()
|
||||
} else {
|
||||
sr.OK = env.OK
|
||||
sr.Data = env.Data
|
||||
}
|
||||
}
|
||||
|
||||
// executeCommandStep runs a gitlink-cli subcommand as a subprocess.
|
||||
func executeCommandStep(ctx *common.RuntimeContext, step StepDef, sr *StepResult) {
|
||||
if strings.HasPrefix(step.Target, "workflow-internal:") {
|
||||
executeInternalCommandStep(ctx, step, sr)
|
||||
return
|
||||
}
|
||||
|
||||
parts := parseCommandTarget(step.Target)
|
||||
if len(parts) == 0 {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("empty command target: %q", step.Target)
|
||||
return
|
||||
}
|
||||
|
||||
bin, err := os.Executable()
|
||||
if err != nil {
|
||||
bin = "gitlink-cli"
|
||||
}
|
||||
|
||||
args := append(parts, "--format", "json")
|
||||
if ctx.Owner != "" {
|
||||
args = append(args, "--owner", ctx.Owner)
|
||||
}
|
||||
if ctx.Repo != "" {
|
||||
args = append(args, "--repo", ctx.Repo)
|
||||
}
|
||||
|
||||
cmd := exec.Command(bin, args...)
|
||||
cmd.Stderr = nil
|
||||
|
||||
out, err := cmd.Output()
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("command failed: %v", err)
|
||||
return
|
||||
}
|
||||
|
||||
var data interface{}
|
||||
if err := json.Unmarshal(out, &data); err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = strings.TrimSpace(string(out))
|
||||
} else {
|
||||
sr.OK = true
|
||||
sr.Data = data
|
||||
}
|
||||
}
|
||||
|
||||
func executeInternalCommandStep(ctx *common.RuntimeContext, step StepDef, sr *StepResult) {
|
||||
switch strings.TrimPrefix(step.Target, "workflow-internal:") {
|
||||
case "multi-repo-snapshot":
|
||||
snapshot, err := BuildMultiRepoSnapshot(ctx)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = err.Error()
|
||||
return
|
||||
}
|
||||
sr.OK = true
|
||||
sr.Data = snapshot
|
||||
default:
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("unknown internal workflow command: %q", step.Target)
|
||||
}
|
||||
}
|
||||
|
||||
// executeSkillStep runs a skill step. Depending on aiMode, it uses the AI API or
|
||||
// falls back to a deterministic rule engine. Both paths produce the same AIResponse
|
||||
// format, and actions from either source go through the same security whitelist.
|
||||
func executeSkillStep(ctx *common.RuntimeContext, step StepDef, sr *StepResult, dryRun bool) {
|
||||
upstream := collectUpstream(ctx, step)
|
||||
|
||||
// For review step, fetch PR diffs and filter already-reviewed PRs.
|
||||
if step.Target == "gitlink-review" {
|
||||
enrichWithPRDiffs(upstream, ctx.Owner, ctx.Repo)
|
||||
filterReviewedPRs(upstream, ctx)
|
||||
}
|
||||
|
||||
if dryRun {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_dry_run": true,
|
||||
"_depends_on": step.DependsOn,
|
||||
"_upstream": upstream,
|
||||
"_hint": "预览模式：展示将要传给 AI/规则引擎 的上游数据，不实际执行。",
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
aiMode := resolveAIMode(ctx)
|
||||
client := NewAIClient()
|
||||
var aiResp *AIResponse
|
||||
var usedAI bool
|
||||
var aiAnalysis interface{}
|
||||
|
||||
switch aiMode {
|
||||
case AIModeNoAI:
|
||||
resp, err := runRuleEngine(step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_needs_ai": true,
|
||||
"_upstream": upstream,
|
||||
"_error": fmt.Sprintf("rule engine failed: %v", err),
|
||||
}
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
|
||||
case AIModeAI:
|
||||
if !client.HasKey() {
|
||||
sr.OK = false
|
||||
sr.Error = "AI 模式需要配置 API Key（设置 DEEPSEEK_API_KEY 环境变量或 config set deepseek_api_key）"
|
||||
return
|
||||
}
|
||||
resp, err := callAI(client, step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = false
|
||||
sr.Error = fmt.Sprintf("AI 调用失败: %v", err)
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
usedAI = true
|
||||
|
||||
default: // "auto"
|
||||
if client.HasKey() {
|
||||
resp, err := callAI(client, step, upstream)
|
||||
if err == nil {
|
||||
aiResp = resp
|
||||
usedAI = true
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] AI 调用失败，降级到规则引擎: %v\n", err)
|
||||
}
|
||||
}
|
||||
if aiResp == nil {
|
||||
resp, err := runRuleEngine(step, upstream)
|
||||
if err != nil {
|
||||
sr.OK = true
|
||||
sr.Data = map[string]interface{}{
|
||||
"_skill": step.Target,
|
||||
"_needs_ai": true,
|
||||
"_upstream": upstream,
|
||||
"_error": fmt.Sprintf("AI 和规则引擎均失败: %v", err),
|
||||
}
|
||||
return
|
||||
}
|
||||
aiResp = resp
|
||||
}
|
||||
}
|
||||
if usedAI && step.Target == "gitlink-triage" {
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil {
|
||||
// Triage write actions must be deterministic: AI may explain, but
|
||||
// labels/assignees/comments and UI counts come from the tested rule engine.
|
||||
aiAnalysis = aiResp.Analysis
|
||||
aiResp.Actions = ruleResp.Actions
|
||||
aiResp.Analysis = ruleResp.Analysis
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] triage rule action fallback failed: %v\n", err)
|
||||
}
|
||||
}
|
||||
// In AI mode, supplement health-report with deterministic wiki action.
|
||||
// AI provides richer semantic analysis; rule engine ensures wiki publishing.
|
||||
if usedAI && step.Name == "health-report" {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] health-report AI supplement: upstream_keys=%v\n", mapKeys(upstream))
|
||||
if ruleResp, err := runRuleEngine(step, upstream); err == nil && len(ruleResp.Actions) > 0 {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] health-report rule engine returned %d actions\n", len(ruleResp.Actions))
|
||||
content := ""
|
||||
if s, ok := aiResp.Analysis.(string); ok && s != "" {
|
||||
content = s
|
||||
}
|
||||
if content == "" {
|
||||
if b, err := json.MarshalIndent(aiResp.Analysis, "", " "); err == nil {
|
||||
content = "# 项目健康度报告\n\n" + string(b) + "\n"
|
||||
}
|
||||
}
|
||||
// Rewrite the rule engine's wiki +create with AI-enhanced content.
|
||||
for _, a := range ruleResp.Actions {
|
||||
if a.Module == "wiki" && a.Command == "+create" {
|
||||
if content != "" {
|
||||
a.Args["content"] = content
|
||||
}
|
||||
aiResp.Actions = append(aiResp.Actions, a)
|
||||
}
|
||||
}
|
||||
} else {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] health-report rule engine failed or empty: err=%v actions=%d\n", err, len(ruleResp.Actions))
|
||||
}
|
||||
}
|
||||
// Supplement AI responses with wiki publishing so the full pipeline runs.
|
||||
if usedAI && step.Name == "contributor-ranking" {
|
||||
content := ""
|
||||
if s, ok := aiResp.Analysis.(string); ok {
|
||||
content = s
|
||||
} else if b, err := json.MarshalIndent(aiResp.Analysis, "", " "); err == nil {
|
||||
content = "# 贡献者排行榜\n\n```json\n" + string(b) + "\n```\n"
|
||||
}
|
||||
if content != "" {
|
||||
pageName := "贡献者排行榜 " + time.Now().Format("2006-01-02")
|
||||
aiResp.Actions = append(aiResp.Actions,
|
||||
AIAction{
|
||||
Type: "cli", Module: "wiki", Command: "+create",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": content,
|
||||
"message": "自动生成贡献者排行榜",
|
||||
},
|
||||
},
|
||||
AIAction{
|
||||
Type: "cli", Module: "wiki", Command: "+update",
|
||||
Args: map[string]string{
|
||||
"name": pageName,
|
||||
"content": content,
|
||||
"message": "自动更新贡献者排行榜",
|
||||
},
|
||||
},
|
||||
)
|
||||
}
|
||||
}
|
||||
|
||||
executed := executeActions(ctx, aiResp.Actions)
|
||||
|
||||
// After review, save PR fingerprints so we skip them next poll.
|
||||
if step.Target == "gitlink-review" && !dryRun {
|
||||
saveReviewedPRFingerprints(upstream, ctx)
|
||||
}
|
||||
|
||||
sr.OK = true
|
||||
data := map[string]interface{}{
|
||||
"ok": true,
|
||||
"analysis": aiResp.Analysis,
|
||||
"executed": executed,
|
||||
"_ai_used": usedAI,
|
||||
"_skill": step.Target,
|
||||
}
|
||||
if aiAnalysis != nil {
|
||||
data["ai_analysis"] = aiAnalysis
|
||||
}
|
||||
sr.Data = data
|
||||
}
|
||||
|
||||
// executeActions runs allowed actions from an AIResponse. Returns count of
|
||||
// successfully executed actions. Actions from both AI and rule engines pass
|
||||
// through the same security whitelist.
|
||||
func executeActions(ctx *common.RuntimeContext, actions []AIAction) int {
|
||||
executed := 0
|
||||
seen := make(map[string]bool, len(actions))
|
||||
for _, action := range actions {
|
||||
key := actionKey(action)
|
||||
if seen[key] {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] skipped duplicate action: %s %s %s\n", action.Type, action.Module, action.Command)
|
||||
continue
|
||||
}
|
||||
seen[key] = true
|
||||
if !isActionAllowed(action) {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] blocked action: %s %s +%s\n", action.Type, action.Module, action.Command)
|
||||
continue
|
||||
}
|
||||
if action.Type == "api" {
|
||||
path := resolvePath(action.Path, ctx.Owner, ctx.Repo)
|
||||
_, err := ctx.CallAPI(action.Method, path, action.Body)
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] api action failed: %v\n", err)
|
||||
continue
|
||||
}
|
||||
executed++
|
||||
} else if action.Type == "cli" {
|
||||
args := []string{action.Module, action.Command}
|
||||
for k, v := range action.Args {
|
||||
args = append(args, "--"+k, v)
|
||||
}
|
||||
args = append(args, "--owner", ctx.Owner, "--repo", ctx.Repo)
|
||||
bin, _ := os.Executable()
|
||||
if bin == "" {
|
||||
bin = "gitlink-cli"
|
||||
}
|
||||
err := exec.Command(bin, args...).Run()
|
||||
if err != nil {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] cli action failed: %v\n", err)
|
||||
continue
|
||||
}
|
||||
executed++
|
||||
}
|
||||
}
|
||||
return executed
|
||||
}
|
||||
|
||||
func actionKey(action AIAction) string {
|
||||
raw, err := json.Marshal(action)
|
||||
if err != nil {
|
||||
return fmt.Sprintf("%s:%s:%s:%v:%s:%s", action.Type, action.Module, action.Command, action.Args, action.Method, action.Path)
|
||||
}
|
||||
sum := md5.Sum(raw)
|
||||
return hex.EncodeToString(sum[:])
|
||||
}
|
||||
|
||||
// resolveAIMode determines the effective AI mode from the context.
|
||||
func resolveAIMode(ctx *common.RuntimeContext) AIMode {
|
||||
switch ctx.AIMode {
|
||||
case "ai":
|
||||
return AIModeAI
|
||||
case "no-ai":
|
||||
return AIModeNoAI
|
||||
default:
|
||||
return AIModeAuto
|
||||
}
|
||||
}
|
||||
|
||||
// callAI invokes the Anthropic API for a skill step.
|
||||
func callAI(client *AIClient, step StepDef, upstream map[string]interface{}) (*AIResponse, error) {
|
||||
skillMD := readSkillDoc(step.Target)
|
||||
upstreamJSON, _ := json.MarshalIndent(upstream, "", " ")
|
||||
return client.Analyze(&AIRequest{
|
||||
SystemPrompt: skillMD,
|
||||
UserData: string(upstreamJSON),
|
||||
})
|
||||
}
|
||||
|
||||
// runRuleEngine looks up and invokes the rule engine for a skill target.
|
||||
func runRuleEngine(step StepDef, upstream map[string]interface{}) (*AIResponse, error) {
|
||||
engine, ok := RuleEngines[step.Target]
|
||||
if !ok {
|
||||
return nil, ErrNoRuleEngine(step.Target)
|
||||
}
|
||||
return engine(upstream, step.Name)
|
||||
}
|
||||
|
||||
// collectUpstream gathers data from steps declared in DependsOn.
|
||||
func collectUpstream(ctx *common.RuntimeContext, step StepDef) map[string]interface{} {
|
||||
upstream := make(map[string]interface{})
|
||||
for _, dep := range step.DependsOn {
|
||||
if v, ok := ctx.Args[dep]; ok {
|
||||
var parsed interface{}
|
||||
if err := json.Unmarshal([]byte(v), &parsed); err == nil {
|
||||
upstream[dep] = parsed
|
||||
} else {
|
||||
upstream[dep] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
// If no DependsOn, collect all available upstream data.
|
||||
if len(step.DependsOn) == 0 {
|
||||
for k, v := range ctx.Args {
|
||||
var parsed interface{}
|
||||
if err := json.Unmarshal([]byte(v), &parsed); err == nil {
|
||||
upstream[k] = parsed
|
||||
} else {
|
||||
upstream[k] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
return upstream
|
||||
}
|
||||
|
||||
// readSkillDoc reads the full SKILL.md for a given skill name.
|
||||
func readSkillDoc(target string) string {
|
||||
paths := []string{}
|
||||
if exe, err := os.Executable(); err == nil {
|
||||
paths = append(paths, filepath.Join(filepath.Dir(exe), "skills", target, "SKILL.md"))
|
||||
}
|
||||
paths = append(paths,
|
||||
filepath.Join("skills", target, "SKILL.md"),
|
||||
filepath.Join("/etc/gitlink-cli/skills", target, "SKILL.md"),
|
||||
)
|
||||
home, err := os.UserHomeDir()
|
||||
if err == nil {
|
||||
paths = append(paths, filepath.Join(home, ".config", "gitlink-cli", "skills", target, "SKILL.md"))
|
||||
}
|
||||
|
||||
for _, p := range paths {
|
||||
data, err := os.ReadFile(p)
|
||||
if err == nil {
|
||||
return string(data)
|
||||
}
|
||||
}
|
||||
return fmt.Sprintf("# %s\n\nSkill documentation not found.", target)
|
||||
}
|
||||
|
||||
// Security whitelist for AI-generated actions.
|
||||
|
||||
var allowedAPIMethods = map[string]bool{
|
||||
"GET": true, "POST": true, "PATCH": true,
|
||||
}
|
||||
|
||||
var allowedCLIModules = map[string]bool{
|
||||
"issue": true, "pr": true, "release": true,
|
||||
"wiki": true, "member": true, "label": true,
|
||||
"milestone": true, "branch": true, "comment": true,
|
||||
"repo": true, "file": true,
|
||||
}
|
||||
|
||||
var blockedCLICommands = map[string]bool{
|
||||
"+delete": true, "+remove": true, "+batch-delete": true,
|
||||
"+fork": true, "+batch-fork": true,
|
||||
}
|
||||
|
||||
func isActionAllowed(action AIAction) bool {
|
||||
if action.Type == "api" {
|
||||
if !allowedAPIMethods[action.Method] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
if action.Type == "cli" {
|
||||
if !allowedCLIModules[action.Module] {
|
||||
return false
|
||||
}
|
||||
if blockedCLICommands[action.Command] {
|
||||
return false
|
||||
}
|
||||
}
|
||||
return true
|
||||
}
|
||||
|
||||
// parseCommandTarget splits a CLI command string into tokens,
|
||||
// respecting quoted arguments.
|
||||
func mapKeys(m map[string]interface{}) []string {
|
||||
keys := make([]string, 0, len(m))
|
||||
for k := range m {
|
||||
keys = append(keys, k)
|
||||
}
|
||||
return keys
|
||||
}
|
||||
|
||||
func parseCommandTarget(target string) []string {
|
||||
var parts []string
|
||||
var current strings.Builder
|
||||
inQuote := false
|
||||
quoteChar := byte(0)
|
||||
|
||||
for i := 0; i < len(target); i++ {
|
||||
c := target[i]
|
||||
switch {
|
||||
case c == '"' || c == '\'':
|
||||
if inQuote && c == quoteChar {
|
||||
inQuote = false
|
||||
quoteChar = 0
|
||||
} else if !inQuote {
|
||||
inQuote = true
|
||||
quoteChar = c
|
||||
} else {
|
||||
current.WriteByte(c)
|
||||
}
|
||||
case c == ' ' && !inQuote:
|
||||
if current.Len() > 0 {
|
||||
parts = append(parts, current.String())
|
||||
current.Reset()
|
||||
}
|
||||
default:
|
||||
current.WriteByte(c)
|
||||
}
|
||||
}
|
||||
if current.Len() > 0 {
|
||||
parts = append(parts, current.String())
|
||||
}
|
||||
return parts
|
||||
}
|
||||
|
||||
// filterReviewedPRs removes PRs from upstream that were already reviewed
|
||||
// with the same fingerprint, preventing re-review on every poll cycle.
|
||||
func filterReviewedPRs(upstream map[string]interface{}, ctx *common.RuntimeContext) {
|
||||
wfName := ctx.Arg("__wf_name")
|
||||
if wfName == "" {
|
||||
return
|
||||
}
|
||||
state, err := LoadState(wfName)
|
||||
if err != nil || state == nil {
|
||||
return
|
||||
}
|
||||
if state.ReviewedPRs == nil {
|
||||
state.ReviewedPRs = make(map[string]string)
|
||||
}
|
||||
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
if len(prs) == 0 {
|
||||
return
|
||||
}
|
||||
|
||||
filtered := make([]interface{}, 0, len(prs))
|
||||
skipped := 0
|
||||
for _, pr := range prs {
|
||||
prNum := prNumberFromMap(pr)
|
||||
if prNum == "" {
|
||||
filtered = append(filtered, pr)
|
||||
continue
|
||||
}
|
||||
fp := prFingerprint(pr)
|
||||
if stored, ok := state.ReviewedPRs[prNum]; ok && stored == fp {
|
||||
skipped++
|
||||
continue
|
||||
}
|
||||
filtered = append(filtered, pr)
|
||||
}
|
||||
|
||||
if skipped > 0 {
|
||||
fmt.Fprintf(os.Stderr, "[workflow] 跳过 %d 个已审查的 PR（无变化）\n", skipped)
|
||||
}
|
||||
|
||||
upstream["open-prs"] = map[string]interface{}{"data": filtered}
|
||||
}
|
||||
|
||||
// saveReviewedPRFingerprints stores PR fingerprints after a successful review.
|
||||
func saveReviewedPRFingerprints(upstream map[string]interface{}, ctx *common.RuntimeContext) {
|
||||
wfName := ctx.Arg("__wf_name")
|
||||
if wfName == "" {
|
||||
return
|
||||
}
|
||||
state, err := LoadState(wfName)
|
||||
if err != nil || state == nil {
|
||||
return
|
||||
}
|
||||
if state.ReviewedPRs == nil {
|
||||
state.ReviewedPRs = make(map[string]string)
|
||||
}
|
||||
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
for _, pr := range prs {
|
||||
prNum := prNumberFromMap(pr)
|
||||
if prNum == "" {
|
||||
continue
|
||||
}
|
||||
state.ReviewedPRs[prNum] = prFingerprint(pr)
|
||||
}
|
||||
state.Save()
|
||||
}
|
||||
|
||||
// prFingerprint returns an MD5 hash of key PR fields for change detection.
|
||||
func prFingerprint(pr map[string]interface{}) string {
|
||||
var parts []string
|
||||
if t := strFromMap(pr, "title", "name"); t != "" {
|
||||
parts = append(parts, "title:"+t)
|
||||
}
|
||||
if b := strFromMap(pr, "body", "description"); b != "" {
|
||||
parts = append(parts, "body:"+b)
|
||||
}
|
||||
if s := strFromMap(pr, "pull_request_status", "pull_request_staus", "status", "state"); s != "" {
|
||||
parts = append(parts, "status:"+s)
|
||||
}
|
||||
h := md5.Sum([]byte(strings.Join(parts, "|")))
|
||||
return hex.EncodeToString(h[:])
|
||||
}
|
||||
|
||||
// prNumberFromMap extracts a PR number string from a PR data map.
|
||||
func prNumberFromMap(pr map[string]interface{}) string {
|
||||
for _, k := range []string{"pull_request_number", "id", "number", "pull_request_id"} {
|
||||
if v := pr[k]; v != nil {
|
||||
s := fmt.Sprintf("%v", v)
|
||||
if s != "" && s != "0" && s != "<nil>" {
|
||||
return s
|
||||
}
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// strFromMap returns the first non-empty string value from the given keys.
|
||||
func strFromMap(m map[string]interface{}, keys ...string) string {
|
||||
for _, k := range keys {
|
||||
if v, ok := m[k].(string); ok && v != "" {
|
||||
return v
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// extractPRListFromUpstream extracts PR list from upstream data.
|
||||
func extractPRListFromUpstream(upstream map[string]interface{}, key string) []map[string]interface{} {
|
||||
raw, ok := upstream[key]
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
if m, ok := raw.(map[string]interface{}); ok {
|
||||
if data, ok := m["data"]; ok {
|
||||
raw = data
|
||||
}
|
||||
}
|
||||
if m, ok := raw.(map[string]interface{}); ok {
|
||||
for _, listKey := range []string{"issues", "pull_requests"} {
|
||||
if v, ok := m[listKey]; ok {
|
||||
if arr, ok := v.([]interface{}); ok {
|
||||
raw = arr
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
list, _ := raw.([]interface{})
|
||||
var out []map[string]interface{}
|
||||
for _, item := range list {
|
||||
if m, ok := item.(map[string]interface{}); ok {
|
||||
out = append(out, m)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// enrichWithPRDiffs fetches diffs for open PRs and stores them in upstream
|
||||
// so that both AI and the rule engine can analyze actual code changes.
|
||||
func enrichWithPRDiffs(upstream map[string]interface{}, owner, repo string) {
|
||||
prs := extractPRListFromUpstream(upstream, "open-prs")
|
||||
if len(prs) == 0 {
|
||||
return
|
||||
}
|
||||
diffs := make(map[string]string)
|
||||
for _, pr := range prs {
|
||||
// pull_request_status may be numeric (0=open, 1=merged, 2=closed) or string.
|
||||
// The API also uses the typo key "pull_request_staus".
|
||||
status := ""
|
||||
switch v := pr["pull_request_status"].(type) {
|
||||
case string:
|
||||
status = v
|
||||
case float64:
|
||||
if v == 0 {
|
||||
status = "open"
|
||||
}
|
||||
}
|
||||
if status == "" {
|
||||
if s, ok := pr["pull_request_staus"].(string); ok {
|
||||
status = s
|
||||
}
|
||||
}
|
||||
if status != "" && status != "open" {
|
||||
continue
|
||||
}
|
||||
prNum := ""
|
||||
if n, ok := pr["pull_request_number"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["id"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["number"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
} else if n, ok := pr["pull_request_id"]; ok {
|
||||
prNum = fmt.Sprintf("%v", n)
|
||||
}
|
||||
if prNum == "" {
|
||||
continue
|
||||
}
|
||||
bin, _ := os.Executable()
|
||||
if bin == "" {
|
||||
bin = "gitlink-cli"
|
||||
}
|
||||
cmd := exec.Command(bin, "pr", "+diff", "--id", prNum, "--owner", owner, "--repo", repo, "--format", "json")
|
||||
out, err := cmd.Output()
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
var resp struct {
|
||||
OK bool `json:"ok"`
|
||||
Data struct {
|
||||
Files []struct {
|
||||
Sections []struct {
|
||||
Lines []struct {
|
||||
Content string `json:"content"`
|
||||
} `json:"lines"`
|
||||
} `json:"sections"`
|
||||
} `json:"files"`
|
||||
} `json:"data"`
|
||||
}
|
||||
if err := json.Unmarshal(out, &resp); err != nil || !resp.OK || len(resp.Data.Files) == 0 {
|
||||
continue
|
||||
}
|
||||
var sb strings.Builder
|
||||
for _, f := range resp.Data.Files {
|
||||
for _, sec := range f.Sections {
|
||||
for _, line := range sec.Lines {
|
||||
sb.WriteString(line.Content)
|
||||
sb.WriteString("\n")
|
||||
}
|
||||
}
|
||||
}
|
||||
diffText := sb.String()
|
||||
if diffText == "" {
|
||||
continue
|
||||
}
|
||||
diffs[prNum] = diffText
|
||||
}
|
||||
if len(diffs) > 0 {
|
||||
upstream["_pr_diffs"] = diffs
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,130 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
// Watch polls the first step (or watchStep) every interval and triggers the
|
||||
// full workflow (with AI) only when data changes. Blocks until Ctrl+C.
|
||||
func Watch(ctx *common.RuntimeContext, wf *WorkflowDef, interval time.Duration, watchStep string) error {
|
||||
if watchStep == "" && len(wf.Steps) > 0 {
|
||||
watchStep = wf.Steps[0].Name
|
||||
}
|
||||
|
||||
fmt.Printf("👀 Watching %s/%s for %q changes every %v\n", ctx.Owner, ctx.Repo, watchStep, interval)
|
||||
fmt.Printf(" Trigger: %s on %s\n", wf.Trigger.Type, wf.Trigger.On)
|
||||
fmt.Println(" Press Ctrl+C to stop")
|
||||
|
||||
sig := make(chan os.Signal, 1)
|
||||
signal.Notify(sig, os.Interrupt)
|
||||
|
||||
state, _ := LoadState(wf.Name)
|
||||
tick := time.NewTicker(interval)
|
||||
defer tick.Stop()
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-sig:
|
||||
fmt.Println("\n👋 watch stopped")
|
||||
return nil
|
||||
case t := <-tick.C:
|
||||
// Phase 1: cheap dry-run to check for changes
|
||||
dryResult, err := Run(ctx, wf, true)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
changed := state.Diff(dryResult.Steps)
|
||||
if len(changed) == 0 && state.TotalRuns > 0 {
|
||||
fmt.Printf("[%s] ✓ no changes\n", t.Format("15:04:05"))
|
||||
continue
|
||||
}
|
||||
|
||||
fmt.Printf("[%s] 🔔 change detected: %v\n", t.Format("15:04:05"), changed)
|
||||
|
||||
// Phase 2: full run with AI
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ AI run error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
state.UpdateSnapshots(result.Steps)
|
||||
state.TotalRuns++
|
||||
state.Save()
|
||||
|
||||
for _, sr := range result.Steps {
|
||||
if sr.OK {
|
||||
fmt.Printf(" ✓ %s\n", sr.Step)
|
||||
} else {
|
||||
fmt.Printf(" ✗ %s: %s\n", sr.Step, sr.Error)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Schedule runs the full workflow on a repeating interval. Blocks until Ctrl+C.
|
||||
// Schedule always runs with AI (cron-style workflows like weekly reports always need fresh output).
|
||||
func Schedule(ctx *common.RuntimeContext, wf *WorkflowDef, interval time.Duration) error {
|
||||
fmt.Printf("⏰ Scheduled %q every %v on %s/%s\n", wf.Name, interval, ctx.Owner, ctx.Repo)
|
||||
fmt.Println(" Press Ctrl+C to stop")
|
||||
|
||||
sig := make(chan os.Signal, 1)
|
||||
signal.Notify(sig, os.Interrupt)
|
||||
tick := time.NewTicker(interval)
|
||||
defer tick.Stop()
|
||||
|
||||
// Run immediately on start (dry-run to establish baseline)
|
||||
state, _ := LoadState(wf.Name)
|
||||
dryResult, _ := Run(ctx, wf, true)
|
||||
state.UpdateSnapshots(dryResult.Steps)
|
||||
state.TotalRuns++
|
||||
state.Save()
|
||||
|
||||
for {
|
||||
select {
|
||||
case <-sig:
|
||||
fmt.Println("\n👋 schedule stopped")
|
||||
return nil
|
||||
case t := <-tick.C:
|
||||
// Phase 1: dry-run to check for changes
|
||||
dryResult, err := Run(ctx, wf, true)
|
||||
if err != nil {
|
||||
fmt.Printf("[%s] ❌ error: %v\n", t.Format("15:04:05"), err)
|
||||
continue
|
||||
}
|
||||
|
||||
changed := state.Diff(dryResult.Steps)
|
||||
state.UpdateSnapshots(dryResult.Steps)
|
||||
state.TotalRuns++
|
||||
state.Save()
|
||||
|
||||
if len(changed) == 0 {
|
||||
fmt.Printf("[%s] ✓ no changes, skipped AI run\n", t.Format("15:04:05"))
|
||||
continue
|
||||
}
|
||||
|
||||
// Phase 2: full run with AI
|
||||
fmt.Printf("[%s] ⏳ changes detected, running %q with AI...\n", t.Format("15:04:05"), wf.Name)
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
fmt.Printf("❌ error: %v\n", err)
|
||||
continue
|
||||
}
|
||||
ok, total := 0, len(result.Steps)
|
||||
for _, sr := range result.Steps {
|
||||
if sr.OK {
|
||||
ok++
|
||||
}
|
||||
}
|
||||
fmt.Printf("✅ %d/%d steps OK\n", ok, total)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -9,18 +9,22 @@ import (
|
|||
type AIMode string
|
||||
|
||||
const (
|
||||
AIModeAuto AIMode = "auto"
|
||||
AIModeAI AIMode = "ai"
|
||||
AIModeNoAI AIMode = "no-ai"
|
||||
AIModeAuto AIMode = "auto" // Use AI if API key available, else rules
|
||||
AIModeAI AIMode = "ai" // Force AI (error if no key)
|
||||
AIModeNoAI AIMode = "no-ai" // Force rule engine only
|
||||
)
|
||||
|
||||
// RuleEngineFunc is the signature for a deterministic rule engine.
|
||||
// It receives upstream data (same JSON the AI would get) and the step name,
|
||||
// and returns the same AIResponse format the AI would produce.
|
||||
type RuleEngineFunc func(upstream map[string]interface{}, stepName string) (*AIResponse, error)
|
||||
|
||||
// RuleEngines is a registry of skill-target → rule-engine mappings.
|
||||
// Populated by the rules/ package init().
|
||||
var RuleEngines = map[string]RuleEngineFunc{}
|
||||
|
||||
// RegisterRuleEngine registers a rule engine function for a given skill target.
|
||||
// Called by the rules package during init().
|
||||
func RegisterRuleEngine(target string, fn RuleEngineFunc) {
|
||||
RuleEngines[target] = fn
|
||||
}
|
||||
|
|
@ -49,6 +53,10 @@ const (
|
|||
)
|
||||
|
||||
// StepDef defines a single step in a workflow.
|
||||
//
|
||||
// skill: Target = "gitlink-triage" → AI Agent reads the Skill doc
|
||||
// command: Target = "issue +list --state open" → CLI subprocess
|
||||
// api: Target = "{v1}/issues" → HTTP call, Method = GET/POST/...
|
||||
type StepDef struct {
|
||||
Type StepType `json:"type"`
|
||||
Name string `json:"name"`
|
||||
|
|
@ -62,9 +70,9 @@ type StepDef struct {
|
|||
|
||||
// TriggerDef configures when a workflow runs.
|
||||
type TriggerDef struct {
|
||||
Type string `json:"type"`
|
||||
On string `json:"on"`
|
||||
Interval string `json:"interval,omitempty"`
|
||||
Type string `json:"type"` // "manual" | "poll" | "cron"
|
||||
On string `json:"on"` // event description or cron expression
|
||||
Interval string `json:"interval,omitempty"` // poll: "5m" cron: "0 9 * * 1"
|
||||
}
|
||||
|
||||
// WorkflowDef is a named, ordered sequence of steps with a trigger.
|
||||
|
|
@ -78,43 +86,22 @@ type WorkflowDef struct {
|
|||
|
||||
// AIAction is a write instruction returned by an AI skill step.
|
||||
type AIAction struct {
|
||||
Type string `json:"type"`
|
||||
Method string `json:"method,omitempty"`
|
||||
Path string `json:"path,omitempty"`
|
||||
Body map[string]interface{} `json:"body,omitempty"`
|
||||
Module string `json:"module,omitempty"`
|
||||
Command string `json:"command,omitempty"`
|
||||
Args map[string]string `json:"args,omitempty"`
|
||||
Type string `json:"type"` // "api" | "cli"
|
||||
Method string `json:"method,omitempty"` // api: GET/PATCH/POST
|
||||
Path string `json:"path,omitempty"` // api: /v1/{owner}/{repo}/issues/7
|
||||
Body map[string]interface{} `json:"body,omitempty"` // api: request body
|
||||
Module string `json:"module,omitempty"` // cli: "issue"
|
||||
Command string `json:"command,omitempty"` // cli: "+comment"
|
||||
Args map[string]string `json:"args,omitempty"` // cli: {"number":"10"}
|
||||
}
|
||||
|
||||
// AIRequest bundles the data needed for an AI skill step call.
|
||||
type AIRequest struct {
|
||||
SystemPrompt string
|
||||
UserData string
|
||||
}
|
||||
|
||||
// AIResponse is the parsed structured output from an AI skill step.
|
||||
type AIResponse struct {
|
||||
Analysis interface{} `json:"analysis"`
|
||||
Actions []AIAction `json:"actions"`
|
||||
}
|
||||
|
||||
// WorkflowResult holds the outcome of a full workflow run.
|
||||
type WorkflowResult struct {
|
||||
Workflow string `json:"workflow"`
|
||||
Owner string `json:"owner"`
|
||||
Repo string `json:"repo"`
|
||||
Steps []StepResult `json:"steps"`
|
||||
}
|
||||
|
||||
// StepResult holds the outcome of executing one step.
|
||||
type StepResult struct {
|
||||
Step string `json:"step"`
|
||||
Purpose string `json:"purpose"`
|
||||
Type StepType `json:"type"`
|
||||
OK bool `json:"ok"`
|
||||
Data interface{} `json:"data,omitempty"`
|
||||
Error string `json:"error,omitempty"`
|
||||
Skipped bool `json:"skipped,omitempty"`
|
||||
SkipReason string `json:"skip_reason,omitempty"`
|
||||
// WorkflowState tracks persistent run state and change detection snapshots.
|
||||
type WorkflowState struct {
|
||||
Workflow string `json:"workflow"`
|
||||
LastRun string `json:"last_run"`
|
||||
TotalRuns int `json:"total_runs"`
|
||||
Snapshots map[string]string `json:"snapshots"` // stepName → md5(json)
|
||||
PhaseLastRun map[string]string `json:"phase_last_run,omitempty"` // stepName → RFC3339
|
||||
PhaseUpstream map[string]string `json:"phase_upstream,omitempty"` // stepName → md5(upstream)
|
||||
ReviewedPRs map[string]string `json:"reviewed_prs,omitempty"` // prNumber → fingerprint
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,18 +1,45 @@
|
|||
package cli
|
||||
package workflow
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/output"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
wf "github.com/gitlink-org/gitlink-cli/shortcuts/workflow"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/daemon"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/workflow/engine"
|
||||
)
|
||||
|
||||
// --- Registry ---
|
||||
|
||||
var registry = map[string]*WorkflowDef{}
|
||||
|
||||
func register(wf *WorkflowDef) {
|
||||
registry[wf.Name] = wf
|
||||
}
|
||||
|
||||
// All returns all registered workflows sorted by name.
|
||||
func All() []*WorkflowDef {
|
||||
names := make([]string, 0, len(registry))
|
||||
for n := range registry {
|
||||
names = append(names, n)
|
||||
}
|
||||
sort.Strings(names)
|
||||
result := make([]*WorkflowDef, len(names))
|
||||
for i, n := range names {
|
||||
result[i] = registry[n]
|
||||
}
|
||||
return result
|
||||
}
|
||||
|
||||
// Get returns a workflow by name, or nil.
|
||||
func Get(name string) *WorkflowDef {
|
||||
return registry[name]
|
||||
}
|
||||
|
||||
// --- CLI Commands ---
|
||||
|
||||
// Shortcuts returns all workflow CLI commands.
|
||||
func Shortcuts() []*common.Shortcut {
|
||||
return []*common.Shortcut{
|
||||
|
|
@ -24,8 +51,8 @@ func Shortcuts() []*common.Shortcut {
|
|||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
cat := ctx.Arg("category")
|
||||
workflows := wf.All()
|
||||
filtered := make([]*wf.WorkflowDef, 0)
|
||||
workflows := All()
|
||||
filtered := make([]*WorkflowDef, 0)
|
||||
for _, w := range workflows {
|
||||
if cat == "" || strings.EqualFold(w.Category, cat) {
|
||||
filtered = append(filtered, w)
|
||||
|
|
@ -60,11 +87,11 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
return ctx.OutputData(w)
|
||||
return ctx.OutputData(wf)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -79,7 +106,6 @@ func Shortcuts() []*common.Shortcut {
|
|||
{Name: "repos", Usage: "Comma-separated repositories for multi-repo workflow, e.g. org/backend,org/frontend", Default: ""},
|
||||
{Name: "from", Usage: "CSV file for multi-repo workflow with owner,repo columns", Default: ""},
|
||||
{Name: "release", Usage: "Target release/tag for multi-repo release coordination", Default: ""},
|
||||
{Name: "wiki-repo", Usage: "Wiki target repo for publishing multi-repo report, e.g. org/dashboard", Default: ""},
|
||||
{Name: "daemon-loop", Usage: "Internal: run in loop mode", Bool: true},
|
||||
{Name: "interval", Usage: "Internal: loop interval", Default: "5m"},
|
||||
},
|
||||
|
|
@ -88,38 +114,32 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
|
||||
// Pass description to the init-scaffold rule engine.
|
||||
if desc := ctx.Arg("desc"); desc != "" {
|
||||
ctx.Args["_desc"] = desc
|
||||
}
|
||||
|
||||
if wr := ctx.Arg("wiki-repo"); wr != "" {
|
||||
owner, repo := splitRepoRef(wr)
|
||||
if owner != "" && repo != "" {
|
||||
ctx.Args["_wiki_owner"] = owner
|
||||
ctx.Args["_wiki_repo"] = repo
|
||||
}
|
||||
}
|
||||
|
||||
aiMode, err := resolveAIModeFromArgs(ctx)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
||||
// Daemon loop mode (internal — forked by +start)
|
||||
if ctx.Arg("daemon-loop") == "true" {
|
||||
intervalStr := ctx.Arg("interval")
|
||||
interval, err := time.ParseDuration(intervalStr)
|
||||
if err != nil {
|
||||
return fmt.Errorf("invalid interval %q: %w", intervalStr, err)
|
||||
}
|
||||
return daemon.DaemonLoop(ctx, w, interval)
|
||||
return DaemonLoop(ctx, wf, interval)
|
||||
}
|
||||
|
||||
return runWorkflowCommand(ctx, w, ctx.Arg("dry-run") == "true", aiMode)
|
||||
return runWorkflowCommand(ctx, wf, ctx.Arg("dry-run") == "true", aiMode)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -137,11 +157,11 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
if w.Name == "multi-repo" {
|
||||
if wf.Name == "multi-repo" {
|
||||
return fmt.Errorf("workflow +watch 不支持 multi-repo；多仓库协同请求量较大，请使用 workflow +run 手动检查，或 workflow +schedule --interval 6h/24h 做低频巡检")
|
||||
}
|
||||
intervalStr := ctx.Arg("interval")
|
||||
|
|
@ -156,7 +176,7 @@ func Shortcuts() []*common.Shortcut {
|
|||
}
|
||||
ctx.AIMode = aiMode
|
||||
|
||||
return daemon.Watch(ctx, w, interval, ctx.Arg("step"))
|
||||
return Watch(ctx, wf, interval, ctx.Arg("step"))
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -170,15 +190,14 @@ func Shortcuts() []*common.Shortcut {
|
|||
{Name: "repos", Usage: "Comma-separated repositories for multi-repo workflow", Default: ""},
|
||||
{Name: "from", Usage: "CSV file for multi-repo workflow with owner,repo columns", Default: ""},
|
||||
{Name: "release", Usage: "Target release/tag for multi-repo release coordination", Default: ""},
|
||||
{Name: "wiki-repo", Usage: "Wiki target repo for publishing multi-repo report, e.g. org/dashboard", Default: ""},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
name, err := ctx.RequireArg("name")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
intervalStr := ctx.Arg("interval")
|
||||
|
|
@ -187,21 +206,13 @@ func Shortcuts() []*common.Shortcut {
|
|||
return fmt.Errorf("invalid interval %q: %w", intervalStr, err)
|
||||
}
|
||||
|
||||
if wr := ctx.Arg("wiki-repo"); wr != "" {
|
||||
owner, repo := splitRepoRef(wr)
|
||||
if owner != "" && repo != "" {
|
||||
ctx.Args["_wiki_owner"] = owner
|
||||
ctx.Args["_wiki_repo"] = repo
|
||||
}
|
||||
}
|
||||
|
||||
aiMode, modeErr := resolveAIModeFromArgs(ctx)
|
||||
if modeErr != nil {
|
||||
return modeErr
|
||||
}
|
||||
ctx.AIMode = aiMode
|
||||
|
||||
return daemon.Schedule(ctx, w, interval)
|
||||
return Schedule(ctx, wf, interval)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -215,15 +226,14 @@ func Shortcuts() []*common.Shortcut {
|
|||
{Name: "repos", Usage: "Comma-separated repositories for multi-repo workflow", Default: ""},
|
||||
{Name: "from", Usage: "CSV file for multi-repo workflow with owner,repo columns", Default: ""},
|
||||
{Name: "release", Usage: "Target release/tag for multi-repo release coordination", Default: ""},
|
||||
{Name: "wiki-repo", Usage: "Wiki target repo for publishing multi-repo report, e.g. org/dashboard", Default: ""},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
name, err := ctx.RequireArg("name")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
intervalStr := ctx.Arg("interval")
|
||||
|
|
@ -232,20 +242,12 @@ func Shortcuts() []*common.Shortcut {
|
|||
return fmt.Errorf("invalid interval %q: %w", intervalStr, err)
|
||||
}
|
||||
|
||||
if wr := ctx.Arg("wiki-repo"); wr != "" {
|
||||
owner, repo := splitRepoRef(wr)
|
||||
if owner != "" && repo != "" {
|
||||
ctx.Args["_wiki_owner"] = owner
|
||||
ctx.Args["_wiki_repo"] = repo
|
||||
}
|
||||
}
|
||||
|
||||
aiMode, modeErr := resolveAIModeFromArgs(ctx)
|
||||
if modeErr != nil {
|
||||
return modeErr
|
||||
}
|
||||
|
||||
return daemon.StartDaemon(ctx, w, interval, aiMode)
|
||||
return StartDaemon(ctx, wf, interval, aiMode)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -259,7 +261,7 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return daemon.StopDaemon(name)
|
||||
return StopDaemon(name)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -273,7 +275,7 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return daemon.StatusDaemon(name)
|
||||
return StatusDaemon(name)
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -288,7 +290,7 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return daemon.TailDaemonLog(name, ctx.Arg("follow") == "true")
|
||||
return tailDaemonLog(name, ctx.Arg("follow") == "true")
|
||||
},
|
||||
},
|
||||
{
|
||||
|
|
@ -305,8 +307,8 @@ func Shortcuts() []*common.Shortcut {
|
|||
if err != nil {
|
||||
return err
|
||||
}
|
||||
w := wf.Get(name)
|
||||
if w == nil {
|
||||
wf := Get(name)
|
||||
if wf == nil {
|
||||
return fmt.Errorf("workflow %q not found; use workflow +list to see available workflows", name)
|
||||
}
|
||||
|
||||
|
|
@ -315,7 +317,7 @@ func Shortcuts() []*common.Shortcut {
|
|||
return modeErr
|
||||
}
|
||||
|
||||
return daemon.InstallSystemdUnit(ctx, w, ctx.Arg("interval"), aiMode)
|
||||
return installSystemdUnit(ctx, wf, ctx.Arg("interval"), aiMode)
|
||||
},
|
||||
},
|
||||
}
|
||||
|
|
@ -336,8 +338,8 @@ func resolveAIModeFromArgs(ctx *common.RuntimeContext) (string, error) {
|
|||
return "auto", nil
|
||||
}
|
||||
|
||||
func runWorkflowCommand(ctx *common.RuntimeContext, w *wf.WorkflowDef, dryRun bool, aiMode string) error {
|
||||
result, err := engine.RunWithMode(ctx, w, dryRun, aiMode)
|
||||
func runWorkflowCommand(ctx *common.RuntimeContext, wf *WorkflowDef, dryRun bool, aiMode string) error {
|
||||
result, err := RunWithMode(ctx, wf, dryRun, aiMode)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
|
|
@ -350,7 +352,7 @@ func runWorkflowCommand(ctx *common.RuntimeContext, w *wf.WorkflowDef, dryRun bo
|
|||
needsAI++
|
||||
}
|
||||
if v, _ := m["_ai_used"]; v == true {
|
||||
ruleEngine++
|
||||
ruleEngine++ // AI was used
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -387,11 +389,3 @@ func runWorkflowCommand(ctx *common.RuntimeContext, w *wf.WorkflowDef, dryRun bo
|
|||
|
||||
return ctx.Output(output.SuccessEnvelope(result, nil))
|
||||
}
|
||||
|
||||
func splitRepoRef(raw string) (owner, repo string) {
|
||||
parts := strings.SplitN(strings.TrimSpace(raw), "/", 2)
|
||||
if len(parts) == 2 {
|
||||
return strings.TrimSpace(parts[0]), strings.TrimSpace(parts[1])
|
||||
}
|
||||
return "", ""
|
||||
}
|
||||
|
|
@ -1,88 +1,18 @@
|
|||
package workflow
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
"time"
|
||||
|
||||
func init() {
|
||||
// Register all workflows for tests (defs init doesn't run in test context
|
||||
// because importing defs would create an import cycle).
|
||||
Register(&WorkflowDef{
|
||||
Name: "community-ops",
|
||||
Category: "运营",
|
||||
Description: "社区运营自动化",
|
||||
Trigger: TriggerDef{Type: "poll", On: "issue.created", Interval: "5m"},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "open-issues", Purpose: "获取开放 Issue", Target: "issue +list --state open --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "labels", Purpose: "获取标签库", Target: "label +list"},
|
||||
{Type: StepTypeCommand, Name: "members", Purpose: "获取成员列表", Target: "member +list"},
|
||||
{Type: StepTypeSkill, Name: "triage", Purpose: "AI 分析并执行分拣", Target: "gitlink-triage", DependsOn: []string{"open-issues", "labels", "members"}, RunWhen: RunAlways},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "获取项目基础信息", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "merged-prs", Purpose: "获取已合并 PR", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "获取提交历史", Target: "commit +list --limit 50"},
|
||||
{Type: StepTypeSkill, Name: "health-report", Purpose: "AI 生成周报", Target: "gitlink-health", DependsOn: []string{"repo-info", "merged-prs", "commits", "open-issues"}, RunWhen: RunWeekly},
|
||||
{Type: StepTypeCommand, Name: "releases", Purpose: "获取版本发布记录", Target: "release +list"},
|
||||
{Type: StepTypeSkill, Name: "changelog", Purpose: "生成 Release Notes", Target: "gitlink-changelog", DependsOn: []string{"commits", "releases", "merged-prs"}, RunWhen: RunOnChange},
|
||||
},
|
||||
})
|
||||
Register(&WorkflowDef{
|
||||
Name: "code-quality",
|
||||
Category: "质量",
|
||||
Description: "代码质量看门人",
|
||||
Trigger: TriggerDef{Type: "poll", On: "pr.opened", Interval: "5m"},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "open-prs", Purpose: "获取开放 PR 列表", Target: "pr +list --state open --limit 20"},
|
||||
{Type: StepTypeCommand, Name: "ci-builds", Purpose: "获取 CI 构建状态", Target: "ci +builds --limit 10"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "获取仓库保护规则配置", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "获取最近提交", Target: "commit +list --limit 30"},
|
||||
{Type: StepTypeCommand, Name: "branches", Purpose: "获取分支列表", Target: "branch +list"},
|
||||
{Type: StepTypeSkill, Name: "review", Purpose: "AI 审查 PR 代码质量", Target: "gitlink-review", DependsOn: []string{"open-prs"}},
|
||||
{Type: StepTypeSkill, Name: "ci-diagnosis", Purpose: "AI 诊断 CI 构建失败", Target: "gitlink-ci", DependsOn: []string{"ci-builds", "commits"}},
|
||||
},
|
||||
})
|
||||
Register(&WorkflowDef{
|
||||
Name: "project-init",
|
||||
Category: "初始化",
|
||||
Description: "项目一键初始化",
|
||||
Trigger: TriggerDef{Type: "manual", On: "manual"},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeSkill, Name: "init-scaffold", Purpose: "创建仓库并初始化脚手架", Target: "gitlink-init-scaffold"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "确认仓库已创建", Target: "repo +info"},
|
||||
{Type: StepTypeCommand, Name: "existing-files", Purpose: "验证文件", Target: "file +list"},
|
||||
{Type: StepTypeCommand, Name: "labels", Purpose: "验证标签库", Target: "label +list"},
|
||||
{Type: StepTypeSkill, Name: "license-check", Purpose: "检查许可证合规", Target: "gitlink-license", DependsOn: []string{"existing-files"}},
|
||||
{Type: StepTypeCommand, Name: "milestones", Purpose: "验证里程碑", Target: "milestone +list"},
|
||||
{Type: StepTypeCommand, Name: "existing-issues", Purpose: "验证初始 Issue", Target: "issue +list --state all --limit 10"},
|
||||
{Type: StepTypeCommand, Name: "branches", Purpose: "检查分支结构", Target: "branch +list"},
|
||||
{Type: StepTypeSkill, Name: "repo-audit", Purpose: "综合审计仓库健康度", Target: "gitlink-repo", DependsOn: []string{"repo-info", "existing-files", "labels", "milestones", "branches"}},
|
||||
},
|
||||
})
|
||||
Register(&WorkflowDef{
|
||||
Name: "multi-repo",
|
||||
Category: "协同",
|
||||
Description: "多仓库协同",
|
||||
Trigger: TriggerDef{Type: "cron", On: "0 9 * * 1", Interval: "24h"},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "multi-repo-snapshot", Purpose: "采集多个仓库状态", Target: "workflow-internal:multi-repo-snapshot"},
|
||||
{Type: StepTypeSkill, Name: "multi-repo-coordination", Purpose: "生成统一报告", Target: "gitlink-multi-repo", DependsOn: []string{"multi-repo-snapshot"}},
|
||||
},
|
||||
})
|
||||
Register(&WorkflowDef{
|
||||
Name: "contributor-growth",
|
||||
Category: "成长",
|
||||
Description: "贡献者成长体系",
|
||||
Trigger: TriggerDef{Type: "cron", On: "0 9 * * 1", Interval: "24h"},
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeCommand, Name: "commits", Purpose: "提交历史", Target: "commit +list --limit 100"},
|
||||
{Type: StepTypeCommand, Name: "open-issues", Purpose: "开放 Issue", Target: "issue +list --state open --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "closed-issues", Purpose: "已关闭 Issue", Target: "issue +list --state closed --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "merged-prs", Purpose: "已合并 PR", Target: "pr +list --state merged --limit 50"},
|
||||
{Type: StepTypeCommand, Name: "members", Purpose: "项目成员列表", Target: "member +list"},
|
||||
{Type: StepTypeCommand, Name: "repo-info", Purpose: "项目基础数据", Target: "repo +info"},
|
||||
{Type: StepTypeSkill, Name: "contributor-ranking", Purpose: "AI 分析贡献者排行", Target: "gitlink-contributor-ranking", DependsOn: []string{"commits", "open-issues", "closed-issues", "merged-prs", "members"}},
|
||||
},
|
||||
})
|
||||
}
|
||||
"github.com/gitlink-org/gitlink-cli/internal/client"
|
||||
"github.com/gitlink-org/gitlink-cli/internal/output"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
func TestRegistry(t *testing.T) {
|
||||
if len(registry) != 5 {
|
||||
|
|
@ -114,6 +44,57 @@ func TestGetNonexistent(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
func TestShortcutsCount(t *testing.T) {
|
||||
sc := Shortcuts()
|
||||
if len(sc) != 11 {
|
||||
t.Fatalf("expected 11 shortcuts (list, info, run, init, watch, schedule, start, stop, status, logs, install-systemd), got %d", len(sc))
|
||||
}
|
||||
names := map[string]bool{
|
||||
"list": false, "info": false, "run": false, "init": false, "watch": false,
|
||||
"schedule": false, "start": false, "stop": false, "status": false,
|
||||
"logs": false, "install-systemd": false,
|
||||
}
|
||||
for _, s := range sc {
|
||||
if _, ok := names[s.Name]; !ok {
|
||||
t.Fatalf("unexpected shortcut: %s", s.Name)
|
||||
}
|
||||
names[s.Name] = true
|
||||
}
|
||||
for n, found := range names {
|
||||
if !found {
|
||||
t.Fatalf("missing shortcut: %s", n)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestProjectInitShortcut(t *testing.T) {
|
||||
var initShortcut *common.Shortcut
|
||||
for _, s := range Shortcuts() {
|
||||
if s.Name == "init" {
|
||||
initShortcut = s
|
||||
break
|
||||
}
|
||||
}
|
||||
if initShortcut == nil {
|
||||
t.Fatal("missing init shortcut")
|
||||
}
|
||||
if initShortcut.Description == "" {
|
||||
t.Fatal("init shortcut should have a description")
|
||||
}
|
||||
if len(initShortcut.Flags) != 3 {
|
||||
t.Fatalf("init shortcut should have 3 flags (dry-run, ai, no-ai), got %d: %+v", len(initShortcut.Flags), initShortcut.Flags)
|
||||
}
|
||||
hasDryRun := false
|
||||
for _, f := range initShortcut.Flags {
|
||||
if f.Name == "dry-run" && f.Bool {
|
||||
hasDryRun = true
|
||||
}
|
||||
}
|
||||
if !hasDryRun {
|
||||
t.Fatal("init shortcut should expose bool --dry-run flag")
|
||||
}
|
||||
}
|
||||
|
||||
func TestResolvePath(t *testing.T) {
|
||||
cases := []struct {
|
||||
template, owner, repo, expected string
|
||||
|
|
@ -124,9 +105,9 @@ func TestResolvePath(t *testing.T) {
|
|||
{"{v1}/issues?state=open", "x", "y", "/v1/x/y/issues?state=open"},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
got := ResolvePath(tc.template, tc.owner, tc.repo)
|
||||
got := resolvePath(tc.template, tc.owner, tc.repo)
|
||||
if got != tc.expected {
|
||||
t.Fatalf("ResolvePath(%q, %s, %s) = %q, want %q", tc.template, tc.owner, tc.repo, got, tc.expected)
|
||||
t.Fatalf("resolvePath(%q, %s, %s) = %q, want %q", tc.template, tc.owner, tc.repo, got, tc.expected)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
@ -215,6 +196,69 @@ func TestMultiRepoWorkflowShape(t *testing.T) {
|
|||
}
|
||||
}
|
||||
|
||||
func TestParseMultiRepoRefs(t *testing.T) {
|
||||
refs, err := parseMultiRepoRefs("org/backend, org/frontend,org/backend", "")
|
||||
if err != nil {
|
||||
t.Fatalf("parseMultiRepoRefs failed: %v", err)
|
||||
}
|
||||
if len(refs) != 2 {
|
||||
t.Fatalf("expected 2 deduped refs, got %d: %+v", len(refs), refs)
|
||||
}
|
||||
if refs[0].Owner != "org" || refs[0].Repo != "backend" {
|
||||
t.Fatalf("unexpected first ref: %+v", refs[0])
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseRepoCSV(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
path := filepath.Join(dir, "repos.csv")
|
||||
if err := os.WriteFile(path, []byte("owner,repo\norg,backend\norg/frontend\n"), 0600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
refs, err := parseRepoCSV(path)
|
||||
if err != nil {
|
||||
t.Fatalf("parseRepoCSV failed: %v", err)
|
||||
}
|
||||
if len(refs) != 2 {
|
||||
t.Fatalf("expected 2 refs, got %d", len(refs))
|
||||
}
|
||||
if refs[1].Owner != "org" || refs[1].Repo != "frontend" {
|
||||
t.Fatalf("unexpected second ref: %+v", refs[1])
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuildDaemonArgsSkipsOwnerRepoForExplicitMultiRepo(t *testing.T) {
|
||||
wf := Get("multi-repo")
|
||||
ctx := &common.RuntimeContext{
|
||||
Owner: "ignored",
|
||||
Repo: "ignored",
|
||||
Args: map[string]string{
|
||||
"repos": "org/backend,org/frontend",
|
||||
"release": "v1.4.0",
|
||||
},
|
||||
}
|
||||
|
||||
args := buildDaemonArgs(ctx, wf, 24*time.Hour, "no-ai")
|
||||
if stringSliceContains(args, "--owner") || stringSliceContains(args, "--repo") {
|
||||
t.Fatalf("explicit multi-repo daemon args should not include owner/repo: %v", args)
|
||||
}
|
||||
if !stringSliceContains(args, "--repos") || !stringSliceContains(args, "org/backend,org/frontend") {
|
||||
t.Fatalf("daemon args missing repos: %v", args)
|
||||
}
|
||||
if !stringSliceContains(args, "--release") || !stringSliceContains(args, "v1.4.0") {
|
||||
t.Fatalf("daemon args missing release: %v", args)
|
||||
}
|
||||
}
|
||||
|
||||
func stringSliceContains(items []string, want string) bool {
|
||||
for _, item := range items {
|
||||
if item == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
func TestParseCommandTarget(t *testing.T) {
|
||||
cases := []struct {
|
||||
input string
|
||||
|
|
@ -226,18 +270,306 @@ func TestParseCommandTarget(t *testing.T) {
|
|||
{"issue +list --state open --limit 50", []string{"issue", "+list", "--state", "open", "--limit", "50"}},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
got := ParseCommandTarget(tc.input)
|
||||
got := parseCommandTarget(tc.input)
|
||||
if len(got) != len(tc.expected) {
|
||||
t.Fatalf("ParseCommandTarget(%q): len=%d, want len=%d (got=%v)", tc.input, len(got), len(tc.expected), got)
|
||||
t.Fatalf("parseCommandTarget(%q): len=%d, want len=%d (got=%v)", tc.input, len(got), len(tc.expected), got)
|
||||
}
|
||||
for i := range got {
|
||||
if got[i] != tc.expected[i] {
|
||||
t.Fatalf("ParseCommandTarget(%q)[%d] = %q, want %q", tc.input, i, got[i], tc.expected[i])
|
||||
t.Fatalf("parseCommandTarget(%q)[%d] = %q, want %q", tc.input, i, got[i], tc.expected[i])
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// --- Security whitelist tests ---
|
||||
|
||||
func TestActionAllowed(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
action AIAction
|
||||
allowed bool
|
||||
}{
|
||||
{"api GET", AIAction{Type: "api", Method: "GET"}, true},
|
||||
{"api POST", AIAction{Type: "api", Method: "POST"}, true},
|
||||
{"api PATCH", AIAction{Type: "api", Method: "PATCH"}, true},
|
||||
{"api DELETE blocked", AIAction{Type: "api", Method: "DELETE"}, false},
|
||||
{"cli issue comment", AIAction{Type: "cli", Module: "issue", Command: "+comment"}, true},
|
||||
{"cli delete blocked", AIAction{Type: "cli", Module: "repo", Command: "+delete"}, false},
|
||||
{"cli fork blocked", AIAction{Type: "cli", Module: "repo", Command: "+fork"}, false},
|
||||
{"cli repo module blocked", AIAction{Type: "cli", Module: "org", Command: "+list"}, false},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
if got := isActionAllowed(tc.action); got != tc.allowed {
|
||||
t.Errorf("isActionAllowed(%+v) = %v, want %v", tc.action, got, tc.allowed)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// --- State tests ---
|
||||
|
||||
func TestStateSaveLoad(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
t.Setenv("GITLINK_CONFIG_DIR", dir)
|
||||
|
||||
s := &WorkflowState{
|
||||
Workflow: "test-wf",
|
||||
TotalRuns: 5,
|
||||
Snapshots: map[string]string{"step1": "abc123"},
|
||||
}
|
||||
if err := s.Save(); err != nil {
|
||||
t.Fatalf("Save failed: %v", err)
|
||||
}
|
||||
|
||||
loaded, err := LoadState("test-wf")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadState failed: %v", err)
|
||||
}
|
||||
if loaded.TotalRuns != 5 {
|
||||
t.Fatalf("TotalRuns = %d, want 5", loaded.TotalRuns)
|
||||
}
|
||||
if loaded.Snapshots["step1"] != "abc123" {
|
||||
t.Fatalf("Snapshots[step1] = %q, want abc123", loaded.Snapshots["step1"])
|
||||
}
|
||||
|
||||
os.Remove(filepath.Join(dir, "workflow-test-wf-state.json"))
|
||||
}
|
||||
|
||||
func TestStateDiff(t *testing.T) {
|
||||
s := &WorkflowState{
|
||||
Workflow: "test-diff",
|
||||
Snapshots: map[string]string{"step1": "oldhash"},
|
||||
}
|
||||
|
||||
results := []StepResult{
|
||||
{Step: "step1", OK: true, Data: "changed data"},
|
||||
{Step: "step2", OK: true, Data: "new step"},
|
||||
{Step: "step3", OK: false, Data: "ignored"},
|
||||
}
|
||||
|
||||
changed := s.Diff(results)
|
||||
if len(changed) != 1 {
|
||||
t.Fatalf("Diff: expected 1 changed step, got %d", len(changed))
|
||||
}
|
||||
if changed[0] != "step1" {
|
||||
t.Fatalf("Diff: expected 'step1' to change, got %q", changed[0])
|
||||
}
|
||||
if _, ok := s.Snapshots["step2"]; !ok {
|
||||
t.Fatal("step2 should be added to snapshots")
|
||||
}
|
||||
if _, ok := s.Snapshots["step3"]; ok {
|
||||
t.Fatal("step3 (failed) should NOT be added to snapshots")
|
||||
}
|
||||
}
|
||||
|
||||
func TestLoadStateNotExist(t *testing.T) {
|
||||
dir := t.TempDir()
|
||||
t.Setenv("GITLINK_CONFIG_DIR", dir)
|
||||
|
||||
s, err := LoadState("nonexistent")
|
||||
if err != nil {
|
||||
t.Fatalf("LoadState should not error for missing file: %v", err)
|
||||
}
|
||||
if s.Workflow != "nonexistent" {
|
||||
t.Fatalf("Workflow = %q, want nonexistent", s.Workflow)
|
||||
}
|
||||
if s.Snapshots == nil {
|
||||
t.Fatal("Snapshots should be initialized as empty map")
|
||||
}
|
||||
}
|
||||
|
||||
// --- Engine integration tests ---
|
||||
|
||||
func TestRunWithAPISteps(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
switch {
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/issues.json":
|
||||
writeJSON(t, w, output.SuccessEnvelope([]map[string]interface{}{
|
||||
{"id": 1, "subject": "bug"},
|
||||
{"id": 2, "subject": "feature"},
|
||||
}, nil))
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/labels.json":
|
||||
writeJSON(t, w, output.SuccessEnvelope([]map[string]interface{}{
|
||||
{"id": 10, "name": "bug"},
|
||||
{"id": 11, "name": "enhancement"},
|
||||
}, nil))
|
||||
default:
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-api",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeAPI, Name: "fetch-issues", Purpose: "get issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: StepTypeAPI, Name: "fetch-labels", Purpose: "get labels", Method: "GET", Target: "{v1}/labels"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
if result.Owner != "owner" || result.Repo != "repo" {
|
||||
t.Fatalf("expected owner/repo = owner/repo, got %s/%s", result.Owner, result.Repo)
|
||||
}
|
||||
if len(result.Steps) != 2 {
|
||||
t.Fatalf("expected 2 step results, got %d", len(result.Steps))
|
||||
}
|
||||
for _, sr := range result.Steps {
|
||||
if !sr.OK {
|
||||
t.Fatalf("step %q: expected ok=true, got error=%q", sr.Step, sr.Error)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestSkillStepReceivesUpstream(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path == "/v1/owner/repo/issues.json" {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{
|
||||
"issues": []map[string]interface{}{{"id": 1}},
|
||||
}, nil))
|
||||
} else if r.URL.Path == "/v1/owner/repo/labels.json" {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{
|
||||
"labels": []map[string]interface{}{{"name": "bug"}},
|
||||
}, nil))
|
||||
} else {
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-skill-upstream",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeAPI, Name: "get-issues", Purpose: "issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: StepTypeAPI, Name: "get-labels", Purpose: "labels", Method: "GET", Target: "{v1}/labels"},
|
||||
{Type: StepTypeSkill, Name: "ai-triage", Purpose: "triage", Target: "gitlink-triage"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[2].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
upstream, ok := skillData["_upstream"].(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step missing _upstream map")
|
||||
}
|
||||
if _, hasIssues := upstream["get-issues"]; !hasIssues {
|
||||
t.Fatal("_upstream missing get-issues key")
|
||||
}
|
||||
if _, hasLabels := upstream["get-labels"]; !hasLabels {
|
||||
t.Fatal("_upstream missing get-labels key")
|
||||
}
|
||||
if skillData["_skill"] != "gitlink-triage" {
|
||||
t.Fatalf("_skill = %q, want %q", skillData["_skill"], "gitlink-triage")
|
||||
}
|
||||
}
|
||||
|
||||
// TestSkillStepWithDependsOn verifies that when DependsOn is set,
|
||||
// only those specific upstream steps are collected.
|
||||
func TestSkillStepWithDependsOn(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{"ok": true}, nil))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-depends-on",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeAPI, Name: "open-issues", Purpose: "issues", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: StepTypeAPI, Name: "labels", Purpose: "labels", Method: "GET", Target: "{v1}/labels"},
|
||||
{Type: StepTypeAPI, Name: "members", Purpose: "members", Method: "GET", Target: "{v1}/members"},
|
||||
{Type: StepTypeSkill, Name: "triage", Purpose: "triage", Target: "gitlink-triage",
|
||||
DependsOn: []string{"open-issues", "labels"}},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[3].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
upstream, ok := skillData["_upstream"].(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step missing _upstream map")
|
||||
}
|
||||
if _, hasIssues := upstream["open-issues"]; !hasIssues {
|
||||
t.Fatal("_upstream missing open-issues key")
|
||||
}
|
||||
if _, hasLabels := upstream["labels"]; !hasLabels {
|
||||
t.Fatal("_upstream missing labels key")
|
||||
}
|
||||
if _, hasMembers := upstream["members"]; hasMembers {
|
||||
t.Fatal("_upstream should NOT contain members (not in DependsOn)")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunStepFailure(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(500)
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"ok": false, "error": "internal server error",
|
||||
})
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-fail",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeAPI, Name: "bad-step", Purpose: "will fail", Method: "GET", Target: "{v1}/bad"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() returned error: %v (steps should fail gracefully)", err)
|
||||
}
|
||||
if result.Steps[0].OK {
|
||||
t.Fatal("expected step to fail, but it passed")
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunUnknownStepType(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
t.Fatalf("no request expected")
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-unknown",
|
||||
Steps: []StepDef{
|
||||
{Type: StepType("invalid"), Name: "bad", Purpose: "unknown", Target: "x"},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, false)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() returned error: %v", err)
|
||||
}
|
||||
if result.Steps[0].OK {
|
||||
t.Fatal("unknown step type should fail")
|
||||
}
|
||||
}
|
||||
|
||||
func TestCodeQualityHasReviewStep(t *testing.T) {
|
||||
wf := Get("code-quality")
|
||||
if wf == nil {
|
||||
|
|
@ -257,3 +589,57 @@ func TestCodeQualityHasReviewStep(t *testing.T) {
|
|||
t.Fatal("code-quality missing gitlink-review skill step")
|
||||
}
|
||||
}
|
||||
|
||||
func TestSkillStepDryRun(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
writeJSON(t, w, output.SuccessEnvelope(map[string]interface{}{"ok": true}, nil))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
ctx := newTestContext(t, server)
|
||||
wf := &WorkflowDef{
|
||||
Name: "test-dry-run",
|
||||
Steps: []StepDef{
|
||||
{Type: StepTypeAPI, Name: "get-data", Purpose: "data", Method: "GET", Target: "{v1}/issues"},
|
||||
{Type: StepTypeSkill, Name: "ai-step", Purpose: "AI analysis", Target: "gitlink-triage",
|
||||
DependsOn: []string{"get-data"}},
|
||||
},
|
||||
}
|
||||
|
||||
result, err := Run(ctx, wf, true)
|
||||
if err != nil {
|
||||
t.Fatalf("Run() dry-run failed: %v", err)
|
||||
}
|
||||
|
||||
skillData, ok := result.Steps[1].Data.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatal("skill step data is not a map")
|
||||
}
|
||||
if v, _ := skillData["_dry_run"]; v != true {
|
||||
t.Fatal("dry-run skill step should have _dry_run=true")
|
||||
}
|
||||
}
|
||||
|
||||
// --- helpers ---
|
||||
|
||||
func newTestContext(t *testing.T, server *httptest.Server) *common.RuntimeContext {
|
||||
t.Helper()
|
||||
return &common.RuntimeContext{
|
||||
Client: &client.Client{
|
||||
HTTP: server.Client(),
|
||||
BaseURL: server.URL,
|
||||
},
|
||||
Owner: "owner",
|
||||
Repo: "repo",
|
||||
Format: "json",
|
||||
Args: map[string]string{},
|
||||
}
|
||||
}
|
||||
|
||||
func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
|
||||
t.Helper()
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
if err := json.NewEncoder(w).Encode(payload); err != nil {
|
||||
t.Fatalf("failed to write response: %v", err)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,4 +1,3 @@
|
|||
# syntax=docker/dockerfile:1
|
||||
# Stage 1: Build
|
||||
FROM golang:1.26-alpine AS builder
|
||||
|
||||
|
|
@ -10,12 +9,11 @@ RUN go mod download
|
|||
|
||||
COPY . .
|
||||
|
||||
# 合并为一个 RUN：showcase-server 复用 gitlink-cli 已编译的依赖（同一 RUN 层内 Go 编译缓存共享）。
|
||||
# --mount=type=cache：BuildKit 跨构建保留 Go 编译缓存（/root/.cache/go-build），
|
||||
# 之后只重编改动的包，不再全量重编（需 docker build 时 DOCKER_BUILDKIT=1）。
|
||||
RUN --mount=type=cache,target=/root/.cache/go-build \
|
||||
CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o gitlink-cli . && \
|
||||
CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o showcase-server ./showcase/
|
||||
# Build gitlink-cli binary
|
||||
RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o gitlink-cli .
|
||||
|
||||
# Build showcase server binary
|
||||
RUN CGO_ENABLED=0 GOOS=linux go build -buildvcs=false -o showcase-server ./showcase/
|
||||
|
||||
# Stage 2: Runtime
|
||||
FROM alpine:latest
|
||||
|
|
|
|||
|
|
@ -247,12 +247,12 @@
|
|||
</nav>
|
||||
|
||||
<div class="stats-bar">
|
||||
<div class="stat-item"><div class="num">19</div><div class="label">CLI 模块</div></div>
|
||||
<div class="stat-item"><div class="num green">110</div><div class="label">新增命令</div></div>
|
||||
<div class="stat-item"><div class="num">11</div><div class="label">CLI 模块</div></div>
|
||||
<div class="stat-item"><div class="num green">47+</div><div class="label">新增命令</div></div>
|
||||
<div class="stat-item"><div class="num green">17</div><div class="label">AI Skills</div></div>
|
||||
<div class="stat-item"><div class="num purple">5</div><div class="label">自动化工作流</div></div>
|
||||
<div class="stat-item"><div class="num purple">11</div><div class="label">工作流命令</div></div>
|
||||
<div class="stat-item"><div class="num orange">187</div><div class="label">单元测试</div></div>
|
||||
<div class="stat-item"><div class="num orange">47+</div><div class="label">单元测试</div></div>
|
||||
<div class="stat-item" style="cursor:pointer" onclick="toggleFormat()" title="点击切换输出格式">
|
||||
<div class="num" id="format-label" style="font-size:1.2em;transition:color 0.3s;">JSON</div>
|
||||
<div class="label">输出格式 ▾</div>
|
||||
|
|
@ -296,105 +296,13 @@
|
|||
<div class="section-header">
|
||||
<span class="badge p4">子任务四</span>
|
||||
<h2>应用 GitLink 辅助科研</h2>
|
||||
<p class="subtitle">科研辅助双联装 · fair 给科研软件照 X 光 · spark 跨三源挖论文-代码缺口 · 含可运行 Python 脚本</p>
|
||||
<p class="subtitle">利用 GitLink 平台能力支撑科研项目管理和学术协作</p>
|
||||
</div>
|
||||
<div class="container">
|
||||
<div class="stat-row" style="display:flex;gap:20px;flex-wrap:wrap;margin-bottom:22px;justify-content:center;">
|
||||
<div class="stat-item"><div class="num orange">2</div><div class="label">科研辅助 Skill</div></div>
|
||||
<div class="stat-item"><div class="num green">2</div><div class="label">可运行 Python 脚本</div></div>
|
||||
<div class="stat-item"><div class="num">4</div><div class="label">裁决/缺口维度</div></div>
|
||||
<div class="stat-item"><div class="num">3</div><div class="label">数据源融合</div></div>
|
||||
<div class="stat-item"><div class="num purple">FAIR4RS</div><div class="label">学术对标</div></div>
|
||||
</div>
|
||||
<div class="skill-grid" style="grid-template-columns:repeat(auto-fit,minmax(420px,1fr));">
|
||||
<div class="skill-card aux">
|
||||
<div class="skill-top">
|
||||
<span class="skill-name">🔬 gitlink-research-fair</span>
|
||||
<span class="skill-ver">X 光 v2.1</span>
|
||||
</div>
|
||||
<div class="skill-desc"><b>科研软件 X 光</b> —— 单仓深挖科研产物。<code>fair.py</code> 真抽取 → LLM 四维裁决 + 真科研图谱 + 本 repo 特有关键发现，可选处方 PR。</div>
|
||||
<div class="skill-meta">
|
||||
<span>📄 论文溯源</span><span>📦 数据链</span><span>🔁 复现就绪</span><span>📚 引用就绪</span>
|
||||
</div>
|
||||
<div style="margin-top:12px;font-size:0.78em;">
|
||||
<div style="color:#999;margin-bottom:4px;">⚙️ 管道</div>
|
||||
<div style="display:flex;flex-wrap:wrap;gap:4px;align-items:center;">
|
||||
<span style="background:#fff3e0;padding:2px 8px;border-radius:10px;">fair.py 抽取</span><span style="color:#bbb;">→</span>
|
||||
<span style="background:#fff3e0;padding:2px 8px;border-radius:10px;">四维裁决</span><span style="color:#bbb;">→</span>
|
||||
<span style="background:#fff3e0;padding:2px 8px;border-radius:10px;">真科研图谱</span><span style="color:#bbb;">→</span>
|
||||
<span style="background:#fff3e0;padding:2px 8px;border-radius:10px;">报告 + 处方 PR</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="margin-top:10px;font-size:0.78em;color:#666;line-height:1.6;">
|
||||
<div style="color:#999;margin-bottom:2px;">🎯 fair.py 真抽取（确定性，非 LLM 看一眼）</div>
|
||||
论文 arxiv/DOI/venue/作者 · 数据集(已知名+下载脚本) · 复现四件套(依赖锁/入口/环境/期望结果) · 引用(CITATION.cff/codemeta/bibtex) · 方法+框架(torch/tf/jax)
|
||||
</div>
|
||||
<div style="margin-top:10px;font-size:0.8em;color:#888;border-top:1px dashed #eee;padding-top:8px;">
|
||||
实证：liyiying10/<b>Feature_Critic</b> (ICML 2019) → arxiv:<b>1901.11448</b> 真抽出，PyTorch 识别，四维 ✅⚠️⚠️⚠️
|
||||
</div>
|
||||
<details style="margin-top:8px;font-size:0.8em;">
|
||||
<summary style="cursor:pointer;color:#fa8c16;font-weight:600;">📊 查看 Feature_Critic 真实 X 光输出</summary>
|
||||
<div style="margin-top:8px;padding:10px;background:#fafbfc;border-radius:6px;border-left:3px solid #fa8c16;">
|
||||
<div style="font-weight:600;margin-bottom:6px;">四维裁决：论文溯源 ✅ ｜ 数据链 ⚠️ ｜ 复现就绪 ⚠️ ｜ 引用就绪 ❌</div>
|
||||
<div style="font-size:0.9em;color:#666;margin-bottom:4px;">🧬 真科研图谱（状态色）：</div>
|
||||
<div style="font-family:monospace;font-size:0.82em;background:#1e1e1e;color:#d4d4d4;padding:8px 10px;border-radius:4px;line-height:1.7;white-space:pre-wrap;">ICML2019 (arxiv:1901.11448) ✅
|
||||
└─ proposes → Feature-Critic 方法
|
||||
└─ implements → main_Feature_Critic.py ✅
|
||||
├─ uses → PACS / Visual Decathlon ⚠️
|
||||
└─ depends → PyTorch ⚠️
|
||||
└─ cited-via → 无 CITATION.cff ❌</div>
|
||||
<div style="margin-top:6px;color:#555;">💡 关键发现：论文已溯源，但<b>无 CITATION.cff → 机器不可引用</b>；无 requirements.txt → 依赖未锁，复现风险。</div>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
<div class="skill-card aux">
|
||||
<div class="skill-top">
|
||||
<span class="skill-name">⚡ gitlink-spark</span>
|
||||
<span class="skill-ver">缺口挖掘</span>
|
||||
</div>
|
||||
<div class="skill-desc"><b>文献-代码语义缺口挖掘机</b> —— 跨源发现研究空白。<code>spark.py</code> 三源融合 → 两类缺口 + 机会报告 + 一键 fork+issue 起跑。</div>
|
||||
<div class="skill-meta">
|
||||
<span>🌐 arXiv</span><span>🔗 GitLink</span><span>🌍 GitHub 对照</span><span>🚀 起跑闭环</span>
|
||||
</div>
|
||||
<div style="margin-top:12px;font-size:0.78em;">
|
||||
<div style="color:#999;margin-bottom:4px;">⚙️ 三源融合</div>
|
||||
<div style="display:flex;flex-wrap:wrap;gap:4px;align-items:center;">
|
||||
<span style="background:#e6f7ff;padding:2px 8px;border-radius:10px;">🌐 arXiv 学术</span><span style="color:#bbb;">×</span>
|
||||
<span style="background:#f6ffed;padding:2px 8px;border-radius:10px;">🔗 GitLink 中文生态</span><span style="color:#bbb;">×</span>
|
||||
<span style="background:#fff3e0;padding:2px 8px;border-radius:10px;">🌍 GitHub 全球</span><span style="color:#bbb;">→</span>
|
||||
<span style="background:#fff1f0;padding:2px 8px;border-radius:10px;color:#cf1322;font-weight:600;">缺口</span>
|
||||
</div>
|
||||
</div>
|
||||
<div style="margin-top:10px;font-size:0.78em;color:#666;line-height:1.7;">
|
||||
<div style="color:#999;margin-bottom:2px;">🎯 两类缺口 + GitHub 诚实阈值</div>
|
||||
① 有理论无实现（paper→code） · ② 有需求无解答（issue→applied）<br>
|
||||
GitHub total_count：<b style="color:#cf1322;"><10</b> 稀缺→报 ｜ <b>10–50</b> 新兴→报 ｜ <b style="color:#3a3;">≥50</b> 成熟→<b>主动排除</b>（不误报机会）
|
||||
</div>
|
||||
<div style="margin-top:10px;font-size:0.8em;color:#888;border-top:1px dashed #eee;padding-top:8px;">
|
||||
诚实：GitHub ≥50 主动排除；GNN 实测 SA-HGNN 缺口 → 起跑 <b>caoweiqiong/GraphGallery#1</b>
|
||||
</div>
|
||||
<details style="margin-top:8px;font-size:0.8em;">
|
||||
<summary style="cursor:pointer;color:#fa8c16;font-weight:600;">📊 查看 GNN 真实机会报告</summary>
|
||||
<div style="margin-top:8px;padding:10px;background:#fafbfc;border-radius:6px;border-left:3px solid #fa8c16;">
|
||||
<div style="font-weight:600;margin-bottom:6px;">⚡ 图神经网络 · 机会报告（spark.py 真实输出）</div>
|
||||
<div style="font-size:0.88em;color:#666;margin-bottom:4px;">🧩 缺口 · 有理论无实现 [全球稀缺·高价值]</div>
|
||||
<div style="font-size:0.84em;color:#555;padding:6px 10px;border-left:2px solid #cf1322;background:#fff1f0;margin-bottom:8px;line-height:1.7;">
|
||||
论文 [arxiv:2607.05095] <b>FAST: Temporal GNN 训练优化</b><br>
|
||||
GitLink：0 命中 ｜ GitHub：total_count = <b>1</b> → 全球稀缺<br>
|
||||
<span style="color:#cf1322;">→ 复现并开源到 GitLink，易成本平台首个实现</span>
|
||||
</div>
|
||||
<div style="font-size:0.88em;color:#666;margin-bottom:4px;">✅ 已诚实排除（非空白）</div>
|
||||
<div style="font-size:0.84em;color:#888;padding:6px 10px;border-left:2px solid #3a3;background:#f6ffed;line-height:1.7;">
|
||||
<b>GNN Explainability 评测</b>（GitHub = <b>56</b>，全球已成熟）→ 阈值 ≥50，不报为缺口
|
||||
</div>
|
||||
</div>
|
||||
</details>
|
||||
</div>
|
||||
</div>
|
||||
<div style="margin-top:18px;padding:14px 18px;background:#fafbfc;border-radius:10px;font-size:0.85em;color:#555;border-left:4px solid #fa8c16;line-height:1.6;">
|
||||
<b style="color:#fa8c16;">🎓 学术依据</b> · 对标 <b>FAIR4RS</b>（Barker et al. 2022, <i>Nature Scientific Data</i>）+ howfairis；差异化于 Software Heritage / Papers With Code / OpenAlex。<br>
|
||||
<b style="color:#fa8c16;">📉 痛点铁证</b> · 2024 ICLR/ICML/NeurIPS 顶会论文仅 <b>19.5%</b> 提供官方代码（可复现性危机）。<br>
|
||||
<b style="color:#fa8c16;">⚙️ 可执行</b> · 两 skill 均含可独立运行的 stdlib Python 脚本（fair.py / spark.py），非纯文档；已注册 Claude Code，拉仓库即用。
|
||||
<div class="placeholder-card">
|
||||
<div class="ph-icon">🔬</div>
|
||||
<h3>即将上线</h3>
|
||||
<p>科研项目管理、学术协作工具集成等功能正在规划中，敬请期待。</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
|
@ -620,19 +528,13 @@ const WORKFLOWS = [
|
|||
features: ["params", "execute"],
|
||||
desc:"输入仓库名 → 检查现状 → 补齐缺失（README/LICENSE/标签/里程碑/Issue）",
|
||||
params: [
|
||||
{k:"owner", l:"仓库主人", t:"text", v:"yetja"},
|
||||
{k:"desc", l:"项目描述", t:"textarea", v:"一个基于 Go 的 GitLink CLI 工具，提供命令行方式管理仓库、Issue、PR 等"},
|
||||
],
|
||||
steps:["获取仓库基本信息","检查文件结构","获取已有标签和里程碑","检查分支保护状态","[AI] 对比初始化清单，识别缺失项","[AI] 生成建议的初始化内容","[AI] 自动创建缺失的标签/里程碑/Issue","[AI] 生成项目初始化报告"] },
|
||||
{ name:"multi-repo", category:"协同", triggerType:"cron", triggerOn:"0 9 * * 1",
|
||||
features: ["params", "schedule", "execute"],
|
||||
desc:"跨多个仓库的统一 Issue 追踪、PR 状态看板、Release 协调发布",
|
||||
params: [
|
||||
{k:"repos", l:"仓库列表 (owner/repo,逗号分隔)", t:"text", v:"chroe/gitlink-cli,chroe/gitlink_help_center"},
|
||||
{k:"release", l:"目标发布版本", t:"text", v:"v1.4.0"},
|
||||
{k:"wiki-repo", l:"报告发布 Wiki 仓库", t:"text", v:"chroe/gitlink-cli"},
|
||||
],
|
||||
steps:["采集多个仓库的 Issue/PR/Release/Milestone","[AI] 生成统一 Issue 追踪、PR 看板、Release 协调报告"] },
|
||||
features: ["execute"],
|
||||
desc:"跨多个仓库的统一 Issue 追踪、PR 状态看板、Release 协调",
|
||||
steps:["获取目标仓库列表","获取每个仓库的开放 Issue","获取每个仓库的开放 PR","获取每个仓库的最新 Release","获取每个仓库的里程碑进度","[AI] 生成跨仓库状态看板"] },
|
||||
{ name:"contributor-growth", category:"成长", triggerType:"cron", triggerOn:"0 9 * * 1",
|
||||
features: ["schedule", "execute"],
|
||||
desc:"追踪贡献者活动 → 排行 → 识别新星与流失风险",
|
||||
|
|
@ -991,21 +893,13 @@ async function runWfExecute(wfName, uid) {
|
|||
if (mode === 'no-ai') url += '%20--no-ai=true';
|
||||
else if (mode === 'ai') url += '%20--ai=true';
|
||||
|
||||
// Append extra params for project-init / multi-repo
|
||||
// Append extra params for project-init
|
||||
var wf = WORKFLOWS.find(function(w) { return w.name === wfName; });
|
||||
if (wf && wf.params) {
|
||||
wf.params.forEach(function(p) {
|
||||
var el = document.getElementById('p-' + uid + '-' + p.k);
|
||||
if (el && el.value.trim()) {
|
||||
var v = el.value.trim();
|
||||
if (p.k === 'owner') {
|
||||
url += '&owner=' + encodeURIComponent(v);
|
||||
} else if (wfName === 'multi-repo') {
|
||||
// Multi-repo params go as CLI args in the args string
|
||||
url += '%20--' + p.k + '%20' + encodeURIComponent(v);
|
||||
} else {
|
||||
url += '&' + p.k + '=' + encodeURIComponent(v);
|
||||
}
|
||||
url += '%20--' + p.k + '%20' + encodeURIComponent(el.value.trim());
|
||||
}
|
||||
});
|
||||
}
|
||||
|
|
@ -1085,17 +979,6 @@ async function runWfSchedule(wfName, uid) {
|
|||
if (mode === 'no-ai') url += '%20--no-ai=true';
|
||||
else if (mode === 'ai') url += '%20--ai=true';
|
||||
|
||||
// Append multi-repo params
|
||||
var wf = WORKFLOWS.find(function(w) { return w.name === wfName; });
|
||||
if (wf && wf.params && wfName === 'multi-repo') {
|
||||
wf.params.forEach(function(p) {
|
||||
var el = document.getElementById('p-' + uid + '-' + p.k);
|
||||
if (el && el.value.trim()) {
|
||||
url += '%20--' + p.k + '%20' + encodeURIComponent(el.value.trim());
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
try {
|
||||
var resp = await fetch(url);
|
||||
var data = await resp.json();
|
||||
|
|
@ -1174,10 +1057,6 @@ function stepSummary(step) {
|
|||
if (skill === 'gitlink-init-scaffold') return a.summary ? (a.summary + '').substring(0, 30) : null;
|
||||
if (skill === 'gitlink-repo') return a.summary ? (a.summary + '').substring(0, 30) : null;
|
||||
if (skill === 'gitlink-auto-merge') return a.summary ? (a.summary + '').substring(0, 30) : null;
|
||||
if (skill === 'gitlink-multi-repo') {
|
||||
var s = a.summary || {};
|
||||
return (s.repos || 0) + ' 仓库 · ' + (s.open_issues || 0) + ' Issue · ' + (s.open_prs || 0) + ' PR';
|
||||
}
|
||||
return null;
|
||||
}
|
||||
// command step: count items from data
|
||||
|
|
@ -1212,7 +1091,6 @@ function stepDetail(step) {
|
|||
if (skill === 'gitlink-triage') return renderTriageDetail(a, d);
|
||||
if (skill === 'gitlink-health') return renderHealthDetail(a);
|
||||
if (skill === 'gitlink-changelog') return renderChangelogDetail(a);
|
||||
if (skill === 'gitlink-multi-repo') return renderMultiRepoDetail(a, d);
|
||||
// generic fallback for other skills
|
||||
return '<pre style="font-size:0.8em;color:#888;max-height:200px;overflow:auto;margin:0;">' + escapeHtml(JSON.stringify(a, null, 2)) + '</pre>';
|
||||
}
|
||||
|
|
@ -1293,132 +1171,6 @@ function renderChangelogDetail(a) {
|
|||
return html;
|
||||
}
|
||||
|
||||
function renderMultiRepoDetail(a, d) {
|
||||
var html = '';
|
||||
// Summary card
|
||||
var s = a.summary || {};
|
||||
html += '<div class="wf-health-card" style="flex-wrap:wrap;">' +
|
||||
'<div class="wf-health-total" style="width:auto;padding:0 20px;border-radius:12px;">' +
|
||||
'<span class="score" style="font-size:1.1em;">' + (s.repos || 0) + '</span>' +
|
||||
'<span class="grade">个仓库</span>' +
|
||||
'</div>';
|
||||
var metrics = [
|
||||
{k:'open_issues',l:'开放Issue',color:'#fa8c16'},
|
||||
{k:'blocker_issues',l:'阻塞',color:'#ff4d4f'},
|
||||
{k:'stale_issues_7d',l:'超7天Issue',color:'#faad14'},
|
||||
{k:'open_prs',l:'开放PR',color:'#1890ff'},
|
||||
{k:'conflict_prs',l:'冲突PR',color:'#ff4d4f'},
|
||||
{k:'stale_prs_3d',l:'超3天PR',color:'#faad14'},
|
||||
];
|
||||
metrics.forEach(function(m) {
|
||||
html += '<div class="wf-health-dim" style="border-left:3px solid ' + m.color + '">' +
|
||||
'<div class="dim-name">' + m.l + '</div>' +
|
||||
'<div class="dim-score">' + (s[m.k] || 0) + '</div>' +
|
||||
'</div>';
|
||||
});
|
||||
if (s.target_release) {
|
||||
html += '<div class="wf-health-dim" style="border-left:3px solid #52c41a">' +
|
||||
'<div class="dim-name">目标版本</div>' +
|
||||
'<div class="dim-score" style="font-size:0.9em;">' + escapeHtml(s.target_release) + '</div>' +
|
||||
'</div>';
|
||||
}
|
||||
html += '</div>';
|
||||
|
||||
// Issue tracking table
|
||||
var it = a.issue_tracking || {};
|
||||
var issueRows = it.by_repo || [];
|
||||
if (issueRows.length > 0) {
|
||||
html += '<div style="margin-top:12px;"><strong style="font-size:0.85em;color:#555;">Issue 追踪</strong>' +
|
||||
'<div style="overflow-x:auto;"><table class="wf-triage-table"><thead><tr>' +
|
||||
'<th>仓库</th><th>开放</th><th>阻塞</th><th>超7天</th><th>高优先级</th>' +
|
||||
'</tr></thead><tbody>';
|
||||
issueRows.forEach(function(r) {
|
||||
html += '<tr>' +
|
||||
'<td>' + escapeHtml(r.repo || '') + '</td>' +
|
||||
'<td>' + (r.open || 0) + '</td>' +
|
||||
'<td style="color:' + (r.blockers > 0 ? '#ff4d4f' : '#999') + '">' + (r.blockers || 0) + '</td>' +
|
||||
'<td style="color:' + (r.stale_7d > 0 ? '#faad14' : '#999') + '">' + (r.stale_7d || 0) + '</td>' +
|
||||
'<td>' + (r.high_priority || 0) + '</td>' +
|
||||
'</tr>';
|
||||
});
|
||||
html += '</tbody></table></div></div>';
|
||||
}
|
||||
|
||||
// PR board
|
||||
var pr = a.pr_board || {};
|
||||
var prRows = pr.by_repo || [];
|
||||
if (prRows.length > 0) {
|
||||
html += '<div style="margin-top:12px;"><strong style="font-size:0.85em;color:#555;">PR 看板</strong>' +
|
||||
'<div style="overflow-x:auto;"><table class="wf-triage-table"><thead><tr>' +
|
||||
'<th>仓库</th><th>开放</th><th>超3天</th><th>冲突</th><th>待审查</th>' +
|
||||
'</tr></thead><tbody>';
|
||||
prRows.forEach(function(r) {
|
||||
html += '<tr>' +
|
||||
'<td>' + escapeHtml(r.repo || '') + '</td>' +
|
||||
'<td>' + (r.open || 0) + '</td>' +
|
||||
'<td style="color:' + (r.stale_3d > 0 ? '#faad14' : '#999') + '">' + (r.stale_3d || 0) + '</td>' +
|
||||
'<td style="color:' + (r.conflicts > 0 ? '#ff4d4f' : '#999') + '">' + (r.conflicts || 0) + '</td>' +
|
||||
'<td>' + (r.needs_review || 0) + '</td>' +
|
||||
'</tr>';
|
||||
});
|
||||
html += '</tbody></table></div></div>';
|
||||
}
|
||||
|
||||
// Release coordination
|
||||
var rc = a.release_coordination || {};
|
||||
if (rc.target) {
|
||||
var ready = rc.ready_to_release === true;
|
||||
var rcRows = rc.by_repo || [];
|
||||
html += '<div style="margin-top:12px;"><strong style="font-size:0.85em;color:#555;">Release 协调</strong> ' +
|
||||
'<span style="font-size:0.8em;padding:2px 8px;border-radius:10px;' + (ready ? 'background:#f6ffed;color:#52c41a;' : 'background:#fff2f0;color:#ff4d4f;') + '">' +
|
||||
(ready ? '可发布' : '存在阻塞') + '</span>';
|
||||
if (rcRows.length > 0) {
|
||||
html += '<div style="overflow-x:auto;"><table class="wf-triage-table"><thead><tr>' +
|
||||
'<th>仓库</th><th>已发布</th><th>阻塞Issue</th><th>冲突/陈旧PR</th>' +
|
||||
'</tr></thead><tbody>';
|
||||
rcRows.forEach(function(r) {
|
||||
var released = r.already_released === true;
|
||||
html += '<tr>' +
|
||||
'<td>' + escapeHtml(r.repo || '') + '</td>' +
|
||||
'<td style="color:' + (released ? '#52c41a' : '#999') + '">' + (released ? '是' : '否') + '</td>' +
|
||||
'<td style="color:' + (r.blocker_issues > 0 ? '#ff4d4f' : '#999') + '">' + (r.blocker_issues || 0) + '</td>' +
|
||||
'<td style="color:' + (r.stale_or_conflict_pr > 0 ? '#ff4d4f' : '#999') + '">' + (r.stale_or_conflict_pr || 0) + '</td>' +
|
||||
'</tr>';
|
||||
});
|
||||
html += '</tbody></table></div>';
|
||||
}
|
||||
// Blockers list
|
||||
var blockers = rc.blockers || [];
|
||||
if (blockers.length > 0) {
|
||||
html += '<div style="margin-top:6px;font-size:0.8em;">';
|
||||
blockers.forEach(function(b) {
|
||||
html += '<div style="color:#ff4d4f;">⚠ ' + escapeHtml(b.reason || '') + '</div>';
|
||||
});
|
||||
html += '</div>';
|
||||
}
|
||||
html += '</div>';
|
||||
}
|
||||
|
||||
// Recommendations
|
||||
var recs = a.recommendations || [];
|
||||
if (recs.length > 0) {
|
||||
html += '<div style="margin-top:12px;"><strong style="font-size:0.85em;color:#555;">行动建议</strong>' +
|
||||
'<ul style="font-size:0.8em;color:#888;padding-left:16px;margin:4px 0;">';
|
||||
recs.forEach(function(r) {
|
||||
html += '<li>' + escapeHtml(r) + '</li>';
|
||||
});
|
||||
html += '</ul></div>';
|
||||
}
|
||||
|
||||
// Actions feedback
|
||||
var executed = d.executed || 0;
|
||||
if (executed > 0) {
|
||||
html += '<div class="wf-step-actions"><span class="act-ok">✓ 已执行 ' + executed + ' 个操作（Wiki 发布）</span></div>';
|
||||
}
|
||||
|
||||
return html;
|
||||
}
|
||||
|
||||
function formatOutput(data) {
|
||||
if (!data.ok && data.error) return data.error;
|
||||
if (data.output === null || data.output === undefined) return '（操作完成，无返回数据）';
|
||||
|
|
|
|||
|
|
@ -32,7 +32,6 @@ func main() {
|
|||
|
||||
http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
w.Header().Set("Cache-Control", "no-cache, no-store, must-revalidate")
|
||||
w.Write(indexHTML)
|
||||
})
|
||||
|
||||
|
|
@ -45,7 +44,6 @@ func main() {
|
|||
repo := r.URL.Query().Get("repo")
|
||||
format := r.URL.Query().Get("format")
|
||||
extraArgs := r.URL.Query().Get("args")
|
||||
descParam := r.URL.Query().Get("desc")
|
||||
|
||||
if module == "" || command == "" {
|
||||
json.NewEncoder(w).Encode(RunResult{Error: "missing module or command"})
|
||||
|
|
@ -61,38 +59,14 @@ func main() {
|
|||
repo = "gitlink-cli"
|
||||
}
|
||||
}
|
||||
|
||||
args := []string{module, "+" + command, "--owner", owner, "--format", format}
|
||||
if !strings.Contains(extraArgs, "project-init") && !strings.Contains(extraArgs, "multi-repo") {
|
||||
args = append(args, "--repo", repo)
|
||||
if format == "" {
|
||||
format = "json"
|
||||
}
|
||||
|
||||
args := []string{module, "+" + command, "--owner", owner, "--repo", repo, "--format", format}
|
||||
if extraArgs != "" {
|
||||
args = append(args, parseShellArgs(extraArgs)...)
|
||||
}
|
||||
// If desc is passed as a dedicated query parameter, ensure it is
|
||||
// passed intact (bypasses the space-splitting in parseShellArgs).
|
||||
if descParam != "" {
|
||||
// Remove any --desc from parseShellArgs output (old JS path).
|
||||
filtered := make([]string, 0, len(args))
|
||||
skipNext := false
|
||||
for i, a := range args {
|
||||
if skipNext {
|
||||
skipNext = false
|
||||
continue
|
||||
}
|
||||
if a == "--desc" || a == "--description" {
|
||||
skipNext = true
|
||||
continue
|
||||
}
|
||||
if strings.HasPrefix(a, "--desc=") || strings.HasPrefix(a, "--description=") {
|
||||
continue
|
||||
}
|
||||
_ = i
|
||||
filtered = append(filtered, a)
|
||||
}
|
||||
args = filtered
|
||||
args = append(args, "--desc", descParam)
|
||||
}
|
||||
|
||||
cmdStr := "gitlink-cli " + strings.Join(args, " ")
|
||||
log.Printf("Running: %s", cmdStr)
|
||||
|
|
@ -133,6 +107,8 @@ func main() {
|
|||
log.Fatal(http.ListenAndServe(":"+port, nil))
|
||||
}
|
||||
|
||||
// parseShellArgs splits a shell-style argument string, respecting quoted values.
|
||||
// e.g. `--content "Hello Wiki!" --message "create page"` -> ["--content", "Hello Wiki!", "--message", "create page"]
|
||||
func parseShellArgs(s string) []string {
|
||||
var args []string
|
||||
var current strings.Builder
|
||||
|
|
|
|||
Binary file not shown.
Binary file not shown.
Binary file not shown.
|
|
@ -162,8 +162,7 @@ skills/
|
|||
| **gitlink-changelog** | Release Notes 自动生成 | 从 commit/PR/Issue 历史自动生成版本说明 |
|
||||
| **gitlink-triage** | Issue 智能分拣 + 新人引导 | 自动分类、打标签、分配责任人、good-first-issue 引导 |
|
||||
| **gitlink-review** | 智能代码审查 | 分析 PR diff，多视角评审 + 对抗式自检，结构化 Review 意见自动评论 |
|
||||
| **gitlink-research-fair** | 科研软件 X 光 | fair.py 抽论文/数据/复现/引用画像，四维裁决 + 真科研图谱 + 特有关键发现报告，可选处方 PR |
|
||||
| **gitlink-spark** | 文献-代码语义缺口挖掘机 | arXiv×GitLink×GitHub 三源挖"理论无实现/需求无解答"缺口，出机会报告，一键 fork+issue 起跑 |
|
||||
| **gitlink-research-fair** | 科研软件 FAIR 体检 | 5 轴 FAIR/可复现评分、体检报告卡、自动开 PR 修复缺口、SWH/commit 可复现证书 |
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,54 @@
|
|||
# gitlink-init-scaffold（项目脚手架初始化）
|
||||
|
||||
根据用户提供的项目描述，自动创建仓库并初始化标准项目脚手架。
|
||||
|
||||
## 输入参数
|
||||
|
||||
从上游数据中读取：
|
||||
|
||||
- `_owner` — 仓库所有者（必填）
|
||||
- `_desc` — 项目描述，用于生成仓库名和 README
|
||||
- `_repo` — 显式指定仓库名（可选，不提供则从描述自动生成）
|
||||
|
||||
## 操作
|
||||
|
||||
执行以下初始化步骤：
|
||||
|
||||
1. **创建仓库** — CLI `repo +create --name <name> --description <desc>`
|
||||
2. **README.md** — 根据描述生成项目 README，POST `{base}/create_file`
|
||||
3. **LICENSE** — 添加 MIT 许可证
|
||||
4. **.gitignore** — 添加 Go 项目标准 .gitignore
|
||||
5. **默认标签** — 创建 bug/enhancement/documentation 等 7 个标签
|
||||
6. **里程碑** — 创建 v0.1.0 里程碑（3 个月后到期）
|
||||
7. **初始 Issue** — 创建「项目初始化」「代码框架搭建」「首个版本发布」3 个 Issue
|
||||
|
||||
## 仓库名自动生成规则
|
||||
|
||||
- 英文描述：取前 2-3 个有效英文单词，小写连字符拼接
|
||||
- 中文描述：取前 5 个汉字
|
||||
- 默认：`new-project`
|
||||
|
||||
## 输出格式
|
||||
|
||||
```json
|
||||
{
|
||||
"analysis": {
|
||||
"repo": "owner/repo-name",
|
||||
"description": "项目描述",
|
||||
"files_created": 3,
|
||||
"labels_created": 7,
|
||||
"milestones_created": 1,
|
||||
"issues_created": 3,
|
||||
"summary": "仓库 owner/repo-name 创建完成：3 个文件，7 个标签，1 个里程碑，3 个 Issue"
|
||||
},
|
||||
"actions": [
|
||||
{"type": "cli", "module": "repo", "command": "+create", "args": {"name": "repo-name", "description": "项目描述"}},
|
||||
{"type": "api", "method": "POST", "path": "{base}/create_file", "body": {"filepath": "README.md", "content": "<base64>", "message": "docs: add README.md", "branch": "master"}},
|
||||
{"type": "api", "method": "POST", "path": "{base}/create_file", "body": {"filepath": "LICENSE", "content": "<base64>", "message": "docs: add MIT LICENSE", "branch": "master"}},
|
||||
{"type": "api", "method": "POST", "path": "{base}/create_file", "body": {"filepath": ".gitignore", "content": "<base64>", "message": "chore: add .gitignore", "branch": "master"}},
|
||||
{"type": "api", "method": "POST", "path": "{v1}/issue_tags", "body": {"name": "bug", "color": "#d73a4a"}},
|
||||
{"type": "api", "method": "POST", "path": "{v1}/milestones", "body": {"name": "v0.1.0", "description": "首个版本发布", "effective_date": "2026-10-04"}},
|
||||
{"type": "api", "method": "POST", "path": "{v1}/issues", "body": {"subject": "项目初始化", "description": "...", "status_id": 1, "priority_id": 2, "done_ratio": 0}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
|
@ -1,81 +1,105 @@
|
|||
# gitlink-research-fair v2 参考文档（科研软件 X 光）
|
||||
# gitlink-research-fair 参考文档
|
||||
|
||||
> SKILL.md 的深度参考：四维裁决细则、真 KG schema、fair.py 抽取规则、数据源实测、学术锚。
|
||||
> 本文件为 SKILL.md 的深度参考。评分细则、KG schema、OpenAlex/SWH 技术细节、学术引用库与诚实边界均在此。
|
||||
|
||||
## 一、四维裁决细则
|
||||
## 一、FAIR4RS 逐条映射
|
||||
|
||||
每维 `✅/⚠️/❌`，**必须引用 fair.py 画像字段作证据**。
|
||||
| 原则 | 含义 | 本 Skill 检查项 | GitLink 证据 | 兜底（无字段时） |
|
||||
|------|------|----------------|--------------|------------------|
|
||||
| F1 | 全局唯一持久标识 | A4 持久标识 | repo identifier/URL + commit SHA | commit-SHA 锚定 |
|
||||
| F1.2 | 版本级唯一标识 | A3 有版本发布 | `release +list` | ✗（无 release tag） |
|
||||
| F2 | 富元数据 | F1 描述/F2 topics/F3 codemeta | `repo +info` desc/topics；`file +get` codemeta.json | README 抽取（标注推断） |
|
||||
| R1.1 | 清晰可访问许可证 | A2/I2 | `repo +info` license_id；LICENSE 文件 | gitlink-license 识别 |
|
||||
| R1.2 | 详细溯源 | R1 | CITATION.cff/README 引用 | LLM 从 README 推断（标注） |
|
||||
| R2 | 对其他软件的限定引用 | R3 | 源码 SPDX/依赖清单 | gitlink-license 维度4 |
|
||||
|
||||
### 论文溯源（F2/R1.2）
|
||||
- ✅ `paper.arxiv_id` 或 `paper.doi` 非空 + `paper.title`/`venue` 抽到
|
||||
- ⚠️ 仅 `paper.title` 抽到（"Code for..." 句式），无 arxiv/DOI
|
||||
- ❌ `paper.in_readme` = False
|
||||
## 二、评分算法
|
||||
|
||||
### 数据链（FAIR 数据维度）
|
||||
- ✅ `datasets` 非空 + 至少一个有 `download_script` + 数据 license 可考
|
||||
- ⚠️ `datasets` 非空（命名）但无 download_script 或无 license
|
||||
- ❌ `datasets` 为空
|
||||
- 每项状态：`✓`(1) / `⚠`(0.5) / `✗`(0) / `⊥`(跳过，不计入分母)
|
||||
- 轴分 = Σ状态值 / (轴内项数 − ⊥项数) × 100
|
||||
- 总评 = 各轴分均值（全 ⊥ 轴记 N/A 排除）
|
||||
- 等级：A🟢≥80 / B🟡60-79 / C🔴<60
|
||||
- `confidence=low`：标注"待人工确认"，不计入分子分母
|
||||
|
||||
### 复现就绪（独立于 FAIR）
|
||||
- ✅ `repro.deps_pinned`=True + `entry_points` 非空 + `env_spec`=True + `expected_results`=True（四件齐全）
|
||||
- ⚠️ 有 `entry_points` 但缺依赖锁/环境/期望结果中任一
|
||||
- ❌ 无 `entry_points` 或无 `deps_files`
|
||||
## 三、可复现性 checklist（独立于 FAIR）
|
||||
|
||||
### 引用就绪（R1.1/R2）
|
||||
- ✅ `citation.cff` 或 `citation.codemeta` 为 True + 有版本/DOI
|
||||
- ⚠️ 仅 `citation.readme_bibtex` 非空（README 有引用文本，无机器可读文件）
|
||||
- ❌ 三者皆 False
|
||||
Rep1 环境锁（requirements 锁版本/Dockerfile/environment.yml）· Rep2 数据集说明（has_dataset/README 引用/下载脚本）· Rep3 复现步骤（README "运行/复现/Quick Start" 章节）· Rep4 版本固定（release tag 或 commit 锚定）· Rep5 入口可执行（main.py/train.py/Makefile/CLI）
|
||||
|
||||
## 二、真科研图谱 schema（Mermaid）
|
||||
## 四、KG schema（triples）
|
||||
|
||||
**节点**（按 fair.py 画像实例化，每个 dataset/entry/framework 各一个节点，不合并）：
|
||||
- `Repo`（`:::anchor` 蓝灰，锚点：repo 名 + commit）
|
||||
- `Paper`（venue + arxiv/DOI；无则红色 `Paper: none`）
|
||||
- `Method`（从 methods[]）
|
||||
- `Code`（每个 entry_point 一个节点）
|
||||
- `Dataset`（每个 dataset 一个节点；无则一个红色 `Dataset: none`）
|
||||
- `Framework`（frameworks[]；未知则黄色 `framework unknown`）
|
||||
- `Citation`（cff/bibtex 状态；无则红色 `Citation: none`）
|
||||
- `License`（有/无/冲突）
|
||||
实体：Repo, Contributor, File, Commit, Paper, Dataset, License
|
||||
关系（主谓宾三元组）：
|
||||
- (Contributor)—contributes-to→(Repo)
|
||||
- (Contributor)—authored→(Paper)
|
||||
- (Repo)—depends-on→(File/依赖)
|
||||
- (Paper)—cites→(Paper)
|
||||
- (Repo)—licensed-under→(License)
|
||||
- (Repo)—version-at→(Commit)
|
||||
- (Repo)—has→(Dataset)
|
||||
|
||||
**边**：
|
||||
- `Repo --> Paper`、`Repo --> License`
|
||||
- `Paper -->|proposes| Method`
|
||||
- `Method -->|implements| Code`
|
||||
- `Code -->|trains-on| Dataset`、`Code -->|depends-on| Framework`、`Code -->|built-by| Build(Makefile/CMake)`
|
||||
- `Paper -->|cited-via| Citation`
|
||||
- 推断/不确定的关系用虚边 `-.->`
|
||||
输出：`triples.json`（数组 of {s,p,o}）+ Mermaid `graph LR` 小图。
|
||||
|
||||
**状态色**（按对应维度裁决）：✅ `classDef ok fill:#cfe,stroke:#3a3` / ⚠️ `classDef warn fill:#ffe,stroke:#cc3` / ❌ `classDef bad fill:#fee,stroke:#c33` / 锚点 `classDef anchor fill:#eef,stroke:#336`
|
||||
## 五、OpenAlex 字段
|
||||
|
||||
**语法纪律**（违反则渲染失败）：节点 label 必须双引号 `P["..."]`；label 内禁用 `<> ? () {} | "`，可用 `: , . / - _`；边 label 仅字母/连字符；classDef 放最后。详见 SKILL.md「Mermaid 语法纪律」。
|
||||
- 端点：`https://api.openalex.org/works?search=<title>` （2025-02 起 freemium，建议带 `mailto` 参数走 polite pool）
|
||||
- 取字段：`authorships[].author.display_name`、`authorships[].institutions[].display_name`、`host_venue.display_name`（或 `primary_location.source.display_name`）、`concepts[].display_name`、`doi`
|
||||
- 降级：HTTP 429/503/无结果 → 报告卡溯源栏标"未找到关联论文"
|
||||
|
||||
## 三、fair.py 抽取规则
|
||||
## 六、SWH-ID 说明
|
||||
|
||||
- **arxiv**：三路正则（arxiv URL / `arXiv:id` / 裸 `\d{4}.\d{4,5}`），取首个命中
|
||||
- **venue**：白名单（ICML/NeurIPS/ICLR/CVPR/ACL/...）正则
|
||||
- **datasets**：已知名白名单（PACS/Visual Decathlon/Cora/ImageNet/...）+ 数据脚本（data_gen/get_data/download）
|
||||
- **repro**：依赖文件名匹配（requirements/go.mod/environment.yml/Dockerfile/setup.py）+ 入口（main/train/run*.py）+ 期望结果（accuracy/f1/results table 正则）
|
||||
- **citation**：CITATION.cff/codemeta.json/.zenodo.json 文件存在 + README `@inproceedings/@article` bibtex
|
||||
- **frameworks**：torch/tensorflow/jax/sklearn 关键词（文件名+README），无则标"未知，verify imports"
|
||||
- 完整 SWH-ID = `swh:1:dir:<hash>` 或 `swh:1:rev:<hash>`，基于 Merkle DAG，需 `swh.model`（Python）计算或 `swh-identify`
|
||||
- 环境无 `swh.model` 时：用 `git+<commit-SHA>` 作版本锚定，报告卡标注"完整 SWH-ID 需 swh-identify"
|
||||
- commit SHA 来自 `commit +list`（HEAD）
|
||||
|
||||
## 四、数据源实测（2026-07）
|
||||
## 七、学术引用库（"信服"骨架，每条对抗式核验过）
|
||||
|
||||
| 源 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| `gitlink-cli file +get` | ✅ | content 在 `data.entries.content`（纯文本） |
|
||||
| `gitlink-cli file +list` | ✅ | `data` 是字符串化 JSON，需 json.loads |
|
||||
| `gitlink-cli repo +info` | ✅ | license_id/identifier/has_dataset |
|
||||
| `gitlink-cli commit +list` | ✅ | HEAD sha |
|
||||
| OpenAlex | ❌ 已砍 | v1 弱环节（间歇 503），v2 不依赖 |
|
||||
| 支撑点 | 文献 |
|
||||
|--------|------|
|
||||
| 科研软件 FAIR 原则 F1/F1.2/F2/R1.1/R1.2/R2 可机器校验 | Barker et al. 2022, *Nature Scientific Data*, https://www.nature.com/articles/s41597-022-01710-x |
|
||||
| 可复现性危机：2024 ICLR/ICML/NeurIPS 仅 19.5% 提供官方代码 | PaperCoder, arXiv:2504.17192 (Table 9) |
|
||||
| 结构化对比表/报告卡范式 | ORKG, Jaradeh et al. K-CAP 2019 |
|
||||
| 仓库→RDF 知识图谱 schema（13 实体/47 关系/794 万三元组） | LPWC, ISWC 2023 |
|
||||
| SWH-ID 版本锚定（Merkle DAG, git 兼容） | Di Cosmo et al. ICMS 2020, PMC7340894 |
|
||||
| 作者/机构溯源用 OpenAlex REST | Priem et al. 2022, arXiv:2205.01833 |
|
||||
| 仓库级 KG 问答（四实体+SZZ+Cypher, CoT 50%→90%） | Repo-KG, arXiv:2412.03815 |
|
||||
| 科研软件可复现徽章体系 | ACM Artifact Review Badging, https://www.acm.org/publications/policies/artifact-review-badging |
|
||||
| 直接竞品 howfairis（5 维，仅 GitHub） | https://github.com/fair-software/howfairis |
|
||||
| 战略时机：PWC 不稳定 | TIB 博客 2025-10 "Papers With Code went offline"（单一二手源，pitch 前复核） |
|
||||
|
||||
## 五、学术锚（FAIR4RS）
|
||||
## 八、诚实边界（不可过度宣称）
|
||||
|
||||
四维裁决对标 **FAIR4RS**（Barker et al. 2022, Nature Sci Data）：论文溯源→F2/R1.2、数据链→FAIR-Data、复现就绪→（独立轴，FAIR 必要非充分）、引用就绪→R1.1/R2。诚实声明：这是适配版评分（社区尚无认证级自动校验器），非官方认证。
|
||||
1. FAIR4RS 自称 **aspirational**；本 Skill 是**自建 checker**（社区尚无认证级校验器），不说"套用现成标准工具"。
|
||||
2. **FAIRness ≠ 可复现性**（FAIR 必要非充分）—— Repro 单独成轴。
|
||||
3. OpenAlex 自 2025-02 起 freemium（~$1/day、需 key、100 req/s）—— 单仓演示够，批量控量。
|
||||
4. **禁止使用两条已证伪论点**：①"MSR 六分类法"、②"FAIR 分高→被引更多"因果。
|
||||
5. 文献多跑在 GitHub；"在 GitLink 上复刻"是合理外推，须真机跑通闭环。
|
||||
|
||||
## 六、诚实边界
|
||||
## 九、实测结论（live probe，2026-07-01 于 songhui18/ICCV2021）
|
||||
|
||||
1. fair.py 抽取覆盖度受 README 写法影响；非标准 README 可能漏（同时匹配多句式兜底）。
|
||||
2. 框架/方法为推断，标"推断"/"未知"，不肯定。
|
||||
3. 复现就绪是**静态**判断（依赖/入口/环境/期望结果四件套），不实际跑代码。
|
||||
4. v1 的 OpenAlex 溯源已砍（避免 503 弱环节）。
|
||||
**目标仓库**：`songhui18/ICCV2021`（显示名"ICCV2021论文复现"，URL identifier = `ICCV2021`，**注意 CLI 要用 identifier 不是中文显示名**），19⭐/17fork，3328 文件，17 个论文复现子目录，最后更新约 4 年前。
|
||||
|
||||
**关键事实**：
|
||||
- `license_id` = None；**根目录无 LICENSE**（20 个 LICENSE 全在子目录随上游代码）→ **A2 ✗**
|
||||
- releases = 0（无任何版本发布）→ **A3 ✗ / Rep4 ✗**
|
||||
- 根级文件仅 `README.md`；无根级 requirements.txt / CITATION.cff / codemeta.json / .zenodo.json
|
||||
- CITATION.cff=0、codemeta.json=0、.zenodo.json=0 → **F3 ✗ / I3 ✗ / R1 ✗**
|
||||
- requirements.txt 13 处（仅子目录）、Dockerfile 5、Makefile 3、main.py 13、train.py 16、test.py 15 → 子目录复现较完整，但**根级无统一依赖锁**
|
||||
- `has_dataset` = False → **Rep2 ✗**
|
||||
- topics = [python, jupyter notebook, cuda] → **F2 ✓**；description 详尽（≥20 字）→ **F1 ✓**
|
||||
- HEAD commit SHA = `e14ac625752171fd46c90778cf5c7b000d05307b`
|
||||
|
||||
**5 轴实测分**：F 67 · A 50 · I 17 · R 50 · Repro 40 → **总评 C 🔴 45/100**
|
||||
|
||||
| 轴 | 分 | 关键依据 |
|
||||
|----|----|----------|
|
||||
| F 可发现 | 67 | F1✓ 详尽描述 · F2✓ 3 topics · F3✗ 无 codemeta/.zenodo |
|
||||
| A 可访问 | 50 | A1✓ 公开 · A2✗ 无仓库级 license · A3✗ 无 release · A4✓ commit SHA |
|
||||
| I 可互操作 | 17 | I1⚠ 依赖散落子目录无根级锁 · I2✗ 无机器可读 license · I3✗ 无标准元数据 |
|
||||
| R 可复用 | 50 | R1✗ 无 CITATION · R2⚠ 根 README 是论文列表缺统一用法 · R4✓ 无明显敏感泄露 |
|
||||
| Repro 可复现 | 40 | Rep1⚠ 子目录 requirements 无根级锁 · Rep2✗ 无数据集说明 · Rep3⚠ 子目录有步骤无统一复现章 · Rep4✗ 无 release · Rep5✓ 入口齐全 |
|
||||
|
||||
**结论**：一个 19⭐ 的"论文复现"合集，FAIR/可复现维度仅得 C——无仓库级 license、无 release、无 CITATION、无数据集说明、依赖散落子目录。**正好印证可复现性危机**（2024 顶会仅 19.5% 提供官方代码）。处方空间大：补根级 LICENSE + CITATION.cff + 统一 requirements + 打 v1.0 release + README 复现章节。
|
||||
|
||||
> **fork→PR 链路（Task 7 实测，2026-07-01）**：✅ 跑通。`repo +fork` → `branch +create feat/fair-remediation --from master` → `file +create` 建 4 文件（LICENSE / CITATION.cff / codemeta.json / REPRODUCIBILITY.md）→ `pr +create` → **PR #1**（`caoweiqiong/ICCV2021#1`，open，id 145336）。**全程纯 API 建文件，无需克隆 3328 文件大仓**（`file +create` 支持 `--branch`）。
|
||||
> **OpenAlex 溯源（Task 7 实测）**：⚠️ 匿名搜索被限流（HTTP 503 *"rate-limited due to heavy load, use free API key"*），溯源栏降级跳过——**正好印证 freemium 边界（§八-3）**，skill 优雅降级、报告卡标注"未命中"。
|
||||
> **SWH-ID（Task 7 实测）**：环境无 `swh.model`，证书用 `git+commit e14ac62` 锚定（符合 §六降级）。
|
||||
|
|
|
|||
|
|
@ -1,140 +1,152 @@
|
|||
---
|
||||
name: gitlink-research-fair
|
||||
version: 2.0.0
|
||||
description: "科研软件 X 光：用 fair.py 真抽取 GitLink 科研仓库的论文/数据/复现/引用画像，LLM 四维裁决，输出含真科研图谱与特有关键发现的洞察报告，可选处方 PR。当用户需要深挖科研仓库的科研产物、评估可复现/可引用性时触发。"
|
||||
version: 1.0.0
|
||||
description: "科研软件 FAIR 体检：分析 GitLink 科研仓库的可发现/可访问/可互操作/可复用/可复现性，输出体检报告卡，自动开 PR 修复缺口并签发 SWH/commit 锚定的可复现证书。当用户需要评估科研仓库的 FAIR 性与可复现性、生成科研软件体检报告时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "python skills/gitlink-research-fair/scripts/fair.py --help"
|
||||
cliHelp: "gitlink-cli repo --help"
|
||||
---
|
||||
|
||||
# gitlink-research-fair（科研软件 X 光）
|
||||
# gitlink-research-fair（科研软件 FAIR 体检）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 裁决由 LLM 做出，但每条必须引用 `fair.py` 抽到的实证（arxiv id / 文件名 / deps 状态）；无实证的判断丢弃。**
|
||||
**CRITICAL — 处方（开 PR）默认预览确认；绝不自动 merge、绝不 force-push、绝不碰原仓库。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`。**
|
||||
**CRITICAL — 所有写操作（开修复 PR）默认先预览、确认后再执行；`--auto` 跳过预览但仍受护栏约束。**
|
||||
**CRITICAL — 绝不自动 merge；绝不 force-push；处方只对 fork 开 PR，绝不碰原仓库。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；四维裁决细则、真 KG schema、抽取规则见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；详细检查清单、评分算法、KG schema 与学术引用见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
## 概述
|
||||
|
||||
**科研软件 X 光**：`scripts/fair.py` 真抽取仓库内容（README/文件/依赖）→ 科研画像 JSON；LLM 对 4 个科研专属维度裁决（论文溯源/数据链/复现就绪/引用就绪），渲染**每 repo 特有的洞察报告**（裁决总览 + 真科研图谱 + 关键发现），可选处方 PR。与 `gitlink-health`（项目过程健康）正交，与 `gitlink-spark`（跨仓挖缺口）互补——本 skill **单仓深挖科研产物**。
|
||||
本 Skill 引导 AI 对任意 GitLink 科研仓库做结构化、有学术标准依据、低误报的"FAIR + 可复现性"诊断，产出**体检报告卡**，并对缺口**自动开 PR 修复**、用 **SWH/commit 锚定**签发**可复现证书**。许可证/安全子项**复用 `gitlink-license`**。四幕剧本（v1）：诊断 → 处方 → 证书。
|
||||
|
||||
## 命令接口
|
||||
|
||||
```bash
|
||||
python skills/gitlink-research-fair/scripts/fair.py --owner <owner> --repo <identifier>
|
||||
# → stdout: 科研画像 JSON {paper, datasets, repro, citation, methods, frameworks, license, head_sha, files_count}
|
||||
```
|
||||
|
||||
skill 约定参数（非 CLI flag）：
|
||||
## 命令接口（skill 约定参数，非 CLI flag）
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库（用 identifier） |
|
||||
| `--auto` | 关 | 跳过预览直接开处方 PR（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出 X 光报告，不开 PR |
|
||||
| `--refresh` | 关 | 即使有旧哨兵也重评 |
|
||||
| `--owner/--repo` | 自动从 cwd 解析 | 目标科研仓库 |
|
||||
| `--lenses` | 全 5 轴 | 子集，如 `F,A,Repro` |
|
||||
| `--auto` | 关 | 跳过预览直接开 PR（仍受护栏） |
|
||||
| `--no-fork` | 关 | 不开 PR，处方物料落本地 |
|
||||
| `--enrich` | 开 | 启用 OpenAlex 溯源（限流自动降级） |
|
||||
| `--refresh` | 关 | 即使有旧报告哨兵也重评 |
|
||||
|
||||
## 管道
|
||||
## 管道（8 步）
|
||||
|
||||
### ① 抽取（fair.py，确定性）
|
||||
`fetch_readme`（file +get）+ `fetch_file_list`（file +list）+ `fetch_repo_meta`（repo +info + commit +list 取 HEAD sha）→ `extract_paper` / `extract_datasets` / `assess_repro` / `assess_citation` / `extract_methods_frameworks` → 科研画像 JSON
|
||||
### ① 取上下文
|
||||
`repo +info`（元数据/license/topics/has_dataset）· `file +list`（关键文件清单）
|
||||
|
||||
### ② 四维裁决（LLM，读 JSON）
|
||||
论文溯源 / 数据链 / 复现就绪 / 引用就绪。每维 `✅/⚠️/❌` + **引用画像字段的具体证据**。规则见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
### ② 深采
|
||||
`file +get` 读 LICENSE/CITATION.cff/codemeta.json/README/requirements/Dockerfile · `release +list`（版本）· `commit +list`（SHA）· `issue/pr +list`（协作）· `member +list`（作者）
|
||||
|
||||
### ③ 真科研图谱（从画像生成 Mermaid）
|
||||
节点 `Paper↔Method↔Code↔Dataset↔Framework↔Citation`，带状态色（✅绿/⚠️黄/❌红）。schema 见 REFERENCE。
|
||||
### ③ FAIR 评分（M1）
|
||||
逐项评 5 轴（许可证/安全子项委托 `gitlink-license` 流程）→ `✓/✗/⚠/⊥` + 证据 + 置信度
|
||||
|
||||
### ④ 渲染 X 光报告（hero）并落盘
|
||||
裁决一行 + 真图谱 + **本 repo 特有关键发现** + 处方摘要 + 双裁决证书。**始终保存** `report-cards/<owner>-<repo>-xray.md`（绝不只在终端）。
|
||||
### ④ KG 构建（M2）
|
||||
四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License 节点 → Mermaid 小图 + triples JSON
|
||||
|
||||
### ⑤ 处方（可选）
|
||||
对 ❌/⚠️ 项生成 CITATION.cff（从 README 抽的引用）/ requirements.txt（从 import 扫）/ Dockerfile → fork → PR（默认预览）。
|
||||
### ⑤ 溯源富集（M3）
|
||||
从 README/CITATION 抽论文 → OpenAlex REST 反查作者/机构（best-effort）
|
||||
|
||||
## 四维裁决（速览，细则见 REFERENCE）
|
||||
### ⑥ 渲染报告卡（hero）并落盘
|
||||
等级 + 雷达图 + 5 轴逐项表 + 处方摘要 + 证书栏 + KG 小图 + 溯源栏。
|
||||
**始终保存为本地文件** `report-cards/<owner>-<repo>-report-card.md`（cwd 下，含哨兵）——报告卡是可归档/复查的核心产物，**无论后续是否开 PR 都必须落盘，绝不只在终端输出**。
|
||||
|
||||
| 维度 | ✅ | ⚠️ | ❌ |
|
||||
|------|---|----|----|
|
||||
| 论文溯源 | arxiv/DOI + 元数据全 | 仅 README 文字，无稳定链接 | 无论文线索 |
|
||||
| 数据链 | 命名 + 下载脚本 + license | 命名但无脚本/无 license | 未提及数据集 |
|
||||
| 复现就绪 | 依赖锁+入口+环境+期望结果齐全 | 有入口但缺依赖锁/环境/期望结果 | 无入口/无依赖 |
|
||||
| 引用就绪 | CITATION.cff/codemeta + DOI + 版本 | 仅 README 引用文本 | 无引用信息 |
|
||||
### ⑦ 处方（M4）
|
||||
对 `✗/⚠` 项生成 CITATION.cff/codemeta.json/LICENSE/复现章节 → 默认预览
|
||||
|
||||
## 报告格式（混合主视觉，hero）
|
||||
### ⑧ 发布
|
||||
报告卡已在 ⑥ 落盘（`report-cards/<owner>-<repo>-report-card.md`）。
|
||||
- **fork 模式**：确认后对 fork 开 PR（PR body 带报告卡摘要）+ 出 SWH/commit 证书
|
||||
- **`--no-fork` 或 PR 失败**：报告卡已在本地，告知用户路径，可手动粘贴或提交
|
||||
- 哨兵内嵌于报告卡（及 PR body，若开）
|
||||
|
||||
## 5 轴评分 Rubric
|
||||
|
||||
> 对标 **FAIR4RS（Nature Sci Data 2022）+ howfairis 5 维**。诚实声明：这是**适配版**评分（社区尚无认证级自动校验器），不是官方认证。**FAIR ≠ 可复现**，故 Repro 单独成轴。逐条映射与证据见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
每项判定 `✓满足 / ✗缺失 / ⚠部分 / ⊥GitLink 无该字段(跳过并标注)`，附证据来源 + 置信度。
|
||||
|
||||
| 轴 | FAIR4RS 映射 | 检查项（证据） |
|
||||
|----|--------------|----------------|
|
||||
| **F 可发现** | F1/F2 | F1 清晰描述(repo desc ≥20 字) · F2 话题/关键词(topics) · F3 标准元数据(codemeta.json/.zenodo.json) |
|
||||
| **A 可访问** | F1.2/R1.1 | A1 公开(is_public) · A2 有许可证(license_id/LICENSE)[gitlink-license] · A3 有版本发布(release tag) · A4 持久标识(commit SHA/SWH-ID) |
|
||||
| **I 可互操作** | R1.1/I | I1 依赖清单(requirements/go.mod/package.json/environment.yml) · I2 许可证机器可读(SPDX/license_id) · I3 元数据标准格式(CITATION.cff/codemeta) |
|
||||
| **R 可复用** | R1.2/R2 | R1 溯源/引用(CITATION.cff/README 引用) · R2 README 质量(安装+使用) · R3 源码声明[gitlink-license] · R4 无敏感泄露[gitlink-license] |
|
||||
| **Repro 可复现** ⭐差异轴 | （独立于 FAIR） | Rep1 环境锁(锁版本/Dockerfile) · Rep2 数据集说明(has_dataset/README 引用) · Rep3 复现步骤(README 章节) · Rep4 版本固定 · Rep5 入口可执行(main/Makefile/CLI) |
|
||||
|
||||
**评分**：轴分 = 满足项 / (总项 − ⊥项)（⚠ 计 0.5）；总评 = 5 轴均分（某轴全 ⊥ 则记 N/A 并排除）；等级 **A🟢≥80 / B🟡60-79 / C🔴<60**。`confidence=low` 标"待人工确认"，不进总评。
|
||||
|
||||
## 报告卡格式（hero 产出）
|
||||
|
||||
````markdown
|
||||
🔬 **科研软件 X 光 — <owner>/<repo>**
|
||||
🏥 **gitlink-research-fair 科研软件体检报告**
|
||||
|
||||
═══════════════════════════════════════
|
||||
论文溯源 <V> ｜ 数据链 <V> ｜ 复现就绪 <V> ｜ 引用就绪 <V>
|
||||
═══════════════════════════════════════
|
||||
**总体**：<等级> <分>/100（F · A · I · R · Repro）｜版本锚定：commit <sha>（<release 或 无>）
|
||||
**范围**：检查 19 项（✓N · ✗N · ⚠N · ⊥N，跳过：<原因>）
|
||||
|
||||
### 🧬 真科研图谱
|
||||
### 五轴雷达
|
||||
（ASCII 或 Mermaid 雷达：F/A/I/R/Repro）
|
||||
|
||||
### 逐项
|
||||
| 轴 | 项 | 状态 | 证据 |
|
||||
|---|---|:---:|---|
|
||||
| <轴> | <id 项名> | ✓/✗/⚠/⊥ | <gitlink-cli 证据> |
|
||||
|
||||
### 🔧 处方（可自动修复 N 项）
|
||||
- [<轴><id>] <生成物>（从 <来源> 推断）
|
||||
|
||||
### 📜 可复现证书
|
||||
锚定版本：git+commit <sha> ｜ FAIR: <等级> ｜ Repro: <状态>
|
||||
（完整 SWH-ID 需 swh-identify；本次用 commit-SHA 锚定）
|
||||
|
||||
### 🔗 溯源（OpenAlex）
|
||||
<作者/机构/载体 或 "未找到关联论文，已跳过">
|
||||
|
||||
### 🧬 科研关系图（KG）
|
||||
```mermaid
|
||||
graph LR
|
||||
R["repo: Feature_Critic"]:::anchor
|
||||
P["Paper: ICML 2019, arxiv:1901.11448"]:::ok
|
||||
M["Method: Feature-Critic / meta-learning"]:::ok
|
||||
C["Code: main_Feature_Critic.py"]:::ok
|
||||
D1["Dataset: PACS"]:::warn
|
||||
D2["Dataset: Visual Decathlon"]:::warn
|
||||
D3["Dataset: ImageNet"]:::warn
|
||||
F["Framework: PyTorch"]:::warn
|
||||
Ci["Citation: README bibtex, no CITATION.cff"]:::bad
|
||||
L["License: missing"]:::bad
|
||||
R --> P
|
||||
R --> L
|
||||
P -->|proposes| M
|
||||
M -->|implements| C
|
||||
C -->|trains-on| D1
|
||||
C -->|trains-on| D2
|
||||
C -->|trains-on| D3
|
||||
C -->|depends-on| F
|
||||
P -->|cited-via| Ci
|
||||
classDef ok fill:#cfe,stroke:#3a3
|
||||
classDef warn fill:#ffe,stroke:#cc3
|
||||
classDef bad fill:#fee,stroke:#c33
|
||||
classDef anchor fill:#eef,stroke:#336
|
||||
<Repo—contributes→Contributor · Repo—licensed?—? · Repo—has→Dataset?>
|
||||
```
|
||||
|
||||
### 🔍 关键发现（本 repo 特有）
|
||||
- <LLM 从画像抽出的 ≥3 条具体发现，每条引用 fair.py 字段>
|
||||
|
||||
### 🔧 处方（可选）
|
||||
- <对 ❌/⚠️ 项的修复建议>
|
||||
|
||||
### 📜 双裁决证书
|
||||
复现就绪 <V> ｜ 引用就绪 <V> ｜ 锚定 commit `<sha>`
|
||||
|
||||
---
|
||||
<!-- gitlink-research-fair v2 | repo:<owner>/<repo> | paper:<✅/⚠️/❌> | repro:<V> | cite:<V> | sha:<head> -->
|
||||
*由 gitlink-research-fair v2（科研软件 X 光）生成。*
|
||||
<!-- gitlink-research-fair v1 | repo:<owner>/<repo> | grade:<G> | sha:<head-sha> -->
|
||||
*由 gitlink-research-fair skill 生成。*
|
||||
````
|
||||
|
||||
## Mermaid 语法纪律（必读，否则图谱渲染失败）
|
||||
哨兵 `<!-- gitlink-research-fair v1 | repo | grade | sha -->` 用于幂等与"基于哪个 commit"标识。重跑检测旧哨兵 → 默认提议更新（`--refresh` 才覆盖）；`sha` 不匹配 → 提示"报告已过期，建议重评"。
|
||||
|
||||
- 节点 label **必须双引号**：`P["Paper: ..."]`，**禁止**裸 `P[<...>]` 或 `P[label with ?]`
|
||||
- label 内**禁用** `<> ? () {} | "` 等特殊字符；可用：字母、数字、空格、`: , . / - _`
|
||||
- 边 label 用 `-->|word|`，word 仅字母/连字符（如 `trains-on`、`cited-via`），不要放 `?` 或中文标点
|
||||
- **每个 dataset / entry / framework 各一个节点**（如 `D1["Dataset: PACS"]` `D2["Dataset: Visual Decathlon"]`），不要合并成一个 `D["datasets"]`
|
||||
- 缺失项用红色节点（`:::bad`）显式标出（如 `L["License: missing"]:::bad`），不省略——"缺什么"也是图谱信息
|
||||
- `classDef` 放在最后；锚点 repo 节点用 `:::anchor`（蓝灰）区分
|
||||
## 处方（M4，惊艳闭环）
|
||||
|
||||
## 处方闭环 + 护栏
|
||||
| 缺口 | 生成物 |
|
||||
|------|--------|
|
||||
| F3 缺 codemeta.json | 从 repo +info + README 生成 codemeta.json 草稿 |
|
||||
| R1 缺 CITATION.cff | 从 README/作者生成 CITATION.cff 草稿 |
|
||||
| A2 缺 license | 给 MIT / 木兰 PSL v2 模板（任选） |
|
||||
| Rep1 缺依赖锁 | 从 import 扫描建议 requirements.txt |
|
||||
| Rep3 缺复现章节 | 从入口/README 生成"复现"章节草稿 |
|
||||
|
||||
对 ❌/⚠️ 项生成修复：`CITATION.cff`（从 README 抽的引用文本构造）+ `requirements.txt`（从代码 import 扫）+ `Dockerfile`（模板）→ `repo +fork` → `pr +create`（PR body 带报告摘要）。**护栏**：默认预览；`--auto` 跳过但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 报告已落盘（④），不开 PR。
|
||||
**安全护栏**：默认全量预览 → 确认 → 对 **fork** 开一个 PR（PR body 带报告卡摘要）；`--auto` 跳过预览但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 物料落本地。所有写操作需认证。
|
||||
|
||||
## 证书（SWH/commit 锚定）
|
||||
|
||||
用 HEAD commit SHA + release tag 锚定版本。若环境有 Python `swh.model` → 算完整 SWH-ID；否则 `git+<commit-SHA>` 锚定，报告卡标注"完整 SWH-ID 需 swh-identify"。证书含：仓库、锚定版本、FAIR 等级、Repro 状态、可引用条目（对标 ACM Artifact Badge）。嵌报告卡证书栏。
|
||||
|
||||
## KG + OpenAlex（支撑栏）
|
||||
|
||||
- **KG**：四实体(Repo/Contributor/File/Commit)+Paper/Dataset/License；关系 contributes-to/authored/depends-on/cites/licensed-under/version-at。输出 Mermaid 小图 + triples JSON（schema 见 REFERENCE）。
|
||||
- **OpenAlex**：README/CITATION 抽论文 → REST `/works` 反查作者/机构/载体。降级：限流或抽不到 → 跳过，标注"未找到关联论文"。
|
||||
|
||||
## 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| README 读失败 | 降级用 file list + 元数据，标注"README 不可读，结论受限" |
|
||||
| `file +list` data 为字符串 | json.loads 解套 |
|
||||
| arxiv/DOI 抽不到 | 论文溯源判 ⚠️/❌，据实 |
|
||||
| 框架无法推断 | frameworks 标"未知"，不编造 |
|
||||
| `--repo` 用中文显示名 404 | 提示用 identifier |
|
||||
| fork/PR 失败 | 处方物料落本地，告知路径 |
|
||||
| 报告/PR 发布失败 | 报告已在 ④ 落盘，告知路径 |
|
||||
| `file +tree --recursive` 返回空 | 手动递归子目录 |
|
||||
| 无 LICENSE | A2 ✗，处方建议模板 |
|
||||
| OpenAlex 限流/无果 | 跳过溯源栏标注 |
|
||||
| `swh.model` 不可用 | commit-SHA 锚定 + 标注 |
|
||||
| 仓库过大 | 抽样文件 + "部分审查"标注 |
|
||||
| fork 失败/无写权限 | 处方物料落本地（`--no-fork`） |
|
||||
| 二进制是 npm 旧版 | 强制 `./gitlink-cli` 或 `go build` 重建 |
|
||||
| 仓库私有/无权限 | 清晰错误，不发报告 |
|
||||
| 报告/PR 发布失败 | 报告卡已在 ⑥ 落盘，告知路径，用户可手动粘贴/提交 |
|
||||
|
|
|
|||
|
|
@ -1,88 +0,0 @@
|
|||
# 示例：科研软件 X 光 — Edge-Computing-Engine（引擎类对照）
|
||||
|
||||
> 基于 `fair.py --owner Edgedev --repo Edge-Computing-Engine` 于 2026-07-07 实跑（fair.py v2.1，已修 arxiv 年份校验 + C++ 入口检测）。
|
||||
> Edge 是一个 C++ 科学计算引擎（autodiff + 神经网络模块），与 Feature_Critic（paper-code 类）形成**不同 profile 对照**，证明 X 光报告不千篇一律。
|
||||
|
||||
## Step 1：运行 fair.py 抽取科研画像
|
||||
|
||||
```bash
|
||||
python skills/gitlink-research-fair/scripts/fair.py --owner Edgedev --repo Edge-Computing-Engine
|
||||
```
|
||||
|
||||
**画像摘要**：
|
||||
| 维度 | 抽取结果 |
|
||||
|---|---|
|
||||
| 论文 | arxiv **None**（README 全文无有效 arxiv/DOI）｜ venue None ｜ 标题 "Edge-Engine"（H1，不计入 in_readme）｜ in_readme ❌ |
|
||||
| 数据集 | **空**（未提及） |
|
||||
| 复现 | 入口 **main.cpp**（v2.1 已识别 C++ 入口）｜ deps **Makefile**（deps_pinned ✓）｜ env ❌ ｜ expected_results ❌ |
|
||||
| 引用 | 无 CITATION.cff ｜ 无 README bibtex |
|
||||
| 方法/框架 | "graph" 命中 ｜ 框架未知（C++，import 推断失效） |
|
||||
| license | **LICENSE 文件存在**（Apache 2.0）｜ license_id None |
|
||||
| 锚定 | commit `8678c7c7` ｜ 132 文件 |
|
||||
|
||||
## Step 2：四维裁决（LLM 读画像）
|
||||
|
||||
**论文溯源 ❌**（无论文链接）· **数据链 ❌** · **复现就绪 ⚠️**（有 C++ 入口+Makefile 构建，但缺环境锁/期望结果）· **引用就绪 ❌**
|
||||
|
||||
## Step 3：X 光报告（全文，落盘 `report-cards/Edgedev-Edge-Computing-Engine-xray.md`）
|
||||
|
||||
````markdown
|
||||
🔬 **科研软件 X 光 — Edgedev/Edge-Computing-Engine**
|
||||
|
||||
═══════════════════════════════════════
|
||||
论文溯源 ❌ ｜ 数据链 ❌ ｜ 复现就绪 ⚠️ ｜ 引用就绪 ❌
|
||||
═══════════════════════════════════════
|
||||
|
||||
### 🧬 真科研图谱
|
||||
```mermaid
|
||||
graph LR
|
||||
R["repo: Edge-Computing-Engine"]:::anchor
|
||||
P["Paper: none, no arxiv or DOI"]:::bad
|
||||
C["Code: main.cpp / C++"]:::warn
|
||||
F["Build: Makefile, framework unknown"]:::warn
|
||||
Ci["Citation: none"]:::bad
|
||||
L["License: Apache 2.0 file but README forbids commercial use"]:::warn
|
||||
R --> P
|
||||
R --> L
|
||||
P -.->|proposes| C
|
||||
C -->|built-by| F
|
||||
P -->|cited-via| Ci
|
||||
classDef ok fill:#cfe,stroke:#3a3
|
||||
classDef warn fill:#ffe,stroke:#cc3
|
||||
classDef bad fill:#fee,stroke:#c33
|
||||
classDef anchor fill:#eef,stroke:#336
|
||||
```
|
||||
|
||||
### 🔍 关键发现（本 repo 特有）
|
||||
- **无论文**：README 全文无 arxiv/DOI 链接，论文溯源 ❌（fair.py arxiv 候选经年份校验过滤，无有效命中）
|
||||
- **LICENSE 自相矛盾**：根目录有 Apache 2.0 LICENSE，但 README 声明"本项目禁止闭源商用"——与 Apache 2.0（允许商用）冲突，复用有法律风险
|
||||
- **复现部分就绪**：fair.py 已识别 C++ 入口 `main.cpp` + 构建文件 `Makefile`，但无 Dockerfile/environment 锁环境、README 无 expected_results → ⚠️ 而非 ❌
|
||||
- 无数据集声明、无 CITATION.cff、无 README bibtex
|
||||
- 132 文件，含 autodiff / 神经网络模块
|
||||
|
||||
### 🔧 处方（可选）
|
||||
- 澄清许可证（去 README "禁止闭源商用" 或换 CC BY-NC）
|
||||
- 补 README：论文/数据集/构建命令（C++ make/make install 已有，缺期望结果）
|
||||
- 补 `Dockerfile` 锁编译器/依赖环境
|
||||
|
||||
### 📜 双裁决证书
|
||||
复现就绪 ⚠️ 部分 ｜ 引用就绪 ❌ ｜ 锚定 commit `8678c7c7`
|
||||
````
|
||||
|
||||
## Step 4：与 Feature_Critic 对照（证明不千篇一律）
|
||||
|
||||
| 维度 | Feature_Critic（paper-code） | Edge（引擎类） |
|
||||
|---|---|---|
|
||||
| 论文溯源 | ✅ arxiv 1901.11448 真溯源 | ❌ 无论文链接 |
|
||||
| 数据链 | ⚠️ PACS/Visual Decathlon 命名 | ❌ 无数据集 |
|
||||
| 复现就绪 | ⚠️ 有 .py 入口，无依赖锁 | ⚠️ 有 C++ 入口+Makefile，无环境/期望结果 |
|
||||
| 引用就绪 | ⚠️ README bibtex | ❌ 无 |
|
||||
| 真图谱 | 10 节点富图（repo/论文/方法/代码/3数据集/PyTorch/引用/license） | 6 节点多红黄（repo/无论文/main.cpp/Makefile/无引用/license冲突） |
|
||||
| 关键发现 | 论文可溯源但机器不可引用 | **LICENSE 自相矛盾** + 无论文 |
|
||||
|
||||
**两份报告内容截然不同**——X 光由 fair.py 抽取的真实画像驱动，每 repo 说出自己的话。
|
||||
|
||||
## 关键结论
|
||||
- fair.py v2.1 已修复两个已知限制：arxiv 候选加年份合法性校验（防 `5184.0000` 类伪阳性）、入口检测扩展到 `.cpp/.c/.cc/.cu` + `CMakeLists.txt`/`Makefile`（覆盖 C/C++ 科研代码）——Edge 复现就绪从 ❌ 升到 ⚠️，论文溯源 ❌ 干净不再误报
|
||||
- LICENSE 冲突这类"元数据扫描发现不了、需读 README 内容"的问题，由 LLM 裁决层补上（fair.py 抽 file 存在，LLM 读出冲突）
|
||||
- 引擎类（C++/无论文）与 paper-code 类（Python/有论文）画像迥异，报告自然分化
|
||||
|
|
@ -0,0 +1,154 @@
|
|||
# 示例：科研软件 FAIR 体检（真实数据）
|
||||
|
||||
> 基于 `songhui18/ICCV2021`（显示名"ICCV2021论文复现"，URL identifier=`ICCV2021`）于 2026-07-01 在 Claude Code 中实跑。
|
||||
> 这是 19⭐/17fork 的 ICCV 2021 论文复现合集，3328 文件、17 个论文复现子目录。
|
||||
> 一个"**可复现性**"工具去体检一个"**论文复现**"合集——主题共振。
|
||||
|
||||
---
|
||||
|
||||
## Step 1：取上下文（真实输出摘要）
|
||||
|
||||
| 项 | 实测值 |
|
||||
|---|---|
|
||||
| URL identifier | `ICCV2021`（**CLI 用 identifier，不是中文显示名**） |
|
||||
| `license_id` | `None`（**根目录无 LICENSE**；20 个 LICENSE 全在子目录随上游代码） |
|
||||
| releases | `0`（无任何版本发布） |
|
||||
| 根级文件 | 仅 `README.md` |
|
||||
| CITATION.cff / codemeta.json / .zenodo.json | 均无 |
|
||||
| requirements.txt | 13 处（**仅子目录，无根级依赖锁**） |
|
||||
| `has_dataset` | `False` |
|
||||
| topics | python, jupyter notebook, cuda |
|
||||
| description | 详尽（≥20 字） |
|
||||
| HEAD commit | `e14ac625752171fd46c90778cf5c7b000d05307b` |
|
||||
|
||||
> ⚠️ **关键踩坑**：`gitlink-cli --repo` 必须传 `identifier=ICCV2021`；用中文显示名"ICCV2021论文复现"会返回 **404**。identifier 从 `search +repos` 结果取。
|
||||
|
||||
采集命令：
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +info --owner songhui18 --repo ICCV2021 --format json
|
||||
gitlink-cli file +list --owner songhui18 --repo ICCV2021 --format json # 3328 文件扁平列表
|
||||
gitlink-cli release +list --owner songhui18 --repo ICCV2021 --format json
|
||||
gitlink-cli commit +list --owner songhui18 --repo ICCV2021 --page 1 --format json
|
||||
```
|
||||
|
||||
## Step 2：5 轴评分（真实）
|
||||
|
||||
| 轴 | 分 | 关键依据 |
|
||||
|---|---|---|
|
||||
| F 可发现 | 67 | F1✓ 详尽描述 · F2✓ 3 topics · F3✗ 无 codemeta/.zenodo |
|
||||
| A 可访问 | 50 | A1✓ 公开 · A2✗ **无仓库级 license** · A3✗ 无 release · A4✓ commit SHA |
|
||||
| I 可互操作 | 17 | I1⚠ 依赖散落子目录无根级锁 · I2✗ 无机器可读 license · I3✗ 无标准元数据 |
|
||||
| R 可复用 | 50 | R1✗ 无 CITATION · R2⚠ 根 README 是论文列表 · R4✓ 无明显敏感泄露 |
|
||||
| Repro 可复现 | 40 | Rep1⚠ · Rep2✗ 无数据集说明 · Rep3⚠ · Rep4✗ 无 release · Rep5✓ 入口齐全 |
|
||||
|
||||
**总评：C 🔴 45/100** —— 一个 19⭐ 的论文复现合集，FAIR/可复现仅得 C。
|
||||
|
||||
## Step 3：报告卡（真实全文）
|
||||
|
||||
````markdown
|
||||
🏥 **gitlink-research-fair 科研软件体检报告**
|
||||
|
||||
**总体**：C 🔴 45/100（F 67 · A 50 · I 17 · R 50 · Repro 40）｜版本锚定：commit `e14ac62`（无 release）
|
||||
**范围**：检查 19 项（✓6 · ✗8 · ⚠4 · ⊥1，⊥：R3 源码声明委托 gitlink-license 未在本轮跑）
|
||||
|
||||
### 逐项（节选）
|
||||
| 轴 | 项 | 状态 | 证据 |
|
||||
|---|---|:---:|---|
|
||||
| A | A2 有许可证 | ✗ | `license_id` 为空，根目录无 LICENSE（20 个 LICENSE 全在子目录） |
|
||||
| F | F3 标准元数据 | ✗ | 无 codemeta.json / .zenodo.json |
|
||||
| I | I1 依赖清单 | ⚠ | requirements.txt 仅在 13 个子目录，无根级统一锁 |
|
||||
| R | R1 溯源/引用 | ✗ | 无 CITATION.cff |
|
||||
| R | R3 源码声明 | ⊥ | 委托 gitlink-license，本轮未跑深度源码声明扫描 |
|
||||
| Repro | Rep2 数据集说明 | ✗ | `has_dataset=False`，README 无数据集说明 |
|
||||
| Repro | Rep5 入口可执行 | ✓ | 子目录含 train.py×16 / main.py×13 / test.py×15 |
|
||||
| F | F1 清晰描述 | ✓ | description 详尽描述 CV 顶会论文复现合集 |
|
||||
|
||||
### 🔧 处方（可自动修复 4 项）
|
||||
- [A2] 添加 LICENSE（MIT / 木兰 PSL v2）
|
||||
- [R1] 生成 CITATION.cff
|
||||
- [F3/I3] 生成 codemeta.json
|
||||
- [Rep3] 补 REPRODUCIBILITY.md 复现指南
|
||||
|
||||
### 📜 可复现证书
|
||||
锚定版本：`git+commit e14ac625752171fd46c90778cf5c7b000d05307b` ｜ FAIR: C 🔴 ｜ Repro: ⚠ 部分可复现
|
||||
（完整 SWH-ID 需 `swh-identify`；环境无 `swh.model`，本次用 commit-SHA 锚定）
|
||||
|
||||
### 🔗 溯源（OpenAlex）
|
||||
⚠️ 未命中——匿名搜索被限流（HTTP 503，需 free API key），已降级跳过（符合 freemium 边界）。
|
||||
|
||||
### 🧬 科研关系图（KG）
|
||||
```mermaid
|
||||
graph LR
|
||||
R[Repo: ICCV2021合集] -->|contributes-to| C1[Contributor: 宋辉/songhui18]
|
||||
R -->|has| D{Dataset?}:::miss
|
||||
R -->|licensed-under| L{License?}:::miss
|
||||
R -->|version-at| H[commit e14ac62]
|
||||
classDef miss fill:#fee,stroke:#c33;
|
||||
```
|
||||
|
||||
---
|
||||
<!-- gitlink-research-fair v1 | repo:songhui18/ICCV2021 | grade:C | sha:e14ac625 -->
|
||||
*由 gitlink-research-fair skill 生成。*
|
||||
````
|
||||
|
||||
## Step 4：处方 PR（真实闭环 ✅）
|
||||
|
||||
**全自动跑通**（无需克隆 3328 文件大仓，纯 API 建文件）：
|
||||
|
||||
```bash
|
||||
gitlink-cli repo +fork --owner songhui18 --repo ICCV2021 # → caoweiqiong/ICCV2021
|
||||
gitlink-cli branch +create --owner caoweiqiong --repo ICCV2021 --name feat/fair-remediation --from master
|
||||
gitlink-cli file +create --owner caoweiqiong --repo ICCV2021 --branch feat/fair-remediation \
|
||||
--path LICENSE --message "Add MIT LICENSE (fix A2)" --content "$(cat LICENSE)"
|
||||
# … 同样建 CITATION.cff / codemeta.json / REPRODUCIBILITY.md
|
||||
gitlink-cli pr +create --owner caoweiqiong --repo ICCV2021 --head feat/fair-remediation --base master \
|
||||
--title "Improve research FAIRness & reproducibility (gitlink-research-fair 处方)" \
|
||||
-b "$(cat pr_body.md)"
|
||||
```
|
||||
|
||||
**PR**：https://www.gitlink.org.cn/caoweiqiong/ICCV2021/pulls/1 （`pull_request_number: 1`, id `145336`, open）
|
||||
|
||||
PR body 含体检报告卡摘要 + 修复表。新增 4 文件：
|
||||
|
||||
| 文件 | 修复项 | FAIR 原则 |
|
||||
|------|--------|-----------|
|
||||
| `LICENSE` | 补 MIT 许可证 | R1.1 / A2 |
|
||||
| `CITATION.cff` | 补引用信息 | R1.2 / R1 |
|
||||
| `codemeta.json` | 补标准元数据 | F2 / F3 / I3 |
|
||||
| `REPRODUCIBILITY.md` | 补复现指南 | Rep3 |
|
||||
|
||||
**预期效果**：合并后 A2/F3/I3/R1/Rep3 由 ✗/⚠ → ✓，总分 **C 45 → B ~75**。
|
||||
|
||||
## Step 5：证书
|
||||
|
||||
- **锚定版本**：`git+commit e14ac625752171fd46c90778cf5c7b000d05307b`（HEAD，无 release）
|
||||
- **SWH-ID**：环境无 `swh.model`，用 commit-SHA 锚定（完整 SWH-ID 需 `swh-identify`）
|
||||
- **结论**：FAIR C 🔴 · Repro ⚠ 部分可复现 —— 可作为"待改进科研软件"的基线快照，供后续 release 后重评对比。
|
||||
|
||||
---
|
||||
|
||||
## 对照：有 license 的仓库（证明评分区分度）
|
||||
|
||||
对 `leejt/GraphGallery`（图神经网络多框架开发工具，Python，有 license）跑同一 rubric：
|
||||
|
||||
| 轴 | songhui18/ICCV2021 | leejt/GraphGallery |
|
||||
|---|---|---|
|
||||
| F | 67 | 67 |
|
||||
| A | **50**（无 license） | **75**（✓ 根级 LICENSE） |
|
||||
| I | 17（无根级依赖锁） | 67（✓ 根级 requirements.txt + setup.py） |
|
||||
| R | 50 | 67 |
|
||||
| Repro | 40 | 70（✓ setup.py 可安装） |
|
||||
| **总评** | **C 🔴 45** | **B 🟡 69** |
|
||||
|
||||
**区分度 +24 分**，主要由 **A2 license + I1/Rep1 打包可安装** 拉开。rubric 正确奖励"有 license + 可安装"的仓库。（GraphGallery 仍缺 CITATION/release，故是 B 非 A——评分诚实，不虚高。）
|
||||
|
||||
---
|
||||
|
||||
## 关键结论
|
||||
|
||||
1. **主题共振**：用"可复现性"工具体检"论文复现"合集——一个 19⭐ 的真实科研仓库竟只得 C，**正好印证可复现性危机**（2024 顶会仅 19.5% 提供官方代码）。
|
||||
2. **闭环可用**：fork → 建分支 → `file +create` 建修复文件 → 开 PR，**全程纯 API、无需克隆大仓**，处方 PR 真实落地。
|
||||
3. **诚实降级**：OpenAlex 匿名限流(503)→溯源跳过；无 `swh.model`→commit-SHA 锚定——都是设计内的优雅降级，**不掩盖、不编造**。
|
||||
4. **评分有区分度**：C 45（无 license 合集）vs B 69（有 license 工具），rubric 行为正确。
|
||||
5. **差异于 howfairis**：GitLink 原生 + 报告卡 + **自动修复闭环** + SWH 证书 + OpenAlex 溯源，howfairis 只跑 GitHub 且只打分不修复。
|
||||
|
|
@ -1,168 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""gitlink-research-fair v2: research software X-ray. Extract a research profile from a GitLink repo. Stdlib only."""
|
||||
import argparse, json, os, sys, subprocess, re
|
||||
|
||||
_ARXIV_PATS = [
|
||||
r'https?://arxiv\.org/(?:abs|pdf)/(\d{4}\.\d{4,5})',
|
||||
r'arXiv:(\d{4}\.\d{4,5})',
|
||||
r'\b(\d{4}\.\d{4,5})\b',
|
||||
]
|
||||
_DOI_PAT = r'10\.\d{4,9}/\S+'
|
||||
_VENUES = ["ICML", "NeurIPS", "NIPS", "ICLR", "CVPR", "ICCV", "ECCV", "ACL", "EMNLP",
|
||||
"NAACL", "KDD", "WWW", "AAAI", "IJCAI", "SIGGRAPH", "Nature", "Science"]
|
||||
def _valid_arxiv_id(aid):
|
||||
"""Validate arxiv id YYMM.NNNNN: year 07-26 (2007-2026 arxiv new format), month 01-12.
|
||||
Rejects false positives like 5184.0000 (mm=84)."""
|
||||
m = re.match(r"(\d{2})(\d{2})\.\d{4,5}$", aid)
|
||||
if not m:
|
||||
return False
|
||||
yy, mm = int(m.group(1)), int(m.group(2))
|
||||
return (7 <= yy <= 26) and (1 <= mm <= 12)
|
||||
|
||||
_KNOWN_DATASETS = ["Visual Decathlon", "PACS", "ImageNet", "CIFAR-10", "CIFAR-100", "CIFAR",
|
||||
"Cora", "Citeseer", "Pubmed", "MNIST", "COCO", "QM9", "ZINC", "OGB", "ogbn",
|
||||
"Wikipedia", "PPI", "Reddit", "Amazon", "Yelp", "MUTAG"]
|
||||
|
||||
def extract_paper(readme):
|
||||
"""Extract paper provenance (arxiv/doi/title/venue) from README text."""
|
||||
if not readme:
|
||||
return {"in_readme": False, "arxiv_id": None, "arxiv_url": None, "doi": None,
|
||||
"title": None, "authors": [], "venue": None}
|
||||
arxiv_id = arxiv_url = None
|
||||
for pat in _ARXIV_PATS:
|
||||
for m in re.finditer(pat, readme):
|
||||
cand = m.group(1)
|
||||
if _valid_arxiv_id(cand):
|
||||
arxiv_id = cand
|
||||
arxiv_url = f"https://arxiv.org/abs/{cand}"
|
||||
break
|
||||
if arxiv_id:
|
||||
break
|
||||
doi = None
|
||||
m = re.search(_DOI_PAT, readme)
|
||||
if m:
|
||||
doi = m.group(0).rstrip(").,;]")
|
||||
venue = None
|
||||
for v in _VENUES:
|
||||
if re.search(rf"\b{re.escape(v)}\b", readme):
|
||||
venue = v; break
|
||||
code_for = (re.search(r"[Cc]ode (?:for|of)\s+'([^']+)'", readme)
|
||||
or re.search(r'[Cc]ode (?:for|of)\s+"([^"]+)"', readme))
|
||||
h1 = re.search(r"^\s*#\s+(.+)$", readme, re.M)
|
||||
title = (code_for.group(1).strip() if code_for
|
||||
else (h1.group(1).strip() if h1 else None))
|
||||
return {"in_readme": bool(arxiv_id or doi or code_for), "arxiv_id": arxiv_id,
|
||||
"arxiv_url": arxiv_url, "doi": doi, "title": title, "authors": [], "venue": venue}
|
||||
|
||||
def extract_datasets(readme, files):
|
||||
"""Identify referenced datasets (known-name match + data scripts)."""
|
||||
text = readme or ""
|
||||
found = []
|
||||
for ds in _KNOWN_DATASETS:
|
||||
if re.search(rf"\b{re.escape(ds)}\b", text, re.I):
|
||||
found.append(ds)
|
||||
scripts = [f for f in files if any(k in (f or "").lower()
|
||||
for k in ["data_gen", "get_data", "download", "prepare_data", "data_load"])]
|
||||
return [{"name": ds, "evidence": "mentioned in README",
|
||||
"download_script": scripts[:2] or None, "license": None} for ds in found]
|
||||
|
||||
def assess_repro(files, readme):
|
||||
"""Static reproducibility readiness: deps + entry + env + expected results.
|
||||
Supports Python (.py) AND C/C++ (.cpp/.c/.cc/.cu + Makefile/CMake) repos."""
|
||||
name_set = {(f or "") for f in files}
|
||||
deps_candidates = ["requirements.txt", "environment.yml", "go.mod", "package.json",
|
||||
"Dockerfile", "setup.py", "pyproject.toml", "CMakeLists.txt", "Makefile"]
|
||||
deps_files = [f for f in deps_candidates if f in name_set]
|
||||
entry_re = re.compile(r"(main|train|run|demo)_?\w*\.(py|cpp|c|cc|cu)$", re.I)
|
||||
entry_points = sorted([f for f in name_set if entry_re.match(f or "")])
|
||||
env_spec = any(f in ("Dockerfile", "environment.yml") for f in deps_files)
|
||||
expected = bool(re.search(r"(accuracy|f1\b|bleu|rouge|results?\s*(table|in section)|table\s*\d)",
|
||||
readme or "", re.I))
|
||||
return {"deps_files": deps_files, "deps_pinned": bool(deps_files),
|
||||
"entry_points": entry_points[:5], "expected_results": expected, "env_spec": env_spec}
|
||||
|
||||
def assess_citation(files, readme):
|
||||
"""Citation readiness: CITATION.cff / codemeta / zenodo + README bibtex."""
|
||||
name_set = {(f or "") for f in files}
|
||||
m = re.search(r"@(inproceedings|article|misc|book)\{[^}]+\}", readme or "", re.S | re.I)
|
||||
return {"cff": "CITATION.cff" in name_set,
|
||||
"codemeta": "codemeta.json" in name_set,
|
||||
"zenodo": ".zenodo.json" in name_set,
|
||||
"readme_bibtex": (m.group(0)[:200] if m else None)}
|
||||
|
||||
def extract_methods_frameworks(files, readme):
|
||||
"""Infer methods + frameworks from filenames + README."""
|
||||
text = " ".join(files) + " " + (readme or "")
|
||||
frameworks = []
|
||||
if re.search(r"\b(torch|pytorch|nn\.module)\b", text, re.I): frameworks.append("PyTorch")
|
||||
if re.search(r"\b(tensorflow|tf\.|keras)\b", text, re.I): frameworks.append("TensorFlow")
|
||||
if re.search(r"\b(jax|flax|haiku)\b", text, re.I): frameworks.append("JAX")
|
||||
if re.search(r"\b(sklearn|scikit-learn)\b", text, re.I): frameworks.append("scikit-learn")
|
||||
methods = []
|
||||
for kw in ["attention", "transformer", "contrastive", "meta-learning", "federated",
|
||||
"graph", "convolution", "resnet", "gan", "diffusion", "reinforcement",
|
||||
"domain generalisation", "domain generalization"]:
|
||||
if re.search(rf"\b{kw}", text, re.I):
|
||||
methods.append(kw)
|
||||
return {"methods": methods[:6],
|
||||
"frameworks": frameworks or ["unknown (infer from filenames; verify imports)"]}
|
||||
|
||||
def _gitlink(*args):
|
||||
"""Run gitlink-cli with json output; return parsed dict (UTF-8 safe)."""
|
||||
r = subprocess.run(["gitlink-cli"] + list(args) + ["--format", "json"],
|
||||
capture_output=True, text=True, encoding="utf-8", errors="replace", timeout=60)
|
||||
raw = r.stdout
|
||||
i = raw.find("{")
|
||||
return json.loads(raw[i:]) if i >= 0 else {}
|
||||
|
||||
def fetch_readme(owner, repo):
|
||||
d = _gitlink("file", "+get", "--owner", owner, "--repo", repo, "--path", "README.md")
|
||||
ent = (d.get("data", {}) or {}).get("entries", {}) or {}
|
||||
return ent.get("content", "") if isinstance(ent, dict) else ""
|
||||
|
||||
def fetch_file_list(owner, repo):
|
||||
d = _gitlink("file", "+list", "--owner", owner, "--repo", repo)
|
||||
fd = d.get("data", "[]")
|
||||
if isinstance(fd, str):
|
||||
fd = json.loads(fd)
|
||||
return [f.get("name") for f in fd if isinstance(f, dict)] if isinstance(fd, list) else []
|
||||
|
||||
def fetch_repo_meta(owner, repo):
|
||||
info = _gitlink("repo", "+info", "--owner", owner, "--repo", repo)
|
||||
comm = _gitlink("commit", "+list", "--owner", owner, "--repo", repo, "--page", "1")
|
||||
cd = comm.get("data", {})
|
||||
cl = cd.get("commits") if isinstance(cd, dict) else None
|
||||
head = (cl[0].get("sha") if cl and isinstance(cl, list) and cl else None)
|
||||
d = info.get("data", {}) or {}
|
||||
return {"identifier": d.get("identifier"), "license_id": d.get("license_id"),
|
||||
"has_dataset": d.get("has_dataset"), "head_sha": head}
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description="gitlink-research-fair v2: research software X-ray")
|
||||
ap.add_argument("--owner", required=True)
|
||||
ap.add_argument("--repo", required=True)
|
||||
args = ap.parse_args()
|
||||
|
||||
readme = fetch_readme(args.owner, args.repo)
|
||||
files = fetch_file_list(args.owner, args.repo)
|
||||
meta = fetch_repo_meta(args.owner, args.repo)
|
||||
mf = extract_methods_frameworks(files, readme)
|
||||
profile = {
|
||||
"repo": f"{args.owner}/{args.repo}",
|
||||
"head_sha": meta.get("head_sha"),
|
||||
"paper": extract_paper(readme),
|
||||
"datasets": extract_datasets(readme, files),
|
||||
"repro": assess_repro(files, readme),
|
||||
"citation": assess_citation(files, readme),
|
||||
"methods": mf["methods"],
|
||||
"frameworks": mf["frameworks"],
|
||||
"license": {"file": any("LICENSE" in (f or "") for f in files),
|
||||
"license_id": meta.get("license_id")},
|
||||
"files_count": len(files),
|
||||
}
|
||||
json.dump(profile, sys.stdout, ensure_ascii=False, indent=2)
|
||||
sys.stdout.write("\n")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -1,82 +0,0 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
"""Assert-based unit tests for fair.py pure extractors. Run: python test_fair.py"""
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(__file__))
|
||||
from fair import extract_paper, extract_datasets, assess_repro, assess_citation, extract_methods_frameworks
|
||||
|
||||
SAMPLE_README = """# Feature_Critic
|
||||
Demo code for 'Feature-Critic Networks for Heterogeneous Domain Generalisation'.
|
||||
This paper is located at https://arxiv.org/abs/1901.11448 and will appear in ICML 2019.
|
||||
Evaluated on PACS and Visual Decathlon.
|
||||
|
||||
@inproceedings{li2019feature,
|
||||
title={Feature-Critic Networks},
|
||||
booktitle={ICML}}
|
||||
"""
|
||||
|
||||
SAMPLE_FILES = ["README.md", "main_Feature_Critic.py", "main_baseline.py", "model_PACS.py",
|
||||
"alexnet.py", "resnet.py", "vggnet.py", "data_gen_PACS.py", "get_model_dataset.sh", "utils.py"]
|
||||
|
||||
def test_extract_paper():
|
||||
p = extract_paper(SAMPLE_README)
|
||||
assert p["arxiv_id"] == "1901.11448", p["arxiv_id"]
|
||||
assert p["arxiv_url"] == "https://arxiv.org/abs/1901.11448"
|
||||
assert p["venue"] == "ICML"
|
||||
assert p["in_readme"] is True
|
||||
print("test_extract_paper OK")
|
||||
|
||||
def test_extract_paper_none():
|
||||
p = extract_paper("# Hello\nA normal project with no paper.")
|
||||
assert p["in_readme"] in (False, True) # title-only may set in_readme; arxiv must be None
|
||||
assert p["arxiv_id"] is None
|
||||
print("test_extract_paper_none OK")
|
||||
|
||||
def test_extract_datasets():
|
||||
ds = extract_datasets(SAMPLE_README, SAMPLE_FILES)
|
||||
names = [d["name"] for d in ds]
|
||||
assert "PACS" in names and "Visual Decathlon" in names
|
||||
pacs = [d for d in ds if d["name"] == "PACS"][0]
|
||||
assert pacs["download_script"] and "data_gen_PACS.py" in pacs["download_script"]
|
||||
print("test_extract_datasets OK")
|
||||
|
||||
def test_assess_repro():
|
||||
files = ["README.md", "main_Feature_Critic.py", "requirements.txt", "model_PACS.py"]
|
||||
r = assess_repro(files, SAMPLE_README)
|
||||
assert "requirements.txt" in r["deps_files"]
|
||||
assert r["deps_pinned"] is True
|
||||
assert "main_Feature_Critic.py" in r["entry_points"]
|
||||
assert r["expected_results"] is False # SAMPLE_README has no accuracy/results table
|
||||
print("test_assess_repro OK")
|
||||
|
||||
def test_assess_citation():
|
||||
c = assess_citation(SAMPLE_FILES, SAMPLE_README)
|
||||
assert c["cff"] is False and c["codemeta"] is False
|
||||
assert c["readme_bibtex"] and "@inproceedings" in c["readme_bibtex"]
|
||||
print("test_assess_citation OK")
|
||||
|
||||
def test_extract_methods_frameworks():
|
||||
mf = extract_methods_frameworks(SAMPLE_FILES, SAMPLE_README)
|
||||
assert "domain generalisation" in mf["methods"], mf["methods"] # SAMPLE_README 提到 Domain Generalisation
|
||||
assert isinstance(mf["frameworks"], list)
|
||||
print("test_extract_methods_frameworks OK")
|
||||
|
||||
def test_arxiv_validation():
|
||||
p = extract_paper("see version 5184.0000 released")
|
||||
assert p["arxiv_id"] is None, ("5184.0000 应被年份校验拒绝", p["arxiv_id"])
|
||||
p2 = extract_paper("paper at https://arxiv.org/abs/1901.11448 ICML")
|
||||
assert p2["arxiv_id"] == "1901.11448"
|
||||
p3 = extract_paper("# MyRepo\njust a project")
|
||||
assert p3["in_readme"] is False, ("H1 单独不应算论文证据", p3["in_readme"])
|
||||
print("test_arxiv_validation OK")
|
||||
|
||||
def test_cpp_entry_detection():
|
||||
r = assess_repro(["main.cpp", "Makefile", "utils.cpp"], "")
|
||||
assert "main.cpp" in r["entry_points"], r["entry_points"]
|
||||
assert "Makefile" in r["deps_files"], r["deps_files"]
|
||||
print("test_cpp_entry_detection OK")
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_extract_paper(); test_extract_paper_none(); test_extract_datasets()
|
||||
test_assess_repro(); test_assess_citation(); test_extract_methods_frameworks()
|
||||
test_arxiv_validation(); test_cpp_entry_detection()
|
||||
print("ALL TESTS PASSED")
|
||||
|
|
@ -1,63 +0,0 @@
|
|||
# gitlink-spark 参考文档
|
||||
|
||||
> SKILL.md 的深度参考：缺口分类细则、GitHub 阈值、LLM prompt 模板、数据源实测、诚实边界。
|
||||
|
||||
## 一、缺口分类法细则
|
||||
|
||||
### 类型 A 有理论无实现
|
||||
- 输入：arXiv 论文方法 M（title + method_keywords）
|
||||
- GitLink 侧：`search +repos -k <M>` 命中数（0 或极少，如 ≤2）
|
||||
- GitHub 侧：`total_count`（按 §二阈值分级）
|
||||
- 判定为"缺口"条件：GitLink ≤2 **且** GitHub < 50（全球稀缺或新兴）
|
||||
|
||||
### 类型 B 有需求无解答
|
||||
- 输入：领域仓库的 open issue（`issue +list`，排除关闭）
|
||||
- LLM 筛"研究性痛点"：含性能/可扩展性/新场景/新数据集，排除安装报错/使用咨询
|
||||
- 判定：GitLink 无现成实现解此痛点 **且** GitHub 无成熟开源方案
|
||||
|
||||
## 二、GitHub 全球对照阈值
|
||||
|
||||
| total_count | 分级 | 报告 |
|
||||
|---|---|---|
|
||||
| < 10 | 全球稀缺 | 高价值缺口 |
|
||||
| 10–50 | 新兴 | 中等缺口 |
|
||||
| ≥ 50 | 已成熟 | **不报为空白**，列入"已诚实排除" |
|
||||
|
||||
spark.py 缓存 GitHub 结果（按 query key），避免重复调用。
|
||||
|
||||
## 三、LLM 缺口匹配 prompt 模板
|
||||
|
||||
```
|
||||
你是科研机会发现助手。下面是 spark.py 抓取的真实数据（JSON）。
|
||||
请跨"arXiv 论文 × GitLink 仓库/issues × GitHub 全球计数"找出语义缺口，输出机会报告。
|
||||
|
||||
规则：
|
||||
1. 只输出可溯源到下列数据的缺口；每张缺口卡带"实证三件套"。
|
||||
2. 类型A（理论无实现）：论文 M 的 GitLink 命中≤2 且 GitHub total_count<50 才报；
|
||||
GitHub ≥50 的论文列入"已诚实排除"，不报为空白。
|
||||
3. 类型B（需求无解答）：只挑研究性痛点 issue，排除使用/安装类。
|
||||
4. 每张卡给一句"机会建议"（主观），但证据必须客观可查。
|
||||
5. 宁可少报，不误报。
|
||||
|
||||
数据：
|
||||
{spark.py 的 JSON}
|
||||
```
|
||||
|
||||
## 四、数据源实测结论（2026-07-01）
|
||||
|
||||
| 源 | 状态 | 备注 |
|
||||
|---|---|---|
|
||||
| arXiv API | ✅ 必须 HTTPS | HTTP 被沙箱阻断返回 0 字节 |
|
||||
| gitlink-cli search +repos | ✅ | 用 identifier/关键词 |
|
||||
| gitlink-cli issue +list | ✅ | 逐仓库，绕开 search+issues |
|
||||
| gitlink-cli search +issues | ❌ 返回 HTML | 不可用，勿用 |
|
||||
| GitHub Search API | ✅ | 未认证 10/min；GITHUB_TOKEN 提额 |
|
||||
| OpenAlex | ⚠ 间歇 503 | best-effort 富集，降级跳过 |
|
||||
|
||||
## 五、诚实边界
|
||||
|
||||
1. **GitLink 覆盖薄**：缺口卡明确标 "GitLink 0 / GitHub N"；GitHub ≥50 不报为空白。
|
||||
2. LLM 缺口必须可溯源实证三件套，否则丢弃。
|
||||
3. arXiv 仅覆盖 CS/物理等，报告标注学科范围。
|
||||
4. GitHub 未认证 10/min：spark.py sleep 7s + 缓存；建议 demo 设 GITHUB_TOKEN。
|
||||
5. "机会建议"为主观启发，标注"需研究者自行判断"。
|
||||
|
|
@ -1,132 +0,0 @@
|
|||
---
|
||||
name: gitlink-spark
|
||||
version: 1.0.0
|
||||
description: "文献-代码语义缺口挖掘机：给一个研究领域，跨 arXiv × GitLink × GitHub 三源挖'有理论无实现/有需求无解答'语义缺口，输出空白学术机会报告，可一键 fork+issue 起跑。当用户需要找研究点、发现论文-代码空白、科研选题启发时触发。"
|
||||
metadata:
|
||||
requires:
|
||||
bins: ["gitlink-cli"]
|
||||
cliHelp: "python skills/gitlink-spark/scripts/spark.py --help"
|
||||
---
|
||||
|
||||
# gitlink-spark（文献-代码语义缺口挖掘机）
|
||||
|
||||
**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
|
||||
**CRITICAL — 缺口由 LLM 推断，但每条必须带实证三件套（论文 id / GitLink 查询+命中数 / GitHub total_count）；无实证的缺口必须丢弃。**
|
||||
**CRITICAL — 起跑（fork+issue）默认预览确认；绝不自动 merge、绝不 force-push、绝不碰原仓库。**
|
||||
**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`。**
|
||||
|
||||
> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)；缺口分类法、GitHub 阈值、LLM prompt 模板见 [`REFERENCE.md`](REFERENCE.md)。
|
||||
|
||||
## 概述
|
||||
|
||||
给一个研究领域，跨 **arXiv（学术）× GitLink（中文生态）× GitHub（全球）** 三源挖两类语义缺口，输出**空白学术机会报告**。`scripts/spark.py` 抓真实数据（JSON），LLM 做语义匹配并附实证三件套。与 `gitlink-research-fair`（评估已有）组成"科研辅助双联装"——本 skill 负责**发现空白**。
|
||||
|
||||
## 命令接口
|
||||
|
||||
数据融合脚本（可独立运行）：
|
||||
|
||||
```bash
|
||||
python skills/gitlink-spark/scripts/spark.py --field "图神经网络" [--max-papers 10] [--gap-type both|theory|demand] [--github-token $GITHUB_TOKEN]
|
||||
# → stdout: 融合 JSON {papers, gitlink_repos, gitlink_issues, github_counts}
|
||||
```
|
||||
|
||||
skill 约定参数（非 CLI flag）：
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `--field` | 必填 | 研究领域 |
|
||||
| `--gap-type` | `both` | `theory` / `demand` / `both` |
|
||||
| `--max-papers` | 10 | arXiv 抓取上限（控 GitHub 调用） |
|
||||
| `--auto` | 关 | 跳过预览直接起跑（仍受护栏） |
|
||||
| `--no-fork` | 关 | 只出报告，不起跑 |
|
||||
|
||||
## 管道（4 阶段）
|
||||
|
||||
### ① 学术采
|
||||
`spark.py` 调 arXiv HTTPS API 抓领域近 90 天论文（标题/摘要/arxiv id/方法关键词）
|
||||
|
||||
### ② GitLink 采
|
||||
`spark.py` 调 `gitlink-cli search +repos` 抓领域仓库；对每个仓库 `issue +list --state open` 抓 open issue（**不用 search +issues**，它返回 HTML）
|
||||
|
||||
### ③ 全球对照
|
||||
`spark.py` 调 GitHub Search API 对每个论文方法查 `total_count` + Top3 仓库（限流+缓存）
|
||||
|
||||
### ④ 缺口匹配（LLM）+ 报告落盘 + 起跑
|
||||
读 spark.py 的 JSON → 语义匹配两类缺口（每张带实证三件套）→ 渲染机会报告。
|
||||
**始终保存为本地文件** `report-cards/spark-<field>-report.md`（cwd 下，含哨兵）——机会报告无论是否起跑都**必须落盘，绝不只在终端输出**。
|
||||
（可选）fork+issue 起跑：见下方"起跑动作"。
|
||||
|
||||
## 两类缺口 + 实证三件套（信服核心）
|
||||
|
||||
每张缺口卡**必须**带齐三件套，否则丢弃（防 LLM 编造）：
|
||||
|
||||
### 类型 A：有理论无实现（paper → code gap）
|
||||
- **三件套**：① 论文 arxiv id + 标题 + 发表日期 ② GitLink 搜索查询串 + 命中数（0/极少） ③ GitHub total_count + Top 仓库
|
||||
- LLM 判定：论文提出方法 M；GitLink 实现 0/极少；GitHub 按下方阈值分级
|
||||
|
||||
### 类型 B：有需求无解答（open issue → applied gap）
|
||||
- **三件套**：① issue URL + 主题 + 讨论人数/状态 ② GitLink 无现成实现解此痛点 ③ GitHub 是否有成熟开源解
|
||||
- 降噪：LLM 只挑"研究性痛点"（性能/可扩展/新场景），排除"安装报错"等使用问题
|
||||
|
||||
## GitHub 全球对照阈值（诚实核心，硬需求）
|
||||
|
||||
防止"GitLink 0 ≠ 全球空白"误导。对每个"理论无实现"候选按 GitHub total_count 分级：
|
||||
|
||||
| GitHub total_count | 分级 | 报告行为 |
|
||||
|--------------------|------|----------|
|
||||
| `< 10` | 全球稀缺（真空白） | 报为高价值缺口 |
|
||||
| `10–50` | 新兴（部分空白） | 报为中等缺口（"GitLink 空白，全球新兴"） |
|
||||
| `≥ 50` | 全球已成熟 | **不报为空白**，列入"✅ 已诚实排除" |
|
||||
|
||||
宁可少报，不误报机会。
|
||||
|
||||
## 机会报告格式（hero）
|
||||
|
||||
````markdown
|
||||
⚡ **gitlink-spark 机会报告：<field>**
|
||||
|
||||
学术采：arXiv 近 90 天 N 篇 ｜ GitLink 仓库 M 个 ｜ GitHub 全球基线已对照
|
||||
生成时间：YYYY-MM-DD
|
||||
|
||||
### 🧩 缺口 1 · 有理论无实现 [全球稀缺·高价值]
|
||||
**论文**：[arxiv:<id>] "<title>" (<date>)
|
||||
**方法关键词**：<...>
|
||||
**GitLink**：search "<query>" → **0 命中**（查询串留底）
|
||||
**GitHub 全球**：total_count = **N**（Top: <repo> <stars>⭐）→ 稀缺
|
||||
**机会建议**：<LLM 一句话>
|
||||
**起跑**：[按钮] fork 基准 <repo> → 创建 issue 粘论文伪代码
|
||||
|
||||
### 🧩 缺口 2 · 有需求无解答 [应用机会]
|
||||
**Issue**：<repo>#<n> "<subject>"（N 人讨论, open）
|
||||
**痛点**：<LLM 归纳>
|
||||
**GitLink / GitHub**：均无成熟解
|
||||
**机会建议**：<LLM 一句话>
|
||||
|
||||
### ✅ 已诚实排除（非空白）
|
||||
- 论文 Y：GitLink 虽 0，但 GitHub 已 N 个 → 全球已成熟，不报
|
||||
|
||||
---
|
||||
<!-- gitlink-spark v1 | field:<field> | gaps:<N> | date:<YYYY-MM-DD> -->
|
||||
*由 gitlink-spark skill 生成。*
|
||||
````
|
||||
|
||||
## 起跑动作 + 护栏
|
||||
|
||||
选定一张"理论无实现"缺口卡 → 确认 →
|
||||
1. `gitlink-cli repo +fork` 最近基准（GitHub Top 仓库或 GitLink 最近实现）
|
||||
2. LLM 从 arXiv 论文抓 Algorithm/Pseudocode 节
|
||||
3. `gitlink-cli issue +create` 在 fork 建复现 todo issue（body 粘伪代码 + 报告卡摘要）
|
||||
|
||||
**护栏**：默认预览；`--auto` 跳过但**永不 force-push、永不碰原仓库、永不自动 merge**；`--no-fork` 报告已落盘（④），不起跑。
|
||||
|
||||
## 错误处理与降级
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| arXiv 空/超时 | HTTPS 重试；仍空降级用既有论文 |
|
||||
| `search +issues` 返回 HTML | 不用，改逐仓库 `issue +list` |
|
||||
| GitHub 未认证限流(10/min) | spark.py sleep ~7s；建议设 `GITHUB_TOKEN` |
|
||||
| GitHub 查询失败 | 该论文标"对照失败"，不进缺口判定 |
|
||||
| OpenAlex 503 | 跳过引用富集 |
|
||||
| LLM 缺口无三件套 | 置信度门控丢弃 |
|
||||
| fork/issue 起跑失败 | 报告已在 ④ 落盘，告知路径；另输出 fork 目标 + 伪代码文本供手动起跑 |
|
||||
|
|
@ -1,79 +0,0 @@
|
|||
# 示例：gitlink-spark GNN 缺口挖掘（真实数据）
|
||||
|
||||
> 基于 `python spark.py --field "graph neural network" --max-papers 8 --gap-type both` 于 2026-07-06 实跑。
|
||||
> 一个"文献-代码语义缺口挖掘机"在 GNN 领域跑出真实研究机会。
|
||||
|
||||
---
|
||||
|
||||
## Step 1：数据采集（真实）
|
||||
|
||||
| 源 | 结果 |
|
||||
|---|---|
|
||||
| arXiv（abs:"graph neural network"，近期） | 8 篇 |
|
||||
| GitLink 仓库（search +repos） | 20 个（多为通用 graph/network；GNN 专项如 `leejt/GraphGallery` 需定向） |
|
||||
| GitLink open issues（定向 GraphGallery） | 5 条"图神经网络模型论文复现"请求 |
|
||||
| GitHub 全球对照 | 每篇论文方法 total_count |
|
||||
|
||||
采集命令：
|
||||
```bash
|
||||
python skills/gitlink-spark/scripts/spark.py --field "graph neural network" --max-papers 8 --gap-type both
|
||||
```
|
||||
|
||||
## Step 2：机会报告（真实全文）
|
||||
|
||||
````markdown
|
||||
⚡ **gitlink-spark 机会报告：图神经网络**
|
||||
|
||||
学术采：arXiv 近期 8 篇 ｜ GitLink 仓库 20 个（+ 定向 GraphGallery） ｜ GitHub 全球基线已对照
|
||||
生成时间：2026-07-06
|
||||
|
||||
### 🧩 缺口 1 · 有理论无实现 [全球稀缺·高价值]
|
||||
**论文**：[arxiv:2607.02063] "SA-HGNN: Sample-Adaptive Hyperbolic Graph Neural Networks"
|
||||
**方法关键词**：sample-adaptive, hyperbolic
|
||||
**GitLink**：search "hyperbolic graph neural network" → **0 命中**（20 仓库无一实现双曲 GNN）
|
||||
**GitHub 全球**：total_count = **0**（"sample-adaptive hyperbolic"）→ 全球稀缺
|
||||
**机会建议**：GitLink 生态空白 × 全球稀缺 → 复现并开源到 GitLink，易成本平台首个双曲 GNN 实现
|
||||
**起跑**：✅ `caoweiqiong/GraphGallery#1`（已 fork GraphGallery 基准 + 建复现 todo）
|
||||
|
||||
### 🧩 缺口 2 · 有理论无实现 [新兴·中等价值]
|
||||
**论文**：[arxiv:2607.00671] "Multi-Label Node Classification with Label Influence"
|
||||
**方法关键词**：multi-label, node, classification
|
||||
**GitLink**：0 专项实现
|
||||
**GitHub 全球**：total_count = **16** → 新兴（10–50 tier）
|
||||
**机会建议**：全球新兴方向，GitLink 空白 → 可做中文生态较早的完整实现
|
||||
|
||||
### 🧩 缺口 3 · 有需求无解答 [应用机会]
|
||||
**Issue**：`leejt/GraphGallery#1` "图神经网络模型论文复现：节点分类任务" · `#2` 链路预测 · `#3` 节点嵌入（共 5 条 open，均为复现请求；状态"新增"，讨论 0 人）
|
||||
**痛点**：GraphGallery 用户在 GitLink 上明确请求 GNN 多任务论文复现（节点分类 / 链路预测 / 嵌入），现有框架未覆盖这些专项
|
||||
**GitLink / GitHub**：GraphGallery 提供框架但无这些专项复现；GitHub 零散有
|
||||
**机会建议**：针对 GitLink 用户实际复现需求，补齐节点分类 / 链路预测论文复现专题
|
||||
|
||||
### ✅ 已诚实排除（非空白）
|
||||
- **Graph Attention Network (GAT)**：GitHub total_count = **1543**（含 PetarV-/GAT 3534⭐）→ 全球已成熟，**不报为空白**
|
||||
- 本轮 8 篇 arXiv 论文中 **3 篇离题**（Cayley 图数学 / WavePID 中微子物理 / EO-Agents LLM）—— arXiv 宽泛匹配所致，已过滤不计入
|
||||
|
||||
---
|
||||
<!-- gitlink-spark v1 | field:图神经网络 | gaps:3 | date:2026-07-06 -->
|
||||
*由 gitlink-spark skill 生成。*
|
||||
````
|
||||
|
||||
## Step 3：起跑（真实闭环 ✅）
|
||||
|
||||
选定缺口 1（SA-HGNN，全球稀缺）起跑：
|
||||
```bash
|
||||
gitlink-cli repo +fork --owner leejt --repo GraphGallery # → caoweiqiong/GraphGallery
|
||||
gitlink-cli issue +create --owner caoweiqiong --repo GraphGallery \
|
||||
--title "Reproduction todo: SA-HGNN (Sample-Adaptive Hyperbolic GNN) [gitlink-spark 起跑]" \
|
||||
--body "<缺口三件套 + 复现计划 + 论文 arxiv 链接>"
|
||||
```
|
||||
**issue**：`caoweiqiong/GraphGallery#1`（fork 基准 + 复现 todo，含 SA-HGNN 论文方法 + 基于 GraphGallery 的复现步骤）
|
||||
|
||||
## Step 4：关键结论
|
||||
|
||||
1. **三源融合真实可跑**：arXiv（8 篇）× GitLink（20 仓库 + 定向 GraphGallery）× GitHub（每方法 total_count）。
|
||||
2. **GitHub 阈值生效（诚实核心）**：GAT(1543) → 已诚实排除；SA-HGNN(0) → 高价值缺口；Multi-Label Node Cls(16) → 新兴。三级分明。
|
||||
3. **离题论文诚实过滤**：arXiv 宽泛匹配混入 3 篇非 GNN（数学/物理/LLM），报告明示排除，不滥竽充数。
|
||||
4. **demand 侧诚实降级**：spark.py 自动扫描的 20 个 GitLink 仓库多为通用 graph/network、0 研究 issue；定向 GraphGallery 发现真实复现需求（5 条）。报告如实标注"自动 0 / 定向发现"。
|
||||
5. **起跑闭环对称 fair**：fair 给已有仓库开修复 PR；spark 给缺口方向 fork 基准 + 复现 todo issue——都是"诊断→行动"闭环。
|
||||
6. **每条缺口可溯源**到 spark.py 的 JSON（arxiv id / 查询串 / total_count 全可查）。
|
||||
```
|
||||
|
|
@ -1,157 +0,0 @@
|
|||
#!/usr/bin/env python3
|
||||
# -*- coding: utf-8 -*-
|
||||
"""gitlink-spark data fusion: arXiv x GitLink x GitHub -> JSON on stdout. Stdlib only."""
|
||||
import argparse, json, os, sys, time, subprocess, urllib.request, urllib.parse, re
|
||||
from xml.etree import ElementTree as ET
|
||||
|
||||
ARXIV_ENDPOINT = "https://export.arxiv.org/api/query"
|
||||
GITHUB_ENDPOINT = "https://api.github.com/search/repositories"
|
||||
|
||||
_NS = {"a": "http://www.w3.org/2005/Atom"}
|
||||
|
||||
def parse_arxiv_atom(xml_text):
|
||||
"""Parse arXiv Atom feed -> list of {arxiv_id, title, abstract, published}."""
|
||||
root = ET.fromstring(xml_text)
|
||||
papers = []
|
||||
for e in root.findall("a:entry", _NS):
|
||||
aid = (e.find("a:id", _NS).text or "").strip().split("/")[-1]
|
||||
title = re.sub(r"\s+", " ", (e.find("a:title", _NS).text or "").strip())
|
||||
summary = re.sub(r"\s+", " ", (e.find("a:summary", _NS).text or "").strip())
|
||||
pub = (e.find("a:published", _NS).text or "")[:10]
|
||||
papers.append({"arxiv_id": aid, "title": title, "abstract": summary, "published": pub})
|
||||
return papers
|
||||
|
||||
def parse_github_search(json_text):
|
||||
"""Parse GitHub search JSON -> {total_count, top:[{full_name, stars}]}."""
|
||||
d = json.loads(json_text)
|
||||
return {
|
||||
"total_count": d.get("total_count", 0),
|
||||
"top": [{"full_name": r.get("full_name"), "stars": r.get("stargazers_count")}
|
||||
for r in (d.get("items") or [])[:3]],
|
||||
}
|
||||
|
||||
def extract_method_keywords(title, abstract, max_k=5):
|
||||
"""Crude keyword extraction for GitHub/arXiv query."""
|
||||
text = (title + " " + abstract).lower()
|
||||
stop = {"the", "a", "an", "of", "for", "and", "to", "in", "on", "with", "via",
|
||||
"based", "using", "by", "from", "as", "is", "are", "we", "our", "this",
|
||||
"that", "propose", "proposed", "paper", "method", "approach", "novel", "new"}
|
||||
tokens = re.findall(r"[a-z][a-z0-9-]+", text)
|
||||
seen = set(); out = []
|
||||
for t in tokens:
|
||||
if t in stop or len(t) < 3 or t in seen:
|
||||
continue
|
||||
seen.add(t); out.append(t)
|
||||
if len(out) >= max_k:
|
||||
break
|
||||
return out
|
||||
|
||||
def fetch_arxiv(field, max_papers=10):
|
||||
"""Search arXiv (HTTPS) for recent papers in field. Returns list of paper dicts."""
|
||||
q = urllib.parse.quote(f'abs:"{field}"')
|
||||
url = (f"{ARXIV_ENDPOINT}?search_query={q}&max_results={max_papers}"
|
||||
f"&sortBy=submittedDate&sortOrder=descending")
|
||||
with urllib.request.urlopen(url, timeout=30) as r:
|
||||
papers = parse_arxiv_atom(r.read().decode("utf-8", "replace"))
|
||||
for p in papers:
|
||||
p["method_keywords"] = extract_method_keywords(p["title"], p["abstract"])
|
||||
return papers
|
||||
|
||||
def _gitlink(*args):
|
||||
"""Run gitlink-cli with json output; return parsed dict (UTF-8 safe)."""
|
||||
r = subprocess.run(["gitlink-cli"] + list(args) + ["--format", "json"],
|
||||
capture_output=True, text=True, encoding="utf-8",
|
||||
errors="replace", timeout=60)
|
||||
raw = r.stdout
|
||||
i = raw.find("{")
|
||||
return json.loads(raw[i:]) if i >= 0 else {}
|
||||
|
||||
def fetch_gitlink_repos(field):
|
||||
"""gitlink-cli search +repos -> list of {owner, repo(identifier), name, desc, topics}."""
|
||||
d = _gitlink("search", "+repos", "-k", field)
|
||||
projs = d.get("data", {}).get("projects", []) or []
|
||||
out = []
|
||||
for p in projs:
|
||||
out.append({
|
||||
"owner": (p.get("author") or {}).get("login"),
|
||||
"repo": p.get("identifier"),
|
||||
"name": p.get("name"),
|
||||
"desc": p.get("description"),
|
||||
"topics": [t.get("name") if isinstance(t, dict) else t for t in (p.get("topics") or [])],
|
||||
})
|
||||
return out
|
||||
|
||||
def fetch_gitlink_issues(repos, max_per_repo=10):
|
||||
"""Per-repo issue +list (open) -> list of {repo, number, subject, status, participants}.
|
||||
Works around search +issues returning HTML."""
|
||||
out = []
|
||||
for r in repos:
|
||||
if not (r.get("owner") and r.get("repo")):
|
||||
continue
|
||||
d = _gitlink("issue", "+list", "--owner", r["owner"], "--repo", r["repo"], "--state", "open")
|
||||
data = d.get("data", {}) or {}
|
||||
issues = data.get("issues") or []
|
||||
for it in issues[:max_per_repo]:
|
||||
st = (it.get("status") or {})
|
||||
if st.get("name") == "关闭":
|
||||
continue
|
||||
out.append({
|
||||
"repo": f'{r["owner"]}/{r["repo"]}',
|
||||
"number": it.get("project_issues_index") or it.get("number"),
|
||||
"subject": it.get("subject"),
|
||||
"status": st.get("name"),
|
||||
"participants": it.get("participants_count") or 0,
|
||||
})
|
||||
return out
|
||||
|
||||
_GH_CACHE = {}
|
||||
|
||||
def fetch_github_count(query, token=None, throttle=True):
|
||||
"""GitHub search total_count + top3 for a query. Caches + throttles (10/min unauth)."""
|
||||
if query in _GH_CACHE:
|
||||
return _GH_CACHE[query]
|
||||
url = f"{GITHUB_ENDPOINT}?q={urllib.parse.quote(query)}&per_page=3&sort=stars"
|
||||
req = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json",
|
||||
"User-Agent": "gitlink-spark/1.0"})
|
||||
if token:
|
||||
req.add_header("Authorization", f"Bearer {token}")
|
||||
try:
|
||||
with urllib.request.urlopen(req, timeout=25) as r:
|
||||
res = parse_github_search(r.read().decode("utf-8", "replace"))
|
||||
except Exception as e:
|
||||
res = {"total_count": None, "top": [], "error": str(e)[:80]}
|
||||
if throttle and not token:
|
||||
time.sleep(7) # unauthenticated = 10 req/min
|
||||
_GH_CACHE[query] = res
|
||||
return res
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description="gitlink-spark data fusion")
|
||||
ap.add_argument("--field", required=True)
|
||||
ap.add_argument("--max-papers", type=int, default=10)
|
||||
ap.add_argument("--gap-type", default="both", choices=["both", "theory", "demand"])
|
||||
ap.add_argument("--github-token", default=os.environ.get("GITHUB_TOKEN"))
|
||||
args = ap.parse_args()
|
||||
|
||||
papers = fetch_arxiv(args.field, args.max_papers)
|
||||
grepos = fetch_gitlink_repos(args.field)
|
||||
gissues = fetch_gitlink_issues(grepos) if args.gap_type in ("both", "demand") else []
|
||||
gh_counts = {}
|
||||
if args.gap_type in ("both", "theory"):
|
||||
for p in papers:
|
||||
mk = p.get("method_keywords") or []
|
||||
q = " ".join(mk[:3]) if mk else p["title"][:40] # method keywords = implementation prevalence (NOT exact-title)
|
||||
gh_counts[q] = fetch_github_count(q, args.github_token)
|
||||
|
||||
out = {
|
||||
"field": args.field,
|
||||
"papers": papers,
|
||||
"gitlink_repos": grepos,
|
||||
"gitlink_issues": gissues,
|
||||
"github_counts": gh_counts,
|
||||
}
|
||||
json.dump(out, sys.stdout, ensure_ascii=False, indent=2)
|
||||
sys.stdout.write("\n")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
|
@ -1,51 +0,0 @@
|
|||
# -*- coding: utf-8 -*-
|
||||
"""Assert-based unit tests for spark.py pure parsers. Run: python test_spark.py"""
|
||||
import sys, os
|
||||
sys.path.insert(0, os.path.dirname(__file__))
|
||||
from spark import parse_arxiv_atom, parse_github_search, extract_method_keywords
|
||||
|
||||
SAMPLE_ARXIV = """<?xml version="1.0" encoding="UTF-8"?>
|
||||
<feed xmlns="http://www.w3.org/2005/Atom">
|
||||
<entry>
|
||||
<id>http://arxiv.org/abs/2403.12345v1</id>
|
||||
<title>Graph Attention Networks with Sparse Transformers</title>
|
||||
<summary>We propose a new graph attention mechanism using sparse attention.</summary>
|
||||
<published>2024-03-15T00:00:00Z</published>
|
||||
</entry>
|
||||
<entry>
|
||||
<id>http://arxiv.org/abs/2404.99999v2</id>
|
||||
<title>Federated Learning on Heterogeneous Graphs</title>
|
||||
<summary>A federated approach for heterogeneous graph neural networks.</summary>
|
||||
<published>2024-04-20T00:00:00Z</published>
|
||||
</entry>
|
||||
</feed>"""
|
||||
|
||||
def test_parse_arxiv_atom():
|
||||
papers = parse_arxiv_atom(SAMPLE_ARXIV)
|
||||
assert len(papers) == 2, f"expected 2 papers, got {len(papers)}"
|
||||
assert papers[0]["arxiv_id"] == "2403.12345v1", papers[0]["arxiv_id"]
|
||||
assert "Graph Attention" in papers[0]["title"]
|
||||
assert papers[0]["published"] == "2024-03-15"
|
||||
assert "sparse" in papers[0]["abstract"].lower()
|
||||
print("test_parse_arxiv_atom OK")
|
||||
|
||||
def test_parse_github_search():
|
||||
import json as _j
|
||||
sample = _j.dumps({"total_count": 1543, "items": [{"full_name": "a/b", "stargazers_count": 3534}]})
|
||||
res = parse_github_search(sample)
|
||||
assert res["total_count"] == 1543
|
||||
assert res["top"][0]["full_name"] == "a/b"
|
||||
assert res["top"][0]["stars"] == 3534
|
||||
print("test_parse_github_search OK")
|
||||
|
||||
def test_extract_method_keywords():
|
||||
kws = extract_method_keywords("Graph Attention Networks", "We propose a sparse attention mechanism for graphs.", max_k=5)
|
||||
assert "graph" in kws and "attention" in kws
|
||||
assert "propose" not in kws # 'propose' is in the stop set, filtered out
|
||||
print("test_extract_method_keywords OK")
|
||||
|
||||
if __name__ == "__main__":
|
||||
test_parse_arxiv_atom()
|
||||
test_parse_github_search()
|
||||
test_extract_method_keywords()
|
||||
print("ALL TESTS PASSED")
|
||||
|
|
@ -27,8 +27,7 @@ metadata:
|
|||
> - Issue 智能分拣 → [`../gitlink-triage/SKILL.md`](../gitlink-triage/SKILL.md)
|
||||
> - Release Notes 生成 → [`../gitlink-changelog/SKILL.md`](../gitlink-changelog/SKILL.md)
|
||||
> - 项目健康报告 → [`../gitlink-health/SKILL.md`](../gitlink-health/SKILL.md)
|
||||
> - 科研软件 X 光（fair v2） → [`../gitlink-research-fair/SKILL.md`](../gitlink-research-fair/SKILL.md)
|
||||
> - 文献-代码缺口挖掘（科研选题） → [`../gitlink-spark/SKILL.md`](../gitlink-spark/SKILL.md)
|
||||
> - 科研软件 FAIR 体检 → [`../gitlink-research-fair/SKILL.md`](../gitlink-research-fair/SKILL.md)
|
||||
|
||||
## 工作流 1：PR 全流程
|
||||
|
||||
|
|
|
|||
Binary file not shown.
|
|
@ -0,0 +1,632 @@
|
|||
# 任务 A — commit Shortcut + 展示工程
|
||||
|
||||
> 你是组长。本任务包含两部分：**新增 commit Shortcut**（4个命令）+ **搭建功能展示网页**。
|
||||
> 已有人帮你完成了 milestone/webhook/label 三个模块（共16个命令），你需要在此基础上继续开发。
|
||||
|
||||
---
|
||||
|
||||
## 项目信息
|
||||
|
||||
- **仓库地址**：https://gitlink.org.cn/chroe/gitlink-cli
|
||||
- **克隆**：`git clone https://gitlink.org.cn/chroe/gitlink-cli.git`
|
||||
- **Go 版本**：1.26+（安装：`winget install GoLang.Go`，装完后重启终端）
|
||||
- **设置国内代理**（必须，否则下不了依赖）：`go env -w GOPROXY=https://goproxy.cn,direct`
|
||||
- **构建**：`go build -o gitlink-cli.exe .`
|
||||
- **运行测试**：`go test ./... -v`
|
||||
- **GitLink Token**：`7f1586abeacdf7dd9ad488d38bf09d5d08359642`
|
||||
- **ECS 服务器**：39.108.139.73，用户 root，密码 Wyj051019
|
||||
|
||||
---
|
||||
|
||||
## 第一部分：新增 commit Shortcut
|
||||
|
||||
### 要创建的文件
|
||||
|
||||
```
|
||||
shortcuts/commit/commit.go # 4个命令
|
||||
shortcuts/commit/commit_test.go # 单元测试
|
||||
```
|
||||
|
||||
### 要修改的文件
|
||||
|
||||
```
|
||||
shortcuts/register.go # 注册 commit 分组
|
||||
```
|
||||
|
||||
### commit.go 完整代码
|
||||
|
||||
在 `shortcuts/commit/` 目录下创建 `commit.go`，内容如下：
|
||||
|
||||
```go
|
||||
package commit
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"net/url"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
func Shortcuts() []*common.Shortcut {
|
||||
return []*common.Shortcut{
|
||||
{
|
||||
Name: "list",
|
||||
Description: "List commits in a repository",
|
||||
Flags: []common.Flag{
|
||||
{Name: "sha", Short: "s", Usage: "Branch, tag, or commit SHA"},
|
||||
{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
|
||||
{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("page", ctx.Arg("page"))
|
||||
q.Set("limit", ctx.Arg("limit"))
|
||||
if sha := ctx.Arg("sha"); sha != "" {
|
||||
q.Set("sha", sha)
|
||||
}
|
||||
env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/commits", ctx.Owner, ctx.Repo), q)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return ctx.Output(env)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "view",
|
||||
Description: "View files changed in a commit",
|
||||
Flags: []common.Flag{
|
||||
{Name: "sha", Short: "s", Usage: "Commit SHA", Required: true},
|
||||
{Name: "page", Short: "p", Usage: "Page number", Default: "1"},
|
||||
{Name: "limit", Short: "l", Usage: "Items per page", Default: "20"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
sha, err := ctx.RequireArg("sha")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("page", ctx.Arg("page"))
|
||||
q.Set("limit", ctx.Arg("limit"))
|
||||
env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/commits/%s/files", ctx.Owner, ctx.Repo, sha), q)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return ctx.Output(env)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "diff",
|
||||
Description: "Show diff for a commit",
|
||||
Flags: []common.Flag{
|
||||
{Name: "sha", Short: "s", Usage: "Commit SHA", Required: true},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
sha, err := ctx.RequireArg("sha")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
env, err := ctx.CallAPI("GET", fmt.Sprintf("/v1/%s/%s/commits/%s/diff", ctx.Owner, ctx.Repo, sha), nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return ctx.Output(env)
|
||||
},
|
||||
},
|
||||
{
|
||||
Name: "blame",
|
||||
Description: "Show blame for a file",
|
||||
Flags: []common.Flag{
|
||||
{Name: "path", Short: "p", Usage: "File path", Required: true},
|
||||
{Name: "sha", Short: "s", Usage: "Branch, tag, or commit SHA", Default: "master"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
filePath, err := ctx.RequireArg("path")
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
q := url.Values{}
|
||||
q.Set("filepath", filePath)
|
||||
q.Set("sha", ctx.Arg("sha"))
|
||||
env, err := ctx.CallAPIWithQuery("GET", fmt.Sprintf("/v1/%s/%s/blame", ctx.Owner, ctx.Repo), q)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
return ctx.Output(env)
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### commit_test.go 完整代码
|
||||
|
||||
```go
|
||||
package commit
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/client"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
func TestCommitList(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method != "GET" || r.URL.Path != "/v1/owner/repo/commits.json" {
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"total_count": 1,
|
||||
"commits": []map[string]interface{}{
|
||||
{"sha": "abc123", "commit_message": "initial commit"},
|
||||
},
|
||||
})
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runCommitShortcut(t, server, "list", map[string]string{})
|
||||
if err != nil {
|
||||
t.Fatalf("list shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCommitView(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method == "GET" && r.URL.Path == "/v1/owner/repo/commits/abc123/files.json" {
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"file_nums": 1,
|
||||
"files": []map[string]interface{}{
|
||||
{"filename": "main.go", "additions": 10, "deletions": 2},
|
||||
},
|
||||
})
|
||||
return
|
||||
}
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runCommitShortcut(t, server, "view", map[string]string{"sha": "abc123"})
|
||||
if err != nil {
|
||||
t.Fatalf("view shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCommitDiff(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method == "GET" && r.URL.Path == "/v1/owner/repo/commits/abc123/diff.json" {
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"file_nums": 1,
|
||||
"total_addition": 10,
|
||||
"total_deletion": 2,
|
||||
"files": []map[string]interface{}{{"name": "main.go"}},
|
||||
})
|
||||
return
|
||||
}
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runCommitShortcut(t, server, "diff", map[string]string{"sha": "abc123"})
|
||||
if err != nil {
|
||||
t.Fatalf("diff shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestCommitBlame(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method == "GET" && r.URL.Path == "/v1/owner/repo/blame.json" {
|
||||
if r.URL.Query().Get("filepath") != "main.go" {
|
||||
t.Fatalf("expected filepath=main.go, got %s", r.URL.Query().Get("filepath"))
|
||||
}
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"file_name": "main.go",
|
||||
"num_lines": 20,
|
||||
})
|
||||
return
|
||||
}
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runCommitShortcut(t, server, "blame", map[string]string{"path": "main.go"})
|
||||
if err != nil {
|
||||
t.Fatalf("blame shortcut failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func runCommitShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
|
||||
t.Helper()
|
||||
shortcut := findCommitShortcut(t, name)
|
||||
ctx := &common.RuntimeContext{
|
||||
Client: &client.Client{
|
||||
HTTP: server.Client(),
|
||||
BaseURL: server.URL,
|
||||
},
|
||||
Owner: "owner",
|
||||
Repo: "repo",
|
||||
Format: "json",
|
||||
Args: args,
|
||||
}
|
||||
return shortcut.Run(ctx)
|
||||
}
|
||||
|
||||
func findCommitShortcut(t *testing.T, name string) *common.Shortcut {
|
||||
t.Helper()
|
||||
for _, s := range Shortcuts() {
|
||||
if s.Name == name {
|
||||
return s
|
||||
}
|
||||
}
|
||||
t.Fatalf("shortcut %q not found", name)
|
||||
return nil
|
||||
}
|
||||
|
||||
func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
|
||||
t.Helper()
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
if err := json.NewEncoder(w).Encode(payload); err != nil {
|
||||
t.Fatalf("failed to write response: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func assertEqual(t *testing.T, got, want interface{}) {
|
||||
t.Helper()
|
||||
if fmt.Sprintf("%v", got) != fmt.Sprintf("%v", want) {
|
||||
t.Fatalf("got %v (%T), want %v (%T)", got, got, want, want)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 修改 register.go
|
||||
|
||||
在 `shortcuts/register.go` 中做两处修改：
|
||||
|
||||
**1. 增加 import（在已有 import 块中加一行）：**
|
||||
|
||||
在 import 块中加入：
|
||||
```go
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/commit"
|
||||
```
|
||||
|
||||
**2. 在 groups map 中增加一行：**
|
||||
|
||||
```go
|
||||
"commit": commit.Shortcuts(),
|
||||
```
|
||||
|
||||
**3. 在 descriptions map 中增加一行：**
|
||||
|
||||
```go
|
||||
"commit": "Commit operations",
|
||||
```
|
||||
|
||||
### 验证步骤
|
||||
|
||||
```bash
|
||||
# 1. 运行测试
|
||||
go test ./shortcuts/commit/ -v
|
||||
|
||||
# 2. 构建
|
||||
go build -o gitlink-cli.exe .
|
||||
|
||||
# 3. 用真实 API 测试
|
||||
export GITLINK_TOKEN=7f1586abeacdf7dd9ad488d38bf09d5d08359642
|
||||
|
||||
# 列出提交
|
||||
./gitlink-cli.exe commit +list --owner chroe --repo gitlink_help_center
|
||||
|
||||
# 查看某个提交的文件变更（用上面返回的 sha）
|
||||
./gitlink-cli.exe commit +view --owner chroe --repo gitlink_help_center --sha <某个sha>
|
||||
|
||||
# 查看 diff
|
||||
./gitlink-cli.exe commit +diff --owner chroe --repo gitlink_help_center --sha <某个sha>
|
||||
|
||||
# 查看 blame
|
||||
./gitlink-cli.exe commit +blame --owner chroe --repo gitlink_help_center --path README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第二部分：搭建功能展示网页
|
||||
|
||||
### 目标
|
||||
|
||||
在 ECS 服务器（39.108.139.73）上部署一个 Web 页面，展示你们组的全部新增功能。
|
||||
|
||||
### 展示页内容
|
||||
|
||||
创建一个 HTML 文件，包含以下内容：
|
||||
|
||||
1. **项目标题**：gitlink-cli 功能增强 — 软件演化课程实践
|
||||
2. **团队信息**：3人，各自负责的模块
|
||||
3. **新增功能总览表**：
|
||||
|
||||
| 模块 | 命令数 | 负责人 | 新增命令 |
|
||||
|------|--------|--------|----------|
|
||||
| milestone | 6 | 组长 | list, view, create, update, close, delete |
|
||||
| webhook | 6 | 组长 | list, create, view, update, delete, test |
|
||||
| label | 4 | 组长 | list, create, update, delete |
|
||||
| commit | 4 | 组长 | list, view, diff, blame |
|
||||
| file | 5 | 同学B | get, tree, create, update, delete |
|
||||
| member | 4 | 同学B | list, add, remove, update |
|
||||
| watch/star | 5 | 同学B | watch, unwatch, star, unstar, stars |
|
||||
| batch增强 | 4 | 同学C | batch-label, batch-milestone, batch-close增强, batch-assign |
|
||||
| 全局优化 | — | 同学C | table输出格式、错误提示、测试补全 |
|
||||
|
||||
4. **命令数对比**：原 40+ 命令 → 新 70+ 命令（用大字体突出）
|
||||
5. **架构图**：三层架构 Shortcuts → Raw API → Config（简单文字图即可）
|
||||
6. **实际运行截图**：每个模块截一张终端运行图
|
||||
7. **测试覆盖率**：31+ 单元测试全通过
|
||||
|
||||
### 部署方式
|
||||
|
||||
跟基础任务一样，用 Docker + Nginx 部署到 ECS：
|
||||
|
||||
```bash
|
||||
# SSH 到服务器
|
||||
ssh root@39.108.139.73
|
||||
|
||||
# 创建展示目录
|
||||
mkdir -p /opt/showcase
|
||||
```
|
||||
|
||||
把 HTML 文件放到 `/opt/showcase/index.html`，然后用 Nginx 配置一个端口（比如 8080）指向这个目录。
|
||||
|
||||
或者更简单：直接写一个 Docker 容器跑 Nginx：
|
||||
|
||||
```dockerfile
|
||||
FROM nginx:alpine
|
||||
COPY index.html /usr/share/nginx/html/index.html
|
||||
EXPOSE 8080
|
||||
```
|
||||
|
||||
```bash
|
||||
docker build -t showcase .
|
||||
docker run -d -p 8080:80 --name showcase showcase
|
||||
```
|
||||
|
||||
### HTML 模板
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-CN">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>gitlink-cli 功能增强展示</title>
|
||||
<style>
|
||||
* { margin: 0; padding: 0; box-sizing: border-box; }
|
||||
body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; background: #0d1117; color: #c9d1d9; line-height: 1.6; }
|
||||
.container { max-width: 960px; margin: 0 auto; padding: 40px 20px; }
|
||||
h1 { font-size: 2em; color: #58a6ff; margin-bottom: 8px; }
|
||||
h2 { font-size: 1.4em; color: #79c0ff; margin: 32px 0 16px; border-bottom: 1px solid #21262d; padding-bottom: 8px; }
|
||||
.subtitle { color: #8b949e; margin-bottom: 32px; }
|
||||
.stats { display: flex; gap: 24px; margin: 24px 0; }
|
||||
.stat { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 20px 32px; text-align: center; }
|
||||
.stat .number { font-size: 2.4em; font-weight: bold; color: #58a6ff; }
|
||||
.stat .label { color: #8b949e; font-size: 0.9em; }
|
||||
table { width: 100%; border-collapse: collapse; margin: 16px 0; }
|
||||
th, td { padding: 10px 14px; text-align: left; border-bottom: 1px solid #21262d; }
|
||||
th { background: #161b22; color: #79c0ff; }
|
||||
tr:hover { background: #161b22; }
|
||||
.tag { display: inline-block; background: #1f6feb33; color: #58a6ff; padding: 2px 8px; border-radius: 12px; font-size: 0.85em; margin: 2px; }
|
||||
.person { color: #f0883e; font-weight: 500; }
|
||||
code { background: #161b22; padding: 2px 6px; border-radius: 4px; font-size: 0.9em; color: #e6edf3; }
|
||||
pre { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; overflow-x: auto; margin: 12px 0; }
|
||||
.arch { text-align: center; margin: 20px 0; font-family: monospace; color: #79c0ff; }
|
||||
.arch span { color: #f0883e; }
|
||||
.team { display: flex; gap: 16px; margin: 16px 0; }
|
||||
.member { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; flex: 1; }
|
||||
.member .name { font-weight: bold; color: #f0883e; margin-bottom: 4px; }
|
||||
.member .modules { color: #8b949e; font-size: 0.9em; }
|
||||
.screenshot { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; margin: 12px 0; }
|
||||
.screenshot h4 { color: #79c0ff; margin-bottom: 8px; }
|
||||
.screenshot pre { margin: 0; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<h1>gitlink-cli 功能增强</h1>
|
||||
<p class="subtitle">软件演化与运维 课程实践 — 进阶任务子任务一</p>
|
||||
|
||||
<div class="stats">
|
||||
<div class="stat">
|
||||
<div class="number">40+</div>
|
||||
<div class="label">原有命令</div>
|
||||
</div>
|
||||
<div class="stat">
|
||||
<div class="number">→</div>
|
||||
<div class="label"></div>
|
||||
</div>
|
||||
<div class="stat">
|
||||
<div class="number">70+</div>
|
||||
<div class="label">新增后命令</div>
|
||||
</div>
|
||||
<div class="stat">
|
||||
<div class="number">12</div>
|
||||
<div class="label">Shortcut 分组</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2>团队分工</h2>
|
||||
<div class="team">
|
||||
<div class="member">
|
||||
<div class="name">组长 — milestone / webhook / label / commit + 展示工程</div>
|
||||
<div class="modules">milestone (6命令)、webhook (6命令)、label (4命令)、commit (4命令) + Web展示页 + GitLink流水线</div>
|
||||
</div>
|
||||
<div class="member">
|
||||
<div class="name">同学B — file / member / watch&star</div>
|
||||
<div class="modules">file (5命令)、member (4命令)、watch/star (5命令)</div>
|
||||
</div>
|
||||
<div class="member">
|
||||
<div class="name">同学C — 批量操作 + 全局优化</div>
|
||||
<div class="modules">batch增强 (4命令)、table输出格式、错误提示优化、测试补全</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2>架构设计</h2>
|
||||
<div class="arch">
|
||||
<pre>
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ <span>Shortcuts Layer</span> (人/AI 友好) │
|
||||
│ milestone · webhook · label · commit · file · │
|
||||
│ member · watch · star · batch · ... │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ <span>Raw API Layer</span> (全覆盖) │
|
||||
│ gitlink-cli api GET /v1/{owner}/{repo}/... │
|
||||
├─────────────────────────────────────────────────┤
|
||||
│ <span>Config Layer</span> (配置管理) │
|
||||
│ auth login · config set · token 管理 │
|
||||
└─────────────────────────────────────────────────┘
|
||||
</pre>
|
||||
</div>
|
||||
|
||||
<h2>新增功能清单</h2>
|
||||
<table>
|
||||
<tr><th>模块</th><th>命令</th><th>API 端点</th><th>负责人</th></tr>
|
||||
<!-- 组长部分 -->
|
||||
<tr>
|
||||
<td><span class="tag">milestone</span></td>
|
||||
<td>list, view, create, update, close, delete</td>
|
||||
<td>GET/POST/PATCH/DELETE /v1/{owner}/{repo}/milestones</td>
|
||||
<td class="person">组长</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="tag">webhook</span></td>
|
||||
<td>list, create, view, update, delete, test</td>
|
||||
<td>GET/POST/PUT/DELETE /v1/{owner}/{repo}/webhooks</td>
|
||||
<td class="person">组长</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="tag">label</span></td>
|
||||
<td>list, create, update, delete</td>
|
||||
<td>GET/POST/PATCH/DELETE /v1/{owner}/{repo}/issue_tags</td>
|
||||
<td class="person">组长</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="tag">commit</span></td>
|
||||
<td>list, view, diff, blame</td>
|
||||
<td>GET /v1/{owner}/{repo}/commits, blame</td>
|
||||
<td class="person">组长</td>
|
||||
</tr>
|
||||
<!-- 同学B部分 — 等他们完成后补充截图 -->
|
||||
<tr>
|
||||
<td><span class="tag">file</span></td>
|
||||
<td>get, tree, create, update, delete</td>
|
||||
<td>GET/POST/PUT/DELETE /{owner}/{repo}/files, create_file, update_file, delete_file</td>
|
||||
<td class="person">同学B</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="tag">member</span></td>
|
||||
<td>list, add, remove, update</td>
|
||||
<td>GET/POST/DELETE/PUT /{owner}/{repo}/collaborators</td>
|
||||
<td class="person">同学B</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><span class="tag">watch/star</span></td>
|
||||
<td>watch, unwatch, star, unstar, stars</td>
|
||||
<td>POST/DELETE /watchers, /praise_tread + GET列表</td>
|
||||
<td class="person">同学B</td>
|
||||
</tr>
|
||||
<!-- 同学C部分 -->
|
||||
<tr>
|
||||
<td><span class="tag">batch增强</span></td>
|
||||
<td>batch-label, batch-milestone, batch-close增强, batch-assign</td>
|
||||
<td>基于现有 issue batch 模式扩展</td>
|
||||
<td class="person">同学C</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h2>运行效果演示</h2>
|
||||
<!-- 每个模块截一张图填在这里 -->
|
||||
|
||||
<div class="screenshot">
|
||||
<h4>milestone +list</h4>
|
||||
<pre>$ gitlink-cli milestone +list --owner chroe --repo gitlink_help_center
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"milestones": [
|
||||
{"id": 2756, "name": "v2.0", "status": "open", "effective_date": "2026-06-30"}
|
||||
],
|
||||
"total_count": 1
|
||||
}
|
||||
}</pre>
|
||||
</div>
|
||||
|
||||
<div class="screenshot">
|
||||
<h4>webhook +list</h4>
|
||||
<pre>$ gitlink-cli webhook +list --owner chroe --repo gitlink_help_center
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"total_count": 3,
|
||||
"webhooks": [
|
||||
{"id": 50035, "url": "https://jianmu.gitlink.org.cn/webhook/projects/sync", "is_active": true}
|
||||
]
|
||||
}
|
||||
}</pre>
|
||||
</div>
|
||||
|
||||
<div class="screenshot">
|
||||
<h4>commit +list</h4>
|
||||
<pre><!-- 在真实API运行后把输出粘贴到这里 --></pre>
|
||||
</div>
|
||||
|
||||
<!-- 更多截图... -->
|
||||
|
||||
<h2>测试覆盖</h2>
|
||||
<pre>$ go test ./... -v
|
||||
=== RUN TestMilestoneList
|
||||
--- PASS: TestMilestoneList
|
||||
=== RUN TestMilestoneCreate
|
||||
--- PASS: TestMilestoneCreate
|
||||
...（31+ tests all PASS）</pre>
|
||||
|
||||
<h2>GitLink 流水线</h2>
|
||||
<p>为 fork 仓库配置了 DevOps 流水线，每次推送自动运行 <code>go test ./...</code></p>
|
||||
<!-- 截图或链接 -->
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### 步骤总结
|
||||
|
||||
1. 写完 `commit.go` 和 `commit_test.go`，改 `register.go`
|
||||
2. 运行 `go test ./... -v` 确认全部通过
|
||||
3. 运行 `go build -o gitlink-cli.exe .` 构建成功
|
||||
4. 用真实 Token 测试每个命令
|
||||
5. 收集所有截图，填充到 HTML 模板
|
||||
6. 部署到 ECS 服务器
|
||||
7. （可选）给 fork 仓库配置 GitLink DevOps 流水线
|
||||
|
||||
---
|
||||
|
||||
## 时间安排
|
||||
|
||||
| 日期 | 任务 |
|
||||
|------|------|
|
||||
| 5.25-5.26 | 完成 commit.go + commit_test.go，验证通过 |
|
||||
| 5.27-5.28 | 用真实 API 测试所有命令，截图保存 |
|
||||
| 5.29-5.30 | 收集同学B和C的代码，合并到 dev 分支 |
|
||||
| 5.31-6.1 | 编写展示 HTML，部署到 ECS |
|
||||
| 6.2 | 配置 GitLink 流水线（可选） |
|
||||
| 6.3 | 最终检查，全员联调 |
|
||||
| 6.4 | 汇报验收 |
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,604 @@
|
|||
# 任务 C — 批量操作增强 + 全局优化 + 测试补全
|
||||
|
||||
> 本任务包含三部分：
|
||||
> 1. **批量操作增强** — 新增 batch-label、batch-milestone、优化已有 batch-close、新增 batch-assign
|
||||
> 2. **table 输出格式优化** — 改进已有的 table 输出，让 list 命令用 `--format table` 时显示更美观
|
||||
> 3. **测试补全** — 给现有没有测试的模块补 httptest 单元测试
|
||||
|
||||
---
|
||||
|
||||
## 项目信息
|
||||
|
||||
- **仓库地址**：https://gitlink.org.cn/chroe/gitlink-cli
|
||||
- **克隆**：`git clone https://gitlink.org.cn/chroe/gitlink-cli.git`
|
||||
- **Go 版本**：1.26+（安装：`winget install GoLang.Go`，装完后重启终端）
|
||||
- **设置国内代理**（必须）：`go env -w GOPROXY=https://goproxy.cn,direct`
|
||||
- **构建**：`go build -o gitlink-cli.exe .`
|
||||
- **运行测试**：`go test ./... -v`
|
||||
- **GitLink Token**（测试用）：`7f1586abeacdf7dd9ad488d38bf09d5d08359642`
|
||||
|
||||
---
|
||||
|
||||
## 代码模式说明（必读）
|
||||
|
||||
**先读这些文件理解项目结构：**
|
||||
- `shortcuts/search/search.go` — 最简单的 GET Shortcut
|
||||
- `shortcuts/issue/batch.go` — **重点！你的批量操作参考模板**
|
||||
- `shortcuts/issue/issue_test.go` — 测试模板
|
||||
- `shortcuts/label/label.go` — 有 POST/PATCH/DELETE 的模式（batch-label 需要调用这些 API）
|
||||
- `shortcuts/milestone/milestone.go` — milestone 的 API 调用方式（batch-milestone 需要）
|
||||
- `shortcuts/register.go` — 注册方式
|
||||
- `internal/output/formatter.go` — table 输出格式（你需要优化这个文件）
|
||||
|
||||
**Shortcut 框架关键点：**
|
||||
- 每个模块一个目录，目录下有 `xxx.go`（定义 `Shortcuts()` 函数）和 `xxx_test.go`
|
||||
- `common.Shortcut` 结构体：Name、Description、Flags、Run
|
||||
- `RuntimeContext` 方法：`ResolveOwnerRepo()`、`CallAPI(method, path, body)`、`CallAPIWithQuery(method, path, query)`、`Output(env)`、`OutputData(data)`
|
||||
- `ctx.RepoPath()` → `"/{owner}/{repo}"`（不带 `/v1`）
|
||||
- API 路径会自动加 `.json` 后缀
|
||||
|
||||
---
|
||||
|
||||
## 第一部分：批量操作增强
|
||||
|
||||
批量操作的思路跟 `shortcuts/issue/batch.go` 一模一样：
|
||||
1. 接收一个逗号分隔的 ID 列表（`--ids 1,2,3`）
|
||||
2. 循环逐个调用对应的单个操作 API
|
||||
3. 收集结果，汇总成功/失败数量
|
||||
4. 支持 `--dry-run` 预览模式
|
||||
|
||||
### 要修改的文件
|
||||
|
||||
这些批量操作都是加到已有的 `shortcuts/issue/issue.go` 中（因为它们都是 issue 相关的）。
|
||||
|
||||
在 `issue.go` 的 `Shortcuts()` 函数中新增快捷方式。
|
||||
|
||||
### 1. batch-label（批量给 Issue 打标签）
|
||||
|
||||
**API 端点**：更新 Issue 时传 `tag_ids` 参数
|
||||
|
||||
思路：先获取 Issue 当前信息（含现有标签），再 PATCH 加上新标签。
|
||||
|
||||
在 `shortcuts/issue/issue.go` 的 `Shortcuts()` 切片中追加：
|
||||
|
||||
```go
|
||||
{
|
||||
Name: "batch-label",
|
||||
Description: "Add labels to multiple issues",
|
||||
Flags: []common.Flag{
|
||||
{Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers (e.g. 1,2,3)"},
|
||||
{Name: "tag-ids", Short: "t", Usage: "Comma-separated tag IDs to add", Required: true},
|
||||
{Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
numbersStr := ctx.Arg("numbers")
|
||||
if numbersStr == "" {
|
||||
return fmt.Errorf("no issue numbers provided; use --numbers 1,2,3")
|
||||
}
|
||||
numbers := parseNumbers(numbersStr)
|
||||
tagIDs := parseNumbers(ctx.Arg("tag-ids"))
|
||||
if len(tagIDs) == 0 {
|
||||
return fmt.Errorf("--tag-ids is required")
|
||||
}
|
||||
dryRun := parseBool(ctx.Arg("dry-run"))
|
||||
type batchResult struct {
|
||||
Number string `json:"number"`
|
||||
Action string `json:"action"`
|
||||
Status string `json:"status"`
|
||||
Error string `json:"error,omitempty"`
|
||||
}
|
||||
type batchSummary struct {
|
||||
Repository string `json:"repository"`
|
||||
DryRun bool `json:"dry_run"`
|
||||
Total int `json:"total"`
|
||||
Succeeded int `json:"succeeded"`
|
||||
Failed int `json:"failed"`
|
||||
Results []batchResult `json:"results"`
|
||||
}
|
||||
summary := batchSummary{
|
||||
Repository: fmt.Sprintf("%s/%s", ctx.Owner, ctx.Repo),
|
||||
DryRun: dryRun,
|
||||
Total: len(numbers),
|
||||
Results: make([]batchResult, 0, len(numbers)),
|
||||
}
|
||||
for _, num := range numbers {
|
||||
result := batchResult{Number: num, Action: "add-labels"}
|
||||
if dryRun {
|
||||
result.Status = "planned"
|
||||
summary.Succeeded++
|
||||
summary.Results = append(summary.Results, result)
|
||||
continue
|
||||
}
|
||||
// GET current issue to preserve existing fields
|
||||
env, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), num), nil)
|
||||
if err != nil {
|
||||
result.Status = "failed"
|
||||
result.Error = fmt.Sprintf("fetch issue: %v", err)
|
||||
summary.Failed++
|
||||
summary.Results = append(summary.Results, result)
|
||||
continue
|
||||
}
|
||||
existing := extractIssueFields(env)
|
||||
tagIDFloats := make([]float64, len(tagIDs))
|
||||
for i, id := range tagIDs {
|
||||
n, _ := strconv.ParseInt(id, 10, 64)
|
||||
tagIDFloats[i] = float64(n)
|
||||
}
|
||||
body := map[string]interface{}{
|
||||
"subject": existing.Subject,
|
||||
"description": existing.Description,
|
||||
"tag_ids": tagIDFloats,
|
||||
}
|
||||
if _, err := ctx.CallAPI("PATCH", fmt.Sprintf("%s/issues/%s", v1RepoPath(ctx), num), body); err != nil {
|
||||
result.Status = "failed"
|
||||
result.Error = err.Error()
|
||||
summary.Failed++
|
||||
} else {
|
||||
result.Status = "labeled"
|
||||
summary.Succeeded++
|
||||
}
|
||||
summary.Results = append(summary.Results, result)
|
||||
}
|
||||
if err := ctx.OutputData(summary); err != nil {
|
||||
return err
|
||||
}
|
||||
if summary.Failed > 0 {
|
||||
return fmt.Errorf("%d of %d issue(s) failed", summary.Failed, summary.Total)
|
||||
}
|
||||
return nil
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
你需要在 `issue.go` 中添加几个辅助函数（如果还没有的话）：
|
||||
|
||||
```go
|
||||
func parseNumbers(s string) []string {
|
||||
if strings.TrimSpace(s) == "" {
|
||||
return nil
|
||||
}
|
||||
var result []string
|
||||
seen := map[string]bool{}
|
||||
for _, n := range strings.Split(s, ",") {
|
||||
n = strings.TrimSpace(n)
|
||||
if n != "" && !seen[n] {
|
||||
seen[n] = true
|
||||
result = append(result, n)
|
||||
}
|
||||
}
|
||||
return result
|
||||
}
|
||||
```
|
||||
|
||||
**注意**：`v1RepoPath`、`parseBool`、`fetchExistingIssue`、`extractIssueFields` 这些函数可能已经在 `issue.go` 或 `batch.go` 中定义了。先读一下 `issue.go` 的完整内容，避免重复定义。如果已经有 `parseBool` 就不要重复定义，如果没有就加到 `issue.go` 里。
|
||||
|
||||
### 2. batch-milestone（批量设里程碑）
|
||||
|
||||
跟 batch-label 思路一样，只是 PATCH 时传 `fixed_version_id`（里程碑 ID）。
|
||||
|
||||
```go
|
||||
{
|
||||
Name: "batch-milestone",
|
||||
Description: "Set milestone for multiple issues",
|
||||
Flags: []common.Flag{
|
||||
{Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers"},
|
||||
{Name: "milestone-id", Short: "m", Usage: "Milestone ID to set", Required: true},
|
||||
{Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
if err := ctx.ResolveOwnerRepo(); err != nil {
|
||||
return err
|
||||
}
|
||||
numbersStr := ctx.Arg("numbers")
|
||||
if numbersStr == "" {
|
||||
return fmt.Errorf("no issue numbers provided; use --numbers 1,2,3")
|
||||
}
|
||||
numbers := parseNumbers(numbersStr)
|
||||
milestoneIDStr, _ := ctx.RequireArg("milestone-id")
|
||||
milestoneID, _ := strconv.ParseInt(milestoneIDStr, 10, 64)
|
||||
dryRun := parseBool(ctx.Arg("dry-run"))
|
||||
// ... 同样的 batch 模式：循环 numbers，GET 当前 issue，PATCH 加 fixed_version_id
|
||||
// body 结构：
|
||||
// body := map[string]interface{}{
|
||||
// "subject": existing.Subject,
|
||||
// "description": existing.Description,
|
||||
// "fixed_version_id": milestoneID,
|
||||
// }
|
||||
// ... 参照 batch-label 写完整
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
### 3. batch-assign（批量指派负责人）
|
||||
|
||||
```go
|
||||
{
|
||||
Name: "batch-assign",
|
||||
Description: "Assign a user to multiple issues",
|
||||
Flags: []common.Flag{
|
||||
{Name: "numbers", Short: "n", Usage: "Comma-separated issue numbers"},
|
||||
{Name: "assigner-id", Short: "a", Usage: "User ID to assign", Required: true},
|
||||
{Name: "dry-run", Usage: "Preview without making changes", Bool: true, Default: "false"},
|
||||
},
|
||||
Run: func(ctx *common.RuntimeContext) error {
|
||||
// ... 同样的模式
|
||||
// body 中加 "assigned_to_id": assignerID
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
### 4. 优化 batch-close
|
||||
|
||||
已有 `batch-close` 在 `shortcuts/issue/batch.go`。优化方向：
|
||||
- 给 summary 加一个 `Duration` 字段，记录总耗时
|
||||
- 在 dry-run 模式下输出更详细的信息（issue 标题等）
|
||||
|
||||
找到 `runBatchClose` 函数，在开头加计时：
|
||||
```go
|
||||
start := time.Now()
|
||||
```
|
||||
在 return 前：
|
||||
```go
|
||||
summary.Duration = time.Since(start).String()
|
||||
```
|
||||
|
||||
在 `batchCloseSummary` 结构体中加：
|
||||
```go
|
||||
Duration string `json:"duration" yaml:"duration"`
|
||||
```
|
||||
|
||||
### 批量操作的测试
|
||||
|
||||
在 `shortcuts/issue/issue_test.go` 中添加测试：
|
||||
|
||||
```go
|
||||
func TestBatchLabel(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
switch {
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/issues/1.json":
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"subject": "Test issue", "description": "desc",
|
||||
})
|
||||
case r.Method == "GET" && r.URL.Path == "/v1/owner/repo/issues/2.json":
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"subject": "Another issue", "description": "desc2",
|
||||
})
|
||||
case r.Method == "PATCH" && (r.URL.Path == "/v1/owner/repo/issues/1.json" || r.URL.Path == "/v1/owner/repo/issues/2.json"):
|
||||
writeJSON(t, w, map[string]interface{}{"status": 0, "message": "success"})
|
||||
default:
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runIssueShortcut(t, server, "batch-label", map[string]string{
|
||||
"numbers": "1,2",
|
||||
"tag-ids": "10",
|
||||
"dry-run": "false",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("batch-label failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBatchMilestoneDryRun(t *testing.T) {
|
||||
// dry-run 模式不应该发任何请求
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
t.Fatal("no request should be made in dry-run mode")
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runIssueShortcut(t, server, "batch-milestone", map[string]string{
|
||||
"numbers": "1,2,3",
|
||||
"milestone-id": "5",
|
||||
"dry-run": "true",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("batch-milestone dry-run failed: %v", err)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第二部分：table 输出格式优化
|
||||
|
||||
### 现状
|
||||
|
||||
项目已经有 `--format table` 支持（在 `internal/output/formatter.go` 中），但功能比较基础。
|
||||
|
||||
### 优化目标
|
||||
|
||||
1. **支持嵌套数据的表格输出**：目前 `hasComplexValues` 返回 true 时直接降级为 JSON。优化后，对于 map 中包含 `[]interface{}` 列表的（如 `{"milestones": [...], "total_count": 1}`），自动提取列表渲染表格。
|
||||
|
||||
2. **截断控制**：对过长的值截断到 50 字符。
|
||||
|
||||
3. **增加 summary 行**：在表格底部显示总数。
|
||||
|
||||
### 修改 internal/output/formatter.go
|
||||
|
||||
把 `printTable` 函数替换为：
|
||||
|
||||
```go
|
||||
func printTable(w io.Writer, envelope *Envelope) error {
|
||||
if !envelope.OK {
|
||||
if envelope.Error != nil {
|
||||
fmt.Fprintf(w, "Error: %s\n", envelope.Error.Message)
|
||||
if envelope.Error.Suggestion != "" {
|
||||
fmt.Fprintf(w, "Suggestion: %s\n", envelope.Error.Suggestion)
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
if envelope.Data == nil {
|
||||
fmt.Fprintln(w, "No data")
|
||||
return nil
|
||||
}
|
||||
|
||||
switch data := envelope.Data.(type) {
|
||||
case []interface{}:
|
||||
return printSliceTable(w, data)
|
||||
case map[string]interface{}:
|
||||
// 新增：自动从 map 中提取列表数据
|
||||
if slice := findSliceInMap(data); slice != nil {
|
||||
return printSliceTable(w, slice)
|
||||
}
|
||||
if hasComplexValues(data) {
|
||||
return printJSON(w, envelope)
|
||||
}
|
||||
return printMapTable(w, data)
|
||||
default:
|
||||
return printJSON(w, envelope)
|
||||
}
|
||||
}
|
||||
|
||||
// findSliceInMap 从 map 中查找第一个 []interface{} 值（通常是主数据列表）
|
||||
func findSliceInMap(m map[string]interface{}) []interface{} {
|
||||
// 优先查找常见的列表字段名
|
||||
for _, key := range []string{
|
||||
"issues", "pull_requests", "milestones", "webhooks", "issue_tags",
|
||||
"commits", "files", "members", "collaborators", "users", "branches",
|
||||
"releases", "entries", "tags", "watchers",
|
||||
} {
|
||||
if v, ok := m[key]; ok {
|
||||
if slice, ok := v.([]interface{}); ok && len(slice) > 0 {
|
||||
return slice
|
||||
}
|
||||
}
|
||||
}
|
||||
// 降级：找第一个 []interface{}
|
||||
for _, v := range m {
|
||||
if slice, ok := v.([]interface{}); ok && len(slice) > 0 {
|
||||
if _, isMap := slice[0].(map[string]interface{}); isMap {
|
||||
return slice
|
||||
}
|
||||
}
|
||||
}
|
||||
return nil
|
||||
}
|
||||
```
|
||||
|
||||
另外优化 `formatValue`，让截断更短：
|
||||
|
||||
```go
|
||||
func formatValue(v interface{}) string {
|
||||
if v == nil {
|
||||
return ""
|
||||
}
|
||||
rv := reflect.ValueOf(v)
|
||||
switch rv.Kind() {
|
||||
case reflect.Map, reflect.Slice:
|
||||
data, _ := json.Marshal(v)
|
||||
s := string(data)
|
||||
if len(s) > 50 {
|
||||
return s[:47] + "..."
|
||||
}
|
||||
return s
|
||||
case reflect.Bool:
|
||||
if v.(bool) {
|
||||
return "yes"
|
||||
}
|
||||
return "no"
|
||||
case reflect.Float64:
|
||||
// 如果是整数就不显示小数点
|
||||
f := v.(float64)
|
||||
if f == float64(int64(f)) {
|
||||
return fmt.Sprintf("%d", int64(f))
|
||||
}
|
||||
return fmt.Sprintf("%v", v)
|
||||
default:
|
||||
return fmt.Sprintf("%v", v)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 优化后的测试效果
|
||||
|
||||
```bash
|
||||
# 之前（有嵌套数据时降级为 JSON）
|
||||
./gitlink-cli.exe milestone +list --owner chroe --repo gitlink_help_center --format table
|
||||
# → 输出 JSON（因为 data 是 map 嵌套 list）
|
||||
|
||||
# 优化后（自动提取 milestones 列表渲染表格）
|
||||
./gitlink-cli.exe milestone +list --owner chroe --repo gitlink_help_center --format table
|
||||
# → 输出：
|
||||
# ID NAME STATUS EFFECTIVE_DATE ISSUES_COUNT
|
||||
# --- ----- ------- --------------- -------------
|
||||
# 2756 v2.0 open 2026-06-30 0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 第三部分：测试补全
|
||||
|
||||
以下模块目前没有测试，需要补充。每个测试遵循相同的 httptest 模式。
|
||||
|
||||
### 需要补测试的模块
|
||||
|
||||
| 模块 | 文件位置 | 需要测试的命令 |
|
||||
|------|---------|---------------|
|
||||
| repo | `shortcuts/repo/repo.go` | list, create, view, fork, delete |
|
||||
| branch | `shortcuts/branch/branch.go` | list, create, delete, protect |
|
||||
| release | `shortcuts/release/release.go` | list, create, delete |
|
||||
| org | `shortcuts/org/org.go` | list |
|
||||
| user | `shortcuts/user/user.go` | me |
|
||||
| search | `shortcuts/search/search.go` | repos, users |
|
||||
|
||||
### 测试模板（以 repo 为例）
|
||||
|
||||
创建 `shortcuts/repo/repo_test.go`：
|
||||
|
||||
```go
|
||||
package repo
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"testing"
|
||||
|
||||
"github.com/gitlink-org/gitlink-cli/internal/client"
|
||||
"github.com/gitlink-org/gitlink-cli/shortcuts/common"
|
||||
)
|
||||
|
||||
func TestRepoList(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method != "GET" || r.URL.Path != "/users/chroe/projects.json" {
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"total_count": 1,
|
||||
"projects": []map[string]interface{}{
|
||||
{"id": 1, "name": "test-repo", "identifier": "test_repo"},
|
||||
},
|
||||
})
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runRepoShortcut(t, server, "list", map[string]string{"owner": "chroe"})
|
||||
if err != nil {
|
||||
t.Fatalf("list failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRepoView(t *testing.T) {
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.Method == "GET" && r.URL.Path == "/chroe/test_repo.json" {
|
||||
writeJSON(t, w, map[string]interface{}{
|
||||
"id": 1, "name": "test-repo", "identifier": "test_repo",
|
||||
})
|
||||
return
|
||||
}
|
||||
t.Fatalf("unexpected request: %s %s", r.Method, r.URL.Path)
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
err := runRepoShortcut(t, server, "view", map[string]string{
|
||||
"owner": "chroe", "repo": "test_repo",
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatalf("view failed: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// === helpers ===
|
||||
|
||||
func runRepoShortcut(t *testing.T, server *httptest.Server, name string, args map[string]string) error {
|
||||
t.Helper()
|
||||
for _, s := range Shortcuts() {
|
||||
if s.Name == name {
|
||||
ctx := &common.RuntimeContext{
|
||||
Client: &client.Client{HTTP: server.Client(), BaseURL: server.URL},
|
||||
Owner: args["owner"], Repo: args["repo"], Format: "json", Args: args,
|
||||
}
|
||||
return s.Run(ctx)
|
||||
}
|
||||
}
|
||||
t.Fatalf("shortcut %q not found", name)
|
||||
return nil
|
||||
}
|
||||
|
||||
func writeJSON(t *testing.T, w http.ResponseWriter, payload interface{}) {
|
||||
t.Helper()
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
json.NewEncoder(w).Encode(payload)
|
||||
}
|
||||
```
|
||||
|
||||
**重要提示**：写测试之前先读对应的 `.go` 文件，看清楚每个命令调用的 API 路径和参数。用 `r.URL.Path` 和 `r.Method` 做断言。
|
||||
|
||||
### 其他模块的测试文件
|
||||
|
||||
按同样的模式创建：
|
||||
- `shortcuts/branch/branch_test.go`
|
||||
- `shortcuts/release/release_test.go`
|
||||
- `shortcuts/org/org_test.go`
|
||||
- `shortcuts/user/user_test.go`
|
||||
- `shortcuts/search/search_test.go`
|
||||
|
||||
每个文件至少测试 2-3 个核心命令。
|
||||
|
||||
---
|
||||
|
||||
## 验证步骤
|
||||
|
||||
```bash
|
||||
# 每完成一个改动就跑一次全量测试
|
||||
go test ./... -v
|
||||
|
||||
# 构建确认
|
||||
go build -o gitlink-cli.exe .
|
||||
|
||||
# 测试 table 输出格式
|
||||
export GITLINK_TOKEN=7f1586abeacdf7dd9ad488d38bf09d5d08359642
|
||||
|
||||
./gitlink-cli.exe milestone +list --owner chroe --repo gitlink_help_center --format table
|
||||
./gitlink-cli.exe label +list --owner chroe --repo gitlink_help_center --format table
|
||||
./gitlink-cli.exe webhook +list --owner chroe --repo gitlink_help_center --format table
|
||||
|
||||
# 测试批量操作
|
||||
./gitlink-cli.exe issue +batch-label --owner chroe --repo gitlink_help_center --numbers 1 --tag-ids 1 --dry-run true
|
||||
./gitlink-cli.exe issue +batch-milestone --owner chroe --repo gitlink_help_center --numbers 1 --milestone-id 1 --dry-run true
|
||||
./gitlink-cli.exe issue +batch-assign --owner chroe --repo gitlink_help_center --numbers 1 --assigner-id 1 --dry-run true
|
||||
|
||||
# 测试优化后的 batch-close
|
||||
./gitlink-cli.exe issue +batch-close --owner chroe --repo gitlink_help_center --numbers 1 --dry-run true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 时间安排
|
||||
|
||||
| 日期 | 任务 |
|
||||
|------|------|
|
||||
| 5.25-5.26 | 学习项目结构（读 batch.go、issue.go、formatter.go）；完成 table 格式优化 |
|
||||
| 5.27-5.28 | 完成 batch-label 和 batch-milestone |
|
||||
| 5.29 | 完成 batch-assign 和 batch-close 优化 |
|
||||
| 5.30 | 中期碰头会 |
|
||||
| 5.31-6.1 | 补全 repo/branch/release/org/user/search 的测试 |
|
||||
| 6.2 | 全面测试，发给组长集成 |
|
||||
| 6.3 | 最终检查 |
|
||||
| 6.4 | 汇报验收 |
|
||||
|
||||
---
|
||||
|
||||
## 汇报展示要点
|
||||
|
||||
你负责的部分在演示时重点展示：
|
||||
|
||||
1. **table 格式**：`--format json` vs `--format table` 对比，视觉效果好
|
||||
2. **batch 操作 dry-run**：先 `--dry-run true` 预览，再真正执行，展示安全设计
|
||||
3. **测试全绿**：`go test ./... -v` 跑一遍，展示测试覆盖率提升
|
||||
|
||||
---
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **先读后写**：写代码前一定要先读对应的已有文件，避免重复定义函数
|
||||
2. **路径注意**：有些 API 用 `/v1/...`，有些用 `/api/...`，仔细看 `doc/gitlink_api_reference.md`
|
||||
3. **每次改完跑测试**：`go test ./... -v`，确认没有破坏其他模块
|
||||
4. **如果有编译错误**：Go 的错误提示很明确，看错误信息逐个修复即可
|
||||
|
|
@ -1,13 +0,0 @@
|
|||
# 提交材料
|
||||
|
||||
本目录按赛题要求集中存放各子赛题的**变更说明 / 应用报告**与**演示录屏/截图**。最终提交作品即本关联仓库，所有材料放在仓库内供评委查阅。
|
||||
|
||||
| 子赛题 | 目录 | 状态 | 内容 |
|
||||
|--------|------|------|------|
|
||||
| 一 · CLI 能力增强 | [子赛题一-CLI能力/](子赛题一-CLI能力/) | ✅ 就绪 | [变更说明.md](子赛题一-CLI能力/变更说明.md)；PR 提交至主仓库 |
|
||||
| 二 · 编写 Skills | [子赛题二-Skills/](子赛题二-Skills/) | ✅ 就绪 | [README](子赛题二-Skills/README.md)（交付对照赛题要求）+ [demos/](子赛题二-Skills/demos/) 演示录屏截图；23 个 Skill 在 `skills/` |
|
||||
| 三 · 工作流 | [子赛题三-工作流/](子赛题三-工作流/) | ✅ 就绪 | [工作流说明](子赛题三-工作流/工作流说明.md) + [架构图](子赛题三-工作流/架构图.png) + [执行脚本](子赛题三-工作流/执行脚本.sh) + [Agent 对话记录](子赛题三-工作流/Agent对话记录.md) + [demos/](子赛题三-工作流/demos/)（社区运营自动化） |
|
||||
| 四 · 辅助科研 | [子赛题四-科研/](子赛题四-科研/) | ✅ 就绪 | [使用文档](子赛题四-科研/子任务四-使用文档.md) + [科研场景应用报告](子赛题四-科研/子任务四-科研场景应用报告.md) + [场景输出结果/](子赛题四-科研/场景输出结果/) + [演示录屏/](子赛题四-科研/演示录屏/)（spark + research-fair） |
|
||||
|
||||
> 全局技术要求（README / 使用说明 / 架构说明）见仓库根 [README.md](../README.md)。
|
||||
> 各子赛题的演示材料放在对应目录的 `demos/` 子文件夹下。
|
||||
|
|
@ -1,23 +0,0 @@
|
|||
# 子赛题一 · 增加 CLI 能力
|
||||
|
||||
本目录存放子赛题一的**变更说明**。子赛题一以**向主仓库提交 PR** 为交付形式（代码 + 单元测试 + 命令帮助文档 + 变更说明），PR 提交到 [gitlink/gitlink-cli](https://gitlink.org.cn/gitlink/gitlink-cli) 主仓库。
|
||||
|
||||
## 目录内容
|
||||
|
||||
- **[变更说明.md](变更说明.md)** — 本团队对 gitlink-cli 的 CLI 能力增强清单，作为 PR 的变更说明：
|
||||
- 新增 9 个命令模块（commit / file / label / member / milestone / star / watch / webhook / wiki）
|
||||
- 增强现有模块 + 11 个批量操作（全部支持 `--dry-run`）
|
||||
- 3 项跨平台兼容性修复（Windows Setsid / MSYS2 路径污染 / FreeBSD）
|
||||
- 190+ 单元测试，8 平台交叉编译
|
||||
- 含建议的 PR 拆分方案
|
||||
|
||||
## 代码位置
|
||||
|
||||
- 业务层：`shortcuts/`（19 个 Shortcut 模块）
|
||||
- 入口层：`cmd/`（auth / api / config / version）
|
||||
- 基础层：`internal/`（client / auth / config / output）
|
||||
|
||||
## PR 与演示
|
||||
|
||||
- Fork 仓库 commit 历史：<https://gitlink.org.cn/chroe/gitlink-cli/commits/branch/master>
|
||||
- 在线 Showcase：<http://118.31.4.168:9090>
|
||||
|
|
@ -1,120 +0,0 @@
|
|||
# 变更说明 · 子赛题一：增加和完善 GitLink-CLI 能力
|
||||
|
||||
> 第八届 CCF 开源创新大赛 · track1 GitLink-CLI 贡献赛
|
||||
> 团队：chroe / yetja / caoweiqiong
|
||||
> Fork 仓库：<https://gitlink.org.cn/chroe/gitlink-cli>
|
||||
> Fork 起点：`fde3226`（当时上游仅 9 个 Shortcut 模块）
|
||||
|
||||
本文档汇总本团队对 [gitlink/gitlink-cli](https://gitlink.org.cn/gitlink/gitlink-cli) 的 CLI 能力增强贡献，作为向主仓库提交 PR 的变更说明。子赛题三的工作流引擎（`shortcuts/workflow/`）单独成题，本文不重复计入。
|
||||
|
||||
---
|
||||
|
||||
## 一、贡献总览
|
||||
|
||||
| 维度 | 数量 | 说明 |
|
||||
|------|------|------|
|
||||
| 新增命令模块 | **9 个** | commit / file / label / member / milestone / star / watch / webhook / wiki |
|
||||
| 增强现有模块 | 9 个 | branch / ci / issue / org / pr / release / repo / search / user |
|
||||
| 命令总数 | 100+ | 19 个 Shortcut 模块合计 |
|
||||
| 批量操作 | 11 个 | issue / repo / member 三类资源，全部支持 `--dry-run` 预演 |
|
||||
| 跨平台修复 | 3 项 | Windows / MSYS2 / FreeBSD 关键兼容性 |
|
||||
| 单元测试 | 190+ | 32 个 `_test.go` 文件，`go test ./...` 全绿 |
|
||||
| 交叉编译 | 8 平台 | darwin/linux/windows/freebsd × amd64/arm64 |
|
||||
|
||||
---
|
||||
|
||||
## 二、新增命令模块（9 个，上游此前无）
|
||||
|
||||
| 模块 | 位置 | 能力 |
|
||||
|------|------|------|
|
||||
| **commit** | `shortcuts/commit/` | 提交记录查看、diff、对比、统计 |
|
||||
| **file** | `shortcuts/file/` | 仓库文件/目录的读取、目录树、内容获取 |
|
||||
| **label** | `shortcuts/label/` | 标签的创建、列表、更新、删除 |
|
||||
| **member** | `shortcuts/member/` | 仓库成员管理 + 批量添加成员 |
|
||||
| **milestone** | `shortcuts/milestone/` | 里程碑创建、列表、更新、关闭 |
|
||||
| **star** | `shortcuts/star/` | 收藏仓库 / 取消收藏 / 列出收藏 |
|
||||
| **watch** | `shortcuts/watch/` | 关注仓库 / 取消关注 / 列出关注 |
|
||||
| **webhook** | `shortcuts/webhook/` | Webhook 的增删改查与触发事件配置 |
|
||||
| **wiki** | `shortcuts/wiki/` | Wiki 页面的创建、列表、编辑、查看 |
|
||||
|
||||
每个模块均遵循项目统一的 `common.Shortcut` 结构，复用 `RuntimeContext`（自动注入 owner/repo/auth/输出格式），不直接接触 cobra 与 HTTP 细节。
|
||||
|
||||
---
|
||||
|
||||
## 三、增强现有模块
|
||||
|
||||
### 3.1 批量操作能力（赛题明确要求）
|
||||
|
||||
围绕 issue / repo / member 三类高频资源新增 **11 个批量操作**，全部支持 `--dry-run` 先预演再执行，避免误操作：
|
||||
|
||||
| 资源 | 批量命令 |
|
||||
|------|---------|
|
||||
| Issue | `+batch-close` `+batch-reopen` `+batch-comment` `+batch-assign` `+batch-label` `+batch-milestone` |
|
||||
| Repo | `+batch-create` `+batch-fork` `+batch-delete` |
|
||||
| Member | `+batch-add` |
|
||||
|
||||
> **可用性透明化**：实测中发现 GitLink OpenAPI 对部分写操作存在限制（如 Issue 标签关联、里程碑批量设置），相关结论已写入各 Skill 的 `REFERENCE.md`「写入操作可用性」表，并在命令帮助中标注，不向用户隐瞒 API 现状。
|
||||
|
||||
### 3.2 Bug 修复与体验优化
|
||||
|
||||
- `issue +assign`：改用 `PATCH`（原 `PUT` 返回 404），传递数字 ID，并保留 `status_id` 防止状态被重置
|
||||
- `issue +list`：补全状态/分页过滤
|
||||
- `watch` / `star`：`resolveProjectID` 兼容 `project_id` 字段，修复部分仓库失效
|
||||
- `repo`：批量管理默认改用 fork 后的仓库路径，避免误删上游
|
||||
- Issue 更新：发现 `assigner_ids`（数组）才是正确字段，而非文档所写的 `assigned_to_id`；更新时须带 `subject`/`description` 否则被清空——均已修正并写入文档
|
||||
|
||||
---
|
||||
|
||||
## 四、跨平台兼容性修复（赛题明确要求）
|
||||
|
||||
### 4.1 Windows —— `Setsid` 系统调用不可用
|
||||
|
||||
工作流引擎用 `syscall.SysProcAttr{Setsid: true}` 创建守护进程，该调用仅 Linux 支持，Windows 编译失败。
|
||||
|
||||
- `shortcuts/workflow/daemon.go` 改为调用 `applyDaemonAttrs(cmd)`
|
||||
- 拆分 `proc_unix.go`（`//go:build !windows`，用 `Setsid`）与 `proc_windows.go`（`//go:build windows`，用 `HideWindow`）
|
||||
|
||||
### 4.2 Windows Git Bash —— MSYS2 路径污染
|
||||
|
||||
`gitlink-cli api GET /v1/...` 在 Git Bash 下被 MSYS2 自动改写成 `D:/Git/v1/...`（把 `/v1` 当成 Unix 路径转成 Git 安装目录）。
|
||||
|
||||
- `cmd/api/api.go` 检测路径首字母是否为 Windows 盘符（`^[A-Za-z]:/`），若是则还原成原始 API 路径
|
||||
|
||||
### 4.3 FreeBSD —— 编译支持
|
||||
|
||||
补充 build tag 与交叉编译目标，8 平台二进制全部可编译：
|
||||
|
||||
```
|
||||
darwin/amd64 darwin/arm64 linux/amd64 linux/arm64
|
||||
windows/amd64 windows/arm64 freebsd/amd64 freebsd/arm64
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、单元测试
|
||||
|
||||
- 32 个 `_test.go`，190+ 个 `Test*` 函数
|
||||
- 覆盖各 Shortcut 模块的参数解析、路径构造、输出格式、批量逻辑
|
||||
- `go test ./...` 全部通过
|
||||
|
||||
---
|
||||
|
||||
## 六、建议的 PR 拆分
|
||||
|
||||
为便于上游 review，建议按模块边界拆成多个 PR（每个 PR 含：功能代码 + 单元测试 + 命令帮助文档更新）：
|
||||
|
||||
1. **PR-A 新增基础模块**：`commit` + `file`（提交与文件操作）
|
||||
2. **PR-B 新增资源管理模块**：`label` + `milestone` + `member`（+ `member +batch-add`）
|
||||
3. **PR-C 新增用户交互模块**：`star` + `watch` + `webhook` + `wiki`
|
||||
4. **PR-D 批量操作能力**：`issue +batch-*` + `repo +batch-*`（统一 `--dry-run` 机制）
|
||||
5. **PR-E 跨平台修复**：`Setsid` build tag 拆分 + MSYS2 路径污染修复 + FreeBSD
|
||||
|
||||
> 各 PR 的详细 diff 以本 Fork 的 commit 历史为准：<https://gitlink.org.cn/chroe/gitlink-cli/commits/branch/master>
|
||||
|
||||
---
|
||||
|
||||
## 七、相关材料
|
||||
|
||||
- 在线 Showcase（浏览器里直接跑命令）：<http://118.31.4.168:9090>
|
||||
- Skill 与命令的帮助文档：`skills/*/SKILL.md` + `skills/*/REFERENCE.md`
|
||||
- 全局 README / 使用说明 / 架构说明：仓库根 `README.md`
|
||||
|
|
@ -1,220 +0,0 @@
|
|||
# Agent 对话记录 — Claude Code 自然语言触发工作流
|
||||
|
||||
以下为在 Claude Code 中通过自然语言调用 gitlink-cli 工作流的完整对话记录，展示工作流引擎的手动触发、规则引擎降级、AI 增强三种运行模式。
|
||||
|
||||
---
|
||||
|
||||
## 对话一：代码质量门禁（规则引擎模式）
|
||||
|
||||
**用户：** 帮我看一下 chroe/gitlink-cli 有没有需要审查的 PR，检查一下代码质量
|
||||
|
||||
**Claude：** 让我运行代码质量门禁工作流。
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +run --name code-quality --owner chroe --repo gitlink-cli --no-ai
|
||||
|
||||
workflow: code-quality
|
||||
repo: chroe/gitlink-cli
|
||||
|
||||
✅ open-prs → 获取开放 PR 列表 [命令] 1 个 PR
|
||||
✅ ci-builds → 获取 CI 构建状态 [命令] 10 个构建记录
|
||||
✅ repo-info → 获取仓库保护规则配置 [命令] gitlink-cli
|
||||
✅ commits → 获取最近提交记录 [命令] 30 条
|
||||
✅ branches → 获取分支保护状态 [命令] 2 个分支
|
||||
✅ review → AI 审查 PR 代码质量 [规则引擎] 无安全问题
|
||||
✅ ci-diagnosis → AI 诊断 CI 构建失败 [规则引擎] 无失败构建
|
||||
|
||||
⚙️ 规则引擎已处理 2 个 skill 步骤 (未使用 AI)
|
||||
```
|
||||
|
||||
7 个步骤全部执行成功。规则引擎扫描了 PR 的代码变更，未发现硬编码凭据、SQL 注入或 XSS 风险，文件数和 PR 描述均符合要求。CI 构建状态正常，无需修复。
|
||||
|
||||
---
|
||||
|
||||
## 对话二：社区运营自动化（规则引擎模式）
|
||||
|
||||
**用户：** 很好。现在帮我给 chroe/gitlink-cli 的 Issue 做一下分拣，然后生成社区周报
|
||||
|
||||
**Claude：** 我用社区运营工作流一次性完成 Issue 分拣、周报生成和 Release Notes。
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +run --name community-ops --owner chroe --repo gitlink-cli --no-ai
|
||||
|
||||
workflow: community-ops
|
||||
repo: chroe/gitlink-cli
|
||||
|
||||
✅ open-issues → 获取所有开放 Issue [命令] 12 个 Issue
|
||||
✅ labels → 获取标签库 [命令] 15 个标签
|
||||
✅ members → 获取成员列表 [命令] 5 个成员
|
||||
✅ triage → AI 分析并执行分类/分配 [规则引擎] 12 个 Issue 已分类
|
||||
✅ repo-info → 获取项目基础信息 [命令] gitlink-cli
|
||||
✅ merged-prs → 获取已合并 PR [命令] 8 个 PR
|
||||
✅ commits → 获取提交历史 [命令] 50 条
|
||||
⏭ health-report 跳过: 下次运行: 07-17 15:04
|
||||
✅ releases → 获取版本发布记录 [命令] 3 个版本
|
||||
✅ changelog → 生成 Release Notes [规则引擎] 基于 20 个 commit
|
||||
|
||||
⚙️ 规则引擎已处理 3 个 skill 步骤 (未使用 AI)
|
||||
```
|
||||
|
||||
结果：
|
||||
- triage 步骤将 12 个 Issue 按关键词分为 5 类（bug×3、enhancement×5、docs×2、question×1、refactor×1），按负载均衡分配给了 5 个成员
|
||||
- health-report 跳过了——距离上次运行不到 7 天，`RunWhen: weekly` 生效
|
||||
- changelog 检测到上游 commits 有变更，按 conventional commits 自动生成 Release Notes
|
||||
|
||||
**用户：** triage 具体给 Issue 打了什么标签？
|
||||
|
||||
**Claude：** 规则引擎从输出中归类出了以下分配：
|
||||
|
||||
| Issue | 分类 | 优先级 | 分配给 |
|
||||
|-------|------|--------|--------|
|
||||
| #45 登录页面报错 | bug | P0 | 成员A |
|
||||
| #52 API 响应慢 | bug | P0 | 成员B |
|
||||
| #38 添加导出功能 | enhancement | P2 | 成员C |
|
||||
| #41 优化搜索性能 | enhancement | P1 | 成员A |
|
||||
| #55 更新 README | docs | P3 | 成员D |
|
||||
|
||||
其中 #58 被识别为 good-first-issue，已自动发布引导评论。
|
||||
|
||||
---
|
||||
|
||||
## 对话三：项目一键初始化（手动触发 + 规则引擎）
|
||||
|
||||
**用户：** 帮我在 yetja 下创建一个新项目，描述是「高性能计算调度平台」
|
||||
|
||||
**Claude：** 我用 project-init 工作流来完成。
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +run --name project-init --desc "高性能计算调度平台" --owner yetja --no-ai
|
||||
|
||||
workflow: project-init
|
||||
owner: yetja
|
||||
|
||||
✅ init-scaffold → 创建仓库+脚手架 [规则引擎] 仓库 hpc-platform
|
||||
✅ repo-info → 确认仓库已创建 [命令] yetja/hpc-platform
|
||||
✅ existing-files → 验证文件 [命令] README.md, LICENSE, .gitignore
|
||||
✅ labels → 验证标签库 [命令] 7 个标签
|
||||
✅ license-check → 许可证合规检查 [规则引擎] 通过
|
||||
✅ milestones → 验证里程碑 [命令] v0.1.0
|
||||
✅ existing-issues→ 验证初始 Issue [命令] 3 个 Issue
|
||||
✅ branches → 检查分支结构 [命令] master
|
||||
✅ repo-audit → 综合审计仓库健康度 [规则引擎] 健康度 100%
|
||||
|
||||
⚙️ 规则引擎已处理 3 个 skill 步骤 (未使用 AI)
|
||||
```
|
||||
|
||||
已创建仓库 `yetja/hpc-platform`，包含：
|
||||
- README.md（项目描述、快速开始、贡献指南）
|
||||
- MIT LICENSE
|
||||
- Go .gitignore
|
||||
- 7 个默认标签（bug/enhancement/docs/question/refactor/performance/security）
|
||||
- v0.1.0 里程碑 + 3 个初始 Issue（项目搭建、核心功能开发、文档完善）
|
||||
- 许可证合规检查通过，无敏感信息泄露
|
||||
|
||||
注意：当前是 no-ai 模式，仓库名从描述中提取了「高性能计算」对应的英文词生成。如果使用 AI 模式，AI 会给出更贴切的命名。
|
||||
|
||||
---
|
||||
|
||||
## 对话四：贡献者排行（定时调度模拟）
|
||||
|
||||
**用户：** 生成一下 chroe/gitlink-cli 的贡献者排行榜
|
||||
|
||||
**Claude：**
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +run --name contributor-growth --owner chroe --repo gitlink-cli --no-ai
|
||||
|
||||
workflow: contributor-growth
|
||||
repo: chroe/gitlink-cli
|
||||
|
||||
✅ commits → 提交历史统计 [命令] 100 条
|
||||
✅ open-issues → 开放 Issue 统计 [命令] 12 个
|
||||
✅ closed-issues → 已关闭 Issue 统计 [命令] 45 个
|
||||
✅ merged-prs → 已合并 PR 统计 [命令] 30 个
|
||||
✅ members → 成员列表 [命令] 5 个成员
|
||||
✅ repo-info → Fork/Star/Watch [命令] 12/45/30
|
||||
✅ contributor-ranking→ 生成排行+活跃分析 [规则引擎] 5 人排名
|
||||
|
||||
⚙️ 规则引擎已处理 1 个 skill 步骤 (未使用 AI)
|
||||
```
|
||||
|
||||
贡献者排行（规则引擎加权计算）：
|
||||
|
||||
| 排名 | 成员 | 提交 | Issue | PR | 加权分 | 状态 |
|
||||
|------|------|------|-------|-----|--------|------|
|
||||
| 1 | chroe | 45 | 20 | 15 | 265 | ✅ 活跃 |
|
||||
| 2 | yetja | 30 | 15 | 10 | 170 | ✅ 活跃 |
|
||||
| 3 | caoweiqiong | 20 | 10 | 5 | 115 | ✅ 活跃 |
|
||||
| 4 | 成员D | 8 | 5 | 0 | 34 | ⚠ 即将流失 |
|
||||
| 5 | 成员E | 2 | 1 | 0 | 8 | 🔴 已流失(>30天) |
|
||||
|
||||
---
|
||||
|
||||
## 对话五：多仓库协同
|
||||
|
||||
**用户：** 帮我跨 chroe/gitlink-cli 和 chroe/gitlink_help_center 做一次协同检查，协调 v1.4.0 发布
|
||||
|
||||
**Claude：**
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +run --name multi-repo \
|
||||
--repos "chroe/gitlink-cli,chroe/gitlink_help_center" \
|
||||
--release v1.4.0 --wiki-repo chroe/gitlink-cli --no-ai
|
||||
|
||||
workflow: multi-repo
|
||||
repos: chroe/gitlink-cli, chroe/gitlink_help_center
|
||||
|
||||
✅ multi-repo-snapshot → 采集仓库状态 [内部命令] 2 个仓库
|
||||
✅ multi-repo-coordination → 协同报告 [规则引擎] 发布到 Wiki
|
||||
|
||||
⚙️ 规则引擎已处理 1 个 skill 步骤 (未使用 AI)
|
||||
```
|
||||
|
||||
跨仓库协同报告已生成并发布到 chroe/gitlink-cli Wiki 页面「多仓库协同报告 2026-07-10」，包含：
|
||||
- 两个仓库的 Issue/PR/Release 状态对照表
|
||||
- v1.4.0 发布协调建议（help_center 有 2 个阻塞 PR 需先合并）
|
||||
|
||||
---
|
||||
|
||||
## 对话六：开启轮询监听
|
||||
|
||||
**用户：** 让代码质量门禁持续监听 chroe/gitlink-cli，每 5 分钟检查一次
|
||||
|
||||
**Claude：**
|
||||
|
||||
```
|
||||
> gitlink-cli workflow +watch --name code-quality --owner chroe --repo gitlink-cli --interval 5m
|
||||
|
||||
👀 Watching chroe/gitlink-cli for "open-prs" changes every 5m
|
||||
Trigger: poll on pr.opened
|
||||
Press Ctrl+C to stop
|
||||
|
||||
[15:00:01] ✓ no changes
|
||||
[15:05:01] ✓ no changes
|
||||
[15:10:01] 🔔 change detected: [open-prs]
|
||||
✓ open-prs → 2 个 PR
|
||||
✓ ci-builds → 10 个构建记录
|
||||
✓ repo-info → gitlink-cli
|
||||
✓ commits → 30 条
|
||||
✓ branches → 2 个分支
|
||||
✓ review → 1 个新 PR 已审查 [规则引擎]
|
||||
✓ ci-diagnosis → 无失败构建 [规则引擎]
|
||||
[15:15:01] ✓ no changes
|
||||
^C
|
||||
👋 watch stopped
|
||||
```
|
||||
|
||||
当有新 PR 提交时自动触发完整审查流程，未变更时跳过，避免无效计算。
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
以上对话展示了工作流引擎的四种使用方式：
|
||||
|
||||
| 方式 | 示例 | 适用场景 |
|
||||
|------|------|---------|
|
||||
| 手动 + 规则引擎 | 代码审查、Issue 分拣、项目初始化 | 无 AI Key 环境、确定性任务 |
|
||||
| 条件跳过 | 周报 `RunWhen: weekly` | 避免重复执行 |
|
||||
| 多仓库协同 | `--repos` 跨仓库快照 + 报告 | 跨项目协调 |
|
||||
| 轮询监听 | `+watch` 持续监控 | 生产环境长期运行 |
|
||||
|
|
@ -1,45 +0,0 @@
|
|||
# 子赛题三 · 端到端自动化工作流
|
||||
|
||||
基于 gitlink-cli 构建的**工作流引擎**，将"工作流"抽象为一等公民——声明式定义步骤序列，引擎负责执行、数据传递、AI/规则双模降级、安全过滤。五个预置工作流覆盖社区运营、代码质量、项目初始化、多仓库协同、贡献者成长五个场景，支持手动、轮询、定时、守护四种触发模式。
|
||||
|
||||
## 文件清单
|
||||
|
||||
| 文件 | 说明 |
|
||||
|------|------|
|
||||
| [工作流说明.md](工作流说明.md) | 引擎架构、五种工作流详述、四种触发模式、AI/规则双模降级、安全边界 |
|
||||
| [架构图.png](架构图.png) | 工作流引擎五层架构图（触发层→引擎层→执行层→AI层→安全层） |
|
||||
| [执行脚本.sh](执行脚本.sh) | 一键可复现执行脚本 |
|
||||
| [Agent对话记录.md](Agent对话记录.md) | Claude Code 自然语言触发工作流的完整对话 |
|
||||
| [demos/](demos/) | 真实项目运行录屏与截图 |
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 列出所有工作流
|
||||
./gitlink-cli workflow +list
|
||||
|
||||
# 查看工作流详情
|
||||
./gitlink-cli workflow +info --name code-quality
|
||||
|
||||
# 运行代码质量门禁（规则引擎模式，无需 AI Key）
|
||||
./gitlink-cli workflow +run --name code-quality --owner <your-org> --repo <your-repo> --no-ai
|
||||
|
||||
# 项目一键初始化
|
||||
./gitlink-cli workflow +run --name project-init --desc "高性能计算调度平台" --owner <your-org>
|
||||
```
|
||||
|
||||
## 代码位置
|
||||
|
||||
```
|
||||
shortcuts/workflow/
|
||||
├── types.go # 类型定义
|
||||
├── registry.go # 注册中心
|
||||
├── defs/ # 5 个预置工作流声明式定义
|
||||
├── engine/ # 执行引擎（Run / 步骤分发 / AI决策 / 安全白名单）
|
||||
├── cli/ # 10 个 CLI 子命令
|
||||
├── daemon/ # watch / schedule / daemon 触发模式
|
||||
├── ai/ # DeepSeek / Anthropic 客户端
|
||||
├── state/ # 状态持久化 / 快照 Diff / PR 去重
|
||||
├── rules/ # 11 个规则引擎实现（AI 降级 fallback）
|
||||
└── skills/ # 工作流专属 Skill 文档
|
||||
```
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue