Module Specification for Capability & Integration Layer

# 能力层与集成层模块规格

本文是新的统合版能力层与集成层规格，统一描述 `anyclaw` 当前能力运行时与外部集成运行时的职责边界。

本文参考：

- `文档/路由层模块规格.md`
- `文档/anyclaw能力层与集成层模块规格.md`
- `文档/openclaw能力层与集成层模块规格.md`

但模块合同以 `anyclaw` 当前真实代码为主，只借用 `openclaw` 的“薄合同、清边界”写法，不直接照搬 `openclaw` 的实现分层。

本文默认：

- 输入层、网关层、路由层已经把一条请求交给执行侧
- 路由层只负责“归谁处理”
- 本文负责“系统有哪些能力、这些能力如何装配、如何被调用、如何接入外部能力”

## 1. 范围

本文覆盖：

- model/provider 选型与调用适配
- tool registry 与内建能力装配
- skill 装载与 prompt 增强
- plugin 能力装配与运行时暴露
- MCP 客户端桥接与 MCP 服务端暴露
- harness / extension 目录型集成
- cron 自动化调度与 agent 执行桥

本文不覆盖：

- 输入层协议接入
- 网关层认证、授权、限流、风控
- 路由层的 agent/session/delivery 归属
- dispatch 对外消息投递

## 2. 三条主链路

### 2.1 Runtime 装配链

```go
BootstrapOptions
  -> runtime.Bootstrap(...)
  -> SkillsManager.Load(...)
  -> tools.NewRegistry()
  -> tools.RegisterBuiltins(...)
  -> SkillsManager.RegisterTools(...)
  -> plugin.NewRegistry(...)
  -> plugin.RegisterToolPlugins(...)
  -> plugin.RegisterAppPlugins(...)
  -> llm.NewClientWrapper(...)
  -> agent.New(...)
  -> App
```

它回答：

- 当前运行时有哪些 skills
- 当前运行时有哪些 tools
- 当前有哪些 plugin 被装入
- 当前默认使用哪个 provider/model
- agent 最终拿到的能力快照是什么

### 2.2 能力调用链

```go
AgentStep
  -> ModelRouteRequest
  -> ModelRouteDecision
  -> ModelCallRequest
  -> LLM Response / ToolCalls
  -> CapabilityCallRequest
  -> Tool Registry / Skill / Plugin / MCP Tool
  -> CapabilityCallResult
```

它回答：

- 这一步该用哪个 provider/model
- 这一轮暴露给 LLM 的工具集合是什么
- 某个工具调用最终落到哪个运行时能力
- 返回给 agent 的统一结果是什么

### 2.3 集成与自动化链

```go
MCPServerConfig
  -> mcp.Registry
  -> mcp.Client
  -> BridgeToToolRegistry(...)
  -> bridged tools
```

```go
CronTask
  -> Scheduler
  -> AgentExecutor
  -> Agent / Orchestrator
  -> TaskRun
```

```go
Harness / Extension Manifest
  -> CapabilityRegistry / ExtensionRegistry
  -> catalog / intent / integration entry
```

它回答：

- 外部 MCP 能力如何变成系统内部工具
- 定时任务如何进入 agent 执行链
- 本地 harness / extension 能力如何被发现与暴露

## 3. 能力层与集成层职责边界

### 3.1 能力层必须负责的事

- 把 provider/model 选择收敛成统一 `Decision`
- 把工具、skill、plugin、MCP tool 收敛成统一能力目录
- 把 system prompt 与 skill prompt 装配给 agent
- 把外部能力桥接成系统内部可调用对象
- 把自动化任务统一交给 agent 或 orchestrator 执行

### 3.2 集成层必须负责的事

- 发现外部能力清单
- 建立到外部能力的连接
- 把外部能力映射成内部运行时入口
- 不绕过已有的 tool policy、runtime policy、agent 执行链

### 3.3 一个必须写死的边界

以下几组对象不是一回事：

- `ModelRouteDecision`：这轮该选哪个 provider/model
- `llm.Response`：真正模型返回的内容与 tool calls

- `Skill`：能力定义、prompt、命令和 entrypoint
- `skill_* tool`：把 `Skill` 暴露给 LLM 的调用壳

- `Plugin Manifest / CapabilityIndex`：插件能力目录
- `plugin tool runner / app runner`：插件真实执行入口

- `MCP Client`：到外部 server 的连接
- `mcp__server__tool`：桥接进本地 `tools.Registry` 之后的工具名

- `Extension / Harness Registry`：本地目录型能力发现
- 输入层 channel adapter：接外部消息的入口

## 4. 共享对象合同

### 4.1 运行时能力对象

