tantingwu/GPU_GUARD_MONOREPO

Fork 0

陈二狗 cc660d19d1 初始化提交

2026-05-20 21:39:12 +08:00

10 KiB

Raw Blame History

title

created

updated

type

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 的普通对话主路径已经是：

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 三者的协作。

10 KiB Raw Blame History Unescape Escape