PingCode 项目与工作项

入口为本 skill 的 scripts/pingcode.py：python3 <skill路径>/scripts/pingcode.py <子命令>。 使用类型化命令和生成端点表，不凭记忆拼 API 路径。当前端点表为官方 REST API V2 （2026-10-14 快照）；V1 路径不在表内。首次配置或授权失败时读 auth.md。

操作原则

• 只执行用户请求的范围。编号先解析成真实 ID；名字解析有歧义时列候选，请用户指定，不能取首项。
• 更新或删除前核对目标及当前字段。类型化 update/set-state/delete 命令已读取目标， 不必为了流程固定再查一遍；需要向用户消除歧义时才单独 show。
• 用户已明确授权且参数齐全时直接执行。复杂多字段或批量操作可用 --dry-run 检查计划； dry-run 仍允许为解析 ID 发起只读请求。删除、树形创建和批量补日期要求 --yes， 这是 CLI 执行开关，不要求重复获取已有授权。
• 评论会对外发送信息，仅在用户明确要求评论时执行；上传附件也须属于请求范围。
• 拆分或录入需求时，史诗、特性、用户故事、任务都要有可执行描述；用户提供截图时， 创建后上传附件并在描述里回链，见 workitem-authoring.md。
• 创建/计划默认从 --sprint、带日期的 --parent 或项目日期继承起止时间；都没有时会在 stderr 提示。缺失日期用 workitem fill-dates 预览后加 --yes 回填。
• 负责人尽量明确：--assignee 姓名 或 --assignee @me；确认先不分配就用 --unassigned（--assignee none 同义）。不写会按未分配处理并提示，不要自己猜人。
• 写操作失败或超时后先检查是否已生效，再决定重试，避免重复创建。批量/树形操作报告已完成部分， 不宣称自动回滚或可直接整棵重跑。
• 批量写操作（bulk-update）退出码 0 不等于逐条成功：按输出里的「已更新/失败」条数核对。 迭代字段按类型可用（默认 scrum 只有用户故事能挂），bulk 挂迭代不可用； 大批量迁移、排期与逐日先后顺序的做法见 batch-migration.md。
• 凭据与令牌不回显；状态只用 auth status / config show，不要读取或粘贴凭据文件内容。
• 工作项不缓存；字典默认缓存 6 小时。目标刚改名、新建或状态配置变化时用 --no-cache。

常用入口

“未完成”按 state.type 排除 completed 和 closed，不能按中文状态名猜。 状态表只约束可选 ID，具体状态流转仍由服务端校验；企业令牌不能识别 @me。

按需查阅

• commands.md：参数、搜索语法、树形计划与批量操作。
• workitem-authoring.md：需求拆分、描述模板和截图附件流程。
• batch-migration.md：大批量建树/迁移、迭代排期、并行提速与校验闭环（实战沉淀）。
• fields.md：字段映射、状态、编号解析和分页。
• auth.md：配置路径、两种令牌与错误处理。
• api.md：端点表、参数来源、维护和通用 API。
• README.md：本地运行与测试。

通用 api 用于范围内未封装的接口；表中存在端点不代表获得了执行权限。 --force 只跳过端点存在性校验，不能替代官方契约或扩大到成员、权限、部门、DevOps 管理。 当前随附端点表没有项目删除接口；不要把“删除项目”替换成改状态或删除工作项。