qlogicagent 2.18.11 → 2.19.1

package/README.md

@@ -1,382 +1,382 @@
-# qlogicagent
-
-## Community Red-Team Reports
-
-Generate the community desensitization red-team report from the same detectors used by local community flows:
-
-```bash
-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. 环境准备
-
-```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 协议
-
-### 请求方法
-
-> ⚠️ 方法名权威清单以 `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`）
-
-```json
-{
-  "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 实例时各自独立数据目录
-
-```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 执行中如果收到新的 `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`）
-
-```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）
-
-```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
-```
+# qlogicagent
+
+## Community Red-Team Reports
+
+Generate the community desensitization red-team report from the same detectors used by local community flows:
+
+```bash
+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. 环境准备
+
+```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 协议
+
+### 请求方法
+
+> ⚠️ 方法名权威清单以 `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`）
+
+```json
+{
+  "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 实例时各自独立数据目录
+
+```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 执行中如果收到新的 `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`）
+
+```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）
+
+```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
+```