# AgentRun 开发与运维参考

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

## 仓库与 Worktree

AgentRun 唯一长期仓库是：

```text
git@github.com:pikasTech/agentrun.git
```

AgentRun 当前 `v0.1` 固定 source worktree 是：

```text
G14:/root/agentrun-v01
```

该目录必须固定使用 `v0.1` 分支，`origin` 必须是 `git@github.com:pikasTech/agentrun.git`，并保持 clean。任何明确面向 UniDesk/HWLAB 基础 Code Agent 调用服务 `v0.1` 的开发、文档修改、部署观察或恢复中断后，先通过 UniDesk SSH 透传执行：

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

期望状态：

- 当前路径是 `/root/agentrun-v01`；
- 分支是 `v0.1...origin/v0.1`；
- `origin` 是 `git@github.com:pikasTech/agentrun.git`；
- 固定 source worktree clean。

如果固定 source worktree 缺失、dirty、分支不对或 remote 不对，必须先修正，再继续工作。不得把 `/root/agentrun` 主线历史目录、`/root/unidesk`、`/root/hwlab`、D601 workspace、临时 clone、runner checkout、pod 内副本或 master-server 副本当作 AgentRun `v0.1` source truth。

## Worktree 规则

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

```text
G14:/root/agentrun-v01/.worktree/{pr_branch}
```

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

## 文档落库规则

AgentRun 的 SPEC 和长期参考文档变更不创建 PR。完成本地审查后，必须直接提交并推送到对应目标分支，例如 `origin/v0.1`。过程计划、阶段证据、验收结果和阻塞点写入对应 GitHub issue 评论区，不能用文档 PR 代替直接落库。

## 部署目标

AgentRun 废弃旧 `dev/prod` 运行口径。`v0.1` 固定部署目标是 G14 原生 k3s namespace：

```text
G14:k3s namespace agentrun-v01
```

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

```bash
tran G14:k3s kubectl get pods -n agentrun-v01
```

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

## 受控 CI/CD 入口

AgentRun `v0.1` 的 Tekton/Argo 控制面写操作必须通过 UniDesk 高层 CLI 执行：

```bash
bun scripts/cli.ts agentrun v01 control-plane status
bun scripts/cli.ts agentrun v01 control-plane trigger-current --dry-run
bun scripts/cli.ts agentrun v01 control-plane trigger-current --confirm
bun scripts/cli.ts agentrun v01 control-plane refresh --dry-run
bun scripts/cli.ts agentrun v01 control-plane refresh --confirm
```

`status` 只读观察 `G14:/root/agentrun-v01` 当前 commit、对应 PipelineRun、GitOps latest、Argo Application 和 `agentrun-v01` workload 摘要，并报告 Argo revision 是否对齐 `v0.1-gitops` latest。`trigger-current` 会先把固定 source worktree 快进到 `origin/v0.1`，再以当前 commit 创建 commit-pinned PipelineRun；同名 PipelineRun 正在运行或已经成功时必须拒绝重复触发，只允许在失败态或不存在时创建。该命令只提交 CI/CD 工作，不等待完整 PipelineRun 或 rollout 完成，后续用 `status` 轮询。`refresh` 只对 `argocd/agentrun-g14-v01` 执行 hard refresh，用于 GitOps promotion 已完成但 Argo 仍停留旧 revision 时的受控同步入口；它不直接 patch runtime workload。

## UniDesk 边界

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

- AgentRun 的固定仓库、source worktree 和 worktree 规则；
- G14 预检、route 语法和远程操作入口；
- `v0.1` 固定 namespace 与后续版本 lane 规则；
- 部署观察、受控 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、命令名、配置键、日志字段、协议字段和不可避免的外部专有名词可以保留英文，但解释性文字必须使用中文。