KPanel 多智能体项目管理规范

August 29, 2026 · View on GitHub

  • 状态：长期强制规范
  • 版本：2026-08-20
  • 适用范围：KPanel 主仓、关联的 kejilion/sh 与 kejilion/apps 变更、Codex/Claude 等多智能体协作和版本发布
  • 权威关系：工程与产品规则以 PROJECT_RULES.md 为准；本文件负责工作分解、并发隔离、集成和发布治理

0. 规范信息架构

为避免 Codex、Claude 和其他智能体各自维护一套相似但逐渐漂移的流程，项目规范按以下层级组织：

层级权威文件只负责什么不应包含什么
产品与工程不变量PROJECT_RULES.md业务真源、管理员能力、安全边界、质量等级、发布硬规则工具按钮、会话 ID、临时任务状态
多 AI 项目治理本文件角色、任务契约、状态、WIP、worktree、验证、集成、发布和权限Codex/Claude 专属操作
跨工具运行手册docs/multi-agent-collaboration.md人和智能体可直接执行的最短协作步骤、移交与失败处理重复完整工程规则
工具入口AGENTS.md、CLAUDE.md工具启动检查、专属能力和如何进入共享规范平行质量标准或门禁参数
可执行适配.codex-workflows/参数化步骤、预期结果和验证第二套规范、长期状态或会话 ID
证据CI、Release、验收记录、基线报告精确提交/产物在声明环境的验证事实无环境、无提交的“已通过”描述

规则冲突时按表中自上而下的权威关系处理；同一规则只在最高适合层定义，其他文件使用链接引用。 修改共享规范后必须复核入口、工作流和自动门禁是否仍一致，但没有行为变化的文件不为“同步”制造空改动。 界面与视觉语言的产品入口为 docs/ui-visual-language.md；组件或业务设计文档只记录 具体旅程和局部例外，不复制第二套字号、颜色或可访问性门槛。

1. 管理目标

KPanel 允许不同 AI 工具中的分析、开发、验证和发布任务并行，但每项写入必须物理隔离、责任唯一、 状态跨工具可发现、交付可复核。并行的单位不是“会话”，而是下面这条可追踪链：

需求 -> 标准任务契约 -> 独立 worktree/分支 -> 聚焦差异/提交 -> 验证证据 -> SSH 远端检查点 -> 发布候选 -> 版本/回滚点

禁止依赖 Codex/Claude 会话记忆、未提交共享工作区或临时口头约定作为项目状态真源。

2. 跨智能体全局真源

Codex 无法天然读取 Claude 会话，Claude 也无法天然读取 Codex 任务，因此全局控制面必须与模型和工具无关：

优先级真源管理内容
1SSH 远端分支与聚焦提交实际代码、任务 scope、基线、差异、交接状态和可回滚点
2CI/自动门禁可复现验证事实
3tag、Release、镜像和验收记录已发布事实和回滚点
4Codex/Claude 本地任务负责人、允许路径、权限和临时上下文，不是长期全局台账

每个写任务必须有稳定 scope、唯一负责人、专用分支和 worktree。开始写入前在任务上下文中明确允许与 禁止路径、基线提交、验证等级、依赖和提交/推送/发布权限；获得提交授权后，首个可复核检查点形成 聚焦提交，并在获得推送授权后通过 SSH 推送到同名远端分支。跨智能体交接不得只依赖未提交文件或 聊天记忆。

源码远端统一为 git@github.com:kejilion/KPanel.git，Git 数据传输统一使用 SSH。GitHub App、Issue、 PR、REST/GraphQL API 和 gh 登录均为可选辅助能力，不是任务登记、worktree 创建、提交、验证、推送 或交接的前置条件。GitHub Actions/Release 使用仓库内置临时 Token，不能替代本机 SSH 凭据。

3. 角色与唯一职责

角色允许动作禁止动作
协调中心接收需求、盘点远端分支/提交、跨工具路由、控制 WIP、验收、决定进入哪个版本在功能任务工作树里直接开发；代替发布任务推主线
分析任务只读调查、方案、风险和验收设计修改文件、切换他人分支、发布
开发任务在专用 worktree 内实现和测试；获授权时形成聚焦提交修改 main、推标签、部署、操作其他任务工作树
验证任务在干净基线上复核差异、测试和风险未经授权修复代码；把局部测试写成发布通过
集成任务将已验收提交重放到最新集成基线，处理冲突并重验引入未登记提交、从脏工作树集成
发布任务独占候选、L3、主线快进、标签、Release、镜像、生产部署安全核对和回滚接受冻结后的临时功能；与其他任务共用工作树

