vox-code 2.0.0__py3-none-any.whl

voxcli/plan/planner.py

@@ -0,0 +1,198 @@
+"""规划器 - 使用LLM将复杂任务分解为执行计划"""
+
+import json
+import re
+import time
+import logging
+from typing import List, Optional
+
+from ..llm.base import LlmClient, Message
+from .task import Task, TaskType
+from .execution_plan import ExecutionPlan
+
+logger = logging.getLogger(__name__)
+
+_PLANNING_PROMPT = """你是一个任务规划专家。请将用户的复杂任务分解为一系列可执行的子任务。
+
+可用任务类型：
+- FILE_READ: 读取文件内容
+- FILE_WRITE: 写入文件内容
+- COMMAND: 执行Shell命令
+- ANALYSIS: 分析结果并做出决策
+- VERIFICATION: 验证结果是否正确
+
+请按以下JSON格式输出执行计划：
+{
+    "summary": "任务摘要",
+    "tasks": [
+        {
+            "id": "task_1",
+            "description": "任务描述",
+            "type": "FILE_READ",
+            "dependencies": []
+        },
+        {
+            "id": "task_2",
+            "description": "任务描述",
+            "type": "FILE_WRITE",
+            "dependencies": ["task_1"]
+        }
+    ]
+}
+
+规则：
+1. 每个任务必须有唯一的id（如 task_1, task_2）
+2. dependencies列出依赖的任务id
+3. 任务应该按执行顺序排列
+4. 任务描述要具体明确
+5. 简单任务（如列目录、读取单个文件、执行单条命令）允许只生成1-3个任务；不要为了凑步数引入无关步骤
+6. 复杂任务再拆分为5-10个子任务
+7. 不要为了"保存中间结果"而额外创建 FILE_WRITE / FILE_READ，除非用户明确要求落盘
+8. 如果一个任务一步就能完成，就保持最短计划
+
+只输出JSON，不要有其他内容。"""
+
+_SIMPLE_GOAL_CUES = ["列出", "查看", "读取", "显示", "执行", "运行", "搜索", "当前目录", "文件"]
+_MULTI_STEP_CUES = ["然后", "并且", "并", "再", "最后", "同时", "先", "之后", "接着", "以及"]
+
+
+class Planner:
+    def __init__(self, llm_client: LlmClient):
+        self._llm = llm_client
+        self._plan_id_counter = 0
+
+    def create_plan(self, goal: str) -> ExecutionPlan:
+        logger.info("Planning for goal: %s", goal)
+        print(f"📋 正在规划任务: {goal}\n")
+
+        if self._is_simple_goal(goal):
+            return self._create_minimal_plan(goal)
+
+        messages = [
+            Message.system(_PLANNING_PROMPT),
+            Message.user(f"请为以下任务制定执行计划：\n{goal}"),
+        ]
+
+        renderer = PlanningStreamRenderer()
+        response = self._llm.chat(messages, listener=renderer)
+        renderer.finish()
+        plan_json = response.content or ""
+
+        return self._parse_plan(goal, plan_json)
+
+    def _parse_plan(self, goal: str, plan_json: str) -> ExecutionPlan:
+        cleaned = re.sub(r"```(?:json)?\s*", "", plan_json).strip()
+        root = json.loads(cleaned)
+
+        summary = root.get("summary", "")
+        tasks_node = root.get("tasks", [])
+
+        plan = ExecutionPlan(self._generate_plan_id(), goal)
+        plan.summary = summary
+
+        id_mapping = {}
+        for i, task_node in enumerate(tasks_node, 1):
+            original_id = task_node.get("id", f"task_{i}")
+            new_id = f"task_{i}"
+            id_mapping[original_id] = new_id
+            desc = task_node.get("description", "")
+            task_type = self._parse_task_type(task_node.get("type", "ANALYSIS"))
+            plan.add_task(Task(new_id, desc, task_type))
+
+        for i, task_node in enumerate(tasks_node, 1):
+            new_id = f"task_{i}"
+            task = plan.get_task(new_id)
+            if task is None:
+                continue
+            for dep in task_node.get("dependencies", []):
+                mapped = id_mapping.get(dep, dep)
+                dep_task = plan.get_task(mapped)
+                if dep_task is not None:
+                    task.add_dependency(mapped)
+                    dep_task.add_dependent(task.id)
+
+        if not plan.compute_execution_order():
+            raise ValueError("计划中存在循环依赖")
+
+        return plan
+
+    @staticmethod
+    def _parse_task_type(type_str: str) -> TaskType:
+        mapping = {
+            "FILE_READ": TaskType.FILE_READ,
+            "FILE_WRITE": TaskType.FILE_WRITE,
+            "COMMAND": TaskType.COMMAND,
+            "ANALYSIS": TaskType.ANALYSIS,
+            "VERIFICATION": TaskType.VERIFICATION,
+        }
+        return mapping.get(type_str.upper(), TaskType.ANALYSIS)
+
+    def _generate_plan_id(self) -> str:
+        self._plan_id_counter += 1
+        return f"plan_{int(time.time())}_{self._plan_id_counter}"
+
+    def replan(self, failed_plan: ExecutionPlan, failure_reason: str) -> ExecutionPlan:
+        print(f"🔄 重新规划，原因: {failure_reason}\n")
+        context_parts = [f"原任务: {failed_plan.goal}", f"失败原因: {failure_reason}",
+                         "已完成的任务:"]
+        for task in failed_plan.get_all_tasks():
+            if task.status.value == "COMPLETED":
+                context_parts.append(f"- {task.id}: {task.description}")
+        context_parts.append("\n请制定新的执行计划，避开之前的问题。")
+        return self.create_plan("\n".join(context_parts))
+
+    @staticmethod
+    def _is_simple_goal(goal: str) -> bool:
+        if not goal or not goal.strip():
+            return False
+        normalized = goal.strip()
+        if any(cue in normalized for cue in _MULTI_STEP_CUES):
+            return False
+        if len(normalized) > 30:
+            return False
+        return any(cue in normalized for cue in _SIMPLE_GOAL_CUES)
+
+    def _create_minimal_plan(self, goal: str) -> ExecutionPlan:
+        plan = ExecutionPlan(self._generate_plan_id(), goal)
+        plan.summary = f"直接执行简单任务：{goal.strip()}"
+        plan.add_task(Task("task_1", goal.strip(), self._infer_simple_task_type(goal)))
+        if not plan.compute_execution_order():
+            raise ValueError("简单计划不应出现循环依赖")
+        return plan
+
+    @staticmethod
+    def _infer_simple_task_type(goal: str) -> TaskType:
+        normalized = goal.strip()
+        if "读取" in normalized or "打开" in normalized or ("查看" in normalized and "文件" in normalized):
+            return TaskType.FILE_READ
+        if "写入" in normalized or "修改" in normalized or "创建文件" in normalized:
+            return TaskType.FILE_WRITE
+        if "分析" in normalized or "总结" in normalized or "解释" in normalized:
+            return TaskType.ANALYSIS
+        if "验证" in normalized or "检查" in normalized:
+            return TaskType.VERIFICATION
+        return TaskType.COMMAND
+
+
+class PlanningStreamRenderer:
+    """规划流式渲染器 - 实现 StreamListener 协议"""
+    def __init__(self):
+        self._buffer = ""
+        self._started = False
+
+    def on_reasoning_delta(self, delta: str):
+        if delta:
+            if not self._started:
+                print("🧠 规划思考")
+                self._started = True
+            print(delta, end="", flush=True)
+            self._buffer += delta
+
+    def on_content_delta(self, delta: str):
+        if delta:
+            print(delta, end="", flush=True)
+            self._buffer += delta
+
+    def finish(self):
+        if self._started:
+            print("\n")

