给 AI 编程助手加一层工作纪律：改代码前先读项目基线、报错先查根因、说"完成"要附验证证据，简单任务仍走快路径。
- 语言
- Python
- License
- MIT
- 分支
- main
安装
$ dsh plugin --profile web add github:GanyuanRan/Aegis在终端中运行以上命令，通过 dsh CLI 安装此插件。可在右上角切换 Profile。 第一次用 dsh？看这篇新手教程
一句话定位
Aegis 是一套给 AI 编程助手使用的工作方法包，内含 22 个方法技能（诊断、计划、评审、验证、收尾等）。安装后它会在会话开始时给 Agent 注入一份精简的路由说明，让 Agent 按任务风险决定是直接动手，还是先分析、先取证。
核心能力
- 让 Agent 在动代码前先读项目现有约定、识别真正该改的模块，减少改错地方导致的返工
- 遇到报错、回归或行为异常时，先走根因定位流程再提修复方案，而不是直接猜着改
- 要求 Agent 在宣称"做完了"时给出本次实际跑过的验证内容、覆盖范围和残留风险
- 提供成套方法技能：需求盘问式头脑风暴、写计划与执行计划、独立代码评审、架构决策记录、长任务断点续跑、旧逻辑退役治理
- 在会话开始、恢复、清空、压缩四个时机自动注入路由说明；简单任务仍允许 Agent 直接声明走快路径
- 提供项目工作区脚本，按需在目标项目的
docs/aegis/下生成基线、计划、检查点与证据记录
技术实现
- 语言: JavaScript（ESM 模块）+ Python 3 脚本，方法本体为 Markdown
- 关键依赖:
@deepseek-ai/dsh-skill-filesystem（复用宿主的技能发现能力）、@deepseek-ai/dsh-llm（构造注入消息），两者均声明为可选 peerDependency 由宿主提供 - 架构模式: 通过
package.json的dsh.bundle.patch向宿主配置插入一行 Cordis 记录，挂载一个不含默认根目录的独立技能提供者指向包内skills/；同时监听宿主原生agent/session-start生命周期，在插件加载阶段就把路由文本准备好并同步注入，避免首步读文件产生竞态；子会话（subagent）不注入 - 入口文件:
extensions/dsh/index.js（由extensions/dsh/cordis.patch.yml声明挂载）
适用场景
适合让 AI 大范围改动真实项目、但又不想全程盯着它的人：Agent 容易在没看清现有结构时就动手，改完还自称完成。它把"先看基线、先定根因、完成要给证据"固化成可复用流程，同时保证琐碎请求不被流程拖慢。
前置依赖与兼容性
| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DeepSeek Harness (dsh) | 0.1.0-rc.6+ | 以可选 peerDependencies 形式声明 @deepseek-ai/dsh-agent、dsh-llm、dsh-skill-filesystem |
| pnpm | 未声明具体版本 | dsh plugin 操作会转发给 pnpm，只能用 npx 启动界面不足以完成插件安装 |
| Python 3 | CI 以 3.11 验证 | 安装自检脚本与项目工作区脚本用 Python 编写，不装则无法完成完整验证 |
| Node.js | 未声明 | package.json 中没有 engines 字段 |
| 运行平台 | 跨平台 | 仓库同时提供 .cmd、PowerShell 钩子与 Windows junction 链接模式 |
| 原生模块 | 无 | 未依赖任何需要编译的原生扩展 |
安装方式
dsh plugin --profile web add github:GanyuanRan/Aegis
配置项
配置写在用户目录 ~/.config/aegis/config.toml，通常由 python scripts/aegis-doctor.py --write-config 自动生成。
| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
activation_mode | 字符串（auto / explicit） | 是否在每次会话开始时自动提醒 Agent 使用这套方法；改成 explicit 后只有你点名才生效 | auto |
tdd_mode | 字符串（auto / off） | 是否让它按任务风险自动要求测试先行 | off |
method_pack_root | 路径 | 记录这份方法包装在哪，供自检和更新流程定位 | 由 --write-config 写入 |
workspace_helper | 路径 | 记录工作区脚本位置，供在目标项目内生成记录 | 由 --write-config 写入 |
也支持用环境变量临时覆盖：AEGIS_ACTIVATION_MODE、AEGIS_TDD_MODE、AEGIS_WORKSPACE_HELPER。修改自动开关后需要重启对应 profile。
常见问题
Q: 安装完立刻就能用吗？
A: 需要重启对应的 DSH profile。安装说明要求先用 dsh plugin --profile web list --depth 0 确认包已安装，再用 dsh --profile web --dump-config 确认配置里出现 aegis-method-pack 一行，然后重启会话。
Q: 怎么判断装成功了？
A: 除了上面的配置回读，还要定位到方法包所在目录（通常是 ~/.dsh/profiles/web/node_modules/aegis），在那里运行 python scripts/aegis-doctor.py --write-config --json，输出需同时包含 "ok": true、"workspaceSupport": "available"、"configStatus": "configured"。注意不要在你的业务项目目录下跑这条命令。
Q: 装上以后每个问题都会走一大套流程吗？
A: 不会。路由规则允许 Agent 对简单任务直接声明走快路径，只有多步实现、共享模块、契约变更这类风险较高的任务才展开完整方法。
Q: 它会往我的项目里写文件吗？
A: 默认不写。只有当工作流需要留存基线、计划、检查点或验证证据时，才在目标项目的 docs/aegis/ 目录下按需创建，普通问答、状态查询和小改动不产生文件。
Q: 配置和记录存在哪里？
A: 全局配置在 ~/.config/aegis/config.toml；项目相关记录写在你所在项目的 docs/aegis/ 里，跟随项目版本管理，不集中上传到别处。
Q: 默认会强制我写测试吗？
A: 不会，TDD 模式默认关闭。需要时运行 python scripts/aegis-doctor.py tdd-mode auto 打开按风险自动路由，或在提问里直接写 strict TDD、test-first 单次要求。
Q: 在 web profile 装了，headless profile 也能用吗？
A: 不能。DSH 的插件依赖按 profile 隔离，需要对每个要用的 profile 分别执行一次安装命令；同时不要再把它注册到 ~/.dsh/skills 等其他技能目录，否则会出现重复来源。
Q: 效果有数据支撑吗？
A: 仓库附了一份冻结的 A/B 对照数据（20 个用例、120 次有效运行）并公开了原始 JSON 与方法说明，同时明确写了这是有界参考证据，评审为隐藏分组的技术评审而非独立人工评审，不能当作通用质量结论。
上手难度
进阶 —— 安装只需一条命令，但要装好 pnpm 与 Python、看懂 profile 隔离概念，并完成配置回读加自检脚本两步验证才算真正装好。
已知问题与限制
- 官方 DSH 宿主适配目前只有结构性支持：会话注入接线有确定性测试覆盖，但缺少发布级的真实会话路由验证
- DSH 本身处于开发者预览阶段，官方声明会有破坏性变更，适配可能随宿主升级失效
- 插件安装与旧的 direct-child 兼容安装不能同时启用，否则会出现同名技能的重复来源和不可靠的路由结果
- 已通过插件安装的版本不要用
scripts/aegis-update.py update --host deepseek-harness更新，该命令只管兼容模式安装；插件安装请用dsh plugin update aegis - 它不是运行时内核，不做硬性工具拦截：快路径声明属于模型自述行为，误判时不会被强制阻断
- 项目工作区记录的完整性依赖工作流正确调用工作区脚本，未调用时索引文件可能缺条目
- 项目基线质量取决于仓库内容是否充足，内容过于稀薄的项目难以生成有用基线
- 架构评审的部分维度（如熵流动、级联扩散）依赖 Agent 定性判断，没有量化测量工具
- 上游 Gemini CLI 宿主适配已退役，不再随包提供与验证
Aegis
Aegis Method Pack
Make your AI coding agent trustworthy: fewer reworks, safer changes, proof before "done".
English · 中文 · Fast-Track Playbook · 速通秘籍
Stop babysitting your agent. Aegis makes your agent plan against your real baseline before it edits, prove completion with fresh evidence, and leave simple tasks alone — you get fewer reworks, safer changes, and less blind trust in "done".
What You Get
Aegis is a method pack that makes AI coding agents work like disciplined engineers — so you don't have to watch them.
- Fewer reworks. Your agent aligns with your project's real baseline — owners, contracts, boundaries — before touching code. It stops guessing, and so do you.
- Safer changes. Measured on a frozen held-out A/B benchmark: contract pass rate 61.67% → 93.33%, unsafe outcomes 13.33% → 0%.
- Proof before "done". Completion claims ship with fresh verification evidence, covered scope, and residual risk. You read evidence, not vibes.
- No ghost code. Retired fallbacks and old paths are tracked or removed with a retirement trigger — technical debt stops accumulating silently.
- Simple tasks stay simple. Trivial requests stay on the fast path; ceremony only appears when the task genuinely needs it.
- One method pack, every host. The same discipline works across Codex, Claude Code, OpenCode, Kimi, and other skill-aware hosts.
The numbers above are bounded advisory evidence from the frozen benchmark below, not a universal-quality or completion-authority claim.
Measured Agentic Benchmark
A frozen held-out A/B benchmark for Aegis 2.7.6 (2026-08-11) kept the Codex client,
prompts, projects, tool policy, and requested the same gpt-5.6-sol / xhigh setting
in both arms; only the Aegis projection differed. Across 120 valid runs on 20 cases,
contract pass rate was 61.67% → 93.33% (+31.67 pp) and unsafe outcomes were 13.33% → 0%. The 95% case-cluster interval was +15.00 pp to +50.00 pp. This is bounded advisory evidence; review was arm-hidden technical review, not independent human review, and host events did not return the observed model identity.
Sanitized JSON · English table · 中文表格 · Methodology
Quick Install
New here? The fastest start is one prompt to your agent — the full install-and-verify flow is below.
Give this prompt to your AI coding agent:
Read https://github.com/GanyuanRan/Aegis, identify my current AI coding host, and install Aegis globally using the correct host guide. If the host is the official DeepSeek Harness (`dsh`), treat global/minimal installation as native profile-plugin installation with `dsh plugin --profile <profile> add github:GanyuanRan/Aegis`; do not silently substitute the direct-child compatibility path unless the plugin manager is unavailable and I explicitly approve compatibility mode. Restart or reload the host if needed, then run complete-install verification from the installed Aegis method-pack root. Do not run the doctor command from the target project directory. First locate `<aegis-method-pack-root>`, then run `cd <aegis-method-pack-root> && python scripts/aegis-doctor.py --write-config --json`. Treat the install as complete only if the JSON includes `"ok": true`, `"workspaceSupport": "available"`, and `"configStatus": "configured"`; if the host uses a separate skill discovery directory, also verify it with `--discovery-root <path>`; if the host guide declares a skill directory name prefix, also pass `--discovery-name-prefix <prefix>`. Also complete the selected host guide's native activation and automatic-entry checks; file discovery or a generic doctor result alone is not sufficient when the host provides a plugin, hook, or session-start bootstrap contract.
Updating Aegis
After a complete install has registered the current host, later updates can use
natural language such as update Aegis or the explicit skill request
aegis:update. The agent can route either form through the local update path:
locate the installed method-pack root, use the host-scoped registry, and call
scripts/aegis-update.py for the current host by default. Updating every
registered host requires an explicit --all request. Aegis does not run
background automatic updates by default.
Before You Use It
Aegis is currently:
Aegis Method Pack (runtime-ready)
It is not the full Aegis Platform, a daemon, a background runner, a runtime
core, an authoritative GateDecision, an authoritative PolicySnapshot, or
final completion authority. User instructions and target-project rules outrank
Aegis guidance.
The following files are optional, manually copied host/profile projections. They do not install Aegis or prove skill discovery. If the host already has reliable Aegis bootstrap and routing, no extra global rule is usually needed for routing. Otherwise, copy Lite as the complete base profile. Advanced is a non-standalone additive overlay; append only the rules needed for persistent governance preferences:
These copied rules are not managed by aegis:update. Lite owns the default
auto activation profile and its explicit-mode replacement; Advanced inherits
that choice instead of repeating it. When switching to explicit, update the
copied Lite profile too; host-native skill matching may still remain
host-controlled.
Activation mode defaults to automatic. To switch to explicit mode, run this from the installed method-pack root:
cd <aegis-method-pack-root>
python scripts/aegis-doctor.py activation-mode explicit
Restart the host after changing activation mode. Details and host caveats live in docs/current/AEGIS_ACTIVATION_MODE.md.
TDD mode defaults to off: Aegis does not automatically require TDD, and
completion verification still applies. To enable automatic TDD routing when you
want Aegis to choose strict, light, or skipped by task risk:
cd <aegis-method-pack-root>
python scripts/aegis-doctor.py tdd-mode auto
You can also request strict TDD directly in a query with explicit markers such
as TDD Route: strict, strict TDD, test-first, or
RED / GREEN / REFACTOR.
Details live in docs/current/AEGIS_TDD_MODE.md.
Supported Hosts
Aegis keeps a multi-host, plugin-installable distribution goal.
| Host group | Current status | Start here |
|---|---|---|
Codex, OpenCode | Fresh evidence exists for the current method-pack scope | Codex, OpenCode |
Claude Code, CodeBuddy, DeepSeek-TUI, DeepSeek Harness, Trae, GitHub Copilot, Qoder, Kimi Code CLI, ZCode, Grok Build | Install guides exist; release-level fresh host smoke is still pending | Claude Code, CodeBuddy, DeepSeek-TUI, DeepSeek Harness, Trae, GitHub Copilot, Qoder, Kimi Code CLI, ZCode, Grok Build |
CC GUI (JetBrains IDEA) | Structural IDE plugin layer support for Claude Code / OpenAI-GPT provider paths; release-level fresh host smoke is still pending | CC GUI |
Antigravity CLI, Antigravity IDE, Antigravity App | Antigravity CLI is the current active closeout target; IDE/App remain structural targets and release-level fresh host smoke is still pending | Antigravity |
Pi CLI, OMP, OpenClaw, Hermes Agent | Structural Agent Skills / SKILL.md skill-host adaptations; release-level fresh host smoke is still pending | Pi CLI, OMP, OpenClaw, Hermes Agent |
Gemini CLI | Retired; Aegis no longer ships or verifies a Gemini CLI adapter | Compatibility Matrix |
Read the current host verdict before making support claims:
Start Fast With Aegis
After installation and host restart, use normal language. Aegis matches the method to the work; name a mode directly when you want less ambiguity.
Why does this login failure happen? Diagnose it before changing code.
Grill me on whether we should ship a hosted version first.
Aegis goal: Fix the auth refresh bug without rewriting the auth system.
Review this diff independently before I merge it.
Read the Fast-Track Playbook for Aegis's lightweight operating model, how it differs from standalone skill packs, its five engineering moats, project workspace lifecycle, natural trigger phrases, controls, and troubleshooting. The Chinese version is Aegis 速通秘籍.
Use these explicit requests when you need tighter control:
Aegis goal: ...frames scope, success evidence, and boundaries.Grill me ...or审问我 ...starts a decision interview; it asks one decision question at a time and does not plan or implement.TDD Route: strict,strict TDD, ortest-firstexplicitly requests strict test-first work. TDD is otherwiseoffby default.aegis:first-principles-revieworreview this from first principlespressure-tests a complex direction before implementation.aegis:updateupdates the installed method pack through its host-aware path.
For non-trivial project work, Aegis can passively reuse relevant canonical
language from CONTEXT.md or a bounded context selected by CONTEXT-MAP.md.
It activates domain modeling only when a term is resolved, ambiguous, renamed,
deprecated, or conflicting. High-confidence existing facts may synchronize
directly; unresolved domain decisions remain user-owned. Files are created
lazily on the first resolved term and remain glossary-only. Stable bytes can be
cache-friendly, but Aegis does not guarantee provider cache hits or savings.
Aegis preserves Workflow Quality by keeping simple work light and expanding only when risk warrants it. For deeper method detail, read the Workflow Guide, Workflow Quality Baseline, Complexity Governance Baseline, and TDD mode.
If a capability does not trigger as expected, use trigger-chain diagnosis:
install/version visibility, host skill discovery, activation mode,
using-aegis routing, task-to-skill matching, and context pressure. Read the
Trigger Health Baseline.
For Maintainers
Primary verification entry:
bash tests/e2e/run-all.sh --full --host-profile fast
Focused docs / method-pack checks:
bash tests/e2e/boundary-compliance-check.sh
bash tests/e2e/workflow-quality-check.sh
bash tests/e2e/install-verification-policy-check.sh
bash tests/e2e/layer1-fast-check.sh --host-profile none
Read:
Community & Extending
- Feedback and discussion: GitHub Discussions · Issues · LINUX DO · DEV.to
- Extend Aegis: write your own skill with
aegis:writing-skills; see the Workflow Guide. - Follow along: RELEASE-NOTES.md · Releases
Relationship To Superpowers
Aegis is derived from Superpowers, created by Jesse Vincent. Superpowers pioneered composable, multi-harness agent skills. Aegis keeps that foundation and adds an architecture- and evidence-focused method layer for real software projects.
Additional inspiration comes from mattpocock/skills, especially concise communication, shared language, and disciplined debugging patterns. These ideas were re-implemented in Aegis format rather than copied verbatim.
License
MIT License. See LICENSE.