docs: add agentrun operations reference

2026-05-27 07:26:21 +00:00
parent fc7902f709
commit d7ebed6ced
2 changed files with 84 additions and 0 deletions
@@ -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/`.