illusion-code 0.1.0__py3-none-any.whl

illusion/skills/bundled/content/update-config.md

@@ -0,0 +1,329 @@
+---
+name: update-config
+description: Configure Illusion Code via settings.json. Use for permissions, hooks, env vars, MCP servers, and other settings. Examples: "allow npm commands", "set DEBUG=true", "add a hook to format code after writes".
+---
+
+# Update Config Skill
+
+Modify Illusion Code configuration by updating settings.json files.
+
+## When Hooks Are Required
+
+If the user wants something to happen automatically in response to an EVENT, they need a **hook** configured in settings.json.
+
+**These require hooks:**
+- "After writing files, run prettier" → `post_tool_use` hook with matcher `Write|Edit`
+- "Before running bash commands, validate them" → `pre_tool_use` hook with matcher `Bash`
+- "When session starts, show a greeting" → `session_start` hook
+
+**Hook events (only 4):**
+- `session_start` — When session starts
+- `session_end` — When session ends
+- `pre_tool_use` — Before tool execution (can block)
+- `post_tool_use` — After tool execution
+
+## CRITICAL: Read Before Write
+
+**Always read the existing settings file before making changes.** Merge new settings with existing ones - never replace the entire file.
+
+## CRITICAL: Use `ask_user_question` for Ambiguity
+
+When the user's request is ambiguous, use `ask_user_question` to clarify:
+- Which settings file to modify (user/project)
+- Whether to add to existing arrays or replace them
+- Specific values when multiple options exist
+
+## Settings File Locations
+
+| File | Scope | Use For |
+|------|-------|---------|
+| `~/.illusion/settings.json` | Global | Personal preferences for all projects |
+| `.illusion/settings.json` | Project | Team-wide hooks, permissions, plugins |
+
+Settings load in order: user → project (later overrides earlier).
+
+## Settings Schema Reference
+
+### Model Configuration
+```json
+{
+  "model": "env_1.model_1",
+  "max_tokens": 16384,
+  "max_turns": 200,
+  "context_window": 200000,
+  "effort": "medium"
+}
+```
+
+The `model` field format is `env_N.model_N` referencing an environment configuration.
+
+### Environment Configuration (env_N)
+```json
+{
+  "env_1": {
+    "api_format": "anthropic",
+    "base_url": null,
+    "api_key": "",
+    "model_1": "claude-sonnet-4-6",
+    "model_2": "claude-opus-4-6"
+  }
+}
+```
+
+### Permissions
+```json
+{
+  "permission": {
+    "mode": "default",
+    "allowed_tools": ["Bash(npm:*)", "Edit", "Read"],
+    "denied_tools": ["Bash(rm -rf:*)"],
+    "denied_commands": ["git push --force"],
+    "path_rules": [
+      {"pattern": ".env*", "allow": false},
+      {"pattern": "*.md", "allow": true}
+    ]
+  }
+}
+```
+
+**Permission modes:** `default`, `plan`, `accept_edits`, `dont_ask`
+
+**Permission Rule Syntax:**
+- Exact match: `"Bash(npm run test)"`
+- Prefix wildcard: `"Bash(git:*)"` - matches `git status`, `git commit`, etc.
+- Tool only: `"Read"` - allows all Read operations
+
+### Hooks
+```json
+{
+  "hooks": {
+    "pre_tool_use": [
+      {
+        "type": "command",
+        "command": "echo 'Tool called'",
+        "timeout_seconds": 30,
+        "matcher": "Bash",
+        "block_on_failure": false
+      }
+    ],
+    "post_tool_use": [
+      {
+        "type": "command",
+        "command": "prettier --write $FILE",
+        "timeout_seconds": 30,
+        "matcher": "Write|Edit"
+      }
+    ]
+  }
+}
+```
+
+### Memory
+```json
+{
+  "memory": {
+    "enabled": true,
+    "max_files": 5,
+    "max_entrypoint_lines": 200
+  }
+}
+```
+
+### MCP Servers
+```json
+{
+  "mcp_servers": {
+    "server-name": {
+      "command": "node",
+      "args": ["server.js"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Other Settings
+- `ui_language`: Interface language (e.g., "zh-CN", "en-US")
+- `output_style`: Output style name
+- `show_thinking`: Show thinking process (boolean)
+- `fast_mode`: Enable fast mode (boolean)
+- `verbose`: Verbose output (boolean)
+- `passes`: Number of passes (integer)
+- `enabled_plugins`: Plugin enable/disable map
+
+## Hook Types
+
+### 1. Command Hook
+Runs a shell command:
+```json
+{
+  "type": "command",
+  "command": "prettier --write $FILE",
+  "timeout_seconds": 30,
+  "matcher": "Write|Edit",
+  "block_on_failure": false
+}
+```
+
+### 2. Prompt Hook
+Uses LLM to evaluate a condition:
+```json
+{
+  "type": "prompt",
+  "prompt": "Is this command safe? $ARGUMENTS",
+  "model": "claude-sonnet-4-6",
+  "timeout_seconds": 30,
+  "matcher": "Bash",
+  "block_on_failure": true
+}
+```
+
+### 3. HTTP Hook
+Sends event payload to an HTTP endpoint:
+```json
+{
+  "type": "http",
+  "url": "https://example.com/webhook",
+  "headers": {"Authorization": "Bearer token"},
+  "timeout_seconds": 30,
+  "matcher": "Write|Edit",
+  "block_on_failure": false
+}
+```
+
+### 4. Agent Hook
+Uses an agent for deep validation:
+```json
+{
+  "type": "agent",
+  "prompt": "Verify this change is safe: $ARGUMENTS",
+  "model": "claude-sonnet-4-6",
+  "timeout_seconds": 60,
+  "matcher": "Write|Edit",
+  "block_on_failure": true
+}
+```
+
+### Hook Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `type` | string | required | Hook type: `command`, `prompt`, `http`, `agent` |
+| `command` | string | (command) | Shell command to execute |
+| `prompt` | string | (prompt/agent) | Prompt for LLM evaluation |
+| `url` | string | (http) | HTTP endpoint URL |
+| `headers` | object | `{}` | HTTP headers |
+| `model` | string | null | Model override (prompt/agent) |
+| `timeout_seconds` | int | 30/60 | Timeout in seconds |
+| `matcher` | string | null | Tool name pattern to match |
+| `block_on_failure` | bool | varies | Block execution on failure |
+
+### Hook Input (stdin JSON)
+Hooks receive JSON on stdin:
+```json
+{
+  "session_id": "abc123",
+  "tool_name": "Write",
+  "tool_input": { "file_path": "/path/to/file.txt", "content": "..." },
+  "tool_response": { "success": true }
+}
+```
+
+### Hook Output
+
+Command hooks can output JSON to control behavior:
+```json
+{
+  "blocked": true,
+  "reason": "Command not allowed",
+  "output": "Detailed explanation"
+}
+```
+
+- `blocked` — Set to `true` to block the tool execution
+- `reason` — Message shown when blocking
+- `output` — Output text (displayed to user or injected as context)
+
+## Common Patterns
+
+### Auto-format after writes
+```json
+{
+  "hooks": {
+    "post_tool_use": [{
+      "type": "command",
+      "command": "jq -r '.tool_input.file_path // .tool_response.filePath' | { read -r f; prettier --write \"$f\"; } 2>/dev/null || true",
+      "matcher": "Write|Edit",
+      "timeout_seconds": 30
+    }]
+  }
+}
+```
+
+### Log all bash commands
+```json
+{
+  "hooks": {
+    "pre_tool_use": [{
+      "type": "command",
+      "command": "jq -r '.tool_input.command' >> ~/.illusion/bash-log.txt",
+      "matcher": "Bash"
+    }]
+  }
+}
+```
+
+### Block dangerous commands
+```json
+{
+  "hooks": {
+    "pre_tool_use": [{
+      "type": "command",
+      "command": "jq -r '.tool_input.command' | grep -qE 'rm -rf|drop table' && echo '{\"blocked\": true, \"reason\": \"Dangerous command blocked\"}' || true",
+      "matcher": "Bash",
+      "block_on_failure": false
+    }]
+  }
+}
+```
+
+## Workflow
+
+1. **Clarify intent** — Ask if the request is ambiguous
+2. **Read existing file** — Use Read tool on the target settings file
+3. **Merge carefully** — Preserve existing settings, especially arrays
+4. **Edit file** — Use Edit tool (if file doesn't exist, create it first)
+5. **Validate** — Check JSON syntax
+6. **Confirm** — Tell user what was changed
+
+## Merging Arrays (Important!)
+
+When adding to permission arrays or hook arrays, **merge with existing**, don't replace:
+
+**WRONG** (replaces existing):
+```json
+{ "permission": { "allowed_tools": ["Bash(npm:*)"] } }
+```
+
+**RIGHT** (preserves existing + adds new):
+```json
+{
+  "permission": {
+    "allowed_tools": [
+      "Bash(git:*)",
+      "Edit",
+      "Bash(npm:*)"
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+If a hook isn't running:
+1. Check the settings file exists and has valid JSON
+2. Verify the event name is correct (lowercase with underscores)
+3. Check the matcher matches the tool name
+4. Check hook type is one of: `command`, `prompt`, `http`, `agent`
+5. Test the command manually
+6. Check `timeout_seconds` isn't too low

illusion/skills/bundled/content/verify.md

@@ -0,0 +1,74 @@
+---
+name: verify
+description: Verify that a code change actually does what it's supposed to by running the app and observing behavior. Use when asked to verify a PR, confirm a fix works, test a change manually, check that a feature works, or validate local changes before pushing.
+---
+
+# Verify: Manual Feature Verification
+
+Verify that a code change actually does what it's supposed to by running the app and observing behavior.
+
+## When to use
+
+Use this skill when:
+- Asked to verify a PR or confirm a fix works
+- Testing a change manually before pushing
+- Checking that a feature works as expected
+- Validating local changes
+
+## Workflow
+
+### 1. Understand the Change
+
+Run `git diff` (or `git diff HEAD` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files.
+
+Identify:
+- What feature/fix was implemented
+- What the expected behavior should be
+- How to trigger/test the behavior
+
+### 2. Determine Verification Method
+
+Based on the change type, choose the appropriate verification:
+
+**UI Changes:**
+- Start the dev server
+- Navigate to the affected page/component
+- Interact with the changed elements
+- Screenshot the result
+
+**API Changes:**
+- Start the server
+- Use curl or similar to hit the affected endpoints
+- Verify response codes and data
+
+**CLI Changes:**
+- Run the CLI with relevant flags/arguments
+- Check output matches expectations
+
+**Logic Changes:**
+- Write a simple test script if needed
+- Run with specific inputs
+- Verify outputs
+
+### 3. Execute Verification
+
+1. **Setup**: Start any required services (dev server, database, etc.)
+2. **Test the happy path**: The primary use case should work
+3. **Test edge cases**: Boundary conditions, error cases
+4. **Check for regressions**: Existing features still work
+
+### 4. Report Results
+
+Provide a clear report:
+- What was tested
+- What passed
+- What failed (if anything)
+- Screenshots/logs if relevant
+
+## Rules
+
+- Actually run the code, don't just read it
+- Test the specific change, not the entire application
+- Report honestly — if something doesn't work, say so
+- Include reproduction steps for any failures
+- If verification requires setup the user hasn't done, ask first

illusion/skills/loader.py

@@ -0,0 +1,219 @@
+"""
+Skill 加载模块 — 从内置和用户目录加载 Skills
+=========================================
+
+本模块提供从内置目录和用户配置目录加载 Skills 的功能。
+
+主要功能：
+    - 获取用户 skills 目录
+    - 加载 skill 注册表
+    - 加载用户 skills
+    - 解析 skill markdown 文件
+
+类说明：
+    - get_user_skills_dir: 获取用户 skills 目录
+    - load_skill_registry: 加载内置和用户定义的 skills
+    - load_user_skills: 从用户配置目录加载 markdown skills
+
+使用示例：
+    >>> from illusion.skills.loader import get_user_skills_dir, load_skill_registry
+    >>> # 获取用户 skills 目录
+    >>> skills_dir = get_user_skills_dir()
+    >>> # 加载 skill 注册表
+    >>> registry = load_skill_registry(cwd="/path/to/project")
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from illusion.config.paths import get_config_dir, get_project_config_dir
+from illusion.config.settings import load_settings
+from illusion.skills.bundled import get_bundled_skills
+from illusion.skills.registry import SkillRegistry
+from illusion.skills.types import SkillDefinition
+
+
+def get_user_skills_dir() -> Path:
+    """返回用户 skills 目录。"""
+    path = get_config_dir() / "skills"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_project_skills_dir(cwd: str | Path) -> Path:
+    """返回项目级 skills 目录（.illusion/skills/）。"""
+    path = get_project_config_dir(cwd) / "skills"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def get_project_rules_dir(cwd: str | Path) -> Path:
+    """返回项目级 rules 目录（.illusion/rules/）。"""
+    path = get_project_config_dir(cwd) / "rules"
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def load_skill_registry(cwd: str | Path | None = None) -> SkillRegistry:
+    """加载内置和用户定义的 skills。"""
+    registry = SkillRegistry()
+    # 注册内置 skills
+    for skill in get_bundled_skills():
+        registry.register(skill)
+    # 注册用户 skills
+    for skill in load_user_skills():
+        registry.register(skill)
+    # 如果提供了工作目录，加载项目级 skills 和插件 skills
+    if cwd is not None:
+        # 项目级 skills（同名时覆盖全局）
+        for skill in load_project_skills(cwd):
+            registry.register(skill)
+        from illusion.plugins.loader import load_plugins
+
+        settings = load_settings()
+        for plugin in load_plugins(settings, cwd):
+            if not plugin.enabled:
+                continue
+            for skill in plugin.skills:
+                registry.register(skill)
+    return registry
+
+
+def load_user_skills() -> list[SkillDefinition]:
+    """从用户配置目录加载 skills（支持 .md、.yaml、.yml）。"""
+    skills: list[SkillDefinition] = []
+    for path in sorted(get_user_skills_dir().iterdir()):
+        if path.suffix in (".yaml", ".yml"):
+            skill = _load_yaml_skill(path, source="user")
+            if skill:
+                skills.append(skill)
+        elif path.suffix == ".md":
+            content = path.read_text(encoding="utf-8")
+            name, description = _parse_skill_markdown(path.stem, content)
+            skills.append(
+                SkillDefinition(
+                    name=name,
+                    description=description,
+                    content=content,
+                    source="user",
+                    path=str(path),
+                )
+            )
+    return skills
+
+
+def load_project_skills(cwd: str | Path) -> list[SkillDefinition]:
+    """从项目目录加载 skills（支持 .md、.yaml、.yml）。
+
+    目录结构: <project>/.illusion/skills/<skill_name>/<skill_name>.md 或 .yaml/.yml
+    """
+    skills: list[SkillDefinition] = []
+    skills_dir = get_project_skills_dir(cwd)
+    for sub in sorted(skills_dir.iterdir()):
+        if not sub.is_dir():
+            continue
+        for path in sorted(sub.iterdir()):
+            if path.suffix in (".yaml", ".yml"):
+                skill = _load_yaml_skill(path, source="project")
+                if skill:
+                    skills.append(skill)
+            elif path.suffix == ".md":
+                content = path.read_text(encoding="utf-8")
+                name, description = _parse_skill_markdown(path.stem, content)
+                skills.append(
+                    SkillDefinition(
+                        name=name,
+                        description=description,
+                        content=content,
+                        source="project",
+                        path=str(path),
+                    )
+                )
+    return skills
+
+
+def _parse_skill_markdown(default_name: str, content: str) -> tuple[str, str]:
+    """解析 skill markdown 文件的名称和描述，支持 YAML frontmatter。"""
+    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_stripped = fm_line.strip()
+                    if fm_stripped.startswith("name:"):
+                        val = fm_stripped[5:].strip().strip("'\"")
+                        if val:
+                            name = val
+                    elif fm_stripped.startswith("description:"):
+                        val = fm_stripped[12:].strip().strip("'\"")
+                        if val:
+                            description = val
+
+    # 回退：从标题和第一段提取
+    if not description:
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("# "):
+                if not name or name == default_name:
+                    name = stripped[2:].strip() or default_name
+                continue
+            if stripped and not stripped.startswith("---") and not stripped.startswith("#"):
+                description = stripped[:200]
+                break
+
+    if not description:
+        description = f"Skill: {name}"
+    return name, description
+
+
+def _load_yaml_skill(path: Path, source: str) -> SkillDefinition | None:
+    """从 YAML 文件加载 skill 定义。
+
+    YAML skill 文件格式:
+        name: my-skill
+        description: "A skill defined in YAML"
+        content: |
+          # Instructions here
+          ...
+    """
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+    name = data.get("name", path.stem)
+    description = data.get("description", "")
+    content = data.get("content", "")
+    if not content:
+        # 如果没有 content 字段，将整个 yaml 序列化作为 content
+        content = yaml.dump(data, allow_unicode=True, default_flow_style=False)
+    return SkillDefinition(
+        name=name,
+        description=description or f"Skill: {name}",
+        content=content,
+        source=source,
+        path=str(path),
+    )

illusion/skills/registry.py

@@ -0,0 +1,40 @@
+"""
+Skill 注册表模块
+================
+
+本模块提供 Skill 注册表功能，按名称存储已加载的 skills。
+
+类说明：
+    - SkillRegistry: 按名称存储已加载的 skills
+
+使用示例：
+    >>> from illusion.skills import SkillRegistry
+    >>> registry = SkillRegistry()
+    >>> # 注册 skill
+    >>> registry.register(skill_definition)
+    >>> # 获取 skill
+    >>> skill = registry.get("my_skill")
+"""
+
+from __future__ import annotations
+
+from illusion.skills.types import SkillDefinition
+
+
+class SkillRegistry:
+    """按名称存储已加载的 skills。"""
+
+    def __init__(self) -> None:
+        self._skills: dict[str, SkillDefinition] = {}
+
+    def register(self, skill: SkillDefinition) -> None:
+        """注册一个 skill。"""
+        self._skills[skill.name] = skill
+
+    def get(self, name: str) -> SkillDefinition | None:
+        """按名称返回 skill。"""
+        return self._skills.get(name)
+
+    def list_skills(self) -> list[SkillDefinition]:
+        """返回所有 skills，按名称排序。"""
+        return sorted(self._skills.values(), key=lambda skill: skill.name)

illusion/skills/types.py

@@ -0,0 +1,24 @@
+"""
+Skill 数据模型模块
+================
+
+本模块定义 Skill 相关的数据模型。
+
+类说明：
+    - SkillDefinition: 已加载的 Skill 数据类
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SkillDefinition:
+    """已加载的 Skill。"""
+
+    name: str
+    description: str
+    content: str
+    source: str
+    path: str | None = None

illusion/state/__init__.py

@@ -0,0 +1,18 @@
+"""
+状态管理模块
+============
+
+本模块提供 IllusionCode 应用状态管理功能。
+
+主要组件：
+    - AppState: 应用状态
+    - AppStateStore: 应用状态存储
+
+使用示例：
+    >>> from illusion.state import AppState, AppStateStore
+"""
+
+from illusion.state.app_state import AppState
+from illusion.state.store import AppStateStore
+
+__all__ = ["AppState", "AppStateStore"]