jarvis-agent-factory 3.47.2 → 3.47.4

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.
Files changed (5) hide show
  1. package/README.md +1 -1
  2. package/dist/package.json +1 -1
  3. package/dist/src/templates/platforms/claude/commands/publish.md +209 -78
  4. package/dist/src/templates/platforms/claude/commands/sync.md +99 -52
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,7 @@
1
1
  # Jarvis Agent Factory · 贾维斯智能体工厂
2
2
 
3
3
  [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
4
- [![Version](https://img.shields.io/badge/version-v3.47.2-green)](https://github.com/Wjl1224734792/Jarvis-Agent-Factory/releases)
4
+ [![Version](https://img.shields.io/badge/version-v3.47.4-green)](https://github.com/Wjl1224734792/Jarvis-Agent-Factory/releases)
5
5
  [![npm](https://img.shields.io/npm/v/jarvis-agent-factory)](https://www.npmjs.com/package/jarvis-agent-factory)
6
6
  [![Visual Primitives MCP](https://img.shields.io/badge/DeepSeek-Visual%20Primitives%20MCP-purple)](https://github.com/Wjl1224734792/visual-primitives-mcp)
7
7
  <br>💡 **纯文本模型（如 DeepSeek）主力用户** → 搭配 [Visual Primitives MCP](https://github.com/Wjl1224734792/visual-primitives-mcp) 获得视觉理解能力
package/dist/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jarvis-agent-factory",
3
- "version": "3.47.2",
3
+ "version": "3.47.4",
4
4
  "description": "Jarvis Agent Factory CLI — Claude Code 多智能体 AI 编程助手配置安装器 | Multi-agent AI coding assistant config installer for Claude Code",
5
5
  "keywords": [
6
6
  "jarvis",
package/dist/src/templates/platforms/claude/commands/publish.md CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
- description: 一键发布——质量门检查→测试→版本bump→commit→push→tag→PR→merge→release
2
+ description: 一键发布——环境检测→质量门→测试→版本bump→commit→push→PR→合并→tag→发布
3
3
  argument-hint: [版本类型：patch|minor|major，默认patch]
4
- version: "3.46.3"
4
+ version: "3.47.2"
5
5
  updated: "2026-05-14"
6
6
  ---
7
7
 
@@ -9,115 +9,237 @@ updated: "2026-05-14"
9
9
 
10
10
  立即执行以下初始化步骤：
11
11
 
12
- ## 步骤 0：加载技能 + 前置检查
12
+ ## 步骤 0：加载技能 + 环境检测
13
13
 
14
14
  ```
15
15
  Skill("code-quality-gate")
16
16
  Skill("git-workflow-and-versioning")
17
17
  ```
18
18
 
19
- **前置检查（不可绕过）**：
19
+ ### 0.1 检测默认分支
20
20
 
21
- 1. 检查当前分支：
22
- - 必须在 `dev` 分支上。若不在 `dev`，报告当前分支并提示用户先切换到 `dev`。
23
- - ```bash
24
- git branch --show-current
25
- ```
21
+ ```bash
22
+ git remote show origin | grep "HEAD branch" | awk '{print $NF}'
23
+ ```
24
+
25
+ 默认分支通常为 `main` 或 `master`。记作 `<DEFAULT>`。
26
+
27
+ 若 `git remote show origin` 失败（无远程仓库），报告用户先配置远程仓库。
28
+
29
+ ### 0.2 检测工作分支
30
+
31
+ ```bash
32
+ git branch --show-current
33
+ ```
34
+
35
+ 当前分支记作 `<CURRENT>`。
36
+
37
+ - **若 `<CURRENT>` != `<DEFAULT>`**：将 `<CURRENT>` 作为工作分支使用，记作 `<WORK>`。
38
+ - **若 `<CURRENT>` == `<DEFAULT>`**：提示用户确认工作分支名称（建议用 `dev`），然后执行：
39
+ ```bash
40
+ git checkout -b dev
41
+ ```
42
+ 若 `dev` 已存在（本地或远程），改为 `git checkout dev && git pull origin dev`。
43
+ 若用户指定了其他名称，使用用户指定的名称。记作 `<WORK>`。
44
+
45
+ ### 0.3 检测包管理器
46
+
47
+ 按优先级检测锁文件，优先使用已有锁文件的包管理器：
48
+
49
+ | 锁文件 | 包管理器 | 运行脚本命令前缀 |
50
+ |--------|---------|-----------------|
51
+ | `package-lock.json` | npm | `npm run` |
52
+ | `yarn.lock` | yarn | `yarn` |
53
+ | `pnpm-lock.yaml` | pnpm | `pnpm` |
54
+
55
+ 若无任何锁文件，默认使用 `npm`。对应的前缀记作 `<PKG>`。以下各步骤中的脚本调用统一为 `<PKG> <script>` 格式。审计命令为 `<PKG> audit`。
26
56
 
27
- 2. 检查工作区状态：
28
- - 工作区必须干净（无未提交变更）。
29
- - ```bash
30
- git status --porcelain
31
- ```
32
- - 若有未提交变更，列出变更文件并提示用户先处理（提交或暂存）。
57
+ ### 0.4 检测版本文件
58
+
59
+ 按优先级检测版本声明文件：
60
+
61
+ | 文件 | 项目类型 | 版本字段 |
62
+ |------|---------|---------|
63
+ | `package.json` | JS/TS | `version` |
64
+ | `pyproject.toml` | Python | `[project] version` 或 `[tool.poetry] version` |
65
+ | `Cargo.toml` | Rust | `[package] version` |
66
+
67
+ 若多个文件同时存在，优先使用 `package.json`。检测到的文件记作 `<VERSION_FILE>`，当前版本记作 `<CUR_VER>`。
68
+
69
+ ### 0.5 检测测试命令
70
+
71
+ ```bash
72
+ # 若 package.json 存在且含 test 脚本
73
+ <PKG> test -- --listTests 2>/dev/null; echo "found"
74
+ ```
75
+
76
+ 若检测到 `scripts.test` 则使用 `<PKG> test`，否则按以下优先级查找：
77
+ - `Makefile` 中的 `test` 目标
78
+ - `pytest`（Python）
79
+ - `cargo test`（Rust）
80
+ - `go test ./...`（Go）
81
+
82
+ 若无法自动检测，提示用户指定测试命令。
83
+
84
+ ### 0.6 汇总检测结果
85
+
86
+ 向用户展示并确认：
87
+
88
+ ```
89
+ === 环境检测结果 ===
90
+ 默认分支: <DEFAULT>
91
+ 工作分支: <WORK>
92
+ 包管理器: <npm|yarn|pnpm>
93
+ 版本文件: <VERSION_FILE>
94
+ 当前版本: <CUR_VER>
95
+ 测试命令: <TEST_CMD>
96
+ ===================
97
+ ```
98
+
99
+ ---
100
+
101
+ ## 步骤 1：前置检查（不可绕过）
102
+
103
+ 1. **工作区干净**：
104
+ ```bash
105
+ git status --porcelain
106
+ ```
107
+ 若有未提交变更，列出文件并提示用户处理。
108
+
109
+ 2. **确认分支**：当前分支必须为 `<WORK>`（已由步骤 0.2 保证）。
110
+
111
+ 3. **与远程同步**：
112
+ ```bash
113
+ git fetch origin
114
+ git pull origin <WORK> --rebase
115
+ ```
33
116
 
34
117
  **前置条件不满足 → 立即停止，向用户报告具体问题和处理建议。**
35
118
 
36
119
  ---
37
120
 
38
- ## 步骤 1：质量门（不可绕过）
121
+ ## 步骤 2：质量门（不可绕过）
122
+
123
+ 加载 `Skill("code-quality-gate")` 后执行四项检查。工具按项目特征自适应选择：
39
124
 
40
- 加载 `Skill("code-quality-gate")` 后执行四项检查：
125
+ ### 2.1 Lint
41
126
 
127
+ | 项目特征 | 检测方式 | 命令（优先脚本，回退直接调用） |
128
+ |---------|---------|------------------------------|
129
+ | `eslint` 配置存在 | `.eslintrc.*` / `eslint.config.*` | `<PKG> lint` 或 `npx eslint .` |
130
+ | `oxlint` 配置存在 | `oxlintrc.*` | `<PKG> lint` 或 `npx oxlint` |
131
+ | `ruff` 配置存在 | `ruff.toml` / `pyproject.toml[tool.ruff]` | `ruff check .` |
132
+ | `golangci-lint` 配置 | `.golangci.yml` | `golangci-lint run` |
133
+ | 无已知配置 | — | 跳过（标记 N/A） |
134
+
135
+ ### 2.2 类型检查
136
+
137
+ | 项目特征 | 配置 | 命令 |
138
+ |---------|------|------|
139
+ | TypeScript | `tsconfig.json` | `<PKG> type-check` 或 `npx tsc --noEmit` |
140
+ | Python + mypy | `mypy.ini` / `pyproject.toml[tool.mypy]` | `mypy .` |
141
+ | 无类型检查配置 | — | 跳过（标记 N/A） |
142
+
143
+ ### 2.3 构建
144
+
145
+ ```bash
146
+ <PKG> build
42
147
  ```
43
- ┌─────────────────────────────────────────────┐
44
- │ 质量门检查（全部通过才继续） │
45
- │ │
46
- │ 1. Lint（eslint / ruff / golangci-lint） │
47
- │ 2. Type-check（tsc --noEmit） │
48
- │ 3. Build（npm run build） │
49
- │ 4. Deps Audit（npm audit） │
50
- └─────────────────────────────────────────────┘
148
+
149
+ 若无 `build` 脚本，尝试项目级构建命令（如 `go build ./...`），无则跳过（标记 N/A）。
150
+
151
+ ### 2.4 依赖审计
152
+
153
+ ```bash
154
+ <PKG> audit
51
155
  ```
52
156
 
53
- **全部通过 → 进入步骤 2**
157
+ 审计命令不可用时跳过（标记 N/A，注明该包管理器不提供审计功能）。
158
+
159
+ ```
160
+ ┌─────────────────────────────────────────────────┐
161
+ │ 质量门检查（全部通过才继续） │
162
+ │ │
163
+ │ 1. Lint（自适应: eslint/ruff/golangci-lint/...）│
164
+ │ 2. Type-check（自适应: tsc/mypy/...） │
165
+ │ 3. Build（自适应） │
166
+ │ 4. Deps Audit（自适应: npm auditor/...） │
167
+ └─────────────────────────────────────────────────┘
168
+ ```
169
+
170
+ **全部通过 → 进入步骤 3**
54
171
 
55
172
  **任意项失败**：
56
173
  1. 输出失败项的详细错误信息
57
174
  2. **立即停止**，不继续后续步骤
58
175
  3. 向用户报告：哪个检查失败、具体错误、修复建议
59
- 4. 用户修复后重新执行 `/publish` 从步骤 1 开始
176
+ 4. 用户修复后重新执行 `/publish` 从步骤 2 开始
60
177
 
61
178
  ---
62
179
 
63
- ## 步骤 2：测试（不可绕过）
180
+ ## 步骤 3：测试（不可绕过）
64
181
 
65
- 运行测试套件：
182
+ 使用步骤 0.5 检测到的测试命令：
66
183
 
67
184
  ```bash
68
- npm test
185
+ <TEST_CMD>
69
186
  ```
70
187
 
71
- **全部通过 → 进入步骤 3**
188
+ **全部通过 → 进入步骤 4**
72
189
 
73
190
  **测试失败**：
74
191
  1. 输出失败的测试名称和错误详情
75
192
  2. **立即停止**，不继续后续步骤
76
193
  3. 向用户报告：失败测试数量、失败原因摘要
77
- 4. 用户修复后重新执行 `/publish` 从步骤 1 开始
194
+ 4. 用户修复后重新执行 `/publish` 从步骤 2 开始
78
195
 
79
196
  ---
80
197
 
81
- ## 步骤 3：版本递增
198
+ ## 步骤 4：版本递增
82
199
 
83
200
  加载 `Skill("git-workflow-and-versioning")` 执行版本管理。
84
201
 
85
- 参数说明：
86
- - 用户可指定版本类型：`patch`（默认）、`minor`、`major`
87
- - 未指定则默认 `patch` 递增
202
+ 参数：用户可指定 `patch`（默认）、`minor`、`major`。未指定则默认 `patch`。
88
203
 
89
- 1. 读取当前 `package.json` 中的 `version` 字段
90
- 2. 按指定类型递增版本号：
204
+ 1. 从 `<VERSION_FILE>` 读取当前版本号 `<CUR_VER>`
205
+ 2. 按类型递增：
91
206
  - `patch`：X.Y.Z → X.Y.(Z+1)
92
207
  - `minor`：X.Y.Z → X.(Y+1).0
93
208
  - `major`：X.Y.Z → (X+1).0.0
94
- 3. 更新 `package.json` 中的 `version` 字段为新版本号
95
- 4. 输出：`版本递增：v<旧版本> → v<新版本>（类型：<patch|minor|major>）`
209
+ 3. 更新 `<VERSION_FILE>` 中的版本字段为新版本号 `<NEW_VER>`
210
+ - `package.json`：修改 `version` 字段
211
+ - `pyproject.toml`：修改 `[project]` 下 `version`，或 `[tool.poetry]` 下 `version`
212
+ - `Cargo.toml`：修改 `[package]` 下 `version`
213
+ 4. 若项目使用 Git tag 标注版本（非 npm 包），同时更新版本文件中的 git tag 引用
214
+
215
+ 输出：`版本递增：v<CUR_VER> → v<NEW_VER>（类型：<patch|minor|major>，文件：<VERSION_FILE>）`
96
216
 
97
217
  ---
98
218
 
99
- ## 步骤 4：提交并推送
219
+ ## 步骤 5：提交并推送
100
220
 
101
221
  ```bash
102
- git add package.json
103
- git commit -m "chore: bump version to v<新版本>"
104
- git push origin dev
222
+ git add <VERSION_FILE>
223
+ git commit -m "chore: bump version to v<NEW_VER>"
224
+ git push origin <WORK>
105
225
  ```
106
226
 
227
+ > 若版本文件关联了锁文件（如 `package.json` 关联 `package-lock.json`），一并提交锁文件变更。
228
+
107
229
  推送失败时报告错误并停止。
108
230
 
109
231
  ---
110
232
 
111
- ## 步骤 5：创建 PR（dev → main）
233
+ ## 步骤 6：创建 PR（工作分支 → 默认分支）
112
234
 
113
235
  ```bash
114
236
  gh pr create \
115
- --base main \
116
- --head dev \
117
- --title "Release v<新版本>" \
237
+ --base <DEFAULT> \
238
+ --head <WORK> \
239
+ --title "Release v<NEW_VER>" \
118
240
  --body "## 发布内容
119
241
 
120
- - 版本：v<新版本>
242
+ - 版本：v<NEW_VER>
121
243
  - 类型：<patch|minor|major>
122
244
 
123
245
  ## 检查清单
@@ -132,7 +254,7 @@ PR 创建失败时报告错误并停止。
132
254
 
133
255
  ---
134
256
 
135
- ## 步骤 6：合并 PR
257
+ ## 步骤 7：合并 PR
136
258
 
137
259
  ```bash
138
260
  gh pr merge --merge
@@ -144,31 +266,31 @@ gh pr merge --merge
144
266
 
145
267
  ---
146
268
 
147
- ## 步骤 7：在 main 上创建并推送 tag
269
+ ## 步骤 8：在默认分支上创建并推送 tag
148
270
 
149
- **仅在 PR 合并成功后**，在 `main` 分支上创建 tag：
271
+ **仅在 PR 合并成功后**，在 `<DEFAULT>` 上创建 tag：
150
272
 
151
273
  ```bash
152
- # 1. 切换到 main 并拉取最新
153
- git checkout main && git pull origin main
274
+ # 1. 切换到默认分支并拉取最新
275
+ git checkout <DEFAULT> && git pull origin <DEFAULT>
154
276
 
155
- # 2. 在 main 上创建 tag（只在这里，不在 dev 上打 tag）
156
- git tag -a v<新版本> -m "Release v<新版本>"
277
+ # 2. 在默认分支上创建 tag（只在这里，不在工作分支上打 tag）
278
+ git tag -a v<NEW_VER> -m "Release v<NEW_VER>"
157
279
 
158
- # 3. 推送 tag（唯一一次触发 release workflow）
159
- git push origin v<新版本>
280
+ # 3. 推送 tag
281
+ git push origin v<NEW_VER>
160
282
  ```
161
283
 
162
- > **关键**：tag 只在 `main` 上创建，确保 release workflow 只触发一次。不要在 `dev` 上打 tag。
284
+ > **关键**：tag 只在默认分支上创建，确保 release workflow 只触发一次。不要在工作分支上打 tag。
163
285
 
164
286
  推送失败时报告错误并停止。
165
287
 
166
288
  ---
167
289
 
168
- ## 步骤 8：切回 dev 并报告结果
290
+ ## 步骤 9：切回工作分支并报告结果
169
291
 
170
292
  ```bash
171
- git checkout dev
293
+ git checkout <WORK>
172
294
  ```
173
295
 
174
296
  输出发布完成报告：
@@ -176,14 +298,18 @@ git checkout dev
176
298
  ```
177
299
  ## 发布完成报告
178
300
 
179
- - 版本：v<旧版本> → v<新版本>
301
+ - 版本：v<CUR_VER> → v<NEW_VER>
180
302
  - 类型：<patch|minor|major>
181
- - 质量门：✅ 通过
182
- - 测试：✅ 通过
303
+ - 包管理器：<npm|yarn|pnpm>
304
+ - 版本文件：<VERSION_FILE>
305
+ - 默认分支：<DEFAULT>
306
+ - 工作分支：<WORK>
307
+ - 质量门：通过
308
+ - 测试：通过
183
309
  - Commit：<commit hash>
184
- - Tag：v<新版本>（指向 main）
310
+ - Tag：v<NEW_VER>（指向 <DEFAULT>）
185
311
  - PR：#<PR number>（已合并）
186
- - 当前分支：dev
312
+ - 当前分支：<WORK>
187
313
  ```
188
314
 
189
315
  ---
@@ -191,31 +317,36 @@ git checkout dev
191
317
  ## 流程总览
192
318
 
193
319
  ```
194
- 步骤 0: 前置检查（dev 分支 + 工作区干净）
320
+ 步骤 0: 环境检测（分支名 + 包管理器 + 版本文件 + 测试命令）
195
321
  ↓
196
- 步骤 1: 质量门（Lint + Type-check + Build + Audit）
322
+ 步骤 1: 前置检查（工作区干净 + 正确分支 + 拉取最新）
323
+ ↓
324
+ 步骤 2: 质量门（Lint + Type-check + Build + Audit）[自适应工具]
197
325
  ↓ 全部通过
198
- 步骤 2: 测试（npm test）
326
+ 步骤 3: 测试（自适应测试命令）
199
327
  ↓ 全部通过
200
- 步骤 3: 版本递增（patch/minor/major）
328
+ 步骤 4: 版本递增（patch/minor/major，自适应版本文件）
201
329
  ↓
202
- 步骤 4: 提交并推送（commit package.json + push dev）
330
+ 步骤 5: 提交并推送（commit VERSION_FILE + push 工作分支）
203
331
  ↓
204
- 步骤 5: 创建 PR（dev → main）
332
+ 步骤 6: 创建 PR（工作分支 → 默认分支）
205
333
  ↓
206
- 步骤 6: 合并 PR
334
+ 步骤 7: 合并 PR
207
335
  ↓
208
- 步骤 7: 在 main 上创建并推送 tag（触发 release workflow）
336
+ 步骤 8: 在默认分支上创建并推送 tag
209
337
  ↓
210
- 步骤 8: 切回 dev + 报告完成
338
+ 步骤 9: 切回工作分支 + 报告完成
211
339
  ```
212
340
 
341
+ ---
342
+
213
343
  ## 红线
214
344
 
215
- - 不在 `dev` 分支上发布（直接从其他分支发布会导致版本混乱）
345
+ - 不确认分支关系就发布（可能导致版本混乱）
216
346
  - 工作区不干净时发布（未提交变更混入发布）
217
347
  - 质量门失败仍继续（带问题的代码不能发布）
218
348
  - 测试失败仍继续（回归未发现的发布是事故）
219
349
  - 手动修改版本号而不使用版本递增流程（破坏版本号一致性）
220
- - tag 不指向 `main` 分支（tag 应指向正式发布分支，只在 main 上打 tag）
221
- - 使用 `--squash` 合并 PR（丢失 dev 分支的提交历史细节）
350
+ - tag 不指向默认分支（tag 应指向正式发布分支，确保 release workflow 正确触发）
351
+ - 使用 `--squash` 合并 PR（丢失工作分支的提交历史细节）
352
+ - 硬编码包管理器命令而不使用环境检测结果（导致非 npm 项目命令无效）
package/dist/src/templates/platforms/claude/commands/sync.md CHANGED
@@ -1,86 +1,133 @@
1
1
  ---
2
- description: 同步项目文件——更新指令/技能/文档到最新版，清理过时缓存
3
- argument-hint: [--dry-run 预览模式]
4
- version: "3.46.3"
2
+ description: 同步项目文档——检查并更新核心文档使其与代码一致，清理过时文件
3
+ argument-hint: [--dry-run 预览模式] [--no-clean 跳过清理]
4
+ version: "3.47.3"
5
5
  updated: "2026-05-14"
6
6
  ---
7
7
 
8
- # 同步项目文件
8
+ # 同步项目文档
9
9
 
10
- 立即执行以下同步流程：
10
+ 检查项目核心文档是否与代码现状一致，修复不一致处，清理过时文件。
11
11
 
12
- ## 1. 同步指令
12
+ ## 步骤 0：扫描项目现状
13
13
 
14
- 从模板 `src/templates/platforms/claude/commands/` 同步最新命令到 `.claude/commands/`：
14
+ 首先了解项目当前实际情况（用于后续对比文档）：
15
15
 
16
- - 扫描模板目录下所有 `.md` 文件
17
- - 按文件名匹配目标目录，若模板比目标新则覆盖
18
- - 目标目录不存在的文件直接创建
19
- - 跳过 `jarvis-lite.md`、`jarvis.md` 等由引擎动态控制的命令文件（以引擎内置版本为准）
16
+ 1. **技术栈**：读取 `package.json`（scripts、dependencies）、`tsconfig.json`、框架配置文件
17
+ 2. **项目结构**：列出主要源码目录（`src/`、`web/`、`app/` 等）和关键配置文件
18
+ 3. **命令清单**：扫描 `.claude/commands/` 下所有 `.md` 文件，提取命令名和描述
19
+ 4. **Git 信息**：获取当前分支、最近提交、远程地址
20
20
 
21
- ## 2. 同步技能
21
+ ---
22
+
23
+ ## 步骤 1：检查 CLAUDE.md
24
+
25
+ **CLAUDE.md** 是项目的 AI 指令文件。对比以下方面：
26
+
27
+ | 检查项 | 方法 |
28
+ |--------|------|
29
+ | 项目名称和简介 | 与 `package.json` 的 name/description 对比 |
30
+ | 常用命令 | 与 `package.json` scripts 对比 |
31
+ | 目录结构 | 与实际源码目录对比 |
32
+ | 技术栈 | 与 dependencies/devDependencies 对比 |
33
+ | 架构说明 | 与实际模块结构对比 |
34
+
35
+ **不一致时**：报告具体差异，修复 CLAUDE.md 中过时的内容。
36
+
37
+ **CLAUDE.md 不存在时**：基于项目现状自动生成初始版本。
38
+
39
+ ---
40
+
41
+ ## 步骤 2：检查 AGENTS.md
42
+
43
+ **AGENTS.md** 是 agent 协作约定。对比：
22
44
 
23
- 从模板 `src/templates/platforms/claude/skills/` 同步最新技能到 `.claude/skills/`：
45
+ | 检查项 | 方法 |
46
+ |--------|------|
47
+ | Agent 列表 | 与 `.claude/agents/` 目录对比 |
48
+ | 命令引用 | 与 `.claude/commands/` 目录对比 |
49
+ | 约束/规范 | 与 `CLAUDE.md` 中的约束一致 |
24
50
 
25
- - 扫描模板 `skills/` 下的子目录，每个子目录是一个技能
26
- - 目标 `.claude/skills/` 不存在则创建
27
- - 按目录比对，模板中的新增/更新技能同步到目标
51
+ ---
28
52
 
29
- ## 3. 同步核心文档
53
+ ## 步骤 3：检查 README.md
30
54
 
31
- 更新以下核心文档，确保与代码变更一致：
55
+ | 检查项 | 方法 |
56
+ |--------|------|
57
+ | 安装命令 | 从 `package.json` 推断正确的安装方式 |
58
+ | 使用说明 | 与 CLI 入口文件对比 |
59
+ | 版本徽章 | 与当前版本号一致 |
32
60
 
33
- - `CLAUDE.md` — 检查命令列表、路径引用、版本号是否与当前代码匹配
34
- - `AGENTS.md` — 检查约束项、流程描述、技术栈是否反映最新架构
35
- - `README.md` — 检查安装命令、使用方式、配置说明是否有效
36
- - `CHANGELOG.md` — 检查最新版本条目是否包含所有近期变更
61
+ **README.md 是面向人类用户的门面文档**，修复时只修正**事实性错误**（错误命令、过时版本），不改变写作风格和叙述结构。
37
62
 
38
- 比较策略：读取文件内容，对比关键字段（命令名、路径、版本号、模块列表），发现不一致则报告并修复。
63
+ ---
39
64
 
40
- ## 4. 清理过时文件
65
+ ## 步骤 4：检查 CHANGELOG.md
41
66
 
42
- 扫描 `.claude/` 目录下不再需要的缓存和临时文件：
67
+ | 检查项 | 方法 |
68
+ |--------|------|
69
+ | 版本条目 | 当前版本号应有对应条目 |
70
+ | 近期变更 | 与 `git log` 对比，确保最近变更已记录 |
43
71
 
44
- - 检查 `.claude/commands/` 中存在但模板目录已删除的文件，标记为过时
45
- - 检查 `.claude/skills/` 中存在但模板目录已删除的技能目录，标记为过时
46
- - 扫描 `.claude/` 下的 `.cache`、`.tmp`、`*.log` 等临时文件并清理
72
+ **CHANGELOG.md 不存在时**：不自动创建（CHANGELOG 应由开发者手动维护）。
47
73
 
48
- ### 跳过目录
74
+ ---
49
75
 
50
- 以下目录不做任何同步或清理操作：
76
+ ## 步骤 5：清理过时文件
51
77
 
52
- - `dist/` — 构建产物
53
- - `docs/YYYY-MM-DD/` — 日期驱动文档
54
- - `node_modules/` — 依赖
55
- - `.git/` — 版本控制
78
+ 扫描项目根目录和 `.claude/` 目录，标记并清理过时文件：
56
79
 
57
- ## 同步策略
80
+ **可清理的类型**：
81
+ - `.claude/` 下不在模板中的孤立 `.md` 文件（用户确认后删除）
82
+ - 空目录
83
+ - IDE/编辑器临时文件（`.DS_Store`、`Thumbs.db`）
84
+ - 日志文件（`*.log`）超过 30 天
58
85
 
59
- - **默认行为**：执行全部同步步骤（指令 + 技能 + 文档 + 清理）
60
- - **--dry-run 模式**：仅预览变更，列出将新增/更新/删除的文件，不实际修改任何文件
61
- - **增量同步**：仅更新有变化的文件，时间戳或内容比对后决定是否覆盖
62
- - **保守删除**：清理步骤仅删除明确标记为过时的模板文件，不对未知文件做自动删除
86
+ **绝不可触碰**：
87
+ - `dist/`、`build/`、`.next/` — 构建产物
88
+ - `node_modules/`、`.git/` — 依赖和版本控制
89
+ - `docs/YYYY-MM-DD/` — 日期驱动的流水线产物
90
+ - 任何 `.env` 文件
91
+ - 用户明确标记为 keep 的文件
63
92
 
64
- ## 同步报告
93
+ **清理策略**：列出待清理清单 → 用户确认 → 执行。`--dry-run` 只列出不执行。
94
+
95
+ ---
65
96
 
66
- 完成后输出结构化报告：
97
+ ## 步骤 6：同步报告
67
98
 
68
99
  ```
69
- === 同步报告 ===
100
+ === 文档同步报告 ===
70
101
 
71
- 【指令】新增: N 更新: N 删除: N 跳过: N
72
- 【技能】新增: N 更新: N 删除: N 跳过: N
73
- 【文档】已检查: CLAUDE.md AGENTS.md README.md CHANGELOG.md
74
- - 更新项: xxx（描述不一致处及修复内容）
75
- - 一致项: xxx（确认无需修改）
76
- 【清理】已清理: N 个文件/目录（列出路径）
102
+ 【CLAUDE.md】
103
+ ✓ 一致 / ~ 已修复 N 处不一致 / + 已创建
104
+ 修复项: （列出具体修改）
77
105
 
78
- 总计变更: N 预览模式: 是/否
106
+ 【AGENTS.md】
107
+ ✓ 一致 / ~ 已修复 N 处不一致
108
+ 修复项: （列出具体修改）
109
+
110
+ 【README.md】
111
+ ✓ 一致 / ~ 已修复 N 处事实性错误
112
+ 修复项: （列出具体修改）
113
+
114
+ 【CHANGELOG.md】
115
+ ✓ 已记录最新版本 / ⚠ 缺少 vX.Y.Z 条目
116
+
117
+ 【清理】
118
+ 待清理: N 个文件/目录
119
+ 已清理: N 个
120
+ 预览模式: 是 / 否
79
121
  ```
80
122
 
123
+ ---
124
+
81
125
  ## 运行约束
82
126
 
83
127
  - 所有文件操作使用绝对路径
84
- - 文档对比需实际读取文件内容，禁止仅凭猜测判断
85
- - 模板过时但目标文件存在新内容时不强制覆盖（以目标为准）
86
- - `--dry-run` 模式下不执行任何写操作
128
+ - **文档对比必须实际读取文件内容**，不可凭记忆判断
129
+ - `--dry-run` 模式不执行任何写入或删除
130
+ - `--no-clean` 模式跳过清理步骤
131
+ - 对 README.md 只修正事实性错误，不改变写作风格
132
+ - 清理步骤需用户确认后才执行实际删除
133
+ - 路径使用 `/`（Unix 风格，跨平台）
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "jarvis-agent-factory",
3
- "version": "3.47.2",
3
+ "version": "3.47.4",
4
4
  "description": "Jarvis Agent Factory CLI — Claude Code 多智能体 AI 编程助手配置安装器 | Multi-agent AI coding assistant config installer for Claude Code",
5
5
  "keywords": [
6
6
  "jarvis",