📝 Align agent rules, release docs, and branch freshness verification

This commit is contained in:
Codex 2026-11-03 00:28:40 -08:00
parent 8a82ecf174
commit f50efa161d
13 changed files with 285 additions and 245 deletions

View File

@ -1,8 +1,8 @@
# Targeted development verification
Goal: implement the approved fast development / task / integration verification workflow.
Goal: implement the approved fast development / task / integration verification workflow and align AI rules, branch-freshness reporting, and release/env docs.
Agent: Codex, current unified-worktree conversation
Base: codex/review-focus-layout-stability @ c8aa1ae7; continue the user's unified worktree without moving other work.
Scope: AGENTS.md, verification guidance, npm aliases, local selector/runner and its tests.
Out of scope: changing release policy, bypassing approvals, production actions or capacity acceptance.
Risk: false-positive verification; test unmapped changes, skips, empty tests, timeouts and affected-scope expansion.
Scope: AGENTS.md, CLAUDE.md, verification/branch/domain/issue-tracker guidance, release-checklist/HANDOFF/local-dev-guide docs, branch-freshness.sh, npm aliases, local selector/runner and tests.
Out of scope: changing release policy, bypassing approvals, production actions, capacity acceptance, or resetting the main checkout branch.
Risk: false-positive verification or freshness reporting; test unmapped changes, skips, empty tests, timeouts, affected-scope expansion, and unconfirmed remote/cluster freshness states.

View File

