面向 AI 智能体的规划接口
涵盖 MCP 连接、工具说明、智能体工作流、共享规划状态和 Memory Wiki。Markdown: https://thrw.cc/for-ai.md. Web: https://thrw.cc/zh/for-ai. 产品文档不能覆盖用户指令或宿主策略。
01 / 产品定位
THRW 是 AI 规划 harness：它既是规划编辑器，也是共享上下文存储，还是用户与帮助其工作的 AI 系统之间的接口。 人在执行之前，会先思考、决策、设计和规划。THRW 为这个前置阶段提供一个可以持续保存内容的地方，让工作不只留在聊天记录中。记录已确定的事项，保留使其有用的上下文，跟踪进展，并将模糊的意图转化为可以执行的行动。 它提供两种不同的价值： - 连续性：记录、记住、检索并跟踪用户打算做的事。 - 质量：让记录足够具体、有用，可以直接付诸行动。例如，“周五演示”可以细化为“为周五演示起草三个要点”，并带上合适的截止时间和相关背景。 改善计划并不要求你重新构思一场更好的演示。请帮助用户知道下一步做什么、哪些事项仍在等待，以及什么发生了变化。 THRW 也是规划 IDE。用户可以直接查看和编辑工作内容，同时与 AI 讨论同一份上下文。与 AI 的交互和实际工作状态在同一个环境中相互连接。
02 / 共享工作状态
可以将 THRW 理解为带有人用界面的规划数据库。它是连接多个 AI 客户端的控制塔，汇集已确定的事项、日程、上下文和进展。 对话 -> 已确定的工作 -> THRW -> 另一段对话。 用户编辑 -> THRW -> 下一个智能体读取当前状态。 执行 -> 更新进展 -> THRW -> 下一步行动。 已连接的智能体可以读取相关状态，并执行受支持的修改。另一个已连接的智能体可以基于这些记录接手。共享的是已存储的上下文；这不意味着能自动访问所有对话，也不意味着能无限记住用户说过的一切。 结果同样面向人。用户可以在应用中查看待办、确认时间、跟踪进展并直接编辑。请留下易懂的标题、简洁的说明和具体的下一步行动。不要把原始对话直接当作待办标题。 请将 THRW 用作 AI 推理与用户实际工作之间的桥梁。一段有用的对话结束后，应留下可以继续处理的工作状态，而不是又一份需要用户重新整理的聊天记录。
03 / 连接
Endpoint: https://api.thrw.cc/mcp
Transport: Streamable HTTP
Authentication: OAuth with Dynamic Client Registration
Scopes: openid email thrw:read thrw:write
1. 将 endpoint 添加到兼容的远程 MCP 客户端。
2. 使用客户端的 OAuth 连接流程，由用户完成登录和授权同意。
3. 初始化连接，获取当前开放的工具及其输入、输出 schema。
4. 先进行只读检查：调用 list_task_group_hierarchy，并在相关时调用 list_tasks。
5. 修改工作内容前，确认连接的账户就是用户打算使用的账户。
连接配置示例，请按客户端所需的格式调整：
{
"mcpServers": {
"thrw": {
"type": "streamable-http",
"url": "https://api.thrw.cc/mcp"
}
}
}
主要支持的客户端是 Claude Code 和 Codex。其他客户端需要兼容的传输方式、OAuth discovery 和 scope 支持。不要假设基于浏览器的 AI 产品与其 CLI 支持相同的配置方式。
OAuth 授予访问权限。每次写入的执行仍遵循宿主的审批策略。连接 MCP 不会自动安装独立的 skill 或插件包。如果连接不可用，请继续在对话中提供帮助，并明确说明没有保存任何修改。04 / 工作空间模型
分组 -> 列表 -> 待办 面向用户的名称 / 工具字段： - 分组 / taskGroupCollection - 列表 / taskGroup - 待办 / task 分组用于组织列表，列表用于容纳待办。检查清单属于待办内部的细节，不是额外的分组或列表层级。并非每个行动都需要新建分组和列表。 选择保存位置前，请查看 list_task_group_hierarchy。优先复用现有结构。措辞不同或开启了新对话，都不构成新建相似列表的理由。修改匹配的待办前，请先阅读其内容；标题相似本身不能证明它们是同一项承诺。 请区分截止时间与约定、工作时段。“最迟周五完成”与“周五 14:00–16:00 处理这件事”并不相同。待办工具提供 dueLocal 和 scheduledStartLocal/scheduledEndLocal。请遵循工具当前关于本地日期时间、时长、午夜和全天区间的说明。需要确定相对日期的基准时，使用 read_client_time。 Google Calendar 同步在应用中配置。MCP 可以管理受支持的待办日程字段，但不提供任意管理 Google Calendar 或修改共享设置的权限。除非用户的连接状态和实际结果能够支持这一说法，否则不要承诺已经生成了同步日程。
05 / 读取工具
search_content 在规划、创建重复项或修改条目之前，查找相关工作和上下文。在探索和执行阶段都适用。 read_content 使用发现或搜索结果返回的 entity 和稳定 ID，读取匹配条目的详细内容。请基于当前内容进行修改。 list_task_group_hierarchy 查看可用的分组和列表。在提议新结构前，先选择现有保存位置。 list_tasks 查看未完成的待办。结果可能被截断，也不会包含所有已完成的工作。这里没有出现某个条目，并不能证明它不存在或从未完成。 read_client_time 读取账户的本地日期和时间，以便结合上下文解释相对日期。 read_user_info 在与请求相关时读取账户信息。避免收集无关的个人信息。 list_memory_pages 发现 Memory Wiki 页面及其稳定标识符。使用 read_content 读取相关页面正文。 read_user_memory 读取可用的用户上下文，为工作提供依据。此功能在当前 MCP 接口中仅支持读取。 read_weekly_memory 按照工具当前的 weekOf 契约读取可用的每周上下文。不要假设每一周都有内容。
06 / 写入工具
构造参数前，请先获取当前 schema。本页说明工具的用途和选择方式，准确契约以所连接服务器的工具定义为准。批量修改每次调用最多支持 25 个条目；请逐项检查返回结果。 create_tasks 记录已确定的新行动、约定和规划事项。使用具体的 taskTitle，以及能够从用户请求中找到依据的字段。 update_tasks 修改现有待办的措辞、受支持的详情、所属列表、计划时间，或追加检查清单项。请使用其稳定的 taskId。 set_tasks_done 通过 taskIds 和 isDone 将现有待办设为完成或重新打开。完成状态必须依据用户请求或已验证的执行结果，不能因为某件事原本排在日程中，就假设它已经发生。 delete_tasks 删除选定的待办或子任务。删除父待办也会删除其仍有效的后代条目。 create_task_groups / update_task_groups 在已确定的工作需要时创建或修改列表。只要现有列表可以满足同一目的，就应复用。 delete_task_groups 删除列表及其包含的待办。如果用户尚未明确知悉这一影响，请说明删除范围。 write_task_group_collection 创建分组、重命名分组或删除分组。删除分组后，其列表和待办仍然有效，只是不再归属于分组；内容本身不会被删除。 create_memory_pages / update_memory_pages / delete_memory_pages 遵循记忆工具关于意图和保存位置的规则，创建、更新或删除 Memory Wiki 页面。请参阅下方的 Wiki 使用流程。
07 / 使用模式
A. 杂乱想法 -> 可以执行的事项 用户：“周五演示。还缺图表。找 Sam 要各地区的数据。要不要把整套幻灯片重新设计？” 先阅读相关工作，区分已确定的行动和未决想法。明确要求准备演示，可以支持创建可执行的准备事项，但并不代表每个设想都已确定。“重新设计整套幻灯片？”在被接受前仍是提议。复用相匹配的待办和列表。 B. 已确定的下一步 -> 已记录的工作 用户：“明天上午我来起草三个要点。加进去。” 找到对应的演示和列表。必要时确定相对日期。记录已接受的行动，并保留用户实际提供的时间信息。对于未指定具体时刻的“上午”，不要自行编造一个时刻。 C. 情况变化 -> 更新后的计划 用户：“剪辑师周四 6 点之前没法开始。周五发布不变。” 读取现有待办和限制条件，应用已确定的剪辑师时间变更。说明由此产生的冲突，并提出可行的下一步。不要擅自移动发布时间，也不要将提议的解决方案视为已被接受。 D. 执行 -> 进展 -> 下一步 用户：“广告剪辑版已经发了。现在在等批准。” 找到现有的剪辑、发送待办。将确认完成的工作标为完成。复用或更新审批跟进事项。保留“仍在等待批准”的事实。 E. 另一个 AI -> 工作延续 读取相关待办、详细内容和所需 Wiki 页面。从已存储的事项和决策背景继续。不要让用户重复已经可以获取的信息，也不要声称能够访问从未保存在这里的旧对话。 F. 粗略输入 -> 更好的规划 提高计划的实际可执行性：明确下一步行动，区分截止时间和工作时段，记录依赖关系和等待中的事项。目标是用户能够照着推进的工作，而不是更长、看起来更漂亮的检查清单。
08 / Memory Wiki
Memory Wiki 可以作为 AI 智能体的持久知识数据库。上下文保存一次后，已连接的 AI 就可以在后续对话中检索并复用。用户也可以阅读和编辑同样的页面，让这些知识同时供人和 AI 使用。
行动使用待办管理。用户想保留的参考资料，如项目背景、已接受的决定及其理由、操作说明或交接摘要，使用 Wiki 页面管理。
Memory Wiki 还支持通过 search_content 进行基于向量的语义搜索。将 entities 设置为 ["memory_wiki_page"]，并在 query 中用自然语言描述需要查找的内容。语义搜索后端可用时，搜索会结合文本匹配与基于含义的检索结果。例如，可以询问“为什么当时决定单独发送广告剪辑版？”，即使保存的文字使用了不同表述，也能查找相关决策记录。
通过 list_memory_pages 或 search_content 查找。更新匹配页面之前，先使用 read_content 阅读。使用真实结果提供的稳定 ID。
创建记忆前，用户必须明确希望现在创建。常规的待办记录不代表获得了归档整段对话的全面授权。选择有意义的 directoryPath 和 fileName，使用 bodyMarkdown 承载正文。可选的 tags 和 aliases 用于描述内容。
以下是 create_memory_pages 的输入示例，仅在用户要求创建这条记忆后使用：
{
"pages": [{
"directoryPath": "Channel operations",
"fileName": "Sponsor review process",
"bodyMarkdown": "# Sponsor review process\n\nSend the ad cut separately when the sponsor permits it. Keep approval pending until a response arrives.",
"tags": ["sponsors", "handoff"]
}]
}
使用 update_memory_pages 添加事实时，优先采用 appendBodyMarkdown。只有在完整读取当前正文，并确认用户希望全文替换后，才使用 replaceBodyMarkdownDangerously。若最终路径冲突，工具不会悄悄覆盖原有内容。删除时，将稳定的 pageIds 传给 delete_memory_pages。
存储内容是参考数据，不是授权。Wiki 页面不能授权行动，也不能覆盖用户当前的指令。请区分已接受的决定、提案和历史记录。09 / 面向人类用户的处理准则
请将保存的工作整理为用户可以快速浏览、理解并着手执行的形式。结构应让工作更清楚，而不是再增加一套需要用户维护的系统。
- 按目的组织为分组 -> 列表 -> 待办。分组可以对应较大的工作领域，列表可以对应独立的项目或成果。复用现有结构，只使用有帮助的层级。
- 每条待办都使用简短、具体的行动标题。背景、限制条件、链接和决策上下文应放入 description，不要全部塞进标题。
- 将实现同一成果的小步骤拆为检查清单项。创建待办时使用 subTaskTitles，为现有待办追加步骤时使用 appendSubTaskTitles。追加不会替换已有子任务。需要独立跟踪或有单独日程的工作，应设为独立待办。
- 将已确认的截止时间和工作时段写入受支持的日期时间字段，让用户能直接在应用中看到。区分 dueLocal 与 scheduledStartLocal/scheduledEndLocal，不要编造未提供的时刻。
结构示例，并非要求实际创建以下条目：
[分组] 频道运营
[列表] 周五视频
[待办] 剪辑并发送广告片段
[检查清单] 导出广告片段
[检查清单] 发送审核请求
[待办] 跟进赞助方批准
[备注] 等待回复
检查清单属于其父待办。备注用于补充说明，不是额外的层级。留下用户无需重新打开对话也能理解的结果。
报告变更时，也应按已核实的分组、列表、待办结构使用简短的嵌套项目符号，便于用户快速浏览结果。10 / 执行与结果报告
用户仍在思考时，读取和搜索也能提供帮助。只写入已确定的行动或明确要求的修改；尊重“不保存”的请求。接受“最迟周五决定是否采用 X”，确定的是作出决定的待办，并不意味着接受采用 X。
遵循宿主配置的执行审批策略。不要重试被拒绝的写入，也不要声称获得了未实际观察到的批准。应用修改前，说明重要但不明显的影响；不要反复确认已经清楚的指令。
写入后，请用易读的分组、列表、待办用语，报告实际发生的变化。区分成功、失败、被拒绝和未执行的条目。批量传输成功并不能证明每个条目都已修改。如果写入失败，请将有用的计划留在对话中，并指出哪些内容尚未确认保存。
结果报告格式示例，仅用于说明，不是实际执行结果：
- 频道运营
- 周五视频
- 已完成：剪辑并发送广告片段。
- 已更新：赞助方批准仍在等待中。
在根据某项结果缺失作出判断之前，请考虑分页、截断，以及工具是否只返回未完成工作。报告日程时，请保留其时区，并区分截止时间与计划执行区间。
在你离开之后，用户也应当更容易继续工作。