Ivan's Blog
项目实践

OctoRill

OctoRill 把与 Ivan 相关的 GitHub 动态整理成适合持续阅读的工作区：发布更新、获星/关注动态、日报和 Inbox，发布内容还支持中文翻译和要点整理。README.md 同时指向 public docs-site、quick start、config、product 和 internal docs，说明它是产品化 Rust 服务 + React UI + 文档站，而不是一次性脚本。

  • shadcn/ui
  • Web demo
  • GitHub Actions scheduling
  • Worktree bootstrap
  • Project docs site

目录

技术栈

运行与交付

CI 工作流
  • ci.yml
  • docs-pages.yml
  • label-gate.yml
  • notify-release-failure.yml
  • release.yml
  • review-policy.yml
能力标记
  • bun_lock
  • cargo_toml
  • dockerfile
  • github_actions
  • package_json
JSON

Purpose

OctoRill 把与 Ivan 相关的 GitHub 动态整理成适合持续阅读的工作区：发布更新、获星/关注动态、日报和 Inbox，发布内容还支持中文翻译和要点整理。README.md 同时指向 public docs-site、quick start、config、product 和 internal docs，说明它是产品化 Rust 服务 + React UI + 文档站，而不是一次性脚本。

Taxonomy

  • Tags: shadcn/ui, Web demo, GitHub Actions scheduling, Worktree bootstrap, Project docs site

Repository map

  • src/ 是 Axum/SQLx 后端，Cargo.toml 包含 GitHub/OAuth、SQLite migration、chrono-tz、reqwest 等服务依赖。
  • web/ 是 Vite/React/shadcn/ui SPA，web/components.json 记录组件层 aliases，web/.storybook/main.ts 提供 Storybook component QA。
  • web/src/demo/ 是与正式 App 共用页面、路由和 API 调用面的 mock-only runtime；其中 scene registry、MSW/SSE transport、in-memory simulated writes 与 Inspector 共同组成页面级演示和验收 surface。
  • docs-site/ 是 Rspress public docs，.github/workflows/docs-pages.yml 发布文档站。
  • migrations/ 是 SQLite schema；Dockerfile 把 web build 与 Rust service 打进 deployable artifact。

Runtime and delivery

根 package.json 负责 hooks 和 worktree bootstrap smoke。Web 有 e2e、Storybook、preview、demo build 和 embedded-version tests；后端由 cargo 构建。web 以独立 build:demo 产物发布 /demo/，而 docs Pages assembly 保持 docs-site 根路径不变，并提供 /demo/** 的静态深链恢复。Dockerfile 使用 Bun stage 构建前端，再在 Rust stage 编译服务，说明 Dockerized dev/delivery 是真实交付路径。它也是当前 playbook 中最典型的轻量 Worktree bootstrap 样本：repo-local hook 安装、post-checkout 首次触发、scripts/worktree-sync.paths 驱动的 copy-missing local resources、odd Git layout 回退与 CI smoke 都已经被写成显式 contract。

Architecture notes

系统核心是“GitHub data ingestion + SQLite state + embedded React workspace”。OAuth 和 GitHub API 负责外部数据，SQLite 保留用户/配置/聚合状态，React UI 提供持续阅读。shadcn/ui 是组件组合层，不应覆盖 Rust 服务、docs-site 和 release workflow 的独立边界。

Web App 有明确的双运行时合同：普通构建走真实 AuthBootstrap 与后端 API；Demo 构建在 React 渲染前识别场景、清理 warm cache 并启动 MSW。两种模式复用同一 App、正式 route suffix 与 API 调用面，但 demo worker 未成功启动时会阻止 App 渲染，避免真实认证或 /api/** 泄漏。demo=<scene-id> 选择可复现场景，d_* 保存可分享的 persona、网络和数据状态；Inspector 面板把 scene、权限、网络、数据、模拟动作与 share URL 组织成结构化控制面，而不把 raw JSON 当作主操作入口。

证据锚点：README.md。

Workflow and quality gates

.github/quality-gates.json、label-gate.yml、review-policy.yml、ci.yml、release.yml、notify-release-failure.yml 共同定义 release/readiness contract。test:worktree-bootstrap 是特别值得保留的 gate：它验证新 worktree 能否靠脚本恢复运行，而不是依赖维护者记忆。

.github/workflows/ci.yml、label-gate.yml 和 review-policy.yml 都监听 edited，并各自用可取消的 per-PR concurrency group。metadata 重验必须与普通 candidate 分组，避免标题或 base 变更取消同一 SHA 的 CI、label 或 review gate；这个仓库是 GitHub Actions scheduling 的首个验证样本。

页面/流程最终证据由 /demo/ 产出，Storybook 只承担可复用 Inspector 片段和组件状态 QA。web/e2e/demo-inspector.spec.ts 覆盖 worker 启动、模拟写入、URL 状态保真、宽屏 pinned rail / floating overlay / mobile drawer、收起恢复和不触发整页 reload 等交互约束；Pages workflow 还构建 demo、Storybook、docs 并验证组装结果。

Reusable decisions

  • GitHub 动态产品需要 docs-site + internal docs 同步，否则配置和 product behavior 会漂移。
  • worktree bootstrap smoke 是多 Agent/多 worktree 项目的高价值门禁。
  • Docker artifact 同时包含 web/dist 和 Rust binary，部署验证必须覆盖二者。
  • 需要页面级视觉证据时，优先为正式 Web App 建独立 mock-only build，而不是把组件 Story 或临时 fetch patch 提升为最终演示面。Demo runtime 必须在认证和数据请求前准备好 network interception，写操作只更新内存模型并记录可见的 simulated mutation。
  • 调试控制面板属于演示 contract，不是任意覆盖层：宽视口在不挤压正式最大版心时可固定为全高左 rail，也必须允许收起为 bubble 回看正常布局；普通桌面保持可避让的浮层，移动端采用 bubble 到 drawer。面板布局只保存在本地，场景和关键数据状态才写入分享 URL。
  • 如果仓库只需要把 shared hooks 与少量本地文件同步到 linked worktree，octo-rill 这种轻量 bootstrap 模式比“checkout 自动做一切”更稳：manifest 小、默认 no-overwrite、历史 revision / stale hook binary 都能安全退化。

Risks and open questions

  • GitHub API/OAuth scope 变化会影响核心数据流。
  • Storybook 没有 accessibility addon 证据时应归为 component QA，不要过度命名为 accessibility。
  • Release queue 与 label intent 是复杂基础设施，简化 workflow 前需要看 quality-gates.json。
  • Demo 的 service worker、404 深链恢复和 app router basepath 必须作为一组发布合同验证；任一环缺失都会让公开分享链接落到 docs 404 或意外请求真实后端。

Evidence index

  • README.md
  • Cargo.toml
  • Dockerfile
  • migrations/
  • docs/architecture.md
  • docs/product.md
  • docs-site/package.json
  • web/package.json
  • web/components.json
  • web/.storybook/main.ts
  • web/src/main.tsx
  • web/src/App.tsx
  • web/src/demo/runtime.tsx
  • web/src/demo/DemoInspector.tsx
  • web/src/demo/transport.ts
  • web/e2e/demo-inspector.spec.ts
  • web/vite.config.ts
  • .github/scripts/assemble-pages-site.sh
  • .github/workflows/docs-pages.yml
  • docs/specs/k8d4m-web-demo-inspector/SPEC.md
  • .github/quality-gates.json
  • .github/workflows/label-gate.yml
  • .github/workflows/release.yml
  • .github/workflows/notify-release-failure.yml

相关内容