lizy-coding · lizy-coding · Jul 12, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -5,9 +5,12 @@
 ## 前置阅读
 
 执行任何修改前，agent 必须读取：
-1. `AI_PROJECT_CONTEXT.md` - 项目整体上下文
-2. `REFACTOR_PLAN.md` - 整改计划与优先级
-3. 目标模块的 `AI_ANALYSIS.md` - 模块结构与修改建议
+1. `AI_ANALYSIS_SCHEMA.json` - agent 文档 schema
+2. `AI_PROJECT_CONTEXT.md` - 机器可解析项目契约
+3. `REFACTOR_PLAN.md` - 机器可解析任务队列
+4. 目标模块的 `AI_ANALYSIS.md` - 机器可解析模块契约
+
+以上 agent 文档均为 JSON，禁止加入 Markdown、自然语言段落或手工文件清单。
 
 ## 新增模块规则
 
@@ -16,21 +19,23 @@
 | 必需项 | 说明 |
 |--------|------|
 | `module_entry.dart` | 导出 `*Entry` Widget，作为模块入口 |
-| `AI_ANALYSIS.md` | 模块分析文档：功能、文件结构、数据流、关键类、修改建议 |
+| `AI_ANALYSIS.md` | 模块机器契约：route、category、status、entrypoints、owns、depends、analysis_parent、validation |
 | 路由注册 | 在 `lib/router/app_route_table.dart` 的 `_modules` 中注册 |
 | 模块元数据 | `ModuleEntry` 必须填写 `category`、`difficulty`、`concepts`、`estimatedMinutes`、`status`、`subtitle` |
 | 教学页面 | 至少 1 个页面使用外部 `flutter_study_learning` 包中的教学模板组件（`LearningScaffold` 等） |
 
 ## 修改模块规则
 
 1. 修改前先读取该模块的 `AI_ANALYSIS.md`
