一键返回本 MCP 进程的运行时结构化状态，用于用户自检与问题上报。适用场景：用户反馈「MCP 不工作 / 对话没抓到 / 数据没上报 / 上报失败 / 后台看不到我的数据 / 帮我看下 MCP 状态」时，优先调用本工具，不要靠翻日志文件拼接。返回 JSON 包含：版本、PID、启动时长、主/从实例、实例安全上限与槽位、token 是否有效、chatGrab 依赖四元组、dbEngine、上报统计（成功数/失败数/上次成功时间/上次失败时间/最近错误）、失败队列长度、Cursor CLI、Claude Code 与 Codex 子链路统计。不暴露 TOKEN 本身。

检测本 MCP 进程与 ACW 云端的连通性及 ACW_TOKEN 是否有效。当用户问「acw-tools 连上没有」「MCP 是否正常」「Token 对不对」「安装后不能用」时应优先调用；不要用读本地 mcp.json 代替本工具判断云端状态。

检查本地技能是否需要更新。当用户说"检查技能更新"、"技能需要更新吗"、"有没有新版本"时，应该调用此工具。

原理：下载远程技能包到系统临时目录，解压后逐文件与本地文件做内容对比，返回详细的文件差异（新增、修改、删除）。
检查完成后临时文件会自动清理。如果有差异，你必须先向用户展示差异详情并询问是否覆盖更新，得到用户确认后再使用 download_skill 工具执行更新。

特性：
- 支持检查单个技能
- 支持检查工作空间下所有技能
- 支持检查用户目录下所有技能
- 支持检查所有技能（工作空间 + 用户目录）
- 通过文件内容二进制对比，精确检测差异

使用场景：
- "检查 code-review 技能有没有更新"
- "看看工作空间的技能需要更新吗"
- "检查所有技能的更新状态"

检查范围：
- "single": 检查单个技能（需要指定 skillName）
- "workspace": 检查当前工作空间下所有技能
- "user": 检查用户目录下所有技能
- "all": 检查所有技能（工作空间 + 用户目录）

当 scope 为 single 时，指定要检查的技能名称

工作空间路径（可选）。用于查找工作空间下的技能。建议使用当前打开的工作区路径。

删除个人知识库中的单个文件，并同步移除索引和存储中的对应内容。

调用条件：用户明确要求删除知识库中的某一篇文档/文件时调用。必须同时提供知识库标识名和文件路径；文件路径应使用知识库中的相对路径（例如 \"docs/guide.md\"）。

注意：这是不可逆操作。删除成功后会从知识库索引、对象存储或 GitLab 源仓库中移除该文件；如需替换文件内容，请使用 upload_knowledge，并根据需求选择 overwrite（整库覆盖）或 incremental（同名文件覆盖、其他文件保留）模式。

知识库中的文件相对路径，例如 docs/guide.md

知识库唯一标识（小写字母、数字和连字符）

将知识库的原始文档下载到本地 Agent 知识库目录。以知识库名称命名文件夹，保留原始目录结构。

当用户提到以下意图时应调用此工具：
- "下载知识库"、"把知识库拉到本地"、"导出知识库"
- "下载 xxx 知识库到本地"
- "把知识库下载到工作区"

下载目录规则：
- Cursor project 写入 {targetDirectory}/.cursor/knowledge/{knowledgeName}/
- Codex project 写入 {targetDirectory}/.agents/knowledge/{knowledgeName}/
- Cursor user 写入 ~/.cursor/knowledge/{knowledgeName}/
- Codex user 写入 $CODEX_HOME/knowledge/{knowledgeName}/（未设置时 ~/.codex/knowledge/{knowledgeName}/）
- 保留知识库中的原始目录结构
- 已存在同名文件会被覆盖

重要规则：
- agent: "auto" 默认写入工作区 .agents/knowledge/；需要 .cursor/knowledge/ 时请显式传 agent: "cursor"
- 下载完成后校验目标目录必须是 .agents/knowledge/ 或 $CODEX_HOME/knowledge/，不得是 .cursor/knowledge/

如果不确定有哪些知识库可以下载，先不传 knowledgeName，工具会返回可下载的知识库列表。

安装目标 Agent（可选）：
- "auto"（默认）：项目级写入 {工作区}/.agents/knowledge/
- "cursor"：强制写入 {工作区}/.cursor/knowledge/
- "codex"：与 auto 相同，写入 {工作区}/.agents/knowledge/

