nexforge-cli 0.2.11__tar.gz → 0.2.12__tar.gz

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nexforge-cli
-Version: 0.2.11
+Version: 0.2.12
 Summary: NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)
 Project-URL: Homepage, https://gitee.com/Lighthorn/nexforgecli
 Author: NexForge

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/manual/01-/345/256/211/350/243/205/344/270/216/351/205/215/347/275/256.md

@@ -1,6 +1,6 @@
 # 安装与配置
 
-> NexForgeCLI v0.2.11
+> NexForgeCLI v0.2.12
 
 ## 环境要求
 

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/manual/04-/345/267/245/345/205/267/345/217/202/350/200/203.md

@@ -49,6 +49,8 @@ NexForgeCLI 内置 **35 个工具**供 AI 调用（`git_commit` 需在 config.to
 | `image_gen` | 图片生成(阿里云通义万相) |
 | `kb_search` | 知识库检索(全局+项目两级) |
 | `kb_write` | 知识沉淀(写入项目/全局知识库) |
+| `window_screenshot` | 指定窗口截图(Windows, 标题/进程定位, 遮挡也能截) |
+| `web_screenshot` | Web 页面离线渲染截图(无头浏览器, 不弹窗) |
 
 详见 [05-数据与搜索](05-数据与搜索.md)。
 
@@ -77,7 +79,9 @@ NexForgeCLI 内置 **35 个工具**供 AI 调用（`git_commit` 需在 config.to
 
 | 工具 | 功能 |
 |------|------|
-| `federation` | 多项目联结体管理 |
+| `federation` | 多项目联结体管理(init/add/remove/context/status/memory/sessions/handoff/close/task-add/task-list/task-done) |
+| `kb_search` | 知识检索(scope 支持 fed 聚合联结体成员、member:<名> 指定成员) |
+| `kb_write` | 知识沉淀(scope 支持 `member:<成员名>` 写回联结体成员知识库) |
 
 ## 工具限制
 

nexforge_cli-0.2.12/manual/07-/344/274/232/350/257/235/344/270/216/350/256/260/345/277/206.md

