Agent Profile 参考

Agent Profile 参考页描述公开 YAML 格式和可配置字段。它适合导入、导出、审查或排查 Profile。

存储与格式

用户 Profile 以 YAML 文件存储。默认目录是 ~/.jarvis/profiles/，管理员可用 JARVIS_PROFILES_DIR 覆盖。

磁盘 YAML 和导出结果使用同一类文档结构。REST 导入也读取这个结构，但当前不会保留 default_cwd 字段；需要项目默认目录时，在导入后编辑 Profile 再保存。

version: 2
name: Example Profile
description: 用一句话说明这个 Profile 适合什么任务
runtime: auto

model:
  model: claude-sonnet-4-6

instructions:
  system_prompt: |
    Describe how this agent should behave.

tools:
  builtin:
    - Read
    - Glob
    - Grep

permissions:
  mode: acceptEdits

created_at、updated_at、source、locked、owner_pack_id 等元数据通常由 Jarvis 管理，手写 Profile 时不需要主动填写。

顶层字段

字段	类型	默认值	说明
`version`	integer	`1`	推荐写 `2`。
`name`	string	必填	Profile 展示名。
`description`	string	`""`	用途说明。
`icon`	string	`bot`	UI 图标名。
`runtime`	string	`auto`	YAML 字段名；API 中对应 `target_runtime`。常用 `auto`、`claude-code`、`codex`、`opencode`、`kimi-code`。
`model`	object	`{}`	模型配置。
`instructions`	object	`{}`	指令配置。
`tools`	object	`{}`	工具和 MCP 配置。
`permissions`	object	`{ mode: acceptEdits }`	权限策略。
`skills`	array	`[]`	Skill 引用。当前 worker 注入只支持 local skills。
`hooks`	object	`{}`	Profile hook 配置。
`auto_apply_dir`	string	`""`	保存后自动应用到的目录。空字符串表示不设置。
`default_cwd`	string	`""`	启动会话时的默认工作目录。空字符串表示不设置；显式 cwd 优先。

`model`

字段	类型	说明
`model`	string	运行时模型标识。
`provider`	string or null	可选提供商标识。
`fallback`	string[]	备用模型列表。Claude Code emitter 使用第一个 fallback。
`options`	object	运行时相关选项。例如 Codex 可读取 `reasoning_effort` 或 `effort`。

`instructions`

字段	类型	说明
`system_prompt`	string	worker 的核心行为说明。
`files`	string[]	附加引用文件。Claude Code 输出中会以文件引用形式呈现。
`rules`	array	路径规则列表。

路径规则结构：

字段	类型	说明
`glob`	string	文件匹配模式。
`instruction`	string	匹配文件时要遵守的说明。

`tools`

字段	类型	说明
`builtin`	string[]	内置工具 allowlist。常见值包括 `Read`、`Write`、`Edit`、`Bash`、`Glob`、`Grep`、`WebSearch`、`WebFetch`、`Agent`。
`mcp_servers`	object	MCP server 配置。
`deny`	string[]	工具拒绝规则，会与权限 deny 合并映射到支持的运行时。

MCP server 配置：

字段	类型	说明
`type`	string	`stdio` 或 `http`。
`command`	string or null	stdio server 启动命令。
`args`	string[]	stdio server 参数。
`url`	string or null	http server 地址。
`env`	object	环境变量映射。不要内联真实密钥。

Codex runtime 中 jarvis 是 Jarvis 保留 MCP server 名称，不要在 Profile MCP 配置中复用。

`permissions`

字段	类型	默认值	说明
`mode`	string	`acceptEdits`	常用值为 `plan`、`acceptEdits`、`bypassPermissions`。
`allow`	string[]	`[]`	显式允许规则。
`deny`	string[]	`[]`	显式拒绝规则。
`ask`	string[]	`[]`	需要询问的规则。当前部分 UI 表单不是一等编辑入口，但 YAML/API 支持。

权限模式：

