KPanel 永久工程规范

September 5, 2026 · View on GitHub

本文件是 KPanel 的长期强制规范。产品设计、实现、测试、发布和代码评审均以此为准； 旧文档、旧实现或历史安全策略与本文件冲突时，以本文件为准。

0. AI-agent-first 工程契约

KPanel 的研发、复核和发布可以由 Codex、Claude 及其他经授权的 AI 智能体协作完成。规范的价值 在于让不同工具中的智能体都能得到同一事实、正确交接和独立复核，而不是增加依赖单个会话记忆的流程。 所有新增或修改的规范必须满足：

  1. 使用可检索的稳定术语，明确目标、允许范围、禁止范围、真实状态来源、失败边界、验收命令、 回滚点和是否授权提交/推送/发布；不得只写原则口号。
  2. 同一门禁只保留一个权威脚本或 Make 入口；AGENTS、工作流和 CI 只引用该入口，不复制参数 不同的平行实现。
  3. 可自动验证的硬规则必须进入测试、静态检查或 CI 阻断；暂时不能自动化的规则必须写明需要 收集的文件、命令和实机证据，不能只依赖“人工注意”。
  4. 日常任务使用变更感知核验，跨权限边界或发布任务才升级到 L2/L3；禁止为形式完整重复全仓 扫描，也禁止用局部测试替代相应等级门禁。
  5. 任一智能体完成任务时必须报告已验证事实、实际修改、验证结果、未验证风险、回滚点，以及是否 发生提交、推送、部署或知识沉淀；不得把计划、推测或工具退出码当作业务成功。
  6. 修改永久规范时同步复核共享文档、AGENTS.md、CLAUDE.md、.codex-workflows/ 和自动门禁， 删除冲突或重复说明，保证不同智能体仅阅读各自项目入口即可正确执行。
  7. 跨智能体任务状态以远端分支/提交、CI 和发布记录为真源；Codex、Claude 或其他工具的本地会话 列表仅用于协调和恢复，不得替代已推送的 Git 检查点。
  8. KPanel 源码远端统一通过 SSH 访问，规范地址为 git@github.com:kejilion/KPanel.git。开发流程不得 把 GitHub App、Issue、PR、REST/GraphQL API 或 gh 登录作为创建 worktree、提交、验证和推送的 前置条件；私钥及本机 core.sshCommand/SSH config 只存在于本机，不得提交到仓库。
  9. 仓库 Bash 门禁统一由 scripts/run-repo-bash.mjs 选择解释器；Make 目标调用该适配器，Windows 没有 Make 时可直接调用同一适配器。Windows 必须使用当前 Git for Windows 自带的 Bash，不得让 PATH 中的 WSL bash.exe 解释 Windows linked worktree；Linux 继续使用系统 Bash。解释器适配只解决路径和环境， 不得改变门禁参数、忽略退出码或修改 Git 元数据。

1. 生态与业务真源

  1. kejilion.sh 是 KPanel 业务行为、资源布局和兼容方式的首要真源。
  2. 脚本可以完成的主机管理功能，KPanel 必须提供等价的 Web 查看、执行和后续管理能力。
  3. kejilion.sh 创建或修改的资源必须能被 KPanel 发现、展示和继续管理；KPanel 创建或修改的 资源必须继续符合 kejilion.sh 的目录、配置、状态标记和生命周期约定。
  4. KPanel 不建立排他的第二套业务状态。Docker Engine、Nginx 配置、系统配置和 kejilion.sh 兼容标记是共享事实；面板持久化只允许保存账户、Session、任务索引、审计和 必要缓存，高权限任务状态由 Agent 在独立目录中有界保存。
  5. 开发新功能前必须先阅读对应的 kejilion.sh 实现，记录输入、产物、状态判断、更新、 删除、失败恢复和发行版差异，再设计 Web 交互。

1.1 外联配置直接复用硬规则

kejilion.sh 已有的外联配置必须直接复用，禁止 KPanel 自行编写替代模板。

“外联配置”包括但不限于网站与反向代理配置、TLS/ACME、Nginx/Caddy/Apache、LDNMP Compose、应用域名与端口、防火墙放行规则、DNS、软件源、对外服务参数及脚本运行时下载的 配置文件。只要 kejilion.sh 已经定义其模板、来源或生成流程，KPanel 就不得根据观察结果 手工翻译、重写或维护一份“近似兼容”的实现。

