Metadata-Version: 2.4
Name: ai-composer
Version: 3.0.0
Summary: AIComposer 3.0: 业务可见性优先的 AI 应用开发范式——框架 = 可选能力层(opt-in), 不是强制约束层
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27

# AIComposer 3.0（分支 redesign-prototype）

业务可见性优先的新范式框架——**框架 = 可选能力层（opt-in）, 不是强制约束层**。
打开一个应用, 30 秒内知道它在干嘛; 开发者写应用 = 传统写法 + 两个 API（ctx/mount）。

## 教程（tutorial/ 或 aic skills 分发到 .claude/.codex/.agent）

```
01-quickstart.md   3 分钟跑起来（init → 打开 app.py → 写业务 → 跑）
02-plugin.md       插件 = 普通包（apply(ctx)）
03-ctx-events.md   ctx 用法 + 事件四模式
04-toolchain.md    工具链（init/graph/template/skills）
05-real-app.md     真实业务对照（review / constplan 迁移形态）
```

## 怎么跑

```bash
cd prototype
python verify.py             # 内核机制: 装配/事件/卸载零残留/覆盖可恢复（9/9）
python verify_events.py      # 事件四模式: EMIT/WATERFALL/PARALLEL/SERIAL（5/5）
python verify_review.py      # review 真实业务: 提取→检索→引擎→报告→事件（9/9）
python verify_constplan.py   # ConstPlan 真实业务: 创建→并行章节→合并→渲染→版本化（11/11）
python verify_toolchain.py   # 工具链端到端: init→运行→graph→template→skills（8/8）

# 工具链（aic 命令; 或 pip install -e . 后 aic 全局可用）
python -m aic.cli init my_app --root <dir>          # 生成应用骨架
python -m aic.cli graph --app <app_dir>             # 计算图 graph-viz.html
python -m aic.cli template <src_app> --out <dir>    # 插件模板提取
python -m aic.cli skills --root <dir>               # skill 分发
```

**全量验证 42/42**（5 套, 经真实 FastAPI TestClient）。

## 框架包结构（prototype/aic/）

```
aic/
├── __init__.py   统一入口（ctx/mount/unmount/mounted/Task/EventMode）
├── context.py    能力容器: register/get/effect/on/emit + 事件四模式
├── assembly.py   装配: mount/unmount（可逆, 零残留/不误伤）+ mounted()
├── task.py       会话信封 Task（可选, 不约束）
├── cli.py        命令入口: init / graph / template / skills（UTF-8 输出）
├── init.py       骨架生成（app.py + plugins/ + 示例插件 + README）
├── graph.py      计算图（AST 扫描: 装配/能力/依赖/事件 → graph-viz.html）
├── template.py   插件模板提取（plugins/ 全带走, 代码可见可改）
└── skills.py     aic 范式 skill 分发（三平台）
```

## 开发者只需要知道两个概念

```
ctx    能力容器: register(提供) / get(取用) / effect(清理) / on/emit(事件)
mount  装配插件（可逆: 卸载零残留——后台机制）
```

## 机制（全部后台, 不要求理解——框架替你做的）

- 可逆装配: mount/unmount 零残留、不误伤
- 覆盖可恢复: ctx.register 同 key 覆盖 → 撤销恢复前一个（换实现零改动）
- 事件四模式: EMIT（观察）/ WATERFALL（中间件）/ PARALLEL（并发）/ SERIAL（顺序加工）
  ——插件间通信机制, 框架职责, 不是业务胶水
- 会话信封 Task（可选）: 多插件协作统一上下文（身份/工作区/元数据/轮次）
- 装配可计算: mounted() / aic graph（装配/依赖/能力/事件 → graph-viz.html）
- 工具: aic init / template（骨架与模板, 代码可见可改）

## 示例应用（真实业务验证）

```
demo/          文件转换（converter 业务插件 + extract 公共插件）
review_app/    审查（extract/standard/engine 公共插件 + service 普通模块）
constplan_app/ 施工方案编写（迁移自 ConstPlan: 分章并行→合并→渲染→版本化）
```

- 业务 = 普通模块普通函数, 唯一 AIC 痕迹 = `ctx.get("...")` 取能力（像用 NumPy）
- 公共能力 = 插件, `mount` 注入; 换引擎 = 同 key 覆盖（业务零改动）
- 落盘 = 直接写文件（无产物通道）; DB/Celery/MinIO 等生产化设施 = 普通库用法

## 不做的事

- 不强制业务进插件（业务默认写在 app.py/普通模块, 可复用才抽）
- 不预设会话模型（业务自己管状态, 落盘直接写文件）
- 无壳布局契约 / 无注入声明 / 无 promote 上浮（插件平铺, 无私有公共之分）
- HTTP/路由不归 AIC 管（应用直接用 FastAPI, 零新概念）

## 打包安装

```bash
pip install -e prototype      # 装 ai-composer 3.0 → aic 命令全局可用
# 注意: 与旧版 ai-composer（同名 aic 包）冲突, 正式切换需先卸载旧版
```
