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

docs: trim materials for official PR

This commit is contained in:
whzy 2026-05-22 12:37:34 +08:00 committed by wbtiger
parent 29dee2697e
commit b3f139801b
7 changed files with 0 additions and 780 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

212
WORK_CONTINUATION.md
View File

@ -1,212 +0,0 @@
# GitLink CLI Workflow Agent Work Continuation
## Current Goal
Implement the GitLink CLI Agent Workflow enhancement suite for `track1_2026GitLinkCli`.
Current implemented slice:
- `workflow +triage`
- `workflow +health`
- `workflow +pr-summary`
- `workflow +repo-report`
Planned next:
- `workflow +release-notes`
- `workflow +stale`
## Current Branch
- Branch: `codex/workflow-agent`
- Remote: `origin https://gitlink.org.cn/Gitlink/gitlink-cli.git`
- Repository path: `E:\GitLinkCLI-Competition\gitlink-cli`
- Local Go toolchain: `E:\GitLinkCLI-Competition\tools\go1.26.1\go`
## Completed Content
- Confirmed current workspace repository is `Gitlink/gitlink-cli`.
- Confirmed `workflow` command group did not previously exist in Go command registration.
- Confirmed `skills/gitlink-workflow/SKILL.md` exists as workflow guidance only.
- Read core command, shortcut, output, client, config, and test patterns.
- Created first workflow agent design draft at `docs/workflow-agent-design.md`.
- Workspace moved out of `C:\Users\zyc\OneDrive\Desktop\4c文档` to `E:\GitLinkCLI-Competition\gitlink-cli`.
- Added pure workflow DTOs under `shortcuts/workflow/types.go`.
- Added pure issue triage rules under `shortcuts/workflow/triage_rules.go`.
- Added pure repository health scoring under `shortcuts/workflow/health_score.go`.
- Added lightweight language messages under `shortcuts/workflow/messages.go`.
- Added unit tests for triage, health, messages, renderers, and local workflow command helpers.
- Installed Go 1.26.1 locally for Windows amd64 after verifying the machine is Intel x64.
- Added `workflow.Shortcuts()` with `+triage`, `+health`, and `+pr-summary`.
- Registered the `workflow` shortcut group in `shortcuts/register.go`.
- Added workflow-local JSON, table, and markdown renderers.
- Added local input support:
- `workflow +triage`: single issue flags or `--from` JSON file.
- `workflow +health`: explicit metric flags or `--from` JSON file.
- `workflow +pr-summary`: PR number fetch or `--from` JSON file.
- `workflow +repo-report`: aggregate health, issues, and PR list metadata or `--from` JSON file.
- Verified all three commands run locally without GitLink API write access.
- Added read-only workflow API fetch helpers and mock tests.
- Added command-level fetch-path smoke tests for `runTriage`, `runHealth`, and `runPRSummary`.
- Added README workflow command usage section.
- Added `docs/workflow-agent-test-report.md`.
- Added `docs/competition-solution.md`.
- Added `docs/pr-draft.md`.
- Added workflow testdata fixtures under `shortcuts/workflow/testdata/`.
- Expanded fetch-layer boundary coverage for empty responses, label and author normalization, error-in-body handling, alternative activity timestamps, release shapes, CI unavailability, and PR summary normalization.
- Added `workflow +repo-report` with local JSON input, read-only partial fetch aggregation,
report score, overall risk level, markdown/table/json rendering, and tests.
- Added competition submission materials:
- `docs/competition-submit.zh-CN.md`
- `docs/demo-script.md`
- `docs/final-submission-checklist.md`
- `docs/defense-qa.md`
- Updated PR draft, test report, competition solution, and continuation notes for final submission readiness.
## Current Go Toolchain Status
- `where go`: `E:\GitLinkCLI-Competition\tools\go1.26.1\go\bin\go.exe`
- `where gofmt`: `E:\GitLinkCLI-Competition\tools\go1.26.1\go\bin\gofmt.exe`
- `go version`: `go version go1.26.1 windows/amd64`
- Temporary PATH change: applied only in shell commands.
- GOPROXY used for tests: `https://goproxy.cn,direct`
- Go toolchain status: available.
- gofmt status: available.
## Current Test Status
- `gofmt` on `shortcuts/workflow/*.go`: passed.
- `go test ./shortcuts/workflow`: passed.
- `go test ./...`: passed.
- Smoke command passed:
```bash
go run . --format json workflow +triage \
--title "Token leaked in logs" \
--body "secret token leaked" \
--number 1 \
--labels security
```
- Smoke command passed:
```bash
go run . --format table workflow +health \
--repository owner/repo \
--open-issues 2 \
--open-prs 1 \
--recent-activity-known \
--recent-activity-days 3 \
--release-known \
--has-recent-release \
--has-readme \
--has-license \
--has-contributing \
--agent-readiness-known \
--agent-readiness-score 9
```
- Smoke command passed:
```bash
go run . --format json workflow +pr-summary \
--from shortcuts/workflow/testdata/pr_summary.json
```
- Smoke command passed:
```bash
go run . --format markdown workflow +repo-report \
--from shortcuts/workflow/testdata/repo_report.json
```
- Remote read-only smoke command passed:
```bash
go run . --format table workflow +triage \
--owner Gitlink \
--repo gitlink-cli \
--state open \
--limit 5
```
- Remote read-only smoke command passed:
```bash
go run . --format markdown --lang zh-CN workflow +health \
--owner Gitlink \
--repo gitlink-cli \
--stale-days 30
```
- Documentation examples now cover local-parameter, local-JSON-file, and read-only fetch usage.
## Recent Changed Files
- `README.md`
- `docs/competition-solution.md`
- `docs/pr-draft.md`
- `docs/competition-submit.zh-CN.md`
- `docs/demo-script.md`
- `docs/final-submission-checklist.md`
- `docs/defense-qa.md`
- `docs/workflow-agent-design.md`
- `docs/workflow-agent-test-report.md`
- `shortcuts/workflow/api_types.go`
- `shortcuts/workflow/messages.go`
- `shortcuts/workflow/render.go`
- `shortcuts/workflow/workflow.go`
- `shortcuts/workflow/workflow_test.go`
- `shortcuts/workflow/pr_summary.go`
- `shortcuts/workflow/pr_fetch.go`
- `shortcuts/workflow/pr_summary_test.go`
- `shortcuts/workflow/pr_fetch_test.go`
- `shortcuts/workflow/render_test.go`
- `shortcuts/workflow/testdata/pr_summary.json`
- `shortcuts/workflow/repo_report.go`
- `shortcuts/workflow/repo_report_fetch.go`
- `shortcuts/workflow/repo_report_test.go`
- `shortcuts/workflow/repo_report_fetch_test.go`
- `shortcuts/workflow/testdata/repo_report.json`
- `skills/gitlink-workflow/SKILL.md`
- `pr-test-file.txt` deleted
## Uncompleted Content
- `workflow +release-notes` is not implemented.
- `workflow +stale` is not implemented.
- Remote write operations remain intentionally deferred.
- GitLink official PR is not created yet.
- CI screenshot/result is not recorded yet.
- Demo video is not recorded yet.
- Final competition submission links are not filled in yet.
## Known Issues
- `codex status` is unavailable from the non-interactive shell: `stdin is not a terminal`.
- Quota reset time unavailable.
- Workflow commands support both local input and read-only GitLink fetch mode.
- Existing global help says default format is table, but shortcut runtime still defaults to json when `--format` is omitted.
- Existing output formatter supports `json`, `yaml`, and `table`; workflow-local renderers currently support `json`, `table`, and `markdown`.
- Workflow Skill examples use some older flag names such as `--id`, while current issue commands use `--number` for issues and PR commands use `--id`.
- API response shapes vary across endpoints and should be normalized behind workflow-specific fetch/parsing helpers.
- `README.zh-CN.md` currently shows encoding/garbling risk in the shell and was left untouched in this slice.
## Key Design Decisions
- No new dependency was added.
- `workflow` is a new shortcut group under `shortcuts/workflow`.
- JSON schemas use explicit workflow DTOs.
- Workflow renderers are local to the workflow package; global formatter was not changed.
- All remote-write behavior remains out of scope.
- `+triage` supports local single-issue flags, JSON file input, and read-only GitLink fetch mode.
- `+health` supports local metric flags, JSON file input, and read-only GitLink fetch mode.
- `+pr-summary` supports local JSON input and read-only PR metadata fetch mode.
- `+repo-report` supports local JSON input and read-only partial aggregation of health, issue, and PR list metadata.
- Treat unavailable future API metrics as `unknown` and include them in `scoring_notes`.
- Workflow-local renderers keep json/table/markdown output isolated from the global formatter.
## Next Minimal Executable Task
Create GitLink official PR, record CI result, and record demo video.
## How To Continue After Interruption
1. Open `WORK_CONTINUATION.md`.
2. Run `git status --short --branch`.
3. Use temporary PATH: `E:\GitLinkCLI-Competition\tools\go1.26.1\go\bin`.
4. Set temporary GOPROXY if dependency download fails: `https://goproxy.cn,direct`.
5. Run `go test ./shortcuts/workflow`.
6. Run `go test ./...`.
7. Create the GitLink official PR before adding more features.
8. Keep all new workflow commands read-only by default.
## Recommended Next Codex Instruction
Create GitLink official PR from branch `codex/workflow-agent`, then record PR URL, CI result, and demo video status in `docs/final-submission-checklist.md`.

