---
title: NetaClaw 模块
created: 2026-04-13
updated: 2026-05-15
type: entity
tags: [module, agent, architecture]
sources: [packages/backend/src/modules/netaclaw/]
---

# NetaClaw 模块

项目的 AI Agent 引擎核心，实现了完整的 ReAct 循环推理、多 LLM 提供商支持、工具系统、记忆系统、技能系统、Multi-Agent Crew 编排、普通会话内子 Agent 委派、Session Tree 会话运行时、上下文压缩和外部渠道接入。2026-05-14 后，微信渠道重点演进为 `weixin-db` 本地群聊代理，并通过 [[desktop-op-module]] 与 `weixin_send_text` 形成双 Agent 自动回复链路。2026-05-15 后，NetaClaw 增加 MySQL 只读问数后端能力，数据源配置、SQL guard、schema/sample/query 工具和审计均收敛在主进程服务侧。

## 目录结构

```
netaclaw/
├── entity/          # 数据模型（含 legacy session/message 与 session-tree 新表）
├── controller/      # REST API
├── gateway/         # WebSocket 网关（/netaclaw + /crew 两个命名空间）
├── runtime/         # Agent 执行引擎核心（含 TodoStore、Thinking、Compaction）
├── memory/          # 长期记忆系统
├── tools/           # 工具定义、内置工具和 Operations 执行后端
├── browser-daemon/  # Netabrowser 后端 daemon（浏览器 session、拟人化交互、state/cookie）
├── plugins/         # LLM 提供商适配层（含 Thinking/Reasoning）
├── service/         # 业务逻辑（Skill、Crew、Channel、Executor、Tool Resolver、Chat Orchestrator）
├── platforms/       # 接入平台（预留）
├── session-tree/    # Session Tree provider、snapshot、projection、context builder
├── subagent/        # 子 Agent worker 进程、协议、runner
└── config.ts        # 模块配置
```

## 核心子系统（23个）

| 子系统 | 关键文件 | 职责 |
|--------|---------|------|
| [[agent-runtime]] | `runtime/agent.ts` | ReAct 循环执行引擎 |
| [[session-tree-runtime]] | `session-tree/provider.ts`, `session-tree/snapshot.ts` | 会话树、快照、active path、节点投影 |
| [[crew-orchestration]] | `service/crew_orchestrator.ts` | Multi-Agent 编排（委派/并行/升级） |
| [[websocket-gateway]] | `gateway/server.ts`, `gateway/crew_server.ts` | 实时通信（对话 + Crew 监控） |
| [[tool-system]] | `tools/builtin/*.ts` | 内置工具与执行链路 |
| [[image-generation-tools]] | `tools/builtin/text_to_image.ts`, `tools/builtin/image_to_image.ts` | 文生图、图生图和图片结果持久化 |
| [[runtime-process-events]] | `runtime/process_events.ts` | 长耗时工具/Skill 过程事件、采样和 JSONL 日志 |
| [[tool-operations]] | `tools/operations/*.ts` | 文件、进程和搜索底层执行后端抽象 |
| [[tool-catalog]] | `tools/catalog.ts` | 工具 schema 注册与默认工具集 |
| [[tool-governance]] | `service/tool_registry.ts`, `service/tool_resolver.ts` | Tool 全局治理、Agent 级过滤与 Prompt Hint |
| [[subagent-session]] | `service/subagent.ts`, `service/chat_orchestrator.ts`, `session-tree/subagent_projection.ts` | 普通会话内子 Agent 委派、结果聚合与回放投影 |
| [[context-compaction]] | `runtime/compaction.ts` | 长会话压缩与 compacted/full 视图 |
| [[prompt-builder]] | `runtime/prompt_builder.ts` | 8层分层 Prompt 注入系统 |
| [[memory-system]] | `memory/*.ts` | 长期记忆（MySQL/SQLite） |
| [[mysql-data-source]] | `service/data_source.ts`, `service/mysql_schema.ts`, `service/mysql_query.ts`, `tools/builtin/mysql.ts` | MySQL 数据源、schema/sample/query、SQL guard 和问数审计 |
| [[skill-system]] | `service/skill_loader.ts` | 技能加载、安装、注册和诊断 |
| [[skill-runtime]] | `service/skill_config.ts`, `service/skill_executor.ts`, `service/skill_secret.ts` | Skill 分类、compute-entry 执行和 scoped secrets |
| [[document-skills]] | `packages/backend/skills/minimax-*` | PDF / DOCX / XLSX 文档处理 skill 包 |
| [[vehicle-damage-skill]] | `packages/backend/skills/vehicle-damage-inspection/` | 汽车环车视频旧伤检测 compute-entry skill |
| [[netabrowser-runtime]] | `browser-daemon/*`, `packages/netabrowser-cli/` | 反风控浏览器 daemon、CLI、拟人化交互和持久 profile |
| [[llm-providers]] | `plugins/llm_providers/*.ts` | 多模型适配（含 Thinking） |
| [[agent-channel]] | `service/agent_channel.ts`, `service/weixin_db.ts` | 外部渠道接入；当前包含 ClawBot 私聊和 weixin-db 本地群聊代理 |
| [[desktop-op-module]] | `packages/backend/src/modules/desktop_op/` | 桌面 GUI 操作运行时；当前支撑微信自动发送 |
| [[todo-system]] | `runtime/todo_store.ts` | 会话级任务管理 |