```go
type RuntimeScope struct {
	// WorkingDir 是当前 agent 实际工作的目录。
	WorkingDir string

	// PermissionLevel 是工具执行权限级别。
	PermissionLevel string

	// AgentName 是当前运行时主 agent 名称。
	AgentName string
}

type ModelRef struct {
	// Provider 是 provider 逻辑名。
	Provider string

	// Model 是 provider 下的模型名。
	Model string
}

type ModelRouteRequest struct {
	// Input 是当前需要做 provider/model 选型的文本。
	Input string

	// DefaultModel 是配置里的默认模型。
	DefaultModel ModelRef
}

type ModelRouteDecision struct {
	// Provider 是最终选择的 provider。
	Provider string

	// Model 是最终选择的模型。
	Model string

	// Reason 是此次选型原因，例如 default / fast / reasoning。
	Reason string
}

type CapabilityDescriptor struct {
	// Name 是对外暴露的稳定能力名。
	Name string

	// Kind 是能力种类，例如 builtin_tool / skill_tool / plugin_tool / mcp_tool。
	Kind string

	// Source 是能力来源，例如 builtin / skill / plugin / mcp / clihub。
	Source string

	// InputSchema 是给 LLM 或上游调用方暴露的参数合同。
	InputSchema map[string]any
}

type CapabilityCallRequest struct {
	// Name 是要调用的能力名。
	Name string

	// Input 是能力调用输入。
	Input map[string]any
}

type CapabilityCallResult struct {
	// Output 是能力输出文本。
	Output string

	// ErrorText 是失败时的错误摘要。
	ErrorText string
}
```

### 4.2 集成对象

```go
type PluginBinding struct {
	// Name 是插件名。
	Name string

	// Kinds 是插件声明的能力种类。
	Kinds []string

	// Entrypoint 是插件执行入口。
	Entrypoint string

	// Enabled 表示插件是否已启用。
	Enabled bool
}

type MCPServerBinding struct {
	// Name 是 MCP server 名。
	Name string

	// Command 是启动命令。
	Command string

	// Args 是启动参数。
	Args []string

	// Enabled 表示是否启用。
	Enabled bool
}

type HarnessCapabilityRef struct {
	// Harness 是能力所属 harness。
	Harness string

	// Command 是能力命令名。
	Command string

	// Action 是能力动作语义。
	Action string

	// SourcePath 是来源路径。
	SourcePath string
}

type AutomationTaskRef struct {
	// TaskID 是定时任务 ID。
	TaskID string

	// Command 是交给 agent 的任务文本。
	Command string

	// Agent 是可选目标 agent。
	Agent string

	// Schedule 是 cron 表达式。
	Schedule string
}
```

设计约束：

- 共享对象只保留跨模块真正反复出现的最小字段
- 各模块若还需要更宽字段，应留在模块内部，不继续外扩成主合同
- `CapabilityDescriptor` 只描述“有什么能力”，不描述执行结果

## 5. M1: Model Runtime / Provider Adapter / 模型运行时与 Provider 适配模块

### 5.1 职责

- 根据输入文本和配置产出 `ModelRouteDecision`
- 把统一消息结构翻译成 provider 协议请求
- 把 provider 私有响应收敛成统一 `llm.Response`
- 提供 failover、fallback、model discovery 这类 provider 级能力

### 5.2 当前实现位置

- `anyclaw/pkg/modelrouting/routing.go`
- `anyclaw/pkg/llm/llm.go`
- `anyclaw/pkg/providers/client.go`
- `anyclaw/pkg/providers/failover.go`

### 5.3 输入结构体

```go
type ModelResolveInput struct {
	// Request 是本轮模型选型输入。
	Request ModelRouteRequest
}

type ModelCallInput struct {
	// Config 是 provider/model 调用配置。
	Config llm.Config

	// Messages 是统一消息序列。
	Messages []llm.Message

	// Tools 是暴露给模型的工具定义。
	Tools []llm.ToolDefinition

	// Stream 表示是否走流式输出。
	Stream bool
}
```

### 5.4 输出结构体

```go
type ModelResolveOutput struct {
	// Decision 是本轮选出的 provider/model。
	Decision ModelRouteDecision
}

type ModelCallOutput struct {
	// Response 是 provider 响应统一化后的结果。
	Response llm.Response

	// ProviderName 是本次真正执行的 provider。
	ProviderName string
}
```

### 5.5 公开函数

