@mingmaple/dsh-handover 0.9.22 → 1.0.0

package/src/templates/Handover.template.md

@@ -0,0 +1,89 @@
+# 交接文档模板
+
+> 本文件是 dsh-handover 随插件发布的交接模板。写交接前先读第 1 节的固定流程，再按第 2 节的总则逐节填写。
+> 本文件只规定写法；各节填写细则见第 3 至第 11 节，写完按第 12 节自检。
+
+## 1 固定流程（强约束）
+
+交接一律重写，不得在旧文件上续写、删改或增行。4 步按顺序执行，不得跳步。
+
+| 步 | 动作 | 命令与判据 |
+|---|---|---|
+| 1 | 读上一份交接 | `ho_handover(action="read")`；文件不存在则跳过第 2 步 |
+| 2 | 归档上一份交接 | `ho_handover(action="archive")`；输出「已归档」且 sha256 一致 |
+| 3 | 读本模板 | 读 `_Control_Center/templates/Handover.md`，读完再动笔 |
+| 4 | 新建空白文件并写入 | `ho_handover(action="new", text=…)`；输出「已归档」「已新建」「体检 通过」 |
+
+禁止事项：
+
+- 不用 `ho_handover(action="write")` 改写已有交接，该动作只用于首次创建。
+- 不用 `ho_handover(action="append")` 追加已完成经过；`append` 只用于会话中途补一行推进状态。
+- 不手工编辑交接文件；不把旧交接的章节搬进新文件。
+- 不跳过归档直接写；旧文件内容只进归档，新交接只写在途。
+
+体积不设上限：不规定字节、行数、页数。体积由结构控制，只写在途与指针；过期内容即删，经历一段时间后按归档重写。
+
+## 2 总则：只写在途
+
+| 应当写 | 不应写 |
+|---|---|
+| 正在做到哪一步、下一步、待用户决定、风险与禁区、关键路径 | 已完成经过、验证记录、需求全文、逐版构建明细、里程碑 |
+| 指向别处的路径（台账、归档、计划、体系注册、规则文件） | 别处已写的内容副本 |
+| 状态用表格或短句，动作写「动作、落点、判据」 | 叙述性过程与理由解释 |
+
+已完成经过写 `_Control_Center/records/Global_Changelog.md`；项目与杂项写本任务台账或提交说明。需求全文写任务根 `PLAN.md` 或任务库文档。旧交接归档到 `_Archives/<范围>/Handover/`；杂项归档在 `_Misc/tasks/<任务>/_archive/`。
+
+## 3 阅读顺序与填写顺序
+
+- 阅读顺序：§0 → §1 → §2 → §4 → §3 → §5 → §6 → §7。
+- 填写顺序：§1 → §2 → §4 → §3 → §5 → §6 → §7 → §0。
+- 交叉引用只指向已填写的小节；回填后复核编号。
+
+## 4 §0 身份与寻址
+
+写明交接双方与按 id 寻址的对象。全局交接必填 7 项：会话类型、本任、链内代数、接任、本文件、冲突以谁为准、修订。
+
+- 「本任」写标题、session id、交接时刻与上下文使用率。
+- 「链内代数」写「第 N 代」，每换一任递增 1。
+- 「修订」只记本次重写改了什么；其他小节不得回写。
+- 不写职责、权限与任务边界，相关内容见章程与规范文件。
+
+## 5 §1 正在做的事
+
+只写状态：已推进至哪一步、尚差哪一步。动作写在 §2，本节不写下一步。存在多个在途事项时，一项一行，标明各自状态。
+
+## 6 §2 下一步
+
+每行一个动作，3 项齐备：动作、落点（文件或命令）、完成判据。按执行顺序排列；判据应可当场验证，不写「继续完善」这类没有终点的条目。
+
+## 7 §3 待用户决定
+
+只列需由用户决定的事项，一项一行，给出选项与建议，并写明该事项阻塞的下一步条目。建议不构成授权，未决定前不得按建议行动。
+
+## 8 §4 用户要求逐条落位
+
+从最近一轮用户消息回溯，只列未闭环的 4 类：待验收、已反馈待处理、未落地、未定。每条带用户原话摘要与落点；已验收只认用户明确表态，沉默不算验收。与 §2 同源的条目写「见 §2-N」，不重复描述动作。
+
+## 9 §5 风险与禁区
+
+- 5.1 风险：一条一行「现象 → 正确做法」，只写本会话遇到或核对过的事项。
+- 5.2 禁区：一条一行「禁止动作 → 原因」，防止接任者出于好意而误操作。
+- 章程或规范文件已载明的内容，只给一行路径，不复制正文。
+
+## 10 §6 关键路径
+
+只写下一步要直接使用的绝对路径与命令，不列目录树与文件清单。每条须在写交接前当场核对；无法核对时注明「未核，待确认」。
+
+## 11 §7 会话 id 对照
+
+全局必填，项目与杂项可删本节。只列在任与仍需联络的会话，不列已交出的；每行必须带 session id。
+
+## 12 写完自检
+
+1. 4 步流程是否照做，旧交接是否已归档。
+2. §1 与 §2 是否一致，是否有已完成经过混入。
+3. 每个下一步是否都有落点与可验证的判据。
+4. §6 的路径与命令是否当场核过。
+5. §0 的代数、修订与本任 id 是否准确。
+6. 通读全文，确认接任者可一次读完。
+7. 体检是否通过：`ho_gate` 或写入回执中的「体检 通过」。

