用途与实际影响
这项功能怎样使用
为什么需要它
长任务会经历对话压缩、换人接手和外部状态变化；源码、测试、安装、发布、公网与用户结果又各自证明不同事情。只看摘要或一个 PASS，很容易在过期前提上继续忙。
举个实际例子
我可以说：“只检查 Git 总索引，别刷新引用，也别修。”系统只做这项零写诊断，分别告诉我结构是否健康、现在能否收口。换一个问题——“本地构建通过了，为什么公网还打不开？”——它会保留“本地通过”和“公网失败”两个结论，并指出下一步缺哪项回读。
最后我会得到什么
我会看到这次查了哪些真实来源、有没有改动，以及本地、远端和用户结果各自到哪一步。若备份或另一项目资料读不到，就保留那一层未知和下一次核对入口，不拿摘要补空白。
正常时
所需事实来源可读、各层证据一致时，形成一份能继续接手的当前结论。
发现问题时
摘要、源码、运行状态或外部回读冲突时，以现场责任源为准，把冲突层单独列出，只停依赖它的判断。
入口不可用或证据不足时
必要来源读不到时，对应结论标成 Unknown（未验证） 或明确阻断；不恢复退役中央系统，也不从旧摘要猜现状。
从哪里开始
在原 AI 任务中说“接着做”并指出目标，或点名只读诊断的项目与检查范围。
需要准备什么
- 原目标和已完成部分
- 想确认的状态层或项目
- 是否仅检查、不修复
从开始到拿到结果
- 1
恢复本次目标
AI 把原要求、更正、授权、未完成项与旧方案分开，不靠摘要猜当前状态。
- 2
向实际来源求证
按问题查看项目、代码仓库或电脑的当前状态；若要求只检查，就明确是否会刷新远端信息。
- 3
说明能否接续
给出证据日期、完成与未知层；冲突或来源读不到时只暂停依赖它的结论。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
当前 E171 身份与完整发布文件已回读；本次聚焦验证和 E98 历史 38/0 完整回归分层，E171 全量 Local 未重跑关键规则与设计选择
普通单项目问题不进入全景控制面。
跨 Owner（责任源）决策先读 metadata（元数据），再展开必要正文。
证据缺失或过期时降为 Unknown（证据不足），而不是 PASS（通过）。
设计、Git、机器运行和外部 read-back（正式回读）分开验证。
压缩、交接、更正、反复失败或扩架构前恢复原意；有冲突改方案而不改用户要求。
当前 E171 活动身份、聚焦验证与 E98 历史完整回归各自成立；短时通过不能外推长程永不偏离。
本模块用到的名词
- 三控制面
- .agents 管 Agent，Git 控制面管仓库，PCConfig 管机器；具体项目仍独立拥有业务。
- Control Plane Doctor（控制面诊断）
- 选择Owner和检查项后按需调用提供器；默认零写，输出健康和收口两个答案，不是后台门禁或自动修复器。
- Health / convergence（健康 / 收口准备度）
- 前者判断结构与证据合同是否正常，后者判断所选Git目标是否现在能收口；健康警告、退出0都不能把收口阻断升级成通过。
- Durable state（可重建状态）
- 现有状态分开保留用户结果、更正、授权与可换方案；恢复先重锚原意，不保存隐藏推理，也不为此新建台账。
- Evidence layer（证据层）
- 每层只证明自己的事。代码存在不证明安装，部署成功不证明用户路径可用。
- Unknown（未验证）
- 没有当前证据时的诚实状态，不是自动 PASS，也不等于永久不可用。
专业定义
只读取会改变当前判断的上下文，分别回答“系统是否健康”和“Git 现在能否收口”；任务再长也能接着做，各层成果不互相冒充。
解决什么
长任务会压缩，多个 owner 会变化，同一结论又可能来自文档、源码、测试、运行时或外部回执。系统必须让重要状态可重建，同时防止把摘要、历史命名或某一层 PASS 当成全部完成。
当前怎样实现
- 现行只有三个控制面：.agents、Git 总索引和 PCConfig；具体项目拥有业务事实。兼容名称不会创造第四个控制面。本人已冻结的项目，批量“全部完善”也默认不读代码、不主动维护；之后明确提出该项目的具体需求，就只处理这次范围，不需要额外解除口令，也不恢复日常维护。目录、服务或备份仍存在，不等于允许主动改动。
- 上下文按责任来源与DocumentId区分直接资料和按需条件资料；不因返回路径就提前读取所有正文或运行动态Provider。完整发布文件验真与按任务阅读正式主题是两件事，必要原文不足就补条件和例外。
- 具名Skill就绪问题可用Doctor -SkillName，只看该入口supply_health与verification_coverage。源码/安装/事务健康和current（当前状态）/fresh/E2E覆盖分别说明；未知覆盖不把健康供应判坏，也不宣称已可用。普通状态问题不以全仓测试为前提。
- Control Plane Doctor（控制面诊断）是另一条按需聚合入口。-Owner可选agents、git、pcconfig及其组合；默认全选三个Owner以兼容旧调用。-CheckId再收窄为skill_supply、pcconfig_drift、project_admission_agents、project_admission_pcconfig、project_admission_index；未知项或越出Owner范围在接触提供器路径前就拒绝，未选Owner不读不启动。排除pcconfig时，Skill供应使用-NoExternalEvidence避免间接读机器证据。
- Doctor默认-Freshness Cached，Git admission（仓库准入检查）不fetch，返回mode=read_only、write_mode=zero_write。只有明确-Freshness Live且选中Git admission（仓库准入检查）才传-Fetch，可能更新本地.git引用，结果明示mode=read_with_local_git_metadata_write、write_mode=local_git_metadata_write；它仍不改工作树、不安装、不修改任务、不commit或push。
- agents.control-plane-doctor.v1同时返回status（控制面健康）与convergence_status（所选Git目标收口准备度）。schema（数据结构）、身份、路径等结构失败可使health=block；缓存、可见性未知、并发dirty或公开冲突可使health=warn而convergence仍block。非Git提供器convergence_status=not_applicable，进程只在health=block时非零退出，退出0不是收口许可。
- 诊断回执用selected_check_ids、providers_invoked、freshness_mode、write_mode公开实际取证成本；默认每个提供器60秒、stdout/stderr合计262144字节上限，无窗口运行，超时、过量输出、无效UTF-8/JSON或合同不符都返回明确错误，不把原始私有载荷转发给页面。
- 长任务在现有项目或宿主持久状态中分开保存用户结果、更正、授权、可推翻方案、已完成和剩余结果；计划、摘要、代码与审查不能成为新需求。简单工作不建文档，也不为重建状态增加台账、服务或数据库。
- 证据层包括合同设计、源码、测试、安装、运行、发布、fresh task（全新任务验证）、E2E（端到端验证） 和用户可见结果，互不冒充。
- 仓库膨胀治理把完成计划和历史复盘留给 Git，活动树只保留当前 source（源码）、contract（合同）、config（配置）和行为回归。backup_source_follow_deletion（备份跟随有效保留集）由活动三控制面合同定义：受管 G 备份跟随登记上游，H 跟随 G，新增、修改、删除都收敛到当前有效保留集；源根正常可读且没有已知归位解释时，已消失项按本人删除处理，不逐件追问或从下游复活。卷离线、锁定、读取失败或备份不完整不能当空源；完整读清保留视图并复制核验新增/修改后，才清理旧副本，纯删除也要收敛。必要的有界版本和短期删除缓冲仍由所属入口保留；不盲镜像整盘、不误删独立原件、不新增服务或自动锁盘。PCConfig 拥有机器映射、任务配置、卷锁和恢复路由，各上游拥有保留视图；本次网页规则取证没有执行 G/H 同步或验证所有链路。
执行流程
- 1
判断跨控制面事实是否真的会改变当前决定
- 2
先选择会改变决定的Owner或DocumentId；主选和条件文档分开，条件项不预读正文或哈希
- 3
分别调用 Git、机器或业务 provider 取得动态事实
- 4
只需健康/漂移诊断时先冻结Owner和CheckId范围，用默认Cached零写入口；分别读取status与convergence_status。确需现场refs且允许本地Git元数据写入时才显式选择Live，修复则退出Doctor交回真实Owner
- 5
将每个结论标记为活动事实、设计原则或解释示例
- 6
按证据层记录 PASS、FAIL、BLOCK、SKIP 或 unknown（未验证）
- 7
压缩、交接、更正、失败循环或扩架构前先恢复原意，再读必要规则、Owner、工作树和证据；长程实质重规划按活动合同安排独立审查
边界
- 普通单项目问题不机械进入三控制面全景
- Doctor默认不fetch；显式Live可能写本地Git引用，必须明示，不能继续称zero_write
- Doctor不修复、安装junction（目录联接）、修改工作树或计划任务，也不commit/push；需要修复时使用所属项目的独立授权流程
- 兼容 ID 不会恢复已退役的第四基座或中央个人上下文
- checkpoint（续作检查点） 不保存秘密、隐藏推理和无关私人内容
- 测试、receipt（执行回执） 和状态字段不能代替用户看得见的产品验收；短时 E2E（端到端验证） 不能证明长程永不偏离原意
失败与恢复
- Doctor的Owner/CheckId无效或检查项超出所选Owner
- 在任何提供器路径读取或进程启动前拒绝；缩小到正确范围，不自动补成全量检查。
- 健康为warn但Git收口为block
- 保留两个结论及精确原因；补所需现场证据或处理对应冲突，不把诊断退出0当作可以发布。
- 诊断提供器缺失、超时、输出越界或合同无效
- 标记受影响提供器与健康阻断，不修复或扩大读取范围；真实Owner修复后仅重验必要项。
- 视图 owner 或 primary 缺失
- 失败关闭跨控制面结论，修复正确 owner 的 catalog（目录） 或路径。
- 摘要、计划或当前方案与用户原意冲突
- 恢复用户目标、更正及授权，修正方案而不是用户要求；必要动态事实仍向规则、Git、机器或业务 Owner 回读。
- 证据过期
- 降为历史或 unknown（未验证），重新执行最小必要 read-back（正式回读）。
真实入口
E:\.agents\docs\contracts\agents.context-sources.md三控制面架构和渐进上下文合同
E:\.agents\tools\Get-FourBaseDecisionContext.ps1零正文 metadata（元数据） 视图入口
E:\.agents\tools\Invoke-ControlPlaneDoctor.ps1Owner/CheckId前置选择、默认零写、有界调用与健康/收口双结论
E:\.agents\tests\Test-ControlPlaneDoctorScope.ps1未选Owner零调用、CheckId范围、Cached/Live写入语义与双结论回归
E:\.agents\config\repository-bloat-budget.json活动树大小、历史路径和例外退出条件
如何验证
- FourBaseDecisionContext 保留兼容视图，按 Owner/DocumentId 区分主选与条件文档；只为选中 E 文档 Resolve，条件项不预读正文或哈希
- 2026-09-02T19:55:45Z 真实只读运行Doctor -Owner git -CheckId project_admission_index：仅调用该1项，freshness（证据新鲜度）=cached、write_mode=zero_write、health=warn、convergence=warn，原因cached_observation；没有运行Live或修复。Test-ControlPlaneDoctorScope另有health=warn/convergence=block与未选Owner零调用的隔离回归，本次未重跑该测试。
- E118 延续当前仓库验证边界；跨控制面上下文按所选文档渐进读取，条件项不预读。安装 state 与 source_current 分开；源码候选变化不让已验证安装失效，Unknown（未验证） 也不等于历史从未验收。命令层拒绝删除的回收站后备仍只覆盖已授权精确目标。
- Cross-control coverage（跨控制面覆盖）在项目当前快照中闭合且无 finding；以后新增合同仍必须单独回归
- refresh snapshot 没有重跑当前 source 的 full Local 回归；验证矩阵中的完整 38/0 仍只属于 E98 历史观察。当前 E171 由完整发布文件 release identity、source/remote（远端仓库） 与正式 pointer 回读证明，二者不能互相替代。
与其他模块的关系
这个模块把其他模块的结论放进正确证据层，并保证长任务和更新快照时不会靠记忆续写；工作树镜像的文件恢复生命周期由独立模块说明。