CvLAC (MinCiencias)

cvlac-mcp

与 AI 助手对话即可更新 CvLAC，无需手动填写表单。

填写 MinCiencias 的 CvLAC 很耗时：每门课程、每个奖项或项目都要填写一份表单，而且机构和市镇目录中不一定能找到你要的内容。cvlac-mcp 让你的 AI 助手（例如 Claude）能够代你完成这些操作：你在聊天中告诉它要添加或更正什么，它便会使用你的账号登录 CvLAC、填写表单、保存并检查是否保存成功。

它在你的电脑上运行。你的凭据不会离开电脑，也不会经过任何中间服务器。

• 效果展示
• 能做什么，不能做什么
• 你需要准备什么
• 分步安装 — 约 15 分钟
• 可以提出哪些请求
• 如何保护你
• 常见问题
• 安全与隐私
• 更新或卸载
• 面向开发者

效果展示

对话大致如下：

你： 给我看看我在 CvLAC 上有哪些荣誉。

助手： 你有 6 项，其中包括“教学工作表彰”（2023 年）和“全国工程大会最佳报告”（2021 年）……

你： 添加这个：“教学工作荣誉奖”，北方大学，2024 年，国家级。

助手： 我还没有保存：这似乎和“教学工作表彰”（2023 年）相似，而这项已经在你的 CvLAC 上了。这是同一项荣誉，你想更正它，还是另一项荣誉，需要单独创建？

你： 是另一项，创建吧。

助手： 好了，CvLAC 已确认保存。它现在已出现在你的列表中：“教学工作荣誉奖”，2024 年，国家级。

助手不会删除任何内容，也不会在未事先询问你的情况下创建重复项。本例中的名称均为虚构。

可以做什么，不能做什么

可以读取、添加、修改和删除：

目前还不能：

• **通过 complete_product 上传证书：**该操作用于管理关键词、领域、合著者、荣誉，以及论文中关联的学生。书籍证书通过带有本地路径的 update_section 附加；它们不属于 complete_product 列表。
• **创建 CvLAC 目录中不存在的期刊、书籍、出版社、课程或领域。**如果目录返回多个选项，工具会显示这些选项供你选择。
• **使用外国国籍账户登录。**目前登录流程默认使用哥伦比亚国籍。
• **更改你的身份信息和地址，**也不能更改任何 GrupLAC 信息。
• **创建 CvLAC 尚未登记的补充培训课程。**CvLAC 搜索器只会显示该机构已有的课程，网站也不允许创建其他课程。

自动比较你的 CvLAC 与其他来源的内容（diff 工具）目前仅适用于具有特定结构的网页简历组合（详情）。如果你没有，也没关系：把简历文本粘贴到聊天中，或者口述给助手，助手会读取你的 CvLAC，并逐项添加缺少的内容；遇到任何相似项时都会先向你确认。

你需要准备什么

• **你的 CvLAC 用户信息：**名字、身份证号码和密码，也就是你登录网站时使用的信息。
• 一台安装了 Windows、macOS 或 Linux 的电脑。
• **Node.js 20 或更高版本，**这是一个让此工具运行的免费程序。第 1 步会介绍如何安装。
• **一款支持 MCP 服务的 AI 应用。**MCP 是这类应用连接此类工具所使用的标准。如果你还没有，可以从 Claude Desktop 开始：它最简单，也是本指南使用的应用。Claude Code、Cursor、VS Code、Windsurf、Zed 和 JetBrains 也适用（如何连接）。

你不需要会编程。你只需要在终端中复制并粘贴几条命令；本指南会准确告诉你要输入哪些命令。

分步安装

什么是终端？ 一个用于输入命令的窗口。 **在 Windows 上：**按 Windows 键，输入 PowerShell 并打开它。 **在 macOS 上：**按 Cmd + 空格，输入 Terminal 并打开它。 要粘贴命令：在 Windows 上右键单击，在 macOS 上按 Cmd + V。然后按 Enter。

步骤 1 · 安装 Node.js

从 nodejs.org 下载 LTS 版本，并使用默认勾选的选项安装。然后关闭并重新打开终端，检查：

node --version

应显示 v20 或更高版本（例如 v22.11.0）。

步骤 2 · 下载工具使用的浏览器

