git-workspace-review

Git 工作区审查

不适用场景

• 编写提交说明（使用 sanctum:commit-messages）
• 运行完整的 PR 前检查（使用 sanctum:pr-prep）

验证

审查后运行 git status，确认工作区状态符合预期。

测试

运行 pytest plugins/sanctum/tests/test_git_workspace_review.py，验证审查工作流。

用法

在依赖仓库状态的工作流之前使用此技能，例如生成提交说明、准备 PR 或编写发布说明。每个会话运行一次，或在暂存的更改发生变化时运行。

必需的进度跟踪

1. git-review:repo-confirmed
2. git-review:status-overview
3. git-review:code-quality-check
4. git-review:diff-stat
5. git-review:diff-details

完成相应步骤后，将每项标记为已完成。

步骤 1：确认仓库（repo-confirmed）

运行 pwd，确认你位于正确的仓库目录中。执行 git status -sb，查看当前分支和简要状态，然后记录分支名称和上游信息。

步骤 2：审查状态概览（status-overview）

分析 git status -sb 的输出，检查已暂存和未暂存的更改。暂存或取消暂存文件，确保后续工作流针对预期的差异进行操作。

步骤 3：检查代码质量（code-quality-check）

从仓库根目录运行 make lint，在提交前验证代码质量。 它会检查 ruff 格式，运行各插件的 ruff 检查， 并运行 bandit。它不会重写任何内容：会修改工作树的检查无法报告 它原本要查找的差异。检查失败时，它会提示运行 make fix，这是 会修改文件的组合命令（ruff format 加 ruff check --fix）。根目录的 Makefile 未定义 format 目标，而 定义了该目标的插件 Makefile 只会在各自的 目录中生效。

立即修复所有错误。不要使用 --no-verify 绕过 pre-commit 钩子。 此检查可及早发现问题，避免在流程后期失败。

步骤 4：审查差异统计（diff-stat）

对于已暂存的更改，运行 git diff --cached --stat（对于 未暂存的更改，运行 git diff --stat）。记录修改的文件数， 并找出新增或删除行数较多的热点区域。

如果可以使用 sem（参见 leyline:sem-integration）， 还需运行 sem diff --format plain --staged，在统计输出旁显示实体级 摘要。它会展示哪些函数、类和方法发生了变化，而不仅仅是 行数变化。

步骤 5：审查详细差异（diff-details）

运行 git diff --cached 检查实际更改。对于未暂存的工作，使用 git diff。找出关键主题，例如 Makefile 调整或新增技能，为下游摘要提供背景信息。

退出标准

下游工作流会依赖这些信息，而不再重新运行 git。

• 已根据 git status -sb 记录分支名称和上游信息
• git diff --cached --stat 恰好列出下次提交所需的文件，没有预期提交的更改仍处于未暂存状态
• make lint 以状态码 0 退出，或者已修复其报告的每个问题，或已向用户说明
• 已记录已暂存差异的关键主题，供后续摘要使用

支持模块

• Git 命令参考 - sanctum 工作流中的差异、状态和分支操作

故障排除

如果 pre-commit 钩子阻止提交，请解决报告的问题，而不是使用 --no-verify。make lint 会自动修复格式问题，并指出剩余的逻辑问题。如果发生合并冲突，请使用 git merge --abort 恢复到干净状态，然后重试。