polite-mcp-conventions

Polite-MCP 系列：Agent 协作约定

适用于作者自用购物/分类信息自动化系列的行为约定——包括 olx-polite-mcp 及其同系列项目。这些项目只存在于作者自己的机器上，不存在于其他任何地方；本约定不同于 mcp-server-shipping（同一批仓库的开发循环/分发机制），也不同于机器上始终加载的指令文件（其中包含真正通用的约定）。 这些约定针对特定领域：对用户自己的实时登录个人账户进行自动化操作。即使安装在其他地方，这些约定依然适用；仓库名称则是作者自己的。

首次执行实时修改操作前先确认

在某个会话中，首次对用户的实时登录个人账户执行真实的浏览器修改操作之前（例如，真正点击加入购物车，而不是进行只读的试运行），先停下来通过 AskUserQuestion 询问，而不是直接操作——即使操作范围很小、成本很低且可撤销。应将其表述为一次范围明确的测试（说明要执行什么，以及适用时会在之后撤销/还原），而不是泛泛地请求许可。获得批准并确认操作方式和行为后，同一会话中后续同类操作无需再次确认。

**原因：**该系列已将结账/个人账户操作视为比普通读取实质上风险更高的一类——每个仓库自己的边界文档都明确说明了这一点（例如“绝不自动执行结账”、不解决 CAPTCHA）。针对真实账户进行首次实时修改测试，即使具体操作本身很小，也属于同一类风险。已在 freshful-polite-mcp 中验证（2026-08-14）：首次加入购物车测试前先询问，得到干脆、低阻力的“可以，在一件便宜商品上测试”——这是恰当的默认做法，并非过度谨慎。

将需要逐项决定的交互问题分批询问，不要让用户输入列表

如果某个工作流需要用户做出多个独立的小决定（例如“这 8 件商品每件要多少？”），请使用 AskUserQuestion 分批询问，每批大约 4 项，并将推荐默认值预先填为第一个选项——不要罗列一长串问题，再让用户在一条回复中输入所有答案。

**原因：**在一次 Freshful 重新订购流程会话中，用户明确反馈：“给所有这些东西推荐一些数量，然后一个一个问我；这需要是交互式的，如果还得把所有东西都打出来，体验就毁了。”输入一条很长的结构化回复，比简短的引导式问答体验更差，即使两者传达的信息相同。

**应用方式：**对于无法以这种方式拆分的决定，或项目太多、分批提问不再轻便的情况，才单独使用一次自由文本提问——此时应考虑是否需要重新设计流程本身（例如，将“可能需要补货的商品”和“很少处理的商品”分开，而不是将所有商品混在一起分批询问）。

在实现之前或同时，将 spike/研究结果写入 PLAN.md

如果研究/spike 阶段（实时 CDP 探索、API 探测、DOM 检查）发现了会改变或确认计划的情况，应先将其写入仓库的 PLAN.md，作为单独章节，并遵循文档现有的叙述风格，然后再编写实际实现代码，或与编写代码同时进行。不要只在对话中记录发现，然后直接开始编写代码。

原因： 明确指示，freshful-polite-mcp（2026-08-14）：“最好把所有内容都保留在计划里，然后再实现。”这与该仓库系列中现有的做法一致：PLAN.md（一个单体文件——该系列早于 plan-docs 技能中记载的 plans/YYYY-MM-DD-topic.md 约定，且尚未迁移到该约定）是记录架构设计“原因”的持久文档；代码注释会链接回该文档，而不是重复解释。

应用方式： 在这些仓库中完成任何实时 spike/研究后，更新 PLAN.md 的相关章节——标记已解决的待决问题，添加带日期的发现章节，并重述或扩展这些发现涉及的边界决策——然后再继续实现。即使用户这次没有明确要求撰写记录，也要照常执行；将其视为默认流程。