Metadata-Version: 2.4
Name: ai-composer
Version: 0.2.1
Summary: AI 应用开发范式: 应用 = 组件组合（框架 aic 包 + 业务平铺）
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：

```
组件 = 能力实现（普通类/函数, 不认识内核）
插件 = 组件 + 插件声明（inject/provides/apply, 内核接入器）
应用 = 组件组合（内核组织 + 插件接入 + 应用壳声明清单）
```

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

```
① 内核零依赖      机制与能力彻底分离：kernel 纯标准库 ~230 行——想看懂它, 半小时
② 可逆卸载        装得上去就卸得下来：卸载零残留, 撤销影响可计算（删了会波及谁, 事前告知）
③ 协议化替换      消费方只依赖 key, 不 import 实现：换存储/引擎/队列 = 改一行注册,
                  20 个消费方零改动
④ 机制强制约束    业务代码进壳、任务名脱锚、跨盒旁路 import——装配时直接报错, 不是靠评审自觉（大声失败）
⑤ 工具闭环        装/看/查/升/卸/模板六命令：init 生成、graph 看清内部、caps 查能力、
                  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 aic.apps.hello_aic.main:app --port 8000
```

## 工具链（aic 六命令）

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

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

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

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

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

```
ai-composer/               # 发布包只装 aic*（框架 = 平台）; 业务平铺在项目根
├── aic/
│   ├── __init__.py        # 统一入口: import aic → Context/Plugin/boot/__version__
│   ├── kernel/            # L1 内核（纯机制, 零能力零业务, 零第三方依赖）
│   │   ├── kernel.py      #   Context/事件总线/挂载卸载/拓扑装配
│   │   ├── layout.py      #   壳布局契约（存在性 + 内容 AST 检查, 机制强制）
│   │   ├── imports.py     #   旁路 import 契约（装配期检查跨盒依赖）
│   │   └── protocols.py   #   协议清单（AgentTask/ToolHandler/...）
│   ├── extensions/
│   │   └── platform/      #   框架平台插件（配置/遥测/存储/缓存/队列/数据库/
│   │                      #   沙箱/SSE/文档提取/引擎/规范检索）
│   ├── apps/hello_aic/    #   示例应用（模板基础, 新项目起点）
│   └── tools/             #   工具链（aic 六命令实现）
├── apps/                  # 用户应用壳（平铺, 不进发布包——业务示例 mvp/review/todo/file_convert）
├── extensions/business/   # 用户业务插件（平铺; 项目平台 extensions/platform 是 promote 上浮目标）
├── docs/
│   ├── tutorial/          # 官方教程（安装/快速开始/首个插件/应用壳/工具链/最佳实践/命令参考）
│   └── reference/         # 社区生态调研（dsh/Cordis/LangChain 对照, 设计参考）
├── test/                  # 回归验证（m0~m7 全绿）
├── .claude/ .codex/ .agent/   # 开发 Skill（约束/规范/命令速查, AI 开发自动加载）
└── pyproject.toml         # 0.2.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 对照与差异化定位（本范式设计参考） |