cvlac-mcp 使用自带的 Chromium 副本操作 CvLAC。Chromium 是一种无窗口运行的浏览器。只需下载一次（约 150 MB）：

npx -y cvlac-mcp@1 install-browser

最后应显示 Chromium 已安装。

$env:NODE_OPTIONS="--use-system-ca"; npx -y cvlac-mcp@1 install-browser   # Windows (PowerShell)

NODE_OPTIONS=--use-system-ca npx -y cvlac-mcp@1 install-browser           # macOS / Linux

步骤 3 · 保存你的登录信息

请将登录信息保存在用户文件夹中的另一个文本文件里，并确保只有你能读取。

Windows — 在 PowerShell 中执行：

mkdir "$HOME\.config\cvlac-mcp" -Force
notepad "$HOME\.config\cvlac-mcp\.env"

记事本会询问是否创建文件，请回答是。粘贴以下三行，将引号内的内容替换为你的信息，保留单引号，然后按 Ctrl + S 保存：

CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'

关闭记事本，并将文件设为只有你的用户可以读取：

icacls "$HOME\.config\cvlac-mcp\.env" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"

macOS / Linux — 粘贴前先更改这三个值，保留单引号：

mkdir -p ~/.config/cvlac-mcp
cat > ~/.config/cvlac-mcp/.env <<'EOF'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
EOF
chmod 600 ~/.config/cvlac-mcp/.env

• CVLAC_NOMBRE 是你在 CvLAC 注册时填写的名字，请保留重音符号和 ñ。
• 单引号很重要：如果不加引号，密码中的 # 及其后面的内容会被截断。
• 如果桌面或文档文件夹正在与 OneDrive 或 Google Drive 同步，请勿将此文件保存在其中。上面的文件夹不会同步。

$contenido = @'
CVLAC_NOMBRE='Tu primer nombre'
CVLAC_CEDULA='1234567890'
CVLAC_PASSWORD='tu clave'
'@
[IO.File]::WriteAllText("$HOME\.config\cvlac-mcp\.env", $contenido)

1. 打开 Claude Desktop，前往 设置 → 开发者 → 编辑配置（英文界面为： Settings → Developer → Edit Config）。系统会打开包含 claude_desktop_config.json 文件的文件夹：用记事本或 TextEdit 打开该文件。
2. 粘贴适用于你系统的代码块，将 TU_USUARIO 替换为你的电脑用户名。要查看用户名： 在 PowerShell 中运行 echo $env:USERNAME，或在 macOS 终端中运行 whoami。

Windows：

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "C:\\Users\\TU_USUARIO\\.config\\cvlac-mcp\\.env"
      }
    }
  }
}

macOS（在 Linux 中，路径以 /home/ 开头，而不是 /Users/）：

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "npx",
      "args": ["-y", "cvlac-mcp@1"],
      "env": {
        "CVLAC_ENV_FILE": "/Users/TU_USUARIO/.config/cvlac-mcp/.env"
      }
    }
  }
}

3. 保存并完全退出 Claude Desktop；仅关闭窗口还不够。在 Windows 中，右键单击时钟旁边的图标 → 退出。在 macOS 中，按 Cmd + Q。然后重新打开应用。

常见问题：

• 如果文件中已有内容，请勿替换：将 "cvlac-mcp": {...} 添加到现有的 "mcpServers" 中，并用逗号隔开。
• 在 Windows 中，路径中的反斜杠必须写成双反斜杠（\\），因为该文件是 JSON。cmd /c 必须放在前面，因为在 Windows 中，npx 不是程序，而是脚本。
• CVLAC_ENV_FILE 是必需的：它用于告诉 cvlac-mcp 第 3 步的文件所在位置。

步骤 5 · 测试

在 Claude Desktop 中新建一个聊天，然后输入：

1. “登录 CvLAC”——它应回复已登录。
2. “显示我在 CvLAC 上的学历信息”——它应列出你已有的信息。

如果两项都正常，就设置完成了。首次连接可能需要约 15 秒，因为需要下载软件包；如果显示未连接，请稍等片刻，然后重启 Claude Desktop。

遇到问题？→ 常见问题。

其他 AI 应用

所有应用的配置都与步骤 4 相同；只需更改粘贴配置的位置。

Claude Code：

# macOS / Linux
claude mcp add cvlac-mcp --scope user -e CVLAC_ENV_FILE=$HOME/.config/cvlac-mcp/.env -- npx -y cvlac-mcp@1

# Windows, desde Git Bash
MSYS_NO_PATHCONV=1 claude mcp add cvlac-mcp --scope user -e 'CVLAC_ENV_FILE=C:\Users\TU_USUARIO\.config\cvlac-mcp\.env' -- cmd /c npx -y cvlac-mcp@1

在 Git Bash 中，如果不设置 MSYS_NO_PATHCONV=1，/c 会被转换为 C:/，导致服务无法连接。从 PowerShell 执行该命令会报错 unknown option '-y'，因为 PowerShell 会吞掉 --：请使用 Git Bash、 在参数前加上 --%，或粘贴 Windows 的 JSON 并运行 claude mcp add-json。

可以让它做什么

用西班牙语自然地交流。以下是一些示例：

建议：

• 先查看，再更改。“告诉我你会添加什么，但不要保存任何内容”是不错的起点。
• **提供完整信息：**日期、机构、小时数、范围（国内或国际）。如果缺少 CvLAC 要求的数据，助手会提醒你，而不是凭空编造。
• 在 CvLAC 中检查写入的内容。履历中的信息由你负责；助手虽然会核实每次保存，但仍可能误解你的要求。

如何保护你

CvLAC 没有撤销按钮，因此 cvlac-mcp 宁可先询问，也不愿出错：

• **未经询问，不会创建重复项。**如果你要添加的内容与已有内容相似，它不会写入任何内容，而是向你展示相似项。
• **不会立即删除。**任何删除操作都需要再次确认，包括移除学术网络或研究领域。
• **不会替你选择。**如果机构名称在 CvLAC 目录中匹配到多个结果——其中有 6 所“安第斯大学”——它会向你展示这些选项。
• **不会编造数据。**如果缺少数据，它会提醒你，而不是随便填入听起来合理的内容。
• 核实结果。它不会仅仅因为已发送表单就认为内容已保存：它会查看 CvLAC 的响应；如果仍有疑问，就会重新读取记录。如果 CvLAC 在保存过程中途发生故障，它会告诉你无法确认保存结果，让你先检查，再决定是否重试。
• **说明失败原因。**如果 CvLAC 拒绝表单，它会告诉你是哪个字段出了问题，以及原因。
• **保护你的账户。**如果 CvLAC 拒绝你的密码，它不会再次尝试，以免导致你的账户被锁定。此外，它还会控制访问 CvLAC 的频率，避免使其过载。

常见问题

还有其他问题？请提交一个 issue，但不要附上你的个人数据，也不要附上包含个人信息的截图。

安全与隐私

具体来说，你的数据会如何处理：

• 你的凭据不会离开你的电脑。 它们存放在第 3 步的文件中。cvlac-mcp 会在 启动时读取这些凭据，并且只会将其填入 scienti.minciencias.gov.co 的登录表单。
• 没有中间服务器、账户、遥测或分析。 cvlac-mcp 作为程序在你的 电脑上运行，并直接与 AI 应用通信。只有在你请求只读 DOI 查询时，它才会连接到 CvLAC、你配置的个人资料库和 api.crossref.org。
• 你的 AI 助手确实能看到你的简历。 但看不到你的凭据——cvlac-mcp 不会返回凭据；它能看到从 CvLAC 读取的内容，因为这些内容会发送到聊天中。如果你的简历包含敏感数据，选择应用时请考虑这一点。
• 会话的安全性不亚于你的密码。 为避免每一步都要求输入密码，cvlac-mcp 会将会话保存在用户文件夹中的 .cvlac-session.json。只要会话仍然有效，任何复制了该文件的人都能进入你的 CvLAC 并进行修改，无需你的密码。在 macOS 和 Linux 上，该文件仅对你可读；在 Windows 上，它会继承用户文件夹的权限。要手动限制权限： chmod 600 ~/.cvlac-session.json（macOS/Linux）或 icacls "$HOME\.cvlac-session.json" /inheritance:r /grant:r "${env:USERNAME}:(R,W)"（Windows）。
• 不要将数据文件或会话文件放在同步文件夹中（OneDrive、Google Drive、Dropbox）。本指南中的路径不在此类文件夹中。
• **要结束会话，**请删除 .cvlac-session.json。下次运行时，cvlac-mcp 会重新登录。
• 日志不会显示机密信息。 即使启用详细模式进行调试，密码、身份证号和 Cookie 也会显示为 ***。如果配置了 CVLAC_LOG_FILE，该文件会以仅限你的用户访问的权限（0600）创建。
• 屏幕截图可能包含个人数据。 分享前请先检查。
• 经过身份验证的浏览仅限 CvLAC。 inspect_form、screenshot 和内部链接只接受 scienti.minciencias.gov.co 上的 HTTPS；file://、其他主机以及删除／保存等操作链接都会被拒绝。
• 浏览器默认保留 Chromium 沙箱。 只有无法以这种方式启动浏览器的环境才应明确设置 CVLAC_NO_SANDBOX=true，并了解这会带来额外风险。
• **如果怀疑信息已泄露，**请更改 CvLAC 密码并删除会话文件。

