psi-agent 0.0.1a2__tar.gz

psi_agent-0.0.1a2/.git

@@ -0,0 +1 @@
+gitdir: /home/hzhangxyz/Cloud/Desktop/psi/.git/worktrees/dev

psi_agent-0.0.1a2/.github/workflows/ci.yml

@@ -0,0 +1,90 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint-and-unit-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+      fail-fast: false
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for hatch-vcs versioning
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies with Python ${{ matrix.python-version }}
+        run: uv sync --all-extras --python ${{ matrix.python-version }}
+
+      - name: Run ruff check
+        run: uv run ruff check examples/ tests/ src/
+
+      - name: Run ruff format check
+        run: uv run ruff format examples/ tests/ src/ --check
+
+      - name: Run ty type check
+        run: uv run ty check examples/ tests/ src/
+
+      - name: Run pytest (unit tests only)
+        run: uv run pytest tests/unit/ -v
+
+  integration-test:
+    runs-on: ubuntu-latest
+    needs: lint-and-unit-test
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for hatch-vcs versioning
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: uv sync --all-extras --python 3.12
+
+      - name: Run integration tests
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          OPENAI_BASE_URL: ${{ secrets.OPENAI_BASE_URL }}
+          OPENAI_MODEL: ${{ secrets.OPENAI_MODEL }}
+        run: uv run pytest tests/integration/ -v
+
+  publish:
+    runs-on: ubuntu-latest
+    needs: [lint-and-unit-test, integration-test]
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment: pypi
+
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required for hatch-vcs versioning
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v4

