refactor: converge app architecture and agent docs

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

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"
   ],
@@ -21,31 +22,36 @@
     "host_integrations"
   ],
   "depends": [
-    "../gcode_core",
-    "../flutter_study_learning",
-    "../file_picker_bridge",
-    "../flutter_ioc_core",
-    "../flutterguard/packages/flutterguard_cli"
+    "packages/gcode_core",
+    "packages/flutter_study_learning",
+    "packages/file_picker_bridge",
+    "packages/flutter_ioc_core",
+    "git:https://github.com/lizy-coding/flutterguard.git#9f9be84a73dc4b99a956a8529b8c334849566b03"
   ],
   "children": [
     "lib/AI_ANALYSIS.md",
     "lib/app/AI_ANALYSIS.md",
     "lib/module_registry/AI_ANALYSIS.md",
     "lib/shared/AI_ANALYSIS.md",
-    "lib/modules/AI_ANALYSIS.md"
+    "lib/modules/AI_ANALYSIS.md",
+    "packages/gcode_core/AI_ANALYSIS.md",
+    "packages/flutter_study_learning/AI_ANALYSIS.md",
+    "packages/file_picker_bridge/AI_ANALYSIS.md",
+    "packages/flutter_ioc_core/AI_ANALYSIS.md"
   ],
   "contracts": {
     "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"
+    "dart run flutterguard_cli:flutterguard scan . --fail-on high"
   ]
 }

AI_ANALYSIS_SCHEMA.json

@@ -1,12 +1,25 @@
 {
-  "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"
     ],
+    "package_contract": [
+      "packages/gcode_core/AI_ANALYSIS.md",
+      "packages/flutter_study_learning/AI_ANALYSIS.md",
+      "packages/file_picker_bridge/AI_ANALYSIS.md",
+      "packages/flutter_ioc_core/AI_ANALYSIS.md"
+    ],
     "section": [
       "lib/AI_ANALYSIS.md",
       "lib/app/AI_ANALYSIS.md",
@@ -51,8 +64,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,
@@ -68,5 +81,21 @@
       "long_file_inventory",
       "natural_language_notes"
     ]
+  },
+  "package_contract_policy": {
+    "required_for_workspace_member": true,
+    "content": [
+      "package_type",
+      "workspace",
+      "entrypoints",
+      "owns",
+      "depends",
+      "validation",
+      "test_status"
+    ],
+    "avoid": [
+      "platform_claims_not_proven_by_manifest",
+      "natural_language_notes"
+    ]
   }
 }