AGENTS.md@.github/contracts/fate git:20261025.3c17b73A

Immutable. This exact content never changes and is served at /api/v1/blob/cec5018a1cd5f667.

# AGENTS.md - .github/contracts/fate

## 目录用途

`.github/contracts/fate/` 存放 FateCat 测算基础设施的能力协议、字段、profile、权重和规则深度契约，是输出字段口径的配置真相源。

## 目录结构

```text
.github/contracts/fate/
├── AGENTS.md
├── capabilities/
│   ├── registry.json
│   ├── errors.json
│   ├── schemas/
│   └── profiles/
├── control-plane/
│   ├── registry.json
│   └── schemas/
├── audit/
│   ├── current-bundle.json
│   ├── dry-run.json
│   ├── handoff.json
│   └── AGENTS.md
├── data-supply-chain/
│   ├── registry.json
│   └── schemas/
├── delivery/
│   ├── multi-surface-semantic-diff.json
│   ├── registry.json
│   └── schemas/
├── developer/
│   ├── api-changelog.json
│   ├── developer-portal.json
│   ├── developer-platform.json
│   ├── sandbox-output-snapshot.json
│   ├── sandbox-token-contract.json
│   ├── sdk-release-baseline.json
│   ├── sandbox.json
│   └── AGENTS.md
├── discovery/
│   ├── AGENTS.md
│   └── query-set.json
├── evaluations/
│   ├── registry.json
│   └── schemas/
├── locations/
│   ├── registry.json
│   └── schemas/
├── observability/
│   ├── registry.json
│   └── schemas/
├── security/
│   ├── registry.json
│   ├── retention-cleanup.json
│   └── schemas/
├── classics_rule_index.json
├── evidence-coverage-baseline.json
├── evidence-coverage-trend-contract.json
├── evidence_schema.json
├── future_features.json
├── rule_depth_registry.json
├── weight_policy.json
└── profiles/
    └── pure_analysis.json
```

## 职责边界

