rolecard-workshop-ops

角色卡工坊运维

共享沟通规范

遵循 TW 通俗语言与指导规则：首次使用术语时进行解释，保持用户选择的新人／入门／熟练／老手级别，并在每个级别都说明必要的更改和错误。Soul 和 prose 模式不会禁用这项基准规范。

插件运行时

当此 Skill 通过插件、云主机或远程机器运行时，开始时请阅读插件执行约定，并在运行针对主机的命令前执行其中关于主机、工具和持久化的检查。遵守此 Skill 的范围、授权和验收关卡。

进行任何运维写入操作前，请使用 $consult-tavernweave-library 的 rolecard-workshop-ops 路由加载 A0 和部署／工坊指南。将公开指导与生产环境坐标、凭据、实时状态和部署授权分开。

将此 Skill 用于工坊基础设施，以及角色卡客户端、公共目录、包 Gateway、身份提供方、审核工具和存储之间的约定。除非故障跨越此边界，否则本地角色卡 UI 工作不属于此 Skill 的范围。

操作模式

选择一种模式，并在行动前说明。

1. 只读诊断是默认模式。检查仓库状态、配置名称、运行状况响应、公共索引、用户已有的日志和约定测试。不要部署或更改远程状态。
2. 变更候选方案用于准备范围明确的补丁或部署计划。列出确切的文件、服务、行为更改、验证方法和回滚路径。候选方案不代表获得部署许可。
3. 已授权部署需要用户明确要求部署或修改指定环境。在执行前，重新确认已解析的目标、当前版本、备份／回滚方案和验证命令。

如果请求仅表示“检查”“调试”“审计”“接手”或“看看原因”，则保持只读诊断模式。

首先解析参数

绝不要根据示例推断部署坐标。请发现或询问以下值，并确保机密不会出现在聊天和日志中：

参数	含义
REPOSITORY_ROOT	包含目录和 Gateway 的本地仓库
GATEWAY_ROOT	Gateway 服务目录
STATIC_INDEX_URL	公共目录／索引 URL
GATEWAY_BASE_URL	Gateway 的公共 HTTPS 来源
HEALTH_PATH	只读运行状况端点路径
SSH_TARGET	已批准的远程主机别名或用户提供的主机
DEPLOY_COMMAND	仓库自有的部署入口
VERIFY_COMMAND	仓库自有的部署前／部署后检查命令
SECRET_CONFIG	部署工具使用的机密来源；绝不可将其内容加载到模型上下文中

任何远程命令执行前，都必须解决所有占位符。不要打印机密值、私钥、OAuth 客户端机密、管理员令牌、会话签名材料或原始身份提供方标识符。

架构边界

• 静态主机发布公共架构、示例、索引、兼容性元数据和版本通知。
• Gateway 负责创建、查看和更新包，撤回包，管理审核状态和所有权，并提供经过身份验证的 API。
• 对象存储保存已批准的公共包和可选媒体；它不是授权数据库。
• OAuth 为发布／更新／撤回操作建立最小化的所有权身份。它不是玩家跟踪系统。
• 角色卡客户端使用公共数据和经过身份验证的所有者 API，但不得包含服务器凭据。
• 导入的包必须通过架构、兼容性和策略检查，然后才能通过单独且可预览的应用事务完成应用。

更改 API 或客户端调用方前，请阅读 architecture-and-contracts.md。

只读诊断流程

1. 检查当前代码仓库和部署文档，不要更改文件。
2. 查找现有运维脚本和包命令；不要另行创建平行的部署路径。
3. 检查公开健康检查端点、静态索引、包列表和一个包详情响应。
4. 将 Gateway 契约与每个客户端使用方及契约测试进行比对。
5. 检查配置键名称和验证逻辑，不要读取配置值。
6. 检查近期日志中与故障请求相关的有限内容，同时对凭据、Cookie、授权标头、查询参数中的机密和个人数据进行脱敏。
7. 报告故障所在层、证据、最小候选改动、验证方式，以及是否需要部署授权。

不要将进程健康视为 OAuth、存储、审核、包详情或客户端集成正常工作的证明。

变更与部署关卡

对于已授权的变更：

1. 将范围限定为一个契约或运维问题。
2. 记录当前发布标识和回滚机制。
3. 运行仓库提供的静态检查、契约测试和本地冒烟测试。
4. 检查差异，确认没有凭据、部署坐标、破坏性命令或无关变更。
5. 重新确认已解析的环境和明确授权。
6. 使用现有部署入口；不要手动复制密钥或擅自在远程环境中修改文件。
7. 验证健康检查、公开索引、包详情、身份验证状态，以及受影响的所有者/审核流程。
8. 如果必要的部署后检查失败，请停止并使用文档规定的回滚路径，而不是叠加紧急补丁。

请阅读 operations-and-security.md，了解审批、CORS、隐私和回滚关卡。

契约规则

• 公开列表端点仅公开已批准且未撤回的包。
• 详情端点保留验证和安装所需的包负载。
• 创建、更新和撤回操作必须在服务端强制执行所有权验证。
• 更新和审核决定使用修订版本或等效的乐观并发机制；过期写入必须安全失败。
• 客户端不能提交权威的审核、所有权、修订版本或审计字段。
• 身份验证交接值必须短时有效、一次性使用、范围受限，且绝不能通过具有兑换权限的公开 URL 传递。
• 安装、更新和卸载必须是事务性的，且只能操作该包拥有的数据。
• API 形状变更只有在 Gateway、客户端使用方、架构/契约定义和冒烟测试达成一致后才算完成。

隐私最低要求

仅持久化所有权所需的最少身份信息，例如由身份提供方范围限定的带密钥哈希和随机发布者标识符。除非存在单独明确的产品需求和法律依据，否则不要持久化电子邮件、昵称、头像、原始身份提供方 ID、IP 画像或行为画像。

日志应包含操作、包标识符、假名化的发布者标识符、结果、原因代码和时间；不得包含访问令牌、Cookie、授权标头、OAuth 代码、原始身份信息或包机密。

停止条件

遇到以下情况时停止，并返回明确的后续步骤：

• 缺少必要的授权、账户验证、CAPTCHA 或外部同意。
• 若要继续，必须暴露凭据、私钥或机密。
• 无法明确确定目标环境或回滚范围。
• 拟议操作可能删除用户包、存储、审计历史或生产数据，且没有经过验证的恢复路径。
• CORS、OAuth、代理、存储或发布指针的变更会悄然扩大已批准的范围。

参考资料

• architecture-and-contracts.md：通用服务和 API 契约。
• operations-and-security.md：只读检查、授权关卡、机密、CORS、部署和回滚。
• provenance.md：公开衍生数据边界。