feat(cypher-executor): magic vars {{_today}} / {{_iso_week}} / {{_now}} 等

對應 LI SDD M2.x improvement,源自 Claude (我) 透過 arcrun_report_feedback
寫的 feedback block c47bf70b 提的「需要內建變數展開」需求。完整閉環:

  AI 用 MCP tool 報 bug → KBDB 收 feedback → AI 自己看 → 自己修補 → deploy

新增 cypher-executor/src/lib/magic-vars.ts:
  - _today / _yesterday / _now / _now_unix / _now_unix_s
  - _iso_week (2026-W20) / _iso_week_num / _iso_year
  - _yyyymm / _yyyymmdd
  - _year / _month / _day / _hour / _minute / _second(zero-padded)
  - _weekday (0-6, 0=日) / _iso_weekday (1-7, 1=一)
  全部 UTC,避免 worker 跨時區誤判

GraphExecutor.execute() 入口注入:
  ctxWithMagic = { ...initialContext, ...buildMagicVars() }
  順序確保 magic vars 永遠 win(防 user 不小心用 _ prefix)

不違反 §2.2(cypher-executor TS 禁實作 secret/JWT 業務邏輯):
  magic vars 是公開時間常數,跟既有 interpolateString 的 ctx 變數展開
  同層,純 orchestrator routing 職責。

AGENTS.md §10.5 加 magic vars 完整表 + weekly archive 範例。

實測(commit 後 deploy + 觸發 weekly_review):
  - KBDB 新建 roadmap-2026-W20 block 正確展開 page_name
  - roadmap-latest 同步更新(雙寫 pattern)
  - 證明 weekly archive 從此真能累積歷史,不再固定 latest 覆蓋

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
2026-05-16 21:20:52 +08:00
parent ef406d714a
commit 8e985684f9
3 changed files with 131 additions and 3 deletions
+30
View File
@@ -255,6 +255,36 @@ config:
---
## 10.5 內建 magic vars`_` prefix reserved
YAML 內可直接用以下變數,cypher-executor 自動展開為當下時間(UTC):
| 變數 | 範例 | 用途 |
|---|---|---|
| `{{_today}}` | `2026-05-16` | 日 log / page_name |
| `{{_yesterday}}` | `2026-05-15` | digest 取昨日 |
| `{{_now}}` | `2026-05-16T09:30:00.123Z` | ISO 8601 |
| `{{_now_unix}}` | `1778937000123` | unix ms |
| `{{_now_unix_s}}` | `1778937000` | unix sec |
| `{{_iso_week}}` | `2026-W20` | weekly archive (本 doc 推薦) |
| `{{_iso_week_num}}` / `{{_iso_year}}` | `20` / `2026` | 拆開用 |
| `{{_yyyymm}}` / `{{_yyyymmdd}}` | `202605` / `20260516` | 緊湊路徑 |
| `{{_year}}` / `{{_month}}` / `{{_day}}` / `{{_hour}}` / `{{_minute}}` | 各別 zero-padded | 自己拼路徑 |
| `{{_weekday}}` | `0`-`6`0=日)| if-control |
| `{{_iso_weekday}}` | `1`-`7`1=一)| ISO 風格 |
**rule**`_` prefix reserved for system**用戶自己 ctx 變數不要用 `_` 開頭**。
**範例**weekly archive
```yaml
publish_roadmap_archive:
component: kbdb_upsert_block
page_name: "roadmap-{{_iso_week}}" # roadmap-2026-W20
tags_json: '["weekly", "week:{{_iso_week}}"]'
```
---
## 11. 給寫 LI 的 AI 自己的 meta-規範
你(AI)在寫 arcrun workflow 時,**遵守以下習慣**會少踩坑: