QClaw 执行诊断与优化

> 本技能是 QClaw 执行问题的诊断工具。当用户反馈"QClaw 不执行""指令没反应""报权限错误""上下文丢了"等问题时，按本技能的流程逐步排查。

诊断总流程

收到问题报告后，按以下顺序逐项排查，定位到具体原因后直接给出修复方案，不继续后续步骤：

1. 指令设计检查 → 2. 执行链路追踪 → 3. 权限边界确认 → 4. 上下文连贯性验证

1. 指令设计检查

常见问题模式

| 问题模式 | 表现 | 修复 |

|---------|------|------|

| 复合指令 | 一条指令包含 3+ 动作 | 拆分为单动作指令序列 |

| 模糊变量 | "从某处获取某些资料" | 明确来源、范围、筛选条件 |

| 隐式依赖 | "把刚才的结果整理一下" | 显式引用前置结果 |

| 过度限定 | 堆砌限定词导致意图模糊 | 精简为核心动作+必要参数 |

指令拆解方法

原则：一条指令 = 一个核心动作 + 明确参数。

示例：

❌ 原指令：

> "帮我从微信、邮件和文档中收集项目资料，分类整理后保存到指定文件夹"

✅ 拆解为：

1. "从微信聊天记录中读取关于项目X的资料，保存到 E:\项目\临时\微信"
2. "从邮件中读取主题包含'项目X'的邮件附件，保存到 E:\项目\临时\邮件"
3. "从 E:\文档 中提取项目X相关内容，保存到 E:\项目\临时\文档"
4. "将 E:\项目\临时 下所有文件按类型（图片/文档/表格）分类，移到对应子文件夹"
5. "将 E:\项目\临时\分类后 的内容归档到 E:\项目\归档"

参数明确性检查清单

对每条指令确认：

• [ ] 动作动词唯一且明确（读取/写入/移动/删除/查询）
• [ ] 数据来源指定（具体路径/应用/账号）
• [ ] 筛选条件具体（关键词/时间范围/文件类型）
• [ ] 输出目标明确（保存路径/格式/命名规则）

2. 执行链路追踪

QClaw 指令执行链路

用户输入 → 协议解析 → Agent路由匹配 → 上下文组装 → 工具/技能调度 → 执行 → 结果返回

各环节常见故障：

| 环节 | 故障表现 | 排查方法 |

|------|---------|---------|

| 协议解析 | 输入被截断或格式异常 | 检查输入是否包含特殊字符、超长内容 |

| Agent路由 | 指令发到了错误的 Agent | 确认当前会话绑定的 Agent 是否正确 |

| 上下文组装 | 历史对话干扰当前执行 | 检查是否需要清除无关上下文 |

| 工具调度 | 调用了错误的工具或技能 | 查看执行日志确认工具匹配 |

| 执行 | 工具执行超时或报错 | 检查具体错误信息，按工具文档排查 |

实操排查步骤

当指令无响应或结果异常时：

1. 简化复现：用最简指令测试同类操作，确认是否普遍性问题
2. 分段执行：将多步操作拆开，逐段执行定位故障点
3. 检查日志：查看 Agent 执行日志中的错误信息
4. 对照测试：用一个已知可工作的简单指令验证环境正常

3. 权限边界诊断

权限层级

QClaw 的权限涉及以下层面：

| 层级 | 说明 | 典型限制 |

|------|------|---------|

| 系统权限 | 操作系统级别的文件/网络访问控制 | 文件只读、防火墙拦截 |

| QClaw 沙箱 | QClaw 配置的工具执行范围限制 | 工作目录限制、命令白名单 |

| 工具权限 | 各工具自身的访问边界 | API 调用频率、认证过期 |

诊断方法

最小粒度测试法：用最简单的操作逐步测试权限边界。

Step 1: 测试文件读取 → cat/type 一个已知存在的文件
Step 2: 测试文件写入 → 在指定目录创建一个测试文件
Step 3: 测试命令执行 → 运行一条无害命令（如 echo/date）
Step 4: 测试目标应用访问 → 执行最简单的应用操作

每步成功则进入下一步，失败则定位到具体权限层。

常见权限问题与修复

| 现象 | 可能原因 | 修复 |

|------|---------|------|

| 文件写入被拒 | 路径超出工作目录范围 | 使用工作目录内路径，或配置允许的目录 |

| 命令执行被拒 | 命令不在白名单中 | 检查 tools.exec 配置 |

| API 调用失败 | 认证过期或配额用尽 | 检查对应 API Key 和配额 |

| 提权请求被拒 | 非管理员权限操作 | 确认是否需要 /approve 提权 |

4. 上下文连贯性维护

核心机制

QClaw 的上下文管理基于 LCM（Lossless Context Management）：

• 活跃上下文：当前对话中的完整消息历史
• 压缩摘要：超出窗口时自动压缩早期对话为摘要
• 跨会话记忆：通过 MEMORY.md 和 memory/*.md 文件持久化

常见上下文问题

| 问题 | 原因 | 修复 |

|------|------|------|

| AI 忘记了之前说的事 | 对话被压缩，关键信息丢失 | 重要信息写入 memory 文件 |

| 多轮任务中途断档 | 插入无关对话打断了任务线索 | 专注任务，避免穿插无关指令 |

| 跨会话信息丢失 | 会话结束，上下文未持久化 | 任务关键信息主动写入 memory |

| 摘要压缩后细节丢失 | LCM 压缩保留了语义但丢失细节 | 用 lcm_expand 展开摘要恢复细节 |

上下文保持最佳实践

1. 重要信息即写即存：不要依赖"AI 记住了"，关键数据写入 memory 文件
2. 多步任务保持连贯：连续指令之间明确引用前一步的结果
3. 跨会话使用语义锚点：在指令中用唯一标识引用之前的操作结果
• 例："[项目资料收集] 基于上一步收集的微信资料，继续从邮件中提取"
4. 长任务拆分存档：大任务每完成一个阶段，将中间结果写入文件

语义锚点用法

语义锚点是在多轮对话中标记关键上下文的标签，帮助 AI 精准回溯：

第一轮："[锚点：环境检测] 检查当前开发环境，记录已安装的工具列表。请将检测结果保存到 memory/。"
第二轮："[锚点：环境检测] 基于检测结果，安装缺失的依赖。"
第三轮："[锚点：环境检测] 验证所有依赖安装成功。"

注意：语义锚点依赖 AI 在同一会话中的理解能力，不是系统级功能。确保锚点标签唯一且语义清晰。

常见问题速查表

| 症状 | 首选排查 | 参考章节 |

|------|---------|---------|

| 指令无响应 | 检查是否复合指令/模糊变量 | §1 指令设计检查 |

| 执行结果不符预期 | 简化指令复现，分段执行 | §2 执行链路追踪 |

| 权限报错 | 最小粒度权限测试 | §3 权限边界诊断 |

| AI 忘记了之前说的 | 检查信息是否写入 memory | §4 上下文连贯性维护 |

| 跨会话任务断档 | 检查 memory 文件是否完整 | §4 上下文连贯性维护 |

| 执行超时 | 检查网络/目标应用状态 | §2 + §3 |

优化清单

完成诊断后，按以下清单给出优化建议：

• [ ] 指令是否为单动作单元？
• [ ] 参数是否全部明确（来源/范围/输出）？
• [ ] 是否避免了隐式依赖？
• [ ] 权限是否在允许范围内？
• [ ] 关键上下文是否已持久化到 memory？
• [ ] 多步任务是否有语义锚点串联？