qlogicagent

Community Red-Team Reports

Generate the community desensitization red-team report from the same detectors used by local community flows:

pnpm redteam:community-desensitization -- --out=../qlogicagent-hub/reports/community-go-live/red-team/desensitization.json

The report contains case ids, rule/finding ids, counts, and failures only; it does not store raw emails, secrets, paths, phone numbers, memories, skill text, tool commands, or file paths.

The generic skill meta-tool no longer exposes raw URL installation. New community skills must enter through the v0.15 registry install flow so manifest kind, source tier, risk tier, dependencies, checksum, and local SKILL.md rescan all run on the same path.

Community skill installation also rescans the downloaded SKILL.md entry after checksum verification and before moving it into the owner profile. Prompt-injection hits fail closed, leave no installed skill or lifecycle record, and return only a generic scan failure.

Pet/Soul data is display-only. Runtime load/save sanitization strips fields and Chinese/English text that claim the pet is a desktop agent, execution actor, decision layer, permission subject, or can alter agent tools, permissions, memory, retrieval, planning, security policy, or system prompts.

小智 Claw 的本地 AI Agent 运行时。作为独立进程运行，通过 ACP (Agent Client Protocol) + Native JSON-RPC over stdio 对外提供 Agent 能力。openclaw 智能网关作为 ACP Client 连接本进程。

功能概览

• 44 个内置工具: 文件操作、Shell 执行、代码编辑、Web 搜索/抓取、图片/视频/音乐生成、MCP 桥接等
• 多 LLM Provider: OpenAI、Anthropic、DeepSeek 等，通过统一 LLMTransport 接口切换
• 编排策略: failover 降级、指数退避重试、并行工具执行、14+ 上下文压缩策略、多代理团队协作
• 权限系统: 命令安全分类、规则引擎、用户审批、破坏性命令警告
• 记忆系统: 进程内分层记忆 — memdir 文件记忆 (L1 项目级，INDEX.md + 主题文件) + 本地 SQLite 语义长期记忆 (L2，本地 embedding，recall-on-demand) + 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

记忆系统为进程内（memdir 文件记忆 + 本地 SQLite 语义记忆 + 本地 embedding），无需启动任何外部服务，开箱即用。

3. 运行

qlogicagent 作为独立进程运行，由 Electron 桌面壳管理生命周期，openclaw 通过 ACP 协议连接：

# 独立启动（开发调试用）
node dist/cli.js

# 以 ACP Server 模式启动
node dist/cli.js --acp

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

JSON-RPC 协议

请求方法

⚠️ 方法名权威清单以 src/cli/rpc-registry.ts(私有 agent-RPC)+ src/protocol/wire/acp-protocol.ts(ACP)为准。一轮对话由 ACP session/prompt 触发(本仓不存在 thread.turn)。

| 方法 | 说明 | 参数 | |------|------|------| | initialize | 协议握手 | { protocolVersion, host: { name, version } } | | agent.ping | 心跳检测 | — | | session/prompt (ACP) | 执行一轮对话 | 见下方详细说明 | | agent.cancel | 中止当前 turn | { turnId } | | thread.list | 列出历史会话 | { limit? } | | thread.create | 创建新线程 | { id?, title?, cwd? } | | session.resume | 恢复会话 | { sessionId } | | memory.dream | 触发记忆整合 | — | | thread.user_response | 回复中途提问 / 工具审批 | { turnId, response }(子代理审批走 agents.approvalResponse) |

一轮对话参数（ACP session/prompt）

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "session/prompt",
  "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 } |

模块结构

LLM 通信不在本仓：Provider 实现来自外部包 @xiaozhiclaw/provider-core，仓内仅保留传输端口 (runtime/ports/model-transport-contracts.ts) 与门面 (cli/provider-core-facade.ts)。记忆同样进程内，无独立 HTTP 服务。

