skill-forge-hub 1.0.3 → 1.0.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.
Files changed (95) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/README.md +82 -150
  3. package/annual-report/SKILL.md +27 -7
  4. package/annual-report/resources/data-collection.md +22 -5
  5. package/annual-report/resources/disk-and-html.md +6 -6
  6. package/annual-report/resources/reference.html +77 -45
  7. package/annual-report/resources/usage-guide.md +10 -2
  8. package/annual-report/user-config.md +16 -4
  9. package/article-to-html/.preserve +3 -0
  10. package/article-to-html/SKILL.md +26 -7
  11. package/article-to-html/design-system.md +9 -3
  12. package/article-to-html/resources/reference.html +631 -0
  13. package/article-to-html/resources/usage-guide.md +9 -1
  14. package/article-to-html/user-config.md +6 -3
  15. package/cli.js +58 -26
  16. package/daily-report/SKILL.md +27 -7
  17. package/daily-report/resources/content-rules.md +2 -2
  18. package/daily-report/resources/data-collection.md +26 -23
  19. package/daily-report/resources/disk-and-html.md +2 -2
  20. package/daily-report/resources/reference.html +24 -3
  21. package/daily-report/resources/usage-guide.md +10 -2
  22. package/daily-report/user-config.md +16 -4
  23. package/deck-stage/SKILL.md +15 -4
  24. package/deck-stage/resources/cover-template.html +3 -3
  25. package/deck-stage/resources/data-schema.md +11 -1
  26. package/deck-stage/resources/pptx-builder.js +1 -1
  27. package/deck-stage/resources/usage-guide.md +9 -2
  28. package/deck-stage/user-config.md +1 -1
  29. package/docs/architecture.md +89 -0
  30. package/docs/images/article-to-html.png +0 -0
  31. package/docs/images/daily-report.png +0 -0
  32. package/docs/images/deck-stage.png +0 -0
  33. package/docs/images/magic-deck.png +0 -0
  34. package/docs/images/meeting-minutes.png +0 -0
  35. package/docs/images/prompt-pouch.png +0 -0
  36. package/docs/install.md +71 -0
  37. package/magic-deck/SKILL.md +23 -8
  38. package/magic-deck/resources/content-guide.md +5 -4
  39. package/magic-deck/resources/deck-spec.md +18 -11
  40. package/magic-deck/resources/reference.html +110 -32
  41. package/magic-deck/resources/usage-guide.md +10 -2
  42. package/magic-deck/user-config.md +4 -4
  43. package/meeting-minutes/SKILL.md +51 -0
  44. package/meeting-minutes/resources/content-rules.md +57 -0
  45. package/meeting-minutes/resources/disk-and-html.md +26 -0
  46. package/meeting-minutes/resources/meeting-type-dictionary.md +24 -0
  47. package/meeting-minutes/resources/reference.html +436 -0
  48. package/meeting-minutes/resources/usage-guide.md +63 -0
  49. package/meeting-minutes/user-config.md +56 -0
  50. package/meta-forge/SKILL.md +6 -6
  51. package/meta-forge/resources/forge-rules.md +61 -9
  52. package/meta-forge/resources/usage-guide.md +7 -3
  53. package/meta-forge/user-config.md +1 -1
  54. package/monthly-report/SKILL.md +62 -0
  55. package/monthly-report/resources/content-rules.md +40 -0
  56. package/monthly-report/resources/data-collection.md +44 -0
  57. package/monthly-report/resources/date-parsing.md +18 -0
  58. package/monthly-report/resources/disk-and-html.md +29 -0
  59. package/monthly-report/resources/industry-dictionary.md +21 -0
  60. package/monthly-report/resources/reference.html +531 -0
  61. package/monthly-report/resources/usage-guide.md +75 -0
  62. package/monthly-report/user-config.md +53 -0
  63. package/package.json +9 -2
  64. package/prompt-pouch/SKILL.md +17 -2
  65. package/prompt-pouch/resources/data-format.md +1 -1
  66. package/prompt-pouch/resources/reference.html +56 -24
  67. package/prompt-pouch/resources/usage-guide.md +10 -3
  68. package/prompt-pouch/user-config.md +1 -1
  69. package/quarterly-report/SKILL.md +63 -0
  70. package/quarterly-report/resources/content-rules.md +42 -0
  71. package/quarterly-report/resources/data-collection.md +46 -0
  72. package/quarterly-report/resources/date-parsing.md +19 -0
  73. package/quarterly-report/resources/disk-and-html.md +22 -0
  74. package/quarterly-report/resources/industry-dictionary.md +21 -0
  75. package/quarterly-report/resources/reference.html +509 -0
  76. package/quarterly-report/resources/usage-guide.md +76 -0
  77. package/quarterly-report/user-config.md +53 -0
  78. package/spec-doc2spec/SKILL.md +21 -22
  79. package/spec-doc2spec/resources/checklist.md +7 -0
  80. package/spec-doc2spec/resources/images.md +14 -5
  81. package/spec-doc2spec/resources/structure.md +19 -10
  82. package/spec-doc2spec/resources/usage-guide.md +10 -8
  83. package/spec-doc2spec/user-config.md +2 -2
  84. package/spec-spec2doc/SKILL.md +4 -4
  85. package/spec-spec2doc/resources/checklist.md +6 -0
  86. package/spec-spec2doc/resources/pdf-path.md +1 -0
  87. package/spec-spec2doc/resources/usage-guide.md +2 -2
  88. package/template/SKILL.md +1 -1
  89. package/weekly-report/SKILL.md +27 -7
  90. package/weekly-report/resources/content-rules.md +2 -2
  91. package/weekly-report/resources/data-collection.md +26 -23
  92. package/weekly-report/resources/disk-and-html.md +3 -3
  93. package/weekly-report/resources/reference.html +132 -120
  94. package/weekly-report/resources/usage-guide.md +10 -2
  95. package/weekly-report/user-config.md +16 -4
package/annual-report/resources/reference.html CHANGED
@@ -3,6 +3,8 @@
3
3
  <head>
4
4
  <meta charset="UTF-8">
5
5
  <meta name="viewport" content="width=device-width, initial-scale=1">
6
+ <meta name="sf-template" content="annual-report@2">
7
+ <meta name="annual-id" content="REF-ANNUAL-0000">
6
8
  <title>2026 研发年度总结</title>
7
9
  <style>
8
10
 