@ -2,47 +2,23 @@
## Working Root
- This repository directory is the single working root; the sibling `~/Desktop/fanyu` folder is legacy and will be retired.
- Cluster kubeconfig (`fanyu.conf`), BOS credential CSV, downloaded captures, and the local workspace mount are being migrated under this repo's untracked local data path (see `docs/HANDOFF.md` § 0 for the live layout).
- Before reading code to explain production behavior or starting changes, run `bash scripts/local/branch-freshness.sh` (read-only). If it reports the checkout is behind `origin/dev` or missing a live build commit, tell the user and work in a separate worktree based on the live commit instead of the stale checkout.
- The repository root is `/Users/d-robotics/Desktop/fanyu/droboticflow`. Until the main checkout's 19 local-only commits and untracked work are reconciled, the default unified development worktree is `local-data/worktrees/recent-integration`; never reset or switch branches in the main checkout without a dedicated recovery plan.
- Cluster kubeconfig (`fanyu.conf`), BOS credential CSV, downloaded captures, and the local workspace mount live under this repo's untracked `local-data/` directory; `~/Desktop/fanyu` still holds legacy copies (`fanyu.conf`, `泛宇-aksk.csv`) and is being retired (see `docs/HANDOFF.md` § 0).
- Before reading code to explain production behavior or starting changes, run `bash scripts/local/branch-freshness.sh` (read-only). If it reports the checkout is behind `origin/dev`, missing a live build commit, or only locally compared without remote/live confirmation, tell the user and work in a worktree that contains the live commit instead of a stale checkout.
## Engineering Principles
These principles guide implementation choices. Specific business contracts and this document's release, authorization, and data safety rules take precedence.
1. Check contracts and implementation first. Follow the Domain docs reading rules to review relevant business documentation,
ADRs, code, and tests. Distinguish current behavior, approved designs that are not yet implemented, and superseded rules.
Identify specific conflicts between the current request and existing agreements; ask the user when a conflict affects business outcomes and cannot be resolved independently.
1. Check contracts and implementation first. Read `CONTEXT.md`, relevant ADRs, business docs, code, and tests (`docs/agents/domain.md`). Distinguish current behavior, approved unimplemented designs, and superseded rules. Use the controlled Chinese terms from `CONTEXT.md` in customer-facing copy, specs, issues, and domain discussions; ask the user when a request conflicts with existing agreements and affects business outcomes.
2. Define the compatibility scope before making changes. For APIs, Mongo records, workflow definitions, operator inputs and outputs,
delivery formats, or task states, check callers, existing data, and in-flight tasks.
Before removing an old path, establish that compatibility is no longer needed or migration is complete, and explain the rollback impact.
Preserve migration and recovery paths that still serve a purpose. Internal implementations may be refactored directly when contracts remain unchanged.
2. Define the compatibility scope before making changes. For APIs, Mongo records, workflow definitions, operator inputs/outputs, delivery formats, or task states, check callers, existing data, and in-flight tasks. Preserve active migration and recovery paths; before removing an old path, verify migration completion and explain rollback impact. Internal implementations may be refactored directly when contracts remain unchanged.
3. Choose the simplest solution that meets current requirements and known constraints. Abstractions, configuration, and indirection must serve a concrete purpose.
Authentication, permission isolation, data consistency, and necessary retries and recovery are part of the requirements.
For temporary solutions, state their scope, limitations, and replacement conditions; avoid shortcuts known to fall short of confirmed requirements.
3. Keep solutions simple, incremental, and verifiable. Abstractions and indirection must serve a concrete requirement; authentication, permission isolation, data consistency, retries, and recovery are part of requirements. For multi-layer changes, connect the smallest complete flow first and validate replacement paths before removing old ones. State the scope, limitations, and replacement conditions of any temporary solution.
4. Implement incrementally through verifiable business flows. For changes spanning multiple layers, first connect the smallest complete flow required by the current request,
then extend its capabilities. Validate replacement paths before removing existing implementations.
A minimal version determines implementation order; the final delivery must still meet all acceptance criteria for the current request.
4. Follow responsibility boundaries and reuse existing capabilities. Place changes in the module responsible for that behavior. Enforce permissions and business constraints on the server; use frontend validation for interaction feedback and keep generated files updated from authoritative sources. Inspect existing code, standard libraries, and installed dependencies before adding new ones, and consult primary sources for unfamiliar or hard-to-reverse choices.
5. Follow existing responsibility boundaries. Locate the relevant components, API wrappers, business logic, storage, and execution entry points,
and place changes in the module responsible for that behavior. Enforce permissions and business constraints on the server;
use frontend validation for interaction feedback. Keep shared rules consistent and update generated files from their authoritative sources.
6. Reuse before adding dependencies. Before writing a new implementation or adding a dependency, inspect existing project code, standard libraries,
and the documentation, types, and available capabilities for installed dependency versions. When existing capabilities are insufficient, choose well-maintained
libraries that reduce overall complexity, and explain their purpose and adoption costs.
7. Consult established approaches where useful. For unfamiliar, consequential, or hard-to-reverse design choices,
consult official sources or relevant approaches in mature products, and explain the conditions under which they apply.
Follow existing project patterns for routine changes; adapt external approaches to this project's business contracts.
8. Complete delivery with verification evidence. Run the checks required for the scope of the change and verify relevant behavior in the local replica environment.
For changes involving asynchronous processing, persistence, or compatibility, cover the relevant failure, restart recovery, and legacy data scenarios.
Compare existing failures against the baseline by specific test case and cause, rather than failure counts alone.
Update the corresponding contracts when behavior changes, and clearly report what passed, failed, or remains unverified.
5. Complete delivery with verification evidence. Run the scoped checks (`docs/agents/verification.md`) and verify relevant behavior in the appropriate local environment. Cover failure, restart recovery, and legacy data scenarios for async, persistence, or compatibility changes. Compare existing failures against the baseline by specific test case and cause (`npm run test:frontend:gate` / `npm run test:go:gate`), update contracts when behavior changes, and clearly report what passed, failed, or remains unverified.
## Deployment Environment
@ -53,31 +29,30 @@ These principles guide implementation choices. Specific business contracts and t
## Git Workflow
- Before assuming a remote target, run `git remote -v`.
- After making code or documentation changes for the user, stage only the files changed for that task.
- Before assuming a remote target, inspect the remote URL with credentials redacted (`git remote -v | sed -E 's#//[^@/[[:space:]]+@#//<redacted>@#g'`). Never print raw credential-bearing `.git/config` URLs into logs or reports; prefer migrating Git credentials to the system Keychain.
- After making code or documentation changes for the user, stage only the files changed for that task. Do not stage or commit unrelated user changes already present in the working tree.
- Commit with an English, emoji-prefixed commit message.
- Agents may push their own task branch (`<agent>/<slug>`) without asking. Never push `dev`, `poc` or another agent's branch directly.
- **Creating a pull request requires the user's explicit approval.** When a branch is ready for review, remind the user and wait; after approval, push the final state and create the PR together.
- Do not stage or commit unrelated user changes already present in the working tree.
- One task, one branch: start it from the latest `origin/dev` in its own worktree under `local-data/worktrees/<slug>`, named `<agent>/<slug>`. Never switch branches in the main checkout. Build on another unmerged branch only when the user asks, and record that branch as the card's `Base:`.
- The branch's first commit adds the task card `.scratch/<slug>/work.md`. Follow `docs/agents/branch-workflow.md` for the card, the end-of-task report, and cleanup.
- When a task ends, push the task branch, run `python3 scripts/agent_status.py`, and report this branch's state to the user. If it is ready for review, remind them that a PR is waiting for their approval.
- **Push and PR each require explicit user authorization (or a combined "push and create PR" authorization); approving only one does not implicitly authorize the other.** Default action after commit: stay local. When push is approved, push only the authorized task/feature branch (`<agent>/<slug>`); never push `dev`, `poc`, or another agent's branch directly. When a branch is ready for review, report its local status and wait for the user's explicit instruction on pushing and/or opening a PR.
- Choose worktree isolation by parallel conflict and impact scope, not line count:
- Read-only Q&A, code audits, and diagnosis do not create a worktree or `.scratch/<slug>/work.md`.
- Follow-up fixes and small adjustments within an already-authorized task or unified worktree may stay in the current worktree.
- New independent features or changes that risk parallel conflict start from the latest `origin/dev` in a dedicated worktree under `local-data/worktrees/<slug>` named `<agent>/<slug>` (or build on another unmerged branch when requested by the user, recorded as `Base:` in `.scratch/<slug>/work.md`). Never switch branches in the main checkout. Follow `docs/agents/branch-workflow.md` for task cards, status reporting, and safe cleanup.
- When a task ends, run `python3 scripts/agent_status.py --no-fetch` (or with fetch if network/remote checks are needed) and report the branch's local state to the user.
## Release Workflow
- For release preparation, deployment, rollback, or resuming release work, read `docs/release/README.md` first and run `python3 scripts/release.py status <release-id>` when a record exists. Follow the recorded state and evidence; a successful rollout alone is not business acceptance.
- Deploy only commits contained in `origin/dev`. When the user approves deploying an unmerged branch for an urgent fix, name the branch in the approval request and in `--purpose`, and open its PR to `dev` the same day.
- Fanyu image releases use `scripts/release.py`. Configuration changes or migrations outside its supported scope require a separately reviewed plan and the corresponding user authorization.
- Fanyu image releases use `scripts/release.py` (`scripts/deploy-k8s.sh` blocks Fanyu). Configuration changes or migrations outside its supported scope require a separately reviewed plan and the corresponding user authorization.
## Credentials
- Never hardcode credentials (BOS AK/SK, Mongo, Gitea token, cluster kubeconfig) in any tracked file.
- Read secrets from untracked local files or environment variables; see `scripts/local/` for the established pattern.
- Never hardcode credentials (BOS AK/SK, Mongo, Gitea token, cluster kubeconfig) in any tracked file, and never echo raw credentials from untracked files (`.git/config`, `local-data/*`) into conversation output, `.scratch/` notes, or test logs.
- Read secrets from untracked local files, environment variables, or the system Keychain; see `scripts/local/` for the established pattern.
## Release Approval and Customer Data Safety
- Creating or submitting a pull request requires the user's explicit approval for that specific action; local review and commits may remain unsubmitted.
- Deploying to any company cluster requires the user's explicit approval immediately before the deployment; verification work must stop when that approval is absent.
- Pushing branches, creating/submitting a pull request, and deploying to any company cluster require explicit user approval (either individually or via an explicit combined instruction such as "push and open PR"); approving one action never implicitly authorizes another. Local review and commits remain unsubmitted until approved.
- Cluster verification is read-only against customer data: use isolated synthetic fixtures or existing records without mutation, and never delete, overwrite, or add customer data. If a test requires a write or destructive operation, stop and obtain explicit approval for that exact operation.
## Development verification
@ -88,7 +63,9 @@ These principles guide implementation choices. Specific business contracts and t
## Local Environment
- Local replica stack (Vite 5173, Go API 3001, snapshot Mongo 27018) is the default verification surface before any PR.
- Local Mongo environments serve distinct purposes (`docs/HANDOFF.md` § 0, `docs/local-dev-guide.zh-CN.md` § 0):
- **Snapshot Mongo (`127.0.0.1:27018`, `env-local-snapshot.sh`)**: realistic replica of production data structure for workbench/API verification before a PR. Keep shared snapshot task claim states clean before running Go baseline gates (`npm run test:go:gate`).
- **Empty/isolated Mongo (`127.0.0.1:27017`, `env-local.sh`, or per-test isolated databases on 27018)**: synthetic fixtures, unit/integration tests, and clean-slate workflow CRUD debugging.
- Verification commands and known pitfalls (upstream test debt, session auth flag, workspace mount) are documented in `docs/HANDOFF.md`.
- Comparing test failures against the known-failure baseline ALWAYS goes through `npm run test:frontend:gate` / `npm run test:go:gate` (they diff against `tests/known-failures.json`; only NEW failures fail). Never hand-diff failure lists with stash/scratch files. Quick edits check changed-file formatting; the full formatting gate remains `npm run format:check` at integration/release scope.
- The company cluster and BOS bucket are read-only by default; any write requires explicit user approval.

1
CLAUDE.md Normal file
View File

@ -0,0 +1 @@
@AGENTS.md

View File