```go
// DecideLLM 根据配置和输入文本决定本轮 provider/model。
// 当前由上层执行链在真正发起模型调用前使用。
func DecideLLM(cfg config.LLMConfig, input string) Decision

// NormalizeProviderName 把 provider 别名归一化成内部逻辑名。
// 当前由 provider client 初始化路径使用。
func NormalizeProviderName(provider string) string

// ProviderRequiresAPIKey 返回某个 provider 是否要求 API key。
// 当前由 llm.NewClient(...) 初始化时使用。
func ProviderRequiresAPIKey(provider string) bool

// NewClient 创建统一的 provider client。
// 当前由 llm.NewClientWrapper(...) 和独立测试路径调用。
func NewClient(cfg Config) (Client, error)

// NewClientWrapper 创建可切 provider/model 的上层包装器。
// 当前由 runtime.Bootstrap(...) 在 LLM phase 调用。
func NewClientWrapper(cfg Config) (*ClientWrapper, error)

// NewFailoverClient 创建带 fallback 的 provider client。
// 当前用于 provider 级降级执行路径。
func NewFailoverClient(primary Client, config FailoverConfig) *FailoverClient

// RegisterProvider 把 provider 接入模型发现器。
// 当前用于 model discovery 管理路径。
func (md *ModelDiscovery) RegisterProvider(provider Provider)

// DiscoverModels 主动发现可用模型清单。
// 当前用于 provider/model 发现路径。
func (md *ModelDiscovery) DiscoverModels(ctx context.Context) error
```

### 5.6 设计约束

- `ModelRouteDecision` 只回答“该选哪个 provider/model”，不回答“有没有工具、有没有 skill”
- provider 私有协议转换必须留在 M1 内部，不能把 OpenAI/Anthropic 私有响应泄漏给上层主合同
- failover 属于 provider 运行时能力，不属于工具目录或插件目录
- M1 不负责 tool policy、skill prompt、plugin visibility

## 6. M2: Tool Registry / Builtin Capability Assembly / 工具注册与内建能力装配模块

### 6.1 职责

- 提供统一 `tools.Registry`
- 注册内建 file/web/memory/session/desktop/clihub/claw bridge 工具
- 暴露统一的 tool schema、tool list、tool call 入口
- 为 skill、plugin、MCP tool 提供统一挂载点

### 6.2 当前实现位置

- `anyclaw/pkg/tools/registry.go`
- `anyclaw/pkg/tools/tools.go`
- `anyclaw/pkg/tools/builtins.go`
- `anyclaw/pkg/tools/clihub.go`

### 6.3 输入结构体

```go
type ToolAssemblyInput struct {
	// Scope 是当前运行时上下文。
	Scope RuntimeScope

	// Options 是内建工具装配选项。
	Options tools.BuiltinOptions
}

type ToolCallInput struct {
	// Request 是统一能力调用请求。
	Request CapabilityCallRequest
}
```

### 6.4 输出结构体

```go
type ToolAssemblyOutput struct {
	// Registry 是本轮装配完成后的工具注册表。
	Registry tools.Registry

	// Tools 是当前可暴露能力的目录快照。
	Tools []CapabilityDescriptor
}

type ToolCallOutput struct {
	// Result 是工具执行结果。
	Result CapabilityCallResult
}
```

### 6.5 公开函数

```go
// NewRegistry 创建统一工具注册表。
// 当前由 runtime.Bootstrap(...) 在 Tools phase 调用。
func NewRegistry() *Registry

// RegisterBuiltins 把内建工具注册进工具表。
// 当前由 runtime.Bootstrap(...) 在 skill 装配之后、plugin 装配之前调用。
func RegisterBuiltins(r *Registry, opts BuiltinOptions)

// RegisterTool 注册一个简单工具。
// 当前由 skills、plugins、MCP bridge 等上层装配路径调用。
func (r *Registry) RegisterTool(name string, desc string, schema map[string]any, handler ToolFunc)

// Register 注册一个完整 Tool 对象。
// 当前由 clihub 等需要补 category/access/timeout 的路径调用。
func (r *Registry) Register(t *Tool)

// Get 返回某个工具定义。
// 当前由 agent、测试和部分运行时检查路径调用。
func (r *Registry) Get(name string) (*Tool, bool)

// Call 调用一个工具。
// 当前由 agent tool-call 执行链消费。
func (r *Registry) Call(ctx context.Context, name string, input map[string]any) (string, error)

// CallWithRetry 对可重试工具执行带退避重试的调用。
// 当前由通用工具调用路径按需使用。
func (r *Registry) CallWithRetry(ctx context.Context, name string, input map[string]any, maxRetries int) (string, error)

// GetToolDefinitions 产出给 LLM 使用的工具定义列表。
// 当前由 agent 组装模型调用时使用。
func (r *Registry) GetToolDefinitions() []map[string]any

// List 返回工具目录的轻量快照。
// 当前由调试、管理与测试路径使用。
func (r *Registry) List() []ToolInfo
```

### 6.6 设计约束

- M2 是统一工具目录，不直接关心某个工具来自 builtin、skill、plugin 还是 MCP
- skill tool、plugin tool、MCP tool 都必须挂进同一个 `Registry`
- M2 负责“注册与调用入口”，不负责 skill 发现、plugin manifest 解析、MCP 连接建立
- CLIHub 的工具外壳属于 M2，但 CLIHub 目录发现与意图解析语义属于 M6

