From a6a9b49665257aba1b92e67ba5e2830e8c1d87ff Mon Sep 17 00:00:00 2001 From: KXH Date: Fri, 31 Jul 2026 02:10:05 +0800 Subject: [PATCH] docs: record showcase prerelease --- DOCUMENT_INDEX.md | 21 ++++++++--------- IMPLEMENTATION_HANDOFF.md | 5 +++-- README.md | 5 +++-- docs/development-log/current-state.md | 8 +++++++ docs/development-log/daily/2026-07-31.md | 26 ++++++++++++++++++++++ docs/learning/opercerta-interview-guide.md | 11 +++++++-- docs/release-evidence/github-actions-ci.md | 8 +++++++ tests/unit/runtime/test_release_assets.py | 2 ++ 8 files changed, 70 insertions(+), 16 deletions(-) create mode 100644 docs/development-log/daily/2026-07-31.md diff --git a/DOCUMENT_INDEX.md b/DOCUMENT_INDEX.md index f895230..67a24cd 100644 --- a/DOCUMENT_INDEX.md +++ b/DOCUMENT_INDEX.md @@ -1,12 +1,12 @@ # OperCerta 文档总索引 -本索引完整登记 OperCerta 当前根工作树中的 115 份 Markdown 文档，并保留旧电脑 6 个 `.worktrees/` 的 456 条历史登记。当前根工作树与每个历史 worktree 使用独立六列表格和独立序号；路径均相对于仓库根目录；日期表示文档首次建立日期。历史 worktree 表用于追溯分支资料，不表示对应物理目录仍存在。Git 元数据、依赖目录、虚拟环境和工具缓存不属于项目文档登记范围。 +本索引完整登记 OperCerta 当前根工作树中的 116 份 Markdown 文档，并保留旧电脑 6 个 `.worktrees/` 的 456 条历史登记。当前根工作树与每个历史 worktree 使用独立六列表格和独立序号；路径均相对于仓库根目录；日期表示文档首次建立日期。历史 worktree 表用于追溯分支资料，不表示对应物理目录仍存在。Git 元数据、依赖目录、虚拟环境和工具缓存不属于项目文档登记范围。 Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/install_typora_index_theme.ps1`，重启 Typora 后选择 `主题 → OperCerta Index`。该主题让正文使用 96% 窗口宽度，并统一设置下列全部六列表格的列宽、自动换行和字号。 ## 项目核心学习导航 -先按 A1–A9 完成一轮“阅读 → 找到代码 → 手动验证 → 自己复述”。后面的 115 份当前文档与 456 条历史 worktree 登记是排查问题和深入学习时使用的资料库，不需要从头到尾顺序阅读。 +先按 A1–A9 完成一轮“阅读 → 找到代码 → 手动验证 → 自己复述”。后面的 116 份当前文档与 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-30.md) | 选择前述任一真实故障对应的代码、日志和修复提交。 | 分别完成 30 秒、3 分钟和 10 分钟讲解；独立复述一个“现象 → 根因 → 修复 → 验证 → 取舍”案例。 | 不看文档也能讲清业务价值、核心链路、技术取舍、可靠性证据和未完成边界，并能接受追问。 | +| A9 | 故障复盘与面试输出 | [面试讲解](docs/learning/opercerta-interview-guide.md)、[工程案例集](docs/development-log/interview-casebook.md)、[最新开发日志](docs/development-log/daily/2026-07-31.md) | 选择前述任一真实故障对应的代码、日志和修复提交。 | 分别完成 30 秒、3 分钟和 10 分钟讲解；独立复述一个“现象 → 根因 → 修复 → 验证 → 取舍”案例。 | 不看文档也能讲清业务价值、核心链路、技术取舍、可靠性证据和未完成边界，并能接受追问。 | -## 根工作树（115 份） +## 根工作树（116 份） 显示说明：本表及后续各 worktree 表均保持“序号、文件名、路径、用途、状态、日期”六列完整字段。 | 序号 | 文件名 | 路径 | 用途（详细） | 状态 | 日期 | | ---: | --- | --- | --- | --- | --- | -| 1 | `README.md` | `README.md` | 项目总入口，说明三业务场景、核心技术栈、运行方式、演示边界、学习入口和发布门禁，供开发者、审阅者与面试官快速了解 OperCerta。 | 已同步最新 main 667 条后端、60 条前端、9/9 Agent、Real Kimi 代表范围、静态 production 与剩余门禁 | 2026-07-30 | -| 2 | `IMPLEMENTATION_HANDOFF.md` | `IMPLEMENTATION_HANDOFF.md` | 跨对话和上下文压缩后的实施交接文件，记录当前分支、已验证事实、未完成事项、下一步动作及禁止越过的发布边界。 | 已同步 PR #17、最新 main Compose、静态 production 与下一掌握阶段 | 2026-07-30 | -| 3 | `DOCUMENT_INDEX.md` | `DOCUMENT_INDEX.md` | OperCerta 全部项目文档的唯一总登记表，用于按文件名、路径、用途、状态和日期统一检索、复查与交接。 | 当前根工作树 115 份文档已完整登记；另保留 6 个旧 worktree 的 456 条历史记录 | 2026-07-15 | +| 1 | `README.md` | `README.md` | 项目总入口，说明三业务场景、核心技术栈、运行方式、演示边界、学习入口和发布门禁，供开发者、审阅者与面试官快速了解 OperCerta。 | 已同步最终 main、667/60/9-of-9、Real Kimi 代表范围、静态 production、Showcase 预发布与产品边界 | 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 全部项目文档的唯一总登记表，用于按文件名、路径、用途、状态和日期统一检索、复查与交接。 | 当前根工作树 116 份文档已完整登记；另保留 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 #17/main 五项门禁、静态 production 晋级、回滚点及仍关闭的公网后端边界 | 2026-07-30 | +| 43 | `current-state.md` | `docs/development-log/current-state.md` | 保存最新可验证项目状态、测试证据、运行环境、发布边界、未完成事项和下一步，作为压缩上下文后的事实入口；同时区分本地候选镜像、空缓存冷构建、远程 CI 和真实生产发布四类证据。 | 已同步 PR #18/main 五项门禁、Showcase 预发布、静态 production、回滚点及仍关闭的产品边界 | 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 | @@ -84,13 +84,13 @@ Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/i | 56 | `learning-method.md` | `docs/development-log/learning-method.md` | 规定源码阅读、手动命令、单变量实验、复述、故障演练和面试问答结合的项目掌握方法。 | 已加入三业务学习与手动闭环建议；需持续实践 | 2026-07-17 | | 57 | `opercerta-core-technical-guide.md` | `docs/learning/opercerta-core-technical-guide.md` | 从一次业务请求出发解释 FastAPI、LangGraph、MCP、PostgreSQL、审批、幂等、恢复、容器和可观测性的代码链路与底层思想。 | 本地学习材料已完成；文件名已统一为英文路径，需结合源码实践 | 2026-07-20 | | 58 | `opercerta-manual-experiment-guide.md` | `docs/learning/opercerta-manual-experiment-guide.md` | 提供 WSL2/Compose 启停、三业务操作、数据库核对、MCP 调用、故障注入和恢复验证的可复制命令与观察点。 | 已同步 signal → case → Agent 调查主流程和根工作树/web 路径；用户掌握检查待继续 | 2026-07-20 | -| 59 | `opercerta-interview-guide.md` | `docs/learning/opercerta-interview-guide.md` | 提供 30 秒、3 分钟、10 分钟项目介绍、架构解释、技术取舍、可靠性证据和常见追问回答框架。 | 已统一最新 CI 数量与 Real Kimi 先失败后通过口径；需口述演练和源码补强 | 2026-07-20 | +| 59 | `opercerta-interview-guide.md` | `docs/learning/opercerta-interview-guide.md` | 提供 30 秒、3 分钟、10 分钟项目介绍、架构解释、技术取舍、可靠性证据和常见追问回答框架。 | 已统一最终 CI、Real Kimi、Showcase 版本和简历表述；需用户口述演练和源码掌握 | 2026-07-20 | | 60 | `demo-script.md` | `docs/demo-script.md` | 规定面向 HR 与面试官的展示顺序、演示前检查、业务闭环操作、异常备用方案和诚实边界。 | 已同步扫描异常、case 调查、审批、Verifier 与幂等工单流程；待用户实演 | 2026-07-18 | | 61 | `approval-atomicity.md` | `docs/release-evidence/approval-atomicity.md` | 保存 PostgreSQL 迁移、审批原子更新、并发批准竞态和业务事实绑定的实际测试命令与结果。 | 本地证据已归档；不代表生产发布 | 2026-07-15 | | 62 | `cache-tracing-model-adapter.md` | `docs/release-evidence/cache-tracing-model-adapter.md` | 保存 Redis 只读缓存、审批后绕过、OpenTelemetry 脱敏关联、严格真实模型适配器及未验证边界的阶段证据。 | 阶段证据已归档；真实模型另有独立证据 | 2026-07-20 | | 63 | `demo-jwt-rbac.md` | `docs/release-evidence/demo-jwt-rbac.md` | 保存本地 JWT 签发、四角色权限矩阵、审批身份绑定、安全拒绝和 Compose 回归结果。 | 本地验证通过；不代表生产身份系统 | 2026-07-18 | | 64 | `docker-linux-runtime.md` | `docs/release-evidence/docker-linux-runtime.md` | 保存 WSL2 Ubuntu 下 Compose 构建、服务健康、数据库初始化、业务 smoke 和重启恢复的实际输出。 | 单节点本地验证通过；发布门禁仍关闭 | 2026-07-17 | -| 65 | `github-actions-ci.md` | `docs/release-evidence/github-actions-ci.md` | 保存 GitHub PR/main Actions、后端与前端测试、PostgreSQL/Compose smoke、仓库可见性变化和分支保护能力核验。 | 已追加 PR #17、main run 30539160493、667/60/9-of-9 与 Compose 重启恢复证据；main 保护尚未配置 | 2026-07-30 | +| 65 | `github-actions-ci.md` | `docs/release-evidence/github-actions-ci.md` | 保存 GitHub PR/main Actions、后端与前端测试、PostgreSQL/Compose smoke、仓库可见性变化和分支保护能力核验。 | 已追加 PR #18、main run 30541088053、667/60/9-of-9、Compose 重启恢复与 Showcase 预发布证据；main 保护尚未配置 | 2026-07-30 | | 66 | `inventory-replenishment-vertical-slice.md` | `docs/release-evidence/inventory-replenishment-vertical-slice.md` | 汇总库存查询、规则判断、审批、执行、唯一工单、审计和 API 的首条端到端后端闭环证据。 | Windows 本地后端闭环已验证；发布门禁仍关闭 | 2026-07-16 | | 67 | `langgraph-restart-recovery.md` | `docs/release-evidence/langgraph-restart-recovery.md` | 保存 LangGraph 四点 A/B 重启测试、checkpointer 状态、审批中断恢复和副作用不重复的数据库断言。 | 本地恢复证据已归档；不代表生产高可用 | 2026-07-16 | | 68 | `native-postgres-environment.md` | `docs/release-evidence/native-postgres-environment.md` | 保存 Windows 原生 PostgreSQL 版本、服务、数据库、角色、认证规则和连接验证结果。 | 历史环境证据已归档；当前主运行时已迁移 | 2026-07-15 | @@ -141,6 +141,7 @@ Typora 显示：首次运行 `powershell -ExecutionPolicy Bypass -File scripts/i | 113 | `verifier-v1.md` | `src/opercerta/prompts/verifier-v1.md` | Verifier 角色版本化 Prompt，用于批准后重新核对事实、识别漂移并决定执行、重审批或安全终止。 | v1 已实施并有事实漂移回归测试 | 2026-07-21 | | 114 | `2026-07-30.md` | `docs/development-log/daily/2026-07-30.md` | 记录新电脑环境最终收口、WSL 登录 shell Node PATH 的 TDD 修复、冻结依赖国内镜像恢复、DrvFS 权限边界、PR/main 门禁，以及发布材料防漂移与静态安全头修订。 | PR #17/main 五项 CI、667/60/9-of-9、Netlify 静态 production 安全头与产物一致性均已验证 | 2026-07-30 | | 115 | `CONTRIBUTING.md` | `CONTRIBUTING.md` | 规定 OperCerta 的分支、最小变更、测试、PR 说明、安全和隐私贡献流程，确保外部协作不引入凭据、客户数据或未经评审的架构扩张。 | 已由 main 的 PR #16 引入；在环境分支同步登记以保证合并态索引一致 | 2026-07-30 | +| 116 | `2026-07-31.md` | `docs/development-log/daily/2026-07-31.md` | 记录 OperCerta 最终 main/CI 复核、Netlify 静态发布与回滚点、Showcase 预发布、自动化工程门禁结论、产品边界和下一掌握任务。 | 求职静态展示与自动化工程已收口；个人掌握待实演，产品 production gate 保持 CLOSED | 2026-07-31 | ## 历史 Worktree：agent-core-architecture（82 条记录） diff --git a/IMPLEMENTATION_HANDOFF.md b/IMPLEMENTATION_HANDOFF.md index ff020b7..183cbc8 100644 --- a/IMPLEMENTATION_HANDOFF.md +++ b/IMPLEMENTATION_HANDOFF.md @@ -2,6 +2,7 @@ ## 当前检查点 +- 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。 @@ -69,7 +70,7 @@ ## 新对话必须先做 1. 先阅读 `DOCUMENT_INDEX.md`、`docs/development-log/current-state.md` 和最近每日日志，再阅读相关设计、计划、交接和 Git 状态。 -2. 只实施 OperCerta；PR #17、最新 main Compose 与静态 production 已全绿。下一步从干净 main 分支完成固定评测口径、源码掌握、演示和简历材料；产品生产门禁关闭前不启动其他项目。 +2. 只实施 OperCerta；PR #18、最新 main Compose、静态 production 与 `v0.1.0-showcase.1` Showcase 预发布已全绿。下一步完成源码掌握、完整实演、3–5 分钟录屏和简历材料；产品生产门禁关闭前不把静态展示误报为生产系统。 3. 运行集成测试前，以不回显方式从已忽略 `.env.local` 加载 `OPERCERTA_DATABASE_URL`；不得提交该文件或任何凭据。 4. 每个效果数字都保留基线、测试数据、测量脚本和结果证据；指标未测出前使用目标值或空值，不写成已实现结果。 5. 使用公开或合成数据，从零编写全部代码和文档，不导入任何原单位源码、数据、截图、模型、品牌或内部规则。 @@ -83,4 +84,4 @@ ## 可复制到新对话的启动语 -> 工作目录为本 OperCerta 仓库根目录。请先读取 `DOCUMENT_INDEX.md`、`docs/development-log/current-state.md`、最近每日日志、`README.md`、`IMPLEMENTATION_HANDOFF.md`、`docs/specs/` 下的四份设计文件及当前相关规格、计划和证据；PR #17 已合并为 main `b6aa5fa`，main run `30539160493` 五项全绿并包含 667 条后端测试、三业务数据库副作用和重启恢复；Netlify 静态 production deploy `6a6b17cf496c38056f737264` 已通过安全头和资源哈希核验。下一步只继续固定评测、源码掌握、演示和简历材料。公开根路径只读、`/engineering` 仅 localhost、`/console` 仅本地真实演示；不复用旧公司材料，不虚构指标，不启动其他项目。 +> 工作目录为本 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` 仅本地真实演示；不复用旧公司材料，不虚构指标，不把静态展示误报为生产系统。 diff --git a/README.md b/README.md index 3facb44..90734e6 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,7 @@ and audit-focused observability in a reproducible reference implementation. - [Project showcase](https://opercerta-kxh.netlify.app) - [Portfolio overview](https://kxh-agent-portfolio.netlify.app) +- [Showcase pre-release](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1) - Status: engineering showcase; the public site is read-only and the production release gate remains closed. @@ -14,7 +15,7 @@ and audit-focused observability in a reproducible reference implementation. OperCerta 是面向库存异常、设备告警和运营工单的智能运营处置 Agent 独立作品仓库。 -> 当前状态：库存补货、设备维修、作业异常恢复三条 FastAPI + 单根 LangGraph + 最小 LangChain + FastMCP + PostgreSQL/pgvector 闭环、演示 JWT/RBAC、Agent Trace、本地 React 控制台、Redis 只读证据缓存和真实 FastEmbed RAG 已有自动化证据。少量 Moonshot AI `kimi-k2.6` 代表验证覆盖三业务只读、库存批准写入和无效 provider fail-closed，未回退 Mock 冒充成功。[PR #17](https://github.com/KXHXK/opercerta/pull/17) 合入发布准备修订；最新 [main CI](https://github.com/KXHXK/opercerta/actions/runs/30539160493) 在 `b6aa5fa` 上通过 667 条后端测试、19 个前端测试文件/60 条用例、9/9 冻结 Agent 评测和真实 Compose 构建、三业务数据库副作用与 API/MCP 重启恢复。[零成本静态项目专题](https://opercerta-kxh.netlify.app)已于 2026-07-30 晋级 deploy `6a6b17cf496c38056f737264`，安全头和资源 SHA-256 已经公网复验；[单页作品集](https://kxh-agent-portfolio.netlify.app)继续可只读访问。公开页面不提供后端写入口；生产身份、交互 HTTPS 后端、自动部署和公开 API 尚未完成，生产发布门禁：`CLOSED`。 +> 当前状态：库存补货、设备维修、作业异常恢复三条 FastAPI + 单根 LangGraph + 最小 LangChain + FastMCP + PostgreSQL/pgvector 闭环、演示 JWT/RBAC、Agent Trace、本地 React 控制台、Redis 只读证据缓存和真实 FastEmbed RAG 已有自动化证据。少量 Moonshot AI `kimi-k2.6` 代表验证覆盖三业务只读、库存批准写入和无效 provider fail-closed，未回退 Mock 冒充成功。[PR #18](https://github.com/KXHXK/opercerta/pull/18) 合入最终静态发布证据；最新 [main CI](https://github.com/KXHXK/opercerta/actions/runs/30541088053) 在 `298fc59` 上通过 667 条后端测试、19 个前端测试文件/60 条用例、9/9 冻结 Agent 评测和真实 Compose 构建、三业务数据库副作用与 API/MCP 重启恢复。[零成本静态项目专题](https://opercerta-kxh.netlify.app)已晋级 deploy `6a6b17cf496c38056f737264`，安全头和资源 SHA-256 已经公网复验；[Showcase 预发布 v0.1.0-showcase.1](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1)精确指向该已验证提交。公开页面不提供后端写入口；生产身份、交互 HTTPS 后端、自动部署和公开 API 尚未完成，产品生产发布门禁：`CLOSED`。 ## 当前已验证范围 @@ -40,7 +41,7 @@ OperCerta 是面向库存异常、设备告警和运营工单的智能运营处 ## 下一实施边界 -下一阶段仍只实施 OperCerta。单根 Agent 纠偏已经合并，main Compose 和新版静态专题生产发布均已通过；下一步完成用户手动演示、源码讲解与口述掌握检查，再整理 Release Tag、简历话术和五分钟演示材料。是否建设公网可写 HTTPS 后端仍需单独选择托管环境并审批成本与安全治理。生产 IAM、限流/防滥用、备份、高可用、自动部署和正式 Release Tag 仍待完成。生产发布门禁为 `CLOSED`，关闭前不启动其他项目。 +下一阶段仍只实施 OperCerta。单根 Agent 纠偏、main Compose、静态专题发布与 `v0.1.0-showcase.1` Showcase 预发布均已通过；下一步只做用户手动业务演示、源码讲解与口述掌握检查，并录制 3–5 分钟演示、定稿简历话术。是否建设公网可写 HTTPS 后端仍需单独选择托管环境并审批成本与安全治理。生产 IAM、限流/防滥用、备份、高可用、自动部署和产品级正式 Release 仍待完成。产品生产发布门禁为 `CLOSED`，关闭前不把静态展示误报为生产系统。 三业务收口规格与八项 TDD 主计划见 [设计](docs/superpowers/specs/2026-07-20-opercerta-three-business-release-design.md)和[计划](docs/superpowers/plans/2026-07-20-opercerta-three-business-release.md)。历史库存切片设计仍作为可靠性内核演进记录保留。 diff --git a/docs/development-log/current-state.md b/docs/development-log/current-state.md index 43ed78b..acb209f 100644 --- a/docs/development-log/current-state.md +++ b/docs/development-log/current-state.md @@ -1,5 +1,13 @@ # OperCerta 当前状态 +## 2026-07-31：Showcase Pre-release 已发布，自动化工程收口 + +[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` 保留为回滚点。 + +状态必须分开表达：求职代码仓库、静态展示、固定评测和可重复本地三业务演示的自动化工程门禁已经通过；个人源码掌握、完整手动实演、3–5 分钟录屏和简历定稿仍需用户亲自完成。公网可写 FastAPI、生产 IAM、限流、防滥用、备份、高可用、自动部署和 SLA 仍未实现，产品 production release gate 保持 `CLOSED`。 + ## 2026-07-30：发布准备已合并，静态 Production 已晋级 [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 重启恢复与清理。 diff --git a/docs/development-log/daily/2026-07-31.md b/docs/development-log/daily/2026-07-31.md new file mode 100644 index 0000000..1f8f584 --- /dev/null +++ b/docs/development-log/daily/2026-07-31.md @@ -0,0 +1,26 @@ +# OperCerta 开发日志：2026-07-31 + +## 今日目标 + +只收口 OperCerta 的求职展示工程，不扩展新业务、不启动 ForenTrail。把最终 main、远程 CI、Netlify 静态发布、GitHub Showcase 版本和下一学习任务统一成可追溯事实。 + +## 完成事项 + +- 复核 [PR #18](https://github.com/KXHXK/opercerta/pull/18) 已合入 main `298fc5978a56961d36e73888f4ae73017e302715`。 +- 复核 [main run 30541088053](https://github.com/KXHXK/opercerta/actions/runs/30541088053) 五项 job 全部成功：后端 `667 passed`、三业务固定契约、冻结 Agent `9/9`、前端 19 文件/60 条，以及真实 Compose 三业务数据库副作用和 API/MCP 重启恢复。 +- 复核 Netlify 静态 production deploy `6a6b17cf496c38056f737264`；上一 production `6a6631d24958714a43ddc508` 继续作为回滚点。 +- 首次创建 GitHub Release 时远端返回 502；保持本地状态不变后重试成功，发布 [Showcase 预发布 `v0.1.0-showcase.1`](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1)，tag 与 release target 均精确指向 `298fc59`。 +- 将版本、最终 CI、诚实发布边界和可直接使用的简历项目表述同步到 README、handoff、当前状态、CI 证据和面试讲解。 + +## 门禁结论 + +- 求职静态展示与自动化工程门禁：`PASSED`。代码仓库、公开只读专题、固定评测、main Compose 证据和可回退的 Showcase 版本均存在。 +- 个人掌握门禁：`PENDING`。文档和代码已就绪，但必须由本人完成一次完整业务实演、一次失败/重启实验、源码链路复述和追问演练。 +- 产品生产发布门禁：`CLOSED`。公网可写 FastAPI、生产 IAM、限流、防滥用、备份、高可用、自动部署和 SLA 未完成；静态 Showcase 不得被表述为生产系统。 + +## 下一步 + +1. 按核心技术手册和实验手册完成约 90 分钟的源码级掌握检查。 +2. 独立演示一条完整业务闭环与一次 MCP/进程重启恢复，并能解释数据库后置条件。 +3. 录制 3–5 分钟演示，使用面试讲解中的简历表述定稿简历。 +4. 上述求职交付完成前继续只处理 OperCerta 收口，不扩展产品生产范围。 diff --git a/docs/learning/opercerta-interview-guide.md b/docs/learning/opercerta-interview-guide.md index cd2aed8..f74c53d 100644 --- a/docs/learning/opercerta-interview-guide.md +++ b/docs/learning/opercerta-interview-guide.md @@ -2,7 +2,7 @@ ## 30 秒版本 -“OperCerta 是我用 FastAPI、LangGraph、最小 LangChain、FastMCP、PostgreSQL/pgvector、Redis 和 React 实现的可恢复运营处置 Agent。它跑通库存补货、设备维修、作业异常恢复三条闭环：确定性检测先发现异常，Plan-and-Execute Agent 受控取证，人工审批绑定快照，批准后重新复核，再幂等写工单。最新 main 有 667 条后端测试、19 个前端测试文件/60 条用例、9/9 Agent 冻结评测和真实 Compose 重启证据；Real Kimi 的三业务只读、库存批准写入和无效 provider fail-closed 做过少量代表验证。公网可写后端仍未上线。” +“OperCerta 是我用 FastAPI、LangGraph、最小 LangChain、FastMCP、PostgreSQL/pgvector、Redis 和 React 实现的可恢复运营处置 Agent。它跑通库存补货、设备维修、作业异常恢复三条闭环：确定性检测先发现异常，Plan-and-Execute Agent 受控取证，人工审批绑定快照，批准后重新复核，再幂等写工单。最新 main 有 667 条后端测试、19 个前端测试文件/60 条用例、9/9 Agent 冻结评测和真实 Compose 重启证据；Real Kimi 的三业务只读、库存批准写入和无效 provider fail-closed 做过少量代表验证，并发布了 `v0.1.0-showcase.1` 只读静态 Showcase 预发布。公网可写后端仍未上线。” ## 3 分钟版本 @@ -11,7 +11,7 @@ 3. **可靠性：** 非法输入在边界失败；审批用行锁保证一个胜者；审批绑定包含证据/规则/事实/计划哈希；批准后绕过缓存重读 MCP；工单用确定性幂等键和唯一约束保证重放不多写。 4. **恢复：** 业务 operation UUID 同时作为 LangGraph thread ID。启动扫描非终态业务表，再从 checkpoint 继续；业务表是真相，checkpoint 是执行进度。 5. **证据：** 原三业务 42 条固定合成评测之外，新增 9 类 Agent 轨迹评测，覆盖非法 schema、提示注入、未知工具、对象漂移、RAG 隔离、审批后漂移、竞态、幂等和重启；Compose 使用真实 FastEmbed/pgvector RAG。 -6. **边界：** 本地 Mock 闭环、真实 RAG/数据库/MCP 和少量 Kimi 兼容路径已验证；真实调用样本不足以形成准确率、SLA 或成本结论。生产 IAM、公开 HTTPS 后端、高可用和 Release Tag 尚未完成。 +6. **边界：** 本地 Mock 闭环、真实 RAG/数据库/MCP 和少量 Kimi 兼容路径已验证；真实调用样本不足以形成准确率、SLA 或成本结论。`v0.1.0-showcase.1` 是只读静态 Showcase 预发布，不代表生产 IAM、公开 HTTPS 后端、高可用或产品级正式 Release 已完成。 ## 10 分钟深挖提纲 @@ -110,6 +110,13 @@ OperCerta 不是把聊天框贴到工单系统上，而是解决仓储异常调 5. 展示一个自动化测试或 42 条报告，而不是滚动大量终端； 6. 主动说明三业务只读、库存批准写入和无效 provider fail-closed 只做过本地代表性验证，公网后端/生产 IAM 仍未完成。 +## 简历项目表述（通过个人掌握检查后使用） + +- 基于 FastAPI、LangGraph、最小 LangChain Tool Calling、FastMCP、PostgreSQL/pgvector、Redis 与 React，实现库存、设备、作业三类异常的可恢复运营处置 Agent；以受控只读取证、人工审批绑定、批准后复核和幂等事务约束高风险写入。 +- 建立 42 条固定三业务契约、9/9 冻结 Agent 安全/恢复评测与 GitHub Actions main Compose 门禁；验证 API/MCP 重启恢复和工单业务有效一次，并以 `v0.1.0-showcase.1` 发布只读静态展示。 + +展示入口：[OperCerta 专题](https://opercerta-kxh.netlify.app)、[GitHub 仓库](https://github.com/KXHXK/opercerta)、[Showcase 预发布](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1)。在完成下方检查前，只陈述已经实现和验证的项目事实，不在简历中使用“精通”、生产级 SLA 或未经测量的准确率、性能和成本数字。 + ## 个人掌握检查 只有能不看稿画链路、解释审批绑定、亲手完成一个业务/规则修改/MCP 故障实验，并回答“为什么不会多写工单”，才把个人熟练度写进简历。文档完成不等于个人已掌握。 diff --git a/docs/release-evidence/github-actions-ci.md b/docs/release-evidence/github-actions-ci.md index 64754b0..98766e6 100644 --- a/docs/release-evidence/github-actions-ci.md +++ b/docs/release-evidence/github-actions-ci.md @@ -1,5 +1,13 @@ # GitHub Actions 分层 CI：远程验证证据 +## 2026-07-31 最终证据合并与 Showcase Pre-release + +- [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` 五个 job 全部为 `success`。 +- 远程门禁继续记录完整后端 `667 passed`、三业务固定契约、冻结 Agent 安全/恢复评测 `9/9`、前端 19 个测试文件/60 条用例和 Vite production build；`compose-smoke` 实际验证三业务数据库副作用、API/MCP 重启恢复并清理隔离资源。 +- [Showcase 预发布 `v0.1.0-showcase.1`](https://github.com/KXHXK/opercerta/releases/tag/v0.1.0-showcase.1) 为非草稿 prerelease，tag 与 release target 均精确指向 `298fc59`。 +- 本节证明可复现的求职静态展示和本地单节点 Agent 发布候选，不证明公网可写后端、生产 IAM、限流、备份、高可用、SLA 或产品级正式发布。 + ## 2026-07-30 发布准备 PR #17 与最新 main 总门禁 - [PR #17](https://github.com/KXHXK/opercerta/pull/17) 的 `repository-safety`、`python-quality`、`frontend`、`backend-tests` 全部成功，`compose-smoke` 按 PR 事件规则跳过；随后以普通 merge commit `b6aa5fa13c7645bd3351092fc23b6c3e132a284d` 合入 main，未绕过检查。 diff --git a/tests/unit/runtime/test_release_assets.py b/tests/unit/runtime/test_release_assets.py index 3f153ce..cff47aa 100644 --- a/tests/unit/runtime/test_release_assets.py +++ b/tests/unit/runtime/test_release_assets.py @@ -188,6 +188,8 @@ def test_current_demo_and_learning_docs_match_the_single_root_agent_release() -> assert "新 Agent 核心的 Real Kimi Tool Calling 代表 query 为 failed" not in content assert "667 条后端测试" in interview + assert "v0.1.0-showcase.1" in readme + assert "v0.1.0-showcase.1" in interview assert ".worktrees/agent-core-implementation" not in manual assert "cd frontend" not in manual assert "cd web" in manual