允许的复用方式只有：

  1. 调用本机可信 kejilion.sh 提供的稳定非交互入口；
  2. 消费脚本使用的同一份模板、URL、版本与校验值，并严格执行脚本定义的参数替换；
  3. 将生成器提取为由 kejilion.sh 和 KPanel 共同调用的单一共享适配器。

KPanel 可以在外层增加结构化输入校验、登录鉴权、原子写入、语法检查、备份、回滚、任务状态 和日志脱敏，但不得改变最终有效配置、默认值、步骤顺序和生命周期语义。脚本尚无稳定机器接口时， 必须先为脚本补充接口；在此之前明确标记“缺少适配器/未实现”，不得用 KPanel 自编模板补位。

所有外联写入必须登记在 docs/external-config-sources.md，记录脚本入口、权威模板或远程来源、 固定版本/摘要、调用方式和双端实机证据。未登记、来源为 KPanel 自身或仅声称“兼容”的实现 不得发布。已存在的自编实现属于冻结迁移债务：不得继续扩展，修改对应文件前必须先迁移到脚本 同源配置并把登记状态改为“已合规”。

1.2 持久化存储选型硬规则

所有持久化设计必须遵守 docs/storage-strategy.md：

  1. 存储服务于产品需求。JSON 用于小型有界状态，JSONL 用于有界追加历史；出现事务、索引、 结构化查询或增长压力时评估 SQLite，不为技术统一强制迁移。
  2. 允许未来部分业务使用 SQLite，但不得改变 Panel/Agent 权限边界，也不得把 Docker、 Nginx、系统文件或 kejilion.sh 产物复制成数据库影子事实。
  3. JSON、JSONL 和数据库都必须有容量、条目、保留期、清理、备份、恢复和损坏处理上限； 禁止无界增长、长期双写和静默双真源。
  4. SQLite 必须使用参数化 SQL、固定 Schema、版本化迁移、最小文件权限、一致性备份和可验证 回滚；数据库、WAL、SHM、备份及驱动供应链均纳入安全与资源验收。
  5. 只有多 Panel 共享写入、主动高可用或多租户控制面有明确需求时，才评估 PostgreSQL。

1.3 产品方案与竞品复核流程

新增或扩展业务能力必须按以下顺序推进：

  1. 先核对 kejilion.sh、KPanel 现有契约和真实资源边界，确认脚本能力是否足以稳定服务面板；
  2. 脚本业务形态不足时，先依据本规范独立形成 KPanel 方案，明确业务真源、结构化接口、交互、 性能预算、安全边界、失败恢复和回滚方式；不得先照搬竞品再反推本项目架构；
  3. 涉及脚本同源业务时，优先补充 kejilion.sh 稳定协议或抽取双端共享适配器；属于 KPanel 原生能力时，可由 Agent 提供固定动作，但仍禁止任意 Shell 和第二套事实来源；
  4. 方案成形后，再使用 1Panel、宝塔等同类产品的当前公开资料和实际体验做竞品复核，形成 功能完整性、易用性、性能、安全、稳定性和资源占用对照；结论必须注明来源、版本或验证日期；
  5. 只有发现可验证差距时才优化原方案；竞品实现不适合 KPanel 定位时记录取舍，不为“看齐” 引入额外常驻服务、无界任务、高风险权限或无关复杂度；
  6. 方案确认后进入开发，按最小可回滚改动完成测试、对应等级验收和独立提交；发布必须继续 通过 L3 门禁、保留回滚点并核对线上产物，不能以竞品已有功能替代本项目验收。

竞品复核用于校验产品下限和发现盲区，不是业务真源。KPanel 对外功能不得低于已确认的核心用户 场景，但“更强”必须体现为可验证的完整性、效率、稳定性或更低资源占用，不以功能数量判断。

1.4 根脚本与中文脚本同步硬规则

修改根目录 kejilion.sh 的业务逻辑、协议、命令、依赖或修复时，必须在同一功能提交中同步 更新 cn/kejilion.sh。两份脚本除区域入口参数外必须保持一致：根脚本使用 canshu="default"，中文脚本使用 canshu="CN"。