## 7. M3: Skill Loader / Prompt Augmentation / Skill 装载与 Prompt 增强模块

### 7.1 职责

- 装载 builtin skill 与本地 skill 目录
- 提供 system prompt 快照
- 把 skill 暴露成 `skill_*` 工具
- 在 entrypoint 模式下执行 skill

### 7.2 当前实现位置

- `anyclaw/pkg/skills/skills.go`
- `anyclaw/pkg/skills/builtins.go`

### 7.3 输入结构体

```go
type SkillLoadInput struct {
	// Dir 是技能目录。
	Dir string

	// EnabledNames 是显式允许的 skill 名列表。
	EnabledNames []string
}

type SkillExecuteInput struct {
	// Name 是目标 skill 名。
	Name string

	// Input 是 skill 调用参数。
	Input map[string]any

	// Options 是执行权限与超时设置。
	Options skills.ExecutionOptions
}
```

### 7.4 输出结构体

```go
type SkillLoadOutput struct {
	// Skills 是加载后的技能列表。
	Skills []skills.Skill

	// SystemPrompts 是要并入 agent system prompt 的文本片段。
	SystemPrompts []string

	// Tools 是 skill 暴露出来的 tool 壳定义。
	Tools []CapabilityDescriptor
}

type SkillExecuteOutput struct {
	// Result 是 skill 执行结果。
	Result CapabilityCallResult
}
```

### 7.5 公开函数

```go
// NewSkillsManager 创建技能管理器。
// 当前由 runtime.Bootstrap(...) 在 Skills phase 调用。
func NewSkillsManager(dir string) *SkillsManager

// Load 装载 builtin skill 和本地目录 skill。
// 当前由 runtime.Bootstrap(...) 调用。
func (s *SkillsManager) Load() error

// FilterEnabled 根据配置筛出启用 skill。
// 当前由 runtime.Bootstrap(...) 在读取 agent skill 配置后调用。
func (s *SkillsManager) FilterEnabled(names []string) *SkillsManager

// RegisterTools 把 skill 暴露成 skill_* 工具。
// 当前由 runtime.Bootstrap(...) 在 Tools phase 调用。
func (s *SkillsManager) RegisterTools(registry *tools.Registry, opts ExecutionOptions)

// Execute 执行指定 skill。
// 当前由 skill_* tool handler 调用。
func (s *SkillsManager) Execute(ctx context.Context, name string, input map[string]any, opts ExecutionOptions) (string, error)

// GetSystemPrompts 返回所有 system prompt 片段。
// 当前由 agent 初始化与 prompt 组装路径使用。
func (s *SkillsManager) GetSystemPrompts() []string

// Catalog 返回技能目录快照。
// 当前由管理、展示和安装相关路径使用。
func (s *SkillsManager) Catalog() []SkillCatalogEntry
```

### 7.6 设计约束

- `Skill` 与 `skill_* tool` 不是一回事，前者是定义，后者是暴露给 LLM 的执行壳
- declarative skill 即使没有 entrypoint，也仍可贡献 system prompt
- 真正执行型 skill 只能通过 `ExecutionOptions` 控制的执行入口运行，不能绕开策略直接运行
- M3 不持有主工具目录，只把 skill 挂载到 M2

## 8. M4: Plugin Capability Runtime / Plugin 能力运行时模块

### 8.1 职责

- 扫描并加载 plugin manifest
- 维护 plugin 启用状态与信任校验
- 把 plugin tool / app workflow 暴露进工具表
- 暴露 ingress/channel/app/surface runner
- 提供 workflow 搜索与 capability index

### 8.2 当前实现位置

- `anyclaw/pkg/plugin/plugin.go`
- `anyclaw/pkg/plugin/capability.go`

### 8.3 输入结构体

```go
type PluginLoadInput struct {
	// Dir 是插件目录。
	Dir string

	// AllowExec 表示是否允许执行型插件。
	AllowExec bool

	// Enabled 是显式启用插件列表。
	Enabled []string
}

type PluginAssemblyInput struct {
	// Registry 是统一工具注册表。
	Registry tools.Registry

	// BaseDir 是插件根目录。
	BaseDir string

	// ConfigPath 是主配置路径，供 app plugin 读取额外状态。
	ConfigPath string
}

type WorkflowSearchInput struct {
	// Query 是 workflow 搜索文本。
	Query string

	// Limit 是最大返回条数。
	Limit int
}
```

### 8.4 输出结构体