psi_agent-0.0.1a2/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# uv
+.uv/
+
+# Sockets
+*.sock
+
+# Session state databases
+example_workspace/state/*.db
+*.db
+
+# Workspace overlay directories
+*.upper/
+*.work/
+*.lower/
+
+# Manifest (runtime generated)
+manifest.json
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+
+# Test coverage
+.coverage
+coverage.xml
+htmlcov/
+.pytest_cache/
+
+# SquashFS images
+*.sqfs

psi_agent-0.0.1a2/CLAUDE.md

@@ -0,0 +1,313 @@
+# Psi Agent Platform
+
+一个绿色可移植的 AI Agent 平台，由独立的模块通过 Unix socket 通信组成。
+
+## 快速开始
+
+```bash
+# 1. 启动 LLM Caller
+uv run psi-ai-openai --session-socket ./ai.sock \
+    --model qwen3.5-plus \
+    --api-key $API_KEY \
+    --base-url https://coding.dashscope.aliyuncs.com/v1
+
+# 2. 启动 Session
+uv run psi-session --workspace ./examples/simple_example \
+    --channel-socket ./channel.sock \
+    --ai-socket ./ai.sock
+
+# 3. 启动 TUI
+uv run psi-channel-tui --session-socket ./channel.sock
+```
+
+## 项目结构
+
+```
+src/
+├── psi_agent/         # Psi Agent 包
+│   ├── session/       # ReAct 循环引擎（核心）
+│   ├── channel/tui/   # TUI 用户界面
+│   ├── ai/openai/     # OpenAI 兼容 LLM Caller
+│   ├── workspace/     # SquashFS/OverlayFS 管理器
+│   └── common/        # 共享协议
+
+examples/
+└── simple_example/     # 示例 workspace
+```
+
+## 核心概念
+
+### Workspace
+
+一个 workspace 是一个完整的 agent，包含：
+- `AGENT.md`: 身份描述
+- `tools/`: 工具（每个 .py 导出 `async run(params, workspace_path)`)
+- `skills/`: 技能（SKILL.md 格式）
+- `systems/builder.py`: 系统提示词构造器
+
+### 通信协议
+
+所有模块通过 Unix socket 通信，使用 JSON Lines 格式：
+
+- Session ↔ AI: OpenAI Chat Completion 格式（流式）
+- Session ↔ Channel: `{"role": "user/assistant", "content": "..."}`
+
+### ReAct 循环
+
+Session 接收用户消息后：
+1. 构建 system prompt（通过 builder.py）
+2. 调用 LLM
+3. 如果有 tool_calls → 执行工具 → 继续循环
+4. 如果无 tool_calls → 返回文本给 Channel
+
+## 设计原则
+
+### Let it Crash
+
+核心原则：**除了外部网络故障，所有错误都应该让进程 crash**。
+
+**分类说明:**
+
+| 类型 | 处理方式 | 示例 |
+|------|----------|------|
+| 外部用户连接断开 | 优雅处理 | Channel断开（用户Ctrl+C/Ctrl+D） |
+| 外部LLM API问题 | 优雅处理或crash | API超时、认证错误（让OpenAI SDK报错） |
+| 组件间连接异常 | **crash** | AI Caller断开（未发送done）、Session断开 |
+| 配置错误 | **crash** | API key缺失、文件不存在、参数无效 |
+| 数据错误 | **crash** | JSON解析失败、schema不匹配 |
+| 业务逻辑错误 | **crash** | 工具不存在、版本链断裂 |
+
+**具体规则:**
+
+1. **启动时配置错误**: 不要额外检查，让系统自然crash并给出错误信息
+   - 例：API key缺失 → 让OpenAI SDK初始化时报错，不要提前检查并sys.exit()
+   
+2. **组件间连接**: 假设连接正常，异常时直接crash
+   - 例：AI Caller发送流式响应但未发送`done`标记就断开 → Session应该crash（`RuntimeError`）
+   
+3. **工具执行错误**: **不crash**，返回错误给LLM
+   - 工具级别错误（如命令不存在）应返回`{"success": False, "error": "..."}`
+   - Session继续运行，让LLM决定下一步
+   
+4. **用户主动退出**: **优雅处理**
+   - KeyboardInterrupt/EOFError → 打印退出信息，清理资源，退出
+   
+5. **可选功能缺失**: 优雅处理（warning/return），不crash
+   - tools目录不存在 → warning并继续
+   - skills目录不存在 → warning并继续
+   - snapshot无改动 → warning并return
+   
+### 其他原则
+
+- **绿色可移植**: workspace 可整体复制/移动
+- **组件化**: 独立进程，socket 通信
+- **不考虑兼容性**: 目前是第一版，不需要向后兼容，可直接删除旧代码
+
+## 日志
+
+所有模块使用 loguru：
+```
+2026-04-20 18:03:42 | INFO | session | Session initialized | id=test
+```
+
+控制级别：`--log-level DEBUG/INFO/WARNING/ERROR`
+
+**TUI 特殊处理**：默认 `WARNING` 级别，避免日志干扰界面。
+
+## 数据模型
+
+使用 pydantic BaseModel：
+- `LLMRequest`/`LLMResponse`: LLM 通信
+- `ToolResult`: 工具结果
+- `UserMessage`/`AssistantMessage`: Channel ↔ Session 通信
+- `DeltaInfo`/`Manifest`/`MountInfo`: Workspace 元数据
+
+**模型使用约定**:
+- 所有协议通信应使用定义的模型（如 Channel 使用 `UserMessage`/`AssistantMessage` 而非 raw dict）
+- 内部方法传递完整对象而非逐个提取字段
+
+## Session 默认行为
+
+Session 默认使用自动生成的 uuid 作为 session_id，因此：
+- **不提供 session_id 时**：每次启动都是新 session，无历史记录
+- **提供 session_id 时**：继续该 session 的历史（如 `--session-id main`）
+
+这是为了让"默认行为无历史"更符合直觉。
+
+## 开发
+
+本仓库使用 **ruff** (lint/格式化) 和 **ty** (类型检查) 进行代码质量控制。
+
+```bash
+# Lint 检查
+uv run ruff check examples/ tests/ src/
+uv run ruff check --fix examples/ tests/ src/
+
+# 格式检查
+uv run ruff format examples/ tests/ src/ --check
+
+# 类型检查
+uv run ty check examples/ tests/ src/
+
+# 测试
+uv run pytest tests/unit/ -v
+
+# 集成测试（需要设置环境变量）
+export OPENAI_API_KEY="your-api-key"
+export OPENAI_BASE_URL="https://api.openai.com/v1"
+export OPENAI_MODEL="gpt-4o-mini"
+uv run pytest tests/integration/ -v
+```
+
+**CI/CD**: GitHub Actions 自动运行 ruff check、ruff format、ty 和测试（`.github/workflows/test.yml`）。
+
+**CLI**: 所有命令使用 tyro 实现，参数通过 dataclass 定义。
+
+## 常用命令
+
+```bash
+# 安装依赖
+uv sync
+
+# 运行测试
+uv run psi-session --workspace ./examples/simple_example ...
+
+# Workspace 管理（使用 FUSE，无需 root）
+# 先安装依赖: sudo apt install squashfuse fuse-overlayfs squashfs-tools
+psi-workspace-create ./examples/simple_example base.sqfs --tag base
+psi-workspace-mount base.sqfs ./workspace
+psi-workspace-snapshot ./workspace v2.sqfs --tag v1
+psi-workspace-umount ./workspace
+```
+
+## Python API
+
+所有模块同时提供 Python function 接口：
+
+```python
+from psi_agent.session import run_session
+from psi_agent.ai.openai import run_ai
+from psi_agent.channel.tui import run_channel
+from psi_agent.workspace import run_create, run_mount, run_umount, run_snapshot
+
+# 启动 AI Caller
+await run_ai(
+    session_socket="./ai.sock",
+    model="qwen3.5-plus",
+    api_key="...",
+    base_url="https://coding.dashscope.aliyuncs.com/v1",
+    log_level="INFO"
+)
+
+# 启动 Session
+await run_session(
+    workspace_path="./examples/simple_example",
+    channel_socket="./channel.sock",
+    ai_socket="./ai.sock",
+    session_id="main",
+    log_level="INFO"
+)
+
+# 启动 TUI
+await run_channel(session_socket="./channel.sock")
+
+# Workspace 管理
+await run_create("./examples/simple_example", "base.sqfs", tag="base")
+await run_mount("base.sqfs", "./workspace")
+await run_snapshot("./workspace", "v2.sqfs", tag="v1")
+await run_umount("./workspace")
+
+# Workspace 管理（需要 root）
+await run_mount("agent.sqfs", "./workspace")
+await run_unmount("./workspace")
+await run_snapshot("./workspace", "new.sqfs", description="v2")
+run_list("./workspace")
+```
+
+## 详细规格
+
+见 `SPEC.md`。
+
+## 代码风格
+
+### 类设计
+
+- **内部状态用私有属性**: 类内部状态用 `_` 前缀（如 `_messages`, `_tools`, `_workspace_path`）
+- **配置用 Pydantic**: 配置参数封装在 `SessionConfig` 等 Pydantic model 中
+- **配置与实现分离**: 配置类只存参数，业务类接收配置对象
+
+### 函数设计
+
+- **辅助函数独立**: 通用辅助函数独立定义（如 `_is_valid_tool_call_name`, `_load_python_module`)
+- **函数有单一职责**: 每个函数只做一件事，名字描述职责
+- **缓存复用**: 重复加载的资源缓存（如 `_builder_module`）
+- **参数类型一致**: 私有方法参数类型应统一（如全部用 `Path` 而非混用 `str` 和 `Path`)
+- **参数命名一致**: 内部变量名与参数名保持一致（如 `source_dir` → `source_dir`，不要改成 `source`）
+- **数据模型统一**: 同一模块内的相似操作应使用相同的数据模型（如 `_handle_stream` 和 `_handle_non_stream` 都用 `LLMRequest` 对象）
+- **传递对象而非字段**: 内部方法应传递完整的 request/response 对象，而非逐个提取字段传递（避免 adhoc 参数列表）
+- **接口简洁**: 
+  - 数据处理放在调用方而非被调用方（如JSON序列化在发送方完成）
+  - 类型转换尽量靠近数据源（如Path转换在参数入口处完成）
+- **避免过度封装**: 简单逻辑不需要额外抽象，三行重复代码比过早抽象更好
+
+### 代码组织
+
+- **模块顶部 import**: 所有 import 放文件顶部，不在函数内部 import
+- **类型注解**: 所有函数参数和返回值有类型注解
+- **docstring 简洁**: docstring 只说明功能，不写冗余说明
+
+### 日志风格
+
+- **格式统一**: `logger.info("Action | key={value}")` 格式，用 `|` 分隔
+- **级别合理**: 
+  - `INFO`: 重要状态变化（初始化、连接、完成）
+  - `DEBUG`: 详细过程（参数、中间状态）
+  - `WARNING`: 预期内的异常情况
+  - `ERROR`: 错误和失败
+
+### 其他约定
+
+- **避免 ad-hoc**: 不写重复逻辑，提取为辅助函数
+- **f-string 有变量**: f-string 必须有插值，否则用普通字符串
+- **is 比较**: `True/False/None` 用 `is` 比较，不用 `==`
+
+### 命名风格
+
+#### CLI 参数命名
+
+- **snake_case**: 所有 CLI 参数使用 snake_case（如 `channel_socket`, `log_level`）
+- **位置参数**: 简短单词（如 `workspace`, `model`, `output`）
+- **socket 参数**: `*_socket` 格式（如 `channel_socket`, `ai_socket`, `session_socket`）
+- **log_level**: 所有模块统一有 `log_level` 参数
+
+#### 文件命名
+
+- **模块目录**: `psi_agent/<name>` 格式（如 `psi_agent/session`, `psi_agent/ai`, `psi_agent/channel`, `psi_agent/workspace`）
+- **Python 文件**: snake_case（如 `builder.py`, `protocol.py`）
+- **配置文件**: 小写无扩展名约定（如 `AGENT.md`, `SKILL.md`）
+
+#### 变量命名
+
+- **私有属性**: `_` 前缀（如 `_messages`, `_tools`, `_config`）
+- **常量**: UPPER_CASE 或 snake_case（如 `MAX_ITERATIONS` 或 `max_iterations`）
+- **函数**: snake_case（如 `load_tools`, `build_system_prompt`）
+- **类**: PascalCase（如 `Session`, `SessionConfig`, `WorkspaceManager`）
+
+#### Socket 命名
+
+**变量命名（代码中）:**
+- `session_socket`: AI Caller 监听的 socket（Session 连接到此）
+- `channel_socket`: Session 监听的 socket（Channel 连接到此）
+- `ai_socket`: Session 连接 AI 的 socket（与 AI 的 `session_socket` 对应）
+
+**文件命名（示例和测试）:**
+- `ai.sock`: AI Caller socket 文件
+- `channel.sock`: Channel/Session socket 文件
+
+**路径原则:**
+- 生产环境：相对路径（如 `./channel.sock`, `./ai.sock`）
+- 测试环境：pytest `tmp_path` fixture（如 `tmp_path / "channel.sock"`）
+
+#### 数据库/JSON 字段
+
+- **snake_case**: 与 Python 保持一致（如 `session_id`, `created_at`）