qlogicagent 2.12.7 → 2.12.9

package/README.md

@@ -1,31 +1,31 @@
-# 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 连接本进程。
+# 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 连接本进程。
 
 ## 功能概览
 
@@ -33,7 +33,7 @@ Pet/Soul data is display-only. Runtime load/save sanitization strips fields and
 - **多 LLM Provider**: OpenAI、Anthropic、DeepSeek 等，通过统一 `LLMTransport` 接口切换
 - **编排策略**: failover 降级、指数退避重试、并行工具执行、14+ 上下文压缩策略、多代理团队协作
 - **权限系统**: 命令安全分类、规则引擎、用户审批、破坏性命令警告
-- **记忆系统**: 本地 memory.json (2200 char, 始终注入 systemPrompt) + QMemory 语义长期记忆 (recall-on-demand) + Dream 整合
+- **记忆系统**: 进程内分层记忆 — memdir 文件记忆 (L1 项目级，INDEX.md + 主题文件) + 本地 SQLite 语义长期记忆 (L2，本地 embedding，recall-on-demand) + Dream 整合，无外部服务依赖
 - **会话持久化**: JSONL 对话转录 + 状态快照 + 会话恢复
 - **MCP 协议**: stdio/HTTP 传输、动态工具注入、资源发现
 - **插件系统**: 用户级/项目级插件加载、插件 API
@@ -66,36 +66,11 @@ cp .env.example .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（推荐）
+记忆系统为进程内（memdir 文件记忆 + 本地 SQLite 语义记忆 + 本地 embedding），无需启动任何外部服务，开箱即用。
 
-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. 运行
+### 3. 运行
 
 qlogicagent 作为独立进程运行，由 Electron 桌面壳管理生命周期，openclaw 通过 ACP 协议连接：
 
@@ -184,112 +159,81 @@ node dist/cli.js --acp
 
 ## 模块结构
 
+> LLM 通信不在本仓：Provider 实现来自外部包 `@xiaozhiclaw/provider-core`，仓内仅保留传输端口
+> (`runtime/ports/model-transport-contracts.ts`) 与门面 (`cli/provider-core-facade.ts`)。记忆同样进程内，无独立 HTTP 服务。
+
 ```
 src/
-├── cli/                 # 组合根：JSON-RPC 协议 + 全模块装配
-│   ├── main.ts          #   进程入口
-│   ├── stdio-server.ts  #   StdioServer (JSON-RPC handler, 工具注册, 配置解析)
-│   └── tool-bootstrap.ts#   工具注册初始化
+├── 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())
-│   ├── 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    #   一站式客户端工厂
+│   ├── 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-state.ts    # 工具循环 FSM
-│   ├── context-compression.ts # 14+ 压缩策略
-│   ├── error-classification.ts # 错误分类
-│   ├── retry-loop.ts         # 重试策略
-│   ├── agent-registry.ts     # 内置代理类型
-│   ├── fork-subagent.ts      # 子代理 fork
-│   ├── team-orchestration.ts # 多代理团队
-│   └── ...                   # 23 个策略文件
+│   ├── 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-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 与 .qlogicagent/rules 加载
-│   └── ...                    # 21 个运行时文件
+│   ├── 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/              # 工具与技能层
-│   ├── 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     # 技能候选类型
+│   ├── 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 发现 / 生命周期 / 校验
 │
-└── config/              # 配置管理
-    └── config.ts              # CLI 参数解析
+├── protocol/            # 线协议：wire/ (Gateway RPC 契约) + notifications + methods
+├── transport/           # ACP server + 事件映射
+├── contracts/           # 纯类型契约（hooks 等，零依赖）
+└── config/              # CLI 参数解析
 ```
 
 ---
 
-## QMemory 集成
+## 记忆系统
 
-qlogicagent 通过 HTTP 连接本地 QMemory 服务实现语义长期记忆。
+qlogicagent 的记忆全部进程内，无外部服务依赖，开箱即用。
 
 ### 记忆层次
 
 | 层 | 说明 | 存储 |
 |----|------|------|