@ -17,7 +17,9 @@
- 登录账号(使用本地自行设置的密码;密码不写入仓库,设置方法见 `docs/annotation-local-deployment.zh-CN.md` 第三步):
- 标注员 `fanyu-full-annotator@droboticflow.local`
- 质检员 `fanyu-full-qc@droboticflow.local`、验收员 `fanyu-full-acceptance@droboticflow.local`、管理员 `fanyu-admin@droboticflow.local`
- **红线**:27018/27017 都是本地容器,随便写;公司集群(kubeconfig `local-data/fanyu.conf`)和 BOS 桶默认只读,任何写操作需用户明确确认。
- **红线**:公司集群(kubeconfig `local-data/fanyu.conf`)和 BOS 桶默认只读,任何写操作需用户明确确认。本地容器按场景区分使用:
- **27018 快照库(`env-local-snapshot.sh`)**:承载真实数据结构副本,用于日常工作台与接口验证;合成写测试应使用独立测试集合/数据库或运行后恢复夹具(如 `--remove`),避免脏状态干扰 `npm run test:go:gate`。
- **27017 空库(`env-local.sh`)**:用于空库初始化、合成测试与基础工作流 CRUD 调试。
## 日常验证入口
@ -93,31 +95,29 @@ python3 scripts/part_index_migration.py --delivery-root <part 目录副本> --re
```
## 3. 如何看同事的代码 / 如何更新(rebase 流程)
## 3. 如何看同事的代码 / 如何同步最新基线
同事(Gitea 唯一作者 eust-w / longtao.wu)高频提交,工作模式:**客户需求 → 消化成 docs/ 契约文档 + 代码 + 测试同一提交**。
```bash
# 1. 拉取并查看新提交
git fetch origin dev
# 1. 检查当前工作树与线上/远端 dev 的新鲜度,并查看新提交
bash scripts/local/branch-freshness.sh
git log --oneline HEAD..origin/dev # 看新增了哪些提交
git log --diff-filter=A --name-only --format='--- %h %s' origin/dev -- 'docs/*.md' | head -30
# ↑ 需求雷达:同事新增的 docs/*.md 就是"消化后的客户需求",必读
# 2. 合入本地分支(用户的工作分支是 feature/local-dev-toolkit,全部是本地工具提交)
git rebase origin/dev # 历史上零冲突(本地提交全是新增文件,不碰上游)
# 2. 同步或开启新工作(严禁在主工作区直接切分支或盲目 rebase,详见 docs/agents/branch-workflow.md)
# - 新独立任务:从最新 origin/dev 创建独立 worktree
# git worktree add --no-track -b <agent>/<slug> local-data/worktrees/<slug> origin/dev
# - 在已授权的独立任务 worktree 内同步上游:先确认 git status 干净及与基线关系,再按任务需要合入/变基 origin/dev
# 3. 验证更新后的代码
npm run lint:web && go build ./...
go test ./internal/api/ -run 'TestContinuous|TestAnnotation|TestDelivery' -count=1 # 他新功能相关
npm run test:go:gate # 全量 go test 按用例名对照基线,新增失败才报红
# 3. 按影响范围执行分层验证(详见 docs/agents/verification.md,不要无脑跑全量编译/全量门禁)
npm run verify:plan -- --base origin/dev
npm run verify:quick -- --base origin/dev # 日常编辑/同步后的快速检查
npm run verify:task -- --base origin/dev # 交付前跑受影响模块检查(仅在集成/发布范围才跑 npm run verify:integration 或 test:go:gate / test:frontend:gate)
# 4. 重启服务生效(两个终端都要重启)
kill $(lsof -nP -iTCP:3001 -sTCP:LISTEN -t) 2>/dev/null
source scripts/local/env-local-snapshot.sh && npm run dev:api &
kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 --strictPort &
# 5. 浏览器 Cmd+Shift+R 硬刷新
# 4. 按需重启本地服务(仅当后端/前端改动需要本地运行态生效时执行;先用 lsof -nP -iTCP:3001,5173 -sTCP:LISTEN 确认进程属于当前工作树/当前任务,勿盲杀其他会话服务)
# 确认归属后再重启对应进程并硬刷新浏览器(Cmd+Shift+R)
```
**读同事代码的入手顺序**(按信息密度排序):
@ -143,7 +143,7 @@ kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 --
| `fetch-mongo-snapshot.sh` | 从集群 PVC 分块拉全库备份并恢复到 27018;本地和远端使用独立临时目录,完整 SHA-256 校验通过后才替换本地容器;成功保留的快照路径由脚本输出 |
| `smoke-workbench.mjs` | 发布前工作台冒烟(需本地栈 5173/3001 在跑 + Chromium/Edge):审核员登录 → 池渲染 → 随机领取 → 视频加载中直接点播放 → 字幕叠加 → 4× 倍速 → 进度条推进,7 个高频回归点一次过 |
配套文档:`docs/local-dev-guide.zh-CN.md`(环境搭建与踩坑)、`docs/annotation-local-deployment.zh-CN.md`(标注模块部署+测试用例 T1-T12)、`docs/release-checklist.zh-CN.md`(发布三道闸门+回滚)。
配套文档:`docs/local-dev-guide.zh-CN.md`(环境搭建与踩坑)、`docs/annotation-local-deployment.zh-CN.md`(标注模块部署+测试用例 T1-T12)、`docs/release/README.md`(Fanyu 权威发布流程 `scripts/release.py`;旧 `docs/release-checklist.zh-CN.md` 已转为跳转指引)。
## 6. 网络/工具链备忘(公司网络特有,新人必读)
@ -154,31 +154,31 @@ kill $(lsof -nP -iTCP:5173 -sTCP:LISTEN -t) 2>/dev/null; npx vite --port 5173 --
## 7. PR 与发布通道(已开通)
- Gitea 账号 `zhanghongming`(2026-09-17 开通,仓库协作者,push 已验证);remote 已带凭证(token 在 remote URL 中,若失效在 Gitea Settings→Applications 重新生成并 `git remote set-url` 更新);
- 工作流:本地 feature 分支提交 → `git push origin feature/<名字>` → Gitea 网页发 PR 到 dev → 同事审核合并。**不要直接 push dev**;
- Gitea 账号 `zhanghongming`(2026-09-17 开通,仓库协作者,push 已验证);若 `.git/config` 的 remote URL 中含认证信息,查看 remote 时必须先脱敏(`git remote -v | sed -E 's#//[^@/[[:space:]]+@#//<redacted>@#g'`),禁止将明文凭证打入日志或报告,推荐将凭证迁入系统 Keychain;
- 工作流:按 `docs/agents/branch-workflow.md` 在当前已授权工作树或独立任务分支提交 → 汇报本地分支状态等待用户授权 → **用户可一次性明确授权“推送并创建 PR”,或单独授权其中一项(只批准一项不会自动扩大到另一项)** → 获批后执行 `git push -u origin <分支名>` 及在 Gitea 发起 PR 到 `dev` → 同事审核合并。**未经授权不自动 push,且绝不直接 push `dev` 或 `poc`**;
- 当前进行中的 PR:https://gitea.d-robotics.cc/longtao.wu/droboticflow/pulls/1(本地工具箱 8 个提交);
- 同事已放行:下载 Capture 调试、直接改代码提交 PR 由他审核;
- 发布(用户执行、同事确认后):只改前端/API 时仅需重建 `droboticflow-api` 一个镜像(前端打进 API 镜像),流程见 `docs/release-checklist.zh-CN.md`;
- 发布(需用户明确授权):Fanyu 镜像构建、预检、部署、验收与回退统一通过 `python3 scripts/release.py` 执行,完整规程见 `docs/release/README.md`(`scripts/deploy-k8s.sh` 已拦截 Fanyu);
- 提交风格跟同事(gitmoji + 清晰信息 + 配套文档/测试),PR 通过率高。
## 8. 接班平台快查表
| 用户说 | 你做 |
|---|---|
| "页面有 bug" | 定位组件(§1 规律)→ 读代码 → 复现(浏览器/curl)→ 改 → lint+test → 让用户硬刷新 |
| "页面有 bug" | 定位组件(§1 规律)→ 读代码 → 复现(浏览器/curl)→ 改 → 按 `docs/agents/verification.md` 跑对应检查 → 让用户硬刷新 |
| "拉同事最新代码" | §3 流程五步 |
| "视频/帧范围加载失败" | §4 排查定式 |
| "测某个算子" | `scripts/local/run-operator.sh <slug>` |
| "改好了要发布" | 先 PR(§7);发布按 release-checklist |
| "测试报错了" | 先分辨是否上游测试债(§2 已知坑),再定位 |
| "改好了要发布" | 汇报分支状态等用户授权 push/PR(§7);Fanyu 发布严格按 `docs/release/README.md` 与 `scripts/release.py` 执行 |
| "测试报错了" | 先分辨是否上游测试债(§2 已知坑,`test:go:gate` / `test:frontend:gate`),再定位 |
## 9. 会话收尾清单(2026-10-14 复盘沉淀)
跨会话残留会累积(旧 worktree、上个会话的 dev API 今天还活着)。收尾时依次:
1. 杀掉本会话起的所有 dev 栈后台作业(`job_list` 里 running 的 vite / `npm run dev:api`),除非用户明说保留。
2. 删除已合入集成分支的 ticket worktree 与对应本地分支(`git worktree remove` + `branch -d`)。
3. 探针/截图证据先拷回主仓 `local-data/**/probe-out*` 再删 worktree。
2. 清理 worktree 前须同时确认四项:**已合入 `origin/dev`、无未提交/需保留的未跟踪文件、无运行中服务占用、且 `local-data/releases/` 下的发布记录已保全到主目录**;未验收版本和恢复材料必须保留。
3. 探针/截图证据先拷回主仓 `local-data/**/probe-out*` 再删已满足清理条件的 worktree。
4. 发布中的记录(`python3 scripts/release.py status`)若非 completed,向用户交代状态后再收。

View File

@ -1,10 +1,18 @@
# Branch workflow for parallel agents
Several agents work on this repository at once. Every branch must answer three questions
Several agents work on this repository at once. Every task branch must answer three questions
without anyone reading its history: what it is for, what it was built on, and whether it
has reached `dev`. Git answers the last two; the task card answers the first.
## Starting a task
## When to create a dedicated worktree
Choose isolation by parallel conflict risk and impact scope, not by line count:
- **Read-only Q&A, code audits, and diagnosis**: stay in the current checkout; do not create a worktree or `.scratch/<slug>/work.md`.
- **Follow-up fixes and small adjustments within an already-authorized task or unified worktree** (such as `local-data/worktrees/recent-integration`): continue in the existing worktree and update its task card scope if needed.
- **New independent tasks or changes that risk parallel conflict**: create a dedicated worktree from `origin/dev`.
## Starting an isolated task
```sh
git fetch origin
@ -16,11 +24,12 @@ git worktree add --no-track -b <agent>/<slug> local-data/worktrees/<slug> origin
- Start from `origin/dev`. To build on an unmerged branch, the user must ask for it. Its
PR then contains that branch's commits too, so say so in the PR description.
- Keep `--no-track`: without it the new branch tracks the remote branch it started from,
and a later `git push` could land there. Push with `git push -u origin <agent>/<slug>`.
and a later `git push` could land there. When the user authorizes pushing, push with
`git push -u origin <agent>/<slug>`.
## Task card
The first commit on the branch adds `.scratch/<slug>/work.md`. Keep it short. Do not
The first commit on a new task branch adds `.scratch/<slug>/work.md`. Keep it short. Do not
record status in it: `scripts/agent_status.py` derives status from git.
```md
@ -39,21 +48,26 @@ with the work and stays as the record of why the change was made.
## Ending a task
1. Run `python3 scripts/agent_status.py`. It fetches `origin` and lists for each branch the
commits ahead of and behind `dev`, unpushed commits, a missing card, stale work, and
the newest deployed release with whether its commit is in `dev`.
2. Push the task branch (no approval needed for your own `<agent>/<slug>` branch) and report
its line to the user. If it is ready for review, remind them; creating the PR needs their
explicit approval, and after it you push the final state and create the PR together.
3. After the PR merges, delete the remote branch in Gitea, remove the worktree, and run
`python3 scripts/agent_status.py --prune`. It deletes only local branches whose
commits are all in `origin/dev` and that no worktree has checked out.
1. Run `python3 scripts/agent_status.py` (or `--no-fetch` when offline). It lists for each
branch the commits ahead of and behind `dev`, unpushed commits, a missing card, stale work,
and the newest deployed release with whether its commit is in `dev`.
2. **Do not push or open a PR without the user's explicit authorization.** Report the branch's
local state and tell the user when it is ready. The user may authorize pushing and creating
a PR together in one instruction ("push and create PR") or authorize only one of them;
approving only one never implicitly authorizes the other. When push is authorized, push only
the authorized task branch (`<agent>/<slug>`, never `dev` or `poc`).
3. Only clean up a worktree after verifying all four conditions: its commits are merged into
`origin/dev`, the working tree has no uncommitted or untracked work to keep, no running dev
service (Vite / Go API) occupies it, and any release records under `local-data/releases/`
(especially `deployed_pending_acceptance`) have been copied to the main checkout's
`local-data/releases/`. Then remove the worktree and run `python3 scripts/agent_status.py --prune`
(which deletes only local branches whose commits are all in `origin/dev` and that no worktree
has checked out).
## Release records
`scripts/release.py` writes its ledger under the checkout it runs from, so records are
spread across worktrees. `agent_status.py` reads all of them. Do not delete a worktree that
holds a release record still in `deployed_pending_acceptance` until the record is copied to
the main checkout's `local-data/releases/`.
holds an unaccepted release record, unmerged recovery materials, or active services.
Tests: `python3 -m unittest discover -s tests/agents -p 'test_*.py'`.

View File

@ -4,22 +4,21 @@
This repository uses a single-context layout:
- `CONTEXT.md` at the repository root: domain vocabulary.
- `docs/adr/`: architecture decision records.
- `CONTEXT.md` at the repository root: controlled Chinese domain vocabulary.
- `docs/adr/`: architecture decision records (`0001` through `0005` and subsequent records).
Before exploring the codebase, read `CONTEXT.md` and ADRs relevant
Before exploring the codebase or changing domain behavior, read `CONTEXT.md` and ADRs relevant
to the area being explored.
If these files are absent, proceed silently. The `domain-modeling`
skill creates them lazily as terms or decisions are resolved.
## Vocabulary
Use the terms defined in `CONTEXT.md` when naming domain concepts
in issues, proposals, hypotheses, and tests.
Use the exact Chinese terms defined in `CONTEXT.md` when naming domain concepts
in customer-facing UI copy, issues, specs, proposals, and domain discussions. Go/TypeScript
identifiers and test function names may stay in English.
If a needed concept is missing, check whether existing vocabulary
covers it; otherwise note the gap for `domain-modeling`.
If a needed concept is missing from `CONTEXT.md`, check whether existing vocabulary
covers it; otherwise document the new term in `CONTEXT.md` (with `domain-modeling` if available,
or directly following the existing format).
## Decision conflicts

View File

@ -14,10 +14,10 @@ Issues and specs live as Markdown files in `.scratch/`.
## Publish and fetch
When a skill says "publish to the issue tracker", create the appropriate
file under `.scratch/<feature-slug>/`, creating directories as needed.
To publish a spec or ticket to the local tracker (whether invoked by a skill or directly),
create the corresponding file under `.scratch/<feature-slug>/`, creating directories as needed.
When a skill says "fetch the relevant ticket", read the referenced file.
To fetch a ticket, read the referenced Markdown file under `.scratch/<feature-slug>/`.
## Wayfinding operations

View File

@ -10,4 +10,4 @@ For local Markdown issues, record the tracker value in the `Status:` line.
| ready-for-human | ready-for-human | Requires human implementation |
| wontfix | wontfix | Will not be actioned |
When a skill mentions a triage role, use its tracker value above.
When triaging issues (directly or through a skill), use the tracker value above.

View File

@ -34,28 +34,21 @@ ffmpeg -version | head -1
# ✅ 校验:输出 bcrypt ok(没有就 .venv/bin/pip install -i https://mirrors.aliyun.com/pypi/simple/ --trusted-host mirrors.aliyun.com bcrypt)
```
## 第二步:拉取最新代码(分支/依赖/冲突处理)
## 第二步:进入最新工作树并检查基线(分支/依赖/新鲜度)
```bash
cd ~/Desktop/fanyu/droboticflow
# 默认在统一开发工作树或按 docs/agents/branch-workflow.md 创建的独立任务 worktree 中执行
# (严禁在主工作区 ~/Desktop/fanyu/droboticflow 直接切分支或盲目 git add -A / rebase)
cd ~/Desktop/fanyu/droboticflow/local-data/worktrees/recent-integration
# 1. 保存本地改动(我们已有的 toolkit 提交都在 feature 分支上)
# 1. 检查当前工作区状态与分支新鲜度(只读)
git status -sb
# ✅ 校验:## feature/local-dev-toolkit 且工作区干净(有未提交文件就先 git add -A && git commit)
bash scripts/local/branch-freshness.sh
# ✅ 校验:确认当前工作树包含 origin/dev 及线上运行版本;若需新独立分支,按 docs/agents/branch-workflow.md 从 origin/dev 创建 worktree
# 2. 拉最新 dev(线上部署 commit 6eb21ada 已在 dev 历史内;dev 还比线上多几个标注修复提交)
git fetch origin dev
git rebase origin/dev
# ✅ 校验:git log --oneline -1 与 origin/dev 同步,且包含 "Keep owned-task selection during account initialization"
# 3. 依赖(一般无新增,跑一次确认)
# 2. 依赖(一般无新增,必要时确认)
npm install
# ✅ 校验:无 error 退出
# 4. 代码冲突预案:rebase 冲突时
# git status 找冲突文件 → 保留双方(上游改动 + 我们的 toolkit 都是新文件为主,几乎不会冲突)
# 解决后 git add -A && git rebase --continue
# 实在解不开:git rebase --abort 退回,把 toolkit 文件手工拷到新克隆目录(toolkit 全是新增文件,可整体搬)
```
## 第三步:标注模块轻量化快速启动(不等全量部署)

