ai-composer 0.1.0__tar.gz

ai_composer-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: ai-composer
+Version: 0.1.0
+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 应用开发范式（Composer）——内核提供机制，
+> 插件提供能力，应用壳做组合。加不同业务插件 = 不同应用。
+
+---
+
+## 一、范式一句话
+
+```
+应用 = 平台内核 + 业务插件组合
+```
+
+- **内核**（`kernel/kernel.py`，~230 行，零能力零业务）：服务注册表 / 事件总线(4 模式) / 挂载卸载(可逆效果) / 拓扑装配——只提供"机制"
+- **插件**（`extensions/*`）：能力提供方——协议 + 多实现 + 插件包装，三件套结构
+- **应用壳**（`apps/mvp/`）：组合者——选插件、传参数、暴露 HTTP 入口，不实现能力
+
+## 二、核心保证（全部实证）
+
+| 保证 | 实证 |
+|------|------|
+| 自动装配 | inject 依赖 → 拓扑排序（乱序传入自动推导） |
+| 自动销毁 | unmount 零残留、不误伤他插件（效果桶 + dispose 守卫） |
+| 任意替换 | 假引擎→Hermes→降级引擎、LocalStorage→MemoryStorage、Thread→Celery，消费方零改动 |
+| 业务即插件 | writer 业务插件独立挂载；加新业务 = 新插件 |
+| 基础设施插件化 | config/telemetry/storage/cache/jobs 与业务插件完全同构 |
+| 降级矩阵 | Failover 包装：Celery↔线程池、主引擎↔备用，broker 黑洞端口不挂起 |
+| 可运行闭环 | FastAPI + Redis + Celery worker 端到端真实执行 |
+
+## 三、快速开始
+
+```bash
+# 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）
+```
+
+## 五、设计文档导航
+
+| 文档 | 内容 |
+|------|------|
+| [docs/tutorial/index.md](docs/tutorial/index.md) | **官方教程（0.1）**——安装→快速开始→第一个插件→应用壳→工具链→最佳实践 |
+| [docs/learn/foundation.md](docs/learn/foundation.md) | **入门基础篇**（范式一句话→插件调用→三步法→会话产物→6 站完整流程，新人第一份讲解） |
+| [docs/learn/tutorial-build-app.md](docs/learn/tutorial-build-app.md) | **从零搭一个应用**（需求→三步法→写插件→写壳→跑通→换清单变应用，概念收拢篇） |
+| [docs/learn/tool-closed-loop.md](docs/learn/tool-closed-loop.md) | **工具闭环**（init 装 ↔ graph 看 ↔ uninstall 卸, 三命令共享同一套事实） |
+| [docs/learn/session-artifact-concept.md](docs/learn/session-artifact-concept.md) | **核心概念**（会话/产物/执行形态，理解范式第一概念） |
+| [docs/design/business-organization.md](docs/design/business-organization.md) | **新开发者上手包**（三步法 + 三层写法 + 协议速查，先读这个） |
+| [docs/api.md](docs/api.md) | MVP 应用 API 接口文档（供测试调用） |
+| [docs/test-api.md](docs/test-api.md) | 示例应用测试 API（file-convert/todo, curl 速查） |
+| [docs/design/architecture.md](docs/design/architecture.md) | 本范式架构设计（总览） |
+| [docs/design/kernel-design.md](docs/design/kernel-design.md) | 内核设计（协议清单/机制/验收标准） |
+| [docs/design/kernel-principles.md](docs/design/kernel-principles.md) | 内核原理通俗讲解（分幕代码走查） |
+| [docs/design/template-boundary.md](docs/design/template-boundary.md) | 业务耦合点清单（提炼依据） |
+| [docs/design/writer-app-architecture.md](docs/design/writer-app-architecture.md) | 参考业务应用架构（业务即插件模型） |
+| [docs/design/review-app-architecture.md](docs/design/review-app-architecture.md) | 审查应用重构架构（strangler: 壳 + review 插件, 全量对标） |
+| [docs/design/module-promotion.md](docs/design/module-promotion.md) | **上浮原则**（插件内部分层/何时子域上浮为独立插件, 重构 vs 新项目） |
+| [docs/design/organization-contract.md](docs/design/organization-contract.md) | **组织契约**（应用壳/任务名协议机制强制; 强制/约定/不强制三档 + 决策树） |
+| [docs/design/verification-summary.md](docs/design/verification-summary.md) | 技术验证成果总结（127 项全绿 + MVP） |
+| [docs/design/milestones/](docs/design/milestones/) | 里程碑文档（M0~M4d 完成, 后续预填） |
+
+## 六、研究路线
+
+```
+已完成: 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 进度推送 → 平台版本化
+```
+
+## 七、快速验证端到端
+
+```bash
+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 章
+```

ai_composer-0.1.0/README.md

