DevTU GitHub 工作流：安全推送代码的预提交钩子与测试验证指南

devtu-github by mims-harvard/tooluniverse

149 周安装量

1,200 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/mims-harvard/tooluniverse --skill devtu-github

自动化代码质量版本控制

🇨🇳中文介绍

DevTU GitHub 工作流

通过强制执行推送前清理、预提交钩子和测试验证，安全地将 ToolUniverse 代码推送到 GitHub。

说明

当用户想要推送代码、修复 CI 或准备提交时，请遵循此工作流：

阶段 1：推送前清理

将临时文件移出根目录 - 会话文档和临时测试脚本绝对不能推送：

```bash

# 将会话 Markdown 文件移动到 temp_docs_and_tests/
for f in $(ls *.md 2>/dev/null | grep -v README.md | grep -v CHANGELOG.md | grep -v LICENSE.md); do
  mv "$f" temp_docs_and_tests/
done

# 将根目录级别的测试脚本移动到 temp_docs_and_tests/
for f in $(ls test_*.py 2>/dev/null); do
  mv "$f" temp_docs_and_tests/
done
```

2. 验证没有不需要的文件被暂存：

```bash
git status --short
```

**危险信号** - 以下内容绝对不应被暂存：
  * 根目录下的 `*_SUMMARY.md`、`*_REPORT.md`、`SESSION_*.md`
  * 根目录下的 `test_*.py`（这些是临时脚本，不是真正的测试）
  * `.env` 或凭证文件
  * `temp_docs_and_tests/` 目录中的内容

阶段 2：激活预提交钩子

确保 pre-commit 已安装并激活：

```bash

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

阶段 3：运行测试

在本地运行完整的测试套件：

python -m pytest tests/ -x --tb=short -q
```

6. 如果测试失败，请使用下面的错误模式进行诊断，并在继续之前修复。

阶段 4：提交和推送

仅暂存特定文件（切勿使用 git add . 或 git add -A）：