## 数据模型（19个表）

| 表名 | Entity 文件 | 用途 |
|------|------------|------|
| `netaclaw_agent` | `entity/agent.ts` | Agent 配置和发布 |
| `netaclaw_session` | `entity/session.ts` | 对话会话 |
| `netaclaw_message` | `entity/message.ts` | 消息历史 |
| `netaclaw_skill` | `entity/skill.ts` | Skill 元数据、env schema 和加密 secrets |
| `netaclaw_model_channel` | `entity/model_channel.ts` | 模型渠道 |
| `netaclaw_memory` | `entity/memory.ts` | 长期记忆 |
| `netaclaw_memory_type` | `entity/memory_type.ts` | 记忆类型和系统类型保护 |
| `netaclaw_tool` | `entity/tool.ts` | Tool 全局治理配置 |
| `netaclaw_subagent_session` | `entity/subagent_session.ts` | 普通会话子 Agent 记录 |
| `netaclaw_crew` | `entity/crew.ts` | Crew 集群定义 |
| `netaclaw_crew_agent` | `entity/crew_agent.ts` | 集群-Agent 关联 |
| `netaclaw_crew_run` | `entity/crew_run.ts` | Crew 运行记录 |
| `netaclaw_crew_task` | `entity/crew_task.ts` | Crew 子任务记录 |
| `netaclaw_agent_channel` | `entity/agent_channel.ts` | 外部渠道配置 |
| `netaclaw_agent_channel_group` | `entity/agent_channel_group.ts` | 渠道群白名单、触发策略和每群 Agent 覆盖 |
| `netaclaw_agent_session` | `entity/agent_session.ts` | Session Tree 会话头与叶子状态 |
| `netaclaw_agent_session_entry` | `entity/agent_session_entry.ts` | Session Tree 节点持久化 |
| `netaclaw_data_source` | `entity/data_source.ts` | MySQL 数据源连接、授权和安全策略配置 |
| `netaclaw_data_source_query_audit` | `entity/data_source_query_audit.ts` | MySQL 问数 SQL 执行、拒绝和失败审计 |

当前数据模型需要区分两条线：

- legacy 线：`netaclaw_session` + `netaclaw_message`，仍服务旧历史消息、压缩和部分兼容逻辑。
- session-tree 线：`netaclaw_agent_session` + `netaclaw_agent_session_entry`，已经是 Agent Chat 主路径的会话状态载体。

## 关键字段

### netaclaw_agent
- `name`（唯一）、`label`、`description`、`icon`
- `systemPrompt`（系统提示词）
- `skills`（JSON 数组，关联的 Skill 名称）
- `modelConfig`（JSON：apiUrl/apiKey/modelId/contextWindow）
- `config`（JSON：memory/defaultThinkLevel 等）
- `status`（0=草稿 1=已发布）

