From 268b4588539d328c3298b11c5135fd289214bcf5 Mon Sep 17 00:00:00 2001 From: Codex Date: Sun, 14 Jun 2026 07:45:55 +0000 Subject: [PATCH] docs: refine unidesk oa planning skill --- .agents/skills/unidesk-oa/SKILL.md | 67 ++-- .agents/skills/unidesk-oa/agents/openai.yaml | 4 +- .../unidesk-oa/references/project-planning.md | 298 ++++++++++-------- .../skills/unidesk-oa/references/templates.md | 93 +++--- 4 files changed, 252 insertions(+), 210 deletions(-) diff --git a/.agents/skills/unidesk-oa/SKILL.md b/.agents/skills/unidesk-oa/SKILL.md index 311dd819..c43e4181 100644 --- a/.agents/skills/unidesk-oa/SKILL.md +++ b/.agents/skills/unidesk-oa/SKILL.md @@ -1,51 +1,52 @@ --- name: unidesk-oa -description: UniDesk/HWLabOA project-management operating skill. Use when the user mentions HWLabOA, OA docs, total project specification, master plan, major project/direction/topic/subtopic hierarchy, task book, implementation plan, testing specification, phase report, project drift, or GitHub issue trees for HWLAB Cloud M1 / UniDesk / AgentRun cross-repo project governance. +description: UniDesk/HWLabOA 项目管理运行技能。用户提到 HWLabOA、OA 文档、总项目规格、总规划、重大项目/方向/课题/子课题层级、任务书、实施方案、测试规格、阶段报告、项目偏离，或通过 GitHub issue 层级树管理 HWLAB Cloud M1 / UniDesk / AgentRun 跨仓项目治理时使用。 --- # UniDesk OA -Use this skill to keep HWLAB Cloud M1 project management centered on a stable master specification and a linked GitHub issue hierarchy. +使用本技能时，把 HWLAB Cloud M1 的项目管理稳定地锚定在总规格和相互链接的 GitHub issue 层级上。 -## Repositories +## 仓库 -- HWLabOA source of truth: `/root/HWLabOA` (`../HWLabOA` from `/root/unidesk`), remote `git@github.com:notLabyet/HWLabOA.git`, branch `main`. -- UniDesk control/tooling repo: `/root/unidesk`, remote `git@github.com:pikasTech/unidesk.git`, branch `master`. -- Before editing HWLabOA docs, run `git status --short --branch` and `git pull --ff-only origin main` in `/root/HWLabOA`. -- Before using UniDesk GitHub CLI or editing this skill, run `git status --short --branch` and `git pull --ff-only origin master` in `/root/unidesk`. +- HWLabOA 真相源：`/root/HWLabOA`（从 `/root/unidesk` 看是 `../HWLabOA`），远端为 `git@github.com:notLabyet/HWLabOA.git`，分支为 `main`。 +- UniDesk 控制/工具仓库：`/root/unidesk`，远端为 `git@github.com:pikasTech/unidesk.git`，分支为 `master`。 +- 修改 HWLabOA 文档前，必须在 `/root/HWLabOA` 执行 `git status --short --branch` 和 `git pull --ff-only origin main`。 +- 使用 UniDesk GitHub CLI 或修改本技能前，必须在 `/root/unidesk` 执行 `git status --short --branch` 和 `git pull --ff-only origin master`。 -## Operating Model +## 运行模型 -- Treat HWLabOA Markdown as the durable specification source of truth. -- Treat GitHub issues as the execution control plane: hierarchy, status, discussion, cross-repo references, PR linkage, and closeout evidence. -- Do not let daily reports become the master plan. Phase reports summarize movement against the master spec; they do not define the center by themselves. -- When a task lacks a parent direction, acceptance criteria, or original validation entry, classify it as planning/investigation before turning it into implementation work. -- L1 directions must be capability domains that directly serve the L0 mission. Do not classify document cleanup, phase reports, project-management mechanics, board maintenance, skill maintenance, repo names, tool names, or temporary execution paths as L1 directions. -- Treat L1 as acceptance ownership, not a loose topic tag. A cross-direction issue may list related L1s, but it must have exactly one primary L1 selected by asking which direction defines the done criteria. +- 将 HWLabOA Markdown 视为长期规格真相源。 +- 将 GitHub issue 视为执行控制面：层级、状态、讨论、跨仓引用、PR 链接和收口证据都在 issue 中流转。 +- 不要让日报或阶段报告成为总规划。阶段报告只总结相对总规格的移动，不能替代中心规划。 +- 当任务缺少上级方向、验收标准或原始验证入口时，先归类为规划/调查，不要直接变成实现任务。 +- L1 方向必须是直接服务 L0 使命的能力域。文档整理、阶段报告、项目管理机制、看板维护、技能维护、仓库名、工具名和临时执行路径都不能作为 L1 方向。 +- L1 是验收主责，不是宽泛标签。跨方向 issue 可以列关联 L1，但必须且只能有一个主责 L1，选择依据是哪个方向定义完成标准。 -## Canonical HWLAB Issue Anchors +## HWLAB 标准 issue 锚点 -- L0 master specification: `PJ2026-01`, `pikasTech/HWLAB#1194` (`HWLAB 总规格`). -- Long-term navigation board: `pikasTech/HWLAB#645` (`HWLAB 长期总面板`). This is a board, not the specification. -- Current Cloud M1 phase specification: `pikasTech/HWLAB#644` (`HWLAB Cloud SPEC / 云平台开发目标 20260601`). This is a phase spec, not an L1 direction. -- When creating or updating HWLAB project-management issues, link nontrivial L1/L2/L3/L4 work back to `#1194` and keep `#645` as a navigation index only. -- Use the HWLAB hierarchy code on all management issues and specs: project codes use `PJ-`: `PJ` means project, `2026` is the establishment year, HWLAB L0 is `PJ2026-01`; L1 codes are `PJ2026-0101`, `PJ2026-0102`, ...; L2 codes append two digits, e.g. `PJ2026-010102` means HWLAB L1 #01, L2 #02. Durable node short names should usually be no more than 8 Chinese characters; put explanations in descriptions, not names. +- L0 总规格：`PJ2026-01`，`pikasTech/HWLAB#1194`（`HWLAB 总规格`）。 +- 长期导航面板：`pikasTech/HWLAB#645`（`HWLAB 长期总面板`）。这是面板，不是规格书。 +- 当前 Cloud M1 阶段规格：`pikasTech/HWLAB#644`（`HWLAB Cloud SPEC / 云平台开发目标 20260601`）。这是阶段规格，不是 L1 方向。 +- 创建或更新 HWLAB 项目管理 issue 时，非平凡 L1/L2/L3/L4 工作都要链接回 `#1194`，并保持 `#645` 只作为导航索引。 +- 所有管理 issue 和规格都使用 HWLAB 层级编号：项目编号格式为 `PJ-`；`PJ` 表示项目，`2026` 是立项年份，HWLAB L0 是 `PJ2026-01`；L1 编号是 `PJ2026-0101`、`PJ2026-0102` 等；L2 继续追加两位，例如 `PJ2026-010102` 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题。稳定节点短名通常控制在 8 个中文汉字以内，解释写在正文，不写进名称。 -## Workflow +## 工作流 -1. For planning questions, read `references/project-planning.md`. -2. For creating or updating master specs or issue bodies, read `references/templates.md`. -3. When writing GitHub issues/PR comments, also use `unidesk-gh`; all writes must go through `bun scripts/cli.ts gh ...` from `/root/unidesk`. -4. When editing long-lived HWLabOA project docs, keep stable planning content in master/spec files and use phase-report docs only for dated summaries. +1. 做规划类问题时，读取 `references/project-planning.md`。 +2. 创建或更新总规格、issue 正文时，读取 `references/templates.md`。 +3. 写入 GitHub issue/PR 评论时，同时使用 `unidesk-gh`；所有写入必须从 `/root/unidesk` 通过 `bun scripts/cli.ts gh ...` 完成。 +4. 修改长期 HWLabOA 项目文档时，把稳定规划内容放到总规格/规格文件，阶段报告只保留带日期的总结。 +5. 修订 L1/L2 层级时，先按完成标准判断主责，再看实现表面。工具、CLI、Web、API 形态可以形成关联 L1，但主责 L1 必须是定义完成标准的能力域。 -## Required Hierarchy And Responsibility +## 必需层级和职责 -Use this task tree unless the user gives a stricter one: +除非用户给出更严格的层级，否则使用以下任务树： -- L0: Major project / master specification. Owns mission, non-goals, current center, L1 direction tree, global acceptance, and drift rules. -- L1: Direction. Owns a stable capability domain that serves L0, its scope boundary, success criteria, L2 topic list, and acceptance-definition authority for child work. -- L2: Topic. Owns a concrete program of work inside one L1 direction, including deliverables, blockers, and validation plan. -- L3: Subtopic / validation slice. Owns one bounded acceptance path, such as one CaseRun line, Web check, CLI smoke, or deployment/control-plane validation. -- L4: Execution task / PR / CaseRun / smoke / doc closeout. Owns concrete execution and evidence collection; it cannot redefine parent scope. +- L0：重大项目 / 总规格。负责使命、非目标、当前中心、L1 方向树、全局验收和偏离规则。 +- L1：方向。负责一个稳定能力域、范围边界、成功标准、L2 课题清单和子工作验收定义权。 +- L2：课题。负责某个 L1 内的具体工作计划，包括交付物、阻塞项和验证计划。 +- L3：子课题 / 验收切片。负责一个有界验收路径，例如一条 CaseRun 线、Web 检查、CLI smoke 或部署/控制面验证。 +- L4：执行任务 / PR / CaseRun / smoke / 文档收口。负责具体执行和证据收集，不能重新定义父级范围。 -Every non-trivial issue should state its parent links, target branch/lane, acceptance criteria, validation entry, and closeout writeback target. +每个非平凡 issue 都应写明上级链接、目标分支/lane、验收标准、验证入口和收口回写目标。 diff --git a/.agents/skills/unidesk-oa/agents/openai.yaml b/.agents/skills/unidesk-oa/agents/openai.yaml index a7e9ec40..6803d3c9 100644 --- a/.agents/skills/unidesk-oa/agents/openai.yaml +++ b/.agents/skills/unidesk-oa/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "UniDesk OA" - short_description: "Manage HWLabOA master specs and issue hierarchies." - default_prompt: "Use this skill to plan HWLabOA project structure, master specifications, and linked GitHub issue trees." + short_description: "管理 HWLabOA 总规格和 issue 层级。" + default_prompt: "使用本技能规划 HWLabOA 项目结构、总规格和相互链接的 GitHub issue 层级树。" diff --git a/.agents/skills/unidesk-oa/references/project-planning.md b/.agents/skills/unidesk-oa/references/project-planning.md index d684fd33..cd0c486f 100644 --- a/.agents/skills/unidesk-oa/references/project-planning.md +++ b/.agents/skills/unidesk-oa/references/project-planning.md @@ -1,192 +1,230 @@ -# UniDesk OA Project Planning +# UniDesk OA 项目规划 -## Purpose +## 目的 -HWLAB Cloud M1 needs a project control structure that prevents local issue/PR work from drifting away from the center. Use a research-project style hierarchy: +HWLAB Cloud M1 需要一个项目控制结构，避免局部 issue/PR 工作偏离中心。使用接近科研项目的层级： -- Major project: overall mission, product goal, delivery boundary (`PJ2026-01` for HWLAB). -- Direction: stable capability domain under the major project that directly serves the L0 mission (`PJ2026-0101`, `PJ2026-0102`, ...). -- Topic: concrete program of work inside a direction (`PJ2026-010102` means HWLAB L1 #01 / L2 #02). -- Subtopic: bounded validation slice with explicit acceptance criteria, appending another two digits. -- Execution task: issue, PR, CaseRun, smoke, deployment, or document closeout, appending another two digits when it needs a persistent management code. +- 重大项目：总体使命、产品目标、交付边界，例如 HWLAB 的 `PJ2026-01`。 +- 方向：重大项目下的稳定能力域，直接服务 L0 使命，例如 `PJ2026-0101`、`PJ2026-0102`。 +- 课题：某个方向内的具体工作计划，例如 `PJ2026-010102` 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题。 +- 子课题：具有明确验收标准的有界验证切片，继续追加两位编号。 +- 执行任务：issue、PR、CaseRun、smoke、部署或文档收口；需要长期管理编号时继续追加两位。 -## Document And Issue Split +## 文档和 issue 分工 -Use documents for durable truth: +用文档承载长期真相： -- Master specification. -- Direction implementation plans. -- Test/validation specifications. -- Decision rationale. -- Stable acceptance criteria. +- 总规格。 +- 方向实施方案。 +- 测试/验收规格。 +- 决策依据。 +- 稳定验收标准。 -Use issues for execution state: +用 issue 承载执行状态： -- Current owner/status. -- Discussion and evidence. -- Cross-repo references. -- PR and commit linkage. -- Runtime trace/session/job IDs. -- Closeout comments. +- 当前负责人和状态。 +- 讨论和证据。 +- 跨仓引用。 +- PR 和 commit 链接。 +- 运行 trace、session、job ID。 +- 收口评论。 -Do not store the only copy of a stable requirement in an issue comment. If the requirement is long-lived, distill it into HWLabOA and link it from the issue. +不要把稳定需求的唯一副本放在 issue 评论里。长期有效的需求必须蒸馏到 HWLabOA，再从 issue 链接过去。 -## Current HWLAB Issue Anchors +## 当前 HWLAB issue 锚点 -- L0 master specification: `PJ2026-01`, `pikasTech/HWLAB#1194` (`HWLAB 总规格`). -- Long-term board/navigation: `pikasTech/HWLAB#645` (`HWLAB 长期总面板`). Do not treat this as the specification. -- Cloud M1 phase specification: `pikasTech/HWLAB#644` (`HWLAB Cloud SPEC / 云平台开发目标 20260601`). This is a phase spec, not an L1 direction. -- New or updated direction/topic/execution issues should include `上级总项目: #1194` unless the user explicitly scopes the task outside HWLAB Cloud M1. +- L0 总规格：`PJ2026-01`，`pikasTech/HWLAB#1194`（`HWLAB 总规格`）。 +- 长期面板/导航：`pikasTech/HWLAB#645`（`HWLAB 长期总面板`）。不要把它当成规格书。 +- Cloud M1 阶段规格：`pikasTech/HWLAB#644`（`HWLAB Cloud SPEC / 云平台开发目标 20260601`）。这是阶段规格，不是 L1 方向。 +- 新建或更新方向/课题/执行 issue 时，除非用户明确限定在 HWLAB Cloud M1 之外，否则正文应包含 `上级总项目: #1194`。 -## Numbering Rule +## 编号规则 -- HWLAB L0 project code is `PJ2026-01`: `PJ` means project, `2026` is the establishment year, and `01` is the HWLAB L0 sequence. -- L1 direction codes are `PJ2026-0101`, `PJ2026-0102`, `PJ2026-0103`, ... -- L2 topic codes append the L2 two-digit sequence after the L1 code payload: `PJ2026-010101`, `PJ2026-010102`, `PJ2026-010201`, ... -- L3/L4 persistent management codes continue appending two digits per level, e.g. `PJ2026-01010203` = HWLAB L1 #01 / L2 #02 / L3 #03. -- Do not renumber existing codes just because priorities change. Add new suffixes for new durable nodes; execution-only PRs or one-off smokes may reference the nearest persistent code instead of receiving their own code. -- Durable node short names should usually be no more than 8 Chinese characters. Issue titles should start with the code and short name, e.g. `PJ2026-010102 频源造模`; put detailed explanations in the body. +- HWLAB L0 项目编号是 `PJ2026-01`：`PJ` 表示项目，`2026` 是立项年份，`01` 是 HWLAB L0 序号。 +- L1 方向编号为 `PJ2026-0101`、`PJ2026-0102`、`PJ2026-0103` 等。 +- L2 课题编号在 L1 编号后继续追加两位，例如 `PJ2026-010101`、`PJ2026-010102`、`PJ2026-010201`。 +- L3/L4 长期管理编号继续每级追加两位，例如 `PJ2026-01010203` 表示 HWLAB L1 #01 / L2 #02 / L3 #03。 +- 不要因为优先级变化而重编号。新稳定节点追加新后缀；执行型 PR 或一次性 smoke 可以引用最近的稳定编号，不一定单独编号。 +- 稳定节点短名通常不超过 8 个中文汉字。issue 标题应以编号和短名开头，例如 `PJ2026-010102 频源造模`；详细解释写在正文。 -## Suggested HWLabOA Structure +## 建议的 HWLabOA 结构 -For HWLAB Cloud M1, keep the durable docs under: +HWLAB Cloud M1 的长期文档放在： ```text /root/HWLabOA/Project Management/[EPIC001][HWLab][PRJ002][CLOUD-M1]/ ``` -Recommended files: +推荐文件： ```text -SPEC-CLOUD-M1-MASTER.md # L0 master specification and issue tree index -SPEC-CLOUD-M1.md # Existing dated/phase material, can link to master -PLAN-CLOUD-M1-DIRECTIONS.md # L1 direction implementation plans, optional -TEST-CLOUD-M1-VALIDATION.md # Cross-direction validation matrix, optional +SPEC-CLOUD-M1-MASTER.md # L0 总规格和 issue 层级树索引 +SPEC-CLOUD-M1.md # 既有阶段材料，可以链接到 master 文件 +PLAN-CLOUD-M1-DIRECTIONS.md # L1 方向实施方案，可选 +TEST-CLOUD-M1-VALIDATION.md # 跨方向验收矩阵，可选 ``` -Prefer one master file first. Split only when the master becomes too large or when a section has independent lifecycle and review needs. +优先维护一个 master 文件。只有当 master 文件过大，或某个部分具有独立生命周期和评审需要时才拆分。 -## L0-L4 Rules +## L0-L4 规则 -### Responsibility Boundaries +### 职责边界 -Use the hierarchy as a responsibility split, not only a numbering scheme: +使用层级做职责拆分，而不只是编号： -| Level | Owns | Does not own | Writes back to | +| 层级 | 负责 | 不负责 | 回写到 | | --- | --- | --- | --- | -| L0 | Mission, non-goals, current center, L1 direction tree, global acceptance, drift rules | PR details, CaseRun logs, daily status, implementation design | HWLabOA master spec and L1 issues | -| L1 | Capability-domain scope, success criteria, L2 topic list, original validation class | Single PRs, one-off smokes, repository/tool/runtime names, project-management mechanics | L0 issue and HWLabOA when direction scope changes | -| L2 | Concrete program of work inside one L1, deliverables, blockers, validation plan | Broad capability domains or implementation minutiae | L1 issue, then L0 for material movement | -| L3 | Bounded validation slice with one acceptance path | Roadmaps, multi-topic programs, parent-scope changes | L2/L1 issue with evidence | -| L4 | Concrete execution: PR, CaseRun, smoke, deployment, doc closeout | New requirements, new direction scope, acceptance-rule changes | Nearest L3/L2/L1 with original-entry evidence | +| L0 | 使命、非目标、当前中心、L1 方向树、全局验收、偏离规则 | PR 细节、CaseRun 日志、日报流水、实现设计 | HWLabOA 总规格和 L1 issue | +| L1 | 能力域范围、成功标准、L2 课题清单、原始验收类型 | 单个 PR、一次性 smoke、仓库/工具/运行面名称、项目管理动作 | L0 issue 和 HWLabOA | +| L2 | 一个 L1 内的具体课题、交付物、阻塞项、验证计划 | 宽泛能力域或实现细节流水 | L1 issue，重大移动再回写 L0 | +| L3 | 一个有界验收切片和单一验收路径 | 路线图、多课题计划、父级范围变化 | L2/L1 issue 并带证据 | +| L4 | 具体执行：PR、CaseRun、smoke、部署、文档收口 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1，并带原入口证据 | -Classification rule: +分类规则： -- If it changes mission, current center, L1 list, or global acceptance, it belongs to L0. -- If it defines a durable capability domain that can contain multiple topics, it belongs to L1. -- If it plans a concrete program of work inside one direction, it belongs to L2. -- If it can be validated through one bounded path, it belongs to L3. -- If it is one PR, one CaseRun, one smoke, one deployment, or one document closeout, it belongs to L4. +- 改变使命、当前中心、L1 列表或全局验收的，属于 L0。 +- 定义可以容纳多个课题的稳定能力域的，属于 L1。 +- 在一个方向内规划具体工作计划的，属于 L2。 +- 可以通过一个有界路径验收的，属于 L3。 +- 一个 PR、一个 CaseRun、一次 smoke、一次部署或一次文档收口，属于 L4。 -### L0 Major Project +### L0 重大项目 -The L0 item defines: +L0 定义： -- Mission and non-goals. -- Current center of gravity. -- Product surfaces. -- Direction list. -- Global acceptance criteria. -- Cross-repo source truth. -- Issue hierarchy index. -- Drift indicators. +- 使命和非目标。 +- 当前工作重心。 +- 产品入口。 +- 方向列表。 +- 全局验收标准。 +- 跨仓真相源。 +- issue 层级索引。 +- 偏离指标。 -There should normally be one L0 GitHub issue and one L0 master spec document. For HWLAB, the canonical L0 code is `PJ2026-01` and the canonical L0 issue is `pikasTech/HWLAB#1194`; `#645` remains only the long-term board/navigation entry. +通常应该有一个 L0 GitHub issue 和一个 L0 总规格文档。对 HWLAB 来说，标准 L0 编号是 `PJ2026-01`，标准 L0 issue 是 `pikasTech/HWLAB#1194`；`#645` 只作为长期面板/导航入口。 -### L1 Direction +### L1 方向 -L1 directions are the top-level capability domains that directly serve the L0 mission. They are not project-management artifacts. +L1 方向是直接服务 L0 使命的顶层能力域，不是项目管理工件。 -Each direction must answer: +每个方向必须回答： -- Which part of the L0 goal it serves. -- What completion means. -- Which repos/branches/lanes are involved. -- Which original user/runtime entry validates it. -- Which L2 topics currently matter. +- 它服务 L0 目标的哪一部分。 +- 什么状态算完成。 +- 涉及哪些仓库、分支、lane。 +- 哪个原始用户/运行面入口可以验收它。 +- 当前重要的 L2 课题有哪些。 -Do not use any of these as L1 directions: +以下内容不能作为 L1 方向： -- Document cleanup, stage reports, or issue/body maintenance. -- Project-management mechanics, board maintenance, skill maintenance, or OA process work. -- Repository names, tool names, CLI names, service names, runtime lanes, or temporary execution paths. -- A single PR, one CaseRun, one smoke, one bug, or one migration step. +- 文档整理、阶段报告、issue/body 维护。 +- 项目管理机制、看板维护、技能维护或 OA 流程工作。 +- 仓库名、工具名、CLI 名、服务名、运行面 lane 或临时执行路径。 +- 单个 PR、一个 CaseRun、一次 smoke、一个 bug 或一个迁移步骤。 -Primary L1 rule: +主责 L1 规则： -- L1 is acceptance ownership, not a loose tag. Every non-trivial L2/L3/L4 issue must name exactly one primary L1. -- Related L1s may be listed for handoff, but the primary L1 is the direction that defines the done criteria. -- If ownership is unclear, ask which completion evidence would close the issue: hardware resource readiness, Agent execution lifecycle, Harness/RL evidence, client/API behavior, user/admin policy, or platform delivery/operations. +- L1 是验收主责，不是宽泛标签。每个非平凡 L2/L3/L4 issue 必须且只能有一个主责 L1。 +- 可以列相关 L1 做交接，但主责 L1 是定义完成标准的方向。 +- 主责不清楚时，问“什么证据能关闭这个 issue”：硬件资源就绪、Agent 执行生命周期、Harness/RL 证据、客户端/API 行为、用户/管理策略，还是平台交付/运维。 +- 先按完成标准判断主责，再看实现表面。CLI、Web 页面、SDK、API、hwpod 工具或服务路由不会自动归入 `客户端`；它们主归属定义正确性的领域。只有当完成标准是多客户端入口行为、用户交互、兼容性、输出格式或公开 API/SDK 体验时，`客户端` 才是主责 L1。 -Typical HWLAB Cloud M1 L1 responsibility matrix: +HWLAB Cloud M1 当前 L1 职责矩阵： -| Code | Short name | Primary responsibility | Does not own | Handoff examples | +| 编号 | 短名 | 主责 | 不负责 | 交接示例 | | --- | --- | --- | --- | --- | -| `PJ2026-0101` | 硬件池 | Hardware resource pool: boards, probes, HWPOD nodes, device registration, occupancy, health, availability | CaseRun pass/fail criteria, Agent scheduling, UI/API presentation, CI/CD | Harness evidence to HarnessRL; resource allocation hooks to Agent编排 | -| `PJ2026-0102` | Agent编排 | Agent execution lifecycle: Code Agent, AgentRun, workspace, sessions, provider profiles, task recovery | Hardware inventory, Harness scoring, client UX/API contracts, CI/CD | Device allocation to 硬件池; evidence to HarnessRL; client status to 客户端 | -| `PJ2026-0103` | HarnessRL | Harness/RL loop: harness, CaseRun, ioProbe, evidence, evaluation, replay, training feedback, RL closure | Hardware capacity, Agent scheduling, user accounts, rollout pipelines | Device facts from 硬件池; run lifecycle from Agent编排 | -| `PJ2026-0104` | 客户端 | User entry surfaces: Web, CLI, HTTP API, SDK/IDE plugin, webhook, public docs, compatibility | User/billing truth, Agent scheduling internals, hardware inventory, CI/CD | Auth/account policy to 用户管理; runtime status to Agent编排 | -| `PJ2026-0105` | 用户管理 | User and admin domain: accounts, registration/login, permissions, API keys, credit, usage, billing, admin, tenant isolation | Client UX, Agent execution, hardware evidence, deployment mechanics | User-facing flows to 客户端; usage sources from Agent编排/HarnessRL | -| `PJ2026-0106` | 平台运维 | Platform delivery and operations: CI/CD, git mirror, YAML-first, Secret sync, rollout, observability, GC, platform release | Product behavior, user policy, Agent semantics, hardware validation criteria | Deployment needs from all L1s; health signals back to owners | +| `PJ2026-0101` | 硬件池 | 硬件资源池：板卡、probe、HWPOD 节点、设备注册、占用、健康、可用性 | CaseRun pass/fail 标准、Agent 调度、UI/API 展示、CI/CD | 把 Harness 证据交给 HarnessRL；把资源分配 hook 交给 Agent编排 | +| `PJ2026-0102` | Agent编排 | Agent 执行生命周期：Code Agent、AgentRun、工作区、session、provider profile、任务恢复 | 硬件 inventory、Harness 评分、客户端 UX/API 契约、CI/CD | 从 硬件池 获取设备分配；向 HarnessRL 提供证据；向 客户端 提供状态 | +| `PJ2026-0103` | HarnessRL | Harness/RL 闭环：harness、CaseRun、ioProbe、证据、evaluation、replay、训练反馈、RL 收敛 | 硬件容量、Agent 调度、用户账户、rollout pipeline | 从 硬件池 获取设备事实；从 Agent编排 获取运行生命周期 | +| `PJ2026-0104` | 客户端 | 用户入口：Web、CLI、HTTP API、SDK/IDE plugin、webhook、公开文档、兼容性 | 用户/账本真相、Agent 调度内部、硬件 inventory、CI/CD | 向 用户管理 交接 auth/account 策略；从 Agent编排 获取运行状态 | +| `PJ2026-0105` | 用户管理 | 用户和管理域：账户、注册/登录、权限、API key、credit、usage、billing、admin、tenant isolation | 客户端 UX、Agent 执行、硬件证据、部署机制 | 把用户入口交给 客户端；从 Agent编排/HarnessRL 获取 usage 来源 | +| `PJ2026-0106` | 平台运维 | 平台交付和运维：CI/CD、git mirror、YAML-first、Secret sync、rollout、observability、GC、platform release | 产品行为、用户策略、Agent 语义、硬件验收标准 | 承接所有 L1 的部署需求；把健康信号回传给负责人 | -### L2 Topic +### L2 课题 -Topics should be concrete enough to plan and close: +课题必须足够具体，可以规划和关闭。例如： -- PLC 71-FREQ CaseRun production loop. -- ARM2D upstream integration. -- D601 v0.3 user-billing and usage summary. -- React to Vue parity closeout. -- Sub2API Codex pool failover stability. +- PLC 71-FREQ CaseRun 生产闭环。 +- ARM2D 上游集成。 +- D601 v0.3 用户账单和使用摘要。 +- React 到 Vue 对齐收口。 +- Sub2API Codex pool failover 稳定性。 -### L3 Subtopic +制定 L2 时： -Subtopics are validation slices. They must define a single acceptance path: +- 从 L1 完成标准出发，再把工作聚合成有交付物和验证计划的稳定课题。 +- 不要只按仓库、CLI 命令、UI 页面、实现模块或临时运行面 lane 拆 L2。 +- L2 短名通常控制在 8 个中文汉字以内。优先使用能力名；只有当标准/协议本身是交付物并约束后续实现时，才用“标准”类名称。 +- 安全、诊断、占用、日志默认合并到拥有相关行为的 L2；除非它们本身成为中心交付物，否则不要单列。 +- 一个课题触及多个 L1 时，仍保留一个主责 L1，并列出关联 L1。用交叉引用表达支撑关系，不要在多个方向下重复建同一棵 issue 层级树。 -- A CaseRun with expected artifact. -- A CLI smoke with target lane. -- A Web original-entry check. -- A deployment/control-plane action with status evidence. -- A document decision with linked references. +### 硬件池 L2 标准 -### L4 Execution Task +`PJ2026-0101 硬件池` 当前 L2 拆分为： -Execution tasks map to one PR, one runtime validation, one CaseRun, or one closeout document update. They should not become mini-epics. +| 编号 | 短名 | 主责 | 关联 L1 | 边界 | +| --- | --- | --- | --- | --- | +| `PJ2026-010101` | `HWPOD标准` | 定义 HWPOD-SPEC、硬件资源身份、能力模型、AI 网关接入标准、操作能力标准、状态/错误语义和验收基线。 | 客户端、HarnessRL、Agent编排 | 这是标准/协议型交付，不是单纯文档。它定义 HWPOD 资源和 AI 网关能力声明的正确性规则。 | +| `PJ2026-010102` | `HWPOD工具` | 实现硬件池领域工具侧，包括 `hwpod-ctl`、HWPOD-SPEC 新建/修改/校验，以及 compile、download、filesystem、IO 等操作入口。 | 客户端 | 这不是通用 `客户端` L1。只要完成标准由 HWPOD 语义或真实硬件执行定义，就主归属硬件池。通用 CLI 登录、profile 体验、公开 API 体验、SDK 对齐和多客户端一致性归 `客户端`。 | +| `PJ2026-010103` | `HWPOD服务` | 实现服务端 HWPOD 注册、管理、状态、必要的权限/租约、请求接收、路由、结果归档，并把工具侧请求转发到 AI 网关节点。 | 用户管理、Agent编排、平台运维 | 它负责 HWPOD 服务端语义，不负责全局部署机制、用户策略或 Agent 任务调度。 | +| `PJ2026-010104` | `AI网关` | 实现连接真实硬件到服务端的节点侧能力，包括 PC 客户端形态、硬件网关盒子形态、心跳、命令执行、日志/artifact/IO 结果回传和适配器执行。 | HarnessRL、Agent编排、平台运维 | debug probe、UART、board-comm、ioProbe、电压/电流/频率/CANopen 等适配器是网关侧能力切片，通常作为本 L2 下的 L3，除非发展成更大的工作计划。 | -## Drift Controls +硬件池已吸收概念： -Flag a task as drift-risk when: +- `资源模型` 并入 `HWPOD标准`；标准同时定义资源模型和网关能力模型。 +- `资源占用` 通常并入 `HWPOD服务`，当它涉及租约、权限、路由状态；涉及用户可见操作请求时也会落到 `HWPOD工具`。 +- `安全状态` 是 `HWPOD服务` 和 `AI网关` 的横向验收要求；除非安全态恢复本身成为中心课题，否则不要单列 L2。 +- `运行诊断` 分散到行为负责人：规格不一致归 `HWPOD标准`，命令/API 诊断归 `HWPOD工具`，路由/状态诊断归 `HWPOD服务`，node/probe/IO 执行诊断归 `AI网关`。 +- debug/download/IO/观测通道默认不单列 L2。把它们视为 `AI网关` 下的能力切片，以及 `HWPOD工具` 侧的操作入口。 -- It has no L1/L2 parent. -- It treats documentation, project management, board maintenance, or skill maintenance as the parent direction. -- It improves tooling but does not remove a named blocker. -- It changes a runtime/control plane without an original validation entry. -- It expands frontend parity without tying back to Code Agent/HWPOD/user workflow. -- It improves observability but no downstream decision depends on the new signal. -- It keeps ARM2D/PLC evidence polishing without a new real upstream or board-facing case. +硬件池跨 L1 示例： -When drift-risk is found, either attach it to a parent and acceptance criterion, or reclassify it as investigation. +| 工作项 | 主责 L1 | 关联 L1 | 理由 | +| --- | --- | --- | --- | +| 增加 `hwpod-ctl spec validate` 校验 HWPOD-SPEC 正确性 | 硬件池 | 客户端 | 完成标准是 HWPOD 标准正确性，即使表面是 CLI。 | +| 统一所有 HWLAB CLI 的 JSON 输出 schema | 客户端 | 硬件池 | 完成标准是多客户端/用户入口一致性。 | +| 在 Web/API 展示 HWPOD inventory | 客户端 | 硬件池 | 用户入口行为是主责，HWPOD 语义从硬件池引用。 | +| 修复 probe mismatch 被报告为成功 | 硬件池 | HarnessRL | 真实硬件执行/错误语义是主责，HarnessRL 消费结果。 | +| 给 AgentRun 任务分配 HWPOD 资源 | 硬件池 或 Agent编排 | Agent编排 或 硬件池 | 如果完成标准是资源分配正确性，主责硬件池；如果完成标准是任务生命周期调度，主责 Agent编排。 | -## Phase Report Rule +### L3 子课题 -Every phase report should include: +子课题是验证切片。必须定义单一验收路径： -- Time window and timezone. -- Source scope: repos/issues/PRs checked. -- Movement against L0/L1 goals. -- Completed validation evidence. -- Open blockers. -- Drift assessment. -- Next validation-oriented target. +- 一个带预期 artifact 的 CaseRun。 +- 一个指定目标 lane 的 CLI smoke。 +- 一个 Web 原入口检查。 +- 一个带状态证据的部署/控制面动作。 +- 一个带引用的文档决策。 -Avoid reporting issue volume as progress. Report only changes that move a direction toward its acceptance criteria. +### L4 执行任务 + +执行任务对应一个 PR、一次运行面验证、一个 CaseRun 或一次收口文档更新。它不应该变成 mini-epic。 + +## 偏离控制 + +出现以下情况时，将任务标记为偏离风险： + +- 没有 L1/L2 上级。 +- 把文档、项目管理、看板维护或技能维护当作父方向。 +- 改进工具但没有移除具名阻塞项。 +- 改变运行面/控制面但没有原始验证入口。 +- 扩展前端对齐但没有绑定到 Code Agent/HWPOD/用户工作流。 +- 改善可观测性但没有下游决策依赖新信号。 +- 持续打磨 ARM2D/PLC 证据，但没有新的真实上游或板级用例。 + +发现偏离风险后，要么挂回上级和验收标准，要么重新归类为调查。 + +## 阶段报告规则 + +每份阶段报告应包含： + +- 时间窗口和时区。 +- 来源范围：核对过的 repo、issue、PR。 +- 相对 L0/L1 目标的移动。 +- 已完成的验证证据。 +- 开放阻塞项。 +- 偏离评估。 +- 下一阶段面向验证的目标。 + +避免把 issue 数量当成进展。只报告真正推动方向接近验收标准的变化。 diff --git a/.agents/skills/unidesk-oa/references/templates.md b/.agents/skills/unidesk-oa/references/templates.md index 586d0032..86a1ca9c 100644 --- a/.agents/skills/unidesk-oa/references/templates.md +++ b/.agents/skills/unidesk-oa/references/templates.md @@ -1,30 +1,30 @@ -# UniDesk OA Templates +# UniDesk OA 模板 -## L0 Master Specification Skeleton +## L0 总规格骨架 ```markdown -# HWLAB Master Specification +# HWLAB 总规格 编号: PJ2026-01 短名: HWLAB -## 1. Mission +## 1. 项目使命 -One paragraph describing the product and research objective. +用一段话描述产品目标和科研目标。 -## 2. Non-Goals +## 2. 非目标 - ... -## 3. Current Center +## 3. 当前中心 -- Current primary validation line: -- Secondary validation line: -- Explicitly paused/deferred line: +- 当前主验证线: +- 次级验证线: +- 明确暂停/后置的线: -## 4. Direction Tree +## 4. 方向树 -| Level | Title | GitHub issue | Spec section | Current status | +| 层级 | 标题 | GitHub issue | 规格章节 | 当前状态 | | --- | --- | --- | --- | --- | | L1 | PJ2026-0101 硬件池 | TBD | ... | ... | | L1 | PJ2026-0102 Agent编排 | TBD | ... | ... | @@ -33,38 +33,38 @@ One paragraph describing the product and research objective. | L1 | PJ2026-0105 用户管理 | TBD | ... | ... | | L1 | PJ2026-0106 平台运维 | TBD | ... | ... | -## 5. Global Acceptance Criteria +## 5. 全局验收标准 - ... -## 6. Direction Details +## 6. 方向详情 -### L1: Embedded cloud-development loop +### L1: <方向短名> -- Goal: -- Non-goal: -- Current topics: -- Acceptance criteria: -- Validation entries: -- Open blockers: +- 目标: +- 非目标: +- 当前课题: +- 验收标准: +- 验证入口: +- 开放阻塞: -## 7. Issue Hierarchy Index +## 7. issue 层级索引 - L0: - L1: - L2: - L3/L4: -## 8. Drift Rules +## 8. 偏离规则 - ... -## 9. Phase Report Links +## 9. 阶段报告链接 - ... ``` -## L0 Issue Body +## L0 issue 正文 ```markdown 目标合并分支: 不适用 @@ -74,7 +74,7 @@ One paragraph describing the product and research objective. 短名: HWLAB 上级面板: #645 当前 L0 总规格: #1194 -总规格文档: +总规格文档: ## 项目中心 @@ -84,11 +84,14 @@ One paragraph describing the product and research objective. ## L1 方向 -- [ ] PJ2026-0101 #... 方向A: -- [ ] PJ2026-0102 #... 方向B: -- [ ] PJ2026-0103 #... 方向C: +- [ ] PJ2026-0101 #... 硬件池: +- [ ] PJ2026-0102 #... Agent编排: +- [ ] PJ2026-0103 #... HarnessRL: +- [ ] PJ2026-0104 #... 客户端: +- [ ] PJ2026-0105 #... 用户管理: +- [ ] PJ2026-0106 #... 平台运维: -方向判定: L1 必须是直接服务 L0 的能力域；文档整理、项目管理、看板维护、skill 维护、仓库名、工具名和临时执行路径不得作为 L1。 +方向判定: L1 必须是直接服务 L0 的能力域；文档整理、项目管理、看板维护、技能维护、仓库名、工具名和临时执行路径不得作为 L1。 编号规则: 项目编号格式为 PJ<立项年份>-<层级路径>；PJ 表示项目，HWLAB L0 为 PJ2026-01；L1 为 PJ2026-0101；L2 继续追加两位，例如 PJ2026-010102 表示 HWLAB L1 第 1 个方向下的第 2 个 L2 课题；更深层级继续每级追加两位。短名一般控制在 8 个中文汉字以内，解释写入正文说明。 @@ -97,10 +100,10 @@ One paragraph describing the product and research objective. | 层级 | 负责定义 | 不负责 | 回写对象 | | --- | --- | --- | --- | | L0 | 项目使命、当前中心、L1 方向树、全局验收、偏离规则 | PR 细节、CaseRun 日志、日报流水 | HWLabOA 总规格、L1 issue | -| L1 | 能力域范围、成功标准、L2 课题清单、原入口验收类型 | 单个 PR、一次 smoke、仓库/工具/runtime 名称、项目管理动作 | L0 issue、HWLabOA | +| L1 | 能力域范围、成功标准、L2 课题清单、原入口验收类型 | 单个 PR、一次 smoke、仓库/工具/运行面名称、项目管理动作 | L0 issue、HWLabOA | | L2 | 单个方向内的具体课题、交付物、阻塞、验收计划 | 总方向定义、实现细节流水 | L1 issue，重大移动再回写 L0 | | L3 | 一个有界验收切片和单一验收路径 | 路线图、跨课题计划、父级范围变化 | L2/L1 issue | -| L4 | PR、CaseRun、smoke、部署、文档收口等执行和 evidence | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1 | +| L4 | PR、CaseRun、smoke、部署、文档收口等执行和证据 | 新需求、新方向、验收规则变化 | 最近的 L3/L2/L1 | ## 全局验收 @@ -118,16 +121,16 @@ One paragraph describing the product and research objective. - L1 阶段完成时必须回写本 issue，并更新 HWLabOA 总规格。 ``` -## L1 Direction Issue Body +## L1 方向 issue 正文 ```markdown 目标合并分支: 不适用 -原因: 本 issue 是方向级项目管理锚点，代码变更由下级 topic/subtopic issue 承载。 +原因: 本 issue 是方向级项目管理锚点，代码变更由下级课题/子课题 issue 承载。 编号: PJ2026-010N 短名: <8字以内> 上级总项目: #1194 -总规格文档: +总规格文档: ## 主责边界 @@ -148,8 +151,8 @@ One paragraph describing the product and research objective. ## 边界 -- In scope: -- Out of scope: +- 范围内: +- 范围外: ## L2 课题 @@ -158,8 +161,8 @@ One paragraph describing the product and research objective. ## 验收标准 - 原入口: -- Runtime/lane: -- Evidence: +- 运行入口/lane: +- 证据: ## 当前阻塞 @@ -171,10 +174,10 @@ One paragraph describing the product and research objective. - 方向状态变化后更新 L0 issue 和 HWLabOA 总规格。 ``` -## L2/L3 Execution Issue Header +## L2/L3 执行 issue 头部 ```markdown -目标合并分支: +目标合并分支: <仓库分支/lane> 编号: PJ2026-010N0M 短名: <8字以内> @@ -183,7 +186,7 @@ One paragraph describing the product and research objective. 关联方向: <可空；只列交接方向，不替代主责> 所属方向: #... 所属课题: #... -规格文档: +规格文档: ## 目标 @@ -192,8 +195,8 @@ One paragraph describing the product and research objective. ## 验收入口 - CLI/Web/CaseRun: -- Target lane/node: -- Required evidence: +- 目标 lane/node: +- 必需证据: ## 完成后回写 @@ -202,7 +205,7 @@ One paragraph describing the product and research objective. - [ ] 如稳定规则变化，更新 HWLabOA 总规格 ``` -## Phase Report Section +## 阶段报告章节 ```markdown ## YYYY年M月D日阶段报告（北京时间）