From ee28c0968f9f43ed291f29233726098e533216b7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=A7=9A=E7=AB=A0=E6=B5=A9?= <zheromiku@example.com>
Date: Mon, 12 Oct 2026 00:12:06 +0800
Subject: [PATCH] =?UTF-8?q?docs(architecture):=20=E8=90=BD=E5=BA=93?=
 =?UTF-8?q?=E4=B8=A4=E4=BB=BD=E8=AE=BE=E8=AE=A1=E8=8D=89=E6=A1=88=EF=BC=8C?=
 =?UTF-8?q?=E5=B9=B6=E6=A0=87=E6=B3=A8=E5=AE=83=E4=BB=AC=E6=98=AF=E8=BF=87?=
 =?UTF-8?q?=E7=A8=8B=E8=AE=B0=E5=BD=95=E8=80=8C=E4=B8=8D=E6=98=AF=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

两份草案此前只在本机工作副本里（未跟踪），而它们是这次改动的依据来源，
不留档就没法回头看"当初为什么这么定"。

同时在文头各加一行后续说明：已落地生效的部分已经并入 01 正本
（§3.1 测试语义、§4.1 CI/CD 分离、§4.8 必需检查清单与结果口径、§8 占位不许假报成功）
与 templates/；试点那份标注"已实施"，并指向 knowledge-governance 的
scripts/ci_checks.py 与 .gitea/workflows/build.yml。

为什么必须标清楚：草案里写着"当前仅文档设计、不修改工作流"，
而现在已经改了 —— 一份自称"尚未生效"的文档会让人以为规则还没落地。

验证：README 的交付物表已列上 docs/architecture/ 并写明"规则以 01 为准"。
---
 .../knowledge-governance-ci-pilot.md          |  76 ++++++++
 docs/architecture/universal-ci-standard.md    | 168 ++++++++++++++++++
 2 files changed, 244 insertions(+)
 create mode 100644 docs/architecture/knowledge-governance-ci-pilot.md
 create mode 100644 docs/architecture/universal-ci-standard.md

