lyon
65 lines
4.9 KiB
Markdown
65 lines
4.9 KiB
Markdown
# 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](commander-collaboration.md)：指挥官协作、工作区、分支、PR、自合并、prompt handoff 和审查护栏。
|
||
- [node-gitops-cicd.md](node-gitops-cicd.md)：node/lane GitOps CI/CD、受控发布入口、旧 CD 边界和公开入口规格链接。
|
||
- [dev-runtime-boundary.md](dev-runtime-boundary.md)：DEV/runtime、证据分级、SOURCE/LOCAL/DRY-RUN 与 DEV-LIVE 边界。
|
||
- [cloud-workbench.md](cloud-workbench.md)：Cloud Workbench 默认首页、UX 和诊断入口边界。
|
||
- [code-agent-chat-readiness.md](code-agent-chat-readiness.md)：Code Agent readiness、真实回复、provider blocker 与错误分类。
|
||
- [agentrun-code-agent-dispatch.md](agentrun-code-agent-dispatch.md)：AgentRun 调度、UniDesk SSH passthrough、GitHub tool credential 边界。
|
||
- [documentation-governance.md](documentation-governance.md)：文档治理、docs-spec 本地权威和历史文档迁移规则。
|
||
- [chinese-first-documentation.md](chinese-first-documentation.md)：中文优先规则。
|
||
- [user-feedback-triage.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，并在文档顶部列出分流入口。
|
||
|