# 生态架构重塑日志（Eco-Arch Log）

> 目标：确立 **khyos = 生态底座、khyquant = 首款应用**，建立「应用接入标准」，
> 让 khyquant 成为符合标准的示范应用，实现**底座与应用绝对解耦**。
> 执行方式：无人值守一口气执行，保守防呆（不确定就保留+标注，绝不盲删导致崩溃）。

唯一契约文档：[`docs/生态架构/应用接入标准.md`](docs/03_DESIGN_设计/%5BDESIGN-ARCH-011%5D%20应用接入标准.md)

---

## 一、五步执行结果

### 步骤 1 — 剥离硬依赖 → 动态发现 ✅

- 全量扫描 khyos 核心源码（`platform/khy_platform`、`platform/khy_os`）对应用包的导入。
- 结论：**底座核心零应用硬依赖**。`khy_platform` 中不存在任何 `import khy_quant`。
- 唯一对 `khy_quant_backend`（底座**自身** Node 后端的独立打包）的探测，已包在
  `try/except ImportError` 内（`platform/khy_platform/cli.py:62`）——属底座定位自身后端，非依赖应用。
- 底座经 `importlib.metadata` 的 `khyos.apps` entry_points 组 + `~/.khyos/apps/` 注册表目录
  **双路动态发现**应用，有则加载、无则跳过、永不崩溃。

### 步骤 2 — 应用生命周期协议 ✅

- 新建单一真源 [`platform/khy_platform/app_protocol.py`](platform/khy_platform/app_protocol.py)（**零应用导入**）：
  - 路径主权：`base_home()`→`~/.khyos`，`app_home(name)`→`~/.<name>`（含路径穿越防护），
    `STANDARD_SUBDIRS = (data, cache, models, logs)`，`ensure_home()`。
  - 协议基类 `KhyApp`（抽象 `standalone_init()` / `eco_init(ctx)`）+ `AppManifest` / `EcoContext`。
  - 发现：`discover_apps()` 合并 entry_points（优先）与注册表，按 `name` 去重，**任何异常不抛出**。
- `khy apps [--json]` CLI 列出已发现应用（`platform/khy_platform/cli.py:_run_apps_cli`）。

### 步骤 3 — khyquant 双模自适应入口 ✅

- 新建 [`software/khyquant/khy_quant/app.py`](software/khyquant/khy_quant/app.py)：`KhyQuant(KhyApp)` 示范实现，
  对底座标准模块的导入做守卫——**独立安装无底座也不崩溃**。
- `khy_quant/cli.py`：`_detect_mode()`（`KHYOS_ECO_MODE` 优先，否则探测底座 `app_protocol` 可导入，
  默认 `standalone`）+ `_ensure_app_home()`，经 `KHYQUANT_MODE` / `KHYQUANT_HOME` 下传 Node 运行时。
- `pyproject.toml` 声明 `[project.entry-points."khyos.apps"] khyquant = "khy_quant.app:create_app"`。

### 步骤 4 — 底座/应用 DB 物理隔离（路径所有权）✅（解析器层）/ ⚠️（活体迁移留待人工）

- `services/backend/src/utils/dataHome.js` 新增**底座归属解析器** `getBaseHome()`→`~/.khyos`
  （`KHYOS_HOME` 可覆盖）、`getBaseDataDir()`，与应用数据家 `getDataHome()` 物理分离。
- **纯增量、不迁移活体数据**：维持应用现有数据家，保证运行中的 khyquant 不被破坏。
- 真正的「混用硬编码 `~/.khyquant` 与解析器 `~/.khy` 收敛」「底座/应用表物理拆分」
  涉及活体数据迁移 → 见下方 `[Eco-Arch-Unresolved]`，按防呆规则不在无人值守流程内盲目执行。

### 步骤 5 — 模型/缓存/日志路径独立 ✅（标准层）

- 标准固化为 `~/.<app>/{data,cache,models,logs}`，由 `app_protocol.ensure_home()` 统一创建。
- 底座自身落 `~/.khyos/{data,cache,models,logs}`。红线：互不读写对方目录/DB，跨域只走公共 API。

---

## 二、验收证据

| 验收项 | 结果 |
|---|---|
| 协议单测 `tests/unit/test_eco_app_protocol.py` | **9 passed** |
| `dataHome` 底座路径隔离 jest | **4 passed** |
| khyos 核心硬依赖应用包扫描 | **0**（仅 `khy_quant_backend` 守卫探测，try/except） |
| 空环境 `discover_apps()` | `[]`（无应用不崩溃） |
| 写底座注册表 → 再发现 | `~/.khyos/apps/khyquant.json` → `[(khyquant, 0.1.78, registry)]` |
| 数据主权隔离 | `~/.khyos` ≠ `~/.khyquant`，互不为子目录 |
| 示范应用合规 | `isinstance(KhyApp)` 真、双模 init 落 `~/.khyquant/data` |

---

## 三、遗留（`[Eco-Arch-Unresolved]` — 须人工带回滚迁移）

1. **应用数据家收敛**：后端 `getDataHome()` 默认 `~/.khy` 与多个服务硬编码 `~/.khyquant` 混用，
   需统一到单一应用数据家（标注于 `dataHome.js`）。
2. **底座/应用表物理拆分**：把真正归属底座的表/文件迁出到 `~/.khyos/data/khyos.db`，需迁移脚本。

二者均为**活体数据迁移**，无人值守流程内只建立解析器与标准、不动用户现存数据。

---

## 四、改动文件清单

**底座（khyos）**
- `platform/khy_platform/app_protocol.py`（新增·协议/发现/路径主权单一真源）
- `platform/khy_platform/cli.py`（新增 `khy apps` 命令）
- `platform/khy_platform/_bootstrap.py`（注册清单写 `~/.khyos/apps/`，兼容旧位）
- `services/backend/src/utils/dataHome.js`（新增 `getBaseHome` / `getBaseDataDir`，纯增量）
- `tests/unit/test_eco_app_protocol.py`、`services/backend/tests/utils/dataHome.baseHome.test.js`（新增测试）

**应用（khyquant）**
- `software/khyquant/khy_quant/app.py`（新增·KhyApp 示范实现）
- `software/khyquant/khy_quant/cli.py`（双模自适应入口）
- `software/khyquant/pyproject.toml`（声明 `khyos.apps` entry_point）

**文档**
- `docs/生态架构/应用接入标准.md`（生态唯一契约）
- `eco_arch_log.md`（本日志）
