接入内网仓库后任务一开始就断，先查权限还是先查索引，取决于失败停在哪一步。任务在初始化、连接或身份校验阶段就中断，通常应先查权限与凭据；任务能启动、能读到仓库结构，但检索结果为空或明显缺文件，才轮到索引。报错含糊时不要凭直觉改配置，先用任务日志把失败收敛到一个具体环节，再用与 CodeBuddy NPC 无关的独立命令，分别验证连通性、凭据范围和索引状态。

判断顺序建议是：日志定位阶段 → 独立命令验证连通性 → 核对凭据覆盖范围 → 确认索引完成度。失败发生在初始化或鉴权阶段时，索引几乎不可能是原因，先改索引只会增加噪声；失败发生在读取或检索阶段、且能列出仓库文件时，才值得看索引。所有验证动作都建议用只读方式，改配置前记录原值，重新触发索引尽量避开使用高峰。

在任务日志里定位失败发生在哪一步

模糊报错大多来自被封装的底层异常，页面上只剩一句“接入失败”或“任务异常”。第一步不是猜原因，而是把日志按阶段切开。通用接入流程通常有这些可观察标记：建立连接、身份校验、拉取仓库元数据（分支或 commit）、列举文件、写入或查询索引、返回结果。不同产品的措辞不一样，但阶段顺序基本一致。

可以直接对导出的日志做粗筛，关键词要按实际日志内容替换，不要照抄：

# task.log 换成从页面导出的任务日志文件
# 关键词只是粗筛，用于快速看到阶段切换的位置
grep -nEi 'connect|auth|token|credential|clone|fetch|checkout|index|embed|search|retriev' task.log | head -80

看结果时关注两件事。其一，日志有没有出现仓库地址、分支名、commit 号、文件列表这类“已经读到仓库内容”的标记；出现了，说明初始化阶段基本通过，问题更可能在索引或检索范围。其二，最后一条成功标记之后紧跟的第一条错误，才是要处理的错误；后面成串的报错往往只是连锁失败。

判断初始化失败还是读取失败，可以看三个信号：没有出现任何仓库路径或分支信息，属于初始化失败；出现了分支或文件列表，但没有检索结果，属于读取或索引阶段失败；日志停在身份校验那一行、后面没有下游调用，属于凭据类失败。适用场景是任何接入内网仓库后立刻中断的任务；验证方式是改完配置后重跑同一任务，看日志是否推进到下一阶段。边界在于：日志级别若被调低，阶段标记可能缺失，此时需要临时提高日志详细程度再复现一次，而不是靠猜。

用独立命令单独验证仓库连通性

把网络问题从权限问题里摘出来，最省事的办法是在与 CodeBuddy NPC 同一网络位置的机器上，用 Git 本身做只读探测。下面是最小骨架，尖括号内容替换为实际仓库地址：

# 只读探测：不写入、不克隆，只问远端有没有这个引用
GIT_TERMINAL_PROMPT=0 git ls-remote <仓库地址> HEAD

# 看本地对该地址生效的凭据与 URL 改写配置来自哪里
git config `--show-origin` `--get-regexp` 'credential|url\.'

预期输出是打印一行 commit 哈希和 HEAD，说明网络可达、地址正确、当前凭据能读这个仓库，问题应转向索引或应用侧配置。失败输出要分类看：出现 Could not resolve host 或连接超时，属于 DNS、路由或网络策略问题，先找网络侧确认；出现 Authentication failed、could not read Username、Permission denied 一类提示，属于凭据或权限问题；出现 Repository not found 或 403、404，通常是无权限或地址指向了不可见的仓库，部分实现会把无权限伪装成 404，需要向仓库管理员确认可见范围。

GIT_TERMINAL_PROMPT=0 的作用是避免命令卡在交互式输入账号密码上，排查时建议保留。这个命令骨架的边界是：它验证的是“这台机器 + 这份凭据”能否读仓库，不能证明 CodeBuddy NPC 内部使用的凭据相同；所以命令通过而任务仍失败时，要回到第 3 步核对应用侧配置的凭据来源。

核对凭据与令牌的可用范围

凭据能连上仓库，不等于能覆盖目标仓库。企业内部常见情况是：令牌绑定在个人账号上，个人对 A 仓库有权限、对目标仓库没有；或者令牌是项目级、组织级，但授权范围只给了部分仓库；也可能是令牌已过期，只是错误被上层吞掉。核对方法有三步：先用同一份凭据对目标仓库单独做一次只读探测（同上一节的命令）；再用另一份已知可用的凭据做对照，确认是凭据问题而非仓库问题；最后在凭据管理页面查看作用范围、有效期和最近使用时间，具体配置项名称以实际界面为准。

典型表现可以这样区分：令牌过期或吊销时，几乎所有仓库都失败，报错稳定且与仓库无关；权限范围不足时，能列出部分仓库、对目标仓库单独失败，报错里常带 401、403、404 或 access denied；凭据本身可用但被错误地配置到了别的地址上，表现为命令成功、应用失败。风险边界是：不要在排查时临时使用高权限账号长期运行任务，验证完应回退到最小权限；改动凭据配置前记录原值，避免把原本可用的任务一起弄坏。

确认仓库索引是否建立完成

如果日志显示已经读到分支和文件列表，独立命令也能正常访问仓库，那么空结果更可能是索引没建好，而不是权限问题。索引状态一般在仓库接入的管理页面、索引任务列表或知识库配置中查看，位置和命名以实际界面为准；需要关注三件事：索引任务是排队、运行中还是已完成；索引覆盖的 commit 是否与仓库当前 HEAD 一致；被排除的文件范围（忽略规则、大文件、二进制文件）是否把目标目录排除掉了。

索引未完成时的任务表现比较有辨识度：任务本身能跑完、不报权限错误，但检索命中为空、只命中部分文件，或者结果明显滞后于最近一次提交。重新触发索引后，观察点按顺序是：任务是否成功入队、运行阶段有无报错、完成状态是否覆盖到最新 commit、文件计数是否与预期量级相符。边界在于：重新触发索引会消耗计算资源，建议在低峰期做；在凭据尚未确认可用之前重建索引，通常仍会失败，只会多出一条无效记录，所以这一步应排在连通性和凭据之后。

整理一张故障判断对照表

下次遇到同类失败，可以直接按下面这张表对号入座。表里的现象是通用观察点，具体报错文案以实际产品和仓库实现为准。

使用这张表的顺序建议是：先看任务结果判断失败发生在初始化还是读取，再对照日志确认阶段，最后用独立命令做交叉验证；三者一致时基本可以定性，不一致时优先相信独立命令和日志，不要只凭页面提示下结论。