Skip to content

JiuwenSwarm is an intelligent AI Agent built on openJiuwen. It extends the powerful capabilities of large language models directly to your fingertips through various communication apps you use daily.

Python
12.4 KB
Raw Blame
# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.

"""FlashSubagentRail 单元测试:spec 自注入 + flash 调优文案 + 机制复用。

锁定五点:
1. spec 自注入:开关开 → 注入 general-purpose spec 并注册 task_tool
   (flash 专属路径,绕过 interface_deep 的 mode 门控);已有非 gp spec
   (research/browser/自定义 agent)时共存注入、原 spec 保留——修复
   「subagents 非空即静默不注入 gp」与 agent 模式同配置行为分叉的问题;
2. 开关关(react.subagents.general_agent.enabled 非 true)→ 跳过注册;
3. 工具卡描述与系统提示段为 flash 调优版(并行规则无条件、无强制委派条款),
   refresh_available_agents 刷新后不回退;
4. 已含 general-purpose spec(热重载路径)→ helper 按名去重,不重复注入;
5. CR-1 回归:flash 适配器 ``_build_subagent_rail`` 必须接受 rail 表注册时
   传入的 ``config_base`` 关键字参数(与 ``_build_task_planning_rail`` 同理),
   否则冷启动经 ``_instantiate_rails`` 构建时抛 TypeError。
"""

from __future__ import annotations

from types import SimpleNamespace

import pytest

from jiuwenswarm.agents.harness.flash.rails.flash_subagent_rail import (
    FlashSubagentRail,
)
from openjiuwen.core.single_agent.schema.agent_card import AgentCard
from openjiuwen.harness.prompts.sections import SectionName
from openjiuwen.harness.schema.config import SubAgentConfig


class _FakeBuilder:
    def __init__(self, language: str = "cn") -> None:
        self.language = language
        self.sections: list = []

    def add_section(self, section) -> None:
        self.sections = [s for s in self.sections if s.name != section.name]
        self.sections.append(section)

    def remove_section(self, name) -> None:
        self.sections = [s for s in self.sections if s.name != name]


class _FakeAbilityManager:
    def __init__(self) -> None:
        self.cards: dict = {}

    def add_ability(self, card, tool) -> None:
        self.cards[card.name] = card


class _FakeAgent:
    def __init__(self, subagents: list) -> None:
        self.deep_config = SimpleNamespace(subagents=list(subagents))
        self.ability_manager = _FakeAbilityManager()
        self.system_prompt_builder = _FakeBuilder()


def _make_rail(agent: _FakeAgent, inject: bool = True) -> FlashSubagentRail:
    """走真实构造(含父类全量属性),避免绕过 __init__ 后漏掉
    agent-core 新版 SubagentRail 增设的属性(enable_subagent_runtime 等)。"""
    rail = FlashSubagentRail(inject_general_purpose=inject)
    rail.init(agent)
    return rail


def _gp_spec() -> SubAgentConfig:
    """已存在的 general-purpose spec(真 SubAgentConfig,helper 去重可识别)。"""
    return SubAgentConfig(
        agent_card=AgentCard(name="general-purpose", description="通用测试子代理"),
        system_prompt="",
    )


def _research_spec() -> SubAgentConfig:
    """非 gp spec:模拟冷启动产物(research/browser/自定义 agent)。"""
    return SubAgentConfig(
        agent_card=AgentCard(name="research_agent", description="研究测试子代理"),
        system_prompt="",
    )


