ai-composer

AIComposer 3.0.0

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

教程（aic/tutorial/ 随 pip 包; 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 迁移形态）
06-sdk-reference.md  SDK 参考（3.0.0 完整 API）

怎么跑

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）。

框架包结构（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, 零新概念）

打包安装

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