Agentic 配置

Agentic 尽量保持 OpenCode 配置兼容。上游字段以 OpenCode schema 和官方文档为准；Agentic 特有的版本、发布、Flow 与外部插件指导维护在静态文档和对应插件中，不重新注入内置产品 skill。模型 Prompt 只保留 Agentic/OpenCode 文档路由，不复制产品知识正文。

模型如何查询

Agentic 产品行为、发布、Desktop、Flow 与平台支持的公开权威入口为 https://github.com/chunklib/agentic-releases#readme。provider、plugin API、command、protocol、OAuth、Zen 与 Go 等上游兼容行为继续查询 https://opencode.ai/docs。

# 本机 Agentic 版本
agentic --version

# npm 已发布版本
npm view @chunklib/agentic version

# 当前合并后配置
agentic debug config

provider/model 可用性取决于当前 OpenCode catalog、本地凭据和用户配置。默认目录是 https://models.opencode.ai，可用 AGENTIC_MODELS_URL 覆盖；Agentic 不维护一张可能过期的固定模型列表，也不替用户选择 provider/model。目录是远程元数据输入，不应指向不受信任的服务。

npm 包名迁移

独立仓基线从 agency-agentic 迁移到 @chunklib/agentic。旧的 [email protected] 只查询旧包的 latest，不能通过 agentic upgrade 跨越 npm 包名；现有用户需要在同一个 npm 全局前缀完成一次手动迁移：

npm uninstall --global agency-agentic
npm install --global @chunklib/[email protected]
agentic --version

迁移到 1.1.0 或更高版本后，npm 渠道的后续 agentic upgrade 会查询并安装 @chunklib/agentic。CLI GitHub binary 是独立渠道，只有存在匹配 Release 资产时才跟随该渠道升级。

上游兼容配置总表

| 范围 | 配置入口 | 说明 | |---|---|---| | provider/model/agent/permission/MCP | agentic.json / agentic.jsonc | 使用 OpenCode 兼容 schema | | 用户全局 | XDG config 下的 Agentic/OpenCode 兼容路径 | 具体合并结果用 agentic debug config 确认 | | 项目级 | 项目中的 agentic.json(c) | 项目配置与 AGENTS.md 分工 | | 外部插件 | plugin 数组 | npm 包名或受支持的本地插件路径 | | 项目指令 | AGENTS.md | AGENTIC.md 别名已退休 | | 外部 skill | 上游兼容 skill 路径 | 可由 Agentic 环境开关限制扫描 |

从 OpenCode v1.18.16 起，schema 已知字段仍校验类型和值，但未知顶层字段由 Effect Schema 忽略，不再让整个配置加载失败。这是上游兼容行为，不表示未知字段会生效；最终有效配置仍以 agentic debug config 为准。

从 OpenCode v1.18.17 起，App 选择默认模型时优先使用当前 server provider catalog 返回的 defaultModel；只有旧 server 完全不返回该字段时，才回退解析 config.model。server 显式返回 null 表示没有默认模型，不能再被旧配置覆盖。provider transform 同版采用 DeepSeek V4 Flash 的 topP=0.95、merge-gateway-ai-sdk-provider reasoning effort，以及 GitHub Copilot PDF capability；这些是上游 provider/model 元数据行为，不新增 Agentic 私有配置键。

OpenCode v1.18.24-v1.18.25 的 V1 配置加载器会先把受支持的 V2 字段降低到 V1 结构：例如 model 选择、agents/commands、mcp.servers、skills、compaction 和部分 experimental 字段。V1 字段优先于冲突的 V2 字段；不支持或有损转换会记录不包含配置值的 diagnostics，V2 原生 permissions 会明确拒绝并提示使用 V1 permission 规则或 opencode2。更新现有 JSON/JSONC 时保留原始记录，不把未知字段静默重写为 V1 schema。

Azure provider 保留 API key 登录，并在安装 Azure CLI 且已用 az login 时提供 Microsoft Entra ID (Azure CLI) 登录。自 v1.18.26 起，OAuth 流程直接询问 AZURE_RESOURCE_NAME，不再通过 Azure management API 发现订阅、资源或 deployments；AZURE_RESOURCE_GROUP 与 AZURE_CONFIG_DIR 不再参与该流程，Azure CLI 缺失时仅隐藏 OAuth 方法而不影响 API key。Entra token 按 Azure endpoint 使用对应 scope，Node runtime 不要求 Bun。

OpenCode v1.18.29 将 provider headerTimeout/chunkTimeout 默认值明确为 300000ms，chunkTimeout 同时支持显式 false 以关闭 SSE chunk 超时；V1 配置 schema 仅更新描述语义，不新增 Agentic 私有配置键。Agentic 原样采用该默认与关闭语义，provider allowlist 仍在 credential-bearing loader 之前执行。

Agentic 保留 AGENTIC_* 产品运行时命名空间；OPENCODE_VERSION、OPENCODE_CHANNEL 等官方构建/协议常量在需要上游兼容时继续保留。不应为了表面品牌统一破坏插件、SDK 或官方服务边界。

项目指令优先级

Agentic 自 OpenCode v1.18.13 起保持上游的 AGENTS.md 发现与兼容行为，不引入品牌专属规则文件：

