导入 AGENTS.md

当前 CLI 原生支持单个 Markdown 文件导入为 Profile，也支持把 Profile 导出为 AGENTS.md。

AGENTS.md -> Profile -> validate / explain -> human review
                     -> optional Policy derive -> review
                     -> AGENTS.md export -> review

导入成功不代表推断正确或内容可信。生成对象包含 ImportNeedsReview=True。

运行导入

在 huoban source repo 根目录执行：

npm exec -- huoban import AGENTS.md --as Profile --out profiles/agents-profile.yaml

public example 使用：

npm run import:profile

它等价于：

node ./bin/huoban.js import examples/import/AGENTS.md --as Profile --out examples/generated/agents-profile.yaml

当前约束：

输入必须是单个可读文件，不支持目录。
--as 只接受 Profile。
--out 必填；CLI 会创建父目录。
输入 basename 决定默认对象名，例如 AGENTS.md 生成 agents-profile。

当前分层规则

importer 使用确定性的标题/文本匹配：

命中内容	目标 layer
style、coding、review、change、simplicity	`style`
command、test、verify、build、lint	`commands`
risk、safety、permission、approval、git、publish、secret	`risk`
未匹配内容	`source`

结构化值写入 data，原始规则文字保留在 content。这是规则推断，不是自然语言的完整语义证明。

完整 public 输出

下面逐字取自 source tree 的 examples/generated/agents-profile.yaml：

apiVersion: huoban.dev/v1alpha1
kind: Profile
metadata:
  name: agents-profile
  labels:
    huoban.dev/imported-from: examples/import/AGENTS.md
spec:
  layers:
    - name: style
      data:
        preferSmallChanges: true
        avoidUnrelatedRefactor: true
        testFirstForBugfixes: true
      content: |-
        Prefer small surgical changes. Do not refactor unrelated code.
        Use test-first changes for bug fixes when practical.
    - name: commands
      data:
        commands:
          - npm run validate
          - npm run explain
      content: |-
        Run `npm run validate` before finalizing schema or example changes.
        Use `npm run explain` to inspect the example workspace.
    - name: risk
      data:
        requiresApproval:
          - publishRemote
          - modifyGitHistory
          - accessSecret
        inferred: true
      content: Ask before modifying git history, publishing remote changes, or accessing secrets.
status:
  conditions:
    - type: ProfileImported
      status: "True"
      reason: ImportedFromMarkdown
      message: examples/import/AGENTS.md was converted into Profile layers.
    - type: ImportNeedsReview
      status: "True"
      reason: RuleBasedInference
      message: Structured fields were inferred by deterministic rules and should be reviewed.

examples/... 是 Huoban source repo 内的路径，不是文档站链接。

验证与解释

npm exec -- huoban validate profiles/agents-profile.yaml
npm exec -- huoban explain profiles/agents-profile.yaml

重点审查：

content 是否保留限定语。
data 是否把自然语言错误地简化成布尔值。
命令是否完整且仍适用于当前仓库。
risk side effect 是否使用当前 enum。
需要审批的规则是否应进入独立 Policy。

派生 Policy

只有存在名为 risk 的 layer，且 data.requiresApproval 为非空数组时，当前 derive 命令才能成功：

npm exec -- huoban derive policy profiles/agents-profile.yaml --out policies/agents-risk-policy.yaml
npm exec -- huoban validate policies/agents-risk-policy.yaml

生成 Policy 会带 PolicyNeedsReview=True。它不会自动绑定到 Flow/Run，也不会自行执行。

导出 AGENTS.md

npm exec -- huoban export profiles/agents-profile.yaml --to AGENTS.md --out generated/AGENTS.md

当前 export 只支持 --to AGENTS.md。输出包含结构化 YAML、原始 content 和 import conditions，并带有 Review before use 注释。生成的 Markdown 不能直接视为可信协议对象。review 是显式采用步骤；当前 CLI 不提供自动接受或 status 迁移。

开始使用

核心概念

规范参考

迁移指南

示例

标准与治理

开源项目

导入 AGENTS.md

运行导入

当前分层规则

完整 public 输出

验证与解释

派生 Policy

导出 AGENTS.md

下一步

​运行导入

​当前分层规则

​完整 public 输出

​验证与解释

​派生 Policy

​导出 AGENTS.md

​下一步

运行导入

当前分层规则

完整 public 输出

验证与解释

派生 Policy

导出 AGENTS.md

下一步