AgentRun 开发与运维参考

本文只记录 UniDesk 侧对独立仓库 pikasTech/agentrun 的开发与运维约束。AgentRun 的架构设计、MVP 范围、API 契约、runner/backend 协议和运行时内部规则必须维护在 AgentRun 仓库自身，不能放在 UniDesk 长期参考里作为事实来源。

仓库与 Workspace

AgentRun 唯一长期仓库是：

git@github.com:pikasTech/agentrun.git

G14 固定 workspace 是：

G14:/root/agentrun

该目录必须固定使用 master 分支，origin 必须是 git@github.com:pikasTech/agentrun.git，并保持 clean。每次开始 AgentRun 开发、部署、文档修改、恢复中断或上下文压缩后，先通过 UniDesk SSH 透传执行：

tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'

期望状态：

当前路径是 /root/agentrun；
首次推送后分支是 master...origin/master；
origin 是 git@github.com:pikasTech/agentrun.git；
固定 workspace clean。

如果 workspace 缺失、dirty、分支不对或 remote 不对，必须先修正，再继续工作。不得把 /root/unidesk、/root/hwlab、D601 workspace、临时 clone、runner checkout、pod 内副本或 master-server 副本当作 AgentRun source truth。

Worktree 规则

固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规 AgentRun 功能、文档和部署修改必须使用独立 worktree：

G14:/root/agentrun/.worktree/{pr_branch}

Worktree 必须从最新 origin/master 创建，任务分支只覆盖当前变更，提交时只提交当前任务相关文件。不要把 /root/agentrun 根目录当作并行任务 scratch 区。

部署目标

AgentRun 默认部署目标是 G14 原生 k3s namespace：

G14:k3s namespace agentrun_dev
G14:k3s namespace agentrun_prod

所有 k3s 操作必须使用 UniDesk route 语法：

tran G14:k3s kubectl get pods -n agentrun_dev
tran G14:k3s kubectl get pods -n agentrun_prod

不得把临时 NodePort、host port、pod IP、provider-gateway 业务 HTTP proxy 或一次性 port-forward 固化为 AgentRun 部署路径。任何公网入口、UniDesk/HWLAB 集成入口或跨服务访问路径，都必须先通过 AgentRun 仓库内经过审查的变更引入；UniDesk 只在后续记录对应运维入口。

UniDesk 边界

UniDesk 是 AgentRun 的综合分布式开发和运维中心。UniDesk 可以记录：

AgentRun 的固定仓库、workspace 和 worktree 规则；
G14 预检、route 语法和远程操作入口；
默认 DEV/PROD namespace；
部署观察、受控 rollout 和运维入口；
AgentRun 仓库定义公共契约后，UniDesk 与 HWLAB 如何接入。

UniDesk 不能作为以下内容的事实来源：

AgentRun 服务架构；
MVP 阶段规划；
RESTful API 契约；
runner/backend 协议；
数据库 schema；
tenant policy 模型；
backend adapter 设计。

这些内容必须维护在 AgentRun 仓库自己的 AGENTS.md 和 docs/reference/ 中。

中文规则

AgentRun 仓库内容默认中文。AgentRun 长期文档、过程文档、issue 标题与正文、PR 标题与正文、PR 评论、review 说明和交付总结都必须使用中文。代码标识符、API path、命令名、配置键、日志字段、协议字段和不可避免的外部专有名词可以保留英文，但解释性文字必须使用中文。

3.4 KiB Raw Blame History Unescape Escape