1. 全局类别优先读取 ~/.config/agentic/AGENTS.md；不存在时，才读取 ~/.claude/CLAUDE.md。
2. 项目类别从当前目录向项目根查找：只要存在 AGENTS.md，就加载沿途全部 AGENTS.md；完全不存在时，才回退查找 CLAUDE.md，随后是已弃用的 CONTEXT.md。
3. 访问项目内文件时，沿文件所在目录向项目根补充尚未注入的子目录规则，同一消息内去重。
4. agentic.json(c) 的 instructions 是显式附加来源，与上述规则合并，不替换它们。

全局与项目类别分别选择首个可用文件类型，因此全局 AGENTS.md 可以与项目 CLAUDE.md 同时生效。多个层级的规则采用叠加语义，不执行键值覆盖；内容冲突时应让更靠近目标文件的规则保持更具体。

CLAUDE.md 回退是 OpenCode v1 上游兼容行为，不是 Agentic 自定义能力。Agentic 的差异仅是全局目录使用 ~/.config/agentic，并提供 AGENTIC_DISABLE_CLAUDE_CODE_PROMPT（或总开关 AGENTIC_DISABLE_CLAUDE_CODE）关闭该回退。预发布 V2 core 当前只聚合 AGENTS.md；Agentic 不为它另加兼容层，后续随上游正式迁移。/init 始终只创建或更新 AGENTS.md。

Flow 适配层

Flow 是 @chunklib/agentic-flow 独立插件，配置属于 agentic-flow.jsonc，不应将 Flow 私有字段写入 OpenCode 核心 schema。启用仍通过标准 plugin 数组，路由、agent 和 tool gates 由插件管理。

使用前以独立仓库 chunklib/agentic-flow 的 README 为准。Flow 必须保持显式启用，不能给普通 Agentic 会话增加默认调度成本。

IDE 接入

Visual Studio Code

Agentic 1.0.9 起提供与 CLI 同版本的独立 VSIX；当前源码与线上最新已发布版本均为 1.1.12。扩展启动 agentic --port <port>，通过 AGENTIC_CALLER=vscode 或 vscode-insiders 激活 IDE 行为，并使用 _EXTENSION_AGENTIC_PORT 隔离终端会话。它不再使用上游 opencode.* command ID、OPENCODE_CALLER 或 opencode 可执行文件。

先安装同版本 CLI，再从相同版本的 Agentic GitHub Release 下载 agentic-vscode-<version>.vsix，用 VS Code 的 “Extensions: Install from VSIX...” 安装。Marketplace/Open VSX 需要独立的 Agentic publisher 凭据；GitHub VSIX 发布不表示这两个商店已经上架。

JetBrains IDE

支持 ACP 的 JetBrains IDE/AI Assistant 可在其 acp.json 中配置 Agentic：

{
  "agent_servers": {
    "Agentic": {
      "command": "agentic",
      "args": ["acp"]
    }
  }
}

JetBrains 通过标准输入输出管理 agentic acp 子进程，不复用 VS Code 扩展，也不需要 Agentic 自建 JetBrains 插件。协议、认证、会话、模型和权限能力由 Agentic ACP 实现及具体 JetBrains 客户端版本共同决定；若 IDE 尚未提供 ACP 设置入口，仅升级 Agentic 不能补出该入口。

Agentic 进程开关

这些开关是运行时或测试边界，不是可选功能的私有业务 schema。常见类别包括：

• server/auth：AGENTIC_SERVER_USERNAME、AGENTIC_SERVER_PASSWORD、AGENTIC_API_KEY；
• 测试隔离：AGENTIC_DISABLE_PROJECT_CONFIG、AGENTIC_DISABLE_EXTERNAL_SKILLS、AGENTIC_DISABLE_CLAUDE_CODE；
• Desktop/runtime：AGENTIC_CLIENT；AGENTIC_SIDECAR_V2=1 与上游相同仅显式启用 v2 daemon，默认仍为 v1；AGENTIC_DISABLE_CHANNEL_DB 仍是 Core 显式诊断开关，但 Desktop 开发启动不再强制设置它；
• 模型目录：运行时 AGENTIC_MODELS_URL；构建兼容顺序为 AGENTIC_MODELS_URL、OPENCODE_MODELS_URL、官方目录；
• 构建兼容：OPENCODE_VERSION、OPENCODE_CHANNEL；浏览器产品版本由发行脚本注入 VITE_AGENTIC_VERSION。

新增开关前要先判断是否能通过现有配置、插件或适配层解决。

Modal 动态模型发现仅在存在对应凭据且 provider 被 allowlist 允许时运行。Agentic 只把 Modal bearer token 发往 HTTPS inference.<region>.modal.direct，拒绝目录提供的其他 host、非 HTTPS URL 和重定向；失败时该次动态模型集合为空，静态配置和其他 provider 不受影响。

发布与防漂移

• 配置以当前 schema 和 agentic debug config 为事实源，不从旧 decision 复制过期字段。
• 每次修改本文档时，同步 npm 分发文档和相关发布检查，不复制到 OpenCode 内置 skill。
• 应用新插件前，实际查询 npm 版本、许可、运行时支持与数据边界。
• Desktop Node sidecar 的验收不默认安装任何外部记忆插件；插件应有独立兼容测试。
• 完整发布前运行 scripts/test-agentic-automation.sh 与无跳过 full 验收。