devtu-github

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DevTU GitHub Workflow

DevTU GitHub 工作流

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

通过执行推送前清理、激活pre-commit钩子和测试验证，安全地将ToolUniverse代码推送到GitHub。

Instructions

操作说明

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

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

Phase 1: Pre-Push Cleanup

阶段1：推送前清理

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

bash

undefined

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

bash

undefined

Move session markdown files to temp_docs_and_tests/

将会话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

Move root-level test scripts to temp_docs_and_tests/

将根目录下的测试脚本移动到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**:

```bash
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

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/
```
目录下的内容

Phase 2: Activate Pre-Commit Hooks

阶段2：激活Pre-Commit钩子

Ensure pre-commit is installed and active:

bash

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:

bash

ls -la .git/hooks/pre-commit

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

bash

pre-commit install

这会在每次

git commit

时自动执行检查：

```
ruff check --fix
```
- 自动修复的Python代码检查
```
ruff format
```
- 代码格式化
YAML/TOML验证
移除尾随空格
修复文件结尾格式

验证钩子已激活：

bash

ls -la .git/hooks/pre-commit

Phase 3: Run Tests

阶段3：运行测试

Run the full test suite locally:

bash

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

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

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

bash

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

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

Phase 4: Commit and Push

阶段4：提交并推送

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

bash

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

Commit (pre-commit hooks run automatically):

bash

git commit -m "Clear, descriptive message"

Push:

bash

git push origin <branch-name>

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

bash

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

提交（pre-commit钩子会自动运行）：

bash

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

推送：

bash

git push origin <branch-name>

Files That Must NEVER Be Pushed

绝对不能推送的文件

Temp Session Documents (Root-Level .md)

临时会话文档（根目录下的.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`	`IMPLEMENTATION_COMPLETE.md`
`BUG_ANALYSIS_*.md`	`BUG_ANALYSIS_DETAILED.md`
`FIX_*.md`	`FIX_SUMMARY.md` , `CORRECT_FIX.md`
`AGENT_*.md`	`AGENT_DESIGN_UPDATES.md`

Exception:

README.md

CHANGELOG.md

LICENSE.md

are real docs and MUST stay.

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

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

是正式文档，必须保留在根目录。

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`	Skill test
`test_reload_fix.py`	Bug reproduction
`test_round10_tools.py`	Ad-hoc tool validation

根目录下的临时测试脚本如

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`	Skill测试
`test_reload_fix.py`	复现Bug
`test_round10_tools.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

```
.env
```
- 包含密钥的环境变量文件
```
temp_docs_and_tests/
```
- 已在.gitignore中配置
```
.claude/
```
- Claude Code配置目录
```
__pycache__/
```
,
```
*.pyc
```
- Python字节码文件
```
.DS_Store
```
- macOS元数据文件

Common Test Failure Patterns

常见测试失败模式

Pattern 1: KeyError: 'role'

模式1：KeyError: 'role'

Symptom:

KeyError: 'role'

when accessing message dicts

Fix: Add

return_message=True

tu.run()

and use

.get()

python

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

症状：访问消息字典时出现

KeyError: 'role'

修复方案：在

tu.run()

中添加

return_message=True

并使用

.get()

方法：

python

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

Pattern 2: Mock Not Subscriptable

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

Symptom:

TypeError: 'Mock' object is not subscriptable

Fix: Use real dicts for

all_tool_dict

and add

_get_tool_instance

python

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

症状：

TypeError: 'Mock' object is not subscriptable

修复方案：为

all_tool_dict

使用真实字典，并添加

_get_tool_instance

方法：

python

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)

模式3：代码检查错误（F841, E731）

Fix F841 (unused variable): Use

prefix or

_ = func()

Fix E731 (lambda assignment): Replace with

def

修复F841（未使用变量）：使用

前缀或

_ = func()

修复E731（lambda赋值）：替换为

def

定义

Pattern 4: Temp Files Tracked by Git

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

Symptom:

git status

shows temp files as modified/staged

Fix:

bash

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

症状：

git status

显示临时文件已被修改/暂存

修复方案：

bash

git rm -r --cached temp_docs_and_tests/
git rm --cached API_DISCOVERY_SESSION_SUMMARY.md
git commit -m "停止跟踪临时文件"

Pre-Commit Hook Configuration

Pre-Commit钩子配置

The project uses

.pre-commit-config.yaml

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/

项目使用

.pre-commit-config.yaml

文件：

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/

的文件

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>`
Move temp files	See Phase 1 commands
Run hooks manually	`pre-commit run --all-files`

任务	命令
激活钩子	`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`

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

每次推送前，请验证：

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

Git Commit Guidelines

Git提交规范

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

提交信息中不要包含AI相关署名
不要提交会话文档markdown文件
使用
```
git add <specific-files>
```
代替
```
git add .
```
编写清晰、专业的提交信息
每次提交只包含一个逻辑变更