Compare commits

...

3 Commits

Author SHA1 Message Date
姚章浩 ad9c5d20d4 Merge remote-tracking branch 'origin/main'
build / build (push) Successful in 49s
2026-10-13 19:08:54 +08:00
姚章浩 3a1d32da8f docs(readme): 重写平台定位与能力边界并归档原说明
build / build (push) Successful in 49s
2026-10-13 17:53:23 +08:00
t 950c1b429b feat(release): 抬档门禁(破坏性 ⇒ 0.x 抬次 / ≥1.0.0 抬主)+ 1.0.0 前置(稳定契约承诺)
原来预检只"打印破坏性条数",抬哪一档靠人自觉 ⇒ 改成硬门禁:

- **抬档门禁**:破坏性条数取自**目标提交里候选版本那一段**(发版事实看提交,不看工作区)。
  `0.x` 阶段有破坏性 ⇒ 必须抬**次版本**(或主版本),只抬修订 ⇒ 阻断并报出该抬到哪一档;
  `≥1.0.0` 之后有破坏性 ⇒ 必须抬**主版本**,抬次/修订都阻断。
  另加"候选号必须大于上一个正式版本"(版本只增不减)。
- **1.0.0 前置**:上一版本是 `0.x` 时,候选 `1.0.0` = 对外承诺契约稳定 ⇒ 必须先有写实的
  《稳定契约承诺》(覆盖 接口 / 数据模型 / 配置 / CLI 输出与退出码,不留 `待填`/`TODO`/`TBD`),
  **且候选发布记录里链接它**,缺任一条 ⇒ 阻断;`1.x → 2.0.0` 不重复要求。
- 预检新增"版本走向"事实行(上一版本 → 候选 / 抬哪一档 / 破坏性 N 条 ⇒ 要求哪一档 ✅⛔);
  `docs/RELEASE_RUNBOOK.md` 新增"抬哪一档"对照表与《稳定契约承诺》段(故意留占位)。