### netaclaw_skill
- `name`（唯一）、`label`、`description`
- `skillType`（能力类型：compute/llm/multimodal）
- `tags`、`version`、`source`、`sourceUrl`
- `installSpec`、`metadata`、`fingerprint`、`installedAt`
- `secrets`（AES-256-GCM 加密后的 skill scoped secrets）
- `envSchema`（环境变量声明，供 [[skill-runtime]] 和前端配置页使用）

### netaclaw_message
- `sessionId`、`role`（user/assistant/tool/system）
- `content`、`thinking`（思考内容）
- `toolCalls`（JSON）、`toolCallId`、`skillName`、`metadata`

### netaclaw_agent_session
- `sessionId`、`agentId`、`userId`
- `rootEntryId`、`leafEntryId`
- `parentSessionId`、`title`、`status`
- `metadata`（会话级扩展状态）

### netaclaw_agent_session_entry
- `sessionId`、`entryId`、`parentEntryId`
- `type`（message / compaction / branch_summary / subagent_batch / subagent_result 等）
- `content`、`message`、`metadata`
- `timestamp`

### netaclaw_agent_channel_group
- `channelId`、`roomId`（channel 内唯一）、`roomName`
- `status`（0 禁用、1 启用、-1 忽略）
- `triggerMode`（at_mention / all，prefix 仅兼容）
- `boundAgentId`（每群 Agent 覆盖）
- `replyIdentityOverride`、`firstSeenAt`、`lastSeenAt`、`lastActiveAt`

### netaclaw_data_source
- `name`（唯一）、`label`、`type`（当前为 mysql）
- `host`、`port`、`database`、`username`
- `passwordEncrypted`（AES-256-GCM 密文）
- `readonly`、`status`
- `allowedAgentIds`（JSON 数组）
- `extra`（JSON：allowedTables、blockedTables、maskedColumns、schemaVisibility、maxRows、maxJoinTables、queryTimeoutMs、SSL 等）

### netaclaw_data_source_query_audit
- `dataSourceId`、`agentId`、`userId`、`toolCallId`
- `sqlHash`、`sqlPreview`
- `status`（success / rejected / failed）
- `rejectReason`、`elapsedMs`、`rowCount`、`errorCode`

### netaclaw_memory_type
- `key`（唯一类型标识）
- `name`、`description`、`icon`
- `isSystem`（1=系统内置，不允许删除）

## 当前主运行路径

当前 NetaClaw 的普通对话主路径已经是：

```text
gateway/server.ts
  -> chat_orchestrator.ts
  -> session-tree/*
  -> tool_resolver.ts / runtime/agent.ts
  -> memory/registry.ts + memory providers
  -> subagent.ts
  -> gateway/protocol.ts + frontend chat store
```

这意味着理解 Neta 项目时，不能再只把 `netaclaw_message` 和线性历史当成核心事实；需要优先理解 [[session-tree-runtime]]、[[agent-runtime]] 和 [[subagent-session]] 三者的协作。

## 相关页面

- [[project-overview]] — 项目总览
- [[agent-runtime]] — 执行引擎详解
- [[session-tree-runtime]] — 会话树运行时
- [[crew-orchestration]] — Multi-Agent 编排
- [[websocket-gateway]] — 通信协议
- [[tool-catalog]] — 工具目录系统
- [[tool-operations]] — 工具底层执行后端抽象
- [[prompt-builder]] — Prompt 分层注入
- [[patch-tool]] — Patch 模糊补丁工具
- [[clarify-tool]] — Clarify 澄清工具
- [[tool-system]] — 工具系统
- [[image-generation-tools]] — 文生图/图生图工具
- [[runtime-process-events]] — 工具和 Skill 过程事件
- [[memory-system]] — 长期记忆和记忆管理页
- [[mysql-data-source]] — MySQL 数据源、问数工具和 SQL guard
- [[skill-runtime]] — Skill 运行时执行和配置
- [[document-skills]] — 文档处理 Skills
- [[vehicle-damage-skill]] — 车辆旧伤检测 Skill
- [[netabrowser-runtime]] — 反风控浏览器运行时
- [[desktop-op-module]] — 桌面 GUI 操作运行时