diff --git a/WORK_CONTINUATION.md b/WORK_CONTINUATION.md deleted file mode 100644 index 0ca89b9..0000000 --- a/WORK_CONTINUATION.md +++ /dev/null @@ -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`. diff --git a/docs/competition-solution.md b/docs/competition-solution.md deleted file mode 100644 index 46a5954..0000000 --- a/docs/competition-solution.md +++ /dev/null @@ -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. diff --git a/docs/competition-submit.zh-CN.md b/docs/competition-submit.zh-CN.md deleted file mode 100644 index 513823f..0000000 --- a/docs/competition-submit.zh-CN.md +++ /dev/null @@ -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 收录申请 -- 更多真实项目验证 diff --git a/docs/defense-qa.md b/docs/defense-qa.md deleted file mode 100644 index c776098..0000000 --- a/docs/defense-qa.md +++ /dev/null @@ -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 可以读取这些结果，生成后续任务、报告或维护计划，而不依赖不稳定的自然语言解析。 diff --git a/docs/demo-script.md b/docs/demo-script.md deleted file mode 100644 index 7fbc429..0000000 --- a/docs/demo-script.md +++ /dev/null @@ -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`，但当前提交保持聚焦、可测试、可落地。 - -截图点位： -- 安全边界列表。 diff --git a/docs/final-submission-checklist.md b/docs/final-submission-checklist.md deleted file mode 100644 index 00cdb96..0000000 --- a/docs/final-submission-checklist.md +++ /dev/null @@ -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 diff --git a/docs/pr-draft.md b/docs/pr-draft.md index 24fe18e..48bc8c6 100644 --- a/docs/pr-draft.md +++ b/docs/pr-draft.md @@ -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