docs: align contributor entry docs with approved-bug-fix-only policy (#3089)

* docs: align contributor entry docs with approved-bug-fix-only policy * docs: align contributor entry docs with approved-bug-fix-only policy * docs: align contributor entry docs with approved-bug-fix-only policy * docs: align contributor entry docs with approved-bug-fix-only policy * docs: link Chinese contributing guide * docs: add Chinese contributing guide * docs: add Chinese bug report form * docs: add Chinese feature request form * docs: bilingual PR template header note * docs(zh-cn): naturalize intro, drop stale feature-PR template line * docs: drop stale feature-PR template line * docs: require approved issue in PR template * docs: fix project layout (agent-core-v2 is current, v1 legacy) * docs(zh-cn): fix project layout (agent-core-v2 is current, v1 legacy)
2026-08-20 06:05:36 +00:00 · 2026-08-19 20:31:56 +08:00 · 2026-08-19 20:31:56 +08:00 · c8029f9f3b
commit c8029f9f3b
parent 38a5a934ae
7 changed files with 226 additions and 19 deletions
--- a/.github/ISSUE_TEMPLATE/1-bug-report.yml
+++ b/.github/ISSUE_TEMPLATE/1-bug-report.yml
@ -13,7 +13,7 @@ body:

        Please try to include as much information as possible.

-        If you plan to submit a fix: link this issue in your PR. Small, reproducible bugs can go straight to a PR; for broader or uncertain fixes, wait for maintainer feedback first.
+        If you plan to submit a fix: check the Contribution box below and wait for a maintainer's `/approve` comment in this issue before opening a PR.

  - type: input
    id: version
@ -65,3 +65,10 @@ body:
    attributes:
      label: Additional information
      description: Is there anything else you think we should know?
+
+  - type: checkboxes
+    id: willing-to-pr
+    attributes:
+      label: Contribution
+      options:
+        - label: I am willing to submit a PR for this bug fix myself (please wait for maintainer approval in this issue first)
--- a/.github/ISSUE_TEMPLATE/2-feature-request.yml
+++ b/.github/ISSUE_TEMPLATE/2-feature-request.yml
@ -11,7 +11,7 @@ body:
        Before you submit a feature:
        1. Search existing issues for similar features. If you find one, 👍 it rather than opening a new one.
        2. The Kimi Code team will try to balance the varying needs of the community when prioritizing or rejecting new features. Please understand that not all features will be accepted.
-        3. Do not open a feature PR until maintainers have had a chance to respond here. PRs without prior discussion may be closed without review.
+        3. Do not open a feature PR. External feature PRs are not accepted — features are discussed and decided in this issue; if accepted, the team will implement it or explicitly invite you to contribute.

  - type: textarea
    id: feature
--- a/.github/ISSUE_TEMPLATE/3-bug-report-zh-cn.yml
+++ b/.github/ISSUE_TEMPLATE/3-bug-report-zh-cn.yml
@ -0,0 +1,73 @@
+name: Bug 报告
+description: 报告需要修复的问题
+labels:
+  - bug
+  - needs triage
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢你提交 bug 报告！这能帮助 Kimi Code 变得更好。
+
+        请确认你正在运行最新版本的 Kimi Code CLI——你遇到的问题可能已经被修复。
+
+        请尽量提供完整的信息。
+
+        如果你打算提交修复：勾选下方 Contribution 选项，并等待维护者在本 issue 中以 `/approve` 评论批准后再提 PR。
+
+  - type: input
+    id: version
+    attributes:
+      label: 你运行的 Kimi Code 版本是？
+      description: 复制 `kimi --version` 或 `/version` 的输出
+    validations:
+      required: true
+  - type: input
+    id: plan
+    attributes:
+      label: 你使用的是哪个开放平台/订阅？
+      description: 运行 `/login` 时选择的那个
+    validations:
+      required: true
+  - type: input
+    id: model
+    attributes:
+      label: 你使用的是哪个模型？
+      description: 底部状态栏可见，如 `kimi-k2.6`、`kimi-for-coding` 等
+  - type: input
+    id: platform
+    attributes:
+      label: 你的电脑平台是？
+      description: |
+        macOS 和 Linux：复制 `uname -mprs` 的输出
+        Windows：在 PowerShell 中运行 `"$([Environment]::OSVersion | ForEach-Object VersionString) $(if ([Environment]::Is64BitOperatingSystem) { "x64" } else { "x86" })"` 并复制输出
+  - type: textarea
+    id: actual
+    attributes:
+      label: 你遇到了什么问题？
+      description: 请包含完整的错误信息和提示词（隐去隐私信息）。如可能，请提供文本而非截图。
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: 复现步骤？
+      description: 说明 bug 并给出可复现的代码片段。如适用，请提供 session id 和上下文用量。
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望的行为是什么？
+      description: 如可能，请提供文本而非截图。
+  - type: textarea
+    id: notes
+    attributes:
+      label: 补充信息
+      description: 还有什么想让我们知道的？
+  - type: checkboxes
+    id: willing-to-pr
+    attributes:
+      label: Contribution
+      options:
+        - label: 我愿意自己提交修复此 bug 的 PR（请先等待维护者在本 issue 中批准）
--- a/.github/ISSUE_TEMPLATE/4-feature-request-zh-cn.yml
+++ b/.github/ISSUE_TEMPLATE/4-feature-request-zh-cn.yml
@ -0,0 +1,26 @@
+name: 功能建议
+description: 为 Kimi Code 提议新功能
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Kimi Code 缺少你想要的某个功能？欢迎在这里提议。
+
+        提交功能建议前：
+        1. 先搜索已有 issue，如有类似功能，点 👍 而不是新开 issue。
+        2. Kimi Code 团队会在排序或拒绝新功能时尽量平衡社区的不同需求，请理解并非所有功能都会被接受。
+        3. 不要提交 feature PR。不接受外部功能 PR——功能在本 issue 中讨论和决定；如被接受，由团队实现或明确邀请你来贡献。
+
+  - type: textarea
+    id: feature
+    attributes:
+      label: 你希望看到什么功能？
+    validations:
+      required: true
+  - type: textarea
+    id: notes
+    attributes:
+      label: 补充信息
+      description: 还有什么想让我们知道的？
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@ -1,13 +1,14 @@
 <!--
 Thank you for your contribution to Kimi Code!
-Please open an issue before sending a feature PR — PRs without prior discussion may be closed without review.
+External PRs are accepted for approved bug fixes only: link an issue that a maintainer has approved (an `/approve` comment). External feature PRs are not accepted.
+外部 PR 仅接受获批准的 bug 修复：请链接维护者已批准（`/approve` 评论）的 issue；不接受外部 feature PR。

 See https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md for more.
 -->

 ## Related Issue

-<!-- Link the issue this feature came from. If there is no issue, explain the problem in the next section instead. -->
+<!-- Link the issue this change came from. External PRs must link an issue approved by a maintainer (an `/approve` comment) — PRs without one may be closed. -->

 Resolve #(issue_number)

@ -22,7 +23,7 @@ Resolve #(issue_number)
 ## Checklist

 - [ ] I have read the [CONTRIBUTING](https://github.com/MoonshotAI/kimi-code/blob/main/CONTRIBUTING.md) document.
- [ ] I have linked a related issue, or explained the problem above.
+- [ ] I have linked a related issue (external PRs: the issue must have a maintainer's `/approve`).
 - [ ] I have added tests that prove my feature works.
 - [ ] Ran `gen-changesets` skill, or this PR needs no changeset.
 - [ ] Ran `gen-docs` skill, or this PR needs no doc update.
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@ -1,5 +1,7 @@
 # Contributing to kimi-code

+[中文版](CONTRIBUTING.zh-CN.md)
+
 Thanks for taking the time to contribute! This project moves quickly, and thoughtful contributions from the community are what keep it sharp. The guide below walks you through how we work so your PR has the best chance of landing smoothly.

 ## Before You Start
@ -10,27 +12,25 @@ We hold AI-assisted contributions to the same standard as hand-written ones. **Y

 We only merge PRs aligned with the roadmap. Drive-by refactors without context are unlikely to land.

-**Discuss first** — open an issue before coding. PRs without prior discussion may be closed without review:
+**External PRs are accepted for approved bug fixes only.** Open an issue first and wait for a maintainer to approve it with an `/approve` comment, then link that issue in your PR. PRs without an approved linked issue may be closed without review; once the issue is approved, ask a maintainer to reopen your PR.

- New features or user-visible behavior changes (regardless of size)
+**Discuss first** — open an issue before coding:
+
+- Bug fixes, including small or typo-level ones: open a bug issue and wait for a maintainer's `/approve` before opening the PR
+- New features or user-visible behavior changes (regardless of size): external feature PRs are not accepted — features are discussed and decided in issues, and accepted features are implemented by the team or by explicit maintainer invitation
 - Refactors or other changes larger than ~100 lines
 - Public API or compatibility changes
- Bug fixes where the cause or fix approach is still unclear
-
-**Can open a PR directly** — link an existing issue when there is one:
-
- Clear, reproducible bug fixes with a focused diff
- Typos, documentation-only changes, and small CI/build fixes
- Small changes that clearly match an existing issue or maintainer request

 ## Project Layout

 This is a pnpm monorepo. The most relevant entry points are:

 - `apps/kimi-code` — CLI / TUI
- `apps/vis` — session replay & debugging visualizer
+- `apps/vscode` — VS Code extension
+- `apps/vis` — session debug visualizer
 - `packages/node-sdk` — public TypeScript SDK (`@moonshot-ai/kimi-code-sdk`)
- `packages/agent-core`, `kosong`, `kaos`, `oauth`, `telemetry` — internal engine packages
+- `packages/agent-core-v2` — the agent engine (v2, DI Scope architecture); `packages/agent-core` is v1 and being phased out
+- `packages/klient`, `kap-server`, `protocol`, `transcript`, `kosong`, `kaos`, `oauth`, `telemetry` — internal engine packages
 - `docs/` — VitePress bilingual docs site

 For the full project map, see [AGENTS.md](AGENTS.md).
@ -84,9 +84,7 @@ This repo uses [changesets](https://github.com/changesets/changesets) to manage

 ## Pull Requests

-Use the [PR template](.github/pull_request_template.md) when opening a feature pull request.
-
-PR titles must follow [Conventional Commits](#commit-convention); CI runs `pnpm lint`, `pnpm typecheck`, and `pnpm test` on every PR. Update user-facing docs in `docs/` when behavior changes — use the `gen-docs` skill when working with coding agents.
+Every PR opens with the [PR template](.github/pull_request_template.md). PR titles must follow [Conventional Commits](#commit-convention); CI runs `pnpm lint`, `pnpm typecheck`, and `pnpm test` on every PR. Update user-facing docs in `docs/` when behavior changes — use the `gen-docs` skill when working with coding agents.

 ## Code Style

--- a/CONTRIBUTING.zh-CN.md
+++ b/CONTRIBUTING.zh-CN.md
@ -0,0 +1,102 @@
+# 为 kimi-code 贡献代码
+
+[English version](CONTRIBUTING.md)
+
+感谢你花时间参与贡献！这个项目迭代很快，离不开社区认真的贡献。下面的指南介绍我们的工作方式，帮助你的 PR 顺利合入。
+
+## 开始之前
+
+Kimi Code 对 CLI/TUI 行为、agent 工作流和公开 API 已有自己的主张。如果你的改动会改变这些方向，请先开 issue 对齐，再投入时间写 PR。
+
+我们对 AI 辅助贡献与手写代码一视同仁。**你应该理解自己提交的内容**——改了什么、边界情况下表现如何、为什么适合这个代码库。如果你解释不清楚，这个 PR 就还没准备好接受评审。
+
+我们只合入与路线图一致的 PR。缺乏上下文背景的顺手重构很难被接受。
+
+**外部 PR 仅接受获批准的 bug 修复。** 先开 issue，等待维护者以 `/approve` 评论明确批准，然后在 PR 中链接该 issue。没有已批准关联 issue 的 PR 可能会不经评审直接关闭；issue 获批后，可联系维护者重开你的 PR。
+
+**先讨论**——写代码前先开 issue：
+
+- bug 修复（包括小的、错别字级别的）：先开 bug issue，等待维护者 `/approve` 后再提 PR
+- 新功能或用户可见的行为变更（无论大小）：不接受外部 feature PR——功能在 issue 中讨论和决定，被接受的功能由团队实现，或由维护者明确邀请你贡献
+- 重构或其他超过约 100 行的改动
+- 公开 API 或兼容性变更
+
+## 项目结构
+
+本仓库是 pnpm monorepo，最常用的入口：
+
+- `apps/kimi-code` — CLI / TUI
+- `apps/vscode` — VS Code 插件
+- `apps/vis` — 会话调试可视化工具
+- `packages/node-sdk` — 公开 TypeScript SDK（`@moonshot-ai/kimi-code-sdk`）
+- `packages/agent-core-v2` — 当前的 agent 引擎（v2，DI Scope 架构）；`packages/agent-core` 为 v1，正在逐步废弃
+- `packages/klient`、`kap-server`、`protocol`、`transcript`、`kosong`、`kaos`、`oauth`、`telemetry` — 内部引擎包
+- `docs/` — VitePress 双语文档站
+
+完整项目地图见 [AGENTS.md](AGENTS.md)。
+
+## 开发环境
+
+前置要求：Node.js >= 24.15.0、pnpm 10.33.0、Git。
+
+```sh
+git clone https://github.com/MoonshotAI/kimi-code.git
+cd kimi-code
+pnpm install
+```
+
+常用脚本：
+
+- `pnpm dev:cli` — 开发模式运行 CLI
+- `pnpm test` — 运行测试（vitest）
+- `pnpm typecheck` — TypeScript 检查（注意：会先构建各包）
+- `pnpm lint` — oxlint
+- `pnpm lint:fix` — oxlint 自动修复
+- `pnpm build` — 构建全部包
+
+## 提交规范
+
+所有 commit 和 PR 标题必须遵循 [Conventional Commits](https://www.conventionalcommits.org/)。
+
+| 类型     | 用途                                     | 示例                                   |
+|----------|------------------------------------------|----------------------------------------|
+| feat     | 新功能                                   | feat(agent-core): add tool dedup       |
+| fix      | bug 修复                                 | fix(tui): correct status bar alignment |
+| docs     | 仅文档                                   | docs: clarify install instructions     |
+| chore    | 工具 / 杂务                              | chore: bump dependencies               |
+| refactor | 无行为变更的内部重构                     | refactor(kosong): extract retry helper |
+| test     | 新增或改进测试                           | test(agent-core): cover skill resolver |
+| ci       | CI / 构建流水线变更                      | ci: cache pnpm store                   |
+| build    | 构建系统 / 产物变更                      | build(native): add win32-arm64 target  |
+| perf     | 性能优化                                 | perf(session): batch event flushes     |
+| style    | 仅格式化（无逻辑变更）                   | style: apply oxlint --fix              |
+
+PR 标题由 `pr-title-checker` 工作流强制校验——不合规的标题会阻止合并。
+
+## Changesets
+
+本仓库使用 [changesets](https://github.com/changesets/changesets) 管理版本与发布。
+
+- 每个影响发布产物（代码、行为、公开 API）的 PR **必须**包含 changeset。
+- 仅文档、仅测试或仅 CI 的 PR 可以不加。
+- 用 `pnpm changeset` 生成并按提示操作（涉及哪些包、什么 bump 级别）。
+- 包选择与 bump 级别的仓库约定见 `.changeset/README.md`。在本仓库使用编程 agent 时，使用 `gen-changesets` 技能。
+
+## Pull Requests
+
+PR 会自动套用 [PR 模板](.github/pull_request_template.md)。PR 标题必须遵循 [Conventional Commits](#提交规范)；每个 PR 的 CI 会运行 `pnpm lint`、`pnpm typecheck` 和 `pnpm test`。行为变更时请同步更新 `docs/` 下的用户文档——使用编程 agent 时使用 `gen-docs` 技能。
+
+## 代码风格
+
+- 全仓库 TypeScript。
+- 使用 `oxlint`（配置见 `.oxlintrc.json`）。
+- 用 `pnpm lint:fix` 自动格式化。
+- lint 规则未覆盖的风格选择，跟随周边现有写法。
+
+## 报告安全问题
+
+发现安全问题？请查看 [SECURITY.md](SECURITY.md)，不要开公开 issue。
+
+## 许可证
+
+向本仓库贡献即表示你同意你的贡献按 [MIT 许可证](LICENSE) 授权。