Coding Net

SKILL.md

---
name: coding-net
version: 1.3.0
description: 查询和操作 Coding 开放平台（e.coding.net）的迭代、事项（需求/缺陷/任务）、团队成员等数据，包括创建需求和缺陷。当用户涉及 Coding 平台操作时触发，如「查迭代」「查事项」「当前迭代的需求」「Coding 上的 bug」「团队成员列表」「assignee」「新建需求」「创建缺陷」。所有 API 均需环境变量 CODING_TOKEN。
---

# Coding Open API Skill

## 环境配置

| 变量 | 必须 | 说明 |
|------|------|------|
| `CODING_TOKEN` | **是** | Bearer Token，`export CODING_TOKEN=...` |
| `CODING_DEFAULT_PROJECT_NAME` | **是** | 默认项目名，推荐值：`biaopin-swiftagent` |
| `CODING_DEFAULT_ITERATION_CODE` | **是** | 默认迭代 Code，需先查询迭代列表后填写（见下方配置流程） |

## 首次安装：必须完成以下配置

> **每次新会话均需重新 export，或写入 shell 配置文件（~/.zshrc / ~/.bashrc）永久生效。**

**第一步：设置 Token（必须）**
```bash
export CODING_TOKEN=your_token_here
```

**第二步：设置默认项目（推荐 `biaopin-swiftagent`）**
```bash
export CODING_DEFAULT_PROJECT_NAME=biaopin-swiftagent
```

**第三步：查询迭代列表，获取当前迭代 Code（必须完成）**

先运行以下代码查看所有迭代：
```python
import sys; sys.path.insert(0, "path/to/coding-net/scripts")
from iterations import get_iteration_list_code_and_name
for it in get_iteration_list_code_and_name():
    print(it['code'], it['name'])
```
从输出中找到当前正在进行的迭代，记下其 `code`。

**第四步：设置默认迭代（必须）**
```bash
export CODING_DEFAULT_ITERATION_CODE=<上一步看到的 code>
```

**完成后即可零参数查询：**
```python
result = describe_issue_list()   # project_name 和 iteration 均走默认值
```

## 脚本结构

```
scripts/
├── core.py        — HTTP 客户端、Token 解析、CodingAPIError
├── iterations.py  — 迭代 API（依赖 core）
├── issues.py      — 事项 API（依赖 core + iterations）
└── members.py     — 团队成员 API（依赖 core）
```

在 Python 中使用（脚本已处理 sys.path，直接 import 即可）：

```python
import sys
sys.path.insert(0, "path/to/scripts")
from iterations import get_iteration_list_code_and_name
from issues import describe_issue, describe_issue_list, create_issue, describe_defect_types, extract_members_from_issue_list
from members import get_team_members_id_and_name
```

## 公开函数速查

### iterations.py

```python
get_iteration_list_code_and_name(project_name=None, *, token=None) -> [{'code': int, 'name': str}]
```
分页拉取全量迭代列表。返回的 `code` 即 `describe_issue_list(iteration=...)` 所需值。

### issues.py

```python
describe_issue_list(
    project_name=None, *,   # 省略时读 CODING_DEFAULT_PROJECT_NAME
    issue_type="ALL",       # ALL / REQUIREMENT / DEFECT / MISSION
    limit="2000",
    assignee_ids=None,      # [int] — 来自 get_team_members_id_and_name 的 id
    iteration=None,         # int  — 省略时读 CODING_DEFAULT_ITERATION_CODE
    status_types=None,      # None→TODO+PROCESSING; []→不过滤; ['TODO',...]→指定
    base_issue_type=None,   # REQUIREMENT / DEFECT / MISSION
    token=None,
) -> dict  # Response.IssueList 每条含 Code/Name/IssueStatusName/Priority/CreatorName/HandlerName/StartDate/DueDate
```

```python
describe_issue(project_name=None, issue_code=0, *, token=None) -> dict
# 返回 {Name, Description, IssueStatusName, AssigneeName, CreatorName}
```

