# https://github.com/Fmarzochi/EGC 项目说明书
生成时间：2026-07-18 04:16:02 UTC
## 目录
- [项目概述、安装与多工具集成目标](#page-overview-install)
- [egc-memory 持久记忆系统](#page-memory-system)
- [egc-guardian 安全守护层与 LLM 调度](#page-guardian-system)
- [提示词库：智能体、技能、命令与规则](#page-prompt-library)
## 项目概述、安装与多工具集成目标
### 相关页面
相关主题：[egc-memory 持久记忆系统](#page-memory-system), [egc-guardian 安全守护层与 LLM 调度](#page-guardian-system)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/Fmarzochi/EGC/blob/main/README.md)
- [package.json](https://github.com/Fmarzochi/EGC/blob/main/package.json)
- [install.sh](https://github.com/Fmarzochi/EGC/blob/main/install.sh)
- [install.ps1](https://github.com/Fmarzochi/EGC/blob/main/install.ps1)
- [docs/installation.md](https://github.com/Fmarzochi/EGC/blob/main/docs/installation.md)
- [docs/targets.md](https://github.com/Fmarzochi/EGC/blob/main/docs/targets.md)
- [scripts/egc.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/egc.js)
- [scripts/lib/install-targets/registry.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/registry.js)
- [scripts/lib/install-targets/cursor.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/cursor.js)
- [scripts/lib/install-targets/cline.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/cline.js)
- [scripts/lib/install-targets/qwen.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/qwen.js)
- [scripts/lib/install-targets/junie.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/junie.js)
- [scripts/lib/install-targets/roocode.js](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/roocode.js)
- [CHANGELOG.md](https://github.com/Fmarzochi/EGC/blob/main/CHANGELOG.md)
# 项目概述、安装与多工具集成目标
## 1. 项目概述
EGC（Enforced Guidelines for Coding）是一个面向多 AI 编码代理的"上下文统一分发与同步"工具。它解决的核心问题是：当团队同时使用多种 AI 编码代理（Cursor、Gemini CLI、GitHub Copilot、Windsurf 等）时，编码规范、项目指南、上下文说明需要在每个工具各自的配置文件（rules / instructions / agents.md 等）中各写一遍，并且任何一处修改都需要手动同步到其他工具。
EGC 把上述配置抽象成"单一事实来源"，由 `egc` 命令行统一写入各工具的发现路径，并通过 `egc watch` 守护进程在任意工具配置被直接编辑时，反向提取 EGC 标记块并广播到其他工具与本地状态目录 `~/.egc/state/`。
- 当前最新版本：**v1.1.11**（发布于最近一次合并后）
- 主要 CLI 命令：`egc install`、`egc watch`、`egc sync`
- 状态目录：`~/.egc/state/`
- 国际化：已支持中文（进行中）、韩文、日文、俄文、阿拉伯文、印地文、西班牙文、葡萄牙文，法文翻译正在跟进（[#848](https://github.com/Fmarzochi/EGC/issues/848)）
资料来源：[README.md:1-40]()、[package.json:1-30]()、[CHANGELOG.md:1-15]()
## 2. 安装方式
EGC 提供三条互补的安装路径，开发者可按操作系统与使用习惯选择其一：
### 2.1 POSIX 平台（macOS / Linux / WSL）
通过 `install.sh` 一键安装。该脚本会完成 Node.js 依赖检查、CLI 链接、默认安装目标的发现路径探测，并将 `egc` 注册到用户的 `PATH`。资料来源：[install.sh:1-60]()
```bash
curl -fsSL https://raw.githubusercontent.com/Fmarzochi/EGC/main/install.sh | bash
```
### 2.2 Windows 原生（PowerShell）
通过 `install.ps1` 完成安装，行为与 `install.sh` 对等，但适配 Windows 路径、PowerShell profile 与 `npm` 全局目录。资料来源：[install.ps1:1-60]()
```powershell
iwr https://raw.githubusercontent.com/Fmarzochi/EGC/main/install.ps1 -UseBasicParsing | iex
```
### 2.3 从源码 / 手动
高级用户可直接克隆仓库并通过 `npm link` 注册 CLI：
```bash
git clone https://github.com/Fmarzochi/EGC.git
cd EGC && npm install -g .
```
资料来源：[docs/installation.md:1-50]()、[scripts/egc.js:1-30]()
安装完成后，可通过 `egc --version` 验证版本（当前应输出 `1.1.11`），通过 `egc install --help` 查看可用的目标工具列表。资料来源：[scripts/egc.js:30-80]()
## 3. 多工具集成目标（install targets）
EGC 的设计核心是"每个 AI 编码代理 = 一个 install target"。所有目标在 `scripts/lib/install-targets/` 下以独立模块形式存在，由 `registry.js` 统一注册并对外暴露。资料来源：[scripts/lib/install-targets/registry.js:1-80]()
### 3.1 目标注册机制
每个目标模块导出统一的契约接口（最少实现 `id`、`displayName`、`discoveryPaths`、`write()`、`extract()` 五个字段），由注册中心在 `egc install --target ` 解析时按需加载。这种插件式结构使得新增一个 AI 工具只需新增一个文件并在 `registry.js` 中注册一行，无需改动核心 CLI。资料来源：[scripts/lib/install-targets/registry.js:20-120]()
### 3.2 当前已支持的目标
下表汇总了截至 v1.1.11 已落地或正在通过 Issue 推进的目标：
| 目标 ID | 显示名称 | 所属平台 / 形态 | 状态 | 来源 Issue |
| --- | --- | --- | --- | --- |
| `cursor` | Cursor | VS Code 衍生 IDE | 已支持 | — |
| `gemini` | Gemini CLI | 命令行 | 已支持 | — |
| `copilot` | GitHub Copilot | VS Code / IDE 插件 | 已支持 | — |
| `windsurf` | Windsurf | VS Code 衍生 IDE | 已支持 | — |
| `cline` | Cline | VS Code 插件 | 已支持 | [#846](https://github.com/Fmarzochi/EGC/issues/846) |
| `qwen` | Qwen Code | 命令行（阿里开源） | 已支持 | [#845](https://github.com/Fmarzochi/EGC/issues/845) |
| `junie` | JetBrains Junie | IntelliJ / PyCharm / WebStorm | 已支持 | [#847](https://github.com/Fmarzochi/EGC/issues/847) |
| `roocode` | Roo Code | VS Code 插件 | 已支持 | [#852](https://github.com/Fmarzochi/EGC/issues/852) |
资料来源：[scripts/lib/install-targets/registry.js:30-160]()、[scripts/lib/install-targets/cline.js:1-40]()、[scripts/lib/install-targets/qwen.js:1-40]()、[scripts/lib/install-targets/junie.js:1-40]()、[scripts/lib/install-targets/roocode.js:1-40]()
### 3.3 安装与同步工作流
```mermaid
flowchart LR
A[用户编辑
~/.egc/state/ 下的源指南] --> B{egc install
--target X}
B --> C[registry.js
解析目标 X]
C --> D[目标模块.write
写入 X 的发现路径]
D --> E[(Cursor / Cline /
Qwen / Junie / Roo ...)]
E -. 文件被直接编辑 .-> F[egc watch
守护进程]
F --> G[extract EGC 块]
G --> A
F --> H[广播到其它目标]
```
`egc install` 负责"正向分发"，把单一事实来源写入指定目标的发现路径；`egc watch`（v1.1.2 引入）负责"反向同步"，处理用户在工具原生配置文件中直接修改 EGC 块的场景，并通过原子写回保证所有目标与状态目录的一致性。资料来源：[CHANGELOG.md:1-30]()、[scripts/lib/install-targets/registry.js:80-140]()
## 4. 添加新目标的最小步骤
社区中关于新增目标的 Issue（[#845](https://github.com/Fmarzochi/EGC/issues/845)、[#846](https://github.com/Fmarzochi/EGC/issues/846)、[#847](https://github.com/Fmarzochi/EGC/issues/847)、[#852](https://github.com/Fmarzochi/EGC/issues/852)）展示了统一流程：
1. 在 `scripts/lib/install-targets/` 下新增 `.js`，导出 `id`、`displayName`、`discoveryPaths`、`write(content, ctx)`、`extract(content)`。
2. 在 `scripts/lib/install-targets/registry.js` 的目标列表中追加该模块的 `require` 与注册项。
3. 在 `docs/targets.md` 的支持列表中补一行，并标注发现路径与文件格式（如 `.cursor/rules/*.mdc`、`.qwen/AGENTS.md` 等）。
4. 视需要补充 README 多语言翻译（中文、英文、法文 [#848](https://github.com/Fmarzochi/EGC/issues/848) 等）。
这一约定使得 Cline、Qwen Code、JetBrains Junie、Roo Code 等目标均以独立 PR 形式快速合入，而不会污染核心 CLI。资料来源：[scripts/lib/install-targets/registry.js:1-60]()、[docs/targets.md:1-40]()、[README.md:40-80]()
---
## egc-memory 持久记忆系统
### 相关页面
相关主题：[项目概述、安装与多工具集成目标](#page-overview-install), [egc-guardian 安全守护层与 LLM 调度](#page-guardian-system)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/servers/egc-memory/src/index.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/index.ts)
- [mcp/servers/egc-memory/src/working-memory.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/working-memory.ts)
- [mcp/servers/egc-memory/src/branch-state.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/branch-state.ts)
- [mcp/servers/egc-memory/src/patterns.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/patterns.ts)
- [mcp/servers/egc-memory/src/compress.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/compress.ts)
- [mcp/servers/egc-memory/src/encryption.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-memory/src/encryption.ts)
# egc-memory 持久记忆系统
## 系统定位与总体架构
`egc-memory` 是 EGC 项目中以 MCP（Model Context Protocol）服务器形式提供的持久记忆子系统，位于 `mcp/servers/egc-memory/` 目录下。它专门服务于多 AI 编码代理协同场景：当 Cursor、GitHub Copilot、JetBrains Junie、Cline、Qwen Code、Gemini CLI、Windsurf 等工具在同一项目内协作时，每个会话天然是无状态的，代理之间需要一种"跨工具、跨会话、可回溯"的共享记忆通道。`egc-memory` 即承担这一职责——它把编码过程中沉淀下来的上下文（决策、约束、习惯、未完成任务）以结构化方式持久化，使下游代理在新的会话开始时能立即恢复认知。
入口模块 `mcp/servers/egc-memory/src/index.ts` 负责服务器引导、工具注册以及与 `egc watch` 守护进程的协同，它把记忆读写操作封装为 MCP 工具暴露给宿主代理。资料来源：[mcp/servers/egc-memory/src/index.ts:1-1]()。
## 核心模块分工
### 工作记忆（working-memory）
`working-memory.ts` 实现会话级别的高速缓存层，对应人类认知中的"短时记忆"。它在内存中保存当前任务栈、活动文件、临时变量等易变信息，并在会话结束时按规则下沉到持久层。它与 `egc watch`（见 v1.1.2 发布说明）形成上下游关系：当 `watch` 检测到工具配置文件中的 EGC 块被直接修改时，会触发 `working-memory` 的失效与重建逻辑，从而保证所有代理读取到的是同一份最新上下文。资料来源：[mcp/servers/egc-memory/src/working-memory.ts:1-1]()。
### 分支状态（branch-state）
`branch-state.ts` 提供基于 Git 分支的隔离记忆视图。不同分支往往对应不同的实验方向或重构路径，若不加隔离，分支间的临时决策会相互污染。该模块为每条分支维护独立的记忆命名空间，并支持切换时的合并/分叉策略，使得代理在 `git checkout` 后能立刻获得与该分支历史相符的上下文。资料来源：[mcp/servers/egc-memory/src/branch-state.ts:1-1]()。
### 模式识别（patterns）
`patterns.ts` 承担长程归纳任务：从累积的会话中提炼出可复用的编码模式、命名偏好、目录约定与禁忌事项。它输出的是"半结构化知识"，可供 `egc install --target ` 在生成各工具专用规则时引用，从而保证 Cursor 的 `.cursorrules`、Junie 的 guidelines、Cline 的 rules 等在风格层面保持一致。资料来源：[mcp/servers/egc-memory/src/patterns.ts:1-1]()。
### 压缩（compress）
`compress.ts` 解决记忆膨胀问题。长期积累的会话与决策会迅速超过 token 预算与磁盘配额，该模块对旧记忆进行摘要、引用化与去重，仅保留高密度索引。它通常与 `patterns.ts` 串联工作——压缩后的低层细节被向上归纳为模式条目。资料来源：[mcp/servers/egc-memory/src/compress.ts:1-1]()。
### 加密（encryption）
`encryption.ts` 保证记忆落盘时的机密性。开发者偏好、API 密钥提示、未公开的内部约定都属于敏感信息；该模块在写入前对内容进行加密，在读取时按需解密，与本机密钥环或 EGC 自身的凭据系统集成，确保即使 `~/.egc/state/` 被共享或备份也难以泄露明文。资料来源：[mcp/servers/egc-memory/src/encryption.ts:1-1]()。
## 模块协作与数据流
下面用一个 Mermaid 图描述一次典型的代理会话中各模块的协作关系：
```mermaid
flowchart LR
A[AI 编码代理] -->|MCP 调用| B[index.ts]
B --> C[working-memory]
C --> D[branch-state]
D --> E[(持久存储)]
E --> F[patterns]
F --> G[compress]
G --> H[encryption]
H --> E
F -->|生成规则片段| A
C -->|失效/重建| I[egc watch]
I -->|同步到工具配置| A
```
代理发出的读/写请求首先进入 `index.ts`，由它路由到 `working-memory` 的会话层，再经 `branch-state` 决定命名空间；写入路径在落地前必须穿过 `encryption`，而读取路径则先经 `compress` 与 `patterns` 重组出与当前任务最相关的上下文片段返回给代理。`egc watch` 作为外部观察者，会在工具配置被直接编辑后回灌到 `working-memory`，形成闭环。资料来源：[mcp/servers/egc-memory/src/index.ts:1-1]()、[mcp/servers/egc-memory/src/branch-state.ts:1-1]()、[mcp/servers/egc-memory/src/encryption.ts:1-1]()。
## 与 EGC 其他特性的关系
`egc-memory` 并非孤立系统，而是 EGC 多工具治理平台的一部分。它向上承接 `egc install` 在各原生目标（Junie、Cline、Roo Code、Qwen Code 等，见 issue #847、#846、#852、#845）中写入的初始上下文；向下配合 `egc watch` 的双向同步守护进程（v1.1.2 发布特性），把直接发生在 `.cursorrules`、Junie guidelines、Cline rules 等文件中的本地编辑抽回持久层并广播给所有工具。换言之，`egc-memory` 是 EGC 实现"一次定义、处处生效、自动回灌"承诺的中央账本。资料来源：[mcp/servers/egc-memory/src/index.ts:1-1]()、[mcp/servers/egc-memory/src/patterns.ts:1-1]()。
---
## egc-guardian 安全守护层与 LLM 调度
### 相关页面
相关主题：[egc-memory 持久记忆系统](#page-memory-system), [项目概述、安装与多工具集成目标](#page-overview-install)
相关源码文件
以下源码文件用于生成本页说明：
- [mcp/servers/egc-guardian/src/index.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/index.ts)
- [mcp/servers/egc-guardian/src/validator.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/validator.ts)
- [mcp/servers/egc-guardian/src/guardian-cli.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/guardian-cli.ts)
- [mcp/servers/egc-guardian/src/llm-router.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/llm-router.ts)
- [mcp/servers/egc-guardian/src/headroom-client.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/headroom-client.ts)
- [mcp/servers/egc-guardian/src/audit-log.ts](https://github.com/Fmarzochi/EGC/blob/main/mcp/servers/egc-guardian/src/audit-log.ts)
# egc-guardian 安全守护层与 LLM 调度
`egc-guardian` 是 EGC（Enforced Generative Context）项目内置的一个 MCP（Model Context Protocol）服务器，承担"安全守护层 + LLM 调度网关"的双重职责。它位于所有 LLM 调用链路的关键路径上，对每一次工具调用、文件写入、命令执行与上下文注入进行合规校验，并在需要时通过统一路由器选择合适的模型后端，再把响应安全地回传给调用方。
## 模块职责划分
整个守护进程由 6 个核心模块协同工作：
- **入口协调（index.ts）**：注册 MCP 工具与资源、加载配置、初始化校验器与路由器，作为服务编排枢纽。
资料来源：[mcp/servers/egc-guardian/src/index.ts:1-80]()
- **输入/输出校验（validator.ts）**：实现白名单/黑名单规则匹配、敏感信息（密钥、令牌、个人隐私）正则扫描、结构化字段校验，是整个守护流程的第一道闸门。
资料来源：[mcp/servers/egc-guardian/src/validator.ts:1-120]()
- **命令行子入口（guardian-cli.ts）**：提供 `egc-guardian` 可执行包装，允许在不启动 MCP 长连接的情况下执行一次性审计、规则测试与离线校验。
资料来源：[mcp/servers/egc-guardian/src/guardian-cli.ts:1-60]()
- **LLM 路由器（llm-router.ts）**：依据策略（成本、延迟、上下文窗口、本地/云端）选择 OpenAI、Anthropic、本地 Ollama 或其他兼容端点，并对响应内容再次执行校验。
资料来源：[mcp/servers/egc-guardian/src/llm-router.ts:1-140]()
- **Headroom 客户端（headroom-client.ts）**：与外部 Headroom 服务通信，实现长上下文的压缩/截断，确保注入到不同模型的 prompt 不超过其上下文上限。
资料来源：[mcp/servers/egc-guardian/src/headroom-client.ts:1-90]()
- **审计日志（audit-log.ts）**：将每一次拦截、路由决策、规则命中事件写入本地追加日志，支持后续回放与合规审查。
资料来源：[mcp/servers/egc-guardian/src/audit-log.ts:1-70]()
## 请求处理流水线
```mermaid
flowchart LR
A[Agent/IDE 调用] --> B[index.ts MCP 入口]
B --> C{validator.ts 校验}
C -- 通过 --> D[headroom-client.ts 压缩上下文]
D --> E[llm-router.ts 选模型]
E --> F[LLM 后端]
F --> G[validator.ts 输出复核]
G --> H[audit-log.ts 记录]
H --> I[返回 Agent/IDE]
C -- 拒绝 --> H
G -- 不合规 --> H
```
## 关键安全策略
1. **纵深防御**：在请求侧（输入校验）与响应侧（输出复核）双重把关，避免单点失效。
资料来源：[mcp/servers/egc-guardian/src/validator.ts:30-80]()
2. **上下文受控**：通过 Headroom 客户端对长 prompt 做截断与摘要，防止上下文窗口溢出或敏感信息随 prompt 一并泄露。
资料来源：[mcp/servers/egc-guardian/src/headroom-client.ts:10-60]()
3. **可观测性**：所有拦截、路由、策略命中事件均落入 `audit-log.ts`，便于事后审计与回放调试。
资料来源：[mcp/servers/egc-guardian/src/audit-log.ts:15-55]()
4. **可独立运行的 CLI**：`guardian-cli.ts` 把上述校验能力封装为独立命令，便于在 CI/CD 流水线或脚本中复用，而无需启动完整 MCP 服务。
资料来源：[mcp/servers/egc-guardian/src/guardian-cli.ts:20-70]()
## 与社区演进方向的关系
近期社区关注的焦点是扩展安装目标（如 Junie、Cline、Qwen Code、Roo Code 等，参见 #847、#846、#845、#852），而 `egc-guardian` 正是保证这些目标在调用 LLM 时仍遵守统一安全约束的关键组件。随着更多 IDE/Agent 接入 EGC，校验规则、路由策略与审计输出均需随之扩展——每新增一种安装目标，就意味着 `validator.ts` 的规则集与 `llm-router.ts` 的端点表都要更新一次。`v1.1.2` 引入的 `egc watch` 双向同步守护进程同样需要 `audit-log.ts` 的事件源来维持一致性，因此本模块实际上承担了 EGC 跨工具一致性体验的安全底盘角色。
---
**总结**：`egc-guardian` 通过"入口 + 校验 + 路由 + 上下文治理 + 审计"的五段式架构，把 EGC 的安全策略下沉到所有 LLM 调用之前，是 EGC 跨工具一致性体验的安全底盘。任何新增的 AI 编程工具只有经过这一层守护，才能获得与 EGC 自身一致的安全保证与可观测性。
---
## 提示词库：智能体、技能、命令与规则
### 相关页面
相关主题：[项目概述、安装与多工具集成目标](#page-overview-install), [egc-guardian 安全守护层与 LLM 调度](#page-guardian-system)
相关源码文件
以下源码文件用于生成本页说明：
- [agents/code-reviewer.md](https://github.com/Fmarzochi/EGC/blob/main/agents/code-reviewer.md)
- [agents/architect.md](https://github.com/Fmarzochi/EGC/blob/main/agents/architect.md)
- [agents/security-reviewer.md](https://github.com/Fmarzochi/EGC/blob/main/agents/security-reviewer.md)
- [agents/planner.md](https://github.com/Fmarzochi/EGC/blob/main/agents/planner.md)
- [commands/plan.md](https://github.com/Fmarzochi/EGC/blob/main/commands/plan.md)
- [commands/code-review.md](https://github.com/Fmarzochi/EGC/blob/main/commands/code-review.md)
- [skills/SKILL.md](https://github.com/Fmarzochi/EGC/blob/main/skills/SKILL.md)
- [rules/coding-style.md](https://github.com/Fmarzochi/EGC/blob/main/rules/coding-style.md)
- [scripts/lib/install-targets/junie.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/junie.sh)
- [scripts/lib/install-targets/cline.sh](https://github.com/Fmarzochi/EGC/blob/main/scripts/lib/install-targets/cline.sh)
# 提示词库：智能体、技能、命令与规则
EGC（Engineering Guidelines Context）的核心价值在于把"团队工程规范"以结构化、可移植的形式注入到各种 AI 编码代理中。本页描述仓库内的提示词库（Prompt Library），它由四类资产组成：**智能体（Agents）**、**技能（Skills）**、**命令（Commands）** 和 **规则（Rules）**。它们共同构成 EGC 的"上下文源（source of truth）"，由安装目标（install targets）按各工具的发现路径分发写入。资料来源：[agents/code-reviewer.md:1-40]()
## 一、智能体（Agents）：面向角色的系统提示
智能体文件位于 `agents/` 目录，每个文件对应一个专家角色，使用 Markdown 描述人格、目标、约束与产出。
- **code-reviewer**：以"严格但不刁难"的语气审查 PR，关注命名、可读性、边界条件与测试覆盖。资料来源：[agents/code-reviewer.md:1-30]()
- **architect**：负责系统设计、模块边界、依赖方向与技术选型权衡。资料来源：[agents/architect.md:1-30]()
- **security-reviewer**：聚焦 OWASP Top 10、机密泄露、注入与依赖漏洞。资料来源：[agents/security-reviewer.md:1-30]()
- **planner**：把模糊需求拆解为可执行任务清单与里程碑。资料来源：[agents/planner.md:1-30]()
智能体文件之间存在**互补关系**：planner 产出计划、architect 把关结构、code-reviewer 与 security-reviewer 在合并前把关。这套角色矩阵让用户在 CLI 中通过 `egc install --target ` 将同一份人格说明映射到不同工具的发现路径，例如 JetBrains Junie、Cline、Qwen Code 等。资料来源：[scripts/lib/install-targets/junie.sh:1-40](), [scripts/lib/install-targets/cline.sh:1-40]()
## 二、命令（Commands）：触发特定工作流的斜杠指令
命令文件位于 `commands/` 目录，每个文件以 Markdown 描述一个用户可主动触发的斜杠（slash）指令流程。
- `plan.md`：把需求转化为分阶段任务清单，输出可勾选的 TODO。资料来源：[commands/plan.md:1-30]()
- `code-review.md`：对当前 diff 执行结构化评审，输出一份按"严重/重要/建议"分级的报告。资料来源：[commands/code-review.md:1-30]()
命令与智能体的区别在于：智能体是**被动上下文**（只要安装就会随项目加载），命令是**主动触发**（用户显式调用才会执行）。两者通过 `egc install` 同步写入目标工具的对应目录。
## 三、技能（Skills）：可复用的领域能力包
技能文件位于 `skills/`，代表可被多个智能体或命令复用的"领域知识块"。根入口 `skills/SKILL.md` 定义了技能的元信息（名称、版本、适用场景、输入/输出契约）。资料来源：[skills/SKILL.md:1-40]()
技能与智能体的关系类似函数与角色：一个技能可以被多个智能体引用，避免提示词重复，也方便按版本管理。EGC 的安装管线在写入目标工具时，会把技能作为独立文件原样保留，让工具自身决定如何发现与加载。
## 四、规则（Rules）：跨场景生效的硬性约束
规则文件位于 `rules/` 目录，提供全局生效、不可被智能体覆盖的硬性约束，例如 `coding-style.md` 规定命名规范、注释要求、提交消息格式等。资料来源：[rules/coding-style.md:1-30]()
| 资产类型 | 目录 | 加载方式 | 是否可被覆盖 |
| --- | --- | --- | --- |
| Agents | `agents/` | 工具启动时随上下文加载 | 否 |
| Skills | `skills/` | 智能体或命令按需引用 | 否 |
| Commands | `commands/` | 用户显式斜杠触发 | 否 |
| Rules | `rules/` | 始终作为系统级约束注入 | 否 |
四类资产统一遵循"单一事实源（single source of truth）"原则：修改仓库内的源文件后，重新执行 `egc install` 或 `egc watch`（v1.1.2 引入的双向同步守护进程）即可把变更同步到所有已安装的工具配置中。资料来源：[release v1.1.2]()
## 五、与社区演进的关系
近期社区讨论集中在**扩展原生安装目标**（如 JetBrains Junie #847、Cline #846、Roo Code #852、Qwen Code #845），这些 PR 的本质都是把同一套提示词库映射到更多工具的发现路径，而不需要重写 `agents/`、`commands/`、`skills/`、`rules/` 下的源文件。这印证了提示词库的"工具无关（tool-agnostic）"设计：新增工具只是新增 `scripts/lib/install-targets/` 下的一个适配脚本。
此外，多语言 README 翻译（如法语 #848）虽属 i18n 范畴，但反映了社区对**把规范以可读形式传递给非英语开发者**的重视，这与 EGC 把"工程规范"作为一等公民的定位一脉相承。
---
---
## Doramagic 踩坑日志
项目：Fmarzochi/EGC
摘要：发现 26 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: feat(install): add native Cline install target。
## 1. 安装坑 · 失败模式：installation: feat(install): add native Cline install target
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat(install): add native Cline install target
- 对用户的影响：Developers may fail before the first successful local run: feat(install): add native Cline install target
- 证据：failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/846 | feat(install): add native Cline install target
## 2. 安装坑 · 失败模式：installation: feat(install): add native JetBrains Junie install target
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat(install): add native JetBrains Junie install target
- 对用户的影响：Developers may fail before the first successful local run: feat(install): add native JetBrains Junie install target
- 证据：failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/847 | feat(install): add native JetBrains Junie install target
## 3. 安装坑 · 失败模式：installation: feat(install): add native Qwen Code install target
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: feat(install): add native Qwen Code install target
- 对用户的影响：Developers may fail before the first successful local run: feat(install): add native Qwen Code install target
- 证据：failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/845 | feat(install): add native Qwen Code install target
## 4. 安装坑 · 来源证据：feat(install): add native Cline install target
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(install): add native Cline install target
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Fmarzochi/EGC/issues/846 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：feat(install): add native JetBrains Junie install target
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(install): add native JetBrains Junie install target
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Fmarzochi/EGC/issues/847 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：feat(install): add native Qwen Code install target
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(install): add native Qwen Code install target
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Fmarzochi/EGC/issues/845 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 安装坑 · 来源证据：feat(install): add native Roo Code install target
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat(install): add native Roo Code install target
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Fmarzochi/EGC/issues/852 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/Fmarzochi/EGC | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli
## 9. 配置坑 · 失败模式：configuration: v1.1.10
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.10
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.10
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.10 | v1.1.10
## 10. 配置坑 · 失败模式：configuration: v1.1.11
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.11
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.11
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.11 | v1.1.11
## 11. 配置坑 · 失败模式：configuration: v1.1.2
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.2
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.2
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.2 | v1.1.2
## 12. 配置坑 · 失败模式：configuration: v1.1.3
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.3
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.3
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.3 | v1.1.3
## 13. 配置坑 · 失败模式：configuration: v1.1.4
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.4
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.4
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.4 | v1.1.4
## 14. 配置坑 · 失败模式：configuration: v1.1.5
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.5
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.5
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.5 | v1.1.5
## 15. 配置坑 · 失败模式：configuration: v1.1.6
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.6
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.6
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.6 | v1.1.6
## 16. 配置坑 · 失败模式：configuration: v1.1.7
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.7
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.7
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.7 | v1.1.7
## 17. 配置坑 · 失败模式：configuration: v1.1.8
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.8
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.8
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.8 | v1.1.8
## 18. 配置坑 · 失败模式：configuration: v1.1.9
- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.1.9
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.9
- 证据：failure_mode_cluster:github_release | https://github.com/Fmarzochi/EGC/releases/tag/v1.1.9 | v1.1.9
## 19. 能力坑 · 来源证据：i18n(fr): add French README translation
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：i18n(fr): add French README translation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/Fmarzochi/EGC/issues/848 | 来源类型 github_issue 暴露的待验证使用条件。
## 20. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Fmarzochi/EGC | README/documentation is current enough for a first validation pass.
## 21. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Fmarzochi/EGC | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Fmarzochi/EGC | no_demo; severity=medium
## 23. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Fmarzochi/EGC | no_demo; severity=medium
## 24. 能力坑 · 失败模式：capability: i18n(fr): add French README translation
- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: i18n(fr): add French README translation
- 对用户的影响：Developers may hit a documented source-backed failure mode: i18n(fr): add French README translation
- 证据：failure_mode_cluster:github_issue | https://github.com/Fmarzochi/EGC/issues/848 | i18n(fr): add French README translation
## 25. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Fmarzochi/EGC | issue_or_pr_quality=unknown
## 26. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Fmarzochi/EGC | release_recency=unknown