docs: bootstrap agentrun references

2026-05-27 15:27:38 +08:00
commit 09c59a4dd6
5 changed files with 347 additions and 0 deletions
@@ -0,0 +1,39 @@
+# AgentRun Agent Index
+
+AgentRun is the shared agent execution infrastructure for UniDesk and HWLAB. This repository owns AgentRun architecture, API contracts, runner/backend behavior and runtime implementation. UniDesk only records how distributed development and deployment are coordinated from the UniDesk control center.
+
+## Critical Source Workspace Rule
+
+- P0: The canonical source workspace is `G14:/root/agentrun`, fixed on branch `master`, with `origin git@github.com:pikasTech/agentrun.git`.
+- P0: Before development, deployment, resumed work or context recovery, run `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'` from UniDesk and confirm the path, branch, remote and clean state.
+- P0: The fixed workspace is only for precheck, fetch, worktree management and final sync. Normal work must use `/root/agentrun/.worktree/{pr_branch}` created from latest `origin/master`.
+- P0: Do not use UniDesk, HWLAB, D601 workspaces, temporary clones, pod-local copies or runner checkouts as AgentRun source truth.
+
+## Critical Runtime Target Rule
+
+- P0: Default deployment targets are G14 native k3s namespaces `agentrun_dev` and `agentrun_prod`.
+- P0: Kubernetes operations must use UniDesk route syntax `G14:k3s`, for example `tran G14:k3s kubectl get pods -n agentrun_dev`.
+- P0: Do not create durable AgentRun exposure through ad hoc NodePort, host port, direct pod IP, one-off port-forward or provider-gateway business HTTP proxy. Public or cross-service access must be introduced through reviewed repository changes.
+
+## Critical MVP Rule
+
+- P0: AgentRun must be developed as a vertical MVP, not as a broad parallel service rewrite.
+- P0: First prove minimal `runner + one backend`; then add `agentrun-mgr` durable facts and manual runner startup; only after that add automatic scheduler.
+- P0: Existing UniDesk Code Queue and HWLAB Code Agent paths are not replaced by default. AgentRun starts as a new shared execution plane with canary integrations.
+
+## Critical RESTful MVP Rule
+
+- P0: The MVP uses short RESTful HTTP/JSON requests only. Do not add SSE, WebSocket, long-polling or long synchronous `turn` calls in the first phase.
+- P0: Long agent work must be represented by asynchronous resources: commands, runs, events, status and leases. Clients observe progress by paged polling.
+- P0: Runner inbound API should stay private and minimal. Clients should call `agentrun-mgr`; manually started runners must still claim and report through the manager.
+
+## Critical CLI Spec Rule
+
+- P0: AgentRun CLI and service work must follow the UniDesk `cli-spec` principles: JSON output by default, no empty-success output, no long blocking CLI calls, visible logs, explicit config validation and RESTful service APIs for stable boundaries.
+- P0: Once a CLI is added, keep the entry small and move implementation into `scripts/src/`; long operations must return quickly and expose status/log/event polling.
+
+## Reference Docs
+
+- `docs/reference/architecture.md`: AgentRun product boundary, service architecture, MVP phases, RESTful API model and data model.
+- `docs/reference/cli.md`: CLI and service API conventions derived from `cli-spec`.
+- `TEST.md`: manual validation scenarios for the documented CLI/service behavior as it is implemented.