一个任务可以先后承担多个角色，但同一时刻必须声明当前角色；发布任务在发布窗口内必须保持唯一。

4. 项目和工作树模型

4.1 强制隔离

  1. C:\GitHub\kejilion-panel 是管理工作树，只用于 fetch、状态盘点、只读比较和维护 worktree。
  2. 每个写任务从明确基线创建独立 worktree。默认基线为最新 origin/main；版本候选可使用协调中心指定的集成提交。
  3. 一个 worktree 只绑定一个任务和一个分支；一个分支同时只有一个写任务。
  4. 禁止任何任务在不属于自己的 worktree 中切分支、重置、清理、暂存、提交或删除文件。
  5. 跨仓库功能分别使用各仓库的专用分支，并在交付包中以同一变更集编号关联；不得在共享工作树里混改。

Codex 应将 C:\GitHub\kejilion-panel 注册为独立 Git 项目；Claude 等工具也应把仓库根目录作为项目 根。无论工具是否自动创建隔离环境，协调中心都必须把专用 worktree 的绝对路径和任务分支写入任务契约。

工作树角色使用唯一机器入口核对：

node scripts/check-collaboration-state.mjs --repo C:\GitHub\kejilion-panel --role management --base-ref origin/main
node scripts/check-collaboration-state.mjs --repo <task-worktree> --role writer --base-ref <exact-base> --require-clean

管理角色要求主工作树、main、clean 且本地提交不得领先批准基线；落后远端只报告，因为写任务必须从 精确 origin/main 或指定提交创建。管理检查失败时该工作树进入隔离状态：协调中心可以继续 fetch、 只读盘点和从精确基线创建新 worktree，但不得在其中开发、集成、暂存或提交，也不得 reset、stash、 clean 或覆盖未知改动。写角色必须是链接 task worktree 和非 main 分支；开发中允许 dirty，启动、 交接和验收 checkpoint 才使用 --require-clean。

为避免会话跳过启动检查，本地 make verify-change 在非 CI 环境自动调用 check-collaboration-state.mjs --role auto：共享多 worktree 仓库的主工作树应用管理规则，链接 worktree 应用写角色结构规则，只有一个工作树的独立验证 clone 保持可用；调用 verify-change 时提供精确基线， 才同时核对祖先关系。未提供基线时不以已前移的浮动 origin/main 误阻断长期任务，但这不替代写入前 对任务契约精确基线运行的显式 --role writer 检查。

4.2 命名

对象格式示例
任务标题KPanel · <AI> · <角色> · <领域>KPanel · Claude · 开发 · 历史监控框选
功能分支feature/<scope>feature/monitoring-range-zoom
修复分支fix/<scope>fix/container-cpu-sampling
规范分支docs/<scope>docs/project-management-standard
发布分支release/v<version>-candidaterelease/v0.46.0-candidate
worktreekejilion-panel-<ai>-<scope>kejilion-panel-claude-monitoring-range-zoom

历史分支无需为改名而改名；新任务和重新建立的候选按本表执行。

5. 工作项状态与 WIP

统一状态如下：

