qlogicagent

v1.2.1

Published

a day ago

XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)

0High
0Medium
0Low

jkait

qlogicagent

小智 Claw 的本地 AI Agent 运行时。作为 openclaw Gateway 的 CLI 子进程，通过 JSON-RPC over stdio 通信，执行完整的 Agent Loop。

功能概览

44 个内置工具: 文件操作、Shell 执行、代码编辑、Web 搜索/抓取、图片/视频/音乐生成、MCP 桥接等
多 LLM Provider: OpenAI、Anthropic、DeepSeek 等，通过统一 LLMTransport 接口切换
编排策略: failover 降级、指数退避重试、并行工具执行、14+ 上下文压缩策略、多代理团队协作
权限系统: 命令安全分类、规则引擎、用户审批、破坏性命令警告
记忆系统: 本地 MD 记忆 + QMemory 语义长期记忆 + 会话记忆自动提取 + Dream 整合
会话持久化: JSONL 对话转录 + 状态快照 + 会话恢复
MCP 协议: stdio/HTTP 传输、动态工具注入、资源发现
插件系统: 用户级/项目级插件加载、插件 API
技能系统: SKILL.md 发现/调用/管理、自主技能学习
Hook 系统: 30+ 生命周期钩子点，可扩展不侵入核心

快速开始

1. 环境准备

# Node.js 22+
node --version    # v22.x.x+

# 安装依赖
pnpm install

# 构建
pnpm build

2. 配置环境变量

cp .env.example .env

编辑 .env：

# 日志级别
LOG_LEVEL=info

# QMemory 服务地址（启用长期记忆）
QMEMORY_BASE_URL=http://127.0.0.1:18800

# QMemory API Key（可选）
# QMEMORY_API_KEY=your-key

3. 启动 QMemory（推荐）

qlogicagent 的完整功能依赖本地 QMemory 服务提供语义记忆：

# 方式一：直接运行（需 Python 3.11+）
cd ../qmemory
pip install -e .
python -m qmemory --port 18800

# 方式二：Docker
docker run -d -p 18800:18800 qmemory:latest

验证 QMemory 运行：

curl http://127.0.0.1:18800/health
# {"status":"ok","version":"..."}

4. 作为子进程运行

qlogicagent 不独立运行，需要由 openclaw Gateway 或其他 JSON-RPC 宿主 spawn：

# Gateway 自动 spawn（标准方式）
cd ../openclaw && node scripts/run-node.mjs gateway --port 18789

# 手动测试（开发调试用）
node dist/cli.js

启动后 agent 等待 stdin 接收 JSON-RPC 请求。

JSON-RPC 协议

请求方法

| 方法 | 说明 | 参数 | |------|------|------| | initialize | 协议握手 | { protocolVersion, host: { name, version } } | | agent.ping | 心跳检测 | — | | thread.turn | 执行一轮对话 | 见下方详细说明 | | agent.abort | 中止当前 turn | { turnId } | | thread.list | 列出历史会话 | { limit? } | | thread.create | 创建新线程 | { id?, title?, cwd? } | | session.resume | 恢复会话 | { sessionId } | | memory.dream | 触发记忆整合 | — | | tool.approval.response | 工具审批响应 | { approvalId, decision } |

thread.turn 参数

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "thread.turn",
  "params": {
    "turnId": "turn-001",
    "sessionId": "sess-001",
    "messages": [
      { "role": "user", "content": "帮我分析 src/ 目录结构" }
    ],
    "tools": [],
    "config": {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "apiKey": "sk-...",
      "baseUrl": "https://api.deepseek.com",
      "maxRounds": 25,
      "temperature": 0.7,
      "workdir": "/path/to/project",
      "mcpServers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
      },
      "skillPaths": ["/path/to/skills"],
      "systemPrompt": "You are a helpful assistant."
    }
  }
}

事件流（Agent → Host）

| 事件 | 说明 | |------|------| | turn.start | 轮次开始 | | turn.delta | 文本流式增量 { text } | | turn.end | 轮次结束 { content, usage, model, provider } | | turn.error | 执行错误 { error, code } | | turn.tool_call | 工具调用 { callId, name } | | turn.tool_result | 工具结果 { callId, name, ok } | | turn.tool_blocked | 权限拦截 { callId, name, reason } | | turn.skill_instruction | 技能指令 { instruction } | | turn.sidechain_started | 子代理启动 { depth, role } | | turn.sidechain_completed | 子代理完成 { depth, toolCallCount } | | turn.recovery | 错误恢复 { action } | | turn.plan_update | 计划更新 { slug, content } | | tool.approval.request | 请求审批 { approvalId, toolName, arguments, message } |