负责任地使用

• 此工具使用你自己的账户和自己的数据，自动操作哥伦比亚政府网站。它不会绕过身份验证、访问他人的简历，也不会使用任何隐藏 API：它做的和你在浏览器中的操作一样，只是更快。
• 使用前请查看 ScienTI/MinCiencias 的使用条款以及所在机构的政策。
• 始终由人工监督。 应先查看更改，再决定是否应用；不要让它在无人查看的情况下运行，也不要将其设置为自动运行。
• 不要同时对多个账户运行，也不要提高请求频率。
• 简历中的内容由你负责。 这是一份会影响征集和评估结果的声明：请在 CvLAC 中核实已写入的内容。

独立项目。 本项目与 MinCiencias 无关联，也未获得该机构背书。它不复制该机构的徽标或视觉形象：上方的符号是原创设计——由环绕在汇聚线条中的 JSON-RPC 花括号 { } 组成；「CvLAC」「ScienTI」和「MinCiencias」仅用于标识此服务所连接的系统。

更新或卸载

• 更新： 无需执行任何操作。使用 cvlac-mcp@1 时，每次打开 AI 应用都会使用最新的 1.x 版本。如果以后发布 2.x 版本，请在配置中将 @1 改为 @2（请先阅读 ROADMAP 了解变更内容）。
• 查看当前版本： npx -y cvlac-mcp@1 --version。
• 卸载： 从应用配置中移除 "cvlac-mcp" 配置块，并删除用户文件夹中的 .config/cvlac-mcp 文件夹和 .cvlac-session.json 文件。

面向开发者

以下内容适用于希望审查代码、贡献代码、直接使用 MCP 工具或将 CvLAC 与网页作品集进行比较的开发者。

基于 TypeScript + Playwright 的 MCP（stdio）服务，采用严格 ESM，使用 Vitest 在 Linux、Windows 和 macOS 上进行测试。已验证的内容、尚待完成的事项和已知限制请参阅 ROADMAP。

• 从源代码安装
• 高级配置
• 与作品集比较（diff 和 sync）
• MCP 工具参考
• 环境变量
• 架构
• 测试与构建
• 开发问题
• 状态与路线图

从源代码安装

适用于开发、贡献或审查代码的情况。如果你只想使用服务，逐步安装指南更简短。请按顺序执行步骤；每一步都包含验证，以免在环境有问题时继续操作。

步骤 0 - 前置条件（所有平台）

需要 Node.js 20 或更高版本、npm 10+ 和 git。

验证（bash、zsh 或 PowerShell 均适用）：

node --version   # debe mostrar v20.x o superior
npm --version    # debe mostrar 10.x o superior
git --version

步骤 1 - 克隆仓库

Linux / macOS（bash 或 zsh）：

cd ~/dev            # o la carpeta que prefieras
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

Windows（PowerShell）：

cd $HOME\dev        # crea la carpeta antes si no existe: mkdir $HOME\dev
git clone https://github.com/stivenson/cvlac-mcp.git
cd cvlac-mcp

步骤 2 - 安装依赖并编译

三个平台的操作相同：

npm install
npm run build

验证： 编译后的入口文件 dist/index.js 应已存在。

# Linux / macOS
ls dist/index.js

