Files
pikasTech-HWLAB/docs/reference/agent-entrypoint.md
T
2026-06-22 08:27:43 +08:00

4.9 KiB
Raw Blame History

HWLAB Agent 入口拆分与低噪声索引

本文是 AGENTS.md 的详细长期参考,目标是让远端 AGENTS.md 保持短小、稳定、可快速读取,并把细节分散到 skill 与 docs/reference/

AGENTS.md 输出预算

  • AGENTS.md 是顶级索引,不是运行手册全文;远端读取不应触发 UniDesk CLI 默认 dump 阈值。
  • 如果 cat AGENTS.md、CLI 默认 help 或常用状态命令输出过大,必须先修可见性:拆分文档、压缩默认输出、提供表格摘要和 drill-down。
  • dump 只作为兜底保护,不是正常工作流;看到反复 dump 应改入口本身。
  • AGENTS.md 每条规则只保留一句话摘要和链接,不展开背景、历史、参数矩阵或完整命令教程。

内容归属

  • 项目级不可错过的 P0 规则保留在 AGENTS.md,但只保留摘要。
  • 稳定、可重复使用的工程规则写入 docs/reference/
  • 通用 CLI 用法、跨仓操作流程和工具细节写入对应 skill;AGENTS.md 和 reference 只交叉引用 skill,不复制完整说明。
  • 一次性排障、流水账、带日期过程记录和临时判断写入 GitHub issue 评论;只有沉淀成长期规则后才进入 docs/reference/
  • YAML/config 能表达的数值不写入 AGENTS.md 或长期文档作为第二真相;文档只说明“以 YAML/config 为准”和验证入口。

Skill 归属

  • hwlab-code-agentCode Agent provider profile、session、send、trace、result、inspect、Web 等价 CLI、auth 和 spawn/poll/result。
  • hwlab-caserunHWPOD CaseRun、case run、Keil 编译/下载/串口验证的无服务入口。
  • hwpod-opshwpod-node 启停、cloud-api 注册、多节点路由和节点运维。
  • dad-dev:跨节点 bug 修复、运行面最小实验、PR/rollout、原入口验收。
  • unidesk-cicdnode/lane CI/CD、Tekton/Argo、git mirror、trigger-current、control-plane status。
  • unidesk-ghGitHub issue/PR 创建、评论、preflight、merge、closeout。
  • unidesk-otelOTel/Tempo 查询、Code Agent/AgentRun trace 诊断和 instrumentation 可见性补强。
  • docs-specAGENTS.mddocs/reference/*.md 和过程文档蒸馏。

主要 reference 分工

Node/lane 入口规则

  • 当前 node/lane 必须来自 issue、PR、CLI 参数或受控配置;没有明确目标时才解析默认配置。
  • D601 v0.3 固定 workspace 是 /home/ubuntu/workspace/hwlab-v03,跟踪 origin/v0.3
  • D601 legacy 只指旧 DEV/CD、迁移对照和事故回放;D601 node-scoped runtime lane 不是 legacy。
  • G14 v0.2、G14 DEV/PROD 或其他 lane 只在当前任务明确选择时使用。
  • k3s 操作使用 UniDesk route,例如 D601:k3s;不要把 master server、本地 kubeconfig 或旧 Docker Desktop Kubernetes 当作目标运行面。

交付路径摘要

  • 文档、AGENTS.mddocs/reference、短连接 CLI/helper 等轻量治理变更可在当前 node/lane 固定主 worktree 直接提交并 push。
  • 业务代码、运行面、发布链路、Secret、权限、数据迁移、PROD 或重启服务等高风险变更走 PR,并按当前 node/lane base 分支提交。
  • CaseRun 和 runner 调试默认无服务;先拆单步验证,再决定是否跑完整编排。
  • 发布、git mirror、Tekton/Argo 和 runtime closeout 使用 UniDesk 受控 CLI;不要恢复旧 D601 JS CD 或裸 kubectl 写操作。

远端读取建议

  • 日常进入仓库先读短 AGENTS.md,再按任务类型打开对应 reference 或 skill。
  • 需要定位某条细则时优先 rg 具体关键词,而不是全量 cat 长文档。
  • reference 文档过长时继续按主题拆分,保持每个文档有明确职责。
  • 如果某个 reference 自身开始频繁触发 dump,应把通用操作迁入 skill,把项目特定规则留在 reference,并在文档顶部列出分流入口。