@mingmaple/dsh-handover 0.9.22 → 1.0.0

package/README.md

@@ -1,6 +1,8 @@
 # dsh-handover
 
-DeepSeek Harness 插件，用于管理长会话的上下文水位、交接文档与压缩流程。插件按会话角色装配工具与提示段，只使用宿主公开的扩展点，不改动 DSH 本体。
+DeepSeek Harness（DSH）插件，用于长会话的上下文水位管理、交接文档、行动计划与体系注册。插件只使用宿主公开的扩展点，不改动 DSH 本体。
+
+当前版本 1.0.0。支持 DSH 0.2.1-rc.2 至 0.3.0，不含 0.3.0 及其候选版；准确范围见 `package.json` 的 `engines.dsh`。
 
 ## 为什么需要
 
@@ -8,175 +10,177 @@ DeepSeek Harness 插件，用于管理长会话的上下文水位、交接文档
 
 本插件一定能很好地帮助你。来试试吧；不满意，随时关闭插件并删除即可。
 
-## 功能
+## 核心机制
 
-- 起始简报：水位、闸门、活跃与沉默、阶段建议，一条命令返回。
-- 交接体检：检查交接文档的结构、字段与占位符，逐条列出问题；覆盖全局、已登记的项目与已登记的杂项任务。
-- 压缩与续跑：由水位与剩余压缩次数共同判定时机，由用户授权，回合结束后执行；压缩后的去向由助手在登记时选择，继续工作时续跑，任务已收尾时静默等待；状态切换与失败原因写入结果。
-- 在任登记与查询：每一类会话（全局、各个项目、各个杂项任务）都登记当前在任的会话与历史编号，记录保存在工作区内的 `Office.json`；按名字或旧编号查询现任，不启动会话也可用命令行查询。
-- 换任由会话自行办理：在任会话在用户授权后自行检查交接、建立接任会话并登记在任，不再由全局会话转交。
-- 会话清点与角色：查看会话水位与状态，设定角色，建立下一代会话，归档与解归档。
-- 会话间通信：会话之间可直接对话，不必经全局转述；默认沉默，任务完成不向全局报告。
-- 工作区迁移：预检、复制并逐文件校验、切换、改写登记、重建链接、清理旧备份。
-- 快照与迁移包：库快照、打包、校验与恢复，包内绝对路径单独体检。
-- 通用规范：各会话共用的做法集中在 `_Control_Center/standards/`，一条规范一个子目录，可随附脚本；写入默认本库，明确「写入通用规范库」一类要求才进共用库。
-- 设置页：常规卡片为授权、移动全局根目录、会话角色、全局前置提示词、会话水位、通用约束条闸门、交接文档体检、插件与最近一次会话间通信判定；末尾另有默认折叠的「工具明细」与「使用说明」。授权与会话水位只列在任会话（全局、各项目、各杂项任务各一行），授权超过五个分页折叠；会话角色按 DSH 工作区分组、默认折叠，已归档与目录已不存在的会话不列出；交接体检覆盖已登记的项目与杂项。尚未接入工作区时置顶显示「首次安装」，可一键部署文件体系、工作区与会话；已接入但还没有全局会话时显示「全局会话」卡片。
+### 任务流程
 
-## 安装
+层级一为轻量任务：单文件修改、局部改名、语法修复、格式化与内容读取。此类任务直接执行，不写计划，不做查证。
 
-### 从 GitHub 安装
+用户说「讨论一下」，或助手已就流程询问过用户时，执行前须再确认。用户明确说「直接做」的除外。
 
-桌面版：侧栏「插件」→「添加插件」，粘贴仓库地址 `https://github.com/MingMaple/dsh-handover`，装完重启 DSH。
+层级二为繁重任务：新增功能、多文件联动、重构、架构或接口变更。按以下顺序执行。
 
-Web 或 CLI：
+1. 先判断纯窗口是否可能超过 40%，当前占用不计入。
+2. 在任务根写 `PLAN.md`：超过 40% 时计划里就安排拆子智能体，助手只做统筹与收尾；没超过就按自己完成来写。写完回看上下文核对。
+3. 子智能体按成本使用：单个自身亦需十余步、结论还要回读；只在单块 ≥15 步或需读 ≥10 个文件、确需隔离、且结果能机械验收时才派，并发 ≤3；能写成脚本再抽检的先写脚本；派几个、每个多少步写进计划随计划确认；同一批文件的下一道工序交回原作者续用（`send_message`），不另开。细则见 Charter §十一 与运行时手册 §12.4。
+4. 发现缺口时给出方案询问用户；优劣不明时并列全部方案。
+5. 用户确认后执行。
 
-```bash
-dsh plugin --profile web add github:MingMaple/dsh-handover
-```
+子智能体提示词由助手放入规范文件地址与体系说明；插件不向其上下文注入内容。
 
-### 从 npm 安装
+余量不足时先刷新交接，再请求压缩或换任。恢复后按「先读交接、再读计划、后执行」继续。
 
-包名为 `@mingmaple/dsh-handover`，版本与仓库同步：
+### 水位与压缩
 
-```bash
-dsh plugin --profile web add @mingmaple/dsh-handover
-```
+水位 35% 与 50% 时，插件在本会话的工具结果末尾各追加 1 次提醒；不修改系统提示段、不生成用户消息、不独立成轮。
 
