4.9 KiB
4.9 KiB
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-agent:Code Agent provider profile、session、send、trace、result、inspect、Web 等价 CLI、auth 和 spawn/poll/result。hwlab-caserun:HWPOD CaseRun、case run、Keil 编译/下载/串口验证的无服务入口。hwpod-ops:hwpod-node 启停、cloud-api 注册、多节点路由和节点运维。dad-dev:跨节点 bug 修复、运行面最小实验、PR/rollout、原入口验收。unidesk-cicd:node/lane CI/CD、Tekton/Argo、git mirror、trigger-current、control-plane status。unidesk-gh:GitHub issue/PR 创建、评论、preflight、merge、closeout。unidesk-otel:OTel/Tempo 查询、Code Agent/AgentRun trace 诊断和 instrumentation 可见性补强。docs-spec:AGENTS.md、docs/reference/*.md和过程文档蒸馏。
主要 reference 分工
- commander-collaboration.md:指挥官协作、工作区、分支、PR、自合并、prompt handoff 和审查护栏。
- node-gitops-cicd.md:node/lane GitOps CI/CD、受控发布入口、旧 CD 边界和公开入口规格链接。
- dev-runtime-boundary.md:DEV/runtime、证据分级、SOURCE/LOCAL/DRY-RUN 与 DEV-LIVE 边界。
- cloud-workbench.md:Cloud Workbench 默认首页、UX 和诊断入口边界。
- code-agent-chat-readiness.md:Code Agent readiness、真实回复、provider blocker 与错误分类。
- agentrun-code-agent-dispatch.md:AgentRun 调度、UniDesk SSH passthrough、GitHub tool credential 边界。
- documentation-governance.md:文档治理、docs-spec 本地权威和历史文档迁移规则。
- chinese-first-documentation.md:中文优先规则。
- user-feedback-triage.md:用户反馈优先级和分流。
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.md、docs/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,并在文档顶部列出分流入口。