文档: 固化 AgentRun 中文规则
This commit is contained in:
Codex
@@ -1,39 +1,45 @@
|
||||
# AgentRun Agent Index
|
||||
# AgentRun Agent 索引
|
||||
|
||||
AgentRun is the shared agent execution infrastructure for UniDesk and HWLAB. This repository owns AgentRun architecture, API contracts, runner/backend behavior and runtime implementation. UniDesk only records how distributed development and deployment are coordinated from the UniDesk control center.
|
||||
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: The canonical source workspace is `G14:/root/agentrun`, fixed on branch `master`, with `origin git@github.com:pikasTech/agentrun.git`.
|
||||
- P0: Before development, deployment, resumed work or context recovery, run `tran G14:/root/agentrun script -- 'pwd; git status --short --branch; git remote -v'` from UniDesk and confirm the path, branch, remote and clean state.
|
||||
- P0: The fixed workspace is only for precheck, fetch, worktree management and final sync. Normal work must use `/root/agentrun/.worktree/{pr_branch}` created from latest `origin/master`.
|
||||
- P0: Do not use UniDesk, HWLAB, D601 workspaces, temporary clones, pod-local copies or runner checkouts as AgentRun source truth.
|
||||
- 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。
|
||||
|
||||
## Critical Runtime Target Rule
|
||||
|
||||
- P0: Default deployment targets are G14 native k3s namespaces `agentrun_dev` and `agentrun_prod`.
|
||||
- P0: Kubernetes operations must use UniDesk route syntax `G14:k3s`, for example `tran G14:k3s kubectl get pods -n agentrun_dev`.
|
||||
- P0: Do not create durable AgentRun exposure through ad hoc NodePort, host port, direct pod IP, one-off port-forward or provider-gateway business HTTP proxy. Public or cross-service access must be introduced through reviewed repository changes.
|
||||
- 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 暴露路径。公网或跨服务入口必须通过本仓库审查后的变更引入。
|
||||
|
||||
## Critical MVP Rule
|
||||
|
||||
- P0: AgentRun must be developed as a vertical MVP, not as a broad parallel service rewrite.
|
||||
- P0: First prove minimal `runner + one backend`; then add `agentrun-mgr` durable facts and manual runner startup; only after that add automatic scheduler.
|
||||
- P0: Existing UniDesk Code Queue and HWLAB Code Agent paths are not replaced by default. AgentRun starts as a new shared execution plane with canary integrations.
|
||||
- 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: The MVP uses short RESTful HTTP/JSON requests only. Do not add SSE, WebSocket, long-polling or long synchronous `turn` calls in the first phase.
|
||||
- P0: Long agent work must be represented by asynchronous resources: commands, runs, events, status and leases. Clients observe progress by paged polling.
|
||||
- P0: Runner inbound API should stay private and minimal. Clients should call `agentrun-mgr`; manually started runners must still claim and report through the manager.
|
||||
- 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 and service work must follow the UniDesk `cli-spec` principles: JSON output by default, no empty-success output, no long blocking CLI calls, visible logs, explicit config validation and RESTful service APIs for stable boundaries.
|
||||
- P0: Once a CLI is added, keep the entry small and move implementation into `scripts/src/`; long operations must return quickly and expose status/log/event polling.
|
||||
- P0: AgentRun CLI 和服务开发必须遵循 UniDesk `cli-spec` 原则：默认 JSON 输出、禁止空输出伪成功、禁止长阻塞 CLI、日志可见、配置显式校验、稳定跨服务边界优先使用 RESTful API。
|
||||
- P0: 一旦新增 CLI，入口文件必须保持轻量，具体实现拆入 `scripts/src/`；长任务必须快速返回，并提供 status/log/event 轮询。
|
||||
|
||||
## Reference Docs
|
||||
## 长期参考文档
|
||||
|
||||
- `docs/reference/architecture.md`: AgentRun product boundary, service architecture, MVP phases, RESTful API model and data model.
|
||||
- `docs/reference/cli.md`: CLI and service API conventions derived from `cli-spec`.
|
||||
- `TEST.md`: manual validation scenarios for the documented CLI/service behavior as it is implemented.
|
||||
- `docs/reference/architecture.md`：AgentRun 产品边界、服务架构、MVP 阶段、RESTful API 模型和数据模型。
|
||||
- `docs/reference/cli.md`：按 `cli-spec` 固化的 CLI 与服务 API 约束。
|
||||
- `TEST.md`：随实现逐步补齐的人工验收场景。
|
||||
|
||||
Reference in New Issue
Block a user