186
docs/competition-solution.md
View File

@ -1,186 +0,0 @@
# GitLink CLI Agent Workflow Enhancement Suite
## 1. Background
GitLink CLI serves both human maintainers and AI Agents.
The competition focuses on intelligent open-source contribution workflows,
where structured analysis, stable output, and safe automation matter more than raw command count.
## 2. Problem
Open-source maintenance often suffers from:
- Issue backlog and delayed triage
- High PR review cost
- Repetitive release note preparation
- Lack of structured repository health evaluation
- AI Agents needing stable, machine-readable output
## 3. Solution
This project extends GitLink CLI with the **GitLink CLI Agent Workflow Enhancement Suite**.
Implemented now:
- `workflow +triage`
- `workflow +health`
- `workflow +pr-summary`
- `workflow +repo-report`
- read-only GitLink fetch layer for workflow triage and health
- read-only PR metadata, changed files, and commits fetch layer for PR summary
- partial read-only repository report aggregation for health, issues, and PR list metadata
- expanded fetch boundary tests for empty responses, label and author normalization,
error-in-body handling, alternative activity timestamps, release shapes, and CI unavailability
- local-first analysis with no LLM dependency
- stable Agent-facing JSON / table / markdown output
Planned next:
- `workflow +release-notes`
- `workflow +stale`
## 4. Technical Route
- Go + Cobra + existing shortcut architecture
- rule-based analysis
- stable DTOs
- `json` / `table` / `markdown` renderers
- `en` / `zh-CN` message mapping
- no LLM dependency
- local-first, dry-run-safe workflow design
## 5. Implemented Features
| Command | Status | Main Value |
|---|---|---|
| `workflow +triage` | Done | Issue classification, priority, missing information, and actions |
| `workflow +health` | Done | Repository health score, risk level, and recommendations |
| `workflow +pr-summary` | Done | PR risk, review focus, test suggestions, and merge checklist |
| `workflow +repo-report` | Done | Aggregated repository workflow report for maintainers and Agents |
| `workflow +release-notes` | Planned | Release note generation from PR titles and commits |
| `workflow +stale` | Planned | Stale issue and PR analysis |
### workflow +triage
- issue type detection
- priority scoring
- confidence scoring
- missing information detection
- risk flags
- recommended action
- suggested comment
- reasoning and matched rules
### workflow +health
- health score
- risk level
- metrics
- scoring notes
- recommendations
- unknown metric tolerance
### workflow +pr-summary
- change type detection
- risk level analysis
- review focus generation
- test suggestion generation
- merge checklist generation
- read-only fetch of PR metadata, changed files, and commits
### workflow +repo-report
- one-command repository workflow report
- health, issue triage, and PR summary aggregation
- report score and overall risk level
- partial report behavior when optional remote sections fail
- markdown output for competition and maintainer reports
- JSON output for Agent consumption
## 6. Innovation Points
- Agent-native structured output
- rule-based intelligence without external LLM dependency
- explainable workflow decisions
- safety-first local analysis
- bilingual command output
- extensible workflow command design
- competition-friendly incremental PR path
## 7. Testing and Verification
- Unit tests cover triage, health scoring, messages, rendering, and command helpers.
- Fetch-layer tests cover issue normalization, repository health probing,
and PR metadata/file/commit normalization with `httptest`.
- Boundary tests cover empty responses, label and author normalization,
error-in-body handling, alternative activity timestamps, release response shapes,
and CI unavailability.
- PR summary tests cover docs-only, workflow code, internal client,
security-sensitive, mixed-file, zh-CN, render, command, and fetch-failure cases.
- Repo report tests cover aggregation, scoring, JSON/table/markdown rendering,
command wiring, local JSON input, partial fetch behavior, and include flags.
- Local command examples were executed successfully.
- Full repository testing passed in the current environment.
- Automated tests use `httptest` and do not depend on real remote API availability.
## 8. Demonstration Plan
### Official repository
Use `Gitlink/gitlink-cli` as the reference repository:
1. `workflow +triage` with English table output
2. `workflow +triage` with security JSON output
3. `workflow +triage` with Chinese markdown output
4. `workflow +health` with table output
5. `workflow +health` with risky JSON output
6. `workflow +pr-summary` with markdown output
7. `workflow +repo-report` with markdown output for the full competition story
8. Explain how agents consume stable JSON
### Self-built test repository
Use a small demo repository to show:
- bug triage
- security triage
- docs triage
- healthy repo score
- risky repo score
- full repo report from `shortcuts/workflow/testdata/repo_report.json`
## 9. Roadmap
- Phase 1: local workflow prototype, completed
- Phase 2: API fetch and normalization, completed
- Phase 3: `pr-summary`, completed
- Phase 4: `repo-report`, completed
- Phase 5: `release-notes`, `stale`
## 10. PR Plan
- PR 1: workflow rule engine and local commands
- PR 2: documentation and tests
- PR 3: API fetch layer
- PR 4: `pr-summary`
- PR 5: `repo-report`
- PR 6: `release-notes` / `stale`
## 11. Evaluation Mapping
| Criterion | Evidence |
|---|---|
| 功能完整性 20% | Four implemented commands cover Issue triage, health scoring, PR summary, and repo report |
| 创新性 20% | Agent-native JSON, explainable rules, local-first safety model, repository workflow report |
| 实用价值 20% | Reduces maintainer triage/review overhead and creates copy-ready markdown reports |
| 文档与演示 20% | README, design doc, test report, competition write-up, demo script, defense Q&A |
| 成果落地 20% | Prepared for GitLink official PR, CI verification, and maintainer review iteration |
## 12. Landing Plan
- Push the implementation branch to the public repository.
- Create a GitLink official PR against `Gitlink/gitlink-cli`.
- Record CI result and PR URL in `docs/final-submission-checklist.md`.
- Respond to maintainer review over the expected 1-2 week review cycle.
- Keep `release-notes` and `stale` as follow-up work instead of expanding this PR further.

