1. 这不是又一个“代码补全插件”，而是一套可落地的AI编码工作流系统

最近在几个技术社区里，总有人问：“现在用Copilot写代码，是不是已经够用了？”——我试过把同一个需求丢给Copilot、CodeWhisperer和Claude，结果发现：它们能写出语法正确的函数，但没法帮你拆解“用户说‘导出Excel报表’背后真正要的是什么”。真正的痛点从来不在单行代码生成，而在需求理解→任务分解→工具调用→错误回溯→结果验证这一整条链路上的断点。XiheAgent（羲和）就是冲着这个断点来的。它不叫“AI编程助手”，而叫“AI编码助手”，一字之差，重心完全不同：前者聚焦“写”，后者锚定“做”。它用LangGraph构建有状态、可中断、可回溯的任务图谱，用FastAPI封装成轻量级服务接口，底层通过DeepAgents实现子任务的自主调度与协作。你不需要把它部署成SaaS平台，它可以跑在本地开发机上，作为VS Code插件后端，也可以嵌入CI/CD流水线做自动化代码审查。关键词XiheAgent、LangGraph、FastAPI、DeepAgents，不是堆砌术语，而是四个不可替代的齿轮：LangGraph是它的“神经系统”，负责记忆上下文与决策路径；FastAPI是它的“外周接口”，让任何语言写的前端都能调用；DeepAgents是它的“执行肌群”，把抽象任务翻译成具体动作；而XiheAgent这个名字本身，就是整套设计哲学的具象化——羲和是中国古代神话中掌管太阳运行的神祇，寓意“调度有序、节律可控、光照全域”。如果你正在被“AI生成代码质量不稳定”“多步骤任务无法连贯执行”“调试时不知道AI到底卡在哪一步”这些问题反复折磨，那这篇内容就是为你写的。它不讲大道理，只拆解真实场景下的每一步怎么选、为什么这么选、踩过哪些坑。

2. 整体架构设计：为什么放弃Chain-of-Thought，选择Graph-of-Action？

2.1 传统方案的三个硬伤，直接决定了必须换路

我最早用LangChain搭过一版类似系统，核心逻辑是Chain-of-Thought（CoT）：用户提问 → LLM生成推理链 → 按步骤调用工具 → 拼接结果返回。实测下来，在简单问答（如“Python怎么读CSV”）上很顺，但只要任务变复杂，立刻崩盘。崩在哪？三点：

第一，状态丢失。比如用户说：“先查下订单表结构，再找出近7天未支付的订单ID，最后用这些ID调用退款接口。”CoT链式执行一旦中间某步失败（比如数据库连接超时），整个流程就断了，LLM不会自动重试或降级，更不会记住“已查过表结构”这个事实，重来一遍又得重复执行前两步。

第二，分支失控。当遇到需要条件判断的场景（如“如果订单金额大于500元，走人工审核流程；否则直接退款”），CoT只能靠LLM自己在prompt里硬编if-else逻辑。但LLM对布尔条件的判断极不稳定，测试中出现过37%的误判率——不是模型能力问题，而是文本生成本质不适合做确定性分支决策。

第三，调试黑盒。所有步骤都在一个LLM调用里完成，日志只有一行“LLM返回了xxx”，根本看不到“第2步调用SQL查询时参数拼错了”这种细节。线上出问题，只能靠猜。

提示：别迷信“LLM越来越强就能解决一切”。LLM是概率引擎，不是确定性执行器。把需要确定性的环节（如分支判断、状态保持、错误重试）交给LLM，等于让交通警察用掷骰子决定红绿灯时长。

2.2 LangGraph的“节点+边”模型，如何精准切中这三个痛点

LangGraph不是LangChain的升级版，而是范式重构。它把任务建模成有向无环图（DAG），每个节点是一个可独立执行、可单独测试的单元（比如“SQL查询节点”“HTTP请求节点”“代码格式化节点”），边定义节点间的流转规则（如“SQL查询成功→进入数据处理节点”，“SQL查询失败→进入错误分析节点”）。这带来三个质变：