# Windows (PowerShell)
Test-Path dist\index.js   # debe imprimir True

步骤 3 - 安装 Playwright 浏览器

该服务使用无头 Chromium 自动操作 CvLAC。请下载与项目所用 Playwright 版本相对应的构建版本：

node dist/index.js install-browser

在 Linux 上，如果缺少系统库，也请安装原生依赖：

npx playwright install-deps chromium   # requiere sudo en algunas distros

步骤 4 - 配置环境变量（.env）

复制模板并编辑值：

Linux / macOS：

cp .env.example .env

Windows（PowerShell）：

Copy-Item .env.example .env

使用你的数据编辑 .env：

CVLAC_NOMBRE='TuNombre'
CVLAC_CEDULA='TuDocumento'
CVLAC_PASSWORD='TuPassword'
PORTFOLIO_URL='https://tu-usuario.github.io'
# Opcional: por defecto, .cvlac-session.json en tu carpeta de usuario
# CVLAC_SESSION_PATH='/ruta/a/tu/.cvlac-session.json'

限制文件权限（Linux/macOS）：

chmod 600 .env

在 Windows 上，chmod 的对应命令是 icacls .env /inheritance:r /grant:r "${env:USERNAME}:(R,W)"。

按平台设置 CVLAC_SESSION_PATH（示例，如需更改）：

• Linux： /home/TU_USUARIO/.cvlac-session.json
• macOS： /Users/TU_USUARIO/.cvlac-session.json
• Windows： C:\\Users\\TU_USUARIO\\.cvlac-session.json

步骤 4b - 配置默认值（cvlac.config.json）

CvLAC 的多个表单要求填写你的作品集里没有的字段（市镇、每周课时、语言）。在此处统一声明：

cp cvlac.config.example.json cvlac.config.json

{
  "portfolioUrl": "https://tu-usuario.github.io",
  "defaults": {
    "municipio": { "nombre": "Bogotá", "codigoDane": "11001" },
    "institucionFallback": "Universidad Nacional de Colombia",
    "horasSemanales": 1,
    "idioma": "ES",
    "pais": "CO"
  }
}

所有字段均为可选。如果缺少某个值，该字段会留空，响应中会附带警告——服务不会为你的简历编造数据。

步骤 4c - 整理项目、软件和活动（data/portfolio-extra.json）

这三个部分无法从作品集中读取：它们需要只有 CvLAC 才有的元数据（项目类型、DANE 代码、枚举代码）。需要手动维护：

cp data/portfolio-extra.example.json data/portfolio-extra.json

文件在加载时会进行验证；如果某个条目格式不正确，服务会报告问题并继续处理其他部分。

步骤 5 - 在你的应用中注册 MCP

与分步安装相同，只需将 npx 替换为 node，并将路径改为你的 dist/index.js。无需设置 CVLAC_ENV_FILE：克隆后，服务会读取仓库根目录下的 .env 文件。

{
  "mcpServers": {
    "cvlac-mcp": {
      "command": "node",
      "args": ["/home/TU_USUARIO/dev/cvlac-mcp/dist/index.js"]
    }
  }
}

• macOS： "/Users/TU_USUARIO/dev/cvlac-mcp/dist/index.js"
• Windows： "C:\\Users\\TU_USUARIO\\dev\\cvlac-mcp\\dist\\index.js"（JSON 中使用双反斜杠；此处无需 cmd /c， 因为 node 是可执行文件）
• Claude Code： claude mcp add cvlac-mcp --scope user -- node /ruta/a/cvlac-mcp/dist/index.js
• 各应用中 JSON 的位置：其他 AI 应用。

**只将凭据保存在 .env 中。**应用配置文件通常没有严格的权限限制，或者会在多台机器间同步。即使你仍将凭据放在 env 块中，它们也会优先于 .env。

步骤 6 - 验证安装

1. 构建和测试均通过：

   npm run build
   npm test
   

2. 启动服务（基本检查；服务会通过 stdio 等待，请用 Ctrl+C 关闭）：

   node dist/index.js
   

3. **在你的编辑器中：**重启编辑器（Claude Desktop 需要完全退出），并确认 cvlac-mcp 已启用且列出了工具——在 Cursor 中查看 Settings → MCP，在 Claude Code 中运行 claude mcp list 或 /mcp，或查看 VS Code 中 Agent 聊天的工具选择器。

