Files

T

姚章浩 ee28c0968f docs(architecture): 落库两份设计草案，并标注它们是过程记录而不是配置

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

同时在文头各加一行后续说明：已落地生效的部分已经并入 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 为准"。

2026-10-12 00:12:06 +08:00

6.0 KiB

Raw Permalink Blame History

知识治理平台：通用 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 启动成功。

6.0 KiB Raw Permalink Blame History Unescape Escape