• 状态显式化：整个图谱运行时，所有节点的输入输出、执行时间、错误信息都存入State对象。你可以随时暂停、检查、修改某个节点的输出，再继续执行。比如SQL查询返回空结果，你手动往State里塞一条模拟数据，跳过失败节点继续往下走——这在CoT里根本做不到。

• 分支确定化：分支逻辑从LLM prompt里剥离，变成图谱中的Router节点。它接收上游节点的输出，用硬编码规则（如if len(data) > 0: return "process"）决定下一步走向。规则写死，结果就100%可预测。

• 调试白盒化：每个节点都有独立日志。出问题时，直接看“SQL查询节点”的日志，里面清清楚楚写着：“执行语句：SELECT * FROM orders WHERE status='pending' AND create_time > '2024-05-01'；错误：OperationalError: (1045, 'Access denied')”。不用再猜LLM到底生成了什么SQL。

XiheAgent的图谱设计不是为了炫技，而是为了解决真实工程问题。我们把一个典型编码任务拆成6个核心节点：parse_request（解析用户意图）、plan_task（生成任务大纲）、fetch_context（获取代码/文档上下文）、generate_code（生成代码）、validate_code（静态检查+单元测试）、execute_action（执行或交付）。每个节点都是独立模块，可以单独替换、压测、监控。比如validate_code节点，我们没用LLM做代码审查，而是集成pylint+pytest+bandit三件套——因为确定性检查必须交给确定性工具。

2.3 DeepAgents：让“子任务”真正具备自主性，而非简单函数调用

很多人看到“DeepAgents”这个词，第一反应是“不就是LangChain里的Tool吗？”——这是最大误解。Tool是被动调用的函数，DeepAgent是主动决策的智能体。在XiheAgent里，fetch_context节点不直接调用“读取文件API”，而是启动一个DeepAgent实例，这个实例会：

1. 先判断当前项目类型（Python/JS/Java），决定该去哪找上下文（pyproject.toml？package.json？pom.xml？）；
2. 再根据用户问题关键词（如“导出Excel”），动态决定要抓取哪些文件（requirements.txt里的openpyxl版本、utils目录下的excel_helper.py、test目录下的导出用例）；
3. 最后才执行具体的文件读取操作，并把结果结构化为{code: [...], docs: [...], tests: [...]}。

这个过程完全由DeepAgent内部的子图谱（subgraph）控制，主图谱只告诉它“去拿上下文”，不干预怎么拿。我们给每个DeepAgent配了独立的LLM（小模型，如Phi-3-mini），避免主LLM被琐碎任务拖慢。实测下来，这种分层调度让整体响应快了40%，且上下文相关性提升明显——因为子Agent比主Agent更懂领域细节。

注意：DeepAgents不是越多越好。我们严格限制子Agent数量，只在三个场景启用：① 需要跨多个异构源（Git+DB+API）聚合信息时；② 需要基于实时反馈动态调整策略时（如代码生成失败后，自动切换到“逐行解释模式”）；③ 需要隔离敏感操作时（如数据库变更，必须经由专用DB-Agent执行，主图谱无权限）。

3. 核心模块实现：从LangGraph图谱搭建到FastAPI服务封装

3.1 LangGraph图谱：6个节点如何协同，附完整代码结构

XiheAgent的图谱不是一次性画完的，而是按“最小可行图谱（MVG）→ 增量扩展”思路迭代。初始版只包含3个节点：parse_request、generate_code、return_result。跑通后，再逐步加入validate_code和execute_action。下面以V2.0稳定版（6节点）为例，说明关键实现细节：

