Examples

NotesPlugin 场景

用一个最小但有真实用途的 NotesPlugin 场景说明 actions、config 和 system 如何组合

NotesPlugin 场景

场景

你希望给某个 agent 增加一组“项目笔记”能力:

  • 查看当前 notes 配置
  • 保存 notes 目录配置
  • 给 agent 注入一段关于 notes 用法的 system 文本

这就是很典型的 plugin 用例。

为什么这里更像 plugin

因为你要的是:

  • 一组显式 action
  • 一段 system 增强文本
  • 一块 project 级配置

而不是一个长期运行 worker。

示例

import { Agent, type Plugin } from "@downcity/agent";

export const notesPlugin: Plugin = {
  name: "notes",
  title: "Project Notes",
  description: "Save and describe a project notes folder.",
  config: {
    plugin: "notes",
    scope: "project",
    defaultValue: {
      injectPrompt: true,
      folder: ".notes",
    },
  },
  system(context) {
    return `Project notes folder: ${context.rootPath}/.notes`;
  },
  actions: {
    status: {
      allowWhenDisabled: true,
      execute: async ({ context }) => {
        return {
          success: true,
          data: {
            rootPath: context.rootPath,
          },
        };
      },
    },
  },
};

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

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

这个场景最适合学什么

  • plugin 可以只靠 config + actions + system 就成立
  • 不需要 worker,也不需要长期实例状态

这个场景在本地 SDK 里怎么落地

上面的写法现在已经可以直接在本地 Agent 里运行。

这里最值得注意的是:

  • status 因为声明了 allowWhenDisabled: true,即使 plugin 被显式禁用也能用于自检
  • agent.plugins.runAction(...) 是最直接的显式调用入口
  • 如果你再实现 system(),当这个 plugin 注册到 Agent 上时,本地 SDK session 主路径会注入这段 system 文本

相关文档