7910717b1e
All checks were successful
CI / test (push) Successful in 3m9s
架构审查总结报告入库：5 个深化候选（scheduler 抽取、决策日志去重内化、 状态机归一、过渡残留清理、前端标签单一出口）的痛点/深化/红利、全景图与 余下机会。按先例归档到 docs/archive/ 并登记 docs/README.md 与 archive/README.md 两处索引。
179 lines
11 KiB
HTML
179 lines
11 KiB
HTML
<!doctype html>
|
||
<html lang="zh-CN">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>架构审查总结 — AgentEvalTool</title>
|
||
<script src="https://cdn.tailwindcss.com"></script>
|
||
<script type="module">
|
||
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
|
||
mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
|
||
</script>
|
||
<style>
|
||
.seam { stroke-dasharray: 4 4; }
|
||
.deep { background: linear-gradient(135deg, #0f172a, #1e293b); color: #e2e8f0; }
|
||
</style>
|
||
</head>
|
||
<body class="bg-stone-50 text-slate-900 font-sans">
|
||
<main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
|
||
|
||
<!-- ══════════════ HEADER ══════════════ -->
|
||
<header class="space-y-4">
|
||
<h1 class="text-3xl font-serif font-bold">架构审查总结 · AgentEvalTool</h1>
|
||
<p class="text-sm text-slate-500">2026-08-20 ～ 21 · 智能评估子系统深化 · 5 个候选全部落地 · 零行为变化</p>
|
||
</header>
|
||
|
||
<!-- ══════════════ 数字 ══════════════ -->
|
||
<section class="grid grid-cols-2 md:grid-cols-5 gap-4">
|
||
<div class="bg-white rounded-lg border border-slate-200 p-4 text-center">
|
||
<div class="text-3xl font-serif font-bold">5</div>
|
||
<div class="text-xs uppercase tracking-wider text-slate-400 mt-1">候选落地</div>
|
||
</div>
|
||
<div class="bg-white rounded-lg border border-slate-200 p-4 text-center">
|
||
<div class="text-3xl font-serif font-bold">4</div>
|
||
<div class="text-xs uppercase tracking-wider text-slate-400 mt-1">提交推送</div>
|
||
</div>
|
||
<div class="bg-white rounded-lg border border-slate-200 p-4 text-center">
|
||
<div class="text-3xl font-serif font-bold">870</div>
|
||
<div class="text-xs uppercase tracking-wider text-slate-400 mt-1">测试通过（原 863）</div>
|
||
</div>
|
||
<div class="bg-white rounded-lg border border-slate-200 p-4 text-center">
|
||
<div class="text-3xl font-serif font-bold">−412</div>
|
||
<div class="text-xs uppercase tracking-wider text-slate-400 mt-1">app.py 行数（586→174）</div>
|
||
</div>
|
||
<div class="bg-white rounded-lg border border-slate-200 p-4 text-center">
|
||
<div class="text-3xl font-serif font-bold">0</div>
|
||
<div class="text-xs uppercase tracking-wider text-slate-400 mt-1">行为变化</div>
|
||
</div>
|
||
</section>
|
||
|
||
<!-- ══════════════ 全景图 ══════════════ -->
|
||
<section class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<h2 class="text-xl font-serif font-bold">深化后的智能评估子系统</h2>
|
||
<p class="text-sm text-slate-600">四个深模块各守一职，web 层退回纯 HTTP 翻译与启停接线。</p>
|
||
<pre class="mermaid">
|
||
flowchart TB
|
||
APP["web/app.py（174 行）<br/>lifespan 只做启停"] -->|"start() / stop()"| SCH
|
||
ROUTER["routers（HTTP 翻译）"] -->|"approve / cancel / submit_report"| LC
|
||
subgraph SCH["scheduler.py — 节奏（deep）"]
|
||
direction TB
|
||
S1["scan_once 扫描节拍"]
|
||
S2["触发原语 docker exec"]
|
||
end
|
||
SCH -.调用.-> LC
|
||
SCH -.补录.-> DL
|
||
subgraph LC["lifecycle.py — 状态机（deep）"]
|
||
direction TB
|
||
L1["_TRANSITIONS 唯一真相"]
|
||
L2["fail_eval 判失败接缝（表校验+CAS）"]
|
||
end
|
||
subgraph DL["decision_logs.py — 留痕（deep）"]
|
||
direction TB
|
||
D1["create（agent 上报·去重）"]
|
||
D2["append（平台落账·纯追加）"]
|
||
D3["count_decisions 计数原语"]
|
||
end
|
||
subgraph DOM["domain.py — 调度知识（deep）"]
|
||
direction TB
|
||
M1["时段解析 · 欠账 · 优先级"]
|
||
end
|
||
LC -.计数.-> DL
|
||
SCH -.入队.-> TQ["task_queue.py"]
|
||
TQ -.调度知识.-> DOM
|
||
LC -.落账.-> DL
|
||
classDef deep fill:#0f172a,color:#e2e8f0,stroke:#0f172a,stroke-width:3px;
|
||
class SCH,S1,S2,LC,L1,L2,DL,D1,D2,D3,DOM,M1 deep
|
||
</pre>
|
||
</section>
|
||
|
||
<section class="space-y-8">
|
||
|
||
<!-- ══════════════ 候选① ══════════════ -->
|
||
<article class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<div class="flex flex-wrap items-center gap-3">
|
||
<h2 class="text-lg font-serif font-bold">① scheduler 抽取</h2>
|
||
<span class="font-mono text-xs text-slate-400">182b0e5</span>
|
||
<span class="text-xs font-semibold px-3 py-1 rounded-full bg-emerald-100 text-emerald-800">已落地</span>
|
||
</div>
|
||
<ul class="text-sm space-y-1.5 text-slate-700">
|
||
<li>• <strong>痛点</strong>：web/app.py 住着约 400 行触发式执行编排，"worker 触发"一个概念散落四个模块</li>
|
||
<li>• <strong>深化</strong>：<code>scheduler.py</code> runtime 单例（<code>start()/stop()/scan_once()</code>），worker/planner 两处重复触发合并为一个触发原语</li>
|
||
<li>• <strong>红利</strong>：locality——触发式执行知识收敛一处；interface 即测试面——10 个测试改驱动 <code>scan_once()</code>，摆脱 TestClient</li>
|
||
</ul>
|
||
</article>
|
||
|
||
<!-- ══════════════ 候选② ══════════════ -->
|
||
<article class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<div class="flex flex-wrap items-center gap-3">
|
||
<h2 class="text-lg font-serif font-bold">② 决策日志去重内化</h2>
|
||
<span class="font-mono text-xs text-slate-400">182b0e5</span>
|
||
<span class="text-xs font-semibold px-3 py-1 rounded-full bg-emerald-100 text-emerald-800">已落地</span>
|
||
</div>
|
||
<ul class="text-sm space-y-1.5 text-slate-700">
|
||
<li>• <strong>痛点</strong>：接缝泄漏——内部去重机制逼着 5 处调用方塞递增 <code>attempt</code> "骗过"它</li>
|
||
<li>• <strong>深化</strong>：双入口——<code>create_decision_log</code>（agent 上报·去重，Gitea #6 契约）与 <code>append_decision_log</code>（平台落账·纯追加）；新增 <code>count_decisions</code> 计数原语收编 5 处裸查询</li>
|
||
<li>• <strong>红利</strong>：调用方不再需要知道去重存在；"数日志条数"知识只住在 decision_logs</li>
|
||
</ul>
|
||
</article>
|
||
|
||
<!-- ══════════════ 候选③ ══════════════ -->
|
||
<article class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<div class="flex flex-wrap items-center gap-3">
|
||
<h2 class="text-lg font-serif font-bold">③ 状态机归一</h2>
|
||
<span class="font-mono text-xs text-slate-400">58c2ad0</span>
|
||
<span class="text-xs font-semibold px-3 py-1 rounded-full bg-emerald-100 text-emerald-800">已落地</span>
|
||
</div>
|
||
<ul class="text-sm space-y-1.5 text-slate-700">
|
||
<li>• <strong>痛点</strong>：<code>_TRANSITIONS</code> 表存在却被 3 处 watchdog 直写绕过，每道 ADR-0011 新闸门都是一次新绕道机会</li>
|
||
<li>• <strong>深化</strong>：公开接缝 <code>fail_eval</code>——表校验 → repo CAS 条件写 → 决策日志留痕；CAS 冲突跳过不当故障</li>
|
||
<li>• <strong>红利</strong>：判失败只有一个写入口，非法转换与并发竞争各在一处被挡；4 个新契约测试锁定</li>
|
||
</ul>
|
||
</article>
|
||
|
||
<!-- ══════════════ 候选④ ══════════════ -->
|
||
<article class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<div class="flex flex-wrap items-center gap-3">
|
||
<h2 class="text-lg font-serif font-bold">④ 删除 ADR-0008 过渡残留</h2>
|
||
<span class="font-mono text-xs text-slate-400">2a0bcdd</span>
|
||
<span class="text-xs font-semibold px-3 py-1 rounded-full bg-emerald-100 text-emerald-800">已落地</span>
|
||
</div>
|
||
<ul class="text-sm space-y-1.5 text-slate-700">
|
||
<li>• <strong>痛点</strong>：过渡期"保签名"wrapper 完成使命后成噪声——2 个零调用死函数 + 6 个 1–3 行委托</li>
|
||
<li>• <strong>深化</strong>：直接删除，调用方改用 domain；5 个行为锁测试迁到 <code>test_intelligent_eval_domain.py</code> 直接锁定 domain</li>
|
||
<li>• <strong>红利</strong>：删除测试通过——复杂度直接消失；时段/欠账/优先级知识只剩 domain 一处</li>
|
||
</ul>
|
||
</article>
|
||
|
||
<!-- ══════════════ 候选⑤ ══════════════ -->
|
||
<article class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<div class="flex flex-wrap items-center gap-3">
|
||
<h2 class="text-lg font-serif font-bold">⑤ 前端标签单一出口</h2>
|
||
<span class="font-mono text-xs text-slate-400">d87aad5</span>
|
||
<span class="text-xs font-semibold px-3 py-1 rounded-full bg-emerald-100 text-emerald-800">已落地</span>
|
||
</div>
|
||
<ul class="text-sm space-y-1.5 text-slate-700">
|
||
<li>• <strong>痛点</strong>：三处手写标签映射与后端枚举字符串隐式耦合——后端加新类型前端静默显示裸字符串</li>
|
||
<li>• <strong>深化</strong>：<code>DECISION_TYPE_META</code> + <code>decisionTypeOf()</code> 收进 status.ts（含审查报告外的第三处双轨 ExecutionProcess）；STAT_CHIPS 从 EVAL_STATUS 派生</li>
|
||
<li>• <strong>红利</strong>：改标签只动一处；未识别类型显式标注"未识别·xxx"</li>
|
||
</ul>
|
||
</article>
|
||
|
||
</section>
|
||
|
||
<!-- ══════════════ 未动的与余下的 ══════════════ -->
|
||
<section class="bg-white rounded-xl border border-slate-200 shadow-sm p-8 space-y-4">
|
||
<h2 class="text-xl font-serif font-bold">边界与余下的机会</h2>
|
||
<ul class="text-sm space-y-2 text-slate-700">
|
||
<li>• <strong>刻意不动</strong>：ADR-0008 S3（domain 接受 Session 的解耦）——无第二个 adapter，抽象是为假想需求付账；会话/任务状态机不立转换表——写入点已集中，一个 adapter 是假想接缝</li>
|
||
<li>• <strong>余下的浅点</strong>：<code>repository.py</code>（1180 行跨 10 域，文件级 locality 欠佳，可按域拆分）；<code>api.ts</code>（908 行单文件，可分域）；前端 intelligent_eval 组件群无测试（5 个组件零覆盖）</li>
|
||
<li>• <strong>纪律提醒</strong>：新增决策日志类型时在 <code>DECISION_TYPE_META</code> 补一行；新增平台"置 failed"必须穿过 <code>fail_eval</code>；平台落账走 <code>append</code>，agent 上报走 <code>create</code></li>
|
||
</ul>
|
||
</section>
|
||
|
||
<footer class="text-xs text-slate-400 pt-4 border-t border-slate-200">
|
||
词汇：module / interface / implementation / depth / seam / adapter / leverage / locality（codebase-design）；领域名词取自 CONTEXT.md。
|
||
变更提交：182b0e5（候选①②）· 58c2ad0（候选③）· 2a0bcdd（候选④）· d87aad5（候选⑤）。
|
||
</footer>
|
||
</main>
|
||
</body>
|
||
</html>
|