节点1：parse_request—— 意图识别的“守门人”
这个节点不生成代码，只做两件事：① 判断用户输入是否为有效编码请求（过滤闲聊、错别字）；② 提取结构化参数。我们没用LLM做NER，而是用正则+关键词匹配（如检测到“python”“sql”“api”等词触发对应解析器）。原因很简单：98%的编码请求都带明确技术栈关键词，规则匹配又快又准。只有当规则无法覆盖时（如用户说“让页面像苹果官网那样动起来”），才fallback到LLM。代码里用@tool装饰器封装，输入是原始字符串，输出是{"intent": "code_generation", "tech_stack": ["vue", "typescript"], "action": "animation"}这样的dict。

节点2：plan_task—— 任务大纲生成器
这里才是LLM第一次真正发力。Prompt设计遵循“三明治结构”：顶部明确角色（“你是一个资深全栈工程师，正在帮同事拆解需求”），中部给示例（展示“用户说‘做个登录页’→ 大纲：1. HTML结构 2. CSS样式 3. JS表单验证”），底部强调约束（“大纲必须是纯数字编号列表，每项不超过10个字，禁止出现‘可能’‘大概’等模糊词”）。生成的大纲不是最终执行计划，而是给后续节点的导航索引。比如大纲第3项“JS表单验证”，会触发generate_code节点专门生成验证逻辑，而不是让LLM一次生成全部代码。

节点3：fetch_context—— 上下文感知的“情报员”
这是DeepAgents首次登场的地方。节点内启动一个ContextAgent实例，它有自己的子图谱：先调用detect_project_type工具确定技术栈，再并行调用read_requirements、scan_source_files、fetch_git_history三个工具，最后用context_summarizer（小LLM）把结果压缩成500字内的摘要。关键技巧：所有文件读取都加了max_lines=200限制，避免大文件拖垮性能；Git历史只查最近3次commit，因为旧代码对当前任务参考价值低。

节点4：generate_code—— 专注生成，拒绝“全能幻觉”
这个节点的LLM prompt强制要求：① 必须引用fetch_context提供的上下文（如“根据requirements.txt，你应使用requests>=2.28.0”）；② 每段代码必须带注释说明用途；③ 禁止生成数据库密码等敏感信息。我们实测发现，加上上下文引用约束后，代码可用率从62%提升到89%。生成结果不是纯文本，而是结构化JSON：{"language": "python", "code": "...", "explanation": "...", "dependencies": ["requests"]}。

节点5：validate_code—— 确定性防线
这是整个图谱里唯一不用LLM的节点。它并行执行三件事：

• pylint_check：用pylint --disable=all --enable=C,R,W,E,F --output-format=json跑静态检查；
• pytest_run：在临时沙箱里执行pytest test_*.py -v --tb=short；
• bandit_scan：用bandit -r . -f json -o bandit_report.json扫安全漏洞。
  三者结果汇总成{"passed": true, "issues": [{"type": "security", "desc": "使用了eval()"}]}。只要任一检查失败，就触发error_handler节点，而不是让LLM“再试一次”。

节点6：execute_action—— 安全执行的“闸门”
所有需要副作用的操作（写文件、发HTTP请求、执行shell命令）都集中在这里。它不做决策，只做验证：检查generate_code输出的action_type字段（如"write_file"），匹配预设白名单（["write_file", "http_post", "run_command"]），再校验参数合法性（如write_file必须含path和content字段）。写文件时，路径必须在项目根目录下，且不能含../；发HTTP请求时，域名必须在allowed_domains = ["api.example.com", "localhost:8000"]列表里。这是最后一道防线，确保AI生成的内容不会越界。

