qlogicagent 0.4.0 → 0.5.0

package/README.md

@@ -1,45 +1,402 @@
 # qlogicagent
 
-CLI 子进程 Agent。小智 Claw 的本地 AI Agent 运行时，作为 openclaw Gateway 的子进程通过 **JSON-RPC over stdio** 通信。
+小智 Claw 的本地 AI Agent 运行时。作为 openclaw Gateway 的 CLI 子进程，通过 **JSON-RPC over stdio** 通信，执行完整的 Agent Loop。
 
-## 职责
+## 功能概览
 
-1. 接收 `agent.turn` JSON-RPC 请求，执行 Agent Loop（prompt → LLM → tool calls → iterate）。
-2. 通过 stdout 流式输出 `turn.chunk`、`turn.tool_call`、`turn.done` 等 JSON-RPC 事件。
-3. 工具执行委托回 Gateway（`turn.tool_call` → Gateway 执行 → `tool.result` 返回）。
-4. 支持 failover、parallel tools、context compression、team orchestration 等编排策略。
-5. 可选 qmemory 集成（memory hooks、skill learning、dream mechanism）。
+- **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. HTTP/WebSocket 服务 — 由 qlogicagent-hub 负责。
-2. 持久化存储 — Agent 是无状态子进程，Session/Skill/Plan 由 Gateway 管理。
-3. LLM API Key 管理 — 配置通过 `agent.turn` 请求的 `config.llm` 字段传入。
-4. 平台 API、订阅、计费 — 由 qlogicagent-hub + openclaw-admin 负责。
+### 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
+
+# QMemory 服务地址（启用长期记忆）
+QMEMORY_BASE_URL=http://127.0.0.1:18800
+
+# QMemory API Key（可选）
+# QMEMORY_API_KEY=your-key
+```
+
+### 3. 启动 QMemory（推荐）
+
+qlogicagent 的完整功能依赖本地 QMemory 服务提供语义记忆：
+
+```bash
+# 方式一：直接运行（需 Python 3.11+）
+cd ../qmemory
+pip install -e .
+python -m qmemory --port 18800
+
+# 方式二：Docker
+docker run -d -p 18800:18800 qmemory:latest
+```
+
+验证 QMemory 运行：
+
+```bash
+curl http://127.0.0.1:18800/health
+# {"status":"ok","version":"..."}
+```
+
+### 4. 作为子进程运行
+
+qlogicagent 不独立运行，需要由 openclaw Gateway 或其他 JSON-RPC 宿主 spawn：
+
+```bash
+# Gateway 自动 spawn（标准方式）
+cd ../openclaw && node scripts/run-node.mjs gateway --port 18789
+
+# 手动测试（开发调试用）
+node dist/cli/main.js
+```
+
+启动后 agent 等待 stdin 接收 JSON-RPC 请求。
+
+---
+
+## JSON-RPC 协议
+
+### 请求方法
+
+| 方法 | 说明 | 参数 |
+|------|------|------|
+| `agent.hello` | 协议握手 | `{ protocolVersion, hostName, hostVersion }` |
+| `agent.ping` | 心跳检测 | — |
+| `agent.turn` | 执行一轮对话 | 见下方详细说明 |
+| `agent.abort` | 中止当前 turn | `{ turnId }` |
+| `session.list` | 列出历史会话 | `{ limit? }` |
+| `session.resume` | 恢复会话 | `{ sessionId }` |
+| `memory.dream` | 触发记忆整合 | — |
+| `tool.approval.response` | 工具审批响应 | `{ approvalId, decision }` |
+
+### agent.turn 参数
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "agent.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 stdio 入口 (main.ts, stdio-server.ts)
-├── agent/          # Agent 核心 (agent.ts, tool-loop.ts, types.ts)
-├── llm/            # LLM provider 注册、传输层 (OpenAI, Anthropic)
-├── orchestration/  # 编排策略 (failover, retry, parallel, compression, team)
-├── skills/         # PortableTool 实现 + 外部 skill 加载
-├── runtime/        # Hook registry, memory hooks, context compression
-├── contracts/      # Hook / planner / skill candidate / todo 契约
-└── config/         # 配置管理
+├── 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 契约接口
+│   ├── tool-registry.ts       # 工具注册表
+│   ├── 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) | `~/.openclaw/session-memory.md` |
+| **QMemory** | 语义向量记忆，自动提取 + 语义召回 | QMemory 服务 (SQLite + embedding) |
+| **会话转录** | JSONL 对话记录，用于会话恢复 | `~/.openclaw/sessions/<id>/` |
+
+### 启用步骤
+
+1. 启动 QMemory 服务（见上方"快速开始"）
+2. 设置环境变量：`QMEMORY_BASE_URL=http://127.0.0.1:18800`
+3. 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 地址 (备选变量名) | — |
+
+### 用户级配置（`~/.openclaw/`）
+
+| 路径 | 说明 |
+|------|------|
+| `~/.openclaw/settings.json` | 权限规则、行为模式 |
+| `~/.openclaw/mcp.json` | 全局 MCP 服务器配置 |
+| `~/.openclaw/plugins/` | 用户级插件目录 |
+| `~/.openclaw/INSTRUCTIONS.md` | 用户级指令 |
+| `~/.openclaw/session-memory.md` | MD 记忆文件 |
+| `~/.openclaw/sessions/` | 会话持久化目录 |
+| `~/.openclaw/.credentials.json` | 安全凭据存储 (0o600) |
+
+### 项目级配置
+
+| 路径 | 说明 |
+|------|------|
+| `.openclaw/settings.json` | 项目权限规则 |
+| `.openclaw/plugins/` | 项目级插件 |
+| `.openclaw/INSTRUCTIONS.md` | 项目指令 |
+| `INSTRUCTIONS.md` | 项目指令 (根目录) |
+| `INSTRUCTIONS.local.md` | 本地私有指令 |
+
+---
+
+## MCP 配置
+
+### 全局 MCP（`~/.openclaw/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`。
+
+---
+
+## 权限配置
+
+### `~/.openclaw/settings.json`
+
+```json
+{
+  "permissionMode": "default",
+  "defaultBehavior": "ask",
+  "permissionRules": [
+    {
+      "pattern": "read",
+      "behavior": "allow"
+    },
+    {
+      "pattern": "exec",
+      "behavior": "ask"
+    },
+    {
+      "pattern": "write:**/node_modules/**",
+      "behavior": "deny"
+    }
+  ]
+}
+```
+
+`behavior` 可选值：`allow`（自动允许）、`ask`（请求审批）、`deny`（拒绝）。
+
+---
+
+## 开发命令
 
 ```bash
-pnpm build          # TypeScript 编译
-pnpm test           # vitest 测试
-pnpm dev            # tsx watch 开发
+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/main.js)
 ```
 
 ## 测试
 
-- 单元测试：`test/` 目录，覆盖 LLM provider、orchestration、semantic turn tools。
-- E2E 测试：`test/e2e/` 目录，spawn CLI 进程验证 JSON-RPC 协议行为。
+```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
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",
@@ -54,4 +54,4 @@
     "typescript": "^5.9.0",
     "vitest": "^3.1.0"
   }
-}
+}