Agent Core 扩展点
Agent Core 当前有四类不同层次的扩展点。它们都是源码级接入点，不是可从外部目录自动安装的统一插件系统。
需求
在修改前先选择边界：
| 目标 | 扩展点 | 运行位置 |
|---|---|---|
| 接入新的模型 API | LLMProvider | Electron 主进程 |
| 接入新的事件来源 | TriggerAdapter | Electron 主进程 |
| 提供不依赖 Minecraft 的工具 | 本地工具 Schema + Pipeline handler | Electron 主进程 |
| 调整计划/执行/移交/总结提示 | 编排 Markdown skill | Prompt 注入阶段 |
架构
Provider
packages/agent-core/src/main/llm/types.ts 中的 LLMProvider 是统一模型接口：
interface LLMProvider {
readonly metadata: ProviderMetadata
chat(messages, tools?, options?): Promise<LLMResponse>
chatStream(messages, tools?, options?): AsyncIterable<LLMChunk>
embed?(text: string): Promise<number[]>
healthCheck(): Promise<HealthCheckResult>
}执行步骤：
- 参考
llm/providers/base-provider.ts与现有 Provider 实现请求、流式解析和错误转换。 - 在
llm/bootstrap.ts的 Provider 工厂映射中构造实例。 - 使用
providerRegistry.register(id, provider)注册；重复 id 会抛错。 - 若工具格式与现有格式不同，还需在
prompt/tools/tool-format-adapters.ts增加转换并接入工厂。 - 为配置、模型发现、健康检查和流式工具调用添加测试。
ProviderRegistry 虽公开注册方法，但当前应用启动 wiring 仍是源码内接线；仅实现接口不会被自动发现。
TriggerAdapter
TriggerAdapter 只负责把来源特定的原始事件归一为 AgentEvent：
interface TriggerAdapter {
readonly source: TriggerSource
start(): Promise<void>
stop(): Promise<void>
handle(rawEvent: unknown): AgentEvent | null
}实现后还必须：
- 扩展
TriggerSource及对应 payload 类型； - 在
trigger/adapters/导出实现； - 在
TriggerModule的adapters、start()、stop()和getAdapter()中接线； - 明确事件订阅生命周期、过滤和失败行为；
- 覆盖原始事件到
AgentEvent的单元测试。
当前没有公共 registerAdapter()；不要声称把文件放入目录即可加载。
本地工具
Agent Core 本地工具与 Adapter 动态工具分开保存。workspace/tool-registry.ts 的 registerLocal(workspaceId, tools) 会把本地 Schema 合入工作区，同名时本地工具覆盖 Adapter 工具。
一个可执行本地工具至少包含两部分：
ToolSchema，让 LLM 看见名称、描述与参数；- Pipeline 中间件或其他本地处理器，拦截该名称并产生
ToolCallResult。
只调用 registerLocal() 会暴露 Schema，但不会自动产生执行逻辑。可参考 main-agent-registry.ts 中 QQ、Wiki、搜索、记忆、任务和 update_plan 的注册与 handler wiring。
编排 Markdown skill
orchestration/skill-injector.ts 启动时扫描指定 skillsDir 下的 .md 文件，按文件名前缀映射阶段：
| 前缀 | 阶段 |
|---|---|
plan* | plan |
execute* | execute |
transfer* | transfer |
summarize* | summarize |
仓库内置文件位于 packages/agent-core/src/main/orchestration/skills/。内容会作为 Markdown 注入 system prompt，并受总 skill token 预算裁剪。无法识别前缀的文件会跳过；读取失败不会阻止其他 skill。
执行
- 在上述四类中只选择与需求匹配的扩展点。
- 参考同目录最小现有实现，保持类型和错误语义一致。
- 在应用启动 wiring 中显式接线；除 Markdown skill 外，没有目录自动发现。
- 运行 Agent Core 类型检查与测试：
pnpm --filter @mcagent/agent-core typecheck
pnpm --filter @mcagent/agent-core test- Provider 还需验证健康检查和流式响应；TriggerAdapter 需验证启停；本地工具需验证 Schema 与 handler 成对存在；skill 需验证阶段选择和预算裁剪。
稳定边界
这些接口是当前仓库内部扩展面，未形成独立 npm SDK 或跨版本兼容承诺。对外分发前应固定 Agent Core 版本，并把启动 wiring 和回归测试一起维护。