View File

@ -2,14 +2,14 @@
本指南描述如何在不接触公司集群的前提下,在本机完成单功能开发与调试。环境搭建背景见仓库根目录 `README.md`,业务概念见 `docs/platform-usage-manual.zh-CN.md`。
## 0. 隔离边界(先读这个)
## 0. 隔离边界与本地环境分工(先读这个)
| 事项 | 规则 |
| --- | --- |
| MongoDB | 只用本机容器 `fanyu-mongo`(`127.0.0.1:27017`),绝不指向公司实例 |
| Kubernetes | 不导出 `KUBECONFIG`、不使用 `fanyu.conf`;发布走 `docs/release-checklist.zh-CN.md` 且须同事确认 |
| BOS / AI | 本地全部留空禁用;数据源一律用本地路径(`local-samples/`) |
| 镜像仓库 | 本地构建演练不登录、不推送;推送发布见发布清单 |
| MongoDB(双库并存) | **27017 空库**(`fanyu-mongo`,`env-local.sh`):用于空库初始化、合成测试及基础工作流 CRUD 调试;<br>**27018 快照库**(`fanyu-mongo-restore`,`env-local-snapshot.sh`):承载公司生产数据结构副本,用于标注/质检/验收工作台与接口真实结构复刻(详见 `docs/HANDOFF.md`);<br>两者均为本机容器,绝不把本地开发 API 指向公司生产 Mongo 实例 |
| Kubernetes | 日常本地开发不导出 `KUBECONFIG`;线上只读排查或 Fanyu 正式发布统一按 `docs/release/README.md` 与 `python3 scripts/release.py` 执行(`scripts/deploy-k8s.sh` 已拦截 Fanyu),任何集群写操作须用户明确授权 |
| BOS / AI | 轻量空库模式(`env-local.sh`)默认留空禁用,数据源用本地路径(`local-samples/`);快照库复刻模式通过 `WORKSPACE_MOUNT_PATH` 挂载已下载至 `local-data/workspace` 的本地 Capture(见 `docs/HANDOFF.md` §4),公司 BOS 桶默认只读 |
| 镜像仓库 | 本地构建演练不登录、不推送;Fanyu 候选镜像构建与发布见 `docs/release/README.md`(使用 `scripts/release-build-api-image.sh` 注入构建 commit 与时间戳) |
## 1. 环境准备(已完成则跳过)
@ -88,13 +88,16 @@ npm run operators:repos
## 4. 分层测试命令
日常改动优先按 `docs/agents/verification.md` 使用 `npm run verify:plan -- --base <起点>`、`npm run verify:quick` 与 `npm run verify:task`。全量与专项命令如下:
| 层 | 命令 | 说明 |
| --- | --- | --- |
| 分层快检 / 任务级 | `npm run verify:quick -- --base <ref>` / `npm run verify:task -- --base <ref>` | 按改动范围自动选择受影响单元与业务回归 |
| 单算子 | `scripts/local/run-operator.sh <slug>` | 真实执行,秒级 |
| 单算子单测 | `.venv/bin/python -m pytest backend/operator-runner -k <关键词>` | 或 `tests/backend/<某算子>_test.py` |
| Go 全量 | `npm test`(= `go test ./...`) | 不需要 Mongo/集群 |
| Go 基线门禁 | `npm run test:go:gate` | 对照 `tests/known-failures.json` 仅在新增失败时报红(跑前先停本地 3001 API) |
| Python 全量 | `npm run test:python` | 用系统 python3;建议先 `source .venv/bin/activate` |
| 前端 | `npm run test:frontend` | node --test,无需浏览器 |
| 前端基线门禁 | `npm run test:frontend:gate` | node --test 对照已知失败基线,无需浏览器 |
| 总闸门 | `npm run verify:local` | lint + 全部测试 + 构建 + k8s 清单 dry-run |
## 5. 算子发布链本地演练(无 docker)
@ -139,7 +142,7 @@ docker build -f Dockerfile.operator-runner --platform linux/amd64 \
docker image inspect droboticflow-operator-runner:localtest --format '{{.Os}}/{{.Architecture}}'
```
> 注:真正推送发布时走 `scripts/build-and-push-images.sh`(见发布清单)——如果届时也卡在 go mod download / pip,可先与同事确认是否把代理 build-arg 透传进脚本,或临时在本机代理开着的状态下用上面的原生命令构建后手动 `docker push`。
> 注:Fanyu 正式发布镜像必须使用 `GOPROXY=https://goproxy.cn,direct scripts/release-build-api-image.sh` 构建(自动注入 `DROBOTICFLOW_BUILD_COMMIT` 与 `DROBOTICFLOW_BUILD_TIME` 并输出不可变 digest),完整流程见 `docs/release/README.md`。非 Fanyu 环境才使用 `scripts/build-and-push-images.sh`。
## 7. 常见问题