# xihe/graph.py 核心图谱定义（简化版） from langgraph.graph import StateGraph, END from typing import TypedDict, List, Dict, Any class AgentState(TypedDict): user_input: str intent: Dict[str, Any] plan: List[str] context: Dict[str, Any] code: Dict[str, Any] validation: Dict[str, Any] action_result: Dict[str, Any] def parse_request(state: AgentState) -> AgentState: # 规则匹配提取intent return {"intent": extract_intent(state["user_input"])} def plan_task(state: AgentState) -> AgentState: # LLM生成大纲 llm = ChatOpenAI(model="gpt-4-turbo") prompt = ChatPromptTemplate.from_messages([ ("system", "你是一个资深工程师..."), ("human", "{input}") ]) chain = prompt | llm | StrOutputParser() plan = chain.invoke({"input": state["user_input"]}) return {"plan": parse_plan(plan)} def fetch_context(state: AgentState) -> AgentState: # 启动ContextAgent子图谱 agent = ContextAgent() context = agent.run(state["intent"]) return {"context": context} # ...其他节点定义省略... # 构建图谱 workflow = StateGraph(AgentState) workflow.add_node("parse_request", parse_request) workflow.add_node("plan_task", plan_task) workflow.add_node("fetch_context", fetch_context) workflow.add_node("generate_code", generate_code) workflow.add_node("validate_code", validate_code) workflow.add_node("execute_action", execute_action) # 定义边（流转规则） workflow.add_edge("parse_request", "plan_task") workflow.add_edge("plan_task", "fetch_context") workflow.add_conditional_edges( "fetch_context", lambda x: "error" if x.get("context", {}).get("error") else "generate_code", {"error": "error_handler", "generate_code": "generate_code"} ) workflow.add_edge("generate_code", "validate_code") workflow.add_conditional_edges( "validate_code", lambda x: "execute_action" if x["validation"]["passed"] else "error_handler", {"execute_action": "execute_action", "error_handler": "error_handler"} ) workflow.add_edge("execute_action", END) app = workflow.compile()

3.2 FastAPI服务：轻量、安全、可监控的API层

LangGraph图谱再强大，也得暴露成API才能用。我们选FastAPI，不是因为它“火”，而是三个硬指标碾压其他框架：

• 异步原生支持：LangGraph的节点执行天然异步（如HTTP请求、文件IO），FastAPI的async/await语法能1:1映射，不用额外套一层线程池；
• 自动生成OpenAPI文档：前端团队直接看/docs就能调用，省去手写接口文档的时间；
• 依赖注入机制：图谱实例、LLM客户端、数据库连接池都能作为依赖注入，方便单元测试和环境隔离。

服务目录结构严格遵循“功能域划分”，而非传统MVC：

xihe_api/ ├── main.py # ASGI入口，只做路由挂载 ├── api/ │ └── v1/ │ ├── __init__.py │ ├── endpoints.py # 所有API路由（/ask, /status, /cancel） │ └── schemas.py # Pydantic模型（Request/Response） ├── core/ │ ├── graph.py # LangGraph图谱实例（单例） │ ├── llm.py # LLM客户端工厂（支持OpenAI/Ollama/本地模型） │ └── security.py # API Key鉴权（JWT + Redis缓存） ├── utils/ │ ├── logger.py # 结构化日志（含trace_id关联图谱节点） │ └── metrics.py # Prometheus指标（节点耗时、成功率、token用量） └── tests/ # 每个endpoint都有对应测试

关键API设计：

• POST /v1/ask：主入口。接收{"query": "用Python写个爬虫抓豆瓣电影Top250"}，返回{"task_id": "abc123", "status": "running"}。立即返回task_id，不阻塞等待结果——因为图谱执行可能长达30秒，前端需轮询。
• GET /v1/task/{task_id}：查状态。返回{"status": "completed", "result": {...}, "steps": [{"node": "generate_code", "duration_ms": 1240, "success": true}]}。steps数组是图谱执行时自动记录的节点轨迹，调试神器。
• POST /v1/cancel/{task_id}：取消任务。利用LangGraph的interrupt机制，向正在运行的图谱发送中断信号，避免资源浪费。

安全方面，我们做了三层防护：

1. 传输层：强制HTTPS，HSTS头开启；
2. 认证层：API Key放在HeaderX-API-Key，经security.verify_api_key()校验，Key存储在Redis里，带TTL（24小时）；
3. 执行层：execute_action节点的白名单校验，已在前文详述。