-### 从本地源码安装
+35% 档的判断标准：完成剩余流程后，上下文占用不超过 45%；50% 档为不超过 55%。
 
-1. 构建：`node scripts/build.mjs`，产物在 `dist/`。
-2. 用 DSH 的插件管理器安装本地目录 `dist/`，target 传绝对路径。
-3. 在插件列表里启用，重启 DSH。
-4. 首次使用按下一节「首次使用」的引导部署。
+35% 后可压缩；85% 为硬上限。同一会话最多压缩 3 次，第 4 次须换任；额度用尽的判定先于水位。
 
-### 首次使用
+压缩须用户在设置页点击「授权压缩」，单次授权 5 分钟内有效。压缩在回合结束后执行，去向取 `resume`：`continue` 续跑，`wait` 不唤醒。
 
-首次安装后，工作区、文件体系与会话一次部署完成：
+压缩前刷新交接；压缩或换任后按「先读交接、再读计划、后执行」恢复。
 
-1. 打开设置页中的 dsh-handover，在「首次安装」卡片粘贴一个长期存在目录的绝对路径。
-2. 点击「一键部署」。插件在该目录内建立 `_Workspace` 与整套文件结构，注册为「全局」工作区，并新建一个「全局」会话。
-3. 在左侧「全局」工作区打开该会话即可开始。只需先铺文件时点击「仅建立文件体系」，之后再点击「注册为工作区」。
-4. 工作区已接入但还没有全局会话时，设置页会单独出现「全局会话」卡片，可随时补建。
+### 交接与续跑
 
-命令行等价操作：`ho_workspace(action="init", parent="<已存在目录>", register=true)`，再新建一个标题含「全局」的会话。
+交接按角色分开：全局为 `_Control_Center/records/Global_Handover.md`，项目为 `_Project_Meta/<项目名>/Handover.md`，杂项为 `_Misc/tasks/<任务名>/Handover.md`。
 
-## 使用
+全局任务的交接在 `_Control_Center/tasks/<任务名>/Handover.md`，由全局会话以 `ho_handover` 的 `task` 参数读写。
 
-安装后直接说明要做的事，不必记命令：
+写交接按固定流程，4 步不可跳：`ho_handover(action="read")` 读上一份 → `action="archive"` 归档 → 读模板 `_Control_Center/templates/Handover.md` → `action="new"` 新建空白文件写入。`action="write"` 只用于首次创建，文件已存在时直接报错；`action="append"` 只用于中途补一行推进状态。归档文件名为 `<原文件名>_<YYYYMMDD_HHMMSS>.md`，同一秒重复时追加 `-2`。交接不设体积上限：体积由结构控制，只写在途与指针。已完成经过、验证记录与需求全文不进交接，分别写台账、计划或归档。
 
-| 想做什么 | 可以这样说 |
-|---|---|
-| 看整体状态 | 先出一份起始简报 |
-| 查规则 | 把 Charter 第 7.2.3 节取出来 |
-| 交接并压缩 | 先把交接文档写好，再压缩并继续 |
-| 换任 | 写好交接，请用户授权，由本会话自己换任 |
-| 查在任 | 现在全局是谁在任 |
-| 设置角色 | 把 Demo1 设成项目角色，并让它整理自己的文件 |
-| 文档定位 | 把本项目的文档定位写进提示段 |
-| 按规范做事 | 按发布规范进行 |
-| 自检 | 检查插件当前状态 |
+换任由在任会话办理：用户发送 `/allow-succeed` 或点击「授权换任」后，会话调用 `ho_succeed`。插件校验授权与交接结构，建立接任会话并登记在任；任一项不通过则不做任何改动。
 
-### 四类会话
+### 行动计划
 
-| 角色 | 提示段 | 工具数 | 说明 |
-|---|---|---|---|
-| 全局 | 有 | 14 | 协调会话、维护规则与交接 |
-| 项目 | 有 | 11 | 管理单个项目库，自己写骨架档案 |
-| 杂项 | 有 | 10 | 管理单个杂项任务 |
-| 普通 | 无 | 0 | 不注入提示、不加载工具 |
+每个任务根有一份 `PLAN.md`，模板为 `_Control_Center/templates/Plan.skeleton.md`，含目标、步骤、验收、风险与状态 5 节。新建计划前，旧计划移入任务根 `_archive/`，之后不再读取；计划随任务归档。
 
-代理子会话不装配 `ho_` 与 `peer` 工具。宿主逐步解析工具表，子会话在解析阶段即被排除，首轮即不可用。
+### 体系注册
 
-### 交接与压缩
+每个任务一份体系注册：项目写 `_Project_Meta/<项目名>/System.md`，杂项写 `_Misc/tasks/<任务名>/System.md`，全局任务写 `_Control_Center/tasks/<任务名>/System.md`。
 
-| 水位 | 动作 |
-|---|---|
-| 低于 32% | 继续 |
-| 32% 至 35% | 可写交接；处于关键步骤时可暂缓 |
-| 35% 至 85%，已压少于 3 次 | 写交接、原地压缩、读交接续跑 |
-| 85% 及以上，已压少于 3 次 | 强制压缩 |
-| 任意水位，已压满 3 次 | 写交接、建立新会话 |
+全局总注册 `_Control_Center/records/systems.md` 只列各任务体系文件的路径，不承载正文。全局提示段只注入路径清单，项目与杂项提示段注入本任务注册全文。注册写入后立即重装本会话提示段。
 