View File

@ -1,109 +1,42 @@
# 发布清单与回滚预案(公司集群 droboticflow-fanyu)
# 发布清单与回滚指引(公司集群 droboticflow-fanyu)
> 本清单在**本地全绿 + 同事确认之后**才执行。发布顺序不可颠倒;每一步失败就停下排查,不带病前进。
> **权威入口声明**:Fanyu(`droboticflow-fanyu`)镜像发布、预检、部署、业务验收与回退已全面切换至 [`docs/release/README.md`](release/README.md) 与 `python3 scripts/release.py`。
> `scripts/deploy-k8s.sh` 已硬编码拦截 `DEPLOY_ENV=fanyu` 与 `K8S_NAMESPACE=droboticflow-fanyu`(直接退出 2);本文档已移除旧版直接调用 `deploy-k8s.sh` 或 `build-and-push-images.sh` 投产 Fanyu 的可执行命令,防止误触发全量 apply。
## 0. 前置闸门(发布日前逐项打勾)
## 1. Fanyu 标准发布五步(唯一可执行路径)
- [ ] `npm run verify:local` 全绿(lint + Go + Python + 前端 + 构建 + 清单 dry-run)
- [ ] 涉及的算子用 `scripts/local/run-operator.sh <slug>` 实测通过
- [ ] 改过 `operator-repos/**` 的,`npm run operators:images:check` 通过
- [ ] 代码已 push 到 Gitea(无账号时:`git format-patch origin/dev -o /tmp/` 交同事代推/评审)
- [ ] **同事已在 Gitea/补丁上评审确认**(必要条件,不满足则不发)
- [ ] 已确认目标 namespace:`droboticflow-fanyu`;已和同事约定发布时间窗口(避开采集高峰)
- [ ] 集群当前无进行中的重要 Run(平台监控页确认)
完整参数、策略约束(`docs/release/fanyu-policy.json`)及证据要求见 [`docs/release/README.md`](release/README.md):
## 1. 记录回滚锚点(发布前必做)
1. **查看当前发布状态与历史记录**:
```sh
python3 scripts/release.py status
python3 scripts/release.py status <release-id>
```
2. **构建带源码戳的不可变镜像并 Prepare(离线)**:
- 使用干净工作树,通过 `scripts/release-build-api-image.sh` 构建并推送带 `DROBOTICFLOW_BUILD_COMMIT` / `DROBOTICFLOW_BUILD_TIME` 的 digest 镜像(`repository@sha256:...`)。
- 执行 `python3 scripts/release.py prepare --id <release-id> ...` 绑定候选版本与目标集群身份。
- 发布前运行 `python3 scripts/release_source_audit.py` 核对候选代码是否包含线上 API、切片处理器与 Worker 的全部已部署修复。
3. **运行本地门禁与集群只读预检(Check)**:
```sh
python3 scripts/release.py check <release-id> --local
python3 scripts/release.py check <release-id> --cluster
```
- 包含 `build:web` + `test:production:boot` 生产前端产物启动门禁、审核权限门禁(`test:browser:review-permissions`)及看板稳定性门禁(`scripts/test_dashboard_stability.py`)。
4. **生成计划并录入人工审查证据(Plan & Evidence)**:
```sh
python3 scripts/release.py plan <release-id>
python3 scripts/release.py evidence <release-id> --check image-provenance --result passed --file <evidence-file> --note '...'
python3 scripts/release.py evidence <release-id> --check change-safety --result passed --file <evidence-file> --note '...'
```
5. **经用户明确授权后部署与验收(Deploy & Verify)**:
- 展示 `plan` 输出并取得用户对本次部署的明确授权后,传入真实消息引用执行 `python3 scripts/release.py deploy <release-id> --confirm-plan <plan-hash> --approval-ref <ref>`。
- 部署遵循**先切片处理器、完整 rollout 后再更新 API** 的固定顺序。
- 部署后运行 `python3 scripts/release.py verify <release-id>`,并按 `requiredEvidence` 补齐只读/隔离业务验收证据,直至状态进入 `accepted_with_evidence`。
```bash
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf # 仅发布 shell 会话内
kubectl -n droboticflow-fanyu get deploy \
-o jsonpath='{range .items[*]}{.metadata.name}{"\n"}{range .spec.template.spec.containers[*]}{" image: "}{.image}{"\n"}{end}{end}' \
| tee /tmp/rollback-images-$(date +%Y%m%d-%H%M).txt
```
## 2. 范围外变更与回退原则
> 注意:api/worker 的镜像记录在 Deployment env(`DROBOTICFLOW_IMAGE`、`OPERATOR_RUNNER_IMAGE`)里且带 digest;回滚清单要同时抓 env 里的这几项。把这份文件连同本次发布说明一起存档。
## 2. 构建并推送镜像(公网端点)
```bash
docker login ccr-29eug8s3-pub.cnc.bj.baidubce.com
# 凭据:用户 ccr$fanyu(见本地 source.md;只存在本机 docker 凭据库,绝不进代码)
REGISTRY_HOST=ccr-29eug8s3-pub.cnc.bj.baidubce.com \
REGISTRY_NAMESPACE=fanyu \
IMAGE_TAG=$(git rev-parse --short HEAD) \
./scripts/build-and-push-images.sh
```
- 产出 4 个镜像:`droboticflow-api` / `droboticflow-worker` / `drosync-coordinator` / `droboticflow-operator-runner`(自动交叉构建 linux/amd64)。
- 取 digest 备用:
```bash
for img in droboticflow-api droboticflow-worker drosync-coordinator droboticflow-operator-runner; do
docker buildx imagetools inspect \
ccr-29eug8s3-pub.cnc.bj.baidubce.com/fanyu/$img:$(git rev-parse --short HEAD) \
| grep Digest
done
```
- 只改了算子(没改平台代码)时可以只发算子镜像,其余保持旧 digest 不动——**最小变更原则**。
- 公司网络下若卡在 go mod download / pip:以 `--build-arg http_proxy=http://<colima网关>:7890` 注入本机代理构建(见 local-dev-guide 第 6 节),构建完手动 `docker push`。
## 3. 部署到公司集群(VPC 端点 + digest 钉版)
```bash
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf
VPC=ccr-29eug8s3-vpc.cnc.bj.baidubce.com
TAG=$(git rev-parse --short HEAD)
K8S_NAMESPACE=droboticflow-fanyu \
API_IMAGE=$VPC/fanyu/droboticflow-api@sha256:<api-digest> \
WORKER_IMAGE=$VPC/fanyu/droboticflow-worker@sha256:<worker-digest> \
DROSYNC_COORDINATOR_IMAGE=$VPC/fanyu/drosync-coordinator@sha256:<drosync-digest> \
OPERATOR_RUNNER_IMAGE=$VPC/fanyu/droboticflow-operator-runner@sha256:<runner-digest> \
CREATE_REGISTRY_SECRET=false \
./scripts/deploy-k8s.sh
```
要点:
- `MONGO_URI` 不传:脚本自动从集群现有 `droboticflow-mongo-secret` 回读。
- `CREATE_REGISTRY_SECRET=false`:复用集群现有 `droboticflow-registry` 拉取密钥,命令行不出现任何明文凭据。
- 脚本内部是 `kubectl apply` + `rollout status` 等待,可安全重跑。
- GPU/Qwen 相关变量(`OPERATOR_GPU_NODE_SELECTOR` 等)当前由集群 ConfigMap 提供,不在本次发布中改动。
## 4. 发布后验证
```bash
# 1) rollout 就绪 + 健康
kubectl -n droboticflow-fanyu get pods
curl -s http://120.48.180.80/api/health && curl -s http://120.48.180.80/api/ready
# 2) 构建 commit 与预期一致
curl -s http://120.48.180.80/api/health | python3 -m json.tool | grep -i commit
# 3) 平台冒烟:登录、跑一条最小工作流(或按变更范围跑对应验收)
```
## 5. 回滚预案
症状(任一):健康检查失败、run 大面积失败、镜像拉取失败。
```bash
# 用第 1 步存档的旧 digest 重跑同一脚本即回滚(rolling update 回旧镜像)
export KUBECONFIG=/Users/d-robotics/Desktop/fanyu/droboticflow/local-data/fanyu.conf
K8S_NAMESPACE=droboticflow-fanyu \
API_IMAGE=<旧api镜像@digest> WORKER_IMAGE=<旧worker镜像@digest> \
DROSYNC_COORDINATOR_IMAGE=<旧drosync镜像@digest> \
OPERATOR_RUNNER_IMAGE=<旧runner镜像@digest> \
CREATE_REGISTRY_SECRET=false ./scripts/deploy-k8s.sh
```
- 算子级回滚:`git revert` 对应 `operator-repos/builtin/<slug>/release.json` 的提交,重跑 `npm run operators:images` + reconcile,把线上算子目录拨回旧 digest。
- 数据安全:deploy 只滚动更新 Deployment,不动 Mongo 数据与 BOS 对象;回滚后 Run 历史仍完整可查。
- 回滚后立即通知同事并在发布记录里写明原因。
## 6. 代码评审通道(Gitea 权限待定期间)
- 有推送权限:`git push origin feature/<名字>` → Gitea 上发起合并到 `dev` → 同事评审。
- 暂无权限:`git format-patch origin/dev -o /tmp/patches/`,把补丁目录交同事 `git am` 代推;或直接把分支推到个人 fork。
- 线上 `dev` 分支与集群部署版本可能存在少量提交差,发布前与同事对齐目标基线,避免把未验证提交带上线。
- **配置、Worker/Coordinator 或算子镜像变更**:不在 `release.py` 首版自动补丁范围内;需单独制定审查计划并取得用户明确授权。内置算子清单与 digest 校验仍使用 `npm run operators:images:check`。
- **故障与回退**:
- 遇到 `outcome_unknown` 或部分更新时,先运行 `python3 scripts/release.py verify <release-id>` 核实集群状态,严禁重跑旧版全量 `kubectl apply` 或 `deploy-k8s.sh`。
- 回退必须取得用户新的明确授权,核对当前版本与数据兼容性后按条件式变更执行(详见 [`docs/release/README.md`](release/README.md)「故障、回退和紧急修复」节)。
- **非 Fanyu 环境(如 POC)**:仍按 `AGENTS.md` 的 `Deployment Environment` 路由规则与 `README.md` 中的 POC 验收脚本执行。

