Aliyun SLS Codex 插件

这是一个固定范围、只读的 Codex 插件，用于调查阿里云日志服务（SLS）中的应用故障。它通过 MCP 暴露日志搜索、上下文查询和连接检查，并附带一个有查询预算的调查 Skill。

固定资源如下，不能通过工具参数切换：

• 地域：cn-beijing
• Project：taient-rpa
• Logstore：node-rpa

架构与文件逻辑

• src/domain.ts：固定资源、查询上限和领域类型。
• src/config.ts：读取两个凭据环境变量；资源仍由代码固定。
• src/query.ts：限制时间范围并安全构造 SLS 查询。
• src/logs.ts：保留原始字段、规范化时间、排序和精确去重。
• src/errors.ts：把 SDK 错误映射为不泄密的公共错误。
• src/sls-client.ts：唯一的阿里云 SDK 边界，仅调用 GetLogsV2 和 GetLogStore。
• src/service.ts：组合搜索、上下文和连接检查策略。
• src/server.ts：声明并注册三个 MCP 工具及输入校验。
• src/index.ts：stdio 入口；stdout 仅承载 MCP 协议。
• skills/aliyun-sls-investigation/SKILL.md：最多三次日志调用的调查流程。

代码在固定资源、区间语义、转义、去重、错误脱敏和 MCP 边界处保留了简洁的中文注释；其余代码尽量由命名和类型表达。

前置条件与构建

需要 Node.js 22+、npm，以及对目标 Logstore 的只读 RAM 凭据。仓库忽略 dist/，所以在启用插件前必须先完成本地构建和检查：

npm install
npm run build
npm run check

发布或安装前建议执行完整预检：

npm run preflight

它依次运行类型检查、全部测试、MCP smoke test 和 git diff --check。smoke test 只列出工具，不访问 SLS。

最小 RAM 权限

建议为插件创建独立的只读 RAM 用户，并绑定如下策略：

{
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "log:GetLogStore",
        "log:GetLogStoreLogs"
      ],
      "Resource": "acs:log:cn-beijing:*:project/taient-rpa/logstore/node-rpa"
    }
  ]
}

资源 ARN 中的账户通配符 * 可能需要按 RAM 控制台要求替换为明确的阿里云账户 ID。不要授予写日志、修改索引或管理 Project 的权限。

在启动 Codex 前注入凭据；不要把真实值写入仓库文件：

export ALIBABA_CLOUD_ACCESS_KEY_ID="replace-with-read-only-ram-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="replace-with-read-only-ram-access-key-secret"

本地插件启用

本仓库是插件源码，不会自动修改个人 Codex 配置。个人 Marketplace 文件 ~/.agents/plugins/marketplace.json 中的 ./plugins/aliyun-sls-codex 会解析为 ~/plugins/aliyun-sls-codex。codex plugin add 只从 Marketplace 注册该位置，不会把任意仓库目录复制过去。

首次安装

仅当个人 Marketplace 中还没有该条目、且 ~/plugins/aliyun-sls-codex 不存在时，运行一次官方脚手架：

python3 ~/.codex/skills/.system/plugin-creator/scripts/create_basic_plugin.py \
  aliyun-sls-codex --with-skills --with-mcp --with-marketplace

不要在已有目录或已有条目上重复执行脚手架，也不要手工编辑 marketplace.json。先在源码仓库执行完整预检，再把源码同步到脚手架目录；将 <repo-root> 替换为本仓库绝对路径：

cd <repo-root>
npm run preflight
rsync -a --exclude .git --exclude node_modules --exclude dist --exclude .env \
  <repo-root>/ ~/plugins/aliyun-sls-codex/
cd ~/plugins/aliyun-sls-codex
npm install
npm run build
npm run check
npm run smoke:mcp

这里不使用 --delete，避免移除目标目录中用户自行保留的文件；.env 明确不复制。凭据本来就应来自环境变量，而不是插件文件。源码目录的 preflight 需要 Git 元数据；安装目录排除了 .git，因此在那里分别运行构建、检查和 smoke test。构建必须在安装后的 ~/plugins/aliyun-sls-codex 路径执行，因为 .mcp.json 从该目录启动 dist/src/index.js。