```go
type PluginLoadOutput struct {
	// Plugins 是已装入插件目录快照。
	Plugins []PluginBinding

	// EnabledNames 是当前启用插件名集合。
	EnabledNames []string
}

type PluginAssemblyOutput struct {
	// Tools 是注册进工具表的 plugin tool/app tool 快照。
	Tools []CapabilityDescriptor

	// IngressRunners 是插件提供的 ingress runner。
	IngressRunners []plugin.IngressRunner

	// ChannelRunners 是插件提供的 channel runner。
	ChannelRunners []plugin.ChannelRunner

	// AppRunners 是插件提供的 app runner。
	AppRunners []plugin.AppRunner
}

type WorkflowSearchOutput struct {
	// Matches 是命中的 app workflow 候选。
	Matches []plugin.AppWorkflowMatch
}
```

### 8.5 公开函数

```go
// NewRegistry 扫描插件目录并建立插件注册表。
// 当前由 runtime.Bootstrap(...) 在 Plugins phase 调用。
func NewRegistry(cfg config.PluginsConfig) (*Registry, error)

// SetPolicyEngine 为插件执行挂载统一策略引擎。
// 当前由 runtime.Bootstrap(...) 在 plugin 装配后调用。
func (r *Registry) SetPolicyEngine(policy *tools.PolicyEngine)

// List 返回插件清单快照。
// 当前由管理与调试路径使用。
func (r *Registry) List() []Manifest

// EnabledPluginNames 返回已启用插件名。
// 当前由展示和运行时检查路径使用。
func (r *Registry) EnabledPluginNames() []string

// RegisterToolPlugins 把插件工具注册进统一工具表。
// 当前由 runtime.Bootstrap(...) 在 Plugins phase 调用。
func (r *Registry) RegisterToolPlugins(registry *tools.Registry, baseDir string)

// RegisterAppPlugins 把插件 app action/workflow 注册进统一工具表。
// 当前由 runtime.Bootstrap(...) 在 Plugins phase 调用。
func (r *Registry) RegisterAppPlugins(registry *tools.Registry, baseDir string, configPath string)

// IngressRunners 返回插件提供的 ingress 运行器。
// 当前由集成侧协议装配路径按需消费。
func (r *Registry) IngressRunners(baseDir string) []IngressRunner

// ChannelRunners 返回插件提供的 channel 运行器。
// 当前由集成侧通道装配路径按需消费。
func (r *Registry) ChannelRunners(baseDir string) []ChannelRunner

// AppRunners 返回插件提供的 app 运行器。
// 当前由 app protocol 集成路径消费。
func (r *Registry) AppRunners(baseDir string) []AppRunner

// ResolveWorkflowMatches 根据查询搜索最匹配的 app workflow。
// 当前由 app/workflow 选择路径消费。
func (r *Registry) ResolveWorkflowMatches(query string, limit int) []AppWorkflowMatch

// NewCapabilityIndex 创建插件能力索引。
// 当前用于插件能力目录管理路径。
func NewCapabilityIndex() *CapabilityIndex

// Index 把 manifest 编进能力索引。
// 当前由插件能力分析路径使用。
func (ci *CapabilityIndex) Index(manifest *ManifestV2) error

// SearchWorkflows 在能力索引里搜索 workflow。
// 当前由能力搜索与 UI 展示路径使用。
func (ci *CapabilityIndex) SearchWorkflows(query string, limit int) []WorkflowCapability
```

### 8.6 设计约束

- plugin manifest 解析与 plugin 实际执行必须分开看
- plugin tool/app 最终仍然要挂进 M2 的统一工具表
- workflow 搜索是能力发现，不属于路由层的 agent/session 路由
- ingress/channel/app/surface runner 是集成输出，不等于输入层或网关层本体

## 9. M5: MCP Bridge / Server / MCP 桥接与服务模块

### 9.1 职责

- 建立到外部 MCP server 的客户端连接
- 发现外部 MCP tools/resources/prompts
- 把远端 MCP tools 桥接成系统内部工具
- 提供本地 MCP server 暴露能力

### 9.2 当前实现位置

- `anyclaw/pkg/mcp/client.go`
- `anyclaw/pkg/mcp/registry.go`
- `anyclaw/pkg/mcp/bridge.go`
- `anyclaw/pkg/mcp/server.go`
- `anyclaw/pkg/gateway/gateway.go` 的 `initMCP(...)`

### 9.3 输入结构体

```go
type MCPAttachInput struct {
	// Servers 是配置里声明的 MCP servers。
	Servers []MCPServerBinding

	// Registry 是统一工具表。
	Registry tools.Registry
}

type MCPCallInput struct {
	// ServerName 是目标 MCP server 名。
	ServerName string

	// ToolName 是目标 MCP tool 名。
	ToolName string

	// Args 是 MCP tool 参数。
	Args map[string]any
}
```

### 9.4 输出结构体

```go
type MCPAttachOutput struct {
	// ToolNames 是桥接到本地后的 mcp tool 名列表。
	ToolNames []string

	// Status 是 MCP server 当前连接状态。
	Status map[string]mcp.ServerStatus
}

type MCPCallOutput struct {
	// Result 是 MCP tool 调用结果。
	Result any
}
```