-2. 修改后同步更新 `AI_ANALYSIS.md` 中的文件结构和关键类信息
-3. 如果修改了路由注册，同步更新元数据字段
+2. 修改模块、依赖、路由或层级时，更新 `tool/generate_agent_indexes.js` 中的生成源
+3. 执行 `bash tool/generate_harness_ai_analysis.sh` 重新生成并校验 agent 文档
+4. 如果修改了路由注册，同步更新元数据字段
 
 ## 验收规则
 
 每次代码修改后 **必须** 执行：
 ```bash
+bash tool/generate_harness_ai_analysis.sh
 dart format .
 flutter analyze
 dart run flutterguard_cli:flutterguard scan --path . --fail-on high

diff --git a/AI_ANALYSIS.md b/AI_ANALYSIS.md
@@ -10,6 +10,7 @@
   },
   "entrypoints": [
     "lib/main.dart",
+    "lib/app/app_bootstrap.dart",
     "lib/app/app.dart",
     "lib/app/router/app_route_table.dart"
   ],
@@ -38,12 +39,13 @@
     "no_natural_language": true,
     "index_only": true,
     "max_index_depth": 2,
-    "doc_consumer": "vibecoding",
-    "doc_mode": "harness",
+    "doc_consumer": "coding_agent",
+    "doc_mode": "machine_contract",
     "update_required_on_file_change": true,
     "import_direction_enforced": true
   },
   "validation": [
+    "bash tool/generate_harness_ai_analysis.sh",
     "dart format .",
     "flutter analyze",
     "dart run flutterguard_cli:flutterguard scan --path . --fail-on high"

diff --git a/AI_ANALYSIS_SCHEMA.json b/AI_ANALYSIS_SCHEMA.json
@@ -1,8 +1,15 @@
 {
-  "schema": "vibecoding.harness.ai_analysis_schema.v1",
+  "schema": "flutter_study.agent_docs.schema.v2",
   "syntax": "json_config",
   "prose": "forbidden",
   "markdown": "forbidden",
+  "generated_by": "tool/generate_agent_indexes.js",
+  "documents": {
+    "project_context": "AI_PROJECT_CONTEXT.md",
+    "refactor_plan": "REFACTOR_PLAN.md",
+    "module_index": "lib/AI_MODULE_INDEX.md",
+    "analysis_glob": "**/AI_ANALYSIS.md"
+  },
   "levels": {
     "workspace": [
       "AI_ANALYSIS.md"
@@ -51,8 +58,8 @@
     "no_natural_language": true,
     "index_only": true,
     "max_index_depth": 2,
-    "doc_consumer": "vibecoding",
-    "doc_mode": "harness"
+    "doc_consumer": "coding_agent",
+    "doc_mode": "machine_contract"
   },
   "module_contract_policy": {
     "keep_for_module_rule": true,

diff --git a/AI_PROJECT_CONTEXT.md b/AI_PROJECT_CONTEXT.md
@@ -1,92 +1,127 @@
-# AI 项目上下文
-
-> 此文件为 AI 编程助手提供项目整体上下文，修改代码前请先阅读。
-
-## 项目概述
-
-- **名称**: main_app
-- **类型**: Flutter 学习项目集合，单应用多模块架构
-- **支持平台**: macOS, Windows, iOS, Android
-- **技术栈**: Flutter 3.x / Dart 3.x
-
-## 架构模式
-
-- **路由**: go_router 统一管理，首页为模块列表，点击后 push 到对应模块
-- **状态管理**: 项目实验多种方案（Provider, Riverpod, Bloc, ChangeNotifier, 自研 IoC）
-- **模块组织**: 每个功能模块位于 `lib/modules/<category>/<module_name>/` 下，通过 `module_entry.dart` 暴露入口 Widget
-
-## 关键约定
-
-1. **模块入口**: 每个模块必须有 `module_entry.dart`，导出名为 `*Entry` 的 Widget
-2. **路由注册**: 新模块需在 `lib/app/router/app_route_table.dart` 的 `_modules` 列表中注册
-3. **依赖**: 所有依赖在根 `pubspec.yaml` 中声明，模块间不共享独立依赖
-4. **命名**: 模块目录使用 snake_case，路由路径使用 kebab-case
-
-## 目录结构
-
-```
-lib/
-├── main.dart              # 应用入口，ProviderScope 包裹
-├── app/
-│   ├── app.dart           # MaterialApp.router 配置
-│   └── router/            # go_router 路由配置
-│       ├── app_router.dart
-│       ├── app_route_table.dart # 路由表 + 模块列表 + 首页 UI
-│       └── AI_ANALYSIS.md
-├── module_registry/       # 模块元数据定义
-│   ├── module_entry.dart
-│   └── module_category.dart
-├── shared/                # 共享能力
-│   ├── multi_window/      # 多窗口能力封装
-│   └── platform/          # 平台通道与系统能力封装
-├── modules/               # 学习模块分区
-│   ├── basic/             # 基础机制
-│   ├── async/             # 异步并发
-│   ├── state/             # 状态管理
-│   ├── ui/                # UI 与动效
-│   ├── popup_table/       # 弹窗与列表
-│   └── platform/          # 网络与平台
-```
-
-教学模板组件由外部包 `flutter_study_learning` 提供（`LearningScaffold`、`LearningObjectives`、`ConceptChips`、`CodeSnippetCard`、`CommonPitfalls`、`ExerciseCard`、`StateLogView`）。
-
-## 模块内部结构（推荐）
-
-```
-modules/<category>/<module>/
-├── module_entry.dart       # 模块入口 Widget
-├── module_routes.dart      # 子路由定义（有子路由时才需要）
-├── AI_ANALYSIS.md          # 模块分析文档
-├── presentation/           # UI 层（pages/ + widgets/）
-├── application/            # 应用层（state/ + services/）
-├── domain/                 # 领域层（models/）
-└── data/                   # 数据层（api/ + parser/ + mock/）
-```
-
-简单模块可以保留精简版：
-```
-modules/basic/debounce_throttle/
-├── module_entry.dart
-├── module_root.dart
-├── AI_ANALYSIS.md
-└── utils/
-```
-
-## 添加新模块步骤
-
-1. 在 `lib/modules/<category>/` 下创建模块目录 `lib/modules/<category>/my_module/`
-2. 创建 `module_entry.dart`，导出 `MyModuleEntry` Widget
-3. 在 `lib/app/router/app_route_table.dart` 中：
-   - import 模块入口
-   - 在 `_modules` 列表添加 `ModuleEntry`
-4. 如需子路由，在模块内定义 `List<GoRoute>` 并在 `ModuleEntry.routes` 中传入
-
-## 常用命令
-
-```bash
-flutter pub get          # 安装依赖
-flutter run -d macos     # 运行 macOS 版本
-flutter analyze          # 代码检查
-dart format .            # 格式化
-flutter build macos      # 构建 macOS 版本
-```
+{
+  "schema": "flutter_study.agent_docs.project_context.v1",
+  "consumer": "coding_agent",
+  "package": {
+    "name": "main_app",
+    "type": "flutter_modular_learning_app",
+    "sdk": [
+      "flutter_3",
+      "dart_3"
+    ]
+  },
+  "platform": {
+    "current_hosts": [
+      "macos",
+      "windows"
+    ],
+    "next_host": "android",
+    "target_hosts": [
+      "android",
+      "ios",
+      "macos",
+      "windows"
+    ]
+  },
+  "entrypoints": {
+    "process": "lib/main.dart",
+    "bootstrap": "lib/app/app_bootstrap.dart",
+    "app": "lib/app/app.dart",
+    "router": "lib/app/router/app_router.dart",
+    "route_table": "lib/app/router/app_route_table.dart"
+  },
+  "layers": [
+    {
+      "id": "app",
+      "path": "lib/app",
+      "owns": [
+        "host_bootstrap",
+        "app_shell",
+        "navigation_policy",
+        "route_composition"
+      ],
+      "may_depend_on": [
+        "module_registry",
+        "shared",
+        "modules"
+      ]
+    },
+    {
+      "id": "module_registry",
+      "path": "lib/module_registry",
+      "owns": [
+        "module_metadata",
+        "catalog_operations"
+      ],
+      "may_depend_on": [
+        "flutter",
+        "go_router"
+      ]
+    },
+    {
+      "id": "shared",
+      "path": "lib/shared",
+      "owns": [
+        "business_neutral_capabilities",
+        "platform_boundaries"
+      ],
+      "forbidden_dependencies": [
+        "app",
+        "modules"
+      ]
+    },
+    {
+      "id": "modules",
+      "path": "lib/modules/{category}/{module}",
+      "owns": [
+        "learning_ui",
+        "module_state",
+        "module_domain",
+        "module_data"
+      ],
+      "forbidden_dependencies": [
+        "other_modules"
+      ]
+    }
+  ],
+  "module_contract": {
+    "required_files": [
+      "module_entry.dart",
+      "AI_ANALYSIS.md"
+    ],
+    "required_registration": "lib/app/router/app_route_table.dart",
+    "required_metadata": [
+      "category",
+      "difficulty",
+      "concepts",
+      "estimatedMinutes",
+      "status",
+      "subtitle"
+    ],
+    "required_learning_dependency": "flutter_study_learning",
+    "route_path_style": "kebab_case",
+    "directory_style": "snake_case"
+  },
+  "platform_rules": {
+    "router_platform_api": "forbidden",
+    "module_host_navigation": "forbidden",
+    "desktop_window_policy": "lib/app/category_navigation.dart",
+    "platform_capability_contract": "business_neutral_interface"
+  },
+  "change_protocol": {
+    "pre_read": [
+      "AI_PROJECT_CONTEXT.md",
+      "REFACTOR_PLAN.md",
+      "{target}/AI_ANALYSIS.md"
+    ],
+    "update_source": [
+      "tool/generate_agent_indexes.js"
+    ],
+    "generate": "bash tool/generate_harness_ai_analysis.sh",
+    "validate": [
+      "bash tool/generate_harness_ai_analysis.sh",
+      "dart format .",
+      "flutter analyze",
+      "dart run flutterguard_cli:flutterguard scan --path . --fail-on high"
+    ]
+  }
+}