@dsh-workbench/core 0.1.9 → 0.1.11

package/skills/workbench-module-diy/STEPS.md

@@ -0,0 +1,93 @@
+# 三步：每一步问什么、要定什么、什么时候算做完
+
+[DESIGN.md](DESIGN.md) 是三张表的来历，本文是每一步的**问法**与**完成判据**。
+
+## 步骤 1 — 面板：他看什么，他配什么
+
+先问出来（一次问一组，每组带推荐答案）：
+
+- 打开这块面板，他**第一眼**要看到什么？他拿这个答案去做什么决定？
+- 哪些事他要能自己配？配完以后，他看到的会有什么不同？
+- 哪些事他一定会说给 agent 听？**那句话原文**是什么？
+
+要定的四件事：
+
+1. **展示清单**（每条一句人话）：这一格是什么、一眼能得出什么结论、点一下可以去哪（去平台看详情 / 交给 agent）。详情、评论、流转、日志这类**零散操作不在面板做**。
+2. **配置清单**：用他的话说清 这管什么 / 默认是什么 / 他能选的值从哪来 / 选错了会怎样 / 按项目分别记 / 他自己按的才生效 / 怎么清掉。
+3. **分流**：他会反复做、要动平台上东西的事 → 交给 agent；一次要动好几下、要等很久、中途要他登录或点头、失败要能接着来的 → 封成一个动作，给他一个按钮（+ 一个交给 agent 的入口）；只是看看 → 只读呈现。
+4. **状态矩阵**：每种状态下"屏幕上是什么 + 他能做什么 + agent 能接着做什么"。
+
+**这一步做完要给他看的**：**ASCII 画面** —— 卡片、设置面、每一种状态都画出来 + 状态矩阵（左列图号）与图例。
+
+**完成判据**
+
+- 他**对着这些图**看过每一种状态，说过"就这样"或指出了哪一格不对。
+- 表里每一格都是他**看得见或能操作**的事，没有一句"系统内部会…"。
+- 矩阵里每个词都在图例里指到了屏幕上的样子；没有图例，或图例里只有同义词，都算没写完。
+- 每种缺失都有一句**能照做**的话：缺什么、去哪补、谁补（他 / agent / 平台）。
+- 每个控件都能翻译成一句他对 agent 说的话，且那句话在界面上有位置。
+- 每种状态都有设计 —— 真机上造不出来的那些也要写。
+
+→ 清单怎么写、界面习惯、状态话术：[PANEL.md](PANEL.md)
+
+## 步骤 2 — agent：他能替用户做什么，哪几件要用户点头
+
+先问出来：
+
+- 他会怎么跟 agent 说这件事？agent 得先知道什么才不用猜？
+- agent 做完，他需要知道什么？
+- 哪几件是**真的动手了**、他必须先点头？点头时他想看到什么，才敢点？
+
+要定的五件事：
+
+1. **能力清单**：每件事一句"agent 能做什么"；并说清它为什么是一件独立的事，而不是已有一件事的一个选项。
+2. **传什么 / 拿回什么**：**贴真实的那一段** —— 真实调用（参数 JSON）＋ 真实返回正文（**照抄，不转述**），再附默认值（不给等于什么）、上限（要多少给多少，**不悄悄截**）、范围（只认哪几个值）、给错怎么改。凡是"大概是这样的"，都不算。
+3. **每件事的全场景**：正常 / 没有 / **说不清是哪一份**（不许猜，让他选）/ 参数不对 / 超出上限 / 能力还没装好 / 平台要登录或超时 / 还有下一批 / 太长截断了（说清截了什么、多少）/ 没有正在做的项目。
+4. **动手的事分两拍**：先预览（说清**将要做什么**，让他确认），再真的做。预览的话要让他能判断"要不要做"，不是"要不要允许"。
+5. **哪几件要点头**：会改平台上东西的、会改这台机器的、会改他面板的。
+   - 点头时他要看到**这次真的会发生什么**（哪一个对象、什么版本、到什么环境），不是"这个操作会写数据"。
+   - **说不清这次会发生什么就不许问**：停下，把原因告诉 agent 让它去查 —— 用户不该为一个看不清的后果点头。
+
+**这一步做完要给他看的**：**真实的调用与返回**，一条一条贴出来给他看（不是概述）：能打到平台就真跑一遍、把记录贴出来；打不到就用真实代码产出的输出，并标明哪些值是样例。
+
+**完成判据**
+
+- 每件事的每种情况都有确定结果；拒绝的话里带 agent 能照做的下一步。
+- 每一件都贴着**真实调用与真实返回**（照抄的正文，不是转述）；边界情况给的是**真实的报错原文**。
+- "说不清是哪一份"这一格不许猜，也不许悄悄退回默认。
+- 截断、越界、分页都说清了边界在哪、下一批怎么拿。
+- 点头那一格写的是"会发生什么"，不是"这是什么操作"；补不齐后果的那条路是**停下**，不是硬问。
+- 用户自己按的那个入口不需要点头，但和 agent 走的是同一件事、看到同一个结果。
+
+→ 能力怎么划、点头全场景、预览怎么写：[TOOLS.md](TOOLS.md)
+
+## 步骤 3 — 联动：agent 做完，用户看到什么
+
+先问出来：
+
+- agent 改完，他需要多久看到、看到哪一格变？
+- agent 只是**读**了一下（看一眼），面板该不该动、动哪一格？（口径：读的是这一格 → 这一格变；
+  读的是面板上没有的东西 → 不动。见 [LINKAGE.md](LINKAGE.md) §1）
+- agent 正在干（要几分钟）的时候，他看哪儿？
+- 他点"交给 agent"之后，agent 手上拿到的是什么？
+
+要定的五件事：
+
+1. **什么时候面板该动**：agent **读了这一格** → 那一格按最窄切片变（值跟对话里那份一样）；读的是面板上没有的东西（明细 / 日志 / 某档子集）→ **不动**；只预览 → **不动**；真的做了 → 那一格变成新值；他自己按的动作 → 那一格立刻变。
+2. **正在干的时候**：显示到哪一步、要登录给他链接、失败给他原因和原始输出；**不画进度条、不画流程控制台**。
+3. **"交给 agent"之后 agent 拿到什么**：哪一类、哪个对象、多少，加一句"该用哪个能力再往下拿"（agent 打不开面板上那个 ↗，明细得靠它自己再问一次）。
+4. **收起模块 = 这个项目里 agent 也做不了这件事**，要在一开始就说清。
+5. **面板凭什么不旧**：切项目、别的窗口也在改、程序刚更新过 —— 这三种都要么实时、要么说清。
+
+**这一步做完要给他看的**：**"变之前 / 变之后"两张 ASCII 并排** + 一张联动表（每格说清什么时候变、哪一格变）。
+
+**完成判据**
+
+- 他**对着那两张图**看过至少一次真实的变化（agent 做完面板变成什么样）。
+- 每一格都说清"什么时候变、哪一格变、用户看到什么"，没有"刷新一下"这类模糊说法；
+  "哪一格"要细到能落成"某条投影 + 最窄那个参数"（`cmdb/builds?env=dev` 这种），
+  不然实现的人只会整卡重读（[LINKAGE.md](LINKAGE.md) §1 末段）。
+- 面板自己永远不会停在旧值上（允许有延迟，但延迟要说清）。
+- 每一颗"交给 agent"都说清了进到 agent 眼里的那段话是什么。
+
+→ 联动场景表：[LINKAGE.md](LINKAGE.md)