@@ -0,0 +1,100 @@
+# 会话与记忆
+
+## 会话管理
+
+### 自动保存
+
+每次 AI 回复完成后自动保存当前会话到 `.nexforge/sessions/`，文件为可读 Markdown 格式。
+
+### 自动恢复
+
+启动时自动恢复当前项目最近一次会话，包括完整对话历史。
+
+### 长会话上下文压缩
+
+超过 60 轮时自动压缩：保留最近 20 轮全文，更早的对话压缩为**历史摘要**（恢复后可见，避免历史大段丢失）；被压缩的原始对话**完整归档**到 `.nexforge/sessions/<id>.archive.md`，随时可查。
+
+### 会话侧边栏
+
+按 `F5` 打开会话侧边栏：
+
+- **新建会话**：点击 `+ 新建会话`
+- **切换会话**：点击会话名，自动保存当前、加载选中
+- **重命名**：`/rename 新名称`
+- **删除**：点击 `✖` 按钮
+
+当前活跃会话有绿色圆点标记。
+
+### 相关命令
+
+| 命令 | 说明 |
+|------|------|
+| `/save [name]` | 保存并命名当前会话 |
+| `/rename <name>` | 重命名当前会话 |
+| `/sessions` | 列出历史会话 |
+| `/clear` | 清空当前会话 |
+| `/cost` | 显示累计 token 和费用 |
+
+## 项目记忆
+
+NexForgeCLI 支持多层记忆，让 AI 在多次对话中持久记住项目信息。
+
+### 记忆类型
+
+| 记忆层 | 文件 | 作用 |
+|--------|------|------|
+| **基础记忆** | `.nexforge/memory/base.md` | 所有场景共享的持久信息 |
+| **运维记忆** | `.nexforge/memory/ops.md` | 运维操作记录(服务器配置、常用命令) |
+| **目标记忆** | `.nexforge/memory/goal.md` | 目标模式专用上下文 |
+| **已验证方案** | `.nexforge/ops_known.md` | 运维已验证的成功命令/调用(读取复用,可手动维护) |
+
+启动时自动加载基础记忆。运维模式开启时额外加载运维记忆。
+
+### 联 结体
+
+联结体是**多项目协同工作区**。关联多个相关项目，为每个项目设定角色，AI 在联结体上下文中工作，
+**并把工作写回各成员项目自身结构**，保证成员回到各自的 nf 实例继续开发时零信息割裂。
+
+```bash
+# 在 nf 输入框里用 /federation 命令
+/federation init                     # 初始化联结体
+/federation add <项目路径> [角色]     # 添加成员(名称取目录名, 角色可选如 后端)
+/federation remove <名称>            # 移除成员
+/federation context                  # 查看联结体上下文(成员+角色+最近共享记忆)
+/federation status                   # 查看各成员实时状态(git分支/未提交/最近会话)
+/federation memory                   # 查看共享记忆
+/federation sessions                 # 列出各成员项目的会话历史
+/federation handoff                  # 为所有成员生成/更新交接文档
+/federation close                    # 结束本次协同: 全成员写回(交接+地图+纪要会话)
+```
+
+#### 双向同步机制（写回）
+
+联结体是**临时工作区**，各成员项目是**持久家园**。协同期间自动写回：
+
+| 写回内容 | 落点(成员项目内) | 触发 |
+|---------|-----------------|------|
+| 每轮操作日志 | `.nexforge/ops_log.md` | 每轮结束自动 |
+| 进展记忆 | `.nexforge/memory/base.md` | 每轮结束自动 |
+| 项目地图刷新 | `.nexforge/map/` | 轮末哈希比对,有变化才 sync |
+| 知识沉淀 | `.nexforge/kb/`(`kb_write scope=member:<名>`) | AI 主动 |
+| 交接文档 | `.nexforge/federation/handoff.md` | `/federation close` 或 `handoff` |
+| 工作纪要会话 | `.nexforge/sessions/session-*.md` | `/federation close` |
+
+成员项目回到自身 nf 启动时，若检测到 `handoff.md` 会自动注入交接上下文，AI 延续工作不割裂。
+`kb_write` 支持 `scope=member:<成员名>` 直接把知识写回指定成员的知识库；
+`kb_search` 支持 `scope=fed`(聚合检索所有成员知识库) 和 `scope=member:<名>`(检索指定成员)。
+
+#### 任务流转
+
+AI 通过 `federation` 工具管理跨成员任务(`.nexforge/federation/tasks.md`)：
+
+```
+federation task-add name=<成员> content=<任务描述>   # 分配任务, 返回 #id
+federation task-list                                # 列出所有任务及状态
+federation task-done content=<id>                   # 标记任务完成
+```
+
+#### 双向记忆
+
+共享记忆按「用户指令 + AI 决策」成对记录(每轮自动)，供联结体上下文读取，协同意图可追溯。

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/manual/README.md

@@ -1,4 +1,4 @@
-# NexForgeCLI 用户手册 · v0.2.11
+# NexForgeCLI 用户手册 · v0.2.12
 
 ## 这是什么
 

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "nexforge-cli"
-version = "0.2.11"
+version = "0.2.12"
 description = "NexForgeCLI — 一个面向 DeepSeek V4 的终端智能体(TUI + CLI 双模式)"
 readme = "README.md"
 requires-python = ">=3.11"

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/src/nexforge/__init__.py

@@ -3,5 +3,5 @@
 TUI(全屏交互)+ CLI(one-shot / 管道)双模式。
 """
 
-__version__ = "0.2.11"
+__version__ = "0.2.12"
 __all__ = ["__version__"]

nexforge_cli-0.2.12/src/nexforge/core/federation.py

@@ -0,0 +1,494 @@
+"""联结体引擎 —— 多项目联结,共享记忆与会话,协同工作写回各成员项目。
+
+设计原则: 联结体是临时工作区, 各成员项目是持久家园。
+所有可归属到成员项目的产出(日志/进展/地图/交接)必须写回成员项目自身结构,
+保证成员项目回到各自的 nf 实例继续开发时零信息割裂。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+
+import tomllib
+
+
+@dataclass
+class Member:
+    name: str         # 项目名
+    path: Path        # 绝对路径
+    git_remote: str = ""  # git remote URL
+    git_branch: str = ""  # 当前分支
+    role: str = ""    # 角色(如 前端/后端/文档/基础设施)
+
+
+@dataclass
+class Federation:
+    name: str
+    root: Path  # 主项目目录
+    members: list[Member] = field(default_factory=list)
+    memory: str = ""  # 共享记忆内容
+    _config_path: Path | None = None
+
+    # 写回文件的行数上限
+    MAX_LOG_LINES = 500      # ops_log.md
+    MAX_MEM_LINES = 800      # memory/base.md
+    MAX_FED_MEM_LINES = 400  # federation/memory.md
+
+    @property
+    def dir(self) -> Path:
+        return self.root / ".nexforge" / "federation"
+
+    @property
+    def memory_path(self) -> Path:
+        return self.dir / "memory.md"
+
+    @property
+    def sessions_dir(self) -> Path:
+        return self.dir / "sessions"
+
+    def init(self) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        self.sessions_dir.mkdir(parents=True, exist_ok=True)
+        if not self.memory_path.exists():
+            self.memory_path.write_text("# 联结体共享记忆\n\n", encoding="utf-8")
+        self._save_config()
+
+    def add_member(self, name: str, project_path: Path, role: str = "") -> Member:
+        p = project_path.resolve()
+        # 重名防御: 同名成员已存在则拒绝(修复: 重复 add 导致 get_member 歧义/写回混乱)
+        if self.get_member(name) is not None:
+            raise ValueError(f"成员已存在: {name}")
+        # 获取 git 信息
+        remote = ""
+        branch = ""
+        try:
+            import subprocess
+            r = subprocess.run(
+                ["git", "-C", str(p), "remote", "get-url", "origin"],
+                capture_output=True, text=True, timeout=5
+            )
+            if r.returncode == 0:
+                remote = r.stdout.strip()
+            r = subprocess.run(
+                ["git", "-C", str(p), "branch", "--show-current"],
+                capture_output=True, text=True, timeout=5
+            )
+            if r.returncode == 0:
+                branch = r.stdout.strip()
+        except Exception:
+            pass
+        member = Member(name=name, path=p, git_remote=remote, git_branch=branch, role=role)
+        self.members.append(member)
+        self._save_config()
+        return member
+
+    def remove_member(self, name: str) -> None:
+        self.members = [m for m in self.members if m.name != name]
+        self._save_config()
+
+    def get_member(self, name: str) -> Member | None:
+        return next((m for m in self.members if m.name == name), None)
+
+    def member_status(self, member: Member) -> str:
+        """单成员状态: git 分支 / 工作区未提交数 / 最近会话时间(P2-9 状态面板)。"""
+        parts: list[str] = []
+        git_ok = False
+        try:
+            import subprocess
+            r = subprocess.run(
+                ["git", "-C", str(member.path), "branch", "--show-current"],
+                capture_output=True, text=True, timeout=5
+            )
+            if r.returncode == 0:
+                git_ok = True
+                if r.stdout.strip():
+                    parts.append(f"分支 {r.stdout.strip()}")
+            r2 = subprocess.run(
+                ["git", "-C", str(member.path), "status", "--porcelain"],
+                capture_output=True, text=True, timeout=5
+            )
+            if r2.returncode == 0:
+                git_ok = True
+                if r2.stdout.strip():
+                    n = len([l for l in r2.stdout.splitlines() if l.strip()])
+                    parts.append(f"未提交 {n} 项")
+                else:
+                    parts.append("工作区干净")
+        except Exception:
+            pass
+        if not git_ok:
+            parts.append("非 git 项目")  # 修复: 原把 git 命令失败误报为"工作区干净"
+        infos = self.list_member_sessions(member)
+        if infos:
+            parts.append(f"最近会话 {infos[0].created}")
+        return " | ".join(parts)
+
+    def status_report(self) -> str:
+        """全成员状态报告(/federation status 与 AI 工具用)。"""
+        lines = [f"[联结体: {self.name}] 成员状态:"]
+        for m in self.members:
+            role = f" (角色: {m.role})" if m.role else ""
+            lines.append(f"  - {m.name}: {m.path}{role}")
+            lines.append(f"      {self.member_status(m)}")
+        return "\n".join(lines)
+
+    # ── 共享记忆(治理: 去重 + 上限) ─────────────────────────
+
+    def read_memory(self) -> str:
+        from nexforge.tools._paths import sanitize
+        if self.memory_path.exists():
+            try:
+                text = self.memory_path.read_text(encoding="utf-8")
+            except (UnicodeDecodeError, OSError):
+                text = ""  # 记忆文件损坏时容错(修复: 原直接抛异常)
+            return sanitize(text)
+        return ""
+
+    def append_memory(self, text: str) -> None:
+        from nexforge.tools._paths import sanitize
+        text = sanitize(text).strip()
+        if not text:
+            return
+        # 单条限长(防超大文本撑爆记忆; 修复: 原无限制)
+        if len(text) > 2000:
+            text = text[:2000] + "…(截断)"
+        current = self.read_memory()
+        # 去重: 核心内容(去掉 ## 时间戳行)完整存在则不追加(防每轮重复刷屏;
+        # 修复: 原 core[:80] 会导致同指令不同决策时漏记新决策)
+        core = "\n".join(
+            l.strip() for l in text.splitlines()
+            if l.strip() and not l.strip().startswith("## ")
+        ).strip()
+        if core and core in current:
+            return
+        current += f"\n{text}\n"
+        # 上限: 超 400 行保留尾部 300 行(最新记忆优先)
+        lines = current.splitlines()
+        if len(lines) > self.MAX_FED_MEM_LINES:
+            current = "\n".join(lines[-300:]) + "\n"
+        self.memory_path.write_text(current, encoding="utf-8")
+
+    def list_member_sessions(self, member: Member) -> list:
+        """列出成员的会话(从其 .nexforge/sessions 目录)。
+
+        直接扫描扁平目录 + 旧日期子目录(异步安全,不切换 cwd)。
+        """
+        from nexforge.store.session_store import SessionInfo, _BASE_RE
+        sessions_dir = member.path / ".nexforge" / "sessions"
+        if not sessions_dir.is_dir():
+            return []
+        from datetime import datetime as _dt, timezone as _tz
+        infos: list[SessionInfo] = []
+        seen: set[str] = set()
+
+        def _add(md: Path, created: str) -> None:
+            if md.stem in seen:
+                return
+            # 只收基础会话文件(复用 session_store 的正则,新旧格式统一;
+            # 修复:旧正则会把新格式 session-YYYYMMDD-HHMMSS-ffffff.md
+            # 误判为分段文件导致联结体列表看不到任何新会话)
+            if not _BASE_RE.match(md.name):
+                return
+            seen.add(md.stem)
+            name = self._read_title(md) or md.stem
+            infos.append(SessionInfo(
+                id=md.stem,
+                name=name,
+                path=md,
+                created=created,
+                message_count=self._count_messages(md),
+            ))
+
+        # 新格式:扁平目录
+        for md in sorted(sessions_dir.glob("*.md"), key=os.path.getmtime, reverse=True):
+            created = _dt.fromtimestamp(md.stat().st_mtime, tz=_tz.utc).strftime("%Y-%m-%d")
+            _add(md, created)
+
+        # 旧格式:YYYY-MM-DD/ 子目录
+        for day_dir in sorted(sessions_dir.iterdir(), reverse=True):
+            if not day_dir.is_dir():
+                continue
+            for md in sorted(day_dir.glob("*.md"), key=os.path.getmtime, reverse=True):
+                _add(md, day_dir.name)
+
+        return infos
+
+    @staticmethod
+    def _read_title(path: Path) -> str | None:
+        from nexforge.tools._paths import sanitize
+        try:
+            first = path.read_text(encoding="utf-8").split("\n", 1)[0]
+            title = first.lstrip("# ").strip()
+            return sanitize(title) or None
+        except Exception:
+            return None
+
+    @staticmethod
+    def _count_messages(path: Path) -> int:
+        try:
+            text = path.read_text(encoding="utf-8")
+            return text.count("### \u276f 用户")
+        except Exception:
+            return 0
+
+    # ── 上下文 ──────────────────────────────────────────────
+
+    def context_prompt(self) -> str:
+        """构建 AI 上下文:联结体信息 + 共享记忆(读最近, 新记忆优先)。"""
+        parts = [f"[联结体: {self.name}]"]
+        parts.append(f"项目数: {len(self.members)}")
+        for m in self.members:
+            parts.append(f"  - {m.name}: {m.path}" + (f" (角色: {m.role})" if m.role else ""))
+            if m.git_branch:
+                parts.append(f"    git: {m.git_remote} ({m.git_branch})")
+        memory = self.read_memory()
+        if memory.strip():
+            # 去掉 init 标题行后仍有内容才算有记忆(避免空联结体输出无意义标题)
+            mem_body = "\n".join(
+                l for l in memory.splitlines()
+                if l.strip() and not l.startswith("# 联结体共享记忆")
+            )
+            if mem_body.strip():
+                parts.append(f"\n## 共享记忆(最近)\n{memory[-2000:]}")
+        return "\n".join(parts)
+
+    # ── 写回机制: 联结体工作 → 成员项目自身结构 ─────────────
+
+    @staticmethod
+    def _member_file(member: Member, rel: str) -> Path:
+        """成员项目内文件(自动创建父目录)。"""
+        p = member.path / ".nexforge" / rel
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return p
+
+    @staticmethod
+    def _append_limited(path: Path, entry: str, max_lines: int, keep_tail: int) -> None:
+        """追加条目,超行数时保留尾部。"""
+        if path.exists():
+            lines = path.read_text(encoding="utf-8", errors="replace").splitlines()
+            if len(lines) > max_lines:
+                path.write_text("\n".join(lines[-keep_tail:]) + "\n", encoding="utf-8")
+        with path.open("a", encoding="utf-8") as f:
+            f.write(entry)
+
+    def append_member_log(self, member: Member, text: str) -> Path:
+        """写回: 成员项目 .nexforge/ops_log.md 追加联结体工作条目。"""
+        from nexforge.tools._paths import sanitize
+        log = self._member_file(member, "ops_log.md")
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        entry = f"\n## {ts} [联结体:{self.name}]\n{sanitize(text).strip()}\n"
+        self._append_limited(log, entry, self.MAX_LOG_LINES, self.MAX_LOG_LINES - 100)
+        return log
+
+    def append_member_progress(self, member: Member, text: str) -> Path:
+        """写回: 成员项目 .nexforge/memory/base.md 追加联结体进展条目。"""
+        from nexforge.tools._paths import sanitize
+        mem = self._member_file(member, "memory/base.md")
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        entry = f"\n## [联结体:{self.name}] {ts}\n{sanitize(text).strip()}\n"
+        self._append_limited(mem, entry, self.MAX_MEM_LINES, self.MAX_MEM_LINES - 100)
+        return mem
+
+    def sync_member_map(self, member: Member) -> bool:
+        """写回: 刷新成员项目地图(哈希比对, 有变化才全量 sync)。"""
+        try:
+            from nexforge.core.project_mapper import ProjectMapper
+            mapper = ProjectMapper(member.path)
+            report = mapper.check()
+            if not report.get("in_sync"):
+                mapper.sync()
+                return True
+        except Exception:
+            pass
+        return False
+
+    def write_back(self, member: Member, *, summary: str = "",
+                   progress: str = "", sync_map: bool = True) -> list[Path]:
+        """综合写回一个成员: 操作日志 + 进展记忆 + (可选)地图刷新。
+
+        返回写出的文件路径列表。单项失败不影响其他(异常保护)。
+        成员目录已不存在时跳过(不重建空 .nexforge)。
+        """
+        if not member.path.is_dir():
+            return []
+        out: list[Path] = []
+        try:
+            if summary.strip():
+                out.append(self.append_member_log(member, summary))
+        except OSError:
+            pass
+        try:
+            if progress.strip():
+                out.append(self.append_member_progress(member, progress))
+        except OSError:
+            pass
+        if sync_map:
+            self.sync_member_map(member)
+        return out
+
+    def generate_handoff(self, member: Member, *, goal: str = "",
+                         summary: str = "", next_steps: str = "") -> Path:
+        """生成/更新成员交接文档 .nexforge/federation/handoff.md。
+
+        成员项目回到自身 nf 实例时, 启动检测到此文件会注入上下文, 零割裂延续。
+        """
+        p = self._member_file(member, "federation/handoff.md")
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        content = (
+            f"# 联结体交接 — {member.name}\n\n"
+            f"- 联结体: {self.name} | 更新时间: {ts}\n"
+            f"- 成员路径: {member.path}\n"
+            f"- 角色: {member.role or '未指定'}\n\n"
+            f"## 协同目标\n{goal.strip() or '(未记录)'}\n\n"
+            f"## 本次改动\n{summary.strip() or '(未记录)'}\n\n"
+            f"## 下一步建议\n{next_steps.strip() or '(未记录)'}\n"
+        )
+        p.write_text(content, encoding="utf-8")
+        return p
+
+    def _write_member_summary_session(self, member: Member, summary: str) -> Path | None:
+        """写回: 成员 .nexforge/sessions/ 写入一条'联结体工作纪要'会话(可 /load 查看)。"""
+        try:
+            from nexforge.store.session_store import _next_id
+            sid = _next_id()  # 已含 "session-" 前缀(修复: 曾重复拼接导致文件名 session-session-*.md 不被会话列表识别)
+            f = member.path / ".nexforge" / "sessions" / f"{sid}.md"
+            f.parent.mkdir(parents=True, exist_ok=True)
+            ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+            body = (
+                f"# 联结体工作纪要\n\n> 创建 {ts}\n"
+                f"> 项目 {member.name}\n\n"
+                f"### ◆ 助手\n\n"
+                f"这是联结体 [{self.name}] 工作期间本项目的操作纪要"
+                f"(生成于 {ts})。\n\n"
+                f"{summary.strip() or '(无记录)'}\n"
+            )
+            f.write_text(body, encoding="utf-8")
+            return f
+        except Exception:
+            return None
+
+    def close(self, *, goal: str = "", summary: str = "", next_steps: str = "") -> dict[str, list[Path]]:
+        """结束联结体工作: 为所有成员生成交接文档 + 刷新地图 + 写纪要会话。
+
+        返回 {成员名: [写出的文件...]}。不销毁联结体配置(可继续 add/复用)。
+        """
+        result: dict[str, list[Path]] = {}
+        # summary 为空时自动取共享记忆尾部, 避免交接文档/纪要会话内容空洞
+        if not summary.strip():
+            mem = self.read_memory()
+            if mem.strip():
+                summary = "(自动摘要, 详见联结体 memory.md)\n" + mem.strip()[-500:]
+        for m in self.members:
+            files: list[Path] = []
+            if not m.path.is_dir():
+                continue  # 成员目录已不存在: 跳过写回(不重建空目录)
+            try:
+                files.append(self.generate_handoff(m, goal=goal, summary=summary, next_steps=next_steps))
+                self.sync_member_map(m)
+                sess = self._write_member_summary_session(m, summary)
+                if sess:
+                    files.append(sess)
+            except OSError:
+                pass  # 单成员写回失败不影响其他成员
+            result[m.name] = files
+        return result
+
+    # ── 任务流转 ────────────────────────────────────────────
+
+    def _tasks_path(self) -> Path:
+        return self.dir / "tasks.md"
+
+    def task_add(self, member_name: str, content: str) -> str:
+        """给成员添加任务。返回任务 id。"""
+        tasks = self._tasks_path()
+        tasks.parent.mkdir(parents=True, exist_ok=True)
+        text = tasks.read_text(encoding="utf-8") if tasks.exists() else ""
+        ids = [int(m.group(1)) for m in re.finditer(r"#(\d+)", text)]
+        tid = max(ids, default=0) + 1
+        ts = datetime.now().strftime("%Y-%m-%d %H:%M")
+        # 任务描述换行压平为空格(修复: 多行描述会破坏 task_done 的块定位)
+        flat = content.strip().replace("\n", " ").replace("\r", "")
+        with tasks.open("a", encoding="utf-8") as f:
+            f.write(f"\n## [{ts}] #{tid} [{member_name}] {flat}\n状态: 待办\n")
+        return str(tid)
+
+    def task_list(self) -> str:
+        """列出所有任务(最新在后)。"""
+        tasks = self._tasks_path()
+        if not tasks.exists():
+            return "(无任务)"
+        return tasks.read_text(encoding="utf-8").strip() or "(无任务)"
+
+    def task_done(self, task_id: str) -> bool:
+        """标记任务完成(按 #id 定位块, 只改该任务的状态)。"""
+        tasks = self._tasks_path()
+        if not tasks.exists():
+            return False
+        lines = tasks.read_text(encoding="utf-8").splitlines()
+        target = f"#{task_id} "
+        in_block = False
+        done = False
+        out: list[str] = []
+        for line in lines:
+            if line.startswith("## "):
+                in_block = target in line
+            if in_block and line.strip() == "状态: 待办":
+                line = f"状态: ✅ 完成 ({datetime.now().strftime('%Y-%m-%d %H:%M')})"
+                done = True
+            out.append(line)
+        if done:
+            tasks.write_text("\n".join(out) + "\n", encoding="utf-8")
+        return done
+
+    # ── 配置持久化 ──────────────────────────────────────────
+
+    @staticmethod
+    def _tstr(v: str) -> str:
+        """TOML 基本字符串转义: 反斜杠/双引号/控制字符(防自由文本破坏配置)。"""
+        return (v.replace("\\", "\\\\").replace('"', '\\"')
+                 .replace("\n", "\\n").replace("\r", "\\r").replace("\t", "\\t"))
+
+    def _save_config(self) -> None:
+        self._config_path = self.dir / "federation.toml"
+        lines = [f'name = "{self._tstr(self.name)}"']
+        for m in self.members:
+            lines.append("")
+            lines.append("[[member]]")
+            lines.append(f'name = "{self._tstr(m.name)}"')
+            lines.append(f'path = "{self._tstr(m.path.as_posix())}"')
+            if m.git_remote:
+                lines.append(f'git_remote = "{self._tstr(m.git_remote)}"')
+            if m.git_branch:
+                lines.append(f'git_branch = "{self._tstr(m.git_branch)}"')
+            if m.role:
+                lines.append(f'role = "{self._tstr(m.role)}"')
+        self._config_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+    @staticmethod
+    def load(root: Path) -> Federation | None:
+        config = root / ".nexforge" / "federation" / "federation.toml"
+        if not config.exists():
+            return None
+        try:
+            with config.open("rb") as f:
+                data = tomllib.load(f)
+            fed = Federation(
+                name=data.get("name", ""),
+                root=root,
+            )
+            for mdata in data.get("member", []):
+                fed.members.append(Member(
+                    name=mdata.get("name", ""),
+                    path=Path(mdata.get("path", "")),
+                    git_remote=mdata.get("git_remote", ""),
+                    git_branch=mdata.get("git_branch", ""),
+                    role=mdata.get("role", ""),
+                ))
+            fed._config_path = config
+            return fed
+        except Exception:
+            return None

{nexforge_cli-0.2.11 → nexforge_cli-0.2.12}/src/nexforge/core/knowledge_base.py

@@ -159,11 +159,18 @@ class KnowledgeBase:
     def search(self, query: str, scope: str = "all", top_k: int = 5) -> str:
         """行级多关键词打分检索, 每文件一条最佳命中(含上下文±1行)。"""
         self.ensure()
+        return self._search_in_dirs(query, self.dirs(scope), top_k)
+
+    def _search_in_dirs(self, query: str, dirs: list[Path], top_k: int = 5) -> str:
+        """行级多关键词打分检索(目录列表版)。
+
+        供跨成员聚合检索复用(kb_search scope=fed / member:<名>)。
+        """
         tokens = self._tokens(query)
         if not tokens:
             return "(空查询)"
         best: dict[Path, tuple[float, int, str]] = {}  # file -> (score, line_no, ctx)
-        for d in self.dirs(scope):
+        for d in dirs:
             for rel, meta in self._refresh_index(d).items():
                 f = d / rel
                 if not f.is_file():