验证:release_preflight --self-test 32 分支全过(含新增 9 条);反向夹具新增 §24 六条真实临时仓库用例
(0.x 只抬修订 ⇒ 阻断、0.x 抬次 ⇒ 放行、≥1.0.0 抬次 ⇒ 阻断、1.0.0 留占位 ⇒ 阻断、写实+链接 ⇒ 放行、
写实但没链接 ⇒ 仍阻断)⇒ 夹具 91/0;make verify 15/15。
于是 0.1.0 之后的第一个提交(本提交)开发号 = 0.1.1。
2026-10-13 17:13:44 +08:00
5 changed files with 629 additions and 209 deletions
+115 -207
View File
@@ -1,251 +1,159 @@
# 知识同步治理平台
# 知识治理平台
独立的知识治理控制平面。当前包含P1持久任务队列、P2统一来源与PP历史接管、P3本地/测试WeKnora编排验收、P4来源只读扫描、P5知识工程师审核与封批门禁、默认关闭的P6三通道生产发布与回滚Worker,以及P7持久快照ChangeSet、真实运行监控和每50项一批的发布进度。
面向企业多数据源的知识同步、生命周期治理与持续运营平台。
## 安全边界
企业知识分散在钉钉、文件目录与业务资料门户中,内容会不断新增、更新和失效。平台连接这些来源与 WeKnora 知识底座,组织资料发现、取件、处理、验收、发布和下架,让知识不只是被导入一次,而是能够持续维护、追踪和治理。
- 本工程不修改 WeKnora、PP、AList、钉钉或 DobotAI 源码。
- PP接管与核验只读取指定的本地账本、manifest和测试WeKnora;不请求PP写接口,不修改来源文件。
- 普通Worker领取演示任务、`test.upload/test.poll/test.validate`和显式启用的`source.scan.pp`;只有普通Worker可挂载测试WeKnora Key和只读PP快照。
- Release Worker默认`RELEASE_WORKER_ENABLED=false`,禁用时不读取release config/生产secret,不连接生产数据面或治理数据库。
- P5封批只生成治理侧`sealed`记录,不创建生产发布Job;5条真实候选仍为待人工审核。
- P6生产请求另受`PRODUCTION_RELEASE_REQUESTS_ENABLED=false`保护;开启时还必须有服务端固定actor和0600 Bearer token文件。当前未授权、未配置、未发布生产。
- 凭据文件位于`secrets/`且被Git忽略;仓库只保留示例文件。
**同步是入口,知识库治理是核心,持续运营是目标。**
## 目录
## 平台解决什么问题
- **资料分散**:统一查看来源与目录,按范围选择、标注和获取内容。
- **更新难追踪**:通过来源身份、内容摘要、版本、快照与变更集记录变化。
- **处理不透明**:查看任务和解析状态,定位失败、停滞和需要人工处理的项目。
- **知识边界不清**:区分对内、对外和禁止导入,绑定相应测试与生产知识库。
- **上线不可控**:先处理与验收,再按审核策略和生产门禁组织发布。
- **失效难治理**:识别需下架内容,提供移除、失败重排与发布回滚等处理机制。
自动同步不等于无条件自动发布。不同来源的扫描、取件、处理和调度能力存在差异;生产变更仍受配置、权限与授权约束。
## 在 DobotAI 体系中的位置
```text
cmd/api HTTP API
cmd/worker 普通任务Worker
cmd/release-worker 默认关闭的发布Worker
cmd/pp-ledger-import PP历史账本一次性导入工具
internal/jobs 任务模型、租约和Worker循环
internal/governance 统一来源治理领域模型
internal/platform PostgreSQL仓库与Migration
internal/releasebundle v0.7.1发布bundle契约与摘要
internal/releaseadapter v0.7.1 PostgreSQL/ES/S3 Sidecar
internal/httpapi HTTP路由
web React TypeScript状态页
deploy Nginx配置
docs 验收计划
业务资料来源:钉钉 / AList / PP(资料门户)
↓
知识治理平台:发现与同步 → 状态跟踪 → 验收与治理 → 发布与维护
↓
WeKnora:文档处理、知识组织、索引与检索
↓
Knowledge Adapter / DobotAI 网关
↓
钉钉问答 / 软件内 AI 助理 / Wiki 问答等业务入口
```
## P2.1来源数据底座
本仓库负责知识治理流程与控制,不重复建设问答应用或检索引擎,也不修改 WeKnora 官方源码。Knowledge Adapter、DobotAI 网关及业务入口属于关联系统,不由本项目部署。
Migration 2创建五张空表:
## 核心能力与当前边界
```text
source_connections 来源连接配置,只保存secret引用名
source_items 来源内稳定对象身份与变化状态
content_objects 按完整SHA-256唯一的内容对象
source_item_versions 来源对象版本与内容对象关联
test_publications 测试知识库导入、处理、检索状态
```
下表描述仓库已有实现及文档记录的能力,**不代表任一部署环境已启用所有功能**。现场接线、运行开关与验收结果以对应环境为准。
`source_change`、`ingest_state`、`processing_state`和`retrieval_state`相互独立。只有同一来源连接内的`stable_external_id`唯一;只有完整小写SHA-256相同才能共享内容对象。
| 能力 | 已有支持 | 边界 |
| --- | --- | --- |
| 来源与目录管理 | 来源连接、目录浏览、范围选择、对内/对外/禁止导入策略 | 标注是治理意图,不代表已取件、入库或发布 |
| 多源资料获取 | 钉钉取件、AList 来源接入、PP 清单与历史账本接管 | 格式、凭据、目录及调度限制不同,不承诺所有来源全自动同步 |
| 变化与资产管理 | 稳定来源身份、内容摘要去重、来源版本、快照与变更集 | 来源变化与目标知识库处理状态分别记录 |
| 测试处理与验收 | 后台上传、轮询、知识与切片验收、失败恢复 | 解析和索引由对接的知识底座完成;部分检索判断仍需人工 |
| 解析与任务监控 | 处理中、失败/死信、需下架、知识库差异及处理进度视图 | 指标、动作与实际覆盖程度见验收清单,不等于完整告警平台 |
| 审核与发布 | 可配置自动审核策略、人工审核、批次锁定、生产授权与结果追踪 | 对内自动审核默认策略与对外人工控制详见操作流程;锁定不等于发布 |
| 回滚与备份 | 发布回滚、目标库快照门禁、备份配置及恢复工具 | 依赖专用接线、权限和恢复验证,不能仅凭页面存在判定可用 |
| 权限与审计 | 管理员、文档工程师、只读角色与操作记录 | 不等于已实现所有来源到问答端的文档级授权 |
P2.1不会自动创建来源连接、读取PP账本或上传文档。完整验收步骤见`docs/P2_SOURCE_FOUNDATION_ACCEPTANCE.md`。
### 数据源支持
## P2.2 PP历史账本接管
| 来源 | 当前接入方式 | 参考文档 |
| --- | --- | --- |
| 钉钉 | 知识库目录发现与取件;优先 dws,按错误类型决定是否回落兼容路径 | [钉钉取件](docs/DINGTALK_DWS_FETCHER.md) |
| AList | 来源目录与资料获取,依赖指定连接和凭据 | [用户操作流程](docs/OPERATIONS_RUNBOOK.md) |
| PP(资料门户) | 本地清单、历史账本接管与只读扫描 | [历史接管](docs/P2_PP_LEDGER_TAKEOVER_ACCEPTANCE.md)、[来源扫描](docs/P42_SOURCE_SCAN_ACCEPTANCE.md) |
一次性工具将PP append-only账本折叠为当前终态:
IT、行政等是待扩展的业务资料范围,不是已经完成的新连接器。接入敏感资料前,需要先确认 Owner、有效版本、可见范围与知识库路由。
```text
1093 条历史事件
→ 559 个来源对象和版本
→ 530 个SHA内容对象
→ 530 条历史测试发布
→ 29 个content_alias共享canonical内容和Knowledge ID
```
## 工作流程
75条旧`completed`记录缺少SHA时,只允许从locator hash匹配的本地manifest恢复,并重新校验文件大小和实际SHA-256。单文件继续遵守旧连接器50MiB上限。连接器默认关闭,历史发布的`retrieval_state`保持`unpublished`,等待未来对目标WeKnora逐条只读核验。
1. **配置来源与知识库绑定**:确认凭据、可见范围和目标库。
2. **发现、标注与取件**:按目录或文件选择范围,记录资料身份和变化。
3. **处理与验收**:进入测试知识库,跟踪上传、解析、索引及验收结果。
4. **审核与组批**:应用审核策略;建立并锁定发布清单,保留可追踪快照。
5. **授权发布**:核验备份与发布门禁,再执行目标知识库变更并读回验证。
6. **持续维护**:跟踪后续更新、失败、失效与需下架内容,按流程重排、移除或回滚。
工具只执行幂等INSERT,不执行UPDATE或DELETE。完整验收步骤见`docs/P2_PP_LEDGER_TAKEOVER_ACCEPTANCE.md`。
具体操作、确认语句和异常处理见 [操作 Runbook](docs/OPERATIONS_RUNBOOK.md);已实测、待验收和已知限制见 [用户流程验收清单](docs/USER_FLOWS_ACCEPTANCE.md)。
## P2.3 PP完整清单与知识资产页
## 访问与部署
P2.3将manifest中未进入旧账本的54个超限来源纳入治理视图:
### 已部署环境
```text
559 个历史终态 + 54 个over_limit阻断项 = 613 个来源对象
530 个内容对象
613 个来源版本
530 条历史测试发布
历史已同步内容计划重新上传数 = 0
```
Compose 中网页入口固定映射为 **宿主机 `8088` → Web 容器 `8080`**。网页和 `/api/` 使用同源入口。
超限版本没有虚假ContentObject或TestPublication,保持`content_state=over_limit`和阻断状态。`GET /api/v1/source-items`提供只读分页清单,支持`state=completed|content_alias|over_limit`、`limit`和`offset`;响应不包含来源URL、URI哈希、raw记录或Knowledge ID。Web“知识资产”模块读取该真实API。完整验收见`docs/P2_PP_INVENTORY_ACCEPTANCE.md`。
- 本机访问:`http://127.0.0.1:8088/`
- 局域网访问:`http://<服务器内网IP>:8088/`
- 健康入口:`http://127.0.0.1:8088/health`
## P3 WeKnora测试编排
可以由 NAS 反向代理提供 HTTPS 域名入口,目标为平台服务器的 `8088`,保持路径原样转发。公网开放前必须验证鉴权、访问控制及转发头配置,不直接暴露数据库或内部管理接口。
普通Worker从只读Spool流式上传到测试WeKnora,持久保存远端身份,按单调`poll_sequence`轮询,并在完成后执行Knowledge/Chunk验收。API和Web只返回安全投影;人工重试只允许失败或停滞且仍有已验证制品的Publication。530条PP历史Knowledge已在测试服务器完成在线只读核验,没有重新上传。
**平台入口展示当前部署版本,不是每次 CI 的构建预览。** CI 静态预览由独立链路提供;CI 通过不会自动更新运行服务。
本地、测试服务器、失败恢复、Worker重启和浏览器验收见`docs/P3_LOCAL_AND_CROSS_ENV_ACCEPTANCE.md`。
### 部署前提
## P4.1 来源连接只读工作台
当前 [compose.yaml](compose.yaml) 面向已有接线环境,包含宿主目录、凭据挂载和外部 Docker 网络,**不是仅克隆仓库就能直接启动的通用安装包**。
`GET /api/v1/source-connections`返回来源ID、类型、名称、启用状态、是否配置调度、健康枚举、对象数和更新时间。查询与响应均不包含`base_url`、`secret_ref`或原始健康错误正文。Web“来源管理”模块展示真实PostgreSQL数据,保留左侧导航和顶部多标签。
部署者需先准备:
P4.1完整验收见`docs/P41_SOURCE_CONNECTIONS_ACCEPTANCE.md`。
- Docker Compose,以及 `compose.yaml` 声明的外部网络。
- PostgreSQL、测试知识库及所启用来源的凭据文件与权限。
- 来源目录、spool 与运行状态挂载;按部署主机调整路径和 UID/GID。
- 测试 WeKnora 连接与对内/对外路由;生产发布按独立配置和授权接线。
## P4.2 PP只读扫描与变化入账
普通Worker在`PP_SCAN_ENABLED=true`且三个安全路径完整时注册`source.scan.pp` Handler。Compose仅给普通Worker只读挂载PP数据目录;API、Web和Release Worker均不挂载。Scanner拒绝越界、软链接、非普通文件和不完整manifest;54个历史`over_limit`项允许其制品未下载,但仍保持阻断。
Migration 5新增`source_scans`和`source_scan_changes`。触发Scan与创建Job原子执行,每个连接最多一个活动Scan;完成时聚合、变化与来源健康原子写入;失败只保存固定错误码。安全API支持触发、扫描历史和连接作用域详情,Web展示真实聚合与变化记录,不返回来源ID/revision/SHA/路径/URL或凭据。
真实PP快照只读扫描结果:
```text
observed=613
unchanged=559
over_limit=54
added=0
updated=0
missing=0
planned_uploads=0
```
过期`running`租约已由常驻Worker真实重领并以`attempt=2`完成;并发第二次触发返回`409`。完整迁移、备份、恢复、API和Firefox验收见`docs/P42_SOURCE_SCAN_ACCEPTANCE.md`。
## P5 知识工程师审核与封批
Migration 6新增追加式`publication_reviews`、`release_batches`和`release_batch_items`。审核决定绑定最新Acceptance run与Publication时间戳;批准仅允许完整结构门禁通过的候选,`retrieval_hit=manual_required`保持人工判断。创建draft和sealed封批均原子验证整个项目集合,任一项目失效则整批拒绝。
“发布管理”模块展示真实审核候选、固定门禁、决定可见性、草稿批次和封批记录,并明确显示“生产门禁保持关闭”“Release Worker保持关闭”“尚未发布”。当前535条Publication中,530条无逐条Acceptance的PP legacy不自动进入人工队列;5条manual合成验收项显示为ready/pending,持久库没有代替知识工程师创建Review或Batch。
P5 Store与HTTP写链路已在disposable PostgreSQL和临时API中验证`pending→approved→draft→sealed`,完成后临时数据库与临时密钥文件均清理;持久环境只应用空Migration 6。完整验收见`docs/P5_REVIEW_AND_SEAL_ACCEPTANCE.md`。
## P6 生产发布Worker与回滚
Migration 7新增`release_executions`与`release_item_executions`。只有受保护的生产授权请求才能把P5 sealed batch原子转换为`release.publish` Job;rollback只允许针对完整成功的publish execution。终态失败可在同一Bearer门禁下重排,仅重置failed items并重新验证sealed snapshot。API和Release Worker使用两个独立默认关闭的门禁,UI只展示执行审计,不提供一键生产授权按钮。
Release Worker按Knowledge Base精确路由,固定WeKnora `v0.7.1 / migration 74 / elasticsearch_v8 / 1024维`契约;同一release package协调复制以下内容且不触发生产解析/Embedding:
```text
PostgreSQL: knowledges/chunks/knowledge_tags/relations/resources/bindings
对象存储: referenced assets,staging→SHA校验→相同relative key
Elasticsearch: chunk text+vectors,先upsert新文档再清理同Knowledge旧_id
```
每个release revision写入0700目录中的0600 bundle并重验整包SHA。失败恢复旧bundle;首次发布无旧revision时禁用Knowledge/Chunk/ES,不删除行、文档或对象。生产WeKnora官方API最终验证Knowledge、Chunk数和knowledge-scoped检索。
本地真实验收使用完整v0.7.1 75个migration的source/target PostgreSQL、真实MinIO、状态化ES协议服务,已通过`publish v1 → publish v2 → rollback v1`以及PG disable、S3 Open/Put/Copy、Worker受限配置装配。模板见`config/release.v071.example.json`,完整边界与结果见`docs/P6_RELEASE_WORKER_ACCEPTANCE.md`。
当前生产状态保持:
```text
PRODUCTION_RELEASE_REQUESTS_ENABLED=false
RELEASE_WORKER_ENABLED=false
release executions/items/jobs=0/0/0
```
## 服务配置在哪配(四项)
「系统设置 → 服务配置」只保留四项,其他都不在这页:
| 项 | 含义 | 校验 | 谁来写 |
| --- | --- | --- | --- |
| 测试地址 | 控制台探活的测试 WeKnora 地址 | 裸 http(s) 源地址 | 仅管理员 |
| 生产地址 | 控制台探活的生产 WeKnora 地址 | 裸 http(s) 源地址 | 仅管理员 |
| 生产 ID | 发布契约里的租户 ID | 十进制整数(空 = 未配置);保存时真查它是否就是该知识库的租户 | 仅管理员 |
| 知识库 ID | 生产知识库标识 | 不含空格、`/`、`?`、`#`、`\`(空 = 未配置);保存时必须在该地址上真实存在 | 仅管理员 |
一次点「保存并启用服务配置」四项一起提交:服务端先格式校验,再写版本化的活动设置(候选 → 激活 →
旧版本保留审计),网页只录裸地址、绝不夹带凭据。四项里任何一项相对活动版本发生变化都要管理员角色,
普通工程师提交会被 403(只改刷新参数不受影响)。留空表示未配置,界面如实显示「未配置」。
- 地址探活:后端按地址真打 `/health`,显示「端点可达 / 不可达 · 未做接单验证」;测试地址留空时回落到
容器 env `TEST_WEKNORA_BASE_URL`,生产地址回落到 `PRODUCTION_WEKNORA_BASE_URL`(可选
`PRODUCTION_WEKNORA_API_KEY_FILE`、`PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP=false`)。探活只打
`/health`,从不读写知识库、从不参与发布,所以生产端点抖动不会阻断测试流水线。
- **两个 ID 的真校验(保存时执行)**:保存/激活服务配置时,后端拿「生产地址 + 生产 API Key 文件」
调 WeKnora 列库接口(`GET /api/v1/knowledge-bases/{id}`,回落到 `GET /api/v1/knowledge-bases`
列租户)真查一次:
- 查到 → 通过,界面显示知识库名与观测到的租户(`verification.knowledge_base_name` /
`observed_tenant_id`,服务端只读,从不写回配置);
- 端点明确回答「没有这个知识库」或租户与该库不符 → **拒绝保存**(HTTP 400 + 原话),一行都不写;
- 端点抖动、超时、`401/403`、未配置生产凭据 → **只警告不拦**(响应里带 `verification.status`
= `unreachable` / `unauthorized` / `cannot_verify`),保存照常落地——运维不能因为端点故障就改不了地址。
真校验需要 api 容器能读到生产凭据:`PRODUCTION_WEKNORA_API_KEY_FILE` 指向 0600 文件(值永不进网页、
永不进响应);留空时该项显示「未核验:没有可用的生产 API Key 文件」,其余行为不变。
激活前会再查一次(候选可以躺几天,库可能已被删);字段与线上一致的回放不重复核验,幂等重试不受端点影响。
覆盖率要点:租户校验只在「该库的 tenant_id」这一条路径上成立;只填生产 ID 时按列库结果的租户去比对。
- 排列组合之外的东西(依赖探活矩阵、对内/对外知识库绑定下拉)已从这页摘掉;依赖状态在总览页,
绑定数据与 API 仍在(`internal/httpapi/routing_bindings.go`,迁移 000034)。
发布目标与凭据仍然是另一件事,刻意不进网页:
1. 发布通道的目标(唯一真源,Release Worker 读它):`RELEASE_CONFIG_FILE` 指向的 0600 JSON 里
`routes[].target.weknora.base_url`(同级 `api_key_file`),模板见 `config/release.v071.example.json`。
硬约束:绝对路径、0600 普通文件、严格 JSON(多字段即报错)、source/target 不能是同一库或同一桶。
凭据与发布目标刻意不进网页、不回读——它只在管理员受限的运行时配置里。
所以:网页上配的地址管「控制台看到的真实状态」,真正发单时的目标仍由发布运行时配置决定。改了一处却
忘了另一处时,控制台会显示旧地址的真实状态——这是提示,不是故障。
## 本地验证
要求Go 1.26、Node.js 22和npm。
准备完成后,由获授权的操作者执行:
```bash
make test
make vet
make build
make web-test
make web-typecheck
make web-build
```
## Docker Compose(由操作者执行)
先创建仅限本机的密钥文件:
```bash
cp secrets/postgres_password.example secrets/postgres_password
cp secrets/pgpass.example secrets/pgpass
# 将两个文件中的CHANGE_ME_LOCAL_ONLY替换为同一随机本地密码
chmod 600 secrets/postgres_password secrets/pgpass
docker compose up --build -d
```
Compose默认让三个Go进程以`1000:1000`运行,以读取宿主机Owner为1000且权限为600的密钥文件。若操作者UID/GID不同,启动前设置`APP_UID`和`APP_GID`为密钥文件Owner。
主机需要提权时,由操作者按本机权限规则执行,不在自动化中默认使用 sudo。停止服务可用 `docker compose down`;**不要执行 `docker compose down -v`,除非明确批准删除数据库卷。**
访问:
## 配置与安全边界
- 状态页:`http://127.0.0.1:8088/`
- 同源健康检查:`http://127.0.0.1:8088/health`
- 网页服务地址用于控制台探活与配置核验;真正的发布目标由受限发布运行时配置决定,两者不能混为一谈。
- 密钥通过文件或 secret 引用提供,不写入 Git、网页响应或日志。示例配置不是真实凭据。
- 生产请求与 Release Worker 默认关闭;启用状态必须现场确认。测试处理成功、自动审核或批次锁定都不能绕过生产门禁。
- 来源扫描与取件不应改写原始业务资料;目标知识库的发布、移除和回滚属于独立受控动作。
- 发布与恢复前必须按目标环境准备备份,并核验可恢复性。
停止时保留数据库:
参考:[服务与操作配置](docs/OPERATIONS_RUNBOOK.md)、[生产备份与恢复](docs/PRODUCTION_BACKUP_RECOVERY.md)、[来源范围规则](docs/SOURCE_SCOPE_POLICY.md)。
## 开发与 CI
基础环境:Go 1.26、Node.js 22、npm,以及检查脚本所需的 Python 3 和工具链。依赖以仓库锁文件和实际 CI 配置为准。
```bash
docker compose down
make verify # 完整检查入口:本地与 CI 使用同一套规则
make list # 查看检查清单与适用范围
```
不要执行`docker compose down -v`,除非明确决定删除本地数据库数据。
单项测试或构建只用于定位问题,不能代替完整验证。远端 CI 校验事件提交身份、汇总必需检查,再按条件生成静态预览与通知;不默认执行部署。
## P1 API
版本与变更见 [CHANGELOG](CHANGELOG.md),正式版本流程见 [发布 Runbook](docs/RELEASE_RUNBOOK.md)。`make version` 查看构建身份;日常开发构建与正式构建分开标识,软件版本 tag 不等同于知识发布批次。
创建普通演示任务:
## 后续方向
```bash
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"type":"demo","payload":{},"idempotency_key":"demo:001"}'
- 扩展多数据源调度与增量同步的覆盖范围。
- 完善处理监控、积压分析、告警及来源与目标知识库的一致性对账。
- 建设知识资产、新鲜度、更新超期与知识缺口报表。
- 对接评测和业务反馈,形成可归因的持续优化闭环。
- 细化敏感资料权限及生命周期规则。
这些是演进方向,不作为当前已上线能力承诺。待办见 [BACKLOG](docs/BACKLOG.md)。
## 文档导航
| 文档 | 用途 |
| --- | --- |
| [操作 Runbook](docs/OPERATIONS_RUNBOOK.md) | 使用步骤、配置、凭据续期与异常处理 |
| [用户流程验收](docs/USER_FLOWS_ACCEPTANCE.md) | 实测证据、待验收项及限制 |
| [领域模型](docs/DOMAIN_MODEL.md) / [状态机](docs/STATE_MACHINE.md) | 模块边界、数据与状态语义 |
| [发布与版本](docs/RELEASE_RUNBOOK.md) | 软件发布准备与只读预检 |
| [备份与恢复](docs/PRODUCTION_BACKUP_RECOVERY.md) | 知识库数据的备份、恢复与演练 |
| [旧 README 存档](docs/archive/README_BEFORE_PRODUCT_REWRITE.md) | 原阶段说明与历史验收记录;不是实时部署状态 |
## 仓库结构
```text
cmd/ API、任务 Worker、发布 Worker 与运维工具
internal/ 治理模型、任务队列、持久化、HTTP 与发布适配
web/ React / TypeScript 管理界面
deploy/ Nginx 配置
config/ 发布等受限配置的示例
scripts/ 检查、资料处理与运维脚本
docs/ 操作、设计、验收与历史档案
```
创建可用于租约恢复验收的30秒任务:
```bash
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"type":"demo.sleep","payload":{"sleep_ms":30000},"idempotency_key":"demo:sleep:001"}'
```
查看最近任务:
```bash
curl -fsS 'http://127.0.0.1:8088/api/v1/jobs?limit=50'
```
完整人工步骤见`docs/P1_ACCEPTANCE_TEST_PLAN.md`。
+20
View File
@@ -64,6 +64,26 @@ python3 scripts/version.py --identity # JSON:release_version / build_kind
- 二进制里的注入字段(`internal/version`)与上表一一对应;契约测试断言:
注入 == CHANGELOG 顶部(发布构建)、开发构建必须是 `dev` 形状(**不许声称正式版**),且**跳过不算通过**。
## 二·补、抬哪一档(硬门禁,预检会拦)
| 抬哪一位 | 什么情况 | 预检判据(不满足 ⇒ 阻断,发不出去) |
|---|---|---|
| **修订** `0.1.N → 0.1.N+1` | 只修 bug、内部改动:对外行为不变、无破坏性、无成规模新能力 | 候选号必须 **> 当前开发号**(开发号到 `0.1.7` 时只能发 `0.1.8` 及以上);候选 ≤ 上一个正式版本 ⇒ 阻断(号只增不减) |
| **次版本** `0.1.x → 0.2.0` | **有破坏性变化**(0.x 阶段一律走次版本),或成规模的对外新能力/行为变化 | 候选发布记录里破坏性条数 ≥1 且当前是 `0.x` ⇒ 必须抬**次版本**;只抬修订 ⇒ 阻断 |
| **主版本** `0.x → 1.0.0`、`1.x → 2.0.0` | 首次声明"对外契约稳定"(`1.0.0`);之后**任何**破坏性变化(`2.0.0`) | ≥1.0.0 阶段破坏性 ⇒ 必须抬**主版本**(抬次/修订都阻断);**首发 `1.0.0` 还要求本文《稳定契约承诺》写实并在发布记录里链接它** |
判据里用的"破坏性条数"取自**目标提交里候选版本那一段**(发版事实看提交里的记录,不看工作区)。
## 二·补·2、《稳定契约承诺》(发 1.0.0 的前置条件)
> ⛔ 现在**故意留着占位**:只要还有 `(待填)` / `TODO` / `TBD`,预检在候选为 `1.0.0`(且上一个正式版本是 `0.x`)时就会阻断。
> 逐项写实、并在 `CHANGELOG.md` 的 `## [1.0.0]` 记录里链接本文后,门禁才放行。四项一个都不能少。
- **接口**(待填):对外 HTTP / CLI / SDK 接口的稳定范围与版本策略(哪些字段冻结、变更怎么通知)。
- **数据模型**(待填):库表 / 文件 / 消息结构的兼容窗口与迁移责任。
- **配置**(待填):配置项与默认值的冻结范围、弃用流程、回退方式。
- **CLI 输出与退出码**(待填):脚本可依赖的输出形态与退出码约定。
## 三、破坏性变化 / 数据迁移怎么写
在 `CHANGELOG.md` 的 `### Changed` 里:
@@ -0,0 +1,255 @@
# 原 README 存档
> 来源:提交 `950c1b429bc814d9fa7c2c1449f999a05537af21` 的 README。保留历史阶段记录;其中数量、开关和部署结论不是当前环境的实时状态。原文相对链接以仓库根目录为基准。
# 知识同步治理平台
独立的知识治理控制平面。当前包含P1持久任务队列、P2统一来源与PP历史接管、P3本地/测试WeKnora编排验收、P4来源只读扫描、P5知识工程师审核与封批门禁、默认关闭的P6三通道生产发布与回滚Worker,以及P7持久快照ChangeSet、真实运行监控和每50项一批的发布进度。
## 安全边界
- 本工程不修改 WeKnora、PP、AList、钉钉或 DobotAI 源码。
- PP接管与核验只读取指定的本地账本、manifest和测试WeKnora;不请求PP写接口,不修改来源文件。
- 普通Worker领取演示任务、`test.upload/test.poll/test.validate`和显式启用的`source.scan.pp`;只有普通Worker可挂载测试WeKnora Key和只读PP快照。
- Release Worker默认`RELEASE_WORKER_ENABLED=false`,禁用时不读取release config/生产secret,不连接生产数据面或治理数据库。
- P5封批只生成治理侧`sealed`记录,不创建生产发布Job;5条真实候选仍为待人工审核。
- P6生产请求另受`PRODUCTION_RELEASE_REQUESTS_ENABLED=false`保护;开启时还必须有服务端固定actor和0600 Bearer token文件。当前未授权、未配置、未发布生产。
- 凭据文件位于`secrets/`且被Git忽略;仓库只保留示例文件。
## 目录
```text
cmd/api HTTP API
cmd/worker 普通任务Worker
cmd/release-worker 默认关闭的发布Worker
cmd/pp-ledger-import PP历史账本一次性导入工具
internal/jobs 任务模型、租约和Worker循环
internal/governance 统一来源治理领域模型
internal/platform PostgreSQL仓库与Migration
internal/releasebundle v0.7.1发布bundle契约与摘要
internal/releaseadapter v0.7.1 PostgreSQL/ES/S3 Sidecar
internal/httpapi HTTP路由
web React TypeScript状态页
deploy Nginx配置
docs 验收计划
```
## P2.1来源数据底座
Migration 2创建五张空表:
```text
source_connections 来源连接配置,只保存secret引用名
source_items 来源内稳定对象身份与变化状态
content_objects 按完整SHA-256唯一的内容对象
source_item_versions 来源对象版本与内容对象关联
test_publications 测试知识库导入、处理、检索状态
```
`source_change`、`ingest_state`、`processing_state`和`retrieval_state`相互独立。只有同一来源连接内的`stable_external_id`唯一;只有完整小写SHA-256相同才能共享内容对象。
P2.1不会自动创建来源连接、读取PP账本或上传文档。完整验收步骤见`docs/P2_SOURCE_FOUNDATION_ACCEPTANCE.md`。
## P2.2 PP历史账本接管
一次性工具将PP append-only账本折叠为当前终态:
```text
1093 条历史事件
→ 559 个来源对象和版本
→ 530 个SHA内容对象
→ 530 条历史测试发布
→ 29 个content_alias共享canonical内容和Knowledge ID
```
75条旧`completed`记录缺少SHA时,只允许从locator hash匹配的本地manifest恢复,并重新校验文件大小和实际SHA-256。单文件继续遵守旧连接器50MiB上限。连接器默认关闭,历史发布的`retrieval_state`保持`unpublished`,等待未来对目标WeKnora逐条只读核验。
工具只执行幂等INSERT,不执行UPDATE或DELETE。完整验收步骤见`docs/P2_PP_LEDGER_TAKEOVER_ACCEPTANCE.md`。
## P2.3 PP完整清单与知识资产页
P2.3将manifest中未进入旧账本的54个超限来源纳入治理视图:
```text
559 个历史终态 + 54 个over_limit阻断项 = 613 个来源对象
530 个内容对象
613 个来源版本
530 条历史测试发布
历史已同步内容计划重新上传数 = 0
```
超限版本没有虚假ContentObject或TestPublication,保持`content_state=over_limit`和阻断状态。`GET /api/v1/source-items`提供只读分页清单,支持`state=completed|content_alias|over_limit`、`limit`和`offset`;响应不包含来源URL、URI哈希、raw记录或Knowledge ID。Web“知识资产”模块读取该真实API。完整验收见`docs/P2_PP_INVENTORY_ACCEPTANCE.md`。
## P3 WeKnora测试编排
普通Worker从只读Spool流式上传到测试WeKnora,持久保存远端身份,按单调`poll_sequence`轮询,并在完成后执行Knowledge/Chunk验收。API和Web只返回安全投影;人工重试只允许失败或停滞且仍有已验证制品的Publication。530条PP历史Knowledge已在测试服务器完成在线只读核验,没有重新上传。
本地、测试服务器、失败恢复、Worker重启和浏览器验收见`docs/P3_LOCAL_AND_CROSS_ENV_ACCEPTANCE.md`。
## P4.1 来源连接只读工作台
`GET /api/v1/source-connections`返回来源ID、类型、名称、启用状态、是否配置调度、健康枚举、对象数和更新时间。查询与响应均不包含`base_url`、`secret_ref`或原始健康错误正文。Web“来源管理”模块展示真实PostgreSQL数据,保留左侧导航和顶部多标签。
P4.1完整验收见`docs/P41_SOURCE_CONNECTIONS_ACCEPTANCE.md`。
## P4.2 PP只读扫描与变化入账
普通Worker在`PP_SCAN_ENABLED=true`且三个安全路径完整时注册`source.scan.pp` Handler。Compose仅给普通Worker只读挂载PP数据目录;API、Web和Release Worker均不挂载。Scanner拒绝越界、软链接、非普通文件和不完整manifest;54个历史`over_limit`项允许其制品未下载,但仍保持阻断。
Migration 5新增`source_scans`和`source_scan_changes`。触发Scan与创建Job原子执行,每个连接最多一个活动Scan;完成时聚合、变化与来源健康原子写入;失败只保存固定错误码。安全API支持触发、扫描历史和连接作用域详情,Web展示真实聚合与变化记录,不返回来源ID/revision/SHA/路径/URL或凭据。
真实PP快照只读扫描结果:
```text
observed=613
unchanged=559
over_limit=54
added=0
updated=0
missing=0
planned_uploads=0
```
过期`running`租约已由常驻Worker真实重领并以`attempt=2`完成;并发第二次触发返回`409`。完整迁移、备份、恢复、API和Firefox验收见`docs/P42_SOURCE_SCAN_ACCEPTANCE.md`。
## P5 知识工程师审核与封批
Migration 6新增追加式`publication_reviews`、`release_batches`和`release_batch_items`。审核决定绑定最新Acceptance run与Publication时间戳;批准仅允许完整结构门禁通过的候选,`retrieval_hit=manual_required`保持人工判断。创建draft和sealed封批均原子验证整个项目集合,任一项目失效则整批拒绝。
“发布管理”模块展示真实审核候选、固定门禁、决定可见性、草稿批次和封批记录,并明确显示“生产门禁保持关闭”“Release Worker保持关闭”“尚未发布”。当前535条Publication中,530条无逐条Acceptance的PP legacy不自动进入人工队列;5条manual合成验收项显示为ready/pending,持久库没有代替知识工程师创建Review或Batch。
P5 Store与HTTP写链路已在disposable PostgreSQL和临时API中验证`pending→approved→draft→sealed`,完成后临时数据库与临时密钥文件均清理;持久环境只应用空Migration 6。完整验收见`docs/P5_REVIEW_AND_SEAL_ACCEPTANCE.md`。
## P6 生产发布Worker与回滚
Migration 7新增`release_executions`与`release_item_executions`。只有受保护的生产授权请求才能把P5 sealed batch原子转换为`release.publish` Job;rollback只允许针对完整成功的publish execution。终态失败可在同一Bearer门禁下重排,仅重置failed items并重新验证sealed snapshot。API和Release Worker使用两个独立默认关闭的门禁,UI只展示执行审计,不提供一键生产授权按钮。
Release Worker按Knowledge Base精确路由,固定WeKnora `v0.7.1 / migration 74 / elasticsearch_v8 / 1024维`契约;同一release package协调复制以下内容且不触发生产解析/Embedding:
```text
PostgreSQL: knowledges/chunks/knowledge_tags/relations/resources/bindings
对象存储: referenced assets,staging→SHA校验→相同relative key
Elasticsearch: chunk text+vectors,先upsert新文档再清理同Knowledge旧_id
```
每个release revision写入0700目录中的0600 bundle并重验整包SHA。失败恢复旧bundle;首次发布无旧revision时禁用Knowledge/Chunk/ES,不删除行、文档或对象。生产WeKnora官方API最终验证Knowledge、Chunk数和knowledge-scoped检索。
本地真实验收使用完整v0.7.1 75个migration的source/target PostgreSQL、真实MinIO、状态化ES协议服务,已通过`publish v1 → publish v2 → rollback v1`以及PG disable、S3 Open/Put/Copy、Worker受限配置装配。模板见`config/release.v071.example.json`,完整边界与结果见`docs/P6_RELEASE_WORKER_ACCEPTANCE.md`。
当前生产状态保持:
```text
PRODUCTION_RELEASE_REQUESTS_ENABLED=false
RELEASE_WORKER_ENABLED=false
release executions/items/jobs=0/0/0
```
## 服务配置在哪配(四项)
「系统设置 → 服务配置」只保留四项,其他都不在这页:
| 项 | 含义 | 校验 | 谁来写 |
| --- | --- | --- | --- |
| 测试地址 | 控制台探活的测试 WeKnora 地址 | 裸 http(s) 源地址 | 仅管理员 |
| 生产地址 | 控制台探活的生产 WeKnora 地址 | 裸 http(s) 源地址 | 仅管理员 |
| 生产 ID | 发布契约里的租户 ID | 十进制整数(空 = 未配置);保存时真查它是否就是该知识库的租户 | 仅管理员 |
| 知识库 ID | 生产知识库标识 | 不含空格、`/`、`?`、`#`、`\`(空 = 未配置);保存时必须在该地址上真实存在 | 仅管理员 |
一次点「保存并启用服务配置」四项一起提交:服务端先格式校验,再写版本化的活动设置(候选 → 激活 →
旧版本保留审计),网页只录裸地址、绝不夹带凭据。四项里任何一项相对活动版本发生变化都要管理员角色,
普通工程师提交会被 403(只改刷新参数不受影响)。留空表示未配置,界面如实显示「未配置」。
- 地址探活:后端按地址真打 `/health`,显示「端点可达 / 不可达 · 未做接单验证」;测试地址留空时回落到
容器 env `TEST_WEKNORA_BASE_URL`,生产地址回落到 `PRODUCTION_WEKNORA_BASE_URL`(可选
`PRODUCTION_WEKNORA_API_KEY_FILE`、`PRODUCTION_WEKNORA_ALLOW_DOCKER_HTTP=false`)。探活只打
`/health`,从不读写知识库、从不参与发布,所以生产端点抖动不会阻断测试流水线。
- **两个 ID 的真校验(保存时执行)**:保存/激活服务配置时,后端拿「生产地址 + 生产 API Key 文件」
调 WeKnora 列库接口(`GET /api/v1/knowledge-bases/{id}`,回落到 `GET /api/v1/knowledge-bases`
列租户)真查一次:
- 查到 → 通过,界面显示知识库名与观测到的租户(`verification.knowledge_base_name` /
`observed_tenant_id`,服务端只读,从不写回配置);
- 端点明确回答「没有这个知识库」或租户与该库不符 → **拒绝保存**(HTTP 400 + 原话),一行都不写;
- 端点抖动、超时、`401/403`、未配置生产凭据 → **只警告不拦**(响应里带 `verification.status`
= `unreachable` / `unauthorized` / `cannot_verify`),保存照常落地——运维不能因为端点故障就改不了地址。
真校验需要 api 容器能读到生产凭据:`PRODUCTION_WEKNORA_API_KEY_FILE` 指向 0600 文件(值永不进网页、
永不进响应);留空时该项显示「未核验:没有可用的生产 API Key 文件」,其余行为不变。
激活前会再查一次(候选可以躺几天,库可能已被删);字段与线上一致的回放不重复核验,幂等重试不受端点影响。
覆盖率要点:租户校验只在「该库的 tenant_id」这一条路径上成立;只填生产 ID 时按列库结果的租户去比对。
- 排列组合之外的东西(依赖探活矩阵、对内/对外知识库绑定下拉)已从这页摘掉;依赖状态在总览页,
绑定数据与 API 仍在(`internal/httpapi/routing_bindings.go`,迁移 000034)。
发布目标与凭据仍然是另一件事,刻意不进网页:
1. 发布通道的目标(唯一真源,Release Worker 读它):`RELEASE_CONFIG_FILE` 指向的 0600 JSON 里
`routes[].target.weknora.base_url`(同级 `api_key_file`),模板见 `config/release.v071.example.json`。
硬约束:绝对路径、0600 普通文件、严格 JSON(多字段即报错)、source/target 不能是同一库或同一桶。
凭据与发布目标刻意不进网页、不回读——它只在管理员受限的运行时配置里。
所以:网页上配的地址管「控制台看到的真实状态」,真正发单时的目标仍由发布运行时配置决定。改了一处却
忘了另一处时,控制台会显示旧地址的真实状态——这是提示,不是故障。
## 本地验证
要求Go 1.26、Node.js 22和npm。
```bash
make test
make vet
make build
make web-test
make web-typecheck
make web-build
```
## Docker Compose(由操作者执行)
先创建仅限本机的密钥文件:
```bash
cp secrets/postgres_password.example secrets/postgres_password
cp secrets/pgpass.example secrets/pgpass
# 将两个文件中的CHANGE_ME_LOCAL_ONLY替换为同一随机本地密码
chmod 600 secrets/postgres_password secrets/pgpass
docker compose up --build -d
```
Compose默认让三个Go进程以`1000:1000`运行,以读取宿主机Owner为1000且权限为600的密钥文件。若操作者UID/GID不同,启动前设置`APP_UID`和`APP_GID`为密钥文件Owner。
访问:
- 状态页:`http://127.0.0.1:8088/`
- 同源健康检查:`http://127.0.0.1:8088/health`
停止时保留数据库:
```bash
docker compose down
```
不要执行`docker compose down -v`,除非明确决定删除本地数据库数据。
## P1 API
创建普通演示任务:
```bash
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"type":"demo","payload":{},"idempotency_key":"demo:001"}'
```
创建可用于租约恢复验收的30秒任务:
```bash
curl -fsS -X POST http://127.0.0.1:8088/api/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"type":"demo.sleep","payload":{"sleep_ms":30000},"idempotency_key":"demo:sleep:001"}'
```
查看最近任务:
```bash
curl -fsS 'http://127.0.0.1:8088/api/v1/jobs?limit=50'
```
完整人工步骤见`docs/P1_ACCEPTANCE_TEST_PLAN.md`。
+99 -1
View File
@@ -805,5 +805,103 @@ else
no "预检留下了 tag:$(git tag -l 'v*' | tr '\n' ' ')"
fi
echo
echo "§24 抬档门禁(破坏性 ⇒ 0.x 抬次 / ≥1.0.0 抬主)与 1.0.0 前置(《稳定契约承诺》)"
cat >/tmp/kg_bump_lib.py <<'LIB'
import os, pathlib, shutil, subprocess, tempfile
def mk(prev, cand, breaking_in_changed, stab_section=None, link_in_record=False):
"""造临时仓库:CHANGELOG 顶部 = 候选版本,下面留上一版本;docs 里有/没有承诺段。"""
d = pathlib.Path(tempfile.mkdtemp(prefix="kg-bump-"))
(d / "scripts").mkdir()
for n in ("check_changelog.py", "release_preflight.py", "version.py"):
(d / "scripts" / n).write_text(pathlib.Path("scripts", n).read_text(encoding="utf-8"),
encoding="utf-8")
(d / "docs").mkdir()
doc = "# 发布运行手册\n"
if stab_section:
doc += "\n## 稳定契约承诺(占位)\n\n" + stab_section + "\n"
(d / "docs" / "RELEASE_RUNBOOK.md").write_text(doc, encoding="utf-8")
(d / ".gitea").mkdir()
(d / ".gitea" / "required-contexts.txt").write_text("build / build (push)\n", encoding="utf-8")
changed = ("\n### Changed\n\n- **破坏性**:接口下线,升级见 "
"[发布文档](docs/RELEASE_RUNBOOK.md)\n") if breaking_in_changed else ""
added = "- 新东西" + ("(稳定契约承诺见 [本文](docs/RELEASE_RUNBOOK.md))" if link_in_record else "")
(d / "CHANGELOG.md").write_text(
f"# Changelog\n\n## [{cand}] - 2026-10-13\n\n### Added\n\n{added}\n{changed}"
f"\n## [{prev}] - 2026-09-01\n\n### Fixed\n\n- 旧\n", encoding="utf-8")
(d / "no-hooks").mkdir()
env = {**os.environ, "GIT_AUTHOR_NAME": "f", "GIT_AUTHOR_EMAIL": "f@f",
"GIT_COMMITTER_NAME": "f", "GIT_COMMITTER_EMAIL": "f@f",
"GIT_CONFIG_COUNT": "1", "GIT_CONFIG_KEY_0": "core.hooksPath",
"GIT_CONFIG_VALUE_0": str(d / "no-hooks")}
for a in (["init", "-q", "-b", "main"], ["add", "-A"], ["commit", "-q", "-m", "chore: 夹具"]):
subprocess.run(["git", *a], cwd=d, env=env, check=True, capture_output=True)
return d
def pre(prev, cand, breaking, *args, **kw):
d = mk(prev, cand, breaking, **kw)
try:
r = subprocess.run(["python3", "scripts/release_preflight.py", "--version", cand, "--no-api"],
cwd=d, capture_output=True, text=True)
return r.stdout + r.stderr
finally:
shutil.rmtree(d, ignore_errors=True)
LIB
FULL="冻结 /api/v1;变更提前一个次版本通知。|表结构兼容窗口 2 个大版本。|配置项冻结,弃用先警告一个小版本。|0/1/2 语义固定。"
pycheck "破坏性 + 0.x 只抬修订(0.1.0→0.1.3)⇒ 阻断,并给出抬档结论" <<'PY'
import kg_bump_lib as L # noqa
out = L.pre("0.1.0", "0.1.3", True)
good = "必须抬**次版本**" in out and "⛔ 抬档不够" in out
print(("✅ " if good else "❌ ") + "版本走向行:" + next((l.strip() for l in out.splitlines()
if "版本走向" in l), "(没有这行)"))
raise SystemExit(0 if good else 1)
PY
pycheck "破坏性 + 0.x 抬次(0.1.0→0.2.0)⇒ 该条不拦(✅ 抬档够)" <<'PY'
import kg_bump_lib as L # noqa
out = L.pre("0.1.0", "0.2.0", True)
good = "必须抬**次版本**" not in out and "✅ 抬档够" in out
print(("✅ " if good else "❌ ") + next((l.strip() for l in out.splitlines() if "版本走向" in l), ""))
raise SystemExit(0 if good else 1)
PY
pycheck "破坏性 + ≥1.0.0 只抬次(1.2.3→1.3.0)⇒ 阻断(必须抬主)" <<'PY'
import kg_bump_lib as L # noqa
out = L.pre("1.2.3", "1.3.0", True)
good = "必须抬**主版本**" in out
print(("✅ " if good else "❌ ") + next((l.strip() for l in out.splitlines() if "版本走向" in l), ""))
raise SystemExit(0 if good else 1)
PY
pycheck "首发 1.0.0 但《稳定契约承诺》留占位 ⇒ 阻断(报出占位与缺项)" <<'PY'
import kg_bump_lib as L # noqa
out = L.pre("0.9.3", "1.0.0", False,
stab_section="- **接口**(待填)\n- **数据模型**(待填)\n")
good = "稳定契约承诺" in out and "占位" in out and "没覆盖「配置」" in out
print(("✅ " if good else "❌ ") + next((l.strip() for l in out.splitlines() if "1.0.0 前置" in l), ""))
raise SystemExit(0 if good else 1)
PY
pycheck "1.0.0 + 承诺段写实 + 发布记录里链接 ⇒ 该条不拦" <<'PY'
import kg_bump_lib as L # noqa
sec = ("- **接口**:冻结 /api/v1;变更提前一个次版本通知。\n"
"- **数据模型**:表结构兼容窗口 2 个大版本。\n"
"- **配置**:配置项冻结,弃用先警告一个小版本。\n"
"- **CLI 输出与退出码**:0/1/2 语义固定。\n")
out = L.pre("0.9.3", "1.0.0", False, stab_section=sec, link_in_record=True)
good = "候选进入 1.0.0" not in out and "✅ 已写实" in out
print(("✅ " if good else "❌ ") + next((l.strip() for l in out.splitlines() if "1.0.0 前置" in l), ""))
raise SystemExit(0 if good else 1)
PY
pycheck "1.0.0 + 承诺段写实但发布记录里**没链接** ⇒ 仍阻断" <<'PY'
import kg_bump_lib as L # noqa
sec = ("- **接口**:冻结 /api/v1。\n- **数据模型**:兼容 2 个大版本。\n"
"- **配置**:配置项冻结。\n- **CLI 输出与退出码**:0/1/2 固定。\n")
out = L.pre("0.9.3", "1.0.0", False, stab_section=sec, link_in_record=False)
good = "候选进入 1.0.0" in out and "没有链接" in out
print(("✅ " if good else "❌ ") + next((l.strip() for l in out.splitlines() if "1.0.0 前置" in l), ""))
raise SystemExit(0 if good else 1)
PY
printf '\n\033[1m════ 反向验收汇总 ════\033[0m\n ✅ 通过 %d | ❌ 失败 %d\n' "$pass" "$fail"
[ "$fail" -eq 0 ] || exit 1
[ "$fail" -eq 0 ] || exit 1
+140 -1
View File
@@ -213,6 +213,61 @@ def _ver_tuple(v: str) -> tuple[int, int, int]:
return a, b, c
BREAK_ITEM = re.compile(r"^\s*(?:[-*+]|\d+[.)])?\s*\*\*破坏性\*\*")
STABILITY_HEADING = re.compile(r"(?m)^##+\s*.*稳定契约承诺")
# 「稳定契约承诺」必须逐项覆盖的对外契约面(缺项 / 留占位 ⇒ 不许发 1.0.0)
STABILITY_ITEMS = ("接口", "数据模型", "配置", "CLI 输出与退出码")
STABILITY_PLACEHOLDERS = ("待填", "TODO", "TBD", "xxx", "XXX")
STABILITY_DOCS = ("docs/RELEASE_RUNBOOK.md", "docs/STABILITY_CONTRACT.md")
def released_in_commit(sha: str, *, root: Path = ROOT) -> list[str]:
"""目标提交里 CHANGELOG 的已发布版本清单(顶部在前)。"""
rc, text = _git_read("show", f"{sha}:CHANGELOG.md", cwd=root)
return released_versions(text) if rc == 0 else []
def breaking_in_commit(sha: str, version: str, *, root: Path = ROOT) -> int:
"""**候选版本那一段**里的破坏性变化条数(发版事实看提交里的记录,不看工作区)。"""
rc, text = _git_read("show", f"{sha}:CHANGELOG.md", cwd=root)
if rc != 0:
return 0
return sum(1 for line in block_of(text, version).splitlines() if BREAK_ITEM.match(line))
def bump_level(prev: str | None, cand: str) -> str | None:
"""抬了哪一档:major / minor / patch;比不出来(首发 / 号没涨)⇒ None。"""
if not (prev and SEMVER.match(prev) and SEMVER.match(cand)):
return None
a, b = _ver_tuple(prev), _ver_tuple(cand)
if b[0] > a[0]:
return "major"
if b[0] == a[0] and b[1] > a[1]:
return "minor"
if b[0] == a[0] and b[1] == a[1] and b[2] > a[2]:
return "patch"
return None
def stability_contract_problems(*, root: Path = ROOT) -> list[str]:
"""《稳定契约承诺》是否写实(发 1.0.0 的前置条件);返回缺失项(空 = 合格)。"""
doc = next((root / d for d in STABILITY_DOCS
if (root / d).is_file()
and STABILITY_HEADING.search((root / d).read_text(encoding="utf-8"))), None)
if doc is None:
return [f"找不到《稳定契约承诺》段(在 {' 或 '.join(STABILITY_DOCS)} 里以 `## …稳定契约承诺` 开头)"]
text = doc.read_text(encoding="utf-8")
sec = text[STABILITY_HEADING.search(text).start():]
problems: list[str] = []
for item in STABILITY_ITEMS:
if item not in sec:
problems.append(f"没覆盖「{item}」")
holes = [w for w in STABILITY_PLACEHOLDERS if w in sec]
if holes:
problems.append(f"还留着占位没填({'、'.join(holes)})")
return problems
def readiness(f: dict) -> tuple[bool, list[str], list[str]]:
"""把**事实**翻成(是否就绪, 阻塞项, 准备建议)——纯函数,可用假事实直接自检。
@@ -245,6 +300,30 @@ def readiness(f: dict) -> tuple[bool, list[str], list[str]]:
advice.append("下一次正式发布建议用 <主>.<次+1>.0(保证正式号严格大于此前所有开发号)")
except ValueError:
pass
prev, level = f.get("prev_version"), f.get("bump_level")
breaking_n = int(f.get("breaking_in_candidate") or 0)
if prev and level and breaking_n:
prev_major = _ver_tuple(str(prev))[0]
if prev_major == 0 and level == "patch":
blocks = (f"有 {breaking_n} 条破坏性变化,但 {prev} → {cand} 只抬了**修订**:"
f"0.x 阶段破坏性变化必须抬**次版本**(例如 "
f"0.{_ver_tuple(str(prev))[1] + 1}.0)—— 否则使用者按'只是修 bug'升级会踩坑")
blockers.append(blocks)
advice.append(f"把候选改成 0.{_ver_tuple(str(prev))[1] + 1}.0(抬次版本),"
f"并在发布文档里写清升级/迁移与回退")
if prev_major >= 1 and level != "major":
blockers.append(f"有 {breaking_n} 条破坏性变化,但 {prev} → {cand} 没有抬**主版本**:"
f"≥1.0.0 之后破坏性变化必须抬**主版本**(例如 {prev_major + 1}.0.0)")
advice.append(f"把候选改成 {prev_major + 1}.0.0(抬主版本)")
if level is None and prev and SEMVER.match(str(prev)) and SEMVER.match(str(cand)) \
and _ver_tuple(str(cand)) <= _ver_tuple(str(prev)):
blockers.append(f"候选 {cand} 不大于上一个正式版本 {prev}(版本号只增不减)")
if f.get("first_1_0_0") and not f.get("stability_ok"):
problems = f.get("stability_problems") or ["(未取到具体缺失项)"]
blockers.append("候选进入 1.0.0 = 对外承诺契约稳定:必须先把《稳定契约承诺》写实、"
"并在候选发布记录里链接它 —— 缺:" + ";".join(str(x) for x in problems))
advice.append("在 docs 的《稳定契约承诺》里逐项写实 接口 / 数据模型 / 配置 / CLI 输出与退出码,"
"并在本次 CHANGELOG 的发布记录里链接该文档;不满足就先发 0.x")
if f.get("candidate_tagged"):
blockers.append(f"远端已经有 tag v{cand} ⇒ 不能覆盖已发布的 tag(版本号只增不减)")
if f.get("dirty"):
@@ -371,6 +450,36 @@ def main(argv: list[str]) -> int:
tag = f"v{candidate}"
required, policy_src = required_contexts()
dev_number, dev_commits = current_dev_number()
rels = released_in_commit(want_sha)
prev_version = next((v for v in rels if v != candidate), None)
level = bump_level(prev_version, candidate)
breaking_n = breaking_in_commit(want_sha, candidate)
first_1_0_0 = (SEMVER.match(candidate) is not None and _ver_tuple(candidate)[0] == 1
and (prev_version is None or _ver_tuple(prev_version)[0] == 0))
stab_problems: list[str] = []
if first_1_0_0:
stab_problems = stability_contract_problems()
rc, ctext = _git_read("show", f"{want_sha}:CHANGELOG.md")
blk = block_of(ctext, candidate) if rc == 0 else ""
if not (any(d in blk for d in STABILITY_DOCS) or "稳定契约承诺" in blk):
stab_problems.append("候选发布记录里没有链接《稳定契约承诺》"
f"(应引 {' 或 '.join(STABILITY_DOCS)})")
stab_ok = not stab_problems
level_cn = {"major": "主版本", "minor": "次版本", "patch": "修订"}.get(level or "", "看不出来(首发 / 号没涨)")
prev_major = _ver_tuple(prev_version)[0] if (prev_version and SEMVER.match(prev_version)) else None
if not breaking_n:
tail = "候选记录里没有破坏性变化 ⇒ 抬哪一档不限(但候选号必须 > 当前开发号)"
elif prev_major is None:
tail = f"候选记录里有 {breaking_n} 条破坏性变化(首发,无上一版本可比)"
else:
need = ("0.x 阶段:有破坏性必须抬次版本(或主版本)" if prev_major == 0
else "≥1.0.0:有破坏性必须抬主版本")
ok = (level in ("minor", "major")) if prev_major == 0 else (level == "major")
tail = f"候选记录里有 {breaking_n} 条破坏性变化 ⇒ {need} {'✅ 抬档够' if ok else '⛔ 抬档不够'}"
print(f" 版本走向 : {prev_version or '(首发)'} → {candidate}(抬{level_cn})|{tail}")
if first_1_0_0:
print(f" 1.0.0 前置 : 《稳定契约承诺》"
f"{'✅ 已写实' if stab_ok else '⛔ 未写实:' + ';'.join(stab_problems)}")
print(f" 当前开发号 : {dev_number or '(无正式基线 / 取不到 tag ⇒ dev+g<短SHA>)'}"
f"{f'(自 v{current} 起 {dev_commits} 个提交)' if (dev_number and dev_commits is not None) else ''}")
top_in_commit = top_version_in_commit(want_sha)
@@ -437,6 +546,8 @@ def main(argv: list[str]) -> int:
"candidate": candidate, "tag": tag, "first_release": first_release,
"explicit_version": bool(args.version), "in_target_commit": in_target,
"top_in_commit": top_in_commit, "dev_number": dev_number,
"prev_version": prev_version, "bump_level": level, "breaking_in_candidate": breaking_n,
"first_1_0_0": first_1_0_0, "stability_ok": stab_ok, "stability_problems": stab_problems,
"dirty": len(dirty_lines), "head_full": bool(FULL_SHA.match(head)),
"sha_is_head": want_sha == head, "checker_ok": checker_ok,
"unreleased_present": bool(unreleased.strip()),
@@ -495,6 +606,9 @@ def self_test() -> int:
"remote_tags_checked": True, "required_contexts": ["build / build (push)"],
"contexts": {"build / build (push)": "success"}, "contexts_error": "",
"release_exists": False, "release_query_error": "", "no_api": False,
# 版本走向/破坏性/1.0.0 前置(默认:无上一版本、无破坏性 ⇒ 新判据不参与)
"prev_version": None, "bump_level": None, "breaking_in_candidate": 0,
"first_1_0_0": False, "stability_ok": True, "stability_problems": [],
}
def rd(name: str, ready_want: bool, needle: str = "", **over) -> None:
@@ -526,6 +640,31 @@ def self_test() -> int:
True, "", candidate="0.2.0", dev_number="0.1.12", in_target_commit=True,
contexts={"build / build (push)": "success"})
rd("候选版本没进目标提交 ⇒ 不就绪", False, "还没写进目标提交", in_target_commit=False)
# ── 抬档判据:破坏性变化 ⇒ 0.x 抬次、≥1.0.0 抬主 ──
rd("破坏性 + 0.x 只抬修订(0.1.0→0.1.3)⇒ 不就绪",
False, "必须抬**次版本**", candidate="0.1.3", prev_version="0.1.0", bump_level="patch",
breaking_in_candidate=1)
rd("破坏性 + 0.x 抬次(0.1.0→0.2.0)⇒ 该条不拦", True,
candidate="0.2.0", prev_version="0.1.0", bump_level="minor", breaking_in_candidate=2)
rd("破坏性 + ≥1.0.0 只抬次(1.2.3→1.3.0)⇒ 不就绪",
False, "必须抬**主版本**", candidate="1.3.0", prev_version="1.2.3", bump_level="minor",
breaking_in_candidate=1)
rd("破坏性 + ≥1.0.0 抬主(1.2.3→2.0.0)⇒ 该条不拦", True,
candidate="2.0.0", prev_version="1.2.3", bump_level="major", breaking_in_candidate=1)
rd("无破坏性 + 只抬修订(0.1.0→0.1.3)⇒ 抬档不拦", True,
candidate="0.1.3", prev_version="0.1.0", bump_level="patch", breaking_in_candidate=0)
rd("候选号没涨(0.2.0→0.2.0)⇒ 不就绪", False, "只增不减",
candidate="0.2.0", prev_version="0.2.0", bump_level=None, breaking_in_candidate=0)
# ── 1.0.0 首见:必须有写实的《稳定契约承诺》 ──
rd("首发 1.0.0 但《稳定契约承诺》没写实 ⇒ 不就绪", False, "稳定契约承诺",
candidate="1.0.0", prev_version="0.9.3", bump_level="major", first_1_0_0=True,
stability_ok=False, stability_problems=["没覆盖「配置」", "还留着占位没填(待填)"])
rd("首发 1.0.0 且《稳定契约承诺》写实 ⇒ 该条不拦", True,
candidate="1.0.0", prev_version="0.9.3", bump_level="major", first_1_0_0=True,
stability_ok=True, stability_problems=[])
rd("已经是 1.x 再抬到 2.0.0 ⇒ 不要求重写承诺段", True,
candidate="2.0.0", prev_version="1.4.0", bump_level="major", breaking_in_candidate=1,
first_1_0_0=False)
rd("候选版本只在历史里(顶部是别的版本)⇒ 不就绪,且信息里给出真实顶部版本",
False, "顶部**已发布版本是 `## [0.3.0]`",
in_target_commit=False, top_in_commit="0.3.0", candidate="0.2.0")
@@ -639,7 +778,7 @@ def self_test() -> int:
print(f" · {p}", file=sys.stderr)
return 1
print("✅ 预检自检通过:写类 git 命令与 POST/PUT/DELETE/PATCH 在预检路径上全部被拒;版本推进正确;"
"就绪判定 21 个分支(context 缺项/pending/failure/查询异常、无策略、Release 非 404、"
"就绪判定 32 个分支(context 缺项/pending/failure/查询异常、无策略、Release 非 404、"
"tag 占用、未核对远端、首发未显式指定、记录未进提交…逐条阻断;证据齐才就绪);"
"『顶部版本才算数』与『写进提交才算数』用临时仓库验证;"
"`--execute` 明确拒绝且零写操作、零 API 调用")