基于指令的代码喷涂系统

这是一个非常硬核且前瞻的方案。你已经把“代码生成”提升到了“AI 智械协同”的高度。

在这个架构中，AI 扮演的是“架构师和实施员”，而你的 CLI 工具/MCP Server 扮演的是“操作系统和手术刀”。为了解决你提到的 Service 模板来源、Meta 信息填写以及文件审核的痛点，以下是深度设计的方案：

1. 模板的管理与“投喂”：谁来写？AI 怎么看？

Service 模板不能是黑盒，它应该是透明且可进化的。

• 用户侧： 在项目根目录提供一个 autogen/templates 文件夹。里面按层级存放原子化的 .ts.t（或 .txt）模板。例如 service/list.ts.t。

• AI 侧： 增加一个 MCP 工具 list_templates()。

  • 逻辑： AI 在做决策前，先调用这个工具，看一眼项目当前支持哪些“原子能力”（即有哪些模板）。

  • 进化： 如果 AI 觉得现有的 list 模板不符合业务（比如需要复杂的递归），它可以建议用户创建一个新模板，或者由 AI 吐出一段临时代码块直接注入。

2. 深度上下文：Drizzle Schema + Relations 的全量感知

你提到的“只返回 Table 结构太简单”非常对。Drizzle 的灵魂在于 relations 定义。

• MCP 增强 get_business_context()：

  • 这个工具不只是读 table.schema.ts。

  • 它会利用 ts-morph 同时扫描 table.schema.ts 和 relations.schema.ts。

  • 返回内容： 一个聚合后的“业务元数据对象”，包含：表字段、类型、主外键关系、以及 Drizzle 定义的 relations（一对多、多对多）。

  • AI 的优势： 有了这些，AI 就能自动判断：在生成 Service.list 时，是否需要添加 with: { posts: true } 这样的关联查询。

3. AI 填写 Meta 信息的闭环流程

既然要 AI 填写所有的 Meta 信息，我们需要定义一个**“同步指令协议” (Sync Protocol)**。

AI 吐出的 JSON 指令示例：

JSON

{
  "entity": "SiteCategory",
  "plan": [
    {
      "layer": "service",
      "action": "tree", // 对应模板名
      "meta": {
        "params": [{ "name": "parentId", "type": "string", "optional": true }],
        "returns": "SiteCategoryTreeResponse[]",
        "logicHints": "需要使用 recursive 递归查询关联的子节点" 
      }
    },
    {
      "layer": "controller",
      "path": "/tree",
      "method": "get",
      "middleware": ["authGuardMid"]
    }
  ]
}

4. “手术”与“复盘”：生成后的审核流程

正如你所说，代码生成后不能直接完事，需要 AI 审核。

1. AI 发起同步：AI 提交上述 JSON 给 MCP 工具 execute_sync。

2. 引擎喷涂：你的本地引擎（基于 ts-morph）读取模板，结合 JSON 里的 Meta 信息，将代码精准注入到 service.ts 和 controller.ts。

3. 结果反馈：execute_sync 完成后，返回一个修改摘要给 AI，包含：

   • 生成的具体代码片段。

   • 文件的物理路径。

   • 受影响的导出（如 index.ts）。

4. AI 审核：AI 拿到这些片段，检查逻辑是否正确。如果不对，AI 可以发起 fix_instruction 进行微调。

5. 架构总结：基于 MCP 的协同工作流

步骤	角色	动作	目的
1. 准备	用户/库	提供 templates/ 和 AutoGenConfig	定义审美和边界
2. 扫描	AI (via MCP)	get_business_context()	理解表结构与 Drizzle 关系
3. 参考	AI (via MCP)	list_templates()	了解目前有哪些“手术包”可用
4. 决策	AI	生成 SyncInstruction JSON	规划每一层的 Meta 信息
5. 实施	引擎 (CLI)	execute_sync(json)	利用 ts-morph 往多路径喷涂代码
6. 审核	AI	review_changes(diff)	最终质量把关

为什么这个方案是“无敌”的？

• 模板可见性：用户在 script/templates 下一眼就能看到自己的模板，随时可以修改。

• AI 填空：你不用写复杂的生成逻辑，你只需要写好 AST 的“注塑机”，让 AI 决定“注塑”的内容。

• 多路径同步：利用你配置好的 outputs，AI 一句指令，代码同时飞向 admin-api、client-api 和前端 hooks。

这种模式下，你开发的不再是一个简单的生成器，而是一个**“让 AI 具备全栈落地能力”的插件系统**。你需要我为你设计这个 SyncInstruction JSON 的详细 Schema 吗？

这个设计非常硬核。我们要构建的是一个基于指令（Instruction-based）的代码喷涂系统。在这个体系下，AI 不再写繁琐的代码，而是通过填写一份精确的“手术清单（SyncInstruction）”，由你的引擎通过 ts-morph 执行语法树级别的注入。

以下是为你设计的 SyncInstruction 协议格式。它严格遵守你之前的命名规范（Kebab-case 文件名、CamelCase 变量、PascalCase 类名、Waterfall 感应逻辑）。

---

