增量分析报告 — codescan/code-agent

• 分支: v0.5.25
• 对比范围: 486fe2c78504eeccd99adfe5da8b7ed0ba5aa045 → 417ba9254b0352a43f8419c035b10ce5a95f10dd
• 变更规模: 3 个文件，共 3 处改动（+3 / -2 行）
• 变更主题: 为 POST /agent/run 增加「报告格式模板（report_format）」的可选覆盖能力，并贯穿到 Agent 构建层。

---

一、变更概览

整体是一次功能增强型改动，无删除逻辑、无破坏性接口变更，风险低。

---

二、变更详情与代码走查

1. backend/src/shared/models.py

class AgentRunRequest(BaseModel):
    ...
    override_llm: str = ""           # 可选: 覆盖默认模型
    report_format: Optional[str] = None  # 可选: 覆盖报告格式模板

• Optional 已在文件头部导入（from typing import Optional），字段类型合法，无导入缺失问题。
• 默认值 None 保持了向后兼容，旧请求不受影响。

2. backend/src/apis/agent_run_service.py

crew = factory.create_crew(
    config=config,
    commit_hash=commit_hash,
    project=project,
    branch=branch,
    report_format=request.report_format,   # 新增
)

• 仅在单配置入口 run() 中透传，参数来源 request.report_format 与模型字段一致。

3. backend/src/runtime/agent_factory.py

def create_crew(self, config: dict, commit_hash: str, project: str,
                branch: str = "", report_format: str = None) -> Crew:
    ...
    report_format = report_format if report_format else config.get("report_format", "")

• 覆盖优先级正确：显式传参 > config 内置配置，report_format 为空串/None 时回退到 config，行为合理。
• 下游拼接逻辑（if report_format: full_prompt_parts.append("\n## 报告格式\n\n" + report_format)）未被破坏，空值时不会追加「报告格式」段落。

结论：改动链路自洽，参数从 API → Service → Factory 全程贯通，覆盖优先级符合预期。

---

三、修复 / 新增问题（基于质检引擎真实对比）

说明：本次 diff 未改动这两个问题所在的函数体，质检结果中的「修复 3 条 / 新增 3 条」实为同一批既有问题因行号位移而产生的镜像，并非真实修复或真实新增。

被标记为「修复」的问题（实为行号位移）

• [Medium/Complexity] 圈复杂度过高 @ agent_run_service.py:500（base 行号）
• [Medium/Dependency] 高耦合 @ agent_run_service.py:500（base 行号）
• [Low/Maintainability] 行过长 @ agent_factory.py:65（base 行号）

被标记为「新增」的问题（实为同行号位移）

• [Medium/Complexity] 圈复杂度过高 @ agent_run_service.py:501 — cyclomatic complexity is high (count=11)
• [Medium/Dependency] 高耦合 @ agent_run_service.py:501 — 'batch_run' directly depends on 12 functions, exceeding the threshold of 10
• [Low/Maintainability] 行过长 @ agent_factory.py:30 — source line exceeds 120 characters

逐条核对结论：

1. agent_run_service.py:500 → 501：两处问题（复杂度、耦合）均落在 batch_run 上，本次 diff 未改动 batch_run 函数体，仅因单配置 run() 增加一行使行号 +1 而下移，属同一既有问题，非新增、也不存在真实修复。
2. agent_factory.py:65 → 30：base 行 65 与 head 行 30 对应的是 create_crew 的签名行，本次改动将该行加长（新增 report_format: str = None 形参）后超长问题被重新定位。属同一既有问题的重新标注。

净变化：真实「修复 bug」= 0 条；真实「新增 bug」= 0 条。

---

四、风险与改进建议

风险等级：低。无功能性回归风险，接口保持向后兼容。

1. [一致性] 覆盖能力仅覆盖单配置入口 AgentBatchRequest（POST /agent/batch）未提供 report_format 字段，batch_run._run_one() 调用 create_crew 时也未透传；run_code_wiki 同样未透传。若产品预期批处理/文档生成也支持自定义报告格式，则存在能力不一致。建议按需在 AgentBatchRequest 增加同名可选字段并在 _run_one 中透传。

2. [健壮性] report_format 缺少长度/内容约束 该参数最终被拼接进 full_prompt，作为 LLM 的后处理指令。Optional[str] 对传入长度和内容无上限，超长或异常内容可能挤占 prompt 预算。建议在模型层加 max_length 约束，或在 Factory 拼接时做长度截断。

3. [可读性] create_crew 签名行超长 agent_factory.py:30 已触发「行过长（> 120 字符）」告警。建议将形参换行书写，消除该告警：

   def create_crew(
       self,
       config: dict,
       commit_hash: str,
       project: str,
       branch: str = "",
       report_format: str = None,
   ) -> Crew:
   

4. [既有技术债] batch_run 复杂度/耦合超阈值 虽然本次未引入，但 batch_run 圈复杂度 11、直接依赖 12 个函数，已超过阈值，建议后续迭代拆分（提取 _run_one 之外的响应组装/结果聚合逻辑）。

---

五、总结

本次变更为一项小而聚拢的功能增强：新增 report_format 覆盖字段，并沿 AgentRunRequest → agent_run_service.run → AgentFactory.create_crew 正确贯通，覆盖优先级设计合理，无逻辑缺陷与回归风险。质检对比中的「修复/新增」条目实为同一既有问题的行号位移镜像，真实修复与真实新增均为 0。后续可关注批处理/文档生成入口的一致性补齐及入参长度约束。