diff --git a/docs/architecture/knowledge-governance-ci-pilot.md b/docs/architecture/knowledge-governance-ci-pilot.md
new file mode 100644
index 0000000..9fe794b
--- /dev/null
+++ b/docs/architecture/knowledge-governance-ci-pilot.md
@@ -0,0 +1,76 @@
+# 知识治理平台：通用 CI 首期试点交接草案
+
+## 1. 背景和目标
+
+使用 universal-ci-standard.md 的通用流程验证 Go + React/TypeScript 项目；项目为 Weknora/knowledge-governance。状态：仅交接文档，未修改工作流、未启动开发、未在远端创建 Issue。
+后续：试点**已实施**（见 knowledge-governance 仓的 `scripts/ci_checks.py` + `.gitea/workflows/build.yml`，14 项必需检查、`make verify` 唯一入口、只做 CI）。本文保留为交接记录；规则以 01 正本为准。
+
+基于此前读取的 main 页面 5f3a71cade 和既有运行 /actions/runs/38。运行显示成功不代表新增检查已经执行；实现前重新核实仓库完整 SHA、实际工具与测试条件。
+
+## 2. 约束条件
+
+沿用现有 Runner，不修改 docker.sock、标签、缓存挂载或分支保护。不进入 CD，不启动真实来源扫描/发布 Worker，不连接生产库，不使用生产密钥。main 是唯一长期分支；仅需要审批或试验时使用短命 PR。
+
+## 3. 系统边界
+
+通用规范负责质量契约，项目负责实际 Go/Web/版本检查，现有 bridge 可选负责报告与预览。无业务 API、数据库和页面改版；无需 prototype。
+
+## 4. 模块与首期检查矩阵
+
+| 模块 | 已有入口/事实 | 实现时要求 |
+|---|---|---|
+| 提交与身份 | .gitea/scripts/ci_gate.py | 检查本次范围；固定事件完整 SHA，不使用随时间变化的分支 HEAD |
+| 工具链 | go.mod 声明 go 1.26.0；README 要求 Node 22 | 先实测现有版本，选择兼容精确版本，不擅自升级 Runner |
+| Go 依赖 | go.mod、go.sum | 安装后只读解析，断言文件无漂移；禁止 -mod=mod 静默更新 |
+| Web 依赖 | web/package.json | 核实 package-lock.json；必须 npm ci，无锁失败 |
+| Go 格式 | 待加显式门禁 | gofmt -l 非空必须非零，不将列出文件当通过 |
+| 前端格式/Lint | package.json 尚无独立工具脚本 | 推荐 Prettier 检查 + ESLint（含 TypeScript/React 适用规则）；锁定工具，先评估存量差异 |
+| Go 静态 | make vet | go vet ./... |
+| Web 类型 | make web-typecheck | npm --prefix web run typecheck |
+| Go 测试 | make test | go test ./...；审核数据库依赖/skip，不能连接生产 |
+| Web 测试 | make web-test | npm --prefix web test；必须加入 CI，不允许空套件成功 |
+| 构建 | make build、make web-build | 使用版本注入入口，不以普通 go build 替代实际产物契约 |
+| 版本 | make changelog-check、make version-contract | 明确 CHANGELOG 为项目唯一来源，契约不得 SKIP 后算通过 |
+| 安全 | 现有工作流未列门禁 | 推荐受控 Gitleaks + govulncheck + npm audit；核实安装/网络/分级，未运行不算安全 |
+| 汇总/预览 | ci_report.py、build.yml | 汇总全部必需项；预览等全部成功；通知不改质量结果 |
+
+统一入口：优先保留现有 make verify，并使其严格串行、失败即停，所有文档与 CI 对齐；不是硬改成 make check。依赖安装与提交范围作为明确外围步骤，不在本地/CI复制独立质量逻辑。
+
+推荐一个质量作业内顺序执行，以避免现有 /tmp 状态跨作业传递错误；未来拆分作业需明确输出/制品传递，不以 /tmp 共享为契约。
+
+## 5. 数据模型草案
+
+复用通用报告：完整 commit_sha、run_id、policy_revision、checks[]、overall_status、notification_status；checks 至少包括上表必需项。版本失败必须使 overall_status 非成功。无需数据库新表。
+
+## 6. API 草案
+
+无新增业务 API。项目产出检查报告，回写 Gitea；现有 POST /api/ci/report 和 /api/ci/publish 保持兼容，升级报告字段前核实 bridge。产物仅供预览/后续 CD 寻址，不自动部署。
+
+## 7. 权限、安全与日志
+
+预览/通知凭据不作为整个质量作业的全局秘密。源码不得读取生产凭据。日志不输出秘密值。工作流变更重点由 GPT 审查；检查失败不能降低规则掩盖。
+
+## 8. 部署与 CI/CD 影响
+
+仅修改 CI 相关配置和入口，业务运行环境不变。静态预览保留现有能力但严格门禁，失败不发布。禁止添加 deploy:test/deploy-production 或启动 compose。
+
+## 9. 风险点
+
+前端存量格式/Lint 清理可能形成大量 diff，应独立提交；新工具版本/Runner可达性未验；后端测试的集成 skip 尚需核查；branch protection 与实时 Runner 状态未核实，不按旧 AGENTS 声明直接操作。
+
+## 10. Issue 草案、范围与验收
+
+### [ARCH] 知识治理平台统一质量入口与 CI 接入契约
+允许范围草案：Makefile、web/package.json、对应锁文件、前端格式/Lint 配置、AGENTS.md、README.md、.gitea/workflows/build.yml、.gitea/scripts/ci_gate.py、ci_report.py、独立检查自测夹具。
+禁止范围：业务逻辑、生产配置/Secrets、Runner、系统、业务发布 Worker。
+验收：干净检出能完成全部必需项；前端测试实际执行；本地/CI入口相同；版本正确注入；必需 skip 不假绿；行为不变。
+
+### [ARCH] 知识治理平台 CI 报告与反向验收
+验收：格式负例失败；单测负例失败；版本负例不预览且不通知成功；锁依赖缺失失败；身份错配失败；通知失败不掩盖质量；修复后的同类正例通过。
+负例优先隔离夹具，不能直接污染 main；必要临时分支由用户审批、完成后清理。
+
+开发拆分建议：先确认工具和测试条件 → 配置格式/Lint与统一入口 → 修订检出及范围 → 汇总/预览 → 安全门禁 → 正反例验收。由用户另行批准后交 DeepSeek 编写与测试，GPT 审查真实 diff、命令日志及运行URL，用户批准 push/合并。当前不创建 DEV 任务。
+
+## 11. 待确认与交付证据
+
+实现前补齐实际项目本地目录、工具版本、前端存量清理边界、集成环境与远端写权限。交付必须附完整提交 SHA、diff、真实命令/退出码、CI 运行URL、失败负例与修复正例、跳过/未验收项、未部署声明。模板或文档完成不等于 CI 启动成功。
diff --git a/docs/architecture/universal-ci-standard.md b/docs/architecture/universal-ci-standard.md
new file mode 100644
index 0000000..3502a55
--- /dev/null
+++ b/docs/architecture/universal-ci-standard.md
@@ -0,0 +1,168 @@
+# 通用工程规范修订草案：Git、代码质量与 CI
+
+状态：架构文档草案（**过程记录**），供修订正本和实现模板使用；尚未替代根目录 01/02 正本，尚未推送。本文不是已运行的 CI 配置。
+后续：本文中已落地生效的部分**已并入** `01-规范-Git与CI-CD（Gitea版）.md`（§3.1 测试语义、§4.1 CI/CD 分离、§4.8 必需检查清单与结果口径、§8 占位不许假报成功）与 `templates/`。看"现在是什么规则"请读 01；本文只解释"当初为什么这么定"。
+
+## 1. 背景和目标
+
+为所有项目提供一致的质量流程、检查契约和结果口径，以知识治理平台为首个验证样板。通用的是标准与流程，不强行统一语言工具和业务测试。CI 与 CD 分离。
+
+用户已确认：main 是唯一长期分支。日常直接在 main 开发；需要审批或尝试新方案时才使用临时分支与 PR，测试通过且批准后合并 main，关闭 PR、删除临时分支，保留记录。
+
+## 2. 约束条件
+
+- 不引入长期 develop/release/feature 分支，不默认强制所有改动走 PR，不自动更改分支保护。
+- 首期仅 CI：检查、测试、构建、证据；不部署服务、不迁移数据库、不访问生产数据。
+- 当前仅文档设计，不修改工作流/生成器/业务代码，不启动 coder、tester 或 cicd。
+- GPT 负责方案与实际 diff 审查，DeepSeek 负责另行批准的实现与修复；prototype 只承担 UI 原型与重大交互改版。
+- push、合并、发布、sudo、Runner 配置更改仍需对应授权，分支策略不是远端写权限的授权。
+
+## 3. 系统边界
+
+通用规范负责 MUST/SHOULD、触发策略、检查与报告契约；语言模板负责工具选择；项目负责显式模块和验收清单；CI 引擎负责运行与提交状态；通知/预览是可选旁路。项目 CD 仅引用 CI 产物证据，部署细节独立管理。
+
+推荐：一套通用规则 + Go/Python/Web 技术栈模板 + 显式项目清单。
+备选：初期用一个 CI 作业串行执行，保持报告完整。
+不推荐：依靠语言自动猜测决定必需项、模板默认携带部署、多个 Agent 自动审批合并。
+
+## 4. 模块划分与规范条款
+
+### 4.1 Git 与交付流程
+
+日常：main 修改 → 本地门禁 → 提交推送（获得相应授权）→ 远端 CI 复验 → GPT 按需审查。
+试验：临时分支 → PR → 头提交检查通过 → 用户批准 → 合并 → 读回合并结果 → 删除临时分支。
+
+CI 在推送后执行，不能阻止已经接受的直推；main CI 红时优先修复或经批准使用 revert 回退，不重写历史、不推进发布。多 Agent 不并行写同一工作区。
+
+保留 Conventional Commits：中文标题、≤72 字符、描述≥3 字符、冒号后一个空格、末尾无句号；scope 使用真实模块名；破坏性变更有 BREAKING CHANGE 说明。自动 merge/revert 等例外必须明确，不能用任意前缀逃逸。正文记录原因、取舍、真实验证及未验证项。
+
+PR 合并读回发生在合并后，不是合并前：确认 state=closed、merged=true、merge_commit_sha 存在，再确认临时分支清理。不能因为接口空响应而重复合并。
+
+### 4.2 通用代码质量
+
+- 按职责组织模块，不同义复制，不为尚未出现的需求过度抽象。
+- 统一格式与命名；注释优先解释原因，允许必要的接口/字段语义说明。
+- 不吞错误；对外错误稳定且不暴露内部秘密，内部诊断保留可定位信息。
+- 外部请求定义超时；重试需考虑幂等和次数限制。
+- 输入校验与权限检查在可信边界执行；不信任客户端身份字段。
+- 日志不包含密钥、原始凭据或不必要的个人/业务敏感内容。
+- 新功能覆盖正常和异常路径；缺陷修复补回归测试；禁止通过删除测试/降低规则来获得绿灯。
+- 行为变更同步接口与文档；Agent 不擅自改变契约、技术栈或扩大范围。
+
+格式、静态检查、测试与构建自动验证；设计合理性、权限语义和行为保持由审查与业务验收补充，不能假称全部可由 Lint 判断。
+
+### 4.3 通用 CI 检查顺序
+
+| ID | 必需检查 | 判据 |
+|---|---|---|
+| identity | 触发提交/检出身份 | 实际 HEAD 等于事件完整 SHA，版本工具存在 |
+| commits | 本次提交信息 | 范围准确、非空且规则通过；手动重跑按已记录事件语义处理 |
+| dependencies | 锁定依赖安装 | 锁文件存在、受控版本、依赖清单不被静默改写 |
+| format | 格式 | 不符合规则非零退出；CI 不自动修复 |
+| static | 静态检查/类型/Lint | 明确的语言模块检查全部通过 |
+| tests | 自动化测试 | 必需套件实际执行且通过，无测试不能假绿 |
+| build | 构建 | 声明的模块构建成功 |
+| contracts | 项目契约 | 版本与产物/接口等声明契约通过 |
+| security | 密钥/依赖漏洞 | 无泄漏，无未获授权的适用高危/严重风险，工具运行成功 |
+
+依赖安装后串行、失败即停；汇总始终执行。测试依赖产物时，在其测试前完成相应构建，记录依赖关系；Go test 会构建测试程序、Vitest 通常测源码，不要求所有单测必须先运行单独构建。
+
+项目必须声明各技术栈的适用检查，不适用项在清单里说明理由，不能执行时临时静默跳过。无可运行检查的项目不得直接报告成功。文档类仓库可声明链接/结构/模板契约检查，不强行要求业务单测。
+
+### 4.4 统一入口与依赖
+
+每个项目只定义一个权威本地门禁入口，名称可为 make verify、make check 或语言脚本，但 AGENTS、Runbook、CI 必须引用实际同一入口，不独立复制第二套核心步骤。
+
+提交信息范围、检出、安全扫描可以是外围门禁，但清单必须明确。严格串行不能只依赖 make 默认行为；调用者传入 -j 时也不得产生互相覆盖产物的并发。
+
+依赖必须按锁文件安装；缺失锁文件不能退化成无约束 install。缓存只加速，不作为通过证据；不得隐式依赖上次构建残留。工具缺失直接失败，不在运行中静默升级。新工具初次安装/Runner 预置需要另行授权。
+
+### 4.5 测试范围与安全门禁
+
+必需测试在隔离环境执行。依赖数据库的集成测试使用可销毁测试库，不连接生产，不触发真实扫描或发布。环境不足时标为未验证并说明补验路径；不能声称全部验收完成。
+
+覆盖率先建立证据基线，不立即设任意百分比硬门槛。必要场景包括权限拒绝、输入非法、任务重试/幂等、关键状态转换，具体由项目定义。
+
+密钥泄漏阻断，输出文件位置和类别而非秘密值；扫描范围覆盖本次变更及检出树，存量历史审计单独安排。适用高危/严重依赖漏洞阻断；无法确认适用性的结果必须显式待审查。例外记录漏洞ID、影响范围、理由、责任人、批准记录、截止条件/日期，过期自动失效。扫描工具或漏洞库获取失败不能伪装无漏洞；不得发送项目源码给未授权外部服务。
+
+### 4.6 通知、预览与触发
+
+推送 main 和临时分支触发同一质量检查；可提供人工重跑，不默认 tag 部署，不叠加相同 push/PR 重复运行。
+
+报告绑定完整 SHA 和 run_id；缺必需上下文不能使用 combined=success 放行。试验 PR 仍需要用户批准，不自动合并。
+
+通知不阻断已完成的质量检查，通知失败单独标注；汇总本身故障导致无法确定质量时不能报绿。预览仅在所有必需检查成功后运行；预览不能写入运行中服务或生产目录，且不影响发布开关。跨作业结果显式传递，禁止假定 /tmp 共享。取消的旧运行不算失败已修复，也不算成功。
+
+## 5. 数据模型草案
+
+项目清单：modules、toolchain_versions、verify_entrypoint、required_checks、optional_checks、test_dependencies、version_source、template_revision。
+检查报告：repository、commit_sha、run_id、event、policy_revision、checks[]、overall_status、artifact_refs、notification_status。
+每个 check：id、required、command、status、exit_code、log_ref、reason。
+状态：success/failure/skipped/cancelled/not_run/unknown。
+overall_status 仅当身份核对通过且所有必需项 success 时为 success；其他情况如实失败/取消/未完成，不能默认为成功。
+无业务数据库变更。
+
+## 6. API 草案
+
+不新增项目业务 API。项目以 CLI 入口产生退出码和结构化报告，CI 写回 Gitea。
+已有 bridge 报告接口若启用，接收上述检查报告或兼容字段；通知协议迁移必须实测兼容，不盲改 bridge。
+产物元数据至少含完整 commit_sha、工具链/模板版本、文件摘要，给后续项目 CD 使用。摘要由工具计算，不手填。
+
+## 7. 权限、安全、日志
+
+不向待测代码全局提供生产、发布或通知密钥；敏感值仅在需要的可信步骤可用。凭据不放 remote URL、argv 或日志。外部输入经环境变量/数据参数读取，不直接插入 shell 源码。
+
+CI 脚本/工作流本身属于审查对象；CI 通过不是授权。模板不得自动 sudo、推送、合并或更改保护。日志可定位首个失败步骤，脱敏且给出复现入口。
+
+## 8. 部署与 CI/CD 影响
+
+通用 CI 默认不生成 deploy:test/deploy-production。CD 各项目独立设计部署目标、产物形式、迁移、健康检查与回滚。通用规范仅保留人工授权、凭据安全、可追溯、使用验收过的同一产物和失败恢复原则，不强制 Docker、指定云、端口或数据库。
+
+未实现占位不得输出“已部署/已送达”并返回成功。生产部署触发及批准方式由项目设计，不能与默认 main CI 隐式绑定。
+
+## 9. 风险与迁移
+
+存量格式与 Lint 问题应独立清理，避免混入业务修改；批准的技术债基线需列明，不能永久忽略全目录。新工具可达性、工具链版本与测试环境需实测，不修改 Runner 来掩盖应用问题。
+
+现有正本中服务器地址、Docker-only、DobotAI 数据库/迁移等内容迁至环境/项目附录，保留原有操作记录但标明不是跨项目强制规范。
+
+必须同步正本、Runbook、接入文档、模板和生成器，避免新旧规则并存；本草案未落入模板前不得声称规范已全部生效。
+
+## 10. Gitea Issue 草案与开发拆分建议
+
+### [ARCH] 统一通用规范与 CI-only 边界
+范围：01 正本、02 Runbook、06 接入文档、README 与 templates/README。
+验收：单 main 与短命 PR 口径一致；日常路径不强制 PR；CI 与 CD 分离；测试语义正确；合并读回顺序正确；项目环境信息不再成为通用强制条款。
+
+### [ARCH] 定义技术栈检查与统一入口契约
+范围：检查清单、工具版本来源、Go/Python/Web 模板要求。
+验收：每项有实际工具选择、输入范围、通过/失败判据、适用理由与正反例；本地与 CI 同源；依赖解析不能静默漂移；严格串行不受 make -j 干扰。
+
+### [ARCH] 定义报告汇总、预览与接入安全契约
+范围：事件 SHA、检查状态、通知/预览、接入器合并权限。
+验收：版本失败不通知成功/不预览；缺失/超时/取消不假绿；跨作业无隐式文件共享；未获批准不请求合并；占位部署无假成功。
+
+实现拆分建议：先文档同步，再核心门禁，再报告/检出，再模板/生成器，再试点负例验证。由另行批准的 DeepSeek 实现，GPT 审查实际 diff 与执行结果；当前不创建 DEV 任务。
+
+### 必须通过的通用反向验收
+
+| 场景 | 预期 |
+|---|---|
+| 合规干净检出 | 所有必需项成功，SHA 对应准确 |
+| 格式错误 | format 失败，不自动修复 |
+| 静态/类型错误 | static 失败，后续标未运行 |
+| 故意失败的单测 | tests 失败，不能由构建成功覆盖 |
+| 必需测试不存在或必需套件跳过 | 不得报告全绿 |
+| 构建失败或版本契约失败 | 不预览、不通知质量成功 |
+| 依赖锁缺失/不一致 | dependencies 失败 |
+| 无真实秘密的合成密钥扫描夹具 | 扫描器按指定检测规则阻断，不打印值 |
+| 必需工具/漏洞库不可用 | 显式失败/未完成，不声称安全 |
+| 事件 SHA 与检出不一致 | identity 失败 |
+| 通知服务不可达 | 质量结果不变，通知失败另列 |
+| 接入器读到失败/未知/超时状态 | 不请求合并 |
+
+不得用故意失败提交污染日常 main。优先隔离夹具测试，必要时使用经用户同意的短命试验分支；验收后删除分支、保留运行记录。
+
+## 11. 需要用户确认的问题
+
+分支策略和 CI/CD 分离已确认，不重复提问。待实现前确认：技术栈工具的准确版本、存量格式清理范围、安全例外、临时集成环境、远端推送授权。任何 Runner/系统变更另行批准。