-压缩次数用尽（默认 3 次）的判定先于水位：额度用尽后，无论水位高低均建议换任；`force` 不能越过额度，`ho_sessions` 的压缩指令（`action="order", order="compact"`）同样会被拒绝。
+`ho_docmap` 提供 read、write、check 与 plan 4 个动作。read 读本会话注册，write 整份替换并逐条校验路径。check 校验路径与缺失注册；plan 读写 `PLAN.md` 并归档旧计划。
 
-压缩须由用户在设置页「授权」卡片点击「授权压缩」，单次授权 5 分钟内有效；`confirm=true` 只表示意图。压缩在回合结束后执行；登记时以 `resume` 选择去向，继续工作时续跑，任务已收尾时不唤醒。全局交接写在 `_Control_Center/records/Global_Handover.md`，项目与杂项交接写在各自目录，每次写入前备份。
+只有本类别在任会话可以写入；全局不代写项目与杂项的注册。全局的 write 按磁盘任务重建总注册。
 
-归档文件名为 `<原文件名>_<YYYYMMDD_HHMMSS>.md`，同一秒重复时追加 `-2`。全局与项目的归档位于 `_Archives/<范围>/Handover/`，杂项归档位于 `_Misc/tasks/<任务>/_archive/`。
+### 全局任务库
 
-换任由在任会话自行办理：写完交接后，由用户在聊天框发送 `/allow-succeed`，或在设置页「授权」卡片点击「授权换任」。授权一次有效，5 分钟内可用，按会话生效。随后会话调用 `ho_succeed`，插件依次校验授权与交接结构，按记录分配下一代编号，建立接任会话并写入角色，登记在任，投递启动提示词，并在旧交接末尾追加换任登记。任何一项校验不通过时，整体不做任何改动，并逐条列出缺项。全局的建会话与换任能力保留，作为自动流程失败时的备选方案。
+全局会话可用 `ho_sessions` 的 task-init 动作，在 `_Control_Center/tasks/<任务名>/` 建立任务库。任务库含交接、体系注册、规则与模板副本，并自动登记进全局总注册。
 
-### 文档定位与授权提示
+任务库可独立为项目或杂项会话：用 new 动作并传 `from_task`。插件先做整库快照，再一并移入并沿用现有体系，不重建、不重新注册；该动作须用户确认后执行。
 
-全局、每个项目、每个杂项任务各可写一份文档定位，放在 `_Control_Center/records/docmap/`，三列为路径、一句话介绍、什么时候该读。写好后注入对应会话的角色提示段：只指路，是否读正文由会话自己判断；空 map 不注入；不设字数上限。
+### 身份互转与名称注册
 
-写入用 `ho_docmap`。写入范围由会话已登记的角色决定，不接受传入项目名；只有对应的在任会话能写，已交出的旧会话只读；全局不代写项目与杂项的 map。写入前逐条校验路径存在，缺项整条拒绝；覆盖前留一份 `.bak`；写盘后当场重装提示段，下一轮即生效。`ho_gate` 会检查 map 里列出的路径是否仍然存在。
+项目与杂项可以互转，用 `ho_sessions` 的 role 动作并传 `migrate`。
 
-用户授权压缩或换任后，目标会话的提示段会在下一轮多一行「用户已授权…至…（一次性，用后失效）」，到期或用掉后消失，无授权不占位。`ho_status(view="phase")` 与 `view="brief"` 的输出里另有「授权」一行，给出剩余分钟与到期时刻。
+缺省 auto：先做整库快照，再移动体系与登记。快照落在 `_Archives/_Global/Backups/身份迁移_<YYYYMMDD_HHMMSS>/`。direct：旧体系移入备份目录，新位置按模板新建体系。
 
-### 通用规范
+项目目标为 `Projects/<项目名>/<项目名>库/`。会话首次用 `ho_office` 的 register 动作注册名称，注册后不得自行修改。名称不超过 40 个字符，不含路径分隔符；已有在任者或同名重复时拒绝注册。改名须由全局处理。
 
-跨会话共用的做法放在 `_Control_Center/standards/`，一条规范一个子目录，目录名即规范名。正文入口为子目录内的 `README.md`；规范自带的脚本与附件放在同一子目录，不混入 `_Control_Center/tools/`。
+### 暂任与协作
 
-用户提到「按某某规范进行」一类要求时，查找范围包括本库与该目录：先看本库有无同名规范，再看规范库；两处都有时按本库那份执行，规范库那份作为通用版本。本库指会话自己所在的工作区。
+暂任规则在任务库 `rules/Delegation_Rules.md`，协作模板在 `_Control_Center/templates/Prompt_Templates.md`。
 
