devtu-self-evolve

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ToolUniverse Self-Evolution Orchestrator

ToolUniverse自进化编排器

Coordinates the full development lifecycle by dispatching to specialized devtu skills.

通过调度专用的devtu技能协调整个开发生命周期。

The Cycle

循环流程

Discover → Create → Test → Fix → Optimize → Ship → Repeat

Each phase maps to a dedicated skill:

Phase	Skill	What it does
Discover	`devtu-auto-discover-apis`	Gap analysis, web search for APIs, batch discovery
Create	`devtu-create-tool`	Build tool class + JSON config + test examples
Test	(this skill)	Launch researcher persona agents to find issues
Fix	`devtu-fix-tool`	Diagnose failures, implement fixes, validate
Optimize	`devtu-optimize-skills`	Improve skill reports, evidence handling, UX
Optimize	`devtu-optimize-descriptions`	Improve tool JSON descriptions for clarity
Docs	`devtu-docs-quality`	Validate documentation accuracy
Ship	`devtu-github`	Branch, commit, push, create PR

Discover → Create → Test → Fix → Optimize → Ship → Repeat

每个阶段对应一个专用技能：

阶段	技能	功能
发现（Discover）	`devtu-auto-discover-apis`	缺口分析、API网页搜索、批量发现
创建（Create）	`devtu-create-tool`	构建工具类 + JSON配置 + 测试示例
测试（Test）	(本技能)	启动研究员角色Agent来排查问题
修复（Fix）	`devtu-fix-tool`	诊断故障、实现修复、验证效果
优化（Optimize）	`devtu-optimize-skills`	完善技能报告、证据处理、UX
优化（Optimize）	`devtu-optimize-descriptions`	优化工具JSON描述的清晰度
文档（Docs）	`devtu-docs-quality`	验证文档准确性
发布（Ship）	`devtu-github`	分支创建、提交、推送、创建PR

Quick Start

快速入门

Pick an entry point based on what's needed:

"Run a test round" → jump to Testing Phase
"Expand coverage" → invoke
```
Skill(skill="devtu-auto-discover-apis")
```
"Create a new tool" → invoke
```
Skill(skill="devtu-create-tool")
```
"Fix a broken tool" → invoke
```
Skill(skill="devtu-fix-tool")
```
"Improve skills" → invoke
```
Skill(skill="devtu-optimize-skills")
```
"Full cycle" → follow all phases below in order

根据需求选择入口点：

"运行一轮测试" → 跳转至测试阶段
"扩展覆盖范围" → 调用
```
Skill(skill="devtu-auto-discover-apis")
```
"创建新工具" → 调用
```
Skill(skill="devtu-create-tool")
```
"修复损坏的工具" → 调用
```
Skill(skill="devtu-fix-tool")
```
"改进技能" → 调用
```
Skill(skill="devtu-optimize-skills")
```
"完整周期" → 按顺序执行以下所有阶段

Phase 1: Discovery (optional)

阶段1：发现（可选）

Invoke

Skill(skill="devtu-auto-discover-apis")

to:

Run gap analysis on current tool categories
Search for life science APIs in underrepresented domains
Score and prioritize APIs by coverage, reliability, documentation

调用

Skill(skill="devtu-auto-discover-apis")

完成以下操作：

对现有工具类别进行缺口分析
搜索覆盖不足领域的生命科学API
按覆盖范围、可靠性、文档质量对API打分并排序优先级

Phase 2: Tool Creation (optional)

阶段2：工具创建（可选）

Invoke

Skill(skill="devtu-create-tool")

for each new API:

Create Python tool class implementing the API
Create JSON config with parameters, descriptions, test examples

_lazy_registry_static.py

and

default_config.py

Validate:

python -m tooluniverse.cli test <ToolName>

为每个新API调用

Skill(skill="devtu-create-tool")

完成以下操作：

创建实现API功能的Python工具类
创建包含参数、描述、测试示例的JSON配置

在

_lazy_registry_static.py

和

default_config.py

中注册

验证：

python -m tooluniverse.cli test <ToolName>

Phase 3: Testing Phase

阶段3：测试阶段

This is the core testing loop, run directly by this skill.

这是核心测试循环，由本技能直接运行。

Setup

准备工作

Check for open PRs:
```
gh pr list --state open
```
If unmerged PR → use that branch; if merged → new branch from
```
origin/main
```

Rebase:

git fetch origin && git rebase origin/main

检查未合并的PR：
```
gh pr list --state open
```
如果存在未合并PR → 使用对应分支；如果已合并 → 从
```
origin/main
```
创建新分支

变基：

git fetch origin && git rebase origin/main

Researcher Persona Agents

研究员角色Agent

Launch 2 agents per round (A + B) using the Agent tool with these parameters:

Each agent gets:

Domain specialty (oncology, genomics, pharmacology, etc.)
Research question (specific biological question)
5-7 test scenarios exercising different tools
Instructions to report issues with severity (HIGH/MEDIUM/LOW)

Issue IDs:

Feature-{round}{letter}-{num}

(e.g.,

Feature-59A-001

)

Agent prompt template — see references/persona-template.md

每轮测试启动2个Agent（A + B），使用Agent工具传入以下参数：

每个Agent的配置：

领域专长（肿瘤学、基因组学、药理学等）
研究问题（具体的生物学问题）
5-7个覆盖不同工具的测试场景
按严重程度（高/中/低）上报问题的说明

问题ID规则：

Feature-{轮次}{字母}-{编号}

（例如

Feature-59A-001

）

Agent提示词模板 参考 references/persona-template.md