知识库标识名。不传则返回可下载的知识库列表，由用户选择后再次调用

安装范围（可选）：
- "project"（默认）：Cursor 安装到 {工作区}/.cursor/knowledge/，Codex 安装到 {工作区}/.agents/knowledge/
- "user"：Cursor 安装到 ~/.cursor/knowledge/，Codex 安装到 $CODEX_HOME/knowledge/（未设置时 ~/.codex/knowledge/）
如果不指定，默认为 project。当指定 scope 为 user 时，targetDirectory 参数会被忽略。

目标工作区目录的绝对路径。**强烈建议明确指定此参数**，使用当前打开的工作区路径。Cursor project 下载到 {targetDirectory}/.cursor/knowledge/{knowledgeName}/；Codex project 下载到 {targetDirectory}/.agents/knowledge/{knowledgeName}/。Codex / CodeX 会话里必须同时显式传 agent: "codex"。

仅用于下载 ACW 规则（Rule）到本地 Agent 规则目录。Cursor project 写入 .cursor/rules/，Codex project 写入 .agents/rules/；用户级目录分别写入 ~/.cursor/rules/ 或 $CODEX_HOME/rules/。注意：本工具不能下载技能（Skill），如果用户要下载的是"技能/Skill"，必须使用 download_skill 工具。

适用场景（仅当用户明确提到"规则"二字时）：
- "下载 XX 规则"、"获取 XX 规则"、"拉取 XX 规则"、"导入 XX 规则"
- "下载最新 XX 规则"、"更新规则"

不适用（必须改用其他工具）：
- 用户说"下载技能"、"安装技能"、"获取 XX 技能" → 使用 download_skill
- 用户说"搜索技能"、"有哪些技能" → 使用 search_skill

输入方式：
1. 完整规则名称（推荐）：如"瀚云公司级规则1.1" - 精确匹配
2. 规则编号：如"GS_JG_Z1_1" - 精确匹配
3. 包含"最新"/"latest"关键词时自动获取最新版本
4. 部分名称：模糊匹配，多结果时提示用户明确

重要规则：
- agent: "auto" 默认写入工作区 .agents/rules/；需要 .cursor/rules/ 时请显式传 agent: "cursor"
- 下载完成后校验目标目录必须是 .agents/rules/ 或 $CODEX_HOME/rules/，不得误写入 .cursor/rules/

安装目标 Agent（可选）：
- "auto"（默认）：项目级写入 {工作区}/.agents/rules/
- "cursor"：强制写入 {工作区}/.cursor/rules/
- "codex"：与 auto 相同，写入 {工作区}/.agents/rules/

是否全面覆盖目标规则目录。false（默认）只覆盖同名文件并保留目录中其他文件；true 会在解压前清空目标规则目录内容，请仅在用户明确要求全量覆盖时使用。

规则标识符，支持以下格式：
1. 完整规则名称（最优）：如"瀚云公司级规则1.1"、"AI测试工坊" - 精确匹配，秒级响应
2. 规则编号（精确）：如"GS_JG_Z1_1" - 全大写+下划线格式
3. 最新版本查询（推荐）：如"最新公司级规则"、"公司级规则最新版本"、"latest company rule" - 自动查找最新版本
4. 自然语言（智能）：如"请帮我下载邦道的公司级规则1.1版本" - AI会自动提取关键词
5. 部分名称（模糊）：如"公司级规则"、"测试工坊" - 可能返回多个结果

特别说明：
- 包含"最新"、"latest"、"newest"等关键词时，系统会自动查找该规则的最新版本
- 例如："帮我下载最新的公司级规则"会自动匹配到"公司级规则1.2"（假设1.2是最新版）

Tips：当返回多个匹配时，请使用返回列表中的完整规则名称重新调用此工具。

安装范围（可选）：
- "project"（默认）：Cursor 安装到 {工作区}/.cursor/rules/，Codex 安装到 {工作区}/.agents/rules/
- "user"：Cursor 安装到 ~/.cursor/rules/，Codex 安装到 $CODEX_HOME/rules/（未设置时 ~/.codex/rules/）
如果不指定，默认为 project。当指定 scope 为 user 时，targetDirectory 参数会被忽略。

