<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/tractorjuice/arckit-gemini) · [上游 README](https://github.com/tractorjuice/arckit-gemini/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

# ArcKit - Gemini CLI Extension

**面向 Gemini CLI 的企业架构治理工具集（Harness）**

ArcKit 在 Gemini CLI 内提供 75 个斜杠命令，覆盖战略、架构、交付、保障与互操作性——包括英国政府合规要求。

## Installation

```bash
gemini extensions install https://github.com/tractorjuice/arckit-gemini
```

### Prerequisites

- **[Gemini CLI](https://github.com/google-gemini/gemini-cli)**: `npm install -g @google/gemini-cli@latest`
- **Node.js**：运行 MCP 服务器桥接（AWS Knowledge、Microsoft Learn）所必需

### Optional: Google Cloud Research

要使用 `/arckit:gcp-research`，请配置你的 Google API key：

```bash
# Set via Gemini CLI settings, or export directly:
export GOOGLE_API_KEY="your-api-key"
```

在 https://makersuite.google.com/app/apikey 获取 key

## Quick Start

```bash
# Start Gemini CLI in your project
cd /path/to/your/project
gemini

# Create a project plan
/arckit:plan Create project plan for cloud migration with 6-month timeline

# Establish governance
/arckit:principles Create cloud-first architecture principles

# Analyze stakeholders
/arckit:stakeholders Analyze stakeholders for payment gateway where CFO wants cost savings

# Define requirements
/arckit:requirements Create requirements for cloud migration project

# Research cloud platforms
/arckit:aws-research Evaluate AWS services for serverless architecture
/arckit:azure-research Evaluate Azure services for enterprise integration
/arckit:gcp-research Evaluate GCP services for data analytics platform
```

## Core Commands

### Phase 0: Project Planning

| Command | Description |
|---------|-------------|
| `/arckit:init` | 初始化 ArcKit 项目结构 |
| `/arckit:plan` | 基于 GDS Agile Delivery 阶段与 Mermaid 甘特图的项目计划 |
| `/arckit:start` | 引导式项目入门、工作流选择与命令推荐 |
| `/arckit:strategy` | 企业架构战略文档 |

### Phase 1: Discovery

| Command | Description |
|---------|-------------|
| `/arckit:principles` | 架构原则（全局、跨项目） |
| `/arckit:stakeholders` | 利益相关方分析（驱动因素、目标、RACI） |
| `/arckit:risk` | 风险登记册（HM Treasury Orange Book） |
| `/arckit:sobc` | 战略概要商业案例（Strategic Outline Business Case，HM Treasury Green Book） |

### Phase 2: Alpha

| Command | Description |
|---------|-------------|
| `/arckit:requirements` | 全面需求（BR/FR/NFR/INT/DR） |
| `/arckit:data-model` | 数据模型（含 ERD、GDPR 合规） |
| `/arckit:data-mesh-contract` | 联邦数据产品契约（ODCS v3.0.2） |
| `/arckit:dpia` | 数据保护影响评估（Data Protection Impact Assessment，GDPR Article 35） |
| `/arckit:platform-design` | 基于 Platform Design Toolkit 的平台战略 |
| `/arckit:wardley` | Wardley Map 及战略分析 |
| `/arckit:roadmap` | 多年期战略架构路线图 |
| `/arckit:adr` | 架构决策记录（Architecture Decision Record，MADR 格式） |
| `/arckit:dfd` | Yourdon-DeMarco 数据流图（DFDs）及结构化分析标注 |
| `/arckit:diagram` | 架构图（C4、Mermaid） |

### Phase 3: Research & Procurement

| Command | Description |
|---------|-------------|
| `/arckit:research` | 技术调研（含自研 vs 采购分析） |
| `/arckit:datascout` | 数据源发现与 API 目录检索 |
| `/arckit:aws-research` | AWS 服务调研（通过 AWS Knowledge MCP） |
| `/arckit:azure-research` | Azure 服务调研（通过 Microsoft Learn MCP） |
| `/arckit:gcp-research` | GCP 服务调研（通过 Google Developer Knowledge MCP） |
| `/arckit:gcloud-search` | G-Cloud 14 框架检索 |
| `/arckit:gcloud-clarify` | G-Cloud 供应商澄清问题 |
| `/arckit:dos` | Digital Outcomes and Specialists 采购 |
| `/arckit:sow` | RFP 工作说明书（Statement of Work） |
| `/arckit:evaluate` | 供应商评分与评估 |
| `/arckit:framework` | 将制品转化为带原则与指南的结构化框架 |

### Phase 4: Beta & Live

| Command | Description |
|---------|-------------|
| `/arckit:hld-review` | 高层设计（High-Level Design）评审 |
| `/arckit:dld-review` | 详细设计（Detailed-Level Design）评审 |
| `/arckit:principles-compliance` | 架构原则合规性（RAG 证据） |
| `/arckit:service-assessment` | GDS Service Standard 评估 |
| `/arckit:secure` | 英国政府 Secure by Design 评审 |
| `/arckit:mod-secure` | MOD Secure by Design 评审 |
| `/arckit:jsp-936` | JSP 936 AI 保障文档 |
| `/arckit:tcop` | Technology Code of Practice 评估 |
| `/arckit:atrs` | AI Transparency Risk Standards 评估 |
| `/arckit:ai-playbook` | AI Playbook 合规检查 |
| `/arckit:conformance` | 架构一致性评估（ADR 实施、漂移、技术债） |

### Phase 5: Operations & Delivery

| Command | Description |
|---------|-------------|
| `/arckit:devops` | DevOps 成熟度评估与 CI/CD 流水线设计 |
| `/arckit:finops` | FinOps 云成本优化评估 |
| `/arckit:mlops` | MLOps 成熟度评估与 ML 流水线设计 |
| `/arckit:operationalize` | 服务运营化与 runbook 生成 |
| `/arckit:backlog` | 可用于 Sprint 的待办项生成 |
| `/arckit:presentation` | 基于项目制品的 MARP 演示幻灯片 |
| `/arckit:story` | 面向指导委员会的高管叙事 |

### Analysis & Reporting

| Command | Description |
|---------|-------------|
| `/arckit:analyze` | 跨全部制品的综合差距分析 |
| `/arckit:traceability` | 需求可追溯性矩阵 |
| `/arckit:servicenow` | ServiceNow CMDB 导出设计 |
| `/arckit:trello` | Trello 看板导出 |
| `/arckit:glossary` | 项目术语与缩写汇总词汇表 |
| `/arckit:health` | 项目健康扫描（过期调研、孤立制品、漂移） |
| `/arckit:maturity-model` | 能力成熟度模型及评估标准 |
| `/arckit:pages` | GitHub Pages 文档站点 |

### Utilities

| Command | Description |
|---------|-------------|
| `/arckit:customize` | 模板自定义管理器 |
| `/arckit:template-builder` | 通过交互式访谈创建新文档模板 |

### Interoperability

| Command | Description |
|---------|-------------|
| `/arckit:export-okf` | 将 ArcKit 制品导出为 OKF 兼容的 Markdown 包 |
| `/arckit:import-okf` | 导入 OKF 包作为可审阅的调研笔记 |

## Agents

ArcKit 包含 6 个自主调研智能体，用于处理依赖 Web 的繁重任务：

- **arckit-research** — 市场调研、供应商评估、自研 vs 采购
- **arckit-datascout** — 数据源发现、API 目录检索
- **arckit-aws-research** — AWS 服务调研（通过 AWS Knowledge MCP）
- **arckit-azure-research** — Azure 服务调研（通过 Microsoft Learn MCP）
- **arckit-gcp-research** — GCP 服务调研（通过 Google Developer Knowledge MCP）
- **arckit-framework** — 将制品转化为结构化框架

## Hooks

自动化钩子会在会话期间触发，以提供上下文并强制执行标准：

- **Session Init** — 启动时注入 ArcKit 版本与项目状态
- **Context Inject** — 在智能体规划前添加项目制品清单
- **Filename Validator** — 在写入文件时校验 ARC-xxx 命名约定
- **File Protection** — 阻止写入敏感/受保护文件
- **Manifest Updater** — 写入项目文件后更新 manifest.json

## Policies

策略规则用于保障扩展安全：

- 防止修改 ArcKit 扩展系统文件
- 在文件内容可能包含潜在密钥时发出警告

## Theme

ArcKit 包含采用英国政府设计系统（UK Government Design System）官方配色的 GDS 品牌终端主题。

## Template Customization

将自定义版本放在项目中即可覆盖默认模板：

```bash
# Create override directory
mkdir -p .arckit/templates

# Copy and edit a template
cp ~/.gemini/extensions/arckit/templates/requirements-template.md .arckit/templates/

# Edit to match your organization's needs
# Commands will automatically use your override
```

常见自定义项：

- 非英国政府项目可移除 UK Government（英国政府）相关章节
- 添加组织专属的文档控制（Document Control）字段
- 更改需求 ID 前缀
- 添加品牌标识、页眉和页脚

## 工作流示例

```bash
# 1. Create project plan
/arckit:plan Create project plan for payment modernization with 6-month timeline

# 2. Establish governance
/arckit:principles Create cloud-first principles for financial services

# 3. Discovery phase
/arckit:stakeholders Analyze stakeholders for payment gateway
/arckit:risk Create risk register for payment modernization
/arckit:sobc Create Strategic Outline Business Case with £2M investment

# 4. Alpha phase
/arckit:requirements Create requirements for payment gateway
/arckit:data-model Create data model for payment transactions with PCI-DSS compliance
/arckit:wardley Create Wardley map showing build vs buy for payment infrastructure

# 5. Research & procurement
/arckit:research Research payment processing platforms
/arckit:aws-research Evaluate AWS payment services
/arckit:gcloud-search Search G-Cloud 14 for payment processing services

# 6. Design reviews
/arckit:hld-review Review high-level design for microservices architecture
/arckit:secure Conduct Secure by Design review

# 7. Delivery
/arckit:backlog Generate sprint backlog with velocity 20 and 8 sprints
```

## MCP 服务器

本扩展内置三个用于云研究的 MCP 服务器：

| 服务器 | 用途 | 是否需要认证 |
|--------|---------|---------------|
| AWS Knowledge | AWS 服务文档与最佳实践 | 无 |
| Microsoft Learn | Azure 与 Microsoft 文档 | 无 |
| Google Developer Knowledge | GCP 文档 | `GOOGLE_API_KEY` |

MCP 服务器通过 `mcp-remote` 桥接（需要 Node.js）。

## 替代安装方式：ArcKit CLI

建议所有 Gemini CLI 用户使用本扩展，它提供自动更新和简洁的零配置体验。

## 链接

- **ArcKit 主仓库**：[github.com/tractorjuice/arc-kit](https://github.com/tractorjuice/arc-kit)
- **Claude Code 插件**：通过 `/plugin marketplace add tractorjuice/arckit-claude` 安装
- **问题反馈**：[github.com/tractorjuice/arc-kit/issues](https://github.com/tractorjuice/arc-kit/issues)
- **Gemini CLI**：[github.com/google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli)

## 许可证

MIT 许可证 — 详情请参阅 [LICENSE](LICENSE)。