package/src/templates/Plan.skeleton.md

@@ -0,0 +1,34 @@
+# 行动计划（<任务名>）
+
+> 本文件是任务当前唯一的计划，位于任务根 `PLAN.md`。新建计划前将旧计划移入任务根 `_archive/PLAN_<YYYYMMDD_HHMMSS>.md`，归档后不读旧计划。
+
+## 1 目标
+
+<用一句话说明本计划要达成的结果，并写明判定完成的客观依据>
+
+## 2 步骤
+
+| # | 步骤 | 落点 | 完成判据 |
+|---|---|---|---|
+| 1 | <做什么> | `<路径>` | <执行什么、观察到什么可判定完成> |
+| 2 | <做什么> | `<路径>` | <完成判据> |
+
+## 3 验收
+
+- <可机械判定的验收条件一>
+- <可机械判定的验收条件二>
+- 未执行的验证不写入验收结论；区分「已完成待验收」与「要求了未落地」。
+
+## 4 风险
+
+- <风险：已识别的问题与应对>
+- <禁区：本次不得修改的文件或目录>
+
+## 5 状态
+
+| 项 | 值 |
+|---|---|
+| 状态 | <未开始、进行中、暂停、完成> |
+| 最近更新 | <YYYY-MM-DD HH:MM +0800> |
+| 关联交接 | <交接绝对路径> |
+| 关联体系注册 | <System.md 绝对路径> |

package/src/templates/Prompt_Templates.md

@@ -1,6 +1,6 @@
-> **用法**：这是跨会话消息的**唯一来源**，复制后填空即发。**规则**说「何时发」（见 `rules/Handover_Rules.md`、`Migration_Rules.md`），本文件只管「发什么」。行内 `|` 之后是写给人看的提示，**发送前连同竖线一起删掉**。（本行也删）
+> **用法**：本文件是跨会话消息的**唯一来源**，复制后填空即可发送。**规则**说明「何时发送」（见 `rules/Handover_Rules.md`、`Migration_Rules.md`），本文件只规定「发送什么」。行内 `|` 之后为阅读提示，**发送前连同竖线一并删除**。（本行亦删除）
 
-# 会话消息模板
+# 跨会话消息模板
 
 ## 1 共用骨架（所有消息都由它起头）
 
@@ -9,13 +9,13 @@
 第一条要读的：<绝对路径>（读毕再开始作业）。| 项目→ _Project_Meta/<项目名>/Handover.md；全局→ records/Global_Handover.md；杂项首任→ rules/Misc_Task_Standard.md
 不得每轮回执，也不发送「收到」「已完成」一类确认；全局只看文件末态。
 你的 session id：<本会话 id>。确需向全局发消息时，以 `peer`（action="send"）发至 <全局 id>。| 不得据 `peer`（action="list"）推测 id