-用户提到「把某某写成规范」时，未指明范围就写本库；说「写入通用规范库」「写成通用规范」「写成共用规范」的才写规范库。规范库由全局会话维护，项目与杂项会话只读；项目与杂项遇到这类要求时，报全局处理。
+交出前刷新交接，提示词写入任务库 `Delegation_Prompt.md`，旧文件移入 `_archive/` 且不再读取；归还时刷新交接并写明暂任者。插件不检查提示词文件是否存在，也不检查是否归档。多会话协作由协调者先 `peer(action="collab", sessions=[…])` 注册，再逐个派任务，用 `peer(action="collect", sessions=[…], timeout_ms=…)` 收结果；谁先完成先返回，同时完成就一起返回。协作期间被交办方不能向交办者或同组成员发明文消息，插件 `peer` 与 DSH 自带 `send_message` 都经守卫拦截；`collect` 取回全部结果后限制自动解除，普通对话不需要注册。`timeout_ms` 按任务预估设置，最低 120 秒。
 
-规范正文只写做法、判据与验收条件，不记某一次作业的进度与结果；进度归交接与台账。目录内仅有 `README.md` 说明时表示尚无共用规范，各库按自己的文档执行。
+### 旧体系迁移
 
-### 工具整合
+0.9.x 的文档定位在 `_Control_Center/records/docmap/`。升级后执行 `ho_workspace` 的 migrate 动作：项目与杂项的条目并入各自体系注册，全局旧内容保留为 `_Control_Center/records/global-docs.md`。
 
-0.9.15 起按「会话一次要做的一件事」合并入口，现有十四个：`ho_status`、`ho_gate`、`ho_sessions`、`ho_charter`、`ho_office`、`ho_docmap`、`ho_handover`、`ho_checkpoint`、`ho_changelog`、`ho_backup`、`ho_workspace`、`ho_profile`、`ho_succeed` 与 `peer`。
+旧目录一并移入 `_Archives/_Global/Backups/1.0-docmap_<YYYYMMDD_HHMMSS>/`，不删除。
 
-原先的 phase、brief、diag、drift、tokens 五个只读入口并入 `ho_status` 的 `view`；快照与迁移包并入 `ho_backup` 的 `action`；首次建立文件体系并入 `ho_workspace` 的 `action="init"`；平级会话的六个入口并入 `peer` 的 `action`。旧入口不再注册，调用会得到未知工具的报错，按本节说明改用新入口。动作级权限未变：`peer` 的 `list`、`peek`、`rename` 仅全局可用，`send` 与 `status` 各角色可用，`new` 仅全局可用、杂项可建到 `_Misc` 下。
+## 安装
 
-### 设置页
+### 从 GitHub 安装
 
-设置页为单页卡片式，常用区直接展开，低频与长文段折叠。未接入工作区时，首次安装卡片置顶出现。删除旧备份须先输入「删除」两字才能解锁按钮；保留旧备份不算待处理，迁移卡片只在待切换、登记未改、链接失效或校验有差异时提示。时间显示为 `YYYY-MM-DD HH:mm` 加本机时区偏移。
+桌面版：在侧栏「插件」中点击「添加插件」，粘贴仓库地址 `https://github.com/MingMaple/dsh-handover`。Web 界面或命令行：
 
-## 迁移与恢复
+```bash
+dsh plugin --profile web add github:MingMaple/dsh-handover
+```
 
-换盘或搬动全局根目录时，按预检、复制并校验、切换、改写登记、清理旧备份五步执行，每一步均可在设置页「移动全局根目录」卡片内完成。切换须在 DSH 完全退出后由后台助手执行，原路径随后成为链接。
+### 从 npm 安装
 
-详见 [迁移全局根目录](docs/migrate.md)。
+包名为 `@mingmaple/dsh-handover`，版本与仓库同步；从本地源码安装先执行 `node scripts/build.mjs`，产物在 `dist/`，用插件管理器安装该目录并重启 DSH。
 
-## 故障处理
+```bash
+dsh plugin --profile web add @mingmaple/dsh-handover
+```
 
-工具数量不符、工作区未接入、设置页刷新失败、压缩未生效、换任未执行、项目名或任务名不合法、新建会话找不到工作区、设置角色后工具未更新、迁移后原路径失效，各有对应处置。
+### 首次使用
 
-详见 [常见故障处理](docs/troubleshoot.md)。
+1. 打开设置页中的 dsh-handover，在「首次安装」卡片粘贴一个长期目录的绝对路径。
+2. 点击「一键部署」。插件在该目录建立 `_Workspace` 与全套结构，注册为全局工作区，并新建全局会话。
+3. 在左侧全局工作区打开该会话。只需先铺文件时，点击「仅建立文件体系」，之后再点击「注册为工作区」。
+4. 已有工作区但还没有全局会话时，设置页单独出现「全局会话」卡片，可随时补建。
 
-## 上下文开销
+命令行等价操作：`ho_workspace(action="init", parent="<全局根上级目录>", register=true)`，再新建一个标题含「全局」的会话。
 
-固定开销为工具 schema 与提示段。按 0.9.17 实测，按角色载入后，全局提示段约 526 加权 token（长路径加迁移提示行约 576），项目与杂项约 514（最坏约 563），随项目名、路径长度与文档定位条数波动；十四个入口的 schema 合计约 1.1 万字符，单条工具描述最宽约 70。以上为实测参考值，不设硬性上限：某条判定需要写清楚时，优先保证表达完整。
+## 使用
 
-## 边界与限制
+安装后直接用中文说明要做的事，不必记命令。
 
