# 数据与项目集成契约

## SceneSpec

```ts
type SceneMatchLevel = 'exact' | 'partial' | 'none';
type PageMode = 'list' | 'add' | 'edit' | 'view' | 'audit';

interface SceneSpec {
  sceneName: string;
  matchLevel: SceneMatchLevel;
  capabilities: SceneCapability[];
  pageName: string;
  moduleName: string;
  targetDirectory: string;
  pageMode: PageMode;
  fields: FieldSpec[];
  tableColumns: TableColumnSpec[];
  sections: SectionSpec[];
  actions: ActionSpec[];
  apis: ApiSpec[];
  requiredCapabilities: CapabilityRequirement[];
  unresolvedItems: UnresolvedItem[];
}
```

未提供的字段、列、分区等使用空数组，不使用 `undefined` 混淆“未提取”和“不存在”。

## ProjectProfile

```ts
interface IntegrationAdapter {
  kind: string;
  importSource?: string;
  evidenceFiles: string[];
  confidence: 'confirmed' | 'inferred' | 'unknown';
  conventions: Record<string, unknown>;
}

interface ProjectProfile {
  projectRoot: string;
  targetDirectory: string;
  reactVersion?: string;
  typescriptVersion?: string;
  antdVersion?: string;
  sisyphusVersion?: string;
  framework?: string;
  routingAdapter?: IntegrationAdapter;
  requestAdapter?: IntegrationAdapter;
  permissionAdapter?: IntegrationAdapter;
  stateAdapter?: IntegrationAdapter;
  fileStructureAdapter?: IntegrationAdapter;
  instructionFiles: string[];
  referencedInstructionFiles: string[];
  typeConvention?: string;
  styleConvention?: string;
  availableCommands: string[];
  approvedExamples: string[];
}
```

`framework` 只记录探测结果，不参与技能启用判断。没有导航需求时不得因为探测到框架而引入路由代码。

`fileStructureAdapter.conventions` 记录经项目规则或标杆样板确认的目录、组件入口与样式、barrel 和类型文件名。`requestAdapter.conventions` 记录全局错误拦截、是否省略请求 `try/catch` 和状态码判断。两者都必须保留 `evidenceFiles`，生成文件树与校验器使用同一份 `ProjectProfile`，不得只探测不消费。

## CapabilityRequirement 与 ComponentDecision

```ts
type CapabilityStatus = 'covered' | 'partial' | 'missing' | 'unverified';
type ComponentSource = 'sisyphus' | 'antd' | 'project' | 'unresolved';

interface CapabilityRequirement {
  id: string;
  description: string;
  required: boolean;
}

interface ComponentEvidence {
  tool: string;
  target: string;
  libraryVersion: string;
  schemaVersion?: number;
  exampleId?: string;
}

interface ComponentDecision {
  requirementId: string;
  requirement: string;
  status: CapabilityStatus;
  source: ComponentSource;
  component?: string;
  apiEvidence?: ComponentEvidence;
  demoEvidence?: ComponentEvidence;
  fallbackReason?: string;
}
```

规则：

- 每个必需 requirement 恰好一条 decision。
- `sisyphus` 来源必须使用结构化 API/demo 证据，记录完全相同的组件版本与 schema v2。
- API 证据必须来自 `sisyphus-get-component-api`；demo 证据必须来自 `sisyphus-get-example` 并记录 `exampleId`。
- `antd` 来源必须有 API/demo 证据与 fallbackReason。
- `project` 来源必须有源码路径与调用示例证据。
- `unresolved` 或 `unverified` 阻断生成。

## ComponentDocsProvider

```ts
interface ComponentDocsProvider {
  getMetaStatus(): Promise<ComponentMetaStatus>;
  listComponents(): Promise<ComponentSummary[]>;
  getComponentApi(name: string): Promise<ComponentApi>;
  getType(name: string): Promise<ComponentType>;
  listExamples(
    name: string,
    scenario?: string,
    cursor?: string,
  ): Promise<ComponentExampleSummary[]>;
  getExample(id: string): Promise<ComponentExample>;
  search(query: string): Promise<ComponentSearchResult[]>;
  /** 仅用于兼容旧 MCP 工具，新流程不得使用。 */
  getExamples?(name: string, scenario?: string): Promise<ComponentExample[]>;
}
```

平台适配器提供：

- `SisyphusMcpProvider`
- `AntdMcpProvider`
- `Context7AntdProvider`

这里只定义能力，不把任何平台的 MCP 工具前缀写入生成代码。
