总体设计与实施手册
版本定位：本文件是 的唯一真源、项目说明入口与工程手册主文档。 文档策略：正文先给出当前真相、入口、边界与验证顺序，再展开设计、实施与路线图。 冲突处理：若本文件与任何派生文档冲突，以本文件为准；派生文档只允许补充，不允许重定义 canonical 边界。
0. 项目说明入口
projectName: <Project Name>
canonicalDoc: README.md
machineReadableEntry: project.json
githubRepo: <repo-url>
defaultBranch: main
localSourceRoot: <local-root>
serverRuntimeRoot: <runtime-root>
publicBaseUrl: <public-api-base>
publicHealthContractPath: <public-health-path>
publicDebugContractPath: <public-debug-path>
consoleUrl: <public-console-url>
serverHost: <server-host>
runtimeHealthUrl: <internal-health-url>
runtimeServiceName: <service-name>
deploymentMode: <deployment-mode>
deploymentRunner: <runner-name>0.1 对外简介
一句话说明项目解决什么问题、对外提供什么能力、对内如何分层。
0.2 快速开始
- 项目名：
<Project Name> - GitHub：
<repo-url> - 本机源码：
<local-root> - 对外入口：
<public-api-base> - 控制台入口：
<public-console-url> - 内部健康检查：
<internal-health-url> - 人类优先读取：
README.md - 机器优先读取：
project.json
0.3 仓库信息卡
| 项目 | 值 |
|---|---|
| GitHub 仓库 | <repo-url> |
| 默认分支 | main |
| 本机工作分支 | <branch> |
| 长期源码真源 | GitHub |
| 本机目录 | <local-root> |
| 服务器目录 | <runtime-root> |
0.4 仓库卫生与运行入口
- Canonical 安装入口：
<install-script> - 运行配置：
<config-path> - repo-managed 运行覆盖：
<overlay-config> - 验证脚本：
<verify-script> - 部署脚本：
<deploy-script>
0.5 Truth Layer
本层只写当前真实运行状态；不写理想态，不写客户端本地配置，不把策略写成事实。
0.5.1 Real Runtime Topology
Client
-> <public-api-base>
-> <ingress/gateway>
-> <internal-target>
-> <runtime-service>
-> <provider/backend>0.5.2 API / Access Truth
<public-api-base>是唯一对外 canonical API 入口。<public-console-url>是唯一对外 canonical console 入口。<internal-target>是当前内部运行目标。
0.5.3 Observability Truth
- 公开 health：
<public-health-path> - 内部 health：
<internal-health-url> - debug / status：
<debug-paths>
0.6 Constraint Layer
0.6.1 Forbidden Actions
- 不允许把历史路径写成当前主路径。
- 不允许把兼容入口写成 canonical 入口。
- 不允许跳过主 health/debug 契约直接下结论。
0.6.2 System Invariants
- 入口不变量：
<invariant> - 路径不变量：
<invariant> - 服务不变量：
<invariant>
0.7 Strategy Layer
0.7.1 Troubleshooting Order
- 先查 Truth Layer 的真实入口与内部目标。
- 再查 Constraint Layer 的禁止事项与不变量。
- 最后按公开 health -> 内部 health -> 最小接口 -> 业务链路的顺序验证。
0.7.2 AI / Operator Execution Protocol
- 先确认 canonical 入口、运行根、服务名。
- 再确认配置入口、脚本入口、验证入口。
- 不允许混淆当前事实与目标态。