161
docs/competition-submit.zh-CN.md
View File

@ -1,161 +0,0 @@
# GitLink CLI Agent Workflow 增强套件参赛说明
## 1. 作品概述
作品名称：GitLink CLI Agent Workflow 增强套件。
本作品基于 `Gitlink/gitlink-cli` 开源仓库，面向开源项目维护者和 AI Agent
增加规则型、可解释、只读安全的协作分析工作流能力。目标不是替代维护者，
而是把 Issue 分诊、仓库健康度评估、PR 审阅摘要和仓库工作流报告变成
CLI 原生命令，降低维护前的信息整理成本。
当前已实现四个命令：
- `workflow +triage`
- `workflow +health`
- `workflow +pr-summary`
- `workflow +repo-report`
## 2. 对应赛题与场景
本作品主要对应子赛题一：`gitlink-cli` 功能增强 / 开源项目贡献。
对应工作流场景：
- Issue 自动分拣
- PR Review 辅助
- 仓库健康度评估
- 仓库工作流报告生成
## 3. 功能完整性说明
### workflow +triage
`workflow +triage` 对 Issue 做规则型智能分诊，支持本地参数、`--from`
JSON 文件和 GitLink 远端只读 fetch。输出包括 Issue 类型识别、优先级判断、
缺失信息检测、风险标记、建议操作、建议评论、规则命中原因，并支持
`json`、`table`、`markdown` 三种格式。
### workflow +health
`workflow +health` 生成仓库健康度评分，覆盖 Issue / PR backlog、最近活跃度、
Release、CI、文档、License、CONTRIBUTING 和 Agent readiness 等指标。
当远端 API 或某些指标不可用时，命令不会伪造结果，而是标记为 unknown
并在 scoring notes 中说明，保证 Agent 和维护者可以判断可信度。
### workflow +pr-summary
`workflow +pr-summary` 对单个 PR 生成审阅摘要，分析 PR 元数据、changed files
和 commits，输出 change type、risk level、review focus、test suggestions、
merge checklist 和 reasoning。该命令只读，不评论、不 approve、不 reject、
不 merge。
### workflow +repo-report
`workflow +repo-report` 聚合 health、triage 和 pr-summary 的能力，生成一份
仓库工作流报告。报告包含整体分数、风险等级、Issue 分布、PR 风险分布、
维护建议和判断依据，适合维护者、比赛材料和 AI Agent 使用。
## 4. 创新性说明
- Agent-native structured output：`json` 给 Agent，`markdown` 给维护者，`table` 给终端用户。
- Rule-based explainable intelligence：不依赖 LLM，所有判断都有规则依据。
- Safety-first read-only workflow：远端模式只读，不污染仓库状态。
- GitLink CLI 原生集成：基于 shortcuts 架构，不是外部脚本。
- Repository workflow report：一条命令聚合多个仓库治理维度。
- Bilingual support：支持 `en` / `zh-CN`。
## 5. 实用价值说明
| 问题 | 对应功能 | 价值 |
|---|---|---|
| 开源仓库 Issue 积压 | `workflow +triage` | 快速识别类型、优先级和缺失信息 |
| PR 审阅前理解成本高 | `workflow +pr-summary` | 生成审阅重点、测试建议和合并清单 |
| 仓库维护状态不清晰 | `workflow +health` | 给出健康度评分、风险等级和修复建议 |
| 维护者需要汇总报告 | `workflow +repo-report` | 一条命令生成可复制的仓库工作流报告 |
| AI Agent 需要稳定输出 | `json` DTO | 字段稳定，适合脚本和 Agent 消费 |
## 6. 技术路线
- Go + Cobra
- `gitlink-cli` shortcuts 架构
- GitLink API 只读 fetch
- API response normalization
- rule engine
- health scoring
- workflow-local renderer
- `json` / `table` / `markdown`
- `httptest` mock
- testdata reproducible examples
## 7. 安全边界
- 不调用 LLM API
- 不执行远端写操作
- 不自动评论
- 不自动打标签
- 不关闭 Issue
- 不 approve / reject / merge PR
- 不修改 `internal/output`
- 远端模式只读 fetch
- 所有分析在本地规则层完成
## 8. 测试与验证
测试命令：
```bash
gofmt -w shortcuts/workflow/*.go shortcuts/register.go
go test ./shortcuts/workflow
go test ./...
```
测试覆盖：
- triage rules
- health scoring
- pr-summary rules
- repo-report aggregation
- fetch normalization
- partial failure
- `json` / `table` / `markdown` render
- `--from` testdata
- command smoke tests
## 9. 可复现演示命令
稳定本地演示命令：
```bash
gitlink-cli workflow +triage --from shortcuts/workflow/testdata/issue_bug.json --format table
gitlink-cli workflow +health --from shortcuts/workflow/testdata/health_good.json --format markdown
gitlink-cli workflow +pr-summary --from shortcuts/workflow/testdata/pr_summary.json --format markdown
gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format markdown
```
远端只读演示命令：
```bash
gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open --limit 5 --format table
gitlink-cli workflow +health --owner Gitlink --repo gitlink-cli --stale-days 30 --format table
gitlink-cli workflow +pr-summary --owner Gitlink --repo gitlink-cli --number 1 --format markdown
gitlink-cli workflow +repo-report --owner Gitlink --repo gitlink-cli --format markdown
```
如果真实远端受认证、网络或 API 形态影响，可使用 `--from` testdata 稳定复现。
## 10. 成果落地计划
- 当前成果已在个人仓库完成。
- 下一步将提交 GitLink 官方主仓库 PR。
- 以 PR 已提交且通过 CI 作为成果落地基础。
- 争取在 Review 后根据维护者意见迭代。
- `release-notes` / `stale` 作为后续规划。
## 11. 后续规划
- `workflow +release-notes`
- `workflow +stale`
- 更完整的真实 GitLink API field normalization
- 官方 Skill 收录申请
- 更多真实项目验证

