modus

让 Coding 不止于 Code

安装 uv tool install openmodus · 更新 modus update

简体中文 · English

核心功能 · 快速开始 · 为什么需要 Modus · 技术原理 · 使用手册 · 开发与贡献

接手陌生项目，要改一条业务规则，如何找到负责它的代码和验证它的测试？

Modus 为 Coding Agent 建立可追溯的项目知识库。本地分析把入口、调用和状态写入定位到源码。Agent 沿这些线索核对实现、测试、业务材料与团队约束，把规则成立的条件、失败后的恢复方式和验证入口写进仓库里的 Markdown。下一次改动时，开发者和 Agent 都能从同一条规则回到当前实现。

目前开源的是 Modus 的项目知识库部分；配套的 AI 工作流开源方案也在持续完善，后续会更新进展。

看一段完整流程：项目源码 + 业务资料 → 可追溯的项目知识。 以一个业务管理系统为例，从安装或更新、选择 Agent 平台开始，在 /modus-init 中提供需求与设计文档、业务网页（平台支持 Computer Use 时）以及流程图、截图等图片，沉淀 Markdown，再沿订单权限规则定位到实现。

核心功能

Modus 把项目知识作为可维护的工程资产：本地分析提供线索，Agent 与人确认业务含义，Markdown 承载长期结论，日常任务按需使用并随变更修订。

从证据建立项目地图

初始化时，本地分析从源码、构建上下文和可用工具链提取有界证据，帮助定位入口、关系与关键行为。Agent 再回读源码、测试、配置和业务材料，确认系统架构、领域边界与真实场景，将判断写入系统概览、领域、模块及专题文档。

Code to MD · Code link MD 可以在同一次 /modus-init 中完成。从源码建立第一份知识时，可以一并提供多份需求、设计、团队规范，以及本地 Wiki、LLM Wiki 中的 Markdown、可访问的网页和流程图、产品截图等图片。Agent 将材料中的业务概念、规则和场景与真实实现核对，让代码有业务背景可解释，让文档有实现可追溯。

为任务渐进装配上下文

开发、排障或评审需要项目事实时，Agent 从系统概览进入相关领域、模块与场景，按需联读团队约束，并回到当前源码核验。检索按问题组织知识和实现片段，明确标示证据缺口；日常使用直接读取仓库中的 Markdown 与当前源码，无需重跑初始化分析。

让知识进入代码评审链路

长期知识以 Markdown 与代码同仓保存。稳定的领域与模块身份、知识链接和结构化源码锚点形成追溯路径；人工维护的业务知识与团队约束有明确所有权，完整性检查负责结构、链接和锚点，让知识变更具有清晰的评审边界。

随长期语义变化精确维护

代码变更后，Agent 根据本次修改判断职责、契约、规则、状态、依赖、资源或源码锚点是否发生长期变化；确有影响时，在原定义处修订受影响正文并同步相关导航与引用。新增业务材料和局部事实也可以定向更新，使知识随项目演进而保持可用。

快速开始

从 PyPI 安装 CLI，接入目标仓库，再由 Agent 结合源码与业务材料创建第一份知识。最终的 Markdown 保存在项目中，可以随代码一起评审。

1. 安装 CLI

从 PyPI 安装发布版，在终端运行以下命令（需要 uv 和 Python 3.11–3.14）。uv 安装说明

uv tool install openmodus

PyPI 上的包名是 openmodus，安装后的命令是 modus。源码安装、pipx 与软件源配置见安装与接入选项。PyPI 发布页

2. 接入项目

进入要使用 Modus 的项目仓库：

cd path/to/your-project
modus init

在交互式终端中选择 Claude Code、Codex、Cursor、CodeBuddy 或 DeepSeek Harness（预览，当前需源码安装）。CLI 将平台中立的 Skill 与命令安装到项目，再通过对应适配器接入所选平台，并记录受管文件的所有权。脚本接入、多平台接入和安装状态检查见安装与接入选项。

3. 创建项目知识

