16gagent/output/agent-architecture-audit.md

Agent Architecture Audit — 小龙 🐉 全系统

审计日期: 2026-06-05 22:13 CST 审计范围: scripts/, memory/, test/, rules/, workspace config, prompts 审计方法: 静态分析 + 架构模式检查 + 运行行为验证

---

第一部分：代码质量审计

发现清单

Critical

C-01: Domain Matcher 生成无效 FK 引用

• 位置: model-contract.mjs → createContract() → FK 生成逻辑
• 问题: 生成 REFERENCES boards(id)、REFERENCES assignees(id)、REFERENCES equipments(id) 等指向不存在的表的外键
• 影响: 每次生成新 domain 都会破坏 SQLite schema，导致 INSERT/DELETE 测试失败
• 根因: FK 生成只看 field name 是否含 Id 后缀，不验证目标表是否存在
• 修复: createContract 阶段校验 FK 目标表是否在 entities 列表中

C-02: Domain Matcher 误匹配导致实体污染

• 位置: project-intake-agent.mjs → matchDomain()
• 问题: "仓库出入库"→NoteApp，"合同管理"→OAFlow，"设备巡检"→generic
• 影响: 2/3 真实项目匹配到错误 domain，产生无关组件（NoteCard、contracts/approvals 表）
• 根因: 纯关键词计数匹配，无权重/否定词机制
• 修复: 增加关键词权重、否定关键词、最高频实体优先

High

H-01: Duplicate Export Bug

• 位置: frontend-builder-agent.mjs → service 文件生成逻辑
• 问题: items.ts 生成了两遍 export function get() 和 export function post()
• 影响: TypeScript 编译失败
• 根因: Domain 模板和 generic 模板叠加生成，无去重

H-02: Singularize Bug — equipments vs equipment

• 位置: model-contract.mjs → toTableName()
• 问题: equipment 被 singularize 为 equipments（添加了 s），但 SQLite 表名是 equipment
• 影响: FK 引用失败
• 根因: singularize 规则对不可数名词处理有误

H-03: Domain Bleed — 跨域组件污染

• 位置: frontend-builder-agent.mjs → component 生成逻辑
• 问题: NoteApp domain 的 NoteCard 组件被注入到仓库出入库系统
• 影响: 构建失败（类型不匹配）
• 根因: component 生成不检查当前 domain 是否为 note

H-04: 3.9GB .tmp-benchmark 目录未清理

• 位置: /Users/a1234/.openclaw/workspace/.tmp-benchmark/
• 问题: 历史 benchmark 产生的临时文件占 3.9GB
• 影响: 磁盘浪费
• 根因: 无自动清理机制

Medium

M-01: Guard Scripts 全部使用相同 import 模式但无共享基类

• 位置: scripts/guard-*.mjs (6 个文件)
• 问题: 每个 guard 都独立 import readdirSync, readFileSync, existsSync，逻辑高度相似
• 影响: 维护成本高，改一处要改 6 处

M-02: type: "commonjs" 但所有脚本使用 ESM

• 位置: package.json
• 问题: "type": "commonjs" 但所有 .mjs 文件使用 import/export
• 影响: .mjs 扩展名强制 ESM 所以能跑，但 package.json 声明与实际不符
• 风险: 低（.mjs 优先级高于 type 字段），但容易误导

M-03: Active Memory 测试存在但脚本已删除

