创建 Agent Profile

这份指南用一个“文档审查员”Profile 说明创建、导入、预览和应用的基本路径。它只读检查文档，不写文件，适合先验证 Profile 链路。

前置条件

Jarvis 已经运行。
至少一个编码运行时 CLI 已安装并登录。
你能打开 Studio 或 Settings / Agent Profiles。

从模板创建

打开 Jarvis UI。
进入 Studio，切到 Agent Profiles；也可以进入设置页的 Profile 管理入口。
点击新建 Profile。
选择接近任务的模板，例如 Documentation Writer 或 Code Reviewer。
修改名称、描述、模型和系统指令。
检查工具和权限，确保它不会获得不需要的写入或发布能力。
保存后点击预览，确认 Jarvis 会为目标运行时生成哪些配置文件。

内置模板适合做起点。不要直接把高权限模板用于无人值守任务；先复制并收紧工具和权限。

完整导入示例

下面是一个可导入的 YAML Profile。它面向只读文档审查，使用 plan 权限模式，并拒绝写入、删除和推送。

version: 2
name: Docs Reviewer
description: 只读检查用户文档的结构、准确性和链接风险
icon: file-search
runtime: auto

model:
  model: claude-sonnet-4-6
  fallback:
    - claude-sonnet-4
  options:
    reasoning_effort: medium

instructions:
  system_prompt: |
    You are a documentation reviewer for Jarvis user docs.
    Focus on factual accuracy, missing prerequisites, broken examples,
    unclear user-facing terminology, and unsafe instructions.
    Do not edit files unless the user explicitly asks you to.
  files:
    - AGENTS.md
  rules:
    - glob: "services/docs-site/src/content/docs/**/*.mdx"
      instruction: "Keep pages concise, user-facing, and linkable from the Starlight sidebar."

tools:
  builtin:
    - Read
    - Glob
    - Grep
  mcp_servers: {}
  deny:
    - "Write(**)"
    - "Edit(**)"
    - "Bash(rm *)"
    - "Bash(git push *)"

permissions:
  mode: plan
  allow:
    - "Read(**)"
    - "Glob(**)"
    - "Grep(**)"
  deny:
    - "Write(**)"
    - "Edit(**)"
    - "Bash(rm *)"
    - "Bash(git push *)"
  ask: []

skills: []

导入后先运行 lint 或预览。如果 Profile 包含 MCP server，env 值应写成环境变量引用，不要把真实 token 放进 YAML。

应用到单次会话

回到聊天输入区。
在 Profile 选择器中选择刚创建的 Docs Reviewer。
选择运行时，或保持 Auto。
输入一个只读任务。
启动后打开会话详情，确认模型、运行时和权限符合预期。

示例任务：

只读检查 docs-site 中新增的 Workflow 文档，指出事实错误、坏链接和示例风险。不要修改文件。

设为默认或绑定项目

Profile 有两种长期应用方式：

方式	适合场景
设为默认	你希望大多数新会话都使用同一套行为配置。
项目绑定	某个项目需要固定 Profile，例如文档仓库默认使用文档审查员。

项目绑定会在项目目录记录 .jarvis/profile。从该目录启动会话时，Jarvis 会自动读取绑定；如果单次启动显式选择了其它 Profile，则以显式选择为准。

应用到 Workflow 节点

在 Workflow 节点里设置 profile_id 后，该节点启动 worker 时会应用对应 Profile。常见搭配：

Code Reviewer Profile 用在只读审查节点；
Documentation Writer Profile 用在文档撰写节点；
Security Auditor Profile 用在安全审计节点；
高权限执行节点打开 requires_approval，先等人工批准。

常见问题

Profile 保存了，但会话没有使用它

确认启动会话时选中了 Profile，或当前目录存在正确的 .jarvis/profile 项目绑定。单次启动显式参数会覆盖部分 Profile 默认值。

预览显示冲突

Profile apply 会用 ownership manifest 保护已存在的运行时配置文件。遇到非 Jarvis 管理或用户手动修改过的文件时，Jarvis 会拒绝部分写入。先检查预览，再决定是否覆盖。

Codex 没有完全遵守工具权限

Codex Profile 当前主要映射 instructions、reasoning effort 和 MCP。内置工具 allowlist、细粒度 allow/deny/ask 不要当作完整强约束。

Skills 没有注入

当前 worker skills 注入只支持 local skills，并主要面向 Claude Code 会话。确认 skill 目录含 SKILL.md，并位于可解析路径。