贡献

开始之前

KISS My Agent 是一个科研工程插件，用于让 Agent 工作与问题规模相称、让失败保持可见，并让结论与证据相称。修改仓库前先阅读 AGENTS.md。修改 Skill、Rule 或 Case 时还要阅读扩展。Runtime 和测试行为分别由配置与测试说明。

通过 Git-backed marketplace 安装或更新正式发布的 Plugin，需要可用的 Git executable 和 GitHub 网络访问，但不需要 Python、Node.js、Docker 或其他语言运行时。贡献者工具链与用户路径分开：Git 与 Python 3.11 或更高版本足以运行标准库 validator 和 Setup contract tests。只修改 Plugin 或 Skill 的贡献者不需要安装 Markdown，也不需要在本地构建站点；pull-request CI 会验证站点。只有真实 discovery 和 dogfooding 检查才需要 Codex。

v0.1 contributor CLI skills/kiss-my-agent-setup/scripts/setup.py 已在 v0.2 移除，这是 breaking contributor-interface change。Setup、check、remove 与 role configuration 应迁移到对话式 kiss-my-agent-setup Skill；粘贴 raw text 时使用 $kiss-my-agent:kiss-my-agent-setup 调用，并把 Agent 原生 engineering evidence 与 deterministic repository-test evidence 分开。

参与本项目即表示同意遵守 Code of Conduct。

在哪里参与

当前文档契约存在可复现缺陷时，使用 bug report。
说明缺失、矛盾或难以执行时，使用 documentation report。
有当前 consumer 且结果范围明确时，使用 feature request。改变 plugin/marketplace 布局、setup scope、角色 schema、Skill trigger 边界、Pages 发布或永久规则前必须先建 issue。
对反复出现的决策方法或具体对照，使用专门的 Rule or Case proposal 模板。小型、有界修正可以直接提交 pull request。
使用 Q&A Discussions寻求使用帮助；尚未收敛为有界改动的开放想法放入 Ideas Discussions。
按安全说明私下报告漏洞。绝不在 issue 或 Discussion 中放入凭证、exploit 细节、私有数据或敏感日志。

贡献者环境准备

在 GitHub 上 fork 仓库，clone 自己的 fork，并把 canonical repository 添加为 upstream：

git clone https://github.com/YOUR_ACCOUNT/Kiss-My-Agent.git
cd Kiss-My-Agent
git remote add upstream https://github.com/AoiOTA/Kiss-My-Agent.git
git fetch upstream

确认贡献者解释器。修改 Plugin、Skill、配置或 Setup contract 不需要虚拟环境或安装 package。

Linux 或 macOS：

python3 --version

Windows 原生 PowerShell：

py -3 --version

显示的 Python 版本必须是 3.11 或更高。WSL 使用 Linux 步骤，产生的是 Linux 证据，而不是 Windows 证据。文档贡献者可以选择创建本地验证中说明的隔离环境。

修改边界