发布前必须执行自动差异检查：先统一换行符，再将上述两个 canshu 值归一化后逐字节比较， 并分别执行 Shell 语法及受影响业务 smoke test。任一检查失败时不得固定新脚本提交、构建 KPanel 镜像或发布；禁止通过跳过测试、复制旧版脚本或仅修改其中一份来规避。

1.5 KPanel 与 kejilion.sh 跨仓库发布联动

跨仓库联动的机器真源为 dependency-policy.json#crossRepositoryReleaseLinkage。每个 KPanel 功能任务、候选版本和脚本独立发布任务都必须填写稳定字段 scriptLinkageState，只允许以下三种状态：

  1. not-required（无需发布脚本（不适用））：本次 KPanel 差异不修改，也不要求新的或变更的 脚本协议、运行时动作、宿主机产物、安装/更新/卸载路径、外联配置或镜像内脚本内容；使用已有且 兼容的脚本契约不改变此结论。必须记录候选实际内置脚本的 commit 与 SHA-256，并保留“差异审查 + 兼容性检查”证据；不创建、不发布脚本提交，禁止用“暂不发布脚本”或其他模糊措辞代替该状态。
  2. coupled：KPanel 行为、协议、配置、安装/更新路径或镜像内容需要新的/变更的脚本能力，或 KPanel 主动消费了新的脚本契约。两个仓库必须各自使用专用分支，以同一变更集编号关联，记录双方精确 commit/摘要、根脚本与中文脚本同步检查、脚本 smoke、KPanel 契约测试、兼容矩阵和成对回滚点。 脚本兼容版本必须先可用（或已有可复核的兼容脚本发布），之后才能冻结、发布 KPanel；脚本未 就绪时只能阻断 KPanel 候选或移除依赖范围，不能改标为 not-required，也不能写成“暂不发布”。
  3. script-only：只有 kejilion.sh 仓库发生变化，受支持 KPanel 的既有契约无需修改，且不需要 重建 KPanel 代码、镜像或配置。脚本任务独立完成同步、语法/smoke、兼容性、发布和回滚验收； 不修改 KPanel VERSION，不创建 KPanel tag、Release 或镜像。同一业务变更集需要 KPanel 代码、镜像或安装配置适配时，禁止使用此状态，必须回到 coupled；无关变更集分别判定，不混入本次发布。

状态必须在候选冻结前决定，不能从“没有脚本提交”“尚未发布”或空差异推断；状态缺失、证据不足或 互相矛盾时停止集成和发布。该规则只决定是否需要脚本联动，不要求每次 KPanel 变更都发布脚本； 真正不依赖脚本时，not-required 就是完成结论。自动检测可以提示候选，但不得自动改状态、提交、 推送、打标签、发布或部署。

策略要求显式判定，不提供默认状态。scripts/report-dependency-freshness.mjs --validate-only 检查三态、 必需证据字段和发布边界的策略结构；实际差异是否涉及新契约、兼容证据是否成立，由接手发布任务核实， 不能把策略结构通过解释为某个业务变更集已完成联动验收。发布接管后的责任见 docs/project-management.md 10.1。

2. 不得设置用户操作护栏

已通过身份验证并拥有管理员权限的用户，应能执行底层工具实际支持的操作。以下理由不得用于 隐藏、禁用或拒绝业务功能：

  • 资源不是由 KPanel 创建；
  • 资源没有 KPanel label、marker 或“归属证明”；
  • 用户在脚本、SSH、Compose 或其他工具中修改过资源；
  • 操作具有破坏性、会使面板离线或可能影响现有服务；
  • 配置使用 privileged、host network、额外 capability、设备或宿主机目录；
  • 用户没有输入固定确认词；
  • 资源是 KPanel 自身。

风险操作可以显示明确影响、要求一次普通确认并写入审计，但确认只用于表达用户意图，不能成为 后端能力开关。真实技术前置条件不存在时可以返回“当前主机不支持”，必须说明缺少的命令、服务、 配置或适配器；不得用“为了安全”替代未实现功能。

3. 必须保留的攻击面与完整性防护

