forked from Gitlink/gitlink-cli
254 lines
19 KiB
JavaScript
254 lines
19 KiB
JavaScript
const fs = require('fs');
|
||
const { Document, Packer, Paragraph, TextRun, Table, TableRow, TableCell,
|
||
Header, Footer, AlignmentType, HeadingLevel, BorderStyle, WidthType,
|
||
ShadingType, PageNumber, PageBreak, LevelFormat } = require('docx');
|
||
|
||
// ===== 通用样式 =====
|
||
const border = { style: BorderStyle.SINGLE, size: 1, color: 'BBBBBB' };
|
||
const borders = { top: border, bottom: border, left: border, right: border };
|
||
|
||
function makeHeaderRow(cells) {
|
||
return new TableRow({
|
||
children: cells.map(c => new TableCell({
|
||
borders,
|
||
width: { size: c.w, type: WidthType.DXA },
|
||
shading: { fill: '1E3A5F', type: ShadingType.CLEAR },
|
||
margins: { top: 60, bottom: 60, left: 100, right: 100 },
|
||
children: [new Paragraph({ children: [new TextRun({ text: c.t, bold: true, color: 'FFFFFF', font: 'Microsoft YaHei', size: 20 })] })]
|
||
}))
|
||
});
|
||
}
|
||
function makeRow(cells) {
|
||
return new TableRow({
|
||
children: cells.map(c => new TableCell({
|
||
borders,
|
||
width: { size: c.w, type: WidthType.DXA },
|
||
margins: { top: 60, bottom: 60, left: 100, right: 100 },
|
||
children: [new Paragraph({ children: [new TextRun({ text: c.t, font: 'Microsoft YaHei', size: 20 })] })]
|
||
}))
|
||
});
|
||
}
|
||
|
||
function p(text, opts) {
|
||
const size = (opts && opts.size) || 22;
|
||
return new Paragraph({ spacing: { after: 100 }, ...opts,
|
||
children: [new TextRun({ text, font: 'Microsoft YaHei', size })]
|
||
});
|
||
}
|
||
function bullet(text) {
|
||
return new Paragraph({
|
||
numbering: { reference: 'bullets', level: 0 },
|
||
children: [new TextRun({ text, font: 'Microsoft YaHei', size: 22 })]
|
||
});
|
||
}
|
||
|
||
const doc = new Document({
|
||
styles: {
|
||
default: { document: { run: { font: 'Microsoft YaHei', size: 24 } } },
|
||
paragraphStyles: [
|
||
{ id: 'Heading1', name: 'Heading 1', basedOn: 'Normal', next: 'Normal', quickFormat: true,
|
||
run: { size: 32, bold: true, font: 'Microsoft YaHei', color: '1E3A5F' },
|
||
paragraph: { spacing: { before: 360, after: 200 }, outlineLevel: 0 } },
|
||
{ id: 'Heading2', name: 'Heading 2', basedOn: 'Normal', next: 'Normal', quickFormat: true,
|
||
run: { size: 28, bold: true, font: 'Microsoft YaHei', color: '2B579A' },
|
||
paragraph: { spacing: { before: 280, after: 160 }, outlineLevel: 1 } },
|
||
{ id: 'Heading3', name: 'Heading 3', basedOn: 'Normal', next: 'Normal', quickFormat: true,
|
||
run: { size: 24, bold: true, font: 'Microsoft YaHei' },
|
||
paragraph: { spacing: { before: 200, after: 120 }, outlineLevel: 2 } },
|
||
]
|
||
},
|
||
numbering: {
|
||
config: [{
|
||
reference: 'bullets',
|
||
levels: [{ level: 0, format: LevelFormat.BULLET, text: '•', alignment: AlignmentType.LEFT,
|
||
style: { paragraph: { indent: { left: 720, hanging: 360 } } } }]
|
||
}]
|
||
},
|
||
sections: [
|
||
// ===== 封面 =====
|
||
{
|
||
properties: {
|
||
page: { size: { width: 11906, height: 16838 }, margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
|
||
},
|
||
children: [
|
||
new Paragraph({ spacing: { before: 3000 }, children: [] }),
|
||
new Paragraph({ alignment: AlignmentType.CENTER, spacing: { after: 200 },
|
||
children: [new TextRun({ text: '《软件演化与运维》', size: 36, color: '1E3A5F', bold: true, font: 'Microsoft YaHei' })] }),
|
||
new Paragraph({ alignment: AlignmentType.CENTER, spacing: { after: 600 },
|
||
children: [new TextRun({ text: 'GitLink 智能化能力提升项目', size: 28, color: '2B579A', font: 'Microsoft YaHei' })] }),
|
||
new Paragraph({ alignment: AlignmentType.CENTER, spacing: { before: 600, after: 200 },
|
||
children: [new TextRun({ text: '软件分析及建模报告', size: 44, bold: true, font: 'Microsoft YaHei', color: '1E3A5F' })] }),
|
||
new Paragraph({ alignment: AlignmentType.CENTER, spacing: { before: 200, after: 100 },
|
||
children: [new TextRun({ text: '—— gitlink-cli 命令行工具与 AI Agent Skills 生态', size: 24, color: '64748B', font: 'Microsoft YaHei' })] }),
|
||
new Paragraph({ spacing: { before: 2400 }, children: [] }),
|
||
new Table({
|
||
width: { size: 7000, type: WidthType.DXA },
|
||
columnWidths: [2500, 4500],
|
||
rows: [
|
||
makeRow([{t:'项目名称',w:2500},{t:'GitLink 智能化能力提升项目',w:4500}]),
|
||
makeRow([{t:'项目成员',w:2500},{t:'刘焱、赵昌(wqer)、曾蔚然(z2_cc)',w:4500}]),
|
||
makeRow([{t:'完成日期',w:2500},{t:'2026-06-30',w:4500}]),
|
||
]
|
||
}),
|
||
]
|
||
},
|
||
// ===== 正文 =====
|
||
{
|
||
properties: {
|
||
page: { size: { width: 11906, height: 16838 }, margin: { top: 1440, right: 1440, bottom: 1440, left: 1440 } }
|
||
},
|
||
headers: {
|
||
default: new Header({
|
||
children: [new Paragraph({
|
||
alignment: AlignmentType.RIGHT,
|
||
border: { bottom: { style: BorderStyle.SINGLE, size: 4, color: '1E3A5F', space: 4 } },
|
||
children: [new TextRun({ text: '软件分析及建模报告 · GitLink CLI', size: 16, color: '94A3B8', font: 'Microsoft YaHei' })]
|
||
})]
|
||
})
|
||
},
|
||
footers: {
|
||
default: new Footer({
|
||
children: [new Paragraph({
|
||
alignment: AlignmentType.CENTER,
|
||
children: [
|
||
new TextRun({ text: '第 ', size: 18, color: '94A3B8' }),
|
||
new TextRun({ children: [PageNumber.CURRENT], size: 18, color: '94A3B8' }),
|
||
new TextRun({ text: ' 页', size: 18, color: '94A3B8' })
|
||
]
|
||
})]
|
||
})
|
||
},
|
||
children: [
|
||
// 第1章
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第1章 引言')] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('1.1 项目背景')] }),
|
||
p('GitLink 是一个新一代的开源创新服务平台，提供分布式协作开发、流水线运维、代码分析等功能。gitlink-cli 是 GitLink 平台的官方命令行工具，采用 Go 语言开发，内置 AI Agent Skills，支持 31 个命令组、181+ 个命令，覆盖仓库管理、Issue 跟踪、PR 协作、CI/CD 等核心场景。'),
|
||
p('随着 Claude Code、Cursor 等 AI 编程智能体的兴起，开发者正在从“手动操作平台”转向“Agent 驱动开发”。gitlink-cli 内置的 Skills 体系使其天然适配这些主流 Agent 平台，既能让 AI Agent 直接调用 GitLink 的代码托管、协作与 CI/CD 能力，也能依托其数据获取能力为科研团队提供智能化辅助服务。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('1.2 项目目标')] }),
|
||
bullet('扩展 CLI 能力：补齐缺失的 Shortcut 命令、优化交互体验、提升跨平台兼容性'),
|
||
bullet('丰富 AI Agent Skills：开发可被 Claude Code 等 Agent 调用的结构化 Skill'),
|
||
bullet('构建端到端工作流：串联多个 Skill 解决真实社区运营和代码质量场景'),
|
||
bullet('赋能科研场景：利用 CLI 数据采集与 AI 分析支持科研项目洞察与热点追踪'),
|
||
|
||
// 第2章
|
||
new Paragraph({ children: [new PageBreak()] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第2章 需求分析')] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('2.1 功能需求')] }),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_3, children: [new TextRun('2.1.1 CLI 能力（子任务一）')] }),
|
||
p('为 gitlink-cli 增加新功能或优化现有功能，包括新增 Shortcut 命令、优化参数设计和输出格式、增加批量操作能力、提升跨平台兼容性和安装体验、补齐 Raw API 封装。最终交付 31 个命令组、181+ 个子命令、20 个单元测试文件。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_3, children: [new TextRun('2.1.2 AI Agent Skills（子任务二）')] }),
|
||
p('基于 gitlink-cli 开发新的 AI Agent Skill，遵循 skills/README.md 规范，兼容 Claude Code 等主流 Agent 平台。核心交付包括 Issue 自动分拣、代码审查、项目健康度报告、自动 Release Notes、许可证合规检查、新人引导等 Skill。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_3, children: [new TextRun('2.1.3 端到端工作流（子任务三）')] }),
|
||
p('组合 ≥3 个 CLI 命令或 Skill 调用，构建可复现的自动化场景。包括社区运营自动化（Issue 分拣→周报→Release Notes）和代码质量看门人（PR 审查→CI 检查→质量评分→自动合并）。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_3, children: [new TextRun('2.1.4 科研辅助（子任务四）')] }),
|
||
p('利用 gitlink-cli 数据获取与 AI Agent 能力，面向科研工作者提供仓库级科研分析（8 维数据采集、4 维度评分）和科研热点追踪（多关键词搜索、知识图谱构建）。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('2.2 非功能需求')] }),
|
||
bullet('可复现性：所有工作流脚本参数化，支持在不同仓库间复用'),
|
||
bullet('安全性：所有写操作默认 dry-run，需显式确认才实际执行'),
|
||
bullet('兼容性：支持 Windows/Linux/macOS 三大平台，兼容 Claude Code 等 Agent'),
|
||
bullet('可追溯性：脚本输出保存到 _output/ 目录，便于审计'),
|
||
|
||
// 第3章
|
||
new Paragraph({ children: [new PageBreak()] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第3章 系统建模')] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('3.1 用例模型')] }),
|
||
p('gitlink-cli 系统的参与者（Actor）包括三种角色：普通开发者、项目维护者/社区运营、科研工作者。'),
|
||
|
||
new Table({
|
||
width: { size: 9026, type: WidthType.DXA },
|
||
columnWidths: [1800, 2400, 2400, 2426],
|
||
rows: [
|
||
makeHeaderRow([{t:'用例',w:1800},{t:'参与者',w:2400},{t:'涉及子任务',w:2400},{t:'前置条件',w:2426}]),
|
||
makeRow([{t:'仓库管理',w:1800},{t:'开发者',w:2400},{t:'子任务一',w:2400},{t:'认证登录',w:2426}]),
|
||
makeRow([{t:'Issue 管理',w:1800},{t:'开发者',w:2400},{t:'子任务一',w:2400},{t:'仓库权限',w:2426}]),
|
||
makeRow([{t:'PR 协作',w:1800},{t:'开发者',w:2400},{t:'子任务一',w:2400},{t:'仓库权限',w:2426}]),
|
||
makeRow([{t:'Issue 自动分拣',w:1800},{t:'维护者',w:2400},{t:'子任务二',w:2400},{t:'CLI + AI Agent',w:2426}]),
|
||
makeRow([{t:'代码审查',w:1800},{t:'维护者',w:2400},{t:'子任务二',w:2400},{t:'CLI + AI Agent',w:2426}]),
|
||
makeRow([{t:'社区运营',w:1800},{t:'维护者',w:2400},{t:'子任务三',w:2400},{t:'脚本环境',w:2426}]),
|
||
makeRow([{t:'质量门禁',w:1800},{t:'维护者',w:2400},{t:'子任务三',w:2400},{t:'PR + CI',w:2426}]),
|
||
makeRow([{t:'科研分析',w:1800},{t:'科研工作者',w:2400},{t:'子任务四',w:2400},{t:'CLI + AI Agent',w:2426}]),
|
||
makeRow([{t:'热点追踪',w:1800},{t:'科研工作者',w:2400},{t:'子任务四',w:2400},{t:'搜索关键词',w:2426}]),
|
||
]
|
||
}),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('3.2 架构模型')] }),
|
||
p('gitlink-cli 采用经典的三层命令行架构：'),
|
||
bullet('第一层 - Shortcuts（快捷命令层）：以 gitlink-cli <group> +<verb> 模式提供高频操作的友好接口'),
|
||
bullet('第二层 - API Commands（命令实现层）：通过元数据驱动的方式封装 GitLink REST API'),
|
||
bullet('第三层 - Raw API（原始 API 层）：通过 gitlink-cli api <METHOD> <PATH> 直接访问任意端点'),
|
||
p('这一设计兼顾了易用性（Shortcuts）与扩展性（Raw API），同时通过统一的客户端层处理认证、错误处理和输出格式化。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('3.3 Skills 框架模型')] }),
|
||
p('AI Agent Skills 是结构化知识库，每个 Skill 包含 SKILL.md（命令参考与流程）、REFERENCE.md（API 细节）、examples/（工作流示例）。Skills 框架采用分层设计：'),
|
||
bullet('共享层（gitlink-shared）：认证、全局参数、安全规则、API 注意事项'),
|
||
bullet('领域层（repo/issue/pr/release/ci）：各功能领域的命令参考'),
|
||
bullet('智能层（code-review/triage/health）：AI 驱动的分析工作流'),
|
||
bullet('编排层（workflow/community-ops/quality-gate）：端到端场景串联'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('3.4 工作流模型')] }),
|
||
p('社区运营自动化采用三阶段顺序执行模型：Phase 1（Issue 分拣）→ Phase 2（周报生成）→ Phase 3（Release Notes）。各阶段通过 JSON 文件传递数据，支持独立执行和断点续传。'),
|
||
p('代码质量看门人采用四阶段流水线模型：Phase 1（PR 采集）→ Phase 2（深度审查）→ Phase 3（CI 检查）→ Phase 4（门禁决策）。决策阶段使用加权评分模型：CodeReview×40% + CI×30% + 设计一致性×30%。'),
|
||
|
||
// 第4章
|
||
new Paragraph({ children: [new PageBreak()] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第4章 架构设计')] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('4.1 整体架构')] }),
|
||
p('系统整体采用四层架构：CLI 层 → Skills 层 → 工作流层 → 可视化层。'),
|
||
p('CLI 层（Go + Cobra）提供 31 个命令组的基础操作能力；Skills 层（Markdown 知识库）为 AI Agent 提供结构化调用指南；工作流层（Bash + Node.js）串联多个命令实现自动化场景；可视化层（HTML + Mermaid）将分析结果以交互式图表呈现。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('4.2 接口设计')] }),
|
||
p('内部接口：Shortcut 统一使用 gitlink-cli <group> +<verb> --flags 模式，输出支持 json/table/yaml 三种格式，统一信封格式 {ok, data, error, meta}。'),
|
||
p('外部接口：通过 .devops/ 流水线配置对接 GitLink DevOps 引擎，通过 .github/workflows/ 对接 GitHub Actions CI/CD。'),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('4.3 安全设计')] }),
|
||
bullet('认证：基于 Token 的认证方式，通过 gitlink-cli auth login 获取，有效期 7 天，存储在 OS Keychain'),
|
||
bullet('写保护：所有自动化脚本默认 DRY_RUN=true，需要显式确认才执行实际写入'),
|
||
bullet('版本一致：detect-cli.sh 自动检测本地编译版本，确保完整命令可用'),
|
||
|
||
// 第5章
|
||
new Paragraph({ children: [new PageBreak()] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第5章 接口规范')] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('5.1 命令接口规范')] }),
|
||
new Table({
|
||
width: { size: 9026, type: WidthType.DXA },
|
||
columnWidths: [2500, 2000, 4526],
|
||
rows: [
|
||
makeHeaderRow([{t:'接口',w:2500},{t:'格式',w:2000},{t:'示例',w:4526}]),
|
||
makeRow([{t:'仓库信息',w:2500},{t:'Shortcut',w:2000},{t:'gitlink-cli repo +info --owner z2_cc --repo gitlink-cli',w:4526}]),
|
||
makeRow([{t:'Issue 列表',w:2500},{t:'Shortcut',w:2000},{t:'gitlink-cli issue +list --state open --format json',w:4526}]),
|
||
makeRow([{t:'PR 审查',w:2500},{t:'Shortcut',w:2000},{t:'gitlink-cli pr +review --id 5 --status approved',w:4526}]),
|
||
makeRow([{t:'提交历史',w:2500},{t:'Shortcut',w:2000},{t:'gitlink-cli commit +list --limit 100 --format json',w:4526}]),
|
||
makeRow([{t:'仓库搜索',w:2500},{t:'Shortcut',w:2000},{t:'gitlink-cli search +repos --keyword "machine learning"',w:4526}]),
|
||
makeRow([{t:'Raw API',w:2500},{t:'Raw API',w:2000},{t:'gitlink-cli api GET /user/me --format json',w:4526}]),
|
||
]
|
||
}),
|
||
|
||
new Paragraph({ heading: HeadingLevel.HEADING_2, children: [new TextRun('5.2 输出格式规范')] }),
|
||
p('所有命令支持 --format json 输出统一信封格式：{ "ok": true, "data": { ... }, "error": null, "meta": { ... } }。data 字段承载具体业务数据，error 字段在失败时包含错误信息。'),
|
||
|
||
// 第6章
|
||
new Paragraph({ children: [new PageBreak()] }),
|
||
new Paragraph({ heading: HeadingLevel.HEADING_1, children: [new TextRun('第6章 总结')] }),
|
||
p('本项目围绕 gitlink-cli 命令行工具及其 AI Agent Skills 生态，完成了 CLI 能力扩展、Skills 丰富、端到端工作流构建和科研辅助模块开发四大任务。'),
|
||
p('子任务一新增了 23 个 Shortcut 命令组 181+ 个命令，覆盖仓库管理、Issue 跟踪、PR 协作、CI/CD 等核心场景，并包含 20 个单元测试文件。子任务二开发了 11 个 Claude Code Skills，在 Claude Code 平台端到端验证通过。子任务三构建了社区运营自动化和代码质量看门人两个完整工作流，提供 9 个可复现脚本和 2 个数据分析引擎。子任务四实现了科研项目洞悟和热点追踪两个模块，提供交互式 HTML 知识图谱可视化。'),
|
||
p('项目产出 47 个交付文件，约 5,800 行代码，经过 14 轮修复迭代，最终全部验证通过。'),
|
||
|
||
new Paragraph({ spacing: { before: 400 }, alignment: AlignmentType.CENTER,
|
||
children: [new TextRun({ text: '— 报告完 —', size: 22, color: '94A3B8', font: 'Microsoft YaHei' })] }),
|
||
]
|
||
}
|
||
]
|
||
});
|
||
|
||
Packer.toBuffer(doc).then(buffer => {
|
||
const outPath = 'e:/gitlink-cli/gitlink-cli/doc/软件分析及建模报告.docx';
|
||
fs.writeFileSync(outPath, buffer);
|
||
console.log('Done: ' + outPath);
|
||
});
|