# AI 工作说明与代码映射 / AI briefs & code mapping

ID: ai-workflow
Version: 1.2.1

让 AI 先理解任务，再查需要的规则，最后按现有组件实现并验证。

Have AI understand the task, retrieve relevant rules, implement with existing components, and verify the result.

## Anatomy
- 任务：页面类型、读者、目标与真实内容来源。
  Task: page type, audience, outcome, and real content source.
- 规则：相关对象的定义、参数、使用边界与状态。
  Rules: definitions, parameters, constraints, and states for relevant objects.
- 映射：稳定对象 id、依赖、变量名和实际代码文件。
  Mapping: stable IDs, dependencies, tokens, and actual source files.
- 验收：截图、交互和构建结果与规则对照。
  Review: compare screenshots, interactions, and build results against the rules.

## Parameters
- knowledge.json: structured registry
  检索对象、依赖与代码位置；不是自动生成服务。
  Retrieve objects, dependencies, and code locations; it is not a generation service.
- rules/*.md: one object / file
  按需给 AI 对应规范，减少无关上下文。
  Give AI the relevant object guide without unrelated context.
- task: create / modify / review
  区分新建、改动和检查，明确交付内容。
  Differentiate creation, modification, and review outputs.

## Rules
- 先引用现有组件和 token；确有缺口再说明新增组件的理由。
  Reference existing components and tokens first; justify a new component when coverage is missing.
- 生成前列出页面结构和规则 id，避免只给一段模糊风格描述。
  List page structure and rule IDs before generation instead of supplying only vague style adjectives.
- 修改范围与验收条件进入工作说明，保留真实数据边界。
  Include scope and acceptance criteria while respecting real-data boundaries.
- 本站提供静态 JSON、CSS 和 Markdown 接入；目前没有对外 MCP 服务。
  This site exposes static JSON, CSS, and Markdown; it does not currently expose an MCP service.

## States
- 新建 / Create: 给出页面结构、组件选择和响应式方案，再实现。
  Specify structure, components, and responsive behavior before implementing.
- 修改 / Modify: 说明目标区域、需要保留的内容与改动依据。
  Identify the target area, retained context, and rationale.
- 检查 / Review: 输出问题、对应规则、证据与修改建议，不把建议写成已完成。
  Report findings, rule IDs, evidence, and recommendations without claiming implementation.

## Do / Avoid
- Do: 读取 resource-cards 规则和实际组件，再改卡片简介与状态。 / Read resource-cards and its actual implementation before changing copy and states.
- Avoid: 只输入“高级、科技、简洁”，让 AI 自行猜测品牌、内容和操作。 / Ask only for premium, futuristic, minimal and let AI guess brand, content, and behavior.

## Code mapping
- src/lib/design-knowledge.ts: 规则与映射注册表 / Rules and mapping registry
- src/components/BrandBriefBuilder.astro: 任务工作说明生成器 / Task brief builder

## Dependencies
page-patterns

## Acceptance
- 工作说明包含任务、目标页面、相关规则和验收方式。
  The brief includes task, target page, relevant rules, and validation.
- 映射中的组件路径确实存在。
  Every mapped source path exists.
- 没有把示例服务或 MCP 配置描述为已部署能力。
  Examples and MCP configurations are not presented as deployed capabilities.

## Implementation example
```
// Read the public knowledge registry, then the referenced source files.
const knowledge = await fetch("/ai-up-lab/brand/knowledge.json")
  .then(response => response.json());
const cardSpec = knowledge.objects.find(item => item.id === "resource-cards");
```

## Reference
Method reference: https://tmall-design.com/#blog/building-design-wiki-for-aigui
Rules, parameters, examples, and branding in this file are specific to AI UP LAB.