Code to MD，从代码建立项目知识。 在所选 Coding Agent 中打开项目，在对话中运行以下工作流，Agent 会从当前源码、测试、配置与项目内已有材料开始调查。

/modus-init

Code link MD，用已有业务材料补全项目理解。 运行 /modus-init 时，可以在同一条消息中附上多份文档、图片，或提供材料的路径、目录和网页链接。需求说明业务目标，设计文档解释取舍，团队规范给出约束，Wiki、业务网站、流程图和产品截图补充实际场景。把下面的示例替换为你的材料即可。

/modus-init
请结合当前项目源码和以下材料创建项目知识：
- docs/requirements/ 下的需求文档
- docs/design.md 技术设计
- docs/team-standard.md 团队规范
- ../project-wiki/ 下的本地 Wiki 或 LLM Wiki Markdown
- https://example.com/project/docs 业务与技术文档
- https://example.com/project/app 的订单与退款页面，仅查阅
- docs/order-flow.png 业务流程图，以及随消息附上的产品截图

将业务概念、规则和场景关联到实际代码，标明材料与当前实现的差异。

Agent 会逐份读取已确认范围内的材料，继续查看文档集合的子目录与子文档，再与当前实现交叉核验。材料的读取依赖 Agent 平台可用的文件、文档、网页与图像读取能力。查阅需要登录或交互的业务网站时，平台需具备浏览器或 Computer Use 能力，并由你提供访问权限与查阅范围。当前工作流的材料覆盖细则见证据创作契约。

/modus-init 是 Agent 对话中的知识创作工作流；终端里的 modus init 负责项目接入。Agent 会先确认 Domain/Module 范围，再逐域撰写正文。若平台以 Skill 名称呈现能力，可直接要求它“使用 modus-init，结合当前项目和这些材料初始化知识”。

完成后，.modus/ 保存平台中立的接入资产，modus/knowledge/ 保存与代码一起评审的 Markdown 知识，modus/.cache/ 保存可丢弃的初始化证据。日常任务按需读取知识与当前源码，无需重跑初始化分析。首次创作的验收与后续维护见使用手册。

为什么需要 Modus

你会得到什么

接手一个项目时，找到代码入口只是开始：还需要弄清规则为何存在、什么结果算完成、失败后如何恢复，以及改动要守住哪些边界。Modus 把经源码和可用业务材料核验的长期结论留在仓库，让后续任务从已有理解出发，并继续以当前源码核对实现。

这份知识是仓库内可读、可改、可删除的 Markdown。初始化分析在本地生成本轮创作需要的有界证据；普通任务直接使用当前源码和已经审阅的正文，不依赖远程知识服务、向量数据库或持久化源码图。

支持的平台与语言

Modus 需要 Python 3.11–3.14，安装后的命令是 modus。下面按平台与语言列出可用范围。

Coding Agent 平台

每个适配器声明自己的 Skill 目录与常驻说明；共享安装器负责确定性写入、所有权清单、升级合并与安全卸载。Modus 通过常驻说明与 Skills 按需提供项目指引，不安装会话启动 hook。

旧项目执行 modus update --project 时，会按安装清单移除 Modus 的 hook 条目和未被用户修改的启动脚本，保留其他工具的命令与用户配置。损坏的配置会保留并报告，修复后可再次更新。

语言能力

当前源码分别记录文件是否纳入分析、语法结构能提取到什么，以及本地工具链能进一步绑定哪些符号。

编译器或类型系统增强

Python、Java、Go、C/C++ 和 TypeScript 可在结构解析的基础上补充本地编译器或类型检查器的观察。自动模式下，可选工具链缺失会留下对应的覆盖缺口。显式要求编译语义时，必需的提供方失败会中止本轮分析。

例如，Java 的结构解析可以定位一行方法调用。项目构建上下文和本地 JDK 可用时，Modus 还会通过 javac 查询该调用绑定的方法声明，保留调用位置和目标身份。Java 编译器适配实现

专门结构提取