refactor(auto_resource): simplify shared agent interpretation

This commit is contained in:
wang-qisen 2026-09-16 15:31:48 +08:00
parent abc7ecb6ad
commit ed05a2af67
5 changed files with 98 additions and 203 deletions

View file

@ -345,7 +345,7 @@ class AutoImageResourceStep(BaseAutoResourceStep):
name="image",
),
]
await self._interpret_resource(
note_path = await self._interpret_resource(
file_path,
date_str,
note_stem,
@ -353,6 +353,7 @@ class AutoImageResourceStep(BaseAutoResourceStep):
"The resource is the image attached above. Follow its interpretation and note-format instructions.",
input_blocks=blocks,
note_metadata={"kind": "image", "media_type": payload["source_mime"]},
required_prefix=f"![[{file_path}]]",
)
if note_path is None:
raise RuntimeError("Resource agent did not write a note")
self.context.response.metadata["media_type"] = payload["source_mime"]

View file

@ -1,16 +1,14 @@
"""Shared lifecycle and helpers for automatic resource processors."""
import asyncio
import hashlib
import re
import uuid
from abc import abstractmethod
from collections.abc import Mapping
from contextlib import contextmanager
from dataclasses import dataclass, field
from datetime import datetime
from pathlib import Path, PurePosixPath
from typing import Any
import uuid
import frontmatter
from agentscope.message import DataBlock, TextBlock, UserMsg
@ -75,6 +73,11 @@ def _compute_note_stem(filename: str) -> str:
return PurePosixPath(filename).stem
def _compute_agent_session_id(path: str) -> str:
"""Return a stable UUID session id for agent backends."""
return str(uuid.uuid5(uuid.NAMESPACE_URL, path))
def _parse_resource_path(file_path: str, resource_dir: str) -> tuple[str, str]:
"""Extract (date, filename) from a resource path like 'resource/2026-06-06/report.pdf'.
@ -146,6 +149,11 @@ class BaseAutoResourceStep(BaseStep):
resource_suffixes: frozenset[str] = frozenset()
router_inherit_keys = frozenset({"file_store", "language"})
def __init__(self, **kwargs):
super().__init__(**kwargs)
self.create_tools: list[str] = ["write"]
self.update_tools: list[str] = ["read", "edit", "frontmatter_update", "write"]
@classmethod
def matches_change(cls, change: Mapping[str, Any]) -> bool:
"""Return whether this processor accepts a change before fallback.
@ -362,8 +370,7 @@ class BaseAutoResourceStep(BaseStep):
*,
input_blocks: list[TextBlock | DataBlock] | None = None,
note_metadata: dict | None = None,
required_prefix: str = "",
) -> None:
) -> str | None:
"""Run the same note-writing agent for text and native multimodal inputs."""
state = await self._prepare_resource_note(day, file_path, note_stem)
prompt = self.prompt_format(
@ -377,65 +384,44 @@ class BaseAutoResourceStep(BaseStep):
date=day,
)
inputs = UserMsg(name="user", content=[*input_blocks, TextBlock(text=prompt)]) if input_blocks else prompt
session_id = str(uuid.uuid5(uuid.NAMESPACE_URL, file_path))
session_id = _compute_agent_session_id(file_path)
self.logger.info(f"[{self.name}] agent start file_path={file_path} note_path={state.path}")
note_path = state.path
agent_finished = False
try:
result = await self.agent_wrapper.reply(
inputs,
system_prompt=self.prompt_format("system_prompt"),
job_tools=["write"] if state.created else ["read", "edit", "frontmatter_update", "write"],
injected_job_kwargs={"file_store": self.file_store.name, "_allowed_paths": [state.path]},
session_id=session_id,
resume=None,
builtin_tools=[],
skills=[],
toolkit=None,
output_schema=None,
)
agent_finished = True
note_path = await self._finalize_resource_note(
state,
day,
file_path,
note_stem,
added,
metadata=note_metadata,
required_prefix=required_prefix,
)
if required_prefix and note_path is None:
raise RuntimeError("Resource agent did not write a note")
self.context.response.success = True
self.context.response.answer = agent_reply_result_text(result)
self.context.response.metadata["agent_session_id"] = session_id
except (Exception, asyncio.CancelledError):
# A tool can write successfully before the agent fails. Keep such
# partial notes source-linked so later retries/deletes can find them.
surviving_bytes = self._note_bytes(state.path)
if not agent_finished and surviving_bytes is not None and surviving_bytes != state.before_bytes:
try:
written_path = await self._resolve_written_note(state, day, file_path)
if written_path is not None:
await self._ensure_resource_frontmatter(written_path, file_path, note_metadata)
except Exception as exc: # pylint: disable=broad-except
self.logger.warning(f"[{self.name}] partial note provenance repair failed: {type(exc).__name__}")
raise
finally:
# Tools may have changed the note before the agent or finalization
# failed. Report the disk state without retrying a partially run agent.
current_path = self.context.response.metadata.get("path") or note_path or state.path
exists = self._note_bytes(current_path) is not None
self.context.response.metadata.update(
{
"path": current_path if exists else None,
"created": state.created and exists,
"modified": self._note_modified(state.path, state.before_bytes, current_path),
},
)
agent_kwargs = {}
if input_blocks:
# Scope multimodal note writing without overriding existing text-wrapper defaults.
agent_kwargs = {
"injected_job_kwargs": {"file_store": self.file_store.name, "_allowed_paths": [state.path]},
"resume": None,
"builtin_tools": [],
"skills": [],
"toolkit": None,
"output_schema": None,
}
result = await self.agent_wrapper.reply(
inputs,
system_prompt=self.prompt_format("system_prompt"),
job_tools=self.create_tools if state.created else self.update_tools,
session_id=session_id,
**agent_kwargs,
)
note_path = await self._finalize_resource_note(
state,
day,
file_path,
note_stem,
added,
metadata=note_metadata,
)
self.context.response.success = True
self.context.response.answer = agent_reply_result_text(result)
if note_path is None:
self.logger.info(f"[{self.name}] done without note file_path={file_path} modified=False")
return None
self.context.response.metadata["agent_session_id"] = session_id
self.logger.info(
f"[{self.name}] agent done file_path={file_path} modified={self.context.response.metadata['modified']}",
)
return note_path
async def _resolve_written_note(
self,
@ -552,7 +538,6 @@ class BaseAutoResourceStep(BaseStep):
added: bool,
*,
metadata: dict | None = None,
required_prefix: str = "",
) -> str | None:
"""Resolve, source-link, rename, index, and report one processor write."""
staged_bytes = self._note_bytes(state.path)
@ -568,33 +553,6 @@ class BaseAutoResourceStep(BaseStep):
self.context.response.metadata.update({"path": None, "created": False, "modified": False})
return None
if required_prefix:
target = self.workspace_path / note_path
before_stat = target.stat()
written_bytes = self._note_bytes(note_path)
after_stat = target.stat()
if (before_stat.st_mtime_ns, before_stat.st_size) != (after_stat.st_mtime_ns, after_stat.st_size):
raise RuntimeError("Resource note changed during content validation")
body = frontmatter.loads(written_bytes.decode("utf-8")).content.strip()
content = re.sub(r"!\[\[.*?\]\]|^\s*#+.*$", "", body, flags=re.MULTILINE).strip()
if not body.startswith(required_prefix) or not content:
if state.created:
# Keep invalid new writes discoverable for retry/deletion.
await self._ensure_resource_frontmatter(note_path, file_path, metadata)
elif state.before_bytes is not None and note_path == state.path:
restored = await self.run_job(
"save",
path=note_path,
content=state.before_bytes.decode("utf-8"),
expected_mtime=datetime.fromtimestamp(after_stat.st_mtime).isoformat(),
_allowed_paths=[note_path],
)
if not restored.success:
raise RuntimeError(
f"Invalid resource note; restoring the previous note failed: {restored.answer}",
)
raise RuntimeError("Resource agent wrote no usable content or omitted the source embed")
modified = self._note_modified(state.path, state.before_bytes, note_path)
self.context.response.metadata.update({"path": note_path, "created": state.created, "modified": modified})
await self._ensure_resource_frontmatter(note_path, file_path, metadata)

