@mingmaple/dsh-handover 0.9.14 → 1.0.0

package/docs/troubleshoot.md

@@ -1,85 +1,269 @@
 # 常见故障处理
 
-## 工具缺失或数量不对
+本文适用于 DeepSeek Harness（DSH）中的 dsh-handover 插件。每节按现象、原因与处置 3 段列出。
 
-1. 在全局会话执行 `ho_diag`，看「角色判定与工具集」一节。
-2. 全局应为 24 个，项目与杂项 11 个，普通 0 个。
-3. 新建会话时角色表中尚无该会话，插件会判为普通；角色写入后，该会话下一轮请求即按新角色装配。
-4. 仍未装配时，在设置页「会话角色」卡片里重新设一次角色；仍无效则执行 `ho_diag` 查 `roleGating` 字段。
-5. 改过源码但未生效：执行 `node scripts/build.mjs`，然后在插件列表停用并启用一次，不必重启 DSH。提示段文本不随重载替换，仍显示旧文本时重启 DSH。
-6. 子会话不装配 `ho_` 与 `peer_` 工具，属正常：子会话在工具表解析阶段即被排除，与角色设置无关。
+## 工具数量不符
+
+现象：`ho_status(view="diag")` 显示的工具数与角色不符，或会话中看不到插件工具。
+
+原因：角色表未写入；角色按标题、工作目录与首条提示推断。子会话默认按普通处理；改过源码但未重建。
+
+处置：
+
+1. 在全局会话执行 `ho_status(view="diag")`，查看「角色」与「角色装配」。
+2. 工具数应为全局 14、项目 11、杂项 10、普通 0。
+3. 角色未写入时，在设置页「会话角色」重新设定；角色写入后，该会话下一轮请求即按新角色装配。
+4. 子会话不装配插件工具，属正常；子会话在工具表解析阶段即被排除。
+5. 改过源码时，执行 `node scripts/build.mjs`，在插件列表停用再启用；提示段文本须重启 DSH 或新建会话才换新。
 
 ## 工作区未接入
 
-`ho_diag` 或设置页显示未接入时，走设置页「首次安装」卡片：粘贴绝对路径后点「一键部署」，文件体系、工作区与会话一次建好；也可以只点「仅建立文件体系」，再点「注册为工作区」。命令行等价操作：
+现象：设置页或 `ho_status` 显示未接入，工具报找不到全局根。
+
+原因：尚未部署文件体系，或当前目录不在已注册的工作区内。
 
-```text
-ho_init(parent="<已存在目录的绝对路径>", register=true)
-```
+处置：
 
-装配里没有写死 `workspaceRoot`。工具侧按配置项、会话工作目录向上查找的顺序定位，向上找不到时再查工作区登记；设置页没有会话上下文，按配置项、标题含「全局」且带 `_Control_Center` 的工作区、任一带 `_Control_Center` 的工作区定位。
+1. 在设置页「首次安装」卡片粘贴长期目录的绝对路径，点击「一键部署」。
+2. 也可点击「仅建立文件体系」，再点击「注册为工作区」。
+3. 命令行等价操作：`ho_workspace(action="init", parent="<已存在目录的绝对路径>", register=true)`。
+4. 再新建标题含「全局」的会话。
 
 ## 新建会话报「必须指明工作区」
 
-`ho_sessions(action="new")` 必须落到明确的工作区：传 `workspace`（id、标题或路径），或传某个已注册工作区根的 `cwd`。两者都没有，或项目没有对应工作区时，工具会报错并列出已注册的工作区，不会静默落到调用者所在的工作区。
+现象：`ho_sessions(action="new")` 报错，并列出已注册的工作区。
+
+原因：未传 `workspace`，也未传某个已注册工作区根的 `cwd`。
+
+处置：
+
+1. 用 `ho_workspace(action="list")` 查看清单。
+2. 没有工作区时先建：`ho_workspace(action="create", path="<目录>", title="<标题>", ensure=true)`。
+3. 再建会话：`ho_sessions(action="new", confirm=true, workspace="<id 或标题>", title="<标题>")`。
+4. 项目会话可同时传 `project`，插件按同名工作区匹配。
+
+## 设置角色后工具未变化
+
+现象：设定角色后，目标会话仍看不到对应工具。
+
+原因：会话休眠时设定，工具在下次开轮时装配；插件重载后，已存在的会话沿用旧提示段文本。
 
 处置：
 
