工具、技能与 MCP

本地工具

工作区本地工具应放在 resources/tools/ 下，并通过 tool({...}) 导出。runtime 启动时会发现这些工具，并把它们纳入统一资源注册表。

resources/
  tools/
    write_file.mjs
    code_review.mjs

适合放这里的是：和仓库强绑定的实现逻辑、狭义自动化动作，以及应该跟着 workspace 一起演化的能力。

最小本地工具形状

import { z } from "zod";
import { tool } from "@botbotgo/agent-harness/tools";

export default tool({
  name: "write_file",
  description: "Write a file inside the workspace",
  inputSchema: z.object({
    path: z.string(),
    content: z.string(),
  }),
  async execute({ path, content }) {
    return { ok: true, path, bytes: content.length };
  },
});

技能包（SKILL）

SKILL 应该放在 resources/skills/ 下，并以 SKILL.md 为入口。它不应该只是 prompt 碎片，而应该是可复用、可维护、能随工作区传播的操作知识。

最小技能包结构

resources/
  skills/
    repo-review/
      SKILL.md

# Repo Review

Use this skill when the task is to review one pull request or one repository slice.

- inspect changed files first
- identify concrete findings before summarizing
- prefer code references over broad opinions

如果一段内容只适用于某一次请求，而不是可重复的方法论，它更可能属于当前任务输入，而不是共享技能包。

MCP servers

MCP server 往往比本地 function tool 更重，更共享，更像一个外部能力面。因此它更适合放进 catalog，由多个 agent 按需引用。

实践建议

让 runtime 在启动时统一扫描本地和附加资源，再让 agent 通过白名单选择 tools 与 skills，并在需要时对 MCP 使用施加细粒度覆盖。

Catalog 风格的 MCP server 条目

apiVersion: agent-harness/v1alpha1
kind: McpServers
spec:
  - kind: McpServer
    id: awesome-github-mcp
    name: awesome-mcp/github-mcp
    description: GitHub 工作流与仓库操作的 MCP server
    repositoryUrl: https://github.com/modelcontextprotocol/servers
    transport: stdio
    command: npx
    args:
      - -y
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: CHANGE_ME

catalog 最好同时保留运行时字段和便于维护的元数据。id 是 runtime 真正认的身份；name、description、repositoryUrl 更适合拿来做 catalog 展示和维护。

agent 侧的 spec.mcpServers 推荐使用对象数组，这样每个 agent 都可以单独挑选远程工具，并在不改动共享 catalog 的前提下做 usage 级覆盖。

spec:
  mcpServers:
    - ref: mcp/awesome-github-mcp
      toolFilters:
        - "^issue_"
        - "^pull_request_"
    - ref: mcp/awesome-github-mcp
      name: github-with-token
      tools:
        - echo_text
      env:
        GITHUB_TOKEN: ${GITHUB_TOKEN}

如果能力是本地、仓库强绑定、而且更适合随代码一起版本化，优先从本地工具起步，不要一开始就上 MCP。

像 - awesome-github-mcp 这样的字符串 shorthand 目前仍然兼容，但文档和代码评审里都应该优先使用对象形态。

Agent 如何接这些扩展

runtime 可以全局发现资源，但 agent 仍然应该显式白名单自己要用的 tools、skills 和 MCP servers。这样能力边界更清楚，治理也更容易做。

apiVersion: agent-harness/v1alpha1
kind: Agent
metadata:
  name: orchestra
spec:
  backend: deepagent
  modelRef: model/default
  tools:
    - tool/write-file
  skills:
    - repo-review
  mcpServers:
    - ref: mcp/awesome-github-mcp
      toolFilters:
        - "^issue_"
        - "^pull_request_"

治理与审批

扩展能力越强，治理压力越高。敏感 durable memory 写入和写类 MCP 副作用，默认都应该走 runtime-owned 的审批门槛，而不是依赖每个工具作者自己记得加防线。

常见扩展模式

能力应该放在哪里