code-reviewer

title 技能（Skill） description 四层技能合成、技能市场、自学习闭环 一个 skill 就是一份写好的能力包：一个目录里放一份 SKILL.md （说明用途、给 agent 看的指令），可以再带一些参考文档、脚本或样例。写好后丢给 agent，它会在合适的时候自己用。 Harness 让你从两个地方装 skill： 技能市场 —— Git 仓库、Nacos、MySQL、classpath、自定义后端 工作区 —— workspace/skills/ 下大家共用； <userId>/skills/ 下按用户隔离 两类来源同时生效，不需要二选一。除此之外，还可以打开 自学习闭环 ：agent 自己起草 skill → 审核 → 后台周期性整理。 一个 skill 目录长这样： code-reviewer/ ├── SKILL.md # 必需，YAML frontmatter（name + description）+ 给 agent 看的指令 ├── references/ # 可选，长篇参考资料，agent 按需读取 │ └── style-guide.md └── scripts/ # 可选，agent 可以通过 shell 调用的脚本 └── run-checks.sh SKILL.md 写法： --- name: code-reviewer description: 当用户需要代码评审、风格反馈或 PR 审核时使用。 --- # Code Reviewer 步骤： 1. 读 `references/style-guide.md` 获取项目规范 2. 跑 `scripts/run-checks.sh <目标路径>` ，把结果汇总给用户 一个例子 把团队的 skill 仓库接进来，agent 立刻就能用： HarnessAgent agent = HarnessAgent.builder() .name( "assistant" ) .model(model) .workspace(workspace) .skillRepository( new GitSkillRepository ( "https://github.com/your-org/team-skills.git" )) .build(); 后续推理时 agent 看得到这个仓库里的 skill，需要哪个就调 load_skill_through_path 加载详情。 接技能市场 skillRepository(...) 是统一入口，传什么后端都可以。 Git < dependency > < groupId > io.agentscope </ groupId > < artifactId > agentscope-extensions-skill-git-repository </ artifactId > < version > ${agentscope.version} </ version > </ dependency > .skillRepository( new GitSkillRepository ( "https://github.com/your-org/team-skills.git" )) 默认每次读取做轻量化的远端检查，HEAD 变了才 pull。仓库根下如果有 skills/ 子目录会优先读它，否则读根目录。想自己控制同步节奏： new GitSkillRepository(url, false) ，然后手动 repo.sync() 。 Nacos < dependency > < groupId > io.agentscope </ groupId > < artifactId > agentscope-extensions-nacos-skill </ artifactId > < version > ${agentscope.version} </ version > </ dependency > NacosSkillRepository market = new NacosSkillRepository (aiService, "namespace" ); HarnessAgent.builder() .skillRepository(market) .build(); 适合需要在线下发、变更订阅的场景。 market 是 AutoCloseable ，应用退出时关掉以释放订阅。 MySQL MysqlSkillRepository registry = MysqlSkillRepository.builder(dataSource) .databaseName( "agentscope" ) .skillsTableName( "skills" ) .createIfNotExist( true ) .writeable( true ) .build(); HarnessAgent.builder() .skillRepository(registry) .build(); 平台侧统一管理 skill 时常用。 writeable(true) 后可以从 agent 侧写回；只读分发就传 false 。 Classpath 把 skill 跟 JAR 一起发： src/main/resources/skills/ └── code-reviewer/ └── SKILL.md .skillRepository( new ClasspathSkillRepository ( "skills" )) 兼容标准 JAR 和 Spring Boot Fat JAR。 接多个 skillRepository(...) 可以重复调用；后注册的优先级更高： HarnessAgent.builder() .skillRepository(communityMarket) .skillRepository(internalRegistry) .skillRepository(teamGitRepo) .build(); 把 skill 放到工作区 工作区里的 skill 不用任何注册，把目录放好就生效。 大家共用 workspace/skills/ └── code-reviewer/ ├── SKILL.md ├── references/ │ └── style-guide.md └── scripts/ └── run-checks.sh 适合放项目特有的规范、内部约定。 单个用户用 如果想给某个用户单独装一个 skill，或给他覆盖一个共用版本，放到他 userId 命名的子目录下： workspace/ ├── skills/code-reviewer/SKILL.md ← 共用版 └── alice/ └── skills/ └── code-reviewer/ └── SKILL.md ← 只对 alice 生效，覆盖共用版 前提是调用时 RuntimeContext.userId 传了"alice"。 这里的 workspace/<userId>/skills/ 是一个 逻辑路径 ，不等于"一定是本机磁盘上的目录"。技能文件的读写统一走 AbstractFilesystem 抽象，实际落在哪儿由你配的 文件系统模式 决定，所以"按用户隔离 skill"这个能力跟具体存储后端解耦： 本机 + shell —— 就是宿主磁盘上的 workspace/alice/skills/... ； 共享存储（remote filesystem） —— skills/ 前缀被路由到 KV，用户隔离体现为命名空间键 agents/<agentId>/users/alice/skills/... ，多副本之间一致；管理台改完下一轮推理即可生效； 沙箱（sandbox filesystem） —— 宿主侧的用户目录在沙箱启动时通过 workspace projection 注入容器的 /workspace ，agent 在沙箱里读到的是同一份。 不管跑在哪种模式， <userId>/skills/ 都按同样的优先级覆盖共用版。各模式下的隔离键、物理表现以及 userId 的作用，详见 文件系统 。 同名冲突谁说了算 四个来源都可能给出同名 skill。优先级从低到高： 优先级 来源 怎么配 1（最低） 项目全局目录 projectGlobalSkillsDir(Path) ，如 ~/.agentscope/skills/ 2 市场 skillRepository(...) ，后注册的覆盖先注册的 3 工作区共用 workspace/skills/ 4（最高） 用户隔离 <userId>/skills/ 下层独有的 skill 仍然保留，只在重名时被上层覆盖。 举例：团队 Git 上有通用 code-reviewer ，项目 workspace/skills/code-reviewer/ 写了项目专属版本，那 agent 看到的就是项目版；Alice 又在自己目录覆盖了一份，那 Alice 调用时拿到的是她自己的版本，其他用户还是项目版。 常用 Builder 选项 方法 说明 skillRepository(repo) 追加一个市场；可重复调用 skillRepositories(list) 一次性替换所有市场 projectGlobalSkillsDir(path) 启用项目全局目录；目录不存在则跳过 disableDynamicSkills() 关掉"每次推理前重新合并"，改成 build 时合并一次 子 agent 自动继承父的市场列表和项目全局目录，不用重复配。 什么时候用 disableDynamicSkills() ：单次任务，跑完就退出；或市场后端慢、不想每轮拉。平时不用动这个开关。 自学习闭环（可选） Harness 拼了一套"让 agent 自己起草 / 沉淀 / 整理 skill"的闭环。各阶段独立可开，按需启用： 第一步：让 agent 能自己写 skill HarnessAgent.builder() ... .enableSkillManageTool(SkillManageConfig.defaults()) .build(); 启用后 agent 获得两个工具： propose_skill —— 把新 skill 写成草稿到 skills/_drafts/<name>/ ，等审核 skill_manage —— 编辑已有 skill（创建 / 修改 / 添加附属文件 / 删除） 如果不想要"草稿 → 审核"两步流程，让 agent 写完直接生效： .enableSkillManageTool(true) （ autoPromote=true ）。生产场景不建议。 同时 agent 每次调 load_skill_through_path / read_skill 时，框架自动记一笔使用计数，存到 skills/.usage.json ——为后面的清理、灰度发布提供数据。 第二步：加审核闸门 + 可见性过滤 .enableSkillPromotionGate( new LocalApprovalGate (LocalApprovalGate.defaultPrompter()), // 谁来批 new CompositeFilter (List.of( // 怎么暴露 new EnvironmentFilter ( "prod" , skillUsageStore), new CanaryFilter ( 0.10 , skillUsageStore) ))) .environment( "prod" ) 闸门 —— 草稿要变正式 skill 必须经过它。内置三种：直接拒绝（默认）、本地人工确认（stdin 等）、推消息后等。 可见性过滤 —— 决定 agent 在推理时能看到哪些"agent 自己创建"的 skill。可按部署环境、灰度比例、白名单组合。 第三步：后台周期性整理 .enableSkillCurator(SkillCuratorConfig.builder() .intervalHours( 7 * 24 ) // 一周跑一次 .staleAfterDays( 30 ) .archiveAfterDays( 90 ) .build()) 后台会按节流闸门跑：超过 30 天没用的 skill 标为 stale，超过 90 天直接归档到 skills/.archive/ 。可选叠加一个 LLM "伞合并"扫描（默认只 dry-run，输出报告，不实际改）。 程序化触发 业务层可以用： List<SkillAuditLog.Entry> entries = agent.queryAudit(LocalDate.now(), e -> true ); agent.runCuratorOnce() // 立刻跑一次整理（绕过节流） .subscribe(report -> System.out.println(report)); agent.promoteSkill( "notes-taker" , "alice" ) // 手动晋升一份草稿 .subscribe(result -> System.out.println(result)); Agent 是怎么读取和执行 skill 的 每轮推理时，agent 会在 system prompt 里看到一个 <available_skills> 块，列出当前可见的所有 skill： < available_skills > < skill > < name > code-reviewer </ name > < description > 当用户需要代码评审、风格反馈或 PR 审核时使用。 </ description > < skill-id > code-reviewer_workspace-namespaced </ skill-id > < files-root > /workspace/skills/code-reviewer </ files-root > </ skill > ... </ available_skills > 每个条目只携带最少的元数据，方便 agent 判断要不要加载详情。 <files-root> （如果有）是 agent 通过 shell 执行该 skill 脚本时使用的绝对路径，详见下面。 读 SKILL.md 和资源文件 加载某个 skill 时 agent 会调用内置工具 load_skill_through_path ： load_skill_through_path(skillId, path="SKILL.md") 返回 markdown 正文 load_skill_through_path(skillId, path="references/style-guide.md") 返回该 skill 目录下的任意文件 具体怎么取文件，取决于 skill 来自哪里： Skill 来源 path 解析方式 项目全局目录（Layer 1） 注册时预载到内存 市场——Git / MySQL / Nacos / classpath（Layer 2） 由后端预载到内存 workspace/skills/ 共用（Layer 3） 注册时预载到内存 <userId>/skills/ 用户隔离（Layer 4） SKILL.md 预载；其它文件按需通过 AbstractFilesystem 读取（自动遵循 per-user namespace + sandbox 路由） agent 感知不到这种差异， load_skill_through_path 调起来都一样。底层查找顺序是"内存命中 → 文件系统读取 → 找不到时返回所有真正可用的路径列表"，所以传错 path 也只会拿到清单而不是死路。 <files-root> 和 shell 执行 当一个 skill 自带脚本（例如 scripts/run-checks.sh ），agent 需要绝对路径才能通过 execute_shell_command 调用它。这个绝对路径就是 skill 条目里的 <files-root> 。它怎么算出来取决于文件系统模式： 文件系统模式（是否有 shell） 工作区 skill 的 <files-root> 市场 skill 的 <files-root> Sandbox /workspace/skills/<name> /workspace/.skills-cache/<source>/<name> Local-with-shell <wsRoot>/skills/<name> <wsRoot>/.skills-cache/<source>/<name> Local 不带 shell / Composite （不渲染——没注册 shell 工具） （不渲染） 所以 agent 发出来的 shell 命令永远是 execute_shell_command("python3 <files-root>/scripts/foo.py") ——不用猜路径，不用记每种来源对应哪个前缀。 市场 skill 文件实际落在哪儿 市场 skill 的资源最初只在内存里。要让 shell 能跑它们，harness 在每轮推理前把它们物化到 <wsRoot>/.skills-cache/<source>/<name>/ ： 文件级 SHA-256 去重，只重写变化过的文件 已经下架的 skill（或被从 builder 中移除的整个仓库）留下的孤儿目录，会在同一轮顺手清掉 Sandbox 模式下， .skills-cache 默认包含在 workspace projection roots 里，沙箱启动时（以及内容变化时）会跟 workspace/skills/ 一起 hydrate 进沙箱 工作区 skill（Layer 3 / Layer 4）不需要 stage——它们本来就在工作区目录里。 如果两个仓库返回了相同的 getSource() ，第二个会自动加后缀（ <source>_2 、 <source>_3 …），并打 warning log，所以路径和 skill-id 不会撞。 在沙箱里运行 skill 沙箱模式 下，文件操作和 shell 都在隔离容器里执行，宿主完全不受影响。这就带来一个问题：skill 的脚本（ scripts/run-checks.sh 、 scripts/foo.py 之类）写在宿主侧，agent 却要在容器里把它们跑起来。harness 用"物化 → 投影 → 容器内执行"三步把这件事做成透明的，下面拆开讲。 哪些 skill 会进沙箱 容器里能跑的 skill 分两类，进沙箱前的落点不同： 来源 进沙箱前住哪儿 沙箱里的路径 工作区 skill（Layer 3 workspace/skills/ 、Layer 4 <userId>/skills/ ） 本来就在工作区目录树里 /workspace/skills/<name> 市场 skill（Layer 1 项目全局、Layer 2 Git / MySQL / Nacos / classpath） 资源最初只在内存里 /workspace/.skills-cache/<source>/<name> 第一步：把市场 skill 物化到宿主 市场 skill 的资源拿到时只是内存里的字节，shell 没法直接执行。每轮推理前， MarketplaceStager 把它们写到宿主的 <wsRoot>/.skills-cache/<source>/<name>/ ： 文件级 SHA-256 去重 —— 只重写变化过的文件，没变的跳过； 孤儿清理 —— 已下架的 skill、或从 builder 里移除的整个仓库，留下的目录在同一轮顺手删掉； 恢复执行位 —— 资源在入库时被转成字符串，POSIX 权限丢了，所以 stager 用启发式补回 +x ：文件开头是 shebang（ #! ），或后缀是已知脚本类型（ .sh / .bash / .py / .rb / .pl / .js / .mjs ），就加上可执行位（按 chmod +x 的语义，只给本来有读权限的位加执行位）。纯静态资产（ .json / .md / .txt ）保持 644。 工作区 skill（Layer 3 / Layer 4）跳过这一步——它们本来就在工作区目录里。 第二步：把工作区投影进沙箱（Workspace Projection） 沙箱 start() 时，harness 把宿主工作区里的"静态资产"打成 tar，hydrate 进容器的 /workspace 。默认投影的根（ workspaceProjectionRoots ）正好覆盖 skill 需要的两个目录： AGENTS.md skills/ subagents/ knowledge/ .skills-cache/ 所以 workspace/skills/ （含 <userId>/skills/ ）和上一步物化出来的 .skills-cache/ 会一起进沙箱。投影对所有被包含的文件按内容算一个整体 SHA-256，跟上次一样就跳过 hydrate，所以反复 call() 不会重复传一样的文件；只有内容变了才重新注入。 可调项（在 DockerFilesystemSpec / KubernetesFilesystemSpec 等沙箱 spec 上）： 方法 作用 workspaceProjectionRoots(List) 自定义投影哪些根目录（默认含 skills 、 .skills-cache ） workspaceProjectionEnabled(false) 完全关掉投影——关了之后沙箱里就没有 skill 文件，脚本自然跑不了 第三步：在容器里执行脚本 <available_skills> 块里每个 skill 的 <files-root> 在沙箱模式下用 容器内 前缀渲染： skill 类型 <files-root>