待分析 -> 已就绪 -> 执行中 -> 待验证 -> 待集成 -> 候选冻结 -> 产物已发布 -> 生产已部署
             |          |          |          |
             +------ 等待输入 / 阻塞 / 废弃 --+
  • “已就绪”必须满足本文件的 Definition of Ready；目标、范围、基线、权限或验收仍需猜测时保持待分析。
  • “待验证”必须已有聚焦差异和任务级自验；已授权提交时形成聚焦提交，未授权时保留在任务专用 worktree 并明确“本地完成、待提交授权”，不得进入跨智能体交接或集成。
  • “待集成”表示提交已验收，但尚未进入当前发布候选。
  • “候选冻结”后只允许修复候选本身；任何代码变化都生成新候选提交并重跑受影响门禁，L3 结果不得沿用。
  • “产物已发布”表示 tag、Release 和公开镜像成功；没有生产部署授权时停留在该状态，不复用历史现场结果。
  • “生产已部署”表示已授权目标完成备份、标准部署和部署安全核对；它不新增质量验证证据，公开镜像 E2E 也不能替代部署事实。
  • 目标必须登记在 environment-policy.json。prod-108（含别名 108）已禁用全部 KPanel 操作， 测试、只读检查、备份、部署、升级、回滚演练、健康采样、日志读取和清理均不得连接。发布验证与 唯一正式部署默认均使用 arena-154；其他目标必须由用户明确指定并登记，且不得回退到 108。
  • 同时进行的写任务上限为 3，其中发布通道最多 1 个、同一业务领域最多 1 个。只读分析不计入上限。
  • 协调中心通过 git worktree list、SSH 远端分支和提交差集重建全局状态；Codex 或 Claude 会话列表 只用于各自工具内的等待、权限记录和恢复，不维护会话 ID 台账。

6. 任务启动契约

6.1 标准任务契约

每个任务使用同一结构，分析任务可以省略 worktree/分支，写任务不得省略：

任务 scope / 角色 / AI：
目标与用户价值：
允许路径 / 禁止路径 / 共享契约：
业务真源与受影响用户旅程：
worktree / branch / base / rollback：
依赖、相邻任务与冲突面：
风险等级 L0-L3 及理由：
验收命令、实机/浏览器证据、环境 ID、前台/后台执行方式和完成条件：
本地功能预览：不适用 / draft / acceptance；mock / integration / isolated-real-host；入口、旅程、证据目录和停止方式：
权限：修改 / 提交 / SSH 推送 / 更新 main / tag / Release / 部署：
交付物：差异 / 提交 / 报告 / 产物：

写任务开始前必须记录：

  1. 稳定任务 scope、目标、允许范围、禁止范围、交付物和验收等级；
  2. 专用 worktree、分支、基线提交和回滚点；
  3. 计划修改的文件/模块，以及是否跨 KPanel、sh、apps；
  4. 是否允许提交、推送、合并、打标签或部署；未明确授权一律视为不允许；
  5. 当前智能体、相邻活跃任务及可能重叠的文件或契约。

6.2 Definition of Ready

同时满足以下条件才进入“已就绪”：

  1. 用户目标、非目标和可验收结果明确，现有代码/文档不足以直接回答的问题已定位；
  2. 业务真源、对应设计文档和现有实现已确认，不需要靠模型记忆猜测；
  3. 唯一负责人、路径所有权、共享契约和相邻任务冲突已确认；
  4. 写任务有专用 worktree、分支、精确基线和回滚点，工作树状态已记录；
  5. L0-L3、受影响用户旅程、自动/实机/浏览器证据和权限边界明确；远程目标已通过环境用途检查， 长时间浏览器测试已定义后台 job、硬超时、证据目录、资源 watchdog 和接手方式； 有可见界面变化时已按 docs/local-feature-preview-standard.md 选择预览模式和等级，不能提供预览时写明原因；
  6. 缺失用户选择会实质改变方案时已经请求输入；仅是实现细节时由任务作最小合理假设并记录。
  7. 涉及依赖、工具链、基础镜像、Action、扫描器或受管脚本时，已读取 dependency-policy.json 和最近 一次 make dependency-report，明确版本通道候选、检测失败、每日安全审计、EOL/例外期限、采用分类和 是否需要独立 L2/L3。

启动检查至少包含：

git remote get-url origin
git fetch origin --prune
git status --short --branch
git rev-parse --show-toplevel
git rev-parse --short HEAD
git worktree list

随后按当前角色运行 scripts/check-collaboration-state.mjs。任务契约中的 base 必须使用精确提交； 不能在任务执行中把已前移的浮动 origin/main 当作原基线。

git remote get-url origin 必须返回 SSH 地址；不得为绕过认证故障临时改成带 Token 的 HTTPS URL。

若任务契约不完整、worktree 不干净、分支与任务不符、基线不明或与其他任务文件范围重叠，先回到 协调中心处理，不得直接开工。恢复写入前必须重新 fetch 并确认负责人、远端分支和最新提交未变化。

7. 开发、验证与交付包

