1. 项目概述Myco一个为AI智能体而生的“活”认知基板如果你和我一样在过去一年里频繁地在LangChain、LangGraph、CrewAI、DSPy这些框架之间切换每次新框架发布都意味着一次痛苦的迁移和重构那么你一定能理解那种“技术债”不断累积的疲惫感。更令人沮丧的是我们为AI智能体构建的“记忆”或“知识库”往往是脆弱且割裂的——上周刚读懂的API文档这周可能就过时了上个月项目会议做出的关键决策这个月的AI助手已经毫无印象每次对话都像是从零开始。我们不是在构建一个持续成长的伙伴而是在不断地打补丁和重启。Myco的出现正是为了解决这个核心痛点。它不是一个框架也不是一个向量数据库更不是一个托管服务。你可以把它理解为一个专为AI智能体设计的“活”文件系统或者说一个认知基板。它的核心思想非常激进让智能体自身成为其知识系统的维护者。所有智能体读取或写入的内容——代码片段、论文、决策记录、遇到的“摩擦”即问题与解决过程——都以Markdown和YAML的形式存储在你的本地文件系统上并通过一个类似菌丝网络的图结构相互链接。这个系统会自主地“吞噬”原始材料将其“消化”为整合的知识进行“免疫检查”以防止知识漂移在不同项目间“传播”学习成果并且当你的工作模式进化、旧的结构不再适用时它能够“重塑”自身。最酷的一点是实现这一切的Myco内核本身也是一个基板。它的源代码、配置文件、设计文档都以同样的方式组织并且默认是可编辑的。这意味着维护Myco系统的智能体与使用Myco的智能体可以是同一个。这解决了早期类似系统最大的失败原因人类维护者跟不上系统演化的速度。Myco将“维护者即智能体”这一理念烘焙进了它的每一个交互界面、每一个操作指令它称之为“动词”和每一条规则中。2. 核心理念与设计哲学拆解2.1 从“工具链”到“生命体”的范式转变传统AI开发栈是“工具链”思维你需要组合检索增强生成、向量数据库、工作流引擎、记忆模块等多个独立组件。每个组件都有自己的数据格式、API和生命周期整合和维护成本高昂。Myco则采用了“生命体”的隐喻其设计深受真菌菌丝网络Mycelium的启发这也是其名字的由来。菌丝网络是一个去中心化的、高度互联的、能够不断生长和适应环境的生命系统。Myco模拟了这种生物特性去中心化存储知识以文件形式散落在项目目录中而非集中于某个数据库降低了单点故障风险也更符合开发者的直觉。高度互联通过图结构链接任何知识点都能通过“遍历”找到关联上下文避免了信息孤岛。持续代谢系统不是静态的它通过“摄入-消化-循环-自稳-进化”这一套代谢循环持续更新自身。自我进化当环境你的工作需求改变时系统能够通过一套严谨的“工艺循环”来改变自身的规则和结构。这种转变的核心优势在于可持续性。你不再需要为下一个“颠覆性”框架做迁移准备因为系统自身就包含了演化的能力。2.2 五大设计原则的深层解读Myco的文档中提到了五个原则这不仅仅是口号而是贯穿其所有行为的铁律。只为智能体Only for the agent这是最反直觉也最重要的一点。Myco的所有界面CLI、MCP工具、文件格式的首要服务对象是AI智能体而非人类。这意味着文件命名、YAML结构、提示词模板都是为了被LLM高效解析和理解而优化的。人类当然可以阅读和编辑但那不是设计的首要目标。这确保了智能体与系统之间极低的认知摩擦。吞噬一切Devour everything在信息摄入阶段不做预设过滤。其逻辑是错过一个潜在的重要信号比如一段看似无关的日志或评论的成本远高于摄入一段冗余信息的成本。智能体在后续的“消化”环节中会自行判断信息的价值和关联性。这鼓励了最大程度的信息保留为后续的知识连接提供了丰富的原材料。自我演化的形态Self-evolving shapeMyco的“规范”、检查维度lint dimensions、操作动词verbs乃至其核心“契约”本身都是可以通过一个受治理的“工艺循环”来修改的。这通过fruit、winnow、molt等动词实现。系统不会因为最初设计的局限而僵化。没有什么是终局Nothing is final“已整合”只是一个状态而非终点。今天得出的结论明天可能成为需要被重新审视的原始材料。这体现了知识永续迭代的科学精神避免了认知固化。菌丝网络Mycelium network每个知识节点都必须通过遍历与其他节点相连。孤立的节点被视为“死组织”会被系统标记并在“免疫”检查中提示。这强制性地保证了知识图谱的连通性和活性。实操心得刚开始接触这五大原则时尤其是“只为智能体”可能会感到不适应。我们习惯了为人设计的UI/UX。但当你尝试以智能体的视角去思考——它如何查找、如何理解、如何连接信息——你就会发现Myco的这种设计极大地提升了人机协作的流畅度。你不再需要“教”AI如何使用你的笔记系统因为它本身就是这个系统的一部分。3. 核心架构与工作流程详解3.1 核心组件文件系统即数据库Myco的“数据库”就是你的项目目录。典型的一个Myco化项目根目录下会有以下关键结构your-project/ ├── .myco/ # Myco运行时目录可选用于插件等 ├── _canon.yaml # **核心配置文件**定义该基板的“宪法” ├── MYCO.md # 智能体的入口页面相当于系统桌面/仪表盘 ├── raw/ # 原始材料区存放未经处理的输入 │ ├── 2024-05-10-meeting-notes.md │ └── api_docs_v2.pdf.ingested.md ├── integrated/ # 已整合知识区存放消化后的结构化知识 │ ├── project-context.md │ └── key-decisions.md └── ... (你的项目源码文件)_canon.yaml这是基板的“宪法”。它定义了系统的“书写表面”哪些文件/目录可写、核心概念字段、关联规则、以及所有可执行动词的清单。智能体的任何写入操作都必须在此文件允许的范围内否则会被WriteSurfaceViolation拒绝。MYCO.md这是智能体会话的起点。它通常包含当前项目的状态摘要、待办事项、最近的活动记录以及到其他重要节点的链接。智能体每次会话都会先读取此文件。raw/ 与 integrated/体现了“代谢”的两阶段。raw是胃存放刚“吃”进去的东西integrated是细胞存放消化吸收后融入身体的知识。3.2 十八个动词智能体的“生命活动”Myco的所有功能都通过18个以真菌生物学命名的“动词”暴露出来分为六个子系统。理解这些动词是掌握Myco的关键。1. 萌发 (Germination)germinate在指定目录初始化一个新的Myco基板。它会创建_canon.yaml、MYCO.md等基础文件结构。2. 摄入 (Ingestion)hunger分析当前知识状态向智能体报告“缺少什么”。这是一个引导性的发现工具。eat吞噬指令。可以将一个文件路径、URL或一段文本作为“原始材料”摄入系统通常存入raw/目录。sense关键词搜索。在现有的知识图谱中进行检索。forage扫描。在文件系统中扫描可能可摄入的路径如新的文档、日志文件。3. 消化 (Digestion)assimilate将raw/中的一条或多条记录“消化”成integrated/中的知识。这个过程通常由LLM执行提取关键信息、建立联系、并格式化。digest提升单条笔记的状态。可以是将一条raw笔记标记为已处理或深化一条integrated笔记。sporulate孢子化。将多条已整合的知识浓缩、提炼生成一个可供传播的提案或总结报告类似于生成“孢子”用于传播。4. 循环 (Circulation)traverse遍历菌丝图。从一个节点出发按照链接探索相关知识网络用于发现关联或检查图谱健康度。propagate传播。将本基板中的学习成果发布到一个下游基板如一个共享的知识库或另一个项目。5. 稳态 (Homeostasis)immune免疫检查。运行一个包含25个维度的lint检查覆盖机械性错误、版本一致性、代谢健康度、语义连通性等。--fix参数可以自动修复其中可机械修复的问题。senesce衰老。优雅地结束一个会话执行清理工作并将会话状态归档为下一次会话做好准备。6. 进化 (Evolution)fruit结果。当现有系统形态无法满足需求时如需要新的检查维度起草一份为期三轮的“工艺”提案文档详细阐述变更理由和设计。winnow筛选。对fruit产生的提案进行评审和把关决定是否采纳其形态。molt蜕皮。执行被批准的契约变更更新_canon.yaml和系统代码实现“进化”。ramify分支。为新的检查维度、动词或适配器搭建代码脚手架。graft嫁接。管理基板本地的插件。brief简报。生成一份面向人类的状态汇总报告。注意事项这18个动词不仅通过CLI (myco verb) 调用更重要的是通过MCP暴露给AI智能体。这意味着在你的代码编辑器如Cursor、VSCode或AI助手如Claude Desktop中智能体可以直接调用这些工具实现与Myco基板的无缝交互。动词清单在src/myco/surface/manifest.yaml中统一定义是CLI和MCP工具的唯一事实来源。3.3 自我验证与契约执行不信任要验证Myco对其服务的智能体也持谨慎态度。它不假设智能体会永远记得规则而是通过机制强制执行。25维Lint检查myco immune命令会从四个类别进行检查机械性规范一致性、书写表面合规、LLM交互边界是否清晰。已发布PyPI包版本与本地规范版本是否一致。代谢性原始材料积压是否过多已整合笔记是否过于陈旧。语义性图谱连接性如何是否存在孤儿节点。 这就像一个持续的体检确保系统健康。七条硬性规则这些规则编码在MCP服务器内部对所有客户端强制生效。R1 (启动仪式)每次会话必须从读取MYCO.md和_canon.yaml开始。R2 (会话结束)必须通过senesce结束会话。R3 (断言前感知)在做出断言或建议前必须先使用sense或traverse确认现有知识。R4 (摩擦时吞噬)遇到问题或“摩擦”时必须将其作为原始材料eat进去。R5 (创建时交叉引用)创建新笔记时必须链接到相关现有笔记。R6 (书写表面纪律)所有写入必须严格在_canon.yaml允许的范围内。R7 (自上而下分层)修改需遵循从愿景到契约再到实现的层级。 违反规则会导致操作被拒绝并收到明确的错误提示。脉冲侧信道每次MCP工具调用返回时都会附带一个substrate_pulse字段其中包含当前契约版本和一个规则提示。随着会话进行提示的规则等级会从R1逐渐上升到R7作为一种持续的、服务端推动的提醒。4. 完整实操从零搭建你的第一个Myco智能体伙伴4.1 环境准备与安装Myco推荐使用可编辑模式安装因为它的内核本身就是一个可演化的基板。# 使用 pipx 确保环境隔离并安装包含MCP服务器功能的版本 pipx run --spec myco[mcp] myco-install fresh ~/myco-kernel这条命令会将Myco的GitHub仓库克隆到~/myco-kernel。以可编辑模式 (pip install -e) 安装这个本地副本。你将得到一个可读写的Myco内核源代码树。接下来为你现有的任何一个项目初始化Myco基板cd /path/to/your/existing-project myco germinate . --substrate-id my-awesome-project执行后你的项目根目录下会生成_canon.yaml和MYCO.md文件。打开_canon.yaml你会看到初始化的“书写表面”配置、系统字段定义等。MYCO.md则是一个简单的欢迎页面。4.2 与AI工作流集成以Claude Desktop为例Myco通过MCP与各种AI客户端集成。以下是配置Claude Desktop或Cowork本地代理模式的步骤配置MCP服务器告诉Myco你的Claude Desktop配置路径。myco-install host cowork这会在Claude Desktop的MCP服务器配置文件中添加指向本地Myco服务器的条目。安装插件包从Myco的GitHub Releases页面下载最新的.plugin文件例如myco-0.9.0.plugin。拖拽安装打开Claude Desktop进入 Settings → Plugins将下载的.plugin文件拖入窗口。Claude Desktop会将其上传到你的私有Cowork市场。自动生效此后每次启动Claude Desktop的新会话它都会自动安装myco-substrate引导技能。一旦智能体检测到当前目录存在_canon.yaml它就会开始遵循R1-R7规则并可以使用所有18个动词。4.3 一个完整的工作会话模拟假设你正在开发一个名为“绿野OCR”的项目并已初始化Myco基板。以下是一个模拟的人机协作会话人类 (你)“我打算集成一个新的PDF解析库‘PyPDF2’替换掉现在的旧方案。帮我调研一下并更新项目。”AI智能体 (通过MCP调用Myco)遵循R1首先读取MYCO.md和_canon.yaml了解项目上下文和规则。遵循R3执行myco sense PyPDF2 pdf parsing在现有知识中搜索是否已有相关记录。发现空白未找到有效信息。智能体通过myco hunger分析确认“第三方库集成方案”是知识缺口。执行调研智能体利用其网络搜索能力找到PyPDF2官方文档和几篇评测博客。遵循R4智能体执行myco eat --url https://pypi.org/project/PyPDF2/和myco eat --text 博客内容...将这些原始材料存入raw/目录。消化知识智能体执行myco assimilate --raw-ids id1 id2让LLM总结PyPDF2的特性、API、优缺点、迁移注意事项生成一条结构化的笔记存入integrated/pypdf2-migration.md。遵循R5在创建这条新笔记时智能体自动在其YAML头中添加链接指向integrated/current-ocr-pipeline.md现有方案和integrated/project-requirements.md项目需求。提供建议智能体基于新整合的知识在聊天界面给出一个具体的迁移步骤草案并询问你的意见。实施与记录在你同意后智能体修改项目代码。同时它将本次代码变更的diff和决策理由通过myco eat存入raw/作为一次“摩擦”记录以备未来查阅。遵循R2工作结束时你或智能体触发myco senesce本次会话的所有临时状态和上下文被妥善归档。几周后你遇到一个PyPDF2的解析怪问题。 你直接问AI“为什么PyPDF2在这里解析会乱码” AI智能体会再次遵循R1/R3读取上下文并搜索。通过myco traverse从integrated/pypdf2-migration.md节点出发找到当时记录决策的raw笔记以及更早之前关于编码问题的讨论。结合历史记录和当前问题给出更精准的答案甚至可能发现这是该库的一个已知限制并提议myco eat这个新发现。至此知识形成了闭环并且随着时间不断积累和连接。4.4 进阶操作自定义与进化当你的团队形成固定工作流需要Myco跟踪“代码审查意见”这个新概念时创建新字段你可以直接编辑_canon.yaml在canon.fields下添加code_review字段及其定义。但更“Myco”的方式是启动一个进化流程。发起进化运行myco fruit --type new-field --name code_review。这会启动一个三轮的“工艺”流程在docs/primordia/下生成一份提案文档要求你和智能体详细阐述添加此字段的理由、数据类型、与其他字段的关系等。评审与落地经过讨论和修改后使用myco winnow对该提案进行评审。通过后使用myco molt来执行变更自动更新_canon.yaml和相关代码。扩展检查你还可以运行myco ramify --dimension semantic来为这个新字段创建一个语义lint检查的脚手架确保每条code_review笔记都关联到具体的代码文件。5. 常见问题与深度排查指南5.1 安装与集成问题Q1:pipx run安装失败提示找不到命令或版本冲突A1: 确保你的Python版本在3.10以上并且pipx已正确安装。可以尝试分步操作# 先使用pipx安装myco到独立环境 pipx install myco[mcp] # 然后使用已安装的myco-install命令 myco-install fresh ~/myco-kernel如果问题依旧检查网络连接或者尝试从GitHub直接克隆并手动安装git clone https://github.com/Battam1111/Myco.git ~/myco-kernel cd ~/myco-kernel pip install -e .[mcp]Q2: 集成到Cursor/VSCode后AI助手无法调用Myco工具A2: 首先确认MCP服务器配置是否正确。检查客户端的配置文件中MCP服务器列表是否包含类似如下的条目{ mcpServers: { myco: { command: /path/to/your/python, args: [-m, mcp_server_myco], env: {MYCO_SUBSTRATE_PATH: /path/to/your/project} } } }MYCO_SUBSTRATE_PATH环境变量至关重要它告诉Myco服务器当前操作的基板是哪个项目。在Cursor中这通常需要配置在~/.cursor/mcp.json中。最可靠的方法是重新运行myco-install host cursor并重启你的编辑器。Q3: Claude Desktop拖拽安装插件后新会话没有自动加载Myco技能A3: Cowork的插件管理有时有延迟。首先在Claude Desktop的设置-插件页面确认myco-substrate插件已启用。其次确保你是在包含_canon.yaml的项目目录下启动的对话。如果还不行尝试在Claude Desktop的会话中手动输入/install myco-substrate命令。最后检查Cowork的本地代理模式是否已激活。5.2 使用与操作问题Q4: 执行myco eat摄入一个大型代码库时卡住或报错A4:eat命令默认可能尝试解析整个目录。对于大型代码库建议分而治之使用--pattern参数只摄入特定文件类型如myco eat ./src --pattern *.py。先使用myco forage ./src扫描并查看有哪些文件会被识别再选择性地摄入。对于非常大的仓库考虑先摄入架构文档 (README.md,ARCHITECTURE.md)让智能体先建立高层认知再按模块分批摄入。Q5:myco immune检查出大量“孤儿节点”或“图谱连接性低”警告怎么办A5: 这是新手最常见的问题意味着你的笔记之间缺乏足够的链接。立即修复运行myco immune --fixMyco会尝试自动为一些节点添加基础链接。手动优化关键在于养成习惯。每次创建新笔记尤其是integrated下的务必使用--links参数或在YAML头中手动添加links:字段指向相关的已有笔记。可以定期运行myco traverse --from 某个核心笔记来可视化检查图谱。重新消化对于早期创建的一批孤立笔记可以将其ID列出用myco assimilate --raw-ids ids重新消化一次并在过程中提示LLM“注意与现有笔记X, Y, Z建立关联”。Q6:myco propagate失败提示下游基板不兼容A6:propagate用于将知识发布到另一个Myco基板。失败通常是因为两个基板的_canon.yaml中定义的“规范”不兼容。检查下游基板的_canon.yaml版本是否与上游一致或兼容。查看myco.symbionts目录下是否有对应的适配器。propagate可能需要特定的适配器来处理字段映射。更简单的方式是先将上游的笔记通过myco sporulate生成一个独立的、自包含的提案文件如Markdown报告然后手动或通过其他方式分享在下游基板中再用myco eat摄入这个文件。5.3 理念与实践冲突Q7: “只为智能体”原则导致文件对人类可读性差团队协作困难A7: 这是一个需要权衡的点。Myco的默认格式确实优先考虑机器解析。利用brief命令定期运行myco brief生成一份面向人类的状态摘要报告这份报告格式更友好可用于团队同步。自定义渲染你可以编写简单的脚本或使用myco的Python API读取基板数据按照团队喜欢的格式如Confluence页面、Notion数据库生成报告。渐进式采纳在团队中可以先由技术负责人或AI助手主要维护Myco基板其他人通过brief报告和智能体问答来消费知识而不直接编辑原始文件。Q8: 七条规则太严格感觉限制了智能体的灵活性A8: 规则的严格性正是为了保障系统的长期健康避免混乱。如果你觉得某个规则在特定场景下确实不适用这正是启动“进化”流程的信号。你可以和智能体一起使用myco fruit --type amend-rule --rule R3来发起修改R3规则的提案。在提案中你需要详细论证在何种情况下可以放宽“断言前感知”的要求以及如何防止滥用。通过这种严谨的流程来修改规则本身就是在践行“自我演化”的原则比随意关闭规则要可持续得多。Q9: 如何将Myco与现有的文档系统如Wiki、Notion结合A9: Myco不旨在取代所有系统而是作为AI原生的“工作记忆”层。作为缓存和索引层让Myco专注于存储高频、细粒度、与当前编码活动强相关的知识。将Mycosporulate产生的总结性提案定期同步到团队的Wiki或Notion作为“官方文档”。反向同步对于Notion/Wiki中的重要更新可以手动或通过自动化脚本将其内容导出为Markdown然后用myco eat摄入到相关项目的基板中确保智能体也知道这些变化。MCP适配器理论上可以为Notion等开发一个MCP服务器让Myco的智能体也能直接查询这些外部系统。但这属于高级定制开发。在我深度使用Myco的几个月里最大的体会是它改变了我与AI协作的心智模式。我不再把它当作一个每次都要从头解释的“实习生”而是一个有持续记忆和成长能力的“同事”。项目初期的磨合成本确实存在需要耐心配置和习惯养成。但一旦跨过那个临界点当你能自然地对AI说“记得我们上周讨论的架构取舍吗基于那个看看这个问题……”并得到连贯的回应时那种流畅感是革命性的。它或许不是所有场景的银弹但对于需要长期维护、知识密集型的软件项目或研究课题而言Myco提供了一条让AI真正融入工作流、沉淀为团队资产的切实路径。