-1. 先看清单：`ho_workspace(action="list")`，或直接读报错文本里的清单。
-2. 还没有工作区时先建：`ho_workspace(action="create", path="<目录>", title="<标题>", ensure=true)`。`ensure=true` 会在目录不存在时自动创建。
-3. 再建会话：`ho_sessions(action="new", confirm=true, workspace="<id 或标题>", title="<标题>")`。项目会话可同时传 `project`，插件会按同名工作区匹配。
+1. 在目标会话触发一轮请求。
+2. 执行 `ho_status(view="diag")`，查看「角色装配」中的已装配会话数与最近时间。
+3. 仍未生效时，在设置页重新设定一次角色。
+4. 需要新提示段文本时，重启 DSH 或新建会话。
+
+## 角色下拉不出现「全局」
 
-## 设置角色后工具没有变化
+现象：设置页「会话角色」的下拉里没有「全局」选项。
 
-会话休眠时设定角色，插件会在它下次开轮时装配工具与提示段。0.9.12 起这一装配由全局会话事件驱动，不必重启 DSH。若仍看不到应有的工具：
+原因：本机已有全局在任会话；同一类别只允许一个在任者。
 
-1. 在设置页「会话角色」重新设定一次，注意「存活会话当场生效」一栏的提示。
-2. 执行 `ho_diag`，看「角色收窄」一栏的已装配会话数与最近时间。
-3. 插件刚从旧版本换上来时，已存在的会话沿用旧提示段文本；重启 DSH 一次即换成新文本，工具裁剪不受影响。
+处置：
+
+1. 先由现任全局会话办理换任，或清理在任登记。
+2. 再设定新的全局会话。
 
 ## 设置页刷新失败
 
-页面保留上次读数，并显示其时间与失败原因。常见原因：
+现象：设置页保留上次读数，并显示读数时间与失败原因。
+
+原因：宿主缺少连接服务时改用 HTTP 回退；桌面版图形界面返回 403；请求超时。
 
-- 宿主没有 `connection` 服务：插件改用 HTTP 回退；纯 CLI 场合回退会被静默跳过。
-- 桌面版 GUI 对非浏览器策略请求返回 403：不要用裸 `fetch` 取数，插件已走 `/api` 载体。
-- 请求超时：页面加载 30 秒、状态 8 至 30 秒、写操作 15 至 900 秒；稍后重试。
+处置：
+
+1. 稍后重试，或重启 DSH。
+2. 纯命令行场合没有浏览器回退，属预期行为。
+3. 排查时用 `ho_status(view="diag")` 取同一份数据。
+
+## 压缩未执行
 
-## 压缩未生效
+现象：`ho_checkpoint` 返回已登记或拒绝排压缩，但回合结束后没有压缩。
+
+原因：未取得用户授权；交接体检不通过；压缩额度用尽。水位低于可压缩线；距上次压缩不足 120 秒；目标会话不空闲。
+
+处置：
 
-1. 压缩须由用户在设置页点「压缩授权」，单次授权 5 分钟内有效，或在聊天框发送 `/allow-compact`。
-2. `ho_checkpoint` 只登记，由调度器在回合结束后执行；目标必须空闲。
-3. 交接体检不通过时拒绝排压缩，先用 `ho_handover(action=read)` 检查结构。
-4. 已压满 3 次后不再压缩，应换任：由本会话写好交接后调用 `ho_succeed` 自行换任，须用户先发送 `/allow-succeed` 授权。额度用尽的判定先于水位；低水位与 `force` 均不能越过，`ho_sessions` 的压缩指令（`action="order", order="compact"`）同样会被拒绝。
+1. 由用户点击设置页「授权压缩」，或在聊天框发送 `/allow-compact`；授权 5 分钟内有效。
+2. 用 `ho_handover(action="read")` 复核交接结构，补齐缺项。
+3. 已压满 3 次时不再压缩，应按换任处理。
+4. 水位低于 35% 时，提前压缩须用户主动要求并授权。
+5. 等当前回合结束再重试；确有需要时传 `force=true`。
 
 ## 换任未执行
 
