> ## Documentation Index
> Fetch the complete documentation index at: https://labs.prompthon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Issue 指南

<div className="not-prose my-4 rounded-md border border-gray-200 bg-gray-50 p-2 text-sm dark:border-gray-800 dark:bg-gray-900/40">
  <div className="mb-2 px-1 text-xs font-semibold uppercase tracking-wide text-gray-500 dark:text-gray-400">需要帮助？</div>

  <div className="flex flex-wrap gap-2">
    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://discord.gg/sDE2HhGTg4" target="_blank" rel="noreferrer">
      <Icon icon="discord" iconType="brands" size={14} />

      <span>在 Discord 提问</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/issues/new/choose" target="_blank" rel="noreferrer">
      <Icon icon="github" iconType="brands" size={14} />

      <span>提交 GitHub Issue</span>
    </a>

    <a className="inline-flex items-center gap-2 rounded-md border border-gray-200 bg-white px-3 py-1.5 font-medium text-gray-700 no-underline shadow-sm hover:border-gray-300 hover:bg-gray-50 dark:border-gray-800 dark:bg-gray-950/60 dark:text-gray-200 dark:hover:bg-gray-900" href="https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/SUPPORT.md" target="_blank" rel="noreferrer">
      <Icon icon="life-ring" size={14} />

      <span>支持指南</span>
    </a>
  </div>
</div>

当你有一个具体的仓库工作项时，请使用 GitHub issue；不要只是提出一个早期问题。

如果请求仍处于探索阶段，请先使用 [Support](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/SUPPORT.md) 或社区 Discord。如果工作已经明确范围，请使用匹配的 issue 表单，这样请求会以可审阅的形式进入流程。

从支持问题、issue 认领，到 fork 或分支、pull request 的完整顺序，请阅读
[贡献者基础 GitHub 流程](/zh-Hans/contributor-kit/contribution-workflow)。

## 选择正确的 issue 表单

* `Content Proposal`：新的实验室页面、重大修订、雷达笔记、精选参考说明，或发布后的后续内容
* `Source Project Proposal`：新的或经过大幅修订的、由仓库拥有的 starter，或位于允许的 lane-local `examples/` 文件夹下的示例
* `Practitioner Skill Package`：位于 `skills/` 下的新建或大幅修订的 local-agent workflow package。这类 issue 是代码加文档的贡献，不是纯文档 issue。
* `Repository Feature Or Process Proposal`：关于仓库工作流、issue 接收、模板、标签、审查规则、贡献者文档或维护者运营的功能请求
* `Bug Or Broken Surface Report`：损坏的链接、事实问题、示例缺陷、模板问题，或仓库工作流回归

## issue 编写标准

* 一张 issue 只聚焦一个结果。
* 明确指出受影响的确切路径、界面或工作流。
* 先描述当前问题，再谈解决方案。
* 提出能解决问题的、最小且清晰的变更。
* 添加成功标准，以便审阅者判断工作何时完成。
* 链接相关的仓库文档、模板或现有页面。
* 对于内容类工作，请包含来源谱系，而不是直接放入原始上游材料。

## 认领 issue

认领状态应该在 issue 本身可见。只有当维护者希望把任务标记为某位内部贡献者正在负责时，才使用 GitHub assignee 字段。

对于尚未成为内部贡献者的公开贡献者，请用 issue 评论作为公开的认领请求：

```md theme={null}
Claim request:
- GitHub username:
- Planned scope:
- Expected first update:
```

维护者可以在评论中确认认领，并添加 `claimed` 标签。除非该贡献者已经是本仓库的内部贡献者，否则保持 GitHub assignee 字段为空。如果工作停滞，维护者可以移除标签或 assignee，并留下简短状态评论，重新开放该任务。

GitHub 原生 assignment 功能受权限约束：拥有写权限的人可以分配 issue；可被分配的人包括自己、评论者、拥有写权限的用户，以及拥有读权限的组织成员。在本仓库中，assignee 表示内部贡献者信号。

认领被确认后，请按照
[贡献者基础 GitHub 流程](/zh-Hans/contributor-kit/contribution-workflow)
完成 fork、分支、pull request 和 review 步骤。

## 一个好的 skill package issue 应包含什么

当工作是在 `skills/` 下创建或修订可安装的 local-agent workflow package 时，请使用 `Practitioner Skill Package` 表单。

好的提交通常包括：

* 技能应该支持的面向用户的工作流
* 需要的本地状态、API、浏览器工具或文件系统访问
* 预期的 `skills/<skill-slug>/` 包结构
* 一份面向人的 `README.md`，解释这个技能为什么存在、适合谁，以及端到端工作流如何运作
* 一份面向 agent 的 `SKILL.md`，定义 Codex 何时应调用它
* 安全、隐私和生成物边界
* 针对说明和辅助代码的具体验收标准

## 一个好的功能请求应包含什么

当请求真正涉及这个仓库应该如何工作时，请使用 `Repository Feature Or Process Proposal` 表单。

好的提交通常包括：

* 维护者或贡献者的痛点
* 建议的仓库级变更
* 该变更影响的界面
* 权衡、迁移成本，或为何应延后
* 成功的明确判定标准

## 标题示例

* `[Feature/Process]: Add a public guide for choosing GitHub issue forms`
* `[Content]: Add a systems page on agent evaluation loops`
* `[Source Project]: Add a minimal deep-research-agent starter`
* `[Practitioner Skill]: Add a Daily News Watcher skill package`
* `[Bug]: Fix the broken contributor-kit link in README.md`

## 提交前

* 查看 [Contributing](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/CONTRIBUTING.md)。
* 检查 [贡献者工具包](/zh-Hans/contributor-kit) 中是否有匹配的模板或指南。
* 搜索现有 open issues，避免重复提交。
* 优先使用精确的仓库路径，而不是泛泛描述。
* 如果你不确定这个请求是否现在就应该放在这里，请先使用 [Support](https://github.com/Prompthon-IO/agent-systems-handbook/blob/main/zh-Hans/SUPPORT.md)。

## 功能请求示例

如果你想提出一个关于 issue 接收流程的仓库功能，请在 `Repository Feature Or Process Proposal` 表单中按如下方式组织：

* `Current problem`: 贡献者可以找到 issue 表单，但不清楚哪种表单算是功能请求，哪种算内容提案。
* `Proposed change`: 在 `contributor-kit/` 中添加一份公开的 GitHub issue 指南，从 `CONTRIBUTING.md`、`SUPPORT.md` 和 issue 选择器中链接到它，并在流程表单中明确提及仓库功能请求。
* `Affected surfaces`: issue 接收、贡献者文档
* `Tradeoffs and risks`: 需要维护的贡献者文档稍多一些，但在 issue 接收过程中歧义会少得多
* `What success looks like`: 新贡献者无需向维护者询问分流帮助，就能选择正确的 issue 表单