# 接口契约速查 (api-contracts.md) > 4 类核心契约的快速参考。详细原理见 [`prd-v3.1.md`](../docs/internal/prd-v3.1.md) §7-§11 > (架构 / 流程 / 评委 / 数据来源 / 5 类契约)。本文档与 PRD 冲突时, 以 PRD 为准。 > > **v2.7 (2026-05-26) 新增**: failure-card 也成正式契约 > (见 [`../schemas/failure-card-schema.json`](../schemas/failure-card-schema.json)), > 6 类自动分类由 [`../scripts/classify_failure.py`](../scripts/classify_failure.py) > 实现, 测试 [`../tests/unit/test_failure_classifier.py`](../tests/unit/test_failure_classifier.py)。 --- ## 1. SKILL.md frontmatter 契约 每个 Skill 文件 (`skills/*/SKILL.md`) 必须以 YAML frontmatter 起头: ```yaml --- name: # 必填, 与父目录名一致 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//SKILL.md ``` --- ## 2. case.json 契约 (ATELIER 6 字段) `cases//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//reviews/.md`: ```yaml --- judge: industry-trend # 必填, 与 Skill 名一致 judge_display_name: 行业趋势评委 judge_category: anchor | dimension # 必填 brand_slug: case_id: C-YYYY-NNNN version: reviewed_at: 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//reviews/.md ``` --- ## 4. laotian 落盘契约 由 `scripts/laotian_filter.py` 写入 `anchors/tian/raw/feishu-laotian//`: ```yaml --- source: laotian # 固定值 upstream_id: # 飞书原 token upstream_url: # 可点击 link upstream_type: docx | docs | sheets | wiki | minutes | vc | drive | media fetched_at: fetched_by_laotian_version: via-filter title: <原文档标题> sensitivity: confidential | tian_only language: zh | en content_hash: # 可选 (从 laotian manifest 解析): author: <人类可读名> author_resolved: "[[_wiki/people/锚点]]" participants: [<姓名列表>] participants_resolved: [] duration_minutes: # v3.3 过滤层产出: laotian_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: --- # 标题 正文 Markdown... ``` 校验: ```bash python scripts/laotian_ingest.py validate anchors/tian/raw/feishu-laotian/.md ``` --- ## 5. panel.yaml 契约 `panels/default.yaml` 与 `reports//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 ``` --- ## 6. _wiki/log.md 追加契约 只追加, 不修改: ```markdown ## [YYYY-MM-DD] | 简短描述 ``` 例: - `## [2026-06-02] laotian-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//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 | laotian 落盘文件 sensitivity 默认 confidential | filter + ingest | | I-10 | anchor_delta 是数据不是判决 | Phase 5 Lead Merge | 修改任何契约需 CTO + 项目主理 双人 review (走 git PR)。