移除操作护栏不等于降低防攻击能力。以下控制必须保留：

  • 登录、Session、CSRF/Origin、Agent Unix Socket、最小权限与速率限制；
  • 结构化 API、严格类型和语法校验，禁止把用户输入拼接为宿主机 Shell；登记的 kejilion.sh PTY 和用户明确选择目标容器后发起的有界容器内控制台不属于宿主机 Shell 注入， 但必须分别遵守固定入口、目标身份、输入/输出、超时、鉴权、审计与资源版本边界；
  • 文件根目录约束、防路径穿越、防符号链接替换和可信脚本来源校验；
  • 资源版本冲突检测，避免旧页面覆盖新状态；
  • 原子写入、配置语法检查、备份、失败回滚和可恢复任务状态；
  • 日志和审计中的密钥、Token、密码及环境变量脱敏；
  • 下载、镜像、脚本和更新来源的完整性与供应链校验；
  • 输出、并发、任务时长和存储配额限制，防止拒绝服务；
  • 只有真实状态或底层工具限制动作时才禁用，例如已运行容器不能重复启动。

这些控制防范的是未授权访问、注入、篡改、竞态、泄密和资源耗尽，不得借此重新引入 “KPanel 创建的资源才可管理”一类产品限制。

3.1 产品质量与验收基线

所有新功能和修改必须遵守 docs/development-quality-standard.md。 涉及界面布局、交互、字体、主题、图标、动效或视觉资产时，同时遵守 docs/ui-visual-language.md；该文件是界面视觉与可读性标准的唯一产品入口， 业务设计文档只能扩展具体旅程，不能降低其字号、对比度、缩放、键盘焦点或状态反馈要求。

KPanel 是面向单管理员、直接管理 Linux 宿主机真实资源的轻量控制面，不是普通内容站点或 独立业务数据库。质量判断必须同时服从“kejilion.sh 双向互通、Panel/Agent 权限分离、低配主机 可运行、长任务可恢复、管理员能力不设人为护栏”五项产品前提。

该规范中的安全性专指抵御网络入侵、远程利用、供应链篡改、凭据泄露、容器/宿主机越权和 资源耗尽，不是对已认证管理员增加业务限制。代码评审和发布必须按受影响范围提供：

  1. 业务正确性、真实状态来源、kejilion.sh/Web 双向继续管理证据；
  2. 信任边界、不可信输入、权限、网络暴露和供应链分析；
  3. 请求、响应、并发、缓存、日志、磁盘、CPU 和内存上限及预算对比；
  4. 超时、取消、重试、失败、回滚、重启恢复和兼容窗口；
  5. 桌面/移动端、键盘与焦点、文案与错误反馈、长任务连续性等用户体验证据；
  6. 自动测试、隔离真机、公开产物和生产部署安全核对分别覆盖到哪一层，以及未验证风险。

不得以禁用功能代替防入侵，不得以增加资源配额代替修复无界并发、无界读取或泄漏。 没有受影响的质量维度可标记“不适用”，但必须说明判定依据；不得用“全量测试通过”替代业务、 真机、性能或用户体验结论。

后台浏览器验收：本地或远程长时间浏览器 E2E、跨视口回归和稳定性测试必须作为后台作业运行，使用 .codex-workflows/background-browser-validation.workflow.yaml 和 scripts/background-browser-test.mjs 记录精确候选、环境、job ID、硬超时、资源保护、终态与证据目录；不得依赖前台浏览器标签、交互式 SSH 或单个 AI 会话持续存在。后台化不降低断言或门禁。普通确定性交互按完成条件验收；只有生命周期、 重连、并发、流式或资源趋势风险才执行 soak，时长或循环数由发布画像决定，禁止机械套用固定 10/30 分钟。

本地功能预览：可见功能会话按 docs/local-feature-preview-standard.md 提供统一预览卡和可停止的回环地址。Mock、回环集成和隔离真机必须分层声明；dirty worktree 只能提供 草稿预览，绑定验收证据的预览必须是 clean checkpoint。预览启动成功、截图或 mock 结果不得单独解释为 功能已验收；多会话不得共用固定端口、证据目录或通过停止其他会话进程解决冲突。