61
docs/defense-qa.md
View File

@ -1,61 +0,0 @@
# Defense Q&A
## 1. 作品解决了什么问题？
本作品解决开源项目维护中信息整理成本高的问题。维护者面对大量 Issue、PR 和仓库状态信号时，往往需要手动判断优先级、风险和下一步动作。本项目把这些判断沉淀为 GitLink CLI 原生命令，提供可复现、可解释、只读安全的工作流分析能力。
## 2. 为什么不使用 LLM？
本阶段不使用 LLM 是为了降低依赖风险和运行成本，并保证输出稳定可测。比赛目标是贡献可落地的 CLI 功能，规则型分析更适合进入基础工具链。未来如果需要接入 LLM，也可以在稳定 DTO 和安全边界之上扩展，而不是直接绑定外部模型。
## 3. 规则型分析如何体现智能化？
智能化不等于必须调用大模型。本项目通过关键词、权重评分、缺失信息检测、风险标记和健康度评分，把维护经验转化为自动化规则。每个结论都有 reasoning 和 matched rules，维护者可以理解判断来源，Agent 也可以消费结构化结果继续处理。
## 4. 如何保证不污染远端仓库？
所有 workflow 命令都遵守只读边界。远端模式只 fetch 数据，不评论、不打标签、不关闭 Issue，也不 approve、reject 或 merge PR。命令默认生成分析结果和建议，不执行写操作，因此不会改变真实仓库状态，适合在评审和演示中安全运行。
## 5. 与普通 CLI 命令相比有什么区别？
普通 CLI 命令主要完成单个 API 操作，例如查看 Issue 或 PR。本作品新增的是工作流级分析命令，会聚合输入、应用规则、生成风险等级、建议和报告。它不是简单包装 API，而是为维护者和 AI Agent 提供更高层的协作决策辅助。
## 6. 与人工维护 Issue / PR 相比有什么价值？
人工维护仍然是最终决策者，但本项目能先完成重复的信息整理工作。例如自动识别 bug、docs、security，指出缺失复现信息，给出 PR 审阅重点和测试建议。这样维护者可以把时间放在判断和修复上，而不是反复阅读和归类。
## 7. json/table/markdown 三种输出分别面向谁？
`json` 面向 AI Agent 和脚本，字段稳定，便于自动处理；`table` 面向终端用户，适合快速查看摘要；`markdown` 面向维护者、Issue/PR 评论草稿和比赛文档，便于复制传播。三种输出复用同一分析结果，减少重复实现。
## 8. repo-report 的评分如何计算？
`repo-report` 以 health score 为基础，结合高风险 Issue、缺失信息数量、高风险或 critical PR 等信号进行扣分，并限制在 0 到 100。风险等级按分数区间划分；如果出现 security P0 Issue 或 critical PR，会提升整体风险等级，保证安全问题优先暴露。
## 9. 如果 GitLink API 字段变化怎么办？
fetch 层使用 response normalization 处理多种字段形态，例如不同的 author、label、release、PR 字段别名。如果真实 API 继续变化，后续只需要在 workflow fetch 层补充映射和 httptest，不需要修改规则引擎或输出协议，维护成本较低。
## 10. 为什么成果可以落地到 gitlink-cli 主仓库？
实现遵循现有 shortcuts 架构，没有修改 `cmd/` 和 `internal/output`，也没有新增第三方依赖。功能边界清楚、默认只读、测试覆盖集中，适合以 PR 形式提交到主仓库。维护者可以分阶段 review，不需要一次接受复杂平台级改造。
## 11. 当前局限是什么？
当前局限主要是远端 API 形态仍需更多真实项目验证，`repo-report` 的远端 PR 部分使用 PR 列表元数据，深度 files/commits 分析仍通过单独的 `workflow +pr-summary` 完成。此外 `release-notes` 和 `stale` 仍是后续规划，尚未实现。
## 12. 后续规划是什么？
后续计划包括 `workflow +release-notes`、`workflow +stale`、更完整的真实 GitLink API 字段归一化、官方 Skill 收录申请和更多真实项目验证。所有后续功能仍会坚持只读优先、可测试、可解释，不会默认执行破坏性远端操作。
## 13. 如何验证功能正常？
可以运行 `gofmt -w shortcuts/workflow/*.go shortcuts/register.go`、`go test ./shortcuts/workflow` 和 `go test ./...`。演示时优先使用 `shortcuts/workflow/testdata/` 下的 JSON 文件，避免网络和认证影响。远端命令也只读，可作为 smoke 验证。
## 14. 如果 PR 没被合并，成果落地如何体现？
子赛题一鼓励提交官方 PR。即使短期未合并，只要 PR 已提交、CI 通过并进入维护者 Review，就已经具备成果落地基础。项目还提供个人仓库、完整测试、文档、演示脚本和后续迭代计划，便于根据维护者反馈继续推进。
## 15. 这个项目如何服务 AI Agent？
AI Agent 需要稳定、结构化、可解释的工具输出。本项目为 Issue、PR、健康度和仓库报告提供稳定 JSON DTO，并保留 reasoning、risk、recommendations 等字段。Agent 可以读取这些结果，生成后续任务、报告或维护计划，而不依赖不稳定的自然语言解析。