目标工作区目录的绝对路径。**强烈建议明确指定此参数**，使用当前打开的工作区路径（可从 workspace_path 获取）。Cursor project 下载到 {targetDirectory}/.cursor/rules/；Codex project 下载到 {targetDirectory}/.agents/rules/。Codex / CodeX 会话里必须同时显式传 agent: "codex"。如果不提供，将尝试使用环境变量 PWD 或进程的当前工作目录。

目标规则目录的绝对路径。提供后将直接写入该目录，并覆盖 targetDirectory + scope + agent 推导出的默认目录。适用于用户明确要求下载到某个规则目录时，例如 /repo/.cursor/rules 或 /repo/.agents/rules。

仅用于下载并安装 Agent 技能（Skill）。Cursor 安装到 .cursor/skills；Codex 安装到工作区 .agents/skills 或用户级 $CODEX_HOME/skills。注意：本工具不能下载规则（Rule），如果用户要下载的是"规则/Rule"，必须使用 download_rule 工具。

这是获取技能的首选方式。当用户提到"技能"或"skill"并表达下载/安装/获取意图时，必须优先调用此工具。

适用场景：
- "下载 xxx 技能"、"获取 xxx 技能"、"安装 xxx 技能"
- "帮我下载/安装 xxx"（当 xxx 是技能名称时）
- "把 xxx 技能拉下来"、"同步技能到本地"

不适用（必须改用其他工具）：
- 用户说"下载规则"、"获取 XX 规则" → 使用 download_rule
- 用户说"搜索技能"、"有哪些技能" → 使用 search_skill
- 用户说"检查技能更新" → 使用 check_skill

重要规则：
- 从 ACW Skills 广场下载到本地，不是从网络搜索
- 全量覆盖：下载后本地目录与平台完全一致，多余的本地文件会被自动清理
- agent: "auto" 默认写入工作区 .agents/skills/；需要 .cursor/skills/ 时请显式传 agent: "cursor" 或设置 ACW_INSTALL_AGENT=cursor
- 下载完成后校验目标目录必须是 .agents/skills/ 或 $CODEX_HOME/skills/，不得误写入 .cursor/skills/

安装目标 Agent（可选）：
- "auto"（默认）：项目级写入 {工作区}/.agents/skills/
- "cursor"：强制写入 {工作区}/.cursor/skills/
- "codex"：与 auto 相同，写入 {工作区}/.agents/skills/

安装范围（可选）：
- "project"（默认）：Cursor 安装到 {工作区}/.cursor/skills/，Codex 安装到 {工作区}/.agents/skills/
- "user"：Cursor 安装到 ~/.cursor/skills/，Codex 安装到 $CODEX_HOME/skills/（未设置时 ~/.codex/skills/）
如果不指定，默认为 project。当指定 scope 为 user 时，targetDirectory 参数会被忽略。

技能标识符，支持以下格式：
1. 技能名称（推荐）：如"code-review"、"pdf-processing" - 精确匹配（名称是全局唯一的）
2. 部分名称：如"code" - 模糊匹配，可能返回多个结果

目标工作区目录的绝对路径。**强烈建议明确指定此参数**，使用当前打开的工作区路径（可从 workspace_path 获取）。Cursor project 下载到 {targetDirectory}/.cursor/skills/；Codex project 下载到 {targetDirectory}/.agents/skills/。Codex / CodeX 会话里必须同时显式传 agent: "codex"。如果不提供，将尝试使用环境变量获取工作区。

按智能小组名称批量下载该小组的技能、规则和知识库，并逐个安装到本地 Agent 目录。

适用场景：
- "下载智能小组 A 下的所有技能"
- "把智能小组 A 的所有资产下下来"
- "下载智能小组 A 中标签为测试的所有资产"

行为规则：
- assetTypes 不传时默认下载 skill、rule、knowledge 三类；用户只说技能时传 ["skill"]
- tag 使用精确匹配，忽略首尾空格和大小写，不做包含匹配
- 知识库当前没有标签，因此提供 tag 时知识库不会命中
- 下载顺序固定为技能、规则、知识库；单项失败后继续下载剩余资产
- agent: "auto" 默认写入工作区 .agents 目录；需要 .cursor 目录时显式传 agent: "cursor"

安装目标 Agent，auto 默认使用 .agents 目录

要下载的资产类型；不传时默认三类全部下载

安装范围，默认 project

