| English | 中文 |
本规范说明登记边界和已实现行为。具体能力、依赖和清单放在工具目录及分类用法中；通用规则不列举模型、框架或技术类别。
| 对象 | 权威来源 | 实际效果 |
|---|---|---|
| 技能 | 默认 SKILL.md 文件头及正文 |
计算机操作：输入输出、依赖、步骤、脚本与验证 |
| 宿主展示 | 技能中的 agents/openai.yaml |
可选展示，不创建函数或登录 |
| 数据集 | 获取技能中的 datasets.yaml |
数据目录信息，不下载或验内容 |
| 工具 | catalog/tools/*.yaml |
已校验元数据及声明的执行支持 |
| 方法映射 | methods/index.yaml 及其方法正文 |
研究问题、学科依据、假设/范围，以及技能和真实工具映射 |
流程和请求文件不替代实现。方法中的技能路径须指向默认真实入口，工具编号必须存在。参考技能可以没有工具编号。
新技能名称使用英文小写字母、数字和连字符；工具编号使用小写字母、数字和下划线。标题供人阅读，不含个人账号、机器名、绝对路径或凭据。
历史文件头名称、数据技能编号、目录和别名可能不同。通过真实元数据和技能说明核对，不按文件夹猜测。保留公开编号，变更时明确迁移。别名不证明对应数据的范围或完整性。
遵守双语编写规范：
默认入口参与发现，译本不是第二个注册能力。独立分发时携带资源或固定版本公开链接，仓库相对引用不会自动随复制的目录提供。
责任技能声明 skill_id、layer 和仓库相对 skill_path。记录包含服务要求的编号、名称、领域和描述，并写清获取方式、来源、覆盖及逻辑缓存根。
使用 ${AIRMOSAIC_ASSETS_DIR}，不写私人映射、真实缓存清单或凭据。检查列表、详情、筛选、唯一性和引用。当前加载器不自动落实全部结构和重复编号约束，不能声称已经自动保证。
catalog/datasets/ 还作为详情查询的后备来源，仅增加后备记录不保证出现在列表。相同编号明确权威声明，避免漂移。
每项工具一个声明文件，使用结构定义。列表查询声明是真实示例。
| 字段 | 要求 |
|---|---|
schema_version、tool_id |
支持的版本，目前为 1；稳定唯一编号 |
title、description、category、skill_id、owner_role |
公开用途、分类、真实技能与维护角色 |
implementation_status、registration_status |
如实说明实现、模板或参考及登记状态 |
entrypoint |
真实相对路径和受支持类型，按需声明命令模块及子命令 |
input_schema、argument_bindings |
字段与旗标或位置绑定一致，不接受任意命令代码 |
default_arguments |
经审查的默认值，结构化查询使用声明格式 |
output_schema |
预期响应或产物，不声称原脚本都是服务 |
requirements |
依赖、程序、非秘密配置、固定资源及人工检查 |
authentication、effects |
逻辑认证方式及读写联网副作用，不含秘密或真实配置路径 |
documentation |
存在的分类用法文档 |
execution |
启用状态、适配器与路径角色和审查策略一致 |
加载器拒绝未知字段、重复键或编号、缺少绑定、不支持版本、不安全路径及外部结构引用。只有声明不能执行任意代码，还需审查允许清单、资源路径输入结果检查，以及有效合成测试。模板和参考保持禁用。
任务文件只含参数，不含工具外壳。执行入口另传工具编号，可先补齐输出字段再校验。调用方结构快照是说明，不是登记权威，应与示例同步。人工计划明确不可执行，不虚构动作。
新增工具先限定真实动作、核对解析器，声明副作用和认证；再校验目录、查看详情和状态、测试正常及拒绝输入、更新用法并审查隐私。资源检查限定在明确配置根下的固定相对位置。就绪状态按成员环境检查，不提交个人登录或依赖状态。
技能目录是源码来源。按路径读取，或安装、链接到宿主支持的位置；核对冲突，不覆盖个人技能。项目没有自动安装器，不能假定任意源码目录会自动发现。
在真实宿主核对名称和调用。展示信息可设置名称、简述和默认提示，不创建函数、不登录、不启动服务。分发携带资源并跟踪版本。
目前仅实现文档声明的 CLI/MCP 发现与经审查执行路径，其他服务传输或适配器需单独实现。未来接口须先实现真实列表与调用、输入结果检查、错误和授权，再展示可调用工具。元数据和行为提示不强制落实权限；参考文件和未适配模板不得作为执行函数。
依据分类和真实声明展示用途、入口类型、实现、当前环境及下一步，明确模板、参考和规划能力。
实现状态、证据与当前就绪分别管理。状态值以加载器真实响应为准，不虚构枚举，不将登记等同就绪。源码审查、合成小样、集成和科学验证分别记录日期与证据。
详情包括调用、字段、单位、依赖、认证、读写联网范围、失败和验证。公开展示使用逻辑路径，完整路径只留在授权本地界面。现有命令、结构化结果与文档导航不表示工具面板、安装器或额外服务已经实现。
适配器需要嵌套任务设置时，可将已审查参数绑定为 configuration_file。它沿用参数文件边界：仅允许明确选择的非秘密配置、数据/结果目录或公共配置示例下的 JSON，不读取认证目录或自动加载个人配置。执行前按专项结构校验并固定快照，未知字段与重复键拒绝，公共回执不包含配置值。新增路径角色仍须同时更新结构、允许清单、执行器及测试，不能只靠清单启用。
CapabilityCatalogService 从 methods/index.yaml、catalog/skills.yaml、默认 SKILL.md 和 catalog/tools/*.yaml 派生一个公共视图，不维护第二套能力清单。科学方法在方法索引中登记一次，明确映射默认技能路径与真实工具编号；没有科学方法的操作技能可加入 catalog/skills.yaml 的有限公共引用。未引用的目录不会自动发现。workflows 组合操作，projects 定义具体研究，assets 经人审后才成为选定数据产品；这些都不是执行注册。
python -m runtime.cli validate-capabilities
python -m runtime.cli list-capabilities
python -m runtime.cli describe-capability method statistical_yearbooks
python -m runtime.cli describe-capability skill machine-learning-model
CLI 与 MCP 的 airmosaic://catalog/capabilities 共用该服务；airmosaic://catalog/methods 和 airmosaic://catalog/skills 分别展示方法、技能和精确文档资源地址。技能入口明确链接的本目录 Markdown 指南另列为有数量限制的一层 supporting_documents，不扫描未声明目录树。服务重启时刷新快照，CLI 每次查询刷新。SHA256 指纹标识当前公共正文，未声明版本仍为 not_declared。
方法可选结构化字段为 research_question、disciplinary_basis、assumptions、applicability、implementation、scientific_evidence；技能在文件头 metadata 中可声明相同字段及 version。既有正文通过链接提供，不复制成另一套声明。结构化字段缺失时标 not_declared，即使正文已有相关说明；服务提供章节标题帮助定位。declared、source_checked、synthetic_verified、real_integration、scientific_review 表示不同证据主张，任何级别的声明都不等于发现服务独立核验；原有 evidence 作为未验证的 evidence_claim 返回。
视图列出真实工具入口及其实现、注册声明。registered_tools_present 仅表示技能至少关联一个已启用工具，不能推断全部分支可执行。documented_scripts 仅列默认正文明确引用的脚本路径、文件是否存在及精确匹配的已启用工具编号；无匹配工具的直接脚本仍未注册。登记时不打开、导入或执行脚本；缺少可选依赖不阻止文档发现，也不构成科学就绪声明。执行就绪保持 not_checked，科学验收保持 not_assessed，元数据校验只证明一致性。具体适配器仍使用 check-tool 和已授权 run-tool；阶段 02 执行限制不变。
校验拒绝方法/技能重复编号、重复 YAML 键或别名、不存在的工具映射、缺失公共文档、不安全仓库相对路径、链接/重解析位置、嵌套 Git 仓库及超大文件。读取只限索引明确列出的公共命名空间和精确资源地址，不扫描真实数据、个人配置或凭据。发现注册不授予执行权限，不改变启动、网络或浏览器授权。