拓冰网站定制 
1. 接手陌生代码库时explore-project Skill 到底解决了什么刚接手一个陌生代码库最耗时的往往不是写代码而是搞清楚「这个项目是怎么跑起来的」。README 可能停留在两年前目录结构靠猜模块之间的调用关系只能靠全局搜索一点点拼。我试过最笨的办法打开入口文件顺着 import 一层层往下翻翻到第三层就迷路了。explore-project 是一个 Claude Code Skill本质是一份结构化的指令文档指导 AI 自主完成「探索项目 → 分析架构 → 生成可视化文档」的全流程。它不是 CLI 工具不是编辑器插件也不需要额外安装运行时依赖。它是一段让 AI 知道「怎么做项目探索」的知识放在~/.claude/skills/目录下就能生效。它适合谁三类人最受益一是刚入职、需要快速了解新项目全貌的开发者二是经常跨项目协作、需要标准化架构文档的团队三是做需求评审前想先看清模块边界和数据流的工程师。如果你只在一个项目里深耕多年或者项目已有持续维护的完善架构文档那它的边际价值就不大。它不解决什么也要说清楚不写业务代码、不做重构建议、不替代设计文档。它产出的是「现状分析」不是「应该怎么改」。它也不跑项目、不调试运行时问题对 monorepo 的全量分析也不适合单包粒度才是它的舒适区。和同类工具比Dependency Cruiser 靠静态分析 import精确但只有依赖关系没有业务语义Madge 出图快但图一大就不可读也缺少上下文说明手动画图最准确但费时费力还容易过时。explore-project 的差异在于AI 主动探索 出图零配置、理解业务语义、中文输出代价是依赖 Claude Code 且输出非确定性。2. TaoToken 前置准备给 Claude Code 接上稳定的模型通道在跑 explore-project 之前得先让 Claude Code 有一个能用的模型后端。Claude Code 默认走 Anthropic 官方通道但很多开发者的网络环境或团队合规要求下需要一个可配置的接入点。TaoToken 提供的就是这样一个模型调用入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。这里要强调一点TaoToken 是合规的模型调用服务不是所谓的中转或代理它的定位是给开发者提供统一的 API 接入能力。你需要在控制台创建一个 API Key然后把它配置到 Claude Code 的环境变量或配置文件里。具体操作路径先访问 https://taotoken.net/api-keys 生成一个 Key注意 Key 只在创建时完整显示一次复制后妥善保存。然后打开 Claude Code 的配置文件通常在~/.claude/settings.json或项目级的.claude/settings.json。如果你用的是 Claude Code 的 Anthropic 兼容模式需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量。对于长期做编码和 Agent 任务的开发者可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对高频编码场景做了额度优化。如果你只是想先验证模型对话是否通可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这个对话入口快速测试。配置完成后在终端里执行claude进入 Claude Code输入一句简单的话确认模型有响应。如果返回 401说明 Key 没配对如果提示 local proxy failed说明 Base URL 写错了或者网络不通。这两个错误后面会专门讲排查方法。3. 可复制配置Skill 目录结构与 settings 片段explore-project 的目录结构设计得很清晰每个文件就是一个扩展点改文件内容就等于改 AI 行为无需编译、无需部署。标准结构如下~/.claude/skills/explore-project/ ├── SKILL.md # 工作流主控改流程在这 ├── agents/ │ ├── phase1-overview.md # Phase 1 子代理 prompt改探索策略 │ ├── phase1-deps.md # 模块依赖分析 prompt │ ├── phase1-entry.md # 入口链路分析 prompt │ ├── phase2-module.md # Phase 2 模块深入 prompt │ ├── phase2-dataflow.md # 数据流分析 prompt │ └── phase2-sequence.md # 业务流程分析 prompt └── templates/ └── output-template.md # 输出文档模板改最终产出格式SKILL.md 是主控文件它定义了 Phase 0 到 Phase 3 的执行顺序。Phase 0 做预扫描读package.json、go.mod、Cargo.toml判断技术栈定位入口文件和路由配置。Phase 1 派发 3 个 Explore 子代理并行工作分别负责全局概览、模块依赖、入口流程。Phase 2 在你选定模块后再派 3 个子代理深入分析内部结构、数据流、业务流程。Phase 3 汇总所有子代理返回的 JSON组装 Markdown调用 mermaid 工具渲染图表最后写入docs/architecture/目录。接下来是 Claude Code 的 settings 配置片段。如果你用 TaoToken 作为模型通道~/.claude/settings.json应该包含{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Glob, Grep, Bash(ls:*), Bash(cat:*), Bash(find:*) ] } }注意ANTHROPIC_MODEL要填你实际可用的模型 ID不同账号权限可能不同可以在控制台的模型列表里确认。如果你用的是 Codex 风格的auth.json配置形态类似把 Base URL 和 Key 填到对应字段即可。Cline MCP 场景下则是在 MCP 配置里指定baseUrl和apiKeyModel ID 同样要写全。Skill 的触发方式很灵活在 Claude Code 会话里输入/explore-project或者直接说「探索一下这个项目」「帮我了解这个项目的架构」都能触发。也可以带路径参数比如/explore-project D:\Projects\ent-micro直接指定要分析的项目目录。4. 验证请求用 Mermaid 与 codegraph 生成结构图并检查覆盖配置好之后进入一个真实项目目录执行cd /path/to/your-project然后在 Claude Code 里触发 Skill。Phase 1 大约 60 秒完成你会看到它自动产出的五类内容项目架构图、模块依赖图、目录结构概览、技术栈总结、入口流程图。Mermaid 图表的渲染依赖 claude-mermaid 插件。安装后Skill 会把生成的 Mermaid 代码传给 Mermaid MCP ServerServer 渲染成 SVG 并在浏览器里热重载。你可以在浏览器里实时看到图表变化如果布局不理想可以手动调整 Mermaid 代码里的方向参数比如把flowchart TD改成flowchart LR或者调整 subgraph 的分组。codegraph 是可选的加速项。如果项目已经建了 codegraph 索引Skill 会优先走图查询速度快且准确度高没有索引时fallback 到文件系统分析用 Glob、Grep、Read 这些工具探索。建索引的命令通常在 codegraph 的文档里核心是让它扫描项目源码生成调用图。验证探索路径是否覆盖关键模块可以这样做先看 Phase 1 产出的模块依赖图数一数图里出现了多少个一级模块再和src/目录下的一级子目录对比。如果某个目录没出现在图里说明子代理可能漏掉了这时候可以在 SKILL.md 的 Phase 1 步骤里补充该目录的探索指令或者手动触发一次针对该目录的 Phase 2。Phase 2 的触发需要你做一次选择。Phase 1 完成后主代理会列出可深入的模块你选一个它再派 3 个子代理并行分析。产出包括模块内部结构图、数据流图、业务流程图、接口清单、状态管理图。数据流图用flowchart LR展示从 API 到处理层到状态层再到 UI 的全链路业务流程图用sequenceDiagram还原用户操作的完整路径。实测下来一个 Vue 2 Express SSR 的项目Phase 1 约 50 秒登录模块的流程图能精准还原业务逻辑一个 Vue 2.7 Pinia Qiankun 的微前端项目Phase 1 约 60 秒AI 问企模块的 SSE 工作流能完整呈现。输出文件在docs/architecture/下包含README.md主文档、images/*.svg图表文件、generated-at.txt时间戳。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth第一个高频错误是 401 Unauthorized。报错长这样API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因通常是ANTHROPIC_API_KEY没设置、设置成了旧 Key、或者 Key 前后有空格。排查步骤在终端执行echo $ANTHROPIC_API_KEY确认值存在且无多余字符检查~/.claude/settings.json里的env.ANTHROPIC_API_KEY是否和 TaoToken 控制台生成的一致如果刚轮换过 Key记得重启 Claude Code 会话环境变量不会热加载。第二个错误是 local proxy failed。报错形态Error: local proxy failed to connect: ECONNREFUSED 127.0.0.1:xxxx这通常说明ANTHROPIC_BASE_URL写成了本地地址或者写错了域名。正确值应该是https://taotoken.net/api注意结尾不要多加/v1或斜杠。如果你之前配过其他工具的本地代理检查是否有残留的HTTP_PROXY环境变量干扰用env | grep -i proxy看一眼有的话临时 unset 掉再试。第三个错误是 reading choices 相关。报错类似TypeError: Cannot read properties of undefined (reading choices)这个多半出现在用 OpenAI 兼容格式调用时响应体结构和预期不符。检查你用的模型 ID 是否在 TaoToken 控制台的可用列表里有些模型只支持 Anthropic 原生格式不支持 OpenAI 的choices字段。换一个模型 ID 试试或者在请求层确认走的是 Anthropic 的 messages 接口而不是 chat completions。第四个是 OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式可能会看到OAuth error: invalid_grant / token exchange failed解决办法是在 settings 里明确禁用 OAuth或者用claude --api-key启动参数强制走 Key 模式。如果同时配了 OAuth 和 API Key优先级可能冲突清掉 OAuth 的缓存文件通常在~/.claude/下的 token 缓存再重启。还有一个容易忽略的点Skill 文件权限。如果~/.claude/skills/explore-project/SKILL.md没有读权限Claude Code 会静默跳过这个 Skill表现为输入/explore-project没反应。用ls -la确认权限是 644 或更高。6. 语义一致 CTA把 explore-project 用起来explore-project 的价值在于把「读代码猜架构」变成「AI 主动探索出图」。它的边界也很清楚产出的是现状分析不是设计文档适合单包粒度不适合 monorepo 全量输出非确定性不适合塞进 CI 自动管道。建议的用法是新人入职跑一次生成基础文档需求评审前对涉及模块跑 Phase 2文档定期重新生成并用 commit hash 判断是否过时。要让这套流程跑起来模型通道得先通。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 生成接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有完整的 Base URL 和参数说明。想先验证模型对话是否正常用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速测一句。长期做编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 额度策略更适合高频场景。最后给一个实用技巧Skill 产出的 Mermaid 图如果节点太多导致拥挤不要硬调布局而是在 agent prompt 里加一句「只展示一级模块和跨模块调用内部细节折叠到 Phase 2」。这样 Phase 1 的图保持可读细节留给 Phase 2 按需展开。图表是起点不是终点人工补充业务背景后才是能传给下一任的架构文档。 explore-project Skill 设计思路：用 Mermaid 与 codegraph 快速上手新项目
1. 接手陌生代码库时explore-project Skill 到底解决了什么刚接手一个陌生代码库最耗时的往往不是写代码而是搞清楚「这个项目是怎么跑起来的」。README 可能停留在两年前目录结构靠猜模块之间的调用关系只能靠全局搜索一点点拼。我试过最笨的办法打开入口文件顺着 import 一层层往下翻翻到第三层就迷路了。explore-project 是一个 Claude Code Skill本质是一份结构化的指令文档指导 AI 自主完成「探索项目 → 分析架构 → 生成可视化文档」的全流程。它不是 CLI 工具不是编辑器插件也不需要额外安装运行时依赖。它是一段让 AI 知道「怎么做项目探索」的知识放在~/.claude/skills/目录下就能生效。它适合谁三类人最受益一是刚入职、需要快速了解新项目全貌的开发者二是经常跨项目协作、需要标准化架构文档的团队三是做需求评审前想先看清模块边界和数据流的工程师。如果你只在一个项目里深耕多年或者项目已有持续维护的完善架构文档那它的边际价值就不大。它不解决什么也要说清楚不写业务代码、不做重构建议、不替代设计文档。它产出的是「现状分析」不是「应该怎么改」。它也不跑项目、不调试运行时问题对 monorepo 的全量分析也不适合单包粒度才是它的舒适区。和同类工具比Dependency Cruiser 靠静态分析 import精确但只有依赖关系没有业务语义Madge 出图快但图一大就不可读也缺少上下文说明手动画图最准确但费时费力还容易过时。explore-project 的差异在于AI 主动探索 出图零配置、理解业务语义、中文输出代价是依赖 Claude Code 且输出非确定性。2. TaoToken 前置准备给 Claude Code 接上稳定的模型通道在跑 explore-project 之前得先让 Claude Code 有一个能用的模型后端。Claude Code 默认走 Anthropic 官方通道但很多开发者的网络环境或团队合规要求下需要一个可配置的接入点。TaoToken 提供的就是这样一个模型调用入口官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。这里要强调一点TaoToken 是合规的模型调用服务不是所谓的中转或代理它的定位是给开发者提供统一的 API 接入能力。你需要在控制台创建一个 API Key然后把它配置到 Claude Code 的环境变量或配置文件里。具体操作路径先访问 https://taotoken.net/api-keys 生成一个 Key注意 Key 只在创建时完整显示一次复制后妥善保存。然后打开 Claude Code 的配置文件通常在~/.claude/settings.json或项目级的.claude/settings.json。如果你用的是 Claude Code 的 Anthropic 兼容模式需要设置ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个环境变量。对于长期做编码和 Agent 任务的开发者可以考虑 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 它针对高频编码场景做了额度优化。如果你只是想先验证模型对话是否通可以用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 这个对话入口快速测试。配置完成后在终端里执行claude进入 Claude Code输入一句简单的话确认模型有响应。如果返回 401说明 Key 没配对如果提示 local proxy failed说明 Base URL 写错了或者网络不通。这两个错误后面会专门讲排查方法。3. 可复制配置Skill 目录结构与 settings 片段explore-project 的目录结构设计得很清晰每个文件就是一个扩展点改文件内容就等于改 AI 行为无需编译、无需部署。标准结构如下~/.claude/skills/explore-project/ ├── SKILL.md # 工作流主控改流程在这 ├── agents/ │ ├── phase1-overview.md # Phase 1 子代理 prompt改探索策略 │ ├── phase1-deps.md # 模块依赖分析 prompt │ ├── phase1-entry.md # 入口链路分析 prompt │ ├── phase2-module.md # Phase 2 模块深入 prompt │ ├── phase2-dataflow.md # 数据流分析 prompt │ └── phase2-sequence.md # 业务流程分析 prompt └── templates/ └── output-template.md # 输出文档模板改最终产出格式SKILL.md 是主控文件它定义了 Phase 0 到 Phase 3 的执行顺序。Phase 0 做预扫描读package.json、go.mod、Cargo.toml判断技术栈定位入口文件和路由配置。Phase 1 派发 3 个 Explore 子代理并行工作分别负责全局概览、模块依赖、入口流程。Phase 2 在你选定模块后再派 3 个子代理深入分析内部结构、数据流、业务流程。Phase 3 汇总所有子代理返回的 JSON组装 Markdown调用 mermaid 工具渲染图表最后写入docs/architecture/目录。接下来是 Claude Code 的 settings 配置片段。如果你用 TaoToken 作为模型通道~/.claude/settings.json应该包含{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Glob, Grep, Bash(ls:*), Bash(cat:*), Bash(find:*) ] } }注意ANTHROPIC_MODEL要填你实际可用的模型 ID不同账号权限可能不同可以在控制台的模型列表里确认。如果你用的是 Codex 风格的auth.json配置形态类似把 Base URL 和 Key 填到对应字段即可。Cline MCP 场景下则是在 MCP 配置里指定baseUrl和apiKeyModel ID 同样要写全。Skill 的触发方式很灵活在 Claude Code 会话里输入/explore-project或者直接说「探索一下这个项目」「帮我了解这个项目的架构」都能触发。也可以带路径参数比如/explore-project D:\Projects\ent-micro直接指定要分析的项目目录。4. 验证请求用 Mermaid 与 codegraph 生成结构图并检查覆盖配置好之后进入一个真实项目目录执行cd /path/to/your-project然后在 Claude Code 里触发 Skill。Phase 1 大约 60 秒完成你会看到它自动产出的五类内容项目架构图、模块依赖图、目录结构概览、技术栈总结、入口流程图。Mermaid 图表的渲染依赖 claude-mermaid 插件。安装后Skill 会把生成的 Mermaid 代码传给 Mermaid MCP ServerServer 渲染成 SVG 并在浏览器里热重载。你可以在浏览器里实时看到图表变化如果布局不理想可以手动调整 Mermaid 代码里的方向参数比如把flowchart TD改成flowchart LR或者调整 subgraph 的分组。codegraph 是可选的加速项。如果项目已经建了 codegraph 索引Skill 会优先走图查询速度快且准确度高没有索引时fallback 到文件系统分析用 Glob、Grep、Read 这些工具探索。建索引的命令通常在 codegraph 的文档里核心是让它扫描项目源码生成调用图。验证探索路径是否覆盖关键模块可以这样做先看 Phase 1 产出的模块依赖图数一数图里出现了多少个一级模块再和src/目录下的一级子目录对比。如果某个目录没出现在图里说明子代理可能漏掉了这时候可以在 SKILL.md 的 Phase 1 步骤里补充该目录的探索指令或者手动触发一次针对该目录的 Phase 2。Phase 2 的触发需要你做一次选择。Phase 1 完成后主代理会列出可深入的模块你选一个它再派 3 个子代理并行分析。产出包括模块内部结构图、数据流图、业务流程图、接口清单、状态管理图。数据流图用flowchart LR展示从 API 到处理层到状态层再到 UI 的全链路业务流程图用sequenceDiagram还原用户操作的完整路径。实测下来一个 Vue 2 Express SSR 的项目Phase 1 约 50 秒登录模块的流程图能精准还原业务逻辑一个 Vue 2.7 Pinia Qiankun 的微前端项目Phase 1 约 60 秒AI 问企模块的 SSE 工作流能完整呈现。输出文件在docs/architecture/下包含README.md主文档、images/*.svg图表文件、generated-at.txt时间戳。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth第一个高频错误是 401 Unauthorized。报错长这样API Error: 401 {error:{type:authentication_error,message:invalid x-api-key}}原因通常是ANTHROPIC_API_KEY没设置、设置成了旧 Key、或者 Key 前后有空格。排查步骤在终端执行echo $ANTHROPIC_API_KEY确认值存在且无多余字符检查~/.claude/settings.json里的env.ANTHROPIC_API_KEY是否和 TaoToken 控制台生成的一致如果刚轮换过 Key记得重启 Claude Code 会话环境变量不会热加载。第二个错误是 local proxy failed。报错形态Error: local proxy failed to connect: ECONNREFUSED 127.0.0.1:xxxx这通常说明ANTHROPIC_BASE_URL写成了本地地址或者写错了域名。正确值应该是https://taotoken.net/api注意结尾不要多加/v1或斜杠。如果你之前配过其他工具的本地代理检查是否有残留的HTTP_PROXY环境变量干扰用env | grep -i proxy看一眼有的话临时 unset 掉再试。第三个错误是 reading choices 相关。报错类似TypeError: Cannot read properties of undefined (reading choices)这个多半出现在用 OpenAI 兼容格式调用时响应体结构和预期不符。检查你用的模型 ID 是否在 TaoToken 控制台的可用列表里有些模型只支持 Anthropic 原生格式不支持 OpenAI 的choices字段。换一个模型 ID 试试或者在请求层确认走的是 Anthropic 的 messages 接口而不是 chat completions。第四个是 OAuth 相关报错。Claude Code 某些版本会尝试 OAuth 登录流程如果你用的是 API Key 模式可能会看到OAuth error: invalid_grant / token exchange failed解决办法是在 settings 里明确禁用 OAuth或者用claude --api-key启动参数强制走 Key 模式。如果同时配了 OAuth 和 API Key优先级可能冲突清掉 OAuth 的缓存文件通常在~/.claude/下的 token 缓存再重启。还有一个容易忽略的点Skill 文件权限。如果~/.claude/skills/explore-project/SKILL.md没有读权限Claude Code 会静默跳过这个 Skill表现为输入/explore-project没反应。用ls -la确认权限是 644 或更高。6. 语义一致 CTA把 explore-project 用起来explore-project 的价值在于把「读代码猜架构」变成「AI 主动探索出图」。它的边界也很清楚产出的是现状分析不是设计文档适合单包粒度不适合 monorepo 全量输出非确定性不适合塞进 CI 自动管道。建议的用法是新人入职跑一次生成基础文档需求评审前对涉及模块跑 Phase 2文档定期重新生成并用 commit hash 判断是否过时。要让这套流程跑起来模型通道得先通。API Key 在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 生成接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 有完整的 Base URL 和参数说明。想先验证模型对话是否正常用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 快速测一句。长期做编码和 Agent 任务的话Coding Plan 在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 额度策略更适合高频场景。最后给一个实用技巧Skill 产出的 Mermaid 图如果节点太多导致拥挤不要硬调布局而是在 agent prompt 里加一句「只展示一级模块和跨模块调用内部细节折叠到 Phase 2」。这样 Phase 1 的图保持可读细节留给 Phase 2 按需展开。图表是起点不是终点人工补充业务背景后才是能传给下一任的架构文档。