docs: add competition submission materials
This commit is contained in:
parent
a904f48099
commit
2dc230430b
|
|
@ -54,6 +54,12 @@ Planned next:
|
|||
- 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
|
||||
|
||||
|
|
@ -126,6 +132,10 @@ Planned next:
|
|||
- `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`
|
||||
|
|
@ -152,6 +162,10 @@ Planned next:
|
|||
- `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
|
||||
|
||||
|
|
@ -180,7 +194,7 @@ Planned next:
|
|||
|
||||
## Next Minimal Executable Task
|
||||
|
||||
Design workflow +release-notes with read-only PR titles and commit messages; implement with httptest mock first; do not add LLM or write operations.
|
||||
Create GitLink official PR and record CI result.
|
||||
|
||||
## How To Continue After Interruption
|
||||
|
||||
|
|
@ -190,9 +204,9 @@ Design workflow +release-notes with read-only PR titles and commit messages; imp
|
|||
4. Set temporary GOPROXY if dependency download fails: `https://goproxy.cn,direct`.
|
||||
5. Run `go test ./shortcuts/workflow`.
|
||||
6. Run `go test ./...`.
|
||||
7. Start `workflow +release-notes` design only after confirming the existing workflow tests still pass.
|
||||
7. Create the GitLink official PR before adding more features.
|
||||
8. Keep all new workflow commands read-only by default.
|
||||
|
||||
## Recommended Next Codex Instruction
|
||||
|
||||
Design workflow +release-notes with read-only PR titles and commit messages; implement with httptest mock first; do not add LLM or write operations.
|
||||
Create GitLink official PR from branch `codex/workflow-agent`, then record PR URL and CI result in `docs/final-submission-checklist.md`.
|
||||
|
|
|
|||
|
|
@ -51,6 +51,15 @@ Planned next:
|
|||
|
||||
## 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
|
||||
|
|
@ -157,3 +166,21 @@ Use a small demo repository to show:
|
|||
- 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.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,161 @@
|
|||
# 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 收录申请
|
||||
- 更多真实项目验证
|
||||
|
|
@ -0,0 +1,61 @@
|
|||
# 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 可以读取这些结果，生成后续任务、报告或维护计划，而不依赖不稳定的自然语言解析。
|
||||
|
|
@ -0,0 +1,103 @@
|
|||
# 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`，但当前提交保持聚焦、可测试、可落地。
|
||||
|
||||
截图点位：
|
||||
- 安全边界列表。
|
||||
|
|
@ -0,0 +1,51 @@
|
|||
# Final Submission Checklist
|
||||
|
||||
## Repository Links
|
||||
|
||||
- GitHub repository:
|
||||
- GitHub branch:
|
||||
- GitLink fork:
|
||||
- GitLink official PR:
|
||||
- CI result:
|
||||
|
||||
## 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
|
||||
127
docs/pr-draft.md
127
docs/pr-draft.md
|
|
@ -1,68 +1,113 @@
|
|||
# PR Draft: Add workflow agent commands for issue triage, repository health, PR summaries, and repo reports
|
||||
# feat(workflow): add agent workflow commands for repository maintenance
|
||||
|
||||
## Summary
|
||||
|
||||
This PR adds `workflow +triage`, `workflow +health`, `workflow +pr-summary`,
|
||||
and `workflow +repo-report` with safe read-only analysis modes:
|
||||
This PR adds four read-only workflow commands for repository maintenance:
|
||||
|
||||
- local flags
|
||||
- local JSON input
|
||||
- read-only GitLink fetch mode
|
||||
- `workflow +triage`
|
||||
- `workflow +health`
|
||||
- `workflow +pr-summary`
|
||||
- `workflow +repo-report`
|
||||
|
||||
It also adds stable `json`, `table`, and `markdown` rendering for Agent consumption.
|
||||
The commands provide rule-based, explainable analysis with stable `json`, concise `table`,
|
||||
and copy-friendly `markdown` output.
|
||||
|
||||
## Motivation
|
||||
|
||||
- Help maintainers triage issues faster
|
||||
- Provide a structured repository health overview
|
||||
- Summarize pull requests with review focus, test suggestions, and merge checklist output
|
||||
- Generate a repository workflow report that aggregates health, issue triage, and PR signals
|
||||
- Give AI Agents stable machine-readable output
|
||||
- Keep the workflow local-first and safe by default
|
||||
- Avoid any dependency on external LLM APIs
|
||||
Open-source maintainers often spend time on repetitive information organization before
|
||||
making actual decisions:
|
||||
|
||||
- Issue triage cost
|
||||
- PR review cost
|
||||
- repository health visibility
|
||||
- Agent needs stable structured output
|
||||
|
||||
This PR adds workflow-level analysis on top of the existing GitLink CLI shortcut architecture
|
||||
without introducing LLM dependencies or remote write behavior.
|
||||
|
||||
## Changes
|
||||
|
||||
- New `shortcuts/workflow` rule engine and DTOs
|
||||
- Local command layer for `workflow +triage` and `workflow +health`
|
||||
- Local and remote command layer for `workflow +pr-summary`
|
||||
- Local and partial remote aggregation for `workflow +repo-report`
|
||||
- Workflow-local renderer for `json`, `table`, and `markdown`
|
||||
- Read-only GitLink fetch and normalization helpers
|
||||
- Unit tests for rules, fetch normalization, rendering, and command wiring
|
||||
- Competition and test documentation updates
|
||||
### `workflow +triage`
|
||||
|
||||
- Classifies issues by type
|
||||
- Scores priority and confidence
|
||||
- Detects missing bug-report information
|
||||
- Produces risk flags, recommended actions, suggested comments, and reasoning
|
||||
|
||||
### `workflow +health`
|
||||
|
||||
- Scores repository health
|
||||
- Covers issue/PR backlog, activity, release, CI, docs, license, contributing, and Agent readiness signals
|
||||
- Tolerates unknown metrics without failing the command
|
||||
|
||||
### `workflow +pr-summary`
|
||||
|
||||
- Summarizes PR metadata, changed files, and commits
|
||||
- Produces change type, risk level, review focus, test suggestions, merge checklist, and reasoning
|
||||
- Supports local JSON input and remote read-only PR fetch
|
||||
|
||||
### `workflow +repo-report`
|
||||
|
||||
- Aggregates health, issue triage, and PR summary signals
|
||||
- Produces a repository workflow report with score, risk level, recommendations, and reasoning
|
||||
- Supports partial read-only remote aggregation when optional sections are unavailable
|
||||
|
||||
## Safety
|
||||
|
||||
- Remote mode is read-only
|
||||
- No comment, label, close, approve, reject, merge, or release write actions
|
||||
- Health scoring tolerates unknown or unavailable metrics
|
||||
- No LLM dependency
|
||||
- No labels/comments/close operations
|
||||
- No PR approve/reject/merge operations
|
||||
- No `internal/output` change
|
||||
- No new third-party dependency
|
||||
- Test fixtures do not contain secrets or tokens
|
||||
|
||||
## Tests
|
||||
|
||||
- `gofmt -w shortcuts/workflow/*.go shortcuts/register.go`
|
||||
- `go test ./shortcuts/workflow`
|
||||
- `go test ./...`
|
||||
- `httptest` coverage for API normalization and fetch tolerance
|
||||
- Manual command examples in local and remote read-only modes
|
||||
- PR summary tests for change type, risk level, partial fetch failures, renderers, and command wiring
|
||||
- Repo report tests for aggregation, partial fetch behavior, renderers, local JSON input, and command wiring
|
||||
```bash
|
||||
gofmt -w shortcuts/workflow/*.go shortcuts/register.go
|
||||
go test ./shortcuts/workflow
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Coverage includes:
|
||||
|
||||
- triage rules
|
||||
- health scoring
|
||||
- PR summary rules
|
||||
- repo report aggregation
|
||||
- fetch normalization
|
||||
- partial failure handling
|
||||
- `json` / `table` / `markdown` rendering
|
||||
- local `--from` fixtures
|
||||
- command wiring tests
|
||||
|
||||
## Documentation
|
||||
|
||||
- `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`
|
||||
- `WORK_CONTINUATION.md`
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- Real API response shapes may still require minor normalization tweaks
|
||||
- `workflow +release-notes` is not implemented.
|
||||
- `workflow +stale` is not implemented.
|
||||
- Real GitLink API shapes may require follow-up normalization.
|
||||
- Remote `workflow +repo-report` PR aggregation currently uses PR list metadata;
|
||||
detailed file and commit analysis remains available through `workflow +pr-summary --number`
|
||||
- Write operations are intentionally deferred to a later PR
|
||||
- `release-notes` and `stale` are planned next
|
||||
detailed changed-file and commit analysis is available through `workflow +pr-summary --number`.
|
||||
|
||||
## Screenshots or Examples
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
gitlink-cli workflow +triage --title "Token leaked in logs" --body "The access token appears in command output" --format json
|
||||
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
|
||||
gitlink-cli workflow +triage --owner Gitlink --repo gitlink-cli --state open --limit 5 --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
|
||||
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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -136,3 +136,39 @@ gitlink-cli workflow +repo-report --from shortcuts/workflow/testdata/repo_report
|
|||
## Conclusion
|
||||
|
||||
The rule-based Agent Workflow prototype, including the read-only fetch layer, is implemented, tested, and locally runnable.
|
||||
|
||||
## Final Verification
|
||||
|
||||
Final verification should be run before opening the official GitLink PR:
|
||||
|
||||
```bash
|
||||
gofmt -w shortcuts/workflow/*.go shortcuts/register.go
|
||||
go test ./shortcuts/workflow
|
||||
go test ./...
|
||||
```
|
||||
|
||||
Expected result:
|
||||
|
||||
- `go test ./shortcuts/workflow` passes.
|
||||
- `go test ./...` passes.
|
||||
- No remote write operation is performed by workflow commands.
|
||||
|
||||
## Competition Demo Commands
|
||||
|
||||
Prefer local fixtures for stable demos:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Read-only remote smoke commands:
|
||||
|
||||
```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
|
||||
```
|
||||
|
|
|
|||
Loading…
Reference in New Issue