@@ -0,0 +1,169 @@
+# AIComposer — AI 应用开发范式
+
+> **应用 = 平台内核 + 业务插件组合**：AI 应用开发范式（Composer）——内核提供机制，
+> 插件提供能力，应用壳做组合。加不同业务插件 = 不同应用。
+
+---
+
+## 一、范式一句话
+
+```
+应用 = 平台内核 + 业务插件组合
+```
+
+- **内核**（`kernel/kernel.py`，~230 行，零能力零业务）：服务注册表 / 事件总线(4 模式) / 挂载卸载(可逆效果) / 拓扑装配——只提供"机制"
+- **插件**（`extensions/*`）：能力提供方——协议 + 多实现 + 插件包装，三件套结构
+- **应用壳**（`apps/mvp/`）：组合者——选插件、传参数、暴露 HTTP 入口，不实现能力
+
+## 二、核心保证（全部实证）
+
+| 保证 | 实证 |
+|------|------|
+| 自动装配 | inject 依赖 → 拓扑排序（乱序传入自动推导） |
+| 自动销毁 | unmount 零残留、不误伤他插件（效果桶 + dispose 守卫） |
+| 任意替换 | 假引擎→Hermes→降级引擎、LocalStorage→MemoryStorage、Thread→Celery，消费方零改动 |
+| 业务即插件 | writer 业务插件独立挂载；加新业务 = 新插件 |
+| 基础设施插件化 | config/telemetry/storage/cache/jobs 与业务插件完全同构 |
+| 降级矩阵 | Failover 包装：Celery↔线程池、主引擎↔备用，broker 黑洞端口不挂起 |
+| 可运行闭环 | FastAPI + Redis + Celery worker 端到端真实执行 |
+
+## 三、快速开始
+
+```bash
+# 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）
+```
+
+## 五、设计文档导航
+
+| 文档 | 内容 |
+|------|------|
+| [docs/tutorial/index.md](docs/tutorial/index.md) | **官方教程（0.1）**——安装→快速开始→第一个插件→应用壳→工具链→最佳实践 |
+| [docs/learn/foundation.md](docs/learn/foundation.md) | **入门基础篇**（范式一句话→插件调用→三步法→会话产物→6 站完整流程，新人第一份讲解） |
+| [docs/learn/tutorial-build-app.md](docs/learn/tutorial-build-app.md) | **从零搭一个应用**（需求→三步法→写插件→写壳→跑通→换清单变应用，概念收拢篇） |
+| [docs/learn/tool-closed-loop.md](docs/learn/tool-closed-loop.md) | **工具闭环**（init 装 ↔ graph 看 ↔ uninstall 卸, 三命令共享同一套事实） |
+| [docs/learn/session-artifact-concept.md](docs/learn/session-artifact-concept.md) | **核心概念**（会话/产物/执行形态，理解范式第一概念） |
+| [docs/design/business-organization.md](docs/design/business-organization.md) | **新开发者上手包**（三步法 + 三层写法 + 协议速查，先读这个） |
+| [docs/api.md](docs/api.md) | MVP 应用 API 接口文档（供测试调用） |
+| [docs/test-api.md](docs/test-api.md) | 示例应用测试 API（file-convert/todo, curl 速查） |
+| [docs/design/architecture.md](docs/design/architecture.md) | 本范式架构设计（总览） |
+| [docs/design/kernel-design.md](docs/design/kernel-design.md) | 内核设计（协议清单/机制/验收标准） |
+| [docs/design/kernel-principles.md](docs/design/kernel-principles.md) | 内核原理通俗讲解（分幕代码走查） |
+| [docs/design/template-boundary.md](docs/design/template-boundary.md) | 业务耦合点清单（提炼依据） |
+| [docs/design/writer-app-architecture.md](docs/design/writer-app-architecture.md) | 参考业务应用架构（业务即插件模型） |
+| [docs/design/review-app-architecture.md](docs/design/review-app-architecture.md) | 审查应用重构架构（strangler: 壳 + review 插件, 全量对标） |
+| [docs/design/module-promotion.md](docs/design/module-promotion.md) | **上浮原则**（插件内部分层/何时子域上浮为独立插件, 重构 vs 新项目） |
+| [docs/design/organization-contract.md](docs/design/organization-contract.md) | **组织契约**（应用壳/任务名协议机制强制; 强制/约定/不强制三档 + 决策树） |
+| [docs/design/verification-summary.md](docs/design/verification-summary.md) | 技术验证成果总结（127 项全绿 + MVP） |
+| [docs/design/milestones/](docs/design/milestones/) | 里程碑文档（M0~M4d 完成, 后续预填） |
+
+## 六、研究路线
+
+```
+已完成: 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 进度推送 → 平台版本化
+```
+
+## 七、快速验证端到端
+
+```bash
+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 章
+```

