AgentLoop

AgentLoop（范式 / PARADIGM）是 Agent 的主循环范式：用一份 YAML 声明每一轮循环在哪些阶段（stage）注入什么内容、执行什么检查，从而定制它的思考与行动流程。范式支持会话级热切换，且切换前后系统提示前缀保持一致，不破坏 KV Cache。 AgentLoop (a paradigm) is the agent's main loop. A single YAML file declares what each stage injects and checks every round, shaping how the agent thinks and acts. Paradigms hot-swap per session, and the system-prompt prefix is kept stable so the KV cache survives the switch.

• 每轮循环依次触发若干阶段，每个阶段可挂多个 hook，按声明顺序执行。 Each round fires several stages in order; a stage can carry multiple hooks that run in declaration order.
• hook 的三种作用：注入内容到系统提示/上下文、执行检查决定循环能否结束、产生反馈（通过 / 失败提示词）。 Hooks do three things: inject into the prompt or context, check whether the loop may end, and feed back a pass or fail prompt.
• on_loop_end 的检查未通过且未达 loop_end_max_retry 上限时，本轮回打重试。 When an on_loop_end check fails below the loop_end_max_retry ceiling, the round is replayed.

name: strict-finish
description: 强制 Agent 调用 finish_task 并提供 summary 才允许结束
description-en: Force the agent to call finish_task with a summary before ending.
path: agent_vm                # 执行环境标识，保持默认
loop_end_max_retry: 3         # on_loop_end 未通过时的最大重试轮数
trigger:                      # 定时触发声明（可选）
  - cron:
      time: "08:08"
      injection: "【Demo】闹钟响了"
hooks:                        # 阶段 -> hook 列表
  on_build_system_prompt:
    - injection: { content: "你是一个严谨的助手。" }
  on_input_received:
    - keyword_check: { keyword: "周报", type: user, successed_prompt: "用户要写周报：先列出数据来源与周期，再按模板生成。", failed_prompt: "本次输入与周报无关，不要生成周报。" }
  on_loop_start:
    - skill_info: { skills: ["my-skill"], failed_prompt: "缺少技能，请先获取。" }
  on_loop_epoch:
    - injection: { content: "当前进度：{{@TASKSPACE}}", interval: 3 }
  on_loop_end:
    - tool_use_check:
        name: "finish_task"
        parameter_check: "summary"
        successed_prompt: "任务已完成，可以结束。"
        failed_prompt: "尚未调用 finish_task 或缺少 summary 参数，请补齐后重试。"

顶层字段Top-level fields

阶段（stage）Stages

hooks 的键即阶段名，全部可选、按需声明。 The keys of hooks are the stage names; all are optional.

keyword_check（in检查）只检查「本批收到的输入」，因此仅在带 received_messages 的 on_input_received 阶段有意义；它不拦截输入，唯一产出就是提示词——两个提示词都留空则等于什么都没做。 keyword_check only inspects the current batch of input, so it is meaningful only in an on_input_received stage. It never blocks input: its only output is the prompt, and with both prompts left empty it does nothing at all.

hook 类型Hook types

每个 hook 是一个「单键对象」：<action> 为键，值为该 action 的参数对象。 Each hook is a single-key object: the key is the <action>, the value is its parameter object.

通用参数：delay（仅在第 N 个 epoch 执行）、interval（每 N 个 epoch 执行一次）、expect（on_loop_end 中 "fail" 表示「未满足才算通过」，用于反向结束条件）。 Shared parameters: delay (run on the Nth epoch only), interval (run every N epochs), and expect ("fail" in on_loop_end means the loop passes only when the check is unmet, for inverted end conditions).

检查类动作的通用语义（提示词才是它的产出）Check actions in general: the prompt is the payload

检查类动作（tool_use_check、keyword_check、file_operation 的 read / exist_check / delete、command_run、skill_info）只做两件事：判断通过 / 不通过，并把 successed_prompt / failed_prompt 以 role=user 的提示消息注入回历史给模型看。 Check actions (tool_use_check, keyword_check, file_operation with read / exist_check / delete, command_run, skill_info) do exactly two things: decide pass / fail, and inject successed_prompt / failed_prompt back into history as a role=user hint for the model to read.

因此不写提示词的检查等于白写：条件不通过时既没有回打理由，也没有任何内容注入给模型。除「纯放行的闸门」外，都应写出 failed_prompt。 So a check without prompts is a no-op: when it fails there is no replay reason and nothing injected for the model. Unless it is a pure gate, always write failed_prompt.

结论：挂在 on_input_received 上的检查价值 100% 体现在提示词上，只写检查条件、两个提示词都留空，是最典型的“写了但没用”的写法。 Bottom line: for a check on on_input_received, the prompts are 100% of its value; declaring the condition with both prompts empty is the classic “wrote it, useless” case.

in检查（keyword_check）的语义The in-check (keyword_check)

• 它检查的是输入侧：本批以 role=user 注入历史的消息里有没有 keyword——不检查模型输出，也不检查文件。It inspects the input side: whether the current batch of role=user history messages contains keyword — not model output, not files.
• 「输入」不只是用户真实提问：钩子自己注入的提示消息（含 on_loop_end 的打回提示）同样算输入，想只针对真实用户提问时用 type: user 收窄；type 留空则不限制消息类型。“Input” is not just a real user question: hook-injected hints (including on_loop_end replay hints) count too. Narrow to real user messages with type: user; leaving type empty means any message type.
• 命中即通过、未命中即不通过，但它不拦截输入、不阻塞流程、不影响循环能否结束，唯一作用是往历史里追加一条提示，用来做输入分诊。A hit passes, a miss fails, but it never blocks input or the flow and cannot end the loop; its only job is to append a hint into history — input triage.
• 只在 on_input_received 上有意义：其他阶段拿不到本批输入，会恒定判为「未命中」并一直注入 failed_prompt。Only meaningful in on_input_received: other stages get no input batch, so they always fail and keep injecting failed_prompt.

on_input_received:
  # 输入分诊：用户提到「周报」才引导周报流程；没提到也要明确告诉模型别乱走流程
  - keyword_check:
      keyword: "周报"
      type: user
      successed_prompt: "用户要写周报：先列出数据来源与周期，再按模板生成。"
      failed_prompt: "本次输入与周报无关，不要生成周报，按用户真实诉求处理。"

@引用 语法@ reference syntax

在 injection.content 内可直接使用： Usable directly inside injection.content:

接口Interfaces

• 列出 / 读取 / 保存：GET /api/paradigms、GET/POST /api/paradigms/{name}。 List, read, save: GET /api/paradigms and GET/POST /api/paradigms/{name}.
• 会话热切换：POST /api/sessions/{session_id}/paradigm（切换后 KV Cache 前缀保持，冷启动更快）。 Hot swap: POST /api/sessions/{session_id}/paradigm keeps the KV-cache prefix, so cold starts are faster.
• 默认范式：~/.purrcat/paradigms/PARADIGM.yaml；用户未提供时回退到内置 src/agent/system_rules/PARADIGM.yaml。 Default paradigm: ~/.purrcat/paradigms/PARADIGM.yaml, falling back to the built-in src/agent/system_rules/PARADIGM.yaml.
• 落地目录：~/.purrcat/paradigms/；市场仓库 PurrPod/agentloops。 Runtime directory: ~/.purrcat/paradigms/; market repository PurrPod/agentloops.