Verification (CRITICAL)

验证（关键步骤）

Before implementing ANY agent-reported issue, verify via CLI:

bash

python3 -m tooluniverse.cli run <ToolName> '<json_args>'

50%+ of agent reports are false positives from MCP interface confusion. Only fix verified issues.

在处理任何Agent上报的问题前，先通过CLI验证：

bash

python3 -m tooluniverse.cli run <ToolName> '<json_args>'

超过50%的Agent上报问题是MCP接口混淆导致的误报，仅修复验证通过的问题。

Fix Principles

修复原则

Prevent, don't recover — fix root cause, not symptoms
Validate at input — reject bad params early with clear guidance
Distinguish "no data" from "bad query" — different messages for each
Fix the abstraction — don't add alias lists that grow forever

Anti-patterns: hint text instead of validation, parameter aliases instead of fixing naming, post-hoc probing instead of pre-validation.

预防而非补救 — 修复根本原因，而非表面症状
输入侧验证 — 尽早拦截无效参数并给出清晰提示
区分"无数据"和"查询错误" — 为两种场景返回不同提示
修复抽象层问题 — 不要维护会无限增长的别名列表

反模式：用提示文本代替验证、用参数别名代替命名修复、用事后探测代替前置验证。

Phase 4: Fix & Commit

阶段4：修复与提交

Implement verified fixes (see references/bug-patterns.md for code-level patterns)
Run code-simplifier:
```
Skill(skill="simplify")
```
— always after writing or modifying code
Lint:
```
ruff check src/tooluniverse/<file>.py
```

Verify syntax:

python -c "from tooluniverse.<module> import <Class>"

Test:

python -m tooluniverse.cli run <Tool> '<json>'

Pre-commit hook pattern: stage → commit (fails, reformats) → re-stage → commit
Push:
```
git push origin <branch>
```

Also see
Skill(skill="devtu-code-optimization")
for reusable fix patterns and anti-patterns.

实现验证通过的修复（代码级模式参考 references/bug-patterns.md）
运行代码简化工具：
```
Skill(skill="simplify")
```
— 编写或修改代码后必须执行
代码检查：
```
ruff check src/tooluniverse/<file>.py
```

语法验证：

python -c "from tooluniverse.<module> import <Class>"

功能测试：

python -m tooluniverse.cli run <Tool> '<json>'

Pre-commit钩子流程：暂存 → 提交（失败会自动格式化）→ 重新暂存 → 提交
推送：
```
git push origin <分支名>
```

可复用修复模式和反模式也可参考
Skill(skill="devtu-code-optimization")

Phase 5: Optimize (optional)

阶段5：优化（可选）

After fixes are stable:

Skill(skill="devtu-optimize-descriptions")

— improve tool descriptions

```
Skill(skill="devtu-optimize-skills")
```
— improve research skill quality
```
Skill(skill="devtu-docs-quality")
```
— validate docs accuracy

修复稳定后执行：

Skill(skill="devtu-optimize-descriptions")

— 优化工具描述

```
Skill(skill="devtu-optimize-skills")
```
— 提升研究技能质量
```
Skill(skill="devtu-docs-quality")
```
— 验证文档准确性

Phase 6: Ship

阶段6：发布

Invoke

Skill(skill="devtu-github")

or manually:

Rebase:

git fetch origin && git stash && git rebase origin/main && git stash pop

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

Create or update PR:

gh pr create

/ verify with

gh pr view <N> --json mergeable

Verify
```
"mergeable": "MERGEABLE"
```
before reporting done

GitHub repo:

mims-harvard/ToolUniverse

— always verify with

git remote -v

before pushing.

调用

Skill(skill="devtu-github")

或手动执行：

变基：

git fetch origin && git stash && git rebase origin/main && git stash pop

git push --force-with-lease origin <分支名>

创建或更新PR：

gh pr create

/ 用

gh pr view <N> --json mergeable

验证状态

上报完成前确认
```
"mergeable": "MERGEABLE"
```

GitHub仓库：

mims-harvard/ToolUniverse

— 推送前务必用

git remote -v

验证仓库地址。

Git Rules (CRITICAL)

Git规则（关键）

NEVER push to main — all work on feature branches
NEVER have multiple open fix PRs — keep adding to current branch

Always rebase before push:

git fetch origin && git rebase origin/main

Commit message format: no "BUG" terminology, use "Feature" or "Fix"
No AI attribution in commits

绝对不要直接推送到main分支 — 所有工作都在特性分支完成
不要同时开启多个修复PR — 所有修改都提交到当前分支

推送前必须变基：

git fetch origin && git rebase origin/main

提交信息格式：不要使用"BUG"术语，用"Feature"或"Fix"
提交信息中不要出现AI归属声明

Common Issue Categories

常见问题分类

Category	Signal
Silent parameter miss	Wrong-field check; param ignored
Always-fires conditional	`.get("field")` on wrong type
Silent normalization	Auto-transform not disclosed
Wrong notation/case	Gene fusions, Title Case names
Substring match	Short symbol returns multiple targets
try/except indent	Mismatched → SyntaxError

Full patterns → references/bug-patterns.md

分类	特征
静默参数丢失	字段检查错误、参数被忽略
条件判断恒成立	对错误类型调用 `.get("field")`
静默归一化	未披露的自动转换逻辑
符号/大小写错误	基因融合、驼峰命名错误
子串匹配问题	短符号查询返回多个匹配结果
try/except缩进错误	缩进不匹配 → 语法错误

完整模式参考 → references/bug-patterns.md