class TestSpecSelfInjection:
    def test_injects_when_empty_and_enabled(self) -> None:
        """空 subagents + 开关开 → 注入 spec 并注册 task_tool(flash 核心路径)。"""
        agent = _FakeAgent([])
        rail = _make_rail(agent, inject=True)

        assert rail.tools, "注入后必须注册工具"
        assert "task_tool" in agent.ability_manager.cards
        # deep_config.subagents 被注入 general-purpose spec
        specs = agent.deep_config.subagents
        assert len(specs) == 1
        assert isinstance(specs[0], SubAgentConfig)
        assert specs[0].agent_card.name == "general-purpose"

    def test_injects_alongside_existing_non_gp_specs(self) -> None:
        """P1 回归:已有非 gp spec(research/browser/自定义 agent)时 gp 仍注入。

        修复前 init 只在 subagents 为空时注入——冷启动带 research/browser/
        自定义 agent 的 flash 会话静默丢失 general-purpose(general_agent
        .enabled=true 被无视),且与 agent 模式同配置行为分叉(agent 模式
        gp 会追加进现有列表)。
        """
        existing = _research_spec()
        agent = _FakeAgent([existing])
        _make_rail(agent, inject=True)

        specs = agent.deep_config.subagents
        names = [spec.agent_card.name for spec in specs]
        # gp 注入头部(helper insert(0)),原 spec 保留
        assert names[0] == "general-purpose"
        assert names.count("general-purpose") == 1
        assert "research_agent" in names
        assert any(spec is existing for spec in specs)
        # task_tool 注册成功,可用类型同时含两种
        assert "task_tool" in agent.ability_manager.cards
        card = agent.ability_manager.cards["task_tool"]
        assert "general-purpose" in card.description
        assert "research_agent" in card.description

    def test_skips_when_disabled(self) -> None:
        """开关关(config 显式非 true)→ 不注入、不注册(对齐 stock 门控语义)。"""
        agent = _FakeAgent([])
        rail = _make_rail(agent, inject=False)

        assert not rail.tools
        assert not agent.deep_config.subagents
        assert "task_tool" not in agent.ability_manager.cards

    def test_no_double_injection_when_spec_exists(self) -> None:
        """已含 general-purpose spec(如热重载路径注入过)→ helper 按名去重,不重复注入。"""
        existing = _gp_spec()
        agent = _FakeAgent([existing])
        _make_rail(agent, inject=True)

        specs = agent.deep_config.subagents
        assert len(specs) == 1
        assert specs[0] is existing


class TestFlashDescriptions:
    def test_registers_and_rewrites_description(self) -> None:
        agent = _FakeAgent([_gp_spec()])
        _make_rail(agent)

        card = agent.ability_manager.cards.get("task_tool")
        assert card is not None, "task_tool 必须注册到 ability_manager"
        # flash 调优描述:并行规则无条件存在
        assert "必须在同一条消息中一次性发出全部 task_tool 调用" in card.description
        # available_agents 已格式化进描述
        assert "general-purpose" in card.description
        assert "{available_agents}" not in card.description
        # 不携带 stock 描述的标志性强制条款
        assert "永远不要委托理解" not in card.description

    def test_available_agents_lists_real_tool_face(self) -> None:
        """回归:available_agents 必须列出 rail 继承的文件/bash 工具。

        stock 构建只列 spec.tools(卡片),漏掉 rail 注册的文件工具,导致
        模型误判「子代理没有 read_file/bash」而放弃委派、全单干。
        CR-2 后文案与实际注册严格一致:不再宣称 todo/memory(对应 rail
        不在 spec 注入范围内),文件/bash 工具保留。
        """
        agent = _FakeAgent([_gp_spec()])
        _make_rail(agent)
        card = agent.ability_manager.cards["task_tool"]

        for tool_name in ("read_file", "write_file", "edit_file", "glob", "grep", "bash"):
            assert tool_name in card.description, (
                f"available_agents 必须包含 rail 继承工具 {tool_name}"
            )
        # 语义化能力声明(CLI/文件/调研)
        assert "执行 CLI 命令" in card.description
        # CR-2:不再虚报 todo / memory(对应 rail 不在 gp spec 注入范围)
        assert "todo" not in card.description
        assert "memory" not in card.description

    def test_subagent_spec_gets_flash_filesystem_rail(self) -> None:
        """CR-2 回归:gp spec 的 rails 字段必须包含 SlimSysOperationRail。

        冷启动时 cfg.rails 恒 None(rails 进 _pending_rails 不写
        deep_config),直接依赖会走 stock SysOperationRail fallback——
        gp 子代理获得 list_files/powershell 等主代理没有的工具。
        修复后 _inject_general_purpose_spec 主动构造 flash 变体传入。
        """
        from openjiuwen.harness.rails.sys_operation_rail import SysOperationRail
        from jiuwenswarm.agents.harness.flash import SlimSysOperationRail

        agent = _FakeAgent([])
        rail = _make_rail(agent, inject=True)

        specs = agent.deep_config.subagents
        assert len(specs) == 1
        gp_spec = specs[0]
        # spec 的 rails 字段包含 SlimSysOperationRail(flash 变体)
        spec_rails = getattr(gp_spec, "rails", None) or []
        assert any(isinstance(r, SlimSysOperationRail) for r in spec_rails), (
            "gp spec rails must include SlimSysOperationRail (flash variant), "
            f"got {[type(r).__name__ for r in spec_rails]}"
        )
        # 不含 stock SysOperationRail(flash 变体已满足 isinstance 检查,
        # 工厂不会再 fallback)
        assert not any(
            type(r) is SysOperationRail for r in spec_rails
        ), "gp spec rails should not contain stock SysOperationRail"

    def test_refresh_keeps_flash_description(self) -> None:
        agent = _FakeAgent([_gp_spec()])
        rail = _make_rail(agent)
        card = agent.ability_manager.cards["task_tool"]

        # DisabledToolsRail 刷新路径:不得回退为 stock 文案
        rail.refresh_available_agents(agent)
        assert "必须在同一条消息中一次性发出全部 task_tool 调用" in card.description
        assert "永远不要委托理解" not in card.description
        assert "read_file" in card.description


