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
3 changes: 2 additions & 1 deletion SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,8 @@ for fv in "类型:需求" "来源:甲方" "需求人:张三" "工时(h):8" "开
## 场景 C:查看与导出(休眠扩展)

```bash
python3 scripts/reconcile.py --project <N> --repo <owner/repo> --dry-run # C1 进度+体检
python3 scripts/reconcile.py --project <N> --repo <owner/repo> --data <账本.json> --dry-run # C1 对账体检
# 启用交付轮次的仓库可用 --from-labels 替代 --data,仅核对轮次字段
python3 scripts/export-timesheet.py --project <N> [--round 轮次] [--customer] [-o xlsx] # C2 验收表
python3 scripts/fill-field.py --project <N> --field <字段> --value <值> [--where 来源=甲方] [--dry-run] # C3 批量填字段(读回验证内置,幂等重跑)
```
Expand Down
4 changes: 2 additions & 2 deletions references/methodology.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
**对账真值文件(`reconcile.py --data`)格式**:

```json
[{"title": "issue 标题", "fields": {"类型": "需求", "来源": "内部", "工时(h)": "2", "开始": "2026-11-08", "结束": "2026-11-08"}}]
[{"number": 123, "title": "issue 标题", "fields": {"类型": "需求", "来源": "内部", "工时(h)": "2", "开始": "2026-11-08", "结束": "2026-11-08"}}]
```

- 数字字段写 `2` / `2.0` / `"2"` 等价,引擎归一后比较——写法不同不会被判成数据漂移
Expand All @@ -60,7 +60,7 @@
4. 工时统一 AI 评估口径:**人类等价工作量**(熟练工程师完成同样工作所需时长,非 AI 墙钟——2026-11-08 定案,与历史账/飞书记录同口径,AI 压缩的是墙钟不是交付价值),**实时与回填一律从宽、宁多勿漏**(回填仅见 git 结果,过程中的诊断/实测/死胡同不可见,只能量级基准上界),依据写进 issue 工时段;开发期 commit message 末尾带 issue 号 `(#N)`
5. 该仓库 README「交付轮次工时汇总」追加本轮汇总表
6. 新轮次首条 issue 前追加轮次选项并立即 reconcile 重建(见坑 6);轮次以 `轮次:<名>` label 镜像在 issue 上
7. AI 自动职责(用户无输入):记账完成后顺手 `reconcile.py --dry-run` 自检有漂移即修;**交付轮次收官时自动导出该轮验收表**并告知位置
7. AI 自动职责(用户无输入):记账完成后顺手 `reconcile.py --data <账本.json> --dry-run` 自检有漂移即修;**交付轮次收官时自动导出该轮验收表**并告知位置

## 五、验收导出

Expand Down
7 changes: 5 additions & 2 deletions scripts/_common.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,12 @@ def run(args, retries=5, timeout=180, pace=0):
return 1, "", last


def gql(query, retries=5):
def gql(query, retries=5, *, cursor=None):
"""GraphQL 查询 → 解析后的 data;失败返回 None(内部自动退避)。"""
rc, out, _ = run(["gh", "api", "graphql", "-f", "query=" + query], retries=retries)
args = ["gh", "api", "graphql", "-f", "query=" + query]
if cursor is not None:
args += ["-f", f"cursor={cursor}"]
rc, out, _ = run(args, retries=retries)
if rc != 0:
return None
try:
Expand Down
46 changes: 28 additions & 18 deletions scripts/fill-field.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,8 @@
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
from _common import gql, norm, run