3.2 依赖与技术栈生命周期

  1. Go/npm 直接与传递依赖、Go/Node 工具链、Docker 基础镜像与构建 frontend、GitHub Actions、 安全扫描器和受管 kejilion.sh 必须全部进入 dependency-policy.json 覆盖的机器检测范围；发现候选与决定采用是两个状态，缺失检测数据不得解释为“已是最新”。
  2. “最新稳定版”必须是上游未撤回、非 alpha/beta/RC/nightly、仍受维护且适用于 KPanel 支持环境的 正式版本。Node 默认跟踪受支持 LTS；浮动 latest 或分支头只用于发现候选，构建和发布继续固定 精确版本、提交 SHA 或镜像 digest。
  3. 检测自动运行，采用按漏洞可达性、上游维护/EOL、SemVer、行为变化、权限、资源、兼容和回滚难度 分级。兼容补丁默认跟进但仍须受影响验收；次版本批量评估；主版本、工具链、基础镜像、扫描器和 受管脚本必须作为独立 L2/L3 任务，不得为提高“最新率”机械升级。启动、决策和完成处置的最长期限 由 dependency-policy.json#adoptionLifecycle 统一定义；完成处置是采用、以证据拒绝或建立有期限例外， 不能以“条件尚未成熟”无限延期。SemVer 幅度决定处理期限，基座位置决定验收下限；基座 Patch/Minor 使用对应短期限但仍保持独立 L2/L3，不机械拖入 Major 的 90 天窗口。
  4. 暂缓或拒绝候选必须记录当前/候选版本、证据、安全与产品影响、缓解、负责人、复核日期、退出条件 和回滚点；例外到期重新进入队列，禁止以 suppress、删除检测源或固定假结果永久隐藏。
  5. 自动化可以只读检测、生成报告和在已明确授权的专用分支形成候选，但不得自动写 main、发布或 部署生产。永久采用仍服从现有 worktree、L0-L3、独立复核、快进集成和发布单写者规则。
  6. 稳定版本候选每周检测，当前依赖图的安全通告至少每日复核并在依赖相关提交时由主 CI 复核；到期 例外和 EOL 复核期限必须进入同一报告并产生失败信号。自动报告中的“稳定”只表示版本通道稳定， 上游维护、许可证、架构、行为、资源和回滚资格仍由采用任务补齐证据。
  7. 直接依赖和 Go/Node、基础镜像、Action、扫描器、构建 frontend、受管脚本等基座是升级行动项； 传递依赖的跨范围 latest 是归属信号，默认通过拥有它的直接依赖、锁文件刷新或可达安全路径处置， 不为消除候选数量逐项强升。安全漏洞始终服从 docs/development-quality-standard.md 第 11 节 更严格的 24/72 小时时限。

4. 双端互通验收

每项业务功能至少覆盖以下闭环：

  1. 用 kejilion.sh 创建或修改资源，KPanel 无需导入即可发现并管理；
  2. 用 KPanel 创建或修改资源，kejilion.sh 能识别并继续更新、删除或维护；
  3. 任一端修改后，另一端刷新即可显示实际状态，不依赖陈旧面板缓存；
  4. 失败时不得留下错误的已安装标记、半份配置或无法恢复的中间状态；
  5. 日志展示原生任务进度和应用初始信息，但敏感值按明确产品需求显示，审计副本仍须脱敏。

实现状态必须在对应业务对齐文档中逐项标记为“已验证”“已实现未实机验证”或“未实现”， 不得把“只读”当作兼容方案。

5. 核验分级

核验与改动风险匹配，不允许把完整发布验收强加给每个小改动：

等级适用范围必做核验
L0纯文档、文案、注释git diff --check、相关链接/格式检查；用户可见文案还需语言资源检查
L1单个前端页面、局部 Go 包、无部署契约变化受影响类型检查、单元测试和构建；界面变更补受影响视口、键盘/焦点和错误态证据
L2跨前后端契约、Agent 权限、系统/Docker/网站写入、安装脚本L1 + 相关集成测试、Linux 构建、失败注入、回滚/重启恢复和受影响双端互通闭环
L3版本发布、镜像、安装/更新/卸载、生产部署全量测试、全架构构建、镜像契约、安全扫描、公开产物 E2E；按发布画像补受影响性能、真机、体验和回滚验收

日常提交默认运行仓库的变更感知核验；只有 L3 发布才运行完整发布链。发现与改动无关的历史 失败时应记录并隔离，不得重复扫描或阻塞无关小改。

