Agent Scope Java 2.x 系列【27】Harness：技能（Skill）配置 TaoToken 实战-开发者社区

1. 从一次技能加载失败说起

Agent Scope Java 2.x 的 Harness 里，Skill 是让 Agent 从「会聊天」变成「会干活」的关键。它本质是一个目录包，里面用SKILL.md描述这个技能什么时候用、怎么用，Agent 在推理时先读name和description做匹配，命中后再加载正文执行步骤。听起来很清晰，但真正动手时，很多人卡在同一个地方：技能写好了，Agent 却死活不触发，或者触发了却报文件找不到。

我试过在本地把workspace/skills/code-reviewer/SKILL.md写得漂漂亮亮，结果一进 Docker 沙箱就崩，原因是脚本里写了绝对路径/workspace/scripts/run.sh。也遇到过技能市场配了 Git 仓库，但 Agent 每次推理都去拉一遍，网络一抖整个对话就卡住。这些坑的共同点是：技能配置本身不难，难的是「加载链路」和「调用链路」要同时通。

这篇就聚焦 Harness 中 Skill 的SKILL.md编写与技能市场接入，并且把模型调用通道统一走 TaoToken，这样你只需要维护一套 Key 和 API 地址，不用在多个供应商之间来回切换。适合正在用 Agent Scope Java 2.x 做智能体、想让 Agent 真正执行 shell 脚本和读取参考文档的开发者。下面从环境准备到验证请求，一步步给可复制的配置。

2. TaoToken 前置：统一 Key 与 API 通道

TaoToken 在这里的角色是「模型调用的统一入口」。Harness 里的 Agent 在匹配技能、生成执行计划时都要调模型，如果每个环境各配一套 Key，测试和上线就会很乱。用 TaoToken 的好处是：一个 Key、一个 API 地址，本地、沙箱、远端共享文件系统三种模式都能用同一套配置。

你需要先拿到两样东西：API Key 和 API 地址。API 地址固定是https://taotoken.net/api，注意这个地址不带任何查询参数，直接作为 base URL 使用。Key 在控制台的 API Keys 页面创建，建议按环境分 Key，比如harness-dev、harness-prod，方便排查问题时定位。

创建 Key 的入口在这里：

控制台 API Keys：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api_keys&utm_campaign=rewrite

拿到 Key 之后，不要硬编码进代码。Harness 的配置通常走settings.json或环境变量，推荐用环境变量注入，这样沙箱和本地都能复用。下面这段是settings.json里模型通道的配置片段，把baseUrl指向 TaoToken，apiKey从环境变量读取：

{ "model": { "provider": "openai-compatible", "baseUrl": "https://taotoken.net/api", "apiKey": "${TAOTOKEN_API_KEY}", "modelName": "claude-sonnet-4-5", "timeoutMs": 60000 }, "harness": { "workspace": "./workspace", "dynamicSkills": true } }

这里provider用openai-compatible是因为 TaoToken 的 API 兼容 OpenAI 风格的请求格式，Harness 的模型客户端可以直接对接。modelName按你实际要用的模型填，timeoutMs给到 60 秒，因为技能匹配阶段可能涉及多轮推理，太短容易超时。

如果你更习惯用命令行验证通道是否通，可以先跑一个最小请求：

curl -s https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer $TAOTOKEN_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 16 }'

返回里有choices字段就说明通道没问题。这一步很关键，因为后面技能加载失败时，你要先排除是模型通道的问题还是技能配置的问题。如果这个 curl 都不通，先别急着调 Skill。

3. 可复制配置：SKILL.md 骨架与技能市场接入

3.1 SKILL.md 骨架

一个能被 Agent 正确匹配并执行的 Skill，目录结构是这样的：

code-reviewer/ ├── SKILL.md ├── references/ │ └── style-guide.md └── scripts/ └── run-checks.sh

SKILL.md是必填的核心文件，头部是 YAML 元数据，正文是执行步骤。下面这份骨架可以直接复制改：

