内容
# DevPath 智能职业规划助手
DevPath 智能职业规划助手是一款专为初级软件开发者设计的 AI 职业规划助手。它分析职位发布、候选人简介、项目作品集和可选的简历背景，然后生成确定的匹配分数、基于证据的差距、准备计划、申请草稿、面试准备和可选的 Gemini 辅助叙事洞察。
该项目是为 Kaggle 的 **AI Agents: Intensive Vibe Coding Capstone Project with Google** 构建的，适用于 **Concierge Agents** 赛道：它为一名开发者提供实用的、个性化的职业策略，同时保持评分的可解释性和个人数据处理的谨慎。
公开仓库：https://github.com/kranel-argonavt/devpath-agent
演示视频：https://youtu.be/kvx_5-GBpkg
## 问题
初级开发者通常难以将广泛的职位发布转化为具体的准备计划。要求与期望技能、资历信号、语言期望和模糊的职责混杂在一起。候选人证据也分散在个人资料笔记、简历文本和作品集项目中。
DevPath 智能职业规划助手将这种比较转化为结构化、可解释的工作流程，帮助初级开发者决定要突出什么、改进什么以及在申请前如何准备。
## 当前架构
```mermaid
flowchart TD
User["用户 / 评委"]
Streamlit["Streamlit UI"]
Inputs["职位发布 + 候选人简介 + 作品集 + 可选简历"]
Settings["AI 智能体演示设置"]
Workflow["devpath.agent_workflow"]
subgraph 模式["工作流程模式"]
ToolCalling["Capstone 智能体模式：Gemini/ADK 工具调用 + MCP 跟踪"]
FullAgent["ADK 风格的确定性多智能体工作流程"]
Standard["基准确定性工作流程"]
end
subgraph 跟踪智能体["可见智能体阶段 / 跟踪标签"]
Privacy["隐私保护"]
Job["职位分析器"]
Portfolio["作品集证据"]
Matcher["个人资料匹配器"]
CareerBuilder["职业报告构建器"]
Gap["差距规划器"]
Writer["申请撰写器"]
Interview["面试辅导"]
GeminiNarrative["Gemini 叙事"]
end
subgraph 工具路由["MCP 首选路由，用于确定性工具"]
DeterministicCalls["掩码/分析/作品集/评分/报告工具调用"]
MCPRuntime["MCP 运行时"]
MCPRegistry["本地 MCP 风格注册表"]
Direct["直接确定性服务"]
ToolOutputs["验证的确定性工具输出"]
end
subgraph Gemini["可选 Gemini API 步骤"]
ExtractJob["使用 Gemini 提取职位要求"]
ExtractCandidate["使用 Gemini 提取候选人上下文"]
NarrativeWriters["差距/行动/申请/面试撰写器"]
end
subgraph 验证["确定性验证边界"]
JobValidator["验证职位要求"]
CandidateValidator["验证候选人上下文"]
ExtractedContext["验证的提取上下文"]
end
subgraph 真相源["确定性真相源"]
Score["加权匹配分数"]
Evidence["按技能划分的证据"]
Gaps["规范差距"]
ReportBuilder["构建职业报告"]
end
Enhanced["LLM 叙事增强，仅限"]
Report["职业策略报告"]
Runtime["智能体工作流程跟踪 + AI 工具调用跟踪 + 工作流程运行时"]
Export["隐私掩码 Markdown 导出"]
User --> Streamlit --> Inputs --> Settings --> Workflow
Workflow --> ToolCalling
Workflow --> FullAgent
Workflow --> Standard
ToolCalling --> Privacy --> Job --> Portfolio --> Matcher --> CareerBuilder --> Gap --> Writer --> Interview --> GeminiNarrative
ToolCalling --> DeterministicCalls
DeterministicCalls --> MCPRuntime
MCPRuntime -->|success| ToolOutputs
MCPRuntime -->|fallback| MCPRegistry
MCPRegistry -->|success| ToolOutputs
MCPRegistry -->|fallback| Direct
Direct --> ToolOutputs
ToolOutputs --> Score
ToolOutputs --> Evidence
ToolOutputs --> Gaps
ToolOutputs --> ReportBuilder
ToolCalling --> ExtractJob --> JobValidator --> ExtractedContext
ToolCalling --> ExtractCandidate --> CandidateValidator --> ExtractedContext
ExtractedContext --> NarrativeWriters
ReportBuilder --> NarrativeWriters
NarrativeWriters --> Enhanced
FullAgent --> ReportBuilder
Standard --> ReportBuilder
Score --> ReportBuilder
Evidence --> ReportBuilder
Gaps --> ReportBuilder
ReportBuilder --> Report
Enhanced --> Report
ToolCalling --> Runtime
FullAgent --> Runtime
Runtime --> Report
Report --> Streamlit
Report --> Export
```
确定性报告仍然是真相源。 Gemini 可以提取结构化上下文并丰富叙事部分，当使用本地 API 密钥配置时，但确定性验证器和评分工具保留规范的分数、证据和差距字段。
## 当前状态
当前状态：**智能体运行时升级 - capstone 级工具调用演示模式。**
已实现：
- Streamlit 模拟工作流程 UI
- 可编辑的职位发布、候选人简介、作品集来源、简历上下文和分析设置
- 确定性基于证据的匹配评分
- 类别评分分解和类别原因
- 强大的、部分的和缺失的技能分类
- 按技能划分的证据和作品集证据地图
- 优先的技能差距和建议
- 准备计划、申请草稿和面试准备
- 丰富的隐私掩码 Markdown 导出
- 可选的 Gemini 辅助结构化提取和更丰富的叙事撰写器
- Google ADK 兼容的 `root_agent` 骨架和子智能体定义
- 确定性智能体工具
- MCP 兼容的服务器骨架和 MCP 风格的工具注册表
- 用于本地个人资料/项目加载、作品集摘要、隐私检测/掩码、导出、评分、公共 GitHub 仓库元数据和公共 README 获取的 MCP 工具
- Capstone 工具调用、ADK 风格的确定性工作流程或基准确定性工作流程的演示工作流程选择器
- 用于非 Capstone 确定性路由的后端比较选择器
- 用于选定的手动工具调用的实验性 MCP stdio 运行时适配器
- 选定的确定性工具的本地 MCP 运行时烟雾测试成功
- 选定的确定性工具的实验性 ADK-MCP 桥接包装器
- 具有安全直接回落的实验性 ADK-MCP 运行时工具后端
- UI 中的工作流程运行时元数据和导出的 Markdown
- GitHub 公共仓库元数据导入为作品集来源
- GitHub 公共仓库元数据映射到作品集证据中
- 用于显式 MCP/API 使用的受控公共 GitHub README 获取帮助程序
- 具有命名阶段和跟踪元数据的完整 ADK 风格确定性智能体工作流程
- Streamlit 中的 `演示工作流程` 选择器，用于 Gemini/ADK 工具调用、完整智能体工作流程或标准工作流程模式
- Streamlit 和导出的 Markdown 中的智能体工作流程跟踪
- Streamlit 和导出的 Markdown 中的 AI 工具调用跟踪
- Capstone 就绪的演示默认值：Gemini/ADK 工具调用、Gemini 辅助摘要（安全回落）、确定性评分、本地样本项目
- 本地 Gemini、ADK 和 MCP 烟雾测试脚本
- 用于确定性帮助程序、工作流程、工具和烟雾脚本的 Pytest 套件
尚未实现：
- Streamlit 中的实时 ADK 运行时路由
- 生产环境 ADK 智能体引擎部署
- GitHub 源代码证据映射
- GitHub 私有仓库访问
- 超出受控公共元数据和显式 README 获取的源代码仓库检查
- 生产环境部署
## 智能体和工具层
- `devpath/agent.py` 导出 ADK 兼容的 `root_agent` 骨架。
- `devpath/sub_agents/` 包含用于职位分析、作品集证据、匹配、差距规划、申请撰写、面试辅导和隐私审查的计划专业智能体。
- `devpath/agent_tools.py` 暴露用于未来智能体编排的确定性工具包装器。
- `mcp_server/server.py` 暴露一个导入安全的 MCP 服务器骨架或备用元数据。
- `mcp_server/tools/` 包含围绕确定性项目逻辑、本地样本读取器、隐私工具、导出和受控公共 GitHub 查找的 MCP 风格包装器。
- `devpath/tool_router.py` 允许工作流程使用直接确定性服务、本地 MCP 风格注册表或实验性 ADK-MCP 运行时包装器。
Streamlit 现在包含一个名为 `Gemini/ADK 工具调用智能体` 的 Capstone 演示模式。它通过可见的工具调用运行职业工作流程，首先请求 MCP 运行时，然后回落到本地 MCP 风格注册表，最后回落到直接确定性服务。Streamlit 仍然 **不** 依赖于部署的 ADK 运行时；该路由故意是本地的、可测试的和安全的，适用于评判。
## Gemini/ADK 工具调用模式
默认演示工作流程是 `Gemini/ADK 工具调用智能体`。它记录一个 `AI 工具调用跟踪`，用于：
- `mask_personal_data`
- `extract_job_requirements_with_gemini`
- `validate_job_requirements`
- `analyze_job_posting`
- `build_portfolio_summary`
- `extract_candidate_context_with_gemini`
- `validate_candidate_context`
- `calculate_match_score`
- `build_career_report`
- `generate_gap_narrative`
- `generate_action_plan_narrative`
- `generate_application_drafts`
- `generate_interview_prep`
- `generate_gemini_career_insights`
每个跟踪条目显示工具名称、智能体名称、使用的后端、状态、输入摘要、输出摘要、回落状态和警告。首选后端是 MCP 运行时。如果 MCP 运行时不可用，则工作流程回落到进程内的 MCP 风格注册表，然后回落到直接确定性 Python 服务。
Gemini 在运行时是可选的，默认情况下用于有界结构化提取和叙事写作。但是，如果没有配置本地 API 密钥或 Gemini 失败，则 Gemini 工具调用被标记为跳过或回落。
## 完整智能体工作流程编排
该项目在 `devpath/full_agent_workflow.py` 中包含一个完整的 ADK 风格确定性工作流程 facade。Streamlit 可以通过 `演示工作流程` 选择器运行标准确定性工作流程或完整智能体工作流程。完整工作流程通过命名阶段运行职业策略过程：
- `privacy_guard`
- `job_analyzer`
- `portfolio_evidence`
- `profile_matcher`
- `gap_planner`
- `application_writer`
- `interview_coach`
这些阶段编排现有的确定性工具和服务，生成智能体跟踪，并将工作流程元数据附加到报告中。UI 显示 `智能体工作流程跟踪`，并且当存在时，Markdown 导出包含相同的跟踪。
## Capstone 适配性
推荐赛道：**Concierge Agents**。
演示的课程概念：
- ADK 风格的多智能体工作流程，具有根智能体、分阶段的子智能体责任和可见的工具调用模式
- MCP 服务器骨架、MCP 风格的工具、本地注册表、MCP 运行时适配器和具有回落的 MCP 首选工具调用路由
- 安全和隐私功能，包括掩码和无秘密导出规则
- 智能体工具和用于评分、隐私、报告、GitHub 证据和导出的确定性工具合同
- 通过需求、Dockerfile、烟雾脚本和测试实现可部署性和可复制的设置
- 可选的 Gemini 结构化提取和叙事撰写器，永远不会修改确定性分数
## 演示流程
默认离线路径：
1. 点击 `加载样本 React 前端场景`。
2. 保持默认的 `Capstone 智能体模式：Gemini/ADK 工具调用 + MCP 跟踪` 和 `本地样本项目`。
3. 点击 `生成职业策略`。
4. 显示匹配分数、证据、差距、智能体工作流程跟踪、AI 工具调用跟踪、工作流程运行时和 Markdown 导出。
可选自定义输入路径：切换到 `手动 JSON 输入`，粘贴项目数组，并在不依赖 GitHub 的情况下生成报告。
可选 GitHub 路径：切换到 `GitHub 公共仓库`，输入公共用户名，获取仓库，并显示 GitHub 仓库证据。
## 设置
### 1. 克隆仓库
打开终端（命令提示符或 Git Bash）并运行以下命令克隆项目并导航到其文件夹：
```bash
# 克隆仓库
git clone https://github.com/kranel-argonavt/devpath-agent.git
# 进入项目目录
cd devpath-agent
```
### 2. 打开 PowerShell 并运行设置
现在，在项目文件夹中打开 **PowerShell** 并执行以下步骤设置应用程序：
#### A. 创建和激活虚拟环境
```powershell
# 1. 创建名为 .venv 的虚拟环境
python -m venv .venv
# 2. 暂时绕过执行策略以允许在此会话中执行脚本
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
# 3. 激活虚拟环境
.\.venv\Scripts\Activate.ps1
```
#### B. 安装依赖项
```powershell
# 升级 pip 以确保包安装顺利
python -m pip install --upgrade pip
# 安装所有必需包
pip install -r requirements.txt
```
### 3. 环境配置
在启动应用程序之前，请配置您的 API 密钥：
1. 复制模板文件：复制 `.env.example` 并重命名为 `.env`。
2. 在文本编辑器中打开 `.env` 并插入您的 Gemini API 密钥：
```env
GOOGLE_API_KEY=your_actual_api_key_here
GEMINI_MODEL=your_actual_model_here(gemini-3.1-flash-lite)
```
### 4. 运行应用程序
确保您的虚拟环境仍然激活（您应该在 PowerShell 行首看到 `(.venv)`），然后运行：
```powershell
streamlit run app.py
```
*应用程序将在您的默认浏览器中自动打开，网址为 `http://localhost:8501`。*
## 命令
运行测试：
```powershell
python -m pytest --basetemp .pytest_tmp
```
如果 `.pytest_tmp` 在 Windows 上被锁定：
```powershell
python -m pytest --basetemp .pytest_tmp_local
```
运行应用程序：
```powershell
streamlit run app.py
```
使用 Docker 运行：
```powershell
docker build -t devpath-agent .
docker run --rm -p 8501:8501 devpath-agent
```
可以在运行时传递可选的 Gemini 配置：
```powershell
docker run --rm -p 8501:8501 --env-file .env devpath-agent
```
运行本地烟雾测试：
```powershell
python scripts/check_gemini_connection.py
python scripts/check_adk_agent.py
python scripts/check_mcp_tools.py
python scripts/check_mcp_runtime.py
python scripts/check_adk_mcp_tools.py
python scripts/check_full_agent_workflow.py
python scripts/check_github_public_import.py octocat
```
## MCP 运行时烟雾测试
运行实验性本地 MCP 运行时烟雾测试：
```powershell
python scripts/check_mcp_runtime.py
```
这启动了一个本地 MCP stdio 服务器进程，并通过 MCP 运行时调用选定的确定性工具。它与默认的 Streamlit 工作流程分开。步骤 6A.1 使用 `ClientSession`、`StdioServerParameters`、`stdio_client` 和 `FastMCP.run(transport="stdio")` 验证此路径是否与已安装的 MCP SDK 配合使用。
## ADK-MCP 工具桥烟雾测试
运行选定工具的 ADK 到 MCP 桥接烟雾测试：
```powershell
python scripts/check_adk_mcp_tools.py
```
这验证了选定的 ADK 样式工具包装器是否可以通过本地 MCP stdio 运行时调用确定性工具。
默认 Streamlit 工作流程现在可以运行 `Gemini/ADK 工具调用智能体` 模式。该模式首先请求 MCP 运行时，然后在本地运行时无法使用时回落到本地 MCP 风格注册表和直接确定性服务。
UI 显示工作流程运行时元数据和 AI 工具调用跟踪，包括选定的后端、使用的后端、MCP 运行时使用情况、回落状态、选定的工具和注释。相同的元数据安全地包含在导出的 Markdown 报告中。
## GitHub 公共仓库导入
用户可以通过 GitHub 用户名导入公共仓库元数据，并将这些仓库用作作品集项目。
- 不需要 GitHub 令牌。
- 仅使用公共元数据：名称、描述、URL、语言、主题、星级、分支、更新时间戳、分支标志和存档标志。
- 不访问私有仓库。
- 不克隆仓库。
- 不下载源代码。
- 在此步骤中不下载源代码。
- README 文本可以通过受控的公共 GitHub README 帮助程序显式获取，但这不是私有仓库访问或源代码检查。
- GitHub 公共仓库元数据通过语言、主题、描述、URL 和仓库信号映射到作品集证据中。
- 星级和分支显示为公共仓库信号，而不是直接技能证明。
手动烟雾测试：
```powershell
python scripts/check_github_public_import.py octocat
```
## 可选 Gemini 设置
模拟确定性模式无需 API 密钥。要在本地测试 Gemini 辅助摘要：
```powershell
Copy-Item .env.example .env
```
然后在本地编辑 `.env`：
```text
GOOGLE_API_KEY=your_key_here
GEMINI_MODEL=gemini-3.1-flash-lite
```
不要提交 `.env`。
## 安全注意事项
- `.env` 被 Git 忽略，不得提交。
- `.env.example` 是安全的，因为它包含空占位符。
- Gemini 在运行时是可选的。对于演示，默认情况下选择 Gemini，但如果未配置本地密钥，则安全地跳过。
- 确定性分数、证据、差距和类别详细信息是真相来源。
- Gemini 可以提取和解释；确定性验证器和工具验证、评分和保留规范的分数/证据/差距字段。
- 导出的 Markdown 经过隐私掩码处理。
- `outputs/*.md` 中的生成报告被 Git 忽略。
- 不要在应用程序、提示、截图或导出报告中粘贴机密、密码、私人令牌或敏感的个人数据。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器