Plugin 总览

在当前 Downcity 里，plugin 就是能力扩展单元。

这意味着：

• 能力通过 plugin 暴露
• 运行时参与点通过 plugin 暴露
• 长生命周期的托管 runtime 模块，也统一建模成 plugin

如果你想看具体 built-in plugin 手册，请继续阅读 Agent Plugins Docs。

一句话理解

plugin 是 Downcity 里“一个能力边界”的统一承载单元。

它可以是：

• action-first
• hook-oriented
• system-oriented
• lifecycle-owned
• HTTP-exposing

两类最重要的 plugin

本地 plugin

这类 plugin 通常直接挂到一个本地 SDK Agent 上。

典型例子：

• skill
• web
• asr
• tts
• auth

托管 plugin

这类 plugin 属于 runtime 管理对象，会跟随目标 agent lifecycle 参与运行。

典型例子：

• chat
• task
• memory
• contact
• shell

ActionSchedule 由 Agent 自身管理，因此不会作为 plugin 出现在列表里。

正因为存在这类托管 plugin，旧的“分层对立”语言已经不再适合当前模型。

在本地 SDK 里怎么接入 plugin

import { Agent } from "@downcity/agent";
import { SkillPlugin, WebPlugin } from "@downcity/plugins";

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  tools: {},
  plugins: [new SkillPlugin(), new WebPlugin()],
});

const plugins = agent.plugins.list();

关键点：

• plugins 是当前这个 Agent 私有的 registry
• SDK 不会自动注册所有 built-in plugin
• 你可以直接使用 agent.plugins.list()、availability()、runAction()
• prompt 阶段的 plugin system 文本，只来自这个 SDK Agent 已注册的 plugin

一个 plugin 可能包含什么

完整 plugin 可能包含：

• config
• actions
• setup
• usage
• hooks
• resolves
• system
• availability
• http
• lifecycle

不是每个 plugin 都需要把这些全部实现。

现在“plugin 启用”到底是什么意思

要分多层理解：

• agent 级：这个本地 SDK Agent 有没有注册该 plugin
• runtime 级：这个托管 plugin 当前是启动还是停止
• plugin 自身级：availability() 当前是否判定可用
• project 级：downcity.json.plugins.* 里有什么运行参数

不要把它们混成一个概念。

推荐阅读顺序

1. Plugin Design Patterns
2. Plugin Lifecycle
3. Plugin 配置
4. Plugin Actions
5. Plugin Hooks
6. Agent Plugins Docs
7. 自定义 Plugin