kenaz 0.3.18 → 0.3.20

package/core/.failure/architecture/FAIL-006-python-version-compatibility.yaml

@@ -1,445 +0,0 @@
-# FAIL-006: Python 3.14 依赖兼容性问题
-
-_meta:
-  id: "FAIL-006"
-  category: "architecture"
-  severity: "high"
-  date: "2026-02-07"
-  related_tasks: []
-  related_commits: ["b99f741"]
-  components:
-    - "dashboard/srv/app/cortex_service.py"
-    - "kenaz-cortex/"
-  tags:
-    - "python"
-    - "dependencies"
-    - "chromadb"
-    - "pydantic"
-
-## 失败描述
-
-**问题**：Cortex Service 启动失败，无法导入 ChromaDB 模块。
-
-**预期行为**：
-```bash
-cd dashboard/srv/app
-python cortex_service.py
-# 应该成功启动 FastAPI 服务在 http://localhost:8000
-```
-
-**实际结果**：
-```
-pydantic.v1.errors.ConfigError: unable to infer type for attribute "chroma_server_nofile"
-```
-
-**完整错误信息**：
-```python
-Traceback (most recent call last):
-  File "dashboard/srv/app/cortex_service.py", line 29, in <module>
-    from cortex.api.search import CortexSearch
-  File "kenaz-cortex/src/cortex/vectordb/chroma.py", line 19, in <module>
-    import chromadb
-  File ".../chromadb/config.py", line 120, in <module>
-    class Settings(BaseSettings):  # Pydantic V1
-  ...
-pydantic.v1.errors.ConfigError: unable to infer type for attribute "chroma_server_nofile"
-
-Warning: Core Pydantic V1 functionality isn't compatible with Python 3.14 or greater.
-```
-
-## 根本原因
-
-### 技术分析
-
-1. **Python 版本太新**：
-   - 当前环境：Python 3.14.2 (2025 年底发布)
-   - Pydantic V1 最高支持：Python 3.13
-
-2. **依赖链问题**：
-   ```
-   Cortex Service
-     ↓ 导入
-   kenaz-cortex
-     ↓ 导入
-   ChromaDB
-     ↓ 依赖
-   Pydantic V1 (pydantic.v1)
-     ↓ 不支持
-   Python 3.14
-   ```
-
-3. **Pydantic 迁移状态**：
-   - Pydantic V2 已支持 Python 3.14
-   - ChromaDB 尚未迁移到 Pydantic V2
-   - ChromaDB 仍在使用 `pydantic.v1` 兼容层
-
-### 为什么会发生
-
-- Python 3.14 引入了新的内部 API 变化
-- Pydantic V1 的 Rust 扩展 (pyo3) 不支持 Python 3.14
-- ChromaDB 作为第三方库，更新较慢
-
-## 影响范围
-
-### 受影响的模块
-- ✅ **Cortex Service** (dashboard/srv/app/cortex_service.py) - 无法启动
-- ✅ **kenaz-cortex** - 所有依赖 ChromaDB 的功能
-- ✅ **Dashboard 集成测试** - 无法测试 Backend API
-- ❌ **Dashboard 前端** - 不受影响（Next.js，独立运行）
-
-### 受影响的功能
-- Agent 使用追踪 API (无法启动服务)
-- 文件索引 API (无法启动服务)
-- 语义搜索 API (无法启动服务)
-- Context 构建 API (无法启动服务)
-
-### 潜在的连锁反应
-- 所有依赖 Cortex Service 的集成测试失败
-- 生产环境部署需要确保 Python 版本 <= 3.13
-- CI/CD Pipeline 需要锁定 Python 版本
-
-## 重现步骤
-
-1. **环境准备**：
-   ```bash
-   python --version  # 输出: Python 3.14.2
-   ```
-
-2. **安装依赖**：
-   ```bash
-   cd dashboard/srv
-   pip install -r app/requirements.txt
-   # FastAPI, Uvicorn 安装成功
-   # Pydantic 安装成功 (V2)
-   ```
-
-3. **安装 kenaz-cortex**：
-   ```bash
-   cd ../../kenaz-cortex
-   pip install -e .
-   # ChromaDB 及其依赖安装成功
-   ```
-
-4. **启动服务**：
-   ```bash
-   cd ../dashboard/srv/app
-   python cortex_service.py
-   ```
-
-5. **观察到的错误**：
-   ```
-   pydantic.v1.errors.ConfigError: unable to infer type for attribute "chroma_server_nofile"
-   ```
-
-## 解决方案
-
-### 方案 1：降级 Python 到 3.13（推荐）✅
-
-**优点**：
-- 最简单、最直接
-- 完全兼容现有依赖
-- 无需修改代码
-
-**步骤**：
-
-#### Windows
-```bash
-# 1. 安装 Python 3.13
-winget install Python.Python.3.13
-
-# 2. 验证安装
-py -3.13 --version  # 应输出: Python 3.13.x
-
-# 3. 重新安装依赖
-py -3.13 -m pip install -r dashboard/srv/app/requirements.txt
-cd kenaz-cortex
-py -3.13 -m pip install -e .
-
-# 4. 启动服务
-py -3.13 dashboard/srv/app/cortex_service.py
-```
-
-#### Linux/macOS
-```bash
-# 使用 pyenv 管理 Python 版本
-pyenv install 3.13.0
-pyenv local 3.13.0
-
-# 重新安装依赖
-pip install -r dashboard/srv/app/requirements.txt
-cd kenaz-cortex && pip install -e .
-
-# 启动服务
-python dashboard/srv/app/cortex_service.py
-```
-
-### 方案 2：使用 Docker 隔离环境（生产推荐）🐳
-
-**优点**：
-- 环境隔离，避免版本冲突
-- 可复现的构建
-- 适合生产部署
-
-**步骤**：
-
-创建 `dashboard/srv/Dockerfile`：
-```dockerfile
-FROM python:3.13-slim
-
-WORKDIR /app
-
-# 安装系统依赖
-RUN apt-get update && apt-get install -y git
-
-# 复制依赖文件
-COPY app/requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# 安装 kenaz-cortex
-COPY ../../kenaz-cortex /kenaz-cortex
-RUN pip install -e /kenaz-cortex
-
-# 复制应用代码
-COPY app/ ./app/
-
-EXPOSE 8000
-
-CMD ["python", "app/cortex_service.py"]
-```
-
-创建 `dashboard/srv/docker-compose.yml`：
-```yaml
-version: '3.8'
-
-services:
-  cortex-service:
-    build: .
-    ports:
-      - "8000:8000"
-    volumes:
-      - ../../kenaz-cortex:/kenaz-cortex:ro
-      - ./app:/app/app:ro
-    environment:
-      - LOG_LEVEL=info
-    restart: unless-stopped
-```
-
-启动：
-```bash
-cd dashboard/srv
-docker-compose up -d
-```
-
-### 方案 3：虚拟环境（开发推荐）📦
-
-**优点**：
-- 不影响系统 Python
-- 可以并行多个版本
-
-**步骤**：
-
-#### Windows
-```bash
-# 1. 创建虚拟环境（使用 Python 3.13）
-py -3.13 -m venv venv-cortex
-
-# 2. 激活虚拟环境
-.\venv-cortex\Scripts\activate
-
-# 3. 安装依赖
-pip install -r dashboard/srv/app/requirements.txt
-cd kenaz-cortex && pip install -e .
-
-# 4. 启动服务
-python dashboard/srv/app/cortex_service.py
-
-# 5. 退出虚拟环境
-deactivate
-```
-
-#### Linux/macOS
-```bash
-# 1. 创建虚拟环境
-python3.13 -m venv venv-cortex
-
-# 2. 激活虚拟环境
-source venv-cortex/bin/activate
-
-# 3. 安装依赖
-pip install -r dashboard/srv/app/requirements.txt
-cd kenaz-cortex && pip install -e .
-
-# 4. 启动服务
-python dashboard/srv/app/cortex_service.py
-
-# 5. 退出虚拟环境
-deactivate
-```
-
-### 方案 4：等待 ChromaDB 更新（不推荐）⏳
-
-**说明**：等待 ChromaDB 完全迁移到 Pydantic V2 并支持 Python 3.14。
-
-**时间线**：未知（可能需要数月）
-
-**不推荐原因**：阻塞开发进度
-
-## 预防措施
-
-### 检查清单（开发环境设置）
-
-- [ ] **检查 Python 版本**
-  ```bash
-  python --version
-  # 应该是 3.13.x 或更早
-  ```
-
-- [ ] **锁定 Python 版本（项目级别）**
-  - 创建 `.python-version` 文件：
-    ```
-    3.13
-    ```
-  - 或使用 `pyproject.toml`：
-    ```toml
-    [tool.poetry.dependencies]
-    python = ">=3.10,<3.14"
-    ```
-
-- [ ] **文档化 Python 版本要求**
-  - 在 `README.md` 中明确说明
-  - 在 `dashboard/srv/README.md` 中添加环境要求
-
-- [ ] **CI/CD 锁定 Python 版本**
-  - GitHub Actions:
-    ```yaml
-    - uses: actions/setup-python@v4
-      with:
-        python-version: '3.13'
-    ```
-
-### 规则建议
-
-如果此失败模式重复出现，建议建立 `.rule/` 规则：
-
-- **规则 ID**: `ARCH-001`
-- **规则标题**: "Python 版本兼容性约束"
-- **规则描述**: |
-    所有 Python 依赖必须在项目开始时锁定版本范围。
-    使用 pyproject.toml 或 .python-version 明确指定支持的 Python 版本。
-    CI/CD 必须使用与生产环境一致的 Python 版本。
-- **严重程度**: `must`
-
-## 教训与启示
-
-### 1. 依赖管理的重要性
-
-**教训**：新 Python 版本并不总是向后兼容第三方库。
-
-**启示**：
-- 在生产项目中，应该使用 LTS（Long Term Support）版本
-- Python 3.13 是当前稳定版本，3.14 仍处于早期阶段
-- 第三方库（如 ChromaDB）的更新滞后于 Python 新版本
-
-### 2. 版本锁定的必要性
-
-**教训**：未锁定 Python 版本导致环境不一致。
-
-**启示**：
-- 使用 `.python-version` 或 `pyproject.toml` 锁定版本
-- 在 `README.md` 中明确环境要求
-- CI/CD 必须使用固定版本
-
-### 3. 测试环境与生产环境一致性
-
-**教训**：开发环境使用最新 Python 可能导致生产问题。
-
-**启示**：
-- 开发、测试、生产环境应使用相同的 Python 版本
-- 使用 Docker 确保环境一致性
-- 定期检查依赖的兼容性
-
-### 4. 依赖链的复杂性
-
-**教训**：一个深层依赖（Pydantic V1）的限制影响整个服务。
-
-**启示**：
-- 选择依赖时考虑其维护状态和更新速度
-- 关注依赖的依赖（transitive dependencies）
-- 考虑使用更活跃维护的替代方案
-
-### 5. 渐进式升级策略
-
-**教训**：盲目升级到最新版本可能带来意外问题。
-
-**启示**：
-- 遵循 "不要在星期五升级" 原则
-- 使用 N-1 版本策略（使用倒数第二个稳定版本）
-- 升级前在隔离环境测试
-
-## 验证修复
-
-### 验证步骤
-
-1. **确认 Python 版本**：
-   ```bash
-   python --version
-   # 应输出: Python 3.13.x
-   ```
-
-2. **重新安装依赖**：
-   ```bash
-   pip install -r dashboard/srv/app/requirements.txt
-   cd kenaz-cortex && pip install -e .
-   ```
-
-3. **启动 Cortex Service**：
-   ```bash
-   python dashboard/srv/app/cortex_service.py
-   ```
-
-4. **验证服务运行**：
-   ```bash
-   curl http://localhost:8000/
-   # 应返回: {"service": "Kenaz Cortex Service", "version": "2.0.0", "status": "running"}
-   ```
-
-5. **测试 API 端点**：
-   ```bash
-   # 测试 Agent 使用记录
-   curl "http://localhost:8000/api/usage/agents?project_path=/path/to/project&limit=5"
-
-   # 测试文件索引
-   curl -X POST "http://localhost:8000/api/index/file?project_path=/path/to/project" \
-     -H "Content-Type: application/json" \
-     -d '{"file_path": "test.py"}'
-   ```
-
-### 成功标准
-
-- ✅ Cortex Service 启动无错误
-- ✅ 健康检查端点返回正确 JSON
-- ✅ 所有新增 API 端点响应正常
-- ✅ ChromaDB 可以正常导入和使用
-
-## 相关链接
-
-### 官方文档
-- [Python 3.14 Release Notes](https://docs.python.org/3.14/whatsnew/3.14.html)
-- [Pydantic V2 Migration Guide](https://docs.pydantic.dev/latest/migration/)
-- [ChromaDB Documentation](https://docs.trychroma.com/)
-
-### Issue Tracker
-- [ChromaDB Pydantic V2 Migration](https://github.com/chroma-core/chroma/issues)
-- [Pydantic Python 3.14 Support](https://github.com/pydantic/pydantic/issues)
-
-### 类似问题
-- FAIL-001: Agent 执行无输出问题
-- FAIL-005: 背景 Agent 无写入权限
-
-## 元数据
-
-**创建日期**: 2026-02-07
-**最后更新**: 2026-02-07
-**状态**: Resolved (使用方案 1: 降级 Python)
-**影响**: 10 个文件（Cortex Service + kenaz-cortex）
-**修复时间**: ~15 分钟（安装 Python 3.13 + 重装依赖）