src/
├── cli/                 # 组合根：JSON-RPC + ACP 协议 + 全模块装配
│   ├── main.ts                #   进程入口
│   ├── stdio-server.ts        #   StdioServer (JSON-RPC 派发 + 运行时状态容器)
│   ├── rpc-registry.ts        #   RPC 方法 → handler 注册表
│   ├── handlers/              #   各域 RPC handler (session/memory/pet/agents/...)
│   ├── provider-core-facade.ts #  LLMTransport / 媒体客户端门面 (provider-core 边界)
│   └── *-coordinator / *-bootstrap.ts  # 会话/记忆/工具/权限/MCP 等装配
│
├── agent/               # Agent 核心：推理 + 工具循环
│   ├── agent.ts                #   Agent 类 (async generator run() — turn 生命周期薄壳)
│   ├── tool-loop.ts            #   工具调用循环状态机 (CC query loop 对齐)
│   ├── tool-loop/             #   循环子阶段 (loop/recovery/single-round/事件 helpers)
│   ├── memory-recall-context.ts   # 召回记忆 → 系统提示 (纯函数 + 冲突检测)
│   ├── memory-recall-injection.ts # 召回编排 (hook + 字节封顶 + after_recall)
│   ├── tunable-defaults.ts     #   运行参数默认/上限
│   └── types.ts                #   核心类型 (ChatMessage, TurnEvent, ToolInvoker, LLMTransport...)
│
├── orchestration/       # 编排策略层（纯函数，零外部依赖）
│   ├── tool-loop/            #   tool-loop-state / conversation-repair / tool-choice-policy / tool-schema
│   ├── context/             #   context-collapse 等上下文压缩策略
│   ├── subagent/            #   agent-registry / fork-subagent (内置代理 + 子代理 fork)
│   ├── workflow/            #   工作流引擎 / 调度 / 预算门控
│   └── ...                  #   错误分类、重试、团队编排、solo/product 等
│
├── runtime/             # 运行时服务层
│   ├── session/             #   session-state / session-persistence / session-memory / locator
│   ├── hooks/              #   hook-registry / memory-hooks / 上下文压缩 hooks
│   ├── execution/          #   forked-agent / streaming-tool-executor
│   ├── prompt/             #   instruction-loader / system-prompt-sections / task-domain
│   ├── infra/              #   model-registry / task-runtime / background-tasks / agent-paths
│   ├── ports/              #   端口契约 (memory / model-transport / permission ...)
│   └── config/             #   tunable-defaults 等运行时配置
│
├── skills/              # 工具与技能层
│   ├── tools/              #   内置工具 (shell / read / write / edit / search / web / agent / team / mcp ...)
│   ├── memory/             #   memdir (文件记忆) + 本地 SQLite store + 本地 embedding + 整合/召回
│   ├── mcp/                #   MCP 桥接
│   ├── permissions/        #   权限规则引擎 / 设置 / sandbox overlay
│   ├── plugins/            #   插件系统
│   └── skill-system/       #   SKILL.md 发现 / 生命周期 / 校验
│
├── protocol/            # 线协议：wire/ (Gateway RPC 契约) + notifications + methods
├── transport/           # ACP server + 事件映射
├── contracts/           # 纯类型契约（hooks 等，零依赖）
└── config/              # CLI 参数解析

记忆系统

qlogicagent 的记忆全部进程内，无外部服务依赖，开箱即用。

记忆层次

| 层 | 说明 | 存储 | |----|------|------| | L1 memdir | 项目级文件记忆，Agent 主动管理 (INDEX.md + 主题文件) | <project>/.qlogicagent/memory/ | | L2 长期记忆 | 语义向量记忆，自动提取 + 语义召回 | 本地 SQLite + 本地 embedding（进程内） | | 会话转录 | JSONL 对话记录，用于会话恢复 | ~/.qlogicagent/profiles/<owner>/projectData/<projectId>/sessions/<id>/ |

工作方式

无需任何配置或外部服务。Agent 自动：

• 在 memory.before_recall hook 预取相关长期记忆（按 category 过滤 + 每轮字节封顶后注入系统提示）
• 通过 memory 工具查询 / 写入语义记忆
• 会话过程中自动提取关键信息写入 L2
• 空闲或达到阈值后触发 Dream 整合（4 阶段：Orient → Gather → Consolidate → Prune）

L1/L2 冲突时不静默合并：召回上下文会标注冲突并提示向用户确认（见 agent/memory-recall-context.ts）。

配置文件

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | LOG_LEVEL | 日志级别 (debug/info/warn/error) | info | | QLOGICAGENT_HOME | Agent 数据根目录（覆盖默认 ~/.qlogicagent/）| ~/.qlogicagent/ | | QLOGICAGENT_IDLE_DREAM_MS | 空闲多久后自动触发 Dream 整合（毫秒）| 300000 (5 min) | | QLOGICAGENT_DREAM_COOLDOWN_MS | 两次 Dream 之间的最短间隔（毫秒）| 1800000 (30 min) |

QLOGICAGENT_HOME

设置后，所有 Agent 数据（sessions、memory、settings、plugins 等）存储到指定目录而非 ~/.qlogicagent/。

典型场景：

• 测试隔离：每个测试用例使用独立 QLOGICAGENT_HOME 避免互相污染
• 多实例部署：同一机器运行多个 agent 实例时各自独立数据目录

# 测试隔离示例
QLOGICAGENT_HOME=/tmp/test-agent-1 node dist/cli.js

Idle Dream（空闲记忆整合）

qlogicagent 内置 idle dream 机制：当用户空闲超过 QLOGICAGENT_IDLE_DREAM_MS 毫秒后，自动触发 Dream 记忆整合流程（Orient → Gather → Consolidate → Prune）。

特性：

• 自治管理：不依赖外部调度器，agent 进程内部自动计时
• 冷却保护：两次 Dream 之间必须间隔 QLOGICAGENT_DREAM_COOLDOWN_MS，防止频繁触发
• 用户活动中止：Dream 执行中如果收到新的 session/prompt，自动中止 Dream
• 最大时长限制：单次 Dream 最长 120 秒，超时自动终止
• 触发门控：需满足记忆数据充足等前置条件才会真正执行

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

| 路径 | 说明 | |------|------| | ~/.qlogicagent/settings.json | 权限规则、行为模式 | | ~/.qlogicagent/mcp.json | 全局 MCP 服务器配置 | | ~/.qlogicagent/plugins/ | 用户级插件目录 | | ~/.qlogicagent/INSTRUCTIONS.md | 用户级指令 | | ~/.qlogicagent/session-memory.md | MD 记忆文件 | | ~/.qlogicagent/profiles/<owner>/projectData/<projectId>/sessions/ | 会话持久化目录（按 projectId 集中，P1 迁移后）| | ~/.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（通过 session/prompt config）

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

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

权限配置

~/.qlogicagent/settings.json

{
  "permissions": {
    "mode": "default",
    "defaultBehavior": "ask",
    "rules": [
      { "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