@agentunion/kite 1.5.0 → 1.6.1

package/docs//350/231/232/346/213/237/347/216/257/345/242/203/345/267/245/344/275/234/345/216/237/347/220/206.md

@@ -0,0 +1,163 @@
+# Python 虚拟环境工作原理
+
+## 概述
+
+Python 虚拟环境（venv）**不会拷贝整个 Python 解释器**，而是通过轻量级启动器 + 独立包目录的方式实现环境隔离。
+
+## 虚拟环境结构
+
+```
+~/.kite/venv/
+├── Scripts/ (Windows) 或 bin/ (Linux/macOS)
+│   ├── python.exe          ← 启动器 (250KB)
+│   ├── pip.exe             ← pip 启动器
+│   └── activate.bat        ← 激活脚本
+├── Lib/site-packages/      ← 独立的包目录
+│   ├── fastapi/
+│   ├── uvicorn/
+│   └── ...
+└── pyvenv.cfg              ← 配置文件
+```
+
+## pyvenv.cfg 配置文件
+
+记录了系统 Python 的位置：
+
+```ini
+home = C:\Users\agentcp\AppData\Local\Microsoft\WindowsApps\...
+include-system-site-packages = false
+version = 3.13.12
+executable = C:\...\python.exe
+```
+
+## 工作原理
+
+### 1. 创建虚拟环境
+
+```bash
+python -m venv ~/.kite/venv
+```
+
+**发生了什么：**
+- ✅ 拷贝 `python.exe` 启动器（250KB）
+- ✅ 创建 `pyvenv.cfg` 记录系统 Python 路径
+- ✅ 创建独立的 `site-packages` 目录
+- ✅ 安装 pip 到虚拟环境
+- ❌ **不拷贝** Python 解释器本体（30-50MB）
+- ❌ **不拷贝** 标准库
+
+### 2. 运行虚拟环境的 Python
+
+```bash
+~/.kite/venv/Scripts/python.exe script.py
+```
+
+**执行流程：**
+1. 启动器读取 `pyvenv.cfg`
+2. 找到系统 Python 解释器的真实路径
+3. 调用系统 Python 解释器
+4. 但使用虚拟环境的 `site-packages`
+
+### 3. 文件大小对比
+
+| 文件 | 大小 | 说明 |
+|------|------|------|
+| 虚拟环境 python.exe | 250KB | 启动器 |
+| 系统 python.exe | 30-50MB | 真正的解释器 |
+| 虚拟环境总大小 | 100-200MB | 包含安装的第三方包 |
+
+## 传统激活方式 vs 我们的方式
+
+### 传统方式（需要激活）
+
+```bash
+# 激活虚拟环境
+source ~/.kite/venv/bin/activate  # Linux/macOS
+C:\Users\agentcp\.kite\venv\Scripts\activate.bat  # Windows
+
+# 然后运行
+python main.py
+```
+
+**激活做了什么：**
+- 修改 `PATH` 环境变量，让虚拟环境的 python 优先
+- 修改 `VIRTUAL_ENV` 环境变量
+- 修改命令行提示符（显示 `(venv)`）
+
+### 我们的方式（无需激活）
+
+```python
+# main.py 开头
+import sys
+sys.path.insert(0, "~/.kite/venv/Lib/site-packages")
+```
+
+**直接运行：**
+```bash
+python main.py  # 使用系统 Python，但加载虚拟环境的包
+```
+
+**优势：**
+- 用户无需手动激活
+- 跨平台一致
+- 代码控制，更灵活
+
+## Kite 的实现
+
+### 启动流程
+
+```python
+# main.py
+from core.dependency_checker import check_and_install_dependencies
+
+# 1. 检查虚拟环境是否存在，不存在则创建
+# 2. 将虚拟环境的 site-packages 添加到 sys.path
+# 3. 检查 requirements.txt 中的依赖
+# 4. 缺失的包自动安装到虚拟环境
+# 5. 继续启动 Kite
+```
+
+### 关键代码
+
+```python
+def activate_venv():
+    """将虚拟环境的 site-packages 添加到 sys.path"""
+    site_packages = get_site_packages_path()
+    if site_packages and site_packages not in sys.path:
+        sys.path.insert(0, str(site_packages))
+```
+
+## 优势总结
+
+1. **节省空间**：只拷贝 250KB 启动器，不拷贝 30-50MB 解释器
+2. **快速创建**：创建虚拟环境只需 1-2 秒
+3. **版本一致**：虚拟环境和系统 Python 版本完全一致
+4. **环境隔离**：每个项目的包互不干扰
+5. **无需激活**：我们的方案直接修改 sys.path，用户体验更好
+
+## 常见问题
+
+### Q: 虚拟环境会占用多少空间？
+
+A: 初始约 10MB（pip + setuptools），安装依赖后约 100-200MB。
+
+### Q: 删除虚拟环境会影响系统 Python 吗？
+
+A: 不会。虚拟环境只是一个独立目录，删除后系统 Python 完全不受影响。
+
+### Q: 可以用不同版本的 Python 创建虚拟环境吗？
+
+A: 可以。用哪个 Python 创建，虚拟环境就用哪个版本：
+```bash
+python3.11 -m venv venv_311
+python3.12 -m venv venv_312
+```
+
+### Q: 虚拟环境可以移动到其他目录吗？
+
+A: 不建议。`pyvenv.cfg` 中记录了绝对路径，移动后需要重新创建。
+
+## 参考资料
+
+- Python 官方文档：https://docs.python.org/3/library/venv.html
+- PEP 405：https://peps.python.org/pep-0405/

package/docs//350/256/241/345/210/222/347/256/241/347/220/206/345/231/250/344/275/277/347/224/250/346/214/207/345/215/227.md

