From cb04ebbe0dc306bb0b953d630d5250e0017bc9c2 Mon Sep 17 00:00:00 2001 From: KXH Date: Fri, 31 Jul 2026 19:57:57 +0800 Subject: [PATCH] release: define showcase and owner acceptance gates --- DOCUMENT_INDEX.md | 17 +- Dockerfile | 2 +- IMPLEMENTATION_HANDOFF.md | 122 ++++--- LICENSE | 201 +++++++++++ README.md | 26 +- README.zh-CN.md | 19 +- ...2026-07-31-spec-release-readiness-audit.md | 211 +++++------- docs/development-log/current-state.md | 324 +++--------------- docs/development-log/daily/2026-07-31.md | 13 + .../opercerta-ownership-acceptance.md | 151 ++++++++ ...showcase-release-and-ownership-closeout.md | 46 +++ ...-showcase-release-gate-amendment-design.md | 91 +++++ scripts/verify_repository_safety.py | 10 +- tests/unit/runtime/test_container_assets.py | 1 + tests/unit/runtime/test_release_assets.py | 50 ++- .../scripts/test_verify_repository_safety.py | 13 + 16 files changed, 812 insertions(+), 485 deletions(-) create mode 100644 LICENSE create mode 100644 docs/learning/opercerta-ownership-acceptance.md create mode 100644 docs/superpowers/plans/2026-07-31-showcase-release-and-ownership-closeout.md create mode 100644 docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md diff --git a/DOCUMENT_INDEX.md b/DOCUMENT_INDEX.md index e9a9929..57f177c 100644 --- a/DOCUMENT_INDEX.md +++ b/DOCUMENT_INDEX.md @@ -1,12 +1,12 @@ # OperCerta 文档总索引 -本索引完整登记 OperCerta 当前根工作树中的 119 份 Markdown 文档，并保留旧电脑 6 个 `.worktrees/` 的 456 条历史登记。当前根工作树与每个历史 worktree 使用独立六列表格和独立序号；路径均相对于仓库根目录；日期表示文档首次建立日期。历史 worktree 表用于追溯分支资料，不表示对应物理目录仍存在。Git 元数据、依赖目录、虚拟环境和工具缓存不属于项目文档登记范围。 +本索引完整登记 OperCerta 当前根工作树中的 122 份 Markdown 文档，并保留旧电脑 6 个 `.worktrees/` 的 456 条历史登记。当前根工作树与每个历史 worktree 使用独立六列表格和独立序号；路径均相对于仓库根目录；日期表示文档首次建立日期。历史 worktree 表用于追溯分支资料，不表示对应物理目录仍存在。Git 元数据、依赖目录、虚拟环境和工具缓存不属于项目文档登记范围。 Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/install_typora_index_theme.ps1`，重启 Typora 后选择 `主题 → OperCerta Index`。该主题让正文使用 96% 窗口宽度，并统一设置下列全部六列表格的列宽、自动换行和字号。 ## 项目核心学习导航 -先按 A1–A9 完成一轮“阅读 → 找到代码 → 手动验证 → 自己复述”。后面的 119 份当前文档与 456 条历史 worktree 登记是排查问题和深入学习时使用的资料库，不需要从头到尾顺序阅读。 +先按 A1–A9 完成一轮“阅读 → 找到代码 → 手动验证 → 自己复述”。后面的 122 份当前文档与 456 条历史 worktree 登记是排查问题和深入学习时使用的资料库，不需要从头到尾顺序阅读。 | 阶段 | 核心主题 | 优先阅读 | 代码与配置入口 | 必做实践 | 掌握标准 | | ---: | --- | --- | --- | --- | --- | @@ -18,17 +18,17 @@ Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/i | A6 | 审批、安全边界与可靠性内核 | [审批原子性](docs/release-evidence/approval-atomicity.md)、[幂等工单](docs/release-evidence/work-order-idempotency.md)、[重启恢复](docs/release-evidence/langgraph-restart-recovery.md)、[批准后 Verifier](docs/release-evidence/agent-verifier-reapproval.md) | [审批仓储](src/opercerta/infrastructure/db/approval_repository.py)、[工单仓储](src/opercerta/infrastructure/db/work_order_repository.py)、[Checkpoint](src/opercerta/infrastructure/checkpoints.py)、[工具策略](src/opercerta/agent/tool_policy.py) | 复现一次重复审批或重启恢复，随后核对数据库事实、审计序列和唯一工单。 | 能用数据库约束、事务、状态机和幂等键解释为什么不会因模型重试产生重复副作用。 | | A7 | React 前端、FastAPI 与身份权限 | [控制台证据](docs/release-evidence/single-page-console.md)、[JWT/RBAC 证据](docs/release-evidence/demo-jwt-rbac.md) | [React 控制台](web/src/App.tsx)、[API 应用](src/opercerta/api/app.py)、[认证授权](src/opercerta/api/auth.py)、[请求模型](src/opercerta/api/models.py) | 从浏览器完成一个业务闭环，同时在 Network 与后端 Trace 中对应每个请求、角色切换和状态更新。 | 能解释 React 只负责交互状态，FastAPI 负责协议与鉴权，Agent 内核负责决策编排，PostgreSQL 保存权威事实。 | | A8 | PostgreSQL、Redis、Docker 与可观测性 | [三业务发布证据](docs/release-evidence/three-business-release.md)、[Docker 证据](docs/release-evidence/docker-linux-runtime.md)、[可观测性证据](docs/release-evidence/observability-security-regression.md) | [Compose](compose.yaml)、[Dockerfile](Dockerfile)、[Redis 缓存](src/opercerta/infrastructure/cache.py)、[数据库迁移](migrations)、[Tracing](src/opercerta/observability/tracing.py) | 执行健康检查、查看容器状态、重启 API/MCP，并确认 checkpoint、业务事实和工单没有丢失或重复。 | 能解释容器与 Compose 的区别、Redis 为什么不是权威存储、PostgreSQL/pgvector 的双重职责及日志如何安全关联。 | -| A9 | 故障复盘与面试输出 | [面试讲解](docs/learning/opercerta-interview-guide.md)、[工程案例集](docs/development-log/interview-casebook.md)、[最新开发日志](docs/development-log/daily/2026-07-31.md) | 选择前述任一真实故障对应的代码、日志和修复提交。 | 分别完成 30 秒、3 分钟和 10 分钟讲解；独立复述一个“现象 → 根因 → 修复 → 验证 → 取舍”案例。 | 不看文档也能讲清业务价值、核心链路、技术取舍、可靠性证据和未完成边界，并能接受追问。 | +| A9 | 本人掌握、故障复盘与演示 | [项目所有者掌握验收](docs/learning/opercerta-ownership-acceptance.md)、[工程案例集](docs/development-log/interview-casebook.md)、[最新开发日志](docs/development-log/daily/2026-07-31.md) | 选择一次真实业务闭环和一个真实故障对应的代码、日志、数据库事实与修复提交。 | 独立执行完整库存闭环、重启/幂等实验和 30 秒/3 分钟/10 分钟讲解，保存 operation/work order/Trace/审计证据并录制 3–5 分钟视频。 | 不看稿也能操作、定位代码、解释取舍和失败收口；验收不得由 Codex 自动代签。 | -## 根工作树（119 份） +## 根工作树（122 份） 显示说明：本表及后续各 worktree 表均保持“序号、文件名、路径、用途、状态、日期”六列完整字段。 | 序号 | 文件名 | 路径 | 用途（详细） | 状态 | 日期 | | ---: | --- | --- | --- | --- | --- | | 1 | `README.md` | `README.md` | 英文项目总入口，使用顶部 `English｜简体中文` 标准链接切换语言，说明业务背景、三业务功能、Agent 闭环、完整技术栈、快速启动、使用流程、验证结果、可靠性边界和路线图。 | 每页只显示一种语言；不使用折叠框 | 2026-07-30 | -| 2 | `IMPLEMENTATION_HANDOFF.md` | `IMPLEMENTATION_HANDOFF.md` | 跨对话和上下文压缩后的实施交接文件，记录当前分支、已验证事实、未完成事项、下一步动作及禁止越过的发布边界。 | 已同步 PR #18、最终 main Compose、静态 production、Showcase 预发布与下一掌握阶段 | 2026-07-30 | -| 3 | `DOCUMENT_INDEX.md` | `DOCUMENT_INDEX.md` | OperCerta 全部项目文档的唯一总登记表，用于按文件名、路径、用途、状态和日期统一检索、复查与交接。 | 当前根工作树 119 份文档已完整登记；另保留 6 个旧 worktree 的 456 条历史记录 | 2026-07-15 | +| 2 | `IMPLEMENTATION_HANDOFF.md` | `IMPLEMENTATION_HANDOFF.md` | 跨对话和上下文压缩后的实施交接文件，记录当前分支、已验证事实、未完成事项、下一步动作及禁止越过的发布边界。 | 已切换为当前权威快照；Showcase 待本人验收，Product gate 关闭 | 2026-07-30 | +| 3 | `DOCUMENT_INDEX.md` | `DOCUMENT_INDEX.md` | OperCerta 全部项目文档的唯一总登记表，用于按文件名、路径、用途、状态和日期统一检索、复查与交接。 | 当前根工作树 122 份文档已完整登记；另保留 6 个旧 worktree 的 456 条历史记录 | 2026-07-15 | | 4 | `2026-07-14-agent-project-naming-design.md` | `docs/specs/2026-07-14-agent-project-naming-design.md` | 定义 OperCerta、ForenTrail、SiteVerum、Federune 四个项目的命名原则、语义边界与品牌一致性，防止项目职责和名称漂移。 | 已冻结为命名基线 | 2026-07-14 | | 5 | `ai-agent-portfolio-overall-design.md` | `docs/specs/ai-agent-portfolio-overall-design.md` | 规定四个 AI Agent 项目的整体定位、差异化业务范围、技术能力组合、实施顺序和共同约束，是项目组合的最高层设计依据。 | 已冻结为总体设计基线；文件名已统一为英文路径 | 2026-07-14 | | 6 | `2026-07-14-agent-portfolio-design.md` | `docs/specs/2026-07-14-agent-portfolio-design.md` | 设计四项目如何组合成求职作品集，包括能力覆盖、展示顺序、共享基础设施边界和避免重复建设的原则。 | 已冻结为组合设计基线 | 2026-07-14 | @@ -68,7 +68,7 @@ Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/i | 40 | `2026-07-20-opercerta-three-business-release.md` | `docs/superpowers/plans/2026-07-20-opercerta-three-business-release.md` | 将三业务适配、六个 MCP 工具、评测、Redis、OpenTelemetry、真实模型代表验证、本地发布和中文学习包拆成主线任务。 | 本地任务已执行；公网交互、用户掌握与最终门禁待完成 | 2026-07-20 | | 41 | `2026-07-20-opercerta-zero-cost-showcase-engineering-walkthrough.md` | `docs/superpowers/plans/2026-07-20-opercerta-zero-cost-showcase-engineering-walkthrough.md` | 规划统一事实清单、招聘专题、本地工程详解、控制台共存、响应式测试、静态导出和 Netlify 发布验证。 | 计划已创建；根分支尚未归档完成证据 | 2026-07-20 | | 42 | `README.md` | `docs/development-log/README.md` | 说明开发日志目录结构、各类日志职责、记录规范、敏感信息禁区和上下文恢复阅读顺序。 | 已建立并持续使用 | 2026-07-15 | -| 43 | `current-state.md` | `docs/development-log/current-state.md` | 保存最新可验证项目状态、测试证据、运行环境、发布边界、未完成事项和下一步，作为压缩上下文后的事实入口；同时区分本地候选镜像、空缓存冷构建、远程 CI 和真实生产发布四类证据。 | 已同步 PR #18/main 五项门禁、Showcase 预发布、静态 production、回滚点及仍关闭的产品边界 | 2026-07-30 | +| 43 | `current-state.md` | `docs/development-log/current-state.md` | 保存最新可验证项目状态、测试证据、运行环境、发布边界、未完成事项和下一步，作为压缩上下文后的唯一当前事实入口；历史状态只保留在 daily 与 release evidence。 | 工程门禁通过；Showcase 待本人验收；Product gate 关闭 | 2026-07-30 | | 44 | `2026-07-15.md` | `docs/development-log/daily/2026-07-15.md` | 记录日志体系、Windows PostgreSQL、审批领域契约及初始可靠性实施过程与命令证据。 | 当日记录已归档 | 2026-07-15 | | 45 | `2026-07-16.md` | `docs/development-log/daily/2026-07-16.md` | 记录库存补货 Task 1–9、幂等工单、LangGraph 恢复、调试过程和本地验证结果。 | 当日记录已归档 | 2026-07-16 | | 46 | `2026-07-17.md` | `docs/development-log/daily/2026-07-17.md` | 记录 WSL2、Docker Linux 运行时、JWT/RBAC 和 Compose 环境迁移中的问题、修复与验证。 | 当日记录已归档 | 2026-07-17 | @@ -145,6 +145,9 @@ Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/i | 117 | `2026-07-31-spec-release-readiness-audit.md` | `docs/development-log/audits/2026-07-31-spec-release-readiness-audit.md` | 对照四份原始设计及三业务、Agent 核心、信号收件箱和单根 LangGraph 有效修订，逐项核验当前源码、技术栈、测试、Compose、Netlify 和发布证据，区分合理设计演进、真实偏差、开源治理缺口、公网交互条件和简历可用边界。 | 审计完成；架构主线一致，本地/静态发布可用，公网交互与企业生产门禁未通过 | 2026-07-31 | | 118 | `README.zh-CN.md` | `README.zh-CN.md` | 简体中文项目总入口，与英文 README 保持等价结构和事实，使用顶部 `English｜简体中文` 链接切换语言，并独立展示中文业务、架构、启动、验证和边界内容。 | 每页只显示一种语言；不使用折叠框 | 2026-07-31 | | 119 | `CONTRIBUTING.zh-CN.md` | `CONTRIBUTING.zh-CN.md` | 简体中文贡献指南，与英文贡献指南保持等价结构和事实，使用顶部 `English｜简体中文` 链接切换语言。 | 每页只显示一种语言；不使用折叠框 | 2026-07-31 | +| 120 | `2026-07-31-showcase-release-gate-amendment-design.md` | `docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md` | 正式拆分 Showcase Release 与 Product Release，规定当前版本交付物为公开静态展示、本地可复现完整 Agent MVP、自动化证据、本人验收和录屏，并禁止把静态站点误报为公网交互产品。 | 已批准；Showcase 等待本人验收，Product gate 保持 CLOSED | 2026-07-31 | +| 121 | `2026-07-31-showcase-release-and-ownership-closeout.md` | `docs/superpowers/plans/2026-07-31-showcase-release-and-ownership-closeout.md` | 将双门禁修订、许可证、Docker 工具链、安全扫描、权威文档同步、自动化验证、本人掌握和最终 tag 拆成可执行收口任务。 | 实施中；最终 tag 必须等待本人验收与录屏 | 2026-07-31 | +| 122 | `opercerta-ownership-acceptance.md` | `docs/learning/opercerta-ownership-acceptance.md` | 规定项目所有者必须亲自完成的环境检查、库存完整闭环、源码链路、重启/幂等实验及 30 秒/3 分钟/10 分钟讲解，并记录 operation、work order、Trace、审计和数据库事实。 | `AWAITING_OWNER_VALIDATION`；不得由 Codex 自动代签 | 2026-07-31 | ## 历史 Worktree：agent-core-architecture（82 条记录） diff --git a/Dockerfile b/Dockerfile index 4a44905..ae26b6e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,6 +1,6 @@ FROM python:3.12.13-slim-bookworm -COPY --from=ghcr.io/astral-sh/uv:0.10.10 /uv /uvx /usr/local/bin/ +COPY --from=ghcr.io/astral-sh/uv:0.11.28 /uv /uvx /usr/local/bin/ WORKDIR /app COPY pyproject.toml uv.lock README.md ./ diff --git a/IMPLEMENTATION_HANDOFF.md b/IMPLEMENTATION_HANDOFF.md index 183cbc8..fcf37f3 100644 --- a/IMPLEMENTATION_HANDOFF.md +++ b/IMPLEMENTATION_HANDOFF.md @@ -1,87 +1,85 @@ -# OperCerta｜智能运营处置 Agent：实施交接 +# OperCerta 实施交接 -## 当前检查点 +> 更新时间：2026-07-31。先读 `DOCUMENT_INDEX.md` 的核心阅读表，再读本文件和 `docs/development-log/current-state.md`。 -- 2026-07-31：最终证据修订经 [PR #18](https://github.com/KXHXK/opercerta/pull/18) 合入 main `298fc5978a56961d36e73888f4ae73017e302715`；[main run 30541088053](https://github.com/KXHXK/opercerta/actions/runs/30541088053) 的 repository-safety、python-quality、frontend、backend-tests、compose-smoke 五项全绿，继续证明后端 `667 passed`、三业务契约、冻结 Agent `9/9`、前端 19 文件/60 条和真实 Compose 重启恢复。[Showcase 预发布 `v0.1.0-showcase.1`](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1) 精确指向该提交；Netlify 静态 production 仍为已核验 deploy `6a6b17cf496c38056f737264`，上一 production `6a6631d24958714a43ddc508` 可回滚。自动化工程与求职静态展示已收口，下一步只做用户源码掌握、完整业务实演、3–5 分钟录屏和简历定稿；公网可写后端及产品治理仍未完成，产品 release gate 保持 `CLOSED`，不启动 ForenTrail。 -- 2026-07-30：发布准备分支经 [PR #17](https://github.com/KXHXK/opercerta/pull/17) 全绿后，以普通 merge commit `b6aa5fa13c7645bd3351092fc23b6c3e132a284d` 合入 main；[main run 30539160493](https://github.com/KXHXK/opercerta/actions/runs/30539160493) 五项全绿，包含完整后端 `667 passed`、三业务契约 `1 passed`、冻结 Agent `9/9`、前端 19 文件/60 条和真实 Compose 重启恢复。已验证 Netlify Preview `6a6b17cf496c38056f737264` 经官方可回滚 API 晋级 production，公网三个静态路由、六项安全头和 JS SHA-256 均复验通过；上一 production `6a6631d24958714a43ddc508` 为回滚点。下一步只做固定评测、源码掌握、演示和简历材料；公网可写后端及生产治理仍未完成，产品 release gate 保持 `CLOSED`，不启动 ForenTrail。 +## 当前交接结论 -- 2026-07-30：换机环境分支经 [PR #15](https://github.com/KXHXK/opercerta/pull/15) 合并为 main 提交 `42ba974`；对应 [main run 30525556998](https://github.com/KXHXK/opercerta/actions/runs/30525556998) 的 repository-safety、python-quality、frontend、backend-tests 和实际 compose-smoke 全部成功。compose-smoke 已执行镜像构建、三业务 Agent 轨迹与数据库副作用、API/MCP 重启、恢复验证和隔离卷清理。本地 main 已 fast-forward 到同一提交；WSL 的 Node `24.18.0`、npm `11.16.0`、uv `0.11.28` 可用，PostgreSQL/Redis/MCP/API 四服务均 healthy，readiness 为 database/checkpoint/MCP 全部 ready。当前后续分支为 `chore/release-readiness-20260730`，用于部署、评测、源码掌握和简历材料收口；公网可写后端和生产 IAM/限流/备份仍未实现，production release gate 保持 `CLOSED`，不启动 ForenTrail。 +OperCerta 的代码与自动化主线已经完成，当前收口分支为 `release/showcase-ownership-closeout-20260731`。收口前最新 main 为 `61d5fa0`，由 PR #22 合入；main Actions run `30622621533` 五项全绿，包含后端 `668 passed`、前端 19 文件/60 条、三业务固定契约 42/42、Agent 安全恢复 9/9 和真实 Compose 重启恢复。本分支增加 3 条发布/安全契约后，本地专用 pgvector 测试库完整结果为 `671 passed`。 -- 2026-07-27：[PR #8](https://github.com/KXHXK/opercerta/pull/8) 已合并为 `609f8f7`；[main run 30203438564](https://github.com/KXHXK/opercerta/actions/runs/30203438564) 五项门禁全绿，包含完整后端、三业务/Agent 评测和实际 Compose 重启恢复。新版静态专题已从 preview `6a660a8f77aa692302ad00aa` 提升为 production deploy `6a6631d24958714a43ddc508`，线上资源 `index-Ckvsq13U.js` 的 SHA-256 与本地产物一致；上一 production `6a5e0bb5563acf4706a09c0d` 是回滚点。公开站点仍无可写 API；生产 IAM、公网后端、限流、备份、高可用、自动部署和 Release Tag 未完成，门禁 `CLOSED`。下一步进入用户手动演示、源码讲解与面试掌握验收，不启动 ForenTrail。 +本版本发布定义已经正式修订为： -- 2026-07-26 单根 Agent Loop 与业务对象 case 工作台 Task 0–11 已在本地完成。production runtime 仅构造一个根 LangGraph，三业务共享 Model↔MCP Observation 循环、确定性 Policy、HITL、批准后刷新、Kimi Verifier、binding、幂等写入与 readback；历史图只用于回归/等价测试。最终单元 `395 passed`，受影响隔离 PostgreSQL 集成 `32 passed`；Task 9 完整集成 `260 passed`，前端 19 文件 `60 passed` 且 build，Ruff/format/Mypy（85 个源文件）和仓库安全通过；隔离 Compose 三业务、RAG、数据库和 API/MCP 重启恢复通过。少量真实 Moonshot `kimi-k2.6` 的三业务只读、库存批准写入和无效 provider fail-closed 已通过，修复模型/MCP timeout 耦合、thinking/tool-call 不兼容和 Final/Verifier structured output 波动。证据见 `docs/release-evidence/single-root-agent-loop-case-workspace.md`，事故见 `docs/development-log/incidents/2026-07-26-kimi-tool-loop-compatibility.md`。所有修改尚未 commit/push/merge；公网可写后端与生产 IAM/限流/备份/自动发布仍未完成，门禁 `CLOSED`，不启动 ForenTrail。 +> **公开静态展示 + 本地可复现完整 Agent MVP + 录屏。** -- 2026-07-24 已继续收口两项端到端语义：未知后端错误使用固定安全 fallback，不向界面传播原始消息；审批写入成功而后置刷新失败时，UI 保留已提交事实、禁用重复决定并引导 auditor 读取。新鲜门禁为前端 `53 passed` + production build、unit `356 passed`、一次性 pgvector 测试库完整后端 `579 passed in 376.68s`、Ruff/189 文件格式/Mypy 76 个源文件/114 包锁定/仓库安全全绿，以及 Mock release Compose 三业务、Verifier 顺序、数据库事实和 API/MCP 重启恢复退出码 0。Windows `.env.local` 所指测试库未运行且旧凭据在失败 traceback 中再次回显，恢复该库前必须轮换并同步 ignored 配置。本轮修改仍未 commit/push；下一步停在用户审批原子提交，Real Kimi、PR 合并、main Compose 与生产发布未执行，门禁保持 `CLOSED`。 +`Showcase Release gate: AWAITING_OWNER_VALIDATION` -- 2026-07-23 已完成规格一致性审计和本地收口：四份原始设计、三业务修订与 Agent 核心规格对照后确认主线未偏离；前端安全错误 envelope、Verifier/绑定护栏 Trace、安全终态、复审周期、三角色和 FastEmbed 冷/热缓存说明已修复。新鲜门禁为 unit `356 passed`、前端 `51 passed` + production build、Ruff/182 文件格式/Mypy 76 个源文件、Mock Compose 三业务和 API/MCP 重启恢复退出码 0，四服务 healthy。当前修改只在本地工作树，尚未 commit/push；Real Kimi、PR 合并、main Compose 与生产发布未执行。详见 `docs/development-log/audits/2026-07-23-spec-conformance-audit.md`，生产门禁保持 `CLOSED`。 +`Product Release gate: CLOSED` -- 2026-07-23 `feat/agent-core-implementation` 已推送并创建 [Draft PR #8](https://github.com/KXHXK/opercerta/pull/8)。首次 run `29936292055` 暴露 backend-tests 的普通 PostgreSQL 镜像不含 vector extension；按 RED/GREEN 新增 CI 资产契约并提交 `ba53e70 fix: use pgvector in backend CI` 后，最新基线 run `29937375023` 的 repository-safety、python-quality、backend-tests、frontend 全绿。PR 的 `compose-smoke` 按设计跳过；review、合并和 main-only Compose 尚未完成。过程见 `docs/development-log/daily/2026-07-23.md`，生产发布门禁保持 `CLOSED`。 +公开站点是 Netlify 静态专题；本地 Docker Compose 才运行真实 React 控制台、FastAPI、LangGraph、LLM adapter、FastMCP、PostgreSQL/pgvector 与 Redis。不得把当前版本描述为公网交互产品或企业生产系统。 -- 2026-07-23 Agent 核心后续修复：Kimi + RAG replan 改为只暴露尚缺工具，provider/图异常会把 operation 原子收口为固定 `dependency_unavailable`；真实图 probe 已完成 inventory → knowledge → policy。新鲜本地证据为 unit 352 条、关键 Agent 图集成 7 条、Ruff/188 文件格式/Mypy 76 个源文件；Draft PR run `29946792369` 为完整后端 `573 passed`、三业务评测 1 条与 Agent 评测 9/9，四个快速 job 全绿。完整 Compose Real Kimi 仍未稳定通过，最终安全报告为 create operation 503 `dependency_unavailable`。测试 traceback 曾展开的本地数据库凭据已轮换，主仓库与 worktree ignored 配置一致，并由 Windows 原生 `psql` 执行 `SELECT 1` 安全验证。证据见 `docs/release-evidence/agent-core-architecture.md`，生产门禁保持 `CLOSED`。 -- 2026-07-22 Agent 核心 Task 9 已提交为 `642d3ba`：新增 9 类冻结 Agent 轨迹评测、真实 Agent Compose/RAG/数据库/重启验证、CI 门禁和安全 Real 报告。新鲜证据为后端 `566 passed in 179.66s`、前端 17 文件/46 条、Ruff/187 文件格式/Mypy 76 个源文件、Agent 评测 9/9、Compose 三业务与 API/MCP 重启退出码 0。Real Moonshot/Kimi `kimi-k2.6` 新 Agent 代表 query 为 failed，未回退 Mock。证据见 `docs/release-evidence/agent-core-architecture.md`。 +## 已完成的工程范围 -- 2026-07-22 Agent 核心 Task 8 已完成 React 单页 Agent 工作台：有限三业务表单、结构化 Goal、真实 Trace、MCP/RAG 证据、模型建议/确定性计划对照、审批 binding、Verifier 说明、工单回读和 operator→approver→auditor 引导已接入；audit 与 Trace 继续分层。前端 17 个测试文件/46 条测试及生产构建通过；1440/1024/390 浏览器检查无横向溢出，应用内无 fixed/sticky。Task 9 真实 Compose 浏览器 E2E、重启和 Kimi Trace 尚未完成，发布门禁保持 `CLOSED`。证据见 `docs/release-evidence/agent-workspace.md`。 +- 库存不足、设备异常、作业阻塞三业务闭环。 +- 单根 LangGraph Agent Loop、LLM 有界规划、MCP 工具调用、RAG SOP、审批中断与恢复。 +- 最新事实复核、审批竞态控制、幂等工单、数据库后置断言与重启恢复。 +- FastAPI/JWT/RBAC/SSE、React Case 工作台、Agent Trace、审计与指标埋点。 +- 固定评测、仓库安全、Python 质量、前端和 Compose main-only 门禁。 +- 公开静态页面、可回滚的历史 Showcase 预发布和完整开发/学习资料。 -- 2026-07-22 Agent 核心 Task 7 已完成：`0006_agent_trace`、run/event/citation 持久化、稳定序列与语义去重、递归脱敏、真实 LangGraph 调查/审批/执行/反馈投影、RAG citation reference、Trace snapshot/SSE API 和 operation 级 RBAC 均已接入。产品代码全量测试 `545 passed`；最新 RBAC 补强后 Task 7 定向 `8 passed`，WSL Git 安全 `4 passed`。失败 traceback 展开的 Windows 本地测试凭据已轮换；Windows 原生 PostgreSQL 无 pgvector，因此 Task 6 之后的完整集成门禁使用 Compose pgvector。Task 8 Agent 工作台与 Task 9 完整 Compose/真实模型 Trace 尚未完成，发布门禁保持 `CLOSED`。证据见 `docs/release-evidence/agent-trace-rbac.md`。 +## 本轮收口修改 -- 2026-07-22 Agent 核心 Task 6 已完成本地代码与真实检索证据：`0005_agent_knowledge`、pgvector 512 维/HNSW、三份合成中文 SOP、FastEmbed、MCP `knowledge.search_sop`、场景/版本过滤、0.5 最小分数、LangGraph citations、可选降级与强制失败关闭均已接入。新建空卷容器网络聚焦 `75 passed`、产品 `535 passed`、WSL Git 安全 `4 passed`，Ruff/173 文件格式/mypy 73 个源文件/114 包锁定依赖/安全扫描通过；真实三场景入库、幂等 replay 与代表查询已完成。空卷门禁修复了迁移测试依赖预迁移数据库的隐式前置条件。新镜像构建和启动健康已观察；额外完整 Compose smoke 因 Codex 自动化 WSL 会话外层在约 43--49 秒停止 Docker service 未完成，留待 Task 9 在稳定交互式终端重跑。Task 7 Agent Trace/API/SSE/RBAC 未实施，生产门禁保持 `CLOSED`。证据见 `docs/release-evidence/agent-pgvector-rag.md`。 +- 新增 Apache-2.0 `LICENSE`。 +- Dockerfile 的 uv 固定为本地/CI 同版 `0.11.28`。 +- 仓库安全扫描覆盖双语 README、双语 CONTRIBUTING、handoff 和文档索引。 +- 新增双门禁修订规格、实施计划和本人掌握验收表。 +- 当前状态不再堆叠历史快照；历史仍保存在 daily 与 release evidence。 -- 2026-07-20 零成本求职展示与本地工程详解 Task 1--8 已完成：PR #6 以 merge commit `e483665` 合并，`main` run `29738863357` 的 repository-safety、python-quality、frontend、backend-tests、compose-smoke 全部通过。OperCerta production deploy `6a5e0bb5563acf4706a09c0d` 与作品集 production deploy `6a5e1b8824ba2290cf63c897` 均已完成 HTTP/浏览器核验；作品集四项目顺序、三业务文案、技术栈、联系方式和专题入口正确，桌面/移动端无横向溢出或 fixed/sticky 元素。公开页面仍为只读静态展示，公网可写后端未部署，生产门禁保持 `CLOSED`。证据见 `docs/release-evidence/zero-cost-showcase-engineering-walkthrough.md`。 +## 下一执行顺序 -- 2026-07-20 已完成用户授权的 Moonshot AI `kimi-k2.6` 三业务代表性验证：每个业务执行 1 条 query 与 1 条批准路径，共 6 个 operation、3 条真实模型解释路径，三种唯一工单均落库。实现提交 `b517ab8`；随后完整后端 `429 passed in 110.61s`、Ruff/138 文件格式/mypy 62 个源文件/92 个锁定包/安全扫描通过，Mock release Compose 新鲜退出码 0。报告不保存模型原文，adapter 未暴露 token/cost usage，因此不估算。公网交互 HTTPS、生产治理、用户掌握、当前远程 CI 与 Release Tag 仍未完成，生产门禁保持 `CLOSED`。证据见 `docs/release-evidence/real-model-representative-validation.md`。 +1. 跑定向门禁与完整 Python/前端/Compose 检查。 +2. 提交、推送、创建 PR，等待所有检查通过后合入 main。 +3. 在 main 上复跑 Compose smoke，更新最终提交、run 和测试数字。 +4. 由项目所有者亲自执行 `docs/learning/opercerta-ownership-acceptance.md`；必须记录 `operation_id`、`work_order_id`、Trace、审计序列和数据库事实，**不得由 Codex 自动代签**。 +5. 完成 3–5 分钟录屏与口述复盘后，才能把 Showcase 门禁改为 `PASSED` 并创建最终 tag。 -- 2026-07-20 三业务主计划 Task 8 本地发布候选阶段：提交 `a3994ef` 新增 Caddy/React 多阶段镜像、内部服务不暴露端口的 release Compose、一键三业务/重启 smoke、三份中文学习材料，以及设备审批哈希稳定性和代理非 JSON 故障窗口修复。该检查点后端 `422 passed in 94.96s`，Ruff/136 文件格式/mypy 62 个源文件/锁定依赖/安全扫描通过；前端 12 文件/25 条测试与构建通过；release smoke 退出码 0、70.8 秒。当时真实模型尚未验证，现已由上条独立证据补齐；公网交互 HTTPS、生产治理、用户掌握、当前远程 CI 和 Release Tag 仍未完成，生产门禁保持 `CLOSED`。证据见 `docs/release-evidence/three-business-release.md`。 +## 本地运行入口 -- 2026-07-20 三业务主计划 Task 7 已完成本地证据：固定套件 42/42 通过；Compose 三业务与 API/MCP 重启恢复通过；2×2 矩阵 60/60 个 query completed、零错误。缓存关闭每场景 10 次 MCP/0 hit，开启为 2 次 MCP/8 hit；最终总门禁 414 passed，锁文件/Ruff/134 文件 format/mypy 62 个源文件/安全扫描通过。每格仅 5 次，不作生产性能承诺。证据见 `docs/release-evidence/three-business-evaluation-compose.md`。Task 8 与发布门禁仍未完成。 +```bash +cd /mnt/d/CODEX/agent-portfolio/opercerta +docker compose up --build -d --wait +curl http://127.0.0.1:8080/health/ready -- 2026-07-20 三业务主计划 Task 6 已完成代码与本地测试：Redis 只缓存初次/查询证据并在故障时旁路，批准后复核直连 MCP；OpenTelemetry 关联 API、LangGraph、MCP、Redis 和 PostgreSQL；严格 OpenAI-compatible adapter 最多两次尝试且真实模式失败不回退 Mock。Task 7 随后已验证 Redis 8.8 Compose、跨业务评测和缓存矩阵；真实模型代表性调用仍待 Task 8，发布门禁保持关闭。 -- 2026-07-19 作品集已完成单页视觉刷新并生产替换：无内部 hash 导航，四项目按 OperCerta、ForenTrail、SiteVerum、Federune 排列，后三项明确未启动；邮箱、用户明确授权公开的手机号和 public GitHub 已接入。production deploy `6a5c986587eaef5b3156f49b` 返回 200。源契约 3/3、镜像契约 8/8 及真实构建/导出通过。 -- 2026-07-19 公开专题功能工作树最终本地门禁通过：后端 `342 passed in 65.94s`、Ruff clean、105 文件 format check、mypy 50 个源文件、仓库安全扫描、前端 11 文件/24 条测试和 Vite 构建均通过。首次门禁在后端通过后因测试文件多余空行触发 Ruff `I001`，最小修复后从头重跑整条门禁。PR #4 run `29652818349` 四个快速 job 成功并合并为 `0f262e0`；main run `29652991288` 五个 job（含 Compose smoke、API/MCP 重启恢复与清理）全部成功。原 release gate 仍为 `CLOSED`。 -- 2026-07-18 已将不连接后端的 OperCerta 静态专题生产部署到 。专题资源与静态回退均已核验；个人作品集随后于 2026-07-19 完成独立 Netlify 部署和单页刷新。公开页面只展示合成数据证据，不改变生产 IAM、HTTPS 后端、自动部署和公开 API 的未完成边界。 -- 2026-07-18 建立 `KXHXK/opercerta` 与分层 GitHub Actions；仓库已于 2026-07-19 由用户改为 public。历史 PR/main Actions 证据仍有效。当前 main branch protection 尚未配置，保护端点返回 404；配置前必须继续执行人工 PR 全绿后合并规则。 -- 2026-07-18 已完成可观测性与安全回归基础：FastAPI `0.139.2`、服务端 request_id、异常后上下文清理、安全 JSON 日志、应用级低基数 Prometheus 指标、SSE 实际回放计数和默认关闭的 `/metrics`。完整后端门禁为 `332 passed in 74.58s`，Ruff、100 文件 format check、mypy 50 个源文件通过；证据见 `docs/release-evidence/observability-security-regression.md`。发布门禁仍为 `CLOSED`。 +cd web +npm ci +npm run dev +``` -- 2026-07-18 已完成本地单页运营控制台：React/Vite、内存 JWT、创建/读取/审批编排与 fetch SSE 审计快照回放。前端门禁为 9 个测试文件、15 个测试通过，构建通过；证据见 `docs/release-evidence/single-page-console.md`。这不是生产身份、完整浏览器端到端或公开发布验证。 +打开 。公开站点为 ，仅作静态展示。 -- 书面设计已经总审通过并冻结为实施基线；当前文档目录见根目录 `DOCUMENT_INDEX.md`。 -- 可靠性内核 Task 1–6 已完成本地总门禁；Task 6 新鲜完整测试为 `116 passed`，迁移 downgrade→upgrade 后集成测试为 `39 passed`，Ruff/format/mypy 通过。总证据见 `docs/release-evidence/reliability-kernel.md`。 -- Windows 原生 PostgreSQL 18.4 已验证为本地集成测试数据库：服务仅监听 `127.0.0.1:55432`，普通 IPv4 回环使用 SCRAM；证据见 `docs/release-evidence/native-postgres-environment.md`。 -- 审批原子性证据见 `docs/release-evidence/approval-atomicity.md`。曾被失败 traceback 展开的本地测试角色密码已轮换并复验；新值不得粘贴到对话或写入 Git。 -- Task 4 已按聚焦计划完成：领域契约 `6f99bf6`、共享数据库 fixture `8408f81`、幂等 Repository 与并发测试 `88c014c`；证据见 `docs/release-evidence/work-order-idempotency.md`。 -- Task 5 已完成五个原子实现提交：快照领域边界 `8fb054e`、operation 原子状态仓储 `5bdacf7`、独立 checkpointer `e9b2834`、JSON-only reliability graph `2e6cbb4`、RecoveryCoordinator 与四点 A/B 重启矩阵 `e93b551`。证据见 `docs/release-evidence/langgraph-restart-recovery.md`。 -- Task 5 最终完整测试为 `116 passed`，重启矩阵十个独立 Pytest 进程实测 `10/10`；Ruff、format 和 mypy（19 个源文件）通过。这些是本地验证，不是生产指标。 -- checkpointer 首次连接失败 traceback 展开了当时的本地测试角色密码；代码、Git 和文档未保存该值，封装已改为无密码 DSN + 临时 `PGPASSWORD`。用户已同步轮换 PostgreSQL 角色密码与 `.env.local`，轮换后 focused checkpointer 回归新鲜 `4 passed`。 -- 后续采用风险分级复核：用户决定产品范围、成本、外部账号和发布；内部技术细节由 Codex 以 TDD、静态检查和证据负责。进度必须区分可靠性内核与完整发布范围。 -- 当前 Git 已配置 `origin` 为 public `KXHXK/opercerta`，本地 `main` 跟踪 `origin/main`；禁止 force push、删除远程历史或未经全绿 PR 直接合并。 -- 发布门禁保持 `CLOSED`，不启动 ForenTrail 或其他项目。 -- 首个纵向业务闭环已确定为“库存不足 → 补货工单”；设计见 `docs/superpowers/specs/2026-07-16-inventory-replenishment-vertical-slice-design.md`，可执行计划见 `docs/superpowers/plans/2026-07-16-inventory-replenishment-vertical-slice.md`。 -- 库存补货 Task 1–7 已完成。Task 7 实现提交为 `9b830d2`：批准后重新读取库存与规则、比较审批绑定事实、幂等创建工单、写后读验证、拒绝终止、审批过期扫描、`OperationRunner` 和补货专用恢复协调器。 -- Task 7 新鲜门禁为完整测试 `275 passed in 43.78s`、Ruff clean、60 文件 format check、mypy 检查 32 个源文件通过；A/B 重启矩阵额外串行重复 10 次，每次 `7 passed`。证据见 `docs/release-evidence/replenishment-execution-restart.md`，这些不是生产成功率或 SLA。 -- Task 8 实现提交为 `c4ac3ab`：新增严格 FastAPI 模型、三条 `/api/v1/operations` 路由、固定中文安全错误 envelope、OpenAPI 非可信 actor 声明和从环境构造的生产 lifespan。 -- Task 8 API focused 为 `8 passed`；MCP + workflow + API 回归为 `55 passed`；提交前完整测试为 `283 passed in 55.73s`，Ruff clean、65 文件 format check、mypy 检查 35 个源文件通过。 -- 生产 lifespan 不自动运行迁移或 checkpointer `setup()`；启动执行一次 `recover_all()`，关闭释放 checkpointer 与 Engine，并在 Engine 构造失败时恢复原 `PGPASSWORD`。 -- Task 9 本地总门禁已执行：初始完整测试 `283 passed in 57.94s`，文档完成后提交前复验 `283 passed in 56.41s`；锁定依赖、Ruff、68 文件 format check、mypy 35 个源文件均通过。 -- secret-safe 迁移完成 `0001_reliability_kernel → 0002_inventory_replenishment (head)`，迁移后集成测试 `131 passed in 55.39s`。 -- 审批十路竞态独立重复 `10/10`；A/B 重启恢复独立重复 `10/10`，每轮 `7 passed`。这些只是本地重复证据。 -- 真实 FastMCP、FastAPI 和独立客户端三进程闭环通过：四工具名称匹配，创建进入 `awaiting_approval`，批准后 `completed`，重复审批 `409`，数据库一条审批、一条工单且终态审计顺序正确。证据见 `docs/release-evidence/inventory-replenishment-vertical-slice.md`。 -- Windows Uvicorn 0.51 默认 Proactor loop 与 Psycopg async 不兼容；真实服务验证使用 Uvicorn custom loop factory 明确选择 Selector loop。Linux/Docker Compose 已完成本地单节点验证，但未形成生产高可用承诺。 -- Docker/Linux 运行时已修订为 WSL2、Ubuntu 26.04 LTS；不使用 Docker Desktop、Hyper-V VM。因 Docker 厂商 APT 源 TLS 被当前网络重置，经用户确认安装 Ubuntu 官方签名仓库的 Docker Engine `29.1.3`、Compose `2.40.3` 与 Buildx `0.30.1`。Docker Hub 直连超时后，经用户授权配置三个实测可达的第三方 registry mirror。OperCerta Compose 的构建、健康、真实审批工单数据库断言和 API/MCP 重启恢复已通过；完整证据见 `docs/release-evidence/docker-linux-runtime.md`，发布门禁仍关闭。 +## 自动化门禁 -## 新对话必须先做 +```bash +uv sync --frozen --all-groups +uv run ruff check . +uv run ruff format --check . +uv run mypy src +uv run pytest -q +uv run python scripts/run_opercerta_evaluation.py +uv run python scripts/run_agent_evaluation.py -1. 先阅读 `DOCUMENT_INDEX.md`、`docs/development-log/current-state.md` 和最近每日日志，再阅读相关设计、计划、交接和 Git 状态。 -2. 只实施 OperCerta；PR #18、最新 main Compose、静态 production 与 `v0.1.0-showcase.1` Showcase 预发布已全绿。下一步完成源码掌握、完整实演、3–5 分钟录屏和简历材料；产品生产门禁关闭前不把静态展示误报为生产系统。 -3. 运行集成测试前，以不回显方式从已忽略 `.env.local` 加载 `OPERCERTA_DATABASE_URL`；不得提交该文件或任何凭据。 -4. 每个效果数字都保留基线、测试数据、测量脚本和结果证据；指标未测出前使用目标值或空值，不写成已实现结果。 -5. 使用公开或合成数据，从零编写全部代码和文档，不导入任何原单位源码、数据、截图、模型、品牌或内部规则。 +cd web +npm ci +npm run test:run +npm run build +``` -## 第一阶段完成条件 +Compose 的三业务数据库副作用和重启恢复由 CI 的 main-only `compose-smoke` 与仓库验证脚本证明。不得用“配置可解析”代替真实启动/恢复证据。 -- 非法输入、状态恢复、审批竞态和幂等写入测试先于对应实现并可重复运行。 -- 最小纵向闭环能够在本地 PostgreSQL 环境运行，失败路径和人工接管路径可演示；Linux/Docker 一致性验证在发布门禁阶段完成。 -- README、架构图、接口说明、评测报告、部署与回滚说明随实现同步更新。 -- 通过详细设计中的发布门禁后，再部署公开演示、填写在线地址并开始 ForenTrail。 +## 未关闭范围 -## 可复制到新对话的启动语 +公网 FastAPI、生产 IAM、限流与防滥用、托管密钥、数据库备份/恢复演练、高可用、线上观测后端与告警均未实现，因此 Product Release gate 必须保持 `CLOSED`。这些不是本轮 Showcase 的阻塞项，但若未来改为公网交互产品，必须重新开规格和产品门禁。 -> 工作目录为本 OperCerta 仓库根目录。请先读取 `DOCUMENT_INDEX.md`、`docs/development-log/current-state.md`、最近每日日志、`README.md`、`IMPLEMENTATION_HANDOFF.md`、`docs/specs/` 下的四份设计文件及当前相关规格、计划和证据；PR #18 已合并为 main `298fc59`，main run `30541088053` 五项全绿并包含 667 条后端测试、三业务数据库副作用和重启恢复；Netlify 静态 production deploy `6a6b17cf496c38056f737264` 已通过安全头和资源哈希核验，Showcase 预发布 `v0.1.0-showcase.1` 精确指向该已验证提交。下一步只继续源码掌握、完整实演、3–5 分钟录屏和简历材料。公开根路径只读、`/engineering` 仅 localhost、`/console` 仅本地真实演示；不复用旧公司材料，不虚构指标，不把静态展示误报为生产系统。 +ForenTrail 暂不启动；FieldPilot 等 OperCerta 完成并由本人掌握后再作为独立项目推进。 + +## 新任务恢复提示 + +> 工作目录是 `D:\CODEX\agent-portfolio\opercerta`。先完整读取 `README.md`、`IMPLEMENTATION_HANDOFF.md`、`docs/development-log/current-state.md`、`DOCUMENT_INDEX.md` 核心阅读表、四份 `docs/specs/` 设计文件，以及 2026-07-31 Showcase 门禁修订规格、实施计划和本人验收表。只实施 OperCerta 收口；公开站点是静态展示，完整 Agent MVP 在本地 Compose 复现，Product Release gate 保持关闭。完成自动化门禁后必须等待项目所有者本人实演、讲解和录屏，不得代签掌握验收，也不启动 ForenTrail。 diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..97ea261 --- /dev/null +++ b/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2026 KXH + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 51eb5d1..3e3b594 100644 --- a/README.md +++ b/README.md @@ -33,11 +33,11 @@ equipment incidents, and blocked operational tasks. It combines bounded LLM reasoning with deterministic policy, human approval, durable workflow state, and idempotent business writes. -> **Development status:** the complete three-business workflow runs locally in -> a single-node Docker Compose environment. The public project page is static -> and does not expose the API or database. **Not production-ready:** production -> identity, public ingress, rate limiting, backups, high availability, and -> automated deployment are not implemented. +> **Release scope:** this version is a **public static showcase + locally +> reproducible complete Agent MVP + recording**. The public page does not expose +> the API or database. It is not a public interactive product or a production +> deployment. Production identity, public ingress, rate limiting, backups, high +> availability, and automated deployment are not implemented. ## Why OperCerta @@ -178,7 +178,7 @@ latency, cost, or SLA claim. | Gate | Current verified result | | --- | ---: | -| Backend suite | 667 tests passed | +| Backend suite | 671 tests passed | | Frontend suite | 19 test files, 60 tests passed | | Three-business fixed contracts | 42/42 passed | | Frozen Agent safety and recovery evaluation | 9/9 passed | @@ -234,7 +234,9 @@ docs/ Technical guides, development records, and release evidence - [Core technical guide](docs/learning/opercerta-core-technical-guide.md) - [Manual experiment guide](docs/learning/opercerta-manual-experiment-guide.md) +- [Owner acceptance guide](docs/learning/opercerta-ownership-acceptance.md) - [Current implementation state](docs/development-log/current-state.md) +- [Showcase release gate definition](docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md) - [Single-root Agent loop evidence](docs/release-evidence/single-root-agent-loop-case-workspace.md) - [GitHub Actions evidence](docs/release-evidence/github-actions-ci.md) @@ -248,6 +250,14 @@ Completed locally: - fixed contract/evaluation suites and main-branch Compose recovery evidence; - read-only public project page and a reproducible pre-release. +Current gate state: + +- engineering and local automated gate: `PASSED`; +- Showcase Release gate: `AWAITING_OWNER_VALIDATION` until the owner completes + the manual walkthrough, source explanation, recovery/idempotency experiment, + and 3–5 minute recording; +- Product Release gate: `CLOSED`. + Open work before a production deployment: - production identity and authorization lifecycle; @@ -260,3 +270,7 @@ Open work before a production deployment: See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, quality gates, pull-request expectations, and Agent safety rules. + +## License + +Licensed under the [Apache License 2.0](LICENSE). diff --git a/README.zh-CN.md b/README.zh-CN.md index 9c7ea83..bb9f47e 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -32,8 +32,8 @@ OperCerta 是一个面向库存短缺、设备异常和作业阻塞的受控、 Agent。它把有边界的大模型推理与确定性规则、人工审批、持久化工作流状态和 幂等业务写入组合成完整闭环。 -> **开发状态：** 三业务完整流程可以在本地单节点 Docker Compose 环境中运行。 -> 公开项目页面为纯静态页面，不连接 API 或数据库。项目**尚未达到生产就绪**： +> **发布范围：** 当前版本定义为“**公开静态展示 + 本地可复现完整 Agent MVP + +> 录屏**”。公开页面不连接 API 或数据库；它不是公网交互产品，也不是生产部署。 > 生产身份、公网入口、限流、备份、高可用和自动部署仍未实现。 ## 项目背景 @@ -166,7 +166,7 @@ provider fail-closed。该小样本只证明 provider 兼容性，不代表模 | 门禁 | 当前已验证结果 | | --- | ---: | -| 后端测试 | 667 条通过 | +| 后端测试 | 671 条通过 | | 前端测试 | 19 个测试文件、60 条用例通过 | | 三业务固定契约 | 42/42 通过 | | 冻结 Agent 安全与恢复评测 | 9/9 通过 | @@ -221,7 +221,9 @@ docs/ 技术指南、开发记录和发布证据 - [核心技术手册](docs/learning/opercerta-core-technical-guide.md) - [手动实验手册](docs/learning/opercerta-manual-experiment-guide.md) +- [项目所有者掌握验收](docs/learning/opercerta-ownership-acceptance.md) - [当前实施状态](docs/development-log/current-state.md) +- [Showcase 发布门禁定义](docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md) - [单根 Agent Loop 实施证据](docs/release-evidence/single-root-agent-loop-case-workspace.md) - [GitHub Actions 证据](docs/release-evidence/github-actions-ci.md) @@ -235,6 +237,13 @@ docs/ 技术指南、开发记录和发布证据 - 固定契约/评测以及 main 分支 Compose 恢复证据； - 只读公开项目页面和可复现预发布版本。 +当前门禁状态： + +- 工程与本地自动化门禁：`PASSED`； +- Showcase Release gate：`AWAITING_OWNER_VALIDATION`，必须由项目所有者亲自完成 + 业务实演、源码讲解、恢复/幂等实验和 3–5 分钟录屏； +- Product Release gate：`CLOSED`。 + 生产部署前仍需完成： - 生产身份和授权生命周期； @@ -247,3 +256,7 @@ docs/ 技术指南、开发记录和发布证据 开发环境、质量门禁、Pull Request 要求和 Agent 安全规则见 [CONTRIBUTING.md](CONTRIBUTING.md)。 + +## 许可证 + +本项目采用 [Apache License 2.0](LICENSE)。 diff --git a/docs/development-log/audits/2026-07-31-spec-release-readiness-audit.md b/docs/development-log/audits/2026-07-31-spec-release-readiness-audit.md index 8b6a943..36267ac 100644 --- a/docs/development-log/audits/2026-07-31-spec-release-readiness-audit.md +++ b/docs/development-log/audits/2026-07-31-spec-release-readiness-audit.md @@ -1,127 +1,98 @@ # OperCerta 规格一致性与发布就绪审计（2026-07-31） -## 结论 - -OperCerta 当前实现与“受控单 Agent + 三业务共享可靠性内核”的有效设计主线一致， -没有退化为普通 CRUD 工单系统，也没有偏离为自由聊天或多 Agent 角色讨论。库存补货、 -设备维修和作业异常恢复共享同一条生产 LangGraph 生命周期，并真实接入 LLM 决策、 -FastMCP 工具、pgvector SOP 检索、人工审批、批准后复核、幂等写入、PostgreSQL 事实、 -Redis 只读缓存、Agent Trace 和重启恢复。 - -当前已经达到“公开源码 + 静态项目页 + 可重复本地单节点完整 Agent MVP”的发布状态， -尚未达到“公网可交互产品”或“企业生产系统”状态。静态 Netlify 页面可以公开访问，但 -`/api/*` 返回静态 SPA HTML；真实 FastAPI、MCP、PostgreSQL 和 Redis 只在本地/CI 与 -release Compose 中运行。 - -## 核验依据与优先级 - -1. 命名基线：`docs/specs/2026-07-14-agent-project-naming-design.md`。 -2. 总体基线：`docs/specs/ai-agent-portfolio-overall-design.md`。 -3. 组合基线：`docs/specs/2026-07-14-agent-portfolio-design.md`。 -4. OperCerta 原始详细设计：`docs/specs/2026-07-14-opercerta-design.md`。 -5. 有效修订：三业务发布、Agent 核心架构、异常信号收件箱、信号对账与后继调查、 - 单根 LangGraph Agent Loop 与 case 工作台规格。 -6. 当前事实：源码、锁文件、迁移、Compose、CI、固定评测、真实模型代表报告和本审计 - 当日运行结果。后来的明确修订优先于早期设计中被修订的范围，运行事实不由文档状态 - 代替。 +## 审计结论 + +OperCerta 当前实现与“受控单 Agent + 三业务共享可靠性内核”的有效设计主线一致。库存补货、设备维修和作业恢复共享同一条生产 LangGraph 生命周期，并接入 LLM 有界决策、FastMCP 工具、pgvector SOP 检索、人工审批、批准后复核、幂等写入、PostgreSQL 事实、Redis 只读缓存、Agent Trace 和重启恢复。 + +本次正式将当前版本定义为： + +> **公开静态展示 + 本地可复现完整 Agent MVP + 3–5 分钟录屏。** + +因此，原始详细设计中“线上地址跑通真实业务”的要求仍属于 Product Release，不能用静态 Showcase 冒充；但它不再阻塞本次 Showcase Release。修订依据见 `docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md`。 + +## 当前门禁 + +| 门禁 | 状态 | 剩余条件 | +| --- | --- | --- | +| 工程与本地自动化 | `PASSED` | 本收口分支合并后补录新鲜 main CI/Compose 结果 | +| Showcase Release | `AWAITING_OWNER_VALIDATION` | 本人完整实演、源码讲解、恢复/幂等验证和录屏 | +| Product Release | `CLOSED` | 公网可写后端及完整生产治理未实现 | + +## 核验依据 + +1. `docs/specs/2026-07-14-agent-project-naming-design.md`。 +2. `docs/specs/ai-agent-portfolio-overall-design.md`。 +3. `docs/specs/2026-07-14-agent-portfolio-design.md`。 +4. `docs/specs/2026-07-14-opercerta-design.md`。 +5. 三业务发布、Agent 核心架构、异常信号收件箱、信号对账、单根 Agent Loop 等后续已批准修订。 +6. 当前源码、锁文件、迁移、Compose、固定评测、CI、真实模型代表报告和本机运行事实。 + +后来的明确修订优先于早期被修订条款；测试或文档不能代替真实运行证据。 ## 设计—实现映射 -| 设计要求 | 当前实现证据 | 结论 | +| 设计要求 | 当前实现 | 结论 | | --- | --- | --- | -| 库存、设备、作业三业务 | scenario registry、三类 signal detector、三类策略和工单 payload | 一致 | -| 有限输入而非自由聊天 | React 三业务表单、严格 Pydantic Goal/Intent、对象和动作 allowlist | 一致；这是后续 Agent 规格对早期“自然语言请求”的安全收敛 | -| 单 Agent Plan-and-Execute | `ControlledAgentRootGraph`、Model → Tool Policy → MCP Observation → Model 有界回环 | 一致 | -| LangGraph 唯一生命周期所有者 | production factory 只构造受控根图；同一 thread/checkpoint 覆盖审批、复核、写入和终态 | 一致；历史场景图只保留回归与等价测试 | -| MCP 工具调用 | FastMCP 注册库存、设备、任务、策略、SOP、工单创建和工单查询共 7 个类型化工具 | 一致；原始 5 工具先由三业务修订扩展，再由 Agent/RAG 修订增加知识工具 | -| RAG 与 Memory | FastEmbed、pgvector 512 维向量、HNSW、版本化合成 SOP、citation；checkpoint/业务事实/知识分层 | 一致；RAG 不提供权威数量和权限 | -| 人工审批和批准后复核 | JWT/RBAC、绑定哈希、PostgreSQL 行锁、fresh-fact cache bypass、模型 Verifier、重新审批 | 一致 | -| 幂等与重启恢复 | 唯一幂等键、写后读、PostgreSQL checkpointer、业务表主导 recovery、API/MCP restart smoke | 一致 | -| API 与前端 | FastAPI 安全 envelope、health、operation/signal/case/trace/SSE API；React case 工作台和局部状态 | 本地一致；公网 API 未部署 | -| 数据与基础设施 | PostgreSQL 18/pgvector、8 个 Alembic 迁移、Redis 8.8、Docker Compose、Caddy | 本地和 CI 一致 | -| 可观测性 | request/operation/thread/tool/trace 关联、JSON 日志、OpenTelemetry、Prometheus、Agent Trace/audit 分层 | 代码与测试一致；公开环境没有 collector、dashboard 或告警 | -| 测试与评测 | 667 条后端、19 文件/60 条前端、42/42 三业务契约、9/9 Agent 安全恢复、main Compose | 已有可重复证据；均不是生产 SLA 或独立准确率 | - -## 原始设计与当前实现的合理变化 - -- 原始详细设计只具体化库存和设备，2026-07-20 三业务修订正式补齐作业异常。因此当前 - 三业务不是范围膨胀或偏差，而是对总体设计缺口的已批准修复。 -- 原始 MCP 清单为 5 个工具；任务工具和 `knowledge.search_sop` 分别由三业务与 Agent - 核心/RAG 规格增加，当前 7 工具与有效设计一致。 -- 原始描述允许自然语言请求，后续规格把产品入口收敛为有限表单和受控 Goal。LLM 仍在 - 根图内完成语义/规划、工具选择、Observation 后续决策和批准后 Verifier，不需要通过 - 无边界聊天框证明 Agent 属性。 -- 早期证据文档记录了当时查询路径不调用模型、旧图或尚未发布等历史事实；当前运行事实 - 以单根 Agent Loop 证据、`current-state.md` 顶部和最新 main CI 为准。历史记录不能被 - 反向解释为当前架构。 - -## 当日新鲜验证 - -- GitHub PR #20 已合并为 main `764f4b5`，main Actions run `30614799180` 五项成功： - repository safety、Python quality、完整 backend、frontend、真实 Compose restart/recovery。 -- 本分支 README/CONTRIBUTING/文档索引定向测试：`14 passed`。 -- GitHub 原生 README 不支持 JavaScript/CSS 标签页。最终采用标准 - `English｜简体中文` 双文件互链，README/CONTRIBUTING 每个页面只显示一种语言， - 不使用 `
` 折叠框；两种语言的结构和事实由自动化测试约束。 -- `https://opercerta-kxh.netlify.app/`、`/console` 和 `/api/v1/auth/demo-token` 均返回 - `200 text/html`；最后一项再次证明公网是静态 SPA，不是 API。 -- 本机 `opercerta-demo` PostgreSQL、Redis、MCP、API 四容器 healthy；readiness 返回 - database/checkpoint/MCP 全部 ready。 -- `docker compose -f compose.release.yaml config --quiet` 通过，说明发布拓扑配置可解析； - 它不等同于公网环境、备份、容量或安全验收。 - -## 尚存问题与优先级 - -### P0：公网交互或生产上线前必须完成 - -- 部署真实 HTTPS FastAPI 后端，并配置与前端完全匹配的 CORS 和公开入口。 -- 用生产身份系统替换本地 demo JWT 签发；补齐身份生命周期、最小权限和会话吊销。 -- 增加限流、配额、模型费用熔断、防滥用、托管密钥和安全数据重置。 -- 使用托管/受维护的 PostgreSQL，完成备份、恢复演练、迁移编排和故障回滚。 -- 部署日志/Trace/指标采集、dashboard 和告警；当前只有埋点与本地测试。 -- 增加公网端到端、浏览器 CORS、超时、并发和失败恢复验收。 - -### P1：优质公开仓库建议补齐 - -- 当前 GitHub community profile 为 42%；缺少明确 `LICENSE`、`SECURITY.md`、 - Code of Conduct、Issue/PR 模板。 -- main 分支尚未启用 branch protection；目前依靠人工坚持 PR 全绿后合并。 -- 缺少独立 ADR 目录；架构取舍存在于规格和技术手册中，但不利于外部贡献者快速定位。 -- 当前真实模型只做少量代表调用，adapter 又没有供应商 usage，不能给出准确率、Token、 - 成本或 SLA 结论。 - -### P2：增强可信度而非阻塞本地 MVP - -- 增加独立人工标注的业务质量集和多次真实模型运行，报告失败样本与方差。 -- 增加 Playwright 类完整浏览器 E2E、无障碍和 Lighthouse 证据。 -- 为容器基础镜像增加 digest/供应链更新策略，为公开部署增加 SBOM 或漏洞扫描。 - -## 发布与作品使用结论 - -| 使用方式 | 当前结论 | 允许表述 | +| 库存、设备、作业三业务 | scenario registry、三类 detector、策略和工单 payload | 一致 | +| 有限输入而非自由聊天 | React 表单、Pydantic Goal/Intent、对象/动作 allowlist | 一致，符合受控业务边界 | +| 单 Agent Plan-and-Execute | `ControlledAgentRootGraph` 与 Model → Tool → Observation 有界回环 | 一致 | +| LangGraph 生命周期 | 同一 thread/checkpoint 覆盖调查、审批、复核、写入和终态 | 一致 | +| MCP 工具 | 7 个类型化事实、规则、知识和工单工具 | 一致；写工具受策略和审批约束 | +| RAG 与 Memory | FastEmbed、pgvector、SOP citation；checkpoint/事实/知识分层 | 一致；检索不提供权威数量或权限 | +| 审批与复核 | JWT/RBAC、绑定哈希、行锁、cache bypass、Verifier | 一致 | +| 幂等与恢复 | 幂等键、唯一约束、写后读、PostgreSQL checkpointer | 一致 | +| 前后端 | FastAPI 安全边界、React Case 工作台、SSE/Trace/审计 | 本地一致；公网 API 未部署 | +| 基础设施 | PostgreSQL 18/pgvector、Redis、Docker Compose、Caddy | 本地与 CI 一致 | +| 可观测性 | 关联 ID、结构化日志、OpenTelemetry、Prometheus | 代码/测试具备；无公网 collector/dashboard | +| 测试评测 | 本分支后端 671、前端 60、三业务 42/42、Agent 9/9、Compose | 后端为一次性 pgvector 库本地结果；最终 main 仍需 CI 复核；不是生产 SLA | + +## 合理设计演进 + +- 三业务修订补齐了原始详细设计对作业阻塞的缺口，不是无审批扩展。 +- MCP 从原始 5 个工具扩展为 7 个，是任务事实与 SOP 检索规格的明确结果。 +- 入口从自由自然语言收敛为有限业务表单；LLM 仍负责图内语义、规划、Observation 后决策和批准后 Verifier。 +- 生产图统一为单根 Agent Loop；历史场景图只承担回归和等价测试。 + +## 已验证事实 + +- 收口前最新 main 为 `61d5fa0`，PR #22 和 Actions run `30622621533` 五项成功。 +- 收口前 main 为后端 668；本分支新增 3 条门禁契约后，本地一次性 pgvector 测试库结果为 `671 passed in 112.07s`。前端 19 文件/60 条、三业务 42/42、Agent 9/9、Compose 数据库副作用及 API/MCP 重启恢复此前均通过，等待本分支最终复验。 +- Netlify 根路径与 `/api/*` 都是静态 SPA，证明公网未暴露 FastAPI。 +- 本机 `opercerta-demo` 的 PostgreSQL、Redis、MCP、API 四服务 healthy，readiness 的 database/checkpoint/MCP 均 ready。 +- README/CONTRIBUTING 使用标准 `English｜简体中文` 双文件互链；GitHub Markdown 不支持无跳转、无折叠且只显示一种语言的自定义状态切换。 + +## 本轮已解决的公开仓库缺口 + +- 新增 Apache-2.0 `LICENSE`。 +- Dockerfile uv 与本地/CI 统一为 `0.11.28`。 +- 仓库安全扫描扩展到双语公开文档、handoff 和索引。 +- 用双门禁修订消除“静态 Showcase”与“公网 Product”完成定义冲突。 +- 新增不得由 Codex 代签的项目所有者掌握验收表。 + +## 非 Showcase 阻塞项 + +以下事项继续阻塞 Product Release，但不阻塞诚实边界内的 Showcase： + +- 生产身份、精确 CORS、公网 HTTPS API、限流、配额、防滥用与模型费用熔断。 +- 托管密钥、托管 PostgreSQL、备份/恢复演练、高可用与迁移回滚。 +- 线上日志/Trace/指标收集、dashboard、告警和公网端到端验收。 +- main branch protection、`SECURITY.md`、Code of Conduct、Issue/PR 模板和独立 ADR 可继续增强开源治理。 +- 独立人工标注质量集、更多真实模型重复运行、浏览器 E2E、无障碍和供应链扫描属于后续增强；不得虚构指标。 + +## 发布使用边界 + +| 使用方式 | 当前结论 | 合法表述 | | --- | --- | --- | -| GitHub 开源源码 | 可用 | 可复现、经过 CI 的受控运营 Agent MVP | -| Netlify 静态项目页 | 已上线 | 公开只读项目说明和静态功能展示 | -| 本地/现场完整演示 | 可用 | Docker Compose 单节点三业务完整闭环 | -| 公网交互演示 | 未完成 | 不可称在线可操作 Agent；需要后端部署与安全治理 | -| 企业生产系统 | 未完成 | 不可声称生产高可用、SLA、真实 WMS/CMMS 接入 | - -因此，OperCerta 已可作为个人 Agent 项目写入简历并用于本地面试演示，前提是明确写成 -“可部署单节点 MVP + 公开静态项目页”，并能亲自解释和操作业务闭环。若希望审阅者无需 -本地环境直接操作真实 Agent，则仍需完成 P0 中的公网交互演示子集；若希望称为生产系统， -则必须完成全部 P0 并补充运行期证据。 - -## 原始完成定义对照 - -| 完成定义 | 状态 | -| --- | --- | -| 核心业务成功/失败/拒绝终态闭环 | 通过 | -| 状态、工具、权限和异常路径测试 | 通过 | -| 固定评测与可重复性能/缓存报告 | 通过，样本边界已声明 | -| 干净 Docker Compose 启动与重启恢复 | 通过 | -| 在线地址可以完成真实核心业务 | 未通过；当前仅静态页 | -| README、架构、API/部署/限制文档 | 部分通过；内容充分但正式 ADR/安全治理文件缺失 | -| 日志、Trace、Token、成本与关键指标 | 部分通过；Trace/指标具备，供应商 usage/公开观测后端缺失 | -| 无密钥、无旧单位专有内容、无未授权材料 | 仓库安全门禁通过 | -| Release tag 与验收记录 | 通过，现有 Showcase pre-release | -| 可重复演示与学习材料 | 材料通过；个人脱稿掌握仍需本人验收 | +| GitHub 源码 | 可用 | 经 CI 验证的受控运营 Agent MVP | +| Netlify | 已上线 | 公开静态项目展示 | +| 本地/现场演示 | 工程具备、待本人验收 | Docker Compose 单节点完整 Agent MVP | +| 公网交互 | 未实现 | 不得称为在线可操作 Agent | +| 企业生产 | 未实现 | 不得声称高可用、SLA 或真实 WMS/CMMS 接入 | + +## 剩余 P0 收口 + +1. 本分支全门禁、PR、main CI 与 Compose 复验。 +2. 项目所有者按 `docs/learning/opercerta-ownership-acceptance.md` 独立完成验收，并保存 `operation_id`、`work_order_id`、Trace、审计和数据库事实。 +3. 完成 3–5 分钟录屏；之后才能签署本人掌握结果并创建最终 Showcase tag。 + +ForenTrail 暂不启动。FieldPilot 在 OperCerta 完成后另行规划，不混入本仓库。 diff --git a/docs/development-log/current-state.md b/docs/development-log/current-state.md index acb209f..390560a 100644 --- a/docs/development-log/current-state.md +++ b/docs/development-log/current-state.md @@ -1,302 +1,64 @@ # OperCerta 当前状态 -## 2026-07-31：Showcase Pre-release 已发布，自动化工程收口 +> 更新时间：2026-07-31。本文件只保存当前权威状态；历史过程见 `docs/development-log/daily/` 与 `docs/release-evidence/`。 -[PR #18](https://github.com/KXHXK/opercerta/pull/18) 已合入 main `298fc5978a56961d36e73888f4ae73017e302715`；[main run 30541088053](https://github.com/KXHXK/opercerta/actions/runs/30541088053) 的 repository-safety、python-quality、frontend、backend-tests、compose-smoke 五项全部成功。证据仍为完整后端 `667 passed`、三业务固定契约、冻结 Agent 安全/恢复评测 `9/9`、前端 19 文件/60 条，以及隔离 Compose 的三业务数据库副作用、API/MCP 重启恢复和无条件清理。 +## 当前结论 -[Showcase 预发布 `v0.1.0-showcase.1`](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1) 已创建并精确指向 `298fc59`。Netlify 公开静态专题保持 production deploy `6a6b17cf496c38056f737264`，六项安全头、资源 SHA-256 和三个静态路由已核验；上一 production `6a6631d24958714a43ddc508` 保留为回滚点。 +OperCerta 的三业务共享 Agent 主线、可靠性内核、前后端、本地 Compose 和自动化证据已经完成。当前版本正式定义为： -状态必须分开表达：求职代码仓库、静态展示、固定评测和可重复本地三业务演示的自动化工程门禁已经通过；个人源码掌握、完整手动实演、3–5 分钟录屏和简历定稿仍需用户亲自完成。公网可写 FastAPI、生产 IAM、限流、防滥用、备份、高可用、自动部署和 SLA 仍未实现，产品 production release gate 保持 `CLOSED`。 +> **公开静态展示 + 本地可复现完整 Agent MVP + 3–5 分钟录屏。** -## 2026-07-30：发布准备已合并，静态 Production 已晋级 +公开站点 只承载静态项目展示，不连接可写 API 或数据库。真实 FastAPI、LangGraph、FastMCP、PostgreSQL、Redis 与 React 控制台在本地 Docker Compose 环境运行。当前版本不是公网交互产品，也不是企业生产系统。 -[PR #17](https://github.com/KXHXK/opercerta/pull/17) 全部必需检查通过，并以普通 merge commit `b6aa5fa13c7645bd3351092fc23b6c3e132a284d` 合入 main。[main run 30539160493](https://github.com/KXHXK/opercerta/actions/runs/30539160493) 五项全绿：完整后端 `667 passed`、三业务契约 `1 passed`、冻结 Agent 评测 `9/9`、前端 19 文件/60 条，以及实际 Compose 构建、三业务数据库副作用、API/MCP 重启恢复与清理。 +## 三类门禁 -已验证 Preview `6a6b17cf496c38056f737264` 通过 Netlify 官方 `restoreSiteDeploy` 晋级为 production；公网根页、`/console`、静态 API 回退均为 `200 text/html`，六项安全响应头和 JS SHA-256 与 main 本地产物一致。上一 production `6a6631d24958714a43ddc508` 保留为回滚点。 +| 门禁 | 状态 | 判定依据 | +| --- | --- | --- | +| 工程与本地自动化门禁 | `PASSED` | 当前 main `61d5fa0`；PR #22 合并；main run `30622621533` 五项成功；本分支本地后端 671；前端 60、三业务 42/42、Agent 9/9、Compose 重启恢复通过 | +| Showcase Release gate | `AWAITING_OWNER_VALIDATION` | 静态站点和本地 MVP 已具备；仍需项目所有者独立完成业务实演、源码讲解、恢复实验和录屏 | +| Product Release gate | `CLOSED` | 未部署公网可写后端、生产身份、限流、防滥用、托管数据库备份、高可用与线上告警 | -当前完成的是“本地完整三业务 Agent 闭环 + 公开静态求职展示”，不是公网可写生产系统。下一优先级是固定项目评测口径、用户源码级掌握验收、演示素材与简历材料；公网 FastAPI、生产 IAM、限流、备份、高可用和自动部署仍未完成，产品 production release gate 继续 `CLOSED`，不启动 ForenTrail。 +`Showcase Release gate: AWAITING_OWNER_VALIDATION` -## 2026-07-30：换机环境已合并 main，远程与本机 Compose 门禁通过 +`Product Release gate: CLOSED` -PR #15 已以普通 merge commit 合并为 main `42ba974`，未删除分支、未强推、未绕过门禁。对应 main run `30525556998` 五个 job 全部成功：repository-safety、python-quality、frontend、backend-tests，以及只在 main push 执行的 compose-smoke。compose-smoke 真实完成镜像构建启动、Agent 轨迹与数据库副作用验证、API/MCP 重启、恢复验证和隔离卷清理。 +最新 main 的后端基线为 668；本分支新增 3 条发布/安全契约后，使用一次性 pgvector 测试库得到 `671 passed in 112.07s`。合并后仍须用最终 main CI 复核该数字。 -本地主线已 fast-forward 到同一提交，随后从干净 main 创建 `chore/release-readiness-20260730` 作为下一阶段分支。WSL 登录 shell 可直接使用 Node `24.18.0`、npm `11.16.0` 和 uv `0.11.28`；使用已有已验证镜像且不删除数据卷恢复本机 Compose 后，PostgreSQL、Redis、MCP、API 四服务均 healthy，`/health/ready` 返回 database/checkpoint/MCP 全部 ready。换机环境阶段至此关闭。 +## 已实现范围 -下一阶段依次为部署边界复核、公开环境 readiness、固定评测、源码级掌握和简历材料。现有 Netlify 是只读静态专题；公网可写后端、生产身份、限流、备份、高可用和自动部署仍未完成，因此 production release gate 继续 `CLOSED`，不启动 ForenTrail。 +- 库存不足、设备异常、作业阻塞三类确定性信号发现与 Case 隔离。 +- 有限表单输入和类型化 Goal，不提供无边界自由聊天。 +- 单一 `ControlledAgentRootGraph`：LLM 规划、工具策略、MCP Observation、有界回环、人工审批中断、恢复与 Verifier。 +- FastMCP 七类类型化工具；业务权威事实由 PostgreSQL 提供，SOP 由 pgvector 检索并带 citation。 +- 审批绑定、批准后最新事实复核、行级并发控制、幂等键、唯一约束和写后读验证。 +- PostgreSQL LangGraph checkpoint、业务表主导恢复、API/MCP 重启恢复。 +- Redis 只缓存只读证据，审批后复核绕过缓存。 +- FastAPI/JWT/RBAC/Pydantic/SSE、React Case 工作台、Agent Trace 和审计时间线。 +- Mock 模型确定性门禁；Moonshot/Kimi K2.6 仅做少量兼容性代表验证，不宣称准确率、成本或 SLA。 -当前分支 `chore/new-machine-env-20260729` 与远端同名分支在本轮修改前为 `ahead 0 / behind 0`，Draft PR #15 的 repository-safety、python-quality、backend-tests、frontend 已有绿色基线。新电脑固定工具链为 WSL2 Ubuntu 26.04、uv `0.11.28`、项目 Python `3.12.13`、Node `24.18.0`、npm `11.16.0`、Docker `29.1.3` 和 Compose `2.40.3`。 +## 当前运行与发布证据 -换机收口发现 Node PATH 只持久化到 `.bashrc`，导致非交互 `bash -lc` 找不到 Node。已按 TDD 把引导契约修复为同时维护 `.bashrc` 与 `.profile`，真实登录 shell 和定向 7 条测试均通过。新机空虚拟环境使用从冻结锁导出的带 hash 临时清单和清华 PyPI 镜像恢复 109 个依赖，未改写 `uv.lock`。DrvFS chmod 不持久化继续作为已知约束管理，不在本轮扩大系统配置变更。 +- GitHub main：`61d5fa0`；PR #22；Actions run `30622621533` 五项全绿。 +- 自动化基线：本分支本地后端 `671 passed`；前端 19 文件/60 条；三业务固定契约 42/42；冻结 Agent 安全恢复 9/9；收口前 main Compose smoke 通过。 +- 本机 WSL2 Ubuntu 26.04 的 `opercerta-demo` PostgreSQL、Redis、MCP、API 四服务 healthy；readiness 中 database、checkpoint、MCP 均 ready。 +- Netlify 为静态站点；`/console` 与 `/api/*` 在公网均是 SPA 静态回退，不是可写后端。 +- 旧预发布 `v0.1.0-showcase.1` 指向较早提交，只保留历史；最终 Showcase tag 必须在本轮合并、本人验收和录屏后创建。 -已有开发卷因三条 signal 已完成而返回预期幂等 `409`，不能复用为首次调查测试。改用独立 Compose project 和新鲜临时卷后，三业务 Agent、RAG/Trace、审批、Verifier、工单数据库断言、API/MCP 重启及 recovery-only 全部通过，退出码 0；原开发卷未删除并已恢复四服务 healthy。当前 Ruff、216 文件格式、Mypy 85 个源文件、仓库安全与文档索引门禁均通过。下一步提交本轮修复并等待 PR #15 新鲜 CI；PR 合并后再执行 main Compose、部署与掌握验收。空缓存 Docker 冷构建和公网生产治理仍未关闭，production release gate 保持 `CLOSED`，不启动 ForenTrail。 +## 当前唯一主线 -首次新鲜 CI 中 repository-safety、python-quality、frontend 通过，backend-tests 为 `2 failed, 663 passed`；失败仅来自最新 main 新增 `CONTRIBUTING.md` 后合并态文档数从 114 变成 115。本地 Git HTTPS 暂时无法 fetch，但 GitHub compare API 已证明 main 的净文件变化仅为该新增文件。当前分支已采用 main 原文并补齐第 115 条索引，正在进行本地复验和二次 CI；不能把首次失败误报为业务或 Agent 测试失败。 +1. 合并本轮双门禁、许可证、工具链和文档防漂移修订，并取得新鲜 main CI/Compose 证据。 +2. 项目所有者按 `docs/learning/opercerta-ownership-acceptance.md` 亲自完成环境、完整库存闭环、代码链路、重启/幂等和分层讲解验收。 +3. 录制 3–5 分钟演示，保存操作编号、工单编号、Trace/审计和数据库后置事实。 +4. 验收通过后创建最终 Showcase tag，并以“公开静态展示 + 本地可复现完整 Agent MVP”对外表述。 -## 2026-07-29：换机本地门禁已通过，冷缓存构建与远程 PR 门禁待关闭 +ForenTrail 暂不启动。FieldPilot 是 OperCerta 完成后的独立项目，不在本仓库扩展或预先实施。 -当前分支 `chore/new-machine-env-20260729` 已通过普通 fast-forward push 把本地门禁提交 `08e113b` 同步到远端同名分支。此前的连接重置来自受限命令环境；获得窄范围 `git push` 网络授权后推送成功。GitHub App 因安装权限不足无法创建 Draft PR，内置浏览器连接 GitHub 超时，本机 `gh` 已安装但尚未登录，因此 PR 与远程 Actions 门禁仍待完成。换机后的固定工具链可用：WSL2 Ubuntu 26.04、Docker/Compose、uv `0.11.28`、项目 Python `3.12.13`、Node `24.18.0` 与 npm `11.16.0`。后端在随机短生命周期 pgvector 容器上完成 `664 passed`，固定业务评估 `1 passed`，Agent 评估 `9/9 passed`；前端完成 `19` 个测试文件、`60` 条用例和 production build。PyJWT 测试弱密钥警告已消除并以 warning-as-error 定向复验。 +## 不得误报的边界 -换机复核发现并修复两类真实跨平台问题：5 个 Linux shell 脚本仍是 CRLF，导致 Bash 无法解析 `pipefail`；三份 SOP 的原始字节与清单哈希不一致，导致知识导入拒绝。所有相关文件已归一化为 LF，SOP 现与冻结 manifest 哈希一致。当前源码候选镜像已通过三业务 Agent Compose、知识导入、API/MCP 重启恢复以及 database/checkpoint/MCP readiness。 +- 不把静态 Netlify 页面描述为公网可操作 Agent。 +- 不把 demo JWT 描述为生产身份系统。 +- 不把固定合成评测描述为生产准确率或真实流量 SLA。 +- 不把少量真实模型调用描述为供应商基准测试。 +- 不在本人尚未实演和讲清代码前，把个人掌握门禁写成通过。 -本次没有宣称空缓存冷构建通过：Docker 内冻结依赖首次下载历史约需 32 分钟，本次为加速本地业务门禁，在确认现有镜像内 `pyproject.toml`、`uv.lock` 与仓库 SHA-256 完全一致后，仅覆盖当前源码和运行资产生成候选镜像。下一步完成最终静态/安全/索引检查、提交推送和 Draft PR 快速 CI；随后再决定是否执行独立冷构建性能优化。生产门禁继续 `CLOSED`，不启动 ForenTrail。 - -## 2026-07-29：新电脑 WSL2 开发环境已恢复，等待 Git 同步与完整门禁 - -新电脑已完成 WSL `2.7.11.0`、Ubuntu `26.04 LTS`、Docker `29.1.3`、Compose `2.40.3`、uv `0.11.28`、项目 Python `3.12.13`、Node.js `24.18.0` 和 npm `11.16.0` 的安装与版本核对。PostgreSQL/pgvector、Redis、MCP 和 API 四个 Compose 服务均为 `healthy`；API readiness 已返回 database/checkpoint/MCP 全部 ready。FastEmbed 首次模型下载通过本机 ignored 的 Hugging Face 镜像端点完成，正式 Compose 未硬编码第三方端点。 - -纯 WSL 前端链路已经在 `/mnt/d/CODEX/agent-portfolio/opercerta/web` 通过：`npm ci` 安装 121 个包，19 个测试文件共 60 条测试通过，Vite production build 成功。DrvFS 当前未启用 `metadata`，`chmod` 不持久化 mode bits，但它没有阻断现有测试与构建；后续必须只用 WSL npm 管理当前 `web/node_modules`，不能与 Windows npm 交替安装，也不能使用 `sudo npm ci`。 - -换机环境脚本已增加固定版本、国内下载镜像、Node 官方 SHA256 校验、失败诊断和跨运行时依赖边界。`DOCUMENT_INDEX.md` 已修复为根工作树 113/113 份 Markdown，并把 6 个旧 worktree 各自保留为明确的历史表。环境与索引成果已在 `chore/new-machine-env-20260729` 形成保护提交 `e02439c`。首次 GitHub fetch/push 因 WSL 网络 TLS/443 失败而未完成；同时确认 WSL 显示的数百个修改全部是 Windows/WSL `core.autocrlf` 不一致造成的行尾假差异，434 个 tracked 文件中真实内容差异为 0、缺失为 0。仓库级 `.gitattributes` 正在固定文本 LF 和 binary 边界。下一步提交行尾策略，待网络恢复后 fetch/rebase/push，再执行完整后端、前端、Compose 重启恢复和远程 CI 门禁。生产门禁继续 `CLOSED`，不启动 ForenTrail。 - -## 2026-07-27：PR #8、main Compose 与新版静态专题已发布 - -单根 Agent Loop 与 case 工作台在 [PR #8](https://github.com/KXHXK/opercerta/pull/8) 合并为 `609f8f7dcbfbadb9d12f4371cf49815d48884a4e`。对应 [main run 30203438564](https://github.com/KXHXK/opercerta/actions/runs/30203438564) 的 `repository-safety`、`python-quality`、`backend-tests`、`frontend`、`compose-smoke` 全部成功；Compose 实际完成容器构建启动、Agent 轨迹与数据库副作用、API/MCP 重启、重启恢复和清理。 - -已验证静态候选 deploy `6a660a8f77aa692302ad00aa`，随后经用户批准发布 production deploy `6a6631d24958714a43ddc508`：。生产根页、独立 deploy URL、`/console` 与 `/api/v1/auth/demo-token` 均为 `200 text/html`；JS 资源为 `index-Ckvsq13U.js`，线上 SHA-256 `dcd31a4d6e1c53f06c1a16cc6fb65f7f5d347926a078dc56fe08606c8052abb1` 与本地候选一致。`/api/*` 返回静态 SPA HTML 是刻意的无后端边界，不代表 API 上线。上一生产 deploy `6a5e0bb5563acf4706a09c0d` 保留为回滚点。 - -当前完成的是“公开静态求职专题 + 本地可运行完整业务闭环”，不是公网可写生产系统。生产 IAM、公网 HTTPS API、托管 PostgreSQL/Redis、限流、防滥用、备份、高可用、自动部署和正式 Release Tag 仍未完成，发布门禁继续 `CLOSED`。下一步是用户手动运行与源码掌握验收、面试材料和 Release Tag 决策；未完成前不启动 ForenTrail。 - -## 2026-07-26 单根 Agent Loop 架构纠偏已批准，Task 0–3 完成 - -用户在真实控制台复核中指出：当前 LLM 没有形成“决策 → 工具 → Observation → 再决策”的 Agent 核心循环；LangGraph 调查图、Python 包装器和三个场景图被串联使用，完整 operation 并非由一个根图拥有；Redis 也只包裹旧场景初读，没有进入统一的 MCP Observation 链路。前端同时把 predecessor/successor signal 平铺为主卡片，并用全局详情和 busy 状态驱动交互，造成多卡、串卡和业务谱系失真。 - -完整复核四份原始设计、2026-07-21 Agent 核心设计和当前实现后确认：这不是用户临时改变需求，而是实现没有兑现已经批准的“LangGraph 唯一编排运行时 + AgentHarness ToolLoop”。可靠性内核仍有效并继续保留，包括 PostgreSQL 事实、signal 认领/对账、RBAC、审批竞态、批准后刷新、Verifier、事实绑定、幂等工单、MCP/RAG 和重启恢复；必须重构的是编排所有权、模型—工具循环、Redis 接入位置和 React case 状态模型。 - -纠偏规格 `docs/superpowers/specs/2026-07-26-single-root-agent-loop-and-case-workspace-design.md` 已获用户批准。Task 0 基线为 71 条可靠性单元测试和一次性 PostgreSQL 上 43 条审批/幂等/signal/恢复集成测试通过。Task 1 先观测 `AgentTurn` 缺失 RED，再新增 ToolDecision/FinalAnalysis 互斥联合契约和累计预算校验；定向 33 条通过。Task 2 先观测统一缓存结果缺失 RED，再新增 `CachedReadToolGateway` 和 `hit/miss/bypass/unavailable` Observation；相关范围 76 条通过，一次性 PostgreSQL 上 Agent 图/RAG/重启恢复 11 条通过。最终使用 `PYTHONPATH=.:src` 和 `set -euo pipefail` 复跑完整单元套件 `386 passed in 34.14s`，全项目 Ruff、Mypy 81 个源文件及 `git diff --check` 通过。 - -Task 3 已新增默认关闭的库存 `InventoryAgentRootGraph` 和 `AgentLoopModelGateway.decide` 协议。查询测试证明模型依次看到 0、1、2 条 Observation 后选择库存、规则并形成最终分析；创建路径在同一根图和 `thread_id` 停在原生 `approval_interrupt`。证据不足、引用不匹配和写工具均安全失败。一次性 PostgreSQL checkpointer 定向 `6 passed`；包含旧 Agent 图的完整回归 `398 passed in 35.32s`，全项目 Ruff、Mypy 82 个源文件和 diff 检查通过。 - -当前根图只到审批中断，尚未接入审批提交后的刷新、Verifier、绑定和幂等写入；候选必须显式 `enabled=True`，默认 API/Compose 仍使用旧路径。未审批当前 operation、未调用 Real Kimi、未 commit/push/merge，发布门禁保持 `CLOSED`。下一步是 Task 4 审批后可靠性节点接入根图。 - -## 2026-07-25 异常信号入口修订 - -已纠正“固定对象直接创建处置”缺少业务动机的问题：新增迁移 `0007_operational_signals`、并发去重信号仓储、信号与 operation 原子认领、三业务确定性 `SignalDetector`、扫描/列表/调查 API，以及 React 异常信号箱。生产模式下 `create_work_order` 没有 `trigger_signal_id` 会返回 422；query 仍作为诊断入口。真实本地 Compose 经 Caddy 扫描三对象得到库存短缺、设备异常、任务阻塞三条信号且零数据源错误；库存信号原子绑定新 operation 并进入 `awaiting_approval`。operation 完成或拒绝时 signal 原子收口为 `resolved`，失败、过期或中止时转为 `attention_required`，形成可再次介入的反馈闭环。新鲜证据：完整后端 `600 passed in 178.48s`；前端 18 文件/`56 passed` 与 production build；Ruff、Mypy 79 个源文件通过；隔离空卷 Mock release Compose 依次验证直接写 422、三信号、三业务审批/Verifier/工单、重复审批、数据库事实以及 API/MCP 重启恢复，退出码 0、耗时 175.1 秒并自动清理。远程 CI、修订后的 Real Kimi、PR 提交/合并与生产治理尚未执行，因此发布门禁继续 `CLOSED`。 - -同日用户复核发现首次页面必须切角色才能扫描，而且切角色会自动读取 PostgreSQL 历史 signal，造成“扫描按钮是假的”观感。修复后首次 operator 无需预先签发 JWT即可点击；首次点击在同一动作内签发内存 JWT 并调用真实 scan API；角色切换不再调用 `GET /signals`，刷新后在扫描完成前保持空信号箱。scan 响应新增服务端 `scanned_at`，页面显示本次范围、6 次只读 MCP、命中数、去重语义和三类具体规则事实。新鲜回归为完整后端 `600 passed in 189.97s`、前端 18 文件/`56 passed`、production build、Ruff 和 Mypy 79 个源文件全绿；本地 Compose 已重建并恢复 `18080` 端口。应用内浏览器因 localhost URL 策略拒绝自动复验，需用户手动刷新做视觉确认，不能将组件测试冒充浏览器证据。 - -## 最新核验：前端安全边界与审批写入语义已完成本地收口 - -2026-07-24，规格一致性复核继续发现并修复两项端到端边界：未知后端错误码不再把原始 `message` 暴露给用户；审批 API 已成功写入但后置读取因 RBAC/网络失败时，前端明确保留“审批已提交”事实并禁用重复决定，不再误报“审批未提交”。两项均先写 RED，再以最小实现转为 GREEN。 - -新鲜门禁：前端 17 文件/`53 passed` 与 production build；后端 unit `356 passed`、一次性 pgvector 测试库完整套件 `579 passed in 376.68s`；Ruff、189 文件格式、Mypy 76 个源文件、114 包锁定与仓库安全扫描通过；Mock release Compose 三业务、RAG/Trace、批准后 Verifier/绑定护栏/受控写入、数据库事实和 API/MCP 重启恢复退出码 0。`.env.local` 指向的 Windows 测试库未运行，失败 traceback 再次回显 ignored 旧凭据，该值必须视为已暴露并在恢复原生测试库前轮换；本轮完整套件改用运行时随机凭据的一次性本地容器且已清理。修改尚未 commit/push；Real Kimi、PR 合并、main Compose、生产发布和 ForenTrail 均未执行，发布门禁保持 `CLOSED`。过程见 `docs/development-log/daily/2026-07-24.md`。 - -## 最新核验：规格一致性审计与 Agent 展示收口通过本地门禁 - -2026-07-23 对四份原始设计、三业务修订、Agent 核心规格、当前源码和证据逐项复核，主线仍是“传统仓储/运营工单可靠性内核 + 受控单 Agent 增强”，没有退化为普通 CRUD，也没有扩成自由聊天或多 Agent。修复了前端吞掉 401/403/409/422/503 安全 envelope、产品 Trace 缺少独立 Verifier/绑定护栏、安全业务终态仍显示 running、主角色混入未完成 demo-admin，以及空 FastEmbed cache 离线冷启动说明不完整。 - -新鲜本地门禁：后端 unit `356 passed in 38.86s`；前端 17 文件/`51 passed` 与 TypeScript/Vite production build；Ruff 全绿、`182 files already formatted`、Mypy 76 个源文件；Mock Compose 三业务 Agent 验证退出码 0，并新增强制 `Verifier → binding guardrail → controlled execution` 顺序断言；API/MCP 重启恢复退出码 0，四服务 healthy。独立本地测试数据库端口未监听，数据库集成 Pytest 未形成新鲜绿色结果；本轮未用环境故障冒充业务失败，Compose 的真实 PostgreSQL 断言已通过。Real Kimi、PR 合并、main Compose、生产发布和 ForenTrail 均未执行，发布门禁保持 `CLOSED`。审计见 `docs/development-log/audits/2026-07-23-spec-conformance-audit.md`。 - -## 最新核验：Agent 核心 Draft PR 快速门禁已通过 - -2026-07-23，`feat/agent-core-implementation` 的 Kimi + RAG replan 已改为只暴露尚缺工具，provider/图异常 operation 已能原子收口为固定 `dependency_unavailable`；真实图 probe 完成 inventory → knowledge → policy。新鲜本地回归为 unit 352 条、关键 Agent 图集成 7 条、Ruff/188 文件格式/Mypy 76 个源文件；Draft PR run `29946792369` 的 repository-safety、python-quality、backend-tests、frontend 全绿，完整后端 `573 passed`、三业务评测 1 条和 Agent 评测 9/9。完整 Compose Real Kimi 仍未稳定通过，最终安全证据为 create operation 503 `dependency_unavailable`；未回退 Mock。测试 traceback 曾展开的本地 PostgreSQL 测试凭据已轮换，主仓库与 worktree ignored 配置一致，并由 Windows 原生 `psql` 执行 `SELECT 1` 安全验证。生产发布门禁保持 `CLOSED`。 - -同日此前已创建 [Draft PR #8](https://github.com/KXHXK/opercerta/pull/8)。首次 Actions 暴露 CI 普通 PostgreSQL 镜像不含迁移要求的 vector extension；提交 `ba53e70` 用资产契约统一为 pgvector 镜像后，最新基线 run `29937375023` 的 repository-safety、python-quality、backend-tests、frontend 全部通过。PR 事件按设计跳过 `compose-smoke`；PR 尚未 review/合并，main 新鲜 Compose 和生产治理仍未完成。 - -## 最新核验：Agent Task 8 React 工作台已完成前端与响应式门禁 - -2026-07-22，Agent 核心 Task 9 已提交 `642d3ba`：本地后端 566 条、前端 46 条、冻结 Agent 评测 9/9、真实 FastEmbed/pgvector RAG、三业务 Compose 与 API/MCP 重启恢复通过。Real Moonshot/Kimi `kimi-k2.6` 新 Agent 代表 query 未通过严格规划路径，报告为 failed，未回退 Mock；异常 operation 原子收口仍是 known limitation。Task 10 中文交付与 Draft PR 快速门禁已完成，review/main Compose 仍待执行，生产发布门禁保持 `CLOSED`。详见 `docs/release-evidence/agent-core-architecture.md`。 - -2026-07-22，本地 `/console` 已从简易工单三栏升级为受控 Agent 工作台：固定表单、结构化 Goal、真实后端 Agent Trace、MCP/RAG 证据、模型建议与确定性计划对照、审批 binding、Verifier 说明、工单回读和 operator→approver→auditor 引导均已接入，且 audit 不再冒充 Trace。完整前端为 17 个测试文件/46 条测试，TypeScript/Vite 生产构建通过；1440/1024/390 浏览器检查无横向溢出，应用内无 fixed/sticky。Task 9 Compose/RAG/重启已在后续证据完成，Real Kimi 新 Agent 路径仍未通过，生产发布门禁保持 `CLOSED`。详见 `docs/release-evidence/agent-workspace.md` 与 `docs/release-evidence/agent-core-architecture.md`。 - -## 最新核验：Agent Task 7 脱敏 Trace、API/SSE 与 RBAC 已完成本地门禁 - -2026-07-22 Task 7 检查点：迁移 `0006_agent_trace`、run/event/citation 数据模型、稳定 sequence/semantic key、递归脱敏、LangGraph 调查/审批/执行/反馈投影、RAG citation reference、Trace snapshot/SSE API 与 operation 级 RBAC 已实现。该检查点产品代码全量测试为 545 条通过；operator owner/非 owner 权限补强后定向 8 条通过，WSL Git 安全 4 条通过。Trace 不保存 prompt、reasoning content、原始工具正文、SOP 正文、秘密或 stack trace；也不以 Trace 替代业务审计或 OTel。Windows 本地测试密码在失败 traceback 展开后已立即轮换。Task 8--9 的后续结论以本文顶部新鲜记录为准。详见 `docs/release-evidence/agent-trace-rbac.md`。 - -## 最新核验：Agent Task 6 pgvector 中文 SOP RAG 已完成本地代码与真实检索门禁 - -2026-07-22，PostgreSQL `0005_agent_knowledge`、`vector(512)`/HNSW、三份从零编写的合成中文 SOP、固定 `BAAI/bge-small-zh-v1.5` FastEmbed、MCP `knowledge.search_sop`、LangGraph citation、普通场景降级和强制 SOP 失败关闭均已实现。新鲜门禁为新建空卷容器网络聚焦 75 条、产品 535 条、Git 安全 4 条，Ruff/173 文件格式/mypy 73 个源文件/114 包锁文件/安全扫描通过；真实模型完成 3 文档 12 chunk 入库、幂等 replay 与三场景隔离检索。空卷门禁还修复了迁移测试依赖预迁移数据库的隐式前置条件。新镜像构建成功并观察到 PostgreSQL/MCP healthy、API started；完整 Compose smoke 在 Codex 自动化 WSL 会话中因外层 Docker service 约 43--49 秒停止而未完成，须在 Task 9 稳定终端重跑。Task 7 Agent Trace/API/SSE/RBAC 与前端展示尚未实施，生产发布门禁保持 `CLOSED`。详见 `docs/release-evidence/agent-pgvector-rag.md`。 - -## 最新核验：Agent Task 5 审批后 Verifier 与多轮复审已完成本地代码门禁 - -2026-07-22，三业务已接入批准后 Verifier：重新取证绕过缓存，`proceed` 仅在 binding 一致时幂等写入，`abort` 零工单安全终止，`escalate` 或模型参数漂移进入新审批周期。PostgreSQL 迁移 `0004_approval_cycles` 保留历史审批并按当前周期授权写入；缺失检查点恢复和“数据库已提交、检查点未保存”重放均有自动化证据。定向门禁 `48 passed`，完整 workflow `62 passed`，后端产品测试 `502 passed`，WSL 原生 Git 安全脚本 `4 passed`，Ruff/mypy 通过。Task 6 的 pgvector/RAG、Task 7 的 Agent Trace/API/SSE/前端展示仍未实施，旧 Compose 应用镜像尚未重建，因此生产发布门禁保持 `CLOSED`。详见 `docs/release-evidence/agent-verifier-reapproval.md`。 - -## 最新核验：零成本公开专题、主线门禁与作品集同步已完成 - -2026-07-20 功能分支 `feat/zero-cost-showcase-walkthrough` 已完成公开根路径、本地 `/engineering` 与本地 `/console` 三种页面职责：公开专题零 API、零写入、只陈述三业务和已验证证据；工程详解仅在开发模式的 localhost/127.0.0.1 渲染，包含 10 步请求链路、三业务差异、10 项技术职责、10 个真实事故复盘和 4 项 localStorage 掌握检查；控制台保持真实本地交互。完整前端为 16 个测试文件/40 条测试，后端为 `430 passed in 106.25s`；Ruff、138 文件格式、mypy 62 个源码文件和仓库安全扫描通过。PR #6 已以 `e483665` 合并，`main` run `29738863357` 五个 job 全绿，包含 Compose 三业务和 API/MCP 重启恢复。OperCerta production deploy `6a5e0bb5563acf4706a09c0d` 与作品集 production deploy `6a5e1b8824ba2290cf63c897` 已通过 HTTP/浏览器核验；作品集移动端无横向溢出、坏图或 fixed/sticky 元素。公开页面仍不连接可写后端，生产门禁继续为 `CLOSED`。证据见 `docs/release-evidence/zero-cost-showcase-engineering-walkthrough.md`。 - -## 最新核验：Task 8 真实模型代表性验证已完成 - -2026-07-20 经用户授权，Moonshot AI `kimi-k2.6` 在本地 release Compose 中完成库存、设备、作业各 1 条 query 与 1 条批准路径，共 6 个 operation、3 条真实模型路径；三条写路径分别生成唯一补货、维修、作业恢复工单。实现提交 `b517ab8`。模型兼容修复后完整后端 `429 passed in 110.61s`，Ruff、138 文件格式、mypy 62 个源文件、92 个锁定包和仓库安全扫描通过；Mock release Compose 新鲜退出码 0、耗时 129.1 秒并自动清理。报告没有模型原文，token/成本因 adapter 未暴露 usage 而标记不可用。证据见 `docs/release-evidence/real-model-representative-validation.md`。生产门禁仍为 `CLOSED`。 - -## 历史核验：Task 8 本地发布候选与中文学习包已完成 - -2026-07-20 提交 `a3994ef` 新增 Caddy/React 多阶段镜像、仅 Caddy 暴露端口的 `compose.release.yaml`、一键发布 smoke，以及中文核心技术、手动实验和面试讲解三份材料。本轮完整后端门禁为 `422 passed in 94.96s`，Ruff、136 文件格式、mypy 62 个源文件、锁定依赖和仓库安全扫描通过；前端 12 个测试文件/25 条测试与生产构建通过。`scripts/verify_release_compose.sh` 新鲜运行退出码 0、耗时 70.8 秒，三业务、拒绝、重复审批、数据库事实、Caddy 路由、API/MCP 重启恢复和 metrics 不公开均通过应用断言。该检查点之后真实模型代表性调用已由本文首节补齐；公网交互 HTTPS、生产 IAM/限流/备份、用户手动掌握、当前远程 CI 与 Release Tag 尚未完成，生产发布门禁保持 `CLOSED`。 - -## 最新核验：三业务固定评测、Compose 与缓存矩阵已通过 - -2026-07-20 Task 7 已完成：版本化套件在 FastAPI + FastMCP + PostgreSQL 边界运行 42 条（库存 30、设备 6、作业 6），42 passed、0 failed；Compose 三业务与 API/MCP 重启恢复通过。2×2 本机矩阵 60/60 个 query completed、零错误，缓存关闭为每场景 10 次 MCP/0 hit，开启为 2 次 MCP/8 hit。最终总门禁 414 passed in 103.80s，锁文件、Ruff、134 文件格式、mypy 62 个源文件和安全扫描通过。每格仅 5 次，延迟不作为生产指标。证据见 `docs/release-evidence/three-business-evaluation-compose.md`。Task 8 本地发布、中文学习与真实模型代表性验证随后已完成，发布门禁仍为 `CLOSED`。 - -## 最新核验：Redis、OpenTelemetry 与 Real model adapter 已完成代码门禁 - -2026-07-20 已实现只读证据 Redis 缓存、批准后缓存绕过、低基数缓存指标、API/LangGraph/MCP/Redis/PostgreSQL OpenTelemetry span、API→MCP trace context 传播，以及严格解释型 OpenAI-compatible adapter。Task 7 已完成 Redis 镜像、缓存矩阵与三业务 Compose smoke；Compose 默认仍使用 Mock，OTLP 默认关闭，真实模型代表性运行随后已由本文首节补齐。提交前安全审查修复了自动异常正文/堆栈进入 span 与指标故障破坏缓存旁路两项问题；Task 6 完整测试 `409 passed in 101.15s`。发布门禁保持 `CLOSED`。 - -## 最新核验：三业务后端与单页控制台已完成本地门禁 - -2026-07-20 已完成库存补货、设备维修、作业异常恢复三条合成业务闭环的领域契约、六个 FastMCP 工具、PostgreSQL 状态/审计/工单、LangGraph 审批与恢复路径，以及 React 单页控制台。三对象同时支持只读 `query` 和受控 `create_work_order`；查询只取证和评估，零审批、零工单。该阶段门禁为后端 392 条、Ruff、125 文件格式检查、mypy 59 个源文件，以及前端 12 文件/25 条测试和生产构建全部通过。后续 Redis/OpenTelemetry、跨业务评测/Compose 和本地发布学习交付现已完成；真实模型与公网交互仍未完成。 - -## 最新核验：公开作品集 Netlify 静态镜像已完成生产部署验证 - -2026-07-19 已将 `D:\CODEX\resume\portfolio` 的 SSR 首页导出为独立静态镜像并部署至 。单页刷新后无内部 hash 导航，四项目依次为 OperCerta、ForenTrail、SiteVerum、Federune；后三项诚实标记未启动。源作品集契约 3/3、镜像契约 8/8、真实构建与静态导出均通过。production deploy `6a5c986587eaef5b3156f49b` 实测 200，邮箱、电话和 public GitHub 均存在。该镜像不提供 OperCerta API 或写入能力；原产品发布门禁仍为 `CLOSED`。证据见 `docs/release-evidence/portfolio-netlify-static-mirror.md`。 - -## 最新核验：公开静态项目专题已完成生产部署验证 - -2026-07-18 已把 Vite 根路径调整为不依赖后端的静态项目专题，`/console` 保留真实本地演示；公开主机未配置 API 时只显示本地启动说明，不提供公网写入。专题已部署至 。线上标题、JS/CSS 指纹、两张 PNG 证据图和 `/api/*` 静态回退均已验证。个人作品集入口当时只完成本地构建；2026-07-19 已通过上节所述的独立 Netlify 静态镜像完成公开部署。2026-07-19 最终本地门禁为后端 342 条、Ruff、105 文件格式检查、mypy 50 个源文件、安全扫描、前端 11 文件/24 条测试及生产构建全部通过。PR #4 run `29652818349` 四个快速 job 成功并合并为 `0f262e0`；main run `29652991288` 五个 job（含 Compose smoke 与 API/MCP 重启恢复）全部成功。原产品发布门禁仍为 `CLOSED`。 - -## 最新核验：GitHub Actions 分层 CI 已完成 - -2026-07-18 已建立 Private `KXHXK/opercerta` 和只读、固定 Action SHA 的分层 Actions。PR `#1` run `29642286517` 的四个快速 job 成功，`compose-smoke` 按设计跳过；main run `29642363033` 的五个 job 全部成功，远程实测后端 `339 passed in 29.46s`、前端 9 个测试文件/15 条测试、Ruff、104 文件格式检查、mypy 50 个源文件、Compose 业务 smoke、API/MCP 重启恢复与无条件清理。Private 分支保护 API 因当前账户能力返回 HTTP 403，未启用并采用人工 PR 全绿后合并规则。证据见 `docs/release-evidence/github-actions-ci.md`；发布门禁保持 `CLOSED`。 - -## 最新核验：可观测性与安全回归基础已完成 - -2026-07-18 已实现服务端 `request_id`、异常后上下文清理、安全 JSON 日志、应用级低基数 Prometheus 指标、SSE 实际回放计数与默认关闭的 `/metrics`。完整后端门禁为 `332 passed in 74.58s`；Ruff clean；100 个文件格式正确；mypy 检查 50 个源文件无问题。前端防回退仍为 9 个测试文件、15 条测试通过且构建成功。证据见 `docs/release-evidence/observability-security-regression.md`；发布门禁保持 `CLOSED`。 - -## 最新核验：单页运营控制台已完成本地前端验证 - -2026-07-18（Asia/Shanghai）新增 Vite + React 单页运营控制台：内存演示 JWT、operator 创建处置、详情读取、approver 绑定审批、fetch SSE 审计快照回放与明确的 CLOSED 门禁均已实现。前端门禁实测为 9 个测试文件、15 个测试通过，生产构建通过。同轮后端回归为 `325 passed in 91.25s`，Ruff/format/mypy 均通过。该证据只证明客户端编排、构建及本机回归；不替代完整浏览器端到端或公开发布。详见 `docs/release-evidence/single-page-console.md`。 - -## 最新核验：JWT/RBAC 与固定契约评测已完成 - -本地短时 JWT 与四角色 RBAC 已实施，审批主体只从 JWT `sub` 取得。库存补货固定合成契约评测当前有效版本为 `replenishment-v3`：真实 FastAPI、FastMCP、PostgreSQL 与恢复夹具运行 30 条，30 passed、0 failed。已新增 SSE 审计快照回放与 `Last-Event-ID` 续传；全量 pytest 为 325 passed。详见 `docs/release-evidence/demo-jwt-rbac.md`、`docs/release-evidence/replenishment-contract-evaluation.md` 和 `docs/release-evidence/sse-audit-replay.md`。 - -历史核验：2026-07-20 Asia/Shanghai；旧解释型真实模型路径、当时主线 CI/Compose、静态专题和作品集生产同步已完成。新 Agent 核心结论以本文顶部 2026-07-22 记录为准，产品发布门禁仍为 `CLOSED`。 - -## 当前阶段 - -可靠性内核、库存补货、设备维修、作业异常恢复、三业务单页控制台、本地 Caddy 发布候选、Mock Agent 与真实 RAG 已完成代码和本机运行门禁。后端已覆盖严格输入、证据与计划、绑定审批、真实 MCP 读写、批准后重取事实、写后读验证、拒绝、过期、A/B 重启恢复以及 FastAPI 查询/创建/审批。旧解释型真实模型路径有历史证据，但新 Plan-and-Execute Kimi Tool Calling 尚未通过。公网交互与生产治理仍未完成，发布门禁保持关闭。 - -## 已验证事实 - -- 非法输入契约提交：`642fc2f`。 -- 确定性状态恢复策略提交：`8bcf7c3`。 -- 单元测试命令 `uv run pytest tests/unit -q` 于 2026-07-15 退出码 0，结果为 `19 passed`。 -- Windows 原生 PostgreSQL 环境设计提交：`d506c8c`；本机端口固定为 `127.0.0.1:55432`，规格修正提交：`51c1583`。 -- 原生 PostgreSQL 环境实施计划提交：`85c04d1`。 -- 开发日志与文档索引设计提交：`a0564b1`；日志初始化计划提交：`6c97d5d`。 -- 开发日志已初始化：`f70411f`；根目录 `DOCUMENT_INDEX.md` 已创建并列出已有文档与计划创建的证据目录，提交：`b29e2a2`。 -- PostgreSQL 18.4 已安装并验证：服务 `postgresql-x64-18` 为 `Running/Automatic`，唯一监听为 `127.0.0.1:55432`，普通 IPv4 回环使用 SCRAM，真实连接探针使用 `opercerta_test`/`opercerta` 成功。 -- 默认 `uv run mypy` 已实际检查 5 个源文件并通过；PEP 561 标记修复提交：`84a7b08`。 -- 审批领域契约设计已确认并提交：`3c55f3b`；批准与拒绝均先原子进入 `resuming`，再由恢复节点路由。 -- 审批领域契约实现提交：`b87ef7f`；目标测试先因缺失模块 RED，再以 `10 passed` GREEN；完整单元测试为 `29 passed`，Ruff 通过，mypy 实际检查 6 个源文件通过。 -- PostgreSQL 可靠性 Schema 与迁移提交：`85e6538`；Alembic 当前版本为 `0001_reliability_kernel (head)`。 -- 原子审批 Repository 提交：`b37a659`；数据库集成测试 `5 passed`，完整测试 `34 passed`，Ruff 通过，mypy 实际检查 10 个源文件通过。 -- 十路审批竞态目标用例独立重复 20 轮，实测 `20/20` 通过；每轮断言一个成功、九个冲突、一条审批、一条审计和 `resuming` 状态。 -- 本地测试数据库密码已于 2026-07-15 轮换；不回显探针确认 `opercerta_test`/`opercerta`、`127.0.0.1:55432` 可连接，轮换后完整测试 `34 passed`、Ruff 和 mypy 通过，新密码未出现在 Git 跟踪文件中。 -- 2026-07-16 重启 Codex 后，PowerShell、OperCerta 工作区和 `.git` 临时写入探针均成功，探针已清理，`main` 工作区恢复干净。 -- Task 4 方案 1、`created` 初始状态和完整书面契约均已获用户确认；契约见 `docs/superpowers/specs/2026-07-16-work-order-idempotency-contract-design.md`。 -- Task 4 聚焦计划见 `docs/superpowers/plans/2026-07-16-work-order-idempotency.md`；规格覆盖、占位文本、类型命名和 Python 代码块语法已自审，计划中的 Pydantic JSON 边界烟雾检查通过，但这些不是生产实现通过证据。 -- Task 4 领域 RED 因新错误契约缺失而退出 1，Repository RED 因模块缺失而退出 1；对应 GREEN 分别为 `27 passed` 和 `12 passed`。 -- Task 4 数据库集成测试为 `17 passed`，完整测试为 `73 passed`，Ruff lint、全量 format check 和 mypy（12 个源文件）通过。 -- 工单十路并发目标用例以 20 个独立 Pytest 进程复验，实测 `20/20`；每轮断言一次创建、九次安全重放、同一 ID、一行工单和一条创建审计。证据见 `docs/release-evidence/work-order-idempotency.md`。 -- Task 5 已确认复用 `operations.request_payload` 的 `schema_version=1` 快照，不新增数据库迁移；审批落库后同时覆盖批准和拒绝恢复；状态与终态审计由独立 `OperationStateRepository` 原子写入。 -- 本地锁定版本核验：`AsyncPostgresSaver.from_conn_string` 提供 async context manager，`setup()` 必须显式调用；`LANGGRAPH_STRICT_MSGPACK` 在 `langgraph-checkpoint==4.1.1` 源码中有效，并需在默认 serializer 构造前设置。 -- 风险分级复核只减少用户对内部技术细节的形式审批，不减少工程文档；规格、计划、RED/GREEN、故障诊断、数据库与重启证据、静态检查、迁移回滚、未完成范围和风险必须继续在本地留痕并纳入 Git。 -- Task 5 聚焦计划已把快照领域模型、原子状态仓储、独立 checkpointer、JSON-only 图、RecoveryCoordinator、批准/拒绝与四点 A/B 重启矩阵拆成六个可提交阶段；占位匹配为零，14 个 Python 代码块语法编译通过。这是计划自审，不是生产实现或测试通过证据。 -- Task 5 快照领域 RED 因稳定错误缺失退出 1；GREEN focused 为 `48 passed`、单元全集为 `77 passed`，Ruff/format 与 mypy（14 个源文件）通过，提交 `8fb054e`。 -- Task 5 状态仓储 RED 因 Repository 模块缺失退出 1；GREEN focused 为 `7 passed`、数据库集成为 `24 passed`，Ruff/format 与 mypy（15 个源文件）通过，提交 `5bdacf7`。 -- Task 5 checkpointer RED 因模块缺失退出 1；DSN 回归还真实发现 `+` 空格编码不兼容与 URL 密码残留。修复后 focused 为 `4 passed`，与数据库回归合并为 `28 passed`，Ruff/format 与 mypy（16 个源文件）通过，提交 `e9b2834`。 -- Task 5 reliability graph RED 因 workflow 模块缺失退出 1；GREEN focused 为 `3 passed`、workflow 集成为 `7 passed`，Ruff/format 与 mypy（18 个源文件）通过。测试断言 interrupt 时零审批、零工单，并覆盖无崩溃的批准完成与拒绝终止；提交 `2e6cbb4`。 -- Task 5 RecoveryCoordinator RED 因模块缺失退出 1；GREEN focused 为 `8 passed`、workflow 集成 `15 passed`，四点矩阵使用完全关闭的 saver A/graph A 与新 saver B/graph B。十个独立 Pytest 进程实测 `10/10`，每轮 `8 passed`。 -- Task 5 完整新鲜门禁为 `116 passed in 9.96s`；Ruff lint 通过、32 个文件 format check 通过、mypy 检查 19 个源文件通过。证据见 `docs/release-evidence/langgraph-restart-recovery.md`，实现提交 `e93b551`。 -- Task 6 新鲜总门禁：依赖冻结同步成功；完整测试 `116 passed in 8.76s`；Ruff、32 文件 format check、mypy（19 个源文件）通过；secret-safe Alembic downgrade→upgrade 后为 `0001_reliability_kernel (head)`，迁移后集成测试 `39 passed in 8.74s`。 -- 可靠性内核按既定权重已达到 100% 的阶段完成口径；这只表示 Task 1–6 本地门禁完成，不是完整 OperCerta 发布进度、生产指标或对外效果数字。 -- 首个业务闭环确认采用确定性库存规则：`available = on_hand - reserved`，不足条件为 `available < reorder_point`，建议补货量为 `target_stock - available`；正常库存零审批、零工单。 -- 所有补货写入强制审批；证据不可用时安全关闭；审批绑定证据 ID、规则版本、事实哈希、计划哈希和建议数量，批准后写入前必须重新取证并比较事实。 -- 纵向切片采用独立 FastMCP 服务、四个真实 MCP 工具、Mock 结构化模型、LangGraph 和 FastAPI；React、SSE、JWT、真实模型与公开部署不在本轮。 -- 设计规格见 `docs/superpowers/specs/2026-07-16-inventory-replenishment-vertical-slice-design.md`。这是已确认设计，不是功能完成或测试通过证据。 -- 实施计划见 `docs/superpowers/plans/2026-07-16-inventory-replenishment-vertical-slice.md`，拆为领域规则、`0002` 数据边界、绑定审批、真实 FastMCP、类型化 MCP 客户端、审批前 workflow、审批后执行与恢复、FastAPI、总门禁九个原子 Task。 -- 2026-07-16 核验官方 PyPI 与本地锁定 API：MCP Python SDK `1.28.1`、FastAPI `0.139.0`、HTTPX `0.28.1`、LangGraph `1.2.9`、`langgraph-checkpoint-postgres 3.1.0`、Pydantic `2.13.4`、SQLAlchemy `2.0.51`、Alembic `1.18.5` 均无需在本切片升级；FastMCP Streamable HTTP、`ClientSession` 和 HTTPX `ASGITransport` 的实际签名已用于计划。 -- 库存补货 Task 1–6 已分别完成严格领域规则、`0002` 数据边界、绑定审批、真实 FastMCP 四工具、类型化 MCP gateway 和审批前 LangGraph；实现提交依次归档于 Git 历史。 -- Task 7 图测试先取得 4 个失败：批准、拒绝、事实变化与写后读不一致均停在原有 `resuming`，证明审批后分支缺失；实现后图 focused 为 `10 passed`。 -- Task 7 恢复测试先因 `operation_runner` 模块缺失在收集阶段退出 1；实现补货专用恢复协调器与 Runner 后，A/B restart focused 为 `7 passed`。 -- 批准后执行会重新读取库存与规则、保存 refresh evidence、使用原批准说明重建确定性计划，并只比较规则版本、事实哈希、计划哈希和数量；不覆盖原批准计划，也不再次调用模型。 -- 拒绝路径零工单；事实变化以 `approval_snapshot_mismatch` 失败；工单回读 ID、operation ID、payload 或 payload hash 不一致时以 `work_order_verification_failed` 失败。 -- 工单预写恢复返回原工单 ID、最终 graph state 为 `replayed=True`，数据库保持一行工单和一条 `work_order_created`；过期扫描在恢复前把到期等待操作终止为 `expired`。 -- Task 7 工作流全集为 `32 passed in 26.63s`；A/B restart 测试串行重复 10 次，每次 `7 passed`，共观察到 70 个恢复用例通过，不解释为生产成功率。 -- Task 7 最终新鲜门禁：完整测试 `275 passed in 43.78s`；Ruff `All checks passed!`；60 文件 format check 通过；mypy 检查 32 个源文件通过。实现提交 `9b830d2`，证据见 `docs/release-evidence/replenishment-execution-restart.md`。 -- Task 8 首次 API RED 因 `opercerta.api` 缺失在收集阶段退出 1；三条 API、严格模型和错误映射实现后 focused 首次为 `6 passed`。 -- API 查询显式返回 `approval_binding`，客户端用其六个精确字段提交绑定审批；批准完成、拒绝零工单、重复审批、过期、旧绑定失配、库存缺失和固定 503 均有 HTTP 回归。 -- API 边界额外拒绝非 `create_work_order + inventory + object_id` 请求；该回归先观察到设备查询错误返回 `202` 并创建失败 operation，修正后固定返回安全 `422`。 -- OpenAPI 回归先证明 `created_at: object` 缺少 `date-time` format；收紧为 timezone-aware `datetime` 类型后 focused 恢复通过。 -- 生产 factory 从环境读取数据库 URL、MCP URL、超时、审批 TTL 和 `mock` 模式；不自动迁移 Schema 或调用 checkpointer `setup()`，启动执行一次恢复扫描，关闭释放 Engine/checkpointer。 -- 生产 lifespan 资源自审先证明 Engine 构造失败会遗留临时 `PGPASSWORD`；将 Engine 构造纳入 `try/finally` 后，错误路径恢复原环境的回归通过。 -- Task 8 API focused 最终为 `8 passed in 10.11s`；MCP + workflow + API 回归为 `55 passed in 40.77s`；完整测试为 `283 passed in 55.73s`；Ruff、65 文件 format check、mypy（35 个源文件）通过。实现提交 `c4ac3ab`。 -- Task 9 `uv sync --frozen --all-groups` 成功；初始完整测试为 `283 passed in 57.94s`，文档完成后提交前复验为 `283 passed in 56.41s`；Ruff clean；68 文件 format check；mypy 检查 35 个源文件通过。 -- secret-safe Alembic 已完成 `0001_reliability_kernel` 降级与 `0002_inventory_replenishment (head)` 恢复；迁移后集成测试 `131 passed in 55.39s`。 -- 绑定审批十路竞态以 10 个独立 Pytest 进程复验 `10/10`；补货 A/B 重启恢复以 10 个独立进程复验 `10/10`，每轮 `7 passed`。不解释为生产指标。 -- 真实传输使用独立 FastMCP 服务、独立 FastAPI 服务和独立客户端进程；四工具名称精确匹配。低库存创建为 `awaiting_approval`，绑定数量 `18`，批准后 `completed`，重复审批 HTTP `409`。 -- 同一真实 operation 的 PostgreSQL 查询确认一条审批、一条工单；最后四个审计事件为 `execution_started → work_order_created → verification_started → operation_completed`；测试 checkpoint 和业务行随后清理。 -- 真实服务首次启动在业务调用前失败，根因是 Uvicorn 0.51 Windows 单进程默认 `ProactorEventLoop` 与 Psycopg async 不兼容。读取本机 Uvicorn loop factory 后，最小验证证明显式 `asyncio:SelectorEventLoop` 可启动，再完成三进程闭环。未修改业务实现。 -- Task 1–9 总证据见 `docs/release-evidence/inventory-replenishment-vertical-slice.md`。 - -## 当前阻塞与风险 - -- Redis 只读缓存、OpenTelemetry Trace、真实模型 adapter 与代表性运行、Redis 8.8/三业务 Compose、跨业务固定评测和本地 Caddy 发布候选已完成；生产 IAM/SSO、公网 HTTPS、限流/备份和公开 API 尚未完成。只读静态专题和独立静态作品集镜像已完成部署，发布门禁保持关闭。 -- Windows 原生真实服务需要显式 Selector loop；WSL2 Ubuntu Compose 已验证默认 Linux 容器进程、健康检查、MCP 服务名访问、独立 PostgreSQL volume 和 API/MCP 重启，但这不代表高可用或生产承诺。 -- Docker/Linux 运行时已修订为 WSL2 → Ubuntu 26.04 LTS，不使用 Docker Desktop 或 Hyper-V VM。Ubuntu 官方仓库的 Docker `29.1.3`、Compose `2.40.3`、Buildx `0.30.1` 已安装；Docker Hub 直连超时后，经用户授权配置了三个可达的第三方 registry mirror。OperCerta Compose 已通过构建、健康、真实业务数据库断言与重启恢复；完整证据见 `docs/release-evidence/docker-linux-runtime.md`，供应链例外见 `docs/superpowers/specs/2026-07-17-wsl2-runtime-amendment-design.md`。 -- 一次预期失败的 Pytest/Psycopg traceback 曾展开旧的本地测试数据库连接密码；代码、Git 和文档未保存该值，fixture 已改为无密码 URL + 临时 `PGPASSWORD`，角色密码也已轮换和复验。 -- 2026-07-16 checkpointer 首次 GREEN 的 Psycopg 连接失败 traceback 再次展开当时的本地测试角色密码。新封装已改为无密码 DSN、临时 `PGPASSWORD` 和 `%20` query 编码，代码/Git/文档未保存该值；用户随后同步轮换 PostgreSQL 角色与 `.env.local`，focused checkpointer 回归新鲜 `4 passed`。 -- 当前 GitHub 仓库 `KXHXK/opercerta` 已由用户改为 public，公共 API 已复验。`main` branch protection 端点当前返回 HTTP 404，说明保护规则尚未配置；在配置前仍人工坚持 PR、快速 job 全绿后合并，并在合并后核验 `compose-smoke`。 - -## 下一步 - -继续只实施 OperCerta。Real Kimi replan、provider 异常 operation 原子收口、Draft PR 快速 Actions、inline 合并前审查和本地凭据轮换验证已完成。下一步进行用户手动演示/口述掌握检查与 PR 合并审批，合并后执行 main Compose。生产 IAM/限流/备份、自动部署和 Release Tag 尚未完成。 - -## 发布门禁 - -`OperCerta production release gate: CLOSED`。当前证据证明三业务本地 Mock Agent、真实 FastEmbed/pgvector RAG、Agent Trace、审批/幂等/恢复、单页控制台、历史静态展示、replan/异常原子收口、Draft PR 快速 CI 和凭据轮换；新 Agent 核心的 Real Kimi 完整 Compose 稳定通过、合并/main Compose、生产身份、公网 HTTPS 后端、限流/备份、自动部署、用户掌握和 Release Tag 仍待完成。求职演示发布门禁不能与生产门禁混用。 - -## 2026-07-25 异常信号历史对账待办 - -- 当前本地持久卷的三条关联 operation 均为 `expired`，但库存与任务 signal 仍为 `investigating`；设备 signal 已为 `attention_required`。 -- 代码当前终态契约是 `completed/rejected → resolved`、`aborted/expired/failed → attention_required`，新路径测试已通过；旧卷状态形成于该映射上线前，尚无启动 backfill/reconciliation。 -- 该问题不会否定新事务映射，但会使人工演示误以为仍在调查。下一实现任务应先为历史对账写 RED 测试，再实现启动对账或显式管理动作，并验证幂等、审计和重启恢复。 -- 同时存在失败恢复入口缺口：`attention_required` signal 当前只能查看关联处置，同一事实哈希的再次扫描又会命中原去重行。下一规格需在“受控 reopen”与“创建带 lineage 的 superseding signal”之间作出选择，并覆盖并发重试、旧审批失效和审计链。 -- 在修复并重新验证前，不把当前旧卷作为完整成功闭环证据，发布门禁继续保持 `CLOSED`。 - -## 2026-07-25 异常信号历史对账与后继调查已完成 - -- 上述待办已通过独立规格和 TDD 实现，不删除历史行：production 先恢复 operation，再把历史 `investigating` signal 对账为 `resolved` 或 `attention_required`。 -- 新增 `0008_signal_successor_lineage`、唯一 predecessor 约束、幂等启动对账、operator-only retry API 和 React 后继谱系展示。 -- 旧持久卷三个根 signal 已全部对账为 `attention_required`，三条旧 operation 仍为 `expired`。 -- 库存 predecessor `57cb635c-07bb-41b3-bd7e-b579b810bb01` 已创建 successor `2cef23d3-1b30-436b-82b0-7a29125c6372` 和 operation `157347ee-ba5b-4911-bfe9-3f64a47ad162`；API/MCP 重启后仍为 `awaiting_approval`，重复 retry 为 HTTP 409。 -- 新鲜门禁：完整后端 `607 passed in 329.96s`；前端 18 文件 `58 passed` 且 build 成功；Ruff、format 199 文件和 mypy 80 个源文件通过。 -- 当前关键节点是人工审批新 operation；未 commit、未 push、未 merge，Real Kimi 未在本轮调用，生产发布门禁仍为 `CLOSED`。 - -## 2026-07-26 单根 Agent 图实施状态 - -- Task 1–3 已建立严格 AgentTurn、统一 Observation/Redis 语义和库存单根 ToolLoop。 -- Task 4 已把批准后强制刷新、模型 Verifier、确定性事实绑定、拒绝/二次审批、安全失败、幂等工单和写后读接入同一 `operation_id/thread_id` 的根图。 -- 一次性 PostgreSQL/MCP 根图用例 `11 passed`；完整单元 `386 passed`；Ruff、Mypy 81 个源文件与 diff 检查通过。 -- 这仍是显式 `enabled=True` 的内部候选；默认 FastAPI/Compose 仍走旧多图路径，设备与任务尚未接入共享根图。 -- 当前执行 Task 5：把设备维修与阻塞任务收敛为策略，不复制生命周期编排。Real Kimi、默认路径切换、旧图删除、公开部署、commit/push/merge 均尚未发生，发布门禁为 `CLOSED`。 - -## 2026-07-26 Task 5 更新 - -- 库存、设备维修和阻塞任务已共用通用根图入口和完全相同的生命周期节点。 -- 场景差异只存在于策略函数：允许的 MCP 事实工具、对象键、证据/评估/计划类型、审批 binding 和工单 payload。 -- 一次性 PostgreSQL/MCP 的三场景根图测试合计 `20 passed`；完整单元 `386 passed`；Ruff、Mypy 82 个源文件与 diff 检查通过。 -- 默认运行入口仍未切换，旧图仍在；下一步为 Task 6 case projection API，生产发布门禁继续 `CLOSED`。 - -## 2026-07-26 Task 6 更新 - -- 后端新增 `/api/v1/signal-cases`，实时投影“一对象一 case”，包含当前 signal、当前 operation、历史计数和有序 lineage。 -- `/signals/scan` 返回本次受影响 case；原始 `/signals` 保留，不迁移或复制业务事实。 -- PostgreSQL signal API 用例 `4 passed`，目标静态检查通过。React 尚未消费新接口，当前执行 Task 7。 - -## 2026-07-26 Task 7 React case 工作台更新 - -- React 已从平铺 signal 列表迁移为按 `case_key` 聚合的一对象一主卡；选中、加载、错误、打开处置和历史展开均只作用于当前卡片。 -- 真实浏览器扫描显示三类业务各一张主卡，单独展开任务历史时全页只有一个“收起历史”。验收同时发现并修复了 case current 选择缺陷：有 successor 后不得回退到仍为 `attention_required` 的祖先，当前事实永远是 lineage 叶节点。 -- 前端 19 个文件共 `60 passed` 且生产构建成功；signal API `5 passed`，目标 Ruff/Mypy 通过。API 镜像已重建；重建后的浏览器 reload 被本地 URL 安全策略阻止，未虚构最终浏览器复验结果。 -- 默认 API/Compose 尚未切到新根图；下一步执行 Task 8 新旧路径等价与旧编排收敛，生产发布门禁保持 `CLOSED`。 - -## 2026-07-26 Task 8–11 单根运行时与最终本地门禁 - -- production factory 已切换为只构造一个 `ControlledAgentRootGraph`；首次运行和重启恢复都通过同一 root runner/coordinator。历史图模块仅供回归与等价测试，产品运行时不存在隐藏 fallback。 -- 三业务新旧路径等价测试 `3 passed`；production lifespan `2 passed`；核心 API/root/equivalence 合集 `41 passed`。同时修复恢复时把失败 read observation 重新提交、触发 `duplicate_tool_call` 的缺陷：成功或失败 Observation 都计入 attempted，证据不完整时最终分析 fail closed。 -- Task 9 本地总门禁：单元 `392 passed`，完整集成 `260 passed`，前端 19 个文件 `60 passed` 且 build 成功，Ruff/format/Mypy（85 个源文件）通过。隔离 Compose 的三业务、RAG、数据库断言和 API/MCP 重启恢复通过，临时环境已清理。 -- Task 10 少量真实 Kimi 代表验证完成：三业务各一次只读、库存一次批准写入、无效 provider 一次 fail-closed。真实路径没有回退 Mock；证据不保存 API key、完整 prompt、模型原文或隐藏推理。 -- 真实门禁暴露并修复三项 Mock 无法发现的兼容问题：LLM 错用 MCP 2 秒 timeout；Kimi 强制 tool calling 需关闭 thinking；通用 structured output 在 Final Analysis/Verifier 上波动。现由独立 90 秒模型 timeout、provider 配置和两个内部原生提交工具收口。 -- Task 11 学习文档、事故复盘、实施证据、每日日志、handoff 和根目录唯一文档索引已更新。当前仅剩外部审批动作与生产能力：commit/push/PR/merge、公开交互部署、生产 IAM/限流/备份/自动发布/Release Tag。 -- 文档完成后的最终复验为完整单元 `395 passed`、受影响隔离 PostgreSQL 集成 `32 passed`、Ruff/213 文件 format check/Mypy 85 个源文件/仓库安全全绿；同步 worktree 当日日志后文档索引核对 544 份、零漏项。 -- 生产发布门禁保持 `CLOSED`；未启动 ForenTrail。 +正式门禁定义见 `docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md`。 diff --git a/docs/development-log/daily/2026-07-31.md b/docs/development-log/daily/2026-07-31.md index ee128c0..55c4ad0 100644 --- a/docs/development-log/daily/2026-07-31.md +++ b/docs/development-log/daily/2026-07-31.md @@ -58,3 +58,16 @@ - 恢复 `README.md`/`README.zh-CN.md` 与 `CONTRIBUTING.md`/`CONTRIBUTING.zh-CN.md` 两组标准语言文件，顶部统一显示 `English｜简体中文`；点击后切换文件，每个页面只渲染一种语言，不再出现下拉箭头。 + +## Showcase 双门禁与本人掌握收口 + +- 正式批准 `docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md`：当前版本定义为“公开静态展示 + 本地可复现完整 Agent MVP + 3–5 分钟录屏”，不再把公网可写后端作为 Showcase 阻塞项，也绝不把静态页面误报为公网交互产品。 +- 工程与本地自动化门禁保持 `PASSED`；Showcase Release 改为 `AWAITING_OWNER_VALIDATION`；Product Release 保持 `CLOSED`。 +- 新增 `docs/learning/opercerta-ownership-acceptance.md`，明确环境、库存完整闭环、代码链路、重启/幂等和分层讲解五组人工验收，必须记录 operation、work order、Trace、审计和数据库事实，且不得由 Codex 自动代签。 +- 新增 Apache-2.0 `LICENSE`；Dockerfile 的 uv 从 `0.10.10` 统一为本地/CI 使用的 `0.11.28`；仓库安全扫描覆盖双语 README/CONTRIBUTING、handoff 与索引。 +- 将 `current-state.md` 和 `IMPLEMENTATION_HANDOFF.md` 从历史堆叠改为当前权威快照，防止上下文压缩或换机后继续依据过期 PR、测试数和门禁状态推理。 +- 收口分支为 `release/showcase-ownership-closeout-20260731`。本分支完成 PR、main CI 与 Compose 复验后，进入本人验收和录屏；只有二者完成后才创建最终 Showcase tag。 +- 定向发布契约 `30 passed`；Ruff、216 文件格式、mypy 85 个源码文件、仓库安全和 122 份文档索引均通过；使用仅绑定 `127.0.0.1:55432`、退出自动删除的一次性 pgvector PostgreSQL 运行完整后端，结果为 `671 passed in 112.07s`。 +- 三业务固定评测脚本通过（pytest wrapper `1 passed`），冻结 Agent 安全/恢复评测 `9/9`；前端 19 文件/60 条和 Vite production build 通过。 +- 本机重建应用镜像等待 `ghcr.io/astral-sh/uv:0.11.28` 层超过 5 分钟后超时，本地未缓存该镜像，未把本次容器构建记为通过；最终容器结论必须来自合并后 GitHub main-only Compose smoke。 +- ForenTrail 暂不启动；FieldPilot 在 OperCerta 完成并真正掌握后另行推进，不混入本仓库。 diff --git a/docs/learning/opercerta-ownership-acceptance.md b/docs/learning/opercerta-ownership-acceptance.md new file mode 100644 index 0000000..c006f12 --- /dev/null +++ b/docs/learning/opercerta-ownership-acceptance.md @@ -0,0 +1,151 @@ +# OperCerta 项目所有权与演示验收 + +## 1. 验收目的 + +本验收把“代码和文档已经完成”转化为“项目所有者能够独立运行、定位、解释和演示”。 +自动化测试可以证明系统行为，但不能证明个人掌握。本文件的完成状态不得由 Codex 自动代签； +必须由项目所有者亲自操作、先回答，再由 Codex 根据实际输出纠错。 + +当前状态：`AWAITING_OWNER_VALIDATION`。 + +## 2. 通过规则 + +以下五组均为必做项，不使用可以被总分掩盖的加权评分： + +1. 能独立启动和停止环境，并解释每个服务的职责。 +2. 能完成一个库存短缺到补货工单的完整业务闭环。 +3. 能沿真实代码解释 Agent、工具、审批和数据库边界。 +4. 能执行一次重启恢复或幂等实验，并解释为什么不会重复写入。 +5. 能完成 30 秒、3 分钟、10 分钟口述和 3–5 分钟录屏。 + +可以查命令帮助，但不能只照读答案。首次回答错误不算失败；纠正后必须重新脱稿回答。 + +## 3. 验收一：环境与服务 + +在 WSL2 中执行： + +```bash +cd /mnt/d/CODEX/agent-portfolio/opercerta +docker compose -p opercerta-demo ps +curl -fsS http://127.0.0.1:8080/health/ready +``` + +本人必须解释： + +- PostgreSQL 为什么是权威业务事实和 checkpoint 存储，而 Redis 不是； +- FastAPI、MCP、LangGraph 分别处于哪一层； +- 为什么 MCP 和数据库不直接暴露到公网； +- readiness 中每个依赖失败时系统应如何处理。 + +验收证据：命令输出、本人解释摘要、验收日期。 + +## 4. 验收二：完整库存业务 + +浏览器打开 `http://127.0.0.1:5173/console`，本人依次完成： + +1. 使用 operator 扫描业务异常； +2. 打开库存短缺 case，启动 Agent 调查； +3. 观察 Goal、模型决策、MCP Observation、SOP citation 和 Agent Trace； +4. 切换 approver，核对绑定事实后批准； +5. 切换 auditor，确认新鲜事实复核、唯一工单、写后读和终态审计。 + +必须记录： + +```text +operation_id: +work_order_id: +最终状态: +审批绑定中的三个关键字段: +Verifier 结论: +最后四个审计事件: +``` + +本人必须解释：为什么不能在扫描前直接创建写操作；为什么批准后仍要重新取证；为什么 LLM +不能直接写 PostgreSQL。 + +## 5. 验收三：代码链路 + +按实际执行顺序找到并解释下列入口： + +1. `web/src/App.tsx`：页面状态和角色切换； +2. `src/opercerta/api/app.py`：协议、JWT/RBAC 和安全错误； +3. `src/opercerta/application/signal_detection.py`：异常信号感知； +4. `src/opercerta/application/controlled_agent_root_runner.py`：运行和恢复入口； +5. `src/opercerta/workflow/inventory_agent_root_graph.py`：唯一 LangGraph 生命周期； +6. `src/opercerta/infrastructure/langchain_model_gateway.py`：真实模型 Tool Calling； +7. `src/opercerta/agent/tool_policy.py`：工具 allowlist 和参数约束； +8. `src/opercerta/infrastructure/mcp_gateway.py`：MCP 传输与类型校验； +9. `src/opercerta/infrastructure/db/approval_repository.py`：审批竞态； +10. `src/opercerta/infrastructure/db/work_order_repository.py`：幂等写入。 + +本人必须独立画出并讲解： + +```text +React → FastAPI → Signal → LangGraph → LLM → Tool Policy → MCP + → Observation/RAG → LangGraph → HITL → Fresh Facts/Verifier + → Idempotent Write → PostgreSQL → Trace/Audit → React +``` + +## 6. 验收四：故障与恢复 + +在一个处置处于 `awaiting_approval` 时执行： + +```bash +docker compose -p opercerta-demo restart api mcp +curl -fsS http://127.0.0.1:8080/health/ready +``` + +刷新页面并继续原处置。本人必须说明： + +- LangGraph checkpoint 保存什么； +- 业务表保存什么； +- 为什么节点可能重放，但业务工单仍有效一次； +- 重复审批为什么返回冲突； +- Redis 丢失为什么不应改变批准后的权威事实。 + +验收证据：重启前后同一 `operation_id`、最终 `work_order_id` 和零重复写入结论。 + +## 7. 验收五：口述与录屏 + +### 30 秒 + +只讲业务问题、Agent 价值、三业务和当前发布边界。 + +### 3 分钟 + +讲清业务动机、Agent 循环、MCP/RAG、HITL、幂等/恢复、测试证据和限制。 + +### 10 分钟 + +结合代码讲清状态机、模型边界、工具协议、PostgreSQL 事务、Redis 缓存、Trace 与一次真实故障。 + +### 3–5 分钟录屏 + +必须包含： + +- 10–20 秒说明业务问题； +- 扫描异常和启动库存调查； +- Agent Trace 中一次模型决策、一次 MCP Observation 和一个 RAG citation； +- approver 批准与 auditor 查看唯一工单； +- 一句话声明“公网是静态展示，完整 Agent 在本地 Compose 运行”。 + +视频不得出现密码、API key、`.env` 内容、手机号或无关桌面隐私。 + +## 8. 最终签收记录 + +以下内容只有完成实际验收后填写： + +```text +验收日期: +验证提交: +operation_id: +work_order_id: +重启恢复结果: +30 秒口述: 未验收 +3 分钟口述: 未验收 +10 分钟口述: 未验收 +录屏文件或链接: +Showcase Release gate: AWAITING_OWNER_VALIDATION +``` + +全部通过后，更新当前状态、开发日志和 Release Evidence，再创建最终 Showcase Tag。 diff --git a/docs/superpowers/plans/2026-07-31-showcase-release-and-ownership-closeout.md b/docs/superpowers/plans/2026-07-31-showcase-release-and-ownership-closeout.md new file mode 100644 index 0000000..4e326ad --- /dev/null +++ b/docs/superpowers/plans/2026-07-31-showcase-release-and-ownership-closeout.md @@ -0,0 +1,46 @@ +# OperCerta Showcase Release 与 Ownership 收口实施计划 + +**规格依据：** `docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md` + +**目标：** 完成可自动化的 Showcase 候选收口，并进入必须由项目所有者亲自通过的验收 + +**排除：** 公网可写后端、生产 IAM、ForenTrail、FieldPilot 代码 + +## Task 1：用测试固定收口契约 + +- 为双门禁、Apache-2.0 许可证、最新测试数、ownership 手册和 Docker uv 版本添加 RED 测试。 +- 为 README 中文版和两份 Contributing 增加凭据扫描回归。 +- 保留 RED 输出作为“缺口真实存在”的实施证据。 + +## Task 2：实施发布治理 + +- 新增 Apache-2.0 `LICENSE`。 +- 把 Dockerfile 的 uv 与 CI 固定为 `0.11.28`。 +- 扩展仓库安全扫描到全部公共入口 Markdown。 +- 将 README 的后端门禁数字同步到最新 main 事实。 + +## Task 3：同步唯一当前事实 + +- 重写 `docs/development-log/current-state.md`，只保留当前权威状态与历史导航。 +- 重写 `IMPLEMENTATION_HANDOFF.md`，删除会误导新对话的旧“当前”状态。 +- 更新 2026-07-31 审计、每日日志和 `DOCUMENT_INDEX.md`。 +- 明确 Showcase、Product 和个人掌握三类状态。 + +## Task 4：建立 Ownership 验收 + +- 新增 `docs/learning/opercerta-ownership-acceptance.md`。 +- 要求项目所有者亲自完成环境、业务、代码、故障和口述五组验收。 +- operation/work-order 标识、截图、口述和视频只能来自本人实际操作，不得由 Codex 自动代签。 + +## Task 5：自动化门禁与合并 + +- 运行定向测试、仓库安全、文档索引、Ruff/format 和必要前后端门禁。 +- 通过 PR 合并 main，等待 main-only Compose smoke。 +- 不在人工验收前创建最终 Showcase Tag。 + +## Task 6：人工验收与最终 Tag + +- 项目所有者按手册完成一个完整库存闭环、一次重启恢复和一次代码讲解。 +- 完成 30 秒、3 分钟、10 分钟口述以及 3–5 分钟录屏。 +- 将验收日期、operation_id、work_order_id、视频位置和诚实边界写入开发日志。 +- 自动化与人工证据全部通过后创建最终 Showcase Tag，并记录回滚提交。 diff --git a/docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md b/docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md new file mode 100644 index 0000000..65dc19d --- /dev/null +++ b/docs/superpowers/specs/2026-07-31-showcase-release-gate-amendment-design.md @@ -0,0 +1,91 @@ +# OperCerta Showcase Release 门禁修订规格 + +**状态：** 2026-07-31 经用户批准，作为 `v0.1.x` 展示版本的有效修订 + +**适用范围：** 仅限 OperCerta；不启动 ForenTrail，不把 FieldPilot 纳入本仓库 + +**修订原则：** 降低公开托管成本，但不降低业务闭环、可靠性、证据和真实性要求 + +## 1. 修订原因 + +原始详细设计把“公网 URL 可完成真实核心业务”同时作为作品展示和产品上线条件。当前 +OperCerta 已具备公开静态展示、本地可复现完整 Agent MVP、固定评测、真实模型代表验证 +和 Docker Compose 重启恢复，但把可写 FastAPI、PostgreSQL、Redis、MCP 与模型服务长期 +暴露到公网，还需要生产身份、限流、防滥用、备份、告警和持续费用。 + +本修订把展示交付和生产上线拆成两个独立门禁，避免为了赶进度把静态页面误报为在线产品， +也避免把生产治理全部塞进求职展示版本。 + +## 2. 两类门禁 + +### 2.1 Showcase Release + +Showcase Release 定义为： + +> 公开静态展示 + 本地可复现完整 Agent MVP + 自动化工程证据 + 本人掌握验收 + 3–5 分钟录屏。 + +必须同时满足： + +1. GitHub 仓库公开，包含 README、许可证、锁文件、架构、限制和可复现命令。 +2. Netlify 静态页面可访问，展示真实业务流程、架构、技术栈和已验证证据。 +3. 本地 Docker Compose 能启动 PostgreSQL、Redis、MCP 和 FastAPI，并通过 readiness。 +4. 库存补货、设备维修、任务恢复共用一个生产 LangGraph 根生命周期。 +5. 固定评测、前后端测试、静态检查和 main Compose 重启恢复门禁全绿。 +6. 真实模型只做少量代表性兼容验证，不把样本包装成准确率、SLA 或成本结论。 +7. 项目所有者亲自完成 `docs/learning/opercerta-ownership-acceptance.md` 的必做验收。 +8. 完成 3–5 分钟录屏，展示业务动机、Agent Trace、审批、工单和当前边界。 +9. Tag 精确指向通过门禁的 main 提交，并保存回滚点和发布说明。 + +Showcase Release 允许表述： + +> OperCerta 是一个公开源码、通过 CI、可在本地单节点 Docker Compose 中复现三业务完整闭环 +> 的受控运营 Agent MVP；公网地址提供只读静态项目展示。 + +不得表述为“公网可操作 Agent”“生产系统”“高可用平台”或“真实企业 WMS/CMMS”。 + +### 2.2 Product Release + +Product Release 继续使用更严格的生产门禁，至少包括： + +- 真实 HTTPS FastAPI 公网入口和精确 Origin CORS； +- 生产身份生命周期、最小权限、会话吊销和审计； +- 限流、配额、模型费用熔断、防滥用和安全数据重置； +- 托管密钥、数据库备份、恢复演练、迁移编排和回滚； +- 日志、Trace、指标采集、Dashboard、告警和运行手册； +- 公网浏览器 E2E、并发、超时、失败恢复和安全验收； +- 明确容量边界，不声称未经验证的 SLA 或高可用。 + +在这些条件完成前，`Product Release gate: CLOSED`。 + +## 3. 对原始规格的覆盖关系 + +本修订只覆盖以下条款在 `v0.1.x Showcase` 中的解释： + +- 总体设计“在线地址可以完成核心演示”； +- OperCerta 详细设计“公网 URL 可以完成核心演示”； +- “未通过产品生产门禁前不得开始其他项目”不再阻止已批准的独立后续规划，但本轮用户明确 + 暂不启动 ForenTrail，先完成 OperCerta 和后续 FieldPilot。 + +原始规格中的 Agent 闭环、三业务、审批、幂等、恢复、评测、安全、真实性和不复用旧公司 +材料等要求全部继续有效。Product Release 的生产条件没有删除或降级。 + +## 4. 当前门禁状态 + +截至本修订创建时： + +- 自动化工程与本地 Compose 证据：通过； +- 公开静态展示：通过； +- 开源许可证、状态文档和最新 Release 收口：正在完成； +- 本人掌握验收与 3–5 分钟录屏：尚未验收； +- `Showcase Release gate: AWAITING_OWNER_VALIDATION`； +- `Product Release gate: CLOSED`。 + +只有本人验收和录屏完成后，才能创建最终 Showcase Tag。 + +## 5. 失败与回滚 + +- 任一自动化门禁失败：不合并 main，不创建 Tag。 +- 本人无法脱稿解释关键链路：回到对应学习模块和代码重新操作，不代签通过。 +- 录屏出现错误或夸大表述：删除候选视频并重录。 +- 公网静态部署异常：回滚到上一已验证 Netlify production deploy。 +- Product Release 条件未满足：始终保留静态公网与本地完整运行的边界说明。 diff --git a/scripts/verify_repository_safety.py b/scripts/verify_repository_safety.py index dc620f2..93d87f3 100644 --- a/scripts/verify_repository_safety.py +++ b/scripts/verify_repository_safety.py @@ -48,7 +48,15 @@ def _is_forbidden_path(path: Path) -> bool: def _is_content_scope(relative: str) -> bool: return ( - relative in {"README.md", "IMPLEMENTATION_HANDOFF.md", "DOCUMENT_INDEX.md"} + relative + in { + "README.md", + "README.zh-CN.md", + "CONTRIBUTING.md", + "CONTRIBUTING.zh-CN.md", + "IMPLEMENTATION_HANDOFF.md", + "DOCUMENT_INDEX.md", + } or relative == "docs/development-log/current-state.md" or relative.startswith("docs/release-evidence/") or relative.startswith("src/") diff --git a/tests/unit/runtime/test_container_assets.py b/tests/unit/runtime/test_container_assets.py index 51ce88c..b0d725a 100644 --- a/tests/unit/runtime/test_container_assets.py +++ b/tests/unit/runtime/test_container_assets.py @@ -58,6 +58,7 @@ def test_compose_pins_pgvector_and_persists_the_embedding_cache() -> None: def test_image_uses_locked_dependencies_and_non_root_user() -> None: dockerfile = Path("Dockerfile").read_text(encoding="utf-8") + assert "ghcr.io/astral-sh/uv:0.11.28" in dockerfile assert "uv sync --frozen --no-dev" in dockerfile assert "install -d -o opercerta -g opercerta /home/opercerta/.cache" in dockerfile assert "USER opercerta" in dockerfile diff --git a/tests/unit/runtime/test_release_assets.py b/tests/unit/runtime/test_release_assets.py index c67f911..bd128a2 100644 --- a/tests/unit/runtime/test_release_assets.py +++ b/tests/unit/runtime/test_release_assets.py @@ -112,10 +112,10 @@ def test_release_documents_keep_verified_boundaries_truthful() -> None: assert "Private GitHub" not in readme assert "Private GitHub" not in state - assert "Not production-ready" in readme - assert "尚未达到生产就绪" in readme_zh - assert "真实模型代表性" in state - assert "尚未" in state + assert "not a public interactive product" in readme + assert "不是公网交互产品" in readme_zh + assert "少量兼容性代表验证" in state + assert "Product Release gate" in state def test_public_entry_documents_show_one_language_and_use_standard_switch_links() -> None: @@ -259,3 +259,45 @@ def test_current_demo_and_learning_docs_match_the_single_root_agent_release() -> assert ".worktrees/agent-core-implementation" not in manual assert "cd frontend" not in manual assert "cd web" in manual + + +def test_showcase_release_gate_and_owner_acceptance_are_explicit() -> None: + amendment = ( + ROOT + / "docs" + / "superpowers" + / "specs" + / "2026-07-31-showcase-release-gate-amendment-design.md" + ).read_text(encoding="utf-8") + ownership = (ROOT / "docs" / "learning" / "opercerta-ownership-acceptance.md").read_text( + encoding="utf-8" + ) + state = (ROOT / "docs" / "development-log" / "current-state.md").read_text(encoding="utf-8") + handoff = (ROOT / "IMPLEMENTATION_HANDOFF.md").read_text(encoding="utf-8") + + for phrase in ( + "Showcase Release", + "Product Release", + "公开静态展示", + "本地可复现完整 Agent MVP", + "3\u20135 分钟录屏", + ): + assert phrase in amendment + assert "Showcase Release gate: AWAITING_OWNER_VALIDATION" in state + assert "Product Release gate: CLOSED" in state + assert "PR #22" in handoff + assert "671 passed" in handoff + assert "不得由 Codex 自动代签" in ownership + assert "operation_id" in ownership + assert "work_order_id" in ownership + + +def test_public_repository_has_an_apache_license_and_current_test_count() -> None: + license_text = (ROOT / "LICENSE").read_text(encoding="utf-8") + readme = (ROOT / "README.md").read_text(encoding="utf-8") + readme_zh = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") + + assert "Apache License" in license_text + assert "Version 2.0, January 2004" in license_text + assert "671 tests passed" in readme + assert "671 条通过" in readme_zh diff --git a/tests/unit/scripts/test_verify_repository_safety.py b/tests/unit/scripts/test_verify_repository_safety.py index c4e9fda..57ae960 100644 --- a/tests/unit/scripts/test_verify_repository_safety.py +++ b/tests/unit/scripts/test_verify_repository_safety.py @@ -92,3 +92,16 @@ def test_unpinned_action_and_write_permission_fail(tmp_path: Path) -> None: assert any("unpinned action" in item for item in findings) assert any("write permission" in item for item in findings) + + +def test_bilingual_public_documents_are_in_secret_scan_scope(tmp_path: Path) -> None: + files = clean_files() | { + "README.zh-CN.md": "# OperCerta\nBearer actual-looking-token\n", + "CONTRIBUTING.md": "# Contributing\nSafe content.\n", + "CONTRIBUTING.zh-CN.md": "# 贡献指南\nSafe content.\n", + } + root = tracked_repo(tmp_path, files) + + findings = scan_repository(root) + + assert any("credential-like content: README.zh-CN.md" in item for item in findings)