devtu-github

DevTU GitHub 工作流

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

说明

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

阶段 1：推送前清理

1. 将临时文件移出根目录——会话文档和临时测试脚本不得推送：

# 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. 确认暂存区中没有不需要的文件：

git status --short

警示项——以下文件绝不能暂存：

• 根目录中的 *_SUMMARY.md、*_REPORT.md、SESSION_*.md
• 根目录中的 test_*.py（这些是临时脚本，不是真正的测试）
• .env 或凭据文件
• temp_docs_and_tests/ 中的内容

阶段 2：启用提交前钩子

3. 确保已安装并启用 pre-commit：

pre-commit install

这样每次执行 git commit 时都会自动运行检查：

• ruff check --fix - Python 代码 lint 检查并自动修复
• ruff format - 代码格式化
• YAML/TOML 验证
• 删除行尾空格
• 修复文件末尾格式

4. 确认钩子已启用：

ls -la .git/hooks/pre-commit

阶段 3：运行测试

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

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

6. 如果测试失败，请根据下方的错误模式进行诊断并修复，然后再继续。

阶段 4：提交并推送

7. 仅暂存指定文件（绝不要使用 git add . 或 git add -A）：

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

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

git commit -m "Clear, descriptive message"

9. 推送前先变基到最新的 main（至关重要——可避免 PR 冲突）：

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

如果发生变基冲突，请解决冲突（保留我们较新的更改），然后：

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

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

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

推送后，确认 PR 没有冲突：

gh pr view <PR-number> --json mergeable,mergeStateStatus
# Must show: "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	重现 Bug
test_pathway_tools.py	临时工具验证
test_protein_interaction_skill.py	技能测试
test_reload_fix.py	重现 Bug
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：Lint 错误（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 Hook 配置

项目使用 .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 钩子（pre-commit install）
• 所有测试均在本地通过（pytest tests/ -x）
• 没有 lint 错误
• 仅暂存相关文件（不包含 .env 和临时文件）
• 提交说明清晰明确
• 已选择正确的分支

Git 提交指南

• 提交中绝不包含 AI 署名
• 绝不提交会话文档 Markdown 文件
• 使用 git add <specific-files>，而不是 git add .
• 编写简洁、专业的提交说明
• 每次提交只包含一个逻辑变更