Metadata-Version: 2.4
Name: ai-composer
Version: 0.1.3
Summary: AI 应用开发范式: 应用 = 平台内核 + 业务插件组合
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Requires-Dist: celery>=5.3
Requires-Dist: redis>=4.5
Requires-Dist: python-docx>=1.1
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: pymysql>=1.0
Requires-Dist: pymupdf>=1.24
Requires-Dist: python-multipart>=0.0.9

# AIComposer — 把 AI 应用开发变成"搭积木"

> **应用 = 平台内核 + 业务插件组合**：内核给机制，插件给能力，应用壳做组合。
> 加不同业务插件 = 不同应用——**一次沉淀，处处复用**。

---

做 AI 应用开发这两年，我被三件事反复折磨。

**第一件，是重复。** 审查要存储，编写要存储，转换也要存储——每做一个新应用，存储、
队列、会话、SSE 这些地基都得重新搭一遍。一开始是复制，后来连复制的勇气都没了：
老项目的烂账越积越多，谁也不知道哪些代码能删、哪些代码不能碰。

**第二件，是恐惧。** 产品说"把存储换成 MinIO"，我看着 20 处 import 的 storage.py
沉默了。改动一旦上线，任何一处漏改都是线上事故。于是"只敢加、不敢删、不敢换"
成了团队心照不宣的默契——系统越做越大，胆子越来越小。

**第三件，是浪费。** 审查业务里打磨了三个月的"文档提取"能力，新项目用不上的时候，
它就像死了一样——经验锁死在单个应用里，带不走、传不下、换不来。

于是我停下来想：能不能把应用拆成**地基**和**业务**？地基是通用的（存储、队列、
会话……），业务是可替换的（审查、编写、转换……）——而且，**装得上去，就卸得下来**。

就在苦思冥想的时候，一个项目点燃了我——**DeepSeek Harness**（dsh）。

2026 年 8 月 13 日开源，**半天一万星**，如今我写到这时已经 16 万+ 星、社区插件 1000+。它把"一切皆插件"
做到了极致：模型是插件、工具是插件、会话是插件，连 loop 都是插件——热插拔，随装随卸。
一个刚开源的项目能爆到这个程度，说明什么？说明"插件化"不是我的执念，**是市场的答案**。

但真正让我下定决心的，不是 dsh 的星数，而是这几年被反复刺痛的经历。

客户需求变更的时候，刺痛我一下；新项目立项、排期的那天，又刺痛我一下；客户说
"你这个技术为什么不用最新最火的"——再刺一下。

AI 发展太快了，AI 应用的需求变化更快。**做过的人应该很有感触**：今天加了一堆
工程代码，明天一次模型升级，全都白做；今天出来一个 OpenClaw，明天出来一个 Hermes，
后天客户又想要一个新玩具——什么都想往系统里加，加到最后，系统变成了谁也改不动的城堡。

所以我想要的，从来不是一个"最新的框架"，而是一个**能扛住这种变化的结构**：
地基稳定，业务随时可以换、可以加、可以拆——技术过时了，换掉那一块就行，
而不是推倒重来。

这个念头，成了 AIComposer 的起点。

这就是 AIComposer：

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

内核给机制（不认识任何业务），插件给能力（业务 + 通用），应用壳做组合（选插件、开入口）。
80% 的地基抽成**公共插件**，你只写那 20% 的业务——剩下的，交给六个特性：

```
① 内核零依赖      机制与能力彻底分离：kernel 纯标准库 ~230 行——想看懂它, 半小时
② 可逆卸载        装得上去就卸得下来：卸载零残留, 撤销影响可计算（删了会波及谁, 事前告知）
③ 协议化替换      消费方只依赖 key, 不 import 实现：换存储/引擎/队列 = 改一行注册,
                  20 个消费方零改动
④ 机制强制约束    业务代码进壳、任务名脱锚——装配时直接报错, 不是靠评审自觉（大声失败）
⑤ 工具闭环        装/看/升/卸/模板五命令：init 生成、graph 看清内部、promote 上浮、
                  uninstall 影响分析删除、template 提取模板
⑥ 模板沉淀飞轮    上浮 = 传承声明：通用能力上浮为公共插件 → 模板只带走公共插件
                  → 新项目从"已验证的半成品"起步 → 再沉淀。越用越强
```

## 它和市面上的框架有什么不同

```
vs DeepSeek Harness   同哲学（一切皆插件, 16 万+ stars 验证了这个方向）——
                      但它是 agent 运行时（TS）；我们是通用应用开发平台（Python, 不绑定 AI）
vs LangChain          编排库 vs 应用框架：我们有插件生命周期 + 应用壳模型 + 可逆卸载
vs Dify/Langflow      低代码拖拽 vs 开发框架：面向开发者, 不是最终用户
vs Cordis             可逆效果组合的启发来源——4 年 4000+ 插件生态验证过的机制
```

## 适合谁