开发遵守 PROJECT_RULES.md 的 L0-L3 分级和 make verify-change/make verify-release 权威入口。 执行时只走以下最短决策链：

  1. 日常任务只运行 make verify-change；它根据差异选择 Web、Go、部署或治理检查，不再由会话逐条 拼接固定命令；本地执行还会自动拒绝主工作树承担功能写入。
  2. 触及跨端契约、Agent 权限或宿主机写入时显式使用 L2；形成版本、镜像或安装更新时使用 L3。
  3. 只对受影响用户旅程补实机、浏览器、性能和失败恢复证据；未触及的维度写明“不适用”依据。
  4. 只有修改永久规范、工作流、环境/依赖策略或治理入口时才完整运行 scripts/verify-governance.sh；该脚本由 make governance-check 和变更感知入口共同复用，禁止再维护 第三份命令清单。
  5. 上述治理变更通过本地门禁后仍只形成治理候选；获得推送和主线授权时，先推送专用非 main 分支并 等待同一精确 SHA 的 Linux CI 成功，再由唯一集成任务快进 main。scripts/verify-change.sh 在主线 CI 对治理路径自动调用 scripts/check-governance-candidate-ci.mjs；没有候选证据时不得把主线首轮 失败当作候选测试。候选分支在主线 CI 成功前不得删除。

Windows linked worktree 不直接调用 PATH 中含义不明的 bash。Make 可用时，make governance-check、 make verify-change、make verify-l2 和 make verify-release 统一通过 scripts/run-repo-bash.mjs；没有 Make 时直接执行 node scripts/run-repo-bash.mjs scripts/verify-change.sh <exact-base>，L2/Release 通过 --env VERIFY_LEVEL=<level> -- 传入。适配器在 Windows 定位 Git for Windows Bash，Linux 仍使用系统 Bash；失败时先修复解释器入口，不改 .git 指针、不把工作树复制到共享 main，也不把“换 Shell 后 退出 0”解释为门禁已经执行完整。

每项任务向协调中心回传同一结构的交付包：

任务 scope：
AI / 会话角色：
目标：
范围：
worktree / branch / base：
提交：
修改文件：
已验证事实：
验证命令与结果：
质量维度状态：业务 / 安全 / 稳定 / 性能资源 / 用户体验 / 数据迁移：
依赖状态：检测源 / 当前与候选版本 / 采用分类 / 例外期限：
证据层级：自动测试 / 隔离真机 / 公开产物 / 生产部署安全核对：
本地功能预览：状态 / 等级 / 数据模式 / URL / 候选身份 / 体验步骤 / 证据目录 / 停止状态：
未验证风险：
与其他任务的依赖或冲突：
建议进入版本：
回滚方式：
推送/合并/发布状态：

7.1 Definition of Done

任务只有同时满足以下条件才可宣布完成：

  1. 差异只包含任务范围，用户已有改动和其他任务文件保持不变；
  2. 行为变化有回归测试，文档/契约/多语言按影响同步，生成物没有无关变化；
  3. 对应 L0-L3 和受影响用户旅程通过，命令、环境、精确提交/差异和失败项可复核；后台浏览器作业 具有终态、退出码、硬超时、完整断言和清理证据；
  4. 已验证事实、分析结论、建议和未验证风险分开；自动、实机、公开产物和生产部署安全核对不混写；
  5. 已授权提交时形成聚焦提交；未授权时明确保留的专用 worktree 与差异，状态不得写成待集成；
  6. 回滚点和回滚方式明确，所有推送、主线、标签、Release、部署状态如实记录；
  7. 只有具备长期复用价值时才更新共享规范/工作流，且已检查没有重复或冲突。
  8. 依赖类任务已重新生成新鲜度报告；采用、暂缓或拒绝都有证据，锁文件/固定 SHA/digest 可重建， 自动检测、任务分支、主线、Release 和生产状态没有混写。
  9. 已启动的本地预览具有统一预览卡；交付后已停止或明确移交 manifest 和停止责任，没有遗留端口或进程。