class TestFlashSection:
    @pytest.mark.asyncio
    async def test_before_model_call_injects_flash_section(self) -> None:
        agent = _FakeAgent([_gp_spec()])
        rail = _make_rail(agent)

        await rail.before_model_call(SimpleNamespace())
        builder: _FakeBuilder = agent.system_prompt_builder
        assert builder.sections, "必须注入 task_tool 提示段"
        section = builder.sections[-1]
        assert section.name == SectionName.TASK_TOOL
        content = section.content["cn"]
        # flash 段标志:按上下文压力判断 + 无条件并行 + 单干快路径 carve-out
        assert "按上下文压力判断" in content
        assert "在同一条消息中一次性发出全部 task_tool 调用" in content
        assert "直接执行更快" in content
        # 不携带 stock 段的强制委派条款(强模型拖慢源)
        assert "必须委派独立子代理处理,不得用 read_file 自行逐篇读取" not in content

    @pytest.mark.asyncio
    async def test_no_tools_no_section(self) -> None:
        agent = _FakeAgent([])
        rail = _make_rail(agent, inject=False)
        await rail.before_model_call(SimpleNamespace())
        assert not agent.system_prompt_builder.sections


class TestFlashCopyConstants:
    def test_bilingual_copies_present(self) -> None:
        from jiuwenswarm.agents.harness.flash.rails.flash_subagent_rail import (
            FLASH_TASK_SECTION,
            FLASH_TASK_TOOL_DESCRIPTION,
        )

        assert set(FLASH_TASK_SECTION) >= {"cn", "en"}
        assert set(FLASH_TASK_TOOL_DESCRIPTION) >= {"cn", "en"}
        for text in FLASH_TASK_SECTION.values():
            assert "task_tool" in text
        for text in FLASH_TASK_TOOL_DESCRIPTION.values():
            assert "{available_agents}" in text


class TestRailTableConstruction:
    def test_build_subagent_rail_accepts_config_base_kwarg(self) -> None:
        """CR-1 回归:flash ``_build_subagent_rail`` 必须接受 ``config_base``。

        冷启动 rail 表注册带 ``{"config_base": config_base}`` params,经
        ``_instantiate_rails`` 以 ``build_func(**info.params)`` 关键字调用;
        签名不匹配会抛 ``TypeError: unexpected keyword argument``,导致
        flash 会话冷启动 100% 失败(参考 review CR-1)。
        """
        from jiuwenswarm.server.runtime.agent_adapter.interface_flash import (
            JiuwenSwarmFlashAdapter,
        )

        adapter = JiuwenSwarmFlashAdapter()
        # 直接以关键字参数调用,模拟 _instantiate_rails 的调用方式
        rail = adapter._build_subagent_rail(config_base={"react": {}})
        assert isinstance(rail, FlashSubagentRail)

        # 无参调用也应兼容(旧路径 / 测试直接构建)
        rail_no_args = adapter._build_subagent_rail()
        assert isinstance(rail_no_args, FlashSubagentRail)