103
docs/demo-script.md
View File

@ -1,103 +0,0 @@
# Demo Script
## 0:00-0:20 项目背景
屏幕内容：
- 打开仓库 README 的 Workflow Agent Commands 小节。
- 展示 `workflow +triage`、`workflow +health`、`workflow +pr-summary`、`workflow +repo-report`。
旁白：
本项目为 GitLink CLI 增加面向维护者和 AI Agent 的规则型工作流增强套件。
它不依赖 LLM，不做远端写操作，通过 CLI 原生命令提供 Issue 分诊、健康度评分、
PR 审阅摘要和仓库工作流报告。
截图点位：
- README workflow 命令列表。
## 0:20-0:50 workflow +triage
演示命令：
```bash
gitlink-cli workflow +triage --from shortcuts/workflow/testdata/issue_bug.json --format table
```
旁白：
这个命令会对 Issue 做规则型分诊，自动识别 Issue 类型，判断优先级，
发现缺失信息，并给出建议操作。表格输出适合维护者在终端快速查看。
截图点位：
- table 输出中的 type、priority、missing、action。
## 0:50-1:20 workflow +health
演示命令：
```bash
gitlink-cli workflow +health --from shortcuts/workflow/testdata/health_good.json --format markdown
```
旁白：
健康度命令根据 Issue、PR、Release、CI、文档、License 和贡献指南等指标，
生成仓库健康度评分、风险等级和维护建议。Markdown 输出可直接复制到报告中。
截图点位：
- health score、risk level、recommendations。
## 1:20-1:50 workflow +pr-summary
演示命令：
```bash
gitlink-cli workflow +pr-summary --from shortcuts/workflow/testdata/pr_summary.json --format markdown
```
旁白：
PR 摘要命令会识别 PR 类型和风险等级，生成 review focus、test suggestions
和 merge checklist。它只读分析，不会评论、approve、reject 或 merge PR。
截图点位：
- Review Focus、Test Suggestions、Merge Checklist。
## 1:50-2:20 workflow +repo-report
演示命令：
```bash
gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format markdown
```
旁白：
仓库报告命令聚合 Issue、PR 和仓库健康度，生成一份完整的仓库工作流报告。
它适合维护者快速了解项目状态，也适合比赛展示项目的综合能力。
截图点位：
- Report score、Risk level、Issue Triage Summary、PR Review Summary。
## 2:20-2:40 JSON 输出给 Agent
演示命令：
```bash
gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report.json --format json
```
旁白：
同一个报告可以输出稳定 JSON 字段，供 AI Agent 和脚本消费。
这让 Agent 可以基于结构化结果继续做排序、摘要或生成后续任务。
截图点位：
- JSON 中的 `report_score`、`risk_level`、`issue_summary`、`pr_summary`。
## 2:40-3:00 安全边界与总结
屏幕内容：
- 展示参赛说明中的安全边界小节。
旁白：
整个 workflow-agent 套件不依赖 LLM，远端模式只读，不评论、不打标签、不关闭 Issue，
也不 approve、reject 或 merge PR。后续规划包括 `workflow +release-notes`
和 `workflow +stale`，但当前提交保持聚焦、可测试、可落地。
截图点位：
- 安全边界列表。

