Merge PR #244: feat(skills): 新增科研主体画像 Skill（gitlink-research-profile）

# Conflicts: # skills/README.md
2026-07-14 22:49:54 +08:00 · 2026-07-14 22:49:54 +08:00 · 42a4ecdf8e
parent ed8000d7ae 979c70c4b0
commit 42a4ecdf8e
6 changed files with 749 additions and 41 deletions
--- a/skills/README.md
+++ b/skills/README.md
@ -32,7 +32,7 @@ gitlink-cli auth status
 gitlink-cli user +me
 ```

-详见: [gitlink-shared/SKILL.md](gitlink-shared/SKILL.md)
+详见: [gitlink-shared/examples/auth-workflow.md](gitlink-shared/examples/auth-workflow.md)

 ### 2. 查看可用命令

@ -64,19 +64,25 @@ skills/
 ├── README.md                          # 本文件
 ├── gitlink-shared/                    # 共享基础规则
 │   ├── SKILL.md                       # 认证、全局参数、安全规则、分支约定
-│   └── references/
-│       ├── api-reference.md           # API 详细参考、错误处理
-│       ├── raw-api-batch.md           # 批量 Raw API 调用参考
-│       └── troubleshooting.md         # 常见问题排查
+│   ├── REFERENCE.md                   # API 详细参考、错误处理
+│   ├── TROUBLESHOOTING.md             # 常见问题排查
+│   └── examples/
+│       └── auth-workflow.md           # 认证工作流示例
 ├── gitlink-repo/                      # 仓库管理
 │   ├── SKILL.md                       # 仓库操作指南
-│   └── references/                    # 仓库命令参考文档
+│   ├── REFERENCE.md                   # 仓库 API 参考
+│   └── examples/
+│       └── repo-workflow.md           # 仓库管理工作流
 ├── gitlink-issue/                     # Issue 管理
 │   ├── SKILL.md                       # Issue 操作指南
-│   └── references/                    # Issue 命令参考文档
+│   ├── REFERENCE.md                   # Issue API 参考
+│   └── examples/
+│       └── issue-workflow.md          # Issue 全流程工作流
 ├── gitlink-pr/                        # Pull Request
 │   ├── SKILL.md                       # PR 操作指南
-│   └── references/                    # PR 命令参考文档
+│   ├── REFERENCE.md                   # PR API 参考
+│   └── examples/
+│       └── pr-workflow.md             # PR 工作流
 ├── gitlink-member/                    # 仓库成员管理
 │   └── SKILL.md                       # 成员与邀请链接操作指南
 ├── gitlink-branch/                    # 分支管理
@ -85,24 +91,25 @@ skills/
 │       └── branch-workflow.md         # 分支工作流
 ├── gitlink-release/                   # 版本发布
 │   ├── SKILL.md                       # Release 操作指南
-│   └── references/                    # Release 命令参考文档
-├── gitlink-release-auto/              # 自动化 Release 管理
-│   └── SKILL.md                       # 自动发版、版本号推荐、Release Notes 生成
+│   ├── REFERENCE.md                   # Release API 参考
+│   └── examples/
+│       └── release-workflow.md        # Release 工作流
 ├── gitlink-search/                    # 搜索功能
 │   ├── SKILL.md                       # 搜索操作指南
-│   └── references/                    # 搜索命令参考文档
+│   └── examples/
+│       └── search-workflow.md         # 搜索工作流
 ├── gitlink-user/                      # 用户管理
-│   ├── SKILL.md                       # 用户操作指南
-│   └── references/                    # 用户命令参考文档
+│   └── SKILL.md                       # 用户操作指南
 ├── gitlink-org/                       # 组织管理
 │   ├── SKILL.md                       # 组织操作指南
-│   └── references/                    # 组织命令参考文档
+│   └── examples/
+│       └── org-workflow.md            # 组织工作流
 ├── gitlink-ci/                        # CI/CD
-│   └── SKILL.md                       # CI 操作指南
+│   ├── SKILL.md                       # CI 操作指南
+│   └── examples/
+│       └── ci-workflow.md             # CI 工作流
 ├── gitlink-pipeline/                  # 流水线工作流
 │   └── SKILL.md                       # Pipeline 操作指南
-├── gitlink-wiki/                      # Wiki 页面管理
-│   └── SKILL.md                       # Wiki 操作指南
 ├── gitlink-pm/                        # 项目管理
 │   └── SKILL.md                       # PM 操作指南
 ├── gitlink-health/                    # 项目健康度分析
@ -114,10 +121,6 @@ skills/
 │   │   └── queries.md                 # SQL 查询参考
 │   └── asset/
 │       └── health_report_template.md  # 报告模板
-├── gitlink-research-trust/            # 科研开源可信度评估
-│   ├── SKILL.md                       # 复现性、可追踪性、合规与文档评分
-│   └── examples/
-│       └── research-trust-workflow.md # 科研可信度工作流示例
 └── gitlink-workflow/                  # AI 自动化工作流
    └── SKILL.md                       # 工作流模板（Issue 分类、PR Review、Release Notes）
 ```
@ -132,7 +135,7 @@ skills/
 |-------|------|----------|
 | **gitlink-shared** | 认证、全局参数、API 参考、安全规则、分支约定 | `auth login`, `auth status` |
 | **gitlink-repo** | 仓库管理与洞察 | `repo +list`, `repo +info`, `repo +languages`, `repo +contributors`, `repo +code-stats`, `repo +follow`, `repo +like` |
-| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close`, `issue +batch-update`, `issue +batch-delete` |
+| **gitlink-issue** | Issue 管理 | `issue +create`, `issue +list`, `issue +view`, `issue +close`, `issue +batch-close` |
 | **gitlink-pr** | Pull Request | `pr +list`, `pr +create`, `pr +view`, `pr +merge`, `pr +versions`, `pr +version-diff`, `pr +reviews`, `pr +review` |
 | **gitlink-member** | 仓库成员管理 | `member +list`, `member +add`, `member +batch-add`, `member +role`, `member +invite-link` |
 | **gitlink-branch** | 分支管理 | `branch +list`, `branch +create`, `branch +delete`, `branch +protect` |
@ -147,12 +150,10 @@ skills/
 | **gitlink-org** | 组织管理 | `org +list`, `org +info`, `org +members` |
 | **gitlink-ci** | CI/CD | `ci +builds`, `ci +logs` |
 | **gitlink-pipeline** | 流水线工作流 | `pipeline +runs`, `pipeline +run`, `pipeline +logs` |
-| **gitlink-wiki** | Wiki 页面管理 | `wiki +list`, `wiki +view`, `wiki +create`, `wiki +update`, `wiki +delete` |
 | **gitlink-pm** | 项目管理 | 通过 Raw API 访问 |
 | **gitlink-workflow** | AI 工作流 | Issue 分类、PR Review、Release Notes |
-| **gitlink-pr-assessor** | open PR 队列评估与执行验证 | open 未审查 PR 扫描、维护者报告 |
 | **gitlink-health** | 开源项目健康度 | 详情见SKILL.md |
-| **gitlink-research-trust** | 科研开源可信度评估 | `search +repos`, `repo +info`, `repo +tree`, `repo +readme` |
+| **gitlink-research-profile** | 科研主体画像（人/团队） | `profile +ability`, `profile +major`, `profile +role` |

 ---

@ -169,7 +170,7 @@ gitlink-cli repo +info
 gitlink-cli repo +info --owner wbtiger --repo gitlink-cli
 ```

-详见: [gitlink-repo/SKILL.md](gitlink-repo/SKILL.md)
+详见: [gitlink-repo/examples/repo-workflow.md](gitlink-repo/examples/repo-workflow.md)

 ### 场景 2：创建和管理 Issue

@ -190,7 +191,7 @@ gitlink-cli issue +close -i 123
 gitlink-cli issue +batch-close --numbers 123,124 --dry-run
 ```

-详见: [gitlink-issue/SKILL.md](gitlink-issue/SKILL.md)
+详见: [gitlink-issue/examples/issue-workflow.md](gitlink-issue/examples/issue-workflow.md)

 ### 场景 3：管理分支和发布

@ -208,7 +209,7 @@ gitlink-cli release +create -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."
 gitlink-cli release +view -i <version_id>
 ```

-详见: [gitlink-release/SKILL.md](gitlink-release/SKILL.md)
+详见: [gitlink-release/examples/release-workflow.md](gitlink-release/examples/release-workflow.md)

 ### 场景 4：搜索和发现