实操心得：别在FastAPI里做复杂业务逻辑。所有“判断”“组装”“转换”都交给LangGraph节点，FastAPI只做三件事：收请求、转调用、发响应。我们曾把代码验证逻辑写进endpoint，结果导致单元测试难写、图谱复用率低，重构后代码量减了40%，可维护性大幅提升。

3.3 DeepAgents子图谱：如何让子Agent既聪明又可控

DeepAgents不是独立服务，而是LangGraph图谱里的“嵌套图谱”。以ContextAgent为例，它的子图谱结构如下：

[DetectProjectType] ↓ [ReadRequirements] → [ScanSourceFiles] → [FetchGitHistory] ↓ ↓ ↓ [MergeContext] ←←←←←←←←←←←←←←←←←←←←←←←←← ↓ [SummarizeContext]

关键实现要点：

• 子图谱独立生命周期：ContextAgent类继承BaseAgent，初始化时创建自己的StateGraph，不共享主图谱的state。通信只通过输入参数和返回值。
• 工具注册中心化：所有子Agent共用一个ToolRegistry，里面存着read_file、list_dir、git_log等工具。注册时指定scope="context"，确保CodeAgent（另一个子Agent）不会误用数据库工具。
• 超时熔断机制：每个子图谱执行设timeout=15s，超时自动终止并返回{"error": "timeout"}。避免某个子任务卡死拖垮整个请求。
• 资源隔离：子Agent的LLM客户端（用于summarize_context）配置独立的max_tokens=512和temperature=0.1，防止它“自由发挥”生成无关内容。

我们刻意限制子Agent的能力边界。比如DBAgent只允许执行SELECT语句，INSERT/UPDATE/DELETE必须由人工确认后，通过/v1/execute-sql专用接口触发。这不是技术限制，而是工程原则：AI可以提建议，但不能替人做决策。

4. 实战部署与避坑指南：从本地调试到生产上线

4.1 本地开发：如何快速启动并验证图谱逻辑

新手最容易卡在“图谱跑不起来”。别急着部署，先确保本地能debug。我们的标准流程是：

1. 环境准备：用conda建纯净环境，避免包冲突

   conda create -n xihe python=3.11 conda activate xihe pip install langgraph fastapi uvicorn pydantic[dotenv] pylint pytest bandit

2. 启动FastAPI服务：

   # 设置环境变量 export OPENAI_API_KEY="sk-xxx" export XIHE_LLM_MODEL="gpt-4-turbo" # 启动（自动重载） uvicorn xihe_api.main:app --reload --host 0.0.0.0 --port 8000

3. 用curl测试最简路径：

   curl -X POST "http://localhost:8000/v1/ask" \ -H "Content-Type: application/json" \ -H "X-API-Key: dev-key" \ -d '{"query":"用Python打印斐波那契数列前10项"}'

   如果返回{"task_id":"abc123","status":"running"}，说明服务通了。接着用task_id查状态，看是否走到generate_code节点。

4. 图谱单步调试：
   在main.py里加断点，或直接调用图谱：

   from xihe.core.graph import app result = app.invoke({"user_input": "hello world"}) print(result) # 查看每个节点的输出

   这比在浏览器里点来点去高效得多，尤其排查parse_request是否正确提取intent时。

踩过的坑：Windows下uvicorn有时会报OSError: [WinError 10013]。解决方案是加--workers 1参数，禁用多进程。Mac M1芯片用户注意：ollama默认用CPU，要加--numa参数启用GPU加速，否则phi-3-mini推理慢得像蜗牛。

4.2 生产部署：Nginx + Uvicorn + Docker的黄金组合

本地跑通不等于生产可用。我们线上用三件套：

• Uvicorn：作为ASGI服务器，配置--workers 4 --limit-concurrency 100 --timeout-keep-alive 5，平衡吞吐与内存；
• Nginx：反向代理+静态文件托管+限流。关键配置：

  location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; # 限流：每个IP每分钟最多30次请求 limit_req zone=xihe burst=5 nodelay; }

