spec 1.0 · 规范性

Leji 智能体配置 frontmatter

AI 智能体辅助翻译。如有出入，以英文页面为准。如果你发现文本有任何问题，欢迎提交议题或发起拉取请求。

校验一份智能体配置文档的 YAML frontmatter。markdown 正文保持自由形式。

权威 $id：https://leji.org/schemas/v1.0/agent-profile.schema.json
原始文件：agent-profile.schema.json

字段

#idstring必填

本配置的稳定标识符，例如 "core" 或 "reviewer"。

匹配模式 ^[a-z0-9]+(-[a-z0-9]+)*$

#namestring必填

该角色的人类可读名称。

#rolestring必填

本配置所担任的角色标识符，在清单的 agents 映射中绑定。

#purposestring

一句话说明这个角色是做什么的。

#versionstring

本配置的可选版本。

#inheritsstring

本配置所扩展的那一份 core 配置的 id，它的姿态数组与正文由本配置继承，按规范解析。解析只有一层：目标必须存在、唯一，并且声明 role 为 core。声明了 inherits 的配置，在基配置已提供 requiredRead 与 mustAskWhen 时可以省略它们。

匹配模式 ^[a-z0-9]+(-[a-z0-9]+)*$

#requiredRead字符串数组

本角色在执行任何任务之前加载的路径。

#defaultContext由 "domain" · "system" · "practice" · "governance" · "decisions" 构成的数组

本角色默认加载的类别。

#mustAskWhen字符串数组

本角色必须停下来向人发问的情形。

#mustRefuseWhen字符串数组

本角色必须直接拒绝、而不是发问的情形。

#escalationstring

向谁或向什么上报。

#owners字符串数组

本配置的可选负责人。

#freshnessobject

本配置的复核期限。

reviewAfterstring

ISO 8601 日期，在此之后应当复核本配置是否过期。

#hoststring

运行这个智能体的智能体宿主，例如 "claude-code"、"codex"、"cursor"。不依赖宿主的配置请省略。

#invocationobject

如何以外部 CLI 的方式启用这个智能体。宿主自带的常驻智能体请省略。

commandstring必填

从 shell 启用这个智能体的命令模板。必须携带 <prompt> 占位符，且它要作为独立的、未加引号的 shell 词出现；pattern 验证的是替换位点存在，位置则由规范来要求。

constraints字符串数组

值得让机器知道的运行约束，例如提示长度上限、超时。

Schema 与示例

Schema示例 · thought-partner.md

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://leji.org/schemas/v1.0/agent-profile.schema.json",
  "title": "Leji agent profile frontmatter",
  "description": "Validates the YAML frontmatter of an agent profile document. The markdown body stays free-form.",
  "type": "object",
  "required": [
    "id",
    "name",
    "role"
  ],
  "if": {
    "not": {
      "required": [
        "inherits"
      ]
    }
  },
  "then": {
    "required": [
      "requiredRead",
      "mustAskWhen"
    ]
  },
  "additionalProperties": false,
  "properties": {
    "id": {
      "description": "Stable identifier for this profile, e.g. \"core\" or \"reviewer\".",
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
    },
    "name": {
      "description": "Human-readable name of the role.",
      "type": "string",
      "minLength": 1
    },
    "role": {
      "description": "The role identifier this profile fills, bound in the manifest's agents map.",
      "type": "string",
      "minLength": 1
    },
    "purpose": {
      "description": "One line on what this role is for.",
      "type": "string"
    },
    "version": {
      "description": "Optional version of this profile.",
      "type": "string"
    },
    "inherits": {
      "type": "string",
      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
      "description": "id of the single core profile whose posture arrays and body this profile extends, resolved per the specification. Resolution is single-level: the target must exist, be unique, and declare role core. A profile that declares inherits may omit requiredRead and mustAskWhen where the base supplies them."
    },
    "requiredRead": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string",
        "pattern": "^(?!/)(?!\\./)(?!.*(^|/)\\.\\.(/|$))(?!.*\\\\).+$"
      },
      "description": "Paths this role loads before any task."
    },
    "defaultContext": {
      "type": "array",
      "items": {
        "enum": [
          "domain",
          "system",
          "practice",
          "governance",
          "decisions"
        ]
      },
      "description": "Categories this role loads by default."
    },
    "mustAskWhen": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string"
      },
      "description": "Conditions under which the role must stop and ask a human."
    },
    "mustRefuseWhen": {
      "description": "Conditions under which the role must refuse outright rather than ask.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "escalation": {
      "type": "string",
      "description": "Who or what to escalate to."
    },
    "owners": {
      "description": "Optional owners of this profile.",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "freshness": {
      "description": "Review horizon for this profile.",
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "reviewAfter": {
          "description": "ISO 8601 date after which the profile should be reviewed for staleness.",
          "type": "string",
          "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])$"
        }
      }
    },
    "host": {
      "type": "string",
      "description": "The agent host that runs this agent, e.g. \"claude-code\", \"codex\", \"cursor\". Omit for host-agnostic profiles."
    },
    "invocation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "command"
      ],
      "properties": {
        "command": {
          "type": "string",
          "pattern": "<prompt>",
          "description": "Command template to engage this agent from a shell. Must carry the <prompt> placeholder, standing as its own unquoted shell word; the pattern verifies the substitution site exists, placement is the spec's rule."
        },
        "constraints": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Operational constraints worth machine-knowing, e.g. prompt length limits, timeouts."
        }
      },
      "description": "How to engage this agent as an external CLI. Omit for the host's own resident agent."
    }
  }
}

一份符合规范的智能体配置。本 schema 校验的是 YAML frontmatter；下方的 markdown 正文是自由形式的散文。

---
id: thought-partner
name: Thought Partner (Codex)
role: thought-partner
purpose: 就文案、设计决定和需要判断的问题给出独立的第二意见。
host: codex
invocation:
  command: codex exec --skip-git-repo-check <prompt>
  constraints:
    - 提示要紧凑；过长的提示会让 CLI 卡住
    - 非交互式；一个提示进，一个回复出，不保留会话状态
inherits: core
requiredRead:
  - docs/boot-profile.md
mustAskWhen:
  - 结论会改变一份已记录的决策时
  - 问题涉及上下文层中尚未包含的机密材料时
---

# Thought Partner (Codex)

通过 `leji.json` 中的 `thought-partner` 角色启用，协议里绝不直呼其名。给它的简报要自成一体：相关的文案或决策、约束它的那些条件，以及确切的问题。它无法访问本仓库或它的历史；一切需要它权衡的内容都要写进提示里。

把它的结论当作一种视角。当这位伙伴与常驻智能体意见不一致时，交由一个人来定夺，并同时呈上双方的看法。

← 全部 Schema