Agent Profile

Agent Profile 是 Jarvis 的代理配置文件。它把一个 coding agent 的行为偏好打包成可复用配置，供单次会话、项目绑定和 Workflow 节点使用。

它不是运行时账号配置，也不是主聊天模型池。它描述的是“这个 worker 应该怎样工作”。

定义

一个 Agent Profile 可以包含：

• 使用哪个模型和备用模型；
• worker 启动时收到的系统指令、引用文件和路径规则；
• 允许使用哪些内置工具、接入哪些 MCP server、拒绝哪些危险工具；
• 权限模式和 allow/deny/ask 规则；
• 要注入的 skills；
• 会话启动、工具调用前后触发的 hooks；
• 默认工作目录和自动应用目录。

当前主存储是 YAML 文件。Jarvis 会在启动时加载内置模板，也会读取用户创建或导入的 Profile。

为什么需要它

没有 Profile 时，你需要在每次启动会话时重复说明模型、角色、权限和工具边界。Profile 把这些稳定选择变成命名配置：

• 给“文档写作”“代码审查”“安全审计”等任务固定默认行为；
• 降低 prompt 重复和权限误配；
• 让 Workflow 节点引用同一套行为配置；
• 在多个项目之间导入、导出和复制配置；
• 预览 Profile 会写入运行时的哪些本地配置文件。

配置段

配置段	负责什么
model	模型、提供商、fallback 和运行时选项。
instructions	系统提示词、引用文件和路径规则。
tools	内置工具、MCP server 和拒绝规则。
permissions	权限模式和 allow/deny/ask 策略。
skills	注入给 worker 的技能引用。当前只支持 local skills 注入。
hooks	SessionStart、PreToolUse、PostToolUse 事件处理器。

这些配置段会按运行时能力映射。Claude Code 映射最完整；Codex、OpenCode、Kimi Code 的映射会受各自运行时能力限制。

应用链路

Profile 可以通过四条路径生效：

路径	说明
单次会话选择	在聊天输入区或启动会话入口选择一个 Profile。
默认 Profile	把某个 Profile 设为默认，后续未显式选择时优先使用。
项目绑定	在项目目录写入 .jarvis/profile，Jarvis 从该目录启动会话时自动应用。
Workflow 节点	在节点上设置 profile_id，该 worker 启动时应用对应 Profile。

Profile 提供默认值；单次启动显式传入的运行时、模型、目录等参数通常优先于 Profile 默认值。

与运行时配置的关系

Jarvis 不替代运行时 CLI 的登录和全局账号配置。Profile 只在 Jarvis 启动或应用会话配置时生成运行时可理解的文件或启动参数。

运行时	映射方式
Claude Code	生成 .claude/settings.json、.claude/agents/jarvis-<id>.md，有 MCP 时生成 .mcp.json。
Codex	通过启动配置注入 instructions、reasoning effort 和 MCP；内置工具 allowlist 与细粒度权限不是完整映射。
OpenCode / Kimi Code	使用通用映射，按运行时能力应用基础指令和配置。

边界

• skills.source 虽然有 local/registry/git schema，但当前 worker 注入只支持 local。
• hooks 只覆盖 Profile schema 中的三个事件，不等同完整运行时 hooks 体系。
• bypassPermissions 风险很高，linter 会把共享 Profile 中的 bypass 标为错误。
• MCP server 的 env 不应内联真实密钥。使用环境变量引用，让 secret 留在本机环境中。
• Extension 提供的 Profile 通常是 locked；复制后才能编辑。

相关页面

• 创建 Agent Profile
• Agent Profile 参考
• 创建 Workflow
• 启动会话
• 权限
• 工具