@awiki/cli 0.0.1-beta.2

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 (119) hide show
  1. package/.github/workflows/release.yml +44 -0
  2. package/.goreleaser.yml +44 -0
  3. package/AGENTS.md +60 -0
  4. package/CLAUDE.md +192 -0
  5. package/README.md +2 -0
  6. package/docs/architecture/awiki-command-v2.md +955 -0
  7. package/docs/architecture/awiki-skill-architecture.md +475 -0
  8. package/docs/architecture/awiki-v2-architecture.md +1063 -0
  9. package/docs/architecture//345/217/202/350/200/203/346/226/207/346/241/243/cli-init.md +1008 -0
  10. package/docs/architecture//345/217/202/350/200/203/346/226/207/346/241/243/output-format.md +407 -0
  11. package/docs/architecture//345/217/202/350/200/203/346/226/207/346/241/243/overall-init.md +741 -0
  12. package/docs/harness/review-spec.md +474 -0
  13. package/docs/installation.md +372 -0
  14. package/docs/plan/awiki-v2-implementation-plan.md +903 -0
  15. package/docs/plan/phase-0/adr-index.md +56 -0
  16. package/docs/plan/phase-0/audit-findings.md +251 -0
  17. package/docs/plan/phase-0/capability-mapping.md +108 -0
  18. package/docs/plan/phase-0/implementation-constraints.md +363 -0
  19. package/docs/publish.md +169 -0
  20. package/go.mod +29 -0
  21. package/go.sum +73 -0
  22. package/internal/anpsdk/registry.go +63 -0
  23. package/internal/authsdk/session.go +351 -0
  24. package/internal/buildinfo/buildinfo.go +34 -0
  25. package/internal/cli/app.go +136 -0
  26. package/internal/cli/app_test.go +88 -0
  27. package/internal/cli/debug.go +104 -0
  28. package/internal/cli/group.go +263 -0
  29. package/internal/cli/id.go +473 -0
  30. package/internal/cli/init.go +134 -0
  31. package/internal/cli/msg.go +228 -0
  32. package/internal/cli/page.go +267 -0
  33. package/internal/cli/root.go +499 -0
  34. package/internal/cli/runtime.go +232 -0
  35. package/internal/cli/upgrade.go +60 -0
  36. package/internal/cmdmeta/catalog.go +203 -0
  37. package/internal/cmdmeta/catalog_test.go +21 -0
  38. package/internal/config/config.go +399 -0
  39. package/internal/config/config_test.go +104 -0
  40. package/internal/config/write.go +37 -0
  41. package/internal/content/service.go +314 -0
  42. package/internal/content/service_test.go +165 -0
  43. package/internal/content/types.go +44 -0
  44. package/internal/docs/topics.go +110 -0
  45. package/internal/doctor/doctor.go +306 -0
  46. package/internal/identity/client.go +267 -0
  47. package/internal/identity/did.go +85 -0
  48. package/internal/identity/did_test.go +50 -0
  49. package/internal/identity/layout.go +206 -0
  50. package/internal/identity/legacy.go +378 -0
  51. package/internal/identity/public.go +70 -0
  52. package/internal/identity/public_test.go +73 -0
  53. package/internal/identity/readiness.go +74 -0
  54. package/internal/identity/service.go +826 -0
  55. package/internal/identity/store.go +385 -0
  56. package/internal/identity/store_test.go +180 -0
  57. package/internal/identity/types.go +204 -0
  58. package/internal/message/auth.go +167 -0
  59. package/internal/message/group_service.go +838 -0
  60. package/internal/message/group_wire.go +350 -0
  61. package/internal/message/group_wire_test.go +67 -0
  62. package/internal/message/helpers.go +61 -0
  63. package/internal/message/http_client.go +334 -0
  64. package/internal/message/proof.go +156 -0
  65. package/internal/message/proof_test.go +61 -0
  66. package/internal/message/service.go +696 -0
  67. package/internal/message/service_test.go +97 -0
  68. package/internal/message/types.go +155 -0
  69. package/internal/message/wire.go +100 -0
  70. package/internal/message/wire_test.go +49 -0
  71. package/internal/message/ws_proxy_client.go +151 -0
  72. package/internal/output/output.go +350 -0
  73. package/internal/output/output_test.go +48 -0
  74. package/internal/runtime/config.go +117 -0
  75. package/internal/runtime/config_test.go +46 -0
  76. package/internal/runtime/listener/files.go +65 -0
  77. package/internal/runtime/listener/manager.go +142 -0
  78. package/internal/runtime/listener/server.go +983 -0
  79. package/internal/runtime/listener/server_test.go +319 -0
  80. package/internal/runtime/listener/sysproc_unix.go +17 -0
  81. package/internal/runtime/listener/sysproc_windows.go +13 -0
  82. package/internal/runtime/listener/types.go +21 -0
  83. package/internal/runtime/listener/wsclient.go +299 -0
  84. package/internal/runtime/listener/wsclient_test.go +41 -0
  85. package/internal/store/dao.go +632 -0
  86. package/internal/store/dao_test.go +87 -0
  87. package/internal/store/helpers.go +197 -0
  88. package/internal/store/import.go +499 -0
  89. package/internal/store/import_test.go +103 -0
  90. package/internal/store/open.go +71 -0
  91. package/internal/store/query.go +151 -0
  92. package/internal/store/schema.go +277 -0
  93. package/internal/store/schema_test.go +56 -0
  94. package/internal/store/types.go +177 -0
  95. package/internal/update/update.go +368 -0
  96. package/package.json +17 -0
  97. package/scripts/install.js +171 -0
  98. package/scripts/release/release-prerelease.sh +86 -0
  99. package/scripts/release/tag-release.sh +66 -0
  100. package/scripts/release/withdraw-release.sh +78 -0
  101. package/scripts/run.js +69 -0
  102. package/skills/README.md +32 -0
  103. package/skills/awiki-bundle/SKILL.md +76 -0
  104. package/skills/awiki-debug/SKILL.md +80 -0
  105. package/skills/awiki-group/SKILL.md +111 -0
  106. package/skills/awiki-id/SKILL.md +123 -0
  107. package/skills/awiki-msg/SKILL.md +131 -0
  108. package/skills/awiki-page/SKILL.md +93 -0
  109. package/skills/awiki-people/SKILL.md +66 -0
  110. package/skills/awiki-runtime/SKILL.md +137 -0
  111. package/skills/awiki-shared/SKILL.md +124 -0
  112. package/skills/awiki-workflow-discovery/SKILL.md +93 -0
  113. package/skills/awiki-workflow-onboarding/SKILL.md +119 -0
  114. package/skills/manifests/skills.yaml +260 -0
  115. package/skills/templates/bundle-skill-template.md +42 -0
  116. package/skills/templates/debug-skill-template.md +44 -0
  117. package/skills/templates/domain-skill-template.md +56 -0
  118. package/skills/templates/shared-skill-template.md +46 -0
  119. package/skills/templates/workflow-skill-template.md +46 -0
