recoup-platform-build-os

Recoup — 构建音乐工作区

重点不在文件夹，而在于搭建一个既能自我管理、又能自我改进的系统。 它会让自身状态始终保持最新（永不过时），并且随着时间推移不断提升自身的工作能力：积累知识，将重复工作提炼成新技能，并改进自身机制。请始终以此为目标推进以下各个阶段；这些结构的存在只是为了服务于这一目标。

具体来说，要把启动输入转变为一个持续运转的操作系统：包含文件夹和文件结构、可自我管理的 CLAUDE.md（同步到 AGENTS.md）、plugin/ 目录（可原地安装的插件，内含技能）、由只读 doctor 提供支持、永不过时的 janitor、复合学习循环，以及自我改进循环。插件默认命名为 {DOMAIN_SLUG}-os，并包含适用于 Claude、Cursor 和 Codex 的清单／适配器。

此构建技能供运行它的 Agent 使用。请按顺序完成各个阶段。不要半途而废——要一直推进到操作系统可用，然后再汇报。进入每个阶段时阅读相应参考资料。

Recoup 专项说明 — 选择实际的音乐工作流

本领域涵盖音乐业务，包括唱片公司、词曲作者、出版商、管理方、录音作品所有者、遗产管理方和获授权的顾问。在阶段 0 中识别其核心记录；切勿为了处理作品或版税事务而虚构艺人账户。

• 根据实际工作选择主干。 艺人／发行运营使用 artists/ 和各艺人名下的发行记录。出版业务使用 compositions/ 和 parties/。审计、版税对账和收购使用包含范围／证据／阶段记录的 cases/。仅使用有实际工作支撑的文件夹；名单为空也完全合理。
• 每个仓库仅设一个获授权的工作区。 在选定的私有工作区中保存私人协议、结算单、标识符和收据。公开的插件示例必须使用合成数据。本地案件只有在受支持的保存操作能够读回数据后，才算托管目录的一部分。
• 在适用时保留现有的艺人约定。 将已核实的艺人映射到 artists/{artist-slug}/RECOUP.md，并填写 artistName、artistSlug 和实际的 artistId。发行记录保存在各艺人的发行目录下。切勿虚构 ID。仅涉及作品的案件可使用本地案件 ID，并保留缺失的 ISRC/ISWC 值。
• 使用现有访问方式。 已通过身份验证的 MCP 连接可以提供账户范围信息。REST 可使用提供的环境凭据；不强制要求特定于测试框架的环境文件。仅在所请求的托管操作需要时连接账户。切勿将 MCP OAuth 凭据复制到文件中。无需登录即可审阅／接收文件。
• 为每种对象编写 operations/sync.md。 仅当发现的 API 实际支持相关字段时，托管的结构化记录才具有权威性。私有工作区用于保存证据、尚未解决的候选项、计划和源版本。对于不受支持的字段，应如实记录，而非声称每条本地记录都已存在于数据库中。对于实际艺人名单，使用受支持的名单读取功能；如有请求，则优先通过 API 创建艺人；艺人数量为零并不意味着可以引入无关人员或出版商。
• 复用专用的 Recoup 技能。 目录导入、组织整理、合同说明、审计、对账、登记、问题处理和交易审查均保留各自的阶段边界。歌曲署名和发行元数据仍属于检查项。本地衔接逻辑仅协调明确要求的阶段；绝不能将审查转变为对外通信。
• 将机密信息保存在版本控制材料之外。 如果需要 REST 访问，则创建 .env.example 以说明变量名称，并创建 .gitignore 以排除实际凭据。服务提供方的成员资格、音乐业务委托和软件权限是彼此独立的事实。
• 根据所选主干配置维护工作。 填写 doctor/dashboard 模板，注明实际实体文件夹和工作流。出版或会计工作区不应仅仅因为没有艺人、估值或定期任务而无法通过健康检查。

阅读 references/blueprint.md 了解精简结构。唱片公司的发行机制仍可使用；但不要将其强加给所有出版商或目录顾问。

运行信念（适用于构建的每个 OS）

以下每条信念都服务于同一个目标：打造一个自我管理（保持最新）并且自我改进（不断积累知识、能力和自身机制）的系统。

1. **将积累的内容与流转的内容分开。**积累的内容 = 每次使用都会改进的可复用资产（模板、知识库、技能、证明）。流转的内容 = 在各阶段之间流转的实例（交易、工单、发布、实验）。建立反馈机制，让每个流转实例都能回馈到某项积累资产中。
2. **永不过时。**管理状态是 Agent 的职责。每当有新输入到达，或用户在 OS 中进行操作时，所有应当更新的文件/文件夹都必须在同一轮中更新。清理技能 + 定时任务是安全网。
3. **让学习不断积累。**每次会话都让系统变得更聪明——将决策、反复出现的答案和模式记录到知识库中。绝不重复解决同一个问题。
4. **将已验证、可重复的工作转化为技能。**完成工作后，确认是否会再次执行或需要维护。如果是，就先将经过验证的流程整理成分阶段、经过验证的技能，再放入 plugin/skills/。一次性工作留在 work/（带日期）中——绝不将其变成独立的顶层文件夹。
5. **自我说明。**每个文件夹都要说明自身用途；CLAUDE.md 负责说明新内容应放在哪里，以及如何让系统保持最新。
6. 证据胜于信心。“已完成”“一致”和“可访问”应由可检查的依据来判定——例如运行 {domain}-doctor、技能验证结果或可访问的触发器，而不是凭 Agent 的感觉。OS 也应随着时间推移而改进自身（{domain}-reflect），而不只是改进其内容。

