#!/usr/bin/env python3 """Generate to-be delta SVGs (module/flow/sequence) per fireworks-tech-graph rules. Delta colors: green=#d4edda (added) / amber=#fff3cd (modified) / red=#ffe0e0 (removed). """ import os ARD = '#155724' # green stroke AMB = '#856404' # amber stroke RED = '#c62828' # red stroke def gen_module_delta(): W, H = 1280, 760 NW, NH = 180, 56 CLW = 220 L = [] emit = L.append emit('' % (W, H)) emit(' ') emit(' ') emit(' ' % ARD) emit(' ') emit(' ') emit(' ' % (W, H)) emit(' to-be · module delta · ++ added / ~ modified / -- removed') TK_X, TK_Y, TK_W, TK_H = 40, 70, 580, 600 emit(' ' % (TK_X, TK_Y, TK_W, TK_H)) emit(' harness-rd-toolkit (source)' % (TK_X+12, TK_Y+22)) CL_X, CL_Y, CL_W, CL_H = 700, 70, 540, 600 emit(' ' % (CL_X, CL_Y, CL_W, CL_H)) emit(' 客户端项目 (targetDir)' % (CL_X+12, CL_Y+22)) # Nodes cli_x, cli_y = 80, 120 # ~ ini_x, ini_y = 340, 120 # unchanged upd_x, upd_y = 340, 220 # ~ ver_x, ver_y = 80, 220 # ~ newcheck_x, newcheck_y = 80, 320 # ++ (added) newstate_x, newstate_y = 340, 320 # ++ (added) protected_x, protected_y = 80, 430 # ++ (added, internal helper) guided_x, guided_y = 340, 430 # ++ (added, internal helper) claude_x, claude_y = 760, 120 set_x, set_y = 760, 210 ctx_x, ctx_y = 760, 300 cfg_x, cfg_y = 760, 390 stamp_x, stamp_y = 760, 480 stamp_w, stamp_h = 220, 80 force_x, force_y = 760, 580 force_w, force_h = 220, 60 def R(x,y,w,h): return (x+w, y+h//2) def LE(x,y,w,h): return (x, y+h//2) def T(x,y,w,h): return (x+w//2, y) def B(x,y,w,h): return (x+w//2, y+h) # ===== EDGES (all green for added connections) ===== # cli --update-check--> newcheck sx,sy = B(cli_x,cli_y,NW,NH); ex,ey = T(newcheck_x,newcheck_y,NW,NH) emit(' ' % (sx,sy,ex,ey,ARD)) emit(' ++ update-check' % (sx+8, (sy+ey)//2)) # cli --guided update--> upd sx,sy = R(cli_x,cli_y,NW,NH); ex,ey = LE(upd_x,upd_y,NW,NH) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey,'#856404')) emit(' ~ guided update' % (mx+8, (sy+ey)//2)) # cli --version--> ver sx,sy = B(cli_x,cli_y+20,NW,NH); ex,ey = T(ver_x,ver_y,NW,NH) if False else (ver_x+NW//2, ver_y) # actually cli is above ver emit(' ' % (cli_x+NW//2, cli_y+NH, ver_x+NW//2, ver_y, '#856404')) emit(' ~ version 对照' % (cli_x+NW+8, (cli_y+NH+ver_y)//2)) # newcheck -> newstate (added edge) sx,sy = B(newcheck_x,newcheck_y,NW,NH); ex,ey = T(newstate_x,newstate_y,NW,NH) # route diagonally emit(' ' % (sx,sy,(sx+ex)//2,sy+30,(sx+ex)//2,sy+30,ARD)) # simpler: newcheck reads newstate emit(' ' % (newcheck_x+NW, newcheck_y+NH//2, (newcheck_x+NW+newstate_x)//2, newcheck_y+NH//2, (newcheck_x+NW+newstate_x)//2, newstate_y+NH//2, newstate_x, newstate_y+NH//2, ARD)) emit(' ++ 读 state' % ((newcheck_x+NW+newstate_x)//2-30, newcheck_y+NH//2-6)) # upd -> newstate sx,sy = B(upd_x,upd_y,NW,NH); ex,ey = T(newstate_x,newstate_y,NW,NH) emit(' ' % (sx,sy,ex,ey,ARD)) emit(' ++ 读/写 state' % (sx+8, (sy+ey)//2)) # upd -> protected (++) sx,sy = B(upd_x,upd_y+20,NW,NH); ex,ey = T(protected_x,protected_y,NW,NH) if False else (upd_x+NW//2, protected_y) # upd above protected (different column); protected is below newcheck, upd is at column 1 emit(' ' % (upd_x, upd_y+NH, upd_x, (upd_y+NH+protected_y)//2, protected_x+NW, (upd_y+NH+protected_y)//2, protected_x+NW, protected_y+NH//2, ARD)) emit(' ++ uses' % ((upd_x+protected_x+NW)//2-30, (upd_y+NH+protected_y)//2-6)) # upd -> guided (++) sx,sy = B(upd_x,upd_y+40,NW,NH); ex,ey = T(guided_x,guided_y,NW,NH) emit(' ' % (sx,sy,ex,ey,ARD)) emit(' ++ entrypoint' % (sx+8, (sy+ey)//2)) # upd -> client (modified sync, amber) sx,sy = R(upd_x,upd_y,NW,NH); ex,ey = LE(cfg_x,cfg_y,CLW,NH) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey,'#856404')) emit(' ~ 受清单约束同步' % (mx+8, sy-6)) # upd -> settings (unchanged union merge) sx,sy = R(upd_x,upd_y+15,NW,NH); ex,ey = LE(set_x,set_y,CLW,NH) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey)) emit(' union merge (不变)' % (mx+8, sy+18)) # upd -> CLAUDE (red dashed -- force 无效) sx,sy = R(upd_x,upd_y-15,NW,NH); ex,ey = LE(claude_x,claude_y,CLW,NH) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey,RED)) emit(' ++ 受保护: 逐项确认' % (mx+8, ey-6)) # upd -> ctx (++) sx,sy = R(upd_x,upd_y+30,NW,NH); ex,ey = LE(ctx_x,ctx_y,CLW,NH) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey,ARD)) emit(' ++ 受保护逐项' % (mx+8, ey+18)) # newstate -> stamp (++) sx,sy = R(newstate_x,newstate_y,NW,NH); ex,ey = LE(stamp_x,stamp_y,stamp_w,stamp_h) mx = (sx+ex)//2 emit(' ' % (sx,sy,mx,sy,mx,ey,ex,ey,ARD)) emit(' ++ 读写' % (mx+8, (sy+ey)//2)) # ===== NODES ===== def node(x,y,w,h,fill,stroke,label,sub=None,lbl_fill='#0f172a',sub_fill='#475569',sw=1.6,dash=None,tag=None): d = ' stroke-dasharray="%s"' % dash if dash else '' emit(' ' % (x,y,w,h,fill,stroke,sw,d)) if tag: emit(' %s' % (x+6, y-4, stroke, tag)) cy = y + h//2 if sub: emit(' %s' % (x+w//2, cy-4, lbl_fill, label)) emit(' %s' % (x+w//2, cy+12, sub_fill, sub)) else: emit(' %s' % (x+w//2, cy+5, lbl_fill, label)) # toolkit nodes node(cli_x, cli_y, NW, NH, '#fff3cd', AMB, 'cli.ts', '+ update-check 子命令', tag='~') node(ini_x, ini_y, NW, NH, '#ffffff', '#3b82f6', 'init.ts', '不变', sw=1.3) node(upd_x, upd_y, NW, NH, '#fff3cd', AMB, 'update.ts', '+ ProtectedRegistry + guided', tag='~') node(ver_x, ver_y, NW, NH, '#fff3cd', AMB, 'version.ts', '+ compareVersions / resolveRemote', tag='~') node(newcheck_x, newcheck_y, NW, NH, '#d4edda', ARD, 'update-check.ts', 'runUpdateCheck (纯读)', tag='++') node(newstate_x, newstate_y, NW, NH, '#d4edda', ARD, 'client-state.ts', '读写 .harness-toolkit-state/', tag='++') node(protected_x, protected_y, NW, NH, '#d4edda', ARD, 'ProtectedRegistry', 'CLAUDE/settings/CONTEXT', tag='++', sw=1.6) node(guided_x, guided_y, NW, NH, '#d4edda', ARD, 'guidedUpdateFlow()', '双重确认入口', tag='++') # client nodes node(claude_x, claude_y, CLW, NH, '#ffffff', '#f57c00', 'CLAUDE.md', '(++, 受保护, --force 无效)') node(set_x, set_y, CLW, NH, '#ffffff', '#f57c00', '.claude/settings.json', '(字段 union, 不变)') node(ctx_x, ctx_y, CLW, NH, '#ffffff', '#f57c00', 'CONTEXT.md', '(++, 受保护逐项)') node(cfg_x, cfg_y, CLW, NH, '#ffffff', '#f57c00', 'pipeline*.yaml / gates / skills', '(逐项 y/N)') node(stamp_x, stamp_y, stamp_w, stamp_h, '#d4edda', ARD, '.harness-toolkit-state/', 'installed-version / deletions.txt / last-sync-at', tag='++') # force constraint callout emit(' ' % (force_x, force_y, force_w, force_h, AMB)) emit(' --force 行为变更' % (force_x+force_w//2, force_y+18, AMB)) emit(' -- 受保护文件无效 (RejectForce)' % (force_x+force_w//2, force_y+34, AMB)) emit(' ++ 非受保护文件 --force 仍可' % (force_x+force_w//2, force_y+50, '#155724')) # Legend LG_Y = H - 56 emit(' ' % LG_Y) emit(' Legend:' % (LG_Y+26)) items = [('#d4edda', ARD, '++ added'), ('#fff3cd', AMB, '~ modified'), ('#ffe0e0', RED, '-- removed (虚线)'), ('#ffffff', '#3b82f6', 'unchanged')] lx = 130 for fill, stroke, txt in items: dash = ' stroke-dasharray="3 2"' if 'removed' in txt else '' emit(' ' % (lx, LG_Y+14, fill, stroke, dash)) emit(' %s' % (lx+24, LG_Y+26, txt)) lx += 180 emit('') p = 'docs/4plus1/delta/client-update-flow/to-be/rendered/module-delta.svg' with open(p, 'w', encoding='utf-8') as f: f.write('\n'.join(L)) print('module-delta written lines=%d size=%d' % (len(L), os.path.getsize(p))) def gen_flow_delta(): W, H = 1280, 1080 L = [] emit = L.append emit('' % (W, H)) emit(' ') emit(' ') emit(' ' % ARD) emit(' ' % AMB) emit(' ') emit(' ') emit(' ' % (W, H)) emit(' to-be · flow delta · ++ added / ~ modified') # notify lane (++) emit(' 提示链路 (++)' % ARD) notify_nodes = [ (40, 100, 220, 50, '++ update-check (SessionStart hook)'), (300, 100, 220, 50, '++ compareVersions(state)'), (560, 100, 220, 50, '++ 注入 session 提示'), (820, 100, 220, 50, '++ 用户看到提示'), ] emit(' ' % ARD) for i, (x,y,w,h,lbl) in enumerate(notify_nodes): emit(' ' % (x,y,w,h)) emit(' %s' % (x+w//2, y+h//2+5, lbl)) if i < len(notify_nodes)-1: nx = notify_nodes[i+1] emit(' ' % (x+w, y+h//2, nx[0], nx[1]+nx[3]//2, ARD)) # guided update flow (~) emit(' 引导式 update (~)' % AMB) emit(' ' % AMB) guided_nodes = [ (40, 240, 220, 50, 'plain', 'harness-toolkit update', ''), (300, 240, 220, 50, 'added', '++ precheck + 读 state', '), (560, 240, 240, 50, 'added', '++ 引导总览 (++/~/-- 清单)', ''), (840, 240, 220, 50, 'added', '++ "确认进入同步?"', '需求: 客户点击确认'), (1080, 240, 140, 50, 'added', '用户 yes', ''), (40, 320, 220, 60, 'modified', '~ syncOneFile', '+ProtectedRegistry +deletions'), (300, 320, 220, 60, 'added', '++ dest 缠失? E deletions', '命中 -> skipped-user-deleted'), (560, 320, 220, 60, 'plain', 'dest -- src?', ''), (840, 320, 220, 60, 'added', '++ Protected?', 'CLAUDE/settings/CONTEXT'), (40, 410, 220, 60, 'modified', '~ settings.*: 字段 union', '不删项 (不变)'), (300, 410, 220, 60, 'added', '++ CLAUDE/CONTEXT 逐项', '--force 无效 (RejectForce)'), (560, 410, 220, 60, 'added', '++ 其他文件逐项', '--force 可自动 yes'), (840, 410, 220, 60, 'added', '++ 应用之前再问', '"按以上决策应用?"'), (40, 510, 220, 50, 'added', '++ 用户否认 -> 0 改动', ''), (300, 510, 220, 50, 'added', '++ 用户否认 -> 0 改动', ''), (560, 510, 220, 50, 'added', '++ 写文件 + 写 state', 'installed-version = toolkitVer'), (840, 510, 220, 50, 'modified', '~ formatUpdateReport', '+ state diff'), ] # Edges (drawn first) edges = [ # (x1,y1, x2,y2, color, marker, dash=None, elab=None) (260,265, 300,265, '#475569', 'arr', None, None), (520,265, 560,265, ARD, 'arrG', None, '++ precheck'), (800,265, 840,265, ARD, 'arrG', None, None), (1060,265, 1080,265, ARD, 'arrG', None, None), (150,290, 150,320, '#475569', 'arr', None, None), (260,350, 300,350, '#475569', 'arr', None, None), (520,350, 560,350, '#475569', 'arr', None, None), (780,350, 840,350, '#475569', 'arr', None, None), (150,380, 70,410, '#475569', 'arr', '4 3', None), # to settings path (routing simplified) (410,380, 410,410, ARD, 'arrG', None, None), (620,380, 410,410, ARD, 'arrG', None, None), (150,470, 150,510, ARD, 'arrG', None, None), (410,470, 670,510, ARD, 'arrG', None, None), (950,470, 950,510, ARD, 'arrG', None, None), ] for x1,y1,x2,y2,c,mk,dash,elab in edges: d = ' stroke-dasharray="%s"' % dash if dash else '' emit(' ' % (x1,y1,x2,y2,c,mk,d)) if elab: emit(' %s' % ((x1+x2)//2-20, (y1+y2)//2-6, elab)) # Then draw nodes for (x,y,w,h,cls,lbl,sub) in guided_nodes: emit(' ' % (x,y,w,h,cls)) if sub: emit(' %s' % (x+w//2, y+h//2-4, lbl)) emit(' %s' % (x+w//2, y+h//2+12, sub)) else: emit(' %s' % (x+w//2, y+h//2+5, lbl)) # Legend LG_Y = H - 56 emit(' ' % LG_Y) emit(' Legend:' % (LG_Y+26)) items = [('#d4edda', ARD, '++ added'), ('#fff3cd', AMB, '~ modified'), ('#ffffff', '#3b82f6', 'unchanged')] lx = 130 for fill, stroke, txt in items: emit(' ' % (lx, LG_Y+14, fill, stroke)) emit(' %s' % (lx+24, LG_Y+26, txt)) lx += 180 emit('') p = 'docs/4plus1/delta/client-update-flow/to-be/rendered/flow-delta.svg' with open(p, 'w', encoding='utf-8') as f: f.write('\n'.join(L)) print('flow-delta written lines=%d size=%d' % (len(L), os.path.getsize(p))) def gen_sequence_delta(): lanes = [ ('用户/Claude', 80), ('++ update-check', 240), ('++ client-state', 390), ('~ update.ts', 540), ('init.ts', 690), ('++ version.ts', 840), ('客户端 FS', 990), ] messages = [ ('++ runUpdateCheck (SessionStart hook)', 0, 1, False, True), ('++ readState', 1, 2, False, True), ('读 installed-version', 2, 6, False, True), ('stamp', 6, 2, True, True), ('++ compareVersions -> hasUpdate', 2, 5, True, True), ('++ 注入提示到 session', 1, 0, False, True), ('harness-toolkit update (用户看到提示后)', 0, 3, False, False), ('++ readState + deletions', 3, 2, False, True), ('全量 hash 扫描', 3, 6, False, False), ('文件清单 + hash', 6, 3, True, False), ('++ 引导总览: N 更新 / M 冲突 / K 受保护 / L 删除戳记', 3, 0, False, True), ('++ "确认进入同步?" (Q3 双重确认之一)', 3, 0, False, True), ('++ yes', 0, 3, False, True), ('loop 每个待同步文件:', -1, -1, False, False), # marker line ('++ dest 缺失 E deletions -> skipped-user-deleted', 3, 6, False, True), ('++ settings.* -> 字段 union merge', 3, 4, False, True), ('写回 settings.* (不删项)', 4, 6, False, True), ('++ 受保护(CLAUDE/CONTEXT): 逐项 y/N, 拒绝则不改 (硬约束)', 3, 0, False, True), ('++ --force 命中受保护 -> RejectForce, 不覆盖', 3, 0, False, True), ('++ 非受保护: 逐项 y/N (--force 可自动 yes)', 3, 0, False, True), ('++ "按以上决策应用?" (Q3 双重确认之二)', 3, 0, False, True), ('++ yes', 0, 3, False, True), ('++ 写"认可"项 + 字段合并 + state', 3, 6, False, True), ('++ 写 installed-version = toolkitVer', 3, 2, False, True), ('~ formatUpdateReport (+ state diff)', 3, 0, False, False), ] SKIP = -1 W = 1100 H = 100 + len(messages) * 50 + 130 L = [] emit = L.append emit('' % (W, H)) emit(' ') emit(' ') emit(' ' % ARD) emit(' ' % AMB) emit(' ') emit(' ') emit(' ' % (W, H)) emit(' to-be · sequence delta · ++ added / ~ modified step') lane_top = 70 lane_bot = H - 90 lane_fills = {0:'#f1f5f9', 1:'#d4edda', 2:'#d4edda', 3:'#fff3cd', 4:'#f1f5f9', 5:'#d4edda', 6:'#fff3e0'} lane_strokes = {0:'#cbd5e1', 1:ARD, 2:ARD, 3:AMB, 4:'#cbd5e1', 5:ARD, 6:'#f57c00'} for name, x in lanes: idx = lanes.index((name,x)) emit(' ' % (x-60, lane_top-30, lane_fills[idx], lane_strokes[idx])) emit(' %s' % (x, lane_top-13, name)) emit(' ' % (x, lane_top, x, lane_bot)) y = lane_top + 30 for msg in messages: if len(msg) == 5: text, src, dst, dashed, added = msg else: text, src, dst, dashed = msg; added=False if src == SKIP and dst == SKIP: emit(' %s' % (y, text)) y += 30 continue x1 = lanes[src][1]; x2 = lanes[dst][1] if added: color = ARD; mk = 'arrG'; cls = 'msgG' else: color = '#475569'; mk = 'arr'; cls = 'msg' dash_attr = ' stroke-dasharray="4 3"' if dashed else '' emit(' ' % (x1, y, x2, y, color, mk, dash_attr)) midx = (x1+x2)//2 emit(' %s' % (midx, y-6, cls, text)) y += 50 emit(' ++ 全程有版本提示; ++ 双重确认; ++ 受保护清单; ++ 删除戳记守护' % (H-50)) emit(' -- 默认路径不再 exit 1; -- --force 对受保护文件无效 (RejectForce)' % (H-32)) emit('') p = 'docs/4plus1/delta/client-update-flow/to-be/rendered/sequence-delta.svg' with open(p, 'w', encoding='utf-8') as f: f.write('\n'.join(L)) print('sequence-delta written lines=%d size=%d' % (len(L), os.path.getsize(p))) if __name__ == '__main__': gen_module_delta() gen_flow_delta() gen_sequence_delta()