codewiki-plus 5.2.2__tar.gz → 5.3.0__tar.gz

{codewiki_plus-5.2.2 → codewiki_plus-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codewiki-plus
-Version: 5.2.2
+Version: 5.3.0
 Summary: Transform codebases into comprehensive documentation using AI-powered analysis
 Author: CodeWiki Contributors
 License: MIT
@@ -93,6 +93,15 @@ Requires-Dist: ruff>=0.1.0; extra == "dev"
 
 ## 中文
 
+### 专栏文章
+
+「迎风追日 / WanderingBug」公众号发布的本项目系列技术专栏，欢迎阅读：
+
+- [专栏开篇词：从代码文档到 AI 知识引擎](https://mp.weixin.qq.com/s/WpjiDAs62_81mytBWUsDQw)（2026-07-26）
+- [第 2 篇：双层 Prompt 架构同时服务人和模型](https://mp.weixin.qq.com/s/1lNjR_SsrU5Fw2NKnkxnMA)（2026-08-01）
+- [第 3 篇：零依赖检索设计](https://mp.weixin.qq.com/s/T7r-ojyWC-YOpM_U5BNbEw)（2026-08-06）
+- [第 4 篇：知识写入方式全景](https://mp.weixin.qq.com/s/V90mghqB5wttKd25eXA-Pw)（2026-08-09）
+
 ### 这个项目是什么？
 
 CodeWiki-Plus 是 [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki) 的增强分支，核心改动是**让 CodeWiki 无需配置任何大模型 API，直接由 AI IDE（CodeBuddy、Cursor、Claude Desktop 等）自身的模型驱动 Wiki 文档生成**，并在此基础上构建了完整的知识管理引擎。

{codewiki_plus-5.2.2 → codewiki_plus-5.3.0}/README.md

@@ -26,6 +26,15 @@
 
 ## 中文
 
+### 专栏文章
+
+「迎风追日 / WanderingBug」公众号发布的本项目系列技术专栏，欢迎阅读：
+
+- [专栏开篇词：从代码文档到 AI 知识引擎](https://mp.weixin.qq.com/s/WpjiDAs62_81mytBWUsDQw)（2026-07-26）
+- [第 2 篇：双层 Prompt 架构同时服务人和模型](https://mp.weixin.qq.com/s/1lNjR_SsrU5Fw2NKnkxnMA)（2026-08-01）
+- [第 3 篇：零依赖检索设计](https://mp.weixin.qq.com/s/T7r-ojyWC-YOpM_U5BNbEw)（2026-08-06）
+- [第 4 篇：知识写入方式全景](https://mp.weixin.qq.com/s/V90mghqB5wttKd25eXA-Pw)（2026-08-09）
+
 ### 这个项目是什么？
 
 CodeWiki-Plus 是 [FSoft-AI4Code/CodeWiki](https://github.com/FSoft-AI4Code/CodeWiki) 的增强分支，核心改动是**让 CodeWiki 无需配置任何大模型 API，直接由 AI IDE（CodeBuddy、Cursor、Claude Desktop 等）自身的模型驱动 Wiki 文档生成**，并在此基础上构建了完整的知识管理引擎。

{codewiki_plus-5.2.2 → codewiki_plus-5.3.0}/codewiki/__init__.py

@@ -5,7 +5,7 @@ This package provides a CLI tool for generating documentation from code reposito
 and an MCP server for IDE-driven documentation generation.
 """
 
-__version__ = "5.2.2"
+__version__ = "5.3.0"
 __author__ = "CodeWiki Contributors"
 __license__ = "MIT"
 

codewiki_plus-5.3.0/codewiki/hooks/task_session_start.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""CodeBuddy SessionStart hook: inject active-task guidance into a new session.
+
+The task-memory layer lets long-running work span sessions. This hook makes the
+"pick (or create) a task" prompt *deterministic* at session start: it reads
+``repowiki/tasks/.index.json`` and emits a ``hookSpecificOutput.additionalContext``
+instructing the agent to ask the user which task to bind (or to create a new
+one) before work begins.
+
+This is the **source** copy of the hook, shipped inside the ``codewiki``
+package. When a user enables task management, the ``team-memory-hook`` MCP
+prompt copies this file into the project's ``.codebuddy/hooks/task_session_start.py``
+and registers it for the ``SessionStart`` event. CodeBuddy runs the *copied*
+file, not this one.
+
+Why a SessionStart hook (not just AGENTS.md guidance):
+    AGENTS.md guidance is a *soft* constraint — an agent may or may not honor
+    "at session start, list tasks and ask the user". A SessionStart hook is a
+    *hard* trigger: the IDE waits for this script's stdout and injects the
+    returned ``additionalContext`` into the agent's context, so the task prompt is
+    guaranteed to surface every time.
+
+Unlike the SessionEnd capture hook (which fires-and-forgets via a detached
+subprocess), this hook MUST return its ``systemMessage`` synchronously — the IDE
+is waiting on stdout. It is therefore deliberately lightweight: it reads at
+most two small JSON files (task index + raw capture index) and prints one JSON
+line, and never imports the ``codewiki`` package (no import-path dance, fast
+startup, no risk of a slow import blocking the IDE).
+
+CodeBuddy invokes it with the event as JSON on stdin, e.g.:
+
+    {
+      "session_id": "abc123",
+      "transcript_path": "/path/to/transcript.txt",
+      "cwd": "/project/path",
+      "hook_event_name": "SessionStart",
+      "source": "startup"
+    }
+
+Stdout is emitted in the CodeBuddy-expected ``{continue, systemMessage}`` shape.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parents[2]  # <repo>/.codebuddy/hooks/ -> <repo>
+
+
+def _read_event() -> dict:
+    """Read the hook event JSON from stdin ({} when absent/unparseable)."""
+    if sys.stdin.isatty():
+        return {}
+    try:
+        # Read raw bytes and decode leniently: PowerShell pipes may prepend one
+        # or more UTF-8 BOMs, which would break json.loads.
+        raw = sys.stdin.buffer.read().decode("utf-8-sig", errors="replace")
+        raw = raw.lstrip("\ufeff").strip()
+    except Exception:
+        return {}
+    if not raw:
+        return {}
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _resolve_repo_path(event: dict) -> str:
+    """Resolve the repo root, preferring authoritative sources.
+
+    Priority: CODEBUDDY_PROJECT_DIR env var (CodeBuddy-specific) >
+    CLAUDE_PROJECT_DIR (compat) > event's cwd > this script's repo location.
+    Candidates that don't exist on disk are skipped.
+    """
+    candidates = [
+        os.environ.get("CODEBUDDY_PROJECT_DIR"),
+        os.environ.get("CLAUDE_PROJECT_DIR"),
+        event.get("cwd"),
+        str(REPO),
+    ]
+    for c in candidates:
+        if c and os.path.isdir(c):
+            return c
+    return str(REPO)
+
+
+def _load_active_tasks(repo_path: str) -> list:
+    """Read repowiki/tasks/.index.json and return active (non-completed) tasks.
+
+    Returns [] when the index is absent/corrupt (the task layer has never been
+    initialized) — the caller then prompts the user to create a task instead.
+    """
+    idx = Path(repo_path) / "repowiki" / "tasks" / ".index.json"
+    if not idx.is_file():
+        return []
+    try:
+        data = json.loads(idx.read_text(encoding="utf-8-sig", errors="replace"))
+    except (OSError, json.JSONDecodeError):
+        return []
+    tasks = data.get("tasks", []) if isinstance(data, dict) else []
+    return [t for t in tasks if isinstance(t, dict) and t.get("status") == "active"]
+
+
+def _count_pending_raws(repo_path: str) -> dict:
+    """Count un-distilled raw captures grouped by task_id.
+
+    Reads ``repowiki/raw/.index.json`` (maintained by capture_conversation,
+    shape ``{"files": [{"relpath", "status", "task_id", ...}]}``): entries
+    whose status is not "distilled" form the distillation backlog. If the index
+    is missing, falls back to a lightweight frontmatter peek of conv-*.md.
+    Any failure returns {} so the hook degrades silently to its previous
+    behaviour (never breaks task binding). Stays stdlib-only and O(entries).
+    """
+    counts: dict = {}
+    try:
+        raw_dir = Path(repo_path) / "repowiki" / "raw"
+        idx_path = raw_dir / ".index.json"
+        if idx_path.is_file():
+            data = json.loads(idx_path.read_text(encoding="utf-8-sig", errors="replace"))
+            files = data.get("files", []) if isinstance(data, dict) else []
+            for e in files:
+                if not isinstance(e, dict):
+                    continue
+                if str(e.get("status") or "pending") == "distilled":
+                    continue
+                rel = str(e.get("relpath") or "")
+                if not rel or not (raw_dir / rel).is_file():
+                    continue  # stale index entry — the file is gone
+                task_id = str(e.get("task_id") or "")
+                counts[task_id] = counts.get(task_id, 0) + 1
+            return counts
+        # Fallback: no index — peek frontmatter of each raw capture.
+        for p in sorted(raw_dir.glob("conv-*.md")):
+            try:
+                text = p.read_text(encoding="utf-8-sig", errors="replace")
+            except OSError:
+                continue
+            status, task_id = "pending", ""
+            for line in text.splitlines():
+                if line.startswith("status:"):
+                    status = line[len("status:"):].strip().strip("\"'")
+                elif line.startswith("task_id:"):
+                    task_id = line[len("task_id:"):].strip().strip("\"'")
+            if status != "distilled":
+                counts[task_id] = counts.get(task_id, 0) + 1
+    except Exception:
+        return {}
+    return counts
+
+
+def _build_message(event: dict, repo_path: str) -> str:
+    """Build the guidance injected into the fresh session.
+
+    IMPORTANT: the user expects an interactive chooser, NOT a text paragraph.
+    The message below must instruct the agent to surface the choice through the
+    ``ask_followup_question`` tool (the IDE's structured-question UI), so the
+    user can click an option or type a task name, exactly like a native dialog.
+    """
+    session_id = str(event.get("session_id") or "").strip()
+    active = _load_active_tasks(repo_path)
+
+    lines = ["[task-memory] 本会话开始前，请先处理「任务关联」（跨会话任务记忆）。"]
+    lines.append("")
+    lines.append(
+        "【硬性执行顺序】无论用户第一条消息问什么（哪怕是关于代码、文件、bug 的具体问题），"
+        "本会话的第一个动作都必须是下面这个任务关联弹框流程；弹框、绑定、拉取上下文"
+        "（以及有积压时的补蒸馏）全部完成后，才允许开始读文件/搜索代码/回答用户提问。"
+        "严禁先探索代码或直接回答，事后再补弹任务关联框。"
+    )
+    lines.append("")
+    lines.append(
+        "【必须弹框】请立即调用 ask_followup_question 工具弹出结构化选择框"
+        "（这是 IDE 的原生弹框 UI，用户可以直接点击选项），不要用纯文本输出一段话让用户自行回复。"
+        "弹框标题用「任务关联」，提供以下选项："
+    )
+    if active:
+        lines.append("- 关联已有任务：把下面每个进行中任务的标题作为弹框选项，用户选中后调用 "
+                     f"set_session_task(source_session_id={session_id or '<当前会话id>'}, task_id=<选中任务>) 建立绑定")
+        lines.append("  当前进行中的任务：")
+        for t in active:
+            lines.append(f"    - {t.get('title') or t.get('id')}（task_id={t.get('id')}）")
+    else:
+        lines.append("- 新建任务：选择后会再弹一个输入框让用户输入任务名（可补一句描述），调用 "
+                     "create_task(title=<任务名>, description=<可选>) 创建后即关联该新任务")
+    lines.append("- 跳过：本次会话不做任务关联，直接开始干活")
+    lines.append("")
+    lines.append(
+        "【新建任务两步弹框】当用户选择「新建任务」后，必须再次调用 ask_followup_question "
+        "弹出第二个输入框：标题用「新建任务」，问题写「请输入新任务名称」，提供 2 个占位示例选项"
+        "（如「临时任务」「在输入框直接输入名称后回车」）。该弹框自带输入框，用户可自由输入任务名后回车；"
+        "以用户输入的文字为准，立即调用 create_task(title=<任务名>, description=<可选>) 创建并关联该新任务。"
+        "若用户只点击了占位选项，则用文字追问确认真实任务名。"
+    )
+    lines.append("")
+    lines.append(
+        "关联完成后调用 get_task_context(task_id=<选中任务>) 拉取该任务上下文继续工作。"
+        "返回中的 pending_raw_count 是本任务尚未蒸馏的历史对话数：若大于 0，必须先按下方"
+        "「补蒸馏」流程处理完积压，再开始回答用户提问。"
+        "若用户明确表示本次会话与任何任务无关，可跳过本提示。"
+    )
+
+    # Catch-up distillation backlog: deterministic trigger so agents that never
+    # "think to" distill still clear the backlog at session start.
+    pending_counts = _count_pending_raws(repo_path)
+    if pending_counts:
+        total = sum(pending_counts.values())
+        lines.append("")
+        lines.append(f"【补蒸馏】检测到 {total} 条未蒸馏的历史对话积压：")
+        for tid, n in sorted(pending_counts.items()):
+            label = f"任务 {tid}" if tid else "未关联任务"
+            lines.append(f"  - {label}: {n} 条")
+        lines.append(
+            "绑定任务之后、开始回答用户提问之前，对已绑定任务执行补蒸馏："
+        )
+        lines.append(
+            "  1. distill_conversation(mode=\"prepare\", task_id=<绑定的任务id>) "
+            "获取该任务的积压对话清单"
+        )
+        lines.append(
+            "  2. 按清单逐条 read_file 阅读 raw 文件，提取 notes（通用经验）与 memories（任务进度）"
+        )
+        lines.append(
+            "  3. distill_conversation(mode=\"submit\", distilled=<提取结果>) 提交；"
+            "产出为草稿笔记与待确认记忆"
+        )
+        lines.append(
+            "  4. 重新 get_task_context 拉取最新上下文（新产出的待确认记忆/草稿笔记会一并注入）"
+        )
+        lines.append(
+            "  5. 向用户展示待确认项，经 confirm_task_memories / confirm_note 确认后才正式落盘"
+        )
+        lines.append(
+            "若用户明确表示紧急，可先回答提问，但必须在会话结束前完成补蒸馏。"
+            "注意：pending 记忆与 draft 笔记在确认前只能作为只读参考，不得当作已定论的结论引用。"
+        )
+
+    return "\n".join(lines)
+
+
+def main() -> int:
+    event = _read_event()
+    repo_path = _resolve_repo_path(event)
+    message = _build_message(event, repo_path)
+
+    # Ensure CJK task titles survive the Windows console encoding (cp936) when
+    # the IDE reads our stdout.
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except (AttributeError, ValueError, OSError):
+        pass
+
+    # SessionStart injects extra context to the *agent* via
+    # hookSpecificOutput.additionalContext. (systemMessage only surfaces to the
+    # user and never reaches the agent — see the CodeBuddy hooks reference.)
+    output = {
+        "continue": True,
+        "hookSpecificOutput": {
+            "hookEventName": "SessionStart",
+            "additionalContext": message,
+        },
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

{codewiki_plus-5.2.2 → codewiki_plus-5.3.0}/codewiki/mcp/_ide_hook.py

@@ -363,6 +363,8 @@ def main(argv: Optional[list] = None) -> int:
                         "(used to resolve repowiki/raw/).")
     parser.add_argument("--session-id", help="Active session id (optional).")
     parser.add_argument("--link-to", help="Wiki object id this conversation relates to.")
+    parser.add_argument("--task-id", help="Task id this conversation is bound to "
+                        "(stamped into raw frontmatter so distillation routes memories back).")
     parser.add_argument("--keep-raw", action="store_true",
                         help="Hint distill_conversation to retain the raw file.")
     args = parser.parse_args(argv)
@@ -405,9 +407,14 @@ def main(argv: Optional[list] = None) -> int:
                   "usable transcript_path; capturing the event envelope only "
                   "(the IDE did not provide an inline transcript).")
             # Fall through: capture the event envelope as a minimal record.
+            # NOTE: role must be "user" (not "system") -- capture_conversation
+            # drops every role outside {user, assistant} in _extract_transcript,
+            # so a system-role envelope would be silently discarded (see
+            # test_envelope_does_not_supersede_full_transcript). The envelope
+            # body carries no system-injection tags, so stripping is a no-op.
             is_envelope = True
             conversation = [{
-                "role": "system",
+                "role": "user",
                 "content": (f"[team-memory] {hook_event} hook fired but the IDE "
                             "provided no inline transcript and no readable "
                             "transcript_path. Raw event envelope preserved for "
@@ -438,6 +445,14 @@ def main(argv: Optional[list] = None) -> int:
             "" if is_envelope
             else (_pick("session_id", args.session_id) or "")
         ),
+        # Task binding, stamped into raw frontmatter so distill_conversation can
+        # route distilled memories back to the task. Like source_session_id, the
+        # envelope (no real transcript) must NOT carry task_id — it is not a real
+        # conversation and would otherwise pollute per-task memory routing.
+        "task_id": (
+            "" if is_envelope
+            else (_pick("task_id", args.task_id) or "")
+        ),
     }
     if not arguments["repo_path"]:
         print("ide-hook: repo_path is required to resolve repowiki/raw/.", file=sys.stderr)

{codewiki_plus-5.2.2 → codewiki_plus-5.3.0}/codewiki/mcp/cache.py

@@ -266,14 +266,16 @@ def _build_indexable_text(content: str, page_type: Optional[str] = None) -> str:
         parts.append(aliases_text)
         parts.append(aliases_text)
 
-    # LLM Wiki: severity boost (for pitfall/known_issue notes)
-    severity = fm.get("severity", "")
+    # LLM Wiki: severity boost (for pitfall/known_issue notes) — may be folded
+    # under metadata: (OKF §4/§5)
+    _meta = fm.get("metadata") or {}
+    severity = fm.get("severity", "") or _meta.get("severity", "")
     if isinstance(severity, str) and severity:
         parts.append(severity)
         parts.append(severity)
 
     # LLM Wiki: related_modules 2x boost (module names for cross-reference discovery)
-    related = fm.get("related_modules", [])
+    related = fm.get("related_modules", []) or _meta.get("related_modules", [])
     if isinstance(related, list):
         related_text = " ".join(str(r) for r in related)
     elif isinstance(related, str):