From 6be81903e8b5603836541e2849b8c1d9d04632a2 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 27 May 2026 07:34:44 +0000 Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=20=E5=9B=BA=E5=8C=96=20Agen?= =?UTF-8?q?tRun=20=E4=B8=AD=E6=96=87=E8=BF=90=E7=BB=B4=E8=A7=84=E5=88=99?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + docs/reference/agentrun.md | 78 +++++++++++++++++++++----------------- 2 files changed, 44 insertions(+), 35 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 63a90be1..c3e97ba3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,7 @@ UniDesk 是一个以主 server 为统一入口的分布式工作平台；本文 - 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`。 +- P0: AgentRun 的文档、issue、PR、review 和交付说明一律中文；代码标识符、API path、配置键、命令和必要英文专有名词可保留英文，解释性文字必须中文。 ## Critical G14 HWLAB Workspace Rule diff --git a/docs/reference/agentrun.md b/docs/reference/agentrun.md index ab52c723..f37da5c0 100644 --- a/docs/reference/agentrun.md +++ b/docs/reference/agentrun.md @@ -1,78 +1,86 @@ -# AgentRun Development And Operations +# AgentRun 开发与运维参考 -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. +本文只记录 UniDesk 侧对独立仓库 `pikasTech/agentrun` 的开发与运维约束。AgentRun 的架构设计、MVP 范围、API 契约、runner/backend 协议和运行时内部规则必须维护在 AgentRun 仓库自身，不能放在 UniDesk 长期参考里作为事实来源。 -## Repository And Workspace +## 仓库与 Workspace -The canonical AgentRun repository is `git@github.com:pikasTech/agentrun.git`. +AgentRun 唯一长期仓库是： -The fixed G14 workspace is: +```text +git@github.com:pikasTech/agentrun.git +``` + +G14 固定 workspace 是： ```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: +该目录必须固定使用 `master` 分支，`origin` 必须是 `git@github.com:pikasTech/agentrun.git`，并保持 clean。每次开始 AgentRun 开发、部署、文档修改、恢复中断或上下文压缩后，先通过 UniDesk SSH 透传执行： ```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. +- 当前路径是 `/root/agentrun`； +- 首次推送后分支是 `master...origin/master`； +- `origin` 是 `git@github.com:pikasTech/agentrun.git`； +- 固定 workspace 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. +如果 workspace 缺失、dirty、分支不对或 remote 不对，必须先修正，再继续工作。不得把 `/root/unidesk`、`/root/hwlab`、D601 workspace、临时 clone、runner checkout、pod 内副本或 master-server 副本当作 AgentRun source truth。 -## Worktree Rule +## Worktree 规则 -The fixed workspace is only for precheck, fetch, worktree management and final synchronization. Normal AgentRun feature/docs/deploy work should use an independent worktree: +固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规 AgentRun 功能、文档和部署修改必须使用独立 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. +Worktree 必须从最新 `origin/master` 创建，任务分支只覆盖当前变更，提交时只提交当前任务相关文件。不要把 `/root/agentrun` 根目录当作并行任务 scratch 区。 -## Deployment Targets +## 部署目标 -Default AgentRun deployment targets are G14 native k3s namespaces: +AgentRun 默认部署目标是 G14 原生 k3s namespace： ```text G14:k3s namespace agentrun_dev G14:k3s namespace agentrun_prod ``` -Use UniDesk route syntax for all k3s operations: +所有 k3s 操作必须使用 UniDesk route 语法： ```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. +不得把临时 NodePort、host port、pod IP、provider-gateway 业务 HTTP proxy 或一次性 port-forward 固化为 AgentRun 部署路径。任何公网入口、UniDesk/HWLAB 集成入口或跨服务访问路径，都必须先通过 AgentRun 仓库内经过审查的变更引入；UniDesk 只在后续记录对应运维入口。 -## UniDesk Boundary +## UniDesk 边界 -UniDesk is the distributed development and operations center for AgentRun. UniDesk may document: +UniDesk 是 AgentRun 的综合分布式开发和运维中心。UniDesk 可以记录： -- 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. +- AgentRun 的固定仓库、workspace 和 worktree 规则； +- G14 预检、route 语法和远程操作入口； +- 默认 DEV/PROD namespace； +- 部署观察、受控 rollout 和运维入口； +- AgentRun 仓库定义公共契约后，UniDesk 与 HWLAB 如何接入。 -UniDesk must not be the source of truth for: +UniDesk 不能作为以下内容的事实来源： -- AgentRun service architecture; -- MVP phase plan; -- RESTful API contract; -- runner/backend protocol; -- database schema; -- tenant policy model; -- backend adapter design. +- AgentRun 服务架构； +- MVP 阶段规划； +- RESTful API 契约； +- runner/backend 协议； +- 数据库 schema； +- tenant policy 模型； +- backend adapter 设计。 -Those topics belong in the AgentRun repository under its own `AGENTS.md` and `docs/reference/`. +这些内容必须维护在 AgentRun 仓库自己的 `AGENTS.md` 和 `docs/reference/` 中。 + +## 中文规则 + +AgentRun 仓库内容默认中文。AgentRun 长期文档、过程文档、issue 标题与正文、PR 标题与正文、PR 评论、review 说明和交付总结都必须使用中文。代码标识符、API path、命令名、配置键、日志字段、协议字段和不可避免的外部专有名词可以保留英文，但解释性文字必须使用中文。