### 9.5 公开函数

```go
// NewClient 创建一个 MCP stdio client。
// 当前由 gateway.Server.initMCP(...) 按配置逐个创建。
func NewClient(name, command string, args []string, env map[string]string) *Client

// NewRegistry 创建 MCP client 注册表。
// 当前由 gateway.Server.initMCP(...) 调用。
func NewRegistry() *Registry

// Register 注册一个 MCP client。
// 当前由 gateway.Server.initMCP(...) 调用。
func (r *Registry) Register(name string, client *Client) error

// ConnectAll 连接所有 MCP servers。
// 当前由 gateway.Server.initMCP(...) 调用。
func (r *Registry) ConnectAll(ctx context.Context) []error

// AllTools 返回所有已连接 server 的工具目录。
// 当前由 BridgeToToolRegistry(...) 使用。
func (r *Registry) AllTools() map[string][]Tool

// CallTool 调用远端 MCP tool。
// 当前由桥接后的 tool handler 调用。
func (r *Registry) CallTool(ctx context.Context, clientName, toolName string, args map[string]any) (any, error)

// Status 返回所有 MCP server 的连接状态。
// 当前由观测和管理路径使用。
func (r *Registry) Status() map[string]ServerStatus

// BridgeToToolRegistry 把远端 MCP tool 挂进本地统一工具表。
// 当前由 gateway.Server.initMCP(...) 在 ConnectAll(...) 之后调用。
func BridgeToToolRegistry(registry *tools.Registry, mcpRegistry *Registry) error

// NewServer 创建本地 MCP server。
// 当前由 gateway.Server.initMCP(...) 调用。
func NewServer(name, version string) *Server

// RegisterTool 向本地 MCP server 注册一个工具。
// 当前由 gateway 自己的 MCP 暴露路径调用。
func (s *Server) RegisterTool(tool ServerTool)

// RegisterResource 向本地 MCP server 注册资源。
// 当前由本地 MCP 暴露路径调用。
func (s *Server) RegisterResource(res ServerResource)

// RegisterPrompt 向本地 MCP server 注册 prompt。
// 当前由本地 MCP 暴露路径调用。
func (s *Server) RegisterPrompt(prompt ServerPrompt)
```

### 9.6 设计约束

- `mcp.Client` 与 `mcp.Server` 是两个方向相反的面，不能混看
- 真正给 agent 用的 MCP tool 名，是桥接后的 `mcp__server__tool`
- MCP bridge 负责接入，不负责 tool policy 和 agent 调度
- 当前 `anyclaw` 的 MCP 主装配点在 `gateway.initMCP(...)`，不在 `runtime.Bootstrap(...)`

## 10. M6: Harness & Extension Integration / Harness 与 Extension 集成模块

### 10.1 职责

- 发现本地 extension manifest
- 发现 CLIHub harness 能力目录
- 做意图到 harness capability 的轻量匹配
- 把 CLIHub catalog / exec 能力暴露为工具

### 10.2 当前实现位置

- `anyclaw/pkg/extension/extension.go`
- `anyclaw/pkg/clihub/capability.go`
- `anyclaw/pkg/clihub/intent.go`
- `anyclaw/pkg/tools/clihub.go`

### 10.3 输入结构体

```go
type ExtensionLoadInput struct {
	// ExtensionsDir 是 extension 根目录。
	ExtensionsDir string
}

type HarnessQueryInput struct {
	// Root 是 CLIHub 根目录。
	Root string

	// Query 是自然语言查询。
	Query string

	// Args 是额外参数。
	Args []string
}
```

### 10.4 输出结构体

```go
type ExtensionLoadOutput struct {
	// Extensions 是已发现 extension 快照。
	Extensions []extension.Extension
}

type HarnessQueryOutput struct {
	// Capabilities 是命中的 harness 能力集合。
	Capabilities []HarnessCapabilityRef

	// ToolNames 是暴露给工具表的 CLIHub tool 名。
	ToolNames []string
}
```

### 10.5 公开函数

