Doramagic 项目包 · 项目说明书

mcp-server 项目

专为 AI Agent 打造的自动化引擎,提供工作流、记忆能力以及 100+ 集成,只需一个 API Key 即可使用。

Server Architecture & Transport

@agentled/mcp-server 是一个基于 Model Context Protocol(MCP) 的服务端实现,将 Agentled 工作空间的「工作流编排、知识图谱、Agent 技能、语义意图路由」等能力以标准化的 MCP 工具形式暴露给大模型客户端(Claude、Codex 等)。包元数据表明其名称为 io.github.Agentled/mcp-serve...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 stdio 传输

继续阅读本节完整说明和来源证据。

章节 MCP SDK 装配

继续阅读本节完整说明和来源证据。

章节 架构总览

继续阅读本节完整说明和来源证据。

服务器架构与传输

概述

@agentled/mcp-server 是一个基于 Model Context Protocol(MCP) 的服务端实现,将 Agentled 工作空间的「工作流编排、知识图谱、Agent 技能、语义意图路由」等能力以标准化的 MCP 工具形式暴露给大模型客户端(Claude、Codex 等)。包元数据表明其名称为 io.github.Agentled/mcp-server,版本 0.18.3,主入口通过 stdio 传输提供工具集 资料来源:server.json:1-32

在仓库的内部结构上,server 部分由一组以 src/tools/*.ts 为核心的 MCP 工具注册模块组成,配合 src/step-shapes.ts 提供的工作流步骤 JSON 模型,向外暴露如 docreate_workflowadd_stepget_step_schemaget_knowledge_text 等工具。同时 src/cli/*.ts 提供了一个同包的命令行客户端,可用于模式查询、模板脚手架与最佳实践打印 资料来源:package.json:1-19、src/cli/examples.ts:1-15。

传输层与协议

stdio 传输

MCP 注册清单显式声明该包使用 stdio 作为唯一传输类型:

"transport": { "type": "stdio" }

这意味着进程以标准输入/输出作为 JSON-RPC 信道,由宿主(MCP 客户端)拉起并托管生命周期 资料来源:server.json:18-32

MCP SDK 装配

所有工具模块都从 @modelcontextprotocol/sdk 导入 McpServer

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

随后调用 server.tool(name, description, schema, handler) 完成注册,例如 do 工具就把自然语言意图路由到匹配的工作流 资料来源:src/tools/intent.ts:6-39。

架构总览

flowchart LR
    Host[MCP 客户端<br/>Claude / Codex] -- JSON-RPC over stdio --> Server[Agentled MCP Server]
    Server -- registerTool --> Tools[工具注册层<br/>workflows / intent / knowledge / routines / agent-skills]
    Tools -- ClientFactory(extra) --> Client[Agentled API 客户端]
    Client -- HTTPS + AGENTLED_API_KEY --> API[Agentled 工作空间 API]
    CLI[CLI 子命令<br/>examples / scaffolds / best-practices] -.读取本地 .md 模式.- Server

工具注册与请求处理

注册模型

每个工具模块导出一个 register*Tools(server, clientFactory) 函数,统一在启动阶段被装配到 McpServer 实例上。例如 registerIntentTools 注册了 do 工具,registerAgentSkillTools 暴露技能元数据 资料来源:src/tools/intent.ts:11-40、src/tools/agent-skills.ts:1-40。

ClientFactory 模式

工具回调签名统一为 async (args, extra) => { ... },并在内部通过 clientFactory(extra) 拿到一个按请求上下文(含认证信息)构造的 API 客户端。这种设计把「每个 MCP 请求」与「每次远程 API 调用」解耦,避免在进程内共享长连接 资料来源:src/tools/workflows.ts:1-10、src/tools/routines.ts:1-15。

响应装饰

部分工具(如 trigger_routinedelete_routine)在拿到 API 响应后,会通过 decorateRoutineResponseWithUrls 注入工作空间链接,再序列化为 content: [{ type: "text", text: JSON.stringify(...) }] 返回给宿主 资料来源:src/tools/routines.ts:1-15。

认证与配置

服务端配置通过环境变量注入,注册清单中唯一的强制参数是:

名称是否必填是否机密用途
AGENTLED_API_KEY工作空间 API Key,在 Workspace Settings → Developer 中生成

资料来源:server.json:25-31

由于 stdio 模式下密钥只能通过环境变量传入,部署侧需要保证:

  1. 由宿主启动进程时设置 AGENTLED_API_KEY
  2. 不要在日志中回显 extra 对象或 API 客户端构造器中的请求头。

CLI 配套架构

@agentled/mcp-server 不仅是 MCP server,还携带了一个 CLI 子命令集合:

  • agentled examples [<pattern>] —— 列出或打印捆绑的工作流模式(从 packages/cli/patterns/v1/*.md 同步),并以着色 Markdown 形式输出 资料来源:src/cli/examples.ts:1-30。
  • agentled workflows scaffold <name> --out <file> —— 输出预检通过的 pipeline JSON 骨架,覆盖 minimallead-scoring-kgemail-polling-dedup 等常见形态 资料来源:src/cli/scaffolds.ts:1-30。
  • agentled best-practices —— 打印 KG 优先、状态去重、复合邮件与可恢复执行等关键原则 资料来源:src/cli/best-practices.ts:1-15。

CLI 与 MCP server 共用 step-shapes.ts 中的 JSON 示例,确保 get_step_schema 返回的样例与 scaffold 落盘的骨架字段一致,避免文档与代码漂移 资料来源:CHANGELOG.md:1-30、src/step-shapes.ts:1-30。

常见失败模式

  • 缺 API KeyAGENTLED_API_KEY 未设置或为空时,注册清单标记其为 isRequired: true,宿主在拉起进程后会立即拒绝连接。
  • 步骤类型闭集create_workflow / add_step 的工具描述中显式列举了合法 type,其余值会被静默丢弃,常见错误包括 aiintegrationknowledge_graph_query 等臆造类型 资料来源:CHANGELOG.md:10-20
  • 输出页字段缺失:若 context.outputPages 中条目缺少 id / title / pathname / outputSteps,工作流详情 UI 会崩溃,并通过 validate_workflow 抛出 MISSING_OUTPUT_PAGE_FIELD 资料来源:src/step-shapes.ts:1-15。

See Also

  • 工作流步骤模型(step-shapes.tsget_step_schema 工具)
  • 工具描述与增量创作路径(create_workflow / add_step / validate_workflow
  • 知识图谱工具(create_knowledge_listget_knowledge_text

资料来源:server.json:25-31

MCP Tools & Resources Reference

@agentled/mcp-server 通过 Model Context Protocol(stdio 传输)将 AgentLed 工作流编排能力暴露给任何兼容 MCP 的客户端(如 Claude Code、Codex)。客户端通过 AGENTLEDAPIKEY 环境变量完成身份认证,调用一组按领域划分的工具(Tools),并消费本地随包的辅助资源(Step Shapes...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 工作流与执行

继续阅读本节完整说明和来源证据。

章节 例程(Routines)

继续阅读本节完整说明和来源证据。

章节 代理技能(Agent Skills)

继续阅读本节完整说明和来源证据。

MCP Tools & Resources 参考

概述

@agentled/mcp-server 通过 Model Context Protocol(stdio 传输)将 AgentLed 工作流编排能力暴露给任何兼容 MCP 的客户端(如 Claude Code、Codex)。客户端通过 AGENTLED_API_KEY 环境变量完成身份认证,调用一组按领域划分的工具(Tools),并消费本地随包的辅助资源(Step Shapes / CLI / Scaffolds)。服务器清单 server.json 明确把 mcpName 注册为 io.github.Agentled/mcp-server,唯一必需的密钥环境变量为 AGENTLED_API_KEY(描述为"在 Workspace Settings > Developer 中生成")。资料来源:server.json:1-

当前版本号为 0.18.3,入口二进制包括 agentled-mcp-serveragentled-mcp-server-httpmcp-server。资料来源:package.json:1-

工具分类

工作流与执行

  • do — 语义意图路由器:用自然语言描述目标,匹配工作区中最相关的 live workflow,并可选自动执行,返回最佳匹配、置信度、抽取的输入与候选项。资料来源:src/tools/intent.ts:1-
  • get_step_schema — 返回步骤 schema 与示例(支持按 stepType / shape 过滤,例如 outputPage:standardaiAction:emailappAction:kg-read-text)。资料来源:src/tools/workflows.ts:1-
  • validate_workflow / publish_workflow — 增量创作路径上的验证与发布动作,工具描述中明确推荐 create_workflow({ name, goal }) → 逐个 add_stepvalidate_workflowpublish_workflow 的创作流程。资料来源:CHANGELOG.md:1-
  • retry_execution — 从失败步骤恢复,避免从头重跑而重复消耗积分。

例程(Routines)

  • trigger_routine — 手动触发例程,source 取值限定为 codex | claude | ui | api | mcp,并要求 1–120 字符的简短原因。资料来源:src/tools/routines.ts:1-
  • delete_routine — 永久删除,文档明确说明"此操作不可撤销"。

代理技能(Agent Skills)

  • list_agent_skills — 列出 create_agent / update_agent / create_routine / update_routine 中可用的技能 ID;默认仅返回公共技能,传 includeRuntime: true 可加载运行时隐藏束(routine-corechannel-emailroutine-manager 等)。资料来源:src/tools/agent-skills.ts:1-

对话与反馈

  • chat — 与 AgentLed AI 代理对话,通过自然语言构建工作流;支持多轮 session_id 维持上下文。资料来源:src/tools/chat.ts:1-
  • submit_feedback_to_agentled — 上报 bug | feature_request | escalation | ask,附带 severityuserEmailsourcecontext 等字段。资料来源:src/tools/feedback.ts:1-

模型发现

  • list_models — 列出工作流步骤可用的 AI 模型(ID、提供商、显示名、mini/standard/max 等级、积分成本、类别)。资料来源:src/tools/models.ts:1-

配套资源

Step Shapes

src/step-shapes.ts 内置一组经过预检的步骤形状示例,例如 inputPage:standardappAction:kg-read-textcode:standard、Agent 团队编排器预设(research-and-summarizeanalyze-and-recommend 等)。这些形状通过 get_step_schema 在线检索,旨在收紧 step.type 的封闭词表、抑制代理发明未知类型。资料来源:src/step-shapes.ts:1-

CLI

命令作用
agentled schema [--step-type <t>]包装 GET /api/external/workflows/step-schema
agentled examples [pattern]列出或打印随 CLI 捆绑的 8 个 agentic-ops 模式(按 slug、序号或关键词解析)
agentled best-practices指向公共规范仓库 github.com/agentled/agentic-ops
agentled workflows scaffold写入预检清洁的 pipeline JSON 骨架

资料来源:src/cli/examples.ts:1-、src/cli/scaffolds.ts:1-、src/cli/best-practices.ts:1-

脚手架(Scaffolds)

agentled workflows scaffold 支持的预置骨架包括 minimallead-scoring-kgai-with-toolsemail-polling-* 等,对应"循环模式 + 报告与知识存储"、"原生 vs 代理"等模式族,可通过 --list 浏览或 --out <file> 写出文件。资料来源:src/cli/scaffolds.ts:1-

工具注册模式与响应形态

所有工具都遵循统一的注册范式:server.tool(name, description, zodSchema, async handler),处理器从 ClientFactory 取得已认证的 API 客户端,并以 { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] } 返回文本内容。这种一致性让 IDE、Claude Code、Codex 等客户端都能可靠地解析响应。资料来源:src/tools/intent.ts:1-、src/tools/feedback.ts:1-

工具生态总览

flowchart LR
    Client["MCP 客户端<br/>(Claude Code / Codex)"]
    Server["@agentled/mcp-server<br/>stdio + AGENTLED_API_KEY"]
    Intent["do<br/>语义意图路由"]
    Chat["chat<br/>对话构建"]
    WF["workflows<br/>get_step_schema / validate / publish"]
    RT["routines<br/>trigger / delete"]
    Skills["list_agent_skills"]
    Models["list_models"]
    FB["submit_feedback_to_agentled"]
    Shapes["step-shapes.ts"]
    CLI["agentled examples / best-practices / scaffold"]

    Client --> Server
    Server --> Intent
    Server --> Chat
    Server --> WF
    Server --> RT
    Server --> Skills
    Server --> Models
    Server --> FB
    WF -. 引用 .-> Shapes
    Server -. 配套 .-> CLI

客户端集成与插件分发

服务器清单(server.json)将传输方式声明为 stdio,并仅要求 AGENTLED_API_KEY 一个密钥。CHANGELOG.md 0.18.0 进一步引入第一方 Claude Code 插件 plugins/agentled/:通过 /plugin marketplace add Agentled/mcp-server 添加源后再 /plugin install agentled@agentled,设置 API Key 后即可一次性获得 agentled:agentled 技能和自动启动的 MCP 服务器。资料来源:server.json:1-、CHANGELOG.md:1-

See Also

  • 工作流创作与校验:src/tools/workflows.ts
  • 步骤形状参考:src/step-shapes.ts
  • CLI 与脚手架入口:src/cli/scaffolds.ts · src/cli/examples.ts
  • 版本历史:CHANGELOG.md

资料来源:src/cli/examples.ts:1-、src/cli/scaffolds.ts:1-、src/cli/best-practices.ts:1-

CLI, Plugin, Hooks & Skills

AgentLed MCP Server 在 Model Context Protocol (MCP) 接口之外,还提供了一组面向开发者与 AI Agent 的扩展机制——CLI 命令、Scaffold 模板、Agent Skills、Knowledge 插件和 Workflow Hooks。本页基于仓库源码梳理这些能力的用途、调用方式与相互关系。

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 1.1 examples — 模式查询

继续阅读本节完整说明和来源证据。

章节 1.2 scaffolds — 预检通过的 JSON 骨架

继续阅读本节完整说明和来源证据。

章节 1.3 best-practices — 准则提示

继续阅读本节完整说明和来源证据。

1. CLI 命令套件

CLI 模块以 agentled 命令为入口,封装了对 MCP 工具能力的脱机访问,方便 Agent 在不连接远端 API 的情况下预先查询模式、生成骨架与验证最佳实践。

1.1 `examples` — 模式查询

agentled examples 从本地 patterns/v1/ 目录读取预置的模式文档,支持按 slug、数字或关键字检索,输出 Markdown 渲染结果。源文件中定义了 PATTERNS 数组,登记 8 套 agentic-ops 模式(如 01-trigger-design02-dedup-gates09-reports-and-knowledge-storage)。命令通过简单的 Markdown 解析(高亮标题、代码块、引用)输出到终端。

资料来源:src/cli/examples.ts:60-150

1.2 `scaffolds` — 预检通过的 JSON 骨架

agentled workflows scaffold 命令输出 preflight-clean 的 pipeline JSON 模板,覆盖 minimallead-scoring-kgai-with-toolsemail-polling-deduplist-match-emailextract-threshold-alert 等常见形状。ScaffoldMeta 接口记录每个模板的名字、描述、关联模式以及 JSON 文件路径,开发者可通过 --list 枚举或 --out <file> 直接落盘。

资料来源:src/cli/scaffolds.ts:1-60

1.3 `best-practices` — 准则提示

该命令打印 AgentLed 的工程准则,包括:先调 schema 后建模、避免在 prompt 中硬编码业务内容、使用 kg.upsert-rows 配合 status 字段做去重、邮件一律走 composed aiAction + approval gate、失败的执行用 retry_execution 而非重启等。这些条目与 MCP Server 的 create_workflowadd_step 工具描述互相呼应。

资料来源:src/cli/best-practices.ts:1-40

2. Skills 技能系统

Skills 是 AgentLed 在 Agent 与 Routine 维度上扩展能力的核心机制,对应 MCP 工具 list_agent_skillsimport_workspace_skillcreate_workspace_skill

2.1 内置 Skill Bundle

源文件 agent-skills.ts 维护一份内置 bundle 注册表,每条记录包含 idversionlabeldescriptioncategorysurfacesrisksmcpVisible 等字段。可见示例包括公开的 web-search/workspace-memory 等运行时工具,以及 routine-corechannel-emailroutine-managermcpVisible: false 的内部 bundle。其中 routine-manager 因涉及自治与管理权限,被标记为 requiresApprovalForActivation: true

资料来源:src/tools/agent-skills.ts:1-60

2.2 工作区技能导入与创建

import_workspace_skill 接受 Markdown/SKILL.md/JSON 内容或 GitHub raw URL,自动将 GitHub blob URL 改写为 raw URL,并通过 metadata.importSource 记录来源标签。create_workspace_skill 是低级入口,要求调用方提供已审核的 AgentFile ID,由服务端绑定 lifecycleriskProfilerelevanceRulesapprovalPolicy 等元数据。

资料来源:src/tools/agent-skills.ts:120-180

3. 工作流 Hooks:Trigger、Step 与 Page

CLI 与 Skills 都通过 workflow 的 Hook 机制落地行为。Hook 主要分布在三类位置:workflow.steps(执行步骤)、workflow.context.inputPages(用户保存的配置表单)以及 workflow.context.outputPages(执行结果落地页)。

flowchart LR
    A[Trigger Hook] --> B[Steps Hook]
    B --> C[AI / AppAction]
    B --> D[KG Sync / Code]
    C --> E[outputPages Hook]
    D --> E
    F[inputPages Hook] --> A
    F --> B
    style A fill:#fde,stroke:#333
    style F fill:#dfe,stroke:#333
    style E fill:#def,stroke:#333
  • Trigger Hookschedule 类型用于邮件轮询与文档处理(幂等、可回填、无需事件基础设施);app_event/webhook 仅在用户明确要求亚分钟级实时性时使用。
  • Step Hook:闭合的 type 词表覆盖 triggerappActionaiActionaiActionWithToolstoolActioncodeknowledgeSyncreturnmilestonesharewaitbranchparallelloopend_ifagentOrchestratorget_step_schema 返回每个类型权威字段表。
  • Page HookoutputPages 是执行后用户可见的结果页(如 LinkedIn 发布页、报告页),禁止用于审批占位或内部管道步骤;inputPages 通过 contextKeyworkflow.context.<contextKey> 双向映射用户保存值。
资料来源:src/tools/workflows.ts:1-80 src/step-shapes.ts:1-120

4. 插件与集成层

Knowledge Graph (KG) 与 Routines 是 CLI/Skills 体系的两大插件集成入口。

4.1 Knowledge Graph 插件

get_knowledge_textcreate_knowledge_list 等工具让 Agent 在生成 prompt 前先检索工作区已沉淀的策略(投资论点、ICP 描述、品牌语气)。KG-First 原则要求:若已有知识条目,应通过运行时读取步骤(如 appAction:kg-read-text)注入上下文,而非硬编码进 prompt 模板。

资料来源:src/tools/knowledge.ts:1-60

4.2 Routines 与手动触发

trigger_routine 接受 routine_idsourcecodex/claude/ui/api/mcp)与 reason,将手动触发标记写入 Routine 历史;delete_routine 则永久删除。两者均通过 decorateRoutineResponseWithUrls 为响应附加可点击的 routine URL,便于在 UI 中跳转复核。

资料来源:src/tools/routines.ts:1-60

5. 版本与兼容性

server.json 当前版本为 0.18.3,通过 stdio 传输,依赖 AGENTLED_API_KEY 环境变量。CHANGELOG 中 MCP-029/030 引入 Skill v0.5.0 schema 升级、MCP-031 将 create_workflow/add_step 改写为增量创建路径——CLI 的 scaffoldsexamples 命令同步提供对应模板,使 Agent 在升级后仍可通过脱机命令快速对齐最新形状。

资料来源:CHANGELOG.md:1-120 server.json:1-25

See Also

  • 工作流增量创作流程(参见 create_workflowadd_stepvalidate_workflowpublish_workflow
  • Knowledge Graph First Doctrine(运行时策略读取的强制顺序)
  • Agentic Ops 模式库(patterns/v1/ 八套基础模式)

来源:https://github.com/Agentled/mcp-server / 项目说明书

Step Shapes, Editing Model & Validation

@agentled/mcp-server 暴露给智能体的工作流编辑能力遵循"形状优先、增量提交、统一校验"的设计原则:先通过 getstepschema 拉取每种 step.type 的权威字段定义与最小 JSON 示例,再以 addstep / updatestep 单步编辑,最后由 validateworkflow 兜底拦截非法形状。这种设计源自 MCP-031 的实测...

章节 相关页面

继续阅读本节完整说明和来源证据。

Step Shapes、编辑模型与校验

概述

@agentled/mcp-server 暴露给智能体的工作流编辑能力遵循"形状优先、增量提交、统一校验"的设计原则:先通过 get_step_schema 拉取每种 step.type 的权威字段定义与最小 JSON 示例,再以 add_step / update_step 单步编辑,最后由 validate_workflow 兜底拦截非法形状。这种设计源自 MCP-031 的实测结论——同一管线在增量路径下产生 0 错误,在整块 JSON(bulk)路径下产生 13 错误,因为后者缺乏每步反馈与闭式词汇表约束(资料来源:CHANGELOG.md)。本页聚焦于"形状目录、单步编辑、校验语义"三者如何协同工作。

闭式 step.type 词汇表与形状目录

create_workflowadd_step 的工具描述中显式列出了闭式 step.type 词汇表,任何不在表中的类型在提交时会被静默剥离或校验拒绝(资料来源:src/tools/workflows.ts)。该词汇表为 16 个稳定类型,而非可自由扩展的开放枚举。

完整的形状定义与最小 JSON 示例集中在 src/step-shapes.ts 中,对外通过 get_step_schema({ stepType, shape? }) 暴露。智能体可按需拉取带键控(keyed)的子集,例如 aiAction:reportaiAction:emailaiActionWithTools:agentic-searchappAction:kg-read-textagentOrchestrator:supervisorcode:standard 等。该机制由 MCP-033 引入——create_workflow 描述从 6144 字节压缩到 2713 字节,重复的 JSON 块被外迁到键控响应中,避免 MCP 宿主端(host)截断或跳过内联示例(资料来源:CHANGELOG.md)。

CLI 端配套提供 agentled schema --step-type <type> [--shape <shape>] 命令,将同一份形状表直接打印到终端,便于本地预检(资料来源:src/cli/schema.ts)。schema --context 则列出 14 种合法的 inputPage.fields[].type 取值(例如 textbooleanselectmultiselectconnected_emails_selector_single 等),任何拼写错误(如 "multi-select""checkbox""number")都会触发静默剥离类失败模式。

类别典型 step.type形状键示例关键约束
AI 推理aiActionaiActionWithToolsaiAction:reportaiAction:email邮件形态必须配合 approvalRequired + onApproval.action:"schedule-email"(src/step-shapes.ts)
外部应用appActionappAction:kg-read-textappAction:kg-upsert-rows-sourcing写操作需在步骤上直挂 preExecuteApproval: true(src/cli/best-practices.ts)
编排agentOrchestratoragentOrchestrator:supervisormetadata.agentTeamModesimple/advanced(src/step-shapes.ts)
确定性codecode:standard仅支持 JavaScript,禁用 Python
控制流branchparallelloopwaitend_ifnext: { stepId } 配合

增量编辑模型与合并语义

推荐的工作流编辑路径是 create_workflow({ name, goal })add_step × N → validate_workflowpublish_workflow,与"导入、模板、JSON 往返"的批量提交并列存在但被刻意降级(资料来源:src/tools/workflows.ts)。

update_step 是对已存在单步编辑的首选入口,其合并语义有三层(资料来源:CHANGELOG.md: MCP-034):

  1. 顶层浅合并——传入的键覆盖原值,未传入的键保留。
  2. 嵌套对象深合并——例如 codeConfig.code 内部字段可逐项更新。
  3. 数组整体替换——fields[]integrations[] 等数组无法按索引增量,必须整组重写。
  4. null 删除字段——但 step.idstep.type 不可变,需走 remove_step + add_step 重建(资料来源:src/tools/workflows.ts)。

触发器(trigger)的选择也属于编辑模型的一部分:默认推荐 schedule(轮询)用于邮件接收、文档处理等非实时场景,具备幂等、支持回填、无需事件基础设施;若用户明确要求秒级延迟(如"30 秒内")才改用 app_eventwebhook(资料来源:src/step-shapes.ts)。子工作流若以 return 步收尾并仅通过 agentled.call-workflow 调用,应将 context.executionInputConfig.internal: true 设为隐藏 UI 中的 Run 按钮(资料来源:src/tools/workflows.ts)。

校验语义与失败模式

validate_workflow 在发布前执行形状与产品规则两类校验。前者对应输出页(output page)字段缺失(如 MISSING_OUTPUT_PAGE_FIELD)与 outputSteps 类型非法(INVALID_OUTPUT_STEPS_TYPE)——工作流详情 UI 在加载时若遇到残缺条目会直接崩溃,因此校验阶段必须先于发布(资料来源:src/step-shapes.ts)。后者体现为 AI_STEP_PREFER_NATIVE_ACTION 类的"提示型"违规:当工作流名是 "Source: LinkedIn" 而其底层是名为 "Discover via web search" 的 aiActionWithTools 时,校验器会建议改用 src/cli/best-practices.ts 中列举的原生应用步骤(list_apps 可见)。

CLI 侧的预检(preflight)能力在 @agentled/cli v0.5.0 中得到强化,能在本地就捕捉两类高频静默剥离失败:input-page 字段 type 取值非法与 aiActionWithTools 工具 builtinType 取值非法(如 "web-search""memory")(资料来源:CHANGELOG.md)。同时,agentled workflows scaffold <name> 输出 5 种预检通过的管线骨架(minimallead-scoring-kgai-with-toolsemail-polling-dedup 等),作为合法形状的最小可行起点(资料来源:src/cli/scaffolds.ts)。

See Also

  • 执行模型与重试语义 — 配合 validate_workflow 之后的 publish_workflowretry_execution 使用
  • 知识图谱(KG)优先原则 — appAction:kg-* 形状与 workspace_memory 工具的协同
  • 触发器选型指南 — schedule vs app_event vs webhook 的决策表

来源:https://github.com/Agentled/mcp-server / 项目说明书

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险,不把社区讨论只当作装饰信息。

high 需要 API Key 或环境变量

用户必须准备账号、额度或密钥;密钥配置错误会导致运行失败或泄漏风险。

medium 可能修改宿主 AI 配置

安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。

medium 能力判断依赖假设

假设不成立时,用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。

Pitfall Log / 踩坑日志

项目:Agentled/mcp-server

摘要:发现 8 个潜在踩坑项,其中 1 个为 high/blocking;最高优先级:配置坑 - 需要 API Key 或环境变量。

1. 配置坑 · 需要 API Key 或环境变量

  • 严重度:high
  • 证据强度:source_linked
  • 发现:项目说明中出现 API Key / 环境变量相关需求。
  • 对用户的影响:用户必须准备账号、额度或密钥;密钥配置错误会导致运行失败或泄漏风险。
  • 证据:packet_text.keyword_scan | https://github.com/Agentled/mcp-server | matched api key / env var keyword

2. 配置坑 · 可能修改宿主 AI 配置

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主,或安装命令涉及用户配置目录。
  • 对用户的影响:安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。
  • 证据:capability.host_targets | https://github.com/Agentled/mcp-server | host_targets=mcp_host, claude_code, claude, cursor

3. 能力坑 · 能力判断依赖假设

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:README/documentation is current enough for a first validation pass.
  • 对用户的影响:假设不成立时,用户拿不到承诺的能力。
  • 证据:capability.assumptions | https://github.com/Agentled/mcp-server | README/documentation is current enough for a first validation pass.

4. 维护坑 · 维护活跃度未知

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:未记录 last_activity_observed。
  • 对用户的影响:新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。
  • 证据:evidence.maintainer_signals | https://github.com/Agentled/mcp-server | last_activity_observed missing
  • 严重度:medium
  • 证据强度:source_linked
  • 发现:no_demo
  • 证据:downstream_validation.risk_items | https://github.com/Agentled/mcp-server | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

  • 严重度:medium
  • 证据强度:source_linked
  • 发现:no_demo
  • 对用户的影响:风险会影响是否适合普通用户安装。
  • 证据:risks.scoring_risks | https://github.com/Agentled/mcp-server | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

  • 严重度:low
  • 证据强度:source_linked
  • 发现:issue_or_pr_quality=unknown。
  • 对用户的影响:用户无法判断遇到问题后是否有人维护。
  • 证据:evidence.maintainer_signals | https://github.com/Agentled/mcp-server | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

  • 严重度:low
  • 证据强度:source_linked
  • 发现:release_recency=unknown。
  • 对用户的影响:安装命令和文档可能落后于代码,用户踩坑概率升高。
  • 证据:evidence.maintainer_signals | https://github.com/Agentled/mcp-server | release_recency=unknown

来源:Doramagic 发现、验证与编译记录