Gitlink
/
gitlink-cli
0
0
Fork 49
Code Issues Pull Requests 11 Packages Projects Releases 10 Wiki Activity

Compare commits

base: Gitlink:v0.1.13
Branches Tags
Gitlink:master
Gitlink:chore/add-contributors-luwanzhou-whale
Gitlink:fix/pr-review-journal-sync
Gitlink:test/slash-1778992192
Gitlink:main
Gitlink:test/branch-skill-1778991125
Gitlink:test/unprotect-1778991372
Gitlink:v0.2.0
Gitlink:v0.1.18
Gitlink:v0.1.17
Gitlink:v0.1.14
Gitlink:v0.1.13
Gitlink:v0.1.12
Gitlink:v0.1.11
Gitlink:v0.1.10
Gitlink:v0.1.9
Gitlink:v0.1.8
Gitlink:v0.1.0-skill-test
Gitlink:v0.0.1-test-del
...
compare: Gitlink:master
Branches Tags
Gitlink:master
Gitlink:chore/add-contributors-luwanzhou-whale
Gitlink:fix/pr-review-journal-sync
Gitlink:test/slash-1778992192
Gitlink:main
Gitlink:test/branch-skill-1778991125
Gitlink:test/unprotect-1778991372
Gitlink:v0.2.0
Gitlink:v0.1.18
Gitlink:v0.1.17
Gitlink:v0.1.14
Gitlink:v0.1.13
Gitlink:v0.1.12
Gitlink:v0.1.11
Gitlink:v0.1.10
Gitlink:v0.1.9
Gitlink:v0.1.8
Gitlink:v0.1.0-skill-test
Gitlink:v0.0.1-test-del

No commits in common. "v0.1.13" and "master" have entirely different histories.
v0.1.13 ... master

1281 changed files with 173605 additions and 2993 deletions
Show Stats Expand all files Collapse all files

41
.devops/ci.yml Normal file
View File

@ -0,0 +1,41 @@
version: 2
name: gitlink_cli_ci
description: "gitlink-cli 代码提交时自动执行 CI 检查（构建、测试、格式化）"
trigger:
webhook: gitlink@1.0.0
event:
- ref: push
ruleset-operator: AND
global:
concurrent: 1
workflow:
- ref: start
name: 开始
task: start
- ref: git_clone_0
name: 拉取代码
task: git_clone@1.2.9
input:
remote_url: '"https://gitlink.org.cn/jiangtx/gitlink-cli.git"'
ref: '"refs/heads/wyx_branch"'
commit_id: '""'
depth: 1
needs:
- start
- ref: ssh_cmd_0
name: CI 检查
task: ssh_cmd@1.1.1
input:
ssh_pass: ((gitlink_cli_ci.ssh_pass))
ssh_ip: '"121.41.212.97"'
ssh_port: '"22"'
ssh_user: '"root"'
ssh_cmd: >-
"cd /root && rm -rf gitlink-cli && git clone --depth=1 -b wyx_branch https://gitlink.org.cn/jiangtx/gitlink-cli.git && cd gitlink-cli && export PATH=$PATH:/usr/local/go/bin && export GOPROXY=https://goproxy.cn,direct && go version && go build ./... && go vet ./... && go test -race ./... && output=$(gofmt -s -l .) && if [ -n \"$output\" ]; then echo '格式化检查失败:' && echo \"$output\" && exit 1; fi && echo '所有 CI 检查通过'"
needs:
- git_clone_0
- ref: end
name: 结束
task: end
needs:
- ssh_cmd_0

42
.devops/自动构建部署.yml Normal file
View File

@ -0,0 +1,42 @@
version: 2
name: 自动构建部署
description: "代码提交自动触发 - 增量拉取 + Docker镜像构建与部署"
global:
concurrent: 1
trigger:
webhook: gitlink@1.0.0
event:
- ref: push
ruleset-operator: AND
workflow:
- ref: start
name: 开始
task: start
- ref: ssh_cmd_0
name: ssh增量拉取并部署
task: ssh_cmd@1.1.1
input:
ssh_pass: ((deploy_server.password))
ssh_ip: '"121.41.222.73"'
ssh_port: '"22"'
ssh_user: '"root"'
ssh_cmd: '"if [ -d /root/gitlink-cli/.git ]; then cd /root/gitlink-cli && git fetch origin && git checkout master && git reset --hard origin/master; else rm -rf /root/gitlink-cli && git clone https://gitlink.org.cn/whale_hihihi/gitlink-cli.git /root/gitlink-cli && cd /root/gitlink-cli && git checkout master; fi && docker stop gitlink-cli 2>/dev/null; docker rm gitlink-cli 2>/dev/null; docker rmi gitlink-cli:latest 2>/dev/null; docker build --no-cache -t gitlink-cli:latest . && docker run -d --name gitlink-cli -p 8080:8080 $([ -f /root/.gitlink-env ] && echo --env-file /root/.gitlink-env) gitlink-cli:latest && echo Deploy success"'
needs:
- start
- ref: ssh_cmd_1
name: 构建并部署demo网页(8000)
task: ssh_cmd@1.1.1
input:
ssh_pass: ((deploy_server.password))
ssh_ip: '"121.41.222.73"'
ssh_port: '"22"'
ssh_user: '"root"'
ssh_cmd: '"cd /root/gitlink-cli && docker stop gitlink-cli-demo 2>/dev/null; docker rm gitlink-cli-demo 2>/dev/null; docker rmi gitlink-cli-demo:latest 2>/dev/null; (docker build --no-cache -f demo/Dockerfile -t gitlink-cli-demo:latest . && docker run -d --name gitlink-cli-demo -p 8000:8000 --restart unless-stopped gitlink-cli-demo:latest && echo Demo deploy success at http://121.41.222.73:8000) || echo Demo deploy FAILED non-blocking, main :8080 unaffected"'
needs:
- ssh_cmd_0
- ref: end
name: 结束
task: end
needs:
- ssh_cmd_0
- ssh_cmd_1

42
.devops/自动部署.yml Normal file
View File

@ -0,0 +1,42 @@
version: 2
name: 自动部署
description: ""
global:
concurrent: 1
trigger:
webhook: gitlink@1.0.0
event:
- ref: push
ruleset-operator: AND
workflow:
- ref: start
name: 开始
task: start
- ref: git_clone_0
name: git clone
task: git_clone@1.2.9
input:
username: ((gitlink_cli.ylly_git_user))
password: ((gitlink_cli.ylly_git_pass))
remote_url: '"https://gitlink.org.cn/ylly/gitlink-cli.git"'
ref: '"refs/heads/master"'
commit_id: '""'
depth: 1
needs:
- start
- ref: ssh_cmd_0
name: ssh执行命令
task: ssh_cmd@1.1.1
input:
ssh_ip: '"8.136.61.14"'
ssh_port: '"22"'
ssh_user: '"root"'
ssh_private_key: ((gitlink_cli.ecs_ssh_key))
ssh_cmd: '"cd /opt/gitlink-cli && git pull && go build -o /usr/local/bin/gitlink-cli . && gitlink-cli version"'
needs:
- git_clone_0
- ref: end
name: 结束
task: end
needs:
- ssh_cmd_0

11
.dockerignore Normal file
View File

@ -0,0 +1,11 @@
.git
.devops
.github
node_modules
dist
doc
npm
*.md
*.exe
.gitignore
.golangci.yml

2
.gitattributes vendored Normal file
View File

@ -0,0 +1,2 @@
.gitattributes text eol=lf
internal/i18n/locales/*.json text eol=lf

35
.gitea/workflows/ci.yml Normal file
View File

@ -0,0 +1,35 @@
name: CI
on:
push:
branches: [master]
pull_request:
branches: [master]
jobs:
check:
name: Build, Lint, Test
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.26.1'
- name: Build
run: go build ./...
- name: Validate i18n and skill metadata
run: |
go run ./internal/i18n/cmd/check
go run ./internal/skillmeta/cmd/check
- name: Lint
run: make lint
- name: Test
run: make test
- name: Check formatting
run: make fmt

26
.github/workflows/ci.yml vendored Normal file
View File

@ -0,0 +1,26 @@
name: CI
on:
push:
branches: [master, main]
pull_request:
branches: [master, main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: '1.22'
- name: Vet
run: go vet ./...
- name: Test
run: go test -v -race ./...
- name: Build
run: go build -v .

95
.github/workflows/release.yml vendored Normal file
View File

@ -0,0 +1,95 @@
name: Release
on:
push:
tags:
- 'v*'
permissions:
contents: write
jobs:
release:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- uses: actions/setup-node@v4
with:
node-version: '20'
registry-url: 'https://registry.npmjs.org'
- name: Build binaries
run: |
mkdir -p dist
VERSION=${GITHUB_REF#refs/tags/v}
MODULE="github.com/gitlink-org/gitlink-cli"
LDFLAGS="-s -w -X ${MODULE}/cmd.Version=${VERSION}"
for pair in \
"darwin amd64" \
"darwin arm64" \
"linux amd64" \
"linux arm64" \
"windows amd64" \
"windows arm64"; do
GOOS=$(echo "$pair" | cut -d' ' -f1)
GOARCH=$(echo "$pair" | cut -d' ' -f2)
OUT="gitlink-cli"
if [ "$GOOS" = "windows" ]; then
OUT="gitlink-cli.exe"
fi
echo "Building ${GOOS}-${GOARCH}..."
BUILD_DIR="dist/gitlink-cli_${VERSION}_${GOOS}_${GOARCH}"
mkdir -p "$BUILD_DIR"
CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH go build -ldflags "$LDFLAGS" -o "$BUILD_DIR/$OUT" .
if [ "$GOOS" = "windows" ]; then
(cd "$BUILD_DIR" && zip -q "../gitlink-cli_${VERSION}_${GOOS}_${GOARCH}.zip" "$OUT")
else
tar -czf "dist/gitlink-cli_${VERSION}_${GOOS}_${GOARCH}.tar.gz" -C "$BUILD_DIR" "$OUT"
fi
rm -rf "$BUILD_DIR"
done
ls -lh dist
- name: Create Release
uses: softprops/action-gh-release@v2
with:
files: |
dist/*.tar.gz
dist/*.zip
generate_release_notes: true
- name: Build npm package
run: |
VERSION=${GITHUB_REF#refs/tags/v}
export VERSION
rm -rf npm-pkg
mkdir -p npm-pkg
cp -R npm/. npm-pkg/
cp README.md npm-pkg/README.md
rm -rf npm-pkg/skills
cp -R skills npm-pkg/skills
node <<'NODE'
const fs = require('fs');
const pkgPath = 'npm-pkg/package.json';
const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
pkg.version = process.env.VERSION;
fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
NODE
chmod +x npm-pkg/bin/cli.js
chmod +x npm-pkg/bin/install-skills.js
cd npm-pkg
npm publish --access public
env:
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

39
.github/workflows/test.yml vendored Normal file
View File

@ -0,0 +1,39 @@
name: Test
on:
pull_request:
push:
branches:
- main
- master
permissions:
contents: read
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- name: Validate i18n messages
run: go run ./internal/i18n/cmd/check
- name: Scan i18n key references
run: go run ./internal/i18n/cmd/check --scan-code
- name: Test Feishu shortcuts
run: go test ./shortcuts/feishu
- name: Test workflow shortcuts
run: go test ./shortcuts/workflow
- name: Run Go tests
run: go test ./...
- name: Vet
run: go vet ./...

29
.gitignore vendored
View File

@ -1,22 +1,9 @@
# Binary
gitlink-cli
# IDE
.idea/
.vscode/
*.swp
*.swo
# OS
.DS_Store
Thumbs.db
# Go
vendor/
# npm packaging
npm/bin/gitlink-cli
npm/*.tgz
npm/README.md
npm/skills/
dist/
gitlink-cli.exe
/gitlink-cli
.local/*
!.local/
!.local/feishu-gitlink.env.example.ps1
*.local.ps1
*.secret.*
reports/feishu-real-smoke-terminal.log

24
.golangci.yml Normal file
View File

@ -0,0 +1,24 @@
run:
timeout: 5m
go: '1.22'
linters:
enable:
- errcheck
- govet
- revive
- unused
- gosimple
- ineffassign
- typecheck
linters-settings:
revive:
rules:
- name: unused-parameter
severity: warning
issues:
exclude-use-default: false
max-issues-per-linter: 50
max-same-issues: 3

31
.local/feishu-gitlink.env.example.ps1 Normal file
View File

@ -0,0 +1,31 @@
# Stable Feishu webhook
$env:FEISHU_WEBHOOK_URL=""
$env:FEISHU_WEBHOOK_SECRET=""
# Feishu Open Platform
$env:FEISHU_APP_ID=""
$env:FEISHU_APP_SECRET=""
# Feishu DocX / Wiki
$env:FEISHU_WIKI_URL=""
$env:FEISHU_WIKI_NODE_TOKEN=""
$env:FEISHU_FOLDER_TOKEN=""
$env:FEISHU_DOCUMENT_ID=""
# Feishu Base / Bitable
$env:FEISHU_BASE_APP_TOKEN=""
$env:FEISHU_REPORT_TABLE_ID=""
$env:FEISHU_ISSUE_TABLE_ID=""
$env:FEISHU_PR_TABLE_ID=""
$env:FEISHU_CONTRIBUTOR_TABLE_ID=""
$env:FEISHU_TASK_TABLE_ID=""
# Feishu Task
$env:FEISHU_TASK_PROJECT_ID=""
$env:FEISHU_TASK_SECTION_ID=""
# GitLink real test input
$env:GITLINK_OWNER=""
$env:GITLINK_REPO=""
$env:GITLINK_TEST_PR_IDS=""
$env:GITLINK_TOKEN=""

41
Dockerfile Normal file
View File

@ -0,0 +1,41 @@
# ============================================================
# 多阶段构建：gitlink-cli 子赛题四网页终端
# ============================================================
# 阶段1 builder —— Go 静态编译
# ============================================================
FROM golang:1.26-alpine AS builder
ENV GOPROXY=https://goproxy.cn,direct
WORKDIR /src
# 先拷依赖清单，利用 Docker 层缓存
COPY go.mod go.sum ./
RUN go mod download
COPY . .
# modernc.org/sqlite 是 pure-Go，CGO_ENABLED=0 即可编译纯静态二进制
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /out/gitlink-cli .
# ============================================================
# 阶段2 runtime —— Python + Go 二进制
# ============================================================
FROM python:3.12-slim
# Go CLI 放入 PATH
COPY --from=builder /out/gitlink-cli /usr/local/bin/gitlink-cli
# 科研算法层：先拷 requirements.txt 安装依赖（利用层缓存），再拷源码
# pip 先升级自身，再用清华镜像（带 retry + trusted-host 防证书/网络抖动）
COPY scripts/research/requirements.txt /app/scripts/research/requirements.txt
RUN pip install --no-cache-dir --upgrade pip && \
pip install --no-cache-dir --default-timeout=300 --retries 5 \
-i https://pypi.tuna.tsinghua.edu.cn/simple \
--trusted-host pypi.tuna.tsinghua.edu.cn \
-r /app/scripts/research/requirements.txt
COPY scripts/research/ /app/scripts/research/
WORKDIR /app
# 子赛题四网页终端 HTTP 服务
EXPOSE 8080
ENTRYPOINT ["gitlink-cli", "server", "--port", "8080", "--research-dir", "/app/scripts/research", "--work-dir", "/app/research-output"]

199
LICENSE
View File

@ -1,190 +1,65 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
Mulan Permissive Software License，Version 2
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
Mulan Permissive Software License，Version 2 (Mulan PSL v2)
1. Definitions.
January 2020 http://license.coscl.org.cn/MulanPSL2
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
Your reproduction, use, modification and distribution of the Software shall be subject to Mulan PSL v2 (this License) with the following terms and conditions:
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
0. Definition
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
Software means the program and related documents which are licensed under this License and comprise all Contribution(s).
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
Contribution means the copyrightable work licensed by a particular Contributor under this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
Contributor means the Individual or Legal Entity who licenses its copyrightable work under this License.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
Legal Entity means the entity making a Contribution and all its Affiliates.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
Affiliates means entities that control, are controlled by, or are under common control with the acting entity under this License, ‘control’ means direct or indirect ownership of at least fifty percent (50%) of the voting power, capital or other securities of controlled or commonly controlled entity.
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
1. Grant of Copyright License
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to the Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable copyright license to reproduce, use, modify, or distribute its Contribution, with modification or not.
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by the Licensor and
subsequently incorporated within the Work.
2. Grant of Patent License
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
Subject to the terms and conditions of this License, each Contributor hereby grants to you a perpetual, worldwide, royalty-free, non-exclusive, irrevocable (except for revocation under this Section) patent license to make, have made, use, offer for sale, sell, import or otherwise transfer its Contribution, where such patent license is only limited to the patent claims owned or controlled by such Contributor now or in future which will be necessarily infringed by its Contribution alone, or by combination of the Contribution with the Software to which the Contribution was contributed. The patent license shall not apply to any modification of the Contribution, and any other combination which includes the Contribution. If you or your Affiliates directly or indirectly institute patent litigation (including a cross claim or counterclaim in a litigation) or other patent enforcement activities against any individual or entity by alleging that the Software or any Contribution in it infringes patents, then any patent license granted to you under this License for the Software shall terminate as of the date such litigation or activity is filed or taken.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
3. No Trademark License
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
No trademark license is granted to use the trade names, trademarks, service marks, or product names of Contributor, except as required to fulfill notice requirements in section 4.
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
4. Distribution Restriction
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
You may distribute the Software in any medium with or without modification, whether in source or executable forms, provided that you provide recipients with a copy of this License and retain copyright, patent, trademark and disclaimer statements in the Software.
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
5. Disclaimer of Warranty and Limitation of Liability
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding any notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
THE SOFTWARE AND CONTRIBUTION IN IT ARE PROVIDED WITHOUT WARRANTIES OF ANY KIND, EITHER EXPRESS OR IMPLIED. IN NO EVENT SHALL ANY CONTRIBUTOR OR COPYRIGHT HOLDER BE LIABLE TO YOU FOR ANY DAMAGES, INCLUDING, BUT NOT LIMITED TO ANY DIRECT, OR INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING FROM YOUR USE OR INABILITY TO USE THE SOFTWARE OR THE CONTRIBUTION IN IT, NO MATTER HOW IT’S CAUSED OR BASED ON WHICH LEGAL THEORY, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
6. Language
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
THIS LICENSE IS WRITTEN IN BOTH CHINESE AND ENGLISH, AND THE CHINESE VERSION AND ENGLISH VERSION SHALL HAVE THE SAME LEGAL EFFECT. IN THE CASE OF DIVERGENCE BETWEEN THE CHINESE AND ENGLISH VERSIONS, THE CHINESE VERSION SHALL PREVAIL.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
END OF THE TERMS AND CONDITIONS
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
How to Apply the Mulan Permissive Software License，Version 2 (Mulan PSL v2) to Your Software
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
To apply the Mulan PSL v2 to your work, for easy identification by recipients, you are suggested to complete following three steps:
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
Fill in the blanks in following statement, including insert your software name, the year of the first publication of your software, and your name identified as the copyright owner;
END OF TERMS AND CONDITIONS
Create a file named "LICENSE" which contains the whole context of this License in the first directory of your software package;
Copyright 2026 gitlink-cli contributors
Attach the statement to the appropriate annotated syntax at the beginning of each source file.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
Copyright (c) [Year] [name of copyright holder]
[Software Name] is licensed under Mulan PSL v2.
You can use this software according to the terms and conditions of the Mulan PSL v2.
You may obtain a copy of Mulan PSL v2 at:
http://license.coscl.org.cn/MulanPSL2
THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT,
MERCHANTABILITY OR FIT FOR A PARTICULAR PURPOSE.
See the Mulan PSL v2 for more details.

16
Makefile
View File

@ -3,7 +3,7 @@ BINARY := gitlink-cli
VERSION ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
LDFLAGS := -s -w -X '$(MODULE)/cmd.Version=$(VERSION)'
.PHONY: build install clean test
.PHONY: build install clean test test-cover lint ci
build:
go build -ldflags "$(LDFLAGS)" -o $(BINARY) .
@ -15,4 +15,16 @@ clean:
rm -f $(BINARY)
test:
go test ./...
go test -v -race ./...
test-cover:
go test -v -race -coverprofile=coverage.out ./...
go tool cover -func=coverage.out
lint:
golangci-lint run ./...
ci: lint test
vet:
go vet ./...

729
README.md
View File

@ -1,49 +1,124 @@
# gitlink-cli
[![GitLink](https://img.shields.io/badge/GitLink-Gitlink%2Fgitlink--cli-green)](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
[![Go Version](https://img.shields.io/badge/Go-1.21%2B-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/License-MulanPSL--2.0-blue.svg)](https://license.coscl.org.cn/MulanPSL2)
[![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org)
[![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/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 11 AI Agent [Skills](./skills/).
The official [GitLink](https://www.gitlink.org.cn) CLI tool — built for humans and AI Agents. Supports **macOS, Linux, and Windows**. Covers repository management, wiki pages, issue tracking, pull requests, webhooks, member collaboration, CI/CD, and AI-powered workflows, with 40+ commands and AI Agent [Skills](./skills/).
[Install](#installation--quick-start) · [AI Agent Skills](#ai-agent-skills) · [Auth](#首次使用) · [Commands](#使用示例) · [Contributing](#相关项目)
**[中文文档](./README.zh-CN.md)**
[Install](#installation--quick-start) · [AI Agent Skills](#ai-agent-skills) · [Auth](#configure--use) · [Commands](#usage-examples) · [Contributing](#related-projects)
## Contributors
<div style="display: flex; gap: 16px; flex-wrap: wrap; align-items: flex-start;">
<div align="center">
<a href="https://www.gitlink.org.cn/wangyue111" title="wangyue111"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/W/43_254_70/120.png" width="40" height="40" alt="wangyue111" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/wangyue111">wangyue111</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/wbtiger" title="tigerwang"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/T/14_168_39/120.png" width="40" height="40" alt="wbtiger" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/wbtiger">wbtiger</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/Mengz" title="Mengz"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/M/166_152_185/120.png" width="40" height="40" alt="Mengz" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/Mengz">Mengz</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/yangsai" title="杨赛"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/Y/94_150_149/120.png" width="40" height="40" alt="yangsai" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/yangsai">yangsai</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/mengcheng" title="camelliamc"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/M/206_114_54/120.png" width="40" height="40" alt="mengcheng" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/mengcheng">mengcheng</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/muel" title="赵奕程"><img src="https://www.gitlink.org.cn/images/avatars/User/149182?t=1779603476" width="40" height="40" alt="muel" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/muel">muel</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/Leo77" title="Leo77"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/L/173_120_149/120.png" width="40" height="40" alt="Leo77" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/Leo77">Leo77</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/yingjie" title="yingjie"><img src="https://www.gitlink.org.cn/images/avatars/User/145288?t=1765791899" width="40" height="40" alt="yingjie" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/yingjie">yingjie</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/topshare" title="Kevin Zhang"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/K/65_152_142/120.png" width="40" height="40" alt="topshare" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/topshare">topshare</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/dtwdtw" title="dtwdtw"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/D/53_166_51/120.png" width="40" height="40" alt="dtwdtw" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/dtwdtw">dtwdtw</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/recorder" title="recorder"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/R/141_201_87/120.png" width="40" height="40" alt="recorder" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/recorder">recorder</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/puygob236" title="Jiachen Li"><img src="https://www.gitlink.org.cn/images/avatars/User/149183?t=1778815174" width="40" height="40" alt="puygob236" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/puygob236">puygob236</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/co63oc" title="co63oc"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/C/205_201_141/120.png" width="40" height="40" alt="co63oc" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/co63oc">co63oc</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/lindiwen23" title="lindiwen23"><img src="https://www.gitlink.org.cn/images/avatars/User/141609?t=1748270628" width="40" height="40" alt="lindiwen23" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/lindiwen23">lindiwen23</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/ohanabi" title="ohanabi"><img src="https://www.gitlink.org.cn/images/avatars/User/148166?t=1778230283" width="40" height="40" alt="ohanabi" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/ohanabi">ohanabi</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/jiangtx" title="jiangtx"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/J/67_157_94/120.png" width="40" height="40" alt="jiangtx" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/jiangtx">jiangtx</a></sub>
</div>
</div>
## Why gitlink-cli?
- **Agent-Native Design** — 11 structured [Skills](./skills/) out of the box, compatible with Claude Code — Agents can operate GitLink with zero extra setup
- **Wide Coverage** — Repository, Issue, PR, Branch, Release, CI, Org, Search, User — all core domains covered
- **Agent-Native Design** — 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, Wiki, Issue, PR, Webhook, Member, Branch, Release, CI, Pipeline, Org, Search, and User workflows are covered by high-level commands
- **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` in one command
- **Open Source, Zero Barriers** — Apache 2.0 license, ready to use, just `npm install`
- **Up and Running in 3 Minutes** — Interactive login, from install to first API call in just 3 steps
- **Secure & Controllable** — OS-native keychain credential storage, auto git remote context resolution
- **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
- **Three-Layer Architecture** — Shortcuts (human & AI friendly) → Raw API (full coverage) → Config (configuration management)
## Features
| Category | Capabilities |
|----------|-------------|
| 📦 Repo | List, create, fork, delete repositories, view repo info |
| 🐛 Issue | Create, update, close, comment on issues |
| 📦 Repo | List, create, fork, delete repositories, view repo info, insights, and interactions |
| 📚 Wiki | List, view, create, update, and delete wiki pages |
| 🐛 Issue | Create, update, close, batch close, comment on issues |
| 🔖 Label | Create, list, update, delete issue labels |
| 🔀 PR | Create, merge, review pull requests, view changed files |
| 🌿 Branch | Create, delete, protect branches |
| 🏷️ Release | Create, view, delete releases |
| 👥 Member | List, add, remove repository members, change roles, create and accept invite links |
| 🌿 Branch | Create, delete, list, protect, unprotect branches |
| 🏷️ Release | Create, edit, update, view, delete releases |
| 🏢 Org | Manage organizations, members, teams |
| 🔧 CI | View builds, logs, CI/CD operations |
| ⚙️ Pipeline | Run, inspect, enable, disable, delete pipeline workflows and logs |
| 🔔 Webhook | Manage repo webhooks and test deliveries |
| 🔍 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
Before you start, make sure you have:
- Node.js 14+ (`npm`/`npx`) — for npm installation
- Supported platforms: macOS, Linux, Windows (x64/arm64)
- Go 1.21+ — only required for building from source
- Go 1.26+ — only required for building from source
### Quick Start (Human Users)
@ -51,32 +126,26 @@ Before you start, make sure you have:
#### Install
Choose **one** of the following methods:
**Option 1 — From npm (recommended):**
**From npm (recommended):**
```bash
# Install CLI
# One command: installs CLI binary + AI Agent Skills
npm install -g @gitlink-ai/cli
# Install CLI SKILL (required, works on all platforms)
gitlink-cli-install-skills
```
**Option 2 — From source:**
The binary is auto-downloaded for your platform during `postinstall`. No extra steps needed.
Requires Go 1.21+.
**From source:**
Requires Go 1.26+.
```bash
git clone https://www.gitlink.org.cn/Gitlink/gitlink-cli.git
cd gitlink-cli
make install
# Install CLI SKILL (required)
npx skills add ./skills -y -g
```
> **Windows 用户注意：** 请在 PowerShell 或 CMD 中运行 `npm install -g @gitlink-ai/cli`。从源码构建请使用 `go install .` 代替 `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
@ -87,6 +156,7 @@ gitlink-cli config init
# 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)
# 3. Start using
gitlink-cli repo +list
@ -99,11 +169,8 @@ gitlink-cli repo +list
**Step 1 — Install**
```bash
# Install CLI
# One command: CLI binary + all Skills auto-installed
npm install -g @gitlink-ai/cli
# Install CLI SKILL (required, works on all platforms)
gitlink-cli-install-skills
```
**Step 2 — Configure**
@ -114,201 +181,540 @@ gitlink-cli config init
**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
# 创建仓库
gitlink-cli repo +create -n my-project -d "项目描述"
# Read repository README
gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master
# Fork 仓库
# List repository files at root or a directory
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main
# Show language breakdown
gitlink-cli repo +languages --owner Gitlink --repo forgeplus
# List contributors
gitlink-cli repo +contributors --owner Gitlink --repo forgeplus
# Show contributor code-line stats for a branch, tag, or commit
gitlink-cli repo +contributor-stats --owner Gitlink --repo forgeplus --ref master --pass-year 1
# Show repository code stats
gitlink-cli repo +code-stats --owner Gitlink --repo forgeplus --ref master
# List watchers and stargazers in a time range
gitlink-cli repo +watchers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
gitlink-cli repo +stargazers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
# Preview and apply repository interaction actions
gitlink-cli repo +follow --owner Gitlink --repo forgeplus --dry-run
gitlink-cli repo +follow --owner Gitlink --repo forgeplus
gitlink-cli repo +unfollow --owner Gitlink --repo forgeplus --project-id 123
gitlink-cli repo +like --owner Gitlink --repo forgeplus
gitlink-cli repo +unlike --owner Gitlink --repo forgeplus --project-id 123
# 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 管理
### Wiki Management
```bash
# 列出 Issue
# List wiki pages
gitlink-cli wiki +list --owner Gitlink --repo forgeplus
# View a wiki page
gitlink-cli wiki +view --owner Gitlink --repo forgeplus --page Home
# Create a wiki page from inline content
gitlink-cli wiki +create --owner Gitlink --repo forgeplus \
--page Home --title Home --content "Welcome to the project wiki"
# Update a wiki page from a Markdown file
gitlink-cli wiki +update --owner Gitlink --repo forgeplus \
--page Home --file docs/wiki-home.md --message "Update Home"
# Delete a wiki page
gitlink-cli wiki +delete --owner Gitlink --repo forgeplus --page Home
```
### Webhook Management
```bash
# List webhooks
gitlink-cli webhook +list --owner Gitlink --repo forgeplus
# Create a webhook
gitlink-cli webhook +create --owner Gitlink --repo forgeplus \
--url https://example.com/hook --events push,create
# Test a webhook
gitlink-cli webhook +test --owner Gitlink --repo forgeplus --id 68
# View webhook delivery tasks
gitlink-cli webhook +tasks --owner Gitlink --repo forgeplus --id 68
```
### Member Management
```bash
# List repository members
gitlink-cli member +list --owner Gitlink --repo forgeplus
# Add a member
gitlink-cli member +add --owner Gitlink --repo forgeplus --user-id 101
# Preview batch add without changing data
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --user-ids 101,102 --dry-run
# Batch add members from a CSV file
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --from members.csv
# Change a member role
gitlink-cli member +role --owner Gitlink --repo forgeplus --user-id 101 --role Developer
# Create an invite link
gitlink-cli member +invite-link --owner Gitlink --repo forgeplus --role developer --apply true
```
### Issue Management
```bash
# List issues
gitlink-cli issue +list --owner Gitlink --repo forgeplus
# 创建 Issue
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" -b "复现步骤..."
# Create an issue
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" -b "Steps to reproduce..."
# 查看 Issue
# Create an issue with metadata
gitlink-cli issue +create --owner Gitlink --repo forgeplus -t "Bug: Login failed" --priority-id 3 --tag-ids 4,5 --assigner-ids 7
# View an issue
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
# 关闭 Issue
# Update issue metadata
gitlink-cli issue +update --owner Gitlink --repo forgeplus --number 123 --priority-id 4 --branch bugfix/login --due-date 2026-06-15
# Close an issue
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
# 添加评论
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 -b "已修复"
# 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"
# List issue assigners
gitlink-cli issue +assigners --owner Gitlink --repo forgeplus
# List issue authors
gitlink-cli issue +authors --owner Gitlink --repo forgeplus
# List issue priorities
gitlink-cli issue +priorities --owner Gitlink --repo forgeplus
# List issue tags
gitlink-cli issue +tags --owner Gitlink --repo forgeplus --only-name
# List issue statuses
gitlink-cli issue +statuses --owner Gitlink --repo forgeplus
```
### Pull Request
`issue +view`, `issue +update`, `issue +close`, and `issue +comment` prefer
`--number` / `-n` for the issue number shown in the web URL. `--id` / `-i`
is accepted as a compatibility alias for the same web issue number, not the
global database ID.
### Label Management
```bash
# 列出 PR
# List issue labels
gitlink-cli label +list --owner Gitlink --repo forgeplus
# Filter labels by keyword
gitlink-cli label +list --owner Gitlink --repo forgeplus -k bug
# Create a label (color defaults to #1E90FF)
gitlink-cli label +create --owner Gitlink --repo forgeplus -n bug -d "Something is broken" -c "#FF0000"
# Update a label (unspecified fields are preserved)
gitlink-cli label +update --owner Gitlink --repo forgeplus -i 42 -c "#00FF00"
# Delete a label
gitlink-cli label +delete --owner Gitlink --repo forgeplus -i 42
```
### Pull Requests
```bash
# List PRs
gitlink-cli pr +list --owner Gitlink --repo forgeplus
# 创建 PR（同仓库分支）
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: 搜索功能" --head feature/search --base master
# Create a PR (same-repo branch)
gitlink-cli pr +create --owner Gitlink --repo forgeplus -t "feat: Search feature" --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
# 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
# 查看 PR
# View a PR
gitlink-cli pr +view --owner Gitlink --repo forgeplus -i 42
# 合并 PR
# Merge a PR
gitlink-cli pr +merge --owner Gitlink --repo forgeplus -i 42
# 查看 PR 变更文件
# Reopen a closed PR
gitlink-cli pr +reopen --owner Gitlink --repo forgeplus -i 42
# View changed files
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
# List PR patchset versions
gitlink-cli pr +versions --owner Gitlink --repo forgeplus -i 42
# View a patchset version diff
gitlink-cli pr +version-diff --owner Gitlink --repo forgeplus -i 42 --version-id 16040
# List PR reviews
gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42
# Create a PR review (with dry-run preview)
gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run
gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM"
```
### 发布管理
### Branch Management
```bash
# 列出 Release
# 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
# 创建 Release
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..."
# Create a release with release notes and optional assets
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 Stable" -b "Changelog..." --attachment-ids 12,34
# 查看 Release
# View a release
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
# Get edit data and update while preserving unspecified fields
gitlink-cli release +edit --owner Gitlink --repo forgeplus -i <version_id>
gitlink-cli release +update --owner Gitlink --repo forgeplus -i <version_id> -b "Updated changelog" --dry-run
# Preview release deletion before executing it
gitlink-cli release +delete --owner Gitlink --repo forgeplus -i <version_id> --dry-run
```
### 搜索
### 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>
```
### Pipeline Operations
```bash
# List platform pipelines
gitlink-cli pipeline +list --owner-id 123 --page 1 --limit 20
# List repository pipeline runs
gitlink-cli pipeline +runs --owner Gitlink --repo forgeplus --ref master --workflow build.yml
# Start a pipeline workflow, previewing the request first
gitlink-cli pipeline +run --owner Gitlink --repo forgeplus --ref master --workflow build.yml --dry-run
# Inspect pipeline details and logs
gitlink-cli pipeline +view --owner Gitlink --repo forgeplus --id 7
gitlink-cli pipeline +logs --owner Gitlink --repo forgeplus --run-id 99 --id 7 --index 43
gitlink-cli pipeline +results --owner Gitlink --repo forgeplus --run-id 99
# Toggle or delete pipeline workflows, previewing destructive writes first
gitlink-cli pipeline +disable --owner Gitlink --repo forgeplus --id 7 --workflow build.yml --dry-run
gitlink-cli pipeline +delete --owner Gitlink --repo forgeplus --id 7 --dry-run
```
### Search
```bash
# Search repositories
gitlink-cli search +repos -k "machine learning"
# 搜索用户
# Search users
gitlink-cli search +users -k "zhangsan"
```
### Raw API
### Workflow Agent Commands
Shortcuts 未覆盖的接口可通过 Raw API 直接调用：
`workflow` provides rule-based repository analysis for maintainers and AI Agents. It currently supports:
- `workflow +triage`
- `workflow +health`
- `workflow +pr-summary`
- `workflow +repo-report`
`workflow +pr-summary` defaults to `table` when `--format` is omitted.
`workflow +repo-report` defaults to `markdown` when `--format` is omitted.
Examples:
```bash
# GET 请求
# Triage with local parameters
gitlink-cli workflow +triage --title "Install failed on Windows" --body "go install failed with error" --format table
# Triage with JSON output
gitlink-cli workflow +triage --title "Token leaked in logs" --body "The access token appears in command output" --format json
# Triage with Chinese markdown output
gitlink-cli workflow +triage \
--title "安装失败，无法登录" \
--body "运行命令时报错" \
--lang zh-CN \
--format markdown
# Triage from a local JSON file
gitlink-cli workflow +triage --from shortcuts/workflow/testdata/issue_bug.json --format json
# Triage by read-only GitLink fetch
gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open --limit 5 --format table
# Health for a healthy repository
gitlink-cli workflow +health \
--repository Gitlink/gitlink-cli \
--open-issues 3 \
--open-prs 1 \
--has-readme \
--has-license \
--has-contributing \
--agent-readiness-known \
--agent-readiness-score 9 \
--format table
# Health for a risky repository
gitlink-cli workflow +health \
--repository demo/repo \
--open-issues 60 \
--stale-issues 25 \
--open-prs 12 \
--stale-prs 6 \
--recent-activity-known \
--recent-activity-days 120 \
--release-known=false \
--format json
# Health with Chinese markdown output
gitlink-cli workflow +health \
--repository Gitlink/gitlink-cli \
--open-issues 3 \
--open-prs 1 \
--has-readme \
--has-license \
--has-contributing \
--lang zh-CN \
--format markdown
# Health by read-only GitLink fetch
gitlink-cli workflow +health --owner Gitlink --repo gitlink-cli --stale-days 30 --format table
# PR review summary by read-only GitLink fetch
gitlink-cli workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 1 --format markdown
# PR review summary from a local JSON file
gitlink-cli workflow +pr-summary --from shortcuts/workflow/testdata/pr_summary.json --format json
# Repository workflow report by read-only GitLink fetch
gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --format markdown
# Repository workflow report from a local JSON file
gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format json
```
Output formats:
- `json` for scripts and AI Agents
- `table` for terminal review
- `markdown` for Issue comments, PR comments, release notes, and competition write-ups
Safety:
- Current workflow commands use local analysis by default and can also read GitLink data in read-only fetch mode.
- They do not modify remote GitLink data.
- They do not depend on LLM APIs.
- `workflow +pr-summary` does not comment, approve, reject, or merge pull requests.
- `workflow +repo-report` aggregates health, issue triage, and PR review summary signals without remote writes.
### Raw API
For endpoints not covered by shortcuts, use the Raw API directly:
```bash
# GET request
gitlink-cli api GET /users/me
# POST 请求
# POST request
gitlink-cli api POST /Gitlink/forgeplus/issues --body '{"subject":"test","description":"..."}'
# 带查询参数
# POST request with body from a file
gitlink-cli api POST /Gitlink/forgeplus/issues --body-file issue.json
# POST request with body from stdin
Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-stdin
# With query parameters
gitlink-cli api GET /Gitlink/forgeplus/commits --query 'page=1&limit=5'
```
## 全局参数
## Global Parameters
| 参数 | 说明 | 示例 |
|------|------|------|
| `--owner` | 仓库所有者 | `--owner Gitlink` |
| `--repo` | 仓库名称 | `--repo forgeplus` |
| `--format` | 输出格式（json/table/yaml） | `--format json` |
| `--debug` | 启用调试输出 | `--debug` |
| Parameter | Description | Example |
|-----------|-------------|---------|
| `--owner` | Repository owner | `--owner Gitlink` |
| `--repo` | Repository name | `--repo forgeplus` |
| `--format` | Output format (json/table/yaml; workflow also supports markdown) | `--format json` |
| `--debug` | Enable debug output | `--debug` |
**自动上下文解析**：在 git 仓库目录下，`--owner` 和 `--repo` 会自动从 `git remote origin` 解析。
**Automatic context resolution:** When running inside a git repository, `--owner` and `--repo` are automatically resolved from `git remote origin`.
## 分支约定
## Branch Conventions
gitlink-cli 支持 GitHub 和 GitLink 的代码双向同步：
gitlink-cli supports bidirectional code sync between GitHub and GitLink:
| 平台 | 主分支 |
|------|--------|
| Platform | Default Branch |
|----------|---------------|
| GitHub | `main` |
| GitLink | `master` |
**本地 push 到 GitLink**：
**Push to GitLink from local:**
```bash
# 方式 1：使用 git 命令
# Method 1: Use git command directly
git push gitlink main:master
# 方式 2：配置 git remote
# Method 2: Configure 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 平台。
The `skills/` directory contains Agent Skill files for AI-automated GitLink operations.
详见 [skills/README.md](skills/README.md)
See [skills/README.md](skills/README.md) for details.
| Skill | 说明 |
|-------|------|
| `gitlink-shared` | 认证、全局参数、安全规则、API 注意事项 |
| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork 等） |
| `gitlink-issue` | Issue 操作（创建、更新、关闭、评论等） |
| `gitlink-pr` | Pull Request 操作（创建、合并、Review 等） |
| `gitlink-branch` | 分支管理（创建、删除、保护等） |
| `gitlink-release` | 发布管理（创建、查看、删除等） |
| `gitlink-org` | 组织管理（成员、团队等） |
| `gitlink-ci` | CI/CD 操作（构建、日志等） |
| `gitlink-search` | 搜索功能（仓库、用户等） |
| `gitlink-user` | 用户管理（个人信息等） |
| `gitlink-workflow` | AI 自动化工作流（Issue 分类、PR Review、Release Notes 等） |
| Skill | Description |
|-------|-------------|
| `gitlink-shared` | Authentication, global parameters, safety rules, API notes |
| `gitlink-repo` | Repository operations (create, view, delete, fork, insights, etc.) |
| `gitlink-wiki` | Wiki operations (list, view, create, update, delete) |
| `gitlink-issue` | Issue operations (create, update, close, comment, etc.) |
| `gitlink-pr` | Pull request operations (create, merge, review, etc.) |
| `gitlink-member` | Repository member and invite link management |
| `gitlink-branch` | Branch management (create, delete, list, protect, unprotect) |
| `gitlink-release` | Release management (create, edit, update, view, delete, etc.) |
| `gitlink-ci` | CI/CD operations (builds, logs, etc.) |
| `gitlink-pipeline` | Pipeline workflow operations (runs, logs, enable, disable, delete, 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.) |
| `gitlink-health` | Project health analysis (PR/Issue metrics aggregation, health reports) |
## 项目结构
## Project Structure
```
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
├── 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/ # 分支 shortcuts
│ ├── member/ # Repository member shortcuts
│ ├── branch/ # Branch shortcuts
│ ├── release/ # Release shortcuts
│ ├── org/ # 组织 shortcuts
│ ├── org/ # Organization shortcuts
│ ├── ci/ # CI shortcuts
│ ├── search/ # 搜索 shortcuts
│ ├── user/ # 用户 shortcuts
│ └── register.go # 注册入口
│ ├── pipeline/ # Pipeline shortcuts
│ ├── search/ # Search shortcuts
│ ├── user/ # User shortcuts
│ └── register.go # Registration entry point
├── skills/ # AI Agent Skills
│ ├── README.md # Skills 使用指南
│ ├── gitlink-shared/ # 共享规则
│ ├── gitlink-repo/ # 仓库 Skill
│ ├── gitlink-issue/ # Issue Skill
│ ├── gitlink-pr/ # PR Skill
│ ├── 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/ # 设计文档
│ ├── SKILLS_TEST_REPORT_2026-04-02.md
├── doc/ # Design documents
│ ├── Design.md
│ ├── CODE_SYNC_STRATEGY_FINAL.md
│ └── ...
├── main.go
@ -317,56 +723,75 @@ gitlink-cli/
└── README.md
```
## 文档
## Documentation
- [Skills 使用指南](skills/README.md) - AI Agent Skills 详细说明
- [设计文档](doc/design.md) - 架构设计和开发计划
- [测试报告](doc/SKILLS_TEST_REPORT_2026-04-02.md) - 功能测试报告
- [代码同步方案](doc/CODE_SYNC_STRATEGY_FINAL.md) - GitHub ↔ GitLink 同步设计
- [Skills Guide](skills/README.md) — AI Agent Skills detailed documentation
- [Design Document](doc/design.md) — Architecture design and development plan
## 常见问题
## FAQ
### Q: 如何在脚本中使用 gitlink-cli？
### Q: How do I use gitlink-cli in scripts?
A: 使用 `--format json` 获取结构化输出：
Use the `GITLINK_TOKEN` environment variable + `--format json` for structured output:
```bash
export GITLINK_TOKEN="your-private-token"
gitlink-cli repo +list --format json | jq '.data.projects[] | .name'
```
### Q: 如何自动解析 owner/repo？
### Q: How does automatic owner/repo resolution work?
A: 在 git 仓库目录下运行命令，CLI 会自动从 `git remote origin` 解析：
When running inside a git repository, the CLI automatically resolves `--owner` and `--repo` from `git remote origin`:
```bash
cd ~/my-gitlink-project
gitlink-cli issue +list # 自动使用当前仓库
gitlink-cli issue +list # Automatically uses the current repository
```
### Q: Token 过期了怎么办？
### Q: What if my token expires?
A: 重新登录：
Re-authenticate:
```bash
# 用户名密码登录
# Username/password login
gitlink-cli auth login
# 或使用私人令牌（在 GitLink 网页端 个人设置 → 私人令牌 中生成）
# Or use a private token (generate at GitLink web → Settings → Private Tokens)
gitlink-cli auth login --token
```
### Q: Windows 上凭证存储在哪里？
### Q: How do I use gitlink-cli in CI/CD or non-interactive environments (e.g. Trae sandbox)?
A: gitlink-cli 使用 Windows Credential Manager 安全存储 Token。如果 Credential Manager 不可用，会自动降级到文件存储 (`~/.config/gitlink-cli/credentials`)。
Set the `GITLINK_TOKEN` environment variable — no `auth login` needed:
### Q: 如何查看完整的 API 参考？
```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"
```
A: 查看 [skills/gitlink-shared/REFERENCE.md](skills/gitlink-shared/REFERENCE.md)
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?
- [gitlink-bisync](https://www.gitlink.org.cn/wbtiger/gitlink-bisync) - GitHub ↔ GitLink 代码双向同步系统
Reinstall first:
## 许可证
```bash
npm install -g @gitlink-ai/cli
```
[Apache License 2.0](LICENSE)
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)

672
README.zh-CN.md Normal file
View File

@ -0,0 +1,672 @@
# gitlink-cli
[![GitLink](https://img.shields.io/badge/GitLink-Gitlink%2Fgitlink--cli-green)](https://www.gitlink.org.cn/Gitlink/gitlink-cli)
[![License](https://img.shields.io/badge/License-MulanPSL--2.0-blue.svg)](https://license.coscl.org.cn/MulanPSL2)
[![Go Version](https://img.shields.io/badge/Go-1.26%2B-blue.svg)](https://golang.org)
[![npm version](https://img.shields.io/npm/v/@gitlink-ai/cli.svg)](https://www.npmjs.com/package/@gitlink-ai/cli)
[GitLink（确实开源）](https://www.gitlink.org.cn) 官方 CLI 工具 — 为人类和 AI Agent 双重设计。支持 **macOS、Linux、Windows**，覆盖仓库管理、Wiki、Issue 追踪、Pull Request、Webhook、成员协作、CI/CD 和 AI 自动化工作流，包含 40+ 命令和 AI Agent [Skills](./skills/)。
**[English](./README.md)**
[安装](#安装与快速上手) · [AI Agent Skills](#ai-agent-skills) · [认证](#配置与使用) · [命令](#使用示例) · [贡献](#相关项目)
## 贡献者
<div style="display: flex; gap: 16px; flex-wrap: wrap; align-items: flex-start;">
<div align="center">
<a href="https://www.gitlink.org.cn/wangyue111" title="wangyue111"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/W/43_254_70/120.png" width="40" height="40" alt="wangyue111" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/wangyue111">wangyue111</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/wbtiger" title="tigerwang"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/T/14_168_39/120.png" width="40" height="40" alt="wbtiger" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/wbtiger">wbtiger</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/Mengz" title="Mengz"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/M/166_152_185/120.png" width="40" height="40" alt="Mengz" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/Mengz">Mengz</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/yangsai" title="杨赛"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/Y/94_150_149/120.png" width="40" height="40" alt="yangsai" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/yangsai">yangsai</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/mengcheng" title="camelliamc"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/M/206_114_54/120.png" width="40" height="40" alt="mengcheng" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/mengcheng">mengcheng</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/muel" title="赵奕程"><img src="https://www.gitlink.org.cn/images/avatars/User/149182?t=1779603476" width="40" height="40" alt="muel" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/muel">muel</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/Leo77" title="Leo77"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/L/173_120_149/120.png" width="40" height="40" alt="Leo77" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/Leo77">Leo77</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/yingjie" title="yingjie"><img src="https://www.gitlink.org.cn/images/avatars/User/145288?t=1765791899" width="40" height="40" alt="yingjie" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/yingjie">yingjie</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/topshare" title="Kevin Zhang"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/K/65_152_142/120.png" width="40" height="40" alt="topshare" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/topshare">topshare</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/dtwdtw" title="dtwdtw"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/D/53_166_51/120.png" width="40" height="40" alt="dtwdtw" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/dtwdtw">dtwdtw</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/recorder" title="recorder"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/R/141_201_87/120.png" width="40" height="40" alt="recorder" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/recorder">recorder</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/puygob236" title="Jiachen Li"><img src="https://www.gitlink.org.cn/images/avatars/User/149183?t=1778815174" width="40" height="40" alt="puygob236" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/puygob236">puygob236</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/co63oc" title="co63oc"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/C/205_201_141/120.png" width="40" height="40" alt="co63oc" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/co63oc">co63oc</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/lindiwen23" title="lindiwen23"><img src="https://www.gitlink.org.cn/images/avatars/User/141609?t=1748270628" width="40" height="40" alt="lindiwen23" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/lindiwen23">lindiwen23</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/ohanabi" title="ohanabi"><img src="https://www.gitlink.org.cn/images/avatars/User/148166?t=1778230283" width="40" height="40" alt="ohanabi" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/ohanabi">ohanabi</a></sub>
</div>
<div align="center">
<a href="https://www.gitlink.org.cn/jiangtx" title="jiangtx"><img src="https://www.gitlink.org.cn/system/lets/letter_avatars/2/J/67_157_94/120.png" width="40" height="40" alt="jiangtx" style="border-radius: 50%;"></a>
<br><sub><a href="https://www.gitlink.org.cn/jiangtx">jiangtx</a></sub>
</div>
</div>
## 为什么选择 gitlink-cli？
- **Agent-Native 设计** — 开箱即用结构化 [Skills](./skills/)，兼容 Claude Code — Agent 零配置即可操作 GitLink
- **广泛覆盖** — 仓库、Wiki、Issue、PR、Webhook、成员、分支、Release、CI、Pipeline、组织、搜索、用户等常用工作流均提供高层命令
- **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、删除仓库，查看仓库信息、洞察数据和互动状态 |
| 📚 Wiki | 列出、查看、创建、更新、删除 Wiki 页面 |
| 🐛 Issue | 创建、更新、关闭、批量关闭、评论 Issue |
| 🔖 标签 | 创建、列出、更新、删除 Issue 标签 |
| 🔀 PR | 创建、合并、Review Pull Request，查看变更文件 |
| 👥 成员 | 列出、添加、移除仓库成员，调整角色，生成和接受邀请链接 |
| 🌿 分支 | 创建、删除、保护分支 |
| 🏷️ 发布 | 创建、编辑、更新、查看、删除 Release |
| 🏢 组织 | 管理组织、成员、团队 |
| 🔧 CI | 查看构建、日志、CI/CD 操作 |
| ⚙️ Pipeline | 运行、查看、启停、删除流水线工作流并查询日志 |
| 🔍 搜索 | 搜索仓库、用户 |
| 👤 用户 | 查看用户资料和信息 |
| 📋 项目管理 | 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
# 读取仓库 README
gitlink-cli repo +readme --owner Gitlink --repo forgeplus --ref master
# 列出仓库根目录或指定目录文件
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --ref master
gitlink-cli repo +tree --owner Gitlink --repo forgeplus --path src --ref main
# 查看语言占比
gitlink-cli repo +languages --owner Gitlink --repo forgeplus
# 列出贡献者
gitlink-cli repo +contributors --owner Gitlink --repo forgeplus
# 查看分支、标签或提交的贡献者代码行统计
gitlink-cli repo +contributor-stats --owner Gitlink --repo forgeplus --ref master --pass-year 1
# 查看仓库代码统计
gitlink-cli repo +code-stats --owner Gitlink --repo forgeplus --ref master
# 按时间范围查看关注者和点赞者
gitlink-cli repo +watchers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
gitlink-cli repo +stargazers --owner Gitlink --repo forgeplus --start-at 1714521600 --end-at 1717200000
# 预览并执行仓库互动操作
gitlink-cli repo +follow --owner Gitlink --repo forgeplus --dry-run
gitlink-cli repo +follow --owner Gitlink --repo forgeplus
gitlink-cli repo +unfollow --owner Gitlink --repo forgeplus --project-id 123
gitlink-cli repo +like --owner Gitlink --repo forgeplus
gitlink-cli repo +unlike --owner Gitlink --repo forgeplus --project-id 123
# 创建仓库
gitlink-cli repo +create -n my-project -d "项目描述"
# Fork 仓库
gitlink-cli repo +fork --owner Gitlink --repo forgeplus
```
### Wiki 管理
```bash
# 列出 Wiki 页面
gitlink-cli wiki +list --owner Gitlink --repo forgeplus
# 查看 Wiki 页面
gitlink-cli wiki +view --owner Gitlink --repo forgeplus --page Home
# 使用命令行内容创建 Wiki 页面
gitlink-cli wiki +create --owner Gitlink --repo forgeplus \
--page Home --title Home --content "欢迎来到项目 Wiki"
# 使用 Markdown 文件更新 Wiki 页面
gitlink-cli wiki +update --owner Gitlink --repo forgeplus \
--page Home --file docs/wiki-home.md --message "更新 Home"
# 删除 Wiki 页面
gitlink-cli wiki +delete --owner Gitlink --repo forgeplus --page Home
```
### Webhook 管理
```bash
# 列出 webhook
gitlink-cli webhook +list --owner Gitlink --repo forgeplus
# 创建 webhook
gitlink-cli webhook +create --owner Gitlink --repo forgeplus \
--url https://example.com/hook --events push,create
# 测试 webhook
gitlink-cli webhook +test --owner Gitlink --repo forgeplus --id 68
# 查看 webhook 投递任务
gitlink-cli webhook +tasks --owner Gitlink --repo forgeplus --id 68
```
### 成员管理
```bash
# 列出仓库成员
gitlink-cli member +list --owner Gitlink --repo forgeplus
# 添加成员
gitlink-cli member +add --owner Gitlink --repo forgeplus --user-id 101
# 预览批量添加成员，不修改数据
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --user-ids 101,102 --dry-run
# 从 CSV 文件批量添加成员
gitlink-cli member +batch-add --owner Gitlink --repo forgeplus --from members.csv
# 调整成员权限
gitlink-cli member +role --owner Gitlink --repo forgeplus --user-id 101 --role Developer
# 生成邀请链接
gitlink-cli member +invite-link --owner Gitlink --repo forgeplus --role developer --apply true
```
### 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 +create --owner Gitlink --repo forgeplus -t "Bug: 登录失败" --priority-id 3 --tag-ids 4,5 --assigner-ids 7
# 查看 Issue
gitlink-cli issue +view --owner Gitlink --repo forgeplus -i 123
# 更新 Issue 元数据
gitlink-cli issue +update --owner Gitlink --repo forgeplus --number 123 --priority-id 4 --branch bugfix/login --due-date 2026-06-15
# 关闭 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 "已修复"
# 列出 Issue 负责人
gitlink-cli issue +assigners --owner Gitlink --repo forgeplus
# 列出 Issue 发布人
gitlink-cli issue +authors --owner Gitlink --repo forgeplus
# 列出 Issue 优先级
gitlink-cli issue +priorities --owner Gitlink --repo forgeplus
# 列出 Issue 标签
gitlink-cli issue +tags --owner Gitlink --repo forgeplus --only-name
# 列出 Issue 状态
gitlink-cli issue +statuses --owner Gitlink --repo forgeplus
```
`issue +view`、`issue +update`、`issue +close` 和 `issue +comment` 推荐使用
`--number` / `-n` 传网页 URL 中的 Issue 编号。`--id` / `-i` 是同一网页 Issue
编号的兼容别名，不是数据库内部 ID。
### 标签管理
```bash
# 列出 Issue 标签
gitlink-cli label +list --owner Gitlink --repo forgeplus
# 按关键词筛选标签
gitlink-cli label +list --owner Gitlink --repo forgeplus -k bug
# 创建标签（颜色默认 #1E90FF）
gitlink-cli label +create --owner Gitlink --repo forgeplus -n bug -d "功能缺陷" -c "#FF0000"
# 更新标签（未指定的字段会被保留）
gitlink-cli label +update --owner Gitlink --repo forgeplus -i 42 -c "#00FF00"
# 删除标签
gitlink-cli label +delete --owner Gitlink --repo forgeplus -i 42
```
### 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 +reopen --owner Gitlink --repo forgeplus -i 42
# 查看 PR 变更文件
gitlink-cli pr +files --owner Gitlink --repo forgeplus -i 42
# 查看 PR patchset/version 列表
gitlink-cli pr +versions --owner Gitlink --repo forgeplus -i 42
# 查看指定 patchset/version diff
gitlink-cli pr +version-diff --owner Gitlink --repo forgeplus -i 42 --version-id 16040
# 查看 PR 审查记录
gitlink-cli pr +reviews --owner Gitlink --repo forgeplus -i 42
# 创建 PR 审查（支持 dry-run 预览）
gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM" --dry-run
gitlink-cli pr +review --owner Gitlink --repo forgeplus -i 42 --status approved -c "LGTM"
```
### 发布管理
```bash
# 列出 Release
gitlink-cli release +list --owner Gitlink --repo forgeplus
# 创建 Release，可附带附件 ID
gitlink-cli release +create --owner Gitlink --repo forgeplus -t v1.0.0 -n "v1.0.0 正式版" -b "更新内容..." --attachment-ids 12,34
# 查看 Release
gitlink-cli release +view --owner Gitlink --repo forgeplus -i <version_id>
# 获取编辑数据并保留未传字段更新
gitlink-cli release +edit --owner Gitlink --repo forgeplus -i <version_id>
gitlink-cli release +update --owner Gitlink --repo forgeplus -i <version_id> -b "更新后的内容" --dry-run
# 删除前先预览请求
gitlink-cli release +delete --owner Gitlink --repo forgeplus -i <version_id> --dry-run
```
### 流水线管理
```bash
# 列出平台流水线
gitlink-cli pipeline +list --owner-id 123 --page 1 --limit 20
# 列出仓库流水线运行记录
gitlink-cli pipeline +runs --owner Gitlink --repo forgeplus --ref master --workflow build.yml
# 运行流水线工作流，先用 dry-run 预览请求
gitlink-cli pipeline +run --owner Gitlink --repo forgeplus --ref master --workflow build.yml --dry-run
# 查看流水线详情、日志和运行结果
gitlink-cli pipeline +view --owner Gitlink --repo forgeplus --id 7
gitlink-cli pipeline +logs --owner Gitlink --repo forgeplus --run-id 99 --id 7 --index 43
gitlink-cli pipeline +results --owner Gitlink --repo forgeplus --run-id 99
# 启停或删除流水线工作流，写入/删除前先预览
gitlink-cli pipeline +disable --owner Gitlink --repo forgeplus --id 7 --workflow build.yml --dry-run
gitlink-cli pipeline +delete --owner Gitlink --repo forgeplus --id 7 --dry-run
```
### 搜索
```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":"..."}'
# 从文件读取 JSON body
gitlink-cli api POST /Gitlink/forgeplus/issues --body-file issue.json
# 从 stdin 读取 JSON body
Get-Content issue.json | gitlink-cli api POST /Gitlink/forgeplus/issues --body-stdin
# 带查询参数
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/` 目录包含 Claude Code Agent Skill 文件，支持 AI 自动化操作 GitLink 平台。
详见 [skills/README.md](skills/README.md)
| Skill | 说明 |
|-------|------|
| `gitlink-shared` | 认证、全局参数、安全规则、API 注意事项 |
| `gitlink-repo` | 仓库操作（创建、查看、删除、Fork、洞察数据等） |
| `gitlink-wiki` | Wiki 操作（列出、查看、创建、更新、删除） |
| `gitlink-issue` | Issue 操作（创建、更新、关闭、评论等） |
| `gitlink-pr` | Pull Request 操作（创建、合并、Review 等） |
| `gitlink-member` | 仓库成员与邀请链接管理 |
| `gitlink-release` | 发布管理（创建、编辑、更新、查看、删除等） |
| `gitlink-org` | 组织管理（成员、团队等） |
| `gitlink-ci` | CI/CD 操作（构建、日志等） |
| `gitlink-pipeline` | 流水线工作流操作（运行、日志、启停、删除等） |
| `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
│ ├── member/ # 仓库成员 shortcuts
│ ├── branch/ # 分支 shortcuts
│ ├── release/ # Release shortcuts
│ ├── org/ # 组织 shortcuts
│ ├── ci/ # CI shortcuts
│ ├── pipeline/ # Pipeline 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)

119
cmd/alias/alias.go Normal file
View File

@ -0,0 +1,119 @@
package alias
import (
"fmt"
"os"
"github.com/spf13/cobra"
"gopkg.in/yaml.v3"
"github.com/gitlink-org/gitlink-cli/internal/config"
)
// AliasConfig represents the aliases section of the CLI config.
type AliasConfig struct {
Aliases map[string]string `yaml:"aliases,omitempty"`
}
// NewAliasCmd creates the alias command with subcommands.
func NewAliasCmd() *cobra.Command {
cmd := &cobra.Command{
Use: "alias",
Short: "管理命令别名（把长命令变短）",
Long: `管理 gitlink-cli 的命令别名。
别名允许你为常用命令创建简短的名称，例如：
gitlink-cli alias +set rl "repo +list"
之后可以使用: gitlink-cli rl
别名存储在 ~/.config/gitlink-cli/aliases.yaml 中。`,
Example: ` gitlink-cli alias +list
gitlink-cli alias +set rl "repo +list"
gitlink-cli alias +set ri "repo +info --owner Gitlink --repo gitlink-cli"
gitlink-cli alias +delete rl`,
}
cmd.AddCommand(
&cobra.Command{
Use: "+list",
Short: "列出所有已定义的别名",
Long: "列出所有已定义的命令别名。如果没有任何别名，会给出创建提示。",
RunE: func(cmd *cobra.Command, args []string) error {
aliases, _ := loadAliases()
if len(aliases) == 0 {
fmt.Println("（未定义任何别名）")
fmt.Println("使用 alias +set <名称> <命令> 来创建别名")
return nil
}
for k, v := range aliases {
fmt.Printf(" %-15s → %s\n", k, v)
}
return nil
},
},
&cobra.Command{
Use: "+set <name> <command>",
Short: "设置别名",
Long: "为一条命令设置别名。如果别名已存在，会被覆盖。",
Args: cobra.ExactArgs(2),
Example: ` gitlink-cli alias +set rl "repo +list"
gitlink-cli alias +set ri "repo +info"`,
RunE: func(cmd *cobra.Command, args []string) error {
aliases, _ := loadAliases()
aliases[args[0]] = args[1]
if err := saveAliases(aliases); err != nil {
return err
}
fmt.Printf("别名已设置: %s → %s\n", args[0], args[1])
return nil
},
},
&cobra.Command{
Use: "+delete <name>",
Short: "删除别名",
Long: "删除一个已定义的命令别名。",
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
aliases, _ := loadAliases()
if _, ok := aliases[args[0]]; !ok {
return fmt.Errorf("别名 %s 不存在", args[0])
}
delete(aliases, args[0])
if err := saveAliases(aliases); err != nil {
return err
}
fmt.Printf("别名已删除: %s\n", args[0])
return nil
},
},
)
return cmd
}
func aliasesPath() string {
return config.ConfigDir() + "/aliases.yaml"
}
func loadAliases() (map[string]string, error) {
data, err := os.ReadFile(aliasesPath())
if err != nil {
return make(map[string]string), nil
}
var ac AliasConfig
if err := yaml.Unmarshal(data, &ac); err != nil {
return make(map[string]string), nil
}
if ac.Aliases == nil {
ac.Aliases = make(map[string]string)
}
return ac.Aliases, nil
}
func saveAliases(a map[string]string) error {
data, err := yaml.Marshal(AliasConfig{Aliases: a})
if err != nil {
return err
}
os.MkdirAll(config.ConfigDir(), 0700)
return os.WriteFile(aliasesPath(), data, 0600)
}

193
cmd/alias/alias_test.go Normal file
View File

@ -0,0 +1,193 @@
package alias
import (
"bytes"
"os"
"strings"
"testing"
"github.com/spf13/cobra"
)
func TestLoadAliasesEmpty(t *testing.T) {
// 设置临时配置目录
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
aliases, err := loadAliases()
if err != nil {
t.Fatalf("loadAliases failed: %v", err)
}
if len(aliases) != 0 {
t.Fatalf("expected empty aliases, got %d", len(aliases))
}
}
func TestSaveAndLoadAliases(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
// 保存
original := map[string]string{
"rl": "repo +list",
"ri": "repo +info",
}
if err := saveAliases(original); err != nil {
t.Fatalf("saveAliases failed: %v", err)
}
// 加载
loaded, err := loadAliases()
if err != nil {
t.Fatalf("loadAliases failed: %v", err)
}
if len(loaded) != 2 {
t.Fatalf("expected 2 aliases, got %d", len(loaded))
}
if loaded["rl"] != "repo +list" {
t.Errorf("expected rl -> repo +list, got %s", loaded["rl"])
}
if loaded["ri"] != "repo +info" {
t.Errorf("expected ri -> repo +info, got %s", loaded["ri"])
}
}
func TestSaveAliasesOverwrite(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
// 第一次保存
saveAliases(map[string]string{"rl": "repo +list"})
// 覆盖保存
saveAliases(map[string]string{"rl": "repo +list --owner Gitlink"})
loaded, _ := loadAliases()
if loaded["rl"] != "repo +list --owner Gitlink" {
t.Errorf("alias should be overwritten, got %s", loaded["rl"])
}
}
func TestLoadAliasesInvalidYAML(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
// 写入无效 YAML
os.WriteFile(tmpDir+"/aliases.yaml", []byte("{{invalid yaml}}"), 0600)
aliases, err := loadAliases()
if err != nil {
t.Fatalf("should not error on invalid YAML, got: %v", err)
}
if len(aliases) != 0 {
t.Fatalf("should return empty map on invalid YAML, got %d", len(aliases))
}
}
func TestNewAliasCmd(t *testing.T) {
cmd := NewAliasCmd()
if cmd.Use != "alias" {
t.Errorf("expected Use 'alias', got %s", cmd.Use)
}
if !cmd.HasSubCommands() {
t.Error("alias command should have subcommands")
}
subcmds := cmd.Commands()
if len(subcmds) != 3 {
t.Fatalf("expected 3 subcommands, got %d", len(subcmds))
}
}
func TestAliasListSubcommand(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
cmd := NewAliasCmd()
// 找到 +list 子命令
var listCmd *cobra.Command
for _, sub := range cmd.Commands() {
if sub.Use == "+list" {
listCmd = sub
break
}
}
if listCmd == nil {
t.Fatal("+list subcommand not found")
}
// 无别名时运行
buf := new(bytes.Buffer)
listCmd.SetOut(buf)
listCmd.SetArgs([]string{})
if err := listCmd.Execute(); err != nil {
t.Fatalf("list failed: %v", err)
}
if !strings.Contains(buf.String(), "未定义任何别名") {
t.Errorf("expected hint for no aliases, got: %s", buf.String())
}
}
func TestAliasSetAndDeleteSubcommands(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
cmd := NewAliasCmd()
// 找到 +set 子命令
var setCmd, deleteCmd *cobra.Command
for _, sub := range cmd.Commands() {
if strings.HasPrefix(sub.Use, "+set") {
setCmd = sub
}
if strings.HasPrefix(sub.Use, "+delete") {
deleteCmd = sub
}
}
// +set
setCmd.SetArgs([]string{"rl", "repo +list"})
if err := setCmd.Execute(); err != nil {
t.Fatalf("set failed: %v", err)
}
// 验证文件写入
aliases, _ := loadAliases()
if aliases["rl"] != "repo +list" {
t.Fatalf("alias not saved correctly: %v", aliases)
}
// +delete
deleteCmd.SetArgs([]string{"rl"})
if err := deleteCmd.Execute(); err != nil {
t.Fatalf("delete failed: %v", err)
}
// 验证已删除
aliases, _ = loadAliases()
if _, ok := aliases["rl"]; ok {
t.Fatal("alias should have been deleted")
}
}
func TestAliasDeleteNonExistent(t *testing.T) {
tmpDir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", tmpDir)
cmd := NewAliasCmd()
var deleteCmd *cobra.Command
for _, sub := range cmd.Commands() {
if strings.HasPrefix(sub.Use, "+delete") {
deleteCmd = sub
break
}
}
deleteCmd.SetArgs([]string{"nonexistent"})
err := deleteCmd.Execute()
if err == nil {
t.Fatal("expected error when deleting nonexistent alias")
}
if !strings.Contains(err.Error(), "不存在") {
t.Errorf("error should mention alias does not exist: %v", err)
}
}

189
cmd/api/api.go
View File

@ -2,42 +2,114 @@ package api
import (
"encoding/json"
"errors"
"fmt"
"io"
"net/url"
"os"
"regexp"
"strings"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
"github.com/gitlink-org/gitlink-cli/internal/client"
"github.com/gitlink-org/gitlink-cli/internal/context"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
"github.com/gitlink-org/gitlink-cli/internal/output"
)
func NewAPICmd() *cobra.Command {
// apiOwnerPlaceholder and apiRepoPlaceholder match the REST-style :owner / :repo
// path placeholders used throughout the GitLink API docs and shortcut commands.
var (
apiOwnerPlaceholder = regexp.MustCompile(`:owner\b`)
apiRepoPlaceholder = regexp.MustCompile(`:repo\b`)
)
func NewAPICmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
apiCmd := &cobra.Command{
Use: "api <METHOD> <PATH>",
Short: "Make raw API requests to GitLink",
Long: `Send arbitrary HTTP requests to the GitLink API. Authentication is injected automatically.`,
Use: "api (<METHOD> <PATH> | --batch-file <FILE>)",
Short: tr.T("cmd.api.short"),
Long: tr.T("cmd.api.long"),
Example: ` gitlink-cli api GET /users/me
gitlink-cli api GET /projects --query 'page=1&limit=10'
gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"Bug","description":"..."}'`,
Args: cobra.ExactArgs(2),
gitlink-cli api POST /:owner/:repo/issues --body '{"subject":"Bug","description":"..."}'
gitlink-cli api POST /:owner/:repo/issues --body-file issue.json
gitlink-cli api --batch-file plan.json --dry-run
gitlink-cli api --batch-file plan.json --var owner=Gitlink --var repo=gitlink-cli`,
Args: validateAPIArgs,
RunE: runAPI,
}
apiCmd.Flags().String("body", "", "Request body (JSON string)")
apiCmd.Flags().String("query", "", "Query parameters (key=val&key2=val2)")
apiCmd.Flags().StringSlice("header", nil, "Additional headers (key:value)")
apiCmd.Flags().String("body", "", tr.T("flag.api.body"))
apiCmd.Flags().String("body-file", "", tr.T("flag.api.body_file"))
apiCmd.Flags().Bool("body-stdin", false, tr.T("flag.api.body_stdin"))
apiCmd.Flags().String("query", "", tr.T("flag.api.query"))
apiCmd.Flags().StringSlice("header", nil, tr.T("flag.api.header"))
apiCmd.Flags().String("batch-file", "", tr.T("flag.api.batch_file"))
apiCmd.Flags().Bool("dry-run", false, tr.T("flag.api.batch_dry_run"))
apiCmd.Flags().Bool("continue-on-error", false, tr.T("flag.api.batch_continue_on_error"))
apiCmd.Flags().StringArray("var", nil, tr.T("flag.api.batch_var"))
return apiCmd
}
func runAPI(c *cobra.Command, args []string) error {
method := strings.ToUpper(args[0])
path := args[1]
func validateAPIArgs(c *cobra.Command, args []string) error {
batchFile, _ := c.Flags().GetString("batch-file")
if batchFile != "" {
if len(args) != 0 {
return fmt.Errorf("api batch mode does not accept METHOD or PATH arguments")
}
return nil
}
return cobra.ExactArgs(2)(c, args)
}
if !strings.HasPrefix(path, "/") {
path = "/" + path
// msysPathRe matches Windows drive-letter prefixes produced by MSYS2/Git Bash
// path conversion, e.g. "C:/Program Files/Git/v1/owner/repo" for input "/v1/owner/repo".
var msysPathRe = regexp.MustCompile(`^[A-Za-z]:/`)
// restoreAPIPath restores an API path polluted by MSYS2/Git Bash path
// conversion on Windows, e.g. "C:/Program Files/Git/v1/owner/repo" -> "/v1/owner/repo".
// If the path does not start with a drive letter, or no known API prefix is
// found, the original path is returned unchanged.
func restoreAPIPath(path string) string {
if !msysPathRe.MatchString(path) {
return path
}
// Pick the EARLIEST occurrence among known API prefixes, so a path like
// ".../api/v1/users" restores to "/api/v1/users" rather than "/v1/users".
bestIdx := -1
for _, prefix := range []string{"/v1/", "/v2/", "/api/", "/users/", "/projects/"} {
if idx := strings.Index(path, prefix); idx >= 0 && (bestIdx == -1 || idx < bestIdx) {
bestIdx = idx
}
}
if bestIdx >= 0 {
return path[bestIdx:]
}
return path
}
func runAPI(c *cobra.Command, args []string) error {
batchFile, _ := c.Flags().GetString("batch-file")
if batchFile != "" {
return runAPIBatch(c, batchFile)
}
method := strings.ToUpper(args[0])
// Fix MSYS2/Git Bash path auto-conversion on Windows first:
// "/v1/owner/repo" is rewritten to "C:/Program Files/Git/v1/owner/repo".
rawPath := restoreAPIPath(args[1])
path, err := resolveAPIPath(c, rawPath)
if err != nil {
return err
}
cli, err := client.New()
@ -46,12 +118,9 @@ func runAPI(c *cobra.Command, args []string) error {
}
cli.Debug = cmdutil.Debug
var body interface{}
bodyStr, _ := c.Flags().GetString("body")
if bodyStr != "" {
if err := json.Unmarshal([]byte(bodyStr), &body); err != nil {
return fmt.Errorf("invalid JSON body: %w", err)
}
body, err := readJSONBody(c)
if err != nil {
return err
}
var query url.Values
@ -66,7 +135,8 @@ func runAPI(c *cobra.Command, args []string) error {
env, err := cli.Do(method, path, body, query)
if err != nil {
if apiErr, ok := err.(*client.APIError); ok {
var apiErr *client.APIError
if errors.As(err, &apiErr) {
errEnv := output.ErrorEnvelope(apiErr.Code, apiErr.Message, "")
return output.Print(errEnv, resolveFormat())
}
@ -76,6 +146,83 @@ func runAPI(c *cobra.Command, args []string) error {
return output.Print(env, resolveFormat())
}
// resolveAPIPath prepares a single-call path: it renders {{var}} templates
// supplied via --var (consistent with batch mode), substitutes the REST-style
// :owner / :repo placeholders (resolved from --owner/--repo or the git remote,
// exactly like the shortcut commands), and ensures a leading slash.
func resolveAPIPath(c *cobra.Command, rawPath string) (string, error) {
path := rawPath
overrides, err := parseBatchVars(c)
if err != nil {
return "", err
}
if len(overrides) > 0 {
rendered, rerr := renderTemplate(path, overrides)
if rerr != nil {
return "", rerr
}
path = rendered
}
if apiOwnerPlaceholder.MatchString(path) || apiRepoPlaceholder.MatchString(path) {
owner, repo, rerr := context.ResolveOwnerRepo(cmdutil.Owner, cmdutil.Repo)
if rerr != nil {
return "", fmt.Errorf("path contains :owner/:repo placeholders but they could not be resolved: %w", rerr)
}
path = apiOwnerPlaceholder.ReplaceAllLiteralString(path, owner)
path = apiRepoPlaceholder.ReplaceAllLiteralString(path, repo)
}
if !strings.HasPrefix(path, "/") {
path = "/" + path
}
return path, nil
}
func readJSONBody(c *cobra.Command) (interface{}, error) {
bodyStr, _ := c.Flags().GetString("body")
bodyFile, _ := c.Flags().GetString("body-file")
bodyStdin, _ := c.Flags().GetBool("body-stdin")
sources := 0
if bodyStr != "" {
sources++
}
if bodyFile != "" {
sources++
}
if bodyStdin {
sources++
}
if sources == 0 {
return nil, nil
}
if sources > 1 {
return nil, fmt.Errorf("use only one of --body, --body-file, or --body-stdin")
}
var data []byte
var err error
switch {
case bodyStr != "":
data = []byte(bodyStr)
case bodyFile != "":
data, err = os.ReadFile(bodyFile)
case bodyStdin:
data, err = io.ReadAll(c.InOrStdin())
}
if err != nil {
return nil, fmt.Errorf("read JSON body: %w", err)
}
var body interface{}
if err := json.Unmarshal(data, &body); err != nil {
return nil, fmt.Errorf("invalid JSON body: %w", err)
}
return body, nil
}
func resolveFormat() string {
f := cmdutil.Format
if f == "" {

560
cmd/api/api_test.go Normal file
View File

@ -0,0 +1,560 @@
package api
import (
"encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"testing"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
)
func TestResolveFormat(t *testing.T) {
tests := []struct {
name string
flagFormat string
want string
}{
{"empty defaults to json", "", "json"},
{"explicit json", "json", "json"},
{"explicit yaml", "yaml", "yaml"},
{"explicit table", "table", "table"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
cmdutil.Format = tt.flagFormat
if got := resolveFormat(); got != tt.want {
t.Fatalf("resolveFormat = %q, want %q", got, tt.want)
}
})
}
}
func TestNewAPICmd(t *testing.T) {
cmd := NewAPICmd()
if cmd.Use != "api (<METHOD> <PATH> | --batch-file <FILE>)" {
t.Fatalf("Use = %q", cmd.Use)
}
if cmd.Short == "" {
t.Fatal("Short is empty")
}
// Verify flags exist
flags := []string{"body", "query", "header", "batch-file", "dry-run", "continue-on-error", "var"}
for _, f := range flags {
if cmd.Flags().Lookup(f) == nil {
t.Fatalf("flag %q not found", f)
}
}
}
func setupAPITest(t *testing.T, handler http.HandlerFunc) string {
t.Helper()
server := httptest.NewServer(handler)
t.Cleanup(server.Close)
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
os.MkdirAll(dir, 0700)
os.WriteFile(filepath.Join(dir, "config.yaml"), []byte("base_url: "+server.URL+"\ndefault_format: table\n"), 0600)
return dir
}
func TestRunAPIGet(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/users/me.json" {
t.Fatalf("unexpected path: %s", r.URL.Path)
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"login": "testuser", "id": 42})
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/users/me"})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI GET error: %v", err)
}
}
func TestRunAPIPostWithBody(t *testing.T) {
var gotBody map[string]interface{}
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
if r.Method != "POST" {
t.Fatalf("expected POST, got %s", r.Method)
}
json.NewDecoder(r.Body).Decode(&gotBody)
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"id": 1, "title": "new issue"})
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"POST", "/repos/owner/repo/issues"})
cmd.Flags().Set("body", `{"title":"new issue","body":"test"}`)
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI POST error: %v", err)
}
if gotBody["title"] != "new issue" {
t.Fatalf("body title = %q, want 'new issue'", gotBody["title"])
}
}
func TestRunAPIBadJSONBody(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("should not reach server")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"POST", "/repos/owner/repo/issues"})
cmd.Flags().Set("body", `{bad json}`)
err := cmd.Execute()
if err == nil {
t.Fatal("expected error for bad JSON body")
}
}
func TestRunAPIBadQuery(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("should not reach server")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/repos/owner/repo/issues"})
cmd.Flags().Set("query", "key=%zz")
err := cmd.Execute()
if err == nil {
t.Fatal("expected error for bad query string")
}
}
func TestRunAPIPaginate(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
page := r.URL.Query().Get("page")
w.Header().Set("Content-Type", "application/json")
switch page {
case "1":
json.NewEncoder(w).Encode(map[string]interface{}{
"total_count": 3,
"issues": []interface{}{
map[string]interface{}{"id": 1},
map[string]interface{}{"id": 2},
},
})
default:
json.NewEncoder(w).Encode(map[string]interface{}{
"total_count": 3,
"issues": []interface{}{
map[string]interface{}{"id": 3},
},
})
}
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/owner/repo/issues", "--paginate", "--query", "limit=2"})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI paginate error: %v", err)
}
}
func TestRunAPIPaginateRejectsNonGET(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("server should not be reached")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"POST", "/owner/repo/issues", "--paginate"})
if err := cmd.Execute(); err == nil {
t.Fatal("expected error for --paginate with POST")
}
}
func TestRunAPIPaginateRejectsBatchFile(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("server should not be reached")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"--batch-file", "plan.json", "--paginate"})
if err := cmd.Execute(); err == nil {
t.Fatal("expected error for --paginate with --batch-file")
}
}
func TestRunAPIHTTPError(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNotFound)
w.Write([]byte("not found"))
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/nonexistent"})
// HTTP errors are caught and printed as error envelopes; runAPI does not return the error
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI HTTP error: %v (expected success with error envelope)", err)
}
}
func TestRunAPIStatusError(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusUnauthorized)
json.NewEncoder(w).Encode(map[string]interface{}{"status": float64(401), "message": "Unauthorized"})
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/users/me"})
// Should print error envelope, not return a Go error (status check in Do() handles this)
// Actually, HTTP 401 triggers APIError return from Do(), so this should error
if err := cmd.Execute(); err != nil {
// Expected — HTTP error
t.Logf("got expected error: %v", err)
}
}
func TestRunAPIDebug(t *testing.T) {
var gotDebugHeader bool
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
gotDebugHeader = true
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"ok": true})
})
cmdutil.Format = "json"
cmdutil.Debug = true
defer func() { cmdutil.Debug = false }()
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/users/me"})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI debug error: %v", err)
}
if !gotDebugHeader {
t.Fatal("server not reached")
}
}
func TestRunAPINoPrefix(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/users/me.json" {
t.Fatalf("unexpected path: %s", r.URL.Path)
}
w.Header().Set("Content-Type", "application/json")
json.NewEncoder(w).Encode(map[string]interface{}{"login": "testuser"})
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "users/me"})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI no-prefix error: %v", err)
}
}
func TestRunAPIRendersOwnerRepoColonPlaceholders(t *testing.T) {
oldOwner, oldRepo := cmdutil.Owner, cmdutil.Repo
cmdutil.Owner, cmdutil.Repo = "Gitlink", "gitlink-cli"
defer func() {
cmdutil.Owner, cmdutil.Repo = oldOwner, oldRepo
}()
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/Gitlink/gitlink-cli/issues.json" {
t.Fatalf("unexpected path: %s", r.URL.Path)
}
json.NewEncoder(w).Encode(map[string]interface{}{"ok": true})
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/:owner/:repo/issues"})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI placeholder error: %v", err)
}
}
func TestRunAPIRendersVarsInQueryAndBody(t *testing.T) {
var gotBody map[string]interface{}
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/v1/Gitlink/gitlink-cli/issues/42/journals.json" {
t.Fatalf("unexpected path: %s", r.URL.Path)
}
if r.URL.Query().Get("notify") != "true" {
t.Fatalf("notify query = %q", r.URL.Query().Get("notify"))
}
if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
t.Fatalf("decode body: %v", err)
}
json.NewEncoder(w).Encode(map[string]interface{}{"id": 99})
})
cmdutil.Format = "json"
bodyPath := filepath.Join(t.TempDir(), "body.json")
if err := os.WriteFile(bodyPath, []byte(`{"notes":"hello {{actor}}","meta":{"repo":"{{repo}}"}}`), 0600); err != nil {
t.Fatalf("write body: %v", err)
}
cmd := NewAPICmd()
cmd.SetArgs([]string{
"POST", "/v1/{{owner}}/{{repo}}/issues/{{number}}/journals",
"--query", "notify={{notify}}",
"--body-file", bodyPath,
"--var", "owner=Gitlink",
"--var", "repo=gitlink-cli",
"--var", "number=42",
"--var", "notify=true",
"--var", "actor=bot",
})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI rendered vars error: %v", err)
}
if gotBody["notes"] != "hello bot" {
t.Fatalf("notes = %#v", gotBody["notes"])
}
meta := gotBody["meta"].(map[string]interface{})
if meta["repo"] != "gitlink-cli" {
t.Fatalf("meta.repo = %#v", meta["repo"])
}
}
func TestRunAPIDryRunDoesNotReachServer(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("dry-run should not reach server")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{
"POST", "/v1/{{owner}}/{{repo}}/issues",
"--body", `{"subject":"{{title}}"}`,
"--dry-run",
"--var", "owner=Gitlink",
"--var", "repo=gitlink-cli",
"--var", "title=Bug report",
})
if err := cmd.Execute(); err != nil {
t.Fatalf("runAPI dry-run error: %v", err)
}
}
func TestRunAPIMissingSingleRequestVar(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("should not reach server")
})
cmdutil.Format = "json"
cmd := NewAPICmd()
cmd.SetArgs([]string{"GET", "/v1/{{owner}}/{{repo}}/issues/{{number}}"})
if err := cmd.Execute(); err == nil {
t.Fatal("expected missing variable error")
}
}
func TestRenderBatchRequestsTemplateVars(t *testing.T) {
requests, err := renderBatchRequests([]batchRequest{
{
Name: "comment-{{number}}",
Method: "post",
Path: "v1/{{owner}}/{{repo}}/issues/{{number}}/journals",
Query: map[string]interface{}{
"label": []interface{}{"{{label}}", "triage"},
"page": float64(1),
},
Body: map[string]interface{}{
"notes": "handled by {{actor}}",
"meta": map[string]interface{}{"repo": "{{repo}}"},
},
},
}, map[string]string{
"owner": "Gitlink",
"repo": "gitlink-cli",
"number": "42",
"label": "bug",
"actor": "bot",
})
if err != nil {
t.Fatalf("renderBatchRequests error: %v", err)
}
if len(requests) != 1 {
t.Fatalf("len = %d, want 1", len(requests))
}
req := requests[0]
if req.Name != "comment-42" {
t.Fatalf("Name = %q", req.Name)
}
if req.Method != "POST" {
t.Fatalf("Method = %q", req.Method)
}
if req.Path != "/v1/Gitlink/gitlink-cli/issues/42/journals" {
t.Fatalf("Path = %q", req.Path)
}
if got := req.Query["label"]; len(got) != 2 || got[0] != "bug" || got[1] != "triage" {
t.Fatalf("label query = %#v", got)
}
body := req.Body.(map[string]interface{})
if body["notes"] != "handled by bot" {
t.Fatalf("notes = %#v", body["notes"])
}
}
func TestRenderBatchRequestsMissingVar(t *testing.T) {
_, err := renderBatchRequests([]batchRequest{{Method: "GET", Path: "/{{missing}}"}}, nil)
if err == nil {
t.Fatal("expected missing variable error")
}
}
func TestRunAPIBatchDryRunDoesNotReachServer(t *testing.T) {
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
t.Fatal("dry-run should not reach server")
})
cmdutil.Format = "json"
plan := writeBatchPlan(t, map[string]interface{}{
"vars": map[string]string{"owner": "Gitlink"},
"requests": []map[string]interface{}{
{"name": "me", "method": "GET", "path": "/users/me"},
{"name": "repo", "method": "GET", "path": "/{{owner}}/gitlink-cli"},
},
})
cmd := NewAPICmd()
cmd.SetArgs([]string{"--batch-file", plan, "--dry-run"})
if err := cmd.Execute(); err != nil {
t.Fatalf("dry-run batch error: %v", err)
}
}
func TestRunAPIBatchExecutesRequestsWithOverrides(t *testing.T) {
var seen []string
var gotBody map[string]interface{}
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
seen = append(seen, r.Method+" "+r.URL.String())
switch r.URL.Path {
case "/v1/Mengz/gitlink-cli/issues.json":
if r.URL.Query().Get("state") != "open" {
t.Fatalf("state query = %q", r.URL.Query().Get("state"))
}
json.NewEncoder(w).Encode(map[string]interface{}{"issues": []interface{}{}})
case "/v1/Mengz/gitlink-cli/issues/7/journals.json":
if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
t.Fatalf("decode body: %v", err)
}
json.NewEncoder(w).Encode(map[string]interface{}{"id": 99})
default:
t.Fatalf("unexpected path: %s", r.URL.Path)
}
})
cmdutil.Format = "json"
plan := writeBatchPlan(t, map[string]interface{}{
"vars": map[string]string{"owner": "Gitlink", "repo": "gitlink-cli", "issue": "7"},
"requests": []map[string]interface{}{
{
"name": "list",
"method": "GET",
"path": "/v1/{{owner}}/{{repo}}/issues",
"query": map[string]interface{}{"state": "open"},
},
{
"name": "comment",
"method": "POST",
"path": "/v1/{{owner}}/{{repo}}/issues/{{issue}}/journals",
"body": map[string]interface{}{"notes": "hello {{repo}}"},
},
},
})
cmd := NewAPICmd()
cmd.SetArgs([]string{"--batch-file", plan, "--var", "owner=Mengz"})
if err := cmd.Execute(); err != nil {
t.Fatalf("batch execute error: %v", err)
}
if len(seen) != 2 {
t.Fatalf("requests = %d, want 2 (%v)", len(seen), seen)
}
if gotBody["notes"] != "hello gitlink-cli" {
t.Fatalf("body notes = %#v", gotBody["notes"])
}
}
func TestRunAPIBatchStopsOnErrorByDefault(t *testing.T) {
var seen []string
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
seen = append(seen, r.URL.Path)
if r.URL.Path == "/fail.json" {
http.Error(w, "boom", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(map[string]interface{}{"ok": true})
})
cmdutil.Format = "json"
plan := writeBatchPlan(t, map[string]interface{}{
"requests": []map[string]interface{}{
{"method": "GET", "path": "/ok"},
{"method": "GET", "path": "/fail"},
{"method": "GET", "path": "/never"},
},
})
cmd := NewAPICmd()
cmd.SetArgs([]string{"--batch-file", plan})
if err := cmd.Execute(); err == nil {
t.Fatal("expected batch error")
}
if len(seen) != 2 {
t.Fatalf("requests = %d, want 2 (%v)", len(seen), seen)
}
}
func TestRunAPIBatchContinueOnError(t *testing.T) {
var seen []string
setupAPITest(t, func(w http.ResponseWriter, r *http.Request) {
seen = append(seen, r.URL.Path)
if r.URL.Path == "/fail.json" {
http.Error(w, "boom", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(map[string]interface{}{"ok": true})
})
cmdutil.Format = "json"
plan := writeBatchPlan(t, map[string]interface{}{
"requests": []map[string]interface{}{
{"method": "GET", "path": "/ok"},
{"method": "GET", "path": "/fail"},
{"method": "GET", "path": "/after"},
},
})
cmd := NewAPICmd()
cmd.SetArgs([]string{"--batch-file", plan, "--continue-on-error"})
if err := cmd.Execute(); err != nil {
t.Fatalf("batch should continue: %v", err)
}
if len(seen) != 3 {
t.Fatalf("requests = %d, want 3 (%v)", len(seen), seen)
}
}
func writeBatchPlan(t *testing.T, payload interface{}) string {
t.Helper()
data, err := json.Marshal(payload)
if err != nil {
t.Fatalf("marshal plan: %v", err)
}
path := filepath.Join(t.TempDir(), "plan.json")
if err := os.WriteFile(path, data, 0600); err != nil {
t.Fatalf("write plan: %v", err)
}
return path
}

351
cmd/api/batch.go Normal file
View File

@ -0,0 +1,351 @@
package api
import (
"encoding/json"
"errors"
"fmt"
"net/url"
"os"
"regexp"
"sort"
"strings"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
"github.com/gitlink-org/gitlink-cli/internal/client"
"github.com/gitlink-org/gitlink-cli/internal/output"
)
type batchPlan struct {
Vars map[string]string `json:"vars"`
Requests []batchRequest `json:"requests"`
}
type batchRequest struct {
Name string `json:"name"`
Method string `json:"method"`
Path string `json:"path"`
Query map[string]interface{} `json:"query"`
Body interface{} `json:"body"`
}
type renderedBatchRequest struct {
Index int `json:"index" yaml:"index"`
Name string `json:"name,omitempty" yaml:"name,omitempty"`
Method string `json:"method" yaml:"method"`
Path string `json:"path" yaml:"path"`
Query url.Values `json:"query,omitempty" yaml:"query,omitempty"`
Body interface{} `json:"body,omitempty" yaml:"body,omitempty"`
}
type batchResult struct {
Index int `json:"index" yaml:"index"`
Name string `json:"name,omitempty" yaml:"name,omitempty"`
Method string `json:"method" yaml:"method"`
Path string `json:"path" yaml:"path"`
OK bool `json:"ok" yaml:"ok"`
Error string `json:"error,omitempty" yaml:"error,omitempty"`
Data interface{} `json:"data,omitempty" yaml:"data,omitempty"`
}
type batchSummary struct {
DryRun bool `json:"dry_run" yaml:"dry_run"`
ContinueOnError bool `json:"continue_on_error" yaml:"continue_on_error"`
Total int `json:"total" yaml:"total"`
Succeeded int `json:"succeeded" yaml:"succeeded"`
Failed int `json:"failed" yaml:"failed"`
Variables map[string]string `json:"variables,omitempty" yaml:"variables,omitempty"`
Requests []renderedBatchRequest `json:"requests,omitempty" yaml:"requests,omitempty"`
Results []batchResult `json:"results,omitempty" yaml:"results,omitempty"`
}
var templatePattern = regexp.MustCompile(`\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}`)
func runAPIBatch(c *cobra.Command, batchFile string) error {
if hasSingleRequestInput(c) {
return fmt.Errorf("use batch flags separately from --body, --body-file, --body-stdin, --query, or --header")
}
dryRun, _ := c.Flags().GetBool("dry-run")
continueOnError, _ := c.Flags().GetBool("continue-on-error")
overrides, err := parseBatchVars(c)
if err != nil {
return err
}
plan, err := readBatchPlan(batchFile)
if err != nil {
return err
}
vars := mergeBatchVars(plan.Vars, overrides)
requests, err := renderBatchRequests(plan.Requests, vars)
if err != nil {
return err
}
if dryRun {
return output.Print(output.SuccessEnvelope(batchSummary{
DryRun: true,
ContinueOnError: continueOnError,
Total: len(requests),
Variables: sortedVars(vars),
Requests: requests,
}, nil), resolveFormat())
}
cli, err := client.New()
if err != nil {
return err
}
cli.Debug = cmdutil.Debug
summary := batchSummary{
DryRun: false,
ContinueOnError: continueOnError,
Total: len(requests),
Variables: sortedVars(vars),
Results: make([]batchResult, 0, len(requests)),
}
for _, req := range requests {
result := batchResult{
Index: req.Index,
Name: req.Name,
Method: req.Method,
Path: req.Path,
}
env, callErr := cli.Do(req.Method, req.Path, req.Body, req.Query)
if callErr != nil {
summary.Failed++
result.OK = false
result.Error = apiBatchErrorMessage(callErr)
summary.Results = append(summary.Results, result)
if !continueOnError {
_ = output.Print(output.SuccessEnvelope(summary, nil), resolveFormat())
return callErr
}
continue
}
summary.Succeeded++
result.OK = true
if env != nil {
result.Data = env.Data
}
summary.Results = append(summary.Results, result)
}
return output.Print(output.SuccessEnvelope(summary, nil), resolveFormat())
}
func hasSingleRequestInput(c *cobra.Command) bool {
body, _ := c.Flags().GetString("body")
bodyFile, _ := c.Flags().GetString("body-file")
bodyStdin, _ := c.Flags().GetBool("body-stdin")
query, _ := c.Flags().GetString("query")
headers, _ := c.Flags().GetStringSlice("header")
return body != "" || bodyFile != "" || bodyStdin || query != "" || len(headers) > 0
}
func parseBatchVars(c *cobra.Command) (map[string]string, error) {
raw, _ := c.Flags().GetStringArray("var")
vars := make(map[string]string, len(raw))
for _, item := range raw {
key, value, ok := strings.Cut(item, "=")
key = strings.TrimSpace(key)
if !ok || key == "" {
return nil, fmt.Errorf("invalid --var %q, want key=value", item)
}
vars[key] = value
}
return vars, nil
}
func readBatchPlan(path string) (*batchPlan, error) {
data, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("read batch file: %w", err)
}
var plan batchPlan
if err := json.Unmarshal(data, &plan); err != nil {
return nil, fmt.Errorf("invalid batch file JSON: %w", err)
}
if len(plan.Requests) == 0 {
return nil, fmt.Errorf("batch file must contain at least one request")
}
return &plan, nil
}
func mergeBatchVars(planVars, overrides map[string]string) map[string]string {
vars := make(map[string]string, len(planVars)+len(overrides))
for key, value := range planVars {
vars[key] = value
}
for key, value := range overrides {
vars[key] = value
}
return vars
}
func renderBatchRequests(requests []batchRequest, vars map[string]string) ([]renderedBatchRequest, error) {
rendered := make([]renderedBatchRequest, 0, len(requests))
for i, req := range requests {
method := strings.ToUpper(strings.TrimSpace(req.Method))
if method == "" {
return nil, fmt.Errorf("request %d method is required", i+1)
}
path, err := renderTemplate(req.Path, vars)
if err != nil {
return nil, fmt.Errorf("request %d path: %w", i+1, err)
}
path = strings.TrimSpace(path)
if path == "" {
return nil, fmt.Errorf("request %d path is required", i+1)
}
if !strings.HasPrefix(path, "/") {
path = "/" + path
}
query, err := renderBatchQuery(req.Query, vars)
if err != nil {
return nil, fmt.Errorf("request %d query: %w", i+1, err)
}
body, err := renderBatchValue(req.Body, vars)
if err != nil {
return nil, fmt.Errorf("request %d body: %w", i+1, err)
}
name, err := renderTemplate(req.Name, vars)
if err != nil {
return nil, fmt.Errorf("request %d name: %w", i+1, err)
}
rendered = append(rendered, renderedBatchRequest{
Index: i + 1,
Name: name,
Method: method,
Path: path,
Query: query,
Body: body,
})
}
return rendered, nil
}
func renderBatchQuery(raw map[string]interface{}, vars map[string]string) (url.Values, error) {
if len(raw) == 0 {
return nil, nil
}
query := url.Values{}
keys := make([]string, 0, len(raw))
for key := range raw {
keys = append(keys, key)
}
sort.Strings(keys)
for _, key := range keys {
renderedKey, err := renderTemplate(key, vars)
if err != nil {
return nil, err
}
values, err := renderQueryValues(raw[key], vars)
if err != nil {
return nil, fmt.Errorf("%s: %w", key, err)
}
for _, value := range values {
query.Add(renderedKey, value)
}
}
return query, nil
}
func renderQueryValues(raw interface{}, vars map[string]string) ([]string, error) {
switch value := raw.(type) {
case nil:
return []string{""}, nil
case string:
rendered, err := renderTemplate(value, vars)
return []string{rendered}, err
case []interface{}:
values := make([]string, 0, len(value))
for _, item := range value {
itemValues, err := renderQueryValues(item, vars)
if err != nil {
return nil, err
}
values = append(values, itemValues...)
}
return values, nil
default:
return []string{fmt.Sprint(value)}, nil
}
}
func renderBatchValue(raw interface{}, vars map[string]string) (interface{}, error) {
switch value := raw.(type) {
case nil:
return nil, nil
case string:
return renderTemplate(value, vars)
case []interface{}:
items := make([]interface{}, 0, len(value))
for _, item := range value {
rendered, err := renderBatchValue(item, vars)
if err != nil {
return nil, err
}
items = append(items, rendered)
}
return items, nil
case map[string]interface{}:
obj := make(map[string]interface{}, len(value))
for key, item := range value {
renderedKey, err := renderTemplate(key, vars)
if err != nil {
return nil, err
}
rendered, err := renderBatchValue(item, vars)
if err != nil {
return nil, err
}
obj[renderedKey] = rendered
}
return obj, nil
default:
return raw, nil
}
}
func renderTemplate(value string, vars map[string]string) (string, error) {
var missing []string
rendered := templatePattern.ReplaceAllStringFunc(value, func(match string) string {
parts := templatePattern.FindStringSubmatch(match)
if len(parts) != 2 {
return match
}
replacement, ok := vars[parts[1]]
if !ok {
missing = append(missing, parts[1])
return match
}
return replacement
})
if len(missing) > 0 {
sort.Strings(missing)
return "", fmt.Errorf("missing template variable(s): %s", strings.Join(missing, ", "))
}
return rendered, nil
}
func sortedVars(vars map[string]string) map[string]string {
if len(vars) == 0 {
return nil
}
copyVars := make(map[string]string, len(vars))
for key, value := range vars {
copyVars[key] = value
}
return copyVars
}
func apiBatchErrorMessage(err error) string {
var apiErr *client.APIError
if errors.As(err, &apiErr) {
return apiErr.Message
}
return err.Error()
}

238
cmd/auth/auth.go
View File

@ -2,141 +2,283 @@ package auth
import (
"bufio"
"context"
"errors"
"fmt"
"io"
"os"
"os/signal"
"strings"
"syscall"
"time"
"github.com/spf13/cobra"
"golang.org/x/term"
internalAuth "github.com/gitlink-org/gitlink-cli/internal/auth"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
)
const envTokenVar = "GITLINK_TOKEN"
func NewAuthCmd() *cobra.Command {
var (
storeToken = internalAuth.StoreToken
loadToken = internalAuth.LoadToken
)
func NewAuthCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
cmd := &cobra.Command{
Use: "auth",
Short: "Authentication commands",
Short: tr.T("cmd.auth.short"),
}
cmd.AddCommand(newLoginCmd())
cmd.AddCommand(newLogoutCmd())
cmd.AddCommand(newStatusCmd())
cmd.AddCommand(newLoginCmd(tr))
cmd.AddCommand(newLogoutCmd(tr))
cmd.AddCommand(newStatusCmd(tr))
cmd.AddCommand(newCheckinCmd(tr))
return cmd
}
func newLoginCmd() *cobra.Command {
func newLoginCmd(tr *i18n.Translator) *cobra.Command {
var tokenMode bool
cmd := &cobra.Command{
Use: "login",
Short: "Login to GitLink",
Short: tr.T("cmd.auth.login.short"),
RunE: func(cmd *cobra.Command, args []string) error {
if tokenMode {
return loginWithToken()
return loginWithToken(cmd.InOrStdin(), cmd.OutOrStdout(), tr)
}
return loginWithPassword()
return loginWithPassword(cmd.InOrStdin(), cmd.OutOrStdout(), tr)
},
}
cmd.Flags().BoolVar(&tokenMode, "token", false, "Login by pasting an existing token")
cmd.Flags().BoolVar(&tokenMode, "token", false, tr.T("flag.auth.token"))
return cmd
}
func loginWithPassword() error {
reader := bufio.NewReader(os.Stdin)
fmt.Print("Username/Email/Phone: ")
func loginWithPassword(in io.Reader, out io.Writer, tr *i18n.Translator) error {
reader := bufio.NewReader(in)
if _, err := fmt.Fprint(out, tr.T("prompt.auth.username")); err != nil {
return err
}
username, _ := reader.ReadString('\n')
username = strings.TrimSpace(username)
fmt.Print("Password: ")
passwordBytes, err := term.ReadPassword(int(syscall.Stdin))
if _, err := fmt.Fprint(out, tr.T("prompt.auth.password")); err != nil {
return err
}
passwordBytes, err := readPassword(in, reader)
if err != nil {
return fmt.Errorf("failed to read password: %w", err)
}
fmt.Println()
if _, err := fmt.Fprintln(out); err != nil {
return err
}
password := string(passwordBytes)
result, err := internalAuth.Login(username, password)
if err != nil {
return fmt.Errorf("login failed: %w", err)
return errors.New(tr.Tf("error.auth.login_failed", i18n.Args{"message": err.Error()}))
}
fmt.Printf("✓ Logged in as %s\n", result.Login)
return nil
_, err = fmt.Fprintln(out, tr.Tf("success.auth.logged_in_as", i18n.Args{"login": result.Login}))
return err
}
func loginWithToken() error {
reader := bufio.NewReader(os.Stdin)
fmt.Print("Paste your token: ")
func readPassword(in io.Reader, reader *bufio.Reader) ([]byte, error) {
if file, ok := in.(*os.File); ok {
fd := int(file.Fd())
if term.IsTerminal(fd) {
return term.ReadPassword(fd)
}
}
password, err := reader.ReadString('\n')
if err != nil && err != io.EOF {
return nil, err
}
return []byte(strings.TrimRight(password, "\r\n")), nil
}
func loginWithToken(in io.Reader, out io.Writer, tr *i18n.Translator) error {
reader := bufio.NewReader(in)
if _, err := fmt.Fprint(out, tr.T("prompt.auth.token")); err != nil {
return err
}
token, _ := reader.ReadString('\n')
token = strings.TrimSpace(token)
if token == "" {
return fmt.Errorf("token cannot be empty")
return errors.New(tr.T("error.auth.token_empty"))
}
if err := internalAuth.StoreToken(token); err != nil {
return fmt.Errorf("failed to store token: %w", err)
if err := storeToken(token); err != nil {
return errors.New(tr.Tf("error.auth.store_token_failed", i18n.Args{"message": err.Error()}))
}
fmt.Println("✓ Token saved")
return nil
_, err := fmt.Fprintln(out, tr.T("success.auth.token_saved"))
return err
}
func newLogoutCmd() *cobra.Command {
func newLogoutCmd(tr *i18n.Translator) *cobra.Command {
return &cobra.Command{
Use: "logout",
Short: "Logout from GitLink",
Short: tr.T("cmd.auth.logout.short"),
RunE: func(cmd *cobra.Command, args []string) error {
if err := internalAuth.DeleteToken(); err != nil {
return fmt.Errorf("failed to delete token: %w", err)
return errors.New(tr.Tf("error.auth.delete_token_failed", i18n.Args{"message": err.Error()}))
}
fmt.Println("✓ Logged out")
return nil
_, err := fmt.Fprintln(cmd.OutOrStdout(), tr.T("success.auth.logged_out"))
return err
},
}
}
func newStatusCmd() *cobra.Command {
func newStatusCmd(tr *i18n.Translator) *cobra.Command {
return &cobra.Command{
Use: "status",
Short: "Show authentication status",
Short: tr.T("cmd.auth.status.short"),
RunE: func(cmd *cobra.Command, args []string) error {
out := cmd.OutOrStdout()
// Check env var token first
if envToken := os.Getenv(envTokenVar); envToken != "" {
fmt.Printf("✓ Logged in via %s environment variable\n", envTokenVar)
if _, err := fmt.Fprintln(out, tr.Tf("success.auth.logged_in_via_env", i18n.Args{"env": envTokenVar})); err != nil {
return err
}
}
token, err := internalAuth.LoadToken()
token, err := loadToken()
if err != nil || token == "" {
if os.Getenv(envTokenVar) == "" {
fmt.Println("✗ Not logged in")
fmt.Println(" Run: gitlink-cli auth login")
fmt.Printf(" Or set %s environment variable\n", envTokenVar)
if _, err := fmt.Fprintln(out, tr.T("warning.auth.not_logged_in")); err != nil {
return err
}
if _, err := fmt.Fprintln(out, tr.T("output.auth.login_hint")); err != nil {
return err
}
if _, err := fmt.Fprintln(out, tr.Tf("output.auth.env_hint", i18n.Args{"env": envTokenVar})); err != nil {
return err
}
}
return nil
}
user, err := internalAuth.GetCurrentUser()
if err != nil {
fmt.Printf("✓ Token stored (but cannot verify: %v)\n", err)
return nil
_, err := fmt.Fprintln(out, tr.Tf("warning.auth.token_unverified", i18n.Args{"message": err.Error()}))
return err
}
login, _ := user["login"].(string)
name, _ := user["name"].(string)
if login != "" {
fmt.Printf("✓ Logged in as %s", login)
text := tr.Tf("success.auth.logged_in_as", i18n.Args{"login": login})
if name != "" {
fmt.Printf(" (%s)", name)
text = fmt.Sprintf("%s (%s)", text, name)
}
fmt.Println()
} else {
fmt.Println("✓ Token stored (user info unavailable)")
_, err := fmt.Fprintln(out, text)
return err
}
return nil
_, err = fmt.Fprintln(out, tr.T("warning.auth.user_unavailable"))
return err
},
}
}
func newCheckinCmd(tr *i18n.Translator) *cobra.Command {
var intervalMinutes int
cmd := &cobra.Command{
Use: "checkin",
Short: tr.T("cmd.auth.checkin.short"),
Long: tr.T("cmd.auth.checkin.long"),
RunE: func(cmd *cobra.Command, args []string) error {
return runCheckin(cmd.OutOrStdout(), intervalMinutes, tr)
},
}
cmd.Flags().IntVarP(&intervalMinutes, "time", "t", 30, tr.T("flag.auth.checkin.time"))
return cmd
}
func runCheckin(out io.Writer, intervalMinutes int, tr *i18n.Translator) error {
// Check if user is logged in
token, err := loadToken()
if err != nil || token == "" {
if os.Getenv(envTokenVar) == "" {
return errors.New(tr.T("error.auth.not_logged_in"))
}
}
// Convert minutes to duration
interval := time.Duration(intervalMinutes) * time.Minute
// Print startup message
fmt.Fprintln(out, tr.Tf("output.auth.checkin.start", i18n.Args{"interval": intervalMinutes}))
fmt.Fprintln(out, tr.T("output.auth.checkin.stop_hint"))
// Setup signal handling for graceful shutdown
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
go func() {
<-sigChan
fmt.Fprintln(out, "\n"+tr.T("output.auth.checkin.stopping"))
cancel()
}()
// Create ticker
ticker := time.NewTicker(interval)
defer ticker.Stop()
// Do first check immediately
if err := doCheckin(out, tr, interval); err != nil {
fmt.Fprintln(out, tr.Tf("error.auth.checkin.failed", i18n.Args{"message": err.Error()}))
}
// Then check periodically
for {
select {
case <-ctx.Done():
fmt.Fprintln(out, tr.T("output.auth.checkin.stopped"))
return nil
case <-ticker.C:
if err := doCheckin(out, tr, interval); err != nil {
fmt.Fprintln(out, tr.Tf("error.auth.checkin.failed", i18n.Args{"message": err.Error()}))
}
}
}
}
func doCheckin(out io.Writer, tr *i18n.Translator, interval time.Duration) error {
timestamp := time.Now().Format("2006-01-02 15:04:05")
fmt.Fprintf(out, "[%s] "+tr.T("output.auth.checkin.checking")+"\n", timestamp)
user, err := internalAuth.GetCurrentUser()
if err != nil {
return err
}
login, _ := user["login"].(string)
name, _ := user["name"].(string)
if login != "" {
msg := tr.Tf("output.auth.checkin.success", i18n.Args{"login": login})
if name != "" {
msg = fmt.Sprintf("%s (%s)", msg, name)
}
fmt.Fprintf(out, "[%s] %s\n", timestamp, msg)
} else {
fmt.Fprintf(out, "[%s] "+tr.T("output.auth.checkin.success_no_user")+"\n", timestamp)
}
// Print next refresh time
nextTime := time.Now().Add(interval).Format("2006-01-02 15:04:05")
fmt.Fprintln(out, tr.Tf("output.auth.checkin.interval", i18n.Args{"time": nextTime}))
return nil
}

243
cmd/auth/auth_test.go Normal file
View File

@ -0,0 +1,243 @@
package auth
import (
"errors"
"os"
"path/filepath"
"testing"
"github.com/spf13/cobra"
"github.com/zalando/go-keyring"
internalAuth "github.com/gitlink-org/gitlink-cli/internal/auth"
)
func tempConfigDir(t *testing.T) string {
t.Helper()
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
return dir
}
func TestEnvTokenVar(t *testing.T) {
if envTokenVar != "GITLINK_TOKEN" {
t.Fatalf("envTokenVar = %q, want GITLINK_TOKEN", envTokenVar)
}
}
func TestNewAuthCmd(t *testing.T) {
cmd := NewAuthCmd()
if cmd.Use != "auth" {
t.Fatalf("Use = %q, want auth", cmd.Use)
}
if cmd.Short == "" {
t.Fatal("Short is empty")
}
expectedSubs := map[string]bool{
"login": false, "logout": false, "status": false, "checkin": false,
}
for _, sub := range cmd.Commands() {
if _, ok := expectedSubs[sub.Use]; !ok {
t.Fatalf("unexpected subcommand: %q", sub.Use)
}
if expectedSubs[sub.Use] {
t.Fatalf("duplicate subcommand: %q", sub.Use)
}
expectedSubs[sub.Use] = true
if sub.Short == "" {
t.Fatalf("subcommand %q has empty Short", sub.Use)
}
}
for name, found := range expectedSubs {
if !found {
t.Fatalf("missing subcommand: %q", name)
}
}
}
func TestLoginTokenFlag(t *testing.T) {
cmd := NewAuthCmd()
loginCmd := findSub(cmd, "login")
if loginCmd == nil {
t.Fatal("login subcommand not found")
}
if f := loginCmd.Flags().Lookup("token"); f == nil {
t.Fatal("login command missing --token flag")
}
}
func TestStatusCmdNotLoggedIn(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
_ = internalAuth.DeleteToken()
cmd := findSub(NewAuthCmd(), "status")
if cmd == nil {
t.Fatal("status subcommand not found")
}
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("status error: %v", err)
}
}
func TestStatusCmdEnvToken(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "env-token-123")
_ = internalAuth.DeleteToken()
cmd := findSub(NewAuthCmd(), "status")
cmd.RunE(cmd, nil)
}
func TestStatusCmdStoredToken(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
dir := tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
os.MkdirAll(dir, 0700)
os.WriteFile(filepath.Join(dir, "credentials"), []byte("cookie:test=abc"), 0600)
cmd := findSub(NewAuthCmd(), "status")
cmd.RunE(cmd, nil)
}
func TestStatusCmdEnvAndStoredToken(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
dir := tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "env-token")
os.MkdirAll(dir, 0700)
os.WriteFile(filepath.Join(dir, "credentials"), []byte("stored-token"), 0600)
cmd := findSub(NewAuthCmd(), "status")
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("status error: %v", err)
}
}
func TestStatusCmdStoredTokenButLoadFails(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
// Do not create credentials; LoadToken should return empty.
cmd := findSub(NewAuthCmd(), "status")
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("status error: %v", err)
}
}
func TestLogoutCmdNoStoredToken(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
// Do not create credentials; logout should be idempotent.
cmd := findSub(NewAuthCmd(), "logout")
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("logout should succeed without stored token: %v", err)
}
}
func TestLogoutCmd(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
dir := tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
// Store a token first so DeleteToken has something to delete
os.MkdirAll(dir, 0700)
os.WriteFile(filepath.Join(dir, "credentials"), []byte("some-token"), 0600)
cmd := findSub(NewAuthCmd(), "logout")
if cmd == nil {
t.Fatal("logout subcommand not found")
}
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("logout error: %v", err)
}
}
func TestLoginWithToken(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
dir := tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
// Mock stdin
oldStdin := os.Stdin
r, w, _ := os.Pipe()
os.Stdin = r
defer func() { os.Stdin = oldStdin }()
go func() {
w.Write([]byte("test-token-123\n"))
w.Close()
}()
cmd := findSub(NewAuthCmd(), "login")
if cmd == nil {
t.Fatal("login subcommand not found")
}
cmd.Flags().Set("token", "true")
err := cmd.RunE(cmd, nil)
if err != nil {
t.Fatalf("login --token error: %v", err)
}
// Verify token was saved to file
data, err := os.ReadFile(filepath.Join(dir, "credentials"))
if err != nil {
t.Fatalf("read credentials: %v", err)
}
if string(data) != "test-token-123" {
t.Fatalf("token = %q, want test-token-123", string(data))
}
}
func TestLoginWithTokenEmpty(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
oldStdin := os.Stdin
r, w, _ := os.Pipe()
os.Stdin = r
defer func() { os.Stdin = oldStdin }()
go func() {
w.Write([]byte("\n"))
w.Close()
}()
cmd := findSub(NewAuthCmd(), "login")
cmd.Flags().Set("token", "true")
err := cmd.RunE(cmd, nil)
if err == nil {
t.Fatal("expected error for empty token")
}
}
func TestLoginWithPasswordNoTerminal(t *testing.T) {
keyring.MockInitWithError(errors.New("keychain unavailable"))
tempConfigDir(t)
t.Setenv("GITLINK_TOKEN", "")
// term.ReadPassword will fail because test has no terminal
cmd := findSub(NewAuthCmd(), "login")
// Don't set --token, so it goes to loginWithPassword
err := cmd.RunE(cmd, nil)
if err == nil {
t.Fatal("expected error when terminal unavailable (ReadPassword fails)")
}
}
func findSub(cmd *cobra.Command, name string) *cobra.Command {
for _, sub := range cmd.Commands() {
if sub.Use == name {
return sub
}
}
return nil
}

58
cmd/browse/browse.go Normal file
View File

@ -0,0 +1,58 @@
package browse
import (
"fmt"
"os/exec"
"runtime"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/internal/context"
)
// NewBrowseCmd creates the browse command for opening GitLink pages in a browser.
func NewBrowseCmd() *cobra.Command {
return &cobra.Command{
Use: "browse [resource]",
Short: "在浏览器中打开 GitLink 页面",
Long: `打开当前仓库（或指定资源）的 GitLink 页面。
如果不带参数，打开当前仓库主页。
资源格式: issues/42, pulls/42, wiki
浏览器打开命令:
- macOS: open
- Windows: start
- Linux: xdg-open`,
Example: ` gitlink-cli browse
gitlink-cli browse issues/42
gitlink-cli browse pulls/128
gitlink-cli browse wiki`,
Args: cobra.MaximumNArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
owner, repo, err := context.ResolveOwnerRepo("", "")
if err != nil {
return fmt.Errorf("无法推断仓库信息: %w", err)
}
url := fmt.Sprintf("https://gitlink.org.cn/%s/%s", owner, repo)
if len(args) > 0 {
url += "/" + args[0]
}
fmt.Printf("正在打开: %s\n", url)
return openBrowser(url)
},
}
}
func openBrowser(url string) error {
var cmd *exec.Cmd
switch runtime.GOOS {
case "darwin":
cmd = exec.Command("open", url)
case "windows":
cmd = exec.Command("cmd", "/c", "start", url)
default:
cmd = exec.Command("xdg-open", url)
}
return cmd.Start()
}

58
cmd/browse/browse_test.go Normal file
View File

@ -0,0 +1,58 @@
package browse
import (
"strings"
"testing"
)
func TestNewBrowseCmd(t *testing.T) {
cmd := NewBrowseCmd()
if cmd.Use != "browse [resource]" {
t.Errorf("expected Use 'browse [resource]', got %s", cmd.Use)
}
if cmd.Short == "" {
t.Error("Short description should not be empty")
}
if cmd.Long == "" {
t.Error("Long description should not be empty")
}
}
func TestBrowseCmdHasCorrectArgs(t *testing.T) {
cmd := NewBrowseCmd()
// MaximumNArgs(1) should allow 0 or 1 args
if err := cmd.Args(cmd, []string{}); err != nil {
t.Errorf("should accept 0 args: %v", err)
}
if err := cmd.Args(cmd, []string{"issues/42"}); err != nil {
t.Errorf("should accept 1 arg: %v", err)
}
if err := cmd.Args(cmd, []string{"a", "b"}); err == nil {
t.Error("should reject more than 1 arg")
}
}
func TestBrowseCmdSubcommandStructure(t *testing.T) {
cmd := NewBrowseCmd()
// browse 不应该有子命令
if cmd.HasSubCommands() {
t.Error("browse should not have subcommands")
}
}
func TestBrowseCmdExample(t *testing.T) {
cmd := NewBrowseCmd()
if cmd.Example == "" {
t.Error("Example should not be empty")
}
if !strings.Contains(cmd.Example, "browse") {
t.Error("Example should contain 'browse'")
}
}
func TestOpenBrowserReturnsNoError(t *testing.T) {
// openBrowser 在所有平台都应该返回 nil 或一个 error
// 在无头环境下可能会失败，但不应该 panic
_ = openBrowser("https://gitlink.org.cn")
// 只要不 panic 就行
}

68
cmd/cmd_test.go Normal file
View File

@ -0,0 +1,68 @@
package cmd
import (
"bytes"
"strings"
"testing"
)
func TestNewRootCmdDefaults(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test"}, nil)
if err != nil {
t.Fatal(err)
}
if root.Use != "gitlink-cli" {
t.Fatalf("Use = %q", root.Use)
}
if !root.SilenceUsage {
t.Fatal("expected SilenceUsage=true")
}
}
func TestRootHelp(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"--help"}}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("help command error: %v", err)
}
}
func TestVersionCmd(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"version"}}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("version command error: %v", err)
}
if got := strings.TrimSpace(out.String()); got != "gitlink-cli test" {
t.Fatalf("version output = %q", got)
}
}
func TestRootCmdHasSubcommands(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test"}, nil)
if err != nil {
t.Fatal(err)
}
names := map[string]bool{}
for _, sub := range root.Commands() {
names[sub.Name()] = true
}
for _, want := range []string{"auth", "completion", "config", "doctor", "version"} {
if !names[want] {
t.Fatalf("missing subcommand: %s", want)
}
}
if len(root.Commands()) < 4 {
t.Fatalf("expected at least 4 subcommands, got %d", len(root.Commands()))
}
}

1
cmd/cmdutil/globals.go
View File

@ -6,4 +6,5 @@ var (
Repo string
Format string
Debug bool
Lang string
)

71
cmd/completion_test.go Normal file
View File

@ -0,0 +1,71 @@
package cmd
import (
"bytes"
"strings"
"testing"
)
func TestCompletionCmdGeneratesSupportedShells(t *testing.T) {
cases := []struct {
shell string
want string
}{
{shell: "bash", want: "__gitlink-cli"},
{shell: "zsh", want: "#compdef gitlink-cli"},
{shell: "fish", want: "complete -c gitlink-cli"},
{shell: "powershell", want: "Register-ArgumentCompleter"},
}
for _, tc := range cases {
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"completion", tc.shell}}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("%s completion error: %v", tc.shell, err)
}
if !strings.Contains(out.String(), tc.want) {
t.Fatalf("%s completion missing %q, got:\n%s", tc.shell, tc.want, out.String()[:min(len(out.String()), 400)])
}
}
}
func TestCompletionCmdNoDescriptions(t *testing.T) {
root, err := NewRootCmd(RootOptions{
Version: "test",
Args: []string{"completion", "bash", "--no-descriptions"},
}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
if strings.Contains(out.String(), "GitLink CLI - command-line tool for GitLink") {
t.Fatalf("expected descriptions to be omitted")
}
}
func TestCompletionCmdRejectsUnsupportedShell(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"completion", "xonsh"}}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
err = root.Execute()
if err == nil {
t.Fatal("expected unsupported shell error")
}
if !strings.Contains(err.Error(), "invalid argument") {
t.Fatalf("expected invalid argument error, got %q", err.Error())
}
}

98
cmd/config/config.go
View File

@ -1,59 +1,80 @@
package config
import (
"errors"
"fmt"
"github.com/spf13/cobra"
internalConfig "github.com/gitlink-org/gitlink-cli/internal/config"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
)
func NewConfigCmd() *cobra.Command {
func NewConfigCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
cmd := &cobra.Command{
Use: "config",
Short: "Manage gitlink-cli configuration",
Short: tr.T("cmd.config.short"),
}
cmd.AddCommand(newInitCmd())
cmd.AddCommand(newSetCmd())
cmd.AddCommand(newGetCmd())
cmd.AddCommand(newListCmd())
cmd.AddCommand(newInitCmd(tr))
cmd.AddCommand(newSetCmd(tr))
cmd.AddCommand(newGetCmd(tr))
cmd.AddCommand(newListCmd(tr))
return cmd
}
func newInitCmd() *cobra.Command {
func newInitCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
return &cobra.Command{
Use: "init",
Short: "Initialize configuration file",
Short: tr.T("cmd.config.init.short"),
RunE: func(cmd *cobra.Command, args []string) error {
cfg := internalConfig.DefaultConfig()
if err := internalConfig.Save(cfg); err != nil {
return fmt.Errorf("failed to save config: %w", err)
return errors.New(tr.Tf("error.config.save_failed", i18n.Args{"message": err.Error()}))
}
fmt.Printf("✓ Config initialized at %s\n", internalConfig.ConfigPath())
return nil
_, err := fmt.Fprintln(cmd.OutOrStdout(), tr.Tf("success.config.initialized", i18n.Args{"path": internalConfig.ConfigPath()}))
return err
},
}
}
func newSetCmd() *cobra.Command {
func newSetCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
return &cobra.Command{
Use: "set <key> <value>",
Short: "Set a configuration value",
Short: tr.T("cmd.config.set.short"),
Args: cobra.ExactArgs(2),
RunE: func(cmd *cobra.Command, args []string) error {
if err := internalConfig.Set(args[0], args[1]); err != nil {
return err
}
fmt.Printf("✓ %s = %s\n", args[0], args[1])
return nil
_, err := fmt.Fprintln(cmd.OutOrStdout(), tr.Tf("success.config.set", i18n.Args{
"key": args[0],
"value": args[1],
}))
return err
},
}
}
func newGetCmd() *cobra.Command {
func newGetCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
return &cobra.Command{
Use: "get <key>",
Short: "Get a configuration value",
Short: tr.T("cmd.config.get.short"),
Args: cobra.ExactArgs(1),
RunE: func(cmd *cobra.Command, args []string) error {
val, err := internalConfig.Get(args[0])
@ -61,30 +82,49 @@ func newGetCmd() *cobra.Command {
return err
}
if val == "" {
fmt.Printf("%s: (not set)\n", args[0])
} else {
fmt.Printf("%s: %s\n", args[0], val)
_, err := fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n", args[0], tr.T("output.config.not_set"))
return err
}
return nil
_, err = fmt.Fprintf(cmd.OutOrStdout(), "%s: %s\n", args[0], val)
return err
},
}
}
func newListCmd() *cobra.Command {
func newListCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
return &cobra.Command{
Use: "list",
Short: "List all configuration values",
Short: tr.T("cmd.config.list.short"),
RunE: func(cmd *cobra.Command, args []string) error {
cfg, err := internalConfig.Load()
if err != nil {
return err
}
fmt.Printf("base_url: %s\n", cfg.BaseURL)
fmt.Printf("default_format: %s\n", cfg.Format)
fmt.Printf("editor: %s\n", cfg.Editor)
fmt.Printf("pager: %s\n", cfg.Pager)
fmt.Printf("\nConfig file: %s\n", internalConfig.ConfigPath())
return nil
out := cmd.OutOrStdout()
if _, err := fmt.Fprintf(out, "base_url: %s\n", cfg.BaseURL); err != nil {
return err
}
if _, err := fmt.Fprintf(out, "default_format: %s\n", cfg.Format); err != nil {
return err
}
if _, err := fmt.Fprintf(out, "editor: %s\n", cfg.Editor); err != nil {
return err
}
if _, err := fmt.Fprintf(out, "pager: %s\n", cfg.Pager); err != nil {
return err
}
if _, err := fmt.Fprintf(out, "lang: %s\n", cfg.Lang); err != nil {
return err
}
if _, err := fmt.Fprintln(out); err != nil {
return err
}
_, err = fmt.Fprintln(out, tr.Tf("output.config.file", i18n.Args{"path": internalConfig.ConfigPath()}))
return err
},
}
}

217
cmd/config/config_test.go Normal file
View File

@ -0,0 +1,217 @@
package config
import (
"os"
"testing"
"github.com/spf13/cobra"
)
func TestNewConfigCmd(t *testing.T) {
cmd := NewConfigCmd()
if cmd.Use != "config" {
t.Fatalf("Use = %q, want config", cmd.Use)
}
if cmd.Short == "" {
t.Fatal("Short is empty")
}
expectedSubs := map[string]bool{
"init": false, "set <key> <value>": false, "get <key>": false, "list": false,
}
for _, sub := range cmd.Commands() {
if _, ok := expectedSubs[sub.Use]; !ok {
t.Fatalf("unexpected subcommand: %q", sub.Use)
}
if expectedSubs[sub.Use] {
t.Fatalf("duplicate subcommand: %q", sub.Use)
}
expectedSubs[sub.Use] = true
if sub.Short == "" {
t.Fatalf("subcommand %q has empty Short", sub.Use)
}
}
for name, found := range expectedSubs {
if !found {
t.Fatalf("missing subcommand: %q", name)
}
}
}
func TestSetCmdArgs(t *testing.T) {
cmd := findSub(NewConfigCmd(), "set <key> <value>")
if cmd == nil {
t.Fatal("set subcommand not found")
}
if cmd.Args == nil {
t.Fatal("set should require exact args")
}
}
func TestGetCmdArgs(t *testing.T) {
cmd := findSub(NewConfigCmd(), "get <key>")
if cmd == nil {
t.Fatal("get subcommand not found")
}
if cmd.Args == nil {
t.Fatal("get should require exact args")
}
}
func TestConfigInitRun(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
cmd := findSub(NewConfigCmd(), "init")
cmd.SetArgs([]string{})
if err := cmd.Execute(); err != nil {
t.Fatalf("init error: %v", err)
}
}
func TestConfigSetAndGet(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
// Init first
initCmd := findSub(NewConfigCmd(), "init")
initCmd.SetArgs([]string{})
if err := initCmd.Execute(); err != nil {
t.Fatalf("init error: %v", err)
}
// Set a value
setCmd := findSub(NewConfigCmd(), "set <key> <value>")
setCmd.SetArgs([]string{"base_url", "https://example.com"})
if err := setCmd.Execute(); err != nil {
t.Fatalf("set error: %v", err)
}
// Get it back
getCmd := findSub(NewConfigCmd(), "get <key>")
getCmd.SetArgs([]string{"base_url"})
if err := getCmd.Execute(); err != nil {
t.Fatalf("get error: %v", err)
}
}
func TestConfigGetNotSet(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
os.WriteFile(dir+"/config.yaml", []byte("base_url: https://example.com\n"), 0644)
getCmd := findSub(NewConfigCmd(), "get <key>")
getCmd.SetArgs([]string{"editor"})
if err := getCmd.Execute(); err != nil {
t.Fatalf("get not-set error: %v", err)
}
}
func TestConfigList(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
initCmd := findSub(NewConfigCmd(), "init")
initCmd.SetArgs([]string{})
if err := initCmd.Execute(); err != nil {
t.Fatalf("init error: %v", err)
}
listCmd := findSub(NewConfigCmd(), "list")
listCmd.SetArgs([]string{})
if err := listCmd.Execute(); err != nil {
t.Fatalf("list error: %v", err)
}
}
func TestConfigInitRunE(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
cmd := newInitCmd()
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("init RunE error: %v", err)
}
}
func TestConfigSetRunE(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
// Init first so config file exists
initCmd := newInitCmd()
if err := initCmd.RunE(initCmd, nil); err != nil {
t.Fatalf("init error: %v", err)
}
cmd := newSetCmd()
if err := cmd.RunE(cmd, []string{"base_url", "https://example.com"}); err != nil {
t.Fatalf("set RunE error: %v", err)
}
}
func TestConfigSetRunENoConfig(t *testing.T) {
// Set without init should still work — Load returns defaults, Save creates dir
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
cmd := newSetCmd()
if err := cmd.RunE(cmd, []string{"base_url", "https://example.com"}); err != nil {
t.Fatalf("set RunE error: %v", err)
}
}
func TestConfigGetRunE(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
initCmd := newInitCmd()
initCmd.RunE(initCmd, nil)
cmd := newGetCmd()
if err := cmd.RunE(cmd, []string{"base_url"}); err != nil {
t.Fatalf("get RunE error: %v", err)
}
}
func TestConfigGetRunENotSet(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
os.WriteFile(dir+"/config.yaml", []byte("base_url: https://example.com\n"), 0644)
cmd := newGetCmd()
if err := cmd.RunE(cmd, []string{"editor"}); err != nil {
t.Fatalf("get RunE not-set error: %v", err)
}
}
func TestConfigListRunE(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
initCmd := newInitCmd()
initCmd.RunE(initCmd, nil)
cmd := newListCmd()
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("list RunE error: %v", err)
}
}
func TestConfigListRunENoConfig(t *testing.T) {
dir := t.TempDir()
t.Setenv("GITLINK_CONFIG_DIR", dir)
// Don't init — Load returns defaults for missing file, so this should work
cmd := newListCmd()
if err := cmd.RunE(cmd, nil); err != nil {
t.Fatalf("list RunE error: %v", err)
}
}
func findSub(cmd *cobra.Command, name string) *cobra.Command {
for _, sub := range cmd.Commands() {
if sub.Use == name {
return sub
}
}
return nil
}

208
cmd/do.go Normal file
View File

@ -0,0 +1,208 @@
package cmd
import (
"fmt"
"os"
"os/exec"
"strings"
"github.com/spf13/cobra"
)
// NLCommand 自然语言命令路由
// 用法: gitlink-cli do "列出issue" 或 gitlink-cli do wiki
// 关键词匹配 → 推荐命令 + 显示参数 + 简短/完全示例
// 输入模块名（如 wiki）→ 列出该模块全部命令
func newDoCmd() *cobra.Command {
return &cobra.Command{
Use: `do "自然语言描述或模块名"`,
Short: "Natural language command helper (e.g. do \"list issues\" or do wiki)",
Long: `用自然语言描述你想做的事，自动匹配命令并显示参数。
也可以直接输入模块名查看该模块全部命令。
示例:
gitlink-cli do 列出issue # 匹配到 issue +list
gitlink-cli do wiki # 列出 wiki 全部命令
gitlink-cli do 创建标签 # 匹配到 label +create`,
Args: cobra.MinimumNArgs(1),
Run: func(cmd *cobra.Command, args []string) {
input := strings.ToLower(strings.Join(args, " "))
input = strings.TrimSpace(input)
exePath, _ := os.Executable()
// 1. 先检查是否是模块名（如 wiki/issue/pr/label...）
modules := []string{"wiki", "issue", "pr", "label", "notification", "snippet",
"repo", "release", "branch", "member", "milestone", "webhook",
"ci", "search", "org", "user", "compare", "workflow"}
for _, mod := range modules {
if input == mod {
fmt.Printf("📦 %s 模块全部命令：\n", mod)
fmt.Println(strings.Repeat("=", 50))
helpCmd := exec.Command(exePath, mod, "--help")
helpCmd.Stdout = os.Stdout
helpCmd.Stderr = os.Stderr
helpCmd.Run()
fmt.Println(strings.Repeat("=", 50))
fmt.Println("\n💡 选择一个命令运行，例如：")
fmt.Printf(" gitlink-cli %s +list\n", mod)
fmt.Printf(" gitlink-cli %s +list --owner ylly --repo gitlink-cli --format json （完全版）\n", mod)
return
}
}
// 2. 关键词匹配
matched := matchNL(input)
if matched == "" {
fmt.Println("❌ 未识别。试试这些：")
fmt.Println(" 输入模块名（wiki/issue/pr/label/notification/snippet/repo...）")
fmt.Println(" 或描述操作（列出issue/创建标签/登录/搜索仓库...）")
fmt.Println("\n示例:")
fmt.Println(" gitlink-cli do wiki # 查看 wiki 全部命令")
fmt.Println(" gitlink-cli do 列出issue # 匹配 issue +list")
os.Exit(1)
}
parts := strings.Fields(matched)
fmt.Printf("✅ 匹配到命令: %s\n\n", matched)
// 显示该命令的 --help
if len(parts) >= 2 {
group := parts[0]
sub := parts[1]
fmt.Println("📋 命令参数说明：")
fmt.Println(strings.Repeat("-", 50))
helpCmd := exec.Command(exePath, group, sub, "--help")
helpCmd.Stdout = os.Stdout
helpCmd.Stderr = os.Stderr
helpCmd.Run()
fmt.Println(strings.Repeat("-", 50))
// 显示简短版 + 完全版示例
fmt.Println("\n💡 命令示例：")
fmt.Printf(" 简短版（在自己的仓库目录里）：\n")
fmt.Printf(" gitlink-cli %s\n", matched)
fmt.Printf(" 完全版（任何目录都能用）：\n")
fmt.Printf(" gitlink-cli %s --owner ylly --repo gitlink-cli --format json\n", matched)
} else {
// auth login / auth status 等无子命令的
fmt.Printf("\n💡 运行：gitlink-cli %s\n", matched)
}
},
}
}
// matchNL 关键词匹配自然语言 → 命令
func matchNL(input string) string {
type rule struct {
keywords []string
cmd string
}
rules := []rule{
// Issue
{[]string{"issue", "疑修", "问题", "list", "列", "查看"}, "issue +list"},
{[]string{"issue", "create", "新建", "创建", "提"}, "issue +create"},
{[]string{"issue", "view", "详情", "看"}, "issue +view"},
{[]string{"issue", "close", "关闭"}, "issue +close"},
{[]string{"issue", "update", "更新", "修改"}, "issue +update"},
{[]string{"issue", "comment", "评论", "回复"}, "issue +comment"},
{[]string{"issue", "batch", "批量", "关闭"}, "issue +batch-close"},
{[]string{"issue", "assigners", "负责人", "分配", "候选"}, "issue +assigners"},
{[]string{"issue", "authors", "作者"}, "issue +authors"},
// PR
{[]string{"pr", "pull", "合并请求", "merge", "list"}, "pr +list"},
{[]string{"pr", "create", "新建", "提交"}, "pr +create"},
{[]string{"pr", "view", "详情", "看"}, "pr +view"},
{[]string{"pr", "merge", "合并"}, "pr +merge"},
{[]string{"pr", "diff", "差异", "变更"}, "pr +diff"},
{[]string{"pr", "files", "文件", "变更文件"}, "pr +files"},
{[]string{"pr", "review", "审查", "review"}, "pr +review"},
{[]string{"pr", "close", "关闭"}, "pr +close"},
{[]string{"pr", "reopen", "重开", "重新打开"}, "pr +reopen"},
// Label
{[]string{"label", "tag", "标签", "list"}, "label +list"},
{[]string{"label", "tag", "标签", "create", "新建", "创建"}, "label +create"},
{[]string{"label", "tag", "标签", "update", "更新", "修改"}, "label +update"},
{[]string{"label", "tag", "标签", "delete", "删除"}, "label +delete"},
{[]string{"label", "tag", "标签", "batch", "批量"}, "label +batch-create"},
// Wiki
{[]string{"wiki", "文档", "知识库", "list"}, "wiki +list"},
{[]string{"wiki", "文档", "create", "新建", "创建"}, "wiki +create"},
{[]string{"wiki", "文档", "view", "查看"}, "wiki +view"},
{[]string{"wiki", "文档", "update", "更新"}, "wiki +update"},
{[]string{"wiki", "文档", "delete", "删除"}, "wiki +delete"},
// Release
{[]string{"release", "发布", "版本", "list"}, "release +list"},
{[]string{"release", "发布", "create", "新建"}, "release +create"},
{[]string{"release", "发布", "view", "查看"}, "release +view"},
// Repo
{[]string{"repo", "仓库", "info", "信息"}, "repo +info"},
{[]string{"repo", "仓库", "create", "新建", "创建"}, "repo +create"},
{[]string{"repo", "仓库", "readme"}, "repo +readme"},
{[]string{"repo", "仓库", "fork", "复刻"}, "repo +fork"},
{[]string{"repo", "仓库", "list", "列"}, "repo +list"},
// Auth
{[]string{"auth", "login", "登录", "认证"}, "auth login"},
{[]string{"auth", "status", "状态"}, "auth status"},
// Snippet
{[]string{"snippet", "片段", "代码片段", "list"}, "snippet +list"},
{[]string{"snippet", "片段", "代码片段", "create", "新建", "保存"}, "snippet +create"},
{[]string{"snippet", "片段", "代码片段", "view", "查看"}, "snippet +view"},
{[]string{"snippet", "片段", "代码片段", "delete", "删除"}, "snippet +delete"},
// Notification
{[]string{"notification", "通知", "消息", "list"}, "notification +list"},
{[]string{"notification", "通知", "read", "已读"}, "notification +read"},
{[]string{"notification", "通知", "delete", "删除"}, "notification +delete"},
// Member
{[]string{"member", "成员", "list"}, "member +list"},
{[]string{"member", "成员", "add", "添加"}, "member +add"},
{[]string{"member", "成员", "invite", "邀请"}, "member +invite-link"},
// Branch
{[]string{"branch", "分支", "list"}, "branch +list"},
{[]string{"branch", "分支", "create", "新建"}, "branch +create"},
// CI
{[]string{"ci", "构建", "流水线", "list"}, "ci +list"},
{[]string{"ci", "构建", "log", "日志"}, "ci +logs"},
// Search
{[]string{"search", "搜索", "查找", "repos"}, "search +repos"},
{[]string{"search", "搜索", "查找", "user", "用户"}, "search +users"},
// Milestone
{[]string{"milestone", "里程碑", "list"}, "milestone +list"},
{[]string{"milestone", "里程碑", "create", "新建"}, "milestone +create"},
// Webhook
{[]string{"webhook", "钩子", "list"}, "webhook +list"},
{[]string{"webhook", "钩子", "create", "新建"}, "webhook +create"},
}
bestMatch := ""
bestScore := 0
for _, r := range rules {
score := 0
for _, kw := range r.keywords {
if strings.Contains(input, kw) {
score++
}
}
if score >= 2 && score > bestScore {
bestScore = score
bestMatch = r.cmd
}
}
// 降级：只匹配1个关键词
if bestMatch == "" {
for _, r := range rules {
for _, kw := range r.keywords {
if strings.Contains(input, kw) {
bestMatch = r.cmd
break
}
}
if bestMatch != "" {
break
}
}
}
return bestMatch
}

319
cmd/doctor/doctor.go Normal file
View File

@ -0,0 +1,319 @@
package doctor
import (
"fmt"
"net/url"
"os"
"strings"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
internalAuth "github.com/gitlink-org/gitlink-cli/internal/auth"
internalConfig "github.com/gitlink-org/gitlink-cli/internal/config"
repoContext "github.com/gitlink-org/gitlink-cli/internal/context"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
"github.com/gitlink-org/gitlink-cli/internal/output"
)
const (
statusOK = "ok"
statusWarning = "warning"
statusError = "error"
statusSkipped = "skipped"
)
var (
loadConfig = internalConfig.Load
loadToken = internalAuth.LoadToken
getCurrentUser = internalAuth.GetCurrentUser
resolveOwnerRepo = repoContext.ResolveOwnerRepo
statFile = os.Stat
lookupEnv = os.LookupEnv
)
type Report struct {
OK bool `json:"ok"`
Summary Summary `json:"summary"`
Checks []Check `json:"checks"`
Actions []string `json:"actions,omitempty"`
}
type Summary struct {
OK int `json:"ok"`
Warning int `json:"warning"`
Error int `json:"error"`
Skipped int `json:"skipped"`
Total int `json:"total"`
}
type Check struct {
Name string `json:"name"`
Status string `json:"status"`
Message string `json:"message"`
Suggestion string `json:"suggestion,omitempty"`
Details map[string]interface{} `json:"details,omitempty"`
}
func NewDoctorCmd(translators ...*i18n.Translator) *cobra.Command {
tr := i18n.Default()
if len(translators) > 0 && translators[0] != nil {
tr = translators[0]
}
var skipNetwork bool
cmd := &cobra.Command{
Use: "doctor",
Short: tr.T("cmd.doctor.short"),
Long: tr.T("cmd.doctor.long"),
RunE: func(cmd *cobra.Command, args []string) error {
report := Run(skipNetwork, tr)
return output.PrintTo(cmd.OutOrStdout(), output.SuccessEnvelope(report, nil), resolveFormat())
},
}
cmd.Flags().BoolVar(&skipNetwork, "skip-network", false, tr.T("flag.doctor.skip_network"))
return cmd
}
func Run(skipNetwork bool, tr *i18n.Translator) Report {
if tr == nil {
tr = i18n.Default()
}
checks := make([]Check, 0, 5)
cfg, cfgErr := loadConfig()
checks = append(checks, checkConfigFile(tr, cfgErr))
checks = append(checks, checkConfigValues(tr, cfg, cfgErr))
checks = append(checks, checkAuthToken(tr))
checks = append(checks, checkRepoContext(tr))
checks = append(checks, checkAuthenticatedUser(tr, skipNetwork, cfgErr))
report := Report{OK: true, Checks: checks}
seenActions := map[string]bool{}
for _, check := range checks {
report.Summary.Total++
switch check.Status {
case statusOK:
report.Summary.OK++
case statusWarning:
report.Summary.Warning++
case statusError:
report.OK = false
report.Summary.Error++
case statusSkipped:
report.Summary.Skipped++
}
if check.Suggestion != "" && !seenActions[check.Suggestion] {
report.Actions = append(report.Actions, check.Suggestion)
seenActions[check.Suggestion] = true
}
}
return report
}
func checkConfigFile(tr *i18n.Translator, cfgErr error) Check {
path := internalConfig.ConfigPath()
info, err := statFile(path)
if err != nil {
if os.IsNotExist(err) {
return Check{
Name: "config_file",
Status: statusWarning,
Message: tr.T("output.doctor.config_file.missing"),
Suggestion: "gitlink-cli config init",
Details: map[string]interface{}{"path": path},
}
}
return Check{
Name: "config_file",
Status: statusError,
Message: tr.Tf("output.doctor.config_file.unreadable", i18n.Args{"message": err.Error()}),
Suggestion: tr.T("output.doctor.suggestion.check_config_permissions"),
Details: map[string]interface{}{"path": path},
}
}
if cfgErr != nil {
return Check{
Name: "config_file",
Status: statusError,
Message: tr.Tf("output.doctor.config_file.invalid", i18n.Args{"message": cfgErr.Error()}),
Suggestion: tr.T("output.doctor.suggestion.fix_config_yaml"),
Details: map[string]interface{}{"path": path},
}
}
return Check{
Name: "config_file",
Status: statusOK,
Message: tr.T("output.doctor.config_file.ok"),
Details: map[string]interface{}{
"path": path,
"size": info.Size(),
},
}
}
func checkConfigValues(tr *i18n.Translator, cfg *internalConfig.Config, cfgErr error) Check {
if cfgErr != nil || cfg == nil {
return Check{
Name: "config_values",
Status: statusSkipped,
Message: tr.T("output.doctor.config_values.skipped"),
Suggestion: tr.T("output.doctor.suggestion.fix_config_yaml"),
}
}
details := map[string]interface{}{
"base_url": cfg.BaseURL,
"default_format": cfg.Format,
}
if err := validateBaseURL(cfg.BaseURL); err != nil {
return Check{
Name: "config_values",
Status: statusError,
Message: tr.Tf("output.doctor.config_values.bad_base_url", i18n.Args{"message": err.Error()}),
Suggestion: "gitlink-cli config set base_url https://www.gitlink.org.cn/api",
Details: details,
}
}
if !validFormat(cfg.Format) {
return Check{
Name: "config_values",
Status: statusWarning,
Message: tr.Tf("output.doctor.config_values.bad_format", i18n.Args{"format": cfg.Format}),
Suggestion: "gitlink-cli config set default_format table",
Details: details,
}
}
return Check{
Name: "config_values",
Status: statusOK,
Message: tr.T("output.doctor.config_values.ok"),
Details: details,
}
}
func checkAuthToken(tr *i18n.Translator) Check {
if token, ok := lookupEnv("GITLINK_TOKEN"); ok && strings.TrimSpace(token) != "" {
return Check{
Name: "auth_token",
Status: statusOK,
Message: tr.T("output.doctor.auth_token.env"),
Details: map[string]interface{}{"source": "env"},
}
}
token, err := loadToken()
if err != nil || strings.TrimSpace(token) == "" {
return Check{
Name: "auth_token",
Status: statusWarning,
Message: tr.T("output.doctor.auth_token.missing"),
Suggestion: "gitlink-cli auth login",
}
}
source := "token"
if strings.HasPrefix(token, "cookie:") {
source = "cookie"
}
return Check{
Name: "auth_token",
Status: statusOK,
Message: tr.T("output.doctor.auth_token.stored"),
Details: map[string]interface{}{"source": source},
}
}
func checkRepoContext(tr *i18n.Translator) Check {
owner, repo, err := resolveOwnerRepo(cmdutil.Owner, cmdutil.Repo)
if err != nil {
return Check{
Name: "repo_context",
Status: statusWarning,
Message: tr.Tf("output.doctor.repo_context.missing", i18n.Args{"message": err.Error()}),
Suggestion: tr.T("output.doctor.suggestion.pass_owner_repo"),
}
}
return Check{
Name: "repo_context",
Status: statusOK,
Message: tr.Tf("output.doctor.repo_context.ok", i18n.Args{"owner": owner, "repo": repo}),
Details: map[string]interface{}{
"owner": owner,
"repo": repo,
},
}
}
func checkAuthenticatedUser(tr *i18n.Translator, skipNetwork bool, cfgErr error) Check {
if skipNetwork {
return Check{
Name: "api_auth",
Status: statusSkipped,
Message: tr.T("output.doctor.api_auth.skipped"),
}
}
if cfgErr != nil {
return Check{
Name: "api_auth",
Status: statusSkipped,
Message: tr.T("output.doctor.api_auth.config_skipped"),
Suggestion: tr.T("output.doctor.suggestion.fix_config_yaml"),
}
}
user, err := getCurrentUser()
if err != nil {
return Check{
Name: "api_auth",
Status: statusError,
Message: tr.Tf("output.doctor.api_auth.failed", i18n.Args{"message": err.Error()}),
Suggestion: "gitlink-cli auth login",
}
}
login, _ := user["login"].(string)
if login == "" {
return Check{
Name: "api_auth",
Status: statusWarning,
Message: tr.T("output.doctor.api_auth.no_login"),
Suggestion: tr.T("output.doctor.suggestion.check_token"),
}
}
return Check{
Name: "api_auth",
Status: statusOK,
Message: tr.Tf("output.doctor.api_auth.ok", i18n.Args{"login": login}),
Details: map[string]interface{}{
"login": login,
},
}
}
func validateBaseURL(value string) error {
u, err := url.Parse(value)
if err != nil {
return err
}
if u.Scheme != "http" && u.Scheme != "https" {
return fmt.Errorf("scheme must be http or https")
}
if u.Host == "" {
return fmt.Errorf("host is required")
}
return nil
}
func validFormat(value string) bool {
switch value {
case "json", "table", "yaml":
return true
default:
return false
}
}
func resolveFormat() string {
if cmdutil.Format != "" {
return cmdutil.Format
}
return "json"
}

200
cmd/doctor/doctor_test.go Normal file
View File

@ -0,0 +1,200 @@
package doctor
import (
"bytes"
"encoding/json"
"errors"
"os"
"path/filepath"
"testing"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
)
func TestDoctorSkipNetworkReportsLocalChecks(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: https://www.gitlink.org.cn/api\ndefault_format: json\n")
t.Setenv("GITLINK_TOKEN", "secret-token")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "Gitlink", "gitlink-cli", nil
}
report := Run(true, i18n.Default())
if !report.OK {
t.Fatalf("expected report OK, got %+v", report)
}
assertCheck(t, report, "config_file", statusOK)
assertCheck(t, report, "config_values", statusOK)
assertCheck(t, report, "auth_token", statusOK)
assertCheck(t, report, "repo_context", statusOK)
assertCheck(t, report, "api_auth", statusSkipped)
if report.Summary.Total != 5 {
t.Fatalf("summary total = %d, want 5", report.Summary.Total)
}
}
func TestDoctorInvalidConfigDoesNotPanic(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: [broken\n")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "Gitlink", "gitlink-cli", nil
}
report := Run(true, i18n.Default())
if report.OK {
t.Fatalf("expected report not OK, got %+v", report)
}
assertCheck(t, report, "config_file", statusError)
assertCheck(t, report, "config_values", statusSkipped)
}
func TestDoctorInvalidBaseURL(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: gitlink.local/api\ndefault_format: table\n")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "Gitlink", "gitlink-cli", nil
}
report := Run(true, i18n.Default())
if report.OK {
t.Fatalf("expected invalid base_url to mark report not OK")
}
check := assertCheck(t, report, "config_values", statusError)
if check.Suggestion == "" {
t.Fatalf("expected config_values suggestion")
}
}
func TestDoctorMissingRepoContextIsWarning(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: https://www.gitlink.org.cn/api\ndefault_format: table\n")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "", "", errors.New("no origin remote")
}
report := Run(true, i18n.Default())
assertCheck(t, report, "auth_token", statusWarning)
check := assertCheck(t, report, "repo_context", statusWarning)
if check.Suggestion == "" {
t.Fatalf("expected repo_context suggestion")
}
if !report.OK {
t.Fatalf("warnings should not make report fail: %+v", report)
}
}
func TestDoctorNetworkCheckCanSucceed(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: https://www.gitlink.org.cn/api\ndefault_format: table\n")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "Gitlink", "gitlink-cli", nil
}
getCurrentUser = func() (map[string]interface{}, error) {
return map[string]interface{}{"login": "Mengz"}, nil
}
report := Run(false, i18n.Default())
assertCheck(t, report, "api_auth", statusOK)
if !report.OK {
t.Fatalf("expected report OK, got %+v", report)
}
}
func TestDoctorCommandPrintsJSONEnvelope(t *testing.T) {
withDoctorTestState(t)
writeConfig(t, "base_url: https://www.gitlink.org.cn/api\ndefault_format: json\n")
resolveOwnerRepo = func(owner, repo string) (string, string, error) {
return "Gitlink", "gitlink-cli", nil
}
cmd := NewDoctorCmd(i18n.Default())
cmd.SetArgs([]string{"--skip-network"})
var out bytes.Buffer
cmd.SetOut(&out)
if err := cmd.Execute(); err != nil {
t.Fatal(err)
}
var env struct {
OK bool `json:"ok"`
Data json.RawMessage `json:"data"`
}
if err := json.Unmarshal(out.Bytes(), &env); err != nil {
t.Fatalf("invalid JSON output: %v\n%s", err, out.String())
}
if !env.OK || len(env.Data) == 0 {
t.Fatalf("unexpected envelope: %+v", env)
}
}
func withDoctorTestState(t *testing.T) {
t.Helper()
oldLoadConfig := loadConfig
oldLoadToken := loadToken
oldGetCurrentUser := getCurrentUser
oldResolveOwnerRepo := resolveOwnerRepo
oldStatFile := statFile
oldLookupEnv := lookupEnv
oldFormat := cmdutil.Format
oldOwner := cmdutil.Owner
oldRepo := cmdutil.Repo
t.Setenv("GITLINK_CONFIG_DIR", t.TempDir())
t.Setenv("GITLINK_TOKEN", "")
cmdutil.Format = "json"
cmdutil.Owner = ""
cmdutil.Repo = ""
loadConfig = oldLoadConfig
loadToken = func() (string, error) { return "", os.ErrNotExist }
getCurrentUser = func() (map[string]interface{}, error) {
return nil, errors.New("unexpected network call")
}
resolveOwnerRepo = oldResolveOwnerRepo
statFile = oldStatFile
lookupEnv = func(key string) (string, bool) {
if key == "GITLINK_TOKEN" {
value := os.Getenv(key)
return value, value != ""
}
return os.LookupEnv(key)
}
t.Cleanup(func() {
loadConfig = oldLoadConfig
loadToken = oldLoadToken
getCurrentUser = oldGetCurrentUser
resolveOwnerRepo = oldResolveOwnerRepo
statFile = oldStatFile
lookupEnv = oldLookupEnv
cmdutil.Format = oldFormat
cmdutil.Owner = oldOwner
cmdutil.Repo = oldRepo
})
}
func writeConfig(t *testing.T, content string) {
t.Helper()
dir := os.Getenv("GITLINK_CONFIG_DIR")
if err := os.MkdirAll(dir, 0700); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte(content), 0600); err != nil {
t.Fatal(err)
}
}
func assertCheck(t *testing.T, report Report, name, status string) Check {
t.Helper()
for _, check := range report.Checks {
if check.Name == name {
if check.Status != status {
t.Fatalf("%s status = %s, want %s; check=%+v", name, check.Status, status, check)
}
return check
}
}
t.Fatalf("missing check %q in %+v", name, report.Checks)
return Check{}
}

90
cmd/expand.go Normal file
View File

@ -0,0 +1,90 @@
package cmd
import (
"strings"
"github.com/spf13/cobra"
internalConfig "github.com/gitlink-org/gitlink-cli/internal/config"
)
// expandAlias rewrites args when the first positional token names a saved alias.
// Built-in commands always take precedence, so an alias can never shadow a real
// command; a colliding alias simply never expands.
func expandAlias(root *cobra.Command, args []string) ([]string, bool) {
if len(args) == 0 {
return args, false
}
name := args[0]
if name == "" || strings.HasPrefix(name, "-") {
return args, false
}
if isBuiltinCommand(root, name) {
return args, false
}
cfg, err := internalConfig.Load()
if err != nil {
return args, false
}
expansion, ok := cfg.Aliases[name]
if !ok {
return args, false
}
parts := splitArgs(expansion)
if len(parts) == 0 {
return args, false
}
return append(parts, args[1:]...), true
}
func isBuiltinCommand(root *cobra.Command, name string) bool {
for _, c := range root.Commands() {
if c.Name() == name {
return true
}
for _, alias := range c.Aliases {
if alias == name {
return true
}
}
}
return false
}
// splitArgs breaks an alias expansion into argv tokens, honoring single and
// double quotes so expansions can carry multi-word flag values.
func splitArgs(s string) []string {
var args []string
var buf strings.Builder
inWord := false
var quote rune
for _, r := range s {
switch {
case quote != 0:
if r == quote {
quote = 0
} else {
buf.WriteRune(r)
}
inWord = true
case r == '\'' || r == '"':
quote = r
inWord = true
case r == ' ' || r == '\t' || r == '\n':
if inWord {
args = append(args, buf.String())
buf.Reset()
inWord = false
}
default:
buf.WriteRune(r)
inWord = true
}
}
if inWord {
args = append(args, buf.String())
}
return args
}

68
cmd/expand_test.go Normal file
View File

@ -0,0 +1,68 @@
package cmd
import (
"reflect"
"testing"
"github.com/spf13/cobra"
internalConfig "github.com/gitlink-org/gitlink-cli/internal/config"
)
func TestSplitArgs(t *testing.T) {
cases := []struct {
in string
want []string
}{
{"", nil},
{"pr +view", []string{"pr", "+view"}},
{" issue +list ", []string{"issue", "+list"}},
{`pr +view --title "needs review"`, []string{"pr", "+view", "--title", "needs review"}},
{`repo +create --name 'my repo'`, []string{"repo", "+create", "--name", "my repo"}},
}
for _, tc := range cases {
if got := splitArgs(tc.in); !reflect.DeepEqual(got, tc.want) {
t.Fatalf("splitArgs(%q) = %#v, want %#v", tc.in, got, tc.want)
}
}
}
func TestExpandAlias(t *testing.T) {
t.Setenv("GITLINK_CONFIG_DIR", t.TempDir())
cfg := internalConfig.DefaultConfig()
cfg.Aliases = map[string]string{
"co": "pr +view",
"config": "should never expand",
}
if err := internalConfig.Save(cfg); err != nil {
t.Fatalf("Save error: %v", err)
}
root := &cobra.Command{Use: "gitlink-cli"}
root.AddCommand(&cobra.Command{Use: "config"})
cases := []struct {
name string
args []string
want []string
expand bool
}{
{"alias match", []string{"co", "42"}, []string{"pr", "+view", "42"}, true},
{"builtin wins", []string{"config", "list"}, nil, false},
{"flag first", []string{"--lang", "zh-CN"}, nil, false},
{"unknown token", []string{"nope"}, nil, false},
{"empty args", nil, nil, false},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
got, ok := expandAlias(root, tc.args)
if ok != tc.expand {
t.Fatalf("expandAlias ok = %v, want %v", ok, tc.expand)
}
if tc.expand && !reflect.DeepEqual(got, tc.want) {
t.Fatalf("expandAlias = %#v, want %#v", got, tc.want)
}
})
}
}

127
cmd/root.go
View File

@ -1,54 +1,133 @@
package cmd
import (
"errors"
"fmt"
"os"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
authCmd "github.com/gitlink-org/gitlink-cli/cmd/auth"
aliasCmd "github.com/gitlink-org/gitlink-cli/cmd/alias"
apiCmd "github.com/gitlink-org/gitlink-cli/cmd/api"
browseCmd "github.com/gitlink-org/gitlink-cli/cmd/browse"
statusCmd "github.com/gitlink-org/gitlink-cli/cmd/status"
authCmd "github.com/gitlink-org/gitlink-cli/cmd/auth"
"github.com/gitlink-org/gitlink-cli/cmd/cmdutil"
configCmd "github.com/gitlink-org/gitlink-cli/cmd/config"
internalConfig "github.com/gitlink-org/gitlink-cli/internal/config"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
"github.com/gitlink-org/gitlink-cli/shortcuts"
)
var Version = "dev"
var rootCmd = &cobra.Command{
Use: "gitlink-cli",
Short: "GitLink CLI — command-line tool for gitlink.org.cn",
Long: `gitlink-cli is a command-line interface for the GitLink (确实开源) platform, providing repository management, issue tracking, pull requests, CI/CD, and AI-powered workflows.`,
SilenceUsage: true,
SilenceErrors: true,
type RootOptions struct {
Version string
Args []string
Env map[string]string
ConfigLang string
}
func init() {
rootCmd.PersistentFlags().StringVar(&cmdutil.Owner, "owner", "", "Repository owner (auto-detected from git remote)")
rootCmd.PersistentFlags().StringVar(&cmdutil.Repo, "repo", "", "Repository name (auto-detected from git remote)")
rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "", "Output format: json, table, yaml (default: table)")
rootCmd.PersistentFlags().BoolVar(&cmdutil.Debug, "debug", false, "Enable debug output")
func NewRootCmd(opts RootOptions, tr *i18n.Translator) (*cobra.Command, error) {
if tr == nil {
var err error
tr, err = newTranslator(opts.Args, opts.Env, opts.ConfigLang)
if err != nil {
return nil, err
}
}
rootCmd.AddCommand(authCmd.NewAuthCmd())
rootCmd.AddCommand(apiCmd.NewAPICmd())
rootCmd.AddCommand(configCmd.NewConfigCmd())
rootCmd.AddCommand(versionCmd)
version := opts.Version
if version == "" {
version = Version
}
shortcuts.RegisterAll(rootCmd)
rootCmd := &cobra.Command{
Use: "gitlink-cli",
Short: tr.T("cmd.root.short"),
Long: tr.T("cmd.root.long"),
SilenceUsage: true,
SilenceErrors: true,
}
rootCmd.PersistentFlags().StringVar(&cmdutil.Owner, "owner", "", tr.T("flag.owner"))
rootCmd.PersistentFlags().StringVar(&cmdutil.Repo, "repo", "", tr.T("flag.repo"))
rootCmd.PersistentFlags().StringVar(&cmdutil.Format, "format", "", tr.T("flag.format"))
rootCmd.PersistentFlags().BoolVar(&cmdutil.Debug, "debug", false, tr.T("flag.debug"))
rootCmd.PersistentFlags().StringVar(&cmdutil.Lang, "lang", "", tr.T("flag.lang"))
rootCmd.AddCommand(authCmd.NewAuthCmd(tr))
rootCmd.AddCommand(apiCmd.NewAPICmd(tr))
rootCmd.AddCommand(configCmd.NewConfigCmd(tr))
rootCmd.AddCommand(newVersionCmd(version, tr))
rootCmd.AddCommand(aliasCmd.NewAliasCmd())
rootCmd.AddCommand(browseCmd.NewBrowseCmd())
rootCmd.AddCommand(statusCmd.NewStatusCmd())
shortcuts.RegisterAll(rootCmd, tr)
if opts.Args != nil {
rootCmd.SetArgs(opts.Args)
}
return rootCmd, nil
}
var versionCmd = &cobra.Command{
Use: "version",
Short: "Print version information",
Run: func(cmd *cobra.Command, args []string) {
fmt.Printf("gitlink-cli %s\n", Version)
},
func newVersionCmd(version string, tr *i18n.Translator) *cobra.Command {
return &cobra.Command{
Use: "version",
Short: tr.T("cmd.version.short"),
RunE: func(cmd *cobra.Command, args []string) error {
_, err := fmt.Fprintln(cmd.OutOrStdout(), tr.Tf("output.version", i18n.Args{"version": version}))
return err
},
}
}
func Execute() error {
args := os.Args[1:]
rootCmd, err := NewRootCmd(RootOptions{
Version: Version,
Args: args,
}, nil)
if err != nil {
fmt.Fprintln(os.Stderr, err)
return err
}
if err := rootCmd.Execute(); err != nil {
fmt.Fprintln(os.Stderr, err)
return err
}
return nil
}
func newTranslator(args []string, env map[string]string, configLang string) (*i18n.Translator, error) {
available, err := i18n.AvailableLocales()
if err != nil {
return nil, err
}
if env == nil {
env = i18n.EnvMap()
}
if configLang == "" {
configLang = loadConfigLangBestEffort()
}
resolved := i18n.ResolveLocaleDetailed(i18n.ResolveOptions{
ExplicitLang: i18n.PreScanLang(args),
Env: env,
ConfigLang: configLang,
}, available)
if !resolved.Supported && (resolved.Source == "flag" || resolved.Source == "env") {
tr := i18n.Default()
return nil, errors.New(tr.Tf("error.unsupported_language", i18n.Args{"lang": resolved.Requested}))
}
return i18n.New(i18n.Options{Locale: resolved.Locale})
}
func loadConfigLangBestEffort() string {
cfg, err := internalConfig.Load()
if err != nil {
return ""
}
return cfg.Lang
}

310
cmd/root_test.go Normal file
View File

@ -0,0 +1,310 @@
package cmd
import (
"bytes"
"strings"
"testing"
"github.com/gitlink-org/gitlink-cli/internal/i18n"
)
func TestRootHelpUsesSelectedLocale(t *testing.T) {
tr, err := i18n.New(i18n.Options{Locale: "zh-CN"})
if err != nil {
t.Fatal(err)
}
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"--help"}}, tr)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
help := out.String()
if !strings.Contains(help, "用于管理 GitLink 上的仓库") {
t.Fatalf("expected Chinese root long help, got:\n%s", help)
}
if !strings.Contains(help, "仓库操作") {
t.Fatalf("expected Chinese shortcut group help, got:\n%s", help)
}
if !strings.Contains(help, "认证命令") || !strings.Contains(help, "管理 gitlink-cli 配置") {
t.Fatalf("expected Chinese core command help, got:\n%s", help)
}
if !strings.Contains(help, "--lang") || !strings.Contains(help, "显示语言") {
t.Fatalf("expected localized lang flag help, got:\n%s", help)
}
}
func TestRootHelpUsesExplicitLang(t *testing.T) {
root, err := NewRootCmd(RootOptions{Version: "test", Args: []string{"--lang", "zh-CN", "--help"}, Env: map[string]string{}}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
help := out.String()
for _, want := range []string{"用于管理 GitLink", "显示语言", "仓库"} {
if !strings.Contains(help, want) {
t.Fatalf("expected %q in help, got:\n%s", want, help)
}
}
}
func TestRootHelpUsesEnvLang(t *testing.T) {
root, err := NewRootCmd(RootOptions{
Version: "test",
Args: []string{"repo", "--help"},
Env: map[string]string{"GITLINK_LANG": "zh-CN"},
}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
help := out.String()
for _, want := range []string{"仓库操作", "仓库所有者", "仓库名称"} {
if !strings.Contains(help, want) {
t.Fatalf("expected %q in help, got:\n%s", want, help)
}
}
}
func TestExplicitLangOverridesConfigLang(t *testing.T) {
root, err := NewRootCmd(RootOptions{
Version: "test",
Args: []string{"--lang", "en-US", "--help"},
Env: map[string]string{},
ConfigLang: "zh-CN",
}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
help := out.String()
if !strings.Contains(help, "Repository operations") {
t.Fatalf("expected English help, got:\n%s", help)
}
if strings.Contains(help, "仓库操作") {
t.Fatalf("expected explicit en-US to override config zh-CN, got:\n%s", help)
}
}
func TestUnsupportedExplicitLangReturnsError(t *testing.T) {
_, err := NewRootCmd(RootOptions{
Version: "test",
Args: []string{"--lang", "fr-FR", "--help"},
Env: map[string]string{},
}, nil)
if err == nil {
t.Fatal("expected unsupported language error")
}
if !strings.Contains(err.Error(), "unsupported language") {
t.Fatalf("expected unsupported language error, got %q", err.Error())
}
}
func TestRequireArgUsesLocalizedError(t *testing.T) {
root, err := NewRootCmd(RootOptions{
Version: "test",
Args: []string{"--lang", "zh-CN", "repo", "+create"},
Env: map[string]string{},
}, nil)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
err = root.Execute()
if err == nil {
t.Fatal("expected missing required flag error")
}
if !strings.Contains(err.Error(), "缺少必需参数") {
t.Fatalf("expected localized missing flag error, got %q", err.Error())
}
}
func TestCoreCommandHelpUsesSelectedLocale(t *testing.T) {
tr, err := i18n.New(i18n.Options{Locale: "zh-CN"})
if err != nil {
t.Fatal(err)
}
cases := []struct {
args []string
want []string
}{
{
args: []string{"api", "--help"},
want: []string{"向 GitLink API 发送任意 HTTP 请求", "--body", "请求体（JSON 字符串）"},
},
{
args: []string{"auth", "login", "--help"},
want: []string{"登录 GitLink", "--token", "通过粘贴已有 Token 登录"},
},
{
args: []string{"config", "--help"},
want: []string{"管理 gitlink-cli 配置", "初始化配置文件", "列出所有配置项"},
},
}
for _, tc := range cases {
root, err := NewRootCmd(RootOptions{Version: "test", Args: tc.args}, tr)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("%v: %v", tc.args, err)
}
help := out.String()
for _, want := range tc.want {
if !strings.Contains(help, want) {
t.Fatalf("%v: expected %q in help, got:\n%s", tc.args, want, help)
}
}
}
}
func TestShortcutHelpUsesSelectedLocale(t *testing.T) {
tr, err := i18n.New(i18n.Options{Locale: "zh-CN"})
if err != nil {
t.Fatal(err)
}
cases := []struct {
args []string
want []string
}{
{
args: []string{"repo", "+create", "--help"},
want: []string{"创建新仓库", "--name", "仓库名称", "--private", "设为私有仓库"},
},
{
args: []string{"pr", "+review", "--help"},
want: []string{"创建拉取请求评审", "--content", "评审内容", "--dry-run"},
},
}
for _, tc := range cases {
root, err := NewRootCmd(RootOptions{Version: "test", Args: tc.args}, tr)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("%v: %v", tc.args, err)
}
help := out.String()
for _, want := range tc.want {
if !strings.Contains(help, want) {
t.Fatalf("%v: expected %q in help, got:\n%s", tc.args, want, help)
}
}
}
}
func TestRemainingShortcutHelpUsesSelectedLocale(t *testing.T) {
tr, err := i18n.New(i18n.Options{Locale: "zh-CN"})
if err != nil {
t.Fatal(err)
}
cases := []struct {
args []string
want []string
}{
{
args: []string{"branch", "+create", "--help"},
want: []string{"创建分支", "--from", "源分支或 Commit"},
},
{
args: []string{"release", "+create", "--help"},
want: []string{"创建发布", "--prerelease", "标记为预发布"},
},
{
args: []string{"webhook", "+create", "--help"},
want: []string{"创建仓库 Webhook", "--events", "逗号分隔的事件"},
},
{
args: []string{"ci", "+logs", "--help"},
want: []string{"查看构建日志", "--build", "构建编号"},
},
}
for _, tc := range cases {
root, err := NewRootCmd(RootOptions{Version: "test", Args: tc.args}, tr)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatalf("%v: %v", tc.args, err)
}
help := out.String()
for _, want := range tc.want {
if !strings.Contains(help, want) {
t.Fatalf("%v: expected %q in help, got:\n%s", tc.args, want, help)
}
}
}
}
func TestVersionUsesInjectedVersion(t *testing.T) {
tr, err := i18n.New(i18n.Options{Locale: "en-US"})
if err != nil {
t.Fatal(err)
}
root, err := NewRootCmd(RootOptions{Version: "1.2.3", Args: []string{"version"}}, tr)
if err != nil {
t.Fatal(err)
}
var out bytes.Buffer
root.SetOut(&out)
root.SetErr(&out)
if err := root.Execute(); err != nil {
t.Fatal(err)
}
if got := strings.TrimSpace(out.String()); got != "gitlink-cli 1.2.3" {
t.Fatalf("version output = %q", got)
}
}

589
cmd/server/server.go Normal file
View File

@ -0,0 +1,589 @@
/*
* 子赛题四「网页终端」HTTP 演示服务
*
* 前端搜索驱动界面 → 后端串行运行 Python 算法脚本
* 支持 7 个科研分析维度（热点/画像/启发/谱系/合规/报告/可视化）
* Python 子进程继承 GITLINK_TOKEN / DEEPSEEK_API_KEY 环境变量
*
* API:
* GET /api/dimensions - 返回可用维度列表
* POST /api/chain - 统一全链路分析入口
* POST /api/run - 单场景执行(向后兼容)
* GET /api/result/{key} - 查询缓存产物
*/
package server
import (
"embed"
"encoding/json"
"fmt"
"io/fs"
"net/http"
"os"
"os/exec"
"path/filepath"
"strings"
"sync"
"time"
"github.com/spf13/cobra"
)
//go:embed static/*
var staticFS embed.FS
const defaultPort = 8080
// 场景定义：前端按钮 ↔ 后端 Python 脚本。
type scenarioDef struct {
Key string `json:"key"`
Label string `json:"label"`
Desc string `json:"desc"`
Script string `json:"script"`
Needs []string `json:"needs"` // 需要的输入: "owner","repo","keyword"
Timeout int `json:"timeout_s"`
}
var scenarios = []scenarioDef{
{Key: "s1", Label: "S1 仓库洞悉", Desc: "科研项目演进谱系 + 创新点", Script: "lineage.py", Needs: []string{"owner", "repo"}, Timeout: 180},
{Key: "s2", Label: "S2 知识图谱", Desc: "科研领域知识图谱(networkx)", Script: "graph_build.py", Needs: []string{"keyword"}, Timeout: 240},
{Key: "s3", Label: "S3 合规复现", Desc: "许可证/密钥/复现性检查", Script: "repro.py", Needs: []string{"owner", "repo"}, Timeout: 120},
{Key: "s4", Label: "S4 协作匹配", Desc: "学者×缺口 智能匹配", Script: "match.py", Needs: []string{"owner", "repo"}, Timeout: 180},
{Key: "s5", Label: "S5 进度预警", Desc: "周报 + 风险预警", Script: "report.py", Needs: []string{"owner", "repo"}, Timeout: 180},
{Key: "s6", Label: "S6 成果可视化", Desc: "交互图表(plotly)", Script: "visual.py", Needs: []string{"owner", "repo"}, Timeout: 240},
{Key: "hotspot", Label: "🔥 热点追踪（关键词）", Desc: "关键词搜索：飙升项目+活跃讨论+主题热度+学者团队", Script: "hotspot.py", Needs: []string{"keyword"}, Timeout: 300},
{Key: "hotspot-cat", Label: "🔥 热点追踪（分类精选）", Desc: "GitLink 官方分类精选 → 领域热点（缩范围）", Script: "hotspot.py", Needs: []string{"category"}, Timeout: 300},
{Key: "profile", Label: "🪪 主体画像", Desc: "项目画像：主题/语言/贡献者/研究维度评分", Script: "profile.py", Needs: []string{"owner", "repo"}, Timeout: 150},
{Key: "inspire", Label: "💡 创新启发", Desc: "缺口挖掘 + 合作者匹配 + LLM 研究方向建议", Script: "inspire.py", Needs: []string{"owner", "repo"}, Timeout: 240},
{Key: "chain", Label: "🔬 全链路", Desc: "分类→热点→画像→启发→合规→分析（一条命令打通）", Script: "research.py", Needs: []string{"category"}, Timeout: 600},
}
// dimensionDef 分析维度：前端展示用，对应一个 Python 脚本。
type dimensionDef struct {
Key string `json:"key"`
Label string `json:"label"`
Icon string `json:"icon"`
Desc string `json:"desc"`
Script string `json:"script"`
Needs []string `json:"needs"` // 需要的参数: "keyword","category","owner","repo","owner_repo"
Timeout int `json:"timeout_s"`
}
var dimensions = []dimensionDef{
{Key: "hotspot", Label: "科研热点分析", Icon: "🔥", Desc: "飙升项目 + 活跃讨论 + 主题热度 + 核心学者", Script: "hotspot.py", Needs: []string{"keyword_or_category"}, Timeout: 300},
{Key: "profile", Label: "主体画像", Icon: "🪪", Desc: "项目/学者画像：主题向量/语言/研究维度评分", Script: "profile.py", Needs: []string{"owner_repo_or_category"}, Timeout: 150},
{Key: "inspire", Label: "创新启发", Icon: "💡", Desc: "缺口挖掘 + 合作者匹配 + LLM 研究方向建议", Script: "inspire.py", Needs: []string{"owner_repo_or_category"}, Timeout: 240},
{Key: "lineage", Label: "演进谱系", Icon: "🌳", Desc: "创新点识别 + 项目演化分支 + 贡献者参与分析", Script: "lineage.py", Needs: []string{"owner", "repo"}, Timeout: 180},
{Key: "repro", Label: "合规复现", Icon: "✅", Desc: "许可证/依赖锁定/容器化/密钥泄漏/复现性评分", Script: "repro.py", Needs: []string{"owner", "repo"}, Timeout: 120},
{Key: "report", Label: "进度报告", Icon: "📋", Desc: "周报 + 里程碑追踪 + 风险预警（交通灯系统）", Script: "report.py", Needs: []string{"owner", "repo"}, Timeout: 180},
{Key: "visual", Label: "成果可视化", Icon: "📊", Desc: "交互式 Plotly 图表：时间线/热力图/语言饼图/Gantt", Script: "visual.py", Needs: []string{"owner", "repo"}, Timeout: 240},
}
// chainRequest 统一分析请求。
type chainRequest struct {
Dimensions []string `json:"dimensions"` // 选中的维度 key 列表
Keyword string `json:"keyword"`
Owner string `json:"owner"`
Repo string `json:"repo"`
Category string `json:"category"`
}
// dimensionResult 单个维度的运行结果。
type dimensionResult struct {
Key string `json:"key"`
Label string `json:"label"`
OK bool `json:"ok"`
Error string `json:"error,omitempty"`
Duration string `json:"duration"`
Command string `json:"command"`
Stdout string `json:"stdout"`
OutDir string `json:"out_dir"`
Artifacts map[string]string `json:"artifacts"`
}
// chainResponse 统一分析 API 返回。
type chainResponse struct {
OK bool `json:"ok"`
SessionID string `json:"session_id"`
Duration string `json:"duration"`
Results map[string]*dimensionResult `json:"results"`
}
type Options struct {
Port int
ResearchDir string // scripts/research 目录
WorkDir string // 产物输出根目录
Token string // 可选鉴权 token
LLMKey string // LLM API Key（内置到服务端，非前端输入）
LLMBase string // LLM API Base URL
LLMModel string // LLM Model 名称
GitLinkToken string // GitLink API Token（内置，Python 子进程通过 GITLINK_TOKEN 使用）
}
func NewServerCmd() *cobra.Command {
opts := Options{Port: defaultPort, ResearchDir: "scripts/research", WorkDir: "research-output", LLMKey: "sk-52b7f7db19fe41118d3b931bded9403c", LLMBase: "https://api.deepseek.com/anthropic", LLMModel: "deepseek-v4-pro", GitLinkToken: "330e35fbb163da345df372b4cbe1cf973aae2b67"}
cmd := &cobra.Command{
Use: "server",
Short: "启动子赛题四网页终端（HTTP 演示服务）",
RunE: func(cmd *cobra.Command, args []string) error {
return Run(opts)
},
}
cmd.Flags().IntVarP(&opts.Port, "port", "p", defaultPort, "监听端口")
cmd.Flags().StringVar(&opts.ResearchDir, "research-dir", "scripts/research", "scripts/research 目录")
cmd.Flags().StringVar(&opts.WorkDir, "work-dir", "research-output", "产物输出根目录")
cmd.Flags().StringVar(&opts.Token, "token", "", "可选鉴权 token（亦可用 DEMO_TOKEN 环境变量）")
cmd.Flags().StringVar(&opts.LLMKey, "llm-key", opts.LLMKey, "LLM API Key（默认内置）")
cmd.Flags().StringVar(&opts.LLMBase, "llm-base", opts.LLMBase, "LLM API Base URL")
cmd.Flags().StringVar(&opts.LLMModel, "llm-model", opts.LLMModel, "LLM Model 名称")
cmd.Flags().StringVar(&opts.GitLinkToken, "gitlink-token", opts.GitLinkToken, "GitLink API Token（默认内置）")
return cmd
}
// Run 启动 HTTP 服务（阻塞）。
func Run(opts Options) error {
if t := os.Getenv("DEMO_TOKEN"); t != "" && opts.Token == "" {
opts.Token = t
}
// LLM key 优先级：--llm-key > DEEPSEEK_API_KEY > LLM_API_KEY
if opts.LLMKey == "" {
if k := os.Getenv("DEEPSEEK_API_KEY"); k != "" {
opts.LLMKey = k
} else if k := os.Getenv("LLM_API_KEY"); k != "" {
opts.LLMKey = k
}
}
// GitLink token：内置默认值注入进程环境，子进程自动继承
if opts.GitLinkToken != "" && os.Getenv("GITLINK_TOKEN") == "" {
_ = os.Setenv("GITLINK_TOKEN", opts.GitLinkToken)
}
// 让 python 子进程复用本二进制（gitlink_data.cli_path 读 GITLINK_CLI），免去额外配置
if os.Getenv("GITLINK_CLI") == "" {
if exe, err := filepath.Abs(os.Args[0]); err == nil {
_ = os.Setenv("GITLINK_CLI", exe)
}
}
_ = os.MkdirAll(opts.WorkDir, 0o755)
mux := http.NewServeMux()
h := &handler{opts: opts}
mux.HandleFunc("GET /api/scenarios", h.handleScenarios)
mux.HandleFunc("POST /api/run", h.handleRun)
mux.HandleFunc("GET /api/result/{key}", h.handleResult)
mux.HandleFunc("GET /api/health", h.handleHealth)
mux.HandleFunc("GET /api/dimensions", h.handleDimensions)
mux.HandleFunc("POST /api/chain", h.handleChain)
sub, err := fs.Sub(staticFS, "static")
if err != nil {
return fmt.Errorf("static fs: %w", err)
}
mux.Handle("GET /", http.FileServer(http.FS(sub)))
addr := fmt.Sprintf(":%d", opts.Port)
fmt.Fprintf(os.Stderr, "子赛题四 网页终端已启动: http://localhost%s\n", addr)
fmt.Fprintf(os.Stderr, " research-dir=%s work-dir=%s auth=%v\n", opts.ResearchDir, opts.WorkDir, opts.Token != "")
if opts.LLMKey != "" {
fmt.Fprintf(os.Stderr, " LLM: enabled (model=%s)\n", opts.LLMModel)
} else {
fmt.Fprintf(os.Stderr, " LLM: disabled (no key)\n")
}
srv := &http.Server{Addr: addr, Handler: mux, ReadHeaderTimeout: 10 * time.Second}
return srv.ListenAndServe()
}
type handler struct {
opts Options
mu sync.Mutex // 串行化场景执行，避免并发打爆 GitLink API
}
func (h *handler) authed(r *http.Request) bool {
if h.opts.Token == "" {
return true
}
return r.Header.Get("X-Demo-Token") == h.opts.Token
}
func (h *handler) handleHealth(w http.ResponseWriter, r *http.Request) {
writeJSON(w, map[string]any{"ok": true, "scenarios": len(scenarios), "dimensions": len(dimensions)})
}
func (h *handler) handleDimensions(w http.ResponseWriter, r *http.Request) {
if !h.authed(r) {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
writeJSON(w, map[string]any{"ok": true, "dimensions": dimensions})
}
func (h *handler) handleScenarios(w http.ResponseWriter, r *http.Request) {
if !h.authed(r) {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
writeJSON(w, map[string]any{"ok": true, "scenarios": scenarios})
}
// handleResult 返回某场景最近一次运行的产物（供 result.html 独立结果页按 key 读取，
// URL 可刷新/分享，便于演示讲解）。无需鉴权串行锁——只读已落盘产物。
func (h *handler) handleResult(w http.ResponseWriter, r *http.Request) {
if !h.authed(r) {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
key := r.PathValue("key")
sc, ok := findScenario(key)
if !ok {
writeJSON(w, map[string]any{"ok": false, "error": "unknown scenario: " + key})
return
}
outDir := filepath.Join(h.opts.WorkDir, sc.Key)
writeJSON(w, map[string]any{
"ok": true,
"scenario": sc.Key,
"label": sc.Label,
"desc": sc.Desc,
"artifacts": readArtifacts(outDir),
})
}
type runRequest struct {
Scenario string `json:"scenario"`
Owner string `json:"owner"`
Repo string `json:"repo"`
Keyword string `json:"keyword"`
Category string `json:"category"`
}
func (h *handler) handleRun(w http.ResponseWriter, r *http.Request) {
if !h.authed(r) {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
var req runRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeJSON(w, map[string]any{"ok": false, "error": "bad request: " + err.Error()})
return
}
sc, ok := findScenario(req.Scenario)
if !ok {
writeJSON(w, map[string]any{"ok": false, "error": "unknown scenario: " + req.Scenario})
return
}
for _, need := range sc.Needs {
if (need == "keyword" && req.Keyword == "") ||
(need == "owner" && req.Owner == "") ||
(need == "repo" && req.Repo == "") ||
(need == "category" && req.Category == "") {
writeJSON(w, map[string]any{"ok": false, "error": "missing parameter: " + need})
return
}
}
// 串行执行：一次只跑一个场景，保护 GitLink API。
h.mu.Lock()
defer h.mu.Unlock()
scriptPath := filepath.Join(h.opts.ResearchDir, sc.Script)
outDir := filepath.Join(h.opts.WorkDir, sc.Key)
_ = os.MkdirAll(outDir, 0o755)
argv := []string{scriptPath, "--out", outDir}
if contains(sc.Needs, "owner") {
argv = append(argv, "--owner", req.Owner, "--repo", req.Repo)
}
if contains(sc.Needs, "keyword") {
argv = append(argv, "--keywords", req.Keyword)
}
if contains(sc.Needs, "category") {
argv = append(argv, "--category", req.Category)
}
// chain 支持可选焦点仓（省略则自动取热点榜 top-1）
if sc.Key == "chain" && req.Owner != "" && req.Repo != "" {
argv = append(argv, "--repo", req.Owner+"/"+req.Repo)
}
// python3 优先，回退 python
py, err := pythonBin()
if err != nil {
writeJSON(w, map[string]any{"ok": false, "error": err.Error()})
return
}
cmd := exec.Command(py, argv...)
// 子进程复用本二进制（python 经 GITLINK_CLI 找 gitlink-cli）；直接注入子进程 env，最稳。
env := os.Environ()
if !envHas(env, "GITLINK_CLI") {
if exe, err := filepath.Abs(os.Args[0]); err == nil {
env = append(env, "GITLINK_CLI="+exe)
}
}
cmd.Env = env
start := time.Now()
out, err := cmd.CombinedOutput()
dur := time.Since(start)
resp := map[string]any{
"ok": err == nil,
"scenario": sc.Key,
"command": py + " " + strings.Join(argv, " "),
"duration": dur.Truncate(time.Millisecond).String(),
"stdout": string(out),
"out_dir": outDir,
}
if err != nil {
resp["error"] = err.Error()
}
// 附带读取关键产物（json + 第一个 mmd + report.md），便于前端直接渲染
resp["artifacts"] = readArtifacts(outDir)
writeJSON(w, resp)
}
// handleChain 统一全链路科研分析入口
//
// 接受维度 key 列表 + 关键词/分类/仓库参数，串行执行各 Python 脚本，
// 聚合结果返回给前端 Tab 面板渲染。每个维度独立计时并记录成功/失败状态。
// 复用全局 mutex 防止并发打爆 GitLink API。
//
// 参数:
// w - HTTP ResponseWriter
// r - HTTP Request（JSON body 为 chainRequest）
//
// 返回:
// JSON chainResponse，包含 session_id、总耗时、各维度结果映射
func (h *handler) handleChain(w http.ResponseWriter, r *http.Request) {
if !h.authed(r) {
http.Error(w, "unauthorized", http.StatusUnauthorized)
return
}
var req chainRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
writeJSON(w, chainResponse{OK: false, Results: map[string]*dimensionResult{"_error": {Key: "_error", Label: "parse error", OK: false, Error: "bad request: " + err.Error()}}})
return
}
if len(req.Dimensions) == 0 {
writeJSON(w, chainResponse{OK: false, Results: map[string]*dimensionResult{"_error": {Key: "_error", Label: "no dimensions", OK: false, Error: "至少选择一个分析维度"}}})
return
}
// 校验所有维度 key 合法
for _, dk := range req.Dimensions {
if _, ok := findDimension(dk); !ok {
writeJSON(w, chainResponse{OK: false, Results: map[string]*dimensionResult{"_error": {Key: dk, Label: dk, OK: false, Error: "未知分析维度: " + dk}}})
return
}
}
// 串行执行（复用 mutex 保护 GitLink API）
h.mu.Lock()
defer h.mu.Unlock()
sessionID := fmt.Sprintf("session_%s", time.Now().Format("20060102_150405"))
results := make(map[string]*dimensionResult)
totalStart := time.Now()
for _, dk := range req.Dimensions {
dim, _ := findDimension(dk)
dimArgs, err := buildDimensionArgs(dim, req)
outDir := filepath.Join(h.opts.WorkDir, sessionID, dim.Key)
_ = os.MkdirAll(outDir, 0o755)
dr := &dimensionResult{Key: dim.Key, Label: dim.Label, OutDir: outDir}
if err != nil {
dr.OK = false
dr.Error = err.Error()
results[dim.Key] = dr
continue
}
py, err := pythonBin()
if err != nil {
dr.OK = false
dr.Error = err.Error()
results[dim.Key] = dr
continue
}
scriptPath := filepath.Join(h.opts.ResearchDir, dim.Script)
argv := append([]string{scriptPath, "--out", outDir}, dimArgs...)
cmd := exec.Command(py, argv...)
env := os.Environ()
if !envHas(env, "GITLINK_CLI") {
if exe, e2 := filepath.Abs(os.Args[0]); e2 == nil {
env = append(env, "GITLINK_CLI="+exe)
}
}
// LLM key 注入子进程
if h.opts.LLMKey != "" {
if !envHas(env, "DEEPSEEK_API_KEY") && !envHas(env, "LLM_API_KEY") {
env = append(env, "DEEPSEEK_API_KEY="+h.opts.LLMKey)
}
if !envHas(env, "DEEPSEEK_BASE_URL") && !envHas(env, "LLM_BASE_URL") {
env = append(env, "DEEPSEEK_BASE_URL="+h.opts.LLMBase)
}
if !envHas(env, "DEEPSEEK_MODEL") && !envHas(env, "LLM_MODEL") {
env = append(env, "DEEPSEEK_MODEL="+h.opts.LLMModel)
}
}
cmd.Env = env
dr.Command = py + " " + strings.Join(argv, " ")
dimStart := time.Now()
out, runErr := cmd.CombinedOutput()
dr.Duration = time.Since(dimStart).Truncate(time.Millisecond).String()
dr.Stdout = string(out)
dr.OK = runErr == nil
if runErr != nil {
dr.Error = runErr.Error()
}
dr.Artifacts = readArtifacts(outDir)
results[dim.Key] = dr
}
resp := chainResponse{
OK: true,
SessionID: sessionID,
Duration: time.Since(totalStart).Truncate(time.Millisecond).String(),
Results: results,
}
writeJSON(w, resp)
}
func findScenario(key string) (scenarioDef, bool) {
for _, s := range scenarios {
if s.Key == key || strings.EqualFold(s.Key, key) {
return s, true
}
}
return scenarioDef{}, false
}
func findDimension(key string) (dimensionDef, bool) {
for _, d := range dimensions {
if d.Key == key || strings.EqualFold(d.Key, key) {
return d, true
}
}
return dimensionDef{}, false
}
func readArtifacts(dir string) map[string]string {
out := map[string]string{}
// json 产物（取第一个 *.json）
if entries, err := os.ReadDir(dir); err == nil {
for _, e := range entries {
if e.IsDir() {
continue
}
name := e.Name()
switch {
case strings.HasSuffix(name, ".json"):
b, _ := os.ReadFile(filepath.Join(dir, name))
out["json"] = string(b)
case strings.HasSuffix(name, ".mmd"):
b, _ := os.ReadFile(filepath.Join(dir, name))
out["mermaid"] = string(b)
case name == "visual.html":
b, _ := os.ReadFile(filepath.Join(dir, name))
out["html"] = string(b)
case strings.HasSuffix(name, ".md"):
// 第一份 .md 报告（report.md / weekly_report.md / compliance_report.md）
if _, ok := out["report"]; !ok {
b, _ := os.ReadFile(filepath.Join(dir, name))
out["report"] = string(b)
}
}
}
}
return out
}
func pythonBin() (string, error) {
// 候选按 Linux 习惯 python3 优先，再 python / py(Windows)。
// 必须实测能产出：Windows 的 WindowsApps\python3.exe 是 Store 桩，对 -c 也可能 exit 0 但不真正执行，
// 故用「stdout 必须含 PYOK」来拦截桩。
for _, name := range []string{"python3", "python", "py"} {
path, err := exec.LookPath(name)
if err != nil {
continue
}
if out, err := exec.Command(path, "-c", "print('PYOK')").Output(); err == nil &&
strings.Contains(string(out), "PYOK") {
return path, nil
}
}
return "", fmt.Errorf("python 未安装；容器需内置 python3 并 pip install -r scripts/research/requirements.txt")
}
func contains(xs []string, s string) bool {
for _, x := range xs {
if x == s {
return true
}
}
return false
}
// buildDimensionArgs 根据维度定义和请求参数构建 Python 脚本 CLI 参数。
func buildDimensionArgs(dim dimensionDef, req chainRequest) ([]string, error) {
argv := []string{} // script 在调用方追加
hasKeyword := req.Keyword != ""
hasCategory := req.Category != ""
hasRepo := req.Owner != "" && req.Repo != ""
// 检查每个 need
for _, need := range dim.Needs {
switch need {
case "keyword_or_category":
if !hasKeyword && !hasCategory {
return nil, fmt.Errorf("维度 %s 需要 --keywords 或 --category", dim.Key)
}
if hasCategory {
argv = append(argv, "--category", req.Category)
} else {
argv = append(argv, "--keywords", req.Keyword)
}
case "keyword":
if !hasKeyword {
return nil, fmt.Errorf("维度 %s 需要 --keywords", dim.Key)
}
argv = append(argv, "--keywords", req.Keyword)
case "owner_repo_or_category":
if !hasRepo && !hasCategory {
return nil, fmt.Errorf("维度 %s 需要 --owner/--repo 或 --category", dim.Key)
}
if hasCategory {
argv = append(argv, "--category", req.Category)
} else {
argv = append(argv, "--owner", req.Owner, "--repo", req.Repo)
}
case "owner":
if !hasRepo {
return nil, fmt.Errorf("维度 %s 需要 --owner 和 --repo", dim.Key)
}
argv = append(argv, "--owner", req.Owner)
case "repo":
if !hasRepo {
return nil, fmt.Errorf("维度 %s 需要 --repo", dim.Key)
}
argv = append(argv, "--repo", req.Repo)
}
}
return argv, nil
}
// envHas 报告环境变量切片里是否已含某 KEY（形如 "KEY=..."）。
func envHas(env []string, key string) bool {
prefix := key + "="
for _, e := range env {
if strings.HasPrefix(e, prefix) {
return true
}
}
return false
}
func writeJSON(w http.ResponseWriter, v any) {
w.Header().Set("Content-Type", "application/json; charset=utf-8")
_ = json.NewEncoder(w).Encode(v)
}

12
cmd/server/static/hotspot.html Normal file
View File

@ -0,0 +1,12 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta http-equiv="refresh" content="0;url=index.html">
<title>科研热点追踪 · GitLink Research Atlas</title>
</head>
<body style="font-family:-apple-system,'PingFang SC','Microsoft YaHei',sans-serif;text-align:center;padding:60px 20px;color:#475569">
<p>🔥 热点追踪已整合到 <a href="index.html" style="color:#4F6BED;font-weight:600">全链路科研分析</a>。</p>
<p style="font-size:13px;color:#94A3B8;margin-top:10px">正在跳转…</p>
</body>
</html>

1048
cmd/server/static/index.html Normal file
View File

File diff suppressed because it is too large Load Diff

504
cmd/server/static/result.html Normal file
View File

@ -0,0 +1,504 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>GitLink Research Atlas · 结果详情</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Cormorant+Garamond:wght@500;600;700&family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@500;700&family=Noto+Serif+SC:wght@600;700&family=Noto+Sans+SC:wght@400;500;700&display=swap" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<style>
:root{
--bg:#F7F9FC; --card:#FFFFFF; --ink:#1E2A44; --ink2:#475569; --mute:#94A3B8;
--line:#E6EBF2; --indigo:#4F6BED; --coral:#F26B5E; --mint:#2EC4B6;
--t-blue:#E8EEFF; --t-coral:#FFEDEA; --t-mint:#E6F7F4; --t-amber:#FEF3C7;
--serif:"Cormorant Garamond","Noto Serif SC",Georgia,serif;
--sans:"Inter","Noto Sans SC",-apple-system,"PingFang SC","Microsoft YaHei",sans-serif;
--mono:"JetBrains Mono",ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
--shadow:0 1px 2px rgba(30,42,68,.04),0 6px 18px rgba(30,42,68,.06);
--shadow-sm:0 1px 2px rgba(30,42,68,.06);
}
*{box-sizing:border-box;margin:0;padding:0}
html,body{height:auto;min-height:100%;margin:0}
body{font-family:var(--sans);color:var(--ink);background:var(--bg);
background-image:radial-gradient(1200px 480px at 80% -8%,#EAF0FF 0%,rgba(234,240,255,0) 60%),
radial-gradient(900px 420px at 0% 0%,#FFF1EE 0%,rgba(255,241,238,0) 55%);
-webkit-font-smoothing:antialiased}
/* ========== PRINT ========== */
@media print{
body{background:#fff!important}
.no-print{display:none!important}
.page-wrap{max-width:100%!important;box-shadow:none!important}
}
/* ========== PAGE WRAPPER ========== */
.page-wrap{max-width:1120px;margin:0 auto;padding:32px 40px 60px}
@media(max-width:760px){.page-wrap{padding:20px 16px 40px}}
/* ========== HEADER ========== */
.res-header{margin-bottom:32px}
.res-header .back{display:inline-flex;align-items:center;gap:6px;font-size:13px;font-weight:600;
color:var(--indigo);text-decoration:none;margin-bottom:16px;padding:6px 14px;border-radius:10px;
background:var(--t-blue);transition:.15s}
.res-header .back:hover{background:#D6DEFF}
.res-header h1{font-family:var(--serif);font-weight:700;font-size:34px;line-height:1.2;letter-spacing:.3px;color:var(--ink)}
.res-header .sub{font-size:15px;color:var(--ink2);margin-top:6px;line-height:1.5}
.res-header .meta{display:flex;flex-wrap:wrap;gap:16px;margin-top:14px;align-items:center}
.res-header .meta .chip{display:inline-flex;align-items:center;gap:6px;font-size:12px;font-weight:500;
padding:5px 12px;border-radius:999px;background:var(--card);border:1px solid var(--line);color:var(--ink2);box-shadow:var(--shadow-sm)}
.res-header .meta .chip b{font-family:var(--mono);font-weight:700;color:var(--ink)}
.res-header .cmd-drawer{margin-top:14px;background:var(--ink);color:#CBD5E1;font-family:var(--mono);
font-size:12px;padding:10px 16px;border-radius:10px;display:flex;align-items:center;gap:10px;overflow:hidden}
.res-header .cmd-drawer .dots{display:flex;gap:6px;flex-shrink:0}
.res-header .cmd-drawer .dots i{width:11px;height:11px;border-radius:50%;display:block}
.res-header .cmd-drawer .cmd{flex:1;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:#E2E8F0}
/* ========== SECTION TITLES ========== */
.section{margin-top:36px}
.section-title{font-family:var(--serif);font-weight:700;font-size:22px;color:var(--ink);margin-bottom:16px;
padding-bottom:8px;border-bottom:2px solid var(--line)}
.section-title .eyebrow{font-family:var(--mono);font-size:10px;letter-spacing:.16em;text-transform:uppercase;
color:var(--mute);display:block;margin-bottom:4px}
/* ========== METRICS ROW ========== */
.metrics-row{display:grid;grid-template-columns:repeat(4,1fr);gap:14px;margin-bottom:8px}
@media(max-width:760px){.metrics-row{grid-template-columns:repeat(2,1fr)}}
.metric-card{background:var(--card);border:1px solid var(--line);border-radius:12px;padding:18px;
box-shadow:var(--shadow);text-align:center}
.metric-card .label{font-size:12px;color:var(--ink2);font-weight:500;margin-bottom:8px}
.metric-card .value{font-family:var(--mono);font-weight:700;font-size:32px;color:var(--ink);line-height:1}
.metric-card .note{font-size:11px;color:var(--mute);margin-top:6px}
/* ========== KNOWLEDGE GRAPH ========== */
.graph-container{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);
padding:20px;overflow:hidden}
.graph-svg-wrap{width:100%;height:500px;position:relative;background:radial-gradient(500px 380px at 50% 45%,#F2F6FF 0%,rgba(255,255,255,0) 70%);
border-radius:10px;overflow:hidden}
.graph-svg-wrap svg{width:100%;height:100%;display:block}
.g-edge{stroke:#9DB4F0;stroke-opacity:.55;stroke-width:1}
.g-node circle{stroke:#fff;stroke-width:2;transition:.2s}
.g-node:hover circle{filter:brightness(1.08)}
.g-node text{font-family:var(--sans);font-size:11px;font-weight:600;fill:var(--ink);pointer-events:none;text-anchor:middle}
.graph-legend{display:flex;flex-wrap:wrap;gap:14px;margin-top:14px;padding-top:12px;border-top:1px solid var(--line)}
.graph-legend .leg-item{display:flex;align-items:center;gap:5px;font-size:12px;color:var(--ink2)}
.graph-legend .leg-dot{width:10px;height:10px;border-radius:50%;flex-shrink:0}
.graph-legend .leg-note{font-size:12px;color:var(--mute);margin-left:auto}
/* ========== VIZ IFRAME (S6) ========== */
.viz-container{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);
padding:12px;overflow:hidden}
.viz-container iframe{width:100%;height:520px;border:0;border-radius:10px;background:#fff}
/* ========== MERMAID ========== */
.mmd-container{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);
padding:16px;overflow:auto;max-height:600px}
/* ========== RADAR / SCORE (S3) ========== */
.score-display{display:flex;align-items:center;justify-content:center;gap:40px;padding:30px;
background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);flex-wrap:wrap}
.score-circle{width:140px;height:140px;border-radius:50%;display:flex;flex-direction:column;align-items:center;justify-content:center;
position:relative;border:6px solid}
.score-circle .val{font-family:var(--mono);font-weight:700;font-size:40px;line-height:1}
.score-circle .label{font-size:13px;color:var(--ink2);margin-top:2px}
.score-circle.repro{border-color:var(--mint);color:var(--mint);background:var(--t-mint)}
.score-circle.compliance{border-color:var(--indigo);color:var(--indigo);background:var(--t-blue)}
/* ========== WEEKLY COMPARISON (S5) ========== */
.weekly-bars{display:flex;flex-direction:column;gap:16px;padding:20px;
background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow)}
.week-row{display:flex;align-items:center;gap:14px}
.week-row .label{width:70px;font-size:13px;font-weight:600;color:var(--ink2);flex-shrink:0}
.week-row .bar-bg{flex:1;height:28px;background:#F1F5F9;border-radius:8px;overflow:hidden;position:relative}
.week-row .bar-fill{height:100%;border-radius:8px;transition:width .6s ease}
.week-row .bar-fill.this-week{background:linear-gradient(90deg,var(--indigo),#7C8CF5)}
.week-row .bar-fill.last-week{background:var(--line)}
.week-row .bar-val{position:absolute;right:8px;top:50%;transform:translateY(-50%);font-family:var(--mono);font-size:12px;font-weight:600;color:var(--ink)}
.risk-list{margin-top:20px;display:flex;flex-direction:column;gap:10px}
.risk-item{padding:10px 14px;border-radius:10px;border-left:4px solid}
.risk-item.critical{border-color:var(--coral);background:var(--t-coral)}
.risk-item.warning{border-color:#F59E0B;background:var(--t-amber)}
.risk-item .type{font-size:11px;font-family:var(--mono);color:var(--mute);text-transform:uppercase}
.risk-item .msg{font-size:13px;color:var(--ink);margin-top:4px}
.risk-item .suggestion{font-size:12px;color:var(--ink2);margin-top:4px;font-style:italic}
/* ========== REPORT (markdown) ========== */
.report-content{background:var(--card);border:1px solid var(--line);border-radius:14px;box-shadow:var(--shadow);
padding:28px 32px;line-height:1.75;font-size:14px;color:var(--ink)}
.report-content h1{font-family:var(--serif);font-weight:700;font-size:26px;margin:24px 0 12px;padding-bottom:8px;border-bottom:2px solid var(--line)}
.report-content h1:first-child{margin-top:0}
.report-content h2{font-family:var(--serif);font-weight:700;font-size:20px;margin:20px 0 10px;color:var(--ink)}
.report-content h3{font-weight:700;font-size:16px;margin:16px 0 8px;color:var(--ink2)}
.report-content p{margin:10px 0}
.report-content ul,.report-content ol{margin:8px 0;padding-left:24px}
.report-content li{margin:4px 0}
.report-content strong{font-weight:700;color:var(--ink)}
.report-content code{font-family:var(--mono);font-size:12.5px;background:var(--t-blue);padding:2px 6px;border-radius:4px;color:var(--indigo)}
.report-content table{width:100%;border-collapse:collapse;margin:12px 0;font-size:13px}
.report-content th{background:var(--t-blue);font-weight:600;text-align:left;padding:8px 12px;border:1px solid var(--line)}
.report-content td{padding:8px 12px;border:1px solid var(--line)}
/* ========== STRUCTURED CARDS ========== */
.cards-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(320px,1fr));gap:16px;margin-top:20px}
.conclusion-card{background:var(--card);border:1px solid var(--line);border-radius:12px;box-shadow:var(--shadow);
padding:16px 18px;border-top:4px solid}
.conclusion-card.innovation{border-top-color:var(--indigo)}
.conclusion-card.risk{border-top-color:var(--coral)}
.conclusion-card.collab{border-top-color:var(--mint)}
.conclusion-card .card-title{font-weight:700;font-size:14px;color:var(--ink);margin-bottom:8px}
.conclusion-card .card-body{font-size:13px;color:var(--ink2);line-height:1.55}
.conclusion-card .card-body p{margin:4px 0}
/* ========== LOADING STATE ========== */
.loading-state{display:flex;flex-direction:column;align-items:center;justify-content:center;padding:80px 20px;color:var(--mute);gap:16px}
.spin-lg{width:40px;height:40px;border-radius:50%;border:4px solid var(--t-blue);border-top-color:var(--indigo);animation:rot .8s linear infinite}
@keyframes rot{to{transform:rotate(360deg)}}
/* ========== ERROR ========== */
.error-state{padding:60px 20px;text-align:center;color:var(--coral)}
.error-state h2{font-family:var(--serif);font-size:24px;margin-bottom:12px}
.error-state p{font-size:14px;color:var(--ink2);max-width:500px;margin:0 auto}
/* empty */
.empty-state{padding:60px 20px;text-align:center;color:var(--mute)}
.empty-state p{font-size:14px}
</style>
</head>
<body>
<div class="page-wrap" id="app">
<div class="loading-state"><div class="spin-lg"></div><div>正在加载结果…</div></div>
</div>
<script>
mermaid.initialize({startOnLoad:false, theme:"base", securityLevel:"loose",
themeVariables:{primaryColor:"#E8EEFF",primaryTextColor:"#1E2A44",primaryBorderColor:"#4F6BED",lineColor:"#9DB4F0",fontSize:"13px"}});
const NODE_COLOR={repo:"#4F6BED",scholar:"#3B82F6",team:"#6366F1",topic:"#06B6D4",method:"#6366F1",
paper:"#8B5CF6",dataset:"#2EC4B6",model:"#4F6BED",experiment:"#F26B5E",
reproduce:"#2EC4B6",license:"#64748B",trend:"#F26B5E",issue:"#F59E0B",pr:"#10B981",default:"#94A3B8"};
const NODE_LABEL={repo:"仓库",scholar:"学者",topic:"主题",paper:"论文",dataset:"数据集",
model:"模型",experiment:"实验",reproduce:"复现",license:"许可证",trend:"趋势",issue:"Issue",pr:"PR"};
function esc(s){return String(s).replace(/[&<>]/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));}
function token(){return localStorage.getItem("demo_token")||"";}
function licOf(o){const l=o.license;if(!l)return o.license_id||"—";return typeof l==="string"?l:(l.id||l.name||l.spdx_id||l.identifier||"—");}
/* ========== Force layout (same as index) ========== */
function forceLayout(nodes,edges,W,H,iters){
const cx=W/2,cy=H/2;
nodes.forEach(n=>{if(n.x==null){n.x=cx+(Math.random()-.5)*W*.5;n.y=cy+(Math.random()-.5)*H*.5;}});
for(let it=0;it<iters;it++){
for(const n of nodes){n._fx=0;n._fy=0;}
for(let i=0;i<nodes.length;i++){for(let j=i+1;j<nodes.length;j++){
let dx=nodes[i].x-nodes[j].x,dy=nodes[i].y-nodes[j].y,d2=dx*dx+dy*dy+.02,d=Math.sqrt(d2),f=2600/d2,fx=dx/d*f,fy=dy/d*f;
nodes[i]._fx+=fx;nodes[i]._fy+=fy;nodes[j]._fx-=fx;nodes[j]._fy-=fy;}}
for(const e of edges){const a=nodes.find(n=>n.id===e[0]),b=nodes.find(n=>n.id===e[1]);if(!a||!b)continue;
let dx=b.x-a.x,dy=b.y-a.y,d=Math.sqrt(dx*dx+dy*dy)+.02,L=a.imp||b.imp?130:85,k=.04;
let f=(d-L)*k,fx=dx/d*f,fy=dy/d*f;a._fx+=fx;a._fy+=fy;b._fx-=fx;b._fy-=fy;}
for(const n of nodes){n._fx+=(cx-n.x)*.012;n._fy+=(cy-n.y)*.012;
n.x+=Math.max(-14,Math.min(14,n._fx));n.y+=Math.max(-14,Math.min(14,n._fy));
n.x=Math.max(45,Math.min(W-45,n.x));n.y=Math.max(38,Math.min(H-34,n.y));}}
}
function drawGraphIn(containerId,data){
const svg=document.getElementById(containerId); if(!svg) return;
const W=svg.clientWidth||800,H=svg.clientHeight||500;
svg.setAttribute("viewBox",`0 0 ${W} ${H}`);
let nodes=(data.nodes||[]).map(n=>Object.assign({},n));
let edges=(data.edges||[]).map(e=>Array.isArray(e)?e:[e.source||e.from,e.target||e.to]);
if(nodes.length>40){
const deg=new Map(nodes.map(n=>[n.id,0]));
edges.forEach(e=>{deg.set(e[0],(deg.get(e[0])||0)+1);deg.set(e[1],(deg.get(e[1])||0)+1);});
nodes.sort((a,b)=>(deg.get(b.id)||0)-(deg.get(a.id)||0));
const keep=new Set(nodes.slice(0,40).map(n=>n.id));nodes=nodes.filter(n=>keep.has(n.id));edges=edges.filter(e=>keep.has(e[0])&&keep.has(e[1]));
}
forceLayout(nodes,edges,W,H,300);
let s=`<defs><filter id="glow2"><feGaussianBlur stdDeviation="5" result="blur"/><feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge></filter></defs>`;
for(const e of edges){const a=nodes.find(n=>n.id===e[0]),b=nodes.find(n=>n.id===e[1]);if(!a||!b)continue;
s+=`<line class="g-edge" x1="${a.x.toFixed(1)}" y1="${a.y.toFixed(1)}" x2="${b.x.toFixed(1)}" y2="${b.y.toFixed(1)}"/>`;}
for(const n of nodes){const col=NODE_COLOR[n.type]||NODE_COLOR.default,r=n.imp?13:8;
s+=`<g class="g-node" transform="translate(${n.x.toFixed(1)},${n.y.toFixed(1)})"><circle r="${r}" fill="${col}"${n.imp?' filter="url(#glow2)"':""}/><text y="${r+13}">${esc(n.label||n.id).slice(0,18)}</text></g>`;}
svg.innerHTML=s;
}
function buildGraphLegend(types){
let h="";
for(const t of [...types].sort()){
h+=`<span class="leg-item"><span class="leg-dot" style="background:${NODE_COLOR[t]||NODE_COLOR.default}"></span>${NODE_LABEL[t]||t}</span>`;
}
return h;
}
/* ========== Simple markdown to HTML ========== */
function mdToHtml(md){
if(!md) return "";
let html=esc(md);
// code blocks
html=html.replace(/```(\w*)\n([\s\S]*?)```/g,'<pre><code>$2</code></pre>');
// inline code
html=html.replace(/`([^`]+)`/g,'<code>$1</code>');
// tables
html=html.replace(/^(\|.+\|)\n(\|[-:\s|]+\|)\n((?:\|.+\|\n?)*)/gm,function(_,hdr,sep,body){
const ths=hdr.split("|").filter(c=>c.trim()).map(c=>`<th>${c.trim()}</th>`).join("");
let rows="";
body.trim().split("\n").forEach(row=>{
const tds=row.split("|").filter(c=>c.trim()).map(c=>`<td>${c.trim()}</td>`).join("");
rows+=`<tr>${tds}</tr>`;
});
return `<table><thead><tr>${ths}</tr></thead><tbody>${rows}</tbody></table>`;
});
// headings
html=html.replace(/^### (.+)$/gm,'<h3>$1</h3>');
html=html.replace(/^## (.+)$/gm,'<h2>$1</h2>');
html=html.replace(/^# (.+)$/gm,'<h1>$1</h1>');
// bold
html=html.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
// unordered lists
html=html.replace(/^- (.+)$/gm,'<li>$1</li>');
html=html.replace(/(<li>.*<\/li>\n?)+/g,'<ul>$&</ul>');
// paragraphs (lines not inside tags)
html=html.replace(/^(?!<[huplo])((?!<).+)$/gm,'<p>$1</p>');
return html;
}
/* ========== MAIN RENDER ========== */
async function loadResult(){
const params=new URLSearchParams(window.location.search);
const scenario=params.get("scenario");
if(!scenario){
document.getElementById("app").innerHTML='<div class="error-state"><h2>缺少场景参数</h2><p>请从仪表盘点击场景，或手动打开 <code>result.html?scenario=s1</code></p></div>';
return;
}
let data;
try{
const r=await fetch("/api/result/"+encodeURIComponent(scenario),{headers:{"X-Demo-Token":token()}});
data=await r.json();
}catch(e){
document.getElementById("app").innerHTML='<div class="error-state"><h2>加载失败</h2><p>'+esc(e.message)+'</p><a class="back" href="index.html">返回仪表盘</a></div>';
return;
}
if(!data.ok){
document.getElementById("app").innerHTML='<div class="error-state"><h2>'+esc(data.error||"数据未就绪")+'</h2><p>请先在仪表盘运行该场景以生成结果。</p><a class="back" href="index.html">返回仪表盘</a></div>';
return;
}
const art=data.artifacts||{};
const obj=art.json?JSON.parse(art.json):null;
const owner=params.get("owner")||val_from("owner")||"";
const repo=params.get("repo")||val_from("repo")||"";
const keyword=params.get("keyword")||val_from("keyword")||"";
render(data,obj,art,scenario,owner,repo,keyword);
}
function val_from(name){try{return localStorage.getItem("atlas_"+name)||"";}catch(e){return"";}}
function render(data,obj,art,scenario,owner,repo,keyword){
const label=data.label||scenario;
const desc=data.desc||"";
const now=new Date().toLocaleString("zh-CN");
let h="";
// ---- HEADER ----
h+=`<div class="res-header">
<a class="back no-print" href="index.html">&#8592; 返回仪表盘</a>
<h1>${esc(label)}</h1>
<div class="sub">${esc(desc)}</div>
<div class="meta">`;
if(owner||repo) h+=`<span class="chip">仓库 <b>${esc(owner)}${repo?"/"+esc(repo):""}</b></span>`;
if(keyword) h+=`<span class="chip">关键词 <b>${esc(keyword)}</b></span>`;
h+=`<span class="chip">场景 <b>${esc(scenario)}</b></span>
<span class="chip">生成于 ${esc(now)}</span>
</div>
<div class="cmd-drawer no-print">
<div class="dots"><i style="background:#FF5F57"></i><i style="background:#FEBC2E"></i><i style="background:#28C840"></i></div>
<span style="color:var(--mint)">atlas &#10095;</span>
<span class="cmd">gitlink-cli research --scenario ${esc(scenario)} ${owner?"--repo "+esc(owner)+"/"+esc(repo):""} ${keyword?'-k "'+esc(keyword)+'"':""}</span>
</div></div>`;
// ---- METRICS ROW ----
const metrics=metricsFor(scenario,obj);
if(metrics){
h+=`<div class="section"><div class="section-title"><span class="eyebrow">Key Metrics</span>关键指标</div>
<div class="metrics-row">${metrics}</div></div>`;
}
// ---- MAIN VIZ ----
h+=`<div class="section"><div class="section-title"><span class="eyebrow">Visualization</span>可视化</div>`;
// S2: Knowledge Graph
if(scenario==="s2"&&obj&&obj.nodes&&obj.edges){
const graphNodes=obj.nodes.map(n=>({id:n.id,type:n.type||"default",label:n.label||n.id,imp:false}));
// highlight repo and high-degree nodes
const deg=new Map();
obj.edges.forEach(e=>{deg.set((e.source||e.from),(deg.get(e.source||e.from)||0)+1);deg.set((e.target||e.to),(deg.get(e.target||e.to)||0)+1);});
graphNodes.forEach(n=>{if(n.type==="repo"||deg.get(n.id)>3)n.imp=true;});
const graphEdges=obj.edges.map(e=>[e.source||e.from,e.target||e.to]);
const types=new Set(graphNodes.map(n=>n.type));
const gId="resGraph_"+Date.now();
h+=`<div class="graph-container">
<div class="graph-svg-wrap"><svg id="${gId}" preserveAspectRatio="xMidYMid meet"></svg></div>
<div class="graph-legend">${buildGraphLegend(types)}
<span class="leg-note">${esc(label)} — ${(obj.meta||{}).repo_count||graphNodes.length} 个仓库节点, ${(obj.meta||{}).edge_count||graphEdges.length} 条关联边</span>
</div></div>`;
// defer drawing
setTimeout(()=>drawGraphIn(gId,{nodes:graphNodes,edges:graphEdges}),100);
}
// S6: plotly
else if(scenario==="s6"&&art.html){
const blob=URL.createObjectURL(new Blob([art.html],{type:"text/html"}));
h+=`<div class="viz-container"><iframe src="${blob}"></iframe></div>`;
}
// S1/S4: mermaid
else if((scenario==="s1"||scenario==="s4")&&art.mermaid){
const mId="resMmd_"+Date.now();
const mmd=art.mermaid.replace(/```mermaid|```/g,"");
h+=`<div class="mmd-container"><div class="mermaid" id="${mId}">${esc(mmd)}</div></div>`;
setTimeout(()=>{const el=document.getElementById(mId);if(el)el.removeAttribute("data-processed");
mermaid.run({nodes:["#"+mId]}).catch(()=>{});},100);
}
// S3: radar / scores
else if(scenario==="s3"&&obj){
const rs=obj.repro_score||0;const cs=obj.compliance_score||0;
h+=`<div class="score-display">
<div class="score-circle repro"><span class="val">${rs}</span><span class="label">复现性 / 10</span></div>
<div class="score-circle compliance"><span class="val">${cs}</span><span class="label">合规性 / 10</span></div>
</div>`;
}
// S5: weekly comparison + risks
else if(scenario==="s5"&&obj){
const ws=obj.week_stats||{};
const tw=ws.this_week||{};const lw=ws.last_week||{};
const maxC=Math.max(tw.commits||0,lw.commits||0,1);
const maxP=Math.max(tw.prs_merged||0,lw.prs_merged||0,1);
const maxI=Math.max(tw.issues_closed||0,lw.issues_closed||0,1);
h+=`<div class="weekly-bars">
<div style="font-weight:700;font-size:14px;margin-bottom:8px;color:var(--ink)">本周 vs 上周 对比</div>
<div class="week-row"><span class="label">Commits</span><div class="bar-bg"><div class="bar-fill last-week" style="width:${(lw.commits/maxC*100||0).toFixed(1)}%"><span class="bar-val">${lw.commits||0}</span></div><div class="bar-fill this-week" style="width:${(tw.commits/maxC*100||0).toFixed(1)}%;position:relative;margin-top:-28px"><span class="bar-val">${tw.commits||0}</span></div></div></div>
<div class="week-row"><span class="label">PR merged</span><div class="bar-bg"><div class="bar-fill last-week" style="width:${(lw.prs_merged/maxP*100||0).toFixed(1)}%"><span class="bar-val">${lw.prs_merged||0}</span></div><div class="bar-fill this-week" style="width:${(tw.prs_merged/maxP*100||0).toFixed(1)}%;position:relative;margin-top:-28px"><span class="bar-val">${tw.prs_merged||0}</span></div></div></div>
<div class="week-row"><span class="label">Issues</span><div class="bar-bg"><div class="bar-fill last-week" style="width:${(lw.issues_closed/maxI*100||0).toFixed(1)}%"><span class="bar-val">${lw.issues_closed||0}</span></div><div class="bar-fill this-week" style="width:${(tw.issues_closed/maxI*100||0).toFixed(1)}%;position:relative;margin-top:-28px"><span class="bar-val">${tw.issues_closed||0}</span></div></div></div>
</div>`;
// risk warnings
const risks=obj.risk_warnings||[];
if(risks.length){
h+=`<div style="margin-top:20px;font-weight:700;font-size:14px;color:var(--ink)">风险预警</div><div class="risk-list">`;
risks.forEach(r=>{const cls=r.level==="critical"?"critical":"warning";
h+=`<div class="risk-item ${cls}"><div class="type">${esc(r.level||"")} · ${esc(r.type||"")}</div><div class="msg">${esc(r.message||"")}</div>${r.suggestion?`<div class="suggestion">${esc(r.suggestion)}</div>`:""}</div>`;});
h+=`</div>`;
}
}
else{
h+=`<div class="empty-state"><p>该场景无可视化产物，详见下方报告。</p></div>`;
}
h+=`</div>`;
// ---- REPORT ----
if(art.report){
h+=`<div class="section"><div class="section-title"><span class="eyebrow">Full Report</span>完整报告</div>
<div class="report-content">${mdToHtml(art.report)}</div></div>`;
}
// ---- STRUCTURED CONCLUSION CARDS ----
const conclusions=buildConclusionCards(scenario,obj);
if(conclusions){
h+=`<div class="section"><div class="section-title"><span class="eyebrow">Conclusions</span>结构化结论</div>
<div class="cards-grid">${conclusions}</div></div>`;
}
document.getElementById("app").innerHTML=h;
}
/* ========== METRICS ========== */
function metricCard(label,val,note){
return `<div class="metric-card"><div class="label">${esc(label)}</div><div class="value">${esc(String(val))}</div><div class="note">${esc(note||"")}</div></div>`;
}
function metricsFor(key,o){
if(!o) return "";
const M=o.meta||{};
switch(key){
case "s1": return metricCard("commits",M.commit_count||0,"采样提交")+metricCard("merged PR",M.merged_pr_count||0,"已合并")+metricCard("docs",M.doc_count||0,"文档文件")+metricCard("创新点",(o.innovation_points||[]).length,"高影响合并");
case "s2": return metricCard("repos",M.repo_count||(o.nodes||[]).length,"仓库节点")+metricCard("scholars",M.scholar_count||0,"学者")+metricCard("topics",M.topic_count||0,"主题方向")+metricCard("edges",M.edge_count||(o.edges||[]).length,"关系边");
case "s3": return metricCard("复现性",(o.repro_score||0)+"/10","reproducibility")+metricCard("合规性",(o.compliance_score||0)+"/10","compliance")+metricCard("风险项",(o.risks||o.risk_items||[]).length,"项")+metricCard("许可证",esc(licOf(o)),"识别");
case "s4": return metricCard("缺口主题",(o.gap_topics||[]).length,"gap topics")+metricCard("推荐候选",(o.candidates||[]).length,"candidates")+metricCard("最高匹配",o.candidates&&o.candidates[0]?o.candidates[0].score:0,"top score")+metricCard("候选池",o.meta&&o.meta.pool_size||0,"pool size");
case "s5":{const tw=(o.week_stats&&o.week_stats.this_week)||{};return metricCard("本周 commits",tw.commits||0,"")+metricCard("预警",(o.risk_warnings||[]).length,"risks")+metricCard("PR 合并",tw.prs_merged||0,"")+metricCard("活跃度",(o.trend&&o.trend.activity_level)||"—","");}
case "s6":{const tl=o.timeline||{};const sm=a=>(a||[]).reduce((x,y)=>x+(y||0),0);return metricCard("周数",(tl.labels||[]).length,"")+metricCard("commits",sm(tl.commits),"")+metricCard("PRs",sm(tl.prs),"")+metricCard("issues",sm(tl.issues),"");}
}
return "";
}
/* ========== CONCLUSION CARDS ========== */
function buildConclusionCards(key,o){
if(!o) return "";
let cards="";
switch(key){
case "s1":{
const ips=o.innovation_points||[];
if(ips.length){
cards+=`<div class="conclusion-card innovation"><div class="card-title">&#128161; 创新点 (${ips.length})</div><div class="card-body">`;
ips.slice(0,8).forEach(i=>{cards+=`<p><strong>[${esc(i.category)}]</strong> ${esc(i.description)}<br><small style="color:var(--mute)">${esc(i.evidence||"")}</small></p>`;});
cards+=`</div></div>`;
}
break;}
case "s2":{
const scholars=o.core_scholars||[];
if(scholars.length){
cards+=`<div class="conclusion-card collab"><div class="card-title">&#128101; 核心学者</div><div class="card-body">`;
scholars.slice(0,6).forEach(s=>{cards+=`<p><strong>${esc(s.login)}</strong> — ${s.repo_count} 个仓库</p>`;});
cards+=`</div></div>`;
}
const topics=o.topic_heat||[];
if(topics.length){
cards+=`<div class="conclusion-card innovation"><div class="card-title">&#128293; 热门主题</div><div class="card-body">`;
topics.slice(0,6).forEach(t=>{cards+=`<p><strong>${esc(t.topic)}</strong> — ${t.count} 个仓库</p>`;});
cards+=`</div></div>`;
}
break;}
case "s3":{
const risks=o.risk_items||o.risks||[];
if(risks.length){
cards+=`<div class="conclusion-card risk"><div class="card-title">&#9888;&#65039; 风险项 (${risks.length})</div><div class="card-body">`;
risks.slice(0,8).forEach(r=>{
const lvl=(r.level||"").includes("high")||r.severity==="P0"?"&#x1F534;":"&#x1F7E1;";
cards+=`<p>${lvl} <strong>${esc(r.category||r.name||"")}</strong> — ${esc(r.detail||r.evidence||"")}</p>`;});
cards+=`</div></div>`;
}
break;}
case "s4":{
const cands=o.candidates||[];
if(cands.length){
cards+=`<div class="conclusion-card collab"><div class="card-title">&#129309; 协作推荐 (${cands.length})</div><div class="card-body">`;
cands.slice(0,6).forEach((c,i)=>{cards+=`<p><strong>#${i+1} ${esc(c.login)}</strong> (${c.score}分)<br><small>${(c.reasons||[]).join("；")}</small></p>`;});
cards+=`</div></div>`;
}
const gaps=o.gap_topics||[];
if(gaps.length){
cards+=`<div class="conclusion-card innovation"><div class="card-title">&#128270; 缺口主题 (${gaps.length})</div><div class="card-body">`;
gaps.slice(0,6).forEach(g=>{cards+=`<p>${esc(typeof g==="string"?g:(g.topic||g.name||JSON.stringify(g)))}</p>`;});
cards+=`</div></div>`;
}
break;}
case "s5":{
const risks=o.risk_warnings||[];
if(risks.length){
cards+=`<div class="conclusion-card risk"><div class="card-title">&#9888;&#65039; 风险预警 (${risks.length})</div><div class="card-body">`;
risks.slice(0,6).forEach(w=>{cards+=`<p><strong>[${esc(w.type)}]</strong> ${esc(w.message)}${w.suggestion?"<br><small>"+esc(w.suggestion)+"</small>":""}</p>`;});
cards+=`</div></div>`;
}
const trend=o.trend||{};
cards+=`<div class="conclusion-card innovation"><div class="card-title">&#128200; 活跃趋势</div><div class="card-body"><p>commit 变化: <strong>${trend.commit_delta_pct||"—"}</strong></p><p>活跃度: <strong>${esc(trend.activity_level||"—")}</strong></p></div></div>`;
break;}
case "s6":{
const tl=o.timeline||{};
cards+=`<div class="conclusion-card innovation"><div class="card-title">&#128202; 数据概览</div><div class="card-body"><p>时间线: ${(tl.labels||[]).length} 周</p><p>语言分布: ${(o.language_pie||[]).length} 类</p><p>累计 commits: ${(tl.commits||[]).reduce((a,b)=>a+(b||0),0)}</p></div></div>`;
break;}
}
return cards;
}
/* go */
loadResult();
</script>
</body>
</html>

68
cmd/status/status.go Normal file
View File

@ -0,0 +1,68 @@
package status
import (
"fmt"
"os"
"github.com/spf13/cobra"
"github.com/gitlink-org/gitlink-cli/internal/auth"
"github.com/gitlink-org/gitlink-cli/internal/config"
"github.com/gitlink-org/gitlink-cli/internal/context"
)
// NewStatusCmd creates the status command that displays login state and context.
func NewStatusCmd() *cobra.Command {
return &cobra.Command{
Use: "status",
Short: "显示当前登录状态和上下文信息",
Long: `显示 gitlink-cli 的当前状态，包括：
- 认证状态（是否已登录、Token 来源）
- API 地址
- 当前目录
- 自动推断的仓库信息`,
Example: ` gitlink-cli status`,
RunE: func(cmd *cobra.Command, args []string) error {
cfg, _ := config.Load()
token, _ := auth.LoadToken()
if token == "" {
token = os.Getenv("GITLINK_TOKEN")
}
cwd, _ := os.Getwd()
fmt.Println("GitLink CLI 状态")
fmt.Println("───────────────")
// 认证状态
if token != "" {
fmt.Println(" 认证状态: 已登录")
fmt.Printf(" Token 来源: %s\n", tokenSource(token))
} else {
fmt.Println(" 认证状态: 未登录（运行 gitlink-cli auth login）")
}
// API 地址
fmt.Printf(" API 地址: %s\n", cfg.BaseURL)
// 当前目录
fmt.Printf(" 当前目录: %s\n", cwd)
// 推断的仓库
owner, repo, err := context.ResolveOwnerRepo("", "")
if err == nil {
fmt.Printf(" 推断仓库: %s/%s\n", owner, repo)
} else {
fmt.Println(" 推断仓库: （不在 Git 仓库中）")
}
return nil
},
}
}
func tokenSource(token string) string {
if token == os.Getenv("GITLINK_TOKEN") {
return "环境变量 GITLINK_TOKEN"
}
return "keyring / 配置文件"
}

58
cmd/status/status_test.go Normal file
View File

@ -0,0 +1,58 @@
package status
import (
"strings"
"testing"
)
func TestNewStatusCmd(t *testing.T) {
cmd := NewStatusCmd()
if cmd.Use != "status" {
t.Errorf("expected Use 'status', got %s", cmd.Use)
}
if cmd.Short == "" {
t.Error("Short description should not be empty")
}
if cmd.Long == "" {
t.Error("Long description should not be empty")
}
}
func TestNewStatusCmdExample(t *testing.T) {
cmd := NewStatusCmd()
if !strings.Contains(cmd.Example, "status") {
t.Errorf("Example should contain 'status', got: %s", cmd.Example)
}
}
func TestNewStatusCmdHasNoSubcommands(t *testing.T) {
cmd := NewStatusCmd()
if cmd.HasSubCommands() {
t.Error("status should not have subcommands")
}
}
func TestTokenSourceFromEnv(t *testing.T) {
t.Setenv("GITLINK_TOKEN", "test-token-123")
result := tokenSource("test-token-123")
if result != "环境变量 GITLINK_TOKEN" {
t.Errorf("expected env source, got: %s", result)
}
}
func TestTokenSourceFromKeyring(t *testing.T) {
// 不设置环境变量，或用不同的值
t.Setenv("GITLINK_TOKEN", "")
result := tokenSource("some-stored-token")
if result != "keyring / 配置文件" {
t.Errorf("expected keyring source, got: %s", result)
}
}
func TestTokenSourceMismatch(t *testing.T) {
t.Setenv("GITLINK_TOKEN", "env-token")
result := tokenSource("different-token")
if result != "keyring / 配置文件" {
t.Errorf("should fallback to keyring when token differs from env, got: %s", result)
}
}

29
demo/Dockerfile Normal file
View File

@ -0,0 +1,29 @@
# demo/Dockerfile — GitLink CLI 演示网页后端
# 多阶段：Go 编译 Linux 二进制 → Python 运行时跑 server.py
# 构建上下文 = 仓库根（gitlink-cli/）： docker build -f demo/Dockerfile -t gitlink-cli-demo .
# ---------- Stage 1: 编译 gitlink-cli（Linux） ----------
FROM golang:1.26-alpine AS builder
ENV GOPROXY=https://goproxy.cn,direct
ENV CGO_ENABLED=0 GOOS=linux GOARCH=amd64
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -ldflags="-s -w" -o /out/gitlink-cli .
# ---------- Stage 2: Python 运行时 ----------
FROM python:3.11-alpine
RUN apk add --no-cache git ca-certificates
WORKDIR /app
# 二进制
COPY --from=builder /out/gitlink-cli /usr/local/bin/gitlink-cli
# 演示网页 + Skills（server.py 要读 SKILL.md）
COPY demo/ /app/demo/
COPY skills/ /app/skills/
ENV HOST=0.0.0.0
ENV PORT=8000
ENV GITLINK_BIN=/usr/local/bin/gitlink-cli
EXPOSE 8000
WORKDIR /app/demo/web
CMD ["python3", "server.py"]

100
demo/README.md Normal file
View File

@ -0,0 +1,100 @@
# GitLink CLI · 演示网页（demo/）
> 一个**可交互演示站**，展示子任务一~四全部成果：25 域命令浏览器、48 Skill 卡片墙、pr-guard 工作流、科研四维画像。
> 后端 `web/server.py`（Python 标准库，零依赖）能真跑 `gitlink-cli`；**访客自带 token，零凭据上云端**。
## 目录结构
```
demo/
├── web/ # 演示网页（核心）
│ ├── server.py # Python 后端（/api/run /api/skill /api/analyze）
│ ├── index.html # 前端单页（Tailwind+Chart.js CDN）
│ └── README.md # 网页本地启动说明
├── Dockerfile # demo 部署镜像（Go 编译 + Python 运行时）
├── build-demo.sh # 本地一键产 Linux 二进制（测 Dockerfile 用）
├── research-insight-workflow.sh # 任务四：科研画像端到端脚本
├── pr-guard-workflow.sh # 任务三：质量看门人脚本
├── live-demo.sh / snippet-live-demo.sh
└── *.md # 各任务指南 + 验证记录 + 报告原件
```
---
## 一、本地跑（Windows / Linux / macOS）
```bash
# 1. 编译 CLI（仓库根）
cd gitlink-cli # 含 go.mod 的仓库根
go build -o gitlink-cli . # Windows 产出 gitlink-cli.exe
# 2. 启动后端
cd demo/web
python server.py # → http://0.0.0.0:8000
# 3. 浏览器开 http://localhost:8000
# 顶栏粘自己的 GitLink token → 平台命令真跑；snippet 等本地命令免 token
```
> 二进制自动探测：`GITLINK_BIN` > 仓库根 `gitlink-cli[.exe]` > PATH。
> 端口/主机：`PORT=9000 HOST=127.0.0.1 python server.py`。
---
## 二、云端部署（用你们已有服务器 121.41.222.73）
已配置好「**push 即上线**」：`.devops/自动构建部署.yml` 在 push 到 master 后，SSH 到服务器增量拉取并**自动构建启动两个服务**：
| 端口 | 服务 | 镜像 | 入口 |
|:---:|------|------|------|
| **:8080** | 任务四科研网页终端 | 根 `Dockerfile`（Go + Python） | `gitlink-cli server --port 8080`（调 `scripts/research/` 跑 S1–S6） |
| **:8000** | 综合能力展示站（本 demo） | `demo/Dockerfile` | `python3 demo/web/server.py` |
```
# ssh_cmd_0：根 Dockerfile → :8080（带 --env-file /root/.gitlink-env 注入 token）
docker build -t gitlink-cli:latest . && docker run -d --name gitlink-cli -p 8080:8080 --env-file /root/.gitlink-env gitlink-cli:latest
# ssh_cmd_1：demo Dockerfile → :8000（非阻塞，失败不影响 :8080）
docker build -f demo/Dockerfile -t gitlink-cli-demo . && docker run -d --name gitlink-cli-demo -p 8000:8000 --restart unless-stopped gitlink-cli-demo
```
**你只需（一次性服务器侧准备）**：
1. 阿里云安全组/防火墙**开放 8080 + 8000** 两条入方向 TCP 规则。
2. 在服务器建 `/root/.gitlink-env`，内容 `GITLINK_TOKEN=你的令牌`（供 :8080 科研终端调平台 API；:8000 展示站不需要，访客自带 token）。
3. 之后每次 `git push origin master` → CI 自动重建双服务 → 直接打开网址：
- 科研终端 `http://121.41.222.73:8080`
- 综合展示 `http://121.41.222.73:8000`
> 手动部署（不走 CI）：SSH 到服务器，`cd /root/gitlink-cli` 后分别跑上面两条 docker 命令。
### 镜像里有什么（demo/Dockerfile 多阶段）
- Stage1 `golang:1.26-alpine`：`CGO_ENABLED=0 GOOS=linux go build` 产 Linux 二进制。
- Stage2 `python:3.11-alpine`：装 `git`/`ca-certificates`，放二进制到 `/usr/local/bin/gitlink-cli`，拷 `demo/` 和 `skills/`，`ENV PORT=8000`，`CMD python3 demo/web/server.py`。
---
## 三、安全模型（为什么能放心公网开放）
| 点 | 做法 |
|----|------|
| 团队 token | **不烘焙**进镜像/代码。镜像里没有任何 GitLink 凭据。 |
| 访客 token | 只存在访客自己的浏览器 localStorage，按请求传后端 → 注入子进程 `GITLINK_TOKEN` → 用完即弃，**不落盘、不写日志**。 |
| 命令注入 | 后端白名单（仅 30 个 gitlink-cli 顶层域）+ subprocess 列表参数（不经 shell）+ 30s 超时。 |
| 写操作 | CLI 写操作本就要 `--dry-run`/确认；演示页默认只点只读命令。 |
→ 公网开放的安全风险≈0：泄露的至多是访客自己输错的那一次请求。
---
## 四、访客怎么用（写进 PPT/答辩）
1. 打开 `http://121.41.222.73:8000`。
2. 顶栏粘自己的 GitLink 个人访问令牌（GitLink → 个人中心 → 个人令牌）。
3. 点「命令域」里任意动词 → 终端真跑；或点 Skill 卡片读 SKILL.md；或科研区「实拉分析」任一仓库。
---
## 五、其它 PaaS 部署（可选，不占你们服务器）
也可部署到 Render / Railway / Koyeb 等（需能跑 Docker）：
- 用 `demo/Dockerfile`，暴露端口环境变量 `PORT`（已支持）。
- 这些平台默认按其给的端口注入 `PORT`，server.py 已读 `PORT` 环境变量，无需改。

96
demo/SHOWCASE.md Normal file
View File

@ -0,0 +1,96 @@
# Skills 功能验收演示文稿
> 用法：照此 5 分钟流程演示。**Demo 1 可现场实跑**（零依赖、最稳），其余讲解设计。
> 配套：`snippet-live-demo.sh`（实演脚本）、`../Skills工作总结.md`（完整成果）
---
## 演示总览（5 分钟）
| 环节 | 时长 | 形式 | 目的 |
|------|:----:|------|------|
| 开场：Skills 是什么 | 30s | 口述 + 成果速览 | 讲清价值定位 |
| **Demo 1 · snippet 实演** | 1.5min | **跑脚本** | 证明 Skill 真能驱动 CLI |
| Demo 2 · onboarding 设计 | 1.5min | 打开 SKILL.md 讲 | 展示 AI 工作流设计深度 |
| Demo 3 · digest/todo 体验优化 | 1min | 讲设计 + 分工 | 展示体验优化与去重思考 |
| 收尾：成果 + 验证 | 30s | 数字 | 强化贡献 |
---
## 开场（30 秒）
> 一句话：**Skills 是写给 AI 的「菜谱」**——告诉 AI「什么场景、按什么顺序、调哪些 gitlink-cli 命令」。我们把 gitlink-cli 从「开发者工具」升级为「AI 可驱动的平台」。
>
> 本次新增 **5 个 Skill** + 补全 **28 个 examples** + snippet **7 命令端到端实测通过**。
---
## Demo 1 · snippet 现场实演（核心，必演）
```bash
bash demo/snippet-live-demo.sh
```
**脚本会演示的闭环**（每个场景都展示「🧑用户提问 → 🤖AI 读 SKILL.md 决策 → 执行命令 → 输出」）：
| 场景 | 命令 | SKILL.md 规则 |
|------|------|--------------|
| 保存代码 | `snippet +create` | --title 必填、--tags 逗号分隔 |
| 浏览 | `snippet +list` | 可按 tag/language 过滤 |
| 检索 | `snippet +search` | 全文匹配 |
| 详情 | `snippet +view` | 按 id |
| 导出 | `snippet +export` | -o 写文件 |
| 更新 | `snippet +update` | 至少一个字段 |
| 删除 | `snippet +delete` | 不可逆，先确认 |
**讲解要点**：注意每个场景 AI 都先「读 SKILL.md 决策」再执行——这就是 Skills 的核心价值，**AI 不是瞎调命令，而是按菜谱编排**。输出严格符合 `{"ok":true,"data":{...}}` 格式。
---
## Demo 2 · onboarding 设计深度（展示 B 类工作流）
**操作**：打开 `gitlink-cli/gitlink-cli/skills/gitlink-onboarding/SKILL.md`
**重点讲三处**（评分重点）：
1. **5 维度友好度评估表**（决策规则章节）——把「哪个 Issue 适合新人」从主观判断变成可量化打分：标题清晰度 / 描述完整度 / 代码定位 / 改动范围 / 难度标签。
2. **4 个工作流**——项目概览 → 找任务 → 生成引导评论 → 贡献全流程（Fork→Branch→PR）。
3. **引导评论输出模板**——AI 能自动生成「欢迎贡献 + 代码定位 + 修改步骤」的个性化评论。
> 一句话：A 类（命令包装）做不到「智能推荐 + 生成评论」，所以选 B 类（AI 工作流）。
---
## Demo 3 · digest / todo 体验优化（展示第二批 + 去重思考）
| Skill | 解决的痛点 | 与团队已有 Skill 的关系 |
|-------|-----------|----------------------|
| `gitlink-digest` | 信息太分散，看动态要挨个刷 | 与团队 `notification-digest` **分工**：它做通知中心，我做项目全景日报（Issue+PR+CI+活跃度） |
| `gitlink-todo` | 没有「我的」视角，不知哪些在等我 | 团队**无对应**，真缺口 |
**去重思考（加分点）**：曾设计「僵尸唤醒 stale」，核查发现团队已有完整的 `gitlink-stale-issue-manager`（563 行），为避免重复造已删除——**体现对项目整体的理解和工程素养**。
---
## 收尾：成果 + 验证（30 秒）
| 指标 | 数据 |
|------|------|
| 新增 Skill | **5 个**（onboarding / auth / snippet / digest / todo） |
| 补充 examples | **28 个**（23 个补已有 Skill + 5 个新增自带） |
| 端到端实测 | snippet 全 7 命令通过 |
| 命令可调用性 | 新增 Skill 全用已注册命令域，可真实调用 |
> 演示结束。完整设计详见 `Skills工作总结.md`。
---
## 答辩 Q&A 预备
| 可能的提问 | 回答要点 |
|-----------|---------|
| 工作边界？ | 新增 5 个 Skill + 补 23 个 examples；团队原有 42 个（见总结第二节） |
| 怎么证明 Skill 真能用？ | 刚跑的 snippet 7 命令闭环；其余 4 个登录后可按 SKILL.md 工作流验证 |
| 为什么 onboarding 选 B 类？ | 需智能推荐 + 生成评论，A 类命令包装做不到 |
| digest 和团队 notification-digest 重复吗？ | 不重复，分工明确：通知中心 vs 项目全景日报 |
| Skill 遵循什么规范？ | 项目模板：YAML frontmatter + CRITICAL 三连 + 引用 gitlink-shared |

13
demo/build-demo.sh Normal file
View File

@ -0,0 +1,13 @@
#!/usr/bin/env bash
# 一键构建 demo 所需的 Linux gitlink-cli 二进制（本地测试 Dockerfile 用）
# 用法：bash demo/build-demo.sh → 产物 demo/bin/gitlink-cli
set -e
DIR="$(cd "$(dirname "$0")" && pwd)"
ROOT="$(cd "$DIR/.." && pwd)" # 仓库根
OUT="$DIR/bin"
mkdir -p "$OUT"
echo "→ 在 $ROOT 编译 Linux amd64 二进制..."
( cd "$ROOT" && CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -ldflags="-s -w" -o "$OUT/gitlink-cli" . )
echo "✓ 产出：$OUT/gitlink-cli"
echo " 本地测容器：docker build -f $DIR/Dockerfile -t gitlink-cli-demo '$ROOT'"
echo " docker run --rm -p 8000:8000 gitlink-cli-demo"

146
demo/live-demo-guide.md Normal file
View File

@ -0,0 +1,146 @@
# 4 个 Skill 登录实演指南（onboarding / digest / todo / auth）
> 用法：登录后，**在 Claude Code 里用自然语言触发**，让真 AI 读 SKILL.md 自主编排 —— 这是最强的实演证据。
> 配套：`live-demo.sh`（辅助采集脚本，不想手敲命令时用）。
---
## 〇、前置准备
1. **登录**：`gitlink-cli auth login`（或 `--token`），用 `gitlink-cli auth status` 确认已登录
2. **准备测试仓库**：用一个你自己的/有权限的公开仓库作为演示对象（避免在团队主仓库留痕）
3. **开着 Claude Code**：在本仓库目录下启动，让 AI 能读到 `skills/*/SKILL.md`
4. **安全原则**：只读命令随便跑；写操作（评论/关闭）让 AI 先 `--dry-run` 或确认
---
## 〇〇、推荐演示方式：自然语言触发真 AI（最有说服力）
> 不要告诉 AI 用哪个命令，只描述需求。看它是否**自主读 SKILL.md → 调对命令 → 输出符合模板**。
> 这是"Skills 让 AI 能驱动 CLI"的活证据，比手敲命令强得多。
每个 Skill 下面都给：**① 触发语**（你对 AI 说这句）→ **② 预期 AI 行为** → **③ 手动备选**（想自己跑时）→ **④ 讲解要点**。
---
## 一、auth 实演（最简单，开场暖身）
**① 触发语**：
> "检查一下我的 gitlink 登录状态"
**② 预期 AI 行为**：读 `auth/SKILL.md` → 调 `gitlink-cli auth status` → 报告登录用户、Token 有效期、存储位置。
**③ 手动备选**：
```bash
gitlink-cli auth status
gitlink-cli auth login --token # 如需演示登录流程
```
**④ 讲解要点**：
- auth Skill 与 `gitlink-shared` 分工：shared 讲认证原理，auth 讲具体命令操作
- 决策树：遇到 401 → 引导 `auth login`；403 → 查权限；CI 环境 → 用 `--token`
- 演示 `logout` 后提醒：会清凭证，需重新登录
---
## 二、onboarding 实演（核心亮点：5 维度评估）
**① 触发语**：
> "我想参与 <owner>/<repo> 这个项目，帮我找几个适合新手的任务"
**② 预期 AI 行为**：读 `onboarding/SKILL.md` →
1. `search +issues --keyword "good first issue" --category opened`（找新手 Issue）
2. `repo +info` + `repo +readme`（项目概览）
3. 对候选 Issue 做 **5 维度友好度评估**（标题/描述/定位/范围/难度）
4. 输出「推荐新手任务」清单 + 可选生成引导评论
**③ 手动备选**：
```bash
gitlink-cli search +issues --owner <owner> --repo <repo> --keyword "good first issue" --category opened
gitlink-cli repo +info --owner <owner> --repo <repo>
gitlink-cli repo +readme --owner <owner> --repo <repo>
```
**④ 讲解要点**：
- **5 维度评估表**是设计亮点：把"哪个 Issue 适合新人"从主观判断变成可量化打分（指着 AI 输出的评分讲）
- 引导评论模板：AI 能生成「欢迎贡献 + 代码定位 + 修改步骤」个性化评论（写操作，会先确认）
- 若无 good-first-issue 标签：AI 应从开放 Issue 推荐最简单的（决策规则）
---
## 三、digest 实演（亮点：跨源聚合成简报）
**① 触发语**：
> "给我一份 <owner>/<repo> 的项目简报，今天有什么动态"
**② 预期 AI 行为**：读 `digest/SKILL.md` → 并行采集 → 聚合分类 →
1. `issue +list --state open` + `pr +list`（Issue/PR 动态）
2. `ci +builds`（CI 状态）
3. `api GET "users/<me>/messages.json"`（通知）
4. 按 🔴需关注 / 🟢新增 / 🔵进行中 / 📊指标 分类，输出 Markdown 简报
**③ 手动备选**：
```bash
gitlink-cli issue +list --state open --format json
gitlink-cli pr +list --format json
gitlink-cli ci +builds --owner <owner> --repo <repo> --format json
gitlink-cli api GET "users/<me>/messages.json"
```
**④ 讲解要点**：
- **跨源聚合**是亮点：一份简报汇总 Issue/PR/CI/通知，不用挨个刷
- 与团队 `notification-digest` 分工：它做通知中心（标记已读），digest 做项目全景（不做标记已读）—— 体现去重思考
- 纯只读，安全可随时跑
---
## 四、todo 实演（亮点：补上「我的」视角）
**① 触发语**：
> "我的待办有哪些？哪些 Issue/PR 在等我处理"
**② 预期 AI 行为**：读 `todo/SKILL.md` →
1. `api GET "users/me"`（识别身份）
2. `search +issues --assignee <me> --category opened`（分配我的）
3. `api GET "users/<me>/messages.json"`（@我的）
4. `pr +list`（我的 PR 状态）
5. 按紧急度（@我 > 待 review > 指派）排序，输出待办清单
**③ 手动备选**：
```bash
gitlink-cli api GET "users/me" --format json
gitlink-cli search +issues --assignee <me> --category opened
gitlink-cli api GET "users/<me>/messages.json"
```
**④ 讲解要点**：
- **「我的」视角**是 gitlink 最缺的：跨 Issue/PR 汇总个人待办
- 紧急度排序逻辑：@我且停留 >24h → 🔴紧急；待 review 的 PR → 🟡本周
- 团队无对应 Skill，是真正的新增价值
---
## 五、验收串场词（5 分钟版）
```
开场（30s）：Skills 让 AI 能驱动 gitlink-cli。先看 snippet 实演（跑 snippet-live-demo.sh）。
转场：snippet 是本地功能。接下来演示需要平台 API 的 4 个 Skill，
我用自然语言提问，看 AI 是否自主读 SKILL.md 编排命令。
① auth（30s）：「检查登录状态」→ AI 调 auth status。
② onboarding（1.5min）：「找新手任务」→ AI 5 维度评估出推荐清单。（重点讲评估表）
③ digest（1.5min）：「给我项目简报」→ AI 跨源聚合出报告。（重点讲与团队分工）
④ todo（1min）：「我的待办」→ AI 汇总排序。（重点讲个人视角是缺口）
收尾（30s）：5 个新增 Skill 都能被 AI 正确调用，snippet 7 命令实测通过。
```
---
## 六、安全清单（实演前确认）
- [ ] 用**测试仓库**演示，不用团队主仓库
- [ ] 写操作（onboarding 引导评论、issue close）让 AI **先确认 / --dry-run**
- [ ] 演示完 `auth logout` 的话，记得重新登录
- [ ] 只读命令（list/view/search/info/messages）可放心反复跑

59
demo/live-demo.sh Normal file
View File

@ -0,0 +1,59 @@
#!/usr/bin/env bash
# ============================================================
# 4 个 Skill 登录实演 · 辅助采集脚本
# 作用：把每个 Skill 的「只读采集命令」串起来自动跑，展示真实数据
# 分析（评估/聚合/排序）部分由 AI 在 Claude Code 里做——那才是亮点
# 用法：bash demo/live-demo.sh <owner> <repo> [your-username]
# 例：bash demo/live-demo.sh myorg myproject zhangsan
# 前置：先 gitlink-cli auth login
# ============================================================
_DIR="$(cd "$(dirname "$0")" && pwd)"
CLI="$_DIR/../gitlink-cli.exe"; [ -f "$CLI" ] || CLI="$_DIR/../gitlink-cli" # Win→.exe，Linux→无后缀
OWNER="${1:-}"; REPO="${2:-}"; ME="${3:-$OWNER}"
G='\033[0;32m'; Y='\033[1;33m'; C='\033[0;36m'; R='\033[0;31m'; B='\033[1m'; N='\033[0m'
banner() { echo -e "\n${B}══════════════════════════════════════════════════════${N}"; echo -e "${B} $1${N}"; echo -e "${B}══════════════════════════════════════════════════════${N}"; }
section() { echo -e "\n${C}━━━ $1 ━━━${N}"; }
run() { echo -e "${Y}❯ $1${N}"; eval "$1" 2>&1 | head -16; echo; }
# ---------- 前置检查 ----------
banner "4 Skill 登录实演 · 辅助采集"
[ -f "$CLI" ] || { echo -e "${R}✗ 找不到 gitlink-cli${N}"; exit 1; }
if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
echo -e "${R}用法: bash $0 <owner> <repo> [your-username]${N}"
echo -e "${R}例 : bash $0 myorg myproject zhangsan${N}"; exit 1
fi
echo -e "${G}✓${N} 目标仓库: ${B}$OWNER/$REPO${N}，当前用户: ${B}$ME${N}"
echo -e "${C}提示：本脚本只跑只读采集命令；分析（评估/聚合/排序）请在 Claude Code 里让 AI 做${N}"
# ---------- 0. auth：登录状态 ----------
section "auth · 登录状态"
run "\"$CLI\" auth status"
# ---------- 1. onboarding：找新手任务 ----------
section "onboarding · 新手 Issue + 项目概览（供 AI 做 5 维度评估）"
run "\"$CLI\" search +issues --owner $OWNER --repo $REPO --keyword 'good first issue' --category opened --format json"
run "\"$CLI\" repo +info --owner $OWNER --repo $REPO --format json"
# ---------- 2. digest：多源数据（供 AI 聚合成简报）----------
section "digest · Issue / PR / CI / 通知（供 AI 跨源聚合）"
run "\"$CLI\" issue +list --owner $OWNER --repo $REPO --state open --format json"
run "\"$CLI\" pr +list --owner $OWNER --repo $REPO --format json"
run "\"$CLI\" ci +builds --owner $OWNER --repo $REPO --format json"
run "\"$CLI\" api GET \"users/$ME/messages.json\""
# ---------- 3. todo：个人待办数据（供 AI 排序）----------
section "todo · 分配给我的 Issue + @我消息（供 AI 排序成待办）"
run "\"$CLI\" api GET \"users/me\" --format json"
run "\"$CLI\" search +issues --assignee $ME --category opened --format json"
run "\"$CLI\" api GET \"users/$ME/messages.json\""
# ---------- 总结 ----------
banner "采集完成"
echo -e "${B}接下来${N}：在 Claude Code 里用自然语言触发，让 AI 读对应 SKILL.md 分析以上数据："
echo -e " • ${C}「找适合新手的任务」${N} → onboarding 的 5 维度评估"
echo -e " • ${C}「给我项目简报」${N} → digest 的跨源聚合"
echo -e " • ${C}「我的待办有哪些」${N} → todo 的紧急度排序"
echo -e "\n详见 ${Y}live-demo-guide.md${N}"
read -p "按回车键继续..."

118
demo/pr-guard-architecture.md Normal file
View File

@ -0,0 +1,118 @@
# 代码质量看门人 · 工作流说明与架构（子任务三）
> 端到端自动化工作流：PR 提交后自动跑完「采集 → AI Review → CI → 评论 → 质量判定/合并」。
> 对应 Skill：`skills/gitlink-pr-guard/SKILL.md`；可复现脚本：`demo/pr-guard-workflow.sh`。
---
## 一、工作流架构图
```
┌─────────────────────────────────────────────┐
│ 触发：PR 提交 / 更新 │
│ （或用户：帮我把关 PR #<id>） │
└──────────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Step 1 采集 PR 变更 │
│ pr +view → pr +files → pr +diff --stat │
│ 产出：PR 详情 / 变更文件 / diff 统计 │
└──────────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Step 2 AI Review（复用 code-review 逻辑） │
│ 逐文件分析 diff → 分级找问题 │
│ 🔴 Critical / 🟡 Warning / 🔵 Suggestion │
└──────────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Step 3 CI 检查 │
│ ci +builds → 匹配分支最新构建 → 状态 │
│ success / failure / pending │
└──────────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Step 4 发布质量看门人报告 │
│ api POST .../pulls/:id/reviews │
│ 报告：判定 + 问题清单 + CI + 处置建议 │
└──────────────────────┬──────────────────────┘
▼
┌─────────────────────────────────────────────┐
│ Step 5 质量判定（门禁规则） │
│ ┌─────────────────────────────────────┐ │
│ │ 0 Critical + CI success → ✅ 合并 │ │
│ │ 有 Critical → 🔴 请求修改 │ │
│ │ CI failure → 🔴 请求修改 │ │
│ └─────────────────────────────────────┘ │
│ 达标+确认 → pr +merge │
└─────────────────────────────────────────────┘
```
---
## 二、串联的 CLI 命令 / Skill（满足"≥3 步"）
| Step | 命令域 | 具体调用 | 类型 |
|:----:|:------:|---------|:----:|
| 1 | pr | `pr +view` / `+files` / `+diff` | 采集 |
| 2 | code-review | Review 分析逻辑（分级找问题） | AI 分析 |
| 3 | ci | `ci +builds` / `+log` | 采集 |
| 4 | api | `POST .../pulls/:id/reviews` | 写（评论） |
| 5 | pr | `pr +merge`（达标确认后） | 写（合并） |
> **共串联 4 个命令域 + 5 个步骤 + 2 处写操作**，远超任务三"≥3 步"要求。
---
## 三、与子任务二的区别（关键）
| 维度 | 子任务二 Skill（如 code-review） | 子任务三 本工作流（pr-guard） |
|------|--------------------------------|-----------------------------|
| **交付单位** | 单个 Skill | 串联多步的**完整解决方案** |
| **职责** | 只做 Review | Review + CI + 评论 + 合并决策 |
| **触发** | 用户要 Review | PR 提交自动跑完整流水线 |
| **决策** | 输出意见 | **质量门禁判定（通过/拒绝/合并）** |
> code-review 是"审查员"，pr-guard 是"看门人"——后者在前者基础上加了 CI 维度和合并决策，形成完整门禁。
---
## 四、可复现性（对应交付要求）
| 要求 | 满足方式 |
|------|---------|
| 串联 ≥3 步 CLI/Skill | 5 步、4 域 ✅ |
| 含自定义 Skill 兼容 Agent | `gitlink-pr-guard` SKILL.md（Claude Code 可读）✅ |
| 可复现执行脚本 | `demo/pr-guard-workflow.sh`（参数化）✅ |
| 真实 GitLink 项目演示 | 登录后对真实 PR 运行（见下） |
| 工作流说明 + 架构图 | 本文档 ✅ |
---
## 五、真实演示步骤（登录后）
```bash
# 1. 登录
gitlink-cli auth login
# 2. 找一个真实 PR
gitlink-cli pr +list --owner <owner> --repo <repo> --state open
# 3. 跑质量看门人流水线（脚本采集，AI 在 Claude Code 做 Step2 分析）
bash demo/pr-guard-workflow.sh <owner> <repo> <pr_id>
# 或在 Claude Code 里自然语言触发：
# "读 skills/gitlink-pr-guard/SKILL.md，帮我把关 <owner>/<repo> 的 PR #42"
```
**预期 AI 行为**：读 pr-guard SKILL.md → 按工作流跑 5 步 → 输出质量看门人报告 + 判定（通过/拒绝）+ 合并建议。
---
## 六、交付清单
- [x] `skills/gitlink-pr-guard/SKILL.md` — 工作流定义 + 门禁规则 + 报告模板
- [x] `demo/pr-guard-workflow.sh` — 可复现脚本（5 步串联）
- [x] `demo/pr-guard-architecture.md` — 本文档（说明 + 架构图）
- [ ] 真实项目演示（登录后运行 + 截图/录屏）
- [ ] 报告（暂缓，后续按统一策略补《新需求构思》《变更影响测试》）

76
demo/pr-guard-workflow.sh Normal file
View File

@ -0,0 +1,76 @@
#!/usr/bin/env bash
# ============================================================
# 代码质量看门人 · 端到端工作流脚本（子任务三）
# 串联 5 步：采集 PR → AI Review → CI 检查 → 汇总评论 → 质量判定
# 用法：bash demo/pr-guard-workflow.sh <owner> <repo> <pr_id>
# 例：bash demo/pr-guard-workflow.sh myorg myproject 42
# 前置：gitlink-cli auth login（涉及平台 API）
# 说明：采集命令真实执行；Review 分析由 AI Agent（读 pr-guard/SKILL.md）完成
# ============================================================
_DIR="$(cd "$(dirname "$0")" && pwd)"
CLI="$_DIR/../gitlink-cli.exe"; [ -f "$CLI" ] || CLI="$_DIR/../gitlink-cli" # Win→.exe，Linux→无后缀
OWNER="${1:-}"; REPO="${2:-}"; PR_ID="${3:-}"
G='\033[0;32m'; Y='\033[1;33m'; C='\033[0;36m'; R='\033[0;31m'; B='\033[1m'; N='\033[0m'
banner() { echo -e "\n${B}══════════════════════════════════════════════════════${N}"; echo -e "${B} $1${N}"; echo -e "${B}══════════════════════════════════════════════════════${N}"; }
step() { echo -e "\n${C}━━━ Step $1 ━━━ ${B}$2${N}"; }
ai() { echo -e "🤖 ${G}AI（读 pr-guard/SKILL.md 后）:${N} $1"; }
run() { echo -e "${Y}❯ $1${N}"; eval "$1" 2>&1 | head -16; echo; }
# ---------- 前置检查 ----------
banner "代码质量看门人 · PR #${PR_ID:-?} 质量流水线"
[ -f "$CLI" ] || { echo -e "${R}✗ 找不到 gitlink-cli${N}"; exit 1; }
if [ -z "$OWNER" ] || [ -z "$REPO" ] || [ -z "$PR_ID" ]; then
echo -e "${R}用法: bash $0 <owner> <repo> <pr_id>${N}"
echo -e "${R}例 : bash $0 myorg myproject 42${N}"; exit 1
fi
echo -e "${G}✓${N} 目标: ${B}$OWNER/$REPO${N} PR #${B}$PR_ID${N}"
# ---------- Step 1：采集 PR 变更 ----------
step 1 "采集 PR 变更（pr +view / +files / +diff）"
ai "先拉 PR 详情、变更文件、diff 统计，作为审查输入。"
run "\"$CLI\" pr +view --id $PR_ID --format json"
run "\"$CLI\" pr +files --id $PR_ID --format json"
run "\"$CLI\" pr +diff --id $PR_ID --stat"
# ---------- Step 2：AI Review（复用 code-review 逻辑）----------
step 2 "AI Review（按 code-review 分级找问题）"
ai "逐文件分析 diff，按安全红线/错误处理/规范分级。这一步由 AI Agent 完成（读 code-review/SKILL.md）。"
echo -e " ${C}分级框架${N}："
echo -e " 🔴 Critical：硬编码密钥 / SQL·命令注入 / 路径遍历（安全红线，阻断合并）"
echo -e " 🟡 Warning ：错误处理缺失 / 边界条件 / 明文敏感信息"
echo -e " 🔵 Suggestion：命名 / 性能 / 可配置化"
echo -e " ${C}Agent 在此输出分级清单（示例见 SKILL.md 输出模板）${N}"
# ---------- Step 3：CI 检查 ----------
step 3 "CI 检查（ci +builds）"
ai "查 PR 对应分支的最新构建状态，作为门禁第二维。"
run "\"$CLI\" ci +builds --owner $OWNER --repo $REPO --format json"
echo -e " ${C}判定：从返回按 source_branch 匹配最新构建 → success / failure / pending${N}"
# ---------- Step 4：发布汇总评论 ----------
step 4 "发布质量看门人报告（api POST .../reviews）"
ai "把 Review 意见 + CI 状态 + 质量判定组装成报告，评论到 PR。"
echo -e "${Y}❯ gitlink-cli api POST /$OWNER/$REPO/pulls/$PR_ID/reviews --body '<报告>'${N}"
echo -e " ${C}报告含${N}：质量判定 + Critical/Warning 清单 + CI 状态 + 处置建议"
echo -e " ${C}[实演时此处真实发送；脚本演示仅展示结构]${N}"
# ---------- Step 5：质量判定 ----------
step 5 "质量判定（门禁规则 → 合并 / 请求修改）"
ai "按门禁规则决策。注意：合并是写操作，默认只建议，确认后才执行。"
echo -e " ${C}门禁规则${N}："
echo -e " 0 Critical + CI success → ✅ 通过，建议合并"
echo -e " 有 Critical 任一 → 🔴 拒绝，请求修改"
echo -e " CI failure → 🔴 拒绝，附 CI 日志"
echo -e " 仅 Warning/Suggestion → 🟡 通过(带建议)"
echo ""
echo -e " ${G}若判定通过 + 用户确认 →${N} ${Y}gitlink-cli pr +merge --id $PR_ID --method squash${N}"
# ---------- 总结 ----------
banner "流水线完成"
echo -e "${B}代码质量看门人${N} 串联了 ${B}5 步${N}，覆盖 ${B}4 个 CLI 域${N}："
echo -e " pr（采集/合并）+ code-review（Review）+ ci（构建）+ api（评论）"
echo -e "\n${C}真实演示${N}：登录后对本仓库一个真实 PR 跑此脚本，由 AI 完成 Step 2 分析。"
echo -e "详见 ${Y}pr-guard-architecture.md${N}（工作流说明 + 架构图）"
read -p "按回车键继续..."

104
demo/research-insight-workflow.sh Normal file
View File

@ -0,0 +1,104 @@
#!/usr/bin/env bash
# ============================================================
# 科研仓库画像 · 端到端工作流脚本（子任务四）
# 4 步：采集数据 → 四维评分 → 协作图谱 → 科研画像报告
# 用法：bash demo/research-insight-workflow.sh <owner> <repo>
# 例：bash demo/research-insight-workflow.sh someresearch awesome-paper-code
# 前置：gitlink-cli auth login（只读分析，不改数据）
# 说明：采集命令真实执行；四维评分 + 协作图谱由 AI（读 research-insight/SKILL.md）完成
# ============================================================
_DIR="$(cd "$(dirname "$0")" && pwd)"
CLI="$_DIR/../gitlink-cli.exe"; [ -f "$CLI" ] || CLI="$_DIR/../gitlink-cli" # Win→.exe，Linux→无后缀
OWNER="${1:-}"; REPO="${2:-}"
G='\033[0;32m'; Y='\033[1;33m'; C='\033[0;36m'; R='\033[0;31m'; B='\033[1m'; N='\033[0m'
banner() { echo -e "\n${B}══════════════════════════════════════════════════════${N}"; echo -e "${B} $1${N}"; echo -e "${B}══════════════════════════════════════════════════════${N}"; }
step() { echo -e "\n${C}━━━ Step $1 ━━━ ${B}$2${N}"; }
ai() { echo -e "🤖 ${G}AI（读 research-insight/SKILL.md 后）:${N} $1"; }
run() { echo -e "${Y}❯ $1${N}"; eval "$1" 2>&1 | head -14; echo; }
# ---------- 前置检查 ----------
banner "🔬 科研仓库画像 · $OWNER/${REPO:-?}"
[ -f "$CLI" ] || { echo -e "${R}✗ 找不到 gitlink-cli${N}"; exit 1; }
if [ -z "$OWNER" ] || [ -z "$REPO" ]; then
echo -e "${R}用法: bash $0 <owner> <repo>${N}"
echo -e "${R}例 : bash $0 someresearch awesome-paper-code${N}"; exit 1
fi
echo -e "${G}✓${N} 分析对象: ${B}$OWNER/$REPO${N}（只读，不改数据）"
# ---------- Step 0：fork 检测（避免给 fork 错评） ----------
step 0 "fork 检测（引用价值要改评 upstream）"
ai "先看 repo +info 的 fork_info。是 fork 则引用价值/活跃度改评 upstream。"
INFO="$("$CLI" repo +info --owner "$OWNER" --repo "$REPO" --format json 2>/dev/null)"
UPSTREAM="$(printf '%s' "$INFO" | grep -o '"fork_project_user_login": *"[^"]*"' | head -1 | sed 's/.*: *"//;s/"$//')"
# fork_project_user_login 缺失或为 null → 非空才算 fork
[ "$UPSTREAM" = "null" ] && UPSTREAM=""
if [ -n "$UPSTREAM" ]; then
echo -e " ${R}⚠️ $OWNER/$REPO 是 ${B}$UPSTREAM/$REPO${N}${R} 的 fork —— 引用价值应改评 upstream ${B}$UPSTREAM/$REPO${N}"
else
echo -e " ${G}✓${N} 独立仓库（非 fork），正常评估"
fi
# ---------- Step 1：采集科研仓库数据 ----------
step 1 "采集科研仓库数据（repo / file / issue / pr + 本地 git 兜底）"
ai "拉基础画像、活跃度、合规复现性数据，作为科研评估输入。"
echo -e "${Y}❯ 基础画像（repo +info / +languages / +contributors）${N}"
"$CLI" repo +info --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -14
"$CLI" repo +languages --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -8
"$CLI" repo +contributors --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -12
echo -e "\n${Y}❯ 复现性文件（file +get 读 LICENSE / CI —— 替代不存在的 repo +raw）${N}"
"$CLI" file +get --owner "$OWNER" --repo "$REPO" --path LICENSE --format json 2>&1 | head -3
"$CLI" repo +tree --owner "$OWNER" --repo "$REPO" --path .gitea/workflows --format json 2>&1 | head -6
echo -e "\n${Y}❯ 版本归档（release +list —— 替代不存在的 repo +tags）${N}"
"$CLI" release +list --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -6
echo -e "\n${Y}❯ 活跃度（issue/pr + git 兜底 —— repo +commits 不存在）${N}"
"$CLI" issue +list --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -8
"$CLI" pr +list --owner "$OWNER" --repo "$REPO" --format json 2>&1 | head -8
echo -e " ${C}repo +commits 不存在 → 用 git clone 兜底读提交时间线${N}"
TMP="/tmp/${OWNER}-${REPO}-analyze"; rm -rf "$TMP"
if git clone --quiet --depth 100 "https://gitlink.org.cn/$OWNER/$REPO.git" "$TMP" 2>/dev/null; then
echo -e " 近 3 月提交: $(git -C "$TMP" log --oneline --since='3 months ago' 2>/dev/null | wc -l) 次"
echo -e " 最近提交 : $(git -C "$TMP" log -1 --format='%ci %an' 2>/dev/null)"
echo -e " tag 列表 : $(git -C "$TMP" tag 2>/dev/null | tr '\n' ' ')"
echo -e " PR 合并数 : $(git -C "$TMP" log --merges --oneline 2>/dev/null | wc -l)"
else
echo -e " ${R}✗ git clone 失败（无 git 或无网络）→ 活跃度改用 repo +info 计数近似${N}"
fi
# ---------- Step 2：四维科研评分 ----------
step 2 "四维科研评分（AI 按指标体系打分）"
ai "对采集数据按科研四维评分。这一步由 AI 完成（指标体系见 SKILL.md）。"
echo -e " ${C}🔁 可复现性${N}（科研核心，满分10）：CI(+2) / 依赖锁定(+2) / 数据说明(+2) / 运行文档(+2) / 版本归档(+2)"
echo -e " ${C}📈 活跃度${N}：近3月提交频率 + Issue/PR 活跃 + 贡献者趋势"
echo -e " ${C}📑 引用价值${N}：LICENSE + 版本归档 + 文档完整 + 星标"
echo -e " ${C}🤝 协作健康${N}：Issue响应 + PR合并率 + 巴士因子（核心贡献者占比）"
echo -e " ${C}Agent 在此输出各维度得分 + 判定依据${N}"
# ---------- Step 3：协作知识图谱 ----------
step 3 "协作知识图谱（贡献者协作网络）"
ai "从贡献者 + PR 协作数据生成 mermaid 协作网络，呼应『知识图谱』要求。"
cat <<'MERMAID'
graph LR
A[核心贡献者1] -->|主提交| P((项目))
B[核心贡献者2] -->|主提交| P
C[偶发贡献者] -->|贡献| P
A -.评审.-> C
B -.评审.-> C
MERMAID
echo -e " ${C}巴士因子${N}：核心贡献者提交占比 → <健康 / 单点风险>"
# ---------- Step 4：科研画像报告 ----------
step 4 "生成科研画像报告"
ai "组装成《科研仓库画像报告》：一句话定性 + 综合评分 + 四维详情 + 协作图 + 引用/复现/合作建议。"
echo -e " ${C}报告含${N}：🔬综合评分 / 📋基础信息 / 🔁可复现性详情 / 🤝协作网络图 / 💡给科研工作者建议"
echo -e " ${C}模板见 SKILL.md「输出模板」+ research-insight-guide.md${N}"
# ---------- 总结 ----------
banner "分析完成"
echo -e "${B}科研仓库画像${N} 串联 ${B}5 步${N}（fork 检测 + 采集 + 评分 + 图谱 + 报告），覆盖 CLI 域（只读）："
echo -e " repo / file / release / issue / pr + 本地 git（提交时间线兜底，repo +commits 不存在）"
echo -e "\n${C}科研视角创新${N}：可复现性评分 + 引用价值 + 协作知识图谱（区别于普通 health 工程视角）"
echo -e "${C}真实验证${N}：登录后对 GitLink 一个科研类仓库跑此脚本，由 AI 完成评分 → 产出报告 + 截图"
echo -e "详见 ${Y}research-insight-guide.md${N}（完整中文使用文档 + 报告样例）"
read -p "按回车键继续..."

94
demo/snippet-live-demo.sh Normal file
View File

@ -0,0 +1,94 @@
#!/usr/bin/env bash
# ============================================================
# GitLink Skills 功能演示 —— snippet 完整闭环
# 核心卖点:AI 读取 SKILL.md → 自动编排 gitlink-cli 命令 → 完成完整场景
# 特点:snippet 是本地功能,无需登录,可安全现场实演
# 用法:bash demo/snippet-live-demo.sh
# ============================================================
# 不用 set -e:保证演示连续性,关键步骤手动检查
_DIR="$(cd "$(dirname "$0")" && pwd)"
CLI="$_DIR/../gitlink-cli.exe"; [ -f "$CLI" ] || CLI="$_DIR/../gitlink-cli" # Win→.exe，Linux→无后缀
# ANSI 颜色
G='\033[0;32m'; Y='\033[1;33m'; C='\033[0;36m'; R='\033[0;31m'; B='\033[1m'; N='\033[0m'
banner() { echo -e "\n${B}══════════════════════════════════════════════════════${N}"; echo -e "${B} $1${N}"; echo -e "${B}══════════════════════════════════════════════════════${N}"; }
scene() { echo -e "\n${C}━━━ 场景 $1 ━━━ ${B}$2${N}"; }
user() { echo -e "🧑 ${B}用户:${N} $1"; }
ai() { echo -e "🤖 ${G}AI（读 snippet/SKILL.md 后）:${N} $1"; }
show() { echo -e "${Y}❯ $1${N}"; }
# ---------- 前置检查 ----------
banner "GitLink Skills 演示 · snippet 闭环"
[ -f "$CLI" ] || { echo -e "${R}✗ 找不到 gitlink-cli: $CLI${N}"; exit 1; }
echo -e "${G}✓${N} gitlink-cli 就绪"
echo -e "${G}✓${N} snippet 为本地功能（${B}无需登录${N}），可安全现场演示"
echo -e "${G}✓${N} 演示数据用完即删，不污染环境"
# ---------- 场景 1：创建 ----------
scene 1 "保存一段常用代码"
user "帮我存一段快速排序代码，语言 python，标签 algorithm"
ai "决策 → \`snippet +create\`（⚠️ Write）。SKILL.md 规则：--title 必填、--tags 逗号分隔、--language 标注。"
show "gitlink-cli snippet +create --title '快速排序(演示)' --language python --tags algorithm,demo --content '...'"
OUT=$("$CLI" snippet +create --title '快速排序(演示)' --language python --tags algorithm,demo \
--content 'def qs(a): return a if len(a)<2 else qs([x for x in a[1:] if x<=a[0]])+[a[0]]+qs([x for x in a[1:] if x>a[0]])' \
--format json 2>&1)
echo "$OUT" | head -12
DEMO_ID=$(echo "$OUT" | grep -oE '"id":[[:space:]]*"[0-9a-f]+"' | head -1 | grep -oE '[0-9a-f]{8}')
echo -e "${G}✓${N} 已创建，id = ${B}$DEMO_ID${N}"
# ---------- 场景 2：列表 ----------
scene 2 "浏览片段库"
user "我存了哪些片段？"
ai "决策 → \`snippet +list\`（Read）。可按 --tag / --language / --keyword 过滤。"
show "gitlink-cli snippet +list --format json"
"$CLI" snippet +list --format json 2>&1 | head -14
# ---------- 场景 3：搜索 ----------
scene 3 "全文检索"
user "帮我找包含 '排序' 的片段"
ai "决策 → \`snippet +search\`（Read，全文匹配 title + content）。"
show "gitlink-cli snippet +search --query '排序' --format json"
"$CLI" snippet +search --query '排序' --format json 2>&1 | head -10
# ---------- 场景 4：查看详情 ----------
scene 4 "查看指定片段"
user "看看 id=$DEMO_ID 这个的详情"
ai "决策 → \`snippet +view --id\`（Read）。"
show "gitlink-cli snippet +view --id $DEMO_ID --format json"
"$CLI" snippet +view --id "$DEMO_ID" --format json 2>&1 | head -12
# ---------- 场景 5：导出 ----------
scene 5 "导出到文件复用"
user "把它导出成文件，我要贴到项目里"
ai "决策 → \`snippet +export --output\`（Read）。SKILL.md：默认输出到 stdout，-o 写文件。"
TMP="$PWD/.demo_export_$$.py"
show "gitlink-cli snippet +export --id $DEMO_ID --output $TMP"
"$CLI" snippet +export --id "$DEMO_ID" --output "$TMP" >/dev/null 2>&1
echo -e "${G}✓${N} 已导出，文件内容："; cat "$TMP"; rm -f "$TMP"
# ---------- 场景 6：更新 ----------
scene 6 "更新片段字段"
user "给这个片段补个 tag 'sort'"
ai "决策 → \`snippet +update\`（⚠️ Write）。--id 必填，至少一个字段。"
show "gitlink-cli snippet +update --id $DEMO_ID --tags algorithm,demo,sort"
"$CLI" snippet +update --id "$DEMO_ID" --tags algorithm,demo,sort --format json 2>&1 | head -8
# ---------- 场景 7：删除（清理）----------
scene 7 "删除演示片段（清理）"
user "演示结束，删掉刚才的测试片段"
ai "决策 → \`snippet +delete\`（🔴 Destructive）。SKILL.md：删除不可逆，建议先 view 确认。"
show "gitlink-cli snippet +delete --id $DEMO_ID"
"$CLI" snippet +delete --id "$DEMO_ID" --format json 2>&1 | head -4
echo -e "${G}✓${N} 演示数据已清理"
# ---------- 总结 ----------
banner "演示完成"
echo -e "${B}gitlink-snippet${N} Skill 的 7 个命令全部实测通过："
echo -e " create / list / search / view / export / update / delete"
echo ""
echo -e "${B}核心价值${N}：AI 读取 SKILL.md 后，能自动编排 gitlink-cli 命令完成完整场景，"
echo -e "输出严格符合 SKILL.md 定义的 envelope 格式 {\"ok\":true,\"data\":{...}}。"
echo -e "\n${C}其他 Skill（onboarding / digest / todo）涉及平台 API，登录后可按其 SKILL.md 的「工作流」演示。${N}"
read -p "按回车键继续..."

56
demo/web/README.md Normal file
View File

@ -0,0 +1,56 @@
# GitLink CLI 智能化能力展示（演示网页）
一个**可交互的演示站**：点动词/敲命令 → 真跑 gitlink-cli → 显示真实输出，配合 25 域命令浏览器、48 Skill 卡片墙、pr-guard 流程、科研四维雷达，全面展示子任务一~四的成果。
> 位置：仓库内 `demo/web/`（`server.py` + `index.html`）。后端零依赖（仅 Python 标准库）。
## 架构（访客自带 token，零凭据上云）
```
浏览器 index.html ──fetch──▶ server.py（Python 标准库）
顶栏 token + owner/repo │ GET /api/skill 读 SKILL.md
命令域 / 终端 / Skill 墙 │ POST /api/run 真跑 CLI（token 透传给子进程）
pr-guard / 科研雷达 │ POST /api/analyze 四维评分 + 巴士因子
▼
gitlink-cli（仓库根 ../../gitlink-cli[.exe]）
```
- 访客 token 仅存在**访客自己的浏览器**（localStorage），按请求传后端 → 注入子进程 `GITLINK_TOKEN` → 用完即弃，**不落服务端、不写日志**。
- 本地命令（`snippet`/`auth`）免 token 即可真跑；平台命令（`repo`/`issue`/`pr`…）需访客填自己的 token。
## 本地启动（3 步）
```bash
# 1. 在仓库根编译 CLI（已有可跳过）
cd gitlink-cli # 仓库根（含 go.mod）
go build -o gitlink-cli . # Windows 会生成 gitlink-cli.exe
# 2. 启动后端（零依赖）
cd demo/web
python server.py # → http://0.0.0.0:8000
# 3. 浏览器打开 http://localhost:8000
# 顶栏粘自己的 GitLink token（auth login --token 拿）→ 平台命令即可真跑
```
> 服务端会自动探测二进制：`GITLINK_BIN` 环境变量 > 仓库根 `gitlink-cli`/`gitlink-cli.exe` > PATH。
> 端口/主机可设：`PORT=9000 HOST=127.0.0.1 python server.py`。
## 展示区
| 区块 | 内容 |
|------|------|
| ① 命令全域浏览器 | 25 域 160+ 动词，按子任务分组 + 搜索；点动词填终端真跑 |
| ② Skill 全集 | 48 个 Skill 卡片（按 全部/新增/科研/质量 筛选），点开读 SKILL.md 全文 |
| ③ pr-guard | 5 步门禁动画 + 「用真实 PR 跑」（填 token） |
| ④ 科研画像 | 「实拉分析」目标仓库 → 四维雷达 + 协作网络 + 巴士因子 |
| ⑤ 验证 | 命令层 / 编排层 / 输出层 三层证据 |
## 安全
- 后端白名单（仅 30 个 gitlink-cli 顶层域）+ subprocess 列表参数（不经 shell）+ 30s 超时。
- 访客 token 不落服务端。公网部署也**不烘焙任何团队 token**。
## 云端部署
见上级 [`demo/README.md`](../README.md)（Dockerfile + `.devops` 流水线 + 服务器部署说明）。

424
demo/web/index.html Normal file
View File

@ -0,0 +1,424 @@
<!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>
<script src="https://cdn.tailwindcss.com"></script>
<script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
<style>
:root { --bg:#0d1117; --panel:#161b22; --border:#30363d; --txt:#c9d1d9; --acc:#58a6ff; --green:#3fb950; --red:#f85149; --yellow:#d29922; }
body { background:var(--bg); color:var(--txt); font-family: -apple-system, "Segoe UI", "Microsoft YaHei", sans-serif; }
.panel { background:var(--panel); border:1px solid var(--border); }
.mono { font-family: "Cascadia Code", Consolas, "Courier New", monospace; }
#term-out { background:#010409; min-height:300px; max-height:440px; overflow-y:auto; padding:14px; }
.l-cmd { color:var(--acc); } .l-out { color:var(--txt); white-space:pre-wrap; word-break:break-all; }
.l-err { color:var(--red); } .l-muted { color:#6e7681; font-style:italic; }
#term-input { background:#010409; border-top:1px solid var(--border); }
.skill-card { transition:.2s; }
.skill-card:hover { border-color:var(--acc); transform:translateY(-2px); }
.step { transition:.3s; }
.step.active { border-color:var(--green); background:#1c2820; }
.verb { font-size:11px; padding:2px 7px; border-radius:4px; border:1px solid var(--border); background:#0d1117; cursor:pointer; transition:.15s; }
.verb:hover { border-color:var(--acc); color:var(--acc); }
.chip { background:#21262d; border:1px solid var(--border); }
.fbtn { font-size:12px; padding:4px 12px; border-radius:9999px; border:1px solid var(--border); cursor:pointer; transition:.15s; }
.fbtn.active { background:var(--acc); color:#000; border-color:var(--acc); }
details > summary { list-style:none; }
details > summary::-webkit-details-marker { display:none; }
details[open] > summary .arr { transform:rotate(90deg); }
.arr { display:inline-block; transition:.15s; }
#skill-modal-body h1,#skill-modal-body h2,#skill-modal-body h3,#skill-modal-body h4 { color:#fff; margin:.7em 0 .35em; font-weight:600; }
#skill-modal-body h1 { font-size:1.3em; border-bottom:1px solid var(--border); padding-bottom:.2em; }
#skill-modal-body h2 { font-size:1.15em; } #skill-modal-body h3 { font-size:1.02em; }
#skill-modal-body p { margin:.4em 0; line-height:1.6; }
#skill-modal-body table { border-collapse:collapse; margin:.5em 0; display:block; overflow-x:auto; }
#skill-modal-body th,#skill-modal-body td { border:1px solid var(--border); padding:4px 8px; text-align:left; font-size:.85em; }
#skill-modal-body th { background:#21262d; }
#skill-modal-body code { background:#010409; padding:1px 5px; border-radius:3px; color:var(--green); font-size:.85em; }
#skill-modal-body pre { background:#010409; padding:10px; border-radius:6px; overflow-x:auto; margin:.5em 0; border:1px solid var(--border); }
#skill-modal-body pre code { background:none; padding:0; color:var(--txt); }
#skill-modal-body strong { color:#fff; }
#skill-modal-body blockquote { border-left:3px solid var(--acc); padding-left:10px; color:#8b949e; margin:.5em 0; }
#skill-modal-body ul,#skill-modal-body ol { padding-left:1.4em; margin:.4em 0; }
#skill-modal-body hr { border-color:var(--border); margin:.8em 0; }
#skill-modal-body a { color:var(--acc); }
</style>
</head>
<body class="min-h-screen">
<!-- Header -->
<header class="border-b border-[var(--border)] panel">
<div class="max-w-7xl mx-auto px-6 py-5 flex items-center justify-between flex-wrap gap-4">
<div>
<h1 class="text-2xl font-bold text-white">🚀 GitLink CLI · 智能化能力展示</h1>
<p class="text-sm text-[#8b949e] mt-1">从「开发者工具」升级为「AI 可驱动平台」—— 命令 · Skills · 工作流 · 科研辅助</p>
</div>
<div class="flex gap-2 flex-wrap text-xs">
<span class="chip px-3 py-1.5 rounded-full">🛠 25 域 / 160+ 命令</span>
<span class="chip px-3 py-1.5 rounded-full">🧠 53 Skills</span>
<span class="chip px-3 py-1.5 rounded-full">🚪 pr-guard 工作流</span>
<span class="chip px-3 py-1.5 rounded-full">🔬 科研四维画像</span>
</div>
</div>
<div class="max-w-7xl mx-auto px-6 pb-4 flex items-center gap-3 flex-wrap text-sm">
<span class="text-[#8b949e] whitespace-nowrap">🔑 GitLink Token</span>
<input id="token-input" type="password" placeholder="粘贴你的 GitLink 个人访问令牌（仅存本机浏览器；公开仓库命令可免）" class="flex-1 min-w-[220px] bg-[#0d1117] border border-[var(--border)] rounded px-3 py-1.5 text-xs mono">
<span class="text-[#8b949e] whitespace-nowrap">📦 默认目标</span>
<input id="owner-input" value="Gitlink" class="w-28 bg-[#0d1117] border border-[var(--border)] rounded px-2 py-1.5 text-xs mono" placeholder="owner">
<span class="text-[#6e7681]">/</span>
<input id="repo-input" value="gitlink-cli" class="w-36 bg-[#0d1117] border border-[var(--border)] rounded px-2 py-1.5 text-xs mono" placeholder="repo">
<span id="token-state" class="text-xs"></span>
</div>
</header>
<main class="max-w-7xl mx-auto px-6 py-8 space-y-10">
<!-- ① 命令浏览器 + 参数构建 + 终端 -->
<section>
<h2 class="text-xl font-bold text-white mb-1">▶ 命令浏览器 <span class="text-sm text-[#8b949e] font-normal">（先选大方向 → 展开域 → 点动词填参数 → 真跑）</span></h2>
<p class="text-sm text-[#8b949e] mb-4">左侧点分类展开命令域；点动词在右侧「参数构建」里填参（搜索类命令的 keyword 等由你决定），回车或点▶运行。本地命令免 token。</p>
<div class="grid grid-cols-1 lg:grid-cols-3 gap-4">
<!-- 左：折叠分层浏览器 -->
<div class="panel rounded-lg p-4">
<div class="flex items-center gap-2 mb-3">
<h3 class="font-semibold text-white">命令域</h3>
<input id="cmd-search" placeholder="🔍 搜索" class="flex-1 bg-[#0d1117] border border-[var(--border)] rounded px-2 py-1 text-xs mono">
</div>
<div id="cmd-groups" class="text-sm max-h-[460px] overflow-y-auto pr-1"></div>
</div>
<!-- 右：参数构建 + 终端 -->
<div class="panel rounded-lg lg:col-span-2 flex flex-col">
<!-- 参数构建条 -->
<div class="px-4 py-3 border-b border-[var(--border)] bg-[#0d1017]">
<div class="flex items-center gap-2 mb-2">
<span class="text-xs text-[var(--yellow)] font-semibold">🧩 参数构建</span>
<span id="builder-hint" class="text-xs text-[#6e7681]">点左侧动词开始</span>
</div>
<div id="builder-params" class="grid grid-cols-2 gap-2 mb-2"></div>
<div class="flex items-center gap-2">
<span class="text-[var(--green)] mono text-sm">$</span>
<input id="builder-cmd" class="flex-1 bg-[#010409] border border-[var(--border)] rounded px-2 py-1.5 text-xs mono text-[var(--green)]" placeholder="组装好的命令会显示在这里（可手改）" autocomplete="off">
<button onclick="runBuilder()" class="bg-[var(--green)] text-black px-3 py-1.5 rounded text-xs font-semibold whitespace-nowrap">▶ 运行</button>
</div>
</div>
<!-- 终端 -->
<div class="flex items-center gap-2 px-4 py-2 border-b border-[var(--border)] text-xs text-[#8b949e]">
<span class="w-3 h-3 rounded-full bg-[var(--red)]"></span><span class="w-3 h-3 rounded-full bg-[var(--yellow)]"></span><span class="w-3 h-3 rounded-full bg-[var(--green)]"></span>
<span class="ml-2">终端</span><span id="term-target" class="ml-auto text-[var(--acc)]"></span>
</div>
<div id="term-out" class="mono text-sm flex-1"></div>
<div class="flex items-center px-4 py-2 mono text-sm" id="term-input">
<span class="text-[var(--green)] mr-2">$</span>
<input id="cmd-input" class="flex-1 bg-transparent text-[var(--green)] mono" placeholder="或在此自由输入 gitlink-cli 命令回车" autocomplete="off">
</div>
</div>
</div>
</section>
<!-- ② Skill 卡片墙 -->
<section>
<div class="flex items-center justify-between flex-wrap gap-3 mb-4">
<h2 class="text-xl font-bold text-white">🧠 Skill 全集 <span class="text-sm text-[#8b949e] font-normal">（53 个 · 点卡片读 SKILL.md 全文）</span></h2>
<div class="flex gap-2 flex-wrap">
<button class="fbtn active" onclick="filterSkill('all',this)">全部 53</button>
<button class="fbtn" onclick="filterSkill('new',this)">✨ 本次新增 7</button>
<button class="fbtn" onclick="filterSkill('research',this)">🔬 科研</button>
<button class="fbtn" onclick="filterSkill('quality',this)">🚪 代码质量</button>
</div>
</div>
<div class="grid grid-cols-2 md:grid-cols-3 lg:grid-cols-5 gap-3" id="skill-wall"></div>
</section>
<!-- ③ 任务三 pr-guard -->
<section class="panel rounded-lg p-6">
<div class="flex items-center gap-2 mb-1"><h2 class="text-xl font-bold text-white">🚪 任务三：代码质量看门人</h2><span class="chip px-2 py-0.5 rounded text-xs">pr-guard</span></div>
<div class="text-sm text-[#8b949e] mb-3 space-y-1">
<p><b class="text-[var(--txt)]">是什么</b>：PR 提交后自动跑完 5 步质量门禁 —— 串接 <code class="text-[var(--green)]">pr → code-review → ci → api → pr</code> 四个命令域。</p>
<p><b class="text-[var(--txt)]">门禁规则</b>：<span class="text-[var(--green)]">0 Critical + CI success → ✅ 合并</span>；否则 <span class="text-[var(--red)]">🔴 拒绝</span>。</p>
<p><b class="text-[var(--txt)]">与 code-review 区别</b>：code-review 只做 Review；pr-guard 是<b>完整闭环</b>（采集→审查→CI→评论→判定/合并）。</p>
<p><b class="text-[var(--txt)]">任务三全家桶</b>（不止 pr-guard）：code-review×pr-summary 闭环、community-ops-sweep 七段式周报（wauxing）+ 自动化 Skill 族 <code class="text-[var(--green)]">gatekeeper / commit-quality / issue-triage / issueops / release-auto / wiki-builder / pipeline-guardian / webhook-sentinel</code>（点下方 Skill 墙查看）。</p>
</div>
<div class="flex items-center justify-between gap-2 mb-5 flex-wrap" id="pr-steps"></div>
<div class="flex gap-2 flex-wrap">
<button onclick="runPipeline()" class="bg-[var(--acc)] text-black px-4 py-2 rounded font-semibold text-sm hover:opacity-90">▶ 模拟流水线</button>
<button onclick="livePR()" class="border border-[var(--border)] text-[var(--txt)] px-4 py-2 rounded text-sm hover:bg-[#21262d]">🔌 用真实 PR 跑（需 token）</button>
</div>
<div id="pr-verdict" class="mt-4 text-sm mono"></div>
</section>
<!-- ④ 任务四 科研画像 -->
<section class="panel rounded-lg p-6">
<div class="flex items-center gap-2 mb-1"><h2 class="text-xl font-bold text-white">🔬 任务四：科研仓库画像</h2><span class="chip px-2 py-0.5 rounded text-xs">research-insight</span></div>
<div class="text-sm text-[#8b949e] mb-3 space-y-1">
<p><b class="text-[var(--txt)]">是什么</b>：四维科研评分（🔁可复现性 / 📈活跃度 / 📑引用价值 / 🤝协作健康）+ 贡献者协作网络 + 巴士因子。</p>
<p><b class="text-[var(--txt)]">区别于 health</b>：health 看「工程维护好不好」，本工具看「<b class="text-[var(--txt)]">科研上值不值得引用/复现</b>」；含 <b class="text-[var(--txt)]">fork 检测</b>（fork 自动改评 upstream）。</p>
<p><b class="text-[var(--txt)]">任务四全家桶</b>（whale 主导，<b class="text-[var(--txt)]">S1–S6 全生命周期</b>）：<code class="text-[var(--green)]">research-insight(S1) / research-graph(S2) / compliance(S3) / collab-match(S4) / research-progress(S5) / research-visual(S6)</code> + research-fork-impact/scholar-profile；Python 算法层 ~5800 行 + Go Web demo。</p>
<p><b class="text-[var(--txt)]">真实验证</b>：<code class="text-[var(--green)]">whale_hihihi/gitlink-cli</code> → 识别为 fork、巴士因子 38%、可复现性 8/10。</p>
</div>
<div class="flex items-center gap-2 mb-5 flex-wrap">
<span class="text-sm text-[#8b949e]">分析对象 = 顶栏 owner/repo</span>
<button onclick="analyze()" class="bg-[var(--green)] text-black px-4 py-2 rounded font-semibold text-sm hover:opacity-90">🔍 实拉分析</button>
<span id="analyze-status" class="text-xs text-[#8b949e]">（公开仓库可免 token）</span>
</div>
<div class="grid grid-cols-1 md:grid-cols-2 gap-6">
<div><canvas id="radar"></canvas><div id="repro-detail" class="text-xs text-[#8b949e] mt-3 mono"></div></div>
<div>
<h4 class="text-white font-semibold mb-2">协作网络图 <span id="bus-info" class="text-xs text-[#8b949e] font-normal">（点「实拉分析」用真实贡献者重绘）</span></h4>
<svg id="collab-svg" viewBox="0 0 360 260" class="w-full panel rounded border border-[var(--border)]"></svg>
<div id="repo-meta" class="text-xs text-[#8b949e] mt-2"></div>
</div>
</div>
</section>
<!-- ⑤ 验证 -->
<section>
<h2 class="text-xl font-bold text-white mb-4">✅ 验证：三层证据（对照模板法）</h2>
<div class="grid grid-cols-1 md:grid-cols-3 gap-3">
<div class="panel rounded-lg p-4"><div class="text-[var(--green)] text-2xl mb-1">①</div><h4 class="text-white font-semibold">命令层</h4><p class="text-sm text-[#8b949e] mt-1">命令真实执行，返回真实数据（非 unknown/401）</p></div>
<div class="panel rounded-lg p-4"><div class="text-[var(--yellow)] text-2xl mb-1">②</div><h4 class="text-white font-semibold">编排层</h4><p class="text-sm text-[#8b949e] mt-1">AI 按 SKILL.md 的顺序调命令</p></div>
<div class="panel rounded-lg p-4"><div class="text-[var(--acc)] text-2xl mb-1">③</div><h4 class="text-white font-semibold">输出层</h4><p class="text-sm text-[#8b949e] mt-1">输出符合 SKILL.md 模板（判定/评分/清单）</p></div>
</div>
</section>
<footer class="text-center text-xs text-[#6e7681] py-6 border-t border-[var(--border)]">
GitLink CLI 智能化能力展示 · 子任务一~四 + DevOps · 后端 demo/web/server.py（访客自带 token，零凭据上云）
</footer>
</main>
<script>
// ===== token & owner/repo =====
const tokenInput=document.getElementById('token-input'), ownerInput=document.getElementById('owner-input'), repoInput=document.getElementById('repo-input');
tokenInput.value=localStorage.getItem('gl_token')||'';
const tokenState=document.getElementById('token-state');
function syncTokenState(){ tokenState.textContent=tokenInput.value?'✅ 已提供':'⚠️ 未提供（公开仓库命令仍可跑）'; tokenState.style.color=tokenInput.value?'var(--green)':'var(--yellow)'; }
tokenInput.addEventListener('input',()=>{localStorage.setItem('gl_token',tokenInput.value);syncTokenState();}); syncTokenState();
const getToken=()=>tokenInput.value.trim(), getOwner=()=>ownerInput.value.trim()||'Gitlink', getRepo=()=>repoInput.value.trim()||'gitlink-cli';
function syncTarget(){ document.getElementById('term-target').textContent=getOwner()+'/'+getRepo(); } syncTarget();
[ownerInput,repoInput].forEach(el=>el.addEventListener('input',()=>{syncTarget();updateCmd();}));
// ===== 命令域（25 域，按子任务分组）=====
const DOMAIN_GROUPS=[
{g:'资源管理（仓库/文件/版本）',open:true,domains:[
{d:'repo',v:['info','languages','contributors','readme','tree','code-stats','list','create','delete','fork','stargazers','watchers']},
{d:'file',v:['get','browse','create','update','delete']},
{d:'branch',v:['list','create','delete','protect','unprotect']},
{d:'release',v:['list','view','create','update','delete','download']},
{d:'search',v:['issues','repos','users']},
{d:'compare',v:['view','files']}]},
{g:'Issue 跟踪',domains:[
{d:'issue',v:['list','view','create','update','close','comment','batch-create','batch-update','batch-close','batch-assign','batch-label']},
{d:'label',v:['list','create','update','delete']},
{d:'milestone',v:['list','view','create','close','delete']}]},
{g:'PR 与代码审查',domains:[
{d:'pr',v:['list','view','diff','files','merge','reopen','comment','review','reviews','check-merge']}]},
{g:'CI/CD · 流水线 · 工作流',domains:[
{d:'ci',v:['builds','logs','restart','stop','enable','disable']},
{d:'pipeline',v:['list','runs','run','view','logs','results','save-yaml']},
{d:'workflow',v:['triage','health','pr-summary','repo-report']}]},
{g:'项目管理 · 协作',domains:[
{d:'pm',v:['boards','sprints','weekly','tags','pipelines','actions']},
{d:'org',v:['list','info','members','create']},
{d:'member',v:['list','add','remove']},
{d:'webhook',v:['list','view','create','update','delete','history','test']},
{d:'wiki',v:['list','view','create','update','delete']}]},
{g:'用户与画像',domains:[
{d:'user',v:['me','info','headmaps','stats-activity','stats-develop','trends']},
{d:'profile',v:['activity','ability','contribution','role']}]},
{g:'数据 · 合规 · 健康',domains:[
{d:'dataset',v:['list','view','create','update']},
{d:'license',v:['list']},
{d:'health',v:['fetch']}]},
{g:'本地工具（免登录）',open:true,domains:[
{d:'snippet',v:['create','list','view','search','update','delete','export']},
{d:'auth',v:['login','status','logout'],raw:true}]},
];
const LOCAL_DOMAINS=new Set(['snippet','auth','config','version','doctor']);
// 需要额外参数表单的动词（flag 已核对 CLI --help）
const FORM={
'search +issues':[{f:'-k',k:'keyword',req:true,ph:'如 good first issue'},{f:'-c',k:'category',sel:['opened','closed','all'],def:'opened'}],
'search +repos':[{f:'-k',k:'keyword',req:true,ph:'如 gitlink'}],
'search +users':[{f:'-k',k:'keyword',req:true,ph:'如用户名'}],
'issue +list':[{f:'-s',k:'state',sel:['open','closed','all'],def:'open'},{f:'-k',k:'keyword',ph:'可选关键词'}],
'issue +view':[{f:'-n',k:'number',req:true,ph:'Issue 编号（URL 里）'}],
'pr +view':[{f:'-i',k:'id',req:true,ph:'PR 编号'}],
'file +get':[{f:'--path',k:'path',req:true,ph:'如 LICENSE / README.md'}],
'repo +tree':[{f:'--path',k:'path',ph:'目录路径，默认根'}],
'snippet +create':[{f:'--title',k:'title',req:true},{f:'--language',k:'language',ph:'python/go'},{f:'--tags',k:'tags',ph:'逗号分隔'},{f:'--content',k:'content',req:true,area:true}],
'snippet +view':[{f:'--id',k:'id',req:true,ph:'先 +list 取 id'}],
'snippet +search':[{f:'--query',k:'query',req:true,ph:'搜索词'}],
'snippet +delete':[{f:'--id',k:'id',req:true,ph:'先 +list 取 id'}],
};
// ===== 渲染折叠浏览器 =====
function renderDomains(q=''){
const Q=q.trim().toLowerCase(); let html='';
DOMAIN_GROUPS.forEach(grp=>{
const doms=grp.domains.filter(dm=>!Q||dm.d.includes(Q)||dm.v.some(x=>x.includes(Q)));
if(!doms.length) return;
html+=`<details class="mb-1" ${grp.open&&!Q?'open':''}><summary class="cursor-pointer text-xs text-[var(--yellow)] py-1 select-none hover:text-[var(--acc)]"><span class="arr">▸</span> ${grp.g} <span class="text-[#6e7681]">(${doms.length})</span></summary><div class="pl-2 mt-1 space-y-1.5">`;
doms.forEach(dm=>{
const local=LOCAL_DOMAINS.has(dm.d);
const tag=local?'<span class="text-[10px] text-[var(--green)]">本地</span>':'<span class="text-[10px] text-[#6e7681]">平台</span>';
const verbs=dm.v.filter(x=>!Q||x.includes(Q)||dm.d.includes(Q)).map(v=>{
const formTag=FORM[dm.d+' +'+v]?'<span class="text-[var(--acc)]">⚙</span>':'';
return `<span class="verb" onclick="clickVerb('${dm.d}','+${v}')">${formTag}+${v}</span>`;
}).join(' ');
html+=`<div class="panel rounded p-2"><div class="mono text-xs text-[var(--acc)] mb-1">${dm.d} ${tag}</div><div class="flex flex-wrap gap-1">${verbs}</div></div>`;
});
html+=`</div></details>`;
});
document.getElementById('cmd-groups').innerHTML=html||'<p class="text-xs text-[#6e7681]">无匹配</p>';
}
renderDomains();
document.getElementById('cmd-search').addEventListener('input',e=>renderDomains(e.target.value));
// ===== 参数构建 =====
let currentVerb=null;
function clickVerb(domain,verb){
currentVerb={domain,verb,key:domain+' '+verb,local:LOCAL_DOMAINS.has(domain),form:FORM[domain+' '+verb]};
renderBuilder();
}
function buildCmd(){
const v=currentVerb; if(!v) return '';
let parts=['gitlink-cli',v.domain,v.verb];
if(v.form) v.form.forEach(p=>{
const el=document.getElementById('pf-'+p.k); let val=el?el.value.trim():'';
if(p.sel&&!val) val=p.def||'';
if(val) parts.push(p.f,val);
});
if(!v.local) parts.push('--owner',getOwner(),'--repo',getRepo());
return parts.join(' ');
}
function updateCmd(){ const c=buildCmd(); if(c) document.getElementById('builder-cmd').value=c; }
function renderBuilder(){
const v=currentVerb; const pe=document.getElementById('builder-params'); const hi=document.getElementById('builder-hint');
if(!v){ pe.innerHTML=''; hi.textContent='点左侧动词开始'; document.getElementById('builder-cmd').value=''; return; }
hi.innerHTML=`<code class="text-[var(--acc)]">${v.domain} ${v.verb}</code> · ${v.local?'本地命令':(v.form?'填参数后运行（自动带 owner/repo）':'平台命令，自动带 owner/repo')}`;
if(v.form){
pe.innerHTML=v.form.map(p=>{
const req=p.req?'<span class="text-[var(--red)]">*</span>':'';
const label=`<label class="text-xs text-[#8b949e]">${p.k}${req}${p.req?'<span class="text-[10px]"> 必填</span>':''}</label>`;
if(p.sel) return `<div>${label}<select id="pf-${p.k}" class="w-full mt-0.5 bg-[#0d1117] border border-[var(--border)] rounded px-1 py-1 text-xs mono">${p.sel.map(s=>`<option ${s===p.def?'selected':''}>${s}</option>`).join('')}</select></div>`;
if(p.area) return `<div class="col-span-2">${label}<textarea id="pf-${p.k}" rows="2" placeholder="${p.ph||''}" class="w-full mt-0.5 bg-[#0d1117] border border-[var(--border)] rounded px-2 py-1 text-xs mono"></textarea></div>`;
return `<div>${label}<input id="pf-${p.k}" placeholder="${p.ph||''}" class="w-full mt-0.5 bg-[#0d1117] border border-[var(--border)] rounded px-2 py-1 text-xs mono"></div>`;
}).join('');
setTimeout(()=>v.form.forEach(p=>{const el=document.getElementById('pf-'+p.k);if(el){el.oninput=updateCmd;el.onchange=updateCmd;}}),0);
} else { pe.innerHTML=''; }
updateCmd();
}
function runBuilder(){ const c=document.getElementById('builder-cmd').value.trim(); if(c) runRaw(c); }
// ===== 终端 =====
const out=document.getElementById('term-out');
const input=document.getElementById('cmd-input');
let history=[],hidx=0;
function appendOut(text,cls='l-out'){const div=document.createElement('div');div.className='mono text-sm '+cls;div.textContent=text;out.appendChild(div);out.scrollTop=out.scrollHeight;}
async function runRaw(cmd){
if(!cmd||cmd.startsWith('#'))return;
history.push(cmd);hidx=history.length;
appendOut('$ '+cmd,'l-cmd');
const m=document.createElement('div');m.className='mono text-sm l-muted';m.textContent='⏳ 运行中...';out.appendChild(m);out.scrollTop=out.scrollHeight;
try{
const r=await fetch('/api/run',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({cmd,token:getToken()})});
const d=await r.json();m.remove();
if(d.stdout) appendOut(d.stdout,'l-out');
if(d.stderr) appendOut('[stderr] '+d.stderr,d.ok?'l-muted':'l-err');
if(!d.ok){
if(!d.stdout&&!d.stderr&&d.error) appendOut('❌ '+d.error,'l-err');
if(d.code!=null) appendOut('[退出码 '+d.code+']','l-err');
if(/缺少必需参数|required|missing/i.test(d.stderr||d.error||'')) appendOut('💡 该命令有必填参数，看上方「参数构建」填写','l-muted');
if(d.needs_token&&!d.token_provided&&/401|登录|未授权|token/i.test(d.stderr||d.error||'')) appendOut('💡 此命令可能需要 token（顶栏填写）','l-muted');
if(/timeout|handshake|refused|no such host|dial tcp/i.test(d.stderr||d.error||'')) appendOut('💡 网络连不上 GitLink（TLS/超时），稍后重试一次','l-muted');
if(/接口数据异常|\[-1\]|数据异常/i.test(d.stderr||d.error||'')) appendOut('💡 GitLink 接口对该仓库返回异常（该仓库可能无此类数据 / CI 未启用）','l-muted');
} else if(!d.stdout&&!d.stderr){ appendOut('(无输出)','l-muted'); }
}catch(e){m.remove();appendOut('❌ 请求失败：'+e+'（后端 server.py 是否启动？）','l-err');}
}
input.addEventListener('keydown',e=>{
if(e.key==='Enter'){const c=input.value.trim();input.value='';runRaw(c);}
else if(e.key==='ArrowUp'){if(hidx>0){hidx--;input.value=history[hidx]||'';e.preventDefault();}}
else if(e.key==='ArrowDown'){if(hidx<history.length){hidx++;input.value=history[hidx]||'';e.preventDefault();}}
});
// ===== Skill 全集 =====
const SKILLS=['auth','branch','ci','ci-health','code-review','collab-match','commit-quality','compare','competition-manager','compliance','contributor-insight','digest','file','gatekeeper','health','insight','issue','issue-tag','issue-triage','issueops','label','license-compliance','member','milestone','notification-digest','onboarding','org','pipeline','pipeline-guardian','pm','pr','pr-guard','release','release-auto','repo','research-fork-impact','research-graph','research-insight','research-progress','research-tracker','research-visual','scholar-profile','search','shared','snippet','stale-issue-manager','todo','user','webhook','webhook-sentinel','wiki','wiki-builder','workflow'];
const NEW_SKILLS=new Set(['onboarding','auth','snippet','digest','todo','pr-guard','research-insight']);
const SKILL_ICON={onboarding:'🚀',auth:'🔑',snippet:'📦',digest:'📰',todo:'📋','pr-guard':'🚪','research-insight':'🔬','code-review':'👁','commit-quality':'✨','health':'❤','release-auto':'🏷','workflow':'🔁','compliance':'✅','license-compliance':'📜','wiki-builder':'📚','pipeline-guardian':'🛡','webhook-sentinel':'📡'};
function skillCat(n){if(NEW_SKILLS.has(n))return'new';if(/research|scholar|contributor-insight|insight|fork-impact|tracker/.test(n))return'research';if(/code-review|commit-quality|gatekeeper|pr-guard|compliance|license-compliance/.test(n))return'quality';return'other';}
function skillEmoji(n){return SKILL_ICON[n]||(/research|scholar/.test(n)?'🔬':/wiki/.test(n)?'📚':/pipeline|ci|webhook/.test(n)?'🛠':'📁');}
let SKILL_FILTER='all';
function filterSkill(f,btn){SKILL_FILTER=f;document.querySelectorAll('.fbtn').forEach(b=>b.classList.remove('active'));btn.classList.add('active');renderSkills();}
function renderSkills(){
const list=SKILLS.filter(n=>SKILL_FILTER==='all'?true:(SKILL_FILTER==='new'?NEW_SKILLS.has(n):skillCat(n)===SKILL_FILTER));
document.getElementById('skill-wall').innerHTML=list.map(n=>{
const tag=NEW_SKILLS.has(n)?'<span class="text-[10px] text-[var(--green)]">✨新增</span>':(skillCat(n)==='research'?'<span class="text-[10px] text-[var(--acc)]">科研</span>':skillCat(n)==='quality'?'<span class="text-[10px] text-[var(--yellow)]">质量</span>':'');
return `<div class="skill-card panel rounded-lg p-3 cursor-pointer" onclick="openSkill('${n}')"><div class="text-xl mb-1">${skillEmoji(n)}</div><div class="text-white text-sm font-semibold mono">gitlink-${n}</div><div class="mt-1">${tag}</div><div class="text-[10px] text-[var(--green)] mt-2">📖 SKILL.md →</div></div>`;
}).join('');
}
renderSkills();
// ===== pr-guard =====
const STEPS=[{n:'① 采集',d:'pr +diff/+files',c:'#8b949e'},{n:'② AI Review',d:'分级找问题',c:'#d29922'},{n:'③ CI 检查',d:'ci +builds',c:'#58a6ff'},{n:'④ 汇总评论',d:'api reviews',c:'#a371f7'},{n:'⑤ 质量判定',d:'门禁规则',c:'#3fb950'}];
document.getElementById('pr-steps').innerHTML=STEPS.map((s,i)=>`<div class="step panel rounded p-3 text-center flex-1 min-w-[120px]" id="step-${i}"><div class="text-sm font-semibold text-white">${s.n}</div><div class="text-xs mono mt-1" style="color:${s.c}">${s.d}</div></div>${i<STEPS.length-1?'<span class="text-[#6e7681]">→</span>':''}`).join('');
function runPipeline(){
document.getElementById('pr-verdict').textContent='';STEPS.forEach((_,i)=>document.getElementById('step-'+i).classList.remove('active'));
let i=0;const tick=setInterval(()=>{if(i>0)document.getElementById('step-'+(i-1)).classList.remove('active');if(i>=STEPS.length){clearInterval(tick);document.getElementById('pr-verdict').innerHTML='<span style="color:var(--green)">✅ 质量判定：通过</span> ｜ 0 Critical + CI success → 建议合并';return;}document.getElementById('step-'+i).classList.add('active');i++;},600);
}
async function livePR(){
runRaw(`pr +list --owner ${getOwner()} --repo ${getRepo()} --format json`);
}
// ===== 雷达 + 协作图 =====
let radarChart=new Chart(document.getElementById('radar'),{type:'radar',data:{labels:['🔁 可复现性','📈 活跃度','📑 引用价值','🤝 协作健康'],datasets:[{label:'示例（点「实拉分析」换真实数据）',data:[6,5,5,6],fill:true,backgroundColor:'rgba(88,166,255,0.18)',borderColor:'#58a6ff',pointBackgroundColor:'#58a6ff'}]},options:{plugins:{legend:{labels:{color:'#c9d1d9',font:{size:11}}}},scales:{r:{min:0,max:10,ticks:{color:'#6e7681',backdropColor:'transparent',stepSize:2},grid:{color:'#30363d'},pointLabels:{color:'#c9d1d9',font:{size:12}},angleLines:{color:'#30363d'}}}}});
function drawCollab(contribs,repoName){
const svg=document.getElementById('collab-svg');svg.innerHTML='';const cx=180,cy=130,R=95;
svg.innerHTML+=`<circle cx="${cx}" cy="${cy}" r="24" fill="#1f6feb"/><text x="${cx}" y="${cy+3}" text-anchor="middle" fill="#fff" font-size="9">${(repoName||'repo').slice(0,8)}</text>`;
const top=(contribs||[]).slice(0,6);if(!top.length){svg.innerHTML+='<text x="180" y="250" text-anchor="middle" fill="#6e7681" font-size="10">（点「实拉分析」用真实贡献者重绘）</text>';return;}
const max=top[0].contributions||1;
top.forEach((c,i)=>{const a=(-Math.PI/2)+i*(2*Math.PI/top.length),x=cx+Math.cos(a)*R,y=cy+Math.sin(a)*R,rad=Math.max(8,18*(c.contributions/max)),core=i<2;
svg.innerHTML+=`<line x1="${cx}" y1="${cy}" x2="${x}" y2="${y}" stroke="${core?'#3fb950':'#30363d'}" stroke-width="${core?2:1}" stroke-dasharray="${core?'':'4'}"/>`;
svg.innerHTML+=`<circle cx="${x}" cy="${y}" r="${rad}" fill="${core?'#238636':'#6e7681'}"/><text x="${x}" y="${y+3}" text-anchor="middle" fill="#fff" font-size="9">${(c.name||'?').slice(0,8)}</text><text x="${x}" y="${y+rad+12}" text-anchor="middle" fill="#8b949e" font-size="8">${c.perc||''}</text>`;});
}
drawCollab(null);
async function analyze(){
document.getElementById('analyze-status').textContent='⏳ 采集中...';
try{
const r=await fetch('/api/analyze',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({owner:getOwner(),repo:getRepo(),token:getToken()})});
const d=await r.json();if(!d.ok){document.getElementById('analyze-status').textContent='❌ '+d.error;return;}
const s=d.scores;radarChart.data.datasets[0].label=`${d.owner}/${d.repo}${d.is_fork?'（⚠️ fork of '+d.fork_from+'）':''}`;
radarChart.data.datasets[0].data=[s.repro,s.activity,s.citation,s.collab];radarChart.update();
document.getElementById('analyze-status').innerHTML=`✅ ${d.contributor_count} 贡献者 · ${d.release_count} release · 协议 ${d.license}`;
document.getElementById('repo-meta').innerHTML=`${d.is_fork?'⚠️ <b style="color:var(--yellow)">是 fork</b>（引用应指 upstream '+d.fork_from+'）':'✅ 独立仓库'} · 巴士因子 <b style="color:${d.bus_risk==='低'?'var(--green)':d.bus_risk==='中'?'var(--yellow)':'var(--red)'}">${d.bus_factor}%（${d.bus_risk}风险）</b>`;
document.getElementById('repro-detail').innerHTML='可复现性 '+s.repro+'/'+d.repro_max+'：'+d.repro_detail.map(x=>x[1]?'✅'+x[0]:'❌'+x[0]).join(' · ');
drawCollab(d.contributors,d.name);
}catch(e){document.getElementById('analyze-status').textContent='❌ '+e;}
}
// 初始提示
appendOut('💡 左侧点分类展开 → 点动词（带 ⚙ 的有参数表单）→ 右侧填参 → ▶运行。','l-muted');
appendOut(' 本地命令（snippet/auth）免 token；公开仓库的 repo/issue 等其实不填 token 也能跑。','l-muted');
// ===== Skill 详情模态框 =====
async function openSkill(name){
const modal=document.getElementById('skill-modal');
document.getElementById('skill-modal-title').textContent='📖 gitlink-'+name;
const body=document.getElementById('skill-modal-body');body.innerHTML='<p class="text-[#8b949e]">⏳ 加载 SKILL.md...</p>';modal.classList.remove('hidden');
try{const r=await fetch('/api/skill?name='+encodeURIComponent(name));const d=await r.json();if(!d.ok){body.innerHTML='<p class="l-err">❌ '+d.error+'</p>';return;}body.innerHTML=marked.parse(d.content);}catch(e){body.innerHTML='<p class="l-err">❌ '+e+'</p>';}
}
function closeSkill(){document.getElementById('skill-modal').classList.add('hidden');}
document.addEventListener('keydown',e=>{if(e.key==='Escape')closeSkill();});
</script>
<div id="skill-modal" class="hidden fixed inset-0 z-50 flex items-center justify-center p-4" onclick="closeSkill()" style="background:rgba(0,0,0,.75)">
<div class="panel rounded-lg max-w-4xl w-full max-h-[88vh] flex flex-col" onclick="event.stopPropagation()">
<div class="flex items-center justify-between px-5 py-3 border-b border-[var(--border)]">
<h3 id="skill-modal-title" class="text-white font-bold text-lg"></h3>
<button onclick="closeSkill()" class="text-[#8b949e] hover:text-white text-3xl leading-none">×</button>
</div>
<div class="p-6 overflow-y-auto text-sm" id="skill-modal-body"></div>
</div>
</div>
</body>
</html>

319
demo/web/server.py Normal file
View File

@ -0,0 +1,319 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
gitlink-cli 演示网页 · 后端（零依赖，仅 Python 标准库）
作用：接收前端命令 + 访客 token，真跑 gitlink-cli，返回真实输出。
启动：python server.py → http://0.0.0.0:$PORT （默认 8000）
位置：仓库内 demo/web/server.py。CLI 在仓库根 ../../gitlink-cli[.exe]。
安全：本地/演示用。已做白名单（只允许 gitlink-cli 子命令）、subprocess 列表参数（不经 shell）、
30s 超时。访客 token 仅在请求内存中传给子进程，不写日志、不落盘。
"""
import http.server
import json
import os
import re
import socketserver
import subprocess
import sys
from pathlib import Path
from urllib.parse import urlparse, parse_qs
# Windows GBK 终端兼容
try:
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
except Exception:
pass
PORT = int(os.getenv("PORT", "8000"))
HOST = os.getenv("HOST", "0.0.0.0") # 云端需 0.0.0.0；只听本机设 HOST=127.0.0.1
ROOT = Path(__file__).resolve().parent # .../demo/web
REPO_ROOT = ROOT.parent.parent # 仓库根 .../gitlink-cli
def _find_cli():
"""CLI 位置：GITLINK_BIN > 仓库内 > PATH。Linux=gitlink-cli，Windows=gitlink-cli.exe。"""
env = os.getenv("GITLINK_BIN")
if env and Path(env).exists():
return Path(env)
for name in ("gitlink-cli", "gitlink-cli.exe"):
p = REPO_ROOT / name
if p.exists():
return p
for d in os.getenv("PATH", "").split(os.pathsep):
p = Path(d) / "gitlink-cli"
if p.exists():
return p
return REPO_ROOT / "gitlink-cli" # 占位
CLI = _find_cli()
CWD = str(REPO_ROOT) # 让 --owner/--repo 可从 git remote 自动解析
ALLOWED_DOMAINS = { # 全部 30 个顶层域
"api", "auth", "branch", "ci", "compare", "config", "dataset", "doctor",
"file", "health", "ignore", "issue", "label", "license", "member",
"milestone", "org", "pipeline", "pm", "pr", "profile", "release", "repo",
"search", "snippet", "user", "version", "webhook", "wiki", "workflow",
}
NEEDS_TOKEN_DOMAINS = { # 平台域（访客需填 token）
"repo", "issue", "pr", "branch", "release", "search", "label", "member",
"milestone", "webhook", "wiki", "org", "user", "ci", "compare", "dataset",
"health", "license", "pipeline", "pm", "profile", "workflow", "api",
}
LOCAL_DOMAINS = {"snippet", "auth", "config", "version", "doctor"}
def _run_cli(args, token="", timeout=30):
env = dict(os.environ)
if token:
env["GITLINK_TOKEN"] = token
r = subprocess.run(
[str(CLI)] + args, capture_output=True, text=True, timeout=timeout,
cwd=CWD, encoding="utf-8", errors="replace", env=env,
)
return r.stdout, r.stderr, r.returncode
def _parse_json(stdout):
s = stdout.strip()
i, j = s.find("{"), s.rfind("}")
if i < 0 or j < 0:
return None
try:
return json.loads(s[i:j + 1])
except Exception:
return None
def _license_name(text):
t = (text or "").lower()
if "mulan" in t: return "Mulan PSL v2"
if t.startswith("mit") or "mit license" in t: return "MIT"
if "apache" in t: return "Apache 2.0"
if "gpl" in t: return "GPL"
if "bsd" in t: return "BSD"
return "有 LICENSE" if text else "无"
def analyze_repo(owner, repo, token):
"""采集 + 按 research-insight 评分表算四维 + 巴士因子。"""
def cli(*a):
return _run_cli(list(a), token=token, timeout=30)
info_o, _, _ = cli("repo", "+info", "--owner", owner, "--repo", repo, "--format", "json")
info = (_parse_json(info_o) or {}).get("data") or {}
contrib_o, _, _ = cli("repo", "+contributors", "--owner", owner, "--repo", repo, "--format", "json")
contribs = ((_parse_json(contrib_o) or {}).get("data") or {}).get("list") or []
contribs_sorted = sorted(contribs, key=lambda c: -(c.get("contributions") or 0))
rel_o, _, _ = cli("release", "+list", "--owner", owner, "--repo", repo, "--format", "json")
releases = ((_parse_json(rel_o) or {}).get("data") or {}).get("releases") or []
lic_o, _, _ = cli("file", "+get", "--owner", owner, "--repo", repo, "--path", "LICENSE", "--format", "json")
lic_text = ""
lic_parsed = _parse_json(lic_o)
if lic_parsed:
d = lic_parsed.get("data") or {}
entries = d.get("entries") if isinstance(d, dict) else None
if isinstance(entries, dict):
lic_text = entries.get("content") or ""
elif isinstance(d, str):
lic_text = d
ci_o, _, _ = cli("repo", "+tree", "--owner", owner, "--repo", repo, "--path", ".gitea/workflows", "--format", "json")
ci_entries = ((_parse_json(ci_o) or {}).get("data") or {}).get("entries") or []
has_ci = bool(ci_entries)
tree_o, _, _ = cli("repo", "+tree", "--owner", owner, "--repo", repo, "--format", "json")
root_files = [str(e.get("name", "")) for e in ((_parse_json(tree_o) or {}).get("data") or {}).get("entries") or []]
lock_files = {"go.sum", "package-lock.json", "yarn.lock", "Cargo.lock", "requirements.txt", "poetry.lock", "pom.xml"}
has_lock = any(f in lock_files for f in root_files)
has_readme = any(f.lower().startswith("readme") for f in root_files)
# 可复现性（工程类，满分 8：数据项 N/A）
repro, repro_detail = 0, []
repro += 2 if has_ci else 0; repro_detail.append(("CI 配置", has_ci))
repro += 2 if has_lock else 0; repro_detail.append(("依赖锁定", has_lock))
repro += 2 if has_readme else 0; repro_detail.append(("运行文档", has_readme))
ver = bool(releases or info.get("version_releases_count"))
repro += 2 if ver else 0; repro_detail.append(("版本归档", ver))
n_contrib = len(contribs)
activity = min(10, round(n_contrib / 3)) if n_contrib else 2 # 无 commits API，用贡献者规模近似
citation = 0
citation += 3 if lic_text else 0
citation += 3 if ver else 0
citation += 2 if has_readme else 0
citation += 2 if (info.get("fork_info") or {}).get("fork_project_user_login") else 0
citation = min(10, citation)
top_perc = 0.0
if contribs_sorted:
try:
top_perc = float(re.sub(r"[^\d.]", "", str(contribs_sorted[0].get("contribution_perc", "0"))))
except Exception:
top_perc = 0.0
collab = 10 if top_perc < 33 else (6 if top_perc < 50 else 3)
fork_from = (info.get("fork_info") or {}).get("fork_project_user_login")
return {
"ok": True, "owner": owner, "repo": repo,
"is_fork": bool(fork_from), "fork_from": fork_from,
"name": info.get("name", repo),
"license": _license_name(lic_text),
"contributor_count": n_contrib,
"release_count": len(releases),
"version_releases_count": info.get("version_releases_count", 0),
"contributors": [
{"name": c.get("name") or c.get("login") or "?",
"contributions": c.get("contributions", 0),
"perc": c.get("contribution_perc", "")}
for c in contribs_sorted[:8]
],
"scores": {"repro": repro, "activity": activity, "citation": citation, "collab": collab},
"repro_max": 8, "repro_detail": repro_detail,
"bus_factor": top_perc,
"bus_risk": "低" if top_perc < 33 else ("中" if top_perc < 50 else "高"),
}
class Handler(http.server.BaseHTTPRequestHandler):
def _cors(self):
self.send_header("Access-Control-Allow-Origin", "*")
self.send_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
self.send_header("Access-Control-Allow-Headers", "Content-Type")
def do_OPTIONS(self):
self.send_response(204); self._cors(); self.end_headers()
def do_GET(self):
path = urlparse(self.path).path
if path in ("/", "/index.html"):
self._serve_file("index.html", "text/html")
elif path == "/api/cli":
self._json({"ok": True, "cli": str(CLI), "exists": CLI.exists()})
elif path == "/api/domains":
self._json({"ok": True, "domains": sorted(ALLOWED_DOMAINS), "local": sorted(LOCAL_DOMAINS)})
elif path == "/api/health":
self._json({"ok": True, "cli_exists": CLI.exists()})
elif path == "/api/skill":
self._handle_skill()
else:
self.send_error(404)
def _handle_skill(self):
q = parse_qs(urlparse(self.path).query)
name = (q.get("name") or [""])[0].strip()
if not name:
self._json({"ok": False, "error": "缺少 ?name="}); return
skill_md = REPO_ROOT / "skills" / f"gitlink-{name}" / "SKILL.md"
if not skill_md.exists():
self._json({"ok": False, "error": f"找不到 SKILL.md：gitlink-{name}"}); return
self._json({"ok": True, "name": name, "content": skill_md.read_text(encoding="utf-8")})
def do_POST(self):
path = urlparse(self.path).path
body = self._read_body()
if path == "/api/run":
self._handle_run(body)
elif path == "/api/analyze":
owner = (body.get("owner") or "").strip()
repo = (body.get("repo") or "").strip()
token = (body.get("token") or "").strip()
if not owner or not repo:
self._json({"ok": False, "error": "缺少 owner/repo"}); return
try:
self._json(analyze_repo(owner, repo, token))
except subprocess.TimeoutExpired:
self._json({"ok": False, "error": "采集超时（>30s）"})
except Exception as e:
self._json({"ok": False, "error": str(e)})
else:
self.send_error(404)
def _handle_run(self, body):
cmd = (body.get("cmd") or "").strip()
token = (body.get("token") or "").strip()
if not cmd:
self._json({"ok": False, "error": "空命令"}); return
args = cmd.split()
while args and args[0] in ("gitlink-cli", "gitlink-cli.exe", "./gitlink-cli.exe"):
args = args[1:]
if not args:
self._json({"ok": False, "error": "缺少子命令"}); return
domain = args[0]
if domain not in ALLOWED_DOMAINS:
self._json({"ok": False, "error": f"不允许的命令：{domain}（仅限 gitlink-cli 子命令）"}); return
needs_token = domain in NEEDS_TOKEN_DOMAINS
try:
out, err, code = _run_cli(args, token=token, timeout=30)
# 失败时从 stderr 取首行作为 error，前端绝不再显示 undefined
err_msg = None
if code != 0:
first = (err.strip() or out.strip()).splitlines()
err_msg = first[0][:200] if first else f"命令失败（退出码 {code}）"
self._json({
"ok": code == 0, "cmd": f"gitlink-cli {' '.join(args)}",
"stdout": out, "stderr": err, "code": code, "error": err_msg,
"needs_token": needs_token, "token_provided": bool(token),
})
except subprocess.TimeoutExpired:
self._json({"ok": False, "error": "命令超时（>30s），可能涉及交互输入"})
except Exception as e:
self._json({"ok": False, "error": str(e)})
def _read_body(self):
length = int(self.headers.get("Content-Length", 0) or 0)
raw = self.rfile.read(length) if length else b"{}"
try:
return json.loads(raw)
except Exception:
return {}
def _json(self, obj):
data = json.dumps(obj, ensure_ascii=False).encode("utf-8")
self.send_response(200)
self.send_header("Content-Type", "application/json; charset=utf-8")
self._cors()
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def _serve_file(self, name, mime):
p = ROOT / name
if not p.exists():
self.send_error(404, f"{name} 不存在"); return
data = p.read_bytes()
self.send_response(200)
self.send_header("Content-Type", f"{mime}; charset=utf-8")
self._cors()
self.send_header("Content-Length", str(len(data)))
self.end_headers()
self.wfile.write(data)
def log_message(self, *a):
pass
class ReuseTCPServer(socketserver.ThreadingMixIn, socketserver.TCPServer):
allow_reuse_address = True
daemon_threads = True # 每个请求独立线程，单个卡死不阻塞其他请求
if __name__ == "__main__":
if not CLI.exists():
print(f"[!] 找不到 gitlink-cli 二进制：{CLI}")
print(" 请先编译：cd <仓库根> && go build -o gitlink-cli . （Linux）")
print(" 或设环境变量 GITLINK_BIN 指向已有二进制。")
with ReuseTCPServer((HOST, PORT), Handler) as httpd:
print(f"[OK] gitlink-cli 演示后端已启动：http://{HOST}:{PORT}")
print(f" CLI：{CLI}（exists={CLI.exists()}）")
print(f" 访客在网页顶栏填自己的 GitLink token 即可跑平台命令。Ctrl+C 停止。")
try:
httpd.serve_forever()
except KeyboardInterrupt:
print("\n已停止")

482
doc/CODE_SYNC_STRATEGY.md
View File

@ -1,482 +0,0 @@
# GitLink-GitHub 代码双向同步方案
**版本**: v1.0
**日期**: 2026-04-02
**状态**: 已确认
---
## 1 概述
实现 GitHub（主仓）和 GitLink（镜像仓）的代码双向同步，确保两个平台的代码始终一致。通过 Git hooks 在关键操作点进行同步检查，自动解决冲突或提示用户手动处理。
### 1.1 核心原则
- **GitHub 为主仓**：GitHub 是代码的唯一真实来源
- **GitLink 为镜像仓**：GitLink 作为备份和协作平台
- **Hook 控制在 GitLink**：所有同步逻辑通过 GitLink 本地 hooks 实现
- **GitHub 完全被动**：GitHub 不需要任何 hook 操作
- **冲突自动解决**：优先自动 rebase 解决，无法解决时提示用户
---
## 2 同步触发点
### 2.1 四个关键触发点
| 触发点 | Hook | 检查内容 | 动作 |
|--------|------|---------|------|
| **直接 commit** | `pre-commit` | GitLink HEAD vs GitHub HEAD | 不同步则阻止 commit |
| **直接 push** | `pre-push` | GitLink HEAD vs GitHub HEAD | 不同步则阻止 push |
| **创建 PR** | Webhook | 拉取最新 GitHub 代码 | 自动 rebase 到最新 GitHub 代码 |
| **Merge PR** | Webhook | 拉取最新 GitHub 代码 + 自动 rebase | 解决冲突后 merge，并推送到 GitHub |
### 2.2 触发点详解
#### 2.2.1 Pre-commit Hook（直接 commit）
**场景**：用户在 GitLink 本地修改代码后执行 `git commit`
**流程**：
```
1. 用户执行: git commit -m "..."
2. pre-commit hook 触发
3. 检查: GitLink HEAD == GitHub HEAD?
- 是 → 允许 commit
- 否 → 阻止 commit，提示用户执行 rebase
```
**实现**：
```bash
#!/bin/bash
# .git/hooks/pre-commit
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
```
#### 2.2.2 Pre-push Hook（直接 push）
**场景**：用户在 GitLink 本地修改代码后执行 `git push`
**流程**：
```
1. 用户执行: git push origin main
2. pre-push hook 触发
3. 检查: GitLink HEAD == GitHub HEAD?
- 是 → 允许 push
- 否 → 阻止 push，提示用户执行 rebase
```
**实现**：
```bash
#!/bin/bash
# .git/hooks/pre-push
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
```
#### 2.2.3 创建 PR 时同步（Webhook）
**场景**：用户在 GitLink 创建 PR
**流程**：
```
1. 用户在 GitLink 创建 PR: feature → main
2. GitLink webhook 触发
3. 拉取最新 GitHub 代码到 GitLink
4. 自动 rebase PR 分支到最新 GitHub main
5. 如果冲突可自动解决 → 直接解决
6. 如果冲突无法自动解决 → 提示用户手动解决
```
**实现逻辑**：
```
POST /webhook/pr-created
├─ 获取 PR 信息 (source_branch, target_branch)
├─ git fetch github main
├─ git checkout source_branch
├─ git rebase github/main
│ ├─ 冲突可解决 → 自动解决 + git rebase --continue
│ └─ 冲突无法解决 → 提示用户，PR 标记为 "需要手动 rebase"
└─ 更新 PR 状态
```
#### 2.2.4 Merge PR 时同步（Webhook）
**场景**：用户在 GitLink 合并 PR
**流程**：
```
1. 用户在 GitLink 点击 "Merge PR"
2. GitLink webhook 触发
3. 拉取最新 GitHub 代码到 GitLink
4. 自动 rebase PR 分支到最新 GitHub main
5. 如果冲突可自动解决 → 直接解决 + merge
6. 如果冲突无法自动解决 → 停止 merge，提示用户
7. Merge 成功后，自动 push 到 GitHub
```
**实现逻辑**：
```
POST /webhook/pr-merge
├─ 获取 PR 信息 (source_branch, target_branch)
├─ git fetch github main
├─ git checkout source_branch
├─ git rebase github/main
│ ├─ 冲突可解决 → 自动解决 + git rebase --continue
│ └─ 冲突无法解决 → 停止 merge，返回错误
├─ git checkout target_branch
├─ git merge source_branch
├─ git push github target_branch
└─ 更新 PR 状态为 "已合并"
```
---
## 3 冲突处理策略
### 3.1 冲突类型与解决方案
| 冲突类型 | 原因 | 解决方案 |
|---------|------|--------|
| **文件内容冲突** | 同一文件同一行被修改 | 自动 rebase（Git 尝试自动合并） |
| **文件删除冲突** | 一边删除，一边修改 | 提示用户手动选择 |
| **文件重命名冲突** | 同一文件被重命名为不同名称 | 提示用户手动选择 |
| **二进制文件冲突** | 二进制文件被修改 | 提示用户手动选择 |
### 3.2 自动解决策略
**可自动解决的冲突**：
- 不同文件的修改
- 同一文件不同行的修改
- 简单的文本冲突（Git 能自动合并）
**实现**：
```bash
git rebase github/main --no-edit
# 如果有冲突，尝试自动解决
if [ $? -ne 0 ]; then
# 尝试使用 ours 或 theirs 策略
git rebase --continue --strategy=recursive -X ours
fi
```
### 3.3 无法自动解决时的处理
**流程**：
```
1. Rebase 失败，存在冲突
2. 返回错误信息给用户
3. PR 标记为 "冲突" 状态
4. 用户本地手动解决冲突
5. 用户执行: git rebase --continue
6. 用户 push 到 GitLink
7. Pre-push hook 检查 → 通过
8. 用户重新点击 "Merge PR"
```
---
## 4 实现架构
### 4.1 组件清单
| 组件 | 位置 | 职责 |
|------|------|------|
| **Pre-commit Hook** | `.git/hooks/pre-commit` | 检查 commit 前的同步状态 |
| **Pre-push Hook** | `.git/hooks/pre-push` | 检查 push 前的同步状态 |
| **PR Created Webhook** | GitLink 服务端 | 创建 PR 时自动 rebase |
| **PR Merged Webhook** | GitLink 服务端 | Merge PR 时自动 rebase + push GitHub |
| **Sync CLI Command** | `gitlink-cli sync` | 手动触发同步（可选） |
### 4.2 数据流
```
GitHub (主仓)
↓ (git fetch)
GitLink 本地仓库
├─ pre-commit hook (检查同步)
├─ pre-push hook (检查同步)
└─ webhook (创建/合并 PR 时自动 rebase)
↓ (git push)
GitLink 远程仓库
↓ (webhook)
GitHub (推送更新)
```
---
## 5 用户工作流
### 5.1 场景 1：直接 commit 到 GitLink
```bash
# 1. 用户在 GitLink 本地修改代码
cd gitlink-cli
echo "new code" >> file.txt
# 2. 执行 commit
git commit -m "feat: add new feature"
# 3. Pre-commit hook 检查
# ✅ 如果 HEAD 同步 → commit 成功
# ❌ 如果 HEAD 不同步 → commit 失败，提示 rebase
# 4. 如果失败，用户手动 rebase
git fetch github
git rebase github/main
# 5. 重新 commit
git commit -m "feat: add new feature"
```
### 5.2 场景 2：创建 PR
```bash
# 1. 用户创建 feature 分支
git checkout -b feature/new-feature
# 2. 修改代码并 commit
git commit -m "feat: implement feature"
# 3. Push 到 GitLink
git push origin feature/new-feature
# 4. 在 GitLink 创建 PR: feature/new-feature → main
# GitLink webhook 自动触发：
# - 拉取最新 GitHub 代码
# - 自动 rebase feature 分支到最新 GitHub main
# - 如果冲突可解决 → 自动解决
# - 如果冲突无法解决 → PR 标记为 "需要手动 rebase"
```
### 5.3 场景 3：Merge PR
```bash
# 1. 用户在 GitLink 点击 "Merge PR"
# GitLink webhook 自动触发：
# - 拉取最新 GitHub 代码
# - 自动 rebase PR 分支到最新 GitHub main
# - 如果冲突可解决 → 自动解决 + merge
# - 如果冲突无法解决 → merge 失败，提示用户
# 2. Merge 成功后，自动 push 到 GitHub
# GitHub 代码自动更新
```
### 5.4 场景 4：直接 push 到 GitLink
```bash
# 1. 用户本地修改代码并 commit
git commit -m "fix: bug fix"
# 2. 执行 push
git push origin main
# 3. Pre-push hook 检查
# ✅ 如果 HEAD 同步 → push 成功
# ❌ 如果 HEAD 不同步 → push 失败，提示 rebase
# 4. 如果失败，用户手动 rebase
git fetch github
git rebase github/main
git push origin main
```
---
## 6 配置与部署
### 6.1 Hook 安装
在 gitlink-cli 项目中创建 hooks：
```bash
# 创建 hooks 目录
mkdir -p .githooks
# 创建 pre-commit hook
cat > .githooks/pre-commit << 'EOF'
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
EOF
# 创建 pre-push hook
cat > .githooks/pre-push << 'EOF'
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "❌ Error: GitLink HEAD 不同步 GitHub"
echo "请执行: git fetch github && git rebase github/main"
exit 1
fi
exit 0
EOF
# 设置权限
chmod +x .githooks/pre-commit .githooks/pre-push
# 配置 Git 使用这些 hooks
git config core.hooksPath .githooks
```
### 6.2 Webhook 配置
在 GitLink 项目设置中配置 webhooks：
**PR Created Webhook**：
- URL: `https://your-server/webhook/pr-created`
- 事件: Pull Request Created
- 负载: PR 信息（source_branch, target_branch, pr_id）
**PR Merged Webhook**：
- URL: `https://your-server/webhook/pr-merged`
- 事件: Pull Request Merged
- 负载: PR 信息（source_branch, target_branch, pr_id）
---
## 7 风险与缓解
### 7.1 潜在风险
| 风险 | 影响 | 缓解措施 |
|------|------|--------|
| **Rebase 失败** | PR 无法合并 | 提示用户手动解决，PR 标记为冲突 |
| **GitHub 网络不可达** | Hook 超时 | 设置超时时间，失败时提示用户 |
| **Webhook 失败** | 同步不及时 | 重试机制 + 手动同步命令 |
| **并发 merge** | 数据不一致 | 使用分布式锁或队列 |
### 7.2 缓解方案
**Hook 超时处理**：
```bash
timeout 5 git ls-remote https://github.com/owner/repo HEAD
if [ $? -eq 124 ]; then
echo "⚠️ Warning: GitHub 网络超时，跳过同步检查"
exit 0 # 允许操作继续
fi
```
**Webhook 重试**：
```
失败 → 等待 5 秒 → 重试
失败 → 等待 10 秒 → 重试
失败 → 等待 30 秒 → 重试
失败 → 记录日志，通知管理员
```
---
## 8 手动同步命令（可选）
提供 CLI 命令供用户手动触发同步：
```bash
# 手动同步 GitLink 到最新 GitHub 代码
gitlink-cli sync --from github --to gitlink
# 手动同步 GitHub 到最新 GitLink 代码（不推荐）
gitlink-cli sync --from gitlink --to github
# 查看同步状态
gitlink-cli sync status
```
---
## 9 验证与测试
### 9.1 测试场景
| 场景 | 预期结果 | 验证方法 |
|------|---------|--------|
| GitHub 有新代码，GitLink 直接 commit | Commit 失败，提示 rebase | 执行 commit，检查错误信息 |
| GitHub 有新代码，GitLink 直接 push | Push 失败，提示 rebase | 执行 push，检查错误信息 |
| 创建 PR 时 GitHub 有新代码 | 自动 rebase，PR 创建成功 | 创建 PR，检查 PR 状态 |
| Merge PR 时 GitHub 有新代码 | 自动 rebase + merge，推送 GitHub | Merge PR，检查 GitHub 代码 |
| 冲突无法自动解决 | PR 标记为<E8AEB0><E4B8BA>突，提示用户 | 创建冲突 PR，检查状态 |
### 9.2 测试命令
```bash
# 1. 测试 pre-commit hook
git commit -m "test"
# 2. 测试 pre-push hook
git push origin main
# 3. 测试 PR 创建同步
# 在 GitLink 创建 PR，检查是否自动 rebase
# 4. 测试 PR 合并同步
# 在 GitLink 合并 PR，检查 GitHub 是否更新
```
---
## 10 后续优化
### 10.1 短期（1-2 周）
- [ ] 实现 pre-commit 和 pre-push hooks
- [ ] 实现 PR Created 和 PR Merged webhooks
- [ ] 编写测试用例
- [ ] 文档完善
### 10.2 中期（2-4 周）
- [ ] 实现手动同步 CLI 命令
- [ ] 添加同步状态监控
- [ ] 优化冲突自动解决策略
- [ ] 添加日志和告警
### 10.3 长期（1 个月+）
- [ ] Issue 和 PR 元数据同步
- [ ] 评论和 Review 同步
- [ ] 自动化测试和 CI/CD 集成
- [ ] 性能优化和扩展性改进
---
## 11 总结
本方案通过 **Git hooks + Webhooks** 的组合，实现了 GitHub 和 GitLink 的代码双向同步。核心特点：
✅ **GitHub 为主仓**：确保代码唯一真实来源
✅ **自动冲突解决**：优先自动 rebase，无法解决时提示用户
✅ **多触发点**：commit、push、PR 创建、PR 合并都有同步检查
✅ **用户友好**：清晰的错误提示和恢复指导
✅ **低风险**：失败时提示用户，不会自动破坏代码
---
**审批人**: [待确认]
**实施日期**: [待定]
**联系人**: [待定]

373
doc/CODE_SYNC_STRATEGY_FINAL.md
View File

@ -1,373 +0,0 @@
# GitLink-GitHub 代码双向同步方案（最终版）
**版本**: v2.0（最终确认）
**日期**: 2026-04-02
**状态**: 已确认，可实施
---
## 1 核心原则
- **GitHub 为主仓**：GitHub 是代码的唯一真实来源
- **GitLink 为镜像仓**：GitLink 作为备份和协作平台
- **所有操作在 GitLink 服务端**：无需用户本地配置
- **Main 分支保护**：只能通过 PR merge，禁止直接 push
- **关键点同步**：PR create/patch/merge 时自动同步 GitHub
---
## 2 同步触发点
### 2.1 三个关键触发点
| 触发点 | 事件 | 操作 |
|--------|------|------|
| **PR Create** | 用户创建 PR | fetch GitHub + rebase |
| **PR Patch** | 用户修改 PR（push 新 commit） | fetch GitHub + rebase |
| **PR Merge** | 用户点击 merge | fetch GitHub + rebase + merge + push GitHub |
### 2.2 详细流程
#### 2.2.1 PR Create 时同步
**触发**：用户在 GitLink 创建 PR（feature → main）
**流程**：
```
1. GitLink webhook 接收 PR created 事件
2. 执行：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → PR 标记为 "需要 rebase"
│ │ 返回错误信息给用户
│ └─ 无冲突 → PR 状态正常，可以 merge
└─ 完成
```
**用户体验**：
- 如果无冲突：PR 创建成功，可以 merge
- 如果有冲突：PR 创建成功，但标记为冲突，提示用户本地解决冲突后重新 push
#### 2.2.2 PR Patch 时同步
**触发**：用户修改 PR（在 feature 分支上新增 commit 并 push）
**流程**：
```
1. GitLink webhook 接收 PR updated 事件
2. 执行：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → PR 标记为 "需要 rebase"
│ │ 返回错误信息给用户
│ └─ 无冲突 → PR 状态正常，可以 merge
└─ 完成
```
**用户体验**：
- 每次 push 新 commit 时，自动检查是否与 GitHub 最新代码冲突
- 如果有冲突，立即提示用户
#### 2.2.3 PR Merge 时同步
**触发**：用户在 GitLink 点击 "Merge PR"
**流程**：
```
1. GitLink webhook 接收 PR merged 事件
2. 执行（事务性操作）：
├─ git fetch github main
├─ git checkout feature_branch
├─ git rebase github/main
├─ 检查是否有冲突
│ ├─ 有冲突 → merge 失败
│ │ 返回错误信息给用户
│ │ PR 状态回滚到 "open"
│ └─ 无冲突 → 继续
├─ git checkout main
├─ git merge feature_branch
├─ git push github main
├─ 检查 push 是否成功
│ ├─ 失败 → merge 失败，回滚
│ └─ 成功 → merge 成功，PR 标记为 "merged"
└─ 完成
```
**用户体验**：
- 点击 merge 后，自动完成所有同步操作
- 如果有冲突或 push 失败，立即反馈给用户
- 成功后，GitHub 和 GitLink 代码自动同步
---
## 3 Main 分支保护
### 3.1 保护规则
| 规则 | 说明 |
|------|------|
| 禁止直接 push | 用户不能直接 push 到 main 分支 |
| 只能 PR merge | main 分支只能通过 PR merge 更新 |
| 禁止 force push | GitLink 禁止所有 force push 操作 |
### 3.2 实现
在 GitLink 服务端配置分支保护：
```
项目设置 → 分支保护
├─ 分支名称: main
├─ 禁止直接 push: ✅
├─ 禁止 force push: ✅
└─ 只能通过 PR merge: ✅
```
---
## 4 用户工作流
### 4.1 场景 1：创建 PR
```bash
# 1. 用户在本地创建 feature 分支
git checkout -b feature/new-feature
# 2. 修改代码并 commit
git commit -m "feat: implement feature"
# 3. Push 到 GitLink
git push origin feature/new-feature
# 4. 在 GitLink 创建 PR: feature/new-feature → main
# GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - 如果无冲突 → PR 创建成功
# - 如果有冲突 → PR 标记为 "需要 rebase"，提示用户
```
### 4.2 场景 2：修改 PR（Patch）
```bash
# 1. 用户在 feature 分支继续修改
git add .
git commit -m "fix: address review comments"
# 2. Push 到 GitLink
git push origin feature/new-feature
# 3. GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - 如果无冲突 → PR 更新成功
# - 如果有冲突 → PR 标记为 "需要 rebase"，提示用户
```
### 4.3 场景 3：Merge PR
```bash
# 1. 用户在 GitLink 点击 "Merge PR"
# GitLink webhook 自动触发：
# - fetch github main
# - rebase feature 到 github/main
# - merge feature 到 main
# - push 到 github main
# - 如果无冲突 → merge 成功，GitHub 自动更新
# - 如果有冲突 → merge 失败，提示用户
```
### 4.4 场景 4：直接 Push（不允许）
```bash
# 用户尝试直接 push 到 main
git push origin main
# GitLink 拒绝：
# ❌ Error: 禁止直接 push 到 main 分支
# 请通过 PR merge 提交代码
```
---
## 5 冲突处理
### 5.1 冲突检测
在 PR create/patch/merge 时，GitLink 自动检查是否有冲突：
```bash
git rebase github/main
# 如果有冲突，rebase 会失败
if [ $? -ne 0 ]; then
# 有冲突
return error "冲突检测"
fi
```
### 5.2 冲突提示
当检测到冲突时，返回给用户：
```json
{
"ok": false,
"error": {
"code": "CONFLICT",
"message": "PR 与 GitHub 最新代码有冲突",
"details": {
"conflicted_files": ["file1.js", "file2.js"],
"suggestion": "请在本地解决冲突后重新 push"
}
}
}
```
### 5.3 用户解决冲突
```bash
# 1. 用户本地拉取最新代码
git fetch origin
git fetch github
# 2. 本地 rebase 到 github/main
git rebase github/main
# 3. 手动解决冲突
# 编辑冲突文件，解决冲突
# 4. 继续 rebase
git add .
git rebase --continue
# 5. 强制推送到 GitLink（覆盖之前的 commit）
git push origin feature/new-feature --force-with-lease
# 6. GitLink 再次检查冲突
# 如果无冲突 → PR 更新成功
```
---
## 6 错误处理
### 6.1 常见错误
| 错误 | 原因 | 解决方案 |
|------|------|--------|
| 冲突 | PR 与 GitHub 最新代码冲突 | 本地解决冲突后重新 push |
| Push 失败 | GitHub 网络问题 | 重试或联系管理员 |
| Merge 失败 | 冲突或权限问题 | 检查冲突或权限 |
### 6.2 错误恢复
**如果 PR merge 失败**：
```
1. GitLink 自动回滚 merge 操作
2. PR 状态回到 "open"
3. 用户收到错误提示
4. 用户解决问题后重新 merge
```
---
## 7 实现清单
### 7.1 GitLink 服务端
- [ ] 配置 main 分支保护（禁止直接 push、禁止 force push）
- [ ] 实现 PR created webhook
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] 检查冲突，标记 PR 状态
- [ ] 实现 PR updated webhook
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] 检查冲突，标记 PR 状态
- [ ] 实现 PR merged webhook（事务性操作）
- [ ] fetch github main
- [ ] rebase feature 到 github/main
- [ ] merge feature 到 main
- [ ] push 到 github main
- [ ] 失败时回滚
### 7.2 错误提示
- [ ] 冲突时返回详细错误信息
- [ ] 包含冲突文件列表
- [ ] 包含解决方案建议
### 7.3 文档
- [ ] 更新 README，说明 main 分支保护规则
- [ ] 编写用户指南，说明 PR 工作流
- [ ] 编写故障排查指南
---
## 8 验证与测试
### 8.1 测试场景
| 场景 | 预期结果 |
|------|---------|
| 创建无冲突 PR | PR 创建成功 |
| 创建有冲突 PR | PR 标记为冲突，提示用户 |
| Patch 无冲突 | PR 更新成功 |
| Patch 有冲突 | PR 标记为冲突，提示用户 |
| Merge 无冲突 | Merge 成功，GitHub 自动更新 |
| Merge 有冲突 | Merge 失败，PR 回滚到 open |
| 直接 push main | 拒绝，提示只能 PR merge |
| Force push | 拒绝，提示禁止 force push |
### 8.2 测试命令
```bash
# 1. 创建 PR
git checkout -b feature/test
echo "test" >> file.txt
git commit -m "test"
git push origin feature/test
# 在 GitLink 创建 PR
# 2. 修改 PR
echo "test2" >> file.txt
git commit -m "test2"
git push origin feature/test
# 3. Merge PR
# 在 GitLink 点击 merge
# 4. 验证 GitHub 是否更新
git log --oneline # 检查 GitHub 是否有新 commit
```
---
## 9 总结
**方案特点**：
✅ **简洁**：只在 PR create/patch/merge 时同步
✅ **安全**：main 分支保护，禁止直接 push
✅ **可靠**：事务性 merge，失败自动回滚
✅ **用户友好**：清晰的错误提示和恢复指导
✅ **无需本地配置**：所有操作在 GitLink 服务端
**预期效果**：
- GitHub 和 GitLink 代码始终一致
- 用户只需正常 git 操作
- 冲突自动检测，提示用户解决
- 代码质量有保证（PR review + merge）
---
**审批**：已确认
**实施日期**：待定
**联系人**：待定

595
doc/CODE_SYNC_STRATEGY_REVIEW.md
View File

@ -1,595 +0,0 @@
# 代码同步方案 - 深度审视与优化
**审视日期**: 2026-04-02
**审视范围**: 用户场景、漏洞、优化点
---
## 1 发现的关键漏洞
### 1.1 漏洞 1：GitHub 直接 push 无法同步到 GitLink
**问题描述**：
- 用户在 GitHub 直接 push 代码（不通过 GitLink）
- GitLink 本地仓库不知道 GitHub 有新代码
- 下次用户在 GitLink 操作时，HEAD 已经不同步，但用户不知道
**场景**：
```
1. 用户在 GitHub Web UI 直接修改文件并 commit
2. 或用户在另一台机器 push 到 GitHub
3. GitLink 本地仓库 HEAD 仍指向旧代码
4. 用户在 GitLink 执行 commit/push 时，pre-commit/pre-push hook 才发现不同步
5. 用户被迫 rebase，但此时可能已经做了本地修改
```
**影响**：
- 用户体验差：突然被告知需要 rebase
- 可能丢失本地修改：如果用户强制操作
**优化方案**：
- 添加 **post-checkout hook**：每次切换分支时检查 GitHub 是否有新代码
- 添加 **post-merge hook**：每次 merge 后检查 GitHub 是否有新代码
- 提供 **定时同步任务**：每 N 分钟自动检查一次 GitHub 是否有新代码
---
### 1.2 漏洞 2：Force Push 绕过 Hook
**问题描述**：
- 用户可以使用 `git push --force` 绕过 pre-push hook
- 这会导致 GitLink 和 GitHub 代码不一致
**场景**：
```bash
git push origin main --force # 绕过 pre-push hook
```
**影响**：
- 破坏同步机制
- 可能覆盖他人代码
**优化方案**：
- 在 pre-push hook 中检查 `--force` 标志，直接拒绝
- 或在 GitLink 服务端配置分支保护，禁止 force push
---
### 1.3 漏洞 3：多分支场景处理不清
**问题描述**：
- 方案只考虑了 `main` 分支的同步
- 用户可能在多个分支上工作（develop、feature 等）
- 不同分支的同步策略不同
**场景**：
```
1. 用户在 feature 分支工作
2. GitHub 的 main 分支有新代码
3. 用户在 feature 分支 commit，pre-commit hook 检查 main 分支
4. 但用户实际在 feature 分支，不需要同步 main
```
**影响**：
- Hook 逻辑不清：应该检查当前分支还是 main 分支？
- 可能误报或漏报
**优化方案**：
- **明确分支同步策略**：
- `main` 分支：必须与 GitHub main 同步
- `develop` 分支：必须与 GitHub develop 同步
- `feature/*` 分支：只需与本地 main 同步（可选）
- Hook 根据当前分支选择对应的检查策略
---
### 1.4 漏洞 4：Rebase 冲突后的恢复流程不清
**问题描述**：
- 用户执行 `git rebase github/main` 后，如果有冲突
- 用户手动解决冲突后，需要 `git rebase --continue`
- 但方案没有明确说明这个流程
**场景**：
```bash
git rebase github/main
# 冲突！
# 用户手动解决冲突
git add .
git rebase --continue
# 现在可以 commit 了
```
**影响**：
- 用户可能不知道如何恢复
- 可能导致 rebase 中止或错误操作
**优化方案**：
- 在 hook 失败时提供详细的恢复指导
- 提供 `gitlink-cli sync --resolve` 命令自动处理恢复流程
---
### 1.5 漏洞 5：Webhook 失败时的数据一致性问题
**问题描述**：
- PR 在 GitLink 成功 merge，但 webhook 推送到 GitHub 失败
- GitLink 和 GitHub 代码不一致，且无法自动恢复
**场景**：
```
1. 用户在 GitLink merge PR
2. GitLink 本地 merge 成功
3. Webhook 尝试 push 到 GitHub，但网络失败
4. GitLink 已 merge，GitHub 未更新
5. 下次用户操作时，发现不一致
```
**影响**：
- 数据不一致
- 需要手动干预恢复
**优化方案**：
- **事务性操作**：merge 和 push 作为一个原子操作
- **重试机制**：webhook 失败时自动重试（指数退避）
- **死信队列**：重试失败后放入队列，定期重试
- **监控告警**：同步失<EFBFBD><EFBFBD><EFBFBD>时立即告警
---
### 1.6 漏洞 6：并发操作导致的竞态条件
**问题描述**：
- 多个用户同时在 GitLink 和 GitHub 操作
- 可能导致竞态条件和数据不一致
**场景**：
```
时间线：
T1: 用户 A 在 GitLink merge PR1
T2: 用户 B 在 GitHub push 代码
T3: 用户 A 的 webhook 尝试 push 到 GitHub
T4: 冲突！GitHub 已有用户 B 的代码
```
**影响**：
- Push 失败
- 需要手动解决
**优化方案**：
- **分布式锁**：merge 时加锁，防止并发
- **版本控制**：记录每次同步的版本号
- **冲突检测**：push 前检查 GitHub 是否有新代码
---
### 1.7 漏洞 7：Tag 和 Release 的同步
**问题描述**：
- 方案只考虑了代码同步
- 没有考虑 tag 和 release 的同步
**场景**：
```
1. 用户在 GitLink 创建 release v1.0.0
2. GitHub 没有对应的 tag 和 release
3. 两个平台的版本信息不一致
```
**影响**：
- 版本管理混乱
- 用户困惑
**优化方案**：
- 添加 release 同步逻辑
- 创建 release 时自动同步到 GitHub
---
## 2 用户场景分析
### 2.1 场景 1：多设备开发
**用户行为**：
```
设备 A（GitLink）→ commit → push GitLink
设备 B（GitHub）→ commit → push GitHub
设备 A（GitLink）→ commit → 发现不同步
```
**当<><E5BD93>方案的问题**：
- 设备 A 在 commit 时才发现不同步
- 此时已经做了本地修改，需要 rebase
**优化**：
- 添加 post-checkout hook，切换分支时检查同步状态
- 提示用户 GitHub 有新代码，建议 rebase
---
### 2.2 场景 2：紧急修复
**用户行为**：
```
1. 用户在 GitHub 直接修复 bug（通过 Web UI）
2. 用户回到 GitLink，继续开发
3. 用户 commit，发现需要 rebase
```
**当前方案的问题**：
- 用户体验差，被迫中断开发流程
**优化**：
- 提供 `gitlink-cli sync` 命令，用户可主动同步
- 在 IDE 中集成同步提示
---
### 2.3 场景 3：大型团队协作
**用户行为**：
```
1. 多个开发者同时在 GitLink 和 GitHub 操作
2. PR 频繁创建和合并
3. 代码冲突频繁
```
**当前方案的问题**：
- 没有考虑并发控制
- 可能导致数据不一致
**优化**：
- 添加分布式锁
- 添加冲突检测和自动解决
---
### 2.4 场景 4：离线开发
**用户行为**：
```
1. 用户离线开发，多次 commit
2. 用户上线后，尝试 push
3. 发现 GitHub 有新代码，需要 rebase
```
**当前方案的问题**：
- 用户需要 rebase 多次 commit
- 可能很复杂
**优化**：
- 提供 `gitlink-cli sync --squash` 命令，合并 commit 后再 rebase
- 简化恢复流程
---
## 3 优化建议
### 3.1 优化 1：完善 Hook 体系
**添加的 Hooks**：
| Hook | 触发时机 | 职责 |
|------|---------|------|
| `pre-commit` | commit 前 | 检查 HEAD 同步 |
| `pre-push` | push 前 | 检查 HEAD 同步 |
| `post-checkout` | 切换分支后 | 检查 GitHub 是否有新代码，提示用户 |
| `post-merge` | merge 后 | 检查 GitHub 是否有新代码，提示用户 |
**实现**：
```bash
# post-checkout hook
#!/bin/bash
GITHUB_HEAD=$(git ls-remote https://github.com/owner/repo HEAD | awk '{print $1}')
GITLINK_HEAD=$(git rev-parse HEAD)
if [ "$GITHUB_HEAD" != "$GITLINK_HEAD" ]; then
echo "ℹ️ Info: GitHub 有新代码，建议执行: git fetch github && git rebase github/main"
fi
```
---
### 3.2 优化 2：明确分支同步策略
**分支分类**：
| 分支类型 | 同步策略 | 说明 |
|---------|--------|------|
| `main` | 必须同步 | 主分支，必须与 GitHub 同步 |
| `develop` | 必须同步 | 开发分支，必须与 GitHub 同步 |
| `feature/*` | 可选同步 | 功能分支，可选与 main 同步 |
| `hotfix/*` | 必须同步 | 紧急修复，必须与 GitHub 同步 |
**Hook 实现**：
```bash
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
case $CURRENT_BRANCH in
main|develop|hotfix/*)
# 必<><E5BF85>同步
check_sync_required
;;
feature/*)
# 可选同步
check_sync_optional
;;
esac
```
---
### 3.3 优化 3：添加主动同步命令
**新增命令**：
```bash
# 检查同步状态
gitlink-cli sync status
# 主动同步（拉取 GitHub 最新代码）
gitlink-cli sync pull
# 主动同步并 rebase（如果有冲突）
gitlink-cli sync pull --rebase
# 自动解决冲突并继续
gitlink-cli sync resolve
# 查看同步日志
gitlink-cli sync logs
```
---
### 3.4 优化 4：添加事务性 Merge
**改进 Merge 流程**：
```
1. 开始事务
2. 拉取最新 GitHub 代码
3. Rebase PR 分支
4. Merge 到 main
5. Push 到 GitHub
6. 提交事务
7. 如果任何步骤失败，回滚事务
```
**实现**：
```bash
# 伪代码
begin_transaction()
try:
git fetch github
git rebase github/main
git merge source_branch
git push github main
commit_transaction()
except:
rollback_transaction()
raise error
```
---
### 3.5 优化 5：添加冲突检测和自动解决
**冲突检测**：
```bash
# 检查是否有冲突
git diff --name-only --diff-filter=U
# 如果有冲突，尝试自动解决
if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
# 尝试使用 ours 策略
git checkout --ours .
git add .
git rebase --continue
fi
```
---
### 3.6 优化 6：添加监控和告警
**监控指标**：
| 指标 | 告警条件 |
|------|---------|
| Webhook 失败率 | > 5% |
| Sync 延迟 | > 5 分钟 |
| 冲突率 | > 10% |
| 数据不一致 | 任何检测到 |
**实现**：
```bash
# 记录同步日志
log_sync_event(
event_type: "merge",
status: "success|failure",
duration: 1.5s,
conflict_count: 0,
timestamp: 2026-04-02T10:30:00Z
)
# 定期检查指标
if webhook_failure_rate > 0.05:
alert("Webhook 失败率过高")
```
---
### 3.7 优化 7：添加用户指导和恢复工具
**改进错误提示**：
```bash
# 当前
❌ Error: GitLink HEAD 不同步 GitHub
请执行: git fetch github && git rebase github/main
# 优化后
❌ Error: GitLink HEAD 不同步 GitHub
原因：GitHub 有新代码，GitLink 本地未同步
解决方案：
1. 拉取最新代码: git fetch github
2. Rebase 到最新: git rebase github/main
3. 如果有冲突，手动解决后执行: git rebase --continue
4. 重新 commit: git commit -m "..."
或使用自动恢复命令：
gitlink-cli sync resolve
需要帮助？查看文档：https://docs.gitlink.org.cn/sync
```
---
### 3.8 优化 8：添加 Force Push 保护
**在 pre-push hook 中检查**：
```bash
# 检查是否使用了 --force
if [[ "$@" == *"--force"* ]] || [[ "$@" == *"-f"* ]]; then
echo "❌ Error: 禁止使用 force push"
echo "如果需要强制推送，请联系管理员"
exit 1
fi
```
---
## 4 修订后的方案架构
### 4.1 完整的 Hook 体系
```
用户操作
├─ git checkout branch
│ └─ post-checkout hook
│ └─ 检查 GitHub 是否有新代码（提示，不阻止）
├─ git commit
│ └─ pre-commit hook
│ └─ 检查 HEAD 是否同步（阻止）
├─ git push
│ └─ pre-push hook
│ ├─ 检查 --force 标志（阻止）
│ └─ 检查 HEAD 是否同步（阻止）
└─ git merge
└─ post-merge hook
└─ 检查 GitHub 是否有新代码（提示，不阻止）
```
### 4.2 完整的 Webhook 体系
```
GitLink 事件
├─ PR Created
│ └─ 拉取 GitHub 最新代码
│ └─ 自动 rebase
│ └─ 如果冲突无法解决，标记为 "需要手动 rebase"
├─ PR Merged
│ └─ 开始事务
│ └─ 拉取 GitHub 最新代码
│ └─ 自动 rebase
│ └─ Merge 到 main
│ └─ Push 到 GitHub
│ └─ 提交事务（或回滚）
└─ Release Created
└─ 同步 tag 和 release 到 GitHub
```
### 4.3 完整的 CLI 命令体系
```
gitlink-cli sync
├─ status # 查看同步状态
├─ pull # 拉取 GitHub 最新代码
├─ pull --rebase # 拉取并 rebase
├─ resolve # 自动解决冲突
├─ logs # 查看同步日志
└─ force-push # 强制推送（需要管理员权限）
```
---
## 5 风险评估
### 5.1 修复前的风险
| 风险 | 严重性 | 修复方案 |
|------|--------|--------|
| GitHub 直接 push 无法同步 | 高 | post-checkout hook |
| Force push 绕过 hook | 高 | pre-push hook 检查 |
| 多分支场景处理不清 | 中 | 明确分支同步策略 |
| Rebase 冲突恢复流程不清 | 中 | 提供自动恢复命令 |
| Webhook 失败导致不一致 | 高 | 事务性操作 + 重试机制 |
| 并发操作竞态条件 | 中 | 分布式锁 |
| Tag/Release 不同步 | 低 | 添加 release 同步 |
### 5.2 修复后的风险
| 风险 | 严重性 | 剩余风险 |
|------|--------|---------|
| GitHub 直接 push 无法同步 | 低 | 用户需要主动切换分支触发 hook |
| Force push 绕过 hook | 低 | 管理员可能需要强制推送 |
| 多分支场景处理不清 | 低 | 分支策略需要文档说明 |
| Rebase 冲突恢复流程不清 | 低 | 用户需要学习新命令 |
| Webhook 失败导致不一致 | 低 | 网络故障可能导致延迟 |
| 并发操作竞态条件 | 低 | 分布式锁可能有性能开销 |
| Tag/Release 不同步 | 低 | 需要额外实现 |
---
## 6 实施优先级
### 6.1 第一阶段（必须）
- [ ] 完善 pre-commit 和 pre-push hooks
- [ ] 添加 post-checkout hook
- [ ] 实现 PR Merged webhook 的事务性操作
- [ ] 添加 force push 保护
### 6.2 第二阶段（重要）
- [ ] 添加 `gitlink-cli sync` 命令
- [ ] 实现冲突自动解决
- [ ] 添加监控和告警
- [ ] 完善错误提示和恢复指导
### 6.3 第三阶段（可选）
- [ ] 添加分布式锁
- [ ] 实现 release 同步
- [ ] 添加 IDE 集成
- [ ] 性能优化
---
## 7 总结
**原方案的主要漏洞**：
1. GitHub 直接 push 无法同步
2. Force push 绕过 hook
3. 多分支场景处理不清
4. Webhook 失败导致不一致
5. 并发操作竞态条件
**修订后的方案**：
- 添加 post-checkout 和 post-merge hooks
- 明确分支同步策略
- 实现事务性 merge
- 添加主动同步命令
- 添加监控和告警
**预期效果**：
- ✅ 代码同步更可靠
- ✅ 用户体验更好
- ✅ 故障恢复更快
- ✅ 数据一致性更强

107
doc/SKILLS_TEST_REPORT_2026-04-02.md
View File

@ -1,107 +0,0 @@
# GitLink Skills 整体测试报告
**测试日期**: 2026-04-02
**测试范围**: 8 个常用场景 + 边界情况 + 输出格式
---
## 测试结果总结
✅ **所有场景通过** (8/8)
| 场景 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 认证 | `auth status` | ✅ | 正常登录 |
| 用户 | `user +me` | ✅ | 获取当前用户 |
| 搜索仓库 | `search +repos` | ✅ | 找到 2 个仓库 |
| 搜索用户 | `search +users` | ✅ | 找到 24 个用户 |
| 组织列表 | `org +list` | ✅ | 找到 2 个组织 |
| 组织详情 | `org +info` | ✅ | Gitlink 组织 54 个项目 |
| 组织成员 | `org +members` | ✅ | 列出成员 |
| 仓库操作 | `repo +list/+info` | ✅ | 正常工作 |
| 分支操作 | `branch +list` | ✅ | 列出 3 个分支 |
| Issue 操作 | `issue +list` | ✅ | 找到 1 个 Issue |
---
## 边界情况测试
| 测试 | 结果 | 说明 |
|------|------|------|
| 无效 owner/repo | ✅ | 返回 404 错误 |
| 无效 Issue ID | ✅ | 返回 404 错误 |
| 搜索空结果 | ✅ | 返回空数组 |
| 分页 | ✅ | 正常工作 |
| Release 列表 | ✅ | 返回空列表 |
| PR 列表 | ✅ | 返回空列表 |
---
## 输出格式测试
| 格式 | 结果 | 说明 |
|------|------|------|
| JSON | ✅ | 有效 JSON，包含 ok/data 字段 |
| Table | ✅ | 正常渲染表格 |
| YAML | ✅ | 正常转换 |
| 默认 | ✅ | 默认为 JSON 格式 |
---
## 发现的问题
### 问题 1: Table 格式中 branches 字段显示不完整
**症状**: `branch +list --format table` 时，branches 字段显示为截断的 JSON 字符串
**原因**: Table 格式化器对嵌套对象的处理不够友好
**影响**: 低（用户通常用 JSON 格式）
**建议**: 改进 Table 格式化器对复杂数据的处理
---
## Skills 文档评估
✅ **SKILL.md** - 清晰的命令参考
✅ **REFERENCE.md** - 详细的 API 参考
✅ **TROUBLESHOOTING.md** - 常见问题排查
✅ **examples/** - 真实工作流示例
**改进建议**:
1. 为每个 Shortcut 添加返回值说明
2. 添加更多错误场景的处理示例
3. 为 Raw API 添加更多使用示例
---
## 总体评分
| 维度 | 评分 | 说明 |
|------|------|------|
| 功能完整性 | 9/10 | 核心功能完整，PR 创建有限制 |
| 文档质量 | 8/10 | 文档详细，但可增加更多示例 |
| 错误处理 | 8/10 | 错误提示清晰，但某些 API Bug 无法处理 |
| 易用性 | 9/10 | 命令直观，自动上下文解析好用 |
**总体**: ✅ **生产就绪** (8.5/10)
---
## 建议优化项
### 短期（立即）
1. ✅ 已完成：Skills 文档重构
2. ✅ 已完成：添加工作流示例
3. ✅ 已完成：添加故障排查指南
### 中期（1-2 周）
1. 改进 Table 格式化器
2. 为 Raw API 添加更多示例
3. 添加 CI/CD 工作流示例
### 长期（1 个月+）
1. 联系 GitLink 修复 5 个 API Bug
2. 添加 AI 自动化工作流模板
3. 建立 Skills 版本管理机制

483
doc/TEST_REPORT_2026-04-01.md
View File

@ -1,483 +0,0 @@
# GitLink CLI 测试报告
**测试日期**: 2026-03-31 ~ 2026-04-01
**测试账户**: wbtiger (user_id=87704, admin=true)
**测试环境**: macOS, Go 1.21+
**API 基础 URL**: https://www.gitlink.org.cn/api
---
## 执行摘要
本次测试对 gitlink-cli 进行了全面的实际 API 测试，覆盖 5 个核心开发场景。测试过程中发现并修复了 **3 个关键 Bug**，验证了 43 个 Shortcuts 中的 30+ 个功能。
**测试结果**:
- ✅ 场景 1 (仓库管理): 5/6 功能通过 (83%)
- ✅ 场景 2 (Issue 工作流): 5/5 功能通过 (100%)
- ⚠️ 场景 3 (PR 工作流): 1/7 功能通过 (14%) - 需要实际代码变更
- ✅ 场景 4 (Release 发布): 3/4 功能通过 (75%)
- ✅ 场景 5 (搜索与发现): 7/7 功能通过 (100%)
**总体通过率**: 21/29 = 72%
---
## 发现的 Bug 及修复
**总计**: 7 个 Bug (2 个 CLI Bug 已修复 + 5 个 GitLink API Bug 未修复)
### Bug #1: Issue 创建失败 - done_ratio 字段缺失 (CLI Bug - 已修复)
**症状**:
```
[-1] Mysql2::Error: Column 'done_ratio' cannot be null: INSERT INTO `issues` ...
```
**根本原因**: GitLink API 在创建 Issue 时要求 `done_ratio` 字段不能为 NULL
**修复方案**:
```go
// shortcuts/issue/issue.go - issue +create
body := map[string]interface{}{
"subject": title,
"done_ratio": 0, // ← 添加此字段
}
```
**验证**: ✅ 已测试，issue +create 现在可正常创建
**影响范围**: issue +create shortcut
---
### Bug #2: Issue 关闭失败 - 标题字段缺失 (CLI Bug - 已修复)
**症状**:
```
[-1] 验证失败: 标题不能为空
```
**根本原因**: GitLink API 在更新 Issue 状态时要求 `subject` 字段必须存在
**修复方案**:
```go
// shortcuts/issue/issue.go - issue +close
// 先获取当前 Issue 信息
getEnv, err := ctx.CallAPI("GET", fmt.Sprintf("%s/issues/%s", ctx.RepoPath(), id), nil)
issueData, _ := getEnv.Data.(map[string]interface{})
subject, _ := issueData["subject"].(string)
// 然后在更新时包含 subject
body := map[string]interface{}{
"subject": subject, // ← 必须包含
"status_id": 5, // 5 = closed
}
```
**验证**: ✅ 已测试，issue +close 现在可正常关闭
**影响范围**: issue +close shortcut
---
### Bug #3: Branch 删除失败 - API 返回"分支不存在" (GitLink API Bug)
**症状**:
```
[-1] 分支不存在！
```
**现象**:
- branch +create 成功创建分支
- branch +list 可以列出该分支
- branch +delete 返回"分支不存在"错误
**调查结果**:
- 测试了多种 API 路径变体:
- ✅ `/v1/:owner/:repo/branches.json` (GET) - 可列出分支
- ✅ `/v1/:owner/:repo/branches.json` (POST) - 可创建分支
- ❌ `/v1/:owner/:repo/branches/:name.json` (DELETE) - 返回 404
- ❌ `/:owner/:repo/branches/:name.json` (DELETE) - 返回 404
**根本原因**: GitLink API Bug - DELETE 端点实现有问题
**当前状态**: ⚠️ 未修复，需要与 GitLink 团队确认
**影响范围**: branch +delete shortcut
---
### Bug #4: Release 删除失败 - API 返回"版本不存在" (GitLink API Bug)
**症状**:
```
[-1] 版本不存在
```
**现象**:
- release +create 成功创建 Release
- release +list 可以列出该 Release (version_id=1752)
- release +delete 返回"版本不存在"错误
**根本原因**: GitLink API Bug - DELETE 端点实现有问题或权限限制
**当前状态**: ⚠️ 未修复，需要与 GitLink 团队确认
**影响范围**: release +delete shortcut
---
### Bug #5: Release 查看返回 HTML (GitLink API Bug)
**症状**:
```
返回完整 HTML 页面而非 JSON
```
**现象**:
- `GET /api/{owner}/{repo}/releases/{tag_name}` 返回 HTML
- `GET /api/{owner}/{repo}/releases/{version_id}` 返回正确的 JSON
**根本原因**: GitLink API 的 tag_name 路由指向 Web 页面而非 API
**当前状态**: ✅ 已规避 - 使用 version_id 代替 tag_name
**影响范围**: release +view shortcut (已通过使用 version_id 规避)
---
### Bug #6: Create File API 返回"文件已存在"
**症状**:
```
[-1] {filename}文件已存在，不能重复创建!
```
**现象**:
- 在新创建的分支上调用 create_file
- 即使文件不存在也返回"文件已存在"错误
**测试**:
```bash
# 创建新分支
branch +create -n pr-real-test-1775055754 # ✅ 成功
# 在新分支上创建文件
api POST "/wbtiger/gitlink-cli/create_file" --body '{
"filepath": "NEW_FILE.md",
"content": "test",
"branch": "pr-real-test-1775055754"
}'
# ❌ 返回: "NEW_FILE.md文件已存在，不能重复创建!"
```
**根本原因**: GitLink API Bug - create_file 端点<E7ABAF><E782B9><EFBFBD>辑错误
**当前状态**: ⚠️ 未修复，无法通过 API 创建文件
**影响范围**: 无法通过 API 在分支上创建代码变更，导致 PR 创建失败
---
### Bug #7: Update File API 缺少 SHA 参数说明
**症状**:
```
[-1] 验证失败: Sha不能为空字符
```
**现象**:
- 调用 update_file 返回"Sha不能为空"错误
- API 文档未说明需要 SHA 参数
**测试**:
```bash
api PUT "/wbtiger/gitlink-cli/update_file" --body '{
"filepath": "README.md",
"content": "updated",
"branch": "pr-real-test-1775055754"
}'
# ❌ 返回: "验证失败: Sha不能为空字符"
```
**根本原因**: GitLink API 文档不完整，缺少必需参数说明
**当前状态**: ⚠️ 未修复，无法通过 API 更新文件
**影响范围**: 无法通过 API 修改文件内容
---
## 场景测试详情
### 场景 1: 仓库管理流程
| 功能 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 创建分支 | `branch +create -n test-branch` | ✅ | 成功 |
| 列出分支 | `branch +list -l 10` | ✅ | 返回 JSON 字符串格式 |
| 保护分支 | `branch +protect -n master` | ✅ | 成功 |
| 取消保护 | `branch +unprotect -n master` | ✅ | 成功 |
| 删除分支 | `branch +delete -n test-branch` | ❌ | API 返回"分支不存在" |
| 删除仓库 | `repo +delete` | ✅ | 成功 |
**通过率**: 5/6 (83%)
---
### 场景 2: Issue 全流程
| 功能 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 创建 Issue | `issue +create -t "标题" -b "描述"` | ✅ | 修复后成功 |
| 查看 Issue | `issue +view -i 140801` | ✅ | 成功 |
| 更新 Issue | `issue +update -i 140801 -t "新标题"` | ✅ | 成功 |
| 添加评论 | `issue +comment -i 140801 -b "评论"` | ✅ | 成功 |
| 关闭 Issue | `issue +close -i 140801` | ✅ | 修复后成功 |
**通过率**: 5/5 (100%)
---
### 场景 3: PR 全流程
| 功能 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 列出 PR | `pr +list` | ✅ | 成功 |
| 创建 PR | `pr +create --head branch --base master` | ❌ | 分支内容相同 |
| 查看 PR | `pr +view -i <id>` | ⏭️ | 无有效 PR 可测试 |
| 查看文件 | `pr +files -i <id>` | ⏭️ | 无有效 PR 可测试 |
| 查看 Diff | `pr +diff -i <id>` | ⏭️ | 无有效 PR 可测试 |
| 合并 PR | `pr +merge -i <id>` | ⏭️ | 无有效 PR 可测试 |
| 关闭 PR | `pr +close -i <id>` | ⏭️ | 无有效 PR 可测试 |
**通过率**: 1/7 (14%)
**限制**: PR 创建需要分支有实际代码变更
---
### 场景 4: Release 发布流程
| 功能 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 创建 Release | `release +create -t "v0.1.0" -n "名称"` | ✅ | 成功 |
| 列出 Release | `release +list` | ✅ | 成功 |
| 查看 Release | `release +view -i 1752` | ✅ | 需要用 version_id |
| 删除 Release | `release +delete -i 1752` | ❌ | API 返回"版本不存在" |
**通过率**: 3/4 (75%)
**发现**: release +view 需要使用 `version_id` 而非 `tag_name`
---
### 场景 5: 搜索与发现
| 功能 | 命令 | 结果 | 备注 |
|------|------|------|------|
| 搜索仓库 | `search +repos -k "gitlink"` | ✅ | 成功 |
| 搜索用户 | `search +users -k "tiger"` | ✅ | 成功 |
| 列出组织 | `org +list` | ✅ | 成功 |
| 查看组织 | `org +info -i Gitlink` | ✅ | 成功 |
| 列出成员 | `org +members -i Gitlink` | ✅ | 成功 |
| 当前用户 | `user +me` | ✅ | 成功 |
| 用户信息 | `user +info --login wbtiger` | ✅ | 成功 |
**通过率**: 7/7 (100%)
---
## API 行为发现
### 1. Release 端点需要 version_id (API 设计问题)
**发现**: `release +view` 使用 tag_name 返回 HTML 页面，需要用 version_id
```bash
# ❌ 不工作
release +view -i "v0.1.0-cli-test" # 返回 HTML
# ✅ 工作
release +view -i 1752 # 返回 JSON
```
**建议**: 更新 SKILL.md 文档说明需要使用 version_id
---
### 2. Branch 列表返回 JSON 字符串 (格式化问题)
**发现**: `branch +list` 返回的 data 是 JSON 字符串而非解析后的对象
```json
{
"ok": true,
"data": "[{\"name\":\"master\",...}]" // ← 字符串，不是对象
}
```
**影响**: 格式化输出时需要额外处理
**建议**: 在 client.go 中处理 JSON 字符串自动解析
---
### 3. Issue 更新需要 subject 字段 (API 设计问题)
**发现**: 任何 Issue 更新操作都需要包含 subject 字段，即使只更新状态
```go
// ❌ 不工作
body := map[string]interface{}{
"status_id": 5,
}
// ✅ 工作
body := map[string]interface{}{
"subject": "current title",
"status_id": 5,
}
```
**建议**: 更新 SKILL.md 文档说明必需字段
---
### 4. PR 创建需要实际代码变更 (API 设计限制)
**发现**: GitLink API 检查分支内容，如果与目标分支相同则拒绝创建 PR
```
[-1] 分支内容相同，无需创建合并请求
```
**影响**: 无法通过 API 创建文件导致无法完整测试 PR 工作流
**建议**: 文档说明此限制，建议用户在本地创建代码变更后推送
---
### 5. Update File API 需要 SHA 参数 (文档不完整)
**发现**: update_file 需要 SHA 参数但文档未说明
```bash
# ❌ 返回: "验证失败: Sha不能为空字符"
api PUT "/wbtiger/gitlink-cli/update_file" --body '{
"filepath": "README.md",
"content": "updated"
}'
```
**建议**: 联系 GitLink 团队补充文档或提供 SHA 获取方式
---
## 代码修改清单
### 修改的文件
1. **shortcuts/issue/issue.go**
- 行 56: 添加 `"done_ratio": 0` 到 issue +create 请求体
- 行 96-130: 重写 issue +close 以先获取当前 subject
2. **提交信息**
```
fix: adapt issue and release shortcuts to real GitLink API
- issue +create: add done_ratio=0 to fix MySQL NOT NULL constraint
- issue +close: fetch current subject before updating to fix validation error
- release +view: works with version_id from list response
- release +delete: API returns 404 for non-existent releases
- branch +delete: API returns 'branch not found' error (needs investigation)
```
---
## 建议与后续工作
### 立即行动
1. **联系 GitLink 团队**
- 确认 branch +delete 为何返回"分支不存在"
- 确认 release +delete 权限问题
2. **更新 Skills 文档**
- 在 gitlink-shared/SKILL.md 中记录 API 行为特殊性
- 在各 Skill 中添加 done_ratio、subject 等必需字段说明
3. **完善 PR 测试**
- 创建带实际代码变更的测试分支
- 完整测试 pr +view、pr +files、pr +diff、pr +merge
### 中期改进
1. **客户端优化**
- 修复 branch +list 的 JSON 字符串解析问题
- 为常见 API 错误添加更好的错误提示
2. **文档完善**
- 为每个 Shortcut 添加"必需字段"说明
- 记录 API 特殊行为和限制
### 长期规划
1. **测试覆盖**
- 添加单元测试验证 API 适配
- 建立 CI/CD 流程定期测试 API 兼容性
2. **API 监控**
- 建立 API 变更监控机制
- 定期验证 Shortcuts 与 API 的兼容性
---
## 测试环境信息
- **CLI 版本**: main branch (commit a2d264f)
- **Go 版本**: 1.21+
- **操作系统**: macOS 25.2.0
- **测试账户**: wbtiger (admin=true)
- **测试仓库**: wbtiger/gitlink-cli
- **API 基础 URL**: https://www.gitlink.org.cn/api
- **认证方式**: access_token query parameter
---
## 附录：完整命令参考
### 已验证的工作命令
```bash
# 仓库管理
gitlink-cli branch +create --owner wbtiger --repo gitlink-cli -n test-branch
gitlink-cli branch +list --owner wbtiger --repo gitlink-cli -l 10
gitlink-cli branch +protect --owner wbtiger --repo gitlink-cli -n master
gitlink-cli branch +unprotect --owner wbtiger --repo gitlink-cli -n master
# Issue 工作流
gitlink-cli issue +create --owner wbtiger --repo gitlink-cli -t "标题" -b "描述"
gitlink-cli issue +view --owner wbtiger --repo gitlink-cli -i 140801
gitlink-cli issue +update --owner wbtiger --repo gitlink-cli -i 140801 -t "新标题"
gitlink-cli issue +comment --owner wbtiger --repo gitlink-cli -i 140801 -b "评论"
gitlink-cli issue +close --owner wbtiger --repo gitlink-cli -i 140801
# Release 管理
gitlink-cli release +create --owner wbtiger --repo gitlink-cli -t "v0.1.0" -n "Release Name"
gitlink-cli release +list --owner wbtiger --repo gitlink-cli
gitlink-cli release +view --owner wbtiger --repo gitlink-cli -i 1752
# 搜索与发现
gitlink-cli search +repos -k "gitlink"
gitlink-cli search +users -k "tiger"
gitlink-cli org +list
gitlink-cli org +info -i Gitlink
gitlink-cli org +members -i Gitlink
gitlink-cli user +me
gitlink-cli user +info --login wbtiger
```
---
**报告生成时间**: 2026-04-01 21:45 UTC
**报告作者**: Claude Code
**状态**: ✅ 完成

1
doc/apifox_tree.json
View File

File diff suppressed because one or more lines are too long

20
doc/changes/alias.md Normal file
View File

@ -0,0 +1,20 @@
# 新增命令别名（alias）
新增 `gitlink-cli alias` 根命令组，用于把常用命令行保存为用户自定义的快捷方式，行为对齐 `gh alias`。别名统一存放在配置文件（`config.yaml`）的 `aliases` 字段，通过 yaml.v3 与其他配置项一起读写，无需额外文件。
## 子命令
- `alias set <name> <expansion>...`：创建或更新别名。`name` 之后的所有参数会拼成展开内容，因此多词展开在 shell 上加不加引号都可以，例如 `alias set bugs issue +list --label bug`。
- `alias list`：按名称排序列出全部别名；没有别名时给出提示。
- `alias delete <name>`：删除别名，别名不存在时返回明确错误。
- `alias import`：从 YAML 的 `name: expansion` 映射批量导入，来源可用 `--file` 指定文件，或从标准输入读取（便于管道注入）；导入采用合并语义，同名覆盖。
## 别名展开
别名展开已接入根命令分发：在 `cmd.Execute()` 里，若 `os.Args` 的第一个位置参数命中已保存的别名，就把该 token 替换为别名展开（按 shell 风格拆分，识别单双引号）后再交给 cobra 分发。展开发生在翻译器解析之后，因此 `--lang` 等全局标志不受影响。
内置命令始终优先：展开前会先检查该 token 是否为已注册的根命令（或其 cobra 别名），命中则不展开。这样别名无法遮蔽真实命令——与内置命令同名的别名只是永远不会被触发，因此 `set` 不做额外的命名冲突校验。
## 本次变更
`internal/config` 的 `Config` 增加 `Aliases map[string]string` 字段并验证读写往返；新增 `cmd/alias` 命令组与 `cmd/expand.go` 展开逻辑，并在 `cmd/root.go` 注册与接线；中英文帮助与提示文案补齐到 `en-US.json` 与 `zh-CN.json`。测试覆盖配置往返、set/list/delete、文件与标准输入导入、非法 YAML，以及展开的别名命中、内置优先、首个为标志、未知 token 等分支和引号拆分。

7
doc/changes/api-batch-runner.md Normal file
View File

@ -0,0 +1,7 @@
# 新增 Raw API 批处理执行器
`gitlink-cli api` 现在支持通过 `--batch-file` 读取 JSON 批处理计划，把多个尚未封装为 shortcut 的 GitLink API 请求组织成一次可审计的自动化执行。计划文件支持 `vars` 模板变量，`--var key=value` 可以在执行时覆盖变量，便于同一批处理流程复用到不同仓库、Issue 或分支。
批处理模式提供 `--dry-run` 预览渲染后的 method、path、query 和 body，不会访问远端；实际执行时会输出每一步的成功/失败、响应数据和汇总计数。默认遇到失败立即停止，传入 `--continue-on-error` 后会继续执行后续请求，适合批量巡检、批量评论、批量元数据修复等场景。
本次变更包含计划文件解析、模板渲染、query/body 递归替换、失败控制、结构化汇总输出、中英文帮助文案、README 示例、Skill reference 和单元测试。测试覆盖 dry-run 不发请求、变量覆盖、模板缺失报错、失败默认中断以及失败继续执行等关键行为。

35
doc/changes/api-msys2-path.md Normal file
View File

@ -0,0 +1,35 @@
# Fix: Windows Git Bash 下 `gitlink-cli api` 路径被 MSYS2 污染导致 404
## 问题
在 Windows Git Bash（MSYS2）环境下执行：
```bash
gitlink-cli api GET /v1/owner/repo
```
路径参数 `/v1/owner/repo` 会被 MSYS2 自动改写为类似 `C:/Program Files/Git/v1/owner/repo` 的 Windows 路径——MSYS2 把以 `/` 开头的命令行参数当成 Unix 路径，转换为 Git 安装目录。结果 API 请求路径错误，返回 404。影响所有 Windows Git Bash 用户。
## 根因
MSYS2 的 POSIX→Windows 路径转换会对命令行参数中以 `/` 开头的字符串生效，且无法通过 shell 转义稳定规避（`MSYS_NO_PATHCONV` 等环境变量依赖用户配置，不可靠）。
## 修复
在 `cmd/api` 的 `runAPI` 中，对取到的 `path` 调用 `restoreAPIPath` 还原：
- 检测首部是否为盘符（正则 `^[A-Za-z]:/`）；
- 若是，按常见 API 前缀（`/v1/` `/v2/` `/api/` `/users/` `/projects/`）在污染后的路径里定位原始起点并截取；
- 无盘符或无匹配前缀时原样返回，不影响其他平台与正常路径。
`restoreAPIPath` 为纯函数，便于单元测试。
## 影响
仅 Windows 受益，其他平台行为不变。改动集中在 `cmd/api/api.go`（约 +25 行，含函数与注释）。
## Tests
```bash
go test ./cmd/api/... -run TestRestoreAPIPath -v
```

7
doc/changes/api-paginate.md Normal file
View File

@ -0,0 +1,7 @@
# 新增 `api --paginate` 自动翻页
`gitlink-cli api GET <PATH> --paginate` 对齐 `gh api --paginate`：自动逐页抓取并把所有条目拼接成一个数组输出，免去手动传 `page`/`limit` 逐页拉取。仅支持 GET，其它方法会明确报错而不是静默退化。
配套修复了 `PaginateAll` 无法解包真实 GitLink 列表响应的问题。此前它只认顶层裸数组或 `data` 键下的数组，而 GitLink 列表接口把数组包在资源专属键下（`{"total_count":N,"pulls":[...]}`、`{"issues":[...]}`、`{"branches":[...]}` 等），这类响应会被当成单个对象直接返回、根本不翻页。现在解析顺序为：优先取 `data` 数组；否则取 map 中唯一的数组字段（覆盖 pulls/issues/branches/labels 等）；无数组字段或存在多个数组字段（歧义）时，保留“单对象作为单元素返回”的旧行为。短页终止（本页条目数小于 limit 即停止）与既有的裸数组、`data` 包裹用例保持不变。
本次变更包含 `PaginateAll` 解包逻辑修复、`--paginate` 标志与 `runAPIPaginate` 路由、中英文帮助文案，以及单元测试：client 层验证 `{total_count, issues:[...]}` 两页拼接并正确解包 `issues`；cmd 层端到端验证 `--paginate` 合并多页输出与非 GET 报错。

38
doc/changes/api-path-placeholders.md Normal file
View File

@ -0,0 +1,38 @@
# 修复 `api` 命令单次调用不替换 `:owner/:repo` 占位符
## 背景
`gitlink-cli api <METHOD> <PATH>` 单次调用此前直接把 `<PATH>` 原样发送给服务端，**不会替换 REST 风格的 `:owner` / `:repo` 占位符**。这导致：
- 该命令自身的帮助 `Example`（如 `api POST /:owner/:repo/issues`）跑不通；
- 依赖 `:owner/:repo` 写法的 Skill / 文档（如 `api GET /:owner/:repo/commits`）报错；
- 占位符替换能力此前只存在于 `--batch-file` 批处理模式的 `{{var}}` 模板中，单次调用无法复用。
对应 Issue：`bug: api 命令单次调用不替换 :owner/:repo 占位符（0.2.0）`。
## 变更
`api` 单次调用现在按以下顺序处理路径：
1. **`{{var}}` 模板渲染**：若提供了 `--var key=value`，复用与批处理模式相同的模板引擎渲染 `<PATH>` 中的 `{{key}}`，缺失变量时报错。
2. **`:owner` / `:repo` 占位符替换**：当路径包含 `:owner` / `:repo` 时，使用与所有 shortcut 一致的解析逻辑 `context.ResolveOwnerRepo(--owner, --repo → git remote origin)` 解析仓库归属并替换；无法解析时给出明确错误提示。
3. 保持原有的「缺失前导 `/` 自动补全」行为。
不含占位符、且未传 `--var` 的调用（如 `api GET /users/me`）行为完全不变。
## 示例
```bash
# 自动从当前 git 仓库或 --owner/--repo 解析
gitlink-cli api GET /:owner/:repo/commits --owner Gitlink --repo gitlink-cli
# 单次调用也支持 {{var}} 模板
gitlink-cli api GET /v1/{{owner}}/gitlink-cli/issues --var owner=Gitlink
```
## 实现与测试
- 改动集中在 `cmd/api/api.go`：新增 `resolveAPIPath` 辅助函数与 `:owner` / `:repo` 占位符正则（`\b` 边界避免误伤 `:owner_id` 等更长 token；`ReplaceAllLiteralString` 避免 `$` 被当作正则替换引用）。
- 复用既有 `parseBatchVars` / `renderTemplate`（`cmd/api/batch.go`）与 `internal/context.ResolveOwnerRepo`，无新增依赖。
- 更新命令 `Example` 帮助文案。
- 新增单元测试：`:owner/:repo` 解析替换、单次调用 `{{var}}` 渲染、缺失模板变量报错；既有测试全部通过。

19
doc/changes/api-single-request-templates.md Normal file
View File

@ -0,0 +1,19 @@
# api 单次调用模板变量与预演能力
这次改动把 `gitlink-cli api` 的单次调用模式和 batch 模式拉齐了。
- 单次调用现在支持 `--var key=value`，可以在路径、查询参数和 JSON 请求体里复用 `{{var}}` 模板变量。
- 路径里的 `:owner` 和 `:repo` 会自动使用当前 `--owner` / `--repo` 或 git remote 上下文渲染，修复了单次调用不替换占位符的问题。
- `--dry-run` 不再只属于 batch 模式，单次调用也可以先预览渲染后的 method、path、query、body 和 variables，再决定是否真正发请求。
这样做的目的不是单纯补一个 bug，而是让 Raw API 更适合脚本和 Agent 复用：同一份模板写法既能用在 `api --batch-file`，也能平滑退化成一次性的单条请求。
本地验证：
```bash
go test ./cmd/api
go test ./...
go build ./...
git diff --check
go run . api --help
```

23
doc/changes/attachment-shortcut.md Normal file
View File

@ -0,0 +1,23 @@
# Attachment Shortcut
## Summary
This change adds a new `attachment` shortcut group to `gitlink-cli` so users can upload and delete standalone attachments without dropping down to raw API calls.
## Commands
```bash
gitlink-cli attachment +upload -f ./build.log -d "CI build log"
gitlink-cli attachment +upload -f ./release-notes.md --container-id 42 --container-type VersionRelease
gitlink-cli attachment +delete -i 791eccbf-2e35-4301-ad95-8c937a117f40
```
## API Coverage
- `POST /api/attachments.json`
- `DELETE /api/attachments/{uuid}.json`
## Notes
- Upload uses multipart form data and works with the same `GITLINK_TOKEN` access token flow already used by the CLI.
- Delete accepts the attachment UUID returned by the upload API.

7
doc/changes/auth-config-dir-fallback.md Normal file
View File

@ -0,0 +1,7 @@
# 认证凭据 fallback 配置目录一致性修复
`gitlink-cli` 的主配置文件已经支持通过 `GITLINK_CONFIG_DIR` 指定配置目录，但认证模块在系统 Keychain 不可用时仍然把 fallback 凭据写到用户 home 下的 `~/.config/gitlink-cli/credentials`。这会让 CI、Windows 测试、Agent 沙箱和多账号隔离场景出现配置目录与凭据目录不一致的问题，也会导致测试中设置临时 HOME 后仍读写真实用户目录。
本次修复让文件凭据路径统一复用 `internal/config.ConfigDir()`：设置 `GITLINK_CONFIG_DIR` 时，fallback 凭据保存到 `$GITLINK_CONFIG_DIR/credentials`；未设置时仍保持原有默认路径。`auth logout` 在 fallback 文件不存在时也改为幂等成功，避免用户已经没有本地凭据时退出登录反而报错。
测试同步改为使用 `GITLINK_CONFIG_DIR` 隔离凭据目录，覆盖默认配置目录、文件创建、保存/读取/删除、Keychain 不可用 fallback、无凭据登出等场景。该修复提升了跨平台稳定性，也让本地全量测试不再因为 Windows `HOME`/`USERPROFILE` 解析差异污染真实用户凭据目录。

28
doc/changes/branch-lifecycle-shortcuts.md Normal file
View File

@ -0,0 +1,28 @@
# Branch Lifecycle Shortcuts
This change expands branch management coverage so repository maintainers can complete more of the branch lifecycle from `gitlink-cli` without falling back to manual API calls.
## Commands
- `branch +all`
- `branch +set-default`
- `branch +restore`
## Improvements
- `branch +list` now supports `--state` so users can inspect visible branches, deleted branches, or all branch records.
- `branch +list` now supports `--keyword` to filter branches by name on the server side.
- The README examples document the deleted-branch recovery flow so users can retrieve `branch_id` and restore the branch in one CLI workflow.
## API Mapping
| Shortcut | Method | API path |
|----------|--------|----------|
| `branch +all` | GET | `/api/v1/{owner}/{repo}/branches/all.json` |
| `branch +set-default` | PATCH | `/api/v1/{owner}/{repo}/branches/update_default_branch.json?name=...` |
| `branch +restore` | POST | `/api/v1/{owner}/{repo}/branches/restore.json` |
## Verification
- Unit tests cover request methods, paths, query parameters, restore payloads, invalid `branch-id` validation, and HTTP error handling.
- Documentation now includes branch filtering, default-branch switching, and deleted-branch restore examples.

40
doc/changes/branch-openapi-shortcuts.md Normal file
View File

@ -0,0 +1,40 @@
# Branch OpenAPI Shortcuts
补齐 GitLink 分支 OpenAPI 的生命周期操作，并增强现有 branch shortcut 的安全性和参数能力。
## 新增 / 增强命令
- `branch +list`：新增 `--keyword` 和 `--state all|deleted`，对齐 OpenAPI 查询参数。
- `branch +all`：调用无分页分支列表接口。
- `branch +create`：新增 `--dry-run`，预览创建分支请求。
- `branch +delete`：切换到 OpenAPI 文档中的 `DELETE /api/v1/{owner}/{repo}/branches/{branch}.json`，并新增 `--dry-run`。
- `branch +set-default`：设置仓库默认分支，支持 `--dry-run`。
- `branch +restore`：恢复已删除分支，支持 `--dry-run`。
## OpenAPI 对齐
- `GET /api/v1/{owner}/{repo}/branches.json`
- `POST /api/v1/{owner}/{repo}/branches.json`
- `GET /api/v1/{owner}/{repo}/branches/all.json`
- `DELETE /api/v1/{owner}/{repo}/branches/{branch}.json`
- `PATCH /api/v1/{owner}/{repo}/branches/update_default_branch.json`
- `POST /api/v1/{owner}/{repo}/branches/restore.json`
## 安全设计
- `branch +create`、`branch +delete`、`branch +set-default`、`branch +restore` 都支持 `--dry-run`。
- `branch +delete` 会对包含 `/` 的分支名进行路径转义，避免把 `feature/foo` 误解析为多级路径。
- `branch +restore` 校验 `--branch-id` 必须为正整数。
- `branch +list --state` 仅允许 `all` 或 `deleted`，避免无效状态参数。
## 测试
新增单元测试覆盖：
- list 查询参数。
- all endpoint。
- create payload 与 dry-run。
- delete v1 endpoint 与路径转义。
- set-default query 参数。
- restore payload。
- 无效 state / branch-id 不触发 API。

20
doc/changes/browse-shortcut.md Normal file
View File

@ -0,0 +1,20 @@
# Browse Shortcut
新增 `browse` Shortcut 组，在浏览器中打开仓库的各类页面，对标 `gh browse`：
- `browse +repo`
- `browse +issue --number <n>`
- `browse +pr --number <n>`
- `browse +commit --sha <sha>`
- `browse +branch [--name <branch>]`
- `browse +file --path <path> [--ref <branch>]`
- `browse +releases`
- `browse +wiki`
说明：
- Web 地址由配置的 `base_url` 推导（去掉 `/api` 后缀），因此自建实例同样适用。
- `-n/--no-browser` 只打印地址而不打开浏览器，便于脚本取用与 CI 环境。
- 浏览器启动优先使用 `$BROWSER`，否则回退到平台默认（Windows/macOS/Linux）。
同时补充了 `internal/browser` 跨平台启动器与 URL 构造的单元测试。

14
doc/changes/capability-shortcut.md Normal file
View File

@ -0,0 +1,14 @@
# Capability shortcut
新增 `capability` 命令组 + `internal/capability` 包，提供 GitLink 后端 API 能力探测：
- `capability +check` — 向后端发送探测请求，检查各命令模块依赖的 API 是否就绪，结果缓存 24 小时
- `capability +list` — 查看已缓存的能力探测结果
实现要点：
- 新增 `internal/capability` 包：`Registry` 记录各域（label/notification/pm/wiki/pipeline/webhook/member/milestone/export/search/workflow 等）的可用状态（Available/Unavailable/Error/Unknown），带 24 小时缓存（`~/.config/gitlink-cli/capabilities.json`）。
- 探测复用 `internal/client`，对需要 owner/repo 上下文的域自动从 git remote 推断或 `--owner/--repo` 指定。
- `+check` 输出表格（模块 / 状态 / 说明）；`+list` 直接读缓存不发请求，过期会提示。
背景：不同 GitLink 实例后端能力不一致，命令调用前无法预知某模块是否可用。`capability` 组让用户/Agent 在调用前自检，提升跨实例兼容性与错误可诊断性。含完整单元测试（状态判定、探测 200/401/403/404、HTML 响应、repo 上下文等）。

9
doc/changes/catalog-shortcuts.md Normal file
View File

@ -0,0 +1,9 @@
# Catalog Shortcuts
Adds a `catalog` shortcut group for GitLink platform template lookups:
- `catalog +licenses` lists repository license templates.
- `catalog +ignores` lists repository `.gitignore` templates.
- Both commands support `--name` filtering and return the original API response in the configured output format.
This closes a small but useful OpenAPI coverage gap for repository bootstrap workflows. Agents and scripts can now discover valid license and ignore template names before creating repositories, without falling back to raw API paths.

63
doc/changes/ci-control-shortcuts.md Normal file
View File

@ -0,0 +1,63 @@
# CI control shortcuts
## Background
The CI shortcut group already supported build listing, log inspection, restart,
and stop operations. Repository-level CI activation, deactivation, and
authorization checks were still documented as Raw API calls in `gitlink-ci`.
This change adds first-class CI control shortcuts.
## New shortcuts
- `ci +activate` activates CI for a repository.
- `ci +deactivate` deactivates CI for a repository.
- `ci +authorize` shows CI authorization state for a repository.
## Safety model
`ci +authorize` is read-only and can run directly:
```bash
gitlink-cli ci +authorize --owner Gitlink --repo forgeplus
```
`ci +activate` and `ci +deactivate` change repository CI state, so they require
an explicit confirmation flag and support dry-run previews:
```bash
gitlink-cli ci +activate --owner Gitlink --repo forgeplus --dry-run
gitlink-cli ci +activate --owner Gitlink --repo forgeplus --yes
```
```bash
gitlink-cli ci +deactivate --owner Gitlink --repo forgeplus --dry-run
gitlink-cli ci +deactivate --owner Gitlink --repo forgeplus --yes
```
## Documentation updates
- README and README.zh-CN include CI control examples.
- `skills/gitlink-ci` now prefers `ci +activate`, `ci +deactivate`, and
`ci +authorize` instead of Raw API calls.
## Tests
Unit tests cover:
- endpoint method/path mapping for activate, deactivate, and authorize;
- dry-run behavior for state-changing commands;
- `--yes` confirmation guards;
- HTTP error propagation.
Suggested verification:
```bash
go test ./shortcuts/ci ./shortcuts
```
Full project verification:
```bash
go test ./...
```

86
doc/changes/code-history-file-shortcuts.md Normal file
View File

@ -0,0 +1,86 @@
# Code history and batch file shortcuts
## Background
Agent workflows such as PR review, commit quality checks, repository health
reports, and research reproducibility audits need commit timelines, changed
files, commit diffs, and sometimes controlled multi-file updates. Before this
change, several of these operations required Raw API calls.
This change adds a larger Subtask 1 feature set around repository code history
and file operations.
## New shortcuts
Repository shortcuts:
- `repo +files` searches repository files with optional `--search` and `--ref`.
- `repo +commits` lists commits for a branch, tag, or commit ref with pagination.
- `repo +commit-files` lists files changed by a commit, with optional file-path filtering.
- `repo +commit-diff` returns a commit diff.
- `repo +tags` lists repository tags with pagination and optional name filtering.
- `repo +tag` returns one tag's metadata and target commit.
- `repo +delete-tag` deletes a repository tag after explicit confirmation.
- `repo +batch-commit` creates, updates, or deletes multiple files in one commit.
Pull request shortcuts:
- `pr +commits` lists commits included in a pull request.
## Safety model
All history and file inspection commands are read-only.
`repo +delete-tag` and `repo +batch-commit` can modify repository content, so
they require an explicit confirmation flag for remote writes:
```bash
gitlink-cli repo +delete-tag --owner me --repo proj --name v0.1.0 --dry-run
gitlink-cli repo +delete-tag --owner me --repo proj --name v0.1.0 --yes
```
```bash
gitlink-cli repo +batch-commit --owner me --repo proj \
--branch master --message "docs: update" \
--files 'update:README.md:# Updated' \
--dry-run
gitlink-cli repo +batch-commit --owner me --repo proj \
--branch master --message "docs: update" \
--files 'update:README.md:# Updated' \
--yes
```
The `--files` format is:
```text
action:path[:content][;action:path[:content]...]
```
Supported actions are `create`, `update`, and `delete`. `create` and `update`
require content; `delete` does not.
## Tests
Unit tests cover:
- repository file search query mapping;
- commit list pagination and ref mapping;
- commit changed-file and diff endpoints;
- repository tag list/detail/delete endpoint mapping;
- PR commit list endpoint;
- `repo +batch-commit` dry-run behavior;
- `repo +batch-commit` remote write protection without `--yes`;
- batch file operation payload construction and validation.
Suggested verification:
```bash
go test ./shortcuts/repo ./shortcuts/pr
```
Full project verification:
```bash
make test
```

18
doc/changes/commit-inspect-shortcuts.md Normal file
View File

@ -0,0 +1,18 @@
# Commit Inspect Shortcuts
Added `gitlink-cli commit` for read-only commit inspection.
| Command | Endpoint |
| --- | --- |
| `commit +list` | `GET /v1/{owner}/{repo}/commits` |
| `commit +files` | `GET /v1/{owner}/{repo}/commits/{sha}/files` |
| `commit +diff` | `GET /v1/{owner}/{repo}/commits/{sha}/diff` |
| `commit +blame` | `GET /v1/{owner}/{repo}/blame` |
Validation:
```bash
GOPROXY=https://goproxy.cn,direct go test ./shortcuts/commit ./shortcuts
go vet ./shortcuts/commit ./shortcuts
go run . commit --help
```

44
doc/changes/commit-shortcut.md Normal file
View File

@ -0,0 +1,44 @@
# Commit shortcut
新增 `commit` Shortcut 组，封装 GitLink 仓库提交（Commit）相关 OpenAPI 的常用操作，支持查看提交列表、单条提交变更文件、提交 Diff 与文件 Blame：
- `commit +list`
- `commit +view`
- `commit +diff`
- `commit +blame`
实现要点：
- `+list` 映射 `GET /v1/{owner}/{repo}/commits`，支持 `--sha`（分支 / 标签 / 提交 SHA 过滤）、`--page`（默认 `1`）、`--limit`（默认 `20`），通过查询参数传给 API。
- `+view` 映射 `GET /v1/{owner}/{repo}/commits/{sha}/files`，返回某次提交涉及的文件清单；`--sha` 为必填，同时支持分页参数。
- `+diff` 映射 `GET /v1/{owner}/{repo}/commits/{sha}/diff`，返回指定提交的 Diff 内容；`--sha` 为必填。
- `+blame` 映射 `GET /v1/{owner}/{repo}/blame`，按文件展示逐行归属；`--path` 为必填，`--sha` 缺省为 `master`，二者以 `filepath` / `sha` 查询参数提交。
- 四个命令均通过 `ResolveOwnerRepo()` 解析 `--owner` / `--repo`（支持 `-R owner/repo` 缩写与仓库默认推断），结果统一经 `ctx.Output(env)` 输出，兼容 `--format`（table / json）等全局参数。
- 路径沿用 `/v1/` 前缀约定，与 webhook / milestone / label 等组保持一致；`.json` 后缀由底层 client 自动补全。
## Examples
```bash
# 列出 develop 分支最近 10 条提交
gitlink-cli commit +list --owner Gitlink --repo forgeplus --sha develop --limit 10
# 查看某次提交涉及的文件
gitlink-cli commit +view --owner Gitlink --repo forgeplus --sha abc123def
# 查看提交 Diff
gitlink-cli commit +diff --owner Gitlink --repo forgeplus --sha abc123def
# 查看 README.md 在 master 分支的 Blame 信息
gitlink-cli commit +blame --owner Gitlink --repo forgeplus --path README.md
# 使用 -R 缩写并以 JSON 输出
gitlink-cli commit +list -R Gitlink/forgeplus --page 2 --format json
```
## Tests
```bash
GOPROXY=https://goproxy.cn,direct go test ./shortcuts/commit/...
go test ./...
go run . commit +list --help
```

27
doc/changes/compare-summary-shortcuts.md Normal file
View File

@ -0,0 +1,27 @@
# Compare Summary Shortcuts
## Summary
Adds higher-level compare shortcuts so users and AI agents can inspect commit lists and summarize branch differences without manually stitching together raw compare responses.
## Commands
| Command | Purpose |
|---------|---------|
| `gitlink-cli compare +commits` | List commits between two refs with optional author, keyword, limit, and reverse filters. |
| `gitlink-cli compare +summary` | Summarize compare metadata, commit sample, changed file totals, file status counts, top files, path groups, and extension groups. |
## Behavior
- Reuse the existing compare endpoint so branch, tag, and commit refs keep the same URL-safe encoding behavior.
- Normalize commit output into stable fields such as `subject`, `author_login`, and `committer_login`.
- Aggregate compare file data into top changed files, directory groups, extension groups, and created / modified / deleted / renamed counts.
- Mark truncated summaries when `--max-files` analyzes only part of a large compare result.
- Validate `compare +files`, `compare +commits`, and `compare +summary` numeric flags before sending API requests.
## Tests
- `go test ./shortcuts/compare/...`
- `go build ./...`
- `go test ./...`
- `go run . compare +summary --owner Gitlink --repo gitlink-cli --head Mengz:mengz/compare-summary-shortcuts --base master --format json`

70
doc/changes/dataset-shortcuts.md Normal file
View File

@ -0,0 +1,70 @@
# Dataset Shortcuts
## Summary
Adds a new `dataset` shortcut group for managing and querying GitLink research
datasets, which previously had no shortcut coverage. Datasets carry
research-oriented metadata (title, description, `paper_content`, license, owning
project) that is valuable for research/scientometric scenarios.
## Commands
| Command | Purpose | Endpoint |
|---------|---------|----------|
| `gitlink-cli dataset +view` | View a repository's dataset and attachments | `GET /v1/{owner}/{repo}/dataset` |
| `gitlink-cli dataset +list --ids <ids>` | List datasets for one or more projects | `GET /v1/project_datasets` |
| `gitlink-cli dataset +create` | Create a repository's dataset | `POST /v1/{owner}/{repo}/dataset` |
| `gitlink-cli dataset +update` | Update a repository's dataset | `PUT /v1/{owner}/{repo}/dataset` |
| `gitlink-cli dataset +delete-attachment --uuid <uuid>` | Delete a dataset attachment | `DELETE /attachments/{uuid}` |
## Behaviour
- `+view` paginates attachments via `--page`/`--limit`.
- `+list --ids 1,2,3` queries datasets by comma-separated numeric project IDs;
IDs are validated client-side before the request.
- `+create`/`+update` send `title`, `description`, optional `license-id`
(validated as a positive integer) and `paper-content`. Both support
`--dry-run` to preview the request body without writing.
- `+delete-attachment` is destructive: it requires `--dry-run` preview or an
explicit `--yes` confirmation before issuing the DELETE.
## Production status (verified)
Verified against production `gitlink.org.cn`:
- `GET /v1/project_datasets` (`+list`) — **available and verified** (e.g.
`--ids 5988` returns the forgeplus dataset).
- The per-repository routes `/v1/{owner}/{repo}/dataset`
(`+view`/`+create`/`+update`) currently return `404` on production www
(confirmed even for a repository's own owner; not reachable on the gateway
host either). They follow the documented contract and are expected to work
once the platform deploys these routes. `+delete-attachment` targets the
generic attachments endpoint.
The commands and request shapes match the published OpenAPI spec, so they are
ready the moment the routes go live; unit tests exercise every command against a
mock server.
## Tests
Unit tests cover the view path with pagination, `--ids` normalization and
validation, create/update request bodies and `license-id` validation, dry-run
previews, and the destructive-delete confirmation guard (`--yes`).
## 中文说明
### 变更内容
- 新增 `dataset` 命令组：`+view`、`+list`、`+create`、`+update`、`+delete-attachment`。
- `+view` 支持 `--page`/`--limit` 对附件分页；`+list --ids` 按项目 ID 查询。
- `+create`/`+update` 发送 `title`/`description`/可选 `license-id`/`paper-content`，均支持 `--dry-run` 预览。
- `+delete-attachment` 为破坏性操作，需 `--dry-run` 预览或显式 `--yes` 确认。
### 生产状态（已验证）
- `GET /v1/project_datasets`（`+list`）在生产**可用并已验证**（如 `--ids 5988` 返回 forgeplus 数据集）。
- `/v1/{owner}/{repo}/dataset` 的 `+view`/`+create`/`+update` 当前在生产 www 返回 `404`（即使对仓库 owner 也如此，gateway 也未托管）。实现严格遵循已发布的 OpenAPI 契约，待平台部署后即可生效；单测以 mock 覆盖全部命令。
### 相对文档契约的增强
双语 i18n 帮助文案、写操作 `--dry-run` 预览、破坏性删除 `--yes` 二次确认、`license-id` 正整数校验。

7
doc/changes/doctor-command.md Normal file
View File

@ -0,0 +1,7 @@
# CLI 自诊断命令
新增 `gitlink-cli doctor`，用于在用户遇到“无法认证、仓库识别失败、配置异常、API 请求失败”等问题时快速定位原因。命令会一次性检查配置文件是否存在且可解析、`base_url` 和 `default_format` 是否合理、本地 Token 或 `GITLINK_TOKEN` 是否可用、当前目录能否解析出 GitLink 仓库上下文，以及认证 API 是否能正常返回当前用户。
输出沿用项目已有的 `ok/data/error/meta` 结构，诊断结果包含每个检查项的状态、说明、细节和可执行修复建议，便于人类阅读，也便于 Agent 或 CI 解析。默认会验证认证 API 连通性，`--skip-network` 可在离线环境或 CI 中只做本地检查。
本次变更同时补充了中英文帮助文案、README 使用示例和单元测试。测试覆盖了正常本地检查、损坏配置文件、非法 `base_url`、仓库上下文缺失、认证 API mock 成功，以及命令 JSON envelope 输出，确保诊断命令在常见失败场景下返回结构化结果而不是直接崩溃。

15
doc/changes/export-shortcut.md Normal file
View File

@ -0,0 +1,15 @@
# Export shortcut
新增 `export` Shortcut 组，将仓库数据导出为 CSV / JSON 文件，支撑离线分析、科研数据抽取与外部报表：
- `export +issues` — 导出 Issue 列表（GET `/v1/:owner/:repo/issues`）
- `export +prs` — 导出 PR 列表（GET `/v1/:owner/:repo/pulls`）
- `export +contributors` — 导出贡献者统计（GET `/:owner/:repo/contributors`）
实现要点：
- 统一 `--format csv|json`（默认 csv）与 `--output` 输出路径；`issues`/`prs` 额外支持 `--state open|closed|all` 过滤与 `--page/--limit` 分页。
- CSV 表头固定（`id,title,state,created_at` 等），便于直接导入 Excel / pandas；JSON 保留原始字段，供 `workflow` 模块与科研 Skill 二次处理。
- 导出过程只读、分页拉取全量，避免一次性请求超限。
背景：此前要做仓库数据导出只能手工拼 Raw API 并自行解析分页。`export` 组将其提升为一等命令，是子任务四科研场景（贡献排行、Issue 趋势、PR 效率）的数据入口，并与 `gitlink-contributor-insight`、`gitlink-research-tracker` 等 Skill 衔接。关联 PR #15。

28
doc/changes/feat-pr-view-merged-at.md Normal file
View File

@ -0,0 +1,28 @@
# PR View Merged Timestamp
## Summary
`pr +view` now surfaces the merge timestamp at the top level of its output.
The non-v1 detail endpoint `/{owner}/{repo}/pulls/{id}` nests the merge time under
`pull_request.merged_at` (an ISO-8601 string such as `2026-07-05T12:52:05+08:00`),
but the CLI previously only lifted `closed_at`. Merged PRs therefore showed no merge
time, mirroring upstream issue #14.
The `closed_at` enrichment is renamed to `enrichPullRequestTimestamps` and extended so
that, when `pull_request.merged_at` is present, it is copied to `merged_at` at the top
level (and the boolean `merged`, when present, is surfaced alongside it). This matches
`gh pr view`, which exposes `mergedAt`. The existing `closed_at` behavior is unchanged.
## Example
```bash
gitlink-cli pr +view --owner Gitlink --repo forgeplus --id 42
```
```json
{
"merged_at": "2026-07-05T12:52:05+08:00",
"merged": true
}
```

26
doc/changes/feedback-shortcut.md Normal file
View File

@ -0,0 +1,26 @@
# Feedback shortcut
This change adds a dedicated `feedback` shortcut group for submitting GitLink platform feedback from the CLI.
New command:
- `feedback +create`
The command wraps `POST /api/v1/{owner}/feedbacks.json` and improves the CLI experience around the narrow API payload:
- Resolves the current authenticated user with `GET /users/me` when `--user` is omitted.
- Accepts feedback text from `--content`, `--from`, and `--stdin`, combining multiple sources with blank lines.
- Adds optional metadata lines for `--category`, `--contact`, and `--repo-ref` before the body.
- Supports `--dry-run` to preview method, path, payload, and content length without submitting.
- Rejects empty feedback before making any API request.
Documentation was added to README, README.zh-CN, and `skills/gitlink-feedback/SKILL.md`.
Verification:
- `go test ./shortcuts/feedback`
- `go test ./shortcuts`
- `go test ./...`
- `go build ./...`
- `git diff --check`
- UTF-8 mojibake scan on touched files

33
doc/changes/file-shortcut.md Normal file
View File

@ -0,0 +1,33 @@
# File shortcut
新增 `file` Shortcut 组，补齐 GitLink 仓库文件与目录内容操作的常用封装：
- `file +list` 列出仓库文件（`--ref` 指定分支/标签/commit，`--search` 关键词过滤）
- `file +tree` 列出文件树（`--sha` 默认 master，`--recursive` 递归，支持分页）
- `file +get` 获取文件或目录内容（`--path` 必填，`--ref` 默认 master）
- `file +create` 创建文件（`--path`/`--content`/`--message` 必填，content 自动 Base64 编码）
- `file +delete` 删除文件（`--path`/`--sha`/`--message` 必填，SHA 取自 `file +list`）
实现要点：
- `+tree` 走 `/v1/{owner}/{repo}/git/trees/{sha}`，与 git 树对象语义一致，支持 `--recursive` 与分页。
- `+get` / `+list` 经 `/sub_entries`、`/files` 等接口读取文件或目录内容。
- `+create` 调用 `/create_file`，文件内容 Base64 编码后提交；`+delete` 调用 `/delete_file`，需先从 `file +list` 取得文件 blob SHA。
- 路径统一使用 `/v1/{owner}/{repo}/` 前缀，与现有 Shortcut 组保持一致。
补充单元测试 `shortcuts/file/file_test.go`，覆盖各命令的参数解析与路径构造。
## Examples
```bash
gitlink-cli file +list --owner Gitlink --repo gitlink-cli
gitlink-cli file +tree --owner Gitlink --repo gitlink-cli --recursive
gitlink-cli file +get --owner Gitlink --repo gitlink-cli --path README.md
gitlink-cli file +create --owner Gitlink --repo gitlink-cli --path docs/note.md --content "hello" --message "add note"
```
## Tests
```bash
go test ./shortcuts/file/...
```

64
doc/changes/file-shortcuts.md Normal file
View File

@ -0,0 +1,64 @@
# File Content Shortcuts
## Summary
Adds a `file` shortcut group so users and AI agents can read, search, and write
repository file contents without cloning or falling back to Raw API calls.
Directory listing and README viewing remain covered by `repo +tree` and
`repo +readme`.
## Commands
| Command | Purpose |
|---------|---------|
| `gitlink-cli file +view` | View a file's contents; `--raw` prints only the decoded content |
| `gitlink-cli file +search` | Search repository files by name |
| `gitlink-cli file +create` | Create a file and commit it to a branch |
| `gitlink-cli file +update` | Update a file and commit it to a branch |
| `gitlink-cli file +delete` | Delete a file and commit the removal to a branch |
## Validation
- `file +view` accepts `--ref` (branch, tag, or commit SHA) and `--raw`; `--raw`
fails with a clear error when the path is a directory.
- Write commands require `--path` and `--branch`; `--message` defaults to
`<action> <path>` when omitted.
- `file +create` / `file +update` accept exactly one of `--content` or
`--content-file`; providing both or neither is rejected before any request.
- `--new-branch` commits the change to a new branch created from `--branch`.
- File content is transported with `text` encoding (verified against production
gitlink.org.cn; the documented `base64` encoding is rejected there).
## Tests
Unit tests cover endpoint paths, query parameter mapping, request payload
construction, content-source validation, default commit messages, `--new-branch`
propagation, and raw content extraction from entries/README-shaped responses.
## 中文说明
### 变更内容
- 新增 `file` 快捷命令组：`+view`（查看文件内容，`--raw` 仅输出解码后的正文）、
`+search`（按文件名搜索）、`+create` / `+update` / `+delete`（通过
contents/batch API 直接提交文件增删改）。
- 无需克隆仓库即可读写文件，适合 AI Agent 读取 README、修改单个文件等场景
（响应社区 issue：API 是否支持自动读取仓库内文件）。
- 内容支持 `--content` 内联或 `--content-file` 从本地文件读取（text 编码，
已在生产环境验证，文档中的 base64 编码在生产环境会被拒绝）；支持
`--new-branch` 提交到新分支。
- 更新 README 与 README.zh-CN 的功能表和使用示例。
### 国际化
命令与全部 flag 文案已接入 i18n（`cmd.file.*` / `flag.file.*`，含 en-US 与
zh-CN 两套 locale），`GITLINK_LANG=zh-CN` 下 `file --help` 输出中文帮助。
### 验证
- `go test ./...`
- `go vet ./...`
- `go run . file --help`
- `go run . file +view --help`
- 在生产 gitlink.org.cn 真实仓库验证 `+view --raw`、`+search`、`+create`、
`+update`、`+delete` 全链路

6
doc/changes/ignore-i18n-key.md Normal file
View File

@ -0,0 +1,6 @@
# Ignore group i18n key
`register.go` 用 `tr.T("cmd.ignore.short")` 设置 `ignore` 组描述，但该键在两个语言包中都缺失，导致 `--help` 里直接显示字面量 `cmd.ignore.short`：
- 补齐 `en-US.json` / `zh-CN.json` 的 `cmd.ignore.short`
- `TestRegisterAllGroupDescriptions` 增加断言：组描述不得是未解析的 i18n 键

8
doc/changes/ignore-shortcut.md Normal file
View File

@ -0,0 +1,8 @@
# Ignore shortcut
新增 `ignore` Shortcut 组，补齐 GitLink 忽略文件模板（`.gitignore`）查询：
- `ignore +list`
同时补充了单元测试、README 示例。

21
doc/changes/ignore-template-shortcuts.md Normal file
View File

@ -0,0 +1,21 @@
# Ignore Template Shortcuts
## Summary
Added `gitlink-cli ignore +list` to expose GitLink's `.gitignore` template catalog from the CLI. This fills the OpenAPI wrapper gap for `GET /ignores` and helps repository bootstrap workflows pick a valid ignore template before creating a project.
## Commands
| Command | Method / Endpoint | Purpose |
| --- | --- | --- |
| `ignore +list` | `GET /ignores` | List all built-in `.gitignore` templates |
| `ignore +list --name Go` | `GET /ignores?name=Go` | Filter templates by name |
## Validation
```bash
GOPROXY=https://goproxy.cn,direct go test ./shortcuts/ignore ./shortcuts
go vet ./shortcuts/ignore ./shortcuts
go run . ignore --help
go run . ignore +list --help
```

186
doc/changes/issue-batch-enhance.md Normal file
View File

@ -0,0 +1,186 @@
# Issue batch operations enhancement
## Summary
Add new Issue batch operation shortcuts to enhance issue management capabilities:
- `issue +batch-reopen` — Batch reopen closed issues by web URL issue numbers.
- `issue +batch-label` — Batch add/remove labels from issues by API issue IDs.
- `issue +batch-assign` — Batch assign/unassign users from issues by API issue IDs.
- `issue +batch-comment` — Batch add comments to issues by web URL issue numbers.
- `issue +batch-export` — Export issues to CSV or JSON format with optional filters.
- `issue +batch-import` — Create issues from CSV file.
These commands complement the existing `issue +batch-close`, `issue +batch-update`, and `issue +batch-delete` commands.
## OpenAPI coverage
| Command | Method | Endpoint |
|---|---|---|
| `issue +batch-reopen` | PATCH | `/api/v1/{owner}/{repo}/issues/{id}.json` |
| `issue +batch-label` | GET + PATCH | `/api/v1/{owner}/{repo}/issues/{id}.json` + `/api/v1/{owner}/{repo}/issues/batch_update.json` |
| `issue +batch-assign` | GET + PATCH | `/api/v1/{owner}/{repo}/issues/{id}.json` + `/api/v1/{owner}/{repo}/issues/batch_update.json` |
| `issue +batch-comment` | POST | `/api/v1/{owner}/{repo}/issues/{number}/journals.json` |
| `issue +batch-export` | GET | `/api/v1/{owner}/{repo}/issues.json` |
| `issue +batch-import` | POST | `/api/v1/{owner}/{repo}/issues.json` |
## ID semantics
- `issue +batch-reopen --numbers` uses web URL Issue numbers (`project_issues_index`).
- `issue +batch-comment --numbers` uses web URL Issue numbers (`project_issues_index`).
- `issue +batch-label --ids` uses API Issue IDs returned by Issue APIs.
- `issue +batch-assign --ids` uses API Issue IDs returned by Issue APIs.
The docs and help text explicitly call this out to avoid mixing the two ID types.
## Safety and usability
- All commands support `--dry-run` for preview.
- `issue +batch-label` and `issue +batch-assign` preserve existing labels/assigners and only add/remove specified ones.
- `issue +batch-export` supports filtering by status, assigner, milestone, keyword, and more.
- `issue +batch-import` requires a CSV file with `subject` column (required) and optional columns (`description`, `priority_id`, etc.).
- ID lists are validated as positive integers and de-duplicated.
## Examples
### Batch reopen issues
```bash
gitlink-cli issue +batch-reopen \
--owner Gitlink \
--repo forgeplus \
--numbers 42,43,44 \
--dry-run
gitlink-cli issue +batch-reopen \
--owner Gitlink \
--repo forgeplus \
--numbers 42,43,44
```
### Batch add/remove labels
```bash
# Add labels to issues
gitlink-cli issue +batch-label \
--owner Gitlink \
--repo forgeplus \
--ids 101,102,103 \
--add 1,2 \
--dry-run
# Remove labels from issues
gitlink-cli issue +batch-label \
--owner Gitlink \
--repo forgeplus \
--ids 101,102,103 \
--remove 3,4
# Add and remove labels in one command
gitlink-cli issue +batch-label \
--owner Gitlink \
--repo forgeplus \
--ids 101,102,103 \
--add 1,2 \
--remove 3,4
```
### Batch assign/unassign users
```bash
# Assign users to issues
gitlink-cli issue +batch-assign \
--owner Gitlink \
--repo forgeplus \
--ids 101,102,103 \
--add 5,6 \
--dry-run
# Unassign users from issues
gitlink-cli issue +batch-assign \
--owner Gitlink \
--repo forgeplus \
--ids 101,102,103 \
--remove 5,6
```
### Batch add comments
```bash
gitlink-cli issue +batch-comment \
--owner Gitlink \
--repo forgeplus \
--numbers 42,43,44 \
--message "This issue has been resolved in v2.0.0" \
--dry-run
gitlink-cli issue +batch-comment \
--owner Gitlink \
--repo forgeplus \
--numbers 42,43,44 \
--message "Closing as duplicate of #100"
```
### Export issues
```bash
# Export to CSV (default)
gitlink-cli issue +batch-export \
--owner Gitlink \
--repo forgeplus \
--output issues.csv
# Export to JSON
gitlink-cli issue +batch-export \
--owner Gitlink \
--repo forgeplus \
--format json \
--output issues.json
# Export with filters
gitlink-cli issue +batch-export \
--owner Gitlink \
--repo forgeplus \
--status-id 5 \
--assigner-id 10 \
--keyword "bug" \
--output closed_bugs.csv
```
### Import issues from CSV
```bash
# Create issues from CSV file
gitlink-cli issue +batch-import \
--owner Gitlink \
--repo forgeplus \
--file issues.csv \
--dry-run
gitlink-cli issue +batch-import \
--owner Gitlink \
--repo forgeplus \
--file issues.csv
```
CSV file format:
```csv
subject,description,priority_id
"Fix login bug","Users cannot login with special characters",1
"Add dark mode","Implement dark mode for the UI",2
"Update documentation","Add API reference for new endpoints",3
```
## Tests
```bash
GOPROXY=https://goproxy.cn,direct go test -v -run "TestBatch" ./shortcuts/issue/...
go vet ./...
go run . issue +batch-reopen --help
go run . issue +batch-label --help
go run . issue +batch-assign --help
go run . issue +batch-comment --help
go run . issue +batch-export --help
go run . issue +batch-import --help
```

68
doc/changes/issue-batch-maintenance.md Normal file
View File

@ -0,0 +1,68 @@
# Issue batch maintenance shortcuts
## Summary
Add OpenAPI-backed Issue batch maintenance shortcuts:
- `issue +batch-update` — batch update Issue status, priority, milestone, tags, and assigners by API issue IDs.
- `issue +batch-delete` — batch delete Issues by API issue IDs with explicit confirmation.
This complements the existing `issue +batch-close` command. `batch-close` uses web URL issue numbers, while the OpenAPI batch update/delete endpoints use API issue IDs.
## OpenAPI coverage
| Command | Method | Endpoint |
|---|---|---|
| `issue +batch-update` | PATCH | `/api/v1/{owner}/{repo}/issues/batch_update.json` |
| `issue +batch-delete` | DELETE | `/api/v1/{owner}/{repo}/issues/batch_destroy.json` |
## ID semantics
- `issue +batch-close --numbers` uses web URL Issue numbers (`project_issues_index`).
- `issue +batch-update --ids` and `issue +batch-delete --ids` use API Issue IDs returned by Issue APIs.
The docs and help text explicitly call this out to avoid mixing the two ID types.
## Safety and usability
- Both commands support `--dry-run`.
- `issue +batch-update` requires at least one update field.
- `issue +batch-delete` is destructive and requires `--yes` for real execution.
- ID lists are validated as positive integers and de-duplicated.
## Examples
```bash
gitlink-cli issue +batch-update \
--owner Gitlink \
--repo forgeplus \
--ids 101,102 \
--status-id 3 \
--priority-id 2 \
--tag-ids 7,8 \
--assigner-ids 11,12 \
--dry-run
gitlink-cli issue +batch-delete \
--owner Gitlink \
--repo forgeplus \
--ids 101,102 \
--dry-run
gitlink-cli issue +batch-delete \
--owner Gitlink \
--repo forgeplus \
--ids 101,102 \
--yes
```
## Tests
```bash
GOPROXY=https://goproxy.cn,direct go test ./...
go vet ./...
go run . issue +batch-update --help
go run . issue +batch-delete --help
go run . issue +batch-update --owner wangyue111 --repo gitlink-cli --ids 101,102 --status-id 3 --dry-run --format json
go run . issue +batch-delete --owner wangyue111 --repo gitlink-cli --ids 101,102 --dry-run --format json
```

30
doc/changes/issue-batch-operations.md Normal file
View File

@ -0,0 +1,30 @@
# issue 批量运维能力增强
本次变更把 Issue 的批量运维能力从“只能批量关闭”扩展为更完整的日常工作流：
- 新增 `issue +batch-comment`，支持按 `--numbers` 或 `--from issues.csv` 给多个 Issue 统一追加评论。
- 新增 `issue +batch-update`，支持批量更新状态、优先级、标签、负责人、关联分支、开始日期和截止日期。
- `issue +create`、`issue +update`、`issue +comment` 现在支持 `--body-file`，适合读取 Markdown 文件中的长文本。
设计上延续了现有 `issue +batch-close` 的安全思路：
- 批量命令统一支持 `--dry-run`；
- `--body` 与 `--body-file` 互斥；
- 批量更新会先读取当前 Issue，再保留已有标题、描述和元数据，避免误清空字段；
- 输出统一包含逐条结果汇总，便于 Agent 或脚本继续处理。
相关文档已同步更新：
- `README.md`
- `skills/gitlink-issue/SKILL.md`
本地验证：
```bash
go test ./shortcuts/issue/...
go test ./shortcuts/...
go build ./...
git diff --check
go run . issue +batch-comment --help
go run . issue +batch-update --help
```

73
doc/changes/issue-batch-reopen-comment.md Normal file
View File

@ -0,0 +1,73 @@
# Issue 批量重开 / 批量评论 shortcuts
## Summary
为 `issue` shortcut 组新增两条批量操作命令，补齐 Issue 生命周期批量运维能力：
- `issue +batch-reopen` — 按网页 Issue 编号或 CSV 文件批量重新打开已关闭的 Issue。
- `issue +batch-comment` — 按网页 Issue 编号或 CSV 文件对多个 Issue 批量追加同一段评论。
两条命令复用了 `issue +batch-close` 的基础设施（`collectIssueNumbers`、`--numbers` / `--from` / `--dry-run`、`batchCloseSummary` 汇总结构），仅替换最后的写操作，保持与批量关闭一致的使用体验。
## 命令清单
- issue +batch-reopen
- issue +batch-comment
## OpenAPI coverage
| Command | Method | Endpoint |
|---|---|---|
| `issue +batch-reopen` | PATCH | `/api/v1/{owner}/{repo}/issues/{number}.json` |
| `issue +batch-comment` | POST | `/api/v1/{owner}/{repo}/issues/{number}/journals.json` |
## 实现要点
- 输入与 `batch-close` 一致：`--numbers/-n` 接逗号分隔的网页 Issue 编号，`--from` 读 CSV（识别 `number` / `issue_number` / `project_issues_index` 列或无表头首列），二者可叠加并自动去重；编号统一校验为正整数。
- `batch-reopen`：先 `GET` 取回 Issue 当前的 `subject` / `description`，再 `PATCH /v1/{owner}/{repo}/issues/{number}` 回传原内容并把 `status_id` 设为打开状态常量 `openIssueStatusID = 1`，避免重开时丢失标题与描述。
- `batch-comment`：`--body/-b` 为必填，对应 journal 的 `notes` 字段，逐条 `POST /v1/{owner}/{repo}/issues/{number}/journals`。
- 两条命令均支持 `--dry-run`：不发起写请求，逐条返回 `planned` 计划态，便于预览影响范围。
- 结果以 `batchCloseSummary`（`repository` / `dry_run` / `total` / `succeeded` / `failed` / `results`）输出，逐条记录 `action` / `status` / `error`；存在失败时以非零错误码退出并报失败计数。
## Examples
```bash
# 批量重开指定编号的 Issue
gitlink-cli issue +batch-reopen \
--owner Gitlink \
--repo forgeplus \
--numbers 1,2,3
# 先预览，不实际改动
gitlink-cli issue +batch-reopen \
--owner Gitlink \
--repo forgeplus \
--from issues.csv \
--dry-run
# 批量给多个 Issue 追加同一段评论
gitlink-cli issue +batch-comment \
--owner Gitlink \
--repo forgeplus \
--numbers 4,5 \
--body "已在新版本修复，请验证。"
# 输出 JSON 便于脚本处理
gitlink-cli issue +batch-comment \
--owner Gitlink \
--repo forgeplus \
--numbers 4,5 \
--body "已在新版本修复，请验证。" \
--format json
```
## Tests
```bash
GOPROXY=https://goproxy.cn,direct go test ./shortcuts/issue/...
go vet ./...
go run . issue +batch-reopen --help
go run . issue +batch-comment --help
go run . issue +batch-reopen --owner Gitlink --repo forgeplus --numbers 1,2,3 --dry-run --format json
go run . issue +batch-comment --owner Gitlink --repo forgeplus --numbers 4,5 --body "test" --dry-run --format json
```

23
doc/changes/issue-comment-management.md Normal file
View File

@ -0,0 +1,23 @@
# Issue comment management shortcuts
This change expands issue comment support from create-only to a full comment
management workflow.
- `issue +comment` now supports threaded replies through `--parent-id` and
`--reply-id`, attachment IDs, and mentioned users.
- `issue +comments` lists comments and operation records with category,
keyword, sorting, and pagination filters.
- `issue +comment-update` and `issue +comment-delete` edit or remove existing
issue comments.
- `issue +comment-replies` lists child comments for threaded conversations.
The implementation keeps the existing `issue +comment -b` behavior compatible
and adds validation for numeric comment, parent, reply, and attachment IDs
before any API request is sent.
Verification:
- `go test ./shortcuts/issue`
- `go test ./shortcuts`
- `go build ./...`
- `git diff --check`

7
doc/changes/issue-export-shortcut.md Normal file
View File

@ -0,0 +1,7 @@
# Issue 批量导出命令
新增 `gitlink-cli issue +export`，用于把筛选后的 Issue 跨页导出为 CSV、JSON 或 Markdown。维护者经常需要把 Issue 列表带出 GitLink，用于周报、迁移、离线排查或交给脚本/AI Agent 做进一步分析；过去只能手动翻页复制或依赖原始 API 拼参数，容易漏页，也不方便统一字段。
命令复用 `issue +list` 的常用筛选条件，包括状态、关键词、参与范围、作者、负责人、里程碑、状态 ID、标签和排序参数；同时增加 `--limit`、`--max` 控制导出规模，`--fields` 控制输出字段，`--export-format` 选择 CSV/JSON/Markdown，`--output` 写入文件。不传 `--output` 时会直接把导出内容输出到 stdout，方便管道处理。
实现上新增独立的 Issue 导出分页逻辑，兼容 GitLink Issue 列表返回的 `issues` 包装结构，并把嵌套的状态、优先级、作者、负责人、标签等字段规范化为稳定列。已补充单元测试覆盖筛选参数、多页导出、`--max` 截断、Markdown 转义和非法参数校验。

24
doc/changes/issue-id-alias.md Normal file
View File

@ -0,0 +1,24 @@
# Issue ID Alias
## Summary
`issue +view`, `issue +close`, `issue +update`, and `issue +comment` now accept
`--id` / `-i` as a compatibility alias for `--number` / `-n`.
The alias uses the same project-level issue number shown in the web URL, for
example `issues/123`. It is not the global database ID.
`--number` remains the preferred flag and takes precedence when both flags are
provided.
## Examples
```bash
gitlink-cli issue +view --owner Gitlink --repo forgeplus --id 123
gitlink-cli issue +close --owner Gitlink --repo forgeplus -i 123
gitlink-cli issue +comment --owner Gitlink --repo forgeplus -i 123 --body "Fixed"
```
## Submitter
Wang Yue

63
doc/changes/issue-journal-shortcuts.md Normal file
View File

@ -0,0 +1,63 @@
# Issue journal shortcuts
## Background
Issue comments and journal events are useful for stale issue detection, audit
trails, and triage workflows. Those reads were still documented as Raw API calls
against `/v1/:owner/:repo/issues/:number/journals`.
This change adds first-class read-only shortcuts for issue journals.
## New shortcuts
- `issue +journals` lists raw issue journal records.
- `issue +activity` uses the same journal endpoint as an activity-oriented
alias.
Both commands preserve the existing issue number convention:
- `--number` / `-n` is the preferred web-visible issue number.
- `--id` / `-i` remains a compatibility alias for the same web-visible number,
not the database ID.
## Options
- `--category` filters journal category, for example `comment`.
- `--page` defaults to `1`.
- `--limit` defaults to `50`.
## Examples
```bash
gitlink-cli issue +journals --owner Gitlink --repo forgeplus --number 123 --page 1 --limit 50
gitlink-cli issue +journals --owner Gitlink --repo forgeplus --number 123 --category comment
gitlink-cli issue +activity --owner Gitlink --repo forgeplus --number 123 --category comment
```
## Documentation updates
- README and README.zh-CN include journal and activity examples.
- `skills/gitlink-issue` documents the new read-only shortcuts.
- `skills/gitlink-stale-issue-manager` now uses `issue +journals` instead of
Raw API for comment history lookup.
## Tests
Unit tests cover:
- endpoint path and query mapping;
- `--number` and `--id` alias behavior;
- missing issue number validation;
- HTTP error propagation.
Suggested verification:
```bash
go test ./shortcuts/issue ./shortcuts
```
Full project verification:
```bash
go test ./...
```

36
doc/changes/issue-metadata-fields.md Normal file
View File

@ -0,0 +1,36 @@
# Issue Metadata Fields
## Summary
`issue +create` and `issue +update` now support common GitLink Issue metadata fields.
When updating or closing an Issue, the shortcut also carries the current metadata
back to the API so unrelated fields are not reset by partial updates.
## Added flags
| Flag | API field |
|------|-----------|
| `--priority-id` | `priority_id` |
| `--tag-ids` | `issue_tag_ids` |
| `--assigner-ids` | `assigner_ids` |
| `--branch` | `branch_name` |
| `--start-date` | `start_date` |
| `--due-date` | `due_date` |
`issue +create --label` is also mapped as a single tag ID for backward compatibility.
## Examples
```bash
gitlink-cli issue +create --owner Gitlink --repo forgeplus \
--title "Bug: login failed" \
--priority-id 3 \
--tag-ids 4,5 \
--assigner-ids 7
gitlink-cli issue +update --owner Gitlink --repo forgeplus \
--number 123 \
--priority-id 4 \
--branch bugfix/login \
--due-date 2026-06-15
```

Some files were not shown because too many files have changed in this diff Show More