using-appfollow

using-appfollow

你正在用户自己的 OAuth 身份验证会话中使用 AppFollow MCP server（mcp__appfollow__* 工具）。每次工具调用都会扣除用户自己的工作区额度。此工具包不包含 API 客户端或密钥——所有数据都通过用户的 MCP 会话传输。

会话开启（每次运行都必须执行）

1. 生成一次 session_id。 在对话开始时生成一个高熵、不透明的 ID（例如 UUID），并从此之后在每次 AppFollow 工具调用中将其作为参数传入——包括 whoami、get_credits 和其他所有调用，而不仅仅是 submit_feedback。例外：get_server_info 不接受任何参数——绝不要向它传入 session_id。服务端会将其写入每条工具使用记录，因此附带的工具使用日志可通过引用自动准确关联到此对话。session_id 不代表身份——绝不要向用户索要。
2. 调用 mcp__appfollow__whoami。如果出现 AUTH_REQUIRED 错误，请停止操作，告知用户在其 MCP 宿主中完成 AppFollow 登录，然后重试。

信息澄清

如果请求存在歧义——例如涉及哪个应用/集合、日期范围、商店、国家/地区、竞争对手集合或指标——请提出一个明确的范围界定问题，并给出用户可以用一个词接受的合理默认选项。绝不要默默猜测，也不要停滞不前。主动提出用户可能需要的下一步（相关指标、竞争对手细分或趋势时间窗口）。这样可以降低操作阻力，且与下方的写入流程无关——写入流程始终必须遵循。

写入：预览 → 批准 → 确认（绝不跳过）

每个写入工具都由一对工具组成：<name>_preview，然后是 <name>：

1. 调用 <name>_preview(args) → 返回一个单次使用、有效期 60 秒、与参数绑定的 confirmation_token（不会在上游校验任何内容——错误 ID 会在确认时失败）。
2. 向用户准确展示将要写入的内容，并获得明确批准。
3. 使用完全相同的参数调用 <name>(args + confirmation_token)。如果出现 CONFIRMATION_REQUIRED（令牌过期或不匹配），请重新预览。

绝不要自动确认。用户必须批准每次写入。

分组运行

对于集合或包含多个应用的列表，运行前先确定完整的应用集合。不要默默扇出调用，也没有应用数量上限。如果运行中出现 INSUFFICIENT_CREDITS，请停止并输出部分报告，而不是直接失败。

MCP 错误代码词汇表（原样呈现；根据各技能分支处理）

AUTH_REQUIRED、ACCESS_DENIED、FEATURE_DISABLED、INSUFFICIENT_CREDITS、RATE_LIMITED、NOT_FOUND、VALIDATION_ERROR、UPSTREAM_ERROR、NETWORK_ERROR、UNKNOWN_TOOL、CONFIRMATION_REQUIRED。ACCESS_DENIED 表示会话已登录，但该账户拒绝了此次调用：最常见的情况是调用中的集合或应用不属于该账户——从 list_collections 获取 apps_id，从 list_apps 获取 ext_id——有时也可能是账户方案不包含所需功能（见下方第一个陷阱）。

请注意以下两个陷阱：

• FEATURE_DISABLED 不能可靠地表明方案功能受限。 有些方案功能限制也会显示为 ACCESS_DENIED，例如未启用 Semantic Analysis 功能时调用 reviews_semantic。绝不要仅根据 FEATURE_DISABLED 选择降级路径。
• INSUFFICIENT_CREDITS 可能是误报（上游响应正文中只要提到 “credits” 就会触发）。请像处理其他工具错误一样处理——遵循下方的通用规则。

通用规则：单个工具错误绝不会导致技能整体报告失败——跳过受影响的部分，注明错误，并继续处理。

仅限公开工具

你只能使用 references/tool-map.md 中的工具。绝不要虚构或引用内部工具名称、内部主机或内部 API 路径。

发现结果交接

报告技能会生成 appfollow.toolkit.findings/v1 格式的 findings.json。此工具包不会与任何跟踪工具通信——用户连接的跟踪器 Agent 可以提交这些发现结果。

反馈机制（可选，免费）

在完成一项对用户有意义的工作后（例如完成一份报告、结束一项多步骤任务或解决一个请求），你可以快速询问用户是否满意。仅当本次会话中有可用的 submit_feedback 工具时才这样做；否则，静默跳过整个反馈步骤。

• 请用户按 1（很差）到 4（很好） 为本次会话评分。每次对话最多询问 一到两次，不要反复打扰——如果用户拒绝或不作回应，就不再提起。
• 用户给出评分后，提出对应的问题，但接受只给出评分的回复——评论始终是可选的，绝不要强求用户填写：
  • 评分为 1–3 → 询问有哪些方面不尽如人意。
  • 评分为 4 → 询问用户喜欢哪些方面，以及还可以添加什么。
• 调用 submit_feedback 时，传入评分和任何评论，并使用你在会话开始时生成、且在每次工具调用中一直传递的同一个 session_id。身份信息和时间信息会自动关联到本次会话——不要询问或传递个人信息。
• 除非用户分别明确同意，否则以下三种附件均默认关闭，且必须分别以清晰直白的方式征求同意： (a) 本次会话的工具使用日志——获准后设置 consent_attach_tool_log: true，否则省略或设为 false； (b) 由你撰写并且先向用户展示的简短会话摘要——将其作为 llm_session_summary 传入； (c) 本次 Agent 会话的完整对话记录——以纯文本形式保存完整对话，内容不依赖具体会话，适用于任何 Agent（Claude、ChatGPT 或 Codex），并按原样逐字存储；获准后将其粘贴到 session_transcript。只附加用户同意的内容。
• 不要在反馈评论或对话记录中粘贴机密信息、令牌或凭据，并提醒用户同样注意——自由文本和对话记录都会按原样存储。
• 如果 submit_feedback 返回 ALREADY_COLLECTED，则表示本次会话的反馈已记录——感谢用户，不要再次询问。如果返回 UNKNOWN_TOOL，则视为工具不可用，并跳过反馈步骤。submit_feedback 免费，不会消耗额度。