fyllo-cortex MCP

fyllo-cortex 是 FylloCode 内置的 MCP server，定位是 Agent 的"大脑"：guidelines 和 knowledge 让项目工程知识跨会话持续沉淀，lineage 让后续 Agent 能反查历史决策依据。它提供三个 tool：

Tool	作用
guidelines	维护项目工程约定，让后续 Agent 会话能读取当前规则
knowledge	维护跨任务、跨会话共享的项目知识条目
lineage	查询代码、commit 或 proposal 背后的任务、会话和设计决策脉络

Bundled Transport 与上下文

在 FylloCode 应用内，fyllo-cortex 由应用级 bundled MCP host 托管。声明 HTTP MCP 能力的 ACP Agent 会通过稳定 loopback proxy 复用后端进程；每次 Workspace MCP activation 获得独立 capability，proxy 校验 server scope 后注入 Workspace v2 上下文。stdio 通过 FYLLO_WORKSPACE_JSON 接收同一份冻结 descriptor。调用方看不到内部 bearer token，也不能通过自带请求头或 cwd 伪造 Project/Folder 上下文。

Agent 不支持 HTTP、后端未就绪或 host 不可用时，FylloCode 会回退到 stdio transport。guidelines、knowledge、lineage 的 tool 名称和 mode 保持，Workspace v2 下的 owner 输入与 repository evidence 契约已更新。设置 FYLLO_DISABLE_BUNDLED_MCP=1 会完全禁用 bundled MCP 注入。

guidelines tool

guidelines 用于维护指定 Project 的 guidelines。正常读取 guidelines 的路径不是调用 tool，而是：

1. FylloCode 在新的 Chat / Apply ACP session 启动时扫描当前 Workspace 中授权 Project 的 guidelines/**/*.md
2. 按 Folder/Project 归属将每个文件的 frontmatter 组成 <guidelines> 索引注入 system reminder
3. Agent 根据索引中的 path 直接读取相关 guideline 全文

Archive 阶段不会注入 <guidelines> 索引，但会在归档前要求 Agent 检查本次变更是否应该更新 guidelines。

当前 tool 有三个维护模式：

mode	返回内容	是否修改文件
init	为尚无 guidelines 的项目返回初始化指令和当前仓库状态	否
create	为一个未沉淀的新约定返回创建指令、现有索引和 AGENTS.md 状态	否
update	为一个已有 guideline 返回修复指令、目标文件状态和当前索引	否

tool 不会直接生成或覆盖文件。它返回的是维护 guidelines 时应遵守的 tool_instruction 和 state，具体修改仍由 Agent 根据仓库事实完成。

不要用 guidelines tool 重新读取 guideline 索引；会话中的 <guidelines> 块才是读取入口。只有在初始化、创建或修复 guideline 时才调用该 tool。

推荐文件结构

FylloCode 项目中的 guideline 体系通常包括：

• 根目录 AGENTS.md：Agent 工作时的入口说明
• guidelines/**/*.md：按主题拆分的详细规范，可按目录继续分组

常见主题包括：

• Architecture
• CodeStyle
• Testing
• DataModel
• IPC
• RendererProcess
• MainProcess
• Build
• DeveloperWorkflow
• Domain

frontmatter

FylloCode 会解析 guideline 文件顶部的 YAML frontmatter 来构建 <guidelines> 索引。

每个 guideline 文档必须以这些字段开头：

---
name: Architecture
description: 系统架构、目录边界与依赖方向
keywords: [architecture, electron, ipc]
---

返回条目包含：

• path
• name
• description
• keywords
• parseError（仅 frontmatter 解析失败或文件读取失败时出现）

没有 frontmatter 的文件仍会被返回，name 会退回到文件名；但推荐修复为完整 frontmatter，否则 Agent 很难只通过索引判断是否需要打开该文档。

触发位置

guidelines 不只由 fyllo-cortex.guidelines tool 触发。FylloCode 会在多个位置把 guideline 维护纳入工作流：