4. 在编辑器的聊天窗口中按以下顺序进行基本功能测试：

   • login（应完成身份验证并持久化会话）
   • 使用 section: "formacion" 调用 read_cvlac（应返回 CvLAC 中已有的内容）
   • 如果配置了作品集：先调用 read_portfolio，再调用 diff

如果响应没有错误，则 MCP 已正确安装和配置。

高级配置

使用服务不需要进行以下配置。通过 npx 安装时，每个文件的路径都通过应用配置中同一 env 块内的变量指定，与 CVLAC_ENV_FILE 并列；克隆后，则从仓库根目录读取。

建议：将它们保存在 .env 旁边的 ~/.config/cvlac-mcp/ 中。如果缺少默认值，该字段会留空，响应中会附带警告：服务绝不会为简历编造数据。

与作品集比较（diff 和 sync）

diff 会将 CvLAC 与网页作品集进行比较，并将每个条目分为四组：缺失、 待更新、相似（已有类似内容：由人工决定）和最新。sync 默认会预览；只有在调用时设置 dry_run: false，才会应用缺失项和待更新项，并且永远不会应用相似项。

重要限制：read_portfolio 是为特定网站构建的——一个带有 #/resume 路径、包含经历、教育和课程标签页，以及“杰出成就”版块的 React 应用。如果找不到这种结构，它会返回空列表，并在日志中发出警告。项目、软件和活动并非来自网站，而是来自 portfolio-extra.json。以下内容也不会纳入 diff：专业经历（公司名称差异太大）、语言、研究方向及其他工作。

将数据源与引擎分离——让 diff 接受标准化的简历 JSON，无论它来自 PDF、ORCID 还是口述——已列入 ROADMAP。

建议的流程：

1. login
2. 使用 dry_run: true 调用 sync
3. 与人工一起检查报告：缺失项、待更新项、相似项和最新项
4. 逐一处理相似项——对现有条目使用 update，或使用 add 并设置 confirm_duplicate:true
5. 应用其余更改：使用 dry_run: false 调用 sync，或逐项使用 update_section，并检查 warnings
6. 使用受影响版块的 read_cvlac 或 read_cvlac_detail 进行验证

read_portfolio ─┐
                ├─► diff ─► sync (dry_run → apply) ─► update_section (add / update / delete)
read_cvlac ─────┘

如果你使用 Claude Code，客户端工作区中的 cvlac-sync skill 封装了这一流程。

MCP 工具参考

工具失败时会返回 isError: true。needs_confirmation 和 unverified 不属于错误：它们要求人工决定或检查。

complete_product

label 用于查找现有产品，操作会接收一个或多个完整列表：

• keywords：按顺序排列的关键词。
• areas：按名称或 CvLAC 代码排列的知识领域。
• coauthors：从先前登记的个人资料目录中按顺序排列的合著者姓名； 简历所有者会自动保留。
• recognitions：从 CvLAC 简历中已登记的表彰中按顺序排列的表彰标题。
• students：仅适用于 tesis；对象为 {name, participation, person_id?}。participation 接受 TUT、ASE、COT、ORI 或对应标签（Tutor、Asesor、Cotutor、Orientado）。如果省略， 则使用 ORI。

这些列表会替换已存储的内容。如果操作会移除现有值，则会先返回 needs_confirmation，并附带 removed；使用 confirm_delete:true 重复操作。无法解析或对应多个个人资料的人会出现在 choices 中，且不会写入任何内容。

update_section

分区：formacion、formacionComple、experiencia、cursos、reconocimientos、proyectos、 software、eventos、idiomas、lineas、demasTrabajos、articulos、libros、capitulos、 tesis、jurados、informesTecnicos、innovacionesProceso、productosTecnologicos、consultorias、 prototipos。每个分区的 data 架构见 src/schemas.ts；格式错误的字段会在打开浏览器前指出名称并拒绝。

更多详情：

