feat(tools): add HugeGraph AI DeepWiki assistant - #71
Conversation
|
@codecov-ai-reviewer review |
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
✅ Files skipped from review due to trivial changes (4)
🚧 Files skipped from review as they are similar to previous changes (2)
Walkthrough本 PR 新增并发布 hugegraph-ai-deepwiki-skill:包含多平台插件元数据、英文/中文文档与 SKILL 规范、DeepWiki MCP 集成声明,以及完整的 Python MCP 客户端实现、离线检索、CLI 和单元测试。 ChangesHugeGraph AI DeepWiki 技能完整发布
Sequence Diagram(s)sequenceDiagram
participant CLI as CLI (deepwiki_mcp.py)
participant Client as McpClient
participant MCP as DeepWiki_MCP
participant Cache as 本地缓存
CLI->>Client: initialize() / call_tool(ask/contents/context/structure/tools)
Client->>MCP: JSON-RPC HTTP request
MCP-->>Client: HTTP response (JSON) or SSE (text/event-stream)
alt SSE
MCP-->>Client: SSE chunks (data:)
Client->>Client: read_sse_response -> parse by id
else JSON
MCP-->>Client: JSON body
Client->>Client: parse_json -> extract result
end
Client->>Cache: write_text_atomic(wiki-contents.md)
Client-->>CLI: 输出抽取文本或上下文片段 / 返回退出码
Estimated code review effort🎯 3 (中等) | ⏱️ ~25 分钟 Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsStopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Code Review
This pull request introduces the "hugegraph-ai-deepwiki-skill" module, which packages a repository knowledge assistant for Apache HugeGraph AI as a Claude Code and Codex skill. It includes configuration files, documentation, and a Python-based MCP client ("deepwiki_mcp.py") that manages local caching and searches. Feedback on the changes suggests a performance optimization in the search functionality of "deepwiki_mcp.py" to perform a fast substring check before executing regular expression matching on text windows.
| def build_term_patterns(terms: list[str]) -> list[tuple[re.Pattern[str], int]]: | ||
| patterns: list[tuple[re.Pattern[str], int]] = [] | ||
| for term in terms: | ||
| pattern = rf"(?<![a-z0-9_]){re.escape(term)}(?![a-z0-9_])" | ||
| weight = max(1, min(len(term), 12)) | ||
| patterns.append((re.compile(pattern), weight)) | ||
| return patterns | ||
|
|
||
|
|
||
| def score_window(lowered: str, patterns: list[tuple[re.Pattern[str], int]]) -> int: | ||
| score = 0 | ||
| for pattern, weight in patterns: | ||
| count = len(pattern.findall(lowered)) | ||
| if count: | ||
| score += count * weight | ||
| if "relevant source files" in lowered: | ||
| score -= 40 | ||
| if lowered.count("src/main/") > 4 or lowered.count(".java") > 6: | ||
| score -= 60 | ||
| return score |
There was a problem hiding this comment.
To improve search efficiency, we can avoid running the regular expression search on windows that do not contain the search term at all. Since term is already lowercase and we search in lowered, a simple and fast substring check (term in lowered) can bypass the regex engine entirely for non-matching windows. This significantly reduces CPU usage and execution time when processing large wiki files with many search terms.
def build_term_patterns(terms: list[str]) -> list[tuple[str, re.Pattern[str], int]]:
patterns: list[tuple[str, re.Pattern[str], int]] = []
for term in terms:
pattern = rf"(?<![a-z0-9_]){re.escape(term)}(?![a-z0-9_])"
weight = max(1, min(len(term), 12))
patterns.append((term, re.compile(pattern), weight))
return patterns
def score_window(lowered: str, patterns: list[tuple[str, re.Pattern[str], int]]) -> int:
score = 0
for term, pattern, weight in patterns:
if term in lowered:
count = len(pattern.findall(lowered))
if count:
score += count * weight
if "relevant source files" in lowered:
score -= 40
if lowered.count("src/main/") > 4 or lowered.count(".java") > 6:
score -= 60
return scoreThere was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py`:
- Around line 118-125: load_repos currently only wraps FileNotFoundError and
json.JSONDecodeError but lets other I/O and decoding errors leak; update
load_repos to catch OSError (or more specifically UnicodeDecodeError) around
REPOS_PATH.open and also catch any other exceptions raised by json.load (e.g.,
unexpected value errors) and re-raise them as McpError so main() sees a unified
error; reference the load_repos function, REPOS_PATH and McpError when locating
where to add these additional except clauses and ensure you chain the original
exception (raise McpError(...) from exc).
- Around line 372-379: The function ensure_cached_contents should not let raw
filesystem exceptions bubble up; wrap the file reads/writes and calls that
access the cache (contents_cache_path usage, path.exists(), path.read_text(...),
write_text_atomic(...)) in a try/except that catches OSError/IOError (or
Exception for broad coverage) and re-raises a McpError with a clear message
including repo_name and the underlying error; keep the same return tuple (text,
path, bool) on success and ensure read_wiki_contents() errors are also
translated to McpError if they propagate here.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 825fb618-2ab9-42b9-90d1-af1c2aebc718
📒 Files selected for processing (10)
tools/ai/hugegraph-ai-deepwiki-skill/.agents/plugins/marketplace.jsontools/ai/hugegraph-ai-deepwiki-skill/.claude-plugin/marketplace.jsontools/ai/hugegraph-ai-deepwiki-skill/README-zh.mdtools/ai/hugegraph-ai-deepwiki-skill/README.mdtools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.claude-plugin/plugin.jsontools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.codex-plugin/plugin.jsontools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/SKILL.mdtools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/agents/openai.yamltools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/references/repos.jsontools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py
There was a problem hiding this comment.
Pull request overview
This PR adds an optional, standalone “HugeGraph AI DeepWiki assistant” tool module under tools/ai/hugegraph-ai-deepwiki-skill. It packages a Claude Code / Codex skill that answers repository-scoped questions about apache/hugegraph-ai by retrieving from DeepWiki (with a local cache for repeated context searches).
Changes:
- Adds installation + usage documentation (English / Chinese) for Claude Code and Codex.
- Adds skill definition (
SKILL.md), repo profile mapping (repos.json), and an OpenAI/Codex agent manifest (agents/openai.yaml). - Adds a small Python CLI (
deepwiki_mcp.py) implementing DeepWiki MCP calls (structure,contents,context,ask,tools) with local wiki contents caching.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/ai/hugegraph-ai-deepwiki-skill/README.md | English installation/usage docs for the assistant module. |
| tools/ai/hugegraph-ai-deepwiki-skill/README-zh.md | Chinese installation/usage docs for the assistant module. |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/SKILL.md | Skill instructions/workflow and routing guidance for DeepWiki retrieval. |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py | DeepWiki MCP client + local cache search CLI implementation. |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/references/repos.json | Repo alias mapping (hugegraph-ai → apache/hugegraph-ai). |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/agents/openai.yaml | Agent manifest wiring DeepWiki MCP as a dependency. |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.codex-plugin/plugin.json | Codex plugin manifest for packaging/install. |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/.claude-plugin/plugin.json | Claude plugin manifest for packaging/install. |
| tools/ai/hugegraph-ai-deepwiki-skill/.claude-plugin/marketplace.json | Claude marketplace manifest pointing at the local plugin. |
| tools/ai/hugegraph-ai-deepwiki-skill/.agents/plugins/marketplace.json | Agents marketplace manifest pointing at the local plugin. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| def load_repos() -> dict[str, dict[str, Any]]: | ||
| try: | ||
| with REPOS_PATH.open("r", encoding="utf-8") as file: | ||
| repos = json.load(file) | ||
| except FileNotFoundError as exc: | ||
| raise McpError(f"Repository profile file is missing: {REPOS_PATH}") from exc | ||
| except json.JSONDecodeError as exc: | ||
| raise McpError(f"Repository profile file is not valid JSON: {REPOS_PATH}") from exc | ||
|
|
||
| if not isinstance(repos, dict): | ||
| raise McpError(f"Repository profile file must contain a JSON object: {REPOS_PATH}") | ||
| return repos |
| def ensure_cached_contents(client: McpClient, repo_name: str, refresh: bool = False) -> tuple[str, Path, bool]: | ||
| path = contents_cache_path(repo_name) | ||
| if path.exists() and not refresh: | ||
| return path.read_text(encoding="utf-8"), path, False | ||
|
|
||
| text = read_wiki_contents(client, repo_name) | ||
| write_text_atomic(path, text) | ||
| return text, path, True |
| ```text | ||
| Install the HugeGraph AI repository assistant from this checkout. Enter `tools/ai/hugegraph-ai-deepwiki-skill`, run `claude plugin marketplace add "$(pwd)"`, then run `claude plugin install hugegraph-ai-deepwiki-skill@hugegraph-ai-deepwiki-skill`. Do not hardcode absolute paths. | ||
| ``` |
| ```text | ||
| Install the HugeGraph AI repository assistant from this checkout. Enter `tools/ai/hugegraph-ai-deepwiki-skill`, run `codex plugin marketplace add "$(pwd)"`, then run `codex plugin add hugegraph-ai-deepwiki-skill@hugegraph-ai-deepwiki-skill`. If this Codex build has no plugin add command, copy `plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill` into `${CODEX_HOME:-$HOME/.codex}/skills`. Do not hardcode absolute paths. | ||
| ``` |
| ```text | ||
| Use $hugegraph-ai-deepwiki-skill to explain the HugeGraph AI RAG workflow. | ||
| ``` |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/tests/test_deepwiki_mcp.py`:
- Around line 18-104: The file fails ruff formatting; run ruff format on this
test module and fix any style issues (imports grouping, unused imports, line
lengths, trailing whitespace, blank lines) so it passes `ruff format --check`;
specifically ensure functions and classes like load_mcp_module, TimeoutResponse,
and DeepWikiMcpTest (and its test_* methods) conform to ruff/PEP8 rules and
adjust import order/spacing, remove or use any unused symbols, and wrap long
string literals or comments to satisfy line-length checks before committing.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: e88fddb7-cbef-463b-9f75-407bb9390d68
📒 Files selected for processing (3)
tools/ai/hugegraph-ai-deepwiki-skill/README-zh.mdtools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.pytools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/tests/test_deepwiki_mcp.py
✅ Files skipped from review due to trivial changes (1)
- tools/ai/hugegraph-ai-deepwiki-skill/README-zh.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.gitattributes:
- Around line 17-18: The rules for the scripts paths currently use the negation
prefix "-export-ignore" which cancels the attribute; update the two entries
referencing tools/ai/hugegraph-ai-deepwiki-skill/.../scripts/ and
tools/ai/hugegraph-ai-deepwiki-skill/.../scripts/** to use "export-ignore"
(remove the leading '-') or simply remove these two lines and rely on the
existing "scripts/ export-ignore" rule (Line 16) to avoid redundancy; ensure the
final entries use "export-ignore" so the scripts/ directories are excluded from
archives.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: bc6999aa-3b27-4b7e-9e46-36f5e6e0ddab
📒 Files selected for processing (6)
.gitattributestools/ai/hugegraph-ai-deepwiki-skill/README-zh.mdtools/ai/hugegraph-ai-deepwiki-skill/README.mdtools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/SKILL.mdtools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.pytools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/tests/test_deepwiki_mcp.py
✅ Files skipped from review due to trivial changes (2)
- tools/ai/hugegraph-ai-deepwiki-skill/README-zh.md
- tools/ai/hugegraph-ai-deepwiki-skill/README.md
🚧 Files skipped from review as they are similar to previous changes (3)
- tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/SKILL.md
- tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/tests/test_deepwiki_mcp.py
- tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore | ||
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore |
There was a problem hiding this comment.
严重语法错误:-export-ignore 会取消排除属性,与预期相反。
Lines 17-18 使用了 -export-ignore(前缀 -),在 gitattributes 语法中,前缀 - 表示取消该属性,而不是设置该属性。这将导致 scripts/ 目录在打包时被包含到源代码归档中,而非排除。
根据文件中其他所有规则(Lines 2-16, 19-20)的语法,应使用 export-ignore(无前缀 -)。
此外,Line 16 已经有 scripts/ export-ignore 规则,它会匹配仓库中任意层级的 scripts/ 目录,因此 Lines 17-18 在修复后可能是冗余的(但显式声明也是可接受的)。
🐛 修复语法错误的建议
方案 1(推荐): 移除冗余规则,依赖 Line 16 的通用 scripts/ 排除规则:
-tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore
-tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore方案 2: 如果需要显式声明此路径,修正语法(移除前缀 -):
-tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore
-tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore
+tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ export-ignore
+tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** export-ignore📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ -export-ignore | |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** -export-ignore | |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/ export-ignore | |
| tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/** export-ignore |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.gitattributes around lines 17 - 18, The rules for the scripts paths
currently use the negation prefix "-export-ignore" which cancels the attribute;
update the two entries referencing
tools/ai/hugegraph-ai-deepwiki-skill/.../scripts/ and
tools/ai/hugegraph-ai-deepwiki-skill/.../scripts/** to use "export-ignore"
(remove the leading '-') or simply remove these two lines and rely on the
existing "scripts/ export-ignore" rule (Line 16) to avoid redundancy; ensure the
final entries use "export-ignore" so the scripts/ directories are excluded from
archives.
Purpose
Add an optional HugeGraph AI repository knowledge assistant under
tools/ai. The assistant is intended for Claude Code and Codex users who want repository-scoped Q&A for https://github.com/apache/hugegraph-ai, using DeepWiki as the online knowledge source while caching wiki contents locally for repeated context search.Changes
tools/ai/hugegraph-ai-deepwiki-skillas a standalone installable module.README.mdandREADME-zh.md.structure,contents,context,ask, andtools.Verification
python3 -m json.toolon all new JSON manifests.python3 -m py_compile tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.uv run --extra dev ruff format --check tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.uv run --extra dev ruff check tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill/skills/hugegraph-ai-deepwiki-skill/scripts/deepwiki_mcp.py.claude plugin validate tools/ai/hugegraph-ai-deepwiki-skill.claude plugin validate tools/ai/hugegraph-ai-deepwiki-skill/plugins/hugegraph-ai-deepwiki-skill.codex plugin marketplace addandcodex plugin add.structure, cachedcontext, and onlineaskforapache/hugegraph-ai.--limit.Compatibility
This is an optional tool module only. It does not change HugeGraph AI runtime behavior, public APIs, package dependencies, or default configuration.
Summary by CodeRabbit
新功能
文档
测试
维护