@@ -162,17 +164,9 @@ body{
162
164
  /* 柱图 */
163
165
  .cb-wrap{margin-top:18px;padding-top:14px;border-top:1px dashed var(--border)}
164
166
  .cb-title{font-size:12px;color:var(--muted);margin-bottom:12px;letter-spacing:1px}
165
- .cb-chart{display:flex;align-items:flex-end;gap:8px;height:110px}
166
- .cb-col{flex:1;display:flex;flex-direction:column;align-items:center;justify-content:flex-end;height:100%;position:relative}
167
- .cb-bar{width:24px;background:linear-gradient(180deg,#5eead4,#14b8a6);border-radius:3px 3px 0 0;
168
- box-shadow:0 0 10px rgba(45,212,191,.35);transition:height .3s ease;animation:cbGrow 1s ease-out both}
169
- .cb-col:hover .cb-bar{box-shadow:0 0 16px rgba(45,212,191,.6)}
170
- .cb-label{font-size:9px;color:var(--muted);margin-top:4px}
171
- .cb-tip{position:absolute;bottom:calc(100% + 6px);left:50%;transform:translateX(-50%) translateY(4px);
172
- background:var(--panel-solid);border:1px solid var(--glow);color:var(--text);font-size:10px;white-space:nowrap;
173
- padding:3px 8px;border-radius:4px;opacity:0;pointer-events:none;transition:opacity .18s,transform .18s;z-index:5}
174
- .cb-col:hover .cb-tip{opacity:1;transform:translateX(-50%) translateY(0)}
175
- @keyframes cbGrow{ from{height:0;} }
167
+ .ech{width:100%;height:110px}
168
+ .ech-off{display:flex;align-items:center;justify-content:center}
169
+ .ech-off::after{content:attr(data-off);font-size:11px;color:var(--muted);text-align:center;line-height:1.6;padding:0 10px}
176
170
  /* 序号徽章 3D 球 */
177
171
  .idx{flex:0 0 auto;width:28px;height:28px;border-radius:50%;position:relative;
178
172
  display:flex;align-items:center;justify-content:center;color:#fff;
@@ -247,7 +241,7 @@ footer{text-align:center;font-size:10px;color:var(--muted);letter-spacing:1px;pa
247
241
  .theme-dock .th-dot[data-theme="mono"]{ background:#1e1f22; }
248
242
  .theme-dock .th-dot[data-theme="light"]{ background:#ffffff; }
249
243
  .theme-dock .th-dot[data-theme="warm"]{ background:#d97706; }
250
- @media print{ .theme-dock{ display:none; .cb-bar{ animation:none !important; } } .rv{ opacity:1 !important; translate:none !important; .cb-bar{ animation:none !important; } } .cb-bar{ animation:none !important; } }
244
+ @media print{ .theme-dock{ display:none; } .rv{ opacity:1 !important; translate:none !important; } }
251
245
  /* 滚动入场：html.js 门控（无 JS/打印全显）；初始视口外的卡片滚到视口才上浮渐显；translate 独立属性不碰 transform，hover 3D 偏转零冲突 */
252
246
  html.js .rv{ opacity:0; translate:0 16px; transition:opacity .5s ease-out, translate .5s ease-out; }
253
247
  html.js .rv.in{ opacity:1; translate:0 0; }
@@ -257,15 +251,6 @@ html.js .rv.in{ opacity:1; translate:0 0; }
257
251
  .wrap{ width:100%; max-width:none; }
258
252
  .header-card{ padding:26px 18px 20px; }
259
253
  .header-card h1{ font-size:26px; }
260
- /* 月提交柱图窄屏收敛：12 列 flex 收缩 + bar 弹性宽 + tip 首末列锚定防裁剪 */
261
- .cb-chart{ gap:4px; }
262
- .cb-col{ min-width:0; }
263
- .cb-bar{ width:100%; max-width:24px; }
264
- .cb-label{ font-size:8px; }
265
- .cb-col:first-child .cb-tip{ left:0; transform:translateY(4px); }
266
- .cb-col:first-child:hover .cb-tip{ transform:translateY(0); }
267
- .cb-col:last-child .cb-tip{ left:auto; right:0; transform:translateY(4px); }
268
- .cb-col:last-child:hover .cb-tip{ transform:translateY(0); }
269
254
  }
270
255
  </style>
271
256
  </head>
@@ -302,7 +287,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
302
287
  <svg viewBox="0 0 24 24" width="22" height="22" fill="none" stroke="#38bdf8" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12 15l4-5M8 15l4-5"/><circle cx="12" cy="14" r="8"/><path d="M12 14l4-5"/></svg>
303
288
  <h2>年度概览</h2>
304
289
  </div>
305
- <div class="tldr-line"><b>TL;DR：</b>立项即狂奔的一年：SpecCore 规范驱动开发平台 7 月从零立项，4 个月 1889 次提交、576 个版本发布、代码库净增 19 万行，完成从单机 CLI 到流水线平台的蜕变。</div>
290
+ <div class="tldr-line"><b>TL;DR：</b>立项即狂奔的一年：示例项目 规范驱动开发平台 7 月从零立项，4 个月 1889 次提交、576 个版本发布、代码库净增 19 万行，完成从单机 CLI 到流水线平台的蜕变。</div>
306
291
  <div class="stat-row">
307
292
  <div class="stat-card"><div class="stat-num">1889</div><div class="stat-label">总提交数（07-05 ~ 11-05）</div></div>
308
293
  <div class="stat-card"><div class="stat-num">576</div><div class="stat-label">版本发布（v5.13.0 → v8.3.399）</div></div>
@@ -332,7 +317,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
332
317
  <div class="tl-group">
333
318
  <span class="tl-node q3">Q3</span>
334
319
  <div class="tl-q">第三季度（7-9 月）</div>
335
- <div class="tl-item"><div class="tl-desc">1、7 月立项首发：SpecCore CLI 完整功能落地，v5.13.0 首版发布</div><div class="tl-meta">335 次提交 · +5.4 万行<span class="tl-badge">Q3</span></div></div>
320
+ <div class="tl-item"><div class="tl-desc">1、7 月立项首发：示例项目 CLI 完整功能落地，v5.13.0 首版发布</div><div class="tl-meta">335 次提交 · +5.4 万行<span class="tl-badge">Q3</span></div></div>
336
321
  <div class="tl-item"><div class="tl-desc">2、8 月密集攻坚：知识资产四层覆盖架构（TOC 目录/自动注入/RAG 检索/阅读清单）成形</div><div class="tl-meta">月内 1154 次提交 · +16.4 万行 · 发布 200+ 版本<span class="tl-badge">Q3</span></div></div>
337
322
  <div class="tl-item"><div class="tl-desc">3、9 月流水线成形：run 端到端流水线与迭代体系建立</div><div class="tl-meta">+7.6 万行 · 328 次提交<span class="tl-badge">Q3</span></div></div>
338
323
  </div>
@@ -340,7 +325,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
340
325
  <span class="tl-node q4">Q4</span>
341
326
  <div class="tl-q">第四季度（10-11 月，截至当前）</div>
342
327
  <div class="tl-item"><div class="tl-desc">4、10 月发布节奏收敛：v8.3 系列起跑，月度发布收紧至约 30 个版本</div><div class="tl-meta">+1.8 万行<span class="tl-badge">Q4</span></div></div>
343
- <div class="tl-item"><div class="tl-desc">5、11-03 v8.3.370 累积发布：GLOBAL 治乱、反推域隔离、文档生成器升格、澄清链修复</div><div class="tl-meta">聚合发布 · 350→370<span class="tl-badge">Q4</span></div></div>
328
+ <div class="tl-item"><div class="tl-desc">5、11-03 v8.3.370 累积发布：全局目录治理、反推域隔离、文档生成器升格、澄清链修复</div><div class="tl-meta">聚合发布 · 350→370<span class="tl-badge">Q4</span></div></div>
344
329
  <div class="tl-item"><div class="tl-desc">6、11-04 v8.3.388：E2E 全链路深度检查 11 项修复 + execute 意图语义硬化</div><div class="tl-meta">379~388 聚合发布<span class="tl-badge">Q4</span></div></div>
345
330
  <div class="tl-item"><div class="tl-desc">7、11-04 v8.3.394：反推链接力协议补全、全局分析默认纯技术、QA 环接力协议（exit 10）</div><div class="tl-meta">392~394 聚合发布<span class="tl-badge">Q4</span></div></div>
346
331
  <div class="tl-item"><div class="tl-desc">8、11-05 v8.3.399（截至当前）：用例核对闸开卷设闸——execute 收尾逐用例勾稽，未实现即入修复环</div><div class="tl-meta">398~399 聚合发布<span class="tl-badge">Q4</span></div></div>
@@ -348,20 +333,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
348
333
  </div>
349
334
  <div class="cb-wrap">
350
335
  <div class="cb-title">年度提交月度分布（次）</div>
351
- <div class="cb-chart">
352
- <div class="cb-col"><div class="cb-tip">1月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">1月</div></div>
353
- <div class="cb-col"><div class="cb-tip">2月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">2月</div></div>
354
- <div class="cb-col"><div class="cb-tip">3月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">3月</div></div>
355
- <div class="cb-col"><div class="cb-tip">4月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">4月</div></div>
356
- <div class="cb-col"><div class="cb-tip">5月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">5月</div></div>
357
- <div class="cb-col"><div class="cb-tip">6月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">6月</div></div>
358
- <div class="cb-col"><div class="cb-tip">7月 · 335 次提交</div><div class="cb-bar" style="height:32px"></div><div class="cb-label">7月</div></div>
359
- <div class="cb-col"><div class="cb-tip">8月 · 1154 次提交</div><div class="cb-bar" style="height:92px"></div><div class="cb-label">8月</div></div>
360
- <div class="cb-col"><div class="cb-tip">9月 · 328 次提交</div><div class="cb-bar" style="height:31px"></div><div class="cb-label">9月</div></div>
361
- <div class="cb-col"><div class="cb-tip">10月 · 54 次提交</div><div class="cb-bar" style="height:8px"></div><div class="cb-label">10月</div></div>
362
- <div class="cb-col"><div class="cb-tip">11月 · 18 次提交</div><div class="cb-bar" style="height:4px"></div><div class="cb-label">11月</div></div>
363
- <div class="cb-col"><div class="cb-tip">12月 · 0 次提交</div><div class="cb-bar" style="height:2px"></div><div class="cb-label">12月</div></div>
364
- </div>
336
+ <div class="ech" id="monthChart" data-off="图表需联网加载 echarts，离线环境不显示"></div>
365
337
  </div>
366
338
  </section>
367
339
 
@@ -374,7 +346,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
374
346
  </div>
375
347
  <ol>
376
348
  <li><span class="idx gw"><b>1</b></span><div class="entry"><div class="desc">沉淀了「四层知识资产架构」（TOC 目录/自动注入/RAG 检索/阅读清单），解决了 AI 对规范库看不见、记不住、找不回的三类可见性断层。</div></div></li>
377
- <li><span class="idx gw"><b>2</b></span><div class="entry"><div class="desc">掌握了 ask 引擎意图识别与 AI 接力协议（[SPECCORE_EXEC]/[SPECCORE_PROMPT]/[SPECCORE_CONTINUE] 标记链），人机协作可从任意断点续跑。</div></div></li>
349
+ <li><span class="idx gw"><b>2</b></span><div class="entry"><div class="desc">掌握了 ask 引擎意图识别与 AI 接力协议（[EXEC]/[PROMPT]/[CONTINUE] 标记链），人机协作可从任意断点续跑。</div></div></li>
378
350
  <li><span class="idx gw"><b>3</b></span><div class="entry"><div class="desc">建立了「聚合发布」节奏：小步高频提交 + 里程碑聚合 tag，兼顾问题定位粒度与交付速度。</div></div></li>
379
351
  <li><span class="idx gw"><b>4</b></span><div class="entry"><div class="desc">积累了质量门禁体系经验：骨架完成度自检、用例核对闸、QA 三阶段验证环，质量兜底不再依赖人肉复查。</div></div></li>
380
352
  </ol>
@@ -389,7 +361,7 @@ html.js .rv.in{ opacity:1; translate:0 0; }
389
361
  </div>
390
362
  <ol>
391
363
  <li><span class="idx rf"><b>1</b></span><div class="entry"><div class="desc">8 月节奏过载：单月 1154 次提交、8-08 单日 95 个版本。</div><div class="meta">影响：文档与代码同步滞后，质量债累积。</div><div class="meta" style="color:var(--accent)"><b style="color:var(--accent)">改进：</b>明年收敛为双周聚合发布、月度版本 ≤20 个。</div></div></li>
392
- <li><span class="idx rf"><b>2</b></span><div class="entry"><div class="desc">生成物污染统计口径：code-graph 等生成物单文件数十万行噪音曾混入行数统计。</div><div class="meta">影响：工作量指标失真，误导投入判断。</div><div class="meta" style="color:var(--accent)"><b style="color:var(--accent)">改进：</b>统计前强制剔除生成物路径白名单。</div></div></li>
364
+ <li><span class="idx rf"><b>2</b></span><div class="entry"><div class="desc">生成物污染统计口径：构建产物等生成文件单文件数十万行噪音曾混入行数统计。</div><div class="meta">影响：工作量指标失真，误导投入判断。</div><div class="meta" style="color:var(--accent)"><b style="color:var(--accent)">改进：</b>统计前强制剔除生成物路径白名单。</div></div></li>
393
365
  <li><span class="idx rf"><b>3</b></span><div class="entry"><div class="desc">发布颗粒度两端失衡：Q3 一日最多 95 个 tag，Q4 单次聚合最多 10 个版本。</div><div class="meta">影响：问题定位粒度在过细与过粗之间摇摆。</div><div class="meta" style="color:var(--accent)"><b style="color:var(--accent)">改进：</b>固定批次大小，每批 ≤10 版本聚合。</div></div></li>
394
366
  </ol>
395
367
  </section>
@@ -404,10 +376,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
404
376
  <div class="goal"><div class="goal-desc">1、<b>发布节奏工程化</b>：双周聚合发布落地，2027 年版本发布总量 ≤120 个</div><div class="goal-q"><span class="q-chip">Q1 建立节奏</span><span class="q-chip">Q2 稳定运行</span></div></div>
405
377
  <div class="goal"><div class="goal-desc">2、<b>测试覆盖率跃升</b>：核心链路自动化覆盖 ≥80%，用例核对闸覆盖全部命令</div><div class="goal-q"><span class="q-chip">Q1 铺 E2E</span><span class="q-chip">Q3 达标</span></div></div>
406
378
  <div class="goal"><div class="goal-desc">3、<b>生成物与体量治理</b>：启动耗时降 30%、生成物目录隔离入白名单</div><div class="goal-q"><span class="q-chip">Q2 完成隔离</span><span class="q-chip">Q4 验收性能</span></div></div>
407
- <div class="goal"><div class="goal-desc">4、<b>生态落地</b>：spec-once/流水线在 ≥3 个真实项目落地并沉淀案例</div><div class="goal-q"><span class="q-chip">Q2 试点</span><span class="q-chip">Q4 案例库发布</span></div></div>
379
+ <div class="goal"><div class="goal-desc">4、<b>生态落地</b>：一键流水线/流水线在 ≥3 个真实项目落地并沉淀案例</div><div class="goal-q"><span class="q-chip">Q2 试点</span><span class="q-chip">Q4 案例库发布</span></div></div>
408
380
  </section>
409
381
 
410
- <footer>GENERATED BY SPECCORE TEAM · 2026</footer>
382
+ <footer>GENERATED BY AI TEAM · 2026</footer>
411
383
  </div>
412
384
 
413
385
  <!-- 主题换肤坞（五色点） -->
@@ -419,9 +391,10 @@ html.js .rv.in{ opacity:1; translate:0 0; }
419
391
  <button class="th-dot" type="button" data-theme="warm" title="温暖渐变"></button>
420
392
  </div>
421
393
 
394
+ <script src="https://cdn.jsdelivr.net/npm/echarts@5.5.1/dist/echarts.min.js"></script>
422
395
  <script>
423
396
  // 复制源 = txt 纯文本全文
424
- var TXT = "2026 研发年度总结\n\n生成时间：2026-11-09 17:03:01\n\n年度概览\nTL;DR：立项即狂奔的一年：SpecCore 规范驱动开发平台 7 月从零立项，4 个月 1889 次提交、576 个版本发布、代码库净增 19 万行，完成从单机 CLI 到流水线平台的蜕变。\n1、总提交数：1889 次（07-05 ~ 11-05）\n2、版本发布：576 个（v5.13.0 → v8.3.399）\n3、净增代码：+19.0 万行（+32.9 万 / -13.9 万）\n4、月度峰值：1154 次提交（8 月）\n\n核心成果与里程碑\n1、7 月立项首发：SpecCore CLI 完整功能落地，v5.13.0 首版发布（335 次提交、+5.4 万行）- Q3\n2、8 月密集攻坚：知识资产四层覆盖架构（TOC 目录/自动注入/RAG 检索/阅读清单）成形，月内 1154 次提交、+16.4 万行、发布 200+ 版本 - Q3\n3、9 月流水线成形：run 端到端流水线与迭代体系建立，+7.6 万行、328 次提交 - Q3\n4、10 月发布节奏收敛：v8.3 系列起跑，月度发布收紧至约 30 个版本，+1.8 万行 - Q4\n5、11-03 v8.3.370 累积发布：GLOBAL 治乱、反推域隔离、文档生成器升格、澄清链修复 - Q4\n6、11-04 v8.3.388：E2E 全链路深度检查 11 项修复 + execute 意图语义硬化 - Q4\n7、11-04 v8.3.394：反推链接力协议补全、全局分析默认纯技术、QA 环接力协议（exit 10）- Q4\n8、11-05 v8.3.399（截至当前）：用例核对闸开卷设闸——execute 收尾逐用例勾稽，未实现即入修复环 - Q4\n\n经验与成长\n1、沉淀了「四层知识资产架构」（TOC 目录/自动注入/RAG 检索/阅读清单），解决了 AI 对规范库看不见、记不住、找不回的三类可见性断层。\n2、掌握了 ask 引擎意图识别与 AI 接力协议（[SPECCORE_EXEC]/[SPECCORE_PROMPT]/[SPECCORE_CONTINUE] 标记链），人机协作可从任意断点续跑。\n3、建立了「聚合发布」节奏：小步高频提交 + 里程碑聚合 tag，兼顾问题定位粒度与交付速度。\n4、积累了质量门禁体系经验：骨架完成度自检、用例核对闸、QA 三阶段验证环，质量兜底不再依赖人肉复查。\n\n不足与反思\n1、8 月节奏过载：单月 1154 次提交、8-08 单日 95 个版本。\n影响：文档与代码同步滞后，质量债累积。\n改进：明年收敛为双周聚合发布、月度版本 ≤20 个。\n2、生成物污染统计口径：code-graph 等生成物单文件数十万行噪音曾混入行数统计。\n影响：工作量指标失真，误导投入判断。\n改进：统计前强制剔除生成物路径白名单。\n3、发布颗粒度两端失衡：Q3 一日最多 95 个 tag，Q4 单次聚合最多 10 个版本。\n影响：问题定位粒度在过细与过粗之间摇摆。\n改进：固定批次大小，每批 ≤10 版本聚合。\n\n新年展望与规划\n1、发布节奏工程化：双周聚合发布落地，2027 年版本发布总量 ≤120 个（Q1 建立节奏、Q2 稳定运行）。\n2、测试覆盖率跃升：核心链路自动化覆盖 ≥80%，用例核对闸覆盖全部命令（Q1 铺 E2E、Q3 达标）。\n3、生成物与体量治理：启动耗时降 30%、生成物目录隔离入白名单（Q2 完成隔离、Q4 验收性能）。\n4、生态落地：spec-once/流水线在 ≥3 个真实项目落地并沉淀案例（Q2 试点、Q4 案例库发布）。";
397
+ var TXT = "2026 研发年度总结\n\n生成时间：2026-11-09 17:03:01\n\n年度概览\nTL;DR：立项即狂奔的一年：示例项目 规范驱动开发平台 7 月从零立项，4 个月 1889 次提交、576 个版本发布、代码库净增 19 万行，完成从单机 CLI 到流水线平台的蜕变。\n1、总提交数：1889 次（07-05 ~ 11-05）\n2、版本发布：576 个（v5.13.0 → v8.3.399）\n3、净增代码：+19.0 万行（+32.9 万 / -13.9 万）\n4、月度峰值：1154 次提交（8 月）\n\n核心成果与里程碑\n1、7 月立项首发：示例项目 CLI 完整功能落地，v5.13.0 首版发布（335 次提交、+5.4 万行）- Q3\n2、8 月密集攻坚：知识资产四层覆盖架构（TOC 目录/自动注入/RAG 检索/阅读清单）成形，月内 1154 次提交、+16.4 万行、发布 200+ 版本 - Q3\n3、9 月流水线成形：run 端到端流水线与迭代体系建立，+7.6 万行、328 次提交 - Q3\n4、10 月发布节奏收敛：v8.3 系列起跑，月度发布收紧至约 30 个版本，+1.8 万行 - Q4\n5、11-03 v8.3.370 累积发布：全局目录治理、反推域隔离、文档生成器升格、澄清链修复 - Q4\n6、11-04 v8.3.388：E2E 全链路深度检查 11 项修复 + execute 意图语义硬化 - Q4\n7、11-04 v8.3.394：反推链接力协议补全、全局分析默认纯技术、QA 环接力协议（exit 10）- Q4\n8、11-05 v8.3.399（截至当前）：用例核对闸开卷设闸——execute 收尾逐用例勾稽，未实现即入修复环 - Q4\n\n经验与成长\n1、沉淀了「四层知识资产架构」（TOC 目录/自动注入/RAG 检索/阅读清单），解决了 AI 对规范库看不见、记不住、找不回的三类可见性断层。\n2、掌握了 ask 引擎意图识别与 AI 接力协议（[EXEC]/[PROMPT]/[CONTINUE] 标记链），人机协作可从任意断点续跑。\n3、建立了「聚合发布」节奏：小步高频提交 + 里程碑聚合 tag，兼顾问题定位粒度与交付速度。\n4、积累了质量门禁体系经验：骨架完成度自检、用例核对闸、QA 三阶段验证环，质量兜底不再依赖人肉复查。\n\n不足与反思\n1、8 月节奏过载：单月 1154 次提交、8-08 单日 95 个版本。\n影响：文档与代码同步滞后，质量债累积。\n改进：明年收敛为双周聚合发布、月度版本 ≤20 个。\n2、生成物污染统计口径：构建产物等生成文件单文件数十万行噪音曾混入行数统计。\n影响：工作量指标失真，误导投入判断。\n改进：统计前强制剔除生成物路径白名单。\n3、发布颗粒度两端失衡：Q3 一日最多 95 个 tag，Q4 单次聚合最多 10 个版本。\n影响：问题定位粒度在过细与过粗之间摇摆。\n改进：固定批次大小，每批 ≤10 版本聚合。\n\n新年展望与规划\n1、发布节奏工程化：双周聚合发布落地，2027 年版本发布总量 ≤120 个（Q1 建立节奏、Q2 稳定运行）。\n2、测试覆盖率跃升：核心链路自动化覆盖 ≥80%，用例核对闸覆盖全部命令（Q1 铺 E2E、Q3 达标）。\n3、生成物与体量治理：启动耗时降 30%、生成物目录隔离入白名单（Q2 完成隔离、Q4 验收性能）。\n4、生态落地：一键流水线/流水线在 ≥3 个真实项目落地并沉淀案例（Q2 试点、Q4 案例库发布）。";
425
398
 
426
399
  // 一键复制
427
400
  var btn = document.getElementById('copyBtn');
@@ -468,7 +441,65 @@ if (location.search.indexOf('shot=content') > -1) {
468
441
  });
469
442
  }
470
443
 
444
+ // 月度提交柱图（echarts CDN 渲染；离线时容器降级提示；?shot 截图模式停动画——headless 虚拟时间下动画帧不推进会停在初始帧）
445
+ (function(){
446
+ var el = document.getElementById('monthChart');
447
+ if (!el) return;
448
+ if (typeof echarts === 'undefined'){ el.classList.add('ech-off'); return; }
449
+ var noAnim = location.search.indexOf('shot=') !== -1;
450
+ var chart = echarts.init(el);
451
+ var MONTHS = ['1月','2月','3月','4月','5月','6月','7月','8月','9月','10月','11月','12月'];
452
+ var VALS = [0,0,0,0,0,0,335,1154,328,54,18,0];
453
+ function tokens(){
454
+ var s = getComputedStyle(document.documentElement);
455
+ return {
456
+ accent:s.getPropertyValue('--accent').trim(), accent2:s.getPropertyValue('--accent2').trim(),
457
+ muted:s.getPropertyValue('--muted').trim(), text:s.getPropertyValue('--text').trim(),
458
+ border:s.getPropertyValue('--border').trim(), glow:s.getPropertyValue('--glow').trim(),
459
+ panel:s.getPropertyValue('--panel-solid').trim()
460
+ };
461
+ }
462
+ function option(){
463
+ var t = tokens();
464
+ return {
465
+ animation: !noAnim,
466
+ grid:{ left:2, right:2, top:18, bottom:18 },
467
+ tooltip:{ trigger:'axis', backgroundColor:t.panel, borderColor:t.border,
468
+ textStyle:{ color:t.text, fontSize:11 },
469
+ formatter:function(p){ return p[0].name + ' · ' + p[0].value + ' 次提交'; } },
470
+ xAxis:{ type:'category', data:MONTHS, axisTick:{ show:false },
471
+ axisLine:{ lineStyle:{ color:t.border } }, axisLabel:{ color:t.muted, fontSize:9 } },
472
+ yAxis:{ type:'value', show:false, max:1200 },
473
+ series:[{ type:'bar', data:VALS, barWidth:'46%',
474
+ itemStyle:{ borderRadius:[3,3,0,0],
475
+ color:new echarts.graphic.LinearGradient(0,0,0,1,[{ offset:0, color:t.accent2 },{ offset:1, color:t.accent }]),
476
+ shadowBlur:10, shadowColor:t.glow } }]
477
+ };
478
+ }
479
+ chart.setOption(option());
480
+ window.__sfEchartsTheme = function(){ chart.setOption(option()); };
481
+ window.addEventListener('resize', function(){ chart.resize(); });
482
+ })();
471
483
  // 主题换肤：五套配色随点随换；记忆上次选择（localStorage，失败静默）；?shot 截图模式隐藏坞
484
+
485
+ /* 稳定身份命名空间：localStorage 键按页内嵌唯一 ID（meta annual-id）命名——Chrome/Safari 下 file:// 与 localhost 共享同源存储，固定键名会导致多份产物互相串台；ID 与文件路径解耦，改名/移动目录记忆不丢 */
486
+ var SF_ID = ((document.querySelector('meta[name="annual-id"]') || {}).content || 'REF-ANNUAL-0000').trim();
487
+ /* ID 格式自愈（格式定死执行层）：meta 非法或缺失（占位残留/手写变体/误沿用旧值）时按路径键自愈为 crypto.randomUUID() 标准 v4，同路径跨打开稳定；合法 UUID 原样使用（复制文件副本=同一身份共享数据，是特性） */
488
+ if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(SF_ID)) {
489
+ var __sfHealKey = 'sf-heal:' + location.pathname;
490
+ try { SF_ID = localStorage.getItem(__sfHealKey) || SF_ID; } catch (e) {}
491
+ if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(SF_ID)) {
492
+ try { SF_ID = crypto.randomUUID(); } catch (e) {
493
+ SF_ID = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c){ var r = Math.random()*16|0, v = c === 'x' ? r : (r&0x3|0x8); return v.toString(16); });
494
+ }
495
+ try { localStorage.setItem(__sfHealKey, SF_ID); } catch (e) {}
496
+ }
497
+ var __sfMeta = document.querySelector('meta[name="annual-id"]');
498
+ if (__sfMeta) __sfMeta.setAttribute('content', SF_ID);
499
+ console.warn('[annual-report] meta annual-id 非法或缺失，已自愈为标准 v4 ID（' + SF_ID + '），建议重新生成页面固化');
500
+ }
501
+
502
+ var SF_NS = 'annual:' + SF_ID;
472
503
  (function(){
473
504
  var THEMES = ['tech','biz','mono','light','warm'];
474
505
  var dock = document.getElementById('themeDock');
@@ -476,9 +507,10 @@ if (location.search.indexOf('shot=content') > -1) {
476
507
  if (location.search.indexOf('shot=') !== -1){ dock.style.display = 'none'; }
477
508
  function apply(t){ document.documentElement.setAttribute('data-theme', t);
478
509
  dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === t); });
479
- try{ localStorage.setItem('sf-report-theme', t); }catch(e){} }
510
+ try{ localStorage.setItem(SF_NS + '-theme', t); }catch(e){}
511
+ if (window.__sfEchartsTheme) window.__sfEchartsTheme(); }
480
512
  var cur = document.documentElement.getAttribute('data-theme');