View file

@ -25,8 +25,7 @@ sys.path.insert(0, str(INTEGRATION_DIR))
# pylint: disable=wrong-import-position
from _workspace_fixture import workspace_env # noqa: E402
from reme.steps.evolve.base_auto_resource import _compute_note_stem # noqa: E402
from reme.steps.evolve.auto_text_resource import _compute_agent_session_id # noqa: E402
from reme.steps.evolve.base_auto_resource import _compute_agent_session_id, _compute_note_stem # noqa: E402
RESOURCE_FILENAME = "project-roadmap.md"
RESOURCE_CONTENT_V1 = """\

View file

@ -19,7 +19,7 @@ from reme.components.runtime_context import RuntimeContext
from reme.steps.evolve.auto_image_resource import AutoImageResourceStep
from reme.steps.evolve.auto_resource import AutoResourceStep
from reme.steps.evolve.base_auto_resource import BaseAutoResourceStep
from reme.steps.file_io import DailyListStep, FrontmatterUpdateStep, MoveStep, SaveStep, WriteStep
from reme.steps.file_io import DailyListStep, FrontmatterUpdateStep, MoveStep, WriteStep
class FakeAgentWrapper(BaseAgentWrapper):
@ -176,7 +176,6 @@ def _install_file_jobs(app_context, file_store) -> None:
"frontmatter_update": _StepJob(FrontmatterUpdateStep, app_context, file_store),
"move": _StepJob(MoveStep, app_context, file_store),
"write": _StepJob(WriteStep, app_context, file_store),
"save": _StepJob(SaveStep, app_context, file_store),
}

View file

@ -3,8 +3,8 @@
# pylint: disable=protected-access
import asyncio
import os
from unittest.mock import patch
import uuid
from unittest.mock import AsyncMock, patch
import frontmatter
import pytest
@ -15,6 +15,7 @@ from reme.components.agent_wrapper import AsAgentWrapper
from reme.components.job import BaseJob
from reme.steps.evolve.auto_image_resource import AutoImageResourceStep
from reme.steps.evolve.auto_resource import AutoResourceStep
from reme.steps.evolve.auto_text_resource import AutoTextResourceStep
from .auto_resource_test_support import FakeAgentWrapper, FakeImageAgentWrapper, caption_fields, image_bytes
@ -22,6 +23,36 @@ pytest_plugins = ("unit.auto_resource_test_plugin",)
pytestmark = pytest.mark.asyncio
@pytest.mark.parametrize("existing", [False, True], ids=["create", "update"])
async def test_text_agent_keeps_main_reply_arguments_and_wrapper_defaults(existing, auto_resource_env):
"""Sharing interpretation must not override the text wrapper's optional settings."""
env = auto_resource_env
source_path = "resource/2026-01-01/notes.txt"
source = env.write_binary(source_path, "中文文本".encode())
if existing:
env.write_note("daily/2026-01-01/notes.md", f"[[{source_path}]]")
wrapper = FakeAgentWrapper()
step = AutoTextResourceStep(app_context=env.app_context, file_store=env.file_store, agent_wrapper=wrapper)
with patch.object(wrapper, "reply", new=AsyncMock(wraps=wrapper.reply)) as reply:
response = await env.run(step, [{"change": "modified" if existing else "added", "path": str(source)}])
assert response.success
assert response.answer == "ok"
assert isinstance(wrapper.inputs, str)
assert "中文文本" in wrapper.inputs
reply.assert_awaited_once()
assert reply.call_args.kwargs == {
"system_prompt": step.prompt_format("system_prompt"),
"job_tools": ["read", "edit", "frontmatter_update", "write"] if existing else ["write"],
"session_id": str(uuid.uuid5(uuid.NAMESPACE_URL, source_path)),
}
tools = step.update_tools if existing else step.create_tools
tools.append("custom_note_tool")
with patch.object(wrapper, "reply", new=AsyncMock(wraps=wrapper.reply)) as reply:
await env.run(step, [{"change": "modified", "path": str(source)}])
assert reply.call_args.kwargs["job_tools"] == tools
assert reply.call_args.kwargs["session_id"] == str(uuid.uuid5(uuid.NAMESPACE_URL, source_path))
async def test_native_image_input_preserves_context_formatter_and_scoped_tools(auto_resource_env):
"""Exercise real Agent construction/observe/format and real file tools, but no model call."""
env = auto_resource_env
@ -177,17 +208,21 @@ async def test_image_agent_failure_before_write_is_not_retried(auto_resource_env
assert not (env.workspace / "daily/2026-01-01/photo.md").exists()
@pytest.mark.parametrize("body", ["", " "])
async def test_image_agent_empty_caption_write_is_a_reportable_failure(body, auto_resource_env):
"""An embed/header alone does not constitute a caption; already-written bytes remain observable."""
async def test_image_agent_body_is_not_postvalidated_or_rewritten(auto_resource_env):
"""Image body instructions belong to the agent prompt, as with text notes."""
env = auto_resource_env
source = env.write_binary("resource/2026-01-01/photo.png", image_bytes())
wrapper = FakeImageAgentWrapper(caption_fields("photo", "", body))
wrapper = FakeImageAgentWrapper(caption_fields("photo", "", ""))
response = await env.run(env.processor(wrapper), [{"change": "added", "path": str(source)}])
result = response.metadata["results"][0]["metadata"]
assert not response.success
assert response.success
assert result["modified"] is True
assert result["action"] == "failed"
assert result["action"] == "added"
note = frontmatter.load(env.workspace / result["path"])
assert note.content == "![[resource/2026-01-01/photo.png]]\n\n## Caption"
assert note["source_resource"] == "[[resource/2026-01-01/photo.png]]"
assert note["kind"] == "image"
assert note["media_type"] == "image/png"
@pytest.mark.parametrize("invalid_config", ["non-agentscope-wrapper", "zero-image-budget"])
@ -263,101 +298,8 @@ async def test_include_images_job_and_call_precedence(
assert response.metadata["results"][0]["metadata"]["reason"] == "include_images=false"
@pytest.mark.parametrize("routed", [False, True])
@pytest.mark.parametrize("source_format", ["PNG", "JPEG"], ids=["same-mime", "changed-source-mime"])
async def test_empty_agent_write_restores_existing_valid_image_note(routed, source_format, auto_resource_env):
"""A blank agent-generated replacement must not destroy a prior valid caption."""
env = auto_resource_env
source = env.write_binary("resource/photo.png", image_bytes(source_format))
note = env.write_note("daily/2026-01-01/original.md", "[[resource/photo.png]]", "Original visual facts.")
before = note.read_bytes()
wrapper = FakeImageAgentWrapper(caption_fields("empty-replacement", "", " "))
response = await env.run(env.processor(wrapper, routed=routed), [{"change": "modified", "path": str(source)}])
assert not response.success
assert len(wrapper.calls) == 1
assert note.read_bytes() == before
assert response.metadata["results"][0]["metadata"]["modified"] is False
assert not (env.workspace / "daily/2026-01-01/empty-replacement.md").exists()
async def test_invalid_image_note_restore_preserves_intervening_editor_changes(auto_resource_env):
"""An optimistic save conflict cannot force an old snapshot over a newer user edit."""
env = auto_resource_env
source = env.write_binary("resource/photo.png", image_bytes())
note = env.write_note("daily/2026-01-01/original.md", "[[resource/photo.png]]", "Original visual facts.")
real_save = env.app_context.jobs["save"]
intervening_content = b"A concurrent editor update that must survive.\n"
save_results = []
async def edit_before_restore(**kwargs):
assert kwargs["path"] == "daily/2026-01-01/original.md"
assert kwargs["_allowed_paths"] == [kwargs["path"]]
assert kwargs["expected_mtime"]
modified_stat = note.stat()
note.write_bytes(intervening_content)
os.utime(note, (modified_stat.st_atime, modified_stat.st_mtime + 2))
result = await real_save(**kwargs)
save_results.append(result)
return result
env.app_context.jobs["save"] = edit_before_restore
wrapper = FakeImageAgentWrapper(caption_fields("empty", "", " "))
response = await env.run(env.processor(wrapper), [{"change": "modified", "path": str(source)}])
assert len(save_results) == 1
assert not save_results[0].success
assert save_results[0].metadata["code"] == "file_conflict"
assert not response.success
assert response.metadata["results"][0]["metadata"]["modified"] is True
assert note.read_bytes() == intervening_content
@pytest.mark.parametrize("routed", [False, True])
@pytest.mark.parametrize("retry_first", [False, True], ids=["delete-partial-note", "retry-then-delete"])
@pytest.mark.parametrize("failure", ["agent-error", "empty-caption"])
async def test_partial_agent_write_remains_owned_for_retry_and_delete(routed, retry_first, failure, auto_resource_env):
"""Agent and content-validation failures retain ownership for subsequent retry/delete."""
env = auto_resource_env
source = env.write_binary("resource/2026-01-01/photo.png", image_bytes("JPEG"))
caption = "Visible photo content." if failure == "agent-error" else ""
wrapper = FakeImageAgentWrapper(caption_fields("suggested-name", "Photo", caption))
if failure == "agent-error":
wrapper.after_write_error = RuntimeError("agent failed after writing")
step = env.processor(wrapper, routed=routed)
response = await env.run(step, [{"change": "added", "path": str(source)}])
assert not response.success
assert len(wrapper.calls) == 1
result = response.metadata["results"][0]["metadata"]
assert result["action"] == "failed"
assert result["modified"] is True
if failure == "empty-caption":
assert "no usable content" in result["error"]
note_path = env.workspace / "daily/2026-01-01/photo.md"
post = frontmatter.load(note_path)
assert post["source_resource"] == "[[resource/2026-01-01/photo.png]]"
assert post["kind"] == "image"
assert post["media_type"] == "image/jpeg"
if retry_first:
wrapper.after_write_error = None
wrapper.content = caption_fields("another-name", "Updated photo", "Updated visual facts.")
retried = await env.run(step, [{"change": "modified", "path": str(source)}])
assert retried.success
metadata = retried.metadata["results"][0]["metadata"]
assert metadata["created"] is False
assert metadata["path"] == "daily/2026-01-01/photo.md"
assert "Updated visual facts." in note_path.read_text(encoding="utf-8")
assert list(note_path.parent.glob("*.md")) == [note_path]
source.unlink()
deleted = await env.run(step, [{"change": "deleted", "path": str(source)}])
assert deleted.success
assert deleted.metadata["results"][0]["metadata"]["action"] == "deleted"
assert not note_path.exists()
assert len(wrapper.calls) == (2 if retry_first else 1)
async def test_partial_agent_write_cannot_claim_an_explicit_foreign_owner(auto_resource_env):
"""Best-effort failure cleanup must not retag another resource's explicit ownership."""
"""A failed agent write cannot make deletion claim an explicitly foreign-owned note."""
env = auto_resource_env
source = env.write_binary("resource/2026-01-01/photo.png", image_bytes())
wrapper = FakeImageAgentWrapper(caption_fields("foreign", "Foreign", "A foreign-owned note."))
@ -375,8 +317,8 @@ async def test_partial_agent_write_cannot_claim_an_explicit_foreign_owner(auto_r
assert note.read_bytes() == before
async def test_cancelled_agent_partial_note_retains_provenance_without_swallowing_cancellation(auto_resource_env):
"""Cancellation propagates, but an already written image note still supports later deletion."""
async def test_agent_cancellation_propagates_without_retrying(auto_resource_env):
"""Keep the text workflow's cancellation behavior instead of adding local recovery."""
env = auto_resource_env
source = env.write_binary("resource/2026-01-01/photo.png", image_bytes())
written = asyncio.Event()
@ -402,9 +344,5 @@ async def test_cancelled_agent_partial_note_retains_provenance_without_swallowin
task.cancel()
await asyncio.gather(task, return_exceptions=True)
note = env.workspace / "daily/2026-01-01/photo.md"
assert frontmatter.load(note)["source_resource"] == "[[resource/2026-01-01/photo.png]]"
assert step.context.response.metadata["modified"] is True
deleted = await env.run(step, [{"change": "deleted", "path": str(source)}])
assert deleted.success
assert not note.exists()
assert "Partial but valid caption." in note.read_text(encoding="utf-8")
assert len(wrapper.calls) == 1