-- 依赖 DSH 的 `ctx.compaction` 服务；未挂载时压缩相关工具明确报错。
-- `ptc` 呈现模式下，插件工具只能经程序调用。
-- 会话压力读取依赖宿主保存的会话状态文件布局；字段变化时用 `ho_status(view="diag")` 排查。
-- 迁移只搬文件与清单，不改写文件内容；写死的绝对路径以体检形式报出。
-- 工具可见性按每一步计算：换角色在下一轮请求即生效，不必重启 DSH。插件重载后，已存在的会话沿用旧提示段文本，需要新文本时重启一次。
-- 项目名与任务名按目录名校验：项目名不超过 24 字符，任务名不超过 40 字符；不含 `< > : " / \ | ? *` 与控制字符；不以点或空格结尾；不使用设备保留名。名字来自自由文本时同样校验，不合法则报错且不写入磁盘。
-- 卸载后残留只限 `~/.dsh/storages/dsh-handover.*` 与 `~/.dsh/storages/dsh-handover/logs/`，删除即可清零。
+| 想做什么 | 可以这样说 |
+|---|---|
+| 看总体状态 | 先出一份起始简报 |
+| 查规则 | 取出 Charter 第 7.2.3 节 |
+| 交接并压缩 | 写好交接后压缩并继续 |
+| 换任 | 写好交接，由本会话自行换任 |
+| 查在任 | 现在全局是谁在任 |
+| 设置角色 | 把 Demo1 设为项目角色 |
+| 体系与计划 | 把体系注册写进提示段并建立行动计划 |
+| 暂任交出 | 把本任务交给另一个会话 |
+| 自检 | 检查插件当前状态 |
 
-## 开发与测试
+### 会话角色
 
-```bash
-npm test                              # 开发自测：逐个工具跑只读用例
-npm run test:blank                    # 空白 DSH 验收：临时 HOME 与空目录跑 14 工具及迁移四件
-npm run test:smoke                    # 空白环境冒烟：工具装配、状态路由、浏览器半渲染、语体扫描
-npm run test:migrate                  # 迁移与恢复端到端
-npm run test:docs                     # 文档校验：工具名、旧数、链接、版本、语体与长度上限
-```
+| 角色 | 提示段 | 工具数 | 说明 |
+|---|---|---|---|
+| 全局 | 有 | 14 | 协调会话、维护登记与交接 |
+| 项目 | 有 | 11 | 管理单个项目库 |
+| 杂项 | 有 | 10 | 管理单个杂项任务 |
+| 普通 | 无 | 0 | 不注入提示，不加载工具 |
 
-源码在 `src/`，`dist/` 为构建产物，不入版本库。服务端代码替换 `dist/` 后在插件列表停用再启用即生效，不必重启 DSH；已存在的会话继续使用旧的提示段文本，需要新文本时重启 DSH 或让会话重建。客户端 bundle 不热更新，改设置页必须重建并重启 DSH。
+代理子会话不装配插件工具与 `peer`；子会话在工具表解析阶段即被排除。
 
-## 版本
+### 工具入口
+
+1.0.0 沿用 14 个工具入口，未新增工具。状态与规则入口为 `ho_status`、`ho_gate`、`ho_charter`、`ho_sessions`、`ho_office`、`ho_docmap`。
+
+写入与备份入口为 `ho_handover`、`ho_checkpoint`、`ho_changelog`、`ho_backup`、`ho_workspace`、`ho_profile`、`ho_succeed`；会话通信用 `peer`。
+
+旧工具名不再注册，调用会得到未知工具提示。
+
+### 设置页
+
+设置页为单页卡片式，常用区展开，低频与长文段折叠。卡片含授权、移动全局根目录、会话角色、全局前置提示词与会话水位。另有通用约束条闸门、交接文档体检与插件信息。末尾有默认折叠的「工具明细」与「使用说明」；删除旧备份须先输入「删除」确认。
+
+## 升级与故障处理
+
+升级与搬动全局根目录见 [从 0.9.x 升级到 1.0.0](docs/migrate.md)；常见症状与处置见 [常见故障处理](docs/troubleshoot.md)。
+
+## 写作规范
+
+全部产出按 `_Control_Center/standards/写作规范/README.md` 的 W-01 至 W-42 执行；提示段只放一行指针，不注入规范正文。
+
+## 边界与限制
+
+- 压缩依赖 DSH 的 `ctx.compaction` 服务；未挂载时压缩相关工具报错。
+- `ptc` 呈现模式下，插件工具只能经程序调用。
+- 会话水位依赖宿主保存的会话状态文件布局；字段变化时用 `ho_status(view="diag")` 排查。
+- 项目名不超过 24 个字符，任务名不超过 40 个字符。名字不含路径分隔符与控制字符，不以点或空格结尾，不使用设备保留名。
+- 插件重载后，已存在的会话沿用旧提示段文本；需要新文本时重启 DSH 或新建会话。
+- 服务端是纯 Node ESM，不调用 PowerShell、cmd 或 bash；Windows、macOS 与 Linux 同一套代码。路径大小写按平台处理，7-Zip 缺失时用内置 tar.gz。
+- 卸载后残留仅 `~/.dsh/storages/dsh-handover.*` 与日志目录，删除即可清零。
+- 插件本体不含用户项目、会话或账号数据；用户数据与角色表保存在本机。
 
