nexforge-cli 0.1.0__py3-none-any.whl

nexforge/store/plan_store.py

@@ -0,0 +1,112 @@
+"""计划文件存储 —— 项目 .nexforge/plans/ 下的 .plan.md 文件。
+
+每个计划文件:
+  - 标题:取首行 # 或 ## 作为显示名
+  - 正文:完整 MD 计划
+  - 进度:统计 [x] / [ ] 约定或表格完成行
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _plans_dir() -> Path:
+    return Path.cwd() / ".nexforge" / "plans"
+
+
+@dataclass
+class PlanInfo:
+    id: str          # 文件名(不含 .plan.md)
+    title: str       # 计划标题
+    path: Path       # 完整路径
+    total: int = 0   # 总任务数
+    done: int = 0    # 已完成任务数
+    content: str = ""  # 缓存内容(切换时用)
+
+
+def _ensure_dir() -> None:
+    _plans_dir().mkdir(parents=True, exist_ok=True)
+
+
+def save_plan(title: str, content: str, plan_id: str = "") -> Path:
+    """保存计划文件。返回文件路径。"""
+    _ensure_dir()
+    if not plan_id:
+        import time
+        plan_id = f"plan-{int(time.time())}"
+    path = _plans_dir() / f"{plan_id}.plan.md"
+    md = f"# {title}\n\n{content}"
+    path.write_text(md, encoding="utf-8")
+    return path
+
+
+def load_plan(plan_id: str) -> str | None:
+    """加载计划的完整 MD 内容。"""
+    path = _plans_dir() / f"{plan_id}.plan.md"
+    if not path.is_file():
+        return None
+    return path.read_text(encoding="utf-8")
+
+
+def list_plans() -> list[PlanInfo]:
+    """列出所有计划,附进度统计。"""
+    d = _plans_dir()
+    if not d.is_dir():
+        return []
+    infos: list[PlanInfo] = []
+    for md in sorted(d.glob("*.plan.md")):
+        text = md.read_text(encoding="utf-8")
+        title = _read_title(text)
+        total, done = _count_progress(text)
+        pid = md.stem.removesuffix(".plan")  # plan-xxx.plan.md → plan-xxx
+        infos.append(PlanInfo(
+            id=pid,
+            title=title or pid,
+            path=md,
+            total=total,
+            done=done,
+        ))
+    return infos
+
+
+def delete_plan(plan_id: str) -> bool:
+    path = _plans_dir() / f"{plan_id}.plan.md"
+    if path.is_file():
+        path.unlink()
+        return True
+    return False
+
+
+def update_plan_progress(plan_id: str, content: str) -> None:
+    """用最新内容覆写计划文件(保留标题)。"""
+    path = _plans_dir() / f"{plan_id}.plan.md"
+    if not path.is_file():
+        return
+    old = path.read_text(encoding="utf-8")
+    # 保留原标题
+    title_line = old.split("\n")[0] if old.startswith("#") else f"# {plan_id}"
+    path.write_text(f"{title_line}\n\n{content}", encoding="utf-8")
+
+
+def _read_title(text: str) -> str | None:
+    for line in text.split("\n"):
+        s = line.strip()
+        if s.startswith("# "):
+            return s[2:].strip() or None
+        if s.startswith("## "):
+            return s[3:].strip() or None
+    return None
+
+
+def _count_progress(text: str) -> tuple[int, int]:
+    """统计 [x] 和 [ ] 标记的任务数。"""
+    done = len(re.findall(r"^\s*- \[[xX]\]", text, re.MULTILINE))
+    total = len(re.findall(r"^\s*- \[[xX\s]\]", text, re.MULTILINE))
+    # 如果没有 checkbox,用表格行数(跳过表头)估计
+    if total == 0:
+        rows = re.findall(r"^\|\s*\d+\s*\|", text, re.MULTILINE)
+        total = len(rows)
+    return total, done

nexforge/store/session_store.py

@@ -0,0 +1,206 @@
+"""会话持久化引擎 —— 按项目+日期保存 MD 文件。
+
+目录结构:
+  .nexforge/sessions/{项目名}/{YYYY-MM-DD}/
+    {序号}-{会话名}.md
+
+每个 MD 包含完整对话(用户/助手/工具调用/工具结果),
+人可直接阅读。每轮完成自动写入;`/save [name]` 手动命名。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+def _sessions_dir() -> Path:
+    """会话存储目录:项目根/.nexforge/sessions/。"""
+    return Path.cwd() / ".nexforge" / "sessions"
+
+
+@dataclass
+class SessionInfo:
+    id: str          # 文件名(不含 .md)
+    name: str        # 会话标题
+    path: Path       # 完整路径
+    created: str     # ISO 日期
+    message_count: int = 0
+
+
+def _project_name() -> str:
+    """从当前工作目录名取项目名。"""
+    return Path.cwd().name or "default"
+
+
+def _today_dir() -> Path:
+    base = _sessions_dir()
+    today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+    d = base / today
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def _next_id(directory: Path, name: str = "") -> str:
+    """生成稳定的时间戳文件名(标题才是显示名,可随对话更新)。"""
+    ts = datetime.now(timezone.utc).strftime("%H%M%S")
+    cand = f"session-{ts}"
+    n = 1
+    while (directory / f"{cand}.md").exists():
+        n += 1
+        cand = f"session-{ts}-{n}"
+    return cand
+
+
+def _format_message(msg: dict) -> str:
+    """单条消息转 Markdown 块。"""
+    role = msg.get("role", "?")
+    content = msg.get("content", "")
+    reasoning = msg.get("reasoning_content", "")
+    tool_calls = msg.get("tool_calls")
+
+    if role == "system":
+        return f"> ℹ {content}\n"
+    if role == "user":
+        return f"### ❯ 用户\n\n{content}\n"
+    if role == "assistant":
+        parts = [f"### ◆ 助手\n"]
+        if reasoning:
+            parts.append(f"<details>\n<summary>💭 思考中…</summary>\n\n{reasoning}\n</details>\n")
+        if content:
+            parts.append(content)
+        if tool_calls:
+            for tc in tool_calls:
+                fn = tc.get("function", {})
+                parts.append(
+                    f"\n🔧 `{fn.get('name', '?')}` "
+                    f"`{fn.get('arguments', '')[:200]}`\n"
+                )
+        return "".join(parts) + "\n"
+    if role == "tool":
+        tool_id = msg.get("tool_call_id", "")
+        return f"> 🔧 结果 `{tool_id[:8]}…`:\n>\n> {content.strip()}\n"
+    return f"_{role}: {content}_\n"
+
+
+def save_session(session_id: str, name: str, messages: list[dict]) -> Path:
+    """把消息列表写成 MD 文件,返回文件路径。"""
+    target = _today_dir() / f"{session_id}.md"
+    lines = [
+        f"# {name}",
+        f"",
+        f"> 创建 {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
+        f"> 项目 `{_project_name()}`",
+        f"",
+        "---",
+        "",
+    ]
+    for msg in messages:
+        lines.append(_format_message(msg))
+    target.write_text("\n".join(lines), encoding="utf-8")
+    return target
+
+
+def load_session(path: Path) -> list[dict] | None:
+    """从 MD 文件重建消息列表(仅含 user/assistant/system 消息)。"""
+    if not path.is_file():
+        return None
+    text = path.read_text(encoding="utf-8")
+    messages: list[dict] = []
+    current_role = ""
+    current_content: list[str] = []
+    skip_details = False
+
+    def _flush() -> None:
+        nonlocal current_content
+        if current_role and current_content:
+            messages.append({"role": current_role, "content": "\n".join(current_content).strip()})
+            current_content = []
+
+    for line in text.splitlines():
+        # <details> 块内全部跳过(含 <summary> 和思考正文)
+        if line.startswith("<details>"):
+            skip_details = True
+            continue
+        if skip_details:
+            if line.startswith("</details>"):
+                skip_details = False
+            continue
+
+        if line.startswith("### ❯ 用户"):
+            _flush()
+            current_role = "user"
+        elif line.startswith("### ◆ 助手"):
+            _flush()
+            current_role = "assistant"
+        elif line.startswith("> ℹ"):
+            _flush()
+            current_role = "system"
+            current_content.append(line[3:].strip())
+        elif line.startswith("> 🔧 结果") or line.startswith("🔧"):
+            current_role = ""
+        elif line == "---" or line.startswith("# "):
+            continue
+        elif line.startswith("> 创建") or line.startswith("> 项目"):
+            continue
+        elif current_role:
+            current_content.append(line)
+    _flush()
+    return messages if messages else None
+
+
+def list_sessions() -> list[SessionInfo]:
+    """列出当前项目所有会话(按时间倒序)。"""
+    proj = _sessions_dir()
+    if not proj.is_dir():
+        return []
+    infos: list[SessionInfo] = []
+    for day_dir in sorted(proj.iterdir(), reverse=True):
+        if not day_dir.is_dir():
+            continue
+        for md in sorted(day_dir.glob("*.md"), key=os.path.getmtime, reverse=True):
+            name = _read_title(md) or md.stem
+            infos.append(SessionInfo(
+                id=md.stem,
+                name=name,
+                path=md,
+                created=day_dir.name,
+                message_count=_count_messages(md),
+            ))
+    return infos
+
+
+def _read_title(path: Path) -> str | None:
+    try:
+        first = path.read_text(encoding="utf-8").split("\n", 1)[0]
+        return first.lstrip("# ").strip() or None
+    except Exception:
+        return None
+
+
+def _count_messages(path: Path) -> int:
+    try:
+        text = path.read_text(encoding="utf-8")
+        return text.count("### ❯ 用户")
+    except Exception:
+        return 0
+
+
+def delete_session(session_id: str) -> bool:
+    today = _today_dir()
+    target = today / f"{session_id}.md"
+    if target.exists():
+        target.unlink()
+        return True
+    # 也搜其他日期目录
+    proj = _sessions_dir()
+    for day_dir in proj.iterdir():
+        if not day_dir.is_dir():
+            continue
+        t = day_dir / f"{session_id}.md"
+        if t.exists():
+            t.unlink()
+            return True
+    return False