读取实际 Marketplace 名称，再安装插件：

python3 ~/.codex/skills/.system/plugin-creator/scripts/read_marketplace_name.py
codex plugin add aliyun-sls-codex@personal

第二条命令中的 personal 是默认个人 Marketplace 的字面示例；如果读取脚本输出其他名称，就将 personal 替换为该名称。安装完成后启动新的 Codex 任务，让新插件和 Skill 被重新发现。

更新已安装插件

更新时不要重新运行首次脚手架，也不要手工编辑 marketplace.json。先用上面的非破坏性 rsync 命令同步源码，然后：

cd ~/plugins/aliyun-sls-codex
npm install
npm run build
npm run check
npm run smoke:mcp
python3 ~/.codex/skills/.system/plugin-creator/scripts/update_plugin_cachebuster.py \
  ~/plugins/aliyun-sls-codex
python3 ~/.codex/skills/.system/plugin-creator/scripts/read_marketplace_name.py
codex plugin add aliyun-sls-codex@personal

若读取到的 Marketplace 名称不是 personal，同样替换命令后缀。重新安装后启动新的 Codex 任务；旧任务不会自动拾取更新后的插件内容。

若暂时不用 Marketplace，可把本仓库的 .mcp.json 作为 MCP 配置参考，并单独加载 SKILL.md。此回退方式仍要求工作目录指向已构建的仓库，且两个环境变量由启动 Codex 的环境提供。

使用

插件提供：

• search_logs：按关键词搜索；默认最近 12 小时、默认 AND、最多 1000 条、按时间倒序。
• get_context_logs：围绕锚点获取上下文；默认前后各 300 秒、最多 24 小时、最多 1000 条、按时间正序。
• check_connection：只检查固定 Logstore 的可读性，不查询日志内容。

搜索和上下文工具的完整 JSON 结果上限为 5 MiB。超过上限时返回 RESULT_TOO_LARGE，不会返回局部日志；请缩小时间范围或增加更具体的关键词。

先检查连接：

调用 check_connection，确认只读 SLS 连接可用。

示例查询：

使用 search_logs 搜索关键词 task-42 和 失败，默认使用 AND 查询最近 12 小时，并解释时间线。

调查 Skill 最多进行 3 次日志调用。首次命中后通常查询前后 5 分钟上下文；AND 无结果时不会静默改为 OR。输出包括摘要、时间线、根因与置信度、原始证据、其他解释、验证建议和查询记录，并区分事实与推断。

错误与排查

• AUTHENTICATION_FAILED：检查 AccessKey 是否正确、是否启用，以及签名时间是否正常。
• PERMISSION_DENIED：确认 RAM 策略包含 log:GetLogStore 和 log:GetLogStoreLogs，资源 ARN 与固定范围一致。
• RESOURCE_NOT_FOUND：确认 cn-beijing、taient-rpa、node-rpa 存在且拼写一致。
• INVALID_QUERY：缩短时间范围并检查关键词；查询跨度不得超过 24 小时。
• RATE_LIMITED：稍后重试，不要添加并发或自动重试风暴。
• NETWORK_ERROR：检查 DNS、代理和到阿里云 SLS 的网络连接。
• Node 18 可能启动部分依赖，但本项目只支持 Node.js 22+；看到 engine 警告时升级 Node 后重新 npm install 和构建。

数据安全

原始日志会进入当前 Codex 会话，而且不会脱敏。日志可能包含用户标识、请求参数或内部错误细节；仅查询调查所需的最小范围，并遵守公司数据政策、访问控制和保留要求。

不要提交 .env、真实 AccessKey、复制出的日志、故障导出或包含凭据的终端输出。不要把凭据放进 plugin.json、.mcp.json、Skill、提示词或聊天消息；.mcp.json 只声明环境变量名称。

提交前运行凭据扫描，并逐项确认命中的是占位符。示例：先搜索 LTAI 形式的 AccessKey ID，再搜索 ALIBABA_CLOUD_ACCESS_KEY_SECRET=；README 和 .env.example 中的 replace-with-... 占位符是预期命中，任何其他赋值都必须在提交前移除并轮换相关凭据。