智能小组名称。精确匹配优先，模糊匹配到多个小组时会返回候选项

可选标签，忽略首尾空格和大小写后精确匹配

目标工作区目录的绝对路径。项目级下载时建议明确传入当前工作区路径

查询集团 SkillHub 技能分类列表，供 upload_skill 选择 categoryCode 使用。

触发场景：
- 上传技能到 ACW 前，需要先获取 SkillHub 分类下拉选项
- 用户询问 SkillHub 有哪些技能分类

返回字段：
- codeValue：上传时传给 upload_skill 的 skillhubCategoryCode
- codeName：分类中文名称，便于选择

从用户的私有知识库中语义检索技术文档、框架用法、内部规范等内容。这些知识不在你的训练数据中，只有通过此工具才能获取。

调用原则：仅在用户明确要求检索/查询/搜索知识库时调用，不得自动触发。

应调用的典型表述：
- "查知识库"、"检索知识库"、"搜索知识库"、"从知识库里找"
- "用 ACW 知识库查一下 xxx"、"在知识库里搜索 xxx"

不应调用：
- 用户仅提到 acw、ACW、use acw，但未要求检索知识库
- 普通编码、排查、读仓库代码等任务，用户未明确要求查知识库
- 纯闲聊、问候、与知识检索无关的对话

检索范围：不指定 knowledgeName 时检索所有可访问的知识库，指定时仅检索该知识库。

指定检索某个知识库的标识名。不传则检索所有可访问的知识库

用自然语言描述你想查找的内容，如 '用户认证的流程是什么'

相关度阈值 0-1（默认 0.3）。调高可过滤掉不太相关的结果

返回结果数量（默认 5，最大 20）。结果较少时可适当增大

在 ACW Skills 广场中搜索可用的技能。当用户想了解有哪些技能、查找特定功能的技能时调用。

触发场景：
- "有哪些技能"、"看看都有什么技能"、"技能列表"
- "搜索 xxx 相关的技能"、"找一下 xxx 技能"
- "有没有 xxx 方面的技能"、"谁做了什么技能"
- 用户不确定技能名称想先搜索再决定下载时

特性：支持关键字模糊搜索、按标签筛选、按创建者筛选

按创建者筛选

搜索关键字，支持技能名称和描述的模糊匹配

每页数量（默认 20，最大 100）

页码（从 1 开始，默认 1）

按标签筛选

将本地文档上传为个人知识库，上传后可通过 search_knowledge 语义检索。

当用户提到以下意图时应调用此工具：
- "帮我上传知识"、"把文档传到知识库"、"上传知识库" → 用当前工作区目录，knowledgeName 从项目名推断
- "把 xxx 目录上传到知识库" → sourcePath 指向该目录
- "更新知识库" → mode 用 overwrite
- "追加文件到知识库" → mode 用 incremental

参数推断规则：
- sourcePath 不传时默认使用当前工作区根目录
- knowledgeName 不传时自动从 sourcePath 的目录名生成（转小写、空格转连字符）
- displayName 不传时使用目录名作为显示名

支持的文件格式：.md .txt .pdf .docx .pptx .html .json .yaml .csv .xml .rst .rtf .epub .ipynb
限制：单次上传总大小不超过 20MB。自动跳过 node_modules、隐藏目录。

知识库用途描述，帮助后续识别和管理

知识库的显示名称。不传时使用目录名

知识库唯一标识（小写字母、数字、连字符）。不传时自动从目录名推断，如目录名 'My Project' → 'my-project'

上传模式：overwrite = 全量覆盖（默认），incremental = 追加新文件不影响已有内容

文档所在目录路径。不传时默认使用当前工作区根目录

知识库存储类型：OSS = 兼容旧上传链路（默认），GITLAB = 提交到 GitLab 仓库并发布索引

上传/发布本地规则到 ACW Skills 广场（规则共享平台）。

触发场景（当用户说以下任意一种时，必须调用此工具）：
- "上传规则"、"上传 xxx 规则"、"上传规则到 acw"
- "发布规则"、"发布 rule"、"发布到广场"
- "同步规则到广场"、"把规则传上去"、"推送规则"
- "更新规则"、"覆盖规则"
- 任何包含"上传/发布/推送/更新" + "规则/rule"的请求

