模拟电子技术教案怎么写？从课时划分到六模块模板与Word自动化生成
2026/9/17 14:36:40
Lightdash 双 Issue 追踪体系：Linear 内部规划 + GitHub 公开反馈的协同工作流
【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash
Lightdash 仓库为 AI Agent（Claude Code 等）与维护团队定义了一套双追踪器（dual-tracker）Issue 管理体系：内部规划默认落在 Linear，客户可见的公开反馈落在 GitHub Issues，二者通过自动同步与"先脱敏、再发布"的桥接流程打通。本文基于 docs/agents/issue-tracker.md 展开，结合仓库内的 triage 标签词汇表、CLAUDE.md 技能声明 与 bug 报告模板 的源码证据，完整讲解追踪器分工、访问方式、Linear ↔ GitHub 桥接规则、triage 流程以及/wayfinder路线图（wayfinding）操作，让读者（尤其是 Agent）能准确、合规地在这套体系中创建、读取、分诊和处理 Issue。
一、双追踪器架构：一条铁律
整个体系由一条原则统摄：
默认使用 Linear；当无法确定某个 Issue 该归属哪个追踪器时，先询问。
- Linear —— 内部追踪器：承载所有规划阶段的工作，包括 wayfinder 地图（map）、规格说明（specs）、任务拆解（ticket breakdowns），以及任何没有客户提出的规划中的修复或功能请求。
- GitHub（
lightdash/lightdash仓库的 Issues）—— 公开开源追踪器：当客户提出某个 Issue、或客户正在其上回应时，该 Issue 才进入（或被移动）到这里。
这一分工的本质是"可见性边界"：Linear 是私密的工作面，GitHub 是面向社区与客户的门面。从源码证据看，这条规则已被固化为 Agent 的顶层指令 —— CLAUDE.md 在 "Agent skills → Issue tracker" 一节直接声明 "Linear (internal, default) + GitHub Issues (public, customer-facing). Seedocs/agents/issue-tracker.md"，意味着任何遵循该仓库指引的 Agent 在开工前都应先加载本文档确立的默认值。
为什么是"内部 + 公开"双轨
- 内部轨（Linear）：支持规格迭代、依赖关系（blocked-by）、子任务等精细结构，适合承载尚未成熟的规划与探索性工作，不会把噪音暴露给社区。
- 公开轨（GitHub）：是开源项目接收外部反馈的法定渠道，Issue 编号对公众可见、可订阅、可回应，同时作为社区的请求面（request surface）。
二、访问方式：两套入口
| 追踪器 | 访问方式 | 说明 |
|---|---|---|
| Linear | 可用的任意 Linear 访问手段（MCP 工具、API） | 不限定具体客户端，Agent 用自身具备的 MCP/API 能力即可 |
| GitHub | ghCLI | 仓库信息通过git remote -v推断，无需硬编码 |
GitHub 侧的关键细节：Agent 不应假设仓库地址，而是读取当前仓库的远程配置（git remote -v）来确定上游仓库，随后使用ghCLI 进行gh issue view <number> --comments等操作（详见下文"获取相关票证"）。
三、Linear ↔ GitHub 桥接：同步、授权与脱敏
两个追踪器不是孤岛，而是通过一套明确的桥接规则协同工作。
3.1 GitHub → Linear：自动同步
- GitHub Issue 会自动同步进 Linear，落在PROD 团队、Triage 队列中；
- 同步的标记方式是：GitHub Issue 上会出现一条
<!-- linear-linkback -->注释，作为"该 Issue 已进入内部追踪器"的链接回写。
从仓库的实际使用中可以印证这种编号形状：例如 docs/usage-analytics/architecture.md 中引用历史票证时使用的正是PROD-11059、PROD-8603、PROD-11103这类PROD-<数字>格式 —— 即 Linear 中 PROD 团队的票证编号，也印证了"GitHub 同步到 Linear 后落在 PROD 团队"这一流转路径。
3.2 Linear → GitHub：必须授权 + 脱敏
反向流动则严格受限：
- 逐票授权：将任何 Linear 内容重新发布（republish）到 GitHub，都需要用户对该特定票证的明确授权 —— 发布前必须向用户确认；
- 公开即永久公开：凡是发布到 GitHub 的内容都是公开的。发布前必须脱敏，具体规则为：
- 不得包含：客户名称、域名、邮箱、工作区名（workspace names）、机密信息、确切的业务数据；
- 使用泛化角色指代，例如 "a user"、"a customer"；
- 对于 bug 类内容，必须匹配 .github/ISSUE_TEMPLATE/bug_report.yml 模板结构。
3.3 将私有 Linear 票证转为公开（已授权流程）
文档给出了一个完整的操作序列：
- 取消（cancel）原始的私有 Linear 票证；
- 发布一个脱敏后的 GitHub Issue；
- 同步机制会自动在 Linear 创建一个新票证，此时把原票证的team / project / status / assignee恢复（restore）到这条自动创建的 Linear 票证上。
这样既保住了公开侧的合规性，又不丢失内部票证的工作上下文（团队、项目、状态、指派人）。
3.4 对照真实模板理解"匹配 bug_report.yml"
"匹配模板"不是一句空话。仓库中的 .github/ISSUE_TEMPLATE/bug_report.yml 明确规定了 bug 报告的字段结构：
name: Bug report、description与内置标签🐛 bug、类型Bug；- 必填字段：
Description（发生了什么、期望什么）与Steps to Reproduce the Bug or Issue（复现步骤，含占位示例）； - 可选字段：
version（Lightdash 版本，可在首页页脚查看，占位示例v0.1045.0）与Cloud or self-hosting（下拉选项：cloud/self-hosting）。
因此，Agent 在代用户向 GitHub 发布 bug 时，应生成与此结构一致的正文，并隐去所有可识别客户与业务信息。
四、技能语义：统一 Agent 的行为接口
本文档同时定义了 Agent 在遇到两种常见技能指令时的标准动作，保证不同 Agent / 会话行为一致。
4.1 "publish to the issue tracker"（发布到 Issue 追踪器）
- 默认动作：创建一条 Linear Issue。
- 仅在客户提出该 Issue、或客户正在其上互动时，才发布到 GitHub —— 且必须脱敏。
4.2 "fetch the relevant ticket"（获取相关票证）
先按标识符形状解析目标属于哪个追踪器，再调用对应命令：
| 标识符形状 | 归属 | 获取方式 |
|---|---|---|
ABC-123（如PROD-1234） | Linear Issue | 使用 Linear 访问手段（MCP/API） |
#123或 github.com 的 URL | GitHub Issue | gh issue view <number> --comments（--comments用于一并读取讨论） |
这套"按形状分派"的设计让 Agent 无需上下文猜测即可路由到正确的工具链。
五、Triage 表面：一套词汇、两个追踪器
分诊（triage）是双轨体系的关键汇合点：由于 GitHub Issue 会自动同步进 Linear，Agent 的分诊工作默认在 Linear 队列中进行；但当某个 Issue 是公开的且客户正在关注时，需要在 GitHub 侧也应用标签。
5.1 标签词汇表
标签词汇在两个追踪器中同名存在。仓库的 docs/agents/triage-labels.md 给出了规范映射表：
| 规范角色（canonical role） | 仓库标签（repository label） | 含义 |
|---|---|---|
needs-triage | needs-triage | 维护者需要评估该 Issue |
needs-info | needs-clarification | 等待澄清 |
ready-for-agent | ai-ready | 已完全明确，可供 AFK（无人值守）Agent 处理 |
ready-for-human | open-questions | 实现前需要人类决策 |
wontfix | wontfix | 不会处理 |
关键规则：当某个技能（skill）提到规范角色时，实际应打上仓库标签。例如技能说 "mark as ready-for-agent"，就在对应追踪器上应用ai-ready。这套映射在 CLAUDE.md 中同样被声明："Use the repository's mapped triage vocabulary. Seedocs/agents/triage-labels.md."
5.2 PR 是否作为请求表面？
PRs as a request surface: no.（PR 不作为请求表面：否）
文档明确当前策略为"否"，即外部 PR 不应被当作功能请求对待；该标记可切换为yes（若未来希望将外部 PR 视为 feature request），且/triage命令会读取这个标记。这意味着当前阶段，社区的 feature 请求只通过 Issue 通道进入，PR 不参与自动分诊。
六、Wayfinding 操作：/wayfinder的六步工作流
Wayfinding（探路）是这套追踪器体系中面向复杂探索性工作的操作集合，由/wayfinder命令驱动，所有内容均保存在 Linear。本文档定义了六个核心操作：
| 操作 | 定义 | 关键动作 |
|---|---|---|
| Map（地图） | 一条承载 Notes / Decisions-so-far / Fog 正文的 Linear Issue，打上wayfinder-map标签（标签缺失时先创建） | 地图是探索的"锚点"，记录讨论、决策与迷雾 |
| Child ticket（子票证） | 地图的子 Issue，标签为wayfinder-<type>，类型为research/prototype/grilling/task | 一旦认领（claimed），指派给负责推进的开发者 |
| Blocking（阻塞） | 使用 Linear 原生的 "blocked by" Issue 关联关系 | 当所有阻塞项均处于 Done/Canceled 时，票证解除阻塞 |
| Frontier query（前沿查询） | 地图中"无未解阻塞项、且无人认领"的未关闭子 Issue 集合 | 按地图顺序取第一条 —— 即下一个应推进的工作项 |
| Claim（认领） | 把子 Issue 指派给自己 | 这是会话的第一次写入动作，标识工作正式被接管 |
| Resolve（解决） | 在子 Issue 上评论答案并标记为 Done，然后在 Map 的 Decisions-so-far 中追加一条上下文指针 | 把结论沉淀回地图，供后续子任务引用 |
这六步构成了一个自洽的探索循环：Map 收拢问题 → 拆出 Child ticket → 用 Blocking 表达依赖 → 用 Frontier query 选出下一个待办 → Claim 认领 → Resolve 闭环并回写决策。对 Agent 而言，这相当于一套"只读调研 → 写入认领 → 回写结论"的可审计工作流，且所有状态变化都通过 Linear 原生能力（issue relations、labels、assignee）表达，无需额外的状态存储。
七、与仓库其他规范的配合
为了让这套追踪器体系在仓库中真正落地，它与周边规范形成互补：
- 领域词汇一致性：docs/agents/domain.md 要求 Issue 标题、验收标准、测试、代码与 UI 文案使用 CONTEXT-MAP.md 词汇表中的规范术语，若提案与 ADR 冲突需显式暴露而非静默覆盖 —— 这同样适用于写进 Issue 的措辞；
- Agent 顶层入口：CLAUDE.md 将 "Issue tracker"、"Triage labels"、"Domain docs" 三个技能声明集中放置，Agent 在执行任何与 Issue 相关的操作前都应先阅读这三个文档；
- 公开模板约束：发布 bug 必须对齐 .github/ISSUE_TEMPLATE/bug_report.yml 的字段结构，模板同时配套了
documentation.yml与feature-request.yml等其他公开模板，构成完整的社区请求面。
八、给 Agent 与维护者的速查清单
- 新建 Issue：默认 Linear；客户提出的需求才考虑 GitHub；
- 拿不准归属：问用户，不要猜；
- 发布到 GitHub 前：拿到该票证的明确授权，脱敏（无客户名、域名、邮箱、工作区名、密钥、精确业务数据），bug 对齐
bug_report.yml模板； - 读取票证：
ABC-123走 Linear，#123/ github.com URL 走gh issue view <number> --comments； - 分诊：在 Linear 队列处理（GitHub 已自动同步），公开且客户在关注的票在 GitHub 侧也打标签，角色标签 ↔ 仓库标签按 triage-labels.md 映射；
- 探路：Map 收束、Child ticket 拆解、Blocking 表达依赖、Frontier query 选下一个、Claim 认领、Resolve 回写决策，全程留在 Linear。
【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考