常见问题
这里的 KISS 是什么？
“Keep It Simple, Scientist”：先做能运行、能验证的最小版本，用真实成功或失败决定下一步；只有结果证明需要时，才增加复杂度。
KISS My Agent 解决什么问题？
它主要减少两种会拖慢科研闭环的倾向：
- 过度设计： 当前假设还没有验证，就先按成熟产品去建设，为未来可能性增加现在没人使用的抽象、配置、迁移、兼容层或平台。
- 过度防御： 不让错误自然暴露，而是叠加校验、重试、回退、异常捕获、审批或门禁，甚至把失败包装成成功。
多 Agent 流程、handoff 和检查变成产出，以及把测试通过夸大成产品或科研目标成功，都是这两种问题的常见表现或后果，不是另外两类核心功能。
必要的认证、授权、边界验证、清理，以及对已知可选故障的明确处理，不属于过度防御。KISS 允许的是低成本、可恢复试错，不会移除不可逆操作或其他高风险安全边界。
编码 Agent 为什么容易偏离，KISS 又怎样应对？
Codex 倾向产出“看起来完整、稳健、成功”的答案。用户又常只说“全面”“稳健”或“生产级”，没有说明当前假设、最小目标和停止条件。框架、防御代码、校验、重试和回退既容易生成，也容易表现为工作有进展；模型还倾向避免明显失败，于是错误可能被捕获、绕开或包装成可用结果。
成熟产品在有真实需求和风险时当然可能需要完整架构与防护；科研早期过早加入它们，则会拖慢反馈并隐藏真实错误。KISS 推动一个更短的闭环：目标或假设 → 最小可运行验证 → 真实运行 → 显式成功或失败 → 迭代或停止。测试和流程服务这个目标，不能替代真实结果。
它适合我吗？
它主要面向使用 Codex 做科研 MVP、算法验证、探索性开发和隐藏错误调试的用户，尤其适合需要用真实运行结果快速决定下一步的任务。它不是通用编排器、权限绕过、确定性执行器或形式化 evaluator，也不能保证第一次尝试就正确。详见首页的适用性判断。
如何安装？
已测试基线是已认证且支持 Plugin 的 Codex CLI 0.152.1 和 0.153.0。还需要 git 与 GitHub 网络访问。其他 Codex 版本未验证。请先检查客户端：
codex --version
codex plugin --help
codex plugin marketplace add AoiOTA/Kiss-My-Agent
codex plugin add kiss-my-agent@kiss-my-agent
codex plugin list --marketplace kiss-my-agent
列表中应看到 kiss-my-agent@kiss-my-agent 的状态为 installed, enabled，且版本与当前支持的 release 一致；cache path 可以不同。如果 Plugin 命令、认证或 marketplace 访问失败，请检查客户端支持、login 状态、git 与 GitHub 网络。简单一次性任务安装后直接使用普通单对话。复杂项目若需要持久 workflow，请启动新会话。Plugin cache roles 不会自动加入 Host catalog。在已测试的 Codex 0.152.1 baseline 上，输入 $ 并在 picker 中选择 kiss-my-agent-setup (kiss-my-agent)。Picker 会插入一个结构化 Skill reference；继续补充 setup 请求并提交 prompt 后，才会调用该 Skill。如果直接粘贴文字，运行 $kiss-my-agent:kiss-my-agent-setup set up this project。Host 提示时信任项目；随后另开新会话并运行 $kiss-my-agent:kiss-my-agent-setup check this project。
Setup 后该怎么用？
直接正常使用 Codex，无需用户提醒才应用 KMA。Master 可以直接完成明确的小任务或局部工作；对实质批量工作、可独立并行或需要不同视角的工作，在收益超过协调成本时应积极委派。按工作量、并行机会、耦合、风险与协调成本选择，角色可选不等于 Master 包办全部。每种可用角色都可有零个、一个或多个实例，不要求固定组合、顺序或每次启动子代理。Master 保留架构、验收和证据判断。委派默认扁平，每个共享资源只有一个 operator；合格的大型独立子系统可有一个临时 lead，但不建立更深或永久层级。
如果 delegation 被禁用、不可用或没有合适角色，Master 可在已有授权和自身能力内继续工作，无需为 staffing 另设审批。用户明确要求的独立检查、特定角色或真实能力缺口仍须报告，不能把直接执行冒充为满足这些要求。
什么时候复用 Agent，什么时候使用 fresh Agent？
同一任务、同一 owner、同一 scope 的连续工作复用原 Agent。新任务或新角色、独立 review，或者已加载的 Plugin、instructions 或 configuration 发生变化时，使用 fresh Agent。并行 Agent 上限表示可用容量，不是目标团队规模。KISS 默认开启实验上下文管理，不设置 context window 或 compaction 阈值。
这是 Plugin 还是只有一个 Skill？
它是一个带版本的 Codex Plugin。Plugin 负责安装、分发与更新，目前打包两个 Skills：
kiss-my-agent提供窄范围决策指导。kiss-my-agent-setup管理显式 project/global setup、检查、移除和现有角色配置。
配置后的项目拥有自己的 .codex/config.toml、standalone role TOML 和 managed AGENTS block。这些文件工具工作流仍可由 Skill 完成，不需要 MCP 服务或独立程序。
何时调用 $kiss-my-agent:kiss-my-agent？
每个 Agent 首次接手 KMA 管理的工作时读取，之后复用指导，在选择或改变行动、分工和解释结果时主动应用，不先要求决策“重要”或“不显然”。已经决定的机械执行，包括实现、测试、构建、Git、查询和格式化，无需重复读取 Skill、额外审查或合规记录。只有指导更新或缺少相关细节时才重读。kiss-my-agent-setup 仍是另一个操作型 Skill，仅用于明确要求的 setup/check/configure/remove 工作。
如何选择 Master 并配置初始 Agents？
Setup 为缺失的 Master 字段补入 gpt-6-astra / high；当前 seed roles 显式使用 gpt-6-astra / medium。已有用户显式选择保持不变。Role wizard 只修改选定角色。静态检查不能证明 Host 有效配置，应在新任务中验证。
对子 Agent，Codex 会先解析显式 spawn 设置，再解析对应的 [agents] default，最后解析 parent；role 文件中的显式设置是最终 override。Current seeds 显式以 Astra / medium 覆盖 model 和 effort。Master 不是 role，role wizard 不能修改它。
对话向导只用于已有 role TOML：
$kiss-my-agent:kiss-my-agent-setup configure agents for this project
$kiss-my-agent:kiss-my-agent-setup configure global agents
Plugin update 和 setup 会保持每个已有角色不变。要显式把三个已有 KISS roles 设置为 gpt-6-astra / medium，请使用：
$kiss-my-agent:kiss-my-agent-setup configure agents in this project: for kiss_explorer, kiss_coder, and kiss_reviewer, set model to gpt-6-astra and model_reasoning_effort to medium
也可以直接编辑 .codex/agents/*.toml 或 $CODEX_HOME/agents/*.toml。向导不会修改 Master config，不会创建、删除或重命名角色，也不会硬编码会变化的 model catalog。
v0.1 setup CLI 去哪里了？
Contributor interface 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 CLI 或 repository-test evidence 不同，必须分别报告。
用户需要 Python 吗？
不需要。Plugin 安装、setup、check、remove、Agent 配置、正常使用和更新都不需要 Python、Node.js、Docker 或包管理器。但 Git-backed 安装或更新要求可用的 git executable 和 GitHub 网络访问。Python 3.11+ 只供贡献者使用；固定版本 Markdown 包只用于渲染和测试文档站点，只修改 Plugin/Skill 的贡献者可以把站点构建交给 pull-request CI。
已安装用户如何更新？会自动更新吗？
第一条命令立即更新，第二条只用于核验结果：
codex plugin marketplace upgrade kiss-my-agent
codex plugin list --marketplace kiss-my-agent
在已验证的 Codex 0.152.1 baseline 上，Host 会在启动时自动刷新默认的 unpinned Git marketplace，并重新安装已启用的 non-curated Plugin。KISS My Agent 自身没有 updater，其他版本的行为可能不同。上面命令完成后，应看到 kiss-my-agent@kiss-my-agent 为 installed, enabled，且版本与当前支持的 release 一致。更新改变已安装 Plugin 后，请启动新会话。
自动 refresh 和显式 marketplace upgrade 都只更新 Plugin 包，不会修改 project/global config、instructions 或角色文件。之前已 managed 的项目更新后可以运行 setup，刷新 managed instruction block、补齐缺失的模型、思考强度与功能默认值，并且只把 Installation 中说明的准确旧 marked Master pair 更新为 Astra/high；所有已有角色都直接保持不变。如需显式把已有角色设置为 gpt-6-astra / medium，请使用上面的准确限定 role-wizard prompt 或手工编辑角色 TOML。
显式 marketplace pin、rollback 与恢复 current unpinned channel 的命令见安装。
项目 setup 会配置所有项目吗？
不会。Project scope 只修改所选项目。全局 setup 必须明确运行 $kiss-my-agent:kiss-my-agent-setup set up globally，并可能影响加载该 Codex home 的所有项目。项目和全局 check/configure/remove 命令始终分开。
三个角色是固定的吗？
不是。它们是可编辑的 standalone starter-role files，不是封闭列表或强制团队。name 字段是身份，文件名只是约定，同一角色可以运行多个实例。默认由 Master 直接分配；只有合格的大型独立子系统可临时增加一层 lead。Fresh setup 会创建每个缺失的 current starter。任何已经存在的角色都立即归用户所有，setup 永不覆盖、迁移或判定其版本。Setup 已存在后，缺失 starter 是合法且 intentionally absent 的 catalog entry，不会重建。
已经有 config、AGENTS 或角色文件怎么办？
Setup 独立为每个缺失的 Master 字段补入 gpt-6-astra / high，为每个缺失功能字段补入带 marker 的 true，包括 features.context_management.experimental_mode。已有显式值（包括 false）保留。只有完整的顶层 gpt-5.6-sol / max pair、每个 key 准确出现一次且每行带准确的 # KISS My Agent managed marker 时，才成对更新为 Astra/high。已修改、未标记或不完整 pair 的已有字段继续归用户所有，只补真正缺失的字段。重复 assignment、无效 TOML 与 ownership 歧义属于 conflict。Setup 只修改选定的 project 或 global scope。
Setup、check 与 remove 只检查所选 scope 中 KISS 管理的 config、AGENTS paths，以及准确的 kiss_explorer.toml、kiss_coder.toml 和 kiss_reviewer.toml targets。不安全或无效的 managed target、bundled identity 不匹配、ownership conflict 或适用的 AGENTS.override.md 会在写入前停止。其他角色文件和另一 scope 不会被解析或协调：catalog warning 和 project-over-global precedence 由 Host 负责。配置角色时，已经点名的请求只解析点名目标；未点名的请求先列出 paths，随后只解析用户选中的角色。无效的未选角色不会阻塞操作。
请按报告中的原因和准确路径解决冲突，不覆盖用户工作，然后重跑同一个 setup 命令。完整策略见安装。
Remove 会删除什么？
只删除明确 scope 中带准确 marker 的当前默认配置 与任何准确的旧 marked Master pair、delimited managed AGENTS block，以及与 current、known v0.2.6、known v0.2.5 或 known v0.1 bundled seed 完全一致的角色文件。其他角色文件与不带 marker 的 config 都会保留。移除 setup 不会卸载 Plugin。 Remove 保留上下文子表及其他用户字段；只删除精确默认值和准确 marker 同时匹配的配置。
怎样确认它有效？
应分开证据：仓库测试、setup check、可信新会话中的 /skills 发现、窄范围实时 Smoke、更新测试和小规模真实 Pilot 分别支持不同结论。Final 表示按用户标准完成完整验收。详见测试。静态 PASS 不能证明模型行为或用户科研目标。
WSL 是 Windows 测试路径吗？
不是。WSL 只产生 Linux 证据。原生 Windows 兼容性需要 Windows runner 或原生 PowerShell 检查。Agent 原生用户 setup 避免依赖某种 shell 语言，但真实 Host 行为仍需要对应平台证据。
其他 Agent Host 可以使用吗？
这些思想可以适配，但打包后的 Plugin、config、roles 和测试以 Codex 为首要 Host。其他 Host 未被本 release 验证。