Aegis

Aegis

面向 AI 编码 Agent 的基于 DAG 的确定性上下文编译器

日本語版 README | 技术指南

Aegis 是一个 MCP 服务，可在 AI 编码 Agent 上强制执行架构指南。它不使用 RAG，而是通过依赖边构成的 DAG，确定性地编译 Agent 针对一组目标文件所需的文档。不搜索，不排序，结果确定。

快速开始

1. 将 Aegis 添加到 IDE 的 MCP 配置中（参见安装）
2. 向 AI Agent 提出请求：“为此项目初始化 Aegis 并部署适配器规则。”
3. Agent 会自动运行 aegis_init_detect → aegis_init_confirm → npx @fuwasegu/aegis deploy-adapters

数据库存储在项目根目录的 .aegis/aegis.db 中。.aegis/ 目录包含自己的 .gitignore，无需手动配置。

安装

Aegis 使用两个 MCP 接入面，二者缺一不可：

仅使用 agent 接入面无法初始化项目或批准提案。这种隔离可确保 AI Agent 未经人工批准，无法修改架构规则。(INV-6)

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初始化后，deploy-adapters 会生成 .cursor/rules/aegis-process.mdc，这是一条 Cursor 规则，指示 Agent 在编写代码前先查阅 Aegis，并在完成后报告违规情况。

Claude Code

claude mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
claude mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初始化后，deploy-adapters 会在 CLAUDE.md 中追加 `` 部分（如果文件不存在，则会创建）。

Codex

codex mcp add aegis -- npx -y @fuwasegu/aegis --surface agent
codex mcp add aegis-admin -- npx -y @fuwasegu/aegis --surface admin

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

初始化后，deploy-adapters 会在 AGENTS.md 中追加 `` 部分（如果文件不存在，则会创建）。

注意： Codex 的 MCP 支持取决于 CLI 版本。如果无法使用 MCP，Agent 仍可遵循生成的 AGENTS.md 中的说明来执行 Aegis 指南。

使用方法

1. 初始化项目

使用 admin 接入面，通过空知识库初始化 Aegis：

aegis_init_detect({ project_root: "/path/to/your/project", skip_template: true })
aegis_init_confirm({ preview_hash: "<hash from detect>" })

这会创建一个空知识库。下一步将用架构文档填充它。

然后通过 CLI 为 AI 编码工具部署适配器规则和 Agent Skills：

npx @fuwasegu/aegis deploy-adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # specific adapters only

2. 在开发过程中使用

agent 接入面为 AI 编码 Agent 提供工具。要获取扩展上下文（由标签驱动的文档），建议按以下流程操作：每个会话调用一次 aegis_get_known_tags（缓存 tag_catalog_hash），然后在 compile 时传入 intent_tags：

aegis_get_known_tags({})
aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: ["<tags from known_tags>"]
})

只有在希望可选的服务端 SLM 标注器（启用 --slm 时）改为从 plan 推断标签时，才省略 intent_tags（参见 ADR-004）。传入 intent_tags: [] 可在不使用 SLM 的情况下跳过扩展上下文。

仅使用基础 DAG（跳过扩展上下文；无论是否启用 --slm，效果都相同，因为 intent_tags: [] 会禁用扩展上下文并跳过 SLM 标注）：

aegis_compile_context({
  target_files: ["src/core/store/repository.ts"],
  plan: "Add a new query method for archived observations",
  intent_tags: []
})

返回与正在编辑的文件相关的架构指南、模式和约束。

3. 添加架构文档

初始化后，通过分析代码库来填充知识库。在 admin 接口上使用 aegis_import_doc 添加架构文档，并通过 edge_hints 将其与文件路径关联：

aegis_import_doc({
  file_path: "/absolute/path/to/docs/architecture-guide.md",
  doc_id: "architecture-guide",
  title: "Architecture Guide",
  kind: "guideline",
  tags: ["architecture"],
  edge_hints: [
    { source_type: "path", source_value: "src/domain/**", edge_type: "path_requires" }
  ]
})

使用 file_path 可直接从磁盘读取内容，避免 LLM 上下文窗口导致内容截断。每次导入都会返回 proposal_ids——请批准它们以激活文档。

若要让导入的文档与源文件保持同步：

aegis_sync_docs()   # detects changes via content hash, creates update_doc proposals

