`（+1 层 DOM） | | `src/client/settings-card.module.css` | 新增 `.injectionDiffList`；`.injectionDiff` 删 `border-top`、加 `radius-md`；`.injectionDiffToggle` padding `8px 0`→`8px 6px`、hover 合并为一条（background + color）；`.injectionPanel` padding 回 `16px 0`；`.injectionDiffBody` padding-bottom `12`→`8` | | `scripts/probe-settings-card.mjs` | 旧 3 条几何断言删除，改为 6 条（见下） | ##### 实测（真实 DSH，`pg-schemeC-home`，2 次运行一致） **38 PASS / 0 FAIL / 退出码 0 / `console errors: (none)`** ``` PASS 7) 差分区是一个带底色、且与背景有色差的整块 — {"listFill":"rgb(245, 246, 247)","backdrop":{255,255,255},"diff":27,"radius":"16px"} PASS 7) 差分区内部不再有分割线（只剩面板底边一条） — {"dividers":[],"panelDivider":true} PASS 7) 分组之间没有额外间隙（block 未再加 gap） — {"panelGap":"normal","boxGaps":[0,0]} PASS 7) 每行标签在其按钮内上下居中（±1px） — {"rows":[{8,8},{8,8},{8,8}]} PASS 7) 标题紧接底色块（8px），且面板顶部留白 16px — {"blockGapAbove":8,"topAir":16} PASS 7) 分组行有悬停底色（去线后可点击性的唯一提示） — 规则在位 ``` **两种主题都可见**（探针只跑 light，dark 由只读脚本补测）： | 主题 | listFill | backdrop | 色差 | |---|---|---|---| | light | `rgb(245,246,247)` | `rgb(255,255,255)` | **27** | | dark | `rgb(53,54,56)` | `rgb(21,21,23)` | **98** | ##### 🔴 本次自己踩到并修掉的三处（**两条真问题 + 一条假绿**） **① 断言口径错（假 FAIL，不是实现缺陷）** 初版断言②用 `panel.querySelectorAll('*')` 收集"有上下边框的元素"并断言 `<= 1`，结果把**四边框的盒子**（`.injectionText` 内容框、`.injectionDiffList` 外框）当成分割线，必然 FAIL（`{"wideLines":["KApx_W_injectionText","KApx_W_injectionDiffList"]}`）。更根本的是：`querySelectorAll('*')` **不含 context 元素自身**，所以面板底边那条**从未被计入**—— `<= 1` 这个配额从来就不可能对应它声称的那条线。 **修法**：只认**单边横线**（左右边框 = 0、上/下 > 0），并**显式**量面板自身底边。 **教训**：「有上下边框」≠「是一条分割线」；用 `querySelectorAll('*')` 量"自身"必然漏掉自己。 **② light 主题下底色块不可见（真问题）** 初版底色用 `bg-layer-1`，而官方 token 定义（`ui-theme/src/styles/design-platform.css`）显示： | 主题 | `bg-layer-1` | `bg-base` | 结果 | |---|---|---|---| | **light** | `bluish-00` = `rgb(255,255,255)` | `bluish-00` = `rgb(255,255,255)` | **同色 → 块不可见** | | dark | `bluish-875` = `rgb(35,35,36)` | `bluish-950` = `rgb(21,21,23)` | 有对比 | ⇒ **light 下"底色块"根本看不见**，方案 C 的"整体成一块"在最常用主题下失效。 **修法**：改用官方 settings 面板表达"面板上的有色编辑区"的 token **`bg-module-platform`**（出处 `ui-settings-models` 的 `.editor`，注释原话 *"a filled module on the panel, matching the settings selector fill"*）—— light `#F9FAFB`、dark `#353638`，两主题都可见。 **教训**：官方先例（`.guide` 用 `bg-layer-1`）**不等于**该 token 在 light 下可见； token 语义要看**定义**，不能只看谁用过。 **③ 断言①假绿（"非透明"不等于"看得见"）** 初版只排除 `rgba(0,0,0,0)`/`transparent`，于是 `rgb(255,255,255)`（白底白）**照样 PASS**。 **修法**：改为与**最近不透明祖先**比 RGB 色差，并把 `listFill`/`backdrop`/`diff` 写进 detail。 **教训**：断言要钉"**性质**"（可见），不是"**形式**"（非透明）。 ##### 待用户判定方案 C 已实现且护栏全绿，**但用户的观感判定尚未回填**。若判定不通过，继续试 M / A / B（§十的表格已备好记录位），且**每次都要同步改这批几何断言**。 ##### 方案 B 实施记录（2026-10-10，已实现并全绿） **用户 2026-10-10：「实现 b 吧」。** B 与 C 的差别**只有一处**： | | C（`587f0a3`，tag `scheme-C`） | B（`91f07b9`） | |---|---|---| | 三个折叠行外面 | 一个填充块（`bg-module-platform` + 圆角 + 边框） | **无容器**，行直接属于面板 | | 静态边界 | ✅ 有 | ⚠️ **无**，靠间距分开 | | hover 底色 | ✅ | ✅（**唯一**可点击提示） | | 行间分割线 | 无 | 无 | **B 的取舍被明说而非隐藏**：没有容器、没有分割线，三个折叠行在光标移上去之前 **就是三行安静的文字**。换来的是"常驻展示 + 标题"这样两段式，而不是"大框套小框"。 **实现要点（一处易踩的坑）**：标题下方的 8px 落在**第一行的 `margin-top`**， **不是按钮的 `padding-top`** —— 后者会破坏"每行标签在按钮内上下居中"这条性质，而它正是 hover 底色与标签对齐的前提，且探针会量它。 **验证**：`probe-settings-card.mjs` **38 PASS / 0 FAIL**；`pnpm check` **718 PASS**。 **🔴 一次假绿（值得记）**：首次跑出 38 PASS，但**探针 home 里是一份包副本而非 junction**，测的是旧快照。**揭穿它的是反向对照** —— 把 C 的容器加回去，本该失败却仍 38 PASS。修正 junction 后重跑反向对照，**命中 2 条**： ``` FAIL 7) 差分区没有外层容器 — {"hasEnclosingSurface":1} FAIL 7) 标题与第一行相距 8px — {"headingToFirstRow":5} ← 容器的 padding 也改了几何 ``` **教训**：反向对照不是额外保险，它是**唯一**能识别"测的不是目标物"的手段。（与 Z-9 那轮"探针按包名定位、每次超时"同型：**先确认测的是目标，再谈结果**。） - [ ] **Z-13 项目包含关系与子项目**（2026-10-10 用户提出） **用户原话**：「项目包含关系和子项目功能。」 **要做的**：让项目可以有**父子包含关系**，形成**子项目**层级。 #### 已核实的前提（立项时的代码事实） 1. **渲染层已经支持任意深度** —— `WorkspaceBrowser.tsx:1621` 的 `renderGroup(group, depth)` 已经递归：`:1639` 的 `group.expanded ? children.map(child => renderGroup(child, depth + 1)) : []`，并且 `:1734` 用 `--dsh-workspace-indent: ${depth * 12}px` 做缩进。 ⇒ **树形渲染与缩进是现成的，不用改渲染层结构。** 2. **数据模型里没有父子字段** —— `src/spec.ts` 的 `projectRecord` 只有 `title / directories / links / docPath / docSpec* / docSpecUsed / docSpecIgnored / createdAt / updatedAt`，**没有 `parentId` 一类字段**。 ⇒ 层级关系目前**无处存放**，这是本待办的主体。 3. **`GroupSource` → `GroupNode` 的管线假定扁平** —— `src/client/grouping.ts` 的 `clientGrouping` 是 `readonly GroupSource[]`， `tree.ts` 的 `groupBySource` 产出一个**扁平数组**再逐个转 `GroupNode`。 ⇒ 要支持父子，这条管线需要能表达"谁是谁的子"。 #### ⚠️ 必须守住的既有约束（与 Z-6/Z-8 同族） - **`.default(...)` 与"不能 bump version"**：`single` 布局在域打开时逐条校验，缺字段会让**整个文件打不开、连累所有项目**；而 `single` **不允许 bump version**。新增父子字段**必须带默认值**（"无父"是合法默认），**且不能 bump version**。 ⚠️ 比 Z-6 更难的一点：**父子关系不能用"缺字段=无父"之外的表达**，否则老数据读不回来。 - **删除语义**：删父项目时子项目怎么办？**级联删 / 提升为顶层 / 拒绝删除** —— 三选一，且与现有的"删项目会同时删 assignments"逻辑要对齐。 - **`projectIds` 的顺序数组**（`globalRecord.projectIds`）是**全局扁平顺序**，与树形层级是**两套顺序**：层级改变时全局顺序如何维护？ - **循环引用**：父子关系必须防环（A 父 B、B 父 A；或更长的环），因为存储层是**用户可手改的 JSON**。 #### 要定的 - **深度**：只允许一层父子，还是任意深度？（渲染层支持任意深度，是数据/UI 的限制） - **创建入口**：在父项目行上加「新建子项目」？还是拖拽改变父子关系？（拖拽已有实现，`commitWorkspaceDrag` 一族可复用） - **注入语义**：会话属于**子项目**时，注入块要不要提及其**父项目**？（这会影响 `renderProjectInjection` 与 `declaredSegments`，进而影响注入文本与断言） - **项目行显示**（与 **Z-7**、**Z-12** 同处）：折叠的父项目要不要显示 "其下有 N 个子项目"？（**Z-12 的"有会话在跑"聚合**与此同构， `g.sessions` 是否含子项目的会话需先核实） - **未分组桶**是否有子项目概念（应无）。 - **文档规范与关联目录**：子项目继承父项目吗？（这会与 `perProjectDocSpec` 交互） **未动代码。** - [x] **Z-10 改注入文案：声明段（已实施，2026-10-07）** **不是做功能，是改文案本身** —— 用户直接给出新文本，逐字替换并同步断言。 **本次改动（仅声明段，两处）**： | # | 原文 | 改动后 | |---|---|---| | 1 | `It provides context information about the session's …` | `It provides context information **set by the user** about the session's …` | | 2 | `… fall into a single base workspace**.** The "working directory" injected …` | `… fall into a single base workspace **—** the "working directory" injected …`（破折号后 `The` 改小写 `the`，并入同句） | **改动后全文（`src/injection.ts` 的 `renderDeclaration`）**： ``` This section is injected by the `project-groups` plugin. It provides context information set by the user about the session's `owning project` `relevant directories`. Project membership is classified by the plugin layer; the plugin does not modify the official workspace system, so all projects' workspace directories fall into a single base workspace — the "working directory" injected in the earlier system prompt is the official base workspace directory, and has no substantive relation to the project this session belongs to under this plugin. ``` （显示折行；实际注入仍是**单行**。） **中文对照**：本节由 `project-groups` 插件注入，提供**由用户设置的**关于该会话的「所属项目」「相关目录」的上下文信息。项目归属由插件层自行分类；该插件不修改官方的工作区系统，因此所有项目的工作区目录都落入同一个底层工作区**——**前面系统提示里注入的「工作目录」是官方底层工作区目录，与本次会话在本插件下所属的项目没有实质关系。 **连带改动**：`scripts/verify-project-injection.mjs:55-61` 的**手写**期望文本（`DECLARATION_TAIL` + `decl()`，刻意不从实现推导）已同步。全仓库无第三份副本（已 grep 确认）。 **本次未动**：句 3 的实质内容保留 —— 它解决"模型把工作目录当成项目"的实测歧义（codearts 会话因此纠结 27 个 step），只是**从独立句子并入前句**，语义未减。 **验收**：`pnpm check` 全绿（typecheck + 全部校验脚本 + 探针）。 **其余段落的改文案需求仍可能后续追加**（未归属/已归属/目录行/文档行/规范行/漂移段），改造时连同各自的**动态段名**与**漂移段逐字匹配约束**一并处理。 - [ ] **Z-11 可编辑注入文案（做功能）**（2026-10-07 用户提出） **目标**：让用户**自己改写注入文案**，而不是只能开关它。 **与 Z-9 / Z-10 的关系**：Z-10 是**我们**改文案，Z-11 是**让用户**能改； Z-9（能看到当前文案）是 Z-11 的前置 —— 先能看，才能改。 **必须守住的既有约束**： - **`` 框架必须保留**：模型靠它识别这一段；去掉框架会让注入块与官方运行时上下文混在一起。 - **声明段（`declaredSegments`）与实际渲染的段必须一致**：它按"能不能渲染"动态列名（`related links` 自 Z-6 起是**真段**，有链接才列入，见 `src/injection.ts:317`）；用户改写后若声明与实际不符，就会出现"承诺了却没有"的段。 - **变量占位**：文案里嵌着项目名、路径、文档路径、规范路径等**运行时值**，所以"改写"实质是**模板**，而不是一段静态文字 ⇒ 需要一套占位符语法（如 `{project}` / `{directories}`），并定义**未知占位符**与 **占位符缺失**时的行为。 - **不本地化**：注入内容刻意保持英文（用户既有决定 "插件注入内容不做本地化，仅选项和问题本地化"），可编辑功能不应把它变成中文。 **要定的**： - 存放位置（进插件自有领域，还是像规范那样作为**可上传文件**） - 是**整段替换**还是**只改固定句、保留自动段**（后者更安全，前者更自由） - 编辑面（详情页文本框 / 上传文件 / 恢复默认按钮） - **校验**：保存时是否强制框架与占位符合法，非法时拒绝还是警告 - 与 `injectProjectInfo` 开关的关系：关掉开关时自定义文案是否保留 - **恢复默认**：内置文案是包内常量，用户改写后需要一个"复原"入口 **未定，未动代码。** - [ ] **Z-12 项目折叠时仍能看出「项目内有正在进行的会话」**（2026-10-09 用户提出） **用户原话**：「现在官方工作区文件夹收起就看不到正在进行的会话，要增加项目收起也能显示表达项目内有正在进行中的会话。」 **要做的**：项目行**折叠**时，在该行上给出一个指示，表示这个项目下有会话正在运行。 #### 已核实的前提（待办立项时的代码事实） 1. **折叠时行数据里根本没有会话** —— 这是核心障碍。 `tree.ts:650-656`：`sessions: expanded ? sectionMembers(...).map(sessionNode) : []` ⇒ **折叠状态下 `group.sessions` 是空数组**。所以"从现有数据里算一个运行中"**做不到**，必须在数据侧新增一个**聚合字段** （在 `:641-657` 那个循环里，对 `g.sessions` 求值，**不受 `expanded` 影响**）。 2. **单个会话的运行状态已经现成**：`SessionNode.running` （`tree.ts:200`、`sessionNode()` 在 `:590`：`status?.running ?? s.running`）。聚合可以复用同一判据 ⇒ **不会出现"行内说在跑、聚合说不跑"的分歧**。 3. **`GroupNode.sessionCount` 已是"只定义不使用"**（`tree.ts:178` 定义、`:650` 赋值，渲染层零读取）—— 与我们 vendored 的上游一致。 **上游同样没有运行聚合字段**：实测上游 `ui-workspace/lib/client.js`， `anyRunning` / `runningSubtree` / `hasRunning` **匹配数全为 0**， `sessionCount` 只在 `:499` 赋值、**从不被渲染层读取**。 4. **渲染插入点已定位**：折叠/展开按钮在 `WorkspaceBrowser.tsx:1776-1779` （`recordExpansion(group.key, !group.expanded)`），行本身通过 `renderGroup` 的 `actions`（`:1828`）接收右侧控件。 ⇒ 指示器应挂在**行标题附近**，而不是会话列表区（那里折叠时不存在）。 #### ⚠️ 与 §0「界面与官方 1:1」的张力（必须先定）这是**官方没有的行为** —— 上游既不显示运行聚合，连 `sessionCount` 都不显示。 **参照判例**： - **X-1**（hover 卡显示项目）因"分组视图里已肉眼可见"被判**未做**； - **Z-7**（项目行显示会话数）仍在待办，理由同族。 **Z-12 与 Z-7 的关系**：两者都要在**折叠的项目行**上加信息，数据来源与插入点是**同一处**。差别是**语义紧迫性**：「有会话在跑」是**状态**（用户需要立刻知道、可能与自己的等待有关），而「几个会话」是**统计** —— 前者比后者更像"该做的"。 ⇒ **建议一起定**：要么都做，要么先做 Z-12（状态优先于统计）。 #### 要定的 - **形态**：项目名后的转圈点 / 呼吸点 / 数字徽标 / 名称加粗？ **必须与现有视觉语言协调**：官方在**会话行**上已有"运行中"转圈（`SessionNode.running`）、"完成未读"绿点（`completed`）。折叠行用同类符号可读性最高，但**不能与会话行混淆**。 - **口径**：只算**直接**会话，还是**含子代理**？（会话行已经有 `runningSubagentCount`，`tree.ts:180-202`）折叠行的聚合是否也要分这两层？ - **包含哪些状态**：仅 `running`？还是也要 **等待用户交互**（`pendingInteraction`，`tree.ts:585`）与**完成未读**（`completed`）？「正在进行的会话」按用户措辞**只指 running**，但等待用户输入可能更该被折叠行提示。 - **嵌套项目**：项目可以嵌套（`renderGroup` 的 `childRows`），折叠的**父**项目是否要反映**子**项目里正在跑的会话？（`g.sessions` 是否含子项目的会话，需先核实 `groupBySource` 的归属语义） - **一个项目都没有会话在跑时**：什么都不显示（推断如此，但需确认不改变行高）。 - **未分组桶**是否同样显示。 - **性能**：聚合要在每次 `statuses` 变化时重算 —— 需确认不引入全量扫描（现有设计刻意让渲染层"never scans"，见 `containsCurrent` 的注释 `tree.ts:180`）。 **未动代码。** ### 通用 - [x] 构建配置（tsdown + `cordis.patch.yml`） - [ ] 单元测试（domain / RPC / 注入 / 重建逻辑） - [ ] 每层的"停用插件后回到原版 DSH"回归测试 - [ ] vendor 重新同步流程演练（并入 L4.5） --- ## 15. 本轮（L0）验证结果 | 验证项 | 手段 | 结果 | |---|---|---| | vendor 与上游一致 | 22 文件 SHA256 逐字节比对 | ✅ 0 差异 | | 产物 external 与官方一致 | `compare-bundle.mjs` 读安装版 `app.asar` | ✅ 5 个完全相同 | | bundle id / apply / inject | 同上 | ✅ | | 无构建机路径泄漏 | 同上 | ✅ 0 处 | | CSS 已内联 | 同上 | ✅ | | 禁用 patch 生效 | `verify-patch.mjs` 跑真实 `applyEntryPatches` | ✅ 无 patch 被跳过 | | 真实组装配置 | `dsh --profile pg-test --dump-config` | ✅ 官方行 disabled、插件行挂载 | | 依赖自动入 roster | `dsh plugin --profile pg-test add` | ✅ 自动加入 bundles | | 宿主启动（端到端） | 未做——避免与运行中的桌面实例争用 `$DSH_HOME` | ⏸ 待确认 | **下一轮（用户确认后）**：按 L1 开始叠加项目分组逻辑。 --- ## 24. 额外功能（默认不做） **基础功能 = 完全不动官方 + 只按项目分组。** 这里列的东西**超出**这个范围：官方没有对应行为。**但注意：这不削弱"插件关了就是官方原样"的保证**——插件的注入/监听器随插件 fiber 销毁，关掉即零残留（**2026-10-04 更正**，原表述已由 §25.1 推翻）。 **⇒ 默认不做。** 要做需要明确点头，且必须在本节登记，而不是混进待办清单。 | # | 功能 | 状态 | 为什么是额外功能 | |---|---|---|---| | **X-1** | **会话 hover 卡显示所属项目** | 未做 | 官方 `SessionHoverContent` 只有标题/时间/槽位/状态/归档。分组视图里项目标题就在行上方**肉眼可见** ⇒ 加了是冗余；只在扁平模式/搜索下有信息量 | | **X-2** | **工作文档**（`docPath` 绑定 + 注入开关 + 模板/大小上限） | **已实施**（2026-10-05，见 §26） | 官方没有这个概念。**格式规范与必读来源已做**；`docPath` 留作占位字段，文档实际路径由 `documentPath()` 运行时解析（§26.1） | > **X-2 已不是"额外功能"，而是本插件的核心能力。** 下面的原稿保留作决策记录， > **其中若干条已被 §26 推翻**： > > | 原稿 | 实际（§26） | > |---|---| > | 走 `agent/pre-step` 注入 | 走 `systemPrompt.context()`，与官方其它 contribution 同形 | > | 注入**文档正文** | 注入**文档路径 + 规范路径**；正文由模型自己读（I/O 留在 Host 侧可控） | > | `docPath` 可覆盖为任意路径 | **不可自定义路径**：统一 `$DSH_HOME/project-groups/.md` | > | 包在 `` 里 | 不用 XML 框架，用 `Label: value` 陈述句 | > | 文档过大截断 | 规范**大小不限**（用户定案）；注入内容本身很小 | > | 位置 `$DSH_HOME/projects/` | `$DSH_HOME/project-groups/` | ### X-2 详细设计（保留原 L5 内容） **目标**：项目绑定一份 md 工作文档，新会话自动注入。 | 项 | 内容 | |---|---| | 领域字段 | 使用已有的 `docPath`（当前为空串，启用其编辑与消费） | | 文档位置 | 默认 `$DSH_HOME/projects/.md` | | 注入 | host 侧 `ctx.on('agent/pre-step', …)` | | UI | 项目设置里绑定/解绑文档；可打开编辑 | | 模板 | 新项目可选生成初始文档 | **技术要点** - `$DSH_HOME` 解析顺序（与官方 `resolveDshHome` 同序）： `profileContext.home` → `$DSH_HOME` → `~/.dsh` - `docPath` 允许用户覆盖为任意路径（放进项目仓库跟 git 走） - 注入内容包在 `` 里，与官方 `dsh-agent-instructions` 的注入**并存不冲突**（两条独立消息） - 注入前做大小上限，避免超长文档吃掉上下文 - **不解析文档内容**——只读原文注入 - 注入仅对"已归类到某项目"的会话生效 **验收标准（若实施）** 1. 给项目绑定文档 → 该项目下新会话首轮即能看到文档内容 2. 未绑定文档的项目 → 不注入任何额外内容 3. 官方 `default-workspace\AGENTS.md` 注入仍正常（两者共存） 4. 关闭插件 → 不再注入（仅剩官方 AGENTS.md） 5. 文档过大时被截断且有提示 **⇒ 实施前必须确认**：这会往会话里注入内容，与"完全不动官方"的边界需要明确。 --- ## 25. 项目信息注入（已定案 2026-10-04） > 定位：**既有基础功能的一部分（开关 + 关联目录），也有额外功能（文档）**。 > 本轮只实现 **基础部分**：开关 + 关联目录 + 文档路径。**不规定文档内容格式，不注入文档正文。** ### 25.1 边界原则：与官方完全分离（用户 2026-10-04 明确） | 状态 | 行为 | |---|---| | **插件开** + 会话在某项目下 | 注入（见 §25.3 文案） | | **插件开** + 会话未分组 | **同样注入**，各字段填「无」。**不区分是否分组——统一形式注入。** | | **插件关** | **完全不注入**，会话回到官方底层工作区，官方链条零残留 | **"插件关就不注入"为什么天然成立**：注入逻辑注册为 Cordis effect，随插件 fiber 销毁；置 `disabled: true` 后监听器随之消失。因此**不需要**"清除已注入内容"的逻辑，**也不与官方 AGENTS.md 机制交叉**：两者是各自独立的消息、各自的来源 kind。 > ⚠️ 早期 §24 曾写"这会削弱『插件关了就是官方原样』的保证"——**该表述不成立**，已由本节更正。 **实测：provider 求值 ≠ 消息落盘（2026-10-04）** | 层 | 频率 | |---|---| | `systemPrompt.assemble()` 调用 `text()` | **每个 prepared request** | | 提交 `user/message` | **仅当合成文本与"当前生效的那条"不同** | 依据：`agent-loop/src/runtime-context.ts` 的 `project()`： ```ts if (this.retained?.text === snapshot) return // ← 不变则什么都不提交 ``` 本机实测佐证（会话日志统计）：`session-0dab5503` **315 个 step，`runtime-context` 只落盘 1 条**； `session-712904f9` 359 step / 2 条。⇒ 真实节奏是「**首轮 + 压缩后 + 内容变化时**」，不是每步注入。 > **对插件的影响**：无需自己实现"首轮/压缩后/变化"这套调度——官方框架自动完成。 > 插件只需保证 `text()` 每次求值返回正确文本。**这也是改动下一步即生效的原因。** ### 25.2 注入通路：`systemPrompt.context()`（user 消息），不是 section **实测依据**（`packages/core/system-prompt/src/index.ts`）： ```ts // assemble() 末尾：complete section 会把 sections 整个替换成只剩它一个 if (completeSection === undefined && !runtimeContextSuppressed) return transformed return { sections: completeSection === undefined ? transformed.sections : [completeSection], // ← 只剩它 contexts: runtimeContextSuppressed ? [] : transformed.contexts, // ← 只看 suppressor } ``` | 通路 | 载体 | 官方 preset 启用了 `complete` 时 | |---|---|---| | `systemPrompt.section()` | system prompt | ❌ **被整个丢弃**（只剩 persona 那一个） | | `systemPrompt.context()` | user 消息（runtime-context 快照） | ⚠️ 仅当该 preset 另设 `includeRuntimeContext: false` 时被清空 | **官方 preset 实测**（`packages/bundle/web-app/presets/`）： - `standard` / `ptc`：persona **未设** `complete` → 两条通路都通； - `minimal`：`complete: true` **且** `includeRuntimeContext: false` → **两条通路都不通**。 **⇒ 采用 `systemPrompt.context()`**：多数 preset 下可用，且是官方"动态运行时事实"的既定形态（sandbox / approval 政策同层）。 ⇒ **已知限制**：`minimal` preset 下不注入。记入 §25.6。 **接缝写法（2026-10-04 实测，两个陷阱方向相反）** | 服务 | 裸属性 `ctx.X` | 原因 | 正确写法 | |---|---|---|---| | `systemPrompt` | ❌ **编译错误** TS2339 | `@deepseek-ai/dsh-system-prompt` **不是本包依赖**，augmentation 不在作用域 | 结构类型 + `scope.get('systemPrompt')` | | `sessions` | ❌ **运行时抛错** | 包是依赖（类型没问题），但**裸属性读受 `inject` 门禁**：`cannot get property "sessions" without inject` | `ctx.get('sessions')` | | `storageDomain` | ✅ 可用 | 已在顶层 `inject` | 保持 | **⇒ 两者都必须走 `ctx.get(...)`，但失败时机不同**（一个在编译期，一个在运行期）—— 这正是"看起来一样的两种写法"最容易踩空的地方。 **顶层 `inject` 保持 `['storageDomain']` 不变**：顶层是**门**，写进去的服务不出现则整个插件不激活。 `systemPrompt` 用**嵌套** `ctx.inject(['systemPrompt'], cb)` 只阻塞子 fiber。 **CONTEXT_ORDERS 实测**（同文件）：官方只登记三个名字（`SANDBOX_POLICY: 110` / `APPROVAL_POLICY: 115` / `SUBAGENT_DELEGATION: 120`）， `getContextOrder()` **只接受这三个名字**；但 `context()` 本身接受**任意有限数字** order。 ⇒ 插件用自己的字面量 `200`（排在 120 之后，成为该快照的末段）。**不调用 `getContextOrder`。** **实测验证（2026-10-04，真实构建产物）** 方法：从已安装 `app.asar` 提取**真实的** `@deepseek-ai/dsh-system-prompt@0.2.0-rc.2` 构建产物（`/dsh/node_modules/@deepseek-ai/dsh-system-prompt/lib/index.js`，连同 `dsh-scope`、`schemastery`），配项目自身的真实 `cordis@4.0.1`，在真 `Context` 上运行。**非 mock、非推理。** | # | 问题 | 结果 | |---|---|---| | Q1a | 裸属性访问（无 `inject`） | **抛错** `cannot get property "systemPrompt" without inject` | | Q1b | `ctx.get('systemPrompt')` | ✅ **解析成功** | | Q1c | `ctx.inject(['systemPrompt'], cb)` | ✅ **触发且属性可读** | | Q2 | `ctx.get` 注册与 `ctx.inject` 的 scope 注册，谁能进 `assemble()` | ✅ **两者都能**，均出现在 `assembly.contexts` | | Q2 | order 200/201 的位置 | ✅ 排在官方 110/115/120 **之后** | | Q3 | `text()` 是否每次 `assemble()` 重新求值 | ✅ **是**——两次 assemble 之间改底层数据，第二次立即反映 | **⇒ 三条结论**： 1. **`system-prompt` 是 base 平面的长驻服务，不是 `pluginNavigation` 那种瞬时服务**（§14 的坑不适用）。 `ctx.get` 与 `ctx.inject` 都能解析；**无需**为"服务晚到"做额外处理。 2. **采用 `ctx.inject(['systemPrompt'], scope => scope.systemPrompt.context(…))`**：两种写法都能进 assembly，选它是因为**与官方 `user-approval` / `sandbox-policy` 同形**，且注册随子 fiber 自动重注册。 3. **`text()` 每次 assemble 重算 ⇒ 改归属/目录后「下一步」即生效，不需要新会话。**（§25.6 原"待验证"项已由 Q3 关闭。） > 探针脚本为一次性验证，跑完即删；结论以本表为准。 ### 25.3 注入文案（定案：2026-10-06 重写，XML 块 + 声明段） **形态**：`` 包裹的**多行块**，字段平铺 `Label: value`。 > **本节 2026-10-06 被重写。** 旧定案（2026-10-05）是"纯文本、无 XML 包裹、两行块"， > 现**已废止**。改动理由见本节末尾「为什么改回 XML」，其中记录了两条**实测证据** > （真实会话里模型为定位自己而反复侦察），而不是审美偏好。 **这一段仍合进官方同一条 runtime-context 消息**（`joinContextSections`），不存在独立的 user 消息；`` 是**这条消息内部的块**。结构固定为**三段**，其中前两段恒定、第三段随数据： ``` ① 声明段 —— 恒定（除非「段清单」变化） ② Owning project —— 永远存在（未分组也在） ③ Relevant directory(ies) —— 按数量：0 / 1 / 多（文档段、链接段、漂移段依次接在其后） ``` #### 25.3.1 声明段（恒定） ``` This section is injected by the `project-groups` plugin. It provides context information about the session's `owning project` `relevant directories` `related links` `work document`. Project membership is classified by the plugin layer; the plugin does not modify the official workspace system, so all projects' workspace directories fall into a single base workspace. The "working directory" injected in the earlier system prompt is the official base workspace directory, and has no substantive relation to the project this session belongs to under this plugin. ``` **逐条理由** | 句子 | 作用 | |---|---| | `This section is injected by the …` | **出处**。官方那条 cwd 来自 persona 层，自定义 profile 可去掉；写明出处后，即使它不在也能指向 | | `about the session's `owning project` `relevant directories` `related links` `work document`` | **段清单，动态裁剪**（见 25.3.4）。**平铺、无 `and`、无逗号**（用户定案）。反引号**保留**（用户定案） | | `classified by the plugin layer … single base workspace` | 解释**为什么**目录与项目无关：是架构决定，不是巧合 | | `The "working directory" … has no substantive relation to the project` | **核心句**。直接免除模型"调和两条互相矛盾信息"的负担 | **为什么必须有最后那句（实测证据）** 真实会话里，模型收到 `Your working directory is …\default-workspace`（官方）与 `Current project: dsh-project-groups`（旧插件文案）后**反复侦察**： | 会话 | 注入 | 注入后出现"哪个项目"犹豫的 step | |---|---|---| | codearts | `Current project: deepseek-harness-codearts` / `Related folders: none` | **27 个** | | minecraft | `Current project: dsh-project-groups` | **3 个** | | a18c5dad | `none (ungrouped)` | 6 个 | | ac2b7c25 | `none (ungrouped)` | 0 | 模型的推理原文（minecraft，`seq 102`）： > "But which project? The runtime says "Current project: dsh-project-groups" … > **Hmm, but the working directory is the default-workspace.** … There's ambiguity" codearts 会话里，模型为定位自己跑了 6 条侦察命令（含 `-Recurse -Depth 6 -Filter "*codearts*"` 和翻 `project_groups.json`），**27 个 step 后才确认**自己在哪个项目。 ⇒ **不是"指向不清"，而是两条无定语信息并列且无人交代关系。** 最后那句就是那句交代。 #### 25.3.2 归属段（`Owning project`） **两种情况分开写**（用户定案，不做统一句式）： **已归档** ``` Owning project: You are currently working on this project, project name "dsh-project-groups" ``` **未分组** ``` Owning project: This conversation does not belong to any project. It is under the "Ungrouped" category. ``` **为什么分开**：统一句式会产出 `You are currently working on this project, project name "none (ungrouped)"` —— **自相矛盾句**（说正在处理，名字却是"无"）。且 `none (ungrouped)` 是**代码常量** （`UNFILED_PROJECT`），不是用户起的名字，套进 `project name "…"` 会被读成 "一个叫这名字的项目"。 #### 25.3.3 目录段（按数量三态，**标签随数量变**） | 数量 | 渲染 | |---|---| | 0 | `Relevant directory: The user has not yet set up the relevant directory.` | | 1 | `Relevant directory: C:\…\dsh-project-groups` | | ≥2 | `Relevant directories:` + 每个一行 `- <路径>`（平铺破折号，**不用 XML 列表**） | **0 条**用用户定案的句子（`The user has not yet set up the relevant directory.`）， **不用旧的 `none`** —— 旧写法是"没有"，新写法是"用户尚未设置"，**后者更有行动指向**，且 `yet` 准确（目录确实可后加：codearts 那次会话 12:21 创建、目录 12:36 才关联）。 **单条也用单数标签**（用户定案）：1 条走 `directory`，≥2 走 `directories`。这与旧定案"每条都用同一列表形态"**相反**，旧理由（形状只取决于数量）**已让位于** "标签与数量一致"的可读性。 #### 25.3.4 段清单动态裁剪（用户定案）声明段里的清单**只列实际会注入的段**，顺序固定： ``` owning project → relevant directories → related links → work document ``` | 段 | 列出条件 | 当前状态 | |---|---|---| | `owning project` | **永远**（未分组也列） | ✅ | | `relevant directories` | 已归档时**永远**（0 目录也列，因为目录段本身会渲染） | ✅ | | `related links` | 已归档时**永远**（0 链接也列 —— 链接段同样总有内容可说） | ✅ **已实现**（Z-6 结案；2026-10-13 改为与目录同规则） | | `work document` | `injectProjectDoc` 开 **且** 已归档 | ✅（默认关） | **⇒ 未分组时清单只剩 `` `owning project` ``** —— 这同时回答了"清单会不会为空"： **永不为空，最少一项**。所以不需要"全空兜底"措辞。 #### 25.3.5 文档段与漂移段（沿用 §26，措辞不变）文档段接在目录段之后，`injectProjectDoc` **开** 且**已归档**时才出现： ``` Project document: <绝对路径> — a failed read means it has not been created yet; create it following the spec. Project document spec: <绝对路径> ``` **规范为「无」时**（含 `custom` 但文件名未选/文件已删 ⇒ 也解析为 `none`，`spec-store.ts:203`）： ``` Project document: <路径> — a failed read means it has not been created yet; create it as the project needs. Project document spec: none — no format is required, and the document's format is left as it is: write freely if it has no format of its own, or add to the existing format rather than reorganising the document. ``` **漂移段**（§26.4 已定案，措辞与匹配规则不变）：三段标记 + 严格逐字 + `REWRITE-FLOW.md` 路径； **问题与选项随界面语言**，其余句子恒为英文。 #### 25.3.6 全部可通状态（枚举自代码，2026-10-06）可达性由主机侧三个决策点决定： ``` src/index.ts:753 injectProjectInfo 关 → 返回 ""（整个插件不贡献任何东西） src/index.ts:756 projectId → 记录；记录已删 ⇒ project undefined（悬空 assignment） src/index.ts:759 document 仅在【有项目】且【injectProjectDoc 开】时构造 src/injection.ts:235 未分组在【第一行就 return】，文档段代码不执行 ``` | # | 状态 | 可达条件 | 段结构 | |---|---|---|---| | **A** | 注入总开关关 | `injectProjectInfo = false` | **空字符串** | | **B** | 未分组 | 无 assignment | ①＋②未分组句 | | **C** | **悬空 assignment** | assignment 有值但项目已删 ⇒ 与 B **同样渲染** | ①＋②未分组句 | | **D/E/F** | 已归档 · 1 / 0 / 多目录 · 文档关 | `injectProjectDoc = false` | ①＋②＋③ | | **G/H/I** | 已归档 · 1 / 0 / 多目录 · 文档开 | `spec.mode = default` | ①＋②＋③＋文档 | | **J/K** | 已归档 · 文档开 · **规范=无** | `mode = none`；**`custom` 未选文件也解析成 `none`** | ①＋②＋③＋文档（无规范句） | | **L** | 已归档 · 文档开 · **漂移（zh）** | `shouldAskSpecDrift` 为真 | ①＋②＋③＋文档＋漂移 | | **M** | 漂移 + 规范=无 | **不可达**（无规范不询问，`shouldAskSpecDrift` 首条即返回 false） | — | | **N** | 已归档 · 文档开 · 漂移（en） | `locale = en` | 同 L，问题与选项换英文 | **三种段结构**：未分组 = 1 段；归档＋文档关 = 3 段；归档＋文档开 = 3~5 段。 **两处曾被误列（记录以免重犯）** - **未分组 + 文档**：**结构上不可能**。文档挂在项目记录上（`docSpecUsed`、路径按 `projectId`），未分组没有记录 ⇒ 主机不发、渲染器也不执行。**不是"决定不给"，是"给不了"。** - **`custom` + 未选文件**：解析结果是 **`mode: 'none'`**，不是 `'custom'` （`spec-store.ts:200-204`），故与 J 共用文案，**不是独立状态**。 #### 25.3.7 为什么改回 XML（2026-10-06，推翻 2026-10-05 的决定）旧定案的两条理由，**现都不成立**： | 旧理由 | 为什么不成立 | |---|---| | "官方 24 处 `context()` 无一处用 XML" | **块的性质变了**：从 1~2 行状态句变成 4~6 行、且**含用户自定义的项目名与路径**（半可信数据）。官方给不可信/无界内容加边界（`agent-instructions` 包用户的 `AGENTS.md` 并转义闭合标签），正是同一情形 | | "加标签会在无标签正文末尾出现孤立标签" | **块现在有明确首尾**，不是孤立标签；而且**将来要加链接、文档等段**，需要一个能容纳扩展的容器 | **仍有代价，已接受**：`context()` 的文本由 `RuntimeContextProjection.project()` 去重， XML 不改变这一点；但声明段会随**段清单**变化（开关文档时）， ⇒ 那一次会重新注入一条上下文消息。 **测试已同步（2026-10-07）**：`no XML frame wraps the block` 已**反向**为断言"框在首尾各出现一次"，并新增四条断言：声明段的段清单随门控变化、 **空链接项目照常声明 `related links`**（Z-6 实施后该段已成为**真段**； ⚠️ 2026-10-13 更正：本条原写"不声明"，与用户 2026-10-06 的定案相反，现断言的是"已归档就声明"）、 **未分组即便传入 document 也不渲染文档段** （把"结构上不可能"钉成可执行的断言），以及单目录用单数标签。 **实现态（2026-10-07）：已实施。** `src/injection.ts` 渲染本节所述形态； `src/index.ts` **未改动**（`injectionText` 的取值与门控原本就符合）。 `verify-project-injection.mjs` 61 条、`verify-doc-spec.mjs` 80 条，全量门禁通过。 --- ### 25.3-old 旧定案（2026-10-05，**已废止**，留档） **A. 项目下，2 个关联目录**（文档行待实施） ``` Current project: dsh-project-groups Related folders: - C:\Users\Think\Desktop\项目\dsh-project-groups - C:\Users\Think\Documents\deepseek-harness\default-workspace ``` **B. 项目下，1 个关联目录** ``` Current project: dsh-project-groups Related folders: - C:\Users\Think\Desktop\项目\dsh-project-groups ``` **C. 项目下，0 个关联目录** ``` Current project: dsh-project-groups Related folders: none ``` **D. 未分组**（**单行**） ``` Current project: none (ungrouped) ``` **E. `injectProjectInfo` 关**（非默认）：**整块不注入**，模型侧零残留。见 §25.4 的 master-gate 规则。 **未分组单行的理由（2026-10-04 定案）**：`directories` 是 **`projectRecord` 的字段**，未分组**没有记录**，也就**没有编辑入口**（未分组行没有可设目录的按钮）。若在那里输出 `Related folders:`，等于**指向一个不存在的设置**，会诱导模型报告"一个可以修好的缺失"。 ⇒ **未分组只报状态**；而**已归类但无目录**的项目**保留该行**——因为那个项目**确有编辑入口**， `none` 在那里是**可执行的**状态，不是缺失。这个不对称是有意的。 **格式规则（2026-10-04 定案）**：已归类项目 ⇒ 目录 **≥1 一律用 `- ` 列表**（含单个，不留特例）； **0 条写 `none`**；**未分组 ⇒ 只有单行**。**无 XML 包裹**（← 此条 2026-10-06 已推翻）。 ### 25.4 两个开关 | 开关 | 默认 | 控制 | 性质 | 实现状态 | |---|---|---|---|---| | `注入项目信息` | **开** | 项目行 + 关联目录行 | 基础功能 | ✅ **已实现** | | `注入项目文档` | **关** | 「工作文档」那一行 | **额外功能** | ✅ **已实现**（§26） | 存储：`globalRecord` 增加两个带 default 的布尔（同 `createOpensSession` 的兼容机制，**不需要 bump version**）： ```ts injectProjectInfo: z.boolean().default(true), injectProjectDoc: z.boolean().default(false), ``` **`injectProjectInfo` 是 master gate**（已实现）：为 `false` 时插件**整块不注入**，`injectProjectDoc` 无法"单独开启"一个信息块。 **UI 联动规则**（定案）： ``` injectProjectInfo === false ⇒ injectProjectDoc 的 Switch：disabled，无法点击 ⇒ 显示说明文案：「由「注入项目信息」控制，现已关闭」 ⇒ 存储值保留，不联动改写（重开 info 时恢复用户原选择） ``` **已实现（2026-10-04）**：`src/client/settings-card.tsx` 两个 `Switch`； master 关闭时 `disabled` + `title` + 描述行改用 `injectDocGated` 文案。灰显的开关**仍显示其存储的 `checked`**（不强制为 `false`）——这正是"保留选择"的可视形态。 `probe-settings-injection-switches.mjs` 用真实浏览器断言了全部 6 条。 **文档功能当前状态**：`docPath` 字段与 `injectProjectDoc` 开关**仅存储**，后端不读文件、不注入文档行（`src/injection.ts` 的 `renderProjectInjection` 不渲染该行）。因此前端该开关**灰显**。这与 §25.7 的范围一致：文档格式规范与正文注入属额外功能，本轮不做。 ### 25.5 关联目录 - **类型**：`directories: string[]`（**可多个**）。顺序即展示顺序。 - **主次目录**：**不做，且不预留任何字段/参数**（用户 2026-10-04 明确："不要主次不要主次"）。即 `directories` 就是 `string[]`，**不写 `{ path, primary }`、不加 `primary` 布尔、不加排序权重**。 - **人工可改**：**能**。入口是**「编辑项目」**——即现有行菜单的「重命名」扩展为"改名 + 改目录" （`WorkspaceBrowser.tsx` 的 rename 对话框扩展，菜单项文案由「重命名」改为「编辑项目」）。 - **模型改**：**本轮不做，也不加开关**，**仅记入设计**（见 §25.9）。默认**只由人工修改**。 #### 25.5.1 目录选择的交互（2026-10-04 暂定） **决定：用 `remote.directoryPicker.pick()`——操作系统原生选择器。** **关键区分（探查后修正）**：官方「添加工作区」用的**不是**这个： | | 路径 A：`directoryFlow` 槽位 | **路径 B：`remote.directoryPicker.pick()`** | |---|---|---| | 形态 | **内置浏览面板**（面包屑 + **新建文件夹**） | **OS 原生对话框**（Windows 资源管理器） | | 提供者 | `dsh-client-ui-directory-picker-browse`（占 slot） | `dsh-host-directory-picker-native` | | 本插件依赖 | ❌ 未依赖 | ✅ 已在 vendored inject 列表（`remote.directoryPicker`） | `dsh-host-directory-picker-auto` 会在启动时二选一挂载。官方 `WorkspacePicker.tsx` 的注释明确说 "the occupant's own create-folder affordance already covers creating one"——**那个创建文件夹的能力属于路径 A**。 **⇒ 暂定走 B（原生对话框）**，代价是**观感与官方「添加工作区」不一致**。理由： 1. **零成本**：接缝现成，不抢 `single` 槽位、不新增依赖； 2. 关联目录多为**已存在**的目录，"新建文件夹"需求弱； 3. OS 原生对话框在 Windows 上是**用户更熟悉**的交互。 **后续可选改动（保留）**： | 方案 | 观感 | 代价 | |---|---|---| | **(b)** 复用 `directoryFlow` slot + `DirectoryFlowOwnerProps` 状态机 | ✅ 与官方一致（含新建文件夹） | ⚠️ 该槽是 `kind: 'single'`，**与官方「添加工作区」冲突**；须处理 priority 或自声明子槽位 | | **(c)** 自调 `list()` / `createDirectory()` 渲染自己的面板 | ✅ 一致，且不抢槽 | 需自行实现目录浏览器 UI，工作量最大 | > **改到 (b)/(c) 时**：只需替换 `ProjectActions.pickDirectory` 的实现与对话框里的调用点， > 对话框其余部分（草稿状态、去重、移除、提交）**不用动**——这是把选择交互收敛到一个动词的原因。 ### 25.6 已知限制 | 限制 | 说明 | |---|---| | `minimal` preset 下不注入 | 该 preset 设了 `complete: true` + `includeRuntimeContext: false`，两条通路都被关。**这是官方 preset 的能力边界，不是插件缺陷。** | | 与 sandbox/approval 合并成一条消息 | `joinContextSections` 的既定行为，无法拆成独立消息 | | ~~会话初始化只读一次？~~ | ✅ **已实测关闭（2026-10-04）**：`text()` 每次 `assemble()` 重新求值 ⇒ **改归属/目录后下一步即生效**。见 §25.2。 | | 跨了"已关闭且未归类"的祖先会断链 | 见 §25.6.1 的遍历规则：父会话关闭后，其**项目**仍可读，但**再往上爬**需要父的 header，读不到就停。 | #### 25.6.1 子代理血缘（2026-10-04 实测 + 实现） **问题**：子代理会话**不在 `assignments` 里**——只有 `session.create` 带 `workspaceId` 才挂账，而委派子代理走 Agent 注册表。若不处理，**每个子代理都会把自己报成「未分组」**。 **官方立场（三层证据）**： | 层 | 事实 | 出处 | |---|---|---| | 候选账 | 子代理**不挂账** | 本机实测：18 会话 / `workspace.json` 仅 17 条，缺的正是 `origin: "subagent"` 那条 | | UI | 子代理**不进树**：`if (session.origin === 'subagent') return false` | `packages/client/ui-workspace/src/client/tree.ts` | | **归属** | **靠祖先回溯**：直接未命中且是 subagent ⇒ `traceSession` 找最近已挂账祖先 | `packages/api/session-controller/src/commands.ts` 的 `forkWorkspace` | | **归档** | **同步逐级回溯**：`ctx.sessions.get()` + visited 集合 | `packages/api/session-controller/src/archived-session-gate.ts` 的 `underArchivedSession` | **⇒ 采用与 `underArchivedSession` 同构的同步遍历**（`src/index.ts` 的 `projectOfSession`）： ``` 1. assignments.get(sessionId) 命中 → 用它（普通会话的唯一路径） 2. 未命中：读 session header；origin !== 'subagent' → 停止（fork 是独立会话） 3. 循环：parentSession → visited 防环 → assignments 命中即返回 → 未命中则 ctx.sessions.get(parent) 取 header 继续 → 父不在活跃集合 → 停止（无法读它自己的 parentSession） ``` **关键实测结论（推翻早期判断）**：**祖先不需要是活跃会话。** ``` 父已关闭，但父在账上 → 仍能读到父的项目 ✅ 父已关闭且未归类，祖父在账上 → 停止，报未分组（无法读父的 header）环形血缘 → 终止，报未分组 ✅ ``` 原因：`assignments` 是本插件**自己的持久表**，按 session id 键；而父的 id 就带在 `header.parentSession` 上。**只有"继续往上爬"才需要活的父会话。** 官方 `underArchivedSession` 同样如此（父不活跃时仍用 id 查归档集）。 **为什么不用 `forkWorkspace` 那套**：它用异步 `sessionQuery.traceSession()`，而 `text()` **必须同步** （实测 `PromptContext.text` 的签名是 `(context) => string`，不能 await）。合并成的调用点又**每个请求都跑**。 ### 25.7 本轮范围（用户 2026-10-04 最终指定） **做**： 1. `directories` 字段（`string[]`，**无主次**）+ 两个开关（存储层）✅ 已完成 2. `systemPrompt.context()` 注入（**项目名 + 关联目录**）✅ 已完成 3. **新建项目界面**加"关联文件夹"（可加多个）——对齐 Codex 的「创建项目」对话框 ✅ 已完成 4. **「重命名」扩展为「编辑项目」**（改名 + 改目录）✅ 已完成 5. 设置卡两个 `Switch`（doc 开关灰显）✅ 已完成 **不做**：文档内容格式规范（§8 暂缓）、**文档正文注入（后端不实现）**、 **主次目录（连字段都不预留）**、**任何模型工具**（§25.9）。 **实现落点**（全部已完成）： | 文件 | 内容 | |---|---| | `src/injection.ts` | **新增**：纯渲染器 `renderProjectInjection`（项目名 + 关联目录，无文档行） | | `src/index.ts` | 接缝类型 + `ctx.inject(['systemPrompt'])` 注册 + `injectionText` + `projectOfSession` 血缘遍历 + **原子 `update`**（`rename` 已删） | | `src/vendored/client/tree.ts` | `GroupSource.directories` + 导出 `sameStringList` | | `src/vendored/client/rows/WorkspaceBrowser.tsx` | 新建/编辑对话框的关联文件夹；`DirectoryRows` / `DirectoryHeader` | | `src/vendored/client/rows/Rows.tsx` | 项目行菜单文案 →「编辑项目」 | | `src/client/settings-card.tsx` | 两个 `Switch`；`injectProjectInfo` 为 master，关时 `injectProjectDoc` 灰显 | | `src/client/grouping.ts` | `clientInjectProjectInfo` / `clientInjectProjectDoc` 两个 observable | **验证脚本**： | 脚本 | 覆盖 | |---|---| | `verify-project-directories.mjs` | 存储层：`directories` 存量兼容、`update` 原子性、开关往返 | | `verify-project-injection.mjs` | 渲染器 9 项 + 漂移谓词 8 项 + 血缘遍历 11 项 | | `probe-project-directories-dialog.mjs` | **真实浏览器**：预填/删除/重开不残留/空占位（17 项） | | `probe-project-duplicate-name.mjs` | **真实浏览器**：重名拦截（含编辑对话框） | | `probe-settings-injection-switches.mjs` | **真实浏览器**：两开关、灰显联动、独立写入（15 项） | > **原生目录选择器无法自动化**：`pickDirectory` 打开的是 OS 系统对话框，Playwright 驱不动。 > 探针覆盖的是它**周围**的一切（渲染、删除、预填、去重、重置、原子提交）； > "点添加文件夹能选到目录"这一步只能人工验。已写入该探针的模块注释。 ### 25.8 社区先例（文档格式规范的参考，本轮不实施）四种成熟手法，供 §8 将来定案时取用： | 项目 | 手法 | 可借鉴点 | |---|---|---| | **Cline Memory Bank** | 固定文件名 + 每个文件的**职责清单**（bullet 列"装什么"） | §8 每个 `##` 区块补"装什么" | | **Agent Skills** | YAML frontmatter **必填字段**，机器可校验 | §8.3 要"程序读文档"，**格式必须可校验** | | **GitHub Spec Kit** | 模板即仓库文件 + `[占位符]` + `[NEEDS CLARIFICATION: …]` | 未决项强制显式标记 | | **Kiro / EARS** | 受限文法 `WHEN … THE SYSTEM SHALL …` | 消除歧义（表达僵硬，谨慎采用） | **注入分法共识**（Cline 与 ZCode 各自独立验证）：**格式规范放 system，内容/索引放 user。** ### 25.9 额外功能：模型自主更改项目信息（**仅记入设计，本轮不做**） > 用户 2026-10-04 定案：**当作额外功能，本轮不做，也不加开关。** 默认只由人工修改。 > 本节只记录设计，供将来取用。**不预留任何代码、字段或开关。** **设想功能**：让模型能够修改项目的**名称 / 关联目录**，对应一个开关（如 `模型自主更改关联项目信息`）。 **为什么是额外功能**：官方没有"项目"概念，更遑论"模型改项目元数据"。它会让模型能够改变**注入给它的那份上下文自身的来源**，是比注入更强的介入。 **两条候选实现路线（均未采用，仅记录）**： | 路线 | 机制 | 评价 | |---|---|---| | **A. 工具** | 插件注册一个 tool，模型调用它改 domain | 需要工具注册、参数校验、审批路径；介入面最大 | | **B. 改文档文件** | 模型编辑项目文档，插件读文件并同步回 domain | 插件**只读文件**，但引入"文档字段 ↔ domain 字段"的双向同步与权威性冲突 | **未决问题（将来若做必须先回答）**： 1. **权威性**：domain 的 `directories` 与文档里的字段，谁是权威？两者不一致时怎么办？ 2. **审批**：改项目归属类信息是否需要用户确认？（参照官方"不可逆操作两阶段确认"） 3. **可见性**：模型改了之后，侧栏如何即时反映（走现有 `follow` 流即可，但需验证）。 4. **与注入的关系**：模型能改注入源，等于能改自己的上下文——是否需要防自指约束。 --- ## 26. 工作文档功能（**已实现** 2026-10-05） §8 的那份规范设计**已废弃**，由本节取代。实现落在 `src/spec-store.ts`、`src/injection.ts`、`src/index.ts`，规范正文在 `spec/PROJECT-SPEC.md` 与 `spec/REWRITE-FLOW.md`（随包发布）。 ### 26.1 为什么规范随包、文档存 `$DSH_HOME` | 文件 | 位置 | 理由 | |---|---|---| | 项目文档 | `$DSH_HOME/project-groups/.md` | 用户要能读到；**不可自定义路径**（2026-10-05 定案） | | 上传的规范 | `$DSH_HOME/project-groups/specs/.md` | 只存**文件名**，路径由插件拼 ⇒ 换机器自动正确 | | 内置规范 | `<插件包>/spec/*.md` | **随包**：插件升级自动生效、无"用户编辑 vs 出厂默认"冲突 | **两条路径都在运行时解析**，源码里没有任何绝对路径字面量： ```ts // 官方解析顺序：profileContext.home → $DSH_HOME → ~/.dsh harnessHome(ctx) = ctx.get('profileContext')?.home ?? process.env.DSH_HOME?.trim() ?? join(homedir(), '.dsh') // 内置规范相对本模块解析（实测 `lib/` 产物中 import.meta.url 存活） BUILT_IN_SPEC_PATH = fileURLToPath(new URL('../spec/PROJECT-SPEC.md', import.meta.url)) ``` > **`spec/` 必须留在 `package.json` 的 `files`**，否则分发时不打包，模型读不到规范。 ### 26.2 规范的身份 = **内容哈希**，不是文件名用 SHA-1（与官方 `agent-instructions/src/digest.ts` 的 `instructionContentSha1` 同算法同用途）。 **为什么不是文件名**： | 情况 | 比文件名 | **比哈希** | |---|---|---| | 覆盖同名上传 | ❌ 检测不到 | ✅ 检测到 | | **插件升级改动内置规范** | ❌ 名字恒定 | ✅ 自动检测到，重新询问 | | 内容相同的两个文件 | 误报变化 | ✅ 视为相同 | 哈希**同步**计算并**按 `path+mtime+size` 记忆化**——因为 `PromptContext.text` 是同步的（`system-prompt/src/index.ts:66`），且每个 prepared request 都会求值。稳态下每次注入只有一次 `statSync`。 **渲染器保持纯函数**：哈希由 `src/index.ts` 算好作为参数传入，`injection.ts` 不碰文件系统。 ### 26.3 三个状态值 | 字段 | 位置 | 含义 | |---|---|---| | `project.docSpecUsed` | 项目记录 | 文档**当前依据**的规范哈希。**absent = 文档从未创建** ⇒ 永不触发漂移询问 | | `project.docSpecIgnored` | 项目记录 | 用户选「长期忽略」时的哈希 ⇒ 直到规范**再变**才重新询问 | | 当前设置 | **实时解析** | 项目覆盖（`docSpec`）?? 全局（`docSpecMode` + `docSpecFileName`） | **判定**（每次注入）—— 实现在 `shouldAskSpecDrift`（**纯函数，可直测**）： ``` current = 当前设置解析出的规范哈希 if (current === undefined) → 不询问（没有迁移目标：无 / 自定义但文件已删） else if (docSpecUsed === undefined) → 不询问（没有文档可迁移） else if (docSpecUsed === current) → 不询问（已对齐） else if (docSpecIgnored === current) → 不询问（已忽略到下次变更） else → 注入询问指令 ``` > #### 第一条前提是 2026-10-06 补上的（真 bug） > > 早先**没有** `current === undefined` 这一条。于是「无」下 —— 当前根本没有规范 —— > **只要文档存在就触发询问**，而那份询问把模型指向规范文件与 `REWRITE-FLOW.md`， > 后者的第一步是"**读取本次注入给出的规范文件全文**"。**那个文件不存在。** > > **症状**：一条注入里同时出现「no format is required」和"去按新规范重构文档"。 > 打印全部 10 个状态时发现。 > > **根因**：迁移需要一个**目标**，而「无」没有目标 —— 它的含义是**不更新格式**。 > 作者在写入侧（`applyDriftChoice`）**已经**防住了（`spec.sha1 === undefined` 时不记任何选择）， > **计算侧漏了同一道判断**。修法是把判断抽成 `shouldAskSpecDrift` 并补上第一条前提。 > > **抽成纯函数的理由**：这个 bug 的**表现是"什么都没出现"**，而渲染文本的断言 > **看不出区别**（"没有漂移"和"该有漂移却没有"渲染结果相同）。只有直测谓词才能锁住它。 > > **`docSpecUsed` 保留旧值不动**，这正是往返正确的原因： > > | 场景 | 结果 | > |---|---| > | 有规范 → `无` | 不询问，文档不动 ✅ | > | `无` → **回到同一个**规范 | 哈希相等 ⇒ 不询问（本来就没变）✅ | > | `无` → **换成新**规范 | 哈希不等 ⇒ 询问（这时确实要迁移）✅ | ### 26.4 注入时机（**已实测**，不是每步） | 触发 | 说明 | |---|---| | 会话首轮 | 首次注入 | | **压缩后** | 快照重建 | | **文本变化时** | 项目名/目录/规范/开关等任何影响渲染的值变了 | **实测依据**：`RuntimeContextProjection.project()` 在文本与保留值相同时不提交（`agent-loop/src/runtime-context.ts:155`）；session-0dab5503 **315 steps 只落 1 条** runtime-context， 54 轮共 5 条。 **⇒ 「本次忽略」不记任何状态即可**：文本未变 ⇒ 不重新提交 ⇒ 不循环。这是官方去重机制给的，不是我们加的。 ### 26.5 询问闭环：**模型问，插件旁听** **模型是提问主体**（用户 2026-10-05 定案），插件**不加工具、不伪造消息**。 ``` ① 注入（漂移时）：给出问题 id / 选项 / 描述，要求**严格逐字**使用，并禁止翻译；同时指明「若选第一项，完整阅读 REWRITE-FLOW.md」 ② 模型调用 ask_user_question → 用户选择 ③ 模型从自己的工具结果得知答案 ⇒ 知道该重写 ④ 插件订阅 session/event 旁听到答案 ⇒ 自动改状态 ``` **为什么不用官方投影**：`sessionProjections.stateOf(session, 'userQuestions')` 只在会话头部记录的是 **timed** schema 时才收录问题（`projection.ts:248` `if (!fold.timed …) return fold`），而 profile 三处 `tool-ask-user` 都是默认 `legacy` 模式 ⇒ **投影恒空**。故自己订阅两个事件： | 事件 | 取什么 | |---|---| | `tool/call` | `name === 'ask_user_question'` 且参数含我们的问题 id ⇒ 记下 `callId` | | `tool/result` | 匹配 `callId` ⇒ 读答案 JSON ⇒ 精确匹配标签 | **匹配靠标签原文**（协议只回传 `selected: string[]`，无序号、无选项 id——`types.ts:60`）。中英标签**都**在匹配表里，所以切换语言不会让历史答案失配。**失配 ⇒ 不记任何状态**（等价「本次忽略」，唯一安全行为）。 > 官方自己的 `AskUserQuestionIntent` 注释也说明选项身份「**Named rather than positional**」—— > 用标签名而非序号，是这个协议的既定做法。 ### 26.6 三个选项的语义 | 选项 | 标签（zh / en） | 记录 | |---|---|---| | 1 | 按新规范重写 / Rewrite for the new spec | `docSpecUsed = current` | | 2 | 本次忽略 / Skip this time | **什么都不记** ⇒ 下一次注入点再问 | | 3 | 在规范再次变更前忽略 / Ignore until the spec changes again | `docSpecIgnored = current` | **选项 2 的"本次"= 本次注入点**（用户 2026-10-05 明确）。不引入会话级抑制——注入去重已保证不循环。 ### 26.7 本地化：**只本地化问题与选项** | 部分 | 语言 | 读者 | |---|---|---| | 框架句（`Owning project:` / `The spec … differs …` / `strictly verbatim` …） | **恒英文** | **模型** | | `question` / `options[].label` / `options[].description` | **按 Host 语言** | **用户** | **Host 语言来源**：`settings` 服务的 `locale` 条目 `preference`； **未设置时兜底中文**——因为系统语言由 Desktop preload 直接交给客户端，**Host 拿不到**，而本部署的界面是中文（实测 `settings.yaml` 不存在 ⇒ `preference` 为 `undefined`）。 **⇒ 一条注入里中英混排是有意的：两个读者，两种语言。** ### 26.8 上传：**读内容，不取路径** 用 `` + `File.text()`，**不读 `window.__DSH_HOST_PATHS__`**。 **理由**：那个 preload 桥只在 DSH 桌面上存在（`ui-conversation/src/client/apply.ts:96-109` 的注释： *a served Web page has none*），而**读内容两端都可行** ⇒ 桌面与远程行为一致。 **同名不覆盖**：拒绝并提示「已存在同名规范，请换一个文件名」。理由：文件可能已被手工编辑，静默覆盖比让用户改名更糟。**删除前**弹确认框，并显示「有 N 个项目正在使用它」 ——判据是**遍历项目解析有效规范的文件名**（不是哈希），因为此刻文件还在。 ### 26.9 项目级覆盖 ``` globalRecord.docSpecMode: 'none' | 'default' | 'custom' default('default') globalRecord.docSpecFileName: string default('') globalRecord.perProjectDocSpec: boolean default(false) ← 开关，默认关 projectRecord.docSpec: 'none' | 'default' | <文件名> | absent optional() ``` **absent 表示「跟随全局」**，不是 `'none'`——两者语义不同（跟随 vs 钉死无规范）。 **`'default'` 是第四个合法值**，与 `'none'` 一样是语义值而非文件名（见 26.11 三·补之二）。 **只有开关开启时**，新建/编辑对话框才多出一行下拉栏，列表**固定**为 `跟随全局 / 无 / 默认 / 各已上传规范…`，**不随全局选择变化**（同 26.11 三·补）。 ### 26.10 沙箱与写入路径 **文档与规范都由 Host 侧写**（`uploadSpec` / `deleteUploadedSpec`），不由模型或工具写。 **模型只读**。 > 附带说明（转录自实测）：`fs-sandbox` 只 override `writeText`/`editText` > （`fs-sandbox/src/index.ts:80,101,122`），**`readText` 不受限** ⇒ 模型能读 `$DSH_HOME` 下的文档与规范。 > 写则受沙箱限制（`sandbox/src/roots.ts:52` 的可写根 = 会话工作区 + 临时目录，不含 `$DSH_HOME`）， > 故**写入必须经 Host**。本项目的设计前提是**完全权限工作流**（§1），此处仍然遵循它。 ### 26.11 卡片的显示与选择器的落点（2026-10-06 定案） #### 一、卡片显示：说明后果，用警告色 | 存储状态 | 卡片显示 | 颜色 | 高亮 | |---|---|---|---| | `custom` + 文件名**存在** | 文件名 | 普通 | **自定义** | | `custom` + 文件名**不存在/空**，且高亮在**自定义** | 「当前未选择规范，将自动解析为无规范」 | **警告色** | **自定义** | | `custom` + 文件名**不存在/空**，且高亮在**无/默认** | 「未选择」 | 普通 | 无/默认 | | `none` | 「不更新格式：无既定格式则自由书写，有既定格式则在其基础上书写」 | 普通 | 无 | | `default` | 「使用插件内置的规范」 | 普通 | 默认 | **四条规则**： 1. **悬空文件的旧名不显示**——`title`（悬停提示）也一并去掉。显示一个未生效的名字会暗示"这个规范正在用"，而实际生效的是 `none`。 2. **高亮跟随「存储的 mode」，不跟随解析结果**。 3. **高亮只在用户点卡片时移动。** 4. **第二行说明"后果"，且颜色随高亮变化**——只有你**正在依赖**这一格时，它的空才值得警告。高亮在无/默认时，同样的空格子只是普通的「未选择」；在那里报警是在为一个**没人依赖**的格子报警。 > **「无」说的是 POLICY，不是"没有要求"**（2026-10-06 定案）。 > > ``` > 无 = 不更新格式 > ├─ 文档没有格式 → 自由书写 > └─ 文档已有格式 → 在其基础上书写（不重组） > ``` > > 早先的文案是「不要求任何格式」，**可以被读成"想怎么写就怎么写"**，那就等于**授权重组** > 一份已有结构的文档 —— 与「无」的真实含义相反。现在两句都把两种文档情况点明。 > > **三张卡各答一个问题**：`无` 说策略（不管格式）、`默认` 说来源（内置规范）、 > `自定义` 说具体文件 —— 并列时语义整齐。 > **第 2 条是改正，不是设计。** 早先一版让高亮跟随 resolver 的返回值，于是 > **删掉一个文件就让高亮自己跳到「无」**——看起来像"删除改了设置"，而实际**一个字段都没写**。 > 用户报为「删除只是删除，怎么自动跳到无规范了」。 > > **参照物是同一页的「底层工作区」**：选过「指定工作区」后，即使那个工作区没了， > 高亮也**一直停在「指定工作区」**，只是把路径标成警告色——它**从不自动跳回「默认工作区」**。 > 规范卡现在与之同构。 > > **高亮只在用户点卡片时移动。** 断言成对锁住：`3e-d`/`3e-b2` 断言"删除或空确认都不移动高亮"， > `3e-a`/`G` 断言"点卡片才移动"。 > **第 3 条改过两次。** 最初是「尚未选择」**普通三级色**，理由是"状态不该看起来像故障"； > 然后改成**无条件警告色**。用户最终定的是**按高亮分色**：高亮在自定义时警告， > 否则普通「未选择」。**理由**：那一行描述的是**自定义格子的状态**，只有你**正在用这一格** > 时它的空才值得警告；在无/默认下报警是在为一个没人依赖的格子报警。 **名字仍保留在存储里**——同名文件回来（重新上传）即自动恢复生效，只是不显示而已。 #### 二、选择器：未选中时**只给一行提示**，不再弹第二层（2026-10-06 定案） ``` 未选中（列表为空或列表非空但没选中任何行） → 在对话框内显示一行警告色提示 → 不拦截任何出口 ``` **「列表为空」和「没选中任何行」是同一个语义**，但**文案分两句**（原因不同、用户能采取的行动不同）：空列表可用「上传」解决，非空未选只需点一行。两条都说明同一个后果。 | 列表 | 提示 | `确认` | |---|---|---| | 空 | 「当前列表为空，使用自定义规范时将自动解析为无规范」 | 可点 | | 非空、未选中 | 「当前未选中任何规范，使用自定义规范时将自动解析为无规范」 | 可点 | | 非空、已选中 | 无提示 | 可点 → 用该文件 | > **措辞是"将自动解析为无规范"，不是"确认将回退到无"。** 早先那句已经**不成立**： > 确认**不再改变模式**（见「二·补」），空的自定义格是靠 `resolveSpec` **自己**解析成 > `none` 的。旧文案把回退归因于那次点击，是错的。 **`确认` 永不禁用**——无可用选择是**一个选择**（等于选了「无」），不是死路。 **空选择不写 `mode`**——只有点卡片才写。详见下一节。 **`确认` 永不禁用**——无可用选择是**一个选择**（等于选了「无」），不是死路。 #### 二·补：「落成无」是**解析结果**，不是**高亮移动** **这是本节最容易看错的一处，单独写清楚。** ``` 高亮 = docSpecMode 的值 = 用户点的是哪张卡。只有点卡片能改。自定义格 = 一个文件名，或空。 ``` `自定义` + 空格子在语义上**就等于「无」**——`resolveSpec` 对 `custom` + 无可读文件 **本来就返回 `none`**（`spec-store.ts:195-198`），卡片第二行那句「当前未选择规范，将自动解析为无规范」就是在说这件事。 ⇒ **所以"落成无"指的是生效的规范解析成无，不是高亮跳到「无」卡片。** **选择器只写「自定义」格的值**（文件名或空），**它不写 `docSpecMode`**： | 高亮 | 选择器里确认（含空选择） | 结果 | |---|---|---| | 无 | 写值 | 高亮仍在**无** | | 默认 | 写值 | 高亮仍在**默认** | | 自定义 | 写值 | 高亮仍在**自定义**（值空 ⇒ 生效解析为无） | > **唯一的例外**是点「自定义」卡片：那张卡没有可用值时**先开选择器**， > 确认就等于**完成这次点击** ⇒ 此时才写 `custom`。这是用户点的意图，不是选择器替他决定。 > **早先错在哪**：空选择时无条件写 `none`。于是高亮在「默认」时进 `更换…`、 > 什么都没选、按确认，**模式被改成「无」**——用户只是编辑了自定义格的值， > 却被换了高亮。这就是"替用户做选择"。修法：`mode` 的写入点从"无条件"** > 收紧为"仅当自定义卡片是被点击的那张"**，而不是保留一个会自行移动的分支。 > **顺带否掉的一个说法**：注释里曾写"写 `none` 才能让存储与生效一致"。**不需要**—— > `resolveSpec` 本来就会解析成 `none`。落无是**解析的自然结果**，不是靠写一个 mode 换来的。 > #### 为什么删掉了原来的二次弹窗 > > 旧版在**两个出口**都弹一层 `Modal`。两个毛病： > 1. **那个弹窗里的「取消」会把整叠拆掉**，而不是退回列表——用户报为 > 「这个界面点取消就真的什么都不干了……应该返回上级菜单」。 > 2. **结构性错误**：嵌套 `Modal` 共用同一套 Escape / 焦点栈，所以那一层**没法单独关掉**， > 必然连带拆掉外层。 > > 改用**行内提示**后两个问题一起消失：只陈述后果，不拦截；`取消` 也不需要先"穿过"一层。 **`取消` = 只关闭，不写任何设置。** 现在这句是**字面事实**：改选、模式都没落盘，删除也**不由它撤销**（删除在自己的确认框上承诺，那张框的文案写着「此操作不可撤销」）。准确说法： **`取消` 放弃的是"这次规范选择"，不是"我刚才做的所有操作"。** #### 三、删除：即时 + 一次确认，**不延后**（2026-10-06 定案）点垃圾桶 → 弹一次确认 → **立即落盘**。 > **考虑过"前端标记待删、确认时才真删"**，并配"若删到了正在用的那个，取消时问是否恢复"。 > **放弃了**，理由是那个方案有一个说不通的状态：被标成待删的行**还在列表里**—— > 它还能被点选吗？能选就是"既删又用"，不能选就是列表里的一个洞，键盘导航还得跳过它。 > 再加上红色横幅已经警告过一次、保存时还要再警告一次，同一件事说两遍。 > > **一次确认一次**更干净：确认那一刻就是承诺点，之后无论怎么退出都不反悔。 #### 三、`更换…` 才是打开选择器的入口 **卡片点击 = 选择模式**（与「底层工作区」同一分工）；**只有 `更换…` 打开选择器**。例外：没有可用文件时点卡片会**只弹选择器、不写状态**（照抄底层工作区的规则）。 #### 三·补、每项目下拉栏：**跟随全局是独立的一行**（2026-10-06 定案）列表**固定**，与全局选择**无关**： ``` 跟随全局 ← 第 1 行，固定无 ← 第 2 行，固定默认 ← 第 3 行，固定各已上传规范… ← 第 4 行起，空列表就是没有，真空 ``` **无分隔线**（平铺）· **无「（继承全局）」后缀** · 「自定义（无）」**不出现** | 存储 `docSpec` | 选中的行 | |---|---| | absent (`null`) | **跟随全局** | | `'none'` | 无 | | `'default'` | 默认 | | 文件名（文件在） | 该文件 | | 文件名（**文件已删**） | **跟随全局** ← 显示"实际生效的" | > #### 为什么从「继承标记」改成「独立的一行」 > > 标记版必须判断**哪一项才是"全局那一项"**。全局选择是「自定义但为空」时， > 这个问题**没有好答案**：实际生效的是**无**，可选的是**自定义** —— 标记要么**说谎** > （标在「无」上但全局其实是自定义），要么**把「自定义」并进「无」那一行**（用户反对的正是这个）。 > > **独立一行把这个问题取消了**：下拉栏**不再需要知道**全局选择是什么， > 所以 `docSpecMode` / `docSpecFileName` 两个注入 hook **一并删掉**。 > > **代价**（已确认接受）：「跟随全局」不再显示"当前跟的是哪个"，要看就回设置页。 > **顺带消掉一个既存混淆**：早先"项目显式选「无」"与"继承全局而全局解析为无" > **共用同一行标签**（结果相同、来源不明）。现在前者选中「无」，后者选中「跟随全局」—— > **来源与效果都清楚**。 #### 三·补之二、`'default'` 曾经存不进去（2026-10-06 修复） **新下拉栏把「默认」做成独立一行后，这个既存缺陷变得更容易踩到**，所以在同轮修掉。 ``` 实测回包: setProjectDocSpec("default") → {"ok":false,"error":{"message":"not a usable spec file name: \"default\""}} ``` **两处缺一半**： | 位置 | 缺陷 | |---|---| | `index.ts` 写入守卫 | 只放行 `'none'`，`'default'` 被 `isSafeSpecName` 按"文件必须以 `.md` 结尾"拒掉 | | `spec-store.ts` `resolveSpec` | **没有 `override === 'default'` 分支** ⇒ 落到全局选择，而不是内置规范 | **后果**：选「默认」保存后**静默保持原值**；即使写进去，项目也会**跟随全局**—— 与它自己对话框显示的**正好相反**。 **修法**：守卫放行 `'default'`；resolver 补一分支返回 `BUILT_IN_SPEC_PATH`。 `protocol.ts` 的请求注释也补成**四态表**（`null` / `'none'` / `'default'` / 文件名）。 **回归断言**（两侧都锁）： - `verify-doc-spec.mjs`：`resolveSpec` 对 `'default'` 覆盖返回内置路径，且**能压过全局的 `'custom'`**（用非 default 的全局值断言，避免两者混淆）。 - `probe-doc-spec.mjs` `3c-3`：五态写入**都被接受**，且各自选中正确的行。 #### 四、`更换…` = 换记忆，**不动模式**（2026-10-06 定案）同一个对话框有两个入口，**意图不同**，所以确认的写入也不同： | 入口 | 用户意图 | 确认写入 | |---|---|---| | **卡片**（无可用值时） | "我要用这个模式" | 值 **+ mode** | | **`更换…`** | "换掉记住的那个文件" | **只有值**，mode 不动 | > **三件事都必须保留**：**预选**（打开时停在记忆上，替换只需一次点击）、**记忆**（切模式时不丢， > 切回来能恢复）、**写入**（真的替换，不是丢弃请求）。**唯一不能做的是移动卡片**——卡片是切模式的。 > > **为什么**：`docSpecFileName` / `base.path` 是**记忆**，按设计**跨模式保留**。早先确认一律写 > `mode='custom'`/`'specified'`，于是「默认」下点 `更换…` 选完文件，卡片也跟着跳到「自定义」—— > 用户报为「点更换然后点确定就跳到自定义了」。 **工作区的实现要点**：`setBaseWorkspace` 必须带 mode，而 `withDefaultMode` 在 `default` 分支原本会用**已存的** path 覆盖请求里的 path ⇒ **替换被静默丢弃**。修法是让 `withDefaultMode` 接受可选的新记忆（`requested`），Host 与 Client **共用同一个助手**——那份文件的注释专门警告过两边各写一遍会漂移。 **两个方向都锁死了断言**：写入**落地**（新路径/新文件名确实存进去了）+ 模式**不动**。只测其中一个都不够——只测"不动"，丢弃请求也会通过；只测"落地"，跳模式也会通过。 ### 26.12 验证 | 脚本 | 覆盖 | 断言数 | |---|---|---| | `verify-doc-spec.mjs` | 文件名安全、`$DSH_HOME` 解析、规范解析（含陈旧覆盖与 **`'default'` 覆盖**）、哈希、漂移渲染、标签匹配、**schema 兼容** | 79 | | `verify-project-host.mjs` | 注册表行为 + **并发写不丢失**（12 轮两字段、七字段、复合写入完整性） | 100 | | `verify-project-injection.mjs` | 六种注入形态 + **漂移谓词 8 项**（含「无」不询问的回归）+ 血缘遍历 | 52 | | `probe-doc-spec.mjs` | **真实浏览器**：卡片渲染（含「无」的策略文案）、三重门控、卡片第二行的按高亮分色、未选中的行内提示、"高亮只跟点卡片"三模式矩阵、**下拉栏固定四项 + 覆盖五态各自选中哪一行（含 `'default'` 回归）**、悬空名显示、上传/拒绝/删除、色彩令牌、帧级无闪烁 | 127 | **`verify-doc-spec.mjs` 里最关键的一条是 schema 兼容**：真实的存量 global 与 project 记录（缺新字段）**必须仍能解析**——否则整个 domain open 被拒，用户所有项目一起读不出来。 **`probe-doc-spec.mjs` 里最该保住的是帧级闪烁断言**：它在深色主题下用 CDP 录屏测 "点无关开关时禁用卡不得跳变"，且**自带两条防空转护栏**（必须命中选中的禁用卡、必须与页面底色可分辨）。没有那两条护栏时它会"测着一张白色卡片"稳定通过——那是假通过。 ## 27. 自动化代码审查（ocr）的处置记录（2026-10-14）外部工具 `@alibaba-group/open-code-review` 对 **0.3.0** 的树跑出 **641 条**发现。本章记录处置方式与**哪些结论被实测推翻**——后者比"修了多少条"更重要，因为审查是模型产出的，不是人核对过的。 ### 27.1 分批与规模 | 阶段 | 范围 | 条数 | 状态 | |---|---|---|---| | 0 | 安全（最优先） | 11 | ✅ | | 1 | 两条 CRITICAL | 2 | ✅ | | 2 | `src/` 产品代码 | 143 | ✅ | | 3 | CI 与打包配置 | 33 | ✅ | | 4 | `scripts/lib/` | 17 | ✅ | | 5 | `scripts/verify-*.mjs` | 52 | ✅ | | 6 | `scripts/probe-*.mjs` | 386 | ✅ | | 7 | `scripts/` 其它 | 5 | ✅ | 看板与逐条勾选在会话临时清单里（`.agent/temp/`），不进仓库——它是过程产物，不是产品文档。 ### 27.2 被实测推翻的审查结论这些**没有**按审查的说法改，因为所述机制在当前代码里不成立。每条都做了测量： | 位置 | 审查的说法 | 实测 | |---|---|---| | `src/spec.ts:82/95/361` | 共享的可变 zod 默认值，跨解析累积 | zod 4.6.5 对数组/非空数组/对象字面量**每次解析返回新引用**；版本**精确锁定**无范围 | | `src/client/tree.ts:307` | 遍历是 O(n²) | `includes` 调用次数**跟随 fork 数**而非节点数：n=200 且 0 fork → 0 次；5 fork → 5 次；200 fork → 200 次。代价是 O(forks × n)，`splice` 那部分是不可避免的 O(n) | | `.gitattributes` | 索引里存有 CRLF，需 renormalize | 按**字节**扫描 143 个已跟踪文本 blob：**0 个含 CRLF**；`git add --renormalize .` 不暂存任何东西 | | `scripts/compare-bundle.mjs:68` | 可选链不全，正则失配会抛 TypeError | 可选链**短路整条链**：`exec()?.[1].replace()` 得到 `undefined` 而不抛错。**但真问题更严重**：两侧产物都把 `inject` 写成变量引用，于是两侧都是 `undefined`，`undefined === undefined` ⇒ **恒真通过**。见 27.3 | | `scripts/probe-base-workspace-routing.mjs:155` | `child.kill()` 收不到进程树，应改用 `taskkill /T /F` | 子进程以 `ELECTRON_RUN_AS_NODE=1` 直接跑 `bin.js`（服务本体），全仓清理约定就是 `child.kill()` | ### 27.3 按「形态」修类，而不是按审查的逐条清单审查对同类缺陷只点了几处，实际分布广得多。**扫描形态**（而非读清单）发现的： | 类 | 审查报的 | 实际 | 说明 | |---|---|---|---| | 凭证泄漏 | 3 处（其中 2 处早已修好） | **14 处未脱敏**，遍及 12 个 probe | 每个 probe 都从子进程 stdout 抓 `?token=`——那是**活凭证**。启动失败时会把 token 打进 CI 日志 | | `spawn` 无 `error` 监听 | 少数几处 | **59 个里只有 3 个有** | 失败的 spawn 发 `'error'` 且不写 stdout ⇒ 要么直接崩进程，要么 120 秒后误报 `boot timeout` | | `chromium.launch` 在 `try` 外 | 少数几处 | **45 个** | 启动失败会抛出脚本，留下存活的 Host 和打开的浏览器 | | 未读的 RPC 响应 | 2 处 | **4 处** | 丢弃响应 ⇒ setup 静默失败，后续断言测的是错的状态 | | 硬编码机器路径 | 1 处 | **5 处 / 4 文件** | 在别的机器上会注册**错误的目录**，而输出里没有任何提示 | | `let running = child` 别名 | 1 处 | **29 个**（去除 28 个） | 纯别名，在读者和真正被杀掉的进程之间加了一层 | ### 27.4 自己引入的回归，以及校准过的扫描修类会引入新缺陷。本轮的三个都是**会让探针完全跑不起来**的： 1. **`page.on(...)` / `installRowKeyHelpers(page)` 留在模块顶层**，而 `page` 已改为在 `try` 内赋值 ⇒ 对 `undefined` 调 `.on`，`TypeError`。涉及 **10 个文件**。 2. **`join(repoRoot, ...)` 被放进 `page.evaluate` 的页面侧函数体** ⇒ 浏览器里没有 `join`/`repoRoot`， `ReferenceError`，种子请求从未执行。 3. **`probe-upstream-upgrade.mjs` 的 boot promise 引用了该文件里不存在的 `child`**（阶段 1 引入） ⇒ 每次运行都 `ReferenceError`。 **教训（写下来是因为我犯过两次）**：扫描结果的**假阳性会误导大范围改动**。第一版「顶层用了 `page`」扫描报了约 250 处，因为它把 `const isMasked = () => page.evaluate(...)` 这类**助手定义**当成顶层执行；校准（拿审查明确说"已正确"的文件作反例）后真值是 **2 处**。同类地，第一版「浏览器侧引用 Node 常量」扫描把 `Array.prototype.join` 当成 `node:path` 的 `join`，报了 7 处假阳性。 **先校准再动手**，否则会白改两百多行本来正确的代码。 ### 27.5 机械不变量（替代逐文件肉眼核对） `scripts/` 下全部 59 个 probe，按形态检查六类；本阶段开始时六类都非零，现在全为 0： redaction 0 未脱敏的启动回显 machinePath 0 硬编码 C:\Users\Think 路径 errorListener 0（46 个 spawn DSH 的 probe 都有 error/exit 处理） launchOutsideTry 0 顶层 launch unguardedClose 0 未守卫的 browser.close() literalTrueCheck 0 恒真的 check(..., true, ...) ### 27.6 无法执行的部分（必须明说） **52 / 59 个 probe 需要 live DSH 实例，本环境未能执行。** 根因是**探针自己的环境缺口**，不是代码问题，也不是"别的 DSH 在拦"——下面这条我一开始写错了，实验推翻了它。 > **更正（同日）**：本节初稿写的是「用户侧 DSH 在运行、Electron 单例把隔离实例接管了」。 > 那是我**推断**的，没有验证，而且**是错的**。实验证据： > > 1. `ELECTRON_RUN_AS_NODE=1` 下 `bin.js --version` 正常输出 `0.2.0-rc.2`，`web --help` 正常—— > 启动方式本身没问题； > 2. 单例假设还自相矛盾：真有单例接管，进程会**转发给既有实例并退出**，不会存活 24 秒； > 3. 真正的原因是 **profile 缺 `cordis.yml`**：`dsh plugin --profile pg add ` 建的 profile > 只是个**用户覆盖层**（只有 `cordis.patch.yml` + `package.json`），没有基础 profile 可挂载。 > 实测该 profile 启动后：进程存活、**不监听端口、stdout/stderr 全空** ⇒ 探针 120 秒超时。 > 4. 对照实验：在干净 `DSH_HOME` 上先 **`dsh --profile pg --from-default-profile web`** 派生 > profile（这一步会生成 `cordis.yml`），再 `plugin add`，然后按探针的**原样**命令启动—— > **端口 3 秒内就监听**。 > > 所以探针的启动命令是对的，缺的是**建 profile 的方式**：59 个探针里 **0 个**做过 > `--from-default-profile`。DESIGN.md 第 15 章（L1559）早就记过这个陷阱 > （`probe-plugin-toggle.mjs` 需要预建 `official` profile，否则"official exited early with 1" > 是**探针环境缺口，不是产品回归**）——但那个结论没有被推广到其余探针。 > > **待修**：探针需要预建 profile 的步骤应写进使用说明（或由探针自己在启动前派生）。 > 这是阶段 8.2/8.3 的前置条件，不是产品缺陷。实际**执行**过的：`probe-approach-b`、`probe-slots`、`probe-service`、`probe-grouping-seam`、 `probe-inject-wait`、`probe-contribution`、`probe-retention`、`probe-service-timing`、 `probe-host-import`（含坏路径反向对照）、`compare-bundle.mjs`，以及 `redactToken` 的纯函数行为验证。 `service-timing` 还做了**负向对照**（用 `--import` 覆盖 `Context.prototype.get`）确认断言与退出码是真的。每个提交都明写了未执行的部分。阶段 8.2/8.3（抽跑 6 个探针、真实 UI 实测）因此**待环境可用后补做**。 ### 27.7 反向对照（证明"修好了"不是空话） - `compare-bundle.mjs` 在门禁内（`verify:bundle`），所以能做完整反向对照：破坏 loader id → 2 个 FAIL；6 种构建机路径 → 各自 FAIL 且**每种恰好 1 处完整路径**；改动 `inject` 列表 → FAIL + exit 1；无法解析 → SKIP 而非通过；产物缺失 → 2 行诊断 + exit 2。 - `grouping.ts` 13 个座位在旧代码上 FAIL；`tree.ts` 6 个；`isValidLink` 3 个（大写 scheme）； purity gate 拒绝 `TYPE_ONLY` 值导入；`verify-projects` 的 pin 顺序 3 个； `verify-locales` 的死键检查能抓出伪造的未使用键；asar 6 个构造损坏输入各自给出具名错误。