--- name: code-reviewer description: 用户需要审查 Java 代码规范、检查命名与异常处理、生成评审意见时启用本技能 version: 1.0.0 --- # 代码评审技能 ## 执行步骤 1. 读取 references/style-guide.md 获取团队规范 2. 对用户提供的代码逐条比对规范 3. 执行 scripts/run-checks.sh 做静态检查 4. 汇总问题并按严重程度排序输出 ## 输出格式 - 问题位置：文件与行号 - 问题类型：命名 / 异常 / 并发 / 性能 - 修复建议：一句话说明

注意description的写法。Agent 第一轮决策只读name和description，不会加载正文。所以描述里要写「用户提问句式」和「触发条件」，而不是只写「代码评审工具」。反面例子是description: 代码评审，Agent 很难判断什么时候该用；正面例子就是上面这种，把「审查 Java 代码规范」「生成评审意见」这些场景词写进去。

正文控制在 2000 tokens 左右，只保留执行步骤。长篇规范丢进references/，可执行脚本丢进scripts/。主文档只写「读哪个文档 → 执行哪个脚本 → 整理输出」这条链路，这样上下文占用小，推理快，也不容易超窗口。

3.2 路径写法：只用相对路径

这是跨文件系统兼容的关键。框架会自动注入根路径变量<files-root>，你写相对路径，它会自动拼接。本地模式拼宿主目录，Docker 沙箱拼容器内/workspace，远端共享文件系统拼 KV 命名空间。

正确写法，相对当前SKILL.md位置：

scripts/run-checks.sh references/style-guide.md

错误写法，沙箱和远端直接失效：

/workspace/scripts/run-checks.sh /root/skill/references/style-guide.md

一旦硬编码绝对路径，技能只能在本机调试跑，一进沙箱就找不到文件。这个坑我踩过，排查了半天才发现是路径问题。

3.3 技能市场接入

技能市场是远程技能仓库的抽象接口，统一叫SkillRepository。Harness 支持 Git、Nacos、MySQL、Classpath 几种来源，通过.skillRepository()注册，后注册的优先级高于先注册的。子 Agent 会自动继承父 Agent 的技能仓库，不用重复配。

Git 仓库方式适合团队共享技能，仓库根目录有skills/就优先读它，否则读根目录。依赖和配置如下：

<dependency> <groupId>io.agentscope</groupId> <artifactId>agentscope-extensions-skill-git-repository</artifactId> <version>${agentscope.version}</version> </dependency>

HarnessAgent.builder() .name("harness-demo") .description("HarnessAgent Demo") .sysPrompt("你是一个 Java 开发 AI 助手") .skillRepository(new GitSkillRepository("https://github.com/xxx/team-skills.git")) .build();

GitSkillRepository默认自动轻量化拉取，只在 HEAD 变更时同步。如果网络延迟高，可以关掉自动同步，手动调repo.sync()：

new GitSkillRepository(gitUrl, false)

Nacos 方式适合平台在线更新技能，支持实时推送变更，实例退出时要close释放订阅：

NacosSkillRepository market = new NacosSkillRepository(aiService, "namespace"); HarnessAgent.builder() .skillRepository(market) .build();

MySQL 方式支持读写分离，writeable=true时允许 Agent 自学习生成的技能回写库：

MysqlSkillRepository registry = MysqlSkillRepository.builder(dataSource) .databaseName("agentscope") .skillsTableName("skills") .createIfNotExist(true) .writeable(true) .build();

Classpath 方式把技能打包进 Jar，随应用一起发布，读resources/skills/：

.skillRepository(new ClasspathSkillRepository("skills"))

多仓库叠加时，后注册的覆盖先注册的：

HarnessAgent.builder() .skillRepository(communityMarket) // 低优先级 .skillRepository(internalRegistry) .skillRepository(teamGitRepo) // 高优先级，同名覆盖前面 .build();

3.4 工作区技能与优先级

除了技能市场，Harness 还会从工作区加载技能。workspace/skills/是项目内团队共用，优先级高于技能市场；workspace/{userId}/skills/是用户私有，优先级最高，同名直接覆盖公共版本。

同名覆盖从低到高是：项目全局目录 → 技能市场 → 工作区公共 → 用户私有。用户隔离是逻辑抽象，本机磁盘、远端 KV、Docker 沙箱三种模式自动适配，你不用改代码。