@ -224,7 +225,7 @@ gitlink-cli org +list
 gitlink-cli org +info -i Gitlink
 ```

-详见: [gitlink-search/SKILL.md](gitlink-search/SKILL.md)
+详见: [gitlink-search/examples/search-workflow.md](gitlink-search/examples/search-workflow.md)

 ---

@ -233,8 +234,8 @@ gitlink-cli org +info -i Gitlink
 ### 快速查找

 - **我想了解认证**: [gitlink-shared/SKILL.md](gitlink-shared/SKILL.md)
- **我想查看 API 细节**: [gitlink-shared/references/api-reference.md](gitlink-shared/references/api-reference.md)
- **我遇到了错误**: [gitlink-shared/references/troubleshooting.md](gitlink-shared/references/troubleshooting.md)
+- **我想查看 API 细节**: [gitlink-shared/REFERENCE.md](gitlink-shared/REFERENCE.md)
+- **我遇到了错误**: [gitlink-shared/TROUBLESHOOTING.md](gitlink-shared/TROUBLESHOOTING.md)
 - **我想看工作流示例**: 查看各 Skill 下的 `examples/` 目录

 ### 按功能分类
@ -242,12 +243,12 @@ gitlink-cli org +info -i Gitlink
 **仓库操作**:
 - [gitlink-repo/SKILL.md](gitlink-repo/SKILL.md) - 仓库命令
 - [gitlink-branch/SKILL.md](gitlink-branch/SKILL.md) - 分支命令
- [gitlink-repo/SKILL.md](gitlink-repo/SKILL.md) - 完整工作流
+- [gitlink-repo/examples/repo-workflow.md](gitlink-repo/examples/repo-workflow.md) - 完整工作流

 **Issue 和 PR**:
 - [gitlink-issue/SKILL.md](gitlink-issue/SKILL.md) - Issue 命令
 - [gitlink-pr/SKILL.md](gitlink-pr/SKILL.md) - PR 命令
- [gitlink-issue/SKILL.md](gitlink-issue/SKILL.md) - Issue 工作流
+- [gitlink-issue/examples/issue-workflow.md](gitlink-issue/examples/issue-workflow.md) - Issue 工作流

 **发布和搜索**:
 - [gitlink-release/SKILL.md](gitlink-release/SKILL.md) - Release 命令
@ -289,11 +290,11 @@ gitlink-cli auth login

 ### Q: 如何查看完整的 API 参考？

-A: 查看 [gitlink-shared/references/api-reference.md](gitlink-shared/references/api-reference.md)
+A: 查看 [gitlink-shared/REFERENCE.md](gitlink-shared/REFERENCE.md)

 ### Q: 遇到错误怎么办？

-A: 查看 [gitlink-shared/references/troubleshooting.md](gitlink-shared/references/troubleshooting.md)
+A: 查看 [gitlink-shared/TROUBLESHOOTING.md](gitlink-shared/TROUBLESHOOTING.md)

 ---

@ -329,7 +330,7 @@ AI 代理可以：
 - 所有边界情况处理正确
 - 完整的文档和示例

-详见: [../doc/design.md](../doc/design.md)
+详见: [../doc/SKILLS_TEST_REPORT_2026-04-02.md](../doc/SKILLS_TEST_REPORT_2026-04-02.md)

 ---

@ -337,7 +338,8 @@ AI 代理可以：

 - [主项目 README](../README.md) - gitlink-cli 项目说明
 - [设计文档](../doc/design.md) - 架构设计和开发计划
- [API 参考文档](../doc/gitlink_api_reference.md) - GitLink API 参考文档
+- [测试报告](../doc/SKILLS_TEST_REPORT_2026-04-02.md) - 功能测试报告
+- [代码同步方案](../doc/CODE_SYNC_STRATEGY_FINAL.md) - GitHub ↔ GitLink 同步设计
 - [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) - 代码双向同步系统

 ---
@ -345,8 +347,8 @@ AI 代理可以：
 ## 📞 获取帮助

 - **命令帮助**: `gitlink-cli <command> --help`
- **故障排查**: [gitlink-shared/references/troubleshooting.md](gitlink-shared/references/troubleshooting.md)
- **API 参考**: [gitlink-shared/references/api-reference.md](gitlink-shared/references/api-reference.md)
+- **故障排查**: [gitlink-shared/TROUBLESHOOTING.md](gitlink-shared/TROUBLESHOOTING.md)
+- **API 参考**: [gitlink-shared/REFERENCE.md](gitlink-shared/REFERENCE.md)
 - **工作流示例**: 查看各 Skill 下的 `examples/` 目录

 ---
@ -354,7 +356,7 @@ AI 代理可以：
 ## 🎓 下一步

 1. 阅读 [gitlink-shared/SKILL.md](gitlink-shared/SKILL.md) 了解基础
-2. 查看 [gitlink-shared/SKILL.md](gitlink-shared/SKILL.md) 完成认证
+2. 查看 [gitlink-shared/examples/auth-workflow.md](gitlink-shared/examples/auth-workflow.md) 完成认证
 3. 根据需求选择相应的 Skill 文档
 4. 参考 `examples/` 目录中的工作流示例
 5. 使用 AI 代理自动化你的工作流
--- a/skills/gitlink-research-profile/REFERENCE.md
+++ b/skills/gitlink-research-profile/REFERENCE.md
@ -0,0 +1,152 @@
+# gitlink-research-profile — API 字段参考
+
+本文档列出 `gitlink-cli profile` 各子命令对应的 GitLink 平台接口、参数与返回字段，
+字段结构基于真实接口响应整理。所有命令均为只读。
+
+> 统一说明：`gitlink-cli` 返回结构为 `{"ok": true, "data": {...}}`，下文"字段"均指 `data` 内的路径。
+> 平台原始接口路径为 `/api/users/{owner}/statistics/*` 与 `/api/users/{owner}/headmaps`，
+> `gitlink-cli` 自动处理认证与 `.json` 后缀。
+
+---
+
+## 1. `profile +ability` — 开发能力
+
+- 命令：`gitlink-cli profile +ability --user <login> [--start-time <unix>] [--end-time <unix>]`
+- 接口：`GET /api/users/{login}/statistics/develop`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `platform.influence` | int(0–100) | 平台影响力基线（头部参照） |
+| `platform.contribution` | int | 平台贡献度基线 |
+| `platform.activity` | int | 平台活跃度基线 |
+| `platform.experience` | int | 平台项目经验基线 |
+| `platform.language` | int | 平台语言能力基线 |
+| `user.influence` | int(0–100) | 用户影响力 |
+| `user.contribution` | int | 用户贡献度 |
+| `user.activity` | int | 用户活跃度 |
+| `user.experience` | int | 用户项目经验 |
+| `user.language` | int | 用户语言能力 |
+| `user.languages_percent` | object{string:float} | 各语言代码量占比（0–1），键为语言名 |
+| `user.each_language_score` | object{string:int} | 各语言能力分（0–100） |
+
+示例（节选）：
+
+```json
+{
+  "platform": {"activity":99,"contribution":99,"experience":99,"influence":99,"language":98},
+  "user": {
+    "activity":94,"contribution":97,"experience":97,"influence":79,"language":90,
+    "languages_percent": {"Go":0.2,"Java":0.13,"HTML":0.11,"JavaScript":0.09},
+    "each_language_score": {"Go":87,"Java":83,"HTML":81,"JavaScript":80}
+  }
+}
+```
+
+---
+
+## 2. `profile +major` — 学科 / 研究方向
+
+- 命令：`gitlink-cli profile +major --user <login> [--start-time] [--end-time]`
+- 接口：`GET /api/users/{login}/statistics/major`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `categories` | [string] | 平台推断的研究/技术方向标签，可能为空数组 |
+
+示例：
+
+```json
+{ "categories": ["人工智能","大数据","生物医药健康","天文地球物理","操作系统"] }
+```
+
+> 标签数量极多（20+）通常意味着账号参与/镜像了大量异质项目（平台维护者或镜像聚合），
+> 需结合 `user +info.mirror_projects_count` 判断方向是否"虚泛"。
+
+---
+
+## 3. `profile +role` — 角色定位
+
+- 命令：`gitlink-cli profile +role --user <login> [--start-time] [--end-time]`
+- 接口：`GET /api/users/{login}/statistics/role`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role.owner.count` / `role.owner.percent` | int / float | 作为 owner 的项目数 / 占比 |
+| `role.manager.count` / `.percent` | int / float | 作为 manager 的项目数 / 占比 |
+| `role.developer.count` / `.percent` | int / float | 作为 developer 的项目数 / 占比 |
+| `role.reporter.count` / `.percent` | int / float | 作为 reporter 的项目数 / 占比 |
+| `total_projects_count` | int | 参与项目总数 |
+
+示例：
+
+```json
+{
+  "role": {
+    "owner": {"count":20,"percent":0.99},
+    "manager": {"count":2,"percent":0},
+    "developer": {"count":5,"percent":0},
+    "reporter": {"count":1,"percent":0}
+  },
+  "total_projects_count": 28
+}
+```
+
+> `percent` 为四舍五入小数，小占比可能显示为 0；解读时以 `count` 为准。
+
+---
+
+## 4. `profile +activity` — 近期活动
+
+- 命令：`gitlink-cli profile +activity --user <login>`
+- 接口：`GET /api/users/{login}/statistics/activity`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `dates` | [string] | 日期序列（如 `2026.06.14`），通常近一周 |
+| `commits_count` | [int] | 与 `dates` 等长，逐日提交数 |
+| `issues_count` | [int] | 与 `dates` 等长，逐日疑修数 |
+| `pull_requests_count` | [int] | 与 `dates` 等长，逐日合并请求数 |
+
+> 四个数组**等长且按下标对齐**：第 i 天 = `dates[i]`，当日提交 = `commits_count[i]`。
+
+---
+
+## 5. `profile +contribution` — 贡献热力图
+
+- 命令：`gitlink-cli profile +contribution --user <login> [--year <yyyy>]`
+- 接口：`GET /api/users/{login}/headmaps`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `total_contributions` | int | 时间范围内贡献总量 |
+| `headmaps` | [object] | 每日贡献数组 |
+| `headmaps[].date` | string | 日期（`YYYY-MM-DD`） |
+| `headmaps[].contributions` | int | 当日贡献数 |
+
+示例（节选）：
+
+```json
+{ "total_contributions": 1280, "headmaps": [ {"date":"2025-06-16","contributions":80}, {"date":"2025-06-18","contributions":28} ] }
+```
+
+---
+
+## 6. 辅助命令
+
+| 命令 | 用途 | 关键字段 |
+|------|------|----------|
+| `gitlink-cli user +info --login <login>` | 基础资料 | `name`/`real_name`、`custom_department`（机构）、`city`/`province`、`common_projects_count`、`mirror_projects_count`、`created_time` |
+| `gitlink-cli search +users -k <kw>` | 按关键词找用户、确认 login | 结果含 `login`、`name` |
+| `gitlink-cli dataset +list --ids <projectIds>` | 查询科研数据集（论文/许可证） | `project_datasets[].{title,description,paper_content,license}` |
+
+---
+
+## 等价 Raw API（当 `profile` 命令不可用时）
+
+```bash
+gitlink-cli api GET /users/<login>/statistics/develop
+gitlink-cli api GET /users/<login>/statistics/major
+gitlink-cli api GET /users/<login>/statistics/role
+gitlink-cli api GET /users/<login>/statistics/activity
+gitlink-cli api GET /users/<login>/headmaps
+```
--- a/skills/gitlink-research-profile/SKILL.md
+++ b/skills/gitlink-research-profile/SKILL.md
@ -0,0 +1,249 @@
+---
+name: gitlink-research-profile
+version: 1.0.0
+description: "科研主体画像：基于 GitLink 平台原生统计接口，为科研工作者/课题组生成开发能力雷达、学科领域分布、角色定位、活跃节奏与语言栈画像，并支持团队画像与跨学科协作匹配。当用户需要了解某位研究者/团队的能力与方向、做人才评估、组队或寻找协作伙伴时触发。"
+metadata:
+  requires:
+    bins: ["gitlink-cli"]
+  cliHelp: "gitlink-cli profile --help"
+---
+
+# gitlink-research-profile（科研主体画像）
+
+**CRITICAL — 开始前必须先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)，其中包含认证、权限处理和 API 注意事项。**
+**CRITICAL — 本 Skill 为只读操作，不会修改任何仓库或用户数据。无需用户额外确认即可执行。**
+**CRITICAL — GitLink 操作只能用 `gitlink-cli`。禁止用 `gh`（GitHub CLI）操作 GitLink 资源。**
+
+> **前置条件：** 先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md) 了解认证和全局参数。
+> **依赖命令：** 本 Skill 依赖 `gitlink-cli profile`（开发能力/学科/角色/活动/贡献统计）。如提示命令不存在，请升级 gitlink-cli 至包含 `profile` 命令组的版本。
+
+---
+
+## 功能概述
+
+面向**科研工作者、课题组、科研团队**的主体画像工具。不同于以"项目/主题"为中心的
+[`gitlink-research-tracker`](../gitlink-research-tracker/SKILL.md)（技术调研）和以"PR 时间戳推算活跃度"
+为主的 [`gitlink-contributor-insight`](../gitlink-contributor-insight/SKILL.md)，本 Skill 以**人/团队为中心**，
+直接消费 GitLink **平台原生画像接口**（`/api/users/{owner}/statistics/*`），刻画其科研能力与方向：
+
+1. **开发能力雷达** — 影响力 / 贡献度 / 活跃度 / 项目经验 / 语言能力 五维评分（含平台基线对照）
+2. **学科领域画像** — 平台推断的研究方向标签（如人工智能、大数据、生物医药健康、天文地球物理…）
+3. **角色定位** — 在所参与项目中作为 owner / manager / developer / reporter 的分布
+4. **活跃节奏** — 近一周提交/疑修/合并请求趋势 + 一年贡献热力图与总量
+5. **语言技术栈** — 各语言占比与单语言能力分
+6. **团队画像与协作匹配** — 多人横向对比、学科互补度分析、组队/找人建议
+
+---
+
+## 适用场景
+
+| 场景 | 说明 |
+|------|------|
+| 科研人才评估 | 评估候选人/合作者的能力结构、研究方向与活跃度 |
+| 课题组盘点 | 汇总团队成员能力与学科覆盖，识别短板与重叠 |
+| 跨学科协作匹配 | 按学科互补 + 能力互补，为某研究方向推荐协作伙伴 |
+| 新成员定位 | 快速了解新人的技术栈与擅长方向，合理分工 |
+| 个人科研复盘 | 研究者自查能力画像与活跃趋势，规划成长 |
+
+---
+
+## 工作流 1：单个科研主体画像
+
+### Step 1：确认目标用户标识（login）
+
+用户给出的可能是姓名或登录名。`profile` 系列命令需要 **login**（用户标识，非昵称）。
+如不确定，先搜索或读取用户资料确认：
+
+```bash
+# 通过关键词搜索用户，确认 login
+gitlink-cli search +users -k "<姓名或关键词>" --format json
+
+# 读取用户资料（确认 login、机构、地区等）
+gitlink-cli user +info --login <login> --format json
+```
+
+`user +info` 关键字段：`name`/`real_name`（姓名）、`custom_department`（所属机构/院校）、
+`city`/`province`（地区）、`common_projects_count`（原创项目数）、`created_time`（注册时间）。
+
+### Step 2：采集五类画像数据
+
+对目标 `<login>` 依次执行（全部只读）：
+
+```bash
+gitlink-cli profile +ability      --user <login> --format json   # 开发能力 + 语言栈
+gitlink-cli profile +major        --user <login> --format json   # 学科领域标签
+gitlink-cli profile +role         --user <login> --format json   # 角色分布
+gitlink-cli profile +activity     --user <login> --format json   # 近一周活跃
+gitlink-cli profile +contribution --user <login> --format json   # 一年贡献热力图
+```
+
+> `+ability/+major/+role` 支持 `--start-time/--end-time`（Unix 时间戳）限定区间；
+> `+contribution` 支持 `--year`。不带则为平台默认窗口。
+
+### Step 3：字段解析
+
+详见 [REFERENCE.md](REFERENCE.md)。核心映射：
+
+| 画像维度 | 命令 | 字段 | 解读 |
+|----------|------|------|------|
+| 能力五维（用户） | `+ability` | `data.user.{influence,contribution,activity,experience,language}` | 0–100，越高越强 |
+| 能力五维（平台基线） | `+ability` | `data.platform.{...}` | 平台 Top 水平参照，用于对照而非简单比高低 |
+| 语言占比 | `+ability` | `data.user.languages_percent{}` | 各语言代码量占比（0–1） |
+| 单语言能力分 | `+ability` | `data.user.each_language_score{}` | 各语言 0–100 |
+| 学科领域 | `+major` | `data.categories[]` | 平台推断的研究/技术方向标签 |
+| 角色分布 | `+role` | `data.role.{owner,manager,developer,reporter}.{count,percent}` | 项目参与角色构成 |
+| 总项目数 | `+role` | `data.total_projects_count` | 参与项目总量 |
+| 近周活跃 | `+activity` | `data.dates[]` 对齐 `commits_count[]/issues_count[]/pull_requests_count[]` | 三条等长时间序列 |
+| 贡献热力 | `+contribution` | `data.total_contributions`、`data.headmaps[].{date,contributions}` | 年度贡献总量与每日分布 |
+
+### Step 4：能力分级与解读规则
+
+| 维度分值 | 等级 | 解读 |
+|----------|------|------|
+| ≥90 | 卓越 | 平台头部水平 |
+| 75–89 | 优秀 | 明显高于平均 |
+| 60–74 | 良好 | 稳定贡献者 |
+| 40–59 | 一般 | 参与度有限 |
+| <40 | 较弱 | 数据稀疏或新用户 |
+
+- **语言栈**：取 `languages_percent` 降序前 3–5 种作为"主力语言"，结合 `each_language_score` 标注熟练度。
+- **学科聚焦度**：`categories` 数量少而集中 → 方向专精；数量多而分散 → 通才/平台维护者（需结合
+  `user +info` 的 `mirror_projects_count` 判断是否为镜像聚合导致的虚高）。
+- **角色画像**：`owner` 占比高 → 主导者/项目发起人；`developer`/`reporter` 占比高 → 参与贡献型。
+
+### Step 5：生成单主体画像报告
+
+使用下方[输出模板](#输出模板单主体)。示例见
+[`examples/researcher-profile-report.md`](examples/researcher-profile-report.md)。
+
+---
+
+## 工作流 2：团队画像与协作匹配
+
+### Step 1：确定成员名单
+
+用户给出一组 `login`（课题组成员），或给出研究方向由你先 `search +users` 找候选。
+
+### Step 2：逐人采集
+
+对每个成员执行工作流 1 的 Step 2（建议每人至少 `+ability` 和 `+major`，控制调用量）。
+
+### Step 3：团队聚合分析
+
+- **能力矩阵**：成员 × 能力五维的表格，算团队均值与最强项/短板。
+- **学科覆盖**：合并所有成员 `categories`，统计覆盖的学科与重叠度（多人共有 vs 独有方向）。
+- **语言栈覆盖**：合并 `languages_percent` 主力语言，识别团队技术栈与缺口。
+- **角色结构**：统计 owner/manager/developer 分布，判断团队是"多主导"还是"主导+执行"。
+
+### Step 4：协作匹配（可选）
+
+给定一个目标研究方向或一位核心研究者：
+
+1. 候选发现：`search +users -k <方向关键词>`，对候选取 `+major` 和 `+ability`。
+2. **学科互补度**：候选的 `categories` 与目标方向/团队缺口的契合度（覆盖空白方向加分）。
+3. **能力互补度**：候选在团队短板维度（如 `language`/`experience`）上的得分（补强加分）。
+4. 输出推荐列表，每位候选给出匹配理由（覆盖了哪个学科空白 / 补强了哪项能力）。
+
+### Step 5：生成团队/匹配报告
+
+使用[团队输出模板](#输出模板团队与匹配)。
+
+---
+
+## 输出模板（单主体）
+
+```markdown
+# 🔬 科研主体画像：{{name}}（@{{login}}）
+
+> 生成时间：{{now}} ｜ 数据来源：GitLink 平台统计接口（`gitlink-cli profile`）
+> 机构：{{custom_department}} ｜ 地区：{{province}}{{city}} ｜ 注册：{{created_time}}
+
+## 一、综合摘要
+{{2–3 句话总结：擅长方向、主力语言、能力亮点与活跃状态}}
+
+## 二、开发能力雷达（0–100）
+
+| 维度 | 用户 | 平台基线 | 等级 |
+|------|------|----------|------|
+| 影响力 influence | {{u.influence}} | {{p.influence}} | {{等级}} |
+| 贡献度 contribution | {{u.contribution}} | {{p.contribution}} | {{等级}} |
+| 活跃度 activity | {{u.activity}} | {{p.activity}} | {{等级}} |
+| 项目经验 experience | {{u.experience}} | {{p.experience}} | {{等级}} |
+| 语言能力 language | {{u.language}} | {{p.language}} | {{等级}} |
+
+## 三、学科领域
+{{categories 列表，聚焦方向加粗；附"方向聚焦度"判断}}
+
+## 四、角色定位
+参与项目 {{total_projects_count}} 个 — Owner {{owner.count}}（{{owner.percent}}）/ Manager {{...}} / Developer {{...}} / Reporter {{...}}
+{{一句话角色画像}}
+
+## 五、语言技术栈
+
+| 语言 | 占比 | 能力分 |
+|------|------|--------|
+| {{lang}} | {{percent}} | {{score}} |
+（取前 5）
+
+## 六、活跃节奏
+- 近一周：提交 {{sum_commits}}、疑修 {{sum_issues}}、PR {{sum_prs}}
+- 年度贡献总量：{{total_contributions}}；活跃峰值日：{{peak_date}}（{{peak_value}}）
+
+## 七、画像结论与建议
+{{适合的角色/方向、可补强的能力、协作建议}}
+```
+
+## 输出模板（团队与匹配）
+
+```markdown
+# 🔬 课题组科研画像：{{team_name}}（{{n}} 人）
+
+## 一、能力矩阵（0–100）
+| 成员 | 影响力 | 贡献度 | 活跃度 | 经验 | 语言 |
+|------|--------|--------|--------|------|------|
+| {{login}} | ... | ... | ... | ... | ... |
+| **团队均值** | ... | ... | ... | ... | ... |
+
+## 二、学科覆盖
+- 共有方向：{{多人共有}}
+- 独有方向：{{各自独有}}
+- 覆盖空白：{{团队未覆盖但相关的方向}}
+
+## 三、技术栈与角色结构
+{{主力语言覆盖与缺口；owner/developer 结构}}
+
+## 四、协作匹配推荐（如适用）
+| 候选 | 匹配度 | 学科互补 | 能力互补 | 推荐理由 |
+|------|--------|----------|----------|----------|
+| @{{login}} | 高/中 | {{补的方向}} | {{补的能力}} | {{一句话}} |
+
+## 五、结论
+{{团队优势、短板、补人/分工建议}}
+```
+
+---
+
+## 异常场景处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 用户给的是姓名不是 login | 先 `search +users -k` 或 `user +info` 确认 login，再调用 profile |
+| `profile` 命令不存在 | 提示升级 gitlink-cli 到含 `profile` 命令组的版本；或临时用 `gitlink-cli api GET /users/<login>/statistics/develop` 等价获取 |
+| 某接口返回空（如 `categories: []`、活动全 0） | 标注"该维度数据稀疏"，不臆造；说明可能是新用户或近期不活跃 |
+| 用户 `owner.count`/学科数量异常巨大 | 结合 `user +info` 的 `mirror_projects_count` 判断是否为平台管理员/镜像聚合账号，画像中标注"含镜像聚合，方向分布偏泛" |
+| 404 用户不存在 | 确认 login 拼写（区分大小写），或该账号已注销 |
+| 团队成员过多（>10） | 优先核心成员；逐人串行调用，避免并发触发限流/TLS 超时 |
+| 网络超时/TLS 错误 | 等待 5 秒重试一次；仍失败则跳过该用户并在报告中标注"数据获取失败" |
+
+---
+
+## 注意事项
+
+- ✅ **全部命令使用 `--format json`**，便于解析。
+- ✅ **本 Skill 为纯只读画像**，不修改任何数据，无需确认即可执行。
+- ✅ **平台基线对照**：`platform.*` 是平台头部参照值（常接近满分），用于说明"距头部的差距"，不要简单地把 user 与 platform 相减当作排名。
+- ⚠️ **login ≠ 昵称**：`profile` 命令的 `--user` 必须是 login（用户标识）。
+- ⚠️ **镜像/管理员账号会让 `role`/`major` 虚高**：参与项目数上万、学科 20+ 往往是平台账号或大量镜像导致，需结合 `user +info` 的 `mirror_projects_count` 标注，避免误读为"全能科研牛人"。
+- ⚠️ **数据为 GitLink 平台内画像**，反映其在 GitLink 上的行为，不代表其在其他平台或线下的全部科研产出。
+- ⚠️ **`+activity` 三个计数数组与 `dates` 等长且按下标对齐**，解读时务必按同一下标取值。
+```
--- a/skills/gitlink-research-profile/TROUBLESHOOTING.md
+++ b/skills/gitlink-research-profile/TROUBLESHOOTING.md
@ -0,0 +1,169 @@
+# gitlink-research-profile — 故障排查
+
+**CRITICAL — 开始前请先阅读 [`../gitlink-shared/SKILL.md`](../gitlink-shared/SKILL.md)（认证、全局参数）与 [`./SKILL.md`](./SKILL.md)（工作流）、[`./REFERENCE.md`](./REFERENCE.md)（字段参考）。**
+**CRITICAL — 本 Skill 全部只读，不会修改任何数据。**
+**CRITICAL — GitLink 资源只能用 `gitlink-cli` 操作，禁止用 `gh`/`glab`。**
+
+本文档列出使用科研主体画像 Skill 时的常见问题，按「症状 / 原因 / 解决」三段式给出。
+
+## 速查表
+
+| # | 症状 | 根因 | 一句话解决 |
+|---|------|------|-----------|
+| 1 | `unknown command "profile"` | `feat/profile-shortcuts` 分支未合入 | 用 Raw API 降级，或等 profile 命令合入 |
+| 2 | 某维度返回空（`categories: []`、活动全 0） | 用户数据稀疏或新注册 | 标注"数据稀疏"，不臆造 |
+| 3 | Owner 数 / 学科数量异常巨大 | 镜像聚合账号导致虚高 | 结合 `user +info.mirror_projects_count` 标注 |
+| 4 | `404` 用户不存在 | login 拼写错误或账号已注销 | 用 `search +users` 确认 login |
+| 5 | 团队画像逐人调用超时 | 成员过多串行请求触发限流 | 控制人数 ≤10，串行逐人，间隔 5 秒 |
+| 6 | `dataset +list` 命令不存在 | `feat/dataset-shortcuts` 分支未合入 | 该辅助命令非必须，可跳过 |
+| 7 | `--start-time/--end-time` 无效 | API 不支持时间窗口过滤 | 忽略该参数，使用平台默认区间 |
+
+---
+
+## 1. `profile` 命令不存在
+
+**症状**：运行 `gitlink-cli profile +ability --user xxx` 报 `unknown command "profile" for "gitlink-cli"`。
+
+**原因**：`profile` 快捷命令在 `feat/profile-shortcuts` 分支中实现，尚未合入当前版本。
+
+**解决**：
+
+```bash
+# 方案 A：使用 Raw API 降级（立即可用）
+gitlink-cli api GET /users/<login>/statistics/develop.json
+gitlink-cli api GET /users/<login>/statistics/major.json
+gitlink-cli api GET /users/<login>/statistics/role.json
+gitlink-cli api GET /users/<login>/statistics/activity.json
+gitlink-cli api GET /users/<login>/headmaps.json
+
+# 方案 B：等待 profile-shortcuts PR 合入后再使用
+```
+
+> Raw API 返回字段与 `profile` 命令完全一致，仅调用方式不同。
+
+---
+
+## 2. 某维度返回空数据
+
+**症状**：`+major` 返回 `categories: []`，或 `+activity` 返回的 `commits_count`/`issues_count`/`pull_requests_count` 全为 0。
+
+**原因**：
+- 用户注册后尚未参与项目或提交代码
+- 近一周无任何活动
+- 平台统计接口对该用户无数据
+
+**解决**：
+- 在画像报告中标注"该维度数据稀疏"
+- 不要臆造或补零，保持数据真实性
+- 建议用户查看 `user +info` 的 `created_time` 判断是否为新用户
+
+---
+
+## 3. Owner 数 / 学科数量异常巨大
+
+**症状**：`+role` 返回 `owner.count` 上万，或 `+major` 返回 20+ 个学科方向。
+
+**原因**：该账号为平台管理型账号或持有大量镜像项目，镜像会自动计入 owner 角色和异质学科。
+
+**解决**：
+
+```bash
+# 确认是否为镜像聚合账号
+gitlink-cli user +info --login <login> --format json
+# 关注 mirror_projects_count 字段
+```
+
+- `mirror_projects_count` 远大于 `common_projects_count` → 镜像聚合账号
+- 在画像中标注"含镜像聚合，角色/方向指标虚高"
+- 真实规模应以 `common_projects_count`（原创项目数）为参照
+
+---
+
+## 4. 404 用户不存在
+
+**症状**：`profile +ability --user xxx` 返回 404。
+
+**原因**：
+- login 拼写错误（区分大小写）
+- 账号已注销
+- 给了昵称而非 login
+
+**解决**：
+
+```bash
+# 通过搜索确认 login
+gitlink-cli search +users -k "<姓名或关键词>" --format json
+
+# 或直接读取用户资料验证
+gitlink-cli user +info --login <login> --format json
+```
+
+> `profile` 命令的 `--user` 必须是 **login**（用户标识），不是昵称。
+
+---
+
+## 5. 团队画像逐人调用超时
+
+**症状**：对 10+ 人团队逐人采集时，中途出现网络超时或 TLS 错误。
+
+**原因**：串行逐人调用 5 个 API，总请求数 = 人数 × 5，并发或高频可能触发平台限流。
+
+**解决**：
+- 优先核心成员（≤10 人）
+- 串行逐人调用，避免并发
+- 每人之间间隔约 5 秒
+- 对失败的用户标注"数据获取失败"，跳过继续
+- 最少可只调用 `+ability` 和 `+major`，控制调用量
+
+---
+
+## 6. `dataset +list` 命令不存在
+
+**症状**：REFERENCE.md 中引用了 `gitlink-cli dataset +list`，但 CLI 报 `unknown command "dataset"`。
+
+**原因**：`dataset` 快捷命令在 `feat/dataset-shortcuts` 分支中实现，尚未合入。
+
+**解决**：`dataset +list` 仅用于查询科研数据集的论文/许可证等元数据，**非画像必需**。可跳过或使用 Raw API 降级：
+
+```bash
+gitlink-cli api GET /v1/project_datasets.json?ids=<projectId>
+```
+
+---
+
+## 7. `--start-time/--end-time` 参数无效
+
+**症状**：传了 `--start-time` / `--end-time`，但返回数据与不传时相同。
+
+**原因**：GitLink 平台 `/statistics/*` 接口当前可能忽略 `start_time`/`end_time` 查询参数，或仅对部分用户有数据。
+
+**解决**：
+- 这是平台侧限制，非 CLI 问题
+- 忽略时间窗口参数，使用平台默认统计区间
+- 如需特定时间段数据，可在画像报告中手动标注"数据为平台全量统计，非限定区间"
+
+---
+
+## 调试技巧
+
+### 启用调试输出
+
+```bash
+gitlink-cli profile +ability --user <login> --debug
+```
+
+### 验证 API 连通性
+
+```bash
+# 最简单的验证（不需要 profile 命令）
+gitlink-cli api GET /users/<login>/statistics/develop.json
+
+# 验证用户是否存在
+gitlink-cli user +info --login <login>
+```
+
+### 检查认证状态
+
+```bash
+gitlink-cli auth status
+```
--- a/skills/gitlink-research-profile/examples/agent-conversation.md
+++ b/skills/gitlink-research-profile/examples/agent-conversation.md
@ -0,0 +1,62 @@
+# 示例：在 AI Agent 中使用 gitlink-research-profile
+
+下面是一段在 Claude Code 中调用本 Skill 的真实交互示意（命令均为只读）。
+
+---
+
+## 场景 A：单个科研主体画像
+
+**用户：** 帮我看看 GitLink 上 yystopf 这个人的科研画像。
+
+**Agent：**（读取 `gitlink-research-profile/SKILL.md` 与 `gitlink-shared/SKILL.md`）
+先确认用户资料，再采集五类画像数据：
+
+```bash
+gitlink-cli user +info --login yystopf --format json
+gitlink-cli profile +ability      --user yystopf --format json
+gitlink-cli profile +major        --user yystopf --format json
+gitlink-cli profile +role         --user yystopf --format json
+gitlink-cli profile +activity     --user yystopf --format json
+gitlink-cli profile +contribution --user yystopf --format json
+```
+
+**Agent（产出）：** 生成《科研主体画像：何慧（@yystopf）》报告——
+能力雷达（贡献/经验/活跃均达卓越）、主力语言 Go/Java、并**识别出该账号含 11453 个镜像项目**，
+据此标注其学科（22 个）与角色（Owner 2 万）为镜像虚高、给出修正解读。
+完整样例见 [`researcher-profile-report.md`](researcher-profile-report.md)。
+
+---
+
+## 场景 B：跨学科协作匹配
+
+**用户：** 我在做"联邦学习 + 医疗影像"的课题，想在 GitLink 上找能补强的协作者。
+
+**Agent：** 先按方向找候选，再对候选取画像并按"学科互补 + 能力互补"排序：
+
+```bash
+# 1) 候选发现（多关键词）
+gitlink-cli search +users -k "联邦学习" --format json
+gitlink-cli search +users -k "federated" --format json
+gitlink-cli search +users -k "医疗影像" --format json
+
+# 2) 对每个候选取学科与能力（示例一位候选）
+gitlink-cli profile +major   --user <candidate> --format json
+gitlink-cli profile +ability --user <candidate> --format json
+```
+
+**Agent（产出）：** 输出协作匹配表——
+
+| 候选 | 匹配度 | 学科互补 | 能力互补 | 推荐理由 |
+|------|--------|----------|----------|----------|
+| @alice | 高 | 覆盖"生物医药健康"空白 | 经验 88 补强 | 医疗方向 + 高经验，契合影像子课题 |
+| @bob | 中 | 覆盖"人工智能/大数据" | 语言 85（Python） | 联邦学习实现栈匹配 |
+
+并说明：候选的学科 `categories` 覆盖了课题缺口、能力维度补强了团队短板。
+
+---
+
+## 要点
+
+- 全程只读，不修改任何数据，无需额外确认。
+- 命令均使用 `--format json` 以便 Agent 解析。
+- 对镜像/管理员账号，Agent 会结合 `user +info.mirror_projects_count` 自动标注"指标虚高"，避免误读。
--- a/skills/gitlink-research-profile/examples/researcher-profile-report.md
+++ b/skills/gitlink-research-profile/examples/researcher-profile-report.md
@ -0,0 +1,74 @@
+# 🔬 科研主体画像：何慧（@yystopf）
+
+> 生成时间：2026-06-14 ｜ 数据来源：GitLink 平台统计接口（`gitlink-cli profile`）
+> 机构：国防科技大学 ｜ 地区：北京 ｜ 注册：2020-11-02
+>
+> 本报告由 `gitlink-research-profile` Skill 基于真实接口数据生成，用于演示输出形态。
+
+## 一、综合摘要
+
+该主体是平台资深贡献者，**贡献度（97）与项目经验（97）接近平台头部**，活跃度高（94）。
+主力语言为 **Go / Java / 前端栈（HTML/JS）**，技术面广。⚠️ 该账号为平台管理型账号，
+持有大量镜像项目（11453 个镜像），导致"角色分布"与"学科领域"显著虚高，下文已据此修正解读。
+
+## 二、开发能力雷达（0–100）
+
+| 维度 | 用户 | 平台基线 | 等级 |
+|------|------|----------|------|
+| 影响力 influence | 79 | 99 | 优秀 |
+| 贡献度 contribution | 97 | 99 | 卓越 |
+| 活跃度 activity | 94 | 99 | 卓越 |
+| 项目经验 experience | 97 | 99 | 卓越 |
+| 语言能力 language | 90 | 98 | 卓越 |
+
+> 平台基线接近满分（头部参照）。该主体除影响力（79，优秀）外其余四维均达"卓越"，
+> 距平台头部仅一步之遥。
+
+## 三、学科领域
+
+平台共标注 **22** 个方向，主要包括：**人工智能、大数据、操作系统、云计算和大数据、
+数据库、物联网、Web 应用开发、DevOps/运维**，并延伸至 **生物医药健康、天文地球物理、
+大气海洋环境、新能源新材料、工业设计制造** 等交叉领域。
+
+> ⚠️ **方向聚焦度判断**：标签多达 22 个且横跨多个不相关学科，结合 `mirror_projects_count=11453`
+> 可判定为**镜像聚合导致的方向虚泛**，并非个人真实研究全覆盖。建议结合其 180 个原创项目
+> （`common_projects_count`）进一步收敛真实方向。
+
+## 四、角色定位
+
+参与项目 **20826** 个 — Owner 20719（99%）/ Manager 86 / Developer 20 / Reporter 1。
+
+> ⚠️ Owner 数高达 2 万，主要由镜像项目计入，**不代表其主导了 2 万个科研项目**。
+> 真实主导规模应参考原创项目数（180）。角色画像：平台级维护者 + 原创项目发起人。
+
+## 五、语言技术栈（前 5）
+
+| 语言 | 占比 | 能力分 |
+|------|------|--------|
+| Go | 20% | 87 |
+| Java | 13% | 83 |
+| HTML | 11% | 81 |
+| JavaScript | 9% | 80 |
+| Python | 9% | 80 |
+
+> 后端以 Go/Java 为主、能力分最高（Go 87）；兼具前端（HTML/JS）与脚本（Shell 80）能力，
+> 属**全栈型**技术结构。
+
+## 六、活跃节奏
+
+- 近一周（2026-06-07 ~ 06-14）：提交 **8**、疑修 **1**、合并请求 **0**。
+- 年度贡献总量：**737**，活跃天数 134 天；活跃峰值日：**2025-06-16（80 次贡献）**。
+
+> 近一周以代码提交为主、协作型动作（PR）较少；年度看呈持续活跃、存在阶段性高峰。
+
+## 七、画像结论与建议
+
+- **定位**：国防科技大学，平台资深维护者 + 全栈研发，能力结构均衡偏强（贡献/经验/活跃卓越）。
+- **真实方向**：需用 180 个原创项目收敛——镜像导致的学科/角色虚高已在上文修正。
+- **协作建议**：适合作为**后端（Go/Java）与平台工程**方向的核心；若组建交叉学科课题组，
+  其影响力（79）可进一步通过对外协作/发版（PR 偏少）提升。
+
+---
+
+*数据通过 `gitlink-cli profile +ability/+major/+role/+activity/+contribution` 与 `user +info`
+实时获取（only-read）。镜像聚合导致的指标虚高已按 Skill 规则标注修正。*