Requirement 共享结构

Requirement 描述对象对目标环境的外部依赖。它只能嵌入 Skill.spec.requirements[]、Profile.spec.requirements[] 或 Adapter.spec.requirements[]，不是顶层 kind。 Flow stage 与 Lifecycle Handler 的 requires 不是 Requirement：前者声明 capability 与 binding role，本页的 requirements[] 声明文件、可执行程序、MCP、凭证等环境依赖。

字段

字段	要求	Schema 语义
`id`	必填	对象内的依赖标识，使用与 `metadata.name` 相同的命名正则。
`type`	必填	九类 Requirement 之一。
`target`	必填	由 `type` 决定的目标对象；不允许目标类型之外的字段。
`optional`	可选，默认语义为 `false`	是否为可选依赖。schema 注明 default，但 validator 不会回写字段。
`origin`	可选，默认语义为 `declared`	`declared` 或 `inferred`；validator 不会回写默认值。
`reviewStatus`	`origin: inferred` 时必填	`accepted` 或 `needsReview`。
`freshness.maxAgeSeconds`	依类型必填	大于等于 1 的整数，用于动态检查证据有效期。

requirements 数组本身没有 minItems 或 uniqueItems。schema 因而允许空数组和重复 id；当前 Preflight 会把可达对象中的重复 id 记录为失败检查。

Requirement 类型

`type`	`target` 必填字段	额外约束
`objectRef`	`kind`、`name`	可选 `generation`，大于等于 1。
`localPath`	`path`、`access`	`access` 至少一项、不可重复，只能是 `read`、`write`、`execute`。
`executable`	`name`	可选 `version` 字符串。
`mcpServer`	`serverUrl`	URL 必须以 `http://` 或 `https://` 开头；必须有 `freshness`。
`mcpTool`	`serverUrl`、`name`	必须有 `freshness`。
`mcpResource`	`serverUrl`、`uri`	必须有 `freshness`。
`credential`	`env`	环境变量名匹配 `^[A-Z_][A-Z0-9_]*$`；必须有 `freshness`。
`runnerCapability`	`name`	`name` 必须是合法 capability；必须有 `freshness`。
`contextSource`	`path` 或 `url`，二选一	URL 必须是 HTTP(S) 且要求 `freshness`；本地 path 不要求 freshness。

合法示例

Requirement 必须放在所属对象内。以下是完整合法的 Skill：

apiVersion: huoban.dev/v1alpha1
kind: Skill
metadata:
  name: spec-outline-writer
spec:
  capabilities:
    - huoban.dev/specification
  requirements:
    - id: node-runtime
      type: executable
      origin: declared
      target:
        name: node
  sideEffects:
    declared:
      - readFile
      - writeFile

对应 source example：examples/skills/spec-outline-writer.yaml。

当前 Preflight 行为

Preflight 分开记录 resolution 与 readiness：前者回答目标是否明确、引用是否解析，后者回答当前环境是否可用。

类型	resolution	readiness
`objectRef`	按 kind/name/generation 查 workspace。	对象存在时为 `True`。
`localPath`	记录声明路径。	按 `access` 用文件系统权限检查。
`executable`	记录程序名或 PATH 解析。	PATH 中可执行为 `True`；声明 `version` 时不执行版本命令，结果为 `Unknown`。
`credential`	记录环境变量名。	只检查变量是否设置，不把值写入报告。
`runnerCapability`	校验 capability 目标。	没有任何 `--runner-capability` 时为 `Unknown`；有声明后按集合检查。
`contextSource` path	记录路径。	检查本地可读。
`contextSource` URL	记录动态目标。	offline 为 `Unknown`；`--live` 使用只读 `HEAD` 请求。
MCP 三类	记录完整 endpoint/member。	offline 为 `Unknown`；`--live` 做有界 discovery。

MCP live 检查会初始化 MCP session，并对 tool/resource 分别调用 tools/list 或 resources/list，最多读取 20 页，每次响应体上限为 1 MiB。它不会调用 MCP tool，也不会读取 MCP resource 内容；报告不保留 URL credential、query、fragment 或远端 error text。 Preflight 只收集当前 Run 可达的依赖：有效 Profile、被 stage 或 handler binding 选中的 Skill/Adapter，以及 Skill 关联 Adapter、Adapter 关联 Trust、Profile/Trust 关联 Policy。它不会扫描 workspace 中每个未使用对象的 Requirement。 origin: inferred 且 reviewStatus: needsReview 的依赖，其 resolution 和 readiness 都是 Unknown。optional: true 的失败或未知不阻断 gate；required 依赖的处理见 Preflight。

验证边界

schema 检查字段形状、条件必填、枚举、正则和 freshness。
huoban validate 不检查本地路径、PATH、环境变量或网络。
Preflight 不把依赖可用解释为 Policy 允许或 Trust 授权。
动态检查产生的 validUntil 只在 readiness 不是 Unknown 且存在 freshness 时生成。
任何带 source.path 的 Adapter source 必须有路径完全相同且包含 read 的 required localPath Requirement。
mcpTool source 必须有 server URL 与 tool name 完全相同的 required mcpTool Requirement。

相邻概念边界

容易混淆	精确边界
stage/handler `requires`	声明 capability 与 Run binding role。
`requirements[]`	声明具体实现或上下文的外部环境依赖。
`Adapter.spec.source`	描述 Adapter 来自哪里；只有显式 Requirement 才进入当前就绪检查。
`Policy`	决定副作用和审批边界，不描述依赖是否安装。
Preflight check	是某次 Run、某个环境对 Requirement 的证据，不是 Requirement 本身。

常见错误

写成顶层 kind: Requirement。
把 Flow.spec.stages[].requires 写成 requirements[] 的目标结构。
给 contextSource 同时写 path 和 url；该目标使用 oneOf，只能选一个。
给 URL、MCP、credential 或 runner capability 动态依赖漏写 freshness。
认为 optional 会让 schema 忽略字段错误；它只影响 Preflight gate。
认为 executable.version 已被实际探测；当前 CLI 明确返回 Unknown。

​字段

​Requirement 类型

​合法示例

​当前 Preflight 行为

​验证边界

​相邻概念边界

​常见错误

字段