---
id: ka-knowledge-贡献规范
kind: knowledge
title: 模板贡献规范
sync_policy: engine_only
status: active
triggers:
  - 贡献
  - 新增模板
  - frontmatter
  - 新增规则
  - 新增知识
  - 软下限
  - 硬下限
extra:
  name: contribution-guide
  scope:
    - '*'
  products:
    - '*'
  category: knowledge
  version: 1.0.0
  last_reviewed: '2026-06-17'
  verification_layer: L2
  stage: _global
  owner_mechanism: mc-registry-infrastructure
---

# 模板贡献规范

> 给未来维护者（含 AI 维护者）：怎么新增/修改 md 资产。
> SoloForge 由 AI 维护，必须简单、数据驱动、配置扩展。参见 [[机制说明]]。

## frontmatter 必填四件套

每个 md 必须有：
- `id`（全局唯一）
- `kind`（artifact / guidance / enforced / knowledge）
- `sync_policy`（copy_to_project / engine_only / internal）
- `status`（active / retired）

## 选 kind 的判断

| 想达到的效果 | 用什么 kind | 关键要求 |
|-------------|------------|---------|
| AI 产出某个文档的骨架 | artifact | 放对应域目录 |
| 注入 AI prompt 的方法论/纪律 | guidance | **必须有非空 triggers，否则永不注入=僵尸** |
| 确定性门禁检查 | enforced | **必须有 gate + 非空 checks** |
| 只供搜索查阅的参考 | knowledge | 注意：**不注入运行时 prompt** |

## 软下限 vs 硬下限

- **软下限 = guidance**：注入指导，不阻断。靠 triggers 匹配 intent 注入。
- **硬下限 = enforced**：门禁检查，阻断。靠 check.gate 聚合到 *-gate 执行。

新增硬下限注意：
- check 的 `executor` 必须是已注册的（`regex_pattern_scan` / `document_structure` / `semantic`）
- 未注册 executor → fail-closed 判失败
- `regex_pattern_scan` 按行扫、不区分注释，容易误报，先想好是否该 warning 级

## 避坑清单

- guidance 没 triggers = 僵尸文件
- enforced 没 gate/checks = 僵尸文件
- knowledge 写成核心纪律 = 白写（不注入），核心纪律用 guidance
- 不要造同义字段，新增字段先查 frontmatter 字段字典
- artifact 改名要同步 domain contract 的 produces 和 CROSS_VALIDATION_ARTIFACT_PATHS 映射

## 用户自定义资产

用户在 `.soloforge/knowledge/`（项目级）或 `~/.soloforge/patterns/`（全局级）放 md（frontmatter 同内置格式），SoloForge 自动按 kind 分流：
- `kind: guidance` → 通过 `sf_knowledge action="query"` 按任务信号显式检索正文；宿主只采用与当前事实匹配的指导
- `kind: enforced` → gate 聚合执行（硬下限，按 `check.gate` 归属到对应 *-gate）
- `kind: knowledge` → sf_knowledge 索引搜索
- `kind: artifact` → 用户 asset 用 `artifact_contract` 块声明 `domain`/`artifact_kind`/`path_pattern`/`gate`/`required`，自动并入对应域 contract produces，并由证据 policy 判断是否需要完整验证；模板按文件名在 `.soloforge/knowledge/` 加载

**内置优先**：同 id 用户资产不覆盖内置。规则文件 `rule_source` 用绝对路径定位（executor resolve 兼容用户目录）。