-当前版本 0.9.22，首次公开版本为 0.9.6。内部版本史不随仓库发布。
+## 开发
 
-支持的内核为 0.2.1-rc.2 至 0.3.0（不含 0.3.0 及其候选版），见 `package.json` 的 `engines.dsh`；0.2.2-rc.1 上的工具装配、角色裁剪与压缩调度已实测通过。
+源码在 `src/`；`dist/` 为构建产物，不入版本库。构建与校验命令见 `package.json` 的 `scripts`。服务端代码替换 `dist/` 后，在插件列表停用再启用即生效。客户端构建产物不热更新，改设置页须重建并重启 DSH。
 
 ## 许可
 
-MIT，见 [LICENSE](LICENSE)。
+MIT，见 [许可证](LICENSE)。

package/docs/migrate.md

@@ -1,61 +1,72 @@
-# 迁移全局根目录
+# 从 0.9.x 升级到 1.0.0
 
-适用场景：把全局根目录换到另一块盘，例如从 D: 换到 E:。全程由 `ho_workspace` 的迁移动作完成，插件不改写文件内容。
+本文说明由 0.9.x 升级到 1.0.0 的步骤。1.0.0 重建了任务流程、体系注册与迁移路径，工具入口仍为 14 个。
 
-## 前提
+升级顺序为：先备份，再安装 1.0.0，补齐文件体系，迁移旧文档定位，最后重载插件并验证。
 
-- 先跑一次完整备份或 `ho_backup(action="snapshot", project="<项目名>")`。
-- 目标父目录可以不存在，插件会自动创建；目标不得在源内部，也不得等于源。
-- 切换必须在 DSH 完全退出后执行：源目录在运行期间被占用，目录改名与建链接都会失败。
+## 备份
 
-## 1. 预检
+1. 完整备份全局根目录，或对每个项目执行 `ho_backup(action="snapshot", project="<项目名>")`。
+2. 记录当前版本与在任会话：`ho_status(view="diag")`。
+3. 确认没有未完成的目录迁移：`ho_workspace(action="move-status")`。
+4. 让正在写文件的作业会话先收束到可暂停位置。
 
-设置页「移动全局根目录」卡片，或：
+## 安装 1.0.0
 
-```text
-ho_workspace(action="move-probe", to="<目标父目录>")
-```
+1. 用插件管理器安装 1.0.0，或替换 `dist/` 后在插件列表停用再启用。
+2. 重启 DeepSeek Harness（DSH）。
+3. 设置页应显示 1.0.0，水位阈值为 35% 与 50%。
 
-核对源总大小、文件数、目标盘可用空间、目标是否为空、是否在源内部。`to` 是父目录，`_Workspace` 会整个搬进去。
+## 补齐文件体系
 
-## 2. 复制并校验
+1. 已接入工作区的，执行 `ho_workspace(action="scaffold")`。
+2. 尚未部署工作区的，在设置页「首次安装」卡片点击「一键部署」或「仅建立文件体系」。
+3. 该动作只新建缺失的目录与文件，不覆盖既有内容。
+4. 新增项包括 `_Control_Center/tasks`、`_Control_Center/records/systems.md`、`Plan.skeleton.md`、`System.skeleton.md` 与 `Delegation_Rules.md`。
 
-```text
-ho_workspace(action="move", to="<目标父目录>")
-```
+## 迁移旧文档定位
 
-复制到新位置，两边各算一遍逐文件 sha256 清单并比对。不一致时不生成切换脚本，报告差异文件。
+1. 检测：`ho_gate` 或 `ho_status` 提示「旧文档定位待迁移」，或 `_Control_Center/records/docmap/` 仍存在。
+2. 执行：`ho_workspace(action="migrate")`。
+3. 结果：`project-<项目名>.md` 与 `misc-<任务名>.md` 的条目并入各自 `System.md`，已有 `System.md` 时保留原文件；`global.md` 保留为 `_Control_Center/records/global-docs.md`，不注入提示段。
+4. 旧目录一并移入 `_Archives/_Global/Backups/1.0-docmap_<YYYYMMDD_HHMMSS>/docmap`，不删除。
+5. 没有旧目录时，动作报告「无需迁移」。
 
-## 3. 切换
+## 重载插件与提示段
 
-```text
-ho_workspace(action="move-switch")
-```
+1. 服务端代码替换后在插件列表停用再启用即生效，不必重启 DSH。
+2. 客户端构建产物不热更新；改设置页后须重建并重启 DSH。
+3. 提示段文本不随插件重载替换；已存在的会话须重启 DSH 或新建会话后才换新。
+4. 需要保留历史的会话，先写交接，再新建会话。
 
-生成并派出后台助手，待插件使用者完全退出 DSH 后自动完成：旧目录改名为 `<旧>.old-<时间戳>`，再在原位置建 junction 指向新位置，并校验指向。日志写在 `~/.dsh/storages/dsh-handover.move.log`。
+## 验证
 
-也可以双击生成的 `dsh-handover.move.cmd`。切换后原路径成为链接，工作区登记、profile 与会话工作目录都无需修改。
+1. `ho_status(view="diag")` 应报版本 1.0.0、14/14 工具与调度器就绪。
+2. `ho_docmap(action="check")` 应报路径全部存在；失效项按输出修正。
+3. `ho_gate` 应无「旧文档定位待迁移」提示。
+4. 设置页水位阈值为 35% 与 50%，不再出现 32%。
+5. 发送一条消息后，提示段应包含两级任务流程与体系注册。
 