-`ho_succeed` 报「换任未执行，未做任何写入」时，按报出的原因逐项处理：
+现象：`ho_succeed` 报「换任未执行，未做任何写入」。
+
+原因：没有授权；调用者不是在任会话；交接体检不合格；该类会话已有新的在任登记。
+
+处置：
+
+1. 由用户发送 `/allow-succeed`，或在设置页点击「授权换任」；授权一次性，5 分钟内有效。
+2. 用 `ho_office` 确认现任会话，再由现任会话执行。
+3. 用 `ho_handover(action="read")` 复核交接，补齐「下一步」等缺项。
+4. 按报错列出的缺项逐条处理后重试。
+
+## 交接越写越长
+
+现象：交接文件持续增大，出现多个版本的实施记录、需求全文与里程碑，接任者读数分钟仍抓不到在途状态。
+
+原因：历次刷新在旧文件上续写，未按固定流程重写。交接只应写在途与指针，体积不设上限，但由结构控制。
+
+处置：
+
+1. 按 `_Control_Center/templates/Handover.md` 的 4 步重写：`action="read"` 读旧交接、`action="archive"` 归档、读模板、`action="new"` 新建写入。
+2. 已完成经过移入台账 `Global_Changelog.md` 或任务提交说明；需求全文移入 `PLAN.md` 或任务库文档。
+3. 旧文件保留在归档目录，不删除、不搬章节。
+
+## 交接体检不通过
+
+现象：`ho_handover` 写入后体检不通过，或 `ho_gate` 报缺节。
+
+原因：项目交接缺「正在做的事」或「下一步」；全局交接缺 §0 至 §7 或字段不全。正文残留「待填」「TODO」一类占位符。
+
+处置：
+
+1. 按 `ho_gate` 输出逐项补齐。
+2. 全局交接保留 §0 至 §7 全套；项目交接至少保留「正在做的事」与「下一步」。
+3. 补齐后重跑 `ho_gate`。
+
+## 体系注册路径失效
+
+现象：`ho_docmap(action="check")` 或 `ho_gate` 报「失效 N 条」。
+
+原因：注册里列出的路径被移动或删除；写入时用了绝对路径或越界路径。
+
+处置：
+
+1. 用 `ho_docmap(action="read")` 查看当前注册。
+2. 按实际位置重新写入：`ho_docmap(action="write", entries=[…])`；路径一律写工作区相对路径。
+3. 写入前逐条校验路径存在，缺项即拒绝写入。
+4. 只有本类别在任会话可以写入；已交出的旧会话只读。
+
+## 旧体系未迁移
+
+现象：`ho_gate` 或 `ho_status` 提示「旧文档定位待迁移」。
 
-1. 没有授权：由用户在聊天框发送 `/allow-succeed`（可留空，也可带 8 位短号授权别的会话），或在设置页「压缩授权」卡片的「换任授权」区域点「允许换任」。授权一次性、5 分钟有效、按会话生效；压缩授权不能顶替换任授权。
-2. 不是在任者：只有登记表中该类会话的现任本人可以换任；已记过一次换任的旧会话也不得再次换任。先用 `ho_office` 确认现任的名字与会话 id，再由现任会话执行。
-3. 交接体检不合格：报错逐条列出缺项——「下一步」一节缺失或没有条目、内容为空、仍有「待填」「TODO」一类占位符。补齐后用 `ho_handover(action=read)` 复核，再重新调用。
+原因：工作区由 0.9.x 创建，`_Control_Center/records/docmap/` 仍存在。
+
+处置：
+
+1. 先运行 `ho_workspace(action="scaffold")` 补齐 1.0 的目录与文件。
+2. 再运行 `ho_workspace(action="migrate")`。
+3. 迁移把条目并入体系注册，并把旧目录移入备份目录，不删除旧文件。
+4. 迁移完成后重跑 `ho_docmap(action="check")`。
+
+## 提示段未更新
+
+现象：体系注册或计划写入后，提示段仍是旧内容；插件升级后流程文本仍是旧版。
+
+原因：提示段按注册文件签名重装；插件重载不替换已存在会话的提示段文本。
+
+处置：
+
+1. 确认写入结果为「提示段已重装」。
+2. 未重装时，在该会话触发一轮请求，或重启 DSH。
+3. 升级插件后，重启 DSH 或新建会话。
+4. 一次性提醒的状态保存在 `~/.dsh/storages/dsh-handover.reminders.json`；需要重新提醒时删除对应会话条目。
+
+## 全局任务库建立失败
+
+现象：`ho_sessions(action="task-init", task="<任务名>")` 报错。
+
+原因：调用者不是全局会话；任务名不合法；任务目录已存在且非空。
+
+处置：
+
+1. 在全局会话执行该动作。
+2. 任务名不超过 40 个字符，不含路径分隔符；名字不能作为目录名时拒绝建立。
+3. 目标目录 `_Control_Center/tasks/<任务名>/` 已有内容时，先归档或改名。
+
+## 全局任务独立失败
+
+现象：`ho_sessions(action="new", from_task="<任务名>")` 报错或未迁移。
+
+原因：调用者不是全局会话；未同时给 `role="project"` 或 `role="misc"`；目标目录已存在且非空；未传 `confirm=true`。
+
+处置：
+
+1. 由全局会话执行，并同时指定 `role` 与 `from_task`。
+2. 独立为项目时给 `project`；独立为杂项时给 `task`。
+3. 确认目标工作区与目标目录为空。
+4. 征得用户同意后传 `confirm=true`。
 
 ## 项目名或任务名不合法
 
