From d7ebed6ced689de526865215ee91afc8805e4aef Mon Sep 17 00:00:00 2001
From: Codex <codex@noreply.local>
Date: Wed, 27 May 2026 07:26:21 +0000
Subject: [PATCH] docs: add agentrun operations reference

---
 AGENTS.md                  |  6 +++
 docs/reference/agentrun.md | 78 ++++++++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)
 create mode 100644 docs/reference/agentrun.md

diff --git a/AGENTS.md b/AGENTS.md
index a5e3bd89..63a90be1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -42,6 +42,12 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文
 
 - P0: `hyueapi.com` / `.hyueapi.com` 是 Codex API 通道的直连域名，必须始终保留在 `NO_PROXY` / `no_proxy` 中；DeepSeek、Codex API 或其他 provider profile 切换、G14 proxy 注入、旧 D601 egress 迁移和 pod/env render 都不得把 hyueapi 流量改成走 HTTP/SOCKS proxy。
 
+## Critical AgentRun Workspace Rule
+
+- P0: `pikasTech/agentrun` 是新的共享 Agent 执行基础设施仓库，不是现有 Code Queue 的就地替换；默认 source truth 是 G14 节点 `/root/agentrun`，固定使用 `master` 分支和 `origin git@github.com:pikasTech/agentrun.git`。
+- P0: AgentRun 开发必须先预检 `G14:/root/agentrun` 的路径、分支、remote 和 clean 状态，再在 `/root/agentrun/.worktree/{pr_branch}` 创建独立 worktree 修改；不要把固定 repo、UniDesk、HWLAB、D601 或临时 clone 当作 AgentRun scratch 区。
+- P0: AgentRun 默认部署目标是 `G14:k3s` 上的 `agentrun_dev` 与 `agentrun_prod` namespace；所有 k3s 操作必须使用 route 语法 `G14:k3s`，UniDesk 侧只维护 AgentRun 的开发和部署运维约束，细则见 `docs/reference/agentrun.md`。
+
 ## Critical G14 HWLAB Workspace Rule
 
 - P0: `G14:HWLAB` 是当前 HWLAB DEV/PROD source workspace 和 k3s/GitOps 运行面真相；唯一长期 source workspace 是 G14 节点上的 `/root/hwlab`，固定使用 `G14` 分支和 `origin git@github.com:pikasTech/HWLAB.git`；所有 HWLAB 新开发、文档、render、polling、CI/CD/GitOps 修复默认都必须以该目录和 G14 运行面为准。
diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md
new file mode 100644
index 00000000..ab52c723
--- /dev/null
+++ b/docs/reference/agentrun.md
@@ -0,0 +1,78 @@
+# AgentRun Development And Operations
+
+This document records only UniDesk-side development and operations rules for the separate `pikasTech/agentrun` repository. AgentRun architecture, MVP scope, API design and runtime internals must live in the AgentRun repository itself, not in UniDesk reference docs.
+
+## Repository And Workspace
+
+The canonical AgentRun repository is `git@github.com:pikasTech/agentrun.git`.
+
+The fixed G14 workspace is:
+
+```text
+G14:/root/agentrun
+```
+
+It must stay on branch `master`, use `origin git@github.com:pikasTech/agentrun.git`, and remain clean except for explicitly identified parallel local changes. Before any AgentRun development, deployment, documentation edit, resumed work or context recovery, run:
+
+```bash
+tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'
+```
+
+Expected state:
+
+- path is `/root/agentrun`;
+- branch is `master...origin/master` after the first remote push;
+- `origin` is `git@github.com:pikasTech/agentrun.git`;
+- fixed workspace is clean.
+
+If the workspace is missing, dirty, on the wrong branch, or pointed at the wrong remote, repair that first. Do not use `/root/unidesk`, `/root/hwlab`, D601 workspaces, temporary clones, runner checkouts, pod-local copies or master-server copies as AgentRun source truth.
+
+## Worktree Rule
+
+The fixed workspace is only for precheck, fetch, worktree management and final synchronization. Normal AgentRun feature/docs/deploy work should use an independent worktree:
+
+```text
+G14:/root/agentrun/.worktree/{pr_branch}
+```
+
+Create worktrees from latest `origin/master`, keep task branches scoped to the current change, and commit only task-related files. Do not use `/root/agentrun` itself as a parallel scratch directory.
+
+## Deployment Targets
+
+Default AgentRun deployment targets are G14 native k3s namespaces:
+
+```text
+G14:k3s namespace agentrun_dev
+G14:k3s namespace agentrun_prod
+```
+
+Use UniDesk route syntax for all k3s operations:
+
+```bash
+tran G14:k3s kubectl get pods -n agentrun_dev
+tran G14:k3s kubectl get pods -n agentrun_prod
+```
+
+Do not use ad hoc NodePort, host port, direct pod IP, provider-gateway business HTTP proxy, or one-off port-forward as a durable AgentRun deployment path. Any public, UniDesk, HWLAB or cross-service integration path must be introduced through reviewed AgentRun repository changes and then reflected in UniDesk deployment/config docs only as an operations entry.
+
+## UniDesk Boundary
+
+UniDesk is the distributed development and operations center for AgentRun. UniDesk may document:
+
+- canonical repository, workspace and worktree rules;
+- G14 precheck and route syntax;
+- default DEV/PROD namespaces;
+- deployment observation and controlled rollout entrypoints;
+- how UniDesk and HWLAB should reach AgentRun once the AgentRun repo defines the public contract.
+
+UniDesk must not be the source of truth for:
+
+- AgentRun service architecture;
+- MVP phase plan;
+- RESTful API contract;
+- runner/backend protocol;
+- database schema;
+- tenant policy model;
+- backend adapter design.
+
+Those topics belong in the AgentRun repository under its own `AGENTS.md` and `docs/reference/`.