7.2 验证证据复用

  • 证据只对“精确提交 + 工具/依赖 + 环境 + 参数”组合有效；候选 HEAD、锁文件、工作流、镜像基础层 或测试环境变化时，相应证据失效。
  • 同一精确提交已有成功 CI 时不在相同环境机械重复全量门禁；协调中心复核差异和关键结果后，只补 本地未覆盖的实机、浏览器、性能或生产证据。
  • 定向测试用于快速反馈，不能替代对应等级门禁；完整门禁也不能替代真实业务产物、用户旅程或回滚。
  • 浏览器长测启动后以前台立即返回为正常；状态真源是后台证据目录，不是会话是否活跃。相同 job 未到终态 不得重复启动，进程消失、超时、资源越线、断言未执行或清理失败均不能复用为成功证据。 权威执行适配为 .codex-workflows/background-browser-validation.workflow.yaml。
  • 与当前差异无关的历史失败记录并隔离，交给独立修复任务；不得反复扫描、顺带修复或伪装为本任务失败。

交付包必须包含本地及远端分支、精确提交哈希和推送状态。协调中心必须读取提交差异并复核关键测试； 不得仅根据任一智能体的最终回复宣布完成。提交信息可追加 AI-Scope: <scope> 和 AI-Agent: <provider> trailer，便于追踪，但作者身份不替代代码评审和验证证据。

获得任务分支推送授权后，使用 SSH 保存可复核检查点：

git push origin HEAD:refs/heads/<task-branch>

只有协调中心已确认精确提交、对应等级验证通过且用户明确授权更新主线时，唯一集成任务才可执行 git push origin <verified-commit>:main。不创建 PR，也不通过插件或 API 代替 Git 推送。

8. 跨智能体交接与评审

跨 Codex/Claude 交接遵循单写者移交：

  1. 原智能体停止写入，形成提交或明确记录未提交文件，不得把模糊工作区直接交给下一方；
  2. 原智能体回传当前提交、远端分支、工作树状态、已完成项、失败命令、风险和建议下一步；
  3. 原负责人明确状态为待复核或阻塞并释放写入声明；
  4. 接手智能体重新 fetch，核对远端分支、提交和差异后再声明接手；
  5. 接手者默认使用新 worktree；除非原工作树已干净且协调中心明确转移所有权，不复用原工作树。

涉及 L2 高风险变更时，优先由不同智能体独立复核；L3 发布必须由与主要实现任务不同的验证/发布任务 检查提交清单、门禁和回滚点。若另一种 AI 暂不可用，使用独立干净会话完成并记录这一限制。

独立复核不以模型品牌判断质量。验证者必须从精确提交重建上下文，优先寻找错误成功判定、权限越界、 真实状态漂移、无界资源、失败恢复、用户旅程和发布范围问题；不得只重复实现者已经报告的命令。

9. 集成队列

  1. 只有状态为“待集成”的聚焦提交可以进入集成队列。
  2. 发布范围用精确提交哈希和依赖顺序表示，不用工作树未提交状态、会话标题或“把最新改动都上”表示。
  3. 集成任务从最新 origin/main 建立干净 worktree，逐项重放批准提交；发生冲突时回到原开发任务修复或由集成任务记录解决，不在共享主工作树试错。
  4. 每加入一项变更就核对 git diff、提交列表和对应测试；全部进入后再执行版本号、Changelog 和 L3。
  5. 候选分支只包含当前版本批准内容；下一版本功能继续开发，但留在自己的分支和 worktree。
  6. 永久规范、CI 和发布工具使用同样的精确提交集成纪律，但属于治理候选而不是产品版本：本地治理 门禁、候选 Linux CI、主线快进和主线 CI 依次完成，不创建版本号、Tag、Release、镜像或生产变更。

10. 发布通道和冻结规则

发布采用单写者模型：同一时刻只有一个发布任务、一个候选 worktree 和一个候选分支。

