bigwo/dev-assistant-mcp/dist/tools/docWrite.js

export const docWriteTool = {
    name: "doc_write",
    description: "为代码生成文档指引。分析代码结构，提取函数/类/接口信息，返回结构化的文档框架和编写指引。",
    inputSchema: {
        type: "object",
        properties: {
            code: {
                type: "string",
                description: "需要生成文档的代码",
            },
            doc_type: {
                type: "string",
                description: "文档类型",
                enum: ["readme", "api", "inline", "changelog", "jsdoc"],
            },
            language: {
                type: "string",
                description: "编程语言",
            },
            project_name: {
                type: "string",
                description: "项目名称（可选，用于 README）",
            },
            extra_info: {
                type: "string",
                description: "额外信息（可选，如版本号、变更内容等）",
            },
        },
        required: ["code", "doc_type", "language"],
    },
};
function extractSymbols(code, language) {
    const symbols = [];
    const lines = code.split("\n");
    for (let i = 0; i < lines.length; i++) {
        const line = lines[i].trim();
        const lineNum = i + 1;
        // 函数
        let m;
        if ((m = line.match(/(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(([^)]*)\)/))) {
            symbols.push({ type: "function", name: m[1], line: lineNum, signature: m[0] });
        }
        // 箭头函数 / const 赋值
        else if ((m = line.match(/(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s+)?\(?([^)]*)\)?\s*=>/))) {
            symbols.push({ type: "function", name: m[1], line: lineNum, signature: m[0] });
        }
        // 类
        else if ((m = line.match(/(?:export\s+)?class\s+(\w+)/))) {
            symbols.push({ type: "class", name: m[1], line: lineNum });
        }
        // 接口 (TS)
        else if ((m = line.match(/(?:export\s+)?interface\s+(\w+)/))) {
            symbols.push({ type: "interface", name: m[1], line: lineNum });
        }
        // 路由 (Express/FastAPI)
        else if ((m = line.match(/(?:router|app)\.(get|post|put|delete|patch)\s*\(\s*['"]([^'"]+)['"]/))) {
            symbols.push({ type: "route", name: `${m[1].toUpperCase()} ${m[2]}`, line: lineNum });
        }
        // Python 函数
        else if ((m = line.match(/(?:async\s+)?def\s+(\w+)\s*\(([^)]*)\)/))) {
            symbols.push({ type: "function", name: m[1], line: lineNum, signature: m[0] });
        }
        // Python 类
        else if ((m = line.match(/class\s+(\w+)(?:\(([^)]*)\))?:/))) {
            symbols.push({ type: "class", name: m[1], line: lineNum });
        }
        // export default
        else if ((m = line.match(/export\s+default\s+(\w+)/))) {
            symbols.push({ type: "export", name: m[1], line: lineNum });
        }
    }
    return symbols;
}
const docTypeInstructions = {
    readme: `请生成 README.md，包含以下章节：
# 项目名称
## 简介（一句话描述）
## 功能特性
## 快速开始（安装、配置、运行）
## API / 使用说明
## 项目结构
## License`,
    api: `请生成 API 文档，每个端点/函数包含：
- 描述
- 请求方法和路径（如适用）
- 参数（名称、类型、是否必填、描述）
- 返回值（类型、描述）
- 示例代码
- 错误码（如适用）`,
    inline: `请为代码添加内联注释：
- 每个函数/方法添加文档注释（JSDoc / docstring）
- 关键逻辑添加简洁的解释性注释
- 不要过度注释显而易见的代码
- 返回带注释的完整代码`,
    changelog: `请生成 CHANGELOG.md，遵循 Keep a Changelog 格式：
## [版本号] - 日期
### Added（新增）
### Changed（变更）
### Fixed（修复）
### Removed（移除）`,
    jsdoc: `请为所有函数/类/接口生成文档注释：
- @param 参数（类型、描述）
- @returns 返回值（类型、描述）
- @throws 可能的异常
- @example 使用示例
- 返回带完整文档注释的代码`,
};
export async function executeDocWrite(args) {
    const { code, doc_type, language, project_name, extra_info } = args;
    const symbols = extractSymbols(code, language);
    const lines = code.split("\n");
    const output = [
        `# 文档生成指引`,
        ``,
        `**文档类型**: ${doc_type} | **语言**: ${language}${project_name ? ` | **项目**: ${project_name}` : ""}`,
        ``,
    ];
    // 代码结构分析
    output.push(`## 代码结构分析`, ``);
    const functions = symbols.filter((s) => s.type === "function");
    const classes = symbols.filter((s) => s.type === "class");
    const interfaces = symbols.filter((s) => s.type === "interface");
    const routes = symbols.filter((s) => s.type === "route");
    if (functions.length > 0) {
        output.push(`### 函数 (${functions.length})`);
        for (const f of functions) {
            output.push(`- **${f.name}** (行 ${f.line})${f.signature ? `: \`${f.signature}\`` : ""}`);
        }
        output.push(``);
    }
    if (classes.length > 0) {
        output.push(`### 类 (${classes.length})`);
        for (const c of classes) {
            output.push(`- **${c.name}** (行 ${c.line})`);
        }
        output.push(``);
    }
    if (interfaces.length > 0) {
        output.push(`### 接口 (${interfaces.length})`);
        for (const i of interfaces) {
            output.push(`- **${i.name}** (行 ${i.line})`);
        }
        output.push(``);
    }
    if (routes.length > 0) {
        output.push(`### API 路由 (${routes.length})`);
        for (const r of routes) {
            output.push(`- **${r.name}** (行 ${r.line})`);
        }
        output.push(``);
    }
    if (symbols.length === 0) {
        output.push(`_未检测到标准的函数/类/接口/路由定义_`, ``);
    }
    // 统计
    output.push(`### 文件统计`, `- 总行数: ${lines.length}`, `- 代码符号: ${symbols.length} 个`, ``);
    // 文档编写指引
    const instruction = docTypeInstructions[doc_type] || docTypeInstructions.readme;
    output.push(`## 文档编写指引`, ``, instruction, ``);
    if (extra_info) {
        output.push(`## 补充信息`, extra_info, ``);
    }
    // 附上源代码
    output.push(`## 源代码`, "```" + language, code, "```");
    return output.join("\n");
}
//# sourceMappingURL=docWrite.js.map