# NC01 参考

## 主机身份

- `NC01` 就是当前 Codex/UniDesk shell 所在主机，不是另一台远端机器。
- 当前工作目录 `/root/unidesk`、HWLAB 固定仓库 `/root/hwlab-v03` 和
  AgentRun 固定仓库 `/root/agentrun-v02` 都位于同一台 NC01 主机。
- `trans NC01 ...` 是访问当前主机的受控 provider route；使用该 route 不会把
  NC01 变成跨主机执行面，也不能据此推断存在远端源码副本、网络边界或第二份状态。
- 普通本机源码读取、worktree 开发和轻量 Git 操作直接使用上述绝对路径；
  Kubernetes 运维继续使用 `trans NC01:k3s ...`，需要受控 provider 语义的主机
  运维继续使用 `trans NC01 ...`。
- 文档中的 `Master server`、控制端或当前主机在未由 owning YAML 明确选择其他
  node 时都指 NC01 的逻辑角色，不得误解成 NC01 之外的默认执行节点。

## 事实来源

- 主机 k8s/provider 配置：`config/unidesk-host-k8s.yaml`。
- 主机代理配置：`config/platform-infra/host-proxy.yaml#targets.NC01`；NC01 的
  host-proxy 使用 `/root/vpn-server` 作为 VPN server 源码来源。
- HWLAB node/lane 配置：`config/hwlab-node-lanes.yaml#lanes.v03.targets.NC01`。
- HWLAB 控制面配置：`config/hwlab-node-control-plane.yaml#nodes.NC01`。
- AgentRun 配置：`config/agentrun.yaml`，lane 为 `nc01-v02`。
- NC01 host PostgreSQL 配置：`config/platform-db/postgres-nc01.yaml`。

## UniDesk Server 运行面

NC01 在 `unidesk` namespace 的 Kubernetes 中运行 UniDesk server/backend-core，
配置权威是 `config/unidesk-host-k8s.yaml`。恢复、验证和 `trans` 操作必须指向
`NC01:k3s` 及对应 Kubernetes 对象。Docker Compose project 或名为
`unidesk-backend-core` 的容器不是 NC01 server 运行面，不能作为恢复证据。
Kubernetes 运行面 healthy 后，除非用户或 owning runbook 明确要求，不得重建、
重启或替换。

## 固定仓库

- HWLAB v0.3：`/root/hwlab-v03`；分支和 remote 来自
  `config/hwlab-node-lanes.yaml`。
- AgentRun v0.2：`/root/agentrun-v02`；分支和 remote 来自
  `config/agentrun.yaml`。
- UniDesk 源码和配置权威：`/root/unidesk`。

这些路径是 NC01 本机路径。不得因为 owning YAML 同时声明 `node: NC01` 或 CLI
支持 `trans NC01:<workspace>`，就把它们描述成远端 workspace。

## 数据库边界

NC01 数据库位置由各 owning YAML 独立选择，不能使用主机级假设。
`config/unidesk-host-k8s.yaml`、`config/agentrun.yaml` 和
`config/hwlab-node-lanes.yaml` 分别声明其 workload 使用 host-native/external
PostgreSQL 还是 lane-local Kubernetes PostgreSQL。验证必须报告选中的模式及对应
Service/SecretRef，不得要求未选中模式的对象存在。

HWLAB v0.3 由 `config/hwlab-node-lanes.yaml` 中的
`runtimeStore.postgres.mode` 选择数据库模式：

- platform-service 模式使用 YAML 声明的 external PostgreSQL bridge，例如
  `nc01-host-postgres`；
- local-k3s 模式使用 lane-local PostgreSQL 对象，并把 external bridge 报告为
  not required；
- runtime database Secret 只能来自选中模式的 YAML `sourceRef`；本地来源位于
  `/root/.unidesk/.state/secrets/hwlab/*`，只允许报告 presence/fingerprint，
  不得输出完整值。

## Decision Center

Decision Center production 运行在 NC01 k8s 的 `unidesk` namespace，不运行在
裸 Docker/Compose，也不使用旧 D601 Decision Center 路径。运行对象是
`deployment/decision-center` 和 `service/decision-center`；GitHub storage 凭据通过
`decision-center-github-ssh` Secret 分发，只允许报告对象/key presence 或
fingerprint。

durable store 是 GitHub 仓库 `pikasTech/decision-center-data` 的 `main` 分支，
base path 为 `data`。PostgreSQL 只是 service index/cache，不是 durable source of
truth。数据迁移或修复后同时验证：

- service health 显示 `storage.primary=github-repo`、`recordCount` 和
  `diaryEntryCount`；
- `/api/storage/verify` 报告 cache 与 repo index count 且 delta 为零；
- repo worktree HEAD 与 `git ls-remote origin refs/heads/main` 一致；
- `bun scripts/cli.ts decision health`、`decision list` 和
  `decision diary list` 通过 NC01 k8s 入口成功。

导出遗留 PostgreSQL 数据时，不得把 Markdown 正文作为普通 JSONL 输出到终端。
使用单行安全编码，例如每行 hex 编码 JSON；同时生成包含行数和 SHA-256 的
manifest，经 `trans download/upload` 传输，并在宣称迁移完成前比较 canonical
source 与 target hash。

## GitHub Token

本地 GitHub token 来源是 `/root/.unidesk/.env/gh_token.txt`。它必须保存为纯 token，
并通过受控 YAML/sourceRef 或临时不打印的 credential helper 使用。禁止放入命令
argv、日志、提交文件或渲染 manifest。NC01 遵循
[Worktree-Independent Local State](devops-hygiene.md#worktree-independent-local-state)
中的 owner-level state 与 compatibility symlink 合同；worktree 通过固定绝对路径
使用 `/root/.unidesk/.env` 和 `/root/.unidesk/.state`，不得复制本地状态目录。

## 公网暴露

NC01 HWLAB v0.3 只有在 YAML 显式声明 `publicExposure` 且存在真实 FRP token 来源时
才要求公网暴露。缺少 `publicExposure` 时，控制面跳过 public probe，不得阻塞
runtime readiness。

需要公网 ingress 的 web-probe sentinel 必须声明自身 YAML `publicExposure` 和
Secret `sourceRef`。不得创建占位 FRP token；依赖 FRP 暴露时，缺少
`platform-infra/pk01-frp.env` token source 是部署 blocker。

## 验证入口

- Provider/trans：`scripts/trans NC01 argv true`。
- NC01 k8s：`scripts/trans NC01:k3s kubectl get nodes -o wide`。
- Decision Center：`bun scripts/cli.ts decision health`；storage 下钻可在 NC01
  `decision-center` Pod 内调用 `/api/storage/verify`。
- HWLAB v0.3：
  `bun scripts/cli.ts hwlab nodes control-plane status --node NC01 --lane v03 --full`。
- AgentRun v0.2：
  `bun scripts/cli.ts agentrun control-plane status --node NC01 --lane nc01-v02`。