zhuge-workflow 0.1.4 → 0.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +173 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# zhuge-workflow
|
|
2
|
+
|
|
3
|
+
`zhuge-workflow` 是一个面向 AI 开发协作场景的 CLI 工具，命令名为 `zhuge`。
|
|
4
|
+
|
|
5
|
+
它的目标是：
|
|
6
|
+
|
|
7
|
+
- 自动检测并安装常用 AI 工作流工具
|
|
8
|
+
- 在本机部署统一的 Claude 配置模板
|
|
9
|
+
- 在项目内初始化协作文档与脚本
|
|
10
|
+
- 提供可复现的 CI/CD 发包流程（GitHub Actions → npm）
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## 支持项总览
|
|
15
|
+
|
|
16
|
+
### 1) CLI 命令支持
|
|
17
|
+
|
|
18
|
+
| 命令 | 说明 | 关键行为 |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `zhuge setup` | 安装/更新外部工具并部署配置 | 检测状态、选择 install/update、可选择锁定版本、部署配置模板 |
|
|
21
|
+
| `zhuge setup --yes` | CI/无人值守模式 | 跳过交互、执行可操作项、跳过配置部署交互 |
|
|
22
|
+
| `zhuge init` | 初始化当前项目 | 调用 OpenSpec/Trellis 初始化（若已安装）、生成 `.zhuge` 状态文件、创建/更新 `CLAUDE.md` |
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
### 2) 外部工具适配支持
|
|
27
|
+
|
|
28
|
+
当前内置 4 个 adapter（按执行顺序）：
|
|
29
|
+
|
|
30
|
+
| 工具 | 标识 | 安装方式 | 版本策略 | 交互式 |
|
|
31
|
+
| --- | --- | --- | --- | --- |
|
|
32
|
+
| OpenSpec | `openspec` | npm global | 支持锁定版本（默认 `1.1.1`）或 latest | 否 |
|
|
33
|
+
| Trellis | `trellis` | npm global | 支持锁定版本（默认 `0.2.15`）或 latest | 否 |
|
|
34
|
+
| Claude Code Bridge | `ccb` | git clone + install 脚本 | 无锁定版本策略 | 否 |
|
|
35
|
+
| CCG Workflow | `ccg` | `npx ccg-workflow` | 支持锁定版本（默认 `1.7.61`）或 latest | 是 |
|
|
36
|
+
|
|
37
|
+
补充说明：
|
|
38
|
+
|
|
39
|
+
- 每个 adapter 都有安装状态检测（install / update / skip）
|
|
40
|
+
- 支持失败隔离：某个工具失败不会中断其它工具执行
|
|
41
|
+
- 交互式工具（如 CCG）会关闭 spinner，直接把终端控制权交给工具本身
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
### 3) 配置部署支持（当前目标：Claude Code）
|
|
46
|
+
|
|
47
|
+
当前配置目标为 `Claude Code (~/.claude)`，支持以下部署规则：
|
|
48
|
+
|
|
49
|
+
| 模板源 | 目标路径 | 策略 | 说明 |
|
|
50
|
+
| --- | --- | --- | --- |
|
|
51
|
+
| `templates/claude/CLAUDE.md` | `~/.claude/CLAUDE.md` | `merge-section` | 替换 `<!-- Global -->` 区段 |
|
|
52
|
+
| `templates/claude/CLAUDE-ccg.md` | `~/.claude/CLAUDE.md` | `merge-section` | 替换 `<!-- CCG 增强 -->` 区段 |
|
|
53
|
+
| `templates/claude/rules/` | `~/.claude/rules/` | `replace` | 递归复制目录 |
|
|
54
|
+
| `templates/claude/skills/` | `~/.claude/skills/` | `replace` | 递归复制目录 |
|
|
55
|
+
| `templates/claude/commands/` | `~/.claude/commands/` | `replace` | 递归复制目录 |
|
|
56
|
+
|
|
57
|
+
支持的部署策略：
|
|
58
|
+
|
|
59
|
+
- `replace`：目标存在时先备份，再替换（文件）或递归复制（目录）
|
|
60
|
+
- `append`：追加内容且幂等（已有内容不重复追加）
|
|
61
|
+
- `merge-section`：按 marker 区段替换；marker 不存在时自动降级 append
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
### 4) 项目初始化支持（`zhuge init`）
|
|
66
|
+
|
|
67
|
+
`zhuge init` 在当前 git 项目内执行以下动作：
|
|
68
|
+
|
|
69
|
+
1. 校验当前目录是 git 仓库（否则退出）
|
|
70
|
+
2. 检测 OpenSpec/Trellis 是否可用，已安装则调用其 `init`
|
|
71
|
+
3. 创建 `.zhuge/init-state.json` 记录初始化状态
|
|
72
|
+
4. 创建或更新项目级 `CLAUDE.md`（幂等写入 zhuge 区段）
|
|
73
|
+
5. 部署增强模板：
|
|
74
|
+
- `templates/init/claude-agents/` → `.claude/agents/`
|
|
75
|
+
- `templates/init/claude-hooks/` → `.claude/hooks/`
|
|
76
|
+
- `templates/init/trellis-scripts/` → `.trellis/scripts/`
|
|
77
|
+
6. 若存在 `.gitignore`，自动追加 `.zhuge/`
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
### 5) CI/CD 与发布支持
|
|
82
|
+
|
|
83
|
+
仓库内已提供 npm 自动发布工作流：
|
|
84
|
+
|
|
85
|
+
- 文件：`.github/workflows/publish-npm.yml`
|
|
86
|
+
- 触发：
|
|
87
|
+
- push tag（`v*.*.*`）
|
|
88
|
+
- 手动 `workflow_dispatch`
|
|
89
|
+
- 发布前校验：测试、类型检查、构建、tag 与 `package.json` 版本一致性
|
|
90
|
+
- 发布命令：`npm publish --access public --provenance`
|
|
91
|
+
|
|
92
|
+
发布说明文档：`docs/npm-trusted-publishing.md`
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 快速开始
|
|
97
|
+
|
|
98
|
+
### 环境要求
|
|
99
|
+
|
|
100
|
+
- Node.js `>=20`
|
|
101
|
+
- 推荐 `pnpm`（开发）
|
|
102
|
+
- Git（`zhuge init` 依赖）
|
|
103
|
+
- 建议 Unix-like 环境（macOS / Linux）
|
|
104
|
+
|
|
105
|
+
### 安装
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
npm i -g zhuge-workflow
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
### 常用命令
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
# 交互式安装/更新工具 + 配置部署
|
|
115
|
+
zhuge setup
|
|
116
|
+
|
|
117
|
+
# CI 模式（跳过交互）
|
|
118
|
+
zhuge setup --yes
|
|
119
|
+
|
|
120
|
+
# 初始化当前项目
|
|
121
|
+
zhuge init
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## 开发与测试
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
# 安装依赖
|
|
130
|
+
pnpm install
|
|
131
|
+
|
|
132
|
+
# 构建
|
|
133
|
+
pnpm build
|
|
134
|
+
|
|
135
|
+
# 单元测试
|
|
136
|
+
pnpm test -- --run
|
|
137
|
+
|
|
138
|
+
# 类型检查
|
|
139
|
+
pnpm lint
|
|
140
|
+
|
|
141
|
+
# Docker E2E（可选）
|
|
142
|
+
pnpm test:e2e
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
沙盒开发脚本（不污染真实 HOME）：
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
bash scripts/dev-sandbox.sh
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## 环境变量
|
|
154
|
+
|
|
155
|
+
| 变量 | 用途 |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `ZHUGE_HOME` | 覆盖 HOME 用于工具路径定位（便于测试沙盒） |
|
|
158
|
+
| `ZHUGE_CI` | 设为 `true` 时启用 CI 模式（等价无人值守） |
|
|
159
|
+
| `CI` | 设为 `true` 时同样启用 CI 模式 |
|
|
160
|
+
|
|
161
|
+
---
|
|
162
|
+
|
|
163
|
+
## 当前边界与说明
|
|
164
|
+
|
|
165
|
+
- 当前内置配置目标为 Claude Code（`~/.claude`）
|
|
166
|
+
- CCG 适配器安装是交互式流程
|
|
167
|
+
- `zhuge init` 要求在 git 仓库内执行
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## License
|
|
172
|
+
|
|
173
|
+
MIT
|