保持人对目标、架构、验收标准、非目标和停止边界的所有权。
保持 kiss-my-agent 精确路由且 non-catch-all。只有反复出现的方法才新增 Rule，只有有用的具体对照才新增 Case。
没有已批准的当前 consumer 时，不扩张 setup、workflow、release、compatibility、telemetry、scoring 或 evaluation machinery。
保持三个 owner：config.toml 中的默认配置、standalone role TOML discovery，以及 AGENTS 中的动态调度。Setup 独立为缺失 Master 字段补入 gpt-6-astra / high、为两个多代理开关补入 true，并为 features.context_management.experimental_mode 补入 true。保留已有用户值；只有完整的顶层 gpt-5.6-sol / max pair、每个 key 准确出现一次且每行带准确 KISS marker 时，才成对更新为 Astra/high。Marker 控制 remove ownership，除此例外不授权重置已有值。Config 不得枚举角色文件。
把提供的角色视为可编辑的 fresh-setup seeds，而不是封闭 catalog；角色 name 是身份，文件名只是约定。角色一旦存在即归用户所有，setup 或 Plugin update 永不覆盖、迁移或判定其版本。
Master 可直接完成明确的小任务或局部工作；对实质批量工作、可独立并行或需要不同视角的工作，在收益超过协调成本时应积极委派。Master 保留架构、验收与证据判断。每种角色可有零个、一个或多个实例，无固定组合或顺序；委派默认扁平，每个共享资源保留一个 writer/operator。合格的大型独立子系统可使用一个临时有界 lead，其 workers 不再委派；绝不增加更深或永久层级。
区分由 Host/对话选择的 Master settings 与 role settings。当前 starter roles 设置 model = "gpt-6-astra" 与 model_reasoning_effort = "medium"；显式 spawn 设置先于 [agents] defaults 与 parent 解析，随后任何 role-level 值成为最终 override。每个已有角色都作为 user-owned 保留；后续 setup 和 update 不得迁移，role wizard 也不得编辑 Master config。
保留用户和其他 Agent 的无关改动。范围外 refactor、生成产物和格式化不得进入 diff。
每份英文开发者文档与简体中文配套文件必须同步：语言切换、显式 anchor IDs、章节顺序和 fenced command blocks。
面向 Codex 的 AGENTS、Skills、Rules、Cases、角色 TOML、LICENSE 与 CODE_OF_CONDUCT.md 只保留英文。
绝不加入凭证、私有路径、私有数据、日志、sessions、本地 plugin cache、虚拟环境或生成的测试内容。

开发流程

从 canonical main 的最新状态创建聚焦分支。使用简短、描述性的分支名；下面只是示例，不是强制命名规则。

git fetch upstream
git switch -c docs/clear-onboarding upstream/main

编辑前先追踪实际 producer-consumer 路径。用最小有效输入复现缺陷，只修改 owning module，加入一条修复前失败的 regression check，并在迭代时运行聚焦检查。如果证据表明不需要代码或文档变更，有依据的 no-change 结论也是有效结果。

创建 pull request 前，检查完整 diff，确认没有无关工作，运行下文适用的必需本地检查，只提交预期文件，再把分支推到自己的 fork：

git status --short
git diff upstream/main
git add path/to/intended-file path/to/another-intended-file
git diff --cached --check
git commit -m "docs: clarify onboarding"
git diff --stat upstream/main...HEAD
git push -u origin docs/clear-onboarding

把示例 paths 和 commit message 换成实际的有界改动；不要使用 git add .。不要重写其他贡献者的分支、force-push 共享工作，或把 release 准备与无关修复混在一起。

本地验证

只修改 Plugin、Skill、配置或 Setup 的贡献不需要第三方 Python 依赖。本地运行下面两项标准库检查。

Linux 或 macOS：

python3 scripts/validate.py
python3 -m unittest tests.test_setup -v

Windows 原生 PowerShell：

py -3 scripts/validate.py
py -3 -m unittest tests.test_setup -v

这些检查验证 source 与 Setup contracts；它们不会执行真实 Codex setup，也不能证明 Host 行为。

它们还验证 v0.1 skills/kiss-my-agent-setup/scripts/setup.py interface 已被移除。不得恢复它，也不得用另一个仓库 staging/setup script 取代；受支持的 setup interface 是对话式 Skill。

修改文档或站点时，CI 是必需的站点构建证据。贡献者可以选择在 checkout 外创建隔离环境进行本地预览。

Linux 或 macOS：

python3 -m venv ../kiss-my-agent-docs-venv
. ../kiss-my-agent-docs-venv/bin/activate
python -m pip install -r requirements-site.txt
python -m unittest tests.test_build_site -v
python scripts/build_site.py --output _site

Windows 原生 PowerShell：

py -3 -m venv ..\kiss-my-agent-docs-venv
..\kiss-my-agent-docs-venv\Scripts\Activate.ps1
python -m pip install -r requirements-site.txt
python -m unittest tests.test_build_site -v
python scripts/build_site.py --output _site

_site/ 是已忽略的本地预览，不得提交。贡献者不需要只为在本地运行完整套件而安装 Markdown。

