内容
# enji-guard-cli
Python 3.14 命令行界面和 MCP 桥接器，用于 Enji Guard。
本仓库是一个早期原型。它支持共享核心、Typer 命令行界面和 FastMCP 服务器，可以向本地工具公开 Enji Guard 访问和紧凑的报告元数据。
## 思维模型
Enji Guard 将 GitHub 仓库分组为项目。大多数工作流程应该使用 GitHub `所有者/仓库名` 仓库选择器；仅当帐户有模糊的仓库或必须将批量操作限定为一个项目时，才添加 `--project 名称或ID`。
修改批量命令需要明确范围。使用 `REPO` 参数表示一个仓库，`--all-repos` 和 `--project 名称或ID` 表示一个项目中的所有仓库，或 `--all-projects` 表示所有项目中的所有仓库。
项目管理员命令是直接的域操作：创建、重命名、删除和在项目之间移动仓库。`project delete` 是破坏性的，需要 `--yes`。
Recon 是基线发现。报告审核是单独的、缓慢的作业，生成可读的报告和分数。分数是分类提示：使用它们对仓库进行排序和优先级排序，然后在更改代码之前阅读报告。当报告公开提交哈希时，请将其与当前检出进行比较，然后再将报告视为最新。
默认情况下，CLI 输出是人类文本和表格。只有当另一个工具需要结构化输出时，才使用 `--json`。
## 代理工作流程
服务运行时是 Docker。代理应该在运行的容器中调用 CLI，而不是在主机上安装或运行此 Python 包：
```bash
docker exec -i enji-guard-cli enji-guard --help
```
应用程序日志在容器外部持久保存于：
```text
~/.config/enji-guard/logs/enji-guard.jsonl
```
CLI 标准输出/标准错误仅用于命令结果、进度和 CLI 错误。请使用日志文件进行 HTTP/身份验证/运行时遥测。
在处理另一个仓库时，请将仓库作为 `所有者/仓库名` 传递。如果代理已经在 GitHub 检出中，并希望从 `origin` 派生它，可以在主机 shell 中执行此操作，并仍然向容器传递明确的选择器：
```bash
REPO=$(git config --get remote.origin.url | sed -E 's#^git@github.com:##; s#^https://github.com/##; s#\.git$##')
docker exec -i enji-guard-cli enji-guard auth status
docker exec -i enji-guard-cli enji-guard repo resolve "$REPO"
docker exec -i enji-guard-cli enji-guard status "$REPO"
```
如果仓库在 Enji 中不存在：
```bash
docker exec -i enji-guard-cli enji-guard repo connect "$REPO"
```
对于跨所有可见仓库的分类：
```bash
docker exec -i enji-guard-cli enji-guard status --sort weakest
docker exec -i enji-guard-cli enji-guard repo list --sort latest-report
```
对于报告：
```bash
docker exec -i enji-guard-cli enji-guard audit start "$REPO" --all
docker exec -i enji-guard-cli enji-guard wait "$REPO"
docker exec -i enji-guard-cli enji-guard report read "$REPO"
```
Recon 和报告审核可能需要数十分钟。使用 `status` 获取快照，`wait` 直到所有报告审核都有结果，`report read` 在报告准备好后。`wait` 报告过时的已审核提交哈希，但不会因 Enji 未跟上当前 HEAD 而失败。最好通过 CLI/MCP 读取报告，而不是依赖电子邮件；在工作流程中不涉及时，请禁用嘈杂的计划邮件。
## 需求
- Docker
- uv，仅用于仓库开发和 QA
## 运行时
```bash
mkdir -p ~/.config/enji-guard/logs
chown -R 1000:1000 ~/.config/enji-guard
chmod 700 ~/.config/enji-guard
docker compose up -d --force-recreate --remove-orphans --wait
docker exec -i enji-guard-cli enji-guard --help
```
Compose 将 MCP 绑定到环回地址，定义服务健康检查，并将容器内存限制为 512 MiB。
## 身份验证
首选的未来路径是 Enji API令牌：
```bash
printf '%s' "$ENJI_API_TOKEN" | docker exec -i enji-guard-cli enji-guard auth import-token --stdin
```
在 API令牌可用之前，cookie 身份验证作为临时兼容性路径受到支持：
```bash
pbpaste | docker exec -i enji-guard-cli enji-guard auth import-cookie --stdin
docker exec -i enji-guard-cli enji-guard auth status
```
请勿直接将凭证粘贴到 shell 历史记录中。身份验证文件默认为 `~/.config/enji-guard/auth.json`，并使用私有文件权限写入。
## 命令行界面
```bash
docker exec -i enji-guard-cli enji-guard access
docker exec -i enji-guard-cli enji-guard project list
docker exec -i enji-guard-cli enji-guard project create Pets
docker exec -i enji-guard-cli enji-guard project rename Pets Friends
docker exec -i enji-guard-cli enji-guard project delete Pets --yes
docker exec -i enji-guard-cli enji-guard repo resolve j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard repo move j2h4u/enji-guard-cli --to-project Friends
docker exec -i enji-guard-cli enji-guard status j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard audit start j2h4u/enji-guard-cli --all
docker exec -i enji-guard-cli enji-guard wait j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard report read j2h4u/enji-guard-cli
docker exec -i enji-guard-cli enji-guard --project Pets schedule list
docker exec -i enji-guard-cli enji-guard --project Pets schedule set --all-repos --enabled off
docker exec -i enji-guard-cli enji-guard --project Pets email set --all-repos --auto off
docker exec -i enji-guard-cli enji-guard auth refresh
```
当自动化使用命令输出时，请传递 `--json`。
在需要将命令限定为一个 Enji 项目时，请使用全局 `--project 名称或ID` 过滤器。
`repo move` 使用全局 `--project` 作为源项目或选择器消歧义（如果需要）。`--to-project` 选择目标项目。
`schedule` 控制自动报告审核运行。它显示每个仓库/报告审核的一行，可以批量更新一个仓库或一个显式批量范围的所有报告审核。使用 `REPO`、`--project 名称或ID --all-repos` 或 `--all-projects`。
## MCP
本地 HTTP MCP 服务：
```bash
docker compose up -d --force-recreate --remove-orphans --wait
```
端点：
```text
http://127.0.0.1:8001/mcp
```
Docker 服务启动后台 cookie 刷新循环。请保持 `~/.config/enji-guard` 可写，以便容器用户使用。
## 开发
```bash
just verify
```
完成门包括 Ruff、basedpyright、import-linter、Vulture、deptry、OpenAPI 合同验证、CRAP <= 30 per 函数、测试和 Docker 构建。
## 安全说明
Cookie 身份验证是临时的，在 Enji 中支持 API令牌后将被删除。MCP HTTP 传输不添加其自己的身份验证；请将它们绑定到环回地址或显式信任边界后面。
## 许可证
PolyForm 非商业许可 1.0.0。商业使用需要单独的许可。
