Skip to main content
Profile 是 Huoban 的墨方：它把项目规则、领域语言、命令和历史上下文组织成可引用的 layer。Profile 不声明能力，也不代替 Policy 授权。 设计背景见 Profile 模型，外部依赖结构见 Requirement。

​
字段

layer item 本身不允许 name、data、content 之外的字段；扩展结构应放在 data 内。schema 允许一个 layer 同时包含 data 与 content。

​
合法示例

对应 source example：examples/profiles/huoban-open-source-project.yaml。

​
当前 CLI 行为

​
Import 与 export

当前 import 只支持 --as Profile。它按 Markdown heading 和关键词归入 style、commands、risk 或 source layer，并写入 ProfileImported=True 与 ImportNeedsReview=True。这是确定性规则推断，不代表生成内容可信。 当前 export 只支持 --to AGENTS.md，会输出 layer data/content 和已有 conditions，并在文件中提示 review。

​
Policy 派生

derive 读取第一个 name: risk layer 的 data.requiresApproval。该值必须是非空数组；输出一个 unknownSideEffect: requireApproval 的 Policy 和一条去重后的 requireApproval rule，并写入 PolicyNeedsReview=True。它不会自动执行该 Policy。

​
Preflight

当前 Preflight 将 Flow 的默认 profile refs 与 Run refs 按名称合并，Run 中同名引用覆盖 Flow 引用。它检查 Profile 引用/generation、Profile Requirement 和 policyRefs 是否可解析，但不计算 effective Profile，也不执行 spec.merge。

​
验证边界

  • validate 只检查 layer 形状，不解释 data 的项目私有字段。
  • schema 不要求 layer 名唯一，也不定义 layer 顺序或冲突规则。
  • spec.merge 是开放对象；当前 CLI 没有 merge 实现。
  • policyRefs 的形状合法不代表目标存在；Preflight 只检查当前 Run 可达的 Profile。
  • import/export 生成的 Markdown 或结构化推断必须 review，不能直接当作可信协议事实。

​
相邻概念边界

​
常见错误

  • 在 layer item 顶层发明字段，而不是放入 data。
  • 同时漏掉 data 和 content。
  • 把权限只写成 risk layer 自然语言，却声称已获得 Policy enforcement。
  • 声称 spec.merge 已有标准合并语义；当前 schema 和 CLI 都没有。
  • 把 import 结果直接当作可信对象，忽略 ImportNeedsReview。
  • 把 Run 的 profileRefHash 写成不存在的 profileSpecHash。