diff --git a/AGENTS.md b/AGENTS.md index 34f927f..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「坑速查」,共 9 条实测坑 +5. 逐条命令见 SKILL.md 链接的实测避坑指南 ## 他人接入(一句话协议) diff --git a/README.md b/README.md index 6d287c2..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) — 10 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 92d318d..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` | 10 条实测坑(执行 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 67fd615..16e15bd 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.103.3) 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)"""