zymi-core 是一个面向 AI 智能体的可审计 MCP 后端，核心思路是把智能体在试错中收敛出的操作流程编译成声明式 YAML 流水线，让这些流程在智能体不在场时也能稳定、可复现地运行。它被定位为受治理、可复现的底层执行层，而不是自主智能体、IDE 插件或聊天界面。
用途 当用户让编码智能体添加 VPN 用户、部署服务或清理服务器时，智能体往往需要反复试错才能完成；一周后再执行类似任务，智能体可能重新推导出略有差异的步骤，或者因限流、离线而无法执行，且没人记得具体步骤。zymi 针对这一场景，把智能体收敛出的流程固化为 YAML 流水线：大多数步骤是确定性的工具调用，仅在真正需要判断的地方引入 LLM。此后流水线可以脱离智能体独立运行，也可以作为单个 MCP 工具供智能体调用，危险步骤需人工审批，每次运行都有不可篡改的事件记录。
主要能力 流水线：由带 depends_on 边的步骤组成 DAG，独立步骤可并行执行。步骤类型包括：确定性工具步骤（直接分发、参数模板化，无 LLM 跳转）、智能体步骤（带工具白名单的 LLM ReAct 循环）、询问步骤（运行暂停并向调用方提问，终端下由人类回答，MCP 下由连接的智能体回答，然后恢复）。步骤可携带 when 条件实现分支，跳过的分支会级联到后代并记录为 StepSkipped 事件。 工具：支持四类工具，统一编目。声明式 shell/HTTP 工具写在 tools/<name>.yml 中，无需代码；Python @tool 写在 tools/<name>.py 中，支持同步或异步，签名自动映射为 JSON Schema 并自动发现，运行在项目自己的 .venv 中；MCP 服务器，一个 mcp_servers: 条目提供 N 个工具，命名空间为 mcp__<server>__<tool>；内置工具包括 read_file、write_file、write_memory、execute_shell_command、spawn_sub_agent。四类工具都发出相同的 ToolCallRequested / ToolCallCompleted 事件。 MCP 服务器：通过 zymi mcp serve 以 stdio 方式将流水线暴露为 MCP 工具，供 Claude Code、Claude Desktop、Cursor 或任何带 MCP 适配器的框架使用。暴露按流水线选择性开启。审批在调用方 UI 中呈现，门控步骤通过活动的 tools/call 发送 elicitation/create，在 Claude Code 中表现为批准/拒绝表单；不支持 elicitation 的客户端会失败关闭。ask: 步骤借用调用方的推理能力，任务增强调用会进入 input_required 状态并携带 { prompt, resume_token }，智能体通过 zymi/reasoning/resume 回答，答案被记录以保证重放字节一致。--expose-observability 可添加只读的 zymi.runs.list / .get / .events / .step_io，让智能体调试自己的运行。 审批：工具上设置 requires_approval: true 会发布 ApprovalRequested 事件，通过通道将人类决定路由回来。通道包括 terminal、http、telegram、mcp_elicitation。解析顺序为流水线覆盖 → 项目默认 → 失败关闭。审批中途崩溃可在重启后修复。 重放、恢复与观察：每次状态变化都是不可变的哈希链事件，可重放、从任意步骤分叉恢复、在 TUI 中浏览，或让智能体读取自己的运行轨迹来解释失败。 长运行服务：zymi serve 响应来自声明式连接器的事件（http_inbound、http_poll、cron、file_read、stdin），并通过输出（http_post、file_append、stdout）应答。默认使用 SQLite，可通过一行 postgres://… 配置多进程共享状态。 上下文窗口管理：智能体的上下文每次迭代从事件日志重建，而非在缓冲区累积；较旧的观察被就地遮蔽，仅在预算仍然紧张时，才用一次摘要调用压缩最旧的一批。 Python 嵌入：在项目 venv 中安装 zymi-core（uv add zymi-core）后，同一个 wheel 暴露 Runtime、Event、EventBus、EventStore、ToolRegistry 和 @tool 装饰器。
使用方式 安装 uv（如未安装）：macOS/Linux 执行 curl -LsSf https://astral.sh/uv/install.sh | sh，Windows 执行 irm https://astral.sh/uv/install.ps1 | iex。~/.zymi 是一个普通 zymi 项目，当不在其他项目内时所有命令都会回退到它。可添加自己的流水线（例如站点检查），在 ~/.zymi/project.yml 中允许命令（policy.allow: ["curl *"]，未列出的命令会先请求审批），然后运行 zymi run site_check。运行、参数和输出会记录在 ~/.zymi/.zymi/events.db 中，zymi observe 可查看。将任何 MCP 宿主指向该库，每个带 expose.mcp: 块的流水线都会成为工具。模型端点可在 ~/.zymi/providers.yml 中按机器声明一次，并通过名称引用（llm: neuraldeep 或 llm: { use: neuraldeep, model: other }），密钥存放在 ~/.zymi/.env。无法解析的提供者只会禁用智能体步骤，纯工具流水线仍可工作。命令使用 --dir，否则若当前目录是项目则用当前目录，否则用 ~/.zymi。
适用场景 适合需要将智能体反复推导的操作流程固化为可复现、可审计流水线的场景，例如运维操作、部署、用户管理、站点检查等；也适合希望以 MCP 工具形式向编码智能体提供受治理流程的团队，以及需要审批门控和事件溯源记录的环境。
限制 官方文档明确说明：异步任务内的审批等待宿主采纳并会超时（同步调用完全可交互）；取消是尽力而为；参数跨边界以字符串传递；mcp serve 目前仅支持 Unix。zymi 有意不是自主智能体、IDE 插件或聊天 UI。
