jscraik/diagram-cli
GitHub: jscraik/diagram-cli
一款用于生成架构图并执行架构策略验证的命令行工具，解决代码变更带来的架构一致性与风险识别问题。
Stars: 0 | Forks: 0
# diagram-cli
从源代码生成架构图、验证报告和 PR 影响工件。
## 目录
- [概述](#overview)
- [快速开始](#quick-start)
- [推荐起步路径](#opinionated-starter-path)
- [人工工作流](#human-workflows)
- [AI 代理工作流](#ai-agent-workflows)
- [机器输出契约](#machine-output-contracts)
- [文档索引](#documentation-index)
- [开发](#development)
## 概述
`diagram-cli` 会扫描你的仓库并生成：
- Mermaid 图表（`generate`、`generate-all`）
- 架构策略验证（`validate`）
- PR 架构影响报告（`workflow pr`）
- AI 上下文工件（`context`）
扫描参数的默认解析优先级如下：
1. CLI 标志
2. `.diagramrc`
3. 命令内置值
这适用于 `patterns`、`exclude`、`maxFiles` 和相关 `theme`。
## 快速开始
```
git clone https://github.com/jscraik/diagram-cli.git
cd diagram-cli
npm install
npm link
```
无需 `npm link`，可直接使用 `node src/diagram.js ...` 运行命令。
## 推荐起步路径
适用于新仓库的起步路径：
```
diagram init .
diagram doctor .
diagram validate .
diagram generate-all . --output-dir .diagram --artifact-profile agent
diagram context .
```
它为你提供：
- `.architecture.yml` 起步规则
- `.diagramrc` 默认配置
- CI 步骤示例：`.diagram/ci/github-actions-step.yml`
- 工具链诊断（CI rollout 前）
- 紧凑的 AI 友好架构工件
## 人工工作流
```
# 分析仓库结构
diagram analyze .
# 生成一张图并打开预览
diagram generate . --type architecture --open
# 仅分析分支中已更改的文件
diagram changed . --base origin/main --head HEAD
# 解释本地依赖邻域
diagram explain auth-service .
# PR 风险/影响范围报告
diagram workflow pr . --base origin/main --head HEAD --risk-threshold medium --fail-on-risk
```
## AI 代理工作流
```
# 稳定的机器输出
diagram generate . --type architecture --format json --deterministic
diagram workflow pr . --base origin/main --head HEAD --format json --deterministic
# 紧凑的上下文包以适应代理令牌预算
diagram generate-all . --output-dir .diagram --artifact-profile agent
diagram context .
```
## 机器输出契约
- 使用 `--format json` 获取机器输出。
- `--json` 是兼容别名，归一化为 `--format json`。
- 命令输出包含明确的 `schemaVersion` 值。
- 使用 `--deterministic` 以在机器负载中获得稳定的排序/时间戳。
- PR 影响 JSON 包含 `agentSummary`，其中包括：
- `changedComponents`
- `riskReasons`
- `suggestedReviewerChecks`
## 文档索引
- [CLI 参考](docs/cli-reference.md)
- [快速入门](docs/getting-started.md)
- [架构测试](docs/architecture-testing.md)
- [从 dependency-cruiser 迁移](docs/migration-from-dependency-cruiser.md)
- [维护者文档索引](docs/README.md)
## 开发
```
npm install
npm test
npm run test:deep
node src/diagram.js --help
```
## 许可证
Apache 2.0 - 参见 [LICENSE](LICENSE)。
标签：AI上下文工件, GNU通用公共许可证, Mermaid, MITM代理, Node.js, npm工具, PR影响分析, WebSocket, 依赖分析, 图生成, 威胁情报, 工作流自动化, 开发者工具, 开箱即用, 数据可视化, 架构可视化, 架构治理, 架构验证, 源码分析, 策略强制执行, 自定义脚本, 诊断工具, 静态架构图