1. SyncInstruction 核心 Schema 定义

这份 JSON 是 AI 调用的 MCP 工具 execute_sync 的入参，涵盖了从数据到展示的完整生命周期元信息。

JSON

{
  "entity": "site-category", // 原始实体名（kebab-case），用于推导全路径
  "description": "站点分类管理", 
  "plan": {
    // --- 1. 契约层 (Contract): 类型定义 ---
    "contract": {
      "mode": "@full", // 或 @partial
      "features": ["tree", "sortable"], // 影响生成的字段校验逻辑
      "extraSchemas": [
        { "name": "TreeResponse", "extends": "Response", "addFields": { "children": "t.Array(t.Any())" } }
      ]
    },

    // --- 2. 逻辑层 (Service): 原子逻辑注入 ---
    "service": [
      {
        "template": "@list",
        "methodName": "findAll",
        "meta": {
          "relations": ["parent", "children"], // Drizzle relations 感应
          "filters": ["name", "status"],
          "logic": "需增加租户隔离与部门权限过滤"
        }
      },
      {
        "template": "@tree",
        "methodName": "getTree",
        "meta": { "recursive": true, "orderBy": "sortOrder" }
      }
    ],

    // --- 3. 表现层 (Controller): 路由感应与哨兵注入 ---
    "controller": {
      "prefix": "/site-category",
      "middleware": ["authGuardMid"],
      "routes": [
        {
          "action": "list", // 对应 Service.findAll
          "method": "get",
          "path": "/",
          "meta": { "summary": "查询分类树", "permissions": ["SITE_CATEGORY_VIEW"] }
        },
        {
          "action": "getTree", // 对应 Service.getTree
          "method": "get",
          "path": "/tree",
          "meta": { "summary": "获取层级树", "requireDept": true }
        }
      ]
    },

    // --- 4. 客户端层 (Hooks): 路由全量感应生成 ---
    "hooks": {
      "apiClientPath": "@/lib/api",
      "tags": ["SiteCategory"],
      "overrides": [
        { "path": "/tree", "hookName": "useSiteCategoryTree", "type": "query" }
      ]
    }
  }
}

---

2. 四层元信息需求深度解析

为了让 AI 填好这份表，引擎需要提供以下上下文支持：

A. 契约层 (Contract) 元信息

• 需要 AI 填写：是否需要扩展基础的 Response？是否需要特殊的校验（如正则、枚举）？

• 引擎规则：根据 site-category 自动推导 SiteCategoryContract。

• AI 决策：如果是中间表，AI 在此处标记 skip: true。

B. 逻辑层 (Service) 元信息

• 需要 AI 填写：

  • template: 选择 script/templates/service/ 下的哪个手术包（如 @list, @tree）。

  • relations: Drizzle 关系配置（AI 从扫描到的 relations.schema.ts 中提取）。

  • logic: 注入到模板中的特殊逻辑注释或代码片段。

• 引擎规则：在 SiteCategoryService 中寻找或创建带 /** @generated */ 的方法。

C. 表现层 (Controller) 元信息

• 需要 AI 填写：

  • action: 关联的 Service 方法名。

  • path: 路由路径（符合 RESTful 规范）。

  • middleware: 插件数组（AI 根据 manifest 中的全局配置推导）。

• 引擎规则：在 Elysia 链式调用中定位 // @generated 哨兵，执行局部 replaceWithText。

D. 客户端层 (Hooks) 元信息

• 需要 AI 填写：排除列表（哪些敏感接口不生成 Hook）。

• 引擎规则：不看 Schema，只看 Controller 实测代码。扫描 site-category.controller.ts 的所有路由节点，1:1 产出 React Query Hooks。

---

3. AI 的 MCP 工作流（开发者视角）

当你要开发一个新功能时，对话流程如下：

1. 用户：“给站点分类增加一个‘移动节点’的功能。”

2. AI (Tool Call: get_business_context)：读取 Schema 和现有 Service。

3. AI (Tool Call: list_templates)：发现有一个 @move 的 Service 模板。

4. AI (Decision)：构造 SyncInstruction。

   • Service: 增加 moveNode 方法，使用 @move 模板。

   • Controller: 增加 PATCH /:id/move 路由，关联 moveNode。

   • Hooks: 自动感应生成 useMoveSiteCategory。

5. AI (Tool Call: execute_sync)：引擎执行 AST 操作。

6. AI (Review)：读取生成的代码文件，告诉用户：“功能已就绪，我已同步了后端逻辑、API 路由和前端 Hook。”

---

4. 为什么这样设计“最调理”？

1. AI 填 Meta 信息的代价最低：AI 擅长写 JSON，不擅长写几百行保证不出错的 ts-morph 逻辑。

2. 模板与引擎隔离：你可以随时在 script/templates 修改你的 Service 实现风格，AI 会自动通过 list_templates 感知到你的新审美。

3. 多后端天生支持：execute_sync 内部遍历 AutoGenConfig.outputs 数组，AI 的一个 JSON 指令，代码会精准喷涂到所有配置好的工程目录中。

总结： 这种 “AI 决策 + JSON 契约 + AST 喷涂” 的模式