```go
// NewRegistry 创建 extension 注册表。
// 当前由 extension 独立加载路径调用。
func NewRegistry(extensionsDir string) *Registry

// LoadAll 发现并装载所有 extension。
// 当前由 extension 管理路径调用。
func (r *Registry) LoadAll() error

// ListByKind 按 kind 返回已启用 extension。
// 当前由集成查询路径使用。
func (r *Registry) ListByKind(kind string) []*Extension

// LoadCapabilityRegistry 加载 CLIHub 能力目录。
// 当前由 agent 意图预处理和工具侧 CLIHub 集成使用。
func LoadCapabilityRegistry(root string) (*CapabilityRegistry, error)

// FindByIntent 根据自然语言查询返回候选 capability。
// 当前由 agent intent 预处理和 CLIHub 查询工具使用。
func (r *CapabilityRegistry) FindByIntent(query string) []Capability

// NewIntentEngine 创建 CLIHub 意图引擎。
// 当前由 CLIHub 集成路径使用。
func NewIntentEngine(root string) (*IntentEngine, error)

// Parse 把自然语言查询解析成 CLIHub intent。
// 当前由意图路由路径调用。
func (e *IntentEngine) Parse(query string) *Intent

// ResolveCommand 把 intent 解析成实际命令和工作目录。
// 当前由 CLIHub 执行路径调用。
func (e *IntentEngine) ResolveCommand(intent *Intent) ([]string, string, error)

// RegisterCLIHubTools 把 CLIHub catalog/exec 等能力注册到统一工具表。
// 当前由 tools.RegisterBuiltins(...) 在内建工具装配阶段调用。
func RegisterCLIHubTools(r *Registry, opts BuiltinOptions)
```

### 10.6 设计约束

- extension registry 当前更像“目录发现层”，还不是 `runtime.Bootstrap(...)` 主链的一部分
- CLIHub 的 intent/capability 匹配属于集成发现，不属于路由层的入站路由
- `clihub_exec` 最终仍通过 M2 的工具调用链落到受策略约束的命令执行
- M6 不能替代输入层 channel adapter，也不能替代 plugin runtime

## 11. M7: Scheduled Automation / Cron Service / 定时自动化模块

### 11.1 职责

- 持有 cron task 生命周期
- 计算 next run、执行重试、保存 run history
- 把 task 交给 agent 或 orchestrator 执行
- 产出统一 `TaskRun`

### 11.2 当前实现位置

- `anyclaw/pkg/cron/scheduler.go`
- `anyclaw/pkg/cron/agent_executor.go`
- `anyclaw/pkg/gateway/handlers_extended.go` 的 cron 装配路径

### 11.3 输入结构体

```go
type AutomationScheduleInput struct {
	// Task 是要注册或更新的定时任务。
	Task cron.Task
}

type AutomationExecuteInput struct {
	// TaskID 是当前执行的任务 ID。
	TaskID string

	// Command 是交给 agent 的任务文本。
	Command string

	// Input 是附加参数。
	Input map[string]any
}
```

### 11.4 输出结构体

```go
type AutomationScheduleOutput struct {
	// TaskID 是成功注册后的任务 ID。
	TaskID string

	// NextRun 是下一次计划执行时间。
	NextRun string
}

type AutomationExecuteOutput struct {
	// Run 是一次执行记录。
	Run cron.TaskRun
}
```

### 11.5 公开函数

```go
// NewScheduler 创建 cron 调度器。
// 当前由 gateway 扩展 handler 在 cron 功能启用时调用。
func NewScheduler(executor Executor) *Scheduler

// SetPersister 为调度器挂载持久化后端。
// 当前由 cron 装配路径调用。
func (s *Scheduler) SetPersister(p TaskPersister)

// LoadPersisted 从持久层恢复任务和运行记录。
// 当前由 cron 启动时调用。
func (s *Scheduler) LoadPersisted() error

// Start 启动调度循环。
// 当前由 gateway cron 启动路径调用。
func (s *Scheduler) Start() error

// Stop 停止调度循环。
// 当前由关闭或回收路径调用。
func (s *Scheduler) Stop()

// AddTask 注册一个新任务。
// 当前由管理接口或测试路径调用。
func (s *Scheduler) AddTask(task *Task) (string, error)

// UpdateTask 更新一个任务。
// 当前由管理接口调用。
func (s *Scheduler) UpdateTask(task *Task) error

// DeleteTask 删除一个任务。
// 当前由管理接口调用。
func (s *Scheduler) DeleteTask(taskID string) error

// RunTaskNow 立即执行一个任务。
// 当前由管理接口调用。
func (s *Scheduler) RunTaskNow(taskID string) error

// NewAgentExecutor 创建 cron 到 agent/orchestrator 的执行桥。
// 当前由 gateway cron 装配路径调用。
func NewAgentExecutor(primaryAgent *agent.Agent, orch *orchestrator.Orchestrator) *AgentExecutor

// Execute 把 cron task 转成 agent prompt 并执行。
// 当前由 Scheduler.runTask(...) 调用。
func (e *AgentExecutor) Execute(ctx context.Context, cmd string, input map[string]interface{}) (string, error)

// ExecuteMultiAgent 把任务交给 orchestrator 做多 agent 执行。
// 当前由自动化多 agent 路径调用。
func (e *AgentExecutor) ExecuteMultiAgent(ctx context.Context, cmd string, agentNames []string) (string, error)
```

### 11.6 设计约束

