@michelj/context-guard 0.4.3 → 0.6.1

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 (161) hide show
  1. package/Coordinator.md +88 -0
  2. package/Executor.md +53 -0
  3. package/README.md +89 -224
  4. package/README.zh-CN.md +89 -224
  5. package/SKILL.md +26 -684
  6. package/THIRD_PARTY_NOTICES.md +47 -0
  7. package/Tester.md +53 -0
  8. package/agents/openai.yaml +2 -2
  9. package/bin/build-runtime.mjs +96 -0
  10. package/bin/context-guard-skill.js +399 -78
  11. package/bin/postinstall.js +2 -2
  12. package/hooks.json +89 -13
  13. package/licenses/JSONParse-MIT.txt +24 -0
  14. package/licenses/Marked-MIT.txt +44 -0
  15. package/licenses/Portless-Apache-2.0.txt +201 -0
  16. package/package.json +35 -6
  17. package/prototype/LICENSES/Marked-MIT.txt +44 -0
  18. package/prototype/LICENSES/Ready-redistribution.txt +14 -0
  19. package/prototype/attachments.mjs +75 -0
  20. package/prototype/coordinator-markdown.mjs +283 -0
  21. package/prototype/coordinator-working-blot.mjs +124 -0
  22. package/prototype/vendor/marked.mjs +2189 -0
  23. package/prototype/workbench-app.js +5197 -0
  24. package/prototype/workbench-data.js +33 -0
  25. package/prototype/workbench-sync.mjs +898 -0
  26. package/prototype/workbench.css +1050 -0
  27. package/prototype/workbench.html +211 -0
  28. package/prototype/working-blot-atlas.png +0 -0
  29. package/references/agent-handoff.md +40 -0
  30. package/references/claude-runtime.md +120 -0
  31. package/references/cloud-sync-interface.md +66 -0
  32. package/references/design-current.md +14 -0
  33. package/references/map-mount.md +41 -0
  34. package/references/map-read.md +50 -0
  35. package/references/memory-definition.md +120 -0
  36. package/references/memory-filesystem-v2/Bug.en.md +162 -0
  37. package/references/memory-filesystem-v2/Bug.md +162 -0
  38. package/references/memory-filesystem-v2/Bug_Coordinater.md +8 -0
  39. package/references/memory-filesystem-v2/Bug_Executor.md +8 -0
  40. package/references/memory-filesystem-v2/Bug_Tester.md +7 -0
  41. package/references/memory-filesystem-v2/Idea.en.md +36 -0
  42. package/references/memory-filesystem-v2/Idea.md +36 -0
  43. package/references/memory-filesystem-v2/Node_Module_Index.en.md +88 -0
  44. package/references/memory-filesystem-v2/Node_Module_Index.md +88 -0
  45. package/references/memory-filesystem-v2/README.md +60 -0
  46. package/references/memory-filesystem-v2/Todo.en.md +137 -0
  47. package/references/memory-filesystem-v2/Todo.md +137 -0
  48. package/references/memory-filesystem-v2/Todo_Coordinater.md +7 -0
  49. package/references/memory-filesystem-v2/Todo_Executor.md +7 -0
  50. package/references/memory-filesystem-v2/Todo_Tester.md +7 -0
  51. package/references/named-workbench.md +124 -0
  52. package/references/plan-review.md +12 -0
  53. package/references/server-memory.md +276 -0
  54. package/references/test-check.md +7 -0
  55. package/references/user-reply.md +38 -0
  56. package/references/workbench-interface.md +531 -0
  57. package/roles.md +13 -0
  58. package/scripts/context_guard.py +1366 -7602
  59. package/scripts/context_guard_hook.py +1960 -711
  60. package/scripts/map_owns.py +699 -0
  61. package/scripts/shared/LICENSES/JSONParse-MIT.txt +24 -0
  62. package/scripts/shared/filesystem-v2.mjs +430 -0
  63. package/scripts/shared/io.mjs +117 -0
  64. package/scripts/shared/map-model.mjs +506 -0
  65. package/scripts/shared/memory-schema.mjs +13 -0
  66. package/scripts/shared/protocol-blobs.mjs +112 -0
  67. package/scripts/shared/protocol-map.mjs +146 -0
  68. package/scripts/shared/protocol-snapshots.mjs +84 -0
  69. package/scripts/shared/protocol-store.mjs +624 -0
  70. package/scripts/shared/protocol-workflow.mjs +226 -0
  71. package/scripts/shared/protocol.mjs +125 -0
  72. package/scripts/shared/vendor/jsonparse.cjs +413 -0
  73. package/scripts/workbench/access.mjs +496 -0
  74. package/scripts/workbench/attachments.mjs +92 -0
  75. package/scripts/workbench/browser-login.mjs +78 -0
  76. package/scripts/workbench/claude-runtime.mjs +372 -0
  77. package/scripts/workbench/cli.mjs +980 -0
  78. package/scripts/workbench/device-heartbeat.mjs +72 -0
  79. package/scripts/workbench/hook-status.mjs +38 -0
  80. package/scripts/workbench/inbox.mjs +155 -0
  81. package/scripts/workbench/journal.mjs +56 -0
  82. package/scripts/workbench/memory-merge.mjs +65 -0
  83. package/scripts/workbench/memory.mjs +252 -0
  84. package/scripts/workbench/named-proxy.mjs +108 -0
  85. package/scripts/workbench/named.mjs +152 -0
  86. package/scripts/workbench/portless-routes.mjs +51 -0
  87. package/scripts/workbench/project.mjs +327 -0
  88. package/scripts/workbench/projections.mjs +68 -0
  89. package/scripts/workbench/protocol-client.mjs +165 -0
  90. package/scripts/workbench/protocol-delivery.mjs +133 -0
  91. package/scripts/workbench/protocol-device.mjs +316 -0
  92. package/scripts/workbench/protocol-events.mjs +53 -0
  93. package/scripts/workbench/protocol-repository.mjs +58 -0
  94. package/scripts/workbench/reconcile.mjs +244 -0
  95. package/scripts/workbench/registry.mjs +111 -0
  96. package/scripts/workbench/runtime.mjs +54 -0
  97. package/scripts/workbench/server.mjs +1171 -0
  98. package/scripts/workbench/store.mjs +243 -0
  99. package/scripts/workbench/sync-coordinator.mjs +518 -0
  100. package/scripts/workbench/sync.mjs +86 -0
  101. package/references/context-template.md +0 -341
  102. package/references/feature-chain-methodology.md +0 -228
  103. package/references/register-template.md +0 -85
  104. package/references/task-case-template.md +0 -63
  105. package/tests/BC-20260618-063.sh +0 -116
  106. package/tests/BC-20260618-065.sh +0 -66
  107. package/tests/BC-20260626-080.sh +0 -48
  108. package/tests/BC-20260626-081.sh +0 -40
  109. package/tests/BC-20260626-082.sh +0 -32
  110. package/tests/BC-20260626-083.sh +0 -66
  111. package/tests/BC-20260627-084.sh +0 -74
  112. package/tests/BC-20260630-086.sh +0 -50
  113. package/tests/BC-20260630-087.sh +0 -103
  114. package/tests/BC-20260630-088.sh +0 -32
  115. package/tests/BC-20260630-089.sh +0 -63
  116. package/tests/BC-20260701-090.sh +0 -84
  117. package/tests/BC-20260702-096.sh +0 -48
  118. package/tests/BC-20260706-098.sh +0 -66
  119. package/tests/BC-20260707-099.sh +0 -47
  120. package/tests/BC-20260707-100.sh +0 -46
  121. package/tests/BC-20260707-101.sh +0 -47
  122. package/tests/BC-20260707-102.sh +0 -68
  123. package/tests/BC-20260707-103.sh +0 -59
  124. package/tests/BC-20260707-104.sh +0 -103
  125. package/tests/BC-20260707-105.sh +0 -109
  126. package/tests/BC-20260707-106.sh +0 -80
  127. package/tests/BC-20260707-107.sh +0 -74
  128. package/tests/BC-20260707-108.sh +0 -48
  129. package/tests/BC-20260707-109.sh +0 -56
  130. package/tests/BC-20260707-110.sh +0 -71
  131. package/tests/BC-20260707-111.sh +0 -70
  132. package/tests/BC-20260707-112.sh +0 -45
  133. package/tests/BC-20260707-113.sh +0 -73
  134. package/tests/BC-20260707-115.sh +0 -77
  135. package/tests/BC-20260707-116.sh +0 -77
  136. package/tests/BC-20260707-118.sh +0 -115
  137. package/tests/BC-20260707-119.sh +0 -47
  138. package/tests/BC-20260707-120.sh +0 -60
  139. package/tests/BC-20260707-121.sh +0 -66
  140. package/tests/BC-20260707-122.sh +0 -48
  141. package/tests/BC-20260707-123.sh +0 -43
  142. package/tests/BC-20260707-124.sh +0 -56
  143. package/tests/BC-20260707-125.sh +0 -64
  144. package/tests/BC-20260707-126.sh +0 -80
  145. package/tests/BC-20260707-127.sh +0 -88
  146. package/tests/BC-20260707-129.sh +0 -59
  147. package/tests/BC-20260707-130.sh +0 -69
  148. package/tests/BC-20260707-131.sh +0 -140
  149. package/tests/BC-20260707-132.sh +0 -150
  150. package/tests/BC-20260707-133.sh +0 -70
  151. package/tests/BC-20260708-136.sh +0 -210
  152. package/tests/BC-20260708-137.sh +0 -106
  153. package/tests/BC-20260708-138.sh +0 -168
  154. package/tests/BC-20260708-139.sh +0 -79
  155. package/tests/BC-20260709-002.sh +0 -63
  156. package/tests/BC-20260709-003.sh +0 -239
  157. package/tests/BC-20260709-006.sh +0 -76
  158. package/tests/BC-20260709-008.sh +0 -168
  159. package/tests/BC-20260710-001.sh +0 -61
  160. package/tests/BC-20260710-002.sh +0 -111
  161. package/tests/npm-install-smoke.sh +0 -53
