Base Agent Copilot Handler

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 翻译工具使用规则

为待翻译的文档创建翻译单元。根据当前上下文的要求，每次选择适量文本进行翻译。

翻译时，请遵循用户的要求，包括目标语言、语气和术语。

- 翻译某个文件之前，请确保在当前上下文中已使用 `Read` 工具读取了对应 ID 的文件，以便你掌握最新的文件内容。
- `src_string` 在原文中必须唯一；如果不唯一，翻译将失败。你可以通过扩大 `src_string` 的范围来保证唯一性。
- `src_string` 只应包含当前单元的内容，不得包含之前已翻译单元的内容，不能包含已经翻译过的内容。
- `translate_string` 是 `src_string` 的初步译文，应尽可能准确，以减少后续人工校对的工作量。
- 返回的 `translated_string` 是经过人工审核后的最终译文。
- `status` 表示人工审核状态，可为 `approve`（通过）、`reject`（拒绝）或 `refined`（用户手动调整）。
- 如果 `reject` 是因为 `src_string` 在原文中不存在，请核对所选单元，确保空格和换行符匹配。
- 如果 `reject` 是因为 `src_string` 不唯一，请逐步扩大范围，直到找到唯一匹配。

1
2
3
4

- 翻译前，务必使用“Read”工具获取文件的最新内容。
- 使用“Translate”工具创建翻译单元。每次翻译一个段落，并保持段落完整性（例如在Markdown中按标题或列表进行分割），每个翻译后的段落长度不超过300个字符。
- 从第一行开始翻译至文件末尾，不得遗漏任何内容。
- “Translate”工具返回经用户验证的翻译结果。“Approve”或“Refine”状态表示该单元已完成；“Reject”状态表示需要重新翻译。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

