qlogicagent 2.23.14 → 2.24.2

package/README.md

@@ -1,365 +1,93 @@
 # qlogicagent
 
-## Community Red-Team Reports
+qlogicagent 是一个普通的 ACP Agent adapter。它由 Runtime Host 作为受监管子进程启动，通过 JSON-RPC stdio 实现标准 ACP 会话协议；它没有 qlogicagent 专属的 Host 旁路、反向 RPC 或控制面。
 
-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 连接本进程。
-
-## 功能概览
-
-- **最小常驻工具面**: qlogicagent 只保留推理循环所需的基础执行工具；记忆、Skill、配置、预览浏览器和开发辅助等能力由 Runtime Host 按 Agent/会话通过 MCP 投影
-- **多 LLM Provider**: OpenAI、Anthropic、DeepSeek 等，通过统一 `LLMTransport` 接口切换
-- **编排策略**: failover 降级、指数退避重试、并行工具执行、14+ 上下文压缩策略、多代理团队协作
-- **权限系统**: 命令安全分类、规则引擎、用户审批、破坏性命令警告
-- **记忆系统**: Gateway Host 单一持久化权威 — 项目 memdir (L1) + owner 级语义长期记忆 (L2)；qlogicagent 保留召回、提取、Dream/蒸馏等推理
-- **会话持久化**: JSONL 对话转录 + 状态快照 + 会话恢复
-- **MCP 协议**: stdio/HTTP 传输、动态工具注入、资源发现
-- **插件系统**: 用户级/项目级插件加载、插件 API
-- **技能系统**: 通过 Host Capability MCP 发现/调用 Skill；管理能力仅在用户明确管理 Skill 时由 Host 投影
-- **Hook 系统**: 30+ 生命周期钩子点，可扩展不侵入核心
-
-## 快速开始
+Runtime Host 是以下事实的唯一权威：
 
-### 1. 环境准备
+- canonical owner、project、session、history 和持久化；
+- Provider profile、凭据、权限策略和 Agent 进程生命周期；
+- Skill、MCP、记忆、附件、媒体、连接器和其他 Host 能力。
 
-```bash
-# Node.js 24
-node --version    # v22.x.x+
+qlogicagent 负责：
 
-# 安装依赖
-pnpm install
+- 模型推理、规划、工具选择和单回合执行；
+- Agent 原生基础工具、权限执行点和指令加载器；
+- 当前 native ACP session 的有界进程内上下文；
+- 连接 Host 为该会话投影的普通 MCP server。
 
-# 构建
-pnpm build
-```
+Host canonical session ID 与 adapter native ACP session ID 是两个身份。qlogicagent 不持久化 Host transcript、标题、摘要、恢复状态或项目注册表；进程重启后由 Host 重新投影 canonical history。
 
-### 2. 配置环境变量
+## 协议
 
-```bash
-cp .env.example .env
-```
+Host 只通过 ACP 调用 adapter：
 
-编辑 `.env`：
+- `initialize`
+- `authenticate` / `logout`（由能力协商决定）
+- `session/new`
+- `session/load`
+- `session/prompt`
+- `session/cancel`
+- `session/close`
+- adapter 声明支持的标准 session 配置方法
 
-```bash
-# 日志级别
-LOG_LEVEL=info
-```
+Agent 使用标准 `session/update` 流式提交文本、思考和工具进度，并通过 `session/request_permission` 请求授权。`session/prompt` 结果只包含标准终止原因和可选用量。
 
-托管运行依赖 Runtime Host 提供记忆、配置与能力投影；qlogicagent 不再独立持有这些持久化权威。
+qlogicagent 在 `initialize` 中声明通用 `promptCapabilities.embeddedContext`。Runtime 只按这个能力协商结果，以 `astraclaw.agentContext` `_meta` 投影 Host 上下文；同一规则适用于任何声明该能力的 adapter，不按 Agent ID 分支。
 
-### 3. 运行
+Skill、MCP、记忆、附件、项目、预览、安装和凭据等 Host 能力只通过会话绑定的普通 MCP/Tool 目录提供。qlogicagent 不安装、配置或管理这些 Host 能力。
 
-qlogicagent 作为独立进程运行，由 Electron 桌面壳管理生命周期，openclaw 通过 ACP 协议连接：
+更完整的 wire 边界见 [docs/acp-extensions.md](docs/acp-extensions.md)。
 