```
✅ 团队维护多个 AI 业务应用（审查/编写/转换/问答……）——共享地基, 业务互相隔离
✅ 从传统单体 AI 应用演进——strangler 重构路径已实证（review 应用就是壳 + 插件化）
✅ 架构要求可替换——引擎/存储/队列随时可换, 消费方零改动, 有契约测试保障
✅ AI 与非 AI 应用同框架——范式不绑定 AI（file-convert/todo 纯逻辑应用同样跑在这套机制上）
✅ 想"看清"软件内部——图谱：依赖关系、孤儿插件、共享资产、卸载影响一图呈现
```

## 快速开始（3 步）

```bash
# 1. 安装
pip install ai-composer

# 2. 创建你的第一个应用
aic init my_app

# 3. 启动
uvicorn apps.my_app.main:app --port 8001
# http://127.0.0.1:8001/health → plugins 列表含 MyAppPlugin

# 示例应用（挂载全部公共插件, 开箱即用）:
uvicorn apps.hello_aic.main:app --port 8000
```

## 工具链（aic 五命令）

```
aic init <name>              装    创建新应用（壳 + 插件骨架）
aic graph                    看    生成项目结构图谱 graph-viz.html（自包含交互）
aic promote <类> [--yes]     升    私有插件上浮为公共插件（移动包 + 更新引用 + PUBLIC 标记）
aic uninstall <应用> [--yes] 卸    应用/插件卸载（影响分析后删除）
aic template <应用> [--out]  模板  提取新应用开发模板（只带走公共插件）
```

- promote / uninstall 默认**预演**（只显示影响清单），加 `--yes` 执行
- 仓库开发模式等价命令：`python -m tools.cli <命令>`

## 范式核心用法：模板沉淀飞轮

```
已完成应用
  → 业务中发现的通用能力 promote 上浮（公共插件, 独立生命周期）
  → aic template 提取模板 = 基础 AIC + 公共插件 + 示例壳 hello_aic
  → 新项目从"已验证的公共插件"起步, 而非空白骨架
  → 新项目又沉淀新的公共插件 → 模板越来越强
```

## 目录结构（0.1 发布版）

```
ai-composer/
├── kernel/                # L1 内核（纯机制, 零能力零业务, 零第三方依赖）
│   ├── kernel.py          #   Context/事件总线/挂载卸载/拓扑装配
│   ├── layout.py          #   壳布局契约（存在性 + 内容 AST 检查, 机制强制）
│   └── protocols.py       #   协议清单（AgentTask/ToolHandler/...）
├── extensions/            # L2 插件（推荐目录——插件区隐式, 除地基外皆可放）
│   ├── platform/          #   通用插件惯例位（配置/遥测/存储/缓存/队列/数据库/
│   │                      #   沙箱/SSE/文档提取/引擎）
│   └── business/          #   领域插件惯例位（writer/review/todo/file_convert/
│                           #   共享领域 standard）
├── apps/                  # L3 应用壳（组合与入口）
│   ├── hello_aic/         #   示例应用（挂载全部公共插件, 新项目起点）
│   ├── mvp/               #   参考应用（FastAPI + SSE + 任务双路径）
│   └── review/            #   审查应用（strangler 重构产物）
├── tools/                 # 工具链（aic 命令实现）
├── docs/
│   ├── tutorial/          # 官方教程（安装/快速开始/首个插件/应用壳/工具链/最佳实践/命令参考）
│   └── reference/         # 社区生态调研（dsh/Cordis/LangChain 对照, 设计参考）
├── test/                  # 回归验证（m0~m7, 61 项）
├── .claude/ .codex/ .agent/   # 开发 Skill（约束/规范/命令速查, AI 开发自动加载）
└── pyproject.toml         # 0.1.0（pip 包, aic 入口）
```

## 文档

| 文档 | 内容 |
|---|---|
| [docs/tutorial/index.md](docs/tutorial/index.md) | **官方教程（0.1）**——背景 → 安装 → 快速开始 → 第一个插件 → 应用壳 → 工具链 → 最佳实践 → 命令参考 |
| [.claude/skills/aic-paradigm/](.claude/skills/aic-paradigm/SKILL.md) | **开发 Skill**——约束/规范/最佳实践/命令速查（Claude Code / Codex / Agent 三端同步） |

## 验证基线（诚实边界）

```
已验证:   内核机制（m0~m5）壳契约与任务名协议（m6）工具链（m7）——61 项回归全绿
          工具闭环（init/graph/promote/uninstall/template）真实跑通
验证基线:  fake 引擎全链路（KIT_ENGINE 默认）
0.2 迭代:  真实 LLM 引擎端到端 / MinerU 提取 / MySQL / 前端对接
```

## 研究路线

```
已完成: M0 内核 → M1 引擎+沙箱 → M2 流水线 → M3 交付物 → M4 生产化+基础设施插件化
        → M5 挂载校验 → M6 壳布局契约 + 任务名协议 → 工具闭环 → 0.1.0 发布
下一步: 真实 hermes 端到端 → MinerU → MySQL → 前端 → 平台版本化
```

## 参考项目

| 文档 | 内容 |
|---|---|
| [docs/reference/ecosystem-research.md](docs/reference/ecosystem-research.md) | **社区生态调研**——DeepSeek Harness / Cordis / Semantic Kernel / LangChain 对照与差异化定位（本范式设计参考） |
