尧图网页设计 
Lightdash 双 Issue 追踪体系Linear 内部规划 GitHub 公开反馈的协同工作流【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdashLightdash 仓库为 AI AgentClaude Code 等与维护团队定义了一套双追踪器dual-trackerIssue 管理体系内部规划默认落在 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以及任何没有客户提出的规划中的修复或功能请求。GitHublightdash/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 能力即可GitHubghCLI仓库信息通过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复现步骤含占位示例可选字段versionLightdash 版本可在首页页脚查看占位示例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-1234Linear Issue使用 Linear 访问手段MCP/API#123或 github.com 的 URLGitHub Issuegh issue view number --comments--comments用于一并读取讨论这套按形状分派的设计让 Agent 无需上下文猜测即可路由到正确的工具链。五、Triage 表面一套词汇、两个追踪器分诊triage是双轨体系的关键汇合点由于 GitHub Issue 会自动同步进 LinearAgent 的分诊工作默认在 Linear 队列中进行但当某个 Issue 是公开的且客户正在关注时需要在 GitHub 侧也应用标签。5.1 标签词汇表标签词汇在两个追踪器中同名存在。仓库的 docs/agents/triage-labels.md 给出了规范映射表规范角色canonical role仓库标签repository label含义needs-triageneeds-triage维护者需要评估该 Issueneeds-infoneeds-clarification等待澄清ready-for-agentai-ready已完全明确可供 AFK无人值守Agent 处理ready-for-humanopen-questions实现前需要人类决策wontfixwontfix不会处理关键规则当某个技能skill提到规范角色时实际应打上仓库标签。例如技能说 mark as ready-for-agent就在对应追踪器上应用ai-ready。这套映射在 CLAUDE.md 中同样被声明Use the repositorys 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），仅供参考 Lightdash 双 Issue 追踪体系：Linear 内部规划 + GitHub 公开反馈的协同工作流
Lightdash 双 Issue 追踪体系Linear 内部规划 GitHub 公开反馈的协同工作流【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdashLightdash 仓库为 AI AgentClaude Code 等与维护团队定义了一套双追踪器dual-trackerIssue 管理体系内部规划默认落在 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以及任何没有客户提出的规划中的修复或功能请求。GitHublightdash/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 能力即可GitHubghCLI仓库信息通过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复现步骤含占位示例可选字段versionLightdash 版本可在首页页脚查看占位示例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-1234Linear Issue使用 Linear 访问手段MCP/API#123或 github.com 的 URLGitHub Issuegh issue view number --comments--comments用于一并读取讨论这套按形状分派的设计让 Agent 无需上下文猜测即可路由到正确的工具链。五、Triage 表面一套词汇、两个追踪器分诊triage是双轨体系的关键汇合点由于 GitHub Issue 会自动同步进 LinearAgent 的分诊工作默认在 Linear 队列中进行但当某个 Issue 是公开的且客户正在关注时需要在 GitHub 侧也应用标签。5.1 标签词汇表标签词汇在两个追踪器中同名存在。仓库的 docs/agents/triage-labels.md 给出了规范映射表规范角色canonical role仓库标签repository label含义needs-triageneeds-triage维护者需要评估该 Issueneeds-infoneeds-clarification等待澄清ready-for-agentai-ready已完全明确可供 AFK无人值守Agent 处理ready-for-humanopen-questions实现前需要人类决策wontfixwontfix不会处理关键规则当某个技能skill提到规范角色时实际应打上仓库标签。例如技能说 mark as ready-for-agent就在对应追踪器上应用ai-ready。这套映射在 CLAUDE.md 中同样被声明Use the repositorys 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），仅供参考