发布前记录：候选基线、提交清单、发布画像、受影响用户旅程、目标版本、上一稳定标签、生产目标、 备份位置和回滚命令。候选开始 make verify-release 后即冻结：

  • 开发任务不得切换候选 worktree 的分支或修改候选文件；
  • 新需求默认进入下一版本；
  • 候选发现缺陷时，先在独立修复分支形成提交，再由发布任务纳入并从受影响层级重新验证；
  • 推送候选前、快进 main 前、打标签前各执行一次远端基线和提交差集核对；
  • origin/main 前移或候选 HEAD 改变时立即停止，重新构造候选并重验；
  • 候选冻结时同步冻结发布执行方案；生产写前在非生产环境完成 SSH 身份、运行时、固定脚本、跨 Shell 参数和证据解析预检。生产写开始后不临时发明新的多层命令，入口失效时先保持/恢复健康，再回到 非生产环境修复唯一入口并重验；
  • 候选 CI、主线 CI、Release 和公开镜像依次通过后可标记“产物已发布”；只有生产部署已明确授权且 备份、标准部署和部署安全核对完成，才标记“生产已部署”。
  • GitHub Release 公开后，Release workflow 仅在候选分支提交已包含于发布标签时自动删除该候选分支； 失败或发生分叉时保留分支并阻断清理，禁止强删。已合并功能分支在确认提交可由 main、Tag 或本地 bundle 恢复后及时删除，并解除本地 upstream，避免普通推送重新创建。
  • 生产回滚不以单台实例恢复为结束：发布任务必须在同一交付包中记录 GitHub Latest、Docker latest 和标准更新入口的实际指向。未通过生产部署安全核对的版本不得无提示继续成为公共默认更新；历史 tag、Release 和不可变版本镜像继续保留，默认通道恢复或短期例外必须有证据、负责人和结束条件。

发布完成后按 docs/release-acceptance-template.md 记录精确标签/提交、线上版本、镜像摘要、 多维质量与证据层级、交付节奏、上一版本回滚点和未完成项；清理候选资源前确认 功能分支、验收记录和生产备份仍可恢复。

11. 冲突与异常恢复

发现分支被切换、文件被外部修改、HEAD 非预期或 worktree 被占用时：

  1. 立即停止写入、测试和发布，不把未知状态继续向前推进；
  2. 记录 git status --short --branch、git rev-parse HEAD、git reflog -10 和 git worktree list；
  3. 不执行 reset --hard、clean、强制切分支、删除 worktree 或覆盖文件；
  4. 识别改动所有者，将自己的已提交工作从已知提交迁移到新专用 worktree；未提交工作由原任务确认后处理；
  5. 重新核对候选差集并重跑被中断或可能受污染的验证；
  6. 把事件、影响范围和恢复结果连同精确提交回传协调中心。发布候选发生此类事件时，原 L3 结果作废。

12. 决策和权限

动作默认权限
只读分析、创建本地专用 worktree、运行测试允许
修改任务范围内文件用户要求开发/修复时允许
创建聚焦本地提交仅用户已授权提交或任务明确要求形成提交时允许
推送功能/候选分支需要明确授权
快进 main仅唯一集成/发布任务且需要明确主线集成授权
打标签、GitHub Release、镜像发布、生产部署仅唯一发布任务且需要明确上线授权
强制推送、重写共享历史、删除未知改动禁止；除非用户对精确目标另行授权

13. 最小管理节奏

  • 每次新需求：协调中心先 fetch，并盘点远端任务分支、活跃任务和 worktree，再复用或创建任务。
  • 每个开发任务：Definition of Ready 后启动，完成后只回传一个标准交付包；中间只报告关键风险、 范围变化或阻塞，不重复发送无状态进展。
  • 每次版本：先形成精确发布范围，再冻结；远程 L3 统一由 scripts/run-release-l3.mjs 生成自包含 执行包并调用 scripts/run-release-gate.sh，随后进入候选 CI、主线、标签、隔离验收和授权生产部署； 不在会话中重写跨 Shell wrapper，浏览器长测在后台运行，108 禁用全部 KPanel 操作。
  • 每次发布后：整理未上线提交、废弃候选、风险和下一版本队列，更新滚动交付/稳定性数据；不把旧分支 存在等同于未上线功能，也不为同一微调机械拆分多个生产版本。

14. 受控自我改进循环

KPanel 允许智能体持续优化规范、自动门禁和协作流程，但“自我进化”是受控工程变更，不是智能体自行 改写约束。循环统一为：

  1. 观察：从重复缺陷、滚动发布指标、CI/验收缺口、事故逃逸或反复人工步骤收集可复核证据；
  2. 假设：使用 docs/quality-improvement-proposal-template.md 写明根因假设、替代解释、可证伪目标、 防回归指标、最小范围和回滚条件；
  3. 准入：由独立复核者读取原始证据并完成 Definition of Ready，排除指标投机、规则自我弱化和 与产品核心思想冲突的方案；
  4. 试行：在专用 branch/worktree 实施最小可回滚差异，按风险执行 L0-L3 和受影响实机/浏览器验收； 永久治理变更在本地门禁后先通过同一精确 SHA 的候选 Linux CI，再允许快进主线；
  5. 决策：根据相同环境、样本和参数的对比结果选择采纳、继续试行、拒绝或回滚；
  6. 观察窗口：采纳后继续核对复发、误报、人工成本及六维质量，恶化时按预设条件回滚。