ITEMS_Q = '''query { viewer { projectV2(number: %d) { items(first: 100) {
ITEMS_Q = '''query($cursor: String) { viewer { projectV2(number: %d) { items(first: 100, after: $cursor) {
pageInfo { hasNextPage endCursor }
nodes {
content { ... on Issue { number title url } }
fieldValues(first: 20) { nodes {
Expand All @@ -31,21 +32,26 @@


def read_items(project):
data = gql(ITEMS_Q % project)
if not data:
sys.exit("读取 Project 失败(限流?稍后重跑)")
items = []
for n in data["viewer"]["projectV2"]["items"]["nodes"]:
c = n.get("content")
if not c:
continue
vals = {}
for f in n["fieldValues"]["nodes"]:
fn = (f.get("field") or {}).get("name")
if fn and fn not in vals:
vals[fn] = f.get("text") if "text" in f else (f.get("name") or f.get("number") or f.get("date"))
items.append({"title": c["title"], "url": c["url"], "vals": vals})
return items
items, cursor = [], None
while True:
data = gql(ITEMS_Q % project, cursor=cursor)
project_data = (data or {}).get("viewer", {}).get("projectV2")
if not project_data:
sys.exit("读取 Project 失败,请检查项目编号和访问权限")
page = project_data["items"]
for node in page["nodes"]:
content = node.get("content") or {}
if not content.get("url"):
continue
vals = {}
for value in node["fieldValues"]["nodes"]:
field = (value.get("field") or {}).get("name")
if field and field not in vals:
vals[field] = value.get("text", value.get("name", value.get("number", value.get("date"))))
items.append({"title": content["title"], "url": content["url"], "vals": vals})
if not page["pageInfo"]["hasNextPage"]:
return items
cursor = page["pageInfo"]["endCursor"]


def plan_changes(items, field, value, where=None):
Expand All @@ -71,7 +77,10 @@ def main():
ap.add_argument("--dry-run", action="store_true")
args = ap.parse_args()

for sweep in range(1, args.sweeps + 1):
if args.sweeps < 1:
ap.error("--sweeps 必须大于 0")

for sweep in range(1, args.sweeps + 2):
todo = plan_changes(read_items(args.project), args.field, args.value, args.where)
print(f"[sweep{sweep}] 需修改 {len(todo)} 条", flush=True)
if not todo:
Expand All @@ -81,13 +90,14 @@ def main():
for it in todo[:15]:
print(f" DRIFT {it['title'][:36]} | 现={it['vals'].get(args.field)!r} → {args.value!r}")
return
if sweep > args.sweeps:
sys.exit(f"FILL INCOMPLETE:读回仍有 {len(todo)} 条差异")
for it in todo:
rc, _, err = run(["gh", "project", "item-edit", str(args.project), "--owner", "@me",
"--url", it["url"], "--field", args.field, "--value", args.value], pace=1.5)
if rc != 0:
print(f" FAIL {it['title'][:30]}: {err[:60]}", flush=True)
time.sleep(10)
print("FILL DONE(达最大轮数,如仍有差异请重跑——幂等只补差异)")


if __name__ == "__main__":
Expand Down
69 changes: 35 additions & 34 deletions scripts/new-project.sh
Original file line number Diff line number Diff line change
Expand Up @@ -184,25 +184,35 @@ def api(path, method="GET", fields=None):
import time as _t
for attempt in range(4):
r = subprocess.run(cmd, capture_output=True, text=True)
if r.returncode == 0 or "404" in r.stderr or "NOT_FOUND" in r.stderr:
return r.returncode, r.stdout, r.stderr # 成功或确定不存在,直接返回
if r.returncode == 0 or any(f"HTTP {status}" in r.stderr for status in (404, 409, 422)):
return r.returncode, r.stdout, r.stderr
_t.sleep(10 * (attempt + 1)) # 网络抖动重试
return r.returncode, r.stdout, r.stderr

def put_file(path_in_repo, content, message):
def read_file(path_in_repo):
enc = urllib.parse.quote(path_in_repo)
code, out, err = api(f"repos/{repo}/contents/{enc}")
fields = {"message": message, "content": base64.b64encode(content.encode()).decode()}
if code == 0:
fields["sha"] = json.loads(out)["sha"]
if content.strip() == base64.b64decode(json.loads(out)["content"]).decode("utf-8", "ignore").strip():
print(f" 已存在且内容一致,跳过: {path_in_repo}")
return
code, out, err = api(f"repos/{repo}/contents/{enc}", "PUT", fields)
data = json.loads(out)
return base64.b64decode(data["content"]).decode("utf-8"), data["sha"]
if "HTTP 404" in err:
return "", None
raise SystemExit(f"读取失败 {path_in_repo}: {err.strip()}")


def put_file(path_in_repo, content, message, old, sha):
if sha and content.strip() == old.strip():
print(f" 已存在且内容一致,跳过: {path_in_repo}")
return
enc = urllib.parse.quote(path_in_repo)
fields = {"message": message, "content": base64.b64encode(content.encode()).decode()}
if sha:
fields["sha"] = sha
code, _, err = api(f"repos/{repo}/contents/{enc}", "PUT", fields)
if code != 0:
print(f" WARN 写入失败 {path_in_repo}: {err.strip()[:200]}")
else:
print(f" 已写入: {path_in_repo}")
raise SystemExit(f"写入失败 {path_in_repo}: {err.strip()}")
print(f" 已写入: {path_in_repo}")


# 小节幂等合并:标记已注入→替换到下一顶级标题(保留其后内容);未注入→追加;返回 None=无需写
def merge_section(old, sec, marker):
Expand All @@ -218,33 +228,24 @@ def merge_section(old, sec, marker):
base = old[:idx].rstrip() if idx >= 0 else old.rstrip()
return base + ("\n\n" if base else "") + sec + ("\n" + tail if tail else "\n")

# CLAUDE.md(幂等标记=小节标题;v1.2.1 起模板正文不含 URL,勿用 url 判断——否则重跑重复追加)
# 用同一次读取的内容和 SHA 合并,避免覆盖并发编辑。
marker = "## 项目管理(devledger"
code, out, _ = api(f"repos/{repo}/contents/CLAUDE.md")
if code == 0:
old = base64.b64decode(json.loads(out)["content"]).decode("utf-8", "ignore")
merged = merge_section(old, section, marker)
if merged is None:
print(" CLAUDE.md 小节已是最新,跳过")
else:
put_file("CLAUDE.md", merged, f"chore: 项目管理规范化——CLAUDE.md 记账规范注入/升级(Project #{num})")
else:
put_file("CLAUDE.md", section + "\n", f"chore: 新建 CLAUDE.md——项目管理记账规范(Project #{num})")

# AGENTS.md(Codex 等读 AGENTS.md 的工具入口;同款幂等合并,文件不存在则带标题新建)
amarker = "## 项目管理记账(devledger"
code, out, _ = api(f"repos/{repo}/contents/AGENTS.md")
if code == 0:
old = base64.b64decode(json.loads(out)["content"]).decode("utf-8", "ignore")
merged = merge_section(old, agents_tpl, amarker)
for path, template, section_marker in (
("CLAUDE.md", section, marker),
("AGENTS.md", agents_tpl, amarker),
):
old, sha = read_file(path)
base = "# AGENTS.md\n" if path == "AGENTS.md" and sha is None else old
merged = merge_section(base, template, section_marker)
if merged is None:
print(" AGENTS.md 小节已是最新,跳过")
print(f" {path} 小节已是最新,跳过")
else:
put_file("AGENTS.md", merged, f"chore: AGENTS.md 记账纪律注入/升级(Project #{num})")
else:
put_file("AGENTS.md", "# AGENTS.md\n\n" + agents_tpl + "\n", f"chore: 新建 AGENTS.md——跨 AI 工具记账纪律(Project #{num})")
put_file(path, merged, f"chore: {path} 记账规范(Project #{num})", old, sha)

put_file(".github/ISSUE_TEMPLATE/需求.md", issue_tpl, f"chore: 项目管理 issue 模板(Project #{num})")
path = ".github/ISSUE_TEMPLATE/需求.md"
old, sha = read_file(path)
put_file(path, issue_tpl, f"chore: 项目管理 issue 模板(Project #{num})", old, sha)
PYEOF
fi

Expand Down
Loading
Loading