aegis_import_doc 和 aegis_sync_docs 都需要 admin 接口。有关分步批量导入工作流的详细说明，请参阅 aegis-bulk-import skill（通过 deploy-adapters 部署）。

4. 报告观察结果

当 Agent 发现缺失的指南或需要更正的内容时：

aegis_observe({
  event_type: "compile_miss",
  related_compile_id: "<from compile_context>",
  related_snapshot_id: "<from compile_context>",
  payload: { target_files: ["..."], review_comment: "Missing error handling guideline" }
})

5. 审核提案

系统会分析观察结果并生成提案。通过 admin 接口进行审核和批准：

aegis_list_proposals({ status: "pending" })
aegis_approve_proposal({ proposal_id: "<id>" })

项目共享（团队工作流）

Aegis 支持通过 Git 提交的 bundle 工件，在团队成员之间共享已批准的规范知识。这样每位开发者都不必从头构建知识库。

工作原理

编写工作区（知识维护者）

批准提案后，导出当前的规范状态：

npx @fuwasegu/aegis share-export                # writes aegis-share/manifest.json + canonical.json
npx @fuwasegu/aegis share-export --out /path    # custom output directory

然后提交并推送 aegis-share/。

副本工作区（团队成员）

拉取包含更新后的 aegis-share/ 的变更后：

npx @fuwasegu/aegis share-hydrate               # rebuild .aegis/aegis.db from aegis-share/
npx @fuwasegu/aegis share-hydrate --replace     # overwrite existing initialized DB
npx @fuwasegu/aegis share-hydrate --bundle-dir /path  # custom bundle directory

警告： share-hydrate 会整体替换数据库。本地运行状态（观察结果、提案、编译日志）不会保留。这是有意为之——副本工作区用于使用共享知识，而非创建知识。

共享状态监控

Aegis 会自动检测本地数据库与共享 bundle 之间的差异：

• npx @fuwasegu/aegis doctor — 显示共享状态（in_sync、bundle_newer、local_ahead、diverged、unreadable_bundle）；存在需要处理的状态时退出码为 1
• npx @fuwasegu/aegis stats — 在 JSON 输出中包含 project_share，其中提供完整的状态详情
• aegis_compile_context 通知 — bundle 不同步时，Agent 会收到可执行的提示（例如“运行 share-hydrate 进行更新”）

not_configured 状态（不存在 aegis-share/ 目录）不会发出提示——只有设置共享后才会显示相关信息。

典型团队工作流

                    Authoring Workspace                    Replica Workspace
                    ───────────────────                    ─────────────────
  approve proposals ──► share-export ──► git push ──► git pull ──► share-hydrate
                                  aegis-share/ committed

1. 作者维护知识库（导入文档、批准提案、同步）
2. 作者运行 share-export 并提交 aegis-share/
3. 团队运行 git pull，然后运行 share-hydrate --replace
4. 此时，副本上的 compile_context 会返回与作者相同的指南

协作编写（源文件原生模式）

除了上述数据库原生工作流（观察 → 提案 → 批准）之外，Aegis 还支持源文件原生协作编写模式。团队成员在 aegis-share/source/ 中编辑易读的源文件，通过拉取请求审查变更，然后将其写入数据库。

重要规则： compile_context 始终从数据库读取内容，而非直接读取源文件。源文件是编写格式；数据库是运行时格式。

两种审批路径

两种路径可以并存。根据实际情况选择其一，也可以同时使用。

目录布局

aegis-share/
├── manifest.json              # Distribution bundle manifest (ADR-017)
├── canonical.json             # Distribution bundle data (ADR-017)
└── source/                    # Collaborative authoring source (ADR-018)
    ├── documents/
    │   └── <doc_id>.md        # Frontmatter + Markdown body
    ├── edges/
    │   ├── path-requires.json
    │   ├── layer-requires.json
    │   ├── command-requires.json
    │   └── doc-depends-on.json
    ├── layer-rules.json
    └── tag-mappings.json

源文件原生工作流

# 1. Bootstrap: export current DB to source format (one-time setup)
npx @fuwasegu/aegis share-source-export

# 2. Edit source files (documents, edges, rules, mappings)
#    Create a branch, make changes, open a PR

# 3. Validate before committing
npx @fuwasegu/aegis share-format                 # Normalize formatting (deterministic, in-place)
npx @fuwasegu/aegis share-lint                   # Check for errors (after formatting)

