illusion-code 0.1.0__py3-none-any.whl

illusion/services/session_storage.py

@@ -0,0 +1,237 @@
+"""
+会话持久化辅助模块
+================
+
+本模块提供会话状态持久化功能，支持保存和加载会话快照。
+
+主要功能：
+    - 获取项目会话目录
+    - 保存会话快照
+    - 加载会话快照
+    - 列出会话快照
+    - 导出会话记录为 Markdown
+
+类说明：
+    - get_project_session_dir: 获取项目会话目录
+    - save_session_snapshot: 保存会话快照
+    - load_session_snapshot: 加载会话快照
+    - list_session_snapshots: 列出会话快照
+    - export_session_markdown: 导出为 Markdown
+
+使用示例：
+    >>> from illusion.services.session_storage import get_project_session_dir, save_session_snapshot
+    >>> # 获取项目会话目录
+    >>> session_dir = get_project_session_dir("/path/to/project")
+    >>> # 保存会话快照
+    >>> save_session_snapshot(cwd="/path/to/project", model="claude-3", messages=[...], usage=...)
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from hashlib import sha1
+from pathlib import Path
+from typing import Any
+from uuid import uuid4
+
+from illusion.api.usage import UsageSnapshot
+from illusion.config.paths import get_sessions_dir
+from illusion.engine.messages import ConversationMessage
+
+
+def get_project_session_dir(cwd: str | Path) -> Path:
+    """返回项目的会话目录。"""
+    path = Path(cwd).resolve()
+    # 使用路径的 SHA1 哈希前 12 位作为目录名的一部分
+    digest = sha1(str(path).encode("utf-8")).hexdigest()[:12]
+    session_dir = get_sessions_dir() / f"{path.name}-{digest}"
+    session_dir.mkdir(parents=True, exist_ok=True)
+    return session_dir
+
+
+def save_session_snapshot(
+    *,
+    cwd: str | Path,
+    model: str,
+    system_prompt: str,
+    messages: list[ConversationMessage],
+    usage: UsageSnapshot,
+    session_id: str | None = None,
+) -> Path:
+    """持久化会话快照。同时按 ID 保存和保存为 latest。"""
+    session_dir = get_project_session_dir(cwd)
+    sid = session_id or uuid4().hex[:12]
+    now = time.time()
+    # 从第一个用户消息提取摘要
+    summary = ""
+    for msg in messages:
+        if msg.role == "user" and msg.text.strip():
+            summary = msg.text.strip()[:80]
+            break
+
+    payload = {
+        "session_id": sid,
+        "cwd": str(Path(cwd).resolve()),
+        "model": model,
+        "system_prompt": system_prompt,
+        "messages": [message.model_dump(mode="json") for message in messages],
+        "usage": usage.model_dump(),
+        "created_at": now,
+        "summary": summary,
+        "message_count": len(messages),
+    }
+    data = json.dumps(payload, indent=2) + "\n"
+
+    # 保存为 latest
+    latest_path = session_dir / "latest.json"
+    latest_path.write_text(data, encoding="utf-8")
+
+    # 按会话 ID 保存
+    session_path = session_dir / f"session-{sid}.json"
+    session_path.write_text(data, encoding="utf-8")
+
+    return latest_path
+
+
+def load_session_snapshot(cwd: str | Path) -> dict[str, Any] | None:
+    """加载项目的最新会话快照。"""
+    path = get_project_session_dir(cwd) / "latest.json"
+    if not path.exists():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def list_session_snapshots(cwd: str | Path, limit: int = 20) -> list[dict[str, Any]]:
+    """列出项目的已保存会话，按最新优先排序。"""
+    session_dir = get_project_session_dir(cwd)
+    sessions: list[dict[str, Any]] = []
+    seen_ids: set[str] = set()
+
+    # 命名会话文件
+    for path in sorted(session_dir.glob("session-*.json"), key=lambda p: p.stat().st_mtime, reverse=True):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            sid = data.get("session_id", path.stem.replace("session-", ""))
+            seen_ids.add(sid)
+            summary = data.get("summary", "")
+            if not summary:
+                # 从消息中提取
+                for msg in data.get("messages", []):
+                    if msg.get("role") == "user":
+                        texts = [b.get("text", "") for b in msg.get("content", []) if b.get("type") == "text"]
+                        summary = " ".join(texts).strip()[:80]
+                        if summary:
+                            break
+            sessions.append({
+                "session_id": sid,
+                "summary": summary,
+                "message_count": data.get("message_count", len(data.get("messages", []))),
+                "model": data.get("model", ""),
+                "created_at": data.get("created_at", path.stat().st_mtime),
+            })
+        except (json.JSONDecodeError, OSError):
+            continue
+        if len(sessions) >= limit:
+            break
+
+    # 也包含 latest.json（如果没有对应的会话文件）
+    latest_path = session_dir / "latest.json"
+    if latest_path.exists() and len(sessions) < limit:
+        try:
+            data = json.loads(latest_path.read_text(encoding="utf-8"))
+            sid = data.get("session_id", "latest")
+            if sid not in seen_ids:
+                summary = data.get("summary", "")
+                if not summary:
+                    for msg in data.get("messages", []):
+                        if msg.get("role") == "user":
+                            texts = [b.get("text", "") for b in msg.get("content", []) if b.get("type") == "text"]
+                            summary = " ".join(texts).strip()[:80]
+                            if summary:
+                                break
+                sessions.append({
+                    "session_id": sid,
+                    "summary": summary or "(latest session)",
+                    "message_count": data.get("message_count", len(data.get("messages", []))),
+                    "model": data.get("model", ""),
+                    "created_at": data.get("created_at", latest_path.stat().st_mtime),
+                })
+        except (json.JSONDecodeError, OSError):
+            pass
+
+    # 按 created_at 降序排序
+    sessions.sort(key=lambda s: s.get("created_at", 0), reverse=True)
+    return sessions[:limit]
+
+
+def load_session_by_id(cwd: str | Path, session_id: str) -> dict[str, Any] | None:
+    """按 ID 加载特定会话。"""
+    session_dir = get_project_session_dir(cwd)
+    # 先尝试命名会话
+    path = session_dir / f"session-{session_id}.json"
+    if path.exists():
+        return json.loads(path.read_text(encoding="utf-8"))
+    # 回退到 latest.json（如果 session_id 匹配）
+    latest = session_dir / "latest.json"
+    if latest.exists():
+        data = json.loads(latest.read_text(encoding="utf-8"))
+        if data.get("session_id") == session_id or session_id == "latest":
+            return data
+    return None
+
+
+def delete_session_by_id(cwd: str | Path, session_id: str) -> bool:
+    """按 ID 删除特定会话。返回是否成功删除。"""
+    session_dir = get_project_session_dir(cwd)
+    path = session_dir / f"session-{session_id}.json"
+    if path.exists():
+        path.unlink()
+        # 如果删除的是 latest.json 对应的会话，也删除 latest.json
+        latest = session_dir / "latest.json"
+        if latest.exists():
+            try:
+                data = json.loads(latest.read_text(encoding="utf-8"))
+                if data.get("session_id") == session_id:
+                    latest.unlink()
+            except (json.JSONDecodeError, OSError):
+                pass
+        return True
+    return False
+
+
+def delete_all_sessions(cwd: str | Path) -> int:
+    """删除项目的所有会话快照。返回删除的文件数量。"""
+    session_dir = get_project_session_dir(cwd)
+    count = 0
+    for path in session_dir.glob("session-*.json"):
+        path.unlink()
+        count += 1
+    latest = session_dir / "latest.json"
+    if latest.exists():
+        latest.unlink()
+        count += 1
+    return count
+
+
+def export_session_markdown(
+    *,
+    cwd: str | Path,
+    messages: list[ConversationMessage],
+) -> Path:
+    """将会话记录导出为 Markdown。"""
+    session_dir = get_project_session_dir(cwd)
+    path = session_dir / "transcript.md"
+    parts: list[str] = ["# IllusionCode Session Transcript"]
+    for message in messages:
+        parts.append(f"\n## {message.role.capitalize()}\n")
+        text = message.text.strip()
+        if text:
+            parts.append(text)
+        for block in message.tool_uses:
+            parts.append(f"\n```tool\n{block.name} {json.dumps(block.input, ensure_ascii=True)}\n```")
+        for block in message.content:
+            if getattr(block, "type", "") == "tool_result":
+                parts.append(f"\n```tool-result\n{block.content}\n```")
+    path.write_text("\n".join(parts).strip() + "\n", encoding="utf-8")
+    return path

illusion/services/token_estimation.py

@@ -0,0 +1,72 @@
+"""
+Token 估算工具
+==============
+
+本模块提供 Token 估算功能，使用改进的启发式方法：
+- 基础估算：字符数 / 4（适用于英文为主的文本）
+- CJK 优化：中日韩文字按 2 字符/token 估算（更密集）
+- JSON 优化：JSON 内容按 2 字节/token 估算
+- 混合文本自动检测
+
+主要功能：
+    - 估算单个文本的 Token 数量
+    - 估算消息列表的总 Token 数量
+    - 检测文本是否包含 CJK 字符
+
+使用示例：
+    >>> from illusion.services.token_estimation import estimate_tokens
+    >>> tokens = estimate_tokens("Hello, world!")
+    >>> print(tokens)  # 输出约 4
+    >>> tokens = estimate_tokens("你好世界")
+    >>> print(tokens)  # 输出约 4
+"""
+
+from __future__ import annotations
+
+import re
+
+# CJK 字符范围的正则表达式（匹配中日韩统一表意文字等）
+_CJK_PATTERN = re.compile(
+    r"[\u4e00-\u9fff"  # CJK Unified Ideographs
+    r"\u3400-\u4dbf"  # CJK Unified Ideographs Extension A
+    r"\uf900-\ufaff"  # CJK Compatibility Ideographs
+    r"\u3040-\u309f"  # Hiragana
+    r"\u30a0-\u30ff"  # Katakana
+    r"\uac00-\ud7af"  # Hangul Syllables
+    r"]"
+)
+
+
+def _has_cjk(text: str) -> bool:
+    """检查文本是否包含 CJK 字符。"""
+    return bool(_CJK_PATTERN.search(text))
+
+
+def estimate_tokens(text: str) -> int:
+    """使用改进的启发式方法估算纯文本的 Token 数。
+
+    对于英文为主的文本，使用字符数 / 4 的估算。
+    对于包含 CJK 字符的文本，使用字符数 / 2 的估算（CJK 文字更密集）。
+    """
+    if not text:
+        return 0
+    if _has_cjk(text):
+        # CJK 文字：每个字符约 0.5-1 token，使用 /2 估算
+        return max(1, (len(text) + 1) // 2)
+    # 英文为主：约 4 字符/token
+    return max(1, (len(text) + 3) // 4)
+
+
+def estimate_tokens_for_json(text: str) -> int:
+    """估算 JSON 文本的 Token 数。
+
+    JSON 内容比普通文本更密集，使用 2 字节/token 估算。
+    """
+    if not text:
+        return 0
+    return max(1, len(text.encode("utf-8")) // 2)
+
+
+def estimate_message_tokens(messages: list[str]) -> int:
+    """估算消息字符串集合的 Token 总数。"""
+    return sum(estimate_tokens(message) for message in messages)

illusion/skills/__init__.py

@@ -0,0 +1,60 @@
+"""
+Skill 模块导出
+=============
+
+本模块导出 skills 子目录中的公共接口。
+
+导出内容：
+    - SkillDefinition: Skill 定义数据类
+    - SkillRegistry: Skill 注册表
+    - get_user_skills_dir: 用户 skills 目录
+    - load_skill_registry: 加载 skill 注册表
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from illusion.skills.registry import SkillRegistry
+    from illusion.skills.types import SkillDefinition
+
+__all__ = [
+    "SkillDefinition",
+    "SkillRegistry",
+    "get_project_rules_dir",
+    "get_project_skills_dir",
+    "get_user_skills_dir",
+    "load_skill_registry",
+]
+
+
+def __getattr__(name: str):
+    if name in {
+        "get_user_skills_dir",
+        "get_project_skills_dir",
+        "get_project_rules_dir",
+        "load_skill_registry",
+    }:
+        from illusion.skills.loader import (
+            get_project_rules_dir,
+            get_project_skills_dir,
+            get_user_skills_dir,
+            load_skill_registry,
+        )
+
+        return {
+            "get_user_skills_dir": get_user_skills_dir,
+            "get_project_skills_dir": get_project_skills_dir,
+            "get_project_rules_dir": get_project_rules_dir,
+            "load_skill_registry": load_skill_registry,
+        }[name]
+    if name == "SkillRegistry":
+        from illusion.skills.registry import SkillRegistry
+
+        return SkillRegistry
+    if name == "SkillDefinition":
+        from illusion.skills.types import SkillDefinition
+
+        return SkillDefinition
+    raise AttributeError(name)