CI 与 release maintainer 在安装 requirements-site.txt 后负责完整的 deterministic 入口：

python scripts/test_all.py

它会运行仓库验证、所有单元测试、临时文档站构建、Git whitespace validation 和运行前后 working-tree 检查。失败本身就是结果的一部分：保留第一个决定性错误，并修复真实 owner。配置了 workflow 不代表它已通过：pull request 需要其当前 commit 的原生绿色 jobs。macOS 或 Windows 支持必须由对应 platform 的精确绿色 job 证明；WSL 仍然只是 Linux 证据。

用 KISS My Agent 开发 KISS My Agent

开发 KISS My Agent 时使用 KISS My Agent，但反馈循环必须受 issue 中由人确定的目标和验收标准约束。Dogfooding 可以暴露歧义或缺陷；它不授权插件重新定义自身架构、扩大自身范围，或把自己的判断当作验收证据。

真实检查前记录 source 和 Host 基线：

git rev-parse HEAD
git status --short
codex --version

真实检查分为两个不同层面：

项目 instructions 与 roles。 从当前 checkout 启动可信的新 Codex 会话，给它一项真实且有界的贡献任务。让 Master 按工作量、并行机会、耦合、风险与协调成本选择直接完成小任务或有收益的委派。对有收益的独立批量工作或需要不同视角的工作应积极委派，不要求固定角色组合；委派保持扁平，每个共享资源指定一个 owner。只有合格的大型独立子系统才使用临时 lead，绝不形成更深层级。确认无关 dirty-tree 改动仍被保留，subprocess failures 仍然可见。
已编辑的 plugin package。 不要为了让本地 cache 失效而修改 tracked release manifest 或 Git-backed marketplace。使用 Codex 的 Plugin Creator local-update workflow，在独立 local marketplace 中暂存一次性副本，让该 marketplace 指向暂存副本，并且只给暂存 manifest 添加一个 +codex.<cachebuster> 后缀。把它从该 local marketplace 安装进隔离 Codex home，然后启动新 thread，让 Host 加载暂存的 Skills。

外部贡献者可复制下面的 Codex prompt 调用该 workflow：

$plugin-creator update this existing KISS My Agent plugin for local development. Stage a disposable candidate copy outside the checkout in a separate local marketplace, point that marketplace only at the candidate copy, add exactly one +codex.<cachebuster> suffix to the copy's manifest version, reinstall it from that marketplace into an isolated Codex home, and tell me to start a new thread. Do not modify tracked release files or the Git-backed marketplace.

参见 OpenAI 官方的 Plugin Creator 与 local marketplace 指南和marketplace add/upgrade 命令。不要为此 workflow 新增仓库 staging script。

在新 thread 中确认 /skills 显示 canonical Plugin Skills kiss-my-agent:kiss-my-agent 与 kiss-my-agent:kiss-my-agent-setup。只对匹配的非显然决策调用 $kiss-my-agent:kiss-my-agent。只在一次性 project scope 中使用 $kiss-my-agent:kiss-my-agent-setup 检查 setup、check、Agent 配置和 remove；开发测试不得使用真实 global scope。保留首次 failed precondition，不要通过重试隐藏它。

分别报告每种证据层级：

证据	能支持	不能支持
Source inspection	被检查文件写了什么	已加载的 runtime 行为
`test_all.py` PASS	该精确 source 实际实现的检查	发布、Host 加载或 Agent 服从
原生 CI PASS	该 platform、job 与精确 commit	所有 OS 版本或未来兼容性
Fresh-session discovery	该 session 中可见的 Skills 或 roles	未来行为或权限安全性
一次有界 Smoke	观察到的任务与环境	普遍可靠性或产品验收
新用户 Pilot	该参与者无需帮助完成了指定场景	普遍可用性
Release verification	已测试的公开 tag、archive、install 或 upgrade 路径	未发布改动或未来 release

记录 platform、原生 shell、精确 source state、Codex 版本、trust state、session 是否为新建、marketplace source/version、prompt、预期结果、实际结果和未测试表面。回答了既定问题后立即停止；不要为了制造信心而重复运行。