-水位：≥32% 应先写毕交接、再通知全局，并提醒当前用户换会话；>35% 不得新开任务。
+水位：≥35% 应先写毕交接、再通知全局，并提醒当前用户换会话；≥50% 不再新开任务。
 边界：只读写 <范围>。删除或覆盖前须先留快照，**删除须经当前用户确认**。对用户可见一律中文（含工具 description 字段）。
 时间一律**带时区偏移**书写（如 2026-10-21 07:58 +0800），不写「今天、几点」这种会漂移的说法；本机时区 Asia/Shanghai（+08:00），历史记录里的 +00:00 与新记录按**绝对时刻**比较。
-简单任务直接执行、直接答复；工具正常返回即予采信，不重复核验。子智能体按成本使用：单个子智能体自身亦需十余步，五个约等于另开一整个会话。仅当单块 ≥15 步且可机械验收、或确需隔离时方可派发，并发 ≤3；一文件一派、将机械批处理拆成 N 份均属反模式；可脚本批量并抽样验收者应先写脚本。判断不清者默认自行完成（Charter §十一）。
+简单任务直接执行、直接答复；工具正常返回即予采信，不重复核验。子智能体按成本使用：单个自身亦需十余步、结论还要回读；只在单块 ≥15 步或需读 ≥10 个文件、确需隔离、且结果能机械验收时才派，并发 ≤3；能写成脚本再抽检的先写脚本；同一批文件的下一道工序交回原作者续用（`send_message`），不另开。细则见 Charter §十一。
 ```
 
-> 现行骨架 8 行，是**上限**而不是起点：宜少不宜多，只保留「不写就会做错」的条目。
+> 现行骨架为 8 行，属**上限**而非起点：宜少不宜多，只保留「不写即会做错」的条目。
 
 ## 2 消息一 · 新会话启动
 
@@ -57,7 +57,7 @@
 
 ## 4 消息三 · 全局代建（仅备选）
 
-> 仅在自动换任失败、且用户要求时使用：全局用 `ho_sessions(action="new")` 建接任会话，标题按 `<项目名><N>`（N＝本机下一个序号），启动提示必须带新会话自己的 session id、现任全局 session id 与旧会话 `Handover.md` 的绝对路径。建完请用户在旧会话里确认停止。
+> 仅在自动换任失败且用户要求时使用：全局用 `ho_sessions(action="new")` 建立接任会话，标题按 `<项目名><N>`（N＝本机下一个序号）。启动提示必须带新会话自身的 session id、在任全局 session id 与旧会话 `Handover.md` 的绝对路径。建立后请用户在旧会话中确认停止。
 
 ## 5 消息四 · 全局 → 项目：新任务派发
 
@@ -68,12 +68,12 @@
 约束：<本次不许碰的东西；无则删本行>
 ```
 