git add src/tooluniverse/specific_file.py tests/specific_test.py
```

8. 提交（预提交钩子会自动运行）：

```bash
git commit -m "清晰、描述性的提交信息"
```

9. 在推送之前，将当前分支变基到最新的 main 分支上（至关重要 — 防止 PR 冲突）：

```bash
git fetch origin
git stash            # 暂存任何未提交的工作
git rebase origin/main
git stash pop        # 恢复未提交的工作
```

如果变基发生冲突，请解决它们（保留我们较新的更改），然后：
```bash
git add <conflicted-file>
git rebase --continue
```

10. 推送（变基后使用 --force-with-lease）：

```bash
git push --force-with-lease origin <branch-name>
```

推送后，验证 PR 没有冲突：
```bash
gh pr view <PR-number> --json mergeable,mergeStateStatus
# 必须显示："mergeable":"MERGEABLE"
```

绝对禁止推送的文件

临时会话文档（根目录下的 .md 文件）

这些是开发过程中创建的会话笔记。在提交前移动到 temp_docs_and_tests/：

模式	示例
`*_SUMMARY.md`	`API_DISCOVERY_SESSION_SUMMARY.md`
`*_REPORT.md`	`SKILL_TESTING_REPORT.md`, `TOOLUNIVERSE_BUG_REPORT.md`
`SESSION_*.md`	`SESSION_2026_02_13.md`
`IMPLEMENTATION_*.md`	`IMPLEMENTATION_COMPLETE.md`
`BUG_ANALYSIS_*.md`	`BUG_ANALYSIS_DETAILED.md`
`FIX_*.md`	`FIX_SUMMARY.md`, `CORRECT_FIX.md`
`AGENT_*.md`	`AGENT_DESIGN_UPDATES.md`

例外：README.md、CHANGELOG.md、LICENSE.md 是真实的文档，必须保留。

根目录级别的测试脚本

根目录下的临时测试脚本，如 test_*.py，不属于测试套件（tests/ 目录中的才是）。将它们移动到 temp_docs_and_tests/：

文件	用途
`test_clear_tools.py`	一次性工具清理测试
`test_finemapping_tools.py`	临时工具验证
`test_metabolomics_tools.py`	临时工具验证
`test_original_bug.py`	错误复现
`test_pathway_tools.py`	临时工具验证
`test_protein_interaction_skill.py`	技能测试
`test_reload_fix.py`	错误复现
`test_round10_tools.py`	临时工具验证

其他排除的文件

.env - 包含密钥的环境变量
temp_docs_and_tests/ - 已在 .gitignore 中忽略
.claude/ - Claude Code 配置
__pycache__/、*.pyc - Python 字节码
.DS_Store - macOS 元数据

常见测试失败模式

模式 1：KeyError: 'role'

症状：访问消息字典时出现 KeyError: 'role'

修复：在 tu.run() 中添加 return_message=True 并使用 .get()：

messages = tu.run(calls, use_cache=True, return_message=True)
if msg.get("role") == "tool":

模式 2：Mock 对象不可下标访问

症状：TypeError: 'Mock' object is not subscriptable

修复：为 all_tool_dict 使用真实的字典并添加 _get_tool_instance：

mock_tu.all_tool_dict = {"Tool": mock_tool}
mock_tu._get_tool_instance = lambda name, cache=True: mock_tu.all_tool_dict.get(name)

模式 3：代码检查错误 (F841, E731)

修复 F841（未使用的变量）：使用 _ 前缀或 _ = func() 修复 E731（lambda 赋值）：用 def 替换

模式 4：Git 跟踪了临时文件

症状：git status 显示临时文件被修改/暂存

git rm -r --cached temp_docs_and_tests/
git rm --cached API_DISCOVERY_SESSION_SUMMARY.md
git commit -m "Remove temp files from tracking"

预提交钩子配置

项目使用 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    hooks: [end-of-file-fixer, trailing-whitespace, check-yaml, check-toml]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks: [ruff-check --fix, ruff-format]

范围：仅匹配 ^(ToolUniverse/)?src/tooluniverse/ 的文件

任务	命令
激活钩子	`pre-commit install`
运行所有测试	`pytest tests/ -x --tb=short -q`
运行特定测试	`pytest tests/path/test.py::Class::method -xvs`
检查暂存文件	`git status --short`
取消暂存文件	`git restore --staged <file>`
从跟踪中移除	`git rm --cached <file>`
移动临时文件	参见阶段 1 的命令
手动运行钩子	`pre-commit run --all-files`

推送前检查清单

每次推送前，请验证：

临时 Markdown 文件已从根目录移动到 temp_docs_and_tests/
根目录级别的 test_*.py 脚本已移动到 temp_docs_and_tests/
预提交钩子已安装 (pre-commit install)
所有测试在本地通过 (pytest tests/ -x)
没有代码检查错误
仅暂存了相关文件（没有 .env，没有临时文件）
提交信息清晰且具有描述性
选择了正确的分支

提交中绝不包含 AI 归属信息
绝不提交会话文档 Markdown 文件
使用 git add <specific-files> 而不是 git add .
编写清晰、专业的提交信息
每次提交只包含一个逻辑变更

🇺🇸English

DevTU GitHub Workflow

Safely push ToolUniverse code to GitHub by enforcing pre-push cleanup, pre-commit hooks, and test validation.

Instructions

When the user wants to push code, fix CI, or prepare a commit, follow this workflow:

Phase 1: Pre-Push Cleanup

Move temp files out of root - session docs and ad-hoc test scripts must NOT be pushed:

# Move session markdown files to temp_docs_and_tests/

for f in $(ls *.md 2>/dev/null | grep -v README.md | grep -v CHANGELOG.md | grep -v LICENSE.md); do
  mv "$f" temp_docs_and_tests/
done

# Move root-level test scripts to temp_docs_and_tests/
for f in $(ls test_*.py 2>/dev/null); do
  mv "$f" temp_docs_and_tests/
done

2. Verify nothing unwanted is staged :

git status --short

Red flags - these should NEVER be staged:

*_SUMMARY.md, *_REPORT.md, SESSION_*.md in root
test_*.py in root (these are ad-hoc scripts, not real tests)
.env or credential files
temp_docs_and_tests/ contents

Phase 2: Activate Pre-Commit Hooks

Ensure pre-commit is installed and active :

pre-commit install

This enables automatic checks on every git commit:

ruff check --fix - Python linting with auto-fix
ruff format - Code formatting
YAML/TOML validation
Trailing whitespace removal
End of file fixes

Verify hooks are active :

ls -la .git/hooks/pre-commit

Phase 3: Run Tests

Run the full test suite locally :

python -m pytest tests/ -x --tb=short -q

If tests fail , diagnose using the error patterns below and fix before proceeding.

Phase 4: Commit and Push

Stage only specific files (never use git add . or git add -A):

git add src/tooluniverse/specific_file.py tests/specific_test.py

Commit (pre-commit hooks run automatically):

git commit -m "Clear, descriptive message"

Rebase onto latest main BEFORE pushing (CRITICAL — prevents PR conflicts):

git fetch origin

git stash            # stash any uncommitted work
git rebase origin/main
git stash pop        # restore uncommitted work

If rebase conflicts arise, resolve them (keep our newer changes), then:

git add <conflicted-file>
git rebase --continue

10. Push (force-with-lease after a rebase):

git push --force-with-lease origin <branch-name>

After pushing, verify the PR is conflict-free:

gh pr view <PR-number> --json mergeable,mergeStateStatus
# Must show: "mergeable":"MERGEABLE"

Files That Must NEVER Be Pushed

Temp Session Documents (Root-Level .md)

These are session notes created during development. Move to temp_docs_and_tests/ before committing:

Pattern	Example
`*_SUMMARY.md`	`API_DISCOVERY_SESSION_SUMMARY.md`
`*_REPORT.md`	`SKILL_TESTING_REPORT.md`, `TOOLUNIVERSE_BUG_REPORT.md`
`SESSION_*.md`	`SESSION_2026_02_13.md`
`IMPLEMENTATION_*.md`

Exception : README.md, CHANGELOG.md, LICENSE.md are real docs and MUST stay.

Root-Level Test Scripts

Ad-hoc test scripts like test_*.py in root are NOT part of the test suite (tests/ directory is). Move them to temp_docs_and_tests/:

File	Purpose
`test_clear_tools.py`	One-off tool cleanup test
`test_finemapping_tools.py`	Ad-hoc tool validation
`test_metabolomics_tools.py`	Ad-hoc tool validation
`test_original_bug.py`	Bug reproduction
`test_pathway_tools.py`	Ad-hoc tool validation
`test_protein_interaction_skill.py`

Other Excluded Files

.env - Environment variables with secrets
temp_docs_and_tests/ - Already in .gitignore
.claude/ - Claude Code configuration
__pycache__/, *.pyc - Python bytecode
.DS_Store - macOS metadata

Common Test Failure Patterns

Pattern 1: KeyError: 'role'

Symptom : KeyError: 'role' when accessing message dicts

Fix : Add return_message=True to tu.run() and use .get():

messages = tu.run(calls, use_cache=True, return_message=True)
if msg.get("role") == "tool":

Pattern 2: Mock Not Subscriptable

Symptom : TypeError: 'Mock' object is not subscriptable

Fix : Use real dicts for all_tool_dict and add _get_tool_instance:

mock_tu.all_tool_dict = {"Tool": mock_tool}
mock_tu._get_tool_instance = lambda name, cache=True: mock_tu.all_tool_dict.get(name)

Pattern 3: Linting Errors (F841, E731)

Fix F841 (unused variable): Use _ prefix or _ = func() Fix E731 (lambda assignment): Replace with def

Pattern 4: Temp Files Tracked by Git

Symptom : git status shows temp files as modified/staged

Fix :

git rm -r --cached temp_docs_and_tests/
git rm --cached API_DISCOVERY_SESSION_SUMMARY.md
git commit -m "Remove temp files from tracking"

Pre-Commit Hook Configuration

The project uses .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    hooks: [end-of-file-fixer, trailing-whitespace, check-yaml, check-toml]
  - repo: https://github.com/astral-sh/ruff-pre-commit
    hooks: [ruff-check --fix, ruff-format]

Scope: Only files matching ^(ToolUniverse/)?src/tooluniverse/

Quick Reference

Task	Command
Activate hooks	`pre-commit install`
Run all tests	`pytest tests/ -x --tb=short -q`
Run specific test	`pytest tests/path/test.py::Class::method -xvs`
Check staged files	`git status --short`
Unstage a file	`git restore --staged <file>`
Remove from tracking	`git rm --cached <file>`

Pre-Push Checklist

Before every push, verify:

Temp markdown files moved from root to temp_docs_and_tests/
Root-level test_*.py scripts moved to temp_docs_and_tests/
Pre-commit hooks installed (pre-commit install)
All tests pass locally (pytest tests/ -x)
No linting errors
Only relevant files staged (no .env, no temp files)
Commit message is clear and descriptive
Correct branch selected

Git Commit Guidelines

Never include AI attribution in commits
Never commit session documentation markdown files
Use git add <specific-files> instead of git add .
Write clean, professional commit messages
One logical change per commit

Weekly Installs

133

Repository

mims-harvard/to…universe

GitHub Stars

1.2K

First Seen

Feb 16, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

codex128

opencode128

gemini-cli127

github-copilot126

cursor123

kimi-cli122

Skills CLI 使用指南：AI Agent 技能包管理器安装与管理教程

43,100 周安装