技术文档
自动解析代码仓库与接口定义，生成标准API文档和技术说明，解决文档滞后、维护成本高的问题。
适用场景
1
研发团队完成接口开发后，自动生成Swagger/OpenAPI文档初稿
2
技术文档工程师根据代码注释批量更新API参考手册
3
售前/交付团队快速生成对外集成说明和示例代码
4
运维团队为内部微服务自动生成调用说明与错误码表
核心Prompt（安装配置用）
你是一名资深技术文档工程师，专注于API文档与技术说明的自动生成。你的任务是基于用户提供的代码片段、接口定义（如OpenAPI/Swagger、GraphQL Schema、gRPC Proto）或数据库表结构，输出结构清晰、可直接发布的技术文档。 角色设定：你熟悉RESTful、GraphQL、gRPC等接口规范，了解企业级文档标准（如OpenAPI 3.0、Markdown、Confluence格式）。 任务描述： 1. 解析输入内容，提取接口路径、方法、请求参数、响应字段、错误码、鉴权方式。 2. 为每个接口生成：功能说明、请求示例（curl/JSON）、响应示例、字段说明表、注意事项。 3. 若输入不完整，主动列出缺失项并给出补充建议，不得编造字段。 输出格式： - 采用Markdown，包含标题层级、表格、代码块。 - 每个接口独立小节，字段表列：字段名、类型、必填、说明、示例值。 约束条件： - 不编造不存在的接口或参数。 - 保持术语与输入一致。 - 对敏感信息（如密钥）用占位符替换。 - 输出语言默认中文，可指定英文。 - 总长度按接口数量自适应，单接口说明不超过300字。
所需工具 / API对接
代码仓库API（GitLab/代码托管平台）、OpenAPI/Swagger解析器、Confluence/语雀API、Markdown渲染服务、企业LLM网关（如OpenAI/通义/文心）、CI/CD钩子（Jenkins/GitLab CI）。
安装部署步骤
11. 环境准备：准备一台4C8G Linux服务器，安装Docker 24+与Docker Compose，开放8080端口。
22. 安装依赖：执行 docker pull techdoc-agent:latest，并拉取 openapi-parser 与 markdown-render 镜像。
33. 配置参数：在 /opt/techdoc/config.yaml 中填写 repo_url、llm_api_key、output_format、auth_token。
44. 导入Prompt：将 core_prompt 写入 /opt/techdoc/prompts/techdoc.prompt，并设置只读权限。
55. 连接工具API：配置 GitLab Token、Confluence Space Key、LLM Endpoint，执行 docker compose up -d 启动服务。
66. 测试验证：运行 curl -X POST localhost:8080/generate -d '{"repo":"demo"}'，检查返回Markdown是否包含接口表。
77. 上线部署：将服务注册到内网DNS，配置CI钩子，在合并请求时自动触发文档生成并推送至Confluence。
配置参数
| 参数名 | 说明 | 默认值 |
|---|---|---|
repo_url |
代码仓库地址 | https://git.company.com/api |
llm_api_key |
大模型调用密钥 | sk-xxxx |
output_format |
输出格式，支持markdown/openapi | markdown |
auth_token |
服务访问令牌 | techdoc-2024 |
language |
文档语言 | zh-CN |
效果示例
输入：POST /v1/orders 接口定义，含请求体 {userId, amount}，响应 {orderId, status}。输出：生成Markdown文档，包含功能说明、请求示例curl、响应JSON、字段表（userId 字符串 必填 用户ID）、错误码401/500说明。用户可直接复制到Confluence发布。
常见问题
Q1：支持哪些代码语言？
A1：支持Java、Python、Go、Node.js的注释解析，以及OpenAPI/Swagger、Proto、GraphQL Schema。
Q2：生成的文档会泄露密钥吗？
A2：不会。Prompt中已约束对敏感信息用占位符替换，且可配置脱敏规则。
Q3：如何保证文档与代码同步？
A3：通过CI钩子在代码合并时自动触发，实时更新文档。
Q4：能否自定义文档模板？
A4：可以，在config.yaml中指定template路径，支持Jinja2模板。
Q5：是否支持私有化部署？
A5：支持，提供Docker镜像，可完全内网运行，数据不出域。
A1：支持Java、Python、Go、Node.js的注释解析，以及OpenAPI/Swagger、Proto、GraphQL Schema。
Q2：生成的文档会泄露密钥吗？
A2：不会。Prompt中已约束对敏感信息用占位符替换，且可配置脱敏规则。
Q3：如何保证文档与代码同步？
A3：通过CI钩子在代码合并时自动触发，实时更新文档。
Q4：能否自定义文档模板？
A4：可以，在config.yaml中指定template路径，支持Jinja2模板。
Q5：是否支持私有化部署？
A5：支持，提供Docker镜像，可完全内网运行，数据不出域。
企业落地建议
建议采用容器化私有部署，初期选择1-2个核心服务试点，成本约每月500-1000元（含LLM调用与服务器）。注意：需指定文档负责人审核生成内容，避免直接发布错误；建议与CI/CD集成，设置合并请求触发；对敏感接口增加人工复核环节。上线后每周收集研发反馈，迭代Prompt与模板。
需要我们帮你落地？
专业团队帮你从0到1部署企业AI Agent，含安装配置、定制开发、持续运营