Coordinator wait window 在没有新消息时返回，不代表子 Agent 超时或失败。有界且不冲突的任务应继续；只有 assignment 已失效、越界、争用共享资源，或用户明确要求停止时才中断。

如果 delegation 被禁用、不可用或没有合适角色，Master 可在已有授权和自身能力内继续工作，无需为 staffing 另设审批。用户明确要求的独立检查、特定角色或真实能力缺口仍须报告，不能把直接执行冒充为满足这些要求。

Pull Requests

向 canonical main 创建 pull request。每个 pull request 只须填写模板中的 Outcome、Change summary、Validation 与 Limitations。需要先建 issue 时必须关联它。只有改动影响 public interface、新增 mechanism、准备 release，或关联 issue 明确要求时，才补充 current consumer、smallest-change rationale 与显式非目标。

Pull request 要聚焦且便于审查。解决重大 review findings 时不要顺带做宽泛清理。绿色 checks 必须属于当前 pull-request commit。Maintainer 使用 Squash and merge 合并已接受的改动，并可删除已合并分支；贡献者不需要只为制造一个 commit 而重写原本清晰的本地 commit history。

测试通过不能证明模型行为、可用性、发布或 release 成功。直接说明所有未测试表面。

发布流程

本节仅供 maintainer 使用。下面示例中的每个 vX.Y.Z 都要替换为本次唯一选定的 release tag，每个 X.Y.Z 都要替换为对应 manifest version。任何已推送 tag 都不可变：绝不移动、删除或重建。

创建有界 release issue，写明验收标准、兼容性约束和显式非目标。
创建 tag 前，在一次性 candidate 中完成行为修改。运行适用的本地检查、完整套件，以及该精确 candidate commit 的 Ubuntu、macOS、Windows 原生 pull-request CI。Candidate 证据不能证明 public install 或真实 Host 行为。
合入聚焦 pull request。将 Plugin manifest version 与 marketplace ref 对齐为 X.Y.Z / vX.Y.Z，同步中英文文档，并验证精确的 merged origin/main commit。

bash git fetch origin git switch main git pull --ff-only origin main

对该 commit 运行完整 deterministic 入口。Linux 或 macOS：

bash python3 scripts/test_all.py

Windows 原生 PowerShell：

powershell py -3 scripts/test_all.py

创建并推送不可变的 annotated tag。此时还不能创建 GitHub Release：

bash git tag -a vX.Y.Z -m "KISS My Agent vX.Y.Z" git push origin vX.Y.Z

只运行必须经过已推送公开分发表面的检查。Source 与覆盖行为未改变时可以复用旧证据，但必须说明是复用；创建 tag 后不要重复 candidate checks。只验证 release 验收标准要求的公开 archive、marketplace install 或 upgrade、fresh-session discovery 或其他 public-only 行为。

bash codex plugin marketplace upgrade kiss-my-agent codex plugin list --marketplace kiss-my-agent

行动前先分类第一个决定性的 post-tag failure： - Tagged 产品源码中的缺陷：保留 tag，不为它创建 Release；修复 source 后使用下一个 patch version。 - Harness、command construction 或 environment failure：修复该 owner，并针对同一个 tag 只补取缺失证据。 - Evaluator error 或其他 invalid run：修正 evaluation，只重跑无效观察；它不是产品负面证据，也不触发 patch version。 - GitHub Release 发布后才发现的产品缺陷：保留已发布 tag，以新的 patch version 发布修复。
只有必需的公开检查通过后，才能把创建 GitHub Release 作为最后一个发布步骤：

bash gh release create vX.Y.Z --verify-tag --title "KISS My Agent vX.Y.Z" --generate-notes

验证公开 Release 页面与 archives，再在 canonical handoff 中记录精确 commit、CI links、有界公开检查、复用证据和剩余限制。

绝不 force-push main、移动已推送 tag、压掉失败检查、把 invalid run 重新标记为成功，或因 harness/environment failure 创建新 patch tag。