模块结构

src/
├── cli/                 # 组合根：JSON-RPC 协议 + 全模块装配
│   ├── main.ts          #   进程入口
│   ├── stdio-server.ts  #   StdioServer (JSON-RPC handler, 工具注册, 配置解析)
│   └── tool-bootstrap.ts#   工具注册初始化
│
├── agent/               # Agent 核心：推理 + 工具循环
│   ├── agent.ts         #   Agent 类 (async generator run())
│   ├── tool-loop.ts     #   工具调用循环
│   ├── types.ts         #   核心类型 (ChatMessage, TurnEvent, ToolInvoker...)
│   └── constants.ts     #   运行参数常量
│
├── llm/                 # LLM 通信层（完全隔离）
│   ├── transport.ts     #   LLMTransport 接口
│   ├── transports/      #   OpenAI / Anthropic 实现
│   ├── provider-registry.ts  # Provider 注册表
│   ├── model-catalog.ts #   模型能力目录
│   └── llm-client.ts    #   一站式客户端工厂
│
├── orchestration/       # 编排策略层（纯函数，零外部依赖）
│   ├── tool-loop-state.ts    # 工具循环 FSM
│   ├── context-compression.ts # 14+ 压缩策略
│   ├── error-classification.ts # 错误分类
│   ├── retry-loop.ts         # 重试策略
│   ├── agent-registry.ts     # 内置代理类型
│   ├── fork-subagent.ts      # 子代理 fork
│   ├── team-orchestration.ts # 多代理团队
│   └── ...                   # 23 个策略文件
│
├── runtime/             # 运行时服务层
│   ├── session-state.ts       # 会话成本追踪
│   ├── session-persistence.ts # JSONL 对话持久化
│   ├── session-memory.ts      # 会话记忆提取
│   ├── hook-registry.ts       # Hook 系统实现
│   ├── forked-agent.ts        # 子代理执行
│   ├── dream-agent.ts         # 记忆整合 (Dream)
│   ├── secure-storage.ts      # 凭据安全存储
│   ├── token-budget.ts        # Token 预算管理
│   ├── instruction-loader.ts  # .instructions.md 加载
│   └── ...                    # 21 个运行时文件
│
├── skills/              # 工具与技能层
│   ├── portable-tool.ts       # PortableTool 契约接口
│   ├── tools.ts               # CC-aligned 工具池 (setToolPool/findTool/getToolManifest)
│   ├── tools/                 # 44 个内置工具
│   │   ├── shell/             # 命令执行子系统 (11 文件)
│   │   ├── exec-tool.ts       # Shell 执行
│   │   ├── read-tool.ts       # 文件读取
│   │   ├── write-tool.ts      # 文件写入
│   │   ├── edit-tool.ts       # 文件编辑
│   │   ├── search-tool.ts     # 文件搜索
│   │   ├── web-search-tool.ts # Web 搜索
│   │   ├── agent-tool.ts      # 子代理调用
│   │   ├── team-tool.ts       # 团队管理
│   │   ├── mcp-tool.ts        # MCP 服务器管理
│   │   └── ...                # 其他工具
│   ├── mcp/                   # MCP 桥接 (4 文件)
│   ├── permissions/           # 权限系统 (9 文件)
│   ├── plugins/               # 插件系统 (4 文件)
│   ├── memory-tool.ts         # 记忆工具 (MD + QMemory)
│   ├── qmemory-adapter.ts     # QMemory HTTP 适配器
│   └── skill-loader.ts        # 技能发现/加载
│
├── contracts/           # 纯类型契约（零依赖）
│   ├── hooks.ts               # 30+ Hook 点定义
│   ├── planner.ts             # 规划器类型
│   ├── todo.ts                # 待办类型
│   └── skill-candidate.ts     # 技能候选类型
│
└── config/              # 配置管理
    └── config.ts              # CLI 参数解析

QMemory 集成

qlogicagent 通过 HTTP 连接本地 QMemory 服务实现语义长期记忆。

记忆层次

| 层 | 说明 | 存储 | |----|------|------| | MD 记忆 | Agent 主动管理的笔记 (add/replace/remove) | ~/.qlogicagent/session-memory.md | | QMemory | 语义向量记忆，自动提取 + 语义召回 | QMemory 服务 (SQLite + embedding) | | 会话转录 | JSONL 对话记录，用于会话恢复 | ~/.qlogicagent/sessions/<id>/ |

启用步骤