• Chat：system reminder 注入 <guidelines> 索引；创建 Proposal 前要求 Agent 考虑是否需要新增或更新 guideline；直接实现或 Plan 实现完成后也要做同样检查。
• Proposal 创建：fyllo-specs create-proposal 的 instruction 会要求 Agent 在编写 tasks.md 时直接决定是否需要具体的 local repository guideline 更新任务；已有 OpenSpec config 不会被自动改写。
• Apply：改代码前必须读取相关 guideline；实现中发现 guideline 缺失、陈旧或与仓库事实冲突时，调用 guidelines tool 维护。
• Archive：归档前再次检查已完成变更是否改变了命令、架构、测试、工作流、数据契约或项目约定。
• Project Health Check：guideline 健康检查不计入健康分，但会直接通过 init / create / update 处理缺失、损坏或陈旧的 guideline，不走 Proposal。
• Project Overview：概览页展示 guidelines 数量、最近更新时间，以及 git 历史中的 guideline 演化记录。

会话注入细节

Chat 与 Apply 的 <guidelines> 索引来自当前 workspace：

• Chat 会按 Session Workspace snapshot 分组扫描各 Project；如果某个 Project 使用 linked worktree，优先扫描该 worktree 下的 guidelines/
• Apply 等单仓库阶段扫描 Proposal owner 的 worktree 或主目录
• 如果没有 guidelines/ 或没有 Markdown 文件，就不注入 <guidelines> 块
• frontmatter 中的尖括号会被转义，避免用户编写的元数据提前关闭 <guidelines> 块

knowledge tool

knowledge 用于维护存储在 FylloCode 应用数据目录中的持久化 Workspace 知识，与 guidelines 不同，knowledge 条目不写入 Project 仓库，而是跨 Project、跨任务、跨会话共享的 Workspace 级积累；引用仓库证据时会保留所属 folderId。产品层面的浏览方式见 知识沉淀。

什么时候触发捕获

Agent 不会持续调用这个 tool，而是遵循一套判断标准（flag test）：这条信息如果丢了，未来某次会话是否要为此付出代价（重新推导、重新翻查、或者理解错）。命中判断标准时，Agent 先在会话里放置一张 knowledge.flag fyllo-action 卡片作为低成本标记，不会立刻调用 knowledge tool，也不会打断当前讨论。

只有当用户在对话正文中确认某张待处理的 flag 卡片，或者明确要求捕获知识时，Agent 才会以 mode: capture 调用 knowledge tool；此时会话内所有待处理的 flag 会被打包成一次捕获请求。会话事件栏只汇总并定位这些待处理项，不提供确认按钮。

维护模式

mode	触发时机	是否修改文件
capture	用户确认 knowledge.flag 后，或用户明确要求捕获知识	否，返回写入指引
update	用户要求修订一条已有条目	否，返回修订指引
retire	用户要求移除一条条目	否，返回下线指引
audit	用户要求检查过期、来源存疑、重复或低质量的条目	否

和 guidelines 一样，knowledge tool 不直接写文件，返回的是当前状态和该 mode 对应的写作指引，具体的条目内容由 Agent 根据指引完成。

Agent 完成 capture 写入或 update 修订后，会放置一张 knowledge.review 卡片，用户确认后 FylloCode 从磁盘打开该条目的最新内容供编辑和审阅；弹层会实时保存完整 Markdown 原文。

lineage tool

lineage 用于查询既有代码背后的设计历史。它返回的是 FylloCode lineage subject 的投影，包含任务摘要、Chat session、proposal、plan、commit hash、proposal 路径和当前 proposal 状态；repository trace 必须明确所属 folderId，可选 worktreePath 也必须是该 Folder 已注册的 worktree。

常见使用场景是用户问“这段代码为什么这样写”“这个 commit 背后的任务是什么”“这个 proposal 后来落地了吗”。这类问题仅靠 git commit message 往往不够，lineage 会把代码变更追溯回任务、对话和 OpenSpec artifacts。

当前有三个查询模式：

mode	输入	返回
trace-file	folderId、filePath，可选 lineRange / worktreePath	在指定 Project 中查找触碰该文件的 commits，并返回带 repository origin/reference 的 lineage entries
trace-commit	folderId、commitHash，可选 worktreePath	返回该 Project 中 commit 对应的 lineage entry
trace-proposal	folderId、changeId，可选 worktreePath	返回该 Project 中 OpenSpec change 对应的 lineage entry

当没有匹配结果或项目缺少 lineage 数据时，tool 返回 null 或空数组。它只读取项目数据和 git 历史，不修改文件。

适用场景