• Docker：镜像分层构建，基础镜像用python:3.11-slim，减少攻击面。Dockerfile关键段：

  FROM python:3.11-slim # 创建非root用户 RUN groupadd -g 1001 -r xihe && useradd -S -u 1001 -r -g xihe xihe USER xihe # 复制依赖（利用Docker缓存） COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 复制代码 COPY . /app WORKDIR /app # 暴露端口 EXPOSE 8000 CMD ["uvicorn", "xihe_api.main:app", "--host", "0.0.0.0:8000", "--proxy-headers"]

环境变量管理用.env文件，通过python-decouple加载，绝不硬编码密钥。生产环境必须设置XIHE_ENV=production，触发严格的安全检查（如禁用/docs接口）。

实操心得：别用docker-compose up -d一键启动就完事。每次部署后，必须执行三步验证：①curl -I http://your-domain.com/healthz看返回200；② 发一个简单请求，检查/v1/task/{id}返回的steps数组是否完整；③ 查看Prometheus指标，确认xihe_node_duration_seconds_count{node="generate_code"}有增量。漏掉任何一步，都可能线上静默故障。

4.3 性能调优：让响应时间从8秒降到1.2秒的5个关键点

刚上线时，平均响应时间8.2秒，用户抱怨“比手写还慢”。我们逐层剖析，找到5个瓶颈点：

最终P95响应时间稳定在1.2秒。关键认知：AI编码助手的性能，70%取决于工程优化，30%取决于模型能力。再快的LLM，遇上糟糕的IO调度，也快不起来。

4.4 监控告警：用Prometheus+Grafana盯住图谱的每一次心跳

没有监控的AI系统，就像没装刹车的跑车。我们监控四类指标：

• 可用性指标：up{job="xihe-api"}（服务存活）、http_requests_total{status=~"5.."}（5xx错误率）；
• 性能指标：xihe_node_duration_seconds_bucket{node="generate_code", le="2.0"}（节点耗时分布）、xihe_token_usage_total{model="gpt-4-turbo"}（Token消耗）；
• 业务指标：xihe_task_success_rate（任务成功率）、xihe_code_acceptance_rate（生成代码被采纳率，前端埋点统计）；
• 资源指标：process_resident_memory_bytes（内存占用）、container_cpu_usage_seconds_total（CPU使用率）。

告警规则示例（Prometheus Rule）：

- alert: XiheNodeLatencyHigh expr: histogram_quantile(0.95, sum(rate(xihe_node_duration_seconds_bucket[1h])) by (le, node)) > 5 for: 5m labels: severity: warning annotations: summary: "Xihe {{ $labels.node }} node latency > 5s" description: "95% of {{ $labels.node }} executions take more than 5 seconds"

Grafana看板分三块：

• 全局概览：QPS、成功率、平均耗时趋势；
• 节点深潜：点击任意节点，看它的耗时分布、错误类型TOP5；
• 任务追踪：输入task_id，还原整个图谱执行轨迹，精确到毫秒级。

注意：监控不是摆设。我们每周五下午固定1小时，集体看Grafana，重点看xihe_task_success_rate是否低于95%。如果连续两天下跌，立刻拉群排查——可能是新上线的validate_code规则太严，误杀了好代码。

5. 常见问题与实战排查：那些文档里不会写的真相

5.1 “图谱卡在某个节点不动了”——90%是状态传递错误

现象：调用/v1/ask后，/v1/task/{id}一直返回"status": "running"，但日志里看不到后续节点执行。

排查路径：

1. 先查/v1/task/{id}返回的steps数组，看最后一个节点名；
2. 对照图谱定义，确认该节点的add_edge或add_conditional_edges是否写错；
3. 最常见错误：conditional_edges的lambda函数返回了不存在的节点名。比如写了return "next_step"，但图谱里实际节点叫"process_data"。LangGraph不会报错，只是静默卡住。

真实案例：有个同事把"validate_code"写成"valiate_code"（少个d），图谱永远停在generate_code。解决方案：在workflow.compile()后加一行print(workflow.get_graph().draw_mermaid())，生成Mermaid图（文本格式），肉眼核对节点名。

