接口契约速查

4 类核心契约的快速参考。详细原理见 PRD v3.1 (internal) §7-§11 (架构 / 流程 / 评委 / 数据来源 / 5 类契约)。本文档与 PRD 冲突时, 以 PRD 为准。
v2.7 (2026-05-26) 新增: failure-card 也成正式契约 (见 ../schemas/failure-card-schema.json), 6 类自动分类由 ../scripts/classify_failure.py 实现, 测试 ../tests/unit/test_failure_classifier.py。

1. SKILL.md frontmatter 契约

每个 Skill 文件 (skills/*/SKILL.md) 必须以 YAML frontmatter 起头:

yaml

---
name: &lt;slug&gt;                          # 必填, 与父目录名一致
description: |                        # 必填 ≥ 30 字
  详细描述, 影响 Skill router 路由质量
allowed-tools:                        # orchestrator 必填; 评委 Skill 必填
  - Read
  - Write
  - mcp__sage-wiki__query

boss:                              # 本项目扩展, 推荐
  schema_version: "1.0"
  skill_class: orchestrator | judge | meta | source-adapter
  quality_tier: high | normal | experimental
  sensitivity: public | internal | confidential
  
  # 评委 Skill 必填:
  judge_category: anchor | dimension
  doctrine_basis:                     # dimension 评委必填
    - references/doctrine/X.md
  research_basis:                     # anchor 评委必填
    - references/research/X.md
  
  # 可选:
  anti_fabrication:
    - "不允许编造 X"
    - "不替锚点说未说过的话"

# meta 类带定时:
schedule: "0 9 * * *"
---

校验:

bash

python scripts/skill_lint.py validate-skill skills/&lt;name&gt;/SKILL.md

2. case.json 契约 (ATELIER 6 字段)

cases/<case_id>/case.json 是判断的输入主文件。Schema 在 schemas/case-schema.json。

json

{
  "case_id": "C-2026-0001",
  "brand_slug": "example-b2b-client-strategy",
  "version": 1,
  "created_at": "2026-05-26T10:00:00+08:00",
  "owner": "项目主理",
  "sensitivity": "internal",

  "context": {
    "trigger_event": {
      "named_event": "某 B2B 客户的战略议题示例 (具体: 5/26 投委议题)",
      "time": "2026-05-26",
      "source": "internal:investment-committee-2026-Q2"
    },
    "stakeholders": ["锚点", "项目主理", "CTO"]
  },

  "thesis": {
    "central_claim": "建议剥离 X 业务",
    "rationale": "依据 PEST / 5 Forces / customer-JTBD 综合判断"
  },

  "evidence": [
    {"point": "市场份额下滑 12% YoY", "source": "_wiki/entities/example-b2b-client.md"},
    {"point": "客户 NPS 跌至 28", "source": "raw/clippings/2024-Q2-report.md"}
  ],

  "counter_arguments": [
    {
      "claim": "剥离会影响品牌完整性",
      "weight": 0.4,
      "addressed_in": "section-counterposition"
    }
  ],

  "attribution": {
    "checkpoints": [
      {"horizon_days": 30, "metric": "...", "threshold": "..."},
      {"horizon_days": 90, "metric": "...", "threshold": "..."},
      {"horizon_days": 365, "metric": "...", "threshold": "..."}
    ]
  },

  "handover": {
    "decision_owner": "锚点 + 投委",
    "decision_deadline": "2026-06-30"
  }
}

关键不变量:

case_id 格式严格: C-YYYY-NNNN
brand_slug 仅 [a-z0-9-]+
context.trigger_event.named_event ≥ 10 字符 (Phase 1 Step 1.3 阻断)
attribution.checkpoints 至少 3 条 (30 / 90 / 365)
sensitivity 枚举: public / internal / confidential / tian_only

校验:

bash

python -c "
import jsonschema, json
schema = json.load(open('schemas/case-schema.json'))
jsonschema.validate(json.load(open('cases/C-2026-0001/case.json')), schema)
"

3. 评委 Review frontmatter 契约

每个评委 sub-agent 输出 reports/<brand>/reviews/<judge>.md:

yaml

---
judge: industry-trend                       # 必填, 与 Skill 名一致
judge_display_name: 行业趋势评委
judge_category: anchor | dimension          # 必填
brand_slug: &lt;brand&gt;
case_id: C-YYYY-NNNN
version: &lt;int&gt;
reviewed_at: <ISO 8601>

scores:                                     # 5 镜头, 各 1-10
  reasoning_soundness: 7
  evidence_thesis_coupling: 6
  counter_position_treatment: 5
  falsifiability: 8
  real_world_resilience: 6

confidence: 0.72                            # 0-1

# dimension 评委必填:
doctrine_anchors:
  - references/doctrine/X.md
adversarial_view:                           # ⚠️ 三字段全部非空, skill_lint 强制
  if_thesis_wrong: <非空字符串>
  contrary_signal_observed: <非空字符串>
  base_rate_warning: <非空字符串>

# anchor 评委 (tian) 必填:
research_anchors:
  - anchors/tian/raw/interviews/X.md
# anchor 评委不必填 adversarial_view (但可填), 因为它本身就是"基准点"

# 共同字段:
wiki_entities_referenced:
  - _wiki/entities/X.md
---

## 一句话
## 关键缺口
## (dimension only) Adversarial View
## 行动建议
## Anti-fabrication 声明

校验:

bash

python scripts/skill_lint.py validate-review reports/&lt;brand&gt;/reviews/&lt;judge&gt;.md

4. 飞书抓取工具落盘契约

由 scripts/feishu_sync_filter.py 写入 anchors/tian/raw/feishu-sync/<kind>/:

yaml

---
source: feishu-sync                          # 固定值
upstream_id: &lt;feishu_doc_token&gt;              # 飞书原 token
upstream_url: <https://...feishu.cn/...>     # 可点击 link
upstream_type: docx | docs | sheets | wiki | minutes | vc | drive | media
fetched_at: <ISO 8601>
fetched_by_sync_version: via-filter
title: <原文档标题>
sensitivity: confidential | tian_only
language: zh | en
content_hash: <sha256 64 hex chars>

# 可选 (从 飞书抓取工具 manifest 解析):
author: <人类可读名>
author_resolved: "[[_wiki/people/锚点]]"
participants: [<姓名列表>]
participants_resolved: [<Wiki link 列表>]
duration_minutes: <int, 仅 meetings>

# v3.3 过滤层产出:
feishu_sync_filter:
  tian_score: 0.0 - 1.0
  match_channels:
    - structural:author_user_id=ou_xxx
    - text:锚点(title=1,body=4,excludes=0)
    - llm:reason(0.50)
  filtered_at: <ISO 8601>
---

# 标题

正文 Markdown...

校验:

bash

python scripts/feishu_sync_ingest.py validate anchors/tian/raw/feishu-sync/&lt;file&gt;.md

5. panel.yaml 契约

panels/default.yaml 与 reports/<brand>/panel.yaml 共享 schema:

yaml

name: default
display_name: V0 默认 panel (锚点 anchor + 6 维度评委)

judges:
  - slug: tian
    judge_category: anchor
    always_active: true
    skill_path: anchors/tian/perspective/SKILL.md
  - slug: industry-trend
    judge_category: dimension
    skill_path: skills/industry-trend-perspective/SKILL.md
  # ... 其他 5 个 dimension

auto_judge_selection:
  default_include: [tian]                    # anchor 永远在
  default_dimension_count: 4                 # 默认 4 个 dimension
  rules:
    strategic: [industry-trend, strategic-vision, financial-strategy, org-strategy]
    product:   [industry-trend, product-strategy, customer-strategy, financial-strategy]
    # ... 其他议题类型

adversarial_mechanism:
  type: distributed                          # v3.1 锁定
  required_field: adversarial_view

merge_rules:
  dimension_weighted_mean: true
  anchor_tian_separate: true
  anchor_delta_required: true
  anchor_delta_threshold: 2.0

场景 panel 扩展: 场景内 scenes/<slug>/panel.yaml 可加 output_format 指定产出形态 —— op2_6section (打分报告, 默认) / workshop_ranking (排名榜) / meeting_summary (定性会议总结 deck)。见多场景评委体系与技术参考 §2.6。

6. _wiki/log.md 追加契约

只追加, 不修改:

markdown

## [YYYY-MM-DD] &lt;source&gt; | &lt;action&gt;

简短描述

例:

## [2026-06-02] feishu-sync-filter | examined=15, passed=8, review=2, skipped=5
## [2026-06-03] judgement | example-b2b-client-strategy v1, anchor_delta=1.4

不变量速查 (来自 v3.1 实施手册 §1.4)

#	不变量	强制
I-1	`reports/<brand>/versions/v{n}_*.md` 不可变	git pre-commit hook
I-2	Wiki ↔ MBA 单向引用 (link, 不复制)	skill_lint boundary check
I-3	sage-wiki ignore 列表严格遵守	config.yaml
I-4	5 镜头 × 6 评委 × 7 调研三层不混淆	CLAUDE.md §5 + review
I-5	评委不读其他评委 review	tool whitelist
I-6	Phase 1 触发事件三要素具象	orchestrator Step 1.3
I-7	dimension review 必填 adversarial_view 三字段	skill_lint
I-8	任何出站经 redact_check fail-close	git pre-commit + Hermes outbound
I-9	飞书抓取工具落盘文件 sensitivity 默认 confidential	filter + ingest
I-10	anchor_delta 是数据不是判决	Phase 5 Lead Merge

修改任何契约需 CTO + 项目主理双人 review (走 git PR)。

接口契约速查 ​

1. SKILL.md frontmatter 契约 ​

2. case.json 契约 (ATELIER 6 字段) ​

3. 评委 Review frontmatter 契约 ​

4. 飞书抓取工具 落盘契约 ​

5. panel.yaml 契约 ​

6. _wiki/log.md 追加契约 ​

不变量速查 (来自 v3.1 实施手册 §1.4) ​

接口契约速查

1. SKILL.md frontmatter 契约

2. case.json 契约 (ATELIER 6 字段)

3. 评委 Review frontmatter 契约

4. 飞书抓取工具落盘契约

5. panel.yaml 契约

6. _wiki/log.md 追加契约

不变量速查 (来自 v3.1 实施手册 §1.4)