-> 派活前先查在任（`ho_office` 空参数，零成本）；复用准则固定写在插件注入的提示段，本节不重复。
+> 派发任务前先查在任（`ho_office` 空参数，零成本）；复用准则固定写入插件注入的提示段，本节不重复。
 
 ## 6 消息五 · 迁移通知（打包前刷交接）
 
 ```text
-【平台迁移通知】当前用户要把整个工作区搬到另一个平台，打包前需要你刷一次交接。
+【平台迁移通知】当前用户要把全部工作区搬到另一个平台，打包前需要你刷一次交接。
 只做三件事，1 分钟内完成；**不要开新任务、不要跑全量自检、不要改库内文件**：
 1) 把 _Project_Meta/<项目名>/Handover.md 的「在途、下一步、关键路径」刷成最新；
 2) 绝对路径改成 <工作区根>/... 的相对写法（新平台的根不同）；
@@ -83,6 +83,87 @@
 
 ## 7 发送纪律
 
-> 汇报时机见插件注入的提示段；格式与频率纪律（不寒暄、一次一件事、并发 ≤3、未被要求勿唤醒、不转述）见 `rules/Workspace_Charter.md` §7.2.4 第 9 条，本节不重复。
+> 汇报时机见插件注入的提示段。格式与频率纪律（不寒暄、一次一件事、并发 ≤3、未被要求勿唤醒、不转述）见 `rules/Workspace_Charter.md` §7.2.4 第 9 条，本节不重复。
 >
-> 本节只留一条**模板自身**的要求：发送前删掉所有 `|` 之后的提示与 `<>` 占位，只留实值。
+> 本节只保留一条**模板自身**的要求：发送前删除所有 `|` 之后的提示与 `<>` 占位，只留实值。
+
+## 8 消息六 · 暂任交出与归还
+
+> 何时暂任、如何交出与归还见 `rules/Delegation_Rules.md`；本节只规定发送内容。暂任提示词写入任务根 `Delegation_Prompt.md`，旧文件移入 `_archive/` 且不再读取；插件不检查该文件是否存在，也不检查是否归档。
+
+### 8.1 交出（可直接复制）
+
+```text
+<骨架（见 §1）>
+你是「<任务名>」的暂任执行会话，由 <交出方名称（session id）> 暂时交出执行权。
+任务库：<任务库绝对路径>；交接：<交接绝对路径>；体系注册：<System.md 绝对路径>；计划：<PLAN.md 绝对路径，无则写「无」>
+暂任提示词：<Delegation_Prompt.md 绝对路径>（读毕再开始作业；与交接冲突时以交接为准）
+写入范围：仅 <任务库路径>，不得写 _Control_Center、其他项目与其他任务。
+可用工具：<ho_handover、ho_status、ho_checkpoint、ho_backup、peer 等>
+本次工序：<范围与步骤>
+验收判据：<跑什么、看到什么即算完成>
+归还：完成或终止后刷新本任务交接，并按 §8.2 回复当前用户，给出可复制文本。
+```
+
+交出完成后，对当前用户的回复中给出可复制文本（代码块内单独一行）：
+
+```text
+请阅读 <Delegation_Prompt.md 绝对路径> 和 <交接绝对路径>
+```
+
+### 8.2 归还（可直接复制）
+
+```text
+【暂任归还】<任务名>｜<类别>
+交接：<交接绝对路径>（已刷新）
+本次范围：<一句话>
+结果：<已完成、部分完成、未开始>
+遗留项：<逐条列出；无则写「无」>
+建议下一步：<逐条列出；无则写「无」>
+身份字段：本次暂任者为 <暂任会话名称>（<session id>）
+```
+
+归还完成后，对当前用户的回复中给出可复制文本（代码块内单独一行）：
+
+```text
+请阅读 <交接绝对路径> 了解当前状态，由暂任归还给在任
+```
+
+### 8.3 纪律
+
+- 交出前刷新交接并用 `ho_gate` 体检；交接不合格不开始暂任。
+- 交出方保持沉默，不每轮询问进度；协同用 `peer`（`action="send"`）。
+- 归还时交接的身份字段填暂任者；旧暂任提示词移入 `_archive/`，此后不读。
+
+## 9 两会话协作与多会话统筹
+
+> 协作指 2 个会话并行推进同一任务的不同部分，与暂任（让出执行权）的分工见 `rules/Delegation_Rules.md` §5。本节提供 2 类可复制骨架。
+
+### 9.1 两会话直接协作（可直接复制）
+
+```text
+【协作】<任务名>｜<我方会话> 与 <对方会话（session id）>
+各自范围：<我方负责 …>；<对方负责 …>
+接口：<交付物、文件名、路径、格式>
+时序：<谁先做、谁等待、何时对齐>
+通信：用 peer（action="send"）直接联系 <对方 session id>；默认沉默，不每轮回执。
+冲突处理：同一文件不同时修改；先改者通知后改者；接口变更须双方确认后执行。
+验收：<合并后的判定方式>
+```
+
+### 9.2 多会话由全局统筹（可直接复制）
+
+```text
+【统筹】<任务名>｜全局 <全局会话名（session id）>
+成员：<会话名（session id）> 负责 <范围>；<会话名（session id）> 负责 <范围>
+阶段：<阶段一；阶段二；收尾>
+约束：同一文件同一时间只由一个会话修改；建会话前先用 ho_office（空参数）查在任，低水位在任直接复用；并发不超过 3。
+进度：各会话只报当前阶段完成与阻塞，不每轮回执；阻塞用 peer（action="send"）报全局。
+收尾：全局核对交接与验收结论，再统一归档。
+```
+
+### 9.3 纪律
+
+- 未被要求不唤醒其他会话；`peer`（`action="send"`）是唯一消耗对方 token 的动作。
+- 跨会话口径只认文件末态：以交接与体系注册为准，不以消息内容为准。
+- 多会话共用同一任务库时，先把范围写进各自交接，避免同时修改同一文件。