- `capabilities/`：统一测算能力协议与注册表；默认能力只能是 `bazi`，其他体系必须独立输出或保持 planned。
- `capabilities/registry.json` 的每个能力必须声明 `maturity`、`engine.engineVersion`、`evidencePolicy` 和 `testGate`；这些字段是测算基础设施成熟度、可复现计算和发布门禁的审计入口。
- `capabilities/errors.json`：标准错误码字典，服务层只负责读取和映射，不在业务代码里另起一套错误事实源。
- `control-plane/`：控制面资源对账契约；把 Capability、Provider、ReleaseGate、EvaluationRun 纳入统一 spec/status/admission/drift 视图，只做发现和对账，不保存运行结果或生产凭证。
- `control-plane/registry.json`：登记控制面资源来源、期望状态、准入策略、验证命令和当前状态口径；最终发布证明仍由 `current-release-proof` 等外部 gate 生成，不写回该 registry。
- `discovery/`：公开发现与 GEO 效果验证契约；只定义稳定采样问题、预期事实、官方来源和禁止声明，不保存平台答案或伪造指标。
- `audit/`：第三方审计交接契约；只登记 audit handoff bundle 输出结构、证据来源和外部待验证项策略，不保存真实生产证据或用户报告正文。
- `audit/handoff.json`：审计包 generator 的机器真相源；要求 Markdown/JSON 输出完整列出 tracked 和 untracked non-ignored `外部连通验证待执行` occurrence。
- `audit/dry-run.json`：审计包 dry-run verifier 的机器真相源；要求本地预检结构完整，同时在外部 live 证据缺失时保持 ship gate blocked。
- `audit/current-bundle.json`：当前 commit 审计证据包机器真相源；要求聚合 release proof、audit handoff、dry-run、release artifacts、rollback drill、evidence index、risk register 和 pending external validations，并在 required 模式拒绝不完整当前发布证据。
- `data-supply-chain/`：数据、典籍、vendor、benchmark 与导出边界注册表；只登记来源、分层、许可状态、usageRole、productionEligibility、exportPolicy 和验证命令，不保存原始大文件。
- `data-supply-chain/registry.json`：登记 raw/canonical/derived/reference/runtime/export 分层资产；`review_required`、`source_archive_only`、`evaluation_only` 和 `reference_only` 不得被文档写成默认生产输入。
- `delivery/`：多端交付资源注册表，登记 DeliverySurface，只做 FastAPI/Web/Bot/CLI/Skill/HF Space 的入口、同源链路、输出契约和验证边界说明，不保存用户输入或运行态报告。
- `delivery/registry.json`：登记 available/partial/manual surfaces；partial surface 必须说明同源范围和未覆盖输出边界。
- `delivery/multi-surface-semantic-diff.json`：标准 Markdown 多交付面语义一致性 gate 契约；只证明本地 API/Web/Bot dry-run normalized hash 同源，不证明真实 Bot/HF/公网 live。
- `developer/`：开发者接入契约、SDK/package baseline、sandbox fixture、sandbox token contract 与 API changelog；只保存本地可验证的北京/测试样本和发布边界，不保存真实 token、生产 URL、报告正文或真实用户数据。
- `developer/developer-platform.json`：开发者平台机器真相源；登记 OpenAPI、SDK/package baseline、sandbox、API changelog 与 validation gate，不代表 SDK 已发布。
- `developer/developer-portal.json`：开发者门户机器真相源；登记本地 portal release baseline、入口、机器契约和外部未上线边界，不代表公网门户上线。
- `developer/sdk-release-baseline.json`：SDK release-readiness manifest；登记 package candidates、local smoke 和未来 registry publish 证据要求。
- `developer/sandbox-output-snapshot.json`：sandbox 固定输出 hash 与结构断言；只保存脱敏摘要，不保存完整响应正文。
- `developer/api-changelog.json`：API 兼容策略和变更记录；公开 breaking change 必须登记迁移说明和兼容窗口。
- `developer/sandbox-token-contract.json`：未来公网 sandbox token 的 claim/scope/rate-limit/revocation contract；当前不发行真实 token。
- `developer/sandbox.json`：开发者文档 smoke 与 SDK 示例的固定输入源；它不是公网 sandbox token 服务。
- `evaluations/`：评测资源注册表，登记 Dataset 与 EvaluationRun，只做发现、审计和发布门禁说明，不保存运行时评测结果库。
- `evaluations/registry.json`：登记 golden fixture、benchmark 和本地评测运行入口；evaluation-only 数据不得被 production provider 当成业务输入。
- `locations/`：出生地点、稳定 ID、WGS84、IANA 时区、时间口径与 DST 歧义处理契约；数据实体仍归 `.github/domains/fate-analysis/data-products/locations/`。
- `observability/`：观测资源注册表，登记 ObservabilitySignal，只做 health、ready、metrics、logs、trace/SLO/alert 的发现和边界说明，不保存运行时观测数据。
- `observability/registry.json`：登记 available/planned signals；planned 信号不得被文档写成生产已验证能力。
- `security/`：安全、隐私与发布门禁资源注册表，登记 SecurityControl，只做 token/CORS/限流/请求体/响应头/隐私扫描/source hygiene/release gate/production readiness 的发现和边界说明，不保存真实凭证。
- `security/registry.json`：登记 available/manual controls；需要真实域名、真实 token、Bot live smoke 或云端权限的控制必须标注外部连通验证待执行。
- `security/retention-cleanup.json`：登记本地 SQLite retention cleanup baseline 的命令、summary、smoke 与脱敏边界；不代表生产 scheduler、生产数据库或外部 SIEM retention 已验证。
- `future_features.json`：记录不再进入标准报告、后续需按新功能重新设计契约的候选能力。
- `evidence-coverage-baseline.json`：八字/紫微 evidence coverage trend 的 tracked baseline；只保存覆盖率门槛、计数和隐私边界，不保存报告正文或真实用户资料。
- `evidence-coverage-trend-contract.json`：evidence coverage trend gate 契约；要求 rule depth registry、classics rule index、analysisEvidence、Report evidenceRefs、冲突解释和反证字段不回退。
- `evidence_schema.json`：综合八字机器可读 evidence 字段契约；默认不渲染到 Markdown。
- `weight_policy.json`：综合八字核心、动态、辅助、民俗权重边界。
- `classics_rule_index.json`：典籍规则索引种子，只保存短规则与来源，不保存大段原文。
- `rule_depth_registry.json`：八字/紫微规则深度配置，只保存规则条件、证据字段、冲突策略与风险边界。
- `owner` / `governance.extensionPolicy`：规则和候选能力的变更口径；新增规则必须有来源、适用条件、不适用条件和风险边界，不得写入确定性断语字段。
- `profiles/`：定义某个输出 profile 允许返回哪些字段。
- 这里不放算法代码，不依赖 Telegram / FastAPI / 数据库。
- 新增字段时，先更新这里的 profile，再更新 `.github/domains/fate-analysis/services/fate-core/` 的 provider / usecase。