详细说明本地 Agent 的 id、path、instruction、model、env、tools 和 plugins 参数

Agent 构造参数

本地 Agent 的构造方式：

new Agent({
  id,
  path,
  model,
  env,
  instruction,
  tools,
  plugins,
  Session,
})

`id`

agent 的稳定标识。

它会影响 SDK session 落盘路径：

<projectRoot>/.downcity/agents/<agentId>/...

`path`

当前 agent 绑定的项目根目录。

SDK 会基于它：

读取项目配置
组织会话落盘目录

如果 path 给错，后面很多行为都会变得不符合预期，因为 Agent 会在错误上下文里读取配置和写数据。

`instruction`

调用方传入的本地 SDK Agent 静态基础指令。

new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  instruction: [
    "你是一个简洁的代码助手。",
    "解释代码时优先给出明确文件引用。",
  ],
});

关键点：

instruction 是静态的，应该保持缓存友好
SDK 不会对它做动态变量渲染
SDK 不会自己读取 PROFILE.md 或 SOUL.md
如果省略 instruction，SDK 会使用包内最小 core instruction 作为 fallback

如果 city 这类宿主希望项目 markdown 文件影响 agent，应由宿主自己读取文件，并把最终文本通过 instruction 传入。

`model`

这个 agent 下新建 session 的默认 LanguageModel 实例。

new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  model: openai.responses("gpt-5"),
});

关键点：

SDK 不负责帮你解析 provider 或 model ID
宿主仍然需要先自己创建 LanguageModel 实例
它会成为这个 agent 的 session 默认执行模型
你仍然可以对某个 session 单独调用 session.set({ model }) 做覆写

`env`

这个 agent 可见的环境变量快照。

new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  env: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? "",
  },
});

关键点：

SDK 只消费你显式传入的环境变量集合
SDK 不再区分 global env 和 agent env
如果宿主需要合并多层 env，应先在外部合并，再把最终结果传给 env
这些值会参与配置解析与运行时上下文装配，但不会自动回写系统环境变量

`tools`

agent 级默认工具集合。

关键点：

它属于 agent 级，不是 session 级
当前 agent 创建出来的 session 会直接复用这份工具集合

这很适合“多个 session 共用一套默认工具能力”的场景。

`plugins`

这里接收的是已经实例化好的 BasePlugin 对象。

例如：

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()],
});

SDK 会为当前 Agent 创建独立的 plugin registry。

关键点：

应该传 new SkillPlugin() 这类实例，而不是原始 plugin 定义对象
它不会默认注册全部内建 plugin
它不会复用全局 runtime 的 plugin manager
同名 plugin 被重复注册时会直接报错
agent.plugins 与 AgentContext.plugins 会使用这份 registry
如果你想一次性注入整套内建 plugin，可以从 @downcity/plugins 传入 plugins: createBuiltinPlugins()

`Session`

本地 session 的高级自定义类。

当你希望替换本地 session 实现，或者在 Session 层注入自定义 Composer 时使用它。Agent 只负责用这个类创建和恢复 session，不理解 Composer 的具体策略。

import {
  Agent,
  Session,
  type SessionOptions,
  type SessionSystemComposer,
} from "@downcity/agent";

const systemComposer: SessionSystemComposer = {
  name: "custom_system",
  async resolve() {
    return [{ role: "system", content: "始终简洁回答。" }];
  },
};

class CustomSession extends Session {
  constructor(options: SessionOptions) {
    super({
      ...options,
      composers: {
        systemComposer,
      },
    });
  }
}

const agent = new Agent({
  id: "repo-helper",
  path: "/path/to/project",
  Session: CustomSession,
});

关键点：

传入的是 class，不是已经创建好的 session 实例
这样 Agent 可以按不同 sessionId 创建多个 session
Composer 自定义留在自定义 Session 类内部
RemoteAgent 不支持本地 Session 类，因为它只是远程 runtime 的访问器