CoPaw 深度技术解析 包括端到端对话流程分析（12章节）
·
一个生产级的多智能体 AI 助手框架——从架构设计到工程实现的完整指南
V2更新: 新增第12章「端到端对话流程分析」- 以真实qmd安装场景为例，完整展示CoPaw处理一轮请求的全流程
📋 目录
- 概述：CoPaw 是什么
- 核心架构全景
- 智能体运行时（Agent Runtime）
- 技能系统（Skill System）
- 记忆与上下文管理
- 多智能体协作
- 模型提供商与故障转移
- 消息处理与流式输出
- 会话管理与状态持久化
- 安全与认证机制
- 工程实践与最佳实践
- 端到端对话流程分析 ⭐
1. 概述：CoPaw 是什么
1.1 定位与愿景
CoPaw 是一个面向生产环境的多智能体 AI 助手框架，基于 Python 构建，采用类似 OpenClaw 的架构设计理念。它将大语言模型（LLM）的能力封装为可编排、可扩展、可持久化的智能体服务。
核心使命：让 AI 助手从"玩具"变成"工具"——具备长期记忆、技能扩展、多轮协作的真正生产力工具。
1.2 与同类框架的对比
| 特性 | CoPaw | OpenClaw | AutoGPT |
|---|---|---|---|
| 架构设计 | 网关+智能体分离 | 网关+智能体分离 | 单体架构 |
| 多智能体 | ✅ 原生支持 | ✅ 原生支持 | ❌ 有限 |
| 技能系统 | ✅ 动态加载 | ✅ 动态加载 | ❌ 插件式 |
| 记忆管理 | ✅ 分层记忆 | ✅ 分层记忆 | ⚠️ 向量数据库 |
| 模型支持 | 多提供商 | 多提供商 | OpenAI 为主 |
| 部署方式 | 本地/远程 | 本地/远程 | 云端为主 |
| 开发语言 | Python | TypeScript | Python |
1.3 适用场景
- 个人知识管理：长期对话记忆、文件整理、笔记归档
- 自动化工作流：定时任务、数据抓取、报表生成
- 多平台助手：同时接入 Telegram、Discord、钉钉等多个渠道
- 企业级部署：私有化部署、多用户管理、权限控制
2. 核心架构全景
2.1 用"餐厅"理解 CoPaw
把 CoPaw 想象成一家特殊的智能餐厅：
┌─────────────────────────────────────────────────────────────┐
│ CoPaw 餐厅 │
├─────────────────────────────────────────────────────────────┤
│ 网关 (Gateway) = 餐厅前台 + 点菜系统 │
│ 智能体 (Agent) = 后厨厨师，真正"思考"的部分 │
│ 通道 (Channels) = 不同的点餐方式 │
│ 技能 (Skills) = 厨师的特殊技能 │
│ 记忆 (Memory) = 顾客的用餐偏好记录 │
│ 模型 (Provider) = 食材供应商 (Claude/GPT/本地模型) │
└─────────────────────────────────────────────────────────────┘
2.2 系统架构图
┌─────────────────────────────────────┐
│ 用户界面层 │
│ ┌─────────┐ ┌─────────┐ ┌───────┐ │
│ │Telegram │ │ Discord │ │钉钉 │ │
│ └────┬────┘ └────┬────┘ └───┬───┘ │
└───────┼───────────┼──────────┼─────┘
│ │ │
┌────────────┴───────────┴──────────┴─────┐
│ 网关层 (Gateway) │
│ ┌─────────────────────────────────────┐│
│ │ 消息路由 · 认证授权 · 会话管理 ││
│ │ 默认地址: 127.0.0.1:18789 ││
│ └─────────────────────────────────────┘│
└──────────────────┬──────────────────────┘
│
┌──────────────────┴──────────────────────┐
│ 智能体运行时 (Agent Runtime) │
│ ┌───────────────────────────────────┐ │
│ │ Agent Loop · 工具调用 · 上下文管理 │ │
│ │ 记忆系统 · 技能加载 · 模型交互 │ │
│ └───────────────────────────────────┘ │
└──────────────────┬──────────────────────┘
│
┌──────────────────┴──────────────────────┐
│ 模型提供商层 (Providers) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Claude │ │ GPT-4 │ │ Kimi │ │
│ │(Anthropic)│ │(OpenAI) │ │ (Moonshot)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
└─────────────────────────────────────────┘
2.3 核心组件职责
| 组件 | 职责 | 关键特性 |
|---|---|---|
| Gateway | 消息总线、路由分发、安全认证 | 必须持续运行，所有消息必经 |
| Agent | 处理逻辑、工具调用、记忆管理 | 可动态加载技能，支持多实例 |
| Channel | 外部通信接口 | 支持多平台同时接入 |
| Skill | 功能扩展单元 | 热插拔，按需加载 |
| Memory | 状态持久化 | 分层存储（工作/短期/长期） |
| Provider | LLM 交互层 | 支持故障转移、多模型切换 |
3. 智能体运行时（Agent Runtime）
3.1 Agent Loop 循环
CoPaw 的智能体采用经典的 ReAct（Reasoning + Acting）循环模式：
# 伪代码示意
while task_not_completed:
# 1. 感知：获取当前上下文
context = build_context(memory, user_message, system_prompt)
# 2. 思考：调用 LLM 决定下一步
response = llm.generate(context, tools_available)
# 3. 行动：执行工具调用或生成回复
if response.has_tool_calls:
results = execute_tools(response.tool_calls)
memory.add_observation(results)
else:
return response.content
# 4. 检查：是否完成任务
if response.is_final_answer:
break
3.2 工具调用机制
CoPaw 使用 OpenAI 兼容的 Function Calling 格式：
{
"tool_calls": [
{
"id": "call_abc123",
"type": "function",
"function": {
"name": "execute_shell_command",
"arguments": "{\"command\": \"ls -la\", \"timeout\": 60}"
}
}
]
}
工具执行后，结果被格式化为 tool 角色的消息返回给 LLM：
{
"role": "tool",
"tool_call_id": "call_abc123",
"content": "total 128\ndrwxr-xr-x 5 user group 160 Mar 27 10:00 ."
}
3.3 Agent 工作空间
每个 Agent 拥有独立的工作目录：
~/.copaw/workspace/
├── agents/
│ ├── agent_001/ # Agent 专属空间
│ │ ├── memory/ # 每日记忆文件
│ │ ├── skills/ # 自定义技能
│ │ └── uploads/ # 上传文件缓存
│ └── agent_002/
├── shared/ # 共享资源
│ ├── models/ # 本地模型缓存
│ └── skills/ # 全局技能库
└── logs/ # 运行日志
└── llm_calls.jsonl # LLM 调用记录
4. 技能系统（Skill System）
4.1 技能架构
技能是 CoPaw 的功能扩展单元，采用模块化设计：
active_skills/
├── skill_name/
│ ├── SKILL.md # 技能文档（必需）
│ ├── __init__.py # 技能入口（可选）
│ ├── tools.py # 工具函数（可选）
│ └── resources/ # 资源文件（可选）
│ ├── templates/
│ └── data/
4.2 SKILL.md 规范
每个技能必须包含 SKILL.md，格式如下：
---
name: skill_name
version: 1.0.0
description: 技能的简短描述
triggers:
- 触发词1
- 触发词2
builtin_skill_version: "1.0"
copaw:
emoji: "🛠️"
---
## 使用说明
技能的详细使用说明...
## 工具列表
- `tool_name`: 工具描述
4.3 内置技能一览
| 技能名称 | 功能 | Emoji |
|---|---|---|
file_reader |
读取和总结文本文件 | 📄 |
browser_visible |
可视浏览器操作 | 🌐 |
xlsx |
Excel 文件处理 | 📊 |
pdf |
PDF 文件操作 | 📑 |
pptx |
PowerPoint 生成 | 📽️ |
cron |
定时任务管理 | ⏰ |
multi_agent_collaboration |
多智能体协作 | 🤝 |
pua |
高压问题解决模式 | 💪 |
guidance |
安装配置指导 | 🧭 |
4.4 技能加载机制
技能在 Agent 启动时动态加载：
# 伪代码示意
class SkillLoader:
def load_skill(self, skill_path):
# 1. 读取 SKILL.md
metadata = parse_skill_md(skill_path / "SKILL.md")
# 2. 注册工具
if (skill_path / "tools.py").exists():
tools = import_tools(skill_path / "tools.py")
self.tool_registry.register(tools)
# 3. 加载提示词
if metadata.system_prompt:
self.prompt_manager.add(skill_path / metadata.system_prompt)
return SkillInstance(metadata)
5. 记忆与上下文管理
5.1 三层记忆架构
CoPaw 采用分层记忆系统，平衡 recall 与成本：
┌─────────────────────────────────────────────────────────┐
│ 三层记忆金字塔 │
├─────────────────────────────────────────────────────────┤
│ Level 3: 长期记忆 (Long-term) │
│ ├── MEMORY.md # 精心整理的核心知识 │
│ └── 存储: 关键决策、技术方案、个人偏好 │
│ └── 容量: 无限制 | 更新: 手动 │
├─────────────────────────────────────────────────────────┤
│ Level 2: 短期记忆 (Short-term) │
│ ├── memory/2026-03-27.md # 每日会话记录 │
│ └── 存储: 原始对话、执行记录、思考过程 │
│ └── 容量: ~30天 | 更新: 自动 │
├─────────────────────────────────────────────────────────┤
│ Level 1: 工作记忆 (Working) │
│ ├── 当前会话上下文 │
│ └── 存储: 当前对话历史、系统提示词 │
│ └── 容量: 受限于模型上下文窗口 │
└─────────────────────────────────────────────────────────┘
5.2 记忆文件结构
MEMORY.md（长期记忆）
# MEMORY.md
## 技术决策
- 2026-03-26: 采用 RetryChatModel 包装器进行 LLM 日志记录
- 2026-03-26: 技能系统采用 SKILL.md + 可选代码的混合模式
## 关键配置
- LLM 日志路径: ~/.copaw/llm_calls.jsonl
- 网关地址: 127.0.0.1:18789
## 个人偏好
- 时区: Asia/Shanghai
- 语言: 中文优先
每日笔记（短期记忆）
# memory/2026-03-27.md
## Session: 1774525792430
### 14:30 - 技能系统优化
- 创建了新的文档技能
- 遇到浏览器启动问题，已解决
### 16:45 - 记忆管理
- 更新了 MEMORY.md
- 压缩了昨日会话上下文
5.3 上下文压缩（Compaction）
当上下文窗口接近上限时，CoPaw 自动触发压缩：
# 压缩后的结构化摘要
session_meta:
session_id: "1774525792430"
agent_id: "RRepcB"
model: "kimi-k2.5"
date: "2026-03-26"
deliverables:
- category: "技能"
item: "llm_log_viewer"
status: "完成"
- category: "分析"
item: "最小 token 日志分析"
status: "完成"
insights:
architecture:
- "CoPaw 使用 RetryChatModel → OpenAIChatModelCompat → OpenAIChatModel 链"
decisions:
- "在包装器层添加日志，确保所有调用都被记录"
next_steps:
- "继续优化技能系统"
6. 多智能体协作
6.1 多智能体路由
CoPaw 支持多个 Agent 实例协作：
┌─────────────┐
用户消息 ──────▶│ Gateway │
└──────┬──────┘
│
┌──────────────┼──────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Agent:助手 │ │ Agent:专家 │ │ Agent:执行 │
│ (通用对话) │ │ (代码审查) │ │ (任务执行) │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
└──────────────┼──────────────┘
▼
┌─────────────┐
│ 结果汇总 │
└─────────────┘
6.2 智能体间通信
Agent 间通过消息总线通信：
# Agent A 请求协作
response = agent.chat(
agent_id="expert_agent",
message="请审查这段代码...",
context=shared_context
)
# 专家 Agent 返回结果
{
"agent_id": "expert_agent",
"response": "发现3个问题：1. ... 2. ...",
"confidence": 0.95
}
6.3 典型协作场景
| 场景 | Agent 分工 | 协作方式 |
|---|---|---|
| 代码开发 | 架构师 → 开发者 → 审查者 | 顺序流水线 |
| 数据分析 | 数据工程师 → 分析师 → 可视化专家 | 并行+汇总 |
| 内容创作 | 研究员 → 写作者 → 编辑 | 迭代反馈 |
7. 模型提供商与故障转移
7.1 模型链架构
┌────────────────────────────────────────────────────┐
│ RetryChatModel │
│ - 重试策略 (指数退避) │
│ - 故障转移 (Failover) │
│ - 日志记录 (可选) │
└──────────────────┬─────────────────────────────────┘
│
┌──────────────────┴─────────────────────────────────┐
│ OpenAIChatModelCompat │
│ - API 格式兼容 │
│ - 参数标准化 │
└──────────────────┬─────────────────────────────────┘
│
┌──────────────────┴─────────────────────────────────┐
│ OpenAIChatModel │
│ - HTTP 请求构造 │
│ - 流式响应处理 │
│ - Token 用量统计 │
└──────────────────┬─────────────────────────────────┘
│
┌──────┴──────┐
▼ ▼
┌───────────┐ ┌───────────┐
│ Kimi API │ │ Claude API│
│ (Moonshot)│ │(Anthropic)│
└───────────┘ └───────────┘
7.2 故障转移策略
# 配置示例
model_config = {
"primary": "kimi-cn:kimi-k2.5",
"fallbacks": [
"openai:gpt-4",
"anthropic:claude-3-opus"
],
"retry_policy": {
"max_retries": 3,
"backoff_factor": 2.0,
"timeout": 60
}
}
7.3 支持的模型提供商
| 提供商 | 标识 | 特点 |
|---|---|---|
| Moonshot (Kimi) | kimi-cn |
中文优化，长上下文 |
| OpenAI | openai |
通用能力强，生态完善 |
| Anthropic | anthropic |
安全性高，推理能力强 |
| Ollama | ollama |
本地部署，隐私优先 |
| Azure OpenAI | azure |
企业合规，SLA 保障 |
8. 消息处理与流式输出
8.1 消息生命周期
1. 用户发送消息
│
▼
2. Gateway 接收并验证
│
▼
3. 路由到对应 Agent
│
▼
4. Agent 构建上下文
┌─────────────────┐
│ 系统提示词 │
│ 历史消息 │
│ 当前消息 │
│ 可用工具 │
└─────────────────┘
│
▼
5. 调用 LLM (流式)
┌─────────────────┐
│ chunk 1: "Hello"│
│ chunk 2: "world"│
│ chunk 3: "!" │
└─────────────────┘
│
▼
6. 返回给用户
8.2 流式输出实现
async def stream_response(messages, tools):
async for chunk in llm.astream(messages, tools=tools):
# 解析 chunk
delta = chunk.choices[0].delta
if delta.content:
# 文本内容
yield {"type": "content", "data": delta.content}
if delta.tool_calls:
# 工具调用
yield {"type": "tool_call", "data": delta.tool_calls}
8.3 消息格式规范
{
"messages": [
{
"role": "system",
"content": "你是猫头鹰，CoPaw 内部逻辑向导..."
},
{
"role": "user",
"content": "帮我分析一下日志"
},
{
"role": "assistant",
"content": null,
"tool_calls": [
{
"id": "call_123",
"type": "function",
"function": {
"name": "read_file",
"arguments": "{\"file_path\": \"log.txt\"}"
}
}
]
},
{
"role": "tool",
"tool_call_id": "call_123",
"content": "日志内容..."
}
]
}
9. 会话管理与状态持久化
9.1 会话结构
@dataclass
class Session:
session_id: str # 唯一标识
agent_id: str # 所属 Agent
user_id: str # 用户标识
channel: str # 来源渠道
messages: List[Message] # 消息历史
metadata: Dict # 会话元数据
created_at: datetime # 创建时间
updated_at: datetime # 最后活跃
expires_at: datetime # 过期时间
9.2 会话修剪策略
为防止内存无限增长，CoPaw 实施会话修剪：
# 修剪策略配置
pruning_config = {
"max_messages": 100, # 单会话最大消息数
"max_age_hours": 24, # 会话最大存活时间
"summary_threshold": 50, # 触发摘要的消息数
"keep_recent": 10 # 始终保留的最近消息数
}
# 修剪流程
async def prune_session(session):
if len(session.messages) > pruning_config["max_messages"]:
# 1. 生成历史摘要
summary = await generate_summary(
session.messages[:-pruning_config["keep_recent"]]
)
# 2. 替换旧消息为摘要
session.messages = [
Message(role="system", content=f"历史摘要: {summary}"),
*session.messages[-pruning_config["keep_recent"]:]
]
9.3 状态持久化
sessions/
├── active/ # 活跃会话（内存）
├── archived/ # 归档会话（磁盘）
│ ├── 2026-03/
│ │ ├── session_001.json
│ │ └── session_002.json
│ └── 2026-04/
└── index.db # 会话索引
10. 安全与认证机制
10.1 配对（Pairing）机制
CoPaw 默认采用配对码机制防止未授权访问：
1. 陌生人发送消息
│
▼
2. Gateway 拦截
│
▼
3. 生成配对码: ABC123
│
▼
4. 通知管理员
│
▼
5. 管理员执行: copaw pairing approve ABC123
│
▼
6. 陌生人获得访问权限
10.2 OAuth 集成
支持第三方 OAuth 认证：
# config/oauth.yaml
google:
client_id: "xxx.apps.googleusercontent.com"
client_secret: "xxx"
redirect_uri: "http://localhost:18789/oauth/callback"
scopes:
- "openid"
- "email"
- "profile"
github:
client_id: "xxx"
client_secret: "xxx"
10.3 远程访问安全
┌─────────────────┐ Tailscale VPN ┌─────────────────┐
│ 手机 (远程) │◄─────────────────────▶│ CoPaw 服务器 │
│ 100.x.x.x │ 加密隧道 │ 100.y.y.y │
└─────────────────┘ └─────────────────┘
│
┌──────┴──────┐
▼ ▼
127.0.0.1:18789 防火墙保护
11. 工程实践与最佳实践
11.1 项目结构规范
copaw-project/
├── .copaw/ # CoPaw 配置目录
│ ├── config.yaml # 主配置
│ ├── providers.yaml # 模型配置
│ └── workspace/ # 工作空间
│
├── active_skills/ # 激活的技能
│ ├── my_custom_skill/
│ │ ├── SKILL.md
│ │ └── tools.py
│ └── another_skill/
│
├── memory/ # 记忆文件
│ ├── MEMORY.md
│ └── 2026-03-27.md
│
└── docs/ # 项目文档
└── README.md
11.2 配置管理
# config.yaml
agent:
name: "猫头鹰"
identity: "CoPaw 内部逻辑向导"
timezone: "Asia/Shanghai"
language: "zh"
model:
default: "kimi-cn:kimi-k2.5"
temperature: 0.7
max_tokens: 4000
memory:
daily_notes: true
compaction_threshold: 50
skills:
auto_load: true
builtin:
- file_reader
- browser_visible
- xlsx
- pdf
11.3 调试与监控
LLM 调用日志
# 查看最近日志
copaw logs --tail 100
# 分析 token 用量
copaw logs --stats --since "1 day ago"
# 导出日志
copaw logs export --format jsonl --output llm_logs.jsonl
实时监控
# 查看 Agent 状态
copaw agent status
# 查看活跃会话
copaw sessions list --active
# 查看技能加载情况
copaw skills list --verbose
11.4 性能优化建议
| 优化点 | 建议 | 效果 |
|---|---|---|
| 上下文长度 | 定期触发 compaction | 降低 token 成本 |
| 工具调用 | 减少不必要的工具定义 | 降低决策延迟 |
| 模型选择 | 简单任务用轻量模型 | 降低成本 |
| 缓存策略 | 缓存常用查询结果 | 减少重复调用 |
| 并发处理 | 使用 async/await | 提高吞吐量 |
11.5 故障排查清单
## Agent 无响应
- [ ] 检查 Gateway 是否运行: `copaw gateway status`
- [ ] 检查模型配置: `copaw model test`
- [ ] 查看日志: `copaw logs --level error`
## 技能加载失败
- [ ] 检查 SKILL.md 格式
- [ ] 验证 Python 依赖
- [ ] 查看技能日志: `copaw skills logs <skill_name>`
## 记忆丢失
- [ ] 检查 workspace 目录权限
- [ ] 验证 MEMORY.md 格式
- [ ] 检查磁盘空间
附录
A. 术语表
| 术语 | 说明 |
|---|---|
| Agent | 智能体，执行任务的 AI 实体 |
| Skill | 技能，功能扩展单元 |
| Channel | 通道，外部通信接口 |
| Gateway | 网关，系统消息总线 |
| Provider | 模型提供商，如 OpenAI、Kimi |
| Context | 上下文，当前对话环境 |
| Memory | 记忆，持久化存储的对话历史 |
| Compaction | 压缩，上下文精简过程 |
B. 参考资源
- OpenClaw 文档 - 架构设计参考
- AgentScope - 底层模型框架
- CoPaw GitHub - 源码仓库
C. 版本信息
| 版本 | 日期 | 主要变更 |
|---|---|---|
| 1.0.0 | 2026-03-27 | 初始文档创建 |
文档维护: 猫头鹰 (CoPaw 内部逻辑向导)
最后更新: 2026-03-27
12. 端到端对话流程分析 ⭐【V2新增章节】
本章以真实场景为例，完整展示 CoPaw 处理一轮对话请求的全流程。
场景：用户请求"帮我配置 qmd 技能，并同步记忆文件"
时间范围：2026-03-27 09:30 - 09:36
12.1 场景设定与请求入口
12.1.1 用户请求
时间: 2026-03-27 09:30:00
用户: "本地安装qmd技能，其它agent都已经装了"
会话ID: session_1774525792430
AgentID: RRepcB (猫头鹰)
12.1.2 请求入口处理（Gateway层）
# Gateway 接收请求流程
1. HTTP POST /v1/agents/RRepcB/chat
Body: {"message": "本地安装qmd技能，其它agent都已经装了",
"session_id": "1774525792430"}
2. 认证鉴权
- 验证 API Key
- 检查用户权限
- 限流检查（Rate Limit: 100/min）
3. 消息路由
- 解析 target_agent = "RRepcB"
- 查找 Agent 实例（存在，直接使用）
- 将消息放入 Agent 的消息队列
4. 日志记录
- 记录请求元数据（时间、用户、消息长度）
- 生成 trace_id 用于全链路追踪
12.1.3 Agent 接收消息
# Agent.message_handler 接收消息
class Agent:
def handle_message(self, message: Message):
# 1. 解析消息
user_content = message.content
session_id = message.session_id
# 2. 加载会话上下文
session = self.session_manager.get(session_id)
# 3. 触发 ReAct Loop
response = self.react_loop.run(
user_message=user_content,
session=session,
tools=self.skills.get_available_tools()
)
return response
12.2 消息处理流水线
12.2.1 ReAct Loop 启动
# ReAct Loop 核心流程
def react_loop(user_message, session, tools):
"""
输入: "本地安装qmd技能，其它agent都已经装了"
"""
# Step 1: 构建系统提示词
system_prompt = build_system_prompt()
# 包含：Agent身份(猫头鹰)、核心准则、工具列表、记忆管理规则
# Step 2: 加载工作记忆
working_memory = session.get_history(limit=20) # 最近20轮对话
# Step 3: 检索相关长期记忆
relevant_memories = memory_search(query=user_message, top_k=5)
# 查询: "qmd技能安装" → 返回 MEMORY.md 中的 qmd 配置记录
# Step 4: 构建完整上下文
context = {
"system": system_prompt,
"memories": relevant_memories,
"history": working_memory,
"user": user_message
}
12.2.2 技能路由决策
# Agent 分析用户需求，决定调用哪些技能
"""
用户意图分析:
- "本地安装qmd技能" → 需要安装/配置技能
- "其它agent都已经装了" → 参考其他Agent的配置
技能匹配:
- qmd_memory_sync (记忆同步) - 相关
- file_reader (文件读取) - 可能需要查看其他Agent配置
- execute_shell_command (执行命令) - 需要执行安装
- qmd (本地搜索) - 配置完成后使用
决策: 先安装qmd，然后配置记忆同步
"""
tools_to_use = [
"glob_search", # 查找其他Agent的qmd安装
"execute_shell_command", # 执行安装命令
"write_file", # 创建配置文件
"edit_file" # 修改记忆文件
]
12.3 技能路由与工具调用
12.3.1 第一轮工具调用：查找其他Agent配置
# LLM 决定先查找其他Agent是否已有qmd
function_call = {
"name": "glob_search",
"arguments": {
"pattern": "**/qmd/**",
"path": "C:\\zss_workspace"
}
}
# 执行结果
result = [] # 未找到，其他Agent也没有qmd
# LLM 推理: "其他Agent也没有安装，需要从 clawhub 安装"
12.3.2 第二轮工具调用：下载并安装qmd
# LLM 决定从 clawhub 下载 qmd SKILL.md
function_call_1 = {
"name": "execute_shell_command",
"arguments": {
"command": "mkdir active_skills\\qmd"
}
}
function_call_2 = {
"name": "execute_shell_command",
"arguments": {
"command": "powershell -Command \"Invoke-WebRequest -Uri 'https://clawhub.ai/steipete/qmd' -OutFile 'active_skills/qmd/SKILL.md'\""
}
}
# 执行结果: 成功下载 SKILL.md (26,633 bytes)
# 但发现是HTML页面，需要下载zip包
function_call_3 = {
"name": "execute_shell_command",
"arguments": {
"command": "powershell -Command \"Invoke-WebRequest -Uri 'https://wry-manatee-359.convex.site/api/v1/download?slug=qmd' -OutFile 'active_skills/qmd/qmd.zip'\""
}
}
# 解压并安装
function_call_4 = {
"name": "execute_shell_command",
"arguments": {
"command": "powershell -Command \"Expand-Archive -Path 'active_skills/qmd/qmd.zip' -DestinationPath 'active_skills/qmd/' -Force\""
}
}
# 执行结果: 成功安装 qmd 技能
# - SKILL.md (817 bytes)
# - _meta.json (122 bytes)
12.3.3 第三轮工具调用：配置Ollama
# 检测 Ollama 状态
function_call = {
"name": "execute_shell_command",
"arguments": {
"command": "curl http://localhost:11434/api/version"
}
}
# 结果: {"version":"0.18.2"} - Ollama运行中
# 拉取embedding模型
function_call_1 = {
"name": "execute_shell_command",
"arguments": {
"command": "ollama pull nomic-embed-text"
}
}
function_call_2 = {
"name": "execute_shell_command",
"arguments": {
"command": "ollama pull shaw/dmeta-embedding-zh"
}
}
# 执行结果: 两个模型下载完成
# - nomic-embed-text: 274MB
# - shaw/dmeta-embedding-zh: 408MB
12.3.4 第四轮工具调用：修复better-sqlite3
# qmd 依赖 better-sqlite3，需要原生模块
function_call = {
"name": "execute_shell_command",
"arguments": {
"command": "cd \"%APPDATA%\\npm\\node_modules\\@tobilu\\qmd\" && npm rebuild better-sqlite3"
}
}
# 执行结果: rebuilt dependencies successfully
12.3.5 第五轮工具调用：创建记忆集合并索引
# 创建 memory 集合
function_call_1 = {
"name": "execute_shell_command",
"arguments": {
"command": "qmd-wrapper.bat collection add memory --name memory --mask \"*.md\""
}
}
# 索引所有工作区文档
function_call_2 = {
"name": "execute_shell_command",
"arguments": {
"command": "qmd-wrapper.bat collection add . --name copaw --mask \"**/*.md\""
}
}
# 执行结果:
# - memory集合: 3个文件
# - copaw集合: 251个文件
12.4 LLM推理与响应生成
12.4.1 汇总执行结果
# 所有工具调用完成，汇总结果
execution_summary = {
"qmd_skill_installed": True,
"location": "active_skills/qmd/",
"ollama_status": "running (v0.18.2)",
"models_installed": ["nomic-embed-text", "shaw/dmeta-embedding-zh"],
"native_deps": "rebuilt",
"collections": {
"memory": {"files": 3, "path": "memory/*.md"},
"copaw": {"files": 251, "path": "**/*.md"}
}
}
# LLM 生成最终回复
response = llm.generate(
context=execution_summary,
instruction="生成安装完成报告，包含使用说明"
)
12.4.2 生成响应内容
## ✅ qmd 技能安装完成！
| 项目 | 详情 |
|------|------|
| **技能名称** | qmd |
| **来源** | https://clawhub.ai/steipete/qmd |
| **安装路径** | `active_skills/qmd/` |
### 已配置集合
- `copaw` (251个文件) - 所有工作区文档
- `memory` (3个文件) - 每日记忆文件
### 使用方式
```bash
# 搜索记忆
qmd-wrapper.bat query -c memory "关键词"
# 更新索引
qmd-wrapper.bat update
### 12.5 输出发送与会话更新
#### 12.5.1 流式输出
```python
# 通过 WebSocket 流式发送响应
for chunk in response_stream:
websocket.send({
"type": "content",
"data": chunk,
"session_id": "1774525792430"
})
# 发送完成标记
websocket.send({
"type": "done",
"session_id": "1774525792430"
})
12.5.2 会话状态更新
# 更新工作记忆
session.add_message({
"role": "user",
"content": "本地安装qmd技能，其它agent都已经装了",
"timestamp": "2026-03-27T09:30:00Z"
})
session.add_message({
"role": "assistant",
"content": response_content,
"timestamp": "2026-03-27T09:36:00Z",
"tools_used": ["glob_search", "execute_shell_command", "write_file"]
})
# 持久化到磁盘
session.save()
12.5.3 记忆文件更新
# 自动更新每日笔记
edit_file(
"memory/2026-03-27.md",
old_text="",
new_text="""
## qmd + Ollama 配置完成
### 配置清单
- [x] Ollama 服务运行 (v0.18.2)
- [x] Embedding模型: nomic-embed-text (274MB)
- [x] Embedding模型: shaw/dmeta-embedding-zh (408MB)
- [x] qmd CLI 安装完成
- [x] better-sqlite3 原生模块重建
- [x] 集合创建: copaw (251个文件), memory (3个文件)
"""
)
# 更新长期记忆
edit_file(
"MEMORY.md",
old_text="| llm_log_viewer | `active_skills/llm_log_viewer/` | 查看 LLM 对话日志 | 📜 |",
new_text="""| llm_log_viewer | `active_skills/llm_log_viewer/` | 查看 LLM 对话日志 | 📜 |
| qmd | `active_skills/qmd/` | 本地搜索/索引 CLI | 📝 |"""
)
12.6 完整时序图
用户 Gateway Agent Skills LLM Ollama
| | | | | |
|──"安装qmd技能"──▶| | | | |
| │──route(msg)───────▶| | | |
| | │──load_session()────│ | |
| | │◀──session──────────│ | |
| | │ | | |
| | │──memory_search()────▶| | |
| | │◀──results───────────│ | |
| | │ | | |
| | │─────── LLM调用 ──────────────────────────▶|
| | │◀────── response ─────────────────────────│
| | │ | | |
| | │──glob_search()──────▶| | |
| | │◀──results───────────│ | |
| | │ | | |
| | │──curl(Ollama)───────▶| │──check()──▶|
| | │◀──running───────────│ │◀───────────│
| | │ | | |
| | │──execute_shell()────▶| | |
| | │ (mkdir) │ | |
| | │◀──done──────────────│ | |
| | │ | | |
| | │──download(qmd)──────▶| | |
| | │◀──SKILL.md──────────│ | |
| | │ | | |
| | │──npm(rebuild)───────▶| | |
| | │◀──success───────────│ | |
| | │ | | |
| | │──ollama(pull)───────▶| │──pull()───▶|
| | │◀──models────────────│ │◀───────────│
| | │ | | |
| | │──qmd(collection)────▶| | |
| | │◀──indexed───────────│ | |
| | │ | | |
| | │─────── LLM调用(汇总) ────────────────────▶|
| | │◀────── final_response ───────────────────│
| | │ | | |
| │◀──stream_response───│ | | |
|◀─────chunk1───────│ | | | |
|◀─────chunk2───────│ | | | |
|◀──────done───────│ | | | |
| | │ | | |
| | │──save_session()─────▶| | |
| | │──update_memory()────▶| | |
| | │ | | |
[总耗时: ~6分钟]
[Token消耗: ~15,000 input, ~2,000 output]
[工具调用: 12次]
12.7 关键洞察与性能分析
12.7.1 延迟分布
| 阶段 | 耗时 | 占比 | 优化建议 |
|---|---|---|---|
| 消息路由 | <100ms | <1% | - |
| 记忆检索 | ~500ms | 8% | 使用qmd缓存 |
| LLM推理(决策) | ~2s | 33% | 批量请求 |
| 工具执行(下载) | ~3min | 50% | 主要瓶颈 |
| 模型下载 | 并行 | - | 预下载镜像 |
| 响应生成 | ~1s | 17% | - |
12.7.2 Token消耗分析
System Prompt: ~2,000 tokens
Memory Context: ~3,000 tokens
History(20轮): ~5,000 tokens
User Message: 20 tokens
Tool Results: ~5,000 tokens
─────────────────────────────
Total Input: ~15,000 tokens
Output: ~2,000 tokens
12.7.3 瓶颈识别与优化
主要瓶颈:
- 模型下载 (nomic-embed-text: 274MB, shaw/dmeta-embedding-zh: 408MB)
- npm rebuild (编译原生模块)
优化策略:
- 预下载常用模型到镜像
- 使用预编译的 better-sqlite3 二进制包
- 启用并行下载
12.7.4 数据持久化流程
对话完成
│
├──► 工作记忆 ──► 保存到 session.json
│
├──► 提取关键事件 ──► 追加到 memory/2026-03-27.md
│
└──► 提取核心知识 ──► 更新 MEMORY.md
版本更新日志
V2 (2026-03-27)
- 新增: 第12章 端到端对话流程分析
- 内容: 以真实qmd安装场景为例，完整展示从请求入口到记忆更新的全流程
- 包含: 时序图、性能分析、Token消耗、瓶颈识别
文档结束 - V2版本
AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。
更多推荐
8
0- 0
已为社区贡献1条内容
所有评论(0)