package/prototype/workbench.html ADDED
@@ -0,0 +1,211 @@
1
+ <!doctype html>
2
+ <html lang="zh-CN">
3
+ <head>
4
+ <!-- CG_SERVER_BOOT -->
5
+ <meta charset="utf-8">
6
+ <meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
7
+ <title>Context Guard · 工作台原型</title>
8
+ <link rel="preconnect" href="https://fonts.googleapis.com">
9
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
10
+ <link id="cg-fonts" data-href="https://fonts.googleapis.com/css2?family=Comic+Neue:wght@400;700&family=IBM+Plex+Sans:wght@400;500;600;700&family=IBM+Plex+Serif:ital,wght@0,400;0,600;1,400&family=Noto+Sans+SC:wght@400;500;700&family=Noto+Serif+SC:wght@400;600;700&family=Libre+Baskerville:ital,wght@0,400;1,400&display=swap" rel="stylesheet">
11
+ <script>
12
+ (function(){
13
+ // Optional fonts must never delay the workbench scripts or initial rendering.
14
+ window.addEventListener("load",function(){ const fonts=document.getElementById("cg-fonts"); fonts.href=fonts.dataset.href; });
15
+ var q = new URLSearchParams(location.search);
16
+ function flag(name){
17
+ if(q.has(name)) return true;
18
+ /* htmlpreview 把 raw GitHub 地址整段塞进 search，q.has 认不出来。 */
19
+ return new RegExp("[?&#]"+name+"=").test(location.href);
20
+ }
21
+ var preview = flag("preview");
22
+ var t = q.get("theme");
23
+ if(!(t==="1"||t==="4"||t==="44"||t==="48")){
24
+ try{ t = localStorage.getItem("cg-workbench-node-theme")||""; }catch(e){ t=""; }
25
+ }
26
+ if(t==="4"||t==="44"||t==="48"){
27
+ document.documentElement.setAttribute("data-node-theme", t);
28
+ }else{
29
+ document.documentElement.removeAttribute("data-node-theme");
30
+ t = "1";
31
+ }
32
+ if(preview) document.documentElement.classList.add("theme-preview");
33
+ window.__CG_NODE_THEME = t;
34
+ window.__CG_PREVIEW = preview;
35
+ /* ?phone=1 电脑上看手机布局；?phone=0 强制电脑布局。Safari「桌面网站」会把视口报成 ~980px。 */
36
+ var phoneMatch = /[?&#]phone=([^&]*)/.exec(location.href);
37
+ var phoneQ = q.has("phone") ? q.get("phone") : (phoneMatch ? phoneMatch[1] : null);
38
+ var phoneForce = phoneQ==null ? null : (phoneQ==="0" ? false : true);
39
+ window.__CG_PHONE_FORCE = phoneForce;
40
+ var phone = false;
41
+ if(phoneForce===true) phone = true;
42
+ else if(phoneForce===false) phone = false;
43
+ else {
44
+ try{
45
+ phone = window.matchMedia("(max-width: 820px), (hover: none) and (pointer: coarse) and (orientation: portrait)").matches;
46
+ }catch(e){}
47
+ if(!phone){
48
+ var short = Math.min(screen.width||0, screen.height||0);
49
+ var tall = Math.max(screen.width||0, screen.height||0);
50
+ var portrait = (window.innerHeight||0) >= (window.innerWidth||0) || tall >= short;
51
+ var touch = (navigator.maxTouchPoints||0) > 0;
52
+ try{ touch = touch || window.matchMedia("(pointer: coarse)").matches; }catch(e){}
53
+ phone = touch && portrait && short > 0 && short <= 820;
54
+ }
55
+ }
56
+ document.documentElement.classList.toggle("cg-phone", !!phone);
57
+ if(phoneForce!==null) document.documentElement.classList.add("phone-preview");
58
+ })();
59
+ </script>
60
+ <link rel="stylesheet" href="./workbench.css?v=work-tools-v2">
61
+ </head>
62
+ <body>
63
+ <div class="theme-preview-banner" id="theme-preview-banner">预览模块卡样式 · 还没写进默认工作台</div>
64
+ <div class="phone-preview-banner" id="phone-preview-banner">手机预览 · 只看布局，电脑顶栏不会跟着砍</div>
65
+ <h1 id="repo-title" hidden>Context Guard 架构导图</h1>
66
+ <header class="top">
67
+ <div class="brand">
68
+ <nav class="nav-crumbs" id="nav-crumbs"></nav>
69
+ <div class="repo-menu" id="repo-menu"></div>
70
+ </div>
71
+ <div class="top-tools">
72
+ <details class="workbench-tools" id="workbench-tools">
73
+ <summary data-i18n="workbenchTools">工作台工具</summary>
74
+ <div class="workbench-tools-menu">
75
+ <button type="button" class="dir-toggle" id="dir-toggle" aria-pressed="false" data-dir="lr" data-i18n-title="dirTitle" title="布局" aria-label="布局">
76
+ <span class="dir-thumb" aria-hidden="true"></span>
77
+ <span class="dir-opt on" data-dir="lr">左右</span>
78
+ <span class="dir-opt" data-dir="tb">上下</span>
79
+ </button>
80
+ <div class="rel-toggle" id="rel-toggle" data-i18n-title="relTitle" title="打开后点击节点只高亮它的生产/消费，不进入。无关模块会变暗。">
81
+ <button type="button" id="btn-rel" aria-pressed="false" data-i18n="relations">关系</button>
82
+ </div>
83
+ <span id="rel-hint" data-i18n="relHint">点击模块看关系，不会进入</span>
84
+ <button class="auth-btn" id="btn-auth" data-i18n-title="authMode" title="授权模式" aria-label="授权模式">🔑</button>
85
+ <button class="tray-btn" id="btn-bugs">🐞 Bug (<span id="bug-count">0</span>)</button>
86
+ <button class="tray-btn" id="btn-todos">TODO (<span id="todo-count">0</span>)</button>
87
+ </div>
88
+ </details>
89
+ <button type="button" class="tray-btn" id="btn-coordinator" aria-expanded="false" hidden>Coordinator</button>
90
+ <div class="session-switch" id="session-switch">
91
+ <button type="button" class="session-chip" id="session-chip" aria-label="切换 Agent 会话" aria-haspopup="listbox" aria-expanded="false" aria-controls="session-menu">
92
+ <b id="session-name">暂无 Agent 会话</b>
93
+ <span id="session-status" class="session-status empty" aria-label="未挂载会话"></span>
94
+ </button>
95
+ <div class="session-menu" id="session-menu" role="listbox" aria-label="Agent 会话" hidden></div>
96
+ </div>
97
+ <span id="cloud-sync-status" class="cloud-sync-status" role="status" aria-label="云端同步状态" hidden></span>
98
+ <span id="repo-status" class="repo-status" hidden></span>
99
+ </div>
100
+ <div class="settings-wrap" id="settings-wrap">
101
+ <button type="button" class="tray-btn" id="btn-settings" aria-expanded="false" aria-haspopup="true" data-i18n-title="settings" title="设置" aria-label="设置">
102
+ <svg class="gear-icon" viewBox="0 0 24 24" aria-hidden="true">
103
+ <path fill="currentColor" d="M19.14 12.94c.04-.31.06-.63.06-.94s-.02-.63-.06-.94l2.03-1.58a.5.5 0 0 0 .12-.64l-1.92-3.32a.5.5 0 0 0-.6-.22l-2.39.96a7.03 7.03 0 0 0-1.63-.94l-.36-2.54A.5.5 0 0 0 13.9 2h-3.8a.5.5 0 0 0-.49.42l-.36 2.54c-.59.24-1.13.55-1.63.94l-2.39-.96a.5.5 0 0 0-.6.22L2.71 8.48a.5.5 0 0 0 .12.64l2.03 1.58c-.04.31-.06.63-.06.94s.02.63.06.94L2.83 14.16a.5.5 0 0 0-.12.64l1.92 3.32c.14.24.43.34.68.22l2.39-.96c.5.39 1.04.7 1.63.94l.36 2.54c.05.24.26.42.49.42h3.8c.24 0 .44-.18.49-.42l.36-2.54c.59-.24 1.13-.55 1.63-.94l2.39.96c.25.12.54.02.68-.22l1.92-3.32a.5.5 0 0 0-.12-.64l-2.03-1.58zM12 15.6A3.6 3.6 0 1 1 12 8.4a3.6 3.6 0 0 1 0 7.2z"/>
104
+ </svg>
105
+ </button>
106
+ <div class="settings-menu" id="settings-menu">
107
+ <div class="set-block">
108
+ <div class="set-label" data-i18n="toolsLabel">工具</div>
109
+ <div class="set-tools">
110
+ <div class="rel-toggle" id="lens-toggle" data-i18n-title="lensTitle" title="首次建图：候选模块摆在画布上，与主节点无连线；选中一个，它才挂到主节点下。">
111
+ <button type="button" id="btn-lens" aria-pressed="false" data-i18n="lensMode">第一层候选</button>
112
+ </div>
113
+ <button class="tray-btn" id="btn-tray">🗂 <span data-i18n="cancelled">已取消</span> (<span id="tray-count">0</span>)</button>
114
+ <button type="button" class="tray-btn" id="btn-link-repo" hidden data-i18n="linkRepo" data-i18n-title="linkRepoTitle" title="选带 SKILL.md 的仓库根，改图可以写回 map.json">连接仓库</button>
115
+ </div>
116
+ </div>
117
+ <div class="set-block">
118
+ <div class="set-label" data-i18n="betaLabel">实验功能</div>
119
+ <button type="button" class="tray-btn beta-motion-toggle" id="btn-beta-motion" aria-pressed="false" data-i18n-title="betaMotionTitle" title="Beta：启用 0.5 秒地图层级钻取动效">
120
+ <span class="beta-badge">BETA</span>
121
+ <span data-i18n="betaMotion">地图钻取动效</span>
122
+ </button>
123
+ </div>
124
+ <div class="set-block">
125
+ <div class="set-label" data-i18n="themeLabel">主题</div>
126
+ <div class="theme-picks" id="theme-picks">
127
+ <button type="button" class="theme-pick" data-theme="1">
128
+ <i class="swatch" style="background:#fff3bf;border-color:#2d2d2d"></i>
129
+ <span data-i18n="themeNow">现在这版</span>
130
+ </button>
131
+ <button type="button" class="theme-pick" data-theme="44">
132
+ <i class="swatch" style="background:#fff6e5;border-color:#e6d3a8"></i>
133
+ <span data-i18n="themeCream">奶油描边</span>
134
+ </button>
135
+ <button type="button" class="theme-pick" data-theme="48">
136
+ <i class="swatch" style="background:#ffe08a;border-color:#cfc6b4"></i>
137
+ <span data-i18n="themeWash">淡彩分层</span>
138
+ </button>
139
+ <button type="button" class="theme-pick" data-theme="4">
140
+ <i class="swatch" style="background:#fff4c2;border-color:#bbb"></i>
141
+ <span data-i18n="themeFlat">无阴影扁平</span>
142
+ </button>
143
+ </div>
144
+ </div>
145
+ <div class="set-block">
146
+ <div class="set-label" data-i18n="langLabel">语言</div>
147
+ <div class="lang-toggle" id="lang-toggle" title="界面语言 / UI language">
148
+ <button type="button" data-lang="zh" class="on">中</button>
149
+ <button type="button" data-lang="en">EN</button>
150
+ </div>
151
+ </div>
152
+ </div>
153
+ </div>
154
+ </header>
155
+ <div class="first-use" id="first-use">
156
+ <div class="card" id="first-use-ask">
157
+ <div class="kicker" data-i18n="firstKicker">演示 · 第一次使用</div>
158
+ <h2 id="first-use-heading">从当前仓库建立架构图</h2>
159
+ <p id="first-use-copy">产品里这一步由当前会话的 Agent 真读仓库，把多个视角的候选模块（标题和用途要一眼能看懂）端到这里。你从各视角挑、改名、删减，拼出自己的第一层，选完才上画布。</p>
160
+ <p data-i18n="firstProduct">第一层定稿后，Agent 再按你选的模块逐个出第二层候选，同样的池子交互，一层层往下。定稿大约 4–8 张主干，写进 architecture.md 和 map.json。</p>
161
+ <div class="actions">
162
+ <button class="primary" id="first-use-go" data-i18n="firstGo">看第一层候选（多视角）</button>
163
+ <button class="quiet" id="first-use-empty" data-i18n="firstEmpty">仓库几乎是空的</button>
164
+ </div>
165
+ </div>
166
+ <div class="card wide" id="first-use-cuts" hidden>
167
+ <div class="kicker" data-i18n="cutKicker">Agent 已读仓 · 请你定第一层</div>
168
+ <h2 data-i18n="cutHeading">候选池不可用</h2>
169
+ <p data-i18n="cutCopy">没有读到 .codex/context/l1-candidates.json。请让 Agent 先真读仓生成候选文件，或在设置里用「第一层候选」进入画布搁板模式。</p>
170
+ <div class="actions">
171
+ <button class="quiet" id="first-use-cut-back" data-i18n="cutBack">返回</button>
172
+ </div>
173
+ </div>
174
+ <div class="card" id="first-use-work" hidden>
175
+ <div class="kicker" data-i18n="workKicker">演示中 · 未调用 Agent</div>
176
+ <h2 data-i18n="workHeading">正在播放预置的分析过程</h2>
177
+ <p data-i18n="workCopy1">浏览器在按写死的步骤和稿子走，没有模型在读 OpenClaw 或本仓库。真实 skill 启用时，才由你正在对话的那个 Agent 读代码。</p>
178
+ <ul class="analyze-log" id="analyze-log"></ul>
179
+ <pre class="arch-md" id="analyze-md" hidden></pre>
180
+ <p data-i18n="workCopy2">下面的笔记是预置演示稿。真做时先商量第一层怎么切，定了再往下拆；卡名必须一眼能看懂。演示里第一页仍是定稿后的 4–8 张主干。这不是这次点击实时读仓得到的。</p>
181
+ </div>
182
+ </div>
183
+
184
+ <div id="viewport">
185
+ <div id="world">
186
+ <svg id="links"></svg>
187
+ <div id="nodes"></div>
188
+ <div id="currents"></div>
189
+ <div id="flow-labs"></div>
190
+ </div>
191
+ </div>
192
+ <div id="dot-hint" hidden role="tooltip"></div>
193
+
194
+ <div class="tray" id="tray">
195
+ <h3 data-i18n="trayTitle">已取消的提议</h3>
196
+ <p class="hint" data-i18n="trayHint">已隐藏，后续 Agent 不会读到。可重新加入 Context Map，或永久删除。</p>
197
+ <ul id="tray-list"></ul>
198
+ </div>
199
+
200
+ <aside class="bug-panel" id="bug-panel">
201
+ <h3 id="work-panel-title" data-i18n="openBugs">Bug 处理状态</h3>
202
+ <ul id="bug-panel-list"></ul>
203
+ </aside>
204
+
205
+ <div class="drawer-split" id="drawer-split" role="separator" aria-orientation="vertical" tabindex="0" data-i18n-title="splitTitle" title="拖动调整检查器宽度，双击恢复"></div>
206
+ <aside class="drawer" id="detail"></aside>
207
+
208
+ <script src="./workbench-data.js?v=bug-claim"></script>
209
+ <script src="./workbench-app.js?v=work-tools-v2"></script>
210
+ </body>
211
+ </html>
package/prototype/working-blot-atlas.png ADDED
Binary file
package/references/agent-handoff.md ADDED
@@ -0,0 +1,40 @@
1
+ # Agent 交接
2
+
3
+ Coordinator 向 Executor、Tester 发送任务时适用。Executor 接收时按同一四项核对。
4
+
5
+ ## 准备与派发
6
+
7
+ 新 TODO/Bug 调用 `prepare_task` 后等待 brief 审批，不用 `ask_user` 再发批准或派发选项。人批准 brief 后后台为任务自动创建执行 Session 和工作树，就绪后派发；不为新任务调用 `dispatch_task`。这就是 Coordinator 创建执行 Session 的正常能力，但不能把“挂载”或“准备成功”说成已经派发。
8
+
9
+ `conversationId` 与 `executionSessionId` 是两类身份，禁止混用。`main`、`legacy`、`session:*`、`item-*` 是对话标识，不能作执行 ID。新任务身份取自 `list_tasks`；旧任务执行 ID 必须逐字复制自本轮 `list_sessions` 返回值。
10
+
11
+ 执行 ID 为空表示尚未创建或绑定，不能调用 `read_task`。核对条目的 `taskId`、`itemId`、`nodeId`、`kind` 及审批状态，需要准备需求时沿用这些身份。`legacy-dispatch-review` 先核对原任务，不能当新任务重派。不向用户展示内部执行 ID，也不要求用户选 Session 或处理内部权限错误。
12
+
13
+ ## 交接内容
14
+
15
+ 一次交接必须写明：
16
+
17
+ 1. 任务说明（用户已确认的那一版，不得改字）
18
+ 2. 挂载节点
19
+ 3. Main 版本
20
+ 4. 验收条件
21
+
22
+ 不得使用含糊指令，例如「适当处理」「参考相关模块」。不得在交接中授予额外节点权限，不得把 Session 草稿当作 Main。
23
+
24
+ 对方可读取总体 context，执行过程中不得改写 Main。不得对人说话。Executor 先提交代码和 handoff，Coordinator 再交给 Tester；测试和人工验收前不归档或结束计划。人工验收后才归档并结束计划。
25
+
26
+ ## Executor 接收核对
27
+
28
+ 所有命令使用宿主提供的当前 worktree；`mainVersion` 是记忆版本，不是 Git SHA。先核对现有代码与任务要求的差距，已满足的部分记录事实和证据，需要补验证时将缺失检查纳入 Plan，不重复实现已经完成的功能。
29
+
30
+ 执行前通过 `plan-status` 读取 `pending_signals`。对应已挂载 Cloud 任务的信号用 `resolve-signal --kind task` 分类，不另建同义 TODO/Bug；独立新需求按其内容记录。Hook 因未分类信号拒绝写入时，先完成分类，再继续原操作，不换工具绕过。
31
+
32
+ ## 中断与返工
33
+
34
+ 未完成任务出现 interrupted 事件后，系统自动发起恢复，保留原 Session、Plan、节点和证据。已有恢复控制时等待匹配的 resumed 回执，不重复发送或绕过 Plan 审核。需要补充指导时使用 `guide_task`，不要把仍在执行的任务当中断任务恢复。
35
+
36
+ CI 失败或人类验收拒绝都回到原任务、原执行环境。验收拒绝由系统自动推进返工，先核对权威状态，不误报为执行端未认领。
37
+
38
+ ## 收工
39
+
40
+ 人工验收通过后，Coordinator 先读取 `read_task.completionPolicy`，用 `guide_task` 通知原 Executor 归档、结束计划。正式任务提交 PR，核验合并和 Session 发布回执后调用 `complete_task`；服务端指定的 `experiment-only` 任务保留同一提交的测试与人审证据，按返回的回执调用 `complete_task`，不创建 PR、不发布 Main。两者都须等宿主 `closed` 回报才算关闭。不要让人直接联系执行端。
package/references/claude-runtime.md ADDED
@@ -0,0 +1,120 @@
1
+ # Managed Claude CLI receiver
2
+
3
+ Claude uses `CLAUDE_CONFIG_DIR` for settings and installed Skills. The installer
4
+ honors that variable first and retains `CLAUDE_HOME` as a legacy fallback. Keep
5
+ executor and CI profiles and real Session IDs separate; use one shared project
6
+ backend and device heartbeat service, not a timer in every Hook.
7
+
8
+ ## Cloud-created Executor Sessions
9
+
10
+ The operator may opt an existing Executor receiver into creation with
11
+ `allowSessionCreation:true` in its private runtime configuration. Cloud must also
12
+ list that receiver's Session ID in the project's `coordinator.sessionTemplates`;
13
+ both opt-ins are required. This does not enable permission bypass or install
14
+ anything into Codex's configuration.
15
+
16
+ The human uses **Coordinator → 新建执行会话**, selects the configured template and
17
+ supplies a name. Cloud persists the request and generated UUID; the existing
18
+ device heartbeat transports it. The backend creates an independent Git worktree
19
+ from the registered Main ref and a private Claude profile containing only the
20
+ template's installed Skill and reviewed settings. It does not copy old chats.
21
+ Only the native startup binding changes the request to `registered`; that state
22
+ is not proof of task execution or current online status. Failed preparation is
23
+ reported through the same heartbeat, with durable retry until acknowledgment.
24
+
25
+ Created Executors use the template's existing independent CI receiver. The
26
+ receiver stays serial; each handoff and CI capability still names the actual
27
+ Executor Session and exact SHA. Cloud verifies the persisted creation relation
28
+ and current device/worktree binding. Removing Cloud's template opt-in revokes this
29
+ inherited delegation. No task is assigned merely by creating a Session.
30
+
31
+ ## Configure an existing receiver
32
+
33
+ After the real Claude Session has emitted its native startup Hook and bound to
34
+ the project, the local operator can configure its receiver:
35
+
36
+ ```sh
37
+ context-guard workbench claude --root <worktree> --session <uuid> --input <private-runtime.json>
38
+ ```
39
+
40
+ The private input contains absolute `command`, `root`, `configDir` and
41
+ `environmentFile` paths, optional command-prefix `args`, plus `name`, `model` and
42
+ `role` (`executor` or `ci`). `resumeExisting:true` is required when the native
43
+ Session already has a persisted conversation. `systemPromptFile` points to the
44
+ installed role prompt. The role field identifies the local runner; it does not
45
+ issue a Cloud CI or Coordinator capability.
46
+
47
+ For CI, also configure `executorSessionId` and an exact `ciCommands` allowlist
48
+ (for example `npm test` and `npm run build`). The CI worktree must differ from
49
+ the Executor worktree. Cloud's private project Coordinator configuration must
50
+ declare `ciReceivers[ciSessionId] = {executorSessionId, worktreeId}`. A body field
51
+ or local role label cannot grant that authority. The backend reuses device login
52
+ and the existing persistent transport; it does not start another heartbeat.
53
+
54
+ On `ci.request`, the receiver checks out the handed-off SHA only in the clean CI
55
+ worktree. `map ci context` returns the logical Executor Session, task, exact SHA,
56
+ immutable reference versions and allowed commands. `map ci exchange --input -`
57
+ accepts normal protocol JSON; the backend supplies that logical Session rather
58
+ than changing the native CI Session identity. Allowed operations are
59
+ `object.read`, evidence-only `object.put` with refs prefixed `ci:<ciSessionId>:`,
60
+ and `ci.result` for this task and SHA. A changed HEAD or dirty worktree prevents
61
+ a CI result. CI Hooks allow only the configured test commands without a Plan;
62
+ business-source writes and development Plans remain forbidden.
63
+
64
+ ## Reviewed Executor tasks
65
+
66
+ `map task plan --input <file>` accepts `{operationId,content:{paths,steps}}`.
67
+ It records an immutable Plan at the actual HEAD and requests Coordinator review.
68
+ Keep the operation ID after an uncertain reply; use a new ID for a revised Plan.
69
+ Approval names the exact task, Plan version and source SHA. Read `map execution`
70
+ and pass its `taskId`, `planRef` and `planVersion` to the usual `plan-start` input.
71
+
72
+ After committing the delivered code, `map task handoff --input <file>` accepts
73
+ `{operationId,ciTodo:{items:[...]},unitTests:[...],experiences:[...]}`. Test evidence
74
+ must describe actual runs; experiences may be empty if nothing reusable was
75
+ learned. The command refuses a dirty worktree, persists immutable objects and
76
+ reports their references with the exact commit SHA. It does not assert CI success,
77
+ human acceptance or a merge. Keep the local Plan active through handoff. The
78
+ handoff precedes Tester and human acceptance; archive and run `plan-finish` only
79
+ after human review. The Coordinator consumes the existing protocol
80
+ journal to receive brief decisions, Plan submissions and CI results; model
81
+ failures remain paused until an explicit retry.
82
+
83
+ `environmentFile` is private JSON containing only the required `ANTHROPIC_*`
84
+ provider fields and optional `CLAUDE_CODE_SUBAGENT_MODEL` and
85
+ `CLAUDE_CODE_ATTRIBUTION_HEADER`. Keep credentials out of runtime arguments,
86
+ prompts, logs and Map data. `permissionMode:"bypassPermissions"` is accepted only
87
+ with `isolated:true`; the operator must actually provide an isolated execution
88
+ environment. This flag does not install or create a sandbox.
89
+
90
+ Cloud remains responsible for task ordering. The local receiver permits one
91
+ native turn per Session; a busy receiver leaves the next notification pending
92
+ in the existing inbox. Accepted invocations have durable identities. A local
93
+ backend restart can recover a lost acknowledgement from the receiver's saved
94
+ intent without launching the same prompt again. Native workers outlive backend
95
+ restarts; they do not own another heartbeat service.
96
+
97
+ `timeoutMs` limits silence; `maxTurnMs` limits the total native turn (30 minutes
98
+ by default). Either limit preserves an interrupted delivery for recovery in the
99
+ same Session rather than treating elapsed time as task completion.
100
+
101
+ The Claude installer includes failure, permission, pre/post-compaction and
102
+ SessionEnd hooks in addition to start/tool/stop events. Non-decision events only
103
+ record state; they do not restart model generation. See the native
104
+ [Claude Hook contract](https://code.claude.com/docs/en/hooks). Signal IDs are read
105
+ from `plan-status.pending_signals`, never inferred from lifecycle event IDs.
106
+
107
+ An interrupted or uncertain native turn remains visible and is not automatically
108
+ re-executed. Do not delete its saved intent to retry. Controlled recovery and CI
109
+ delegation must be verified before claiming full lifecycle support. Native turn
110
+ completion is not a successful task, human acceptance, GitHub merge, or archive.
111
+
112
+ For an explicitly requested continuation of an interrupted turn, the local operator
113
+ may run `workbench claude --recover --root <worktree> --session <uuid> --input
114
+ <private-json>`. Input is `{operationId,deliveryId,message}`: identify the exact
115
+ interrupted delivery and describe what to continue. Both previous processes must
116
+ have exited; a live or uncertain process is never killed by recovery. The original
117
+ record remains unchanged, and a new durable continuation resumes the same native
118
+ Session. Reuse the same operation ID and content after an uncertain response.
119
+ Existing task, Plan and CI permissions still apply; this is not an approval or
120
+ permission to repeat completed work. No background recovery loop is added.
package/references/cloud-sync-interface.md ADDED
@@ -0,0 +1,66 @@
1
+ # Cloud Session synchronization
2
+
3
+ Read this reference for a Cloud-connected project or a preserved synchronization
4
+ conflict. Memory authority and publication remain defined in `server-memory.md`.
5
+
6
+ ## One connection, isolated Sessions
7
+
8
+ Use `context-guard workbench connect --url <origin> --root <project> --session
9
+ <actual-session-id> --wait` for browser authorization. Once connected, ordinary
10
+ `workbench --root <project> --session <actual-session-id>` reuses the project
11
+ connection. The workbench owns the background connection; never start a separate
12
+ project-wide Map daemon or point a Session at Main to bypass publication.
13
+
14
+ Local edits enter a durable outbox. Cloud changes are read through events with
15
+ heartbeat recovery. Receipts, queues and cursors remain isolated per Session:
16
+
17
+ ```text
18
+ <project-shared-dir>/session-memory/<session-hash>/remote-sync/
19
+ state.json
20
+ server-base.json
21
+ outbox.json
22
+ conflict.json
23
+ ```
24
+
25
+ These are private data, not repository files. The workbench preserves uncertain
26
+ requests and retries their original operation IDs. Independent edits can merge;
27
+ overlapping edits preserve base, local and remote documents for review.
28
+
29
+ ## Commands and confirmation
30
+
31
+ ```bash
32
+ context-guard sync status --root <project> --session <actual-session-id>
33
+ context-guard sync ensure --root <project> --session <actual-session-id>
34
+ context-guard sync prepare --root <project> --session <actual-session-id>
35
+ context-guard sync checkpoint --root <project> --session <actual-session-id>
36
+ context-guard sync finish --root <project> --session <actual-session-id>
37
+ ```
38
+
39
+ `status` reads saved Session synchronization state without printing credentials;
40
+ it is not a fresh server receipt. `ensure` reuses the workbench. `prepare`, `pull`
41
+ and `checkpoint` use the current memory read/reconciliation path. `finish` uploads
42
+ the Session through the durable memory path and returns `confirmed: true` only
43
+ with a server snapshot version. None of these commands publishes Main or records
44
+ human acceptance. Lifecycle `plan-finish` still enforces archive and review gates.
45
+
46
+ The retired project-wide development windows are not supported. Plan scope stays
47
+ in the lifecycle plan; `sync track`, `sync connect` and `sync serve` must not start
48
+ the old transport. Use `workbench connect` for authentication.
49
+
50
+ ## Upgrades and conflicts
51
+
52
+ Old `.codex/context/private/cloud-sync/` data and shared `cloud-sync/` configuration
53
+ are inspected read-only. Unconfirmed work, a changed draft, unreadable state or a
54
+ conflict returns `UPGRADE_REQUIRED` with reason `legacy-sync-state-pending`.
55
+ Preserve and reconcile those records; do not delete them or infer that an old
56
+ project Map belongs to a particular Session. A configuration-only remnant does
57
+ not block an already connected current client. If it is the only connection,
58
+ `legacy-sync-reconnect` requests current browser authorization.
59
+
60
+ Network failure leaves current queues on disk. Reconnect retries with backoff;
61
+ conflicts require explicit reconciliation. Do not manufacture a new request ID,
62
+ erase private state or report success merely because a connection is alive.
63
+
64
+ The private Session service uses authorized `/v1/projects/:project/sessions/`
65
+ reads, changes/events and map writes. Session generations and server authorization
66
+ remain enforced. Credentials never belong in Maps, logs or generated HTML.
package/references/design-current.md ADDED
@@ -0,0 +1,14 @@
1
+ # 当前设计版本
2
+
3
+ 读者：产品角色 Agent 与仓库开发 Agent。
4
+
5
+ **当前版本：`fs-v2.2`**
6
+
7
+ 现行存储与工作项文件格式仍是 [Memory Filesystem v2.1](memory-filesystem-v2/README.md)。v2.2 增加 Session 发布完成证明：可信审核路径显式确认 `sessionId`、`generation`、`sessionVersion`、`sourceCommit` 后才可进入既有 Git/任务发布门禁。上传、心跳和初始 HEAD 在 Main 上均不代表完成；后续修改使证明失效。底层 v2 事务格式与现有单文件接口不变。Agent 默认只认这一份。下次改设计必须再开新版本，不能在同一份「现行」上悄悄换意思。旧版不留在 main。
8
+
9
+ 未升格设计草案不是当前版本，也不是已升格的法。没升版之前，实现和 Skill 都不得拿它们当存储、权限或发布协议。
10
+
11
+ 尚未拍板、本文不选边：
12
+
13
+ - Agent 打开模块时读哪套目录（FIND.md / snapshot 与 v2 Markdown 投影如何切换）
14
+ - 安装包里链到仓库 `docs/` 打不开怎么办
package/references/map-mount.md ADDED
@@ -0,0 +1,41 @@
1
+ # 挂载 Map
2
+
3
+ 读者：产品角色 Agent。意图清楚后打开本文，学会怎么调用。第一次挂载或忘记时通读。用户说挂错了时再打开。
4
+
5
+ Executor 写入自己的 Session Map，不是 Main。非人写 Main 结构只有 Coordinator：通过 `edit_map` / `mapWrite` 创建、改名、更新、移动或删除节点，也可删除指定节点上的 TODO/Bug，并以 `coordinator` 身份审计；可以先草稿，进 Main 再过门禁。版本校验、幂等回执和根节点保护由服务端强制执行，不能借此修改权限或记忆。不要把白名单 developer 客户端当成现行例外。命令细节以 [workbench-interface.md](workbench-interface.md) 为准。
6
+
7
+ ## 挂到哪
8
+
9
+ 节点定位由 Coordinator 完成，方式见 [读取 Map](map-read.md)。按需求读取已发布 Main 的导航、候选节点职责与 owns，推荐现有节点并用一句话解释依据；不要要求用户描述节点名称、ID 或代码路径。
10
+
11
+ 需求不清楚时，只问缺失的业务信息。例如“测试实验”应问想验证什么功能，而不是问挂到哪里。存在多个候选时比较职责后给出推荐，只就影响选择的业务差异提问。没有匹配节点时说明已查范围并提出新节点建议。Coordinator 可先建草稿节点，进 Main 仍走门禁；Executor 仍按提案交人类在 Coordinator 会话里确认，不编造节点或自行批准。
12
+
13
+ ## 需求
14
+
15
+ 需求摘要写清“要改变什么、在哪里可见、如何验收”。用户要求部署、发布、启动服务或提供访问地址时，保留实际交付目标；只问真正缺少的环境信息，不得用源码路径或 CI 通过替代部署结果。只有用户明确要求只读检查时才采用只读任务。
16
+
17
+ 推荐节点使用 Main 中的完整节点标题，通过 `show_nodes` 或 `ask_user.nodeIds` 提供可跳转引用。推荐不等于批准或派单。
18
+
19
+ Cloud 用户确认节点和事项类型后，调用 `mount_conversation` 把 Coordinator 挂到该节点，不写入 Main。执行 Session 仍须等该事项的 brief 获批后创建。用户找回旧话题时先用 `list_conversations` 定位，有歧义再澄清，不重新创建同一事项。
20
+
21
+ 使用本次 Prompt 的 signal，不要编造。
22
+
23
+ ```sh
24
+ context-guard record-todo --root "<project>" --session "<session-id>" \
25
+ --signal "<signal-id>" --node <id> --title "<title>" --description "<acceptance>"
26
+ ```
27
+
28
+ ## Bug
29
+
30
+ ```sh
31
+ context-guard record-bad-case --root "<project>" --session "<session-id>" \
32
+ --signal "<signal-id>" --node <id> --title "<title>" --phenomenon "<what-failed>"
33
+ ```
34
+
35
+ ## 新节点
36
+
37
+ Executor 需要新职责时用 `map apply` 提交 create，带上 `owns` 与 `proposalEvidence`，由 Coordinator 会话里的人确认。Coordinator 使用注入目录中的稳定父节点 ID、记录所属 `nodeId` 与当前 Main 版本调用 `edit_map`；可以先草稿，进 Main 再过门禁。页面收到提交事件后负责渲染节点和动效。两者都不能直接改 `map.json`，冲突后先重读权威 Main，再按原操作身份核对回执。
38
+
39
+ ## 挂错了
40
+
41
+ 用户说挂错了：重新读取相关节点，自行检查职责与 owns，给出修订建议和依据，不要求用户找出正确节点。只有需求范围仍有歧义时才问业务问题。改完把挂载与摘要再交给用户审核；需要新节点时仍走提案，不得自己确认。
package/references/map-read.md ADDED
@@ -0,0 +1,50 @@
1
+ # 读取 Map
2
+
3
+ 第一次使用时通读本文，学会怎么调用。以后直接读已发布 Main。需要或忘记时再打开本文。
4
+
5
+ Map 是整个项目的记忆。命令细节以 [workbench-interface.md](workbench-interface.md) 为准。
6
+
7
+ ## 读哪一张图
8
+
9
+ Ask user 与路由只读**已发布 Main**。Session 草稿不是项目事实，不得用来判断意图或挂载节点。
10
+
11
+ 没有已发布 Main 时如实说明，不得用未发布图顶替。项目选用服务器记忆时，权威来源见 [server-memory.md](server-memory.md)。
12
+
13
+ ## 怎么读
14
+
15
+ 先读足以定位职责的导航（节点标题与职责），再读目标节点上的记忆、Idea、Todo、Bug。按需读取，不要把整张 Map 贴进对话。不要 Grep 整个 `.codex/context/`。当活动接口已经暴露 Filesystem v2 投影时，从目标 `index.md` 跟随 Markdown 链接；链接就是跳转。Agent 打开模块时先读哪套目录（FIND.md / snapshot 与 v2）尚未拍板，不得在本文选边。
16
+
17
+ 已知节点时，从该节点读起。未知节点时，沿 Map 的模块与职责定位，不得猜测一个不存在的节点。专用检索是可选加速，不是必经步骤。
18
+
19
+ 事项当前所在节点只是检索起点，不自动等于最终执行节点。Coordinator 应根据需求读取候选节点的职责与 owns 后推荐挂载位置，不把查图工作交给用户。
20
+
21
+ 指定节点时，只取该节点及其直接相关记录，不自动展开子树，不读取邻接节点的未授权内容。
22
+
23
+ ## 命令
24
+
25
+ 本地会话首次承担 Coordinator 时，用 `context-guard workbench --root <project> --session <actual-session-id> --role coordinator` 显式记录上下文身份；该标记只控制上下文投递，不授予 Main 写权。
26
+
27
+ 本地：
28
+
29
+ ```sh
30
+ context-guard map read --root "<project>" --session "<session-id>" --node <id>
31
+ context-guard map changes --root "<project>" --session "<session-id>" --cursor "<last-cursor>"
32
+ ```
33
+
34
+ `map read` 返回该时刻的权威内容与 `version`。缺少 cursor 表示读取当前状态，不是「没有变化」。错误码与页面草稿门禁见 [workbench-interface.md](workbench-interface.md)。
35
+
36
+ Cloud 读取已发布 Main 使用 `workbench.read`，`scope=main`。省略 version 时取当前已发布版本，随后分页与路由必须固定该版本。见 [接口契约](https://github.com/Michel-Johnson/Context-Guard-Cloud/blob/main/docs/interface.md)。
37
+
38
+ ## 版本
39
+
40
+ Cloud 每轮提供 Main 节点目录；事项对话还提供节点祖先链和分级记忆。目录用于定位，旧对话不能代替 `read_task` 等权威读取；Main 版本变化后使用新目录。
41
+
42
+ 记下本次读取的 Main 版本。后续挂载、交接与审计划都使用这一版，不得改口成「最新」。指定的历史版本不可用时失败，不得偷偷换成另一版。
43
+
44
+ ## 页面导航
45
+
46
+ `read_map` 会同步聚焦被读取的节点，但不修改 Map。逐层读取时按实际层级调用，不用文字声称已完成页面操作。
47
+
48
+ 用户明确要求打开、进入、跳转或定位已确定的节点时，直接调用 `open_node`，不改成推荐按钮。只有同名或多个候选不能唯一定位时，才用 `ask_user.nodeIds` 澄清。
49
+
50
+ 用户要求演示、展示或游览 Map 时，选 2～4 个有代表性的现有节点调用 `tour_nodes`；完成后简述展示内容，不要求用户逐个点击。演示不授予修改权限。