启动 QMemory 服务（见上方"快速开始"）
设置环境变量：QMEMORY_BASE_URL=http://127.0.0.1:18800
Agent 自动：
- 在 memory.before_recall hook 预取相关记忆
- 通过 memory 工具的 search action 查询语义记忆
- 会话结束时自动提取关键信息写入 QMemory
- 达到阈值后触发 Dream 整合（4 阶段：Orient → Gather → Consolidate → Prune）

不启用 QMemory

如果不设置 QMEMORY_BASE_URL，Agent 仍可运行，但：

❌ 无语义记忆召回
❌ 无自动记忆提取
❌ 无 Dream 整合
✅ MD 本地记忆仍可用
✅ 会话转录仍正常

配置文件

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | LOG_LEVEL | 日志级别 (debug/info/warn/error) | info | | QMEMORY_BASE_URL | QMemory 服务地址 | 不设则禁用 | | QMEMORY_API_KEY | QMemory 认证 Key | — | | QLOGICAGENT_QMEMORY_BASE_URL | QMemory 地址 (备选变量名) | — |

用户级配置（`~/.qlogicagent/`）

| 路径 | 说明 | |------|------| | ~/.qlogicagent/settings.json | 权限规则、行为模式 | | ~/.qlogicagent/mcp.json | 全局 MCP 服务器配置 | | ~/.qlogicagent/plugins/ | 用户级插件目录 | | ~/.qlogicagent/INSTRUCTIONS.md | 用户级指令 | | ~/.qlogicagent/session-memory.md | MD 记忆文件 | | ~/.qlogicagent/sessions/ | 会话持久化目录 | | ~/.qlogicagent/.credentials.json | 安全凭据存储 (0o600) |

项目级配置

| 路径 | 说明 | |------|------| | .qlogicagent/settings.json | 项目权限规则 | | .qlogicagent/plugins/ | 项目级插件 | | .qlogicagent/INSTRUCTIONS.md | 项目指令 | | INSTRUCTIONS.md | 项目指令 (根目录) | | INSTRUCTIONS.local.md | 本地私有指令 |

MCP 配置

全局 MCP（`~/.qlogicagent/mcp.json`）

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
  },
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_TOKEN": "ghp_..." }
  }
}

Per-Turn MCP（通过 `agent.turn` config）

{
  "config": {
    "mcpServers": {
      "project-db": {
        "type": "http",
        "url": "http://localhost:3100/mcp"
      }
    }
  }
}

MCP 工具自动注入到 Agent 工具列表，前缀格式：mcp__servername__toolname。

权限配置

`~/.qlogicagent/settings.json`

{
  "permissionMode": "default",
  "defaultBehavior": "ask",
  "permissionRules": [
    {
      "pattern": "read",
      "behavior": "allow"
    },
    {
      "pattern": "exec",
      "behavior": "ask"
    },
    {
      "pattern": "write:**/node_modules/**",
      "behavior": "deny"
    }
  ]
}

behavior 可选值：allow（自动允许）、ask（请求审批）、deny（拒绝）。

开发命令

pnpm install         # 安装依赖
pnpm build           # esbuild 构建 (scripts/build.mjs)
pnpm dev             # tsx watch 开发模式
pnpm test            # vitest 运行测试
pnpm test:watch      # vitest watch 模式
pnpm lint            # oxlint 代码检查
pnpm start           # 启动 CLI (node dist/cli.js)

测试

pnpm test                    # 全部测试
pnpm test -- test/e2e        # E2E 协议测试
pnpm test -- --coverage      # 覆盖率

单元测试：test/ — LLM provider、orchestration、tool、permission
E2E 测试：test/e2e/ — spawn CLI 进程验证 JSON-RPC 协议

发布

# 版本已在 package.json 中更新后：
git tag v0.4.0
git push origin master
git push origin v0.4.0
# Gitee 流水线自动: build → test → npm publish → Gitee Release

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

qlogicagent

功能概览

快速开始

1. 环境准备

2. 配置环境变量

3. 启动 QMemory（推荐）

4. 作为子进程运行

JSON-RPC 协议

请求方法

thread.turn 参数

事件流（Agent → Host）

模块结构

QMemory 集成

记忆层次

启用步骤

不启用 QMemory

配置文件

环境变量

用户级配置（~/.qlogicagent/）

项目级配置

MCP 配置

全局 MCP（~/.qlogicagent/mcp.json）

Per-Turn MCP（通过 agent.turn config）

权限配置

~/.qlogicagent/settings.json

开发命令

测试

发布

用户级配置（`~/.qlogicagent/`）

全局 MCP（`~/.qlogicagent/mcp.json`）

Per-Turn MCP（通过 `agent.turn` config）

`~/.qlogicagent/settings.json`