@roll-agent/core 0.18.0 → 0.20.0

package/dist/config/guidance.d.ts

@@ -0,0 +1,571 @@
+import type { AgentEnvDeclaration, AgentSkillEnvDeclarations } from "../types/agent.ts";
+export declare const INSTALL_SCENARIOS: readonly ["default-network", "china-dev", "private-registry", "advanced"];
+export type InstallScenario = (typeof INSTALL_SCENARIOS)[number];
+export interface ConfigGuidanceEntry {
+    readonly path: string;
+    readonly title: string;
+    readonly purpose: string;
+    readonly defaultBehavior?: string;
+    readonly example?: string;
+    readonly setupCommand?: string;
+}
+export declare const CONFIG_GUIDANCE_ENTRIES: readonly [{
+    readonly path: "llm";
+    readonly title: "LLM 与模型";
+    readonly purpose: "集中设置 Roll 默认使用的模型提供商、模型名称和各 Provider 连接信息。";
+    readonly defaultBehavior: "默认使用内置的 Anthropic Provider 与默认模型；实际调用仍需要可用的认证信息。";
+    readonly example: `llm:
+  default-provider: ${string}
+  default-model: ${string}
+  providers: {}`;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.default-provider";
+    readonly title: "默认 LLM 提供商";
+    readonly purpose: "选择 `roll ask`、`roll run` 的 MCP sampling，以及未单独覆盖时 `roll chat` 使用的模型提供商。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
+    readonly example: `llm:
+  default-provider: ${string}`;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.default-model";
+    readonly title: "默认 LLM 模型";
+    readonly purpose: "指定 Ask 的默认路由与 sampling 模型、Run 的 sampling 模型，以及 Chat 未单独覆盖时的模型。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
+    readonly example: `llm:
+  default-model: ${string}`;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.providers";
+    readonly title: "LLM Provider 配置";
+    readonly purpose: "按 Provider 名称保存认证密钥和可选的自定义 API 地址。";
+    readonly defaultBehavior: "默认没有 Provider 连接条目；只需添加实际会使用的 Provider。";
+    readonly example: string;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.providers.<provider>";
+    readonly title: "单个 LLM Provider";
+    readonly purpose: "配置一个由名称标识的模型服务连接，例如 `anthropic`、`openai` 或兼容网关。";
+    readonly defaultBehavior: "新增条目后必须提供 API 密钥；API 地址可留空并使用 Provider 默认值。";
+    readonly example: string;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.providers.<provider>.api-key";
+    readonly title: "Provider API 密钥";
+    readonly purpose: string;
+    readonly defaultBehavior: "无默认值；新增 provider 配置后必须填写，否则配置校验失败。";
+    readonly example: string;
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "llm.providers.<provider>.base-url";
+    readonly title: "Provider API 地址";
+    readonly purpose: "把指定 provider 指向代理、兼容网关或私有部署的 API 根地址。";
+    readonly defaultBehavior: "不配置时使用各 provider 的内置地址；Qwen 使用 DashScope OpenAI 兼容地址。";
+    readonly example: "llm:\n  providers:\n    openai:\n      base-url: https://api.openai.com/v1";
+    readonly setupCommand: "roll config setup llm";
+}, {
+    readonly path: "ask";
+    readonly title: "Ask 智能路由";
+    readonly purpose: "只覆盖 `roll ask` 的路由模型和低置信度确认阈值。";
+    readonly defaultBehavior: "不设置覆盖时沿用全局 LLM 模型与内置确认阈值。";
+    readonly example: "ask:\n  confirm-threshold: 0.5";
+}, {
+    readonly path: "ask.llm-model";
+    readonly title: "Ask 路由模型";
+    readonly purpose: "仅为 `roll ask` 的意图路由和参数提取指定模型，不改变 `roll chat` 模型。";
+    readonly defaultBehavior: "不配置时使用 `llm.default-model`。";
+    readonly example: "ask:\n  llm-model: gpt-5.4-mini";
+}, {
+    readonly path: "ask.confirm-threshold";
+    readonly title: "Ask 执行阈值";
+    readonly purpose: "路由置信度低于此值时停止自动执行，并返回需要确认的结果。";
+    readonly defaultBehavior: "不配置时使用内置阈值 `0.5`。";
+    readonly example: "ask:\n  confirm-threshold: 0.5";
+}, {
+    readonly path: "runtime";
+    readonly title: "Chat 运行时";
+    readonly purpose: "控制 `roll chat` 的模型、单轮限制、审批、上下文压缩和 Shell 工具。";
+    readonly defaultBehavior: "所有子项都有安全默认值；只有需要覆盖默认行为时才写入配置。";
+    readonly example: `runtime:
+  max-steps: ${number}
+  turn-timeout-ms: ${number}`;
+}, {
+    readonly path: "runtime.provider";
+    readonly title: "Chat 模型提供商";
+    readonly purpose: "仅覆盖 `roll chat` 使用的模型提供商，便于让 Ask 与 Chat 使用不同服务。";
+    readonly defaultBehavior: "不配置时使用 `llm.default-provider`。";
+    readonly example: "runtime:\n  provider: openai";
+}, {
+    readonly path: "runtime.model";
+    readonly title: "Chat 模型";
+    readonly purpose: "仅覆盖 `roll chat` 的主模型；子 Agent 的 sampling 也复用该模型。";
+    readonly defaultBehavior: "不配置时使用 `llm.default-model`。";
+    readonly example: "runtime:\n  model: gpt-5.5";
+}, {
+    readonly path: "runtime.max-steps";
+    readonly title: "单轮最大步骤数";
+    readonly purpose: "限制 `roll chat` 单轮中模型继续推理和调用工具的最大步骤数。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF1B\u8FBE\u5230\u4E0A\u9650\u540E\u672C\u8F6E\u505C\u6B62\u7EE7\u7EED\u8C03\u7528\u5DE5\u5177\u3002`;
+    readonly example: `runtime:
+  max-steps: ${number}`;
+}, {
+    readonly path: "runtime.turn-timeout-ms";
+    readonly title: "单轮超时时间";
+    readonly purpose: "限制 `roll chat` 一整轮从开始到结束可占用的总时间，单位毫秒。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF0C\u5373 5 \u5206\u949F\u3002`;
+    readonly example: `runtime:
+  turn-timeout-ms: ${number}`;
+}, {
+    readonly path: "runtime.threads-dir";
+    readonly title: "会话存储目录";
+    readonly purpose: "保存 `roll chat` 会话元数据和消息记录，供会话恢复与列表命令读取。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF1B\u52A0\u8F7D\u65F6\u4F1A\u5C55\u5F00 \`~/\`\u3002`;
+    readonly example: `runtime:
+  threads-dir: ${string}`;
+}, {
+    readonly path: "runtime.context-window";
+    readonly title: "上下文窗口";
+    readonly purpose: "手动声明当前 Chat 模型的上下文 token 容量，用于计算自动压缩触发点。";
+    readonly defaultBehavior: "不配置时按模型名查询内置容量表；无法识别时不按占用比例触发压缩。";
+    readonly example: "runtime:\n  context-window: 200000";
+}, {
+    readonly path: "runtime.thinking-level";
+    readonly title: "推理强度";
+    readonly purpose: "控制 Chat 与 MCP sampling 的推理强度；可选 `off`、`low`、`medium`、`high`。";
+    readonly defaultBehavior: "默认值为 `off`；具体预算由 provider 适配层映射。" | "默认值为 `low`；具体预算由 provider 适配层映射。" | "默认值为 `medium`；具体预算由 provider 适配层映射。" | "默认值为 `high`；具体预算由 provider 适配层映射。";
+    readonly example: "runtime:\n  thinking-level: off" | "runtime:\n  thinking-level: low" | "runtime:\n  thinking-level: medium" | "runtime:\n  thinking-level: high";
+}, {
+    readonly path: "runtime.approval";
+    readonly title: "工具审批";
+    readonly purpose: "控制 Chat 调用工具时的默认授权方式，并允许按工具精确覆盖。";
+    readonly defaultBehavior: string;
+    readonly example: "runtime:\n  approval:\n    default: auto\n    overrides: {}" | "runtime:\n  approval:\n    default: guarded\n    overrides: {}" | "runtime:\n  approval:\n    default: deny\n    overrides: {}";
+}, {
+    readonly path: "runtime.approval.default";
+    readonly title: "工具默认审批策略";
+    readonly purpose: "决定 `roll chat` 未被单独覆盖的工具如何审批：`guarded` 按风险判断，`auto` 放行非破坏性操作，`deny` 拒绝。";
+    readonly defaultBehavior: "默认值为 `auto`。此配置不影响 `roll ask`。" | "默认值为 `guarded`。此配置不影响 `roll ask`。" | "默认值为 `deny`。此配置不影响 `roll ask`。";
+    readonly example: "runtime:\n  approval:\n    default: auto" | "runtime:\n  approval:\n    default: guarded" | "runtime:\n  approval:\n    default: deny";
+}, {
+    readonly path: "runtime.approval.overrides";
+    readonly title: "单个工具审批规则";
+    readonly purpose: "按完整 `agentName.toolName` 为特定工具设置例外规则。";
+    readonly defaultBehavior: "默认为空；未命中的工具回退到 `runtime.approval.default`。";
+    readonly example: "runtime:\n  approval:\n    overrides:\n      browser-use-agent.zhipin_send_prepared_reply: confirm\n      browser-use-agent.browser_status: auto";
+}, {
+    readonly path: "runtime.approval.overrides.<tool>";
+    readonly title: "单个工具审批策略";
+    readonly purpose: "为一个完整 `agentName.toolName` 选择 `auto`、`confirm` 或 `deny`。";
+    readonly defaultBehavior: "不配置该工具时回退到 `runtime.approval.default`。";
+    readonly example: "runtime:\n  approval:\n    overrides:\n      browser-use-agent.browser_status: auto";
+}, {
+    readonly path: "runtime.compaction";
+    readonly title: "上下文压缩";
+    readonly purpose: "在长对话接近模型上下文容量时，控制何时压缩以及保留多少近期内容。";
+    readonly defaultBehavior: "默认开启摘要压缩，并保留近期轮次与 token 预算。";
+    readonly example: "runtime:\n  compaction:\n    enabled: true\n    strategy: summarize" | "runtime:\n  compaction:\n    enabled: true\n    strategy: truncate";
+}, {
+    readonly path: "runtime.compaction.enabled";
+    readonly title: "自动压缩上下文";
+    readonly purpose: "允许 Chat 在上下文接近容量或收到上下文超限错误时压缩早期消息。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\u3002`;
+    readonly example: `runtime:
+  compaction:
+    enabled: ${string}`;
+}, {
+    readonly path: "runtime.compaction.strategy";
+    readonly title: "上下文压缩策略";
+    readonly purpose: "选择 `summarize` 生成交接摘要，或用 `truncate` 直接移除较早消息。";
+    readonly defaultBehavior: "默认值为 `summarize`；结构化输出无效或过长时退回 `truncate`，Provider、网络或超时错误则保留原上下文。" | "默认值为 `truncate`；结构化输出无效或过长时退回 `truncate`，Provider、网络或超时错误则保留原上下文。";
+    readonly example: "runtime:\n  compaction:\n    strategy: summarize" | "runtime:\n  compaction:\n    strategy: truncate";
+}, {
+    readonly path: "runtime.compaction.timeout-ms";
+    readonly title: "压缩模型超时";
+    readonly purpose: "限制结构化 Checkpoint 模型请求的总等待时间，不包含本地证据整理和持久化。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\` \u6BEB\u79D2\uFF1B\u8D85\u65F6\u4FDD\u6301\u539F\u4E0A\u4E0B\u6587\uFF0C\u4E0D\u81EA\u52A8\u622A\u65AD\u3002`;
+    readonly example: `runtime:
+  compaction:
+    timeout-ms: ${string}`;
+}, {
+    readonly path: "runtime.compaction.thinking-level";
+    readonly title: "压缩推理强度";
+    readonly purpose: "覆盖结构化 Checkpoint 生成的推理强度；使用 AI SDK 的统一 reasoning 语义映射到当前 Provider。";
+    readonly defaultBehavior: "默认不单独设置并继承 `runtime.thinking-level`；Qwen 结构化输出仍会强制关闭 thinking，不支持关闭推理的模型会在调用前报错。";
+    readonly example: "runtime:\n  compaction:\n    thinking-level: high";
+}, {
+    readonly path: "runtime.compaction.max-output-tokens";
+    readonly title: "压缩输出 Token 上限";
+    readonly purpose: "限制结构化 Checkpoint 请求的 AI SDK 输出 token 预算。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF1BProvider \u7684 reasoning token \u4E5F\u53EF\u80FD\u5360\u7528\u8BE5\u9884\u7B97\u3002`;
+    readonly example: `runtime:
+  compaction:
+    max-output-tokens: ${string}`;
+}, {
+    readonly path: "runtime.compaction.threshold";
+    readonly title: "自动压缩触发比例";
+    readonly purpose: "当最近一次输入 token 占上下文窗口的比例达到此值时，在下一轮前压缩。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\u3002`;
+    readonly example: `runtime:
+  compaction:
+    threshold: ${number}`;
+}, {
+    readonly path: "runtime.compaction.keep-recent-turns";
+    readonly title: "保留最近对话轮数";
+    readonly purpose: "压缩时至少保留最近的用户对话轮，避免当前任务细节过早进入摘要。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\` \u8F6E\u3002`;
+    readonly example: `runtime:
+  compaction:
+    keep-recent-turns: ${number}`;
+}, {
+    readonly path: "runtime.compaction.keep-recent-tokens";
+    readonly title: "保留最近 Token 预算";
+    readonly purpose: "压缩时用于保留近期完整对话的近似 token 预算，并与保留轮数共同取更保守边界。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\u3002`;
+    readonly example: `runtime:
+  compaction:
+    keep-recent-tokens: ${number}`;
+}, {
+    readonly path: "runtime.shell";
+    readonly title: "Shell 工具";
+    readonly purpose: "控制 Chat 是否可执行本地命令，以及一次性命令和后台会话的安全限制。";
+    readonly defaultBehavior: "默认关闭；开启后仍受工具审批策略、超时和输出上限约束。";
+    readonly example: "runtime:\n  shell:\n    enabled: true";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.enabled";
+    readonly title: "Chat 内建 shell 工具";
+    readonly purpose: "在 `roll chat` 中注册命令工具：macOS/Linux 使用 `roll__bash`，Windows 使用 `roll__powershell`。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\uFF1BWindows \u8FD8\u9700\u8981 PowerShell 7+\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.auto-approve-safe";
+    readonly title: "只读命令免确认";
+    readonly purpose: "让 POSIX shell 中已识别的安全只读命令免确认；危险或无法识别的命令仍需审批。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF1BWindows PowerShell \u547D\u4EE4\u76EE\u524D\u4ECD\u6309\u672A\u77E5\u64CD\u4F5C\u5904\u7406\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true\n    auto-approve-safe: false";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.default-timeout-ms";
+    readonly title: "Shell 默认超时时间";
+    readonly purpose: "为未显式传入超时的一次性 shell 命令设置执行上限，单位毫秒。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF1B\u8FD8\u4F1A\u53D7\u6700\u5927\u8D85\u65F6\u548C\u5355\u8F6E\u8D85\u65F6\u9650\u5236\u3002`;
+    readonly example: `runtime:
+  shell:
+    default-timeout-ms: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.max-timeout-ms";
+    readonly title: "Shell 最大超时时间";
+    readonly purpose: "限制模型为一次性 shell 命令请求的最长执行时间，单位毫秒。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF1B\u5B9E\u9645\u65F6\u9650\u4ECD\u4E0D\u4F1A\u8D85\u8FC7\u5355\u8F6E\u8D85\u65F6\u3002`;
+    readonly example: `runtime:
+  shell:
+    max-timeout-ms: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.max-capture-bytes";
+    readonly title: "Shell 输出捕获上限";
+    readonly purpose: "限制 shell 标准输出与错误输出的内存捕获量，并限制后台会话输出缓冲区。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\` \u5B57\u8282\u3002`;
+    readonly example: `runtime:
+  shell:
+    max-capture-bytes: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.max-model-output-chars";
+    readonly title: "Shell 模型输出上限";
+    readonly purpose: "限制一次性 shell 工具返回给模型的 stdout 与 stderr 总字符数。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\` \u4E2A\u5B57\u7B26\uFF1B\u8D85\u51FA\u90E8\u5206\u4F1A\u622A\u65AD\u5E76\u6807\u8BB0\u3002`;
+    readonly example: `runtime:
+  shell:
+    max-model-output-chars: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session";
+    readonly title: "后台命令会话";
+    readonly purpose: "让长命令跨 Chat 轮次继续运行，并通过轮询读取增量输出和退出状态。";
+    readonly defaultBehavior: "默认关闭；必须同时开启 Shell 工具，且会话随当前 Chat 进程退出。";
+    readonly example: "runtime:\n  shell:\n    enabled: true\n    session:\n      enabled: true";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session.enabled";
+    readonly title: "Chat 会话式长命令执行";
+    readonly purpose: "在 macOS/Linux 与 Windows PowerShell 7+ 中注册 `roll__exec_command`、`roll__exec_poll`、`roll__exec_list`，让长命令在后台跨轮运行。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF08\u5173\u95ED\uFF09\uFF1B\u4EC5\u957F\u9A7B Chat \u6A21\u5F0F\u53EF\u7528\u4E14\u9700\u5F00\u542F \`runtime.shell.enabled\`\uFF0C\`--server\` \u8FD8\u9700\u663E\u5F0F\u653E\u884C \`roll.exec_command\`\u3002`;
+    readonly example: "runtime:\n  shell:\n    enabled: true\n    session:\n      enabled: true\n  approval:\n    overrides:\n      roll.exec_command: auto";
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session.max-sessions";
+    readonly title: "后台命令会话上限";
+    readonly purpose: "限制同一 `roll chat` 进程中可保留的运行中或待领取结果的后台命令会话数。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\` \u4E2A\u4F1A\u8BDD\u3002`;
+    readonly example: `runtime:
+  shell:
+    session:
+      max-sessions: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session.default-yield-ms";
+    readonly title: "后台命令默认等待时间";
+    readonly purpose: "设置 `exec_command` 首次返回前以及后续轮询通常等待的时间，单位毫秒。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF1B\u8C03\u7528\u65B9\u4ECD\u53EF\u5728\u5DE5\u5177\u53C2\u6570\u4E2D\u8986\u76D6\u3002`;
+    readonly example: `runtime:
+  shell:
+    session:
+      default-yield-ms: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "runtime.shell.session.max-output-tokens";
+    readonly title: "后台命令单次输出上限";
+    readonly purpose: "限制 `exec_command` / `exec_poll` 每次返回给模型的新输出量，以近似 token 数计。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF1B\u8FD0\u884C\u4E2D\u7684\u4F1A\u8BDD\u4E0D\u4F1A\u56E0\u8F93\u51FA\u622A\u65AD\u800C\u505C\u6B62\u3002`;
+    readonly example: `runtime:
+  shell:
+    session:
+      max-output-tokens: ${number}`;
+    readonly setupCommand: "roll config setup shell";
+}, {
+    readonly path: "skills";
+    readonly title: "Skills 发现";
+    readonly purpose: "补充 `roll chat` 自动发现范围之外的 Skill 目录。";
+    readonly defaultBehavior: "标准项目级、用户级和已注册 Agent Skills 始终自动发现。";
+    readonly example: "skills:\n  dirs: []";
+}, {
+    readonly path: "skills.dirs";
+    readonly title: "Chat 额外 skill 目录";
+    readonly purpose: "`roll chat` 会自动发现项目级、用户级和已注册 Agent 的 Skill。这里只填写标准范围之外的额外目录，例如团队共享目录；目录可以直接包含 `SKILL.md`，也可以包含多个 Skill 子目录。";
+    readonly defaultBehavior: "默认为空；`<项目>/.agents/skills`、`~/.agents/skills`，以及通过 `npx skills add` 安装到标准位置的 Skill 都会自动发现，无需重复填写。";
+    readonly example: "skills:\n  dirs:\n    - ./openclaw-roll-core-skill-template";
+}, {
+    readonly path: "skills.dirs.<item>";
+    readonly title: "额外 Skill 目录路径";
+    readonly purpose: "添加一个额外搜索目录；它可以直接含 `SKILL.md`，也可以包含多个 skill 子目录。";
+    readonly defaultBehavior: "默认没有额外目录；项目级、用户级和已注册 Agent 的 skills 仍会自动发现。";
+    readonly example: "skills:\n  dirs:\n    - ./skills/team-shared";
+}, {
+    readonly path: "agents";
+    readonly title: "Agent 管理";
+    readonly purpose: "设置 Roll 的 Agent 数据目录，并为子 Agent 声明额外环境变量。";
+    readonly defaultBehavior: "使用默认数据目录；未写入的环境变量继续从 Roll 进程环境继承。";
+    readonly example: `agents:
+  data-dir: ${string}`;
+}, {
+    readonly path: "agents.data-dir";
+    readonly title: "Agent 数据目录";
+    readonly purpose: "保存已注册 Agent、PID、日志和 runtime sidecar 等 Roll 管理数据。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF1B\u52A0\u8F7D\u65F6\u4F1A\u5C55\u5F00 \`~/\`\u3002`;
+    readonly example: `agents:
+  data-dir: ${string}`;
+}, {
+    readonly path: "agents.env";
+    readonly title: "其他 Agent 环境变量";
+    readonly purpose: "为未在独立 Agent 页面中展示的 Agent 或自定义变量提供通用键值配置入口。";
+    readonly defaultBehavior: "默认没有额外注入；已声明的注册 Agent 优先在各自页面配置。";
+    readonly example: "agents:\n  env:\n    custom-agent:\n      FEATURE_FLAG: enabled";
+    readonly setupCommand: "roll config setup agent <agent-name>";
+}, {
+    readonly path: "agents.env.<agent-name>";
+    readonly title: "Agent 环境变量组";
+    readonly purpose: "按 Agent 名称组织需要注入子进程的环境变量。";
+    readonly defaultBehavior: "默认没有额外注入；子进程仍继承当前 Roll 进程环境。";
+    readonly example: "agents:\n  env:\n    browser-use-agent:\n      REPLY_AUTHORITY_URL: https://example.com";
+    readonly setupCommand: "roll config setup agent <agent-name>";
+}, {
+    readonly path: "agents.env.<agent-name>.<variable>";
+    readonly title: "Agent 环境变量";
+    readonly purpose: "为一个 Agent 注入单个字符串环境变量；同名值会覆盖父进程继承值。";
+    readonly defaultBehavior: "不配置时沿用 Roll 进程中的同名环境变量；core-managed Agent 需重启后生效。";
+    readonly example: "agents:\n  env:\n    browser-use-agent:\n      REPLY_AUTHORITY_URL: https://example.com";
+    readonly setupCommand: "roll config setup agent <agent-name>";
+}, {
+    readonly path: "install";
+    readonly title: "安装与更新";
+    readonly purpose: "控制 Agent 安装和 Roll 更新时使用的 npm 软件源、重试、缓存与超时。";
+    readonly defaultBehavior: "默认使用 npm 自身的软件源，并采用 Roll 的安全网络默认值。";
+    readonly example: `install:
+  fetch-retries: ${number}
+  prefer-offline: false`;
+    readonly setupCommand: "roll config setup install";
+}, {
+    readonly path: "install.registry";
+    readonly title: "npm Registry 地址";
+    readonly purpose: "指定 `roll agent install` 与 `roll update` 查询和安装 npm 包时使用的软件源。";
+    readonly defaultBehavior: "不配置时使用 npm 自身默认源；Roll 不做隐式镜像 fallback。";
+    readonly example: "install:\n  registry: https://registry.npmmirror.com";
+    readonly setupCommand: "roll config setup install";
+}, {
+    readonly path: "install.fetch-retries";
+    readonly title: "安装下载重试次数";
+    readonly purpose: "设置 npm `--fetch-retries`，同时作为 Roll 安装网络操作的整体重试次数。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\` \u6B21\u3002`;
+    readonly example: `install:
+  fetch-retries: ${number}`;
+    readonly setupCommand: "roll config setup install";
+}, {
+    readonly path: "install.prefer-offline";
+    readonly title: "优先使用本地缓存";
+    readonly purpose: "决定 npm 安装时是否附加 `--prefer-offline`，优先复用本地缓存元数据。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${string}\`\uFF0C\u4F18\u5148\u83B7\u53D6\u65B0\u9C9C\u5143\u6570\u636E\u3002`;
+    readonly example: `install:
+  prefer-offline: ${string}`;
+    readonly setupCommand: "roll config setup install";
+}, {
+    readonly path: "install.network-timeout-ms";
+    readonly title: "安装网络超时时间";
+    readonly purpose: "限制单次 npm install 命令的等待时间，单位毫秒。";
+    readonly defaultBehavior: `\u9ED8\u8BA4\u503C\u4E3A \`${number}\`\uFF0C\u5373 120 \u79D2\u3002`;
+    readonly example: `install:
+  network-timeout-ms: ${number}`;
+    readonly setupCommand: "roll config setup install";
+}, {
+    readonly path: "browser";
+    readonly title: "浏览器实例";
+    readonly purpose: "管理 browser-use-agent 可以连接或启动的浏览器实例及默认选择。";
+    readonly defaultBehavior: "未声明实例时继续使用 legacy 单实例环境变量配置。";
+    readonly example: "browser:\n  instances: {}";
+}, {
+    readonly path: "browser.default-instance";
+    readonly title: "默认浏览器实例";
+    readonly purpose: "指定工具未传 `browserInstance` 时优先选择的已声明实例。";
+    readonly defaultBehavior: "不配置且只有一个实例时自动选择；有多个实例时必须由调用方指定。";
+    readonly example: "browser:\n  default-instance: boss-a";
+}, {
+    readonly path: "browser.instances";
+    readonly title: "浏览器实例声明";
+    readonly purpose: "声明 browser-use-agent 可使用的浏览器 profile、CDP 端口、会话目录和业务归因信息。";
+    readonly defaultBehavior: "不配置时 browser-use-agent 使用 legacy 单实例环境变量路径。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      platform: zhipin\n      mode: managed-cdp\n      cdp-port: 9222\n      user-data-dir: ~/.roll-agent/browser/boss-a";
+}, {
+    readonly path: "browser.instances.<instance>";
+    readonly title: "单个浏览器实例";
+    readonly purpose: "用一个稳定名称描述浏览器连接方式、Profile、窗口和业务归属。";
+    readonly defaultBehavior: "默认使用本地托管 Chrome；仍必须为每个实例设置独占 Profile 目录和 CDP 端口。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      mode: managed-cdp\n      cdp-port: 9222\n      user-data-dir: ~/.roll-agent/browser/boss-a";
+}, {
+    readonly path: "browser.instances.<instance>.platform";
+    readonly title: "业务平台";
+    readonly purpose: "标记该浏览器实例属于 BOSS 直聘（`zhipin`）还是鱼泡（`yupao`），用于平台匹配校验。";
+    readonly defaultBehavior: "不配置时实例不限定业务平台，平台专用工具不会做实例平台冲突校验。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      platform: zhipin";
+}, {
+    readonly path: "browser.instances.<instance>.mode";
+    readonly title: "浏览器连接模式";
+    readonly purpose: "选择本地托管浏览器、远程 CDP，或连接用户已启动浏览器会话。";
+    readonly defaultBehavior: "默认值为 `managed-cdp`。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      mode: managed-cdp";
+}, {
+    readonly path: "browser.instances.<instance>.headless";
+    readonly title: "无头运行";
+    readonly purpose: "控制 `managed-cdp` 启动的浏览器是否隐藏窗口；其他连接模式不使用此项。";
+    readonly defaultBehavior: "不配置时继承 browser-use-agent 全局设置，默认显示浏览器窗口。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      headless: false";
+}, {
+    readonly path: "browser.instances.<instance>.cdp-url";
+    readonly title: "CDP 连接地址";
+    readonly purpose: "提供 `remote-cdp` 或 `existing-session` 模式要连接的 HTTP(S) / WebSocket CDP 地址。";
+    readonly defaultBehavior: "这两种模式下无默认值且必须填写；`managed-cdp` 使用 host 与 port 生成地址。";
+    readonly example: "browser:\n  instances:\n    chrome-open:\n      mode: existing-session\n      cdp-url: http://127.0.0.1:9222";
+}, {
+    readonly path: "browser.instances.<instance>.cdp-host";
+    readonly title: "本地 CDP 主机";
+    readonly purpose: "指定 `managed-cdp` 启动后用于健康检查和连接的 CDP 主机地址。";
+    readonly defaultBehavior: "默认值为 `127.0.0.1`；远程与已有会话模式不使用此项。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      cdp-host: 127.0.0.1";
+}, {
+    readonly path: "browser.instances.<instance>.cdp-port";
+    readonly title: "本地 CDP 端口";
+    readonly purpose: "指定 `managed-cdp` 浏览器的远程调试端口；每个实例必须使用不同端口。";
+    readonly defaultBehavior: "`managed-cdp` 实例无默认值且必须填写；其他模式不使用此项。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      cdp-port: 9222";
+}, {
+    readonly path: "browser.instances.<instance>.channel";
+    readonly title: "浏览器类型";
+    readonly purpose: "选择 `managed-cdp` 启动系统 Chrome、Playwright Chromium 或 Microsoft Edge。";
+    readonly defaultBehavior: "默认值为 `chrome`；配置 `executable-path` 后此项会被忽略。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      channel: chrome";
+}, {
+    readonly path: "browser.instances.<instance>.executable-path";
+    readonly title: "浏览器程序路径";
+    readonly purpose: "为 `managed-cdp` 指定浏览器可执行文件，适合非标准安装位置或定制版本。";
+    readonly defaultBehavior: "不配置时按 `channel` 查找系统浏览器；配置后优先使用此路径。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      executable-path: /Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+}, {
+    readonly path: "browser.instances.<instance>.user-data-dir";
+    readonly title: "浏览器 Profile 目录";
+    readonly purpose: "为实例声明独占的 Profile 目录；`managed-cdp` 在此保存登录态，状态检查也会检查其可写性。";
+    readonly defaultBehavior: "无默认值；每个已声明实例都必须填写。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      user-data-dir: ~/.roll-agent/browser/boss-a";
+}, {
+    readonly path: "browser.instances.<instance>.sessions-dir";
+    readonly title: "浏览器会话目录";
+    readonly purpose: "保存 Roll 的页面会话快照，与浏览器自身的 Profile 数据分开存放。";
+    readonly defaultBehavior: "不配置时使用 `~/.roll-agent/browser/sessions/<instance-id>`。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      sessions-dir: ~/.roll-agent/browser/sessions/boss-a";
+}, {
+    readonly path: "browser.instances.<instance>.args";
+    readonly title: "浏览器启动参数列表";
+    readonly purpose: "仅为本地托管浏览器追加确有必要的命令行开关。";
+    readonly defaultBehavior: "默认使用 browser-use-agent 内置启动参数，不追加自定义值。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      args:\n        - --lang=zh-CN";
+}, {
+    readonly path: "browser.instances.<instance>.args.<item>";
+    readonly title: "浏览器启动参数";
+    readonly purpose: "向 `managed-cdp` 浏览器追加一个命令行参数；仅添加确实需要的开关。";
+    readonly defaultBehavior: "默认不追加自定义参数；远程与已有会话模式不使用此项。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      args:\n        - --lang=zh-CN";
+}, {
+    readonly path: "browser.instances.<instance>.profile-name";
+    readonly title: "浏览器 Profile 名称";
+    readonly purpose: "设置托管 Chrome 窗口显示的 Profile 名称，帮助区分多个业务账号。";
+    readonly defaultBehavior: "不配置时使用浏览器实例 ID。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      profile-name: BOSS 主账号";
+}, {
+    readonly path: "browser.instances.<instance>.profile-color";
+    readonly title: "浏览器 Profile 颜色";
+    readonly purpose: "用六位十六进制颜色标记托管 Chrome Profile，帮助肉眼区分多个窗口。";
+    readonly defaultBehavior: "不配置时按实例顺序自动分配不同颜色。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      profile-color: \"#2563EB\"";
+}, {
+    readonly path: "browser.instances.<instance>.window-bounds";
+    readonly title: "窗口位置与大小";
+    readonly purpose: "可选地固定托管浏览器窗口的屏幕位置和尺寸。";
+    readonly defaultBehavior: "整组留空时，多实例可视模式会自动排布窗口。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      window-bounds:\n        x: 0\n        y: 0\n        width: 960\n        height: 900";
+}, {
+    readonly path: "browser.instances.<instance>.window-bounds.x";
+    readonly title: "窗口横向位置";
+    readonly purpose: "设置托管浏览器窗口左上角距主屏左侧的像素数。";
+    readonly defaultBehavior: "整个 `window-bounds` 未设置时，多实例可视模式会自动排布；否则交由系统决定。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      window-bounds:\n        x: 0";
+}, {
+    readonly path: "browser.instances.<instance>.window-bounds.y";
+    readonly title: "窗口纵向位置";
+    readonly purpose: "设置托管浏览器窗口左上角距主屏顶部的像素数。";
+    readonly defaultBehavior: "整个 `window-bounds` 未设置时，多实例可视模式会自动排布；否则交由系统决定。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      window-bounds:\n        y: 0";
+}, {
+    readonly path: "browser.instances.<instance>.window-bounds.width";
+    readonly title: "窗口宽度";
+    readonly purpose: "设置托管浏览器窗口宽度，单位像素，必须大于 0。";
+    readonly defaultBehavior: "整个 `window-bounds` 未设置时，多实例可视模式会自动排布；否则交由系统决定。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      window-bounds:\n        width: 960";
+}, {
+    readonly path: "browser.instances.<instance>.window-bounds.height";
+    readonly title: "窗口高度";
+    readonly purpose: "设置托管浏览器窗口高度，单位像素，必须大于 0。";
+    readonly defaultBehavior: "整个 `window-bounds` 未设置时，多实例可视模式会自动排布；否则交由系统决定。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      window-bounds:\n        height: 900";
+}, {
+    readonly path: "browser.instances.<instance>.tracking-agent-id";
+    readonly title: "招聘事件 Agent ID";
+    readonly purpose: "为该浏览器实例上报的招聘事件指定归因 Agent ID。";
+    readonly defaultBehavior: "不配置时回退到 `RECRUITMENT_EVENTS_DEFAULT_AGENT_ID`；两者都没有时状态标记为未配置。";
+    readonly example: "browser:\n  instances:\n    boss-a:\n      tracking-agent-id: zhipin-boss-a";
+}];
+export declare function listConfigGuidanceEntries(): readonly ConfigGuidanceEntry[];
+export declare function findConfigGuidance(path: string): ConfigGuidanceEntry | undefined;
+export declare function flattenAgentEnvDeclarations(declarations: AgentSkillEnvDeclarations | undefined): ReadonlyArray<AgentEnvDeclaration & {
+    readonly required: boolean;
+}>;
+export declare function isSecretEnvDeclaration(declaration: AgentEnvDeclaration): boolean;