-工具报出「项目名不合法」「任务名不合法」一类错误时，说明名字不能作为目录名使用；此时不写入磁盘，也不改动登记。按下列规则改名后重试：
+现象：工具报「项目名不合法」或「任务名不合法」。
+
+原因：名字要当目录名使用；长度、字符集或保留名不符合要求。
+
+处置：
 
-- 项目名不超过 24 字符，任务名不超过 40 字符。
-- 不含 `< > : " / \ | ? *` 与控制字符，不以点或空格结尾，不使用 `CON`、`NUL`、`COM1` 这类设备保留名。
-- 名字通常从会话工作目录、首条提示或标题推断。若报错指出名字含 `*` 等字符，检查首条提示中是否将 `Projects/**` 这类通配写法写在与项目名相邻的位置。
+1. 项目名不超过 24 个字符，任务名不超过 40 个字符。
+2. 名字不含路径分隔符、`< > : " / \ | ? *` 与控制字符。
+3. 名字不以点或空格结尾，不使用设备保留名。
+4. 名字来自首条提示时同样校验；不合法则报错，且不写入磁盘。
 
-名字合法但被判为普通角色的会话，用设置页「会话角色」卡片或 `ho_sessions(action="role")` 明确设定。
+## 身份互转失败
+
+现象：`ho_sessions(action="role", migrate="auto")` 报错或只完成一部分。
+
+原因：目标目录已存在且非空；名册里已有目标类别；快照失败。
+
+处置：
+
+1. 确认目标 `Projects/<项目名>/<项目名>库/` 或 `_Misc/tasks/<任务名>/` 为空。
+2. 确认名册里没有同名类别。
+3. 重试前检查 `_Archives/_Global/Backups/身份迁移_*` 下的快照。
+4. 也可改用 `migrate="direct"`：旧体系进备份目录，新位置按模板新建。
+
+## 名称注册被拒绝
+
+现象：`ho_office(action="register", name="<名称>")` 报错。
+
+原因：本会话已有注册名；类别已有其他在任者；名字过长或含路径分隔符。
+
+处置：
+
+1. 注册名只在首次注册时写入，注册后不得自行修改。
+2. 需要改名时由全局处理。
+3. 类别已有在任者时，先由全局办理现任的换任或清理。
 
 ## 迁移后原路径失效
 
-若链接被误删，页面会显示「原路径不存在」与「重建链接」。执行：
+现象：搬动全局根目录后，原路径的链接丢失，页面提示「原路径不存在」。
 
-```text
-ho_workspace(action="move-repair")
-```
+原因：链接被删除，或切换未完成。
 
-只重建链接，不改动文件。若新位置也不存在，先确认数据实际位置，再决定是否回退。
+处置：
 