# 4. After PR merge: apply source to DB
npx @fuwasegu/aegis share-materialize            # Applies changes + auto-approves
npx @fuwasegu/aegis share-materialize --dry-run  # Preview changes without applying

# 5. Export updated bundle for replicas
npx @fuwasegu/aegis share-export

CI 集成

将 share-lint 添加到 CI 流水线，在合并前发现错误：

npx @fuwasegu/aegis share-lint  # exits 1 on errors — suitable for CI checks

第一阶段的限制

• 不支持本地覆盖 — 所有更改都通过共享源进行
• share-materialize 是完整应用（而非增量补丁）

用于扩展上下文的 SLM — 可选启用

Aegis 内置 llama.cpp 引擎，可选用于基于 SLM 的意图标注。SLM 默认禁用 — 即使不启用，基于确定性 DAG 的上下文功能也能完美运行。

若要启用，请在 agent 接口中添加 --slm：

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "agent", "--slm", "--model", "qwen3.5-4b"]
    },
    "aegis-admin": {
      "command": "npx",
      "args": ["-y", "@fuwasegu/aegis", "--surface", "admin"]
    }
  }
}

首次启用 SLM 启动时，所选模型会下载到 ~/.aegis/models/（所有项目共享）。

你也可以直接传入 HuggingFace URI：--model hf:user/repo:file.gguf

旧版： 如果更喜欢基于 Ollama 的推理，可以使用 --ollama 标志。使用 --ollama 会隐式启用 SLM。

参考

MCP 工具 — Agent 接口（6 个工具）

MCP 工具 — 管理接口（额外 18 个工具，共 24 个）

CLI 子命令

npx @fuwasegu/aegis deploy-adapters                         # Deploy all adapters
npx @fuwasegu/aegis deploy-adapters --targets cursor,codex  # Deploy specific adapters
npx @fuwasegu/aegis deploy-adapters --project-root /path    # Specify project root
npx @fuwasegu/aegis deploy-adapters --db /path/to/aegis.db  # Use custom DB path
npx @fuwasegu/aegis maintenance                             # Process observations, sync, archive
npx @fuwasegu/aegis maintenance --dry-run                   # Report only (no writes)
npx @fuwasegu/aegis stats                                   # JSON health and usage data
npx @fuwasegu/aegis doctor                                  # Health check summary
npx @fuwasegu/aegis share-export                            # Export to aegis-share/
npx @fuwasegu/aegis share-hydrate --replace                 # Rebuild DB from bundle
npx @fuwasegu/aegis share-source-export                     # Export DB to aegis-share/source/
npx @fuwasegu/aegis share-lint                              # Validate shared source
npx @fuwasegu/aegis share-format                            # Normalize shared source
npx @fuwasegu/aegis share-materialize                       # Apply source to DB
npx @fuwasegu/aegis share-materialize --dry-run             # Preview changes
npx @fuwasegu/aegis --list-models                           # List available SLM models

注意：仅在完整部署（不带 --targets）时才会更新版本跟踪记录。部分部署不会更新版本记录，因此“适配器模板可能已过时”的提示会一直显示，直到执行完整部署。

CLI 标志（MCP 服务模式）

开发

构建

npm run build    # Compile TypeScript
npm test         # Run all tests (406+)
npm run test:watch

git clone https://github.com/fuwasegu/aegis.git
cd aegis
npm install && npm run build

架构

┌─ MCP Layer (src/mcp/) ──────────────────┐
│ Tool registration, surface separation   │
└──────────────┬──────────────────────────┘
               │
┌─ Core Layer (src/core/) ────────────────┐
│ ContextCompiler, Repository, Init,      │
│ Automation (Analyzers), Tagging         │
└──────────────┬──────────────────────────┘
               │
┌─ Adapters (src/adapters/) ──────────────┐
│ Cursor, Claude rule generation          │
└──────────────┬──────────────────────────┘
               │
┌─ Expansion (src/expansion/) ────────────┐
│ llama.cpp engine, IntentTagger          │
└─────────────────────────────────────────┘

依赖关系自上而下。Core 不会导入 MCP、Adapters 或 Expansion 中的内容。

核心概念

• Canonical Knowledge：已批准的架构文档 + DAG 边
• 观察层：由 Agent 报告的事件（编译错误、修正、PR 合并）
• 提议层：需要人工批准的自动化提议
• 快照：Canonical Knowledge 的不可变、内容可寻址版本

许可证

ISC