```python
create_issue(
    project_name=None, *,
    name: str,                  # 标题（必填）
    issue_type="REQUIREMENT",   # REQUIREMENT / DEFECT / MISSION
    description="",
    priority=2,                 # 0=最高 1=高 2=中 3=低 4=最低
    assignee_id=None,           # int — 成员 ID（见 members.py 或从事项列表反查）
    iteration=None,             # int — 省略时读 CODING_DEFAULT_ITERATION_CODE
    start_date=None,            # str 'YYYY-MM-DD' — 部分项目必填
    due_date=None,              # str 'YYYY-MM-DD' — 部分项目必填
    label_ids=None,             # [int] — 部分项目必填，缺失报 issue_project_label_required
    working_hours=None,         # float — 工时（小时），部分项目必填
    issue_type_id=None,         # int — 事项大类 ID（非缺陷子类型）
    defect_type_id=None,        # int — 缺陷子类型 ID，来自 describe_defect_types
    token=None,
) -> dict  # {Code, Name, IssueStatusName, AssigneeName, CreatorName}
```

```python
describe_defect_types(project_name=None, *, token=None) -> [{'id': int, 'name': str}]
# 返回缺陷子类型列表，对应 create_issue(defect_type_id=...)
```

```python
extract_members_from_issue_list(issues_result: dict) -> [{'id': int, 'name': str}]
# 从 describe_issue_list 返回值中提取去重成员，用于 DescribeTeamMembers 无权限时的替代
```

### members.py

```python
get_team_members_id_and_name(*, token=None) -> [{'id': int, 'name': str}]
```
分页拉取全量团队成员。`id` 可用于 `describe_issue_list(assignee_ids=[...])` 过滤。
**注意**：部分 token 无 `DescribeTeamMembers` 权限，会报错，此时改用 `extract_members_from_issue_list`。

## 常见工作流

**查当前迭代所有未完成事项：**
```python
iterations = get_iteration_list_code_and_name(project_name)
# 选择目标迭代 code（通常取最新一个）
result = describe_issue_list(project_name, iteration=iterations[-1]['code'])
issues = result['Response']['IssueList']
```

**按成员过滤事项（token 有 DescribeTeamMembers 权限时）：**
```python
members = get_team_members_id_and_name()
uid = next(m['id'] for m in members if m['name'] == '张三')
result = describe_issue_list(project_name, iteration=code, assignee_ids=[uid])
```

**按成员过滤事项（token 无 DescribeTeamMembers 权限时，从事项列表反查）：**
```python
result = describe_issue_list(project_name, iteration=code, status_types=[])
members = extract_members_from_issue_list(result)
uid = next(m['id'] for m in members if m['name'] == '张三')
result = describe_issue_list(project_name, iteration=code, assignee_ids=[uid])
```

**查单条事项详情（含描述）：**
```python
detail = describe_issue(project_name, issue_code=12345)
```

**创建需求（最简调用，迭代走默认环境变量）：**
```python
issue = create_issue(project_name, name="支持 XX 功能")
print(issue['Code'], issue['Name'])
```

**创建缺陷（含项目级必填字段）：**
```python
# 1. 查迭代
iterations = get_iteration_list_code_and_name(project_name)
# 2. 从事项列表反查成员 ID（无 DescribeTeamMembers 权限时）
result = describe_issue_list(project_name, iteration=iterations[-1]['code'], status_types=[])
members = extract_members_from_issue_list(result)
uid = next(m['id'] for m in members if m['name'] == '张三')
# 3. 查缺陷子类型
defect_types = describe_defect_types(project_name)
# [{'id': 36666669, 'name': '功能缺陷'}, ...]
# 4. 创建（start_date/due_date/label_ids/working_hours 按项目配置决定是否必填）
issue = create_issue(
    project_name,
    name="登录页面报 500 错误",
    issue_type="DEFECT",
    priority=1,
    assignee_id=uid,
    iteration=iterations[-1]['code'],
    start_date="2026-06-17",
    due_date="2026-06-20",
    label_ids=[123],          # 项目标签 ID
    working_hours=2.0,
    defect_type_id=defect_types[0]['id'],
)
```

**创建需求（最简调用）：**
```python
issue = create_issue(project_name, name="支持 XX 功能", start_date="2026-06-17", due_date="2026-06-30")
```