重要规则：
- 全量覆盖：上传后平台仓库将与本地文件完全一致，平台上多余文件会被自动清理
- 自动检索本地规则路径：优先项目目录，找不到再搜索用户目录；也可显式传 rulePath
- 规则不存在时自动创建，已存在时需 forceOverwrite=true 确认覆盖
- rulePath 可指向单个 .md/.mdc 文件，也可指向规则目录
- 指定 smartGroupIds 或 smartGroupNames 时，规则会设置为智能小组可见
- 规则标题最长 20 个字；不传 ruleTitle 时会从规则文件 frontmatter title、一级标题或文件名推断

规则描述（可选）。如果不提供，将从规则文件 frontmatter description 读取，最多 300 个字符。

是否强制覆盖已存在的规则（可选，默认 false）。如果规则已存在且此参数为 false，将返回确认提示。

本地规则文件或目录的绝对路径（可选）。支持单个 .md/.mdc 文件或包含规则文件的目录。如果不提供，将按 ruleTitle 在 .agents/rules、.cursor/rules、用户级规则目录中检索。

规则标题（可选）。如果不提供，将从规则文件 frontmatter title、一级标题或文件名推断；最长 20 个字。

智能小组 UUID 列表（可选）。传入后规则会设置为智能小组可见。

智能小组名称列表（可选）。会按当前 ACW_TOKEN 可访问的小组解析为 UUID，名称匹配多个时会要求改用 UUID。

规则标签（可选）。

工作区路径（可选）。用于在项目目录中检索规则。建议使用当前打开的工作区路径。

上传/发布本地技能到 ACW Skills 广场（技能共享平台）。

触发场景（当用户说以下任意一种时，必须调用此工具）：
- "上传技能"、"上传 xxx 技能"、"上传技能到 acw"
- "发布技能"、"发布 skill"、"发布到广场"
- "同步技能到广场"、"把技能传上去"、"推送技能"
- "帮我上传下技能"、"帮我发布一下 xxx"
- 任何包含"上传/发布/推送" + "技能/skill"的请求

重要规则：
- 全量覆盖：上传后平台仓库将与本地完全一致，平台上多余的文件会被自动清理
- 覆盖已有技能时会上传本地目录的新版本文件，并同步该版本 SKILL.md frontmatter 中的元数据到广场列表
- 自动检索本地技能目录：优先项目目录，找不到再搜索用户目录
- 技能不存在时自动创建，已存在时需 forceOverwrite=true 确认覆盖
- 技能目录必须包含 SKILL.md 文件
- 元数据优先级：upload_skill 入参 > 本地 SKILL.md frontmatter > 平台已有值；未传 smartGroupIds/smartGroupNames 时保留平台已有小组配置
- 指定 smartGroupIds 或 smartGroupNames 时，技能会设置为智能小组可见
- 上传时会同步技能元数据到广场列表：description、displayNameZh、tags、downloadNotice、visibility、smartGroupIds
- 推荐上传集团 SkillHub 前先调用 list_skillhub_categories 选择分类，并将 codeValue 传入 skillhubCategoryCode；SkillHub 不可用时允许省略
- 名称规范：小写字母、数字、连字符，1-64 字符

技能描述（可选）。如果不提供，将从 SKILL.md 中读取。

技能中文展示名（可选）。如果不提供，将从 SKILL.md frontmatter 读取。

下载注意事项（可选）。如果不提供，将从 SKILL.md frontmatter 读取。

是否强制覆盖已存在的技能（可选，默认 false）。如果技能已存在且此参数为 false，将返回确认提示。

技能目录的绝对路径（可选）。如果不提供，将自动检索：优先搜索项目目录，找不到再搜索用户目录。

技能名称（必填）。必须符合 agentskills 规范：
- 1-64 个字符
- 只能包含小写字母、数字和连字符
- 不能以连字符开头或结尾
- 不能有连续连字符
例如: "code-review"、"api-test-helper"、"my-skill"

集团 SkillHub 分类编码（可选）。推荐先调用 list_skillhub_categories 使用返回的 codeValue；SkillHub 不可用时允许省略。

智能小组 UUID 列表（可选）。传入后技能会设置为智能小组可见。

技能标签（可选）。

可见性（可选）：PUBLIC / PRIVATE / GROUP。如果不提供，将从 SKILL.md frontmatter 或平台已有值读取。

工作区路径（可选）。用于在项目目录中检索技能。建议使用 Cursor 当前打开的工作区路径。