package/skills/workbench-module-diy/TOOLS.md

@@ -0,0 +1,112 @@
+# agent 能力：他能替用户做什么，哪几件要用户点头
+
+步骤 2 的参考。写的是"agent 传什么拿回什么、用户看到什么"，不是怎么实现。
+
+## 1 能力怎么划
+
+| 情况 | 结论 |
+|---|---|
+| 同一件事、同一份数据，只是"要不要展开明细" | **一件事**，加一个"展开"的选项（agent 少学一件事，也少花上下文） |
+| 不同的动作、不同的后果（一个只是看，一个会改东西） | **分开** |
+| 用户要反复做、而且每次都得他本人点头 | 别硬拆成一堆小事；考虑封成一个动作（一个按钮 + 一件事） |
+
+每件事都要能回答："用户会怎么跟 agent 说这件事？"
+
+## 2 传什么，怎么写清
+
+**写法：贴真实的那一段。** 一件能力＝真实调用（参数 JSON）＋ 真实返回正文（**照抄，不转述**）；"大概返回一个列表"这种句子不算写清。参数 schema 也要照抄一份（模型每轮都收到它）。
+
+**哪来的"真实"**：能打到平台就**真跑一遍**、把记录粘进来（最好连时间戳一起）；打不到就用真实代码产出的输出，并在旁边标明哪些值是样例。**实现之后**换成真机记录。
+
+- **字段名用人和 agent 都懂的话**（别用平台内部字段名）。
+- **默认值**：不给他什么，等于什么。
+- **范围**：只认哪几个值（例：严重度只认"严重 / 错误"）；值不对就拒绝并说清怎么改。
+- **上限**：要多少给多少，**不悄悄截**；超了就说清上限是多少。
+- **该先问谁**：这件事需要先拿到别的东西（先看能流转到哪、先看成员名单），就在描述里指给 agent 看（"先调 X 拿到目标值"）。
+- **会改变行为的话要留着**：默认只预览、要点头、别连刷、同一个做了一半的接着问。
+
+## 3 拿回什么
+
+- 只放 **agent 推不出来的事实**：口径 + 数字 / 每一行 + 平台链接 + "要更多明细该走哪一步"。
+- 口径复述、"这是最后一批"、"你打不开链接"这类全删 —— 那是废话。
+- **截断要说清**：截了什么、截了多少、完整的那份在哪。
+- **总数读不到就说读不到**（例：手上这份能力给不出精确总数），不拿这一页冒充实测总数。
+- **每一页都要能往下走**：给能接着问的标识 + 还有多少 + 下一批怎么要。
+- 长编号原样保留（别让它被当成数字，转一次就可能查到别的东西）。
+
+## 4 每件事的全场景（一格不许空）
+
+每一格写**真实的返回或真实的报错原文**（照抄），不写"会报错说清原因"这类转述 —— 转述会在实现时被重新编一遍。
+
+| 情况 | 必须给什么 |
+|---|---|
+| 正常 | 口径 + 数字 / 行 + 链接 |
+| 没有 | 说"没有"并给依据（不是报错）+ 下一步 |
+| 分不清是哪一份 | 把候选举出来让他选；**不许猜、不许悄悄用默认那份** |
+| 参数不对 | 说清哪个字段、该给什么，让 agent 自己能改 |
+| 超出上限 | 拒绝并说清上限 |
+| 能力还没装好 | 缺的是哪一件 + 该去哪更新它 |
+| 平台要登录 / 超时 | 分开说，并给一条重试或去登录的路 |
+| 还有下一批 | 这一页给了什么 + 下一批怎么要 |
+| 太长截断 | 截了什么、多少、完整的那份在哪 |
+| 没有正在做的项目 | 说清这件事按哪个项目取数 |
+
+## 5 动手的事：两拍
+
+1. **第一拍（预览）**：说清**将要做什么**——哪一个对象、什么值、到哪去；然后请他确认。
+   预览的话要让他能判断"要不要做"，不是"要不要允许"。
+2. **第二拍（真的做）**：只有他确认之后才真的动平台，并回话说做完了。
+
+- 一件事只做一条链路：他按按钮走的和 agent 走的是**同一件事**，结果一样、状态一样。
+- **重复发起要安全**：先看平台上是不是已经有一条（已经建了 / 已经发了），不重复触发；同一对象正在做就接着看那一次，不新开一次。
+
+## 6 哪几件要用户点头
+
+三条判据，命中任一就要点头：
+
+1. 会改**平台上**的东西；
+2. 会改**这台机器**（装 / 卸 / 更新）；
+3. 会改**他自己的面板**（加 / 收 / 排序 / 清空）。
+
+点头时，用户要看到的是**这次真的会发生什么**：
+
+- 哪一个对象、什么值 / 什么版本、到什么环境、影响几台；
+- 一句"这一步会真的做什么"（例："这一步会真的合并分支"）；
+- **不是**"这个操作会写数据"这种空话。
+
+**硬要求：说不清这次会发生什么，就不许问。**
+
+- 缺东西就**先自己去看一遍**（走一遍预览，不真的动），把确定的事实摆出来；
+- 补不齐就**停下**，把原因交给 agent 去查 —— 不许让弹窗指挥用户去指挥 agent；
+- 用户侧不该出现"看不到版本 / 分不清是哪个项目"这类话（他根本不该在这个状态下被问）。
+
+## 7 点头的全场景
+
+| 情况 | 用户看到什么 | agent 得到什么 |
+|---|---|---|
+| 预览（还没到真的做） | 什么都不弹 | 预览的话：将要做什么 |
+| 真的做，且料齐 | 弹出的问话：**这次会发生什么**（几行确定的事实）+ "允许吗" | 等他答 |
+| 料补不齐（没绑定 / 平台读不到 / 关键值缺） | **不弹**（他不该被问） | 停下的原因 → 去查 |
+| 他拒绝 | 弹窗关掉 | 被拒的原因 |
+| 他这一轮没回答就中断了 | 弹窗消失 | 这一轮结束 |
+| 他设了"后台不许问" | 不弹 | 自动不许做（后台不许问，就不许做） |
+| 这件事在他当前项目里没开 | 不弹 | 能力根本不在手上 |
+| 一口气连着要好几件 | 一次一条，逐条问 | 逐条等 |
+| 项目对不上 | 不弹 | 说清是哪个项目的事 |
+| 他点头之后中途情况变了 | 弹窗里的料是当时那一份 | 失败原因要能照做 |
+
+问答的按钮、快捷键、弹窗本身都是现成的（不是这个模块自己画）；模块能决定的是**里面那块明细画什么**。那块明细要自己排版：**一行一个事实**，别一行塞三句。
+
+## 8 用户自己按的那个入口
+
+他自己按按钮发起的事**不问他**（是他自己按的），但：
+
+- 给他一个最小的确认条（将要做什么 + 取消 / 执行）；按下去之后按钮自己变成"正在做…"；
+- 做失败留在条里说原因，不假装成功；
+- 和 agent 走的是同一件事、同一个进度、同一个结果。
+
+## 9 范例
+
+- 先摸清能流转到哪、再动手；预览 → 确认；每一页给下一层的标识；参数错了让 agent 自己能改：`.scratch/coding-analysis/spec.md` §5.2（每一页给下一层的标识）/ §5.3（参数错了让 agent 自己能改）。
+- 封成一个动作的发布：一跳、随时可续、失败给原始输出、点头时把"版本 / 环境 / 配置 / 分支 / 目标主机"摆出来：`.scratch/cmdb-module/spec.md` §5.1（工具与参数）/ §5.2（逐字返回）/ §5.4（点头时他看到什么）/ §6（联动）。
+- 一句话："只放 agent 推不出来的事实"：`.scratch/coding-analysis/spec.md` §5.1 的 token 一条。