• 位置: test/active-memory/*.test.mjs (31 个文件) vs scripts/active-memory-*.mjs (不存在)
• 问题: package.json 引用的 active-memory:* 脚本全部不存在
• 影响: 6 个 npm script 全部不可用
• 根因: 脚本被删除但测试和 package.json 未清理

M-04: Dream Cycle 日志但事件数极少

• 位置: memory/.dreams/events.jsonl (8 events), memory/.dreams/short-term-recall.json (350 entries)
• 问题: Dream Cycle 每天运行但事件捕获极少
• 影响: 记忆系统实际贡献度存疑

Low

L-01: .memory-core-test/ 和 .active-memory-precompute-cache/ 空目录

• 位置: workspace root
• 影响: 无功能影响，只是残留

L-02: 多个 report 文件堆积在 workspace root

• 位置: benchmark-report.md, certification-report.md, capability-report.md 等 10+ 个文件
• 影响: workspace 混乱，应归档到 docs/reports/

---

第二部分：性能与瘦身审计

存储浪费分析

路径	大小	状态
.tmp-benchmark/	3.9 GB	🔴 立即删除
output/	1.3 GB	🟡 按需保留
.benchmark/	87 MB	🟡 可归档
.codegraph/	19 MB	🟢 保留
.tmp-pr12-test/	16 KB	🔴 删除
.tmp-pr13-test/	28 KB	🔴 删除
.memory-core-test/	0 B	🔴 删除空目录
.active-memory-precompute-cache/	0 B	🔴 删除空目录

总浪费: ~4 GB

代码冗余分析

冗余类型	位置	影响
Guard 脚本重复	6× guard-*.mjs	维护成本 ×6
Contract 相关脚本重复	model-contract + contract-consistency-test + contract-e2e (1,630 行)	测试和核心逻辑边界模糊
Active Memory 测试残留	31 个 test 文件，0 个实现	测试无效
Workspace root 报告堆积	10+ 个 .md/.json	混乱

Token 浪费分析

浪费源	估算
MEMORY.md 注入上下文（每次对话）	~2,500 tokens
AGENTS.md + SOUL.md + IDENTITY.md + USER.md + TOOLS.md	~3,000 tokens
HEARTBEAT.md	~500 tokens
capability-registry.json (注入 context)	~800 tokens
其他 workspace files	~1,000 tokens
总注入上下文	~7,800 tokens/会话

优化空间: capability-registry.json 和 TOOLS.md 注入无实际使用价值（工具由 OpenClaw 管理），可节省 ~1,800 tokens。

必须保留 / 建议删除

必须保留

• scripts/project-intake-agent.mjs — Generator 入口
• scripts/architecture-agent.mjs — 架构生成
• scripts/frontend-builder-agent.mjs — 前端生成
• scripts/backend-builder-agent.mjs — 后端生成
• scripts/fullstack-composer-agent.mjs — 全栈组合
• scripts/model-contract.mjs — 核心数据模型
• scripts/lib/deprecation-warning.mjs — 工具函数
• memory/daily/ — 日常记忆
• memory/vault.md — 动态记忆
• memory/registers/ — 持久化事实
• test/e2e-regression.test.mjs — 核心回归测试
• test/software-factory-core.test.mjs — 核心测试

建议保留

• scripts/guard-all.sh — 统一入口
• scripts/guard-runtime-core.mjs — 最有价值的 guard
• scripts/smoke-test.mjs — 快速验证
• scripts/dream-cycle.sh — 记忆维护
• scripts/memory-sync.sh — 记忆同步
• scripts/memory-auto.sh — 记忆自动化

可选

• scripts/guard-dreaming-phase.mjs — 低频使用
• scripts/guard-memory-backend.mjs — 低频使用
• scripts/guard-tool-path.mjs — 低频使用
• scripts/guard-tool-trace.mjs — 低频使用
• scripts/check-deprecations.mjs — 低频使用
• scripts/electron-builder-agent.mjs — Real World 未使用
• scripts/release-builder-agent.mjs — Real World 未使用
• test/active-memory/ (31 个文件) — 实现已删除

建议删除

• .tmp-benchmark/ (3.9 GB) — 纯浪费
• .tmp-pr12-test/, .tmp-pr13-test/ — 临时残留
• .memory-core-test/, .active-memory-precompute-cache/ — 空目录
• scripts/contract-consistency-test.mjs — 可合并到 e2e-regression
• scripts/contract-e2e.mjs — 可合并到 e2e-regression
• workspace root 的 10+ 个 report 文件 → 归档到 docs/reports/

---

第三部分：任务规划能力审计

当前状态

User 输入
    ↓
小龙理解意图（LLM 推理）
    ↓
直接执行（调用工具）
    ↓
验证结果
    ↓
返回用户

缺失环节

环节	存在？	说明
Planner Agent	❌	无独立规划器
Task Decomposition	❌	无自动任务拆解
Dynamic Task Tree	❌	Goal→SubGoal→Task→Action 不支持
Task Rollback	❌	失败后无回滚机制
Failure Replanning	❌	失败后靠 LLM 临时推理，无结构化重规划
Complexity Detection	⚠️ 部分	靠 LLM 推理判断，无显式机制
Plan Persistence	⚠️ 部分	update_plan 工具存在但仅当前会话有效

评估

• 简单任务: 直接执行 ✅ 正确
• 复杂任务: 仍直接执行，靠 LLM 推理拆解 ⚠️ 不稳定
• 多步骤任务: 会使用 update_plan 跟踪进度 ✅ 但无自动拆解
• 失败恢复: 靠 LLM 自行判断重试 ⚠️ 不可靠

评分: 35/100

优势:

• LLM 推理能力作为隐式 planner 能处理大多数任务
• update_plan 提供了基本的任务跟踪

缺陷:

• 无显式 planning 层
• 无 complexity classifier
• 无 structured replanning
• 无 task dependency graph
• 无 parallel task execution planning

改进方案

Level 0 (当前): LLM 推理 → 直接执行
Level 1 (推荐): LLM 推理 → Plan Check → 执行 → 验证
Level 2 (进阶): Planner Agent → Task Graph → 执行器 → 反思
Level 3 (理想): 自适应规划 → 动态任务树 → 失败重规划 → 学习

立即可做: 在 AGENTS.md 中增加 planning 协议 — 复杂任务必须先输出 plan 再执行。

---

第四部分：记忆系统审计

记忆层全景

记忆层	路径	行数	真正使用？	使用频率	实际贡献
MEMORY.md	workspace root	126	✅ 每会话注入	每次	⭐⭐⭐⭐⭐ 核心
AGENTS.md	workspace root	128	✅ 每会话注入	每次	⭐⭐⭐⭐ 行为指南
SOUL.md	workspace root	30	✅ 每会话注入	每次	⭐⭐⭐⭐ 人格
IDENTITY.md	workspace root	19	✅ 每会话注入	每次	⭐⭐⭐ 基础
USER.md	workspace root	13	✅ 每会话注入	每次	⭐⭐⭐ 基础
TOOLS.md	workspace root	21	✅ 每会话注入	每次	⭐⭐ 低（工具由 OpenClaw 管理）
HEARTBEAT.md	workspace root	52	⚠️ 心跳时	低频	⭐⭐⭐ 心跳检查
memory/vault.md	memory/	~200	⚠️ 按需读取	中频	⭐⭐⭐⭐ 动态记忆
memory/daily/	memory/daily/	~700	⚠️ 按需读取	中频	⭐⭐⭐⭐ 日志
memory/registers/	memory/registers/	~200	⚠️ 按需读取	低频	⭐⭐⭐ 持久事实
memory/USER.md	memory/	~50	⚠️ 按需读取	低频	⭐⭐ 与 workspace USER.md 重复
memory/SESSION_START.md	memory/	~30	⚠️ 启动时	低频	⭐⭐ 协议文件
memory/core/	memory/core/	~300	❌ 极少读取	极低	⭐ 与 registers 重复
memory/entities/	memory/entities/	~100	❌ 极少读取	极低	⭐ 实体记忆，价值低
memory/projects/	memory/projects/	~400	⚠️ 按需	低频	⭐⭐⭐ 项目记忆
memory/CONTRADICTION.md	memory/	~50	❌ 从未读取	无	⭐ 无贡献
memory/companion-log.md	memory/	~50	❌ 从未读取	无	⭐ 无贡献
memory/pet-tuanzi.md	memory/	~30	❌ 从未读取	无	⭐ 无贡献
memory/index.md	memory/	~50	❌ 从未读取	无	⭐ 无贡献
memory/.dreams/	memory/.dreams/	~350	⚠️ dream-cycle	低频	⭐⭐ 短期召回
memory/2026-06-04.md	memory/	~50	⚠️ 按需	低频	⭐⭐ 旧格式日志

问题诊断

1. 记忆冗余

• memory/USER.md 与 workspace/USER.md 重复
• memory/core/ 与 memory/registers/ 功能重叠
• memory/SESSION_START.md 与 AGENTS.md 功能重叠

2. 记忆污染

• memory/pet-tuanzi.md — 宠物信息，与核心工作无关
• memory/companion-log.md — 伴侣日志，从未使用
• memory/CONTRADICTION.md — 矛盾记录，从未使用

3. 记忆孤岛

• memory/core/ 目录有 6 个文件但几乎从不被读取
• memory/entities/ 有 2 个实体文件但从未被检索
• memory/index.md 存在但无实际索引功能

4. Dream Cycle 效率低

• events.jsonl 只有 8 条事件
• short-term-recall.json 有 350 条但从未被主动检索
• Dream Cycle 每天运行但产出极少

保留/删除/替代

文件	操作	原因
memory/core/	删除	与 registers 重复，从未被读取
memory/entities/	删除	从未被检索，价值低
memory/CONTRADICTION.md	删除	从未使用
memory/companion-log.md	删除	从未使用
memory/pet-tuanzi.md	归档	移到 memory/archive/
memory/index.md	删除	无实际索引功能
memory/USER.md	删除	与 workspace USER.md 重复
memory/SESSION_START.md	合并	合并到 AGENTS.md
memory/2026-06-04.md	归档	旧格式，移到 memory/daily/

---

第五部分：工具系统审计

工具价值排行榜

高价值（每次会话都用）

工具	价值
read / write / edit	⭐⭐⭐⭐⭐ 文件操作核心
exec	⭐⭐⭐⭐⭐ 命令执行核心
context-mode__ctx_search	⭐⭐⭐⭐⭐ 知识检索
context-mode__ctx_execute	⭐⭐⭐⭐⭐ 代码沙箱
context-mode__ctx_index	⭐⭐⭐⭐ 知识存储
context-mode__ctx_fetch_and_index	⭐⭐⭐⭐ Web 内容索引
web_search / web_fetch	⭐⭐⭐⭐ 信息获取
memory_search / memory_get	⭐⭐⭐⭐ 记忆检索
cron	⭐⭐⭐⭐ 定时任务

中价值（偶尔使用）

工具	价值
sessions_spawn / sessions_yield	⭐⭐⭐ 子任务
update_plan	⭐⭐⭐ 任务跟踪
session_status	⭐⭐ 状态查看
image	⭐⭐ 图像分析
video_generate	⭐⭐ 视频生成

低价值（极少使用）

工具	价值
context-mode__ctx_insight	⭐ Dashboard
context-mode__ctx_doctor	⭐ 诊断
context-mode__ctx_upgrade	⭐ 升级
context-mode__ctx_purge	⭐ 清理
context-mode__ctx_stats	⭐ 统计

工具问题

1. context-mode 工具过多 — 10 个 ctx_* 工具，功能重叠
2. sessions 工具链复杂 — sessions_list/history/send/spawn/yield，使用率低
3. image/video 工具未充分利用 — 生成式能力几乎未使用

---

第六部分：Prompt 系统审计

注入上下文分析

文件	Token 估算	每会话注入	冗余度
AGENTS.md	~1,500	✅	低
SOUL.md	~400	✅	低
IDENTITY.md	~250	✅	中（与 SOUL.md 重叠）
USER.md	~200	✅	中（与 memory/USER.md 重叠）
TOOLS.md	~300	✅	高（工具由 OpenClaw 管理）
MEMORY.md	~2,500	✅	低
HEARTBEAT.md	~700	✅	低

总注入: ~5,850 tokens/会话

冲突检测

冲突	严重度
IDENTITY.md 中的性格定义 vs SOUL.md 中的 Vibe 定义	低（互补）
USER.md vs memory/USER.md 重复	中（浪费 token）
TOOLS.md 说"工具速查" vs 实际工具由 OpenClaw 管理	中（误导）
AGENTS.md 的"执行流程" vs MEMORY.md 的"工程范式" 重叠	低（强化）

精简方案

操作	节省 Token
删除 TOOLS.md（工具由 OpenClaw 管理）	~300
合并 IDENTITY.md 到 SOUL.md	~200
删除 workspace USER.md，保留 memory/USER.md	~200
精简 MEMORY.md 中的重复内容	~300
总节省	~1,000 tokens

---

第七部分：AI Agent 反模式检查

反模式	存在？	严重度	证据
Feature Creep (功能膨胀)	✅	🔴 High	Active Memory 系统：31 个测试文件但实现已删除
Over Engineering (过度设计)	✅	🟡 Medium	6 个 Guard 脚本做类似的事
Memory Overload (记忆过载)	✅	🟡 Medium	20+ 个记忆文件，多个从未使用
Tool Explosion (工具爆炸)	⚠️	🟡 Medium	10 个 ctx_* 工具，功能重叠
Prompt Bloat (Prompt 肥大)	⚠️	🟢 Low	~5,850 tokens，可控
Agent Drift (Agent 漂移)	⚠️	🟡 Medium	Domain Matcher 偏离用户意图
Context Pollution (上下文污染)	✅	🟡 Medium	workspace root 堆积 10+ 个报告文件
Architecture Debt (架构债务)	✅	🔴 High	Active Memory 脚本删除但测试残留
Reasoning Collapse (推理退化)	❌	-	未观察到
Planning Collapse (规划退化)	❌	-	原生就弱，非退化

---

第八部分：未来升级空间

当前等级评估

Level 1: Script          ✅ 已超越
Level 2: Workflow         ✅ 已超越
Level 3: Agent           ✅ 当前位置 — 隐式规划，工具调用，记忆系统
Level 4: Multi-Agent     ⚠️ 部分具备 — sessions_spawn 但无协调协议
Level 5: Autonomous      ❌ 未达到
Level 6: Self-Improving  ❌ 未达到
Level 7: Self-Evolving   ❌ 未达到

当前: Level 3 — Agent

距离 Level 4 (Multi-Agent) 还缺什么

1. Agent 间通信协议 — 当前 sessions_send 是消息传递，非结构化协议
2. 任务分配器 — 无中央调度器决定哪个 agent 处理什么任务
3. 共享状态 — agents 间无共享 memory/workspace（除了文件系统）
4. 角色定义 — 无专门化的 agent 角色（planner/executor/validator）
5. 冲突解决 — 多 agent 并发修改同一资源无锁机制

距离 Level 5 (Autonomous) 还缺什么

1. 目标驱动 — 当前是任务驱动，非目标驱动
2. 自主决策 — 无自主决定下一步做什么的能力
3. 环境感知 — 无持续监控外部环境变化
4. 资源管理 — 无自主管理 token/时间/存储预算

---

最终输出

1. 架构评分卡

维度	评分	说明
Planning	35/100	无显式 planner，靠 LLM 推理
Memory	55/100	多层架构但冗余严重，实际使用率低
Tool Use	75/100	核心工具优秀，但 ctx_* 过多
Reasoning	80/100	LLM 推理能力作为隐式推理层
Reliability	70/100	生成器可靠性高，但 domain matcher 不稳定
Maintainability	50/100	架构债务明显，残留代码多
Scalability	45/100	无 multi-agent 协调，无自治能力

综合评分: 59/100

2. 风险排行榜 Top 10

#	风险	严重度	影响
1	Domain Matcher 系统性误匹配	🔴 Critical	2/3 真实项目生成错误
2	FK 生成不验证目标表存在	🔴 Critical	每次生成都会破坏 schema
3	Active Memory 系统残留	🔴 High	31 个无效测试，6 个无效 npm script
4	.tmp-benchmark 3.9GB 未清理	🔴 High	磁盘浪费
5	Singularize 规则 bug	🟡 High	equipment→equipments 破坏 FK
6	Domain Bleed 组件污染	🟡 High	跨域组件导致构建失败
7	Duplicate Export 生成	🟡 Medium	service 文件重复导出
8	记忆系统冗余严重	🟡 Medium	20+ 文件多个无用
9	无显式 Planning 层	🟡 Medium	复杂任务不稳定
10	Workspace 根目录混乱	🟢 Low	10+ 个报告文件堆积

3. 优化路线图

立即修复（今天）

1. rm -rf .tmp-benchmark/ .tmp-pr12-test/ .tmp-pr13-test/ .memory-core-test/ .active-memory-precompute-cache/ — 释放 3.9GB
2. 修复 model-contract.mjs FK 生成逻辑 — 验证目标表存在
3. 修复 matchDomain() — 增加关键词权重和否定词
4. 删除 test/active-memory/ (31 个无效测试)
5. 清理 package.json 中的 6 个无效 npm script

1 周内修复

1. 修复 singularize 规则 — equipment 不可数名词处理
2. 修复 domain bleed — component 生成检查当前 domain
3. 修复 duplicate export — service 文件生成去重
4. 清理记忆系统 — 删除 memory/core/, memory/entities/, memory/CONTRADICTION.md, memory/companion-log.md
5. 合并 IDENTITY.md 到 SOUL.md，删除 TOOLS.md
6. 归档 workspace root 的 10+ 个报告文件到 docs/reports/

1 个月内修复

1. 重构 Guard 脚本 — 提取共享基类，6→2 个文件
2. 增加显式 Planning 协议 — 复杂任务先输出 plan
3. 合并 contract-consistency-test + contract-e2e 到 e2e-regression
4. 优化 Dream Cycle — 增加事件捕获频率
5. 减少注入上下文 — 目标从 ~5,850 降到 ~4,000 tokens

长期规划

1. 设计 Multi-Agent 协调协议
2. 实现显式 Planner Agent
3. 实现 Complexity Classifier
4. 实现 Task Dependency Graph
5. 实现 Failure Replanning

4. 删除清单

删掉后系统会更强的东西

删除项	大小/行数	理由
.tmp-benchmark/	3.9 GB	纯浪费
test/active-memory/ (31 files)	~15,000 行	实现已删除，测试无效
memory/core/ (6 files)	~300 行	与 registers 重复，从未读取
memory/entities/ (2 files)	~100 行	从未被检索
memory/CONTRADICTION.md	~50 行	从未使用
memory/companion-log.md	~50 行	从未使用
memory/index.md	~50 行	无实际索引功能
scripts/contract-consistency-test.mjs	776 行	可合并到 e2e-regression
scripts/contract-e2e.mjs	206 行	可合并到 e2e-regression
TOOLS.md	21 行	工具由 OpenClaw 管理，注入浪费
workspace root 10+ report files	~50,000 行	归档到 docs/reports/

预计释放: 3.9GB 磁盘 + ~16,500 行代码 + ~500 tokens/会话

5. 最终结论

如果我是这个项目的 CTO：

会保留

• Generator 核心 (7 个 agent scripts + model-contract) — 这是真正的价值
• 记忆系统核心 (MEMORY.md + daily/ + vault.md + registers/) — 经过验证有效
• E2E 测试 (e2e-regression + smoke-test + guard-all) — 质量保障
• OpenClaw 基础设施 — 工具系统、会话管理、cron

会删除

• Active Memory 全系统 — 脚本已删，测试残留，package.json 引用无效
• 3.9GB 临时文件 — 无理由保留
• 6 个 Guard 脚本中的 4 个 — 合并到 guard-all.sh 一个脚本
• 记忆系统中的孤岛文件 — core/, entities/, CONTRADICTION.md, companion-log.md, index.md
• workspace root 的报告堆积 — 归档到 docs/

会重构

1. Domain Matcher — 从纯关键词计数改为加权匹配 + 否定词 + 实体优先级
2. FK 生成逻辑 — 增加目标表存在性验证
3. Guard 脚本 — 从 6 个独立脚本重构为 1 个可配置的 guard 框架
4. 记忆系统 — 从"写入优先"重构为"读取优先"，删除从未被读取的文件

为什么

这个项目的核心问题不是功能不够，而是功能膨胀后的维护成本。

Generator 本身是优秀的（Real World Qualification 证明了这一点），但围绕它生长了大量从未使用的基础设施（Active Memory 测试、Guard 脚本、记忆孤岛）。

下一步应该做的不是加功能，而是减功能。 删掉 3.9GB 的临时文件、16,500 行无效测试、6 个重复的 Guard 脚本、10 个从未读取的记忆文件。

系统会因此变得更强。

---

审计完成 — 小龙 🐉 Agent Architecture Audit