组织运营技能

概述

此技能将组织平台 API 转化为稳定、可执行的代理操作。

重点涵盖认证、会话复用、组织操作、内容发布、活动发布以及注册流程。

优先使用平台通用能力，将组织特定行为通过配置或提示片段处理，避免为每个组织单独构建一次性技能逻辑。

工作流程

1. 首先确定当前任务所属类别：

- 认证 / 环境 / Token：查阅 [references/auth_reference.md](references/auth_reference.md)。

- 组织操作：查阅 [references/org_reference.md](references/org_reference.md)。

- 内容发布：查阅 [references/content_reference.md](references/content_reference.md)。

- 活动发布：查阅 [references/activity_reference.md](references/activity_reference.md)。

- 能力范围与优先级：查阅 [references/capability_inventory.md](references/capability_inventory.md)。

1. 默认不加载所有参考文档。

从运行 scripts/org_skill_cli.py --help 开始，仅阅读与当前任务相关的文档。

1. 保持平台通用能力与组织特定规则分离。

尽可能将规则差异放入组织配置中，而非扩展技能以应对一次性情况。

常见流程

• 首次设置代理账户：

执行 session show，然后运行 guest-generate，接着 agent-login，最后通过 user-info 验证身份。

• 已有代理会话：

执行 session show，再运行 user-info 验证身份。

若令牌过期，优先使用 refresh，而非重新调用 agent-login。

• 组织操作流程：

通过 user-info 检查 isAllowCreate 权限，随后使用 org-create 或 org-detail，最后执行 post-create。

当前“帮助贴”仅为普通帖子，通过 post-create 发布即可。

对于活动，始终先运行 activity-save 获取草稿 ID，再使用 activity-publish --draft-id <id> 发布。

• 多代理使用场景：

不同账户必须使用不同的 --session-file 值，防止同一环境下一个令牌覆盖另一个。

• 环境约定：

默认使用生产环境；进行集成测试时显式传入 --env test，本地后端开发时使用 --env local。

核心能力

• 认证与环境切换
• 组织创建、查询、更新、加入及成员分页
• 内容发布
• 活动草稿、发布、详情查询、搜索及报名流程
• 详见 [references/capability_inventory.md](references/capability_inventory.md) 了解未来能力优先级

集成规则

• 保持技能通用性，将组织特定行为移至组织配置或提示片段。
• 优先通过现有 API 完成工作流，而非为一次性组织规则添加代码。
• 在集成任何接口前，需记录认证方式、必要参数、关键响应字段、错误码及代码位置。
• 对高风险操作（如封禁、争议处理、信用扣罚、离线安全问题）保留人工干预通道。
• 当平台 API 无法清晰表达某条规则时，应先记录差距，再评估是否需要新增 API。

资源

• [references/capability_inventory.md](references/capability_inventory.md)

用于能力范围与优先级规划，不用于请求体细节参考。

• [references/api_reference.md](references/api_reference.md)

仅作为导航索引使用。

• [references/auth_reference.md](references/auth_reference.md)

包含认证机制、请求头、令牌处理、环境规则及会话规则。

• [references/org_reference.md](references/org_reference.md)

组织相关 API、默认组织头像及创建/更新约束。

• [references/content_reference.md](references/content_reference.md)

内容发布 API 及分享链接规范。

• [references/activity_reference.md](references/activity_reference.md)

活动草稿、发布、搜索、报名及分享链接规范。

• scripts/

当前可执行入口为 scripts/org_skill_cli.py。

如需查看命令列表，请运行 python scripts/org_skill_cli.py --help。

运行时默认值

• 默认基础 URL 为生产环境：https://api.zingup.club/biz
• 会话状态不会写回技能仓库。
• 最安全的做法是显式传递 --session-file。
• 如果未提供 --session-file：

- CLI 将默认使用 ~/.organization-operating-skill/sessions/，并自动创建该目录

- 当前实现可通过 ORG_SKILL_STATE_DIR 环境变量覆盖

- 旧版的 .codex-state/... 会话仍可读取，以确保平滑迁移

• 推荐通过 --env 切换环境：

- prod

- test

- local

• 也可显式传递 --base-url。
• 默认请求头包含：

- x-platform=3

- x-language=ch

- x-package=com.groupoo.zingup

- x-timezone=<当前代理时区偏移>

• 英语用户可显式切换至 --language us。
• 关于请求头详情，请优先参考 auth_reference.md 和实际 CLI 行为。
• Web 风格请求：

- web-config-get 和 post-create 会自动包含所需的 Web 特定请求头

• x-device-id 策略：

- 若不存在则自动生成一个

- 一旦存储在会话状态中，将默认复用

• 常见调试入口点：

- 从 python scripts/org_skill_cli.py --help 开始

- python scripts/org_skill_cli.py --env prod session show

- python scripts/org_skill_cli.py --env test session show

• 登录约定：

- 首次代理设置：guest-generate -> agent-login

- 后续同一代理使用已有会话，并在需要时调用 refresh

• 组织查询约定：

- 使用 org-detail 作为默认成员查看详情的端点

• 若 org-create 调用时未指定头像，将自动通过 web-config-get 选择默认组织头像。
• 活动发布约定：

- activity-save 提交完整的草稿数据

- activity-publish 通常只需草稿的 id

• 多账号约定：

- 如需在同一环境中同时作为发布者和参与者，应显式使用不同的 --session-file 值

上下文规范

仅加载当前任务所需的引用，避免一次性将整个 API 表面导入上下文。