From 5cecb7370582306e3aa329e1f6115f635cf739a6 Mon Sep 17 00:00:00 2001 From: guanlili Date: Thu, 12 Nov 2026 17:39:55 +0800 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20=E5=9D=91=E9=80=9F=E6=9F=A5?= =?UTF-8?q?=E6=96=B0=E5=A2=9E#11=E2=80=94=E2=80=94=E6=96=B0=E7=89=88=20gh?= =?UTF-8?q?=20item-edit=20=E6=8C=89=E5=90=8D=E7=BC=96=E8=BE=91=E9=A1=BB=20?= =?UTF-8?q?--url=20=E5=AF=BB=E5=9D=80=EF=BC=88--id=20=E7=A6=81=E9=85=8D=20?= =?UTF-8?q?--field=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 实测背景:2026-11-12 jilin-flex-platform 飞书台账回填(8 条 issue 入板补字段), gh 2.103.3 下 `gh project item-edit --id --field 名 --value 值` 报 `--field cannot be used with --id`。按名编辑须改用 `item-edit <编号> --owner @me --url --field 名 --value 值`; `--id` 只配 `--field-id`+`--project-id`(机器模式)。坑2 的 --value 通吃结论不变。 同步:坑2 加交叉引用;README/README.zh-CN 坑数 10→11;AGENTS.md 红线5 计数 9→11(坑#10 加入时漏更)。 --- AGENTS.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- references/pitfalls.md | 5 +++-- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 34f927f..9e987b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ 2. 记账以 **issue 为唯一真相源**,Project 字段只是视图 3. 完成可交付单元的会话**不记账不结束**(硬性纪律) 4. 读 Project 数据一律 `gh api graphql`(`gh project item-list` 会损坏中文字段名) -5. 逐条命令见 SKILL.md「坑速查」,共 9 条实测坑 +5. 逐条命令见 SKILL.md「坑速查」,共 11 条实测坑 ## 他人接入(一句话协议) diff --git a/README.md b/README.md index 6d287c2..e7840ba 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Requires `gh` CLI (project scopes), bash 3.2+, python3+openpyxl for exports. Wor ## Documentation - [SKILL.md](SKILL.md) — agent entry point (decision tree + per-scenario commands) -- [references/pitfalls.md](references/pitfalls.md) — 10 hard-won gh/GitHub API pitfalls +- [references/pitfalls.md](references/pitfalls.md) — 11 hard-won gh/GitHub API pitfalls - [references/methodology.md](references/methodology.md) — principles, data model, migration patterns - [README.zh-CN.md](README.zh-CN.md) — full documentation in Chinese diff --git a/README.zh-CN.md b/README.zh-CN.md index 92d318d..9c494e4 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -70,7 +70,7 @@ bash ~/.agents/skills/devledger/scripts/new-project.sh | `scripts/fill-field.py` | 批量字段填充(读回验证内置,幂等重跑) | | `scripts/reconcile.py` | 字段对账(读回→diff→补写循环;`--from-labels` 重建) | | `scripts/install.sh` | 幂等安装自检 | -| `references/pitfalls.md` | 10 条实测坑(执行 API 前必读) | +| `references/pitfalls.md` | 11 条实测坑(执行 API 前必读) | | `references/methodology.md` | 方法论:原则/数据模型/原生取舍/历史迁移 | | `references/data/*.json` | 各项目账本真值(reconcile 用) | diff --git a/references/pitfalls.md b/references/pitfalls.md index 67fd615..950a4d6 100644 --- a/references/pitfalls.md +++ b/references/pitfalls.md @@ -1,9 +1,9 @@ -# 坑速查(10 条,全部实测 2026-11) +# 坑速查(11 条,全部实测 2026-11) 执行 gh / GitHub API 操作前必读;详细背景见 methodology.md。 1. **编码**:`gh project item-list` 损坏中文自定义字段名首字节(值正常)→ 读数据一律 `gh api graphql` 直查 ProjectV2 -2. **设值**:`gh project item-edit` 用 `--field 名 --value 值`(无 --single-select-option 旗标) +2. **设值**:`gh project item-edit` 用 `--field 名 --value 值`(无 --single-select-option 旗标;寻址方式见坑 11) 3. **限流两层**:主 5000 点/小时(等 `rateLimit.resetAt`);次级限流=连续写触发(2026-11-09 energy-platform 18 条回填实测细节): - 触发阈值约 **40–70 次连续写**;冷却期 GraphQL **读写全封**——`gh issue list` 等底层走 GraphQL 的命令也挂,报错同为 "rate limit exceeded" - 判别法:先查 `gh api rate_limit`,主限流余量充足却报限流 = 次级(REST 端点本身不受次级限流影响,冷却期可用 `gh api repos/...` 读数据) @@ -16,3 +16,4 @@ 8. **bash 3.2(macOS)**:无关联数组;`$VAR` 一律写 `${VAR}` 且不紧跟中文字符 9. **代理**:终端访问 github.com 网页域(OAuth/push)超时 → 配置 `HTTPS_PROXY` 指向本地代理;api.github.com 通常可直连 10. **GraphQL 手写单行查询会丢右括号**:报错 `Expected NAME, actual: (none)` 且列号=查询末尾 = 少一个 `}`(不是服务端故障)→ 一律多行书写并数平括号。(实测更正:`--value` 通吃所有字段类型含 TEXT,`--text`/`--number`/`--date` 是别名——以读回验证为准,勿轻信文档包括本文件) +11. **item-edit 寻址**:新版 gh 禁止 `--id` 与 `--field`(按名)混用,报 `` `--field` cannot be used with `--id` `` → 按名编辑须 `gh project item-edit <编号> --owner @me --url --field 名 --value 值`;`--id` 只配 `--field-id` + `--project-id`(机器模式)。坑 2 的 `--value` 通吃结论在 --url 模式下继续成立(2026-11-12 jilin-flex-platform 8 条回填实测,gh 2.7x) From 0e1e60ee6ba3d6789e9e1d7d314ed5db6c4ab5f8 Mon Sep 17 00:00:00 2001 From: guanlili Date: Thu, 12 Nov 2026 20:26:59 +0800 Subject: [PATCH 2/3] docs: verify gh version and remove duplicated pitfall counts --- AGENTS.md | 2 +- README.md | 2 +- README.zh-CN.md | 2 +- SKILL.md | 2 +- references/pitfalls.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9e987b1..105fe05 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ 2. 记账以 **issue 为唯一真相源**,Project 字段只是视图 3. 完成可交付单元的会话**不记账不结束**(硬性纪律) 4. 读 Project 数据一律 `gh api graphql`(`gh project item-list` 会损坏中文字段名) -5. 逐条命令见 SKILL.md「坑速查」,共 11 条实测坑 +5. 逐条命令见 SKILL.md 链接的实测避坑指南 ## 他人接入(一句话协议) diff --git a/README.md b/README.md index e7840ba..702fd8f 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ Requires `gh` CLI (project scopes), bash 3.2+, python3+openpyxl for exports. Wor ## Documentation - [SKILL.md](SKILL.md) — agent entry point (decision tree + per-scenario commands) -- [references/pitfalls.md](references/pitfalls.md) — 11 hard-won gh/GitHub API pitfalls +- [references/pitfalls.md](references/pitfalls.md) — gh/GitHub API pitfalls from real usage - [references/methodology.md](references/methodology.md) — principles, data model, migration patterns - [README.zh-CN.md](README.zh-CN.md) — full documentation in Chinese diff --git a/README.zh-CN.md b/README.zh-CN.md index 9c494e4..97363db 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -70,7 +70,7 @@ bash ~/.agents/skills/devledger/scripts/new-project.sh | `scripts/fill-field.py` | 批量字段填充(读回验证内置,幂等重跑) | | `scripts/reconcile.py` | 字段对账(读回→diff→补写循环;`--from-labels` 重建) | | `scripts/install.sh` | 幂等安装自检 | -| `references/pitfalls.md` | 11 条实测坑(执行 API 前必读) | +| `references/pitfalls.md` | 实测避坑指南(执行 API 前必读) | | `references/methodology.md` | 方法论:原则/数据模型/原生取舍/历史迁移 | | `references/data/*.json` | 各项目账本真值(reconcile 用) | diff --git a/SKILL.md b/SKILL.md index 373d516..c23977c 100644 --- a/SKILL.md +++ b/SKILL.md @@ -72,7 +72,7 @@ python3 scripts/fill-field.py --project --field <字段> --value <值> [--wh ## 执行前必读 -- **[references/pitfalls.md](references/pitfalls.md)——10 条实测坑**(编码/限流/字段 API 行为/bash 兼容),执行任何 gh API 操作前先读 +- **[references/pitfalls.md](references/pitfalls.md)——实测避坑指南**(编码/限流/字段 API 行为/bash 兼容),执行任何 gh API 操作前先读 - 深度背景:[references/methodology.md](references/methodology.md)(原则/数据模型/原生取舍/历史迁移模式) - 各项目账本真值:本地 `~/devledger-private/data/*.json`(含客户信息不入库;仓库内 example-ledger.json 为格式示例) diff --git a/references/pitfalls.md b/references/pitfalls.md index 950a4d6..16e15bd 100644 --- a/references/pitfalls.md +++ b/references/pitfalls.md @@ -16,4 +16,4 @@ 8. **bash 3.2(macOS)**:无关联数组;`$VAR` 一律写 `${VAR}` 且不紧跟中文字符 9. **代理**:终端访问 github.com 网页域(OAuth/push)超时 → 配置 `HTTPS_PROXY` 指向本地代理;api.github.com 通常可直连 10. **GraphQL 手写单行查询会丢右括号**:报错 `Expected NAME, actual: (none)` 且列号=查询末尾 = 少一个 `}`(不是服务端故障)→ 一律多行书写并数平括号。(实测更正:`--value` 通吃所有字段类型含 TEXT,`--text`/`--number`/`--date` 是别名——以读回验证为准,勿轻信文档包括本文件) -11. **item-edit 寻址**:新版 gh 禁止 `--id` 与 `--field`(按名)混用,报 `` `--field` cannot be used with `--id` `` → 按名编辑须 `gh project item-edit <编号> --owner @me --url --field 名 --value 值`;`--id` 只配 `--field-id` + `--project-id`(机器模式)。坑 2 的 `--value` 通吃结论在 --url 模式下继续成立(2026-11-12 jilin-flex-platform 8 条回填实测,gh 2.7x) +11. **item-edit 寻址**:新版 gh 禁止 `--id` 与 `--field`(按名)混用,报 `` `--field` cannot be used with `--id` `` → 按名编辑须 `gh project item-edit <编号> --owner @me --url --field 名 --value 值`;`--id` 只配 `--field-id` + `--project-id`(机器模式)。坑 2 的 `--value` 通吃结论在 --url 模式下继续成立(2026-11-12 jilin-flex-platform 8 条回填实测,gh 2.103.3) From c7cca9510fc84ff8877f9f882b7dbde237d18436 Mon Sep 17 00:00:00 2001 From: guanlili Date: Thu, 12 Nov 2026 20:27:42 +0800 Subject: [PATCH 3/3] test: verify pitfall guide link instead of hard-coded count --- tests/test_rollout_readiness.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_rollout_readiness.py b/tests/test_rollout_readiness.py index a81f92e..0f73cd0 100644 --- a/tests/test_rollout_readiness.py +++ b/tests/test_rollout_readiness.py @@ -13,10 +13,10 @@ class TestRolloutReadiness(unittest.TestCase): def test_skill_doc_six_field_era(self): - """SKILL.md 不得残留 5 字段/8 列/9 坑的旧口径(v1.2.1 起为 6 字段 9 列 10 坑)""" + """SKILL.md 应说明 6 字段、9 列并链接避坑指南""" self.assertNotIn("5 字段", SKILL) self.assertNotIn("View 8 列", SKILL) - self.assertIn("10 条实测坑", SKILL) + self.assertIn("](references/pitfalls.md)", SKILL) def test_templates_use_standard_install_path(self): """注入模板必须引用标准安装路径 ~/.agents/skills/devledger(他人机器无 ~/devledger)"""