Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
2. 记账以 **issue 为唯一真相源**,Project 字段只是视图
3. 完成可交付单元的会话**不记账不结束**(硬性纪律)
4. 读 Project 数据一律 `gh api graphql`(`gh project item-list` 会损坏中文字段名)
5. 逐条命令见 SKILL.md「坑速查」,共 9 条实测坑
5. 逐条命令见 SKILL.md 链接的实测避坑指南

## 他人接入(一句话协议)

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 1 addition & 1 deletion README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ bash ~/.agents/skills/devledger/scripts/new-project.sh <owner/repo>
| `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 用) |

Expand Down
2 changes: 1 addition & 1 deletion SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ python3 scripts/fill-field.py --project <N> --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 为格式示例)

Expand Down
5 changes: 3 additions & 2 deletions references/pitfalls.md
Original file line number Diff line number Diff line change
@@ -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/...` 读数据)
Expand All @@ -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 <issue链接> --field 名 --value 值`;`--id` 只配 `--field-id` + `--project-id`(机器模式)。坑 2 的 `--value` 通吃结论在 --url 模式下继续成立(2026-11-12 jilin-flex-platform 8 条回填实测,gh 2.103.3)
4 changes: 2 additions & 2 deletions tests/test_rollout_readiness.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)"""
Expand Down
Loading