企业官网建设流程全解析

Pi-Harness 是 Pi Coding Agent 的运维超集桌面应用，内置了一套完整的原生 Git 工作区：提交历史图、文件级 Diff 对比、近期提交活动热力图，以及一键 AI 生成规范提交信息。本文将带你从入门到进阶，把这套 Git 工作流用起来。

快速上手：在哪里打开 Git 工作区 🚀

Git 视图是 Pi-Harness 中的一个独立入口（路由#/git），不需要先选中某个会话即可使用——它会读取工作区中已打开的全部项目：

• 打开应用后，在左侧导航栏点击Git；
• 若工作区还没有项目，界面会提示"暂无 Git 项目"，先在工作区打开一个 Git 仓库即可；
• 进入后你会看到三个主要区域：左侧仓库侧栏、中间的提交图谱、右侧的提交面板。

Git 视图的整体装配逻辑在 GitView.vue 中完成，历史行为可用端到端测试 git-workspace.spec.ts 作为操作参考。

提交历史图：像 GitKraken 一样浏览 Commit 📊

中间的 Commit graph 以图谱方式展示全部提交：每个提交一行，包含作者、时间、SHA 短哈希，分支标签与 Tag 以彩色徽标显示，合并提交会画出真实的分支汇聚线条。常用操作包括：

• 搜索提交：顶部输入框可按提交信息、作者、SHA、Tag 过滤；
• 按引用过滤：点击图谱上的分支标签（如feature/graph），只显示该分支上的提交，再次点击即可清除过滤；
• 右键提交：检出该提交、在此处建分支/打 Tag、合并到当前分支、变基、复制 SHA 或提交信息。

点击任意提交即可打开评审视图，查看"已更改文件"列表，再点击某个文件即可打开该文件的历史 Diff。图谱组件见 GitHistoryGraph.vue，交互逻辑在 GitWorkspaceView.vue。

一键 Diff：工作区差异与历史差异都看得到 🔍

Pi-Harness 的 Diff 能力覆盖两个场景：

1. 工作区 Diff：提交面板中列出"未暂存/已暂存"两组文件，点击文件名即以浮层形式打开该文件相对 HEAD 的差异，红绿行对照清晰可读；新文件会自动生成"整文件新增"的补丁视图；
2. 历史 Diff：从提交评审中点文件，查看该提交对文件的具体改动（超过 50 万字符的补丁会自动截断，避免界面卡死）。

底层由 GitService.diff 实现，差异渲染组件在 GitDiffView.vue 与 UnifiedDiffPreview.vue。文件级"它被哪些提交改过"则通过文件历史抽屉查看，对应 GitFileHistoryDrawer.vue 与 GitService.fileHistory。

历史活动图：近期提交热力图 🔥

左侧仓库侧栏底部有一张 GitHub 风格的近期提交热力图：

• 覆盖最近182 天（26 周）的提交记录，每周为一列，每天一个格子，提交越多颜色越深；
• 颜色深浅按仓库自身活跃度分档，安静仓库和活跃仓库都能读出节奏；
• 点击可打开"提交热力详情"，查看提交次数、活跃天数、峰值以及各提交者的贡献分布。

窗口天数定义在 git-activity.ts，绘图逻辑在 GitActivityGraph.vue：格子尺寸会自适应面板宽度，小窗口不会溢出。

AI 生成提交信息：一键产出规范 Commit ✨

这是 Git 工作区最实用的功能之一。把文件"全部暂存"后，提交面板底部的生成按钮即可点亮：

1. 在模型选择器中挑选一个模型（默认使用当前活动模型）；
2. 点击生成，应用会把暂存区的 diff 摘要 + 最近 8 条提交信息发给模型；
3. 模型按Conventional Commits规范输出type(scope): summary格式的信息，并自动匹配仓库既有提交的语言与语气；
4. 生成结果可编辑，也支持"修正上一次提交"（amend）。

系统提示词对输出有严格约束：主题行不超过 72 字符、祈使句、不虚构 diff 中不存在的测试或问题编号，见 commitSystemPrompt。上下文组装（暂存 diff + 近期提交）在 commitMessageContext 中完成。

💡 小贴士：若模型额度用尽或不支持关闭思考，界面会给出明确的中文提示，切换模型即可重试。

进阶操作：分支、远程与 Worktree 🛠️

除了日常提交，顶部工具条和右键菜单还封装了完整的仓库管理动作：

所有可变操作都会先校验路径是否位于所选仓库内，防止越权修改，实现见 GitService.action；Worktree 管理由 worktree-service.ts 提供。

小结 📝

Pi-Harness 的 Git 工作区把"看历史 → 读 Diff → 生成提交信息 → 提交/推送"的完整闭环搬进了桌面端：

• 提交历史图 + 搜索过滤，替代反复敲git log；
• 工作区/历史双重 Diff 浮层，替代手动git diff；
• 182 天提交热力图，直观掌握项目节奏；
• AI 一键生成符合 Conventional Commits 的提交信息。

核心源码导航：

• Git 服务层：src/main/git/
• AI 提交信息：commit-message-service.ts
• 界面组件：src/renderer/src/components/git/
• 端到端测试：e2e/git-workspace.spec.ts