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 与 backendProfile=dsflash-go 都必须通过同一个 Codex CLI app-server stdio backend kind 执行，启动受控 codex app-server --listen stdio://，使用 JSON-RPC 方法 initialize、thread/start 或 thread/resume、turn/start；DeepSeek、MiniMax-M3 和 dsflash-go 都是 profile/config/SecretRef/model catalog 选择，不是直接 Responses HTTP 代理、独立 fake provider 或文本 fallback。
• P0: codex、deepseek、minimax-m3 与 dsflash-go profile 必须使用 profile-scoped SecretRef 和 writable CODEX_HOME，不得互相 fallback、复用运行态文件或污染默认 codex profile；dsflash-go 还必须携带 profile-scoped model-catalog.json；切换顺序必须可验证为 codex -> deepseek -> minimax-m3 -> dsflash-go -> 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-provider-profile-management.md：v0.1 provider profile 管理 API、HWLAB 委托信任边界、API Key 写入、Secret/config 更新和 canary 规格。
• docs/reference/spec-v01-runtime-assembly.md：v0.1 runner/backend 启动前的装配 SPEC，覆盖 BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef.kind="gitbundle"、bundles[]/promptRefs、gitbundle tools/skillDirs 装配和 tool credential SecretRef scope；旧 toolAliases / skillRefs / workspaceFiles 不再是有效装配入口。
• 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/dsflash-go profile、~/.codex 测试凭据 Secret projection、model catalog 和真实 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 为准。