阶段 0 — 深入了解项目（始终优先执行）

阅读 references/domain-inference.md。

• 摄取所有启动输入（文件、转录文本、提示词）。如果存在文件，请完整阅读。
• 确定领域原型和核心工作单元（例如：咨询 -> 交易/客户，产品 -> 功能/发布，唱片公司 -> 艺人/发布，研究 -> 问题/实验）。
• 如果输入丰富，则从材料中推导结构。如果输入稀疏（只有提示词），则运用最佳判断：推断领域，预测项目所需的实体、阶段、资产、例行工作和指标，并提前准备，而不是等待——但应将这些准备整理为轻量级根目录中的占位内容和子文件夹（参见阶段 1），而不是额外创建顶层目录。
• 编写一份简短的理解概要：领域、核心工作单元、生命周期阶段、关键实体、积累资产、重复性任务（技能候选项）、指标和可能用到的外部工具。
• 只有在重要事项存在歧义时才向用户确认概要；否则继续执行。

阶段 1 — 设计分类体系

阅读 references/blueprint.md。

• 从循环维护的少量核心内容着手：流转存储（暂存流水线文件夹 + clients/ / artists/ / features/ 之类的实体文件夹）、可累积的存储 knowledge/ 和 library/、work/（按项目归档的非重复性产出）、artifacts/（已定稿的重复性产出，例如仪表板）、plugin/（原位插件）以及 operations/（例行任务、同步、健康检查、改进）。
• 仅当领域目前确实有相关内容时，才添加可选的顶层文件夹：reference/（权威资料/来源）、proof/（成果）、content/（实际的内容创作流程）、business/（法律/财务/指标）。拿不准时就先不添加，之后只需运行一次 mkdir 即可。
• 所有顶层文件夹名称都保持为一个小写单词（用 operations，而不是 operating-system；用 knowledge，而不是 knowledge-base）。可按领域的语言重命名，但名称必须是单个单词。（plugin/skills/ 中的技能文件夹继续使用 kebab-case — 这是另一种约定。）
• 不要不加判断地照搬整套结构，也不要把一次性工作提升为顶层文件夹——临时任务放在 work/；只有重复发生或需要维护的工作才成为 plugin/ 中的技能。将过度准备的内容放进子文件夹和占位文件，而不是创建一排空的顶层目录。

阶段 2 — 搭建结构和核心

• 只创建分类体系所需的文件夹（保持根目录精简）。为每个不言自明程度较低的文件夹创建简短的 README.md 占位文件，说明其中应存放什么。
• 根据 assets/dashboard.html.tmpl 编写 artifacts/dashboard.html（使用 HTML，而不是 md）。初始化 operations/health.md（留空 — 由 {domain}-doctor 填写）和 operations/improvements.md（为 {domain}-reflect 记录表创建标题）。
• 根据领域定制 assets/CLAUDE.md.tmpl，编写具备自我管理能力的 CLAUDE.md（归档决策树、自动管理循环、永不过时约定、从重复工作到技能的规则）。阅读 references/self-management.md，了解约定必须包含哪些内容。
• 创建指向 CLAUDE.md 的符号链接 AGENTS.md（ln -s CLAUDE.md AGENTS.md），让查找任一文件的 Agent runner 都能获得相同的核心内容。如果不支持符号链接，则创建一个写着“参见 CLAUDE.md”的 AGENTS.md — 但优先使用符号链接。

阶段 3 — 积累可复用资产

• 填充 library/（可重复使用的空白工具，例如模板、脚本、检查清单）和 knowledge/（查阅后即可获得既定答案的内容，例如常见问题、见解、决策、标准操作流程）。经验法则：如果你会用它来制作某样东西，就放在 library/；如果你会查阅它来做决定，就放在 knowledge/。
• 从输入中提取这些材料。如果输入稀少，就为该领域准备合理的入门模板，并标注为“草稿 — 请确认”。

阶段 4 — 编写技能（原位的 plugin/）

阅读 references/skill-authoring.md 和 references/skillifying-work.md（晋升工作流）。

