使用说明
gitnexus稳定运营
为AI代理提供360°代码库视图。
阻止Copilot和Claude Code打断他们不认识的来电者。
gitnexus-stable-ops 是一个生产运营工具包，可以保持 GitNexus 在25个以上的存储库中可靠运行——零嵌入损失、零版本漂移、零脏图意外。
“专为自主智能体群体设计” — @d3thshot7777GitNexus维护者
为39多个OpenClaw代理提供动力·14个上游PR→ 7 合并·3个月以上生产
快速开始
git clone https://github.com/ShunsukeHayashi/gitnexus-stable-ops.git
cd gitnexus-stable-ops && make install
# Diagnose a repo
bin/gitnexus-doctor.sh ~/dev/my-repo my-repo MyClassName
# Smart reindex (skips if up-to-date, protects embeddings)
REPO_PATH=~/dev/my-repo bin/gitnexus-auto-reindex.sh
# See what breaks if you change a class
gni impact AuthService
✅ Direct callers (d=1): UserController.login, SessionManager.refresh
⚠️ Transitive deps (d=2): 14 files affected
🔴 Risk: HIGH — update callers before merging
为什么存在
GitNexus是当今最强大的开源代码智能引擎之一。但运行它 生产 --在人工智能代理工作流程中，通过自动重新索引，在数十个存储库中暴露出四个关键的操作问题：
| 问题 | 影响 | 此工具包的修复 |
|---|---|---|
| 版本漂移 | CLI和MCP引用不同版本，导致数据损坏 | 固定二进制文件($GITNEXUS_BIN)所有脚本都使用 |
| 嵌入损失 | analyze --force 静默删除嵌入 |
自动检测现有嵌入，添加 --embeddings 自动标记 |
| 肮脏的工作台 | 重新索引未提交的工作会污染代码图 | 默认情况下跳过脏的存储库(ALLOW_DIRTY_REINDEX=0) |
| 冲击不稳定 | impact 在arm64 macOS上并发查询时崩溃 |
优雅地回退到基于上下文的分析 |
我们发现并解决了这些问题，在25+个repos上运行GitNexus超过3个月。
生产统计
| 度量 | 值 |
|---|---|
| 已索引的存储库 | 25+ |
| 知识图谱中的符号 | 32,000+ |
| 边缘（关系） | 73,000+ |
| 使用图形的AI代理 | 40 （OpenClaw MAS） |
| 嵌入损失事件 | 0 从v1.0开始 |
| 上游PR合并到GitNexus | 第7页，共14页 已提交 |
| 生产正常运行时间 | 3个月以上 |
AI代理如何使用它
Agent receives task: "Fix auth bug in service-api"
|
+-- 1. gni impact AuthService --> What breaks if we change it?
+-- 2. gni context AuthService --> Get callers, callees, dependencies
+-- 3. Agent writes code fix
+-- 4. auto-reindex.sh --> Graph stays current (post-commit hook)
关键洞察：当AI代理共享代码知识图时，他们会避免打断他们不知道的调用者。 gni impact 是安全重构和凌晨2点事件之间的区别。
# Example: OpenClaw 39-agent system
steps:
- agent: dev-architect
action: gni impact TargetClass --direction upstream
purpose: Blast radius before code change
- agent: dev-coder
action: gni context TargetClass
purpose: Understand dependencies before writing fix
- trigger: post-commit hook
action: gitnexus-auto-reindex.sh
purpose: Graph stays current for the next agent
特性
| 脚本 | 目的 |
|---|---|
bin/gni |
生产CLI包装器——可读输出、密码stderr捕获、影响回退 |
bin/gitnexus-doctor.sh |
诊断版本漂移、索引运行状况、MCP配置、嵌入状态 |
bin/gitnexus-smoke-test.sh |
端到端健康检查（分析→ 状态→ list → 上下文→ 密码→ 影响） |
bin/gitnexus-safe-impact.sh |
基于上下文的故障自动回退影响分析 |
bin/gitnexus-auto-reindex.sh |
智能单仓库重新索引（过时检测+嵌入保护+脏跳过） |
bin/gitnexus-reindex.sh |
批量重新索引最近更改的存储库（对cron友好） |
bin/gitnexus-reindex-all.sh |
用安全默认值重新索引所有已注册的存储库 |
bin/gitnexus-install-hooks.sh |
安装git钩子，以便在提交/合并时自动重新索引 |
安全默认值
| 功能 | 默认 | 覆盖 |
|---|---|---|
| 嵌入保护 | 自动检测和保存 | 始终打开 |
| 脏工作台跳过 | 跳过脏仓库 | ALLOW_DIRTY_REINDEX=1 |
| 影响回退 | 失败时基于上下文的JSON | 始终打开 |
| 版本固定 | $GITNEXUS_BIN 看看谁。 |
环境变量
| 变量 | 默认值 | 用途 |
|---|---|---|
GITNEXUS_BIN |
~/.local/bin/gitnexus-stable |
固定GitNexus CLI路径 |
REGISTRY_PATH |
~/.gitnexus/registry.json |
索引回购注册表 |
ALLOW_DIRTY_REINDEX |
0 |
允许重新索引脏的工作树 |
REPOS_DIR |
~/dev |
批量重新索引的根目录 |
LOOKBACK_HOURS |
24 |
检查更改的时间有多远 |
边缘案例和经验教训
生产使用3个月后：
| 边缘案例 | 状态 | 注释 |
|---|---|---|
| LadybugDB并发查询锁定错误 | ✅ 固定上游 产品编号425 +本地回退 | 使用 gitnexus-safe-impact.sh 对于旧版本 |
在上嵌入静默删除 --force |
✅ 自v1.0以来零事件 | 自动检测 meta.json，补充道 --embeddings |
| CLI和MCP之间的版本漂移 | ✅ 固定二进制 | 所有脚本都使用 $GITNEXUS_BIN |
| 脏的工作台图形污染 | ✅ 默认情况下跳过 | 覆盖： ALLOW_DIRTY_REINDEX=1 |
| 大型单仓库堆耗尽 | ✅ 检测并记录清楚 | 设置 NODE_OPTIONS=--max-old-space-size=8192 |
▶ Agent Context Graph (v1.3.0) — Index agents, skills, and cluster topology
除了代码符号，gitnexus稳定操作索引 代理级实体 从您的工作区——为LLM提供实时地图 谁可以在哪里做什么.
它索引了什么
| 实体 | 来源 | 描述 |
|---|---|---|
Agent |
KNOWLEDGE/AGENTS_*.md frontmatter |
具有角色、窗格ID和社会成员身份的命名代理 |
Skill |
SKILL/**/*.md |
优先级、关键字、脚本路径技能 |
KnowledgeDoc |
KNOWLEDGE/**/*.md |
参考文档和上下文文件 |
MemoryDoc |
MEMORY/**/*.md |
会话记忆和每日日志 |
ComputeNode |
workspace.json nodes[] |
集群中的物理/虚拟机 |
WorkspaceService |
workspace.json services[] |
已部署具有型号信息的代理/服务 |
渐进式披露
| 级别 | 令牌 | 用例 |
|---|---|---|
--level 1 |
~100 | LLM系统提示概述 |
--level 2 |
~400 | 默认上下文注入 |
--level 3 |
~2000 | 全边深潜 |
# Build the agent graph
gni agent-index ~/dev/MY_WORKSPACE --force
# Query at different detail levels
gni aq "deploy agent" --level 1
gni aq "cc-hayashi" --level 2
gni aq "announce skill" --level 3
# Auto-generate CLAUDE.md / AGENTS.md
gni cg . --update
有关完整指南，请参阅 docs/agent-context-graph.md.
▶ Production Deployment — Docker and cron setup
码头工人
FROM node:22-slim
RUN npm install -g gitnexus@1.4.6
RUN git clone https://github.com/ShunsukeHayashi/gitnexus-stable-ops.git /opt/stable-ops \
&& cd /opt/stable-ops && make install
RUN ln -sf $(which gitnexus) /usr/local/bin/gitnexus-stable
ENV GITNEXUS_BIN=/usr/local/bin/gitnexus-stable
ENV REPOS_DIR=/repos
COPY crontab /etc/cron.d/gitnexus
CMD ["cron", "-f"]
Cron时间表
# Smart reindex: only repos changed in last 24h
0 3 * * * REPOS_DIR=/repos bin/gitnexus-reindex.sh >> /var/log/gitnexus-reindex.log
# Weekly full reindex (Sunday 4 AM)
0 4 * * 0 bin/gitnexus-reindex-all.sh >> /var/log/gitnexus-full-reindex.log
# Health check (daily)
30 9 * * * bin/gitnexus-doctor.sh /repos/main-app main-app >> /var/log/gitnexus-doctor.log
有关完整的CI/CD指南，请参阅 docs/ci-cd-integration.md.
上游贡献
| PR | 标题 | 状态 |
|---|---|---|
| #441 | 添加 confidence 相似性阈值常数 |
✅ 已合并 |
| #451 | 跨会话保存聊天历史记录 | ✅ 已合并 |
| #453 | 添加结构化调试记录器 | ✅ 已合并 |
| #454 | detect_changes --按变更类型分类 |
✅ 已合并 |
| #425 | 使用指数回退修复LadybugDB并发锁定错误 | ✅ 已合并 |
| #455 | 对齐 QueryResult 使用LadybugDB WASM API的类型 |
🔄 回顾 |
| #458 | 在中公开每个回购资源 resources/list （修复MCP发现） |
🔄 回顾 |
| #443 | 添加 maxIterations 以防止失控的代理循环 |
🔄 回顾 |
| （+6个以上） | 错误处理、性能、CI稳定性 | 🔄 回顾 |
兼容性
| 平台 | 状态 |
|---|---|
| macOS（苹果硅） | ✅ 初级开发平台 |
| Linux（Ubuntu、Debian、Fedora） | ✅ 已测试 |
| Docker | ✅ 请参阅上面的部署部分 |
| Windows | ⚠️ 使用WSL或Git Bash |
需要：Bash 4.0+·Git 2.0+·jq 1.6+·Python 3.6+·Node.js 20+
文档
- 代理上下文图指南 --设置、命令、LLM注入、常见问题
- 运行手册 --逐步操作程序
- 建筑 --设计原则和数据流
- MCP集成 --MCP服务器配置
- CI/CD集成 --GitHub Actions、GitLab、PR中的影响分析
- 企业常见问题 --Docker、K8s、安全、SLA
贡献
欢迎投稿！看 贡献.md.
所有贡献必须包括测试，如下 常规提交，并通过 make test.
企业
在受监管的环境中大规模运行GitNexus？Miyabi G.K.提供架构审查、定制CI/CD集成和优先问题解决。
📧 shunsuke.hayashi@miyabi-ai.jp 🐦 @The_AGI_WAY
许可证
这个工具包：麻省理工学院 --仅涵盖包装器脚本、工具和文档。
GitNexus 其本身已获得许可 PolyForm非商业版1.0.0。此工具包调用GitNexus CLI，但不包含或重新分发任何GitNexus源代码。对于商业用途，请独立验证GitNexus许可。
建造于 Miyabi G.K。
🐦 @The_AGI_WAY · 📧 shunsuke.hayashi@miyabi-ai.jp
积极贡献者 GitNexus --提交了14份PR，合并了7份。