5.1 发布画像、节奏与验收记录

  1. 每个候选冻结前必须记录发布画像：业务域、变更面（展示/只读/写入/协议或数据/部署）、受影响 用户旅程、风险等级、所需证据和不适用维度；发布后使用 docs/release-acceptance-template.md 形成统一验收记录。
  2. KPanel 处于快速迭代阶段，不设置无证据的固定等待天数，也不以发布次数单独判断质量。同一问题的 连续视觉微调、文案或布局修复应优先在一个冻结候选中聚合；安全修复、回滚修复或独立用户价值 可以单独发布，但必须保持范围聚焦。
  3. 危险、付费、耗流量或改变宿主机状态的场景默认在隔离真机验证，不为了“生产全覆盖”主动破坏 生产数据。验证目标必须登记在 environment-policy.json 并通过用途检查；未登记目标默认拒绝。 prod-108（含别名 108）已禁用全部 KPanel 操作。任何任务都不得连接 108 执行测试、只读检查、 候选/功能验收、浏览器 E2E、灰度、备份、部署、升级、回滚演练、健康采样、日志读取或清理，也不存在 稳定版本或临时授权例外。发布验证与唯一正式部署默认均使用 arena-154；迁移到其他主机必须先由 用户明确指定并登记新的非 108 环境。
  4. 至少按滚动 14 天和最近 20 个正式版本分别记录稳定标签形成的正式发布频率、有生产完成证据的 部署频率及覆盖率，并记录提交到生产用时、变更失败/回滚/紧急热修复、恢复时间和重复发布原因； 使必需步骤无效、失败或需要重试的发布基础设施、执行器、验证通道和无效证据另计“发布流程异常”。 首次生产写操作前被拦截的流程异常不计变更失败；生产写操作后若造成服务退化、回滚、紧急热修复 或重复发布，则同时计变更失败和流程异常；产品载荷单独失败只计变更失败。各类数据均不得把缺失 事实推断为零或成功； 数据不足时先建立基线，不得凭主观感受强制降速或放宽门禁。
  5. 候选 CI、主线 CI、Release、公开镜像、生产部署和验收记录是不同证据层；前一层通过不自动证明 后一层成功。未完成的层级必须明确写为未验证，不能用计划或历史版本结果代替。
  6. 生产部署安全核对失败并回滚时保留不可变 tag、Release 和版本镜像作为历史，但回滚任务必须同时 复核并记录 GitHub Latest、Docker latest 和标准更新入口。未通过部署安全核对的版本不得无提示继续作为公共默认 更新通道；只能恢复上一稳定默认版本，或在明确已知问题、影响范围、负责人和修复期限后短期保留。
  7. 流程异常不能只记总数。只要异常计数大于零，验收记录必须按“阶段/权威入口/根因类别”给出稳定的 流程异常指纹、生产写前后位置、影响、恢复证据和永久处置；不得通过改名、合并不同事件或漏记来降低 指标。同一指纹在滚动 5 个正式版本内出现 2 次，视为重复流程缺陷：下一次 L3 生产写操作前必须修复 唯一仓库脚本、Runner、夹具或预检并补回归。确认属于不可控上游瞬时故障时可以建立有期限的例外， 但仍保留原始证据和复核日期，不能降低 fail-closed 门禁。机器只校验计数和必需结构；流程复核者 必须读取原始日志并比较最近 5 个验收记录，不能把格式通过解释为根因和永久处置真实。自 v0.90.2 起，明细使用 kpanel-release-process-incidents:start/end 封闭 JSON 区块；机器必须核对明细次数总和、 生产写后次数总和与两项流程指标一致，旧记录不追溯改写。
  8. 候选冻结后必须同时冻结发布执行方案。首次生产写操作前应在非生产环境核对 SSH 身份、所需运行时、 固定脚本、跨 Shell 参数传递和证据解析；生产写操作开始后不得临时拼接新的多层 PowerShell/SSH/Shell 命令或首次引入未预检工具。若冻结入口不可用，先停止、保持或恢复服务健康，在非生产环境修复唯一 入口并重跑受影响门禁；不把一次成功的现场绕行直接当作永久流程。
  9. 远程 L3 的外层权威入口是 scripts/run-release-l3.mjs，内部质量入口仍是 scripts/run-release-gate.sh / make verify-release。外层入口负责精确 Tag、bundle、固定远端脚本、 不可变 Runner ID、唯一 run ID 和证据终态；不得为单次发布另写 PowerShell/SSH/远端 wrapper。 每次重试必须使用新 run ID 并保留旧证据，不能覆盖失败后将其报告为首轮成功。