• 除非用户明确指定名称，否则从领域派生插件名称，格式为 {DOMAIN_SLUG}-os（kebab-case）。所有清单中都使用同一个名称。
• 在原位将 plugin/ 搭建为真正的插件：根据 assets/claude-plugin.json.tmpl 创建 plugin/.claude-plugin/plugin.json，根据 assets/codex-plugin.json.tmpl 创建 plugin/.codex-plugin/plugin.json，并创建 plugin/skills/ 目录。Codex 清单必须包含 "skills": "./skills/"；参见 references/packaging.md。
• 创建 .agents/skills，将其设为指向 ../plugin/skills 的符号链接，以便 Cursor 和 Codex 发现相同的项目技能。如果不支持符号链接，则将 plugin/skills/ 复制到该位置，并注明这是一个兼容性镜像。
• 对简介中提到的每项重复性任务，编写 plugin/skills/{name}/SKILL.md（frontmatter 中包含 name 和带有真实触发短语的 description，随后是引用工作区路径的祈使步骤）。
• 始终包含维护技能（OS 的反馈器官），并根据模板生成：
  • doctor（assets/doctor-SKILL.md.tmpl）——只读验证界面（健康评分 + 写入 operations/health.md 的待办清单）；janitor 和构建报告均以此为前置条件。还要根据 assets/doctor.py.tmpl 生成 operations/doctor.py（填入 PIPELINE/ENTITY/slug），作为确定性的快速路径——让机械检查随构建一同交付，而不是以后再重新发明。
  • janitor（assets/janitor-SKILL.md.tmpl）——运行 doctor，然后协调并修复安全的问题。
  • compound-learn 技能（assets/compound-learn-SKILL.md.tmpl）——每次工作会话结束后，将决策/答案/模式记录到 knowledge/。
  • reflect 技能（assets/reflect-SKILL.md.tmpl）——改进 OS 本身（技能、路由、检查、模板），并记录到 operations/improvements.md；预算为 50/50。
  • skillify 技能（assets/skillify-SKILL.md.tmpl）——将已验证的可重复工作晋升为经过验证的暂存技能。
• 还要包含一个编排器技能，将自动管理循环设为一个触发器，并命名为 {domain}-intake。
• **路由保持精简：**在技能数量较少时，依靠每项技能的 description 进行路由；只有当技能数量增长到描述重叠，或 doctor 的可达性检查发现歧义时，才添加 plugin/skills/RESOLVER.md（触发条件 -> 技能表）。
• 仅为重复性或需要维护的工作编写技能——一次性构建应放在 work/ 中，而不是创建临时技能。对于从已完成工作中创建的技能，请遵循 skillify 循环：证明来源、提取可重复流程、暂存到 work/、使用最适合该领域的强有力检查进行验证、移动到 plugin/skills/ 前先征求同意，然后重新打包。

阶段 5 — 打包插件

阅读 references/packaging.md。

• 先运行 {domain}-doctor——打包必须以报告干净（或已解释清楚）为前置条件。
• 工作区的 plugin/ 目录本身就是可安装的插件——无需复制。验证以下内容：每个 plugin/skills/*/ 都有 SKILL.md；两个插件清单都是有效的 JSON，且名称均为 {DOMAIN_SLUG}-os；任何 description 中都不得包含尖括号；plugin/skills/ 中没有多余的非技能文件夹；.agents/skills 指向或镜像 plugin/skills/。打包前修复所有问题。
• 先将 plugin/ 的内容 zip 到 /tmp，然后将 .plugin 复制到输出文件夹并提供安装。

阶段 6 — 配置永不过时的计划任务

• 尝试创建一个定时任务来运行 janitor 技能（默认每周一次），让工作区即使在用户没有查看时也能自行协调一致。
• **如果没有可用的计划任务工具，或用户拒绝：**这不算失败。在 operations/routines.md 中记录预定频率，并从 assets/janitor-schedule.tmpl 中放入一个可直接使用的计划任务配置（GitHub Actions / cron / launchd / agent-runner 任务），这样日后启用时只需复制，无需重新研究。操作系统仍然是完整的 — janitor 也可以按需运行 — 但在启用计划任务之前，doctor 会持续报告一项较低级别的“计划任务已启用”问题，因为“在无人查看时自行协调一致”只有在它确实能无人值守运行后才成立。
• 不要因为计划任务而阻塞构建或将其视为“未完成”；把它当作唯一的可选步骤。

阶段 7 — 报告

运行 {domain}-doctor，并将其评分作为构建的验证依据 — “完成”意味着 doctor 运行结果干净（或问题已说明），而不是凭感觉判断。总结：创建的结构、编写的技能、生成的插件、设置的计划任务，以及健康评分。列出哪些内容是推断所得、哪些已确认，以便用户纠正任何假设。

防护原则

• 不要编造必须由用户确认的领域事实 — 将推断内容标记为“草稿 — 待确认”。
• 不留下过时内容：如果修改了项目，请在同一轮中更新仪表板、看板以及受影响的任何 README。
• 优先改进模板或技能，而不是只处理单个实例。