@@ -0,0 +1,363 @@
1
+ # Phase 0 实现约束表
2
+
3
+ **状态**:Frozen for implementation
4
+ **适用阶段**:Phase 1 及之后所有实现阶段
5
+ **优先级**:当本文与 `docs/architecture/*.md` 或 `docs/plan/awiki-v2-implementation-plan.md` 冲突时,以本文为准。
6
+ **最后更新**:2026-04-07
7
+
8
+ ---
9
+
10
+ ## 1. 适用范围与优先级
11
+
12
+ 本文是 Phase 0 的冻结产物,作用是把“实现时不能再摇摆”的决策固定下来,供后续编码、拆 Issue、验收使用。
13
+
14
+ 实现期优先级如下:
15
+
16
+ 1. `docs/plan/phase-0/implementation-constraints.md`
17
+ 2. `docs/plan/phase-0/audit-findings.md` 中的明确裁决
18
+ 3. `docs/plan/awiki-v2-implementation-plan.md`
19
+ 4. `docs/architecture/awiki-command-v2.md`
20
+ 5. `docs/architecture/awiki-v2-architecture.md`
21
+ 6. `docs/architecture/output-format.md`
22
+ 7. 服务 API 文档
23
+ 8. `../awiki-agent-id-message/`
24
+ 9. `../cli/`
25
+
26
+ ---
27
+
28
+ ## 2. 公共命令面冻结
29
+
30
+ ### 2.1 canonical 顶级命令
31
+
32
+ Phase 1 必须搭出的顶级命令骨架固定为:
33
+
34
+ ```text
35
+ awiki-cli status
36
+ awiki-cli docs
37
+ awiki-cli schema
38
+ awiki-cli doctor
39
+ awiki-cli version
40
+ awiki-cli completion
41
+ awiki-cli config
42
+ awiki-cli id
43
+ awiki-cli msg
44
+ awiki-cli group
45
+ awiki-cli runtime
46
+ awiki-cli people
47
+ awiki-cli page
48
+ awiki-cli debug
49
+ ```
50
+
51
+ ### 2.2 extension 命令策略
52
+
53
+ - `discovery` 视为保留扩展域,不阻塞 Phase 1 命令壳。
54
+ - 如果 Phase 1 需要最小化顶级命令树,可以暂不实现 `discovery`。
55
+
56
+ ### 2.3 群组命令归属冻结
57
+
58
+ - **canonical 公共域使用 `group` 顶级命令**。
59
+ - 群生命周期命令统一挂在 `group` 下:
60
+ - `group create`
61
+ - `group show`
62
+ - `group update`
63
+ - `group join`
64
+ - `group leave`
65
+ - `group kick`
66
+ - `group members`
67
+ - `group messages`
68
+ - `group code *`
69
+ - `msg send --group` 是唯一 canonical 群发消息入口。
70
+ - `msg group ...` 只视为历史草案写法,不作为 Phase 1 必做公共命令面;如果后续实现,只能作为兼容 alias,不得反向替代 `group ...`。
71
+
72
+ ### 2.4 raw/debug 命令归属冻结
73
+
74
+ - Phase 1 不暴露顶级 `api` 命令。
75
+ - raw RPC / DB inspection / schema cache 一律挂在 `debug` 域。
76
+ - 当前 canonical 路径:
77
+ - `debug raw rpc ...`
78
+ - `debug db query ...`
79
+ - `debug schema-cache`
80
+
81
+ ---
82
+
83
+ ## 3. 全局参数与输出协议冻结
84
+
85
+ ### 3.1 全局参数
86
+
87
+ 所有 Phase 1 公共命令统一支持以下全局参数:
88
+
89
+ | 参数 | 说明 |
90
+ |---|---|
91
+ | `--format` | 输出格式,canonical 全局格式参数 |
92
+ | `--jq` | 对 JSON 输出做 jq 过滤 |
93
+ | `--dry-run` | 只返回执行计划,不产生副作用 |
94
+ | `--identity` | 选择当前 identity |
95
+ | `--verbose` | 增强调试输出 |
96
+
97
+ 冻结规则:
98
+
99
+ - `--format` 是唯一 canonical 输出格式参数。
100
+ - `--identity` 是唯一 canonical 身份选择参数。
101
+ - 如因兼容需要保留 `--credential`,只能作为 deprecated alias,帮助文档中不作为首选写法。
102
+
103
+ ### 3.2 输出 envelope
104
+
105
+ Phase 1 的结构化输出必须遵循统一 envelope:
106
+
107
+ - success: `ok=true`
108
+ - error: `ok=false`
109
+ - 更新提示字段固定为:`_notice`
110
+ - `meta.format` 使用实际渲染格式
111
+ - `meta.identity` 在 identity 已解析时提供
112
+
113
+ ### 3.3 错误码与退出码
114
+
115
+ Phase 1 冻结以下错误码集合:
116
+
117
+ ```text
118
+ invalid_argument
119
+ identity_required
120
+ auth_required
121
+ permission_denied
122
+ not_found
123
+ conflict
124
+ network_error
125
+ transport_unavailable
126
+ secure_session_required
127
+ unsupported_mode
128
+ partial_failure
129
+ internal_error
130
+ ```
131
+
132
+ Phase 1 冻结以下退出码:
133
+
134
+ ```text
135
+ 0 success
136
+ 1 generic error
137
+ 2 invalid argument
138
+ 3 identity/auth missing
139
+ 4 permission denied
140
+ 5 not found
141
+ 6 partial failure
142
+ 7 confirmation required but not provided
143
+ ```
144
+
145
+ ---
146
+
147
+ ## 4. 术语与兼容字段冻结
148
+
149
+ ### 4.1 用户层术语
150
+
151
+ - 用户层术语固定使用 **identity**。
152
+ - CLI 帮助、文档、schema、doctor 输出优先使用 `identity`。
153
+
154
+ ### 4.2 兼容存储字段
155
+
156
+ 为了兼容 v1 数据与导入逻辑,Phase 1 先保留以下存储命名:
157
+
158
+ - `credential_name`
159
+ - `default_credential_name`
160
+
161
+ 冻结规则:
162
+
163
+ - 用户接口叫 `identity`
164
+ - 存储字段可继续叫 `credential_*`
165
+ - Go 内部类型可以把两者桥接,但导入/导出必须兼容 v1 现有字段名
166
+
167
+ ### 4.3 对外身份标识冻结
168
+
169
+ - **对外公共身份标识固定使用 `handle`。**
170
+ - `did` 仅允许在协议级定位、调试或跨服务引用确有必要时出现在公共结果中。
171
+ - `user_id` 固定为内部实现字段,只允许存在于:
172
+ - 本地 identity 存储
173
+ - SQLite 内部表
174
+ - 服务端 API 适配与内部映射
175
+ - `user_id` 不得出现在以下对外面向:
176
+ - CLI 参数
177
+ - help / schema / docs 示例
178
+ - `pretty` / `table` / `json` / `ndjson` 结构化输出
179
+ - 公共命令结果中的字段名或 `missing` 提示项
180
+
181
+ ### 4.4 本地数据隔离主键
182
+
183
+ - 本地快照隔离主键固定为:`owner_did`
184
+ - Phase 1~Phase 5 都不得把 `owner_did` 改成其他主隔离键
185
+
186
+ ---
187
+
188
+ ## 5. 路径、环境变量与迁移冻结
189
+
190
+ ### 5.1 v2 原生工作目录
191
+
192
+ v2 原生路径固定为单一工作目录根(概念上记为 `AWIKI_HOME`):
193
+
194
+ ```text
195
+ $AWIKI_HOME/
196
+ config.json # 运行期主配置
197
+ db/awiki-cli.db # SQLite 数据库
198
+ identities/ # 本地身份与密钥
199
+ logs/ # 运行日志
200
+ cache/ # 缓存数据
201
+ tmp/ # 临时文件 / runtime 状态
202
+ ```
203
+
204
+ 默认情况下:
205
+
206
+ - macOS / Linux:`$HOME/.awiki-cli`
207
+ - Windows:`%LOCALAPPDATA%\AwikiCli`
208
+
209
+ 实际解析工作目录根时,行为必须符合以下顺序:
210
+
211
+ 1. 若设置环境变量 `AWIKI_HOME`,本次运行优先使用该路径(高级/CI/测试用,不建议普通用户长期依赖);
212
+ 2. 否则使用默认根本身。
213
+
214
+ 实现约束:
215
+
216
+ - 所有运行期副作用产物(配置、数据库、凭证、日志、缓存、临时文件)必须落在 `AWIKI_HOME` 之下;
217
+ - 不再使用 XDG `~/.config` / `~/.local/share` / `~/.local/state` / `~/.cache` 四个独立根目录作为 v2 官方路径;
218
+ - 旧 XDG 路径只作为 v1 兼容导入的来源(见 5.3),不再作为 v2 默认写入位置。
219
+
220
+ ### 5.2 环境变量冻结
221
+
222
+ 环境变量前缀仍为 `AWIKI_*`,但公开集合大幅收敛,Frozen 约束为:
223
+
224
+ - 不再使用 `AVIKI_*` typo alias;
225
+ - 不再使用 `E2E_*` 作为运行期 fallback;
226
+ - 仅保留以下环境变量作为用户可见入口:
227
+
228
+ ```text
229
+ AWIKI_HOME
230
+ AWIKI_IDENTITY
231
+ AWIKI_RUNTIME_MODE
232
+ AWIKI_FORMAT
233
+ AWIKI_NO_COLOR
234
+ ```
235
+
236
+ 优先级固定为:
237
+
238
+ ```text
239
+ flag > env (AWIKI_*) > config.json > default
240
+ ```
241
+
242
+ 含义:
243
+
244
+ - `AWIKI_HOME`:临时覆盖工作目录根路径(高级/CI/测试用);
245
+ - `AWIKI_IDENTITY`:临时覆盖 `identity.active`;
246
+ - `AWIKI_RUNTIME_MODE`:临时覆盖 `runtime.mode`;
247
+ - `AWIKI_FORMAT`:临时覆盖 `output.format`;
248
+ - `AWIKI_NO_COLOR`:临时覆盖 `output.no_color`。
249
+
250
+ 实现约束:
251
+
252
+ - 不再提供 `AWIKI_CONFIG_DIR` / `AWIKI_DATA_DIR` / `AWIKI_STATE_DIR` / `AWIKI_CACHE_DIR` 等路径级 env;
253
+ - 不再提供 `AWIKI_USER_SERVICE_URL` / `AWIKI_MESSAGE_*` / `AWIKI_DID_DOMAIN` / `AWIKI_CA_BUNDLE` 等 URL/域名级 env;
254
+ - 任何新增长期配置项一律通过 `config.json` 管理,不再新增新的 `AWIKI_*` 环境变量。
255
+
256
+ ### 5.3 v1 路径兼容策略
257
+
258
+ 必须兼容检测以下旧路径,但 **默认不原地写入**:
259
+
260
+ ```text
261
+ ~/.openclaw/credentials/awiki-agent-id-message/
262
+ ~/.openclaw/workspace/data/awiki-agent-id-message/
263
+ ```
264
+
265
+ 冻结规则:
266
+
267
+ - `doctor`、`runtime setup`、`migrate from-v1` 需要检测旧路径;
268
+ - 默认行为是提示导入,不直接修改旧目录;
269
+ - 正式迁移入口固定为:`awiki-cli migrate from-v1`。
270
+
271
+ ## 6. 本地存储基线冻结
272
+
273
+ ### 6.1 凭证/identity 布局
274
+
275
+ v2 凭证布局以 `../awiki-agent-id-message/scripts/credential_layout.py` 为基线,必须兼容以下文件集合:
276
+
277
+ ```text
278
+ index.json
279
+ identity.json
280
+ auth.json
281
+ did_document.json
282
+ key-1-private.pem
283
+ key-1-public.pem
284
+ e2ee-signing-private.pem
285
+ e2ee-agreement-private.pem
286
+ e2ee-state.json
287
+ ```
288
+
289
+ ### 6.2 SQLite 表与视图基线
290
+
291
+ v2 SQLite 基线以 `../awiki-agent-id-message/scripts/local_store.py` 为准,首版必须保留:
292
+
293
+ **表**
294
+ - `contacts`
295
+ - `messages`
296
+ - `e2ee_outbox`
297
+ - `groups`
298
+ - `group_members`
299
+ - `relationship_events`
300
+ - `e2ee_sessions`
301
+
302
+ **视图**
303
+ - `threads`
304
+ - `inbox`
305
+ - `outbox`
306
+
307
+ ### 6.3 线程规则
308
+
309
+ Phase 1 冻结以下 thread id 规则:
310
+
311
+ - 私聊:`dm:{min_did}:{max_did}`
312
+ - 群聊:`group:{group_id}`
313
+
314
+ ### 6.4 文档与实现不一致时的处理
315
+
316
+ - 如果 `local-store-schema.md` 与 `local_store.py` 冲突,以 `local_store.py` 为准
317
+ - 当前已知必须补齐的遗漏:`e2ee_outbox`
318
+
319
+ ---
320
+
321
+ ## 7. runtime / secure / build 边界冻结
322
+
323
+ ### 7.1 runtime 边界
324
+
325
+ - transport 只允许在 `runtime` 域显式暴露
326
+ - websocket mode 下,listener 持有唯一远端连接
327
+ - websocket mode 下,其它 CLI 通过本地 IPC / daemon 转发
328
+ - http mode 下,CLI 直接访问服务
329
+
330
+ ### 7.2 secure 首发范围
331
+
332
+ - Phase 1 只要求 secure 契约与命令面冻结
333
+ - 首发 secure 范围固定为 **direct E2EE**
334
+ - **group E2EE 不阻塞首发**
335
+
336
+ ### 7.3 Go 兼容性与构建策略
337
+
338
+ 这是新增冻结要求:
339
+
340
+ - **Go 语言版本基线固定为 1.22**
341
+ - **Go 核心实现必须保持 pure Go**
342
+ - **主二进制禁止依赖 CGO**
343
+ - SQLite、加密、配置、输出、completion、打包链路都必须优先选择纯 Go 依赖
344
+ - 如果存在系统兼容性或 OS 集成层面的额外需求,可以在 **TypeScript/Node 的薄壳** 中实现,但不能把这类兼容性交给 CGO 去解决
345
+
346
+ 具体约束:
347
+
348
+ - `go.mod` 的 `go` 指令固定为 `1.22`
349
+ - Go CLI 主程序必须在默认 `CGO_ENABLED=0` 下可构建
350
+ - 任何新增依赖如果要求 CGO,默认视为不满足约束,除非后续 ADR 明确批准替代方案
351
+ - 如果需要做平台安装器、系统壳、Node 分发包装、桌面/脚本桥接,优先放到 TS shell 层
352
+
353
+ ---
354
+
355
+ ## 8. 跟进文档同步项
356
+
357
+ Phase 0 已冻结但原始文档尚未完全同步的点如下:
358
+
359
+ 1. `docs/architecture/awiki-command-v2.md` 中的 `AVIKI_*` 需要后续同步为 `AWIKI_*`
360
+ 2. `docs/architecture/awiki-command-v2.md` 中的 `msg group ...` 需要后续同步为 `group ...` canonical surface 或明确标注为 alias
361
+ 3. `docs/architecture/awiki-v2-architecture.md` 附录中的顶级 `api` 需要后续同步为“保留项”或删除
362
+ 4. `../awiki-agent-id-message/references/local-store-schema.md` 需要补 `e2ee_outbox`
363
+ 5. 主计划文档需要标注 Phase 0 冻结结果优先于草案细节
@@ -0,0 +1,169 @@
1
+ # awiki-cli 发布与回滚手册
2
+
3
+ 本文档描述 awiki-cli 的发布主链路、预发布/回滚脚本,以及在出现坏版本时的处理建议。目标是让日常发版在几条标准命令内完成,并且可以安全地撤回。
4
+
5
+ ## 1. 版本号与 Tag 约定
6
+
7
+ - 单一版本真相:仓库根目录的 `package.json.version`,npm 包名为 `@awiki/cli`。
8
+ - Git Tag 规则:
9
+ - 正式版:`vX.Y.Z`(例如 `v0.1.0`)。
10
+ - 预发布版:`vX.Y.Z-<pre>`(例如 `v0.2.0-beta.1` / `v0.2.0-rc.1`)。
11
+ - Go 构建版本:通过 GoReleaser 将 Tag 版本注入 `internal/buildinfo.Version`。
12
+
13
+ **注意**:修改版本号时必须先改 `package.json.version`,并提交到当前分支,任何 Tag 都必须与该版本严格一致。
14
+
15
+ ## 2. 正式发布(stable)
16
+
17
+ ### 2.1 前置检查
18
+
19
+ 1. 确保当前分支已经包含所有要发布的改动,并推送到远端:
20
+
21
+ ```bash
22
+ git status
23
+ git push
24
+ ```
25
+
26
+ 2. 确认 `package.json.version` 为标准 semver(不带 `-beta` / `-rc` 等)。
27
+
28
+ 3. 在 GitHub 仓库的 workflow secrets 中配置 npm 凭据:
29
+
30
+ - `NPM_TOKEN`:具有发布 `@awiki/cli` 的权限。
31
+
32
+ ### 2.2 创建并推送 Tag
33
+
34
+ 在 awiki-cli 仓库根目录执行:
35
+
36
+ ```bash
37
+ scripts/release/tag-release.sh
38
+ ```
39
+
40
+ 该脚本会:
41
+
42
+ - 从 `package.json.version` 读取版本,生成 `vX.Y.Z`;
43
+ - 要求工作区干净、当前分支已设置 upstream 且完全 push;
44
+ - 检查本地和远端是否已有同名 Tag;
45
+ - 创建 `vX.Y.Z` 的 annotated tag 并 push 到 origin。
46
+
47
+ ### 2.3 CI 行为
48
+
49
+ 推送 `vX.Y.Z` Tag 后,`.github/workflows/release.yml` 会自动执行:
50
+
51
+ 1. 使用 GoReleaser 按 `.goreleaser.yml` 构建多平台二进制,并创建 GitHub Release;
52
+ 2. 对稳定 Tag(`vX.Y.Z` 且不包含 `-`)执行一次 npm 发布:
53
+
54
+ ```bash
55
+ npm publish --access public
56
+ ```
57
+
58
+ 发布完成后可以做一个最小自检:
59
+
60
+ ```bash
61
+ npm view @awiki/cli version
62
+ ```
63
+
64
+ 确认 registry 上的版本号与刚刚发布的一致。
65
+
66
+ ## 3. 预发布版本(beta/rc)
67
+
68
+ > 预发布用于内测 / 灰度,不会自动覆盖 npm 的 `latest`,而是挂在指定 dist-tag(例如 `beta`)。
69
+
70
+ ### 3.1 调整版本号
71
+
72
+ 将 `package.json.version` 修改为带预发布后缀的版本,例如:
73
+
74
+ - `0.2.0-beta.1`
75
+ - `0.2.0-rc.1`
76
+
77
+ 提交并推送修改。
78
+
79
+ ### 3.2 使用预发布脚本创建 Tag
80
+
81
+ 运行:
82
+
83
+ ```bash
84
+ scripts/release/release-prerelease.sh <dist-tag>
85
+ ```
86
+
87
+ 示例:
88
+
89
+ ```bash
90
+ scripts/release/release-prerelease.sh beta
91
+ ```
92
+
93
+ 脚本行为:
94
+
95
+ - 读取 `package.json.version`,要求版本中包含 `-`(预发布后缀);
96
+ - 检查工作区干净、当前分支已 push 且没有同名 Tag;
97
+ - 创建并推送 Tag:`v<package.json.version>`(例如 `v0.2.0-beta.1`);
98
+ - 打印后续建议,包括如何发布带 dist-tag 的 npm 预发布包。
99
+
100
+ 当前版本的 CI release workflow 只对稳定 Tag 自动执行 `npm publish`。预发布包的 npm 发布建议手动执行:
101
+
102
+ ```bash
103
+ NODE_AUTH_TOKEN=... npm publish --access public --tag <dist-tag>
104
+ ```
105
+
106
+ 后续可以根据需要将这一流程收敛到单独的预发布 workflow。
107
+
108
+ ## 4. 回滚/撤回发布
109
+
110
+ > 回滚操作具有破坏性,仅在明确确认为 “坏版本” 时使用。脚本默认只打印推荐命令,只有在显式开启时才真正执行。
111
+
112
+ ### 4.1 withdraw-release.sh 概览
113
+
114
+ 脚本路径:`scripts/release/withdraw-release.sh`
115
+
116
+ 用法:
117
+
118
+ ```bash
119
+ scripts/release/withdraw-release.sh <version>
120
+ ```
121
+
122
+ 示例:
123
+
124
+ ```bash
125
+ scripts/release/withdraw-release.sh 0.1.0
126
+ scripts/release/withdraw-release.sh 0.2.0-beta.1
127
+ ```
128
+
129
+ 脚本会:
130
+
131
+ - 计算 Tag 名:`v<version>`;
132
+ - 检查本地和远端是否存在该 Tag;
133
+ - 打印一组推荐的回滚命令,包括:
134
+ - 删除 Git Tag(本地 + origin);
135
+ - 使用 GitHub CLI 草拟/删除 Release;
136
+ - 使用 `npm deprecate` 和/或 `npm dist-tag` 调整 npm 状态;
137
+ - **只在设置环境变量 `AWIKI_CLI_WITHDRAW_EXECUTE=1` 时真正执行这些命令**,否则仅打印提示,方便人工审阅后复制执行。
138
+
139
+ 典型撤回流程可以是:
140
+
141
+ 1. 先在命令行预览脚本给出的建议:
142
+
143
+ ```bash
144
+ scripts/release/withdraw-release.sh 0.1.0
145
+ ```
146
+
147
+ 2. 确认无误后,显式开启执行开关:
148
+
149
+ ```bash
150
+ AWIKI_CLI_WITHDRAW_EXECUTE=1 scripts/release/withdraw-release.sh 0.1.0
151
+ ```
152
+
153
+ 3. 根据实际情况适当调整 `npm deprecate` 文案和保留的 dist-tag。
154
+
155
+ ## 5. 与版本策略/强制升级的关系
156
+
157
+ awiki-cli 内部通过 `internal/update` 模块和配置项:
158
+
159
+ - `update.disable_strict_version`
160
+ - `update.metadata_cache_ttl_seconds`
161
+ - 环境变量 `AWIKI_CLI_DISABLE_STRICT_VERSION` / `AWIKI_CLI_UPDATE_CACHE_TTL`
162
+
163
+ 来决定:
164
+
165
+ - 哪个版本是最新版本(latest);
166
+ - 哪个版本是最小支持版本(minSupportedVersion);
167
+ - 何时对过旧版本执行强制升级拦截。
168
+
169
+ 一旦通过正式发布或预发布调整了 npm 上的 `version` 和 `awikiCli.minSupportedVersion`,客户端的版本策略会在缓存 TTL 过期或手动刷新后自动生效。坏版本被回滚或标记为 deprecated 后,也建议同步更新 `minSupportedVersion`,确保新版本的强制升级逻辑与发布状态一致。
package/go.mod ADDED
@@ -0,0 +1,29 @@
1
+ module github.com/agentconnect/awiki-cli
2
+
3
+ go 1.22
4
+
5
+ require (
6
+ github.com/agent-network-protocol/anp/golang v0.7.2
7
+ github.com/coder/websocket v1.8.12
8
+ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1
9
+ github.com/google/uuid v1.6.0
10
+ github.com/itchyny/gojq v0.12.17
11
+ github.com/spf13/cobra v1.9.1
12
+ modernc.org/sqlite v1.34.5
13
+ )
14
+
15
+ require (
16
+ github.com/btcsuite/btcd/btcec/v2 v2.3.6 // indirect
17
+ github.com/dustin/go-humanize v1.0.1 // indirect
18
+ github.com/inconshreveable/mousetrap v1.1.0 // indirect
19
+ github.com/itchyny/timefmt-go v0.1.6 // indirect
20
+ github.com/mattn/go-isatty v0.0.20 // indirect
21
+ github.com/ncruces/go-strftime v0.1.9 // indirect
22
+ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
23
+ github.com/spf13/pflag v1.0.6 // indirect
24
+ golang.org/x/crypto v0.31.0 // indirect
25
+ golang.org/x/sys v0.28.0 // indirect
26
+ modernc.org/libc v1.55.3 // indirect
27
+ modernc.org/mathutil v1.6.0 // indirect
28
+ modernc.org/memory v1.8.0 // indirect
29
+ )
package/go.sum ADDED
@@ -0,0 +1,73 @@
1
+ github.com/agent-network-protocol/anp/golang v0.7.2 h1:8pk5VIhGrJhkSmhiPALaL2hj9avcrRUD9Sx2aSrsAZk=
2
+ github.com/agent-network-protocol/anp/golang v0.7.2/go.mod h1:IarvwCndJNX0fZUuT8dWnkG67Ah2zMXuunzQr6lbE30=
3
+ github.com/btcsuite/btcd/btcec/v2 v2.3.6 h1:IzlsEr9olcSRKB/n7c4351F3xHKxS2lma+1UFGCYd4E=
4
+ github.com/btcsuite/btcd/btcec/v2 v2.3.6/go.mod h1:m22FrOAiuxl/tht9wIqAoGHcbnCCaPWyauO8y2LGGtQ=
5
+ github.com/btcsuite/btcd/chaincfg/chainhash v1.0.1 h1:q0rUy8C/TYNBQS1+CGKw68tLOFYSNEs0TFnxxnS9+4U=
6
+ github.com/btcsuite/btcd/chaincfg/chainhash v1.0.1/go.mod h1:7SFka0XMvUgj3hfZtydOrQY2mwhPclbT2snogU7SQQc=
7
+ github.com/coder/websocket v1.8.12 h1:5bUXkEPPIbewrnkU8LTCLVaxi4N4J8ahufH2vlo4NAo=
8
+ github.com/coder/websocket v1.8.12/go.mod h1:LNVeNrXQZfe5qhS9ALED3uA+l5pPqvwXg3CKoDBB2gs=
9
+ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
10
+ github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
11
+ github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
12
+ github.com/decred/dcrd/crypto/blake256 v1.1.0 h1:zPMNGQCm0g4QTY27fOCorQW7EryeQ/U0x++OzVrdms8=
13
+ github.com/decred/dcrd/crypto/blake256 v1.1.0/go.mod h1:2OfgNZ5wDpcsFmHmCK5gZTPcCXqlm2ArzUIkw9czNJo=
14
+ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1 h1:5RVFMOWjMyRy8cARdy79nAmgYw3hK/4HUq48LQ6Wwqo=
15
+ github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.1/go.mod h1:ZXNYxsqcloTdSy/rNShjYzMhyjf0LaoftYK0p+A3h40=
16
+ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
17
+ github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
18
+ github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd h1:gbpYu9NMq8jhDVbvlGkMFWCjLFlqqEZjEmObmhUy6Vo=
19
+ github.com/google/pprof v0.0.0-20240409012703-83162a5b38cd/go.mod h1:kf6iHlnVGwgKolg33glAes7Yg/8iWP8ukqeldJSO7jw=
20
+ github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
21
+ github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
22
+ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
23
+ github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
24
+ github.com/itchyny/gojq v0.12.17 h1:8av8eGduDb5+rvEdaOO+zQUjA04MS0m3Ps8HiD+fceg=
25
+ github.com/itchyny/gojq v0.12.17/go.mod h1:WBrEMkgAfAGO1LUcGOckBl5O726KPp+OlkKug0I/FEY=
26
+ github.com/itchyny/timefmt-go v0.1.6 h1:ia3s54iciXDdzWzwaVKXZPbiXzxxnv1SPGFfM/myJ5Q=
27
+ github.com/itchyny/timefmt-go v0.1.6/go.mod h1:RRDZYC5s9ErkjQvTvvU7keJjxUYzIISJGxm9/mAERQg=
28
+ github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
29
+ github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
30
+ github.com/ncruces/go-strftime v0.1.9 h1:bY0MQC28UADQmHmaF5dgpLmImcShSi2kHU9XLdhx/f4=
31
+ github.com/ncruces/go-strftime v0.1.9/go.mod h1:Fwc5htZGVVkseilnfgOVb9mKy6w1naJmn9CehxcKcls=
32
+ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
33
+ github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
34
+ github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
35
+ github.com/spf13/cobra v1.9.1 h1:CXSaggrXdbHK9CF+8ywj8Amf7PBRmPCOJugH954Nnlo=
36
+ github.com/spf13/cobra v1.9.1/go.mod h1:nDyEzZ8ogv936Cinf6g1RU9MRY64Ir93oCnqb9wxYW0=
37
+ github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
38
+ github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
39
+ golang.org/x/crypto v0.31.0 h1:ihbySMvVjLAeSH1IbfcRTkD/iNscyz8rGzjF/E5hV6U=
40
+ golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
41
+ golang.org/x/mod v0.16.0 h1:QX4fJ0Rr5cPQCF7O9lh9Se4pmwfwskqZfq5moyldzic=
42
+ golang.org/x/mod v0.16.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
43
+ golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
44
+ golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
45
+ golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
46
+ golang.org/x/tools v0.19.0 h1:tfGCXNR1OsFG+sVdLAitlpjAvD/I6dHDKnYrpEZUHkw=
47
+ golang.org/x/tools v0.19.0/go.mod h1:qoJWxmGSIBmAeriMx19ogtrEPrGtDbPK634QFIcLAhc=
48
+ gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
49
+ gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
50
+ modernc.org/cc/v4 v4.21.4 h1:3Be/Rdo1fpr8GrQ7IVw9OHtplU4gWbb+wNgeoBMmGLQ=
51
+ modernc.org/cc/v4 v4.21.4/go.mod h1:HM7VJTZbUCR3rV8EYBi9wxnJ0ZBRiGE5OeGXNA0IsLQ=
52
+ modernc.org/ccgo/v4 v4.19.2 h1:lwQZgvboKD0jBwdaeVCTouxhxAyN6iawF3STraAal8Y=
53
+ modernc.org/ccgo/v4 v4.19.2/go.mod h1:ysS3mxiMV38XGRTTcgo0DQTeTmAO4oCmJl1nX9VFI3s=
54
+ modernc.org/fileutil v1.3.0 h1:gQ5SIzK3H9kdfai/5x41oQiKValumqNTDXMvKo62HvE=
55
+ modernc.org/fileutil v1.3.0/go.mod h1:XatxS8fZi3pS8/hKG2GH/ArUogfxjpEKs3Ku3aK4JyQ=
56
+ modernc.org/gc/v2 v2.4.1 h1:9cNzOqPyMJBvrUipmynX0ZohMhcxPtMccYgGOJdOiBw=
57
+ modernc.org/gc/v2 v2.4.1/go.mod h1:wzN5dK1AzVGoH6XOzc3YZ+ey/jPgYHLuVckd62P0GYU=
58
+ modernc.org/libc v1.55.3 h1:AzcW1mhlPNrRtjS5sS+eW2ISCgSOLLNyFzRh/V3Qj/U=
59
+ modernc.org/libc v1.55.3/go.mod h1:qFXepLhz+JjFThQ4kzwzOjA/y/artDeg+pcYnY+Q83w=
60
+ modernc.org/mathutil v1.6.0 h1:fRe9+AmYlaej+64JsEEhoWuAYBkOtQiMEU7n/XgfYi4=
61
+ modernc.org/mathutil v1.6.0/go.mod h1:Ui5Q9q1TR2gFm0AQRqQUaBWFLAhQpCwNcuhBOSedWPo=
62
+ modernc.org/memory v1.8.0 h1:IqGTL6eFMaDZZhEWwcREgeMXYwmW83LYW8cROZYkg+E=
63
+ modernc.org/memory v1.8.0/go.mod h1:XPZ936zp5OMKGWPqbD3JShgd/ZoQ7899TUuQqxY+peU=
64
+ modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
65
+ modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
66
+ modernc.org/sortutil v1.2.0 h1:jQiD3PfS2REGJNzNCMMaLSp/wdMNieTbKX920Cqdgqc=
67
+ modernc.org/sortutil v1.2.0/go.mod h1:TKU2s7kJMf1AE84OoiGppNHJwvB753OYfNl2WRb++Ss=
68
+ modernc.org/sqlite v1.34.5 h1:Bb6SR13/fjp15jt70CL4f18JIN7p7dnMExd+UFnF15g=
69
+ modernc.org/sqlite v1.34.5/go.mod h1:YLuNmX9NKs8wRNK2ko1LW1NGYcc9FkBO69JOt1AR9JE=
70
+ modernc.org/strutil v1.2.0 h1:agBi9dp1I+eOnxXeiZawM8F4LawKv4NzGWSaLfyeNZA=
71
+ modernc.org/strutil v1.2.0/go.mod h1:/mdcBmfOibveCTBxUl5B5l6W+TTH1FXPLHZE6bTosX0=
72
+ modernc.org/token v1.1.0 h1:Xl7Ap9dKaEs5kLoOQeQmPWevfnk/DM5qcLcYlA8ys6Y=
73
+ modernc.org/token v1.1.0/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=