ai_composer-0.1.0/ai_composer.egg-info/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: ai-composer
+Version: 0.1.0
+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 应用开发范式（Composer）——内核提供机制，
+> 插件提供能力，应用壳做组合。加不同业务插件 = 不同应用。
+
+---
+
+## 一、范式一句话
+
+```
+应用 = 平台内核 + 业务插件组合
+```
+
+- **内核**（`kernel/kernel.py`，~230 行，零能力零业务）：服务注册表 / 事件总线(4 模式) / 挂载卸载(可逆效果) / 拓扑装配——只提供"机制"
+- **插件**（`extensions/*`）：能力提供方——协议 + 多实现 + 插件包装，三件套结构
+- **应用壳**（`apps/mvp/`）：组合者——选插件、传参数、暴露 HTTP 入口，不实现能力
+
+## 二、核心保证（全部实证）
+
+| 保证 | 实证 |
+|------|------|
+| 自动装配 | inject 依赖 → 拓扑排序（乱序传入自动推导） |
+| 自动销毁 | unmount 零残留、不误伤他插件（效果桶 + dispose 守卫） |
+| 任意替换 | 假引擎→Hermes→降级引擎、LocalStorage→MemoryStorage、Thread→Celery，消费方零改动 |
+| 业务即插件 | writer 业务插件独立挂载；加新业务 = 新插件 |
+| 基础设施插件化 | config/telemetry/storage/cache/jobs 与业务插件完全同构 |
+| 降级矩阵 | Failover 包装：Celery↔线程池、主引擎↔备用，broker 黑洞端口不挂起 |
+| 可运行闭环 | FastAPI + Redis + Celery worker 端到端真实执行 |
+
+## 三、快速开始
+
+```bash
+# 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）
+```
+
+## 五、设计文档导航
+
+| 文档 | 内容 |
+|------|------|
+| [docs/tutorial/index.md](docs/tutorial/index.md) | **官方教程（0.1）**——安装→快速开始→第一个插件→应用壳→工具链→最佳实践 |
+| [docs/learn/foundation.md](docs/learn/foundation.md) | **入门基础篇**（范式一句话→插件调用→三步法→会话产物→6 站完整流程，新人第一份讲解） |
+| [docs/learn/tutorial-build-app.md](docs/learn/tutorial-build-app.md) | **从零搭一个应用**（需求→三步法→写插件→写壳→跑通→换清单变应用，概念收拢篇） |
+| [docs/learn/tool-closed-loop.md](docs/learn/tool-closed-loop.md) | **工具闭环**（init 装 ↔ graph 看 ↔ uninstall 卸, 三命令共享同一套事实） |
+| [docs/learn/session-artifact-concept.md](docs/learn/session-artifact-concept.md) | **核心概念**（会话/产物/执行形态，理解范式第一概念） |
+| [docs/design/business-organization.md](docs/design/business-organization.md) | **新开发者上手包**（三步法 + 三层写法 + 协议速查，先读这个） |
+| [docs/api.md](docs/api.md) | MVP 应用 API 接口文档（供测试调用） |
+| [docs/test-api.md](docs/test-api.md) | 示例应用测试 API（file-convert/todo, curl 速查） |
+| [docs/design/architecture.md](docs/design/architecture.md) | 本范式架构设计（总览） |
+| [docs/design/kernel-design.md](docs/design/kernel-design.md) | 内核设计（协议清单/机制/验收标准） |
+| [docs/design/kernel-principles.md](docs/design/kernel-principles.md) | 内核原理通俗讲解（分幕代码走查） |
+| [docs/design/template-boundary.md](docs/design/template-boundary.md) | 业务耦合点清单（提炼依据） |
+| [docs/design/writer-app-architecture.md](docs/design/writer-app-architecture.md) | 参考业务应用架构（业务即插件模型） |
+| [docs/design/review-app-architecture.md](docs/design/review-app-architecture.md) | 审查应用重构架构（strangler: 壳 + review 插件, 全量对标） |
+| [docs/design/module-promotion.md](docs/design/module-promotion.md) | **上浮原则**（插件内部分层/何时子域上浮为独立插件, 重构 vs 新项目） |
+| [docs/design/organization-contract.md](docs/design/organization-contract.md) | **组织契约**（应用壳/任务名协议机制强制; 强制/约定/不强制三档 + 决策树） |
+| [docs/design/verification-summary.md](docs/design/verification-summary.md) | 技术验证成果总结（127 项全绿 + MVP） |
+| [docs/design/milestones/](docs/design/milestones/) | 里程碑文档（M0~M4d 完成, 后续预填） |
+
+## 六、研究路线
+
+```
+已完成: 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 进度推送 → 平台版本化
+```
+
+## 七、快速验证端到端
+
+```bash
+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 章
+```