voxcli/plan/task.py

@@ -0,0 +1,123 @@
+"""任务节点 - 表示一个可执行的任务单元"""
+
+import time
+from enum import Enum
+from typing import List, Optional, Dict
+
+
+class TaskType(Enum):
+    PLANNING = "PLANNING"
+    FILE_READ = "FILE_READ"
+    FILE_WRITE = "FILE_WRITE"
+    COMMAND = "COMMAND"
+    ANALYSIS = "ANALYSIS"
+    VERIFICATION = "VERIFICATION"
+
+
+class TaskStatus(Enum):
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    SKIPPED = "SKIPPED"
+
+
+class Task:
+    def __init__(self, id: str, description: str, type: TaskType,
+                 dependencies: Optional[List[str]] = None):
+        self._id = id
+        self._description = description
+        self._type = type
+        self._status = TaskStatus.PENDING
+        self._result: Optional[str] = None
+        self._error: Optional[str] = None
+        self._dependencies: List[str] = dependencies or []
+        self._dependents: List[str] = []
+        self._start_time: float = 0.0
+        self._end_time: float = 0.0
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def description(self) -> str:
+        return self._description
+
+    @property
+    def type(self) -> TaskType:
+        return self._type
+
+    @property
+    def status(self) -> TaskStatus:
+        return self._status
+
+    @property
+    def result(self) -> Optional[str]:
+        return self._result
+
+    @property
+    def error(self) -> Optional[str]:
+        return self._error
+
+    @property
+    def dependencies(self) -> List[str]:
+        return list(self._dependencies)
+
+    @property
+    def dependents(self) -> List[str]:
+        return list(self._dependents)
+
+    @property
+    def start_time(self) -> float:
+        return self._start_time
+
+    @property
+    def end_time(self) -> float:
+        return self._end_time
+
+    def add_dependent(self, task_id: str):
+        if task_id not in self._dependents:
+            self._dependents.append(task_id)
+
+    def add_dependency(self, task_id: str):
+        if task_id not in self._dependencies:
+            self._dependencies.append(task_id)
+
+    def mark_started(self):
+        self._status = TaskStatus.RUNNING
+        self._start_time = time.time()
+
+    def mark_completed(self, result: str):
+        self._status = TaskStatus.COMPLETED
+        self._result = result
+        self._end_time = time.time()
+
+    def mark_failed(self, error: str):
+        self._status = TaskStatus.FAILED
+        self._error = error
+        self._end_time = time.time()
+
+    def mark_skipped(self):
+        self._status = TaskStatus.SKIPPED
+        self._end_time = time.time()
+
+    @property
+    def duration(self) -> float:
+        if self._start_time == 0:
+            return 0.0
+        if self._end_time == 0:
+            return time.time() - self._start_time
+        return self._end_time - self._start_time
+
+    def is_executable(self, all_tasks: Dict[str, "Task"]) -> bool:
+        if self._status != TaskStatus.PENDING:
+            return False
+        for dep_id in self._dependencies:
+            dep = all_tasks.get(dep_id)
+            if dep is None or dep.status != TaskStatus.COMPLETED:
+                return False
+        return True
+
+    def __repr__(self) -> str:
+        return f"Task[{self._id}: {self._description}] ({self._status.value})"