Builder 常用方法里，disableDynamicSkills()值得注意。默认每次推理前会动态拉取合并所有来源的最新技能，如果是一次性短期任务，或者技能仓库网络延迟高，可以关掉，只在构建时加载一次：

HarnessAgent.builder() .disableDynamicSkills() .build();

4. 验证请求与成功结果

配置写完，怎么确认技能真的加载并调用了？分两步验证。

第一步，验证技能被加载。启动 Agent 后，在日志里搜SkillRepository和技能名，能看到类似loaded skill: code-reviewer的输出，说明仓库拉取成功。如果用的是 Git 仓库，第一次启动会 clone，日志里会有同步记录。

第二步，验证技能被调用。给 Agent 发一个能触发description场景的提问，比如「帮我审查这段 Java 代码的命名规范」。观察日志里是否出现load_skill_through_path，这是 Agent 命中技能后加载正文的动作。如果出现了，说明匹配成功；如果没出现，说明description写得不够场景化，Agent 没认出来。

一个完整的调用链路日志大概长这样：

[Harness] skill matched: code-reviewer [Harness] load_skill_through_path: code-reviewer/SKILL.md [Harness] execute script: scripts/run-checks.sh [Harness] skill result: 3 issues found

看到skill result就说明整条链路通了：匹配 → 加载 → 执行脚本 → 返回结果。这时候你可以把scripts/run-checks.sh换成自己的业务脚本，比如调内部 API、跑数据校验、生成报表。

如果你还想单独验证模型通道，可以用模型对话页面发一条消息，确认 TaoToken 的 Key 和地址配置正确：

模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite

5. 本篇常见错排查

技能不触发，Agent 像没看见一样。九成是description写得太泛。Agent 只读name和description做匹配，描述里没有用户会说的场景词，就匹配不上。改成「用户需要……时启用本技能」这种句式，把业务场景写进去。

报文件找不到，本地能跑沙箱不行。检查SKILL.md和脚本里有没有绝对路径。全部改成相对路径，让框架注入的<files-root>去拼接。这个错误在 Docker 沙箱和远端 KV 模式下必现。

每次推理都卡一下，响应变慢。默认开启动态技能合并，每轮推理前都去拉所有仓库。如果技能仓库网络延迟高，或者是一次性任务，加.disableDynamicSkills()关掉，只在构建时加载一次。

同名技能没覆盖成功。检查注册顺序和目录位置。技能市场里后注册的覆盖先注册的；工作区公共覆盖市场；用户私有覆盖全部。如果用户私有没生效，确认RuntimeContext.userId和目录名是否一致。

Nacos 技能更新后没生效。Nacos 是订阅变更，实例退出要close释放订阅，否则可能拿到旧连接。另外确认 namespace 和 dataId 配置对得上。

MySQL 回写失败。writeable=true才允许回写，同时确认数据库账号有写权限，skillsTableName表存在或createIfNotExist(true)能自动建表。

模型通道超时。先用第 2 节的 curl 验证 TaoToken 通道，确认 Key 和地址没问题。如果 curl 通但 Harness 超时，检查timeoutMs是否太短，技能匹配阶段可能涉及多轮推理，给到 60 秒比较稳。

6. 继续接入与长期编码

技能跑通之后，下一步通常是把它接到长期运行的编码或 Agent 流程里。如果你只是偶尔验证模型输出，用模型对话页面就够了；如果是持续编码、多轮 Agent 任务，建议用 Coding Plan 管理调用配额和通道，避免频繁手动换 Key：

Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite

接入文档里有完整的 API 参数和错误码说明，排障时对照着看更快：

接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite

如果你用的是 Claude Code 这类工具做长期编码，Anthropic 兼容通道的配置方式在下面这个页面：

ClaudeCodeAnthropic：https://taotoken.net/claude-code-anthropic?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite

最后给一个实用建议：技能库不要一次性全开自学习。先把人工编写的技能稳定跑起来，再开enableSkillManageTool(true)让 Agent 起草草稿，草稿默认写用户私有目录；然后加人工审核闸门，审核通过才提升到项目公共或技能市场；最后才开自动清理 curator，定期归档长期没被调用的陈旧技能。顺序反了，脏数据会泛滥，清理成本很高。