190 lines
10 KiB
Markdown
190 lines
10 KiB
Markdown
---
|
||
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 操作运行时
|