From 17f6389623fbccc3d7a0b2dec169671df53bc084 Mon Sep 17 00:00:00 2001 From: Codex Date: Fri, 15 May 2026 05:00:54 +0000 Subject: [PATCH] docs: document single-path sync discipline --- AGENTS.md | 6 ++++++ docs/reference/arch.md | 10 ++++++++++ 2 files changed, 16 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 5365f6f3..d01f960c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,12 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文件是项目顶级索引，也承担 `scripts/cli.ts` 的 CLI 使用说明入口。 +## Critical Git / Multi-Repo Sync Rule + +- UniDesk 同时存在 main server、D601 `~/cq-deploy` 和其他 provider worktree 等多个开发/部署实例；Git remote 是长期 source of truth，本地部署实例只能视为运行副本或缓存。 +- 任何需要保留的代码、文档或配置变更，在完成必要自测/部署验证后必须立刻按 `git-spec` 提交并 push 到 remote；禁止让未推送的本地修改成为部署真相或后续任务依赖。 +- 提交前必须用 `git status` 和 `git diff` 区分并只提交当前任务相关文件，保留并避开并行任务产生的无关修改；长期规则见 `docs/reference/arch.md`。 + ## Critical Provider Gateway Upgrade Rule - `src/components/provider-gateway` 有任何代码或行为变更时，必须在同一变更集中递增 `src/components/provider-gateway/package.json` 的版本号，并在升级后通过 frontend 或 `debug health` 确认目标节点上报新版本；权威规则见 `docs/reference/provider-gateway.md`。 diff --git a/docs/reference/arch.md b/docs/reference/arch.md index 890888ee..f8828b27 100644 --- a/docs/reference/arch.md +++ b/docs/reference/arch.md @@ -64,6 +64,16 @@ - All state changes are reported to the main server in real time by Provider Gateway - The main server writes state updates to PostgreSQL, completing the unified closed loop - Pipeline workflow control follows the OA event-flow model: OA is the only control bus, factual node events remain policy-neutral, and runner/monitor/frontend/CLI actions are represented as OA events; detailed constraints live in `docs/reference/pipeline-oa-event-flow.md` + - Single Authoritative Path Discipline + - Every durable capability must declare one authoritative data, control, event, or network path in reference docs, API contracts, health output, and E2E checks; frontend, CLI, worker, and service code must consume that path directly. + - Hidden fallback is forbidden. A service must not silently answer from local JSON, transcripts, in-memory state, stale task caches, direct host URLs, old service IDs, alternate proxies, local direct internet, or legacy event streams when the documented path is unavailable. + - Failure must be explicit and observable through HTTP status, response body, `/health`, diagnostics, frontend degraded state, or test output. If temporary compatibility is unavoidable, it must be documented as a bounded migration or degraded mode with a visible status marker, validation gate, and removal condition. + - Migration bridges may normalize legacy facts into the authoritative bus or table, but must not become a second source of truth or keep read-time dual-path fallback after the authoritative path is ready. + - Multi-Repo Deployment Sync + - The main server repository, D601 deployment tree, provider-local worktrees, and other live copies are working or deployment instances; the Git remote is the long-term project source of truth. + - Any source, document, or persistent configuration change intended to survive the current task must be committed and pushed to the remote promptly after required self-tests or deployment validation, following `git-spec`. + - Live deployment should run from a known commit or from a change set that is immediately committed and pushed; local-only hotfixes must not become the implicit dependency for later tasks. + - Secrets, tokens, generated runtime state, and node-local env files stay outside Git, but their required contract, storage location, and recovery path must be documented so pushing source changes is not blocked by runtime-only data. - Critical Task Deployment Principles - Single-point components such as the database, core scheduler logic, and API gateway are deployed on the main server - The high-availability environment of the main server ensures the critical scheduling path never breaks