5.2 受控自我改进

  1. 规范、门禁和工作流只能由可复核证据触发改进：重复缺陷、滚动指标恶化、验收/CI/生产事件、 证据缺口或反复高成本人工步骤。模型偏好、发布次数、一次偶发失败或测试数量不能单独作为依据。
  2. 改进前使用 docs/quality-improvement-proposal-template.md 记录事实、原因假设、替代解释、基线、目标、防回归指标、最小范围、观察窗口和回滚条件；数据不足时 先建立基线，不把缺失数据推断为成功。
  3. 改进不得自动放宽安全边界、真实资源真源、双端互通、质量阈值或授权边界，也不得为通过门禁而 删除测试、扩大例外、改写历史验收证据或只对固定样例优化。
  4. 永久规范或发布门禁的修改必须由未编写方案的复核者独立读取原始证据，并按正常任务契约、验证等级 和集成权限执行；自我改进流程不自动获得提交、推送、发布或生产权限。
  5. 采纳后在约定窗口以相同环境、样本和参数复测主指标及防回归指标。未达目标或其他质量维度恶化时， 必须继续试行、拒绝或按预定条件回滚，不以“已实施”替代有效性结论。
  6. 永久规范、工作流、CI、环境/依赖策略或治理门禁的提交在获得推送和主线授权后，必须先推送到 docs/、feature/、fix/ 或 release/ 专用候选分支，并等待同一精确 SHA 的 Linux CI 成功； 随后才允许唯一集成任务快进 main。主线 CI 必须对治理路径变更查询并核对该候选证据，缺失、失败、 SHA 不一致或查询不可用时失败关闭。候选分支保留到同一 SHA 的主线 CI 成功；本流程不自动创建产品 Tag、Release、镜像或生产部署。

5.3 规范验收契约 v1.0

本节是永久规范、项目管理文档、工作流、策略文件和治理门禁的唯一验收标准。它只约束“规范如何被 复核”，不替代产品代码的 L0-L3，也不要求普通任务额外创建规范审计文档。

5.3.1 复核开始前冻结验收合同

规范复核必须先记录：精确 Git 基线、允许范围、明确非目标、权威入口、固定验收矩阵、正常执行路径、 证据来源和停止条件。开始后不得为了继续寻找问题而无限扩展输入空间；新增反例只有满足以下任一条件 才进入本轮结论：

  1. 属于冻结矩阵或正常授权路径；
  2. 可在项目支持的环境和默认配置中复现；
  3. 虽在范围外，但会造成安全、权限、数据、生产或发布错误成功的阻断风险。

其他低概率、非标准前置条件或未来优化进入后续事项，不重新推翻已通过范围。修复后只重验受影响项和 预先冻结的回归集；除非精确基线、权威入口或风险边界改变，不重新开启无界全量探索。

5.3.2 六项固定验收维度

维度通过条件
正确性符合 KPanel 产品思想、业务真源、安全边界、用户授权和事实状态
一致性权威规范、管理文档、适配入口、工作流和机器门禁没有相互冲突或第二真源
完整性目标、范围、角色、风险、执行入口、成功/失败条件、证据、权限和回滚足以执行
可执行性硬规则有唯一机器入口；人工判断写明可复核证据，不依赖会话记忆或模型信心
效率与比例性风险越高证据越完整；小改不机械套完整流程，同一证据不重复运行
可演进性变更由真实证据触发，可证伪、可回滚、有观察窗口，不因单个理论反例膨胀规范

5.3.3 严重度和统一结论

严重度必须同时考虑影响、正常路径可达性和发生可能性，不得只因能构造反例就升级：

