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...
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
服务器架构与传输
概述
@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 模型,向外暴露如 do、create_workflow、add_step、get_step_schema、get_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_routine、delete_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 模式下密钥只能通过环境变量传入,部署侧需要保证:
- 由宿主启动进程时设置
AGENTLED_API_KEY; - 不要在日志中回显
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 骨架,覆盖minimal、lead-scoring-kg、email-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 Key:
AGENTLED_API_KEY未设置或为空时,注册清单标记其为isRequired: true,宿主在拉起进程后会立即拒绝连接。 - 步骤类型闭集:
create_workflow/add_step的工具描述中显式列举了合法type,其余值会被静默丢弃,常见错误包括ai、integration、knowledge_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.ts与get_step_schema工具) - 工具描述与增量创作路径(
create_workflow/add_step/validate_workflow) - 知识图谱工具(
create_knowledge_list、get_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...
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
继续阅读本节完整说明和来源证据。
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-server、agentled-mcp-server-http、mcp-server。资料来源:package.json:1-
工具分类
工作流与执行
do— 语义意图路由器:用自然语言描述目标,匹配工作区中最相关的 live workflow,并可选自动执行,返回最佳匹配、置信度、抽取的输入与候选项。资料来源:src/tools/intent.ts:1-get_step_schema— 返回步骤 schema 与示例(支持按stepType/shape过滤,例如outputPage:standard、aiAction:email、appAction:kg-read-text)。资料来源:src/tools/workflows.ts:1-validate_workflow/publish_workflow— 增量创作路径上的验证与发布动作,工具描述中明确推荐create_workflow({ name, goal })→ 逐个add_step→validate_workflow→publish_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-core、channel-email、routine-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,附带severity、userEmail、source、context等字段。资料来源:src/tools/feedback.ts:1-
模型发现
list_models— 列出工作流步骤可用的 AI 模型(ID、提供商、显示名、mini/standard/max 等级、积分成本、类别)。资料来源:src/tools/models.ts:1-
配套资源
Step Shapes
src/step-shapes.ts 内置一组经过预检的步骤形状示例,例如 inputPage:standard、appAction:kg-read-text、code:standard、Agent 团队编排器预设(research-and-summarize、analyze-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 支持的预置骨架包括 minimal、lead-scoring-kg、ai-with-tools、email-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. CLI 命令套件
CLI 模块以 agentled 命令为入口,封装了对 MCP 工具能力的脱机访问,方便 Agent 在不连接远端 API 的情况下预先查询模式、生成骨架与验证最佳实践。
1.1 `examples` — 模式查询
agentled examples 从本地 patterns/v1/ 目录读取预置的模式文档,支持按 slug、数字或关键字检索,输出 Markdown 渲染结果。源文件中定义了 PATTERNS 数组,登记 8 套 agentic-ops 模式(如 01-trigger-design、02-dedup-gates、09-reports-and-knowledge-storage)。命令通过简单的 Markdown 解析(高亮标题、代码块、引用)输出到终端。
资料来源:src/cli/examples.ts:60-150
1.2 `scaffolds` — 预检通过的 JSON 骨架
agentled workflows scaffold 命令输出 preflight-clean 的 pipeline JSON 模板,覆盖 minimal、lead-scoring-kg、ai-with-tools、email-polling-dedup、list-match-email、extract-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_workflow、add_step 工具描述互相呼应。
资料来源:src/cli/best-practices.ts:1-40
2. Skills 技能系统
Skills 是 AgentLed 在 Agent 与 Routine 维度上扩展能力的核心机制,对应 MCP 工具 list_agent_skills、import_workspace_skill、create_workspace_skill。
2.1 内置 Skill Bundle
源文件 agent-skills.ts 维护一份内置 bundle 注册表,每条记录包含 id、version、label、description、category、surfaces、risks、mcpVisible 等字段。可见示例包括公开的 web-search/workspace-memory 等运行时工具,以及 routine-core、channel-email、routine-manager 等 mcpVisible: 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,由服务端绑定 lifecycle、riskProfile、relevanceRules、approvalPolicy 等元数据。
资料来源: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 Hook:
schedule类型用于邮件轮询与文档处理(幂等、可回填、无需事件基础设施);app_event/webhook仅在用户明确要求亚分钟级实时性时使用。 - Step Hook:闭合的
type词表覆盖trigger、appAction、aiAction、aiActionWithTools、toolAction、code、knowledgeSync、return、milestone、share、wait、branch、parallel、loop、end_if、agentOrchestrator。get_step_schema返回每个类型权威字段表。 - Page Hook:
outputPages是执行后用户可见的结果页(如 LinkedIn 发布页、报告页),禁止用于审批占位或内部管道步骤;inputPages通过contextKey与workflow.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_text、create_knowledge_list 等工具让 Agent 在生成 prompt 前先检索工作区已沉淀的策略(投资论点、ICP 描述、品牌语气)。KG-First 原则要求:若已有知识条目,应通过运行时读取步骤(如 appAction:kg-read-text)注入上下文,而非硬编码进 prompt 模板。
资料来源:src/tools/knowledge.ts:1-60
4.2 Routines 与手动触发
trigger_routine 接受 routine_id、source(codex/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 的 scaffolds 与 examples 命令同步提供对应模板,使 Agent 在升级后仍可通过脱机命令快速对齐最新形状。
资料来源:CHANGELOG.md:1-120 server.json:1-25
See Also
- 工作流增量创作流程(参见
create_workflow→add_step→validate_workflow→publish_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_workflow 与 add_step 的工具描述中显式列出了闭式 step.type 词汇表,任何不在表中的类型在提交时会被静默剥离或校验拒绝(资料来源:src/tools/workflows.ts)。该词汇表为 16 个稳定类型,而非可自由扩展的开放枚举。
完整的形状定义与最小 JSON 示例集中在 src/step-shapes.ts 中,对外通过 get_step_schema({ stepType, shape? }) 暴露。智能体可按需拉取带键控(keyed)的子集,例如 aiAction:report、aiAction:email、aiActionWithTools:agentic-search、appAction:kg-read-text、agentOrchestrator:supervisor、code: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 取值(例如 text、boolean、select、multiselect、connected_emails_selector_single 等),任何拼写错误(如 "multi-select"、"checkbox"、"number")都会触发静默剥离类失败模式。
| 类别 | 典型 step.type | 形状键示例 | 关键约束 |
|---|---|---|---|
| AI 推理 | aiAction、aiActionWithTools | aiAction:report、aiAction:email | 邮件形态必须配合 approvalRequired + onApproval.action:"schedule-email"(src/step-shapes.ts) |
| 外部应用 | appAction | appAction:kg-read-text、appAction:kg-upsert-rows-sourcing | 写操作需在步骤上直挂 preExecuteApproval: true(src/cli/best-practices.ts) |
| 编排 | agentOrchestrator | agentOrchestrator:supervisor | metadata.agentTeamMode 取 simple/advanced(src/step-shapes.ts) |
| 确定性 | code | code:standard | 仅支持 JavaScript,禁用 Python |
| 控制流 | branch、parallel、loop、wait、end_if | — | 与 next: { stepId } 配合 |
增量编辑模型与合并语义
推荐的工作流编辑路径是 create_workflow({ name, goal }) → add_step × N → validate_workflow → publish_workflow,与"导入、模板、JSON 往返"的批量提交并列存在但被刻意降级(资料来源:src/tools/workflows.ts)。
update_step 是对已存在单步编辑的首选入口,其合并语义有三层(资料来源:CHANGELOG.md: MCP-034):
- 顶层浅合并——传入的键覆盖原值,未传入的键保留。
- 嵌套对象深合并——例如
codeConfig.code内部字段可逐项更新。 - 数组整体替换——
fields[]、integrations[]等数组无法按索引增量,必须整组重写。 - 传
null删除字段——但step.id与step.type不可变,需走remove_step+add_step重建(资料来源:src/tools/workflows.ts)。
触发器(trigger)的选择也属于编辑模型的一部分:默认推荐 schedule(轮询)用于邮件接收、文档处理等非实时场景,具备幂等、支持回填、无需事件基础设施;若用户明确要求秒级延迟(如"30 秒内")才改用 app_event 或 webhook(资料来源: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 种预检通过的管线骨架(minimal、lead-scoring-kg、ai-with-tools、email-polling-dedup 等),作为合法形状的最小可行起点(资料来源:src/cli/scaffolds.ts)。
See Also
- 执行模型与重试语义 — 配合
validate_workflow之后的publish_workflow与retry_execution使用 - 知识图谱(KG)优先原则 —
appAction:kg-*形状与workspace_memory工具的协同 - 触发器选型指南 —
schedulevsapp_eventvswebhook的决策表
来源:https://github.com/Agentled/mcp-server / 项目说明书
失败模式与踩坑日记
保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险,不把社区讨论只当作装饰信息。
用户必须准备账号、额度或密钥;密钥配置错误会导致运行失败或泄漏风险。
安装可能改变本机 AI 工具行为,用户需要知道写入位置和回滚方法。
假设不成立时,用户拿不到承诺的能力。
新项目、停更项目和活跃项目会被混在一起,推荐信任度下降。
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 发现、验证与编译记录