AgentRun Agent 索引

AgentRun 是面向 UniDesk 与 HWLAB 的共享 Agent 执行基础设施。本仓库负责 AgentRun 架构、API 契约、runner/backend 行为和运行时实现。UniDesk 只记录如何从 UniDesk 综合分布式开发中心协调 AgentRun 的开发与部署。

Critical Chinese Documentation Rule

P0: 唯一长期 source workspace 是 G14:/root/agentrun，固定使用 master 分支，origin 固定为 git@github.com:pikasTech/agentrun.git。
P0: 每次开发、部署、恢复中断或上下文压缩后，都必须先从 UniDesk 执行 tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'，确认路径、分支、remote 和 clean 状态。
P0: 固定 workspace 只用于预检、fetch、worktree 管理和最终同步。常规修改必须在 /root/agentrun/.worktree/{pr_branch} 中完成，并从最新 origin/master 创建。
P0: 不得把 UniDesk、HWLAB、D601 workspace、临时 clone、pod 内副本或 runner checkout 当作 AgentRun source truth。

P0: 默认部署目标是 G14 原生 k3s namespace：agentrun_dev 和 agentrun_prod。
P0: Kubernetes 操作必须使用 UniDesk route 语法 G14:k3s，例如 tran G14:k3s kubectl get pods -n agentrun_dev。
P0: 不得通过临时 NodePort、host port、pod IP、一次性 port-forward 或 provider-gateway 业务 HTTP proxy 固化 AgentRun 暴露路径。公网或跨服务入口必须通过本仓库审查后的变更引入。

P0: AgentRun 必须按纵向 MVP 开发，不能一开始并行铺开成多服务大重写。
P0: 先证明最小 runner + 一个 backend；再加入 agentrun-mgr 的 durable facts 和手动启动 runner；最后再加入自动 scheduler。
P0: 现有 UniDesk Code Queue 和 HWLAB Code Agent 路径默认不被 AgentRun 替换。AgentRun 先作为新的共享执行面，通过 canary 集成逐步验证。

P0: MVP 阶段只使用短 RESTful HTTP/JSON 请求。第一阶段不做 SSE、WebSocket、long-polling 或长同步 turn 请求。
P0: 长时间 Agent 工作必须表示为异步资源：commands、runs、events、status 和 leases。客户端通过分页轮询观察进度。
P0: Runner inbound API 应保持私有且最小。业务客户端调用 agentrun-mgr；人工启动的 runner 也必须通过 manager claim 和 report。

P0: AgentRun CLI 和服务开发必须遵循 UniDesk cli-spec 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞 CLI、日志可见、配置显式校验、稳定跨服务边界优先使用 RESTful API。
P0: 一旦新增 CLI，入口文件必须保持轻量，具体实现拆入 scripts/src/；长任务必须快速返回，并提供 status/log/event 轮询。