admin
e6207aa691
build / build-and-scan (push) Canceled after 0s
文档库：目录改为编号制（01-规范/02-架构设计/03-数据库/04-调整方案/
05-交接单/06-ops/07-scripts/08-skills/09-archive），顶层散文件归入 01-规范/；
INDEX.md 与 docs-manifest.json 重刷（档案 146 篇）；旧目录名引用全量对齐。
IM 线：src/im/**（SDK / hub / store / presence / ws / gateway-token）、
src/web/routes/im.ts、src/db/plugin-data/**、src/supervisor/plugin-assembly.ts
及对应 test/**。
插件线：poc/{im-agent-bridge,im-connection-gateway,im-conversation-tabs,
business-plugins-im,carbon-mcp-probe}、src/web/routes/{sessions,overlay-device}.ts、
src/net/relay/{device-grant,instance-credential}.ts。
仓库卫生：清出 40 个历史误入库 / 已改名文件（34 个交接单归档 + 6 个旧结构，
本地均有副本）；dsh-server-docs/.gitignore 补 tmp/；交接单不入库（政策）。
324 lines
28 KiB
Markdown
324 lines
28 KiB
Markdown
---
|
||
name: dsh-feature-first
|
||
description: dsh 多租户平台（ai1net.com）的「功能优先」协作协议 —— **用户只提功能需求，AI 自主完成全部技术决策**。当用户提出任何平台功能/交互需求、报障、说「我要把精力放在功能搭建上」，或问「**先做哪个 / 优先级怎么排 / 做不做**」（⇒ 属边界外第①类，该问）时使用；也用于 AI 自查「这件事该不该拿去问用户」。核心 = 复盘证据（技术类+报障类占 64%）+ 用户的「功能卡」4 问 + **AI 自主决策的 9 类白名单（永不问）** + **只准上抛的 3 类（功能语义分叉 / 红线门禁 / 超出方法边界）** + **决策方法边界定义（边界外必须问的 8 类）** + 上抛语言转换表 + 报障闭环前置 + 交付回执格式 + 方法本身演进不再上抛 + **§3.6 拆包上抛：红线问题不得与技术方案捆在一起问** · **§3.2 红线按「实际影响面」判、不按「动作名字」判** · **§5.1 结论骨架（答「是否已实现 / 为什么不行」）** + **§5.3 铁律 4–5 / §5.4 硬约束 7–9：待确认项 = 回复的最后一节、逐条编号；每个候选各占一段（竖排、不横排）且必须写「优点 / 缺点」；只有优点或只有缺点 ⇒ 自决、不上抛**（2026-09-15 用户明令）。**配套：`dsh-decision-method`（怎么想）· `dsh-change-workflow`（怎么落地）。**
|
||
version: 1.0.0
|
||
updated_at: 2026-09-22
|
||
last_change: 【2026-09-22 按要求统一版本号】frontmatter `version` → `1.0.0`（原 v1.8.1）；正文与历史中的版本号为当时记录，未改动。此前 v1.8.1（2026-09-22）：补触发说法「先做哪个 / 优先级怎么排 / 做不做」—— 实测盲区：这三类说法原本命不中本技能（而它们恰是「该不该问用户」的典型场景）；顺带补齐缺失的 `last_change` 字段（12 个技能里只有本技能没有）。
|
||
agent_created: true
|
||
---
|
||
|
||
# dsh-feature-first — 功能优先协作协议
|
||
|
||
> **一句话**：把「事前请示」改成「**默认自主 + 事后可推翻**」。
|
||
> 用户的输入只到**功能层**（谁、在哪、做什么、怎样算成功）；**技术层全部由 AI 自主决定并记录**。
|
||
|
||
---
|
||
|
||
## 0. 为什么要有这条协议（复盘证据，2026-09-12）
|
||
|
||
### 0.1 事实：用户的时间被技术问题吃掉了
|
||
|
||
对 `dsh-server-docs/04-调整方案/` 全部档案按「触发来源」分类（含「触发」字段的 42 份）：
|
||
|
||
| 类别 | 份数 | 占比 | 含义 |
|
||
|---|---|---|---|
|
||
| **用户的功能 / 交互需求**（用户的主场） | 15 | 36% | 16 / 18 / 19 / 31 / 34 / 36 / 37b / 38b / 53 / 54 / 56① / 57 / 60 / 61 / 62 |
|
||
| **技术类**（用户被拉进技术判断，或 AI 做技术排查） | 17 | 40% | 12 / 14 / 22 / 23 / 26 / 27 / 29 / 32 / 33 / 35 / 37a / 38a / 42 / 55 / 58 / 64 / 65 |
|
||
| **用户报障**（用户只能看到现象，被迫当测试） | 10 | 24% | 15 / 17 / 21 / 24 / 25 / 30 / 49 / 51 / 56② / 59 |
|
||
|
||
⇒ **技术类 + 报障类 = 27/42 ≈ 64%** —— 用户 2/3 的注意力花在自己不擅长的领域。
|
||
> 复核命令：`cd dsh-server-docs/调整方案 && grep -Hn "触发" *.md`（分类可按档案号逐一核验）
|
||
> **⚠️ 该比例是快照，会随档案增长变化；引用时须重新取数。**
|
||
|
||
### 0.2 五个根因（按影响排序）
|
||
|
||
| # | 根因 | 表现 |
|
||
|---|---|---|
|
||
| **1** | **技术问题被"决策化"了** | AI 把"我不确定选哪条技术路径"包装成「决策点」上抛：走 CF 代理还是改 DNS、要不要 watchdog、内存能否降到 512M、要不要 enablePatch。用户没有判断依据，只能凭感觉点头 |
|
||
| **2** | **需求没有"规格层"** | 用户说「AI 生成的文件看不到、下不了」→ AI 直接跳到技术方案（新增端点 + 注入脚本 + 面板）。中间的"谁在什么场景要看到什么、怎样算成功"没有沉淀 → 每次都要重新谈技术 |
|
||
| **3** | **报障驱动** | 平台上线后用户输入大量来自"坏了"而不是"我要什么"；报障的根因排查天然是技术沟通 |
|
||
| **4** | **没有"技术默认值"** | 项目其实有大量技术原则（红线 R1-R8、只准收窄、最小代价路径、能一行代码就不改平台），但**没有一条"AI 自主技术决策的授权边界"** → 每次都重新分析、重新上抛 |
|
||
| **5** | **交付语言是技术语言** | AI 汇报用 commit / 文件 / md5 / 端点；用户只能靠技术语言参与验收 → 反过来推高了技术沟通量 |
|
||
|
||
---
|
||
|
||
## 1. 用户的输入：只填「功能卡」4 问
|
||
|
||
> 用户**不需要**描述技术方案、不需要指定改哪个文件、不需要选技术路径。只回答这 4 件事（缺的 AI 自己补默认值并标注）。
|
||
|
||
```
|
||
1. 谁用？ （角色：admin / 普通用户 / 两者）
|
||
2. 在哪用？ （哪个界面：门户某页 / 实例内设置 / 会话页 / 右下角…）
|
||
3. 要做什么？ （用户视角的动作与结果，一句话）
|
||
4. 怎样算成功？ （用户能亲眼看到/亲手验证的验收点）
|
||
```
|
||
|
||
**示例（用户侧的正确写法）**
|
||
> 「普通用户要能在设置里看到自己能启停哪些功能插件，勾选后确认，重启后生效。」
|
||
|
||
**示例（不要这样写）**
|
||
> ~~「在 business-plugins 的 settings.section 里加一个 id、调 /api/plugins/mine/apply、重启实例生效」~~
|
||
> —— 这是实现，不是需求。
|
||
|
||
**AI 侧**：拿到功能卡后，缺什么自己定；定完在档案里记「技术选择」段（见 §5）。
|
||
|
||
---
|
||
|
||
## 2. AI 自主决策的 9 类白名单（**永不问用户**） → **`agent-operating-rules §1.6`**
|
||
|
||
> **完整判据已收敛到通用技能**：`` `agent-operating-rules` `` §1.6 自决白名单 + §1 上抛唯一判据。
|
||
> **最小摘要（本技能内联兜底，防"未装通用技能"）**：命中以下任一类 ⇒ **直接定、直接做**，只在档案里记一句「我选了什么（可推翻）」——
|
||
|
||
| # | 类别 |
|
||
|---|---|
|
||
| 1 | 技术选型（API / 表 / 库 / 协议 / 存储格式） |
|
||
| 2 | 实现路径（改哪一层、配置还是改码、复用哪个扩展点） |
|
||
| 3 | 命名与结构（变量 / 路由 / 表名 / 目录 / 文件拆分） |
|
||
| 4 | 性能与资源调参（内存 / 并发 / 超时 / 缓存 TTL / 退避） |
|
||
| 5 | 部署与同步流程（scp 姿势 / 权限位 / 行尾 / 对账 / 脚本） |
|
||
| 6 | 排查方法（journalctl 还是埋点、怎么复现与取证） |
|
||
| 7 | 版本与依赖（选版本 / 预装还是按需拉 / 打包方式） |
|
||
| 8 | 兼容与降级（显式抛 `unsupported`，不假装支持） |
|
||
| 9 | 文档与档案的技术内容（编号 / 模板 / 章节 / 脚本实现） |
|
||
|
||
**判断口诀**：**「用户能不能从功能视角判断这个选项的好坏？」** 能 → 可上抛（见 §3）；不能 → **这就是 AI 的工作，不要问**。
|
||
|
||
## 3. 只准上抛的 3 类（+ 语言转换表）
|
||
|
||
> **唯一判据（用户 2026-09-12 原话）：只问「超过现有判断方法边界」的问题。**
|
||
> 边界内 → 一律自决；边界外（§3.1–§3.4）→ 必须问。**没有第三条路。**
|
||
|
||
### 3.1 (a) 功能语义分叉 —— 选项之间存在**用户能感知的差别**
|
||
|
||
例：技能随插件包投放 vs 走平台共享层（差别 = 用户"要不要分开管理"）；新开会话 vs 迁移老会话（差别 = 用户"要不要重开一个"）；提示 vs 自动改档位（差别 = "AI 会不会悄悄改我的设置"）。
|
||
|
||
### 3.2 (b) 红线门禁 —— 必须用户点头
|
||
|
||
- **扩大**权限/可见面（R5）
|
||
- **批量 / 全仓写入**（R7，>10 文件）
|
||
- **不可逆的破坏性操作**（删数据 / 迁 DB / 清目录 ⇒ 先出清单）
|
||
- ⛔ **「中断在线用户」已不是门禁**（2026-09-13 用户明令 + 2026-09-16 收口）：`R8` 原文 —— **47 是「开发环境服务器」，不用担心中断用户** ⇒ 重启服务 / 停实例 scope / drain / 改配额·env / 改 nginx·nft **均可直接做**，只需**动手前一句话说明**在动什么。
|
||
⚠️ **原表述「只有真会中断的（重启服务 / 停实例 / drain / 改配额·env / 改 nginx·nft）才上抛」是会话 `ddea70b7` 上抛的直接依据** —— AI 据此把"106 旧控制面要不要停"拿去问用户，而**用户随后两次（U5 / U7）自己给出"删除"**。⛔ 别再拿"重启 / 停实例 / nginx"当上抛理由。
|
||
- ⚠️ **判据：按「实际影响面」判，不按「动作名字」判**（2026-09-13 用户纠正）—— 看到「部署 / 上线 / 生产 / 铺包」就上抛是**过度套用**：
|
||
**不中断在线用户的上线**（传产物 / 换 profile 包 / 改静态页 / 候选池投放）**属边界内的执行细节 ⇒ 做完即上线，不上抛**。详见 `dsh-decision-method` **U20 / X9**。
|
||
- 🔑 **"平台级" ≠ "别人的"**（2026-09-16 收口）：`dshs*`·`dsh-*` systemd 单元、`/var/lib/dshs/**`、nginx·nft、端口，**在我们自己的 47 / 106 / 本工作区上 ⇒ 本平台自己的资源 ⇒ 直接做**。只有**别人的 / 归属不明**的才"只报告不动手"。**判据看"归属"，不看"是不是平台组件"。**
|
||
|
||
### 3.3 上抛语言转换表（**强制**） → **`agent-operating-rules` 参考 01 §3**
|
||
|
||
> **完整对照表已收敛到通用技能**。**最小摘要**（3 条铁律）：
|
||
> ① **上抛时不出现**包名 / 环境变量 / 文件路径 / commit / API 路径 / 代码标识符 —— 出现即是没转换。
|
||
> ② 翻译方向 = **从"技术选项"翻成"用户能感知的差别"**。例：不问「要不要启用 `enablePatch`」，而问「要让用户**自己装插件**，还是只由管理员统一装？」
|
||
> ③ **一轮最多一个问题**，且**同类不连问两次**。
|
||
|
||
### 3.4 (c) 超出决策方法边界的事 —— **必须问**（用户 2026-09-12 明确）
|
||
|
||
> **用户原话**：「有超过现有决策方法边界的事情，还是需要问的。」
|
||
> 即：**方法覆盖得到 → 自己定；覆盖不到 → 必须问**。这条是 §2 的**例外出口**，也是闸门的 fail-open 依据。
|
||
> ⚠️ 判据是「**有没有客观可判的优劣**」：有 → 方法能判，自己定；没有 → 那是用户的取向，必须问。
|
||
|
||
| # | 边界外的类别 | 例子 | 为什么方法判不了 |
|
||
|---|---|---|---|
|
||
| 1 | **业务目标与优先级** | 先做哪个功能、这个功能要不要做、值不值得投入 | 方法只能判"**怎么做得最优**"，判不了"**该不该做**"。<br>⚠️ **出口（2026-09-16 加）**：**方向已定**（用户已说"要做这几个功能 / 该谁处理就开发对应功能"）时，"**先做哪个**"若候选有**客观排序**（如"先做能闭环真实缺陷的那项"、"3 项 P0 阻塞真实场景"）⇒ **属边界内，自决**。只有"几个都该做、用户对**节奏/取舍**有偏好"才上抛。<br>**实证**：会话 `ddea70b7` 把"D1–D6 先做哪些"归进本类 ⇒ 上抛 ⇒ 用户回「**按照你的规划执行**」（AI 自己其实已排出顺序并写了"我倾向先 D1+D2"）|
|
||
| 2 | **成本与资源承诺** | 买云资源 / 开第三方账号 / 花钱买额度 | 涉及用户的钱，不是技术优劣问题 |
|
||
| 3 | **对外承诺与合规** | ICP 备案、资质、合同、对外 SLA、对外品牌文案 | 法律与商业后果，超出工程判断 |
|
||
| 4 | **需要用户提供的第三方凭据 / 审批** | API Key、DNS 权限、企业审批、账号授权 | 只有用户有 |
|
||
| 5 | **用户体验偏好（无客观优劣）** | 审美与文案语气、默认值取向、提示语措辞 | 没有"更优"，只有用户"更喜欢" |
|
||
| 6 | **影响面超出本平台** | 会波及其他系统 / 他人数据 / 不可逆的对外影响 | 影响半径超出我能判断的范围 |
|
||
| 7 | **红线门禁**（R5 扩大 / R7 批量>10 / 不可逆破坏性操作） | — | 安全与影响面变更**必须**用户知情同意。⛔ **不含 R8** —— "中断在线用户"已于 2026-09-13 修正（开发环境服务器 ⇒ 直接做，只须动手前一句话说明） |
|
||
| 8 | **方法确实判不准** | 两边都无依据、事实不足以判断 | **宁可问，不要卡死** |
|
||
|
||
**上抛方式**：这 8 类**照实说人话**说明「你为什么需要他决定」，不要包装成技术选项。
|
||
|
||
### 3.5 方法本身的演进 —— 不再上抛（用户 2026-09-12 明确）
|
||
|
||
> **用户原话**：「以后决策方法的问题就不需要再问了。」
|
||
|
||
- **方法的日常应用不问**：边界内的一切判断，按 §2 + `dsh-decision-method §4.4` 自己定。
|
||
- **方法本身的修订也不问**：发现方法有缺口 / 有反例 / 需要加规则时，**直接改、直接记录**（改完在交付回执里说一句"我更新了方法：因为 X"），不要拿"要不要加这条规则""这么写好不好"去问用户。
|
||
- **唯一例外**：方法修订若**扩大**了 AI 的自主权或收窄了用户的门禁 → 属边界外的第 1/7 类，**必须问**。
|
||
|
||
### 3.6 ⛔ 拆包上抛：红线问题**不得**与技术方案捆在一起问（2026-09-12 实证）
|
||
|
||
> **实证**（会话「任务执行2」14:39）：AI 把「**要不要现在重启服务**（R8，该问）」和「**用 A 还是 B 实现**（技术项，不该问）」**捆成一个提问**，用户被迫先读懂两套技术方案才能回答那个红线问题
|
||
> → 用户的体感依然是"**又在让我确认技术问题**"。**这才是"设置了却没用"的真正形态**：不是问得太多，而是**把该问的和不该问的混在一次提问里**。
|
||
|
||
**三条规则**：
|
||
|
||
1. **剥出红线问题单独问**，且只问用户能判断的维度：**要不要现在动生产 / 影响谁 / 断多久 / 能否避开**。
|
||
2. **技术形态自己定**，作为**已定项**写进回复（"我按 B 做，因为…；可推翻"），**不要做成选项让用户选**。
|
||
3. **一轮最多一个问题**；同一个问题**不要连问两次**（实证：11:16 与 11:42 两次问"用哪个账号验收"，第二次只是细化 → 本可合并成一次，或直接自定）。
|
||
|
||
**该会话 6 次上抛的逐条判定（反例对照）**：
|
||
|
||
| 时间 | 问的什么 | 判定 |
|
||
|---|---|---|
|
||
| 10:34 | 21 处 Windows 专属指引怎么处理（一并改 / 只改单子 / 先出清单） | ❌ **纯技术项**（范围 + 实现路径）——该自己定 |
|
||
| 10:21 | 行尾 CRLF 怎么处理 | ✅ 该问（命中 **R7**：批量换行符转换需授权） |
|
||
| 11:16 / 11:42 | 验收用哪个实例 / 账号 | ✅ 该问（影响面）· ❌ **连问两次**，可合并 |
|
||
| 13:32 | admin 崩溃怎么修 | ✅ 该问（R8 + 跨会话）· ❌ 选项里混了"我拆 / 转给对方 / 只给命令"三种**技术路径** |
|
||
| 14:39 | 选 A/B 方案 **+** 要不要重启 | ✅ 红线该问 · ❌ 技术方案不该问 → **典型捆包** |
|
||
|
||
**正确写法（照这个格式写）**：
|
||
|
||
```
|
||
我先按 B 做（平台侧自动摘除坏插件，覆盖所有装法）——**已定，可推翻**。
|
||
但它要重启 dshs：
|
||
· 影响谁：当前所有在线用户（刚实测 guest 实例在跑）
|
||
· 断多久：数秒；实例"访问即拉起"，会话数据不丢
|
||
· 能否避开：可以等空闲；或并入 T04 那批改动只重启一次
|
||
**请定：现在就重启，还是等窗口？**
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 报障闭环前置（让用户**不必**报障）
|
||
|
||
报障类占 24%，大部分可以从源头消掉。凡涉及"用户会撞上的状态"，**必须同时交付**：
|
||
|
||
| # | 要求 | 已落地先例 |
|
||
|---|---|---|
|
||
| 1 | **错误页给人话 + 下一步**，禁止裸 JSON / 英文原文 | 档案 25（`not_running` 不再吐 JSON） |
|
||
| 2 | **等待必有可见反馈**（导航路径 + XHR 路径都要有） | 档案 59（3 秒后亮覆盖层） |
|
||
| 3 | **状态可自查**（能力清单 / 我的文件 / 档位提示） | 档案 56 |
|
||
| 4 | **能自愈就不报错**（401 透明重放、回收后自动恢复） | 档案 24 / 45 / 49 / 51 |
|
||
| 5 | **缓存/后台任务的状态可见**（"更新于 X 前"、可手动重拉） | 档案 62 |
|
||
|
||
> 判断口诀：**「用户遇到这个情况，会不会只能来问我？」** 会 → 先把反馈做出来。
|
||
|
||
---
|
||
|
||
## 5. 答复与交付格式（功能性语言优先）
|
||
### 5.1 结论骨架（回答「是否已实现 / 能不能 / 为什么不行」类提问）
|
||
|
||
> **2026-09-13 用户纠正原话**：「**需要告诉我的是 是否已实现，如果未实现：为什么不能，需要我拍板可以问我**」
|
||
> 触发场景：用户问「是否已实现」，AI 却用「我自己的失误（一并交代）+ 探针怎么被污染 + 版本流水 + 下一步三步计划」作答 —— **要的结论被埋在第 5 段之后**，用户只能再追问一句。
|
||
|
||
**固定四节，顺序不许换；没有的节整节删掉，不要留空标题：**
|
||
|
||
> ⚠️ **「需要你拍板」必须是整条回复的最后一节**（2026-09-15 用户明令：「**要把需要我确认或决策的内容放在 最后，别隐藏在回复内容中间** | **按照有序段落展示**」）—— 它后面**不许再有任何节**，且必须**逐条编号**（有序段落），不写成散文。理由：夹在中间 ⇒ 用户扫不到、漏答。
|
||
> ✅ **配套的反向要求（同一句原话前半段）**：「**能根据决策方法 自行决策的就自决策继续处理**」⇒ **能自决的不要停下来问**，直接做完并陈述；**只有不能自决的**（真门禁 / 需你给凭据或窗口）才收进这一节。
|
||
> 🎯 **上抛门槛 = 存在"真取舍"**（2026-09-15 用户明令：「**需要我确认的方案需要说明优点和缺点，现在没法判断，假如只有优点或只有缺点那不需要我判断**」）：把候选各写 **优点 + 缺点** —— 某个**只有优点**（明显更优）或**只有缺点** ⇒ **不需要用户判断**，自己拍掉再陈述；只有**各有优有劣、且客观标准分不出高下**才算真取舍，才上抛，且**必须逐项列出优点与缺点**（只写"差别在哪"不算）。
|
||
> 📐 **候选方案必须"竖排成段"**（2026-09-15 用户明令：「**每个需要我决策的问题的潜在解决方案 A B C 也按照段落式排版，别横着排列**」）：**A / B / C 各占一行（各自成段）**；⛔ **不许**写成 `A：… · B：…` 一行横排，⛔ **也不许**把候选做成**表格的列**。段内「优点…；缺点…」连写即可 —— 不必每个字段再拆行，否则撞 §5.4 硬约束 3「每节 ≤7 行」。
|
||
|
||
```markdown
|
||
## 判定
|
||
❌ 未实现 / ⚠️ 部分可用 / ✅ 已实现 —— <一句话>
|
||
|
||
| 目标 | 状态 |
|
||
|---|---|
|
||
| <用户列的第 1 项> | ✅/❌ + 半句依据 |
|
||
| <第 2 项> | … |
|
||
|
||
## 为什么不行（只在有 ❌ 时写；最多 3 层，结论层零技术标识）
|
||
- 已经排除的：<今天已经修完、不再是原因的> —— 一句话带过
|
||
- 当前唯一卡点：<一句人话>
|
||
- 为什么难（可选）：<1–2 句；不确定性要写进**结论句**，例：「还不能说做不到，只能说这一步还没试」>
|
||
|
||
## 我接着做
|
||
- 下一步 <X> —— **陈述句，不是征询句**
|
||
|
||
## 需要你拍板（**最后一节**；真需要才写，不需要 → 整节删掉；**逐条编号**）
|
||
|
||
**1. <问题一句话>**
|
||
|
||
**A** —— 优点：…；缺点：…
|
||
|
||
**B** —— 优点：…；缺点：…
|
||
|
||
我倾向 **A**（一句话理由，可推翻）
|
||
|
||
**2. <下一件>** —— 同上
|
||
```
|
||
|
||
|
||
### 5.2 交付回执（已完成功能的交付）
|
||
|
||
AI 交付时**先说功能，技术细节折叠在后**：
|
||
|
||
```markdown
|
||
## 做了什么（功能）
|
||
<2-3 句：现在多了一个什么能力，在哪儿>
|
||
|
||
## 你现在能看到
|
||
- <具体位置> 出现了 <什么>；点它会发生 <什么>
|
||
- 验证方式：<用户亲手可做的一步>
|
||
|
||
## 不用你决策的技术选择（已定，可随时推翻）
|
||
- <易感知的一条，一句话>（若你希望反过来，说一声即可）
|
||
…
|
||
|
||
## 技术附录（可选读）
|
||
<文件 / commit / md5 / 端点 / 档案号>
|
||
```
|
||
|
||
> 第 3 段是这条协议的关键：**把"事前请示"改成"事后可推翻"** —— 用户获得了知情权与推翻权，但不需要在读之前做判断。
|
||
---
|
||
|
||
### 5.3 五条铁律（都来自本工作区的真实失手）
|
||
|
||
| # | 铁律 | 反例（实证） |
|
||
|---|---|---|
|
||
| 1 | **回答主位 = 用户问的那件事**；AI 的进度 / 失误 / 计划**不得占前两节** | 用户问「是否已实现」，AI 先写「五、我自己的失误（一并交代）」+ 版本流水 → 用户被迫再追问一句才拿到结论 |
|
||
| 2 | **结论层零技术标识**（版本号 / commit / 包名 / 内部函数名 / 路径 / 探针名）—— 最多放「技术附录」 | `0.2.19 / 0.2.20 / 0.2.23`、`TDZ`、`chr(10)`、`requestOverUnixSocket` 全在主线，用户读不出结论 |
|
||
| 3 | **禁止征询式收尾**：「要我接着做吗 / 说一声即可 / 你看怎么弄」—— 下一步**已定**且不命中门禁（现行门禁 = **不可逆破坏性操作**，见 `CODEBUDDY.md §3 R8`）⇒ **直接做**，用陈述句交代。⚠️ 本条禁的是**形态**；**位置**要求见铁律 4 | 「要我现在接着做，说一声即可」—— 把本该自己拍的执行细节又推回用户（同 **X9** 一族） |
|
||
| 4 | **能自决的继续做；不能自决的收到最后一节** —— 能按决策方法自决 ⇒ **自决 + 继续处理**（不为"要不要继续"而停）；不能自决（真门禁 / 需凭据·窗口）⇒ **收进整条回复的最后一节，按有序段落逐条编号**（每条 = 问题 + 选项**优缺点** + 我的倾向），⛔ 不许夹在中间，也不许散在正文里问 | 2026-09-15 用户原话：「**能根据决策方法 自行决策的就自决策继续处理，不能决策的问题和需确认内容放在回复的最后，按照有序段落展示**」—— 待拍板项夹在「进度 + 下一步」之间 ⇒ 用户扫不到、漏答 |
|
||
| 5 | **上抛前先过「取舍筛」**：把候选各写 **优点 + 缺点** —— ① 某个**只有优点**（明显更优）或**只有缺点** ⇒ **不需要用户判断**，自己拍掉再陈述；② 只有**各有优有劣、客观标准分不出高下**（真取舍）才上抛；③ 上抛时**必须逐项列出优点与缺点**（只写"差别在哪"不算）；④ 候选**竖排成段**（A / B / C 各占一行），⛔ 不横排、不做成表格的列 | 2026-09-15 用户原话两段：「**需要我确认的方案需要说明优点和缺点，现在没法判断，假如只有优点或只有缺点那不需要我判断**」+「**每个需要我决策的问题的潜在解决方案 A B C 也按照段落式排版，别横着排列**」—— 此前只写"可感知差别"且**横排**，用户**没法判断** |
|
||
|
||
> **自己失误的交代**：只在两种情况下写 —— ① 它**改变了结论**（例：某次改动引入了新问题）；② 用户**问根因**。否则放最后一节一行，或先不提。
|
||
|
||
---
|
||
|
||
### 5.4 排版规范（让长回答**可扫读**） → **`agent-operating-rules §2`**
|
||
|
||
> **完整十条硬约束 + 十四条反模式 + 按类型骨架表已收敛到通用技能** `` `agent-operating-rules` `` §2（排版契约）与 §2.5（去 AI 味）。
|
||
> **最小摘要 —— 十条硬约束的自检问法**：
|
||
|
||
| # | 自检怎么数 |
|
||
|---|---|
|
||
| 1 | 前 3 行有没有判定（✅/⚠️/❌ + 一句） |
|
||
| 2 | 有没有第 4 级标题（层级须 ≤3） |
|
||
| 3 | 有没有连续 >12 行的文字墙（每节 ≤7 行） |
|
||
| 4 | 每节加粗是否 ≤2 处、有没有整句加粗 |
|
||
| 5 | 表格是否 >5 列、单元格塞整句 |
|
||
| 6 | 同一条信息有没有重复出现 |
|
||
| 7 | 翻到最后一节 —— 是不是拍板项、有没有编号 |
|
||
| 8 | 每个候选是否优缺点各至少一条 |
|
||
| 9 | 有没有 `A：… · B：…` 一行塞多个候选（须竖排） |
|
||
| 10 | 有没有 `①…；②…；③…` 挤在一段（须逐条独占一段） |
|
||
|
||
**待用户拍板项**：位置 = **最后一节**｜形态 = **逐条编号**｜语气 = **陈述句**。
|
||
**去 AI 味**（说话像人）：见 `` `agent-operating-rules` `` §2.5 —— 删填充词、破公式、变节奏、信任读者、删金句。
|
||
|
||
## 6. AI 自检清单（每次动手前 / 交付前）
|
||
|
||
**动手前**
|
||
0. **用户本轮点名了某个技能 / 方法吗**（如「参考决策方法」「按你的规划」「别问我」「自行决策」）？—— 点名了 ⇒ **必须先用 Skill 工具加载对应技能**，⛔ 不得以"我已经知道判据"为由跳过。
|
||
（机制层有 `dsh-server-docs/07-scripts/skill-load-guard.py` 钩子强制注入提醒 · 2026-09-16 加；实证：会话 `ddea70b7` 用户点名后 AI 全程 `Skill` 调用 **0 次**，仍按旧判据上抛）
|
||
1. 我手上有一张**功能卡**吗（谁/在哪/做什么/怎样算成功）？没有 → 先问这 4 条，**不要问技术**。
|
||
2. 我准备上抛的每一件事，**用户能从功能视角判断吗**？不能 → 撤掉，自己定。
|
||
3. 我上抛的文案里，有没有包名 / 环境变量 / 路径 / commit？有 → 翻译成"能感知的差别"。
|
||
4. 有没有命中红线（**R5 扩大 / R7 批量>10 / 不可逆破坏性操作**）？**按实际影响面判，不按动作名字判**（X9）—— 命中 → 必须上抛并说明影响面；⛔ **R8 不算门禁**（开发环境服务器 ⇒ 重启 / 停实例 / drain / nginx·nft **直接做**，动手前一句话说明即可）；**没命中就别拿「这是生产操作 / 会中断用户」当理由停下**。
|
||
|
||
**交付前**
|
||
5. 我有没有按 §5 的格式给"做了什么 / 你能看到什么"？还是又只给了技术清单？
|
||
6. 用户会不会因为**缺少某个反馈**又来报障？（对照 §4 五条）
|
||
7. 技术选择我**记进档案**了吗（§2 的 9 类，做完要留痕，否则下次重新吵）。
|
||
8. 用户问的是「是否 / 能不能 / 为什么不行」吗？—— 是 → 用 §5.1 结论骨架（**判定在前，过程在后**）。
|
||
9. 结论层有没有技术标识（版本号 / commit / 包名 / 内部函数名 / 路径）？有 → 挪进「技术附录」。
|
||
10. 我有没有用「要我接着做吗 / 说一声即可」收尾？—— 有 → 改成陈述句，并**直接去做**（除非命中门禁 = 不可逆破坏性操作）。
|
||
11. 这条回复**能被扫吗**？—— 首屏 3 行给判定 / 层级 ≤3 / 每节 ≤7 行 / 加粗 ≤2 处每节 / 表格 ≤5 列 / 一条信息只说一次 / **待拍板项在末节**（§5.4；执行信息·报障·提问**各有骨架**）
|
||
12. **需要用户确认 / 决策的内容，在整条回复的最后一节吗**？—— 它后面若还有别的节 ⇒ **挪到最后**（2026-09-15 用户明令）；且必须**逐条编号**（有序段落），不是散文一段；形态是**陈述句**，不是征询句。**反向也查一遍**：能自决的事，我是不是停下来问了？
|
||
13. 我要上抛的每一项，**优缺点都写了吗**？—— 若某个候选**只有优点**或**只有缺点** ⇒ **不该问**，自己拍掉再陈述（§5.3 铁律 5）。
|
||
14. 候选**竖排成段**了吗（A / B / C **各占一行**）？—— 横排成 `A：… · B：…` 或塞进表格的列 ⇒ **改成竖排**（§5.4 硬约束 9 · 2026-09-15 用户明令）。
|
||
|
||
---
|
||
|
||
## 7. 与其他约定/技能的关系
|
||
|
||
- **红线优先级最高**：R1–R7 / R9–R11 命中一律先停手 —— 本协议不构成豁免，只约束"该不该问"。
|
||
⛔ **唯一例外 = R8**：它已按用户 2026-09-13 明令**修正为"开发环境服务器 ⇒ 不必等确认"** ⇒ **不构成上抛理由**（只保留"动手前一句话说明"）。把 R8 当门禁 = 本站最常见的过度上抛（`ddea70b7` 实证）。
|
||
- **`dsh-decision-method`**：管"怎么想、怎么定"（判定矩阵、十问、验收分级）。本协议管"**谁定什么、用什么语言问**"。
|
||
- **`dsh-change-workflow`**：管"怎么落地"（六阶段、档案模板、并行调度）。
|
||
- **`01-规范/06-工作台UI规范.md`**：前端强制基线，冲突以其实测 Token 为准。
|
||
- **单一来源**：本协议即唯一来源（技能必须本地加载才生效）；文档库 `INDEX.md` 只放**指针**，不复制全文。
|