手把手教你写deepwiki-rs自定义AgentStepForwardAgent抽象层源码级教学【免费下载链接】deepwiki-rsTurn code into clarity. Generate accurate technical docs and AI-ready context in minutes—perfectly structured for human teams and intelligent agents.项目地址: https://gitcode.com/gh_mirrors/de/deepwiki-rsdeepwiki-rs 是一款把代码变成清晰文档的开源工具输入一个代码仓库几分钟内就能自动生成面向人类团队与 AI Agent 的结构化技术文档。而支撑这一切的正是它背后 13 个分工明确的研究与写作 Agent。本文将以源码级视角带你彻底搞懂 deepwiki-rs 自定义 Agent 的基石——StepForwardAgent 抽象层学完你就能照葫芦画瓢写出属于自己的专属 Agent。为什么 deepwiki-rs 需要 Agent 抽象层deepwiki-rs 的整个文档生成流水线分为 4 个阶段预处理Preprocess→ 研究Research→ 编排撰写Compose→ 输出Outlet每个阶段都有多个 Agent 在干活。如果没有抽象层13 个 Agent 就要各自实现验证数据 → 格式化 → 构建 Prompt → 调用 LLM → 写回 Memory这一整套流程代码重复率会高得吓人。StepForwardAgent 抽象层正是为了解决这个问题而生统一执行流程 定制化配置。它的设计哲学很像麦当劳的中央厨房——每个汉堡的工序完全一样烤面包 → 加肉饼 → 加配料 → 包装区别只是配方不同。Agent 也一样执行逻辑全部复用你只需提供自己的配方。核心源码解析StepForwardAgent trait 到底做了什么抽象层的灵魂位于 src/generator/step_forward_agent.rs核心是一个 Rust trait#[async_trait] pub trait StepForwardAgent: Send Sync { type Output: JsonSchema fora Deserializea Serialize Send Sync static; fn agent_type(self) - String; fn memory_scope_key(self) - String; fn data_config(self) - AgentDataConfig; fn prompt_template(self) - PromptTemplate; async fn execute(self, context: GeneratorContext) - ResultSelf::Output { ... } }其中execute()是带默认实现的总指挥内部是一条标准的 7 步流水线校验必需数据源 → 合并必需可选数据 → 用模板构建 Prompt → 按模式调用 LLM → 时间占位符替换 → 结果写入 Memory → 执行后处理钩子。而你需要自己实现的其实只有 4 个方法agent_type()身份标识、memory_scope_key()结果存储位置、data_config()要什么数据、prompt_template()怎么提问。剩下的post_process()、provide_custom_prompt_content()、should_include_timestamp()都是带默认值的可选钩子按需覆写即可。数据从哪来AgentDataConfig 与 DataSource 声明式取数自定义 Agent 最常问的问题是我能用哪些数据答案在AgentDataConfig里它把数据源分成required_sources必需和optional_sources可选两组。注意必需数据缺失时 Agent 会直接报错跳过这是防呆设计。DataSource枚举提供了 4 种开箱即用的取数方式PROJECT_STRUCTURE项目目录树来自预处理阶段CODE_INSIGHTS代码洞察文件用途、重要度评分DEPENDENCY_ANALYSIS依赖关系分析ResearchResult(...)其他研究 Agent 的产出实现 Agent 间接力knowledge_categories(...)按分类加载外部知识配置 Agent 的配方PromptTemplate 与三种 LLM 调用模式PromptTemplate由 4 部分组成system_prompt系统角色设定、opening_instruction开场引导、closing_instruction收尾输出要求、llm_call_mode调用模式。其中调用模式决定了 Agent 的输出性格Extract要求 LLM 返回结构化 JSON自动反序列化为 Rust 类型适合需要精确数据的分析型 AgentPrompt返回自由文本直接作为文档内容适合写作型 AgentPromptWithTools开启 ReAct 循环Agent 能自主调用文件浏览、代码阅读等内置工具适合需要自主探索的 Agent实操教学手写第一个自定义 Agent下面以官方研究 Agent 为蓝本演示三步写一个架构分析 Agent。参考实现位于 src/generator/research/agents/architecture_researcher.rs。第一步声明输出与身份#[derive(Default)] pub struct MyArchitectureAgent; impl StepForwardAgent for MyArchitectureAgent { type Output String; // 自由文本输出 fn agent_type(self) - String { My Architecture Report.to_string() } fn memory_scope_key(self) - String { studies_research.to_string() } }第二步声明数据需求fn data_config(self) - AgentDataConfig { AgentDataConfig { required_sources: vec![ DataSource::ResearchResult(System Context Research Report.to_string()), ], optional_sources: vec![ DataSource::PROJECT_STRUCTURE, DataSource::knowledge_categories(vec![architecture, adr]), ], } }第三步编写 Prompt 模板并接入编排器把系统提示词写进prompt_template()指定llm_call_mode: LLMCallMode::PromptWithTools然后在 src/generator/research/orchestrator.rs 的execute_research_pipeline()里加一行self.execute_agent(MyArchitectureAgent, context).await?;就完成了。整个 pipeline 的执行入口在 src/generator/workflow.rs。进阶技巧三个官方 Agent 的精彩实践技巧一结构化输出的代表——BoundaryAnalyzersrc/generator/research/agents/boundary_analyzer.rs 使用type Output BoundaryAnalysisReportLLMCallMode::Extract让 LLM 严格返回cli_boundaries、api_boundaries等 JSON 字段。它还覆写了provide_custom_prompt_content()先本地过滤出 Entry/API/Config 类代码洞察再喂给 LLM这是先本地粗筛、再让 LLM 精析的经典组合拳。技巧二写作 Agent 的标准答案——OverviewEditorsrc/generator/compose/agents/overview_editor.rs 是写作型 Agent 的标杆用Prompt模式产出 C4 SystemContext 文档system_prompt里写死了 Mermaid 语法安全规则ASCII 节点 ID、标准图表头并在closing_instruction里给出完整的文档章节骨架引导 LLM 稳定输出。技巧三后处理钩子的妙用post_process()在结果写入 Memory 后触发。官方用它打印分析摘要如边界分析发现了几个 CLI 命令你完全可以在这里做结果校验、二次加工或发送通知不占用 LLM 调用成本。避坑指南自定义 Agent 的 4 个常见错误必需数据源乱声明如果上游 Agent 没产出你的 Agent 会直接报错。优先用optional_sources兜底忘记时间戳钩子需要时效性感知的写作 Agent记得覆写should_include_timestamp()返回trueOutput 类型不合规必须同时实现JsonSchema Serialize Deserialize否则编译不过Prompt 超长崩溃FormatterConfig内置了紧急截断和语义压缩机制保持默认即可别随意关掉结语从会用到会写只差一层抽象deepwiki-rs 的优雅之处在于它把 AI 文档生成这件复杂事抽象成了配置数据 配置提示词两件简单事。掌握了 StepForwardAgent 抽象层你不仅能看懂项目里 13 个 Agent 的协作逻辑更能按需扩展出自己的专属 Agent——无论是新增一个安全审计报告 Agent还是性能瓶颈分析 Agent都只需要几十行配置代码。现在就去克隆仓库https://gitcode.com/gh_mirrors/de/deepwiki-rs亲手试一次吧从读懂 src/generator/step_forward_agent.rs 开始你的第一个自定义 Agent 已经在路上了。【免费下载链接】deepwiki-rsTurn code into clarity. Generate accurate technical docs and AI-ready context in minutes—perfectly structured for human teams and intelligent agents.项目地址: https://gitcode.com/gh_mirrors/de/deepwiki-rs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考