Profile 模型

Profile 是 Huoban 的墨方：把团队规则、项目结构、领域语言、历史决策和判断偏好，从散落的规则文件、项目文档和聊天上下文中拆出来，变成可分层、可合并、可审查、可引用的标准对象。它不改变 Skill 本身，但会改变同一个 Skill 在不同项目中的判断重点。换成活字印刷术的比喻，Skill 是活字，Profile 是墨方：同一枚字放进不同墨方，最终印出的语气、边界和判断标准会不同。本页属于核心概念，解释 Profile 的设计边界和使用模型；字段级定义、必填项和 schema 约束见 Profile 规范。

上下文对象

把 AGENTS.md、CLAUDE.md、Cursor Rules、团队规范和项目知识升级为跨工具上下文对象。

分层合并

用 layer 表达 style、architecture、domain、testing、history 和 riskSignals 等上下文部件。

保留原文

导入现有上下文时保留自然语言原文，让结构化结果可以被审查和修正。

不替代 Policy

Profile 提供判断语境；权限、审批和副作用边界必须进入 Policy。

显式来源依赖

外部上下文文件或 URL 通过 requirements[] 声明，并在执行前由 Preflight 检查。

Profile 不是普通规则文件

现有生态里已经有很多上下文文件：

AGENTS.md
CLAUDE.md
Cursor Rules
项目 prompt 文档
团队 coding guidelines

这些文件通常是单文件、自然语言、工具特定或项目特定的。 Huoban 不替代这些入口。它把这些上下文资产升级为协议对象：可分层、可合并、可校验、可导入导出，并能进入 Run 的审查链路。更准确地说，AGENTS.md、CLAUDE.md 和 Cursor Rules 是上下文入口；Huoban Profile 是跨工具的上下文对象。前者可以继续存在，后者负责进入标准对象模型。这也是 Profile 和工具私有 skill / rule / memory 的核心差异：它不是某个工具内部的 prompt 配置，而是可以被支持 Huoban 的工具链解析、传递，并被 Flow / Run 引用的标准上下文层。中文活字并不是一整块不可拆的图案。字形背后有偏旁、部首、结构和组合规则。Profile 也不应该是不可拆分的 prompt 文本，而应该拆成可以独立识别、组合、润墨和审查的上下文部件。

data 与 content

Profile 的每个 layer 至少包含 data 或 content。二者可以同时存在，但不是同时必填。

apiVersion: huoban.dev/v1alpha1
kind: Profile
metadata:
  name: huoban-open-source-project
spec:
  layers:
    - name: architecture
      data:
        architectureStyle: spec-first
        objectModel: declarative-resource
      content: |
        Prefer defining API objects before adding execution behavior.
        Keep the public standard separate from company-specific practice.

二者同时存在时，职责不同：

字段	面向谁	作用
`data`	工具、校验器、explain、后续派生流程	承载可合并、可 diff、可审查的结构化上下文。
`content`	agent / LLM / 人类 reviewer	承载自然语言背景、判断理由和暂时无法结构化的知识。

能结构化的进入 data；需要语义解释、历史背景或判断理由的进入 content。导入 AGENTS.md、CLAUDE.md 或 Cursor Rules 时，不能因为抽取出了 data 就丢掉原文；同时，只有 content 或只有 data 的 layer 仍然是合法 Profile。

Layer

Profile 使用 layer 表达上下文分层。常见 layer：

style：代码风格、改动粒度、测试习惯。
architecture：模块边界、依赖规则、设计约束。
domain：业务术语、不变量、合规要求。
commands：项目常用命令和验证方式。
testing：测试策略、覆盖要求、fixture 习惯。
history：ADR、历史迁移、拒绝过的方案。
riskSignals：风险语境、敏感路径、需要额外注意的判断信号。
policyDerivationNotes：可用于派生 Policy 的提示，但不直接代表权限规则。

这些 layer name 是约定示例，不是 v1alpha1 的保留词。实现可以定义自己的 layer name，但不能把 Profile layer 直接执行成权限规则。示例：

spec:
  layers:
    - name: style
      data:
        preferSmallChanges: true
        testFirstForBugfixes: true
      content: |
        Prefer surgical changes. Do not refactor unrelated code.
    - name: architecture
      data:
        boundaryStyle: ports-and-adapters
      content: |
        Domain logic should not depend on infrastructure adapters.
    - name: riskSignals
      data:
        sensitiveAreas:
          - publishing
          - credentials
      content: |
        Changes that publish remote state or touch credentials require extra review.

riskSignals 可以提醒 agent 如何判断风险，但“能不能写文件”“是否需要审批”“是否允许发布远端变更”必须由 Policy 决定。

上下文内容与来源依赖

