feat(profile): 建立技术能力契约与校验器

2026-09-03 17:11:47 +08:00
parent f7ea0dcd86
commit 381308e04a
9 changed files with 286 additions and 0 deletions
@@ -0,0 +1,23 @@
+# Profile 契约
+
+每个提供方以 `references/manifest.json` 声明能力。清单只包含路由元数据，规则正文保存在同一 Skill 的 Markdown 文件中。
+
+必需字段包括 `schemaVersion`、`provider` 和 `profiles`。Profile 必须声明稳定 ID、版本体系、版本范围、优先级、探测证据、能力资料入口和回退入口。
+
+首期能力标识：
+
+- `project-detection`
+- `knowledge-routing`
+- `backend-design`
+- `backend-implementation`
+- `backend-testing`
+- `language-review`
+- `framework-review`
+- `command-resolution`
+
+缺少能力表示提供方不提供该能力，不能使用空文件占位。
+
+首期版本范围只支持 `*`、精确数字版本，以及用逗号连接的 `>=`、`>`、`<=`、`<`、`==` 条件。不支持并集、排除、预发布标签和生态专属通配表达式。
+
+诊断结果使用 `<plugin>:<skill>/<skill 内相对路径>` 逻辑标识。该值不能被消费者拼接为物理路径。
+
@@ -0,0 +1,10 @@
+# 提供方发现协议
+
+1. 当前会话的 Skill 清单是提供方是否可用的唯一运行时依据。
+2. 消费者请求已发现的 `<provider>:profile`，由提供方读取自己的清单和资料。
+3. 没有发现对应 Skill 时返回 `missing`，不扫描用户插件缓存。
+4. Profile 插件不维护运行时注册表，不读取其他插件目录。
+5. 新增或更新插件后的真实发现行为必须在安装后的新会话验证。
+
+仓库静态校验只能证明声明有效，不能证明插件已经安装或当前会话已经加载。
+
@@ -0,0 +1,12 @@
+# Profile 回退规则
+
+| 状态 | 条件 | 消费者行为 |
+| --- | --- | --- |
+| `available` | 提供方已发现、版本匹配且资料有效 | 加载专项资料 |
+| `generic` | 只有版本中性资料 | 使用通用资料并说明适用范围 |
+| `missing` | 提供方或能力未发现 | 继续核心通用流程并报告缺口 |
+| `incompatible` | 项目版本不在支持范围 | 禁止加载冲突资料 |
+| `ambiguous` | 模块或候选无法唯一确定 | 展示候选并请求最小必要信息 |
+| `invalid` | 清单或引用未通过校验 | 隔离该提供方并报告错误 |
+
+回退结果必须说明核心工作流仍可完成的范围，不能把缺少增强能力描述为项目缺陷。
@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://craftkit.local/schemas/profile-manifest-v1.json",
+  "title": "CraftKit Profile Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "provider", "profiles"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "provider": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "kind", "displayName"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+        "kind": { "enum": ["language", "framework", "toolchain"] },
+        "displayName": { "type": "string", "minLength": 1 }
+      }
+    },
+    "profiles": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "version", "priority", "detect", "capabilities", "fallback"]
+      }
+    }
+  }
+}
@@ -0,0 +1,20 @@
+# Profile 解析规则
+
+## 模块选择
+
+- 将目标路径和模块根转换为项目相对规范路径。
+- 选择路径前缀最长的模块根。
+- 同一目标命中多个同长度模块时返回 `ambiguous`。
+- 跨模块任务分别解析，不合并为仓库级单一 Profile。
+
+## 候选选择
+
+1. 项目已确认 `preferredProfiles` 时，先检查对应提供方是否被发现。
+2. 没有偏好时按语言、框架、版本和构建证据筛选。
+3. 优先版本范围更窄、探测证据更具体的候选。
+4. 仍有多个候选时按较高 `priority` 选择。
+5. 排序后仍不能唯一确定时返回 `ambiguous`。
+6. 没有版本匹配时，只允许加载 `*` 的版本中性 Profile。
+
+项目事实和清单冲突时保留项目事实，返回 `incompatible`，不能建议自动升级项目依赖。
+