@@ -0,0 +1,196 @@
+# 计划管理器使用指南
+
+## 概述
+
+`plan_manager.py` 是 Kite CLI 开发计划的管理工具,用于跟踪任务进度、状态和历史记录。
+
+## 安装
+
+无需安装,直接运行 Python 脚本:
+
+```bash
+cd Kite
+python scripts/plan_manager.py <命令>
+```
+
+## 命令列表
+
+### 1. 列出任务
+
+```bash
+# 列出所有任务
+python scripts/plan_manager.py list
+
+# 只显示 Phase 1 的任务
+python scripts/plan_manager.py list --phase "Phase 1"
+
+# 只显示进行中的任务
+python scripts/plan_manager.py list --status "进行中"
+
+# 组合过滤
+python scripts/plan_manager.py list --phase "Phase 1" --status "待开始"
+```
+
+### 2. 开始任务
+
+```bash
+# 开始任务 (默认负责人: 开发者)
+python scripts/plan_manager.py start "Phase 1.1.1"
+
+# 指定负责人
+python scripts/plan_manager.py start "Phase 1.1.1" --assignee "张三"
+```
+
+### 3. 完成任务
+
+```bash
+# 完成任务
+python scripts/plan_manager.py complete "Phase 1.1.1"
+
+# 完成任务并添加备注
+python scripts/plan_manager.py complete "Phase 1.1.1" --note "已实现版本号解析和下载"
+```
+
+### 4. 阻塞任务
+
+```bash
+# 标记任务为阻塞状态
+python scripts/plan_manager.py block "Phase 1.1.1" "等待 API 文档"
+```
+
+### 5. 解除阻塞
+
+```bash
+# 解除任务阻塞
+python scripts/plan_manager.py unblock "Phase 1.1.1"
+```
+
+### 6. 查看进度
+
+```bash
+# 显示整体进度和各阶段进度
+python scripts/plan_manager.py progress
+```
+
+### 7. 查看历史
+
+```bash
+# 显示最近 10 条操作历史
+python scripts/plan_manager.py history
+
+# 显示最近 20 条
+python scripts/plan_manager.py history --limit 20
+```
+
+## 工作流程示例
+
+### 开始开发一个新功能
+
+```bash
+# 1. 查看待开始的任务
+python scripts/plan_manager.py list --status "待开始"
+
+# 2. 选择一个任务开始
+python scripts/plan_manager.py start "Phase 1.1.1" --assignee "我"
+
+# 3. 查看当前进度
+python scripts/plan_manager.py progress
+
+# 4. 开发过程中遇到阻塞
+python scripts/plan_manager.py block "Phase 1.1.1" "需要先实现依赖功能"
+
+# 5. 阻塞解除后继续
+python scripts/plan_manager.py unblock "Phase 1.1.1"
+
+# 6. 完成任务
+python scripts/plan_manager.py complete "Phase 1.1.1" --note "已实现并测试通过"
+
+# 7. 查看操作历史
+python scripts/plan_manager.py history
+```
+
+## 任务 ID 格式
+
+任务 ID 格式为: `Phase X.Y.Z`
+
+- `X` - Phase 编号 (1-5)
+- `Y` - Phase 内的主任务编号
+- `Z` - 子任务编号
+
+例如:
+- `Phase 1.1.1` - Phase 1 的第 1 个主任务的第 1 个子任务
+- `Phase 2.2.3` - Phase 2 的第 2 个主任务的第 3 个子任务
+
+## 状态说明
+
+- **待开始** - 任务尚未开始
+- **进行中** - 任务正在进行
+- **已完成** - 任务已完成
+- **阻塞** - 任务被阻塞,无法继续
+
+## 数据存储
+
+计划状态保存在: `docs/.cli_plan_state.json`
+
+该文件包含:
+- 所有任务的状态、负责人、时间戳
+- 操作历史记录
+
+**注意**: 该文件应该加入 `.gitignore`,因为它是本地开发状态。
+
+## 与用户交互
+
+当你(AI助手)和用户一起开发时:
+
+1. **开始新任务前**,使用 `list` 查看待开始的任务
+2. **开始任务时**,使用 `start` 标记任务开始
+3. **完成任务后**,询问用户确认,然后使用 `complete` 标记完成
+4. **定期**使用 `progress` 向用户展示进度
+5. **遇到问题时**,使用 `block` 标记阻塞并说明原因
+
+## 示例对话
+
+**AI**: 我们现在开始实现 Phase 1.1.1 版本管理增强功能吗?
+
+**用户**: 好的,开始吧
+
+**AI**:
+```bash
+python scripts/plan_manager.py start "Phase 1.1.1" --assignee "AI+用户"
+```
+[Done] 任务 Phase 1.1.1 已开始
+
+现在我来实现版本号解析功能...
+
+(实现代码...)
+
+**AI**: 功能已实现,请测试一下 `kite install requests@2.28.0`
+
+**用户**: 测试通过了
+
+**AI**:
+```bash
+python scripts/plan_manager.py complete "Phase 1.1.1" --note "已实现版本号解析、下载和安装"
+```
+[Done] 任务 Phase 1.1.1 已完成
+
+让我们查看一下进度:
+```bash
+python scripts/plan_manager.py progress
+```
+
+## 快捷别名 (可选)
+
+可以在 shell 配置文件中添加别名:
+
+```bash
+# ~/.bashrc 或 ~/.zshrc
+alias kite-plan='python /path/to/Kite/scripts/plan_manager.py'
+```
+
+然后就可以使用:
+```bash
+kite-plan list
+kite-plan start "Phase 1.1.1"
+kite-plan complete "Phase 1.1.1"
+```