layers 保存进入上下文的结构化数据或原文；requirements[] 声明生成或使用这些层之前必须可用的外部来源。二者不能混为一谈。

spec:
  layers:
    - name: architecture
      content: |
        Prefer defining API objects before runtime behavior.
  requirements:
    - id: repository-guidance
      type: contextSource
      origin: declared
      target:
        path: examples/import/AGENTS.md

contextSource 只记录文件或 URL 在该次检查时是否可访问，不把来源内容自动注入 layer，也不代表内容可信。导入、合并和 review 仍是独立步骤；URL 来源还必须声明 freshness。详见 Requirement 与 Preflight。

多 Profile 合并

一个 Run 可以使用多个 Profile：

profileRefs:
  - name: global-style
  - name: project-context
  - name: strict-review-profile
  - name: run-overrides-profile

reference implementation 可以采用以下推荐合并行为：

按数组顺序应用。
后者覆盖前者的同名 scalar 字段。
list 字段可以默认 append，但 replace / override 等策略必须由实现或后续规范明确声明。
同名 layer 可以合并。
冲突应写入 status.conditions 或 explain 输出，而不是静默吞掉。
最终 effective profile 应可解释；实现如果计算内容 hash，必须公开算法和证据位置。

这些是当前阶段的推荐合并语义，不是 v1alpha1 已经强制定义的字段级算法。Profile schema 已经提供 spec.merge 扩展点，但并未把所有字段级冲突策略都写死为协议行为；公开实现应在 explain 输出里暴露实际采用的合并策略。

Flow 与 Run 中的 Profile

Flow 可以声明默认 Profile：

# Flow spec fragment
profileRefs:
  - name: project-profile

Run 可以覆盖或追加 Profile：

# Run spec fragment
profileRefs:
  - name: project-profile
  - name: strict-review-profile

Flow 的 profileRefs 是编排默认上下文入口。Run 的 profileRefs 是一次执行实际声明的上下文集合；reference Preflight 以名称合并默认引用和 Run 引用，同名 Run 引用覆盖 Flow 默认引用。 Run.spec.snapshot.profileRefHash 只散列引用列表，不是 effective Profile 内容 hash。内容级不可变性需要 generation、外部内容寻址存储或实现明确声明的额外证据。不要把长期上下文、一次执行状态和产物都塞回 Profile。

Profile 与 Policy 的边界

Profile 影响 agent 判断，Policy 决定行为边界。不要把权限规则混进 Profile。比如“这个项目偏好小改动”属于 Profile；“写文件需要审批”属于 Policy。正确关系：

# Profile spec fragment
policyRefs:
  - name: standard-human-checkpoint-policy

Profile 可以引用 Policy，但不要和 Policy 混成同一个对象。Profile 可以保存风险语境或 policy 派生提示；真正的权限、审批、副作用边界必须由 Policy 承担。

Import / Export

Profile 是 Huoban 的关键采用路径。

huoban import AGENTS.md --as Profile --out profiles/project.yaml
huoban explain profiles/project.yaml
huoban validate profiles/project.yaml
huoban export profiles/project.yaml --to AGENTS.md --out AGENTS.md

导入时必须保留原始文本，不能为了结构化而丢失上下文。由 Markdown、聊天记录或工具规则自动生成的 Profile 不能直接视为可信协议对象；进入正式 Flow / Run 前，需要经过 review、explain 和 validate。

不承载运行态

Profile 只承载可复用上下文，不承载一次执行的运行状态。

对象	承担内容
`Profile`	长期上下文、项目语境、团队判断偏好。
`Flow`	capability-first 的任务编排。
`Run`	一次锁定执行的对象引用、bindings、snapshot 字段和状态索引。
`Checkpoint`	人或系统的判断边界。
`Artifact`	执行产生的产物和审查材料。

如果把运行结果、checkpoint 决策、错误、耗时和产物都塞进 Profile，Profile 会退化成不可合并、不可复用、不可审查的上下文堆积层。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

Profile 模型

上下文对象

分层合并

保留原文

不替代 Policy

显式来源依赖

Profile 不是普通规则文件

data 与 content

Layer

上下文内容与来源依赖

多 Profile 合并

Flow 与 Run 中的 Profile

Profile 与 Policy 的边界

Import / Export

不承载运行态

上下文对象

分层合并

保留原文

不替代 Policy

显式来源依赖

​Profile 不是普通规则文件

​data 与 content

​Layer

​上下文内容与来源依赖

​多 Profile 合并

​Flow 与 Run 中的 Profile

​Profile 与 Policy 的边界

​Import / Export

​不承载运行态

Profile 不是普通规则文件

data 与 content

Layer

上下文内容与来源依赖

多 Profile 合并

Flow 与 Run 中的 Profile

Profile 与 Policy 的边界

Import / Export

不承载运行态