- Scheduler 负责“什么时候跑”，不负责“如何选模型、如何选工具”
- AgentExecutor 负责把 task 桥接进 agent/orchestrator，不负责 task 存储
- `Task` 是自动化任务合同，不是网关层普通请求合同
- M7 属于集成层，不属于网关协议层本体

## 12. anyclaw 当前总入口与交接

### 12.1 Runtime 能力装配总入口

```go
// Bootstrap 按 config -> storage -> security -> qmd -> skills -> tools -> plugins -> llm -> agent -> orchestrator 的顺序装配运行时。
// 当前由 anyclaw 启动主程序路径调用。
func Bootstrap(opts BootstrapOptions) (*App, error)
```

### 12.2 anyclaw 当前能力装配链

```go
BootstrapOptions
  -> runtime.Bootstrap(...)
  -> SkillsManager.Load(...)
  -> tools.NewRegistry()
  -> tools.RegisterBuiltins(...)
  -> SkillsManager.RegisterTools(...)
  -> plugin.NewRegistry(...)
  -> plugin.RegisterToolPlugins(...)
  -> plugin.RegisterAppPlugins(...)
  -> llm.NewClientWrapper(...)
  -> agent.New(...)
  -> App{Skills, Tools, Plugins, LLM, Agent}
```

### 12.3 anyclaw 当前 MCP 装配链

```go
gateway.Server.initMCP(...)
  -> mcp.NewRegistry()
  -> mcp.NewClient(...)
  -> Registry.Register(...)
  -> Registry.ConnectAll(...)
  -> mcp.BridgeToToolRegistry(app.Tools, registry)
  -> mcp.NewServer(...)
```

### 12.4 anyclaw 当前能力调用链

```go
Agent step
  -> modelrouting.DecideLLM(...)
  -> llm.ClientWrapper.Chat(...) / StreamChat(...)
  -> LLM ToolCalls
  -> tools.Registry.Call(...)
  -> builtin tool / skill_* / plugin tool / app tool / mcp__* / clihub_*
  -> tool result
  -> agent continue
```

### 12.5 anyclaw 当前自动化链

```go
cron.Task
  -> cron.Scheduler
  -> cron.AgentExecutor
  -> agent.Agent.Run(...) / orchestrator.RunTask(...)
  -> cron.TaskRun
```

这里最重要的边界结论是：

- 路由层只把请求交给执行侧，不负责能力装配
- 能力层的统一挂载点是 `tools.Registry`
- skill、plugin、MCP tool 最终都要回到同一个工具表
- MCP 当前主装配点在 `gateway.initMCP(...)`
- extension / clihub 当前属于集成发现与工具桥接，不是输入层本体


Module Specification for Capability & Integration Layer #61

Description

能力层与集成层模块规格

1. 范围

2. 三条主链路

2.1 Runtime 装配链

2.2 能力调用链

2.3 集成与自动化链

3. 能力层与集成层职责边界

3.1 能力层必须负责的事

3.2 集成层必须负责的事

3.3 一个必须写死的边界

4. 共享对象合同

4.1 运行时能力对象

4.2 集成对象

5. M1: Model Runtime / Provider Adapter / 模型运行时与 Provider 适配模块

5.1 职责

5.2 当前实现位置

5.3 输入结构体

5.4 输出结构体

5.5 公开函数

5.6 设计约束

6. M2: Tool Registry / Builtin Capability Assembly / 工具注册与内建能力装配模块

6.1 职责

6.2 当前实现位置

6.3 输入结构体

6.4 输出结构体

6.5 公开函数

6.6 设计约束

7. M3: Skill Loader / Prompt Augmentation / Skill 装载与 Prompt 增强模块

7.1 职责

7.2 当前实现位置

7.3 输入结构体

7.4 输出结构体

7.5 公开函数

7.6 设计约束

8. M4: Plugin Capability Runtime / Plugin 能力运行时模块

8.1 职责

8.2 当前实现位置

8.3 输入结构体

8.4 输出结构体

8.5 公开函数

8.6 设计约束

9. M5: MCP Bridge / Server / MCP 桥接与服务模块

9.1 职责

9.2 当前实现位置

9.3 输入结构体

9.4 输出结构体

9.5 公开函数

9.6 设计约束

10. M6: Harness & Extension Integration / Harness 与 Extension 集成模块

10.1 职责

10.2 当前实现位置

10.3 输入结构体

10.4 输出结构体

10.5 公开函数

10.6 设计约束

11. M7: Scheduled Automation / Cron Service / 定时自动化模块

11.1 职责

11.2 当前实现位置

11.3 输入结构体

11.4 输出结构体

11.5 公开函数

11.6 设计约束

12. anyclaw 当前总入口与交接

12.1 Runtime 能力装配总入口

12.2 anyclaw 当前能力装配链

12.3 anyclaw 当前 MCP 装配链

12.4 anyclaw 当前能力调用链

12.5 anyclaw 当前自动化链

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions