# `06_MCP_SKILL_AGENT_RUNTIME.md` > DevOS Developer Work OS > MCP / Skill / Capability / Agent Runtime 设计规范 > Version: 1.0 --- # 1. 文档目标 `06` 定义 DevOS 的 **AI Capability Runtime**。 前面的架构已经确定： ```text 03 Resource / Action 04 Task / Job / Execution 05 Plugin Runtime ``` 现在需要解决： > **Agent 到底如何发现能力、理解能力、规划任务、调用工具并持续执行？** 核心目标不是再做一个“聊天机器人”。 而是建立： ```text Capability ↓ Skill ↓ Agent ↓ Plan ↓ Task ↓ Action ↓ Execution ``` 同时支持： ```text MCP Plugin Skill Workflow Human ``` 统一进入同一个 Runtime。 --- # 2. 最重要的架构原则 DevOS 必须严格区分： ```text MCP Skill Action Agent ``` 它们不是同一个东西。 --- ## MCP > **如何访问外部能力。** 例如： ```text GitHub MCP Cloudflare MCP Browser MCP Search MCP ``` --- ## Action > **系统真正可以执行的原子行为。** 例如： ```text github.repository.create website.scan server.deploy article.publish ``` --- ## Skill > **告诉 Agent 如何完成一类目标。** 例如： ```text seo.website.audit seo.campaign.execute github.repository.manage deploy.application ``` --- ## Agent > **根据 Goal 动态决定使用哪些 Skill / Action / Resource。** 因此： ```text MCP ≠ Skill Skill ≠ Action Action ≠ Agent ``` --- # 3. 四层架构 DevOS AI Runtime： ```text ┌──────────────────────────────┐ │ Agent │ │ Goal / Planning │ └──────────────┬───────────────┘ │ ┌──────────────▼───────────────┐ │ Skill │ │ Domain Knowledge │ └──────────────┬───────────────┘ │ ┌──────────────▼───────────────┐ │ Capability │ │ Action / MCP / Resource │ └──────────────┬───────────────┘ │ ┌──────────────▼───────────────┐ │ DevOS Runtime │ │ Permission / Task / Queue │ └──────────────────────────────┘ ``` --- # 4. Capability Capability 是 Agent 能看到的： > **“系统能做什么”的统一描述。** Capability 可以来自： ```text Core Plugin MCP Action Skill Workflow ``` --- # 5. Capability Registry DevOS 必须建立： ```text Capability Registry ``` 例如： ```text capabilities ├── actions ├── resources ├── skills ├── mcp-tools └── workflows ``` 统一搜索： ```ts capabilityRegistry.search({ query: "deploy website" }) ``` 返回： ```text server.deploy docker.build github.repository.release ``` --- # 6. Capability 数据模型 ```ts interface Capability { id: string type: | "action" | "skill" | "mcp_tool" | "workflow" | "resource" name: string description: string namespace: string inputSchema?: unknown outputSchema?: unknown permissions?: string[] source: { type: "core" | "plugin" | "mcp" id: string } metadata?: Record } ``` --- # 7. Capability Discovery Agent 不应该把所有工具一次性塞进 LLM Context。 错误： ```text 5000 tools ↓ 全部发送给模型 ``` 这会导致： ```text Token 巨大 成本高 模型选择能力下降 ``` 正确： ```text Goal ↓ Capability Search ↓ Top relevant capabilities ↓ LLM ``` --- # 8. 两阶段 Discovery 推荐： ```text Phase 1: Semantic Search Phase 2: Permission / Scope Filtering ``` 流程： ```text Goal ↓ Search ↓ Candidate Capabilities ↓ Permission ↓ Scope ↓ Availability ↓ Final Capabilities ``` --- # 9. Capability Search 例如： ```text Goal: “把最新 GitHub 项目部署到服务器” ``` 搜索： ```text deploy github repository docker server ``` 候选： ```text github.repository.get github.repository.release docker.build server.deploy server.health_check ``` Agent 才看到这些能力。 --- # 10. Token-Efficient Discovery 这是 DevOS Agent Runtime 的重点。 不要发送： ```text 完整 JSON Schema 完整 Plugin Manifest 完整 README 完整文档 ``` 第一阶段只返回： ```text id name description type required permission ``` 例如： ```json { "id": "server.deploy", "name": "Deploy Application", "description": "Deploy an application to a server", "type": "action" } ``` 模型决定需要后，再获取详细 Schema。 --- # 11. Progressive Disclosure 能力信息分层： ```text Level 1 Capability Summary Level 2 Capability Schema Level 3 Skill Instructions Level 4 Execution Context ``` 例如： ```text Agent ↓ “我需要部署” ↓ 发现 server.deploy ↓ 获取 schema ↓ 生成 input ↓ 执行 ``` --- # 12. Skill Skill 是 Agent 的： > **任务解决方法 / 专业流程 / 决策指南。** Skill 不应该成为一个新的执行 Runtime。 --- # 13. Skill 示例 ```text seo.website.audit ``` 描述： ```text 目标： 完成网站 SEO 审计。 输入： website 步骤： 1. 获取网站 2. Crawl 3. 技术 SEO 分析 4. 内容分析 5. Backlink 分析 6. 生成报告 使用能力： website.scan seo.keyword.analyze seo.backlink.analyze report.generate ``` --- # 14. Skill Manifest ```ts interface SkillManifest { id: string name: string description: string version: string inputs?: unknown outputs?: unknown requiredCapabilities?: string[] instructions?: string examples?: SkillExample[] metadata?: Record } ``` --- # 15. Skill 不应该直接执行代码 错误： ```text Skill ↓ 直接调用 API ``` 正确： ```text Skill ↓ 选择 Capability ↓ Action Runtime ``` 因此 Skill 是： ```text Knowledge + Strategy ``` 而不是： ```text Execution Engine ``` --- # 16. Skill 来源 Skill 可以来自： ```text Core Plugin Project User Agent Marketplace ``` 例如： ```text skills/ ├── core/ ├── seo/ ├── github/ ├── devops/ └── custom/ ``` --- # 17. Skill Scope Skill 也支持 Scope： ```text global organization project user ``` 例如某个项目可以有： ```text project.deploy.production ``` 只适用于该项目。 --- # 18. Skill 与 Plugin Plugin： > 提供能力。 Skill： > 教 Agent 如何使用这些能力。 例如： ```text GitHub Plugin │ ├── github.repository.sync ├── github.repository.create └── github.issue.create GitHub Skill │ └── github.repository.manage ``` 这两个应该分开。 --- # 19. MCP MCP 是 DevOS 与外部 Agent / Tool Ecosystem 之间的标准能力接口。 DevOS 可以： ```text 作为 MCP Client ``` 也可以： ```text 作为 MCP Server ``` --- # 20. DevOS 作为 MCP Client 例如： ```text DevOS ↓ External MCP ↓ Browser ``` 或者： ```text DevOS ↓ Search MCP ``` --- # 21. DevOS 作为 MCP Server 外部 Agent： ```text Claude Cursor 其他 Agent ``` 可以连接： ```text DevOS MCP Server ``` 获得： ```text Resources Actions Skills Tasks ``` --- # 22. MCP Tool 映射 最重要规则： > **MCP Tool 必须尽可能映射到 DevOS Capability。** 例如： ```text MCP: create_github_issue ``` 映射： ```text github.issue.create ``` 调用： ```text MCP ↓ Capability ↓ Action Runtime ``` --- # 23. MCP 不允许绕过权限 即使调用来源是外部 Agent： ```text External Agent ↓ MCP ``` 仍然： ```text Authentication ↓ Authorization ↓ Scope ↓ Action ↓ Audit ``` 绝不能： ```text MCP ↓ direct database ``` --- # 24. MCP Server DevOS MCP Server： ```text /api/mcp ``` 提供： ```text tools resources prompts ``` 但是不要默认暴露整个 DevOS。 必须经过： ```text Capability Filter ``` --- # 25. MCP Capability Filter 根据： ```text Actor Organization Project Permission Scope Plugin Status ``` 过滤。 例如： ```text Admin → 100 tools Normal User → 30 tools Agent → 15 tools ``` --- # 26. Agent Agent 是： > **Goal-driven Decision & Execution Runtime。** Agent 不只是： ```text LLM + Prompt ``` 而应该拥有： ```text Goal Memory Context Planning Capability Discovery Execution Observation Reflection Retry Approval ``` --- # 27. Agent Runtime ```text ┌─────────────────────────────┐ │ Agent Runtime │ ├─────────────────────────────┤ │ Goal │ │ Context │ │ Memory │ │ Planner │ │ Capability Discovery │ │ Executor │ │ Observer │ │ Evaluator │ │ Approval │ └─────────────────────────────┘ ``` --- # 28. Agent Goal ```ts interface AgentGoal { id: string description: string actor: Actor organizationId: string projectId?: string status: | "pending" | "planning" | "executing" | "waiting" | "completed" | "failed" | "cancelled" constraints?: Record createdAt: Date } ``` --- # 29. Goal 示例 用户： ```text 10天内让 a.com 获得100篇软文和200个外链。 ``` Agent 不应该直接： ```text 调用 SEO Tool ``` 而应该： ```text Goal ↓ Understand ↓ Discover Skills ↓ Discover Capabilities ↓ Plan ↓ Approval if needed ↓ Tasks ↓ Execute ↓ Observe ↓ Verify ↓ Report ``` --- # 30. Agent Plan Plan 是 Agent 对 Goal 的执行计划。 ```ts interface AgentPlan { id: string goalId: string steps: AgentPlanStep[] status: string } ``` Step： ```ts interface AgentPlanStep { id: string type: | "action" | "task" | "workflow" | "approval" | "condition" capabilityId: string input?: unknown dependsOn?: string[] status: string } ``` --- # 31. Agent Plan 示例 ```text Goal │ ├── Step 1 │ seo.website.scan │ ├── Step 2 │ seo.keyword.research │ ├── Step 3 │ seo.content.generate │ ├── Step 4 │ seo.content.publish │ └── Step 5 seo.backlink.submit ``` --- # 32. Plan 不等于 Workflow 两者必须区分。 ```text Workflow = 预先定义的流程 ``` ```text Agent Plan = Agent 根据当前 Goal 动态产生的计划 ``` 例如： ```text Workflow: A → B → C ``` Agent： ```text Goal ↓ 发现情况 ↓ A ↓ 观察结果 ↓ 决定 B 或 D ↓ 继续 ``` --- # 33. Agent Loop Agent Runtime 核心： ```text Observe ↓ Think / Plan ↓ Act ↓ Observe ↓ Evaluate ↓ Continue / Replan / Finish ``` 代码模型： ```ts while (!goal.completed) { const observation = await observe() const decision = await planner.decide(observation) const result = await executor.execute(decision) await evaluator.evaluate(result) } ``` 实际生产环境必须支持： ```text maxIterations timeout budget cancel approval ``` --- # 34. Agent Executor Agent Executor 不应该直接执行代码。 ```text Agent Executor ↓ Capability ↓ Action Runtime ``` 例如： ```ts executor.execute({ capability: "github.repository.create", input: {...} }) ``` 最终： ```text Action Runtime ``` 负责真正执行。 --- # 35. Agent Observation Action 完成后： ```text Execution Result ↓ Observation ↓ Agent ``` 例如： ```json { "success": true, "output": { "pages": 1032, "errors": 14 } } ``` Agent 决定： ```text 继续 ``` 或者： ```text 重新规划 ``` --- # 36. Replanning Agent 不应该一次生成一个不可修改的巨大计划。 推荐： ```text Plan ↓ Execute 1-3 steps ↓ Observe ↓ Replan ``` 尤其适用于： ```text 外部 API Web SEO DevOps 自动化 ``` 因为环境会发生变化。 --- # 37. Agent Memory Memory 分为： ```text Short-term Long-term Working Context ``` --- ## Short-term 当前执行上下文： ```text 最近 Action 最近结果 当前计划 ``` --- ## Long-term 持久知识： ```text Project Preferences Previous Decisions Important Facts ``` --- ## Working Context 当前 Goal 所需的信息： ```text website project credentials resources previous results ``` --- # 38. Memory 不应该等于 Chat History 不要： ```text 整个聊天记录 ↓ 每次全部发给 LLM ``` 应该： ```text Memory Store ↓ Retrieve relevant context ↓ LLM ``` --- # 39. Agent Context 统一： ```ts interface AgentContext { goalId: string organizationId: string projectId?: string actor: Actor resources: ResourceRef[] capabilities: Capability[] memory: MemoryContext variables: Record budget?: AgentBudget } ``` --- # 40. Agent Budget Agent 必须有预算控制。 ```ts interface AgentBudget { maxTokens?: number maxIterations?: number maxExecutionTimeMs?: number maxTasks?: number maxMoney?: number maxCredits?: number } ``` 例如： ```text 最多： 100 次 Action 20 次 LLM $5 30 分钟 ``` --- # 41. Agent Cost 每个 Agent Execution 应记录： ```text LLM tokens Tool calls Action executions External API calls Money Credits ``` 最终： ```text Goal Cost $2.37 ``` --- # 42. Approval Agent 遇到高风险 Action： ```text Agent ↓ Action ↓ requiresApproval ↓ Approval Task ↓ Human ↓ Approved ↓ Execution ``` 例如： ```text 删除服务器 部署生产环境 批量发送邮件 批量发布内容 批量外链 ``` --- # 43. Agent Safety Policy 每个 Agent 都必须经过 Policy。 例如： ```ts interface AgentPolicy { allowedCapabilities: string[] deniedCapabilities: string[] maxIterations: number requireApprovalFor: string[] } ``` --- # 44. Agent Permission Agent 的权限不能自动等于用户全部权限。 例如： ```text User: admin Agent: seo-agent ``` Agent 可以被限制： ```text seo.website.* seo.content.* ``` 但： ```text server.delete ``` 明确禁止。 --- # 45. Agent Identity Agent 应该拥有自己的 Actor： ```text actor.type = "agent" actor.id = "agent_xxx" ``` Audit： ```text User ↓ Agent ↓ Action ``` 因此能够知道： > “这个操作是谁授权的，又是哪个 Agent 执行的？” --- # 46. Agent Task Agent 创建： ```text Task ``` 而不是： ```text AgentTask ``` 避免出现两套系统。 正确： ```text Agent ↓ Task Runtime ``` --- # 47. Agent Workflow Agent 可以调用 Workflow： ```text Agent ↓ Workflow ↓ Tasks ↓ Actions ``` 这非常适合： ```text 稳定流程 ``` Agent 只负责： ```text 选择 Workflow 填充参数 观察结果 ``` --- # 48. Skill + Workflow + Agent 三者关系： ```text Skill = 怎么解决问题 Workflow = 固定怎么执行 Agent = 当前应该怎么解决 ``` 例如： ```text Skill: SEO Audit Workflow: 标准 SEO Audit Workflow Agent: 根据网站情况决定是否使用完整 Workflow ``` --- # 49. Skill 可以推荐 Workflow Skill 可以声明： ```json { "recommendedWorkflows": [ "seo.standard_audit" ] } ``` Agent 可以选择： ```text Workflow ``` 或者： ```text 动态 Action Plan ``` --- # 50. Agent Tool Calling 模型产生： ```json { "capability": "github.repository.sync", "input": { "repositoryId": "repo_123" } } ``` Agent Runtime 不应该直接信任。 必须： ```text LLM Output ↓ Schema Validation ↓ Permission ↓ Scope ↓ Policy ↓ Approval ↓ Action Runtime ``` --- # 51. Tool Result Tool Result 必须标准化： ```ts interface ToolResult { success: boolean data?: unknown error?: { code: string message: string } executionId?: string taskId?: string } ``` --- # 52. MCP Tool Result MCP 返回的结果最终应该转换为统一： ```text Capability Result ``` 这样 Agent 不需要知道： ```text 这是 MCP 这是 Plugin 这是 Core ``` 它只知道： ```text Capability ``` --- # 53. Capability Adapter 如果外部 MCP Tool 无法直接映射到 Action： ```text External MCP ↓ MCP Adapter ↓ Capability ``` Adapter 负责： ```text Input conversion Output conversion Error normalization ``` --- # 54. MCP Resource MCP Resource 可以映射： ```text DevOS Resource ``` 例如： ```text github://repository/123 ``` 对应： ```text github.repository:123 ``` Agent 可以读取： ```text Resource ``` 再决定调用： ```text Action ``` --- # 55. Skill Discovery Agent 不应该搜索所有 Skill。 例如： ```text Goal: 部署 Next.js 应用 ``` 搜索： ```text deploy nextjs application ``` 返回： ```text application.deploy docker.deploy nextjs.deploy ``` 然后再加载详细内容。 --- # 56. Capability Ranking 搜索结果应该有： ```text relevance permission availability quality cost ``` 例如： ```text server.deploy score: 0.93 docker.deploy score: 0.84 ssh.execute score: 0.51 ``` 优先选择高层 Capability。 --- # 57. 为什么不能让 Agent 直接 SSH 例如： ```text Agent ↓ ssh.execute ↓ rm -rf / ``` 风险非常高。 应该优先： ```text Agent ↓ server.deploy ``` 高层 Action 可以拥有： ```text Schema Permission Policy Validation Audit ``` 因此： > **Agent 应优先使用业务 Action，而不是低层原始工具。** --- # 58. Capability Abstraction Level 建议： ```text Level 1 Business Action Level 2 System Action Level 3 Raw Tool ``` 例如： ```text deploy.application ↓ docker.run ↓ ssh.execute ``` Agent 默认优先 Level 1。 只有没有高层能力时，才允许向下。 --- # 59. Agent Fallback 例如： ```text deploy.application ``` 不存在。 Agent 可以发现： ```text docker.build server.execute_command ``` 然后组合： ```text docker.build ↓ server.execute_command ``` 但如果存在高层： ```text deploy.application ``` 就不应该自己拼底层 Action。 --- # 60. Agent Planning Policy Planner 可以设置： ```text prefer_existing_workflow prefer_high_level_actions minimize_tool_calls minimize_cost require_approval ``` 例如： ```json { "preferHighLevelActions": true, "minimizeToolCalls": true, "maxIterations": 20 } ``` --- # 61. Agent State Machine ```text pending ↓ planning ↓ executing ↓ observing ↓ evaluating ├── completed ├── replanning ├── waiting └── failed ``` 取消： ```text 任何状态 ↓ cancelled ``` --- # 62. Agent Run 一次 Agent Goal 执行应该有： ```ts interface AgentRun { id: string goalId: string status: AgentRunStatus model?: string provider?: string iterations: number tokenUsage?: TokenUsage cost?: ExecutionCost startedAt?: Date completedAt?: Date } ``` --- # 63. Agent Step ```ts interface AgentStep { id: string runId: string type: | "thought" | "plan" | "tool_call" | "observation" | "evaluation" | "approval" capabilityId?: string input?: unknown output?: unknown status: string createdAt: Date } ``` 注意： > 不要求把模型内部完整思维过程持久化或展示。 只保存： ```text decision summary action result reason / metadata ``` --- # 64. Agent Trace UI： ```text Agent Run ──────────────────────────── Goal 10天完成 SEO Campaign Step 1 ✓ Website Scan Step 2 ✓ Keyword Research Step 3 ✓ Content Plan Step 4 ⏳ Generate Content Step 5 ○ Publish Step 6 ○ Backlinks ``` 点击 Step： ```text Capability Input Execution Output Cost Logs ``` --- # 65. Agent 与 Event Agent 可以订阅 Event： ```text deployment.completed website.scan.completed content.published ``` 例如： ```text Event ↓ Agent Observation ↓ Agent Decision ``` --- # 66. Agent 与 Scheduler Scheduler 可以启动 Agent Goal： ```text 每天 02:00 ↓ Create Agent Goal ↓ Agent Run ``` 例如： ```text 每天检查所有网站 SEO 健康状态。 ``` --- # 67. Agent 与 Webhook Webhook： ```text GitHub Push ↓ Event ↓ Agent Trigger ↓ Goal ↓ Plan ``` --- # 68. Agent Trigger 统一： ```ts interface AgentTrigger { type: | "manual" | "schedule" | "event" | "webhook" config: unknown goalTemplate: unknown } ``` --- # 69. Agent 与 Plugin Plugin 提供： ```text Capability Skill MCP ``` Agent 自动发现。 因此 Plugin 安装： ```text Install SEO Plugin ``` 之后 Agent 自动拥有： ```text SEO Skills SEO Actions SEO MCP ``` 无需修改 Agent Core。 --- # 70. 这是 DevOS 的关键扩展机制 最终： ```text 安装 Plugin ↓ Resources Actions Skills MCP UI ↓ Capability Registry ↓ Agent 自动发现 ``` 因此： > **增加 Agent 能力，不需要修改 Agent。** 只需要增加 Plugin。 --- # 71. AI SEO 示例 用户： ```text 10天内给 a.com 做100篇软文 + 200个外链。 ``` Agent： ```text Goal ↓ Discover Skills ↓ seo.campaign.execute ``` Skill： ```text 需要： website keyword data content capability backlink capability ``` Capability Discovery： ```text seo.website.scan seo.keyword.research seo.content.generate seo.content.publish seo.backlink.submit ``` --- # 72. Agent Plan ```text 1. Scan website 2. Research keywords 3. Build content strategy 4. Generate 100 articles 5. Publish articles 6. Find backlink opportunities 7. Submit backlinks 8. Verify 9. Report ``` 但是： > Agent 不一定一次性执行全部步骤。 可能： ```text Scan ↓ Observe ↓ Replan ↓ Keyword Research ↓ Observe ↓ Generate ``` --- # 73. 批量任务 100 篇文章不能： ```text Agent ↓ 生成 100 × Tool Call ``` 应该： ```text Agent ↓ Create Task ↓ Task creates Jobs ↓ 100 Jobs ↓ Queue ↓ Workers ``` Agent 只负责： ```text 规划 ``` 而不是亲自执行 100 个工作单元。 --- # 74. Agent 与 Task 的边界 ```text Agent: “What should we do?” Task: “What work needs to be done?” Action: “How do we execute it?” Execution: “What actually happened?” ``` 这是整个 AI Runtime 的核心分层。 --- # 75. Agent 不应该控制 Queue 错误： ```text Agent ↓ Redis ↓ Queue ``` 正确： ```text Agent ↓ Task Runtime ↓ Queue Runtime ``` --- # 76. Agent 不应该控制 Worker 同样： ```text Agent ↓ Worker ``` 禁止。 Agent 只： ```text Create Task Execute Action Observe Result ``` --- # 77. AI Runtime API 建议： ```text POST /agents/goals GET /agents/goals GET /agents/goals/:id POST /agents/goals/:id/cancel GET /agents/runs/:id GET /agents/runs/:id/steps POST /capabilities/search GET /capabilities/:id GET /skills GET /skills/:id ``` --- # 78. Capability API ```http POST /api/capabilities/search ``` Request： ```json { "query": "deploy application", "types": ["action", "skill", "workflow"], "limit": 10 } ``` Response： ```json { "items": [ { "id": "application.deploy", "type": "action", "name": "Deploy Application" } ] } ``` --- # 79. Capability Detail API ```http GET /api/capabilities/application.deploy ``` 返回： ```text Input Schema Output Schema Permissions Description Examples Provider Version ``` --- # 80. Skill API ```http GET /api/skills/seo.website.audit ``` 返回： ```text Description Inputs Outputs Required Capabilities Instructions Examples ``` --- # 81. MCP Gateway 推荐： ```text packages/mcp/ ``` 结构： ```text MCP Runtime ├── MCP Server ├── MCP Client ├── Tool Registry ├── Resource Registry ├── Prompt Registry └── Adapter ``` --- # 82. Agent Runtime Package ```text packages/agent/ ├── runtime ├── planner ├── executor ├── observer ├── evaluator ├── memory ├── policy └── budget ``` --- # 83. Skill Runtime ```text packages/skill/ ├── registry ├── loader ├── resolver ├── validator └── runtime ``` --- # 84. Capability Runtime ```text packages/capability/ ├── registry ├── discovery ├── resolver ├── ranking ├── permission-filter └── adapters ``` --- # 85. 模型 Provider Agent Runtime 不应该绑定单一 LLM。 统一： ```ts interface ModelProvider { generate(request: ModelRequest): Promise stream(request: ModelRequest): AsyncIterable } ``` 支持： ```text OpenAI Anthropic Google Local OpenRouter Custom ``` --- # 86. Model Registry ```text Model Registry ``` 记录： ```text Provider Model Context Window Pricing Capabilities Vision Tool Calling Structured Output ``` Agent 可以选择： ```text cheap model fast model reasoning model vision model ``` --- # 87. Model Policy 不同任务可以选择不同模型： ```text 简单分类 → Fast / Cheap 复杂 Planning → Reasoning 图片分析 → Vision ``` 不要把模型选择硬编码进 Agent。 --- # 88. Structured Output Planner 必须尽量使用： ```text JSON Schema ``` 例如： ```ts const planSchema = z.object({ steps: z.array(...) }) ``` 避免： ```text LLM ↓ 纯文本 ↓ 正则解析 ``` --- # 89. Agent Error Handling Agent 可能遇到： ```text Capability unavailable Permission denied Tool failed Invalid input Timeout Budget exceeded Model error ``` 统一处理： ```text Retry Fallback Replan Ask Human Fail ``` --- # 90. Human-in-the-loop Agent 不应该永远自动完成。 可以： ```text Agent ↓ Need decision ↓ Human Approval ↓ Continue ``` Task： ```text waiting ``` Approval 完成： ```text running ``` --- # 91. Agent Chat 聊天只是 Agent 的一个入口。 ```text Chat ↓ Agent Goal ``` 而不是： ```text Chatbot = Agent Runtime ``` 未来还可以： ```text API CLI Scheduler Webhook MCP ``` 创建 Goal。 --- # 92. Agent UI 推荐： ```text Agents ├── Agents ├── Goals ├── Runs ├── Skills ├── Capabilities └── Models ``` Agent Detail： ```text Agent ──────────────── Capabilities Skills Policies Models Memory Runs Cost ``` --- # 93. Agent Run UI ```text Goal │ ├── Planning ✓ │ ├── Website Scan ✓ │ ├── Keyword Research ✓ │ ├── Generate Content ⏳ │ └── Publish ○ ``` 每一步都能进入： ```text Task Execution Logs Output ``` --- # 94. Agent Debug Mode 开发环境必须支持： ```text Agent Trace Capability Discovery Selected Skill Plan Tool Calls Execution IDs Task IDs Cost Errors ``` 这样开发者才能调试 Agent。 --- # 95. 不要实现“万能 Agent” 第一版不要： ```text One giant agent ``` 推荐： ```text Agent Runtime + Agent Profiles ``` 例如： ```text General Agent SEO Agent DevOps Agent Content Agent ``` 它们共用 Runtime。 --- # 96. Agent Profile ```ts interface AgentProfile { id: string name: string description?: string systemInstructions?: string allowedSkills?: string[] allowedCapabilities?: string[] deniedCapabilities?: string[] modelPolicy?: ModelPolicy budget?: AgentBudget policy?: AgentPolicy } ``` --- # 97. SEO Agent ```text SEO Agent │ ├── Skills │ ├── seo.audit │ ├── seo.content │ └── seo.backlink │ ├── Capabilities │ └── seo.* │ └── Policy ``` 它不需要独立 Runtime。 --- # 98. DevOps Agent ```text DevOps Agent │ ├── server.* ├── docker.* ├── deployment.* └── monitoring.* ``` 依旧使用： ```text Agent Runtime ``` --- # 99. 最终完整链路 ```text User │ ▼ Goal │ ▼ Agent Runtime │ ┌───────┴───────┐ ▼ ▼ Skill Capability Search │ │ └───────┬───────┘ ▼ Plan │ ▼ Task │ ▼ Job │ ▼ Action │ ▼ Action Runtime │ ▼ Execution │ ▼ Event │ ▼ Observation │ ▼ Agent │ ┌───────┼────────┐ ▼ ▼ ▼ Continue Replan Complete ``` --- # 100. MCP 的完整位置 ```text Agent │ ▼ Capability Layer │ ┌────────┼─────────┐ ▼ ▼ ▼ Action Skill MCP │ │ │ ▼ │ External System │ ▼ Action Runtime ``` MCP 是能力来源 / 适配层，不是 DevOS 的第二套业务执行系统。 --- # 101. Plugin 的完整位置 ```text Plugin │ ├── Resource ├── Action ├── Skill ├── MCP ├── Workflow └── UI │ ▼ Capability Registry │ ▼ Agent ``` 所以： > **Plugin 是能力供应商，Agent 是能力消费者。** --- # 102. 黄金规则 ### Rule 1 ```text Agent 不直接操作数据库 ``` ### Rule 2 ```text Agent 不直接操作 Queue ``` ### Rule 3 ```text Agent 不直接操作 Worker ``` ### Rule 4 ```text Agent 必须通过 Capability / Action 执行 ``` ### Rule 5 ```text Skill 不直接执行底层业务 ``` ### Rule 6 ```text MCP 不绕过 Action Runtime ``` ### Rule 7 ```text Agent Task 必须使用 DevOS Task Runtime ``` ### Rule 8 ```text Agent 必须经过 Permission / Policy ``` ### Rule 9 ```text Agent Capability Discovery 必须进行权限过滤 ``` ### Rule 10 ```text 不要一次向 LLM 暴露全部 Tools ``` ### Rule 11 ```text 优先高层 Business Action ``` ### Rule 12 ```text Agent Runtime 不绑定具体模型 ``` --- # 103. Zcode 实现要求 新增： ```text packages/ ├── capability/ ├── skill/ ├── agent/ └── mcp/ ``` 核心模块： ```text CapabilityRegistry CapabilityDiscovery CapabilityResolver CapabilityRanker SkillRegistry SkillLoader SkillResolver AgentRuntime AgentPlanner AgentExecutor AgentObserver AgentEvaluator AgentMemory AgentPolicy AgentBudget MCPServer MCPClient MCPToolRegistry MCPAdapter ModelRegistry ModelProvider ``` --- # 104. 第一阶段验收 Demo Zcode 必须完成以下完整演示。 ## Demo 1：Capability Discovery 输入： ```text deploy application ``` 返回： ```text application.deploy docker.build server.health_check ``` --- ## Demo 2：Skill Discovery 输入： ```text SEO audit ``` 返回： ```text seo.website.audit ``` --- ## Demo 3：Agent Goal 输入： ```text 检查 example.com 的 SEO ``` 完整链路： ```text Goal ↓ Agent ↓ Skill ↓ Capability Discovery ↓ seo.website.scan ↓ Task ↓ Execution ↓ Result ↓ Agent ↓ Report ``` --- ## Demo 4：MCP 外部 MCP Tool： ```text seo_scan_website ``` 最终： ```text MCP ↓ seo.website.scan ↓ Action Runtime ``` --- ## Demo 5：Plugin → Agent 安装： ```text GitHub Plugin ``` 之后： ```text Capability Registry ``` 自动出现： ```text github.repository.* ``` Agent 可以立即发现这些能力。 **不允许修改 Agent Runtime 源码。** --- # 105. 最终目标 完成 `06` 后，DevOS 的核心已经形成： ```text ┌───────────────┐ │ Agent │ └───────┬───────┘ │ Skill / Plan │ ▼ Capability Registry │ ┌─────────────┼─────────────┐ ▼ ▼ ▼ Action MCP Workflow │ │ │ └─────────────┼─────────────┘ ▼ Action Runtime │ ▼ Task │ ▼ Job │ ▼ Queue │ ▼ Worker │ ▼ Execution │ ▼ Event │ ▼ Observation │ └──────→ Agent ``` 这一步完成后，DevOS 就不再只是一个“后台框架”。 它实际上开始形成： > **Resource Runtime + Action Runtime + Plugin Runtime + Execution Runtime + Capability Runtime + Agent Runtime** 这几个 Runtime 共同构成你后面真正可以反复复用的 **DevOS Application/Agent Platform Core**。