pikasTech-agentrun/AGENTS.md

# AgentRun Agent 索引

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

## Critical Chinese Documentation Rule

- P0: AgentRun 的所有长期文档、过程文档、issue、PR 标题、PR 正文、PR 评论和交付说明一律使用中文。
- P0: 代码标识符、API 路径、命令、配置键、日志字段、协议字段和必要英文专有名词可以保留英文，但解释性文字必须使用中文。
- P0: 外部英文资料只能作为引用或短摘录出现；落入本仓库的设计结论、验收标准和操作说明必须转写为中文。
- P0: SPEC 和长期参考文档变更不创建 PR，必须在完成本地审查后直接提交并推送到对应目标分支；过程计划和证据写入 GitHub issue 评论区，不能用文档 PR 代替直接落库。

## Critical Source Worktree Rule

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

## Critical Versioned Lane Rule

- P0: AgentRun 废弃 `dev/prod` 管理口径，后续按 `v0.1`、`v0.2`、`v0.3` 这种版本 lane 滚动；每条 lane 拥有独立 branch、workspace、namespace、GitOps desired state 和发布验收。
- P0: `v0.1` 固定部署目标是 G14 原生 k3s namespace `agentrun-v01`；不得继续把 `agentrun_dev` 或 `agentrun_prod` 当作当前规格、验收或发布目标。
- P0: Kubernetes 操作必须使用 UniDesk route 语法 `G14:k3s`，例如 `tran G14:k3s kubectl get pods -n agentrun-v01`。
- P0: 不得通过临时 NodePort、host port、pod IP、一次性 port-forward 或 provider-gateway 业务 HTTP proxy 固化 AgentRun 暴露路径。公网或跨服务入口必须通过本仓库审查后的变更引入。

## Critical MVP Rule

- P0: AgentRun 必须按纵向 MVP 开发，不能一开始并行铺开成多服务大重写。
- P0: 先证明最小 `runner + 一个 backend`；再加入 `agentrun-mgr` 的 durable facts 和手动启动 runner；最后再加入自动 scheduler。
- P0: UniDesk Code Queue 的下一阶段收敛方向是被 AgentRun Queue 直接吸收；不得做长期 adapter 过渡、双写或旧 API/UI/CLI 兼容层。旧 Code Queue 只保留冻结/归档语义，新任务进入 AgentRun Queue。
- P0: `v0.1` 面向 HWLAB v0.2 的下一阶段目标是先通过 `agentrun-mgr` 手动调度 API 提供 canary 服务；HWLAB `hwlab-cloud-api` 负责显式创建 run/command 并启动 runner Job，自动 scheduler 不作为前置条件。

## Critical RESTful MVP Rule

- 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。

## Critical CLI Spec Rule

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

## Critical v0.1 Implementation Stack Rule

- P0: AgentRun `v0.1` 自研 runtime、CLI、manager、runner、backend adapter、Codex backend 和后续 scheduler 的优先实现语言是 Bun + TypeScript；官方 TypeScript CLI 入口是 `scripts/agentrun-cli.ts`，G14/CI/人工非交互命令使用 `./scripts/agentrun` 启动同一入口，复杂逻辑拆入 `scripts/src/` 和 `src/`。
- P0: `backendProfile=codex`、`backendProfile=deepseek` 与 `backendProfile=minimax-m3` 都必须通过同一个 Codex CLI app-server stdio backend kind 执行，启动受控 `codex app-server --listen stdio://`，使用 JSON-RPC 方法 `initialize`、`thread/start` 或 `thread/resume`、`turn/start`；DeepSeek 和 MiniMax-M3 都是 profile/config/SecretRef 选择，不是直接 Responses HTTP 代理、独立 fake provider 或文本 fallback。
- P0: `codex`、`deepseek` 与 `minimax-m3` profile 必须使用 profile-scoped SecretRef 和 writable `CODEX_HOME`，不得互相 fallback、复用运行态文件或污染默认 `codex` profile；切换顺序必须可验证为 `codex -> deepseek -> minimax-m3 -> codex` 均独立。
- P0: 实现 Codex stdio backend/profile 前必须参考 UniDesk Code Queue 的 `src/components/microservices/code-queue/src/code-agent/codex.ts`、`common.ts`，以及 HWLAB 的 `internal/cloud/codex-stdio-session.mjs`、`scripts/code-agent-chat-smoke.mjs`、`docs/reference/spec-v02-deepseek-proxy.md`、`docs/reference/code-agent-chat-readiness.md`；复用协议、redaction、trace、failure 分类、profile overlay 和 Secret projection 经验，不复制环境专用路径或明文密钥。

## 长期参考文档

- `docs/reference/spec-v01-documentation-governance.md`：v0.1 文档治理、唯一入口、spec 权威和过程材料承载规则。
- `docs/reference/spec-v01-services.md`：v0.1 服务总览、保留对象、deferred 对象和单服务规格索引。
- `docs/reference/spec-v01-cicd.md`：v0.1 分支、source worktree、git mirror、env reuse、namespace、GitOps、registry、CI/CD 和发布验收规格。
- `docs/reference/spec-v01-postgres.md`：v0.1 Postgres durable store、schema migration 和 SecretRef 规格。
- `docs/reference/spec-v01-secret-distribution.md`：v0.1 Code Agent provider credential 和运行时 Secret 分发规格。
- `docs/reference/spec-v01-runtime-assembly.md`：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、Git-only ResourceBundleRef 和 tool credential SecretRef scope。
- `docs/reference/spec-v01-queue.md`：v0.1 AgentRun Queue 直接吸收 UniDesk Code Queue 的 RESTful API、CLI、数据模型、Session 边界和验收规格。
- `docs/reference/spec-v01-hwlab-manual-dispatch.md`：v0.1 通过手动调度 API 为 HWLAB v0.2 提供 canary Code Agent 服务的目标、缺口和增强计划。
- `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。
- `docs/reference/spec-v01-agentrun-mgr.md`：v0.1 manager REST API、tenant boundary、runner claim 和 event/status authority。
- `docs/reference/spec-v01-agentrun-runner.md`：v0.1 短生命周期 runner、claim/poll/report、日志和 failureKind。
- `docs/reference/spec-v01-backend-adapter.md`：v0.1 backend adapter 合同、event normalization、failure mapping 和 redaction。
- `docs/reference/spec-v01-backend-codex.md`：v0.1 Codex app-server stdio backend、`codex`/`deepseek`/`minimax-m3` profile、`~/.codex` 测试凭据 Secret projection 和真实 turn 验收。
- `docs/reference/spec-v01-cli.md`：v0.1 AgentRun CLI 命令族、JSON 输出、短返回和日志可见。
- `docs/reference/spec-v01-scheduler.md`：v0.1 自动 scheduler 的 deferred 边界。
- `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。
- `docs/reference/cli.md`：CLI 与服务 API 辅助参考；`v0.1` CLI 权威以 `spec-v01-cli.md` 为准。