voxcli/policy/audit_log.py

@@ -0,0 +1,111 @@
+"""危险工具调用的结构化审计日志（JSONL 格式）"""
+
+import json
+import os
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+
+_AUDIT_DIR: Optional[Path] = None
+
+
+def _audit_dir() -> Path:
+    global _AUDIT_DIR
+    if _AUDIT_DIR is not None:
+        return _AUDIT_DIR
+    env_dir = os.environ.get("VOX_CODE_AUDIT_DIR", "")
+    if env_dir.strip():
+        _AUDIT_DIR = Path(env_dir.strip())
+    else:
+        _AUDIT_DIR = Path.home() / ".vox-code" / "audit"
+    return _AUDIT_DIR
+
+
+def _today_file() -> Path:
+    d = date.today().isoformat()
+    return _audit_dir() / f"audit-{d}.jsonl"
+
+
+_MAX_FIELD_CHARS = 1000
+
+
+def _truncate(s: Optional[str]) -> Optional[str]:
+    if s is None:
+        return None
+    return s if len(s) <= _MAX_FIELD_CHARS else s[:_MAX_FIELD_CHARS] + "...(truncated)"
+
+
+class AuditEntry:
+    def __init__(self, tool: str, args: str, outcome: str,
+                 reason: Optional[str] = None, duration_ms: float = 0):
+        self.tool = tool
+        self.args = args
+        self.outcome = outcome
+        self.reason = reason
+        self.duration_ms = duration_ms
+
+
+class AuditLog:
+    @staticmethod
+    def allow(tool: str, args: str, duration_ms: float) -> AuditEntry:
+        return AuditEntry(tool, args, "allow", duration_ms=duration_ms)
+
+    @staticmethod
+    def deny_by_policy(tool: str, args: str, reason: str, duration_ms: float) -> AuditEntry:
+        return AuditEntry(tool, args, "deny", reason=reason, duration_ms=duration_ms)
+
+    @staticmethod
+    def error(tool: str, args: str, message: str, duration_ms: float) -> AuditEntry:
+        return AuditEntry(tool, args, "error", reason=message, duration_ms=duration_ms)
+
+    def record(self, entry: AuditEntry):
+        _write_entry({
+            "timestamp": datetime.utcnow().isoformat() + "Z",
+            "tool": entry.tool,
+            "args": _truncate(entry.args),
+            "outcome": entry.outcome,
+            "reason": entry.reason,
+            "approver": "none",
+            "durationMs": int(entry.duration_ms),
+        })
+
+    @staticmethod
+    def recent(n: int = 10) -> list:
+        if n <= 0:
+            return []
+        file_path = _today_file()
+        if not file_path.exists():
+            return []
+        try:
+            lines = file_path.read_text(encoding="utf-8").strip().split("\n")
+            entries = []
+            for raw in lines[-n:]:
+                raw = raw.strip()
+                if not raw:
+                    continue
+                try:
+                    data = json.loads(raw)
+                    entries.append(AuditEntry(
+                        tool=data.get("tool", ""),
+                        args=data.get("args", ""),
+                        outcome=data.get("outcome", ""),
+                        reason=data.get("reason"),
+                        duration_ms=data.get("durationMs", 0),
+                    ))
+                except json.JSONDecodeError:
+                    pass
+            return entries
+        except OSError:
+            return []
+
+
+def _write_entry(entry: dict):
+    try:
+        log_dir = _audit_dir()
+        log_dir.mkdir(parents=True, exist_ok=True)
+        file_path = _today_file()
+        with open(file_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+    except OSError as e:
+        print(f"⚠️ 审计日志写入失败: {e}")

voxcli/policy/command_guard.py

@@ -0,0 +1,34 @@
+"""命令快速拒绝：在命令执行前的黑名单 fast-fail"""
+
+import re
+from typing import Optional
+
+_RULES: list[tuple[str, re.Pattern]] = [
+    ("禁止 sudo 提权", re.compile(r"(?i)\bsudo\b")),
+    (
+        "禁止 rm -rf 删除全盘或用户目录",
+        re.compile(
+            r"(?i)\brm\s+-[a-z]*r[a-z]*f[a-z]*\s+(/|~|\$home)|"
+            r"\brm\s+-[a-z]*f[a-z]*r[a-z]*\s+(/|~|\$home)"
+        ),
+    ),
+    ("禁止 mkfs 格式化磁盘", re.compile(r"(?i)\bmkfs(\.|\b)")),
+    ("禁止 dd 写入裸设备", re.compile(r"(?i)\bdd\b[^\n]*\bof=/dev/")),
+    ("识别为 fork bomb", re.compile(r":\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:")),
+    ("禁止 curl / wget 管道直接执行远端脚本", re.compile(r"(?i)\b(curl|wget)\b[^|\n]*\|\s*(sh|bash|zsh|fish|ksh)\b")),
+    ("不允许扫描 /、~ 或整个文件系统", re.compile(r"(?i)\bfind\s+(/|~|\$home)")),
+    ("禁止 chmod 777 全盘", re.compile(r"(?i)\bchmod\s+-R\s+777\s+(/|~)")),
+    ("禁止 shutdown / reboot / halt", re.compile(r"(?i)\b(shutdown|reboot|halt|poweroff)\b")),
+]
+
+
+class CommandGuard:
+    @staticmethod
+    def check(command: str) -> Optional[str]:
+        if not command or not command.strip():
+            return None
+        normalized = re.sub(r"\s+", " ", command.strip())
+        for reason, pattern in _RULES:
+            if pattern.search(normalized):
+                return reason
+        return None

voxcli/policy/exception.py

@@ -0,0 +1,5 @@
+"""安全策略拦截异常"""
+
+class PolicyException(Exception):
+    """路径围栏、命令围栏等安全策略拦截时抛出"""
+    pass

voxcli/policy/path_guard.py

@@ -0,0 +1,32 @@
+"""路径围栏：文件类工具调用的路径合法性检查"""
+
+import os
+from pathlib import Path
+
+from .exception import PolicyException
+
+
+class PathGuard:
+    def __init__(self, root: str):
+        if not root or not root.strip():
+            raise ValueError("项目根路径不能为空")
+        candidate = Path(root).resolve()
+        self._root_path = candidate
+
+    @property
+    def root_path(self) -> Path:
+        return self._root_path
+
+    def resolve_safe(self, input_path: str) -> Path:
+        if not input_path or not input_path.strip():
+            raise PolicyException("路径不能为空")
+
+        raw = Path(input_path)
+        resolved = raw if raw.is_absolute() else (self._root_path / raw)
+        resolved = resolved.resolve()
+
+        if not str(resolved).startswith(str(self._root_path)):
+            raise PolicyException(
+                f"路径越界: {input_path} 不在项目根 {self._root_path} 之内"
+            )
+        return resolved

voxcli/prompting/__init__.py

@@ -0,0 +1,7 @@
+from .presenter import PresentationMode, PresentationResult, ResponsePresenter
+
+__all__ = [
+    "PresentationMode",
+    "PresentationResult",
+    "ResponsePresenter",
+]

voxcli/prompting/presenter.py

@@ -0,0 +1,154 @@
+"""Presentation layer for user-facing reply rendering."""
+
+from dataclasses import dataclass
+from enum import Enum
+import logging
+import re
+from typing import Optional, Union
+
+from ..config import pai_config
+from ..llm.base import LlmClient, Message
+
+logger = logging.getLogger(__name__)
+
+PRESENTER_GUARD_PROMPT = """你不是任务执行者，你是结果转述者。
+
+你的任务是：基于“原始回复”进行人格化重述，让它更像桌面宠物 Vox 在向主人汇报。
+
+硬规则：
+1. 只能基于提供的原始回复重述，不得新增事实、步骤、结论。
+2. 不得伪造任何工具调用、文件读取、联网搜索、代码修改行为。
+3. 所有代码块、命令、路径、URL、JSON、错误正文必须原样保留。
+4. 可以调整语气、顺序和解释方式，但不能改变技术含义。
+5. 如果原始回复已经很短，只做轻度自然化改写。
+6. 如果原始回复较长，可以“人格化开场 + 专业正文保留”。
+7. 默认只输出给主人看的最终回复，不要解释你如何改写。
+"""
+
+_STATS_RE = re.compile(r"(?:\n|\A)📊 Token:.*$", re.S)
+
+
+class PresentationMode(str, Enum):
+    WORK = "work"
+    PET = "pet"
+
+    @classmethod
+    def normalize(cls, value: Optional[str]) -> "PresentationMode":
+        if not value:
+            return cls.WORK
+        normalized = value.strip().lower()
+        return cls.PET if normalized == cls.PET.value else cls.WORK
+
+    @classmethod
+    def is_valid(cls, value: Optional[str]) -> bool:
+        if not value:
+            return False
+        return value.strip().lower() in {cls.WORK.value, cls.PET.value}
+
+
+@dataclass
+class PresentationResult:
+    raw_response: str
+    display_response: str
+    used_presenter: bool = False
+
+
+class ResponsePresenter:
+    def __init__(self, llm_client: LlmClient):
+        self._llm = llm_client
+
+    def present(self, user_input: str, raw_response: str,
+                mode: Union[PresentationMode, str]) -> PresentationResult:
+        normalized_mode = PresentationMode.normalize(
+            mode.value if isinstance(mode, PresentationMode) else mode
+        )
+        if not raw_response:
+            return PresentationResult(raw_response=raw_response, display_response=raw_response)
+
+        if normalized_mode == PresentationMode.WORK:
+            return PresentationResult(raw_response=raw_response, display_response=raw_response)
+
+        stats = _extract_stats(raw_response)
+        body = _strip_stats(raw_response)
+        source = _extract_presentable_body(body)
+
+        if _looks_strictly_structured(source):
+            return PresentationResult(raw_response=raw_response, display_response=raw_response)
+
+        prompt = _build_presenter_input(user_input, source)
+        persona_prompt = pai_config.get_active_persona_prompt()
+
+        try:
+            response = self._llm.chat([
+                Message.system(persona_prompt + "\n\n" + PRESENTER_GUARD_PROMPT),
+                Message.user(prompt),
+            ])
+            display = (response.content or "").strip()
+            if not display:
+                return PresentationResult(raw_response=raw_response, display_response=raw_response)
+            if _contains_code_block(source) and not _preserves_code_block(source, display):
+                logger.warning("Presenter output dropped code block, falling back to raw response")
+                return PresentationResult(raw_response=raw_response, display_response=raw_response)
+            final = display if not stats else f"{display}\n\n{stats}"
+            return PresentationResult(
+                raw_response=raw_response,
+                display_response=final,
+                used_presenter=True,
+            )
+        except Exception as e:
+            logger.warning("Presenter LLM failed, falling back to raw response: %s", e)
+            return PresentationResult(raw_response=raw_response, display_response=raw_response)
+
+
+def _build_presenter_input(user_input: str, raw_response: str) -> str:
+    return (
+        "请将下面的原始回复改写成桌面宠物 Vox 对主人的自然汇报。\n\n"
+        f"用户原始输入：\n{user_input}\n\n"
+        "要求：\n"
+        "- 可爱但克制，别太吵\n"
+        "- 优先准确，别改事实\n"
+        "- 需要保留所有技术正文中的代码、命令、路径、URL、错误、JSON\n"
+        "- 不要输出多余解释\n\n"
+        f"原始回复：\n{raw_response}"
+    )
+
+
+def _strip_stats(text: str) -> str:
+    return _STATS_RE.sub("", text).strip()
+
+
+def _extract_stats(text: str) -> str:
+    match = _STATS_RE.search(text)
+    return match.group(0).strip() if match else ""
+
+
+def _extract_presentable_body(text: str) -> str:
+    marker = "\n\n🤖 回复:\n"
+    if marker in text:
+        return text.split(marker, 1)[1].strip()
+    return text.strip()
+
+
+def _looks_strictly_structured(text: str) -> bool:
+    stripped = text.strip()
+    if not stripped:
+        return True
+    if stripped.startswith("{") and stripped.endswith("}"):
+        return True
+    if stripped.startswith("[") and stripped.endswith("]"):
+        return True
+    if stripped.startswith("```json") or stripped.startswith("```yaml"):
+        return True
+    if '"approved"' in stripped and stripped.count("{") >= 1:
+        return True
+    if '"steps"' in stripped or '"tasks"' in stripped:
+        return True
+    return False
+
+
+def _contains_code_block(text: str) -> bool:
+    return "```" in text
+
+
+def _preserves_code_block(source: str, display: str) -> bool:
+    return source.count("```") == display.count("```")

voxcli/rag/__init__.py

@@ -0,0 +1,16 @@
+from .chunk import CodeChunk
+from .chunker import CodeChunker
+from .embedding import EmbeddingClient
+from .store import VectorStore
+from .index import CodeIndex
+from .retriever import CodeRetriever
+from .formatter import SearchResultFormatter
+from .tokenizer import RagQueryTokenizer
+from .relation import CodeRelation
+from .analyzer import CodeAnalyzer
+
+__all__ = [
+    "CodeChunk", "CodeChunker", "EmbeddingClient", "VectorStore",
+    "CodeIndex", "CodeRetriever", "SearchResultFormatter",
+    "RagQueryTokenizer", "CodeRelation", "CodeAnalyzer",
+]