-```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"]
-        }
-      },
-      "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.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`)。记忆持久化由 Runtime Host 持有，qlogicagent 通过 Host request/MCP 消费。
-
-```
+```text
 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 / capability-schema-directory
-│   ├── infra/              #   model-registry / task-runtime / background-tasks / agent-paths
-│   ├── ports/              #   端口契约 (memory / model-transport / permission ...)
-│   └── config/             #   tunable-defaults 等运行时配置
-│
-├── skills/              # 工具与技能层
-│   ├── tools/              #   qlogicagent 常驻基础工具
-│   ├── memory/             #   Host 项目记忆存储实现 + Host-backed 召回/Dream/蒸馏
-│   ├── mcp/                #   MCP 桥接
-│   ├── permissions/        #   权限规则引擎 / 设置 / sandbox overlay
-│   ├── plugins/            #   插件系统
-│   └── skill-system/       #   SKILL.md 发现 / 生命周期 / 校验
-│
-├── protocol/            # 线协议：wire/ (Gateway RPC 契约) + notifications + methods
-├── transport/           # ACP server + 事件映射
-├── contracts/           # 纯类型契约（hooks 等，零依赖）
-└── config/              # CLI 参数解析
+├── cli/             ACP 组合根、会话适配、权限和会话级 MCP 装配
+├── agent/           推理与工具循环
+├── orchestration/   Agent 内部的纯策略和子 Agent 执行构件
+├── runtime/         Agent 本地运行时、提示、hooks、native session 投影
+├── skills/          原生基础工具、权限检查、MCP client 和 Skill 读取
+├── protocol/        ACP wire 类型与内部 turn 事件
+├── transport/       ACP server 和标准事件映射
+└── contracts/       内部端口契约
 ```
 
----
-
-## 记忆系统
-
-记忆持久化由 Gateway Host 统一持有；qlogicagent 保留召回、提取、Dream/蒸馏等推理逻辑，并通过 Host Memory MCP/Host request 使用同一份数据。
-
-### 记忆层次
+Provider 传输实现来自 `@xiaozhiclaw/provider-core`。仓内只保留传输端口和组合门面，不复制 Provider 实现。
 
-| 层 | 说明 | 存储 |
-|----|------|------|
-| **L1 memdir** | 项目级文件记忆 (INDEX.md + 主题文件)，由 Host `project_memory` 权威读写 | `<project>/.qlogicagent/memory/` |
-| **L2 长期记忆** | 语义向量记忆，自动提取 + 语义召回 | Gateway Host Memory store |
-| **会话转录** | JSONL 对话记录，用于会话恢复 | `~/.qlogicagent/profiles/<owner>/projectData/<projectId>/sessions/<id>/` |
+## 开发
 
-### 工作方式
-
-在 Gateway 托管会话中，Agent 自动：
-- 在 `memory.before_recall` hook 预取相关长期记忆（按 category 过滤 + 每轮字节封顶后注入系统提示）
-- 通过 Host 投影的 `astraclaw_memory` MCP：`project_memory` 读写项目记忆，`memory_search/read/write` 使用长期记忆（不再注册 qlogicagent 本地 `memory` Tool）
-- 会话过程中自动提取关键信息写入 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
-
-设置后，qlogicagent 的运行数据根目录改为指定目录。托管产品中的凭据、共享指令、Skill 和 Host 记忆仍由 Runtime Host 的配置/存储权威管理，不能用该变量绕过 Host。
-
-典型场景：
-- **测试隔离**：每个测试用例使用独立 `QLOGICAGENT_HOME` 避免互相污染
-- **多实例部署**：同一机器运行多个 agent 实例时各自独立数据目录
+要求 Node.js 24。
 
 ```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/profiles/<owner>/settings.json` | Host 配置权威文件；qlogicagent 仅消费会话解析结果及原生权限段，不提供对话配置 Tool |
-| `~/.qlogicagent/plugins/` | 用户级插件目录 |
-| `~/.qlogicagent/INSTRUCTIONS.md` | 新项目可复制的 qlogicagent 原生指令模板；运行时不作为 Host 共享指令读取 |
-| `~/.qlogicagent/profiles/<owner>/projectData/<projectId>/` | Runtime Host 持有的项目、会话、共享指令和项目记忆数据；不是 qlogicagent 配置面 |
-
-模型/API 密钥、桌面参数和 MCP 绑定只通过 Runtime Host UI/控制面维护。qlogicagent 不读取或写入设备级凭据文件。
-
-### 项目级配置
-
-| 路径 | 说明 |
-|------|------|
-| `.qlogicagent/settings.json` | 项目权限规则 |
-| `.qlogicagent/plugins/` | 项目级插件 |
-| `.qlogicagent/INSTRUCTIONS.md` | 项目指令 |
-| `INSTRUCTIONS.md` | 项目指令 (根目录) |
-| `INSTRUCTIONS.local.md` | 本地私有指令 |
-
-这些项目文件由 qlogicagent 自己的原生指令加载器读取。Host 共享指令是额外基础层，存放在 Host 的 `projectData/<projectId>/shared-instructions/`，不会替换或禁用 `AGENTS.md`、`CLAUDE.md`、上述 qlogicagent 指令文件等各 Agent 原生机制。
-
----
-
-## MCP 投影
-
-qlogicagent 不读取用户级 `~/.qlogicagent/mcp.json`，也不拥有 MCP 安装、凭据或绑定配置。Runtime Host 在 canonical session 建立时传入该会话获准使用的 MCP server；qlogicagent 只负责连接和把工具注入当前会话，解绑时一并释放。
-
-注入后的可调用名称使用 `servername__toolname`。Host 自有能力同样遵循该命名，例如 `astraclaw_memory__project_memory`；这不会注册同名 qlogicagent 本地 Tool。
-
----
-
-## 权限配置
-
-### Host 管理的 owner profile `settings.json`
-
-下例仅说明 qlogicagent 原生权限检查器消费的 `permissions` 段。托管产品应通过 Runtime Host UI/控制面修改，不应让 Agent 在对话中直接编辑该文件。
-
-```json
-{
-  "permissions": {
-    "mode": "default",
-    "defaultBehavior": "ask",
-    "rules": [
-      { "pattern": "read", "behavior": "allow" },
-      { "pattern": "exec", "behavior": "ask" },
-      { "pattern": "write:**/node_modules/**", "behavior": "deny" }
-    ]
-  }
-}
+pnpm install
+pnpm run build
+pnpm run check
 ```
 
-`behavior` 可选值：`allow`（自动允许）、`ask`（请求审批）、`deny`（拒绝）。
-
----
-
-## 开发命令
+本地 ACP 调试：
 
 ```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)