等级判定处理
阻断正常授权路径或支持环境可达，并可能造成安全、权限、数据、生产、发布错误成功，或使正常任务不可执行修复前结论只能为 FAIL
重要较可能造成多 AI 分歧、证据失真、重复返工或长期错误决策，但当前有明确边界且无阻断影响设负责人/触发条件/期限，可判 PASS WITH FOLLOW-UP
一般低概率、非标准前置条件、局部维护债务或已有防护覆盖的健壮性问题进入待办，不阻断
建议可读性、体验或未来收益优化自愿采纳，不改变结论

规范复核只允许三个最终结论：

  • PASS：固定矩阵完成且没有阻断或重要事项；
  • PASS WITH FOLLOW-UP：没有阻断，重要/一般事项均有明确影响边界和后续条件；
  • FAIL：至少存在一个阻断事项，或固定矩阵/关键证据未完成。

5.3.4 停止条件和交付

当固定矩阵全部完成、证据可复核、阻断项为零、其他事项已分级并记录后续条件时，本轮必须结束。 最终报告只保留：基线与范围、固定矩阵、证据、分级事项、统一结论、停止依据、未验证项和后续事项。 不同审查者对同一事实使用本节同一尺度；若要改变矩阵、严重度或停止条件，必须先说明新证据和范围变化， 不得在修复后追加强度来维持 FAIL。

6. 变更纪律

  • 使用最小、可验证、可回滚的改动，不夹带无关重构。
  • 保留用户已有未提交修改，不覆盖、不清理。
  • 协调中心和写任务在开始写入前使用 scripts/check-collaboration-state.mjs 核对工作树角色。管理工作树 必须位于主工作树、保持 main、clean 且不得包含未进入批准基线的本地提交；失败时只隔离该管理树， 保留现场并从精确 origin/main 创建专用 worktree，不得 reset、stash、清理或覆盖未知改动。写任务 必须位于链接 task worktree 和非 main 分支；启动或验收检查点按需要求 clean。
  • 本地 verify-change 必须在非 CI 环境自动以 --role auto 复核当前工作树：共享多 worktree 仓库的 主工作树按管理角色 fail-closed，链接 worktree 按写角色核对结构，独立验证 clone 不得误判为管理树； 调用方传入精确基线时同时核对祖先关系。自动复核不能替代写入前对任务契约精确基线执行的显式检查， 也不得用浮动 origin/main 误阻断正常长期分支。
  • 所有行为变化补充测试；所有兼容结论注明证据。
  • scripts/check-ecosystem-policy.sh 必须在日常核验和 CI 中执行，防止已删除的来源门槛、 固定确认词、自保护策略和 KPanel 自编外联模板重新进入生产代码。
  • 直接推送是本项目约定的交付方式，不创建 PR。开发检查点先通过 SSH 推送任务分支；经对应等级验证 和用户明确集成授权后，再由唯一集成/发布任务通过 SSH 推送精确提交到 main。GitHub Actions 和 Release 使用仓库内置的临时 Token 属于远端自动化，不作为本地开发凭据；部署和发布仍须执行 L3 验收并保留回滚点。
  • 任何旧文档中的“外部资源只读”“危险配置只读”“系统重装永久锁定”等描述均视为历史设计， 必须在相关功能实现时更新或删除。

6.1 GitHub Release 说明硬规则

  1. 每个发布版本必须在 CHANGELOG.md 中存在与 VERSION 完全一致的版本章节，并至少列出一项 明确的用户可见更新；禁止只使用自动提交列表、镜像摘要或“若干优化”作为发布说明。
  2. GitHub Release 页面必须包含：版本更新内容、升级方式、兼容性或迁移注意事项、发布产物与 完整性校验、测试结论和回滚提示。
  3. 涉及配置、数据格式、端口、权限、kejilion.sh 协议或人工迁移时，必须在对应版本记录中 单独列出升级注意事项；没有额外迁移时也应明确说明保持现有配置和数据。
  4. Release 工作流必须从对应版本的 Changelog 生成说明，并在镜像构建前校验章节和更新条目； 校验失败不得创建或公开 Release。
  5. 发布后必须复核 GitHub Release 页面正文、附件、版本镜像摘要和 latest 指向，验收记录不得 代替面向用户的 Release 更新说明。

7. 多语言界面

界面新增或修改用户可见文案时，必须遵守 docs/internationalization.md：使用稳定资源键，补齐所有已发布语言， 保留命令、路径、协议和第三方原始输出，并通过资源完整性、类型检查和生产构建验证。