illusion/skills/bundled/__init__.py

@@ -0,0 +1,110 @@
+"""
+内置 Skill 定义模块
+==================
+
+本模块从 .md 文件加载内置 skill 定义。
+
+主要功能：
+    - 从 content 目录加载所有内置 skills
+    - 解析 Markdown 文件的前 matter
+
+类说明：
+    - get_bundled_skills: 加载所有内置 skills
+
+使用示例：
+    >>> from illusion.skills.bundled import get_bundled_skills
+    >>> # 加载内置 skills
+    >>> skills = get_bundled_skills()
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from illusion.skills.types import SkillDefinition
+
+# 内置 skill 内容目录
+_CONTENT_DIR = Path(__file__).parent / "content"
+
+
+def get_bundled_skills() -> list[SkillDefinition]:
+    """从 content 目录加载所有内置 skills（支持 .md、.yaml、.yml）。"""
+    skills: list[SkillDefinition] = []
+    if not _CONTENT_DIR.exists():
+        return skills
+    from illusion.skills.loader import _load_yaml_skill
+
+    for path in sorted(_CONTENT_DIR.iterdir()):
+        if not path.is_file():
+            continue
+        if path.suffix in (".yaml", ".yml"):
+            skill = _load_yaml_skill(path, source="bundled")
+            if skill:
+                skills.append(skill)
+        elif path.suffix == ".md":
+            content = path.read_text(encoding="utf-8")
+            name, description = _parse_frontmatter(path.stem, content)
+            skills.append(
+                SkillDefinition(
+                    name=name,
+                    description=description,
+                    content=content,
+                    source="bundled",
+                    path=str(path),
+                )
+            )
+    return skills
+
+
+def _parse_frontmatter(default_name: str, content: str) -> tuple[str, str]:
+    """从 skill markdown 文件中提取名称和描述。
+
+    支持 YAML frontmatter（--- 分隔），并回退到标题/段落解析。
+    """
+    import yaml
+
+    name = default_name
+    description = ""
+    lines = content.splitlines()
+
+    # 先尝试 YAML frontmatter
+    if lines and lines[0].strip() == "---":
+        end_idx = -1
+        for i, line in enumerate(lines[1:], 1):
+            if line.strip() == "---":
+                end_idx = i
+                break
+        if end_idx > 0:
+            fm_text = "\n".join(lines[1:end_idx])
+            try:
+                data = yaml.safe_load(fm_text)
+                if isinstance(data, dict):
+                    if data.get("name"):
+                        name = str(data["name"]).strip()
+                    if data.get("description"):
+                        description = str(data["description"]).strip()
+            except Exception:
+                # YAML 解析失败，回退到手动解析
+                for fm_line in lines[1:end_idx]:
+                    fm = fm_line.strip()
+                    if fm.startswith("name:"):
+                        val = fm[5:].strip().strip("'\"")
+                        if val:
+                            name = val
+                    elif fm.startswith("description:"):
+                        val = fm[12:].strip().strip("'\"")
+                        if val:
+                            description = val
+        if description:
+            return name, description
+
+    # 回退：标题 + 第一段
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("# "):
+            name = stripped[2:].strip() or default_name
+            continue
+        if stripped and not stripped.startswith("---") and not stripped.startswith("#"):
+            description = stripped[:200]
+            break
+    return name, description or f"Bundled skill: {name}"

illusion/skills/bundled/content/batch.md

@@ -0,0 +1,86 @@
+---
+name: batch
+description: Research and plan a large-scale change, then execute it in parallel across 5-30 isolated worktree agents that each open a PR.
+argument-hint: "<instruction>"
+---
+
+# Batch: Parallel Work Orchestration
+
+You are orchestrating a large, parallelizable change across this codebase.
+
+## User Instruction
+
+The instruction will be provided as arguments.
+
+## Phase 1: Research and Plan (Plan Mode)
+
+Call the `enter_plan_mode` tool now to enter plan mode, then:
+
+1. **Understand the scope.** Launch one or more subagents (in the foreground — you need their results) to deeply research what this instruction touches. Find all the files, patterns, and call sites that need to change. Understand the existing conventions so the migration is consistent.
+
+2. **Decompose into independent units.** Break the work into 5–30 self-contained units. Each unit must:
+   - Be independently implementable in an isolated git worktree (no shared state with sibling units)
+   - Be mergeable on its own without depending on another unit's PR landing first
+   - Be roughly uniform in size (split large units, merge trivial ones)
+
+   Scale the count to the actual work: few files → closer to 5; hundreds of files → closer to 30. Prefer per-directory or per-module slicing over arbitrary file lists.
+
+3. **Determine the e2e test recipe.** Figure out how a worker can verify its change actually works end-to-end — not just that unit tests pass. Look for:
+   - A browser-automation tool (for UI changes: click through the affected flow, screenshot the result)
+   - A CLI-verifier skill (for CLI changes: launch the app interactively, exercise the changed behavior)
+   - A dev-server + curl pattern (for API changes: start the server, hit the affected endpoints)
+   - An existing e2e/integration test suite the worker can run
+
+   If you cannot find a concrete e2e path, use the `ask_user_question` tool to ask the user how to verify this change end-to-end. Offer 2–3 specific options based on what you found.
+
+   Write the recipe as a short, concrete set of steps that a worker can execute autonomously.
+
+4. **Write the plan.** In your plan file, include:
+   - A summary of what you found during research
+   - A numbered list of work units — for each: a short title, the list of files/directories it covers, and a one-line description of the change
+   - The e2e test recipe (or "skip e2e because …" if the user chose that)
+   - The exact worker instructions you will give each agent (the shared template)
+
+5. Call `exit_plan_mode` to present the plan for approval.
+
+## Phase 2: Spawn Workers (After Plan Approval)
+
+Once the plan is approved, spawn one background agent per work unit using the `agent` tool. **All agents must use `isolation: "worktree"` and `run_in_background: true`.** Launch them all in a single message block so they run in parallel.
+
+For each agent, the prompt must be fully self-contained. Include:
+- The overall goal (the user's instruction)
+- This unit's specific task (title, file list, change description — copied verbatim from your plan)
+- Any codebase conventions you discovered that the worker needs to follow
+- The e2e test recipe from your plan (or "skip e2e because …")
+- The worker instructions below, copied verbatim:
+
+```
+After you finish implementing the change:
+1. **Simplify** — Invoke the `skill` tool with `name: "simplify"` to review and clean up your changes.
+2. **Run unit tests** — Run the project's test suite (check for package.json scripts, Makefile targets, or common commands like `npm test`, `bun test`, `pytest`, `go test`). If tests fail, fix them.
+3. **Test end-to-end** — Follow the e2e test recipe from the coordinator's prompt. If the recipe says to skip e2e for this unit, skip it.
+4. **Commit and push** — Commit all changes with a clear message, push the branch, and create a PR with `gh pr create`. Use a descriptive title. If `gh` is not available or the push fails, note it in your final message.
+5. **Report** — End with a single line: `PR: <url>` so the coordinator can track it. If no PR was created, end with `PR: none — <reason>`.
+```
+
+Use `subagent_type: "general-purpose"` unless a more specific agent type fits.
+
+## Phase 3: Track Progress
+
+After launching all workers, render an initial status table:
+
+| # | Unit | Status | PR |
+|---|------|--------|----|
+| 1 | <title> | running | — |
+| 2 | <title> | running | — |
+
+As background-agent completion notifications arrive, parse the `PR: <url>` line from each agent's result and re-render the table with updated status (`done` / `failed`) and PR links. Keep a brief failure note for any agent that did not produce a PR.
+
+When all agents have reported, render the final table and a one-line summary (e.g., "22/24 units landed as PRs").
+
+## Rules
+
+- This command requires a git repo because it spawns agents in isolated git worktrees and creates PRs from each. Initialize a repo first if needed.
+- Each agent must be fully self-contained — no shared state between agents
+- All agents must use worktree isolation
+- Track progress and report results clearly

illusion/skills/bundled/content/coding-guidelines.md

@@ -0,0 +1,70 @@
+---
+name: coding-guidelines
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+---
+
+# Coding Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

illusion/skills/bundled/content/debug.md

@@ -0,0 +1,38 @@
+---
+name: debug
+description: Enable debug logging for this session and help diagnose issues
+---
+
+# Debug Skill
+
+Help the user debug an issue they're encountering in this current Illusion Code session.
+
+## Session Debug Log
+
+The debug log for the current session is located at the path shown in the session startup output.
+
+## Issue Description
+
+The user's issue description will be provided as arguments. If no description is given, read the debug log and summarize any errors, warnings, or notable issues.
+
+## Settings
+
+Remember that settings are in:
+* user - ~/.illusion/settings.json
+* project - .illusion/settings.json
+
+## Instructions
+
+1. Review the user's issue description
+2. Look for [ERROR] and [WARN] entries, stack traces, and failure patterns in the debug log
+3. Consider launching a subagent to understand the relevant Illusion Code features
+4. Explain what you found in plain language
+5. Suggest concrete fixes or next steps
+
+## Rules
+
+- Read the error message carefully before searching code
+- Don't guess — verify your hypothesis before changing code
+- Fix the root cause, not the symptom
+- Don't retry the same approach if it failed — investigate why
+- If stuck after 3 attempts, explain what you've tried and ask for help