52
docs/final-submission-checklist.md
View File

@ -1,52 +0,0 @@
# Final Submission Checklist
## Repository Links
- GitHub repository: 待填写
- GitHub branch: 待填写
- GitLink fork: 待填写
- GitLink official PR: 待填写
- CI result: 待填写
- Competition submission: 待填写
## Core Files
- README.md
- README.zh-CN.md
- docs/competition-submit.zh-CN.md
- docs/workflow-agent-design.md
- docs/workflow-agent-test-report.md
- docs/competition-solution.md
- docs/demo-script.md
- docs/pr-draft.md
- skills/gitlink-workflow/SKILL.md
## Commands Implemented
- workflow +triage
- workflow +health
- workflow +pr-summary
- workflow +repo-report
## Test Commands
- gofmt -w shortcuts/workflow/*.go shortcuts/register.go
- go test ./shortcuts/workflow
- go test ./...
## Demo Assets
- demo video: 待填写
- screenshots: 待填写
- command output logs: 待填写
## Before Submission
- [ ] GitLink official PR created
- [ ] CI passed
- [ ] README examples verified
- [ ] demo video recorded
- [ ] competition platform form filled
- [ ] repository links submitted
- [ ] PR link submitted
- [ ] docs links submitted

5
docs/pr-draft.md
View File

@ -87,11 +87,6 @@ Coverage includes:
- `README.md`
- `docs/workflow-agent-design.md`
- `docs/workflow-agent-test-report.md`
- `docs/competition-solution.md`
- `docs/competition-submit.zh-CN.md`
- `docs/demo-script.md`
- `docs/final-submission-checklist.md`
- `docs/defense-qa.md`
- `skills/gitlink-workflow/SKILL.md`
## Known Limitations