wuyang/zk-data-agent

Fork 0

Files

T

wuyang6 3054b3bc6b docs: add technical architecture guide

2026-05-18 19:28:02 +08:00

4.9 KiB

Raw Blame History

04. Skill 体系和能力包约定

1. Skill 的定位

Skill 是经验层。它不是单纯 prompt，也不是单纯脚本。

一个 Skill 应该回答：

什么场景触发。
输入材料是什么。
Agent 应该按什么流程做。
哪些地方必须让用户 review。
应该调用哪些工具或脚本。
产物应该写到哪里。
哪些做法是禁止的。

稳定可执行逻辑不应该长期写在 Skill 文本里，而应该进入：

skills/<skill-name>/scripts/

或者平台级工具。

2. Skill loader 实现

关键文件：

src/bundled_skills.py

项目级 Skill 目录：

skills/<skill-name>/SKILL.md

核心数据结构：

src/bundled_skills.py:28 BundledSkill

字段：

name
description
when_to_use
aliases
allowed_tools
user_invocable
source
path
get_prompt

3. SKILL.md 解析

解析逻辑：

src/bundled_skills.py:147 _parse_front_matter
src/bundled_skills.py:176 _load_directory_skill

SKILL.md 必须有 frontmatter：

---
name: product-data
description: 从产品/标签定义、手写边界规则或示例 query 中提取标签边界...
when_to_use: 当用户提供产品定义、标签规则...
aliases: definition-data, label-data
allowed_tools: read_file, write_file, python_exec
---

解析后：

frontmatter 进入 BundledSkill 元数据。
body 作为真正的 Skill prompt。
如果调用 Skill 时带 args，会追加到 ## Invocation Arguments。

对应实现：

src/bundled_skills.py:138 _directory_skill_prompt

4. Skill 发现顺序

项目 Skill 发现入口：

src/bundled_skills.py:199 load_directory_skills
src/bundled_skills.py:215 load_project_skills

系统提示词中可见 Skill 列表由：

src/bundled_skills.py:270 format_skills_for_system_prompt

生成。

Web 后端会按当前账号和 session 配置计算启用 Skill：

backend/api/server.py:691 enabled_skill_names
backend/api/server.py:706 set_skill_enabled
backend/api/server.py:738 set_all_skills_enabled

这意味着：

Skill 可以存在于项目中，但不一定对某个 session 启用。
启用状态影响系统提示词里的 Skill 列表。
被禁用的 Skill 不应该被模型主动选择。

5. Skill 工具

Skill 本身也是一个工具：

src/agent_tools.py:1012 AgentTool(name='Skill')

模型调用：

{
  "skill": "product-data",
  "args": "用户原始需求或显式参数"
}

执行后，Skill body 会被加入对话，让模型按 Skill 中的流程继续做任务。

6. Skill 和 Agent Loop 的关系

Skill 不会替代 Agent loop，而是改变 Agent loop 的下一步决策依据。

典型模式：

用户提出任务
  -> 模型从 Skill 列表中选择某个 Skill
  -> 调用 Skill 工具
  -> Skill.md 正文进入上下文
  -> 模型按 Skill 指令调用 read_file/python_exec/data_agent 等工具
  -> 工具结果进入上下文
  -> 模型继续按 Skill 流程推进

因此 Skill 的好坏直接影响：

模型能否召回正确能力。
是否会过早执行。
是否能在 review 门禁停下来。
是否能使用正确工具而不是手写不稳定逻辑。

7. 推荐 Skill 目录结构

skills/<skill-name>/
  SKILL.md
  README.md
  knowledge/
  scripts/
  examples/
  schemas/
  tools.yaml
  requirements.txt

各部分职责：

SKILL.md
  运行时入口，写流程、门禁、工具调用方式和禁止事项。

README.md
  给维护者看的说明，不一定进入模型上下文。

knowledge/
  业务知识、标签规则、字段说明、边界案例。

scripts/
  确定性脚本，优先通过 python_exec.script_path 执行。

examples/
  示例输入输出，用于回归和讲解。

schemas/
  JSON schema 或字段约定。

tools.yaml
  描述 portable scripts 如何注册为工具，便于迁移到其他 Agent。

requirements.txt
  Skill 脚本的 Python 依赖。

8. Skill 更新

Web 后端提供 Skill 更新能力：

backend/api/server.py:765 sync_skills_from_git

核心行为：

1. 检查当前目录是否是 git 仓库。
2. 检查 tracked 文件是否干净。
3. git fetch origin。
4. git pull --ff-only origin 当前分支。
5. 清理当前账号 agent cache。
6. 重新读取 get_bundled_skills。

这让新增或修改 Skill 后，不一定需要重启服务才能让 Skill 列表刷新。

9. Skill 设计边界

适合写在 Skill：

工作流。
何时提问。
何时 review。
哪些工具优先。
输出位置约定。
常见失败经验。

不适合长期写在 Skill：

大段可检索知识。
复杂代码。
格式转换。
查询外部系统的具体实现。
需要校验的稳定数据结构。

这些应该分别放到：

knowledge/
scripts/
schemas/
platform tools

4.9 KiB Raw Blame History Unescape Escape