481
- var saved = null; try{ saved = localStorage.getItem('sf-report-theme'); }catch(e){}
513
+ var saved = null; try{ saved = localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
482
514
  if (saved && THEMES.indexOf(saved) !== -1 && saved !== cur){ apply(saved); }
483
515
  else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on', d.getAttribute('data-theme') === (cur || 'tech')); }); }
484
516
  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click', function(){ apply(d.getAttribute('data-theme')); }); });
package/annual-report/resources/usage-guide.md CHANGED
@@ -45,7 +45,7 @@
45
45
  - 词典外行业走兜底：按骨架 + 你提供的素材现场生成词条；说「记住这个行业」→ 固化为新词条
46
46
 
47
47
  ## 控制落盘（临时要求，仅对当次生效）
48
- - 默认：对话输出 Markdown + md/txt/html 三文件 + 内容区截图 content-png 落盘到 DIR（auto 按系统选：macOS=/Users/luzhaosheng/MyWork/智慧食堂/reports、Windows=d:\Workspace_QCoder\reports，路径以 user-config.md 顶部「默认配置」为准）/annual-YYYY/ + html 自动打开（DIR 目录/盘符不存在时自动改用用户主目录下 reports：macOS=~/reports、Windows=%USERPROFILE%\reports）
48
+ - 默认：对话输出 Markdown + md/txt/html 三文件 + 内容区截图 content-png 落盘到 DIR（auto 按系统选：macOS=~/reports、Windows=%USERPROFILE%\reports，模板默认值，路径以 user-config.md 顶部「默认配置」为准）/annual-YYYY/ + html 自动打开（DIR 目录/盘符不存在时自动改用用户主目录下 reports：macOS=~/reports、Windows=%USERPROFILE%\reports）
49
49
  - 说「写到桌面」→ 本次落盘到桌面（macOS=~/Desktop、Windows=%USERPROFILE%\Desktop）；说「存到 ~/report / D:\report」→ 本次用指定目录（均自动按年度建子目录）
50
50
  - 说「不落盘/别写文件」→ 本次只在对话输出，不写文件、不开浏览器
51
51
  - 说「只要 md」「只出 html」「只要内容区截图」→ 本次只落指定格式文件；说「这次不截图」→ 本次跳过截图（content-png = 五张分节卡片整体一张图，四周约 40px 留白，不含头部标题、复制按钮、页脚）
@@ -58,10 +58,18 @@
58
58
  |---|---|---|
59
59
  | DISK | 是否落盘写文件 | true（落盘，默认）/ false（默认只在对话输出） |
60
60
  | FORMATS | 落盘哪些格式（数组） | [md, txt, html, content-png]（默认，含内容区截图）/ [md, html] / [md, txt, html]（不截图）；content-png = 五张分节卡片整体截图（四周约 40px 留白），不含头部标题/复制按钮/页脚 |
61
- | DIR | 落盘根目录 | auto（按当前系统自动选 DIR_MAC / DIR_WIN，默认）；DIR_MAC = macOS 根目录（/Users/luzhaosheng/MyWork/智慧食堂/reports）；DIR_WIN = Windows 根目录（d:\Workspace_QCoder\reports） |
61
+ | DIR | 落盘根目录 | auto（按当前系统自动选 DIR_MAC / DIR_WIN，默认）；DIR_MAC = macOS 根目录（模板默认 ~/reports，可改）；DIR_WIN = Windows 根目录（模板默认 %USERPROFILE%\reports，可改） |
62
62
  | OPEN_HTML | 落盘后是否自动打开 html | true（自动打开，默认）/ false（不打开） |
63
63
  | TEMPLATE | 报告模板 | default（内置五段式，默认）/ custom（按「📝 自定义模板」节的结构生成） |
64
64
  | ROLE | 默认职业角色画像 | 全栈开发工程师（企业内技术开发）等；职业名 + 括号内工作内容 |
65
65
  | CONFIRM | 落盘前先出效果确认 | never（直接生成不确认，默认）/ text（纯文字整理模式确认）/ always（所有生成都确认） |
66
66
  - 优先级：临时口头要求（不落盘/写到桌面/只要 md/只要内容区截图/这次不截图/别开浏览器/临时换模板等）永远优先于默认配置，仅对当次生效、不改配置
67
67
  - DIR（按系统解析）指向的目录/盘符不存在时，自动回退到用户主目录下 reports（macOS=~/reports、Windows=%USERPROFILE%\reports）
68
+
69
+ ## 效果不对怎么办
70
+
71
+ - 页面效果不对（布局乱 / 样式错 / 交互异常 / 内容显示不全），直接对 AI 说「这个页面效果不对，对照参考模板修复」，把问题描述清楚（哪一节、什么现象，能截图最好）
72
+ - 本技能的设计标准答案就在技能目录里：`resources/reference.html`（双击可直接打开看标准效果），AI 修复时以此为唯一对照
73
+ - AI 的处理流程固定：先打开 reference.html 作标准 → 再读你那份问题 html 文件 → 逐处比对找出跑偏的地方 → 以 reference 为准修复 → 用浏览器自动截图对比修复前后，自证修好了再交付
74
+ - 效果对了但内容不对（数字/条目写错）同样说「内容有误：xxx 应该是 xxx」，AI 只改数据不动版式；参考模板本身有缺陷时（生成结果与 reference 一模一样但仍有问题）说一句「参考模板也有这个问题」，AI 会连模板一起修并同步回 reference.html
75
+ - 修复后想要永久按修复效果生成：说「以后都按这个效果生成」即可
package/annual-report/user-config.md CHANGED
@@ -10,16 +10,28 @@
10
10
 
11
11
  ```yaml
12
12
  DISK: true # 是否落盘写文件；false = 默认只在对话输出，不写文件不开浏览器
13
- CONFIG_VERSION: 2 # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
13
+ CONFIG_VERSION: 3 # 配置结构版本：skill 升级时若配置结构变化会递增；AI 每次执行前对比 SKILL.md「配置版本机制」节声明的当前版本，不一致时按 SKILL.md 的迁移规则处理（先备份本文件为带时间戳 .bak，再迁移，最后对话告知用户）
14
14
  FORMATS: [md, txt, html, content-png] # 落盘哪些格式（数组，可删减/增，如 [md, html] / [md, txt, html]（不截图）；content-png = 内容区截图（五张分节卡片整体，不含头部标题/复制按钮/页脚），删除该项即不截图；不影响对话中的 md 正文输出）
15
15
  DIR: auto # 落盘根目录：auto = 按当前系统自动选 DIR_MAC / DIR_WIN（也可直接写死某个绝对路径）
16
- DIR_MAC: /Users/luzhaosheng/MyWork/智慧食堂/reports # macOS 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录不存在时回退用户主目录下 reports）
17
- DIR_WIN: d:\Workspace_QCoder\reports # Windows 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录/盘符不存在时回退用户主目录下 reports）
16
+ DIR_MAC: ~/reports # macOS 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录不存在时回退用户主目录下 reports）
17
+ DIR_WIN: %USERPROFILE%\reports # Windows 落盘根目录（自动按目标年度建子目录 annual-YYYY；目录/盘符不存在时回退用户主目录下 reports）
18
18
  OPEN_HTML: true # 落盘后是否自动用浏览器打开 html（FORMATS 不含 html 时忽略）
19
- THEME: tech # html 页面主题：tech 深蓝科技（默认）/ biz 浅色商务 / mono IDEA 黑亮 / light IDEA 白亮 / warm 温暖渐变；生成时写 <html data-theme="THEME值"> 定默认，页面右下角换肤坞五色点随点随换（浏览器本地记忆，?shot 截图模式自动隐藏，打印隐藏）
19
+ THEME: tech # html 页面主题：tech 深蓝科技（默认）/ biz 浅色商务 / mono IDEA 黑亮 / light IDEA 白亮 / warm 温暖渐变；生成时写 <html data-theme="THEME值"> 定默认，页面右下角换肤坞五色点随点随换（浏览器本地记忆（键按页内嵌唯一 ID 隔离、多份产物互不串台、改名/移动目录记忆不丢；生成时头部写 `<meta name="annual-id" content="<UUID>">`，每次新 UUID），?shot 截图模式自动隐藏，打印隐藏）
20
20
  TEMPLATE: default # 报告模板：default = 内置五段式（年度概览/核心成果与里程碑/经验与成长/不足与反思/新年展望与规划）；custom = 使用下方「📝 自定义模板」节；口头临时指定模板仅当次生效
21
21
  ROLE: 全栈开发工程师（企业内技术开发） # 用户默认职业角色与主要工作内容（两者并存：职业名 + 括号内工作内容，生成内容/术语/量化指标/里程碑/风险话术全部按此画像走）；用户随口描述职业时（如「我搞装修的，天天跑工地」）→ AI 提炼为规范表述（装修项目经理（负责工地现场管理、施工进度与质量巡检））更新此处；说「以 XX 的身份写」→ 当次临时换角色不改配置；说「以后默认用 XX 角色 / 我的职业是 XX / 我的主要工作是 XX」→ 永久更新此处
22
22
  CONFIRM: never # 落盘前确认：never = 直接生成落盘不确认（默认）；text = 纯文字整理模式先出效果确认后再落盘；always = 任何方式生成都先确认；临时说「先看看效果」当次先确认、说「不用确认」当次跳过
23
+ DATA_SOURCES: [] # 数据源清单（升级不覆盖；AI 每次生成前 Read 本文件按此清单收集；空清单 = 只按会话/文字内容生成）。每项：name 唯一名称 + type 类型 + 路径。三种类型示例（把下方 # 注释示例改成你的真实数据源后填入上方数组；未知 type（拼写错误）忽略该项并在生成时一句话提示，不中断）：
24
+ # - name: 主项目仓库 # 名称：唯一 key（重名视为同一数据源；口述「只聚合 xxx」按 name 匹配）
25
+ # type: git # git = 代码仓库（git log 聚合提交；路径不存在/非代码仓库时静默跳过）
26
+ # mac: ~/Projects/main-app # macOS 路径（绝对路径或 ~ 开头）
27
+ # win: D:\Projects\main-app # Windows 路径；「-」= 该系统不存在，自动跳过
28
+ # - name: 周例会纪要
29
+ # type: file # file = 普通文件/目录（文件 Read 全文、目录逐个 Read 文本文件，二进制跳过；路径无效静默跳过）
30
+ # mac: ~/Documents/meeting-notes.md
31
+ # win: -
32
+ # - name: 数据接口
33
+ # type: remote # remote = 远程网络源（只需 url 字段忽略 mac/win；AI 联网拉取内容提取要点；失败静默跳过不阻塞；仅收集时联网，HTML 产物仍零外链）
34
+ # url: https://example.com/data.json
23
35
  ```
24
36
 
25
37
  > 临时口头要求（仅对当次生效，不修改上方配置）：说「不落盘/别写文件」→ 当次 DISK=false；说「写到桌面/存到 ~/report（macOS）或 D:\report（Windows）」→ 当次改用该 DIR；说「只要 md / 只出 html / 只要内容区截图」→ 当次只落指定格式；说「这次不截图」→ 当次不生成内容区截图；说「只要截图/重新截个图」→ 当次只对现有 html 执行内容区截图（不重新收集数据、不重写 md/txt/html 内容文件）；说「别开浏览器」→ 当次 OPEN_HTML=false；说「这次按 xxx 模板来」→ 当次临时换模板（不改配置）；说「以后都用这个模板」→ 自动写入下方「📝 自定义模板」节并把 TEMPLATE 改为 custom（永久生效）；说「先看看效果/先出效果再落盘」→ 当次先出效果确认后再落盘；说「不用确认/直接落盘」→ 当次跳过确认直接落盘。说「页面用浅色商务主题/浅色主题」→ 当次 THEME=biz；说「以后默认用暖色主题」→ 永久改 THEME=warm。
package/article-to-html/.preserve ADDED
@@ -0,0 +1,3 @@
1
+ # 升级时永不覆盖的用户可改文件（每行一个文件名，# 注释）
2
+ # 官方版有更新时另存 .upstream 对照，供手动合并
3
+ design-system.md
package/article-to-html/SKILL.md CHANGED
@@ -13,11 +13,11 @@ Turn any Word/Markdown/plain-text article into a standalone styled HTML page and
13
13
 
14
14
  ## ⚙️ 配置与自定义主题
15
15
 
16
- **执行本 skill 前必须先 Read 同目录 `user-config.md`**：`THEME` 配置决定 A 款页面的默认主题色（tech 科技蓝 / gold 暖棕金 / forest 墨绿 / plum 梅紫）。升级技能时 user-config.md 不会被覆盖，你的修改永久保留。
16
+ **执行本 skill 前必须先 Read 同目录 `user-config.md`**：`THEME` 配置决定 A 款页面的默认主题色（tech 科技蓝 / gold 暖棕金 / forest 墨绿 / plum 梅紫）；`DIR` 配置决定产物落盘根目录（auto 按系统选 DIR_MAC/DIR_WIN，目录不存在时回退用户主目录，用户口头指定目录永远优先）。升级技能时 user-config.md 不会被覆盖，你的修改永久保留。
17
17
 
18
18
  ## 配置版本机制（升级保护）
19
19
 
20
- 本 skill 当前配置版本为 `1`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明不一致：
20
+ 本 skill 当前配置版本为 `2`（对应 user-config.md 中的 `CONFIG_VERSION`）。执行时若发现 user-config.md 的 CONFIG_VERSION 与本节声明不一致：
21
21
  1. 将旧 user-config.md 备份为 `user-config.md.bak-<时间戳>`
22
22
  2. 保留用户全部自定义字段，按本节「当前版本变更记录」逐项改写旧字段
23
23
  3. 更新 CONFIG_VERSION 为当前版本
@@ -27,7 +27,12 @@ Turn any Word/Markdown/plain-text article into a standalone styled HTML page and
27
27
 
28
28
  **无法迁移项处理**（值域失效 / 语义漂移 / 数据不兼容）：三情形——①旧值不在新值域（如旧模板/主题名已移除）②同名键含义变化（单位/枚举变更）③数据文件 schema 不兼容。三绝不：绝不静默（无法迁移项停下问，不猜值）、绝不丢失（旧值永远在 .bak-时间戳）、一次说清（升级报告三段式：⚠️ 版本与备份路径 → ✅ 已自动迁移清单 → 🟡 无法迁移项逐条附原因+影响+建议替代）；随后 AskUserQuestion 三选项（A 用建议值 / B 用户给新值 / C 保持旧配置——不更新 CONFIG_VERSION，每次执行再提醒）；报告必附回滚一句话；数据文件迁移前先复制 .bak-时间戳，能映射则映射、不能则写兼容层或留备份提示手动整理
29
29
 
30
- 当前版本变更记录：暂无（初始版本 1，含 THEME 字段）。
30
+ 当前版本变更记录：
31
+ - v1→v2：新增 `DIR: auto` + `DIR_MAC: ~/articles` + `DIR_WIN: %USERPROFILE%\articles`（产物落盘根目录，auto 按系统选、目录不存在回退用户主目录、口头指定优先）；其余字段不变。
32
+
33
+ ## 产物升级（回炉）
34
+
35
+ 生成 HTML 时头部写版本戳 `<meta name="sf-template" content="article-to-html@2">`（模板升级时递增 @N 并同步 reference.html 与本文档）。用户说「升级旧产物/回炉旧页面/旧文章页换新样式」时：扫落盘目录下本技能生成的 html，读版本戳筛出旧版（无版本戳或缺少 `<meta name="article-id">` 稳定 ID 的产物视为 v0 最旧版，一并进清单）→ 列清单（文件/旧版本/手改状态——html 与同目录 md 底稿正文对比，不一致视为可能手改过；无 md 底稿时标记「无法比对」）→ AskUserQuestion 选全部或部分 → 逐份升级：浅升级（仅 CSS/JS 变化）对旧页替换 `<style>` 块与交互脚本、正文内容原样保留；深升级（DOM 结构变化）从 md 底稿按当前 reference.html 重建（无 md 底稿则提取旧 html 正文重建），先备份旧版 `.bak-时间戳` → 报告三段式：✅ 已升级清单 / ⚠️ 手改保留说明 / 🟡 失败项原因。模板改动分级：业务改动（板块/段落/标题体系）、数据格式改动（字段/存储结构）、页面改动（样式/布局/交互）任一发生即模板升级，版本戳 +1 并同步 reference.html 与本文档；纯措辞润色不 bump。每次生成 HTML 时顺扫落盘目录读版本戳：发现旧版产物（vN-1 或无版本戳的历史产物）主动告知「技能模板已升级至 vN，检测到 X 份旧版文章页，说『把我旧文章页都升级成新样式』即可一键升级」，不让用户背触发语。
31
36
 
32
37
  ## Prerequisites（新用户准备）
33
38
 
@@ -86,12 +91,13 @@ Turn any Word/Markdown/plain-text article into a standalone styled HTML page and
86
91
  - 通读解析出的内容，判断文章气质（科技 / 文艺 / 教程 / 科普 / 报道 / 商业等），从 [design-system.md](design-system.md)「0. 风格菜单」的六款版式中选一款
87
92
  - 默认款（暗色封面长文风）适用于大多数科技 / 产品文；文艺散文选文艺排版风；教程干货选极简白；硬核技术选终端极客风；科普清单选卡片流；深度报道选报纸分栏
88
93
  - 拿不准或用户有明确偏好时，用 AskUserQuestion 让用户在 2-4 款候选里挑（每款附一句话气质描述），不替用户做有风格争议的决定
89
- - A 款页面主题色默认取 user-config.md 的 `THEME` 值写入 `<html data-theme>`，页面右下角换肤坞四色点随点随换（浏览器本地记忆）
94
+ - A 款页面主题色默认取 user-config.md 的 `THEME` 值写入 `<html data-theme>`，页面右下角换肤坞四色点随点随换（浏览器本地记忆，键按页内嵌唯一 ID 隔离、多份产物互不串台、改名/移动目录记忆不丢（生成时头部写 `<meta name="article-id" content="<UUID>">`，每次 crypto.randomUUID() 生成标准 UUID v4（8-4-4-4-12 十六进制，禁止手写变体、禁止沿用占位与旧值）；落盘写文件前顺扫落盘目录下本技能命名的 html，读各文件 id meta 查重，撞号重掷至不重复））
90
95
  - 任何风格都不许引入第三个字体：文艺排版风同样只用思源黑体，文艺感靠排版营造（大行距、留白、首字下沉、细分割线），不得改用宋体
91
96
  - 无论哪款风格：字体白名单锁死（Roboto + 思源黑体）、零兜底、第 3.5 步核查照跑
92
97
 
93
98
  ### 3. Build the HTML
94
99
 
100
+ - **先 Read `resources/reference.html`**（A 款骨架与 18 组件全集，设计真相源）再动手——骨架结构、组件用法、主题令牌以 reference.html 为准，与 design-system.md 冲突时 reference.html 说了算
95
101
  - 先写入当前工作区（如 `outputs/<标题>.html`），完成后用 Bash `cp` 到用户目标目录——Write 工具被沙盒限制在工作区内
96
102
  - 大文件分片写：Write 创建文件（head + 封面 + 前几章），后续用 SearchReplace 以文件末尾 `</section>\n</div>\n</body>\n</html>` 为锚点追加章节
97
103
  - 使用 [design-system.md](design-system.md) 中的 CSS 变量与组件模式；源文档中每张图表必须有对应的 HTML/CSS 组件；表格 `td` 一律 `vertical-align:middle`
@@ -158,7 +164,7 @@ grep -nE "PingFang|YaHei|apple-system|sans-serif|serif|monospace|SF Mono|Menlo|M
158
164
  - 截图对象：封面 `.hero` + `.wrap` 内每个 `section`（引言 + 各章 + 写在最后 + 作者），一章节一张
159
165
  - **统一宽度**：JS 注入 `.hero` → `width:730px;margin:0 auto;padding:112px 16px 104px;box-sizing:border-box`；每个 section → `padding:72px 16px 24px`；DPR=2 时所有图宽度一致（1460px）
160
166
  - 元素级截图，截前先 `scrollIntoView`；四周 16px 内边距保证 box-shadow 阴影完整显示
161
- - 命名与顺序：`C00-封面.png`、`C00-引言.png`、`C01-<章节短名>.png` … `C13-作者介绍.png`，保存到 `<目标目录>/文章截图/章节截图/`
167
+ - 命名与顺序：`C00-封面.png`、`C00-引言.png`、`C01-<章节短名>.png` … `C13-作者介绍.png`，保存到 `<目标目录>/文章截图/<标题slug>/`（slug 用简洁英文或拼音；每篇文章一个目录，多篇文章截图互不覆盖；同一目标目录下已有同 slug 目录时对话确认归属，同名不同篇则 slug 追加 -2/-3 序号）
162
168
  - 若子代理报浏览器窗口不可见（`NATIVE_BROWSER_VIEWPORT_UNAVAILABLE`），请用户把浏览器窗口置前，然后重新派发子代理；不要无限重试
163
169
 
164
170
  - **窗口不可见时的 headless 兜底**（三轮置前失败后直接走此路，无需可见窗口）：
@@ -187,7 +193,7 @@ grep -nE "PingFang|YaHei|apple-system|sans-serif|serif|monospace|SF Mono|Menlo|M
187
193
  - 等价于「更新模式」的「仅改样式保留内容」：只动 CSS（配色/间距/字号/组件样式），不动正文；若外来 HTML 缺章节骨架，可顺手改造成自家骨架（文字不动）
188
194
  - **每轮调整后重跑第 3.5 步核查**，防调整引入新字体污染
189
195
  - 第 4.5 步双确认闭环照跑：美化完先 RunPreview 问满意，点头才进入截图；至多 3 轮
190
- - 美化 A 款自家骨架时保留换肤坞（坞 HTML + 坞 JS + [data-theme] 块）；被误删时按 design-system.md 骨架模板补装
196
+ - 美化 A 款自家骨架时保留换肤坞（坞 HTML + 坞 JS + [data-theme] 块）；被误删时按 reference.html 的坞 HTML/坞 JS 补装
191
197
  - 美化定稿后用户要截图 → 转 6.3；单文件版如需要，用 inline_fonts.py 重铸
192
198
 
193
199
  **6.3 只截图**
@@ -203,15 +209,28 @@ grep -nE "PingFang|YaHei|apple-system|sans-serif|serif|monospace|SF Mono|Menlo|M
203
209
 
204
210
  ## Output conventions
205
211
 
212
+ <目标目录> = 用户口头指定的目录；未指定时取 user-config.md 的 DIR（auto 按系统选 DIR_MAC/DIR_WIN，目录不存在时回退用户主目录）。
213
+
206
214
  ```
207
215
  <目标目录>/
208
216
  ├── <标题>.html # 标准版（依赖 assets/fonts）
209
217
  ├── <标题>-单文件版.html # 字体全内嵌，双击即开
210
218
  ├── assets/fonts/roboto-latin-{400,500,700,900}-normal.woff2
211
- └── 文章截图/章节截图/
219
+ └── 文章截图/<标题slug>/ # 每篇文章一个目录，互不覆盖
212
220
  ├── C00-封面.png C00-引言.png C01-*.png … C13-作者介绍.png
213
221
  ```
214
222
 
223
+
224
+ ## 🔧 报修处理流程（用户报页面问题时）
225
+
226
+ 用户说「页面 / 截图效果不对 / 第 X 章有 XX 问题 / 布局乱了」（常附截图或指出具体现象）→ 按以下流程处理：
227
+
228
+ 1. **立标准**：先 Read `resources/reference.html`——A 款骨架与组件全集就是本 skill 的设计真相源；六款版式参数对照根目录 `design-system.md`；两者冲突以 reference.html 为准
229
+ 2. **找问题**：Read 那份问题 html，对照 design-system.md 逐处比对（版式结构 / --accent 令牌 / 字体白名单 / 图表组件），定位跑偏处；用户给了截图则按截图现象反查
230
+ 3. **修复**：以 design-system.md 为准修复（只修跑偏处）；改完重跑「3.5 交付前零侵权核查」grep 扫描——任何字体污染命中必须清零
231
+ 4. **自证**：按第 5 步规格重截问题章节（1460px 统一宽度），Read 自查恢复标准效果；用户给了问题截图时尽量复现同视角截图做前后对比
232
+ 5. **汇报**：一句话说清问题根因 + 修复了什么 + 附截图；若根因在 design-system.md 或 reference.html 自身（版式规范本身有缺陷），顺修这两个文件保持同步（reference.html 是真相源）并在汇报中说明「设计标准已同步修正」
233
+
215
234
  ## Pitfalls
216
235
 
217
236
  1. **Write 沙盒限制**：工作区外无法直接 Write → 写工作区 `outputs/` 再 `cp` 到目标目录
package/article-to-html/design-system.md CHANGED
@@ -2,6 +2,8 @@
2
2
 
3
3
  本文件提供文章 HTML 的设计系统：CSS 变量 + 组件类名 + 关键样式片段。执行时按需复制到 `<style>` 中，并根据文章内容裁剪不需要的组件。
4
4
 
5
+ > ⚠️ **真相源铁律**：本文件与 `resources/reference.html` 构成双轨——reference.html 是 A 款完整组装示范（骨架 + 18 组件实例 + 换肤坞），本文件提供六款版式参数与裁剪说明。生成 / 修复任何 A 款页面前必须先 Read 两份，**冲突以 reference.html 为准**；修改 CSS 时两份必须同步更新。
6
+
5
7
  ## 0. 风格菜单（构建前按文章气质选一款）
6
8
 
7
9
  六款版式范式，每款给适用气质与关键参数。选定后其余章节的组件按需裁剪。字体白名单锁死为 Roboto + 思源黑体，任何风格都不许引入其他字体。
@@ -378,7 +380,7 @@ td.hl{font-weight:700;color:var(--ink)}
378
380
  <meta charset="UTF-8">
379
381
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
380
382
  <title>文章标题</title>
381
- <style>/* 按需复制上面的变量与组件样式（A 款含四主题 data-theme 块与换肤坞 CSS） */</style>
383
+ <style>/* 按需复制上面的变量与组件样式（A 款含四主题 data-theme 块与换肤坞 CSS）；完整组装示范见 resources/reference.html */</style>
382
384
  </head>
383
385
  <body>
384
386
  <div class="hero">…封面…</div>
@@ -400,6 +402,10 @@ td.hl{font-weight:700;color:var(--ink)}
400
402
  </div>
401
403
  <script>
402
404
  /* 主题换肤：html[data-theme] 切换 + 记忆上次选择（localStorage，失败静默）；?shot 截图模式隐藏坞 */
405
+
406
+ /* 稳定身份命名空间：localStorage 键按页内嵌唯一 ID（meta article-id）命名——Chrome/Safari 下 file:// 与 localhost 共享同源存储，固定键名会导致多份产物互相串台；ID 与文件路径解耦，改名/移动目录记忆不丢 */
407
+ var SF_ID = ((document.querySelector('meta[name="article-id"]') || {}).content || 'ref-article').trim();
408
+ var SF_NS = 'article:' + SF_ID;
403
409
  (function(){
404
410
  var THEMES=['tech','gold','forest','plum'];
405
411
  var dock=document.getElementById('themeDock');
@@ -408,11 +414,11 @@ td.hl{font-weight:700;color:var(--ink)}
408
414
  function apply(t){
409
415
  document.documentElement.setAttribute('data-theme',t);
410
416
  dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on',d.getAttribute('data-theme')===t); });
411
- try{ localStorage.setItem('sf-article-theme',t); }catch(e){}
417
+ try{ localStorage.setItem(SF_NS + '-theme',t); }catch(e){}
412
418
  }
413
419
  var cur=document.documentElement.getAttribute('data-theme');
414
420
  var saved=null;
415
- try{ saved=localStorage.getItem('sf-article-theme'); }catch(e){}
421
+ try{ saved=localStorage.getItem(SF_NS + '-theme') || localStorage.getItem('sf:' + location.pathname + '-theme'); }catch(e){}
416
422
  if(saved && THEMES.indexOf(saved)!==-1 && saved!==cur){ apply(saved); }
417
423
  else{ dock.querySelectorAll('.th-dot').forEach(function(d){ d.classList.toggle('on',d.getAttribute('data-theme')===(cur||'tech')); }); }
418
424
  dock.querySelectorAll('.th-dot').forEach(function(d){ d.addEventListener('click',function(){ apply(d.getAttribute('data-theme')); }); });