nexforge/theme.tcss

@@ -0,0 +1,128 @@
+/* NexForgeCLI 主题 —— 品牌色 #6D5EF5(靛) / #22D3EE(青)。
+ *
+ * 背景:不做透明(Textual alt-screen 限制),使用终端原生暗色系,
+ * 与主流终端(Windows Terminal / iTerm2 / Kitty)暗色主题融为一体。
+ */
+
+Screen {
+    background: #101014;
+}
+
+/* 水平容器:主区 + 侧边栏 */
+Horizontal {
+    height: 1fr;
+}
+#main-area {
+    width: 1fr;
+    margin: 0 1 0 0;
+}
+
+/* 顶部品牌横幅 */
+#banner {
+    height: auto;
+    padding: 1 2 0 2;
+}
+
+/* 聊天记录区:占据剩余空间,可滚动 */
+#chat-log {
+    height: 1fr;
+    padding: 0 2;
+    scrollbar-size-vertical: 1;
+    scrollbar-color: #6D5EF5 30%;
+}
+
+/* 聊天记录区:占据剩余空间,可滚动 */
+#chat-log {
+    height: 1fr;
+    padding: 0 2;
+    scrollbar-size-vertical: 1;
+    scrollbar-color: #6D5EF5 30%;
+}
+
+/* 用户消息 */
+UserMessage {
+    height: auto;
+    margin: 1 0 0 0;
+    color: $text;
+}
+
+/* 助手回合容器 */
+AssistantTurn {
+    height: auto;
+    margin: 1 0 0 0;
+}
+
+/* 思考面板 */
+AssistantTurn Collapsible {
+    border-left: outer #6D5EF5 30%;
+    color: $text-muted;
+    margin: 0 0 1 0;
+}
+AssistantTurn Collapsible > Contents {
+    color: $text-muted;
+    max-height: 12;
+    overflow-y: auto;
+    scrollbar-size-vertical: 1;
+}
+#reasoning-body {
+    color: $text-muted;
+    text-style: italic;
+}
+
+/* 正文 markdown */
+AssistantTurn Markdown {
+    margin: 0;
+    padding: 0;
+}
+/* 压掉段落/标题的默认下边距,避免句子之间出现大空白 */
+AssistantTurn Markdown MarkdownParagraph {
+    margin: 0;
+}
+AssistantTurn Markdown MarkdownH1,
+AssistantTurn Markdown MarkdownH2,
+AssistantTurn Markdown MarkdownH3,
+AssistantTurn Markdown MarkdownH4 {
+    margin: 0;
+    padding: 0;
+}
+
+/* 工具卡片 */
+ToolCard {
+    height: auto;
+    margin: 0 0 0 1;
+    color: #22D3EE;
+}
+
+/* 系统提示 / 错误 */
+SystemNote {
+    height: auto;
+    margin: 1 0;
+    color: $text-warning;
+}
+
+/* 状态栏 */
+#status {
+    height: 1;
+    padding: 0 2;
+    color: $text-muted;
+}
+
+/* 输入框 */
+#prompt {
+    dock: bottom;
+    margin: 0 0 1 0;
+    border: solid #6D5EF5;
+    height: auto;
+    max-height: 7;
+    overflow-y: auto;
+}
+#prompt:focus {
+    border: round #22D3EE;
+}
+#prompt-hint {
+    height: 1;
+    dock: bottom;
+    color: $text-muted;
+    text-style: dim;
+    padding: 0 2;
+}