状态真源仍是 Git 提案、精确提交、CI 和验收记录；会话记忆、模型信心和内部评分不构成采纳证据。 该循环不能自动降低安全/质量门禁，不能自动提交、推送、发布或操作生产。可复用执行步骤见 .codex-workflows/evolve-kpanel.workflow.yaml，滚动指标统一由 make release-metrics 生成。永久规范、 工作流、策略和治理门禁的采纳结论统一使用 PROJECT_RULES.md 5.3 的规范验收契约；不得由不同会话 临时改变严重度、扩大反例范围或延后停止条件。 验收指标只读取 kpanel-release-metrics:start/end 唯一 marker 之间的六行交付字段，以及 kpanel-release-process-metrics:start/end 唯一 marker 之间的两行流程指标；区块外 Markdown 只服务人工说明，不能提供、覆盖或隐藏机器指标证据。稳定标签形成的正式发布频率与有生产完成证据的 部署频率必须分开报告。首次生产写操作前被拦截的流程异常只计流程指标；生产写操作后若造成服务退化、 回滚、紧急热修复或重复发布，则同时计变更失败与流程异常；产品载荷单独失败只计变更失败。 异常计数大于零时，验收记录还必须给出“阶段/权威入口/根因类别”流程异常指纹、生产写前后位置、 影响、恢复和永久处置。同一指纹在滚动 5 个正式版本内出现 2 次，或生产写后发生本可由预检发现的 本地流程异常，必须在下一次 L3 生产写前修复唯一入口并补回归；不可控上游瞬时故障使用有期限例外， 不得为降低指标漏记或放宽门禁。

14.1 依赖与底层技术栈维护循环

依赖新鲜度采用“自动检测、人工/智能体分级决策、受控实施、按风险验收”的现有任务模型：

  1. 定时 CI 和 make dependency-report 只读取上游稳定来源，输出候选、检测源完整性、行动项/传递依赖 归属信号和采用时限，不写代码；
  2. 协调中心按安全可达性、EOL、补丁/次/主版本、工具链/基础组件和产品收益建立聚焦任务。完整检测首次 确认后，Patch 最晚 7 天启动/14 天决策/30 天完成处置，Minor 为 14/30/60 天，Major 或 digest/pin/ revision 等非 SemVer 基座变化为 30/90/90 天；基座 Patch/Minor 使用较短期限但仍保持 L2/L3 验收， 安全事项服从漏洞响应更严格时限；
  3. 完成处置是采用、以证据拒绝或建立有期限例外。暂缓候选按 dependency-policy.json 建立有负责人、 复核日期、缓解、退出条件和回滚点的例外；重复报告不能重置期限；
  4. 直接依赖和基座作为行动项；传递依赖跨父范围的 latest 由拥有它的直接依赖、锁文件刷新或可达安全 路径处置，不逐项机械强升，也不得从报告中隐藏；
  5. 升级在独立 worktree 实施，补丁按影响 L1/L2，次版本至少 L2，主版本、工具链、基础镜像、Action、 扫描器和受管脚本执行 L2/L3；
  6. 只有门禁和授权满足后才允许任务分支、快进主线、发布或生产进入各自状态；采用后观察失败、资源、 兼容和回滚，结果恶化时回退升级，不降低既有门禁。

可复用步骤见 .codex-workflows/maintain-kpanel-dependencies.workflow.yaml。该流程不是第二套集成或发布 通道，也不要求所有候选立即升级；目标是全量可见、决策有证据、例外有期限、结果可回滚。

可复用执行步骤见：

  • .codex-workflows/session-collaboration.workflow.yaml
  • .codex-workflows/release-kpanel.workflow.yaml
  • .codex-workflows/evolve-kpanel.workflow.yaml
  • .codex-workflows/maintain-kpanel-dependencies.workflow.yaml

跨工具执行说明和交接模板见 docs/multi-agent-collaboration.md。