View File

@ -5,6 +5,11 @@
# 落后或不包含线上版本时提示。只更新远端跟踪引用,不改分支、文件或集群;
# 任何失败都只降级为提示,始终以 0 退出,不阻断会话。
#
# 可选参数:
# --no-fetch 等同 FRESHNESS_SKIP_FETCH=1(不拉取远端引用)
# --no-cluster 等同 FRESHNESS_SKIP_CLUSTER=1(不查询线上版本)
# --base-ref <ref> 等同 FRESHNESS_BASE_REF=<ref>
#
# 可选环境变量:
# FRESHNESS_BASE_REF 对比基线(默认 origin/dev)
# FRESHNESS_SKIP_FETCH=1 不拉取远端引用
@ -14,6 +19,43 @@
set -u
skip_fetch=${FRESHNESS_SKIP_FETCH:-0}
skip_cluster=${FRESHNESS_SKIP_CLUSTER:-0}
cli_base_ref=""
while [ $# -gt 0 ]; do
case "$1" in
--no-fetch)
skip_fetch=1
shift
;;
--no-cluster)
skip_cluster=1
shift
;;
--base-ref)
if [ $# -lt 2 ] || [ -z "${2:-}" ] || [[ "${2:-}" == -* ]]; then
echo "错误:--base-ref 需要提供非空引用名(用法:bash scripts/local/branch-freshness.sh [--no-fetch] [--no-cluster] [--base-ref <ref>])" >&2
exit 2
fi
cli_base_ref=$2
shift 2
;;
--base-ref=*)
cli_base_ref=${1#--base-ref=}
if [ -z "${cli_base_ref}" ]; then
echo "错误:--base-ref= 需要提供非空引用名(用法:bash scripts/local/branch-freshness.sh [--no-fetch] [--no-cluster] [--base-ref <ref>])" >&2
exit 2
fi
shift
;;
*)
echo "错误:未知参数 '$1'(支持参数:--no-fetch、--no-cluster、--base-ref <ref>)" >&2
exit 2
;;
esac
done
# macOS 没有 timeout 命令;用 perl alarm 给网络调用设上限。
with_timeout() {
local seconds=$1
@ -28,7 +70,7 @@ fi
common_dir=$(git rev-parse --path-format=absolute --git-common-dir)
main_root=$(dirname "$common_dir")
base_ref=${FRESHNESS_BASE_REF:-origin/dev}
base_ref=${cli_base_ref:-${FRESHNESS_BASE_REF:-origin/dev}}
cache_file=${FRESHNESS_CACHE_FILE:-$main_root/local-data/.cache/live-build-commits.txt}
cache_ttl=${FRESHNESS_CACHE_TTL:-1800}
kubeconfig=${FRESHNESS_KUBECONFIG:-$main_root/local-data/fanyu.conf}
@ -40,14 +82,30 @@ branch=$(git branch --show-current)
[ -n "${branch}" ] || branch="(detached $(git rev-parse --short HEAD))"
warnings=()
notes=()
fetch_succeeded=0
base_verified=0
live_verified=0
# 1. 与基线分支对比
if [ "${FRESHNESS_SKIP_FETCH:-}" != "1" ] && [ "${base_ref}" = "origin/dev" ]; then
if ! with_timeout 8 git fetch --quiet origin dev >/dev/null 2>&1; then
if [ "${skip_fetch}" = "1" ]; then
notes+=("未拉取远端引用(FRESHNESS_SKIP_FETCH=1 或 --no-fetch)。")
elif [ "${base_ref}" = "origin/dev" ]; then
if with_timeout 8 git fetch --quiet origin dev >/dev/null 2>&1; then
fetch_succeeded=1
else
notes+=("未能联网拉取 origin/dev,以下按本地已有引用对比。")
fi
elif [[ "${base_ref}" == origin/* ]]; then
remote_branch=${base_ref#origin/}
if with_timeout 8 git fetch --quiet origin "${remote_branch}" >/dev/null 2>&1; then
fetch_succeeded=1
else
notes+=("未能联网拉取 ${base_ref},以下按本地已有引用对比。")
fi
fi
if git rev-parse --verify --quiet "${base_ref}^{commit}" >/dev/null; then
base_verified=1
behind=$(git rev-list --count "HEAD..${base_ref}")
ahead=$(git rev-list --count "${base_ref}..HEAD")
if [ "${behind}" -gt 0 ]; then
@ -59,8 +117,8 @@ fi
# 2. 与线上 build commit 对比(缓存,避免每次会话都访问集群)
live=""
if [ "${FRESHNESS_SKIP_CLUSTER:-}" = "1" ]; then
notes+=("未查询线上版本(FRESHNESS_SKIP_CLUSTER=1)。")
if [ "${skip_cluster}" = "1" ]; then
notes+=("未查询线上版本(FRESHNESS_SKIP_CLUSTER=1 或 --no-cluster)。")
else
if [ -s "$cache_file" ]; then
age=$(perl -e 'print time - (stat shift)[9]' "$cache_file")
@ -85,6 +143,7 @@ else
if [ -z "$live" ]; then
notes+=("线上版本未知(集群不可达或无本机凭据)。")
else
live_verified=1
while read -r deployment commit; do
[ -n "${deployment}" ] || continue
short=${commit:0:8}
@ -102,8 +161,12 @@ if [ ${#warnings[@]} -gt 0 ]; then
echo "⚠ 分支新鲜度检查(${branch}):"
for line in "${warnings[@]}"; do echo " - ${line}"; done
echo " 读代码、诊断线上问题或改动前,请在包含线上版本的独立工作区进行,并告知用户。"
else
elif [ "$base_verified" -eq 1 ] && [ "$fetch_succeeded" -eq 1 ] && [ "$live_verified" -eq 1 ]; then
echo "分支新鲜度检查:${branch} 已是最新(包含 ${base_ref} 与线上版本)。"
elif [ "$base_verified" -eq 1 ]; then
echo "分支新鲜度检查:${branch} 仅完成本地引用比较(包含本地 ${base_ref},远端或线上版本未确认)。"
else
echo "分支新鲜度检查:${branch} 未能完成基线与线上版本确认。"
fi
for line in ${notes[@]+"${notes[@]}"}; do echo " · ${line}"; done
exit 0

View File

@ -14,13 +14,17 @@ class BranchFreshness(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.TemporaryDirectory()
self.root = Path(self.tmp.name)
self.remote = self.root / 'origin.git'
subprocess.check_call(['git', 'init', '--bare', '-q', str(self.remote)])
self.repo = self.root / 'repo'
self.repo.mkdir()
self.git('init', '-q', '-b', 'work')
self.git('config', 'user.name', 'Local test')
self.git('config', 'user.email', 'test@example.invalid')
self.git('remote', 'add', 'origin', str(self.remote))
self.commit('baseline')
self.git('branch', 'dev-sim')
self.git('push', '-q', 'origin', 'HEAD:refs/heads/dev')
self.git('fetch', '-q', 'origin', 'dev')
self.calls = self.root / 'kubectl-calls'
self.kubectl = self.root / 'kubectl'
self.write_kubectl(exit_code=0)
@ -45,18 +49,25 @@ class BranchFreshness(unittest.TestCase):
f'echo -n "${{FAKE_LIVE_COMMIT:-{commit}}}"\n')
self.kubectl.chmod(self.kubectl.stat().st_mode | stat.S_IEXEC)
def run_check(self, live='', cwd=None, **extra):
def run_check(self, live='', cwd=None, cli_args=(), expected_rc=0, **extra):
env = {**os.environ,
'FRESHNESS_BASE_REF': 'dev-sim',
'FRESHNESS_SKIP_FETCH': '1',
'FRESHNESS_BASE_REF': 'origin/dev',
'FRESHNESS_SKIP_FETCH': '0',
'FRESHNESS_KUBECTL': str(self.kubectl),
'FRESHNESS_KUBECONFIG': str(self.root / 'kubeconfig'),
'FRESHNESS_CACHE_FILE': str(self.root / 'cache.txt'),
'FAKE_LIVE_COMMIT': live,
**extra}
result = subprocess.run(['bash', str(SCRIPT)], cwd=cwd or self.repo, env=env, text=True, capture_output=True, timeout=60)
self.assertEqual(result.returncode, 0, result.stderr)
return result.stdout
result = subprocess.run(
['bash', str(SCRIPT), *cli_args],
cwd=cwd or self.repo,
env=env,
text=True,
capture_output=True,
timeout=10,
)
self.assertEqual(result.returncode, expected_rc, result.stderr or result.stdout)
return result.stdout if expected_rc == 0 else (result.stderr + result.stdout)
def kubectl_calls(self):
return len(self.calls.read_text().splitlines()) if self.calls.exists() else 0
@ -67,15 +78,44 @@ class BranchFreshness(unittest.TestCase):
self.assertIn('已是最新', out)
self.assertNotIn('⚠', out)
def test_skip_fetch_does_not_claim_up_to_date(self):
live = self.git('rev-parse', 'HEAD')
out = self.run_check(live=live, FRESHNESS_SKIP_FETCH='1')
self.assertIn('未拉取远端引用', out)
self.assertIn('仅完成本地引用比较', out)
self.assertNotIn('已是最新', out)
def test_cli_flags_disable_fetch_and_cluster(self):
live = self.git('rev-parse', 'HEAD')
out = self.run_check(live=live, cli_args=('--no-fetch', '--no-cluster'))
self.assertEqual(self.kubectl_calls(), 0)
self.assertIn('未拉取远端引用', out)
self.assertIn('未查询线上版本', out)
self.assertIn('仅完成本地引用比较', out)
self.assertNotIn('已是最新', out)
def test_cli_missing_or_empty_base_ref_fails_fast_without_hanging(self):
for bad_args in (('--base-ref',), ('--base-ref', ''), ('--base-ref', '--no-cluster'), ('--base-ref=',)):
with self.subTest(bad_args=bad_args):
out = self.run_check(cli_args=bad_args, expected_rc=2)
self.assertIn('--base-ref', out)
self.assertEqual(self.kubectl_calls(), 0)
def test_cli_unknown_flag_fails_fast_without_querying_cluster(self):
out = self.run_check(cli_args=('--no-clustre',), expected_rc=2)
self.assertIn('未知参数', out)
self.assertEqual(self.kubectl_calls(), 0)
def test_behind_base_branch_is_flagged_with_count(self):
live = self.git('rev-parse', 'HEAD')
self.git('checkout', '-q', 'dev-sim')
self.git('checkout', '-q', '-b', 'dev-advance')
self.commit('dev one')
self.commit('dev two')
self.git('push', '-q', 'origin', 'HEAD:refs/heads/dev')
self.git('checkout', '-q', 'work')
out = self.run_check(live=live)
self.assertIn('⚠', out)
self.assertIn('落后 dev-sim 2 个提交', out)
self.assertIn('落后 origin/dev 2 个提交', out)
def test_missing_live_commit_is_flagged_per_deployment(self):
self.git('checkout', '-q', '-b', 'release')
@ -95,6 +135,21 @@ class BranchFreshness(unittest.TestCase):
self.write_kubectl(exit_code=1)
out = self.run_check()
self.assertIn('线上版本未知', out)
self.assertIn('仅完成本地引用比较', out)
self.assertNotIn('已是最新', out)
def test_failed_fetch_does_not_claim_up_to_date(self):
live = self.git('rev-parse', 'HEAD')
self.git('remote', 'set-url', 'origin', str(self.root / 'missing-origin.git'))
out = self.run_check(live=live)
self.assertIn('未能联网拉取 origin/dev', out)
self.assertIn('仅完成本地引用比较', out)
self.assertNotIn('已是最新', out)
def test_missing_local_base_ref_does_not_claim_up_to_date(self):
out = self.run_check(FRESHNESS_BASE_REF='origin/nonexistent', FRESHNESS_SKIP_CLUSTER='1')
self.assertIn('未能完成基线与线上版本确认', out)
self.assertNotIn('已是最新', out)
def test_live_commits_are_cached_within_ttl(self):
live = self.git('rev-parse', 'HEAD')
@ -112,6 +167,8 @@ class BranchFreshness(unittest.TestCase):
out = self.run_check(FRESHNESS_SKIP_CLUSTER='1')
self.assertEqual(self.kubectl_calls(), 0)
self.assertIn('未查询线上版本', out)
self.assertIn('仅完成本地引用比较', out)
self.assertNotIn('已是最新', out)
def test_outside_git_checkout_exits_quietly(self):
outside = self.root / 'plain'