• 如果 update 未能更改表单中的任何字段，则不会提交：会返回带有警告的 failed。
• 精确匹配的机构会自动解析。目录中存在精确重复项——有 6 个“Universidad de los Andes”——因此仅凭名称有时不足以确定机构。
• formacionComple 使用与 formacion 相同的表单，但采用另一套级别目录（Y 其他、8 延伸教育、F 短期课程、E MBA），并包含 startMonth。只有 CvLAC 已为该机构和级别登记的学术项目才能执行 add。
• libros：certificateCLCDO 和 certificateCLRI 是指向实际表单中两份 PDF 证书的可选本地路径。提交前会验证 %PDF- 签名、扩展名、文件是否存在以及 2 MiB 的大小上限。CvLAC 不会将这些文件作为表单值返回，因此仅编辑证书可能会返回 unverified；请先确认档案再重试。
• demasTrabajos：name、year、month、medio（纸质、互联网或其他）、finalidad，以及可选的 idioma 和 ciudad。表单默认预选 Enero 和 Papel：如果缺少 month 或 medio，则会保存这些默认值并发出提醒。
• idiomas：language（西班牙语名称或 2 个字母的 ISO 代码）以及 read/write/speak/listen 级别；也可以使用 level 一次设置所有级别：Deficiente、Aceptable 或 Bueno。
• lineas：name、active（默认为 true，并会发出提醒）和 objective。
• experiencia：CvLAC 表单没有职位字段；如果条目包含 role，系统会提示该字段未写入。

update_profile

• description 会替换个人简介文本。不能为空：CvLAC 将其标记为必填项（最多 3950 个字符）。
• networks 会与已保存的内容合并：CvLAC 表单会重写整张表，因此工具会先读取现有内容，再一并提交。url:null 会移除一个网络，并要求设置 confirm_delete:true。接受的网络包括：google_scholar、researchgate、ssr、ssrn、academia_edu、mendeley、linkedin、 repositorios_disciplinares、repositorios_institucionales、researcher_id、scopus_author_id、 orcid 和 otro（在 label 中填写其名称）。
• areas 是完整的研究领域列表，顺序不可更改——第一项为主要领域——可使用名称或 CvLAC 代码（0-1B01）。它会替换已保存的内容：遗漏任何一项都意味着删除该项，并要求设置 confirm_delete:true。目录包含 3 个级别的 267 个领域；如果名称存在歧义，会在 choices 中返回选项，而不会自行猜测。

环境变量

在 .env 中定义，或在应用配置的 env 区块中定义；后者优先级更高。

启动时，服务会在 stderr 中写明读取的 .env 文件： env file: <ruta> (found, 3 vars)、NOT FOUND，或者在文件不是 UTF-8 编码时显示 read as utf16le / read as latin1。

请求节奏

请求过于密集时，CvLAC 会开始返回 5xx。服务会在每次导航之间留出间隔，采用退避策略重试；如果网站连续拒绝多个请求，服务会停止重试，直到冷却时间结束。默认值适用于正常的 sync；如果连续遇到 503，请调高这些值：

架构

src/
├── index.ts                  # Entry point: subcomandos, carga del .env, stdio transport
├── cli.ts                    # install-browser, --version, --help
├── env.ts                    # Ubicación y lectura del .env (UTF-8, UTF-16 o ANSI)
├── server.ts                 # Registro de tools MCP, isError
├── types.ts                  # Tipos de portfolio/CvLAC/diff/update
├── schemas.ts                # Un schema zod por sección
├── config.ts                 # cvlac.config.json
├── logger.ts                 # Logs a stderr, con secretos ocultos
├── diff.ts                   # Motor de comparación (normalize + nameMatches)
├── browser/
│   ├── session.ts            # Login, sesión persistente, Playwright context
│   ├── navigation.ts         # URLs de listas y formularios CvLAC
│   ├── navigate.ts           # Toda navegación: ritmo, reintentos, cortes
│   ├── pacing.ts             # Espaciado de peticiones y backoff
│   ├── availability.ts       # Distingue "CvLAC caído" de un error propio
│   └── catalogue.ts          # Catálogos de CvLAC (municipios, instituciones)
├── tools/
│   ├── login.ts  read-cvlac.ts  read-cvlac-detail.ts  read-portfolio.ts  diff.ts  sync.ts
│   ├── update-section.ts     # add/update/delete por sección
│   ├── write-verdict.ts      # ¿Se guardó? saved / rejected / unverified
│   ├── profile.ts            # Perfil y redes académicas
│   ├── areas.ts              # Áreas de actuación
│   └── screenshot.ts
└── extractors/
    ├── portfolio.ts          # Renderiza el portafolio + portfolio-extra.json
    └── cvlac/                # Un extractor por sección, sobre rows.ts