nexforge/tools/__init__.py

@@ -0,0 +1,6 @@
+"""工具层:BaseTool / 注册表 / 内置工具。"""
+
+from nexforge.tools.base import BaseTool, ToolResult
+from nexforge.tools.registry import ToolRegistry, default_registry
+
+__all__ = ["BaseTool", "ToolResult", "ToolRegistry", "default_registry"]

nexforge/tools/_paths.py

@@ -0,0 +1,22 @@
+"""工具通用辅助:路径解析与输出截断。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+MAX_OUTPUT_CHARS = 20_000
+
+
+def resolve(path: str) -> Path:
+    """相对路径按当前工作目录解析。"""
+    p = Path(path).expanduser()
+    if not p.is_absolute():
+        p = Path.cwd() / p
+    return p
+
+
+def truncate(text: str, limit: int = MAX_OUTPUT_CHARS) -> str:
+    if len(text) <= limit:
+        return text
+    head = text[:limit]
+    return f"{head}\n… [输出被截断,共 {len(text)} 字符,已显示前 {limit}]"

nexforge/tools/background.py

@@ -0,0 +1,111 @@
+"""后台作业工具:run_background / job_output / wait_for_job / stop_job / list_jobs。"""
+
+from __future__ import annotations
+
+from nexforge.core.jobs import job_manager
+from nexforge.tools._paths import truncate
+from nexforge.tools.base import BaseTool, ToolResult
+
+
+class RunBackgroundTool(BaseTool):
+    name = "run_background"
+    description = "在后台启动一个长时进程(dev server / 监听 / 下载等),立即返回作业 id,不阻塞。"
+    parameters = {
+        "type": "object",
+        "properties": {"command": {"type": "string", "description": "要执行的命令"}},
+        "required": ["command"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def preview(self, args: dict) -> str:
+        return f"run_background($ {args.get('command', '')[:50]})"
+
+    def run(self, command: str) -> ToolResult:
+        try:
+            job = job_manager.start(command)
+        except Exception as exc:
+            return ToolResult(ok=False, error=f"启动失败:{exc}")
+        return ToolResult(
+            ok=True,
+            output=f"已启动后台作业 #{job.id}(pid {job.proc.pid}):{command}",
+            summary=f"job #{job.id} started",
+        )
+
+
+class JobOutputTool(BaseTool):
+    name = "job_output"
+    description = "读取后台作业最近输出。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "job_id": {"type": "integer"},
+            "tail_lines": {"type": "integer", "description": "末尾行数,默认 80"},
+        },
+        "required": ["job_id"],
+    }
+
+    def run(self, job_id: int, tail_lines: int = 80) -> ToolResult:
+        job = job_manager.get(job_id)
+        if job is None:
+            return ToolResult(ok=False, error=f"无此作业:#{job_id}")
+        status = "运行中" if job.running else f"已退出(code {job.exit_code})"
+        body = f"[作业 #{job_id} {status}]\n{job.tail(tail_lines)}"
+        return ToolResult(ok=True, output=truncate(body), summary=f"job #{job_id} {status}")
+
+
+class WaitForJobTool(BaseTool):
+    name = "wait_for_job"
+    description = "阻塞等待后台作业结束(或超时)。返回是否退出 + 最近输出。"
+    parameters = {
+        "type": "object",
+        "properties": {
+            "job_id": {"type": "integer"},
+            "timeout": {"type": "integer", "description": "最大等待秒数,默认 60"},
+        },
+        "required": ["job_id"],
+    }
+
+    def run(self, job_id: int, timeout: int = 60) -> ToolResult:
+        job = job_manager.wait(job_id, timeout)
+        if job is None:
+            return ToolResult(ok=False, error=f"无此作业:#{job_id}")
+        exited = not job.running
+        status = f"已退出(code {job.exit_code})" if exited else "仍在运行(超时)"
+        body = f"[作业 #{job_id} {status}]\n{job.tail(40)}"
+        return ToolResult(ok=exited, output=truncate(body), summary=f"job #{job_id} {status}")
+
+
+class StopJobTool(BaseTool):
+    name = "stop_job"
+    description = "停止后台作业(SIGTERM,必要时 SIGKILL)。"
+    parameters = {
+        "type": "object",
+        "properties": {"job_id": {"type": "integer"}},
+        "required": ["job_id"],
+    }
+    requires_approval = True
+    parallel_safe = False
+
+    def run(self, job_id: int) -> ToolResult:
+        job = job_manager.stop(job_id)
+        if job is None:
+            return ToolResult(ok=False, error=f"无此作业:#{job_id}")
+        return ToolResult(ok=True, output=f"已停止作业 #{job_id}", summary=f"job #{job_id} stopped")
+
+
+class ListJobsTool(BaseTool):
+    name = "list_jobs"
+    description = "列出本会话所有后台作业(运行中 + 已退出)。"
+    parameters = {"type": "object", "properties": {}}
+
+    def run(self) -> ToolResult:
+        jobs = job_manager.all()
+        if not jobs:
+            return ToolResult(ok=True, output="(无后台作业)", summary="0 jobs")
+        lines = [
+            f"#{j.id}  {'运行中' if j.running else f'退出{j.exit_code}'}  "
+            f"pid={j.proc.pid}  {j.command[:50]}"
+            for j in jobs
+        ]
+        return ToolResult(ok=True, output="\n".join(lines), summary=f"{len(jobs)} jobs")

nexforge/tools/base.py

@@ -0,0 +1,56 @@
+"""工具基类与结果类型。
+
+每个工具声明 name/description/parameters(JSON Schema),实现 run()。
+写类/危险工具置 requires_approval=True,由上层审批门处理(M2 起接 UI)。
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class ToolResult:
+    ok: bool
+    output: str = ""
+    error: str = ""
+    # 供 UI 摘要显示(如受影响文件、行数)
+    summary: str = ""
+
+    def to_content(self) -> str:
+        """转成回灌给模型的 tool 消息内容。"""
+        if self.ok:
+            return self.output if self.output else "(无输出)"
+        return f"ERROR: {self.error}"
+
+
+class BaseTool(ABC):
+    name: str = ""
+    description: str = ""
+    parameters: dict = {"type": "object", "properties": {}}
+    requires_approval: bool = False
+    # 只读工具可并行;写类工具需串行(M2 调度用)
+    parallel_safe: bool = True
+
+    def to_openai(self) -> dict:
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def preview(self, args: dict) -> str:
+        """一行参数摘要,用于 UI 的工具卡片(如 read_file(src/x.py:1-40))。"""
+        if not args:
+            return self.name
+        head = ", ".join(f"{k}={v}" for k, v in list(args.items())[:2])
+        return f"{self.name}({head})"
+
+    @abstractmethod
+    def run(self, **kwargs) -> ToolResult:
+        """同步执行。Agent 会在线程池中调用,避免阻塞事件循环。"""
+        raise NotImplementedError