提示：用langgraph.checkpoint.sqlite做状态持久化时，SQLite文件权限错误也会导致卡住。确保Uvicorn进程对checkpoints/目录有读写权限。

5.2 “生成的代码总缺一行import”——上下文注入失效的隐秘原因

现象：generate_code节点生成的代码，经常漏掉import requests，尽管fetch_context明明返回了requirements.txt里有requests==2.31.0。

根因分析：

• fetch_context输出的context是{"requirements": ["requests==2.31.0"], "files": [...]}；
• generate_code的prompt里写的是“请参考以下依赖：{context.requirements}”，但LangGraph的state是dict，{context.requirements}会被当成字符串"['requests==2.31.0']"，LLM看不懂；
• 正确写法是{context['requirements']}，或者在节点里预处理：state["context_str"] = "\n".join(state["context"]["requirements"])，prompt里用{context_str}。

解决方案：
所有传给LLM的上下文，必须提前格式化为自然语言段落。我们写了个通用函数：

def format_context(context: dict) -> str: parts = [] if context.get("requirements"): parts.append("项目依赖：" + ", ".join(context["requirements"])) if context.get("files"): parts.append("相关文件：" + ", ".join([f["name"] for f in context["files"][:3]])) return "\n".join(parts)

然后在generate_code节点里调用它。从此再没出现过import缺失。

5.3 “FastAPI启动报错：No module named 'xihe_api'”——Python路径的坑

现象：Docker里uvicorn xihe_api.main:app启动失败，报ModuleNotFoundError。

原因：Docker默认工作目录是镜像根目录/，而代码在/app下。Uvicorn找不到xihe_api包。

标准解法：

• 在Dockerfile里加WORKDIR /app；
• 或启动命令改uvicorn --chdir /app xihe_api.main:app；
• 更彻底的方案：在/app下放一个setup.py，用pip install -e .安装为可编辑包。

避坑技巧：本地开发时，用PYTHONPATH=/path/to/xihe_api临时解决，但绝不能带到生产环境。

5.4 “DeepAgent子图谱不执行”——作用域隔离的双刃剑

现象：fetch_context节点里启动ContextAgent，但子图谱的日志完全不输出，仿佛没运行。

真相：子图谱的logger默认用root logger，而主程序的logger配置了propagate=False，导致子日志被拦截。

修复方法：
在子Agent初始化时，显式配置logger：

import logging logger = logging.getLogger(f"context_agent_{uuid4().hex[:4]}") logger.setLevel(logging.INFO) handler = logging.StreamHandler() formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s') handler.setFormatter(formatter) logger.addHandler(handler)

这样子日志就能独立输出，不被主logger压制。

5.5 “线上突然大量500错误”——API Key泄露的连锁反应

现象：某天凌晨，http_requests_total{status="500"}突增，但图谱日志显示"error": "Authentication failed"。

溯源：查Nginx access log，发现大量请求来自同一IP，Header里X-API-Key是明文dev-key。原来前端同学把开发Key写进了生产JS代码，被爬虫扫走了。

亡羊补牢：

• 立即在Redis里删掉dev-key；
• FastAPI层加rate_limit中间件，对异常Key频次做限制；
• 强制推行Key轮换机制：所有Key有效期设为7天，到期自动失效。

最后分享个小技巧：在/v1/askendpoint里，加一行logger.info(f"API Key used: {request.headers.get('X-API-Key', '')[:5]}...")，但只在XIHE_ENV=development时生效。生产环境不打Key，但开发时能快速定位谁在用哪个Key。

我在实际用XiheAgent写CI脚本时发现，它最珍贵的价值不是生成了多少行代码，而是把“人脑里模糊的需求”变成了“机器可追溯的执行路径”。每次看到steps数组里清晰记录着“fetch_context耗时320ms，generate_code调用gpt-4-turbo，validate_code发现1个PEP8警告”，我就觉得，这才是AI该有的样子——不是取代人，而是