已导致过问题的设计决策和 CvLAC 的注意事项见 CLAUDE.md；经实际验证的 URL、列和字段名称见 docs/cvlac-findings.md。

测试与构建

npm test          # suite completa: sin red, sin credenciales, sin CvLAC
npm run build     # compila src/ a dist/, que es lo que ejecuta la app
npm run dev       # corre src/ con tsx, sin compilar
npm run test:watch

测试涵盖提取器（使用匿名化 HTML fixture）、diff 引擎、schemas、配置和 .env 加载、日志中的密钥脱敏、sync 报告、MCP 边界以及详细信息卡片读取。fixture 特意使用虚构数据：如果你为新测试捕获了真实 HTML，请在提交前将其匿名化。

smoke 工作流在 Linux、Windows 和 macOS 上运行：编译、运行测试、使用 install-browser 安装 Chromium，并执行 scripts/smoke.mjs，以检查启动、MCP 协议、已注册的工具、不包含凭据的消息以及浏览器是否能打开。另一个 job 会在 PowerShell 5.1 和 7 中以三种常见方式写入 .env，并验证服务能否读取。手动触发时，它还会测试从 npm 安装后的软件包。

实时测试套件（可选，会写入你的真实 CvLAC）

CVLAC_E2E=1 npm run test:e2e:live                      # las secciones con lista
CVLAC_E2E=1 npm run test:e2e:live -- --sections=cursos  # solo una
CVLAC_E2E=1 npm run test:e2e:live -- --sections=perfil  # perfil y redes

针对你的真实账户，按板块遍历完整 CRUD 流程：列表 → add → 列表 → read_cvlac_detail → 重复执行 add（应返回 needs_confirmation）→ update → 查看详情以确认更改 → delete → 最终列表。它创建的每个条目都带有前缀 ZZ PRUEBA MCP，并且总会尝试删除这些条目；如果有任何条目残留，会在最后报告，供你手动删除。--sections=perfil 会创建快照，在无人使用的网络上写入数据，编辑并删除它，然后恢复原有内容。

这是唯一会操作真实数据的测试套件，因此需要 CVLAC_E2E=1，且不会随 npm test 运行。它与 dist/index.js 通信，因此要在 npm run build 之后运行。报告保存在 tests/e2e/report-<fecha>.json（已加入 gitignore）。

开发问题

• **应用使用的是旧版代码：**修改 src/ 后运行 npm run build。应用运行的是 dist/index.js，而不是 src/index.ts。
• **应用中没有显示（克隆安装）：**检查 args 中指向 dist/index.js 的绝对路径；在 Windows 上使用双反斜杠，然后重启应用。
• **表单未保存某个字段：**CvLAC 的多个字段是 readonly，由 JS 填写。使用 inspect_form 查看实际名称，使用 CVLAC_HEADLESS=false 查看浏览器，并使用 CVLAC_LOG_LEVEL=debug 查看每个字段的详细信息。
• diff 中误报缺失项：nameMatches() 会规范化重音符号和后缀（(en línea)、 - Aprobado ...）；经验部分有意不纳入 diff。

状态与路线图

原有的 11 个板块、个人资料、学术网络和研究领域均支持读取和写入（add/update/delete），并已针对真实 CvLAC 验证 CRUD。文章、图书、章节、论文、评审和技术成果板块也已实现。文章的完整 CRUD 已在真实环境中验证；技术报告和咨询项目已验证新增、列表、详情、重复项拦截和删除。某些编辑字段取决于真实表单的变化，相关情况已记录在路线图中。diff 和重复项拦截也通过 JMesa 分页覆盖完整列表。

complete_product 已可为现有成果补全关键词、研究领域、共同作者和认可信息，并关联参与论文项目的学生。图书在 update_section 中也支持本地路径 certificateCLCDO 和 certificateCLRI；每个 PDF 最大为 2 MiB。该操作已通过临时记录完成端到端验证。

完整详情、已知限制及后续计划： 路线图。