-## 交接体检报「缺节」
+1. 执行 `ho_workspace(action="move-repair")` 重建链接；该动作只建链接，不改动文件。
+2. 用 `ho_workspace(action="move-status")` 查看迁移阶段。
+3. 新位置也不存在时，先确认数据位置，再决定是否回退。
+
+## 跨平台相关
+
+现象：在 Linux 或 macOS 上，7-Zip 探测失败、迁移后路径比较异常，或提示里出现 Windows 专有词。
+
+原因：配置了只适用于 Windows 的 7-Zip 路径；同一条路径用不同大小写写法时被误判为相同或不同。
+
+处置：
+
+1. 不配置 `sevenZipPath` 时，插件按常见位置与 PATH 探测 `7z`、`7zz`、`7za`；定制安装再填绝对路径。
+2. 路径比较由 `lib/pathkey.mjs` 统一处理：Windows 与 macOS 折叠大小写，Linux 保留；不要另写比较逻辑。
+3. 迁移后的旧路径在 Windows 是 junction，在 POSIX 是目录符号链接；删除链接即可回退。
+4. 没有 7-Zip 时用 `format=tar` 或保持 `auto`，内置归档器功能等价。
+
+## 语体门禁或文档校验不通过
+
+现象：`npm run test:style` 或 `npm run test:docs` 非零退出。
+
+原因：命中阻断级条款或文档规则，例如口语词、感叹号、界面动作未写「点击」、版本不一致、链接不可达。
+
+处置：
 
-项目交接至少要有「正在做的事」与「下一步」两节；全局交接需要 §0 至 §7 全套，§0 含七个字段，§7 至少一行 session id。缺节允许压缩，不合格必须先补齐。
+1. 按输出逐条定位文件与行号。
+2. 语体门禁的阻断项为 W-01、W-02、W-04、W-05、W-07 与 W-08，其余为警告。
+3. 文档校验同时检查工具名、版本、链接与版本说明；按提示修正后重跑。

package/package.json

@@ -1,71 +1,74 @@
-{
-  "name": "@mingmaple/dsh-handover",
-  "version": "0.9.14",
-  "type": "module",
-  "description": "DeepSeek Harness 插件：把「全局」的交接、闸门、会话清点与上下文压缩续跑流程做成工具（dsh-handover）",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MingMaple/dsh-handover.git"
-  },
-  "homepage": "https://github.com/MingMaple/dsh-handover#readme",
-  "bugs": {
-    "url": "https://github.com/MingMaple/dsh-handover/issues"
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "handover",
-    "context-compaction"
-  ],
-  "engines": {
-    "node": ">=20",
-    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
-  },
-  "exports": {
-    ".": "./src/index.mjs",
-    "./client": "./src/client.js"
-  },
-  "files": [
-    "src",
-    "scripts",
-    "docs",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "test": "node src/selftest.mjs --tool all",
-    "test:blank": "node scripts/blank-dsh.mjs",
-    "test:smoke": "node scripts/blank-smoke.mjs",
-    "test:migrate": "node scripts/e2e-migration.mjs",
-    "test:docs": "node scripts/check-docs.mjs"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./src/cordis.patch.yml"
-    },
-    "client": {
-      "platform": "web",
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-connection"
-      ]
-    },
-    "compatibility": {
-      "dsh": "0.2.2-rc.1",
-      "profiles": [
-        "desktop",
-        "web"
-      ],
-      "dshReleases": {
-        "0.2.1-rc.2": "compatible",
-        "0.2.2-rc.1": "compatible"
-      }
-    }
-  }
-}
+{
+  "name": "@mingmaple/dsh-handover",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "DeepSeek Harness 插件：把「全局」的交接、闸门、会话清点与上下文压缩续跑流程做成工具（dsh-handover）",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MingMaple/dsh-handover.git"
+  },
+  "homepage": "https://github.com/MingMaple/dsh-handover#readme",
+  "bugs": {
+    "url": "https://github.com/MingMaple/dsh-handover/issues"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "handover",
+    "context-compaction"
+  ],
+  "engines": {
+    "node": ">=20",
+    "dsh": ">=0.2.1-rc.2 <0.3.0-0"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./client": "./src/client.js"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node src/selftest.mjs --tool all",
+    "test:blank": "node scripts/blank-dsh.mjs",
+    "test:smoke": "node scripts/blank-smoke.mjs",
+    "test:migrate": "node scripts/e2e-migration.mjs",
+    "test:docs": "node scripts/check-docs.mjs",
+    "test:style": "node scripts/style-gate.mjs",
+    "test:behavior": "node scripts/behavior.mjs",
+    "test:portability": "node scripts/portability.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./src/cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-connection"
+      ]
+    },
+    "compatibility": {
+      "dsh": "0.2.2-rc.1",
+      "profiles": [
+        "desktop",
+        "web"
+      ],
+      "dshReleases": {
+        "0.2.1-rc.2": "compatible",
+        "0.2.2-rc.1": "compatible"
+      }
+    }
+  }
+}