26 篇文档带有标签（标签：how-to）

用最小但真实的链路帮你跑通第一条 Agent 主线：AgentBuilder 默认装配、ReActRuntime step loop、AgentModelClient 协议适配、AgentMemory 回灌与 AgentResult 收口。

Explains ai4j-agent Skills: how the SDK discovers and scopes SKILL.md, the workspace-safe vs user-home roots, request-scoped AgentSkillResolver for tenants, and why Skills never bypass tool authorization.

最短路径确认 starter 装配、task API 暴露、无 LLM 与带 LLM 两条最小流程跑通 validate -> run -> result -> report 链路，附 demo 默认模型配置踩坑与排障顺序。

How to contribute to AI4J — reporting issues, proposing changes, running docs-site local checks and Java module tests, and following the security disclosure policy.

AI4J 文档站推荐部署方案：Docusaurus + Cloudflare Pages + 自定义域名。覆盖 GitHub 集成自动构建、全球 CDN 分发、免费额度、自定义域名配置与持续发布流程。

用最短路径把 ai4j-cli 跑起来：构建 fat jar、跑通 one-shot 与持续会话，并核对 session、workspace、provider/model 状态以完成最小验证。

只讲后端 executor 这一半：FlowGramNodeExecutor 接口、runtime 识别与注册时机、getType 协议名稳定性、execute 前 runtime 已完成的输入解析与上下文字段。

讲解 IImageService 图像生成与流式监听用法，覆盖 OpenAI 与豆包适配、请求字段、事件模型和常见接入问题。

普通 Java / Maven 项目接入 AI4J 的最短路径：从依赖、环境变量到第一条同步 Chat 请求，给出可复制的 Configuration→AiService→IChatService 闭环代码与成功标准。

聚焦单服务模式：McpClient 的真实生命周期、connect() 与 AUTO/legacy profile 的差异、缓存与心跳重连语义，以及 callTool 的失败语义和常见排障路径。

拆开第三方 MCP 从配置文件一路进入 Agent 推理循环并被模型调用的 7 层执行链，覆盖投影、调用分发、多租户回退与 trace 诊断点。

讲解 IMusicService 音乐生成用法：submitMusic/submitLyrics 提交任务、fetch 轮询任务结果，Suno 适配、任务生命周期、字段模型与轮询要点。

Spring Boot 项目接入 AI4J 的最短路径：引入 starter、最小 application.yml 配置、AiService Bean 注入，并给出 controller 发出第一条模型请求的完整示例。

Spring Boot 接入 AI4J 的最短成功路径：引入 starter、配置 ai.*、注入 AiService 并发出第一个 ChatCompletion。

讲解 IVideoService 视频生成用法：create 提交任务、retrieve 轮询状态、content 拉取成片字节流、remix 改写，OpenAI 兼容网关、multipart 提交与异步轮询模型。

在 ai4j-flowgram-webapp-demo 里把新节点做成可编辑、可校验、可序列化、可映射到后端的前端节点：type 枚举、FlowNodeRegistry、onAdd schema 工厂与 backend type 映射。

分清 Coding Agent 的构建、Maven 发布与终端 CLI 安装三层，说明当前仓库已提供 fat jar 与平台 launcher，并明确 fat jar 为最稳分发基线及 release 缺口。

用天气分析双 Agent workflow 讲清 SequentialWorkflow 的 outputText 接力、WorkflowContext side channel、节点 session 隔离与 NamedNode 最小观测，以及何时该升级到 StateGraphWorkflow。

ai4j-agent 的拦截层：ToolInterceptor(block/modify/routeTo sandbox) 与 PromptInterceptor 对应 Claude Code 的 PreToolUse/PostToolUse/UserPromptSubmit，加上 observe-only 生命周期 Hook，附 hooks 门面与 CLI 配置。

AI4J 生产排障入口。不列出所有异常栈，而是按能力层把问题定位到正确页面和检查项：模型请求失败查 provider key、Chat 能用 Responses 不能用查 provider 支持、Streaming 没增量查消费方式。

面向第三方插件作者的动手指南：用 CLI 生成最小插件项目，稳定 manifest 与公共 ID 命名规则，写结构化 tool input schema，把 apply() 保持为轻量注册函数，完成 manifest/资源/schema 校验与发布前声明。

插件使用者的组装配方：jar 进 classpath 后如何用 CLI plan/check 做接入前检查，按 Java、Spring Boot、Agent、Coding Agent、多插件组合分别给出 enable/allow/expose 配置，区分 command 与 tool 暴露语义。

讲解 AI4J 如何用 @McpService/@McpTool 注解、adapter 和 McpServerEngine 把 Java 能力发布成 MCP Server，覆盖 Tool/Resource/Prompt 三类能力链与三种服务端 transport 的真实差异。

讲清第六种插件能力 ExtensionCapability.LIFECYCLE：插件通过 context.lifecycle().register(hook) 注册 AgentLifecycleHook，在 session/turn/model/tool/compact 事件点接收 AgentLifecycleEvent，用于观察、遥测与审计，不贡献工具或资源。

讲清 Claude-Code 风格的 shell-command 生命周期钩子（PreToolUse/PostToolUse/UserPromptSubmit/Stop/PreCompact/SessionStart/SessionEnd）的配置、拦截/观察分流、退出码协议，以及让这些钩子能安全加载的工作区信任门与 ai4j-cli trust 命令。

自定义节点是把能力正式接入 Flowgram 前后端执行契约：后端 FlowGramNodeExecutor 扩展点、getType 协议名、输入输出 contract 稳定性原则与前后端协同三件事。