gitlink-cli/doc/generate_word.py

404 lines
21 KiB
Python
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""生成系统动态模型章节的 Word 文档 - 四个赛题"""
from docx import Document
from docx.shared import Pt, Inches, RGBColor
from docx.enum.text import WD_ALIGN_PARAGRAPH
from docx.enum.table import WD_TABLE_ALIGNMENT
from docx.oxml.ns import qn
from docx.oxml import OxmlElement
def set_cell_shading(cell, color):
"""设置单元格背景颜色"""
shading = OxmlElement('w:shd')
shading.set(qn('w:fill'), color)
cell._tc.get_or_add_tcPr().append(shading)
def add_table(doc, headers, rows, header_color="4472C4"):
"""添加表格"""
table = doc.add_table(rows=len(rows)+1, cols=len(headers))
table.style = 'Table Grid'
table.alignment = WD_TABLE_ALIGNMENT.CENTER
# 表头
for i, header in enumerate(headers):
cell = table.rows[0].cells[i]
cell.text = header
set_cell_shading(cell, header_color)
for paragraph in cell.paragraphs:
paragraph.alignment = WD_ALIGN_PARAGRAPH.CENTER
for run in paragraph.runs:
run.font.bold = True
run.font.color.rgb = RGBColor(255, 255, 255)
# 数据行
for i, row in enumerate(rows):
for j, value in enumerate(row):
table.rows[i+1].cells[j].text = value
return table
def create_document():
doc = Document()
# 设置默认字体
style = doc.styles['Normal']
style.font.name = 'Microsoft YaHei'
style._element.rPr.rFonts.set(qn('w:eastAsia'), 'Microsoft YaHei')
# 标题
title = doc.add_heading('系统动态模型', 0)
title.alignment = WD_ALIGN_PARAGRAPH.CENTER
# 概述
doc.add_heading('概述', level=1)
doc.add_paragraph(
'系统动态模型描述了 gitlink-cli 在四个赛题场景下的运行时行为,'
'展示了各组件之间的交互流程和数据流向。每个赛题对应一个核心能力方向,'
'覆盖 CLI 功能扩展、Skills 开发、自动化工作流和科研辅助四大领域。'
)
# ==================== 赛题一 ====================
doc.add_heading('子赛题一:增加和完善 GitLink-CLI 能力', level=1)
doc.add_heading('1.1 能构建的模型', level=2)
doc.add_paragraph(
'本赛题聚焦于 CLI 命令系统的功能扩展和优化。可构建以下动态模型:'
)
doc.add_paragraph('命令执行模型:描述 Shortcut 命令从参数解析到 API 调用的完整执行流程', style='List Bullet')
doc.add_paragraph('批量操作模型描述批量命令batch-close、batch-create 等)的遍历执行和错误处理机制', style='List Bullet')
doc.add_paragraph('参数校验模型:描述 Choices 枚举校验和 Validate 自定义校验的执行流程', style='List Bullet')
doc.add_paragraph('输出格式化模型:描述 Envelope 数据经过 table/json/yaml 格式化后的输出流程', style='List Bullet')
doc.add_heading('1.2 新生成的组件', level=2)
add_table(doc,
['组件类型', '组件名称', '功能说明'],
[
['Shortcut', 'wiki +list/+view/+create/+update/+delete', 'Wiki 页面 CRUD 操作'],
['Shortcut', 'webhook +list/+create/+update/+delete/+test', 'Webhook 配置管理'],
['Shortcut', 'board +view/+columns/+issues/+move/+assign', '项目看板操作'],
['Shortcut', 'issue +batch-close/+batch-create/+batch-assign', 'Issue 批量操作'],
['Shortcut', 'repo +batch-create/+batch-update', '仓库批量操作'],
['Shortcut', 'pr +merge (支持 merge/rebase/squash)', 'PR 合并方式选择'],
['Shortcut', 'branch +protect/+unprotect', '分支保护规则管理'],
['Shortcut', 'release +list/+create/+view/+delete', '版本发布管理'],
['结构体', 'Flag.Choices', '枚举参数校验,自动追加 [val1|val2] 提示'],
['结构体', 'Flag.Validate', '自定义校验函数,跨参数约束'],
['结构体', 'PrintOptions', '输出选项:列过滤、禁用截断、彩色输出'],
['函数', 'OpError()', '统一错误构造函数,中英文双语错误信息'],
]
)
doc.add_heading('1.3 交互流程示例', level=2)
doc.add_paragraph('示例一Wiki 页面创建', style='List Bullet')
steps = [
'用户输入gitlink-cli wiki +create --title "API文档" --content "# API Reference"',
'Cobra 解析命令,匹配到 wiki +create Shortcut',
'Validate 校验:检查 --title 是否为空',
'ResolveOwnerRepo() 从 git remote 解析 owner/repo',
'CallAPI("POST", "/wiki/open/createWiki", body) 调用 Gateway API',
'OutputData() 格式化输出创建结果',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例二:枚举参数校验', style='List Bullet')
steps = [
'用户输入gitlink-cli pr +merge --id 42 --method unknown',
'Cobra 解析参数,发现 --method 值为 unknown',
'Choices 校验unknown 不在 [merge, rebase, squash] 中',
'输出错误invalid value "unknown" for --method有效值: merge, rebase, squash',
'命令终止exit code = 1',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例三:批量关闭 Issuedry-run 预览)', style='List Bullet')
steps = [
'用户输入gitlink-cli issue +batch-close --numbers 101,102,103 --dry-run',
'解析 --numbers 参数,得到 [101, 102, 103]',
'IsDryRun() == true进入预览模式',
'构建 BatchSummary {dry_run: true, total: 3, results: [{status: "planned"},...]}',
'输出预览结果,不发起 HTTP 请求',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
# ==================== 赛题二 ====================
doc.add_heading('子赛题二:编写和丰富 GitLink Skills', level=1)
doc.add_heading('2.1 能构建的模型', level=2)
doc.add_paragraph(
'本赛题聚焦于 AI Agent Skill 的开发。可构建以下动态模型:'
)
doc.add_paragraph('Skill 加载模型:描述 Claude Code 触发 Skill、加载 SKILL.md 和 reference 文档的流程', style='List Bullet')
doc.add_paragraph('AI 分析模型:描述 AI 对 PR Diff、Issue 内容、仓库数据的分析和决策流程', style='List Bullet')
doc.add_paragraph('自动执行模型:描述 AI 分析结果转化为 CLI 命令执行的流程', style='List Bullet')
doc.add_heading('2.2 新生成的组件', level=2)
add_table(doc,
['组件类型', '组件名称', '功能说明'],
[
['Skill', 'gitlink-code-review', '智能代码审查:分析 PR diff输出结构化 Review 意见'],
['Skill', 'gitlink-issue-triage', 'Issue 自动分拣:根据内容自动分类、打标签、分配责任人'],
['Skill', 'gitlink-changelog', 'Release Notes 生成:根据 commit 和 PR 生成版本说明'],
['Skill', 'gitlink-health', '项目健康度报告:统计 Issue 响应时间、PR 合并效率'],
['Skill', 'gitlink-compliance', '许可证合规检查:扫描许可证合规性和敏感信息泄露'],
['Skill', 'gitlink-onboard', '新人引导:为 good-first-issue 自动添加引导评论'],
['Skill', 'gitlink-stale', '过期 Issue 管理:自动标记和关闭长期未活动的 Issue'],
['Skill', 'gitlink-faq', 'FAQ 自动回复:根据 Issue 内容匹配 FAQ 并自动评论'],
['Reference', 'references/pr-review.md', 'PR 审查参考文档:审查维度、评分标准、评论模板'],
['Reference', 'references/issue-triage.md', 'Issue 分类参考文档:分类规则、标签映射、分配策略'],
]
)
doc.add_heading('2.3 交互流程示例', level=2)
doc.add_paragraph('示例一:智能代码审查', style='List Bullet')
steps = [
'用户触发:"帮我审查 PR #42"',
'Claude Code 加载 gitlink-code-review skill',
'获取 PR 详情gitlink-cli pr +view --id 42 --format json',
'获取变更文件gitlink-cli pr +files --id 42 --format json',
'AI 分析代码:检测未处理 error、SQL 注入风险、性能问题',
'生成审查报告:质量评分 8.5/10列出 3 个问题',
'提交审查评论gitlink-cli pr +review --id 42 --body "..." --event comment',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例二Issue 自动分拣', style='List Bullet')
steps = [
'用户触发:"帮我分类本周的 Issue"',
'Claude Code 加载 gitlink-issue-triage skill',
'获取 Issue 列表gitlink-cli issue +list --state open --format json',
'AI 分析内容识别关键词bug/功能/提问)',
'自动添加标签gitlink-cli issue +label-add --number 101 --labels "缺陷"',
'自动分配责任人gitlink-cli issue +update --number 101 --assignee "zhangsan"',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例三Release Notes 生成', style='List Bullet')
steps = [
'用户触发:"帮我生成 v2.1.0 的 Release Notes"',
'Claude Code 加载 gitlink-changelog skill',
'获取已合并 PRgitlink-cli pr +list --state merged --format json',
'获取 commit 历史git log --oneline v2.0.0..HEAD',
'AI 分类整理新功能、Bug 修复、性能优化、Breaking Changes',
'生成 Release Notesgitlink-cli release +create --tag v2.1.0 --body "..."',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
# ==================== 赛题三 ====================
doc.add_heading('子赛题三:构建端到端自动化工作流', level=1)
doc.add_heading('3.1 能构建的模型', level=2)
doc.add_paragraph(
'本赛题聚焦于串联多个步骤的完整解决方案。可构建以下动态模型:'
)
doc.add_paragraph('工作流调度模型:描述工作流从触发、菜单选择、步骤执行到结果输出的完整流程', style='List Bullet')
doc.add_paragraph('多步骤编排模型:描述多个 CLI 命令和 Skill 的串联执行和错误处理', style='List Bullet')
doc.add_paragraph('数据聚合模型:描述从多个数据源采集数据并汇总生成报告的流程', style='List Bullet')
doc.add_heading('3.2 新生成的组件', level=2)
add_table(doc,
['组件类型', '组件名称', '功能说明'],
[
['Skill', 'gitlink-workflows', '工作流调度入口,提供功能菜单选择'],
['Workflow', '01-community-ops.sh', '社区运营自动化Issue 分类 + 周报生成'],
['Workflow', '01a-issue-triage.sh', 'Issue 分类子工作流'],
['Workflow', '01a-webhook-setup.sh', 'Webhook 配置子工作流'],
['Workflow', '02-code-quality-gatekeeper.sh', '代码质量门禁PR 审查 + 评分'],
['Workflow', '03-project-init.sh', '项目一键初始化:仓库 + 文件 + CI + Issues'],
['Workflow', '04-multi-repo-collab.sh', '多仓库协同:依赖追踪 + 协同发版'],
['Workflow', '05-contributor-growth.sh', '贡献者成长体系:评分 + 排行 + Badge'],
['Lib', 'lib/common.sh', '公共函数库:认证检查、错误处理、日志输出'],
]
)
doc.add_heading('3.3 交互流程示例', level=2)
doc.add_paragraph('示例一:项目一键初始化', style='List Bullet')
steps = [
'用户触发:"帮我初始化新项目 my-project"',
'Claude Code 加载 gitlink-workflows skill显示菜单',
'用户选择"项目一键初始化"',
'认证检查gitlink-cli auth status',
'创建仓库gitlink-cli repo +create --name my-project --private',
'初始化文件gitlink-cli file +create --path README.md --content "..."',
'初始化文件gitlink-cli file +create --path .gitignore --content "..."',
'初始化文件gitlink-cli file +create --path LICENSE --content "..."',
'配置分支保护gitlink-cli branch +protect --name master --require-review',
'创建 Issuesgitlink-cli issue +create --title "完善单元测试" --labels "good-first-issue"',
'输出初始化报告',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例二:多仓库协同发版', style='List Bullet')
steps = [
'用户触发:"帮我管理多仓库协同"',
'扫描仓库列表gitlink-cli repo +list --user my-org --format json',
'分析依赖关系frontend → api-client → backend',
'查询跨仓库 PRgitlink-cli pr +list --state open --format json',
'检查发版就绪gitlink-cli release +list --format json',
'识别阻塞项backend PR #456 未合并',
'生成协同 Dashboard显示各仓库状态、依赖关系、阻塞项',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例三:贡献者成长体系', style='List Bullet')
steps = [
'用户触发:"帮我生成贡献者排行榜"',
'获取贡献者列表gitlink-cli repo +members --format json',
'统计 PR 活动gitlink-cli pr +list --state merged --format json',
'统计 Issue 活动gitlink-cli issue +list --state closed --format json',
'AI 计算贡献评分PR 数量 × 3 + Issue 数量 × 1 + Review × 2',
'生成排行榜zhangsan(85分) > lisi(72分) > wangwu(68分)',
'自动颁发 Badge为 top 3 贡献者添加 "core-contributor" 标签',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
# ==================== 赛题四 ====================
doc.add_heading('子赛题四:应用 GitLink 辅助科研', level=1)
doc.add_heading('4.1 能构建的模型', level=2)
doc.add_paragraph(
'本赛题聚焦于科研场景的智能化赋能。可构建以下动态模型:'
)
doc.add_paragraph('科研项目洞悉模型:描述从仓库数据提取科研项目信息(技术栈、活跃度、依赖)的流程', style='List Bullet')
doc.add_paragraph('热点追踪模型:描述从 Issue/PR/Commit 数据挖掘科研热点趋势的流程', style='List Bullet')
doc.add_paragraph('合规检查模型:描述许可证合规性扫描和敏感信息检测的流程', style='List Bullet')
doc.add_paragraph('协作匹配模型:描述根据贡献者技能和项目需求进行智能匹配的流程', style='List Bullet')
doc.add_heading('4.2 新生成的组件', level=2)
add_table(doc,
['组件类型', '组件名称', '功能说明'],
[
['Skill', 'gitlink-research', '科研辅助系统总入口,提供科研场景菜单'],
['Skill', 'gitlink-code-insight', '仓库级科研项目洞悉:技术栈、活跃度、依赖分析'],
['Skill', 'gitlink-compliance', '科研项目合规与复现性检查:许可证、依赖、环境'],
['Workflow', '06-research-insights.sh', '科研热点追踪:从 Issue/PR 挖掘研究趋势'],
['Workflow', '08-research-compliance.sh', '科研合规检查:扫描许可证和敏感信息'],
['Workflow', '10-research-progress.sh', '科研进度跟踪:里程碑进度、阻塞项识别'],
['Workflow', '11-research-citation.sh', '论文引用分析:追踪仓库的学术引用情况'],
]
)
doc.add_heading('4.3 交互流程示例', level=2)
doc.add_paragraph('示例一:仓库级科研项目洞悉', style='List Bullet')
steps = [
'用户触发:"帮我分析这个仓库的科研价值"',
'Claude Code 加载 gitlink-code-insight skill',
'获取仓库信息gitlink-cli repo +info --format json',
'分析技术栈:扫描 package.json/go.mod/requirements.txt',
'分析活跃度gitlink-cli pr +list --state merged --format json',
'分析依赖:识别上下游依赖关系',
'生成科研洞悉报告:技术栈、活跃贡献者、核心模块、研究方向',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例二:科研热点追踪', style='List Bullet')
steps = [
'用户触发:"帮我追踪 AI 领域的科研热点"',
'扫描相关仓库gitlink-cli search +repos --query "machine-learning"',
'获取 Issue 列表gitlink-cli issue +list --state open --format json',
'获取 PR 列表gitlink-cli pr +list --state merged --format json',
'AI 分析关键词识别高频技术词汇transformer、diffusion、LLM',
'生成热点报告:技术趋势、热门项目、活跃研究者',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
doc.add_paragraph('示例三:科研合规与复现性检查', style='List Bullet')
steps = [
'用户触发:"帮我检查这个科研项目的合规性"',
'Claude Code 加载 gitlink-compliance skill',
'扫描许可证:检查 LICENSE 文件和依赖许可证',
'扫描敏感信息:检查 API Key、密码、私钥泄露',
'检查复现性:验证 requirements.txt/go.mod 完整性',
'生成合规报告:许可证合规、依赖风险、复现性评分',
]
for i, step in enumerate(steps, 1):
doc.add_paragraph(f' {i}. {step}')
# ==================== 赛题对比总结 ====================
doc.add_heading('赛题对比总结', level=1)
add_table(doc,
['维度', '赛题一CLI 能力', '赛题二Skills 开发', '赛题三:自动化工作流', '赛题四:辅助科研'],
[
['核心目标', '扩展 CLI 命令', '开发 AI Skill', '串联完整流程', '科研场景赋能'],
['技术栈', 'Go + Cobra', 'Markdown + CLI', 'Shell + CLI + Skill', '数据分析 + AI'],
['交付物', 'Shortcut + 结构体', 'SKILL.md + Reference', 'Workflow 脚本', '科研 Skill + 报告'],
['AI 参与', '', '核心AI 分析)', '调度 + 分析', '深度(知识挖掘)'],
['典型场景', 'Wiki/Webhook/批量', '代码审查/Issue 分类', '项目初始化/协同发版', '热点追踪/合规检查'],
]
)
# ==================== 组件依赖关系 ====================
doc.add_heading('组件依赖关系', level=1)
dep_tree = """gitlink-cli (CLI 核心)
├── Shortcuts (赛题一)
│ ├── wiki +list/+view/+create/+update/+delete
│ ├── webhook +list/+create/+update/+delete/+test
│ ├── board +view/+columns/+issues/+move/+assign
│ ├── issue +batch-close/+batch-create/+batch-assign
│ ├── repo +batch-create/+batch-update
│ └── branch +protect/+unprotect
├── Skills (赛题二)
│ ├── gitlink-code-review (代码审查)
│ ├── gitlink-issue-triage (Issue 分类)
│ ├── gitlink-changelog (Release Notes)
│ ├── gitlink-health (项目健康度)
│ ├── gitlink-compliance (合规检查)
│ ├── gitlink-onboard (新人引导)
│ └── gitlink-stale (过期管理)
├── Workflows (赛题三)
│ ├── 01-community-ops.sh (社区运营)
│ ├── 02-code-quality-gatekeeper.sh (质量门禁)
│ ├── 03-project-init.sh (项目初始化)
│ ├── 04-multi-repo-collab.sh (多仓库协同)
│ └── 05-contributor-growth.sh (贡献者成长)
└── Research Skills (赛题四)
├── gitlink-research (科研总入口)
├── gitlink-code-insight (项目洞悉)
├── gitlink-compliance (合规检查)
└── research workflows (热点/进度/引用)"""
p = doc.add_paragraph()
run = p.add_run(dep_tree)
run.font.name = 'Consolas'
# ==================== 状态转换说明 ====================
doc.add_heading('状态转换说明', level=1)
doc.add_heading('Shortcut 命令执行状态', level=2)
doc.add_paragraph('Init → Parsing → Validation → Resolving → Loading → Executing → APICall → Done/Error')
doc.add_paragraph('任何阶段出现错误都会进入 Error 状态,输出结构化错误信息后终止。')
doc.add_heading('Skill 触发状态', level=2)
doc.add_paragraph('Idle → Triggered → Loaded → AuthCheck → DataCollection → AIAnalysis → Execution → Output')
doc.add_paragraph('Skill 加载失败时回退到 Idle 状态AI 分析失败时输出错误提示。')
doc.add_heading('Workflow 执行状态', level=2)
doc.add_paragraph('Idle → Selecting → Loading → AuthCheck → Step1 → Step2 → ... → StepN → Done')
doc.add_paragraph('任一步骤失败时根据配置决定继续或终止,最终输出执行汇总。')
# 保存
output_path = r'C:\Users\Lenovo\Desktop\soft运维\gitlink-cli\doc\系统动态模型章节.docx'
doc.save(output_path)
print(f'Word 文档已生成:{output_path}')
if __name__ == '__main__':
create_document()