-| **MD 记忆** | Agent 主动管理的笔记 (add/replace/remove) | `~/.qlogicagent/session-memory.md` |
-| **QMemory** | 语义向量记忆，自动提取 + 语义召回 | QMemory 服务 (SQLite + embedding) |
+| **L1 memdir** | 项目级文件记忆，Agent 主动管理 (INDEX.md + 主题文件) | `<project>/.qlogicagent/memory/` |
+| **L2 长期记忆** | 语义向量记忆，自动提取 + 语义召回 | 本地 SQLite + 本地 embedding（进程内） |
 | **会话转录** | JSONL 对话记录，用于会话恢复 | `~/.qlogicagent/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）
+无需任何配置或外部服务。Agent 自动：
+- 在 `memory.before_recall` hook 预取相关长期记忆（按 category 过滤 + 每轮字节封顶后注入系统提示）
+- 通过 `memory` 工具查询 / 写入语义记忆
+- 会话过程中自动提取关键信息写入 L2
+- 空闲或达到阈值后触发 Dream 整合（4 阶段：Orient → Gather → Consolidate → Prune）
 
-### 不启用 QMemory
-
-如果不设置 `QMEMORY_BASE_URL`，Agent 仍可运行，但：
-- ❌ 无语义记忆召回
-- ❌ 无自动记忆提取
-- ❌ 无 Dream 整合
-- ✅ MD 本地记忆仍可用
-- ✅ 会话转录仍正常
+L1/L2 冲突时不静默合并：召回上下文会标注冲突并提示向用户确认（见 `agent/memory-recall-context.ts`）。
 
 ---
 
@@ -300,9 +244,6 @@ qlogicagent 通过 HTTP 连接本地 QMemory 服务实现语义长期记忆。
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `LOG_LEVEL` | 日志级别 (debug/info/warn/error) | `info` |
-| `QMEMORY_BASE_URL` | QMemory 服务地址 | 不设则禁用 |
-| `QMEMORY_API_KEY` | QMemory 认证 Key | — |
-| `QLOGICAGENT_QMEMORY_BASE_URL` | QMemory 地址 (备选变量名) | — |
 | `QLOGICAGENT_HOME` | Agent 数据根目录（覆盖默认 `~/.qlogicagent/`）| `~/.qlogicagent/` |
 | `QLOGICAGENT_IDLE_DREAM_MS` | 空闲多久后自动触发 Dream 整合（毫秒）| `300000` (5 min) |
 | `QLOGICAGENT_DREAM_COOLDOWN_MS` | 两次 Dream 之间的最短间隔（毫秒）| `1800000` (30 min) |
@@ -329,7 +270,7 @@ qlogicagent 内置 idle dream 机制：当用户空闲超过 `QLOGICAGENT_IDLE_D
 - **冷却保护**：两次 Dream 之间必须间隔 `QLOGICAGENT_DREAM_COOLDOWN_MS`，防止频繁触发
 - **用户活动中止**：Dream 执行中如果收到新的 `thread.turn`，自动中止 Dream
 - **最大时长限制**：单次 Dream 最长 120 秒，超时自动终止
-- **触发门控**：需满足记忆数据充足、QMemory 可用等前置条件才会真正执行
+- **触发门控**：需满足记忆数据充足等前置条件才会真正执行
 
 ### 用户级配置（`~/.qlogicagent/`）
 
@@ -398,22 +339,15 @@ MCP 工具自动注入到 Agent 工具列表，前缀格式：`mcp__servername__
 
 ```json
 {
-  "permissionMode": "default",
-  "defaultBehavior": "ask",
-  "permissionRules": [
-    {
-      "pattern": "read",
-      "behavior": "allow"
-    },
-    {
-      "pattern": "exec",
-      "behavior": "ask"
-    },
-    {
-      "pattern": "write:**/node_modules/**",
-      "behavior": "deny"
-    }
-  ]
+  "permissions": {
+    "mode": "default",
+    "defaultBehavior": "ask",
+    "rules": [
+      { "pattern": "read", "behavior": "allow" },
+      { "pattern": "exec", "behavior": "ask" },
+      { "pattern": "write:**/node_modules/**", "behavior": "deny" }
+    ]
+  }
 }
 ```