AIComposer — AI 应用开发范式

应用 = 平台内核 + 业务插件组合：AI 应用开发范式（Composer）——内核提供机制， 插件提供能力，应用壳做组合。加不同业务插件 = 不同应用。

一、范式一句话

应用 = 平台内核 + 业务插件组合

• 内核（kernel/kernel.py，~230 行，零能力零业务）：服务注册表 / 事件总线(4 模式) / 挂载卸载(可逆效果) / 拓扑装配——只提供"机制"
• 插件（extensions/*）：能力提供方——协议 + 多实现 + 插件包装，三件套结构
• 应用壳（apps/mvp/）：组合者——选插件、传参数、暴露 HTTP 入口，不实现能力

二、核心保证（全部实证）

三、快速开始

# 0. 安装（0.1.0 pip 包, 获得 aic 命令; 仓库开发模式用 python -m tools.cli 等价）
pip install -e .                  # 开发模式安装

# 1. 回归验证（确定性, 无 API 成本）
python test/m0_main.py   # 内核机制 16 项
python test/m1_main.py   # 引擎协议 9 项
python test/m1c_main.py  # 沙箱 10 项
python test/m2_main.py --skip-real   # 流水线 20 项
python test/m3_main.py --skip-real   # 渲染 20 项
python test/m4_main.py   # 生产化 18 项
python test/m4b_main.py  # 基础设施插件化 14 项
python test/m4c_main.py  # 任务队列插件化 12 项
python test/m5_main.py   # 挂载校验 + 撤销影响分析 11 项
python test/m6_main.py   # 壳布局契约 + 任务名协议（机制强制）32 项
python test/m7_main.py   # 工具回归（graph/promote/uninstall/template）58 项

# 3. 启动参考应用（MVP）
python -m uvicorn apps.mvp.main:app --port 8007
# 可选: Redis + Celery worker（默认线程降级自动兜底）
docker run -d --name kit-redis -p 6379:6379 redis:7-alpine
python -m apps.mvp.worker

# 4. 工具链（安装后统一入口 aic; 仓库模式 python -m tools.cli 等价）
aic init my-app                       # 初始化新应用（装）
aic graph                             # 项目结构图谱（看）
aic promote MyPlugin --yes            # 私有插件上浮为公共插件（升）
aic uninstall my-app --yes            # 卸载应用/插件（卸）
aic template review --out ~/tpl       # 新应用开发模板提取（模板）

# 5. 项目结构图谱（插件引用关系可视化, 自包含 HTML 双击即开）
python -m tools.graph                     # 生成 graph-viz.html（点击插件高亮引用/影响）

# 6. 卸载（元命令: 影响分析后删除, 默认只显示影响清单——预演, 不实际删除）
#    预演: 显示将删除什么/保留什么（共享与公共插件不删）; 加 --yes 才真正执行
python -m tools.uninstall my-app                      # 预演: 看影响清单（壳 + 专属插件）
python -m tools.uninstall my-app --yes                # 确认清单后真正卸载
python -m tools.uninstall --plugin DemoPlugin --yes   # 卸载插件包（有挂载/消费方则拒绝）

# 7. 上浮（私有插件 → 公共插件: 移动包到公共位 + 更新全项目 import + 写 PUBLIC 标记,
#    上浮后该插件有独立生命周期——不随任何应用卸载删除, 只能单独 uninstall --plugin）
python -m tools.promote MyPlugin                      # 预演: 显示将移动哪些目录/改哪些引用/标记写哪
python -m tools.promote MyPlugin --yes                # 确认清单后真正上浮到 platform 惯例位
python -m tools.promote MyPlugin --to business --yes  # 上浮到领域惯例位（共享领域插件）

# 8. 新应用开发模板（跨应用复用核心用法: 只带走公共插件, 先 promote 再提取）
python -m tools.template review --dry-run             # 预演: 只显示清单（公共插件 + 未上浮提示）
python -m tools.template review --out ~/my-tpl        # 提取模板 = 基础 AIC + 公共插件
                                                      #   + 示例壳 hello_aic + docs/learn

四、目录结构（三层模型）

ai-composer/
├── kernel/                # L1 内核（纯机制, 零能力零业务）
│   ├── kernel.py          #   Context/事件总线/挂载卸载/拓扑装配 (~230 行)
│   ├── layout.py          #   壳布局契约（机制强制: 存在性 + 内容 AST 检查, M6）
│   ├── protocols.py       #   协议清单: AgentTask/ToolHandler/KnowledgeProvider/AgentLoop
│   └── plugin.py          #   插件基类 (inject + provides + apply)
├── extensions/            # L2 插件（能力提供方; 推荐目录——插件区隐式, 除地基外皆可）
│   ├── platform/          #   通用能力惯例位（所有应用共享）
│   │   ├── base/          #     基础设施插件: config/telemetry/storage/cache/jobs
│   │   ├── loops/         #     引擎插件: FakeLoop / HermesLoop / FailoverLoop
│   │   ├── security/      #     沙箱插件（可逆补丁）
│   │   ├── session/       #     会话服务 ctx.sessions + artifacts 产物管理
│   │   ├── render/        #     渲染注册表 ctx.renderers
│   │   └── stream/        #     SSE 进度推送 ctx.stream
│   └── business/          #   领域能力惯例位（每业务一套）
│       ├── demo/          #     内核演示插件（装配/事件/替换/销毁）
│       ├── review/        #     审查业务插件（strangler 重构: SOP/工具规则/知识/报告/流程/补丁）
│       └── writer/        #     编写业务插件（5 阶段流水线/docx/批量/反馈闭环）
├── apps/                  # L3 应用壳（组合与入口, 每应用一个目录）
│   ├── mvp/               #   参考应用（FastAPI + Celery + SSE）——新应用起点模板
│   │   ├── main.py        #   FastAPI 入口 + 5 端点（含 SSE）
│   │   ├── profile.py     #   插件组合清单（应用壳组装点）
│   │   ├── shell.py       #   装配共用（API 与 worker 进程同一组合）
│   │   ├── tasks.py       #   任务双路径（线程内联 + Celery worker 自举）
│   │   └── worker.py      #   Celery worker 入口（-Q review,followup）
│   └── review/            #   审查应用壳（strangler 重构产物, 复用平台能力）
│       ├── main.py        #   FastAPI: /health /files/upload /conversations(SSE) /report /status...
│       ├── profile.py     #   7 平台插件 + ReviewPlugin
│       ├── shell.py       #   装配（config + 引擎决策 + 任务注册）
│       ├── tasks.py       #   审查任务双路径（线程内联 + Celery worker 同名）
│       └── worker.py      #   Celery worker 入口（-Q review,followup）
├── docs/                  # 文档（api.md 接口 + design/ 设计文档）
├── test/                  # 回归验证脚本（12 个, m0~m7_main.py）
└── requirements.txt

tools/graph.py 生成物: graph-viz.html（自包含交互图谱, 已 gitignore）

五、设计文档导航

六、研究路线

已完成: M0 内核 → M1a/b/c 引擎+沙箱 → M2 流水线 → M3 交付物
        → M4a 生产化 → M4b/c 基础设施插件化 → M4d 可运行 MVP + Celery 真实路径
        → M5 挂载校验 + 撤销影响分析
        → strangler 第一版: 审查应用 → 壳 + review 插件（全量对标, fake 引擎全链路验证）
        → M6 壳布局契约 + 任务名协议（机制强制, init 全量骨架）
下一步: review 真实 hermes 端到端 → MinerU 提取引擎 → DB 切 MySQL → 前端对接
        → review/writer 共享 standard 领域子插件 → SSE 进度推送 → 平台版本化
        → KIT_ENGINE=hermes 真实引擎端到端 → SSE 进度推送 → 平台版本化

七、快速验证端到端

python -m uvicorn apps.mvp.main:app --port 8007 &
curl http://127.0.0.1:8007/health
curl -X POST http://127.0.0.1:8007/api/v1/conversations \
  -H "Content-Type: application/json" \
  -d '{"project_info": "跨江特大桥挂篮施工方案"}'
# 3 秒后查询: 产物含 方案_v1.docx / 方案_v1.md / 3 章