模式	含义
`plan`	偏只读或先计划，适合审查、研究和高风险场景。
`acceptEdits`	允许常规编辑，但仍保留权限边界。
`bypassPermissions`	高风险模式。共享 Profile 中会被 linter 视为错误，除非你明确知道后果。

运行时对权限的支持程度不同。不要把 Profile 权限当作绕过运行时本地安全机制的方式。

`skills`

字段	类型	说明
`name`	string	Skill 名称。
`source`	string	schema 允许 `local`、`registry`、`git`；当前 worker 注入只支持 `local`。
`path`	string or null	显式 skill 目录。目录内需要 `SKILL.md`。
`version`	string or null	预留版本字段。

Skill 解析优先使用显式 path，否则查找个人级和项目级 .claude/skills/<name>。

`hooks`

Profile hooks 只覆盖三个事件：

事件	触发点
`SessionStart`	会话开始时。
`PreToolUse`	工具调用前。
`PostToolUse`	工具调用后。

handler 字段：

字段	类型	说明
`type`	string	`command`、`http` 或 `prompt`。
`command`	string or null	command handler 使用。
`url`	string or null	http handler 使用。
`prompt`	string or null	prompt handler 使用。
`matcher`	string or null	匹配条件。
`timeout`	integer	默认 `60` 秒。

不要把这里的 hooks 写成所有运行时完整 hooks 能力。它只描述 Profile schema 当前支持的事件和 handler。

内置模板

slug	用途	关键默认
`coding-assistant`	通用编码助手	`runtime: auto`，`acceptEdits`，默认模板。
`code-reviewer`	只读代码审查	只读工具，拒绝 Bash/Write/Edit，`mode: plan`。
`researcher`	多源调研	读和 Web 工具，`mode: plan`。
`security-auditor`	安全审计	只读/审计取向，拒绝写入。
`frontend-developer`	前端开发	前端任务工具面，拒绝危险删除和推送。
`documentation-writer`	文档撰写	文档编辑工具面，拒绝危险删除和推送。
`devops-engineer`	CI/CD、容器、部署	模板权限较高；复制后按任务收紧。
`pair-programmer`	结对编程	较宽工具面，适合交互式协作。

运行时映射

运行时	支持情况
`claude-code`	映射最完整。可生成 `.claude/settings.json`、`.claude/agents/jarvis-<id>.md` 和 `.mcp.json`，支持 permissions/hooks/MCP 的主要路径。
`codex`	注入 instructions、reasoning effort 和 MCP；内置工具 allowlist、细粒度 allow/deny/ask 当前不是完整映射。
`opencode`	使用通用配置映射；具体工具与权限效果取决于运行时。
`kimi-code`	使用通用配置映射；具体工具与权限效果取决于运行时。
`auto`	让 Jarvis 根据可用运行时和启动参数选择。

API 与主聊天工具

REST 入口：

路径	用途
`GET /api/v1/agent-profiles`	列出 Profile。
`POST /api/v1/agent-profiles`	创建 Profile。
`PATCH /api/v1/agent-profiles/{profile_id}`	更新 Profile。
`DELETE /api/v1/agent-profiles/{profile_id}`	删除用户 Profile。
`POST /api/v1/agent-profiles/{profile_id}/duplicate`	复制 Profile，常用于编辑 locked Profile。
`POST /api/v1/agent-profiles/{profile_id}/set-default`	设为默认 Profile。
`POST /api/v1/agent-profiles/{profile_id}/apply`	应用到运行时配置文件。
`GET /api/v1/agent-profiles/{profile_id}/preview`	预览会生成的文件和警告。
`GET /api/v1/agent-profiles/{profile_id}/lint`	校验 Profile。
`POST /api/v1/agent-profiles/import`	导入 YAML。
`GET /api/v1/agent-profiles/{profile_id}/export`	导出 YAML。
`POST /api/v1/agent-profiles/project-binding`	设置项目绑定。

主聊天可通过 manage_agent_profile 管理 Profile，常用动作包括 list、read、create、update、delete、apply、search、generate、remember、scan。

Agent Profile 参考

存储与格式

顶层字段

model

instructions

tools

permissions

skills

hooks