+node dist/cli.js --acp
 ```
 
-## 测试
+`pnpm run check` 是完整门禁，覆盖类型、机械规则、架构边界、全量测试和 npm 制品初始化。边界回归由 `src/cli/ordinary-acp-adapter-boundary.test.ts` 与 Runtime supervisor 测试共同锁定。
 
-```bash
-pnpm test                    # 全部测试
-pnpm test -- test/e2e        # E2E 协议测试
-pnpm test -- --coverage      # 覆盖率
-```
+## 原生文件
 
-- 单元测试：`test/` — LLM provider、orchestration、tool、permission
-- E2E 测试：`test/e2e/` — spawn CLI 进程验证 JSON-RPC 协议
+qlogicagent 继续读取自己的原生指令文件，例如项目中的 `INSTRUCTIONS.md`、`INSTRUCTIONS.local.md` 和 `.qlogicagent/rules`。Host 共享指令是额外基础层，不覆盖或禁用任何 Agent 的原生指令机制。
+
+`QLOGICAGENT_HOME` 只改变 adapter 原生运行数据根目录，不能改变 Host 权威、绕过 Host 凭据或建立第二份 canonical session store。
 
 ## 发布
 
-发布只能由维护者从已与远端同步、工作区干净的 `master` 人工执行：
+发布由维护者从已与远端同步且工作区干净的 `master` 执行：
 
 ```bash
-# 版本更新、提交并推送后，先重新拉取并确认本地 master 与上游一致
-git pull --ff-only
-git status --short --branch
-
-# 只读 preview：运行完整门禁、构建并校验唯一制品，不发布
 node scripts/release.mjs
-
-# preview 通过后，由维护者显式发布同一流程生成并校验的制品
 node scripts/release.mjs --publish
-
-# 确认 registry 中的版本和制品摘要
-npm view qlogicagent@<version> version dist.shasum dist.integrity --json
+npm view qlogicagent@<version> version dist.tarball dist.integrity
 ```
 
-CI 只负责检查，不自动创建 tag 或发布 npm 包。
+第一条命令只做预览和完整门禁；第二条命令显式发布同一流程校验的制品；第三条命令核对已发布版本及不可变制品信息。CI 不自动创建 tag 或发布 npm 包。