这是 Codex 迁移版的完整操作指南。原 DSH 的 update-progress-target 由五个 MCP 工具接替；计划保存在本插件项目的 runtime/data，看板读取同一数据。用户的实际请求决定执行范围。
每个 Codex 对话拥有自己的计划。相同项目目录、相同操作系统进程或同一个根会话，都不能作为共享计划的依据。对话恢复后沿用该对话原有计划；分叉后的新对话获得独立身份，默认没有计划。
- 在当前任务自己的命令环境读取
CODEX_THREAD_ID。可运行本插件scripts/current-context.mjs，输出threadId和workspaceRoot。这只是读取当前身份，不是执行用户任务或查询计算资源。 - 每次 MCP 调用都传入这个真实
threadId。不要从工具示例、其他对话、共享 MCP 服务进程的环境、进程号、项目目录或CODEX_SESSION_ID猜测身份。根 session ID 可能被分叉对话共享。 - 先调用
plan_get({threadId, detail:true})。返回plan:null就是当前对话还没有计划，不得改用列表里其他对话的计划。身份无法确认时停止计划读写并说明缺少身份。 plan_create同时写入ownerThreadId并绑定当前计划。读取、更新、删除、看板和导出都检查归属。plan_get的history:true也只返回该对话的历史。- 当前对话已有未收尾计划时修改它，不静默新建并替换。计划最终收尾后，可以在同一对话建立下一份计划，旧计划保持原样并可从本对话历史查看。
这是一组本地计划归属校验，不是操作系统账户之间的权限隔离。工具会验证传入身份和归属；代理必须从当前对话的可信上下文取得身份。
新任务指“在当前对话制定一份计划再执行”时，不调用 Codex create_thread。只有用户明确要求另开 Codex 对话时才使用宿主的新任务功能。
只保留影响决策、最终质量、可用性、安全或真实下游需求的内容。按真实依赖拆阶段，不为了展示进度增加阶段、指标、交付物、证据、资源分支或审计。
SHA、复现说明、manifest、额外报告、消融和反复合理性审计不是默认要求。指标来源与证据达到决策所需程度就停止补充；一个足够好的指标候选即可，不为凑数列备选。不要为使用此插件而扩大简单任务。
读取本指南、已有计划和必要资料，完成与目标相关的指标调研。来源可以是用户的明确要求、现有项目资料、官方文档、文献或已有基线；不能把模板说明当作实际研究。需要外部现行信息时按宿主规则查证。未知事实保持未知。
使用 plan_create 建立 v2 计划：
executionState:"paused"（默认）；每个阶段status:"pending"，不记录startedAt或实际执行成果。- 填写完整
finalObjective、必要的timeline、每阶段deadlineAt、指标、交付物与executionPlan。 - 未测量的
metrics.value使用null。空值不会当作 0，也不会通过任何质量门。 - 暂不执行时，
executionPlan.resourceDiscovery使用{ "deferred": true, "reason": "仅制定计划，执行前查询真实资源", "servers": [] }。预计资源分支只能是planned；不知道实际分配时可暂不列分支。不得伪造查询时间、可用 GPU 或正在运行的资源。 - 只做制定计划所需的资料阅读与身份读取，不启动任务命令、训练、实验、后台进程或资源查询，不占用资源。
完整参数形状见 v2 示例。示例中的身份、目标、阈值、来源、日期都需要替换。指标调研不足以设置正式阈值时，如实说明欠缺的输入；不要为了创建成功编造研究或实验结果。
先读 plan_get({threadId, detail:true})，每次写入都提交最新 expectedRevision。冲突时重新读取，不覆盖新版本。
完整修改用 plan_manage 的 operation:"revise-plan"：可以更新标题、说明和尚未开始阶段的完整契约。传入 timeline 时，它代表修改后要保留的全部 pending 阶段；未传时保持原 pending 阶段。可以更换、添加或精简 pending 阶段的指标和交付物，但仍需满足最低质量与必要交付约束。
执行中的阶段和已结束阶段会自动完整保留，不要把这些阶段放进 revise-plan.timeline。有执行历史时最终目标冻结，不能修改目标让历史结果变成达标。进行中阶段不能回退为 pending；仅修改尚未开始部分，整个计划会保存为 paused。用户实际要求暂停正在运行的作业时，还须用相应作业工具处理，插件状态不会自行终止进程。
修改后所有改动的阶段保持 pending，不启动执行。删除一个原有阶段，即使它尚未开始，也需要本请求或已有会话中的明确删除授权；删除历史阶段使用 delete-phase，整个删除使用 delete-plan。userAuthorized:true 和 reason 是已有授权的记录，不能代替用户授权。没有删除授权时保留阶段，采用必要的修改。
局部改标题、说明、指标值等可用 phase_update；pending 修改不会把 paused 自动变成 active。添加或删除指标、交付物等完整契约变更用 revise-plan。
用户说“按当前计划开始执行”或“继续执行”后：读取当前计划及 revision，按需重新确认已经过期的预计截止时间，然后 plan_manage(operation:"set-execution",state:"active")。不要把仅“查看、制定、修改计划”理解成执行授权。
每阶段开始时重新查询所有已配置服务器，提交真实且新鲜的资源快照和完整执行安排，再使用 phase_update 转为 in-progress。这时不能使用 deferred 记录；即使制定时已查询，启动也要提交更新的快照。资源准备和实际任务执行由代理通过已有工具完成，ProgressTarget 只校验并保存记录。
前序阶段必须合法结束且必需交付物可供下游使用，下游才能开始。开始后不能降低指标阈值或取消必需交付物来绕过验收。需要修正方向时保留历史并制定必要的后续工作。
每阶段的指标 key、交付物 name，以及最终目标中的对应标识必须唯一，去除首尾空白后仍不能重复。最终实测提交也不能为同一指标提交相互矛盾的重复值。required 只接受 true/false；evidence 必须是文字，null、空白或结构化对象不能作为已交付证据。执行后保留原测量单位、方法、指标类型、阈值依据和交付物验收条件，不能改换标准使结果达标。
finalObjective 包含最终目标说明、结构化最终指标和最终交付物。每阶段包含：
metricResearch：需要回答的问题、可追溯来源及发现、候选指标及测量局限、已选指标和选择原因。metrics：至少一个quality或final指标，包含测量方法、局限和thresholdBasis。process指标不能单独作为质量门。质量指标必须来自已选指标，不能全是空洞的“>0/≥0”。thresholdBasis：使用 requirement、literature、historical-baseline、pilot-baseline、expert-judgment 中适用的依据，说明证据和原因。adaptive 质量阈值必须先用已有研究或预实验结果冻结为正式阈值，不能带着未冻结阈值启动正式验收。objectiveContribution：关联已定义的最终指标，解释作用机制、证据等级、验证安排、未满足的风险与不确定性。无充分证据时impactEstimate:null；不能捏造改善幅度。deliverables：只列真实需要的交付物，明确验收条件。必需交付物必须status:"ready"且有非空、能支持该结论的 evidence。
证据等级包括 hypothesis、literature-supported、pilot-supported、validated。对话说明、文件位置、日志或实际测量结果可作与任务匹配的证据，不默认要求另写证据报告。结构校验不能证明外部证据真实；代理必须如实读取和报告。
所有业务时间使用带 +08:00 的 ISO 8601 北京时间，拒绝无时区时间和 Z。保留创建、开始、截止和结束时间。
不存在的日历日期和非 ISO 时间会被拒绝，不自动滚动到下个月；startedAt 不能晚于当前时间。
指标比较支持 >=、>、<=、<、==；质量门要求所有约定指标通过。
pending：尚未开始。in-progress：正在执行。未满足质量、交付或截止要求的更新需记录attempt.summary/findings/adjustment，说明实际结果和下一步调整。completed：已达到指标、必需交付物有证据、且未过 deadlineAt。overdue：已过 deadlineAt，但必需交付物齐备且可用；可以推进下游，必须保留未达质量的事实。
交付物缺失时不能通过 completed 或 overdue 离开阶段。到期仍缺产物，保持进行中，重新估计剩余时间并更新执行安排。修改进行中阶段截止时间需同时提交重规划和调整原因，历史截止时间会保留。
阶段结束率与质量通过率分别展示。全部阶段结束以后，还需实际测量最终指标，并通过 plan_manage(operation:"finalize") 提交最终实测值和交付证据。最终未达标时不能宣称成功；必要时补纠正阶段，合法逾期造成的部分交付则如实记录 shortfall 与原因。
上述最终测量规则适用于 v2。旧 v1 计划继续按原来的指标、交付物与截止时间验收；所有阶段合法结束后调用 finalize 收尾，不要求先升级 v2，也不编造原计划未定义的最终指标。此时 finalAcceptance 保持 null，界面明确说明只是 v1 阶段收尾。
已记录的 v2 最终验收不可重复覆盖。必要时追加后续阶段，原最终验收会保留在 finalAcceptanceHistory，新一轮验收单独记录。不能用一次无后续阶段的 revise-plan 抹掉已完成的验收。
固定资源清单在插件的 local-config.json.requiredServers 中配置。未配置固定服务器时，不凭空增加 GPU 清单；按任务使用本地 CPU 等必要资源。
每次启动或重规划均须查询全部已配置服务器，记录 available/busy/unreachable/unknown、可用 GPU 数及证据。快照不得超过配置的新鲜度窗口（默认 10 分钟），须晚于该阶段上一份快照；下游启动快照还须晚于上一阶段结束时间。保留快照代次和历史。
可分片且多台服务器有可用 GPU 时，执行分支必须覆盖这些服务器，每个分支写明 server 和 shard。不适合分片时说明 shardReason；超过 30 分钟却不能并行时说明 serialReason。可并行的执行安排至少有两个独立分支；仅制定计划的 deferred 占位不要求预先分配实际资源。代理只在任务确有需要且已获授权时使用后台作业或子代理。
初始安排为 5 分钟、50%、75% 检查点，以及 100% 结果收获点。到任何点仍未结束时：读取实际状态、重估剩余时间、重查资源，随后只按新剩余时间设置 50% 检查与 100% 收获；需要时递归重估。禁止另加无依据的高频轮询或固定尝试轮数。
看板的自动刷新只是读取状态，不是执行代理的工作检查；插件不会自行触发计算任务或计时唤醒。
set-execution 支持 active、waiting、paused、blocked。waiting 记录真实等待原因、下一动作和可选 waitingUntil；paused 等待用户明确恢复；blocked 记录真实缺失条件。用户中断与权限、宿主能力及真实阻塞优先。
Hook 适配 SessionStart、Stop、Interrupt：恢复当前对话上下文、检查仍可继续的工作、记录中断暂停。只在取得可靠 threadId 时选择计划，缺失时不猜测。Stop 不会因为 pending 计划未完成就强迫执行 paused 计划，也不以固定重试轮数结束任务。
Interrupt 在写锁内暂停最新状态，保留同时到达的进度写入；重复中断不重复写记录，也不会把刚完成验收的计划重新打开。此逻辑仍以宿主实际触发 Hook 为前提。
Hook 需要宿主加载和信任。独立进程测试验证了输入输出逻辑，尚未完成本机桌面宿主真实事件触发验收；不能把它当作已验证的自动续跑保证。未触发 Hook 时，代理仍须使用当前任务身份和 MCP 明确读写状态。
本插件没有独立后台调度器，也不会绕过宿主限额或在应用关闭后继续运行。用户确实要求定时跟进时，使用宿主提供且符合请求的自动任务能力；仅记录 waitingUntil 不会自动创建它。
调用 plan_open({threadId}) 得到当前对话专属的本地网页链接，包含 thread 参数。可用 Codex 网页面板或系统浏览器查看；页面自动更新，不调用模型。它替代 DSH 的嵌入进度页，不注册任意原生插件标签。
当前入口只显示本对话的计划及历史。未绑定的新对话为空；无身份的服务根地址只显示使用引导；合成演示从显式 ?demo=1 入口查看。复制链接和 JSON 导出保留相同对话范围。看板只读，更新通过 MCP 完成。
页面显示完整计划说明、阶段标签与文字时间安排，区分“逾期执行中”和“逾期交付”，分别展示质量门和只计算必需项的交付物门。旧版单独保存的 harvestAtMinutes 仍显示为收获点。实时连接断开时，每 10 秒进行一次本地只读刷新；这与代理的资源巡检不同，不调用模型或计算资源。
旧 DSH 计划使用 import-plan 建立独立副本，记录来源，不改原文件；默认 paused。已有未完成计划时不自动覆盖绑定。v1 可直接补充原有阶段的指标/交付物、revise-plan 修订 pending 阶段、append-phase 追加必要阶段并按原规则执行，读取和这些操作不会自动升级格式。中文语义阶段 ID 也可保留。
v1 到 v2 使用显式完整 migrate-plan，保留原实测值、阈值、交付记录、实际时间、资源安排、补录和截止时间变更历史；原有指标和交付物不能借迁移移除。失败不落盘。导入、迁移历史资源记录时不追溯要求它包含当前部署新增的服务器，但真正启动或重规划仍必须查询当前完整清单。已结束阶段只能在获得授权后用 audit-phase 补空字段，v2 指标补录保留其 kind、测量方法和阈值依据，不能覆盖原有值。导入 Codex 导出的副本也保留原事件与最终验收历史，副本本身仍先暂停。
首版遗留的无归属计划只有在明确确认归属且已有授权时，才用 bind 认领并记录事件；不能认领其他对话的计划。仅本次迁移验收计划已明确归属回创建它的对话。新任务不自动继承它。
管理操作的精确参数见 管理参考。
显式 v1→v2 迁移后整体暂停，并保留迁移前执行状态和旧收尾事件。已经收尾的 v1 也可以补充 v2 契约，再单独提交真实最终验收。v2 导入保存校验后的契约，同时保留历史时间、实测值和原有检查点。
列表发现损坏的状态文件时会提示可能不完整，并保留原文件；其他可读取计划仍按当前对话展示。直接读取损坏的当前计划会明确报错，不会改选其他对话。