# qlogicagent

## Community Red-Team Reports

Generate the v0.15 community red-team reports from the same detectors and permission checker used by local community flows:

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

The reports contain case ids, rule/finding ids, counts, and failures only; they do not store raw emails, secrets, paths, phone numbers, memories, skill text, tool commands, or file paths.

Installed community skills are marked from their lifecycle registry provenance. Non-official installed skills execute as `community-skill:*` subturns, and `PermissionChecker` applies the L1 sandbox overlay only while that subturn is active.

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.

At runtime, the community sandbox overlay also blocks host side-effect tools such as `send_message`, `agent`, `team`, `cron`, and `monitor` from community skill subturns, so injected instructions cannot escape through delegation, team control, or scheduled work.

Community skill subturns also treat local file upload as tainted data egress. A `file_upload` call from `community-skill:*` requires explicit per-call approval before any provider Files API upload can proceed; auto-mode classifiers cannot replace that approval, and denied approvals leave no raw file path in the sandbox red-team report.

Community skill subturns also treat provider prompt/media tools as tainted external egress. Calls such as `image_generate`, `video_generate`, `music_generate`, `tts`, `three_d_generate`, `video_edit`, `video_merge`, `video_upscale`, `voice_clone`, and `stt` require explicit per-call approval from `community-skill:*`; worker/coordinator roles fail closed, and auto-mode classifiers cannot replace that approval.

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. 环境准备

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

# 安装依赖
pnpm install

# 构建
pnpm build
```

### 2. 配置环境变量

```bash
cp .env.example .env
```

编辑 `.env`：

```bash
# 日志级别
LOG_LEVEL=info
```

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

### 3. 运行

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

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

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

启动后 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 参数

```json
{
  "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 }` |

---

## 模块结构

> 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/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 实例时各自独立数据目录

```bash
# 测试隔离示例
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 执行中如果收到新的 `thread.turn`，自动中止 Dream
- **最大时长限制**：单次 Dream 最长 120 秒，超时自动终止
- **触发门控**：需满足记忆数据充足等前置条件才会真正执行

### 用户级配置（`~/.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`）

```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）

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

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

---

## 权限配置

### `~/.qlogicagent/settings.json`

```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`（拒绝）。

---

## 开发命令

```bash
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)
```

## 测试

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

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

## 发布

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