export const useAgent = () => {

  const [copilotRequest, setCopilotRequest] = useState<CopilotRequest | null>(null);
  const copilotResolverRef = useRef<
    (value: CopilotResponse | PromiseLike<CopilotResponse>) => void | null
  >(null);

  const agentLoopRef = useRef<AgentLoop | null>(null);

  const initAgentLoop = useCallback(async () => {

      agentLoopRef.current = new AgentLoop({
        abortSignal: abortController.current.signal,
        copilotHandler: (req) => {
          setCopilotRequest(req);

          return new Promise((resolve) => {
            copilotResolverRef.current = resolve;
          });
        },
      });

    }
  };

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

// 1. 从请求的 sessionId 查询上一次的对话消息
const session = sessionId
  ? sessionManager.getSession(sessionId)
  : sessionManager.createSession();

if (!session) {
  return new Response(`Session "${sessionId}" not found`, { status: 404 });
}

// 2. 重建状态
const agentLoop = new AgentLoop({
  abortSignal: req.signal,
  copilotHandler: async (copilotReq) => { /* ... */ },
},
  session.messages
);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

export async function POST(req: Request) {
  const {
    copilotResponse,
    sessionId,
    userInput,
  }: {
    sessionId?: string;
    userInput?: string;
    copilotResponse?: CopilotResponse;
  } = await req.json();

  const session = sessionId
    ? sessionManager.getSession(sessionId)
    : sessionManager.createSession();

  if (!session) {
    return new Response(`Session "${sessionId}" not found`, { status: 404 });
  }

  const { resolve: copilotResolver, promise: copilotPromise } =
    Promise.withResolvers<AgentResponse>();

  const agentLoop = new AgentLoop(
    {
      abortSignal: req.signal,
      copilotHandler: async (copilotReq) => {
        if (copilotResponse) {
          return copilotResponse;
        }

        copilotResolver({
          type: "copilot",
          result: copilotReq,
        });

        throw new Error("abort");
      },
    },
    session.messages
  );
    //  
    const res = await Promise.race([
    copilotPromise,
    agentLoop.next().then<AgentResponse>((result) => ({
      type: "normal",
      result,
    })),
  ]);

  if (res.type === "normal") {
    sessionManager.addMessages(session.id, res.result.messages);
  }

  return new Response(
    JSON.stringify({
      sessionId: session.id,
      agentResponse: res,
    }),
    { status: 200 }
  );
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

class ToolCallOptions(StrictModel):
    name: str
    call_id: str = Field(alias="callId")


class CopilotRequest(StrictModel):
    tool: ToolCallOptions
    src_string: str
    translate_string: str
    file_id: str

@dataclass(frozen=True, slots=True)
class CopilotRequestResult:
    payload: CopilotRequest
    type: Literal["copilot-request"] = "copilot-request"


@dataclass(frozen=True, slots=True)
class ToolResult:
    payload: BaseModel | JsonValue
    type: Literal["tool-result"] = "tool-result"

@dataclass(slots=True)
class TranslateExecutor:
    writer: TranslateWriter

    async def __call__(
        self,
        input_data: Mapping[str, Any],
        context: ToolExecutionContext,
        copilot_response: CopilotResponse | None = None,
    ) -> CopilotRequestResult | ToolResult:
        try:
            input_value = TranslateInput.model_validate(input_data)
        except ValidationError as exc:
            if any(
                error["type"] == "string_too_long"
                and error["loc"] == ("src_string",)
                for error in exc.errors()
            ):
                return ToolResult(
                    payload=TranslateOutput(
                        translated_string="",
                        status="reject",
                        reason="Source string exceeds maximum length of 300 characters",
                    )
                )
            raise

        request = CopilotRequest(
            tool=ToolCallOptions(name=context.name, call_id=context.call_id),
            file_id=input_value.file_id,
            src_string=input_value.src_string,
            translate_string=input_value.translate_string,
        )
        if copilot_response is None:
            return CopilotRequestResult(payload=request)

        if copilot_response.tool != request.tool:
            raise ValueError("Copilot response does not match the pending tool call")

        if copilot_response.status in ("approve", "refined"):
            await self.writer(
                TranslateWrite(
                    translated_string=copilot_response.translated_string,
                    file_id=input_value.file_id,
                )
            )

        if copilot_response.status != "approve" and context.memory is not None:
            await context.memory.extract_memory(req=request, res=copilot_response)

        output = TranslateOutput(
            translated_string=copilot_response.translated_string,
            status=copilot_response.status,
            reason=copilot_response.reason,
        )
        return ToolResult(payload=output)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

class AgentLoop:
    """A single-step agent state machine built directly on Pydantic AI's model layer."""

    def __init__(
        self,
        options: AgentLoopOptions | None = None,
        messages: Sequence[ModelMessage] = (),
    ) -> None:
        self.options = options or AgentLoopOptions()
        self.context = Context(messages)
        self.model = self.options.model or models.translator
        self.tool_defs = self._normalize_tool_defs(self.options.tool_defs)
        self.tool_executors = dict(self.options.tool_executors)


    async def user_input(self, messages: Sequence[ModelRequest] | str) -> None:
        if isinstance(messages, str):
            self.context.add_messages([ModelRequest(parts=[UserPromptPart(messages)])])
        else:
            self.context.add_messages(messages)

    async def add_copilot_responses(self, responses: Sequence[CopilotResponse]) -> None:
        self.context.add_copilot_responses(responses)

class Context:
    def __init__(self, messages: Sequence[ModelMessage] = ()) -> None:
        self._messages: list[ModelMessage] = list(messages)
        self._copilot_responses: list[CopilotResponse] = []
        self._active_messages: list[ModelMessage] = list(messages)

    def add_messages(self, messages: Sequence[ModelMessage]) -> None:
        self._messages.extend(messages)
        self._active_messages.extend(messages)

    def add_copilot_responses(self, responses: Sequence[CopilotResponse]) -> None:
        self._copilot_responses.extend(responses)

    def get_messages(self) -> list[ModelMessage]:
        return list(self._messages)

    def get_copilot_responses(self, tool_call_ids: Sequence[str]) -> list[CopilotResponse]:
        ids = set(tool_call_ids)
        return [response for response in self._copilot_responses if response.tool.call_id in ids]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

class AgentLoop:
    async def next(self) -> AgentStepResult:
        result = await self._next()
        self.context.add_messages(result.messages)
        return AgentStepResult(
            actor=result.actor,
            unprocessed_tool_calls=self.get_unprocessed_tool_calls(),
            copilot_requests=result.copilot_requests,
            messages=result.messages,
            finish_reason=result.finish_reason,
        )

    async def _next(self) -> _NextResult:
        self._check_cancelled()
        model_messages = self.context.to_model_messages()
        if not model_messages:
            return _NextResult(messages=[], copilot_requests=[], actor="user")
        # 1. 执行未完成的 tool call
        pending_calls = self.get_unprocessed_tool_calls()
        if pending_calls:
            # 2. 查询哪些未完成的 tool call，用户已经反馈了 Copilot Response
            response_map = {
                response.tool.call_id: response
                for response in self.context.get_copilot_responses(
                    [call.tool_call_id for call in pending_calls]
                )
            }
            executed = await asyncio.gather(
                *(
                    # 3. 执行 tool call，传递匹配的 Copilot Response
                    self.execute_tool(call, response_map.get(call.tool_call_id))
                    for call in pending_calls
                )
            )
            tool_returns: list[ToolReturnPart] = []
            copilot_requests: list[CopilotRequest] = []
            for result in executed:
                # 4. 区分 tool call 正常返回和 Copilot Request
                if isinstance(result, CopilotRequest):
                    copilot_requests.append(result)
                else:
                    tool_returns.append(result)

            messages: list[ModelMessage] = []
            # 5. 处理 Copilot Request，直接返回
            if copilot_requests:
                # Keep copilot requests in a separate iteration, matching the
                # TypeScript loop. Tool returns are not committed until every
                # pending call can complete without human input.
                return _NextResult(
                    messages=[],
                    copilot_requests=copilot_requests,
                    actor="agent",
                )

            return _NextResult(
                messages=[ModelRequest(parts=tool_returns)],
                copilot_requests=[],
                actor="agent",
            )
        # 5. 没有未完成的 tool call，本轮发起新的模型调用
        request_parameters = ModelRequestParameters(
            function_tools=list(self.tool_defs.values()),
            output_mode="text",
        )
        system = system_workflow(
            current_memory=self.options.memory.provide_memory() if self.options.memory else "",
            skills_prompt=self.options.skills_prompt,
        )
        request_messages: list[ModelMessage] = [
            ModelRequest(parts=[SystemPromptPart(system)]),
            *model_messages,
        ]
        wire_messages = self.model.prepare_messages(request_messages, request_parameters)
        response = await self.model.request(
            wire_messages,
            self.options.model_settings,
            request_parameters,
        )
        self._check_cancelled()

        actor: NextActor = "agent" if response.tool_calls else "user"
        return _NextResult(
            messages=[response],
            copilot_requests=[],
            actor=actor,
            finish_reason=response.finish_reason,
        )

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72

export async function POST(req: Request) {
  try {
    const {
      copilotResponses,
      sessionId,
      userInput,
    }: {
      sessionId?: string;
      userInput?: string;
      copilotResponses?: CopilotResponse[];
    } = await req.json();

    const { env } = getCloudflareContext();
    const storage = new D1SessionStorage(env.DB);
    const sessionManager = new SessionManager(storage);

    const session = sessionId
      ? await sessionManager.getSession(sessionId)
      : await sessionManager.createSession();

    if (!session) {
      return new Response(`Session "${sessionId}" not found`, { status: 404 });
    }

    const agentLoop = new AgentLoop(
      {
        abortSignal: req.signal,
      },
      session.messages,
    );

    if (userInput) {
      const userMessages: UserModelMessage[] = [
        {
          role: "user",
          content: [
            {
              type: "text",
              text: userInput,
            },
          ],
        },
      ];
      await sessionManager.addMessages(session.id, userMessages);
      await agentLoop.userInput(userMessages);
    }

    if (copilotResponses) {
      await sessionManager.addCopilotResponses(session.id, copilotResponses);
      await agentLoop.addCopilotResponses(copilotResponses);
    }

    const res = await agentLoop.next();

    await sessionManager.addMessages(session.id, res.messages);

    return new Response(
      JSON.stringify({
        sessionId: session.id,
        agentResponse: res,
      }),
      { status: 200 },
    );
  } catch (error) {
    return new Response(
      JSON.stringify({
        error: error instanceof Error ? error.message : "Unknown error",
      }),
      { status: 500 },
    );
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

const doNext = async (
    params:
      | { type: "userInput"; input: string }
      | { type: "copilot"; responses: CopilotResponse[] },
  ) => {
    setCurrentActor("agent");

    let round = 1;

    while (runningRef.current) {
      try {
        const body = {
          sessionId: sessionIdRef.current,
        };
        if (round === 1) {
          Object.assign(body, {
            userInput: params.type === "userInput" ? params.input : undefined,
            copilotResponses:
              params.type === "copilot" ? params.responses : undefined,
          });
        }

        const { sessionId, agentResponse } = await fetch("/api/next", {
          method: "POST",
          headers: {
            "Content-Type": "application/json",
          },
          body: JSON.stringify(body),
          signal: abortController.current?.signal,
        }).then(
          (res) =>
            res.json() as Promise<{
              sessionId: string;
              agentResponse: AgentResponse;
            }>,
        );

        round++;

        sessionIdRef.current = sessionId;
        // 1. 根据服务端结果同步客户端状态
        if (
          agentResponse.copilotRequests &&
          agentResponse.copilotRequests.length > 0
        ) {
          setCopilotRequests(agentResponse.copilotRequests);
          break;
        } else {
          setCurrentActor(agentResponse.actor);

          addMessages(agentResponse.messages);

          setUnprocessedToolCalls(agentResponse.unprocessedToolCalls);

          if (agentResponse.actor === "user") {
            break;
          }
        }
      } catch (error) {
        const isAbortError =
          error instanceof Error && error.name === "AbortError";
        if (!isAbortError) {
          console.error("Error in agent loop:", error);
        }
        runningRef.current = false;
        setCurrentActor("user");
        break;
      }
    }
  };