-## 4. 改登记（仅在需要时）
+## 行为变化
 
-切换助手完成后，若 DSH 的 `workspace.json` 或聊天集成登记仍写着旧路径，页面会提示。执行：
+- 提醒线由 32% 的单线改为 35% 与 50% 共 2 条一次性提醒，投递方式为在会话的工具结果末尾追加。
+- 文档定位改为体系注册：项目与杂项各一份 `System.md`，全局只列路径。
+- 行动计划固定在任务根 `PLAN.md`；压缩或换任后按先交接、再计划、后执行恢复。
+- 项目与杂项互转默认整库快照后移动，也可选择直接建。
 
-```text
-ho_workspace(action="move-retarget")
-```
+## 搬动全局根目录
 
-只替换 JSON 文本里的路径字符串，结构不动，每份先备份 `.bak-<时间>`。
+1. 预检：`ho_workspace(action="move-probe", to="<目标父目录>")`。
+2. 复制并校验：`ho_workspace(action="move", to="<目标父目录>")`。
+3. 切换：完全退出 DSH 后执行 `ho_workspace(action="move-switch")`；后台助手完成改名并建链接。
+4. 改登记：需要时执行 `ho_workspace(action="move-retarget")`。
+5. 清理旧备份：重启 DSH 并确认新位置可用后执行 `ho_workspace(action="move-cleanup", confirm=true)`；该操作不可撤销。
+6. 链接丢失时执行 `ho_workspace(action="move-repair")`。
+7. 回退：删除链接，把 `.old-<时间戳>` 目录改回原名；登记已改写时再执行一次改登记。
 
-## 5. 清理旧备份
+## 注意事项
 
-确认新位置可正常工作、并已重启 DSH 后，可在设置页「移动全局根目录」卡片里输入「删除」确认，再执行（旧备份保留不影响使用，不必急着删）：
-
-```text
-ho_workspace(action="move-cleanup", confirm=true)
-```
-
-只删匹配 `<旧>.old-` 前缀、且既不是源也不是目标的目录。此操作不可撤销。
-
-## 回退
-
-删除链接，把 `.old-*` 改回原名。若登记已改写，再执行一次改登记指回原路径。
+- 迁移不删除旧文件；旧目录与新位置的备份都保留。
+- 体系注册写入前留 `.bak`；交接写入前自动备份。
+- 角色表与提醒状态保存在 `~/.dsh/storages/`，不随工作区迁移改变。
+- 升级不改变项目与杂项的角色；身份互转须另行执行 `ho_sessions` 的 `role` 动作。

package/docs/releases/0.9.12.md

@@ -4,7 +4,7 @@
 
 ## 新增与调整
 
-- 一键部署：在设置页「首次安装」卡片粘贴绝对路径后点「一键部署」，一次完成三件事：建立 `_Workspace` 与整套文件结构，把该目录注册为「全局」工作区，新建一个「全局」会话并登记全局角色。「全局」会话的产生不再依赖手工新建标题含「全局」的会话。
+- 一键部署：在设置页「首次安装」卡片粘贴绝对路径后点击「一键部署」，一次完成三件事：建立 `_Workspace` 与整套文件结构，把该目录注册为「全局」工作区，新建一个「全局」会话并登记全局角色。「全局」会话的产生不再依赖手工新建标题含「全局」的会话。
 - 补建入口：工作区已接入但还没有全局会话时，设置页单独出现「全局会话」卡片，可随时补建；只建会话，不建体系，不动既有文件。
 - 新建会话必须指明工作区：`ho_sessions(action="new")` 未给 `workspace` 或 `cwd`、或项目没有对应工作区时直接报错，并列出已注册的工作区，不再静默落到调用者所在的工作区。传 `project` 且存在同名工作区时自动匹配；`cwd` 必须是已注册工作区的根。
 - `ho_workspace(action="create")` 新增 `ensure`：目录不存在时自动创建再注册。仍是显式开关，默认不建目录。
@@ -24,5 +24,4 @@
 ## 兼容
 
 - 支持 DSH 内核 0.2.1-rc.2 至 0.3.0，不含 0.3.0 及其候选版，见 `package.json` 的 `engines.dsh`。
-- 已在 DSH NEXT 2.0.22 与内核 0.2.2-rc.1 上实测：设置角色后按轮换装、新建会话的工作区校验与报错清单。
-- 一键部署的建体系、注册工作区与建会话三步，在空白环境验证通过；首次实机安装建议先在空环境验证一次。
+- 首次实机安装建议先在空环境演练一次。

package/docs/releases/0.9.14.md

@@ -1,6 +1,6 @@
 # 0.9.14
 
-修三处与新建会话、换任相关的路径与登记问题，均在真机演练中复现后修复。
+修正三处与新建会话、换任相关的路径与登记问题。
 
 ## 修复
 
@@ -9,10 +9,6 @@
 - 杂项换任：接任会话此前落在工作区根，现落回本会话所在的注册工作区。做法是按会话工作目录反查工作区注册表，反查不到时才退回工作区根。
 - 换任启动提示词里的「全局 id」改为现任全局会话。此前填入的是发起换任的前任会话，项目与杂项的接任者因此被指向已经退休的会话。
 
