Codex
52 lines
4.5 KiB
Markdown
52 lines
4.5 KiB
Markdown
# 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: 外部英文资料只能作为引用或短摘录出现；落入本仓库的设计结论、验收标准和操作说明必须转写为中文。
|
||
|
||
## Critical Source Workspace Rule
|
||
|
||
- P0: `v0.1` 长期 source workspace 是 `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: 固定 workspace 只用于预检、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 和 HWLAB Code Agent 路径默认不被 AgentRun 替换。AgentRun 先作为新的共享执行面，通过 canary 集成逐步验证。
|
||
|
||
## 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。
|
||
- P0: 一旦新增 CLI，入口文件必须保持轻量，具体实现拆入 `scripts/src/`；长任务必须快速返回，并提供 status/log/event 轮询。
|
||
|
||
## 长期参考文档
|
||
|
||
- `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 分支、workspace、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 API Key 和运行时 Secret 分发规格。
|
||
- `docs/reference/spec-v01-validation.md`：v0.1 两层验证模型，自测试允许 mock，综合联调必须 100% 真实。
|
||
- `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。
|
||
- `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。
|