feat(engine): 添加运行时上下文支持并重构工具迭代限制

添加 RuntimeContext 类用于捕获模型运行时的日期时间信息，包括UTC时间、本地时间和时区信息，并在系统提示中显示这些信息。同时增加最大上下文消息数和工具迭代次数的配置选项，将验证服务从引擎加载器中移除，并更新相关的数据结构和接口。 BREAKING CHANGE: 移除了验证服务，相关字段被替换为证据状态和接受状态。 - 添加 RuntimeContext 类和相关渲染方法 - 增加 max_context_messages 和 max_tool_iterations 配置 - 移除 ValidationService 相关代码 - 更新消息记录中的验证状态字段 - 添加原始工具调用检测和回退处理
2026-05-26 11:18:35 +08:00
parent 16347caf5e
commit 6e9e74d1ee
57 changed files with 5710 additions and 1582 deletions
--- a/projcet_review/backend_blueprint/blueprint.css
+++ b/projcet_review/backend_blueprint/blueprint.css
@ -0,0 +1,224 @@
+* {
+  box-sizing: border-box;
+}
+
+:root {
+  --ink: #111827;
+  --muted: #4b5563;
+  --line: #9ca3af;
+  --soft: #f3f4f6;
+  --paper: #ffffff;
+  --accent: #0f766e;
+  --warn: #92400e;
+}
+
+body {
+  margin: 0;
+  background: #e5e7eb;
+  color: var(--ink);
+  font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  line-height: 1.55;
+}
+
+a {
+  color: var(--accent);
+  text-decoration: none;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+.page {
+  max-width: 1240px;
+  margin: 0 auto;
+  background: var(--paper);
+  min-height: 100vh;
+  border-left: 1px solid var(--line);
+  border-right: 1px solid var(--line);
+}
+
+.topbar {
+  border-bottom: 2px solid var(--ink);
+  padding: 28px 36px 22px;
+}
+
+.topbar h1 {
+  margin: 0 0 8px;
+  font-size: 30px;
+  letter-spacing: 0;
+}
+
+.topbar p {
+  margin: 0;
+  max-width: 920px;
+  color: var(--muted);
+}
+
+.nav {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  padding: 14px 36px;
+  border-bottom: 1px solid var(--line);
+  background: var(--soft);
+}
+
+.nav a {
+  display: inline-block;
+  border: 1px solid var(--line);
+  background: #fff;
+  color: var(--ink);
+  padding: 6px 10px;
+  font-size: 13px;
+}
+
+.content {
+  padding: 32px 36px 52px;
+}
+
+h2 {
+  margin: 34px 0 12px;
+  padding-bottom: 6px;
+  border-bottom: 1px solid var(--line);
+  font-size: 22px;
+}
+
+h3 {
+  margin: 24px 0 10px;
+  font-size: 17px;
+}
+
+.lead {
+  max-width: 980px;
+  color: var(--muted);
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  gap: 14px;
+}
+
+.card,
+.module {
+  border: 1px solid var(--line);
+  background: #fff;
+  padding: 14px;
+}
+
+.module h3,
+.card h3 {
+  margin-top: 0;
+}
+
+.meta {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.flow {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: stretch;
+  gap: 10px;
+  margin: 16px 0 22px;
+  padding: 14px;
+  border: 1px solid var(--line);
+  background: #f9fafb;
+}
+
+.step {
+  border: 1px solid var(--ink);
+  background: #fff;
+  padding: 10px 12px;
+  min-width: 150px;
+  flex: 1 1 150px;
+}
+
+.step strong {
+  display: block;
+  margin-bottom: 4px;
+}
+
+.arrow {
+  align-self: center;
+  color: var(--muted);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+}
+
+.subflow {
+  display: grid;
+  grid-template-columns: 1fr;
+  gap: 8px;
+  margin: 10px 0;
+}
+
+.subflow div {
+  border-left: 4px solid var(--accent);
+  background: #f9fafb;
+  padding: 9px 11px;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 14px 0;
+}
+
+.table th,
+.table td {
+  border: 1px solid var(--line);
+  padding: 9px 10px;
+  text-align: left;
+  vertical-align: top;
+}
+
+.table th {
+  background: var(--soft);
+}
+
+.code,
+pre {
+  border: 1px solid var(--line);
+  background: #f9fafb;
+  padding: 12px;
+  overflow: auto;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 13px;
+}
+
+.callout {
+  border-left: 4px solid var(--warn);
+  background: #fffbeb;
+  padding: 12px 14px;
+  margin: 16px 0;
+}
+
+.toc {
+  columns: 2;
+  column-gap: 32px;
+}
+
+.toc li {
+  break-inside: avoid;
+  margin: 6px 0;
+}
+
+@media (max-width: 760px) {
+  .topbar,
+  .content,
+  .nav {
+    padding-left: 18px;
+    padding-right: 18px;
+  }
+
+  .arrow {
+    display: none;
+  }
+
+  .toc {
+    columns: 1;
+  }
+}
--- a/projcet_review/backend_blueprint/coordinator.html
+++ b/projcet_review/backend_blueprint/coordinator.html
@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Coordinator 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Coordinator</h1><p>Coordinator 负责把 planner 输出的 team graph 落成可执行节点。它不自己造模型调用，而是把每个节点包装成 DelegationEnvelope，交给 LocalAgentRunner 复用 AgentLoop。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="tasks.html">Tasks</a><a href="engine.html">Engine</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>ExecutionGraph</strong>sequence / parallel / dag</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Scheduler</strong>找可运行节点</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Envelope</strong>注入 parent/session/deps/skills</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>LocalAgentRunner</strong>启动子 AgentLoop run</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>NodeRunResult</strong>输出、证据、错误</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>models</h3>
+  <p>定义 <code>AgentDescriptor</code>、<code>ExecutionNode</code>、<code>ExecutionGraph</code>、<code>DelegationEnvelope</code>、<code>NodeRunResult</code> 和 <code>TeamRunResult</code>。</p>
+  <div class="subflow">
+    <div>ExecutionNode 包含 node_id、task、agent、depends_on、constraints、expected_output、pinned skills。</div>
+    <div>ExecutionGraph.validate() 检查 strategy、节点 id、依赖合法性。</div>
+    <div>DelegationEnvelope 是真正传给 LocalAgentRunner 的运行包。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>TeamGraphScheduler</h3>
+  <p>按照 sequence、parallel 或 dag 策略运行节点。依赖节点完成后，其 output 会进入后续节点的 dependency_outputs。</p>
+  <div class="subflow">
+    <div>sequence：按 nodes 顺序逐个运行。</div>
+    <div>parallel：无依赖节点可并行运行。</div>
+    <div>dag：每轮选出依赖已满足节点，运行后更新完成集。</div>
+    <div>汇总 success、node_results、run_ids、errors。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>LocalAgentRunner</h3>
+  <p>本地委派执行器。它给每个 node 生成 child session id，并把 node task 作为 user input 交给 AgentLoop。子 agent 的 execution_context 和 skill_selection_context 都在这里拼装。</p>
+  <div class="subflow">
+    <div>child session id = parent_session:team:node:随机后缀。</div>
+    <div>execution_context 写入 parent task/run、delegated worker、constraints、expected output、dependency outputs、pinned skills、ephemeral guidance。</div>
+    <div>skill_selection_context 写入 node task、phase=team_node、skill query、required capabilities、dependency outputs 和选择指令。</div>
+    <div>AgentLoop 完成后用 EvidenceBuilder 建 node evidence。</div>
+  </div>
+  <p>详细字段见 <a href="prompt-atlas.html#delegated-contexts">Prompt Atlas</a>。</p>
+</article>
+
+<article class="module">
+  <h3>registry / resolver</h3>
+  <p>AgentRegistry 和 TargetResolver 是后续多 agent/多运行目标扩展点。当前主要路径用 generic_skill_worker 和本地 AgentLoop。</p>
+  <div class="subflow">
+    <div>注册 agent descriptor。</div>
+    <div>解析目标 provider/model 或本地 runner。</div>
+    <div>为将来远程/专用 agent 留边界。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/engine.html
+++ b/projcet_review/backend_blueprint/engine.html
@ -0,0 +1,63 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Engine 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Engine</h1><p>Engine 是执行内核：加载 runtime 依赖、捕获 memory、选择 skill/tool、组装 prompt、调用 provider、执行 tool loop，并把全过程写回 session。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="providers.html">Providers</a><a href="tools.html">Tools</a><a href="skills.html">Skills</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>boot</strong>EngineLoader 加载配置/registry/stores/services</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>run start</strong>ensure session + frozen memory</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>能力装配</strong>skills + tools</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>上下文构建</strong>ContextBuilder messages</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>循环</strong>provider chat -> tool calls -> tool results</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>收尾</strong>run_completed + receipts</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>loader</h3>
+  <p>EngineLoader 是依赖装配根。它创建 config、session manager、memory service、tool registry/executor/assembler、skills loader/assembler、task services、MCP manager 等。</p>
+  <div class="subflow">
+    <div>读取 workspace/config。</div>
+    <div>初始化 stores 与 registries。</div>
+    <div>注册内置工具与 MCP 工具。</div>
+    <div>返回 EngineLoadResult 供 AgentLoop 复用。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>AgentLoop</h3>
+  <p>AgentLoop 是所有 root agent 和 delegated agent 共用的执行 kernel。它支持直接 process，也支持 run queue 的 submit_direct 串行消费。</p>
+  <div class="subflow">
+    <div>解析 provider/model/max_tokens/temperature/tool iteration。</div>
+    <div>确保 session，记录 run_started、intent decision、skill/tool selection snapshot。</div>
+    <div>调用 provider；若返回 tool_calls，则逐个 ToolExecutor 执行并追加 tool message。</div>
+    <div>到达工具迭代上限时，追加 finalizer system message 再要求模型无工具收尾。</div>
+    <div>记录 run_completed、usage、skill effect receipts。</div>
+  </div>
+  <p>Prompt 相关：主链 context、tool failure guidance、tool limit finalizer 都在 <a href="prompt-atlas.html#agent-loop">Prompt Atlas</a> 展开。</p>
+</article>
+
+<article class="module">
+  <h3>ContextBuilder</h3>
+  <p>唯一负责 provider messages 形状的组件。它把身份、base system prompt、session、execution context、memory、extra sections 拼成 system prompt，再把 skill 正文作为 user-role activation message 插入。</p>
+  <div class="subflow">
+    <div>build_system_prompt：固定顺序拼 section，用 <code>---</code> 分隔。</div>
+    <div>build_skill_activation_messages：每个 SkillContext 变成一条 user 消息。</div>
+    <div>build_messages：system -> skill messages -> history(跳过 system) -> current user input。</div>
+    <div>add_assistant_message/add_tool_result：tool loop 中追加 provider 兼容消息。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>session</h3>
+  <p>session store/manager/search 负责把运行过程落成可追溯事件。可见历史和审计事件分离，避免 internal snapshots 进入下一轮 prompt。</p>
+  <div class="subflow">
+    <div>append_message 记录 role/event_type/content/tool_calls/context_visible。</div>
+    <div>get_history 给 ContextBuilder 提供裁剪后的可见上下文。</div>
+    <div>search/FTS 支持 session_search 工具和 UI 检索。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/foundation.html
+++ b/projcet_review/backend_blueprint/foundation.html
@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Foundation 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Foundation</h1><p>底座模块提供配置、事件、cron 数据模型和 embedding 检索。它不直接处理业务请求，而是让上层 runtime 有稳定的配置来源、轻量事件通道和通用相似度检索能力。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="services.html">Services</a><a href="engine.html">Engine</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>环境/文件配置</strong><code>Config.load()</code></div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>运行目标解析</strong>main / auxiliary / embedding target</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>能力底座</strong>MessageBus / EmbeddingRetriever / Cron models</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>上层消费</strong>EngineLoader、SkillAssembler、ToolAssembler、CronService</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>config</h3>
+  <p>负责把环境变量和配置文件收敛为 runtime 可用的 provider、embedding、workspace、数据库、MCP、cron 等配置。上层不会直接散读环境变量，而是通过配置对象解析目标。</p>
+  <div class="subflow">
+    <div>读取环境/默认值，形成配置对象。</div>
+    <div>入口传入 model/provider_name 时，覆盖或补充默认 provider target。</div>
+    <div><code>resolve_provider_target()</code>、<code>resolve_embedding_target()</code> 输出 provider factory 能消费的字典。</div>
+  </div>
+  <p class="meta">关键文件：<code>beaver/foundation/config/*</code></p>
+</article>
+
+<article class="module">
+  <h3>events</h3>
+  <p>轻量消息总线，给内部组件做事件发布/订阅。当前核心链路更多依赖 session event 记录，MessageBus 是后续异步投影、通知、可观察性的扩展点。</p>
+  <div class="subflow">
+    <div>组件注册 handler。</div>
+    <div>业务动作发布消息。</div>
+    <div>订阅者异步消费，不反向污染核心执行逻辑。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>cron models</h3>
+  <p>定义 cron job、run record、payload、状态等结构。Services 层用这些模型创建计划任务、记录触发历史，并把结果映射成 notification 或 Task。</p>
+  <div class="subflow">
+    <div>CronJob 保存用户配置、调度表达式和 payload。</div>
+    <div>CronRunRecord 保存单次触发、输出、错误、关联 task/run。</div>
+    <div>CronService 负责状态迁移，AgentService 负责真正执行。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>embedding</h3>
+  <p>通用 embedding retriever 被 skill 和 tool 装配共用。它输入 query 和候选项，输出 top-k 候选；当远程 embedding 不可用时，有 fallback top-k 机制保证链路不完全中断。</p>
+  <div class="subflow">
+    <div>候选项统一渲染为 name/description/text。</div>
+    <div>调用 embedding runtime 计算相似度。</div>
+    <div>按 top-k 输出候选，供 LLM 二次选择或直接加入工具集。</div>
+  </div>
+</article>
+
+<h2>核对点</h2>
+<p>这个模块主要是“稳定输入”。后续如果修改 provider、embedding 或 cron 行为，优先核对配置解析是否继续保持单一入口，避免在 Service 或 Engine 中散落环境变量读取。</p>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/index.html
+++ b/projcet_review/backend_blueprint/index.html
@ -0,0 +1,87 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Beaver Backend 多页模块蓝图</title>
+  <link rel="stylesheet" href="blueprint.css">
+</head>
+<body>
+  <main class="page">
+    <header class="topbar">
+      <h1>Beaver Backend 多页模块蓝图</h1>
+      <p>基于 <code>app-instance/backend/beaver</code> 源码拆出的模块级审阅文档。每个大模块独立成页，页内继续拆小模块、执行流程、数据流和 prompt 组装点。</p>
+    </header>
+    <nav class="nav">
+      <a href="index.html">索引</a>
+      <a href="foundation.html">Foundation</a>
+      <a href="interfaces.html">Interfaces</a>
+      <a href="services.html">Services</a>
+      <a href="engine.html">Engine</a>
+      <a href="providers.html">Providers</a>
+      <a href="tasks.html">Tasks</a>
+      <a href="coordinator.html">Coordinator</a>
+      <a href="tools.html">Tools</a>
+      <a href="skills.html">Skills</a>
+      <a href="memory.html">Memory</a>
+      <a href="integrations.html">Integrations</a>
+      <a href="permissions.html">Permissions</a>
+      <a href="prompt-atlas.html">Prompt Atlas</a>
+    </nav>
+    <section class="content">
+      <h2>项目在做什么</h2>
+      <p class="lead">这个后端是 Beaver 的本地/服务端 agent runtime。它把 Web、CLI、MCP、定时任务等入口统一成 session run，再通过 Intent Agent 判断是否进入内部 Task 模式；Task 模式会计划单 agent 或 team graph，装配 skills/tools/memory，调用 provider，执行工具循环，收集 evidence，并把结果交给用户验收。只有用户接受后的 Task evidence 才进入 skill learning，生成候选、草稿、审核和发布链路。</p>
+
+      <div class="flow">
+        <div class="step"><strong>入口</strong>Web / CLI / Gateway / Cron</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>服务编排</strong>AgentService / CronService / TeamService</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>运行内核</strong>AgentLoop + ContextBuilder</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>能力装配</strong>Skills / Tools / Memory</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>模型与工具</strong>Providers + ToolExecutor</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>任务验收</strong>Evidence / User Acceptance</div>
+      </div>
+
+      <h2>大模块页</h2>
+      <div class="grid">
+        <article class="module"><h3><a href="foundation.html">Foundation</a></h3><p>配置、事件总线、cron 数据结构、embedding 检索基础设施。</p><p class="meta">beaver/foundation</p></article>
+        <article class="module"><h3><a href="interfaces.html">Interfaces</a></h3><p>Web API、静态 UI、CLI、Gateway、MCP server 和外部通道入口。</p><p class="meta">beaver/interfaces</p></article>
+        <article class="module"><h3><a href="services.html">Services</a></h3><p>产品级用例层，负责把入口请求变成 agent run、task run、cron run、team run。</p><p class="meta">beaver/services</p></article>
+        <article class="module"><h3><a href="engine.html">Engine</a></h3><p>运行内核，负责加载依赖、构造上下文、执行 LLM/tool loop、落 session 事件。</p><p class="meta">beaver/engine</p></article>
+        <article class="module"><h3><a href="providers.html">Providers</a></h3><p>统一 provider 协议和 OpenAI/LiteLLM/Anthropic/Codex/Custom 的适配转换。</p><p class="meta">beaver/engine/providers</p></article>
+        <article class="module"><h3><a href="tasks.html">Tasks</a></h3><p>内部 Task 模式：路由、计划、team 技能解析、事实证据和用户验收。</p><p class="meta">beaver/tasks</p></article>
+        <article class="module"><h3><a href="coordinator.html">Coordinator</a></h3><p>把 team graph 节点调度到本地子 agent，管理依赖输出和节点证据。</p><p class="meta">beaver/coordinator</p></article>
+        <article class="module"><h3><a href="tools.html">Tools</a></h3><p>工具规格、注册表、按 run 选择工具、执行器、内置工具和 MCP 工具包装。</p><p class="meta">beaver/tools</p></article>
+        <article class="module"><h3><a href="skills.html">Skills</a></h3><p>Skill 目录、LLM 选择、注入、草稿、审核、发布、学习流水线。</p><p class="meta">beaver/skills</p></article>
+        <article class="module"><h3><a href="memory.html">Memory</a></h3><p>curated memory、session SQLite、run receipt、skill learning store。</p><p class="meta">beaver/memory</p></article>
+        <article class="module"><h3><a href="integrations.html">Integrations</a></h3><p>MCP、AuthZ、Outlook 等外部集成边界。</p><p class="meta">beaver/integrations</p></article>
+        <article class="module"><h3><a href="permissions.html">Permissions</a></h3><p>当前是预留骨架，用来承载后续权限策略。</p><p class="meta">beaver/permissions</p></article>
+      </div>
+
+      <h2>Prompt 组装总图</h2>
+      <p>所有直接构造 LLM messages 的位置集中在 <a href="prompt-atlas.html">Prompt Atlas</a>。模块页中只保留与该模块有关的 prompt 流程，详细字段顺序、system/user message 内容结构、fallback 逻辑都在 Prompt Atlas 展开。</p>
+      <div class="flow">
+        <div class="step"><strong>Intent Agent</strong>判断 simple/task/revise/new/close</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>Planner</strong>判断 single/team，生成 graph</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>Skill Select</strong>选择 published skill 或临时 guidance</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>ContextBuilder</strong>system prompt + skill activation + history + user</div>
+        <div class="arrow">-&gt;</div>
+        <div class="step"><strong>User Acceptance</strong>用户接受、修改或放弃</div>
+      </div>
+
+      <h2>已知核对点</h2>
+      <div class="callout">
+        <strong>定时任务路径有一处疑似运行时错误：</strong>
+        <code>services/agent_service.py</code> 的 <code>run_scheduled_task()</code> 末尾写 event payload 时引用了未定义的 <code>job</code> 和 <code>run</code>，应改用函数参数 <code>cron_job_id</code>、<code>scheduled_run_id</code>、<code>cron_job_name</code>。
+      </div>
+    </section>
+  </main>
+</body>
+</html>
--- a/projcet_review/backend_blueprint/integrations.html
+++ b/projcet_review/backend_blueprint/integrations.html
@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Integrations 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Integrations</h1><p>Integrations 是外部系统边界。当前主要包括 MCP client 连接、AuthZ 客户端、Outlook，以及 A2A/WhatsApp 的占位接入。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="tools.html">Tools</a><a href="services.html">Services</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>配置</strong>外部服务 target/token</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>连接</strong>MCP/AuthZ/Outlook client</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>适配</strong>转成内部 tool/client API</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>消费</strong>ToolRegistry 或 Services 调用</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>MCP client</h3>
+  <p>Engine boot 时 MCP manager 连接配置中的 MCP servers，把远程 tool 描述包装为 Beaver ToolSpec 并注册到 ToolRegistry。</p>
+  <div class="subflow">
+    <div>读取 MCP server 配置。</div>
+    <div>connect_all 建立连接并拉取工具列表。</div>
+    <div>MCP wrapper 转换工具 schema 和 callable。</div>
+    <div>ToolAssembler 后续按任务选择这些工具。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>AuthZ</h3>
+  <p>权限授权系统的外部客户端边界。当前实际权限模块仍是骨架，AuthZ client 是后续接入策略判断的位置。</p>
+  <div class="subflow">
+    <div>Service 或 Tool 发起授权检查。</div>
+    <div>AuthZ client 调外部服务。</div>
+    <div>返回 allow/deny/context。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>Outlook / A2A / WhatsApp</h3>
+  <p>这些是面向外部渠道或平台的适配边界。成熟路径应保持“集成层只做协议适配，业务语义进入 Services”。</p>
+  <div class="subflow">
+    <div>外部事件或 API 请求进入 client。</div>
+    <div>规范化成内部消息、工具结果或服务参数。</div>
+    <div>交给 AgentService/ToolExecutor，不在集成层直接拼业务 prompt。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/interfaces.html
+++ b/projcet_review/backend_blueprint/interfaces.html
@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Interfaces 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Interfaces</h1><p>接口层把外部输入转成内部服务调用。它包含 Web API/静态文件、CLI、Gateway、渠道适配和 MCP server。核心原则是：入口负责协议转换，业务决策交给 Services 和 Engine。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="services.html">Services</a><a href="engine.html">Engine</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>外部请求</strong>HTTP / CLI / MCP / Channel</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Schema/参数整理</strong>session、model、thinking、routing</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>调用 Services</strong>AgentService / CronService / SkillHubService</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>返回响应</strong>chat result、task state、skill artifacts、cron history</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>web</h3>
+  <p>Web 应用是主要产品入口，集中提供 chat、task acceptance、cron、session、skill draft/review/publish 等 API，并服务前端静态资源。</p>
+  <div class="subflow">
+    <div>请求进入 FastAPI route，解析 body/query/path。</div>
+    <div>根据功能调用 AgentService、CronService、SkillHubService 或 SessionProcessProjector。</div>
+    <div>把内部 dataclass/model 转成 JSON payload，并在必要时补充 session/run/task 元数据。</div>
+  </div>
+  <p class="meta">关键文件：<code>beaver/interfaces/web/app.py</code>、<code>beaver/interfaces/web/files.py</code></p>
+</article>
+
+<article class="module">
+  <h3>cli</h3>
+  <p>CLI 入口用于本地命令行运行 Beaver。它复用同一套 AgentService/AgentLoop，因此 CLI 不是第二套 runtime，只是更薄的协议层。</p>
+  <div class="subflow">
+    <div>读取命令行参数。</div>
+    <div>构造 session/source/model 参数。</div>
+    <div>调用 agent run，打印最终输出。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>gateway 与 channels</h3>
+  <p>Gateway 和 channels 是多渠道接入边界，把渠道消息抽象为统一的内部消息。当前代码中通道能力较轻，主要服务未来接入不同聊天来源。</p>
+  <div class="subflow">
+    <div>渠道事件进入 adapter。</div>
+    <div>规范化 user_id、channel、chat_id、content。</div>
+    <div>转给 AgentService，最终仍落入同一个 session/run 体系。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>mcp_servers</h3>
+  <p>对外暴露 MCP server 能力，让 Beaver 的部分能力可以被其他 MCP client 调用；这和 Beaver 作为 MCP client 使用外部工具是两条边界。</p>
+  <div class="subflow">
+    <div>MCP client 调用 server tool。</div>
+    <div>接口层解析 MCP 参数。</div>
+    <div>转调内部服务或数据访问层。</div>
+  </div>
+</article>
+
+<h2>修改影响点</h2>
+<p>入口层新增字段时，要同步核对 Services 层是否需要进入 prompt：例如 <code>thinking_enabled</code> 会影响 router、skill assembler、provider chat kwargs；<code>execution_context</code> 会进入 ContextBuilder 的 system prompt。</p>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/memory.html
+++ b/projcet_review/backend_blueprint/memory.html
@ -0,0 +1,58 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Memory 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Memory</h1><p>Memory 模块提供三类持久上下文：curated memory、session/run memory、skill learning memory。主链 prompt 使用 frozen curated snapshot，审计和学习使用 session/run evidence；Task evidence 只作为事实记录。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="engine.html">Engine</a><a href="skills.html">Skills</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>Curated</strong>MEMORY.md / USER.md</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Snapshot</strong>run 开始前冻结</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Prompt</strong>ContextBuilder 注入 system sections</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Session</strong>运行事件和可见历史</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Learning</strong>run receipts / skill effects</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>curated</h3>
+  <p>人工或工具维护的长期记忆文件。MemoryService 在每个 run 开始前捕获 snapshot，ContextBuilder 只读 snapshot，避免运行中变化影响同一轮 prompt。</p>
+  <div class="subflow">
+    <div>读取 workspace 下的 memory 文件。</div>
+    <div>生成 MemorySnapshot。</div>
+    <div><code>as_prompt_sections()</code> 渲染为 system prompt sections。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>sessions</h3>
+  <p>SQLite session store 保存 message/event 流、usage、system prompt snapshot、tool call、tool result、task evidence 与 acceptance 事件等，并支持 FTS 检索。</p>
+  <div class="subflow">
+    <div>AgentLoop append_message 记录每一步。</div>
+    <div>context_visible=false 的内部事件不进入普通对话历史。</div>
+    <div>get_history 给 ContextBuilder 取可见历史。</div>
+    <div>session_search 工具使用检索能力找历史证据。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>runs</h3>
+  <p>run memory 记录一次 run 的 receipts、acceptance metadata、skill effects。它是 skill learning 的主要证据来源，但 learning 入口由 task accepted 触发，而不是单个 run 触发。</p>
+  <div class="subflow">
+    <div>run_completed 后记录 run receipt。</div>
+    <div>用户 acceptance accept/revise/abandon 更新 task 状态，并为 skill learning 标记 final accepted run。</div>
+    <div>skill effects 根据成功率重算版本分数。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>skills learning store</h3>
+  <p>保存 learning candidates、drafts、review 状态和发布记录。它把一次运行经验变成可审核的长期能力改动。</p>
+  <div class="subflow">
+    <div>从 accepted task evidence 建 candidate，包含 task 的所有 runs 和 final_accepted_run_id。</div>
+    <div>candidate 进入 synthesis。</div>
+    <div>生成 draft 后由人审阅发布。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/permissions.html
+++ b/projcet_review/backend_blueprint/permissions.html
@ -0,0 +1,30 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Permissions 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Permissions</h1><p>当前 <code>beaver/permissions</code> 更像预留边界，还没有形成完整策略执行链路。它应该承接工具执行、文件访问、外部集成、用户身份和审计之间的权限判断。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="tools.html">Tools</a><a href="integrations.html">Integrations</a></nav>
+<section class="content">
+<h2>预期大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>请求动作</strong>tool / integration / file / cron</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>上下文</strong>user/session/source/workspace</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>策略判断</strong>本地 policy 或 AuthZ</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>执行/拒绝</strong>ToolResult 或异常</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>审计</strong>session event/run evidence</div>
+</div>
+
+<h2>当前状态</h2>
+<article class="module">
+  <h3>骨架模块</h3>
+  <p>现有代码没有在核心路径中统一调用 permissions policy。工具执行主要依赖 ToolExecutor 和各工具自身约束；外部授权能力放在 integrations/authz 边界。</p>
+  <div class="subflow">
+    <div>权限模块可作为未来统一策略层。</div>
+    <div>ToolContext 已携带 user/session/workspace/services，可作为策略输入。</div>
+    <div>session event 已经具备审计载体，可记录 allow/deny。</div>
+  </div>
+</article>
+
+<h2>修改建议核对点</h2>
+<p>如果后续补权限，建议从 ToolExecutor 前置检查切入：它是所有 provider tool_call 的统一收口点。第二个切入点是 web route 层的管理类 API，例如 skill 发布、cron 修改、文件系统工具。</p>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/prompt-atlas.html
+++ b/projcet_review/backend_blueprint/prompt-atlas.html
@ -0,0 +1,217 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Prompt Atlas</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Prompt Atlas</h1><p>这里集中记录后端所有直接组装 LLM messages 的位置。每段都按“谁调用、输入怎么来、system/user prompt 怎么拼、模型输出怎么解析、失败怎么 fallback”展开。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="services.html">Services</a><a href="engine.html">Engine</a><a href="tasks.html">Tasks</a><a href="skills.html">Skills</a><a href="coordinator.html">Coordinator</a></nav>
+<section class="content">
+<h2>总览流程</h2>
+<div class="flow">
+  <div class="step"><strong>Intent Router</strong>是否 Task</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Planner</strong>single/team</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Skill 选择</strong>主 run / team node</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Main Context</strong>身份/会话/记忆/技能/历史</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Evidence</strong>事实记录</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Learning</strong>accepted task evidence -> 草稿合成</div>
+</div>
+
+<h2 id="intent-router">1. MainAgentRouter</h2>
+<p class="meta">文件：<code>beaver/tasks/router.py</code>；调用方：<code>AgentService._process_with_main_agent()</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>作用</td><td>只决定当前用户消息进入 simple chat 还是 internal Task mode，不回答用户。</td></tr>
+  <tr><td>system message</td><td>声明自己是 Beaver 的 Intent Agent；唯一职责是路由；只返回紧凑 JSON；不要回答用户，不要解释。</td></tr>
+  <tr><td>user prompt 组成</td><td>固定说明“Decide how to route”；可选 intent-agent-router skill guidance；Actions 列表；Critical policy；返回 JSON keys；Active task JSON；最近 8 条 user/assistant 对话；Current user message。</td></tr>
+  <tr><td>输出</td><td><code>{ action, reason, short_title }</code>。action 映射为 simple_chat、continue_task、revise_task、new_task、close_task、abandon_task。</td></tr>
+  <tr><td>fallback</td><td>provider 不可用或两次超时失败：有 active task 则 continue_task，否则 simple_chat。</td></tr>
+</table>
+<div class="flow">
+  <div class="step">message + active_task + recent_messages</div><div class="arrow">-&gt;</div>
+  <div class="step">拼 router prompt</div><div class="arrow">-&gt;</div>
+  <div class="step">aux/main provider chat</div><div class="arrow">-&gt;</div>
+  <div class="step">parse JSON object</div><div class="arrow">-&gt;</div>
+  <div class="step">MainAgentDecision</div>
+</div>
+<pre>user prompt =
+"Decide how to route..."
+ optional "Intent Agent skill guidance:\n{intent_skill}"
+ Actions 列表
+ Critical policy 列表
+ "Return JSON only with keys: action, reason, short_title."
+ "Active task:\n{json(active_task_payload)}"
+ "Recent conversation:\n{json(recent[-8:])}"
+ "Current user message:\n{message}"</pre>
+
+<h2>2. TaskExecutionPlanner</h2>
+<p class="meta">文件：<code>beaver/tasks/planner.py</code>；调用方：<code>AgentService._run_task_mode()</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>作用</td><td>决定本次 Task attempt 直接单 agent 执行，还是先创建 sub-agent team。</td></tr>
+  <tr><td>system message</td><td>选择 internal Beaver Task attempt 的执行模式；返回紧凑 JSON。</td></tr>
+  <tr><td>user prompt 组成</td><td>执行模式说明；team 使用条件；JSON schema；Task goal；Current user request；Attempt index；必要的 task history（若有）。</td></tr>
+  <tr><td>输出</td><td><code>mode</code> 为 single 或 team；team 时还需 <code>strategy</code>、<code>nodes</code>、<code>final_synthesis_instruction</code>。</td></tr>
+  <tr><td>fallback</td><td>provider 不可用、JSON 解析失败、graph validate 失败、skill resolver 失败都会回退 single。</td></tr>
+</table>
+<pre>planner user prompt =
+"Decide execution mode for this internal Task attempt."
+ "Use mode=team only when ..."
+ JSON schema(mode/reason/strategy/nodes/final_synthesis_instruction)
+ "Task goal:\n{task.goal}"
+ "Current user request:\n{user_message}"
+ "Attempt index: {attempt_index}"
+ optional "Relevant task history:\n{task_history}"</pre>
+
+<h2>3. TaskSkillResolver</h2>
+<p class="meta">文件：<code>beaver/tasks/skill_resolver.py</code>；调用方：planner 解析 team graph 后</p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>query 组装</td><td><code>skill_query</code>、<code>node.task</code>、required capabilities、task.goal、user_message 用换行拼接。</td></tr>
+  <tr><td>召回</td><td>SkillsLoader 构建候选，EmbeddingRetriever top-8。</td></tr>
+  <tr><td>system message</td><td>为一个 generic sub-agent node 选择 published Beaver skills；只返回 JSON array；不能编造名字；不匹配返回 []。</td></tr>
+  <tr><td>user prompt</td><td>Node skill query；Candidate skills 列表；要求返回 JSON，例如 <code>["skill-a"]</code> 或 <code>[]</code>。</td></tr>
+  <tr><td>输出过滤</td><td>只保留候选集中真实存在的 skill name，并保持模型输出顺序。</td></tr>
+  <tr><td>fallback</td><td>LLM 失败或返回空时，进入 EphemeralGuidanceSynthesizer。</td></tr>
+</table>
+<pre>node skill query =
+join_non_empty(skill_query, node.task, " ".join(required_capabilities), task.goal, user_message)</pre>
+
+<h2>4. EphemeralGuidanceSynthesizer</h2>
+<p class="meta">文件：<code>beaver/skills/learning/missing_skill.py</code>；调用方：TaskSkillResolver</p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>作用</td><td>team node 没有 published skill 可用时，生成当前委派子任务专用的一次性 guidance。</td></tr>
+  <tr><td>system message</td><td>创建 concise Beaver ephemeral guidance；只返回 JSON keys：guidance_name、description、content、tags。</td></tr>
+  <tr><td>user prompt</td><td>说明“Create procedural guidance”；Task goal；Current user request；Node id；Node task；Skill query；Required capabilities；要求 content 是临时 sub-agent 可执行指导，不包含实现声明、review metadata 或 publish metadata。</td></tr>
+  <tr><td>输出</td><td>生成 <code>SkillContext(name="ephemeral:{guidance_name}", version="ephemeral:{guidance_id}")</code>。</td></tr>
+  <tr><td>fallback</td><td>失败时本地生成基础 payload：Objective、Capabilities to apply、Output。</td></tr>
+</table>
+
+<h2 id="skill-assembler">5. SkillAssembler</h2>
+<p class="meta">文件：<code>beaver/skills/assembler/task_assembler.py</code>；调用方：<code>AgentLoop._process_direct_impl()</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>query 来源</td><td>默认是 task；Task 模式会传入 AgentService 组装的 skill_selection_context；team node 会传 LocalAgentRunner 组装的 delegated skill_selection_context。</td></tr>
+  <tr><td>召回</td><td>SkillsLoader candidates -> EmbeddingRetriever top-k。</td></tr>
+  <tr><td>shortlist</td><td>候选数超过 max_detailed_candidates 时，LLM 先基于摘要返回最多 N 个 skill names。</td></tr>
+  <tr><td>final</td><td>把 shortlist 对应候选补充 skill 正文，再让 LLM 返回最终要激活的 skill names。</td></tr>
+  <tr><td>system message</td><td>选择 Beaver skills；输入 task description 和 candidate skill information；只返回 JSON array；不能编造名字；无匹配返回 []；包含 selection stage 和返回数量指令。</td></tr>
+  <tr><td>user prompt</td><td>Task description；Candidate skills；返回 JSON 示例。</td></tr>
+  <tr><td>注入</td><td>加载 skill 正文并 strip frontmatter，生成 SkillContext，稍后由 ContextBuilder 转成 activation message。</td></tr>
+</table>
+<pre>skill selector messages =
+system: "You select Beaver skills for a single run..." + "Selection stage: {shortlist|final}..."
+user: "Task description:\n{task_description}\n\nCandidate skills:\n{candidate_summary}\n\nReturn only JSON..."</pre>
+
+<h2 id="agent-service-contexts">6. AgentService 组装的上下文片段</h2>
+<p class="meta">文件：<code>beaver/services/agent_service.py</code></p>
+<article class="module">
+  <h3>Task skill selection context</h3>
+  <p>传给 SkillAssembler 的 task_description。它不是 provider chat 的最终 prompt，但会影响选中哪些 skills。</p>
+  <div class="subflow">
+    <div>Task goal / description / current user request。</div>
+    <div>Execution phase、task status、attempt index。</div>
+    <div>constraints、prior skills、必要的 task history。</div>
+    <div>planner reason、strategy、nodes、team summaries、final synthesis instruction。</div>
+    <div>明确要求优先选择 existing published skills。</div>
+  </div>
+</article>
+<article class="module">
+  <h3>Team execution context</h3>
+  <p>如果 team 先跑，主 agent 的 execution_context 会包含 planner reason、team strategy、team success、node results、rendered team evidence、final synthesis instruction，以及避免重复失败工具调用的提醒。</p>
+</article>
+<article class="module">
+  <h3>Scheduled execution context</h3>
+  <p>cron task/notification 会把 Cron Job ID、Name、Scheduled Run ID 和“不向用户确认，直接执行/生成通知”的约束放进 execution_context。</p>
+</article>
+
+<h2 id="delegated-contexts">7. LocalAgentRunner delegated contexts</h2>
+<p class="meta">文件：<code>beaver/coordinator/local.py</code></p>
+<table class="table">
+  <tr><th>上下文</th><th>拼装内容</th></tr>
+  <tr><td>execution_context</td><td>Parent task ID、Parent run ID、delegated worker 说明、agent.system_prompt、constraints、expected output、dependency outputs、pinned inherited skills、ephemeral pinned guidance。</td></tr>
+  <tr><td>skill_selection_context</td><td>Parent task ID、Node task、Execution phase=team_node、Agent role、Skill query、Required capabilities、constraints、expected output、pinned skills、dependency outputs 前 800 字、Skill selection instruction。</td></tr>
+</table>
+<div class="flow">
+  <div class="step">DelegationEnvelope</div><div class="arrow">-&gt;</div>
+  <div class="step">child session id</div><div class="arrow">-&gt;</div>
+  <div class="step">execution_context</div><div class="arrow">+</div>
+  <div class="step">skill_selection_context</div><div class="arrow">-&gt;</div>
+  <div class="step">AgentLoop.process_direct</div>
+</div>
+
+<h2 id="agent-loop">8. AgentLoop 主运行 prompt</h2>
+<p class="meta">文件：<code>beaver/engine/loop.py</code>、<code>beaver/engine/context/builder.py</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>base identity</td><td>固定 Beaver 身份：海狸（Beaver），博维资讯系统有限公司研发的 AI 助手。</td></tr>
+  <tr><td>base system prompt</td><td>AgentProfile.system_prompt。</td></tr>
+  <tr><td>session section</td><td>Session ID、Source、Model、User ID、Channel、Chat ID、Parent Session ID。</td></tr>
+  <tr><td>execution context</td><td>Service 或 LocalAgentRunner 传入，标题为 <code># Execution Context</code>。</td></tr>
+  <tr><td>memory snapshot</td><td>MemorySnapshot.as_prompt_sections() 的 frozen sections。</td></tr>
+  <tr><td>extra sections</td><td>当前固定加入 Tool Failure Guidance。</td></tr>
+  <tr><td>skill activation</td><td>每个 SkillContext 变成一条 user message，位于 system prompt 之后、历史消息之前。</td></tr>
+  <tr><td>history</td><td>session_manager.get_history()，ContextBuilder 跳过 role=system 的历史。</td></tr>
+  <tr><td>current user</td><td>本轮 task/message 作为最后一条 user message。</td></tr>
+</table>
+<pre>messages =
+[
+  {"role": "system", "content": build_system_prompt(...)},
+  ...build_skill_activation_messages(activated_skills),
+  ...visible_history_without_system,
+  {"role": "user", "content": current_user_input}
+]</pre>
+<h3>Tool Failure Guidance</h3>
+<p>AgentLoop 把一段额外 section 放进 system prompt：如果同类工具反复失败，不要继续换 query 重试；使用已有材料，明确不确定性，给出部分已确认结果。</p>
+<h3>Tool iteration finalizer</h3>
+<p>到达最大工具迭代数后，AgentLoop 追加一条新的 system message，要求工具预算已耗尽、不要再调用工具、基于现有对话和工具结果给出最终答案，并明确不确定性。该 finalizer 只用于最后一次无工具收尾调用。</p>
+
+<h2>9. Tool loop 消息追加</h2>
+<p class="meta">文件：<code>beaver/engine/context/builder.py</code>、<code>beaver/engine/loop.py</code></p>
+<div class="flow">
+  <div class="step">provider response</div><div class="arrow">-&gt;</div>
+  <div class="step">assistant message(content + tool_calls)</div><div class="arrow">-&gt;</div>
+  <div class="step">ToolExecutor</div><div class="arrow">-&gt;</div>
+  <div class="step">tool message(tool_call_id/name/content)</div><div class="arrow">-&gt;</div>
+  <div class="step">下一轮 provider chat</div>
+</div>
+<p>assistant 消息始终显式包含 <code>content</code> 键，即使工具调用时为空；tool_calls 会被规范化为 OpenAI-compatible 结构，arguments 非字符串时转 JSON 字符串。</p>
+
+<h2>10. Task Evidence</h2>
+<p class="meta">文件：<code>beaver/tasks/evidence.py</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>作用</td><td>记录 Task run 的事实证据，不判断、不打分、不 gate，也不生成 revision prompt。</td></tr>
+  <tr><td>输入</td><td>Task goal、attempt index、main run、team runs、tool results、team node results、assistant final output。</td></tr>
+  <tr><td>输出</td><td>TaskEvidencePacket / rendered evidence text，供审计、过程展示和 skill learning 使用。</td></tr>
+  <tr><td>边界</td><td>Task 是否完成只由 User Acceptance 决定；accepted task evidence 包含 task 的所有 runs，并标记 final_accepted_run_id。</td></tr>
+</table>
+
+<h2>11. SkillDraftSynthesizer</h2>
+<p class="meta">文件：<code>beaver/skills/learning/synthesizer.py</code></p>
+<table class="table">
+  <tr><th>阶段</th><th>内容</th></tr>
+  <tr><td>作用</td><td>从 accepted task evidence 合成 skill 草稿，支持 new/revise/merge。</td></tr>
+  <tr><td>system message</td><td>从 accepted task evidence 合成 Beaver skill drafts；只返回 JSON keys：frontmatter、content、change_reason。</td></tr>
+  <tr><td>user prompt</td><td>Action；Candidate kind；Reason；Related skills；Called tool names；Run-selected tool names；Task summaries；Session excerpts；final_accepted_run_id；frontmatter 必须包含 description 和 tools 数组。</td></tr>
+  <tr><td>输出 normalize</td><td>frontmatter.tools 为空时用 evidence_packet.metadata.tool_names 补齐。</td></tr>
+  <tr><td>fallback</td><td>JSON 不合格时本地生成基础 frontmatter 和 Evidence 内容。</td></tr>
+</table>
+
+<h2 id="provider-conversion">12. Provider conversion</h2>
+<p class="meta">文件：<code>beaver/engine/providers/*</code></p>
+<p>Provider 层不负责创造业务 prompt，但会改变 messages 的传输形式。Anthropic/Codex 类 provider 会把第一条 system message 拆出来传给 SDK 的 <code>system</code> 或 <code>instructions</code> 字段，剩余 messages 作为对话；OpenAI/LiteLLM 风格 provider 基本保留 messages + tools。</p>
+<div class="subflow">
+  <div>ContextBuilder 输出统一 messages。</div>
+  <div>Provider adapter 根据目标 SDK 转换 system、tools、tool calls、usage、reasoning。</div>
+  <div>响应统一回 LLMResponse，AgentLoop 不感知 SDK 差异。</div>
+</div>
+
+<h2>13. 无 LLM prompt 但影响 prompt 的组件</h2>
+<table class="table">
+  <tr><th>组件</th><th>影响</th></tr>
+  <tr><td>ToolAssembler</td><td>不调用 LLM，但决定哪些 tool schema 暴露给主模型。</td></tr>
+  <tr><td>MemoryService</td><td>不调用 LLM，但 frozen snapshot 会进入 system prompt。</td></tr>
+  <tr><td>SessionManager</td><td>不调用 LLM，但可见历史决定 ContextBuilder 的 history。</td></tr>
+  <tr><td>SkillDraftSafetyChecker</td><td>不调用 LLM，是 deterministic safety gate，影响草稿是否能进入后续审核。</td></tr>
+</table>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/providers.html
+++ b/projcet_review/backend_blueprint/providers.html
@ -0,0 +1,68 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Providers 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Providers</h1><p>Providers 把不同模型服务统一成 Beaver 内部的 <code>chat(messages, tools, model, ...)</code> 协议，屏蔽 OpenAI/LiteLLM/Anthropic/Codex/Custom 的差异。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="engine.html">Engine</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>配置目标</strong>provider_name/model/api_base/key</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>ProviderBundle</strong>main/auxiliary/embedding</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Provider.chat</strong>统一入参</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>协议转换</strong>system/tool/reasoning/usage</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>LLMResponse</strong>content/tool_calls/finish_reason</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>base models</h3>
+  <p><code>LLMProvider</code> 定义 chat 协议；<code>LLMResponse</code> 统一模型输出；<code>ToolCallRequest</code> 统一工具调用 id/name/arguments。</p>
+  <div class="subflow">
+    <div>AgentLoop 只消费 LLMResponse，不关心具体 SDK。</div>
+    <div>Tool call arguments 被规范化为字符串或 dict 后交给 ToolExecutor。</div>
+    <div>usage 被映射回 session usage。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>factory / runtime / registry</h3>
+  <p>根据配置创建 provider runtime，并组织 main provider、auxiliary provider 和 embedding runtime。Router、Planner、Validator 和 Skill 选择通常使用 auxiliary provider；主回答使用 main provider。</p>
+  <div class="subflow">
+    <div>resolve provider target。</div>
+    <div>创建 runtime，带 api key/base/header/timeout/model。</div>
+    <div>创建 ProviderBundle，供一次 Task attempt 复用。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>LiteLLM / OpenAI-like</h3>
+  <p>主要走 OpenAI 风格 messages + tools。它最接近 Beaver 内部协议，转换成本最低。</p>
+  <div class="subflow">
+    <div>接收 ContextBuilder messages。</div>
+    <div>附加 tools、max_tokens、temperature、thinking_enabled。</div>
+    <div>解析 content、tool_calls、usage、finish_reason。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>Anthropic 与 Codex</h3>
+  <p>这两类 provider 对 system prompt 有特殊要求，会把第一条 system message 提取到独立字段，剩余 messages 作为对话输入。Codex 还会使用 prompt cache key。</p>
+  <div class="subflow">
+    <div>扫描 messages，提取第一条 system。</div>
+    <div>其余 system 或非 system message 按 provider 能接受的格式转换。</div>
+    <div>调用 provider SDK，并把响应转回 LLMResponse。</div>
+  </div>
+  <p>Prompt 相关：provider 本身不创造业务 prompt，但会改变 system message 的传输位置，详见 <a href="prompt-atlas.html#provider-conversion">Prompt Atlas</a>。</p>
+</article>
+
+<article class="module">
+  <h3>fallback chain</h3>
+  <p>当主 provider 失败时，fallback chain 可以尝试备用目标。上层仍看到统一的 LLMResponse。</p>
+  <div class="subflow">
+    <div>主 provider 调用失败。</div>
+    <div>记录异常并尝试 fallback target。</div>
+    <div>成功则返回 fallback response；全部失败则 finish_reason/error。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/services.html
+++ b/projcet_review/backend_blueprint/services.html
@ -0,0 +1,71 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Services 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Services</h1><p>Services 是产品用例编排层。它不实现底层 tool loop，但决定什么时候进入 Task、什么时候跑通知、什么时候创建 team、什么时候记录用户验收和学习候选。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="tasks.html">Tasks</a><a href="engine.html">Engine</a><a href="coordinator.html">Coordinator</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>接口调用</strong>chat / cron / acceptance / skill admin</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>AgentService</strong>路由 simple vs Task</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Task 编排</strong>planner、team、main run、evidence</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>状态落盘</strong>session events、task store、run memory、skill learning</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>AgentService</h3>
+  <p>核心服务。普通消息先由 MainAgentRouter 分类；simple chat 关闭 skill/tool 装配直接跑；Task 模式创建或复用 TaskRecord，计划 single/team，运行主 agent，记录 evidence，并等待用户验收。</p>
+  <div class="subflow">
+    <div>输入 message + session kwargs，创建 provider bundle。</div>
+    <div>调用 Intent Agent，得到 simple_chat / continue_task / revise_task / new_task / close_task / abandon_task。</div>
+    <div>Task 模式中调用 TaskExecutionPlanner，必要时先跑 TeamGraphScheduler。</div>
+    <div>主 AgentLoop 执行后构建 evidence packet；evidence 只记录事实，不判断结果质量。</div>
+    <div>run 完成后进入 awaiting_acceptance；用户 accept/revise/abandon 决定后续状态。</div>
+  </div>
+  <p>Prompt 相关：AgentService 组装 Task skill selection context、team execution context、scheduled execution context，详细见 <a href="prompt-atlas.html#agent-service-contexts">Prompt Atlas</a>。</p>
+</article>
+
+<article class="module">
+  <h3>CronService</h3>
+  <p>管理定时任务的创建、启停、触发、run history。CronService 负责调度状态；真正生成内容时调用 AgentService 的 scheduled task 或 notification 路径。</p>
+  <div class="subflow">
+    <div>保存 CronJob 配置和 payload。</div>
+    <div>到点创建 CronRunRecord。</div>
+    <div>调用 AgentService 执行 notification 或 Task。</div>
+    <div>回写 output/error/task_id/run_id。</div>
+  </div>
+  <div class="callout">核对点：<code>run_scheduled_task()</code> 当前末尾引用未定义 <code>job</code>/<code>run</code>，应改为函数入参。</div>
+</article>
+
+<article class="module">
+  <h3>TeamService</h3>
+  <p>提供 team graph 的产品级封装。底层执行在 coordinator，Service 层关心的是把执行结果转成 API 友好的结构。</p>
+  <div class="subflow">
+    <div>接收 graph / nodes / strategy。</div>
+    <div>创建 TeamGraphScheduler 和 LocalAgentRunner。</div>
+    <div>返回 node results、run ids、success/error。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>MemoryService 与 SessionProcessProjector</h3>
+  <p>MemoryService 给每个 run 捕获 frozen curated memory snapshot；SessionProcessProjector 把 session 事件投影成 UI 所需的过程视图。</p>
+  <div class="subflow">
+    <div>run 开始前捕获 memory snapshot，避免运行中写入导致 prompt 漂移。</div>
+    <div>session event 记录完整过程。</div>
+    <div>projector 从事件流还原步骤、工具、evidence 和用户验收状态。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>SkillHubService</h3>
+  <p>面向产品的 skill 草稿、审核、发布、学习候选接口。底层由 skills/drafts/reviews/publisher/learning 实现。</p>
+  <div class="subflow">
+    <div>列出 learning candidates 或 drafts。</div>
+    <div>触发 draft synthesis / review。</div>
+    <div>人工确认后发布为 published skill。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/skills.html
+++ b/projcet_review/backend_blueprint/skills.html
@ -0,0 +1,82 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Skills 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Skills</h1><p>Skills 模块负责加载、选择、注入、学习和发布 Beaver 技能。技能不是普通文档摘要，而是会被 ContextBuilder 作为显式 user 消息注入当前 run 的操作指导。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="engine.html">Engine</a><a href="tasks.html">Tasks</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>目录加载</strong>published/builtin/drafts/specs</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>候选召回</strong>embedding retrieve</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>LLM 选择</strong>shortlist/final 或 node skill selection</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>注入</strong>SkillContext -> activation message</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>学习</strong>accepted task evidence -> candidate -> draft -> review -> publish</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>catalog loader</h3>
+  <p>扫描和加载 published skills、builtin skills，并构建供 embedding/LLM 选择的候选摘要。它也提供 load_published_skill、get_skill_record、get_skill_tool_hints。</p>
+  <div class="subflow">
+    <div>读取 SKILL.md 和 frontmatter。</div>
+    <div>记录 name、description、version、content_hash、tool hints。</div>
+    <div>输出 selection candidates。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>SkillAssembler</h3>
+  <p>主 agent 每个 run 的 skill 选择器。先用 embedding 召回候选；候选太多时先 LLM shortlist；再把完整 skill 正文截断后交给 LLM final selection。</p>
+  <div class="subflow">
+    <div>query = task_description 或 AgentService 提供的 skill_selection_context。</div>
+    <div>embedding top-k 召回 selection candidates。</div>
+    <div>shortlist 阶段只看摘要，返回最多 N 个 skill names。</div>
+    <div>final 阶段看候选正文，返回最终激活 skill names。</div>
+    <div>加载正文，strip frontmatter，生成 SkillContext。</div>
+  </div>
+  <p>详细 prompt 见 <a href="prompt-atlas.html#skill-assembler">Prompt Atlas</a>。</p>
+</article>
+
+<article class="module">
+  <h3>activation injection</h3>
+  <p>ContextBuilder 不把 skill 正文塞进 system prompt，而是每个 skill 生成一条 user-role activation message。这样 skills 的正文和主 system prompt 分层清晰。</p>
+  <pre>[SYSTEM: The "{skill.name}" skill (version {skill.version}) is active for this run.
+Follow its instructions as active guidance unless the user overrides them.]
+
+{skill.content}</pre>
+</article>
+
+<article class="module">
+  <h3>drafts / reviews / publisher</h3>
+  <p>草稿、审核和发布构成 skill 的人工治理链路。Learning 只生成候选和草稿，不直接把新能力静默注入 published 目录。</p>
+  <div class="subflow">
+    <div>DraftService 保存草稿内容和 metadata。</div>
+    <div>ReviewService 记录审核意见、状态、决策。</div>
+    <div>SkillPublisher 把通过审核的草稿写成正式 skill spec。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>learning</h3>
+  <p>从用户接受后的 Task evidence 中提取学习候选，合成新 skill 或修订草稿，再经过 safety/eval/review。Safety/Eval 只评估 skill draft，不评估 task result。</p>
+  <div class="subflow">
+    <div>Task accepted 后触发 learning；一个 task 的所有 runs 都进入证据包，并标记 final_accepted_run_id。</div>
+    <div>LearningService 构建 learning candidates。</div>
+    <div>EvidencePacket 收集 task summary、session excerpts、tool names、user acceptance event 和 revision history。</div>
+    <div>SkillDraftSynthesizer 用 LLM 生成 frontmatter/content/change_reason JSON。</div>
+    <div>SafetyChecker 做确定性扫描，Eval 评估后进入 draft/review。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>missing skill guidance</h3>
+  <p>当 team node 没有匹配 published skill 时，TaskSkillResolver 生成一次性 ephemeral guidance。它以 SkillContext 形式进入 delegated agent，但不会发布为正式 skill。</p>
+  <div class="subflow">
+    <div>输入 task goal、user request、node id/task、skill query、required capabilities。</div>
+    <div>LLM 返回 guidance_name、description、content、tags。</div>
+    <div>若失败，用 fallback payload 生成基础指导。</div>
+    <div>SkillContext name = <code>ephemeral:{guidance_name}</code>，version = <code>ephemeral:{guidance_id}</code>。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/tasks.html
+++ b/projcet_review/backend_blueprint/tasks.html
@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Tasks 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Tasks</h1><p>Tasks 模块把“需要执行和跟踪”的用户请求从普通聊天中拆出来，形成有状态的内部任务。它包含路由、计划、技能解析、事实证据、用户验收和 task store。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="services.html">Services</a><a href="coordinator.html">Coordinator</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>Router</strong>simple/task/revise/new/close</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>TaskRecord</strong>创建或复用 open task</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Planner</strong>single 或 team graph</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Run</strong>team + main AgentLoop</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>Evidence</strong>事实记录，不判断</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>User Acceptance</strong>accept/revise/abandon</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>models / store / service</h3>
+  <p><code>TaskRecord</code> 保存 task_id、session_id、description、goal、status、run_ids、acceptance history、metadata。TaskService 提供 create/start/complete/acceptance/close/abandon 等状态操作。</p>
+  <div class="subflow">
+    <div>router 决定进入 Task 后创建或复用 active task。</div>
+    <div>每次 attempt 调用 start_run 记录 user_message 和 attempt_index。</div>
+    <div>run 完成后构建 TaskEvidencePacket，状态进入 awaiting_acceptance。</div>
+    <div>用户验收后进入 closed（accepted）、needs_revision 或 abandoned。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>MainAgentRouter</h3>
+  <p>独立 LLM 调用，只负责路由，不回答用户。输入 active task 摘要、最近对话、当前 message 和 intent-agent skill guidance，输出紧凑 JSON。</p>
+  <div class="subflow">
+    <div>provider 不可用时 fallback：有 active task 则 continue_task，否则 simple_chat。</div>
+    <div>system message 约束“只路由、不解释、只 JSON”。</div>
+    <div>user prompt 包含 actions、critical policy、active task、recent conversation、current message。</div>
+    <div>解析 action，映射成 MainAgentDecision。</div>
+  </div>
+  <p>详细 prompt 字段见 <a href="prompt-atlas.html#intent-router">Prompt Atlas</a>。</p>
+</article>
+
+<article class="module">
+  <h3>TaskExecutionPlanner</h3>
+  <p>决定当前 attempt 是单 agent 还是先跑小 team。它要求模型返回 JSON schema：mode、reason、strategy、nodes、final_synthesis_instruction。</p>
+  <div class="subflow">
+    <div>选择 auxiliary/main provider。</div>
+    <div>输入 task goal、当前用户请求、attempt index 和必要的 task history。</div>
+    <div>如果 team，解析 nodes 为 ExecutionGraph 并 validate。</div>
+    <div>调用 TaskSkillResolver 为 team node 绑定 published skills 或 ephemeral guidance。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>TaskSkillResolver</h3>
+  <p>给 planner 生成的泛型 team node 解析能力来源：先 embedding 召回 published skills，再让 LLM 从候选中选；没有匹配则生成一次性 ephemeral guidance。</p>
+  <div class="subflow">
+    <div>构造 query：skill_query、node.task、required_capabilities、task.goal、user_message。</div>
+    <div>embedding top-8 召回候选 skill。</div>
+    <div>LLM 返回候选 skill name JSON array。</div>
+    <div>若为空，EphemeralGuidanceSynthesizer 生成临时 SkillContext 注入 node。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>EvidenceBuilder / User Acceptance</h3>
+  <p>EvidenceBuilder 从 session 中提取 run evidence、tool summaries、team node results。Evidence 只记录事实，不判断、不打分、不 gate，也不生成 revision prompt；Task 是否完成只由用户验收决定。</p>
+  <div class="subflow">
+    <div>主 run 完成后收集 assistant output、tool result、team result。</div>
+    <div>渲染 evidence packet 文本，用于审计、展示和后续 skill learning。</div>
+    <div>用户 accept 后关闭 task，并把整个 task 的所有 runs 标记为 Accepted Task Evidence。</div>
+    <div>用户 revise 时只把 revision message 和必要 task history 带入下一轮执行，不把整包 evidence 自动塞进 prompt。</div>
+  </div>
+</article>
+</section></main></body></html>
--- a/projcet_review/backend_blueprint/tools.html
+++ b/projcet_review/backend_blueprint/tools.html
@ -0,0 +1,79 @@
+<!doctype html>
+<html lang="zh-CN">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Tools 模块蓝图</title><link rel="stylesheet" href="blueprint.css"></head>
+<body><main class="page">
+<header class="topbar"><h1>Tools</h1><p>Tools 模块定义 Beaver 可调用工具的规格、注册、选择和执行。它把内置工具与 MCP 工具统一成 provider tool schema，再把模型返回的 tool_calls 安全地执行成 tool result。</p></header>
+<nav class="nav"><a href="index.html">索引</a><a href="engine.html">Engine</a><a href="skills.html">Skills</a><a href="prompt-atlas.html">Prompt Atlas</a></nav>
+<section class="content">
+<h2>大模块流程</h2>
+<div class="flow">
+  <div class="step"><strong>注册</strong>内置工具 + MCP wrapper</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>选择</strong>always + skill hints + embedding top-k</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>导出 schema</strong>provider function/tool schema</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>执行</strong>ToolExecutor 执行 tool_call</div><div class="arrow">-&gt;</div>
+  <div class="step"><strong>回填</strong>tool message + session event</div>
+</div>
+
+<h2>小模块拆分</h2>
+<article class="module">
+  <h3>base</h3>
+  <p><code>ToolSpec</code> 描述 name、description、input schema、always flag；<code>ToolContext</code> 携带 workspace、session、user、services；<code>ToolResult</code> 统一 success/content/error。</p>
+  <div class="subflow">
+    <div>工具实现暴露成 BaseTool 或 ObjectBackedTool。</div>
+    <div>ToolSpec 同时可转 MCP descriptor、provider schema、embedding candidate。</div>
+    <div>执行结果必须是 ToolResult，AgentLoop 再转成 provider tool message。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>registry</h3>
+  <p>ToolRegistry 是工具目录。EngineLoader 会注册内置工具，MCP manager connect_all 后也把外部 MCP 工具注册进来。</p>
+  <div class="subflow">
+    <div>register tool spec 与 callable。</div>
+    <div>list_specs/list_always_specs/get_specs 供 ToolAssembler 使用。</div>
+    <div>export_selected_provider_schemas 输出本轮模型可见工具。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>ToolAssembler</h3>
+  <p>按 run 选择工具，不做 LLM prompt。选择顺序固定：always tools、配置里的默认 always names、activated skills 的 tool hints、embedding top-k。</p>
+  <div class="subflow">
+    <div>先加入 registry.list_always_specs。</div>
+    <div>再加入默认 <code>memory</code>、<code>session_search</code>。</div>
+    <div>收集 activated skill 的 <code>tool_hints</code> 或 loader 中的 skill tool hints。</div>
+    <div>对剩余工具做 embedding retrieve，补充 top-k。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>runtime executor</h3>
+  <p>ToolExecutor 接收 provider 返回的 ToolCallRequest，查 registry，解析 arguments，传入 ToolContext，捕获异常并返回 ToolResult。</p>
+  <div class="subflow">
+    <div>模型返回 tool_calls。</div>
+    <div>AgentLoop 序列化并记录 assistant tool call。</div>
+    <div>ToolExecutor 执行对应工具。</div>
+    <div>AgentLoop 把 result.content 追加为 role=tool message。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>builtins</h3>
+  <p>内置工具包括 terminal、filesystem、web、memory、session_search、skill_view、skills_admin、cron、utility、echo。它们覆盖本地开发、记忆、会话检索、skill 管理和定时任务。</p>
+  <div class="subflow">
+    <div>工具从 ToolContext 取 workspace/services。</div>
+    <div>执行具体 IO 或服务动作。</div>
+    <div>返回文本结果，进入下一轮模型上下文。</div>
+  </div>
+</article>
+
+<article class="module">
+  <h3>mcp wrapper</h3>
+  <p>把外部 MCP tool 适配成 Beaver ToolSpec/callable，使外部工具和内置工具对 AgentLoop 呈现同一种接口。</p>
+  <div class="subflow">
+    <div>MCP manager connect_all。</div>
+    <div>为每个外部 tool 建 wrapper。</div>
+    <div>注册进 ToolRegistry，后续由 ToolAssembler 选择。</div>
+  </div>
+</article>
+</section></main></body></html>