-## 测试
-
-冒烟新增三条回归断言：新建杂项会话的启动提示读本任务交接、杂项接任者落回本会话所在的工作区、接任提示的全局 id 为现任全局。
-
 ## 升级
 
 先移除旧版本再安装；或替换文件后在插件列表停用再启用。已存在的在任登记表无需改动，工作区一栏在下次登记时自然更新。

package/docs/releases/0.9.22.md

@@ -12,7 +12,7 @@
 - 交接类文档不设体积上限：只判结构与占位符。
 - 通用规范库：`_Control_Center/standards/` 一条规范一个子目录；三档角色段加查找指针；写入分两档（默认写本库，明确「写入通用规范库」一类说法才写共用库）；`ho_workspace(action="scaffold")` 用于补齐既有工作区。
 - 设置页：授权卡改名并按在任会话折叠；「待处理」合并进既有卡片；工具清单独立为默认折叠的「工具明细」；会话水位、通知与交接体检统一以 `_Control_Center/records/Office.json` 的在任为准，普通会话不参与；交接体检只查已登记的项目与杂项，并接受有序列表；会话角色按 DSH 工作区分组、默认折叠、已归档与无目录会话不列；迁移卡片不再把保留的旧备份当作待处理；全页文案与注释改为规范书面语。
-- 使用说明：逐条按实现核对，起始简报、换任入口、压缩去向、打包格式、会话清点输出、自检项与文档定位权限均按当前输出改写。
+- 使用说明：起始简报、换任入口、压缩去向、打包格式、会话清点输出、自检项与文档定位权限按当前输出改写。
 
 ## 会话角色
 

package/docs/releases/1.0.0.md

@@ -0,0 +1,33 @@
+# 1.0.0
+
+**本次修改**：新增 1.0.0 版本说明（首版）。相对 0.9.22，新增两级任务流程与行动计划。同时新增体系注册、全局任务库、身份互转、名称注册、交接固定流程与会话协作。另新增旧体系迁移，路径比较改为按平台处理大小写。
+
+## 新增
+
+- 两级任务流程。层级一为轻量任务，直接执行，不写计划。层级二为繁重任务，先判断纯窗口是否可能超过 40%（不计当前占用）。超过时，写计划即安排拆分子智能体，本会话只做统筹与收尾；未超过时，计划按本会话完成来写。
+- 行动计划。任务根新增 `PLAN.md`；`ho_docmap` 新增 `plan` 动作，用于读写计划与归档旧计划。
+- 体系注册。每任务一份 `System.md`；全局总注册 `_Control_Center/records/systems.md` 只列各任务体系文件的路径。
+- 全局任务库。`ho_sessions` 新增 `task-init`，建立 `_Control_Center/tasks/<任务名>/` 并登记总注册。
+- 全局任务独立。`ho_sessions(action="new")` 新增 `from_task`，把全局任务整体独立为项目或杂项会话。体系与文件一并迁入。
+- 身份互转。项目与杂项互转默认先做整库快照再移动。`migrate="direct"` 只建新体系，不搬旧文件。
+- 名称注册。`ho_office` 新增 `register`；会话首次注册名称，注册后不得自行修改。
+- 交接固定流程。`ho_handover` 新增 `new`：先归档旧交接，再新建空白文件写入；`write` 只用于首次创建。模板 `Handover.template.md` 写明读旧交接、归档、读模板、新建写入 4 步。
+- 全局任务交接。`ho_handover` 新增 `task` 参数，供全局会话读写全局任务交接。
+- 会话协作。`peer` 新增 `wait`、`collect` 与 `collab`，`send` 支持 `wait=true`。协作期间，被交办方不得向交办者或同组成员发送明文消息。插件 `peer` 与 DeepSeek Harness（DSH）的 `send_message` 均经守卫拦截。`collect` 取回全部结果后限制解除。
+- 旧体系迁移。`ho_workspace` 新增 `migrate`，并入体系注册并归档旧目录。
+- 跨平台。路径比较按平台折叠大小写；7-Zip 探测覆盖 Windows、macOS 与 Linux；迁移助手不依赖外部 shell。
+- 模板与规范。新增 `Plan.skeleton.md`、`System.skeleton.md`、`Handover.template.md`、`Delegation_Rules.md`，以及写作规范 W-01 至 W-42 与依据文本。
+
+## 变更
+
+- 提醒线由 32% 单线改为 35% 与 50% 共 2 条。投递方式改为在本会话工具结果末尾追加。
+- 判断标准：35% 档完成剩余流程后不超过 45%，50% 档不超过 55%。
+- `ho_docmap` 的动作由 read、write、check 扩为 read、write、check、plan。
+- 已有交接不得再用 `write` 改写，该动作只用于首次创建。
+- 设置页水位文案改为 35% 与 50%，不再出现 32%。
+- 提示段按 1.0 重写为 6 节。全局、项目与杂项共用同一份流程文本。并加入子智能体判据与续用纪律一行，细则仍在章程与运行时手册。
+
+## 移除
+
+- 移除 32% 提醒线与 `warnRatio` 配置项。
+- 移除文档定位的独立提示段注入路径与简版提示段。流程文本全文进提示段。