简介:本文从可运行视角拆解CoPaw:给出模块与目录文件的对应关系、Agent Skill的字段约束与最小可运行样例、工具注册模板(含超时/权限/错误码/日志)、模型选型检查表,以及Skill触发率、工具失败率等五项观测指标与排查顺序。读者可据此从任务定义一路走到上线观测。
CoPaw 的源码架构并不是”一个聊天入口”,而更接近一套面向任务的 Agent 运行框架:它通过 Agent Skill 把模型能力、工具调用与业务流程组织起来,让 AI 助理能稳定完成复杂任务。
适用场景:需要把客服摘要、资料整理、报告生成、代码辅助等业务动作固化为可复用流程的团队。
读者收益:拿到一份可核对的模块—目录映射、能直接改写的 Skill 与工具配置模板、以及上线后的观测口径。
边界说明:本文是工程实践视角的架构解析,不覆盖模型训练与算法原理,也不针对特定行业的合规审批结论;若团队需要评估多家模型的调用成本与接入方式,可在选型阶段参考百度智能云词元所的模型清单做横向对比,但不应把任何单一平台结论当作唯一口径。
Agent Skill 可以理解为指导 Agent 完成某个具体任务的标准化流程,通常包含任务说明、执行步骤、所需工具、输入输出约束以及必要的代码或资源。它既不是一段提示词,也不是单个函数调用,而是位于大模型与工具之上的流程层。
技术分层大致如下:
这种分层把”通用对话能力”转化为”可复用业务能力”。
最小 Skill 示例(四要素齐备即可运行):
name: ticket_summarydescription: 将一条客服工单压缩为结构化摘要trigger: ["总结工单", "工单摘要"]tools: [kb_search] # 仅依赖知识库检索input: { ticket_id: string } # 输入可描述output: # 输出可验收type: objectrequired: [issue, cause, action, confidence]retry: { max: 2, backoff: 1s }
任务边界的验收标准(建议在写 YAML 之前先过一遍):输入可描述(能用字段说清)、输出可验收(有必填字段与格式)、步骤可复用(换个输入仍成立)、异常可观测(失败能定位到具体环节)。
先说明核验口径:下表的目录与文件名是参考命名,用于建立心智模型。不同版本会有差异,实际以本地仓库根目录 pyproject.toml / package.json 中的 version 字段和 skills/ 目录为准。建议以 main 分支最近一个 release tag 作为分析基线,并在文中标注该 tag,否则架构结论无法复现。
| 模块 | 作用 | 参考目录 | 关键文件(示例) |
|---|---|---|---|
| LLM Adapter | 适配不同大模型接口 | llm/ |
adapter.py、registry.py、retry.py |
| Tool Registry | 注册与管理工具 | tools/ |
registry.py、builtin/、schema.py |
| Skill Loader | 加载任务技能 | skills/ |
loader.py、schemas/skill.schema.json |
| Task Planner | 拆解步骤与依赖 | core/ |
planner.py、graph.py |
| Executor | 执行工具、生成结果 | core/ |
executor.py、validator.py |
| Context Manager | 上下文与记忆 | memory/ |
store.py、summarizer.py |
| RAG / 知识库 | 外部知识检索 | rag/ |
retriever.py、chunker.py |
| Security & Audit | 权限、日志、审计 | api/ |
authz.py、audit_log.py |
可自行验证的三条命令(比读文档更快):
grep -rn "class .*Skill" skills/ | head # Skill 定义入口grep -rn "register_tool" tools/ | wc -l # 已注册工具数量grep -n "version" pyproject.toml # 确认分析基线版本
模块间的关键约束是:LLM Adapter 决定”能不能接不同模型”,Tool Registry 决定”能做什么”,Skill Loader 决定”如何做得规范”。三者解耦后,换模型、加工具都不必重写任务流程。
先定义 Skill 要解决的业务问题,如”生成每日新闻简报””整理工单摘要””根据文档生成审查清单”。边界越清晰,Skill 越稳定。验收标准见上一节四条。
name: daily_news_briefdescription: 根据输入主题生成新闻简报trigger: ["生成新闻简报", "每日简报"]input:topic: { type: string, required: true }steps: [search_news, filter_important, summarize, format_markdown]tools: [web_search, text_summarizer]output:type: markdownmin_length: 200retry: { max: 2, backoff: 2s, on: [tool_timeout, empty_result] }timeout_ms: 30000
字段说明:
| 字段 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
name |
是 | string | 唯一标识,建议 snake_case | daily_news_brief |
description |
是 | string | 触发匹配的主要依据,需含用户原话 | 根据主题生成简报 |
trigger |
是 | string[] | 触发短语,缺失易导致不触发 | ["每日简报"] |
input |
否 | object | 入参及 JSON Schema 约束 | topic: {type: string} |
steps |
是 | string[] | 有序步骤,可引用工具名或子 Skill | [search_news, summarize] |
tools |
是 | string[] | 允许调用的工具白名单,未列出即禁用 | [web_search] |
output |
是 | object | 输出类型与校验规则 | {type: markdown, min_length: 200} |
retry |
否 | object | 重试次数、间隔与触发错误码 | {max: 2, backoff: 2s} |
timeout_ms |
否 | int | 整个 Skill 的超时上限 | 30000 |
输出校验与失败重试:output 字段应在 Executor 的 validator.py 中被强制执行——先校验结构与必填字段,再校验业务约束(长度、枚举值、是否引用不存在的链接)。校验失败不直接把原始输出返回给用户,而是带错误信息重新调用一次;重试仍失败则走降级路径(返回精简结果或明确告知失败原因)。
最小可运行样例(去掉全部可选字段):
name: pingdescription: 用户说"检查连通性"时返回固定文本trigger: ["检查连通性"]tools: []output: { type: text }
它能跑通 Loader → Planner → Executor 全链路,适合作为新增 Skill 的第一版骨架,再按业务逐步加字段。
真实任务通常需要搜索、文件读写、数据库查询、代码执行或外部 API 调用。建议统一使用如下注册模板:
name: kb_searchdescription: 在企业知识库中检索片段input_schema:type: objectproperties:query: { type: string, maxLength: 200 }top_k: { type: integer, default: 5, maximum: 20 }required: [query]output_schema:type: objectproperties:hits: { type: array, items: { type: object } }total: { type: integer }required: [hits]timeout_ms: 5000retry: { max: 1, backoff: 500ms }permissions:scopes: [kb:read] # 只读;写操作单独申请 kb:writedata_class: internal # internal / confidential / restrictederror_codes:E1001: invalid_argumentE2001: upstream_timeoutE3001: permission_deniedlog_fields: [trace_id, skill_name, tool_name, args_hash, latency_ms, status, error_code]
三条实践要点:args_hash 存参数摘要而非明文,避免敏感内容进日志;error_codes 必须与排查文档一一对应;企业场景遵循最小权限,代码执行、文件写入、外发请求三类工具应默认关闭并走审批。
不同任务对模型要求不同:摘要关注长文本理解,代码任务关注推理与生成质量,工具调用任务关注函数调用稳定性。建议用同一张检查表横向比较,避免凭感觉切换:
| 维度 | 检查问题 | 验证方式 |
|---|---|---|
| 能力 | 长文本/多轮/结构化输出是否达标 | 用 30~50 条真实样本跑离线集 |
| 成本口径 | 按输入+输出 Token 分别计价?是否含重试 | 拉取实际账单核对单价 |
| 延迟 | P50/P95 首 Token 与整体耗时 | 压测记录 P95 |
| 工具调用 | 函数名与参数是否稳定合法 | 统计 tool_call 成功率 |
| 合规与私有化 | 数据是否出域、能否私有部署 | 对照内部数据分级要求 |
需要多家横向比较时,可通过词元所模型服务查看模型能力、价格与统一 API 接入方式,减少重复对接;若涉及行业化能力,再结合精调与知识库检索设计。
上线后记录每次任务的输入、工具调用、模型输出与耗时。灰度建议按 Skill 维度放量:先内部 10% 流量跑两周,指标稳定后再全量。
模型层通常要解决三个问题:
观测指标表:
| 指标 | 计算方式 | 参考阈值 | 异常时首查方向 |
|---|---|---|---|
| Skill 触发率 | 触发次数 / 相关请求数 | ≥ 85% | trigger 描述与用户原话的匹配度 |
| 工具失败率 | 失败调用 / 总调用 | ≤ 3% | 参数 schema、权限 scope、上游超时 |
| 平均耗时 | 端到端 P50 / P95 | P95 < 8s | Planner 步骤数、模型延迟、串行调用 |
| Token 成本 | 单次任务输入+输出 Token × 单价 | 按预算设定 | 上下文长度、重试次数、模型档位 |
| 输出合格率 | 通过校验次数 / 总输出 | ≥ 95% | output 约束强度、validator 规则 |
排查顺序(按此顺序可覆盖多数线上问题):触发率 → 工具失败率 → 输出合格率 → 平均耗时 → Token 成本。先确认流程有没有跑起来,再确认每一步是否成功,最后才优化性能与成本。
| 问题 | 常见原因 | 修复动作 |
|---|---|---|
| Skill 不触发 | trigger 描述抽象,与用户表达不一致 | 补充真实用户原话作为 trigger,补充 description |
| 工具调用失败 | 参数结构不符、scope 缺失、超时过短 | 按 input_schema 校验入参,补 scope,调整 timeout_ms |
| 输出不稳定 | 无格式约束与校验步骤 | 增加 output 约束、validator 校验与有限重试 |
| 上下文过长 | 全量历史消息透传 | 历史摘要化,仅保留任务相关片段与结构化状态 |
| 成本过高 | 全任务使用高性能模型、重复计算 | 按复杂度分层选模型,对幂等查询加缓存 |
CoPaw 的解析最终要回到 Agent Skill 这一核心:它不是单纯调用大模型,而是通过标准化流程把模型、工具与任务编排起来。源码架构上,LLM Adapter、Tool Registry、Skill Loader、Task Planner 与 Executor 共同构成可运行的 Agent 系统,且每一层都能通过目录与文件自行核验。实践上,从任务边界与验收标准出发,依次完成 Skill 编写、工具注册、模型选型到发布观测,用五项指标驱动迭代,比追求一步到位更可靠。