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

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

关键配置项

配置项	作用	说明
`provider`	当前 provider	`web-access` 或 `agent-browser`
`injectPrompt`	是否注入 provider 提示词	建议大多数场景保持开启
`repositoryUrl`	记录来源仓库	更偏安装元信息
`sourceVersion`	记录来源版本	更偏安装元信息
`browserCommand`	浏览器命令名	仅 `agent-browser` 模式相关
`installScope`	安装位置	`user` 或 `project`

主要动作

Action	作用	什么时候用
`status`	看当前配置与可用状态	想先了解当前环境
`providers`	列出支持的 provider	想做选择器或控制面
`configure`	写入配置	想更新 provider 或提示词策略
`install`	安装当前 provider 对应能力	首次接入时
`on`	启用 plugin	从 city 级生命周期打开
`off`	关闭 plugin	从 city 级生命周期关闭
`use`	切换当前 provider	项目运行时切换联网方式
`doctor`	做依赖诊断	怀疑 provider 没装好时

场景化用法示例

查看当前状态

const status = await agent.plugins.runAction({
  plugin: "web",
  action: "status",
});

这个结果通常会告诉你：

当前 plugin 配置
当前 availability
当前 provider 的就绪信息

列出所有 provider

const providers = await agent.plugins.runAction({
  plugin: "web",
  action: "providers",
});

安装 provider

const result = await agent.plugins.runAction({
  plugin: "web",
  action: "install",
  payload: {
    provider: "web-access",
    installScope: "user",
    injectPrompt: true,
  },
});

切换当前 provider

const result = await agent.plugins.runAction({
  plugin: "web",
  action: "use",
  payload: {
    provider: "agent-browser",
    browserCommand: "agent-browser",
    injectPrompt: true,
  },
});

更新常规配置

const result = await agent.plugins.runAction({
  plugin: "web",
  action: "configure",
  payload: {
    provider: "web-access",
    injectPrompt: true,
  },
});

做依赖诊断

const diagnosis = await agent.plugins.runAction({
  plugin: "web",
  action: "doctor",
});

`setup` 和 `usage` 在这里分别做什么

web 是理解这两个概念最清楚的内建样本之一。

`setup`

更偏首次接入：

选 provider
选安装位置
决定是否注入提示词

`usage`

更偏已经接入后的日常配置：

当前 provider 是谁
是否继续注入提示词
浏览器命令是什么

所以你可以把它理解为：

setup 解决“先接上”
usage 解决“接上之后怎么用”

`system` 在这里为什么很重要

web 会根据当前配置，把 provider 对应的指导文本注入 system prompt。

这一步很关键，因为“agent 具备联网能力”和“agent 知道自己应该怎么用这项联网能力”不是一回事。

比如：

web-access 更偏搜索、查证、资料获取
agent-browser 更偏真实浏览器操作

如果不把这种差异注入 prompt，agent 很容易选错路径。

它的自然边界

web 自己并不承担真实搜索引擎或浏览器执行器的长期实例管理。

它更像一个：

provider 选择器
安装入口
prompt 适配层

如果你要理解“plugin 负责接能力、外部能力负责执行能力”，web 是很好的例子。

需要注意的边界

它不直接做网页搜索

真正搜索或浏览器操作的执行不在这个 plugin 内部。

`on/off` 是 city 级生命周期，不只是项目配置

这意味着：

configure 改的是怎么用
on/off 改的是这个 plugin 在平台上是否启用

这两层不要混淆。

切 provider 不等于自动迁移所有心智

从 web-access 切到 agent-browser 后，最重要的是 system prompt 也要随之变化。

这也是 injectPrompt 默认值得保留为 true 的原因。

什么时候优先参考它

当你要设计这些能力时，优先参考 web：

provider 适配层
setup / usage 双界面插件
availability 与 doctor 诊断
system prompt 随配置切换

web Plugin

web Plugin

它到底做什么

`web-access` 和 `agent-browser` 有什么区别

`web-access`

`agent-browser`

它使用了哪些 plugin 能力

为什么它是理解完整 plugin 的好样本

典型场景

场景一：项目主要做资料研究

场景二：项目要操作登录后的动态后台

场景三：项目里既有研究任务，又有浏览器自动化任务

在 SDK 里怎么挂载